@delegance/claude-autopilot 7.6.0 → 7.8.0

package/CHANGELOG.md

@@ -2,6 +2,107 @@
 
 - v5.6 Phase 7 (docs reconciliation) — pending.
 
+## 7.8.0 — 2026-05-11
+
+### Changed
+- `tsx` resolution now prefers project-local installation, then `tsx` on
+  `$PATH`, then the bundled copy. The bundled `tsx` is scheduled for removal
+  in v8.0.0 — a once-per-day deprecation warning surfaces when falling back
+  to the bundled copy. Silence with `CLAUDE_AUTOPILOT_NO_TSX_DEPRECATION=1`.
+  Override resolution source with `CLAUDE_AUTOPILOT_TSX=bundled|project|path`
+  or the new `--tsx-source` CLI flag.
+- `@supabase/supabase-js` is now lazy-loaded only when invoking
+  `claude-autopilot dashboard upload`. Moved from `dependencies` to
+  `optionalDependencies` — default install footprint is unchanged in npm 10
+  (which installs optional deps), but `npm install --omit=optional` now
+  works for local-only usage. A new `omit-optional-smoke.yml` CI workflow
+  exercises this install path on every PR. **The `--omit=optional` guarantee
+  is verified for npm only**; pnpm/yarn behavior is best-effort and not
+  gated in CI for v7.8.0 (per spec amendment A8).
+
+### Removed (from published tarball)
+- `tests/snapshots/`, `scripts/snapshots/`, `scripts/autoregress.ts` —
+  dev-only. The `autoregress` CLI verb continues to work from the repo
+  itself, but the snapshot fixtures are no longer shipped to npm consumers.
+
+Published tarball file count drops by ~15 files (the snapshot fixtures and
+the autoregress harness); runtime behavior is unchanged for default local-only
+usage except for the bundled `tsx` deprecation warning.
+
+### Added
+- `--tsx-source <bundled|project|path>` CLI flag and `CLAUDE_AUTOPILOT_TSX`
+  env var for explicit resolution overrides (escape-hatch for users whose
+  project-local tsx is broken / incompatible).
+- `CLAUDE_AUTOPILOT_NO_TSX_DEPRECATION=1` env opt-out for the deprecation
+  warning (CI / log-hygiene).
+- `XDG_STATE_HOME` + `CLAUDE_AUTOPILOT_STATE_DIR` support for the warning
+  dedup state file (defaults to `~/.claude-autopilot/`).
+- `scripts/audit-supabase-imports.ts` — AST-based audit (TypeScript compiler
+  API) that fails CI if a static value-import of `@supabase/supabase-js`
+  appears outside `src/cli/dashboard/**`. Runs via `npm run audit:supabase`.
+- `.github/workflows/omit-optional-smoke.yml` — install-and-probe smoke
+  test for the `npm install --omit=optional` install path.
+- `src/cli/tsx-resolver.ts` + `src/cli/dashboard/missing-package.ts` (new
+  modules, fully unit-tested — see `tests/cli/tsx-resolver.test.ts`,
+  `tests/cli/dashboard/missing-package.test.ts`, and
+  `tests/cli/tsx-source-flag.test.ts`).
+
+### Spec
+- `docs/specs/v7.8.0-decouple-runtime-deps.md` — full spec with two folded
+  codex reviews (pass-1 portability + escape hatch; pass-2 amendments
+  A1-A8 covering ESM/CJS safety, CLI parser scope, PATH self-pointer,
+  AST audit, type-only imports, hand-rolled PATH lookup dropping the
+  `which` dep, XDG state dir, npm-only --omit=optional documentation).
+
+## 7.7.0 (2026-05-11)
+
+**v7.7.0 — Rust scaffold support.** Minor release. Promotes Rust from
+"detected-but-unsupported" (exit 3 in v7.4–v7.6) to a first-class
+scaffold target, matching the Node + Python + FastAPI + Go shape.
+
+**New:** `claude-autopilot scaffold --from-spec <spec.md> --stack rust`
+(or auto-detected when the spec's `## Files` section lists `Cargo.toml`,
+`src/main.rs`, or `src/lib.rs`).
+
+**Lib-vs-bin fork.** Rust adds a fork the Go scaffolder doesn't need:
+
+- spec lists ONLY `src/lib.rs` (no main.rs) → **library crate**
+  (`src/lib.rs` with a public `hello()` + inline `#[cfg(test)] mod tests`,
+  Cargo.lock added to `.gitignore`)
+- spec lists `src/main.rs` (with or without lib.rs) → **binary crate**
+  (`src/main.rs` with `println!` + `tests/integration_test.rs` smoke
+  test, Cargo.lock NOT in `.gitignore`)
+- spec lists BOTH → **mixed mode** (both targets generated; Cargo.lock
+  excluded since the binary target wins per Cargo's documented convention)
+- spec hints neither → defaults to binary (matches `cargo init` default)
+
+**Cargo.lock heuristic.** Library-only crates omit `Cargo.lock` from the
+commit per Cargo docs; binary + mixed crates commit it. The Rust
+scaffolder's `.gitignore` augmentation reflects this — `target/` is
+always added; `Cargo.lock` is added only when the spec resolves to
+library-only.
+
+**Crate name normalization.** Cargo identifiers are `[a-z0-9_]` only and
+must not start with a digit. The scaffolder lowercases `basename(cwd)`,
+replaces any non-allowed char with `_`, collapses underscore runs, and
+prefixes `_` when the result starts with a digit. Examples: `my-pkg-2`
+→ `my_pkg_2`, `2cool` → `_2cool`, `My App` → `my_app`, `foo.bar` →
+`foo_bar`.
+
+**Never overwrites.** `Cargo.toml`, `src/main.rs`, `src/lib.rs`, and
+`tests/integration_test.rs` are preserved if they already exist — matches
+the Go + Python scaffolder pattern.
+
+**Polyglot detection.** `detectStack()` now includes Rust signals
+(`Cargo.toml` / `src/main.rs` / `src/lib.rs`) in the polyglot count. So
+e.g. `package.json` + `Cargo.toml` together correctly fail-loud with
+`polyglot spec — pass --stack to disambiguate` instead of silently
+picking one.
+
+**`--list-stacks`** now shows Rust under Supported and drops it from
+Recognized-but-unsupported. Ruby remains the lone detection-only stack
+(would detect via `Gemfile`).
+
 ## 7.6.0 (2026-05-10)
 
 **v7.6.0 — Go scaffold support.** Minor release. Promotes Go from

package/README.md

@@ -407,6 +407,25 @@ ANTHROPIC_API_KEY=sk-ant-... claude-autopilot scan --all
 
 We do not claim 13/13 reflects every real-world repo — it's a reproducible upper bound on a fixture that exercises the categories we explicitly target.
 
+## What's Next (v8.0.0)
+
+v7.8.0 begins decoupling runtime deps so local-only users can install a
+leaner package:
+
+- **`tsx` is being removed from `dependencies` in v8.0.0.** Today it ships
+  bundled and the launcher prefers a project-local install if you have one,
+  falling back to the bundled copy with a once-per-day deprecation warning.
+  In v8.0.0 the bundled fallback goes away — install `tsx` locally
+  (`npm install -D tsx`) or set `CLAUDE_AUTOPILOT_TSX=path` to use a global
+  install.
+- **The hosted-dashboard upload is moving to a separate optional package
+  (`@delegance/claude-autopilot-cloud`)** so you can skip Supabase entirely
+  with `npm install --omit=optional` today, and skip the dep entirely with
+  v8.0.0. The smoke workflow `.github/workflows/omit-optional-smoke.yml`
+  verifies the install-with-omit path on every PR.
+
+Track the v8.0.0 plan and request comments at https://github.com/axledbetter/claude-autopilot/issues
+
 ## Contributing
 
 Issues and PRs welcome — https://github.com/axledbetter/claude-autopilot/issues. The pipeline literally builds itself; many features in this repo were implemented by autopilot running against autopilot ([DEMO.md](DEMO.md) walks through six self-eat PRs with cost trajectory $10 → ~$2.50). Read [CONTRIBUTING.md](CONTRIBUTING.md) if it exists, otherwise: clone, `npm install`, `npm test`, open a PR.

package/bin/_launcher.js

@@ -23,12 +23,308 @@ function resolveEntry() {
   return null;
 }
 
+// v7.8.0 — three-tier tsx resolution (project-local → PATH → bundled) with
+// a once-per-day deprecation warning on the bundled fallthrough. This is a
+// JS port of src/cli/tsx-resolver.ts (which remains the testable source of
+// truth used by autoregress, --tsx-source flag handling, and other call
+// sites). The launcher can't import the TS resolver directly because it
+// runs BEFORE tsx is available, so the two implementations are kept in
+// sync by hand. See docs/specs/v7.8.0-decouple-runtime-deps.md.
+//
+// Escape hatches:
+//   --tsx-source=<bundled|project|path>     (parsed from argv, then stripped)
+//   CLAUDE_AUTOPILOT_TSX=<bundled|project|path>
+//   CLAUDE_AUTOPILOT_NO_TSX_DEPRECATION=1   (silences bundled-fallthrough warning)
+const TSX_VALID_SOURCES = ['bundled', 'project', 'path'];
+
+function readTsxFlagOverride(argv) {
+  // Find --tsx-source=foo or --tsx-source foo without disturbing other argv
+  // (we surface "invalid value" diagnostics from the CLI's own arg parser
+  // when it sees the still-present flag — only strip and use it here).
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (!a) continue;
+    if (a.startsWith('--tsx-source=')) {
+      const v = a.slice('--tsx-source='.length);
+      return TSX_VALID_SOURCES.includes(v) ? v : null;
+    }
+    if (a === '--tsx-source' && i + 1 < argv.length) {
+      const v = argv[i + 1];
+      return TSX_VALID_SOURCES.includes(v) ? v : null;
+    }
+  }
+  return null;
+}
+
+function bundledTsxPath() {
+  // Our own bundled tsx — relative to the package root (two levels up from bin/).
+  const p = path.resolve(__dirname, '..', 'node_modules', '.bin', 'tsx');
+  return fs.existsSync(p) ? p : null;
+}
+function projectLocalTsxPath() {
+  // Consumer project — when installed as a dep, npm hoists peer bins to
+  // <consumer>/node_modules/.bin/tsx. ONLY classify as project-local if
+  // the consumer EXPLICITLY declared tsx in their package.json. Without
+  // this gate, npm's hoisting of our own bundled tsx would be mislabeled
+  // as project-local, suppressing the deprecation warning that drives
+  // the v8.0.0 migration.
+  //
+  // Layout when installed as a dep:
+  //   <consumer>/package.json
+  //   <consumer>/node_modules/@delegance/claude-autopilot/bin/_launcher.js   <-- __dirname/..
+  //   <consumer>/node_modules/.bin/tsx
+  // So the consumer package root is four dirs up from bin/.
+  const consumerPkgRoot = path.resolve(__dirname, '..', '..', '..', '..');
+  if (!consumerDeclaresTsx(consumerPkgRoot)) return null;
+  const p = path.resolve(__dirname, '..', '..', '..', '.bin', 'tsx');
+  return fs.existsSync(p) ? p : null;
+}
+
+/**
+ * True iff the consumer's `package.json` declares `tsx` in dependencies,
+ * devDependencies, or peerDependencies. Mirrors the TS resolver's
+ * `consumerDeclaresTsx` — see src/cli/tsx-resolver.ts. Missing or
+ * malformed package.json → false (conservative: better to fall through
+ * to PATH/bundled than to mislabel hoisted deps as project-local).
+ */
+function consumerDeclaresTsx(consumerPkgRoot) {
+  try {
+    const pkgPath = path.join(consumerPkgRoot, 'package.json');
+    const raw = fs.readFileSync(pkgPath, 'utf8');
+    const pkg = JSON.parse(raw);
+    const dd = (pkg && pkg.dependencies) || {};
+    const ddv = (pkg && pkg.devDependencies) || {};
+    const pd = (pkg && pkg.peerDependencies) || {};
+    return 'tsx' in dd || 'tsx' in ddv || 'tsx' in pd;
+  } catch {
+    return false;
+  }
+}
+function pathTsxPath() {
+  const PATH = process.env.PATH || process.env.Path || '';
+  if (!PATH) return null;
+  const isWin = process.platform === 'win32';
+  const sep = isWin ? ';' : ':';
+  const exts = isWin ? (process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';') : [''];
+  const bundled = bundledTsxPath();
+  for (const dir of PATH.split(sep)) {
+    if (!dir) continue;
+    // Windows NTFS is case-insensitive — `tsx.cmd`, `TSX.CMD`, `Tsx.Cmd` all
+    // resolve to the same file. Use a case-insensitive readdir match instead
+    // of existsSync(tsx + ext), which mismatches when on-disk filename casing
+    // differs from PATHEXT casing.
+    const cand = isWin
+      ? findTsxCaseInsensitive(dir, exts)
+      : (() => {
+          const c = path.join(dir, 'tsx');
+          return fs.existsSync(c) ? c : null;
+        })();
+    if (!cand) continue;
+    // A3 self-pointer: if PATH-resolved bin's package root is OUR own
+    // bundled tsx package root, skip this candidate and keep searching.
+    // npm prepends `node_modules/.bin` to PATH for `npm run`, so the
+    // bundled-pointing entry is typically hit first. `return null` here
+    // would abort the whole PATH search and hide a user's globally-
+    // installed tsx later in PATH. `continue` instead — if no other PATH
+    // entry hits, the loop falls off the end and the caller falls
+    // through to bundled with the deprecation warning.
+    if (isInBundledPackage(cand, bundled)) {
+      continue;
+    }
+    // On Windows, `.cmd`/`.bat` shims can't be executed directly by
+    // spawn() — callers must pass `shell: true`. Mark the resolution
+    // with the metadata they need.
+    if (isWin && /\.(cmd|bat)$/i.test(cand)) {
+      return { path: cand, shell: true };
+    }
+    return cand;
+  }
+  return null;
+}
+
+/**
+ * Case-insensitive lookup for `tsx` + each PATHEXT entry inside `dir`.
+ * Mirrors src/cli/tsx-resolver.ts findTsxCaseInsensitive(). Returns the
+ * actual on-disk filename joined onto `dir`, or null if no match.
+ */
+function findTsxCaseInsensitive(dir, exts) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return null;
+  }
+  const wanted = new Set(exts.map((ext) => `tsx${ext}`.toLowerCase()));
+  for (const entry of entries) {
+    if (wanted.has(entry.toLowerCase())) {
+      return path.join(dir, entry);
+    }
+  }
+  return null;
+}
+
+/**
+ * True iff `candidatePath` resolves into our bundled tsx package directory
+ * (after realpath). `bundled` is the path to our own `node_modules/.bin/tsx`
+ * (or null if it can't be located). We compare PACKAGE ROOTS — `node_modules/
+ * tsx/` — not bin dirs, since `.bin/tsx` and `tsx/dist/cli.mjs` live in
+ * different directories.
+ */
+function isInBundledPackage(candidatePath, bundled) {
+  if (!bundled) return false;
+  try {
+    const realCandidate = fs.realpathSync(candidatePath);
+    const realBundled = fs.realpathSync(bundled);
+    // realBundled now points at the real tsx entry (e.g. .../node_modules/
+    // tsx/dist/cli.mjs on Unix, or remains the .cmd shim on Windows). Walk
+    // up to the tsx package root.
+    const bundledPkgRoot = packageRootContaining(realBundled);
+    if (!bundledPkgRoot) return false;
+    return realCandidate.startsWith(bundledPkgRoot + path.sep) || realCandidate === bundledPkgRoot;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Walk upward from a file path looking for `node_modules/tsx`. Returns the
+ * absolute path to the tsx package root, or null if not found within 5 levels.
+ *
+ * PARITY: keep in sync with src/cli/tsx-resolver.ts packageRootContaining().
+ * The TS version is parameterized over `pkgName`; this launcher copy is
+ * specialized to `tsx` since the launcher only resolves tsx.
+ */
+function packageRootContaining(filePath) {
+  let dir = path.dirname(filePath);
+  for (let i = 0; i < 6; i += 1) {
+    const base = path.basename(dir);
+    if (base === 'tsx' && path.basename(path.dirname(dir)) === 'node_modules') {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+function stateDir() {
+  if (process.env.CLAUDE_AUTOPILOT_STATE_DIR) return process.env.CLAUDE_AUTOPILOT_STATE_DIR;
+  if (process.platform !== 'win32' && process.env.XDG_STATE_HOME) {
+    return path.join(process.env.XDG_STATE_HOME, 'claude-autopilot');
+  }
+  return path.join(os.homedir(), '.claude-autopilot');
+}
+
+const TSX_DEPRECATION_MESSAGE =
+  '\n' +
+  '[deprecation] @delegance/claude-autopilot is using its bundled `tsx` to run\n' +
+  '              your TypeScript scripts. In v8.0.0, `tsx` will be removed from\n' +
+  '              runtime deps and you will need to install it yourself:\n' +
+  '\n' +
+  '                  npm install -D tsx\n' +
+  '\n' +
+  '              To silence this warning now and prepare for v8.0.0:\n' +
+  '                1. Add `tsx` to your project devDependencies, OR\n' +
+  '                2. Set `CLAUDE_AUTOPILOT_NO_TSX_DEPRECATION=1` in your env.\n' +
+  '\n' +
+  '              Override resolution: `CLAUDE_AUTOPILOT_TSX=bundled|project|path`\n' +
+  '              See docs/specs/v7.8.0-decouple-runtime-deps.md for details.\n';
+
+function emitTsxDeprecationWarningSafe() {
+  if (process.env.CLAUDE_AUTOPILOT_NO_TSX_DEPRECATION === '1') return;
+  const today = new Date().toISOString().slice(0, 10);
+  const dedupPath = path.join(stateDir(), '.tsx-deprecation-shown');
+  try {
+    if (fs.existsSync(dedupPath)) {
+      const lastShown = fs.readFileSync(dedupPath, 'utf8').trim();
+      if (lastShown === today) return;
+    }
+  } catch { /* unreadable — fall through and print */ }
+  try {
+    fs.mkdirSync(path.dirname(dedupPath), { recursive: true });
+    fs.writeFileSync(dedupPath, today);
+  } catch { /* non-fatal */ }
+  process.stderr.write(TSX_DEPRECATION_MESSAGE);
+}
+
+/**
+ * Resolve a tsx executable using the v7.8.0 precedence ladder. Returns
+ * `{path, shell?}`. Honors --tsx-source / CLAUDE_AUTOPILOT_TSX overrides,
+ * with --tsx-source taking priority. On bundled fallthrough (no override),
+ * emits the once-per-day deprecation warning unless silenced.
+ *
+ * Forced overrides MUST fail fast: if the user explicitly asked for a
+ * source and it can't be resolved, exit 2 with an actionable stderr message.
+ * Silently falling back to a global `tsx` was a footgun — the user has no
+ * indication their override was ignored.
+ */
 function findTsx() {
-  const own = path.resolve(__dirname, '..', 'node_modules', '.bin', 'tsx');
-  if (fs.existsSync(own)) return own;
-  const consumer = path.resolve(__dirname, '..', '..', '..', '.bin', 'tsx');
-  if (fs.existsSync(consumer)) return consumer;
-  return 'tsx';
+  const flagOverride = readTsxFlagOverride(process.argv.slice(2));
+  const envOverride = process.env.CLAUDE_AUTOPILOT_TSX;
+  const override = flagOverride
+    || (TSX_VALID_SOURCES.includes(envOverride) ? envOverride : null);
+  const forcedBy = flagOverride ? '--tsx-source' : (override ? 'CLAUDE_AUTOPILOT_TSX' : null);
+
+  if (override === 'project') {
+    const p = projectLocalTsxPath();
+    if (!p) {
+      process.stderr.write(
+        `[claude-autopilot] Error: ${forcedBy}=project requested but no project-local tsx found.\n` +
+        '  Install tsx in your project: npm install -D tsx\n' +
+        '  Or unset the override.\n',
+      );
+      process.exit(2);
+    }
+    return toResolution(p);
+  }
+  if (override === 'path') {
+    const p = pathTsxPath();
+    if (!p) {
+      process.stderr.write(
+        `[claude-autopilot] Error: ${forcedBy}=path requested but no tsx found on PATH.\n` +
+        '  Install tsx globally (npm install -g tsx) or unset the override.\n',
+      );
+      process.exit(2);
+    }
+    return toResolution(p);
+  }
+  if (override === 'bundled') {
+    const p = bundledTsxPath();
+    if (!p) {
+      process.stderr.write(
+        `[claude-autopilot] Error: ${forcedBy}=bundled requested but the bundled tsx is missing.\n` +
+        '  Reinstall @delegance/claude-autopilot or unset the override.\n',
+      );
+      process.exit(2);
+    }
+    return toResolution(p);
+  }
+
+  // Default precedence: project → PATH → bundled (with deprecation warning).
+  const project = projectLocalTsxPath();
+  if (project) return toResolution(project);
+  const fromPath = pathTsxPath();
+  if (fromPath) return toResolution(fromPath);
+  emitTsxDeprecationWarningSafe();
+  const bundled = bundledTsxPath();
+  if (!bundled) {
+    process.stderr.write(
+      '[claude-autopilot] Error: bundled tsx is missing — reinstall @delegance/claude-autopilot.\n',
+    );
+    process.exit(2);
+  }
+  return toResolution(bundled);
+}
+
+/**
+ * Normalize the result of a tsx-path lookup into a `{path, shell?}`
+ * resolution. `pathTsxPath()` may return either a string or an object with
+ * `{path, shell}` for `.cmd`/`.bat` shims that require `shell: true`.
+ */
+function toResolution(value) {
+  if (typeof value === 'string') return { path: value };
+  return value;
 }
 
 // v7.1.7 — Per-calendar-day deprecation dedup, keyed in the user's home dir.
@@ -118,7 +414,15 @@ export function launch(opts) {
   } else {
     // Dev path — run source via tsx. Used from the repo itself, or by users who
     // installed from git or linked a local copy.
-    result = spawnSync(findTsx(), [entry.path, ...process.argv.slice(2)], { stdio: 'inherit' });
+    //
+    // On Windows, PATH-resolved `.cmd`/`.bat` shims must be spawned with
+    // `shell: true` — Node's exec syscalls can't launch them directly.
+    // Bundled / project-local hits run as bare JS via node and don't need
+    // a shell. The resolver tells us which mode to use.
+    const tsx = findTsx();
+    const spawnOpts = { stdio: 'inherit' };
+    if (tsx.shell) spawnOpts.shell = true;
+    result = spawnSync(tsx.path, [entry.path, ...process.argv.slice(2)], spawnOpts);
   }
 
   if (result.error) {

package/dist/src/cli/dashboard/missing-package.d.ts

@@ -0,0 +1,48 @@
+export interface MissingPackageOpts {
+    /**
+     * Whether to also match CommonJS-style `Cannot find module '<pkg>'`
+     * messages in addition to the ESM-style `Cannot find package '<pkg>'`.
+     *
+     * Default **true**. Node's error format depends on the loader path
+     * (ESM vs CJS) — `import()` of a missing package can surface either
+     * depending on the consumer's module type and how the dep is loaded
+     * by the runtime. Accepting both is the safer default for our
+     * install-hint surface: a false negative here means the user sees a
+     * raw `ERR_MODULE_NOT_FOUND` instead of the actionable hint.
+     *
+     * Set to `false` to require ESM form specifically (used by the
+     * standalone `extractMissingSpecifier` helper in some tests).
+     */
+    acceptCjsForm?: boolean;
+}
+/**
+ * Returns true iff `err` is a "module/package not found" error whose missing
+ * specifier matches `pkgName` exactly. Transitive misses (specifier !==
+ * pkgName) return false so we don't falsely advise the user to install
+ * `pkgName` when something `pkgName` itself depends on is broken.
+ */
+export declare function isMissingOptionalPackageError(err: unknown, pkgName: string, opts?: MissingPackageOpts): boolean;
+/**
+ * Extract the missing specifier from a Node module-not-found message.
+ *
+ *   ESM: "Cannot find package '<pkg>' imported from <url>"
+ *   CJS: "Cannot find module '<pkg>'"
+ *
+ * Returns `undefined` if no specifier can be extracted (the message format
+ * may shift across Node versions; caller treats this as "not our package").
+ */
+export declare function extractMissingSpecifier(msg: string, acceptCjsForm?: boolean): string | undefined;
+/**
+ * Standard install-hint error message for `@supabase/supabase-js`. Shared by
+ * dashboard upload and the omit-optional smoke test so the assertion string
+ * stays in one place.
+ */
+export declare const SUPABASE_INSTALL_HINT = "Dashboard upload requires @supabase/supabase-js. Install with: npm install @supabase/supabase-js";
+/**
+ * Probe that lazy-loads `@supabase/supabase-js`. Returns the imported module
+ * on success. Throws an Error with `SUPABASE_INSTALL_HINT` if the package is
+ * not installed; re-throws everything else (transitive failures, syntax
+ * errors, etc.) so they aren't misclassified.
+ */
+export declare function loadSupabaseOrInstallHint(): Promise<typeof import('@supabase/supabase-js')>;
+//# sourceMappingURL=missing-package.d.ts.map

package/dist/src/cli/dashboard/missing-package.js

@@ -0,0 +1,85 @@
+// src/cli/dashboard/missing-package.ts
+//
+// Disambiguate "user needs to install <pkg>" from "transitive dep of <pkg> is
+// missing." When `@supabase/supabase-js` is lazy-loaded with `await import()`
+// and the package itself isn't installed, Node throws an ERR_MODULE_NOT_FOUND
+// whose specifier is the package name. If a transitive dep is missing instead
+// (e.g. `@supabase/postgrest-js`), the specifier will be the transitive name —
+// we should NOT instruct the user to install supabase in that case.
+//
+// Used by dashboard upload (the only feature reachable from the CLI that
+// requires `@supabase/supabase-js`). Moved to `optionalDependencies` in v7.8.0
+// so local-only `npm install --omit=optional` users can skip it.
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * Returns true iff `err` is a "module/package not found" error whose missing
+ * specifier matches `pkgName` exactly. Transitive misses (specifier !==
+ * pkgName) return false so we don't falsely advise the user to install
+ * `pkgName` when something `pkgName` itself depends on is broken.
+ */
+export function isMissingOptionalPackageError(err, pkgName, opts = {}) {
+    if (!(err instanceof Error))
+        return false;
+    const e = err;
+    if (e.code !== 'ERR_MODULE_NOT_FOUND' && e.code !== 'MODULE_NOT_FOUND') {
+        return false;
+    }
+    const specifier = extractMissingSpecifier(e.message, opts.acceptCjsForm ?? true);
+    return specifier === pkgName;
+}
+/**
+ * Extract the missing specifier from a Node module-not-found message.
+ *
+ *   ESM: "Cannot find package '<pkg>' imported from <url>"
+ *   CJS: "Cannot find module '<pkg>'"
+ *
+ * Returns `undefined` if no specifier can be extracted (the message format
+ * may shift across Node versions; caller treats this as "not our package").
+ */
+export function extractMissingSpecifier(msg, acceptCjsForm = true) {
+    const esm = msg.match(/Cannot find package '([^']+)'/);
+    if (esm)
+        return esm[1];
+    if (acceptCjsForm) {
+        const cjs = msg.match(/Cannot find module '([^']+)'/);
+        if (cjs)
+            return cjs[1];
+    }
+    return undefined;
+}
+/**
+ * Standard install-hint error message for `@supabase/supabase-js`. Shared by
+ * dashboard upload and the omit-optional smoke test so the assertion string
+ * stays in one place.
+ */
+export const SUPABASE_INSTALL_HINT = 'Dashboard upload requires @supabase/supabase-js. Install with: npm install @supabase/supabase-js';
+/**
+ * Probe that lazy-loads `@supabase/supabase-js`. Returns the imported module
+ * on success. Throws an Error with `SUPABASE_INSTALL_HINT` if the package is
+ * not installed; re-throws everything else (transitive failures, syntax
+ * errors, etc.) so they aren't misclassified.
+ */
+export async function loadSupabaseOrInstallHint() {
+    try {
+        // Suppress TS error when `@supabase/supabase-js` isn't installed in
+        // smoke-test environments — the failure surface is exactly what we're
+        // probing for, and the static type-only side is fine because callers
+        // who care about the typed shape import `type { ... }` separately.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return (await import(__rewriteRelativeImportExtension('@supabase/supabase-js')));
+    }
+    catch (err) {
+        if (isMissingOptionalPackageError(err, '@supabase/supabase-js')) {
+            throw new Error(SUPABASE_INSTALL_HINT);
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=missing-package.js.map

package/dist/src/cli/dashboard/upload.d.ts

@@ -1,4 +1,4 @@
-import { type UploadResult } from '../../dashboard/upload/uploader.ts';
+import type { UploadResult } from '../../dashboard/upload/uploader.ts';
 export interface ManualUploadOptions {
     runId: string;
     runsDir?: string;

package/dist/src/cli/dashboard/upload.js

@@ -2,11 +2,25 @@
 //
 // Locates run dir at <homeDir>/runs/<runId>, calls uploadRun() directly,
 // and prints the result. Intended for resuming interrupted auto-uploads.
+//
+// v7.8.0: probes `@supabase/supabase-js` availability before any upload work.
+// Supabase is now an optionalDependency (so `npm install --omit=optional`
+// works for local-only users); if a user invokes a dashboard verb without
+// it installed, we surface an actionable install hint instead of a raw
+// `ERR_MODULE_NOT_FOUND`. Wired through `loadSupabaseOrInstallHint` so the
+// transitive-dep miss case is correctly distinguished (see
+// missing-package.ts).
 import * as path from 'node:path';
 import { promises as fs } from 'node:fs';
 import { readConfig, getConfigDir } from "../../dashboard/config.js";
-import { uploadRun } from "../../dashboard/upload/uploader.js";
+import { loadSupabaseOrInstallHint } from "./missing-package.js";
 export async function runDashboardUpload(opts) {
+    // v7.8.0 — supabase is an optionalDependency. Probe availability before
+    // doing any upload work; if missing, surface the actionable install hint
+    // (Error message defined in missing-package.ts). Local-only users who
+    // installed with `npm install --omit=optional` will hit this on first
+    // attempted upload and know exactly how to fix it.
+    await loadSupabaseOrInstallHint();
     const cfg = await readConfig();
     if (!cfg) {
         if (!opts.silent) {
@@ -31,6 +45,11 @@ export async function runDashboardUpload(opts) {
         ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
         ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
     };
+    // Dynamic import — evaluated AFTER the supabase probe at the top of
+    // this function. Keeps the install-hint path correct even if any
+    // future change inside `uploader.ts` (or its transitive imports)
+    // adds a static value-import of `@supabase/supabase-js`.
+    const { uploadRun } = await import("../../dashboard/upload/uploader.js");
     const res = await uploadRun(opts.runId, runDir, uploadOpts);
     if (!opts.silent) {
         if (res.ok && res.url) {

package/dist/src/cli/help-text.d.ts

@@ -42,7 +42,7 @@ export declare const HELP_OPTIONS: Record<string, string>;
  * support varies; v6.0.1 wires them into `scan` first, additional verbs land
  * in subsequent v6.0.x point releases per docs/v6/wrapping-pipeline-phases.md).
  */
-export declare const GLOBAL_FLAGS_BLOCK = "Global flags:\n  --json                 Emit a structured JSON envelope on stdout (most verbs)\n  --engine               [v7.0 deprecated no-op] engine is always on; flag emits a warning\n                         v7.0 removed the engine-off opt-out flag and code path entirely.\n                         CLAUDE_AUTOPILOT_ENGINE=off is now ignored (warns once per process)\n                         instead of disabling the engine. See docs/v7/breaking-changes.md.";
+export declare const GLOBAL_FLAGS_BLOCK = "Global flags:\n  --json                 Emit a structured JSON envelope on stdout (most verbs)\n  --engine               [v7.0 deprecated no-op] engine is always on; flag emits a warning\n                         v7.0 removed the engine-off opt-out flag and code path entirely.\n                         CLAUDE_AUTOPILOT_ENGINE=off is now ignored (warns once per process)\n                         instead of disabling the engine. See docs/v7/breaking-changes.md.\n\nResolution overrides (v7.8.0):\n  --tsx-source <bundled|project|path>\n                         Override how the dev launcher picks the tsx binary used\n                         to run .ts files. Default precedence is project-local\n                         \u2192 PATH \u2192 bundled (with deprecation warning on the\n                         bundled fallthrough). Env equivalent: CLAUDE_AUTOPILOT_TSX.\n                         Silence the bundled-fallthrough warning with\n                         CLAUDE_AUTOPILOT_NO_TSX_DEPRECATION=1. `tsx` will be\n                         removed from runtime deps in v8.0.0.";
 /** Build the full two-level help text. Returned as a string so tests can assert against it without spawning. */
 export declare function buildHelpText(): string;
 /** Build help text for a single verb. Returns null if the verb is unknown. */