fix: keep quoted paths, drop heredoc bodies, split the verb tables

The previous commit's quote handling DELETED quoted spans, which took the path
with them. `cd "<worktree>" && npm ci` left `cd` with no argument, so the
install was judged against the session cwd and allowed. That is the arrival
shape this hook exists for, and quoting a path is the ordinary spelling, so the
rewrite regressed the headline case.

Quoted spans are now neutralised rather than removed: the quote characters go,
the content stays, and only the separators inside them are defused. It is a
character-by-character state machine because quote nesting has to be tracked,
and a single-quote sed pass running first paired the apostrophe in `can't` with
the next quote in the line and swallowed a real install between them.

Heredoc bodies are dropped. This repo's docs are full of `npm install` lines
and a newline is a command separator here.

The merged verb table is per manager again: `a` is a BUN alias, so merging it
blocked `npm --workspace a run build`, and `bun upgrade` upgrades the Bun
binary rather than node_modules. `npm audit fix` joins the block list on the
same rationale as `link`, `rebuild` and `prune`, `--cwd` and `--dir` are mined
as target directories like `--prefix`, and an informational `yarn --version` is
no longer read as a bare install.

Author: vivek7405

.claude/hooks/block-install-in-linked-worktree.sh

@@ -53,17 +53,74 @@ if [ -z "$cmd" ]; then exit 0; fi
 # THROUGH the link rather than replacing it. `link`, `rebuild` and `prune` are
 # here for the same reason as the remove verbs: they all mutate the tree that
 # the symlink points at.
-INSTALL_VERBS='install-ci-test|clean-install-test|install-clean|clean-install|install-test|install|isntall|isntal|isnta|isnt|instal|insta|inst|ins|in|i|add|a|ci|cit|sit|it|ic|update|upgrade|udpate|up|dedupe|ddp|uninstall|unlink|un|remove|rm|r|link|ln|rebuild|rb|prune'
+# PER MANAGER, not one merged list. Merging them blocked `npm --workspace a run
+# build`, because `a` is a BUN alias for `add`, and blocked `bun upgrade`, which
+# upgrades the Bun BINARY and never touches node_modules.
+#
+# The one-letter aliases `a` and `r` are deliberately omitted from npm's list.
+# They are rare as commands and common as flag VALUES, and the scan cannot tell
+# the two apart, so admitting them blocks `npm -w a run build`. KNOWN GAP: `npm
+# r <pkg>` and `npm a <pkg>` are therefore not blocked. That is the deliberate
+# trade, because the false positive lands on an ordinary command while the false
+# negative lands on a spelling almost nobody types, and the repair, report and
+# doctor layers still catch the damage after the fact.
+NPM_INSTALL='install-ci-test|clean-install-test|install-clean|clean-install|install-test|install|isntall|isntal|isnta|isnt|instal|insta|inst|ins|in|i|add|ci|cit|sit|it|ic|update|upgrade|udpate|up|dedupe|ddp|uninstall|unlink|un|remove|rm|link|ln|rebuild|rb|prune'
+BUN_INSTALL='install|i|add|a|remove|rm|link|unlink|update|pm'
+PNPM_INSTALL='install|i|add|update|upgrade|up|dedupe|remove|rm|uninstall|un|link|unlink|prune|rebuild'
+YARN_INSTALL='install|add|upgrade|up|dedupe|remove|link|unlink'
 # Verbs that do NOT touch node_modules. Listed explicitly so the scan can STOP:
 # without them, `npm run test -- --grep add` would keep scanning and hit `add`.
 SAFE_VERBS='run|run-script|rum|urn|test|tst|t|start|stop|restart|exec|x|ls|list|la|ll|init|innit|create|publish|pack|version|view|v|info|show|why|ping|config|c|get|set|docs|home|repo|bugs|audit|fund|outdated|prefix|root|bin|whoami|token|team|org|access|star|unstar|search|s|se|find|help|doctor|explain|edit|deprecate|dist-tag|hook|login|logout|adduser|owner|profile|shrinkwrap|unpublish|completion|diff|query|sbom'
