ronce-racine 0.5.0 → 0.5.1

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/README.md CHANGED
@@ -21,8 +21,13 @@ Copy-pasted `.claude/` config **rots**: every repo drifts, and nobody remembers
21
21
 
22
22
  ## Requirements
23
23
 
24
- - **Node ≥ 18**. The installer runs via `npx ronce-racine`, no clone needed; the target repo needs **only Node**, because hooks ship pre-built (`dist/hooks/*.js`).
24
+ - **Node ≥ 18** in the target repo. The installer runs via `npx ronce-racine`,
25
+ no clone needed, and hooks ship pre-built (`.mjs`) so they run on plain
26
+ `node` with no TypeScript runtime.
25
27
  - **rules / skills / agents are plain Markdown** and need no toolchain at all.
28
+ - **`tsx` only if you install a detection script.** The optional `scripts/*.ts`
29
+ (secret scan, project sweep, call-site audit) ship as TypeScript and are run
30
+ on demand with `npx tsx`. Skip them and Node alone is enough.
26
31
 
27
32
  ## The name
28
33
 
@@ -67,6 +72,7 @@ The two coexist: an adopted repo loads its project copy (which takes precedence)
67
72
  | `clean-architecture-deps.md` | code (ts/py/go/rs/php/java) | dependencies toward the domain, no logic in the handler |
68
73
  | `no-raw-sql-interpolation.md` | code (ts/py/go/rs/php/java) | parameterized queries, never SQL interpolation |
69
74
  | `ui-states-complete.md` | components (tsx/jsx/vue/svelte) | loading/error/empty/success all handled and distinguishable |
75
+ | `doc-code-parity.md` | Markdown (README, docs/) | documented commands are run before commit; behavior changes sweep the docs |
70
76
 
71
77
  Each rule also carries `version` + `metadata.last-reviewed` (parity with the skills), validated by `npm test`.
72
78
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  Generic Claude Code hooks, to be wired into `settings.json` (or a repo's `.claude/settings.json`). The harness runs these scripts; they depend on no particular project.
4
4
 
5
- All scripts are TypeScript, run via `tsx` (like `install.ts`/`tools/skills.ts`). The target repo must have `tsx` available (`npx tsx` resolves it on the fly).
5
+ Hooks are authored in TypeScript but SHIP BUILT: the installer copies `.mjs` files that run on plain `node`. A target repo needs Node and nothing else to run them - no `tsx`, no compilation on every invocation (which used to cost about half a second per prompt).
6
6
 
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
 
@@ -18,7 +18,7 @@ Locates skills in this order: `$CLAUDE_PROJECT_DIR/.claude/skills`, `./.claude/s
18
18
  {
19
19
  "hooks": {
20
20
  "UserPromptSubmit": [
21
- { "hooks": [{ "type": "command", "command": "npx tsx $CLAUDE_PROJECT_DIR/.claude/hooks/skill-reminder.ts" }] }
21
+ { "hooks": [{ "type": "command", "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/skill-reminder.mjs" }] }
22
22
  ]
23
23
  }
24
24
  }
@@ -42,7 +42,7 @@ Leaves interactive `npm install <pkg>` calls (adding a dependency) untouched.
42
42
  "PreToolUse": [
43
43
  { "matcher": "Bash",
44
44
  "hooks": [{ "type": "command",
45
- "command": "npx tsx $CLAUDE_PROJECT_DIR/.claude/hooks/bash-npm-silent.ts" }] }
45
+ "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/bash-npm-silent.mjs" }] }
46
46
  ]
47
47
  }
48
48
  }
@@ -66,7 +66,7 @@ Leaves interactive `npm install <pkg>` calls (adding a dependency) untouched.
66
66
  "PreToolUse": [
67
67
  { "matcher": "Bash",
68
68
  "hooks": [{ "type": "command",
69
- "command": "npx tsx $CLAUDE_PROJECT_DIR/.claude/hooks/truncate-output.ts" }] }
69
+ "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/truncate-output.mjs" }] }
70
70
  ]
71
71
  }
72
72
  }
@@ -89,7 +89,7 @@ Writes a session memo to `~/.claude/projects/<repo-slug>/sessions/<branch>.md` (
89
89
  "hooks": {
90
90
  "Stop": [
91
91
  { "hooks": [{ "type": "command",
92
- "command": "npx tsx $CLAUDE_PROJECT_DIR/.claude/hooks/session-writer.ts" }] }
92
+ "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/session-writer.mjs" }] }
93
93
  ]
94
94
  }
95
95
  }
@@ -107,7 +107,7 @@ Re-reads the memo (written by `session-writer`) and injects it as `additionalCon
107
107
  "SessionStart": [
108
108
  { "matcher": "compact",
109
109
  "hooks": [{ "type": "command",
110
- "command": "npx tsx $CLAUDE_PROJECT_DIR/.claude/hooks/session-inject.ts" }] }
110
+ "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/session-inject.mjs" }] }
111
111
  ]
