@chorus-aidlc/chorus 0.16.3 → 0.17.0

package/cli/init/codex-mcp-config.mjs

@@ -0,0 +1,183 @@
+// cli/init/codex-mcp-config.mjs
+// Writes the Chorus native-MCP server block into ~/.codex/config.toml using a KEYLESS
+// env-var reference — `bearer_token_env_var = "CHORUS_API_KEY"` — instead of a literal
+// `Authorization: Bearer <key>`. Codex loads ~/.codex/.env into its process env at arg0
+// startup and resolves that env var into `Authorization: Bearer <key>` at connect time
+// (config/src/mcp_types.rs StreamableHttp.bearer_token_env_var; codex-mcp resolve_bearer_token),
+// so the API key lives in exactly ONE place (~/.codex/.env). A daemon-woken Codex — whose
+// spawner exports CHORUS_API_KEY into the child env — then also authenticates to native MCP,
+// closing the gap a literal Bearer left (cli/codex-spawner.mjs:16-22).
+//
+// `codex plugin add` does NOT write [mcp_servers.chorus] (its marketplace `authentication:
+// ON_INSTALL` is metadata only — verified codex-cli 0.150.1), so `chorus agents add` writes it
+// here, AFTER the plugin install (authoritative, no race).
+//
+// TARGETED TEXTUAL upsert — no TOML-parser dependency (the repo stays pure-JS / cross-platform),
+// preserving every other section, key, and comment verbatim. The secret is NEVER written here
+// (bearer_token_env_var is a variable NAME, not the key).
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const BEARER_ENV_VAR = "CHORUS_API_KEY";
+
+/** A non-empty trimmed string, or undefined. */
+function nonEmpty(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+/**
+ * Resolve the Codex `~/.codex/config.toml` path. Honors `CODEX_HOME`, then `HOME` (so tests
+ * can inject a temp home), else the OS home dir — matching cli/codex-spawner.mjs +
+ * install-methods.mjs.
+ * @param {Record<string, string | undefined>} env
+ */
+export function resolveCodexConfigPath(env) {
+  const base = nonEmpty(env.CODEX_HOME) ?? join(nonEmpty(env.HOME) ?? homedir(), ".codex");
+  return join(base, "config.toml");
+}
+
+/**
+ * Normalize a Chorus base URL to the MCP endpoint the same way the hook wrapper
+ * (chorus-mcp-call.sh) does: a URL that already has a path segment beyond the host is used
+ * as-is; a bare host gains `/api/mcp`. Returns undefined for an empty URL.
+ * @param {string | undefined} rawUrl
+ */
+export function codexMcpUrl(rawUrl) {
+  const u = nonEmpty(rawUrl);
+  if (!u) return undefined;
+  const trimmed = u.replace(/\/+$/, "");
+  const m = trimmed.match(/^https?:\/\/[^/]+(\/.*)?$/);
+  if (m && m[1] && m[1].length > 0) return trimmed; // already a full endpoint
+  return `${trimmed}/api/mcp`;
+}
+
+// TOML basic-string value: escape backslash then double-quote. URLs don't contain these, but
+// escape defensively so we never emit invalid TOML.
+const toToml = (v) => `"${String(v).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+
+/**
+ * Upsert `[mcp_servers.chorus]` in `~/.codex/config.toml` to
+ *   url = "<mcp-endpoint>"
+ *   bearer_token_env_var = "CHORUS_API_KEY"
+ * and MIGRATE away any legacy literal auth: a `bearer_token = "..."` line is dropped, and a
+ * `[mcp_servers.chorus.http_headers]` `Authorization = "..."` line is removed (dropping the
+ * whole http_headers subtable when it becomes empty, preserving any OTHER header). Every other
+ * section/key/comment in the file is preserved verbatim.
+ *
+ * Atomic 0600 temp+rename; idempotent (a re-run with the same url reproduces the file). The API
+ * key is NEVER written — only the env-var NAME.
+ * @param {{ configPath: string, url: string }} args
+ * @param {{
+ *   read?: (p: string) => string,
+ *   write?: (p: string, c: string, o: object) => void,
+ *   mkdir?: (p: string, o: object) => void,
+ *   rename?: (from: string, to: string) => void,
+ * }} [deps]
+ * @returns {string} the config.toml path written
+ */
+export function writeCodexMcpServer({ configPath, url }, deps = {}) {
+  const read = deps.read ?? ((p) => readFileSync(p, "utf8"));
+  const write = deps.write ?? writeFileSync;
+  const mkdir = deps.mkdir ?? mkdirSync;
+  const rename = deps.rename ?? renameSync;
+
+  const mcpUrl = codexMcpUrl(url);
+  if (!mcpUrl) throw new Error("writeCodexMcpServer requires a url");
+
+  let existing = "";
+  try {
+    existing = read(configPath);
+  } catch {
+    existing = ""; // no file yet — start fresh
+  }
+
+  const lines = existing.length ? existing.split(/\r?\n/) : [];
+  if (lines.length && lines[lines.length - 1] === "") lines.pop();
+
+  const isHeader = (s) => /^\s*\[/.test(s);
+  const chorusHeaderRe = /^\s*\[mcp_servers\.chorus\]\s*$/;
+  const headersHeaderRe = /^\s*\[mcp_servers\.chorus\.http_headers\]\s*$/;
+  // A `key = value` line (not a comment or blank) — used to tell whether a subtable still has
+  // content after removing Authorization.
+  const isKvLine = (s) => /^\s*[^#\s][^=]*=/.test(s);
+
+  // Split into groups: a preamble (before the first table header) + one group per table header.
+  const groups = [];
+  let cur = { header: null, body: [] };
+  for (const line of lines) {
+    if (isHeader(line)) {
+      groups.push(cur);
+      cur = { header: line, body: [] };
+    } else {
+      cur.body.push(line);
+    }
+  }
+  groups.push(cur);
+
+  const outGroups = [];
+  let wroteChorus = false;
+  for (const g of groups) {
+    if (g.header === null) {
+      outGroups.push(...g.body); // preamble verbatim
+      continue;
+    }
+    if (chorusHeaderRe.test(g.header)) {
+      // Normalize the [mcp_servers.chorus] body: set url + bearer_token_env_var in place,
+      // drop any literal bearer_token, preserve every other key.
+      let seenUrl = false;
+      let seenBearerEnv = false;
+      const body = [];
+      for (const l of g.body) {
+        if (/^\s*url\s*=/.test(l)) {
+          body.push(`url = ${toToml(mcpUrl)}`);
+          seenUrl = true;
+          continue;
+        }
+        if (/^\s*bearer_token_env_var\s*=/.test(l)) {
+          body.push(`bearer_token_env_var = ${toToml(BEARER_ENV_VAR)}`);
+          seenBearerEnv = true;
+          continue;
+        }
+        if (/^\s*bearer_token\s*=/.test(l)) continue; // drop legacy literal bearer_token
+        body.push(l);
+      }
+      const head = [];
+      if (!seenUrl) head.push(`url = ${toToml(mcpUrl)}`);
+      if (!seenBearerEnv) head.push(`bearer_token_env_var = ${toToml(BEARER_ENV_VAR)}`);
+      outGroups.push(g.header, ...head, ...body);
+      wroteChorus = true;
+      continue;
+    }
+    if (headersHeaderRe.test(g.header)) {
+      // Strip the literal Authorization; drop the whole subtable if nothing else remains.
+      const body = g.body.filter((l) => !/^\s*Authorization\s*=/i.test(l));
+      if (body.some(isKvLine)) {
+        outGroups.push(g.header, ...body);
+      }
+      // else: drop the emptied subtable entirely
+      continue;
+    }
+    outGroups.push(g.header, ...g.body);
+  }
+
+  if (!wroteChorus) {
+    if (outGroups.length && outGroups[outGroups.length - 1] !== "") outGroups.push("");
+    outGroups.push(
+      "[mcp_servers.chorus]",
+      `url = ${toToml(mcpUrl)}`,
+      `bearer_token_env_var = ${toToml(BEARER_ENV_VAR)}`,
+    );
+  }
+
+  // Trim trailing blank lines so idempotent re-runs never accumulate them.
+  while (outGroups.length && outGroups[outGroups.length - 1] === "") outGroups.pop();
+  const content = outGroups.join("\n") + "\n";
+
+  mkdir(dirname(configPath), { recursive: true });
+  const tmp = `${configPath}.tmp`;
+  write(tmp, content, { mode: 0o600 });
+  rename(tmp, configPath);
+  return configPath;
+}

package/cli/init/contracts.mjs

@@ -0,0 +1,120 @@
+// cli/init/contracts.mjs
+// Shared contracts for `chorus init` (idea c055e285, A1 foundation). Two
+// extension points let sibling ideas grow the command without editing its core:
+//
+//   1. AgentAdapter — one per coding-agent harness (Claude Code, Codex, Kiro,
+//      opencode, OpenClaw, Pi, dsh). Adding an agent = adding an adapter to the
+//      registry (cli/init/registry.mjs). Detection, install-state read, and the
+//      plugin install all live behind this interface.
+//
+//   2. InitStep — one per configuration concern. THIS change ships the
+//      credential-seed step (scope "once") and the plugin-install step (scope
+//      "per-agent"). Sibling ideas register more steps (MCP proxy cc115e6b,
+//      daemon setup a7c2a3e8) into the same ordered registry.
+//
+// Iteration ownership (resolves proposal-review note #3): the ORCHESTRATOR
+// (runInit) owns per-agent iteration. A `per-agent` step's run(ctx) is invoked
+// once per selected agent with ctx.agentId set; a `once` step's run(ctx) is
+// invoked a single time with ctx.agentId undefined. Steps never loop the
+// selection themselves.
+//
+// Plain ESM, zero dependencies — ships verbatim in the npm package. This module
+// is intentionally (mostly) JSDoc typedefs plus a few frozen enums so the shape
+// is one source of truth for the whole cli/init tree and its tests.
+
+/**
+ * Step scopes. `once` runs a single time per `chorus init` invocation;
+ * `per-agent` runs once for each selected agent.
+ * @readonly
+ */
+export const STEP_SCOPES = Object.freeze({ ONCE: "once", PER_AGENT: "per-agent" });
+
+/**
+ * Terminal per-unit outcomes a step reports for the summary table.
+ * - installed: a fresh configuration was applied
+ * - repaired:  an existing but incomplete/broken configuration was fixed
+ * - skipped:   already configured / nothing to do
+ * - seeded:    a `once` step persisted shared state (e.g. credentials)
+ * - failed:    the unit could not be configured (detail carries the reason)
+ * - unsupported: the agent has no verified automated mechanism (guided message)
+ * @readonly
+ */
+export const OUTCOME_ACTIONS = Object.freeze({
+  INSTALLED: "installed",
+  REPAIRED: "repaired",
+  SKIPPED: "skipped",
+  SEEDED: "seeded",
+  FAILED: "failed",
+  UNSUPPORTED: "unsupported",
+});
+
+/** Outcome actions that mean "this unit did not succeed" — drive the exit code. */
+export const FAILURE_ACTIONS = Object.freeze([OUTCOME_ACTIONS.FAILED]);
+
+/**
+ * @typedef {Object} AgentDetection
+ * @property {string} id            Stable adapter id (e.g. "claude").
+ * @property {string} displayName   Human label (e.g. "Claude Code").
+ * @property {boolean} binaryOnPath Whether the agent's CLI resolves on PATH.
+ * @property {boolean} configDirPresent Whether the agent's config dir exists.
+ * @property {boolean} detected     `binaryOnPath || configDirPresent` — drives
+ *                                  default pre-selection only, never gates choice.
+ */
+
+/**
+ * @typedef {Object} AgentInstallState
+ * @property {boolean} supported    Whether an automated install is available on
+ *                                  this machine (false ⇒ guided message only).
+ * @property {boolean} marketplaceRegistered Whether the Chorus marketplace/source
+ *                                  is already registered for this agent.
+ * @property {boolean} pluginInstalled Whether the Chorus plugin is already installed.
+ * @property {string} [version]     Installed plugin version, when known.
+ * @property {string} [detail]      Optional human note (e.g. why unsupported).
+ */
+
+/**
+ * @typedef {Object} AgentAdapter
+ * @property {string} id
+ * @property {string} displayName
+ * @property {(env: NodeJS.ProcessEnv) => {binaryOnPath: boolean, configDirPresent: boolean}} detect
+ *   Pure-ish: may stat the filesystem and look up PATH; MUST NOT mutate anything.
+ * @property {(deps: object) => AgentInstallState} readInstallState
+ *   Read-only idempotency probe (e.g. parse the agent's own state files).
+ * @property {(ctx: StepContext) => StepOutcome} installPlugin
+ *   Register the agent's native remote marketplace and install/enable the Chorus
+ *   plugin surface. MUST be idempotent, MUST back up before overwrite via
+ *   ctx.backup(), and MUST NOT write any per-agent MCP/credential config.
+ */
+
+/**
+ * @typedef {Object} InitStep
+ * @property {string} id            Stable step id (e.g. "credential-seed").
+ * @property {number} order         Ascending run order.
+ * @property {("once"|"per-agent")} scope
+ * @property {(ctx: StepContext) => (StepOutcome | Promise<StepOutcome>)} run
+ */
+
+/**
+ * @typedef {Object} StepOutcome
+ * @property {string} stepId
+ * @property {string} [agentId]     Present for per-agent outcomes.
+ * @property {("installed"|"repaired"|"skipped"|"seeded"|"failed"|"unsupported")} action
+ * @property {string} detail        One-line human explanation for the summary.
+ */
+
+/**
+ * @typedef {Object} StepContext
+ * @property {string[]} selection   Selected agent ids (for `once` steps that need the set).
+ * @property {string} [agentId]     The current agent id (per-agent steps only).
+ * @property {AgentAdapter} [adapter] The current agent's adapter (per-agent steps only).
+ * @property {object} flags         Parsed init flags (see cli/init-args.mjs).
+ * @property {{ log: (m: string) => void, ask: Function, isTTY: boolean }} io
+ * @property {(path: string) => (string|null)} backup  Copy a file to <path>.chorus-bak
+ *   once before overwrite; returns the backup path or null if the source is absent.
+ * @property {NodeJS.ProcessEnv} env
+ */
+
+/** True when an outcome represents a failure (drives the process exit code). */
+export function isFailureOutcome(outcome) {
+  return !!outcome && FAILURE_ACTIONS.includes(outcome.action);
+}

package/cli/init/detect.mjs

@@ -0,0 +1,97 @@
+// cli/init/detect.mjs
+// Cross-platform detection primitives for `chorus init` adapters. Dual signal:
+// a CLI binary resolvable on PATH, and/or an agent config directory present.
+// All IO (env, filesystem, platform, home) is injectable so adapters unit-test
+// without a real machine. Zero runtime dependencies beyond node core.
+
+import { existsSync as fsExistsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, delimiter as pathDelimiter } from "node:path";
+
+/**
+ * Expand a config-dir spec into an absolute path:
+ *   - a leading `~` → the home directory,
+ *   - a leading `$VAR` segment → env[VAR] (whole spec dropped if unset),
+ * Returns null when the spec cannot be resolved (e.g. `$DSH_HOME` unset).
+ * @param {string} spec
+ * @param {{ env?: Record<string,string|undefined>, home?: string }} [deps]
+ * @returns {string | null}
+ */
+export function expandPath(spec, { env = process.env, home = homedir() } = {}) {
+  if (typeof spec !== "string" || !spec) return null;
+  if (spec.startsWith("~")) {
+    return join(home, spec.slice(1).replace(/^[/\\]/, ""));
+  }
+  if (spec.startsWith("$")) {
+    const slash = spec.search(/[/\\]/);
+    const varName = (slash === -1 ? spec.slice(1) : spec.slice(1, slash));
+    const value = env[varName];
+    if (!value) return null; // unset env var → this candidate does not apply
+    const rest = slash === -1 ? "" : spec.slice(slash + 1);
+    return rest ? join(value, rest) : value;
+  }
+  return spec;
+}
+
+/**
+ * True if any of `names` resolves to an executable on PATH. Scans PATH entries
+ * and (on Windows) the PATHEXT extension list. Pure lookup — never executes.
+ * @param {string[]} names  candidate binary base names (e.g. ["claude"])
+ * @param {{
+ *   env?: Record<string,string|undefined>,
+ *   existsSync?: (p: string) => boolean,
+ *   platform?: NodeJS.Platform,
+ * }} [deps]
+ * @returns {boolean}
+ */
+export function binaryOnPath(names, { env = process.env, existsSync = fsExistsSync, platform = process.platform } = {}) {
+  const rawPath = env.PATH ?? env.Path ?? "";
+  if (!rawPath) return false;
+  const sep = platform === "win32" ? ";" : pathDelimiter;
+  const dirs = rawPath.split(sep).filter(Boolean);
+  const exts =
+    platform === "win32"
+      ? ["", ...String(env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean)]
+      : [""];
+  for (const name of names) {
+    if (!name) continue;
+    for (const dir of dirs) {
+      for (const ext of exts) {
+        // Windows filesystems are case-insensitive; try the ext as-given.
+        if (existsSync(join(dir, name + ext))) return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * True if any of the config-dir specs (after expandPath) exists on disk.
+ * @param {string[]} specs
+ * @param {{
+ *   env?: Record<string,string|undefined>,
+ *   existsSync?: (p: string) => boolean,
+ *   home?: string,
+ * }} [deps]
+ * @returns {boolean}
+ */
+export function configDirPresent(specs, { env = process.env, existsSync = fsExistsSync, home = homedir() } = {}) {
+  for (const spec of specs || []) {
+    const resolved = expandPath(spec, { env, home });
+    if (resolved && existsSync(resolved)) return true;
+  }
+  return false;
+}
+
+/**
+ * Compute the dual-signal detection for one agent descriptor.
+ * @param {{ binaries: string[], configDirs: string[] }} descriptor
+ * @param {object} [deps]  forwarded to binaryOnPath / configDirPresent
+ * @returns {{ binaryOnPath: boolean, configDirPresent: boolean }}
+ */
+export function detectSignals(descriptor, deps = {}) {
+  return {
+    binaryOnPath: binaryOnPath(descriptor.binaries || [], deps),
+    configDirPresent: configDirPresent(descriptor.configDirs || [], deps),
+  };
+}

package/cli/init/file-template.mjs

@@ -0,0 +1,248 @@
+// cli/init/file-template.mjs
+// Kiro's Chorus "plugin" is not a CLI-installable package — it is a set of loose
+// files dropped under .kiro/ (skills, the `chorus` main agent + reviewer
+// subagents, the steering doc, and the session-automation hook scripts), plus a
+// `chorus` MCP server merged into settings/mcp.json. This module drops those
+// files natively in pure JS so `chorus init` can install them CROSS-PLATFORM
+// (Windows-safe) with no bash / curl dependency — Node's built-in `fetch`
+// downloads the template, node:fs writes it. (The legacy public/install-kiro.sh
+// is now a deprecation stub that redirects to `chorus init`; this module is the
+// sole Kiro plugin installer.)
+//
+// ASSET SOURCE (owner-decided): the .kiro/ assets are DOWNLOADED from the
+// connected Chorus instance at `${CHORUS_URL}/kiro-plugin/…`, NOT bundled into
+// the npm package. `chorus init` already holds the connection URL, so this keeps
+// the assets in lockstep with the server the user is connecting to and avoids
+// shipping a second copy.
+//
+// The variable asset lists (skills / reviewer agents / hook scripts) live in a
+// data file — public/kiro-plugin/manifest.txt — read by this module
+// (parseManifest), so the shipped asset set is declared in one place.
+
+import { readFileSync, writeFileSync, mkdirSync, chmodSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The shared artifact manifest (repo path — used by the parity test; the runtime
+ *  installer downloads its own copy from the instance so it works in the stripped
+ *  npm package where public/ is not shipped). */
+export const KIRO_MANIFEST_URL = new URL("../../public/kiro-plugin/manifest.txt", import.meta.url);
+
+/**
+ * Parse the manifest text into the three artifact lists: one "<kind> <name>"
+ * pair per line; blank lines and `#` comments ignored; kind ∈ {skill, reviewer,
+ * hook}. Unknown kinds are ignored (forward-compatible).
+ * @param {string} text
+ * @returns {{ skills: string[], reviewerAgents: string[], hookScripts: string[] }}
+ */
+export function parseManifest(text) {
+  const skills = [];
+  const reviewerAgents = [];
+  const hookScripts = [];
+  for (const rawLine of String(text ?? "").split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const parts = line.split(/\s+/);
+    const kind = parts[0];
+    const name = parts[1];
+    if (!name) continue;
+    if (kind === "skill") skills.push(name);
+    else if (kind === "reviewer") reviewerAgents.push(name);
+    else if (kind === "hook") hookScripts.push(name);
+  }
+  return { skills, reviewerAgents, hookScripts };
+}
+
+/** Read + parse the shared manifest from a local file (default: the repo copy).
+ *  Used by the parity test; the installer downloads its copy instead. */
+export function readKiroManifestFile({ manifestUrl = KIRO_MANIFEST_URL } = {}) {
+  return parseManifest(readFileSync(fileURLToPath(manifestUrl), "utf8"));
+}
+
+/**
+ * Normalize a Chorus connection URL to the ASSET BASE — the origin under which
+ * public/ is served (public/kiro-plugin/… ⇒ `${base}/kiro-plugin/…`). Mirrors
+ * install-kiro.sh: strip a trailing `/api/mcp` (the MCP endpoint) and any
+ * trailing slash. Throws on an empty / non-http(s) URL (named in the message).
+ * @param {string} chorusUrl
+ * @returns {string}
+ */
+export function normalizeAssetBase(chorusUrl) {
+  const raw = typeof chorusUrl === "string" ? chorusUrl.trim() : "";
+  if (!raw) throw new Error("CHORUS_URL is not set — cannot download the kiro .kiro/ template");
+  if (!/^https?:\/\//i.test(raw)) {
+    throw new Error(`CHORUS_URL must start with http:// or https:// — got: ${raw}`);
+  }
+  return raw
+    .replace(/\/+$/, "") // trailing slash(es)
+    .replace(/\/api\/mcp$/i, "") // the MCP endpoint suffix
+    .replace(/\/+$/, ""); // any slash the strip left behind
+}
+
+/**
+ * Substitute the `__CHORUS_BIN__` placeholder in the main agent's hook `command`
+ * strings with the resolved ABSOLUTE chorus-bin path. Fails loudly (throws) if
+ * any placeholder survives — mirrors install-kiro.sh's post-write grep guard.
+ * @param {string} text  raw agents/chorus.json content
+ * @param {string} chorusBinAbs  absolute path to <KIRO_DIR>/chorus-bin
+ * @returns {string}
+ */
+export function substituteChorusBin(text, chorusBinAbs) {
+  const out = String(text).split("__CHORUS_BIN__").join(chorusBinAbs);
+  if (out.includes("__CHORUS_BIN__")) {
+    throw new Error("__CHORUS_BIN__ placeholder was not fully substituted in agents/chorus.json");
+  }
+  return out;
+}
+
+/**
+ * Merge the `chorus` MCP server into an existing settings/mcp.json body,
+ * PRESERVING every pre-existing server. Empty/absent body ⇒ a fresh document.
+ * Invalid JSON throws (never silently clobbers a file we can't parse).
+ * @param {string} existingText  current file contents ("" if absent)
+ * @param {object} serverObj  the chorus server object to set at .mcpServers.chorus
+ * @returns {string}  pretty-printed JSON (trailing newline)
+ */
+export function mergeChorusServer(existingText, serverObj) {
+  let data = {};
+  const trimmed = (existingText ?? "").trim();
+  if (trimmed) {
+    try {
+      data = JSON.parse(trimmed);
+    } catch (err) {
+      throw new Error(`existing settings/mcp.json is not valid JSON: ${err?.message ?? String(err)}`);
+    }
+  }
+  if (typeof data !== "object" || data === null || Array.isArray(data)) data = {};
+  if (typeof data.mcpServers !== "object" || data.mcpServers === null || Array.isArray(data.mcpServers)) {
+    data.mcpServers = {};
+  }
+  data.mcpServers.chorus = serverObj;
+  return `${JSON.stringify(data, null, 2)}\n`;
+}
+
+/**
+ * Install the Chorus `.kiro/` file template natively.
+ *
+ * Two phases guarantee NO PARTIAL DROP: (1) download every asset into memory,
+ * verifying each fetch and aborting (naming the unreachable URL) before touching
+ * disk; (2) only once all fetches succeed, write the tree, chmod hooks (POSIX
+ * only), and merge the `chorus` MCP server into settings/mcp.json.
+ *
+ * @param {{
+ *   chorusUrl: string,
+ *   kiroDir: string,
+ *   fetchImpl?: typeof fetch,
+ *   backup?: (path: string) => (string|null),
+ *   platform?: NodeJS.Platform,
+ *   log?: (m: string) => void,
+ * }} opts
+ * @returns {Promise<{ skills: number, reviewerAgents: number, hookScripts: number, kiroDir: string, chorusBinAbs: string }>}
+ */
+export async function installFileTemplate({
+  chorusUrl,
+  kiroDir,
+  fetchImpl,
+  backup,
+  platform = process.platform,
+  log,
+} = {}) {
+  const assetBase = normalizeAssetBase(chorusUrl); // throws on bad/empty URL
+  const doFetch = fetchImpl ?? globalThis.fetch;
+  if (typeof doFetch !== "function") {
+    throw new Error("no fetch implementation available (need Node 18+ global fetch or an injected fetchImpl)");
+  }
+  const kiroBase = `${assetBase}/kiro-plugin`;
+  const chorusBinAbs = join(kiroDir, "chorus-bin");
+
+  // fetch <relpath-under-kiro-plugin> as text; verify + name the URL on failure.
+  async function fetchText(rel) {
+    const url = `${kiroBase}/${rel}`;
+    let res;
+    try {
+      res = await doFetch(url);
+    } catch (err) {
+      throw new Error(`failed to download ${url}: ${err?.message ?? String(err)}`);
+    }
+    if (!res || !res.ok) {
+      throw new Error(`failed to download ${url} (HTTP ${res?.status ?? "?"}) — is CHORUS_URL correct and reachable?`);
+    }
+    return await res.text();
+  }
+
+  // ---- phase 1: fetch EVERYTHING into memory (no disk writes) ----
+  const manifest = parseManifest(await fetchText("manifest.txt"));
+  if (manifest.skills.length === 0 && manifest.reviewerAgents.length === 0 && manifest.hookScripts.length === 0) {
+    throw new Error(`manifest at ${kiroBase}/manifest.txt resolved no assets — is the instance serving the kiro plugin?`);
+  }
+
+  /** @type {Map<string, { text: string, exec?: boolean }>} dest-abs-path -> content */
+  const files = new Map();
+
+  // fixed assets (single, always-present files — not in the variable manifest)
+  const mcpTemplateText = await fetchText(".kiro/settings/mcp.json");
+  files.set(join(kiroDir, "steering", "chorus.md"), { text: await fetchText(".kiro/steering/chorus.md") });
+  files.set(join(kiroDir, "agents", "chorus.md"), { text: await fetchText(".kiro/agents/chorus.md") });
+  // main agent: substitute the hook-command placeholder in memory (throws if it survives)
+  files.set(join(kiroDir, "agents", "chorus.json"), {
+    text: substituteChorusBin(await fetchText(".kiro/agents/chorus.json"), chorusBinAbs),
+  });
+
+  for (const a of manifest.reviewerAgents) {
+    files.set(join(kiroDir, "agents", `${a}.json`), { text: await fetchText(`.kiro/agents/${a}.json`) });
+  }
+  for (const s of manifest.skills) {
+    files.set(join(kiroDir, "skills", s, "SKILL.md"), { text: await fetchText(`.kiro/skills/${s}/SKILL.md`) });
+  }
+  for (const h of manifest.hookScripts) {
+    files.set(join(chorusBinAbs, h), { text: await fetchText(`bin/${h}`), exec: true });
+  }
+
+  // The chorus server object is single-sourced from the downloaded template, but
+  // its `url` MUST be the CONCRETE endpoint, not the template's
+  // `${CHORUS_URL}/api/mcp` token: kiro does NOT interpolate a bare `${...}` in the
+  // url field (only `${env:...}`, as the Authorization header uses), so leaving a
+  // token here makes kiro fail the server with "relative URL without a base". Bake
+  // the resolved `<assetBase>/api/mcp`; the API key stays the `${env:CHORUS_API_KEY}`
+  // ref — kiro DOES resolve that, and it keeps the secret off disk + per-agent.
+  let serverObj;
+  try {
+    serverObj = JSON.parse(mcpTemplateText)?.mcpServers?.chorus;
+  } catch (err) {
+    throw new Error(`downloaded settings/mcp.json template is not valid JSON: ${err?.message ?? String(err)}`);
+  }
+  if (!serverObj || typeof serverObj !== "object") {
+    throw new Error("downloaded settings/mcp.json template has no mcpServers.chorus entry to merge");
+  }
+  serverObj.url = `${assetBase}/api/mcp`;
+
+  // ---- phase 2: write to disk (every fetch already verified) ----
+  for (const [dest, { text, exec }] of files) {
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, text);
+    if (exec && platform !== "win32") {
+      try {
+        chmodSync(dest, 0o755);
+      } catch {
+        // chmod is best-effort; a read-only FS shouldn't fail the whole install.
+      }
+    }
+  }
+
+  // ---- merge the `chorus` MCP server into settings/mcp.json (back up first) ----
+  const mcpJsonPath = join(kiroDir, "settings", "mcp.json");
+  mkdirSync(dirname(mcpJsonPath), { recursive: true });
+  const existed = existsSync(mcpJsonPath);
+  if (existed && typeof backup === "function") backup(mcpJsonPath);
+  const existingText = existed ? readFileSync(mcpJsonPath, "utf8") : "";
+  writeFileSync(mcpJsonPath, mergeChorusServer(existingText, serverObj));
+
+  log?.(`[chorus agents add] kiro: wrote .kiro/ template into ${kiroDir}`);
+  return {
+    skills: manifest.skills.length,
+    reviewerAgents: manifest.reviewerAgents.length,
+    hookScripts: manifest.hookScripts.length,
+    kiroDir,
+    chorusBinAbs,
+  };
+}