aw-ecc 1.4.21

package/scripts/lib/aw-harness-registry.js

@@ -0,0 +1,122 @@
+/**
+ * Unified harness registry for aw-ecc hook generators.
+ *
+ * Replaces the pattern of importing from three separate *-hook-config.js and
+ * *-aw-hook-files.js modules when generating hook outputs. Each harness entry
+ * exposes the same interface so the unified generator (Phase 3) can iterate
+ * over all harnesses without per-harness branches.
+ *
+ * The underlying per-harness modules (claude-hook-config, codex-hook-config,
+ * cursor-hook-config, claude-aw-hook-files, codex-aw-hook-files,
+ * cursor-aw-hook-files) are still used by the install system — do not delete
+ * them.
+ */
+
+const {
+  getClaudeAwHomeSourceRelativeDir,
+} = require('./claude-aw-hook-files');
+const { serializeClaudeHookConfig } = require('./claude-hook-config');
+
+const {
+  CODEX_AW_HOOK_FILES,
+  getCodexAwHomeSourceRelativeDir,
+  getCodexAwHookConfigSourceRelativePath,
+  getCodexAwHookSourceRelativeDir,
+} = require('./codex-aw-hook-files');
+const { serializeCodexHookConfig } = require('./codex-hook-config');
+
+const {
+  CURSOR_AW_HOOK_FILES,
+  CURSOR_AW_SHARED_HOOK_FILES,
+  getCursorAwHomeSourceRelativeDir,
+  getCursorAwHookSourceRelativeDir,
+  getCursorAwSharedHookSourceRelativeDir,
+} = require('./cursor-aw-hook-files');
+const { serializeCursorHookConfig } = require('./cursor-hook-config');
+
+const { getClaudePhaseNames, getCodexPhaseNames, getCursorMappedEventNames } = require('./aw-hook-contract');
+
+/**
+ * Registry of all supported harnesses.
+ * Each entry fully describes how to generate that harness's hook outputs.
+ *
+ * @type {Record<string, import('./aw-harness-registry').HarnessConfig>}
+ */
+const HARNESS_REGISTRY = Object.freeze({
+  claude: {
+    name: 'claude',
+    getHomeSourceDir: getClaudeAwHomeSourceRelativeDir,
+    getHooksConfigSourceRelativePath: () => {
+      const path = require('path');
+      return path.join(getClaudeAwHomeSourceRelativeDir(), 'hooks.json');
+    },
+    /** hook files to copy: none for claude (only a JSON config) */
+    hookFiles: [],
+    sharedHookFiles: [],
+    getHookSourceDir: null,
+    getSharedHookSourceDir: null,
+    getOutputDir: null,
+    getOutputSharedDir: null,
+    serialize: (repoRoot) => serializeClaudeHookConfig({ repoRoot }),
+    getPhaseNames: getClaudePhaseNames,
+  },
+  codex: {
+    name: 'codex',
+    getHomeSourceDir: getCodexAwHomeSourceRelativeDir,
+    getHooksConfigSourceRelativePath: getCodexAwHookConfigSourceRelativePath,
+    hookFiles: CODEX_AW_HOOK_FILES,
+    sharedHookFiles: [],
+    getHookSourceDir: getCodexAwHookSourceRelativeDir,
+    getSharedHookSourceDir: null,
+    getOutputDir: () => '.codex/hooks',
+    getOutputSharedDir: null,
+    serialize: () => serializeCodexHookConfig(),
+    getPhaseNames: getCodexPhaseNames,
+  },
+  cursor: {
+    name: 'cursor',
+    getHomeSourceDir: getCursorAwHomeSourceRelativeDir,
+    getHooksConfigSourceRelativePath: () => {
+      const path = require('path');
+      return path.join(getCursorAwHomeSourceRelativeDir(), 'hooks.json');
+    },
+    hookFiles: CURSOR_AW_HOOK_FILES,
+    sharedHookFiles: CURSOR_AW_SHARED_HOOK_FILES,
+    getHookSourceDir: getCursorAwHookSourceRelativeDir,
+    getSharedHookSourceDir: getCursorAwSharedHookSourceRelativeDir,
+    getOutputDir: () => '.cursor/hooks',
+    getOutputSharedDir: () => '.cursor/hooks/shared',
+    serialize: () => serializeCursorHookConfig(),
+    getPhaseNames: getCursorMappedEventNames,
+  },
+});
+
+/**
+ * Returns the registry config for a given harness name.
+ * Throws if the harness is unknown.
+ *
+ * @param {string} harness - one of 'claude', 'codex', 'cursor'
+ * @returns {object}
+ */
+function getHarnessConfig(harness) {
+  const config = HARNESS_REGISTRY[harness];
+  if (!config) {
+    throw new Error(`Unknown harness: '${harness}'. Expected one of: ${Object.keys(HARNESS_REGISTRY).join(', ')}`);
+  }
+  return config;
+}
+
+/**
+ * Returns the ordered list of supported harness names.
+ *
+ * @returns {string[]}
+ */
+function getSupportedHarnesses() {
+  return Object.keys(HARNESS_REGISTRY);
+}
+
+module.exports = {
+  HARNESS_REGISTRY,
+  getHarnessConfig,
+  getSupportedHarnesses,
+};

