AgentHub/server/lib/lane-agents.js

/**
 * @file Installs a `claude` lane's driving instructions: the
 * ship-feature-lane pipeline's agent templates
 * (qc-local, senior-gate-reviewer) into a lane's own .claude/agents/, so a
 * driving session can launch them by the BARE subagent_type name. Source is
 * the repo's own `agents/` — the same files the agenthub plugin ships, where
 * they resolve as `agenthub:qc-local`; installing them into the lane is what
 * makes the unprefixed name work there too. Plain file I/O except
 * for one git call — resolving where a worktree lane's shared info/exclude
 * actually lives, the same git-dir/git-common-dir distinction E2's
 * lane-sync.js had to get right for info/attributes.
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */

const fs = require("node:fs");
const path = require("node:path");
const { git } = require("./worktree");

const TEMPLATE_DIR = path.join(__dirname, "..", "..", "agents");
const TEMPLATE_FILES = ["qc-local.md", "senior-gate-reviewer.md"];
const EXCLUDE_LINE = ".claude/agents/";

// The block older builds wrote into a codex lane's AGENTS.md. Codex lanes no
// longer carry a pipeline, so `removeStageDoc` takes it back out.
const STAGE_BLOCK_START = "<!-- agenthub:stage:start -->";
const STAGE_BLOCK_END = "<!-- agenthub:stage:end -->";

/**
 * Remove AgentHub's stage block from `<cwd>/AGENTS.md`, leaving every other
 * line as it was. A file left with nothing else in it was AgentHub's own
 * creation, so it is deleted. Never throws.
 *
 * @returns {boolean} whether the file changed
 */
function removeStageDoc(cwd) {
  const file = path.join(cwd, "AGENTS.md");
  try {
    const doc = fs.readFileSync(file, "utf8");
    const start = doc.indexOf(STAGE_BLOCK_START);
    const end = doc.indexOf(STAGE_BLOCK_END, start);
    if (start === -1 || end === -1) return false;
    const rest = (
      doc.slice(0, start).trimEnd() +
      "\n\n" +
      doc.slice(end + STAGE_BLOCK_END.length).trimStart()
    ).trim();
    if (rest) fs.writeFileSync(file, `${rest}\n`);
    else fs.rmSync(file);
    return true;
  } catch {
    return false; // no file, or unreadable — nothing of ours to take out
  }
}

/** The dir shared across every worktree of a repo — where info/exclude
 *  lives (same as info/attributes; MERGE_HEAD/HEAD/the index are the only
 *  per-worktree-private state, not this). */
async function commonGitDir(cwd) {
  const result = await git(cwd, ["rev-parse", "--git-common-dir"]);
  const dir = result.stdout.trim();
  return path.isAbsolute(dir) ? dir : path.join(cwd, dir);
}

/**
 * Copy both agent templates into `<lane.cwd>/.claude/agents/` (overwriting
 * any existing copy — this is a reinstall, not a merge) and idempotently
 * git-exclude that directory in the shared common git dir.
 *
 * A `codex` or `antigravity` lane gets nothing: neither CLI reads
 * `.claude/agents/`, and those lanes carry no pipeline to drive.
 *
 * @param {{cwd: string, tool?: string}} lane
 * @returns {Promise<{installed: string[]}>}
 */
async function installAgents(lane) {
  if (!fs.existsSync(path.join(lane.cwd, ".git"))) {
    throw Object.assign(new Error(`lane has no .git — not a git repository: ${lane.cwd}`), {
      code: "ENOTGITREPO",
    });
  }

  if (lane.tool && lane.tool !== "claude") return { installed: [] };

  const dest = path.join(lane.cwd, ".claude", "agents");
  fs.mkdirSync(dest, { recursive: true });
  const installed = [];
  for (const name of TEMPLATE_FILES) {
    fs.copyFileSync(path.join(TEMPLATE_DIR, name), path.join(dest, name));
    installed.push(name);
  }

  const infoDir = path.join(await commonGitDir(lane.cwd), "info");
  fs.mkdirSync(infoDir, { recursive: true });
  const excludePath = path.join(infoDir, "exclude");
  const existing = fs.existsSync(excludePath) ? fs.readFileSync(excludePath, "utf8") : "";
  const lines = existing.split("\n").filter(Boolean);
  if (!lines.includes(EXCLUDE_LINE)) {
    lines.push(EXCLUDE_LINE);
    fs.writeFileSync(excludePath, lines.join("\n") + "\n");
  }

  return { installed };
}

module.exports = { installAgents, removeStageDoc };