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

package/src/init.mjs

@@ -0,0 +1,627 @@
+// `agent-kit init --tag vX`: adopt Agent-kit in a Consumer from one tag. It
+// copies the Kit-owned paths, writes a Caller per chosen flow from the tag's
+// examples/ with its placeholders filled in, writes the Threat pack skeleton
+// and (if there is none) .github/dependabot.yml, then prints the GitHub-side
+// steps as `gh` commands for the Consumer to run. It writes only local files.
+//
+// Plan first, then write: every file is read and every refusal checked
+// before anything on disk changes.
+
+import { join } from "node:path";
+import { DEFAULT_KIT_REPO } from "./callers.mjs";
+import { command } from "./checks/result.mjs";
+import { fileAndPinChecks, printFileAndPinChecks } from "./doctor.mjs";
+import { firstLine } from "./exec.mjs";
+import { openKitTag, PreManifestTagError, serverFromEnv } from "./kit-tag.mjs";
+import { localTreeHashes } from "./local-tree.mjs";
+import {
+  applyPlan,
+  checkDeletable,
+  checkLocalPath,
+  kitFileWrites,
+  listed,
+  lstatOrNull,
+  Refusal,
+  reportRefusal,
+  stageFileModes,
+  uncommittedChanges,
+} from "./local-writes.mjs";
+import { caseCollisions, checkSafePath, fileDirConflicts } from "./safe-paths.mjs";
+import { isReleaseTag } from "./tags.mjs";
+import {
+  DEFAULT_THREAT_PACK_DIR,
+  FLOWS,
+  renderCaller,
+  TemplateError,
+  THREAT_PACK_FILES,
+} from "./templates.mjs";
+
+const LOGIN = /^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}(?:\[bot\])?$/;
+const BRANCH = /^[A-Za-z0-9_][A-Za-z0-9._-]*(?:\/[A-Za-z0-9_][A-Za-z0-9._-]*)*$/;
+const PRESET = /^[a-z0-9][a-z0-9-]*$/;
+// Tab and newline are allowed in --verify; every other control character is not.
+// eslint-disable-next-line no-control-regex
+const VERIFY_CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u2028\u2029]/;
+const DEPENDABOT_FILES = [".github/dependabot.yml", ".github/dependabot.yaml"];
+
+export const DEPENDABOT_BLOCK = `version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    ignore:
+      - dependency-name: "*"
+        versions:
+          - "*-alpha.*"
+          - "*-beta.*"
+          - "*-rc.*"
+`;
+
+const LABELS = [
+  ["agent:plan", "1D76DB", "Agent-kit: plan this issue"],
+  ["agent:implement", "0E8A16", "Agent-kit: implement the Verified plan"],
+  ["agent:review", "5319E7", "Agent-kit: review this PR"],
+];
+
+/** The `init` answers, as flags name them, with what each one asks. */
+export const QUESTIONS = [
+  { key: "tag", flag: "--tag <vX>", ask: "Agent-kit tag to adopt (for example v1.0.0)" },
+  { key: "flows", flag: "--flows pipeline,audit", ask: "Flows to set up (pipeline, audit)" },
+  {
+    key: "actors",
+    flag: "--actors <login,...>",
+    ask: "Allowlist: GitHub logins allowed to trigger runs",
+  },
+  { key: "defaultBranch", flag: "--default-branch <name>", ask: "Default branch" },
+  {
+    key: "verify",
+    flag: "--verify <commands>",
+    ask: "verify_commands (lint/tests/typecheck; use \\n between commands)",
+    only: "pipeline",
+  },
+  {
+    key: "preset",
+    flag: "--preset <name|none>",
+    ask: "setup_commands preset (python, node, mixed, redis-service, or none)",
+    only: "pipeline",
+  },
+  {
+    key: "threatPackDir",
+    flag: "--threat-pack-dir <dir>",
+    ask: "Folder for the Threat pack",
+    only: "audit",
+  },
+];
+
+/** Answers with a default: asked about only on a terminal, never required. */
+const DEFAULTS = { preset: "none", threatPackDir: DEFAULT_THREAT_PACK_DIR };
+
+const split = (s) =>
+  String(s)
+    .split(/[\s,]+/)
+    .filter(Boolean);
+
+/**
+ * Check and normalise one answer. Returns { value } or { error }.
+ */
+export function parseAnswer(key, raw, { prompted = false } = {}) {
+  const s = String(raw ?? "");
+  switch (key) {
+    case "tag":
+      return isReleaseTag(s)
+        ? { value: s }
+        : {
+            error: `--tag must be a Release-line tag (vX.Y.Z or vX.Y.Z-stage.N), got ${JSON.stringify(s)}`,
+          };
+    case "flows": {
+      const flows = [...new Set(split(s))];
+      const bad = flows.filter((f) => !(f in FLOWS));
+      if (flows.length === 0 || bad.length) {
+        return { error: `--flows takes pipeline and/or audit, got ${JSON.stringify(s)}` };
+      }
+      return { value: Object.keys(FLOWS).filter((f) => flows.includes(f)) };
+    }
+    case "actors": {
+      const actors = [...new Set(split(s))];
+      const bad = actors.filter((a) => !LOGIN.test(a));
+      if (actors.length === 0 || bad.length) {
+        return { error: `--actors takes GitHub logins, got ${JSON.stringify(bad[0] ?? s)}` };
+      }
+      return { value: actors };
+    }
+    case "defaultBranch":
+      return BRANCH.test(s) && !s.includes("..") && !/\.lock(?:\/|$)/.test(s) && !s.endsWith(".")
+        ? { value: s }
+        : { error: `--default-branch is not a branch name this CLI accepts: ${JSON.stringify(s)}` };
+    case "verify": {
+      // A prompt takes one line, so there \n separates commands; a flag keeps it.
+      let v = s.replace(/\r\n?/g, "\n");
+      if (prompted) v = v.replace(/\\n/g, "\n");
+      v = v.replace(/^\n+|\s+$/g, "");
+      if (!v.trim()) return { error: "--verify must not be empty" };
+      if (VERIFY_CONTROL.test(v)) return { error: "--verify contains a control character" };
+      if (v.includes("${{")) {
+        return {
+          error:
+            "--verify must not contain ${{ }}: GitHub would expand it into the script. " +
+            "Read values from environment variables instead.",
+        };
+      }
+      return { value: v };
+    }
+    case "preset":
+      if (s === "none") return { value: null };
+      return PRESET.test(s)
+        ? { value: s }
+        : { error: `--preset takes a preset name or none, got ${JSON.stringify(s)}` };
+    case "threatPackDir": {
+      const dir = s.replace(/\/+$/, "");
+      try {
+        checkSafePath(dir, "--threat-pack-dir");
+      } catch (err) {
+        return { error: err.message };
+      }
+      const lower = dir.toLowerCase();
+      if (lower === ".github/workflows" || lower.startsWith(".github/workflows/")) {
+        return { error: "--threat-pack-dir must not be inside .github/workflows" };
+      }
+      return { value: dir };
+    }
+    default:
+      throw new Error(`unknown answer ${key}`);
+  }
+}
+
+/**
+ * Gather every answer from flags, then (on a terminal, without --yes) by
+ * asking. Returns { answers } or { missing: [flags] } or { error }.
+ *
+ * @param {{ flags: Record<string, string | undefined>, prompt: ((q: string) => Promise<string>) | null, yes: boolean, defaultBranch: string }} opts
+ */
+export async function collectAnswers({ flags, prompt, yes, defaultBranch }) {
+  const interactive = Boolean(prompt) && !yes;
+  const answers = {};
+  const missing = [];
+  for (const q of QUESTIONS) {
+    if (q.only && answers.flows && !answers.flows.includes(q.only)) continue;
+    let raw = flags[q.key];
+    let prompted = false;
+    const fallback = q.key === "defaultBranch" ? defaultBranch : DEFAULTS[q.key];
+    if (raw === undefined && interactive) {
+      const hint = fallback !== undefined ? ` [${fallback}]` : "";
+      raw = (await prompt(`${q.ask}${hint}: `)) || fallback;
+      prompted = true;
+    }
+    if (raw === undefined) raw = fallback;
+    if (raw === undefined || raw === "") {
+      // Asked on a terminal and left empty: say so now, rather than asking on
+      // (later questions depend on this one) or claiming there is no terminal.
+      if (prompted) return { error: `${q.ask} is required (${q.flag}).` };
+      missing.push(q.flag);
+      continue;
+    }
+    const parsed = parseAnswer(q.key, raw, { prompted });
+    if (parsed.error) return { error: parsed.error };
+    answers[q.key] = parsed.value;
+  }
+  if (missing.length) return { missing };
+  return { answers };
+}
+
+/**
+ * The default branch to suggest: origin's HEAD, else main. Never the current
+ * branch, which is often the adoption branch itself.
+ */
+export function detectDefaultBranch(runner, cwd) {
+  const r = runner("git", [
+    "-C",
+    cwd,
+    "symbolic-ref",
+    "--quiet",
+    "--short",
+    "refs/remotes/origin/HEAD",
+  ]);
+  const name = r.status === 0 ? r.stdout.trim().replace(/^origin\//, "") : "";
+  return name && parseAnswer("defaultBranch", name).value ? name : "main";
+}
+
+/** Text from the tag that will be inlined into YAML or written as a file. */
+function tagText(snap, path) {
+  const text = snap.readFile(path);
+  if (text === null) return null;
+  // eslint-disable-next-line no-control-regex
+  if (/[\r\ufffd\u0085\u2028\u2029]|[\u0000-\u0008\u000b-\u001f]/.test(text)) {
+    throw new Refusal(`${path} at ${snap.tag} is not plain UTF-8 text with LF line endings.`);
+  }
+  return text;
+}
+
+function presetText(snap, name) {
+  const path = `examples/setup-presets/${name}.sh`;
+  const text = tagText(snap, path);
+  if (text === null) {
+    let known = [];
+    try {
+      known = snap
+        .listFiles("examples/setup-presets/")
+        .map((f) => f.path.replace(/^.*\//, "").replace(/\.sh$/, ""));
+    } catch {
+      // No list to offer; the refusal still names the preset.
+    }
+    throw new Refusal(
+      `${snap.tag} has no setup preset ${JSON.stringify(name)}` +
+        (known.length ? `; it has: ${known.join(", ")}, or none.` : "."),
+    );
+  }
+  // The same rules scripts/setup-presets-contract.test.py holds presets to.
+  // A first line that starts with a space would change the block's indentation.
+  if (text.includes("${{") || text.includes("<<") || /^[ \t]/.test(text)) {
+    throw new Refusal(`${path} at ${snap.tag} cannot be inlined into setup_commands safely.`);
+  }
+  return text;
+}
+
+/**
+ * Work out everything init would write and throw Refusal for anything that
+ * stops it. Touches nothing on disk.
+ */
+export function planInit({ runner, root, snap, answers, force }) {
+  const { tag } = snap;
+  const conflicts = [];
+  const deletes = [];
+  const writes = [];
+  const notes = [];
+  const overwrites = [];
+  const kept = [];
+  const exists = (rel) => lstatOrNull(join(root, rel)) !== null;
+  // A Caller or Threat pack file: refused while planning if something other
+  // than a regular file is in the way, so the write cannot fail half-way.
+  // Returns whether the file already exists.
+  const fileTarget = (rel, what) => {
+    checkLocalPath(root, rel);
+    const st = lstatOrNull(join(root, rel));
+    if (st && !st.isFile()) {
+      throw new Refusal(`${rel} exists and is not a file, so init cannot write the ${what} there.`);
+    }
+    return Boolean(st);
+  };
+
+  // Kit-owned paths: copied whole. One that already matches the tag (an
+  // earlier init, adding a flow now) is left as it is; any other existing
+  // one is an earlier adoption, replaced only with --force.
+  const existing = snap.kitOwnedPaths.filter((p) => {
+    checkLocalPath(root, p.replace(/\/$/, ""));
+    return exists(p.replace(/\/$/, ""));
+  });
+  const local = existing.length
+    ? localTreeHashes({ runner, cwd: root, paths: existing }).hashes
+    : new Map();
+  const unchanged = existing.filter((p) => {
+    const hash = local.get(p);
+    return hash !== null && hash !== undefined && hash === snap.treeHash(p);
+  });
+  for (const p of existing.filter((x) => !unchanged.includes(x))) {
+    if (!force) conflicts.push(`${p} (Kit-owned path)`);
+    else {
+      const rel = p.replace(/\/$/, "");
+      checkDeletable(root, rel);
+      deletes.push(rel);
+    }
+  }
+  writes.push(...kitFileWrites(snap).filter((w) => !unchanged.some((p) => w.path.startsWith(p))));
+
+  const dir = answers.threatPackDir ?? DEFAULT_THREAT_PACK_DIR;
+  // Case-insensitive: on Windows and macOS `.Claude/skills/x` is `.claude/skills/x`.
+  const lowerDir = `${dir.toLowerCase()}/`;
+  // Only a folder inside a Kit-owned path is replaced by upgrade; a parent
+  // such as .github is fine (.github/workflows is checked on its own).
+  const kitOwned = snap.kitOwnedPaths.find((p) => lowerDir.startsWith(p.toLowerCase()));
+  if (answers.flows.includes("audit") && kitOwned) {
+    throw new Refusal(
+      `--threat-pack-dir ${dir} overlaps the Kit-owned path ${kitOwned}, which upgrade replaces.`,
+    );
+  }
+
+  const values = {
+    actors: answers.actors,
+    tag,
+    defaultBranch: answers.defaultBranch,
+    verify: answers.verify ?? "",
+    preset: answers.preset ? presetText(snap, answers.preset) : null,
+    threatPackDir: dir,
+  };
+  for (const flow of answers.flows) {
+    const { example, caller } = FLOWS[flow];
+    const text = tagText(snap, example);
+    if (text === null) throw new Refusal(`${tag} has no ${example}.`);
+    let rendered;
+    try {
+      rendered = renderCaller(flow, text, values);
+    } catch (err) {
+      if (err instanceof TemplateError) throw new Refusal(err.message);
+      throw err;
+    }
+    if (fileTarget(caller, "Caller")) {
+      conflicts.push(`${caller} (Caller)`);
+      overwrites.push(caller);
+    }
+    writes.push({ path: caller, bytes: Buffer.from(rendered, "utf8") });
+  }
+
+  if (answers.flows.includes("audit")) {
+    const files = THREAT_PACK_FILES.map((f) => [f, tagText(snap, `examples/threat-pack/${f}`)]);
+    if (files.some(([, text]) => text === null)) {
+      notes.push(
+        `${tag} has no examples/threat-pack/, so no Threat pack was written: create ` +
+          `${dir}/threat-model.md and ${dir}/findings-ledger.md by hand (Getting started, step 7).`,
+      );
+    } else {
+      for (const [f, text] of files) {
+        const path = `${dir}/${f}`;
+        // The Threat pack is the Consumer's data (the ledger may hold
+        // findings): an existing file is kept, even with --force.
+        if (fileTarget(path, "Threat pack")) kept.push(path);
+        else writes.push({ path, bytes: Buffer.from(text, "utf8") });
+      }
+    }
+  }
+
+  const dependabot = DEPENDABOT_FILES.find(exists) ?? null;
+  if (!dependabot) {
+    checkLocalPath(root, DEPENDABOT_FILES[0]);
+    writes.push({ path: DEPENDABOT_FILES[0], bytes: Buffer.from(DEPENDABOT_BLOCK, "utf8") });
+  }
+
+  if (conflicts.length && !force) {
+    throw new Refusal(
+      `${conflicts.length} path(s) init would write already exist, and init does not overwrite them. ` +
+        "To add a flow to an existing adoption, run init with only the new flow: Kit-owned paths " +
+        `that already match ${tag} are left as they are. To move an existing adoption to another ` +
+        `tag, run \`npx @mnaimfaizy/agent-kit upgrade --tag ${tag}\`. To overwrite anyway, run ` +
+        "init again with --force.",
+      listed(conflicts),
+    );
+  }
+  const paths = writes.map((w) => w.path);
+  const clash = caseCollisions(paths);
+  if (clash.length) {
+    throw new Refusal(`Two files differ only in case: ${clash[0].join(" and ")}.`);
+  }
+  const fileDir = fileDirConflicts(paths);
+  if (fileDir.length) {
+    throw new Refusal(`${fileDir[0][0]} would be both a file and a folder (${fileDir[0][1]}).`);
+  }
+  if (kept.length) {
+    notes.push(`Kept the existing Threat pack file(s), which are yours: ${kept.join(", ")}.`);
+  }
+  if (unchanged.length) {
+    notes.push(`Left as they are (they already match ${tag}): ${unchanged.join(", ")}.`);
+  }
+  // --force discards whatever is uncommitted in the Kit-owned paths it
+  // replaces and the Callers it overwrites: list it first, as upgrade does.
+  const replaced = [...deletes, ...overwrites];
+  const { changed: dirty, ignored } = replaced.length
+    ? uncommittedChanges({ runner, root, paths: replaced })
+    : { changed: [], ignored: [] };
+  return { deletes, writes, conflicts, notes, dependabot, dirty, ignored, unchanged };
+}
+
+/**
+ * The GitHub-side steps init does not take, as POSIX-shell commands built
+ * with checks/result.mjs `command()` (every argument fixed or allowlisted).
+ */
+export function manualSteps({ flows, tag, kitRepo, serverUrl }) {
+  const pipeline = flows.includes("pipeline");
+  const audit = flows.includes("audit");
+  const lines = [];
+  let n = 0;
+  const step = (title, ...cmds) => {
+    lines.push(`${++n}. ${title}`);
+    for (const c of cmds) lines.push(`  $ ${c}`);
+  };
+  step(
+    "Secrets (gh asks for each value; CLAUDE_CODE_OAUTH_TOKEN comes from `claude setup-token`):",
+    command("gh", "secret", "set", "CLAUDE_CODE_OAUTH_TOKEN"),
+    ...(audit ? [command("gh", "secret", "set", "AGENT_KIT_ADVISORIES_TOKEN")] : []),
+  );
+  if (pipeline) {
+    step(
+      "Trigger labels:",
+      ...LABELS.map(([name, color, description]) =>
+        command("gh", "label", "create", name, "--color", color, "--description", description),
+      ),
+    );
+    step("Install the Claude GitHub App on this repository: https://github.com/apps/claude");
+  }
+  step(
+    "Rulesets the Claude GitHub App cannot bypass: list yours, then follow " +
+      `${serverUrl}/${kitRepo}/blob/${tag}/docs/repository-hardening.md`,
+    command("gh", "api", "repos/{owner}/{repo}/rulesets"),
+  );
+  step(
+    "Last, after you have reviewed and pushed the Callers, turn the flows on (Kill switch variables):",
+    ...(pipeline
+      ? [command("gh", "variable", "set", "CLAUDE_PIPELINE_ENABLED", "--body", "true")]
+      : []),
+    ...(audit
+      ? [command("gh", "variable", "set", "CLAUDE_SECURITY_AUDIT_ENABLED", "--body", "true")]
+      : []),
+  );
+  return lines;
+}
+
+/**
+ * @param {{
+ *   cwd: string,
+ *   runner: import("./exec.mjs").Runner,
+ *   flags: Record<string, string | undefined>,
+ *   force?: boolean,
+ *   yes?: boolean,
+ *   prompt?: ((question: string) => Promise<string>) | null,
+ *   confirm?: ((question: string) => Promise<boolean>) | null,
+ *   out: (text: string) => void,
+ *   err: (text: string) => void,
+ *   openTag?: typeof openKitTag,
+ *   env?: NodeJS.ProcessEnv,
+ * }} opts
+ * @returns {Promise<number>} exit code
+ */
+export async function runInit({
+  cwd,
+  runner,
+  flags,
+  force = false,
+  yes = false,
+  prompt = null,
+  confirm = null,
+  out,
+  err,
+  openTag = openKitTag,
+  env = process.env,
+}) {
+  const refuse = (e) => reportRefusal(out, e);
+
+  const collected = await collectAnswers({
+    flags,
+    prompt,
+    yes,
+    defaultBranch: detectDefaultBranch(runner, cwd),
+  });
+  if (collected.error) {
+    err(collected.error);
+    return 2;
+  }
+  if (collected.missing) {
+    const why = prompt && yes ? "--yes asks nothing" : "there is no terminal to ask on";
+    const needed = [...collected.missing, ...(prompt || yes ? [] : ["--yes"])];
+    err(`agent-kit init: ${why}, so pass ${needed.join(" and ")}.`);
+    return 2;
+  }
+  if (!prompt && !yes) {
+    err("agent-kit init: there is no terminal to confirm on, so pass --yes.");
+    return 2;
+  }
+  const { answers } = collected;
+  const bots = answers.actors.filter((a) => a.endsWith("[bot]"));
+  if (bots.length) {
+    out(
+      `Note: the Allowlist includes ${bots.join(", ")}. Anything that acts as that app can then ` +
+        "trigger the flows; list people unless you mean it.",
+    );
+  }
+
+  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();
+  const serverUrl = serverFromEnv(env);
+  out(`Adopting ${DEFAULT_KIT_REPO}@${answers.tag} (${answers.flows.join(", ")}) in ${root}.`);
+  if (answers.flows.includes("pipeline")) {
+    out(`Default branch in the Callers: ${answers.defaultBranch} (--default-branch to change).`);
+  }
+
+  let snap;
+  try {
+    snap = openTag({
+      runner,
+      repo: DEFAULT_KIT_REPO,
+      tag: answers.tag,
+      serverUrl,
+      forDeletion: true,
+    });
+  } catch (e) {
+    if (e instanceof PreManifestTagError) return refuse(e);
+    return refuse(new Refusal(firstLine(e?.message ?? e)));
+  }
+  try {
+    let plan;
+    try {
+      plan = planInit({ runner, root, snap, answers, force });
+    } catch (e) {
+      if (e instanceof Refusal) return refuse(e);
+      return refuse(new Refusal(firstLine(e?.message ?? e)));
+    }
+
+    out("");
+    out(`Write (from ${answers.tag}):`);
+    for (const p of snap.kitOwnedPaths.filter((x) => !plan.unchanged.includes(x))) {
+      const n = plan.writes.filter((w) => w.path.startsWith(p)).length;
+      out(
+        `  ${p} (${n} file${n === 1 ? "" : "s"}${plan.deletes.includes(p.replace(/\/$/, "")) ? ", replacing the existing copy" : ""})`,
+      );
+    }
+    for (const w of plan.writes.filter(
+      (x) => !snap.kitOwnedPaths.some((p) => x.path.startsWith(p)),
+    )) {
+      out(`  ${w.path}`);
+    }
+    if (plan.conflicts.length) {
+      out(`--force: overwriting ${plan.conflicts.length} existing path(s):`);
+      for (const c of listed(plan.conflicts)) out(`  ${c}`);
+    }
+    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 && !(confirm && (await confirm("Go ahead? [y/N] ")))) {
+      out("Stopped. Nothing was changed.");
+      return 1;
+    }
+    try {
+      applyPlan(root, plan);
+    } catch (e) {
+      if (e instanceof Refusal) return refuse(e);
+      out(`FAILED  init stopped part-way: ${firstLine(e?.message ?? e)}`);
+      out("      See `git status`; remove what was written and run init again.");
+      return 1;
+    }
+    out(`Wrote ${plan.writes.length} file(s).`);
+    const note = stageFileModes({ runner, root, writes: plan.writes });
+    if (note) out(note);
+    for (const n of plan.notes) out(n);
+    if (plan.dependabot) {
+      out("");
+      out(
+        `${plan.dependabot} already exists, so init left it alone. Merge this block into it by hand:`,
+      );
+      out(DEPENDABOT_BLOCK.replace(/\n$/, ""));
+    }
+    if (plan.writes.some((w) => w.path === `${answers.threatPackDir}/threat-model.md`)) {
+      out("");
+      out(
+        `Fill in ${answers.threatPackDir}/threat-model.md before the first audit; it is a skeleton.`,
+      );
+    }
+
+    out("");
+    const failed = printFileAndPinChecks(out, fileAndPinChecks({ runner, root, snap }));
+
+    out("");
+    out(
+      "Still to do on GitHub (init changed nothing there). Lines starting with $ are POSIX shell commands for you to run:",
+    );
+    for (const line of manualSteps({
+      flows: answers.flows,
+      tag: answers.tag,
+      kitRepo: DEFAULT_KIT_REPO,
+      serverUrl,
+    })) {
+      out(line);
+    }
+    out("");
+    out(
+      failed
+        ? "Result: a check failed (exit 1)."
+        : "Result: done. Review `git status` and `git diff`, commit, then run `npx @mnaimfaizy/agent-kit doctor` for the GitHub-side checks.",
+    );
+    return failed ? 1 : 0;
+  } finally {
+    snap.cleanup();
+  }
+}

package/src/kit-owned-paths.mjs

@@ -0,0 +1,48 @@
+// Parses kit-owned-paths.txt.
+//
+// Two levels of trust:
+// - forDeletion (the default): `upgrade` deletes every entry before copying
+//   it fresh, so only the permitted shapes pass, the same rule
+//   scripts/kit-owned-paths-contract.test.py enforces on the kit side. A tag
+//   that broke that rule must not delete Consumer files.
+// - read-only (`forDeletion: false`, used by doctor): any plain relative
+//   folder path is accepted, so an older CLI can still check a newer tag that
+//   adds a new kind of Kit-owned path. Nothing is deleted on this path.
+
+const ALLOWED_SHAPE =
+  /^(?:\.claude\/skills\/[A-Za-z0-9._-]+\/|\.github\/(?:agent-runtime|agent-pipeline|security-audit)\/)$/;
+const SAFE_PATH = /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*\/$/;
+
+export class ManifestError extends Error {}
+
+function safe(line) {
+  const parts = line.slice(0, -1).split("/");
+  return (
+    SAFE_PATH.test(line) &&
+    !parts.includes("..") &&
+    !parts.includes(".") &&
+    !parts.some((p) => p.toLowerCase() === ".git")
+  );
+}
+
+/**
+ * @param {string} text
+ * @param {{ forDeletion?: boolean }} [opts]
+ */
+export function parseKitOwnedPaths(text, { forDeletion = true } = {}) {
+  const entries = [];
+  for (const raw of String(text).split("\n")) {
+    const line = raw.replace(/\r$/, "");
+    if (!line || line.startsWith("#")) continue;
+    const ok = safe(line) && (!forDeletion || ALLOWED_SHAPE.test(line));
+    if (!ok) {
+      throw new ManifestError(
+        `kit-owned-paths.txt: ${JSON.stringify(line)} is not a permitted Kit-owned path`,
+      );
+    }
+    if (entries.includes(line)) throw new ManifestError(`kit-owned-paths.txt lists ${line} twice`);
+    entries.push(line);
+  }
+  if (entries.length === 0) throw new ManifestError("kit-owned-paths.txt lists no paths");
+  return entries;
+}