@yolo-labs/yolo-cli 0.24.0 → 0.30.0

package/dist/deploy-bundle.js

@@ -8,11 +8,21 @@
  *   - **Worker module** — esbuild ESM bundle of the entry
  *     (`{bundle, format:'esm', platform:'browser',
  *     conditions:['workerd','worker'], target:'es2022', write:false,
- *     minify:true}`). If the entry already points at a BUILT `.js`/`.mjs`
- *     module (vinext/OpenNext output, skill-directed), esbuild is
- *     SKIPPED and the module ships byte-for-byte as-is — the size
- *     ceilings still apply. esbuild is lazy-imported so `yolo plan`
- *     startup never pays for it (the `serve.ts` lazy-load precedent).
+ *     minify:true, define:{'process.env.NODE_ENV':'"production"'}}` +
+ *     `nodeBuiltinExternalPlugin`). `NODE_ENV` is pinned to `production` so
+ *     libraries that branch on it (React et al.) never ship their dev build on
+ *     workerd (which has no runtime `process.env`). The plugin leaves every real
+ *     `node:` builtin external (nodejs_compat serves the supported ones); a
+ *     misspelled non-builtin is the only `node:` case that fails the build. It
+ *     WARNS (not fails) when nodejs_compat is absent and when a builtin is loaded
+ *     via `require()` (throws in an ESM Worker unless guarded). If the entry
+ *     already points at a
+ *     BUILT `.js`/`.mjs` module (vinext/OpenNext output, skill-directed),
+ *     esbuild is SKIPPED and the module ships byte-for-byte as-is — the size
+ *     ceilings still apply and the shipped text is scanned to WARN on retained
+ *     `node:` imports and an unpinned `process.env.NODE_ENV`. esbuild is
+ *     lazy-imported so `yolo plan` startup never pays for it (the `serve.ts`
+ *     lazy-load precedent).
  *   - **Asset manifest** — walk `assetsDir` (skip dotfiles +
  *     node_modules), URL-style path → `{hash: sha256hex, size}`.
  *     Pure-static ships NO module; common-api attaches the canonical
@@ -32,6 +42,7 @@
  */
 import { createHash } from 'node:crypto';
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { isBuiltin } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { gzipSync } from 'node:zlib';
@@ -95,6 +106,98 @@ function vendoredFlexdbPlugin() {
         },
     };
 }
+// ─── node: builtin externalization ──────────────────────────────────────────
+//
+// A `node:` builtin can't be bundled — esbuild's browser resolver would hard-
+// fail it. We leave every REAL builtin external (workerd's nodejs_compat serves
+// the ones it supports at the pinned compatibility date); the ONLY `node:` case
+// that stays a build error is a non-builtin specifier (a `node:async_hook` typo
+// → esbuild "Could not resolve"). Everything else externalizes and, where risky,
+// WARNS post-bundle:
+//   - a require()-kind load → esbuild emits __require(...), which throws in an
+//     ESM Worker UNLESS guarded by try/catch → warn (collectExternalNodeRequires),
+//     don't fail — a hard error would break guarded optional-dependency probes
+//   - node: builtins with no nodejs_compat → warn (warnMissingNodejsCompat)
+//
+// Deliberately NOT a workerd compatibility oracle: which builtins a given
+// compatibility-date + flag set actually serves (tls, node:fs behind
+// enable_nodejs_fs_module, modules dropped by no_* flags, …) is a moving matrix
+// that belongs to the runtime, not the bundler. Modeling it here only produces
+// false build rejections of valid Workers. The post-ship boot probe / runtime is
+// the authority on whether a module is really served.
+/**
+ * esbuild plugin that leaves every real `node:` builtin external (any import
+ * kind, including require-call), so a non-builtin typo is the only `node:` case
+ * that stays a build error. A require()-kind load is externalized rather than
+ * rejected: esbuild emits `__require(...)`, which a GUARDED probe
+ * (`try { require("node:fs") } catch { …fallback… }`) can still catch — a hard
+ * rejection would break that common optional-dependency pattern. An UNGUARDED
+ * require of a builtin throws in an ESM Worker; that's surfaced as a post-bundle
+ * warning (see collectExternalNodeRequires), not a build failure.
+ */
+function nodeBuiltinExternalPlugin() {
+    return {
+        name: 'yolo-node-builtin-external',
+        setup(build) {
+            build.onResolve({ filter: /^node:/ }, (args) => {
+                if (isBuiltin(args.path))
+                    return { path: args.path, external: true };
+                return null; // not a builtin at all → esbuild reports "Could not resolve"
+            });
+        },
+    };
+}
+/**
+ * The distinct `node:<builtin>` specifiers referenced by already-bundled text
+ * (prebuilt worker path, which never touches esbuild). A `node:` literal in
+ * call position — `require(…)`, esbuild's `__require(…)`, dynamic `import(…)` —
+ * or after `from`/bare `import` counts. Matching any call `(` (rather than a
+ * specific helper name) is deliberate: bundlers rename the require helper.
+ * Deduped, sorted.
+ */
+export function collectNodeBuiltinsFromText(text) {
+    const found = new Set();
+    const re = /(?:\bfrom\s*|\bimport\s*|\(\s*)['"](node:[a-zA-Z0-9_/.-]+)['"]/g;
+    let m;
+    while ((m = re.exec(text)) !== null)
+        found.add(m[1]);
+    return [...found].sort();
+}
+/**
+ * The distinct `node:` builtins loaded via a CommonJS `require(…)` / esbuild's
+ * `__require(…)` (any `<ident>require(` helper) in already-bundled text. These
+ * throw in an ESM Worker regardless of `nodejs_compat` — the esbuild path
+ * rejects them; the prebuilt path (esbuild skipped) can only WARN. Deduped, sorted.
+ */
+export function collectNodeRequireCalls(text) {
+    const found = new Set();
+    // A require-CALL of a node: literal: `require("node:x")`, `__require("node:x")`.
+    // The leading \w* covers renamed helpers; it won't match the shim's own
+    // definition (that has no node: string argument).
+    const re = /\w*require\s*\(\s*['"](node:[a-zA-Z0-9_/.-]+)['"]/g;
+    let m;
+    while ((m = re.exec(text)) !== null)
+        found.add(m[1]);
+    return [...found].sort();
+}
+/**
+ * Push the "missing nodejs_compat" warning when a Worker references a `node:`
+ * builtin but that flag isn't set. Shared by the esbuild and prebuilt paths so
+ * `BundleOptions`' promise holds for both.
+ *
+ * Keyed strictly on `nodejs_compat` — the ONLY compatibility flag the hosting
+ * service accepts at ship (`ship-session.ts` ALLOWED_COMPATIBILITY_FLAGS). We
+ * deliberately do NOT recognize narrower flags (`nodejs_als`) or per-module
+ * enable flags here: suppressing the warning for a flag the server rejects
+ * would pass local bundling only to fail at ship with `bundle-invalid`.
+ */
+function warnMissingNodejsCompat(nodeBuiltins, compatibilityFlags, warnings) {
+    if (nodeBuiltins.length === 0 || compatibilityFlags.includes('nodejs_compat'))
+        return;
+    warnings.push(`worker imports node: builtins (${nodeBuiltins.join(', ')}) but compatibilityFlags does not ` +
+        `include "nodejs_compat" — they resolve to nothing at runtime on workerd. Add "nodejs_compat" ` +
+        `to .yolo/deploy.json compatibilityFlags.`);
+}
 // ─── Public types ─────────────────────────────────────────────────────────
 export const DEPLOY_CEILINGS = {
     /** CF hard per-file limit. */
@@ -106,20 +209,28 @@ export const DEPLOY_CEILINGS = {
     maxModuleBytes: 10 * 1024 * 1024,
     /** Gzipped-module size that triggers a warning (not a failure). */
     warnModuleGzipBytes: 1 * 1024 * 1024,
+    /**
+     * Sourcemap sidecar cap — mirrors the server's FINALIZE_SOURCEMAPS_MAX_BYTES
+     * (common-api `routes/deploy.ts`). Over this we DROP the map (+ warn) rather
+     * than fail the deploy or 413 late at finalize — symbolication is optional.
+     */
+    maxSourceMapBytes: 40 * 1024 * 1024,
 };
-// ─── Public entry ─────────────────────────────────────────────────────────
-export async function bundleProject(shape, cwd, ceilings = {}) {
+export async function bundleProject(shape, cwd, ceilings = {}, options = {}) {
     const caps = { ...DEPLOY_CEILINGS, ...definedOnly(ceilings) };
     const warnings = [];
+    const compatibilityFlags = options.compatibilityFlags ?? [];
     // ── Worker module (esbuild, or as-is for pre-built entries) ────────────
     let module = null;
     let moduleSource = null;
+    let sourceMap = null;
     if (shape.type === 'worker') {
-        const built = await buildWorkerModule(shape.entry, cwd, shape.prebuilt === true, caps, warnings);
+        const built = await buildWorkerModule(shape.entry, cwd, shape.prebuilt === true, caps, warnings, compatibilityFlags, options.sourcemaps === true);
         if (!built.ok)
             return built;
         module = built.module;
         moduleSource = built.source;
+        sourceMap = built.sourceMap ?? null;
     }
     // ── Asset walk + manifest + ceilings ────────────────────────────────────
     const manifest = {};
@@ -195,6 +306,7 @@ export async function bundleProject(shape, cwd, ceilings = {}) {
         module,
         workerModules: module === null ? [] : [module],
         moduleSource,
+        sourceMap, // sidecar — intentionally excluded from workerModules + the digest below
         fileCount,
         totalAssetBytes,
         bundleDigest: computeBundleDigest(module === null ? [] : [module], manifest),
@@ -228,11 +340,68 @@ export function computeBundleDigest(modules, manifest) {
     hash.update(JSON.stringify(entries), 'utf8');
     return `sha256:${hash.digest('hex')}`;
 }
-async function buildWorkerModule(entry, cwd, prebuilt, caps, warnings) {
+// ─── Internals ────────────────────────────────────────────────────────────
+/**
+ * The distinct `node:` builtin specifiers esbuild left external for this
+ * bundle (deduped, sorted). Empty when the Worker imports none. Used to warn
+ * when `nodejs_compat` is absent — the runtime, not the bundler, is where a
+ * missing flag bites.
+ */
+function collectExternalNodeBuiltins(metafile) {
+    if (!metafile)
+        return [];
+    const found = new Set();
+    for (const input of Object.values(metafile.inputs)) {
+        for (const imp of input.imports) {
+            if (imp.external && imp.path.startsWith('node:'))
+                found.add(imp.path);
+        }
+    }
+    return [...found].sort();
+}
+/**
+ * Ensure the sourcemap JSON carries a `file` field naming the module it maps
+ * (`index.js`) — CF associates a map to its module by this field (verified live)
+ * and esbuild omits it. Returns the map text unchanged if it isn't parseable
+ * JSON (defensive; the map still ships, just possibly un-symbolicated).
+ */
+function withMapFile(mapText, moduleName) {
+    try {
+        const parsed = JSON.parse(mapText);
+        if (parsed.file === moduleName)
+            return mapText;
+        parsed.file = moduleName;
+        return JSON.stringify(parsed);
+    }
+    catch {
+        return mapText;
+    }
+}
+/**
+ * The distinct `node:` builtins loaded via a CommonJS `require()` (esbuild
+ * import kind `require-call`) in this bundle. esbuild compiles these to
+ * `__require(...)`, which throws in an ESM Worker unless the call is guarded by
+ * try/catch — so we WARN (not fail), preserving the guarded optional-dependency
+ * pattern. Deduped, sorted.
+ */
+function collectExternalNodeRequires(metafile) {
+    if (!metafile)
+        return [];
+    const found = new Set();
+    for (const input of Object.values(metafile.inputs)) {
+        for (const imp of input.imports) {
+            if (imp.external && imp.kind === 'require-call' && imp.path.startsWith('node:'))
+                found.add(imp.path);
+        }
+    }
+    return [...found].sort();
+}
+async function buildWorkerModule(entry, cwd, prebuilt, caps, warnings, compatibilityFlags, sourcemaps) {
     const entryAbs = path.resolve(cwd, entry);
     let contents;
     let name;
     let source;
+    let sourceMap;
     // Ship as-is ONLY for an explicitly-configured built output (deploy.json
     // worker.entry → .js/.mjs). Auto-detected `src/index.js` is SOURCE and must
     // be bundled or its imports are dropped (codex P2 r6).
@@ -250,6 +419,28 @@ async function buildWorkerModule(entry, cwd, prebuilt, caps, warnings) {
         }
         name = path.basename(entryAbs);
         source = 'prebuilt';
+        // esbuild never runs for prebuilt output (vinext/OpenNext), so its define +
+        // node: externalization can't apply — scan the shipped text directly and
+        // WARN instead. Mutating an opaque framework bundle would break the
+        // ship-as-is contract; the fix belongs in the framework build.
+        const prebuiltText = Buffer.from(contents).toString('utf8');
+        warnMissingNodejsCompat(collectNodeBuiltinsFromText(prebuiltText), compatibilityFlags, warnings);
+        // A require()/__require() of a node: builtin throws in an ESM Worker no
+        // matter what nodejs_compat is — the esbuild path rejects it, so warn here
+        // independently of the missing-compat warning above (which nodejs_compat
+        // suppresses). The framework build should emit ESM imports instead.
+        const nodeRequires = collectNodeRequireCalls(prebuiltText);
+        if (nodeRequires.length > 0) {
+            warnings.push(`prebuilt worker uses require() of node: builtins (${nodeRequires.join(', ')}) — a CommonJS ` +
+                `require of a builtin throws in an ESM Worker. Rebuild it to emit ESM \`import\`s.`);
+        }
+        if (prebuiltText.includes('process.env.NODE_ENV')) {
+            // A pinned build would have replaced this literal with "production"; its
+            // survival means NODE_ENV is unpinned → risks shipping a dev build.
+            warnings.push(`prebuilt worker references process.env.NODE_ENV — workerd has no runtime process.env, so an ` +
+                `unpinned NODE_ENV can ship a dev build (e.g. development React). Pin it in your framework ` +
+                `build (esbuild define 'process.env.NODE_ENV'='"production"').`);
+        }
     }
     else {
         // Lazy-load so non-deploy verbs never pay esbuild's startup cost.
@@ -268,9 +459,23 @@ async function buildWorkerModule(entry, cwd, prebuilt, caps, warnings) {
                 target: 'es2022',
                 write: false,
                 minify: true,
+                metafile: true,
+                // Pin production so libraries that gate on process.env.NODE_ENV (React
+                // et al.) never emit their dev build — workerd has no runtime
+                // process.env, so an unpinned NODE_ENV silently ships dev code.
+                define: { 'process.env.NODE_ENV': '"production"' },
                 absWorkingDir: path.resolve(cwd),
                 logLevel: 'silent',
-                plugins: flexdbPlugin ? [flexdbPlugin] : [],
+                // sourcemaps: 'linked' adds a `//# sourceMappingURL=index.js.map`
+                // comment (which CF uses to associate the uploaded map) + emits the
+                // .map as a second output. A fixed outfile makes that comment's name
+                // deterministic so it matches the uploaded sidecar. OFF → the exact
+                // prior options → byte-identical module → stable digest.
+                ...(sourcemaps ? { sourcemap: 'linked', outfile: path.resolve(cwd, 'index.js') } : {}),
+                // nodeBuiltinExternalPlugin leaves real node: builtins external
+                // (nodejs_compat serves them); only a non-builtin misspelling fails the
+                // build. Ordered first so it wins over default resolve.
+                plugins: [nodeBuiltinExternalPlugin(), ...(flexdbPlugin ? [flexdbPlugin] : [])],
             });
         }
         catch (err) {
@@ -281,13 +486,45 @@ async function buildWorkerModule(entry, cwd, prebuilt, caps, warnings) {
                 message: `esbuild failed for ${entry}: ${msg}`,
             };
         }
