vigiles 33.2.0 → 33.3.0

package/dist/setup-plan.d.ts

@@ -16,7 +16,10 @@ export interface SetupPlan {
     test: boolean;
     /** Wire CI (the `zernie/vigiles@v1` Action; creates a workflow if none). */
     gha: boolean;
-    /** Install the Claude Code plugin (hooks + skills). */
+    /**
+     * Install vigiles's skills + hooks for the agent: the skills LINKED into the
+     * repo (every clone), the Claude Code hooks via the per-machine plugin.
+     */
     plugin: boolean;
     /**
      * Adopt/scaffold the instruction file(s) into typed `.spec.ts` (the compiled
@@ -193,15 +196,18 @@ export interface InstallPlan {
     notes: string[];
     /** Whether this method writes files into the consumer's repo (vendoring). */
     vendors: boolean;
+    /**
+     * Link the package's shipped skills into the repo's skills home
+     * (`src/skill-links.ts`). True only where the vendor documents following a
+     * symlinked skill folder — a link the harness skips is a silent absence.
+     */
+    linkSkills: boolean;
+    /**
+     * The global install carries HOOKS as well as skills, so linked skills do not
+     * replace it (see {@link shouldRunGlobalInstall}).
+     */
+    globalInstallCarriesHooks: boolean;
 }
-/** Per-harness install plan. `hasClaude` gates the auto-run `claude plugin` CLI
- * (else the same two steps are printed as `/plugin` slash commands).
- *
- * Both methods install GLOBALLY, never into the repo: Claude through its plugin
- * marketplace (~/.claude/plugins/), Codex through the cross-agent `skills` CLI
- * with `-g -y` (the global store ~/.agents/skills/, which Codex reads). Codex
- * gets the skills but NOT hooks — Codex hook wiring (.codex/config.toml [hooks])
- * is not automated yet. */
 /**
  * The SHIPPED consumer skills (the `skills/` dir, published via `plugin.json`) —
  * the ONLY ones a user's install should get. The cross-agent `skills` CLI would
@@ -212,9 +218,43 @@ export interface InstallPlan {
  * dogfood test in `src/adapters/claude-code/skills-dogfood.test.ts`.
  */
 export declare const SHIPPED_SKILLS: readonly ["adopt-spec", "debug-my-harness", "edit-spec", "linter-docs", "strengthen", "test-harness"];
+/**
+ * Per-harness install plan. `hasClaude` gates the auto-run `claude plugin` CLI
+ * (else the same two steps are printed as `/plugin` slash commands).
+ *
+ * TWO CARRIERS, by what each one reaches. The SKILLS are linked into the repo
+ * (`linkSkills`), so every clone and container has them after `npm install`. The
+ * GLOBAL installs reach one machine: Claude Code's plugin (~/.claude/plugins/)
+ * is still the only carrier of vigiles's Claude Code HOOKS, so it always runs;
+ * Codex's `skills` CLI install (~/.agents/skills/) carries skills only, so it
+ * runs only when the links could not be made (no `package.json` to install
+ * into). Codex's nudge hooks are written into `.codex/config.toml` directly.
+ *
+ * THE CODEX GLOBAL COMMAND. The cross-agent `skills` CLI with `-g -y` installs
+ * to the global store ~/.agents/skills/ (NOT the repo, and NOT ~/.codex/ —
+ * verified against the real CLI). It is scoped to the SHIPPED skills with `-s`
+ * — without it the `skills` CLI installs EVERY SKILL.md in the repo, leaking
+ * the contributor-only .claude/skills/ into the user's global store
+ * (#dogfood-I2; confirmed — the CLI's `-l` list shows 17 skills for this repo,
+ * incl. .claude/skills). The `-s` parser is SPACE-separated (it consumes
+ * consecutive non-dash args), NOT comma-separated — a comma list is read as one
+ * literal skill name, matches nothing, and the install exits 1 (verified against
+ * the real `skills@1.5.20` arg parser).
+ */
 export declare function planPluginInstall(harnesses: readonly string[], opts: {
     hasClaude: boolean;
 }): InstallPlan[];
