@andromarces/agent-loops 0.2.2 → 0.3.0

package/src/install/commands.mjs

@@ -0,0 +1,268 @@
+// CLI commands for `agent-loop install`, `agent-loop uninstall`, and
+// `agent-loop harness-check` (#139). The installer is interactive when a TTY
+// is present; `--harness` and `--yes` make it scriptable, and tests always pass
+// `--harness`.
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { readArgValue } from "../lib/args.mjs";
+import { logError, logInfo, logInfoFull, logWarn, setVerbose } from "../lib/log.mjs";
+import { nearestHarness } from "../lib/process-ancestry.mjs";
+import { HARNESS_META, HARNESS_ORDER, isHarness } from "./harnesses.mjs";
+import { detectHarnesses, install, uninstall } from "./installer.mjs";
+import { readManifest, resolveHome } from "./manifest.mjs";
+
+const PACKAGE_ROOT = fileURLToPath(new URL("../../", import.meta.url));
+
+function parseHarnessList(value) {
+  const harnesses = [
+    ...new Set(
+      value
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean),
+    ),
+  ];
+  for (const harness of harnesses) {
+    if (!isHarness(harness)) {
+      throw new Error(`Unknown harness: ${harness}. Choose from ${HARNESS_ORDER.join(", ")}.`);
+    }
+  }
+  return harnesses;
+}
+
+function parseFlags(argv) {
+  const options = { harnesses: null, yes: false, dryRun: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--harness") {
+      options.harnesses = parseHarnessList(readArgValue(argv, arg, ++i));
+    } else if (arg === "--yes" || arg === "-y") {
+      options.yes = true;
+    } else if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (arg === "--verbose") {
+      options.verbose = true;
+    } else if (arg === "--help" || arg === "-h") {
+      options.help = true;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return options;
+}
+
+function resolveSelection(token, discovered) {
+  if (/^\d+$/.test(token)) {
+    const index = Number(token) - 1;
+    const harness = discovered[index];
+    if (!harness) {
+      throw new Error(`No harness at position ${token}.`);
+    }
+    return harness;
+  }
+  return parseHarnessList(token)[0];
+}
+
+async function selectHarnesses(discovered) {
+  const menu = HARNESS_ORDER.map((harness, index) => {
+    const marker = discovered.includes(harness) ? " [detected]" : "";
+    return `${index + 1}. ${HARNESS_META[harness].label} (${harness})${marker}`;
+  });
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (
+      await rl.question(
+        `\nSelect harnesses by number or name, comma-separated.\n${menu.join("\n")}\n` +
+          `Selection [${discovered.join(",") || "none"}]: `,
+      )
+    ).trim();
+    if (answer === "") {
+      return discovered;
+    }
+    return [
+      ...new Set(
+        answer
+          .split(",")
+          .map((part) => resolveSelection(part.trim(), discovered))
+          .filter(Boolean),
+      ),
+    ];
+  } finally {
+    rl.close();
+  }
+}
+
+function printReports(reports, dryRun) {
+  if (reports.length === 0) {
+    logInfo("Nothing to change.");
+    return;
+  }
+  for (const entry of reports) {
+    const prefix = dryRun ? "would " : "";
+    const detail = entry.detail ? ` (${entry.detail})` : "";
+    if (entry.action === "note") {
+      // Notes carry guidance past the 300-character log cap, so print them in
+      // full (#200).
+      logInfoFull(`${entry.harness}: ${entry.detail}`);
+      continue;
+    }
+    logInfo(`${entry.harness}: ${prefix}${entry.action} ${entry.path}${detail}`);
+    if (entry.snippet) {
+      console.log(entry.snippet);
+    }
+  }
+}
+
+export async function runInstallCommand(argv) {
+  let options;
+  try {
+    options = parseFlags(argv);
+  } catch (err) {
+    logError(err.message);
+    process.exitCode = 1;
+    return;
+  }
+  if (options.help) {
+    console.log(
+      [
+        "Usage: agent-loop install [--harness <list>] [--yes] [--dry-run]",
+        "",
+        `Harnesses: ${HARNESS_ORDER.join(", ")}`,
+        "Without --harness, detected CLIs are preselected in an interactive prompt.",
+      ].join("\n"),
+    );
+    return;
+  }
+  setVerbose(Boolean(options.verbose));
+
+  let harnesses = options.harnesses;
+  if (!harnesses) {
+    if (options.yes || !process.stdin.isTTY) {
+      logError("No --harness given and stdin is not interactive. Pass --harness <list>.");
+      process.exitCode = 1;
+      return;
+    }
+    harnesses = await selectHarnesses(await detectHarnesses());
+  }
+  if (!harnesses.length) {
+    logWarn("No harness selected; nothing to do.");
+    return;
+  }
+
+  let reports;
+  try {
+    reports = await install({
+      harnesses,
+      home: resolveHome(),
+      packageRoot: PACKAGE_ROOT,
+      dryRun: options.dryRun,
+    });
+  } catch (err) {
+    logError(err.path ? `${err.path}: ${err.message}` : err.message);
+    if (err.snippet) {
+      console.log(err.snippet);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  printReports(reports, options.dryRun);
+}
+
+export async function runUninstallCommand(argv) {
+  let options;
+  try {
+    options = parseFlags(argv);
+  } catch (err) {
+    logError(err.message);
+    process.exitCode = 1;
+    return;
+  }
+  if (options.help) {
+    console.log(
+      [
+        "Usage: agent-loop uninstall [--harness <list>] [--yes] [--dry-run]",
+        "",
+        "Without --harness, the harnesses recorded in the install manifest are removed.",
+      ].join("\n"),
+    );
+    return;
+  }
+  setVerbose(Boolean(options.verbose));
+
+  let harnesses = options.harnesses;
+  if (!harnesses && !options.yes && process.stdin.isTTY) {
+    let manifest;
+    try {
+      manifest = await readManifest(resolveHome());
+    } catch (err) {
+      logError(err.message);
+      process.exitCode = 1;
+      return;
+    }
+    const installed = HARNESS_ORDER.filter((harness) => manifest.harnesses[harness]);
+    if (installed.length === 0) {
+      logInfo("No harness is installed; nothing to remove.");
+      return;
+    }
+    harnesses = await selectHarnesses(installed);
+  }
+
+  let reports;
+  try {
+    reports = await uninstall({ harnesses, home: resolveHome(), dryRun: options.dryRun });
+  } catch (err) {
+    logError(err.message);
+    process.exitCode = 1;
+    return;
+  }
+  printReports(reports, options.dryRun);
+}
+
+const HARNESS_ALIASES = new Map([["agy", "antigravity"]]);
+
+/**
+ * Exit code for a harness mismatch: the named harness is not the nearest
+ * ancestor, so another harness owns the shell. Exit 0 means the names match;
+ * every other non-zero code means the check could not run, found no harness
+ * ancestor, or could not read the process ancestry. The distinct code lets a
+ * caller separate a genuine harness refusal from a check that did not decide
+ * (#151).
+ */
+export const HARNESS_MISMATCH_EXIT = 3;
+
+export async function runHarnessCheckCommand(argv, { lookup = nearestHarness } = {}) {
+  const requested = argv[0];
+  if (!requested) {
+    logError("harness-check requires a harness name.");
+    process.exitCode = 1;
+    return;
+  }
+  const harness = HARNESS_ALIASES.get(requested) ?? requested;
+  if (!isHarness(harness)) {
+    logError(`Unknown harness: ${requested}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  let found;
+  try {
+    found = await lookup();
+  } catch (err) {
+    logError(`could not read the process table: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (found === harness) {
+    process.exitCode = 0;
+    return;
+  }
+  if (found === null || found === undefined) {
+    logError(
+      `no known harness process was found above this shell, so not ${harness}. Not starting a run.`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  logError(`nearest harness ancestor is ${found}, not ${harness}. Refusing to start a run.`);
+  process.exitCode = HARNESS_MISMATCH_EXIT;
+}

package/src/install/fsutil.mjs

@@ -0,0 +1,159 @@
+// Filesystem and comparison helpers for the user-scope installer (#139).
+// Every write is atomic (temp file plus rename) and every hash is SHA-256 over
+// the UTF-8 bytes, so the manifest can prove equality with what it last wrote.
+import {
+  access,
+  chmod,
+  mkdir,
+  readFile,
+  rename,
+  rm,
+  rmdir,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+export { sha256 } from "../lib/hash.mjs";
+
+/** Reads a file as UTF-8; returns null when the path does not exist. */
+export async function readTextOrNull(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return null;
+    }
+    throw err;
+  }
+}
+
+export async function pathExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The permission bits of a file, or null when it does not exist. */
+export async function fileMode(path) {
+  try {
+    return (await stat(path)).mode & 0o777;
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return null;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Writes through a temp file in the same directory, then renames. Preserves the
+ * destination's permission bits unless `mode` is given, so a private settings
+ * file stays private after install, backup, and restore. The temp file is
+ * created with that mode, so it is never briefly world-readable.
+ */
+export async function writeTextAtomic(path, text, { mode } = {}) {
+  const temp = `${path}.${process.pid}.tmp`;
+  const targetMode = mode ?? (await fileMode(path));
+  await writeFile(temp, text, { encoding: "utf8", mode: targetMode ?? 0o666 });
+  if (targetMode !== null && process.platform !== "win32") {
+    await chmod(temp, targetMode);
+  }
+  await rename(temp, path);
+}
+
+export async function removeFileQuiet(path) {
+  await rm(path, { force: true });
+}
+
+/**
+ * Removes an empty directory. A missing directory and a non-empty directory
+ * throw nothing, including the EEXIST that some platforms report for a
+ * non-empty directory. Every other error, such as EPERM, EACCES, or EBUSY,
+ * reaches the caller so it can report the failure and retry later.
+ * @returns {Promise<boolean>} true when this call removed the directory
+ */
+export async function removeDirQuiet(path) {
+  try {
+    await rmdir(path);
+    return true;
+  } catch (err) {
+    if (err.code === "ENOENT" || err.code === "ENOTEMPTY" || err.code === "EEXIST") {
+      // A non-empty or already-removed directory needs no action.
+      return false;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Creates `dir` and every missing ancestor, recording each directory that did
+ * not exist before so uninstall can prune exactly what install created.
+ * @param {string} dir
+ * @param {Set<string>} created receives every newly created directory
+ */
+export async function ensureDir(dir, created) {
+  const missing = [];
+  let current = resolve(dir);
+  while (!(await pathExists(current))) {
+    missing.push(current);
+    const parent = dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+  if (missing.length === 0) {
+    return;
+  }
+  await mkdir(dir, { recursive: true });
+  // Record shallow to deep so uninstall can remove deepest first.
+  for (const path of missing.reverse()) {
+    created.add(path);
+  }
+}
+
+/**
+ * Removes empty directories, deepest first. Missing and non-empty entries are
+ * ignored; any other error propagates to the caller.
+ * @returns {Promise<string[]>} the directories this call removed
+ */
+export async function pruneEmptyDirs(dirs) {
+  const ordered = [...new Set(dirs)].sort((a, b) => b.length - a.length);
+  const removed = [];
+  for (const dir of ordered) {
+    if (await removeDirQuiet(dir)) {
+      removed.push(dir);
+    }
+  }
+  return removed;
+}
+
+/** Structural equality for JSON-shaped values. Object key order is irrelevant. */
+export function deepEqual(a, b) {
+  if (a === b) {
+    return true;
+  }
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) {
+      return false;
+    }
+    return a.every((value, index) => deepEqual(value, b[index]));
+  }
+  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") {
+    return false;
+  }
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) {
+    return false;
+  }
+  return keysA.every((key) => Object.hasOwn(b, key) && deepEqual(a[key], b[key]));
+}
+
+export function backupPathFor(path) {
+  return `${path}.agent-loops-backup`;
+}

package/src/install/harnesses.mjs

@@ -0,0 +1,170 @@
+// Harness registry for the installer (#139). Each harness declares the files it
+// creates and the one settings entry it owns, resolved against the installed
+// package, so `src/install/templates/` stays the only source of every entry
+// point and guard.
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+export const HARNESS_ORDER = ["claude", "codex", "opencode", "copilot", "antigravity"];
+
+export const HARNESS_META = {
+  claude: { label: "Claude Code", commands: ["claude"] },
+  codex: { label: "Codex CLI", commands: ["codex"] },
+  opencode: { label: "OpenCode", commands: ["opencode"] },
+  copilot: { label: "GitHub Copilot CLI", commands: ["copilot"] },
+  antigravity: { label: "Antigravity CLI", commands: ["agy", "antigravity"] },
+};
+
+export function isHarness(value) {
+  return Object.hasOwn(HARNESS_META, value);
+}
+
+function forwardSlashes(path) {
+  return path.replaceAll("\\", "/");
+}
+
+async function template(templateDir, ...segments) {
+  return readFile(join(templateDir, ...segments), "utf8");
+}
+
+function claudeEntry(guardPath) {
+  return {
+    matcher: "Edit|Write|MultiEdit|NotebookEdit",
+    hooks: [{ type: "command", command: `node "${guardPath}"`, timeout: 10 }],
+  };
+}
+
+function codexEntry(guardPath) {
+  return {
+    matcher: "^apply_patch$",
+    hooks: [
+      {
+        type: "command",
+        command: `node "${guardPath}"`,
+        timeout: 10,
+        statusMessage: "Checking parent orchestration guard",
+      },
+    ],
+  };
+}
+
+/**
+ * Builds the full target list for one harness.
+ * @param {string} harness
+ * @param {{ home: string, packageRoot: string, copilotHome?: string }} options
+ * @returns {Promise<{ files: Array<{path: string, content: string}>, settings: Array<{path: string, locator: object, entry: object}> }>}
+ */
+export async function buildTargets(harness, { home, packageRoot, copilotHome }) {
+  const templateDir = join(packageRoot, "src/install/templates");
+  const instructions = join(packageRoot, "docs/orchestrator-instructions.md");
+  const guardPath = join(packageRoot, "src/hook/parent-guard.mjs");
+  // The absolute invocation works from Git Bash and PowerShell alike, where the
+  // bare `agent-loop` command is absent or resolves only to a Windows `.cmd`
+  // shim. Bash does not resolve that shim, so a PATH lookup would report a
+  // missing command and the skill would misread it as a harness refusal (#151).
+  const cli = `node "${forwardSlashes(join(packageRoot, "src/cli.mjs"))}"`;
+  const files = [];
+  const settings = [];
+
+  const renderSkill = (text) =>
+    text
+      .replaceAll("{{AGENT_LOOP_INSTRUCTIONS}}", forwardSlashes(instructions))
+      .replaceAll("__AGENT_LOOP_CLI__", cli);
+
+  if (harness === "claude") {
+    const skill = await template(templateDir, "claude", "skills", "agent-loop", "SKILL.md");
+    files.push({
+      path: join(home, ".claude", "skills", "agent-loop", "SKILL.md"),
+      content: renderSkill(skill),
+    });
+    const entry = claudeEntry(guardPath);
+    settings.push({
+      path: join(home, ".claude", "settings.json"),
+      locator: {
+        kind: "array",
+        path: ["hooks", "PreToolUse"],
+        matcher: entry.matcher,
+      },
+      entry,
+    });
+  } else if (harness === "codex") {
+    const skill = await template(templateDir, "codex", "skills", "agent-loop", "SKILL.md");
+    files.push({
+      path: join(home, ".agents", "skills", "agent-loop", "SKILL.md"),
+      content: renderSkill(skill),
+    });
+    files.push({
+      path: join(home, ".agents", "skills", "agent-loop", "agents", "openai.yaml"),
+      content: await template(
+        templateDir,
+        "codex",
+        "skills",
+        "agent-loop",
+        "agents",
+        "openai.yaml",
+      ),
+    });
+    const entry = codexEntry(guardPath);
+    settings.push({
+      path: join(home, ".codex", "hooks.json"),
+      locator: {
+        kind: "array",
+        path: ["hooks", "PreToolUse"],
+        matcher: entry.matcher,
+      },
+      entry,
+    });
+  } else if (harness === "opencode") {
+    const plugin = await template(templateDir, "opencode", "plugins", "parent-guard.ts");
+    files.push({
+      path: join(home, ".config", "opencode", "plugins", "parent-guard.ts"),
+      content: renderSkill(plugin)
+        .replaceAll(
+          "__AGENT_LOOP_PLUGIN_URL__",
+          pathToFileURL(join(packageRoot, "src/hook/opencode-plugin.mjs")).href,
+        )
+        .replaceAll(
+          "__AGENT_LOOP_GUARD_URL__",
+          pathToFileURL(join(packageRoot, "src/hook/decision.mjs")).href,
+        ),
+    });
+  } else if (harness === "copilot") {
+    const hook = JSON.parse(await template(templateDir, "copilot", "hooks", "parent-guard.json"));
+    // Copilot consumes a flat permissionDecision object, so it runs its own
+    // guard script rather than the Claude/Codex hookSpecificOutput shape (#155).
+    hook.hooks.PreToolUse[0].args = [join(packageRoot, "src/hook/copilot-parent-guard.mjs")];
+    files.push({
+      path: join(copilotHome ?? join(home, ".copilot"), "hooks", "parent-guard.json"),
+      content: `${JSON.stringify(hook, null, 2)}\n`,
+    });
+  } else if (harness === "antigravity") {
+    const skill = await template(templateDir, "antigravity", "skills", "agent-loop", "SKILL.md");
+    files.push({
+      path: join(home, ".gemini", "antigravity-cli", "skills", "agent-loop", "SKILL.md"),
+      content: renderSkill(skill),
+    });
+    const shim = await template(
+      templateDir,
+      "antigravity",
+      "agent-loop-antigravity-parent-guard.mjs",
+    );
+    files.push({
+      path: join(home, ".gemini", "config", "agent-loop-antigravity-parent-guard.mjs"),
+      content: shim.replaceAll(
+        "__AGENT_LOOP_GUARD_URL__",
+        pathToFileURL(join(packageRoot, "src/hook/antigravity-parent-guard.mjs")).href,
+      ),
+    });
+    const group = JSON.parse(await template(templateDir, "antigravity", "hooks.json"));
+    settings.push({
+      path: join(home, ".gemini", "config", "hooks.json"),
+      locator: { kind: "key", key: "agent-loop-parent-guard" },
+      entry: group["agent-loop-parent-guard"],
+    });
+  } else {
+    throw new Error(`Unsupported harness: ${harness}`);
+  }
+
+  return { files, settings };
+}