The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat: add dry-run mode for hook execution (#2116) (#2188)
Naomi48608863ea5c
diff --git a/scripts/ecc.js b/scripts/ecc.jsindex 946a1fc7c..7e38b3d38 100755--- a/scripts/ecc.js+++ b/scripts/ecc.js@@ -106,6 +106,7 @@ ECC selective-install CLIUsage:ecc <command> [args...]ecc [install args...]+ ecc --dry-run <command> [args...]Commands:${PRIMARY_COMMANDS.map(command => ` ${command.padEnd(15)} ${COMMANDS[command].description}`).join('\n')}@@ -115,6 +116,9 @@ Compatibility:ecc [args...] Without a command, args are routed to "install"ecc help <command> Show help for a specific command+Global Flags:+ --dry-run Preview actions without executing (sets ECC_DRY_RUN=1)+Examples:ecc typescriptecc install --profile developer --target claude@@ -152,7 +156,21 @@ function resolveCommand(argv) {return { mode: 'help' };}- const [firstArg, ...restArgs] = args;+ if (args.includes('--dry-run')) {+ process.env.ECC_DRY_RUN = '1';+ }++ let cmdStart = 0;+ while (cmdStart < args.length && args[cmdStart] === '--dry-run') {+ cmdStart++;+ }++ if (cmdStart >= args.length) {+ return { mode: 'help' };+ }++ const firstArg = args[cmdStart];+ const restArgs = args.slice(cmdStart + 1);if (firstArg === '--help' || firstArg === '-h') {return { mode: 'help' };diff --git a/scripts/hooks/run-with-flags.js b/scripts/hooks/run-with-flags.jsindex c1c3b9046..41ff14623 100755--- a/scripts/hooks/run-with-flags.js+++ b/scripts/hooks/run-with-flags.js@@ -11,7 +11,7 @@const fs = require('fs');const path = require('path');const { spawnSync } = require('child_process');-const { isHookEnabled } = require('../lib/hook-flags');+const { isHookEnabled, isDryRun } = require('../lib/hook-flags');const { buildPreToolUseAdditionalContext } = require('./pretooluse-visible-output');const MAX_STDIN = 1024 * 1024;@@ -100,6 +100,50 @@ function getPluginRoot() {return path.resolve(__dirname, '..', '..');}++//Safely extract target context from hook stdin JSON for dry-run preview.++function extractTargetContext(raw) {+ const result = { tool: '', filePath: '', command: '' };+ if (!raw || typeof raw !== 'string') return result;++ try {+ const payload = JSON.parse(raw);+ if (payload && typeof payload === 'object') {+ result.tool = String(payload.tool || '');+ const input = payload.tool_input;+ if (input && typeof input === 'object') {+ result.filePath = String(input.file_path || input.path || '');+ result.command = String(input.command || '');+ }+ }+ } catch {+ }+ return result;+}++// Build the [DryRun] preview line for stderr.++function buildDryRunPreview(hookId, relScriptPath, profilesCsv, raw) {+ const ctx = extractTargetContext(raw);+ const parts = [+ `[DryRun] Hook "${hookId}" would execute: ${relScriptPath}`,+ `(enabled=true, profiles=${profilesCsv || 'default'})`,+ ];++ if (ctx.tool) {+ parts.push(`tool=${ctx.tool}`);+ }+ if (ctx.filePath) {+ parts.push(`target=${ctx.filePath}`);+ }+ if (ctx.command) {+ parts.push(`command=${ctx.command}`);+ }++ return parts.join(' ') + '\n';+}+async function main() {const [, , hookId, relScriptPath, profilesCsv] = process.argv;const { raw, truncated } = await readStdinRaw();@@ -125,6 +169,13 @@ async function main() {return;}+ if (isDryRun()) {+ const preview = buildDryRunPreview(hookId, relScriptPath, profilesCsv, raw);+ process.stderr.write(preview);+ process.stdout.write(raw);+ process.exit(0);+ }+const pluginRoot = getPluginRoot();const resolvedRoot = path.resolve(pluginRoot);const scriptPath = path.resolve(pluginRoot, relScriptPath);diff --git a/scripts/lib/hook-flags.js b/scripts/lib/hook-flags.jsindex 4f56660d1..70106bc15 100644--- a/scripts/lib/hook-flags.js+++ b/scripts/lib/hook-flags.js@@ -50,6 +50,10 @@ function parseProfiles(rawProfiles, fallback = ['standard', 'strict']) {return parsed.length > 0 ? parsed : [...fallback];}+function isDryRun() {+ return process.env.ECC_DRY_RUN === '1';+}+function isHookEnabled(hookId, options = {}) {const id = normalizeId(hookId);if (!id) return true;@@ -71,4 +75,5 @@ module.exports = {getDisabledHookIds,parseProfiles,isHookEnabled,+ isDryRun,};diff --git a/tests/lib/dry-run.test.js b/tests/lib/dry-run.test.jsnew file mode 100644index 000000000..18190ea9c--- /dev/null+++ b/tests/lib/dry-run.test.js@@ -0,0 +1,250 @@+/**+ * Tests for dry-run mode+ *+ * Run with: node tests/lib/dry-run.test.js+ */++const assert = require('assert');+const path = require('path');+const { spawnSync } = require('child_process');++function test(name, fn) {+ try {+ fn();+ console.log(` ✓ ${name}`);+ return true;+ } catch (err) {+ console.log(` ✗ ${name}`);+ console.log(` Error: ${err.message}`);+ return false;+ }+}++function runTests() {+ console.log('\n=== Testing dry-run mode ===\n');++ let passed = 0;+ let failed = 0;++ console.log('isDryRun():');++ if (test('returns false when ECC_DRY_RUN is unset', () => {+ const env = { ...process.env };+ delete env.ECC_DRY_RUN;+ const result = spawnSync(process.execPath, [+ '-e',+ 'const { isDryRun } = require("./scripts/lib/hook-flags"); process.exit(isDryRun() ? 1 : 0)',+ ], { cwd: path.resolve(__dirname, '..', '..'), env });+ assert.strictEqual(result.status, 0);+ })) passed++; else failed++;++ if (test('returns true when ECC_DRY_RUN=1', () => {+ const env = { ...process.env, ECC_DRY_RUN: '1' };+ const result = spawnSync(process.execPath, [+ '-e',+ 'const { isDryRun } = require("./scripts/lib/hook-flags"); process.exit(isDryRun() ? 1 : 0)',+ ], { cwd: path.resolve(__dirname, '..', '..'), env });+ assert.strictEqual(result.status, 1);+ })) passed++; else failed++;++ if (test('returns false when ECC_DRY_RUN=0', () => {+ const env = { ...process.env, ECC_DRY_RUN: '0' };+ const result = spawnSync(process.execPath, [+ '-e',+ 'const { isDryRun } = require("./scripts/lib/hook-flags"); process.exit(isDryRun() ? 1 : 0)',+ ], { cwd: path.resolve(__dirname, '..', '..'), env });+ assert.strictEqual(result.status, 0);+ })) passed++; else failed++;++ console.log('\nrun-with-flags.js dry-run gating:');++ if (test('skips hook execution and logs preview when ECC_DRY_RUN=1', () => {+ const runWithFlags = path.resolve(__dirname, '..', '..', 'scripts', 'hooks', 'run-with-flags.js');+ const hookScript = 'scripts/hooks/doc-file-warning.js';+ const input = JSON.stringify({ tool: 'Write', tool_input: { file_path: '/tmp/test.md' } });++ const result = spawnSync(process.execPath, [+ runWithFlags,+ 'pre:write:doc-file-warning',+ hookScript,+ 'standard,strict',+ ], {+ input,+ encoding: 'utf8',+ env: { ...process.env, ECC_DRY_RUN: '1' },+ cwd: path.resolve(__dirname, '..', '..'),+ });++ assert.strictEqual(result.status, 0, `Expected exit 0, got ${result.status}`);+ assert.ok(+ result.stderr.includes('[DryRun]'),+ `Expected stderr to contain [DryRun] tag, got: ${result.stderr}`+ );+ assert.ok(+ result.stderr.includes('pre:write:doc-file-warning'),+ `Expected stderr to contain hook ID, got: ${result.stderr}`+ );+ assert.ok(+ result.stderr.includes('tool=Write'),+ `Expected stderr to contain tool name, got: ${result.stderr}`+ );+ assert.ok(+ result.stderr.includes('target=/tmp/test.md'),+ `Expected stderr to contain target file path, got: ${result.stderr}`+ );+ assert.strictEqual(result.stdout, input, 'Expected stdin to be passed through unchanged');+ })) passed++; else failed++;++ if (test('dry-run preview includes command for bash hooks', () => {+ const runWithFlags = path.resolve(__dirname, '..', '..', 'scripts', 'hooks', 'run-with-flags.js');+ const hookScript = 'scripts/hooks/block-no-verify.js';+ const input = JSON.stringify({ tool: 'Bash', tool_input: { command: 'git commit --no-verify -m "test"' } });++ const result = spawnSync(process.execPath, [+ runWithFlags,+ 'pre:bash:block-no-verify',+ hookScript,+ 'standard,strict',+ ], {+ input,+ encoding: 'utf8',+ env: { ...process.env, ECC_DRY_RUN: '1' },+ cwd: path.resolve(__dirname, '..', '..'),+ });++ assert.strictEqual(result.status, 0, `Expected exit 0, got ${result.status}`);+ assert.ok(+ result.stderr.includes('tool=Bash'),+ `Expected stderr to contain tool=Bash, got: ${result.stderr}`+ );+ assert.ok(+ result.stderr.includes('command=git commit --no-verify'),+ `Expected stderr to contain command, got: ${result.stderr}`+ );+ assert.strictEqual(result.stdout, input, 'Expected stdin to be passed through unchanged');+ })) passed++; else failed++;++ if (test('dry-run preview handles non-JSON stdin gracefully', () => {+ const runWithFlags = path.resolve(__dirname, '..', '..', 'scripts', 'hooks', 'run-with-flags.js');+ const hookScript = 'scripts/hooks/session-start.js';+ const input = 'not valid json at all';++ const result = spawnSync(process.execPath, [+ runWithFlags,+ 'pre:session:start',+ hookScript,+ 'standard',+ ], {+ input,+ encoding: 'utf8',+ env: { ...process.env, ECC_DRY_RUN: '1' },+ cwd: path.resolve(__dirname, '..', '..'),+ });++ assert.strictEqual(result.status, 0, `Expected exit 0, got ${result.status}`);+ assert.ok(+ result.stderr.includes('[DryRun]'),+ `Expected stderr to contain [DryRun], got: ${result.stderr}`+ );+ assert.ok(+ !result.stderr.includes('tool='),+ 'Expected no tool= when stdin is not JSON'+ );+ assert.strictEqual(result.stdout, input, 'Expected stdin to be passed through unchanged');+ })) passed++; else failed++;++ if (test('dry-run preview handles empty stdin gracefully', () => {+ const runWithFlags = path.resolve(__dirname, '..', '..', 'scripts', 'hooks', 'run-with-flags.js');+ const hookScript = 'scripts/hooks/session-start.js';++ const result = spawnSync(process.execPath, [+ runWithFlags,+ 'post:stop:session-end',+ hookScript,+ 'standard',+ ], {+ input: '',+ encoding: 'utf8',+ env: { ...process.env, ECC_DRY_RUN: '1' },+ cwd: path.resolve(__dirname, '..', '..'),+ });++ assert.strictEqual(result.status, 0, `Expected exit 0, got ${result.status}`);+ assert.ok(+ result.stderr.includes('[DryRun]'),+ `Expected stderr to contain [DryRun], got: ${result.stderr}`+ );+ assert.ok(+ !result.stderr.includes('target='),+ 'Expected no target= when stdin is empty'+ );+ })) passed++; else failed++;++ if (test('executes hook normally when ECC_DRY_RUN is not set', () => {+ const runWithFlags = path.resolve(__dirname, '..', '..', 'scripts', 'hooks', 'run-with-flags.js');+ const hookScript = 'scripts/hooks/doc-file-warning.js';+ const input = JSON.stringify({ tool: 'Write', tool_input: { file_path: '/tmp/test.txt' } });++ const env = { ...process.env };+ delete env.ECC_DRY_RUN;++ const result = spawnSync(process.execPath, [+ runWithFlags,+ 'pre:write:doc-file-warning',+ hookScript,+ 'standard,strict',+ ], {+ input,+ encoding: 'utf8',+ env,+ cwd: path.resolve(__dirname, '..', '..'),+ });++ assert.strictEqual(result.status, 0);+ assert.ok(+ !result.stderr.includes('[DryRun]'),+ 'Expected no [DryRun] tag in normal execution'+ );+ })) passed++; else failed++;++ console.log('\necc.js --dry-run flag parsing:');++ if (test('--dry-run sets ECC_DRY_RUN env var for child commands', () => {+ const eccJs = path.resolve(__dirname, '..', '..', 'scripts', 'ecc.js');+ const result = spawnSync(process.execPath, [eccJs, '--dry-run', '--help'], {+ encoding: 'utf8',+ env: { ...process.env },+ });+ assert.strictEqual(result.status, 0);+ assert.ok(result.stdout.includes('--dry-run'), 'Help text should mention --dry-run');+ })) passed++; else failed++;++ if (test('--dry-run is stripped from args so command routing works', () => {+ const eccJs = path.resolve(__dirname, '..', '..', 'scripts', 'ecc.js');+ const result = spawnSync(process.execPath, [eccJs, '--dry-run', 'doctor'], {+ encoding: 'utf8',+ env: { ...process.env },+ });+ assert.ok(+ !result.stderr.includes('Unknown command: --dry-run'),+ 'Global --dry-run must not be treated as an unknown command'+ );+ })) passed++; else failed++;++ if (test('--dry-run works with implicit install routing', () => {+ const eccJs = path.resolve(__dirname, '..', '..', 'scripts', 'ecc.js');+ const result = spawnSync(process.execPath, [eccJs, '--dry-run', '--json', 'typescript'], {+ encoding: 'utf8',+ env: { ...process.env },+ });+ assert.strictEqual(result.status, 0, `Expected exit 0, got ${result.status}: ${result.stderr}`);+ const payload = JSON.parse(result.stdout);+ assert.strictEqual(payload.dryRun, true, 'Expected dryRun=true in JSON output');+ assert.deepStrictEqual(payload.plan.legacyLanguages, ['typescript']);+ })) passed++; else failed++;++ console.log(`\nResults: ${passed} passed, ${failed} failed`);+ process.exit(failed > 0 ? 1 : 0);+}++runTests();