@thedecipherist/claude-packs 0.0.0-stage → 1.1.0

package/configurations/node/config.json

@@ -0,0 +1,102 @@
+{
+  "name": "node",
+  "description": "A Node.js or TypeScript service, web app, CLI, library, MCP server or edge proxy: base, plus the packs its stack needs (js-ts, mongo, fastify, ai, docker, shell-hooks, html-ui, web, tui, nginx). The presets pick them.",
+  "packs": {
+    "always": [
+      "base",
+      "writing",
+      "hook-proof"
+    ],
+    "choose": [
+      "js-ts",
+      "mongo",
+      "postgres",
+      "fastify",
+      "ai",
+      "docker",
+      "shell-hooks",
+      "html-ui",
+      "web",
+      "tui",
+      "nginx",
+      "stored-text",
+      "ui-craft",
+      "python",
+      "shell",
+      "cpp",
+      "http-api",
+      "react",
+      "multi-tenant",
+      "websocket",
+      "host-agent",
+      "go",
+      "rust",
+      "ci",
+      "dynamic-data",
+      "zod",
+      "content-site"
+    ],
+    "default": [
+      "js-ts"
+    ]
+  },
+  "layout": {
+    "folders": {
+      "docs": {
+        "path": "docs",
+        "purpose": "spec, decisions, versions.md"
+      },
+      "src": {
+        "path": "src",
+        "purpose": "the code: the entry, routes, handlers, the database gateway, schemas"
+      },
+      "test": {
+        "path": "test",
+        "purpose": "tests"
+      },
+      "tools": {
+        "path": "tools",
+        "purpose": "scripts that never ship"
+      }
+    },
+    "kinds": {
+      "tests": {
+        "what": "tests",
+        "in": "test",
+        "concepts": [
+          "js-tests"
+        ],
+        "files": [
+          "**/*.test.*",
+          "**/*.spec.*"
+        ]
+      },
+      "docs": {
+        "what": "the spec, decisions, research, versions.md",
+        "in": "docs",
+        "concepts": [
+          "docs-folder"
+        ]
+      },
+      "tools": {
+        "what": "scripts that never ship",
+        "in": "tools"
+      }
+    }
+  },
+  "sourceFiles": "\\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs)$",
+  "preamble": {
+    "always": [
+      "Ask the user before inventing a new folder. A new folder goes into `.claude/layout.json` first.",
+      "When a hook, check or guard blocks work that is correct, stop and report its exact message. A blocking hook is a red check: fix the hook first, with a selftest, then continue.",
+      "When a command is refused or fails, the step fails loudly. Never report a refused write or a failed command as done.",
+      "claude-packs (`@thedecipherist/claude-packs`) is the source of truth for every rule, check, hook and skill this project's configuration installs. A fix to one of them is made in the kit, with its test, and comes here with `npx --no-install @thedecipherist/claude-packs update`. A project edits its installed copy only to try a fix before it goes into the kit."
+    ],
+    "never": [
+      "Create source files outside these folders, or put a kind of thing anywhere but its place. The folder-law and placement-law hooks refuse both.",
+      "Edit files in `.claude/rules`, `.claude/checks` or `.claude/hooks` to get past a block. Fix the code, or ask the user to change the law.",
+      "Route around a block: no override variables, no writing through the shell after a refusal, no parking files in a scratchpad, no putting new code into an unrelated existing file.",
+      "Point at a document by line number. Cite a fixed anchor (`{#id}`) or a symbol name; lines move."
+    ]
+  }
+}

package/configurations/python/config.json

