@lunora/cli 1.0.0-alpha.7 → 1.0.0-alpha.71

package/dist/packem_chunks/runMigrateGenerateCommand.mjs

@@ -1,14 +1,15 @@
 import { existsSync, mkdirSync, writeFileSync, mkdtempSync, rmSync, readFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { discoverSchema, discoverMigrations } from '@lunora/codegen';
+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 { 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-DdsljJT-.mjs';
-import { runExportCommand, runImportCommand } from '../packem_shared/DEFAULT_IMPORT_BATCH_SIZE-Ck-2bU08.mjs';
+import { runExportCommand, runImportCommand } from '../packem_shared/DEFAULT_IMPORT_BATCH_SIZE-CRQmmBZM.mjs';
 
 const SNAPSHOT_FILENAME = ".snapshot.json";
 const NON_ALPHANUMERIC = /[^\da-z]+/gu;
@@ -41,12 +42,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) => {

package/dist/packem_chunks/runResetCommand.mjs

@@ -1,7 +1,7 @@
 import { existsSync, rmSync } from 'node:fs';
 import { join } from '@visulima/path';
-import { d as defineHandler } from '../packem_shared/command-BDXcJCCJ.mjs';
-import { a as tuiConfirm } from '../packem_shared/tui-prompts-XHFxlOg5.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();

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-Bn8luojF.mjs → COMMANDS-0BD3K1pb.mjs}

@@ -1,9 +1,11 @@
 import { readFileSync, 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 { A as API_SPEC_HELP } from './api-spec-Bx0iKbxA.mjs';
+import { createLogger } from './createLogger-CIWSHrTL.mjs';
+import { VisulimaError, renderError } from '@visulima/error';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
@@ -14,7 +16,8 @@ const addCommand = {
     ["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 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"]
   ],
@@ -25,7 +28,10 @@ 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 },
     {
@@ -33,7 +39,8 @@ const addCommand = {
       name: "ref",
       type: String
     },
-    { description: "Permit --source values outside gh:/github:/https://", name: "allow-unsafe-source", type: Boolean }
+    { 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 }
   ]
 };
 
@@ -208,9 +215,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)"]
@@ -220,10 +237,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 }
@@ -256,21 +282,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",
@@ -288,7 +317,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",
@@ -310,7 +339,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",
@@ -334,7 +363,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",
@@ -415,6 +444,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): auth | email | storage | ratelimit | crons | presence | backup",
+      name: "add",
+      type: String
+    },
+    {
+      description: "Walk through every step (prompts + output) without writing files, installing, or running git",
+      name: "dry-run",
+      type: Boolean
     }
   ]
 };
@@ -428,7 +467,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",
@@ -450,7 +489,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",
@@ -466,7 +505,7 @@ 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",
   group: "Deploy",
