@praneeth_54/agentdoctor 0.2.0-beta → 1.0.0

package/dist/core/fix/plan.js

@@ -0,0 +1,247 @@
+import path from "node:path";
+import { readTextFile } from "../../utils/fs.js";
+import { settingsTextDeniesPath } from "../rules/claude-deny.js";
+import { configTextDeniesPath } from "../rules/codex-deny.js";
+import { createIgnoreIndex, parseIgnoreFile, pathMatchesAny } from "../rules/ignore.js";
+import { isSafeContextFixRule, patternForFinding } from "./patterns.js";
+import { denyRuleForFixPattern } from "./writers/claude-settings.js";
+import { assertWritableCodexConfig, denyKeyForFixPattern } from "./writers/codex-config.js";
+const DEFAULT_MAX_IGNORE_BYTES = 512 * 1024;
+function cursorConfigured(result) {
+    return result.agents.some((a) => a.id === "cursor" && (a.detected || a.configured));
+}
+function claudeConfigured(result) {
+    return result.agents.some((a) => a.id === "claude-code" && (a.detected || a.configured));
+}
+function codexConfigured(result) {
+    return result.agents.some((a) => a.id === "codex" && (a.detected || a.configured));
+}
+async function loadCursorignorePatterns(root) {
+    const filePath = path.join(root, ".cursorignore");
+    const text = await readTextFile(filePath, DEFAULT_MAX_IGNORE_BYTES);
+    if (text === null) {
+        return [];
+    }
+    return parseIgnoreFile(text);
+}
+async function loadClaudeSettingsText(root) {
+    return readTextFile(path.join(root, ".claude/settings.json"), DEFAULT_MAX_IGNORE_BYTES);
+}
+async function loadCodexConfigText(root) {
+    return readTextFile(path.join(root, ".codex/config.toml"), DEFAULT_MAX_IGNORE_BYTES);
+}
+/**
+ * Build a fix plan from a scan result.
+ * Safe context exclusions: Cursor `.cursorignore`, Claude Code Read deny, Codex filesystem deny.
+ */
+export async function buildFixPlan(result) {
+    const root = result.repository.root;
+    const skipped = [];
+    const actionsByKey = new Map();
+    const existingCursorPatterns = await loadCursorignorePatterns(root);
+    const cursorIndex = createIgnoreIndex({
+        gitignorePatterns: [],
+        cursorignorePatterns: existingCursorPatterns,
+    });
+    const claudeSettingsText = await loadClaudeSettingsText(root);
+    const codexConfigText = await loadCodexConfigText(root);
+    const hasCursor = cursorConfigured(result);
+    const hasClaude = claudeConfigured(result);
+    const hasCodex = codexConfigured(result);
+    for (const finding of result.findings) {
+        if (finding.fixability !== "safe") {
+            skipped.push({
+                findingId: finding.id,
+                ruleId: finding.ruleId,
+                reason: finding.fixability === "review"
+                    ? "Requires human review (not auto-fixed)"
+                    : finding.fixability === "manual"
+                        ? "Manual remediation required (not auto-fixed)"
+                        : "Not auto-fixable",
+            });
+            continue;
+        }
+        if (!isSafeContextFixRule(finding.ruleId)) {
+            skipped.push({
+                findingId: finding.id,
+                ruleId: finding.ruleId,
+                reason: "No automated fixer for this safe rule yet",
+            });
+            continue;
+        }
+        const pattern = patternForFinding(finding);
+        const evidencePath = finding.evidence?.path?.replace(/\\/g, "/");
+        if (!pattern || !evidencePath) {
+            skipped.push({
+                findingId: finding.id,
+                ruleId: finding.ruleId,
+                reason: "Finding has no usable evidence path",
+            });
+            continue;
+        }
+        const wantsCursor = finding.affectedAgents.includes("cursor");
+        const wantsClaude = finding.affectedAgents.includes("claude-code");
+        const wantsCodex = finding.affectedAgents.includes("codex");
+        if (wantsCursor && hasCursor) {
+            if (cursorIndex.matchesCursorignore(evidencePath) ||
+                cursorIndex.matchesCursorignore(pattern)) {
+                skipped.push({
+                    findingId: finding.id,
+                    ruleId: finding.ruleId,
+                    reason: "Already excluded by .cursorignore",
+                });
+            }
+            else {
+                mergeCursorAction(actionsByKey, finding, pattern, evidencePath);
+            }
+        }
+        else if (wantsCursor && !hasCursor) {
+            skipped.push({
+                findingId: finding.id,
+                ruleId: finding.ruleId,
+                reason: "Cursor not detected; skipping .cursorignore fix",
+            });
+        }
+        if (wantsClaude && hasClaude) {
+            const denyRule = denyRuleForFixPattern(pattern, evidencePath);
+            if (claudeSettingsText && settingsTextDeniesPath(claudeSettingsText, evidencePath)) {
+                skipped.push({
+                    findingId: finding.id,
+                    ruleId: finding.ruleId,
+                    reason: "Already excluded by Claude Code Read deny",
+                });
+            }
+            else {
+                mergeClaudeAction(actionsByKey, finding, pattern, evidencePath, denyRule);
+            }
+        }
+        else if (wantsClaude && !hasClaude) {
+            skipped.push({
+                findingId: finding.id,
+                ruleId: finding.ruleId,
+                reason: "Claude Code not detected; skipping settings deny fix",
+            });
+        }
+        if (wantsCodex && hasCodex) {
+            const denyKey = denyKeyForFixPattern(pattern, evidencePath);
+            if (codexConfigText && configTextDeniesPath(codexConfigText, evidencePath)) {
+                skipped.push({
+                    findingId: finding.id,
+                    ruleId: finding.ruleId,
+                    reason: "Already excluded by Codex filesystem deny",
+                });
+            }
+            else if (codexConfigText) {
+                // Refuse unwritable/invalid config the same way Claude Fix refuses bad JSON —
+                // do not silently skip and leave Codex findings uncleared after a partial Cursor write.
+                assertWritableCodexConfig(codexConfigText);
+                mergeCodexAction(actionsByKey, finding, pattern, evidencePath, denyKey);
+            }
+            else {
+                mergeCodexAction(actionsByKey, finding, pattern, evidencePath, denyKey);
+            }
+        }
+        else if (wantsCodex && !hasCodex) {
+            skipped.push({
+                findingId: finding.id,
+                ruleId: finding.ruleId,
+                reason: "Codex not detected; skipping config.toml deny fix",
+            });
+        }
+        for (const agent of finding.affectedAgents) {
+            if (agent === "cursor" || agent === "claude-code" || agent === "codex") {
+                continue;
+            }
+            skipped.push({
+                findingId: finding.id,
+                ruleId: finding.ruleId,
+                reason: `Fix writer for ${agent} not implemented yet`,
+            });
+        }
+    }
+    return {
+        root,
+        actions: [...actionsByKey.values()].sort((a, b) => a.id.localeCompare(b.id)),
+        skipped,
+    };
+}
+function mergeCursorAction(actionsByKey, finding, pattern, evidencePath) {
+    const key = `cursor:.cursorignore:${pattern}`;
+    const existing = actionsByKey.get(key);
+    if (existing) {
+        if (!existing.findingIds.includes(finding.id)) {
+            existing.findingIds.push(finding.id);
+        }
+        return;
+    }
+    actionsByKey.set(key, {
+        id: key,
+        kind: "append-ignore-pattern",
+        agent: "cursor",
+        targetRelativePath: ".cursorignore",
+        pattern,
+        evidencePath,
+        findingIds: [finding.id],
+        description: `Exclude ${evidencePath} from Cursor agent context via .cursorignore`,
+    });
+}
+function mergeClaudeAction(actionsByKey, finding, pattern, evidencePath, denyRule) {
+    const key = `claude-code:.claude/settings.json:${denyRule}`;
+    const existing = actionsByKey.get(key);
+    if (existing) {
+        if (!existing.findingIds.includes(finding.id)) {
+            existing.findingIds.push(finding.id);
+        }
+        return;
+    }
+    actionsByKey.set(key, {
+        id: key,
+        kind: "append-ignore-pattern",
+        agent: "claude-code",
+        targetRelativePath: ".claude/settings.json",
+        pattern,
+        evidencePath,
+        findingIds: [finding.id],
+        description: `Exclude ${evidencePath} from Claude Code via permissions.deny ${denyRule}`,
+    });
+}
+function mergeCodexAction(actionsByKey, finding, pattern, evidencePath, denyKey) {
+    const key = `codex:.codex/config.toml:${denyKey}`;
+    const existing = actionsByKey.get(key);
+    if (existing) {
+        if (!existing.findingIds.includes(finding.id)) {
+            existing.findingIds.push(finding.id);
+        }
+        return;
+    }
+    actionsByKey.set(key, {
+        id: key,
+        kind: "append-ignore-pattern",
+        agent: "codex",
+        targetRelativePath: ".codex/config.toml",
+        pattern,
+        evidencePath,
+        findingIds: [finding.id],
+        description: `Exclude ${evidencePath} from Codex via filesystem deny "${denyKey}"`,
+    });
+}
+/** Patterns that would be newly appended given current file contents. */
+export function missingPatternsForCursorignore(currentContent, patterns) {
+    const existing = currentContent === null ? [] : parseIgnoreFile(currentContent);
+    const missing = [];
+    for (const pattern of patterns) {
+        if (existing.includes(pattern)) {
+            continue;
+        }
+        if (pathMatchesAny(pattern.replace(/\/$/, ""), existing) &&
+            existing.some((p) => p === pattern)) {
+            continue;
+        }
+        const evidenceGuess = pattern.endsWith("/") ? pattern.slice(0, -1) : pattern;
+        if (pathMatchesAny(evidenceGuess, existing) || pathMatchesAny(pattern, existing)) {
+            continue;
+        }
+        missing.push(pattern);
+    }
+    return missing;
+}

