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

package/README.md

@@ -1,3 +1,22 @@
-# Temporary Holding Version
+# @mnaimfaizy/agent-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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 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`.
+- `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-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

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// @mnaimfaizy/agent-kit: adopt, upgrade and check Agent-kit in a Consumer
+// 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 = 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,31 @@
 {
   "name": "@mnaimfaizy/agent-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "bin": {
+    "agent-kit": "bin/agent-kit.mjs"
+  },
+  "files": [
+    "bin/agent-kit.mjs",
+    "src/"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mnaimfaizy/agent-kit.git",
+    "directory": "cli"
+  },
+  "homepage": "https://github.com/mnaimfaizy/agent-kit/blob/main/cli/README.md",
+  "bugs": "https://github.com/mnaimfaizy/agent-kit/issues",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "node --test ../scripts/cli-*.test.mjs"
+  }
+}

package/src/callers.mjs

@@ -0,0 +1,204 @@
+// Reads a Consumer's Caller workflows: the jobs that `uses:` an Agent-kit
+// reusable workflow, the secrets they pass, the repository variables they
+// read, and their Trigger labels.
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parseScalar, parseYamlSubset, stripBom, stripComment } from "./yaml-subset.mjs";
+
+export const KIT_REPO_NAME = "agent-kit";
+export const DEFAULT_KIT_REPO = "mnaimfaizy/agent-kit";
+
+// owner/agent-kit/.github/workflows/<file>@<ref>. GitHub owner and repository
+// names are case-insensitive, so the match is too.
+const KIT_USES =
+  /^([A-Za-z0-9][A-Za-z0-9-]*)\/(agent-kit)\/\.github\/workflows\/([A-Za-z0-9._-]+\.ya?ml)@(\S+)$/i;
+// `uses:`, `"uses":`, `'uses' :`, optionally as a list item.
+const USES_LINE = /^\s*(?:-\s+)?(?:uses|"uses"|'uses')\s*:\s*(.+)$/;
+const NAME = "[A-Za-z_][A-Za-z0-9_]*";
+
+/** Parse a `uses:` value; null unless it points at an Agent-kit reusable workflow. */
+export function parseKitUses(value) {
+  const m = KIT_USES.exec(parseScalar(stripComment(String(value))));
+  return m ? { owner: m[1], repo: `${m[1]}/${m[2]}`, file: m[3], ref: m[4] } : null;
+}
+
+// `key: |` or `- key: >-`: the lines after it, indented deeper than the key,
+// are a block scalar (a `run:` script, say), not YAML keys.
+const BLOCK_START = /^(-\s+)?[^\s:#][^:]*:\s*[|>][-+0-9]*\s*$/;
+
+/**
+ * Every Agent-kit `uses:` line in a workflow file, with its line number.
+ * Text inside block scalars, such as a `run: |` script, is not a pin.
+ */
+export function findKitPins(text) {
+  const pins = [];
+  let blockIndent = null;
+  stripBom(String(text))
+    .replace(/\r\n?/g, "\n")
+    .split("\n")
+    .forEach((line, idx) => {
+      const indent = line.length - line.trimStart().length;
+      if (blockIndent !== null) {
+        if (line.trim() === "" || indent > blockIndent) return;
+        blockIndent = null;
+      }
+      if (line.trimStart().startsWith("#")) return;
+      const content = stripComment(line.slice(indent)).trimEnd();
+      const block = BLOCK_START.exec(content);
+      if (block) {
+        blockIndent = indent + (block[1]?.length ?? 0);
+        return;
+      }
+      const m = USES_LINE.exec(line);
+      if (!m) return;
+      const pin = parseKitUses(m[1]);
+      if (pin) pins.push({ ...pin, line: idx + 1 });
+    });
+  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")
+    .split("\n")
+    .filter((l) => !l.trimStart().startsWith("#"))
+    .map(stripComment);
+}
+
+/** Names of `secrets.X` in an expression. */
+export function secretNames(value) {
+  return [...String(value ?? "").matchAll(new RegExp(`secrets\\.(${NAME})`, "g"))].map((m) => m[1]);
+}
+
+/**
+ * Every `vars.X` a file reads. A variable is optional when every read of it
+ * falls back with `||` (as the model variables do); otherwise it is required
+ * (the Kill switch variables: unset means the flow never runs). The `||` may
+ * follow closing parentheses, and may sit on the next line of a multi-line
+ * expression.
+ */
+export function variableRefs(text) {
+  const refs = new Map();
+  const re = new RegExp(`vars\\.(${NAME})((?:\\s*\\))*\\s*\\|\\|)?`, "g");
+  for (const m of lines(text).join("\n").matchAll(re)) {
+    const optional = Boolean(m[2]);
+    const prev = refs.get(m[1]);
+    refs.set(m[1], { name: m[1], optional: prev ? prev.optional && optional : optional });
+  }
+  return [...refs.values()];
+}
+
+/**
+ * Why a job's `secrets:` cannot be read, or null. The parser reads block
+ * mappings and `inherit`; a flow mapping, an anchor, an alias or a merge key
+ * would need a full YAML parser, so those jobs are reported, not guessed at.
+ */
+function unsupportedSecrets(value) {
+  if (value === undefined || value === null || value === "inherit") return null;
+  if (typeof value === "string") {
+    if (value.startsWith("{")) return "`secrets:` is a flow mapping ({ ... })";
+    if (value.startsWith("*")) return "`secrets:` is a YAML alias";
+    if (value.startsWith("&")) return "`secrets:` uses a YAML anchor";
+    return `\`secrets:\` is ${JSON.stringify(value)}`;
+  }
+  if (value.$seq) return "`secrets:` is a list";
+  if ("<<" in value) return "`secrets:` uses a YAML merge key (<<)";
+  return null;
+}
+
+/**
+ * The jobs of one workflow file that call an Agent-kit reusable workflow.
+ * `parseIncomplete` is set when the file has more Agent-kit pins than jobs
+ * the parser could read, so checks built on the jobs report it instead of
+ * passing.
+ */
+export function parseCaller(text) {
+  const doc = parseYamlSubset(text);
+  const jobs = [];
+  const jobMap = doc.jobs && typeof doc.jobs === "object" && !doc.jobs.$seq ? doc.jobs : {};
+  for (const [name, job] of Object.entries(jobMap)) {
+    if (!job || typeof job !== "object" || typeof job.uses !== "string") continue;
+    const uses = parseKitUses(job.uses);
+    if (!uses) continue;
+    const withBlock = job.with && typeof job.with === "object" && !job.with.$seq ? job.with : {};
+    const secretsUnsupported = unsupportedSecrets(job.secrets);
+    let secrets = {};
+    if (job.secrets === "inherit") secrets = "inherit";
+    else if (!secretsUnsupported && job.secrets && typeof job.secrets === "object") {
+      secrets = job.secrets;
+    }
+    jobs.push({ name, uses, with: withBlock, secrets, secretsUnsupported });
+  }
+  const pins = findKitPins(text);
+  const parseIncomplete =
+    pins.length > jobs.length
+      ? `${pins.length} Agent-kit pin(s) but only ${jobs.length} job(s) doctor could read; ` +
+        "the rest were not checked"
+      : null;
+  return { jobs, pins, variables: variableRefs(text), parseIncomplete };
+}
+
+/** Workflow files in .github/workflows/ (relative paths, sorted). */
+export class WorkflowsDirError extends Error {}
+
+export function listWorkflowFiles(repoRoot) {
+  const dir = join(repoRoot, ".github", "workflows");
+  if (!existsSync(dir)) return [];
+  if (!statSync(dir).isDirectory()) {
+    throw new WorkflowsDirError(
+      ".github/workflows is not a folder, so there are no Callers to read.",
+    );
+  }
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isFile() && /\.ya?ml$/.test(e.name))
+    .map((e) => `.github/workflows/${e.name}`)
+    .sort();
+}
+
+/** Read every workflow file; `callers` are the ones with at least one Agent-kit pin. */
+export function readWorkflows(repoRoot) {
+  const files = listWorkflowFiles(repoRoot).map((path) => {
+    const text = stripBom(readFileSync(join(repoRoot, path), "utf8"));
+    return { path, text, ...parseCaller(text) };
+  });
+  return { files, callers: files.filter((f) => f.pins.length > 0) };
+}

