@mnaimfaizy/agent-kit 0.0.0-stage → 1.0.0-beta.1

package/src/local-writes.mjs

@@ -0,0 +1,307 @@
+// What `init` and `upgrade` share for changing a Consumer's checkout: path
+// checks, the uncommitted-changes check, reading Kit-owned files from a tag,
+// and carrying out a plan. Both commands plan first and write second: every
+// refusal (a Refusal) is raised while planning, before anything is written.
+
+import {
+  chmodSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { firstLine } from "./exec.mjs";
+import { EXECUTABLE_MODE } from "./kit-tag.mjs";
+import { fileModeIsOff, gitSafetyArgs } from "./local-tree.mjs";
+import { checkSafePath } from "./safe-paths.mjs";
+
+/** A reason not to start. Nothing has been written when this is thrown. */
+export class Refusal extends Error {
+  constructor(message, details = []) {
+    super(message);
+    this.details = details;
+  }
+}
+
+/** The most items a plan or a refusal lists before "…". */
+export const MAX_LISTED = 20;
+
+/** `items`, cut to MAX_LISTED with a closing "…" when there are more. */
+export function listed(items) {
+  return items.length > MAX_LISTED ? [...items.slice(0, MAX_LISTED), "…"] : items;
+}
+
+/** Print a refusal and its details; the exit code is 1. */
+export function reportRefusal(out, err) {
+  out(`REFUSED  ${err.message}`);
+  for (const d of err.details ?? []) out(`      ${d}`);
+  out("Nothing was changed.");
+  return 1;
+}
+
+export function lstatOrNull(path) {
+  try {
+    return lstatSync(path);
+  } catch (err) {
+    if (err.code === "ENOENT" || err.code === "ENOTDIR") return null;
+    throw err;
+  }
+}
+
+/**
+ * Refuse unless `rel` (a repository-relative path, no trailing slash) can be
+ * deleted and written without leaving `root`: it must be a safe path (the
+ * strict rules for names that come from a tag), no part of it may be a
+ * symbolic link or junction, and every existing parent must be a folder.
+ */
+export function checkLocalPath(root, rel, { deleted = [] } = {}) {
+  try {
+    checkSafePath(rel);
+  } catch (err) {
+    throw new Refusal(err.message);
+  }
+  checkNoLinks(root, rel, { deleted });
+}
+
+/**
+ * Refuse unless no part of `rel` is a symbolic link or junction and every
+ * existing parent is a folder. For the Consumer's own files, rewritten in
+ * place, whose names need not follow the strict tag rules.
+ *
+ * `deleted` lists folders the plan deletes before it writes: what is on disk
+ * inside them now (a file the new tag turns into a folder, say) is gone by
+ * the time `rel` is written, so the walk stops there.
+ */
+export function checkNoLinks(root, rel, { deleted = [] } = {}) {
+  const parts = rel.split("/");
+  for (let i = 1; i <= parts.length; i++) {
+    const sub = parts.slice(0, i).join("/");
+    if (deleted.includes(sub)) return;
+    const st = lstatOrNull(join(root, sub));
+    if (!st) return;
+    if (st.isSymbolicLink()) {
+      throw new Refusal(
+        `${sub} is a symbolic link or junction; the CLI does not delete or write through links. ` +
+          `Replace it with a plain folder or file, then run the command again.`,
+      );
+    }
+    if (i < parts.length && !st.isDirectory()) {
+      throw new Refusal(`${sub} is a file, but ${rel} needs it to be a folder.`);
+    }
+  }
+}
+
+/** Links inside `rel`: never followed or guessed at. */
+function linksUnder(root, rel) {
+  const found = [];
+  const walk = (sub) => {
+    const st = lstatOrNull(join(root, sub));
+    if (!st) return;
+    if (st.isSymbolicLink()) found.push(sub);
+    else if (st.isDirectory()) {
+      for (const name of readdirSync(join(root, sub)).sort()) walk(`${sub}/${name}`);
+    }
+  };
+  walk(rel);
+  return found;
+}
+
+/** Refuse unless folder `rel` can be deleted whole: checkLocalPath, and no link inside it. */
+export function checkDeletable(root, rel) {
+  checkLocalPath(root, rel);
+  const links = linksUnder(root, rel);
+  if (links.length) {
+    throw new Refusal(
+      `${rel}/ holds a symbolic link or junction, which the kit never ships: ${links[0]}. ` +
+        `Remove it by hand, then run the command again.`,
+    );
+  }
+}
+
+/** A temporary empty hooks folder and the safe git options for `root`; call done(). */
+function safeGit(runner, root) {
+  const tmp = mkdtempSync(join(tmpdir(), "agent-kit-git-"));
+  const noHooks = join(tmp, "no-hooks");
+  mkdirSync(noHooks);
+  try {
+    return {
+      args: ["-C", root, ...gitSafetyArgs({ runner, root, noHooks }), "--literal-pathspecs"],
+      done: () => rmSync(tmp, { recursive: true, force: true }),
+    };
+  } catch (err) {
+    rmSync(tmp, { recursive: true, force: true });
+    throw err;
+  }
+}
+
+/**
+ * Files under `paths` with uncommitted changes (modified, staged, deleted or
+ * untracked), as "XY path", and, apart, the ignored files and folders there
+ * (deleting the paths deletes those too). git runs no hooks, fsmonitor or
+ * filter drivers, and takes no optional locks.
+ *
+ * @returns {{ changed: string[], ignored: string[] }}
+ */
+export function uncommittedChanges({ runner, root, paths }) {
+  const git = safeGit(runner, root);
+  try {
+    const r = runner("git", [
+      ...git.args,
+      "--no-optional-locks",
+      "status",
+      "--porcelain=v1",
+      "-z",
+      "--untracked-files=all",
+      "--ignored=matching",
+      "--ignore-submodules=all",
+      "--no-renames",
+      "--",
+      ...paths,
+    ]);
+    if (r.status !== 0) throw new Refusal(`git status failed: ${firstLine(r.stderr)}`);
+    const entries = r.stdout.split("\0").filter(Boolean);
+    // git status cannot see local edits to files marked assume-unchanged
+    // (a lower-case tag) or skip-worktree (S): count those as changed.
+    const flagged = runner("git", [...git.args, "ls-files", "-v", "-z", "--", ...paths]);
+    if (flagged.status !== 0)
+      throw new Refusal(`git ls-files failed: ${firstLine(flagged.stderr)}`);
+    const hidden = flagged.stdout
+      .split("\0")
+      .filter((e) => /^(?:[a-z]|S) /.test(e))
+      .map(
+        (e) =>
+          `${e[0]} ${e.slice(2)} (marked ${e[0] === "S" ? "skip-worktree" : "assume-unchanged"})`,
+      );
+    return {
+      changed: [
+        ...entries
+          .filter((e) => !e.startsWith("!!"))
+          .map((e) => `${e.slice(0, 2).trim() || "?"} ${e.slice(3)}`),
+        ...hidden,
+      ],
+      ignored: entries.filter((e) => e.startsWith("!!")).map((e) => e.slice(3)),
+    };
+  } finally {
+    git.done();
+  }
+}
+
+/**
+ * Every file of every Kit-owned path at the tag, with its bytes, ready to
+ * write. Refuses a listed path with no files.
+ *
+ * @returns {{ path: string, mode: string, bytes: Buffer }[]}
+ */
+export function kitFileWrites(snap) {
+  const writes = [];
+  for (const path of snap.kitOwnedPaths) {
+    const listed = snap.listFiles(path);
+    if (listed.length === 0) {
+      throw new Refusal(
+        `${snap.tag}'s kit-owned-paths.txt lists ${path}, but the tag has no files there.`,
+      );
+    }
+    for (const f of listed) {
+      writes.push({ path: f.path, mode: f.mode, bytes: snap.readBlob(f.oid) });
+    }
+  }
+  return writes;
+}
+
+/**
+ * Carry out a plan: delete each folder in `deletes`, write each file in
+ * `writes` (paths from a tag), then each file in `rewrites` (the Consumer's
+ * own files, rewritten in place, whose names need not follow the tag rules).
+ * Only file-system errors can stop it part-way.
+ *
+ * @param {string} root
+ * @param {{ deletes?: string[], writes: { path: string, mode?: string, bytes: Buffer | string }[], rewrites?: { path: string, bytes: Buffer | string }[] }} plan
+ */
+export function applyPlan(root, { deletes = [], writes, rewrites = [] }) {
+  // Checked again here: time may have passed at the confirmation prompt.
+  for (const rel of deletes) checkDeletable(root, rel);
+  for (const w of writes) checkLocalPath(root, w.path, { deleted: deletes });
+  for (const w of rewrites) checkNoLinks(root, w.path);
+  for (const rel of deletes) rmSync(join(root, rel), { recursive: true, force: true });
+  for (const w of [...writes, ...rewrites]) {
+    const target = join(root, w.path);
+    mkdirSync(dirname(target), { recursive: true });
+    const executable = w.mode === EXECUTABLE_MODE;
+    writeFileSync(target, w.bytes, { mode: executable ? 0o755 : 0o644 });
+    if (executable) chmodSync(target, 0o755);
+  }
+}
+
+/**
+ * Without core.fileMode (the default on Windows) git cannot see an
+ * executable bit on disk, and `git add` keeps the mode the index already
+ * has (100644 for a new file). So stage the tag's mode: +x for each
+ * executable file written, and -x for each regular file the index still
+ * records as executable. Returns a line to print, or null when nothing was
+ * needed.
+ *
+ * @param {{ runner: import("./exec.mjs").Runner, root: string, writes: { path: string, mode?: string }[] }} opts
+ */
+export function stageFileModes({ runner, root, writes }) {
+  if (writes.length === 0 || !fileModeIsOff(runner, root)) return null;
+  const git = safeGit(runner, root);
+  try {
+    const failed = [];
+    const add = writes.filter((w) => w.mode === EXECUTABLE_MODE).map((w) => w.path);
+    const regular = writes.filter((w) => w.mode !== EXECUTABLE_MODE).map((w) => w.path);
+    const regularSet = new Set(regular);
+    const drop = [];
+    for (const batch of batches(regular)) {
+      const indexed = runner("git", [...git.args, "ls-files", "-s", "-z", "--", ...batch]);
+      if (indexed.status !== 0) {
+        failed.push(`--chmod=-x (git ls-files: ${firstLine(indexed.stderr)}): ${batch.join(", ")}`);
+        continue;
+      }
+      drop.push(
+        ...indexed.stdout
+          .split("\0")
+          .filter((e) => e.startsWith(`${EXECUTABLE_MODE} `))
+          .map((e) => e.slice(e.indexOf("\t") + 1))
+          .filter((f) => regularSet.has(f)),
+      );
+    }
+    for (const [flag, files] of [
+      ["--chmod=+x", add],
+      ["--chmod=-x", drop],
+    ]) {
+      for (const batch of batches(files)) {
+        // --sparse: a path outside a sparse-checkout cone is refused without
+        // it. git before 2.34 has no --sparse; it then gets a plain add.
+        let r = runner("git", [...git.args, "add", "--sparse", flag, "--", ...batch]);
+        if (r.status !== 0 && /unknown option|usage: git add/i.test(r.stderr)) {
+          r = runner("git", [...git.args, "add", flag, "--", ...batch]);
+        }
+        if (r.status !== 0) failed.push(`${flag} (${firstLine(r.stderr)}): ${batch.join(", ")}`);
+      }
+    }
+    if (failed.length) {
+      return (
+        "Could not stage the tag's file modes; after `git add`, run " +
+        `\`git update-index <flag> -- <file>\` for: ${failed.join("; ")}`
+      );
+    }
+    if (add.length + drop.length === 0) return null;
+    return (
+      `Staged the tag's file mode for ${add.length + drop.length} file(s) ` +
+      "(core.fileMode is off here, so git cannot see it on disk)."
+    );
+  } finally {
+    git.done();
+  }
+}
+
+/** Command-line-sized slices of a file list. */
+function batches(files, size = 200) {
+  const out = [];
+  for (let i = 0; i < files.length; i += size) out.push(files.slice(i, i + size));
+  return out;
+}

package/src/prompt.mjs

@@ -0,0 +1,42 @@
+// Questions on the terminal, with Node's built-in readline/promises (no
+// dependency). Only used when stdin and stdout are both a terminal; without
+// one, commands stop and name the flags to pass instead.
+
+import { createInterface } from "node:readline/promises";
+import { sanitizeLine } from "./checks/result.mjs";
+
+/**
+ * @param {{ input: NodeJS.ReadableStream & { isTTY?: boolean }, output: NodeJS.WritableStream & { isTTY?: boolean } }} streams
+ * @returns {((question: string) => Promise<string>) | null} null when there is no terminal
+ */
+export function terminalPrompt({ input, output }) {
+  if (!input.isTTY || !output.isTTY) return null;
+  // Ctrl-D (end of input) and Ctrl-C answer "" rather than throwing or
+  // ending the process, so the command stops cleanly ("Stopped. Nothing was
+  // changed.") and still removes its temporary repository.
+  return (question) =>
+    new Promise((resolve) => {
+      const rl = createInterface({ input, output, terminal: true });
+      let done = false;
+      const finish = (answer) => {
+        if (done) return;
+        done = true;
+        rl.close();
+        resolve(answer);
+      };
+      rl.on("close", () => finish(""));
+      rl.on("SIGINT", () => {
+        output.write("\n");
+        finish("");
+      });
+      rl.question(sanitizeLine(question)).then(
+        (answer) => finish(answer.trim()),
+        () => finish(""),
+      );
+    });
+}
+
+/** Ask a yes/no question; anything but y or yes is no. */
+export async function askYesNo(prompt, question) {
+  return /^(?:y|yes)$/i.test(await prompt(question));
+}

package/src/safe-paths.mjs

@@ -0,0 +1,68 @@
+// Rules for a repository-relative path the CLI writes or deletes in a
+// Consumer's checkout. A path read from a tag passes only if writing it is
+// safe on Linux, macOS and Windows alike: plain name characters, no `.` or
+// `..` segment, nothing git or Windows treats as special (`.git` in any case,
+// a trailing dot, a device name such as `nul`). `~` is not a name character,
+// so no 8.3 short name (`git~1`, `PROGRA~1`) can alias another folder.
+
+const SEGMENT = /^[A-Za-z0-9._-]+$/;
+const WINDOWS_DEVICE = /^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\..*)?$/i;
+
+export class UnsafePathError extends Error {}
+
+/** Why `segment` is unsafe, or null. */
+function segmentProblem(segment) {
+  if (!SEGMENT.test(segment)) return "has a character outside A-Z a-z 0-9 . _ -";
+  if (segment === "." || segment === "..") return "is a . or .. segment";
+  if (segment.toLowerCase() === ".git") return "names .git";
+  if (segment.endsWith(".")) return "ends with a dot, which Windows drops";
+  if (WINDOWS_DEVICE.test(segment)) return "is a Windows device name";
+  return null;
+}
+
+/**
+ * Throw UnsafePathError unless `path` (no leading or trailing slash) is safe
+ * to write or delete. Returns the path.
+ */
+export function checkSafePath(path, what = "path") {
+  const s = String(path);
+  if (s === "" || s.startsWith("/") || s.endsWith("/")) {
+    throw new UnsafePathError(`refusing ${what} ${JSON.stringify(s)}: not a relative file path`);
+  }
+  for (const segment of s.split("/")) {
+    const problem = segmentProblem(segment);
+    if (problem) {
+      throw new UnsafePathError(
+        `refusing ${what} ${JSON.stringify(s)}: ${JSON.stringify(segment)} ${problem}`,
+      );
+    }
+  }
+  return s;
+}
+
+/**
+ * Groups of paths that are the same file on a case-insensitive file system
+ * (Windows and macOS by default). Writing them would leave only one.
+ */
+export function caseCollisions(paths) {
+  const byKey = new Map();
+  for (const p of paths) {
+    const key = p.toLowerCase();
+    byKey.set(key, [...(byKey.get(key) ?? []), p]);
+  }
+  return [...byKey.values()].filter((group) => new Set(group).size > 1);
+}
+
+/** Every prefix that is also a file: `a` and `a/b` cannot both be files. */
+export function fileDirConflicts(paths) {
+  const lower = new Set(paths.map((p) => p.toLowerCase()));
+  const out = [];
+  for (const p of paths) {
+    const parts = p.split("/");
+    for (let i = 1; i < parts.length; i++) {
+      const prefix = parts.slice(0, i).join("/");
+      if (lower.has(prefix.toLowerCase())) out.push([prefix, p]);
+    }
+  }
+  return out;
+}

