@mnaimfaizy/agent-kit 0.0.0-stage → 1.0.0-alpha.12

package/src/local-tree.mjs

@@ -0,0 +1,190 @@
+// Git tree hashes of paths in the local working copy, as they would be if the
+// working copy were committed now (tracked and untracked files, minus ignored
+// ones, after git's own line-ending rules).
+//
+// Read-only: git runs against a temporary index built from HEAD, and writes
+// any new objects to a temporary object directory that borrows the
+// repository's objects through objects/info/alternates. The Consumer's index,
+// object store and refs are never written. Because the temporary index holds
+// only HEAD plus the Kit-owned paths, a merge conflict elsewhere in the
+// repository does not get in the way.
+//
+// git runs no hooks (core.hooksPath is an empty folder), no fsmonitor, and no
+// configured clean/process filter drivers, so hashing a checkout runs no
+// command that the checkout's or the adopter's git config names.
+
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { firstLine } from "./exec.mjs";
+
+const SAFE_PATH = /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*\/$/;
+
+export const SKIP_WORKTREE_REASON =
+  "some of its files are marked skip-worktree (for example by a sparse checkout) and HEAD has no copy of them to compare";
+export const HEAD_COPY_NOTE =
+  "its files are marked skip-worktree (for example by a sparse checkout), so the copy committed at HEAD was compared";
+
+export class LocalTreeError extends Error {}
+
+/** `filter.<driver>.<key>` config names → the driver names. */
+export function filterDrivers(configNames) {
+  const drivers = new Set();
+  for (const raw of configNames) {
+    const m = /^filter\.(.+)\.[^.]+$/i.exec(raw.trim());
+    if (m) drivers.add(m[1]);
+  }
+  return [...drivers];
+}
+
+/**
+ * @param {{ runner: import("./exec.mjs").Runner, cwd: string, paths: string[] }} opts
+ * @returns {{ root: string, hashes: Map<string, string | null>, skipped: Map<string, string>, notes: Map<string, string> }}
+ *   A null hash means the path is missing locally; `skipped` holds paths that
+ *   could not be compared, with the reason; `notes` explains how a path was compared.
+ */
+export function localTreeHashes({ runner, cwd, paths }) {
+  for (const p of paths) {
+    if (!SAFE_PATH.test(p) || p.split("/").includes("..")) {
+      throw new LocalTreeError(`refusing to hash ${JSON.stringify(p)}`);
+    }
+  }
+  const top = runner("git", ["-C", cwd, "rev-parse", "--show-toplevel"]);
+  if (top.status !== 0) throw new LocalTreeError(`not a git repository: ${firstLine(top.stderr)}`);
+  const root = top.stdout.trim();
+  // --git-common-dir (not --path-format=absolute, which needs git 2.31) may
+  // be relative to `root`; the objects of a linked worktree live there too.
+  const common = runner("git", ["-C", root, "rev-parse", "--git-common-dir"]);
+  if (common.status !== 0) {
+    throw new LocalTreeError(`git rev-parse failed: ${firstLine(common.stderr)}`);
+  }
+  const commonDir = common.stdout.trim();
+  const realObjects = join(isAbsolute(commonDir) ? commonDir : resolve(root, commonDir), "objects");
+  if (/[\r\n]/.test(realObjects) || realObjects.startsWith('"')) {
+    throw new LocalTreeError("the repository path cannot be written to an alternates file");
+  }
+
+  const tmp = mkdtempSync(join(tmpdir(), "agent-kit-tree-"));
+  try {
+    const index = join(tmp, "index");
+    const objects = join(tmp, "objects");
+    const noHooks = join(tmp, "no-hooks");
+    mkdirSync(join(objects, "info"), { recursive: true });
+    mkdirSync(noHooks);
+    // An alternates file, not GIT_ALTERNATE_OBJECT_DIRECTORIES: that variable
+    // splits on ':' on POSIX, so a path containing one would break it.
+    writeFileSync(join(objects, "info", "alternates"), `${realObjects}\n`);
+
+    const safety = [
+      "-c",
+      `core.hooksPath=${noHooks}`,
+      "-c",
+      "core.fsmonitor=false",
+      "-c",
+      "gc.auto=0",
+    ];
+    const listed = runner("git", [
+      "-C",
+      root,
+      "config",
+      "--name-only",
+      "--get-regexp",
+      "^filter\\.",
+    ]);
+    for (const driver of filterDrivers(listed.status === 0 ? listed.stdout.split("\n") : [])) {
+      if (/[=\r\n]/.test(driver)) {
+        throw new LocalTreeError(`cannot turn off git filter driver ${JSON.stringify(driver)}`);
+      }
+      safety.push("-c", `filter.${driver}.clean=`, "-c", `filter.${driver}.process=`);
+      safety.push("-c", `filter.${driver}.required=false`);
+    }
+    const base = ["-C", root, ...safety, "--literal-pathspecs"];
+    const env = { GIT_INDEX_FILE: index, GIT_OBJECT_DIRECTORY: objects };
+    const git = (...args) => runner("git", [...base, ...args], { env });
+    const real = (...args) => runner("git", [...base, ...args]);
+
+    const head = real("rev-parse", "--verify", "--quiet", "HEAD^{commit}");
+    // HEAD gives tracked files their recorded modes (core.fileMode=false on
+    // Windows would otherwise drop executable bits).
+    if (head.status === 0) {
+      const read = git("read-tree", "HEAD");
+      if (read.status !== 0) {
+        throw new LocalTreeError(`git read-tree HEAD failed: ${firstLine(read.stderr)}`);
+      }
+    }
+
+    const hashes = new Map();
+    const skipped = new Map();
+    const notes = new Map();
+    for (const path of paths) {
+      // The real index (read only) knows skip-worktree entries (`S`), which
+      // have no files on disk. Everything else comes from the working copy
+      // (`git add`); only the S files are then reset to HEAD's copy, so local
+      // edits and new files elsewhere in the path still count.
+      const tags = real("ls-files", "-t", "-z", "--", path);
+      const entries = tags.status === 0 ? tags.stdout.split("\0").filter(Boolean) : [];
+      const skipFiles = entries.filter((e) => e.startsWith("S ")).map((e) => e.slice(2));
+      if (skipFiles.length) {
+        const inHead =
+          head.status === 0
+            ? real("ls-tree", "-r", "-z", "--name-only", "HEAD", "--", path)
+            : { status: 1, stdout: "" };
+        const committed = new Set(inHead.stdout.split("\0").filter(Boolean));
+        if (inHead.status !== 0 || skipFiles.some((f) => !committed.has(f))) {
+          skipped.set(path, SKIP_WORKTREE_REASON);
+          continue;
+        }
+      }
+      // --sparse: in a sparse checkout, a path outside the cone may still have
+      // stray files on disk, and plain `git add` refuses to touch it. git
+      // before 2.34 has no --sparse; it then gets a plain add.
+      let add = git("add", "--all", "--sparse", "--", path);
+      if (add.status !== 0 && /unknown option|usage: git add/i.test(add.stderr)) {
+        add = git("add", "--all", "--", path);
+      }
+      // Two refusals that still stage what can be staged, then exit 1: files
+      // force-added under an ignored folder, and (old git) a path outside
+      // the sparse-checkout definition.
+      const benign =
+        /ignored by one of your \.gitignore files|outside of your sparse-checkout definition/i.test(
+          add.stderr,
+        );
+      if (add.status !== 0 && !benign && existsSync(join(root, path))) {
+        throw new LocalTreeError(`git add ${path} failed: ${firstLine(add.stderr)}`);
+      }
+      for (let i = 0; i < skipFiles.length; i += 200) {
+        const reset = git("reset", "--quiet", "HEAD", "--", ...skipFiles.slice(i, i + 200));
+        if (reset.status !== 0) {
+          throw new LocalTreeError(
+            `git reset of skip-worktree files failed: ${firstLine(reset.stderr)}`,
+          );
+        }
+      }
+      const inIndex = git("ls-files", "-z", "--", path);
+      const staged = inIndex.status === 0 ? inIndex.stdout.split("\0").filter(Boolean) : [];
+      if (staged.length === 0) {
+        hashes.set(path, null);
+        continue;
+      }
+      if (skipFiles.length) {
+        // The HEAD-only wording only when nothing came from the working copy.
+        notes.set(
+          path,
+          staged.length === skipFiles.length
+            ? HEAD_COPY_NOTE
+            : `${skipFiles.length} of its ${staged.length} files are marked skip-worktree and were compared as committed at HEAD; the rest came from the working copy`,
+        );
+      }
+      const tree = git("write-tree", `--prefix=${path}`);
+      if (tree.status !== 0) {
+        throw new LocalTreeError(
+          `git write-tree --prefix=${path} failed: ${firstLine(tree.stderr)}`,
+        );
+      }
+      hashes.set(path, tree.stdout.trim());
+    }
+    return { root, hashes, skipped, notes };
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}

package/src/tags.mjs

@@ -0,0 +1,45 @@
+// Release-line tags: vX.Y.Z or vX.Y.Z-(alpha|beta|rc).N, the same shape
+// scripts/verify_release_snapshot.py accepts. The npm package version is the
+// tag without its leading v.
+
+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. */
+export const FIRST_NPM_TAG = "v1.0.0-alpha.12";
+
+/** The first tag that ships kit-owned-paths.txt. */
+export const FIRST_MANIFEST_TAG = "v1.0.0-alpha.11";
+
+export const PACKAGE_NAME = "@mnaimfaizy/agent-kit";
+
+const STAGE_RANK = { alpha: 0, beta: 1, rc: 2, "": 3 };
+
+export function isReleaseTag(tag) {
+  return typeof tag === "string" && TAG_PATTERN.test(tag);
+}
+
+function key(tag) {
+  const m = TAG_PATTERN.exec(tag);
+  if (!m) throw new Error(`not a Release-line tag: ${tag}`);
+  return [Number(m[1]), Number(m[2]), Number(m[3]), STAGE_RANK[m[4] ?? ""], Number(m[5] ?? 0)];
+}
+
+/** Negative if a < b, 0 if equal, positive if a > b. */
+export function compareTags(a, b) {
+  const ka = key(a);
+  const kb = key(b);
+  for (let i = 0; i < ka.length; i++) if (ka[i] !== kb[i]) return ka[i] - kb[i];
+  return 0;
+}
+
+export function versionForTag(tag) {
+  key(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}`;
+}

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];
+}