scc-universal 1.1.0 → 1.2.1

package/scripts/lib/hook-input.js

@@ -0,0 +1,105 @@
+'use strict';
+
+/**
+ * hook-input.js — Normalize hook input across Claude Code and Cursor formats.
+ *
+ * Claude Code and Cursor send different JSON structures for the same logical data:
+ *
+ *   | Data          | Claude Code                    | Cursor                    |
+ *   |---------------|--------------------------------|---------------------------|
+ *   | Shell command | tool_input.command             | command                   |
+ *   | File path     | tool_input.file_path           | file_path                 |
+ *   | Shell output  | tool_output (stringified JSON) | output (raw text)         |
+ *   | File edits    | N/A                            | edits[]                   |
+ *   | Duration      | N/A                            | duration (ms)             |
+ *   | Sandbox       | N/A                            | sandbox (boolean)         |
+ *   | Prompt text   | prompt                         | prompt                    |
+ *   | Tool name     | tool_name                      | tool_name                 |
+ *   | Working dir   | cwd                            | cwd                       |
+ *
+ * This module provides a single normalizeInput() function that merges both
+ * formats into a consistent shape. Scripts import this instead of parsing
+ * raw input directly.
+ */
+
+/**
+ * Normalize hook input from either Claude Code or Cursor format.
+ *
+ * @param {object} raw - The parsed JSON input from stdin
+ * @returns {object} Normalized input with consistent field names
+ */
+function normalizeInput(raw) {
+  if (!raw || typeof raw !== 'object') {
+    return {
+      filePath: '',
+      command: '',
+      toolName: '',
+      cwd: '',
+      output: '',
+      edits: [],
+      duration: 0,
+      sandbox: false,
+      prompt: '',
+      raw: raw || {},
+    };
+  }
+
+  return {
+    // File path: Cursor sends top-level, Claude Code nests under tool_input
+    filePath: raw.file_path || (raw.tool_input && raw.tool_input.file_path) || '',
+
+    // Shell command: Cursor sends top-level, Claude Code nests under tool_input
+    command: raw.command || (raw.tool_input && raw.tool_input.command) || '',
+
+    // Tool name: same field in both harnesses
+    toolName: raw.tool_name || '',
+
+    // Working directory: same field in both harnesses
+    cwd: raw.cwd || '',
+
+    // Shell output: Cursor sends 'output' (string), Claude Code sends 'tool_output'
+    // tool_output can be a string or object { output: '...' }
+    output: raw.output
+      || (typeof raw.tool_output === 'string' ? raw.tool_output : '')
+      || (raw.tool_output && raw.tool_output.output) || '',
+
+    // File edits: Cursor afterFileEdit sends edits[], Claude Code does not
+    edits: raw.edits || [],
+
+    // Duration: Cursor afterShellExecution sends duration (ms)
+    duration: raw.duration || 0,
+
+    // Sandbox: Cursor beforeShellExecution indicates sandboxed commands
+    sandbox: raw.sandbox || false,
+
+    // Prompt text: same field in both harnesses (UserPromptSubmit / beforeSubmitPrompt)
+    prompt: raw.prompt || '',
+
+    // Preserve the full raw input for any hook-specific fields
+    raw,
+  };
+}
+
+/**
+ * Read and parse JSON from stdin, then normalize.
+ * Convenience wrapper used by most hook scripts.
+ *
+ * @returns {Promise<object>} Normalized input
+ */
+function readInput() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => {
+      try {
+        const parsed = JSON.parse(data);
+        resolve(normalizeInput(parsed));
+      } catch {
+        resolve(normalizeInput({}));
+      }
+    });
+  });
+}
+
+module.exports = { normalizeInput, readInput };

package/scripts/lib/hooks-adapter.js

