@bubblebrain-ai/bubble 0.0.63 → 0.0.64

package/dist/skills/discovery.js

@@ -0,0 +1,166 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { parseFrontmatter } from "./frontmatter.js";
+export function discoverSkills(options) {
+    const diagnostics = [];
+    const skills = [];
+    const seenNames = new Map();
+    for (const root of options.roots) {
+        if (!existsSync(root.path))
+            continue;
+        let entries = [];
+        try {
+            entries = readdirSync(root.path);
+        }
+        catch (error) {
+            diagnostics.push({
+                level: "warning",
+                filePath: root.path,
+                message: `Failed to read skill root: ${error.message || String(error)}`,
+            });
+            continue;
+        }
+        for (const entry of entries) {
+            const entryPath = join(root.path, entry);
+            let stat;
+            try {
+                stat = statSync(entryPath);
+            }
+            catch {
+                continue;
+            }
+            if (!stat.isDirectory())
+                continue;
+            const skillFile = join(entryPath, "SKILL.md");
+            if (!existsSync(skillFile))
+                continue;
+            const parsed = loadSkillRecord(skillFile, root.source);
+            diagnostics.push(...parsed.diagnostics);
+            if (!parsed.skill)
+                continue;
+            const existing = seenNames.get(parsed.skill.meta.name);
+            if (existing) {
+                diagnostics.push({
+                    level: "error",
+                    skillName: parsed.skill.meta.name,
+                    filePath: skillFile,
+                    message: `Duplicate skill name "${parsed.skill.meta.name}" already defined at ${existing}`,
+                });
+                continue;
+            }
+            seenNames.set(parsed.skill.meta.name, skillFile);
+            skills.push(parsed.skill);
+        }
+    }
+    skills.sort((a, b) => a.meta.name.localeCompare(b.meta.name));
+    return { skills, diagnostics };
+}
+function loadSkillRecord(skillFile, source) {
+    const diagnostics = [];
+    let raw = "";
+    try {
+        raw = readFileSync(skillFile, "utf8");
+    }
+    catch (error) {
+        diagnostics.push({
+            level: "error",
+            filePath: skillFile,
+            message: `Failed to read skill file: ${error.message || String(error)}`,
+        });
+        return { diagnostics };
+    }
+    const { attributes, body } = parseFrontmatter(raw);
+    const rootDir = skillFile.slice(0, -"/SKILL.md".length);
+    const fallbackName = basename(rootDir);
+    const meta = normalizeMeta(attributes, fallbackName, skillFile, diagnostics);
+    if (!meta) {
+        return { diagnostics };
+    }
+    return {
+        skill: {
+            meta,
+            rootDir,
+            skillFile,
+            content: body.trim(),
+            resources: indexResources(rootDir),
+            source,
+        },
+        diagnostics,
+    };
+}
+function normalizeMeta(attributes, fallbackName, filePath, diagnostics) {
+    const name = typeof attributes.name === "string" && attributes.name.trim() ? attributes.name.trim() : fallbackName;
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name)) {
+        diagnostics.push({
+            level: "error",
+            skillName: name,
+            filePath,
+            message: `Invalid skill name "${name}"`,
+        });
+        return undefined;
+    }
+    const description = typeof attributes.description === "string" ? attributes.description.trim() : "";
+    if (!description) {
+        diagnostics.push({
+            level: "error",
+            skillName: name,
+            filePath,
+            message: "Skill description is required",
+        });
+        return undefined;
+    }
+    const tags = Array.isArray(attributes.tags)
+        ? attributes.tags.filter((item) => typeof item === "string" && !!item.trim()).map((item) => item.trim())
+        : undefined;
+    const author = typeof attributes.author === "string" && attributes.author.trim()
+        ? attributes.author.trim()
+        : undefined;
+    const allowedTools = normalizeStringList(attributes["allowed-tools"] ?? attributes.allowedTools);
+    return {
+        name,
+        description,
+        disableModelInvocation: attributes["disable-model-invocation"] === true,
+        version: typeof attributes.version === "number" ? attributes.version : undefined,
+        tags: tags && tags.length > 0 ? tags : undefined,
+        author,
+        allowedTools,
+    };
+}
+function normalizeStringList(value) {
+    const raw = Array.isArray(value)
+        ? value
+        : typeof value === "string"
+            ? value.trim().replace(/^\[(.*)\]$/, "$1").split(",")
+            : [];
+    const items = raw
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    return items.length > 0 ? [...new Set(items)] : undefined;
+}
+function indexResources(rootDir) {
+    return {
+        references: listRelativeFiles(join(rootDir, "references"), rootDir),
+        scripts: listRelativeFiles(join(rootDir, "scripts"), rootDir),
+        assets: listRelativeFiles(join(rootDir, "assets"), rootDir),
+    };
+}
+function listRelativeFiles(targetDir, rootDir) {
+    if (!existsSync(targetDir))
+        return [];
+    const results = [];
+    walkDir(targetDir, rootDir, results);
+    results.sort((a, b) => a.localeCompare(b));
+    return results;
+}
+function walkDir(targetDir, rootDir, results) {
+    for (const entry of readdirSync(targetDir)) {
+        const fullPath = join(targetDir, entry);
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+            walkDir(fullPath, rootDir, results);
+            continue;
+        }
+        results.push(fullPath.slice(rootDir.length + 1).replace(/\\/g, "/"));
+    }
+}