112
112
  }
113
113
  }
@@ -124,7 +124,7 @@ Injects the memo as `systemMessage` into the compaction prompt, so the generated
124
124
  "hooks": {
125
125
  "PreCompact": [
126
126
  { "hooks": [{ "type": "command",
127
- "command": "npx tsx $CLAUDE_PROJECT_DIR/.claude/hooks/session-precompact.ts" }] }
127
+ "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/session-precompact.mjs" }] }
128
128
  ]
129
129
  }
130
130
  }
@@ -143,7 +143,7 @@ If the session starts in a linked git worktree (not the main worktree) and the m
143
143
  "hooks": {
144
144
  "SessionStart": [
145
145
  { "hooks": [{ "type": "command",
146
- "command": "npx tsx $CLAUDE_PROJECT_DIR/.claude/hooks/worktree-env-setup.ts" }] }
146
+ "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/worktree-env-setup.mjs" }] }
147
147
  ]
148
148
  }
149
149
  }
@@ -42,5 +42,9 @@ function main() {
42
42
  }
43
43
  process.stdout.write(truncateOutput(output));
44
44
  }
45
- if (process.argv[1]?.endsWith('truncate-bash-output.ts'))
45
+ // Entry guard by BASENAME, never by extension: this file is authored as .ts and
46
+ // ships as .mjs, and an extension-bound guard silently disables main() in the
47
+ // built copy - the hook then exits 0 doing nothing, with no signal at all.
48
+ const invoked = (process.argv[1] ?? "").split("/").pop()?.replace(/\.(ts|mjs|js)$/, "");
49
+ if (invoked === 'truncate-bash-output')
46
50
  main();
@@ -41,7 +41,7 @@ export function wrapCommand(cmd, hookDir) {
41
41
  // Run the helper via `npx tsx` (works on any Node ≥ 18) rather than
42
42
  // `node --experimental-strip-types` (only Node ≥ 22.6), matching how the
43
43
  // hooks themselves are wired in settings.json.
44
- return `TRUNCATE_CMD_B64=${encoded} npx -y tsx '${hookDir}/truncate-bash-output.ts'`;
44
+ return `TRUNCATE_CMD_B64=${encoded} node '${hookDir}/truncate-bash-output.mjs'`;
45
45
  }
