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

package/README.md

@@ -1,19 +1,22 @@
 # @mnaimfaizy/agent-kit
 
-The command-line companion to [Agent-kit](https://github.com/mnaimfaizy/agent-kit): checks a Consumer repository against the Agent-kit tag its Callers pin.
+The command-line companion to [Agent-kit](https://github.com/mnaimfaizy/agent-kit): adopts Agent-kit in a Consumer repository, checks it against the Agent-kit tag its Callers pin, and upgrades it to another tag.
 
 ```bash
-npx @mnaimfaizy/agent-kit doctor            # local run with your own gh login
-npx @mnaimfaizy/agent-kit doctor --ci       # Kit-owned paths and pins only
-npx @mnaimfaizy/agent-kit doctor --strict   # warnings fail too
+npx @mnaimfaizy/agent-kit init --tag <tag>          # first adoption (asks first)
+npx @mnaimfaizy/agent-kit doctor                    # local run with your own gh login
+npx @mnaimfaizy/agent-kit doctor --ci               # Kit-owned paths and pins only
+npx @mnaimfaizy/agent-kit doctor --strict           # warnings fail too
+npx @mnaimfaizy/agent-kit upgrade --tag <new-tag>   # move to another tag (asks first)
 ```
 
 - The package holds only code. Kit files are read from the git tag your `uses:` pins name, never bundled.
 - `doctor` is read-only. It runs git in your checkout without hooks or configured filter commands, never changes files or GitHub settings, and for anything to fix prints a POSIX-shell `gh` command for you to run.
 - No runtime dependencies. Needs Node.js 22 or later, `git`, and (outside `--ci`) `gh` logged in with admin on the repository.
 - Tags before `v1.0.0-alpha.11` have no `kit-owned-paths.txt`, and the CLI refuses them: adopt those by hand with that tag's `docs/adopt.md`.
-- `init` and `upgrade` are not in this version yet.
+- `upgrade --tag <vY>` reads the current tag from your Agent-kit `uses:` pins (they must agree), replaces each Kit-owned path vY lists (delete, then copy), deletes paths only the old tag listed, rewrites only the `@<tag>` of those pins, prints the `examples/` diff between the two tags for you to apply by hand, and then runs the `doctor --ci` checks. Every refusal is checked before anything is written. It refuses a path with uncommitted changes unless `--force`, refuses symbolic links in or above a Kit-owned path, and copies only regular and executable files from the tag. Ignored files inside a replaced path are deleted with it, and listed first. After a Dependabot pin bump, when the pins already name vY, add `--from <vX>` to also delete paths only vX listed and see the `examples/` diff. It asks before writing; pass `--yes` when there is no terminal. It writes only local files and commits nothing; where `core.fileMode` is off (Windows), it stages each copied file with the tag's mode (`git add --chmod=+x` or `-x`), so the executable bit is neither lost nor kept by mistake.
+- `init --tag <vX>` copies the Kit-owned paths, writes `.github/workflows/agent-pipeline.yml` and/or `security-audit.yml` from the tag's `examples/` with your answers filled in (`--flows`, `--actors`, `--default-branch`, `--verify`, `--preset`), writes the Threat pack skeleton to `.security/` (or `--threat-pack-dir`) and `.github/dependabot.yml` if there is none, and prints the GitHub-side steps as `gh` commands. It refuses to overwrite an existing Caller or Kit-owned path without `--force`, never overwrites an existing Threat pack file, and leaves Kit-owned paths that already match the tag alone (so `init --flows audit` later adds that flow); use `upgrade` to change tags. `--yes` asks nothing.
 
-The package version matches the Agent-kit Release line: `@mnaimfaizy/agent-kit@1.0.0-alpha.12` is published from tag `v1.0.0-alpha.12`, with npm provenance.
+The package version matches the Agent-kit Release line: `@mnaimfaizy/agent-kit@1.0.0-beta.1` is published from tag `v1.0.0-beta.1`, with npm provenance.
 
 Full documentation: [Getting started](https://github.com/mnaimfaizy/agent-kit/blob/main/docs/getting-started.md) and [Adopt](https://github.com/mnaimfaizy/agent-kit/blob/main/docs/adopt.md#check-an-adoption-with-doctor).

package/bin/agent-kit.mjs

@@ -3,9 +3,11 @@
 // repository. It writes only local files and never changes GitHub settings.
 
 import { main } from "../src/cli.mjs";
+import { terminalPrompt } from "../src/prompt.mjs";
 
-process.exitCode = main(process.argv.slice(2), {
+process.exitCode = await main(process.argv.slice(2), {
   cwd: process.cwd(),
   stdout: (s) => process.stdout.write(`${s}\n`),
   stderr: (s) => process.stderr.write(`${s}\n`),
+  prompt: terminalPrompt({ input: process.stdin, output: process.stdout }),
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnaimfaizy/agent-kit",
-  "version": "1.0.0-alpha.12",
+  "version": "1.0.0-beta.1",
   "description": "Adopt, upgrade and check Agent-kit in a Consumer repository. Reads kit files from the pinned git tag.",
   "license": "MIT",
   "type": "module",

package/src/callers.mjs

@@ -58,6 +58,44 @@ export function findKitPins(text) {
   return pins;
 }
 
+export class PinRewriteError extends Error {}
+
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * Point every Agent-kit `uses:` pin in `text` at `newRef`. Only the `@ref`
+ * of each pin line changes: every other byte of the file, the line endings
+ * and a byte-order mark included, stays as it was. Throws PinRewriteError
+ * when a pin line cannot be rewritten unambiguously.
+ *
+ * @returns {{ text: string, count: number }}
+ */
+export function rewriteKitPins(text, newRef) {
+  const pins = findKitPins(text);
+  if (pins.length === 0) return { text, count: 0 };
+  // Split the raw text the way findKitPins numbers lines (\r\n, \r or \n),
+  // keeping each separator so the file is rebuilt byte for byte.
+  const parts = String(text).split(/(\r\n|\r|\n)/);
+  let count = 0;
+  for (const pin of pins) {
+    const idx = (pin.line - 1) * 2;
+    const line = parts[idx];
+    const re = new RegExp(
+      `(/${escapeRegExp(pin.file)}@)${escapeRegExp(pin.ref)}(?=$|[\\s"'#])`,
+      "g",
+    );
+    const matches = [...line.matchAll(re)];
+    if (matches.length !== 1) {
+      throw new PinRewriteError(
+        `line ${pin.line}: cannot find exactly one ${pin.file}@${pin.ref} to rewrite`,
+      );
+    }
+    parts[idx] = line.replace(re, (_, prefix) => `${prefix}${newRef}`);
+    if (parts[idx] !== line) count++;
+  }
+  return { text: parts.join(""), count };
+}
+
 function lines(text) {
   return stripBom(String(text))
     .replace(/\r\n?/g, "\n")

package/src/checks/kit-owned-trees.mjs

@@ -64,8 +64,8 @@ export function checkKitOwnedTrees({ runner, cwd, snapshot }) {
         ...howCompared,
         `Kit-owned paths are replaced whole from the tag your pins name, never edited.`,
         `If a pin bump (for example from Dependabot) moved the pins to ${tag}, re-copy them on the same branch.`,
-        `The command below needs \`upgrade\`, which ships in a later release; until then, ` +
-          `delete and re-copy each path by hand as ${manualCopyUrl(repo, tag, serverUrl)} describes.`,
+        `Run the command below, or delete and re-copy each path by hand as ` +
+          `${manualCopyUrl(repo, tag, serverUrl)} describes.`,
       ],
       fix: [upgradeCommand(tag)],
     },

package/src/checks/result.mjs

@@ -47,8 +47,14 @@ export function byHand(what, value) {
   return `fix by hand: ${what} ${JSON.stringify(String(value))} (not printed as a command)`;
 }
 
-// C0 and C1 controls, DEL, and the Unicode line and paragraph separators.
-const CONTROL = new RegExp("[\u0000-\u001f\u007f-\u009f\u2028\u2029]", "g");
+// C0 and C1 controls, DEL, the Unicode line and paragraph separators, and the
+// invisible and bidirectional formatting characters that can make printed
+// text read differently from what it is (zero-width, LRM/RLM, embeddings,
+// overrides and isolates).
+const CONTROL = new RegExp(
+  "[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2066-\u2069\ufeff]",
+  "g",
+);
 
 /**
  * Make one output line safe for a terminal and for a CI log: escape control

package/src/cli.mjs

@@ -1,21 +1,30 @@
 // Argument parsing and dispatch. Exit codes: 0 ok, 1 a check failed (or a
-// warning under --strict, or the tag was refused), 2 usage error.
+// warning under --strict, or the tag or the change was refused), 2 usage
+// error (including a missing answer when there is no terminal to ask on).
 
-import { readFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 import { formatReport, runDoctor } from "./doctor.mjs";
 import { REPO_PATTERN, sanitizeLine } from "./checks/result.mjs";
 import { systemRunner } from "./exec.mjs";
+import { askYesNo } from "./prompt.mjs";
+import { CLI_VERSION, isReleaseTag } from "./tags.mjs";
+import { runInit } from "./init.mjs";
+import { runUpgrade } from "./upgrade.mjs";
 
-export const VERSION = JSON.parse(
-  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
-).version;
+export const VERSION = CLI_VERSION;
 
 const USAGE = `Usage: agent-kit <command> [options]
 
 Commands:
+  init       Adopt Agent-kit from a tag: copy the Kit-owned paths, write a
+             Caller per flow with your answers filled in, the Threat pack
+             skeleton and .github/dependabot.yml, then print the GitHub-side
+             steps as gh commands. Local files only.
   doctor     Read-only checks of this repository against the Agent-kit tag
              its Callers pin. Never changes anything.
+  upgrade    Move this repository to another Agent-kit tag: replace the
+             Kit-owned paths, rewrite the uses: pins, print the examples/
+             diff, then run doctor's file and pin checks. Local files only.
 
 Options for doctor:
   --ci            Check only Kit-owned paths and uses: pins (no gh needed).
@@ -24,19 +33,64 @@ Options for doctor:
   --repo <o/r>    The GitHub repository to check (default: gh's choice for
                   the current directory).
 
+Options for init (each one is asked for when missing, on a terminal):
+  --tag <vX>              The Agent-kit tag to adopt.
+  --flows <list>          pipeline, audit, or both (comma-separated).
+  --actors <logins>       GitHub logins allowed to trigger runs.
+  --default-branch <b>    Default branch (default: origin's HEAD, else main).
+  --verify <commands>     verify_commands for implement (pipeline). In a
+                          prompt, \\n separates commands.
+  --preset <name|none>    Inline examples/setup-presets/<name>.sh as
+                          setup_commands (pipeline; default none).
+  --threat-pack-dir <d>   Where the Threat pack goes (audit; default .security).
+  --yes                   Ask nothing; every answer comes from flags.
+  --force                 Overwrite existing Callers, Threat pack files and
+                          Kit-owned paths (use upgrade to change tags).
+
+Options for upgrade:
+  --tag <vY>      The Agent-kit tag to move to (asked for when missing).
+  --from <vX>     The tag you are leaving, when the pins already name <vY>
+                  (after a Dependabot bump): deletes paths only <vX> listed
+                  and prints the examples/ diff.
+  --yes           Do not ask before changing files.
+  --force         Replace Kit-owned paths even when they have uncommitted
+                  changes (those changes are lost).
+
   -h, --help      Show this help.
-  -v, --version   Show the version.
+  -v, --version   Show the version.`;
 
-init and upgrade are not available yet.`;
+const COMMAND_OPTIONS = {
+  doctor: ["ci", "strict", "repo"],
+  init: [
+    "tag",
+    "flows",
+    "actors",
+    "default-branch",
+    "verify",
+    "preset",
+    "threat-pack-dir",
+    "yes",
+    "force",
+  ],
+  upgrade: ["tag", "from", "yes", "force"],
+};
 
 /**
  * @param {string[]} argv
- * @param {{ cwd: string, stdout: (s: string) => void, stderr: (s: string) => void, runner?: import("./exec.mjs").Runner, openTag?: Function }} io
- * @returns {number} exit code
+ * @param {{
+ *   cwd: string,
+ *   stdout: (s: string) => void,
+ *   stderr: (s: string) => void,
+ *   runner?: import("./exec.mjs").Runner,
+ *   openTag?: Function,
+ *   openRepo?: Function,
+ *   prompt?: ((question: string) => Promise<string>) | null,
+ * }} io  `prompt` is null (or absent) when there is no terminal to ask on.
+ * @returns {Promise<number>} exit code
  */
-export function main(argv, io) {
-  const { cwd, runner = systemRunner, openTag } = io;
-  // Anything doctor prints can echo its arguments or file contents: sanitize every line.
+export async function main(argv, io) {
+  const { cwd, runner = systemRunner, openTag, openRepo, prompt = null } = io;
+  // Anything printed can echo arguments or file contents: sanitize every line.
   const clean = (text) => String(text).split("\n").map(sanitizeLine).join("\n");
   const stdout = (text) => io.stdout(clean(text));
   const stderr = (text) => io.stderr(clean(text));
@@ -50,6 +104,16 @@ export function main(argv, io) {
         ci: { type: "boolean" },
         strict: { type: "boolean" },
         repo: { type: "string" },
+        tag: { type: "string" },
+        from: { type: "string" },
+        flows: { type: "string" },
+        actors: { type: "string" },
+        "default-branch": { type: "string" },
+        verify: { type: "string" },
+        preset: { type: "string" },
+        "threat-pack-dir": { type: "string" },
+        yes: { type: "boolean", short: "y" },
+        force: { type: "boolean" },
         help: { type: "boolean", short: "h" },
         version: { type: "boolean", short: "v" },
       },
@@ -68,18 +132,49 @@ export function main(argv, io) {
     (command || values.help ? stdout : stderr)(USAGE);
     return values.help ? 0 : 2;
   }
-  if (command === "init" || command === "upgrade") {
-    stderr(`agent-kit ${command} is not available in ${VERSION} yet; it ships in a later release.`);
-    return 2;
-  }
-  if (command !== "doctor") {
+  if (!(command in COMMAND_OPTIONS)) {
     stderr(`Unknown command: ${command}\n\n${USAGE}`);
     return 2;
   }
   if (rest.length) {
-    stderr(`doctor takes no arguments, got: ${rest.join(" ")}`);
+    stderr(`${command} takes no arguments, got: ${rest.join(" ")}`);
+    return 2;
+  }
+  const foreign = Object.keys(values).filter(
+    (k) => k !== "help" && k !== "version" && !COMMAND_OPTIONS[command].includes(k),
+  );
+  if (foreign.length) {
+    stderr(`${command} does not take ${foreign.map((k) => `--${k}`).join(", ")}\n\n${USAGE}`);
     return 2;
   }
+
+  if (command === "init") {
+    stdout(`agent-kit init ${VERSION}`);
+    return runInit({
+      cwd,
+      runner,
+      flags: {
+        tag: values.tag,
+        flows: values.flows,
+        actors: values.actors,
+        defaultBranch: values["default-branch"],
+        verify: values.verify,
+        preset: values.preset,
+        threatPackDir: values["threat-pack-dir"],
+      },
+      force: Boolean(values.force),
+      yes: Boolean(values.yes),
+      prompt,
+      confirm: prompt ? (q) => askYesNo(prompt, q) : null,
+      out: stdout,
+      err: stderr,
+      ...(openTag ? { openTag } : {}),
+    });
+  }
+  if (command === "upgrade") {
+    return upgrade(values, { cwd, runner, openRepo, prompt, stdout, stderr });
+  }
+
   if (values.repo !== undefined && !REPO_PATTERN.test(values.repo)) {
     stderr(`--repo must be owner/name, got: ${JSON.stringify(values.repo)}`);
     return 2;
@@ -95,3 +190,40 @@ export function main(argv, io) {
   stdout(formatReport(report, { version: VERSION }));
   return report.exitCode;
 }
+
+async function upgrade(values, { cwd, runner, openRepo, prompt, stdout, stderr }) {
+  if (!prompt) {
+    // No terminal: every answer must come from a flag.
+    const needed = [];
+    if (values.tag === undefined) needed.push("--tag <vY>");
+    if (!values.yes) needed.push("--yes");
+    if (needed.length) {
+      stderr(`agent-kit upgrade: there is no terminal to ask on, so pass ${needed.join(" and ")}.`);
+      return 2;
+    }
+  }
+  let tag = values.tag;
+  if (tag === undefined) tag = await prompt("Agent-kit tag to upgrade to (for example v1.0.0): ");
+  if (values.from !== undefined && !isReleaseTag(values.from)) {
+    stderr(`--from must be a Release-line tag, got: ${JSON.stringify(values.from)}`);
+    return 2;
+  }
+  if (!isReleaseTag(tag)) {
+    stderr(
+      `--tag must be a Release-line tag (vX.Y.Z or vX.Y.Z-stage.N), got: ${JSON.stringify(tag)}`,
+    );
+    return 2;
+  }
+  stdout(`agent-kit upgrade ${VERSION}`);
+  return runUpgrade({
+    cwd,
+    runner,
+    tag,
+    from: values.from,
+    force: Boolean(values.force),
+    yes: Boolean(values.yes),
+    confirm: prompt ? (q) => askYesNo(prompt, q) : null,
+    out: stdout,
+    ...(openRepo ? { openRepo } : {}),
+  });
+}

package/src/doctor.mjs

@@ -24,9 +24,7 @@ import {
 } from "./checks/secrets-and-variables.mjs";
 import { firstLine } from "./exec.mjs";
 import { createGitHub } from "./github.mjs";
-import { DEFAULT_SERVER, openKitTag, PreManifestTagError } from "./kit-tag.mjs";
-
-const SERVER = /^https:\/\/[A-Za-z0-9.-]+(?::\d+)?$/;
+import { openKitTag, PreManifestTagError, serverFromEnv } from "./kit-tag.mjs";
 
 /**
  * The GitHub server the pins resolve on: the repository's host in a local
@@ -35,8 +33,7 @@ const SERVER = /^https:\/\/[A-Za-z0-9.-]+(?::\d+)?$/;
  */
 function serverFor(info, env) {
   if (info?.host) return `https://${info.host}`;
-  const fromEnv = String(env.GITHUB_SERVER_URL ?? "").replace(/\/$/, "");
-  return SERVER.test(fromEnv) ? fromEnv : DEFAULT_SERVER;
+  return serverFromEnv(env);
 }
 
 /** The checks that need a `gh` login with admin on the repository. */
@@ -358,7 +355,7 @@ function formatLines(report, { version } = {}) {
   return lines;
 }
 
-function formatResult(r) {
+export function formatResult(r) {
   const out = [
     `${LABEL[r.status]}  ${r.title}: ${r.summary}${r.strict ? " (warning; failed by --strict)" : ""}`,
   ];
@@ -366,3 +363,43 @@ function formatResult(r) {
   for (const f of r.fix) out.push(`      $ ${f}`);
   return out;
 }
+
+/** doctor --ci's pin and Kit-owned path checks, against an already-fetched tag. */
+export function fileAndPinChecks({ runner, root, snap }) {
+  let pins;
+  try {
+    pins = checkPins(readWorkflows(root).files);
+  } catch (err) {
+    return [result("pins", "uses: pins agree", "fail", firstLine(err?.message ?? err))];
+  }
+  const results = [pins.result];
+  if (pins.tag !== snap.tag) {
+    results.push(
+      result(
+        "kit-owned-trees",
+        "Kit-owned paths match the pinned tag",
+        "fail",
+        `The pins do not all name ${snap.tag}.`,
+      ),
+    );
+    return results;
+  }
+  try {
+    results.push(checkKitOwnedTrees({ runner, cwd: root, snapshot: snap }));
+  } catch (err) {
+    results.push(
+      result("kit-owned-trees", "Kit-owned paths match the pinned tag", "fail", err.message),
+    );
+  }
+  return results;
+}
+
+/**
+ * Print fileAndPinChecks results under a heading, for init and upgrade.
+ * Returns true when one failed.
+ */
+export function printFileAndPinChecks(out, results) {
+  out("Checks (as doctor --ci):");
+  for (const r of results) for (const line of formatResult(r)) out(line);
+  return results.some((r) => r.status === "fail");
+}

package/src/exec.mjs

@@ -8,7 +8,10 @@ const ALLOWED = new Set(["git", "gh"]);
 
 /**
  * @typedef {{ status: number | null, stdout: string, stderr: string }} RunResult
- * @typedef {(cmd: string, args: string[], opts?: { cwd?: string, env?: NodeJS.ProcessEnv }) => RunResult} Runner
+ * @typedef {{ status: number | null, stdout: Buffer, stderr: string }} BufferResult
+ * @typedef {(cmd: string, args: string[], opts?: { cwd?: string, env?: NodeJS.ProcessEnv, encoding?: "utf8" | "buffer" }) => RunResult} Runner
+ *   With `encoding: "buffer"`, stdout is the raw bytes (a Buffer): use it for
+ *   file contents, which need not be UTF-8. stderr is always text.
  */
 
 /** @type {Runner} */
@@ -20,15 +23,25 @@ export function systemRunner(cmd, args, opts = {}) {
   const result = spawnSync(cmd, args, {
     cwd: opts.cwd,
     env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GH_PROMPT_DISABLED: "1", ...opts.env },
-    encoding: "utf8",
+    encoding: "buffer",
     shell: false,
     windowsHide: true,
     maxBuffer: 64 * 1024 * 1024,
   });
+  const raw = opts.encoding === "buffer";
   if (result.error) {
-    return { status: null, stdout: "", stderr: `${cmd}: ${result.error.message}` };
+    return {
+      status: null,
+      stdout: raw ? Buffer.alloc(0) : "",
+      stderr: `${cmd}: ${result.error.message}`,
+    };
   }
-  return { status: result.status, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+  const stdout = result.stdout ?? Buffer.alloc(0);
+  return {
+    status: result.status,
+    stdout: raw ? stdout : stdout.toString("utf8"),
+    stderr: (result.stderr ?? Buffer.alloc(0)).toString("utf8"),
+  };
 }
 
 /**