@mmerterden/multi-agent-pipeline 20.8.1 → 20.8.2

package/install/codex.mjs

@@ -241,7 +241,7 @@ function installRouterSkill(pipelineSrc, skillsDir) {
 
   // ensureRealDir only swaps a --link-era symlink for a real dir; ensureDir
   // creates a missing one. Every owned tree below needs both.
-  ensureRealDir(skillsDir);
+  skillsDir = ensureRealDir(skillsDir, { userOwned: true });
   ensureDir(skillsDir);
   pruneLegacyCommandSkills(skillsDir);
 
@@ -297,7 +297,7 @@ function installRefs(pipelineSrc, dest) {
   const refsSrc = join(pipelineSrc, "multi-agent-refs");
   const commandsSrc = join(pipelineSrc, "commands", "multi-agent");
 
-  ensureRealDir(dest);
+  if (ensureRealDir(dest) === null) return;
   ensureDir(dest);
   wipeDir(dest);
 
@@ -373,7 +373,7 @@ function installPersonas(pipelineSrc, dest) {
  * orchestrator - one spec, two entry points.
  */
 function installPrompt(promptsDir) {
-  ensureRealDir(promptsDir);
+  promptsDir = ensureRealDir(promptsDir, { userOwned: true });
   ensureDir(promptsDir);
   const body = [
     "Run the multi-agent development pipeline.",
@@ -409,7 +409,7 @@ function installSkillRefs(pipelineSrc, dest, home, platformFlag) {
   const externalSrc = join(pipelineSrc, "skills", "shared", "external");
   const coreSrc = join(pipelineSrc, "skills", "shared", "core");
 
-  ensureRealDir(dest);
+  if (ensureRealDir(dest) === null) return;
   ensureDir(dest);
   wipeDir(dest);
 
@@ -482,7 +482,7 @@ function installScripts(pipelineSrc, dest, useSymlinks) {
   const src = join(pipelineSrc, "scripts");
   if (!existsSync(src)) return;
   if (!useSymlinks) {
-    ensureRealDir(dest);
+    if (ensureRealDir(dest) === null) return;
     ensureDir(dest);
   }
   wipeDir(dest);
@@ -512,7 +512,7 @@ function installTemplates(pipelineSrc, dest, useSymlinks) {
   const src = join(dirname(pipelineSrc), "install", "templates");
   if (!existsSync(src)) return;
   if (!useSymlinks) {
-    ensureRealDir(dest);
+    if (ensureRealDir(dest) === null) return;
     ensureDir(dest);
   }
   wipeDir(dest);
@@ -524,7 +524,7 @@ function installTree(name, pipelineSrc, dest, useSymlinks) {
   const src = join(pipelineSrc, name);
   if (!existsSync(src)) return;
   if (!useSymlinks) {
-    ensureRealDir(dest);
+    if (ensureRealDir(dest) === null) return;
     ensureDir(dest);
   }
   wipeDir(dest);

package/install/copilot.mjs

@@ -225,7 +225,7 @@ function installScripts(pipelineSrc, dest, useSymlinks) {
   if (!existsSync(scriptsSrc)) return;
   // Replace a --link-era symlink with a real dir before wiping/copying so the
   // install can never land inside the developer's repo checkout.
-  if (!useSymlinks) ensureRealDir(dest);
+  if (!useSymlinks && ensureRealDir(dest) === null) return;
   wipeDir(dest);
   copyDir(scriptsSrc, dest, { exclude: DEV_ONLY_SCRIPTS, useSymlinks });
   // Count files actually excluded by walking the tree: DEV_ONLY_SCRIPTS mixes
@@ -243,11 +243,12 @@ function installAgents(pipelineSrc, dest, useSymlinks) {
   // ~/.copilot/agents also holds user-authored agent files. Never wipe the
   // whole dir; remove only the pipeline-shipped agent files (name set derived
   // from the source tree so it cannot go stale), then copy the fresh set in.
+  let target = dest;
   if (!useSymlinks) {
-    ensureRealDir(dest);
-    removePipelineAgentFiles(dest, agentsSrc);
+    target = ensureRealDir(dest, { userOwned: true });
+    removePipelineAgentFiles(target, agentsSrc);
   }
-  copyDir(agentsSrc, dest, { useSymlinks });
+  copyDir(agentsSrc, target, { useSymlinks });
   console.log(`    -> ${countFiles(agentsSrc)} files copied to ${dest}`);
 }
 
@@ -255,7 +256,7 @@ function installSchemas(pipelineSrc, dest, useSymlinks) {
   console.log("  [Copilot CLI] Installing JSON schemas...");
   const schemasSrc = join(pipelineSrc, "schemas");
   if (!existsSync(schemasSrc)) return;
-  if (!useSymlinks) ensureRealDir(dest);
+  if (!useSymlinks && ensureRealDir(dest) === null) return;
   wipeDir(dest);
   copyDir(schemasSrc, dest, { useSymlinks });
   console.log(`    -> ${countFiles(schemasSrc)} files copied to ${dest}`);
@@ -269,7 +270,7 @@ function installTemplates(pipelineSrc, dest, useSymlinks) {
   console.log("  [Copilot CLI] Installing templates...");
   const templatesSrc = join(dirname(pipelineSrc), "install", "templates");
   if (!existsSync(templatesSrc)) return;
-  if (!useSymlinks) ensureRealDir(dest);
+  if (!useSymlinks && ensureRealDir(dest) === null) return;
   wipeDir(dest);
   copyDir(templatesSrc, dest, { useSymlinks });
   console.log(`    -> ${countFiles(templatesSrc)} files copied to ${dest}`);
@@ -279,7 +280,7 @@ function installLib(pipelineSrc, dest, useSymlinks) {
   console.log("  [Copilot CLI] Installing shell libraries...");
   const libSrc = join(pipelineSrc, "lib");
   if (!existsSync(libSrc)) return;
-  if (!useSymlinks) ensureRealDir(dest);
+  if (!useSymlinks && ensureRealDir(dest) === null) return;
   wipeDir(dest);
   copyDir(libSrc, dest, { useSymlinks });
   console.log(`    -> ${countFiles(libSrc)} files copied to ${dest}`);
@@ -299,7 +300,7 @@ function installRules(pipelineSrc, dest, useSymlinks) {
   console.log("  [Copilot CLI] Installing convention rules...");
   const rulesSrc = join(pipelineSrc, "rules");
   if (!existsSync(rulesSrc)) return;
-  if (!useSymlinks) ensureRealDir(dest);
+  if (!useSymlinks && ensureRealDir(dest) === null) return;
   wipeDir(dest);
   if (useSymlinks) {
     copyDir(rulesSrc, dest, { useSymlinks });
@@ -318,15 +319,16 @@ function installRules(pipelineSrc, dest, useSymlinks) {
 }
 
 function installSkills(opts) {
-  const { home, pipelineSrc, dest, indexOnly, useSymlinks, platformFlag } = opts;
+  const { home, pipelineSrc, indexOnly, useSymlinks, platformFlag } = opts;
   console.log("  [Copilot CLI] Installing skills...");
 
   // The skills root is always a real directory, in --link mode too: the manifest,
   // index and README written below are generated files, and an older --link
   // install pointed the whole root at pipeline/skills/shared/core, so every one
   // of those writes (and the external / plugin symlinks) landed in the checkout.
-  // Link mode now links each authored skill dir individually instead.
-  ensureRealDir(dest);
+  // Link mode now links each authored skill dir individually instead. A
+  // symlink elsewhere (the user's own skills repo) is written through.
+  const dest = ensureRealDir(opts.dest, { pipelineSrc, userOwned: true });
 
   if (indexOnly) {
     try {

package/install/index.mjs

@@ -12,7 +12,7 @@ import { dirname } from "path";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "url";
 
-import { readFileSync } from "fs";
+import { existsSync, readFileSync } from "fs";
 import { join } from "path";
 
 import { installClaude } from "./claude.mjs";
@@ -59,6 +59,7 @@ export async function runInstall(argv) {
   const KNOWN_FLAGS = [
     ...TOOL_FLAGS,
     "--all",
+    "--installed",
     "--link",
     "--index-only",
     "--dry-run",
@@ -82,13 +83,26 @@ export async function runInstall(argv) {
   const dryRun = flags.includes("--dry-run");
   setDryRun(dryRun);
 
-  const isExplicitlyTargeted = flags.some((f) => TOOL_FLAGS.includes(f)) || flags.includes("--all");
+  const installed = flags.includes("--installed") ? installedTargets(HOME) : null;
+  const isExplicitlyTargeted =
+    flags.some((f) => TOOL_FLAGS.includes(f)) ||
+    flags.includes("--all") ||
+    Boolean(installed && (installed.claude || installed.copilot || installed.codex));
+  if (installed && !isExplicitlyTargeted) {
+    console.log("  --installed: no target carries a version stamp yet; installing Claude Code.");
+  }
 
-  const forClaude = flags.includes("--claude") || flags.includes("--all") || !isExplicitlyTargeted;
+  const forClaude =
+    flags.includes("--claude") ||
+    flags.includes("--all") ||
+    Boolean(installed?.claude) ||
+    !isExplicitlyTargeted;
 
-  const forCopilot = flags.includes("--copilot") || flags.includes("--all");
+  const forCopilot =
+    flags.includes("--copilot") || flags.includes("--all") || Boolean(installed?.copilot);
 
-  const forCodex = flags.includes("--codex") || flags.includes("--all");
+  const forCodex =
+    flags.includes("--codex") || flags.includes("--all") || Boolean(installed?.codex);
 
   const useSymlinks = flags.includes("--link");
   const indexOnly = flags.includes("--index-only");
@@ -111,9 +125,14 @@ export async function runInstall(argv) {
   if (dryRun) console.log("  (dry-run: no files will be written)");
   console.log("");
 
-  if (forClaude) installClaude(installerCtx);
-  if (forCopilot) installCopilot(installerCtx);
-  if (forCodex) installCodex(installerCtx);
+  try {
+    if (forClaude) installClaude(installerCtx);
+    if (forCopilot) installCopilot(installerCtx);
+    if (forCodex) installCodex(installerCtx);
+  } catch (err) {
+    reportInstallFailure(err);
+    process.exit(1);
+  }
 
   // Version marker: update-check.sh falls back to this for npx-only installs
   // that have no pipeline repo clone to read a version from.
@@ -136,11 +155,53 @@ export async function runInstall(argv) {
 }
 
 /**
- * Stamp the installed package version into each target so the advisory
- * update check works without a repo clone. Failure is non-fatal.
+ * One line for a failed install, and a non-zero exit from the caller. The
+ * stack trace is for debugging the installer itself, so it prints only with
+ * MULTI_AGENT_INSTALL_DEBUG=1.
  *
- * @param {{home: string, forClaude: boolean, forCopilot: boolean, forCodex?: boolean}} opts
+ * @param {unknown} err
+ */
+function reportInstallFailure(err) {
+  const reason =
+    err?.code === "INSTALL_INCOMPLETE"
+      ? err.message
+      : `${err?.code ? `${err.code}: ` : ""}${String(err?.message || err).split("\n")[0]}`;
+  console.error("");
+  console.error(`  install incomplete: ${reason}.`);
+  console.error("  Fix the cause and re-run the same install command.");
+  if (process.env.MULTI_AGENT_INSTALL_DEBUG === "1" && err?.stack) {
+    console.error(err.stack);
+    if (err.cause?.stack) console.error(err.cause.stack);
+  } else {
+    console.error("  (MULTI_AGENT_INSTALL_DEBUG=1 prints the stack trace.)");
+  }
+}
+
+/** Version stamp each target's installer writes. */
+export function versionStampPaths(home) {
+  return {
+    claude: join(home, ".claude", ".pipeline-version"),
+    copilot: join(home, ".copilot", ".pipeline-version"),
+    codex: join(home, ".codex", ".pipeline-version"),
+  };
+}
+
+/**
+ * The targets an earlier install laid down, told by their version stamps.
+ * `--installed` uses it so an update refreshes what is there and nothing else.
+ *
+ * @param {string} home
+ * @returns {{claude: boolean, copilot: boolean, codex: boolean}}
  */
+export function installedTargets(home) {
+  const stamps = versionStampPaths(home);
+  return {
+    claude: existsSync(stamps.claude),
+    copilot: existsSync(stamps.copilot),
+    codex: existsSync(stamps.codex),
+  };
+}
+
 /**
  * Print the unattended permission profile, then apply it. Printing first is the
  * contract: an installer that widens a permission set has to say what it is
@@ -196,6 +257,12 @@ function applyUnattended({ home, forClaude, dryRun = false }) {
   }
 }
 
+/**
+ * Stamp the installed package version into each target so the advisory
+ * update check works without a repo clone. Failure is non-fatal.
+ *
+ * @param {{home: string, forClaude: boolean, forCopilot: boolean, forCodex?: boolean}} opts
+ */
 export function writeVersionMarkers({ home, forClaude, forCopilot, forCodex }) {
   let version;
   try {
@@ -204,10 +271,11 @@ export function writeVersionMarkers({ home, forClaude, forCopilot, forCodex }) {
     return;
   }
   if (!version) return;
+  const stamps = versionStampPaths(home);
   const targets = [];
-  if (forClaude) targets.push(join(home, ".claude", ".pipeline-version"));
-  if (forCopilot) targets.push(join(home, ".copilot", ".pipeline-version"));
-  if (forCodex) targets.push(join(home, ".codex", ".pipeline-version"));
+  if (forClaude) targets.push(stamps.claude);
+  if (forCopilot) targets.push(stamps.copilot);
+  if (forCodex) targets.push(stamps.codex);
   for (const target of targets) {
     try {
       writeFile(target, `${version}\n`);
@@ -217,12 +285,8 @@ export function writeVersionMarkers({ home, forClaude, forCopilot, forCodex }) {
   }
 }
 
-/**
- * @param {string[]} flags
- * @returns {"ios"|"android"|"all"}
- */
 // Presence check only - never a hard requirement. The pipeline's own engine is
-// node; jq is a convenience several shell helpers reached for.
+// node; jq is a convenience several shell helpers reach for.
 function hasJq() {
   try {
     execFileSync("jq", ["--version"], { stdio: "ignore", timeout: 3000 });
@@ -232,6 +296,10 @@ function hasJq() {
   }
 }
 
+/**
+ * @param {string[]} flags
+ * @returns {"ios"|"android"|"all"}
+ */
 function parsePlatformFlag(flags) {
   const raw = flags.find((f) => f.startsWith("--platform="));
   if (!raw) return "all";
@@ -272,9 +340,8 @@ function printSummary(opts) {
     console.log("");
   }
 
-  // All three register automatically now. Claude Code was the last to gain it, and
-  // this summary kept telling users to do it by hand long enough that the
-  // hand-registered entry became the only reason it worked on any given machine.
+  // Each installer registers the server itself; the lines below name the
+  // command it ran, for a host whose CLI was not on PATH.
   console.log("  For UI testing, the multi-agent-toolkit MCP server is registered automatically:");
   if (forClaude) {
     console.log(
@@ -291,11 +358,9 @@ function printSummary(opts) {
     "    Skipped only when the host CLI is not on PATH - the command to run is printed above.",
   );
   console.log("");
-  // jq is not a declared engine and macOS did not always ship it, yet thirteen
-  // runtime paths guard on it and skip in silence when it is missing. Silence is
-  // the problem: a cost summary that never renders and a tracker that never
-  // updates look like bugs, not like an absent tool. Say it once, here, where
-  // somebody can act on it.
+  // jq is not a declared engine and not every macOS ships it. Several runtime
+  // paths skip in silence without it, which reads as a bug rather than an
+  // absent tool, so the install says it once, where somebody can act on it.
   if (!hasJq()) {
     console.log("  Note: jq was not found on PATH.");
     console.log("    Everything installs and the pipeline runs, but a few shell");

package/install/templates/claude-hooks.json

@@ -7,13 +7,13 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash $HOME/.claude/scripts/pre-commit-check.sh",
+            "command": "bash \"$HOME/.claude/scripts/pre-commit-check.sh\"",
             "timeout": 15,
             "statusMessage": "Scanning staged changes for secrets..."
           },
           {
             "type": "command",
-            "command": "bash $HOME/.claude/scripts/agent-guard.sh",
+            "command": "bash \"$HOME/.claude/scripts/agent-guard.sh\"",
             "timeout": 10,
             "statusMessage": "Checking commit/push safety (attribution + force-push)..."
           }
@@ -24,7 +24,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash $HOME/.claude/scripts/agent-guard.sh",
+            "command": "bash \"$HOME/.claude/scripts/agent-guard.sh\"",
             "timeout": 10,
             "statusMessage": "Checking the edit target..."
           }
@@ -35,7 +35,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash $HOME/.claude/scripts/agent-guard.sh",
+            "command": "bash \"$HOME/.claude/scripts/agent-guard.sh\"",
             "timeout": 10,
             "statusMessage": "Checking the fetch host..."
           }
@@ -46,7 +46,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash $HOME/.claude/scripts/check-read-size.sh",
+            "command": "bash \"$HOME/.claude/scripts/check-read-size.sh\"",
             "timeout": 10,
             "statusMessage": "Checking read size..."
           }
@@ -58,7 +58,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash $HOME/.claude/scripts/capture-flush.sh --quiet",
+            "command": "bash \"$HOME/.claude/scripts/capture-flush.sh\" --quiet",
             "timeout": 20,
             "statusMessage": "Persisting what this run learned before compaction..."
           }
@@ -70,13 +70,13 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash $HOME/.claude/scripts/capture-flush.sh --if-stale --quiet",
+            "command": "bash \"$HOME/.claude/scripts/capture-flush.sh\" --if-stale --quiet",
             "timeout": 20,
             "statusMessage": "Persisting what this run learned..."
           },
           {
             "type": "command",
-            "command": "bash $HOME/.claude/scripts/note-session.sh",
+            "command": "bash \"$HOME/.claude/scripts/note-session.sh\"",
             "timeout": 20,
             "statusMessage": "Noting this session..."
           }
@@ -89,7 +89,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash $HOME/.claude/scripts/capture-resume.sh",
+            "command": "bash \"$HOME/.claude/scripts/capture-resume.sh\"",
             "timeout": 10,
             "statusMessage": "Checking for unfinished runs..."
           }