feat(cli): flag the narrower embedded token when publish enables API access - #492

Merge Risk: 🔵 Low · up to e62eb

The CLI may mislead users about timeout defaults and embedded API limits, while documentation and tests leave two smaller regressions possible. These are bounded follow-up issues rather than evidence of a serious runtime failure.

• Fix all pre-merge checks with AI

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

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.86%. Comparing base (0d31f24) to head (e62eb1b).

@@           Coverage Diff           @@
##             main     #492   +/-   ##
=======================================
  Coverage   89.85%   89.86%           
=======================================
  Files         206      207    +1     
  Lines       12194    12200    +6     
  Branches     3512     3514    +2     
=======================================
+ Hits        10957    10963    +6     
  Misses       1234     1234           
  Partials        3        3           

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

Verified this PR's claims against staging with a real static app viewer token (fresh project with sharing and API access enabled, one notebook, one code block), and against the server code staging was running at the time. Findings, blocking first.

Blocking

• "Does not report an error" is wrong. Every call outside the allowlist returns HTTP 403 with {"message":"This endpoint is not available to static app tokens"}. Observed live for notebook listing, run enumeration, project read, /v2/me, and a project DELETE. The silence comes from examples/local-runner/cloud-app, whose listRuns returns { runs: [] } on any non-OK response. The wrong claim appears in cli-publish.md line 60 (bold), the help text in cli.ts lines 601-602, and the runtime note plus its comment in publish.ts lines 343-356. Telling authors there is no error signal hides the one thing that diagnoses the problem, the 403 in the network tab.

• The "Available" list overstates the surface. Observed live with the viewer token:

  • POST /v2/runs with detached: false returns 400 Static app tokens only support detached runs. Omitting the field is fine since it defaults to true, so only apps that explicitly request a live run hit this.
  • GET /v2/notebooks/:id strips block source. Blocks come back as { id, type } only.
  • GET /v2/runs/:id ignores snapshotDelivery. snapshotContent and snapshotDownloadUrl are always null and outputs arrive only as snapshotBlocks. An app that requests snapshotDelivery=inline and parses the YAML locally gets null when embedded, with no error. This is the one genuinely silent local-versus-embedded difference, and the note does not mention it.
  • The "Unavailable" line reads as a complete list, while the server is default-deny for everything else.

  apps.md states all of this correctly. The runtime note (publish.ts line 352), the help text (cli.ts lines 596-597), and cli-publish.md lines 50-51 say plain "start a run" and "read the configured notebook".

• Token lifetime is a local-versus-embedded difference the note skips. The viewer token expires 15 minutes after it is minted, while a personal API key does not expire. An app that stores the token once starts getting 401 mid-session. The example app refreshes on 401 over postMessage. Neither the note, the help text, cli-publish.md, nor apps.md says this.

• The skill reference now has three prose copies of the same boundary. AGENTS.md line 222 assigns token boundaries to apps.md, and apps.md section 4 already has the table, the quiet-failure paragraph, and the isEmbedded pointer. docs/deepnote-cli-publish.md lines 139-142 also already describe the token and its surface, so the PR body's "nothing said so" only holds for the help text and the skill reference. The new cli-publish.md section restates it with a narrower, less accurate table and no cross-link. Suggest one sentence saying publish prints a reminder, plus a link to apps.md. The help text should shrink to a pointer for the same reason.

Checked and correct as written

• "May not read another viewer's run" is enforced. The static app router on the server rejects a run read with 403 when the run's creator is not the token's viewer, and returns lastRunId: null and lastRunAt: null on the notebook read so there is no pointer to anyone else's run. Both are covered by server tests. Live I could only exercise the same-user case, where reads across two credentials of one user succeed as expected, so the cross-user 403 rests on the code and its tests. The table row at cli-publish.md line 52 and the matching apps.md rows can stay.

Non-blocking

• "Prints a reminder whenever it leaves API access enabled" is stronger than the code. The note lives on the success branch inside the quiet guard, and deepnote static-site access, which toggles the same setting, prints API access: enabled with no note. Either share the note between both commands or soften cli-publish.md line 63.
• The note fires on every redeploy, not on the enable transition. When settings are reused, the flag comes from stored settings, so a CI job on an already-enabled project prints the block on every run. That contradicts the PR title. The reuse branch is untested, and the new test ties the flag and the mocked server result to the same boolean, so it cannot tell which one the note keys on. Add a case with no flag and stored settings already enabled, and decide whether transition-only is what you want.
• Test and code trimming. The quiet-mode test re-checks the output helper's quiet gating and the pre-existing quiet guard, neither touched here, so it can go. The two-column it.each has identical columns and could fold into the existing API-access it.each at line 191. The five log calls could be one template literal, and the three-line comment restates the printed text.
• PR body: "Closes feat(cli): flag the narrower embedded token when publish enables API access #492" references this PR's own number, so it closes nothing. docs/deepnote-cli-publish.md and the CLI README describe the same flag and were not updated, though AGENTS.md does not require that.

Replies to the review-body remarks that have no inline thread:

• Assert the complete warning (Aug 26 and Sep 14): done in 18bf933. Both command tests now assert the full shared note via the helper's output, and the disabled case still asserts it is absent.
• Exit-code description names only the sharing update: done in 9914565. The PATCH carries API access as well, so it now says "project settings update".
• Prune-baseline qualification (cli-publish.md, mirror-update failure): pre-existing text outside this PR's subject; leaving it for a follow-up.

The two inline threads from Sep 10 are addressed in 99f50d0 and resolved.

Posted by Claude Code on Wojtek's behalf.