@mnaimfaizy/agent-kit 1.0.0-beta.1 → 1.0.0-beta.2

package/README.md

@@ -17,6 +17,6 @@ npx @mnaimfaizy/agent-kit upgrade --tag <new-tag>   # move to another tag (asks
 - `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.
+The package version matches the Agent-kit Release line: `@mnaimfaizy/agent-kit@1.0.0-beta.2` is published from tag `v1.0.0-beta.2`, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnaimfaizy/agent-kit",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "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/checks/kit-owned-trees.mjs

@@ -9,6 +9,8 @@ import { result } from "./result.mjs";
 
 const ID = "kit-owned-trees";
 const TITLE = "Kit-owned paths match the pinned tag";
+/** A Kit-owned skill folder, capturing the skill's name. */
+const SKILL_DIR = /^\.claude\/skills\/([^/]+)\/$/;
 
 /**
  * @param {{ runner: import("../exec.mjs").Runner, cwd: string, snapshot: { tag: string, kitOwnedPaths: string[], treeHash: (p: string) => string | null } }} opts
@@ -16,11 +18,24 @@ const TITLE = "Kit-owned paths match the pinned tag";
 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 { hashes, skipped, notes, links } = localTreeHashes({ runner, cwd, paths: kitOwnedPaths });
   const serverUrl = snapshot.serverUrl ?? "https://github.com";
   const bad = [];
   const notChecked = [];
+  const linkedSkills = [];
   for (const path of kitOwnedPaths) {
+    if (links.has(path)) {
+      const link = links.get(path);
+      // npx skills links the skill folder itself. A link inside it, or above it
+      // (a shared .claude/skills, say), is the Consumer's own, so no hint to remove it.
+      const skill = link === path.replace(/\/$/, "") ? SKILL_DIR.exec(path)?.[1] : undefined;
+      bad.push(
+        `${path}: ${link} is a symbolic link or junction, where the tag ships plain files` +
+          (skill ? ` (installing the skill with \`npx skills\` does this)` : ""),
+      );
+      if (skill) linkedSkills.push({ skill, link });
+      continue;
+    }
     if (skipped.has(path)) {
       notChecked.push(`${path}: not checked, ${skipped.get(path)}`);
       continue;
@@ -36,6 +51,16 @@ export function checkKitOwnedTrees({ runner, cwd, snapshot }) {
     }
   }
   const howCompared = [...notes].map(([path, note]) => `${path}: ${note}`);
+  // A link at or inside a Kit-owned path goes when upgrade replaces the path whole
+  // (with --force, since its files then show as deleted). One above every Kit-owned
+  // path (a linked .claude/skills, say) is the Consumer's to sort out.
+  const linked = [...links].map(([path, link]) => ({ folder: path.replace(/\/$/, ""), link }));
+  const unique = (list) => [...new Set(list.map(({ link }) => link))];
+  const linksAtOrInside = unique(
+    linked.filter(({ folder, link }) => link === folder || link.startsWith(`${folder}/`)),
+  );
+  const linksAbove = unique(linked.filter(({ folder, link }) => folder.startsWith(`${link}/`)));
+  const named = (list) => (list.length === 1 ? `${list[0]} is` : `${list.join(", ")} are`);
   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}.`, {
@@ -62,12 +87,30 @@ export function checkKitOwnedTrees({ runner, cwd, snapshot }) {
         ...bad,
         ...notChecked,
         ...howCompared,
+        ...linkedSkills.map(
+          ({ skill, link }) =>
+            `To restore ${skill}, remove the link ${link} (and the copy npx skills made at ` +
+            `.agents/skills/${skill}/), then run the command below: a Consumer gets Kit-owned ` +
+            `skills from the tag, not from npx skills.`,
+        ),
+        ...(linksAtOrInside.length
+          ? [
+              `--force: once ${named(linksAtOrInside)} gone, the files show as deleted, which upgrade ` +
+                `otherwise refuses as uncommitted changes. It discards changes in Kit-owned paths only.`,
+            ]
+          : []),
+        ...linksAbove.map(
+          (link) =>
+            `${link} is a link: Kit-owned paths must be real folders in the repository, not reached ` +
+            `through a link to somewhere else. Whether to replace it (and keep what it points to) ` +
+            `is your call; upgrade refuses to write through it, with or without --force.`,
+        ),
         `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)],
