@bubblebrain-ai/bubble 0.0.1

package/dist/orchestrator/default-hooks.js

@@ -0,0 +1,96 @@
+import { classifyTask } from "../agent/task-classifier.js";
+import { EvidenceTracker } from "../agent/evidence-tracker.js";
+import { ExecutionGovernor } from "../agent/execution-governor.js";
+import { arbitrateToolCall } from "../agent/tool-arbiter.js";
+import { buildTaskSummaryReminder, buildWorkflowPhaseReminder } from "../prompt/reminders.js";
+import { formatCoverageSummary, resolveWorkflowPhase } from "./workflow.js";
+export function createDefaultHooks() {
+    return [
+        {
+            beforeTurn(ctx) {
+                const taskType = classifyTask(ctx.input);
+                ctx.state.taskType = taskType;
+                ctx.state.governor = new ExecutionGovernor(taskType);
+                if (taskType === "security_investigation") {
+                    ctx.state.evidenceTracker = new EvidenceTracker();
+                    ctx.state.workflowPhase = "investigate";
+                    ctx.state.workflowKey = "";
+                }
+                for (const reminder of ctx.state.governor.consumePendingReminders()) {
+                    ctx.queueReminder(reminder);
+                }
+                ctx.agent.compactResidentHistory();
+            },
+            beforeModelCall(ctx) {
+                ctx.agent.compactResidentHistory();
+                if (ctx.state.governor) {
+                    ctx.toolEntries = ctx.state.governor.filterToolDefinitions(ctx.toolEntries);
+                }
+                if (ctx.state.taskType === "security_investigation" && ctx.state.evidenceTracker && ctx.state.governor) {
+                    const coverage = ctx.state.evidenceTracker.snapshot();
+                    const phase = resolveWorkflowPhase({
+                        coreCoverageComplete: ctx.state.evidenceTracker.isCoreCoverageComplete(),
+                        searchFrozen: ctx.state.governor.snapshot().searchFrozen,
+                    });
+                    ctx.state.workflowPhase = phase;
+                    const summary = formatCoverageSummary(coverage);
+                    const key = `${phase}:${ctx.state.evidenceTracker.key()}:${ctx.state.governor.snapshot().searchFrozen ? "1" : "0"}`;
+                    if (ctx.state.workflowKey !== key) {
+                        ctx.state.workflowKey = key;
+                        ctx.queueReminder(buildWorkflowPhaseReminder({
+                            phase,
+                            covered: summary.covered,
+                            pending: summary.pending,
+                        }));
+                    }
+                }
+            },
+            afterTurn(ctx) {
+                ctx.agent.compactResidentHistory();
+            },
+        },
+        {
+            beforeToolCall(ctx) {
+                const arbitration = arbitrateToolCall(ctx.toolCall);
+                ctx.replaceToolCall({ ...arbitration.toolCall, ...(arbitration.note ? { arbiterNote: arbitration.note } : {}) });
+                const decision = ctx.state.governor?.beforeToolCall(ctx.toolCall);
+                if (decision?.blockedResult) {
+                    ctx.blockToolCall(decision.blockedResult);
+                }
+            },
+            afterToolCall(ctx) {
+                if (ctx.toolCall.arbiterNote) {
+                    ctx.replaceResult({
+                        ...ctx.result,
+                        metadata: {
+                            ...ctx.result.metadata,
+                            arbiterNote: ctx.toolCall.arbiterNote,
+                        },
+                    });
+                }
+                ctx.state.evidenceTracker?.observe(ctx.toolCall, ctx.result);
+                ctx.state.governor?.afterToolResult(ctx.toolCall, ctx.result);
+                if (ctx.toolCall.name === "task") {
+                    ctx.queueReminder(buildTaskSummaryReminder());
+                }
+                if (ctx.state.governor) {
+                    for (const reminder of ctx.state.governor.consumePendingReminders()) {
+                        ctx.queueReminder(reminder);
+                    }
+                }
+            },
+            beforeContinuation(ctx) {
+                if (ctx.state.taskType === "security_investigation" && ctx.state.evidenceTracker?.isCoreCoverageComplete()) {
+                    ctx.requestTextOnlyTurn("Core security investigation evidence has been collected. Summarize the findings instead of continuing with more tool calls.");
+                    return;
+                }
+                const allSearchResultsWereLowSignal = ctx.toolCalls.length > 0
+                    && ctx.toolCalls.every((toolCall) => ["glob", "grep", "bash", "web_search", "web_fetch"].includes(toolCall.name))
+                    && ctx.toolResults.every((result) => result.status === "no_match" || result.status === "blocked");
+                if (ctx.state.governor?.snapshot().searchFrozen && allSearchResultsWereLowSignal) {
+                    ctx.requestTextOnlyTurn("Search continuation has become low-yield. Summarize the strongest evidence already collected instead of continuing broad exploration.");
+                }
+            },
+        },
+    ];
+}

