vigiles 32.1.0 → 33.0.0

package/dist/hook-check-install.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installHookCheck = installHookCheck;
+/**
+ * Writes the start-of-session check described in `src/hook-check.ts` and adds its
+ * entry to each harness's settings. `vigiles compile` calls this once, after it
+ * has merged the hooks.
+ *
+ * The list of files comes from the settings as they are now, not from the hooks
+ * this run compiled. So compiling one hook does not make the check forget the
+ * others, and compiling twice changes nothing. The entry is found again by the
+ * script's path, so a recompile replaces it in place and leaves any
+ * `SessionStart` hook the user wrote alone.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const hook_check_js_1 = require("./hook-check.js");
+const hook_install_js_1 = require("./hook-install.js");
+function isShellAdapter(adapter) {
+    return adapter.shellHooks;
+}
+/** One harness's settings as a plain object, or `undefined` if the file does not exist yet. */
+function readSettings(adapter, cwd) {
+    const file = (0, node_path_1.resolve)(cwd, adapter.layout.settingsPath);
+    return (0, node_fs_1.existsSync)(file)
+        ? adapter.layout.settings.parse((0, node_fs_1.readFileSync)(file, "utf-8"))
+        : undefined;
+}
+/** Add the check's `SessionStart` entry to one harness's settings, or replace it where it already is. */
+function registerCheck(adapter, existing, cwd) {
+    const ref = (0, hook_install_js_1.hookGateRef)(hook_check_js_1.HOOK_CHECK_REF, adapter.layout.projectRootTokens);
+    const merged = adapter.hookProtocol.mergeRegistrations(existing, {
+        SessionStart: [
+            { hooks: [{ type: "command", command: `sh ${ref} || exit 0` }] },
+        ],
+    }, hook_check_js_1.HOOK_CHECK_REF);
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(cwd, adapter.layout.settingsPath), adapter.layout.settings.render(merged));
+}
+function installHookCheck(adapters, cwd = process.cwd()) {
+    const found = adapters.filter(isShellAdapter).flatMap((adapter) => {
+        const settings = readSettings(adapter, cwd);
+        return settings === undefined ? [] : [{ adapter, settings }];
+    });
+    const { paths, unsafe } = (0, hook_check_js_1.checkPaths)(found.flatMap((f) => (0, hook_check_js_1.commandsIn)(f.settings.hooks)));
+    for (const path of unsafe) {
+        console.warn(`⚠ hook-check: ${path} has characters the check cannot quote safely, so it is NOT covered.`);
+    }
+    if (paths.length === 0)
+        return;
+    const script = (0, node_path_1.resolve)(cwd, hook_check_js_1.HOOK_CHECK_REF);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(script), { recursive: true });
+    (0, node_fs_1.writeFileSync)(script, (0, hook_check_js_1.renderHookCheck)(paths));
+    for (const { adapter, settings } of found)
+        registerCheck(adapter, settings, cwd);
+    console.log(`✓ ${hook_check_js_1.HOOK_CHECK_REF} → SessionStart notice for ${paths.length} wired hook file(s)`);
+}
+//# sourceMappingURL=hook-check-install.js.map

package/dist/hook-check.d.ts