package/src/tags.mjs

@@ -0,0 +1,55 @@
+// Release-line tags: vX.Y.Z or vX.Y.Z-(alpha|beta|rc).N, the same shape
+// scripts/verify_release_snapshot.py accepts. The npm package version is the
+// tag without its leading v.
+
+import { readFileSync } from "node:fs";
+
+export const TAG_PATTERN = /^v(\d+)\.(\d+)\.(\d+)(?:-(alpha|beta|rc)\.(\d+))?$/;
+
+/** The first tag published to npm; older tags have no matching package version. */
+export const FIRST_NPM_TAG = "v1.0.0-alpha.12";
+
+/** The first tag that ships kit-owned-paths.txt. */
+export const FIRST_MANIFEST_TAG = "v1.0.0-alpha.11";
+
+export const PACKAGE_NAME = "@mnaimfaizy/agent-kit";
+
+/** The version of this CLI, from its package.json. */
+export const CLI_VERSION = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+).version;
+
+const STAGE_RANK = { alpha: 0, beta: 1, rc: 2, "": 3 };
+
+export function isReleaseTag(tag) {
+  return typeof tag === "string" && TAG_PATTERN.test(tag);
+}
+
+function key(tag) {
+  const m = TAG_PATTERN.exec(tag);
+  if (!m) throw new Error(`not a Release-line tag: ${tag}`);
+  return [Number(m[1]), Number(m[2]), Number(m[3]), STAGE_RANK[m[4] ?? ""], Number(m[5] ?? 0)];
+}
+
+/** Negative if a < b, 0 if equal, positive if a > b. */
+export function compareTags(a, b) {
+  const ka = key(a);
+  const kb = key(b);
+  for (let i = 0; i < ka.length; i++) if (ka[i] !== kb[i]) return ka[i] - kb[i];
+  return 0;
+}
+
+export function versionForTag(tag) {
+  key(tag);
+  return tag.slice(1);
+}
+
+/**
+ * The `npx` command that upgrades to `tag`: the npm version that matches the
+ * tag, or this CLI's version when the tag is older (an older package has no
+ * `upgrade`, and tags before FIRST_NPM_TAG have no package at all).
+ */
+export function upgradeCommand(tag, cliVersion = CLI_VERSION) {
+  const version = compareTags(tag, `v${cliVersion}`) >= 0 ? versionForTag(tag) : cliVersion;
+  return `npx ${PACKAGE_NAME}@${version} upgrade --tag ${tag}`;
+}