+# `npm audit` reports and is safe; `npm audit fix` INSTALLS revised versions
+# straight through the link, so it is matched ahead of the safe-verb scan.
+AUDIT_FIX='(^|[[:space:]])audit([[:space:]]+-[^[:space:]]+)*[[:space:]]+fix([[:space:]]|$)'
 # A GLOBAL install writes to the npm prefix, never through the local link, and
 # `npm update -g webjsdev` is this repo's documented post-release step.
 GLOBAL='(^|[[:space:]])(-g|--global)([[:space:]]|$)'
 
-# STAGE 1: remove quoted spans. See the docblock; this is what keeps a shell
-# metacharacter inside a commit message from being read as a command boundary.
-scrubbed=$(printf '%s' "$cmd" | sed -e "s/'[^']*'/ /g" -e 's/"[^"]*"/ /g')
+# STAGE 1: neutralise quoted spans and drop heredoc bodies.
+#
+# A quoted span must keep its CONTENT (a quoted path is the ordinary defensive
+# spelling of `cd "<worktree>" && npm ci`, which is the arrival shape this hook
+# exists for) while losing its power to look like a command boundary. So the
+# quote characters are removed and only the SEPARATORS inside them are
+# neutralised. Deleting the whole span instead loses the path and fails open.
+#
+# It is a character-by-character state machine rather than a pair of seds
+# because quote nesting has to be tracked: an apostrophe inside a double-quoted
+# string is literal, and a sed pass over `'...'` first would pair it with the
+# next single quote in the line and swallow whatever sat between.
+#
+# A heredoc BODY is not commands. This repo's docs are full of `npm install`
+# lines, and `cat > doc.md <<'EOF'` ... `EOF` must not read as an install.
+scrubbed=$(printf '%s' "$cmd" | awk '
+  function flushline(l) { print l }
+  BEGIN { heredoc = "" }
+  {
+    if (heredoc != "") {
+      line = $0
+      sub(/[[:space:]]+$/, "", line)
+      if (line == heredoc) heredoc = ""
+      next
+    }
+    out = ""; inS = 0; inD = 0
+    n = length($0)
+    for (i = 1; i <= n; i++) {
+      c = substr($0, i, 1)
+      if (!inD && c == "\047") { inS = !inS; continue }
+      if (!inS && c == "\042") { inD = !inD; continue }
+      if ((inS || inD) && (c == "&" || c == "|" || c == ";" || c == "(" || c == ")")) { out = out "\001"; continue }
+      out = out c
+    }
+    if (match(out, /<<-?[[:space:]]*[A-Za-z_][A-Za-z0-9_]*/)) {
+      tag = substr(out, RSTART, RLENGTH)
+      sub(/^<<-?[[:space:]]*/, "", tag)
+      heredoc = tag
+      sub(/<<-?[[:space:]]*[A-Za-z_][A-Za-z0-9_]*.*$/, "", out)
+    }
+    flushline(out)
+  }
+')
 
 eff="$PWD"
 target=""
@@ -133,7 +190,10 @@ while IFS= read -r seg; do
 
   # STAGE 4: only a manager-led segment can be an install.
   case "$head_tok" in
-    npm|bun|pnpm|yarn|yarnpkg) ;;
+    npm) verbs="$NPM_INSTALL" ;;
+    bun) verbs="$BUN_INSTALL" ;;
+    pnpm) verbs="$PNPM_INSTALL" ;;
+    yarn|yarnpkg) verbs="$YARN_INSTALL" ;;
     *) continue ;;
   esac
   shift
@@ -142,13 +202,14 @@ while IFS= read -r seg; do
   printf '%s' "$seg" | grep -Eq "$GLOBAL" && continue
 
   verdict=""
+  if printf '%s' "$seg" | grep -Eq "$AUDIT_FIX"; then verdict="install"; fi
   prefix_dir=""
   pending_prefix=0
   while [ $# -gt 0 ]; do
     tok="$1"; shift
     case "$tok" in
-      --prefix=*|-C=*) prefix_dir="${tok#*=}"; continue ;;
-      --prefix|-C) pending_prefix=1; continue ;;
+      --prefix=*|-C=*|--cwd=*|--dir=*) prefix_dir="${tok#*=}"; continue ;;
+      --prefix|-C|--cwd|--dir) pending_prefix=1; continue ;;
       -*) continue ;;
     esac
     if [ "$pending_prefix" = "1" ]; then prefix_dir="$tok"; pending_prefix=0; continue; fi
