@lunora/cli 0.0.0 → 1.0.0-alpha.2

package/dist/packem_shared/runAddCommand-BZGkRnBs.mjs

@@ -0,0 +1,693 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { join, dirname } from '@visulima/path';
+import { DEV_VARS_FILE, parseDevVariableEntries, promptYesNo } from '@lunora/config';
+import { modify, applyEdits, parse } from 'jsonc-parser';
+import { collectCatalog, buildRegistryIndex } from './buildRegistryIndex-BcYe607_.mjs';
+import { insertSchemaExtension } from './insertSchemaExtension-BuzF6-t2.mjs';
+import { createHash } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { downloadTemplate } from 'giget';
+import parseManifest from './parseManifest--vZf2FY1.mjs';
+
+const applyDeps = (deps, projectRoot, logger, section = "dependencies") => {
+  const entries = Object.entries(deps);
+  if (entries.length === 0) {
+    return [];
+  }
+  const packageJsonPath = join(projectRoot, "package.json");
+  if (!existsSync(packageJsonPath)) {
+    logger.warn(`package.json not found at ${packageJsonPath} — skipping dependency updates`);
+    return [];
+  }
+  let text = readFileSync(packageJsonPath, "utf8");
+  const parsed = JSON.parse(text);
+  const added = [];
+  for (const [name, range] of entries) {
+    if (parsed.dependencies?.[name] !== void 0 || parsed.devDependencies?.[name] !== void 0) {
+      logger.info(`dep already present: ${name}`);
+      continue;
+    }
+    const edits = modify(text, [section, name], range, {
+      formattingOptions: { insertSpaces: true, tabSize: 4 }
+    });
+    text = applyEdits(text, edits);
+    added.push(name);
+  }
+  if (added.length > 0) {
+    writeFileSync(packageJsonPath, text, "utf8");
+    logger.success(
+      `added ${String(added.length)} ${section === "devDependencies" ? "devDependency(ies)" : "dependency(ies)"} to package.json: ${added.join(", ")}`
+    );
+  }
+  return added;
+};
+const applyEnvVariables = (envVariables, projectRoot, logger) => {
+  if (envVariables.length === 0) {
+    return [];
+  }
+  const devVariablesPath = join(projectRoot, DEV_VARS_FILE);
+  const existing = existsSync(devVariablesPath) ? readFileSync(devVariablesPath, "utf8") : "";
+  const present = new Set(parseDevVariableEntries(existing).map((entry) => entry.key));
+  const appended = [];
+  const secretsToSet = [];
+  const lines = [];
+  for (const variable of envVariables) {
+    if (variable.secret) {
+      secretsToSet.push(variable.name);
+    }
+    if (present.has(variable.name)) {
+      continue;
+    }
+    if (variable.description) {
+      lines.push(`# ${variable.description}`);
+    }
+    lines.push(`${variable.name}=${variable.secret ? "" : variable.value ?? ""}`);
+    appended.push(variable.name);
+  }
+  if (appended.length > 0) {
+    const prefix = existing === "" || existing.endsWith("\n") ? existing : `${existing}
+`;
+    writeFileSync(devVariablesPath, `${prefix}${lines.join("\n")}
+`, "utf8");
+    logger.success(`scaffolded ${String(appended.length)} env var(s) into .dev.vars: ${appended.join(", ")}`);
+  }
+  if (secretsToSet.length > 0) {
+    logger.info(`set secret value(s) locally in .dev.vars, then for production: ${secretsToSet.map((name) => `wrangler secret put ${name}`).join("; ")}`);
+  }
+  return appended;
+};
+const ALLOWED_BINDING_ROOTS = /* @__PURE__ */ new Set([
+  "ai",
+  "analytics_engine_datasets",
+  "browser",
+  "d1_databases",
+  "durable_objects",
+  "hyperdrive",
+  "kv_namespaces",
+  "mtls_certificates",
+  "queues",
+  "r2_buckets",
+  "send_email",
+  "services",
+  "vars",
+  "vectorize",
+  "version_metadata",
+  "workflows"
+]);
+const applyBindings = (bindings, projectRoot, logger) => {
+  if (bindings.length === 0) {
+    return [];
+  }
+  const candidates = ["wrangler.jsonc", "wrangler.json"];
+  const wranglerPath = candidates.map((candidate) => join(projectRoot, candidate)).find((candidate) => existsSync(candidate));
+  if (!wranglerPath) {
+    logger.warn("wrangler.jsonc not found — skipping binding updates");
+    return [];
+  }
+  let text = readFileSync(wranglerPath, "utf8");
+  const applied = [];
+  const isUnknownArray = (value) => Array.isArray(value);
+  const readAt = (path) => {
+    let node = parse(text);
+    for (const segment of path) {
+      if (typeof node !== "object" || node === null) {
+        return void 0;
+      }
+      node = node[segment];
+    }
+    return node;
+  };
+  for (const binding of bindings) {
+    const root = binding.path[0];
+    if (root === void 0 || !ALLOWED_BINDING_ROOTS.has(root)) {
+      logger.warn(
+        `skipping binding "${binding.path.join(".")}" — only resource bindings (${[...ALLOWED_BINDING_ROOTS].join(", ")}) may be written, not exec/entrypoint keys`
+      );
+      continue;
+    }
+    let { value } = binding;
+    if (isUnknownArray(value)) {
+      const existing = readAt(binding.path);
+      if (isUnknownArray(existing)) {
+        const seen = new Set(existing.map((entry) => JSON.stringify(entry)));
+        value = [...existing, ...value.filter((entry) => !seen.has(JSON.stringify(entry)))];
+      }
+    }
+    const edits = modify(text, [...binding.path], value, {
+      formattingOptions: { insertSpaces: true, tabSize: 4 }
+    });
+    if (edits.length === 0) {
+      continue;
+    }
+    text = applyEdits(text, edits);
+    applied.push(binding.path.join("."));
+  }
+  if (applied.length > 0) {
+    writeFileSync(wranglerPath, text, "utf8");
+    logger.success(`applied ${String(applied.length)} binding(s) to ${wranglerPath}: ${applied.join(", ")}`);
+  }
+  return applied;
+};
+const applyItemResources = (manifest, cwd, logger) => {
+  const deps = [];
+  const bindings = [];
+  if (manifest.deps) {
+    deps.push(...applyDeps(manifest.deps, cwd, logger));
+  }
+  if (manifest.devDependencies) {
+    deps.push(...applyDeps(manifest.devDependencies, cwd, logger, "devDependencies"));
+  }
+  if (manifest.bindings) {
+    bindings.push(...applyBindings(manifest.bindings, cwd, logger));
+  }
+  if (manifest.envVars) {
+    applyEnvVariables(manifest.envVars, cwd, logger);
+  }
+  return { bindings, deps };
+};
+const confirmDepMutation = async (items, options) => {
+  const hasDeps = items.some(({ manifest }) => Object.keys(manifest.deps ?? {}).length > 0 || Object.keys(manifest.devDependencies ?? {}).length > 0);
+  const hasBindings = items.some(({ manifest }) => (manifest.bindings ?? []).length > 0);
+  const nonDefaultSource = options.source !== void 0 && options.source.length > 0;
+  if (!hasDeps && !hasBindings && !nonDefaultSource || options.yes) {
+    return true;
+  }
+  const reasons = [];
+  if (hasDeps) {
+    reasons.push("add dependencies to package.json");
+  }
+  if (hasBindings) {
+    reasons.push("write wrangler.jsonc bindings");
+  }
+  if (nonDefaultSource) {
+    reasons.push(`come from a non-default source (${String(options.source)})`);
+  }
+  const reasonText = reasons.join(", ");
+  if (!process.stdin.isTTY && options.confirm === void 0) {
+    options.logger.error(`add: stdin is not a TTY and the requested items ${reasonText} — re-run with --yes to confirm`);
+    return false;
+  }
+  const confirmer = options.confirm ?? promptYesNo;
+  const confirmed = await confirmer(`The requested items ${reasonText}. Continue? [y/N] `);
+  if (!confirmed) {
+    options.logger.info("add: aborted");
+  }
+  return confirmed;
+};
+
+const LOCK_VERSION = 1;
+const LOCK_FILE = ".lunora-registry.json";
+const lockPath = (projectRoot) => join(projectRoot, "lunora", LOCK_FILE);
+const isLockShape = (value) => {
+  if (typeof value !== "object" || value === null || !("items" in value)) {
+    return false;
+  }
+  return typeof value.items === "object" && value.items !== null;
+};
+const hashContent = (content) => createHash("sha256").update(content).digest("hex");
+const readLock = (projectRoot) => {
+  const path = lockPath(projectRoot);
+  if (!existsSync(path)) {
+    return { items: {}, version: LOCK_VERSION };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (isLockShape(parsed)) {
+      return { items: parsed.items, version: LOCK_VERSION };
+    }
+  } catch {
+  }
+  return { items: {}, version: LOCK_VERSION };
+};
+const writeLock = (projectRoot, lock) => {
+  writeFileSync(lockPath(projectRoot), `${JSON.stringify(lock, void 0, 2)}
+`, "utf8");
+};
+const recordFile = (lock, itemKey, destinationRelative, content) => {
+  const existing = lock.items[itemKey];
+  const item = existing ?? { files: {} };
+  if (existing === void 0) {
+    lock.items[itemKey] = item;
+  }
+  item.files[destinationRelative] = hashContent(content);
+};
+const recordedHash = (lock, itemKey, destinationRelative) => lock.items[itemKey]?.files[destinationRelative];
+
+const CONTEXT = 3;
+const splitLines = (text) => text === "" ? [] : text.split("\n");
+const renderDiff = (oldText, newText) => {
+  const a = splitLines(oldText);
+  const b = splitLines(newText);
+  let start = 0;
+  while (start < a.length && start < b.length && a[start] === b[start]) {
+    start += 1;
+  }
+  let endA = a.length;
+  let endB = b.length;
+  while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+    endA -= 1;
+    endB -= 1;
+  }
+  if (start === endA && start === endB) {
+    return [];
+  }
+  const out = [];
+  for (let k = Math.max(0, start - CONTEXT); k < start; k += 1) {
+    out.push(`  ${a[k] ?? ""}`);
+  }
+  for (let k = start; k < endA; k += 1) {
+    out.push(`- ${a[k] ?? ""}`);
+  }
+  for (let k = start; k < endB; k += 1) {
+    out.push(`+ ${b[k] ?? ""}`);
+  }
+  for (let k = endB; k < Math.min(b.length, endB + CONTEXT); k += 1) {
+    out.push(`  ${b[k] ?? ""}`);
+  }
+  return out;
+};
+
+const reconcileSchemaExtension = (file, itemKey, itemDirectory, projectRoot, logger, diff) => {
+  const schemaPath = join(projectRoot, "lunora", "schema.ts");
+  if (diff) {
+    logger.info(`~ would merge .extend(${itemKey}.extension) into lunora/schema.ts (and create ${file.to} if absent)`);
+    return { kind: "skipped", path: schemaPath };
+  }
+  const destinationPath = join(projectRoot, file.to);
+  if (!existsSync(destinationPath)) {
+    mkdirSync(dirname(destinationPath), { recursive: true });
+    writeFileSync(destinationPath, readFileSync(join(itemDirectory, file.from), "utf8"), "utf8");
+  }
+  const existingSchema = existsSync(schemaPath) ? readFileSync(schemaPath, "utf8") : 'import { defineSchema } from "@lunora/server";\n\nexport const schema = defineSchema({});\n';
+  const result = insertSchemaExtension(existingSchema, itemKey);
+  if (result.ok) {
+    mkdirSync(dirname(schemaPath), { recursive: true });
+    writeFileSync(schemaPath, result.text, "utf8");
+    logger.success(`merged .extend(${itemKey}.extension) into lunora/schema.ts`);
+    return { kind: "written", path: schemaPath };
+  }
+  if (result.reason === "already-applied") {
+    logger.warn(`lunora/schema.ts already extends "${itemKey}" — skipping`);
+    return { kind: "skipped", path: schemaPath };
+  }
+  if (result.reason === "invalid-identifier") {
+    throw new Error(
+      `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}`);
+};
+const previewWholeFile = (file, current, incoming, exists, logger) => {
+  const lines = renderDiff(current, incoming);
+  if (lines.length === 0) {
+    logger.info(`= ${file.to} (unchanged)`);
+    return;
+  }
+  logger.info(`${exists ? "~" : "+"} ${file.to}`);
+  for (const line of lines) {
+    logger.info(`    ${line}`);
+  }
+};
+const reconcileWholeFile = (file, itemKey, itemDirectory, projectRoot, logger, lock, reconcileOptions) => {
+  const destinationPath = join(projectRoot, file.to);
+  const incoming = readFileSync(join(itemDirectory, file.from), "utf8");
+  const exists = existsSync(destinationPath);
+  const current = exists ? readFileSync(destinationPath, "utf8") : "";
+  const write = (message) => {
+    mkdirSync(dirname(destinationPath), { recursive: true });
+    writeFileSync(destinationPath, incoming, "utf8");
+    recordFile(lock, itemKey, file.to, incoming);
+    logger.success(`${message}: ${file.to}`);
+    return { kind: "written", path: destinationPath };
+  };
+  if (reconcileOptions.diff) {
+    previewWholeFile(file, current, incoming, exists, logger);
+    return { kind: "skipped", path: destinationPath };
+  }
+  if (!exists) {
+    return write("write");
+  }
+  const currentHash = hashContent(current);
+  if (currentHash === hashContent(incoming)) {
+    recordFile(lock, itemKey, file.to, incoming);
+    logger.warn(`skip (exists): ${file.to}`);
+    return { kind: "skipped", path: destinationPath };
+  }
+  if (reconcileOptions.overwrite) {
+    return write("overwrite");
+  }
+  const base = recordedHash(lock, itemKey, file.to);
+  if (base === void 0) {
+    logger.warn(`skip (exists, untracked): ${file.to} — refusing to overwrite a file lunora didn't add (use --overwrite to force)`);
+    return { kind: "skipped", path: destinationPath };
+  }
+  if (base === currentHash) {
+    return write("update");
+  }
+  writeFileSync(`${destinationPath}.new`, incoming, "utf8");
+  logger.warn(`conflict: ${file.to} has local edits and an upstream update — wrote ${file.to}.new (use --overwrite to take theirs)`);
+  return { kind: "skipped", path: destinationPath };
+};
+const reconcileFile = (file, itemKey, itemDirectory, projectRoot, logger, lock, reconcileOptions = {}) => {
+  if (file.merge === "schema-extension") {
+    return reconcileSchemaExtension(file, itemKey, itemDirectory, projectRoot, logger, reconcileOptions.diff === true);
+  }
+  return reconcileWholeFile(file, itemKey, itemDirectory, projectRoot, logger, lock, reconcileOptions);
+};
+const reconcileItems = (items, cwd, logger, reconcileOptions = {}) => {
+  const written = [];
+  const skipped = [];
+  const depsAdded = [];
+  const bindingsApplied = [];
+  const lock = readLock(cwd);
+  for (const { directory, manifest } of items) {
+    for (const file of manifest.files) {
+      const outcome = reconcileFile(file, manifest.name, directory, cwd, logger, lock, reconcileOptions);
+      (outcome.kind === "written" ? written : skipped).push(outcome.path);
+    }
+    if (reconcileOptions.diff) {
+      continue;
+    }
+    const applied = applyItemResources(manifest, cwd, logger);
+    depsAdded.push(...applied.deps);
+    bindingsApplied.push(...applied.bindings);
+  }
+  if (!reconcileOptions.diff && Object.keys(lock.items).length > 0) {
+    writeLock(cwd, lock);
+  }
+  return { bindings: bindingsApplied, deps: depsAdded, skipped, written };
+};
+
+const DEFAULT_SOURCE_BASE = "gh:anolilab/lunora/registry";
+const DEFAULT_SOURCE_REF = "alpha";
+const VALID_ITEM_NAME = /^[A-Za-z0-9][\w-]*$/u;
+const assertSafeItemName = (name) => {
+  if (!VALID_ITEM_NAME.test(name)) {
+    throw new Error(
+      `invalid registry item name "${name}" — names must match ${VALID_ITEM_NAME.source} (letters, digits, "-", "_"; no path separators or "..")`
+    );
+  }
+};
+const isSafeSource = (source) => {
+  if (source.includes("..")) {
+    return false;
+  }
+  return source.startsWith("gh:") || source.startsWith("github:") || source.startsWith("https://");
+};
+const isBlockedRemoteSource = (options) => options.from === void 0 && options.source !== void 0 && options.source.length > 0 && !options.allowUnsafeSource && !isSafeSource(options.source);
+const sourceGateError = (command, options) => isBlockedRemoteSource(options) ? `${command}: refusing --source ${String(options.source)} — only gh:, github:, or https:// sources are allowed (and may not contain ".."). Re-run with --allow-unsafe-source if you really want this.` : void 0;
+const fetchToStaging = async (remote, label, logger) => {
+  const stagingRoot = mkdtempSync(join(tmpdir(), `lunora-${label}-fetch-`));
+  const stagingDirectory = join(stagingRoot, label);
+  logger.info(`fetching ${remote}`);
+  try {
+    const downloaded = await downloadTemplate(remote, {
+      cwd: stagingRoot,
+      dir: stagingDirectory,
+      force: true,
+      install: false,
+      silent: true
+    });
+    logger.info(downloaded.commit ? `resolved ${downloaded.source} @ ${downloaded.commit}` : `resolved ${downloaded.source}`);
+    return {
+      cleanup: () => {
+        rmSync(stagingRoot, { force: true, recursive: true });
+      },
+      directory: stagingDirectory
+    };
+  } catch (error) {
+    rmSync(stagingRoot, { force: true, recursive: true });
+    throw error;
+  }
+};
+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}`);
+    }
+    return { cleanup: () => {
+    }, directory };
+  }
+  const base = options.source ?? DEFAULT_SOURCE_BASE;
+  return fetchToStaging(`${base}/${name}#${DEFAULT_SOURCE_REF}`, "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}`);
+    }
+    return { cleanup: () => {
+    }, root: options.from };
+  }
+  const base = options.source ?? DEFAULT_SOURCE_BASE;
+  const { cleanup, directory } = await fetchToStaging(`${base}#${DEFAULT_SOURCE_REF}`, "registry", options.logger);
+  return { cleanup, root: directory };
+};
+const readManifest = (itemDirectory, name) => {
+  const raw = JSON.parse(readFileSync(join(itemDirectory, "registry.json"), "utf8"));
+  return parseManifest(raw, name);
+};
+const resolvePlan = async (names, options) => {
+  const items = [];
+  const cleanups = [];
+  const seen = /* @__PURE__ */ new Set();
+  const inProgress = /* @__PURE__ */ new Set();
+  const visit = async (name) => {
+    if (seen.has(name)) {
+      return;
+    }
+    if (inProgress.has(name)) {
+      throw new Error(`cyclic registry dependency detected at "${name}"`);
+    }
+    inProgress.add(name);
+    const { cleanup, directory } = await resolveItemDirectory(name, options);
+    cleanups.push(cleanup);
+    const manifest = readManifest(directory, name);
+    for (const requirement of manifest.requires ?? []) {
+      await visit(requirement);
+    }
+    inProgress.delete(name);
+    seen.add(name);
+    items.push({ directory, manifest });
+  };
+  try {
+    for (const name of names) {
+      await visit(name);
+    }
+  } catch (error) {
+    for (const cleanup of cleanups) {
+      cleanup();
+    }
+    throw error;
+  }
+  return { cleanups, items };
+};
+
+const emptyResult = () => {
+  return { bindings: [], code: 0, deps: [], skipped: [], written: [] };
+};
+
+const printPlan = (logger, manifest) => {
+  const label = manifest.title ?? manifest.description;
+  logger.info(`plan: ${manifest.name}${label ? ` — ${label}` : ""}`);
+  for (const file of manifest.files) {
+    logger.info(`  file  ${file.to}  (${file.merge})`);
+  }
+  for (const [dep, range] of Object.entries(manifest.deps ?? {})) {
+    logger.info(`  dep   ${dep}@${range}`);
+  }
+  for (const [dep, range] of Object.entries(manifest.devDependencies ?? {})) {
+    logger.info(`  dev   ${dep}@${range}`);
+  }
+  for (const binding of manifest.bindings ?? []) {
+    logger.info(`  bind  ${binding.path.join(".")} = ${JSON.stringify(binding.value)}`);
+  }
+  for (const variable of manifest.envVars ?? []) {
+    const valueSuffix = variable.secret ? " (secret)" : ` = ${JSON.stringify(variable.value ?? "")}`;
+    logger.info(`  env   ${variable.name}${valueSuffix}`);
+  }
+};
+const printJsonPlan = (items) => {
+  const planSnapshot = items.map(({ manifest }) => {
+    return {
+      // Include the concrete value so a JSON-plan consumer can audit the
+      // mutation (not just the key path) before it is applied.
+      bindings: (manifest.bindings ?? []).map((binding) => {
+        return { path: binding.path.join("."), value: binding.value };
+      }),
+      deps: Object.keys(manifest.deps ?? {}),
+      devDependencies: Object.keys(manifest.devDependencies ?? {}),
+      envVars: (manifest.envVars ?? []).map((variable) => {
+        return { name: variable.name, ...variable.secret ? { secret: true } : { value: variable.value ?? "" } };
+      }),
+      files: manifest.files.map((file) => {
+        return { merge: file.merge, to: file.to };
+      }),
+      name: manifest.name,
+      requires: manifest.requires ?? [],
+      title: manifest.title
+    };
+  });
+  process.stdout.write(`${JSON.stringify({ items: planSnapshot }, void 0, 2)}
+`);
+};
+const reportAddResult = (items, deps, written, skipped, logger) => {
+  logger.success(`add complete: ${String(written)} written, ${String(skipped)} skipped`);
+  logger.info("next steps:");
+  logger.info("  lunora codegen   # regenerate _generated/ so the new tables/functions appear");
+  if (deps.length > 0) {
+    logger.info("  pnpm install     # install newly-added dependencies");
+  }
+  for (const { manifest } of items) {
+    if (manifest.docs) {
+      logger.info(`${manifest.name}: ${manifest.docs}`);
+    }
+  }
+};
+const runListCommand = async (options) => {
+  const empty = emptyResult();
+  const gate = sourceGateError("list", options);
+  if (gate) {
+    options.logger.error(gate);
+    return { ...empty, code: 1 };
+  }
+  let cleanup = () => {
+  };
+  try {
+    const resolved = await resolveRegistryRoot(options);
+    cleanup = resolved.cleanup;
+    const items = collectCatalog(resolved.root);
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify(items, void 0, 2)}
+`);
+      return empty;
+    }
+    options.logger.info(`available registry items (${String(items.length)}):`);
+    for (const item of items) {
+      options.logger.info(`  ${item.name}${item.description ? ` — ${item.description}` : ""}`);
+    }
+    return empty;
+  } catch (error) {
+    options.logger.error(`list failed: ${error instanceof Error ? error.message : String(error)}`);
+    return { ...empty, code: 1 };
+  } finally {
+    cleanup();
+  }
+};
+const runAddCommand = async (options) => {
+  const cwd = options.cwd ?? process.cwd();
+  const empty = emptyResult();
+  if (options.list) {
+    return runListCommand(options);
+  }
+  if (options.names.length === 0) {
+    options.logger.error("add requires at least one item name. Usage: lunora registry add <name> [...names]");
+    return { ...empty, code: 1 };
+  }
+  const gate = sourceGateError("add", options);
+  if (gate) {
+    options.logger.error(gate);
+    return { ...empty, code: 1 };
+  }
+  let cleanups = [];
+  try {
+    const { cleanups: planCleanups, items } = await resolvePlan(options.names, options);
+    cleanups = planCleanups;
+    for (const { manifest } of items) {
+      printPlan(options.logger, manifest);
+    }
+    if (options.json) {
+      printJsonPlan(items);
+    }
+    if (options.dryRun) {
+      options.logger.info("dry-run: stopping before any files are written");
+      return empty;
+    }
+    if (options.diff) {
+      reconcileItems(items, cwd, options.logger, { diff: true });
+      options.logger.info("diff: preview only — re-run without --diff to apply");
+      return empty;
+    }
+    if (!await confirmDepMutation(items, options)) {
+      return { ...empty, code: 1 };
+    }
+    const { bindings, deps, skipped, written } = reconcileItems(items, cwd, options.logger, { overwrite: options.overwrite });
+    reportAddResult(items, deps, written.length, skipped.length, options.logger);
+    return { bindings, code: 0, deps, skipped, written };
+  } catch (error) {
+    options.logger.error(`add failed: ${error instanceof Error ? error.message : String(error)}`);
+    return { ...empty, code: 1 };
+  } finally {
+    for (const cleanup of cleanups) {
+      cleanup();
+    }
+  }
+};
+const runRegistryViewCommand = async (options) => {
+  const empty = emptyResult();
+  if (options.names.length === 0) {
+    options.logger.error("view requires an item name. Usage: lunora registry view <name>");
+    return { ...empty, code: 1 };
+  }
+  const gate = sourceGateError("view", options);
+  if (gate) {
+    options.logger.error(gate);
+    return { ...empty, code: 1 };
+  }
+  const cleanups = [];
+  try {
+    for (const name of options.names) {
+      const { cleanup, directory } = await resolveItemDirectory(name, options);
+      cleanups.push(cleanup);
+      const manifest = readManifest(directory, name);
+      printPlan(options.logger, manifest);
+      for (const file of manifest.files) {
+        options.logger.info(`--- ${file.to} (${file.merge}) ---`);
+        const content = readFileSync(join(directory, file.from), "utf8");
+        for (const line of content.split("\n")) {
+          options.logger.info(line);
+        }
+      }
+    }
+    return empty;
+  } catch (error) {
+    options.logger.error(`view failed: ${error instanceof Error ? error.message : String(error)}`);
+    return { ...empty, code: 1 };
+  } finally {
+    for (const cleanup of cleanups) {
+      cleanup();
+    }
+  }
+};
+const runBuildIndexCommand = async (options) => {
+  const empty = emptyResult();
+  const root = options.from;
+  if (root === void 0) {
+    options.logger.error("registry build requires --from <registry root>");
+    return { ...empty, code: 1 };
+  }
+  if (!existsSync(root)) {
+    options.logger.error(`registry root not found: ${root}`);
+    return { ...empty, code: 1 };
+  }
+  const index = buildRegistryIndex(root);
+  const outputPath = options.out ?? join(root, "index.json");
+  if (options.check) {
+    const current = existsSync(outputPath) ? JSON.parse(readFileSync(outputPath, "utf8")) : { items: [] };
+    const drift = JSON.stringify(current.items ?? []) !== JSON.stringify(index.items);
+    if (drift) {
+      options.logger.error(`registry: ${outputPath} is stale — run \`lunora registry build\` to regenerate it`);
+      return { ...empty, code: 1 };
+    }
+    options.logger.success(`registry: ${outputPath} is up to date (${String(index.items.length)} items)`);
+    return empty;
+  }
+  writeFileSync(outputPath, `${JSON.stringify({ $schema: "./schema/registry.schema.json", ...index }, void 0, 4)}
+`, "utf8");
+  options.logger.success(`registry: wrote ${outputPath} (${String(index.items.length)} items)`);
+  return empty;
+};
+
+export { runAddCommand, runBuildIndexCommand, runListCommand, runRegistryViewCommand };