arcane-cli 1.9.2 → 1.10.1

package/dist/index.js

@@ -121,6 +121,15 @@ async function copyDirectory(srcDir, targetDir, relativeDir, opts = {}) {
   }
   return copiedFiles;
 }
+async function listDirectoryFiles(srcDir, relativeDir) {
+  const files = [];
+  for (const entry of await readdir(srcDir, { withFileTypes: true })) {
+    const rel = `${relativeDir}/${entry.name}`;
+    if (entry.isDirectory()) files.push(...await listDirectoryFiles(path.join(srcDir, entry.name), rel));
+    else files.push(rel);
+  }
+  return files;
+}
 
 // src/modules/manifest.ts
 import { readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
@@ -1470,7 +1479,7 @@ async function printWelcome(version, cwd) {
   }
   printFooter(version);
   console.log();
-  const label = (s) => chalk.hex(STEEL_DIM)(s.padEnd(11));
+  const label2 = (s) => chalk.hex(STEEL_DIM)(s.padEnd(11));
   const dot = chalk.hex(FAINT)("\xB7");
   let repoLine;
   try {
@@ -1481,11 +1490,11 @@ async function printWelcome(version, cwd) {
   } catch {
     repoLine = `${chalk.hex(STEEL_DIM)("\u25CB")} not initialized ${chalk.hex(FAINT)("\u2014")} run ${chalk.hex(STEEL).inverse(" spell init ")} ${chalk.hex(STEEL_DIM)("to scaffold")}`;
   }
-  console.log(`  ${label("This repo")}${repoLine}`);
+  console.log(`  ${label2("This repo")}${repoLine}`);
   const phases = ["plan", "architect", "implement", "test", "review", "ship"].join(
     chalk.hex(STEEL_DEEP)(" \u2192 ")
   );
-  console.log(`  ${label("Spell Loop")}${chalk.hex("#dbe3f7")(phases)}`);
+  console.log(`  ${label2("Spell Loop")}${chalk.hex("#dbe3f7")(phases)}`);
   const flat = ["plan", "architect", "implement", "test", "review", "ship"].join(" \u2192 ");
   const loopStart = 13 + flat.indexOf("implement");
   const loopEnd = 13 + flat.indexOf("review") + 5;
@@ -2469,7 +2478,7 @@ async function runAgentsInit(options, targetDir, assetsDir) {
   const scope = options.scope ?? "repo";
   if (scope === "user") await requireUserStore(targetDir);
   const baseDir = agentsBaseDir(targetDir, scope);
-  const label = scope === "user" ? "~/.arcane" : ".arcane";
+  const label2 = scope === "user" ? "~/.arcane" : ".arcane";
   if (!options.force && await rosterExists(targetDir, scope)) {
     console.log(
       'Agent roster already exists at .arcane/agents.yaml. Run "spell agents sync" to regenerate outputs, or use --force to reinitialize.'
@@ -2569,7 +2578,7 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
     await mkdir4(arcaneDir, { recursive: true });
     await writeFile6(join4(baseDir, "agents.yaml"), stringify(roster), "utf8");
   } else {
-    console.log(`  [dry-run] Would write: ${label}/agents.yaml`);
+    console.log(`  [dry-run] Would write: ${label2}/agents.yaml`);
   }
   for (const roleId of selectedRoleIds) {
     const src = join4(assetsDir, "agents", `${roleId}.yaml`);
@@ -2581,7 +2590,7 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
         console.warn(`  ! Could not copy definition for "${roleId}" \u2014 skipping`);
       }
     } else {
-      console.log(`  [dry-run] Would copy: ${label}/agents/${roleId}.yaml`);
+      console.log(`  [dry-run] Would copy: ${label2}/agents/${roleId}.yaml`);
     }
   }
   if (options.dryRun) {
@@ -2608,7 +2617,7 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
   }
   console.log();
   console.log(
-    `    \u{1F4A1} Customize: edit ${label}/agents.yaml \u2192 spell agents sync${scope === "user" ? " --user" : ""}`
+    `    \u{1F4A1} Customize: edit ${label2}/agents.yaml \u2192 spell agents sync${scope === "user" ? " --user" : ""}`
   );
   console.log();
   if (hasUnresolvedRoles) {
@@ -4407,30 +4416,116 @@ async function runInitUser(options, storeRoot, assetsDir, packageVersion) {
   console.log();
 }
 
-// src/commands/add.ts
+// src/modules/component-install.ts
+import { readFile as readFile7, stat, writeFile as writeFile9 } from "fs/promises";
 import { join as join8 } from "path";
-async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
-  let manifest;
+async function planComponentInstall(component, targetDir, assetsDir, opts = {}) {
+  const files = [];
+  const stateOf = async (file, src) => {
+    const dest = join8(targetDir, file);
+    if (!await fileExists(dest)) return { file, src, state: "missing" };
+    if ((await stat(dest)).isDirectory()) return { file, src, state: "directory" };
+    const same = await hashFile(dest) === await hashFile(src);
+    return { file, src, state: same ? "identical" : "differs" };
+  };
+  for (const file of component.files) {
+    files.push(await stateOf(file, join8(assetsDir, component.sourceOverrides?.[file] ?? file)));
+  }
+  for (const dir of component.directories ?? []) {
+    const srcDir = join8(assetsDir, dir);
+    for (const file of await listDirectoryFiles(srcDir, dir)) {
+      files.push(await stateOf(file, join8(assetsDir, file)));
+    }
+  }
+  const of = (...states) => files.filter((f) => states.includes(f.state));
+  if (opts.force) {
+    return { component, files, toCopy: of("missing", "identical", "differs"), kept: [], conflicts: of("directory") };
+  }
+  if (component.skipExisting) {
+    return { component, files, toCopy: of("missing"), kept: of("identical", "differs", "directory"), conflicts: [] };
+  }
+  return { component, files, toCopy: of("missing", "identical"), kept: [], conflicts: of("differs", "directory") };
+}
+async function executeInstallPlan(plan, targetDir) {
+  const files = [];
+  const fileHashes = {};
+  const written = [];
   try {
-    manifest = await readManifest(targetDir);
-  } catch (err) {
-    if (err instanceof ManifestNotFoundError) {
-      console.error(
-        'Not initialized. Run "spell init" first before adding components.'
-      );
-      process.exit(1);
-      return;
+    for (const { file, src, state } of plan.toCopy) {
+      const previous = state === "missing" ? null : await readFile7(join8(targetDir, file));
+      fileHashes[file] = await copyFile(src, targetDir, file, { force: true });
+      written.push({ file, previous });
+      files.push(file);
     }
+  } catch (err) {
+    await rollback(written, targetDir);
     throw err;
   }
+  return { files, fileHashes };
+}
+async function rollback(written, targetDir) {
+  for (const { file, previous } of [...written].reverse()) {
+    try {
+      if (previous === null) {
+        await removeWithin(targetDir, file);
+        await removeEmptyAncestors(targetDir, file);
+      } else {
+        await writeFile9(join8(targetDir, file), previous);
+      }
+    } catch {
+    }
+  }
+}
+
+// src/commands/add.ts
+function describeExisting(f) {
+  if (f.state === "directory") return "is a directory";
+  return f.state === "identical" ? "identical to the packaged file" : "differs from the packaged file";
+}
+function directoryConflict(plan) {
+  return plan.conflicts.find((f) => f.state === "directory");
+}
+function printDryRun2(name, plan, options) {
+  for (const f of plan.files) {
+    if (f.state === "missing") {
+      console.log(`  [dry-run] Would copy: ${f.file}`);
+    } else if (f.state === "directory" && !(plan.component.skipExisting && !options.force)) {
+      console.log(`  [dry-run] Would refuse: ${f.file} (exists, is a directory) \u2014 remove it first`);
+    } else if (options.force) {
+      console.log(`  [dry-run] Would overwrite: ${f.file} (exists, ${describeExisting(f)})`);
+    } else if (plan.component.skipExisting) {
+      console.log(`  [dry-run] Would keep: ${f.file} (exists, yours, ${describeExisting(f)})`);
+    } else if (f.state === "identical") {
+      console.log(`  [dry-run] Would adopt: ${f.file} (exists, identical to the packaged file)`);
+    } else {
+      console.log(`  [dry-run] Would refuse: ${f.file} (exists, ${describeExisting(f)}) \u2014 needs --force`);
+    }
+  }
+  const dir = directoryConflict(plan);
+  if (dir) {
+    console.log(`
+[dry-run] Would refuse component "${name}": a directory is at "${dir.file}", which --force does not replace. Remove it first.`);
+    return;
+  }
+  if (plan.conflicts.length > 0) {
+    console.log(
+      `
+[dry-run] Would refuse component "${name}": ${plan.conflicts.length} existing file${plan.conflicts.length === 1 ? "" : "s"}. Re-run with --force to overwrite.`
+    );
+    return;
+  }
+  console.log(`
+[dry-run] Would add component "${name}" \u2014 ${plan.toCopy.length} files`);
+}
+async function addOne(name, options, targetDir, assetsDir, packageVersion) {
+  const manifest = await readManifest(targetDir);
   let component;
   try {
     component = getComponent(name);
   } catch (err) {
     if (err instanceof ComponentNotFoundError) {
       console.error(err.message);
-      process.exit(1);
-      return;
+      return "failed";
     }
     throw err;
   }
@@ -4438,58 +4533,81 @@ async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
     console.log(
       `Component "${name}" is already installed. Use "spell update" to update it.`
     );
-    return;
+    return "skipped";
   }
-  let fileCount = 0;
-  const installedFiles = [];
-  const fileHashes = {};
-  for (const file of component.files) {
-    const srcPath = join8(assetsDir, component.sourceOverrides?.[file] ?? file);
-    if (options.dryRun) {
-      console.log(`  [dry-run] Would copy: ${file}`);
-    } else {
-      fileHashes[file] = await copyFile(srcPath, targetDir, file, { force: options.force });
-    }
-    installedFiles.push(file);
-    fileCount++;
+  const plan = await planComponentInstall(component, targetDir, assetsDir, { force: options.force });
+  if (options.dryRun) {
+    printDryRun2(name, plan, options);
+    return plan.conflicts.length > 0 ? "failed" : "added";
   }
-  for (const dir of component.directories ?? []) {
-    const srcDirPath = join8(assetsDir, dir);
-    if (options.dryRun) {
-      console.log(`  [dry-run] Would copy directory: ${dir}/`);
-    } else {
-      const copied = await copyDirectory(srcDirPath, targetDir, dir, { force: options.force });
-      for (const { path: copiedPath, hash } of copied) {
-        installedFiles.push(copiedPath);
-        fileHashes[copiedPath] = hash;
-      }
-      fileCount += copied.length;
-    }
+  const dir = directoryConflict(plan);
+  if (dir) {
+    console.error(
+      `Cannot add "${name}": "${dir.file}" is a directory, which --force does not replace. Nothing was written. Remove it first.`
+    );
+    return "failed";
   }
-  if (options.dryRun) {
-    console.log(
-      `
-[dry-run] Would add component "${name}" \u2014 ${fileCount} files`
+  if (plan.conflicts.length > 0) {
+    const others = plan.conflicts.length - 1;
+    console.error(
+      `Cannot add "${name}": "${plan.conflicts[0].file}" already exists${others > 0 ? ` (and ${others} more)` : ""}. Nothing was written. Use --force to overwrite.`
     );
-    return;
+    return "failed";
   }
+  const { files, fileHashes } = await executeInstallPlan(plan, targetDir);
+  for (const f of plan.kept) console.log(`  Kept existing (yours): ${f.file}`);
   const newComponent = {
     name,
-    files: installedFiles,
+    files,
     installedVersion: packageVersion,
     fileHashes
   };
-  const updated = addComponent(manifest, newComponent);
-  await writeManifest(targetDir, updated);
+  await writeManifest(targetDir, addComponent(manifest, newComponent));
   console.log(
     `
-\u2713 Added component "${name}" \u2014 ${fileCount} files copied`
+\u2713 Added component "${name}" \u2014 ${files.length} files copied${plan.kept.length > 0 ? `, ${plan.kept.length} kept` : ""}`
   );
+  return "added";
+}
+async function runAdd(names, options, targetDir, assetsDir, packageVersion) {
+  try {
+    await readManifest(targetDir);
+  } catch (err) {
+    if (err instanceof ManifestNotFoundError) {
+      console.error(
+        'Not initialized. Run "spell init" first before adding components.'
+      );
+      process.exit(1);
+      return;
+    }
+    throw err;
+  }
+  const added = [];
+  const refused = [];
+  for (const [index, name] of names.entries()) {
+    const outcome = await addOne(name, options, targetDir, assetsDir, packageVersion);
+    if (outcome === "added") added.push(name);
+    if (outcome !== "failed") continue;
+    refused.push(name);
+    if (options.dryRun) continue;
+    if (names.length > 1) {
+      const notAttempted = names.slice(index + 1);
+      console.error(
+        `Added: ${added.length > 0 ? added.join(", ") : "none"}.${notAttempted.length > 0 ? ` Not attempted: ${notAttempted.join(", ")}.` : ""}`
+      );
+    }
+    process.exit(1);
+    return;
+  }
+  if (refused.length > 0) {
+    console.error(`[dry-run] Would refuse: ${refused.join(", ")}.`);
+    process.exit(1);
+  }
 }
 
 // src/commands/update.ts
 import { dirname as dirname5, join as join10 } from "path";
-import { readFile as readFile7, writeFile as writeFile9 } from "fs/promises";
+import { readFile as readFile8, writeFile as writeFile10 } from "fs/promises";
 
 // src/modules/merge3.ts
 var CONFLICT_START = "<<<<<<< yours (edited)";
@@ -4693,27 +4811,111 @@ function formatRegistryChanges(changes) {
   }
   if (newlyAvailable.length > 0) {
     const profile = changes.profile ? ` "${changes.profile}"` : "";
-    lines.push(`  Newly available for your${profile} profile, not installed \u2014 nothing was added:`);
+    lines.push(
+      changes.installedByUpdate ? `  Newly available for your${profile} profile, not installed by this run:` : `  Newly available for your${profile} profile, not installed \u2014 nothing was added:`
+    );
     for (const component of newlyAvailable) {
       lines.push(`    ${component.name} \u2014 ${component.description}`);
       lines.push(`      spell add ${component.name}`);
       if (component.alreadyPresent.length > 0) {
         lines.push(
-          `      (already here and yours: ${component.alreadyPresent.join(", ")} \u2014 \`spell add\` stops at an existing file rather than overwrite it)`
+          `      (already here and yours: ${component.alreadyPresent.join(", ")} \u2014 \`spell add\` keeps it rather than overwrite it)`
         );
       }
     }
+    if (!changes.addNewUsed) lines.push("    To install them in one step: `spell update --add-new`");
   }
   if (missingRequires.length > 0) {
     lines.push("  Missing prerequisites \u2014 installed components cite these, and they are not installed:");
-    for (const { name, requiredBy } of missingRequires) {
+    for (const { name, requiredBy, leftAloneReason } of missingRequires) {
       lines.push(`    ${name} (required by ${requiredBy.join(", ")})`);
       lines.push(`      spell add ${name}`);
+      if (leftAloneReason) lines.push(`      (not installed by update: ${leftAloneReason})`);
     }
   }
   return lines;
 }
 
+// src/modules/update-installs.ts
+import { checkbox as checkbox2 } from "@inquirer/prompts";
+function offerableNewComponents(newlyAvailable, missingRequires) {
+  return newlyAvailable.filter(
+    (c) => !getComponent(c.name).initOnly && !missingRequires.some((m) => m.name === c.name)
+  );
+}
+async function selectNewComponents(candidates, mode) {
+  if (candidates.length === 0) return [];
+  if (mode.addNew) return candidates;
+  if (!mode.interactive || mode.dryRun) return [];
+  const chosen = await checkbox2({
+    message: "Newly available components. Space to select, Enter to confirm (none selected installs nothing):",
+    choices: candidates.map((c) => ({ name: `${c.name} \u2014 ${c.description}`, value: c.name, checked: false }))
+  });
+  return candidates.filter((c) => chosen.includes(c.name));
+}
+async function planUpdateInstalls(args) {
+  const items = [];
+  const leftAlone = [];
+  for (const { name, requiredBy } of args.missingRequires) {
+    const component = componentForSpellScope(getComponent(name), args.spellScope);
+    if (component.initOnly) {
+      leftAlone.push({ name, kind: "prerequisite", reason: "it is an initOnly component: adding it mid-life changes how Git treats existing files, so it is your call" });
+      continue;
+    }
+    if (component.files.length === 0) continue;
+    const plan = await planComponentInstall(component, args.targetDir, args.assetsDir, {});
+    if (plan.conflicts.length > 0) {
+      leftAlone.push({ name, kind: "prerequisite", reason: conflictReason(plan) });
+      continue;
+    }
+    items.push({ plan, kind: "prerequisite", requiredBy });
+  }
+  for (const candidate of args.selectedNew) {
+    const component = componentForSpellScope(getComponent(candidate.name), args.spellScope);
+    if (component.initOnly || component.files.length === 0) continue;
+    const plan = await planComponentInstall(component, args.targetDir, args.assetsDir, {});
+    if (plan.conflicts.length > 0) {
+      leftAlone.push({ name: candidate.name, kind: "new", reason: conflictReason(plan) });
+      continue;
+    }
+    items.push({ plan, kind: "new", requiredBy: [] });
+  }
+  return { items, leftAlone };
+}
+function conflictReason(plan) {
+  const first = plan.conflicts[0];
+  if (first.state === "directory") return `${first.file} is a directory, which update does not replace`;
+  const more = plan.conflicts.length > 1 ? ` (and ${plan.conflicts.length - 1} more)` : "";
+  return `${first.file} already exists${more}, and update does not overwrite`;
+}
+function label(item) {
+  return item.kind === "prerequisite" ? `prerequisite of ${item.requiredBy.join(", ")}` : "newly available";
+}
+function describeInstallPlan(plan) {
+  const lines = [];
+  for (const item of plan.items) {
+    lines.push(`  [dry-run] Would install: ${item.plan.component.name} (${label(item)}) \u2014 ${item.plan.toCopy.length} files`);
+    for (const f of item.plan.kept) lines.push(`    [dry-run] Would keep: ${f.file} (exists, yours)`);
+  }
+  return lines;
+}
+async function executeUpdateInstalls(plan, targetDir, packageVersion) {
+  const installed = [];
+  const lines = [];
+  for (const item of plan.items) {
+    const { files, fileHashes } = await executeInstallPlan(item.plan, targetDir);
+    installed.push({
+      name: item.plan.component.name,
+      files,
+      installedVersion: packageVersion,
+      fileHashes
+    });
+    lines.push(`  Installed: ${item.plan.component.name} (${label(item)}) \u2014 ${files.length} files`);
+    for (const f of item.plan.kept) lines.push(`    Kept existing (yours): ${f.file}`);
+  }
+  return { installed, lines };
+}
+
 // src/modules/npm-registry.ts
 var NPM_PACKAGE_NAME = "arcane-cli";
 async function fetchPublishedFile(version, relativeAssetPath) {
@@ -4947,6 +5149,13 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
     return;
   }
   const scope = resolvedScope.scope;
+  if (options.addNew && scope !== "repo") {
+    console.error(
+      "\n  \u2717 --add-new offers the components a repository's profile gained; the user tier has no profile. Run it without --user, inside a repository.\n"
+    );
+    process.exit(1);
+    return;
+  }
   let flagPatch = {};
   if (hasManifestFlags(options.manifestFlags)) {
     if (scope !== "repo") {
@@ -5015,19 +5224,49 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
       missingRequires: findMissingRequires(manifest.components, manifest.profile)
     } : {}
   };
+  let installPlan = { items: [], leftAlone: [] };
+  if (scope === "repo" && manifest.components.length > 0) {
+    const missingRequires = registryChanges.missingRequires ?? [];
+    const selectedNew = await selectNewComponents(
+      offerableNewComponents(registryChanges.newlyAvailable ?? [], missingRequires),
+      { addNew: Boolean(options.addNew), interactive: Boolean(process.stdin.isTTY), dryRun: Boolean(options.dryRun) }
+    );
+    installPlan = await planUpdateInstalls({ targetDir, assetsDir, spellScope, missingRequires, selectedNew });
+    const installing = new Set(installPlan.items.map((i) => i.plan.component.name));
+    registryChanges.installedByUpdate = installing.size > 0;
+    registryChanges.addNewUsed = Boolean(options.addNew);
+    registryChanges.newlyAvailable = (registryChanges.newlyAvailable ?? []).filter((c) => !installing.has(c.name));
+    registryChanges.missingRequires = missingRequires.filter((m) => !installing.has(m.name)).map((m) => ({ ...m, leftAloneReason: installPlan.leftAlone.find((l) => l.name === m.name)?.reason }));
+  }
   const printRegistryChanges = () => {
     for (const line of formatRegistryChanges(registryChanges)) console.log(line);
   };
+  const applyInstalls = async () => {
+    const declined = installPlan.leftAlone.filter((l) => l.kind === "new");
+    if (installPlan.items.length === 0 && declined.length === 0) return [];
+    console.log(options.dryRun ? "\n[dry-run] Components this update would install (ARC-052):" : "\nComponents installed by this update (ARC-052):");
+    for (const l of declined) console.log(`  ! Not installed: ${l.name} \u2014 ${l.reason}`);
+    if (options.dryRun) {
+      for (const line of describeInstallPlan(installPlan)) console.log(line);
+      return [];
+    }
+    const { installed, lines } = await executeUpdateInstalls(installPlan, targetDir, packageVersion);
+    for (const line of lines) console.log(line);
+    return installed;
+  };
   let sameVersionRestore = false;
   if (manifest.version === packageVersion && manifest.components.length > 0) {
     const missing = await findMissingTrackedFiles(targetDir, manifest.components, scope, spellScope, readopted);
     const unmanaged = findUnmanagedTrackedFiles(manifest.components, scope, spellScope);
     if (missing.length === 0 && unmanaged.length === 0) {
-      console.log("Already up to date.");
+      console.log(installPlan.items.length === 0 ? "Already up to date." : "Installed components are at the current version.");
+      const newlyInstalled = await applyInstalls();
       printRegistryChanges();
-      if (scope === "repo" && Object.keys(flagPatch).length > 0) {
-        if (!options.dryRun) await writeManifest(targetDir, answered);
-        reportFlagPatch(flagPatch, manifest, answered, options.dryRun);
+      if (scope === "repo" && (Object.keys(flagPatch).length > 0 || newlyInstalled.length > 0)) {
+        if (!options.dryRun) {
+          await writeManifest(targetDir, { ...answered, components: [...answered.components, ...newlyInstalled] });
+        }
+        if (Object.keys(flagPatch).length > 0) reportFlagPatch(flagPatch, manifest, answered, options.dryRun);
       }
       if (scope === "user") {
         const fanout = await syncUserTierFanout({
@@ -5161,11 +5400,11 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
             handled = true;
           } else {
             const [currentContent, newContent] = await Promise.all([
-              readFile7(join10(targetDir, file), "utf-8"),
-              readFile7(srcPath, "utf-8")
+              readFile8(join10(targetDir, file), "utf-8"),
+              readFile8(srcPath, "utf-8")
             ]);
             const result = merge3(oldVendorContent, currentContent, newContent);
-            await writeFile9(join10(targetDir, file), result.content, "utf-8");
+            await writeFile10(join10(targetDir, file), result.content, "utf-8");
             fileHashes[file] = await hashFile(srcPath);
             if (result.hasConflict) {
               conflictedFiles.push(file);
@@ -5214,6 +5453,7 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
       fileHashes
     });
   }
+  updatedComponents.push(...await applyInstalls());
   const claimed = new Set(updatedComponents.flatMap((c) => c.files));
   const resolvedOrphans = /* @__PURE__ */ new Set();
   for (const { owner, file, recordedHash } of orphanCandidates) {
@@ -5349,7 +5589,7 @@ ${verb} ${orphansToReport.length} orphaned file(s) (tracked before this update,
 import { dirname as dirname7 } from "path";
 
 // src/modules/version-check.ts
-import { readFile as readFile8, writeFile as writeFile10, mkdir as mkdir6 } from "fs/promises";
+import { readFile as readFile9, writeFile as writeFile11, mkdir as mkdir6 } from "fs/promises";
 import { dirname as dirname6, join as join11 } from "path";
 import { homedir as homedir3 } from "os";
 import { createRequire } from "module";
@@ -5368,7 +5608,7 @@ var DEFAULT_CACHE_PATH = join11(homedir3(), ".arcane", "version-cache.json");
 var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
 async function readCache(cachePath) {
   try {
-    const content = await readFile8(cachePath, "utf-8");
+    const content = await readFile9(cachePath, "utf-8");
     const parsed = JSON.parse(content);
     if (typeof parsed.latest !== "string" || typeof parsed.checkedAt !== "string") {
       return null;
@@ -5381,7 +5621,7 @@ async function readCache(cachePath) {
 async function writeCache(cachePath, latest) {
   await mkdir6(dirname6(cachePath), { recursive: true });
   const entry = { latest, checkedAt: (/* @__PURE__ */ new Date()).toISOString() };
-  await writeFile10(cachePath, JSON.stringify(entry, null, 2), "utf-8");
+  await writeFile11(cachePath, JSON.stringify(entry, null, 2), "utf-8");
 }
 async function getLatestVersion(feedUrl) {
   const normalizedBase = feedUrl.endsWith("/") ? feedUrl : feedUrl + "/";
@@ -5510,11 +5750,11 @@ async function runStatus(targetDir, packageVersion, options = {}) {
     `  ${"-".repeat(nameWidth)}  ${"-".repeat(filesWidth)}  ${"-".repeat(versionWidth)}`
   );
   for (const component of manifest.components) {
-    const label = component.name;
+    const label2 = component.name;
     const fileCount = component.files.length.toString();
     const displayVersion = component.installedVersion;
     console.log(
-      `  ${pad(label, nameWidth)}  ${rpad(fileCount, filesWidth)}  ${displayVersion}`
+      `  ${pad(label2, nameWidth)}  ${rpad(fileCount, filesWidth)}  ${displayVersion}`
     );
   }
   console.log("");
@@ -5752,7 +5992,7 @@ async function uninstallUserTier(options, storeRoot, manifest) {
 }
 
 // src/commands/doctor.ts
-import { access as access4, readdir as readdir9, readFile as readFile11, mkdir as mkdir7, copyFile as fsCopyFile } from "fs/promises";
+import { access as access4, readdir as readdir9, readFile as readFile12, mkdir as mkdir7, copyFile as fsCopyFile } from "fs/promises";
 import { join as join15, dirname as dirname9 } from "path";
 
 // src/config/incidents.ts
@@ -5821,7 +6061,7 @@ function evaluateIncidentGate(records) {
 }
 
 // src/modules/denylist-scan.ts
-import { readFile as readFile9, readdir as readdir7 } from "fs/promises";
+import { readFile as readFile10, readdir as readdir7 } from "fs/promises";
 import { join as join13, relative } from "path";
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -5839,7 +6079,7 @@ async function scanFile(absolutePath, displayPath, rules) {
   const findings = [];
   let content;
   try {
-    content = await readFile9(absolutePath, "utf8");
+    content = await readFile10(absolutePath, "utf8");
   } catch {
     return findings;
   }
@@ -6133,7 +6373,7 @@ function parseAdoRemote(url) {
 }
 
 // src/modules/placeholders.ts
-import { readdir as readdir8, readFile as readFile10 } from "fs/promises";
+import { readdir as readdir8, readFile as readFile11 } from "fs/promises";
 import { join as join14 } from "path";
 var PLACEHOLDER_STANDARD_FILE = "spell-authoring-standards.md";
 var RUNTIME_PLACEHOLDERS_START = "<!-- runtime-placeholders:start -->";
@@ -6229,7 +6469,7 @@ function parseRuntimePlaceholders(standardContent) {
 async function scanGovernancePlaceholders(governanceDir) {
   let standard;
   try {
-    standard = await readFile10(join14(governanceDir, PLACEHOLDER_STANDARD_FILE), "utf8");
+    standard = await readFile11(join14(governanceDir, PLACEHOLDER_STANDARD_FILE), "utf8");
   } catch (err) {
     if (err.code === "ENOENT") {
       return { status: "skipped", reason: `${PLACEHOLDER_STANDARD_FILE} is not installed` };
@@ -6248,7 +6488,7 @@ async function scanGovernancePlaceholders(governanceDir) {
   const templateDocs = [];
   const findings = [];
   for (const file of files) {
-    const content = await readFile10(join14(governanceDir, file), "utf8");
+    const content = await readFile11(join14(governanceDir, file), "utf8");
     const status = parseFrontmatterStatus(content);
     if (status === "template") templateDocs.push(file);
     if (status !== "active") continue;
@@ -6276,8 +6516,8 @@ async function checkNodeVersion() {
     message: `${raw} \u2014 Node.js 18 or later is required`
   };
 }
-async function checkVSCodeExtension(id, label, homeDir = resolveHomeDir()) {
-  const name = `VS Code extension: ${label}`;
+async function checkVSCodeExtension(id, label2, homeDir = resolveHomeDir()) {
+  const name = `VS Code extension: ${label2}`;
   const flavours = [
     { dir: join15(homeDir, ".vscode", "extensions"), bin: "code" },
     { dir: join15(homeDir, ".vscode-insiders", "extensions"), bin: "code-insiders" }
@@ -6314,7 +6554,7 @@ async function checkArcaneManifest(targetDir) {
   } catch {
     const selfHostedManifestPath = join15(targetDir, "src", "assets", ".arcane.json");
     try {
-      const raw = await readFile11(selfHostedManifestPath, "utf8");
+      const raw = await readFile12(selfHostedManifestPath, "utf8");
       const manifest = JSON.parse(raw);
       if (isRecord3(manifest) && manifest["selfHosted"] === true && manifest["tracking_mode"] === "internal") {
         return {
@@ -6333,7 +6573,7 @@ async function checkArcaneManifest(targetDir) {
     };
   }
   try {
-    const raw = await readFile11(manifestPath2, "utf8");
+    const raw = await readFile12(manifestPath2, "utf8");
     const manifest = JSON.parse(raw);
     if (!isRecord3(manifest) || typeof manifest["version"] !== "string" || !manifest["version"] || !Array.isArray(manifest["components"])) {
       return {
@@ -6619,15 +6859,45 @@ async function checkComponentRequires(targetDir) {
     name,
     passed: false,
     blocking: false,
-    message: missing.map(({ name: required, requiredBy }) => `${requiredBy.join(", ")} cites ${required}, which is not installed \u2014 \`spell add ${required}\``).join("; ")
+    message: missing.map(({ name: required, requiredBy }) => `${requiredBy.join(", ")} cites ${required}, which is not installed \u2014 ${getComponent(required).initOnly ? "" : "`spell update` installs it, or "}\`spell add ${required}\``).join("; ")
   };
 }
+async function checkNewlyAvailableComponents(targetDir) {
+  const name = "Newly available components";
+  let manifest;
+  try {
+    manifest = await readManifest(targetDir);
+  } catch {
+    return { name, passed: true, blocking: false, skipped: true, message: "skipped \u2014 no readable .arcane.json" };
+  }
+  if (manifest.scope === "user" || !Array.isArray(manifest.components)) {
+    return { name, passed: true, blocking: false, skipped: true, message: "skipped \u2014 no repository install to compare" };
+  }
+  const installed = manifest.components.flatMap(
+    (c) => (LEGACY_COMPONENT_MIGRATIONS[c.name] ?? [c.name]).map((n) => ({ ...c, name: n }))
+  );
+  const prerequisites = findMissingRequires(manifest.components, manifest.profile).map((m) => m.name);
+  const fresh = (await findNewlyAvailable(targetDir, manifest.profile, installed, effectiveSpellScope(manifest))).filter((c) => !prerequisites.includes(c.name));
+  if (fresh.length === 0) {
+    return { name, passed: true, blocking: false, message: "the profile has nothing this install lacks" };
+  }
+  const offerable = fresh.filter((c) => !getComponent(c.name).initOnly).map((c) => c.name);
+  const byHand = fresh.filter((c) => getComponent(c.name).initOnly).map((c) => c.name);
+  const parts = [];
+  if (offerable.length > 0) {
+    parts.push(`${offerable.join(", ")} \u2014 \`spell update --add-new\` installs ${offerable.length === 1 ? "it" : "them"}`);
+  }
+  if (byHand.length > 0) {
+    parts.push(`${byHand.join(", ")} \u2014 initOnly, so only ${byHand.map((n) => `\`spell add ${n}\``).join(", ")}`);
+  }
+  return { name, passed: false, blocking: false, message: `newly available for your profile, not installed: ${parts.join("; ")}` };
+}
 async function checkMcpConfig(targetDir) {
   const name = "MCP config (per-server timeout, I12)";
   const filePath = join15(targetDir, ".mcp.json");
   let raw;
   try {
-    raw = await readFile11(filePath, "utf8");
+    raw = await readFile12(filePath, "utf8");
   } catch {
     return { name, passed: true, blocking: false, message: "no .mcp.json \u2014 nothing to check" };
   }
@@ -6699,7 +6969,7 @@ async function checkDelegations(targetDir) {
   const filePath = join15(targetDir, ".arcane", "delegations.json");
   let raw;
   try {
-    raw = await readFile11(filePath, "utf8");
+    raw = await readFile12(filePath, "utf8");
   } catch {
     return { name, passed: true, blocking: false, message: "no delegations recorded" };
   }
@@ -6874,7 +7144,8 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
     checkUserTier(resolveHomeDir(), options.packageVersion),
     checkSpellScope(targetDir),
     checkGovernancePlaceholders(targetDir),
-    checkComponentRequires(targetDir)
+    checkComponentRequires(targetDir),
+    checkNewlyAvailableComponents(targetDir)
   ]);
   const sessionResults = await checkSessionContinuity(targetDir);
   results.push(...sessionResults);
@@ -6882,8 +7153,8 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
   for (const result of results) {
     const skipped = result.passed && result.skipped === true;
     const icon = skipped ? "\u2013" : result.passed ? "\u2713" : result.blocking === false ? "\u26A0" : "\u2717";
-    const label = skipped ? "skip" : result.passed ? "pass" : result.blocking === false ? "warn" : "FAIL";
-    console.log(`  ${icon} [${label}] ${result.name}`);
+    const label2 = skipped ? "skip" : result.passed ? "pass" : result.blocking === false ? "warn" : "FAIL";
+    console.log(`  ${icon} [${label2}] ${result.name}`);
     if (!result.passed || skipped) {
       console.log(`         ${result.message}`);
     }
@@ -6918,16 +7189,16 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
 }
 
 // src/commands/ward.ts
-import { readFile as readFile13 } from "fs/promises";
+import { readFile as readFile14 } from "fs/promises";
 
 // src/modules/ward.ts
-import { readdir as readdir10, readFile as readFile12 } from "fs/promises";
+import { readdir as readdir10, readFile as readFile13 } from "fs/promises";
 import { join as join16, relative as relative2 } from "path";
 async function scanFileAllRules(absolutePath, displayPath, rules) {
   const findings = [];
   let content;
   try {
-    content = await readFile12(absolutePath, "utf8");
+    content = await readFile13(absolutePath, "utf8");
   } catch {
     return findings;
   }
@@ -7022,7 +7293,7 @@ async function runWard(repoRoot, options = {}) {
     const findings2 = await scanFileAllRules(absolutePath, displayPath, allRules);
     if (findings2.length > 0) {
       try {
-        fileLines.set(displayPath, (await readFile12(absolutePath, "utf8")).split("\n"));
+        fileLines.set(displayPath, (await readFile13(absolutePath, "utf8")).split("\n"));
       } catch {
       }
     }
@@ -7050,7 +7321,7 @@ function parseTermsFileContent(raw) {
 }
 async function readTermsFile(filePath) {
   try {
-    return parseTermsFileContent(await readFile13(filePath, "utf8"));
+    return parseTermsFileContent(await readFile14(filePath, "utf8"));
   } catch (error) {
     console.warn(
       `\u26A0 arcane: could not read --terms-file "${filePath}": ${error.message}`
@@ -7265,11 +7536,11 @@ import { access as access5 } from "fs/promises";
 import { join as join19 } from "path";
 
 // src/modules/show-report/generate.ts
-import { mkdir as mkdir8, readdir as readdir11, readFile as readFile15, writeFile as writeFile11 } from "fs/promises";
+import { mkdir as mkdir8, readdir as readdir11, readFile as readFile16, writeFile as writeFile12 } from "fs/promises";
 import { basename as basename3, dirname as dirname10, isAbsolute, join as join18, relative as relative3, resolve as resolve4 } from "path";
 
 // src/modules/show-report/model.ts
-import { readFile as readFile14 } from "fs/promises";
+import { readFile as readFile15 } from "fs/promises";
 import { join as join17 } from "path";
 
 // src/modules/show-report/plan-parser.ts
@@ -7543,7 +7814,7 @@ async function getCast(cwd, fromRef, toRef, generatedOutputs = []) {
 // src/modules/show-report/model.ts
 async function readOptional(path4) {
   try {
-    return await readFile14(path4, "utf8");
+    return await readFile15(path4, "utf8");
   } catch {
     return null;
   }
@@ -7645,7 +7916,7 @@ async function buildShowReportModel(options) {
   const ledgerAbsPath = join17(options.rootDir, ledgerRelPath);
   const decisionsAbsPath = join17(options.rootDir, "DECISIONS.md");
   const [planContent, queueContent, ledgerContent, decisionsContent] = await Promise.all([
-    readFile14(planAbsPath, "utf8"),
+    readFile15(planAbsPath, "utf8"),
     readOptional(queueAbsPath),
     readOptional(ledgerAbsPath),
     readOptional(decisionsAbsPath)
@@ -7841,7 +8112,7 @@ function toPosix(path4) {
 async function programFromPlan(rootDir, slug, planRelPath) {
   let planContent;
   try {
-    planContent = await readFile15(join18(rootDir, planRelPath), "utf8");
+    planContent = await readFile16(join18(rootDir, planRelPath), "utf8");
   } catch {
     return { skipped: { slug, reason: `no PLAN.md at ${planRelPath}` } };
   }
@@ -7886,14 +8157,14 @@ function normalizeLineEndings2(content) {
 }
 async function readOptionalFile(path4) {
   try {
-    return await readFile15(path4, "utf8");
+    return await readFile16(path4, "utf8");
   } catch (error) {
     if (error.code === "ENOENT") return null;
     throw error;
   }
 }
 async function generateReport(rootDir, program2, templateHtml, theme = "auto") {
-  const planContent = await readFile15(join18(rootDir, program2.planRelPath), "utf8");
+  const planContent = await readFile16(join18(rootDir, program2.planRelPath), "utf8");
   const frontmatter = parseFrontmatter(planContent);
   const model = await buildShowReportModel({
     rootDir,
@@ -7913,7 +8184,7 @@ async function generateReport(rootDir, program2, templateHtml, theme = "auto") {
   };
 }
 async function runReportGeneration(options) {
-  const templateHtml = await readFile15(options.templatePath, "utf8");
+  const templateHtml = await readFile16(options.templatePath, "utf8");
   const theme = options.theme ?? "auto";
   const drifted = [];
   const repaired = [];
@@ -7936,7 +8207,7 @@ async function runReportGeneration(options) {
         drifted.push(`${relPath} does not match a regeneration from its sources.`);
         if (options.mode === "write") {
           await mkdir8(outAbs, { recursive: true });
-          await writeFile11(join18(options.rootDir, relPath), expected, "utf8");
+          await writeFile12(join18(options.rootDir, relPath), expected, "utf8");
           repaired.push(relPath);
         }
       }
@@ -8084,10 +8355,10 @@ withManifestFlags(
     );
   }
 );
-program.command("add <component>").description("Add a component to an existing Arcane installation").option("--force", "Overwrite existing files without error").option("--dry-run", "Preview what would be added without making changes").action(
-  async (component, opts) => {
+program.command("add <components...>").description("Add one or more components to an existing Arcane installation, in order; stops at the first failure").option("--force", "Overwrite existing files without error").option("--dry-run", "Preview what would be added without making changes").action(
+  async (components, opts) => {
     await runAdd(
-      component,
+      components,
       { force: opts.force, dryRun: opts.dryRun },
       process.cwd(),
       ASSETS_DIR,
@@ -8100,6 +8371,9 @@ withManifestFlags(
     "--prune",
     "Also delete orphaned managed files (tracked before this update, no longer part of any current component). Hash-checked: an edited file is reported, never silently deleted"
   ).option("--user", USER_FLAG_DESCRIPTION).option(
+    "--add-new",
+    "Also install the components your profile gained since your install (never an initOnly component, never over an existing file). Without it a terminal asks and a script installs nothing"
+  ).option(
     "--default-scope <scope>",
     "With --user: remember repo | user as the answer `spell init` pre-selects for NEW repositories on this machine. Never rewrites an existing repository, and the question is still asked"
   )
@@ -8123,6 +8397,7 @@ withManifestFlags(
       dryRun: opts.dryRun,
       prune: opts.prune,
       user: opts.user,
+      addNew: opts.addNew,
       manifestFlags: manifestFlagsFrom(opts),
       ...opts.defaultScope === void 0 ? {} : { defaultScope: opts.defaultScope }
     },