@@ -0,0 +1,265 @@
+'use strict';
+
+/**
+ * hooks-adapter.js — Transforms SCC hooks from Claude Code format to Cursor format.
+ *
+ * Claude Code hooks use:
+ *   - PascalCase event names (PreToolUse, PostToolUse, SessionStart)
+ *   - Nested structure: { matcher, hooks: [{ type, command, async, timeout }] }
+ *   - Regex matchers on tool names
+ *   - ${CLAUDE_PLUGIN_ROOT} path variable
+ *   - run-with-flags.js profile gating wrapper
+ *   - 4 hook types: command, http, prompt, agent
+ *
+ * Cursor hooks use:
+ *   - camelCase event names (preToolUse, beforeShellExecution, afterFileEdit)
+ *   - Flat structure: { command, timeout, matcher, failClosed, loop_limit }
+ *   - Tool-specific events instead of matchers (beforeShellExecution vs PreToolUse+Bash)
+ *   - Relative paths from project root
+ *   - No profile gating
+ *   - 2 hook types: command, prompt
+ *   - version: 1 required
+ */
+
+// ── Event mapping ────────────────────────────────────────────────────────────
+
+/**
+ * Map Claude Code event+matcher → Cursor event.
+ * Some Claude Code events with tool matchers map to Cursor-specific events.
+ */
+const EVENT_MAP = {
+  SessionStart: 'sessionStart',
+  SessionEnd: 'sessionEnd',
+  PreCompact: 'preCompact',
+  Stop: 'stop',
+  PostToolUseFailure: 'postToolUseFailure',
+};
+
+/**
+ * PreToolUse matcher → Cursor event mapping.
+ * Claude Code uses PreToolUse + matcher; Cursor has tool-specific events.
+ */
+const PRE_TOOL_USE_MAP = {
+  Bash: 'beforeShellExecution',
+};
+
+/**
+ * PostToolUse matcher → Cursor event mapping.
+ */
+const POST_TOOL_USE_MAP = {
+  Bash: 'afterShellExecution',
+  Edit: 'afterFileEdit',
+  Write: 'afterFileEdit',
+};
+
+// Cursor hook types (command and prompt only; http and agent are Claude Code only)
+const CURSOR_SUPPORTED_TYPES = new Set(['command', 'prompt']);
+
+// ── Path remapping ───────────────────────────────────────────────────────────
+
+/**
+ * Strip the run-with-flags.js wrapper and extract the actual script command.
+ * Claude Code: node "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js" <id> <profile> "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/<script>.js"
+ * Cursor:      node scripts/hooks/<script>.js
+ *
+ * Also handles run-with-flags-shell.sh for bash hooks.
+ */
+function remapCommand(command) {
+  // Pattern 1: node "...run-with-flags.js" <id> <profile> ".../<script>.js"
+  const runWithFlagsMatch = command.match(
+    /node\s+"?\$\{CLAUDE_PLUGIN_ROOT\}\/scripts\/hooks\/run-with-flags\.js"?\s+\S+\s+\S+\s+"?\$\{CLAUDE_PLUGIN_ROOT\}\/scripts\/hooks\/([^"]+)"?/
+  );
+  if (runWithFlagsMatch) {
+    return `node scripts/hooks/${runWithFlagsMatch[1]}`;
+  }
+
+  // Pattern 2: bash "...run-with-flags-shell.sh" <id> "scripts/hooks/<script>" <profiles>
+  const shellFlagsMatch = command.match(
+    /bash\s+"?\$\{CLAUDE_PLUGIN_ROOT\}\/scripts\/hooks\/run-with-flags-shell\.sh"?\s+\S+\s+"?scripts\/hooks\/([^"]+)"?\s+\S+/
+  );
+  if (shellFlagsMatch) {
+    return `bash scripts/hooks/${shellFlagsMatch[1]}`;
+  }
+
+  // Pattern 3: Direct node "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/<script>.js"
+  const directMatch = command.match(
+    /node\s+"?\$\{CLAUDE_PLUGIN_ROOT\}\/scripts\/hooks\/([^"]+)"?/
+  );
+  if (directMatch) {
+    return `node scripts/hooks/${directMatch[1]}`;
+  }
+
+  // Pattern 4: npx commands (pass through as-is)
+  if (command.startsWith('npx ')) {
+    return command;
+  }
+
+  // Fallback: replace ${CLAUDE_PLUGIN_ROOT}/ with empty
+  return command.replace(/\$\{CLAUDE_PLUGIN_ROOT\}\//g, '');
+}
+
+// ── Security classification ──────────────────────────────────────────────────
+
+/**
+ * Determine if a hook should use failClosed: true in Cursor.
+ * Security-critical hooks should block on failure rather than fail-open.
+ */
+const FAIL_CLOSED_HOOKS = new Set([
+  'mcp-health-check',
+  'block-no-verify',
+]);
+
+function shouldFailClosed(command) {
+  return [...FAIL_CLOSED_HOOKS].some(hook => command.includes(hook));
+}
+
+// ── Core transform ──────────────────────────────────────────────────────────
+
+/**
+ * Resolve the Cursor event name for a Claude Code event + matcher combination.
+ */
+function resolveCursorEvent(claudeEvent, matcher) {
+  // Direct mapping (no tool-specific routing needed)
+  if (EVENT_MAP[claudeEvent]) {
+    return EVENT_MAP[claudeEvent];
+  }
+
+  // PreToolUse: check if matcher maps to a Cursor-specific event
+  if (claudeEvent === 'PreToolUse') {
+    if (matcher && PRE_TOOL_USE_MAP[matcher]) {
+      return PRE_TOOL_USE_MAP[matcher];
+    }
+    return 'preToolUse';
+  }
+
+  // PostToolUse: check if matcher maps to a Cursor-specific event
+  if (claudeEvent === 'PostToolUse') {
+    if (matcher && POST_TOOL_USE_MAP[matcher]) {
+      return POST_TOOL_USE_MAP[matcher];
+    }
+    return 'postToolUse';
+  }
+
+  // Fallback: camelCase the event name
+  return claudeEvent.charAt(0).toLowerCase() + claudeEvent.slice(1);
+}
+
+/**
+ * Transform a single Claude Code hook entry to a Cursor hook entry.
+ * @param {object} hook - Claude Code hook { type, command, async, timeout }
+ * @param {string} groupMatcher - The matcher from the parent group
+ * @param {string} cursorEvent - The resolved Cursor event name
+ * @returns {object|null} - Cursor hook entry, or null if unsupported
+ */
+function transformHookEntry(hook, groupMatcher, cursorEvent) {
+  // Skip unsupported hook types (http, agent)
+  const hookType = hook.type || 'command';
+  if (!CURSOR_SUPPORTED_TYPES.has(hookType)) {
+    return null;
+  }
+
+  const entry = {};
+
+  // Command (required)
+  if (hookType === 'command') {
+    entry.command = remapCommand(hook.command);
+  } else if (hookType === 'prompt') {
+    entry.type = 'prompt';
+    entry.prompt = hook.prompt;
+  }
+
+  // Timeout (if specified)
+  if (hook.timeout) {
+    entry.timeout = hook.timeout;
+  }
+
+  // Note: Claude Code 'async' field is dropped — Cursor does not support it.
+  // Claude Code 'if' field is dropped — Cursor uses matcher against command text instead.
+  // Claude Code 'statusMessage' is dropped — Cursor does not support it.
+
+  // failClosed for security-critical hooks
+  if (hookType === 'command' && shouldFailClosed(hook.command)) {
+    entry.failClosed = true;
+  }
+
+  // Matcher: only add if the Cursor event supports it AND the Claude Code
+  // matcher wasn't already consumed by event routing (Bash → beforeShellExecution)
+  const toolSpecificEvents = new Set([
+    'beforeShellExecution', 'afterShellExecution',
+    'afterFileEdit',
+  ]);
+
+  if (groupMatcher && !toolSpecificEvents.has(cursorEvent)) {
+    // For preToolUse/postToolUse, the matcher maps to Cursor's tool type format
+    // Claude Code uses "Edit|Write", Cursor uses "Write" (tool names)
+    const cursorMatcher = mapMatcherToCursor(groupMatcher);
+    if (cursorMatcher) {
+      entry.matcher = cursorMatcher;
+    }
+  }
+
+  // For beforeShellExecution, pass through the original matcher as command filter
+  if (cursorEvent === 'beforeShellExecution' && groupMatcher && groupMatcher !== 'Bash') {
+    entry.matcher = groupMatcher;
+  }
+
+  // loop_limit for stop hooks (Cursor default is 5, Claude Code default is null/unlimited)
+  if (cursorEvent === 'stop') {
+    entry.loop_limit = 3;
+  }
+
+  return entry;
+}
+
+/**
+ * Map Claude Code regex matcher to Cursor tool matcher format.
+ * Cursor matchers: Shell, Read, Write, Grep, Delete, Task, MCP:<tool>
+ */
+function mapMatcherToCursor(claudeMatcher) {
+  if (!claudeMatcher || claudeMatcher === '') return null;
+
+  const mappings = {
+    Bash: 'Shell',
+    'Edit|Write': 'Write',
+    Edit: 'Write',
+    Write: 'Write',
+  };
+
+  return mappings[claudeMatcher] || claudeMatcher;
+}
+
+/**
+ * Transform Claude Code hooks.json to Cursor hooks.json format.
+ * @param {object} claudeHooks - Parsed Claude Code hooks.json
+ * @returns {object} - Cursor-format hooks.json
+ */
+function transformHooks(claudeHooks) {
+  const cursorHooks = {};
+  const sourceHooks = claudeHooks.hooks || {};
+
+  for (const [claudeEvent, groups] of Object.entries(sourceHooks)) {
+    for (const group of groups) {
+      const matcher = group.matcher || '';
+      const cursorEvent = resolveCursorEvent(claudeEvent, matcher);
+
+      if (!cursorHooks[cursorEvent]) {
+        cursorHooks[cursorEvent] = [];
+      }
+
+      const hooks = group.hooks || [];
+      for (const hook of hooks) {
+        const entry = transformHookEntry(hook, matcher, cursorEvent);
+        if (entry) {
+          cursorHooks[cursorEvent].push(entry);
+        }
+      }
+    }
+  }
+
+  return {
+    version: 1,
+    hooks: cursorHooks,
+  };
+}
+
+module.exports = { transformHooks, remapCommand, resolveCursorEvent, transformHookEntry };

