ronce-racine 0.5.2 → 0.7.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/AGENTS.md +7 -2
- package/README.md +213 -207
- package/agents/code-reviewer.md +1 -1
- package/dist/hooks/README.md +62 -0
- package/dist/hooks/readme-freshness.mjs +159 -0
- package/dist/hooks/truncate-output.mjs +13 -5
- package/dist/install.js +114 -711
- package/dist/src/catalog.js +80 -0
- package/dist/src/detect.js +140 -0
- package/dist/src/lock.js +200 -0
- package/dist/src/paths.js +25 -0
- package/dist/src/selector.js +324 -0
- package/dist/src/settings.js +55 -0
- package/dist/src/uninstall.js +170 -0
- package/docs/adopting-a-repo.md +29 -22
- package/docs/architecture.md +9 -10
- package/docs/catalog.md +86 -0
- package/docs/decisions.md +31 -13
- package/docs/developing.md +69 -29
- package/docs/distribution-model.md +130 -0
- package/docs/evaluating-skills.md +42 -2
- package/docs/git-worktrees.md +2 -2
- package/docs/quality-bar.md +55 -0
- package/docs/templates/rule.template.md +2 -1
- package/docs/writing-a-rule.md +13 -3
- package/docs/writing-a-skill.md +16 -7
- package/package.json +17 -4
- package/skills/adversarial-feature-challenge/SKILL.md +5 -3
- package/skills/api-contract-versioning/SKILL.md +6 -4
- package/skills/bug-ticket-root-cause/SKILL.md +5 -3
- package/skills/bug-triage-structured/SKILL.md +5 -3
- package/skills/ci-pipeline-orchestration/SKILL.md +5 -3
- package/skills/commit-readiness-review/SKILL.md +7 -3
- package/skills/commit-readiness-review/scripts/precommit-scan.ts +3 -3
- package/skills/comprehensive-test-strategy/SKILL.md +5 -3
- package/skills/daily-workflow-optimization/SKILL.md +6 -4
- package/skills/database-schema-evolution/SKILL.md +6 -4
- package/skills/ddd-backend-implementation/SKILL.md +5 -3
- package/skills/design-system-component-lifecycle/SKILL.md +6 -4
- package/skills/detection-sweep/SKILL.md +7 -3
- package/skills/detection-sweep/scripts/sweep.ts +3 -3
- package/skills/domain-glossary/README.md +44 -0
- package/skills/domain-glossary/SKILL.md +166 -0
- package/skills/frontend-fullstack-implementation/SKILL.md +6 -4
- package/skills/frontend-spec-call-site-audit/SKILL.md +7 -3
- package/skills/frontend-spec-call-site-audit/scripts/audit-entry-points.ts +4 -1
- package/skills/merge-request-review/SKILL.md +5 -3
- package/skills/performance-profiling/README.md +69 -0
- package/skills/performance-profiling/SKILL.md +223 -0
- package/skills/performance-profiling/reference/go.md +235 -0
- package/skills/performance-profiling/reference/native.md +148 -0
- package/skills/performance-profiling/reference/node-web.md +157 -0
- package/skills/performance-profiling/reference/statistics.md +181 -0
- package/skills/performance-profiling/reference/tracy.md +137 -0
- package/skills/production-incident-diagnostic/SKILL.md +5 -3
- package/skills/qa-session-intake/SKILL.md +5 -3
- package/skills/recording-decisions/SKILL.md +5 -3
- package/skills/recurring-bug-root-cause/SKILL.md +5 -3
- package/skills/recurring-bug-root-cause/scripts/detect-recurring-fixes.ts +1 -1
- package/skills/refactoring-shared-component-api/SKILL.md +7 -3
- package/skills/refactoring-shared-component-api/scripts/sweep-call-sites.ts +10 -3
- package/skills/validating-features-end-to-end/SKILL.md +5 -3
- package/skills/visual-regression-check/SKILL.md +6 -4
- package/skills/writing-robust-tests/SKILL.md +8 -4
package/dist/hooks/README.md
CHANGED
|
@@ -6,6 +6,28 @@ Hooks are authored in TypeScript but SHIP BUILT: the installer copies `.mjs` fil
|
|
|
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
|
|
|
9
|
+
|
|
10
|
+
## Composition rule: a hook is never alone on its event
|
|
11
|
+
|
|
12
|
+
Several plugins can observe the same Claude Code event, and `PreToolUse`
|
|
13
|
+
`updatedInput` is last-wins. A hook that rewrites a command therefore hands its
|
|
14
|
+
output to whatever runs next, plus the transcript and the logs.
|
|
15
|
+
|
|
16
|
+
**A hook that rewrites a command must preserve the original in readable form.**
|
|
17
|
+
`truncate-output` learned this the hard way: it replaced the command with an
|
|
18
|
+
opaque base64 blob, which broke every downstream consumer and made transcripts
|
|
19
|
+
unreadable. It now carries the original as a trailing shell comment, which runs
|
|
20
|
+
to end of line and swallows quotes and apostrophes without interpreting them.
|
|
21
|
+
|
|
22
|
+
Two corollaries:
|
|
23
|
+
|
|
24
|
+
- **Rewrite only when the rewrite earns its cost.** `truncate-output` used to
|
|
25
|
+
wrap `git log --oneline -5`, whose output never reaches the truncation
|
|
26
|
+
threshold: pure loss.
|
|
27
|
+
- **Never mask an exit code.** Piping through `head` or `tail` replaces the
|
|
28
|
+
command's status with the pipe's. `bash-npm-silent` adds a flag rather than a
|
|
29
|
+
pipe for exactly this reason.
|
|
30
|
+
|
|
9
31
|
---
|
|
10
32
|
|
|
11
33
|
## `skill-reminder.ts` - skill suggestion (UserPromptSubmit)
|
|
@@ -151,6 +173,46 @@ If the session starts in a linked git worktree (not the main worktree) and the m
|
|
|
151
173
|
|
|
152
174
|
---
|
|
153
175
|
|
|
176
|
+
## `readme-freshness.ts` - re-reads the README before a push (PreToolUse/Bash)
|
|
177
|
+
|
|
178
|
+
**Event**: `PreToolUse` · **Matcher**: `Bash` · **Opt-in** (spends one API call per push)
|
|
179
|
+
|
|
180
|
+
Before a `git push` that carries structural changes (`install.ts`, `package.json`,
|
|
181
|
+
`skills/`, `rules/`, `hooks/`, `agents/`, `scripts/`, `templates/`), asks Claude to
|
|
182
|
+
read `README.md` against the diff being pushed and report the claims it
|
|
183
|
+
contradicts: a wrong count, a renamed command, a mechanism that changed, a
|
|
184
|
+
documented file that moved.
|
|
185
|
+
|
|
186
|
+
An LLM rather than a grep, because the drift that matters is semantic - "34
|
|
187
|
+
skills" or "validated by npm test" stays true-looking to any pattern you can
|
|
188
|
+
write, and stops being true the moment the number or the command changes.
|
|
189
|
+
|
|
190
|
+
**Warns, never blocks, by default.** It fails open on every failure mode: no
|
|
191
|
+
`claude` on PATH, not authenticated, timed out, rate-limited, no upstream to
|
|
192
|
+
diff against. A push is never held hostage by this check.
|
|
193
|
+
|
|
194
|
+
| Variable | Effect |
|
|
195
|
+
|---|---|
|
|
196
|
+
| `RONCE_README_CHECK=block` | a contradiction denies the push instead of warning |
|
|
197
|
+
| `RONCE_README_CHECK=off` | skips the check entirely |
|
|
198
|
+
| `RONCE_CLAUDE_BIN` | path to the `claude` binary (default: `claude` on PATH) |
|
|
199
|
+
|
|
200
|
+
Scope: this sees pushes made by Claude. A human typing `git push` in their own
|
|
201
|
+
terminal does not go through it - keep a CI job for that guarantee.
|
|
202
|
+
|
|
203
|
+
```json
|
|
204
|
+
{
|
|
205
|
+
"hooks": {
|
|
206
|
+
"PreToolUse": [
|
|
207
|
+
{ "matcher": "Bash", "hooks": [{ "type": "command",
|
|
208
|
+
"command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/readme-freshness.mjs" }] }
|
|
209
|
+
]
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
---
|
|
215
|
+
|
|
154
216
|
## `precommit-scan.ts` - secret/debug scan before commit
|
|
155
217
|
|
|
156
218
|
Shipped with the `commit-readiness-review` skill (`skills/commit-readiness-review/scripts/precommit-scan.ts`). Read-only, exit 1 if a secret/sensitive file is staged. Two possible wirings:
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* PreToolUse hook for Bash: before a `git push`, has Claude re-read README.md
|
|
4
|
+
* against what the push actually changes, and reports the claims the change
|
|
5
|
+
* contradicts.
|
|
6
|
+
*
|
|
7
|
+
* Why an LLM rather than a grep: the drift that matters is semantic. A README
|
|
8
|
+
* saying "34 skills", "validated by npm test" or "hooks ship as TypeScript"
|
|
9
|
+
* stays true-looking to any pattern you can write, and stops being true the
|
|
10
|
+
* moment a number, a command or a mechanism changes. That is exactly the class
|
|
11
|
+
* of defect the doc-code-parity rule targets, and the only reader able to spot
|
|
12
|
+
* it is one that understands both texts.
|
|
13
|
+
*
|
|
14
|
+
* WARNS, never blocks, by design: this repo's own rule is that a hook fires on
|
|
15
|
+
* every session of every repo that installed it, so it fails open - a flaky
|
|
16
|
+
* gate gets disabled, which is worse than no gate. Set
|
|
17
|
+
* RONCE_README_CHECK=block to make a contradiction deny the push instead.
|
|
18
|
+
* Set RONCE_README_CHECK=off to skip it entirely.
|
|
19
|
+
*
|
|
20
|
+
* Scope, stated plainly: this sees pushes made by Claude. A human typing
|
|
21
|
+
* `git push` in their own terminal does not go through it - use the CI job for
|
|
22
|
+
* that guarantee.
|
|
23
|
+
*
|
|
24
|
+
* @version 1.0.0
|
|
25
|
+
* @last-reviewed 2026-08-08
|
|
26
|
+
*/
|
|
27
|
+
import { readFileSync, existsSync } from 'node:fs';
|
|
28
|
+
import { spawnSync } from 'node:child_process';
|
|
29
|
+
import { join } from 'node:path';
|
|
30
|
+
/** Paths whose change can invalidate a README claim. Docs alone cannot. */
|
|
31
|
+
const STRUCTURAL = /^(install\.ts|package\.json|skills\/|rules\/|hooks\/|agents\/|scripts\/|templates\/|\.claude-plugin\/)/;
|
|
32
|
+
const VERDICT_OK = 'README_OK';
|
|
33
|
+
const TIMEOUT_MS = 120_000;
|
|
34
|
+
const MAX_DIFF_CHARS = 60_000;
|
|
35
|
+
export function isGitPush(cmd) {
|
|
36
|
+
// A push hidden behind `&&` still pushes; a `--dry-run` does not.
|
|
37
|
+
if (/--dry-run\b/.test(cmd))
|
|
38
|
+
return false;
|
|
39
|
+
return cmd.split(/&&|\|\||;/).some((part) => /^\s*git\s+(-\S+\s+)*push\b/.test(part));
|
|
40
|
+
}
|
|
41
|
+
/** Files the push would send, i.e. local commits the upstream does not have. */
|
|
42
|
+
export function changedFiles(cwd) {
|
|
43
|
+
const git = (args) => {
|
|
44
|
+
const r = spawnSync('git', args, { cwd, encoding: 'utf8', timeout: 10_000 });
|
|
45
|
+
return r.status === 0 ? (r.stdout ?? '').trim() : null;
|
|
46
|
+
};
|
|
47
|
+
// `@{push}` is the tracking ref when configured; fall back to the remote HEAD,
|
|
48
|
+
// and give up rather than guess when neither resolves (a first push, a repo
|
|
49
|
+
// with no upstream) - a diff against nothing would flag the entire README.
|
|
50
|
+
const base = git(['rev-parse', '--abbrev-ref', '@{push}']) ?? git(['rev-parse', '--abbrev-ref', 'origin/HEAD']);
|
|
51
|
+
if (!base)
|
|
52
|
+
return [];
|
|
53
|
+
const out = git(['diff', '--name-only', `${base}...HEAD`]);
|
|
54
|
+
return out ? out.split('\n').filter(Boolean) : [];
|
|
55
|
+
}
|
|
56
|
+
export function buildPrompt(readme, files, diff) {
|
|
57
|
+
return [
|
|
58
|
+
'You are checking a README against changes about to be pushed.',
|
|
59
|
+
'',
|
|
60
|
+
'Report ONLY statements in the README that the changes make FALSE or misleading:',
|
|
61
|
+
'a wrong count, a command that no longer exists or was renamed, a described',
|
|
62
|
+
'mechanism that changed, a documented file that moved or disappeared.',
|
|
63
|
+
'',
|
|
64
|
+
'Do NOT report: style, tone, wording, missing sections, things you would',
|
|
65
|
+
'phrase differently, or anything you cannot check against the diff below.',
|
|
66
|
+
'Absence of documentation for a new thing is only worth reporting when the',
|
|
67
|
+
'README already claims to list every one of them (a table of all skills, all',
|
|
68
|
+
'hooks, all rules).',
|
|
69
|
+
'',
|
|
70
|
+
`If nothing in the README is contradicted, reply with exactly: ${VERDICT_OK}`,
|
|
71
|
+
'Otherwise reply with one line per problem: `<README quote>` -> <what is now true>',
|
|
72
|
+
'',
|
|
73
|
+
'=== FILES IN THIS PUSH ===',
|
|
74
|
+
files.join('\n'),
|
|
75
|
+
'',
|
|
76
|
+
'=== DIFF ===',
|
|
77
|
+
diff.length > MAX_DIFF_CHARS ? `${diff.slice(0, MAX_DIFF_CHARS)}\n[diff truncated]` : diff,
|
|
78
|
+
'',
|
|
79
|
+
'=== README.md ===',
|
|
80
|
+
readme,
|
|
81
|
+
].join('\n');
|
|
82
|
+
}
|
|
83
|
+
/** `claude -p --output-format json` wraps the text in {"result": "..."}. */
|
|
84
|
+
export function unwrapEnvelope(raw) {
|
|
85
|
+
try {
|
|
86
|
+
const parsed = JSON.parse(raw);
|
|
87
|
+
if (typeof parsed.result === 'string')
|
|
88
|
+
return parsed.result;
|
|
89
|
+
}
|
|
90
|
+
catch {
|
|
91
|
+
// Plain-text output, or a stub: use it as-is.
|
|
92
|
+
}
|
|
93
|
+
return raw;
|
|
94
|
+
}
|
|
95
|
+
function emit(decision, reason) {
|
|
96
|
+
process.stdout.write(JSON.stringify({
|
|
97
|
+
hookSpecificOutput: {
|
|
98
|
+
hookEventName: 'PreToolUse',
|
|
99
|
+
permissionDecision: decision,
|
|
100
|
+
permissionDecisionReason: reason,
|
|
101
|
+
},
|
|
102
|
+
}));
|
|
103
|
+
}
|
|
104
|
+
function main() {
|
|
105
|
+
const mode = process.env.RONCE_README_CHECK ?? 'warn';
|
|
106
|
+
if (mode === 'off')
|
|
107
|
+
return;
|
|
108
|
+
let parsed;
|
|
109
|
+
try {
|
|
110
|
+
parsed = JSON.parse(readFileSync(0, 'utf-8'));
|
|
111
|
+
}
|
|
112
|
+
catch {
|
|
113
|
+
return; // No input, or not JSON: nothing to decide on.
|
|
114
|
+
}
|
|
115
|
+
if (parsed.tool_name !== 'Bash')
|
|
116
|
+
return;
|
|
117
|
+
const cmd = parsed.tool_input?.command ?? '';
|
|
118
|
+
if (!cmd || !isGitPush(cmd))
|
|
119
|
+
return;
|
|
120
|
+
const cwd = parsed.cwd ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
|
|
121
|
+
const readmePath = join(cwd, 'README.md');
|
|
122
|
+
if (!existsSync(readmePath))
|
|
123
|
+
return;
|
|
124
|
+
const files = changedFiles(cwd);
|
|
125
|
+
if (!files.some((f) => STRUCTURAL.test(f)))
|
|
126
|
+
return; // Nothing that can invalidate a claim.
|
|
127
|
+
const bin = process.env.RONCE_CLAUDE_BIN ?? 'claude';
|
|
128
|
+
const diff = spawnSync('git', ['diff', '--stat', '-p', '@{push}...HEAD'], {
|
|
129
|
+
cwd, encoding: 'utf8', timeout: 15_000, maxBuffer: 32 * 1024 * 1024,
|
|
130
|
+
});
|
|
131
|
+
let readme;
|
|
132
|
+
try {
|
|
133
|
+
readme = readFileSync(readmePath, 'utf-8');
|
|
134
|
+
}
|
|
135
|
+
catch {
|
|
136
|
+
return;
|
|
137
|
+
}
|
|
138
|
+
const run = spawnSync(bin, ['-p', buildPrompt(readme, files, diff.stdout ?? ''), '--output-format', 'json'], {
|
|
139
|
+
cwd, encoding: 'utf8', timeout: TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024,
|
|
140
|
+
});
|
|
141
|
+
// Fail open on every failure mode: claude absent, not authenticated, timed
|
|
142
|
+
// out, rate-limited. A push must never be held hostage by this check.
|
|
143
|
+
if (run.error || run.status !== 0)
|
|
144
|
+
return;
|
|
145
|
+
const verdict = unwrapEnvelope(run.stdout ?? '').trim();
|
|
146
|
+
if (!verdict || verdict.includes(VERDICT_OK))
|
|
147
|
+
return;
|
|
148
|
+
const message = `README may be out of date with this push:\n${verdict}`;
|
|
149
|
+
if (mode === 'block')
|
|
150
|
+
emit('deny', `${message}\n\nFix the README, or push with RONCE_README_CHECK=off.`);
|
|
151
|
+
else
|
|
152
|
+
emit('allow', message);
|
|
153
|
+
}
|
|
154
|
+
// Entry guard by BASENAME, never by extension: this file is authored as .ts and
|
|
155
|
+
// ships as .mjs, and an extension-bound guard silently disables main() in the
|
|
156
|
+
// built copy - the hook then exits 0 doing nothing, with no signal at all.
|
|
157
|
+
const invoked = (process.argv[1] ?? '').split('/').pop()?.replace(/\.(ts|mjs|js)$/, '');
|
|
158
|
+
if (invoked === 'readme-freshness')
|
|
159
|
+
main();
|
|
@@ -20,7 +20,10 @@ const VERBOSE_PATTERNS = [
|
|
|
20
20
|
// two-hook conflict on the same command - PreToolUse updatedInput is last-wins).
|
|
21
21
|
/^\s*npm\s+run\s+(build|test|typecheck|lint)\b/,
|
|
22
22
|
/^\s*npx\s+(vitest|tsc|nuxi|tsx)\b/,
|
|
23
|
-
|
|
23
|
+
// git log/diff are only voluminous UNBOUNDED: `--oneline`, `-n`, `-<count>`
|
|
24
|
+
// or a `--stat` summary stay short, and rewriting them costs readability for
|
|
25
|
+
// nothing since the 4000-char threshold would never fire anyway.
|
|
26
|
+
/^\s*git\s+(log|diff)\b(?!.*(--oneline|--stat|--name-only|--name-status|\s-\d+|\s-n\s))/,
|
|
24
27
|
/^\s*curl\s/,
|
|
25
28
|
/^\s*docker\s+(build|logs)\b/,
|
|
26
29
|
/^\s*rustup\s/,
|
|
@@ -38,10 +41,15 @@ export function isVerboseCommand(cmd) {
|
|
|
38
41
|
}
|
|
39
42
|
export function wrapCommand(cmd, hookDir) {
|
|
40
43
|
const encoded = Buffer.from(cmd).toString('base64');
|
|
41
|
-
//
|
|
42
|
-
//
|
|
43
|
-
//
|
|
44
|
-
|
|
44
|
+
// The command travels base64-encoded so no shell quoting can break it, but an
|
|
45
|
+
// opaque blob is hostile to anything downstream: other hooks observing the
|
|
46
|
+
// same event, a human reading the transcript, a log. So the original is kept
|
|
47
|
+
// in clear as a TRAILING COMMENT - a shell comment runs to end of line and
|
|
48
|
+
// swallows quotes and apostrophes without interpreting them, which a leading
|
|
49
|
+
// `: 'cmd';` prefix does not (it breaks on `echo it's fine`).
|
|
50
|
+
// Newlines are flattened, otherwise the comment would swallow the next line.
|
|
51
|
+
const readable = cmd.replace(/\s*\n\s*/g, ' ').trim();
|
|
52
|
+
return `TRUNCATE_CMD_B64=${encoded} node '${hookDir}/truncate-bash-output.mjs' # ${readable}`;
|
|
45
53
|
}
|
|
46
54
|
function readStdin() {
|
|
47
55
|
try {
|