@lunora/cli 1.0.0-alpha.39 → 1.0.0-alpha.390

package/dist/index.d.ts

@@ -1,33 +1,34 @@
-import { CodegenOptions, SchemaIR } from '@lunora/codegen';
-import '@visulima/cerebro';
-import { ensureDevVariables, ensureDevVarsExample, fillDevSecrets, materializeRemoteWranglerConfig } from '@lunora/config';
-export { REQUIRED_COMPATIBILITY_DATE, REQUIRED_FLAG, type WranglerProjectValidationOptions as WranglerValidationOptions, type WranglerValidationReport, type WranglerProjectValidationResult as WranglerValidationResult, validateWranglerProject as validateWrangler, validateWranglerConfig } from '@lunora/config';
+import { CodegenOptions, Finding, FieldSnapshot, SchemaIR } from '@lunora/codegen';
+import { ensureDevVariables, ensureDevVarsExample, fillDevSecrets, startCelldDevSession, LintTool, LintIgnoreOutcome, PackageManager, PackageManagerProbe } from '@lunora/config';
+import { materializeDevWranglerConfig, materializeServiceDevConfigs } from '@lunora/config/cloudflare';
+export { REQUIRED_COMPATIBILITY_DATE, REQUIRED_FLAG, type WranglerProjectValidationOptions as WranglerValidationOptions, type WranglerValidationReport, type WranglerProjectValidationResult as WranglerValidationResult, validateWranglerProject as validateWrangler, validateWranglerConfig } from '@lunora/config/cloudflare';
 /** Every command name the CLI registers (drives the `CommandName` type + tests). */