package/scripts/lib/install-executor.js

@@ -14,6 +14,7 @@ const { copyFile, readJson, fileExists, simpleHash } = require('./utils');
 const { saveState } = require('./state-store');
 const { transformSkillDir } = require('./skill-adapter');
 const { transformAgentFile } = require('./agent-adapter');
+const { transformHooks } = require('./hooks-adapter');
 
 const VALID_TARGETS = ['claude', 'cursor'];
 const VALID_PROFILES = ['apex', 'lwc', 'full'];
@@ -31,13 +32,14 @@ function getTargetDirs(target, projectRoot) {
         skills: path.join(projectRoot, '.claude', 'skills'),
         commands: path.join(projectRoot, '.claude', 'commands'),
         hooks: path.join(projectRoot, '.claude', 'hooks'),
+        settings: path.join(projectRoot, '.claude', 'settings.json'),
       };
     case 'cursor':
       return {
         agents: path.join(projectRoot, '.cursor', 'agents'),
         skills: path.join(projectRoot, '.cursor', 'skills'),
         commands: path.join(projectRoot, '.cursor', 'commands'),
-        hooks: null,
+        hooks: path.join(projectRoot, '.cursor', 'hooks.json'),
       };
     default:
       throw new Error(`Unknown target: ${target}`);