@@ -159,13 +220,19 @@ while IFS= read -r seg; do
     # judged against the primary's own real node_modules and allowed. The FIRST
     # verdict wins; later tokens are only mined for the prefix.
     [ -n "$verdict" ] && continue
-    if printf '%s' "$tok" | grep -Eq "^(${INSTALL_VERBS})$"; then verdict="install"; continue; fi
+    if printf '%s' "$tok" | grep -Eq "^(${verbs})$"; then verdict="install"; continue; fi
     if printf '%s' "$tok" | grep -Eq "^(${SAFE_VERBS})$"; then verdict="safe"; continue; fi
   done
 
   # A bare `yarn` (only flags, no verb) IS an install in yarn classic.
+  # A flags-only `yarn` IS an install in yarn classic, but `yarn --version` and
+  # `yarn --help` only print, so they must not be read as one.
   if [ -z "$verdict" ]; then
-    case "$head_tok" in yarn|yarnpkg) verdict="install" ;; esac
+    case "$head_tok" in
+      yarn|yarnpkg)
+        if printf '%s' "$seg" | grep -Eq '(^|[[:space:]])(--version|-v|-V|--help|-h)([[:space:]]|$)'; then :
+        else verdict="install"; fi ;;
+    esac
   fi
   [ "$verdict" = "install" ] || continue
 

framework-dev.md

@@ -162,9 +162,9 @@ Measured on npm 11.19.0 and bun 1.3.14:
 
 So prevention lives one layer up, and the rest is repair:
 
-- **Block.** `.claude/hooks/block-install-in-linked-worktree.sh` is a `PreToolUse` (Bash) hook, the only layer that sees the state before the package manager starts. It refuses an install verb whose target directory has a symlinked `node_modules`, covering every manager's documented aliases (`bun i` matters most, since Bun writes THROUGH the link) and the REMOVE verbs too, because `npm rm` in a linked worktree deletes from the checkout that owns the tree. Escape hatch `WEBJS_NO_WORKTREE_INSTALL_GATE=1`.
+- **Block.** `.claude/hooks/block-install-in-linked-worktree.sh` is a `PreToolUse` (Bash) hook, the only layer that sees the state before the package manager starts. It refuses an install verb whose target directory has a symlinked `node_modules`, covering every manager's documented aliases (`bun i` matters most, since Bun writes THROUGH the link), the REMOVE verbs, and `link` / `rebuild` / `prune` / `audit fix`, all of which mutate the tree the symlink points at. The tables are per manager, so `bun upgrade`, which upgrades the Bun binary, stays allowed while `pnpm upgrade` does not. Escape hatch `WEBJS_NO_WORKTREE_INSTALL_GATE=1`.
 