@@ -0,0 +1,99 @@
+{
+  "name": "python",
+  "description": "Python projects: universal engineering and the python pack.",
+  "packs": {
+    "always": [
+      "base",
+      "writing",
+      "hook-proof"
+    ],
+    "choose": [
+      "python",
+      "shell",
+      "docker",
+      "ai",
+      "mongo",
+      "postgres",
+      "js-ts",
+      "cpp",
+      "http-api",
+      "multi-tenant",
+      "ci",
+      "go",
+      "rust",
+      "dynamic-data",
+      "web",
+      "ui-craft",
+      "content-site"
+    ],
+    "default": [
+      "python"
+    ]
+  },
+  "layout": {
+    "folders": {
+      "docs": {
+        "path": "docs",
+        "purpose": "spec, laws, licences, work orders, decisions"
+      },
+      "src": {
+        "path": "src",
+        "purpose": "all source code, only inside the subfolders below"
+      },
+      "tests": {
+        "path": "tests",
+        "purpose": "unit tests, gates with planted faults, golden files"
+      },
+      "tools": {
+        "path": "tools",
+        "purpose": "scripts and research tooling (not shipped)"
+      }
+    },
+    "kinds": {
+      "tests": {
+        "what": "tests, gates with planted faults, golden renders",
+        "in": "tests",
+        "concepts": [
+          "tests"
+        ],
+        "files": [
+          "**/*_test.*",
+          "**/*Test.cpp",
+          "**/*Tests.cpp",
+          "**/test_*.*",
+          "**/*.test.*"
+        ]
+      },
+      "docs": {
+        "what": "the spec, laws.md, decisions, research, work orders",
+        "in": "docs",
+        "concepts": [
+          "docs-folder"
+        ],
+        "files": [
+          "**/laws.md",
+          "**/*-spec.md"
+        ]
+      },
+      "tools": {
+        "what": "scripts and research tools that never ship",
+        "in": "tools"
+      }
+    }
+  },
+  "preamble": {
+    "always": [
+      "Ask the user before inventing a new folder. A new folder goes into `.claude/layout.json` first.",
+      "When a hook, check or guard blocks work that is correct, stop and report its exact message. A blocking hook is a red check: fix the hook first, with a selftest, then continue.",
+      "When a command is refused or fails, the step fails loudly. Never report a refused write or a failed command as done.",
+      "claude-packs (`@thedecipherist/claude-packs`) is the source of truth for every rule, check, hook and skill this project's configuration installs. A fix to one of them is made in the kit, with its test, and comes here with `npx --no-install @thedecipherist/claude-packs update`. A project edits its installed copy only to try a fix before it goes into the kit."
+    ],
+    "never": [
+      "Create source files outside these folders, or put a kind of thing anywhere but its place. The folder-law and placement-law hooks refuse both.",
+      "Edit files in `.claude/rules`, `.claude/checks` or `.claude/hooks` to get past a block. Fix the code, or ask the user to change the law.",
+      "Route around a block: no override variables, no writing through the shell after a refusal, no parking files in a scratchpad, no putting new code into an unrelated existing file.",
+      "Point at a document by line number. Cite a fixed anchor (`{#id}`) or a symbol name; lines move."
+    ]
+  },
+  "sourceFiles": "\\.(?:py|pyi)$"
+}

package/configurations/rust/config.json

