vigiles 33.2.0 → 33.3.0

package/dist/skill-links.js

@@ -0,0 +1,255 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VIGILES_PACKAGE = void 0;
+exports.decideSkillLink = decideSkillLink;
+exports.locatePackage = locatePackage;
+exports.isWithinProject = isWithinProject;
+exports.linkPrecondition = linkPrecondition;
+exports.portableTarget = portableTarget;
+exports.planSkillLinks = planSkillLinks;
+exports.relinkTempPath = relinkTempPath;
+exports.writeSkillLink = writeSkillLink;
+exports.linkFailureReason = linkFailureReason;
+exports.skillLinksUsable = skillLinksUsable;
+exports.formatSkillLinks = formatSkillLinks;
+/**
+ * The pure half of how `vigiles init` makes vigiles's skills visible to the
+ * agent in EVERY clone: one relative symlink per shipped skill,
+ * `<skills home>/<name> -> ../../node_modules/vigiles/skills/<name>`, committed
+ * with the repo. The IO half (lstat, readlink, symlink) is `linkVigilesSkills`
+ * in `cli-main.ts`; everything that decides something is here, so it is tested
+ * without a filesystem.
+ *
+ * 🔴 WHY LINKS AND NOT ONLY THE PLUGIN. `npm install vigiles` puts the skills at
+ * `node_modules/vigiles/skills/`, which no harness scans. The Claude Code plugin
+ * install carries them, but it lands in `~/.claude/plugins/` — a fact about ONE
+ * machine. A fresh clone or a fresh container has an empty home directory, and
+ * the project's `enabledPlugins` declaration only makes Claude Code PROMPT for
+ * an install (`./plugin-declaration.ts`); headless, nobody sees the prompt. The
+ * skills were on disk and silently absent. A link is part of the repository, so
+ * it arrives with `git clone` and resolves as soon as `npm install` has run —
+ * the same step every other dependency already needs.
+ *
+ * Both harnesses document following a symlinked skill folder:
+ *
+ * > Claude Code: "a `<skill-name>` entry in the enterprise, personal, or project
+ * > location can be a symlink to a directory elsewhere on disk. Claude Code
+ * > reads `SKILL.md` from the target" (code.claude.com/docs/en/skills, fetched
+ * > 2026-10-07).
+ *
+ * > Codex: "Codex supports symlinked skill folders and follows the symlink
+ * > target when scanning these locations" (learn.chatgpt.com/docs/build-skills,
+ * > fetched 2026-10-07).
+ *
+ * The layout is the one paperlint's `init` already ships (its `link-skills.ts`),
+ * kept on purpose: the links that work in a real consumer are the proven shape.
+ *
+ * ── THE RULES ──────────────────────────────────────────────────────────────
+ *   what to link     every skill the package ships: the installed package's
+ *                    `skills/` when it is installed, the running CLI's own
+ *                    otherwise (the version `init` just declared).
+ *   where it points  `node_modules/vigiles` as the PROJECT spells it, found by
+ *                    walking up no further than the repository root. A link that
+ *                    leaves the repository resolves on this machine only — the
+ *                    defect this module exists to remove. Under pnpm the real
+ *                    path is a version-stamped store directory; a link spelled
+ *                    through `node_modules/vigiles` survives the next upgrade.
+ *   what it touches  only what is missing. An entry that already leads to the
+ *                    shipped skill is kept; ANY other entry of the same name —
+ *                    the user's own skill directory, a file, a link elsewhere —
+ *                    is theirs, and is reported, never replaced.
+ *
+ * Names are not namespaced: a linked skill is `test-harness`, where the plugin's
+ * copy is `vigiles:test-harness`. A user's own skill of the same name therefore
+ * wins by construction (we never replace it) and the report names the skill
+ * they did not get.
+ */
+const node_path_1 = require("node:path");
+const skill_link_target_js_1 = require("./core/skill-link-target.js");
+/** The package whose skills are linked. */
+exports.VIGILES_PACKAGE = "vigiles";
+/**
+ * Decide one entry. A link with OUR target is ours even while it dangles — that
+ * is exactly how a committed link looks in a clone that has not run
+ * `npm install` yet, and calling it foreign would make re-running `init` noisy
+ * in precisely the place it is meant to help.
+ */
+function decideSkillLink(name, entry, want) {
+    switch (entry.kind) {
+        case "missing":
+            return { name, action: "create", target: want.target };
+        case "link":
+            if (entry.target === want.target ||
+                (entry.resolvesTo !== null && entry.resolvesTo === want.real))
+                return { name, action: "keep" };
+            // Provably ours (the shape `init` writes, same skill) but aimed elsewhere —
+            // e.g. linked before a workspace install hoisted the package. Rewrite it.
+            if ((0, skill_link_target_js_1.isVigilesSkillTarget)(entry.target, name))
+                return { name, action: "replace", target: want.target };
+            return {
+                name,
+                action: "refuse",
+                reason: entry.resolvesTo === null
+                    ? `a dangling link to ${entry.target}`
+                    : `a link to ${entry.target}`,
+            };
+        case "directory":
+            return { name, action: "refuse", reason: "a directory (your own skill)" };
+        case "file":
+            return { name, action: "refuse", reason: "a file" };
+    }
+}
+/** Is there a workspace root strictly above `project`, up to the repo root? */
+function insideWorkspace(project, probe) {
+    const walk = (dir) => {
+        if (dir !== project && probe.isWorkspaceRoot(dir))
+            return true;
+        if (probe.isRepoRoot(dir) || (0, node_path_1.dirname)(dir) === dir)
+            return false;
+        return walk((0, node_path_1.dirname)(dir));
+    };
+    return walk(project);
+}
+/**
+ * Node's own lookup — the first `node_modules/vigiles` up the tree — bounded by
+ * the repository root, because a committed link that leaves the repository is a
+ * link only this machine can follow.
+ */
+function locatePackage(project, probe) {
+    // The walk stops at the repository root; with no repository yet (before
+    // `git init`) the project itself is the boundary, or an unrelated ancestor's
+    // node_modules would be linked into it.
+    const repoRoot = (dir) => {
+        if (probe.isRepoRoot(dir))
+            return dir;
+        return (0, node_path_1.dirname)(dir) === dir ? null : repoRoot((0, node_path_1.dirname)(dir));
+    };
+    const boundary = repoRoot(project) ?? project;
+    const walk = (dir) => {
+        const candidate = (0, node_path_1.join)(dir, "node_modules", exports.VIGILES_PACKAGE);
+        if (probe.isPackage(candidate))
+            return { kind: "installed", dir: candidate };
+        if (dir === boundary || (0, node_path_1.dirname)(dir) === dir)
+            return null;
+        return walk((0, node_path_1.dirname)(dir));
+    };
+    const installed = walk(project);
+    if (installed !== null)
+        return installed;
+    return insideWorkspace(project, probe)
+        ? {
+            kind: "unsure",
+            reason: "vigiles isn't installed yet and this package is in a workspace, where the install decides whether it lands in this package's node_modules or the workspace root's — run npm install, then npx vigiles init",
+        }
+        : { kind: "expected", dir: (0, node_path_1.join)(project, "node_modules", exports.VIGILES_PACKAGE) };
+}
+/**
+ * Is the real path `path` the project's own real path or somewhere under it?
+ * Both must be physical (symlink-free), or a link could pass for a child.
+ */
+function isWithinProject(project, path) {
+    const rel = (0, node_path_1.relative)(project, path);
+    // A child can be NAMED `..cache`; only a whole `..` segment leaves the project.
+    return rel.split(node_path_1.sep)[0] !== ".." && !(0, node_path_1.isAbsolute)(rel);
+}
+/**
+ * Why NOT to link, or null to go ahead. A link into a `node_modules/vigiles`
+ * that no install will ever create is a dangling link committed to the repo — a
+ * worse state than no link, because it looks like the job was done.
+ */
+function linkPrecondition(facts) {
+    if (facts.isVigilesItself)
+        return "this is the vigiles repository itself; its skills are the plugin's own skills/";
+    if (!facts.installed && !facts.dependsOnVigiles)
+        return "this repo has no package.json dependency on vigiles, so no install will create node_modules/vigiles for a link to point at; the global install carries the skills here instead";
+    return null;
+}
+/**
+ * A link target as it is committed: `/` separators on every OS. `relative()` on
+ * Windows yields `..\\..\\node_modules\\…`, and a clone on Linux or macOS
+ * reads those backslashes as ordinary filename characters, so the link dangles.
+ */
+function portableTarget(target, separator = node_path_1.sep) {
+    return target.split(separator).join("/");
+}
+function planSkillLinks(input) {
+    const skillsDir = (0, node_path_1.join)(input.site.dir, "skills");
+    return {
+        pending: input.site.kind === "expected",
+        decisions: input.names.map((name) => decideSkillLink(name, input.entries(name), {
+            target: portableTarget((0, node_path_1.relative)(input.physicalHome, (0, node_path_1.join)(skillsDir, name))),
+            real: input.realOf(name),
+        })),
+    };
+}
+/** Where a replacement link is built before it takes the old one's place. */
+function relinkTempPath(entry) {
+    return (0, node_path_1.join)((0, node_path_1.dirname)(entry), `.${(0, node_path_1.basename)(entry)}.vigiles-new`);
+}
+/**
+ * Write the link `decision` asks for. A `replace` never leaves a gap: the new
+ * link is built under a temporary name beside the old one and renamed over it,
+ * which is atomic. Removing the old link first would lose it for good when the
+ * new one cannot be created (a Windows account without the symlink privilege,
+ * a full disk) — a skill that worked yesterday gone, and only a warning to show
+ * for it. Any failure leaves the old link in place and throws.
+ */
+function writeSkillLink(io, entry, target, action) {
+    if (action === "create") {
+        io.symlink(target, entry);
+        return;
+    }
+    const temp = relinkTempPath(entry);
+    // Whatever already sits at the temporary name is not ours to delete: the
+    // `symlink` then fails (EEXIST) and is reported, and both entries stay.
+    io.symlink(target, temp);
+    try {
+        io.rename(temp, entry);
+    }
+    catch (e) {
+        try {
+            // Only the link this call just created is removed.
+            io.unlink(temp);
+        }
+        catch {
+            // Already gone: the rename error is the news.
+        }
+        throw e;
+    }
+}
+/** Why a `symlink` call failed, with the fix when there is a known one. */
+function linkFailureReason(code, message) {
+    const base = `could not create the link: ${message}`;
+    return code === "EPERM"
+        ? `${base} — on Windows, creating a symlink needs Developer Mode (or an elevated shell), and git needs core.symlinks=true to check one out`
+        : base;
+}
+/** At least one shipped skill now reaches the agent through a link. */
+function skillLinksUsable(outcome) {
+    return (outcome.kind === "linked" &&
+        outcome.results.some((r) => r.status !== "skipped"));
+}
+/**
+ * The lines `init` prints. Skipped skills are named one by one: the user loses
+ * that skill, and the reason is theirs to act on.
+ */
+function formatSkillLinks(outcome) {
+    if (outcome.kind === "not-linked")
+        return [`⚠ vigiles's skills were NOT linked — ${outcome.reason}`];
+    const count = (s) => outcome.results.filter((r) => r.status === s).length;
+    const skipped = outcome.results.filter((r) => r.status === "skipped");
+    const mark = skipped.length > 0 ? "⚠" : "✓";
+    return [
+        `${mark} vigiles's ${String(outcome.results.length)} skills → ${outcome.home}/ (relative links into node_modules; commit them): ` +
+            `${String(count("created"))} linked now, ${String(count("present"))} already linked, ` +
+            (count("relinked") > 0 ? `${String(count("relinked"))} relinked, ` : "") +
+            `${String(skipped.length)} skipped`,
+        ...skipped.map((r) => `  ${outcome.home}/${r.name} left alone — it is ${r.reason}. Rename it to get vigiles's ${r.name}.`),
+        ...(outcome.pending
+            ? [
+                "  They resolve once vigiles is installed: run npm install (every clone and container needs it anyway).",
+            ]
+            : []),
+    ];
+}
+//# sourceMappingURL=skill-links.js.map