package/dist/skills/format.d.ts

@@ -0,0 +1,32 @@
+import type { SkillSummary } from "./types.js";
+/** Default size of the always-present skill catalog (the listed lines, not the header). */
+export declare const SKILL_CATALOG_CHARS = 12000;
+/** Each description is cut to this length; it only has to tell the model when to load. */
+export declare const SKILL_CATALOG_DESC_CHARS = 120;
+export declare const SKILL_CATALOG_HEADING = "## Skills";
+/** First line under the heading; together they mark the catalog unambiguously. */
+export declare const SKILL_CATALOG_INTRO = "Skills are task-specific instructions loaded on demand. When a task matches a skill below, call `skill` with its exact name before starting, then follow it. Load only what clearly applies.";
+export interface SkillCatalogOptions {
+    /** Budget for the listed lines; 0 turns the catalog off. */
+    budgetChars?: number;
+    /** skill_search is available, so the overflow line can point to it. */
+    searchable?: boolean;
+}
+export interface SkillCatalog {
+    /** The system-prompt section, or "" when there is nothing to list. */
+    text: string;
+    listed: number;
+    unlisted: number;
+    /** Characters used by the listed lines, against budgetChars. */
+    chars: number;
+    budgetChars: number;
+}
+/**
+ * The always-present skill catalog: name and a one-line description per skill,
+ * so the model knows what exists and loads a body with `skill` only when it
+ * applies. Ordering is deterministic (source, then name) so the system prompt
+ * stays byte-identical, and cacheable, while the skill set is unchanged.
+ */
+export declare function buildSkillCatalog(skills: SkillSummary[], options?: SkillCatalogOptions): SkillCatalog;
+/** The catalog section text (see buildSkillCatalog). */
+export declare function formatSkillsPrompt(skills: SkillSummary[], options?: SkillCatalogOptions): string;

package/dist/skills/format.js

