@lunora/cli 1.0.0-alpha.1 → 1.0.0-alpha.100

package/dist/packem_chunks/runMigrateGenerateCommand.mjs

@@ -1,14 +1,16 @@
-import { existsSync, mkdirSync, writeFileSync, readFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync, mkdtempSync, rmSync, readFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { discoverMigrations, discoverSchema } from '@lunora/codegen';
+import { discoverSchema, discoverMigrations } from '@lunora/codegen';
+import { isInteractive, promptSelect, promptText } from '@lunora/config';
+import { LunoraError } from '@lunora/errors';
 import { join } from '@visulima/path';
 import { Project } from 'ts-morph';
 import { r as resolveAdminBaseUrl } from '../packem_shared/admin-url-4UzT-CI4.mjs';
-import { d as defineHandler } from '../packem_shared/command-BDXcJCCJ.mjs';
-import { diffSnapshots, renderMigrationFile } from '../packem_shared/diffSnapshots-RR2ZE8Ya.mjs';
+import { d as defineHandler } from '../packem_shared/command-lYnl4QyF.mjs';
+import { diffSnapshots, renderMigrationFile } from '../packem_shared/diffSnapshots-BeDvvNiF.mjs';
 import { a as resolveProductionWorkerUrl } from '../packem_shared/resolve-target-qbsJ_5sF.mjs';
-import schemaIrToSnapshot from '../packem_shared/schemaIrToSnapshot-aBTo7TM5.mjs';
-import { runExportCommand, runImportCommand } from '../packem_shared/DEFAULT_IMPORT_BATCH_SIZE-Ck-2bU08.mjs';
+import schemaIrToSnapshot from '../packem_shared/schemaIrToSnapshot-DdsljJT-.mjs';
+import { runExportCommand, runImportCommand } from '../packem_shared/DEFAULT_IMPORT_BATCH_SIZE-D0VOTerB.mjs';
 
 const SNAPSHOT_FILENAME = ".snapshot.json";
 const NON_ALPHANUMERIC = /[^\da-z]+/gu;
@@ -41,12 +43,12 @@ const loadSnapshot = (path) => {
     const raw = readFileSync(path, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed.version !== 1) {
-      throw new Error(`unsupported snapshot version: ${parsed.version}`);
+      throw new LunoraError("INTERNAL", `unsupported snapshot version: ${parsed.version}`);
     }
     return parsed;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`failed to read ${path}: ${message}`, { cause: error });
+    throw new LunoraError("INTERNAL", `failed to read ${path}: ${message}`, { cause: error });
   }
 };
 const runMigrateGenerateCommand = (options) => {
@@ -151,7 +153,47 @@ const camelCase = (slug) => slug.split("-").filter((part) => part.length > 0).ma
   }
   return part.charAt(0).toUpperCase() + part.slice(1);
 }).join("");