-        const out = result.outputFiles?.[0];
+        const outputs = result.outputFiles ?? [];
+        // The module is the non-.map output; the .map (present only with sourcemaps)
+        // is the sidecar.
+        const out = outputs.find((o) => !o.path.endsWith('.map'));
+        const mapOut = outputs.find((o) => o.path.endsWith('.map'));
         if (out === undefined) {
             return { ok: false, kind: 'build-failed', message: `esbuild produced no output for ${entry}` };
         }
+        // node: builtins were left external above; if the Worker actually imports
+        // any and nodejs_compat isn't enabled, they resolve to nothing at runtime.
+        warnMissingNodejsCompat(collectExternalNodeBuiltins(result.metafile), compatibilityFlags, warnings);
+        // A require()-kind load of a builtin becomes __require(...), which throws in
+        // an ESM Worker unless guarded — advisory (guarded probes stay valid).
+        const nodeRequires = collectExternalNodeRequires(result.metafile);
+        if (nodeRequires.length > 0) {
+            warnings.push(`worker loads node: builtins via require() (${nodeRequires.join(', ')}) — require() throws in an ` +
+                `ESM Worker unless wrapped in try/catch. Prefer an ESM \`import\`.`);
+        }
         contents = out.contents;
         name = 'index.js';
         source = 'esbuild';