-  loader: () => import('../packem_chunks/handler14.mjs').then((m) => {
+  loader: () => import('../packem_chunks/handler15.mjs').then((m) => {
     return { default: m.execute };
   }),
   name: "logs",
@@ -526,7 +565,7 @@ const prepareCommand = {
   description: "Run codegen + binding reconcile + wrangler validation (no Vite) — for CI",
   examples: [["lunora prepare", "Codegen + binding reconcile + validate (CI, before deploy)"]],
   group: "Deploy",
-  loader: () => import('../packem_chunks/handler15.mjs').then((m) => {
+  loader: () => import('../packem_chunks/handler16.mjs').then((m) => {
     return { default: m.execute };
   }),
   name: "prepare",
@@ -550,7 +589,7 @@ const registryCommand = {
     ["lunora registry build --check", "Verify the committed catalog is current"]
   ],
   group: "Project",
-  loader: () => import('../packem_chunks/handler16.mjs').then((m) => {
+  loader: () => import('../packem_chunks/handler17.mjs').then((m) => {
     return { default: m.execute };
   }),
   name: "registry",
@@ -600,7 +639,7 @@ const rulesCommand = {
     ["lunora rules check --strict", "Exit non-zero when rules are missing (CI gate)"]
   ],
   group: "Project",
-  loader: () => import('../packem_chunks/handler17.mjs').then((m) => {
+  loader: () => import('../packem_chunks/handler18.mjs').then((m) => {
     return { default: m.execute };
   }),
   name: "rules",
@@ -638,7 +677,7 @@ const seedCommand = {
     ["lunora seed --seed 7 --dry-run", "Print the NDJSON for seed 7 without inserting"]
   ],
   group: "Data",
-  loader: () => import('../packem_chunks/handler18.mjs').then((m) => {
+  loader: () => import('../packem_chunks/handler19.mjs').then((m) => {
     return { default: m.execute };
   }),
   name: "seed",
@@ -667,7 +706,7 @@ const verifyCommand = {
     ["lunora verify --no-typecheck", "Skip the TypeScript type-check"]
   ],
   group: "Deploy",
-  loader: () => import('../packem_chunks/handler19.mjs').then((m) => {
+  loader: () => import('../packem_chunks/handler20.mjs').then((m) => {
     return { default: m.execute };
   }),
   name: "verify",
@@ -686,13 +725,28 @@ const viewCommand = {
     ["lunora view --remote", "Open the deployed studio"]
   ],
   group: "Project",
-  loader: () => import('../packem_chunks/handler20.mjs').then((m) => {
+  loader: () => import('../packem_chunks/handler21.mjs').then((m) => {
     return { default: m.execute };
   }),
   name: "view",
   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) {
@@ -907,7 +961,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 ?? "";

package/dist/packem_shared/{DEFAULT_IMPORT_BATCH_SIZE-Ck-2bU08.mjs → DEFAULT_IMPORT_BATCH_SIZE-CRQmmBZM.mjs}

@@ -1,5 +1,6 @@
 import { createWriteStream, createReadStream } from 'node:fs';
 import { unlink, stat } from 'node:fs/promises';
+import { LunoraError } from '@lunora/errors';
 import { r as resolveAdminBaseUrl } from './admin-url-4UzT-CI4.mjs';
 
 const EXPORT_ENDPOINT_PATH = "/_lunora/admin/export";
@@ -183,7 +184,7 @@ const runImportCommand = async (options) => {
     });
     if (!response.ok) {
       const text = await response.text().catch(() => "<no body>");
-      throw new Error(`import batch failed (HTTP ${String(response.status)}): ${text}`);
+      throw new LunoraError("INTERNAL", `import batch failed (HTTP ${String(response.status)}): ${text}`);
     }
     const json = await response.json();
     if (json.inserted) {
@@ -213,7 +214,7 @@ const runImportCommand = async (options) => {
       parsedDocument = JSON.parse(trimmed);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      throw new Error(`invalid JSON on line ${String(lineNumber)}: ${message}`, { cause: error });
+      throw new LunoraError("INTERNAL", `invalid JSON on line ${String(lineNumber)}: ${message}`, { cause: error });
     }
     batch.push(JSON.stringify({ doc: parsedDocument, table: options.table }));
   };

package/dist/packem_shared/{api-spec-CtA6ilu4.mjs → api-spec-Bx0iKbxA.mjs}

@@ -1,3 +1,5 @@
+import { LunoraError } from '@lunora/errors';
+
 const API_SPEC_VALUES = ["both", "none", "openapi", "openrpc"];
 const API_SPEC_HELP = API_SPEC_VALUES.join(" | ");
 const parseApiSpec = (value) => {
@@ -7,7 +9,7 @@ const parseApiSpec = (value) => {
   if (API_SPEC_VALUES.includes(value)) {
     return value;
   }
-  throw new Error(`invalid --api-spec "${value}" — expected one of: ${API_SPEC_HELP}`);
+  throw new LunoraError("INTERNAL", `invalid --api-spec "${value}" — expected one of: ${API_SPEC_HELP}`);
 };
 
 export { API_SPEC_HELP as A, parseApiSpec as p };

package/dist/packem_shared/{buildRegistryIndex-BcYe607_.mjs → buildRegistryIndex-CqM5FwGI.mjs}

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from '@visulima/path';
-import parseManifest from './parseManifest--vZf2FY1.mjs';
+import parseManifest from './parseManifest-BBrXCg9V.mjs';
 
 const CONTROL_CHARS = /[\u0000-\u001F\u007F-\u009F]/gu;
 const stripControlChars = (value) => value === void 0 ? void 0 : value.replaceAll(CONTROL_CHARS, "");

package/dist/packem_shared/codegen-error-DJG-ghs_.mjs

@@ -0,0 +1,31 @@
+import { findLunoraSolution } from '@lunora/codegen';
+import { VisulimaError, renderError } from '@visulima/error';
+
+const flattenSolutionBody = (solution) => solution.body.split("\n").filter((line) => !line.startsWith("```")).join("\n").replaceAll(/\*\*(.+?)\*\*/gu, "$1").replaceAll(/`([^`]+)`/gu, "$1");
+const NO_STACK = { filterStacktrace: () => false, hideErrorCodeView: true };
+const renderCodegenFailure = (error, reason) => {
+  const message = error instanceof Error ? error.message : String(error);
+  const solution = findLunoraSolution(message);
+  const rendered = new VisulimaError({
+    hint: solution ? [solution.header, "", flattenSolutionBody(solution)] : void 0,
+    message: reason === void 0 ? `codegen failed: ${message}` : `codegen failed (${reason}): ${message}`,
+    name: "CodegenError"
+  });
+  rendered.stack = "";
+  return renderError(rendered, NO_STACK);
+};
+const renderCodegenHint = (message) => {
+  const solution = findLunoraSolution(message);
+  if (solution === void 0) {
+    return void 0;
+  }
+  const rendered = new VisulimaError({
+    hint: [flattenSolutionBody(solution)],
+    message: solution.header,
+    name: "Hint"
+  });
+  rendered.stack = "";
+  return renderError(rendered, NO_STACK);
+};
+
+export { renderCodegenHint as a, renderCodegenFailure as r };

package/dist/packem_shared/{command-BDXcJCCJ.mjs → command-lYnl4QyF.mjs}

@@ -1,4 +1,5 @@
-import { createLogger } from './createLogger-CHPNjFw2.mjs';
+import { createLogger } from './createLogger-CIWSHrTL.mjs';
+import { P as PromptCancelledError, a as PROMPT_CANCEL_EXIT_CODE } from './prompt-cancelled-APzX1Im-.mjs';
 
 const defineHandler = (body) => async (toolbox) => {
   const logger = createLogger();
@@ -6,6 +7,10 @@ const defineHandler = (body) => async (toolbox) => {
     const { code } = await body({ argument: toolbox.argument, cwd: toolbox.process.cwd, logger, options: toolbox.options });
     toolbox.process.exit(code);
   } catch (error) {
+    if (error instanceof PromptCancelledError) {
+      toolbox.process.exit(PROMPT_CANCEL_EXIT_CODE);
+      return;
+    }
     logger.error(error instanceof Error ? error.message : String(error));
     toolbox.process.exit(1);
   }

package/dist/packem_shared/{commands-DqsEzojt.mjs → commands-vnRRkhNE.mjs}

@@ -3,13 +3,14 @@ import { dirname, join } from '@visulima/path';
 import { DEV_VARS_FILE, parseDevVariableEntries } from '@lunora/config';
 import { modify, applyEdits, parse } from 'jsonc-parser';
 import { fileURLToPath } from 'node:url';
-import { a as tuiConfirm } from './tui-prompts-XHFxlOg5.mjs';
-import { collectCatalog, buildRegistryIndex } from './buildRegistryIndex-BcYe607_.mjs';
-import { insertSchemaExtension } from './insertSchemaExtension-BuzF6-t2.mjs';
+import { LunoraError } from '@lunora/errors';
+import { b as tuiConfirm } from './tui-prompts-BjEN8XgP.mjs';
+import { collectCatalog, buildRegistryIndex } from './buildRegistryIndex-CqM5FwGI.mjs';
+import { insertSchemaExtension } from './insertSchemaExtension-DAqbfr9Z.mjs';
 import { createHash } from 'node:crypto';
 import { tmpdir } from 'node:os';
 import { downloadTemplate } from 'giget';
-import parseManifest from './parseManifest--vZf2FY1.mjs';
+import parseManifest from './parseManifest-BBrXCg9V.mjs';
 
 const DEFAULT_SOURCE_REF_FALLBACK = "alpha";
 const STABLE_BRANCH = "main";
@@ -54,17 +55,88 @@ const resolveVersionRef = (version) => {
 const resolveSourceRef = (ref) => {
   if (ref !== void 0 && ref.length > 0) {
     if (!isSafeRef(ref)) {
-      throw new Error(`invalid --ref "${ref}" — a ref may contain letters, digits, ".", "_", "-", "/", "@" and must not contain "..".`);
+      throw new LunoraError("INTERNAL", `invalid --ref "${ref}" — a ref may contain letters, digits, ".", "_", "-", "/", "@" and must not contain "..".`);
     }
     return ref;
   }
   return resolveVersionRef(resolveCliVersion());
 };
+const SOURCE_REPO = "anolilab/lunora";
+const COMMIT_SHA = /^[0-9a-f]{40}$/iu;
+const SEMVER_BODY = String.raw`\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)+)?(?:\+[0-9A-Za-z.-]+)?`;
+const LEADING_VERSION_TAG = new RegExp(String.raw`^v?${SEMVER_BODY}$`, "u");
+const PACKAGE_VERSION_TAG = new RegExp(String.raw`^(?:@[\w.-]+\/)?[\w.-]+@${SEMVER_BODY}$`, "u");
+const isImmutableRef = (ref) => COMMIT_SHA.test(ref) || LEADING_VERSION_TAG.test(ref) || PACKAGE_VERSION_TAG.test(ref);
+const githubAuthHeaders = () => {
+  const token = process.env["GITHUB_TOKEN"] ?? process.env["GH_TOKEN"];
+  return token !== void 0 && token.length > 0 ? { authorization: `Bearer ${token}` } : {};
+};
+const fetchBranchSha = async (branch) => {
+  try {
+    const response = await fetch(`https://api.github.com/repos/${SOURCE_REPO}/commits/${encodeURIComponent(branch)}`, {
+      headers: { accept: "application/vnd.github+json", "user-agent": "lunora-cli", ...githubAuthHeaders() },
+      signal: AbortSignal.timeout(1e4)
+    });
+    if (!response.ok) {
+      return void 0;
+    }
+    const body = await response.json();
+    return typeof body.sha === "string" && COMMIT_SHA.test(body.sha) ? body.sha : void 0;
+  } catch {
+    return void 0;
+  }
+};
+const resolvePinnedSourceRef = async (ref, logger) => {
+  const resolved = resolveSourceRef(ref);
+  if (isImmutableRef(resolved)) {
+    return resolved;
+  }
+  const sha = await fetchBranchSha(resolved);
+  if (sha === void 0) {
+    logger.warn(`could not pin ${SOURCE_REPO}#${resolved} to a commit — fetching the UNPINNED branch (set GITHUB_TOKEN if rate-limited).`);
+    return resolved;
+  }
+  logger.info(`pinned ${SOURCE_REPO}#${resolved} → ${sha}`);
+  return sha;
+};
 const STABLE_DIST_TAG = "latest";
 const resolveDistTag = () => {
   const ref = resolveVersionRef(resolveCliVersion());
   return ref === STABLE_BRANCH ? STABLE_DIST_TAG : ref;
 };
+const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+const registryBase = () => {
+  const configured = process.env["npm_config_registry"];
+  const base = configured !== void 0 && configured.length > 0 ? configured : DEFAULT_REGISTRY;
+  return base.endsWith("/") ? base.slice(0, -1) : base;
+};
+const resolveTagVersion = async (packageName, tag) => {
+  try {
+    const response = await fetch(`${registryBase()}/${packageName.replace("/", "%2F")}`, {
+      headers: { accept: "application/vnd.npm.install-v1+json" },
+      signal: AbortSignal.timeout(1e4)
+    });
+    if (!response.ok) {
+      return void 0;
+    }
+    const packument = await response.json();
+    return packument["dist-tags"]?.[tag];
+  } catch {
+    return void 0;
+  }
+};
+const resolveTagVersions = async (names, tag) => {
+  const resolved = /* @__PURE__ */ new Map();
+  await Promise.all(
+    [...new Set(names)].map(async (name) => {
+      const version = await resolveTagVersion(name, tag);
+      if (version !== void 0) {
+        resolved.set(name, version);
+      }
+    })
+  );
+  return resolved;
+};
 
 const resolveDepRange = (range) => {
   if (!range.startsWith("workspace:")) {
@@ -386,11 +458,12 @@ export const schema = defineSchema({});
     return { kind: "skipped", path: schemaPath };
   }
   if (result.reason === "invalid-identifier") {
-    throw new Error(
+    throw new LunoraError(
+      "INTERNAL",
       `schema-extension item "${itemKey}" is not a valid JS identifier — it is spliced into lunora/schema.ts as \`import { ${itemKey} }\` / \`.extend(${itemKey}.extension)\`. Rename the item to a valid identifier (no leading digit, no "-").`
     );
   }
-  throw new Error(`schema-extension merge failed for "${itemKey}": ${result.reason}`);
+  throw new LunoraError("INTERNAL", `schema-extension merge failed for "${itemKey}": ${result.reason}`);
 };
 const previewWholeFile = (file, current, incoming, exists, logger) => {
   const lines = renderDiff(current, incoming);
@@ -478,7 +551,8 @@ const DEFAULT_SOURCE_BASE = "gh:anolilab/lunora/registry";
 const VALID_ITEM_NAME = /^[A-Za-z0-9][\w-]*$/u;
 const assertSafeItemName = (name) => {
   if (!VALID_ITEM_NAME.test(name)) {
-    throw new Error(
+    throw new LunoraError(
+      "INTERNAL",
       `invalid registry item name "${name}" — names must match ${VALID_ITEM_NAME.source} (letters, digits, "-", "_"; no path separators or "..")`
     );
   }
@@ -515,29 +589,39 @@ const fetchToStaging = async (remote, label, logger) => {
     throw error;
   }
 };
+const remoteRefCache = /* @__PURE__ */ new WeakMap();
+const resolveRemoteRef = async (options) => {
+  const cached = remoteRefCache.get(options);
+  if (cached !== void 0) {
+    return cached;
+  }
+  const pending = options.source !== void 0 && options.source.length > 0 ? Promise.resolve(resolveSourceRef(options.ref)) : resolvePinnedSourceRef(options.ref, options.logger);
+  remoteRefCache.set(options, pending);
+  return pending;
+};
 const resolveItemDirectory = async (name, options) => {
   assertSafeItemName(name);
   if (options.from !== void 0) {
     const directory = join(options.from, name);
     if (!existsSync(directory)) {
-      throw new Error(`registry item not found in local source: ${directory}`);
+      throw new LunoraError("INTERNAL", `registry item not found in local source: ${directory}`);
     }
     return { cleanup: () => {
     }, directory };
   }
   const base = options.source ?? DEFAULT_SOURCE_BASE;
-  return fetchToStaging(`${base}/${name}#${resolveSourceRef(options.ref)}`, "item", options.logger);
+  return fetchToStaging(`${base}/${name}#${await resolveRemoteRef(options)}`, "item", options.logger);
 };
 const resolveRegistryRoot = async (options) => {
   if (options.from !== void 0) {
     if (!existsSync(options.from)) {
-      throw new Error(`registry root not found: ${options.from}`);
+      throw new LunoraError("INTERNAL", `registry root not found: ${options.from}`);
     }
     return { cleanup: () => {
     }, root: options.from };
   }
   const base = options.source ?? DEFAULT_SOURCE_BASE;
-  const { cleanup, directory } = await fetchToStaging(`${base}#${resolveSourceRef(options.ref)}`, "registry", options.logger);
+  const { cleanup, directory } = await fetchToStaging(`${base}#${await resolveRemoteRef(options)}`, "registry", options.logger);
   return { cleanup, root: directory };
 };
 const readManifest = (itemDirectory, name) => {
@@ -554,7 +638,7 @@ const resolvePlan = async (names, options) => {
       return;
     }
     if (inProgress.has(name)) {
-      throw new Error(`cyclic registry dependency detected at "${name}"`);
+      throw new LunoraError("INTERNAL", `cyclic registry dependency detected at "${name}"`);
     }
     inProgress.add(name);
     const { cleanup, directory } = await resolveItemDirectory(name, options);
@@ -583,6 +667,26 @@ const resolvePlan = async (names, options) => {
 const emptyResult = () => {
   return { bindings: [], code: 0, deps: [], skipped: [], written: [] };
 };
+const setBindingField = (manifest, section, match, field, fieldValue) => {
+  if (!manifest.bindings) {
+    return manifest;
+  }
+  return {
+    ...manifest,
+    bindings: manifest.bindings.map((binding) => {
+      if (binding.path[0] !== section || !Array.isArray(binding.value)) {
+        return binding;
+      }
+      const entries = binding.value;
+      return {
+        ...binding,
+        value: entries.map(
+          (entry) => typeof entry === "object" && entry !== null && entry[match.key] === match.value ? { ...entry, [field]: fieldValue } : entry
+        )
+      };
+    })
+  };
+};
 
 const printPlan = (logger, manifest) => {
   const label = manifest.title ?? manifest.description;
@@ -688,8 +792,12 @@ const runAddCommand = async (options) => {
   }
   let cleanups = [];
   try {
-    const { cleanups: planCleanups, items } = await resolvePlan(options.names, options);
+    const { cleanups: planCleanups, items: resolvedItems } = await resolvePlan(options.names, options);
     cleanups = planCleanups;
+    const { transformManifest } = options;
+    const items = transformManifest ? resolvedItems.map((item) => {
+      return { ...item, manifest: transformManifest(item.manifest) };
+    }) : resolvedItems;
     for (const { manifest } of items) {
       printPlan(options.logger, manifest);
     }
@@ -785,4 +893,4 @@ const runBuildIndexCommand = async (options) => {
   return empty;
 };
 
-export { runBuildIndexCommand as a, runRegistryViewCommand as b, resolveDistTag as c, resolveSourceRef as d, runListCommand as e, runAddCommand as r };
+export { runBuildIndexCommand as a, runRegistryViewCommand as b, resolveTagVersions as c, resolveSourceRef as d, resolvePinnedSourceRef as e, resolveDistTag as f, runListCommand as g, runAddCommand as r, setBindingField as s };