-  It judges a COMMAND, never a token. The command is split on `&&`, `||`, `;`, `|`, `(` and `)`, and each segment is judged only by what it STARTS with, after leading env assignments and wrappers like `sudo` are stripped. Matching the manager token anywhere in the line is the obvious shortcut and it is badly wrong: it blocks `git commit -m "fix: npm install ..."`, `grep -rn "npm ci" AGENTS.md` and `git log --grep "npm install"`. A linked worktree is the mandated working state here, so that fires on ordinary commands constantly, and a gate that cries wolf is a gate someone turns off. `npm test`, `npm run <script>`, `npx ...`, `npm init` and `yarn test` all pass, and so does a GLOBAL install (`-g` / `--global`), which writes to the npm prefix rather than through the link and is this repo's documented post-release step.
+  It judges a COMMAND, never a token, in four stages. Quoted spans are neutralised FIRST, keeping their content but stripping the separators inside them, and heredoc bodies are dropped. The remainder is split on `&&`, `||`, `;`, `|`, `(`, `)` and newlines. Each segment is then judged by its FIRST token, after leading env assignments and wrappers like `sudo` are stripped. Only inside a manager-led segment are the remaining tokens scanned, for the first one recognised as either an install verb or a known safe verb, so a flag sitting before the verb does not hide it. Matching the manager token anywhere in the line is the obvious shortcut and it is badly wrong: it blocks `git commit -m "fix: npm install ..."`, `grep -rn "npm ci" AGENTS.md` and `git log --grep "npm install"`. A linked worktree is the mandated working state here, so that fires on ordinary commands constantly, and a gate that cries wolf is a gate someone turns off. `npm test`, `npm run <script>`, `npx ...`, `npm init` and `yarn test` all pass, and so does a GLOBAL install (`-g` / `--global`), which writes to the npm prefix rather than through the link and is this repo's documented post-release step.
 - **Report.** The root `preinstall` runs `scripts/warn-worktree-install.mjs`, which ALWAYS exits 0 and returns immediately unless `.git` is a FILE, so a normal clone and CI never see it. It names whichever of the three states it landed in and prints the repair.
 - **Repoint on teardown.** `.claude/hooks/cleanup-merged-worktree.sh` repoints any `<primary>/node_modules/@webjsdev/*` link targeting a worktree it is about to remove, before removing it.
 - **Repair on demand.** `npm run worktree:link` repairs the primary's `@webjsdev/*` scope: a dangling link, a link into a live foreign checkout, and an absolute in-primary link all become the relative form, and a DANGLING `.name-HASH` npm staging entry is dropped. A LIVE staging entry is left strictly alone. `npm run check:worktree-links` reports without writing and exits non-zero when there is work. Escape hatch `WEBJS_NO_WORKTREE_REPAIR=1` suppresses the repair WRITE only, so `--check` ignores it and still inspects; the `defaultPrimary()` test needs the hatch for the same reason it needs `WEBJS_NO_WORKTREE_SEED=1`: the repair pass sits ABOVE the primary-checkout guard by design, so it runs in both positions and would otherwise rewrite the real checkout during `npm test`.

test/hooks/block-install-in-linked-worktree.test.mjs