@@ -0,0 +1,36 @@
+/** Where the generated script is written. It is committed, next to the hook sources. */
+export declare const HOOK_CHECK_REF = ".vigiles/hook-check.sh";
+/**
+ * Every `command` string in a parsed hooks block. It looks for the key `command`
+ * instead of following one layout, because the layout depends on the harness
+ * (Claude Code nests commands under a matcher block, Codex's TOML is flat).
+ */
+export declare function commandsIn(node: unknown): string[];
+export interface CheckPaths {
+    /** Paths relative to the project, sorted, no duplicates: what the script tests. */
+    readonly paths: readonly string[];
+    /**
+     * Paths the check found but cannot safely write into the script. `compile`
+     * warns about each one, because a path left out is a hook the check does not
+     * cover.
+     */
+    readonly unsafe: readonly string[];
+}
+/**
+ * The files that the compiled-hook commands in `commands` need, as paths relative
+ * to the project. Two kinds of path are left out on purpose: absolute paths
+ * (another machine's checkout will not have them) and paths that use any variable
+ * except the project root, such as `$HOME` or a plugin root (we cannot resolve
+ * them here).
+ */
+export declare function checkPaths(commands: readonly string[]): CheckPaths;
+/**
+ * The text of the script. The same paths always give the same text, so a
+ * recompile that finds the same hooks writes the same bytes.
+ *
+ * The script prints JSON with an `additionalContext` field instead of plain text.
+ * That form is confirmed for the start of a session on both Claude Code and
+ * Codex; plain text is only confirmed on Claude Code.
+ */
+export declare function renderHookCheck(paths: readonly string[]): string;
+//# sourceMappingURL=hook-check.d.ts.map

