ronce-racine 0.5.2 → 0.5.3
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 +3 -0
- package/dist/hooks/README.md +22 -0
- package/dist/hooks/truncate-output.mjs +13 -5
- package/package.json +1 -1
package/AGENTS.md
CHANGED
|
@@ -7,6 +7,9 @@ Doc aimed at an agent (LLM) that **works on** this repo or uses it to **equip an
|
|
|
7
7
|
Canonical source of **generic Claude Code config** (project-agnostic), installable in any repository:
|
|
8
8
|
`rules/` (always-on, by `paths`) · `skills/` (on-demand workflows) · `hooks/` (settings.json scripts - granular, one hook per `.ts` file) · `agents/` (subagents) · `scripts/` (executable detections). CLI: `install.ts` is the single tool (all families; rules-only via `--rules-only`).
|
|
9
9
|
|
|
10
|
+
|
|
11
|
+
**Hook composition**: several plugins observe the same event and `PreToolUse` `updatedInput` is last-wins. A hook that rewrites a command MUST keep the original readable (trailing shell comment), must not rewrite when the rewrite buys nothing, and must never mask an exit code through a pipe. See `hooks/README.md`.
|
|
12
|
+
|
|
10
13
|
## Non-negotiable rules
|
|
11
14
|
|
|
12
15
|
- **Genericity**: an artifact here contains **no** project coupling (crate/script/path name, imposed tracker, imposed stack). If useful but coupled → split: the generic principle here, the tooling in the project repo. A routing override "e.g. acme-app → `x`, it wins" is allowed.
|
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)
|
|
@@ -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 {
|