@@ -0,0 +1,68 @@
+/** Default size of the always-present skill catalog (the listed lines, not the header). */
+export const SKILL_CATALOG_CHARS = 12_000;
+/** Each description is cut to this length; it only has to tell the model when to load. */
+export const SKILL_CATALOG_DESC_CHARS = 120;
+export const SKILL_CATALOG_HEADING = "## Skills";
+/** First line under the heading; together they mark the catalog unambiguously. */
+export const SKILL_CATALOG_INTRO = "Skills are task-specific instructions loaded on demand. When a task matches a skill below, call `skill` with its exact name before starting, then follow it. Load only what clearly applies.";
+const SOURCE_PRIORITY = {
+    project: 0,
+    configured: 1,
+    user: 2,
+};
+/**
+ * The always-present skill catalog: name and a one-line description per skill,
+ * so the model knows what exists and loads a body with `skill` only when it
+ * applies. Ordering is deterministic (source, then name) so the system prompt
+ * stays byte-identical, and cacheable, while the skill set is unchanged.
+ */
+export function buildSkillCatalog(skills, options = {}) {
+    const budgetChars = Math.max(0, Math.floor(options.budgetChars ?? SKILL_CATALOG_CHARS));
+    const empty = { text: "", listed: 0, unlisted: skills.length, chars: 0, budgetChars };
+    if (skills.length === 0 || budgetChars === 0)
+        return empty;
+    const sorted = [...skills].sort((a, b) => {
+        const ap = SOURCE_PRIORITY[a.source ?? "user"] ?? 3;
+        const bp = SOURCE_PRIORITY[b.source ?? "user"] ?? 3;
+        if (ap !== bp)
+            return ap - bp;
+        // Code-point order, not locale collation: the prompt must be byte-identical across runtimes.
+        return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+    });
+    const lines = [];
+    let used = 0;
+    for (const skill of sorted) {
+        const line = formatSkillLine(skill);
+        if (used + line.length + 1 > budgetChars)
+            break;
+        lines.push(line);
+        used += line.length + 1;
+    }
+    if (lines.length === 0)
+        return empty;
+    const unlisted = sorted.length - lines.length;
+    if (unlisted > 0) {
+        lines.push(options.searchable
+            ? `- … and ${unlisted} more skills not listed here; use skill_search to find them.`
+            : `- … and ${unlisted} more skills not listed here.`);
+    }
+    const text = [
+        SKILL_CATALOG_HEADING,
+        SKILL_CATALOG_INTRO,
+        ...lines,
+    ].join("\n");
+    return { text, listed: sorted.length - unlisted, unlisted, chars: used, budgetChars };
+}
+/** The catalog section text (see buildSkillCatalog). */
+export function formatSkillsPrompt(skills, options = {}) {
+    return buildSkillCatalog(skills, options).text;
+}
+function formatSkillLine(skill) {
+    const raw = (skill.description ?? "").replace(/\s+/g, " ").trim();
+    // Cut by code points so an emoji is never split into a lone surrogate, which some APIs reject.
+    const points = Array.from(raw);
+    const desc = points.length > SKILL_CATALOG_DESC_CHARS
+        ? points.slice(0, SKILL_CATALOG_DESC_CHARS - 1).join("").trimEnd() + "…"
+        : raw;
+    return desc ? `- ${skill.name}: ${desc}` : `- ${skill.name}`;
+}

package/dist/skills/frontmatter.d.ts

@@ -0,0 +1,5 @@
+export interface ParsedFrontmatter {
+    attributes: Record<string, unknown>;
+    body: string;
+}
+export declare function parseFrontmatter(raw: string): ParsedFrontmatter;

package/dist/skills/frontmatter.js

@@ -0,0 +1,60 @@
+export function parseFrontmatter(raw) {
+    if (!raw.startsWith("---\n") && !raw.startsWith("---\r\n")) {
+        return { attributes: {}, body: raw };
+    }
+    const normalized = raw.replace(/\r\n/g, "\n");
+    const end = normalized.indexOf("\n---\n", 4);
+    if (end === -1) {
+        return { attributes: {}, body: raw };
+    }
+    const frontmatter = normalized.slice(4, end);
+    const body = normalized.slice(end + 5);
+    return {
+        attributes: parseFrontmatterBlock(frontmatter),
+        body,
+    };
+}
+function parseFrontmatterBlock(block) {
+    const attributes = {};
+    const lines = block.split("\n");
+    let currentListKey = null;
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        const listMatch = line.match(/^\s*-\s+(.*)$/);
+        if (listMatch && currentListKey) {
+            const current = attributes[currentListKey];
+            if (Array.isArray(current)) {
+                current.push(parseScalar(listMatch[1].trim()));
+            }
+            else {
+                attributes[currentListKey] = [parseScalar(listMatch[1].trim())];
+            }
+            continue;
+        }
+        const keyValueMatch = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (!keyValueMatch) {
+            currentListKey = null;
+            continue;
+        }
+        const [, key, rawValue] = keyValueMatch;
+        if (!rawValue.trim()) {
+            attributes[key] = [];
+            currentListKey = key;
+            continue;
+        }
+        attributes[key] = parseScalar(rawValue.trim());
+        currentListKey = null;
+    }
+    return attributes;
+}
+function parseScalar(value) {
+    const unquoted = value.replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1");
+    if (unquoted === "true")
+        return true;
+    if (unquoted === "false")
+        return false;
+    if (/^-?\d+$/.test(unquoted))
+        return Number.parseInt(unquoted, 10);
+    return unquoted;
+}