package/dist/hook-check.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOOK_CHECK_REF = void 0;
+exports.commandsIn = commandsIn;
+exports.checkPaths = checkPaths;
+exports.renderHookCheck = renderHookCheck;
+/**
+ * A check that runs when a session starts and says "run npm install" if files
+ * that the repo's hooks need are missing.
+ *
+ * Why it exists (#312). A compiled hook lives in two places: the wiring in
+ * `.claude/settings.json` (stored in git) and the files that wiring runs (in
+ * `node_modules`, stored by npm). A fresh container, a merge that brings new
+ * wiring, or a dependency update can change one without the other. Today the
+ * first sign is a hook refusing the first command. This check notices one step
+ * earlier and names the fix.
+ *
+ * What it does not do: fix anything. If a hook that can block commands has
+ * missing files, it still refuses every shell command, including the install.
+ * The check only says so before the first command is tried, so a person can run
+ * the install from a terminal outside the session. Removing the cause would need
+ * hook files stored in git next to their wiring; that is a separate decision
+ * (#312).
+ *
+ * Three rules shape the code:
+ *
+ * - It must work when nothing is installed. So the script is plain POSIX `sh`
+ *   using only built-in commands (no node, no vigiles, no grep), and it is
+ *   committed, so it arrives together with the wiring.
+ * - It only prints and always exits 0. We have not verified what exit code 2
+ *   does at session start, and a check that could fail would be one more way to
+ *   break the session it is meant to help. It is wired `|| exit 0`, like any
+ *   reminder.
+ * - It lists only what a compiled hook needs: the hook files named by
+ *   `hook-runtime run-program` commands in the settings, plus the local runtime
+ *   when it is started by path. Reporting any other script (say
+ *   `scripts/build.sh`) as missing in a fresh clone would be a false alarm,
+ *   because `npm install` does not create it.
+ *
+ * The list is read from the settings after `compile` has merged into them. So it
+ * also covers hooks that another tool wrote there, and it does not shrink when
+ * `compile` is run on just one hook. A hook added after the last `compile` is
+ * not covered until the next one.
+ *
+ * Limits: it checks that a file exists, not that it loads. A package that is
+ * present but no longer exports what a hook imports passes this check and still
+ * breaks. A path is recognised by the same pattern the coverage code uses, which
+ * has no room for spaces or quotes, so a hook under such a path is not covered,
+ * and the check cannot say so.
+ */
+const coverage_probe_js_1 = require("./coverage-probe.js");
+/** Where the generated script is written. It is committed, next to the hook sources. */
+exports.HOOK_CHECK_REF = ".vigiles/hook-check.sh";
+/**
+ * Every `command` string in a parsed hooks block. It looks for the key `command`
+ * instead of following one layout, because the layout depends on the harness
+ * (Claude Code nests commands under a matcher block, Codex's TOML is flat).
+ */
+function commandsIn(node) {
+    if (Array.isArray(node))
+        return node.flatMap(commandsIn);
+    if (typeof node !== "object" || node === null)
+        return [];
+    return Object.entries(node).flatMap(([key, value]) => key === "command" && typeof value === "string"
+        ? [value]
+        : commandsIn(value));
+}
+/** How a command may spell the project root. It is removed to leave a relative path. */
+const PROJECT_ROOT_PREFIX = /^\$(?:\{CLAUDE_PROJECT_DIR\}|CLAUDE_PROJECT_DIR)\//;
+/** The characters a path may contain. It is written into a shell string and a JSON string. */
+const SAFE_PATH = /^[A-Za-z0-9._@+/-]+$/;
+/**
+ * The files that the compiled-hook commands in `commands` need, as paths relative
+ * to the project. Two kinds of path are left out on purpose: absolute paths
+ * (another machine's checkout will not have them) and paths that use any variable
+ * except the project root, such as `$HOME` or a plugin root (we cannot resolve
+ * them here).
+ */
+function checkPaths(commands) {
+    const relative = commands
+        .flatMap(coverage_probe_js_1.runProgramFiles)
+        .map((file) => file.replace(PROJECT_ROOT_PREFIX, ""))
+        .filter((file) => !file.startsWith("/") && !file.includes("$"));
+    const unique = [...new Set(relative)].sort();
+    return {
+        paths: unique.filter((p) => SAFE_PATH.test(p)),
+        unsafe: unique.filter((p) => !SAFE_PATH.test(p)),
+    };
+}
+/**
+ * The text of the script. The same paths always give the same text, so a
+ * recompile that finds the same hooks writes the same bytes.
+ *
+ * The script prints JSON with an `additionalContext` field instead of plain text.
+ * That form is confirmed for the start of a session on both Claude Code and
+ * Codex; plain text is only confirmed on Claude Code.
+ */
+function renderHookCheck(paths) {
+    const list = paths.map((p) => `  '${p}'`).join(" \\\n");
+    return `#!/bin/sh
+# Generated by \`vigiles compile\`. Do not edit; the next compile rewrites it.
+#
+# Start-of-session notice (vigiles #312). If a file that a compiled hook runs is
+# not installed, it says so in the first turn. It uses only plain sh and shell
+# built-ins (no node, no node_modules, no vigiles), because "not installed" is
+# exactly the situation it reports. It only prints and always exits 0.
+#
+# It does not fix anything. A hook that can block commands, with its files
+# missing, refuses every shell command including the install, so the install has
+# to be run from a terminal outside the session.
+root="\${CLAUDE_PROJECT_DIR:-.}"
+missing=""
+for p in \\
+${list}
+do
+  [ -e "$root/$p" ] || missing="$missing $p"
+done
+if [ -n "$missing" ]; then
+  printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\\n' \\
+    "vigiles: hook files that this repo runs are not installed:$missing. Run npm ci (or npm install) from a terminal outside this session before anything else. A blocking hook whose files are missing refuses every shell command in a session, the install included; a reminder-only hook that cannot load is skipped. See docs/compiled-hooks.md, When a hook cannot load."
+fi
+exit 0
+`;
+}
+//# sourceMappingURL=hook-check.js.map

package/dist/hook-install.d.ts

@@ -1,12 +1,100 @@
-import type { DispatchKind } from "./core/hook-program.js";
+import { type CompilableMarker, type SourceKind } from "./source-kinds.js";
 /** The agnostic, committed home for hook SOURCE — one dir, cross-adapter. */
 export declare const HOOKS_DIR = ".vigiles/hooks";
 /** The committed home for registered context-provider SOURCE (v2). */
 export declare const PROVIDERS_DIR = ".vigiles/providers";
