feat(cli): schedule notebooks in Deepnote Cloud - #437

No actionable comments were generated in the recent review. 🎉

sequenceDiagram
  participant CLI
  participant scheduleInCloud
  participant DeepnoteCloud
  CLI->>scheduleInCloud: local file, cron, timezone
  scheduleInCloud->>DeepnoteCloud: resolve or create notebook
  scheduleInCloud->>DeepnoteCloud: upsert recurring schedule
  DeepnoteCloud-->>scheduleInCloud: schedule result
  scheduleInCloud-->>CLI: formatted result

_{Comment @coderabbitai help to get the list of available commands.}

Codecov Report

❌ Patch coverage is 97.21627% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.78%. Comparing base (0e58ac8) to head (34b4c0d).

@@            Coverage Diff             @@
##             main     #437      +/-   ##
==========================================
+ Coverage   87.36%   87.78%   +0.42%     
==========================================
  Files         181      187       +6     
  Lines        9494     9927     +433     
  Branches     2624     2768     +144     
==========================================
+ Hits         8294     8714     +420     
- Misses       1199     1212      +13     
  Partials        1        1              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

@dinohamzic thanks — worked through all nine. Seven are fixed in b166daf..1cc9009; two need your input because they depend on things outside this repo.

Fixed

[P1] Preserve init-notebook semantics — createProject has no init_notebook_id field, so preserving the designation through the public API is not available. Took the other option and refused before creating a broken schedule: scheduleInCloud now throws when the file declares an initNotebookId that resolves to a real notebook and the project is not in Deepnote yet, pointing at the way through (import once, which keeps the designation, then schedule). A project already in Deepnote is unaffected, since nothing is created. Refused before the first POST, so there is no half-built project left behind.

[P1] Share only neutral creation state — took the neutral-create route. createFromFile no longer bakes input overrides into what it writes; a run passes its overrides to triggerNotebookRun, where they belong to the run rather than to the notebook. That keeps the shared create genuinely shareable, so a run joining a schedule-triggered create still gets the block-id mapping — which keying the coordinator on caller state would have cost. Run-only blockIds are now validated before entering the coordinator, so a typo fails only the call that made it rather than whichever schedule joined it.

Two existing tests asserted the old baked-in behaviour and were inverted deliberately — worth a look, since that was a documented design choice I have changed: run-in-cloud.test.ts "creates blocks in sortingKey order…" and "creates a not-found multi-notebook file from its own values…". The coordinator test now also pins that the shared create holds the file's value, not the racing run's.

[P1] Do not trust Host — right, matching two client-controlled headers proved nothing. The Origin is now checked against the socket the request arrived on: a loopback hostname, and the port from req.socket.localPort. Added a raw-http.request test sending the DNS-rebinding shape (matching attacker Origin and Host) — fetch refuses to set Host, which is why it bypasses it — plus a loopback-origin-on-another-port case and a localhost/127.0.0.1 spelling check.

[P2] Reject ambiguous sibling mappings — fails closed now. If a notebook-function block names a local sibling whose name is shared with another notebook in the file, it throws rather than mapping both onto the first cloud match.

[P2] Resolve composed init projects consistently — routed through resolveSnapshotNotebookId, so [init, main] resolves to the main notebook without --notebook. The ambiguity refusal stays for files it cannot resolve. Added a CLI test with an init-backed file.

[P2] Classify malformed files as usage errors — ParseError now maps to exit 2, matching the help text and the other file commands. Tests for malformed YAML and a schema-invalid file.

[P2] Avoid concentrating hourly jobs at minute zero — --hourly now uses the creation minute, and --at is accepted with it to pin one (:15, 15, or an HH:mm whose hour is 00; a non-zero hour is refused rather than silently dropped). resolveScheduleExpression takes an injectable now so this stays testable. Docs updated in the CLI README and the schedule skill reference.

Needs your input

[P2] Select a project that accepts additional notebooks — I can preserve projectType through the parser and prefer a standard project in findProject, but projectType appears nowhere in this repo and the list API's values are not in anything I can see here. What are the identifiers for the standard, single-notebook, and Agent types? With those I will add it. Guessing the enum seemed worse than leaving findProject honest about picking the newest exact-name match.