@@ -0,0 +1,106 @@
+{
+  "name": "rust",
+  "description": "Rust projects: universal engineering and the rust pack.",
+  "packs": {
+    "always": [
+      "base",
+      "writing",
+      "hook-proof"
+    ],
+    "choose": [
+      "rust",
+      "go",
+      "shell",
+      "docker",
+      "postgres",
+      "http-api",
+      "multi-tenant",
+      "websocket",
+      "host-agent",
+      "ci",
+      "js-ts",
+      "python",
+      "dynamic-data",
+      "web",
+      "ui-craft",
+      "content-site"
+    ],
+    "default": [
+      "rust"
+    ]
+  },
+  "layout": {
+    "folders": {
+      "docs": {
+        "path": "docs",
+        "purpose": "spec, laws, licences, work orders, decisions"
+      },
+      "src": {
+        "path": "src",
+        "purpose": "the source of a single crate"
+      },
+      "tests": {
+        "path": "tests",
+        "purpose": "integration tests (unit tests live beside their code, in a #[cfg(test)] module)"
+      },
+      "tools": {
+        "path": "tools",
+        "purpose": "scripts and research tooling (not shipped)"
+      },
+      "crates": {
+        "path": "crates",
+        "purpose": "the crates of a workspace, each with its own src/ and tests/",
+        "planned": true
+      },
+      "benches": {
+        "path": "benches",
+        "purpose": "benchmarks",
+        "planned": true
+      },
+      "examples": {
+        "path": "examples",
+        "purpose": "runnable examples",
+        "planned": true
+      }
+    },
+    "kinds": {
+      "tests": {
+        "what": "integration tests",
+        "in": "tests",
+        "concepts": [
+          "tests"
+        ]
+      },
+      "docs": {
+        "what": "the spec, laws.md, decisions, research, work orders",
+        "in": "docs",
+        "concepts": [
+          "docs-folder"
+        ],
+        "files": [
+          "**/laws.md",
+          "**/*-spec.md"
+        ]
+      },
+      "tools": {
+        "what": "scripts and research tools that never ship",
+        "in": "tools"
+      }
+    }
+  },
+  "preamble": {
+    "always": [
+      "Ask the user before inventing a new folder. A new folder goes into `.claude/layout.json` first.",
+      "When a hook, check or guard blocks work that is correct, stop and report its exact message. A blocking hook is a red check: fix the hook first, with a selftest, then continue.",
+      "When a command is refused or fails, the step fails loudly. Never report a refused write or a failed command as done.",
+      "claude-packs (`@thedecipherist/claude-packs`) is the source of truth for every rule, check, hook and skill this project's configuration installs. A fix to one of them is made in the kit, with its test, and comes here with `npx --no-install @thedecipherist/claude-packs update`. A project edits its installed copy only to try a fix before it goes into the kit."
+    ],
+    "never": [
+      "Create source files outside these folders, or put a kind of thing anywhere but its place. The folder-law and placement-law hooks refuse both.",
+      "Edit files in `.claude/rules`, `.claude/checks` or `.claude/hooks` to get past a block. Fix the code, or ask the user to change the law.",
+      "Route around a block: no override variables, no writing through the shell after a refusal, no parking files in a scratchpad, no putting new code into an unrelated existing file.",
+      "Point at a document by line number. Cite a fixed anchor (`{#id}`) or a symbol name; lines move."
+    ]
+  },
+  "sourceFiles": "(?<!/build)\\.rs$"
+}

package/configurations/synth-creator/config.json