-/** Discover hook source files under {@link HOOKS_DIR} (stamps excluded). */
-export declare function discoverHookFiles(cwd: string): string[];
-/** Discover registered-provider source files under {@link PROVIDERS_DIR}. */
-export declare function discoverProviderFiles(cwd: string): string[];
+/** What discovery found in one source directory, split by what `compile` owes each part. */
+export interface Discovered {
+    /** Files this directory's role compiles: `.hook.` files in `.vigiles/hooks/`, `.provider.` files in `.vigiles/providers/`. */
+    readonly claimed: readonly string[];
+    /**
+     * Runnable files nothing claims here. `compile` REFUSES these out loud
+     * ({@link unclaimedMessage}); dropping them would make a hook that lost its
+     * marker vanish from the build without a word.
+     */
+    readonly unclaimed: readonly string[];
+}
+/** Discover hook sources under {@link HOOKS_DIR}: `.hook.` files, and the runnable files that are nobody's. */
+export declare function discoverHookFiles(cwd: string): Discovered;
+/** Discover registered-provider sources under {@link PROVIDERS_DIR}. */
+export declare function discoverProviderFiles(cwd: string): Discovered;
+/** Why an explicit `compile` argument is an error rather than a hook, a refusal or a skip. */
+export type InvalidArgReason = "missing" | "directory" | "not-a-source";
+/** What `vigiles compile <files…>` makes of the paths it was handed. */
+export interface HookArgs {
+    readonly hooks: readonly string[];
+    /** Runnable files nothing claims (or a marked file in the wrong directory): refused, with the fix. */
+    readonly unclaimed: readonly string[];
+    /** Named on purpose, not compilable (a test, a stamp…): said out loud, not an error. */
+    readonly skipped: readonly {
+        readonly path: string;
+        readonly kind: SourceKind["kind"];
+    }[];
+    /** Not a file at all, or not a source: an error, the way it always was. */
+    readonly invalid: readonly {
+        readonly path: string;
+        readonly reason: InvalidArgReason;
+    }[];
+}
+/** What the file system says a path is. Injected so the rules below stay pure. */
+export type PathProbe = (path: string) => "file" | "directory" | "missing" | "other";
+/**
+ * Sort explicit `compile` arguments by the same classifier discovery uses, so
+ * `compile guard.mjs` and a bare `compile` give the same answer about it — for a
+ * path ANYWHERE, not just under `.vigiles/hooks/`: `compile .claude/hooks/x.mjs`
+ * or a plugin's `hooks/guard.mjs` is refused unless it carries `.hook.`.
+ *
+ * A path that is missing, a directory or not a regular file is an error (it used
+ * to fail, and the first version of the marker rule turned it into a green run).
+ * The one lenient case exists for a shell glob (`compile .vigiles/hooks/*`): a
+ * test, declaration or stamp is reported as skipped, and so is a README or
+ * `.gitkeep` — but only inside the two vigiles source directories, where a glob
+ * would sweep one up. A `/etc/passwd` is not a README.
+ */
+export declare function partitionHookArgs(args: readonly string[], probe?: PathProbe): HookArgs;
+/** The line `compile` prints for an argument it cannot treat as a hook source at all. */
+export declare function invalidArgMessage(path: string, reason: InvalidArgReason): string;
+/**
+ * Discovery, shaped like {@link partitionHookArgs}'s answer, so `compile` handles
+ * "no arguments" and "these paths" through one code path afterwards.
+ */
+export declare function discoveredHookArgs(cwd: string): HookArgs;
+/**
+ * The ONE shell command that renames an unclaimed file to its marked name and
+ * (for a hook) recompiles it. Every path is single-quoted: this is printed by a
+ * tool and pasted by a person, and a repository can plant a file name that is a
+ * command.
+ *
+ * 🔴 THE HOOK COMMAND COPIES FIRST AND DELETES LAST, and that order is the
+ * point. Already-wired hooks keep running after an upgrade: the runtime loads
+ * whatever path `settings.json` names, and never asks what a file is called. So
+ * the break is the NEXT compile, and a plain `mv` + `compile` has one bad
+ * moment — the old path is gone and the wiring still names it. For a gate
+ * wired `|| exit 2` that is a hook that cannot load, which blocks every Bash
+ * call (the repair is a file write, not a command). Compiling the renamed copy
+ * while the old file still exists, and deleting the old one only after that
+ * compile succeeded, has no such moment: if anything fails the old hook is
+ * still on disk and still wired. `compile` replaces the old wiring itself
+ * ({@link ownedRefs}), so nothing is left naming the deleted path.
+ *
+ * 🔴 `cp -n`, because the marked name may already exist: a plain `cp` replaced
+ * an edited `guard.hook.mjs` with the stale `guard.mjs`, and the weaker hook
+ * became the wired gate. {@link unclaimedMessage} checks first and prints no
+ * command at all in that case; `-n` is for the file that appears in between.
+ */
+export declare function renameCommand(path: string, role: CompilableMarker): string;
+/**
+ * {@link unclaimedMessage} with the one fact it cannot know, read off the disk:
+ * whether the marked name is already there.
+ */
+export declare function unclaimedReport(path: string, role: CompilableMarker, cwd?: string): string;
+/**
+ * The text `compile` prints for one file it will not compile, with the exact
+ * command to fix it. `targetExists` is whether the marked name is already on
+ * disk: then there is nothing safe to copy, and the message says to merge by
+ * hand instead.
+ */
+export declare function unclaimedMessage(path: string, role: CompilableMarker, targetExists?: boolean): string;
 interface CommandHook {
     readonly type: "command";
     readonly command: string;
@@ -73,41 +161,6 @@ export declare function normalizeHookRef(hookPath: string, cwd?: string): string
  * it can be given — see {@link hookGateRef} for the same fallback.
  */
 export declare function hookRuntimeRef(projectRootTokens: readonly string[] | undefined): string;
-/**
- * What the shell must do when the runtime above CANNOT START — a missing
- * `node_modules/vigiles`, an unreadable file, an interpreter that dies before a
- * single line of ours runs. No code of ours executes in that case, so the policy
- * has to be expressed in the emitted command or not at all.
- *
- * 🔴 THIS IS NOT A NEW POLICY. `runHookProgramCommand`'s load-failure branch has
- * decided it since 2026-08: *"an inject's purpose is to ADD context, not to
- * ENFORCE a decision … Gates (file, bash, prompt, stop) remain conservative and
- * fail closed."* That branch only reaches failures that happen AFTER the runtime
- * starts. This carries the same rule one layer out, to the failures that happen
- * before it.
- *
- * WHY THE SPLIT, RATHER THAN ONE ANSWER FOR EVERYTHING — the two failures are
- * not comparable:
- *
- *   A GATE THAT SILENTLY PASSES IS WORSE THAN NO GATE. Its whole value is the
- *   refusal, and a harness that reports protection it is not providing is the
- *   one state worse than admitting it has none. So a gate whose runtime is
- *   missing exits 2: loud, blocking, and the cause is on stderr.
- *
- *   A NUDGE THAT BLOCKS COSTS THE WHOLE REPOSITORY. Measured here 2026-08-10:
- *   merge-conflict markers in `package.json` stopped every hook loading, the
- *   Bash gate then refused `git merge --abort` — the one command that undoes the
- *   cause — and the session could not be repaired from inside. A reminder is
- *   never worth that, so a nudge exits 0 and says nothing it cannot say.
- *
- * The role is not a flag someone can flip: `Reaction` has no `deny` and an
- * inject returns context, so "nudge" is a fact about the TYPE the author chose.
- *
- * (Industry does not agree on one answer either — husky and lefthook skip,
- * pre-commit fails. Which is itself the argument for deciding by role instead
- * of picking one and imposing it on both.)
- */
-export declare function hookRuntimeMissingExit(kind: DispatchKind): 0 | 2;
 export declare function hookGateRef(ref: string, projectRootTokens: readonly string[] | undefined): string;
 /**
  * Idempotently merge a compiled hook's block into an existing `settings.json`