refactor(local-runner): one run endpoint for dynamic apps, cloud by default - #465

Summary

serveStatic — the machinery behind dynamic apps — exposed two run routes: POST /api/run for a local kernel and POST /api/run-cloud for Deepnote. Every app built on it therefore needed two buttons, two response shapes to render, and a decision from the user about where a run should happen before anything could run at all.

This collapses them into one POST /api/run whose destination is a server setting, defaulting to Deepnote Cloud.

await serveStatic({
  dir: "./public",
  notebookPath: "dashboard.deepnote",
  // runTarget: "local",  // omit for Deepnote Cloud
});

GET /api/info now reports runTarget alongside the input blocks, so a page can label its Run button without being told separately — run-app uses this to say "Running in Deepnote Cloud…" or "Running in a local kernel…" from one handler.

Security: the guard follows what it protects

The cross-origin guard stayed tied to what it protects rather than to a route name. A cloud run spends the token and can create project content as a side effect, so it keeps the guard; a local run does neither and keeps the looser rule it had on its own route:

if (runTarget === 'cloud' && rejectCrossOriginRequest(req, res)) return

Both directions are pinned by tests — a foreign origin still gets 403 against a cloud-targeted server, and still gets through to a local one — so folding the routes together can't silently tighten or loosen it.

Behaviour change in the example

run-app now runs in Deepnote Cloud by default and wants DEEPNOTE_TOKEN; RUN_TARGET=local restores the local-kernel path and its OPENAI_API_KEY requirement. serve.mjs turns that env var into runTarget, so the option is visible in the example rather than only in the docs.

Local responses now state success: true rather than implying it, so a page reads one field for both targets instead of inferring "no news is good news" from the shorter local response.

Breaking change

POST /api/run-cloud is gone. Callers that ran in the cloud now POST to /api/run against a server using the default runTarget; callers that ran locally pass runTarget: 'local'. serveStatic has no consumers outside this repo's run-app example, which is updated here.

cloudRunner is gone too — the two runner seams are now one RunnerFn:

type RunnerFn = (input, inputs, options?: RunOptions) => Promise<RunResult>

RunOptions carries what either end needs (pythonEnv, persistSnapshot, token). RunResult describes either outcome: outputs and success are the fields every run has, while runId, status, created, and viewUrl describe a cloud run and are simply absent from a local one — they drop out of the JSON rather than being sent as nulls.

Both ends are adapted to that signature where the runner is resolved, so the route itself no longer branches at all — one call, one response builder:

const runner: RunnerFn = options.runner ??
  (runTarget === 'local'
    ? (input, inputs, o) => runWithInputs(input, inputs, { pythonEnv: o?.pythonEnv, persistSnapshot: o?.persistSnapshot })
    : (input, inputs, o) => runInCloud(input, inputs, { token: o?.token }))

The Deepnote API is the default, and the only thing that overrides it is having a local Deepnote kernel to point at.

Test plan

• pnpm test — 2896 passed, 1 skipped (serve-static.test.ts: 34 passed)
• pnpm typecheck clean
• pnpm spell-check — 0 issues
• pnpm prettier:check clean
• New tests: cloud is the default target, runTarget: 'local' reaches the local runner, /api/info reports either, and the origin guard applies to cloud but not local
• pnpm example:local-runner with DEEPNOTE_TOKEN — one Run button, runs in Deepnote
• RUN_TARGET=local OPENAI_API_KEY=… pnpm example:local-runner — same button, local kernel

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Unified notebook execution through a single /api/run endpoint.
  • Deepnote Cloud execution is now the default, with optional local execution.
  • Added execution target information to status updates and results.
  • Simplified the runner interface with one Run button for both execution modes.
  • Improved reporting for execution failures and invalid run targets.
• Documentation
  • Updated local runner guides with cloud-default behavior, credentials, configuration, and local execution instructions.
• Bug Fixes
  • Improved request protection for cloud execution while allowing local runs from permitted contexts.