[P2] Align first-schedule safety defaults — agreed on the substance, but both halves land outside this PR: UpsertNotebookScheduleBody accepts only cron and timezone, so exposing republish/autoPauseOnFailure means changing the internal API's request contract first, and aligning its creation defaults is a deepnote-internal change. Happy to add the fields here the moment the contract carries them — do you want that tracked as a follow-up, or should this PR stay draft until the internal side lands?

CI is green and the full suite passes (2764 tests). Leaving it in draft.

Correcting my previous comment on the two "needs input" items — I had only searched this repo, not the public API docs. The spec at https://api.deepnote.com/v2/openapi.json answers both.

[P2] Select a project that accepts additional notebooks — now fixed in 336d971. No input needed after all; the enum is public:

"projectType": {
  "description": "Project type. Omit to create a `standard` project; `notebook` creates a single-notebook project; `agent` creates an Agent project.",
  "type": "string",
  "enum": ["standard", "notebook", "agent"]
}

It is a required field on the project response. projectSchema now preserves it and findProject skips notebook and agent, exactly as you described. Three details worth confirming:

• When every exact-name match is closed, findProject returns undefined rather than a project the create would 409 on — the caller then makes a fresh standard project. That can leave two same-named projects (one an Agent project), which seemed clearly better than a hard failure, but say if you'd rather it threw.
• An unreported type is treated as usable. Refusing what we cannot read would bring back the duplicate projects this lookup exists to prevent, so the unknown case fails in the safe direction.
• Kept as z.string() rather than a zod enum, so a fourth project type ships without breaking every lookup in this client.

[P2] Align first-schedule safety defaults — confirmed out of scope for this repo, with stronger evidence than I had. UpsertNotebookScheduleBody is:

{
  "type": "object",
  "properties": { "cron": {...}, "timezone": { "default": "UTC", ... } },
  "required": ["cron"],
  "additionalProperties": false
}

additionalProperties: false means sending republish or autoPauseOnFailure today would be rejected, not ignored — so this is blocked on the internal contract carrying them, and on that side's creation defaults. The gap is now written down in the schedule skill reference rather than left implicit, so a CLI-created schedule not matching the UI's defaults is at least documented. Still happy to wire the fields the moment the contract has them — follow-up issue, or hold this PR?

Full suite green (2767 tests). Still draft.

@coderabbitai the four outside-diff-range findings, addressed in 4d64e0e:

serve-static.ts — apply the origin guard to the other token-backed route. Right, and thanks for catching it. POST /api/run-cloud spends the same cloud token and creates project content when the notebook is not in Deepnote yet, so hardening only the schedule route left the same DNS-rebinding door open next to it. Guard applied, with a test asserting a foreign origin gets 403 there too.

schedule-in-cloud.ts — move the init check behind the project lookup. Correct, and the error text was actively misleading: it told the user to import a project they had already imported. Fixed by moving the assertion into createFromFile behind the !destination branch, which is the create-a-new-project path and nothing else. That also resolves the inline run-in-cloud.ts finding in the same place rather than duplicating the check.

run-in-cloud.ts — building specs for every notebook. Agreed, and the misleading-warnings half is the real cost: toBlockSpec warns as it goes, so adding one notebook could report problems in siblings the operation never touches. Spec building is now per-notebook via a specFor(i) helper — the full set only for createProject, just the target for addNotebookToExistingProject. Test asserts one spec goes over the wire.

schedule-expression.ts — validate cron field syntax. Not taking this one. --cron "invalid foo bar baz qux" does reach the API, but the API validates it and returns HTTP 400, which this command already maps to exit code 2 with the server's message — so the user gets a clear, correctly-classified failure either way. Writing a local cron parser to duplicate that would be a heavy lift, as you note, and the failure mode of getting it wrong is worse than the problem: cron legitimately accepts JAN-DEC/MON-SUN names, step values, ranges, and lists, so a hand-rolled validator that is even slightly too strict would reject expressions Deepnote accepts. The server is authoritative on its own cron dialect and I would rather defer to it than shadow it. Happy to revisit if there is a spec-published grammar to validate against.

Full suite green (2773 tests).

#!/bin/bash
set -euo pipefail

git show --no-ext-diff --stat --oneline 4d64e0e
git show --no-ext-diff --format= -- \
  packages/local-runner/src/serve-static.ts \
  packages/local-runner/src/serve-static.test.ts \
  packages/local-runner/src/schedule-in-cloud.ts \
  packages/local-runner/src/run-in-cloud.ts \
  packages/local-runner/src/run-in-cloud.test.ts \
  packages/cli/src/commands/schedule.ts \
  packages/cli/src/utils/schedule-expression.ts \
  4d64e0e