package/src/templates.mjs

@@ -0,0 +1,133 @@
+// The Caller templates `init` fills in: which example each flow copies, where
+// it lands, and the placeholders in it, each with the exact number of times
+// it must appear. A count that does not match means the tag's example
+// changed shape, and init fails loudly instead of writing a half-filled
+// Caller. scripts/example-placeholders-contract.test.mjs holds this
+// repository's examples to the same counts.
+
+export class TemplateError extends Error {}
+
+/** The two flows init sets up, keyed by the name `--flows` takes. */
+export const FLOWS = {
+  pipeline: {
+    example: "examples/plan-implement-review-caller.yml",
+    caller: ".github/workflows/agent-pipeline.yml",
+  },
+  audit: {
+    example: "examples/security-audit-caller.yml",
+    caller: ".github/workflows/security-audit.yml",
+  },
+};
+
+export const DEFAULT_THREAT_PACK_DIR = ".security";
+export const THREAT_PACK_FILES = ["threat-model.md", "findings-ledger.md"];
+
+const VERIFY_LINE =
+  /^( *)echo "Provide Consumer verify commands here \(lint\/tests\/typecheck\)\."$/gm;
+const SETUP_BLOCK = /^( *)# setup_commands: \|\n\1# {3}set -euo pipefail\n\1# {3}\.\.\.$/gm;
+const KIT_PIN =
+  /(\/agent-kit\/\.github\/workflows\/[A-Za-z0-9._-]+\.ya?ml)@v\d+\.\d+\.\d+(?:-(?:alpha|beta|rc)\.\d+)?(?=$|[\s"'#])/gm;
+
+const indentLines = (text, indent) =>
+  text
+    .split("\n")
+    .map((line) => (line ? indent + line : ""))
+    .join("\n");
+
+/**
+ * Each placeholder: what it matches, how many times per flow, and what it
+ * becomes. `values` is { actors, tag, defaultBranch, verify, preset,
+ * threatPackDir }; `preset` is the preset's text, or null to leave the
+ * commented block as it is.
+ */
+export const PLACEHOLDERS = [
+  {
+    name: "your-github-login",
+    pattern: /your-github-login/g,
+    counts: { pipeline: 4, audit: 1 },
+    replace: (v) => () => v.actors.join('","'),
+  },
+  {
+    name: "the @vX.Y.Z pin of each Agent-kit uses:",
+    pattern: KIT_PIN,
+    counts: { pipeline: 3, audit: 1 },
+    replace: (v) => (_, path) => `${path}@${v.tag}`,
+  },
+  {
+    name: '"main" (the default branch)',
+    pattern: /"main"/g,
+    counts: { pipeline: 2, audit: 0 },
+    replace: (v) => () => `"${v.defaultBranch}"`,
+  },
+  {
+    name: "the placeholder verify_commands echo line",
+    pattern: VERIFY_LINE,
+    counts: { pipeline: 1, audit: 0 },
+    replace: (v) => (_, indent) => indentLines(v.verify, indent),
+  },
+  {
+    name: "the commented `# setup_commands: |` block",
+    pattern: SETUP_BLOCK,
+    counts: { pipeline: 1, audit: 0 },
+    replace: (v) => (match, indent) =>
+      v.preset === null
+        ? match
+        : `${indent}setup_commands: |\n${indentLines(v.preset.replace(/\n+$/, ""), `${indent}  `)}`,
+  },
+  {
+    name: '".security/threat-model.md"',
+    pattern: /"\.security\/threat-model\.md"/g,
+    counts: { pipeline: 0, audit: 1 },
+    replace: (v) => () => `"${v.threatPackDir}/threat-model.md"`,
+  },
+  {
+    name: '".security/findings-ledger.md"',
+    pattern: /"\.security\/findings-ledger\.md"/g,
+    counts: { pipeline: 0, audit: 1 },
+    replace: (v) => () => `"${v.threatPackDir}/findings-ledger.md"`,
+  },
+];
+
+/** How many times each placeholder appears in `text`, by name. */
+export function placeholderCounts(text) {
+  return Object.fromEntries(
+    PLACEHOLDERS.map((p) => [p.name, [...String(text).matchAll(p.pattern)].length]),
+  );
+}
+
+/**
+ * Fill in the example for `flow`. Throws TemplateError, naming every
+ * placeholder whose count is wrong, before replacing anything.
+ */
+export function renderCaller(flow, text, values) {
+  const { example } = FLOWS[flow];
+  if (/\r/.test(text)) throw new TemplateError(`${example} has CR line endings`);
+  const found = placeholderCounts(text);
+  const wrong = PLACEHOLDERS.filter((p) => found[p.name] !== p.counts[flow]).map(
+    (p) => `${p.name}: expected ${p.counts[flow]}, found ${found[p.name]}`,
+  );
+  if (wrong.length) {
+    throw new TemplateError(
+      `${example} does not have the placeholders this CLI fills in (${wrong.join("; ")}). ` +
+        "Use the CLI version that matches the tag, or copy the example by hand.",
+    );
+  }
+  // One pass over the original text: a value written for one placeholder
+  // (an actor called main, say) is never matched by a later one.
+  const edits = PLACEHOLDERS.filter((p) => p.counts[flow] > 0).flatMap((p) =>
+    [...text.matchAll(p.pattern)].map((m) => ({
+      start: m.index,
+      end: m.index + m[0].length,
+      text: p.replace(values)(...m),
+    })),
+  );
+  edits.sort((a, b) => a.start - b.start);
+  let out = "";
+  let at = 0;
+  for (const e of edits) {
+    if (e.start < at) throw new TemplateError(`${example}: two placeholders overlap`);
+    out += text.slice(at, e.start) + e.text;
+    at = e.end;
+  }
+  return out + text.slice(at);
+}