@bubblebrain-ai/bubble 0.0.1

package/dist/skills/discovery.js

@@ -0,0 +1,148 @@
+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;
+    return {
+        name,
+        description,
+        disableModelInvocation: attributes["disable-model-invocation"] === true,
+        version: typeof attributes.version === "number" ? attributes.version : undefined,
+        tags: tags && tags.length > 0 ? tags : 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,2 @@
+import type { SkillSummary } from "./types.js";
+export declare function formatSkillsPrompt(skills: SkillSummary[]): string;

package/dist/skills/format.js

@@ -0,0 +1,47 @@
+const MAX_SKILL_DESC_CHARS = 200;
+const SKILLS_BUDGET_CHARS = 6000;
+const SOURCE_PRIORITY = {
+    project: 0,
+    configured: 1,
+    user: 2,
+};
+export function formatSkillsPrompt(skills) {
+    if (skills.length === 0)
+        return "";
+    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;
+        return a.name.localeCompare(b.name);
+    });
+    const header = [
+        "Skills provide specialized instructions and workflows for specific tasks.",
+        "Use the skill system when a task clearly matches a skill description.",
+        "Available skills:",
+    ];
+    const lines = [];
+    let used = 0;
+    let dropped = 0;
+    for (const skill of sorted) {
+        const line = formatSkillLine(skill);
+        if (used + line.length + 1 > SKILLS_BUDGET_CHARS) {
+            dropped = sorted.length - lines.length;
+            break;
+        }
+        lines.push(line);
+        used += line.length + 1;
+    }
+    if (dropped > 0) {
+        lines.push(`- ... and ${dropped} more skills (use /skills to list all)`);
+    }
+    return [...header, ...lines].join("\n");
+}
+function formatSkillLine(skill) {
+    const tagSuffix = skill.tags && skill.tags.length > 0 ? ` [tags: ${skill.tags.join(", ")}]` : "";
+    const rawDesc = skill.description ?? "";
+    const desc = rawDesc.length > MAX_SKILL_DESC_CHARS
+        ? rawDesc.slice(0, MAX_SKILL_DESC_CHARS - 1) + "…"
+        : rawDesc;
+    return `- ${skill.name}: ${desc}${tagSuffix}`;
+}

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,51 @@
+export function parseSkillInvocation(input, registry) {
+    const trimmed = input.trim();
+    if (!trimmed.startsWith("/"))
+        return undefined;
+    const withoutSlash = trimmed.slice(1).trim();
+    if (!withoutSlash)
+        return undefined;
+    if (withoutSlash.startsWith("skill ")) {
+        const rest = withoutSlash.slice("skill ".length).trim();
+        const firstSpace = rest.indexOf(" ");
+        if (firstSpace === -1)
+            return undefined;
+        const skillName = rest.slice(0, firstSpace).trim();
+        const task = rest.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),
+        };
+    }
+    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,17 @@
+import type { SkillDiagnostic, SkillRecord, SkillSummary } from "./types.js";
+export interface SkillRegistryOptions {
+    cwd?: string;
+    bubbleHome?: string;
+    agentsHome?: string;
+    skillPaths?: string[];
+}
+export declare class SkillRegistry {
+    private readonly skills;
+    private readonly diagnostics;
+    constructor(options?: SkillRegistryOptions);
+    all(): SkillRecord[];
+    promptVisible(): SkillRecord[];
+    summaries(): SkillSummary[];
+    get(name: string): SkillRecord | undefined;
+    getDiagnostics(): SkillDiagnostic[];
+}

package/dist/skills/registry.js

@@ -0,0 +1,42 @@
+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;
+    constructor(options = {}) {
+        const cwd = options.cwd ?? process.cwd();
+        const bubbleHome = options.bubbleHome ?? getBubbleHome();
+        const agentsHome = options.agentsHome ?? join(homedir(), ".agents");
+        const roots = [
+            { path: join(bubbleHome, "skills"), source: "user" },
+            { path: join(agentsHome, "skills"), source: "user" },
+            { path: join(cwd, ".bubble", "skills"), source: "project" },
+            ...(options.skillPaths ?? []).map((path) => ({ path, source: "configured" })),
+        ];
+        const result = discoverSkills({ roots });
+        this.skills = result.skills;
+        this.diagnostics = result.diagnostics;
+    }
+    all() {
+        return this.skills.slice();
+    }
+    promptVisible() {
+        return this.skills.filter((skill) => !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) {
+        return this.skills.find((skill) => skill.meta.name === name);
+    }
+    getDiagnostics() {
+        return this.diagnostics.slice();
+    }
+}

package/dist/skills/types.d.ts

@@ -0,0 +1,32 @@
+export interface SkillMeta {
+    name: string;
+    description: string;
+    disableModelInvocation: boolean;
+    version?: number;
+    tags?: 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,7 @@
+import type { UnifiedCommand } from "./unified.js";
+/**
+ * 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[];