package/src/checks/claude-app.mjs

@@ -0,0 +1,55 @@
+// The Claude GitHub App must be installed on the repository. GitHub only shows
+// app installations to an organization admin (`orgs/<org>/installations`) or
+// to a GitHub App user token; a `gh` login on a personal account cannot see
+// them, so there the check is skipped rather than guessed.
+
+import { result } from "./result.mjs";
+
+const ID = "claude-app";
+const TITLE = "Claude GitHub App installed";
+const APP_SLUG = "claude";
+const APP_URL = "https://github.com/apps/claude";
+
+export function checkClaudeApp({ github, repo, owner, ownerType }) {
+  if (ownerType !== "Organization") {
+    return result(
+      ID,
+      TITLE,
+      "skip",
+      "GitHub does not show a personal account's app installations to a gh login.",
+      {
+        details: [
+          `Check https://github.com/settings/installations, or install it from ${APP_URL}.`,
+        ],
+      },
+    );
+  }
+  let rows;
+  try {
+    rows = github.getLines(
+      `orgs/${owner}/installations`,
+      '.installations[] | [.app_slug, .repository_selection] | join(" ")',
+    );
+  } catch (err) {
+    return result(ID, TITLE, "skip", `Could not list ${owner}'s app installations: ${err.message}`);
+  }
+  const app = rows.map((r) => r.split(" ")).find(([slug]) => slug === APP_SLUG);
+  if (!app) {
+    return result(ID, TITLE, "fail", `The Claude GitHub App is not installed on ${owner}.`, {
+      details: [`Install it on ${repo} from ${APP_URL}.`],
+    });
+  }
+  if (app[1] === "all")
+    return result(ID, TITLE, "pass", `Installed on all of ${owner}'s repositories.`);
+  return result(
+    ID,
+    TITLE,
+    "skip",
+    `Installed on selected ${owner} repositories; gh cannot see which.`,
+    {
+      details: [
+        `Check that ${repo} is selected: https://github.com/organizations/${owner}/settings/installations`,
+      ],
+    },
+  );
+}

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

