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

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();
+  }
+}

package/src/workflow-call.mjs

@@ -0,0 +1,44 @@
+// Reads a reusable workflow's `on.workflow_call.secrets` block: which secrets
+// it declares and which of them are required.
+
+import { parseYamlSubset } from "./yaml-subset.mjs";
+
+/** @returns {Map<string, { required: boolean }> | null} null when the file is not a reusable workflow. */
+export function parseWorkflowCallSecrets(text) {
+  const doc = parseYamlSubset(text);
+  const on = doc.on ?? doc["'on'"] ?? doc['"on"'];
+  if (!on || typeof on !== "object" || !("workflow_call" in on)) return null;
+  const call = on.workflow_call && typeof on.workflow_call === "object" ? on.workflow_call : {};
+  const secrets =
+    call.secrets && typeof call.secrets === "object" && !call.secrets.$seq ? call.secrets : {};
+  const out = new Map();
+  for (const [name, spec] of Object.entries(secrets)) {
+    const required =
+      spec && typeof spec === "object" ? String(spec.required).toLowerCase() === "true" : false;
+    out.set(name.toLowerCase(), { name, required });
+  }
+  return out;
+}
+
+/**
+ * A reusable workflow's `on.workflow_call.inputs`: each input's default (or
+ * null) and whether it is required.
+ * @returns {Map<string, { default: string | null, required: boolean }> | null}
+ */
+export function parseWorkflowCallInputs(text) {
+  const doc = parseYamlSubset(text);
+  const on = doc.on ?? doc["'on'"] ?? doc['"on"'];
+  if (!on || typeof on !== "object" || !("workflow_call" in on)) return null;
+  const call = on.workflow_call && typeof on.workflow_call === "object" ? on.workflow_call : {};
+  const inputs =
+    call.inputs && typeof call.inputs === "object" && !call.inputs.$seq ? call.inputs : {};
+  const out = new Map();
+  for (const [name, spec] of Object.entries(inputs)) {
+    const obj = spec && typeof spec === "object" ? spec : {};
+    out.set(name, {
+      default: typeof obj.default === "string" ? obj.default : null,
+      required: String(obj.required).toLowerCase() === "true",
+    });
+  }
+  return out;
+}

package/src/yaml-subset.mjs

@@ -0,0 +1,118 @@
+// A small, dependency-free reader for the YAML that workflow files use: block
+// mappings, plain and quoted scalars, block scalars (| and >), and sequences.
+// It returns nested plain objects. Sequences come back as { $seq: rawLines }
+// and block scalars as strings; flow collections ([a, b], {a: b}) stay as
+// their raw text. That is enough to read a Caller's jobs and a reusable
+// workflow's `on.workflow_call.secrets`, which is all the CLI needs.
+
+const BOM = String.fromCharCode(0xfeff);
+
+/** Drop a leading UTF-8 byte-order mark, which would otherwise hide the first key. */
+export function stripBom(text) {
+  const s = String(text);
+  return s.startsWith(BOM) ? s.slice(1) : s;
+}
+
+/** Remove a trailing `# comment` that sits outside quotes. */
+export function stripComment(line) {
+  let quote = null;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quote) {
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'") quote = c;
+    else if (c === "#" && (i === 0 || /\s/.test(line[i - 1]))) return line.slice(0, i);
+  }
+  return line;
+}
+
+export function parseScalar(raw) {
+  const v = raw.trim();
+  if (v.length >= 2 && v.startsWith('"') && v.endsWith('"')) {
+    return v.slice(1, -1).replace(/\\(["\\])/g, "$1");
+  }
+  if (v.length >= 2 && v.startsWith("'") && v.endsWith("'")) {
+    return v.slice(1, -1).replace(/''/g, "'");
+  }
+  return v;
+}
+
+const KEY = /^("[^"]*"|'[^']*'|[^\s"'#:-][^:]*?|-[^\s:][^:]*?):(?:\s+(.*))?$/;
+
+export function parseYamlSubset(text) {
+  const lines = stripBom(text).replace(/\r\n?/g, "\n").split("\n");
+  const indentOf = (l) => l.length - l.trimStart().length;
+  const isBlank = (l) => stripComment(l).trim() === "";
+
+  function nextContent(i) {
+    while (i < lines.length && isBlank(lines[i])) i++;
+    return i;
+  }
+
+  function parseMapping(start, parentIndent) {
+    const obj = {};
+    let i = start;
+    let childIndent = null;
+    while (i < lines.length) {
+      if (isBlank(lines[i])) {
+        i++;
+        continue;
+      }
+      const ind = indentOf(lines[i]);
+      if (ind <= parentIndent) break;
+      if (childIndent === null) childIndent = ind;
+      if (ind < childIndent) break;
+      const content = stripComment(lines[i].slice(ind)).trimEnd();
+      if (ind > childIndent || content.startsWith("- ") || content === "-") {
+        i++;
+        continue;
+      }
+      const m = KEY.exec(content);
+      i++;
+      if (!m) continue;
+      const key = parseScalar(m[1]);
+      const value = (m[2] ?? "").trim();
+      if (value === "") {
+        const j = nextContent(i);
+        if (
+          j < lines.length &&
+          stripComment(lines[j]).trimStart().startsWith("-") &&
+          indentOf(lines[j]) >= childIndent
+        ) {
+          const raw = [];
+          while (i < lines.length) {
+            const l = lines[i];
+            if (!isBlank(l)) {
+              const li = indentOf(l);
+              const starts = l.trimStart().startsWith("-");
+              if (li < childIndent || (li === childIndent && !starts)) break;
+            }
+            raw.push(l);
+            i++;
+          }
+          obj[key] = { $seq: raw };
+        } else if (j < lines.length && indentOf(lines[j]) > childIndent) {
+          const [sub, next] = parseMapping(j, childIndent);
+          obj[key] = sub;
+          i = next;
+        } else {
+          obj[key] = null;
+        }
+      } else if (/^[|>][-+0-9]*$/.test(value)) {
+        const raw = [];
+        while (i < lines.length && (lines[i].trim() === "" || indentOf(lines[i]) > childIndent)) {
+          raw.push(lines[i]);
+          i++;
+        }
+        obj[key] = raw.join("\n");
+      } else {
+        obj[key] = parseScalar(value);
+      }
+    }
+    return [obj, i];
+  }
+
+  return parseMapping(0, -1)[0];
+}