your-cto-jev 0.1.0

package/dist/hooks.js

@@ -0,0 +1,174 @@
+import { styleText } from 'node:util';
+import { evaluate, providerOrder, providers } from './api.js';
+import { freshErrors, loadBrain, loadConfig, saveBrain } from './brain.js';
+import { chunkDiff, filterDiff, pool } from './diff.js';
+import { personaDict, t } from './i18n.js';
+import { maskDiff, maskSensitiveState } from './masker.js';
+const Q = {
+    credential_leak: {
+        type: 'noul',
+        instructions: 'Does this git diff add a real secret (API key, token, password, private key) to the repository? ' +
+            'Values shown as [REDACTED: TYPE] were real secrets detected and masked before review; treat them as real. ' +
+            'Every value in .env files is masked as [REDACTED: ENV_VALUE]: committing a real .env file with values is a leak, ' +
+            'while .env.example, .env.sample or .env.template files are normally placeholders.',
+        criteria: {
+            true: 'A real credential is being committed',
+            false: 'No real credential: placeholders, examples, or references to environment variables only',
+        },
+    },
+    destructive_command: {
+        type: 'noul',
+        instructions: 'Judge only the command about to run. Is this shell command irreversibly destructive ' +
+            '(deletes or overwrites data outside build artifacts, force-pushes or rewrites shared git history, drops databases) ' +
+            'in a way that cannot be undone?',
+        criteria: { true: 'Irreversibly destroys data or history', false: 'Safe, read-only, or reversible' },
+    },
+    infinite_loop: {
+        type: 'noul',
+        instructions: 'The state holds a command about to run and recently failed commands with their errors. ' +
+            'Is the agent stuck repeating the same failing approach, so running this command again will fail the same way?',
+        criteria: {
+            true: 'Same or near-identical command that already failed with the same error',
+            false: 'A new approach, a fix attempt, or unrelated to the earlier failures',
+        },
+    },
+    code_complexity: {
+        type: 'score',
+        instructions: 'Rate the maintenance cost and structural complexity of this change.',
+        criteria: [
+            'Minimal and clean',
+            'Simple with minor noise',
+            'Acceptable complexity',
+            'Over-engineered or deeply nested',
+            'Unmaintainable',
+        ],
+    },
+};
+const architectureQ = (goal) => ({
+    type: 'noul',
+    instructions: `The current sprint goal is: "${goal}". Does this change clearly work against or drift away from that goal?`,
+    criteria: { true: 'Clearly off-goal or contradicts the sprint goal', false: 'Aligned with or neutral to the sprint goal' },
+});
+const value = (a) => (a?.type === 'noul' ? a.noul : a?.type === 'score' ? a.score : undefined);
+function exceeded(answers, signal, cfg) {
+    const v = value(answers[signal]);
+    return v !== undefined && v > cfg.thresholds[signal] ? v : undefined;
+}
+function verdict(lang, signal, v, cfg, color) {
+    const head = `[cto] ${personaDict[lang][signal]}`;
+    const detail = `      ${t(lang, 'detail', { signal, value: v, threshold: cfg.thresholds[signal] })}`;
+    if (!color)
+        return [head, detail];
+    const s = (fmt, txt) => styleText(fmt, txt, { stream: process.stderr });
+    return [s([color, 'bold'], head), s('dim', detail)];
+}
+// ---------- git-commit ----------
+export async function gitCommit(rawDiff, { root, lang, now }) {
+    const cfg = loadConfig(root);
+    const brain = loadBrain(root);
+    const out = { code: 0, stderr: [] };
+    const files = filterDiff(maskDiff(rawDiff));
+    if (!files.length)
+        return out;
+    const chunks = chunkDiff(files);
+    const soft = { code_complexity: Q.code_complexity };
+    if (cfg.sprint_goal.trim())
+        soft.architecture_violation = architectureQ(cfg.sprint_goal.trim());
+    const notices = new Set();
+    const ctx = { brain, lang, timeoutMs: 5000, notices, now };
+    // Credential check on every chunk (no sampling); soft signals on the first chunk only. Max 3 in flight.
+    const results = await pool(chunks, 3, (state, i) => evaluate({ state, questions: i === 0 ? { credential_leak: Q.credential_leak, ...soft } : { credential_leak: Q.credential_leak } }, ctx));
+    if (results.some((r) => !r.ok))
+        brain.skipped_attempts++;
+    if (results.some((r) => !r.ok && r.reason === 'no_keys'))
+        notices.add(t(lang, 'no_keys'));
+    // No session concept in git: while degraded (non-primary provider), say so on every commit.
+    const primary = providerOrder()[0];
+    for (const r of results)
+        if (r.ok && r.provider !== primary)
+            notices.add(t(lang, 'using', { name: providers[r.provider].label }));
+    const lines = [];
+    const leaks = results.flatMap((r) => (r.ok ? [exceeded(r.answers, 'credential_leak', cfg)] : [])).filter((v) => v !== undefined);
+    if (leaks.length) {
+        out.code = 1;
+        brain.blocked_attempts++;
+        lines.push(...verdict(lang, 'credential_leak', Math.max(...leaks), cfg, 'red'));
+    }
+    const first = results[0];
+    if (first?.ok) {
+        for (const s of ['architecture_violation', 'code_complexity']) {
+            const v = exceeded(first.answers, s, cfg);
+            if (v !== undefined)
+                lines.push(...verdict(lang, s, v, cfg, 'yellow'));
+        }
+    }
+    out.stderr = [...notices, ...lines];
+    saveBrain(root, brain);
+    return out;
+}
+// ---------- pre (Bash / shell command gate, any agent) ----------
+function sessionNotice(brain, sessionId, lang, r, notices) {
+    if (!sessionId || brain.notified_sessions.includes(sessionId))
+        return;
+    brain.notified_sessions = [...brain.notified_sessions, sessionId].slice(-20);
+    if (r.ok)
+        notices.add(t(lang, 'using', { name: providers[r.provider].label }));
+    else if (r.reason === 'no_keys')
+        notices.add(t(lang, 'no_keys'));
+    else if (!notices.size)
+        notices.add(t(lang, 'fail_open', { detail: '' }));
+}
+export async function agentPre(agent, input, { root, lang, now }) {
+    const command = input.command;
+    if (!command?.trim())
+        return { code: 0, stderr: [] };
+    const cfg = loadConfig(root);
+    const brain = loadBrain(root);
+    const questions = { destructive_command: Q.destructive_command };
+    let state = maskSensitiveState(command);
+    const recent = freshErrors(brain, (now ?? Date.now)());
+    if (recent.length) {
+        questions.infinite_loop = Q.infinite_loop;
+        state =
+            `Command about to run:\n${state}\n\nRecently failed commands (oldest first):\n` +
+                recent.map((e) => `$ ${e.command}\n${e.error}`).join('\n\n');
+    }
+    const notices = new Set();
+    const { sessionId } = input;
+    const r = await evaluate({ state, questions, ...(sessionId && { session_id: sessionId }) }, { brain, lang, timeoutMs: 2000, notices, now });
+    if (!r.ok)
+        brain.skipped_attempts++;
+    sessionNotice(brain, sessionId, lang, r, notices);
+    let out = { code: 0, stderr: [] };
+    if (r.ok) {
+        for (const s of ['destructive_command', 'infinite_loop']) {
+            const v = exceeded(r.answers, s, cfg);
+            if (v === undefined)
+                continue;
+            brain.blocked_attempts++;
+            out = agent.block([...verdict(lang, s, v, cfg, null), ...notices]);
+            break;
+        }
+    }
+    if (out.code === 0 && notices.size)
+        out = agent.notice([...notices]);
+    saveBrain(root, brain);
+    return out;
+}
+// ---------- post (failure recording) ----------
+/** Record the failure only; never calls Jev. No error field, no record. */
+export function agentPost(input, { root }) {
+    if (!input)
+        return { code: 0, stderr: [] };
+    const brain = loadBrain(root);
+    brain.recent_errors = [
+        ...freshErrors(brain),
+        {
+            command: maskSensitiveState(input.command).slice(0, 500),
+            error: maskSensitiveState(input.error).slice(0, 500),
+            at: new Date().toISOString(),
+        },
+    ].slice(-5);
+    saveBrain(root, brain);
+    return { code: 0, stderr: [] };
+}

