your-cto-jev 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rainday
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# your-cto-jev
+
+**A sharp-tongued CTO that reviews what your AI coding agent is about to do, and says no.**
+
+`cto` hooks into `git commit` and into the shell tool of Claude Code, Cursor, Gemini CLI and Codex. Before a commit lands or a command runs, it asks [TypeSafe Jev](https://developers.cloudflare.com/ai/models/typesafe/jev/), a typed decision model, a few yes/no questions. Then it blocks, warns, or stays completely silent.
+
+```text
+$ git commit -m "add payments"
+[cto] Nice one, genius. You almost pushed a secret into Git. Commit BLOCKED. Remove it.
+      credential_leak = 0.94 (threshold > 0.5)
+
+# Claude Code tries: rm -rf ~
+[cto] Hold it. This command is irreversibly destructive. Not running it.
+      destructive_command = 0.96 (threshold > 0.7)
+
+# Same build fails twice, agent tries the exact same thing again
+[cto] Same error again. You are looping and burning tokens. This tool call is BLOCKED. Fix the logic first.
+      infinite_loop = 0.95 (threshold > 0.85)
+```
+
+Messages come in English or 繁體中文, picked from your locale.
+
+## Why
+
+Coding agents move fast and occasionally do something you would never approve: commit an API key, `rm -rf` the wrong directory, force-push over a shared branch, or retry the same failing command until your token budget is gone. Regex scanners catch some of this, but they cannot tell a real key from a placeholder, or a cleanup from a disaster.
+
+Jev judges meaning and answers with probabilities, not prose. It costs about $0.00002 per check and answered in about 250 ms (p95 about 330 ms) in our tests. `cto` adds the hooks, the thresholds and the attitude.
+
+## What it checks
+
+| Signal | Where | What happens |
+|---|---|---|
+| `credential_leak` | every `git commit` | **Blocks** the commit |
+| `destructive_command` | every agent shell command | **Blocks** the command |
+| `infinite_loop` | agent shell commands, after a recent failure | **Blocks** the command |
+| `architecture_violation` | `git commit`, once you set a sprint goal | Warns only |
+| `code_complexity` | every `git commit` | Warns only |
+
+Architecture and complexity only warn on purpose. They are subjective, and a gate that blocks too often teaches people to use `git commit --no-verify`, which switches off the secret check too.
+
+When nothing crosses a threshold, `cto` prints nothing at all.
+
+## How it works
+
+```mermaid
+flowchart TD
+    A["git commit"] --> B["Staged diff<br/>minus lock files, minified files, maps, binaries<br/>split into ~24k-token chunks"]
+    C["Agent shell command<br/>Claude Code · Cursor · Gemini CLI · Codex"] --> D["Command + failures from the last 15 min"]
+    E["Agent command failed"] --> F[("Error recorded locally<br/>no API call")]
+    F -.-> D
+    B --> M["Mask secrets<br/>keys, tokens, .env values"]
+    D --> M
+    M --> P1{"Cloudflare<br/>Workers AI"}
+    P1 -- "answers" --> J{"Jev scores vs<br/>.cto.json thresholds"}
+    P1 -- "error, cooling down or no key" --> P2{"OpenRouter"}
+    P2 -- "answers" --> J
+    P2 -- "error or no key" --> O["Fail open<br/>let it through"]
+    J -- "secret, destructive or loop" --> X["BLOCK<br/>commit exit 1 · tool call exit 2"]
+    J -- "complex or off the sprint goal" --> W["Warn, then allow"]
+    J -- "nothing crosses" --> S["Allow silently"]
+```
+
+A provider that fails is skipped for 5 minutes after a timeout, `429` or `5xx`, or for 1 hour after an auth or billing error, then retried. A `400` means the request itself is wrong, so `cto` fails open without trying the other provider.
+
+## Quick start
+
+Requires Node.js 22 or newer.
+
+```sh
+npm install -g your-cto-jev
+cd your-project
+cto setup
+```
+
+Run the same install command again to update.
+
+`cto setup` walks you through it in the terminal:
+
+```text
+Which coding agents should get command interception?
+  Claude Code (detected) [Y/n]
+  Cursor (detected) [Y/n]
+  Gemini CLI [y/N]
+  Codex CLI (detected) [Y/n]
+
+Set up a Jev API key (at least one; press Enter to skip).
+  OpenRouter API key: ********
+  Verifying OpenRouter with one real request...
+  OpenRouter OK
+```
+
+Then restart your agent session so it picks up the new hooks.
+
+Other forms:
+
+```sh
+cto setup --agents claude,cursor --yes   # non-interactive (scripts, CI)
+cto setup --keys                         # change keys later
+cto setup --uninstall                    # remove every cto hook again
+```
+
+`setup` appends marked blocks and merges JSON. It never overwrites your existing hooks or settings, and `--uninstall` puts them back exactly as they were. It never touches your shell rc files.
+
+## Supported agents
+
+The git pre-commit check is always installed. It protects every agent and every human who commits from that repo.
+
+| Agent | Config written | Command gate | Loop detection |
+|---|---|---|---|
+| Claude Code | `.claude/settings.local.json` | yes | yes |
+| Cursor | `.cursor/hooks.json` | yes | yes |
+| Gemini CLI | `.gemini/settings.json` | yes | yes |
+| Codex CLI | `.codex/hooks.json` | yes | limited: Codex has no failure event |
+
+Claude Code is tested end to end inside the agent. The Cursor, Gemini CLI and Codex adapters follow each agent's official hook docs and are tested with their documented payloads, but have not been run inside those agents yet. Reports welcome.
+
+Codex only runs project hooks after you trust the project. Teammates who have not installed `cto` are never blocked: the git hook checks for `cto` first, and Claude Code, Cursor and Gemini CLI document a failed hook command (other than exit 2) as non-blocking.
+
+## API keys
+
+You need at least one provider:
+
+| Provider | Keys | Notes |
+|---|---|---|
+| [OpenRouter](https://openrouter.ai) | `OPENROUTER_API_KEY` | Easiest way to start |
+| [Cloudflare Workers AI](https://developers.cloudflare.com/ai/models/typesafe/jev/) | `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` | Tried first when set. Your account's default AI Gateway must have **Authenticated Gateway** on and Unified Billing credits, or every call returns `403` |
+
+If the first provider fails, `cto` switches to the next one and tells you once. It retries the first provider later. A missing key, a timeout or an outage never blocks you: `cto` fails open and lets the action through. It only blocks when Jev answers and the answer crosses a threshold.
+
+**Where keys live.** Environment variables win. Otherwise `cto` reads a per-user file that `setup` writes:
+
+- Windows: `%APPDATA%\your-cto-jev\credentials.json`
+- macOS and Linux: `~/.config/your-cto-jev/credentials.json` (mode 600)
+
+The file sits outside every repository, so it cannot be committed. It exists because agents and git clients started from a GUI often never see variables exported in `.zshrc`, and the hook would silently let everything through.
+
+## What leaves your machine
+
+Every check sends text to your chosen provider. `cto` masks it first:
+
+- **For commits:** the staged diff, with lock files, minified files, source maps and binaries removed.
+- **For agent commands:** the command, plus up to five failures from the last 15 minutes when checking for loops.
+- **Always masked:** private key blocks, Stripe, OpenAI, AWS, GitHub and npm tokens, and any `NAME=value` whose name ends in `PASSWORD`, `SECRET`, `TOKEN` or `KEY`. Every value in a `.env` file is masked as well.
+
+Masking only controls what goes out. Jev still sees labels such as `[REDACTED: STRIPE_KEY]`, which is how it knows a real secret was there.
+
+Nothing else is uploaded, and nothing is logged unless you set `CTO_DEBUG=1`. That writes the masked input to `debug_stdin.json`, which `setup` adds to `.gitignore`.
+
+## Configuration
+
+`.cto.json` is shared with the team, so commit it:
+
+```json
+{
+  "sprint_goal": "",
+  "thresholds": {
+    "credential_leak": 0.5,
+    "destructive_command": 0.7,
+    "infinite_loop": 0.85,
+    "architecture_violation": 0.85,
+    "code_complexity": 2
+  }
+}
+```
+
+- **`sprint_goal`**: fill it in to enable the architecture check, for example `"Ship Stripe billing, no new services"`.
+- **Thresholds**: Jev returns a probability from 0 to 1. `code_complexity` is the exception: it is a score from 0 (clean) to 4 (unmaintainable).
+- **Calibration**: in our tests `git push --force` scored about 0.50 for `destructive_command`, so the default lets it through. Lower that threshold to about 0.45 if you want force pushes blocked.
+
+`.cto-brain.json` holds personal runtime state and is gitignored.
+
+| Env var | Purpose |
+|---|---|
+| `CTO_PROVIDER` | Use only `cloudflare` or only `openrouter` |
+| `CTO_FAILOVER=0` | Never switch providers |
+| `CTO_LANG` | `en` or `zh-TW` (default: your locale) |
+| `CTO_DEBUG=1` | Write masked hook input to `debug_stdin.json` |
+
+## Known limitations
+
+- **Git GUIs hide warnings.** VS Code, SourceTree and GitKraken usually hide hook output when the commit succeeds, so the architecture and complexity warnings are invisible there. Blocks still show.
+- **A retry after a fix can look like a loop.** The loop check sees recent failures but not the edits you made since. Failures expire after 15 minutes. Raise `infinite_loop` if it gets in your way.
+- **Each agent shell command waits about half a second** for Node startup plus one Jev request.
+
+## Development
+
+```sh
+git clone https://github.com/rainday/your-cto-jev
+cd your-cto-jev
+npm install
+npm test
+```
+
+The full design, including the measured results behind the defaults, is in [`your-cto-jev-spec.html`](./your-cto-jev-spec.html) (written in 繁體中文).
+
+## License
+
+[MIT](./LICENSE)

package/dist/agents.js

@@ -0,0 +1,90 @@
+// One row per coding agent. The verdict logic is shared; each row only maps the agent's
+// stdin shape, its blocking convention, and where setup writes its hook config.
+const str = (v) => (typeof v === 'string' && v.trim() ? v : undefined);
+const cmdOf = (i) => String(i?.tool_input?.command ?? i?.command ?? '');
+// Claude, Codex and Gemini share this convention: exit 2 + stderr blocks, exit 0 hides stderr so notices go out as systemMessage.
+const exit2Block = (lines) => ({ code: 2, stderr: lines });
+const systemMessage = (msgs) => ({ code: 0, stdout: JSON.stringify({ systemMessage: msgs.join('\n') }), stderr: [] });
+const nestedPre = (i) => ({ command: str(i?.tool_input?.command), sessionId: str(i?.session_id), cwd: str(i?.cwd) });
+/** Pull a non-zero exit out of free-form tool output ("Exit Code: 1", "exit_code": 2, ...). */
+function nonZeroExit(v) {
+    if (v && typeof v === 'object') {
+        const o = v;
+        const code = o.exit_code ?? o.exitCode ?? o['Exit Code'];
+        if (typeof code === 'number' && code !== 0)
+            return str(o.stderr) ?? str(o.output) ?? str(o.stdout) ?? JSON.stringify(o);
+        return undefined;
+    }
+    const s = str(v);
+    return s && /exit[ _]?code:?\s*"?([1-9]\d*)/i.test(s) ? s : undefined;
+}
+export const agents = {
+    claude: {
+        label: 'Claude Code',
+        homeDir: '.claude',
+        settings: '.claude/settings.local.json',
+        style: 'nested',
+        pre: { event: 'PreToolUse', matcher: 'Bash' },
+        post: { event: 'PostToolUseFailure', matcher: 'Bash' },
+        parsePre: nestedPre,
+        parsePost: (i) => (i?.is_interrupt || !str(i?.error) ? null : { command: cmdOf(i), error: i.error, cwd: str(i?.cwd) }),
+        block: exit2Block,
+        notice: systemMessage,
+    },
+    cursor: {
+        label: 'Cursor',
+        homeDir: '.cursor',
+        settings: '.cursor/hooks.json',
+        style: 'cursor',
+        pre: { event: 'beforeShellExecution' },
+        post: { event: 'postToolUseFailure' },
+        parsePre: (i) => ({ command: str(i?.command), sessionId: str(i?.conversation_id), cwd: str(i?.cwd) ?? str(i?.workspace_roots?.[0]) }),
+        parsePost: (i) => i?.tool_name !== 'Shell' || i?.is_interrupt || !str(i?.error_message)
+            ? null
+            : { command: cmdOf(i), error: i.error_message, cwd: str(i?.cwd) ?? str(i?.workspace_roots?.[0]) },
+        // Both documented block paths at once: exit 2 and permission "deny".
+        block: (lines) => ({
+            code: 2,
+            stdout: JSON.stringify({ permission: 'deny', user_message: lines.join('\n'), agent_message: lines.join('\n') }),
+            stderr: lines,
+        }),
+        notice: (msgs) => ({ code: 0, stdout: JSON.stringify({ permission: 'allow', user_message: msgs.join('\n') }), stderr: [] }),
+    },
+    gemini: {
+        label: 'Gemini CLI',
+        homeDir: '.gemini',
+        settings: '.gemini/settings.json',
+        style: 'nested',
+        pre: { event: 'BeforeTool', matcher: 'run_shell_command' },
+        post: { event: 'AfterTool', matcher: 'run_shell_command' },
+        parsePre: nestedPre,
+        parsePost: (i) => {
+            if (i?.tool_name !== 'run_shell_command')
+                return null;
+            const r = i?.tool_response;
+            const err = str(r?.error) ?? str(r?.error?.message) ?? nonZeroExit(r?.llmContent);
+            return err ? { command: cmdOf(i), error: err, cwd: str(i?.cwd) } : null;
+        },
+        block: exit2Block,
+        notice: systemMessage,
+    },
+    codex: {
+        label: 'Codex CLI',
+        homeDir: '.codex',
+        settings: '.codex/hooks.json',
+        style: 'nested',
+        pre: { event: 'PreToolUse', matcher: 'Bash' },
+        // Codex has no failure event; PostToolUse is recorded only when its output shows a non-zero exit.
+        post: { event: 'PostToolUse', matcher: 'Bash' },
+        note: 'note_codex_trust',
+        parsePre: nestedPre,
+        parsePost: (i) => {
+            const err = nonZeroExit(i?.tool_response);
+            return err ? { command: cmdOf(i), error: err, cwd: str(i?.cwd) } : null;
+        },
+        block: exit2Block,
+        notice: systemMessage,
+    },
+};
+export const agentNames = Object.keys(agents);
+export const hookCommand = (agent, phase) => `cto --hook ${agent}-${phase}`;

package/dist/api.js

@@ -0,0 +1,123 @@
+import { t } from './i18n.js';
+import { maskSensitiveState } from './masker.js';
+const env = process.env;
+const HOUR = 3_600_000;
+const FIVE_MIN = 300_000;
+// One row per provider. Same questions/answers schema everywhere; only URL, auth and body wrapping differ.
+export const providers = {
+    cloudflare: {
+        label: 'Cloudflare',
+        enabled: () => !!(env.CLOUDFLARE_API_TOKEN && env.CLOUDFLARE_ACCOUNT_ID),
+        url: () => `https://api.cloudflare.com/client/v4/accounts/${env.CLOUDFLARE_ACCOUNT_ID}/ai/run`,
+        headers: () => ({ Authorization: `Bearer ${env.CLOUDFLARE_API_TOKEN}` }),
+        // Cloudflare rejects session_id inside input with a 400 (verified), so it is OpenRouter-only.
+        body: ({ session_id: _, ...input }) => ({ model: 'typesafe/jev', input }),
+    },
+    openrouter: {
+        label: 'OpenRouter',
+        enabled: () => !!env.OPENROUTER_API_KEY,
+        url: () => 'https://openrouter.ai/api/alpha/decisions',
+        headers: () => ({ Authorization: `Bearer ${env.OPENROUTER_API_KEY}` }),
+        body: (req) => ({ model: 'typesafe/jev-1.13', ...req }),
+    },
+};
+/** Ordered provider names honoring CTO_PROVIDER. */
+export function providerOrder() {
+    const order = env.CTO_PROVIDER ? [env.CTO_PROVIDER] : Object.keys(providers);
+    return order.filter((n) => providers[n]?.enabled());
+}
+async function callOnce(name, req, timeoutMs) {
+    const p = providers[name];
+    try {
+        const res = await fetch(p.url(), {
+            method: 'POST',
+            headers: { ...p.headers(), 'Content-Type': 'application/json' },
+            body: JSON.stringify(p.body(req)),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        const text = await res.text();
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch { /* handled below */ }
+        if (!res.ok) {
+            const s = res.status;
+            const message = maskSensitiveState(String(json?.error?.message ?? json?.errors?.[0]?.message ?? text).slice(0, 200));
+            if (s === 402)
+                return { ok: false, kind: 'persistent', status: '402', reason: 'reason_402', message };
+            if (s === 401 || s === 403)
+                return { ok: false, kind: 'persistent', status: String(s), reason: 'reason_auth', message };
+            if (s === 400 || s === 422)
+                return { ok: false, kind: 'request', status: String(s), reason: 'bad_request', message };
+            if (s === 429)
+                return { ok: false, kind: 'transient', status: '429', reason: 'reason_429', message };
+            return { ok: false, kind: 'transient', status: String(s), reason: 'reason_5xx', message };
+        }
+        // Cloudflare docs say unwrapped; tolerate a {success, result} envelope anyway.
+        const out = json?.result?.answers ? json.result : json;
+        if (!out?.answers || typeof out.answers !== 'object') {
+            return { ok: false, kind: 'transient', status: String(res.status), reason: 'reason_bad_response' };
+        }
+        return { ok: true, answers: out.answers };
+    }
+    catch (e) {
+        const timeout = e?.name === 'TimeoutError' || e?.name === 'AbortError';
+        return { ok: false, kind: 'transient', status: timeout ? 'timeout' : 'network', reason: timeout ? 'reason_timeout' : 'reason_network' };
+    }
+}
+/** One tiny real request to check a key during setup. */
+export async function probeProvider(name) {
+    const r = await callOnce(name, {
+        state: 'echo hello',
+        questions: { probe: { type: 'noul', instructions: 'Is this a shell command?', criteria: { true: 'Yes', false: 'No' } } },
+    }, 15_000);
+    return r.ok ? { ok: true } : { ok: false, status: r.status, message: r.message };
+}
+/**
+ * Try providers in order, skipping cooled-down ones. Persistent errors cool 1h, transient 5m,
+ * a 400 stops without failover. Every failure path is fail-open for the caller.
+ * Notices are only added on state changes: switch away, switch back, fail-open.
+ */
+export async function evaluate(req, ctx) {
+    const { brain, lang, notices } = ctx;
+    const now = ctx.now ?? Date.now;
+    const enabled = providerOrder();
+    if (!enabled.length)
+        return { ok: false, reason: 'no_keys' };
+    const candidates = env.CTO_FAILOVER === '0' ? enabled.slice(0, 1) : enabled;
+    let lastFail;
+    for (const name of candidates) {
+        const cd = brain.provider_cooldown[name];
+        if (cd && cd.until > now())
+            continue;
+        const r = await callOnce(name, req, ctx.timeoutMs);
+        if (r.ok) {
+            if (cd) {
+                delete brain.provider_cooldown[name];
+                notices.add(t(lang, 'recovered', { name: providers[name].label }));
+            }
+            if (lastFail) {
+                brain.failover_count++;
+                notices.add(t(lang, 'switched', {
+                    from: providers[lastFail.name].label, reason: t(lang, lastFail.reason), status: lastFail.status,
+                    dur: t(lang, lastFail.dur), to: providers[name].label,
+                }));
+            }
+            return { ok: true, provider: name, answers: r.answers };
+        }
+        if (r.kind === 'request') {
+            notices.add(t(lang, 'bad_request', { msg: r.message ?? '' }));
+            return { ok: false, reason: 'bad_request' };
+        }
+        const dur = r.kind === 'persistent' ? 'dur_1h' : 'dur_5m';
+        brain.provider_cooldown[name] = { until: now() + (r.kind === 'persistent' ? HOUR : FIVE_MIN), status: r.status };
+        lastFail = { name, status: r.status, reason: r.reason, dur };
+    }
+    if (lastFail) {
+        notices.add(t(lang, 'fail_open', {
+            detail: t(lang, 'fail_open_detail', { from: providers[lastFail.name].label, reason: t(lang, lastFail.reason), status: lastFail.status }),
+        }));
+    }
+    return { ok: false, reason: 'all_failed' };
+}

package/dist/brain.js

@@ -0,0 +1,100 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export const DEFAULT_CONFIG = {
+    sprint_goal: '',
+    thresholds: {
+        credential_leak: 0.5,
+        destructive_command: 0.7,
+        infinite_loop: 0.85,
+        architecture_violation: 0.85,
+        code_complexity: 2,
+    },
+};
+const emptyBrain = () => ({
+    recent_errors: [],
+    blocked_attempts: 0,
+    skipped_attempts: 0,
+    failover_count: 0,
+    provider_cooldown: {},
+    notified_sessions: [],
+});
+/** Nearest ancestor holding .cto.json or .git; falls back to start. No git spawn. */
+export function findRoot(start = process.cwd()) {
+    let dir = start;
+    for (;;) {
+        if (existsSync(join(dir, '.cto.json')) || existsSync(join(dir, '.git')))
+            return dir;
+        const up = dirname(dir);
+        if (up === dir)
+            return start;
+        dir = up;
+    }
+}
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function loadConfig(root) {
+    const raw = readJson(join(root, '.cto.json')) ?? {};
+    return {
+        sprint_goal: typeof raw.sprint_goal === 'string' ? raw.sprint_goal : '',
+        thresholds: { ...DEFAULT_CONFIG.thresholds, ...(raw.thresholds ?? {}) },
+    };
+}
+/** Corrupt or missing state rebuilds as empty: the gate must never crash on its own bookkeeping. */
+export function loadBrain(root) {
+    const raw = readJson(join(root, '.cto-brain.json'));
+    return raw && typeof raw === 'object' ? { ...emptyBrain(), ...raw } : emptyBrain();
+}
+// ---------- user-level credentials ----------
+// GUI-launched agents and git clients often do not inherit shell env vars, so keys set in .zshrc
+// never reach the hook. A per-user file outside every repo fixes that without touching rc files.
+export const CREDENTIAL_KEYS = ['CLOUDFLARE_API_TOKEN', 'CLOUDFLARE_ACCOUNT_ID', 'OPENROUTER_API_KEY'];
+export function credentialsPath(env = process.env) {
+    const base = env.APPDATA ?? env.XDG_CONFIG_HOME ?? join(homedir(), '.config');
+    return join(base, 'your-cto-jev', 'credentials.json');
+}
+export function loadCredentials() {
+    const raw = readJson(credentialsPath()) ?? {};
+    return Object.fromEntries(CREDENTIAL_KEYS.filter((k) => typeof raw[k] === 'string' && raw[k]).map((k) => [k, raw[k]]));
+}
+/** Env vars win; the file only fills what is missing. */
+export function applyCredentials(env = process.env) {
+    for (const [k, v] of Object.entries(loadCredentials()))
+        if (!env[k])
+            env[k] = v;
+}
+export function saveCredentials(c) {
+    const path = credentialsPath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(c, null, 2) + '\n', { mode: 0o600 });
+    return path;
+}
+/**
+ * Atomic write via per-process tmp + rename. No file lock (spec section 7): parallel hooks race, last write wins.
+ * Never throws: losing bookkeeping is fine, but an exception here would turn a block into a fail-open pass.
+ */
+export function saveBrain(root, brain) {
+    const path = join(root, '.cto-brain.json');
+    const tmp = `${path}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tmp, JSON.stringify(brain, null, 2) + '\n');
+        renameSync(tmp, path);
+    }
+    catch {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { /* nothing to clean */ }
+    }
+}
+/** Failures older than this are history, not a loop. */
+export const RECENT_ERROR_WINDOW_MS = 15 * 60_000;
+export function freshErrors(brain, now = Date.now()) {
+    return brain.recent_errors.filter((e) => now - Date.parse(e.at) < RECENT_ERROR_WINDOW_MS);
+}

package/dist/diff.js

@@ -0,0 +1,66 @@
+// Large diff handling (spec section 6): filter noise, then chunk by file.
+const EXCLUDE = /(^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock)$|\.min\.js$|\.map$/;
+export const CHUNK_TOKENS = 24_000;
+/** ~1 token per CJK char, ~4 chars per token otherwise. */
+export function estimateTokens(s) {
+    const cjk = s.match(/[　-鿿가-힯豈-﫿＀-￯]/g)?.length ?? 0;
+    return cjk + Math.ceil((s.length - cjk) / 4);
+}
+export function splitFiles(diff) {
+    return diff.split(/^(?=diff --git )/m).filter((s) => s.trim());
+}
+export function filterDiff(diff) {
+    return splitFiles(diff).filter((section) => {
+        const m = /^diff --git a\/.+? b\/(.+)$/m.exec(section);
+        if (m && EXCLUDE.test(m[1]))
+            return false;
+        return !/^(Binary files .* differ|GIT binary patch)$/m.test(section);
+    });
+}
+/** Greedy pack of file sections into chunks. A single oversized file is split by lines: no sampling. */
+export function chunkDiff(files, limit = CHUNK_TOKENS) {
+    const pieces = [];
+    for (const f of files) {
+        if (estimateTokens(f) <= limit) {
+            pieces.push(f);
+            continue;
+        }
+        // Repeat the file header on every piece so Jev always knows which file (.env vs .env.example) it sees.
+        const [header, ...rest] = f.split('\n');
+        let buf = header + '\n';
+        for (const line of rest) {
+            if (buf !== header + '\n' && estimateTokens(buf + line) > limit) {
+                pieces.push(buf);
+                buf = header + '\n';
+            }
+            buf += line + '\n';
+        }
+        if (buf)
+            pieces.push(buf);
+    }
+    const chunks = [];
+    let cur = '';
+    for (const p of pieces) {
+        if (cur && estimateTokens(cur + p) > limit) {
+            chunks.push(cur);
+            cur = '';
+        }
+        cur += p;
+    }
+    if (cur)
+        chunks.push(cur);
+    return chunks;
+}
+/** Run tasks with at most `limit` in flight. */
+export async function pool(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const i = next++;
+            out[i] = await fn(items[i], i);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return out;
+}