@@ -197,6 +199,160 @@ function installPaths(pathsList, destDir, pluginRoot, moduleName, dryRun, target
   return installed;
 }
 
+/**
+ * Remap hook commands from plugin paths to project-local paths.
+ * ${CLAUDE_PLUGIN_ROOT}/scripts/hooks/foo.js → "$CLAUDE_PROJECT_DIR"/.claude/hooks/foo.js
+ */
+function remapHookCommandForProject(command) {
+  // Strip run-with-flags wrapper and extract the actual script
+  const runWithFlagsMatch = command.match(
+    /node\s+"?\$\{CLAUDE_PLUGIN_ROOT\}\/scripts\/hooks\/run-with-flags\.js"?\s+\S+\s+\S+\s+"?\$\{CLAUDE_PLUGIN_ROOT\}\/scripts\/hooks\/([^"]+)"?/
+  );
+  if (runWithFlagsMatch) {
+    return `node "$CLAUDE_PROJECT_DIR"/.claude/hooks/${runWithFlagsMatch[1]}`;
+  }
+
+  // Shell flags wrapper
+  const shellFlagsMatch = command.match(
+    /bash\s+"?\$\{CLAUDE_PLUGIN_ROOT\}\/scripts\/hooks\/run-with-flags-shell\.sh"?\s+\S+\s+"?scripts\/hooks\/([^"]+)"?\s+\S+/
+  );
+  if (shellFlagsMatch) {
+    return `bash "$CLAUDE_PROJECT_DIR"/.claude/hooks/${shellFlagsMatch[1]}`;
+  }
+
+  // Direct script reference
+  const directMatch = command.match(
+    /node\s+"?\$\{CLAUDE_PLUGIN_ROOT\}\/scripts\/hooks\/([^"]+)"?/
+  );
+  if (directMatch) {
+    return `node "$CLAUDE_PROJECT_DIR"/.claude/hooks/${directMatch[1]}`;
+  }
+
+  // npx commands pass through
+  if (command.startsWith('npx ')) {
+    return command;
+  }
+
+  return command.replace(/\$\{CLAUDE_PLUGIN_ROOT\}\/scripts\/hooks\//g, '"$CLAUDE_PROJECT_DIR"/.claude/hooks/');
+}
+
+/**
+ * Install hooks by merging into .claude/settings.json (Claude Code target)
+ * or generating .cursor/hooks.json (Cursor target).
+ *
+ * Claude Code reads hooks from settings.json, NOT from a separate hooks.json.
+ * The hooks/hooks.json format is only for plugins.
+ */
+function installHooks(group, pluginRoot, targetName, projectRoot, moduleName, dryRun) {
+  const installed = [];
+  const hooksSourcePath = path.join(pluginRoot, group.hooksSource || 'hooks/hooks.json');
+
+  if (!fileExists(hooksSourcePath)) {
+    console.warn(`  [WARN] Hooks source not found: ${hooksSourcePath}`);
+    return installed;
+  }
+
+  // Step 1: Copy hook scripts to target directory
+  const destRelative = (group.targets || {})[targetName];
+  if (destRelative) {
+    const destDir = path.join(projectRoot, destRelative);
+    installed.push(...installPaths(group.paths || [], destDir, pluginRoot, moduleName, dryRun, targetName));
+  }
+
+  // Step 2: For Claude Code target, merge hooks into .claude/settings.json
+  if (targetName === 'claude') {
+    const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+    const hooksJson = readJson(hooksSourcePath);
+
+    if (!hooksJson || !hooksJson.hooks) {
+      console.warn('  [WARN] No hooks found in hooks source');
+      return installed;
+    }
+
+    // Remap all hook commands from plugin paths to project-local paths
+    const remappedHooks = {};
+    for (const [event, groups] of Object.entries(hooksJson.hooks)) {
+      remappedHooks[event] = groups.map(g => ({
+        ...g,
+        hooks: (g.hooks || []).map(h => ({
+          ...h,
+          command: h.command ? remapHookCommandForProject(h.command) : h.command,
+        })),
+      }));
+    }
+
+    if (dryRun) {
+      const hookCount = Object.values(remappedHooks).reduce((sum, arr) => sum + arr.length, 0);
+      console.log(`  [dry-run] Would merge ${hookCount} hook groups into .claude/settings.json`);
+    } else {
+      // Read existing settings or create new
+      let settings = {};
+      if (fileExists(settingsPath)) {
+        settings = readJson(settingsPath) || {};
+      }
+
+      // Merge hooks (SCC hooks replace any existing SCC hooks)
+      settings.hooks = remappedHooks;
+
+      // Write settings.json
+      const settingsDir = path.dirname(settingsPath);
+      if (!fs.existsSync(settingsDir)) {
+        fs.mkdirSync(settingsDir, { recursive: true });
+      }
+      fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+      console.log(`  [OK] Merged hooks into .claude/settings.json`);
+    }
+
+    installed.push({
+      destPath: settingsPath,
+      srcPath: hooksSourcePath,
+      module: moduleName,
+      hash: simpleHash(hooksSourcePath),
+    });
+  }
+
+  // Step 3: For Cursor target, generate .cursor/hooks.json via adapter
+  if (targetName === 'cursor') {
+    const hooksJson = readJson(hooksSourcePath);
+    if (hooksJson) {
+      const cursorHooksPath = path.join(projectRoot, '.cursor', 'hooks.json');
+      const cursorHooks = transformHooks(hooksJson);
+
+      // Remap adapter paths from scripts/hooks/ to .cursor/hooks/
+      // (adapter outputs plugin-relative paths, but install copies to .cursor/hooks/)
+      for (const hooks of Object.values(cursorHooks.hooks)) {
+        for (const hook of hooks) {
+          if (hook.command) {
+            hook.command = hook.command.replace(/\bnode scripts\/hooks\//g, 'node "$CURSOR_PROJECT_DIR"/.cursor/hooks/');
+            hook.command = hook.command.replace(/\bbash scripts\/hooks\//g, 'bash "$CURSOR_PROJECT_DIR"/.cursor/hooks/');
+          }
+        }
+      }
+
+      if (dryRun) {
+        const hookCount = Object.values(cursorHooks.hooks).reduce((sum, arr) => sum + arr.length, 0);
+        console.log(`  [dry-run] Would generate .cursor/hooks.json (${hookCount} hooks)`);
+      } else {
+        const destDir = path.dirname(cursorHooksPath);
+        if (!fs.existsSync(destDir)) {
+          fs.mkdirSync(destDir, { recursive: true });
+        }
+        fs.writeFileSync(cursorHooksPath, JSON.stringify(cursorHooks, null, 2) + '\n', 'utf8');
+        console.log(`  [OK] Generated .cursor/hooks.json`);
+      }
+
+      installed.push({
+        destPath: cursorHooksPath,
+        srcPath: hooksSourcePath,
+        module: moduleName,
+        hash: simpleHash(hooksSourcePath),
+      });
+    }
+  }
+
+  return installed;
+}
+
 /**
  * Install files for a single module definition.
  * Supports two formats:
@@ -218,6 +374,13 @@ function installModule(moduleDef, moduleName, pluginRoot, targetName, projectRoo
     let hasAnyTarget = false;
 
     for (const group of moduleDef.pathGroups) {
+      // Special handling for hooks install type
+      if (group.installType === 'hooks') {
+        hasAnyTarget = true;
+        installed.push(...installHooks(group, pluginRoot, targetName, projectRoot, moduleName, dryRun));
+        continue;
+      }
+
       const destRelative = (group.targets || {})[targetName];
       if (!destRelative) continue;
       hasAnyTarget = true;

package/scripts/scc.js

@@ -23,14 +23,14 @@ function showHelp(exitCode = 0) {
 SCC — Salesforce Claude Code CLI
 
 Usage:
-  scc <command> [args...]
-  scc [install args...]
+  scc-universal <command> [args...]
+  scc-universal [install args...]
 
 Commands:
 ${PRIMARY_COMMANDS.map(cmd => `  ${cmd.padEnd(18)} ${COMMANDS[cmd].description}`).join('\n')}
 
 Compatibility:
-  scc [args...]      Without a command, args are routed to "install"
+  scc-universal [args...]      Without a command, args are routed to "install"
   scc help <command> Show help for a specific command
 
 Install targets:
@@ -44,17 +44,17 @@ Install profiles:
   --profile full       Complete suite — all 7 bundles (default)
 
 Examples:
-  scc apex
-  scc all
-  scc install --config scc-install.json
-  scc install --profile apex --target claude
-  scc plan --config scc-install.json --target cursor
-  scc doctor
-  scc repair --dry-run
-  scc status --json
-  scc sessions
-  scc session-inspect claude:latest
-  scc uninstall --dry-run
+  scc-universal apex
+  scc-universal all
+  scc-universal install --config scc-install.json
+  scc-universal install --profile apex --target claude
+  scc-universal plan --config scc-install.json --target cursor
+  scc-universal doctor
+  scc-universal repair --dry-run
+  scc-universal status --json
+  scc-universal sessions
+  scc-universal session-inspect claude:latest
+  scc-universal uninstall --dry-run
 
 Environment:
   SCC_HOOK_PROFILE    Hook profile: minimal | standard | strict