printf '\n--- outlines ---\n'
ast-grep outline packages/local-runner/src/serve-static.ts --items all --type function
ast-grep outline packages/local-runner/src/run-in-cloud.ts --items all --type function
ast-grep outline packages/local-runner/src/schedule-in-cloud.ts --items all --type function

printf '\n--- targeted references ---\n'
rg -n -C 4 \
  'run-cloud|schedule-cloud|Origin|localPort|createFromFile|initNotebookId|specFor|toBlockSpec|statusCode|ScheduleExpressionError|ApiError' \
  packages/local-runner/src/serve-static.ts \
  packages/local-runner/src/serve-static.test.ts \
  packages/local-runner/src/schedule-in-cloud.ts \
  packages/local-runner/src/run-in-cloud.ts \
  packages/local-runner/src/run-in-cloud.test.ts \
  packages/cli/src/commands/schedule.ts \
  packages/cli/src/utils/schedule-expression.ts

@jamesbhobbs Verified in 4d64e0e.

• POST /api/run-cloud now uses the socket-based origin guard before it reads the body. The regression test expects HTTP 403 for a foreign origin.
• assertInitNotebookSurvivesCreation now runs only for new-project creation. Existing projects can receive the missing notebook without the misleading refusal.
• The existing-project path now builds only the target notebook spec. The test confirms that one spec reaches addNotebooksToProject.

I also withdraw the cron field-validation finding. The CLI validates empty and non-five-field cron input. The API validates its authoritative cron dialect. HTTP 400 maps to ExitCode.InvalidUsage, so the user receives the API validation message with the correct exit code.

Learnt from: jamesbhobbs
URL: https://github.com/deepnote/deepnote/pull/437

Timestamp: 2026-08-01T23:58:30.680Z
Learning: For `deepnote schedule`, `packages/cli/src/utils/schedule-expression.ts` performs only structural cron validation, while the Deepnote API is authoritative for cron field syntax and dialect. `packages/cli/src/commands/schedule.ts` maps API HTTP 400 responses to `ExitCode.InvalidUsage`, so server-side cron validation errors are reported as CLI usage errors.

_{You are interacting with an AI system.}

@dinohamzic second round handled — three fixed in 2fdd3d8, and the fourth verified but deliberately left to you.

[P1] Unresolved sibling init notebook — fixed

You're right, and the old branch was worse than "returns successfully": its comment asserted "the designation names nothing in this file, so there is no setup to lose", which is exactly the wrong reading of the split shape. Confirmed against split.test.ts:654-660 — initNotebookId is preserved in every main file precisely so the sibling resolver can find the standalone init.

Worth noting composing would not have fixed it either: resolveAndComposeInit produces [init, main] as two notebooks with initNotebookId still set, so the created project still needs a designation this API cannot set. Failing closed is the only sound option.

[P1] Exact-name destination proves nothing — fixed

Agreed, and this reverses a change I made last round on CodeRabbit's suggestion that the existing-project path was safe. Your reasoning wins: only the target notebook is uploaded, and the API will not report the destination's designation, so a same-name project — or one whose designation was removed — runs without setup.

Both P1s now collapse into one rule in createFromFile: if initNotebookId is set, refuse to create, full stop. No destination gate, no unresolvable-id escape. That covers runInCloud too, which had the same hole. Tests cover the new-project, existing-project, and sibling-init cases for both entry points.

[P2] Spread daily/weekly/monthly — fixed

Fair — spreading only hourly was half a fix. All cadences now default to the creation time, matching SchedulingModalContainer's defaultTime = dayjs().format('HH:mm') and the reasoning in its comment. 09:00 was arguably the worst possible fixed default. --at still pins a time; resolveScheduleExpression takes an injectable clock so it stays testable.

[P2] First-schedule safety defaults — verified, not actioned here

I verified your claim exhaustively against the published spec rather than assuming, and it holds in the strongest form:

• UpsertNotebookScheduleBody is {cron, timezone} with additionalProperties: false — extra fields are rejected, not ignored.
• Zero occurrences of republish, pause, failure, or consecutive anywhere in the 132 KB spec.
• No write endpoint in the entire public API could carry them: POST /projects takes only folderId/name/projectType, and there is no project or notebook settings update endpoint.
• Column defaults confirmed as you said (republish false, auto_pause_on_failure false), against max_consecutive_failures defaulting to 3, which already matches the modal.

So there is no way to close this from this repo — it needs the internal create branch to apply the product defaults, which is your call to sequence rather than something I should land unilaterally in a different repo. Flagging one thing for whoever picks it up: notebooks.schedule.test.ts's "preserves fields not included in an update, such as republish" seeds republish: true, which is the same value a defaulting create branch would produce — so it would keep passing even if update wrongly applied the create defaults. Seeding false would make it prove preservation.

Happy to wire the client side here the moment the contract carries the fields.

CI note: Test (Node 23) is the 5-minute job timeout hitting Build packages (5m16s, reported as cancelled, no test ever ran) — re-run requested. Audit - All is a newly published brace-expansion advisory; it passed on this branch ~19h ago on the identical lockfile and my commit touches no dependency files, so it is repo-wide rather than from this PR, and looks like a separate chore(security) bump.

CI follow-up: the Test (Node 23) red was the 5-minute job timeout as expected — it passes on re-run, so the only red left is Audit - All.

Refining what I said about that one: Audit - Production passes and only Audit - All fails, so the brace-expansion advisory sits in a dev-only dependency and nothing shipped is affected. Still repo-wide rather than from this PR (no dependency files touched here, and it passed on this branch ~19h ago on the identical lockfile), and still best handled as a separate chore(security) bump.

Everything else is green: 20/21 checks, full suite 2779 tests.

@coderabbitai open an issue describing this difference to deepnote cloud as something to fix later #437 (review)

#!/bin/bash
set -euo pipefail

gh api repos/deepnote/deepnote/pulls/comments/4853245965 \
  --jq '{id, html_url, body, path, line, user: .user.login}'

gh pr view 437 --repo deepnote/deepnote \
  --json url,title \
  --jq '{url,title}'

#!/bin/bash
set -euo pipefail

gh api repos/deepnote/deepnote/pulls/437/reviews/4853245965 \
  --jq '{id, html_url, body, user: .user.login}'

gh pr view 437 --repo deepnote/deepnote \
  --json url,title \
  --jq '{url,title}'

#!/bin/bash
set -euo pipefail

ISSUE_TITLE="$(cat <<'EOF'
Preserve friendly schedule cadence for API-created notebook schedules
EOF
)"

ISSUE_BODY="$(cat <<'EOF'
## Summary

Notebook schedules created through the public API use a cron expression. When the CLI creates a schedule with `--hourly`, `--daily`, `--weekly`, or `--monthly`, Deepnote Cloud displays the schedule type as `Cron (custom)` instead of the matching friendly cadence.

Deepnote Cloud should preserve or recognize the friendly cadence for schedules created through the API.

## Rationale

The CLI presents friendly cadence options. The Deepnote Cloud UI should show the same cadence after the schedule is created. A `Cron (custom)` display makes a standard schedule appear different from the selected CLI option.

## Affected areas

- Deepnote Cloud notebook schedule creation and display
- Public schedule API contract
- Schedule persistence or schedule-type inference

## References

- PR: [`#437`](https://github.com/deepnote/deepnote/pull/437)
- Review: [pullrequestreview-4853245965](https://github.com/deepnote/deepnote/pull/437#pullrequestreview-4853245965)
- Requested by: `@jamesbhobbs`

## Acceptance criteria

- [ ] A schedule created with the API from an hourly cadence displays as `Hourly` in Deepnote Cloud.
- [ ] A schedule created with the API from daily, weekly, and monthly cadences displays as the matching cadence in Deepnote Cloud.
- [ ] A genuinely custom cron expression continues to display as `Cron (custom)`.
- [ ] The public API contract documents the supported behavior. If cadence metadata is required, the API accepts and returns it.
EOF
)"

issue_url="$(
  gh issue create \
    --repo deepnote/deepnote \
    --title "$ISSUE_TITLE" \
    --body "$ISSUE_BODY" \
    --assignee jamesbhobbs
)"

printf '%s\n' "$issue_url"

@jamesbhobbs Created and assigned #446: Preserve friendly schedule cadence for API-created notebook schedules.

_{You are interacting with an AI system.}