codeep 2.6.0 → 2.7.0

package/README.md

@@ -217,12 +217,32 @@ AI-powered review of your git diff with `/review`:
 
 If there are no git changes, falls back to static analysis automatically.
 
-#### Custom rules (`.codeep/review.json`)
+#### Custom rules (`.codeep/review.yml` or `.codeep/review.json`)
 
 The static reviewer (`codeep review` / `/review --static`) ships a set of
-built-in rules, but a project can tailor them — check a `.codeep/review.json`
-into the repo and the CLI **and** the [Codeep GitHub Action](https://github.com/VladoIvankovic/codeep-action)
-both pick it up automatically (zero LLM cost):
+built-in rules, but a project can tailor them — check a `.codeep/review.yml`
+(or `.codeep/review.json`) into the repo and the CLI **and** the
+[Codeep GitHub Action](https://github.com/VladoIvankovic/codeep-action) both
+pick it up automatically (zero LLM cost). YAML is preferred when present and is
+nicer for regexes — single-quoted YAML keeps backslashes literal
+(`pattern: '\bfoo\('`) so you avoid JSON's double-escaping:
+
+```yaml
+# .codeep/review.yml
+rules:
+  - id: no-internal-import
+    pattern: "from ['\"]@acme/internal"
+    category: best-practice
+    severity: error
+    message: Don't import from @acme/internal outside the platform team
+    suggestion: Use the public @acme/sdk package
+    extensions: [.ts, .tsx]
+disable: [todo-comment, anonymous-function]
+include: ['src/**']
+exclude: ['**/*.test.ts', 'vendor/**']
+```
+
+The same config as JSON:
 
 ```json
 {
@@ -246,14 +266,28 @@ both pick it up automatically (zero LLM cost):
 - **`rules`** — your own checks. `id`, `pattern` (a regex string), and `message`
   are required; `flags` (default `g`), `category`, `severity`
   (`error|warning|info|suggestion`), `suggestion`, and `extensions` are optional.
-- **`disable`** — turn off built-in rules by id (e.g. `eval-usage`,
-  `hardcoded-password`, `todo-comment`, `any-type`, `console-statement`,
-  `long-file`, `long-function`, …).
+- **`disable`** — turn off built-in rules by id. Run `codeep review --rules` for
+  the live list; the built-in ids are: `eval-usage`, `inner-html`,
+  `dangerously-set-inner-html`, `hardcoded-password`, `hardcoded-api-key`,
+  `foreach-await`, `await-in-loop`, `select-star`, `loose-null-check`,
+  `empty-catch`, `console-statement`, `todo-comment`, `any-type`, `ts-ignore`,
+  `as-any`, `var-usage`, `anonymous-function`, `missing-jsdoc`, `long-file`,
+  `long-function`.
 - **`include` / `exclude`** — glob scoping (`**`, `*`, `?`); `include` empty = all files.
 
 A missing, malformed, or partially-invalid config never breaks a review — bad
 entries are skipped and the run proceeds with whatever is valid.
 
+**More review commands:**
+- `codeep review --rules` — list the built-in rule ids (above) and exit.
+- `codeep review --ai` — after the offline pass, get an advisory AI second
+  opinion on the working-tree diff from your configured provider (needs an API
+  key; never changes the exit code, so CI stays deterministic).
+- `codeep hook install` — install a git pre-commit hook that reviews the
+  working-tree content of your staged files and blocks the commit on failures
+  (`--pre-push` for pre-push, `--fail-on <level>` to set the threshold,
+  `codeep hook uninstall` to remove). Stage changes fully before committing.
+
 ### Interactive Mode
 Agent asks clarifying questions when tasks are ambiguous:
 ```

package/dist/acp/server.js

@@ -973,11 +973,10 @@ export function startAcpServer() {
             });
         };
         resetTokenTracking();
-        // In manual mode, confirm write/edit operations
-        const prevConfirmWrite = config.get('agentConfirmWriteFile');
-        if (session.currentModeId === 'manual') {
-            config.set('agentConfirmWriteFile', true);
-        }
+        // Manual mode gates write/edit for THIS run via a per-call option passed to
+        // runAgentSession (extraDangerousTools, below) — NOT by mutating the global
+        // `agentConfirmWriteFile` config, which leaked the session's mode into the
+        // TUI/other processes and raced on a non-atomic restore.
         const agentResponseChunks = [];
         const sendChunk = (text) => {
             agentResponseChunks.push(text);
@@ -1083,6 +1082,9 @@ export function startAcpServer() {
                         }
                     }
                 },
