@lunora/cli 1.0.0-alpha.57 → 1.0.0-alpha.59

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-D3lB_4Az.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,6 +1,6 @@
 import { existsSync, rmSync } from 'node:fs';
 import { join } from '@visulima/path';
-import { d as defineHandler } from '../packem_shared/command-D3lB_4Az.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) => {

package/dist/packem_chunks/runRpcCommand.mjs

@@ -1,4 +1,5 @@
-import { d as defineHandler } from '../packem_shared/command-D3lB_4Az.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-B0ftFD_3.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-B40gPzQo.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';
 
@@ -213,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)"]
@@ -225,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 }
@@ -711,6 +732,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) {
@@ -925,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/{command-D3lB_4Az.mjs → command-lYnl4QyF.mjs}

@@ -1,4 +1,4 @@
-import { createLogger } from './createLogger-B40gPzQo.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) => {

package/dist/packem_shared/{commands-BK6Pt3Ni.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 { LunoraError } from '@lunora/errors';
 import { b as tuiConfirm } from './tui-prompts-BjEN8XgP.mjs';
-import { collectCatalog, buildRegistryIndex } from './buildRegistryIndex-BcYe607_.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,7 +55,7 @@ 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;
   }
@@ -457,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);
@@ -549,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 "..")`
     );
   }
@@ -601,7 +604,7 @@ const resolveItemDirectory = async (name, options) => {
   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 };
@@ -612,7 +615,7 @@ const resolveItemDirectory = async (name, options) => {
 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 };
@@ -635,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);

package/dist/packem_shared/{createLogger-B40gPzQo.mjs → createLogger-CIWSHrTL.mjs}

@@ -2,19 +2,46 @@ import { STEP_BADGE_NAMES, LunoraReporter } from '@lunora/config';
 import { JsonReporter } from '@visulima/pail/reporter/json';
 import { createPail } from '@visulima/pail/server';
 
+let sharedPail;
+let jsonForced = false;
+let configuredReporters;
 const wantJson = () => {
+  if (jsonForced) {
+    return true;
+  }
   const flag = process.env.LUNORA_LOG_JSON;
   return flag === "1" || flag === "true";
 };
-const buildReporter = () => {
-  const Reporter = wantJson() ? JsonReporter : LunoraReporter;
-  return new Reporter();
+const constructReporter = (Reporter) => new Reporter();
+const buildReporters = () => {
+  if (jsonForced) {
+    return [constructReporter(JsonReporter)];
+  }
+  if (configuredReporters !== void 0 && configuredReporters.length > 0) {
+    return configuredReporters;
+  }
+  return [constructReporter(wantJson() ? JsonReporter : LunoraReporter)];
+};
+const forceJsonLogging = () => {
+  if (jsonForced) {
+    return;
+  }
+  jsonForced = true;
+  sharedPail = void 0;
+};
+const logHandlers = {
+  compose: (...reporters) => reporters,
+  console: () => constructReporter(LunoraReporter),
+  json: () => constructReporter(JsonReporter)
+};
+const configureLogHandlers = (reporters) => {
+  configuredReporters = Array.isArray(reporters) ? reporters : [reporters];
+  sharedPail = void 0;
 };
 const STEP_LOG_TYPES = Object.fromEntries(STEP_BADGE_NAMES.map((name) => [name, { label: name, logLevel: "informational" }]));
-let sharedPail;
 const getPail = () => {
   sharedPail ??= createPail({
-    reporters: [buildReporter()],
+    reporters: buildReporters(),
     scope: ["lunora"],
     stderr: process.stderr,
     stdout: process.stdout,
@@ -75,4 +102,4 @@ const logStep = (type, message) => {
   getPail()[type](message);
 };
 
-export { createLogger, createStderrLogger, getPail, logStep, pail };
+export { configureLogHandlers, createLogger, createStderrLogger, forceJsonLogging, getPail, logHandlers, logStep, pail };

package/dist/packem_shared/{createRecordingSpawner-DxI3mebw.mjs → createRecordingSpawner-Cw5Iu73G.mjs}

@@ -1,5 +1,13 @@
 import { spawn } from 'node:child_process';
 
+const NEEDS_CMD_QUOTING = /\s/;
+const spawnShellCompat = (command, args, platform = process.platform) => {
+  if (platform !== "win32" || command === process.execPath) {
+    return { args: [...args], command, shell: false };
+  }
+  const quote = (value) => NEEDS_CMD_QUOTING.test(value) ? `"${value}"` : value;
+  return { args: args.map((argument) => quote(argument)), command: quote(command), shell: true };
+};
 const defaultSpawner = (descriptor) => new Promise((resolve, reject) => {
   const hasInput = typeof descriptor.input === "string";
   const wantCapture = descriptor.captureStdout === true;
@@ -9,9 +17,11 @@ const defaultSpawner = (descriptor) => new Promise((resolve, reject) => {
   } else if (descriptor.stdoutToStderr) {
     stdout = 2;
   }
-  const child = spawn(descriptor.command, [...descriptor.args], {
+  const exec = spawnShellCompat(descriptor.command, descriptor.args);
+  const child = spawn(exec.command, exec.args, {
     cwd: descriptor.cwd ?? process.cwd(),
     env: descriptor.env ? { ...process.env, ...descriptor.env } : process.env,
+    shell: exec.shell,
     stdio: [hasInput ? "pipe" : "inherit", stdout, "inherit"]
   });
   let captured = "";
@@ -40,4 +50,4 @@ const createRecordingSpawner = (exitCode = 0) => {
   return { calls, spawner };
 };
 
-export { createRecordingSpawner, defaultSpawner };
+export { createRecordingSpawner, defaultSpawner, spawnShellCompat };

package/dist/packem_shared/{open-url-Dfq6fAyT.mjs → open-url-4PBLY9X0.mjs}

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
 import { platform } from 'node:os';
+import { LunoraError } from '@lunora/errors';
 
 const platformCommand = () => {
   const os = platform();
@@ -29,10 +30,10 @@ const openUrl = async (url, options = {}) => {
   try {
     parsed = new URL(url);
   } catch {
-    throw new Error(`Invalid URL: ${url}`);
+    throw new LunoraError("INTERNAL", `Invalid URL: ${url}`);
   }
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    throw new Error(`Refusing to open non-http(s) URL: ${url}`);
+    throw new LunoraError("INTERNAL", `Refusing to open non-http(s) URL: ${url}`);
   }
   const opener = options.opener ?? platformOpener;
   await opener(url);

package/dist/packem_shared/{output-format-wUvAN6AL.mjs → output-format-B4642rjE.mjs}

@@ -1,4 +1,4 @@
-import { createStderrLogger } from './createLogger-B40gPzQo.mjs';
+import { createStderrLogger } from './createLogger-CIWSHrTL.mjs';
 
 const OUTPUT_FORMATS = /* @__PURE__ */ new Set(["json", "pretty"]);
 const validateOutputFormat = (command, format) => {

package/dist/packem_shared/{parseManifest--vZf2FY1.mjs → parseManifest-BBrXCg9V.mjs}

@@ -1,17 +1,20 @@
+import { LunoraError } from '@lunora/errors';
+
 const NEWLINE_PRESENT = /[\r\n]/u;
 const VALID_ENV_NAME = /^[A-Za-z_]\w*$/u;
 const VALID_ITEM_NAME = /^[A-Za-z0-9][\w-]*$/u;
 const parseManifest = (raw, itemName) => {
   if (typeof raw !== "object" || raw === null) {
-    throw new Error(`registry.json for "${itemName}" is not an object`);
+    throw new LunoraError("INTERNAL", `registry.json for "${itemName}" is not an object`);
   }
   const record = raw;
   const { name } = record;
   if (typeof name !== "string" || name.length === 0) {
-    throw new Error(`registry.json for "${itemName}" is missing a string "name"`);
+    throw new LunoraError("INTERNAL", `registry.json for "${itemName}" is missing a string "name"`);
   }
   if (!VALID_ITEM_NAME.test(name)) {
-    throw new Error(
+    throw new LunoraError(
+      "INTERNAL",
       `registry.json for "${itemName}": name "${name}" must match ${VALID_ITEM_NAME.source} (letters, digits, "-", "_"; no path separators, "..", or code)`
     );
   }
@@ -21,7 +24,7 @@ const parseManifest = (raw, itemName) => {
   }
   const files = filesRaw.map((entry, index) => {
     if (typeof entry !== "object" || entry === null) {
-      throw new Error(`registry.json "${itemName}": files[${String(index)}] is not an object`);
+      throw new LunoraError("INTERNAL", `registry.json "${itemName}": files[${String(index)}] is not an object`);
     }
     const fileRecord = entry;
     const { from } = fileRecord;
@@ -31,14 +34,17 @@ const parseManifest = (raw, itemName) => {
       throw new TypeError(`registry.json "${itemName}": files[${String(index)}] needs string "from" and "to"`);
     }
     if (merge !== "create-or-skip" && merge !== "schema-extension") {
-      throw new Error(`registry.json "${itemName}": files[${String(index)}].merge must be "create-or-skip" or "schema-extension"`);
+      throw new LunoraError("INTERNAL", `registry.json "${itemName}": files[${String(index)}].merge must be "create-or-skip" or "schema-extension"`);
     }
     for (const [field, value] of [
       ["from", from],
       ["to", to]
     ]) {
       if (value.includes("..") || value.startsWith("/")) {
-        throw new Error(`registry.json "${itemName}": files[${String(index)}].${field} "${value}" must be a relative path without ".."`);
+        throw new LunoraError(
+          "INTERNAL",
+          `registry.json "${itemName}": files[${String(index)}].${field} "${value}" must be a relative path without ".."`
+        );
       }
     }
     return { from, merge, to };
@@ -59,15 +65,16 @@ const parseManifest = (raw, itemName) => {
   ).map((entry) => {
     const hasValue = typeof entry.value === "string";
     if (!VALID_ENV_NAME.test(entry.name)) {
-      throw new Error(
+      throw new LunoraError(
+        "INTERNAL",
         `registry.json "${itemName}": envVars["${entry.name}"].name must match ${VALID_ENV_NAME.source} (letters, digits, underscore; no "=" or newline)`
       );
     }
     if (hasValue && NEWLINE_PRESENT.test(entry.value)) {
-      throw new Error(`registry.json "${itemName}": envVars["${entry.name}"].value must not contain a newline`);
+      throw new LunoraError("INTERNAL", `registry.json "${itemName}": envVars["${entry.name}"].value must not contain a newline`);
     }
     if (typeof entry.description === "string" && NEWLINE_PRESENT.test(entry.description)) {
-      throw new Error(`registry.json "${itemName}": envVars["${entry.name}"].description must not contain a newline`);
+      throw new LunoraError("INTERNAL", `registry.json "${itemName}": envVars["${entry.name}"].description must not contain a newline`);
     }
     return {
       ...typeof entry.description === "string" ? { description: entry.description } : {},

package/dist/packem_shared/runAddCommand-BCcJzs_k.mjs

@@ -0,0 +1,4 @@
+import 'node:fs';
+import '@visulima/path';
+export { r as runAddCommand, a as runBuildIndexCommand, g as runListCommand, b as runRegistryViewCommand } from './commands-vnRRkhNE.mjs';
+import './buildRegistryIndex-CqM5FwGI.mjs';

package/dist/packem_shared/{storage-C8SAm5zu.mjs → storage-bGfgwOgF.mjs}

@@ -1,4 +1,4 @@
-import { s as setBindingField } from './commands-BK6Pt3Ni.mjs';
+import { s as setBindingField } from './commands-vnRRkhNE.mjs';
 
 const INVALID_SLUG_CHARS = /[^a-z0-9]+/u;
 const toKebabSlug = (input, min, max) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/cli",
-  "version": "1.0.0-alpha.57",
+  "version": "1.0.0-alpha.59",
   "description": "The Lunora CLI: init, dev, deploy, codegen, run, reset, and migrate commands",
   "keywords": [
     "agent-skills",
@@ -52,11 +52,12 @@
   },
   "dependencies": {
     "@bomb.sh/tab": "0.0.17",
-    "@lunora/codegen": "1.0.0-alpha.28",
-    "@lunora/config": "1.0.0-alpha.45",
-    "@lunora/container": "1.0.0-alpha.5",
-    "@lunora/d1": "1.0.0-alpha.21",
-    "@lunora/seed": "1.0.0-alpha.13",
+    "@lunora/codegen": "1.0.0-alpha.29",
+    "@lunora/config": "1.0.0-alpha.47",
+    "@lunora/container": "1.0.0-alpha.6",
+    "@lunora/d1": "1.0.0-alpha.22",
+    "@lunora/errors": "1.0.0-alpha.1",
+    "@lunora/seed": "1.0.0-alpha.14",
     "@visulima/cerebro": "3.0.0-alpha.32",
     "@visulima/error": "6.0.0-alpha.34",
     "@visulima/fs": "5.0.0-alpha.32",

package/skills/lunora-quickstart/SKILL.md

@@ -31,9 +31,12 @@ Set up a working Lunora project as fast as possible.
    Lunora into the current project.
 4. Run `lunora codegen` to generate `lunora/_generated/` and typecheck the
    schema + functions. This is the agent's feedback loop.
-5. Start the dev loop with `lunora dev` (ask the user to run it locally, or
-   start it in the background for cloud/headless agents — it is long-running and
-   does not exit).
+5. Start the dev loop. As an agent, run `lunora dev --background` — it starts
+   the server as a managed detached process, blocks until it accepts requests,
+   prints the URL + PID, and returns (under a detected AI agent, plain
+   `lunora dev` does this automatically, with JSON logs). Never leave a bare
+   `lunora dev` running in your own shell — it is long-running and does not
+   exit.
 6. Verify a query/mutation round-trip works end to end.
 
 ## Path 1: New Project (Recommended)
@@ -87,7 +90,23 @@ not exit, so:
 
 - **Local development (user at the keyboard):** ask the user to run `lunora dev`
   in a terminal.
-- **Cloud or headless agents:** start `lunora dev` in the background.
+- **Agents:** run `lunora dev --background`. It detaches the server, waits until
+  it answers HTTP, prints `Dev server running at <url> (pid <n>)`, and exits —
+  no orphaned shell, no PID bookkeeping. When Lunora detects an AI agent
+  (Claude Code, Cursor, Codex, …), plain `lunora dev` flips into this mode
+  automatically with JSON logs; `LUNORA_AGENT_MODE=0` opts out.
+
+Manage the running server afterwards:
+
+```bash
+lunora dev status --json   # machine-readable: url, pid, uptime, logFile
+lunora dev logs --lines 50 # tail the captured output (.lunora/dev.log)
+lunora dev stop            # idempotent — succeeds even if nothing runs
+```
+
+A second `lunora dev` never double-starts: it reports the existing instance
+(`.lunora/dev.json` is the lockfile). Probe readiness or liveness at
+`GET /_lunora/status` (`{"ok":true}`).
 
 Vite serves on `http://localhost:5173` by default; the Worker is served on the
 same origin via `@cloudflare/vite-plugin`.
@@ -236,5 +255,6 @@ ids, `.dev.vars` secrets, and container exports.
 - [ ] New project: scaffolded with `lunora init --template <t>`.
 - [ ] Existing app: ran `lunora init --here` and wired `LunoraProvider`.
 - [ ] Ran `lunora codegen`: `lunora/_generated/` exists and typecheck is clean.
-- [ ] `lunora dev` is running — user terminal, or background for cloud agents.
+- [ ] Dev server is running — user terminal, or `lunora dev --background`
+      (check with `lunora dev status`).
 - [ ] Verified a query/mutation round-trip re-renders the client live.

package/dist/packem_shared/runAddCommand-DWjH0Heb.mjs

@@ -1,4 +0,0 @@
-import 'node:fs';
-import '@visulima/path';
-export { r as runAddCommand, a as runBuildIndexCommand, g as runListCommand, b as runRegistryViewCommand } from './commands-BK6Pt3Ni.mjs';
-import './buildRegistryIndex-BcYe607_.mjs';