arcane-cli 1.9.2 → 1.10.0

package/README.md

@@ -218,8 +218,20 @@ Install everything, or just the slice you want:
 ```bash
 spell init --profile full
 spell add agent-policies   # or install any component à la carte
+spell add spells-build compliance-standards   # or several, in order
 ```
 
+`spell add` takes one or more names. It checks each component's files before writing any of them: if one already exists, it prints one line naming the file and `--force`, exits 1, and writes nothing from that component. With several names it stops at the first failure and says which were added and which were not attempted; a name that is already installed is skipped. A component that keeps your own file (`.mcp.json`) leaves an existing one alone and creates a missing one. `--dry-run` lists each file as identical, differing or missing, or as one that would be kept or refused, and writes nothing.
+
+### What `spell update` installs
+
+Beyond refreshing what you have, `spell update` installs two things, and reports each by name ([ARC-052](DECISIONS.md#arc-052--spell-update-installs-the-requires-prerequisites-of-installed-components)):
+
+- **Missing prerequisites.** A component that cites another one in `requires` (`spells-build` cites the standards documents) gets it installed when it is missing. It is tracked with hashes like any other component. If a file at its destination already exists, or it is an `initOnly` component, `update` leaves it alone and keeps it in the list with the reason.
+- **Newly available components, only when you ask.** In a terminal, `spell update` offers them as a checklist with nothing ticked. Without one, pass `spell update --add-new`. With neither, nothing is installed and the list prints as before. `--add-new` is for repositories, not the user tier.
+
+`spell update` never installs an `initOnly` component (`line-ending-baseline`, `docs-baseline`): adding one changes how Git treats files you already have, so it stays a `spell add` you run yourself. `--dry-run` names exactly the components a real run would install. `spell doctor` installs nothing; it names the command.
+
 ### Setup questions, answered by flags
 
 `spell init` asks a few questions about the repository and records the answers in `.arcane.json`; `spell update` asks any that an older install predates. Each question has a flag, on both commands, so a script or an agent harness can answer without a terminal:

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,77 @@ async function runInitUser(options, storeRoot, assetsDir, packageVersion) {
   console.log();
 }
 
-// src/commands/add.ts
+// src/modules/component-install.ts
+import { stat } from "fs/promises";
 import { join as join8 } from "path";
-async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
-  let manifest;
-  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;
+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: "differs" };
+    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)));
     }
-    throw err;
   }
+  const present = files.filter((f) => f.state !== "missing");
+  const missing = files.filter((f) => f.state === "missing");
+  if (opts.force) return { component, files, toCopy: files, kept: [], conflicts: [] };
+  return component.skipExisting ? { component, files, toCopy: missing, kept: present, conflicts: [] } : { component, files, toCopy: missing, kept: [], conflicts: present };
+}
+async function executeInstallPlan(plan, targetDir) {
+  const files = [];
+  const fileHashes = {};
+  for (const { file, src } of plan.toCopy) {
+    fileHashes[file] = await copyFile(src, targetDir, file, { force: true });
+    files.push(file);
+  }
+  return { files, fileHashes };
+}
+
+// src/commands/add.ts
+function describeExisting(f) {
+  return f.state === "identical" ? "identical to the packaged file" : "differs from the packaged file";
+}
+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 (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 {
+      console.log(`  [dry-run] Would refuse: ${f.file} (exists, ${describeExisting(f)}) \u2014 needs --force`);
+    }
+  }
+  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,53 +4494,69 @@ async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
     console.log(
       `Component "${name}" is already installed. Use "spell update" to update it.`
     );
-    return;
-  }
-  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++;
-  }
-  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;
-    }
+    return "skipped";
   }
+  const plan = await planComponentInstall(component, targetDir, assetsDir, { force: options.force });
   if (options.dryRun) {
-    console.log(
-      `
-[dry-run] Would add component "${name}" \u2014 ${fileCount} files`
+    printDryRun2(name, plan, options);
+    return plan.conflicts.length > 0 ? "failed" : "added";
+  }
+  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
@@ -4693,27 +4765,105 @@ 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: `${plan.conflicts[0].file} already exists${plan.conflicts.length > 1 ? ` (and ${plan.conflicts.length - 1} more)` : ""}, and update does not overwrite` });
+      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: `${plan.conflicts[0].file} already exists, and update does not overwrite` });
+      continue;
+    }
+    items.push({ plan, kind: "new", requiredBy: [] });
+  }
+  return { items, leftAlone };
+}
+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 +5097,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 +5172,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({
@@ -5214,6 +5401,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) {
@@ -5510,11 +5698,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("");
@@ -6276,8 +6464,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" }
@@ -6619,9 +6807,39 @@ 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");
@@ -6874,7 +7092,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 +7101,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}`);
     }
@@ -8084,10 +8303,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 +8319,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 +8345,7 @@ withManifestFlags(
       dryRun: opts.dryRun,
       prune: opts.prune,
       user: opts.user,
+      addNew: opts.addNew,
       manifestFlags: manifestFlagsFrom(opts),
       ...opts.defaultScope === void 0 ? {} : { defaultScope: opts.defaultScope }
     },