package/scripts/lib/aw-hook-contract.js

@@ -0,0 +1,86 @@
+/**
+ * Shared AW hook lifecycle contract for aw-ecc-managed harnesses.
+ *
+ * This keeps Claude, Codex, and Cursor aligned on the same semantic phases
+ * even when each harness maps them to different native event names.
+ */
+
+const AW_HOOK_PHASES = [
+  {
+    phase: 'SessionStart',
+    tier: 'core',
+    claudeEvent: 'SessionStart',
+    codexEvent: 'SessionStart',
+    cursorEvents: ['sessionStart'],
+  },
+  {
+    phase: 'UserPromptSubmit',
+    tier: 'core',
+    claudeEvent: 'UserPromptSubmit',
+    codexEvent: 'UserPromptSubmit',
+    cursorEvents: ['beforeSubmitPrompt'],
+  },
+  {
+    phase: 'PreToolUse',
+    tier: 'core',
+    claudeEvent: 'PreToolUse',
+    codexEvent: 'PreToolUse',
+    cursorEvents: ['beforeShellExecution', 'beforeMCPExecution'],
+  },
+  {
+    phase: 'PostToolUse',
+    tier: 'core',
+    claudeEvent: 'PostToolUse',
+    codexEvent: 'PostToolUse',
+    cursorEvents: ['afterShellExecution', 'afterFileEdit', 'afterMCPExecution'],
+  },
+  {
+    phase: 'Stop',
+    tier: 'core',
+    claudeEvent: 'Stop',
+    codexEvent: 'Stop',
+    cursorEvents: ['stop'],
+  },
+  {
+    phase: 'SessionEnd',
+    tier: 'extended',
+    claudeEvent: 'SessionEnd',
+    codexEvent: null,
+    cursorEvents: ['sessionEnd'],
+  },
+  {
+    phase: 'PostToolUseFailure',
+    tier: 'extended',
+    claudeEvent: 'PostToolUseFailure',
+    codexEvent: null,
+    cursorEvents: [],
+  },
+  {
+    phase: 'PreCompact',
+    tier: 'extended',
+    claudeEvent: 'PreCompact',
+    codexEvent: null,
+    cursorEvents: ['preCompact'],
+  },
+];
+
+function getClaudePhaseNames() {
+  return AW_HOOK_PHASES.map((phase) => phase.claudeEvent);
+}
+
+function getCursorMappedEventNames() {
+  return [...new Set(AW_HOOK_PHASES.flatMap((phase) => phase.cursorEvents || []))];
+}
+
+function getCodexPhaseNames() {
+  return AW_HOOK_PHASES
+    .map((phase) => phase.codexEvent)
+    .filter(Boolean);
+}
+
+module.exports = {
+  AW_HOOK_PHASES,
+  getClaudePhaseNames,
+  getCodexPhaseNames,
+  getCursorMappedEventNames,
+};

package/scripts/lib/claude-aw-hook-files.js

@@ -0,0 +1,28 @@
+const path = require('path');
+
+const GENERATED_CLAUDE_AW_HOOK_CONFIG_SUFFIXES = Object.freeze([
+  '/hooks/hooks.json',
+]);
+
+function buildGeneratedClaudeAwHookSourceSuffixes() {
+  return [...GENERATED_CLAUDE_AW_HOOK_CONFIG_SUFFIXES];
+}
+
+function getClaudeAwHomeSourceRelativeDir() {
+  return path.join('scripts', 'claude-aw-home');
+}
+
+function getClaudeAwHookBaseSourceRelativePath() {
+  return path.join(getClaudeAwHomeSourceRelativeDir(), 'hooks.base.json');
+}
+
+function getClaudeAwHookConfigSourceRelativePath() {
+  return path.join(getClaudeAwHomeSourceRelativeDir(), 'hooks.json');
+}
+
+module.exports = {
+  buildGeneratedClaudeAwHookSourceSuffixes,
+  getClaudeAwHomeSourceRelativeDir,
+  getClaudeAwHookBaseSourceRelativePath,
+  getClaudeAwHookConfigSourceRelativePath,
+};