package/dist/i18n.js

@@ -0,0 +1,130 @@
+/** CTO_LANG > LC_ALL / LANG > OS locale via Intl (Windows has no LANG) > en. zh-* maps to zh-TW. */
+export function detectLang(env = process.env) {
+    const pick = (v) => {
+        if (!v || v === 'C' || v === 'POSIX')
+            return undefined;
+        return v.toLowerCase().startsWith('zh') ? 'zh-TW' : v.toLowerCase().startsWith('en') ? 'en' : undefined;
+    };
+    return (pick(env.CTO_LANG) ??
+        pick(env.LC_ALL) ??
+        pick(env.LANG) ??
+        pick(Intl.DateTimeFormat().resolvedOptions().locale) ??
+        'en');
+}
+export const personaDict = {
+    'zh-TW': {
+        credential_leak: '喂，大天才。你差點把金鑰推進 Git。Commit 已攔下，立刻拿掉。',
+        destructive_command: '停手。這個指令有不可逆的破壞性，這次不准執行。',
+        infinite_loop: '同樣的錯誤又來了，你們在鬼打牆燒 Token。這次工具呼叫我擋下了，先去看邏輯。',
+        architecture_violation: '這次變更偏離了 Sprint 目標。我放你過，但這筆帳記著。',
+        code_complexity: '複雜度超標，過度工程化。這次不擋，但趕快重構。',
+    },
+    en: {
+        credential_leak: 'Nice one, genius. You almost pushed a secret into Git. Commit BLOCKED. Remove it.',
+        destructive_command: 'Hold it. This command is irreversibly destructive. Not running it.',
+        infinite_loop: 'Same error again. You are looping and burning tokens. This tool call is BLOCKED. Fix the logic first.',
+        architecture_violation: 'This change drifts from the sprint goal. Letting it through, but I noticed.',
+        code_complexity: 'Over-engineered. Not blocking this time, but refactor it.',
+    },
+};
+const messages = {
+    'zh-TW': {
+        reason_402: () => '額度不足',
+        reason_auth: () => '認證失敗',
+        reason_429: () => '請求過多',
+        reason_timeout: () => '逾時',
+        reason_5xx: () => '服務錯誤',
+        reason_network: () => '連線失敗',
+        reason_bad_response: () => '回應格式錯誤',
+        dur_1h: () => '1 小時',
+        dur_5m: () => '5 分鐘',
+        switched: (v) => `[cto] ${v.from} ${v.reason} (${v.status})，${v.dur}內改用 ${v.to}`,
+        recovered: (v) => `[cto] ${v.name} 已恢復，切回主要 provider`,
+        using: (v) => `[cto] 目前使用 ${v.name} 審查`,
+        fail_open: (v) => `[cto] ${v.detail}所有 provider 都無法使用，這次直接放行`,
+        fail_open_detail: (v) => `${v.from} ${v.reason} (${v.status})。`,
+        bad_request: (v) => `[cto] Jev 拒絕請求 (400)，這次直接放行：${v.msg}`,
+        no_keys: () => '[cto] 未設定 Jev API key，全部放行。請設定 CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID 或 OPENROUTER_API_KEY',
+        detail: (v) => `${v.signal} = ${v.value}（門檻 > ${v.threshold}）`,
+        setup_not_git: () => '[cto] 這裡不是 git repository，setup 中止。',
+        setup_bad_json: (v) => `[cto] ${v.path} 不是合法 JSON 或 hooks 格式不符，未修改任何檔案。請先修正該檔。`,
+        setup_hook: (v) => `[cto] pre-commit 區塊已寫入 ${v.path}`,
+        setup_hook_exit: (v) => `[cto] 警告：${v.path} 在 cto 區塊之前有 exit 0，cto 檢查不會執行。請調整該 hook。`,
+        setup_gitignore: () => '[cto] .gitignore 已加入 .cto-brain.json 與 debug_stdin.json',
+        setup_config: () => '[cto] 已建立 .cto.json（請 commit 給團隊共用）',
+        setup_sprint: () => '[cto] 提示：在 .cto.json 填入 sprint_goal 以啟用架構對齊檢查。',
+        setup_done: () => '[cto] 安裝完成。',
+        uninstall_hook: (v) => `[cto] 已從 ${v.path} 移除 cto 區塊`,
+        uninstall_gitignore: () => '[cto] 已從 .gitignore 移除 cto 區塊',
+        uninstall_done: () => '[cto] 已解除安裝（.cto.json 保留）。',
+        setup_agent: (v) => `[cto] ${v.label} hooks 已寫入 ${v.path}`,
+        uninstall_agent: (v) => `[cto] 已從 ${v.path} 移除 ${v.label} hooks`,
+        note_codex_trust: () => '[cto] 注意：Codex 只在專案被信任後才執行 .codex/ 的 hook，第一次在此目錄開 codex 時請選擇信任。',
+        wiz_agents: () => '\n要為哪些 coding agent 安裝指令攔截？（git commit 檢查一律安裝，所有 agent 共用）',
+        wiz_agent_q: (v) => `  ${v.label}${v.found} [${v.hint}] `,
+        wiz_found: () => '（已偵測到）',
+        wiz_keys_present: () => '[cto] 已從環境變數或憑證檔找到 Jev API key，略過金鑰設定。要重設請執行 cto setup --keys',
+        wiz_keys: (v) => `\n設定 Jev API key（至少一組，直接 Enter 跳過）。key 存在 ${v.path}，只有你的帳號可讀，不會進 git。`,
+        wiz_or_key: () => '  OpenRouter API key: ',
+        wiz_cf_account: () => '  Cloudflare Account ID: ',
+        wiz_cf_token: () => '  Cloudflare API token: ',
+        wiz_checking: (v) => `  正在用一次真實請求驗證 ${v.name}...`,
+        wiz_ok: (v) => `  ${v.name} 驗證成功`,
+        wiz_fail: (v) => `  ${v.name} 驗證失敗 (${v.status}) ${v.msg}`,
+        wiz_save_anyway: () => '  仍要儲存這組 key 嗎？[y/N] ',
+        wiz_saved: (v) => `[cto] key 已儲存到 ${v.path}`,
+        wiz_no_keys: () => '[cto] 沒有設定任何 key，cto 會全部放行，之後可執行 cto setup --keys 補上。',
+        usage: () => '用法：cto setup [--agents claude,cursor,gemini,codex] [--keys] [--yes] [--uninstall] | cto --hook <git-commit|AGENT-pre|AGENT-post>',
+    },
+    en: {
+        reason_402: () => 'out of credits',
+        reason_auth: () => 'auth failed',
+        reason_429: () => 'rate limited',
+        reason_timeout: () => 'timed out',
+        reason_5xx: () => 'server error',
+        reason_network: () => 'network error',
+        reason_bad_response: () => 'malformed response',
+        dur_1h: () => '1 hour',
+        dur_5m: () => '5 minutes',
+        switched: (v) => `[cto] ${v.from} ${v.reason} (${v.status}), using ${v.to} for the next ${v.dur}`,
+        recovered: (v) => `[cto] ${v.name} recovered, switched back to the primary provider`,
+        using: (v) => `[cto] Reviewing with ${v.name}`,
+        fail_open: (v) => `[cto] ${v.detail}No provider available, letting this one through`,
+        fail_open_detail: (v) => `${v.from} ${v.reason} (${v.status}). `,
+        bad_request: (v) => `[cto] Jev rejected the request (400), letting this one through: ${v.msg}`,
+        no_keys: () => '[cto] No Jev API key set, everything passes. Set CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID or OPENROUTER_API_KEY',
+        detail: (v) => `${v.signal} = ${v.value} (threshold > ${v.threshold})`,
+        setup_not_git: () => '[cto] Not a git repository, setup aborted.',
+        setup_bad_json: (v) => `[cto] ${v.path} is not valid JSON or has an unexpected hooks shape. Nothing was changed. Fix it first.`,
+        setup_hook: (v) => `[cto] pre-commit block written to ${v.path}`,
+        setup_hook_exit: (v) => `[cto] Warning: ${v.path} has an exit 0 before the cto block, so cto will never run. Adjust that hook.`,
+        setup_gitignore: () => '[cto] Added .cto-brain.json and debug_stdin.json to .gitignore',
+        setup_config: () => '[cto] Created .cto.json (commit it for the team)',
+        setup_sprint: () => '[cto] Tip: set sprint_goal in .cto.json to enable the architecture alignment check.',
+        setup_done: () => '[cto] Setup complete.',
+        uninstall_hook: (v) => `[cto] Removed the cto block from ${v.path}`,
+        uninstall_gitignore: () => '[cto] Removed the cto block from .gitignore',
+        uninstall_done: () => '[cto] Uninstalled (.cto.json kept).',
+        setup_agent: (v) => `[cto] ${v.label} hooks written to ${v.path}`,
+        uninstall_agent: (v) => `[cto] Removed ${v.label} hooks from ${v.path}`,
+        note_codex_trust: () => '[cto] Note: Codex only runs .codex/ hooks once the project is trusted. Trust it the first time you open codex here.',
+        wiz_agents: () => '\nWhich coding agents should get command interception? (the git commit check is always installed and covers every agent)',
+        wiz_agent_q: (v) => `  ${v.label}${v.found} [${v.hint}] `,
+        wiz_found: () => ' (detected)',
+        wiz_keys_present: () => '[cto] Found a Jev API key in env or the credentials file, skipping key setup. Run cto setup --keys to change it.',
+        wiz_keys: (v) => `\nSet up a Jev API key (at least one; press Enter to skip). Keys are stored in ${v.path}, readable only by you, never in git.`,
+        wiz_or_key: () => '  OpenRouter API key: ',
+        wiz_cf_account: () => '  Cloudflare Account ID: ',
+        wiz_cf_token: () => '  Cloudflare API token: ',
+        wiz_checking: (v) => `  Verifying ${v.name} with one real request...`,
+        wiz_ok: (v) => `  ${v.name} OK`,
+        wiz_fail: (v) => `  ${v.name} failed (${v.status}) ${v.msg}`,
+        wiz_save_anyway: () => '  Save this key anyway? [y/N] ',
+        wiz_saved: (v) => `[cto] Keys saved to ${v.path}`,
+        wiz_no_keys: () => '[cto] No key set, so cto lets everything through. Run cto setup --keys later.',
+        usage: () => 'Usage: cto setup [--agents claude,cursor,gemini,codex] [--keys] [--yes] [--uninstall] | cto --hook <git-commit|AGENT-pre|AGENT-post>',
+    },
+};
+export function t(lang, key, vars = {}) {
+    return (messages[lang][key] ?? messages.en[key])(vars);
+}