@@ -0,0 +1,148 @@
+{
+  "name": "synth-creator",
+  "description": "JUCE synths and effects units: realtime audio, the sound engines, the Dawn GPU painter, Stellix. Everything the kit installed before configurations existed.",
+  "packs": {
+    "always": [
+      "base",
+      "synth-creator",
+      "writing",
+      "hook-proof"
+    ],
+    "choose": [
+      "cpp",
+      "audio-core",
+      "gpu-painter",
+      "stellix",
+      "python",
+      "shell",
+      "ci",
+      "reverse-engineering",
+      "midi",
+      "sound-design",
+      "instrument-shell"
+    ],
+    "default": [
+      "cpp",
+      "audio-core"
+    ]
+  },
+  "layout": {
+    "folders": {
+      "docs": {
+        "path": "docs",
+        "purpose": "spec, laws, licences, work orders, decisions"
+      },
+      "src": {
+        "path": "src",
+        "purpose": "all source code, only inside the subfolders below"
+      },
+      "tests": {
+        "path": "tests",
+        "purpose": "unit tests, gates with planted faults, golden files"
+      },
+      "tools": {
+        "path": "tools",
+        "purpose": "scripts and research tooling (not shipped)"
+      }
+    },
+    "kinds": {
+      "tests": {
+        "what": "tests, gates with planted faults, golden renders",
+        "in": "tests",
+        "concepts": [
+          "tests"
+        ],
+        "files": [
+          "**/*_test.*",
+          "**/*Test.cpp",
+          "**/*Tests.cpp",
+          "**/test_*.*",
+          "**/*.test.*"
+        ]
+      },
+      "docs": {
+        "what": "the spec, laws.md, decisions, research, work orders",
+        "in": "docs",
+        "concepts": [
+          "docs-folder"
+        ],
+        "files": [
+          "**/laws.md",
+          "**/*-spec.md"
+        ]
+      },
+      "tools": {
+        "what": "scripts and research tools that never ship",
+        "in": "tools"
+      }
+    }
+  },
+  "hookOrder": {
+    "PreToolUse Write|Edit|MultiEdit|NotebookEdit|Bash": [
+      "lesson-checks.mjs",
+      "file-size-guard.mjs",
+      "frozen-files.mjs",
+      "placement-law.mjs",
+      "protect-vendor.mjs",
+      "spec-lock.mjs",
+      "folder-law.mjs",
+      "shape-law.mjs",
+      "brief-guard.mjs",
+      "once-only.mjs",
+      "secrets-guard.mjs",
+      "untrusted-boundary.mjs",
+      "realtime-guard.mjs",
+      "browser-guard.py",
+      "no-shipped-images.mjs"
+    ],
+    "PreToolUse Agent|Task": [
+      "brief-guard.mjs"
+    ],
+    "PreToolUse Bash": [
+      "stage-guard.mjs",
+      "git-guard.mjs",
+      "build-guard.mjs"
+    ],
+    "PreToolUse *": [
+      "time-guard.mjs"
+    ],
+    "PostToolUse *": [
+      "time-guard.mjs"
+    ],
+    "Stop": [
+      "idle-wake.mjs",
+      "making-check.mjs",
+      "git-guard.mjs"
+    ],
+    "SessionStart compact": [
+      "user-asks.mjs"
+    ],
+    "SessionStart": [
+      "build-sweep.mjs"
+    ],
+    "SubagentStop": [
+      "build-sweep.mjs"
+    ],
+    "UserPromptSubmit": [
+      "making.mjs"
+    ],
+    "PostToolUse Write|Edit|MultiEdit|NotebookEdit|Bash": [
+      "param-id-lock.mjs"
+    ]
+  },
+  "preamble": {
+    "always": [
+      "Ask the user before inventing a new folder. A new folder goes into `.claude/layout.json` first.",
+      "When a hook, check or guard blocks work that is correct, stop and report its exact message. A blocking hook is a red check: fix the hook first, with a selftest, then continue.",
+      "When a command is refused or fails, the step fails loudly. Never report a refused write or a failed command as done.",
+      "claude-packs (`@thedecipherist/claude-packs`) is the source of truth for every rule, check, hook and skill used to build synths. A fix to one of them, or a lesson that should hold in every synth, is made in the kit, with its test, and comes here with `npx --no-install @thedecipherist/claude-packs update`, so every synth gets it. A project edits its installed copy only to try a fix before it goes into the kit."
+    ],
+    "never": [
+      "Create source files outside these folders, or put a kind of thing anywhere but its place. The folder-law and placement-law hooks refuse both.",
+      "Put drawing code in audio or world folders, or audio and world logic in the painter or UI folders.",
+      "Edit files in `.claude/rules`, `.claude/checks` or `.claude/hooks` to get past a block. Fix the code, or ask the user to change the law.",
+      "Route around a block: no override variables, no writing through the shell after a refusal, no parking files in a scratchpad, no putting new code into an unrelated existing file.",
+      "Point at a document by line number. Cite a fixed anchor (`{#id}`) or a symbol name; lines move."
+    ]
+  }
+}