package/dist/test-coverage.js

@@ -147,6 +147,42 @@ function read(path) {
         return "";
     }
 }
+/**
+ * Is this skill directory a DEPENDENCY's — does it really live under a
+ * `node_modules` that is not the scanned base's own ancestor?
+ *
+ * The `node_modules/**` floor (`EXCLUDE_FLOOR`) is applied to the path as
+ * SPELLED, and `.claude/skills/<name>` spells no `node_modules` even when it is
+ * a link into one — which is exactly what `vigiles init` (and paperlint's)
+ * commits so the agent sees a package's skills in every clone. Those skills are
+ * the package's work, tested by the package; counting them here would report
+ * the repo's own `init` as six untested skills, and fail `--strict`.
+ *
+ * Both the link as written and its real target are asked (see the body).
+ * Measured on the path RELATIVE to the base's real path, so auditing a package
+ * that itself sits in `node_modules` still sees its own skills, and a pnpm
+ * store target (`node_modules/.pnpm/…`) or a hoisted workspace root
+ * (`../../node_modules/…`) both count as dependencies. A link elsewhere (one
+ * shared skills folder linked per skill) is the repo's own and stays graded.
+ * Unresolvable → not a dependency (the skill stays visible: silence is the
+ * worse error here).
+ */
+function isDependencySkill(basePath, skillDir) {
+    try {
+        const base = (0, node_fs_1.realpathSync)(basePath);
+        const inNodeModules = (p) => (0, node_path_1.relative)(base, p).split(node_path_1.sep).includes("node_modules");
+        // Both the link as WRITTEN and where it finally lands: under `npm link`, a
+        // `file:` dependency or a workspace, `node_modules/<pkg>` is itself a link
+        // to a source checkout, so the real path alone names no `node_modules`.
+        const spelled = (0, node_fs_1.lstatSync)(skillDir).isSymbolicLink()
+            ? (0, node_path_1.resolve)((0, node_fs_1.realpathSync)((0, node_path_1.dirname)(skillDir)), (0, node_fs_1.readlinkSync)(skillDir))
+            : skillDir;
+        return inNodeModules(spelled) || inNodeModules((0, node_fs_1.realpathSync)(skillDir));
+    }
+    catch {
+        return false;
+    }
+}
 function discoverSkills(basePath, ignore, layout) {
     const out = [];
     // 🔴 ONE GATE FOR THE WHOLE FUNCTION, and it is structural rather than
@@ -159,7 +195,7 @@ function discoverSkills(basePath, ignore, layout) {
     const skillDir = layout.surfaces.skill;
     if (skillDir === undefined)
         return out;
-    const found = (0, glob_1.globSync)(surfaceGlobs(skillDir, "*/SKILL.md", (0, layout_js_1.materializePrefix)(layout)), { cwd: basePath, ignore });
+    const found = (0, glob_1.globSync)(surfaceGlobs(skillDir, "*/SKILL.md", (0, layout_js_1.materializePrefix)(layout)), { cwd: basePath, ignore }).filter((path) => !isDependencySkill(basePath, (0, node_path_1.join)(basePath, (0, node_path_1.dirname)(path))));
     for (const path of found.sort()) {
         const name = (0, node_path_1.basename)((0, node_path_1.dirname)(path));
         const content = read((0, node_path_1.join)(basePath, path));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "33.2.0",
+  "version": "33.3.0",
   "description": "Audit, test and measure the harness your AI agent runs on — grade your CLAUDE.md / AGENTS.md, skills, subagents and hooks, run them against a scripted model, and measure whether they actually fire.",
   "keywords": [
     "claude-code",