package/dist/orchestrator/hooks.d.ts

@@ -0,0 +1,78 @@
+import type { Agent } from "../agent.js";
+import type { ContentPart, ParsedToolCall, ToolRegistryEntry, ToolResult } from "../types.js";
+import type { TaskType } from "../agent/task-classifier.js";
+import type { ExecutionGovernor } from "../agent/execution-governor.js";
+import type { EvidenceTracker } from "../agent/evidence-tracker.js";
+import type { WorkflowPhase } from "./workflow.js";
+export interface TurnHookState {
+    taskType?: TaskType;
+    governor?: ExecutionGovernor;
+    evidenceTracker?: EvidenceTracker;
+    workflowPhase?: WorkflowPhase;
+    workflowKey?: string;
+    turnCount?: number;
+    forceTextOnlyReason?: string;
+    taskBudget?: {
+        total: number;
+        spent: number;
+    };
+}
+export interface TurnHookContext {
+    agent: Agent;
+    cwd: string;
+    input: string | ContentPart[];
+    state: TurnHookState;
+    queueReminder: (reminder: string) => void;
+    flushReminders: () => void;
+}
+export interface BeforeModelCallHookContext extends TurnHookContext {
+    toolEntries: ToolRegistryEntry[];
+    disableTools: (reason: string) => void;
+}
+export interface BeforeToolCallHookContext extends TurnHookContext {
+    toolCall: ParsedToolCall & {
+        arbiterNote?: string;
+    };
+    blockedResult?: ToolResult;
+    replaceToolCall: (toolCall: ParsedToolCall & {
+        arbiterNote?: string;
+    }) => void;
+    blockToolCall: (result: ToolResult) => void;
+}
+export interface AfterToolCallHookContext extends TurnHookContext {
+    toolCall: ParsedToolCall & {
+        arbiterNote?: string;
+    };
+    result: ToolResult;
+    replaceResult: (result: ToolResult) => void;
+}
+export interface BeforeContinuationHookContext extends TurnHookContext {
+    toolCalls: Array<ParsedToolCall & {
+        arbiterNote?: string;
+    }>;
+    toolResults: ToolResult[];
+    requestTextOnlyTurn: (reason: string) => void;
+}
+export interface TurnHooks {
+    beforeTurn?: (ctx: TurnHookContext) => void | Promise<void>;
+    beforeModelCall?: (ctx: BeforeModelCallHookContext) => void | Promise<void>;
+    beforeToolCall?: (ctx: BeforeToolCallHookContext) => void | Promise<void>;
+    afterToolCall?: (ctx: AfterToolCallHookContext) => void | Promise<void>;
+    beforeContinuation?: (ctx: BeforeContinuationHookContext) => void | Promise<void>;
+    afterTurn?: (ctx: TurnHookContext) => void | Promise<void>;
+}
+export declare class HookBus {
+    private beforeTurnHooks;
+    private beforeModelCallHooks;
+    private beforeToolCallHooks;
+    private afterToolCallHooks;
+    private beforeContinuationHooks;
+    private afterTurnHooks;
+    register(hooks: TurnHooks): void;
+    runBeforeTurn(ctx: TurnHookContext): Promise<void>;
+    runBeforeModelCall(ctx: BeforeModelCallHookContext): Promise<void>;
+    runBeforeToolCall(ctx: BeforeToolCallHookContext): Promise<void>;
+    runAfterToolCall(ctx: AfterToolCallHookContext): Promise<void>;
+    runBeforeContinuation(ctx: BeforeContinuationHookContext): Promise<void>;
+    runAfterTurn(ctx: TurnHookContext): Promise<void>;
+}

package/dist/orchestrator/hooks.js

