ronce-racine 0.7.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/hooks/README.md +60 -10
- package/dist/hooks/readme-freshness.mjs +9 -7
- package/dist/hooks/skill-reminder.mjs +12 -7
- package/dist/hooks/truncate-bash-output.mjs +17 -7
- package/dist/hooks/truncate-output.mjs +25 -11
- package/dist/install.js +15 -3
- package/dist/src/settings.js +134 -7
- package/dist/src/uninstall.js +11 -6
- package/docs/decisions.md +40 -0
- package/docs/postmortems/2026-08-24-hook-portability.md +216 -0
- package/package.json +4 -3
package/dist/hooks/README.md
CHANGED
|
@@ -7,6 +7,56 @@ Hooks are authored in TypeScript but SHIP BUILT: the installer copies `.mjs` fil
|
|
|
7
7
|
> **Note** - the `install.ts` installer copies the selected hooks and automatically composes the merged `settings.json` snippet - the manual wiring below is only useful for a hand install.
|
|
8
8
|
|
|
9
9
|
|
|
10
|
+
## Wiring rule: exec form, always
|
|
11
|
+
|
|
12
|
+
Every snippet below uses the **exec form** - `"command"` holds the executable,
|
|
13
|
+
`"args"` holds the arguments:
|
|
14
|
+
|
|
15
|
+
```json
|
|
16
|
+
{ "type": "command", "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/skill-reminder.mjs"] }
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Not the shell form (`"command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/x.mjs"`),
|
|
20
|
+
which shipped until 0.7.0 and broke for every adopter whose project path
|
|
21
|
+
contained a space - the shell split the expanded path at the space, and on a
|
|
22
|
+
Windows box without Git Bash the unbraced `$CLAUDE_PROJECT_DIR` was never
|
|
23
|
+
expanded at all. Exec form spawns with no shell: each argument is passed exactly
|
|
24
|
+
as written, and `${CLAUDE_PROJECT_DIR}` braced is substituted by Claude Code
|
|
25
|
+
itself rather than by whichever shell happens to be there.
|
|
26
|
+
|
|
27
|
+
Two constraints worth knowing:
|
|
28
|
+
|
|
29
|
+
- **`node` plus a script path, never the script as the executable.** On Windows
|
|
30
|
+
exec form needs `command` to resolve to a real binary; `node.exe` is one
|
|
31
|
+
everywhere. The `.cmd` shims in `node_modules/.bin` are not.
|
|
32
|
+
- **A hook needing shell syntax stays in shell form** - a pipe, `&&`, `|| true`.
|
|
33
|
+
Then every placeholder must be wrapped in double quotes (see the
|
|
34
|
+
`precommit-scan` snippet below), because the shell does the tokenizing.
|
|
35
|
+
|
|
36
|
+
`ronce-racine install` writes the exec form and repairs a pre-0.8 shell-form
|
|
37
|
+
wiring in place, so re-running the installer is enough to pick this up.
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## Permission gate: the rewriting hooks answer `allow`
|
|
42
|
+
|
|
43
|
+
`bash-npm-silent` and `truncate-output` change the command that runs. Claude Code
|
|
44
|
+
only applies an `updatedInput` when the hook answers
|
|
45
|
+
`permissionDecision: "allow"`, so **every command these two rewrite is
|
|
46
|
+
auto-approved and skips the permission prompt you would otherwise see.**
|
|
47
|
+
|
|
48
|
+
Concretely, with both installed, these no longer prompt: `npm install`, `npm ci`
|
|
49
|
+
(which run `postinstall` scripts), `cargo build/test/clippy`, `curl …`,
|
|
50
|
+
`docker build/logs`, `rustup …`, and unbounded `git log`/`git diff`. Commands
|
|
51
|
+
they do not match are unaffected.
|
|
52
|
+
|
|
53
|
+
This is a real widening of what runs without asking. If that trade is not one you
|
|
54
|
+
want, do not install these two hooks - or wire them under an `if` rule narrowing
|
|
55
|
+
them to the command classes you accept. The other hooks in this directory observe
|
|
56
|
+
without rewriting and do not answer `allow`.
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
10
60
|
## Composition rule: a hook is never alone on its event
|
|
11
61
|
|
|
12
62
|
Several plugins can observe the same Claude Code event, and `PreToolUse`
|
|
@@ -40,7 +90,7 @@ Locates skills in this order: `$CLAUDE_PROJECT_DIR/.claude/skills`, `./.claude/s
|
|
|
40
90
|
{
|
|
41
91
|
"hooks": {
|
|
42
92
|
"UserPromptSubmit": [
|
|
43
|
-
{ "hooks": [{ "type": "command", "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/skill-reminder.mjs" }] }
|
|
93
|
+
{ "hooks": [{ "type": "command", "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/skill-reminder.mjs"] }] }
|
|
44
94
|
]
|
|
45
95
|
}
|
|
46
96
|
}
|
|
@@ -64,7 +114,7 @@ Leaves interactive `npm install <pkg>` calls (adding a dependency) untouched.
|
|
|
64
114
|
"PreToolUse": [
|
|
65
115
|
{ "matcher": "Bash",
|
|
66
116
|
"hooks": [{ "type": "command",
|
|
67
|
-
"command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/bash-npm-silent.mjs" }] }
|
|
117
|
+
"command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/bash-npm-silent.mjs"] }] }
|
|
68
118
|
]
|
|
69
119
|
}
|
|
70
120
|
}
|
|
@@ -88,7 +138,7 @@ Leaves interactive `npm install <pkg>` calls (adding a dependency) untouched.
|
|
|
88
138
|
"PreToolUse": [
|
|
89
139
|
{ "matcher": "Bash",
|
|
90
140
|
"hooks": [{ "type": "command",
|
|
91
|
-
"command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/truncate-output.mjs" }] }
|
|
141
|
+
"command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/truncate-output.mjs"] }] }
|
|
92
142
|
]
|
|
93
143
|
}
|
|
94
144
|
}
|
|
@@ -111,7 +161,7 @@ Writes a session memo to `~/.claude/projects/<repo-slug>/sessions/<branch>.md` (
|
|
|
111
161
|
"hooks": {
|
|
112
162
|
"Stop": [
|
|
113
163
|
{ "hooks": [{ "type": "command",
|
|
114
|
-
"command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/session-writer.mjs" }] }
|
|
164
|
+
"command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/session-writer.mjs"] }] }
|
|
115
165
|
]
|
|
116
166
|
}
|
|
117
167
|
}
|
|
@@ -129,7 +179,7 @@ Re-reads the memo (written by `session-writer`) and injects it as `additionalCon
|
|
|
129
179
|
"SessionStart": [
|
|
130
180
|
{ "matcher": "compact",
|
|
131
181
|
"hooks": [{ "type": "command",
|
|
132
|
-
"command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/session-inject.mjs" }] }
|
|
182
|
+
"command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/session-inject.mjs"] }] }
|
|
133
183
|
]
|
|
134
184
|
}
|
|
135
185
|
}
|
|
@@ -146,7 +196,7 @@ Injects the memo as `systemMessage` into the compaction prompt, so the generated
|
|
|
146
196
|
"hooks": {
|
|
147
197
|
"PreCompact": [
|
|
148
198
|
{ "hooks": [{ "type": "command",
|
|
149
|
-
"command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/session-precompact.mjs" }] }
|
|
199
|
+
"command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/session-precompact.mjs"] }] }
|
|
150
200
|
]
|
|
151
201
|
}
|
|
152
202
|
}
|
|
@@ -165,7 +215,7 @@ If the session starts in a linked git worktree (not the main worktree) and the m
|
|
|
165
215
|
"hooks": {
|
|
166
216
|
"SessionStart": [
|
|
167
217
|
{ "hooks": [{ "type": "command",
|
|
168
|
-
"command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/worktree-env-setup.mjs" }] }
|
|
218
|
+
"command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/worktree-env-setup.mjs"] }] }
|
|
169
219
|
]
|
|
170
220
|
}
|
|
171
221
|
}
|
|
@@ -205,7 +255,7 @@ terminal does not go through it - keep a CI job for that guarantee.
|
|
|
205
255
|
"hooks": {
|
|
206
256
|
"PreToolUse": [
|
|
207
257
|
{ "matcher": "Bash", "hooks": [{ "type": "command",
|
|
208
|
-
"command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/readme-freshness.mjs" }] }
|
|
258
|
+
"command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/readme-freshness.mjs"] }] }
|
|
209
259
|
]
|
|
210
260
|
}
|
|
211
261
|
}
|
|
@@ -229,7 +279,7 @@ exec npx tsx "$CLAUDE_PROJECT_DIR/.claude/skills/commit-readiness-review/scripts
|
|
|
229
279
|
"PreToolUse": [
|
|
230
280
|
{ "matcher": "Bash",
|
|
231
281
|
"hooks": [{ "type": "command",
|
|
232
|
-
"command": "npx tsx $CLAUDE_PROJECT_DIR/.claude/skills/commit-readiness-review/scripts/precommit-scan.ts || true" }] }
|
|
282
|
+
"command": "npx tsx \"${CLAUDE_PROJECT_DIR}/.claude/skills/commit-readiness-review/scripts/precommit-scan.ts\" || true" }] }
|
|
233
283
|
]
|
|
234
284
|
}
|
|
235
285
|
}
|
|
@@ -241,4 +291,4 @@ exec npx tsx "$CLAUDE_PROJECT_DIR/.claude/skills/commit-readiness-review/scripts
|
|
|
241
291
|
|
|
242
292
|
The `install.ts` installer copies the selected hooks and automatically composes the merged `settings.json` snippet - this is the recommended method.
|
|
243
293
|
|
|
244
|
-
For a manual install: copy the desired `.
|
|
294
|
+
For a manual install: copy the desired `.mjs` files into `<repo>/.claude/hooks/`, then add the corresponding wiring to `<repo>/.claude/settings.json`. Paths use `${CLAUDE_PROJECT_DIR}` (substituted by Claude Code itself) - no hardcoded absolute path, and no reliance on a shell to expand it.
|
|
@@ -21,12 +21,13 @@
|
|
|
21
21
|
* `git push` in their own terminal does not go through it - use the CI job for
|
|
22
22
|
* that guarantee.
|
|
23
23
|
*
|
|
24
|
-
* @version 1.
|
|
25
|
-
* @last-reviewed 2026-08-
|
|
24
|
+
* @version 1.1.0
|
|
25
|
+
* @last-reviewed 2026-08-24
|
|
26
26
|
*/
|
|
27
27
|
import { readFileSync, existsSync } from 'node:fs';
|
|
28
28
|
import { spawnSync } from 'node:child_process';
|
|
29
29
|
import { join } from 'node:path';
|
|
30
|
+
import { pathToFileURL } from 'node:url';
|
|
30
31
|
/** Paths whose change can invalidate a README claim. Docs alone cannot. */
|
|
31
32
|
const STRUCTURAL = /^(install\.ts|package\.json|skills\/|rules\/|hooks\/|agents\/|scripts\/|templates\/|\.claude-plugin\/)/;
|
|
32
33
|
const VERDICT_OK = 'README_OK';
|
|
@@ -151,9 +152,10 @@ function main() {
|
|
|
151
152
|
else
|
|
152
153
|
emit('allow', message);
|
|
153
154
|
}
|
|
154
|
-
//
|
|
155
|
-
//
|
|
156
|
-
//
|
|
157
|
-
|
|
158
|
-
|
|
155
|
+
// Compare URLs, never parse the path: pathToFileURL normalizes the separator,
|
|
156
|
+
// so this holds on win32 where a basename split on "/" never matches, and it is
|
|
157
|
+
// blind to the .ts -> .mjs rename the build performs. Both traps cost us a
|
|
158
|
+
// silently dead hook once each (see docs/postmortems/2026-08-24-hook-portability.md).
|
|
159
|
+
const isMain = import.meta.url === pathToFileURL(process.argv[1] ?? '').href;
|
|
160
|
+
if (isMain)
|
|
159
161
|
main();
|
|
@@ -6,12 +6,12 @@
|
|
|
6
6
|
* quoted triggers + the words of the name against the prompt.
|
|
7
7
|
* NEVER blocks (exit 0 no matter what); emits nothing if there is no match.
|
|
8
8
|
*
|
|
9
|
-
* settings.json wiring (see hooks/README.md):
|
|
10
|
-
* "UserPromptSubmit": [{ "hooks": [{ "type": "command",
|
|
11
|
-
* "
|
|
9
|
+
* settings.json wiring (see hooks/README.md) - exec form, no shell involved:
|
|
10
|
+
* "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "node",
|
|
11
|
+
* "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/skill-reminder.mjs"] }] }]
|
|
12
12
|
*
|
|
13
|
-
* @version 1.
|
|
14
|
-
* @last-reviewed 2026-
|
|
13
|
+
* @version 1.1.0
|
|
14
|
+
* @last-reviewed 2026-08-24
|
|
15
15
|
*/
|
|
16
16
|
import { readFileSync, readdirSync, existsSync } from "node:fs";
|
|
17
17
|
import { join, dirname } from "node:path";
|
|
@@ -50,8 +50,13 @@ function loadSkills(dir) {
|
|
|
50
50
|
if (!existsSync(p))
|
|
51
51
|
continue;
|
|
52
52
|
const raw = readFileSync(p, "utf8");
|
|
53
|
-
|
|
54
|
-
|
|
53
|
+
// \r?\n, not \n: with core.autocrlf=true (the Git default on Windows) a
|
|
54
|
+
// checkout materializes SKILL.md as CRLF, and an LF-only delimiter matched
|
|
55
|
+
// none of them - the hook then suggested only the skills that happened to
|
|
56
|
+
// stay LF. Same reason the capture is bounded to the line rather than `.*`,
|
|
57
|
+
// which would keep a trailing \r.
|
|
58
|
+
const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw);
|
|
59
|
+
const desc = fm && /description:\s*([^\r\n]*)/.exec(fm[1]);
|
|
55
60
|
if (desc)
|
|
56
61
|
out.push({ name, triggers: triggers(name, desc[1]) });
|
|
57
62
|
}
|
|
@@ -6,10 +6,11 @@
|
|
|
6
6
|
* exceeds the character threshold.
|
|
7
7
|
* On error (exit ≠ 0), the full output is preserved for debugging.
|
|
8
8
|
*
|
|
9
|
-
* @version 1.
|
|
10
|
-
* @last-reviewed 2026-
|
|
9
|
+
* @version 1.1.0
|
|
10
|
+
* @last-reviewed 2026-08-24
|
|
11
11
|
*/
|
|
12
12
|
import { spawnSync } from 'node:child_process';
|
|
13
|
+
import { pathToFileURL } from 'node:url';
|
|
13
14
|
export const THRESHOLD = 4000;
|
|
14
15
|
export const HEAD_LINES = 20;
|
|
15
16
|
export const TAIL_LINES = 20;
|
|
@@ -34,6 +35,14 @@ function main() {
|
|
|
34
35
|
maxBuffer: 50 * 1024 * 1024,
|
|
35
36
|
stdio: ['inherit', 'pipe', 'inherit'],
|
|
36
37
|
});
|
|
38
|
+
// A wrapper that cannot spawn must SAY so. Returning stdout ?? '' with exit 0
|
|
39
|
+
// reported the user's command as a silent success and swallowed its output
|
|
40
|
+
// whole - the worst outcome available, and the one a missing `bash` produces
|
|
41
|
+
// (Git for Windows is optional; Claude Code then falls back to PowerShell).
|
|
42
|
+
if (result.error) {
|
|
43
|
+
process.stderr.write(`truncate-bash-output: cannot run the wrapped command (${result.error.message})\n`);
|
|
44
|
+
process.exit(1);
|
|
45
|
+
}
|
|
37
46
|
const output = result.stdout ?? '';
|
|
38
47
|
const exitCode = result.status ?? 1;
|
|
39
48
|
if (exitCode !== 0) {
|
|
@@ -42,9 +51,10 @@ function main() {
|
|
|
42
51
|
}
|
|
43
52
|
process.stdout.write(truncateOutput(output));
|
|
44
53
|
}
|
|
45
|
-
//
|
|
46
|
-
//
|
|
47
|
-
//
|
|
48
|
-
|
|
49
|
-
|
|
54
|
+
// Compare URLs, never parse the path: pathToFileURL normalizes the separator,
|
|
55
|
+
// so this holds on win32 where a basename split on "/" never matches, and it is
|
|
56
|
+
// blind to the .ts -> .mjs rename the build performs. Both traps cost us a
|
|
57
|
+
// silently dead hook once each (see docs/postmortems/2026-08-24-hook-portability.md).
|
|
58
|
+
const isMain = import.meta.url === pathToFileURL(process.argv[1] ?? '').href;
|
|
59
|
+
if (isMain)
|
|
50
60
|
main();
|
|
@@ -10,10 +10,12 @@
|
|
|
10
10
|
*
|
|
11
11
|
* Bypass strategy: if the command contains `# no-truncate`, we leave it untouched.
|
|
12
12
|
*
|
|
13
|
-
* @version 2.
|
|
14
|
-
* @last-reviewed 2026-
|
|
13
|
+
* @version 2.1.0
|
|
14
|
+
* @last-reviewed 2026-08-24
|
|
15
15
|
*/
|
|
16
16
|
import { readFileSync } from 'node:fs';
|
|
17
|
+
import { join } from 'node:path';
|
|
18
|
+
import { fileURLToPath, pathToFileURL } from 'node:url';
|
|
17
19
|
const VERBOSE_PATTERNS = [
|
|
18
20
|
/^\s*cargo\s+(build|test|clippy|check|fmt|doc|run)/,
|
|
19
21
|
// `npm install`/`npm ci` are handled by the bash-npm-silent hook (avoid a
|
|
@@ -49,7 +51,16 @@ export function wrapCommand(cmd, hookDir) {
|
|
|
49
51
|
// `: 'cmd';` prefix does not (it breaks on `echo it's fine`).
|
|
50
52
|
// Newlines are flattened, otherwise the comment would swallow the next line.
|
|
51
53
|
const readable = cmd.replace(/\s*\n\s*/g, ' ').trim();
|
|
52
|
-
|
|
54
|
+
// Single quotes keep spaces and backslashes literal (a Windows hookDir is full
|
|
55
|
+
// of both), but they do not survive an apostrophe in the path: `'` has to be
|
|
56
|
+
// closed, escaped and reopened. `/home/o'brien/...` is rarer than a space, not
|
|
57
|
+
// rarer than never.
|
|
58
|
+
const helper = quoteForShell(join(hookDir, 'truncate-bash-output.mjs'));
|
|
59
|
+
return `TRUNCATE_CMD_B64=${encoded} node ${helper} # ${readable}`;
|
|
60
|
+
}
|
|
61
|
+
/** POSIX single-quoting: the only form that is literal for every other character. */
|
|
62
|
+
export function quoteForShell(value) {
|
|
63
|
+
return `'${value.replace(/'/g, `'\\''`)}'`;
|
|
53
64
|
}
|
|
54
65
|
function readStdin() {
|
|
55
66
|
try {
|
|
@@ -76,10 +87,12 @@ function main() {
|
|
|
76
87
|
if (!cmd || !isVerboseCommand(cmd))
|
|
77
88
|
return;
|
|
78
89
|
// Resolving the hooks directory: the CLAUDE_PROJECT_DIR variable takes priority,
|
|
79
|
-
// otherwise a path relative to this file (for local execution / tests)
|
|
90
|
+
// otherwise a path relative to this file (for local execution / tests).
|
|
91
|
+
// fileURLToPath, never URL.pathname: on win32 the latter yields a percent-encoded
|
|
92
|
+
// "/C:/Users/First%20LAST/..." that no shell and no runtime can resolve.
|
|
80
93
|
const hookDir = process.env.CLAUDE_PROJECT_DIR
|
|
81
|
-
?
|
|
82
|
-
: new URL('.', import.meta.url).
|
|
94
|
+
? join(process.env.CLAUDE_PROJECT_DIR, '.claude', 'hooks')
|
|
95
|
+
: fileURLToPath(new URL('.', import.meta.url)).replace(/[\\/]$/, '');
|
|
83
96
|
const output = {
|
|
84
97
|
hookSpecificOutput: {
|
|
85
98
|
hookEventName: 'PreToolUse',
|
|
@@ -92,9 +105,10 @@ function main() {
|
|
|
92
105
|
};
|
|
93
106
|
process.stdout.write(JSON.stringify(output));
|
|
94
107
|
}
|
|
95
|
-
//
|
|
96
|
-
//
|
|
97
|
-
//
|
|
98
|
-
|
|
99
|
-
|
|
108
|
+
// Compare URLs, never parse the path: pathToFileURL normalizes the separator,
|
|
109
|
+
// so this holds on win32 where a basename split on "/" never matches, and it is
|
|
110
|
+
// blind to the .ts -> .mjs rename the build performs. Both traps cost us a
|
|
111
|
+
// silently dead hook once each (see docs/postmortems/2026-08-24-hook-portability.md).
|
|
112
|
+
const isMain = import.meta.url === pathToFileURL(process.argv[1] ?? '').href;
|
|
113
|
+
if (isMain)
|
|
100
114
|
main();
|
package/dist/install.js
CHANGED
|
@@ -30,6 +30,7 @@ import { interactiveSelect } from "./src/selector.js";
|
|
|
30
30
|
// Re-exported so importers (and the test suite) keep a single entry point.
|
|
31
31
|
export { canonicalHash, copyPath, describeSource, isStale } from "./src/lock.js";
|
|
32
32
|
export { CATALOG } from "./src/catalog.js";
|
|
33
|
+
export { hookCommand, wiredHookName } from "./src/settings.js";
|
|
33
34
|
export { applySelectorKey } from "./src/selector.js";
|
|
34
35
|
/**
|
|
35
36
|
* Reads the lockfile, or exits 2 saying why.
|
|
@@ -209,12 +210,23 @@ async function doInstall(repo, opts) {
|
|
|
209
210
|
// announces itself as healthy, and stays that way (issue #1).
|
|
210
211
|
if (collectedWirings.length > 0) {
|
|
211
212
|
const settingsPath = join(dotclaude, "settings.json");
|
|
212
|
-
|
|
213
|
+
// The lockfile's hooks, so a legacy wiring is repaired even when this run's
|
|
214
|
+
// detection no longer selects that hook (installed once with --all, signal
|
|
215
|
+
// since gone). Without it, "re-run the installer" only fixes what is picked.
|
|
216
|
+
const installedHookFiles = (prevLock?.installed ?? [])
|
|
217
|
+
.filter((t) => t.startsWith("hook:"))
|
|
218
|
+
.map((t) => t.slice("hook:".length));
|
|
219
|
+
const { added, rewired, backedUp, malformed } = mergeHookSettings(dotclaude, collectedWirings, installedHookFiles);
|
|
220
|
+
const backupNote = backedUp && !malformed ? " (backup: settings.json.bak)" : "";
|
|
213
221
|
if (malformed)
|
|
214
222
|
console.log(`\n⚠ ${settingsPath} was not valid JSON (or its hooks section had an unexpected shape) - backed up to settings.json.bak and rewritten.`);
|
|
215
223
|
if (added > 0)
|
|
216
|
-
console.log(`${malformed ? "" : "\n"}Wired ${added} hook(s) into ${settingsPath}${
|
|
217
|
-
|
|
224
|
+
console.log(`${malformed ? "" : "\n"}Wired ${added} hook(s) into ${settingsPath}${backupNote}.`);
|
|
225
|
+
// Worth its own line: it means the wirings that were there did not work, or
|
|
226
|
+
// were duplicated. Folding it into "no change" would hide a repair.
|
|
227
|
+
if (rewired > 0)
|
|
228
|
+
console.log(`${added > 0 || malformed ? "" : "\n"}Repaired ${rewired} pre-existing wiring(s) to the exec form${added > 0 ? "" : backupNote}.`);
|
|
229
|
+
if (added === 0 && rewired === 0 && !malformed)
|
|
218
230
|
console.log(`\nHooks already wired in ${settingsPath} - no change.`);
|
|
219
231
|
console.log(`(details: .claude/hooks/README.md)`);
|
|
220
232
|
}
|
package/dist/src/settings.js
CHANGED
|
@@ -5,7 +5,113 @@ import { readFileSync, existsSync, writeFileSync } from "node:fs";
|
|
|
5
5
|
import { join } from "node:path";
|
|
6
6
|
import { shippedHookName } from "./paths.js";
|
|
7
7
|
import { copyPath } from "./lock.js";
|
|
8
|
-
|
|
8
|
+
/**
|
|
9
|
+
* The wiring the installer writes: EXEC FORM, spawned with no shell at all.
|
|
10
|
+
*
|
|
11
|
+
* The shell form (`node $CLAUDE_PROJECT_DIR/.claude/hooks/x.mjs`) shipped until
|
|
12
|
+
* 0.7.0 and broke on any project path containing a space - the shell split the
|
|
13
|
+
* expanded path, and on a Windows box without Git Bash the unbraced variable was
|
|
14
|
+
* never expanded to begin with. Exec form passes each argument verbatim, and
|
|
15
|
+
* `${CLAUDE_PROJECT_DIR}` braced is substituted by Claude Code itself rather
|
|
16
|
+
* than by whatever shell happens to be there.
|
|
17
|
+
*
|
|
18
|
+
* `node` + a script path, never the script as the executable: on Windows exec
|
|
19
|
+
* form needs a real binary, and node.exe is one on every platform.
|
|
20
|
+
*/
|
|
21
|
+
export function hookCommand(commandFile) {
|
|
22
|
+
return {
|
|
23
|
+
type: "command",
|
|
24
|
+
command: "node",
|
|
25
|
+
args: [`\${CLAUDE_PROJECT_DIR}/.claude/hooks/${shippedHookName(commandFile)}`],
|
|
26
|
+
};
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Any reference to a shipped hook, whatever shape it takes.
|
|
30
|
+
*
|
|
31
|
+
* The leading separator is optional so a relative `node .claude/hooks/x.mjs`
|
|
32
|
+
* counts, but the character before `.claude` is still constrained, so
|
|
33
|
+
* `/opt/my.claude/hooks/x.mjs` does not. The extension is captured loosely
|
|
34
|
+
* because the same hook has been wired as `.ts` (pre-0.5, run through tsx) and
|
|
35
|
+
* as `.mjs` (since): both name the same hook, and an installer that only
|
|
36
|
+
* recognizes today's spelling appends a duplicate beside yesterday's.
|
|
37
|
+
*/
|
|
38
|
+
const HOOK_REF = /(?:^|[\\/\s"'=])\.claude[\\/]hooks[\\/]([\w.-]+?)\.(?:mjs|js|ts)(?=$|[\s"'])/;
|
|
39
|
+
/**
|
|
40
|
+
* Which shipped hook an entry launches - its LOGICAL identity - or null.
|
|
41
|
+
* Returns the name WITHOUT extension, because the extension is spelling, not
|
|
42
|
+
* identity: `skill-reminder.ts` and `skill-reminder.mjs` are the same wiring.
|
|
43
|
+
*
|
|
44
|
+
* Install and uninstall both need to answer "is this entry mine?", and they used
|
|
45
|
+
* to answer it differently: exact string equality on one side, basename of
|
|
46
|
+
* `command` on the other. Neither survived a wiring rewritten into another valid
|
|
47
|
+
* form, so install appended a duplicate beside the working entry and uninstall
|
|
48
|
+
* walked past it, leaving a wiring that errors on every event. One predicate,
|
|
49
|
+
* used by both, is the fix - anything else drifts apart again.
|
|
50
|
+
*/
|
|
51
|
+
export function wiredHookName(hook) {
|
|
52
|
+
if (!hook || typeof hook !== "object")
|
|
53
|
+
return null;
|
|
54
|
+
for (const token of [hook.command, ...(Array.isArray(hook.args) ? hook.args : [])]) {
|
|
55
|
+
if (typeof token !== "string")
|
|
56
|
+
continue;
|
|
57
|
+
const m = HOOK_REF.exec(token);
|
|
58
|
+
if (m)
|
|
59
|
+
return m[1];
|
|
60
|
+
}
|
|
61
|
+
return null;
|
|
62
|
+
}
|
|
63
|
+
/** The identity of a catalog hook file, in the same space wiredHookName returns. */
|
|
64
|
+
export const hookNameOf = (commandFile) => commandFile.replace(/\.(ts|mjs|js)$/, "");
|
|
65
|
+
/** Whether an entry already IS what hookCommand would write, down to the args. */
|
|
66
|
+
function isCurrentForm(hook, wanted) {
|
|
67
|
+
return hook.command === wanted.command
|
|
68
|
+
&& Array.isArray(hook.args)
|
|
69
|
+
&& hook.args.length === wanted.args?.length
|
|
70
|
+
&& hook.args.every((a, i) => a === wanted.args?.[i]);
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* Rewrites a legacy wiring for a hook that is installed but NOT part of this
|
|
74
|
+
* run's selection, and returns how many it repaired.
|
|
75
|
+
*
|
|
76
|
+
* Without this, "re-run the installer to get the fix" is only true for the
|
|
77
|
+
* hooks the current detection happens to select. A hook installed once with
|
|
78
|
+
* --all, or one whose signal has since disappeared from the repo, keeps its
|
|
79
|
+
* broken pre-0.8 wiring while its file sits right there in .claude/hooks.
|
|
80
|
+
*
|
|
81
|
+
* Bounded by `installedFiles`, which comes from the lockfile: hooks WE put
|
|
82
|
+
* there. A hook the user wrote and wired themselves is never touched, even if
|
|
83
|
+
* it lives in the same directory - their shell form may carry a pipe or a
|
|
84
|
+
* `|| true` that exec form cannot express.
|
|
85
|
+
*/
|
|
86
|
+
function repairUnselected(hooks, installedFiles, selected) {
|
|
87
|
+
const repairable = new Map(installedFiles
|
|
88
|
+
.map((f) => hookNameOf(f))
|
|
89
|
+
.filter((name) => !selected.has(name))
|
|
90
|
+
.map((name) => [name, hookCommand(`${name}.ts`)]));
|
|
91
|
+
if (repairable.size === 0)
|
|
92
|
+
return 0;
|
|
93
|
+
let repaired = 0;
|
|
94
|
+
for (const entries of Object.values(hooks)) {
|
|
95
|
+
if (!Array.isArray(entries))
|
|
96
|
+
continue;
|
|
97
|
+
for (const entry of entries) {
|
|
98
|
+
if (!entry || !Array.isArray(entry.hooks))
|
|
99
|
+
continue;
|
|
100
|
+
entry.hooks = entry.hooks.map((h) => {
|
|
101
|
+
const name = wiredHookName(h);
|
|
102
|
+
const wanted = name === null ? undefined : repairable.get(name);
|
|
103
|
+
if (!wanted || isCurrentForm(h, wanted))
|
|
104
|
+
return h;
|
|
105
|
+
repaired++;
|
|
106
|
+
return wanted;
|
|
107
|
+
});
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
return repaired;
|
|
111
|
+
}
|
|
112
|
+
export function mergeHookSettings(dotclaude, wirings,
|
|
113
|
+
/** Hook files the lockfile says are installed. Enables the sweep above. */
|
|
114
|
+
installedFiles = []) {
|
|
9
115
|
const settingsPath = join(dotclaude, "settings.json");
|
|
10
116
|
const existed = existsSync(settingsPath);
|
|
11
117
|
let settings = {};
|
|
@@ -27,8 +133,10 @@ export function mergeHookSettings(dotclaude, wirings) {
|
|
|
27
133
|
settings.hooks ??= {};
|
|
28
134
|
const hooks = settings.hooks;
|
|
29
135
|
let added = 0;
|
|
136
|
+
let rewired = 0;
|
|
30
137
|
for (const w of wirings) {
|
|
31
|
-
const
|
|
138
|
+
const wanted = hookCommand(w.commandFile);
|
|
139
|
+
const shipped = hookNameOf(w.commandFile);
|
|
32
140
|
if (!Array.isArray(hooks[w.event])) {
|
|
33
141
|
if (hooks[w.event] !== undefined)
|
|
34
142
|
malformed = true;
|
|
@@ -40,16 +148,35 @@ export function mergeHookSettings(dotclaude, wirings) {
|
|
|
40
148
|
entry = { ...(w.matcher ? { matcher: w.matcher } : {}), hooks: [] };
|
|
41
149
|
entries.push(entry);
|
|
42
150
|
}
|
|
43
|
-
|
|
44
|
-
|
|
151
|
+
const mine = entry.hooks.filter((h) => wiredHookName(h) === shipped);
|
|
152
|
+
if (mine.length === 0) {
|
|
153
|
+
entry.hooks.push(wanted);
|
|
45
154
|
added++;
|
|
155
|
+
continue;
|
|
46
156
|
}
|
|
157
|
+
// Already wired, possibly several times and possibly in the fragile pre-0.8
|
|
158
|
+
// shell form. Re-installing is how a user gets the fix, so this repairs in
|
|
159
|
+
// place: one entry, current form. Duplicates are collapsed, not tolerated.
|
|
160
|
+
const stale = mine.filter((h) => !isCurrentForm(h, wanted));
|
|
161
|
+
if (stale.length === 0 && mine.length === 1)
|
|
162
|
+
continue;
|
|
163
|
+
// In place, at the position it already held - never dropped and re-pushed.
|
|
164
|
+
// Order inside an event is semantic: this repo's own hooks README says
|
|
165
|
+
// PreToolUse `updatedInput` is last-wins, so appending our repaired entry
|
|
166
|
+
// after a hook the user wired themselves would silently flip which rewrite
|
|
167
|
+
// wins. A repair must not change anything but the entry it repairs.
|
|
168
|
+
const first = entry.hooks.findIndex((h) => wiredHookName(h) === shipped);
|
|
169
|
+
entry.hooks = entry.hooks.filter((h, i) => i === first || wiredHookName(h) !== shipped);
|
|
170
|
+
entry.hooks[first] = wanted;
|
|
171
|
+
rewired++;
|
|
47
172
|
}
|
|
48
|
-
|
|
49
|
-
|
|
173
|
+
rewired += repairUnselected(hooks, installedFiles, new Set(wirings.map((w) => hookNameOf(w.commandFile))));
|
|
174
|
+
const changed = added > 0 || rewired > 0 || malformed;
|
|
175
|
+
const backedUp = existed && changed;
|
|
176
|
+
if (changed) {
|
|
50
177
|
if (backedUp)
|
|
51
178
|
copyPath(settingsPath, `${settingsPath}.bak`);
|
|
52
179
|
writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
|
|
53
180
|
}
|
|
54
|
-
return { added, backedUp, malformed };
|
|
181
|
+
return { added, rewired, backedUp, malformed };
|
|
55
182
|
}
|
package/dist/src/uninstall.js
CHANGED
|
@@ -13,7 +13,8 @@
|
|
|
13
13
|
import { existsSync, readFileSync, writeFileSync, rmSync, rmdirSync, readdirSync, renameSync } from "node:fs";
|
|
14
14
|
import { join, resolve, sep } from "node:path";
|
|
15
15
|
import { tokenPaths, compareToken } from "./lock.js";
|
|
16
|
-
import {
|
|
16
|
+
import { ADOPTED_HEADER } from "./paths.js";
|
|
17
|
+
import { wiredHookName, hookNameOf } from "./settings.js";
|
|
17
18
|
/** Directories the installer creates, deepest first so a parent empties before it is tested. */
|
|
18
19
|
const OWNED_DIRS = ["rules/shared", "rules", "skills", "hooks", "agents", "scripts"];
|
|
19
20
|
/** Errors that mean "this directory is simply not removable", as opposed to a bug. */
|
|
@@ -41,10 +42,14 @@ export function unwireHookSettings(dotclaude, hookFiles) {
|
|
|
41
42
|
const hooks = settings.hooks;
|
|
42
43
|
if (!hooks || typeof hooks !== "object" || Array.isArray(hooks))
|
|
43
44
|
return { removed: 0, unreadable: false };
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
45
|
+
// The SAME predicate the installer writes with. Reading only `command` made
|
|
46
|
+
// every exec-form entry invisible here (its command is just "node"), so
|
|
47
|
+
// uninstall deleted the .mjs files and left the wirings behind - the dangling
|
|
48
|
+
// state the docblock above says it exists to prevent.
|
|
49
|
+
const ours = new Set(hookFiles.map((f) => hookNameOf(f)));
|
|
50
|
+
const isOurs = (hook) => {
|
|
51
|
+
const file = wiredHookName(hook);
|
|
52
|
+
return file !== null && ours.has(file);
|
|
48
53
|
};
|
|
49
54
|
let removed = 0;
|
|
50
55
|
for (const event of Object.keys(hooks)) {
|
|
@@ -55,7 +60,7 @@ export function unwireHookSettings(dotclaude, hookFiles) {
|
|
|
55
60
|
if (!entry || !Array.isArray(entry.hooks))
|
|
56
61
|
continue;
|
|
57
62
|
const before = entry.hooks.length;
|
|
58
|
-
entry.hooks = entry.hooks.filter((h) => !
|
|
63
|
+
entry.hooks = entry.hooks.filter((h) => !isOurs(h));
|
|
59
64
|
removed += before - entry.hooks.length;
|
|
60
65
|
}
|
|
61
66
|
// An entry we emptied was ours; one that was already empty is not our business.
|
package/docs/decisions.md
CHANGED
|
@@ -88,3 +88,43 @@ To reassess if: the genericity scope changes, or an infra constraint requires ke
|
|
|
88
88
|
**Consequences**: the open items from those entries are the ones not listed here, chiefly the reassessment of whether the audit suite deserves its own release cadence.
|
|
89
89
|
|
|
90
90
|
**Status**: Done.
|
|
91
|
+
|
|
92
|
+
## 2026-08-24 - Hook wiring moves to the exec form (issue #2)
|
|
93
|
+
|
|
94
|
+
**Context**: an external adopter running Windows with a space in the project path reported that the hooks failed in every session. The installer wrote each wiring as a single shell string (`"command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/x.mjs"`), which the shell split at the space - and which a Windows box without Git Bash never expanded at all. Five sibling defects were hiding behind that first one. Full analysis in [`postmortems/2026-08-24-hook-portability.md`](postmortems/2026-08-24-hook-portability.md).
|
|
95
|
+
|
|
96
|
+
**Options**: *(a)* keep the shell form and double-quote the placeholder, as Claude Code's docs allow; *(b)* move to the exec form (`"command": "node"`, `"args": [...]`), which the same docs recommend for any hook referencing a path placeholder.
|
|
97
|
+
|
|
98
|
+
**Decision**: **the exec form**, plus a single shared identity predicate (`wiredHookFile`) used by both install and uninstall.
|
|
99
|
+
|
|
100
|
+
Rationale: quoting is a property you have to get right at every site and re-check on every edit; the exec form removes the shell entirely, so there is nothing to quote and nothing to tokenize on any platform. `node` plus a script path rather than the script as the executable, because Windows exec form needs `command` to resolve to a real binary. The shared predicate exists because install and uninstall each answered "is this entry mine?" differently, and the two answers had already drifted apart into two separate defects.
|
|
101
|
+
|
|
102
|
+
**Consequences**: install **rewrites** a pre-0.8 shell-form wiring in place rather than appending beside it, so re-running the installer is how an affected user recovers; the repair is reported on its own line rather than folded into "no change". A hook needing genuine shell syntax (a pipe, `|| true`) stays in shell form with quoted placeholders - the `precommit-scan` snippet in `hooks/README.md` is the one such case. `hooks/README.md` and the CI grew a `windows-latest` leg and a `tools/portability.ts` gate so the class cannot return silently.
|
|
103
|
+
|
|
104
|
+
**Status**: Done.
|
|
105
|
+
|
|
106
|
+
## 2026-08-24 - No `.gitattributes` forcing LF
|
|
107
|
+
|
|
108
|
+
**Context**: the CRLF defect (a frontmatter parser blind to `\r\n`) came from `core.autocrlf=true`, the Git default on Windows. The obvious reflex is to add a `.gitattributes` normalizing the repository to LF.
|
|
109
|
+
|
|
110
|
+
**Decision**: **do not add one.**
|
|
111
|
+
|
|
112
|
+
Rationale: it would fix our own checkout and nothing else. `skill-reminder` reads the `SKILL.md` files of the *adopting* repository, whose line endings we do not control, so the hook has to be CRLF-tolerant on its own merits. Worse, normalizing this repo would make the Windows CI job - which checks out with `autocrlf=true` precisely to reproduce the adopter's tree - vacuous, removing the only mechanical check that the tolerance still holds.
|
|
113
|
+
|
|
114
|
+
**Consequences**: contributors on Windows get a CRLF working tree, and that is intentional. Any parser reading repository files must handle both; `tools/portability.ts` fails the build on an LF-only frontmatter delimiter.
|
|
115
|
+
|
|
116
|
+
**Status**: Done.
|
|
117
|
+
|
|
118
|
+
## 2026-08-24 - Transient CI branches may reach the public remote
|
|
119
|
+
|
|
120
|
+
**Context**: the 2026-08-08 entry locks the public GitHub history to one squashed commit per release, and states that the private history never reaches the public remote. Validating the issue #2 fixes needs the new `windows-latest` job to actually run, and GitHub Actions is the only place a Windows runner exists for this project. The workflow triggers on a push to `master`/`main` or on a pull request - both of which mean publishing work commits.
|
|
121
|
+
|
|
122
|
+
**Options**: *(a)* a throwaway private GitHub repository used only as a CI runner; *(b)* a transient branch or PR on the public repository, deleted afterwards; *(c)* no CI validation, rely on a local Windows VM only.
|
|
123
|
+
|
|
124
|
+
**Decision**: **(b)** - the "one commit per release" rule governs the **main history**, not every ref that transits the remote. A branch pushed to run CI and deleted afterwards is explicitly out of that rule's scope.
|
|
125
|
+
|
|
126
|
+
Rationale: the intent of the 2026-08-08 entry is that `git log main` reads as a release history, and a transient branch does not change that. Option (a) preserves the letter of the rule but needs a second repository whose CI configuration would drift from the real one - a validation of something slightly other than what ships. Option (c) trades a three-minute check for an hour of VM setup, and cannot cover the GitHub-hosted runner at all.
|
|
127
|
+
|
|
128
|
+
**Consequences**: work commits pushed on such a branch stay reachable through the pull request even after the branch is deleted - that is accepted, not overlooked. The rule stands unchanged for `main`: releases keep going through `git commit-tree`. A local Windows VM is being set up in parallel, because CI cannot cover the one thing that matters most here - Claude Code's own `${CLAUDE_PROJECT_DIR}` substitution in exec form, which only a real session on Windows exercises.
|
|
129
|
+
|
|
130
|
+
**Status**: Accepted.
|
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
# Postmortem - hooks silently dead off Linux (issue #2)
|
|
2
|
+
|
|
3
|
+
**Date**: 2026-08-24 · **Reported by**: an external adopter (issue #2, 2026-08-14)
|
|
4
|
+
**Affected versions**: up to and including 0.7.0 · **Severity**: high, silent
|
|
5
|
+
**Class**: portability of what ships - path semantics, launch contract, line endings
|
|
6
|
+
|
|
7
|
+
An adopter running Windows 11 with the project under `C:\Users\First LAST\...`
|
|
8
|
+
(a space in the username) and `core.autocrlf=true` reported that the hooks were
|
|
9
|
+
broken in every session. Six technical defects, all reproduced. None of them
|
|
10
|
+
could have been observed on our CI, which ran only on Linux.
|
|
11
|
+
|
|
12
|
+
This is the **third** occurrence of the same class: two prior `fix(hooks):`
|
|
13
|
+
commits already corrected an entry guard. That is what makes this a recurrence
|
|
14
|
+
postmortem rather than a bug report.
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## 1. Timeline
|
|
19
|
+
|
|
20
|
+
| Date | Event |
|
|
21
|
+
|---|---|
|
|
22
|
+
| 2026-06-25 | `eacb52e` *fix(hooks): guard point d'entrée robuste* - the entry-guard problem is solved **correctly** for the session trio, using `pathToFileURL`. |
|
|
23
|
+
| 2026-07-10 | `6c6f34f` *perf(hooks): ship built JS* - hooks move from `.ts` to a built `.mjs`. Every guard bound to an extension becomes a latent bomb. |
|
|
24
|
+
| 2026-07-21 | `523edf8` *two shipped hooks were silently dead after the build* - occurrence #2. Fixed by **inventing a new idiom** (`argv[1].split("/")`) instead of reusing the June one. Adds `builtHook()`, a genuinely good harness - which runs on Linux. |
|
|
25
|
+
| 2026-08-14 | Issue #2 filed. Occurrence #3 of the guard, plus five sibling defects. |
|
|
26
|
+
| 2026-08-24 | This postmortem, the fixes, and the tooled guardrails. |
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 2. What was actually wrong
|
|
31
|
+
|
|
32
|
+
Seven findings, all confirmed against the code. The reporter's analysis was
|
|
33
|
+
accurate throughout; the numbering is theirs.
|
|
34
|
+
|
|
35
|
+
| # | Defect | Site |
|
|
36
|
+
|---|---|---|
|
|
37
|
+
| 1 | Wiring written as a shell string - dies on any path with a space | `src/settings.ts:40` |
|
|
38
|
+
| 2 | Install dedupes by exact string equality → duplicates after any rewrite | `src/settings.ts:51` |
|
|
39
|
+
| 3 | Uninstall reads `command` only → blind to exec form, leaves dangling wirings | `src/uninstall.ts:47` |
|
|
40
|
+
| 4 | Entry guard splits on `/` → never fires on win32, hook silently does nothing | `truncate-output`, `truncate-bash-output`, **and `readme-freshness`** |
|
|
41
|
+
| 5 | Frontmatter regex LF-only → blind to CRLF skills | `hooks/skill-reminder.ts:56` |
|
|
42
|
+
| 6 | `URL.pathname` → percent-encoded, unresolvable path | `hooks/truncate-output.ts:91` |
|
|
43
|
+
| 7 | `permissionDecision: "allow"` bypasses the permission prompt (design) | `bash-npm-silent`, `truncate-output` |
|
|
44
|
+
|
|
45
|
+
Found during the sweep, beyond the report:
|
|
46
|
+
|
|
47
|
+
- **A third occurrence of (4)** in `readme-freshness.ts:165`. The report listed two.
|
|
48
|
+
- **`hooks/README.md` had 9 fragile wirings, not 3.** Documentation that ships to
|
|
49
|
+
an adopter's machine is code (`rules/doc-code-parity.md`).
|
|
50
|
+
- **`tools/skills.ts` had the CRLF blind spot of (5)** in its frontmatter lint. On
|
|
51
|
+
a Windows checkout the lint would pass by seeing no frontmatter at all.
|
|
52
|
+
- **`truncate-bash-output` swallowed a spawn failure**: `result.stdout ?? ''` with
|
|
53
|
+
exit 0 reported the user's command as a silent success and discarded its
|
|
54
|
+
output entirely. Platform-independent, and the worst outcome available.
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## 3. Root cause
|
|
59
|
+
|
|
60
|
+
> **The execution contract of a shipped hook exists nowhere as code.**
|
|
61
|
+
|
|
62
|
+
A hook must satisfy five clauses: *(a)* it is launched by an unknown runner
|
|
63
|
+
(POSIX shell? `cmd.exe`? direct spawn?), *(b)* from an arbitrary path that may
|
|
64
|
+
contain spaces and backslashes, *(c)* under a `.mjs` name its `.ts` source never
|
|
65
|
+
had, *(d)* over files whose line endings depend on the adopter's `core.autocrlf`,
|
|
66
|
+
*(e)* and it must never break the session.
|
|
67
|
+
|
|
68
|
+
No module, type, or test embodied that contract. Nine hooks re-implemented it
|
|
69
|
+
from memory, and produced **three competing idioms for the single question "am I
|
|
70
|
+
being run directly?"**:
|
|
71
|
+
|
|
72
|
+
```
|
|
73
|
+
main() nu → session-inject, session-precompact, bash-npm-silent
|
|
74
|
+
pathToFileURL(argv[1]).href === … → session-writer, worktree-env-setup ✅ correct
|
|
75
|
+
argv[1].split("/").pop() → truncate-output, truncate-bash-output,
|
|
76
|
+
readme-freshness ❌ dead on win32
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
The correct idiom **already existed in the repository, forty lines away**, when
|
|
80
|
+
the broken one was invented. Nothing designated it as *the* answer, so the next
|
|
81
|
+
person to face the problem solved it again, worse. The comment added in
|
|
82
|
+
`523edf8` - *"Entry guard by BASENAME, never by extension"* - is a **documentary**
|
|
83
|
+
guardrail: it protected against the previous regression and did not see the next
|
|
84
|
+
one coming.
|
|
85
|
+
|
|
86
|
+
### Two amplifiers
|
|
87
|
+
|
|
88
|
+
**A. The CI tested one world.** Every job ran `ubuntu-latest`. The matrix
|
|
89
|
+
existed, but its axis was the **Node version**, not the operating system. The
|
|
90
|
+
most recent commit before the report (`c4a9828`, *"the Node 18 leg tested the
|
|
91
|
+
toolchain, not the product"*) shows that matrix being actively refined - without
|
|
92
|
+
anyone questioning the axis that was missing. All six technical defects are
|
|
93
|
+
invisible on Linux.
|
|
94
|
+
|
|
95
|
+
**B. The default failure mode is silence.** The issue title says it: *silently*.
|
|
96
|
+
A `PreToolUse` hook exiting 0 with empty stdout is **indistinguishable** from one
|
|
97
|
+
that decided there was nothing to do. Combined with `catch { /* a hook must never
|
|
98
|
+
break the session */ }`, this yields a system where total failure and nominal
|
|
99
|
+
operation produce the same observable. That is why *"three follow-up defects were
|
|
100
|
+
hiding behind it"* - not a coincidence, but the designed behavior.
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## 4. Detection gap
|
|
105
|
+
|
|
106
|
+
Required by `rules/detection-gap-protocol.md`: a defect a **user** found is a
|
|
107
|
+
detection failure before it is anything else, because the user must never be the
|
|
108
|
+
safety net. Six defects reached an adopter past a green pipeline, a 35-mutant
|
|
109
|
+
harness, and a suite that deliberately exercises the built artifacts.
|
|
110
|
+
|
|
111
|
+
| Level | Should it have caught this? | Why it did not |
|
|
112
|
+
|---|---|---|
|
|
113
|
+
| Typecheck | No | Every defect is type-correct. `split("/")` on a win32 path, `URL.pathname`, an LF-only regex: all well-typed, all wrong. |
|
|
114
|
+
| Lint (biome) | **Yes, for the idioms** | No rule expressed "this construct is POSIX-only". Now `tools/portability.ts`, which found three live hits the moment it existed. |
|
|
115
|
+
| Unit tests | **Yes, for (2) and (3)** | Install and uninstall were each tested against their *own* notion of identity. Nothing tested them **against each other**, so two predicates drifted apart unobserved. Now one shared predicate plus a round-trip test. |
|
|
116
|
+
| Behavioral tests on the built artifacts | **Yes, for (4), (5), (6)** | `builtHook()` runs the real shipped `.mjs`, which is right, and runs it on ubuntu-latest, which is why it saw nothing. The harness was sound; its single environment was the gap. |
|
|
117
|
+
| CI matrix | **Yes, the primary gap** | The matrix axis was the Node version. No OS axis, so the only environment where any of the six can appear was never entered. |
|
|
118
|
+
| Mutation testing | No | It mutates our source, not the platform. No mutant expresses "run this on win32". |
|
|
119
|
+
| Release / smoke | No such stage | The package ships hooks that run on someone else's machine; nothing exercised them off Linux before publishing. The Windows job now does, on every push. |
|
|
120
|
+
|
|
121
|
+
Two gaps stand out because neither is about missing tests:
|
|
122
|
+
|
|
123
|
+
- **The suite tested one world.** Coverage was good and evidence was narrow. More
|
|
124
|
+
tests on Linux would have added nothing; one job on another OS added everything.
|
|
125
|
+
- **Two components were never tested against each other.** Install and uninstall
|
|
126
|
+
each passed alone. The contract *between* them was the thing nobody asserted,
|
|
127
|
+
and it is where (2) and (3) lived.
|
|
128
|
+
|
|
129
|
+
## 5. Hypotheses tested
|
|
130
|
+
|
|
131
|
+
| Hypothesis | Verdict | Evidence |
|
|
132
|
+
|---|---|---|
|
|
133
|
+
| Isolated lapse of attention | **Refuted** | Three occurrences of the same construct across three months, two already carrying their own `fix(hooks):` commit. |
|
|
134
|
+
| Purely a Windows problem | **Refuted** | Defect (1) breaks on any path containing a space, including `/Users/Jean Dupont/`. Windows made it *systematic* (space in the username is near-default, `autocrlf=true` is the Git default), not *existent*. |
|
|
135
|
+
| The existing tooling should have caught it | **Refuted** | It structurally could not. `builtHook()` runs the real shipped `.mjs` - on Linux. Mutation testing does not mutate platform behavior. |
|
|
136
|
+
| The correct solution was unknown at the time | **Refuted** | `eacb52e` had shipped it a month earlier, in the same directory. |
|
|
137
|
+
| No shared runtime contract → each hook reinvents it | **Confirmed** | Three idioms for one question; two independent frontmatter parsers, one CRLF-tolerant by luck (`src/selector.ts`) and one not (`skill-reminder`). |
|
|
138
|
+
|
|
139
|
+
The luck in `src/selector.ts` is worth naming: `indexOf("\n---")` happens to
|
|
140
|
+
match inside `"\r\n---"`, and the stray `\r` happens to be eaten by a later
|
|
141
|
+
`.trim()`. Nobody decided that. It is the same parsing problem solved twice
|
|
142
|
+
independently, once fortunate and once not - which is the root cause restated.
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## 6. Fixes
|
|
147
|
+
|
|
148
|
+
| # | Fix |
|
|
149
|
+
|---|---|
|
|
150
|
+
| 1 | `settings.ts` writes **exec form** (`command: "node"`, `args: ["${CLAUDE_PROJECT_DIR}/…"]`). No shell, and the braced placeholder is substituted by Claude Code itself. |
|
|
151
|
+
| 2, 3 | One shared predicate, `wiredHookFile()`, used by **both** install and uninstall. Install now also **repairs** a pre-0.8 shell-form wiring in place and collapses duplicates, so re-running the installer is how an affected user recovers. |
|
|
152
|
+
| 4 | The three divergent guards unified onto the June idiom. |
|
|
153
|
+
| 5 | `\r?\n` delimiter, description bounded to the line. Same fix in `tools/skills.ts`. |
|
|
154
|
+
| 6 | `fileURLToPath()`, and the helper path is shell-quoted with apostrophe escaping. |
|
|
155
|
+
| 7 | Documented in `hooks/README.md` - which commands stop prompting, and how to decline the trade. Not silently fixed: the behavior is required for `updatedInput` to apply. |
|
|
156
|
+
| + | `truncate-bash-output` now fails loudly on a spawn error instead of reporting empty success. |
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
## 7. Guardrails - tooled, not documentary
|
|
161
|
+
|
|
162
|
+
Each one sweeps **existing** code, per the anti-recurrence rule: a rule that only
|
|
163
|
+
applies to future code leaves the live bombs in place.
|
|
164
|
+
|
|
165
|
+
1. **`windows-latest` CI job** (`.github/workflows/ci.yml`). The missing matrix
|
|
166
|
+
axis. Checks out with `core.autocrlf=true`, runs the portability gate, asserts
|
|
167
|
+
`skill-reminder` parses the CRLF tree, asserts `truncate-output` fires and
|
|
168
|
+
yields a resolvable helper, and installs/uninstalls into a path containing a
|
|
169
|
+
space. Deliberately **not** the full vitest suite: it shells out to `ln -s`,
|
|
170
|
+
`bash` stubs and `git worktree`, so a failure there would report on the test
|
|
171
|
+
harness rather than the product. Widening it means porting those helpers first.
|
|
172
|
+
|
|
173
|
+
2. **`tools/portability.ts`**, wired into `npm test`. Two passes:
|
|
174
|
+
- *static* - forbids `split("/")` on a path, `URL.pathname` on a file URL, an
|
|
175
|
+
`argv[1]`-parsing entry guard, and LF-only frontmatter delimiters. It found
|
|
176
|
+
three real hits on first run.
|
|
177
|
+
- *smoke* - copies every built hook into a directory whose name contains a
|
|
178
|
+
space, runs it, and fails if it produces nothing. On the Windows runner the
|
|
179
|
+
same pass also covers the backslash separator.
|
|
180
|
+
|
|
181
|
+
Escape hatch: `// portability:allow <reason>` on the line, mirroring the
|
|
182
|
+
`gitleaks:allow` convention the repo's rules already use. Never disable the check.
|
|
183
|
+
|
|
184
|
+
3. **A test pinning the positive form** - every guarded hook must use the one
|
|
185
|
+
idiom. The static gate forbids the known-bad shapes; this makes a *fourth*
|
|
186
|
+
invention a failing test rather than a discovery from a user.
|
|
187
|
+
|
|
188
|
+
4. **Five new mutants** in `tools/mutations.ts`, one per fixed defect, each
|
|
189
|
+
verified to be killed. 38/38 mutations killed.
|
|
190
|
+
|
|
191
|
+
### Deliberately not done: adding `.gitattributes`
|
|
192
|
+
|
|
193
|
+
Forcing LF in this repo would make our own checkout clean and the Windows CRLF
|
|
194
|
+
job **vacuous**, while doing nothing for adopters - `skill-reminder` reads the
|
|
195
|
+
`SKILL.md` files of *their* repository, whose line endings we do not control. The
|
|
196
|
+
hook has to be CRLF-tolerant on its own; keeping this repo CRLF-able on Windows
|
|
197
|
+
is what keeps the CI leg honest.
|
|
198
|
+
|
|
199
|
+
---
|
|
200
|
+
|
|
201
|
+
## 8. What this cost, and what to carry forward
|
|
202
|
+
|
|
203
|
+
Six defects reached users. All six were invisible to a green CI, a 38-mutant
|
|
204
|
+
harness, and a test suite that deliberately exercises the built artifacts. The
|
|
205
|
+
gap was never rigor - it was that **every check ran in the one environment where
|
|
206
|
+
none of the defects can appear.**
|
|
207
|
+
|
|
208
|
+
Two lessons worth generalizing beyond hooks:
|
|
209
|
+
|
|
210
|
+
- **When a fix invents a new way to do something the repo already does, that is
|
|
211
|
+
the defect.** The reviewable moment was `523edf8`, where a second idiom
|
|
212
|
+
appeared next to a working first one. Divergence is cheaper to catch than its
|
|
213
|
+
consequences.
|
|
214
|
+
- **A guardrail that cannot fail is not a guardrail.** "Entry guard by BASENAME,
|
|
215
|
+
never by extension" was true, prominent, and useless, because nothing executed
|
|
216
|
+
it. Prefer the check that runs.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ronce-racine",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.8.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Ronce Racine - generic Claude Code config (always-on rules + on-demand skills) with a distribution CLI",
|
|
6
6
|
"license": "MIT",
|
|
@@ -44,7 +44,7 @@
|
|
|
44
44
|
"lint": "biome check .",
|
|
45
45
|
"lint:fix": "biome check --write .",
|
|
46
46
|
"verify": "npm run typecheck && npm run lint && npm test",
|
|
47
|
-
"test": "tsx tools/skills.ts validate && tsx tools/skills.ts triggers && tsx tools/skills.ts routing && tsx tools/skills.ts rules && tsx tools/skills.ts scripts && tsx tools/skills.ts hooks && tsx tools/skills.ts agents && tsx tools/skills.ts templates && tsx tools/skills.ts docs && vitest run",
|
|
47
|
+
"test": "tsx tools/skills.ts validate && tsx tools/skills.ts triggers && tsx tools/skills.ts routing && tsx tools/skills.ts rules && tsx tools/skills.ts scripts && tsx tools/skills.ts hooks && tsx tools/skills.ts agents && tsx tools/skills.ts templates && tsx tools/skills.ts docs && tsx tools/portability.ts && vitest run",
|
|
48
48
|
"test:mutation": "tsx tools/mutations.ts",
|
|
49
49
|
"eval:dry": "tsx playground/setup.ts >/dev/null && tsx tools/eval.ts run --dry-run",
|
|
50
50
|
"skills:list": "tsx tools/skills.ts list",
|
|
@@ -54,7 +54,8 @@
|
|
|
54
54
|
"prepublishOnly": "tsx tools/build.ts && npm test",
|
|
55
55
|
"test:watch": "vitest",
|
|
56
56
|
"coverage": "vitest run --coverage",
|
|
57
|
-
"test:mutation:inprocess": "stryker run"
|
|
57
|
+
"test:mutation:inprocess": "stryker run",
|
|
58
|
+
"portability": "tsx tools/portability.ts"
|
|
58
59
|
},
|
|
59
60
|
"devDependencies": {
|
|
60
61
|
"@biomejs/biome": "^2.5.7",
|