+                // Manual mode gates write_file/edit_file for this run only (per-call,
+                // no global config mutation).
+                extraDangerousTools: session.currentModeId === 'manual' ? ['write_file', 'edit_file'] : undefined,
                 // Only request permission in Manual mode
                 onRequestPermission: session.currentModeId === 'manual'
                     ? async (toolCall) => {
@@ -1183,7 +1185,6 @@ export function startAcpServer() {
                 if (agentResponse) {
                     session.history.push({ role: 'assistant', content: agentResponse });
                 }
-                config.set('agentConfirmWriteFile', prevConfirmWrite);
                 autoSaveSession(session.history, session.workspaceRoot);
                 // Report token usage to dashboard
                 const projectCtx = getProjectContext(session.workspaceRoot);
@@ -1247,7 +1248,6 @@ export function startAcpServer() {
                     transport.error(msg.id, -32000, err.message);
                 }
             }).finally(() => {
-                config.set('agentConfirmWriteFile', prevConfirmWrite);
                 if (session)
                     session.abortController = null;
                 planEntries.clear();

package/dist/acp/session.d.ts

@@ -11,6 +11,8 @@ export interface AgentSessionOptions {
     onThought?: (text: string) => void;
     onToolCall?: (toolCallId: string, toolName: string, kind: string, title: string, status: 'pending' | 'running' | 'finished' | 'error', locations?: string[], rawOutput?: string) => void;
     onRequestPermission?: (toolCall: ToolCall) => Promise<PermissionOutcome>;
+    /** Tools to force into the per-run dangerous set (ACP manual mode). */
+    extraDangerousTools?: string[];
     onExecuteCommand?: (command: string, args: string[], cwd: string) => Promise<{
         stdout: string;
         stderr: string;

package/dist/acp/session.js

@@ -145,6 +145,7 @@ export async function runAgentSession(opts) {
             }
         },
         onRequestPermission: opts.onRequestPermission,
+        extraDangerousTools: opts.extraDangerousTools,
         onExecuteCommand: opts.onExecuteCommand,
         fs: opts.fs,
         // Route MCP-prefixed tool calls through the per-session registry.

package/dist/config/index.d.ts

@@ -96,6 +96,10 @@ interface ConfigSchema {
     /** True once legacy plaintext keys (providerApiKeys / apiKey) have been
      *  migrated into secure storage and wiped from the config file. */
     keysSecured: boolean;
+    /** Plaintext fallback key map used by utils/keychain.ts ONLY when the OS
+     *  keychain is unavailable. Swept into the keychain once it becomes available
+     *  (see sweepFallbackKeysToKeychain). Empty {} on keychain-capable systems. */
+    apiKeys?: Record<string, string>;
     /** Master switch for automatic cloud uploads (usage stats, session
      *  transcripts, progress, memory notes). Default true; set false to opt out.
      *  The CODEEP_NO_TELEMETRY / DO_NOT_TRACK env vars also force it off. */

package/dist/config/index.js

@@ -186,6 +186,7 @@ function createConfig() {
         providerApiKeys: [],
         configuredProviderIds: [],
         keysSecured: false,
+        apiKeys: {},
         telemetry: true,
         githubId: '',
         githubUsername: '',
@@ -359,6 +360,44 @@ async function migrateKeysToSecureStorage() {
         _migrationPromise = null;
     }
 }
+let _sweepPromise = null;
+/**
+ * If the OS keychain is now available but API keys are still sitting in the
+ * plaintext `apiKeys` fallback map (written by utils/keychain.ts while the
+ * keychain was unavailable on a prior run), move each into the keychain. The
+ * keychain write also deletes the entry from the plaintext fallback map, so a
+ * successful sweep leaves no plaintext behind. Cheap no-op when the map is
+ * empty or the keychain is unavailable; deduped for concurrent callers. Runs
+ * independently of `keysSecured` so a key written during a keychain outage is
+ * still swept up later.
+ */
+async function sweepFallbackKeysToKeychain() {
+    if (!_sweepPromise) {
+        _sweepPromise = (async () => {
+            const store = secureKeyStore();
+            // Only sweep when the keychain is actually usable; otherwise leave the
+            // plaintext fallback in place (there's nowhere safer to move it).
+            if (!store.isKeychainAvailable || !(await store.isKeychainAvailable()))
+                return;
+            const plaintext = config.get('apiKeys') || {};
+            for (const [providerId, apiKey] of Object.entries(plaintext)) {
+                if (typeof apiKey !== 'string' || !apiKey)
+                    continue;
+                try {
+                    await store.setApiKey(providerId, apiKey); // writes keychain + deletes from fallback map
+                    addConfiguredProviderId(providerId);
+                }
+                catch { /* keep the plaintext entry on failure — never lose a key */ }
+            }
+        })();
+    }
+    try {
+        await _sweepPromise;
+    }
+    finally {
+        _sweepPromise = null;
+    }
+}
 export const LANGUAGES = {
     'auto': 'Auto-detect',
     'en': 'English',
@@ -417,9 +456,11 @@ export async function loadApiKey(providerId) {
  * Should be called at app startup
  */
 export async function loadAllApiKeys() {
-    // Migrate any legacy plaintext keys, then load all from secure storage using
-    // the non-secret configuredProviderIds index (no need to probe every provider).
+    // Migrate any legacy plaintext keys, then sweep any keychain-fallback plaintext
+    // up into the keychain (no-op when none / keychain unavailable), then load all
+    // from secure storage using the non-secret configuredProviderIds index.
     await migrateKeysToSecureStorage();
+    await sweepFallbackKeysToKeychain();
     const store = secureKeyStore();
     for (const providerId of (config.get('configuredProviderIds') || [])) {
         const key = await store.getApiKey(providerId);

package/dist/renderer/main.js

@@ -387,7 +387,11 @@ async function main() {
     // the review usage rather than the top-level help.
     if (args[0] === 'review') {
         const { runHeadlessReview } = await import('../utils/headlessReview.js');
-        process.exit(runHeadlessReview(args.slice(1)));
+        process.exit(await runHeadlessReview(args.slice(1)));
+    }
+    if (args[0] === 'hook') {
+        const { runHookCommand } = await import('../utils/gitHookInstaller.js');
+        process.exit(runHookCommand(args.slice(1)));
     }
     if (args.includes('--version') || args.includes('-v')) {
         console.log(`Codeep v${getCurrentVersion()}`);
@@ -403,7 +407,9 @@ Usage:
   codeep account sync   Pull keys + personalities + commands + profile from codeep.dev
   codeep account push   Push local keys + personalities + commands + profile to codeep.dev
   codeep acp          Start ACP server (for Zed editor integration)
-  codeep review       Offline code review for CI (--json, --fail-on <level>)
+  codeep review       Offline code review for CI (--json, --fail-on, --rules, --ai)
+  codeep hook install   Install a git pre-commit hook running \`codeep review\`
+  codeep hook uninstall Remove the Codeep git hook
   codeep --version    Show version
   codeep --help       Show this help
 

package/dist/utils/agent.d.ts

@@ -22,6 +22,14 @@ export type PermissionDecision = 'allow-once' | 'allow-always' | 'deny-once' | '
  * invariant is unit-tested independently of the agent loop.
  */
 export declare function classifyPermissionOutcome(outcome: string | undefined | null): PermissionDecision;
+/**
+ * Build the set of tools that require a permission prompt this run. Derived from
+ * the global agentConfirm* settings, plus any `extra` tools forced in for this
+ * run only (ACP manual mode passes ['write_file','edit_file'] this way instead
+ * of mutating the global `agentConfirmWriteFile` config — which would leak the
+ * session's mode into the TUI and race on restore). Exported for unit testing.
+ */
+export declare function buildDangerousTools(extra?: string[]): Set<string>;
 export interface AgentOptions {
     maxIterations: number;
     maxDuration: number;
@@ -34,6 +42,10 @@ export interface AgentOptions {
     onTaskPlan?: (plan: TaskPlan) => void;
     onTaskUpdate?: (task: SubTask) => void;
     onRequestPermission?: (toolCall: ToolCall) => Promise<PermissionOutcome>;
+    /** Tool names to force into the per-run dangerous set, on top of the global
+     *  agentConfirm* settings. ACP manual mode passes ['write_file','edit_file']
+     *  here to gate them for THIS run only, instead of mutating global config. */
+    extraDangerousTools?: string[];
     onExecuteCommand?: (command: string, args: string[], cwd: string) => Promise<{
         stdout: string;
         stderr: string;

package/dist/utils/agent.js

@@ -119,6 +119,23 @@ export function classifyPermissionOutcome(outcome) {
         return 'deny-always';
     return 'deny-once'; // 'reject_once' OR anything unexpected → fail closed
 }
+/**
+ * Build the set of tools that require a permission prompt this run. Derived from
+ * the global agentConfirm* settings, plus any `extra` tools forced in for this
+ * run only (ACP manual mode passes ['write_file','edit_file'] this way instead
+ * of mutating the global `agentConfirmWriteFile` config — which would leak the
+ * session's mode into the TUI and race on restore). Exported for unit testing.
+ */
+export function buildDangerousTools(extra = []) {
+    const tools = new Set([
+        ...(config.get('agentConfirmDeleteFile') !== false ? ['delete_file'] : []),
+        ...(config.get('agentConfirmExecuteCommand') !== false ? ['execute_command'] : []),
+        ...(config.get('agentConfirmWriteFile') === true ? ['write_file', 'edit_file'] : []),
+    ]);
+    for (const t of extra)
+        tools.add(t);
+    return tools;
+}
 /**
  * Build the result for a run that paused at a safety limit. Pausing is a normal,
  * resumable state — not an error — so the summary tells the user how to resume.
@@ -384,11 +401,7 @@ export async function runAgent(prompt, projectContext, options = {}) {
     // Track tools permanently rejected this session via reject_always
     const alwaysRejectedTools = new Set();
     // Tools that require permission when onRequestPermission is set (configurable)
-    const dangerousTools = new Set([
-        ...(config.get('agentConfirmDeleteFile') !== false ? ['delete_file'] : []),
-        ...(config.get('agentConfirmExecuteCommand') !== false ? ['execute_command'] : []),
-        ...(config.get('agentConfirmWriteFile') === true ? ['write_file', 'edit_file'] : []),
-    ]);
+    const dangerousTools = buildDangerousTools(opts.extraDangerousTools);
     // Delegation handler: run a named (or generic) sub-agent in its own fresh
     // context and return its summary as the tool result. Reachable only when the
     // `delegate` tool was advertised (depth 0). The sub-agent runs nested (no own

package/dist/utils/codeReview.d.ts

@@ -54,3 +54,24 @@ export declare function formatReviewResult(result: ReviewResult): string;
  * Get review prompt for AI-enhanced review
  */
 export declare function getReviewSystemPrompt(result: ReviewResult): string;
+export interface BuiltinRuleInfo {
+    id: string;
+    category: ReviewCategory;
+    severity: ReviewIssue['severity'];
+    description: string;
+}
+/**
+ * Built-in rule metadata (id + what each flags) — the ids that
+ * `.codeep/review.{json,yml}` "disable" accepts. Includes the two line-count
+ * heuristics (long-file / long-function) that live outside CODE_PATTERNS.
+ */
+export declare function listBuiltinRules(): BuiltinRuleInfo[];
+/**
+ * Append an advisory "AI second opinion" section to a markdown review report.
+ * Advisory only — it never changes the score or the exit code; the deterministic
+ * review remains authoritative.
+ */
+export declare function appendAiSection(markdown: string, aiText: string | null, meta?: {
+    provider?: string;
+    model?: string;
+}): string;

package/dist/utils/codeReview.js

@@ -462,3 +462,34 @@ ${formatReviewResult(result)}
 
 Be concise and practical. Focus on issues that matter most for code quality and maintainability.`;
 }
+/**
+ * Built-in rule metadata (id + what each flags) — the ids that
+ * `.codeep/review.{json,yml}` "disable" accepts. Includes the two line-count
+ * heuristics (long-file / long-function) that live outside CODE_PATTERNS.
+ */
+export function listBuiltinRules() {
+    return [
+        ...CODE_PATTERNS.map((p) => ({
+            id: p.id,
+            category: p.category,
+            severity: p.severity,
+            description: p.message,
+        })),
+        { id: 'long-file', category: 'maintainability', severity: 'info', description: 'File exceeds 500 lines — consider splitting into smaller modules' },
+        { id: 'long-function', category: 'maintainability', severity: 'info', description: 'Function exceeds 50 lines — consider breaking it down' },
+    ];
+}
+/**
+ * Append an advisory "AI second opinion" section to a markdown review report.
+ * Advisory only — it never changes the score or the exit code; the deterministic
+ * review remains authoritative.
+ */
+export function appendAiSection(markdown, aiText, meta = {}) {
+    const label = meta.model
+        ? `${meta.model}${meta.provider ? ` via ${meta.provider}` : ''}`
+        : (meta.provider || 'your provider');
+    if (!aiText || !aiText.trim()) {
+        return `${markdown}\n\n## AI Second Opinion\n_Skipped — no response from ${label}._`;
+    }
+    return `${markdown}\n\n## AI Second Opinion (${label})\n_Advisory — does not affect the score or exit code; the deterministic review above is authoritative._\n\n${aiText.trim()}`;
+}

package/dist/utils/gitHookInstaller.d.ts

@@ -0,0 +1,26 @@
+import type { FailOn } from './headlessReview.js';
+export type HookType = 'pre-commit' | 'pre-push';
+export type HookAction = 'install' | 'uninstall' | 'help';
+export interface HookArgs {
+    action: HookAction;
+    hookType: HookType;
+    failOn: FailOn;
+    help: boolean;
+}
+export declare const HOOK_HELP = "Usage: codeep hook <install|uninstall> [options]\n\nInstall a git hook that runs `codeep review` on your changes, blocking the\ncommit/push when issues at/above the threshold are found. Honors a project's\n.codeep/review.yml (or .json).\n\nActions:\n  install      Install the hook (pre-commit by default)\n  uninstall    Remove the Codeep-managed hook\n\nOptions:\n  --pre-push          Manage the pre-push hook instead of pre-commit\n  --fail-on <level>   Severity that blocks: error | warning | info | none (default: error)\n  -h, --help          Show this help\n\nThe pre-commit hook reviews the working-tree content of staged files, so stage\nyour changes fully before committing for the most accurate result.\nCodeep never overwrites a pre-existing hook it didn't create.";
+/** Parse argv after `hook`. Pure. */
+export declare function parseHookArgs(argv: string[]): HookArgs;
+/** The hook script body. Pure. pre-commit scopes to staged files; pre-push reviews changes. */
+export declare function buildHookScript(hookType: HookType, failOn: FailOn): string;
+/** True when a hook file was created by Codeep (safe to overwrite/remove). */
+export declare function isCodeepHook(content: string): boolean;
+/** Resolve the git hooks directory (honors worktrees + core.hooksPath). Null if not a repo. */
+export declare function resolveHooksDir(cwd: string): string | null;
+export interface HookDeps {
+    resolveHooksDir: (cwd: string) => string | null;
+    readHook: (path: string) => string | null;
+    writeHook: (path: string, content: string) => void;
+    removeHook: (path: string) => void;
+    write: (text: string) => void;
+}
+export declare function runHookCommand(argv: string[], deps?: HookDeps): number;

package/dist/utils/gitHookInstaller.js

@@ -0,0 +1,168 @@
+// `codeep hook install|uninstall` — installs a GIT hook (pre-commit / pre-push)
+// that runs the offline reviewer on your changes and blocks the commit/push when
+// issues at/above the threshold are found. Honors .codeep/review.{yml,json}.
+//
+// This is a GIT-hook installer — distinct from the lifecycle SHELL hooks in
+// utils/hooks.ts (.codeep/hooks/<event>.sh) and the React hook in src/hooks/.
+import { readFileSync, writeFileSync, mkdirSync, chmodSync, rmSync } from 'fs';
+import { join, dirname, isAbsolute } from 'path';
+import { execSync } from 'child_process';
+const FAIL_ON_VALUES = ['error', 'warning', 'info', 'none'];
+const MARKER_START = '# >>> codeep hook >>>';
+const MARKER_END = '# <<< codeep hook <<<';
+export const HOOK_HELP = `Usage: codeep hook <install|uninstall> [options]
+
+Install a git hook that runs \`codeep review\` on your changes, blocking the
+commit/push when issues at/above the threshold are found. Honors a project's
+.codeep/review.yml (or .json).
+
+Actions:
+  install      Install the hook (pre-commit by default)
+  uninstall    Remove the Codeep-managed hook
+
+Options:
+  --pre-push          Manage the pre-push hook instead of pre-commit
+  --fail-on <level>   Severity that blocks: error | warning | info | none (default: error)
+  -h, --help          Show this help
+
+The pre-commit hook reviews the working-tree content of staged files, so stage
+your changes fully before committing for the most accurate result.
+Codeep never overwrites a pre-existing hook it didn't create.`;
+/** Parse argv after `hook`. Pure. */
+export function parseHookArgs(argv) {
+    const out = { action: 'help', hookType: 'pre-commit', failOn: 'error', help: false };
+    let i = 0;
+    if (argv[0] === 'install' || argv[0] === 'uninstall') {
+        out.action = argv[0];
+        i = 1;
+    }
+    for (; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--pre-push')
+            out.hookType = 'pre-push';
+        else if (a === '--pre-commit')
+            out.hookType = 'pre-commit';
+        else if (a === '-h' || a === '--help')
+            out.help = true;
+        else if (a === '--fail-on') {
+            const v = argv[++i];
+            if (FAIL_ON_VALUES.includes(v))
+                out.failOn = v;
+        }
+        else if (a.startsWith('--fail-on=')) {
+            const v = a.slice('--fail-on='.length);
+            if (FAIL_ON_VALUES.includes(v))
+                out.failOn = v;
+        }
+    }
+    return out;
+}
+/** The hook script body. Pure. pre-commit scopes to staged files; pre-push reviews changes. */
+export function buildHookScript(hookType, failOn) {
+    const lines = [
+        '#!/bin/sh',
+        MARKER_START,
+        '# Managed by Codeep: `codeep hook install` to update, `codeep hook uninstall` to remove.',
+        'command -v codeep >/dev/null 2>&1 || exit 0', // no codeep on PATH → skip, don't block
+    ];
+    if (hookType === 'pre-commit') {
+        // NUL-delimited + xargs -0 so staged paths with spaces/metachars survive as
+        // single arguments (an unquoted $files would word-split and silently skip
+        // them — a fail-open gate). Temp file keeps it portable: BSD/macOS xargs has
+        // no `-r`, so we guard emptiness with `[ -s ]` instead.
+        lines.push('tmp=$(mktemp)');
+        lines.push('git diff --cached --name-only -z --diff-filter=ACMR > "$tmp"');
+        lines.push('if [ -s "$tmp" ]; then');
+        lines.push(`  xargs -0 codeep review --fail-on ${failOn} < "$tmp"`);
+        lines.push('  status=$?');
+        lines.push('else');
+        lines.push('  status=0');
+        lines.push('fi');
+        lines.push('rm -f "$tmp"');
+        lines.push('exit $status');
+    }
+    else {
+        lines.push(`codeep review --fail-on ${failOn}`);
+    }
+    lines.push(MARKER_END, '');
+    return lines.join('\n');
+}
+/** True when a hook file was created by Codeep (safe to overwrite/remove). */
+export function isCodeepHook(content) {
+    return content.includes(MARKER_START);
+}
+/** Resolve the git hooks directory (honors worktrees + core.hooksPath). Null if not a repo. */
+export function resolveHooksDir(cwd) {
+    try {
+        execSync('git rev-parse --is-inside-work-tree', { cwd, stdio: 'ignore' });
+        const hooks = execSync('git rev-parse --git-path hooks', { cwd, encoding: 'utf8' }).trim();
+        return isAbsolute(hooks) ? hooks : join(cwd, hooks);
+    }
+    catch {
+        return null;
+    }
+}
+export function runHookCommand(argv, deps = defaultHookDeps()) {
+    const args = parseHookArgs(argv);
+    if (args.help || args.action === 'help') {
+        deps.write(HOOK_HELP);
+        return 0;
+    }
+    const hooksDir = deps.resolveHooksDir(process.cwd());
+    if (!hooksDir) {
+        deps.write('Not a git repository — run `codeep hook` inside a repo.');
+        return 1;
+    }
+    const target = join(hooksDir, args.hookType);
+    const existing = deps.readHook(target);
+    if (args.action === 'uninstall') {
+        if (existing === null) {
+            deps.write(`No ${args.hookType} hook to remove.`);
+            return 0;
+        }
+        if (!isCodeepHook(existing)) {
+            deps.write(`Refusing to remove ${args.hookType}: it was not created by Codeep.`);
+            return 1;
+        }
+        deps.removeHook(target);
+        deps.write(`Removed the Codeep ${args.hookType} hook.`);
+        return 0;
+    }
+    // install
+    if (existing !== null && !isCodeepHook(existing)) {
+        deps.write(`A ${args.hookType} hook already exists and was not created by Codeep — refusing to overwrite it. Remove it first, or add a \`codeep review\` call manually.`);
+        return 1;
+    }
+    deps.writeHook(target, buildHookScript(args.hookType, args.failOn));
+    const when = args.hookType === 'pre-commit' ? 'commit' : 'push';
+    deps.write(`Installed the Codeep ${args.hookType} hook → runs \`codeep review --fail-on ${args.failOn}\` on each ${when}.`);
+    return 0;
+}
+function defaultHookDeps() {
+    return {
+        resolveHooksDir,
+        readHook: (p) => {
+            try {
+                return readFileSync(p, 'utf8');
+            }
+            catch {
+                return null;
+            }
+        },
+        writeHook: (p, content) => {
+            mkdirSync(dirname(p), { recursive: true });
+            writeFileSync(p, content, { mode: 0o755 });
+            try {
+                chmodSync(p, 0o755);
+            }
+            catch { /* best effort (e.g. Windows) */ }
+        },
+        removeHook: (p) => {
+            try {
+                rmSync(p);
+            }
+            catch { /* ignore */ }
+        },
+        write: (t) => process.stdout.write(t + '\n'),
+    };
+}

package/dist/utils/headlessReview.d.ts

@@ -4,21 +4,35 @@ export interface ReviewArgs {
     files: string[];
     json: boolean;
     failOn: FailOn;
+    rules: boolean;
+    ai: boolean;
     help: boolean;
 }
-export declare const REVIEW_HELP = "Usage: codeep review [options] [files...]\n\nRun a deterministic, offline code review (no API key required). With no files,\nreviews your unstaged git changes, falling back to a src/ scan when the tree is\nclean. Pass files (or let your CI pass the PR's changed files) to scope it.\n\nOptions:\n  --json              Print the result as JSON instead of the markdown report\n  --fail-on <level>   Exit non-zero when an issue at or above <level> is found:\n                      error | warning | info | none   (default: error)\n  -h, --help          Show this help\n\nExit code: 0 when nothing at/above --fail-on is found, 1 otherwise.";
+export declare const REVIEW_HELP = "Usage: codeep review [options] [files...]\n\nRun a deterministic, offline code review (no API key required). With no files,\nreviews your unstaged git changes, falling back to a src/ scan when the tree is\nclean. Pass files (or let your CI pass the PR's changed files) to scope it.\n\nCustom/disabled rules come from .codeep/review.yml (or .json) in the repo.\n\nOptions:\n  --json              Print the result as JSON instead of the markdown report\n  --fail-on <level>   Exit non-zero when an issue at or above <level> is found:\n                      error | warning | info | none   (default: error)\n  --rules             List the built-in rule ids (for \"disable\" in .codeep/review.*) and exit\n  --ai                After the offline pass, ask your configured provider for a\n                      contextual second opinion on the working-tree diff\n                      (advisory; needs an API key; never affects the exit code)\n  -h, --help          Show this help\n\nExit code: 0 when nothing at/above --fail-on is found, 1 otherwise.";
 /** Parse `codeep review` argv (everything after the subcommand). Pure. */
 export declare function parseReviewArgs(argv: string[]): ReviewArgs;
 /** Exit code for a result under a fail-on threshold. Pure. */
 export declare function exitCodeForResult(result: ReviewResult, failOn: FailOn): number;
+/** Render the built-in rule ids for `--rules`. Pure. */
+export declare function formatBuiltinRules(): string;
 export interface ReviewDeps {
     /** Run the review over optional specific files. */
     review: (files?: string[]) => ReviewResult;
     /** Sink for the report (one call). */
     write: (text: string) => void;
+    /** List of built-in rule ids (for --rules). */
+    listRules: () => string;
+    /** Optional AI second opinion; returns null when unavailable (no key / error). */
+    aiReview: (result: ReviewResult) => Promise<string | null>;
+    /** Provider/model label for the AI section header. */
+    aiMeta: () => {
+        provider?: string;
+        model?: string;
+    };
 }
 /**
  * Orchestrate a headless review and return the process exit code. Side effects
- * (filesystem, stdout) live behind `deps` so the flow is unit-testable.
+ * (filesystem, stdout, provider call) live behind `deps` so the flow is
+ * unit-testable. The exit code is ALWAYS deterministic — `--ai` is advisory.
  */
-export declare function runHeadlessReview(argv: string[], deps?: ReviewDeps): number;
+export declare function runHeadlessReview(argv: string[], deps?: ReviewDeps): Promise<number>;

package/dist/utils/headlessReview.js

@@ -2,7 +2,12 @@
 // deterministic reviewer in codeReview.ts. No API key, no TUI: it scans, prints
 // a report (markdown or JSON), and exits non-zero when issues at/above a chosen
 // severity are found, so it drops cleanly into CI (e.g. a GitHub Action).
-import { performCodeReview, formatReviewResult } from './codeReview.js';
+//
+// `--ai` is the one opt-in online mode: after the offline pass it asks the
+// configured provider for a contextual second opinion (advisory only — it never
+// affects the exit code), and degrades to deterministic-only when no key is set.
+import { performCodeReview, formatReviewResult, getReviewSystemPrompt, listBuiltinRules, appendAiSection, } from './codeReview.js';
+import { config, getCurrentProvider } from '../config/index.js';
 const FAIL_ON_VALUES = ['error', 'warning', 'info', 'none'];
 // Higher = more severe. `suggestion` sits below `info` so `--fail-on info`
 // never trips on a mere suggestion.
@@ -13,21 +18,33 @@ Run a deterministic, offline code review (no API key required). With no files,
 reviews your unstaged git changes, falling back to a src/ scan when the tree is
 clean. Pass files (or let your CI pass the PR's changed files) to scope it.
 
+Custom/disabled rules come from .codeep/review.yml (or .json) in the repo.
+
 Options:
   --json              Print the result as JSON instead of the markdown report
   --fail-on <level>   Exit non-zero when an issue at or above <level> is found:
                       error | warning | info | none   (default: error)
+  --rules             List the built-in rule ids (for "disable" in .codeep/review.*) and exit
+  --ai                After the offline pass, ask your configured provider for a
+                      contextual second opinion on the working-tree diff
+                      (advisory; needs an API key; never affects the exit code)
   -h, --help          Show this help
 
 Exit code: 0 when nothing at/above --fail-on is found, 1 otherwise.`;
 /** Parse `codeep review` argv (everything after the subcommand). Pure. */
 export function parseReviewArgs(argv) {
-    const out = { files: [], json: false, failOn: 'error', help: false };
+    const out = { files: [], json: false, failOn: 'error', rules: false, ai: false, help: false };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === '--json') {
             out.json = true;
         }
+        else if (arg === '--rules') {
+            out.rules = true;
+        }
+        else if (arg === '--ai') {
+            out.ai = true;
+        }
         else if (arg === '-h' || arg === '--help') {
             out.help = true;
         }
@@ -56,18 +73,44 @@ export function exitCodeForResult(result, failOn) {
     const tripped = result.issues.some((i) => (SEVERITY_RANK[i.severity] ?? 0) >= threshold);
     return tripped ? 1 : 0;
 }
+/** Render the built-in rule ids for `--rules`. Pure. */
+export function formatBuiltinRules() {
+    const rules = listBuiltinRules();
+    const idW = Math.max(...rules.map((r) => r.id.length));
+    const sevW = Math.max(...rules.map((r) => r.severity.length));
+    const out = [
+        'Built-in review rules — put any id in "disable" in .codeep/review.yml|json:',
+        '',
+    ];
+    for (const r of rules) {
+        out.push(`  ${r.id.padEnd(idW)}  ${r.severity.padEnd(sevW)}  ${r.description}`);
+    }
+    return out.join('\n');
+}
 /**
  * Orchestrate a headless review and return the process exit code. Side effects
- * (filesystem, stdout) live behind `deps` so the flow is unit-testable.
+ * (filesystem, stdout, provider call) live behind `deps` so the flow is
+ * unit-testable. The exit code is ALWAYS deterministic — `--ai` is advisory.
  */
-export function runHeadlessReview(argv, deps = defaultDeps()) {
+export async function runHeadlessReview(argv, deps = defaultDeps()) {
     const args = parseReviewArgs(argv);
     if (args.help) {
         deps.write(REVIEW_HELP);
         return 0;
     }
+    if (args.rules) {
+        deps.write(deps.listRules());
+        return 0;
+    }
     const result = deps.review(args.files.length ? args.files : undefined);
-    deps.write(args.json ? JSON.stringify(result, null, 2) : formatReviewResult(result));
+    const aiText = args.ai ? await deps.aiReview(result) : null;
+    if (args.json) {
+        deps.write(JSON.stringify(args.ai ? { ...result, aiReview: aiText } : result, null, 2));
+    }
+    else {
+        const md = formatReviewResult(result);
+        deps.write(args.ai ? appendAiSection(md, aiText, deps.aiMeta()) : md);
+    }
     return exitCodeForResult(result, args.failOn);
 }
 // Only the reviewer's `.root` is read, so a minimal context rooted at cwd is
@@ -84,8 +127,41 @@ function minimalContext(root) {
     };
 }
 function defaultDeps() {
+    const cwd = process.cwd();
     return {
-        review: (files) => performCodeReview(minimalContext(process.cwd()), files),
+        review: (files) => performCodeReview(minimalContext(cwd), files),
         write: (text) => process.stdout.write(text + '\n'),
+        listRules: () => formatBuiltinRules(),
+        aiMeta: () => {
+            try {
+                return { provider: getCurrentProvider().name, model: String(config.get('model') || '') };
+            }
+            catch {
+                return {};
+            }
+        },
+        aiReview: async (result) => {
+            try {
+                const { loadAllApiKeys, isConfigured } = await import('../config/index.js');
+                await loadAllApiKeys();
+                if (!isConfigured()) {
+                    process.stderr.write('codeep review --ai: no API key configured for the current provider; skipping the AI pass (deterministic results below).\n');
+                    return null;
+                }
+                const { getGitDiff } = await import('./git.js');
+                const { chat } = await import('../api/index.js');
+                const d = getGitDiff(false, cwd);
+                const diff = d.success && d.diff ? d.diff.slice(0, 50000) : '(no textual diff available — reviewing the deterministic findings only)';
+                // Fold the prompt + findings into the user message (not a system-role
+                // history entry): chat() does not hoist a history `system` entry into
+                // the Anthropic top-level `system` field, so it would be dropped on
+                // Anthropic-protocol providers. As the user message it reaches every provider.
+                const message = `${getReviewSystemPrompt(result)}\n\n## Diff under review\n\`\`\`diff\n${diff}\n\`\`\``;
+                return await chat(message, []);
+            }
+            catch {
+                return null; // never hard-fail the review on an AI error
+            }
+        },
     };
 }

package/dist/utils/keychain.d.ts

@@ -9,6 +9,9 @@ export interface SecureStorage {
     setApiKey(providerId: string, apiKey: string): Promise<void>;
     deleteApiKey(providerId: string): Promise<void>;
     hasApiKey(providerId: string): Promise<boolean>;
+    /** Whether the OS keychain is usable (vs the plaintext-config fallback).
+     *  Optional — only SmartStorage (what createSecureStorage returns) implements it. */
+    isKeychainAvailable?(): Promise<boolean>;
 }
 /**
  * Migrate existing plain-text API keys to keychain

package/dist/utils/keychain.js

@@ -124,6 +124,10 @@ class SmartStorage {
         }
         this.keychainTested = true;
     }
+    async isKeychainAvailable() {
+        await this.ensureKeychainTested();
+        return this.useKeychain;
+    }
     async getApiKey(providerId) {
         await this.ensureKeychainTested();
         if (this.useKeychain) {

package/dist/utils/reviewConfig.js

@@ -23,7 +23,10 @@
  */
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
-const CONFIG_PATH = '.codeep/review.json';
+import yaml from 'js-yaml';
+// Candidate config files, in precedence order: YAML preferred (nicer for a
+// human-authored rules file — comments, single-quoted regex), JSON as fallback.
+const CONFIG_PATHS = ['.codeep/review.yml', '.codeep/review.yaml', '.codeep/review.json'];
 const MAX_RULES = 200;
 const VALID_CATEGORIES = [
     'security', 'performance', 'maintainability', 'bug', 'style', 'types', 'best-practice', 'documentation',
@@ -53,19 +56,35 @@ function asStringArray(v) {
         : [];
 }
 export function loadReviewConfig(projectRoot) {
-    const filePath = join(projectRoot, CONFIG_PATH);
-    if (!existsSync(filePath))
+    // First existing candidate wins (.yml > .yaml > .json).
+    let chosen = null;
+    let text = '';
+    for (const candidate of CONFIG_PATHS) {
+        const fp = join(projectRoot, candidate);
+        if (existsSync(fp)) {
+            chosen = candidate;
+            try {
+                text = readFileSync(fp, 'utf-8');
+            }
+            catch {
+                return null;
+            }
+            break;
+        }
+    }
+    if (!chosen)
         return null;
+    const isJson = chosen.endsWith('.json');
     let data;
     try {
-        data = JSON.parse(readFileSync(filePath, 'utf-8'));
+        data = isJson ? JSON.parse(text) : yaml.load(text);
     }
     catch {
-        console.warn(`[codeep] Ignoring ${CONFIG_PATH}: not valid JSON.`);
+        console.warn(`[codeep] Ignoring ${chosen}: not valid ${isJson ? 'JSON' : 'YAML'}.`);
         return null;
     }
     if (!data || typeof data !== 'object' || Array.isArray(data)) {
-        console.warn(`[codeep] Ignoring ${CONFIG_PATH}: expected a JSON object.`);
+        console.warn(`[codeep] Ignoring ${chosen}: expected a top-level object.`);
         return null;
     }
     const cfg = data;
@@ -82,12 +101,12 @@ export function loadReviewConfig(projectRoot) {
         const message = typeof r.message === 'string' && r.message.trim() ? r.message.trim() : null;
         const patternSrc = typeof r.pattern === 'string' && r.pattern ? r.pattern : null;
         if (!id || !message || !patternSrc) {
-            console.warn(`[codeep] Skipping a rule in ${CONFIG_PATH}: each rule needs id, pattern and message.`);
+            console.warn(`[codeep] Skipping a rule in ${chosen}: each rule needs id, pattern and message.`);
             continue;
         }
         // Reject oversized patterns outright — keeps regex compilation/run bounded.
         if (patternSrc.length > 1000) {
-            console.warn(`[codeep] Skipping rule "${id}" in ${CONFIG_PATH}: pattern is too long (>1000 chars).`);
+            console.warn(`[codeep] Skipping rule "${id}" in ${chosen}: pattern is too long (>1000 chars).`);
             continue;
         }
         // Conservative ReDoS screen: reject the classic catastrophic shape — a group
@@ -95,7 +114,7 @@ export function loadReviewConfig(projectRoot) {
         // (\d*)*, (.*)+, (x+){2,}. Not exhaustive (the GitHub Action also bounds
         // wall-clock), but it blocks the common foot-guns in an untrusted review.json.
         if (/\([^)]*[+*]\)\s*[+*{]/.test(patternSrc)) {
-            console.warn(`[codeep] Skipping rule "${id}" in ${CONFIG_PATH}: nested quantifiers risk catastrophic backtracking (ReDoS).`);
+            console.warn(`[codeep] Skipping rule "${id}" in ${chosen}: nested quantifiers risk catastrophic backtracking (ReDoS).`);
             continue;
         }
         // Always include the global flag so every match in a file is found.
@@ -107,7 +126,7 @@ export function loadReviewConfig(projectRoot) {
             pattern = new RegExp(patternSrc, flags);
         }
         catch {
-            console.warn(`[codeep] Skipping rule "${id}" in ${CONFIG_PATH}: invalid regex.`);
+            console.warn(`[codeep] Skipping rule "${id}" in ${chosen}: invalid regex.`);
             continue;
         }
         const category = VALID_CATEGORIES.includes(r.category)

package/dist/utils/update.d.ts

@@ -5,7 +5,9 @@ export interface VersionInfo {
     error?: string;
 }
 /**
- * Get current version from package.json
+ * Current Codeep version. Uses the build-time-baked VERSION constant (works in
+ * the bun-compiled binary, which has no package.json on disk), falling back to
+ * reading package.json for an unbuilt dev tree.
  */
 export declare function getCurrentVersion(): string;
 /**

package/dist/utils/update.js

@@ -1,14 +1,18 @@
 import { readFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
+import { VERSION } from '../version.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 /**
- * Get current version from package.json
+ * Current Codeep version. Uses the build-time-baked VERSION constant (works in
+ * the bun-compiled binary, which has no package.json on disk), falling back to
+ * reading package.json for an unbuilt dev tree.
  */
 export function getCurrentVersion() {
+    if (VERSION)
+        return VERSION;
     try {
-        // In built version, package.json is in parent directory
         const packagePath = join(__dirname, '../../package.json');
         const packageJson = JSON.parse(readFileSync(packagePath, 'utf-8'));
         return packageJson.version;

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "2.7.0";

package/dist/version.js

@@ -0,0 +1,4 @@
+// AUTO-GENERATED by scripts/gen-version.js — do not edit by hand.
+// Baked from package.json at build time so the bun-compiled binary reports
+// the right version (it has no package.json on disk to read at runtime).
+export const VERSION = '2.7.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeep",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "AI-powered coding assistant built for the terminal. Multiple LLM providers, project-aware context, and a seamless development workflow.",
   "type": "module",
   "main": "dist/index.js",
@@ -8,9 +8,9 @@
     "codeep": "bin/codeep.js"
   },
   "scripts": {
-    "dev": "node --import tsx src/renderer/main.ts",
-    "prepack": "tsc; node scripts/fix-imports.js",
-    "build": "tsc && node scripts/fix-imports.js",
+    "dev": "node scripts/gen-version.js && node --import tsx src/renderer/main.ts",
+    "prepack": "node scripts/gen-version.js && tsc; node scripts/fix-imports.js",
+    "build": "node scripts/gen-version.js && tsc && node scripts/fix-imports.js",
     "start": "node dist/renderer/main.js",
     "demo:renderer": "node --import tsx src/renderer/demo.ts",
     "demo:app": "node --import tsx src/renderer/demo-app.ts",
@@ -42,10 +42,12 @@
   "dependencies": {
     "clipboardy": "^4.0.0",
     "conf": "^12.0.0",
+    "js-yaml": "^4.1.0",
     "keytar": "^7.9.0",
     "open": "^10.0.0"
   },
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.10.0",
     "@vitest/coverage-v8": "^4.0.18",
     "pkg": "^5.8.1",