package/dist/skills/invocation.d.ts

@@ -0,0 +1,8 @@
+import type { SkillRegistry } from "./registry.js";
+import type { SkillRecord } from "./types.js";
+export interface SkillInvocation {
+    skill: SkillRecord;
+    task: string;
+    actualPrompt: string;
+}
+export declare function parseSkillInvocation(input: string, registry: SkillRegistry): SkillInvocation | undefined;

package/dist/skills/invocation.js

@@ -0,0 +1,33 @@
+export function parseSkillInvocation(input, registry) {
+    const trimmed = input.trim();
+    if (!trimmed.startsWith("/"))
+        return undefined;
+    const withoutSlash = trimmed.slice(1).trim();
+    if (!withoutSlash)
+        return undefined;
+    const firstSpace = withoutSlash.indexOf(" ");
+    if (firstSpace === -1)
+        return undefined;
+    const skillName = withoutSlash.slice(0, firstSpace).trim();
+    const task = withoutSlash.slice(firstSpace + 1).trim();
+    if (!skillName || !task)
+        return undefined;
+    const skill = registry.get(skillName);
+    if (!skill)
+        return undefined;
+    return {
+        skill,
+        task,
+        actualPrompt: buildSkillExecutionPrompt(skill, task),
+    };
+}
+function buildSkillExecutionPrompt(skill, task) {
+    return [
+        `Use the skill tool to load the "${skill.meta.name}" skill before responding.`,
+        `The task clearly matches that skill.`,
+        `Do not simply restate the skill contents; use the loaded instructions to complete the task.`,
+        "",
+        "User request:",
+        task,
+    ].join("\n");
+}

package/dist/skills/registry.d.ts

@@ -0,0 +1,28 @@
+import type { SkillDiagnostic, SkillRecord, SkillSummary } from "./types.js";
+export interface SkillRegistryOptions {
+    cwd?: string;
+    bubbleHome?: string;
+    agentsHome?: string;
+    claudeHome?: string;
+    skillPaths?: string[];
+    disabledSkills?: string[];
+    onDisabledSkillsChange?: (disabledSkills: string[]) => void;
+}
+export declare class SkillRegistry {
+    private skills;
+    private diagnostics;
+    private readonly roots;
+    private readonly disabledSkills;
+    private readonly onDisabledSkillsChange?;
+    constructor(options?: SkillRegistryOptions);
+    reload(): void;
+    all(): SkillRecord[];
+    promptVisible(): SkillRecord[];
+    summaries(): SkillSummary[];
+    get(name: string): SkillRecord | undefined;
+    getAny(name: string): SkillRecord | undefined;
+    isEnabled(name: string): boolean;
+    setEnabled(name: string, enabled: boolean): boolean;
+    getDisabledSkillNames(): string[];
+    getDiagnostics(): SkillDiagnostic[];
+}

package/dist/skills/registry.js