package/dist/core/fix/render.d.ts

@@ -0,0 +1,8 @@
+import type { FixApplyResult, FixPlan } from "./types.js";
+export declare function renderFixPlanTerminal(plan: FixPlan, options: {
+    dryRun: boolean;
+    cursorContent: string | null;
+    claudeSettingsContent?: string | null;
+    codexConfigContent?: string | null;
+    applyResult?: FixApplyResult;
+}): string;

package/dist/core/fix/render.js

@@ -0,0 +1,116 @@
+import { previewClaudeSettingsActions } from "./writers/claude-settings.js";
+import { previewCodexConfigActions } from "./writers/codex-config.js";
+import { previewCursorignoreActions } from "./writers/cursorignore.js";
+export function renderFixPlanTerminal(plan, options) {
+    const lines = [];
+    lines.push("");
+    lines.push(options.dryRun ? "AgentDoctor fix (dry-run)" : "AgentDoctor fix");
+    lines.push("");
+    if (plan.actions.length === 0) {
+        lines.push("  No automatic fixes available for this scan.");
+        if (plan.skipped.length > 0) {
+            lines.push("");
+            lines.push(`  ${plan.skipped.length} finding(s) need manual or review action:`);
+            const reasons = summarizeSkipReasons(plan.skipped.map((s) => s.reason));
+            for (const [reason, count] of reasons) {
+                lines.push(`    - ${reason} (${count})`);
+            }
+            lines.push("");
+            lines.push("Next");
+            lines.push("  Inspect a finding: agentdoctor explain <rule-id>  (ids in scan --json)");
+            lines.push("  Confirm with verify: agentdoctor verify --baseline agentdoctor-report.json");
+            lines.push("  No baseline yet? agentdoctor scan --json > agentdoctor-report.json");
+        }
+        else {
+            lines.push("  Scan found nothing that Fix can change.");
+            lines.push("");
+            lines.push("Next");
+            lines.push("  Re-scan: agentdoctor scan");
+        }
+        lines.push("");
+        return lines.join("\n");
+    }
+    lines.push(`  Proposed actions: ${plan.actions.length}`);
+    for (const action of plan.actions) {
+        lines.push(`    • [${action.agent}] ${action.description}`);
+        lines.push(`      pattern: ${action.pattern}`);
+        lines.push(`      findings: ${action.findingIds.length}`);
+    }
+    const cursorPreview = previewCursorignoreActions(options.cursorContent, plan.actions);
+    const claudePreview = previewClaudeSettingsActions(options.claudeSettingsContent ?? null, plan.actions);
+    const codexPreview = previewCodexConfigActions(options.codexConfigContent ?? null, plan.actions);
+    if (cursorPreview || claudePreview || codexPreview) {
+        lines.push("");
+        lines.push("  File changes:");
+        let shown = false;
+        if (cursorPreview) {
+            lines.push(`    ${cursorPreview.targetRelativePath} (+${cursorPreview.patternsToAdd.length} pattern(s))`);
+            lines.push("");
+            for (const previewLine of cursorPreview.preview.split("\n")) {
+                lines.push(`  ${previewLine}`);
+            }
+            shown = true;
+        }
+        if (claudePreview) {
+            if (shown) {
+                lines.push("");
+            }
+            lines.push(`    ${claudePreview.targetRelativePath} (+${claudePreview.denyRulesToAdd.length} deny rule(s))`);
+            lines.push("");
+            for (const previewLine of claudePreview.preview.split("\n")) {
+                lines.push(`  ${previewLine}`);
+            }
+            shown = true;
+        }
+        if (codexPreview) {
+            if (shown) {
+                lines.push("");
+            }
+            lines.push(`    ${codexPreview.targetRelativePath} (+${codexPreview.denyKeysToAdd.length} deny key(s))`);
+            lines.push("");
+            for (const previewLine of codexPreview.preview.split("\n")) {
+                lines.push(`  ${previewLine}`);
+            }
+        }
+    }
+    if (options.applyResult && !options.dryRun) {
+        lines.push("");
+        if (options.applyResult.writtenFiles.length > 0) {
+            lines.push(`  Wrote: ${options.applyResult.writtenFiles.join(", ")}`);
+        }
+        else {
+            lines.push("  No files written.");
+        }
+    }
+    else if (options.dryRun) {
+        lines.push("");
+        lines.push("  No files were modified (dry-run).");
+    }
+    if (plan.skipped.length > 0) {
+        lines.push("");
+        lines.push(`  Skipped: ${plan.skipped.length} finding(s):`);
+        const reasons = summarizeSkipReasons(plan.skipped.map((s) => s.reason));
+        for (const [reason, count] of reasons) {
+            lines.push(`    - ${reason} (${count})`);
+        }
+    }
+    lines.push("");
+    lines.push("Next");
+    if (options.dryRun && plan.actions.length > 0) {
+        lines.push("  Apply these changes: agentdoctor fix -y");
+    }
+    if (plan.skipped.length > 0) {
+        lines.push("  Review/manual findings stay open — inspect with: agentdoctor explain <rule-id>");
+    }
+    lines.push("  Confirm with verify: agentdoctor verify --baseline agentdoctor-report.json");
+    lines.push("  No baseline yet? agentdoctor scan --json > agentdoctor-report.json");
+    lines.push("");
+    return lines.join("\n");
+}
+function summarizeSkipReasons(reasons) {
+    const map = new Map();
+    for (const reason of reasons) {
+        map.set(reason, (map.get(reason) ?? 0) + 1);
+    }
+    return [...map.entries()].sort((a, b) => b[1] - a[1]);
+}