package/global/hooks/gnu-shell.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// gnu-shell (SessionStart; global by design): the Bash tool runs bash 5 with the GNU tools, not zsh with the BSD ones.
+//
+// "can you do a proper skill/hook for zsh because this seems to happen alot?". Claude Code's Bash tool runs
+// the login shell, zsh on this Mac: `$VAR` holding several words is not split, an unmatched glob is an error, and
+// `sed -i`, `date -d`, `stat -c` are the BSD tools'. The fix has two halves:
+//   1. THE SHELL: settings.json `env` sets CLAUDE_CODE_SHELL and SHELL to /opt/homebrew/bin/bash (Homebrew's bash 5).
+//   2. THE TOOLS: this hook writes one `export PATH=...` to the file CLAUDE_ENV_FILE names, which Claude Code sources
+//      before every Bash call: ~/.claude/bin first (buildq, the machine-wide build queue), then the `libexec/gnubin`
+//      folder of every GNU formula installed, so sed, date, stat, awk, tar, find, xargs, which are the GNU builds; and a
+//      line that warns on EVERY command while the session runs zsh (WB-41). The user's own terminal is not touched.
+// It says so at the session's start when it cannot deliver: no Homebrew, a formula missing, the shell not bash 5.
+// On Linux (KWB-27) the system's sed, date, stat and awk are the GNU builds already: no Homebrew is looked for, the PATH line
+// puts only ~/.claude/bin first, and the shell is still checked for bash 5 (any bash 5, not Homebrew's).
+//   node gnu-shell.mjs --selftest
+import { execFileSync } from 'node:child_process';
+import { appendFileSync, chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+
+export const FORMULAS = ['coreutils', 'findutils', 'gawk', 'gnu-sed', 'gnu-tar', 'gnu-which', 'grep'];
+const BASH = '/opt/homebrew/bin/bash';
+const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return false; } };
+const gnubin = (pre, f) => join(pre, 'opt', f, 'libexec', 'gnubin');
+
+// Homebrew's prefix, found on the disk, not by asking brew (a hook started by an app may not have brew on PATH).
+export function prefix() {
+  return ['/opt/homebrew', '/usr/local'].find((p) => isDir(join(p, 'opt')) && FORMULAS.some((f) => isDir(gnubin(p, f)))) ?? null;
+}
+
+function bashMajor(path) {
+  try { return Number(execFileSync(path, ['--version'], { encoding: 'utf8', timeout: 5000 }).match(/version (\d+)\./)?.[1] ?? 0); } catch { return 0; }
+}
+
+const shellSaid = (sh, mac) => `gnu-shell: the Bash tool's shell is ${sh || 'unknown'}, not ${mac ? `Homebrew's bash 5 (${BASH})` : 'bash 5'}: ` +
+  '`$VAR` lists do not split (use ${=VAR} or an array) and an unmatched glob is an error. The env block in .claude/settings.json takes effect from the next session.';
+const shellOk = (sh) => basename(sh ?? '') === 'bash' && bashMajor(sh) >= 5;
+const ZSH_WARNING = '[ -n "$ZSH_VERSION" ] && echo "gnu-shell: THIS SESSION RUNS ZSH, not bash 5 (variables are not split into words, an unmatched glob is an error). Restart Claude Code to get bash 5." >&2\n';
+
+// Linux: the tools are GNU already; ~/.claude/bin first, the zsh warning, and the shell checked.
+function runLinux(envFile, shell) {
+  const said = [];
+  if (envFile) {
+    appendFileSync(envFile, 'export PATH="$HOME/.claude/bin:${PATH}"\n');
+    appendFileSync(envFile, ZSH_WARNING);
+  } else said.push('gnu-shell: CLAUDE_ENV_FILE is not set, so ~/.claude/bin could not be put first on the Bash tool\'s PATH.');
+  if (!shellOk(shell)) said.push(shellSaid(shell, false));
+  return said;
+}
+
+// Writes the PATH line; returns what must be said (empty when all is as it should be).
+export function run(envFile, shell, { platform = process.platform, pre } = {}) {
+  if (platform !== 'darwin') return runLinux(envFile, shell);
+  if (pre === undefined) pre = prefix();
+  const said = [];
+  if (!pre) {
+    return ["gnu-shell: no Homebrew found (/opt/homebrew or /usr/local): this session's sed, date, stat and awk are the macOS (BSD) builds, " +
+      "not GNU. Write BSD-safe commands (sed -i '' ..., no date -d)."];
+  }
+  const have = FORMULAS.filter((f) => isDir(gnubin(pre, f))).map((f) => gnubin(pre, f));
+  const missing = FORMULAS.filter((f) => !isDir(gnubin(pre, f)));
+  if (envFile && have.length) {
+    appendFileSync(envFile, `export PATH="$HOME/.claude/bin:${have.join(':')}:\${PATH}"\n`);
+    appendFileSync(envFile, ZSH_WARNING);
+  }
+  if (missing.length) {
+    said.push(`gnu-shell: GNU formula(s) not installed: ${missing.join(', ')}; those tools are the macOS (BSD) builds this session. ` +
+      `Install them with: brew install ${missing.join(' ')}`);
+  }
+  if (!envFile) said.push('gnu-shell: CLAUDE_ENV_FILE is not set, so the GNU tools could not be put first on the Bash tool\'s PATH.');
+  if (!shellOk(shell)) said.push(shellSaid(shell, true));
+  return said;
+}
+
+// A fake bash that reports the given version: the selftest never depends on this machine's /bin/bash (KWB-27).
+function fakeBash(dir, version) {
+  const file = join(dir, `bash-${version}`, 'bash');
+  mkdirSync(join(dir, `bash-${version}`), { recursive: true });
+  writeFileSync(file, `#!/bin/sh\necho 'GNU bash, version ${version}(1)-release'\n`);
+  chmodSync(file, 0o755);
+  return file;
+}
+
+function selftest() {
+  const bad = [];
+  const expect = (name, ok) => { if (!ok) bad.push(name); };
+  const d = mkdtempSync(join(tmpdir(), 'gnu-shell-'));
+  const bash5 = fakeBash(d, '5.2.37');
+  const bash32 = fakeBash(d, '3.2.57');
+  const notBash5 = (said) => said.some((s) => s.includes('not ') && s.includes('bash 5'));
+  // macOS
+  const pre = join(d, 'brew');
+  for (const f of FORMULAS) mkdirSync(gnubin(pre, f), { recursive: true });
+  const mac = (file, shell) => run(join(d, file), shell, { platform: 'darwin', pre });
+  const said = mac('env.sh', bash5);
+  const text = readFileSync(join(d, 'env.sh'), 'utf8');
+  const line = text.split('\n')[0];
+  expect("mac: every formula's gnubin written first on PATH", FORMULAS.every((f) => line.includes(`/opt/${f}/libexec/gnubin`)) && line.endsWith(':${PATH}"'));
+  expect('mac: ~/.claude/bin first', line.startsWith('export PATH="$HOME/.claude/bin:'));
+  expect('mac: a zsh session is warned on every command (WB-41)', text.includes('[ -n "$ZSH_VERSION" ]') && text.toUpperCase().includes('RESTART'));
+  expect('mac: bash 5 and every formula: nothing said', said.length === 0);
+  expect('mac: no Homebrew is said', run(join(d, 'e1.sh'), bash5, { platform: 'darwin', pre: null }).some((s) => s.includes('no Homebrew')));
+  expect("mac: zsh as the shell is said", mac('e3.sh', '/bin/zsh').some((s) => s.includes("not Homebrew's bash 5")));
+  expect("mac: Apple's bash 3.2 is said", mac('e4.sh', bash32).some((s) => s.includes("not Homebrew's bash 5")));
+  rmSync(gnubin(pre, 'gnu-sed'), { recursive: true });
+  expect('mac: a missing formula is said, by name', mac('e2.sh', bash5).some((s) => s.includes('gnu-sed')));
+  // Linux (KWB-27): the system tools are GNU; no Homebrew is looked for, even when one is there
+  const linux = (file, shell) => run(join(d, file), shell, { platform: 'linux', pre });
+  const lsaid = linux('l1.sh', bash5);
+  const ltext = readFileSync(join(d, 'l1.sh'), 'utf8');
+  expect('linux: bash 5: nothing said (no Homebrew, no BSD tools)', lsaid.length === 0);
+  expect('linux: ~/.claude/bin first, no gnubin', ltext.split('\n')[0] === 'export PATH="$HOME/.claude/bin:${PATH}"');
+  expect('linux: a zsh session is warned on every command', ltext.includes('[ -n "$ZSH_VERSION" ]'));
+  expect('linux: zsh as the shell is said', notBash5(linux('l2.sh', '/usr/bin/zsh')));
+  expect('linux: bash 3.2 is said', notBash5(linux('l3.sh', bash32)));
+  expect('linux: no env file is said', run(undefined, bash5, { platform: 'linux' }).some((s) => s.includes('CLAUDE_ENV_FILE')));
+  rmSync(d, { recursive: true, force: true });
+  for (const b of bad) console.error(`FAIL  ${b}`);
+  console.log(`gnu-shell selftest: ${bad.length ? `${bad.length} wrong` : 'OK'}`);
+  return bad.length ? 1 : 0;
+}
+
+function main() {
+  if (process.argv.includes('--selftest')) return selftest();
+  try { readFileSync(0, 'utf8'); } catch { /* no stdin */ }
+  const said = run(process.env.CLAUDE_ENV_FILE, process.env.CLAUDE_CODE_SHELL || process.env.SHELL);
+  if (said.length) console.log(said.join('\n')); // SessionStart: what is printed reaches the session's context
+  return 0;
+}
+
+process.exit(main());

