codex-toolkit 0.4.0

package/src/diff-budget.js

@@ -0,0 +1,173 @@
+// diff-budget — set a per-task ceiling on how much Codex may change.
+//
+// Why: scope-guard controls *where* Codex may edit. diff-budget controls
+// *how much*. Even within an allowed scope, an agent can quietly rewrite
+// half the file or churn 30 files in one turn. This hook catches that.
+//
+// Two layers of defense, both configurable:
+//
+// 1. Per-call ceiling (stateless, easy to reason about):
+//      max_bytes_per_write  — refuse writes whose input is larger than N bytes.
+//
+// 2. Per-session ceiling (stateful, file-based counter):
+//      max_files_per_task   — refuse once N distinct files have been touched
+//                             in the current session.
+//      max_total_bytes      — refuse once total bytes written exceeds N.
+//
+// State persists at <cwd>/.codex-toolkit/.diff-budget.json and is keyed
+// by session id (best-effort) or cwd. Reset by deleting the file or
+// running `codex-toolkit diff-budget reset`.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import {
+  DECISIONS,
+  FILE_MUTATING_TOOLS,
+  emitDecision,
+  emitError,
+  parseHookInput,
+  extractTargetPath,
+} from './hook-protocol.js';
+import { readState, resolveStateFile, sessionKey, updateState } from './state-store.js';
+
+const DEFAULT_CONFIG = {
+  mode: 'enforce', // 'enforce' | 'ask' | 'off'
+  max_bytes_per_write: 100_000, // ~100 KB per single write
+  max_files_per_task: 25, // ~distinct files per session
+  max_total_bytes: 500_000, // ~500 KB total per session
+  log: true,
+};
+
+function loadConfig() {
+  const candidates = [
+    process.env.CODEX_TOOLKIT_DIFF_BUDGET_CONFIG,
+    path.join(process.cwd(), '.codex-toolkit', 'diff-budget.json'),
+    path.join(process.env.HOME || '', '.codex', 'diff-budget.json'),
+  ].filter(Boolean);
+  for (const file of candidates) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+      return { ...DEFAULT_CONFIG, ...parsed };
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        emitError(`diff-budget: failed to read ${file}: ${err.message}`);
+      }
+    }
+  }
+  return { ...DEFAULT_CONFIG };
+}
+
+function byteSizeOfWrite(input) {
+  if (!input || typeof input !== 'object') return 0;
+  const candidates = [
+    input.content,
+    input.contents,
+    input.new_string,
+    input.newString,
+    input.text,
+    input.body,
+    input.patch,
+  ];
+  for (const c of candidates) {
+    if (typeof c === 'string') return Buffer.byteLength(c, 'utf8');
+  }
+  return 0;
+}
+
+function overThreshold(value, limit) {
+  return typeof limit === 'number' && limit > 0 && value > limit;
+}
+
+function formatReason(kind, current, limit) {
+  return `diff-budget: ${kind} (${current}) exceeded limit (${limit}). Increase the limit in .codex-toolkit/diff-budget.json or split the task.`;
+}
+
+export function evaluate(event) {
+  const config = loadConfig();
+  if (config.mode === 'off') {
+    return { decision: DECISIONS.ALLOW, reason: null, skipped: true };
+  }
+  if (!FILE_MUTATING_TOOLS.has(event.toolName)) {
+    return { decision: DECISIONS.ALLOW, reason: null, skipped: true };
+  }
+
+  const target = extractTargetPath(event.toolInput);
+  const writeBytes = byteSizeOfWrite(event.toolInput);
+
+  // (1) per-call ceiling
+  if (overThreshold(writeBytes, config.max_bytes_per_write)) {
+    return respond(config, 'deny', formatReason('per-write size', writeBytes, config.max_bytes_per_write));
+  }
+
+  // (2) per-session ceiling
+  const stateFile = resolveStateFile('diff-budget');
+  const key = sessionKey(event);
+  const state = updateState(
+    stateFile,
+    (s) => {
+      s.sessions = s.sessions || {};
+      const sess = s.sessions[key] || { files: {}, totalBytes: 0 };
+      if (target && !sess.files[target]) {
+        sess.files[target] = { firstAt: Date.now() };
+      }
+      sess.totalBytes += writeBytes;
+      s.sessions[key] = sess;
+      return s;
+    },
+    { sessions: {} }
+  );
+  const sess = state.sessions[key] || { files: {}, totalBytes: 0 };
+  const fileCount = Object.keys(sess.files).length;
+
+  if (overThreshold(fileCount, config.max_files_per_task)) {
+    return respond(config, 'deny', formatReason('files touched this task', fileCount, config.max_files_per_task));
+  }
+  if (overThreshold(sess.totalBytes, config.max_total_bytes)) {
+    return respond(config, 'deny', formatReason('total bytes this task', sess.totalBytes, config.max_total_bytes));
+  }
+
+  return { decision: DECISIONS.ALLOW, reason: null, stats: { fileCount, totalBytes: sess.totalBytes } };
+}
+
+function respond(config, severity, reason) {
+  const decision = severity === 'deny' && config.mode === 'ask' ? DECISIONS.ASK : DECISIONS.DENY;
+  if (config.log) {
+    process.stderr.write(`[diff-budget] -> ${decision}: ${reason}\n`);
+  }
+  return { decision, reason };
+}
+
+// --- CLI entry point ---------------------------------------------------------
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => (data += chunk));
+    process.stdin.on('end', () => resolve(data));
+  });
+}
+
+async function main() {
+  const raw = await readStdin();
+  const parsed = parseHookInput(raw);
+  if (!parsed.ok) {
+    emitError(`diff-budget: ${parsed.error}`);
+    return;
+  }
+  const result = evaluate(parsed);
+  emitDecision(result.decision, result.reason);
+  if (result.decision === DECISIONS.DENY) {
+    process.exit(2);
+  }
+}
+
+const isMain =
+  import.meta.url === `file://${process.argv[1]}` ||
+  process.argv[1]?.endsWith('diff-budget.js');
+if (isMain) {
+  main().catch((err) => emitError(err.stack || err.message));
+}
+
+export default { evaluate };

