@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/lib/cli/global-setup-extras.mjs

@@ -0,0 +1,454 @@
+/**
+ * lib/cli/global-setup-extras.mjs — the front-door half of `maestro global-setup`.
+ *
+ * `bin/maestro.mjs#globalSetup` wires the collective hooks, the collective
+ * CLAUDE.md block and the machine pointer. This module adds what §3.7 of the
+ * 2026-09-08 design asks for, so ANY Claude Code session on the seat machine
+ * knows who the agent is and has its tools:
+ *
+ *   1. ~/.claude/CLAUDE.md          the delimited `maestro:identity` block
+ *   2. ~/.claude.json               user-scope MCP server `cohort` → cohort-mcp
+ *                                   (via `claude mcp add-json --scope user` when
+ *                                   the CLI is available, else a JSON merge)
+ *   3. ~/.claude/settings.json      crossSessionInbound, permissions.allow,
+ *                                   the mcp__cohort__messaging_send PreToolUse
+ *                                   persona/audit hook
+ *   4. ~/.claude/skills/maestro-<name>/  every shipped skill (symlink for a global
+ *                                   install, copy otherwise)
+ *   5. ~/.claude/skills/<pack skill>/    the vendored design skill packs (WP-M7),
+ *                                   copied under their own frontmatter names;
+ *                                   a directory that is not ours is never touched,
+ *                                   local edits inside one that IS ours are
+ *                                   copied aside first, and the whole step is
+ *                                   opt-out via MAESTRO_SKIP_VENDOR_SKILLS=1
+ *
+ * Additive, idempotent, backed up: JSON files are copied to
+ * `<file>.backup.<stamp>` before the first write of a run, and a re-run that
+ * changes nothing writes nothing (and backs up nothing). Every step is
+ * fail-open and reported; the merges themselves are the pure functions in
+ * lib/collective/global-config.mjs. All I/O is injectable for tests.
+ *
+ * Two rules for the two files Claude Code itself owns (~/.claude.json and
+ * ~/.claude/settings.json), because a wrong write there costs the seat its
+ * OAuth account, onboarding state and per-project trust:
+ *   - A file that is PRESENT but UNPARSEABLE (mid-rewrite by a running claude,
+ *     a BOM, trailing garbage) is never "merged onto {}": the step warns and
+ *     skips; nothing is written.
+ *   - A write is a read → merge → verify-unchanged → rename cycle
+ *     ({@link mergeJsonFileAtomic}) that keeps the file's mode (0600 stays
+ *     0600) and re-merges when another process rewrote the file in between —
+ *     the closest thing to a lock a file Claude Code rewrites at will allows.
+ *
+ * @module lib/cli/global-setup-extras
+ */
+
+"use strict";
+
+import { existsSync, readFileSync, writeFileSync, copyFileSync, mkdirSync, statSync, openSync, writeSync, fsyncSync, closeSync, renameSync, unlinkSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  buildIdentityClaudeMd, upsertDelimitedBlock, IDENTITY_BEGIN, IDENTITY_END,
+  cohortMcpEntry, mergeMcpServers, mergeSessionSettings,
+} from "../collective/global-config.mjs";
+import { installSkills, isGlobalInstall } from "../collective/global-skills.mjs";
+import { buildContext } from "../render.mjs";
+
+/** The SDK package root (two levels up from lib/cli/). */
+export const SDK_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+function stamp(now) {
+  return new Date(Number.isFinite(now) ? now : Date.now()).toISOString().replace(/[:.]/g, "-");
+}
+
+/**
+ * Read a JSON file. `{present:false}` when absent; `{present:true, value}` when
+ * parsed; `{present:true, value:null, unparseable:true}` when the bytes are
+ * there but do not parse — the caller must NOT write over that.
+ */
+function readJsonFile(p) {
+  if (!existsSync(p)) return { present: false, value: null };
+  try {
+    return { present: true, value: JSON.parse(readFileSync(p, "utf8")) };
+  } catch {
+    return { present: true, value: null, unparseable: true };
+  }
+}
+
+/**
+ * First `<dir>/<name>` on a PATH string that exists as a file. Pure over the
+ * injected `existsSync`. Null when nothing matches or the PATH is empty.
+ * @param {string} name @param {string} pathEnv @param {{existsSync?:Function}} [deps]
+ */
+export function findOnPath(name, pathEnv, deps = {}) {
+  const ex = deps.existsSync || existsSync;
+  const n = String(name || "");
+  if (!n) return null;
+  for (const dir of String(pathEnv || "").split(":")) {
+    if (!dir) continue;
+    const candidate = join(dir, n);
+    try { if (ex(candidate)) return candidate; } catch { /* an unreadable PATH entry is not a hit */ }
+  }
+  return null;
+}
+
+/**
+ * Turn the resolver's answer into a usable binary path or null. lib/claude-bin
+ * returns the bare name "claude" when none of its fixed locations exist (an
+ * nvm / npm-prefix install); that is a PATH lookup, not a miss.
+ * @param {string} resolved @param {{pathEnv?:string, existsSync?:Function}} [o]
+ */
+export function pickClaudeBin(resolved, o = {}) {
+  const ex = o.existsSync || existsSync;
+  const r = String(resolved || "");
+  if (!r) return null;
+  if (r === "claude" || !r.includes("/")) return findOnPath(r, o.pathEnv === undefined ? process.env.PATH : o.pathEnv, { existsSync: ex });
+  try { return ex(r) ? r : null; } catch { return null; }
+}
+
+/**
+ * Read → merge → publish, refusing to clobber. `mergeFn(parsedOrNull)` returns
+ * `{config, changed}` (the shape of the pure mergers). The file's mode is kept
+ * (a new file gets `o.mode`, default 0o600). Before the rename the file is
+ * re-read and compared with what was merged from: a difference means another
+ * process wrote in between, so the merge is redone (up to `o.attempts`, 3).
+ *
+ * @returns {{ok:boolean, changed:boolean, attempts:number, reason?:string}}
+ */
+export function mergeJsonFileAtomic(path, mergeFn, o = {}) {
+  const maxAttempts = Number.isFinite(o.attempts) && o.attempts > 0 ? o.attempts : 3;
+  let attempts = 0;
+  while (attempts < maxAttempts) {
+    attempts += 1;
+    let raw = null;
+    let mode = Number.isFinite(o.mode) ? o.mode : 0o600;
+    if (existsSync(path)) {
+      try {
+        raw = readFileSync(path, "utf8");
+        mode = statSync(path).mode & 0o777;
+      } catch (err) {
+        return { ok: false, changed: false, attempts, reason: `unreadable: ${err && err.message}` };
+      }
+    }
+    let parsed = null;
+    if (raw !== null) {
+      try { parsed = JSON.parse(raw); } catch { return { ok: false, changed: false, attempts, reason: "unparseable" }; }
+    }
+    const merged = mergeFn(parsed);
+    if (!merged || !merged.changed) return { ok: true, changed: false, attempts };
+    const out = JSON.stringify(merged.config, null, 2) + "\n";
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+    const fd = openSync(tmp, "w", mode);
+    try { writeSync(fd, out); fsyncSync(fd); } finally { closeSync(fd); }
+    // Verify nobody wrote in between; a change means our merge is stale.
+    let now = null;
+    try { now = existsSync(path) ? readFileSync(path, "utf8") : null; } catch { now = undefined; }
+    if (now !== raw) {
+      try { unlinkSync(tmp); } catch { /* orphan tmp is harmless */ }
+      continue;
+    }
+    try {
+      renameSync(tmp, path);
+    } catch (err) {
+      try { unlinkSync(tmp); } catch { /* ignore */ }
+      return { ok: false, changed: false, attempts, reason: `rename failed: ${err && err.message}` };
+    }
+    return { ok: true, changed: true, attempts };
+  }
+  return { ok: false, changed: false, attempts, reason: "concurrent writer: gave up after retries" };
+}
+
+/** `npm root -g`, "" when npm is unavailable (→ copy mode). */
+function defaultGlobalRoot() {
+  try {
+    return execFileSync("npm", ["root", "-g"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 15_000 }).trim();
+  } catch {
+    return ""; // no npm on PATH: skills are copied rather than linked
+  }
+}
+
+/** The claude CLI, or null when it is not installed (→ JSON merge). */
+async function defaultClaudeBin(pathEnv) {
+  try {
+    const mod = await import("../claude-bin.mjs");
+    return pickClaudeBin(mod.resolveClaudeBin(), { pathEnv });
+  } catch {
+    return null; // resolver unavailable: the JSON merge path is the fallback
+  }
+}
+
+function defaultExec(bin, args) {
+  try {
+    const stdout = execFileSync(bin, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 30_000 });
+    return { status: 0, stdout };
+  } catch (err) {
+    return { status: typeof err.status === "number" ? err.status : 1, stderr: String((err && err.stderr) || (err && err.message) || "") };
+  }
+}
+
+/** Marker every persona-gated pre-send-audit.sh carries (section a2). */
+export const PERSONA_GATE_MARKER = "PERSONA_PATTERNS";
+
+/** Does `<agentRoot>/scripts/hooks/pre-send-audit.sh` exist and carry the persona gate? */
+export function checkPersonaHookScript(agentRoot) {
+  const path = join(String(agentRoot || ""), "scripts", "hooks", "pre-send-audit.sh");
+  try {
+    if (!existsSync(path)) return { path, present: false, personaGate: false };
+    return { path, present: true, personaGate: readFileSync(path, "utf8").includes(PERSONA_GATE_MARKER) };
+  } catch {
+    return { path, present: false, personaGate: false };
+  }
+}
+
+/**
+ * Apply the four steps. Returns a summary; never throws.
+ *
+ * @param {object} o
+ * @param {string} o.agentRoot          the agent repo being wired
+ * @param {string} [o.claudeDir]        ~/.claude
+ * @param {string} [o.claudeJsonPath]   ~/.claude.json
+ * @param {string} [o.sdkRoot]          where plugins/maestro-skills lives (default: this package)
+ * @param {boolean} [o.dryRun]
+ * @param {string|null} [o.claudeBin]   claude CLI path; null = not available
+ * @param {(bin:string,args:string[])=>{status:number}} [o.execImpl]
+ * @param {string} [o.globalRoot]       `npm root -g`
+ * @param {string} [o.pathEnv]          PATH to resolve `claude` / `cohort-mcp` on (default process.env.PATH)
+ * @param {number} [o.now]
+ * @param {(m:string)=>void} [o.log] [o.ok] [o.warn]
+ */
+export async function applyFrontDoorSetup(o = {}) {
+  const log = o.log || (() => {});
+  const ok = o.ok || log;
+  const warn = o.warn || log;
+  const dryRun = !!o.dryRun;
+  const pre = dryRun ? "[dry-run] " : "";
+  const agentRoot = String(o.agentRoot || "");
+  const claudeDir = o.claudeDir || join(homedir(), ".claude");
+  const claudeJsonPath = o.claudeJsonPath || join(homedir(), ".claude.json");
+  const sdkRoot = o.sdkRoot || SDK_ROOT;
+  const now = Number.isFinite(o.now) ? o.now : Date.now();
+  const ts = stamp(now);
+  const pathEnv = o.pathEnv === undefined ? (process.env.PATH || "") : String(o.pathEnv || "");
+  const summary = {
+    ok: true,
+    identity: { changed: false, skipped: false },
+    mcp: { changed: false, via: null, skipped: null },
+    settings: { changes: [], skipped: null, hookScript: null },
+    skills: { mode: null, installed: [], unchanged: [] },
+    vendorSkills: { installed: [], unchanged: [], skipped: [], errors: [] },
+  };
+  let agentJson = null; // config/agent.json, shared by the identity block and the skill renderer
+
+  const backupOnce = (p) => {
+    if (dryRun || !existsSync(p)) return;
+    try { copyFileSync(p, `${p}.backup.${ts}`); } catch { /* a missing backup must not block the write; the merge is additive */ }
+  };
+
+  // 1) Identity block.
+  try {
+    const aj = join(agentRoot, "config", "agent.json");
+    if (existsSync(aj)) { try { agentJson = JSON.parse(readFileSync(aj, "utf8")); } catch { agentJson = null; } }
+    if (!agentJson || !(agentJson.fullName || agentJson.firstName)) {
+      summary.identity.skipped = true;
+      warn("identity block skipped: config/agent.json has no name yet (run `maestro setup`, then re-run global-setup)");
+    } else {
+      const mdPath = join(claudeDir, "CLAUDE.md");
+      let cur = "";
+      if (existsSync(mdPath)) { try { cur = readFileSync(mdPath, "utf8"); } catch { cur = ""; } }
+      const r = upsertDelimitedBlock(cur, buildIdentityClaudeMd(agentJson, { agentRoot }), { begin: IDENTITY_BEGIN, end: IDENTITY_END });
+      summary.identity.changed = r.changed;
+      if (r.changed && !dryRun) { mkdirSync(claudeDir, { recursive: true }); writeFileSync(mdPath, r.content); }
+      ok(r.changed ? `${pre}global CLAUDE.md identity block written` : "global CLAUDE.md identity block up to date");
+    }
+  } catch (err) {
+    summary.ok = false;
+    warn(`identity block failed: ${err && err.message}`);
+  }
+
+  // 2) MCP server entry (user scope).
+  try {
+    // Bare `cohort-mcp` needs the global npm install. Until that lands on a
+    // seat (WP-M6 refreshes it on upgrade), point the entry at this package's
+    // own bin under the current node so every session's `cohort` server still
+    // starts; a later re-run flips it back to the bare command once it is on PATH.
+    let entry;
+    if (findOnPath("cohort-mcp", pathEnv)) {
+      entry = cohortMcpEntry(agentRoot);
+    } else {
+      const localBin = join(sdkRoot, "bin", "cohort-mcp.mjs");
+      if (existsSync(localBin)) {
+        entry = cohortMcpEntry(agentRoot, { command: process.execPath, args: [localBin] });
+        log(`cohort-mcp is not on PATH — registering ${localBin} under ${process.execPath} (re-run global-setup after \`npm i -g @cohortapp/agent-sdk\`)`);
+      } else {
+        entry = cohortMcpEntry(agentRoot);
+        warn("cohort-mcp is not on PATH and this package has no bin/cohort-mcp.mjs; the entry is registered as the bare command and will fail to start until the global install exists");
+      }
+    }
+    const cur = readJsonFile(claudeJsonPath);
+    if (cur.unparseable) {
+      summary.ok = false;
+      summary.mcp.skipped = "unparseable";
+      warn(`${claudeJsonPath} is present but does not parse as JSON — leaving it untouched (a running claude may be mid-rewrite; re-run global-setup in a minute, or fix the file). cohort MCP server NOT registered.`);
+    } else {
+      const merged = mergeMcpServers(cur.value, entry);
+      if (!merged.changed) {
+        ok("cohort MCP server already registered in ~/.claude.json");
+      } else if (dryRun) {
+        summary.mcp.changed = true;
+        summary.mcp.via = "json";
+        ok(`${pre}cohort MCP server → ~/.claude.json (user scope)`);
+      } else {
+        summary.mcp.changed = true;
+        const claudeBin = o.claudeBin === undefined ? await defaultClaudeBin(pathEnv) : o.claudeBin;
+        const exec = o.execImpl || defaultExec;
+        let done = false;
+        if (claudeBin) {
+          try {
+            const r = exec(claudeBin, ["mcp", "add-json", "cohort", JSON.stringify(entry), "--scope", "user"]);
+            if (r && r.status === 0) {
+              // Trust but verify: the CLI owns the file format; confirm the entry landed.
+              const after = readJsonFile(claudeJsonPath);
+              done = !after.unparseable && !mergeMcpServers(after.value, entry).changed;
+            }
+          } catch {
+            done = false; // spawn failure → JSON merge below
+          }
+        }
+        if (done) {
+          summary.mcp.via = "cli";
+          ok("cohort MCP server registered via `claude mcp add-json --scope user`");
+        } else {
+          backupOnce(claudeJsonPath);
+          const w = mergeJsonFileAtomic(claudeJsonPath, (doc) => mergeMcpServers(doc, entry), { mode: 0o600 });
+          if (!w.ok) {
+            summary.ok = false;
+            summary.mcp.skipped = w.reason || "write failed";
+            warn(`cohort MCP server NOT written to ${claudeJsonPath}: ${w.reason}`);
+          } else {
+            summary.mcp.via = "json";
+            ok(`cohort MCP server merged into ${claudeJsonPath}${claudeBin ? " (CLI registration failed; JSON merge used)" : ""}`);
+          }
+        }
+      }
+    }
+  } catch (err) {
+    summary.ok = false;
+    warn(`MCP registration failed: ${err && err.message}`);
+  }
+
+  // 3) settings.json.
+  try {
+    const settingsPath = join(claudeDir, "settings.json");
+    const cur = readJsonFile(settingsPath);
+    if (cur.unparseable) {
+      summary.ok = false;
+      summary.settings.skipped = "unparseable";
+      warn(`${settingsPath} is present but does not parse as JSON — leaving it untouched (its hooks and permissions would be lost). Front-door settings NOT applied.`);
+    } else {
+      const r = mergeSessionSettings(cur.value, { agentRoot });
+      summary.settings.changes = r.changes;
+      if (r.changes.length === 0) {
+        ok("global settings already carry the front-door additions (no change)");
+      } else if (dryRun) {
+        ok(`${pre}global settings updated: ${r.changes.join(", ")}`);
+      } else {
+        backupOnce(settingsPath);
+        mkdirSync(claudeDir, { recursive: true });
+        const w = mergeJsonFileAtomic(settingsPath, (doc) => {
+          const m = mergeSessionSettings(doc, { agentRoot });
+          return { config: m.settings, changed: m.changes.length > 0 };
+        }, { mode: 0o644 });
+        if (!w.ok) {
+          summary.ok = false;
+          summary.settings.skipped = w.reason || "write failed";
+          warn(`global settings NOT written to ${settingsPath}: ${w.reason}`);
+        } else {
+          ok(`global settings updated: ${r.changes.join(", ")}`);
+        }
+      }
+    }
+    // The PreToolUse persona hook points at the AGENT's copy of pre-send-audit.sh.
+    // `upgrade` keeps a locally modified copy, so a seat can have the matcher
+    // wired to a script that predates the persona gate. Say so; nothing else
+    // in this WP can (doctor/verify are M5/M6).
+    summary.settings.hookScript = checkPersonaHookScript(agentRoot);
+    if (summary.settings.hookScript.present && !summary.settings.hookScript.personaGate) {
+      warn(`${summary.settings.hookScript.path} has no persona gate (PERSONA_PATTERNS) — the file is older than this SDK or locally modified; the mcp__cohort outbound hook will not screen persona leaks until it is refreshed (\`maestro upgrade --force-overwrite\`, or merge by hand)`);
+    } else if (!summary.settings.hookScript.present) {
+      warn(`${summary.settings.hookScript.path} is missing — the global PreToolUse persona hook will fail closed on every mcp__cohort outbound call until \`maestro upgrade\` ships it`);
+    }
+  } catch (err) {
+    summary.ok = false;
+    warn(`settings merge failed: ${err && err.message}`);
+  }
+
+  // 4) Skills — rendered to this agent's identity where they carry tokens
+  //    (Claude Code loads SKILL.md verbatim; only the cadence consumer used
+  //    to render). No identity yet → templates verbatim, as before.
+  try {
+    const globalRoot = o.globalRoot === undefined ? defaultGlobalRoot() : o.globalRoot;
+    const mode = isGlobalInstall(sdkRoot, { globalRoot }) ? "symlink" : "copy";
+    let context = null;
+    if (agentJson) {
+      let companyJson = null;
+      const cj = join(agentRoot, "config", "company.json");
+      if (existsSync(cj)) { try { companyJson = JSON.parse(readFileSync(cj, "utf8")); } catch { companyJson = null; } }
+      context = buildContext(agentJson, null, companyJson);
+    }
+    const r = installSkills({ sdkRoot, skillsDir: join(claudeDir, "skills"), mode, dryRun, context });
+    summary.skills = { mode, installed: r.installed, unchanged: r.unchanged, rendered: r.rendered || [], errors: r.errors };
+    const renderedNote = r.rendered && r.rendered.length ? `; ${r.rendered.length} rendered to ${agentJson.firstName || agentJson.fullName}` : "";
+    if (!r.ok && r.error) warn(`skills not installed: ${r.error}`);
+    else if (r.installed.length === 0) ok(`global skills up to date (${r.unchanged.length} ${mode === "symlink" ? "linked" : "copied"}${renderedNote})`);
+    else ok(`${pre}global skills ${mode === "symlink" ? "linked" : "copied"}: ${r.installed.join(", ")}${r.unchanged.length ? ` (+${r.unchanged.length} unchanged)` : ""}${renderedNote}`);
+    if (!agentJson && r.plan && r.plan.length) warn("skills installed as templates ({{agent.*}} unrendered): config/agent.json has no name yet — re-run global-setup after `maestro setup`");
+    for (const e of r.errors || []) warn(`skill ${e.name}: ${e.error}`);
+  } catch (err) {
+    summary.ok = false;
+    warn(`skills install failed: ${err && err.message}`);
+  }
+
+  // 5) Vendored design skill packs (WP-M7) — impeccable, emilkowalski, taste-skill,
+  //    unlazy, installed under their OWN frontmatter names because that is what
+  //    their prose and the cohort-design harmoniser refer to. Copies, never
+  //    links: the point of vendoring is that the seat holds reviewed bytes. A
+  //    directory that is not ours (the human installed the upstream pack
+  //    themselves, launcher and hooks and all) is left exactly as it is.
+  try {
+    // An opt-out, because this step writes into the GLOBAL ~/.claude/skills and
+    // so reaches every piece of work done on the machine, including repos that
+    // have nothing to do with Cohort design. A seat that does not want the
+    // packs sets MAESTRO_SKIP_VENDOR_SKILLS=1 and keeps every other step.
+    const skip = String(process.env.MAESTRO_SKIP_VENDOR_SKILLS || "").trim();
+    if (skip && skip !== "0" && skip.toLowerCase() !== "false") {
+      summary.vendorSkills = { skippedByEnv: true };
+      ok("vendored design skills skipped (MAESTRO_SKIP_VENDOR_SKILLS)");
+      return summary;
+    }
+    const [{ PACKS }, vendor] = await Promise.all([
+      import("../../scripts/vendor/skill-packs.mjs"),
+      import("../collective/vendor-skills.mjs"),
+    ]);
+    const r = vendor.installVendorSkills({ sdkRoot, skillsDir: join(claudeDir, "skills"), packs: PACKS, dryRun });
+    summary.vendorSkills = { installed: r.installed, unchanged: r.unchanged, skipped: r.skipped, backups: r.backups || [], errors: r.errors };
+    if (r.installed.length === 0 && r.skipped.length === 0 && r.errors.length === 0) {
+      ok(`vendored design skills up to date (${r.unchanged.length} pack skill(s))`);
+    } else if (r.installed.length) {
+      ok(`${pre}vendored design skills copied: ${r.installed.join(", ")}${r.unchanged.length ? ` (+${r.unchanged.length} unchanged)` : ""}`);
+    }
+    for (const b of r.backups || []) warn(`design skill ${b.name}: local edits found (${b.files.join(", ")}) — copied to ${b.path} before rewriting`);
+    for (const sk of r.skipped) warn(`design skill ${sk.name} left alone: ${sk.reason}`);
+    for (const e of r.errors || []) warn(`design pack ${e.pack}: ${e.error}`);
+  } catch (err) {
+    // Fail-open: an SDK copy that predates WP-M7 has no vendor tree, and a seat
+    // that cannot install design skills must still get its identity and tools.
+    warn(`vendored design skills not installed: ${err && err.message}`);
+  }
+
+  return summary;
+}
+
+export default { applyFrontDoorSetup, mergeJsonFileAtomic, findOnPath, pickClaudeBin, checkPersonaHookScript, SDK_ROOT };