@@ -0,0 +1,78 @@
+// Each Kit-owned path in the working copy must have the same git tree hash as
+// the same path at the pinned tag. Kit-owned paths are copied verbatim and
+// never edited, so any difference means a stale, partial or edited copy.
+
+import { DEFAULT_KIT_REPO } from "../callers.mjs";
+import { localTreeHashes } from "../local-tree.mjs";
+import { upgradeCommand } from "../tags.mjs";
+import { result } from "./result.mjs";
+
+const ID = "kit-owned-trees";
+const TITLE = "Kit-owned paths match the pinned tag";
+
+/**
+ * @param {{ runner: import("../exec.mjs").Runner, cwd: string, snapshot: { tag: string, kitOwnedPaths: string[], treeHash: (p: string) => string | null } }} opts
+ */
+export function checkKitOwnedTrees({ runner, cwd, snapshot }) {
+  const { tag, kitOwnedPaths } = snapshot;
+  const repo = snapshot.repo ?? DEFAULT_KIT_REPO;
+  const { hashes, skipped, notes } = localTreeHashes({ runner, cwd, paths: kitOwnedPaths });
+  const serverUrl = snapshot.serverUrl ?? "https://github.com";
+  const bad = [];
+  const notChecked = [];
+  for (const path of kitOwnedPaths) {
+    if (skipped.has(path)) {
+      notChecked.push(`${path}: not checked, ${skipped.get(path)}`);
+      continue;
+    }
+    const expected = snapshot.treeHash(path);
+    const actual = hashes.get(path);
+    if (expected === null) {
+      bad.push(`${path}: listed in ${tag}'s kit-owned-paths.txt but not in the tag`);
+    } else if (actual === null) {
+      bad.push(`${path}: missing (expected tree ${expected.slice(0, 12)})`);
+    } else if (actual !== expected) {
+      bad.push(`${path}: differs (local ${actual.slice(0, 12)}, ${tag} ${expected.slice(0, 12)})`);
+    }
+  }
+  const howCompared = [...notes].map(([path, note]) => `${path}: ${note}`);
+  const checked = kitOwnedPaths.length - notChecked.length;
+  if (bad.length === 0 && notChecked.length === 0) {
+    return result(ID, TITLE, "pass", `All ${kitOwnedPaths.length} Kit-owned paths match ${tag}.`, {
+      details: howCompared,
+    });
+  }
+  if (bad.length === 0) {
+    // A path that could not be compared is never reported as matching.
+    return result(
+      ID,
+      TITLE,
+      "skip",
+      `${checked} Kit-owned path(s) match ${tag}; ${notChecked.length} could not be checked.`,
+      { details: [...notChecked, ...howCompared, "Run doctor in a full checkout to check them."] },
+    );
+  }
+  return result(
+    ID,
+    TITLE,
+    "fail",
+    `${bad.length} of ${kitOwnedPaths.length} Kit-owned paths do not match ${tag}.`,
+    {
+      details: [
+        ...bad,
+        ...notChecked,
+        ...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.`,
+        `Run the command below, or delete and re-copy each path by hand as ` +
+          `${manualCopyUrl(repo, tag, serverUrl)} describes.`,
+      ],
+      fix: [upgradeCommand(tag)],
+    },
+  );
+}
+
+/** adopt.md's copy section at the tag, which links the manual delete-then-copy loop. */
+export function manualCopyUrl(repo, tag, serverUrl = "https://github.com") {
+  return `${serverUrl}/${repo}/blob/${tag}/docs/adopt.md#copy-kit-owned-paths-from-the-same-tag`;
+}

package/src/checks/labels.mjs

@@ -0,0 +1,100 @@
+// Every Trigger label a Caller uses must exist: its `trigger_label`, or the
+// reusable workflow's default for that input at the pinned tag when the
+// Caller leaves it out.
+
+import { parseWorkflowCallInputs } from "../workflow-call.mjs";
+import { byHand, command, LABEL_PATTERN, result } from "./result.mjs";
+
+const ID = "trigger-labels";
+const TITLE = "Trigger labels exist";
+
+/**
+ * @param {object[]} callers
+ * @param {((workflowFile: string) => string | null) | null} readReusable reads
+ *   .github/workflows/<file> at the pinned tag; null when the tag is unknown.
+ * @returns {{ labels: { name: string, where: string[] }[], unknown: string[] }}
+ *   `unknown`: jobs whose label could not be worked out (a default that could
+ *   not be read, or a Caller file doctor could not parse fully).
+ */
+export function triggerLabels(callers, readReusable = null) {
+  const labels = new Map();
+  const unknown = [];
+  const defaults = new Map();
+  const defaultFor = (file) => {
+    if (!readReusable) return undefined;
+    if (!defaults.has(file)) {
+      const text = readReusable(file);
+      const inputs = text === null ? null : parseWorkflowCallInputs(text);
+      defaults.set(file, inputs ? (inputs.get("trigger_label")?.default ?? null) : undefined);
+    }
+    return defaults.get(file);
+  };
+  for (const caller of callers) {
+    if (caller.parseIncomplete) unknown.push(`${caller.path}: ${caller.parseIncomplete}`);
+    for (const job of caller.jobs) {
+      const explicit = job.with && "trigger_label" in job.with;
+      const label = explicit ? job.with.trigger_label : defaultFor(job.uses.file);
+      const where = `${caller.path}:${job.name}${explicit ? "" : " (default)"}`;
+      if (label === undefined) {
+        unknown.push(
+          `${where}: uses the default trigger_label of ${job.uses.file}, which could not be read`,
+        );
+        continue;
+      }
+      if (typeof label !== "string" || label === "" || label.includes("${{")) continue;
+      labels.set(label.toLowerCase(), {
+        name: label,
+        where: [...(labels.get(label.toLowerCase())?.where ?? []), where],
+      });
+    }
+  }
+  return { labels: [...labels.values()], unknown };
+}
+
+export function checkLabels({ github, repo, callers, readReusable = null }) {
+  const { labels: wanted, unknown } = triggerLabels(callers, readReusable);
+  if (wanted.length === 0 && unknown.length === 0) {
+    return result(ID, TITLE, "pass", "No Caller uses a Trigger label.");
+  }
+  let existing = new Set();
+  if (wanted.length) {
+    try {
+      existing = new Set(
+        github.getLines(`repos/${repo}/labels`, ".[].name").map((n) => n.toLowerCase()),
+      );
+    } catch (err) {
+      return result(ID, TITLE, "skip", `Could not list labels: ${err.message}`, {
+        details: unknown,
+      });
+    }
+  }
+  const missing = wanted.filter((l) => !existing.has(l.name.toLowerCase()));
+  if (missing.length) {
+    const fix = [];
+    const notes = [];
+    for (const l of missing) {
+      if (LABEL_PATTERN.test(l.name))
+        fix.push(command("gh", "label", "create", l.name, "--repo", repo));
+      else notes.push(byHand("create the label", l.name));
+    }
+    return result(ID, TITLE, "fail", `${missing.length} Trigger label(s) missing.`, {
+      details: [
+        ...missing.map((l) => `${JSON.stringify(l.name)} (${l.where.join(", ")})`),
+        ...unknown,
+        ...notes,
+      ],
+      fix,
+    });
+  }
+  if (unknown.length) {
+    // A label that could not be worked out is never reported as existing.
+    return result(
+      ID,
+      TITLE,
+      "skip",
+      `${wanted.length} Trigger label(s) exist; ${unknown.length} could not be worked out.`,
+      { details: unknown },
+    );
+  }
+  return result(ID, TITLE, "pass", `All ${wanted.length} Trigger label(s) exist.`);
+}

package/src/checks/pins.mjs

@@ -0,0 +1,76 @@
+// Every Agent-kit `uses:` pin must name the same repository and the same
+// Release-line tag: the copied Kit-owned paths come from one tag.
+
+import { DEFAULT_KIT_REPO } from "../callers.mjs";
+import { isReleaseTag } from "../tags.mjs";
+import { result } from "./result.mjs";
+
+const ID = "pins";
+const TITLE = "uses: pins agree";
+
+/**
+ * @param {{ path: string, pins: { repo: string, file: string, ref: string, line: number }[] }[]} files
+ * @returns {{ result: object, repo: string | null, tag: string | null }}
+ */
+export function checkPins(files) {
+  const all = files.flatMap((f) => f.pins.map((p) => ({ ...p, path: f.path })));
+  if (all.length === 0) {
+    return {
+      result: result(
+        ID,
+        TITLE,
+        "fail",
+        "No Caller in .github/workflows/ pins an Agent-kit reusable workflow.",
+        {
+          details: [
+            "Copy a Caller from the tag's examples/ (see docs/getting-started.md, step 5).",
+          ],
+        },
+      ),
+      repo: null,
+      tag: null,
+    };
+  }
+  const where = (p) => `${p.path}:${p.line} → ${p.repo}@${p.ref}`;
+  const refs = new Set(all.map((p) => p.ref));
+  // GitHub owner names are case-insensitive: MnaimFaizy/ and mnaimfaizy/ are one repository.
+  const repos = new Set(all.map((p) => p.repo.toLowerCase()));
+  const notTags = all.filter((p) => !isReleaseTag(p.ref));
+  const details = [];
+  if (repos.size > 1)
+    details.push(`Pins name more than one kit repository: ${[...repos].join(", ")}.`);
+  if (refs.size > 1) details.push(`Pins name more than one ref: ${[...refs].join(", ")}.`);
+  if (notTags.length)
+    details.push("Pin a Release-line tag (vX.Y.Z or vX.Y.Z-stage.N), not a branch or SHA.");
+  if (details.length) {
+    return {
+      result: result(
+        ID,
+        TITLE,
+        "fail",
+        `${all.length} pins disagree or are not Release-line tags.`,
+        {
+          details: [...details, ...all.map(where)],
+        },
+      ),
+      repo: null,
+      tag: null,
+    };
+  }
+  const { repo } = all[0];
+  const [tag] = refs;
+  const summary = `${all.length} pin${all.length === 1 ? "" : "s"} use ${repo}@${tag}.`;
+  if (repo.toLowerCase() !== DEFAULT_KIT_REPO) {
+    // A fork or an Enterprise mirror is a valid choice: say so, but not as a warning.
+    return {
+      result: result(ID, TITLE, "pass", summary, {
+        details: [
+          `The pins name ${repo}, not ${DEFAULT_KIT_REPO}; the Kit-owned path checks compare against that repository.`,
+        ],
+      }),
+      repo,
+      tag,
+    };
+  }
+  return { result: result(ID, TITLE, "pass", summary), repo, tag };
+}

package/src/checks/result.mjs

@@ -0,0 +1,74 @@
+// A check result, and the rules for anything doctor prints. `skip` means the
+// check did not run, and is never counted as a pass.
+//
+// Doctor prints values that come from files and API responses it does not
+// control (secret and variable names, label names, error text). So:
+// - a fix command is printed only when every value in it passes a strict
+//   allowlist, and each argument is quoted; otherwise the adopter gets a
+//   "fix by hand" note with the value JSON-escaped, never a command;
+// - every printed line has control characters escaped and cannot start a
+//   CI log command (see sanitizeLine).
+
+export const STATUSES = ["pass", "warn", "fail", "skip"];
+
+export function result(id, title, status, summary, { details = [], fix = [] } = {}) {
+  if (!STATUSES.includes(status)) throw new Error(`unknown status ${status}`);
+  return { id, title, status, summary, details, fix };
+}
+
+/** A GitHub Actions secret or variable name. */
+export const NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A label name doctor will put in a command: no quotes, no shell or PowerShell syntax. */
+export const LABEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9 :._/-]*$/;
+/** owner/name as GitHub allows it, never starting with `-`. */
+export const REPO_PATTERN = /^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9._-]+$/;
+
+/** Arguments doctor itself writes into a command (flags and fixed words). */
+const WORD = /^[A-Za-z0-9_.:/@=+-]+$/;
+
+/**
+ * Quote one argument for a POSIX shell. Callers only pass values that matched
+ * an allowlist above, none of which contains a quote, so single quotes are
+ * enough in bash and in PowerShell alike.
+ */
+export function shellQuote(value) {
+  const s = String(value);
+  if (s.includes("'")) throw new Error("refusing to quote a value that contains a single quote");
+  return WORD.test(s) ? s : `'${s}'`;
+}
+
+/** Build a printable command from argument words, every one quoted. */
+export function command(...args) {
+  return args.map(shellQuote).join(" ");
+}
+
+/** A note for a value that cannot go into a command, shown JSON-escaped. */
+export function byHand(what, value) {
+  return `fix by hand: ${what} ${JSON.stringify(String(value))} (not printed as a command)`;
+}
+
+// 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
+ * characters (so no ANSI escape, no carriage return, no embedded newline),
+ * and keep the line from starting a GitHub Actions workflow command
+ * (`::name::` or the older `##[name]`).
+ */
+export function sanitizeLine(line) {
+  let s = String(line).replace(
+    CONTROL,
+    (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+  const lead = s.length - s.trimStart().length;
+  const rest = s.slice(lead);
+  if (rest.startsWith("::") || rest.startsWith("##[")) s = `${s.slice(0, lead)}\\${rest}`;
+  return s;
+}