@@ -0,0 +1,52 @@
+export class HookBus {
+    beforeTurnHooks = [];
+    beforeModelCallHooks = [];
+    beforeToolCallHooks = [];
+    afterToolCallHooks = [];
+    beforeContinuationHooks = [];
+    afterTurnHooks = [];
+    register(hooks) {
+        if (hooks.beforeTurn)
+            this.beforeTurnHooks.push(hooks.beforeTurn);
+        if (hooks.beforeModelCall)
+            this.beforeModelCallHooks.push(hooks.beforeModelCall);
+        if (hooks.beforeToolCall)
+            this.beforeToolCallHooks.push(hooks.beforeToolCall);
+        if (hooks.afterToolCall)
+            this.afterToolCallHooks.push(hooks.afterToolCall);
+        if (hooks.beforeContinuation)
+            this.beforeContinuationHooks.push(hooks.beforeContinuation);
+        if (hooks.afterTurn)
+            this.afterTurnHooks.push(hooks.afterTurn);
+    }
+    async runBeforeTurn(ctx) {
+        for (const hook of this.beforeTurnHooks) {
+            await hook(ctx);
+        }
+    }
+    async runBeforeModelCall(ctx) {
+        for (const hook of this.beforeModelCallHooks) {
+            await hook(ctx);
+        }
+    }
+    async runBeforeToolCall(ctx) {
+        for (const hook of this.beforeToolCallHooks) {
+            await hook(ctx);
+        }
+    }
+    async runAfterToolCall(ctx) {
+        for (const hook of this.afterToolCallHooks) {
+            await hook(ctx);
+        }
+    }
+    async runBeforeContinuation(ctx) {
+        for (const hook of this.beforeContinuationHooks) {
+            await hook(ctx);
+        }
+    }
+    async runAfterTurn(ctx) {
+        for (const hook of this.afterTurnHooks) {
+            await hook(ctx);
+        }
+    }
+}

package/dist/orchestrator/workflow.d.ts

@@ -0,0 +1,10 @@
+import type { InvestigationCoverage } from "../agent/evidence-tracker.js";
+export type WorkflowPhase = "investigate" | "correlate" | "conclude";
+export declare function resolveWorkflowPhase(input: {
+    coreCoverageComplete: boolean;
+    searchFrozen: boolean;
+}): WorkflowPhase;
+export declare function formatCoverageSummary(coverage: InvestigationCoverage): {
+    covered: string[];
+    pending: string[];
+};

package/dist/orchestrator/workflow.js

@@ -0,0 +1,22 @@
+export function resolveWorkflowPhase(input) {
+    if (input.coreCoverageComplete) {
+        return "conclude";
+    }
+    if (input.searchFrozen) {
+        return "correlate";
+    }
+    return "investigate";
+}
+export function formatCoverageSummary(coverage) {
+    const items = [
+        { label: "config load paths", done: coverage.configLoadPaths },
+        { label: "environment variable reads", done: coverage.envReads },
+        { label: "persistence paths", done: coverage.persistencePaths },
+        { label: "exposure paths", done: coverage.exposurePaths },
+        { label: "masking or redaction signals", done: coverage.maskingSignals },
+    ];
+    return {
+        covered: items.filter((item) => item.done).map((item) => item.label),
+        pending: items.filter((item) => !item.done).map((item) => item.label),
+    };
+}

package/dist/permission/mode.d.ts

@@ -0,0 +1,23 @@
+import type { PermissionMode } from "../types.js";
+/**
+ * Display metadata for each permission mode. Mirrors Claude Code's
+ * PERMISSION_MODE_CONFIG — kept narrow to what the TUI needs today.
+ */
+export interface PermissionModeInfo {
+    title: string;
+    shortTitle: string;
+    /** Single/double-char prefix shown in the footer badge. Empty = no badge. */
+    symbol: string;
+    /** Theme colour key. */
+    color: "muted" | "accent" | "success" | "warning" | "error";
+}
+export declare const PERMISSION_MODE_INFO: Record<PermissionMode, PermissionModeInfo>;
+/**
+ * Cycle order for the interactive mode keybind. This intentionally mirrors
+ * opencode's primary-agent switch: the keybind toggles Build and Plan only.
+ * Permission presets like acceptEdits/bypassPermissions remain opt-in through
+ * flags or commands and are never reached accidentally from Tab.
+ */
+export declare function getNextPermissionMode(current: PermissionMode, _options?: {
+    bypassEnabled?: boolean;
+}): PermissionMode;

package/dist/permission/mode.js