+        if (sourcemaps && mapOut !== undefined) {
+            // Name matches the `//# sourceMappingURL=index.js.map` comment esbuild
+            // wrote into the module (deterministic via the fixed outfile).
+            // CF associates the sourcemap to the module by the map's `file` field —
+            // verified against the live account: esbuild OMITS `file`, and without it
+            // CF returns minified exception stacks; adding `file` = the module name
+            // makes it symbolicate. (wrangler's map carries `file` too.)
+            const content = withMapFile(Buffer.from(mapOut.contents).toString('utf8'), name);
+            if (Buffer.byteLength(content, 'utf8') > caps.maxSourceMapBytes) {
+                // Too big to upload — drop it (the module is valid) so the deploy still
+                // ships, just without symbolicated stacks. Better than a late 413.
+                warnings.push(`sourcemap is ${formatBytes(Buffer.byteLength(content, 'utf8'))} (> ${formatBytes(caps.maxSourceMapBytes)}) — ` +
+                    `skipping it; exceptions in deploy.logs won't be source-mapped for this release`);
+            }
+            else {
+                sourceMap = { name: 'index.js.map', content };
+            }
+        }
     }
     if (contents.byteLength > caps.maxModuleBytes) {
         return {
@@ -301,7 +538,7 @@ async function buildWorkerModule(entry, cwd, prebuilt, caps, warnings) {
     if (gzipBytes > caps.warnModuleGzipBytes) {
         warnings.push(`worker module is ${formatBytes(gzipBytes)} gzipped (> ${formatBytes(caps.warnModuleGzipBytes)}) — cold starts will suffer`);
     }
-    return { ok: true, module: { name, contents }, source };
+    return { ok: true, module: { name, contents }, source, ...(sourceMap ? { sourceMap } : {}) };
 }
 /**
  * Depth-first walk returning sorted posix-relative file paths. Skips

package/dist/deploy-cli.js

@@ -35,12 +35,16 @@ import { runDeployShip, exitCodeForFailure, formatShipSuccess, formatPending, fo
 import { resolveDeployContext, createProject, getProjectStatus, listProjects, rollbackProject, unpublishProject, republishProject, renameProject, addAlias, removeAlias, setRedirect, deleteProject, cloneProject, getLogs, pollTail, queryD1, } from './deploy-client.js';
 import { readDeployConfig, writeDeployConfig } from './deploy-config.js';
 import { adaptWrangler, detectProjectShape } from './deploy-detect.js';
+import { collectNodeBuiltinsFromText } from './deploy-bundle.js';
+import { runDeployDev } from './deploy-dev.js';
 import { defaultReadFile } from './auth-context.js';
 const USAGE = [
     'Usage: yolo deploy [--env <staging|prod>] [--dry-run] [--json]',
     '       yolo deploy init [--slug <slug>] [--type <static|worker>]',
     '       yolo deploy link (--project-id <id> | --slug <slug>) [--type <static|worker>]',
     '       yolo deploy validate [--json]',
+    '       yolo deploy doctor [--json]',
+    '       yolo deploy dev [--port <n>] [--host <h>] [--var KEY=VALUE ...]',
     '       yolo deploy status [--json]',
     '       yolo deploy logs [--tail] [--since <dur>] [--json]',
     '       yolo deploy rollback [releaseId] [--json]',
@@ -69,6 +73,10 @@ export async function runDeployCmd(args, deps = {}) {
         return runLinkCmd(args.slice(1), deps, io);
     if (sub === 'validate')
         return runValidateCmd(args.slice(1), deps, io);
+    if (sub === 'doctor')
+        return runDoctorCmd(args.slice(1), deps, io);
+    if (sub === 'dev')
+        return runDevCmd(args.slice(1), deps, io);
     if (sub === 'status')
         return runStatusCmd(args.slice(1), deps, io);
     if (sub === 'logs')
@@ -251,6 +259,11 @@ async function runInitCmd(args, deps, io) {
     const created = await create(auth.context, {
         name: parsed.slug ?? path.basename(cwd),
         ...(parsed.slug ? { slug: parsed.slug } : {}),
+        // Session pods provide WORKSPACE_ID. Persisting it on the hosting project
+        // lets server-side deploy lifecycle events route back to the workspace
+        // (and therefore to VibeAssist event watchers). Local CLI use remains
+        // unchanged because the field is optional.
+        ...(deps.env?.WORKSPACE_ID ? { workspaceId: deps.env.WORKSPACE_ID } : {}),
     });
     if (!created.ok) {
         // create-or-LINK: a `slug-taken` on a slug the caller ALREADY OWNS means a
@@ -577,6 +590,212 @@ async function runValidateCmd(args, deps, io) {
         io.out(`  note: ${n}\n`);
     return 0;
 }
+/**
+ * `yolo deploy doctor [--json]` — a fast OFFLINE lint of the worker entry
+ * against the workerd runtime contract (see the Runtime Contract doc). Catches
+ * the field-report gotchas before a ship: `process.env` reads (workerd has no
+ * runtime process.env), `node:` imports without `nodejs_compat`, `require()` of
+ * a builtin, and an unpinned `NODE_ENV` in a prebuilt bundle.
+ *
+ * It scans only the ENTRY file (no bundling, no dep walk) — advisory, so
+ * warnings do NOT fail the command; only a broken config / missing source entry
+ * exits non-zero. Run `yolo deploy --dry-run` for a full bundle-level check.
+ */
+async function runDoctorCmd(args, deps, io) {
+    const jsonOutput = args.includes('--json');
+    const unexpected = args.filter((a) => a !== '--json');
+    if (unexpected.length > 0) {
+        io.err(`yolo deploy doctor: unexpected argument(s): ${unexpected.join(' ')}\nUsage: yolo deploy doctor [--json]\n`);
+        return 64;
+    }
+    const cwd = deps.cwd ?? process.cwd();
+    const readFile = deps.readFileImpl ?? defaultReadFile;
+    const statPath = deps.statPathImpl ?? defaultStatPath;
+    const readConfig = deps.readDeployConfigImpl ?? readDeployConfig;
+    // Resolve config + shape (a broken config is a hard error, like validate).
+    const readResult = readConfig(cwd, deps.readFileImpl);
+    if (!readResult.ok) {
+        const msg = readResult.errors?.map((e) => `${e.path ? `${e.path}: ` : ''}${e.message}`).join('; ') ?? readResult.message;
+        if (jsonOutput)
+            io.out(`${JSON.stringify({ ok: false, error: msg })}\n`);
+        else
+            io.err(`FAIL: ${msg}\n  hint: run 'yolo deploy validate' for full config diagnostics\n`);
+        return 1;
+    }
+    const config = readResult.config;
+    const det = detectProjectShape({ cwd, config: config ?? null, readFileImpl: deps.readFileImpl });
+    if (!det.ok) {
+        if (jsonOutput)
+            io.out(`${JSON.stringify({ ok: false, error: det.message })}\n`);
+        else
+            io.err(`FAIL: ${det.message}\n`);
+        return 1;
+    }
+    const shape = det.shape;
+    const hasNodejsCompat = (config?.compatibilityFlags ?? []).includes('nodejs_compat');
+    const checks = [];
+    let hardError = false;
+    if (shape.type === 'static') {
+        checks.push({ ok: true, title: 'static site — the workerd runtime contract applies to Workers only' });
+    }
+    else {
+        // Read the entry text (source or prebuilt). A missing SOURCE entry is a hard
+        // error; a missing build OUTPUT is a can't-scan note (build hasn't run yet).
+        const entryAbs = path.resolve(cwd, shape.entry);
+        const kind = statPath(entryAbs);
+        if (kind === 'missing') {
+            // Only a PREBUILT entry is a build OUTPUT that may not exist yet; a SOURCE
+            // entry (src/index.ts) is committed input esbuild bundles in place — the
+            // build doesn't create it — so a missing source entry is a typo, a hard
+            // error, even when a build command is configured (matches `validate`).
+            if (shape.prebuilt === true) {
+                checks.push({ ok: true, title: `entry '${shape.entry}' not built yet — run your build, then re-run doctor` });
+            }
+            else {
+                checks.push({ ok: false, title: `entry '${shape.entry}' does not exist`, detail: 'fix worker.entry in .yolo/deploy.json or create the file' });
+                hardError = true;
+            }
+        }
+        else {
+            const text = readFile(entryAbs);
+            if (text === undefined) {
+                checks.push({ ok: false, title: `entry '${shape.entry}' could not be read`, detail: 'check file permissions' });
+                hardError = true;
+            }
+            else {
+                checks.push({ ok: true, title: `entry '${shape.entry}' resolves` });
+                for (const c of lintWorkerEntry(text, shape.entry, shape.prebuilt === true, hasNodejsCompat))
+                    checks.push(c);
+            }
+        }
+    }
+    const anyWarn = checks.some((c) => !c.ok);
+    if (jsonOutput) {
+        io.out(`${JSON.stringify({ ok: !hardError, hardError, checks, scannedEntryOnly: true })}\n`);
+        return hardError ? 1 : 0;
+    }
+    io.out(`yolo deploy doctor — ${shape.type} project\n`);
+    for (const c of checks) {
+        io.out(`  ${c.ok ? '✓' : '⚠'} ${c.title}\n`);
+        if (c.detail)
+            io.out(`    → ${c.detail}\n`);
+    }
+    if (shape.type === 'worker') {
+        io.out('  note: doctor scans your entry file only — run `yolo deploy --dry-run` to bundle and check dependencies too\n');
+    }
+    io.out(hardError ? '\nFAIL: fix the errors above before shipping\n' : anyWarn ? '\nOK with warnings — review the ⚠ items above\n' : '\nOK: no runtime-contract issues found\n');
+    return hardError ? 1 : 0;
+}
+/** The workerd-runtime-contract checks over one entry file's text. */
+function lintWorkerEntry(text, entry, prebuilt, hasNodejsCompat) {
+    const out = [];
+    // process.env reads other than NODE_ENV — workerd has no runtime process.env.
+    const envNames = new Set();
+    const envRe = /process\.env\.([A-Za-z_][A-Za-z0-9_]*)/g;
+    let m;
+    while ((m = envRe.exec(text)) !== null) {
+        if (m[1] !== 'NODE_ENV')
+            envNames.add(m[1]);
+    }
+    if (envNames.size > 0) {
+        const names = [...envNames].sort();
+        out.push({
+            ok: false,
+            title: `${entry} reads process.env.${names.join(', process.env.')}`,
+            detail: `workerd has no runtime process.env — read these from the env fetch arg (env.${names[0]})`,
+        });
+    }
+    else {
+        out.push({ ok: true, title: 'no process.env reads (other than NODE_ENV)' });
+    }
+    // node: builtins vs nodejs_compat.
+    const builtins = collectNodeBuiltinsFromText(text);
+    if (builtins.length === 0) {
+        out.push({ ok: true, title: 'no node: builtins imported' });
+    }
+    else if (hasNodejsCompat) {
+        out.push({ ok: true, title: `node: builtins (${builtins.join(', ')}) covered by nodejs_compat` });
+    }
+    else {
+        out.push({
+            ok: false,
+            title: `imports node: builtins (${builtins.join(', ')}), deploy.json missing nodejs_compat`,
+            detail: 'add "nodejs_compat" to .yolo/deploy.json compatibilityFlags',
+        });
+    }
+    // require("node:…") — throws in an ESM Worker.
+    if (/\brequire\s*\(\s*['"]node:/.test(text)) {
+        out.push({ ok: false, title: `${entry} uses require() of a node: builtin`, detail: 'use an ESM `import` — require() throws at runtime in an ESM Worker' });
+    }
+    // NODE_ENV pinning. The bundler pins it for a SOURCE entry; a prebuilt bundle
+    // that still references it was not pinned in the framework build.
+    if (prebuilt) {
+        if (text.includes('process.env.NODE_ENV')) {
+            out.push({ ok: false, title: 'prebuilt bundle references an unpinned process.env.NODE_ENV', detail: 'pin NODE_ENV=production in your framework build or it may ship a dev build' });
+        }
+        else {
+            out.push({ ok: true, title: 'NODE_ENV not left unpinned in the prebuilt bundle' });
+        }
+    }
+    else {
+        out.push({ ok: true, title: 'NODE_ENV pinned to production by the bundler' });
+    }
+    return out;
+}
+/** Parse `yolo deploy dev` flags: --port <n>, --host <h>, repeatable --var KEY=VALUE. */
+export function parseDevArgs(args) {
+    let port;
+    let host;
+    const vars = {};
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--port' || a.startsWith('--port=')) {
+            const v = a.includes('=') ? a.slice('--port='.length) : args[++i];
+            const n = Number(v);
+            if (!v || !Number.isInteger(n) || n < 0 || n > 65535)
+                return { ok: false, message: `--port must be an integer 0–65535 (got '${v ?? ''}')` };
+            port = n;
+        }
+        else if (a === '--host' || a.startsWith('--host=')) {
+            const v = a.includes('=') ? a.slice('--host='.length) : args[++i];
+            if (!v || v.startsWith('--'))
+                return { ok: false, message: '--host requires a value' };
+            host = v;
+        }
+        else if (a === '--var' || a.startsWith('--var=')) {
+            const v = a.includes('=') && a.startsWith('--var=') ? a.slice('--var='.length) : args[++i];
+            const eq = v ? v.indexOf('=') : -1;
+            if (!v || eq <= 0)
+                return { ok: false, message: `--var must be KEY=VALUE (got '${v ?? ''}')` };
+            vars[v.slice(0, eq)] = v.slice(eq + 1);
+        }
+        else {
+            return { ok: false, message: `unexpected argument: ${a}` };
+        }
+    }
+    return { ok: true, port, host, vars };
+}
+/**
+ * `yolo deploy dev` — serve the project locally on workerd (miniflare) so the
+ * runtime-contract gotchas surface before a ship. Delegates to
+ * `deploy-dev.ts` (which lazy-imports miniflare). Runs until Ctrl-C.
+ */
+async function runDevCmd(args, deps, io) {
+    const parsed = parseDevArgs(args);
+    if (!parsed.ok) {
+        io.err(`yolo deploy dev: ${parsed.message}\nUsage: yolo deploy dev [--port <n>] [--host <h>] [--var KEY=VALUE ...]\n`);
+        return 64;
+    }
+    const devOpts = {
+        cwd: deps.cwd,
+        io,
+        vars: parsed.vars,
+        ...(parsed.port !== undefined ? { port: parsed.port } : {}),
+        ...(parsed.host !== undefined ? { host: parsed.host } : {}),
+        ...(deps.devDeps ?? {}),
+    };
+    return runDeployDev(devOpts);
+}
 // ─── status ───────────────────────────────────────────────────────────────
 async function runStatusCmd(args, deps, io) {
     const parsed = parseFlagOnlyArgs(args, 'status');
@@ -778,7 +997,16 @@ function formatLogEntry(entry) {
     const ts = str(e.timestamp) ?? str(e.ts) ?? str(e.time);
     const level = str(e.level);
     const message = str(e.message) ?? str(e.msg) ?? JSON.stringify(entry);
-    return [ts ? `[${ts}]` : undefined, level, message].filter(Boolean).join(' ');
+    const head = [ts ? `[${ts}]` : undefined, level, message].filter(Boolean).join(' ');
+    // Surface the (CF-symbolicated) exception stack indented under the message —
+    // this is what turns an opaque 1101 into a real source-mapped trace.
+    const stack = str(e.stack);
+    if (stack) {
+        const errName = str(e.errorName);
+        const lines = stack.split(/\r?\n/).map((l) => `    ${l.trim()}`).filter((l) => l.trim());
+        return [head, errName ? `  ${errName}` : undefined, ...lines].filter(Boolean).join('\n');
+    }
+    return head;
 }
 export function parseRollbackArgs(args) {
     let releaseId;

package/dist/deploy-client.js

@@ -92,7 +92,7 @@ export async function uploadAssetBucket(ctx, projectId, shipId, files) {
  *   success | 409 awaiting-approval (T3 prod gate — NOT an error)
  *           | 410 upload-expired (ship session lapsed → rerun)
  */
-export async function finalizeShip(ctx, projectId, shipId, modules = []) {
+export async function finalizeShip(ctx, projectId, shipId, modules = [], sourceMap) {
     // NOT auto-retried (unlike ship/start + assets). finalize is single-shot per
     // ship session: if the first request reached the server and created the
     // release but the response was lost to a transient 5xx/522, a blind retry
@@ -114,6 +114,11 @@ export async function finalizeShip(ctx, projectId, shipId, modules = []) {
             for (const module of modules) {
                 form.append(module.name, new Blob([module.contents], { type: 'application/javascript+module' }), module.name);
             }
+            // Sourcemap sidecar — the server distinguishes it from modules by the
+            // `application/source-map` content-type (never a worker module / digest input).
+            if (sourceMap) {
+                form.append(sourceMap.name, new Blob([sourceMap.content], { type: 'application/source-map' }), sourceMap.name);
+            }
             // No explicit Content-Type — fetch sets the multipart boundary itself.
             response = await fetchImpl(url, {
                 method: 'POST',

package/dist/deploy-dev.js

@@ -0,0 +1,215 @@
+/**
+ * `yolo deploy dev` — run the project locally on the SAME runtime it deploys to
+ * (Cloudflare workerd, via miniflare) so the workerd-contract gotchas
+ * (`process.env`, `node:` builtins, `WeakRef`/`FinalizationRegistry`, an
+ * unpinned dev-React build) surface locally instead of only after a ship. A
+ * plain `node dist/server.js` runs on Node and gives false confidence — see the
+ * Runtime Contract doc.
+ *
+ * The worker is bundled with the SAME `bundleProject` recipe `yolo deploy` uses
+ * (so the NODE_ENV pin + node: handling match prod), and served under the SAME
+ * pinned compatibility date the hosting service uses. Static projects are served
+ * through the identical assets-only shim the server attaches in prod.
+ *
+ * miniflare is a heavy (workerd-carrying) dependency, so it's dynamically
+ * imported ONLY here — no other `yolo` verb pays for it.
+ */
+import { copyFileSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { bundleProject } from './deploy-bundle.js';
+import { readDeployConfig } from './deploy-config.js';
+import { detectProjectShape } from './deploy-detect.js';
+import { defaultRunBuild } from './deploy-ship.js';
+/**
+ * The compatibility date the hosting runtime pins
+ * (`common-api/.../release-service.ts` COMPATIBILITY_DATE). Dev MUST match it so
+ * a feature that works locally works in prod and vice-versa.
+ */
+export const DEV_COMPATIBILITY_DATE = '2024-12-01';
+/** The assets-only shim the SERVER attaches for a pure-static project (kept in lockstep). */
+const STATIC_DEV_SHIM = `export default { async fetch(request, env) { return env.ASSETS.fetch(request); } };`;
+/**
+ * Map deploy.json + the bundled module text + an already-STAGED assets dir onto
+ * miniflare options. Pure — the whole config→runtime translation is unit-tested
+ * here without starting workerd. Local KV/D1/R2 are declared (in-memory) so a
+ * worker that reads `env.<NAME>` doesn't crash; they hold no real data.
+ *
+ * `stagedAssetsDir` MUST be a dir holding only the prod-shipped asset set (see
+ * stageProdAssets) — never the raw project dir, which would expose dotfiles
+ * (`.env`), `node_modules`, and escaped symlinks that prod excludes.
+ */
+export function buildMiniflareInit(params) {
+    const { config, script, port, host, vars, stagedAssetsDir } = params;
+    const bindings = config?.bindings ?? [];
+    const byKind = (kind) => bindings.filter((b) => b.kind === kind).map((b) => b.binding).filter((n) => typeof n === 'string');
+    return {
+        port,
+        host,
+        script,
+        modules: true,
+        compatibilityDate: DEV_COMPATIBILITY_DATE,
+        compatibilityFlags: config?.compatibilityFlags ?? [],
+        bindings: { ...vars },
+        kvNamespaces: byKind('kv'),
+        d1Databases: byKind('d1'),
+        r2Buckets: byKind('r2'),
+        ...(stagedAssetsDir ? { assets: { directory: stagedAssetsDir, binding: 'ASSETS' } } : {}),
+    };
+}
+/**
+ * Copy the bundle's ALREADY-FILTERED asset set (bundleProject applies the prod
+ * exclusion rules: dotfiles, node_modules, escaping symlinks) into a fresh temp
+ * dir laid out by manifest path, so miniflare serves exactly what prod would —
+ * not the raw project dir.
+ *
+ * Returns null for an empty asset set UNLESS `alwaysDir` — a static project's
+ * shim unconditionally calls `env.ASSETS.fetch`, so an empty static site still
+ * needs an ASSETS binding (an empty dir → faithful 404s) rather than a runtime
+ * "ASSETS is undefined" throw on every request.
+ */
+export function stageProdAssets(assets, alwaysDir = false) {
+    if (assets.length === 0 && !alwaysDir)
+        return null;
+    const dir = mkdtempSync(path.join(os.tmpdir(), 'yolo-dev-assets-'));
+    for (const a of assets) {
+        const dest = path.join(dir, a.path); // a.path is a URL-style '/index.html'
+        mkdirSync(path.dirname(dest), { recursive: true });
+        copyFileSync(a.absPath, dest);
+    }
+    return dir;
+}
+/** Default server start — lazy-imports miniflare so no other verb loads workerd. */
+async function startWithMiniflare(init) {
+    let Miniflare;
+    try {
+        ({ Miniflare } = await import('miniflare'));
+    }
+    catch {
+        throw new Error("`yolo deploy dev` needs the 'miniflare' package (it carries the workerd runtime). Install it with `npm i miniflare`.");
+    }
+    const mf = new Miniflare(init);
+    const url = (await mf.ready).toString();
+    return { url, dispose: () => mf.dispose() };
+}
+/** Block until SIGINT/SIGTERM. */
+function waitForSigint() {
+    return new Promise((resolve) => {
+        const stop = () => resolve();
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+    });
+}
+/**
+ * Orchestrate a local dev run: resolve shape → bundle (worker) or shim (static)
+ * → assemble options → serve until stopped. Exit 0 on a clean stop, 1 on a
+ * bundle/config failure.
+ */
+export async function runDeployDev(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const io = opts.io;
+    const readConfig = opts.readDeployConfigImpl ?? readDeployConfig;
+    const detect = opts.detectProjectShapeImpl ?? detectProjectShape;
+    const bundle = opts.bundleProjectImpl ?? bundleProject;
+    const runBuild = opts.runBuildImpl ?? defaultRunBuild;
+    const stageAssets = opts.stageAssetsImpl ?? stageProdAssets;
+    const start = opts.startImpl ?? startWithMiniflare;
+    const waitForStop = opts.waitForStopImpl ?? waitForSigint;
+    const port = opts.port ?? 8787;
+    const host = opts.host ?? '127.0.0.1';
+    const readResult = readConfig(cwd);
+    if (!readResult.ok) {
+        io.err(`FAIL: ${readResult.message}\n  hint: run 'yolo deploy validate' for full config diagnostics\n`);
+        return 1;
+    }
+    const config = readResult.config;
+    const det = detect({ cwd, config: config ?? null });
+    if (!det.ok) {
+        io.err(`FAIL: ${det.message}\n`);
+        return 1;
+    }
+    const shape = det.shape;
+    // Build first — a static/prebuilt project serves its build OUTPUT, so a clean
+    // checkout would otherwise miss (or serve stale) files. Mirrors the ship path.
+    if (shape.buildCommand) {
+        io.out(`building: ${shape.buildCommand}\n`);
+        const built = await runBuild(shape.buildCommand, cwd, (chunk) => {
+            for (const line of chunk.split(/\r?\n/))
+                if (line.trim())
+                    io.err(`build> ${line}\n`);
+        });
+        if (built.code !== 0) {
+            io.err(`FAIL: build command \`${shape.buildCommand}\` exited with code ${built.code}\n`);
+            return 1;
+        }
+    }
+    // Bundle (both static + worker): this walks the assets dir with the SAME prod
+    // exclusion rules (dotfiles, node_modules, escaping symlinks) and, for a
+    // worker, produces the module. We serve the STAGED filtered set — never the
+    // raw dir — so dev can't expose files prod wouldn't.
+    const bundled = await bundle(shape, cwd, undefined, { compatibilityFlags: config?.compatibilityFlags });
+    if (!bundled.ok) {
+        io.err(`FAIL: ${bundled.message}${bundled.hint ? `\n  hint: ${bundled.hint}` : ''}\n`);
+        return 1;
+    }
+    for (const w of bundled.warnings)
+        io.err(`warn: ${w}\n`);
+    let script;
+    if (shape.type === 'worker') {
+        if (!bundled.module) {
+            io.err('FAIL: worker produced no module to run\n');
+            return 1;
+        }
+        script = Buffer.from(bundled.module.contents).toString('utf8');
+    }
+    else {
+        script = STATIC_DEV_SHIM;
+    }
+    // Static projects always need an ASSETS binding (the shim calls it), even when
+    // the output dir is empty — stage an empty dir in that case.
+    const stagedAssetsDir = stageAssets(bundled.assets, shape.type === 'static');
+    const cleanup = () => {
+        if (stagedAssetsDir) {
+            try {
+                rmSync(stagedAssetsDir, { recursive: true, force: true });
+            }
+            catch {
+                /* best-effort temp cleanup */
+            }
+        }
+    };
+    const init = buildMiniflareInit({ config, script, port, host, vars: opts.vars ?? {}, stagedAssetsDir });
+    let server;
+    try {
+        server = await start(init);
+    }
+    catch (err) {
+        io.err(`FAIL: ${err instanceof Error ? err.message : String(err)}\n`);
+        cleanup();
+        return 1;
+    }
+    io.out(`yolo deploy dev — serving ${shape.type} on ${server.url} (workerd, compat ${DEV_COMPATIBILITY_DATE})\n`);
+    if (Object.keys(init.bindings).length === 0) {
+        io.out('  note: no local vars set — real env vars/secrets are server-side; pass `--var KEY=VALUE` for local values\n');
+    }
+    io.out('  press Ctrl-C to stop\n');
+    try {
+        await waitForStop();
+    }
+    finally {
+        // A dispose failure at shutdown is best-effort — warn, don't turn a clean
+        // Ctrl-C into a crash — and the inner finally guarantees the staged-asset
+        // cleanup runs regardless.
+        try {
+            await server.dispose();
+        }
+        catch (err) {
+            io.err(`warn: dev server dispose failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+        finally {
+            cleanup();
+        }
+    }
+    io.out('\ndev server stopped\n');
+    return 0;
+}

package/dist/deploy-ship.js

@@ -76,7 +76,12 @@ export async function runDeployShip(options) {
         progress(`deploy: build \`${shape.buildCommand}\` ... ok (${((Date.now() - startedAt) / 1000).toFixed(1)}s)`);
     }
     // 4. Bundle — all size/count ceilings fire locally in here, pre-network.
-    const bundled = await bundle(shape, cwd);
+    //    Request a sourcemap so CF can symbolicate exception stacks in deploy.logs
+    //    (the .map ships as a sidecar, out of the module + the digest).
+    const bundled = await bundle(shape, cwd, undefined, {
+        compatibilityFlags: config.compatibilityFlags,
+        sourcemaps: true,
+    });
     if (!bundled.ok) {
         return { ok: false, kind: bundled.kind, message: bundled.message, hint: bundled.hint, detail: bundled.detail };
     }
@@ -159,8 +164,9 @@ export async function runDeployShip(options) {
             progress(`deploy: assets ${i + 1}/${buckets.length} buckets ok (${formatMiB(uploadedBytes)})`);
         }
     }
-    // 8. Finalize — worker modules multipart / empty JSON for pure-static.
-    const finalized = await finalizeLeg(ctx, projectId, shipId, workerModules);
+    // 8. Finalize — worker modules multipart / empty JSON for pure-static. The
+    //    sourcemap sidecar rides alongside the modules (out of the digest).
+    const finalized = await finalizeLeg(ctx, projectId, shipId, workerModules, bundled.sourceMap);
     if (!finalized.ok) {
         if (finalized.kind === 'awaiting-approval' && 'approvalId' in finalized) {
             progress('deploy: finalize → pending operator approval (T3 prod ship)');
@@ -325,7 +331,7 @@ export function shortDigest(digest) {
 function describeError(err) {
     return err instanceof Error ? err.message : String(err);
 }
-function defaultRunBuild(command, cwd, onOutput) {
+export function defaultRunBuild(command, cwd, onOutput) {
     return new Promise((resolve) => {
         const child = spawn(command, { cwd, shell: true, stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
         child.stdout?.on('data', (data) => onOutput(String(data)));

package/dist/tileapp-validator.js

@@ -49,7 +49,11 @@ export function parsePermissionShape(raw) {
                 return null; // arg = McpScope (membership checked server-side)
             return { raw, namespace: 'mcp', arg };
         case 'llm':
-            if (action !== 'invoke' || !arg)
+            // llm.invoke — provider-agnostic (the router picks the model). A legacy
+            // `llm.invoke:<provider>` still parses; the provider is advisory only. Head
+            // must be EXACTLY `llm.invoke`: bare is valid, but `llm.invoke:` and extra
+            // segments `llm.invoke.foo` are rejected.
+            if (head !== 'llm.invoke' || arg === '')
                 return null;
             return { raw, namespace: 'llm', action, arg };
         case 'media':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yolo-labs/yolo-cli",
-  "version": "0.24.0",
+  "version": "0.30.0",
   "description": "YOLO Studio substrate CLI — owns yolo plan/workspace/artifact substrate-tooling commands. Distinct from yolo-code (the agent CLI) and yolo-router (the LLM gateway client).",
   "license": "MIT",
   "type": "module",
@@ -29,7 +29,8 @@
   "dependencies": {
     "ajv": "^6.12.6",
     "esbuild": "^0.24.0",
-    "js-yaml": "^4.1.0"
+    "js-yaml": "^4.1.0",
+    "miniflare": "^3.20250718.3"
   },
   "devDependencies": {
     "typescript": "^5.4.0",