@bubblebrain-ai/bubble 0.0.1

package/dist/approval/controller.d.ts

@@ -0,0 +1,48 @@
+import type { PermissionCheckResult, PermissionQuery, PermissionRuleSet } from "../permissions/types.js";
+import type { PermissionMode } from "../types.js";
+import type { BashAllowlist } from "./session-cache.js";
+import type { ApprovalController, ApprovalDecision, ApprovalRequest } from "./types.js";
+export interface ApprovalControllerOptions {
+    /** Reads the live agent mode on each request so mode flips take effect immediately. */
+    getMode: () => PermissionMode;
+    /**
+     * UI handler attached by the TUI on mount. Returns the user's decision from
+     * an interactive dialog. When not attached (e.g. --print mode), the
+     * controller falls back to rejecting in safe modes.
+     */
+    handlerRef: {
+        current?: (req: ApprovalRequest) => Promise<ApprovalDecision>;
+    };
+    /** Session-scoped bash command prefix allowlist. Optional. */
+    bashAllowlist?: BashAllowlist;
+    /** Working directory — used to anchor relative path rules. */
+    cwd: string;
+    /**
+     * Live view of configured allow/deny rules (from ~/.bubble/settings.json and
+     * project-level equivalents). Called on each request so edits via
+     * /permissions take effect immediately. Omit to disable rule-based gating.
+     */
+    getRuleSet?: () => PermissionRuleSet;
+}
+/**
+ * Default ApprovalController. Decision tree:
+ *
+ *   deny rule match              → reject (applies even under bypassPermissions)
+ *   bypassPermissions / dontAsk  → auto-approve, no prompt
+ *   acceptEdits + edit|write     → auto-approve
+ *   plan                         → reject with instructions to use exit_plan_mode
+ *   allow rule match             → auto-approve
+ *   bash in session allowlist    → auto-approve
+ *   default / other              → delegate to UI; if no UI, reject
+ *
+ * Deny rules sit at the top as a hard ceiling: bypassPermissions is a trust
+ * escalation, not a policy override. Users who want to permit a currently-
+ * denied action must edit their settings.json, not bypass checks at runtime.
+ */
+export declare class PermissionAwareApprovalController implements ApprovalController {
+    private readonly options;
+    constructor(options: ApprovalControllerOptions);
+    checkRules(query: PermissionQuery): PermissionCheckResult;
+    request(req: ApprovalRequest): Promise<ApprovalDecision>;
+    private requestToQuery;
+}

package/dist/approval/controller.js

@@ -0,0 +1,78 @@
+import { checkPermission } from "../permissions/rule.js";
+/**
+ * Default ApprovalController. Decision tree:
+ *
+ *   deny rule match              → reject (applies even under bypassPermissions)
+ *   bypassPermissions / dontAsk  → auto-approve, no prompt
+ *   acceptEdits + edit|write     → auto-approve
+ *   plan                         → reject with instructions to use exit_plan_mode
+ *   allow rule match             → auto-approve
+ *   bash in session allowlist    → auto-approve
+ *   default / other              → delegate to UI; if no UI, reject
+ *
+ * Deny rules sit at the top as a hard ceiling: bypassPermissions is a trust
+ * escalation, not a policy override. Users who want to permit a currently-
+ * denied action must edit their settings.json, not bypass checks at runtime.
+ */
+export class PermissionAwareApprovalController {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    checkRules(query) {
+        const ruleSet = this.options.getRuleSet?.();
+        if (!ruleSet)
+            return { decision: "ask" };
+        return checkPermission(ruleSet, query);
+    }
+    async request(req) {
+        const query = this.requestToQuery(req);
+        const ruleResult = this.checkRules(query);
+        if (ruleResult.decision === "deny") {
+            return {
+                action: "reject",
+                feedback: `Blocked by deny rule: ${ruleResult.rule?.source ?? "<unknown>"}`,
+            };
+        }
+        const mode = this.options.getMode();
+        if (mode === "bypassPermissions" || mode === "dontAsk") {
+            return { action: "approve" };
+        }
+        if (mode === "acceptEdits" && (req.type === "edit" || req.type === "write")) {
+            return { action: "approve" };
+        }
+        if (mode === "plan") {
+            return {
+                action: "reject",
+                feedback: "Plan mode is active. Do not call destructive tools directly — propose your changes via exit_plan_mode and wait for user approval.",
+            };
+        }
+        if (ruleResult.decision === "allow") {
+            return { action: "approve" };
+        }
+        // Session-scoped allowlist: previously-approved bash prefixes skip the prompt.
+        if (req.type === "bash" && this.options.bashAllowlist?.matches(req.command)) {
+            return { action: "approve" };
+        }
+        const handler = this.options.handlerRef.current;
+        if (!handler) {
+            return {
+                action: "reject",
+                feedback: "No interactive UI is available to approve this tool call.",
+            };
+        }
+        return handler(req);
+    }
+    requestToQuery(req) {
+        switch (req.type) {
+            case "bash":
+                return { tool: "Bash", command: req.command };
+            case "write":
+                return { tool: "Write", path: req.path, cwd: this.options.cwd };
+            case "edit":
+                return { tool: "Edit", path: req.path, cwd: this.options.cwd };
+            case "lsp":
+                return { tool: "Lsp", path: req.path, cwd: this.options.cwd };
+        }
+    }
+}