package/dist/core/fix/run.d.ts

@@ -0,0 +1,15 @@
+import type { FixApplyResult, FixPlan } from "./types.js";
+export interface RunFixOptions {
+    cwd: string;
+    dryRun: boolean;
+    yes: boolean;
+}
+export interface RunFixResult {
+    plan: FixPlan;
+    applyResult: FixApplyResult;
+    cancelled: boolean;
+}
+/**
+ * Scan → plan → (confirm) → apply Safe Repository Mutation actions.
+ */
+export declare function runFix(options: RunFixOptions): Promise<RunFixResult>;

package/dist/core/fix/run.js

@@ -0,0 +1,58 @@
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { scan } from "../scanner/scan.js";
+import { applyFixPlan, readClaudeSettings, readCodexConfig, readCursorignore } from "./apply.js";
+import { buildFixPlan } from "./plan.js";
+import { renderFixPlanTerminal } from "./render.js";
+/**
+ * Scan → plan → (confirm) → apply Safe Repository Mutation actions.
+ */
+export async function runFix(options) {
+    const result = await scan({ cwd: options.cwd });
+    const plan = await buildFixPlan(result);
+    const cursorContent = await readCursorignore(plan.root);
+    const claudeSettingsContent = await readClaudeSettings(plan.root);
+    const codexConfigContent = await readCodexConfig(plan.root);
+    if (plan.actions.length === 0 || options.dryRun) {
+        const applyResult = await applyFixPlan(plan, { dryRun: true });
+        return { plan, applyResult, cancelled: false };
+    }
+    if (!options.yes) {
+        const previewText = renderFixPlanTerminal(plan, {
+            dryRun: true,
+            cursorContent,
+            claudeSettingsContent,
+            codexConfigContent,
+        });
+        process.stdout.write(previewText);
+        const confirmed = await confirm("Apply these changes?");
+        if (!confirmed) {
+            return {
+                plan,
+                applyResult: {
+                    plan,
+                    dryRun: true,
+                    writtenFiles: [],
+                    changedFiles: [],
+                },
+                cancelled: true,
+            };
+        }
+    }
+    const applyResult = await applyFixPlan(plan, { dryRun: false });
+    return { plan, applyResult, cancelled: false };
+}
+async function confirm(question) {
+    if (!input.isTTY || !output.isTTY) {
+        process.stderr.write("Error: confirmation required but stdin is not a TTY. Re-run with --yes or --dry-run.\n");
+        return false;
+    }
+    const rl = readline.createInterface({ input, output });
+    try {
+        const answer = await rl.question(`${question} [y/N] `);
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/core/fix/types.d.ts

@@ -0,0 +1,34 @@
+import type { AgentId } from "../../types/index.js";
+export type FixKind = "append-ignore-pattern";
+/** Allowlisted relative paths fix may create or modify. */
+export declare const FIX_PATH_ALLOWLIST: readonly [".cursorignore", ".claude/settings.json", ".codex/config.toml"];
+export type FixAllowlistedPath = (typeof FIX_PATH_ALLOWLIST)[number];
+export interface FixAction {
+    id: string;
+    kind: FixKind;
+    agent: AgentId;
+    targetRelativePath: FixAllowlistedPath;
+    /** Ignore pattern to ensure is present (gitignore-style). */
+    pattern: string;
+    /** Evidence path this pattern is meant to exclude. */
+    evidencePath: string;
+    findingIds: string[];
+    description: string;
+}
+export interface SkippedFix {
+    findingId: string;
+    ruleId: string;
+    reason: string;
+}
+export interface FixPlan {
+    root: string;
+    actions: FixAction[];
+    skipped: SkippedFix[];
+}
+export interface FixApplyResult {
+    plan: FixPlan;
+    dryRun: boolean;
+    writtenFiles: string[];
+    /** Relative paths that would be / were written */
+    changedFiles: string[];
+}

package/dist/core/fix/types.js

@@ -0,0 +1,6 @@
+/** Allowlisted relative paths fix may create or modify. */
+export const FIX_PATH_ALLOWLIST = [
+    ".cursorignore",
+    ".claude/settings.json",
+    ".codex/config.toml",
+];

package/dist/core/fix/writers/claude-settings.d.ts

@@ -0,0 +1,16 @@
+import type { FixAction } from "../types.js";
+declare const SETTINGS_RELATIVE = ".claude/settings.json";
+export interface ClaudeSettingsWritePreview {
+    targetRelativePath: typeof SETTINGS_RELATIVE;
+    denyRulesToAdd: string[];
+    before: string;
+    after: string;
+    preview: string;
+}
+export declare function denyRuleForFixPattern(pattern: string, evidencePath: string): string;
+export declare function missingClaudeDenyRules(currentContent: string | null, denyRules: string[]): string[];
+export declare function buildClaudeSettingsContent(currentContent: string | null, denyRulesToAdd: string[]): string;
+export declare function previewClaudeSettingsActions(currentContent: string | null, actions: FixAction[]): ClaudeSettingsWritePreview | null;
+export declare function readClaudeSettings(root: string): Promise<string | null>;
+export declare function writeClaudeSettings(root: string, content: string): Promise<void>;
+export {};

package/dist/core/fix/writers/claude-settings.js

@@ -0,0 +1,100 @@
+import path from "node:path";
+import { atomicWriteTextFile, readTextFile } from "../../../utils/fs.js";
+import { claudeReadDenyRule } from "../../rules/claude-deny.js";
+const MAX_BYTES = 512 * 1024;
+const SETTINGS_RELATIVE = ".claude/settings.json";
+export function denyRuleForFixPattern(pattern, evidencePath) {
+    const isDirectory = pattern.endsWith("/");
+    return claudeReadDenyRule(evidencePath, isDirectory ? "directory" : "file");
+}
+export function missingClaudeDenyRules(currentContent, denyRules) {
+    const existing = parseDenyList(currentContent);
+    const missing = [];
+    for (const rule of denyRules) {
+        if (existing.includes(rule)) {
+            continue;
+        }
+        missing.push(rule);
+    }
+    return missing;
+}
+export function buildClaudeSettingsContent(currentContent, denyRulesToAdd) {
+    if (denyRulesToAdd.length === 0) {
+        return currentContent ?? `${JSON.stringify({ permissions: { deny: [] } }, null, 2)}\n`;
+    }
+    let parsed = {};
+    if (currentContent && currentContent.trim().length > 0) {
+        try {
+            parsed = JSON.parse(currentContent);
+        }
+        catch {
+            throw new Error(`${SETTINGS_RELATIVE} is not valid JSON; refusing to apply Claude Fix`);
+        }
+    }
+    const permissions = parsed.permissions && typeof parsed.permissions === "object" ? { ...parsed.permissions } : {};
+    const deny = Array.isArray(permissions.deny)
+        ? permissions.deny.filter((item) => typeof item === "string")
+        : [];
+    for (const rule of denyRulesToAdd) {
+        if (!deny.includes(rule)) {
+            deny.push(rule);
+        }
+    }
+    permissions.deny = deny;
+    parsed.permissions = permissions;
+    return `${JSON.stringify(parsed, null, 2)}\n`;
+}
+export function previewClaudeSettingsActions(currentContent, actions) {
+    const claudeActions = actions.filter((a) => a.agent === "claude-code" && a.targetRelativePath === SETTINGS_RELATIVE);
+    if (claudeActions.length === 0) {
+        return null;
+    }
+    const requested = [
+        ...new Set(claudeActions.map((a) => denyRuleForFixPattern(a.pattern, a.evidencePath))),
+    ];
+    const denyRulesToAdd = missingClaudeDenyRules(currentContent, requested);
+    if (denyRulesToAdd.length === 0) {
+        return null;
+    }
+    const before = currentContent ?? "";
+    const after = buildClaudeSettingsContent(currentContent, denyRulesToAdd);
+    return {
+        targetRelativePath: SETTINGS_RELATIVE,
+        denyRulesToAdd,
+        before,
+        after,
+        preview: formatSimpleDiff(SETTINGS_RELATIVE, before, after),
+    };
+}
+export async function readClaudeSettings(root) {
+    return readTextFile(path.join(root, SETTINGS_RELATIVE), MAX_BYTES);
+}
+export async function writeClaudeSettings(root, content) {
+    await atomicWriteTextFile(path.join(root, SETTINGS_RELATIVE), content);
+}
+function parseDenyList(currentContent) {
+    if (!currentContent || currentContent.trim().length === 0) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(currentContent);
+        const deny = parsed.permissions?.deny;
+        if (!Array.isArray(deny)) {
+            return [];
+        }
+        return deny.filter((item) => typeof item === "string");
+    }
+    catch {
+        return [];
+    }
+}
+function formatSimpleDiff(fileLabel, before, after) {
+    const lines = [];
+    lines.push(`--- a/${fileLabel}`);
+    lines.push(`+++ b/${fileLabel}`);
+    lines.push(before.trim().length === 0 ? "@@ new file @@" : "@@ update @@");
+    for (const line of after.split(/\r?\n/)) {
+        lines.push(`+${line}`);
+    }
+    return lines.join("\n");
+}

package/dist/core/fix/writers/codex-config.d.ts

@@ -0,0 +1,22 @@
+import type { FixAction } from "../types.js";
+declare const CONFIG_RELATIVE = ".codex/config.toml";
+export interface CodexConfigWritePreview {
+    targetRelativePath: typeof CONFIG_RELATIVE;
+    denyKeysToAdd: string[];
+    before: string;
+    after: string;
+    preview: string;
+}
+export declare function denyKeyForFixPattern(_pattern: string, evidencePath: string): string;
+export declare function missingCodexDenyKeys(currentContent: string | null, denyKeys: string[]): string[];
+/**
+ * Merge filesystem deny keys into project `.codex/config.toml`.
+ * Refuses when sandbox_mode is present (permission profiles do not compose).
+ * Refuses when default_permissions selects a built-in `:…` profile.
+ */
+export declare function buildCodexConfigContent(currentContent: string | null, denyKeysToAdd: string[]): string;
+export declare function previewCodexConfigActions(currentContent: string | null, actions: FixAction[]): CodexConfigWritePreview | null;
+export declare function readCodexConfig(root: string): Promise<string | null>;
+export declare function writeCodexConfig(root: string, content: string): Promise<void>;
+export declare function assertWritableCodexConfig(content: string): void;
+export {};