fix: harden hook portability and plugin docs

scripts/hooks/post-edit-format.js

@@ -13,8 +13,31 @@
 const { execFileSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
+const { getPackageManager } = require('../lib/package-manager');
 
 const MAX_STDIN = 1024 * 1024; // 1MB limit
+const BIOME_CONFIGS = ['biome.json', 'biome.jsonc'];
+const PRETTIER_CONFIGS = [
+  '.prettierrc',
+  '.prettierrc.json',
+  '.prettierrc.json5',
+  '.prettierrc.js',
+  '.prettierrc.cjs',
+  '.prettierrc.mjs',
+  '.prettierrc.ts',
+  '.prettierrc.cts',
+  '.prettierrc.mts',
+  '.prettierrc.yml',
+  '.prettierrc.yaml',
+  '.prettierrc.toml',
+  'prettier.config.js',
+  'prettier.config.cjs',
+  'prettier.config.mjs',
+  'prettier.config.ts',
+  'prettier.config.cts',
+  'prettier.config.mts',
+];
+const PROJECT_ROOT_MARKERS = ['package.json', ...BIOME_CONFIGS, ...PRETTIER_CONFIGS];
 let data = '';
 process.stdin.setEncoding('utf8');
 
@@ -27,46 +50,66 @@ process.stdin.on('data', chunk => {
 
 function findProjectRoot(startDir) {
   let dir = startDir;
-  while (dir !== path.dirname(dir)) {
-    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
-    dir = path.dirname(dir);
+
+  while (true) {
+    if (PROJECT_ROOT_MARKERS.some(marker => fs.existsSync(path.join(dir, marker)))) {
+      return dir;
+    }
+
+    const parentDir = path.dirname(dir);
+    if (parentDir === dir) break;
+    dir = parentDir;
   }
+
   return startDir;
 }
 
 function detectFormatter(projectRoot) {
-  const biomeConfigs = ['biome.json', 'biome.jsonc'];
-  for (const cfg of biomeConfigs) {
+  for (const cfg of BIOME_CONFIGS) {
     if (fs.existsSync(path.join(projectRoot, cfg))) return 'biome';
   }
 
-  const prettierConfigs = [
-    '.prettierrc',
-    '.prettierrc.json',
-    '.prettierrc.js',
-    '.prettierrc.cjs',
-    '.prettierrc.mjs',
-    '.prettierrc.yml',
-    '.prettierrc.yaml',
-    '.prettierrc.toml',
-    'prettier.config.js',
-    'prettier.config.cjs',
-    'prettier.config.mjs',
-  ];
-  for (const cfg of prettierConfigs) {
+  for (const cfg of PRETTIER_CONFIGS) {
     if (fs.existsSync(path.join(projectRoot, cfg))) return 'prettier';
   }
 
   return null;
 }
 
-function getFormatterCommand(formatter, filePath) {
-  const npxBin = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+function getRunnerBin(bin) {
+  if (process.platform !== 'win32') return bin;
+  if (bin === 'npx') return 'npx.cmd';
+  if (bin === 'pnpm') return 'pnpm.cmd';
+  if (bin === 'yarn') return 'yarn.cmd';
+  if (bin === 'bunx') return 'bunx.cmd';
+  return bin;
+}
+
+function getFormatterRunner(projectRoot) {
+  const pm = getPackageManager({ projectDir: projectRoot });
+  const execCmd = pm?.config?.execCmd || 'npx';
+  const [bin = 'npx', ...prefix] = execCmd.split(/\s+/).filter(Boolean);
+
+  return {
+    bin: getRunnerBin(bin),
+    prefix
+  };
+}
+
+function getFormatterCommand(formatter, filePath, projectRoot) {
+  const runner = getFormatterRunner(projectRoot);
+
   if (formatter === 'biome') {
-    return { bin: npxBin, args: ['@biomejs/biome', 'format', '--write', filePath] };
+    return {
+      bin: runner.bin,
+      args: [...runner.prefix, '@biomejs/biome', 'format', '--write', filePath]
+    };
   }
   if (formatter === 'prettier') {
-    return { bin: npxBin, args: ['prettier', '--write', filePath] };
+    return {
+      bin: runner.bin,
+      args: [...runner.prefix, 'prettier', '--write', filePath]
+    };
   }
   return null;
 }
@@ -80,7 +123,7 @@ process.stdin.on('end', () => {
       try {
         const projectRoot = findProjectRoot(path.dirname(path.resolve(filePath)));
         const formatter = detectFormatter(projectRoot);
-        const cmd = getFormatterCommand(formatter, filePath);
+        const cmd = getFormatterCommand(formatter, filePath, projectRoot);
 
         if (cmd) {
           execFileSync(cmd.bin, cmd.args, {

scripts/hooks/pre-bash-dev-server-block.js

@@ -4,6 +4,142 @@
 const MAX_STDIN = 1024 * 1024;
 const { splitShellSegments } = require('../lib/shell-split');
 
+const DEV_COMMAND_WORDS = new Set([
+  'npm',
+  'pnpm',
+  'yarn',
+  'bun',
+  'npx',
+  'bash',
+  'sh',
+  'zsh',
+  'fish',
+  'tmux'
+]);
+const SKIPPABLE_PREFIX_WORDS = new Set(['env', 'command', 'builtin', 'exec', 'noglob', 'sudo']);
+const PREFIX_OPTION_VALUE_WORDS = {
+  env: new Set(['-u', '-C', '-S', '--unset', '--chdir', '--split-string']),
+  sudo: new Set([
+    '-u',
+    '-g',
+    '-h',
+    '-p',
+    '-r',
+    '-t',
+    '-C',
+    '--user',
+    '--group',
+    '--host',
+    '--prompt',
+    '--role',
+    '--type',
+    '--close-from'
+  ])
+};
+
+function readToken(input, startIndex) {
+  let index = startIndex;
+  while (index < input.length && /\s/.test(input[index])) index += 1;
+  if (index >= input.length) return null;
+
+  let token = '';
+  let quote = null;
+
+  while (index < input.length) {
+    const ch = input[index];
+
+    if (quote) {
+      if (ch === quote) {
+        quote = null;
+        index += 1;
+        continue;
+      }
+
+      if (ch === '\\' && quote === '"' && index + 1 < input.length) {
+        token += input[index + 1];
+        index += 2;
+        continue;
+      }
+
+      token += ch;
+      index += 1;
+      continue;
+    }
+
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      index += 1;
+      continue;
+    }
+
+    if (/\s/.test(ch)) break;
+
+    if (ch === '\\' && index + 1 < input.length) {
+      token += input[index + 1];
+      index += 2;
+      continue;
+    }
+
+    token += ch;
+    index += 1;
+  }
+
+  return { token, end: index };
+}
+
+function shouldSkipOptionValue(wrapper, optionToken) {
+  if (!wrapper || !optionToken || optionToken.includes('=')) return false;
+  const optionSet = PREFIX_OPTION_VALUE_WORDS[wrapper];
+  return Boolean(optionSet && optionSet.has(optionToken));
+}
+
+function isOptionToken(token) {
+  return token.startsWith('-') && token.length > 1;
+}
+
+function getLeadingCommandWord(segment) {
+  let index = 0;
+  let activeWrapper = null;
+  let skipNextValue = false;
+
+  while (index < segment.length) {
+    const parsed = readToken(segment, index);
+    if (!parsed) return null;
+    index = parsed.end;
+
+    const token = parsed.token;
+    if (!token) continue;
+
+    if (skipNextValue) {
+      skipNextValue = false;
+      continue;
+    }
+
+    if (token === '--') {
+      activeWrapper = null;
+      continue;
+    }
+
+    if (/^[A-Za-z_][A-Za-z0-9_]*=.*/.test(token)) continue;
+
+    if (SKIPPABLE_PREFIX_WORDS.has(token)) {
+      activeWrapper = token;
+      continue;
+    }
+
+    if (activeWrapper && isOptionToken(token)) {
+      if (shouldSkipOptionValue(activeWrapper, token)) {
+        skipNextValue = true;
+      }
+      continue;
+    }
+
+    return token;
+  }
+
+  return null;
+}
+
 let raw = '';
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', chunk => {
@@ -23,7 +159,13 @@ process.stdin.on('end', () => {
       const tmuxLauncher = /^\s*tmux\s+(new|new-session|new-window|split-window)\b/;
       const devPattern = /\b(npm\s+run\s+dev|pnpm(?:\s+run)?\s+dev|yarn\s+dev|bun\s+run\s+dev)\b/;
 
-      const hasBlockedDev = segments.some(segment => devPattern.test(segment) && !tmuxLauncher.test(segment));
+      const hasBlockedDev = segments.some(segment => {
+        const commandWord = getLeadingCommandWord(segment);
+        if (!commandWord || !DEV_COMMAND_WORDS.has(commandWord)) {
+          return false;
+        }
+        return devPattern.test(segment) && !tmuxLauncher.test(segment);
+      });
 
       if (hasBlockedDev) {
         console.error('[Hook] BLOCKED: Dev server must run in tmux for log access');

scripts/hooks/run-with-flags-shell.sh

@@ -4,6 +4,8 @@ set -euo pipefail
 HOOK_ID="${1:-}"
 REL_SCRIPT_PATH="${2:-}"
 PROFILES_CSV="${3:-standard,strict}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "${SCRIPT_DIR}/../.." && pwd)}"
 
 # Preserve stdin for passthrough or script execution
 INPUT="$(cat)"
@@ -14,13 +16,13 @@ if [[ -z "$HOOK_ID" || -z "$REL_SCRIPT_PATH" ]]; then
 fi
 
 # Ask Node helper if this hook is enabled
-ENABLED="$(node "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/check-hook-enabled.js" "$HOOK_ID" "$PROFILES_CSV" 2>/dev/null || echo yes)"
+ENABLED="$(node "${PLUGIN_ROOT}/scripts/hooks/check-hook-enabled.js" "$HOOK_ID" "$PROFILES_CSV" 2>/dev/null || echo yes)"
 if [[ "$ENABLED" != "yes" ]]; then
   printf '%s' "$INPUT"
   exit 0
 fi
 
-SCRIPT_PATH="${CLAUDE_PLUGIN_ROOT}/${REL_SCRIPT_PATH}"
+SCRIPT_PATH="${PLUGIN_ROOT}/${REL_SCRIPT_PATH}"
 if [[ ! -f "$SCRIPT_PATH" ]]; then
   echo "[Hook] Script not found for ${HOOK_ID}: ${SCRIPT_PATH}" >&2
   printf '%s' "$INPUT"