@@ -0,0 +1,20 @@
+export const PERMISSION_MODE_INFO = {
+    default: { title: "Default", shortTitle: "default", symbol: "", color: "muted" },
+    acceptEdits: { title: "Accept edits", shortTitle: "accept edits", symbol: "⏵⏵", color: "success" },
+    plan: { title: "Plan", shortTitle: "plan", symbol: "⏸", color: "accent" },
+    bypassPermissions: { title: "Bypass permissions", shortTitle: "bypass", symbol: "⏵⏵", color: "error" },
+    dontAsk: { title: "Do not ask", shortTitle: "silent", symbol: "·", color: "warning" },
+};
+/**
+ * Cycle order for the interactive mode keybind. This intentionally mirrors
+ * opencode's primary-agent switch: the keybind toggles Build and Plan only.
+ * Permission presets like acceptEdits/bypassPermissions remain opt-in through
+ * flags or commands and are never reached accidentally from Tab.
+ */
+export function getNextPermissionMode(current, _options = {}) {
+    if (current === "plan")
+        return "default";
+    if (current === "bypassPermissions" || current === "dontAsk")
+        return "default";
+    return "plan";
+}

package/dist/permissions/rule.d.ts

@@ -0,0 +1,39 @@
+import type { ParsedRule, PermissionCheckResult, PermissionDecision, PermissionQuery, PermissionRule, PermissionRuleSet } from "./types.js";
+/**
+ * Parse a single rule string, e.g. `Bash(git status:*)`.
+ *
+ * Whitespace around the whole expression is trimmed; whitespace inside the
+ * pattern is preserved (Bash patterns are tokenized later, paths may legitimately
+ * contain spaces inside globs).
+ */
+export declare function parseRule(input: string): ParsedRule;
+/**
+ * Parse a list of rule strings. Invalid entries are reported in `errors`; valid
+ * ones populate `rules`. Callers decide whether to surface errors or ignore.
+ */
+export declare function parseRules(inputs: string[]): {
+    rules: PermissionRule[];
+    errors: {
+        source: string;
+        message: string;
+    }[];
+};
+/**
+ * Does `rule` match `query`?
+ *
+ * Tool name must match (or rule.tool is "*"). If the rule has no pattern, it
+ * matches any use of that tool. Otherwise the tool-specific matcher decides.
+ */
+export declare function matchRule(rule: PermissionRule, query: PermissionQuery): boolean;
+/**
+ * Evaluate a rule set against a query. Deny wins; otherwise first allow wins;
+ * otherwise "ask".
+ */
+export declare function checkPermission(rules: PermissionRuleSet, query: PermissionQuery): PermissionCheckResult;
+/**
+ * Convenience: given raw `allow`/`deny` string arrays from settings, produce a
+ * ready-to-use rule set (silently dropping parse errors — callers that want
+ * diagnostics should call parseRules directly).
+ */
+export declare function buildRuleSet(allow: string[], deny: string[]): PermissionRuleSet;
+export type { PermissionDecision };

package/dist/permissions/rule.js