-const runMigrateCreateCommand = (options) => {
+const discoverKnownTables = (cwd) => {
+  const schemaPath = join(cwd, "lunora", "schema.ts");
+  if (!existsSync(schemaPath)) {
+    return [];
+  }
+  try {
+    const project = new Project({ skipAddingFilesFromTsConfig: true });
+    return discoverSchema(project, schemaPath).tables.map((table) => table.name);
+  } catch {
+    return [];
+  }
+};
+const promptForTable = async (tables) => {
+  if (tables.length > 0) {
+    return promptSelect(
+      "Which table does this migration iterate?",
+      tables.map((name) => {
+        return { label: name, value: name };
+      })
+    );
+  }
+  return promptText("Target table for the migration: ");
+};
+const resolveCreateTable = async (cwd, options) => {
+  if (options.table !== void 0) {
+    return options.table;
+  }
+  const prompt = options.promptTable ?? (isInteractive() ? promptForTable : void 0);
+  if (prompt === void 0) {
+    options.logger.error("migrate create requires a target table when not running interactively — re-run with --table <table>");
+    return void 0;
+  }
+  const answer = await prompt(discoverKnownTables(cwd));
+  const table = answer?.trim();
+  if (table === void 0 || table === "") {
+    options.logger.error("no table selected — re-run with --table <table>");
+    return void 0;
+  }
+  return table;
+};
+const runMigrateCreateCommand = async (options) => {
   const cwd = options.cwd ?? process.cwd();
   const slug = kebabCase(options.name);
   if (slug === "") {
@@ -165,9 +207,12 @@ const runMigrateCreateCommand = (options) => {
     );
     return { code: 1, file: "" };
   }
-  const table = options.table ?? "TODO_table";
+  const table = await resolveCreateTable(cwd, options);
+  if (table === void 0) {
+    return { code: 1, file: "" };
+  }
   if (!IDENTIFIER_PATTERN.test(table)) {
-    options.logger.error(`invalid --table: "${table}" — must be a valid identifier ([A-Za-z_][A-Za-z0-9_]*)`);
+    options.logger.error(`invalid table: "${table}" — must be a valid identifier ([A-Za-z_][A-Za-z0-9_]*)`);
     return { code: 1, file: "" };
   }
   const lunoraDirectory = join(cwd, "lunora");
@@ -195,9 +240,6 @@ ${content}`;
 ${block}
 `, "utf8");
   options.logger.success(`scaffolded migration "${slug}" in ${file}`);
-  if (options.table === void 0) {
-    options.logger.warn(`set the \`table\` field on "${slug}" — it defaults to "${table}"`);
-  }
   return { code: 0, file };
 };
 const resolveMigrationTable = (cwd, id) => {
@@ -305,44 +347,49 @@ const runMigrateToHyperdriveCommand = async (options) => {
   }
   const temporaryDirectory = options.out === void 0 ? mkdtempSync(join(tmpdir(), "lunora-d1ps-")) : void 0;
   const dumpPath = options.out ?? join(temporaryDirectory, "dump.ndjson");
-  logger.info(`Exporting .global() data from the D1 source (${fromUrl ?? "http://localhost:8787"}) …`);
-  const exportResult = await runExportCommand({
-    fetchImpl: options.fetchImpl,
-    logger,
-    out: dumpPath,
-    prod: options.prod,
-    tables: options.tables,
-    token: options.fromToken,
-    url: fromUrl
-  });
-  if (exportResult.code !== 0) {
-    return { code: exportResult.code };
-  }
-  logger.info(`Exported ${String(exportResult.rows)} row(s) (${String(exportResult.bytes)} bytes).`);
-  logger.info(`Importing into the Hyperdrive target (${toUrl ?? "http://localhost:8787"}) …`);
-  const importResult = await runImportCommand({
-    batchSize: options.batchSize,
-    fetchImpl: options.fetchImpl,
-    file: dumpPath,
-    logger,
-    prod: options.prod,
-    token: options.toToken,
-    url: toUrl
-  });
-  if (temporaryDirectory !== void 0) {
-    rmSync(temporaryDirectory, { force: true, recursive: true });
-  }
-  if (importResult.code !== 0) {
-    return { code: importResult.code };
-  }
-  if (importResult.inserted === exportResult.rows) {
-    logger.info(`✓ Migrated ${String(exportResult.rows)} row(s) — counts match. Verify your app reads from Hyperdrive, then decommission the D1 binding.`);
-  } else {
-    logger.warn(
-      `Imported ${String(importResult.inserted)} of ${String(exportResult.rows)} exported row(s) — the remainder likely already existed in the target (see conflicts above). Re-run after resolving, or inspect the dump with --out.`
-    );
+  try {
+    logger.info(`Exporting .global() data from the D1 source (${fromUrl ?? "http://localhost:8787"}) …`);
+    const exportResult = await runExportCommand({
+      fetchImpl: options.fetchImpl,
+      logger,
+      out: dumpPath,
+      prod: options.prod,
+      tables: options.tables,
+      token: options.fromToken,
+      url: fromUrl
+    });
+    if (exportResult.code !== 0) {
+      return { code: exportResult.code };
+    }
+    logger.info(`Exported ${String(exportResult.rows)} row(s) (${String(exportResult.bytes)} bytes).`);
+    logger.info(`Importing into the Hyperdrive target (${toUrl ?? "http://localhost:8787"}) …`);
+    const importResult = await runImportCommand({
+      batchSize: options.batchSize,
+      fetchImpl: options.fetchImpl,
+      file: dumpPath,
+      logger,
+      prod: options.prod,
+      token: options.toToken,
+      url: toUrl
+    });
+    if (importResult.code !== 0) {
+      return { code: importResult.code };
+    }
+    if (importResult.inserted === exportResult.rows) {
+      logger.info(
+        `✓ Migrated ${String(exportResult.rows)} row(s) — counts match. Verify your app reads from Hyperdrive, then decommission the D1 binding.`
+      );
+    } else {
+      logger.warn(
+        `Imported ${String(importResult.inserted)} of ${String(exportResult.rows)} exported row(s) — the remainder likely already existed in the target (see conflicts above). Re-run after resolving, or inspect the dump with --out.`
+      );
+    }
+    return { code: 0 };
+  } finally {
+    if (temporaryDirectory !== void 0) {
+      rmSync(temporaryDirectory, { force: true, recursive: true });
+    }
   }
-  return { code: 0 };
 };
 const execute = defineHandler(({ argument, cwd, logger, options }) => {
   const sub = argument[0];

package/dist/packem_chunks/runResetCommand.mjs

@@ -1,7 +1,7 @@
 import { existsSync, rmSync } from 'node:fs';
-import { promptYesNo } from '@lunora/config';
 import { join } from '@visulima/path';
-import { d as defineHandler } from '../packem_shared/command-BDXcJCCJ.mjs';
+import { d as defineHandler } from '../packem_shared/command-lYnl4QyF.mjs';
+import { b as tuiConfirm } from '../packem_shared/tui-prompts-BjEN8XgP.mjs';
 
 const runResetCommand = async (options) => {
   const cwd = options.cwd ?? process.cwd();
@@ -15,8 +15,8 @@ const runResetCommand = async (options) => {
       options.logger.error("reset: stdin is not a TTY — re-run with --yes to confirm deleting .wrangler/state");
       return { code: 1, removed: [] };
     }
-    const confirmer = options.confirm ?? promptYesNo;
-    const confirmed = await confirmer("This will delete .wrangler/state. Continue? [y/N] ");
+    const confirmer = options.confirm ?? tuiConfirm;
+    const confirmed = await confirmer("This will delete .wrangler/state. Continue?");
     if (!confirmed) {
       options.logger.info("reset: aborted");
       return { code: 1, removed: [] };

package/dist/packem_chunks/runRpcCommand.mjs

@@ -1,4 +1,5 @@
-import { d as defineHandler } from '../packem_shared/command-BDXcJCCJ.mjs';
+import { LunoraError } from '@lunora/errors';
+import { d as defineHandler } from '../packem_shared/command-lYnl4QyF.mjs';
 import { r as resolveWorkerUrl } from '../packem_shared/resolve-target-qbsJ_5sF.mjs';
 
 const parseArgsJson = (raw) => {
@@ -9,7 +10,7 @@ const parseArgsJson = (raw) => {
     return JSON.parse(raw);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`failed to parse --args as JSON: ${message}`, { cause: error });
+    throw new LunoraError("INTERNAL", `failed to parse --args as JSON: ${message}`, { cause: error });
   }
 };
 const TRAILING_SLASH = /\/$/u;

package/dist/packem_shared/{COMMANDS-1V_KEx35.mjs → COMMANDS-BOJIDoVY.mjs}

@@ -1,21 +1,29 @@
-import { readFileSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, lstatSync, writeFileSync } from 'node:fs';
+import { resolveHint, isLunoraError, flattenHint, findSolutionByMessage } from '@lunora/errors';
 import { createCerebro } from '@visulima/cerebro';
 import completionCommand from '@visulima/cerebro/command/completion';
 import versionCommand from '@visulima/cerebro/command/version';
-import { A as API_SPEC_HELP } from './api-spec-CtA6ilu4.mjs';
-import { createLogger } from './createLogger-CHPNjFw2.mjs';
-import { tmpdir } from 'node:os';
+import { A as API_SPEC_HELP } from './api-spec-Bx0iKbxA.mjs';
+import { createLogger } from './createLogger-CIWSHrTL.mjs';
+import { VisulimaError, renderError } from '@visulima/error';
+import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 const addCommand = {
-  argument: { description: "Feature or registry item: auth | email | storage | crons | presence | ratelimit | backup | …", name: "feature", type: String },
-  description: "Add a feature or registry item (auth, email, storage, crons, …) to the current Lunora project",
+  argument: {
+    description: "Feature or registry item: ai | auth | email | storage | crons | presence | queue | workflow | flags | backup | …",
+    name: "feature",
+    type: String
+  },
+  description: "Add a feature or registry item (ai, auth, email, storage, crons, …) to the current Lunora project",
   examples: [
     ["lunora add auth", "Add authentication (asks which provider)"],
     ["lunora add auth --provider clerk", "Add Clerk auth without prompting"],
     ["lunora add email", "Add transactional email (Cloudflare Email Workers + dev mail catcher)"],
-    ["lunora add storage", "Add the R2 storage registry item"],
-    ["lunora add crons", "Add the scheduled-jobs registry item"]
+    ["lunora add storage", "Add the R2 storage registry item (asks for the bucket name)"],
+    ["lunora add storage --bucket my-app-uploads", "Add storage with a bucket name, no prompt"],
+    ["lunora add crons", "Add the scheduled-jobs registry item"],
+    ["lunora add storage --ref alpha", "Add an item from the alpha branch's registry"]
   ],
   group: "Project",
   loader: () => import('../packem_chunks/handler.mjs').then((m) => {
@@ -24,10 +32,19 @@ const addCommand = {
   name: "add",
   options: [
     { description: "auth: provider to use without prompting (auth | clerk | auth0)", name: "provider", type: String },
-    { description: "Skip the provider prompt and use the default (email & password)", name: "yes", type: Boolean },
+    { description: "auth: D1 database name to use without prompting (lowercase alphanumeric + hyphens)", name: "db", type: String },
+    { description: "storage: R2 bucket name to use without prompting (lowercase alphanumeric + hyphens)", name: "bucket", type: String },
+    { description: "email: verified destination address to use without prompting", name: "mail-to", type: String },
+    { description: "Skip prompts (auth provider, DB name, bucket name, mail destination) and use the defaults", name: "yes", type: Boolean },
     { description: "Local registry root (offline; expects <name>/ subdirs)", name: "from", type: String },
     { description: "Override the remote registry source base (e.g. gh:owner/repo/registry)", name: "source", type: String },
-    { description: "Permit --source values outside gh:/github:/https://", name: "allow-unsafe-source", type: Boolean }
+    {
+      description: "Fetch items from a git ref (branch, tag, or commit), e.g. --ref alpha. Overrides the version-derived default",
+      name: "ref",
+      type: String
+    },
+    { description: "Permit --source values outside gh:/github:/https://", name: "allow-unsafe-source", type: Boolean },
+    { description: "Output format: pretty (default) or json", name: "format", type: String }
   ]
 };
 
@@ -202,9 +219,19 @@ const deploymentsCommand = {
 };
 
 const devCommand = {
+  argument: {
+    description: "Optional subcommand: stop (shut the running dev server down) | status (report it) | logs (print its captured output)",
+    name: "args",
+    type: String
+  },
   description: "Run the dev stack: wrangler worker + studio + codegen watch",
   examples: [
     ["lunora dev", "Run the worker + studio + codegen watch"],
+    ["lunora dev --background", "Run detached: blocks until ready, prints URL + PID, then returns"],
+    ["lunora dev stop", "Stop the background/tracked dev server (idempotent)"],
+    ["lunora dev status", "Report the running dev server (URL, PID, uptime)"],
+    ["lunora dev logs", "Print the captured dev-server log (background runs)"],
+    ["lunora dev --json", "Machine-readable JSON log lines (also LUNORA_LOG_JSON=1)"],
     ["lunora dev --no-studio", "Skip the embedded studio server"],
     ["lunora dev --worker-port 8080", "Use a custom wrangler dev port"],
     ["lunora dev --remote", "Proxy D1/KV/R2 to the deployed worker (also LUNORA_REMOTE=1)"]
@@ -214,10 +241,19 @@ const devCommand = {
     return { default: m.execute };
   }),
   name: "dev",
+  // KEEP IN SYNC with `daemonArguments` in `./lifecycle.ts`: a new flag that
+  // must reach a `--background` daemon has to be forwarded there explicitly.
   options: [
     { description: `Which API spec(s) codegen emits: ${API_SPEC_HELP} (default openapi)`, name: "api-spec", type: String },
     { description: "Studio server port (default 6173)", name: "port", type: Number },
     { description: "wrangler dev port (default 8787)", name: "worker-port", type: Number },
+    {
+      description: "Run the dev server as a managed background process (auto-enabled when an AI agent is detected; LUNORA_AGENT_MODE=0 disables)",
+      name: "background",
+      type: Boolean
+    },
+    { description: "Emit machine-readable JSON log lines (also LUNORA_LOG_JSON=1; auto-enabled for AI agents)", name: "json", type: Boolean },
+    { description: "How many trailing lines `lunora dev logs` prints (default 100, 0 = all)", name: "lines", type: Number },
     { description: "Don't start the embedded studio server", name: "no-studio", type: Boolean },
     { description: "Don't watch + regenerate codegen", name: "no-codegen", type: Boolean },
     { description: "Proxy D1/KV/R2 bindings to the deployed worker (or set LUNORA_REMOTE=1)", name: "remote", type: Boolean }
@@ -250,21 +286,24 @@ const doctorCommand = {
 };
 
 const envCommand = {
-  argument: { description: "list | get <KEY> | set <KEY> <VALUE> | unset <KEY> | push | diff | doctor", name: "subcommand", type: String },
-  description: "Manage .dev.vars and sync secrets via wrangler (list | get | set | unset | push | diff | doctor)",
+  argument: { description: "list | get <KEY> | set <KEY> <VALUE> | unset <KEY> | generate [KEY] | push | diff | doctor", name: "subcommand", type: String },
+  description: "Manage .dev.vars and sync secrets via wrangler (list | get | set | unset | generate | push | diff | doctor)",
   examples: [
     ["lunora env list", "List .dev.vars keys"],
     ["lunora env set API_KEY secret", "Set a local variable"],
+    ["lunora env generate", "Generate strong values for the project's secrets (print KEY=value)"],
+    ["lunora env generate AUTH_SECRET --set", "Generate one secret and write it to .dev.vars"],
     ["lunora env push --yes", "Upload secrets to Cloudflare"],
     ["lunora env diff", "Compare local .dev.vars keys against Cloudflare"]
   ],
   group: "Data",
-  loader: () => import('../packem_chunks/handler21.mjs').then((m) => {
+  loader: () => import('../packem_chunks/handler9.mjs').then((m) => {
     return { default: m.execute };
   }),
   name: "env",
   options: [
     { description: "Target production for `push` (passes --env production to wrangler)", name: "prod", type: Boolean },
+    { description: "For `generate` — write the generated secrets into .dev.vars instead of printing them", name: "set", type: Boolean },
     {
       description: "Push secrets to a temporary-account deployment when unauthenticated (wrangler secret put --temporary). Errors if you're already authenticated.",
       name: "temporary",
@@ -282,7 +321,7 @@ const exportCommand = {
     ["lunora export --tables messages,users", "Export only specific tables"]
   ],
   group: "Data",
-  loader: () => import('../packem_chunks/handler9.mjs').then((m) => {
+  loader: () => import('../packem_chunks/handler10.mjs').then((m) => {
     return { default: m.execute };
   }),
   name: "export",
@@ -304,7 +343,7 @@ const importCommand = {
   description: "Bulk-insert rows from an NDJSON file via the worker's admin endpoint",
   examples: [["lunora import backup.ndjson", "Bulk-insert rows from an NDJSON file"]],
   group: "Data",
-  loader: () => import('../packem_chunks/handler10.mjs').then((m) => {
+  loader: () => import('../packem_chunks/handler11.mjs').then((m) => {
     return { default: m.execute };
   }),
   name: "import",
@@ -312,6 +351,7 @@ const importCommand = {
     { description: "Wrap each bare doc as `{table:<name>,doc:...}`", name: "table", type: String },
     { description: "Rows per HTTP request (default 500)", name: "batch-size", type: Number },
     { description: "Target production — requires an explicit --url", name: "prod", type: Boolean },
+    { description: "Confirm bulk-writing production (required with --prod)", name: "yes", type: Boolean },
     { description: "Worker URL (default http://localhost:8787)", name: "url", type: String },
     {
       description: "Admin bearer token (prefer LUNORA_ADMIN_TOKEN; --token is visible to other local processes via the process table)",
@@ -328,7 +368,7 @@ const infoCommand = {
     ["lunora info --json", "Emit a JSON snapshot"]
   ],
   group: "Project",
-  loader: () => import('../packem_chunks/handler11.mjs').then((m) => {
+  loader: () => import('../packem_chunks/handler12.mjs').then((m) => {
     return { default: m.execute };
   }),
   name: "info",
@@ -340,8 +380,10 @@ const initCommand = {
   description: "Scaffold a new Lunora project",
   examples: [
     ["lunora init my-app", "Scaffold with the default (vite) template"],
+    ["lunora init my-app -t next", "Scaffold a Next.js app"],
     ["lunora init my-app -t tanstack-start-react", "Scaffold a TanStack Start (React) app"],
     ["lunora init my-app -t tanstack-start-solid", "Scaffold a TanStack Start (Solid) app"],
+    ["lunora init my-app --ref alpha", "Scaffold from the alpha branch's templates"],
     ["lunora init --here", "Add Lunora to the current project"],
     ["lunora init my-app --ci github", "Scaffold + add a GitHub Actions deploy pipeline"],
     ["lunora init my-app --ci gitlab", "Scaffold + add a GitLab CI deploy pipeline"]
@@ -354,11 +396,19 @@ const initCommand = {
   options: [
     {
       alias: "t",
-      defaultValue: "vite",
-      description: "Template to scaffold (vite | standalone | astro | nuxt | sveltekit | tanstack-start-react | tanstack-start-solid)",
+      // No default: when omitted, an interactive run shows the framework
+      // picker (default React overlay) and a non-interactive run errors.
+      // For React/Vue/Solid/Svelte SPAs use `--vite <framework>` (overlay);
+      // `-t` selects a bespoke template.
+      description: "Bespoke template (standalone | astro | next | nuxt | sveltekit | tanstack-start-react | tanstack-start-solid). For an SPA use --vite react|vue|solid|svelte.",
       name: "template",
       type: String
     },
+    {
+      description: "Scaffold via the create-vite overlay for a framework (react | vue | solid | svelte | vanilla) — official create-vite base + Lunora layer",
+      name: "vite",
+      type: String
+    },
     {
       description: "Local templates root to copy from (offline-friendly; expects <type>/ subdirs)",
       name: "from",
@@ -369,6 +419,11 @@ const initCommand = {
       name: "source",
       type: String
     },
+    {
+      description: "Fetch templates from a git ref (branch, tag, or commit), e.g. --ref alpha. Overrides the version-derived default",
+      name: "ref",
+      type: String
+    },
     {
       description: "Permit --source values outside gh:/github:/https:// (e.g. local file://)",
       name: "allow-unsafe-source",
@@ -395,6 +450,16 @@ const initCommand = {
       description: "Also scaffold a CI deploy pipeline: github (.github/workflows/deploy.yml) or gitlab (.gitlab-ci.yml)",
       name: "ci",
       type: String
+    },
+    {
+      description: "Add features non-interactively after scaffolding (comma-separated): ai | auth | backup | browser | cloudflare-access | crons | email | flags | hyperdrive | payment | presence | queue | storage | workflow",
+      name: "add",
+      type: String
+    },
+    {
+      description: "Walk through every step (prompts + output) without writing files, installing, or running git",
+      name: "dry-run",
+      type: Boolean
     }
   ]
 };
@@ -408,7 +473,7 @@ const insightsCommand = {
     ["lunora insights --prod --url https://app.example.com --token $LUNORA_ADMIN_TOKEN", "Report against production"]
   ],
   group: "Develop",
-  loader: () => import('../packem_chunks/handler12.mjs').then((m) => {
+  loader: () => import('../packem_chunks/handler13.mjs').then((m) => {
     return { default: m.execute };
   }),
   name: "insights",
@@ -430,7 +495,7 @@ const linkCommand = {
     ["lunora link --remove", "Remove the link"]
   ],
   group: "Deploy",
-  loader: () => import('../packem_chunks/handler13.mjs').then((m) => {
+  loader: () => import('../packem_chunks/handler14.mjs').then((m) => {
     return { default: m.execute };
   }),
   name: "link",
@@ -444,9 +509,9 @@ const linkCommand = {
 
 const logsCommand = {
   argument: { description: "Worker name (defaults to the name in wrangler config)", name: "worker", type: String },
-  description: "Stream live logs from a deployed Lunora Worker",
+  description: "Stream live logs from a deployed Worker, or read the durable log archive with --durable",
   group: "Deploy",
-  loader: () => import('../packem_chunks/handler14.mjs').then((m) => {
+  loader: () => import('../packem_chunks/handler21.mjs').then((m) => {
     return { default: m.execute };
   }),
   name: "logs",
@@ -459,7 +524,22 @@ const logsCommand = {
       description: "Tail a temporary-account deployment when unauthenticated (wrangler tail --temporary). Errors if you're already authenticated.",
       name: "temporary",
       type: Boolean
-    }
+    },
+    // --- durable-archive path (--durable) ---
+    { description: "Read the durable log archive (pipelineLogSink → R2) via R2 SQL instead of tailing live", name: "durable", type: Boolean },
+    { description: "durable: Iceberg table the Pipeline writes to (required with --durable)", name: "table", type: String },
+    { description: "durable: Iceberg namespace (R2 Data Catalog database) the table lives in", name: "namespace", type: String },
+    { description: "durable: lower time bound (epoch-millis or ISO 8601), inclusive", name: "since", type: String },
+    { description: "durable: upper time bound (epoch-millis or ISO 8601), inclusive", name: "until", type: String },
+    { description: "durable: exact severity filter (trace|debug|log|info|warn|error|fatal)", name: "level", type: String },
+    { description: "durable: severity floor — this level and every more-severe one", name: "min-level", type: String },
+    { description: "durable: keep function paths starting with this prefix (LIKE 'prefix%')", name: "function-prefix", type: String },
+    { description: "durable: trace-id filter", name: "trace-id", type: String },
+    { description: "durable: shard-key filter", name: "shard-key", type: String },
+    { description: "durable: user-id filter", name: "user-id", type: String },
+    { description: "durable: max rows (clamped to 1–10000; default 500)", name: "limit", type: String },
+    { description: "durable: resume after a prior page — the ts from its nextCursor", name: "cursor", type: String },
+    { description: "durable: emit one JSON object per line instead of a table", name: "ndjson", type: Boolean }
   ]
 };
 
@@ -480,7 +560,7 @@ const migrateCommand = {
   name: "migrate",
   options: [
     { description: "Migration name slug (e.g. add_users_email)", name: "name", type: String },
-    { description: "Target table for `create`", name: "table", type: String },
+    { description: "Target table for `create` (prompted for interactively when omitted)", name: "table", type: String },
     { description: "Preview a data migration without rewriting rows", name: "dry-run", type: Boolean },
     { description: "Rows per batch for a data migration", name: "batch-size", type: Number },
     { description: "Cap batches processed this run (maps to the runner's maxBatches)", name: "steps", type: Number },
@@ -541,6 +621,11 @@ const registryCommand = {
     { description: "add: skip the package.json mutation confirmation prompt", name: "yes", type: Boolean },
     { description: "Local registry root (offline; expects <name>/ subdirs)", name: "from", type: String },
     { description: "Override the remote registry source base (e.g. gh:owner/repo/registry)", name: "source", type: String },
+    {
+      description: "Fetch items from a git ref (branch, tag, or commit), e.g. --ref alpha. Overrides the version-derived default",
+      name: "ref",
+      type: String
+    },
     { description: "Permit --source values outside gh:/github:/https://", name: "allow-unsafe-source", type: Boolean },
     { description: "Emit JSON output (add plan / list)", name: "json", type: Boolean },
     { description: "build: output path for the catalog (default <root>/index.json)", name: "out", type: String },
@@ -639,7 +724,8 @@ const verifyCommand = {
   description: "Validate wrangler.jsonc + codegen dry-run + tsc --noEmit (no files written)",
   examples: [
     ["lunora verify", "Validate wrangler + codegen + tsc"],
-    ["lunora verify --no-typecheck", "Skip the TypeScript type-check"]
+    ["lunora verify --no-typecheck", "Skip the TypeScript type-check"],
+    ["lunora verify --health-url https://my-app.workers.dev", "Also probe the deployment's /_lunora/health"]
   ],
   group: "Deploy",
   loader: () => import('../packem_chunks/handler19.mjs').then((m) => {
@@ -650,6 +736,11 @@ const verifyCommand = {
     { description: "Treat breaking schema drift as a warning instead of a failure", name: "allow-schema-drift", type: Boolean },
     { description: `Which API spec(s) to emit: ${API_SPEC_HELP} (default openapi)`, name: "api-spec", type: String },
     { description: "Output format: pretty (default) or json", name: "format", type: String },
+    {
+      description: "Probe this deployment's /_lunora/health endpoint (off by default; keeps verify offline-safe)",
+      name: "health-url",
+      type: String
+    },
     { description: "Skip the TypeScript type-check step", name: "no-typecheck", type: Boolean }
   ]
 };
@@ -668,6 +759,21 @@ const viewCommand = {
   options: [{ description: "Open the deployed worker URL instead of localhost", name: "remote", type: Boolean }]
 };
 
+const NO_STACK = { filterStacktrace: () => false, hideErrorCodeView: true };
+const renderLunoraError = (error, options = {}) => {
+  const message = error instanceof Error ? error.message : String(error);
+  const hint = resolveHint(isLunoraError(error) ? { code: error.code, hint: error.hint, message } : message);
+  const rendered = new VisulimaError({
+    // `renderError` iterates `hint` as lines; the shared flattener returns one
+    // string, so split it back to lines for the terminal renderer.
+    hint: hint === void 0 ? void 0 : flattenHint(hint).split("\n"),
+    message: options.reason === void 0 ? message : `${options.reason}: ${message}`,
+    name: error instanceof Error && error.name.length > 0 ? error.name : "Error"
+  });
+  rendered.stack = "";
+  return renderError(rendered, NO_STACK);
+};
+
 const editDistance = (a, b) => {
   const distances = Array.from({ length: b.length + 1 }, (_, index) => index);
   for (let row = 1; row <= a.length; row += 1) {
@@ -730,6 +836,15 @@ const isNewer = (current, latest) => compareVersions(latest, current) > 0;
 const isCacheFresh = (checkedAt, nowMs, ttlMs) => nowMs - checkedAt < ttlMs;
 const formatUpdateNotice = (current, latest) => `Update available for @lunora/cli: ${current} → ${latest} — run \`pnpm add -D @lunora/cli@latest\``;
 const cacheFilePath = (cacheDirectory) => join(cacheDirectory, "lunora-cli-update.json");
+const defaultCacheDirectory = (env) => {
+  const base = env.XDG_CACHE_HOME && env.XDG_CACHE_HOME.length > 0 ? env.XDG_CACHE_HOME : join(homedir(), ".cache");
+  const directory = join(base, "lunora");
+  try {
+    mkdirSync(directory, { mode: 448, recursive: true });
+  } catch {
+  }
+  return directory;
+};
 const readCache = (cacheDirectory) => {
   try {
     const parsed = JSON.parse(readFileSync(cacheFilePath(cacheDirectory), "utf8"));
@@ -745,7 +860,14 @@ const readCache = (cacheDirectory) => {
 };
 const writeCache = (cacheDirectory, cache) => {
   try {
-    writeFileSync(cacheFilePath(cacheDirectory), `${JSON.stringify(cache)}
+    const path = cacheFilePath(cacheDirectory);
+    try {
+      if (lstatSync(path).isSymbolicLink()) {
+        return;
+      }
+    } catch {
+    }
+    writeFileSync(path, `${JSON.stringify(cache)}
 `, "utf8");
   } catch {
   }
@@ -770,7 +892,7 @@ const maybeNotifyUpdate = async (deps) => {
   if (isNotifierDisabled(deps.current, env, isTty)) {
     return;
   }
-  const cacheDirectory = deps.cacheDir ?? tmpdir();
+  const cacheDirectory = deps.cacheDir ?? defaultCacheDirectory(env);
   const nowMs = (deps.now ?? Date.now)();
   const ttlMs = deps.ttlMs ?? CACHE_TTL_MS;
   const cache = readCache(cacheDirectory);
@@ -882,7 +1004,11 @@ const reportRunError = (error) => {
   const message = error instanceof Error ? error.message : String(error);
   const unknown = UNKNOWN_COMMAND.exec(message);
   if (!unknown?.groups) {
-    logger.error(message);
+    if (isLunoraError(error) || findSolutionByMessage(message) !== void 0) {
+      logger.error(renderLunoraError(error));
+    } else {
+      logger.error(message);
+    }
     return;
   }
   const name = unknown.groups.name ?? "";