package/dist/index.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { agentNames, agents } from './agents.js';
+import { applyCredentials, findRoot } from './brain.js';
+import { agentPost, agentPre, gitCommit } from './hooks.js';
+import { detectLang, t } from './i18n.js';
+import { maskDiff, maskSensitiveState } from './masker.js';
+import { detectAgents, setup } from './setup.js';
+import { terminalAsk, wizard } from './wizard.js';
+async function readStdin() {
+    if (process.stdin.isTTY)
+        return '';
+    let s = '';
+    process.stdin.setEncoding('utf8');
+    for await (const chunk of process.stdin)
+        s += chunk;
+    return s;
+}
+function emit(out) {
+    if (out.stdout)
+        process.stdout.write(out.stdout + '\n');
+    if (out.stderr.length)
+        process.stderr.write(out.stderr.join('\n') + '\n');
+    process.exitCode = out.code;
+}
+async function runHook(name) {
+    const raw = await readStdin();
+    const lang = detectLang();
+    const debug = (root, text) => {
+        if (process.env.CTO_DEBUG === '1')
+            writeFileSync(join(root, 'debug_stdin.json'), text);
+    };
+    if (name === 'git-commit') {
+        const root = findRoot();
+        debug(root, maskDiff(raw));
+        return gitCommit(raw, { root, lang });
+    }
+    const m = /^(claude|cursor|gemini|codex)-(pre|post)$/.exec(name);
+    if (!m)
+        return { code: 0, stderr: [] };
+    const agent = agents[m[1]];
+    let input = {};
+    try {
+        input = JSON.parse(raw);
+    }
+    catch { /* fail-open below */ }
+    if (m[2] === 'pre') {
+        const pre = agent.parsePre(input);
+        const root = findRoot(pre.cwd ?? process.cwd());
+        debug(root, maskSensitiveState(raw));
+        return agentPre(agent, pre, { root, lang });
+    }
+    const post = agent.parsePost(input);
+    const root = findRoot(post?.cwd ?? input?.cwd ?? process.cwd());
+    debug(root, maskSensitiveState(raw));
+    return agentPost(post, { root, lang });
+}
+const args = process.argv.slice(2);
+const lang = detectLang();
+const flag = (name) => {
+    const i = args.indexOf(name);
+    return i >= 0 ? args[i + 1] : undefined;
+};
+applyCredentials();
+if (args[0] === '--hook' && args[1]) {
+    try {
+        emit(await runHook(args[1]));
+    }
+    catch (e) {
+        // Fail-open: a crash in the gate must never block a commit or a tool call.
+        if (process.env.CTO_DEBUG === '1')
+            process.stderr.write(String(e?.stack ?? e) + '\n');
+        process.exitCode = 0;
+    }
+}
+else if (args[0] === 'setup') {
+    const uninstall = args.includes('--uninstall');
+    let chosen;
+    const list = flag('--agents');
+    if (list)
+        chosen = list.split(',').map((s) => s.trim()).filter((s) => agentNames.includes(s));
+    else if (!uninstall && process.stdin.isTTY && process.stdout.isTTY && !args.includes('--yes')) {
+        const { ask, close } = terminalAsk();
+        try {
+            chosen = await wizard(ask, lang, detectAgents(), (s) => console.log(s), args.includes('--keys'));
+        }
+        finally {
+            close();
+        }
+    }
+    else if (!uninstall) {
+        chosen = detectAgents();
+    }
+    const r = setup(process.cwd(), lang, { uninstall, agents: chosen });
+    (r.code ? process.stderr : process.stdout).write(r.lines.join('\n') + '\n');
+    process.exitCode = r.code;
+}
+else {
+    process.stderr.write(t(lang, 'usage') + '\n');
+    process.exitCode = args.length ? 1 : 0;
+}