package/scripts/lib/claude-hook-config.js

@@ -0,0 +1,76 @@
+const fs = require('fs');
+const path = require('path');
+
+const { getClaudePhaseNames } = require('./aw-hook-contract');
+const {
+  getClaudeAwHookBaseSourceRelativePath,
+} = require('./claude-aw-hook-files');
+
+const DEFAULT_SCHEMA = 'https://json.schemastore.org/claude-code-settings.json';
+const GENERATED_AW_HOOKS = Object.freeze({
+  SessionStart: [
+    {
+      matcher: 'startup|clear|compact',
+      hooks: [
+        {
+          type: 'command',
+          command: 'bash -lc \'exec bash "${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}/hooks/session-start"\'',
+        },
+      ],
+      description: 'Load AW routing context at session start',
+    },
+  ],
+  UserPromptSubmit: [
+    {
+      hooks: [
+        {
+          type: 'command',
+          command: 'bash -lc \'exec bash "${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}/scripts/hooks/session-start-rules-context.sh"\'',
+        },
+      ],
+      description: 'Inject compact AW routing and rule reminders on each prompt',
+    },
+  ],
+});
+
+function cloneJson(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function readClaudeHookBase(repoRoot = path.join(__dirname, '../..')) {
+  const sourcePath = path.join(repoRoot, getClaudeAwHookBaseSourceRelativePath());
+  return JSON.parse(fs.readFileSync(sourcePath, 'utf8'));
+}
+
+function buildClaudeHookConfig(options = {}) {
+  const baseConfig = readClaudeHookBase(options.repoRoot);
+  const hooks = cloneJson(baseConfig.hooks || {});
+
+  for (const [eventName, entries] of Object.entries(GENERATED_AW_HOOKS)) {
+    hooks[eventName] = cloneJson(entries);
+  }
+
+  const config = {
+    $schema: baseConfig.$schema || DEFAULT_SCHEMA,
+    hooks,
+  };
+
+  for (const phaseName of getClaudePhaseNames()) {
+    if (!Array.isArray(config.hooks[phaseName]) || config.hooks[phaseName].length === 0) {
+      throw new Error(`Claude hook config is missing required AW phase '${phaseName}'`);
+    }
+  }
+
+  return config;
+}
+
+function serializeClaudeHookConfig(options = {}) {
+  return `${JSON.stringify(buildClaudeHookConfig(options), null, 2)}\n`;
+}
+
+module.exports = {
+  GENERATED_AW_HOOKS,
+  buildClaudeHookConfig,
+  readClaudeHookBase,
+  serializeClaudeHookConfig,
+};

package/scripts/lib/codex-aw-hook-files.js

@@ -0,0 +1,38 @@
+const path = require('path');
+
+const CODEX_AW_HOOK_FILES = Object.freeze([
+  'aw-post-tool-use.sh',
+  'aw-pre-tool-use.sh',
+  'aw-session-start.sh',
+  'aw-stop.sh',
+  'aw-user-prompt-submit.sh',
+]);
+
+function buildGeneratedCodexAwHookSourceSuffixes() {
+  return [
+    '/.codex/hooks.json',
+    ...CODEX_AW_HOOK_FILES.map(fileName => (
+      `/.codex/hooks/${String(fileName).replace(/\\/g, '/')}`
+    )),
+  ];
+}
+
+function getCodexAwHomeSourceRelativeDir() {
+  return path.join('scripts', 'codex-aw-home');
+}
+
+function getCodexAwHookSourceRelativeDir() {
+  return path.join(getCodexAwHomeSourceRelativeDir(), 'hooks');
+}
+
+function getCodexAwHookConfigSourceRelativePath() {
+  return path.join(getCodexAwHomeSourceRelativeDir(), 'hooks.json');
+}
+
+module.exports = {
+  CODEX_AW_HOOK_FILES,
+  buildGeneratedCodexAwHookSourceSuffixes,
+  getCodexAwHomeSourceRelativeDir,
+  getCodexAwHookConfigSourceRelativePath,
+  getCodexAwHookSourceRelativeDir,
+};

package/scripts/lib/codex-hook-config.js

@@ -0,0 +1,88 @@
+const { getCodexPhaseNames } = require('./aw-hook-contract');
+
+const GENERATED_AW_HOOKS = Object.freeze({
+  SessionStart: [
+    {
+      matcher: '*',
+      hooks: [
+        {
+          type: 'command',
+          command: 'bash -lc \'bash "$HOME/.codex/hooks/aw-session-start.sh"\'',
+        },
+      ],
+      description: 'Load AW routing context at session start',
+    },
+  ],
+  UserPromptSubmit: [
+    {
+      hooks: [
+        {
+          type: 'command',
+          command: 'bash -lc \'bash "$HOME/.codex/hooks/aw-user-prompt-submit.sh"\'',
+        },
+      ],
+      description: 'Inject compact AW routing and rule reminders on each prompt',
+    },
+  ],
+  PreToolUse: [
+    {
+      matcher: '*',
+      hooks: [
+        {
+          type: 'command',
+          command: 'bash -lc \'bash "$HOME/.codex/hooks/aw-pre-tool-use.sh"\'',
+        },
+      ],
+      description: 'Reserved AW pre-tool-use phase for Codex home installs',
+    },
+  ],
+  PostToolUse: [
+    {
+      matcher: '*',
+      hooks: [
+        {
+          type: 'command',
+          command: 'bash -lc \'bash "$HOME/.codex/hooks/aw-post-tool-use.sh"\'',
+        },
+      ],
+      description: 'Reserved AW post-tool-use phase for Codex home installs',
+    },
+  ],
+  Stop: [
+    {
+      hooks: [
+        {
+          type: 'command',
+          command: 'bash -lc \'bash "$HOME/.codex/hooks/aw-stop.sh"\'',
+        },
+      ],
+      description: 'Reserved AW stop phase for Codex home installs',
+    },
+  ],
+});
+
+function cloneJson(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function buildCodexHookConfig() {
+  const hooks = cloneJson(GENERATED_AW_HOOKS);
+
+  for (const phaseName of getCodexPhaseNames()) {
+    if (!Array.isArray(hooks[phaseName]) || hooks[phaseName].length === 0) {
+      throw new Error(`Codex hook config is missing required AW phase '${phaseName}'`);
+    }
+  }
+
+  return { hooks };
+}
+
+function serializeCodexHookConfig() {
+  return `${JSON.stringify(buildCodexHookConfig(), null, 2)}\n`;
+}
+
+module.exports = {
+  GENERATED_AW_HOOKS,
+  buildCodexHookConfig,
+  serializeCodexHookConfig,
+};

package/scripts/lib/cursor-aw-hook-files.js

@@ -0,0 +1,62 @@
+const path = require('path');
+
+const CURSOR_AW_HOOK_FILES = Object.freeze([
+  'adapter.js',
+  'after-file-edit.js',
+  'after-mcp-execution.js',
+  'after-shell-execution.js',
+  'aw-phase-adapter.js',
+  'before-mcp-execution.js',
+  'before-shell-execution.js',
+  'before-submit-prompt.js',
+  'pre-compact.js',
+  'session-end.js',
+  'session-start.js',
+  'stop.js',
+]);
+
+const CURSOR_AW_SHARED_HOOK_FILES = Object.freeze([
+  'aw-phase-definitions.js',
+  'aw-phase-runner.js',
+  'session-start.sh',
+  'user-prompt-submit.sh',
+]);
+
+function buildGeneratedCursorAwHookSourceSuffixes() {
+  return CURSOR_AW_HOOK_FILES.map(fileName => (
+    `/.cursor/hooks/${String(fileName).replace(/\\/g, '/')}`
+  ));
+}
+
+function buildGeneratedCursorAwSharedHookSourceSuffixes() {
+  return CURSOR_AW_SHARED_HOOK_FILES.map(fileName => (
+    `/.cursor/hooks/shared/${String(fileName).replace(/\\/g, '/')}`
+  ));
+}
+
+function getCursorAwHookSourceRelativeDir() {
+  return path.join('scripts', 'cursor-aw-hooks');
+}
+
+function getCursorAwSharedHookSourceRelativeDir() {
+  return path.join('scripts', 'hooks', 'shared');
+}
+
+function getCursorAwHomeSourceRelativeDir() {
+  return path.join('scripts', 'cursor-aw-home');
+}
+
+function getCursorAwHookConfigSourceRelativePath() {
+  return path.join(getCursorAwHomeSourceRelativeDir(), 'hooks.json');
+}
+
+module.exports = {
+  CURSOR_AW_HOOK_FILES,
+  CURSOR_AW_SHARED_HOOK_FILES,
+  buildGeneratedCursorAwHookSourceSuffixes,
+  buildGeneratedCursorAwSharedHookSourceSuffixes,
+  getCursorAwHomeSourceRelativeDir,
+  getCursorAwHookConfigSourceRelativePath,
+  getCursorAwHookSourceRelativeDir,
+  getCursorAwSharedHookSourceRelativeDir,
+};

package/scripts/lib/cursor-hook-config.js

@@ -0,0 +1,148 @@
+const { getCursorMappedEventNames } = require('./aw-hook-contract');
+
+const CURSOR_HOOK_ENTRIES = Object.freeze({
+  sessionStart: [
+    {
+      command: 'node .cursor/hooks/session-start.js',
+      event: 'sessionStart',
+      description: 'Load previous context and detect environment',
+    },
+  ],
+  sessionEnd: [
+    {
+      command: 'node .cursor/hooks/session-end.js',
+      event: 'sessionEnd',
+      description: 'Persist session state and evaluate patterns',
+    },
+  ],
+  beforeShellExecution: [
+    {
+      command: 'npx block-no-verify@1.1.2',
+      event: 'beforeShellExecution',
+      description: 'Block git hook-bypass flag to protect pre-commit, commit-msg, and pre-push hooks from being skipped',
+    },
+    {
+      command: 'node .cursor/hooks/before-shell-execution.js',
+      event: 'beforeShellExecution',
+      description: 'Tmux dev server blocker, tmux reminder, git push review',
+    },
+  ],
+  afterShellExecution: [
+    {
+      command: 'node .cursor/hooks/after-shell-execution.js',
+      event: 'afterShellExecution',
+      description: 'PR URL logging, build analysis',
+    },
+  ],
+  afterFileEdit: [
+    {
+      command: 'node .cursor/hooks/after-file-edit.js',
+      event: 'afterFileEdit',
+      description: 'Auto-format, TypeScript check, console.log warning',
+    },
+  ],
+  beforeMCPExecution: [
+    {
+      command: 'node .cursor/hooks/before-mcp-execution.js',
+      event: 'beforeMCPExecution',
+      description: 'MCP audit logging and untrusted server warning',
+    },
+  ],
+  afterMCPExecution: [
+    {
+      command: 'node .cursor/hooks/after-mcp-execution.js',
+      event: 'afterMCPExecution',
+      description: 'MCP result logging',
+    },
+  ],
+  beforeReadFile: [
+    {
+      command: 'node .cursor/hooks/before-read-file.js',
+      event: 'beforeReadFile',
+      description: 'Warn when reading sensitive files (.env, .key, .pem)',
+    },
+  ],
+  beforeSubmitPrompt: [
+    {
+      command: 'node .cursor/hooks/before-submit-prompt.js',
+      event: 'beforeSubmitPrompt',
+      description: 'Detect secrets in prompts (sk-, ghp_, AKIA patterns)',
+    },
+  ],
+  subagentStart: [
+    {
+      command: 'node .cursor/hooks/subagent-start.js',
+      event: 'subagentStart',
+      description: 'Log agent spawning for observability',
+    },
+  ],
+  subagentStop: [
+    {
+      command: 'node .cursor/hooks/subagent-stop.js',
+      event: 'subagentStop',
+      description: 'Log agent completion',
+    },
+  ],
+  beforeTabFileRead: [
+    {
+      command: 'node .cursor/hooks/before-tab-file-read.js',
+      event: 'beforeTabFileRead',
+      description: 'Block Tab from reading secrets (.env, .key, .pem, credentials)',
+    },
+  ],
+  afterTabFileEdit: [
+    {
+      command: 'node .cursor/hooks/after-tab-file-edit.js',
+      event: 'afterTabFileEdit',
+      description: 'Auto-format Tab edits',
+    },
+  ],
+  preCompact: [
+    {
+      command: 'node .cursor/hooks/pre-compact.js',
+      event: 'preCompact',
+      description: 'Save state before context compaction',
+    },
+  ],
+  stop: [
+    {
+      command: 'node .cursor/hooks/stop.js',
+      event: 'stop',
+      description: 'Console.log audit on all modified files',
+    },
+  ],
+});
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function buildCursorHookEntries() {
+  const entries = clone(CURSOR_HOOK_ENTRIES);
+
+  for (const eventName of getCursorMappedEventNames()) {
+    if (!Array.isArray(entries[eventName]) || entries[eventName].length === 0) {
+      throw new Error(`Cursor hook config is missing required AW-mapped event '${eventName}'`);
+    }
+  }
+
+  return entries;
+}
+
+function buildCursorHookConfig() {
+  return {
+    version: 1,
+    hooks: buildCursorHookEntries(),
+  };
+}
+
+function serializeCursorHookConfig() {
+  return `${JSON.stringify(buildCursorHookConfig(), null, 2)}\n`;
+}
+
+module.exports = {
+  CURSOR_HOOK_ENTRIES,
+  buildCursorHookEntries,
+  buildCursorHookConfig,
+  serializeCursorHookConfig,
+};