@mnaimfaizy/agent-kit 1.0.0-alpha.12 → 1.0.0-beta.1

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

@@ -2,6 +2,8 @@
 // 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. */
@@ -12,6 +14,11 @@ 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) {
@@ -37,9 +44,12 @@ export function versionForTag(tag) {
   return tag.slice(1);
 }
 
-/** The `npx` command that upgrades to `tag`. */
-export function upgradeCommand(tag) {
-  const spec =
-    compareTags(tag, FIRST_NPM_TAG) >= 0 ? `${PACKAGE_NAME}@${versionForTag(tag)}` : PACKAGE_NAME;
-  return `npx ${spec} upgrade --tag ${tag}`;
+/**
+ * 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);
+}

package/src/upgrade.mjs

@@ -0,0 +1,288 @@
+// `agent-kit upgrade --tag vY`: move a Consumer from the tag its pins name to
+// vY. It replaces each Kit-owned path whole (delete, then copy from vY),
+// deletes paths only the old tag listed, rewrites the `@ref` of every
+// Agent-kit `uses:` pin, prints the examples/ diff for the Consumer to apply
+// by hand, and then runs doctor's file and pin checks.
+//
+// Plan first, then write: every file is read from the tag and every refusal
+// is checked before anything on disk changes, so a refusal never leaves a
+// half-upgraded checkout. It writes only local files.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PinRewriteError, readWorkflows, rewriteKitPins } from "./callers.mjs";
+import { checkPins } from "./checks/pins.mjs";
+import { fileAndPinChecks, printFileAndPinChecks } from "./doctor.mjs";
+import { firstLine } from "./exec.mjs";
+import { openKitRepo, PreManifestTagError, serverFromEnv } from "./kit-tag.mjs";
+import {
+  applyPlan,
+  checkDeletable,
+  checkLocalPath,
+  checkNoLinks,
+  kitFileWrites,
+  listed,
+  Refusal,
+  reportRefusal,
+  stageFileModes,
+  uncommittedChanges,
+} from "./local-writes.mjs";
+import { caseCollisions } from "./safe-paths.mjs";
+import { compareTags } from "./tags.mjs";
+
+const BOM = "\ufeff";
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+
+/** A workflow file's text, or a Refusal when it is not UTF-8 (rewriting it would corrupt it). */
+function readWorkflowText(root, path) {
+  // The Consumer's own file, rewritten in place: any name it has is fine.
+  checkNoLinks(root, path);
+  const raw = readFileSync(join(root, path));
+  try {
+    // TextDecoder drops a leading byte-order mark: keep it, so it is written back.
+    const hasBom = raw[0] === 0xef && raw[1] === 0xbb && raw[2] === 0xbf;
+    return (hasBom ? BOM : "") + utf8.decode(raw);
+  } catch {
+    throw new Refusal(`${path} is not valid UTF-8, so its pins cannot be rewritten safely.`);
+  }
+}
+
+/**
+ * Work out everything upgrade would do, reading every file it would write,
+ * and throw Refusal for anything that stops it. Touches nothing on disk.
+ */
+export function planUpgrade({ runner, root, oldSnap, newSnap, files, force, pinnedTag }) {
+  const newPaths = newSnap.kitOwnedPaths;
+  const removed = oldSnap.kitOwnedPaths.filter((p) => !newPaths.includes(p));
+  for (const snap of [newSnap, oldSnap]) {
+    const clash = caseCollisions(snap.kitOwnedPaths);
+    if (clash.length) {
+      throw new Refusal(
+        `${snap.tag}'s kit-owned-paths.txt lists paths that differ only in case: ${clash[0].join(" and ")}.`,
+      );
+    }
+  }
+
+  // Every path is deleted first; the new tag's paths are then copied fresh.
+  const deletes = [...newPaths, ...removed].map((p) => p.replace(/\/$/, ""));
+  for (const rel of deletes) checkDeletable(root, rel);
+  const writes = kitFileWrites(newSnap);
+  for (const w of writes) checkLocalPath(root, w.path, { deleted: deletes });
+
+  const pinEdits = [];
+  if (pinnedTag !== newSnap.tag) {
+    for (const file of files) {
+      if (file.pins.length === 0) continue;
+      const text = readWorkflowText(root, file.path);
+      let rewritten;
+      try {
+        rewritten = rewriteKitPins(text, newSnap.tag);
+      } catch (err) {
+        if (err instanceof PinRewriteError) throw new Refusal(`${file.path}: ${err.message}`);
+        throw err;
+      }
+      pinEdits.push({
+        path: file.path,
+        count: rewritten.count,
+        bytes: Buffer.from(rewritten.text, "utf8"),
+      });
+    }
+  }
+
+  const { changed: dirty, ignored } = uncommittedChanges({ runner, root, paths: deletes });
+  if (dirty.length && !force) {
+    throw new Refusal(
+      `${dirty.length} file(s) in the paths upgrade would replace or delete have uncommitted changes. ` +
+        `Commit or stash them, or run again with --force to discard them.`,
+      listed(dirty),
+    );
+  }
+
+  return { deletes, removed, writes, pinEdits, dirty, ignored };
+}
+
+/**
+ * @param {{
+ *   cwd: string,
+ *   runner: import("./exec.mjs").Runner,
+ *   tag: string,
+ *   from?: string,   // the tag being left, when the pins already name `tag`
+ *   force?: boolean,
+ *   yes?: boolean,
+ *   confirm?: ((question: string) => Promise<boolean>) | null,
+ *   out: (text: string) => void,
+ *   openRepo?: typeof openKitRepo,
+ *   env?: NodeJS.ProcessEnv,
+ * }} opts
+ * @returns {Promise<number>} exit code
+ */
+export async function runUpgrade({
+  cwd,
+  runner,
+  tag: newTag,
+  from,
+  force = false,
+  yes = false,
+  confirm = null,
+  out,
+  openRepo = openKitRepo,
+  env = process.env,
+}) {
+  const refuse = (err) => reportRefusal(out, err);
+
+  const top = runner("git", ["-C", cwd, "rev-parse", "--show-toplevel"]);
+  if (top.status !== 0) return refuse(new Refusal(`${cwd} is not a git repository.`));
+  const root = top.stdout.trim();
+
+  let workflows;
+  try {
+    workflows = readWorkflows(root);
+  } catch (err) {
+    return refuse(new Refusal(firstLine(err?.message ?? err)));
+  }
+  const pins = checkPins(workflows.files);
+  if (!pins.tag) {
+    return refuse(
+      new Refusal(
+        `upgrade needs every Agent-kit uses: pin to name the same Release-line tag: ${pins.result.summary}`,
+        pins.result.details,
+      ),
+    );
+  }
+  const pinnedTag = pins.tag;
+  if (from !== undefined && pinnedTag !== from && pinnedTag !== newTag) {
+    return refuse(
+      new Refusal(
+        `The pins name ${pinnedTag}, which is neither --from ${from} nor --tag ${newTag}.`,
+      ),
+    );
+  }
+  const oldTag = from ?? pinnedTag;
+  out(`Upgrading ${pins.repo} from ${oldTag} to ${newTag} in ${root}.`);
+  if (compareTags(newTag, oldTag) < 0) out(`Note: ${newTag} is older than ${oldTag}.`);
+
+  let kit;
+  try {
+    kit = openRepo({ runner, repo: pins.repo, serverUrl: serverFromEnv(env) });
+  } catch (err) {
+    return refuse(err);
+  }
+  try {
+    let oldSnap;
+    let newSnap;
+    let plan;
+    try {
+      oldSnap = kit.fetchTag(oldTag, { forDeletion: true });
+      newSnap = newTag === oldTag ? oldSnap : kit.fetchTag(newTag, { forDeletion: true });
+      plan = planUpgrade({
+        runner,
+        root,
+        oldSnap,
+        newSnap,
+        files: workflows.files,
+        force,
+        pinnedTag,
+      });
+    } catch (err) {
+      // PreManifestTagError gives the same message doctor prints.
+      if (err instanceof Refusal || err instanceof PreManifestTagError) return refuse(err);
+      return refuse(new Refusal(firstLine(err?.message ?? err)));
+    }
+
+    out("");
+    out(`Replace (delete, then copy from ${newTag}):`);
+    for (const p of newSnap.kitOwnedPaths) {
+      const n = plan.writes.filter((w) => w.path.startsWith(p)).length;
+      out(`  ${p} (${n} file${n === 1 ? "" : "s"})`);
+    }
+    if (plan.removed.length) {
+      out(`Delete (no longer in ${newTag}'s kit-owned-paths.txt):`);
+      for (const p of plan.removed) out(`  ${p}`);
+    }
+    if (plan.pinEdits.length) {
+      out(`Rewrite uses: pins to @${newTag}:`);
+      for (const e of plan.pinEdits) out(`  ${e.path} (${e.count} pin${e.count === 1 ? "" : "s"})`);
+    } else {
+      out(`The uses: pins already name ${newTag}.`);
+    }
+    if (plan.dirty.length) {
+      out(`--force: discarding uncommitted changes in ${plan.dirty.length} file(s):`);
+      for (const d of listed(plan.dirty)) out(`  ${d}`);
+    }
+    if (plan.ignored.length) {
+      out(`Also deleted: ${plan.ignored.length} ignored file(s) or folder(s) in those paths:`);
+      for (const d of listed(plan.ignored)) out(`  ${d}`);
+    }
+    out("");
+
+    if (!yes) {
+      if (!confirm) {
+        out("Not run: there is no terminal to confirm in. Run again with --yes to go ahead.");
+        return 2;
+      }
+      if (!(await confirm("Go ahead? [y/N] "))) {
+        out("Stopped. Nothing was changed.");
+        return 1;
+      }
+    }
+
+    try {
+      applyPlan(root, { deletes: plan.deletes, writes: plan.writes, rewrites: plan.pinEdits });
+    } catch (err) {
+      if (err instanceof Refusal) return refuse(err);
+      out(`FAILED  upgrade stopped part-way: ${firstLine(err?.message ?? err)}`);
+      out("      See `git status`; restore with `git checkout -- .` and `git clean` as needed.");
+      return 1;
+    }
+    out(
+      `Copied ${plan.writes.length} file(s) from ${newTag}` +
+        (plan.pinEdits.length ? ` and rewrote ${plan.pinEdits.length} workflow file(s).` : "."),
+    );
+    const note = stageFileModes({ runner, root, writes: plan.writes });
+    if (note) out(note);
+
+    out("");
+    if (oldTag === newTag) {
+      out(
+        `The pins already named ${newTag}, so there is no examples/ diff to show, and no path ` +
+          `only an older tag listed was deleted. If they were bumped from an older tag (by ` +
+          `Dependabot, say), run again with --from <that tag> to get both.`,
+      );
+    } else {
+      let diff = "";
+      try {
+        diff = kit.diff(oldSnap, newSnap, "examples/");
+      } catch (err) {
+        out(`Could not diff examples/: ${firstLine(err?.message ?? err)}`);
+      }
+      if (diff.trim()) {
+        out(
+          `examples/ changed between ${oldTag} and ${newTag}. Your Callers are yours: ` +
+            `apply what you need by hand.`,
+        );
+        // eslint-disable-next-line no-control-regex
+        if (/[\u0000-\u0009\u000b-\u001f]/.test(diff)) {
+          out(
+            "(Control characters, tabs and carriage returns included, are shown escaped as \\uXXXX.)",
+          );
+        }
+        out(diff.replace(/\n$/, ""));
+      } else {
+        out(`examples/ did not change between ${oldTag} and ${newTag}.`);
+      }
+    }
+
+    // The same file and pin checks as `doctor --ci`, against the tag already fetched.
+    out("");
+    const failed = printFileAndPinChecks(out, fileAndPinChecks({ runner, root, snap: newSnap }));
+    out("");
+    out(
+      failed
+        ? "Result: a check failed (exit 1)."
+        : "Result: done. Review `git status` and `git diff`, then commit the pins and the Kit-owned paths together.",
+    );
+    return failed ? 1 : 0;
+  } finally {
+    kit.cleanup();
+  }
+}