@@ -0,0 +1,234 @@
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+import picomatch from "picomatch";
+const KNOWN_TOOLS = new Set([
+    "Bash",
+    "Read",
+    "Write",
+    "Edit",
+    "Lsp",
+    "WebFetch",
+    "WebSearch",
+    "*",
+]);
+const RULE_SHAPE = /^([A-Za-z_*][A-Za-z0-9_]*)(?:\(([^)]*)\))?$/;
+/**
+ * Parse a single rule string, e.g. `Bash(git status:*)`.
+ *
+ * Whitespace around the whole expression is trimmed; whitespace inside the
+ * pattern is preserved (Bash patterns are tokenized later, paths may legitimately
+ * contain spaces inside globs).
+ */
+export function parseRule(input) {
+    const source = input;
+    const trimmed = input.trim();
+    if (!trimmed) {
+        return {
+            ok: false,
+            error: { source, message: "Rule is empty." },
+        };
+    }
+    const match = RULE_SHAPE.exec(trimmed);
+    if (!match) {
+        return {
+            ok: false,
+            error: {
+                source,
+                message: `Rule must look like "Tool" or "Tool(pattern)"; got: ${trimmed}`,
+            },
+        };
+    }
+    const tool = match[1];
+    const rawPattern = match[2];
+    if (tool !== "*" && !KNOWN_TOOLS.has(tool)) {
+        // Allow unknown tool names through — future MCP tools etc. can reuse this
+        // parser. But empty bodies with no paren and unknown names are fine too.
+    }
+    const pattern = rawPattern !== undefined ? rawPattern.trim() : undefined;
+    if (pattern !== undefined && pattern.length === 0) {
+        return {
+            ok: false,
+            error: {
+                source,
+                message: `Rule has empty parentheses; drop the parens to match all uses of ${tool}.`,
+            },
+        };
+    }
+    return {
+        ok: true,
+        rule: { tool, pattern, source },
+    };
+}
+/**
+ * Parse a list of rule strings. Invalid entries are reported in `errors`; valid
+ * ones populate `rules`. Callers decide whether to surface errors or ignore.
+ */
+export function parseRules(inputs) {
+    const rules = [];
+    const errors = [];
+    for (const input of inputs) {
+        const parsed = parseRule(input);
+        if (parsed.ok) {
+            rules.push(parsed.rule);
+        }
+        else {
+            errors.push(parsed.error);
+        }
+    }
+    return { rules, errors };
+}
+/**
+ * Does `rule` match `query`?
+ *
+ * Tool name must match (or rule.tool is "*"). If the rule has no pattern, it
+ * matches any use of that tool. Otherwise the tool-specific matcher decides.
+ */
+export function matchRule(rule, query) {
+    if (rule.tool !== "*" && rule.tool !== query.tool) {
+        return false;
+    }
+    if (rule.pattern === undefined) {
+        return true;
+    }
+    const toolKey = rule.tool === "*" ? query.tool : rule.tool;
+    switch (toolKey) {
+        case "Bash":
+            if (!("command" in query) || typeof query.command !== "string")
+                return false;
+            return matchBash(rule.pattern, query.command);
+        case "Read":
+        case "Write":
+        case "Edit":
+        case "Lsp":
+            if (!("path" in query) || !("cwd" in query))
+                return false;
+            return matchPath(rule.pattern, query.path, query.cwd);
+        case "WebFetch":
+            if (!("url" in query) || typeof query.url !== "string")
+                return false;
+            return matchDomain(rule.pattern, query.url);
+        case "WebSearch":
+            // WebSearch rules only support tool-level match for v1.
+            return false;
+        default:
+            // Unknown tool with a pattern: be conservative, don't match.
+            return false;
+    }
+}
+/**
+ * Evaluate a rule set against a query. Deny wins; otherwise first allow wins;
+ * otherwise "ask".
+ */
+export function checkPermission(rules, query) {
+    for (const rule of rules.deny) {
+        if (matchRule(rule, query)) {
+            return { decision: "deny", rule };
+        }
+    }
+    for (const rule of rules.allow) {
+        if (matchRule(rule, query)) {
+            return { decision: "allow", rule };
+        }
+    }
+    return { decision: "ask" };
+}
+// --- per-tool matchers ---------------------------------------------------
+/**
+ * Bash pattern matching.
+ *
+ * - `git status`     → command tokens equal ["git","status"] exactly
+ * - `git status:*`   → command tokens start with ["git","status"]
+ *
+ * Tokenization splits on whitespace. Shell control tokens (`&&`, `|`, `;`) are
+ * treated as plain tokens; a rule that includes them would have to match them
+ * literally. v1 does not try to parse shell grammar.
+ */
+function matchBash(pattern, command) {
+    const cmdTokens = tokenize(command);
+    let ruleTokens = tokenize(pattern);
+    let prefixMatch = false;
+    if (ruleTokens.length > 0) {
+        const last = ruleTokens[ruleTokens.length - 1];
+        if (last === ":*") {
+            prefixMatch = true;
+            ruleTokens = ruleTokens.slice(0, -1);
+        }
+        else if (last.endsWith(":*")) {
+            prefixMatch = true;
+            ruleTokens = ruleTokens.slice(0, -1).concat([last.slice(0, -2)]);
+        }
+    }
+    if (ruleTokens.length === 0) {
+        return prefixMatch; // `Bash(:*)` would match anything; keep behavior defined
+    }
+    if (prefixMatch) {
+        if (ruleTokens.length > cmdTokens.length)
+            return false;
+        return ruleTokens.every((tok, i) => tok === cmdTokens[i]);
+    }
+    if (ruleTokens.length !== cmdTokens.length)
+        return false;
+    return ruleTokens.every((tok, i) => tok === cmdTokens[i]);
+}
+/**
+ * Path pattern matching via picomatch (glob). The rule pattern is expanded for
+ * `~` (home) and resolved relative to cwd if not absolute. The query path is
+ * resolved the same way to compare canonical absolute paths.
+ */
+function matchPath(pattern, queryPath, cwd) {
+    const expandedPattern = expandHome(pattern);
+    const absolutePattern = isAbsolute(expandedPattern)
+        ? expandedPattern
+        : resolve(cwd, expandedPattern);
+    const absoluteQuery = isAbsolute(queryPath)
+        ? queryPath
+        : resolve(cwd, queryPath);
+    const matcher = picomatch(absolutePattern, { dot: true });
+    return matcher(absoluteQuery);
+}
+/**
+ * WebFetch domain matching. Pattern must be `domain:<host>`. Match is true if
+ * the URL host equals `<host>` or is a subdomain of it.
+ *
+ *   domain:github.com → matches https://github.com/... and https://api.github.com/...
+ */
+function matchDomain(pattern, url) {
+    const prefix = "domain:";
+    if (!pattern.startsWith(prefix))
+        return false;
+    const expectedHost = pattern.slice(prefix.length).trim().toLowerCase();
+    if (!expectedHost)
+        return false;
+    let host;
+    try {
+        host = new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+    if (host === expectedHost)
+        return true;
+    return host.endsWith("." + expectedHost);
+}
+// --- small helpers -------------------------------------------------------
+function tokenize(input) {
+    return input.trim().split(/\s+/).filter(Boolean);
+}
+function expandHome(p) {
+    if (p === "~")
+        return homedir();
+    if (p.startsWith("~/"))
+        return resolve(homedir(), p.slice(2));
+    return p;
+}
+/**
+ * Convenience: given raw `allow`/`deny` string arrays from settings, produce a
+ * ready-to-use rule set (silently dropping parse errors — callers that want
+ * diagnostics should call parseRules directly).
+ */
+export function buildRuleSet(allow, deny) {
+    return {
+        allow: parseRules(allow).rules,
+        deny: parseRules(deny).rules,
+    };
+}

package/dist/permissions/settings.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Persistent permission settings.
+ *
+ * Three scopes, lowest to highest precedence:
+ *
+ *   user    — ~/.bubble/settings.json            (cross-project preferences)
+ *   project — <cwd>/.bubble/settings.json        (team-shared, check into git)
+ *   local   — <cwd>/.bubble/settings.local.json  (personal, gitignore)
+ *
+ * `defaultMode` uses last-wins precedence (local beats project beats user).
+ * `allow` / `deny` arrays are concatenated across scopes (with the rule text
+ * itself carrying provenance via `PermissionRule.source`).
+ *
+ * Parse errors do not fail the load; they collect into `diagnostics` so callers
+ * can surface them in /permissions or on startup without taking the agent down.
+ */
+import type { PermissionMode } from "../types.js";
+import { type LspConfig } from "../lsp/config.js";
+import type { PermissionRuleSet } from "./types.js";
+export type SettingsScope = "user" | "project" | "local";
+export type RuleList = "allow" | "deny";
+export interface RawSettings {
+    lsp?: unknown;
+    permissions?: {
+        defaultMode?: string;
+        allow?: string[];
+        deny?: string[];
+    };
+}
+export interface SettingsDiagnostic {
+    scope: SettingsScope;
+    path: string;
+    message: string;
+}
+export interface MergedSettings {
+    defaultMode?: PermissionMode;
+    lsp?: LspConfig;
+    ruleSet: PermissionRuleSet;
+    diagnostics: SettingsDiagnostic[];
+}
+export interface SettingsManagerOptions {
+    /** Override for Bubble home. Respects BUBBLE_HOME/BUBBLE_DEV env vars by default. */
+    bubbleHome?: string;
+}
+export declare class SettingsManager {
+    private readonly cwd;
+    private readonly paths;
+    private raw;
+    private fileDiagnostics;
+    constructor(cwd: string, options?: SettingsManagerOptions);
+    /** Re-read all three files from disk. */
+    reload(): void;
+    getPath(scope: SettingsScope): string;
+    /** Merged view for runtime consumption. Does not hit disk — call `reload()` first if stale. */
+    getMerged(): MergedSettings;
+    /**
+     * Add a rule to the specified list in the specified scope. Creates the file
+     * and parent directories if needed. Silently skips if the exact string is
+     * already present.
+     *
+     * Returns true if the file was written.
+     */
+    addRule(scope: SettingsScope, list: RuleList, rule: string): boolean;
+    /**
+     * Remove the first matching rule (by exact string) from the specified list
+     * in the specified scope. Returns true if a rule was removed.
+     */
+    removeRule(scope: SettingsScope, list: RuleList, rule: string): boolean;
+    private readFile;
+    private writeFile;
+}