@@ -0,0 +1,79 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { getBubbleHome } from "../bubble-home.js";
+import { discoverSkills } from "./discovery.js";
+export class SkillRegistry {
+    skills = [];
+    diagnostics = [];
+    roots;
+    disabledSkills;
+    onDisabledSkillsChange;
+    constructor(options = {}) {
+        const cwd = options.cwd ?? process.cwd();
+        const bubbleHome = options.bubbleHome ?? getBubbleHome();
+        const agentsHome = options.agentsHome ?? join(homedir(), ".agents");
+        const claudeHome = options.claudeHome ?? join(homedir(), ".claude");
+        this.roots = [
+            { path: join(bubbleHome, "skills"), source: "user" },
+            { path: join(agentsHome, "skills"), source: "user" },
+            { path: join(claudeHome, "skills"), source: "user" },
+            { path: join(cwd, ".bubble", "skills"), source: "project" },
+            ...(options.skillPaths ?? []).map((path) => ({ path, source: "configured" })),
+        ];
+        this.disabledSkills = new Set(options.disabledSkills ?? []);
+        this.onDisabledSkillsChange = options.onDisabledSkillsChange;
+        this.reload();
+    }
+    reload() {
+        const result = discoverSkills({ roots: this.roots });
+        this.skills = result.skills;
+        this.diagnostics = result.diagnostics;
+    }
+    all() {
+        return this.skills.slice();
+    }
+    promptVisible() {
+        return this.skills.filter((skill) => (this.isEnabled(skill.meta.name) && !skill.meta.disableModelInvocation));
+    }
+    summaries() {
+        return this.promptVisible().map((skill) => ({
+            name: skill.meta.name,
+            description: skill.meta.description,
+            tags: skill.meta.tags,
+            source: skill.source,
+        }));
+    }
+    get(name) {
+        if (!this.isEnabled(name))
+            return undefined;
+        return this.getAny(name);
+    }
+    getAny(name) {
+        return this.skills.find((skill) => skill.meta.name === name);
+    }
+    isEnabled(name) {
+        return !this.disabledSkills.has(name);
+    }
+    setEnabled(name, enabled) {
+        if (!this.getAny(name))
+            return false;
+        let changed = false;
+        if (enabled) {
+            changed = this.disabledSkills.delete(name);
+        }
+        else if (!this.disabledSkills.has(name)) {
+            this.disabledSkills.add(name);
+            changed = true;
+        }
+        if (!changed)
+            return false;
+        this.onDisabledSkillsChange?.([...this.disabledSkills].sort((a, b) => a.localeCompare(b)));
+        return true;
+    }
+    getDisabledSkillNames() {
+        return [...this.disabledSkills].sort((a, b) => a.localeCompare(b));
+    }
+    getDiagnostics() {
+        return this.diagnostics.slice();
+    }
+}

package/dist/skills/types.d.ts

@@ -0,0 +1,34 @@
+export interface SkillMeta {
+    name: string;
+    description: string;
+    disableModelInvocation: boolean;
+    version?: number;
+    tags?: string[];
+    author?: string;
+    allowedTools?: string[];
+}
+export interface SkillResourceIndex {
+    references: string[];
+    scripts: string[];
+    assets: string[];
+}
+export interface SkillRecord {
+    meta: SkillMeta;
+    rootDir: string;
+    skillFile: string;
+    content: string;
+    resources: SkillResourceIndex;
+    source: "user" | "project" | "configured";
+}
+export interface SkillSummary {
+    name: string;
+    description: string;
+    tags?: string[];
+    source?: "user" | "project" | "configured";
+}
+export interface SkillDiagnostic {
+    level: "warning" | "error";
+    skillName?: string;
+    filePath?: string;
+    message: string;
+}

package/dist/skills/types.js

@@ -0,0 +1 @@
+export {};

package/dist/slash-commands/commands.d.ts

@@ -0,0 +1,10 @@
+import type { SlashCommand } from "./types.js";
+import type { UnifiedCommand } from "./unified.js";
+/** Rebuild the system prompt from the agent's live options (model, tools, memory, Skills catalog). */
+export declare function syncSystemPrompt(ctx: Pick<Parameters<SlashCommand["handler"]>[1], "agent" | "cwd">, model: string): void;
+/**
+ * Public export — built-in commands tagged with `source: "builtin"` so the
+ * registry and TUI can group them uniformly alongside MCP-derived commands.
+ * Kept as a mapped projection to avoid adding the field to every object literal.
+ */
+export declare const builtinSlashCommands: UnifiedCommand[];