@mmerterden/multi-agent-pipeline 20.28.0 → 20.30.0

package/pipeline/scripts/stack-toggle.mjs

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+/**
+ * @file stack-toggle.mjs  -  read and set which stack plugins a repository
+ * enables, the one writer of `.claude/settings.json` `enabledPlugins` for
+ * `/multi-agent:stack` and the office panel (POST /v1/stack).
+ *
+ * The write rules, applied to the repository's settings file and nothing else:
+ *
+ *   - every plugin `pluginsForStacks()` (scripts/_stack-routing.mjs) derives for
+ *     the selection is set to true;
+ *   - every other stack toolkit of the marketplace is set to false;
+ *   - ai-common-toolkit and ai-analyst-toolkit are always true;
+ *   - retired `ai-*-engineering-toolkit` keys are deleted;
+ *   - `xcode-integration@xcode-apple` follows `ios`, only when the installer
+ *     linked Apple's marketplace (`~/.claude/xcode-apple-marketplace`);
+ *   - every key outside the marketplace and every other setting is kept as it
+ *     was.
+ *
+ * An empty selection is refused rather than written: it would turn every stack
+ * toolkit off, which nobody asks for by selecting nothing. The file is written
+ * atomically (a temporary file renamed over it), keeping its mode.
+ *
+ * Usage:
+ *   stack-toggle.mjs status --repo <path> [--json]
+ *   stack-toggle.mjs set --repo <path> <stack>... [--json] [--dry-run]
+ *
+ * Exit: 0 done, 1 refused (unknown stack, empty selection, unreadable
+ * settings), 2 usage.
+ *
+ * @module pipeline/scripts/stack-toggle
+ */
+
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import {
+  ALWAYS_ON,
+  KNOWN_STACKS,
+  STACK_PLUGIN_ALIAS,
+  expandStackArg,
+  pluginsForStacks,
+} from "./_stack-routing.mjs";
+import { PLUGIN_MARKETPLACE, pluginSkillRootCandidates } from "../lib/plugin-skill-roots.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+const SUFFIX = `@${PLUGIN_MARKETPLACE}`;
+const XCODE_KEY = "xcode-integration@xcode-apple";
+const RETIRED = /^ai-[a-z]+-engineering-toolkit@multi-agent-plugins$/;
+
+export class StackError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+const home = (env) => env.HOME || homedir();
+const stackPlugin = (s) => `ai-${STACK_PLUGIN_ALIAS[s] ?? s}-toolkit`;
+
+/** The repository's settings file. */
+export function settingsPath(repo) {
+  return join(repo, ".claude", "settings.json");
+}
+
+function readSettings(repo) {
+  const p = settingsPath(repo);
+  if (!existsSync(p)) return {};
+  try {
+    const doc = JSON.parse(readFileSync(p, "utf8"));
+    if (!doc || typeof doc !== "object" || Array.isArray(doc)) throw new Error("not an object");
+    return doc;
+  } catch (err) {
+    throw new StackError(
+      "unreadable-settings",
+      `the repository's .claude/settings.json is not valid JSON (${err.message})`,
+    );
+  }
+}
+
+function marketplaceNames(env) {
+  const path = join(
+    home(env),
+    ".claude",
+    "plugins",
+    "marketplaces",
+    PLUGIN_MARKETPLACE,
+    ".claude-plugin",
+    "marketplace.json",
+  );
+  try {
+    return (JSON.parse(readFileSync(path, "utf8")).plugins || [])
+      .map((p) => p.name)
+      .filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
+/** The skill names a plugin ships, from its best local root. */
+function skillsOf(plugin, env) {
+  // Marketplace checkout first, then the plugin cache, newest version first.
+  const marketplaceCopy = join(
+    home(env),
+    ".claude",
+    "plugins",
+    "marketplaces",
+    PLUGIN_MARKETPLACE,
+    "plugins",
+    plugin,
+    "skills",
+  );
+  for (const root of [marketplaceCopy, ...pluginSkillRootCandidates(home(env), [plugin])]) {
+    try {
+      return readdirSync(root)
+        .filter((d) => existsSync(join(root, d, "SKILL.md")))
+        .sort();
+    } catch {
+      // The next root may be readable.
+    }
+  }
+  return [];
+}
+
+/**
+ * The repository's current state: which stacks are on, every marketplace
+ * plugin with its enablement and skills.
+ *
+ * @param {string} repo  absolute path
+ */
+export function stackStatus(repo, env = process.env) {
+  if (!isAbsolute(repo)) throw new StackError("bad-repo", "the repository path must be absolute");
+  const enabled = readSettings(repo).enabledPlugins ?? {};
+  const names = marketplaceNames(env) ?? [...ALWAYS_ON, ...KNOWN_STACKS.map(stackPlugin)];
+  const plugins = names.map((name) => ({
+    name,
+    enabled: enabled[`${name}${SUFFIX}`] === true,
+    alwaysOn: ALWAYS_ON.includes(name),
+    stack: KNOWN_STACKS.find((s) => stackPlugin(s) === name) ?? null,
+    skills: skillsOf(name, env),
+  }));
+  return {
+    contractVersion: CONTRACT_VERSION,
+    stacks: KNOWN_STACKS.filter((s) => enabled[`${stackPlugin(s)}${SUFFIX}`] === true),
+    knownStacks: KNOWN_STACKS,
+    plugins,
+    manifestVerified: marketplaceNames(env) !== null,
+  };
+}
+
+/**
+ * The enabledPlugins block the write rules give for a selection.
+ *
+ * @param {object} current  the current enabledPlugins
+ * @param {string[]} args  stack arguments as a user types them (aliases allowed)
+ */
+export function plannedPlugins(current, args, env = process.env) {
+  const stacks = [...new Set(args.flatMap((a) => expandStackArg(a)))];
+  const unknown = args.filter((a) => !expandStackArg(a).length);
+  if (unknown.length) {
+    throw new StackError(
+      "unknown-stack",
+      `unknown stack ${unknown.join(", ")}; one of ${KNOWN_STACKS.join(" ")} mobile fullstack all`,
+    );
+  }
+  if (!stacks.length) {
+    throw new StackError("empty-selection", "no stack selected; nothing is changed");
+  }
+  const { plugins, dropped } = pluginsForStacks(stacks, {
+    manifestPath: join(
+      home(env),
+      ".claude",
+      "plugins",
+      "marketplaces",
+      PLUGIN_MARKETPLACE,
+      ".claude-plugin",
+      "marketplace.json",
+    ),
+  });
+  const next = {};
+  for (const [k, v] of Object.entries(current ?? {})) if (!RETIRED.test(k)) next[k] = v;
+  for (const s of KNOWN_STACKS) next[`${stackPlugin(s)}${SUFFIX}`] = false;
+  for (const p of plugins) next[`${p}${SUFFIX}`] = true;
+  for (const p of ALWAYS_ON) next[`${p}${SUFFIX}`] = true;
+  if (existsSync(join(home(env), ".claude", "xcode-apple-marketplace"))) {
+    next[XCODE_KEY] = stacks.includes("ios");
+  }
+  return { stacks, enabledPlugins: next, dropped };
+}
+
+/**
+ * Apply a selection to the repository's settings file.
+ *
+ * @returns {{contractVersion: string, stacks: string[], enabledPlugins: object,
+ *   changed: string[], dropped: string[], written: boolean}}
+ */
+export function stackSet(repo, args, { env = process.env, dryRun = false } = {}) {
+  if (!isAbsolute(repo)) throw new StackError("bad-repo", "the repository path must be absolute");
+  const doc = readSettings(repo);
+  const before = doc.enabledPlugins ?? {};
+  const plan = plannedPlugins(before, args, env);
+  const keys = new Set([...Object.keys(before), ...Object.keys(plan.enabledPlugins)]);
+  const changed = [...keys].filter((k) => before[k] !== plan.enabledPlugins[k]).sort();
+  if (!dryRun && changed.length) {
+    const p = settingsPath(repo);
+    mkdirSync(join(repo, ".claude"), { recursive: true });
+    const mode = existsSync(p) ? statSync(p).mode & 0o777 : 0o644;
+    const tmp = `${p}.${process.pid}.tmp`;
+    writeFileSync(
+      tmp,
+      JSON.stringify({ ...doc, enabledPlugins: plan.enabledPlugins }, null, 2) + "\n",
+    );
+    chmodSync(tmp, mode);
+    renameSync(tmp, p);
+  }
+  return {
+    contractVersion: CONTRACT_VERSION,
+    stacks: plan.stacks,
+    enabledPlugins: plan.enabledPlugins,
+    changed,
+    dropped: plan.dropped,
+    written: !dryRun && changed.length > 0,
+  };
+}
+
+function main(argv) {
+  const [mode, ...rest] = argv;
+  let repo = null;
+  let json = false;
+  let dryRun = false;
+  const stacks = [];
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === "--repo") repo = rest[++i];
+    else if (rest[i] === "--json") json = true;
+    else if (rest[i] === "--dry-run") dryRun = true;
+    else if (rest[i].startsWith("--")) return usage(`unknown argument ${rest[i]}`);
+    else stacks.push(rest[i]);
+  }
+  repo ??= process.cwd();
+  if (mode !== "status" && mode !== "set") return usage();
+  if (mode === "status" && stacks.length) return usage("status takes no stacks");
+  try {
+    const out = mode === "status" ? stackStatus(repo) : stackSet(repo, stacks, { dryRun });
+    if (json) process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+    else if (mode === "status") {
+      process.stdout.write(`stacks: ${out.stacks.join(" ") || "(none)"}\n`);
+      for (const p of out.plugins)
+        process.stdout.write(`  ${p.enabled ? "on " : "off"} ${p.name}\n`);
+    } else {
+      for (const d of out.dropped) process.stderr.write(`not in the marketplace, dropped: ${d}\n`);
+      process.stdout.write(JSON.stringify({ enabledPlugins: out.enabledPlugins }, null, 2) + "\n");
+    }
+    return 0;
+  } catch (err) {
+    if (err instanceof StackError) {
+      process.stderr.write(`stack-toggle: ${err.message}\n`);
+      return 1;
+    }
+    throw err;
+  }
+}
+
+function usage(why) {
+  if (why) process.stderr.write(`stack-toggle: ${why}\n`);
+  process.stderr.write(
+    "usage: stack-toggle.mjs status --repo <path> [--json] | set --repo <path> <stack>... [--json] [--dry-run]\n",
+  );
+  return 2;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  runMain("stack-toggle", () => {
+    process.exitCode = main(process.argv.slice(2));
+  });
+}