+      fix: [linksAtOrInside.length ? `${upgradeCommand(tag)} --force` : upgradeCommand(tag)],
     },
   );
 }

package/src/kit-tag.mjs

@@ -82,13 +82,22 @@ export function openKitRepo({ runner, repo, serverUrl = DEFAULT_SERVER, remoteUr
   const dir = join(tmp, "repo.git");
   const noHooks = join(tmp, "no-hooks");
   mkdirSync(noHooks);
-  const cleanup = () => rmSync(tmp, { recursive: true, force: true });
+  // The retries are a fallback only: with background maintenance off (below)
+  // no git process is left writing in `tmp` once its command has returned.
+  const cleanup = () =>
+    rmSync(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+  // No background maintenance: `git fetch` ends with `git maintenance run
+  // --auto`, which newer git detaches (maintenance.autoDetach, gc.autoDetach).
+  // The detached process outlives the fetch and can still be writing in the
+  // repository (objects/maintenance.lock, gc.pid) when cleanup() removes it,
+  // which failed cleanup with ENOTEMPTY.
+  const noBackground = ["-c", "maintenance.auto=false", "-c", "gc.auto=0"];
   // No hooks run, whatever the adopter's global git config says.
-  const base = ["-C", dir, "-c", `core.hooksPath=${noHooks}`];
+  const base = ["-C", dir, "-c", `core.hooksPath=${noHooks}`, ...noBackground];
   const git = (...args) => runner("git", [...base, ...args]);
   const gitBytes = (...args) => runner("git", [...base, ...args], { encoding: "buffer" });
   try {
-    const r = runner("git", ["init", "--bare", "--quiet", "--template=", dir]);
+    const r = runner("git", [...noBackground, "init", "--bare", "--quiet", "--template=", dir]);
     if (r.status !== 0) throw new KitTagError(`git init failed: ${firstLine(r.stderr)}`);
   } catch (err) {
     cleanup();

package/src/local-tree.mjs

@@ -13,7 +13,15 @@
 // 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 {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { firstLine } from "./exec.mjs";
@@ -76,11 +84,62 @@ export function gitSafetyArgs({ runner, root, noHooks }) {
   return safety;
 }
 
+/** `lstat`, or null when nothing is there. */
+export function lstatOrNull(path) {
+  try {
+    return lstatSync(path);
+  } catch (err) {
+    if (err.code === "ENOENT" || err.code === "ENOTDIR") return null;
+    throw err;
+  }
+}
+
+/**
+ * The first symbolic link or junction at, above or inside the folder `path`
+ * (relative to `root`, ending in /), as a path without a trailing slash, or
+ * null. git looks straight through a Windows junction, stops at a symlink
+ * with "beyond a symbolic link", and stores a symlink inside a folder as a
+ * link entry, so this is checked before git ever sees the path.
+ */
+export function linkAt(root, path) {
+  const folder = path.replace(/\/$/, "");
+  const parts = folder.split("/");
+  for (let i = 1; i <= parts.length; i++) {
+    const sub = parts.slice(0, i).join("/");
+    const st = lstatOrNull(join(root, sub));
+    if (!st) return null;
+    if (st.isSymbolicLink()) return sub;
+  }
+  return linksUnder(root, folder)[0] ?? null;
+}
+
+/**
+ * Every symbolic link or junction at or inside `rel` (relative to `root`, no
+ * trailing slash), in sorted walk order: never followed or guessed at. doctor
+ * reports what it finds and upgrade refuses to delete through it, so both
+ * agree on what is linked.
+ */
+export function linksUnder(root, rel) {
+  const found = [];
+  const walk = (sub) => {
+    const st = lstatOrNull(join(root, sub));
+    if (!st) return;
+    if (st.isSymbolicLink()) found.push(sub);
+    else if (st.isDirectory()) {
+      for (const name of readdirSync(join(root, sub)).sort()) walk(`${sub}/${name}`);
+    }
+  };
+  walk(rel);
+  return found;
+}
+
 /**
  * @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> }}
+ * @returns {{ root: string, hashes: Map<string, string | null>, skipped: Map<string, string>, notes: Map<string, string>, links: 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.
+ *   could not be compared, with the reason; `notes` explains how a path was compared;
+ *   `links` maps a path that is, sits under, or holds a symbolic link or junction to
+ *   that link. A linked path is never hashed.
  */
 export function localTreeHashes({ runner, cwd, paths }) {
   for (const p of paths) {
@@ -137,7 +196,13 @@ export function localTreeHashes({ runner, cwd, paths }) {
     const hashes = new Map();
     const skipped = new Map();
     const notes = new Map();
+    const links = new Map();
     for (const path of paths) {
+      const link = linkAt(root, path);
+      if (link !== null) {
+        links.set(path, link);
+        continue;
+      }
       // 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
@@ -233,7 +298,7 @@ export function localTreeHashes({ runner, cwd, paths }) {
       }
       hashes.set(path, tree.stdout.trim());
     }
-    return { root, hashes, skipped, notes };
+    return { root, hashes, skipped, notes, links };
   } finally {
     rmSync(tmp, { recursive: true, force: true });
   }

package/src/local-writes.mjs

@@ -3,20 +3,12 @@
 // and carrying out a plan. Both commands plan first and write second: every
 // refusal (a Refusal) is raised while planning, before anything is written.
 
-import {
-  chmodSync,
-  lstatSync,
-  mkdirSync,
-  mkdtempSync,
-  readdirSync,
-  rmSync,
-  writeFileSync,
-} from "node:fs";
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { firstLine } from "./exec.mjs";
 import { EXECUTABLE_MODE } from "./kit-tag.mjs";
-import { fileModeIsOff, gitSafetyArgs } from "./local-tree.mjs";
+import { fileModeIsOff, gitSafetyArgs, linksUnder, lstatOrNull } from "./local-tree.mjs";
 import { checkSafePath } from "./safe-paths.mjs";
 
 /** A reason not to start. Nothing has been written when this is thrown. */
@@ -43,14 +35,8 @@ export function reportRefusal(out, err) {
   return 1;
 }
 
-export function lstatOrNull(path) {
-  try {
-    return lstatSync(path);
-  } catch (err) {
-    if (err.code === "ENOENT" || err.code === "ENOTDIR") return null;
-    throw err;
-  }
-}
+// Defined beside the link walk doctor uses (local-tree.mjs imports nothing from here).
+export { lstatOrNull };
 
 /**
  * Refuse unless `rel` (a repository-relative path, no trailing slash) can be
@@ -95,21 +81,6 @@ export function checkNoLinks(root, rel, { deleted = [] } = {}) {
   }
 }
 
-/** Links inside `rel`: never followed or guessed at. */
-function linksUnder(root, rel) {
-  const found = [];
-  const walk = (sub) => {
-    const st = lstatOrNull(join(root, sub));
-    if (!st) return;
-    if (st.isSymbolicLink()) found.push(sub);
-    else if (st.isDirectory()) {
-      for (const name of readdirSync(join(root, sub)).sort()) walk(`${sub}/${name}`);
-    }
-  };
-  walk(rel);
-  return found;
-}
-
 /** Refuse unless folder `rel` can be deleted whole: checkLocalPath, and no link inside it. */
 export function checkDeletable(root, rel) {
   checkLocalPath(root, rel);