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 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.
@@ -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
- /^\s*git\s+(log|diff)\b/,
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
- // Run the helper via `npx tsx` (works on any Node ≥ 18) rather than
42
- // `node --experimental-strip-types` (only Node ≥ 22.6), matching how the
43
- // hooks themselves are wired in settings.json.
44
- return `TRUNCATE_CMD_B64=${encoded} node '${hookDir}/truncate-bash-output.mjs'`;
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 {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ronce-racine",
3
- "version": "0.5.2",
3
+ "version": "0.5.3",
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",