package/src/hook-protocol.js

@@ -0,0 +1,146 @@
+// Shared constants and helpers for Codex CLI hooks.
+//
+// The Codex CLI hook protocol (as observed in the openai/codex feature flag
+// "hooks", default-on since v0.50) follows the same shape used by other major
+// AI coding CLIs:
+//
+//   1. Codex invokes a hook as a subprocess and writes a JSON event to its stdin.
+//   2. The hook reads the event, decides, and writes a JSON decision to stdout.
+//   3. The hook exits:
+//        0  -> success, decision in stdout is honored
+//        2  -> blocking error, stderr is fed back to the model
+//        *  -> non-blocking error, stderr is shown to the user, execution continues
+//
+// We keep the schema loose (`parseHookInput` tolerates a few common shapes)
+// because Codex has not yet published a formal protocol spec; once it does,
+// the parser becomes a single-file change without touching any individual hook.
+
+export const HOOK_EVENTS = Object.freeze({
+  PRE_TOOL_USE: 'PreToolUse',
+  POST_TOOL_USE: 'PostToolUse',
+  USER_PROMPT_SUBMIT: 'UserPromptSubmit',
+  SESSION_START: 'SessionStart',
+  SESSION_END: 'SessionEnd',
+});
+
+export const DECISIONS = Object.freeze({
+  ALLOW: 'allow',
+  DENY: 'deny',
+  ASK: 'ask',
+});
+
+// Tools that operate on file paths. Used by hooks that care about *where* a
+// change is being made (scope-guard, env-guard, auto-lint).
+export const FILE_MUTATING_TOOLS = new Set([
+  'write_file',
+  'edit_file',
+  'apply_patch',
+  'create_file',
+  'patch_file',
+  'multi_edit',
+  'Write',
+  'Edit',
+  'MultiEdit',
+  'NotebookEdit',
+]);
+
+// Tools that run shell commands. Used by hooks that care about *what*
+// command is being executed (shield-destructive-cmd, shield-env-guard).
+export const SHELL_TOOLS = new Set([
+  'shell',
+  'bash',
+  'exec',
+  'Bash',
+  'Shell',
+]);
+
+// Best-effort extraction of the file path an event is about to mutate.
+// Returns `null` if no obvious path is present.
+export function extractTargetPath(input) {
+  if (!input || typeof input !== 'object') return null;
+  const candidates = [
+    input.file_path,
+    input.path,
+    input.filePath,
+    input.target_file,
+    input.targetPath,
+    input?.tool_input?.file_path,
+    input?.tool_input?.path,
+    input?.tool_input?.filePath,
+    input?.tool_input?.target_file,
+  ];
+  for (const c of candidates) {
+    if (typeof c === 'string' && c.length > 0) return c;
+  }
+  return null;
+}
+
+// Best-effort extraction of the shell command an event is about to run.
+export function extractShellCommand(input) {
+  if (!input || typeof input !== 'object') return null;
+  const candidates = [
+    input.command,
+    input.cmd,
+    input.shell_command,
+    input?.tool_input?.command,
+    input?.tool_input?.cmd,
+  ];
+  for (const c of candidates) {
+    if (typeof c === 'string' && c.length > 0) return c;
+  }
+  return null;
+}
+
+// Tolerate several observed JSON shapes. We do not throw on unknown shapes —
+// instead we return a `parseHookInput` result with what we could extract.
+export function parseHookInput(rawJson) {
+  let event = rawJson;
+  if (typeof rawJson === 'string') {
+    try {
+      event = JSON.parse(rawJson);
+    } catch {
+      return { ok: false, error: 'invalid JSON' };
+    }
+  }
+  if (!event || typeof event !== 'object') {
+    return { ok: false, error: 'event is not an object' };
+  }
+
+  const eventName =
+    event.event ||
+    event.hook_event_name ||
+    event.type ||
+    event.eventName ||
+    null;
+
+  const toolName =
+    event.tool_name ||
+    event.toolName ||
+    event?.tool?.name ||
+    event?.tool_input?.tool ||
+    null;
+
+  const toolInput =
+    event.tool_input ||
+    event.toolInput ||
+    event?.tool?.input ||
+    event.input ||
+    null;
+
+  const cwd =
+    event.cwd || event.working_directory || event.cwd || process.cwd();
+
+  return { ok: true, eventName, toolName, toolInput, cwd, raw: event };
+}
+
+// Standard JSON decision writer used by every hook.
+export function emitDecision(decision, reason) {
+  const out = { decision };
+  if (reason) out.reason = reason;
+  process.stdout.write(JSON.stringify(out) + '\n');
+}
+
+export function emitError(message) {
+  process.stderr.write(`[codex-toolkit] ${message}\n`);
+  process.exit(2);
+}