package/global/hooks/lib/shell-writes.mjs

@@ -0,0 +1,2 @@
+// The one shell reader is base's. This line lets the global hooks run from the kit's own folder; `global add` installs the reader itself (lib/global.mjs).
+export * from '../../../packs/base/hooks/lib/shell-writes.mjs';

package/global/hooks/shell-traps.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// shell-traps (PreToolUse, Bash; global by design): refuses the shell traps that cost time on this Mac, with the right form.
+//
+// "make a skill that triggers the moment you touch bash" (the skill: shell-rules). A skill is read only
+// when remembered; this hook sees every command. It refuses (exit 2):
+//   - BSD flags on the GNU tools first on PATH: `date -r <seconds>`, `stat -f`, `sed -i ''` (WB-23);
+//   - an in-place perl edit of a code file (apprack B-135: twice it wrote its text at the top of the file);
+//   - a `for` loop over an unquoted variable while the session runs zsh (the words are not split there, WB-41);
+//   - `;` chaining a destructive step (checkout --detach, rm -rf, kill) after another command (WB-19).
+// Text inside heredoc bodies and quoted strings is ignored.
+//   node shell-traps.mjs --selftest
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+
+export function noHeredocs(cmd) {
+  const out = [];
+  const lines = cmd.split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    out.push(lines[i]);
+    const m = lines[i].match(/<<-?\s*['"]?(\w+)['"]?/);
+    if (m) { i += 1; while (i < lines.length && lines[i].trim() !== m[1]) i += 1; }
+  }
+  return out.join('\n');
+}
+
+const bodyOf = (cmd) => noHeredocs(cmd).replace(/'[^']*'|"(?:\\.|[^"\\])*"/g, "''");
+const zshSession = () => basename(process.env.SHELL ?? '').includes('zsh') && !(process.env.CLAUDE_CODE_SHELL ?? '').includes('bash');
+
+export function verdict(cmd, zsh = zshSession()) {
+  const b = bodyOf(cmd);
+  if (/(^|[\s;&|(])date\s+(-\w*\s+)*-r\s+\$?\(?[\d@$]/.test(b)) {
+    return "`date -r <seconds>` is the BSD form; here date is GNU (-r means a FILE's time). Use: date -d @<seconds> '+%Y-%m-%d %H:%M %Z'";
+  }
+  if (/(^|[\s;&|(])stat\s+(-\w+\s+)*-f\s/.test(b)) {
+    return '`stat -f` is the BSD form; here stat is GNU (-f is file-SYSTEM info). Use `stat -c %Y file`, or better Python os.stat for a measurement (WB-23).';
+  }
+  if (/(^|[\s;&|(])sed\s+-i\s+(''|"")(\s|$)/.test(noHeredocs(cmd))) return "`sed -i ''` is the BSD form; here sed is GNU: `sed -i 's/a/b/' file`."; // the real quotes
+  if (/(^|[\s;&|(])perl\s+(-\w+\s+)*-\w*i\w*\b[^;&|]*\.(ts|tsx|js|mjs|cpp|cc|c|h|hpp|py|cmake)\b/.test(b)) {
+    return 'an in-place perl edit of a code file: twice it wrote its text at the top of the file instead of in place (apprack B-135). Change code with the Edit tool; perl -pi stays for data files.';
+  }
+  if (zsh && /\bfor\s+\w+\s+in\s+\$\w+\s*;/.test(b)) {
+    return 'this session runs zsh: `for x in $VAR` does not split words. Use `${=VAR}`, an explicit list, or a script file run with bash. Restart Claude Code to get bash 5 (WB-41).';
+  }
+  if (/;\s*(GUARD_OK=1\s+)?git\s+checkout\s+-q?\s*--detach|;\s*rm\s+-rf\s|;\s*kill\s/.test(b)) {
+    return 'a destructive step chained with `;` runs even when the step before it failed (WB-19). Chain with `&&`, or run it as its own command after checking the first.';
+  }
+  return null;
+}
+
+function selftest() {
+  const cases = [
+    ["TZ=America/New_York date -r 1797000000 '+%F'", false, true], ["date -d @1797000000 '+%F'", false, false],
+    ["stat -f '%m %N' x", false, true], ['stat -c %Y x', false, false], ["sed -i '' 's/a/b/' f", false, true],
+    ["sed -i 's/a/b/' f", false, false], ['for t in $LIST; do echo $t; done', true, true],
+    ['for t in $LIST; do echo $t; done', false, false], ['for t in a b; do echo $t; done', true, false],
+    ['python3 x.py; GUARD_OK=1 git checkout -q --detach', false, true], ['python3 x.py && git checkout -q --detach', false, false],
+    ["echo 'date -r 5 and stat -f'", false, false], ["cat <<'EOF'\nsed -i '' x\nEOF", false, false],
+    ["perl -0pi -e 's|a|b|' src/readonly.ts", false, true], ["cd x && perl -pi -e 's/a/b/' lib/a.cpp", false, true],
+    ["perl -pi -e 's/a/b/' docs/not-carried.md", false, false], ["perl -0pi -e 's/a/b/' build.json", false, false],
+    ["perl -ne 'print' src/a.ts", false, false],
+  ];
+  const bad = cases.filter(([cmd, zsh, want]) => (verdict(cmd, zsh) !== null) !== want);
+  for (const [cmd, zsh, want] of bad) console.error(`shell-traps selftest FAILED: ${want ? 'not refused' : 'wrongly refused'}: ${cmd.replace(/\n/g, ' / ')}${zsh ? ' (zsh)' : ''}`);
+  if (!bad.length) console.log(`shell-traps selftest: OK (${cases.length} cases)`);
+  return bad.length ? 1 : 0;
+}
+
+function main() {
+  if (process.argv.includes('--selftest')) return selftest();
+  let ev;
+  try { ev = JSON.parse(readFileSync(0, 'utf8')); } catch { return 0; }
+  if (ev.tool_name !== 'Bash') return 0;
+  const v = verdict(String(ev.tool_input?.command ?? ''));
+  if (!v) return 0;
+  process.stderr.write(`shell-traps: ${v}\n`);
+  return 2;
+}
+
+process.exit(main());