package/dist/approval/danger.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Heuristic classifier for bash commands that deserve an extra user warning.
+ *
+ * Conservative by design: false negatives are fine (users are still prompted
+ * to approve), false positives are annoying (users get desensitised to the
+ * warning). We only flag patterns that are widely recognised as destructive
+ * or commonly abused by injected prompts.
+ */
+export interface DangerSignal {
+    pattern: string;
+    message: string;
+}
+export declare function classifyBashDanger(command: string): DangerSignal | null;

package/dist/approval/danger.js

@@ -0,0 +1,55 @@
+/**
+ * Heuristic classifier for bash commands that deserve an extra user warning.
+ *
+ * Conservative by design: false negatives are fine (users are still prompted
+ * to approve), false positives are annoying (users get desensitised to the
+ * warning). We only flag patterns that are widely recognised as destructive
+ * or commonly abused by injected prompts.
+ */
+export function classifyBashDanger(command) {
+    const normalized = command.trim();
+    if (!normalized)
+        return null;
+    // Piping an internet download into a shell — classic supply-chain foot-gun.
+    if (/\b(curl|wget|fetch)\b[^|]*\|\s*(bash|sh|zsh|fish)\b/i.test(normalized)) {
+        return {
+            pattern: "curl | sh",
+            message: "This command pipes a downloaded script directly into a shell.",
+        };
+    }
+    // Recursive force delete. Match `rm -rf`, `rm -fr`, `rm -Rf`, etc.
+    if (/\brm\s+(-[a-zA-Z]*[rR][a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*[rR])\b/.test(normalized)) {
+        return {
+            pattern: "rm -rf",
+            message: "This command recursively deletes files and directories.",
+        };
+    }
+    // Privilege escalation.
+    if (/\bsudo\b/.test(normalized)) {
+        return {
+            pattern: "sudo",
+            message: "This command runs with elevated privileges.",
+        };
+    }
+    // chmod 777 and friends.
+    if (/\bchmod\s+(-R\s+)?(0?777|a\+rwx|u\+rwx,g\+rwx,o\+rwx)\b/.test(normalized)) {
+        return {
+            pattern: "chmod 777",
+            message: "This command gives world-writable permissions.",
+        };
+    }
+    // Git force push / reset hard — potentially destructive on shared branches.
+    if (/\bgit\s+push\s+(-f\b|--force\b|--force-with-lease\b)/.test(normalized)) {
+        return {
+            pattern: "git push --force",
+            message: "This force-pushes and can overwrite the remote branch history.",
+        };
+    }
+    if (/\bgit\s+reset\s+--hard\b/.test(normalized)) {
+        return {
+            pattern: "git reset --hard",
+            message: "This discards uncommitted changes and rewrites the working tree.",
+        };
+    }
+    return null;
+}

package/dist/approval/diff-hunks.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Parses unified-diff output (e.g. from `diff`'s `createTwoFilesPatch`) into
+ * discrete hunks so the TUI can render each one with its own header and fold
+ * gracefully when the total body exceeds the available line budget.
+ */
+export interface DiffHunk {
+    /** The `@@ -old,count +new,count @@ ...` line verbatim. */
+    header: string;
+    /** Body lines, each beginning with '+', '-', or ' '. No trailing newline. */
+    lines: string[];
+}
+export declare function parseDiffHunks(diff: string): DiffHunk[];

package/dist/approval/diff-hunks.js

@@ -0,0 +1,32 @@
+/**
+ * Parses unified-diff output (e.g. from `diff`'s `createTwoFilesPatch`) into
+ * discrete hunks so the TUI can render each one with its own header and fold
+ * gracefully when the total body exceeds the available line budget.
+ */
+export function parseDiffHunks(diff) {
+    const hunks = [];
+    const rawLines = diff.split("\n");
+    let current = null;
+    for (const line of rawLines) {
+        if (line.startsWith("===") ||
+            line.startsWith("Index:") ||
+            line.startsWith("---") ||
+            line.startsWith("+++")) {
+            continue;
+        }
+        if (line.startsWith("@@")) {
+            if (current)
+                hunks.push(current);
+            current = { header: line, lines: [] };
+            continue;
+        }
+        if (!current)
+            continue;
+        if (line.startsWith("\\ No newline"))
+            continue;
+        current.lines.push(line);
+    }
+    if (current)
+        hunks.push(current);
+    return hunks;
+}

package/dist/approval/session-cache.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Session-scoped allowlist of bash command prefixes. Not persisted to disk.
+ *
+ * Matching rule: a command is allowed if it starts with one of the stored
+ * prefixes and the next character is either end-of-string or whitespace.
+ * This means the prefix "git status" will match "git status" and
+ * "git status -s", but NOT "git statuss" or "git statusbad".
+ *
+ * For ergonomic parity with Claude Code we also strip a trailing ":*" when
+ * storing so that users may type "npm run:*" as a pattern — functionally
+ * equivalent to just "npm run" under our simple prefix rule.
+ */
+export declare class BashAllowlist {
+    private prefixes;
+    add(prefix: string): void;
+    remove(prefix: string): boolean;
+    clear(): void;
+    matches(command: string): boolean;
+    list(): string[];
+    size(): number;
+}
+/**
+ * Infers a reasonable "don't ask again" prefix from a bash command. Uses the
+ * first two whitespace-separated tokens when the second token looks like a
+ * subcommand (no leading `-` or `/`), otherwise falls back to the first token.
+ * Examples:
+ *   "git status -s"     → "git status"
+ *   "git status"        → "git status"
+ *   "git"               → "git"
+ *   "npm run test"      → "npm run"
+ *   "npm test"          → "npm test"
+ *   "rm -rf /tmp/x"     → "rm"
+ *   "./scripts/foo.sh"  → "./scripts/foo.sh"
+ */
+export declare function inferBashPrefix(command: string): string;

package/dist/approval/session-cache.js

@@ -0,0 +1,68 @@
+/**
+ * Session-scoped allowlist of bash command prefixes. Not persisted to disk.
+ *
+ * Matching rule: a command is allowed if it starts with one of the stored
+ * prefixes and the next character is either end-of-string or whitespace.
+ * This means the prefix "git status" will match "git status" and
+ * "git status -s", but NOT "git statuss" or "git statusbad".
+ *
+ * For ergonomic parity with Claude Code we also strip a trailing ":*" when
+ * storing so that users may type "npm run:*" as a pattern — functionally
+ * equivalent to just "npm run" under our simple prefix rule.
+ */
+export class BashAllowlist {
+    prefixes = new Set();
+    add(prefix) {
+        const cleaned = prefix.trim().replace(/:\*$/, "").trim();
+        if (!cleaned)
+            return;
+        this.prefixes.add(cleaned);
+    }
+    remove(prefix) {
+        return this.prefixes.delete(prefix.trim());
+    }
+    clear() {
+        this.prefixes.clear();
+    }
+    matches(command) {
+        const trimmed = command.trim();
+        for (const prefix of this.prefixes) {
+            if (trimmed === prefix)
+                return true;
+            if (trimmed.startsWith(prefix) && /\s/.test(trimmed.charAt(prefix.length))) {
+                return true;
+            }
+        }
+        return false;
+    }
+    list() {
+        return [...this.prefixes].sort();
+    }
+    size() {
+        return this.prefixes.size;
+    }
+}
+/**
+ * Infers a reasonable "don't ask again" prefix from a bash command. Uses the
+ * first two whitespace-separated tokens when the second token looks like a
+ * subcommand (no leading `-` or `/`), otherwise falls back to the first token.
+ * Examples:
+ *   "git status -s"     → "git status"
+ *   "git status"        → "git status"
+ *   "git"               → "git"
+ *   "npm run test"      → "npm run"
+ *   "npm test"          → "npm test"
+ *   "rm -rf /tmp/x"     → "rm"
+ *   "./scripts/foo.sh"  → "./scripts/foo.sh"
+ */
+export function inferBashPrefix(command) {
+    const tokens = command.trim().split(/\s+/);
+    if (tokens.length === 0 || !tokens[0])
+        return "";
+    const first = tokens[0];
+    const second = tokens[1];
+    if (second && /^[A-Za-z_]/.test(second)) {
+        return `${first} ${second}`;
+    }
+    return first;
+}

package/dist/approval/tool-helper.d.ts

@@ -0,0 +1,14 @@
+import type { ToolResult } from "../types.js";
+import type { ApprovalController, ApprovalDecision, ApprovalRequest } from "./types.js";
+/**
+ * Runs a tool action through the approval controller. Returns either the
+ * decision (on approve) or a pre-built rejection ToolResult (on reject or
+ * no controller available to the tool).
+ */
+export declare function gateToolAction(approval: ApprovalController | undefined, req: ApprovalRequest): Promise<{
+    approved: true;
+    decision: ApprovalDecision;
+} | {
+    approved: false;
+    result: ToolResult;
+}>;

package/dist/approval/tool-helper.js

@@ -0,0 +1,32 @@
+/**
+ * Runs a tool action through the approval controller. Returns either the
+ * decision (on approve) or a pre-built rejection ToolResult (on reject or
+ * no controller available to the tool).
+ */
+export async function gateToolAction(approval, req) {
+    if (!approval) {
+        return { approved: true, decision: { action: "approve" } };
+    }
+    const decision = await approval.request(req);
+    if (decision.action === "approve") {
+        return { approved: true, decision };
+    }
+    const feedback = decision.feedback?.trim();
+    const label = approvalRequestLabel(req);
+    const message = feedback
+        ? `${label} was rejected by the user. User feedback: ${feedback}`
+        : `${label} was rejected by the user.`;
+    return { approved: false, result: { content: message, isError: true } };
+}
+function approvalRequestLabel(req) {
+    switch (req.type) {
+        case "edit":
+            return `Edit to ${req.path}`;
+        case "write":
+            return `${req.fileExists ? "Overwrite" : "Write"} to ${req.path}`;
+        case "bash":
+            return `Bash command \`${req.command}\``;
+        case "lsp":
+            return `LSP ${req.operation} on ${req.path}`;
+    }
+}

package/dist/approval/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Approval flow: tools that want a gating UI construct an ApprovalRequest and
+ * await an ApprovalDecision from the harness (via ApprovalController).
+ *
+ * Mirrors Claude Code's per-tool Permission Request components in that each
+ * request carries tool-typed data so the UI can render a meaningful preview.
+ */
+import type { PermissionCheckResult, PermissionQuery } from "../permissions/types.js";
+export interface EditApprovalRequest {
+    type: "edit";
+    path: string;
+    /** Unified patch (with context lines) to show the user. */
+    diff: string;
+    fileExists: boolean;
+}
+export interface WriteApprovalRequest {
+    type: "write";
+    path: string;
+    /** Full pending file contents. */
+    content: string;
+    /** Unified patch from existing contents to pending contents. */
+    diff?: string;
+    fileExists: boolean;
+}
+export interface BashApprovalRequest {
+    type: "bash";
+    command: string;
+    cwd: string;
+}
+export interface LspApprovalRequest {
+    type: "lsp";
+    path: string;
+    operation: string;
+}
+export type ApprovalRequest = EditApprovalRequest | WriteApprovalRequest | BashApprovalRequest | LspApprovalRequest;
+export type ApprovalDecision = {
+    action: "approve";
+    feedback?: string;
+} | {
+    action: "reject";
+    feedback?: string;
+};
+export interface ApprovalController {
+    /**
+     * Decide whether a tool call should proceed. May consult the current
+     * permission mode, configured allow/deny rules, session-level allowlists,
+     * and — as a final fallback — a user-interactive UI handler.
+     */
+    request(req: ApprovalRequest): Promise<ApprovalDecision>;
+    /**
+     * Pure rule evaluation (no UI, no mode gates). Tools that silently execute
+     * unless explicitly denied (e.g. Read, WebFetch) call this to honor
+     * user-configured deny rules without changing the UX for the common case.
+     */
+    checkRules(query: PermissionQuery): PermissionCheckResult;
+}

package/dist/approval/types.js

@@ -0,0 +1,8 @@
+/**
+ * Approval flow: tools that want a gating UI construct an ApprovalRequest and
+ * await an ApprovalDecision from the harness (via ApprovalController).
+ *
+ * Mirrors Claude Code's per-tool Permission Request components in that each
+ * request carries tool-typed data so the UI can render a meaningful preview.
+ */
+export {};

package/dist/bubble-home.d.ts

@@ -0,0 +1,8 @@
+export type BubbleEnvironment = "production" | "dev" | "custom";
+export interface BubbleHomeInfo {
+    home: string;
+    environment: BubbleEnvironment;
+}
+export declare function getBubbleHome(): string;
+export declare function getBubbleHomeInfo(): BubbleHomeInfo;
+export declare function isBubbleDevMode(): boolean;

package/dist/bubble-home.js

@@ -0,0 +1,19 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function getBubbleHome() {
+    return getBubbleHomeInfo().home;
+}
+export function getBubbleHomeInfo() {
+    const explicitHome = process.env.BUBBLE_HOME?.trim();
+    if (explicitHome) {
+        return { home: explicitHome, environment: "custom" };
+    }
+    if (isBubbleDevMode()) {
+        return { home: join(homedir(), ".bubble-dev"), environment: "dev" };
+    }
+    return { home: join(homedir(), ".bubble"), environment: "production" };
+}
+export function isBubbleDevMode() {
+    const value = process.env.BUBBLE_DEV?.trim().toLowerCase();
+    return value === "1" || value === "true" || value === "yes" || value === "on";
+}

package/dist/cli.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CLI argument parsing.
+ */
+import type { PermissionMode, ThinkingLevel } from "./types.js";
+export interface CliArgs {
+    model?: string;
+    cwd: string;
+    apiKey?: string;
+    resume?: boolean;
+    sessionName?: string;
+    print?: boolean;
+    prompt?: string;
+    thinkingLevel?: ThinkingLevel;
+    mode?: PermissionMode;
+    /** When true, --dangerously-skip-permissions was passed; bypassPermissions is reachable via the mode cycle and auto-approves every tool. */
+    bypassEnabled?: boolean;
+}
+export declare function parseArgs(argv: string[]): CliArgs;
+export declare function printHelp(): void;

package/dist/cli.js

@@ -0,0 +1,82 @@
+/**
+ * CLI argument parsing.
+ */
+import { isThinkingLevel } from "./variant/thinking-level.js";
+export function parseArgs(argv) {
+    const args = {
+        cwd: process.cwd(),
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--model":
+            case "-m":
+                args.model = argv[++i];
+                break;
+            case "--cwd":
+                args.cwd = argv[++i];
+                break;
+            case "--api-key":
+            case "-k":
+                args.apiKey = argv[++i];
+                break;
+            case "--resume":
+            case "-r":
+                args.resume = true;
+                break;
+            case "--session":
+                args.sessionName = argv[++i];
+                break;
+            case "--reasoning":
+                args.thinkingLevel = "medium";
+                break;
+            case "--reasoning-effort": {
+                const value = argv[++i];
+                if (isThinkingLevel(value)) {
+                    args.thinkingLevel = value;
+                }
+                break;
+            }
+            case "--print":
+            case "-p":
+                args.print = true;
+                break;
+            case "--plan":
+                args.mode = "plan";
+                break;
+            case "--accept-edits":
+                args.mode = "acceptEdits";
+                break;
+            case "--dangerously-skip-permissions":
+                args.bypassEnabled = true;
+                args.mode = "bypassPermissions";
+                break;
+            default:
+                if (!arg.startsWith("-") && !args.prompt) {
+                    args.prompt = arg;
+                }
+                break;
+        }
+    }
+    return args;
+}
+export function printHelp() {
+    console.log(`
+Usage: bubble [options] [prompt]
+
+Options:
+  -m, --model <model>      Model to use
+  --cwd <dir>              Working directory (default: current)
+  -k, --api-key <key>      API key for the active provider
+  -r, --resume             Resume a previous session (latest by default)
+  --session <name>         Session name to create or resume
+  --reasoning              Enable reasoning mode at medium effort
+  --reasoning-effort <l>   Set reasoning effort: off|minimal|low|medium|high|xhigh|max
+  --plan                   Start in plan mode (read-only investigation; propose before executing)
+  --accept-edits           Start with edits/writes auto-approved (bash still prompts)
+  --dangerously-skip-permissions
+                           Enable bypass mode (auto-approve EVERY tool; disables all safety prompts)
+  -p, --print              Non-interactive mode (single prompt)
+  -h, --help               Show this help
+`);
+}

package/dist/config.d.ts

@@ -0,0 +1,41 @@
+/**
+ * User-level configuration manager.
+ *
+ * Uses a single JSON file in Bubble home, normally ~/.bubble/config.json.
+ */
+import type { ProviderProfile } from "./provider-registry.js";
+import type { ThinkingLevel } from "./types.js";
+export interface UserConfigData {
+    defaultModel?: string;
+    defaultThinkingLevel?: ThinkingLevel;
+    skillPaths?: string[];
+    theme?: Record<string, string>;
+    recentModels?: string[];
+    apiKey?: string;
+    providers?: ProviderProfile[];
+    defaultProvider?: string;
+}
+export declare class UserConfig {
+    private data;
+    constructor();
+    private load;
+    private save;
+    getDefaultModel(): string | undefined;
+    setDefaultModel(model: string): void;
+    getDefaultThinkingLevel(): ThinkingLevel | undefined;
+    setDefaultThinkingLevel(level: ThinkingLevel): void;
+    getRecentModels(): string[];
+    pushRecentModel(model: string): void;
+    getApiKey(): string | undefined;
+    setApiKey(key: string): void;
+    getProviders(): ProviderProfile[];
+    setProviders(providers: ProviderProfile[]): void;
+    getDefaultProvider(): string | undefined;
+    setDefaultProvider(id: string): void;
+    getSkillPaths(): string[];
+    setSkillPaths(paths: string[]): void;
+    getTheme(): Record<string, string>;
+    setTheme(theme: Record<string, string>): void;
+}
+/** Mask an API key for safe display. */
+export declare function maskKey(key: string): string;