-declare const COMMANDS: readonly ["init", "add", "dev", "codegen", "build", "deploy", "containers", "prepare", "link", "deployments", "logs", "run", "insights", "reset", "migrate", "export", "import", "seed", "backup", "verify", "info", "doctor", "env", "analyze", "view", "docs", "registry", "rules"];
+declare const COMMANDS: readonly ["init", "add", "dev", "codegen", "build", "deploy", "prepare", "link", "cloudflare", "logs", "run", "insights", "profile", "reset", "migrate", "export", "import", "seed", "shards", "backup", "eval", "verify", "info", "doctor", "env", "analyze", "view", "docs", "registry", "rules", "mcp"];
 type CommandName = (typeof COMMANDS)[number];
 declare const VERSION: string;
 interface RunCliOptions {
   argv?: ReadonlyArray<string>;
   cwd?: string;
   /**
-  * Inject a console-like logger so callers (tests) can capture cerebro's
-  * help / version / usage rendering. Omitted in production, where cerebro
-  * uses its default stdout/stderr logger.
-  */
+   * Inject a console-like logger so callers (tests) can capture cerebro's
+   * help / version / usage rendering AND the commands' own output. Omitted in
+   * production, where cerebro uses its default stdout/stderr logger and the
+   * commands log through the shared pail.
+   */
   logger?: Console;
 }
 /**
-* Run the CLI and resolve to the process exit code. cerebro handles help,
-* version, usage, and unknown commands (the latter throws, caught here as 1).
-* `shouldExitProcess: false` keeps the process alive so callers/tests read the
-* captured exit code.
-*/
+ * Run the CLI and resolve to the process exit code. cerebro handles help,
+ * version, usage, and unknown commands (the latter throws, caught here as 1).
+ * `shouldExitProcess: false` keeps the process alive so callers/tests read the
+ * captured exit code.
+ */
 declare const runCli: (options?: RunCliOptions) => Promise<number>;
 /**
-* The `--api-spec` flag's accepted values, mirroring `@lunora/codegen`'s
-* `CodegenOptions["apiSpec"]`. `"openapi"` (the default) emits `openapi.json`;
-* `"openrpc"` emits `openrpc.json`; `"both"` emits both; `"none"` emits neither.
-*/
+ * The `--api-spec` flag's accepted values, mirroring `@lunora/codegen`'s
+ * `CodegenOptions["apiSpec"]`. `"openapi"` (the default) emits `openapi.json`;
+ * `"openrpc"` emits `openrpc.json`; `"both"` emits both; `"none"` emits neither.
+ */
 type ApiSpec = NonNullable<CodegenOptions["apiSpec"]>;
 interface Logger {
   debug?: (message: string) => void;
@@ -37,11 +38,11 @@ interface Logger {
   warn: (message: string) => void;
 }
 /**
-* Narrowed view over the pail instance. `createPail` returns an intersection
-* type that includes a constructor signature and `(...args: any[])` logger
-* overloads, which the type-aware linter cannot safely resolve. We only ever
-* call the level methods with a string, so we describe exactly that surface.
-*/
+ * Narrowed view over the pail instance. `createPail` returns an intersection
+ * type that includes a constructor signature and `(...args: any[])` logger
+ * overloads, which the type-aware linter cannot safely resolve. We only ever
+ * call the level methods with a string, so we describe exactly that surface.
+ */
 interface PailLogger {
   debug: (message: string) => void;
   error: (message: string) => void;
@@ -51,59 +52,107 @@ interface PailLogger {
 }
 declare const createLogger: () => Logger;
 /**
-* Logger whose every channel writes to `process.stderr`. Used by commands in
-* `--format json` mode so all human/progress output stays off stdout — leaving
-* stdout for the single JSON document the command prints, so `… --format json`
-* stays cleanly pipeable (`| jq`). Each line carries a one-character level tag
-* so the stream is still readable when a human watches it.
-*/
-/**
-* Direct access to the underlying pail instance for advanced use-cases.
-* A Proxy keeps the public `pail` binding lazy: the real pail is only
-* constructed on first property access, so importing this module (and thus
-* the package barrel) stays side-effect-free.
-*/
+ * Direct access to the underlying pail instance for advanced use-cases.
+ * A Proxy keeps the public `pail` binding lazy: the real pail is only
+ * constructed on first property access, so importing this module (and thus
+ * the package barrel) stays side-effect-free.
+ */
 declare const pail: PailLogger;
 /**
-* Emit a badged step line through the shared pail (the `init` flow's off-TTY
-* fallback for the create-astro-style transcript). The `message` may contain
-* newlines — `LunoraReporter` indents continuation lines under the badge so a
-* dimmed answer sits below its question.
-*/
+ * The two renderings every Lunora command speaks. `pretty` is the human-facing
+ * default; `json` puts the command's structured result on stdout as a single
+ * JSON document and moves every human line to stderr.
+ *
+ * Resolved ONCE, by `defineHandler`, from the raw `--format` string — a command
+ * body receives this narrowed type and never re-validates it.
+ */
+type OutputFormat = "json" | "pretty";
+/**
+ * The envelope `--format json` puts on stdout — the same three keys for every
+ * command, so a consumer parses one shape and never has to know which command
+ * produced it.
+ *
+ * - `code` is the exit code the process will terminate with.
+ * - `data` is the command's own payload, and is absent when the run produced
+ * none — which is what a failure before any work looks like.
+ * - `error` is the single-line reason for a non-zero `code`. It is the half that
+ * makes a FAILURE machine-readable: before the envelope, a failed command wrote
+ * nothing at all to stdout and the reason could only be scraped out of English
+ * prose on stderr.
+ *
+ * `defineHandler` serializes exactly these keys, once, after the body returns —
+ * so a body may return a richer result for its in-process callers without
+ * widening the document, and a failure gets one for free.
+ */
+interface CommandResult<TData> {
+  /** Process exit code — one of `EXIT_CODE`. */
+  code: number;
+  /** The command's structured payload. Absent when the run produced none. */
+  data?: TData;
+  /**
+   * Set by a command that forwards `--format json` to a child process which
+   * writes the document itself (`wrangler … --json`, `wrangler tail`). The
+   * envelope is suppressed for that run: stdout already carries exactly one
+   * document, and appending a second would make the stream unparseable.
+   */
+  delegated?: boolean;
+  /** Why the run failed. Set whenever `code` is non-zero and a reason is known. */
+  error?: string;
+}
 interface CodegenCommandOptions {
   /** Which API spec(s) to emit. Defaults to codegen's `"openapi"` when omitted. */
   apiSpec?: ApiSpec;
   cwd?: string;
   /** Output format: `pretty` (default) or `json`. */
-  format?: string;
+  format?: OutputFormat;
   logger: Logger;
+  /**
+   * Fail the run when any ERROR-level advisory is reported. Defaults to CI
+   * detection so a local `lunora codegen` stays advisory while a pipeline
+   * gates on it; `--no-strict-advisories` forces it off either way.
+   */
+  strictAdvisories?: boolean;
+  /** Deploy target the emitted `ctx.*` surface is tailored to. Resolved by the caller; falls back to `"target"` in `lunora.config.*`, then `"cloudflare"`. */
+  target?: string;
 }
-interface CodegenCommandResult {
+/** The `--format json` payload: what codegen wrote, and what it has to say about it. */
+interface CodegenCommandData {
   advisories: ReadonlyArray<{
     detail: string;
-    level: string;
+    level: Finding["level"];
     name: string;
     remediation: string;
   }>;
   cronTriggers: ReadonlyArray<string>;
-  /** Set when the run aborted on an invalid `--format` before codegen ran. */
-  error?: string;
+  /** ERROR-level advisories that made the run fail, when strict mode is on. */
+  failedAdvisories: number;
   outputDirectory: string;
 }
+interface CodegenCommandResult extends CodegenCommandData {
+  /**
+   * Exit code, when the run resolved one itself. Only a USAGE refusal does —
+   * every other outcome is classified from `error`/`failedAdvisories` by
+   * `execute`, which cannot tell a bad `--format` (the invocation is wrong,
+   * exit 2) from a failed codegen (exit 1) after the fact.
+   */
+  code?: number;
+  /** Set when the run failed: an unregistered target, or an error-level platform diagnostic. */
+  error?: string;
+}
 declare const runCodegenCommand: (options: CodegenCommandOptions) => CodegenCommandResult;
-/** `lunora codegen` handler (lazy-loaded via the command's `loader`). */
-/** Rows per HTTP request when importing. Convex uses ~500; same here. */
-declare const DEFAULT_IMPORT_BATCH_SIZE = 500;
 /**
-* Minimal projection of `globalThis.fetch` for the export path — we need
-* `body` as a stream-iterable, which the shared {@link FetchLike} type
-* intentionally hides for the JSON-only commands.
-*/
+ * Minimal projection of `globalThis.fetch` for the transfer commands: `body` is
+ * exposed as a stream-iterable (the export path pipes it) and accepts bytes (the
+ * blob path uploads them). The JSON-only commands use the narrower `FetchLike`
+ * in `../run/handler` instead.
+ */
 type StreamingFetchLike = (input: string, init?: {
-  body?: string;
+  body?: string | Uint8Array;
   headers?: Record<string, string>;
   method?: string;
 }) => Promise<{
+  /** Optional: only the storage transfer reads raw bytes, and only real `fetch` needs to supply it. */
+  arrayBuffer?: () => Promise<ArrayBuffer>;
   body: ReadableStream<Uint8Array> | null;
   json: () => Promise<unknown>;
   ok: boolean;
@@ -113,6 +162,12 @@ type StreamingFetchLike = (input: string, init?: {
 interface ExportCommandOptions {
   cwd?: string;
   fetchImpl?: StreamingFetchLike;
+  /**
+   * Output format: `pretty` (default) or `json`. `json` reports the run as a
+   * single document and therefore requires a file destination — with `--out -`
+   * (or none) stdout already carries the NDJSON stream.
+   */
+  format?: OutputFormat;
   logger: Logger;
   /** Output file path; `undefined`/`-` streams to stdout. */
   out?: string;
@@ -125,18 +180,97 @@ interface ExportCommandOptions {
   /** Worker URL (default `http://localhost:8787`). */
   url?: string;
 }
-interface ExportCommandResult {
+/** The `--format json` payload: what was dumped, from which tables, and where to. */
+interface ExportCommandData {
+  bytes: number;
+  /** The file the dump landed in. */
+  out: string;
+  rows: number;
+  /** The table allowlist, omitted when the export covered every table. */
+  tables?: string[];
+}
+interface ExportCommandResult extends CommandResult<ExportCommandData> {
   bytes: number;
-  code: number;
   /** Number of NDJSON lines streamed (0 on error). */
   rows: number;
 }
 /**
-* Stream an export. The worker emits NDJSON; we count newlines as we go and
-* pipe straight to the output sink, so a 10M-row export doesn't materialise
-* the body in memory.
-*/
+ * Stream an export. The worker emits NDJSON; we count newlines as we go and
+ * pipe straight to the output sink, so a 10M-row export doesn't materialise
+ * the body in memory.
+ */
 declare const runExportCommand: (options: ExportCommandOptions) => Promise<ExportCommandResult>;
+/** One row-scoped failure as the admin import endpoint reports it. */
+interface ImportRowError {
+  code: string;
+  line: number;
+  message: string;
+  table: string;
+}
+/**
+ * One SHARD the fan-out never reached, as the admin import endpoint reports it.
+ *
+ * Distinct from {@link ImportRowError}: the rows a dead shard owned contribute
+ * to neither `inserted` nor `errors`, so an unknown slice of the batch is simply
+ * missing. The endpoint answers 207 Multi-Status when this array is non-empty.
+ */
+interface ImportShardFailure {
+  message: string;
+  shardKey: string;
+  timedOut: boolean;
+}
+/**
+ * The sources `--from` accepts.
+ *
+ * Only the two that cannot be detected. A Convex snapshot announces itself (a
+ * directory of `<table>/documents.jsonl`, or a `.zip` of one) and anything else
+ * is NDJSON, so naming those would advertise a control this does not implement:
+ * `--from ndjson` against a Convex export would have to either refuse it or
+ * silently import it as Convex, and the second is what an unhonoured flag
+ * actually did.
+ */
+declare const IMPORT_SOURCE_NAMES: readonly ["firebase", "supabase"];
+type ImportSourceName = (typeof IMPORT_SOURCE_NAMES)[number];
+/**
+ * The storage-reference rewrite: turning a Convex storage id into the
+ * content-hash R2 key its blob was migrated to.
+ *
+ * Split out of `./storage-mapping` (which owns the mapping *file*) because it
+ * has two callers that must never diverge — the import rewrite and `--scan`,
+ * which runs this same walk as a dry run to propose the mapping. A detector
+ * that proposed columns the rewrite would not touch, or missed ones it would,
+ * is worse than no detector.
+ */
+/** One reference the walk could not rewrite, with where it was found. */
+interface UnresolvedStorageReference {
+  column: string;
+  storageId: string;
+  table: string;
+}
+/**
+ * What a run's storage references resolved to. The two failure buckets are
+ * deliberately separate, because they are not the same problem and do not have
+ * the same remedy:
+ *
+ * `unmigrated` is a reference to a blob that does not exist — the export omitted
+ * it, or `--include-file-storage` was not passed. Nothing the operator writes in
+ * a mapping file can fix it, and the data is broken after import, so it fails
+ * `--verify`.
+ *
+ * `ambiguous` is a string that exactly matches a blob that *did* migrate, sitting
+ * in a column the mapping does not name. It may be a storage reference the
+ * mapping forgot, or it may be user text that happens to equal an id. Failing the
+ * run on a coincidence is not defensible, so it warns and names the column the
+ * operator would add to resolve it.
+ */
+interface StorageRemapReport {
+  ambiguous: UnresolvedStorageReference[];
+  /** Number of references rewritten to a content-hash key. */
+  rewritten: number;
+  unmigrated: UnresolvedStorageReference[];
+}
+/** Rows per HTTP request when importing. Convex uses ~500; same here. */
+declare const DEFAULT_IMPORT_BATCH_SIZE = 500;
 interface ImportCommandOptions {
   /** Rows per HTTP request. Defaults to {@link DEFAULT_IMPORT_BATCH_SIZE}. */
   batchSize?: number;
@@ -144,84 +278,228 @@ interface ImportCommandOptions {
   fetchImpl?: StreamingFetchLike;
   /** Source NDJSON file. Required. */
   file: string;
+  /** Output format: `pretty` (default) or `json`. */
+  format?: OutputFormat;
+  /**
+   * Which reader to use. Omit to auto-detect between a Convex export snapshot
+   * and a plain NDJSON file; `supabase`/`firebase` must be explicit, because a
+   * directory of CSV or JSON has no signature that distinguishes it from
+   * anything else a user might point at.
+   */
+  from?: ImportSourceName;
   logger: Logger;
   prod?: boolean;
   /**
-  * Wrap each line as `{table:&lt;name>,doc:&lt;line>}`. Use when the source NDJSON
-  * is bare docs from a single table — Convex's `convex import --table users`
-  * shape.
-  */
+   * Scan the export for columns holding `_storage` ids and write a candidate
+   * `lunora/import-convex.json`. Scan-only: nothing is imported.
+   */
+  scan?: boolean;
+  /**
+   * Local directory of storage objects to migrate alongside the rows — how
+   * Firebase Cloud Storage arrives, after `gcloud storage cp -r`.
+   */
+  storageDir?: string;
+  /**
+   * Wrap each line as `{table:<name>,doc:<line>}`. Use when the source NDJSON
+   * is bare docs from a single table — Convex's `convex import --table users`
+   * shape.
+   */
   table?: string;
   token?: string;
   url?: string;
+  /**
+   * Verify per-table row parity + dangling-storage after import. Exits non-zero
+   * when a table's inserted count differs from its source line count, or when a
+   * document references a storage id that was not migrated.
+   */
+  verify?: boolean;
+  /**
+   * Also migrate Convex `_storage` blobs: read `_storage/documents.jsonl`, upload
+   * each blob with sha256+size verification, and build the `storageId → key` map.
+   * Off by default so the plain-document import path is unchanged.
+   */
+  withStorage?: boolean;
+  /** Confirm bulk-writing production. Required alongside `--prod`. */
+  yes?: boolean;
 }
-interface ImportCommandResult {
-  body: unknown;
-  code: number;
+/**
+ * The JSON summary a run prints and returns — the same object either way, so a
+ * caller reading `body.conflicts` does not have to cast its way there.
+ *
+ * `undefined` on every path that imports nothing: a rejected source, a failed
+ * storage phase, or `--scan` (whose product is the mapping file it writes, not
+ * a return value).
+ */
+interface ImportSummary {
+  conflicts: number;
+  errors: ImportRowError[];
+  /** Shards the endpoint could not reach (it answered 207). Their rows are MISSING, not rejected — present only when non-empty. */
+  failed?: ImportShardFailure[];
+  inserted: Record<string, number>;
+  received: number;
+  storage?: {
+    /** Up to {@link UNRESOLVED_REPORT_LIMIT} distinct references — a sample, not the whole set. See `ambiguousTotal`. */
+    ambiguous: StorageRemapReport["ambiguous"];
+    /** How many DISTINCT `(table, column, storageId)` references were ambiguous. */
+    ambiguousTotal: number;
+    blobs: number;
+    rewritten: number;
+    /** Up to {@link UNRESOLVED_REPORT_LIMIT} distinct references — a sample, not the whole set. See `unmigratedTotal`. */
+    unmigrated: StorageRemapReport["unmigrated"];
+    /** How many DISTINCT `(table, column, storageId)` references resolved to no migrated blob. */
+    unmigratedTotal: number;
+  };
+  warnings?: string[];
+}
+/** The `--format json` payload: which file went in, and what the endpoint made of it. */
+interface ImportCommandData {
+  file: string;
+  inserted: number;
+  /** The batcher's own roll-up: inserted-per-table, conflicts, row errors, unreached shards. */
+  summary: ImportSummary;
+}
+interface ImportCommandResult extends CommandResult<ImportCommandData> {
+  body: ImportSummary | undefined;
   /** Total inserted rows across batches. */
   inserted: number;
 }
-/**
-* Stream an NDJSON file in chunks, POSTing each batch to
-* `/_lunora/admin/import`. We keep the line buffer bounded by `batchSize` so a
-* multi-GiB file imports without buffering everything in memory.
-*/
 declare const runImportCommand: (options: ImportCommandOptions) => Promise<ImportCommandResult>;
 /**
-* Injectable probe for a Docker-compatible container engine. Tests pass a
-* stub; production uses {@link isDockerAvailable}.
-*/
+ * Every exit code `lunora` can terminate with. Stable — a value never changes
+ * meaning, and a new bucket takes the next free number.
+ */
+declare const EXIT_CODE: {
+  /** The command did what was asked. */
+  readonly SUCCESS: 0;
+  /** A failure that fits none of the narrower buckets. */
+  readonly FAILURE: 1;
+  /** Bad usage, bad input, or a validation failure — the invocation itself, or the project source it read, is wrong. */
+  readonly USAGE: 2;
+  /** Not authenticated: no credential, or an expired one. */
+  readonly AUTH: 3;
+  /** Authenticated, but not allowed to do this. */
+  readonly PERMISSION: 4;
+  /** The named thing does not exist. */
+  readonly NOT_FOUND: 5;
+  /** The write lost a race, or the name is already taken. */
+  readonly CONFLICT: 6;
+  /** Rate limited — back off and retry. */
+  readonly RATE_LIMITED: 7;
+  /** The far side is unavailable or timed out. Retryable. */
+  readonly UNAVAILABLE: 8;
+  /** A local tool the command shells out to (wrangler, git, docker, …) is missing, or not running. */
+  readonly MISSING_DEPENDENCY: 9;
+  /** Interactive cancel — the POSIX `128 + SIGINT` convention. */
+  readonly CANCELLED: 130;
+};
+/** One of {@link EXIT_CODE}'s values. */
+type ExitCode = (typeof EXIT_CODE)[keyof typeof EXIT_CODE];
+/** The exit code for a transport status; `undefined` and anything unmapped are a general failure. */
+declare const exitCodeForStatus: (status: number | undefined) => ExitCode;
+/**
+ * The exit code for a Lunora error `code`, resolved through the catalog. An
+ * unregistered code has no status to derive from, so it is a general failure.
+ */
+declare const exitCodeForCode: (code: string) => ExitCode;
+/**
+ * The exit code for a thrown value. A Lunora error is classified by its `code`
+ * (override table first) and then by the `status` the instance carries — which
+ * is the catalog's, unless the throw site passed a more specific one (the
+ * upstream-API codes do). Anything else is a general failure.
+ */
+declare const exitCodeForError: (error: unknown) => ExitCode;
+/**
+ * Injectable probe for a Docker-compatible container engine. Tests pass a
+ * stub; production uses {@link isDockerAvailable}.
+ */
 type DockerProbe = () => boolean;
 /**
-* True when a Docker-compatible engine answers `docker info` — the same
-* prerequisite `wrangler deploy` has for building and pushing a container
-* image from a local Dockerfile. Quiet by design (output discarded): callers
-* own the messaging.
-*/
+ * The shared `/_lunora/health` probe used by `lunora verify --health-url` and
+ * `lunora deploy --health-check`.
+ *
+ * Both commands ask the same question — "does this deployment answer?" — so
+ * they ask it through one implementation with one error-message shape. The
+ * runtime auto-registers both routes (`packages/runtime/src/health-routes.ts`):
+ * `/_lunora/health/ready` is the readiness gate ("can this version serve"), and
+ * `/_lunora/health` is the aggregate that also exists on older deployments.
+ *
+ * The probe is transport-only: it never throws, and reports its verdict as an
+ * `{ error }` message the caller decides what to do with.
+ */
+/**
+ * Minimal fetch surface the probe needs — a subset of the global `fetch`,
+ * injectable so a test can feed a canned response without a network.
+ */
+type HealthFetch = (url: string) => Promise<{
+  ok: boolean;
+  status: number;
+}>;
 interface SpawnDescriptor {
   args: ReadonlyArray<string>;
   /**
-  * Capture the child's stdout (in addition to streaming it to the parent), so
-  * the caller can parse it — used by `deploy` to read the deployed URL from
-  * `wrangler deploy` output. Each chunk is still teed to the parent's stdout
-  * so the user sees live progress. Mutually exclusive with `stdoutToStderr`.
-  */
+   * Capture the child's stderr (in addition to streaming it to the parent).
+   * Needed when a tool reports the *expected* outcome as an error there —
+   * `wrangler vectorize create-metadata-index` writes "already exists" to
+   * stderr, and without this the caller can only see a bare exit code and
+   * would warn on every re-run. Composes with `stdoutToStderr`, so a caller
+   * can keep stdout clean for `--format json` and still read the reason.
+   */
+  captureStderr?: boolean;
+  /**
+   * Capture the child's stdout (in addition to streaming it to the parent), so
+   * the caller can parse it — used by `deploy` to read the deployed URL from
+   * `wrangler deploy` output. Each chunk is still teed to the parent's stdout
+   * so the user sees live progress. Mutually exclusive with `stdoutToStderr`
+   * and `captureStdoutSilently`.
+   */
   captureStdout?: boolean;
+  /**
+   * Capture the child's stdout WITHOUT teeing it to the parent's stdout —
+   * for output that is parsed, never displayed (e.g. `wrangler secret list
+   * --format json`). Unlike `captureStdout`, nothing is written to
+   * `process.stdout`, so it can't interleave with — and corrupt — a
+   * caller's own stdout (notably `lunora deploy --format json`, which must
+   * emit exactly one JSON document). Mutually exclusive with `captureStdout`
+   * and `stdoutToStderr`.
+   */
+  captureStdoutSilently?: boolean;
   command: string;
   cwd?: string;
   env?: Readonly<Record<string, string>>;
   /**
-  * Pipe this string into the child's stdin and close it. Used to feed
-  * `wrangler secret put` its value without exposing it on the command
-  * line or in env. When absent, stdin is inherited from the parent.
-  */
+   * Pipe this string into the child's stdin and close it. Used to feed
+   * `wrangler secret put` its value without exposing it on the command
+   * line or in env. When absent, stdin is inherited from the parent.
+   */
   input?: string;
   /**
-  * Route the child's stdout to the parent's STDERR instead of stdout. Set in
-  * `--format json` mode so a spawned tool's human output (e.g. `wrangler
-  * deploy`'s progress + the deployed URL) can't interleave with — and corrupt
-  * — the single JSON document the command prints to stdout.
-  */
+   * Route the child's stdout to the parent's STDERR instead of stdout. Set in
+   * `--format json` mode so a spawned tool's human output (e.g. `wrangler
+   * deploy`'s progress + the deployed URL) can't interleave with — and corrupt
+   * — the single JSON document the command prints to stdout.
+   */
   stdoutToStderr?: boolean;
 }
 interface SpawnResult {
   code: number;
-  /** The captured stdout, present only when the descriptor set `captureStdout`. */
+  /** The captured stderr, present only when the descriptor set `captureStderr`. */
+  stderr?: string;
+  /** The captured stdout, present only when the descriptor set `captureStdout` or `captureStdoutSilently`. */
   stdout?: string;
 }
 /**
-* Injectable spawner. Tests pass a stub that just records the descriptor
-* instead of executing a real subprocess.
-*/
+ * Injectable spawner. Tests pass a stub that just records the descriptor
+ * instead of executing a real subprocess.
+ */
 type Spawner = (descriptor: SpawnDescriptor) => Promise<SpawnResult>;
 declare const defaultSpawner: Spawner;
 interface RecordedSpawn {
   descriptor: SpawnDescriptor;
 }
 /**
-* Test helper: returns a spawner that records every invocation and resolves
-* with the configured exit code.
-*/
+ * Test helper: returns a spawner that records every invocation and resolves
+ * with the configured exit code.
+ */
 declare const createRecordingSpawner: (exitCode?: number) => {
   calls: RecordedSpawn[];
   spawner: Spawner;
@@ -250,11 +528,6 @@ interface ListRemoteSecretsResult {
   /** False when wrangler failed or its output could not be parsed. */
   ok: boolean;
 }
-/**
-* Parse `wrangler secret list --format json` output into a sorted name list.
-* The payload is an array of `{ name, type }`; anything else yields `undefined`
-* so the caller can report a parse failure rather than silently returning [].
-*/
 type FetchLike = (input: string, init?: {
   body?: string;
   headers?: Record<string, string>;
@@ -267,83 +540,119 @@ type FetchLike = (input: string, init?: {
 }>;
 interface RunCommandOptions {
   args?: string;
+  /** Forge this user id for the call (dispatches through the admin-gated `runAs` op). */
+  as?: string;
+  /** JSON-encoded extra identity claims to accompany {@link RunCommandOptions.as}. */
+  claims?: string;
   cwd?: string;
   fetchImpl?: FetchLike;
+  /** Output format: `pretty` (default) or `json`. */
+  format?: OutputFormat;
   functionPath: string;
   logger: Logger;
   shard?: string;
+  /** Admin bearer for the `runAs` dispatch; resolved from the environment / `.dev.vars` when absent. */
+  token?: string;
   url?: string;
 }
 interface RunCommandResult {
   body: unknown;
   code: number;
+  /** Why the call failed before (or at) the RPC, for the `--format json` envelope. */
+  error?: string;
   requestUrl: string;
 }
 declare const runRpcCommand: (options: RunCommandOptions) => Promise<RunCommandResult>;
-/** `lunora run &lt;functionPath>` handler (lazy-loaded via the command's `loader`). */
 interface DeployCommandOptions {
   /** Override the schema-drift gate — deploy even with breaking drift and no new migration. */
   allowSchemaDrift?: boolean;
   /** Which API spec(s) codegen emits. Defaults to codegen's `"openapi"` when omitted. */
   apiSpec?: ApiSpec;
+  /**
+   * The command the operator actually ran. `build` delegates here with
+   * `dryRun: true`; without this the gate names the wrong command in its
+   * blocked message and offers flags the real caller does not accept.
+   */
+  commandName?: PreDeployCommand;
   cwd?: string;
   /** Docker-availability probe injected in tests. Defaults to a real `docker info` check. */
   dockerAvailable?: DockerProbe;
   /**
-  * Validate, bundle, and run all pre-deploy gates without publishing
-  * (`wrangler deploy --dry-run`). Post-deploy steps (data migrations, schema
-  * baseline re-bless) are skipped since nothing shipped.
-  */
+   * Validate, bundle, and run all pre-deploy gates without publishing
+   * (`wrangler deploy --dry-run`). Post-deploy steps (data migrations, schema
+   * baseline re-bless) are skipped since nothing shipped.
+   */
   dryRun?: boolean;
+  /**
+   * Write the binding manifest (`build --emit-bindings`) to this path once the
+   * bundle exists. Owned here rather than by the caller because it is the last
+   * artifact that has to read the PROVISIONED `wrangler.jsonc`, and the dry-run
+   * rollback below closes that window as soon as this function returns.
+   * Relative paths resolve against the project root.
+   */
+  emitBindings?: string;
   env?: string;
   /** Fetch implementation injected in tests for `--migrate` RPC calls. */
   fetchImpl?: FetchLike;
   /** Output format: `pretty` (default) or `json`. */
-  format?: string;
+  format?: OutputFormat;
+  /**
+   * After a successful live deploy, probe the new version's health route
+   * (`/_lunora/health/ready`, falling back to `/_lunora/health`) and fail the
+   * command when it never answers. Opt-in, not default-on: a worker whose
+   * health route is admin-gated or unreachable from CI must still be
+   * deployable, and a default network step would turn a successful deploy
+   * into a red build for an unrelated reason.
+   */
+  healthCheck?: boolean;
+  /** Injectable fetch for `--health-check`; defaults to the global `fetch`. */
+  healthFetch?: HealthFetch;
+  /** Injectable inter-attempt delay for `--health-check`; injected in tests to skip the real wait. */
+  healthSleep?: (ms: number) => Promise<void>;
   /** Set to `false` to disable interactive spinners (test injection). */
   interactive?: boolean;
   logger: Logger;
   /**
-  * When true, after a successful `wrangler deploy`, discover and run all
-  * pending data migrations via the worker's `/_lunora/migrate` admin RPC.
-  * The worker must be live (exit 0) before migrations are attempted.
-  *
-  * Implementation note: the status RPC returns the full shard-level
-  * migration state, but there is no single authoritative "list of pending
-  * migration ids" that can be read client-side before running the worker.
-  * Instead, `--migrate` runs `migrate status` followed by `migrate up` for
-  * each migration id discovered locally via `discoverMigrations`.  The
-  * worker's `MigrationRunner` is idempotent — running `up` on an already-
-  * applied migration is a no-op — so this approach is safe.
-  */
+   * When true, after a successful `wrangler deploy`, discover and run all
+   * pending data migrations via the worker's `/_lunora/migrate` admin RPC.
+   * The worker must be live (exit 0) before migrations are attempted.
+   *
+   * Implementation note: the status RPC returns the full shard-level
+   * migration state, but there is no single authoritative "list of pending
+   * migration ids" that can be read client-side before running the worker.
+   * Instead, `--migrate` runs `migrate status` followed by `migrate up` for
+   * each migration id discovered locally via `discoverMigrations`.  The
+   * worker's `MigrationRunner` is idempotent — running `up` on an already-
+   * applied migration is a no-op — so this approach is safe.
+   */
   migrate?: boolean;
   /** Admin bearer token for `--migrate` (falls back to `LUNORA_ADMIN_TOKEN`). */
   migrateToken?: string;
   /**
-  * Worker URL for `--migrate`. REQUIRED when `--migrate` is set — the deploy
-  * handler never captures the URL `wrangler deploy` published to, so there is
-  * no safe default; omitting it would silently target `http://localhost:8787`
-  * (the dev worker), applying the migration to local state instead of prod.
-  */
+   * Worker URL for `--migrate`. REQUIRED when `--migrate` is set — the deploy
+   * handler never captures the URL `wrangler deploy` published to, so there is
+   * no safe default; omitting it would silently target `http://localhost:8787`
+   * (the dev worker), applying the migration to local state instead of prod.
+   */
   migrateUrl?: string;
   /**
-  * Confirm a production data migration triggered via `--migrate` (the
-  * `migrate up --prod` confirmation the standalone command requires). Without
-  * it a `--migrate --migrate-url &lt;prod>` deploy refuses to run the migration.
-  */
+   * Confirm a production data migration triggered via `--migrate` (the
+   * `migrate up --prod` confirmation the standalone command requires). Without
+   * it a `--migrate --migrate-url <prod>` deploy refuses to run the migration.
+   */
   migrateYes?: boolean;
   /**
-  * Emit the bundled worker to this directory via `wrangler deploy --outdir`
-  * (paired with `dryRun` by `lunora build`). Also writes esbuild metadata to
-  * `&lt;outDir>/bundle-meta.json`. When unset, no artifact is written.
-  */
+   * Emit the bundled worker to this directory via `wrangler deploy --outdir`
+   * (paired with `dryRun` by `lunora build`). Also writes esbuild metadata to
+   * `<outDir>/bundle-meta.json`. When unset, no artifact is written.
+   */
   outDir?: string;
   /**
-  * Upload a preview version (`wrangler versions upload`) instead of a live
-  * `wrangler deploy`. Codegen + the drift gate + validation still run, but
-  * the post-deploy finalize (migrations, baseline re-bless, auto-link, the
-  * production summary) is skipped — a preview never shifts live traffic.
-  */
+   * Upload a preview version (`wrangler versions upload`) instead of a live
+   * `wrangler deploy`. Codegen + the drift gate + validation still run, but
+   * the post-deploy finalize (migrations, baseline re-bless, auto-link, the
+   * production summary) is skipped — a preview never shifts live traffic.
+   */
   preview?: boolean;
   /** Railpack-availability probe injected in tests. Defaults to a real `railpack --version` + `BUILDKIT_HOST` check. */
   railpackAvailable?: DockerProbe;
@@ -352,24 +661,95 @@ interface DeployCommandOptions {
   /** Remote-secret lister for the missing-secret offer; injected in tests. Defaults to `wrangler secret list`. */
   secretLister?: (inputs: ListRemoteSecretsInputs) => Promise<ListRemoteSecretsResult>;
   skipCodegen?: boolean;
+  /** Deploy only the app, leaving the `lunora.config` services it binds as they are (`--skip-services`). */
+  skipServices?: boolean;
   spawner?: Spawner;
   /**
-  * Deploy to a temporary Cloudflare account (`wrangler deploy --temporary`).
-  * For unauthenticated use only: wrangler provisions a short-lived account +
-  * token, deploys, and prints a claim URL; the deployment stays live ~60
-  * minutes before the unclaimed account is deleted. Wrangler itself errors
-  * if credentials are already present (OAuth / `CLOUDFLARE_API_TOKEN` /
-  * global API key), so we pass the flag straight through without guarding.
-  */
+   * Fail the deploy when codegen reports an ERROR-level advisory. Same
+   * option `lunora codegen` exposes as `--no-strict-advisories`; defaults to
+   * CI detection (on in CI, off locally) so a legitimately-partial target
+   * can still be shipped interactively. Does NOT gate platform diagnostics
+   * (`platform_unsupported_feature` / `platform_unknown_target`), which
+   * always block — those mean the emitted `ctx.*` surface does not match
+   * what the target can serve, not merely a style nit.
+   */
+  strictAdvisories?: boolean;
+  /**
+   * Deploy target. Falls back to `"target"` in `lunora.config.*`, then
+   * `"cloudflare"`, which selects the wrangler
+   * toolchain — i.e. today's behavior for every project. An unregistered name
+   * throws rather than falling back, so a typo can never ship the app to the
+   * wrong provider.
+   */
+  target?: string;
+  /**
+   * Deploy to a temporary Cloudflare account (`wrangler deploy --temporary`).
+   * For unauthenticated use only: wrangler provisions a short-lived account +
+   * token, deploys, and prints a claim URL; the deployment stays live ~60
+   * minutes before the unclaimed account is deleted. Wrangler itself errors
+   * if credentials are already present (OAuth / `CLOUDFLARE_API_TOKEN` /
+   * global API key), so we pass the flag straight through without guarding.
+   */
   temporary?: boolean;
   /** Re-bless the committed schema baseline with the current shape (accepts breaking drift). */
   updateSchemaBaseline?: boolean;
 }
+/**
+ * What this run put where — the identity of the thing that was just deployed.
+ *
+ * Present on every run that reached (and completed) the wrangler invocation,
+ * including `--dry-run` and `--preview`, so a consumer can tell "nothing went
+ * live" from "went live" without inferring it from a missing `url`. A dry run
+ * publishes nothing and therefore never carries a `url`.
+ *
+ * No `versionId`: the pinned wrangler (see the `wrangler` catalog entry in
+ * `pnpm-workspace.yaml`) has no structured deploy output
+ * and no flag that returns the version id — it only prints it in prose, and
+ * scraping a second value out of prose is exactly what this shouldn't do. The
+ * id is available from `lunora cloudflare deployments list` after the fact.
+ */
+interface DeployedIdentity {
+  /** ISO-8601 stamp taken when the wrangler invocation returned. */
+  deployedAt: string;
+  /** True when `--dry-run` validated + bundled without publishing. */
+  dryRun: boolean;
+  /** The Cloudflare environment this run targeted, when `--env` named one. */
+  env?: string;
+  /** True when `--preview` uploaded a version instead of shifting live traffic. */
+  preview: boolean;
+  /** The URL wrangler reported publishing to; absent on a dry run, or when the output carried no URL. */
+  url?: string;
+  /** The Worker name from the project's wrangler config. */
+  workerName?: string;
+}
 interface DeployCommandResult {
   code: number;
+  /** What was deployed and where — set once the wrangler invocation completed. */
+  deployment?: DeployedIdentity;
   descriptor: SpawnDescriptor | undefined;
   /** Set when the run aborted before reaching the wrangler invocation. */
   error?: string;
+  /**
+   * The `--health-check` probe's verdict, when the flag was set and the probe
+   * ran. A red probe fails the command (`code` is non-zero) — but the deploy
+   * itself still succeeded, which is why the reason is reported separately
+   * from `error`.
+   */
+  healthCheck?: {
+    error?: string;
+    ok: boolean;
+    url: string;
+  };
+  /** Whether the target a successful deploy shipped to has a log tail for `lunora logs`. */
+  logsAvailable?: boolean;
+  /**
+   * The `.dev.vars`-shaped filename (never a full path, never a value) a
+   * secret minted during this run was recorded into, when the missing-
+   * secret gate minted one — `.dev.vars` for the default environment, or a
+   * `.dev.vars.<env>` sibling for an explicit `--env`. `undefined` when
+   * nothing was minted this run.
+   */
+  mintedSecretsFile?: string;
   /** The schema-drift gate verdict, when it ran (skipped on `--skip-codegen`). */
   schemaDrift?: {
     blocked: boolean;
@@ -381,48 +761,107 @@ interface DeployCommandResult {
   };
 }
 /**
-* Run a deploy, then (in `--format json` mode) serialize the structured
-* {@link DeployCommandResult} to stdout. Human/progress logging is routed to
-* stderr for json output so stdout carries only the single JSON document.
-*/
+ * The commands that run the pre-deploy pipeline, as the OPERATOR typed them.
+ *
+ * These checks are reached from `lunora deploy`, `lunora prepare` and
+ * `lunora build`, and a blocked run naming a command the operator never ran
+ * reads as a bug in the tool rather than a problem in the project.
+ *
+ * `build` is one of them: it delegates to `runDeployCommand({ dryRun: true })`.
+ * The name is threaded through rather than assumed, because the drift gate uses
+ * it for two operator-facing decisions — which override flags to offer, and what
+ * to call the thing that was blocked. Hardcoding `"deploy"` here meant `lunora
+ * build` reported "deploy blocked" for a deploy nobody attempted and recommended
+ * a flag `build` rejects with a raw stack trace.
+ */
+type PreDeployCommand = "build" | "deploy" | "prepare";
+/**
+ * Run a deploy. In `--format json` mode the human/progress channel is already on
+ * stderr (`defineHandler` routed it) and the Vercel-style summary is skipped, so
+ * stdout is left to the single result document `execute` returns.
+ */
 declare const runDeployCommand: (options: DeployCommandOptions) => Promise<DeployCommandResult>;
-/** `lunora deploy` handler (lazy-loaded via the command's `loader`). */
 /**
-* Start the codegen watch loop and return a handle to stop it. Regenerates on
-* startup, then on debounced changes under `lunora/` (ignoring writes to the
-* `_generated/` output to avoid a feedback loop). If the platform can't do a
-* recursive watch, it logs once and falls back to startup-only codegen.
-*/
+ * Start the codegen watch loop and return a handle to stop it. Regenerates on
+ * startup, then on debounced changes under `lunora/` (ignoring writes to the
+ * `_generated/` output to avoid a feedback loop). If the platform can't do a
+ * recursive watch, it logs once and falls back to startup-only codegen.
+ */
 declare const startCodegenWatch: (options: CodegenWatcherOptions) => CodegenWatcherHandle;
 interface CodegenWatcherOptions {
   /** Which API spec(s) to emit. Defaults to codegen's `"openapi"` when omitted. */
   apiSpec?: CodegenOptions["apiSpec"];
   /** Debounce window for coalescing rapid edits. Defaults to 100ms. */
   debounceMs?: number;
+  /**
+   * The caller's logs are NDJSON on stdout, so the `postcodegen` hook's own
+   * stdout must be routed to stderr or it corrupts the stream. `lunora dev`
+   * turns this on for `--json` AND for a detected AI agent.
+   */
+  jsonLogs?: boolean;
   logger: Logger;
   /** Override the lunora subdirectory name. Defaults to `"lunora"`. */
   lunoraDirectory?: string;
   /** Project root containing the `lunora/` directory. */
   projectRoot: string;
+  /** Process spawner for the `postcodegen` hook. Injectable so tests need no real subprocess. */
+  spawner?: Spawner;
+  /** Deploy target the emitted `ctx.*` surface is tailored to. Resolved by the caller; falls back to `"target"` in `lunora.config.*`, then `"cloudflare"`. */
+  target?: string;
 }
 interface CodegenWatcherHandle {
-  /** Stop watching and cancel any pending regeneration. */
-  close: () => void;
-  /**
-  * `true` when the platform supports recursive watch and the loop is active.
-  * `false` when `fs.watch({ recursive })` threw — startup-only codegen was run
-  * but schema edits will NOT auto-regenerate. Callers can surface this in the
-  * dev banner so the degraded state is visible beyond the single startup warning.
-  */
+  /**
+   * Stop watching, drop any queued regeneration, and resolve once the run
+   * already in flight has finished.
+   *
+   * Awaiting the result is what keeps a `postcodegen` child from being
+   * orphaned by the caller's `process.exit`; a caller that only needs the
+   * watcher detached can ignore it.
+   */
+  close: () => Promise<void>;
+  /**
+   * Resolves once the startup regeneration — codegen AND the project's
+   * `postcodegen` — has finished.
+   *
+   * Await it before starting anything that reads generated output. `runCodegen`
+   * is synchronous and has already run by the time `startCodegenWatch` returns,
+   * but the hook is the step that FINISHES that output, so a worker spawned
+   * without waiting can bundle the unfinished copy. Resolves (never rejects)
+   * even when codegen or the hook failed — both report for themselves, and a
+   * dev server still has to come up.
+   */
+  ready: Promise<void>;
+  /**
+   * `true` when the platform supports recursive watch and the loop is active.
+   * `false` when `fs.watch({ recursive })` threw — startup-only codegen was run
+   * but schema edits will NOT auto-regenerate. Callers can surface this in the
+   * dev banner so the degraded state is visible beyond the single startup warning.
+   */
   watchAvailable: boolean;
 }
 /**
-* Start the studio server and resolve once it is listening. Loads the static
-* bundle + renders the host HTML once up front; serves them and proxies
-* `/_lunora/*` (HTTP + WS) to the worker.
-*/
+ * Readiness probe seam — tests swap the real HTTP probe out.
+ *
+ * The optional `signal` lets a caller cancel an attempt already in flight. Its
+ * absence is why a teardown used to leave one request dangling for up to
+ * {@link ATTEMPT_TIMEOUT_MS} after the dev server had been told to stop.
+ */
+type ReadinessProbe = (origin: string, signal?: AbortSignal) => Promise<boolean>;
+/**
+ * Start the studio server and resolve once it is listening. Loads the static
+ * bundle + renders the host HTML once up front; serves them and proxies
+ * `/_lunora/*` (HTTP + WS) to the worker.
+ */
 declare const startStudioServer: (options: StudioServerOptions) => Promise<StudioServerHandle>;
 interface StudioServerOptions {
+  /**
+   * API-spec mode the host runs codegen with, forwarded to the local endpoints
+   * so a studio edit regenerates the SAME spec files the host's own codegen run
+   * writes. Codegen writes the spec its mode names and deletes the other, so
+   * omitting it made every studio edit delete an `apiSpec: "openrpc"` project's
+   * `openrpc.json`.
+   */
+  apiSpec?: CodegenOptions["apiSpec"];
   /** Project root — `.dev.vars` is read from here for the admin token. */
   cwd: string;
   /** Loopback host to bind. Defaults to `127.0.0.1` (admin tooling stays local). */
@@ -442,6 +881,25 @@ interface StudioServerHandle {
   /** The URL to open in a browser. */
   url: string;
 }
+/**
+ * How the dev child runs. `wrangler` is the classic `lunora dev` stack (wrangler
+ * worker + embedded studio + codegen watch) for a standalone class-C project.
+ * `vite` is a project whose BUNDLER PLUGIN already runs the worker — `@lunora/vite`
+ * inside the Vite dev server, or `@lunora/rspack/rsbuild` alongside an Rsbuild
+ * one — together with studio and codegen, so `lunora dev` runs the project's own
+ * dev script and gets out of the way — this also covers class-B
+ * frameworks whose own dev server runs the worker in `workerd` (Astro 6 +
+ * `@astrojs/cloudflare`, which embeds `@cloudflare/vite-plugin` in `astro dev`:
+ * SSR + `/_lunora/*` + `ShardDO` in one process, HMR intact). `framework-worker`
+ * is a class-B framework whose dev server CANNOT host the `ShardDO` Durable
+ * Object (SvelteKit / Nuxt: their adapters use wrangler's `getPlatformProxy()`,
+ * which runs an empty-script Miniflare and does not emulate internal DOs); there
+ * `lunora dev` runs the framework's own dev server (front door, HMR, and — via
+ * its `@lunora/vite` plugin — studio + codegen) AND a second `wrangler dev`
+ * sidecar that owns the real `ShardDO` in `workerd`, wired via the committed
+ * `wrangler.dev.jsonc`.
+ */
+type DevFlavor = "framework-worker" | "vite" | "wrangler";
 /** A running worker child the orchestrator controls: send signals, await its exit. */
 interface WorkerProcess {
   /** Resolves with the worker's exit code (1 if it failed to start). */
@@ -452,25 +910,73 @@ interface WorkerProcess {
 type WorkerSpawner = (descriptor: SpawnDescriptor & {
   tag: string;
 }, logger: Logger) => WorkerProcess;
+/** What a long-lived child runs: the one-shot descriptor's command/args/cwd/env, plus how to spawn it. */
+interface LongLivedDescriptor {
+  args: ReadonlyArray<string>;
+  command: string;
+  cwd?: string;
+  /** A real executable, never a package-manager shim — spawned without a shell, with stdin ignored. */
+  direct?: boolean;
+  env?: Readonly<Record<string, string>>;
+}
+/** Spawns a long-lived child and streams its output line by line. Injectable for tests. */
+type LongLivedSpawner = (descriptor: LongLivedDescriptor, onLine: (line: string, kind: "stderr" | "stdout") => void, onError?: (error: Error) => void) => WorkerProcess;
+/** A `--tunnel` request, built once from the parsed flags. */
+interface DevTunnelRequest {
+  /** Normalized `--allow-mail` entries, passed to cloudflared as `--allowed-mail`; empty opens a PUBLIC tunnel. */
+  allowMail: ReadonlyArray<string>;
+  /** Injection seam for tests — the one-shot spawner the `cloudflared --version` probe runs through. */
+  spawner?: Spawner;
+  /** Injection seam for tests — starts the long-lived `cloudflared tunnel` child. */
+  startChild?: LongLivedSpawner;
+}
 interface DevCommandOptions {
   /** Which API spec(s) the codegen watcher emits. Defaults to codegen's `"openapi"` when omitted. */
   apiSpec?: ApiSpec;
   /** Disable the codegen watch loop. */
   codegen?: boolean;
   cwd?: string;
+  /**
+   * Override where the binding manifest is written. One is always produced at
+   * `DEV_BINDINGS_FILE`; naming a path also makes a derivation failure
+   * fatal, since a named path means something is waiting on it.
+   */
+  emitBindings?: string;
   /** Injection seam for tests — defaults to the real `.dev.vars` scaffolder. */
   ensureEnv?: typeof ensureDevVariables;
   /** Injection seam for tests — defaults to the real `.dev.vars.example` package-aware scaffolder. */
   ensureExample?: typeof ensureDevVarsExample;
   /** Injection seam for tests — defaults to the real empty-secret/admin-token filler. */
   fillSecrets?: typeof fillDevSecrets;
+  /** Injection seam for tests — defaults to the real free-port probe (`findAvailablePort`). */
+  findFreePort?: (preferred: number) => Promise<number>;
+  /** Dev flavor override (tests / callers that already detected it) — defaults to `detectDevFlavor`. */
+  flavor?: DevFlavor;
+  /** Injection seam for tests — defaults to the real IPv6-loopback probe (`hasIpv6Loopback`). */
+  hasIpv6Loopback?: () => boolean;
+  /** `wrangler dev` devtools inspector port (`--inspector-port`). Wrangler flavor only — see `resolveInspectorPort`. */
+  inspectorPort?: number;
+  /**
+   * Logs are NDJSON on stdout (`--json`, or a detected AI agent). Forwarded to
+   * the codegen watcher so a `postcodegen` script's own stdout is routed to
+   * stderr instead of corrupting the stream.
+   */
+  jsonLogs?: boolean;
+  /** Pass `--local` to `wrangler dev`: no remote proxy session, so a binding with no local mode (`ai`) cannot stop the session from starting. */
+  local?: boolean;
   logger: Logger;
-  /** Injection seam for tests — defaults to the real remote-config materializer. */
-  materializeRemote?: typeof materializeRemoteWranglerConfig;
+  /** Injection seam for tests — defaults to the real dev-config materializer (remote bindings and the logged-out `ai` withholding). */
+  materializeDev?: typeof materializeDevWranglerConfig;
+  /** Injection seam for tests — defaults to the real per-service dev-config materializer. */
+  materializeServiceConfigs?: typeof materializeServiceDevConfigs;
   /** Studio server port. */
   port?: number;
+  /** Injection seam for tests — defaults to the real HTTP readiness probe. Without it the suite issues live GETs to the dev port. */
+  probeReady?: ReadinessProbe;
   /** Proxy D1/KV/R2 bindings to the deployed worker during dev (`LUNORA_REMOTE=1` / `--remote`); DO shards stay local. */
   remote?: boolean;
+  /** Starts the celld dev session for the celld target; injected in tests. */
+  startCelldSession?: typeof startCelldDevSession;
   /** Injection seam for tests — defaults to the real codegen watcher. */
   startCodegen?: typeof startCodegenWatch;
   /** Injection seam for tests — defaults to the real studio server. */
@@ -479,6 +985,21 @@ interface DevCommandOptions {
   startWorker?: WorkerSpawner;
   /** Disable the embedded studio server. */
   studio?: boolean;
+  /** Deploy target the emitted `ctx.*` surface is tailored to. Resolved by the caller; falls back to `"target"` in `lunora.config.*`, then `"cloudflare"`. */
+  target?: string;
+  /** `--tunnel`: share the worker's origin through a Cloudflare quick tunnel. Absent means no tunnel. */
+  tunnel?: DevTunnelRequest;
+  /**
+   * Injection seam for tests — defaults to parking until SIGINT.
+   *
+   * Attached mode (`--no-worker`) ends only on a signal, so without this the
+   * whole branch is unreachable from a test. That is how the readiness probe
+   * came to be wired after the early return, reported for a flavor it never
+   * covered, and shipped.
+   */
+  waitForInterrupt?: (logger: Logger) => Promise<number>;
+  /** Disable the `wrangler dev` spawn — an external task runner owns the worker. */
+  worker?: boolean;
   /** `wrangler dev` port. */
   workerPort?: number;
 }
@@ -486,69 +1007,129 @@ interface DevRemotePlan {
   /** Short binding labels remoted (e.g. `"DB (D1)"`), for the banner. */
   bindings: string[];
   /**
-  * Removes the generated temp wrangler config when dev exits. Always present
-  * and idempotent — a no-op when remote mode is off or nothing was
-  * materialized. The dev loop calls it on every shutdown path.
-  */
+   * Removes the generated temp wrangler config when dev exits. Always present
+   * and idempotent — a no-op when remote mode is off or nothing was
+   * materialized. The dev loop calls it on every shutdown path.
+   */
   cleanup: () => void;
   /** Whether remote mode was requested. */
   enabled: boolean;
   /** Why remote mode didn't take effect despite being requested, for logging. */
   reason?: string;
+  /** `ai` bindings a session left out for lack of Cloudflare credentials, for the banner warning. */
+  withheld: string[];
 }
 interface DevCommandPlan {
-  codegenEnabled: boolean;
+  /**
+   * `true` when the worker is a celld dev session (a target running its own
+   * dev server) rather than {@link DevCommandPlan.wrangler}'s process: services
+   * registered first, a service edit re-registering it and restarting the app.
+   */
+  celldSession?: true;
+  /** Which stack the child runs — see {@link DevFlavor}. */
+  flavor: DevFlavor;
+  /**
+   * One-line redirect hint printed when a meta-framework is detected on the
+   * wrangler flavor: without `@lunora/vite` in the dependencies the worker
+   * still runs *inside* the framework's dev server, so the user should run
+   * their framework dev script for the full app. `undefined` for the vite
+   * flavor (`lunora dev` already runs the project's dev script there) and
+   * for a standalone project. Purely informational: the wrangler spawn runs
+   * regardless.
+   */
+  frameworkHint?: string;
+  /**
+   * True when `wrangler dev` was given `--ip 127.0.0.1` because the host has no
+   * IPv6 loopback (`::1`) — surfaced so the dev loop can note the rebind.
+   * Always `false` for the vite flavor (the plugin owns its own bind).
+   */
+  ipv4LoopbackForced: boolean;
   /** The remote-binding decision: which D1/KV/R2 bindings hit the deployed worker. */
   remote: DevRemotePlan;
+  runsCodegenWatch: boolean;
+  /**
+   * Unlinks the copies of service configs written so a service's custom build
+   * runs in its own folder (`materializeServiceDevConfigs`). Idempotent; absent
+   * for a flavor that runs no services through a `wrangler dev` of its own.
+   */
+  serviceConfigCleanup?: () => void;
+  /**
+   * The `wrangler dev` sidecar for the `framework-worker` flavor (SvelteKit /
+   * Nuxt): a second child that owns the real `ShardDO` in `workerd`, wired via
+   * the committed `wrangler.dev.jsonc`. `undefined` for every other flavor —
+   * only the two-process class-B stack has a sidecar. When present, `wrangler`
+   * (above) is the framework's own dev server (the front door / HMR) and this
+   * is the Lunora realtime plane.
+   */
+  sidecar?: SpawnDescriptor & {
+    tag: string;
+  };
   studioEnabled: boolean;
   studioPort: number;
+  /**
+   * Whether this process spawns `wrangler dev`.
+   *
+   * `--no-worker` turns it off so an external task runner (Turbo, Nx, vis, a
+   * Procfile) can own worker supervision while `lunora dev` still provides
+   * codegen-watch and Studio. Without it, `lunora dev` insisted on being the
+   * process root, which is what blocked running the Lunora worker as one node
+   * in a larger dev graph.
+   */
+  workerEnabled: boolean;
   workerOrigin: string;
   workerPort: number;
-  /** The single child process `lunora dev` spawns: `wrangler dev`. */
+  /** The primary child `lunora dev` spawns: `wrangler dev` (wrangler flavor) or the framework/`vite dev` server (vite / framework-worker). */
   wrangler: SpawnDescriptor & {
     tag: string;
   };
 }
 /**
-* Resolve remote-binding mode into the extra `wrangler dev` args + a banner
-* summary. When `--remote`/`LUNORA_REMOTE` is set we materialize a temp wrangler
-* config with `"remote": true` on each D1/KV/R2 binding (Durable Object shards
-* stay local) and point `wrangler dev --config` at it, so the local worker reads
-* and writes the **deployed** resources. When disabled, or when there's nothing
-* to remote, the args stay empty and dev runs fully local.
-*/
-/**
-* Plan `lunora dev`: it runs the worker via `wrangler dev` and nothing else as a
-* child process. Vite is intentionally NOT spawned — a project may not use Vite,
-* and when it does, the `@lunora/vite` plugin already runs the worker inside
-* Vite, so the user runs `vite` themselves. Pure + synchronous so it's unit-testable.
-*/
-declare const planDevCommand: (options: DevCommandOptions) => DevCommandPlan;
-/**
-* Start codegen watch + the studio server, spawn `wrangler dev`, print the
-* banner, and resolve when the worker exits or the user interrupts — tearing
-* down the sibling servers either way. The three side-effecting pieces (worker,
-* studio, codegen) are injectable so this is testable without real I/O.
-*/
+ * Start codegen watch + the studio server, spawn `wrangler dev`, print the
+ * banner, and resolve when the worker exits or the user interrupts — tearing
+ * down the sibling servers either way. The three side-effecting pieces (worker,
+ * studio, codegen) are injectable so this is testable without real I/O.
+ */
 declare const runDevCommand: (options: DevCommandOptions) => Promise<{
   code: number;
   plan: DevCommandPlan;
 }>;
-/** `lunora dev` handler (lazy-loaded via the command's `loader`). */
+/**
+ * Plan `lunora dev`. Wrangler flavor: the worker runs via `wrangler dev` and
+ * nothing else as a child process. Vite flavor (`@lunora/vite` declared): the
+ * plugin already runs the worker inside the Vite dev server, so the one child
+ * is the project's own dev script (`vite dev`, `astro dev`, …) and every CLI
+ * sibling is disabled. Pure + synchronous so it's unit-testable.
+ */
+declare const planDevCommand: (options: DevCommandOptions) => DevCommandPlan;
 /** Supported CI providers. */
 type CiProvider = "github" | "gitlab";
-type PackageManager = "pnpm" | "npm" | "yarn" | "bun";
-/** True when `manager` is on PATH — probed by running `&lt;manager> --version`. Injectable for tests. */
-type PackageManagerProbe = (manager: PackageManager) => boolean;
-/**
-* The package managers actually installed on this machine, in preference order
-* ({@link INSTALL_PREFERENCE} — pnpm > bun > yarn > npm). The first entry is the
-* recommended default for the install prompt; the whole list is what the user
-* picks from. Empty when none are found.
-*/
+/**
+ * The per-framework auth-UI registry items (`auth-ui` resolves to one of these).
+ *
+ * Solid has two because these are copy-in source files, not a compiled package:
+ * the 1.x and 2.0 spellings are mutually exclusive in the source itself, so the
+ * two majors get one item each and {@link detectAuthUiItem} picks.
+ */
+type AuthUiItem = "auth-ui-angular" | "auth-ui-react" | "auth-ui-solid" | "auth-ui-solid-v2" | "auth-ui-svelte" | "auth-ui-vue";
 /** A registry item a feature can install. */
-type FeatureItem = "auth" | "auth-auth0" | "auth-clerk" | "mail";
-/** The auth-provider choices offered for `add auth` / the init auth prompt. Each value is a registry item name. */
+type FeatureItem = "auth" | "auth-auth0" | "auth-clerk" | AuthUiItem | "mail";
+/** One catalog entry as `lunora registry list` reports it. */
+interface CatalogItem {
+  description?: string;
+  name: string;
+}
+/** A built index entry (catalog item plus its short `title`). */
+interface IndexItem extends CatalogItem {
+  title?: string;
+}
+/**
+ * Build the catalog (`index.json` contents) from a local registry root by
+ * reading every item's `registry.json`. Used by both `lunora registry build`
+ * and the registry tests so the committed index can't drift from the item dirs.
+ */
+declare const buildRegistryIndex: (root: string) => {
+  items: IndexItem[];
+};
 /** A single file the item scaffolds into the project. */
 interface RegistryFile {
   /** Source path inside the item dir (e.g. `schema.ts`). */
@@ -564,10 +1145,10 @@ interface RegistryBinding {
   value: unknown;
 }
 /**
-* An environment variable an item needs. Scaffolded into `.dev.vars` (Workers'
-* local-secrets file) on add — non-secrets get their `value`; secrets get an
-* empty placeholder and a reminder to run `wrangler secret put` for production.
-*/
+ * An environment variable an item needs. Scaffolded into `.dev.vars` (Workers'
+ * local-secrets file) on add — non-secrets get their `value`; secrets get an
+ * empty placeholder and a reminder to run `wrangler secret put` for production.
+ */
 interface RegistryEnvVariable {
   /** Human note on what the variable is for. */
   description?: string;
@@ -578,6 +1159,13 @@ interface RegistryEnvVariable {
   /** A default/example value for non-secret vars. */
   value?: string;
 }
+/** A re-export the item needs injected into the worker entry point (class-B/C only). */
+interface EntrypointReexport {
+  /** Optional JS comment placed above the re-export line. */
+  comment?: string;
+  /** Module specifier (e.g. `"_generated/workflows"` → `export * from "./lunora/_generated/workflows"`). */
+  module: string;
+}
 /** The `registry.json` manifest shape. */
 interface RegistryManifest {
   /** wrangler.jsonc additions (best-effort structural edits). */
@@ -589,6 +1177,8 @@ interface RegistryManifest {
   devDependencies?: Readonly<Record<string, string>>;
   /** Post-install guidance printed after the item is added (per-item next steps). */
   docs?: string;
+  /** Worker-entry re-exports the item needs (class-B/C only). */
+  entrypointReexports?: ReadonlyArray<EntrypointReexport>;
   /** Environment variables the item needs; scaffolded into `.dev.vars`. */
   envVars?: ReadonlyArray<RegistryEnvVariable>;
   files: ReadonlyArray<RegistryFile>;
@@ -610,10 +1200,10 @@ interface AddCommandOptions {
   diff?: boolean;
   /** Print the plan and stop without writing anything. */
   dryRun?: boolean;
+  /** Output format: `pretty` (default) or `json` — a JSON snapshot of the plan/list. */
+  format?: OutputFormat;
   /** Local registry root (offline / tests). Expects per-item subdirs, each with a `registry.json`. */
   from?: string;
-  /** Emit a JSON snapshot of the plan/result. */
-  json?: boolean;
   /** `--list`: enumerate available items instead of adding. */
   list?: boolean;
   logger: Logger;
@@ -628,19 +1218,51 @@ interface AddCommandOptions {
   /** Override the remote registry source base (default gh:anolilab/lunora/registry). */
   source?: string;
   /**
-  * Customize each resolved manifest after it is loaded but before the plan is
-  * printed / reconciled — used to inject user-chosen values into otherwise
-  * static manifests (e.g. the R2 `bucket_name` the init storage prompt asks
-  * for). Applied to every item; return the manifest unchanged to leave it as-is.
-  */
+   * Customize each resolved manifest after it is loaded but before the plan is
+   * printed / reconciled — used to inject user-chosen values into otherwise
+   * static manifests (e.g. the R2 `bucket_name` the init storage prompt asks
+   * for). Applied to every item; return the manifest unchanged to leave it as-is.
+   */
   transformManifest?: (manifest: RegistryManifest) => RegistryManifest;
   /** Skip the package.json mutation confirmation prompt. */
   yes?: boolean;
 }
-interface AddCommandResult {
+/**
+ * One item in the `--format json` plan snapshot. Carries the concrete binding
+ * VALUES, not just the key paths, so a plan consumer can audit the mutation
+ * before it is applied.
+ */
+interface RegistryPlanItem {
+  bindings: {
+    path: string;
+    value: unknown;
+  }[];
+  deps: string[];
+  devDependencies: string[];
+  entrypointReexports: {
+    comment?: string;
+    module: string;
+  }[];
+  envVars: {
+    name: string;
+    secret?: boolean;
+    value?: string;
+  }[];
+  files: {
+    merge: RegistryFile["merge"];
+    to: string;
+  }[];
+  name: string;
+  requires: ReadonlyArray<string>;
+  title?: string;
+}
+/** The `--format json` payload: the catalog (`list`) or the resolved plan (`add`). */
+interface RegistryCommandData {
+  items: ReadonlyArray<CatalogItem | RegistryPlanItem>;
+}
+interface AddCommandResult extends CommandResult<RegistryCommandData> {
   /** Bindings written to wrangler.jsonc. */
   bindings: ReadonlyArray<string>;
-  code: number;
   /** Deps added to package.json. */
   deps: ReadonlyArray<string>;
   /** Files skipped because they already existed. */
@@ -648,21 +1270,20 @@ interface AddCommandResult {
   /** Files written (absolute paths). */
   written: ReadonlyArray<string>;
 }
-/** One resolved item: its parsed manifest plus the (possibly staged) directory it lives in. */
 /**
-* A feature offered in the post-scaffold multi-select. `auth`/`email` carry a
-* sub-prompt or alias; every other value IS the registry item name applied
-* directly (`storage` → the `storage` registry item, etc.).
-*/
-type StackFeature = "auth" | "backup" | "crons" | "email" | "presence" | "ratelimit" | "storage";
+ * A feature offered in the post-scaffold multi-select. `auth`/`email` carry a
+ * sub-prompt or alias; every other value IS the registry item name applied
+ * directly (`storage` → the `storage` registry item, etc.).
+ */
+type StackFeature = "ai" | "auth" | "auth-ui" | "backup" | "browser" | "cloudflare-access" | "crons" | "email" | "flags" | "hyperdrive" | "payment" | "presence" | "queue" | "storage" | "workflow";
 /** Customize a resolved manifest before it is written (e.g. inject the chosen R2 bucket name). */
 type OfferTransformManifest = (manifest: RegistryManifest) => RegistryManifest;
 /**
-* One feature ready to apply: the registry item name(s), an optional manifest
-* transform, and a short `label` (the feature value) shown on the combined
-* progress line. Built up-front by the collectors so every prompt is answered
-* before any apply runs.
-*/
+ * One feature ready to apply: the registry item name(s), an optional manifest
+ * transform, and a short `label` (the feature value) shown on the combined
+ * progress line. Built up-front by the collectors so every prompt is answered
+ * before any apply runs.
+ */
 interface FeatureApply {
   label: string;
   names: ReadonlyArray<string>;
@@ -670,11 +1291,11 @@ interface FeatureApply {
 }
 interface OfferDeps {
   /**
-  * Apply the collected features into the new project in one batch — resolves
-  * `true` when every item succeeds. The CLI renders this as a single progress
-  * line whose label changes per feature; each plan's `transformManifest`
-  * customizes that item's manifest before it is written.
-  */
+   * Apply the collected features into the new project in one batch — resolves
+   * `true` when every item succeeds. The CLI renders this as a single progress
+   * line whose label changes per feature; each plan's `transformManifest`
+   * customizes that item's manifest before it is written.
+   */
   applyAll: (plans: ReadonlyArray<FeatureApply>) => Promise<boolean>;
   /** When `false`, skip all prompts and print the later-setup hint. */
   interactive: boolean;
@@ -688,13 +1309,24 @@ interface OfferDeps {
     defaults?: ReadonlyArray<StackFeature>;
   }) => Promise<StackFeature[]>;
   /**
-  * Features chosen non-interactively (the `--add` flag). When set, the
-  * multi-select and every sub-prompt are skipped — each feature is applied with
-  * its shipped defaults (base registry item, placeholder bindings).
-  */
+   * Features chosen non-interactively (the `--add` flag). When set, the
+   * multi-select and every sub-prompt are skipped — each feature is applied with
+   * its shipped defaults (base registry item, placeholder bindings).
+   */
   preselected?: ReadonlyArray<StackFeature>;
   /** The new project's name — seeds smart defaults like the `project-uploads` bucket name. */
   projectName: string;
+  /**
+   * Resolve which per-framework auth-UI item (`auth-ui-react|vue|…`) fits the
+   * scaffolded project. Injected by the CLI (detected from the template's deps);
+   * defaults to `auth-ui-react` when absent so this module stays pure/testable.
+   *
+   * `undefined` is a REFUSAL, not "unknown": no auth-UI item fits this project
+   * (React Native). `lunora add auth-ui` already refuses there, and this offer
+   * used to `?? "auth-ui-react"` its way past that — copying ~85 DOM files into
+   * an Expo app and exiting 0.
+   */
+  resolveAuthUiItem?: () => string | undefined;
   /** Single-select among the auth providers (TTY-backed in production). */
   select: (message: string, options: ReadonlyArray<{
     description?: string;
@@ -709,114 +1341,127 @@ interface OfferDeps {
     placeholder?: string;
   }) => Promise<string>;
 }
-/**
-* Offer the stack features (auth, email, storage, rate limiting, crons,
-* presence, backups) in ONE multi-select after a successful scaffold. Auth,
-* email, and storage run a follow-up prompt (provider / destination / bucket
-* name); every other feature value is applied as its registry item directly.
-*
-* Every question is asked FIRST (in selection order), then the picked features
-* are applied together via {@link OfferDeps.applyAll} — the CLI renders that as a
-* single progress line whose label changes per feature, instead of one spinner
-* per item. Non-interactive: prints how to add them later and changes nothing.
-*/
-type Template = "analog" | "astro" | "next" | "nuxt" | "react-router" | "standalone" | "sveltekit" | "tanstack-start-react" | "tanstack-start-solid";
+/** One choice in the multi-select. */
+interface LintToolOption {
+  description: string;
+  label: string;
+  value: LintTool;
+}
+interface LintToolOfferDeps {
+  /** Write the ignores for the chosen tools — `applyLintIgnores` in production. */
+  apply: (tools: ReadonlyArray<LintTool>) => LintIgnoreOutcome[];
+  /** Tools already detectable in the scaffolded project — pre-selected in the prompt. */
+  detected: ReadonlyArray<LintTool>;
+  /** False in CI / `--yes` / off a TTY: skip the prompt and configure whatever was detected. */
+  interactive: boolean;
+  logger: Logger;
+  multiSelect: (message: string, choices: ReadonlyArray<LintToolOption>, settings?: {
+    defaults?: ReadonlyArray<LintTool>;
+  }) => Promise<LintTool[]>;
+}
+type Template = "analog" | "astro" | "expo" | "next" | "nuxt" | "react-router" | "rspack-react" | "solid-v2" | "standalone" | "sveltekit" | "tanstack-start-react" | "tanstack-start-react-rspack" | "tanstack-start-solid" | "vinext" | "vinext-pages";
 interface InitCommandOptions {
   /**
-  * Add features non-interactively after scaffolding (the `--add` flag): a
-  * comma-separated list of `auth | email | storage | ratelimit | crons |
-  * presence | backup`. Bypasses the interactive multi-select and sub-prompts —
-  * each named feature is applied with its shipped defaults.
-  */
+   * Add features non-interactively after scaffolding (the `--add` flag): a
+   * comma-separated list of `ai | auth | auth-ui | backup | browser | cloudflare-access | crons | email | flags | hyperdrive | payment | presence | queue | storage | workflow`.
+   * Bypasses the interactive multi-select and sub-prompts —
+   * each named feature is applied with its shipped defaults.
+   */
   add?: string;
   /**
-  * When true, accept `--source` values that don't start with `gh:` /
-  * `github:` / `https://` or that contain `..`. Defaults to false; the CLI
-  * gate exists to stop arbitrary filesystem / scheme sources from being
-  * pulled without the caller opting in.
-  */
+   * When true, accept `--source` values that don't start with `gh:` /
+   * `github:` / `https://` or that contain `..`. Defaults to false; the CLI
+   * gate exists to stop arbitrary filesystem / scheme sources from being
+   * pulled without the caller opting in.
+   */
   allowUnsafeSource?: boolean;
   /** When set, also scaffold a CI deploy pipeline for the given provider. */
   ci?: CiProvider;
   cwd?: string;
   /**
-  * Walk the whole flow — prompts, task list, next-steps, mascot — but make no
-  * changes: skip the template fetch/copy, the feature applies, the dependency
-  * install, and `git init`. Each skipped action logs a `would …` line instead.
-  */
+   * Walk the whole flow — prompts, task list, next-steps, mascot — but make no
+   * changes: skip the template fetch/copy, the feature applies, the dependency
+   * install, and `git init`. Each skipped action logs a `would …` line instead.
+   */
   dryRun?: boolean;
   /**
-  * Local directory containing the template subdirs (e.g. `vite/`,
-  * `standalone/`). When provided, skips the network fetch entirely.
-  * Useful for offline runs, the clean-machine smoke test, and unit tests.
-  */
+   * Local directory containing the template subdirs (e.g. `vite/`,
+   * `standalone/`). When provided, skips the network fetch entirely.
+   * Useful for offline runs, the clean-machine smoke test, and unit tests.
+   */
   from?: string;
   /**
-  * When true, configure Lunora into the CURRENT project (`cwd`) instead of
-  * scaffolding a new directory. Finds an existing `vite.config.*` and
-  * patches it via `patchViteConfig`, or creates a minimal one when absent.
-  * All other scaffold options (`name`, `templateType`, `source`, `from`)
-  * are ignored in this mode.
-  */
+   * When true, configure Lunora into the CURRENT project (`cwd`) instead of
+   * scaffolding a new directory. Finds an existing `vite.config.*` and
+   * patches it via `patchViteConfig`, or creates a minimal one when absent.
+   * All other scaffold options (`name`, `templateType`, `source`, `from`)
+   * are ignored in this mode.
+   */
   inPlace?: boolean;
   /**
-  * Inject the post-scaffold install offer's prompts (tests). When set, the
-  * offer runs regardless of TTY: `confirmInstall` drives the yes/no, and
-  * `selectManager` picks among the detected managers.
-  */
+   * Inject the post-scaffold install offer's prompts (tests). When set, the
+   * offer runs regardless of TTY: `confirmInstall` drives the yes/no, and
+   * `selectManager` picks among the detected managers.
+   */
   installPrompt?: {
     confirmInstall: () => Promise<boolean>;
     selectManager: (managers: ReadonlyArray<PackageManager>) => Promise<PackageManager>;
   };
   /**
-  * Force the post-scaffold "add auth / email?" offer on (the `--interactive`
-  * flag). When omitted, the offer runs only when stdin is a TTY. `--yes`
-  * suppresses it regardless. Has no effect once {@link prompt} is injected.
-  */
+   * Force the post-scaffold "add auth / email?" offer on (the `--interactive`
+   * flag). When omitted, the offer runs only when stdin is a TTY. `--yes`
+   * suppresses it regardless. Has no effect once {@link prompt} is injected.
+   */
   interactive?: boolean;
+  /**
+   * Test seam for the lint/formatter multi-select. Separate from {@link prompt}
+   * because that one is pinned to the feature-offer's value union — reusing it
+   * here would only typecheck through a cast.
+   */
+  lintPrompt?: LintToolOfferDeps["multiSelect"];
   logger: Logger;
   name?: string;
   /**
-  * Local directory holding create-vite bases (one `template-&lt;id>/` subdir per
-  * framework). When set with `vite`, the overlay copies the base from disk
-  * instead of fetching `create-vite` over the network — offline mode + tests.
-  */
+   * Local directory holding create-vite bases (one `template-<id>/` subdir per
+   * framework). When set with `vite`, the overlay copies the base from disk
+   * instead of fetching `create-vite` over the network — offline mode + tests.
+   */
   overlayBaseFrom?: string;
-  /** Probe for which package managers are installed (tests). Defaults to a real `&lt;pm> --version` check. */
+  /** Probe for which package managers are installed (tests). Defaults to a real `<pm> --version` check. */
   packageManagerProbe?: PackageManagerProbe;
   /**
-  * Inject the offer's prompts (tests). When set, the offer is treated as
-  * interactive regardless of TTY, and these drive the feature multi-select,
-  * the auth-provider sub-select, and the storage bucket-name text input.
-  */
+   * Inject the offer's prompts (tests). When set, the offer is treated as
+   * interactive regardless of TTY, and these drive the feature multi-select,
+   * the auth-provider sub-select, and the storage bucket-name text input.
+   */
   prompt?: Pick<OfferDeps, "multiSelect" | "select" | "text">;
   /**
-  * Override the git ref (branch, tag, or commit) the default template source
-  * is fetched from. Takes precedence over the version-derived ref. Ignored
-  * when `source` or `from` is set.
-  */
+   * Override the git ref (branch, tag, or commit) the default template source
+   * is fetched from. Takes precedence over the version-derived ref. Ignored
+   * when `source` or `from` is set.
+   */
   ref?: string;
   /** Local registry root for the offer's `runAddCommand` (offline / tests). Mirrors `from` but for registry items. */
   registryFrom?: string;
   /** Override the remote registry source base for the offer (default `gh:anolilab/lunora/registry`). */
   registrySource?: string;
   /**
-  * Override the remote source giget downloads from. Default:
-  * `gh:anolilab/lunora/templates/&lt;templateType>#&lt;ref>`, where `&lt;ref>` is
-  * the `ref` option when set, else derived from the CLI version (pre-release
-  * channels → their branch, stable → `main`). Tests typically use `from`
-  * instead to skip the network.
-  */
+   * Override the remote source giget downloads from. Default:
+   * `gh:anolilab/lunora/templates/<templateType>#<ref>`, where `<ref>` is
+   * the `ref` option when set, else derived from the CLI version (pre-release
+   * channels → their branch, stable → `main`). Tests typically use `from`
+   * instead to skip the network.
+   */
   source?: string;
   /** Spawner for the post-scaffold dependency install (tests inject a recording stub). Defaults to a real subprocess. */
   spawner?: Spawner;
   templateType?: Template;
   /**
-  * Scaffold via the **create-vite overlay** for this framework (`react`,
-  * `vue`, `solid`, `svelte`, `vanilla`) instead of a bespoke template: fetch
-  * the official create-vite base and apply the Lunora layer on top. Takes
-  * precedence over `templateType`.
-  */
+   * Scaffold via the **create-vite overlay** for this framework (`react`,
+   * `vue`, `solid`, `svelte`, `vanilla`) instead of a bespoke template: fetch
+   * the official create-vite base and apply the Lunora layer on top. Takes
+   * precedence over `templateType`.
+   */
   vite?: string;
   /** Suppress the offer entirely (the `--yes` flag): scaffold only, print the later-setup hint. */
   yes?: boolean;
@@ -826,8 +1471,12 @@ interface InitCommandResult {
   files: ReadonlyArray<string>;
   target: string;
 }
+/**
+ * `lunora init` entry: scaffold (in-place or a new directory), then — on success
+ * — offer to add auth + email via the registry. The offer never affects the
+ * scaffold's exit code.
+ */
 declare const runInitCommand: (options: InitCommandOptions) => Promise<InitCommandResult>;
-/** Narrow a raw `--template` value to a known {@link Template}. */
 interface MigrateGenerateCommandOptions {
   cwd?: string;
   logger: Logger;
@@ -840,42 +1489,25 @@ interface MigrateGenerateCommandResult {
   code: number;
   /** Whether the diff was empty (no changes detected). */
   empty: boolean;
+  /** Why it failed, when the reason is known — the shared `CommandResult` contract. */
+  error?: string;
   /** Absolute path to the migration file (empty string when nothing was written). */
   migrationFile: string;
 }
 declare const runMigrateGenerateCommand: (options: MigrateGenerateCommandOptions) => MigrateGenerateCommandResult;
-/** One catalog entry as `lunora registry list` reports it. */
-interface CatalogItem {
-  description?: string;
-  name: string;
-}
-/** A built index entry (catalog item plus its short `title`). */
-interface IndexItem extends CatalogItem {
-  title?: string;
-}
-/** Names of the subdirectories under `root` that ship a `registry.json`. */
-
-/**
-* Build the catalog (`index.json` contents) from a local registry root by
-* reading every item's `registry.json`. Used by both `lunora registry build`
-* and the registry tests so the committed index can't drift from the item dirs.
-*/
-declare const buildRegistryIndex: (root: string) => {
-  items: IndexItem[];
-};
 /** `lunora registry add` (one or more item names): scaffold items into the project. */
 declare const runAddCommand: (options: AddCommandOptions) => Promise<AddCommandResult>;
 /**
-* `lunora registry view` — inspect a registry item without installing it:
-* print its plan (files / deps / env vars) followed by the full contents of each
-* file it would scaffold. Resolves only the named item — no `requires` expansion.
-*/
+ * `lunora registry view` — inspect a registry item without installing it:
+ * print its plan (files / deps / env vars) followed by the full contents of each
+ * file it would scaffold. Resolves only the named item — no `requires` expansion.
+ */
 declare const runRegistryViewCommand: (options: AddCommandOptions) => Promise<AddCommandResult>;
 /**
-* `lunora registry build` — regenerate `index.json` from the item directories
-* (the catalog `list` reads). With `--check`, verify the committed index matches
-* instead of rewriting it (exits non-zero on drift) — a CI guard.
-*/
+ * `lunora registry build` — regenerate `index.json` from the item directories
+ * (the catalog `list` reads). With `--check`, verify the committed index matches
+ * instead of rewriting it (exits non-zero on drift) — a CI guard.
+ */
 declare const runBuildIndexCommand: (options: AddCommandOptions) => Promise<AddCommandResult>;
 /** Validate + narrow a parsed JSON value into a {@link RegistryManifest}. */
 declare const parseManifest: (raw: unknown, itemName: string) => RegistryManifest;
@@ -893,23 +1525,6 @@ interface ResetCommandResult {
   removed: ReadonlyArray<string>;
 }
 declare const runResetCommand: (options: ResetCommandOptions) => Promise<ResetCommandResult>;
-/** `lunora reset` handler (lazy-loaded via the command's `loader`). */
-/**
-* Tiny argv parser.
-*
-* Supports long options (`--name value`, `--name=value`, `--flag`), short
-* options (`-x value`, `-xvalue`), positional arguments (everything else, in
-* order), and a `--` terminator after which everything is positional.
-*
-* Intentionally small — replaces a full CLI library for the handful of
-* subcommands we need.
-*/
-interface ParsedArgs {
-  flags: Record<string, boolean>;
-  options: Record<string, string>;
-  positional: ReadonlyArray<string>;
-}
-declare const parseArgs: (argv: ReadonlyArray<string>, booleanFlags?: ReadonlySet<string>) => ParsedArgs;
 type InsertSchemaExtensionResult = {
   ok: true;
   text: string;
@@ -918,12 +1533,12 @@ type InsertSchemaExtensionResult = {
   reason: "already-applied" | "invalid-identifier" | "no-define-schema" | "non-object-argument";
 };
 /**
-* Append `.extend(&lt;key>.extension)` and a managed import to an existing
-* `lunora/schema.ts`. Idempotent: a second call for the same `key` returns
-* `already-applied` and leaves the text unchanged.
-* @param source the current `lunora/schema.ts` contents
-* @param key the registry item key (e.g. `"ratelimit"`)
-*/
+ * Append `.extend(<key>.extension)` and a managed import to an existing
+ * `lunora/schema.ts`. Idempotent: a second call for the same `key` returns
+ * `already-applied` and leaves the text unchanged.
+ * @param source the current `lunora/schema.ts` contents
+ * @param key the registry item key (e.g. `"ratelimit"`)
+ */
 declare const insertSchemaExtension: (source: string, key: string) => InsertSchemaExtensionResult;
 /** Compact snapshot of a single global table — what we persist + diff. */
 interface TableSnapshot {
@@ -933,6 +1548,20 @@ interface TableSnapshot {
   name: string;
 }
 interface ColumnSnapshot {
+  /**
+   * The column's full validator shape — the SAME {@link FieldSnapshot} the
+   * deploy gate diffs (`shared/schema-snapshot.ts`), not a second parallel
+   * format.
+   *
+   * `sqlType` alone is lossy: `bigint`, `array`, `record`, `id`, `literal` and
+   * `string` all map to the TEXT affinity, so `v.string()` → `v.bigint()` was
+   * byte-identical here and `migrate generate` answered "no schema changes
+   * detected" for a change `lunora prepare` blocks as breaking.
+   *
+   * Optional so a `.snapshot.json` written before this existed still parses —
+   * it simply gets no deep check until the next generate rewrites it.
+   */
+  field?: FieldSnapshot;
   /** True when the column accepts NULL (validator wrapped in v.optional). */
   nullable: boolean;
   /** SQLite type affinity, derived from the validator. */
@@ -966,26 +1595,42 @@ interface SchemaDiff {
   unsupported: ReadonlyArray<UnsupportedEntry>;
 }
 /**
-* Map a Lunora validator kind to a SQLite type affinity — the canonical
-* `@lunora/d1/dialect` mapping. Re-exported under this name because
-* `schema-snapshot.ts` builds the persisted snapshot from it.
-*/
+ * Map a Lunora validator kind to a SQLite type affinity — the canonical
+ * `@lunora/d1/dialect` mapping. Re-exported under this name because
+ * `schema-snapshot.ts` builds the persisted snapshot from it.
+ */
 declare const validatorKindToSqlType: (kind: string) => ColumnSnapshot["sqlType"];
-/** Emit `CREATE TABLE` SQL for a new global table. */
+/**
+ * Emit `CREATE TABLE` SQL for a new global table.
+ *
+ * Refuses a table past D1's column ceiling rather than writing SQL that
+ * `lunora migrate up` will reject: the runtime auto-provisioner checks the same
+ * number, and a migration file is the worse place to find out — the failure
+ * lands later, against a database, with none of the schema context that names
+ * which table and field to split.
+ */
 declare const renderCreateTable: (table: TableSnapshot) => string;
 declare const renderDropTable: (tableName: string) => string;
+/**
+ * `ALTER TABLE … ADD COLUMN`, always nullable. SQLite rejects `ADD COLUMN … NOT NULL` without a default on a table
+ * that already has rows, and D1 is SQLite, so a NOT NULL add fails exactly when it matters. The runtime
+ * auto-provisioner makes the same choice (see `alterGlobalTableDrift` in `@lunora/sql-store`), and the declared
+ * `notNull` is still enforced on write. Existing rows read the new column as NULL until they are written, so for a
+ * required column the statement is followed by a comment that says so and gives the backfill to run. The snapshot
+ * records no default value, so the value is left for the author to fill in rather than guessed.
+ */
 declare const renderAddColumn: (tableName: string, columnName: string, column: ColumnSnapshot) => string;
 declare const renderCreateIndex: (tableName: string, index: IndexSnapshot) => string;
 declare const renderDropIndex: (tableName: string, indexName: string) => string;
 /**
-* Compute a {@link SchemaDiff} from two snapshots. Pure function — no I/O.
-*/
+ * Compute a {@link SchemaDiff} from two snapshots. Pure function — no I/O.
+ */
 declare const diffSnapshots: (previous: SchemaSnapshot | undefined, next: SchemaSnapshot) => SchemaDiff;
 /**
-* Render a complete migration file body from a diff. Includes a header,
-* each SQL statement, and (if any) a trailing comment block describing the
-* manual SQL the user needs to fill in for unsupported deltas.
-*/
+ * Render a complete migration file body from a diff. Includes a header,
+ * each SQL statement, and (if any) a trailing comment block describing the
+ * manual SQL the user needs to fill in for unsupported deltas.
+ */
 declare const renderMigrationFile: (name: string, diff: SchemaDiff, generatedAt: string) => string;
 declare const schemaIrToSnapshot: (ir: SchemaIR) => SchemaSnapshot;
-export { type AddCommandOptions, type AddCommandResult, COMMANDS, type ColumnSnapshot, type CommandName, DEFAULT_IMPORT_BATCH_SIZE, type DeployCommandOptions, type DeployCommandResult, type DevCommandOptions, type DevCommandPlan, type DiffEntry, type ExportCommandOptions, type ExportCommandResult, type FetchLike, type ImportCommandOptions, type ImportCommandResult, type IndexSnapshot, type InitCommandOptions, type InitCommandResult, type InsertSchemaExtensionResult, type Logger, type MigrateGenerateCommandOptions, type MigrateGenerateCommandResult, type RecordedSpawn, type RegistryBinding, type RegistryFile, type RegistryManifest, type ResetCommandOptions, type ResetCommandResult, type RunCliOptions, type RunCommandOptions, type RunCommandResult, type SchemaDiff, type SchemaSnapshot, type SpawnDescriptor, type SpawnResult, type Spawner, type StreamingFetchLike, type TableSnapshot, type Template, type UnsupportedEntry, VERSION, buildRegistryIndex, createLogger, createRecordingSpawner, defaultSpawner, diffSnapshots, insertSchemaExtension, pail, parseArgs, parseManifest, planDevCommand, renderAddColumn, renderCreateIndex, renderCreateTable, renderDropIndex, renderDropTable, renderMigrationFile, runAddCommand, runBuildIndexCommand, runCli, runCodegenCommand, runDeployCommand, runDevCommand, runExportCommand, runImportCommand, runInitCommand, runMigrateGenerateCommand, runRegistryViewCommand, runResetCommand, runRpcCommand, schemaIrToSnapshot, validatorKindToSqlType };
+export { type AddCommandOptions, type AddCommandResult, COMMANDS, type ColumnSnapshot, type CommandName, DEFAULT_IMPORT_BATCH_SIZE, type DeployCommandOptions, type DeployCommandResult, type DeployedIdentity, type DevCommandOptions, type DevCommandPlan, type DiffEntry, EXIT_CODE, type ExitCode, type ExportCommandOptions, type ExportCommandResult, type FetchLike, type ImportCommandOptions, type ImportCommandResult, type IndexSnapshot, type InitCommandOptions, type InitCommandResult, type InsertSchemaExtensionResult, type Logger, type MigrateGenerateCommandOptions, type MigrateGenerateCommandResult, type RecordedSpawn, type RegistryBinding, type RegistryFile, type RegistryManifest, type ResetCommandOptions, type ResetCommandResult, type RunCliOptions, type RunCommandOptions, type RunCommandResult, type SchemaDiff, type SchemaSnapshot, type SpawnDescriptor, type SpawnResult, type Spawner, type StreamingFetchLike, type TableSnapshot, type Template, type UnsupportedEntry, VERSION, buildRegistryIndex, createLogger, createRecordingSpawner, defaultSpawner, diffSnapshots, exitCodeForCode, exitCodeForError, exitCodeForStatus, insertSchemaExtension, pail, parseManifest, planDevCommand, renderAddColumn, renderCreateIndex, renderCreateTable, renderDropIndex, renderDropTable, renderMigrationFile, runAddCommand, runBuildIndexCommand, runCli, runCodegenCommand, runDeployCommand, runDevCommand, runExportCommand, runImportCommand, runInitCommand, runMigrateGenerateCommand, runRegistryViewCommand, runResetCommand, runRpcCommand, schemaIrToSnapshot, validatorKindToSqlType };