+/**
+ * Run a plan's GLOBAL install, given whether the skills were linked into the
+ * repo? Skip it only when linked skills make it redundant — when it carries
+ * nothing but skills. Running it anyway would list every skill twice (Codex:
+ * "If two skills share the same `name`, Codex doesn't merge them; both can
+ * appear in skill selectors"). Claude Code's plugin carries the hooks, so it
+ * always runs; its skills are namespaced `vigiles:<name>` and load beside the
+ * linked `<name>` (a known, documented duplicate until the hooks move into the
+ * repo too).
+ */
+export declare function shouldRunGlobalInstall(plan: Readonly<Pick<InstallPlan, "globalInstallCarriesHooks">>, skillsLinked: boolean): boolean;
 /** One vigiles-managed Codex hook: a `[[hooks.<event>]]` entry. */
 export interface CodexPluginHook {
     readonly event: string;

package/dist/setup-plan.js

@@ -18,6 +18,7 @@ exports.shouldPrompt = shouldPrompt;
 exports.collectSetupAnswers = collectSetupAnswers;
 exports.gateOnlyInvitation = gateOnlyInvitation;
 exports.planPluginInstall = planPluginInstall;
+exports.shouldRunGlobalInstall = shouldRunGlobalInstall;
 exports.codexPluginHooks = codexPluginHooks;
 exports.applyCodexPluginHooks = applyCodexPluginHooks;
 exports.resolvePlan = resolvePlan;
@@ -225,7 +226,7 @@ async function collectSetupAnswers(ask) {
     }
     const pillars = (await ask("Set up which pillars? [both/lint/test] (both): ", "both")).toLowerCase();
     const gha = isYesAnswer(await ask("Wire CI (GitHub Action)? [Y/n]: ", "y"));
-    const plugin = isYesAnswer(await ask("Install the Claude Code plugin (hooks + skills)? [Y/n]: ", "y"));
+    const plugin = isYesAnswer(await ask("Install vigiles's skills + hooks for your agent (skills linked into the repo, hooks via the Claude Code plugin)? [Y/n]: ", "y"));
     // Structural gating (broken tools/hooks/MCP/collisions) is always on. This asks
     // about the WORKFLOW tier — a spec per file + a test per surface — which a clean
     // repo can fail just for not having done the work yet, so it's the recommended
@@ -289,14 +290,6 @@ function gateOnlyInvitation(plan) {
         return null;
     return "→ Want your agent to maintain this + measure whether your skills fire? Run `npx vigiles init` and choose 'full' (installs the skills). Optional — the gate above already works.";
 }
-/** Per-harness install plan. `hasClaude` gates the auto-run `claude plugin` CLI
- * (else the same two steps are printed as `/plugin` slash commands).
- *
- * Both methods install GLOBALLY, never into the repo: Claude through its plugin
- * marketplace (~/.claude/plugins/), Codex through the cross-agent `skills` CLI
- * with `-g -y` (the global store ~/.agents/skills/, which Codex reads). Codex
- * gets the skills but NOT hooks — Codex hook wiring (.codex/config.toml [hooks])
- * is not automated yet. */
 /**
  * The SHIPPED consumer skills (the `skills/` dir, published via `plugin.json`) —
  * the ONLY ones a user's install should get. The cross-agent `skills` CLI would
@@ -314,70 +307,111 @@ exports.SHIPPED_SKILLS = [
     "strengthen",
     "test-harness",
 ];
+/**
+ * Per-harness install plan. `hasClaude` gates the auto-run `claude plugin` CLI
+ * (else the same two steps are printed as `/plugin` slash commands).
+ *
+ * TWO CARRIERS, by what each one reaches. The SKILLS are linked into the repo
+ * (`linkSkills`), so every clone and container has them after `npm install`. The
+ * GLOBAL installs reach one machine: Claude Code's plugin (~/.claude/plugins/)
+ * is still the only carrier of vigiles's Claude Code HOOKS, so it always runs;
+ * Codex's `skills` CLI install (~/.agents/skills/) carries skills only, so it
+ * runs only when the links could not be made (no `package.json` to install
+ * into). Codex's nudge hooks are written into `.codex/config.toml` directly.
+ *
+ * THE CODEX GLOBAL COMMAND. The cross-agent `skills` CLI with `-g -y` installs
+ * to the global store ~/.agents/skills/ (NOT the repo, and NOT ~/.codex/ —
+ * verified against the real CLI). It is scoped to the SHIPPED skills with `-s`
+ * — without it the `skills` CLI installs EVERY SKILL.md in the repo, leaking
+ * the contributor-only .claude/skills/ into the user's global store
+ * (#dogfood-I2; confirmed — the CLI's `-l` list shows 17 skills for this repo,
+ * incl. .claude/skills). The `-s` parser is SPACE-separated (it consumes
+ * consecutive non-dash args), NOT comma-separated — a comma list is read as one
+ * literal skill name, matches nothing, and the install exits 1 (verified against
+ * the real `skills@1.5.20` arg parser).
+ */
 function planPluginInstall(harnesses, opts) {
-    return harnesses.map((harness) => {
-        if (harness === "claude") {
-            return {
-                harness,
-                commands: opts.hasClaude
-                    ? [
-                        "claude plugin marketplace add zernie/vigiles",
-                        "claude plugin install vigiles@vigiles",
-                    ]
-                    : [],
-                successMessage: "✓ Installed the vigiles plugin (hooks + skills) into ~/.claude/plugins/",
-                manualSteps: [
-                    "/plugin marketplace add zernie/vigiles",
-                    "/plugin install vigiles@vigiles",
-                ],
-                notes: [
-                    "Installs globally to ~/.claude/plugins/ — nothing is added to your repo.",
-                ],
-                vendors: false,
-            };
-        }
-        if (harness === "codex") {
-            // The cross-agent `skills` CLI with `-g -y` installs to the global store
-            // ~/.agents/skills/ (NOT the repo, and NOT ~/.codex/ — verified against
-            // the real CLI). Skills install globally; the proactive NUDGE hooks
-            // (eval-lock + refs) are wired into the repo's .codex/config.toml by
-            // `init` (see codexPluginHooks / wireCodexHooks) — Codex config is
-            // repo-committed, so that's the idiomatic place.
-            // Scope to the SHIPPED skills with `-s` — without it the `skills` CLI
-            // installs EVERY SKILL.md in the repo, leaking the contributor-only
-            // .claude/skills/ into the user's global store (#dogfood-I2; confirmed —
-            // the CLI's `-l` list shows 17 skills for this repo, incl. .claude/skills).
-            // The `-s` parser is SPACE-separated (it consumes consecutive non-dash
-            // args), NOT comma-separated — a comma list is read as one literal skill
-            // name, matches nothing, and the install exits 1 (verified against the
-            // real `skills@1.5.20` arg parser).
-            const skillScope = `-s ${exports.SHIPPED_SKILLS.join(" ")}`;
-            return {
-                harness,
-                commands: [
-                    `npx --yes skills add zernie/vigiles -a codex ${skillScope} -g -y`,
-                ],
-                successMessage: "✓ Installed the vigiles skills into ~/.agents/skills/ (global, not vendored)",
-                manualSteps: [
-                    `npx skills add zernie/vigiles -a codex ${skillScope} -g -y`,
-                ],
-                notes: [
-                    "Codex reads AGENTS.md directly; the skills install globally to ~/.agents/skills/ (not the repo).",
-                    "The eval-lock + refs NUDGE hooks are wired into .codex/config.toml (repo-committed, the Codex norm).",
-                    "Still manual on Codex: the SessionStart lint summary + compile-on-edit/pre-edit guards (no harness-neutral entrypoint yet).",
-                ],
-                vendors: true,
-            };
-        }
+    return harnesses.map((harness) => ({
+        ...globalInstallFor(harness, opts),
+        ...skillCarriers(harness),
+    }));
+}
+/**
+ * How the skills and the hooks travel for one harness. Linking is on only where
+ * the vendor documents following a symlinked skill folder (quoted in
+ * `./skill-links.ts`); the global install "carries hooks" only for Claude Code,
+ * whose plugin is where its hooks live.
+ */
+function skillCarriers(harness) {
+    if (harness === "claude")
+        return { linkSkills: true, globalInstallCarriesHooks: true };
+    // eslint-disable-next-line local/no-harness-names -- init's per-harness install plan is keyed by harness name, like the global install beside it
+    if (harness === "codex")
+        return { linkSkills: true, globalInstallCarriesHooks: false };
+    return { linkSkills: false, globalInstallCarriesHooks: false };
+}
+/** The global install half of {@link planPluginInstall}, per harness. */
+function globalInstallFor(harness, opts) {
+    if (harness === "claude") {
         return {
             harness,
-            commands: [],
-            successMessage: "",
-            manualSteps: [],
-            notes: [`No plugin install path for harness '${harness}'.`],
+            commands: opts.hasClaude
+                ? [
+                    "claude plugin marketplace add zernie/vigiles",
+                    "claude plugin install vigiles@vigiles",
+                ]
+                : [],
+            successMessage: "✓ Installed the vigiles plugin (hooks + skills) into ~/.claude/plugins/",
+            manualSteps: [
+                "/plugin marketplace add zernie/vigiles",
+                "/plugin install vigiles@vigiles",
+            ],
+            notes: [
+                "The plugin installs globally to ~/.claude/plugins/ and carries the hooks (and a namespaced copy of the skills, listed as vigiles:<name>) on this machine only.",
+            ],
             vendors: false,
         };
-    });
+    }
+    if (harness === "codex") {
+        const skillScope = `-s ${exports.SHIPPED_SKILLS.join(" ")}`;
+        return {
+            harness,
+            commands: [
+                `npx --yes skills add zernie/vigiles -a codex ${skillScope} -g -y`,
+            ],
+            successMessage: "✓ Installed the vigiles skills into ~/.agents/skills/ (global, not vendored)",
+            manualSteps: [
+                `npx skills add zernie/vigiles -a codex ${skillScope} -g -y`,
+            ],
+            notes: [
+                "Codex reads AGENTS.md directly; the skills install globally to ~/.agents/skills/ (not the repo).",
+                "The eval-lock + refs NUDGE hooks are wired into .codex/config.toml (repo-committed, the Codex norm).",
+                "Still manual on Codex: the SessionStart lint summary + compile-on-edit/pre-edit guards (no harness-neutral entrypoint yet).",
+            ],
+            vendors: true,
+        };
+    }
+    return {
+        harness,
+        commands: [],
+        successMessage: "",
+        manualSteps: [],
+        notes: [`No plugin install path for harness '${harness}'.`],
+        vendors: false,
+    };
+}
+/**
+ * Run a plan's GLOBAL install, given whether the skills were linked into the
+ * repo? Skip it only when linked skills make it redundant — when it carries
+ * nothing but skills. Running it anyway would list every skill twice (Codex:
+ * "If two skills share the same `name`, Codex doesn't merge them; both can
+ * appear in skill selectors"). Claude Code's plugin carries the hooks, so it
+ * always runs; its skills are namespaced `vigiles:<name>` and load beside the
+ * linked `<name>` (a known, documented duplicate until the hooks move into the
+ * repo too).
+ */
+function shouldRunGlobalInstall(plan, skillsLinked) {
+    return plan.globalInstallCarriesHooks || !skillsLinked;
 }
 /**
  * vigiles's proactive nudges, wired into a Codex repo's `.codex/config.toml`.

package/dist/skill-links.d.ts

@@ -0,0 +1,183 @@
+/** The package whose skills are linked. */
+export declare const VIGILES_PACKAGE = "vigiles";
+/** What occupies `<skills home>/<name>` today, as the IO edge observed it. */
+export type SkillEntry = {
+    readonly kind: "missing";
+} | {
+    readonly kind: "link";
+    /** The link's stored target, exactly as `readlink` returns it. */
+    readonly target: string;
+    /** Where it resolves, or null when it dangles. */
+    readonly resolvesTo: string | null;
+} | {
+    readonly kind: "directory";
+} | {
+    readonly kind: "file";
+};
+/** What `init` should do about one skill. */
+export type SkillLinkDecision = {
+    readonly name: string;
+    /** `replace`: an earlier `init`'s link that now points at the wrong place. */
+    readonly action: "create" | "replace";
+    readonly target: string;
+} | {
+    readonly name: string;
+    readonly action: "keep";
+} | {
+    readonly name: string;
+    readonly action: "refuse";
+    readonly reason: string;
+};
+/** The link `init` wants for one skill. */
+export interface WantedLink {
+    /** The relative target to write (and to recognise on a re-run). */
+    readonly target: string;
+    /** The real path of the shipped skill, or null while it is not installed. */
+    readonly real: string | null;
+}
+/**
+ * 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.
+ */
+export declare function decideSkillLink(name: string, entry: SkillEntry, want: WantedLink): SkillLinkDecision;
+/** Where the package is, as the project spells it. */
+export type PackageSite = 
+/** Installed: `<ancestor>/node_modules/vigiles`, inside the repository. */
+{
+    readonly kind: "installed";
+    readonly dir: string;
+}
+/** Not installed yet: where npm puts the devDependency `init` declares. */
+ | {
+    readonly kind: "expected";
+    readonly dir: string;
+}
+/**
+ * Not installed, and the project is a member of a workspace: npm and yarn
+ * hoist its dependencies to the workspace ROOT's `node_modules`, pnpm keeps
+ * them in the member's own, and a hoist can be refused by a version
+ * conflict. Which one happens is decided by the install, so no link is made
+ * before it — a guessed link can dangle for good.
+ */
+ | {
+    readonly kind: "unsure";
+    readonly reason: string;
+};
+/** What the walk may ask of the filesystem. */
+export interface PackageProbe {
+    /** Is `dir` an installed vigiles package (its `package.json` names it)? */
+    readonly isPackage: (dir: string) => boolean;
+    /** Is `dir` the repository root (it holds `.git`)? The walk stops there. */
+    readonly isRepoRoot: (dir: string) => boolean;
+    /** Is `dir` a workspace root (`workspaces` in package.json, or pnpm-workspace.yaml)? */
+    readonly isWorkspaceRoot: (dir: string) => boolean;
+}
+/**
+ * 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.
+ */
+export declare function locatePackage(project: string, probe: PackageProbe): PackageSite;
+/**
+ * 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.
+ */
+export declare function isWithinProject(project: string, path: string): boolean;
+/** The facts that decide whether linking makes sense at all here. */
+export interface LinkFacts {
+    /** The project IS vigiles — its skills are the plugin's own `skills/`. */
+    readonly isVigilesItself: boolean;
+    /** `package.json` declares vigiles (so `npm install` will put it in node_modules). */
+    readonly dependsOnVigiles: boolean;
+    /** The package already resolves from the project. */
+    readonly installed: boolean;
+}
+/**
+ * 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.
+ */
+export declare function linkPrecondition(facts: LinkFacts): string | null;
+/** Everything {@link planSkillLinks} needs, observed by the IO edge. */
+export interface SkillLinkInput {
+    /** The skills the package ships. */
+    readonly names: readonly string[];
+    readonly site: Exclude<PackageSite, {
+        kind: "unsure";
+    }>;
+    /**
+     * The skills home as it PHYSICALLY exists (`.claude` may itself be a link).
+     * A relative link target resolves against the directory that holds the link.
+     */
+    readonly physicalHome: string;
+    readonly entries: (name: string) => SkillEntry;
+    /** The real path of the installed skill, or null. */
+    readonly realOf: (name: string) => string | null;
+}
+/** The decisions, and whether the links will dangle until `npm install`. */
+export interface SkillLinkPlan {
+    readonly pending: boolean;
+    readonly decisions: readonly SkillLinkDecision[];
+}
+/**
+ * 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.
+ */
+export declare function portableTarget(target: string, separator?: string): string;
+export declare function planSkillLinks(input: SkillLinkInput): SkillLinkPlan;
+/** The three filesystem calls that write a link; the IO edge passes the real ones. */
+export interface LinkIo {
+    readonly symlink: (target: string, path: string) => void;
+    readonly rename: (from: string, to: string) => void;
+    readonly unlink: (path: string) => void;
+}
+/** Where a replacement link is built before it takes the old one's place. */
+export declare function relinkTempPath(entry: string): string;
+/**
+ * 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.
+ */
+export declare function writeSkillLink(io: LinkIo, entry: string, target: string, action: "create" | "replace"): void;
+/** Why a `symlink` call failed, with the fix when there is a known one. */
+export declare function linkFailureReason(code: string, message: string): string;
+/** One skill's result after the IO ran. */
+export type SkillLinkResult = {
+    readonly name: string;
+    readonly status: "created" | "relinked" | "present";
+} | {
+    readonly name: string;
+    readonly status: "skipped";
+    readonly reason: string;
+};
+/** What `init` did about the skills for one harness. */
+export type SkillLinkOutcome = {
+    readonly kind: "linked";
+    /** Repo-relative skills home, e.g. `.claude/skills`. */
+    readonly home: string;
+    /**
+     * The same home with every symlink resolved, repo-relative with `/`.
+     * Git refuses a pathspec that runs through a symlink, so the commit hint
+     * names this one.
+     */
+    readonly physicalHome: string;
+    readonly pending: boolean;
+    readonly results: readonly SkillLinkResult[];
+} | {
+    readonly kind: "not-linked";
+    readonly reason: string;
+};
+/** At least one shipped skill now reaches the agent through a link. */
+export declare function skillLinksUsable(outcome: SkillLinkOutcome): boolean;
+/**
+ * The lines `init` prints. Skipped skills are named one by one: the user loses
+ * that skill, and the reason is theirs to act on.
+ */
+export declare function formatSkillLinks(outcome: SkillLinkOutcome): readonly string[];
+//# sourceMappingURL=skill-links.d.ts.map