@aetherwing/fcp-core 0.1.0

package/dist/server.js

@@ -0,0 +1,140 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { EventLog } from "./event-log.js";
+import { parseOp, isParseError } from "./parsed-op.js";
+import { VerbRegistry } from "./verb-registry.js";
+import { SessionDispatcher } from "./session.js";
+import { formatResult, suggest } from "./formatter.js";
+/**
+ * Create an MCP server wired up with FCP conventions.
+ *
+ * Registers 4 tools:
+ *   {domain}         — primary mutation tool (ops array)
+ *   {domain}_query   — read-only queries
+ *   {domain}_session — lifecycle (new, open, save, checkpoint, undo, redo)
+ *   {domain}_help    — reference card
+ */
+export function createFcpServer(config) {
+    const { domain, adapter, verbs, referenceCard } = config;
+    // Build registry and reference card
+    const registry = new VerbRegistry();
+    registry.registerMany(verbs);
+    const refCard = registry.generateReferenceCard(referenceCard?.sections);
+    // Event log
+    const eventLog = new EventLog();
+    // Session dispatcher with hooks
+    const sessionHooks = {
+        onNew(params) {
+            return adapter.createEmpty(params["title"] ?? "Untitled", params);
+        },
+        async onOpen(path) {
+            const { readFile } = await import("node:fs/promises");
+            const data = await readFile(path);
+            const model = adapter.deserialize(data);
+            adapter.rebuildIndices(model);
+            return model;
+        },
+        async onSave(model, path) {
+            const { writeFile } = await import("node:fs/promises");
+            const data = adapter.serialize(model);
+            await writeFile(path, data);
+        },
+        onRebuildIndices(model) {
+            adapter.rebuildIndices(model);
+        },
+        getDigest(model) {
+            return adapter.getDigest(model);
+        },
+    };
+    const session = new SessionDispatcher(sessionHooks, eventLog, {
+        reverseEvent: (event, model) => adapter.reverseEvent(event, model),
+        replayEvent: (event, model) => adapter.replayEvent(event, model),
+    });
+    // MCP server
+    const server = new McpServer({
+        name: `fcp-${domain}`,
+        version: "0.1.0",
+    });
+    // ── Primary mutation tool ──────────────────────────────
+    server.tool(domain, `Execute ${domain} operations. Each op string follows the FCP verb DSL.\n\n${refCard}`, {
+        ops: z
+            .array(z.string())
+            .describe("Array of operation strings"),
+    }, async ({ ops }) => {
+        const model = session.model;
+        if (!model) {
+            return {
+                content: [{ type: "text", text: "error: no model loaded. Use session 'new' or 'open' first." }],
+                isError: true,
+            };
+        }
+        const lines = [];
+        let hasErrors = false;
+        for (const opStr of ops) {
+            const parsed = parseOp(opStr);
+            if (isParseError(parsed)) {
+                lines.push(`ERROR: ${parsed.error}`);
+                hasErrors = true;
+                continue;
+            }
+            // Check if verb is known
+            const spec = registry.lookup(parsed.verb);
+            if (!spec) {
+                const suggestion = suggest(parsed.verb, verbs.map((v) => v.verb));
+                const msg = `unknown verb "${parsed.verb}"`;
+                lines.push(suggestion ? `ERROR: ${msg}\n  try: ${suggestion}` : `ERROR: ${msg}`);
+                hasErrors = true;
+                continue;
+            }
+            const result = await adapter.dispatchOp(parsed, model, eventLog);
+            lines.push(formatResult(result.success, result.message, result.prefix));
+            if (!result.success)
+                hasErrors = true;
+        }
+        // Append digest
+        lines.push(adapter.getDigest(model));
+        return {
+            content: [{ type: "text", text: lines.join("\n") }],
+            isError: hasErrors,
+        };
+    });
+    // ── Query tool ─────────────────────────────────────────
+    server.tool(`${domain}_query`, `Query ${domain} state. Read-only.`, {
+        q: z.string().describe("Query string"),
+    }, async ({ q }) => {
+        const model = session.model;
+        if (!model) {
+            return {
+                content: [{ type: "text", text: "error: no model loaded." }],
+                isError: true,
+            };
+        }
+        const result = await adapter.dispatchQuery(q, model);
+        if (typeof result === "string") {
+            return { content: [{ type: "text", text: result }] };
+        }
+        const qr = result;
+        const content = [];
+        if (qr.image) {
+            content.push({ type: "image", data: qr.image.base64, mimeType: qr.image.mimeType });
+        }
+        content.push({ type: "text", text: qr.text });
+        return { content };
+    });
+    // ── Session tool ───────────────────────────────────────
+    server.tool(`${domain}_session`, `${domain} lifecycle: new, open, save, checkpoint, undo, redo.`, {
+        action: z.string().describe("Action: 'new \"Title\"', 'open ./file', 'save', 'save as:./out', 'checkpoint v1', 'undo', 'undo to:v1', 'redo'"),
+    }, async ({ action }) => {
+        const text = await session.dispatch(action);
+        const model = session.model;
+        const digest = model ? adapter.getDigest(model) : "";
+        const output = digest ? `${text}\n${digest}` : text;
+        return { content: [{ type: "text", text: output }] };
+    });
+    // ── Help tool ──────────────────────────────────────────
+    server.tool(`${domain}_help`, `Returns the ${domain} FCP reference card.`, {}, async () => {
+        return { content: [{ type: "text", text: refCard }] };
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/session.d.ts

@@ -0,0 +1,40 @@
+import { EventLog } from "./event-log.js";
+/**
+ * Hooks that a domain must implement for session lifecycle operations.
+ */
+export interface SessionHooks<Model> {
+    /** Create a new empty model with the given title/params. */
+    onNew(params: Record<string, string>): Model;
+    /** Open a model from a file path. */
+    onOpen(path: string): Promise<Model>;
+    /** Save a model to a file path. */
+    onSave(model: Model, path: string): Promise<void>;
+    /** Rebuild any derived indices after undo/redo. */
+    onRebuildIndices(model: Model): void;
+    /** Return a compact digest string for drift detection. */
+    getDigest(model: Model): string;
+}
+/**
+ * Routes session-level actions (new, open, save, checkpoint, undo, redo)
+ * to the appropriate handler. Framework handles checkpoint/undo/redo;
+ * domain handles new/open/save via hooks.
+ */
+export declare class SessionDispatcher<Model, Event> {
+    private _model;
+    private _filePath;
+    private hooks;
+    private eventLog;
+    private reverseEvent;
+    private replayEvent;
+    constructor(hooks: SessionHooks<Model>, eventLog: EventLog<Event>, options: {
+        reverseEvent: (event: Event, model: Model) => void;
+        replayEvent: (event: Event, model: Model) => void;
+    });
+    /**
+     * Dispatch a session action string. Returns a result message.
+     */
+    dispatch(action: string): Promise<string>;
+    get model(): Model | null;
+    get filePath(): string | null;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAG1C;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,KAAK;IACjC,4DAA4D;IAC5D,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC;IAC7C,qCAAqC;IACrC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IACrC,mCAAmC;IACnC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,mDAAmD;IACnD,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACrC,0DAA0D;IAC1D,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC;CACjC;AAED;;;;GAIG;AACH,qBAAa,iBAAiB,CAAC,KAAK,EAAE,KAAK;IACzC,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,YAAY,CAAuC;IAC3D,OAAO,CAAC,WAAW,CAAuC;gBAGxD,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,EAC1B,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,EACzB,OAAO,EAAE;QACP,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;QACnD,WAAW,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;KACnD;IAQH;;OAEG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA0G/C,IAAI,KAAK,IAAI,KAAK,GAAG,IAAI,CAExB;IAED,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAE5B;CACF"}

package/dist/session.js

@@ -0,0 +1,142 @@
+import { tokenize, isKeyValue, parseKeyValue } from "./tokenizer.js";
+/**
+ * Routes session-level actions (new, open, save, checkpoint, undo, redo)
+ * to the appropriate handler. Framework handles checkpoint/undo/redo;
+ * domain handles new/open/save via hooks.
+ */
+export class SessionDispatcher {
+    _model = null;
+    _filePath = null;
+    hooks;
+    eventLog;
+    reverseEvent;
+    replayEvent;
+    constructor(hooks, eventLog, options) {
+        this.hooks = hooks;
+        this.eventLog = eventLog;
+        this.reverseEvent = options.reverseEvent;
+        this.replayEvent = options.replayEvent;
+    }
+    /**
+     * Dispatch a session action string. Returns a result message.
+     */
+    async dispatch(action) {
+        const tokens = tokenize(action);
+        if (tokens.length === 0)
+            return "empty action";
+        const cmd = tokens[0].toLowerCase();
+        switch (cmd) {
+            case "new": {
+                const params = {};
+                const positionals = [];
+                for (let i = 1; i < tokens.length; i++) {
+                    if (isKeyValue(tokens[i])) {
+                        const { key, value } = parseKeyValue(tokens[i]);
+                        params[key] = value;
+                    }
+                    else {
+                        positionals.push(tokens[i]);
+                    }
+                }
+                if (positionals.length > 0) {
+                    params["title"] = positionals[0];
+                }
+                this._model = this.hooks.onNew(params);
+                this._filePath = null;
+                const title = params["title"] ?? "Untitled";
+                return `new "${title}" created`;
+            }
+            case "open": {
+                const path = tokens[1];
+                if (!path)
+                    return "open requires a file path";
+                try {
+                    this._model = await this.hooks.onOpen(path);
+                    this._filePath = path;
+                    return `opened "${path}"`;
+                }
+                catch (e) {
+                    const msg = e instanceof Error ? e.message : String(e);
+                    return `error: ${msg}`;
+                }
+            }
+            case "save": {
+                if (!this._model)
+                    return "error: no model to save";
+                let savePath = this._filePath;
+                for (let i = 1; i < tokens.length; i++) {
+                    if (isKeyValue(tokens[i])) {
+                        const { key, value } = parseKeyValue(tokens[i]);
+                        if (key === "as")
+                            savePath = value;
+                    }
+                }
+                if (!savePath)
+                    return "error: no file path. Use save as:./file";
+                try {
+                    await this.hooks.onSave(this._model, savePath);
+                    this._filePath = savePath;
+                    return `saved "${savePath}"`;
+                }
+                catch (e) {
+                    const msg = e instanceof Error ? e.message : String(e);
+                    return `error: ${msg}`;
+                }
+            }
+            case "checkpoint": {
+                const name = tokens[1];
+                if (!name)
+                    return "checkpoint requires a name";
+                this.eventLog.checkpoint(name);
+                return `checkpoint "${name}" created`;
+            }
+            case "undo": {
+                if (!this._model)
+                    return "nothing to undo";
+                // undo to:NAME or undo [count]
+                if (tokens.length >= 2 && tokens[1].startsWith("to:")) {
+                    const name = tokens[1].slice(3);
+                    if (!name)
+                        return "undo to: requires a checkpoint name";
+                    const events = this.eventLog.undoTo(name);
+                    if (!events)
+                        return `cannot undo to "${name}"`;
+                    for (const ev of events) {
+                        this.reverseEvent(ev, this._model);
+                    }
+                    this.hooks.onRebuildIndices(this._model);
+                    return `undone ${events.length} event${events.length !== 1 ? "s" : ""} to checkpoint "${name}"`;
+                }
+                const events = this.eventLog.undo();
+                if (events.length === 0)
+                    return "nothing to undo";
+                for (const ev of events) {
+                    this.reverseEvent(ev, this._model);
+                }
+                this.hooks.onRebuildIndices(this._model);
+                return `undone ${events.length} event${events.length !== 1 ? "s" : ""}`;
+            }
+            case "redo": {
+                if (!this._model)
+                    return "nothing to redo";
+                const events = this.eventLog.redo();
+                if (events.length === 0)
+                    return "nothing to redo";
+                for (const ev of events) {
+                    this.replayEvent(ev, this._model);
+                }
+                this.hooks.onRebuildIndices(this._model);
+                return `redone ${events.length} event${events.length !== 1 ? "s" : ""}`;
+            }
+            default:
+                return `unknown session action "${cmd}"`;
+        }
+    }
+    get model() {
+        return this._model;
+    }
+    get filePath() {
+        return this._filePath;
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/tokenizer.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Tokenize an operation string by whitespace, respecting quoted strings.
+ * "add svc \"Auth Service\" theme:blue" -> ["add", "svc", "Auth Service", "theme:blue"]
+ */
+export declare function tokenize(input: string): string[];
+/**
+ * Check if a token is a key:value pair.
+ * Must contain ":" but not start with "@" (selectors) and not be an arrow.
+ */
+export declare function isKeyValue(token: string): boolean;
+/**
+ * Parse a key:value token. The value may include colons (e.g., "style:orthogonal").
+ */
+export declare function parseKeyValue(token: string): {
+    key: string;
+    value: string;
+};
+/**
+ * Check if a token is an arrow operator.
+ */
+export declare function isArrow(token: string): boolean;
+/**
+ * Check if a token is a selector (@-prefixed).
+ */
+export declare function isSelector(token: string): boolean;
+//# sourceMappingURL=tokenizer.d.ts.map

package/dist/tokenizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenizer.d.ts","sourceRoot":"","sources":["../src/tokenizer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAmEhD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKjD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAM3E;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE9C;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEjD"}

package/dist/tokenizer.js

@@ -0,0 +1,114 @@
+/**
+ * Tokenize an operation string by whitespace, respecting quoted strings.
+ * "add svc \"Auth Service\" theme:blue" -> ["add", "svc", "Auth Service", "theme:blue"]
+ */
+export function tokenize(input) {
+    const tokens = [];
+    let i = 0;
+    const len = input.length;
+    while (i < len) {
+        // Skip whitespace
+        while (i < len && input[i] === " ")
+            i++;
+        if (i >= len)
+            break;
+        if (input[i] === '"') {
+            // Quoted string
+            i++; // skip opening quote
+            let token = "";
+            while (i < len && input[i] !== '"') {
+                if (input[i] === "\\" && i + 1 < len) {
+                    const next = input[i + 1];
+                    if (next === "n") {
+                        token += "\n";
+                        i += 2;
+                    }
+                    else {
+                        i++;
+                        token += input[i];
+                        i++;
+                    }
+                }
+                else {
+                    token += input[i];
+                    i++;
+                }
+            }
+            if (i < len)
+                i++; // skip closing quote
+            tokens.push(token);
+        }
+        else {
+            // Unquoted token — handle embedded quotes (e.g., key:"value")
+            let token = "";
+            while (i < len && input[i] !== " ") {
+                if (input[i] === '"') {
+                    // Embedded quoted value
+                    i++; // skip opening quote
+                    while (i < len && input[i] !== '"') {
+                        if (input[i] === "\\" && i + 1 < len) {
+                            const next = input[i + 1];
+                            if (next === "n") {
+                                token += "\n";
+                                i += 2;
+                            }
+                            else {
+                                i++;
+                                token += input[i];
+                                i++;
+                            }
+                        }
+                        else {
+                            token += input[i];
+                            i++;
+                        }
+                    }
+                    if (i < len)
+                        i++; // skip closing quote
+                }
+                else {
+                    token += input[i];
+                    i++;
+                }
+            }
+            // Convert literal \n in unquoted tokens to actual newlines
+            tokens.push(token.replace(/\\n/g, "\n"));
+        }
+    }
+    return tokens;
+}
+/**
+ * Check if a token is a key:value pair.
+ * Must contain ":" but not start with "@" (selectors) and not be an arrow.
+ */
+export function isKeyValue(token) {
+    if (token.startsWith("@"))
+        return false;
+    if (isArrow(token))
+        return false;
+    const colonIdx = token.indexOf(":");
+    return colonIdx > 0 && colonIdx < token.length - 1;
+}
+/**
+ * Parse a key:value token. The value may include colons (e.g., "style:orthogonal").
+ */
+export function parseKeyValue(token) {
+    const colonIdx = token.indexOf(":");
+    return {
+        key: token.slice(0, colonIdx),
+        value: token.slice(colonIdx + 1),
+    };
+}
+/**
+ * Check if a token is an arrow operator.
+ */
+export function isArrow(token) {
+    return token === "->" || token === "<->" || token === "--";
+}
+/**
+ * Check if a token is a selector (@-prefixed).
+ */
+export function isSelector(token) {
+    return token.startsWith("@");
+}
+//# sourceMappingURL=tokenizer.js.map

package/dist/tokenizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenizer.js","sourceRoot":"","sources":["../src/tokenizer.ts"],"names":[],"mappings":"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"}

package/dist/verb-registry.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Specification for a single verb in an FCP protocol.
+ */
+export interface VerbSpec {
+    verb: string;
+    syntax: string;
+    category: string;
+    params?: string[];
+    description?: string;
+}
+/**
+ * Registry of verb specifications. Provides lookup by verb name and
+ * reference card generation grouped by category.
+ */
+export declare class VerbRegistry {
+    private specs;
+    private categories;
+    /**
+     * Register a single verb specification.
+     */
+    register(spec: VerbSpec): void;
+    /**
+     * Register multiple verb specifications at once.
+     */
+    registerMany(specs: VerbSpec[]): void;
+    /**
+     * Look up a verb specification by name.
+     */
+    lookup(verb: string): VerbSpec | undefined;
+    /**
+     * Generate a reference card string grouped by category.
+     * Optional `sections` adds extra static sections (e.g., domain-specific
+     * reference material) appended after the verb listing.
+     */
+    generateReferenceCard(sections?: Record<string, string>): string;
+    /**
+     * All registered verb specifications.
+     */
+    get verbs(): VerbSpec[];
+}
+//# sourceMappingURL=verb-registry.d.ts.map

package/dist/verb-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verb-registry.d.ts","sourceRoot":"","sources":["../src/verb-registry.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,UAAU,CAAiC;IAEnD;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI;IAO9B;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI;IAMrC;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAI1C;;;;OAIG;IACH,qBAAqB,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM;IA2BhE;;OAEG;IACH,IAAI,KAAK,IAAI,QAAQ,EAAE,CAEtB;CACF"}

package/dist/verb-registry.js

@@ -0,0 +1,65 @@
+/**
+ * Registry of verb specifications. Provides lookup by verb name and
+ * reference card generation grouped by category.
+ */
+export class VerbRegistry {
+    specs = new Map();
+    categories = new Map();
+    /**
+     * Register a single verb specification.
+     */
+    register(spec) {
+        this.specs.set(spec.verb, spec);
+        const list = this.categories.get(spec.category) ?? [];
+        list.push(spec);
+        this.categories.set(spec.category, list);
+    }
+    /**
+     * Register multiple verb specifications at once.
+     */
+    registerMany(specs) {
+        for (const spec of specs) {
+            this.register(spec);
+        }
+    }
+    /**
+     * Look up a verb specification by name.
+     */
+    lookup(verb) {
+        return this.specs.get(verb);
+    }
+    /**
+     * Generate a reference card string grouped by category.
+     * Optional `sections` adds extra static sections (e.g., domain-specific
+     * reference material) appended after the verb listing.
+     */
+    generateReferenceCard(sections) {
+        const lines = [];
+        for (const [category, specs] of this.categories) {
+            lines.push(`${category.toUpperCase()}:`);
+            for (const spec of specs) {
+                lines.push(`  ${spec.syntax}`);
+            }
+            lines.push("");
+        }
+        if (sections) {
+            for (const [title, content] of Object.entries(sections)) {
+                lines.push(`${title.toUpperCase()}:`);
+                lines.push(content);
+                lines.push("");
+            }
+        }
+        // Remove trailing empty line
+        while (lines.length > 0 && lines[lines.length - 1] === "") {
+            lines.pop();
+        }
+        return lines.join("\n");
+    }
+    /**
+     * All registered verb specifications.
+     */
+    get verbs() {
+        return [...this.specs.values()];
+    }
+}
+//# sourceMappingURL=verb-registry.js.map

package/dist/verb-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verb-registry.js","sourceRoot":"","sources":["../src/verb-registry.ts"],"names":[],"mappings":"AAWA;;;GAGG;AACH,MAAM,OAAO,YAAY;IACf,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAC;IACpC,UAAU,GAAG,IAAI,GAAG,EAAsB,CAAC;IAEnD;;OAEG;IACH,QAAQ,CAAC,IAAc;QACrB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAChC,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QACtD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC3C,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,KAAiB;QAC5B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,IAAY;QACjB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACH,qBAAqB,CAAC,QAAiC;QACrD,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,KAAK,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAChD,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;YACzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;YACjC,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;QAED,IAAI,QAAQ,EAAE,CAAC;YACb,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACxD,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;gBACtC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACpB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACjB,CAAC;QACH,CAAC;QAED,6BAA6B;QAC7B,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;YAC1D,KAAK,CAAC,GAAG,EAAE,CAAC;QACd,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,IAAI,KAAK;QACP,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IAClC,CAAC;CACF"}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@aetherwing/fcp-core",
+  "version": "0.1.0",
+  "description": "File Context Protocol — reusable framework for building MCP servers",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.2",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.1"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}