46
46
  function readStdin() {
47
47
  try {
@@ -84,5 +84,9 @@ function main() {
84
84
  };
85
85
  process.stdout.write(JSON.stringify(output));
86
86
  }
87
- if (process.argv[1]?.endsWith('truncate-output.ts'))
87
+ // Entry guard by BASENAME, never by extension: this file is authored as .ts and
88
+ // ships as .mjs, and an extension-bound guard silently disables main() in the
89
+ // built copy - the hook then exits 0 doing nothing, with no signal at all.
90
+ const invoked = (process.argv[1] ?? "").split("/").pop()?.replace(/\.(ts|mjs|js)$/, "");
91
+ if (invoked === 'truncate-output')
88
92
  main();
@@ -0,0 +1,29 @@
1
+ # Rule - `doc-code-parity`
2
+
3
+ > A command shown in the documentation is executed before it is committed, and a behavior change greps the docs in the same commit.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Rule (scoped to Markdown) |
8
+ | **Scope (`paths`)** | `**/README.md`, `**/docs/**/*.md` |
9
+ | **Version** | 1.0.0 |
10
+ | **Artifact** | [`rules/doc-code-parity.md`](../../rules/doc-code-parity.md) |
11
+ | **Enforced by** | `tools/skills.ts docs`, wired into `npm test` |
12
+
13
+ ## What it enforces
14
+
15
+ - Commands appearing in docs are run before commit
16
+ - A behavior change sweeps the docs in the same commit
17
+ - Documentation that ships to a user's repository is treated as code
18
+ - Requirements are stated per component, never as one global promise
19
+ - Verifiable claims become harness checks instead of trusted prose
20
+
21
+ ## Why it matters
22
+
23
+ This rule exists because two documentation defects reached published users. `hooks/README.md`, which the installer copies into every adopting repository, still instructed readers to wire hooks with `npx tsx .../hook.ts` after the installer had moved to `node .../hook.mjs`. And the README promised "the target repo needs only Node" while the optional detection scripts still shipped as TypeScript requiring `tsx`.
24
+
25
+ Neither was caught by tests, typecheck or review. Both described a past state of the code confidently enough that a reader would follow them and fail. The lesson is not "write better docs": it is that any doc claim reducible to a fact about the code belongs in the harness, and the rest belongs in a habit of running what you write.
26
+
27
+ ## How it is checked
28
+
29
+ `tools/skills.ts docs` compares documentation against the installer itself: wiring examples must match the command shape the installer generates, every hook must be documented and no phantom one may be, a "only Node" claim must not coexist with shipped TypeScript, and any documented `npx tsx <path>` must name a file that exists.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ronce-racine",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
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",
@@ -20,15 +20,23 @@
20
20
  "!docs/superpowers/",
21
21
  "AGENTS.md"
22
22
  ],
23
- "repository": { "type": "git", "url": "git+https://github.com/ChariereFiedler/ronce-racine.git" },
24
- "keywords": ["claude-code", "ai-agents", "developer-tools", "code-quality"],
23
+ "repository": {
24
+ "type": "git",
25
+ "url": "git+https://github.com/ChariereFiedler/ronce-racine.git"
26
+ },
27
+ "keywords": [
28
+ "claude-code",
29
+ "ai-agents",
30
+ "developer-tools",
31
+ "code-quality"
32
+ ],
25
33
  "engines": {
26
34
  "node": ">=18"
27
35
  },
28
36
  "scripts": {
29
37
  "build": "tsx tools/build.ts",
30
38
  "typecheck": "tsc --noEmit",
31
- "test": "tsx tools/skills.ts validate && tsx tools/skills.ts triggers && tsx tools/skills.ts rules && tsx tools/skills.ts scripts && tsx tools/skills.ts hooks && tsx tools/skills.ts templates && tsx tools/tests.ts",
39
+ "test": "tsx tools/skills.ts validate && tsx tools/skills.ts triggers && tsx tools/skills.ts rules && tsx tools/skills.ts scripts && tsx tools/skills.ts hooks && tsx tools/skills.ts templates && tsx tools/skills.ts docs && tsx tools/tests.ts",
32
40
  "test:mutation": "tsx tools/mutations.ts",
33
41
  "eval:dry": "tsx playground/setup.ts >/dev/null && tsx tools/eval.ts run --dry-run",
34
42
  "skills:list": "tsx tools/skills.ts list",
@@ -0,0 +1,16 @@
1
+ ---
2
+ paths:
3
+ - "**/README.md"
4
+ - "**/docs/**/*.md"
5
+ version: 1.0.0
6
+ metadata:
7
+ last-reviewed: 2026-07-21
8
+ ---
9
+
10
+ # Documentation must match the code it describes
11
+
12
+ - **A command shown in a doc is executed, not imagined.** Before committing a doc that contains a command, run it. A wiring snippet, an install line or a CLI invocation that no longer matches the code is worse than no example: the reader trusts it.
13
+ - **When behavior changes, grep the docs in the same commit.** Renaming a file, changing what a generator emits, or changing a runtime requirement invalidates every doc that quoted it. Search for the old form before declaring the change done.
14
+ - **Documentation that ships to users is code.** A file copied into someone else's repository (here: `hooks/README.md`) describes what runs on their machine. Treat a stale claim in it as a defect, not as cosmetics.
15
+ - **State requirements per component, not globally.** "This needs only Node" is false the moment one optional part needs more. Say which part needs what.
16
+ - **Prefer a mechanical check over a promise.** Where a doc claim can be verified against the source of truth, add it to the harness (`tools/skills.ts docs`) rather than relying on review to notice.