@@ -110,7 +110,10 @@ test('blocks the HYPHENATED npm verbs, which the short aliases do not cover', ()
 test('blocks the REMOVE verbs, which delete from the owning checkout', () => {
   const { root, worktree } = makeLinkedPair();
   try {
-    for (const cmd of ['npm uninstall x', 'npm rm x', 'npm r x', 'bun rm x', 'pnpm rm x', 'yarn remove x', 'pnpm upgrade', 'pnpm dedupe', 'yarn dedupe']) {
+    // `npm r` and `npm a` are deliberately NOT in npm's table: they are rare as
+    // commands and common as flag VALUES, and the scan cannot tell the two
+    // apart, so admitting them blocks `npm -w a run build`. A documented gap.
+    for (const cmd of ['npm uninstall x', 'npm rm x', 'npm unlink x', 'bun rm x', 'pnpm rm x', 'yarn remove x', 'pnpm upgrade', 'pnpm dedupe', 'yarn dedupe']) {
       assert.equal(runHook(cmd, worktree).status, 2, `expected block for \`${cmd}\``);
     }
   } finally { rmSync(root, { recursive: true, force: true }); }
@@ -193,7 +196,6 @@ test('an `=` in a FLAG does not disable the gate (fail-open regression)', () =>
       'npm install --workspace=packages/core',
       'bun install --backend=hardlink',
       'yarn add x --registry=https://r',
-      'pnpm add x --dir=/y',
       'npm i -D esbuild --foreground-scripts=true',
     ]) {
       assert.equal(runHook(cmd, worktree).status, 2, `expected block for \`${cmd}\``);
@@ -317,7 +319,7 @@ test('a flag VALUE never hides the verb, and a safe verb still stops the scan',
   } finally { rmSync(root, { recursive: true, force: true }); }
 });
 
-test('follows every `cd` spelling, including ~, --, and pushd', () => {
+test('follows the `cd --`, `cd -P` and `pushd` spellings', () => {
   const { root, worktree } = makeLinkedPair();
   try {
     for (const cmd of [`cd -- ${worktree} && npm ci`, `pushd ${worktree} && npm ci`, `cd -P ${worktree} && npm ci`]) {
@@ -357,3 +359,91 @@ test('escalates to the git toplevel, so an install from a SUBDIRECTORY blocks',
     assert.equal(runHook('npm install', sub).status, 2, 'a subdirectory install still reaches the linked root');
   } finally { rmSync(root, { recursive: true, force: true }); }
 });
+
+test('a QUOTED directory argument survives the quote handling', () => {
+  // Quoted spans must lose their power to look like a command boundary while
+  // KEEPING their content. Deleting the span instead leaves `cd` with no
+  // argument, so the install is judged against the session cwd (the primary,
+  // whose node_modules is real) and the headline scenario fails open. Quoting a
+  // path is the ordinary defensive spelling.
+  const { root, primary, worktree } = makeLinkedPair();
+  try {
+    for (const cmd of [
+      `cd "${worktree}" && npm ci`,
+      `cd '${worktree}' && npm ci`,
+      `cd "${worktree}" && bun install`,
+      `npm --prefix "${worktree}" install`,
+      `npm install --prefix '${worktree}'`,
+    ]) {
+      assert.equal(runHook(cmd, primary).status, 2, `expected block for \`${cmd}\``);
+    }
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('an apostrophe inside a double-quoted string does not swallow a later install', () => {
+  // Running a single-quote pass before a double-quote pass pairs the apostrophe
+  // in `can't` with the next single quote anywhere in the line and deletes
+  // everything between, taking a real install with it.
+  const { root, worktree } = makeLinkedPair();
+  try {
+    assert.equal(runHook(`echo "can't resolve" && npm i -D esbuild`, worktree).status, 2);
+    assert.equal(runHook(`git commit -m "don't ship" && npm ci && echo "it's done"`, worktree).status, 2);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('a heredoc BODY is content, not commands', () => {
+  // This repo's docs are full of `npm install` lines.
+  const { root, worktree } = makeLinkedPair();
+  try {
+    assert.equal(runHook("cat > doc.md <<'EOF'\nnpm install\nEOF", worktree).status, 0);
+    assert.equal(runHook('cat > doc.md <<EOF\nnpm ci\nEOF', worktree).status, 0);
+    // ...but a real newline-separated install still blocks.
+    assert.equal(runHook('echo hi\nnpm ci', worktree).status, 2);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('`npm audit fix` blocks while a bare `npm audit` does not', () => {
+  // `audit fix` installs revised versions straight through the link, which is
+  // the same test `rebuild`, `prune` and `link` pass.
+  const { root, worktree } = makeLinkedPair();
+  try {
+    assert.equal(runHook('npm audit fix', worktree).status, 2);
+    assert.equal(runHook('npm audit fix --force', worktree).status, 2);
+    assert.equal(runHook('npm audit', worktree).status, 0);
+    assert.equal(runHook('npm audit --json', worktree).status, 0);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('the verb tables are PER MANAGER, so one manager alias cannot fire for another', () => {
+  const { root, worktree } = makeLinkedPair();
+  try {
+    // `a` is a BUN alias for add. As an npm flag VALUE it must mean nothing.
+    assert.equal(runHook('npm --workspace a run build', worktree).status, 0);
+    assert.equal(runHook('npm -w a run build', worktree).status, 0);
+    assert.equal(runHook('bun a nanoid', worktree).status, 2, 'but it IS an install for bun');
+    // `bun upgrade` upgrades the Bun BINARY and never touches node_modules.
+    assert.equal(runHook('bun upgrade', worktree).status, 0);
+    assert.equal(runHook('pnpm upgrade', worktree).status, 2, 'while pnpm upgrade DOES install');
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('an informational flags-only yarn is not read as a bare install', () => {
+  const { root, worktree } = makeLinkedPair();
+  try {
+    for (const cmd of ['yarn --version', 'yarn -v', 'yarnpkg --help', 'yarn -h']) {
+      assert.equal(runHook(cmd, worktree).status, 0, `expected allow for \`${cmd}\``);
+    }
+    assert.equal(runHook('yarn', worktree).status, 2, 'a truly bare yarn still installs');
+    assert.equal(runHook('yarn --frozen-lockfile', worktree).status, 2);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('mines --cwd and --dir as target directories, not just --prefix', () => {
+  // Bun is the manager that writes THROUGH the link, so `bun --cwd` matters most.
+  const { root, primary, worktree } = makeLinkedPair();
+  try {
+    assert.equal(runHook(`bun --cwd ${worktree} install`, primary).status, 2);
+    assert.equal(runHook(`pnpm --dir ${worktree} install`, primary).status, 2);
+    assert.equal(runHook(`yarn --cwd ${worktree} install`, primary).status, 2);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});