package/dist/masker.js

@@ -0,0 +1,35 @@
+// Egress filter: everything sent to Jev or written to disk passes through here.
+// Masking is not the verdict; Jev still judges leaks from the [REDACTED: TYPE] labels.
+export function maskSensitiveState(raw) {
+    return raw
+        .replace(/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, '[REDACTED: PRIVATE_KEY_BLOCK]')
+        .replace(/\bsk_(live|test)_[A-Za-z0-9_]{16,}/g, '[REDACTED: STRIPE_KEY]')
+        .replace(/\bsk-(proj-)?[A-Za-z0-9_-]{20,}/g, '[REDACTED: OPENAI_KEY]')
+        .replace(/\bAKIA[0-9A-Z]{16}\b/g, '[REDACTED: AWS_ACCESS_KEY]')
+        .replace(/\b(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}/g, '[REDACTED: GITHUB_TOKEN]')
+        .replace(/\bgithub_pat_[A-Za-z0-9_]{22,}/g, '[REDACTED: GITHUB_PAT]')
+        .replace(/\bnpm_[A-Za-z0-9]{36,}/g, '[REDACTED: NPM_TOKEN]')
+        // Lookahead keeps an already-masked value from being masked twice.
+        .replace(/\b(\w*(?:PASSWORD|SECRET|TOKEN|KEY))=(?!\[REDACTED)\S+/gi, '$1=[REDACTED: SENSITIVE_VALUE]');
+}
+const ENV_FILE = /(^|\/)\.env(\.[^/]*)?$/;
+// Added, removed and context lines all carry real values.
+const ENV_LINE = /^([+\- ])(\s*(?:export\s+)?[A-Za-z_][\w.]*\s*=\s*)(\S.*)$/;
+/** Mask a unified diff: every NAME=value line in .env / .env.* files, then the generic patterns. */
+export function maskDiff(diff) {
+    let inEnv = false;
+    const lines = diff.split('\n').map((line) => {
+        if (line.startsWith('diff --git ')) {
+            const m = / b\/(.+)$/.exec(line);
+            inEnv = !!m && ENV_FILE.test(m[1]);
+            return line;
+        }
+        if (inEnv && !line.startsWith('+++') && !line.startsWith('---')) {
+            const m = ENV_LINE.exec(line);
+            if (m)
+                return `${m[1]}${m[2]}[REDACTED: ENV_VALUE]`;
+        }
+        return line;
+    });
+    return maskSensitiveState(lines.join('\n'));
+}

package/dist/setup.js

@@ -0,0 +1,216 @@
+import { execFileSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, relative } from 'node:path';
+import { agentNames, agents, hookCommand } from './agents.js';
+import { DEFAULT_CONFIG } from './brain.js';
+import { t } from './i18n.js';
+const START = '# >>> YOUR CTO JEV START >>>';
+const END = '# <<< YOUR CTO JEV END <<<';
+// Pin the diff format: user config (noprefix, color.diff=always, external diff, textconv) would break parsing and masking.
+export const DIFF_CMD = 'git diff --cached --no-color --no-ext-diff --no-textconv --src-prefix=a/ --dst-prefix=b/';
+const HOOK_BODY = `if command -v cto >/dev/null 2>&1; then\n  ${DIFF_CMD} | cto --hook git-commit || exit 1\nfi\n`;
+const IGNORE_BODY = '.cto-brain.json\n.cto-brain.json.*tmp\ndebug_stdin.json\n';
+const OURS = (cmd) => typeof cmd === 'string' && cmd.startsWith('cto --hook ');
+const block = (body) => `${START}\n${body}${END}\n`;
+const blockRe = /\n?# >>> YOUR CTO JEV START >>>\n[\s\S]*?# <<< YOUR CTO JEV END <<<\n?/;
+export function removeBlock(content) {
+    return content.replace(blockRe, (m) => (m.startsWith('\n') && m.endsWith('\n') ? '\n' : ''));
+}
+export function appendBlock(content, body) {
+    const base = removeBlock(content);
+    return (base && !base.endsWith('\n') ? base + '\n' : base) + block(body);
+}
+/** An exit 0 outside our block means the appended block never runs. */
+export function hasEarlyExit(content) {
+    return /^\s*exit\s+0\b/m.test(removeBlock(content));
+}
+const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+/** Hooks dir honoring core.hooksPath (via --git-path). Husky's generated .husky/_ is replaced on install, so use .husky. */
+export function hooksDir(root) {
+    const dir = git(root, 'rev-parse', '--path-format=absolute', '--git-path', 'hooks');
+    return basename(dir) === '_' && basename(dirname(dir)) === '.husky' ? dirname(dir) : dir;
+}
+/** Agents whose home config dir exists. */
+export function detectAgents(home = homedir()) {
+    return agentNames.filter((n) => existsSync(join(home, agents[n].homeDir)));
+}
+function readSettings(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/** Settings must be an object; the hook events cto writes must be arrays if present. Checked before anything is written. */
+function validShape(json, name) {
+    if (!isObj(json))
+        return false;
+    if (json.hooks === undefined)
+        return true;
+    if (!isObj(json.hooks))
+        return false;
+    const a = agents[name];
+    return [a.pre, a.post].every((spec) => !spec || json.hooks[spec.event] === undefined || Array.isArray(json.hooks[spec.event]));
+}
+function writeOrRemove(path, settings) {
+    const meaningful = Object.keys(settings).filter((k) => k !== 'version');
+    if (meaningful.length)
+        return writeFileSync(path, JSON.stringify(settings, null, 2) + '\n');
+    unlinkSync(path);
+    try {
+        if (!readdirSync(dirname(path)).length)
+            rmdirSync(dirname(path));
+    }
+    catch { /* keep dir */ }
+}
+function installAgent(settings, name) {
+    const a = agents[name];
+    settings.hooks ??= {};
+    if (a.style === 'cursor')
+        settings.version ??= 1;
+    for (const phase of ['pre', 'post']) {
+        const spec = a[phase];
+        if (!spec)
+            continue;
+        const command = hookCommand(name, phase);
+        const arr = (settings.hooks[spec.event] ??= []);
+        if (a.style === 'cursor') {
+            if (!arr.some((h) => h?.command === command))
+                arr.push({ command });
+        }
+        else if (!arr.some((m) => m?.hooks?.some((h) => h?.command === command))) {
+            arr.push({ ...(spec.matcher && { matcher: spec.matcher }), hooks: [{ type: 'command', command }] });
+        }
+    }
+}
+/** Remove every cto hook from a settings object (both styles). Returns whether anything changed. */
+function uninstallHooks(settings) {
+    if (!settings.hooks || typeof settings.hooks !== 'object')
+        return false;
+    let touched = false;
+    for (const [event, arr] of Object.entries(settings.hooks)) {
+        if (!Array.isArray(arr))
+            continue;
+        const kept = arr.flatMap((m) => {
+            if (OURS(m?.command)) {
+                touched = true;
+                return [];
+            } // cursor style
+            if (!Array.isArray(m?.hooks) || !m.hooks.some((h) => OURS(h?.command)))
+                return [m];
+            touched = true;
+            const hooks = m.hooks.filter((h) => !OURS(h?.command));
+            return hooks.length ? [{ ...m, hooks }] : [];
+        });
+        if (kept.length)
+            settings.hooks[event] = kept;
+        else
+            delete settings.hooks[event];
+    }
+    if (touched && !Object.keys(settings.hooks).length)
+        delete settings.hooks;
+    return touched;
+}
+export function setup(cwd, lang, opts = {}) {
+    const lines = [];
+    let root;
+    try {
+        root = git(cwd, 'rev-parse', '--show-toplevel');
+    }
+    catch {
+        return { code: 1, lines: [t(lang, 'setup_not_git')] };
+    }
+    const rel = (p) => relative(root, p) || p;
+    // Validate every config file we may touch before writing anything.
+    const targets = opts.uninstall ? agentNames : (opts.agents ?? []);
+    const settings = new Map();
+    for (const name of targets) {
+        const path = join(root, agents[name].settings);
+        const json = readSettings(path);
+        if (json === null || !validShape(json, name))
+            return { code: 1, lines: [t(lang, 'setup_bad_json', { path: rel(path) })] };
+        settings.set(name, { path, json });
+    }
+    const hookPath = join(hooksDir(root), 'pre-commit');
+    const ignorePath = join(root, '.gitignore');
+    if (opts.uninstall) {
+        if (existsSync(hookPath)) {
+            const c = readFileSync(hookPath, 'utf8');
+            if (blockRe.test(c)) {
+                const rest = removeBlock(c);
+                if (!rest.trim() || rest.trim() === '#!/bin/sh')
+                    unlinkSync(hookPath);
+                else
+                    writeFileSync(hookPath, rest);
+                lines.push(t(lang, 'uninstall_hook', { path: rel(hookPath) }));
+            }
+        }
+        for (const [name, { path, json }] of settings) {
+            if (!existsSync(path) || !uninstallHooks(json))
+                continue;
+            writeOrRemove(path, json);
+            lines.push(t(lang, 'uninstall_agent', { label: agents[name].label, path: rel(path) }));
+        }
+        if (existsSync(ignorePath)) {
+            const c = readFileSync(ignorePath, 'utf8');
+            if (blockRe.test(c)) {
+                const rest = removeBlock(c);
+                if (rest.trim())
+                    writeFileSync(ignorePath, rest);
+                else
+                    unlinkSync(ignorePath);
+                lines.push(t(lang, 'uninstall_gitignore'));
+            }
+        }
+        lines.push(t(lang, 'uninstall_done'));
+        return { code: 0, lines };
+    }
+    // 1. git pre-commit: covers every agent and humans alike. Append a marked block, never overwrite.
+    if (existsSync(hookPath)) {
+        const c = readFileSync(hookPath, 'utf8');
+        writeFileSync(hookPath, appendBlock(c, HOOK_BODY));
+        if (hasEarlyExit(c))
+            lines.push(t(lang, 'setup_hook_exit', { path: rel(hookPath) }));
+    }
+    else {
+        mkdirSync(dirname(hookPath), { recursive: true });
+        writeFileSync(hookPath, '#!/bin/sh\n' + block(HOOK_BODY));
+    }
+    chmodSync(hookPath, 0o755);
+    lines.push(t(lang, 'setup_hook', { path: rel(hookPath) }));
+    // 2. Agent hooks: merge, keep everything else.
+    for (const [name, { path, json }] of settings) {
+        installAgent(json, name);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(json, null, 2) + '\n');
+        lines.push(t(lang, 'setup_agent', { label: agents[name].label, path: rel(path) }));
+        const note = agents[name].note;
+        if (note)
+            lines.push(t(lang, note));
+    }
+    // 3. .gitignore block.
+    writeFileSync(ignorePath, appendBlock(existsSync(ignorePath) ? readFileSync(ignorePath, 'utf8') : '', IGNORE_BODY));
+    lines.push(t(lang, 'setup_gitignore'));
+    // 4. Shared config, created once and never removed.
+    const cfgPath = join(root, '.cto.json');
+    let goal = '';
+    if (!existsSync(cfgPath)) {
+        writeFileSync(cfgPath, JSON.stringify(DEFAULT_CONFIG, null, 2) + '\n');
+        lines.push(t(lang, 'setup_config'));
+    }
+    else {
+        try {
+            goal = JSON.parse(readFileSync(cfgPath, 'utf8')).sprint_goal ?? '';
+        }
+        catch { /* keep empty */ }
+    }
+    if (!String(goal).trim())
+        lines.push(t(lang, 'setup_sprint'));
+    lines.push(t(lang, 'setup_done'));
+    return { code: 0, lines };
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};