package/src/index.js

@@ -0,0 +1,12 @@
+// Public entry point. Re-exports the stable API surface.
+// All hook modules are also runnable as standalone scripts — see bin/codex-toolkit.js.
+
+export { default as scopeGuard } from './scope-guard.js';
+export { default as diffBudget } from './diff-budget.js';
+export { default as toolPaceCheck } from './tool-pace-check.js';
+export { default as shieldDestructiveCmd } from './shield-destructive-cmd.js';
+export { default as shieldEnvGuard } from './shield-env-guard.js';
+export { default as autoLint } from './auto-lint.js';
+export { install, uninstall, list, doctor } from './installer.js';
+export { HOOK_EVENTS, DECISIONS, parseHookInput } from './hook-protocol.js';
+export { readState, writeState, updateState, sessionKey } from './state-store.js';

package/src/installer.js

@@ -0,0 +1,331 @@
+// codex-toolkit — installer and CLI.
+//
+// Subcommands:
+//   init      install the bundled hooks into ~/.codex/ (user-level)
+//   list      show installed hooks and their current state
+//   doctor    sanity-check the install (config files, executables, permissions)
+//   uninstall remove every file this tool wrote
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(__dirname, '..');
+const HOOKS_DIR = path.join(PKG_ROOT, 'src');
+
+const CODEX_HOME =
+  process.env.CODEX_HOME ||
+  path.join(os.homedir(), '.codex');
+
+const HOOKS_INSTALLED = path.join(CODEX_HOME, 'hooks');
+const HOOKS_CONFIG = path.join(CODEX_HOME, 'hooks.json');
+const HOOKS_CONFIG_TOML = path.join(CODEX_HOME, 'config.toml');
+
+// Bundled hooks (relative to src/).
+const BUNDLED = [
+  {
+    id: 'scope-guard',
+    file: 'scope-guard.js',
+    event: 'PreToolUse',
+    description: 'Block file edits outside the declared task scope.',
+  },
+  {
+    id: 'diff-budget',
+    file: 'diff-budget.js',
+    event: 'PostToolUse',
+    description: 'Refuse writes that exceed a per-task file/byte budget.',
+  },
+  {
+    id: 'tool-pace-check',
+    file: 'tool-pace-check.js',
+    event: 'PreToolUse',
+    description: 'Slow Codex down when it chains many tool calls in a short window.',
+  },
+  {
+    id: 'shield-destructive-cmd',
+    file: 'shield-destructive-cmd.js',
+    event: 'PreToolUse',
+    description: 'Refuse shell commands that can destroy the project (rm -rf, force push, drop table, etc.).',
+  },
+  {
+    id: 'shield-env-guard',
+    file: 'shield-env-guard.js',
+    event: 'PreToolUse',
+    description: 'Refuse writes to .env, SSH keys, cloud creds, and other sensitive files.',
+  },
+  {
+    id: 'auto-lint',
+    file: 'auto-lint.js',
+    event: 'PostToolUse',
+    description: 'Run the right linter (gofmt/ruff/eslint/rustfmt) on every file Codex touches.',
+  },
+];
+
+// --- helpers -----------------------------------------------------------------
+
+function log(msg) {
+  process.stdout.write(`[codex-toolkit] ${msg}\n`);
+}
+function warn(msg) {
+  process.stderr.write(`[codex-toolkit] WARN: ${msg}\n`);
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+
+function copyHook(file) {
+  const src = path.join(HOOKS_DIR, file);
+  const dst = path.join(HOOKS_INSTALLED, file);
+  fs.copyFileSync(src, dst);
+  fs.chmodSync(dst, 0o755);
+  return dst;
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(file, value) {
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n', {
+    mode: 0o600,
+  });
+}
+
+// Generate a TOML fragment that declares the hooks. We append (not overwrite)
+// so existing user config is preserved. If the user has no config.toml at
+// all we create a minimal one.
+function patchConfigToml(hookEntries) {
+  let existing = '';
+  try {
+    existing = fs.readFileSync(HOOKS_CONFIG_TOML, 'utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+
+  if (existing.includes('[hooks]')) {
+    log(`[hooks] section already present in ${HOOKS_CONFIG_TOML} — leaving as-is.`);
+    return { status: 'skipped', reason: 'hooks section exists' };
+  }
+
+  const header =
+    '# Added by codex-toolkit — do not edit by hand unless you know what you are doing.\n';
+  const lines = ['[hooks]'];
+  for (const entry of hookEntries) {
+    const cmd = entry.command.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    lines.push(`"${entry.event}" = [{ command = "${cmd}", timeout = 30 }]`);
+  }
+  const fragment = header + lines.join('\n') + '\n';
+
+  const next = existing.endsWith('\n') || existing === ''
+    ? existing + fragment
+    : existing + '\n' + fragment;
+
+  fs.writeFileSync(HOOKS_CONFIG_TOML, next, { mode: 0o600 });
+  return { status: 'written', file: HOOKS_CONFIG_TOML };
+}
+
+// --- subcommands -------------------------------------------------------------
+
+export function install({ dryRun = false, scope = 'user' } = {}) {
+  if (scope !== 'user') {
+    warn(`Only --scope=user is supported in this version.`);
+  }
+  log(`Installing into ${CODEX_HOME}`);
+
+  ensureDir(CODEX_HOME);
+  ensureDir(HOOKS_INSTALLED);
+
+  const entries = [];
+  for (const hook of BUNDLED) {
+    if (dryRun) {
+      log(`(dry-run) would install ${hook.id} -> ${HOOKS_INSTALLED}/${hook.file}`);
+    } else {
+      const dst = copyHook(hook.file);
+      log(`installed ${hook.id} -> ${dst}`);
+    }
+    entries.push({
+      event: hook.event,
+      command: `node ${path.join(HOOKS_INSTALLED, hook.file)}`,
+      id: hook.id,
+    });
+  }
+
+  if (!dryRun) {
+    const hooksJson = readJson(HOOKS_CONFIG) || { hooks: {} };
+    hooksJson.hooks = hooksJson.hooks || {};
+    for (const entry of entries) {
+      hooksJson.hooks[entry.event] = hooksJson.hooks[entry.event] || [];
+      // Don't double-register.
+      const dup = hooksJson.hooks[entry.event].some(
+        (e) => e?.command === entry.command
+      );
+      if (!dup) {
+        hooksJson.hooks[entry.event].push({
+          type: 'command',
+          command: entry.command,
+        });
+      }
+    }
+    writeJson(HOOKS_CONFIG, hooksJson);
+    log(`wrote ${HOOKS_CONFIG}`);
+
+    try {
+      const result = patchConfigToml(entries);
+      if (result.status === 'written') {
+        log(`appended [hooks] to ${result.file}`);
+      }
+    } catch (err) {
+      warn(`could not patch config.toml (${err.message}). ${HOOKS_CONFIG} still works.`);
+    }
+  }
+
+  log('Done. Next: run `codex-toolkit list` to verify, then `codex-toolkit doctor`.');
+}
+
+export function list() {
+  log(`Codex home: ${CODEX_HOME}`);
+  for (const hook of BUNDLED) {
+    const dst = path.join(HOOKS_INSTALLED, hook.file);
+    const exists = fs.existsSync(dst);
+    const stats = exists ? fs.statSync(dst) : null;
+    log(
+      `  ${hook.id.padEnd(20)} ${exists ? 'OK ' : 'MISSING'}  ${dst}` +
+        (stats ? `  (${stats.size} bytes)` : '')
+    );
+  }
+  const cfg = readJson(HOOKS_CONFIG);
+  if (cfg) {
+    log(`  hooks.json:        ${HOOKS_CONFIG}`);
+  } else {
+    warn(`no ${HOOKS_CONFIG} found. Run \`codex-toolkit init\`.`);
+  }
+}
+
+export function doctor() {
+  const checks = [];
+  checks.push({
+    name: 'Node version >= 18',
+    ok: Number(process.versions.node.split('.')[0]) >= 18,
+    detail: process.version,
+  });
+  checks.push({
+    name: '~/.codex exists',
+    ok: fs.existsSync(CODEX_HOME),
+    detail: CODEX_HOME,
+  });
+  checks.push({
+    name: 'hooks.json present',
+    ok: Boolean(readJson(HOOKS_CONFIG)),
+    detail: HOOKS_CONFIG,
+  });
+  for (const hook of BUNDLED) {
+    const dst = path.join(HOOKS_INSTALLED, hook.file);
+    let ok = false;
+    let detail = dst;
+    try {
+      const stats = fs.statSync(dst);
+      ok = stats.isFile();
+      detail += ` (${stats.size} bytes)`;
+    } catch {
+      detail += ' (missing)';
+    }
+    checks.push({ name: `hook installed: ${hook.id}`, ok, detail });
+  }
+  let allOk = true;
+  for (const c of checks) {
+    log(`${c.ok ? 'OK  ' : 'FAIL'}  ${c.name.padEnd(34)} ${c.detail}`);
+    if (!c.ok) allOk = false;
+  }
+  // Smoke test: run scope-guard with a sample event.
+  try {
+    const sample = JSON.stringify({
+      event: 'PreToolUse',
+      tool_name: 'write_file',
+      tool_input: { file_path: 'src/api/handlers/auth.ts' },
+    });
+    const proc = spawnSync(
+      'node',
+      [path.join(HOOKS_INSTALLED, 'scope-guard.js')],
+      { input: sample, encoding: 'utf8' }
+    );
+    log(`smoke test: scope-guard stdout=${proc.stdout.trim() || '(empty)'} stderr=${proc.stderr.trim() || '(empty)'} exit=${proc.status}`);
+  } catch (err) {
+    warn(`smoke test failed: ${err.message}`);
+  }
+  if (!allOk) {
+    process.exitCode = 1;
+  }
+}
+
+export function uninstall() {
+  for (const hook of BUNDLED) {
+    const dst = path.join(HOOKS_INSTALLED, hook.file);
+    if (fs.existsSync(dst)) {
+      fs.unlinkSync(dst);
+      log(`removed ${dst}`);
+    }
+  }
+  log('Uninstall complete. Manual cleanup: edit ' + HOOKS_CONFIG_TOML + ' and ' + HOOKS_CONFIG);
+}
+
+// --- CLI dispatcher ----------------------------------------------------------
+
+function main() {
+  const [, , subcommand, ...rest] = process.argv;
+  const flags = new Set(rest);
+  switch (subcommand) {
+    case 'init':
+      return install({ dryRun: flags.has('--dry-run') });
+    case 'list':
+      return list();
+    case 'doctor':
+      return doctor();
+    case 'uninstall':
+      return uninstall();
+    case 'version':
+    case '--version':
+    case '-v':
+      log(JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8')).version);
+      return;
+    case undefined:
+    case 'help':
+    case '--help':
+    case '-h':
+      log(
+        [
+          'codex-toolkit <command>',
+          '',
+          'Commands:',
+          '  init       install hooks into ~/.codex/',
+          '  list       show installed hooks and config',
+          '  doctor     run sanity checks + smoke test',
+          '  uninstall  remove installed hooks',
+          '  version    print the version',
+          '',
+          'Flags:',
+          '  --dry-run  show what `init` would do without touching the filesystem',
+        ].join('\n')
+      );
+      return;
+    default:
+      warn(`unknown command: ${subcommand}. Try \`codex-toolkit help\`.`);
+      process.exitCode = 2;
+  }
+}
+
+const invokedDirectly =
+  import.meta.url === `file://${process.argv[1]}` ||
+  process.argv[1]?.endsWith('codex-toolkit.js');
+if (invokedDirectly) {
+  main();
+}