@lunora/cli 1.0.0-alpha.248 → 1.0.0-alpha.249

package/dist/bin.mjs

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import{r as e}from"./packem_shared/cli-CbScYTbi.mjs";try{const r=await e();process.exit(r)}catch(r){process.stderr.write(`${r instanceof Error?r.message:String(r)}
+import{r as e}from"./packem_shared/cli-CSnnYlA3.mjs";try{const r=await e();process.exit(r)}catch(r){process.stderr.write(`${r instanceof Error?r.message:String(r)}
 `),process.exit(1)}

package/dist/index.d.mts

@@ -58,12 +58,53 @@ declare const createLogger: () => Logger;
  * the package barrel) stays side-effect-free.
  */
 declare const pail: PailLogger;
+/**
+ * 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
@@ -74,7 +115,8 @@ interface CodegenCommandOptions {
   /** 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: Finding["level"];
@@ -82,12 +124,21 @@ interface CodegenCommandResult {
     remediation: string;
   }>;
   cronTriggers: ReadonlyArray<string>;
-  /** Set when the run failed: an invalid `--format`, an unregistered target, or an error-level platform diagnostic. */
-  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;
 /**
  * Minimal projection of `globalThis.fetch` for the transfer commands: `body` is
@@ -111,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;
@@ -123,9 +180,17 @@ 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;
 }
@@ -213,6 +278,8 @@ 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
@@ -284,9 +351,15 @@ interface ImportSummary {
   };
   warnings?: string[];
 }
-interface ImportCommandResult {
+/** 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;
-  code: number;
   /** Total inserted rows across batches. */
   inserted: number;
 }
@@ -296,6 +369,50 @@ declare const runImportCommand: (options: ImportCommandOptions) => Promise<Impor
  * stub; production uses {@link isDockerAvailable}.
  */
 type DockerProbe = () => boolean;
+/**
+ * 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;
 /**
  * The shared `/_lunora/health` probe used by `lunora verify --health-url` and
  * `lunora deploy --health-check`.
@@ -429,6 +546,8 @@ interface RunCommandOptions {
   claims?: string;
   cwd?: string;
   fetchImpl?: FetchLike;
+  /** Output format: `pretty` (default) or `json`. */
+  format?: OutputFormat;
   functionPath: string;
   logger: Logger;
   shard?: string;
@@ -439,6 +558,8 @@ interface RunCommandOptions {
 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>;
@@ -474,7 +595,7 @@ interface DeployCommandOptions {
   /** 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
@@ -651,9 +772,9 @@ interface DeployCommandResult {
  */
 type PreDeployCommand = "build" | "deploy" | "prepare";
 /**
- * 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.
+ * 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>;
 /**
@@ -945,6 +1066,23 @@ type CiProvider = "github" | "gitlab";
 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" | 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`). */
@@ -1015,10 +1153,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;
@@ -1042,10 +1180,42 @@ interface AddCommandOptions {
   /** 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. */
@@ -1272,27 +1442,12 @@ 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;
-}
-/**
- * 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>;
 /**
@@ -1423,4 +1578,4 @@ declare const diffSnapshots: (previous: SchemaSnapshot | undefined, next: Schema
  */
 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 DeployedIdentity, 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, 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 };