package/pipeline/scripts/steer-run.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * @file steer-run.mjs  -  queue one instruction for a running task, the writer
+ * behind `/multi-agent:steer` step 5 and POST /v1/runs/{id}/steer.
+ *
+ * The instruction is stored as `pendingSteer` in the run's agent-state.json
+ * through the state lock (gate-ledger.mjs updateState), never by editing the
+ * file, because the running task writes it too. The next phase reads it at its
+ * entry, applies it and sets `appliedAt` (multi-agent-refs/phases.md, "Phase
+ * entry - pending steer"). One instruction is queued at a time: a new one
+ * replaces an unconsumed one, and the replaced text is returned so the caller
+ * can show what was dropped.
+ *
+ * A finished run is refused: nothing would read the instruction.
+ *
+ * Usage:
+ *   steer-run.mjs <agent-state.json> --text <instruction>
+ *   steer-run.mjs <agent-state.json> --text-file <path>
+ *
+ * Stdout: one JSON line {contractVersion, queuedAt, replaced, status, currentPhase}.
+ * Exit: 0 queued, 1 refused, 2 usage.
+ *
+ * @module pipeline/scripts/steer-run
+ */
+
+import { readFileSync } from "node:fs";
+import { updateState } from "./gate-ledger.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+export const MAX_STEER_CHARS = 4000;
+const FINISHED = new Set(["complete", "completed", "done"]);
+
+export class SteerError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+/**
+ * Queue `text` on the run whose state file is `stateFile`.
+ *
+ * @returns {Promise<{contractVersion: string, queuedAt: string, replaced: string|null,
+ *   status: string|null, currentPhase: number|null}>}
+ */
+export async function queueSteer(stateFile, text) {
+  if (typeof text !== "string" || !text.trim()) {
+    throw new SteerError("empty", "the instruction is empty");
+  }
+  if (text.length > MAX_STEER_CHARS) {
+    throw new SteerError("too-long", `the instruction is over ${MAX_STEER_CHARS} characters`);
+  }
+  const queuedAt = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+  let replaced = null;
+  let status = null;
+  let currentPhase = null;
+  await updateState(stateFile, (s) => {
+    status = typeof s.status === "string" ? s.status : null;
+    currentPhase = Number.isFinite(Number(s.currentPhase)) ? Number(s.currentPhase) : null;
+    if (FINISHED.has(status)) {
+      throw new SteerError("finished", "the run is finished; nothing would read the instruction");
+    }
+    const prev = s.pendingSteer;
+    if (prev && typeof prev === "object" && !prev.appliedAt && typeof prev.text === "string") {
+      replaced = prev.text;
+    }
+    return { ...s, pendingSteer: { text, at: queuedAt, appliedAt: null, appliedPhase: null } };
+  });
+  return { contractVersion: CONTRACT_VERSION, queuedAt, replaced, status, currentPhase };
+}
+
+async function main(argv) {
+  const [file, flag, value, ...rest] = argv;
+  if (!file || rest.length || !value || (flag !== "--text" && flag !== "--text-file")) {
+    process.stderr.write(
+      "usage: steer-run.mjs <agent-state.json> --text <instruction> | --text-file <path>\n",
+    );
+    return 2;
+  }
+  const text = flag === "--text" ? value : readFileSync(value, "utf8");
+  try {
+    process.stdout.write(`${JSON.stringify(await queueSteer(file, text))}\n`);
+    return 0;
+  } catch (err) {
+    if (!(err instanceof SteerError) && err?.code !== "no-state") throw err;
+    process.stderr.write(`steer-run: ${err.message}\n`);
+    return 1;
+  }
+}
+
+if (invokedDirectly(import.meta.url)) {
+  runMain("steer-run", async () => {
+    process.exitCode = await main(process.argv.slice(2));
+  });
+}