@aetherwing/fcp-core 0.1.0

package/src/event-log.ts

@@ -0,0 +1,209 @@
+/**
+ * Sentinel object stored in the event log to mark a checkpoint.
+ */
+const CHECKPOINT_SENTINEL = Symbol("checkpoint");
+
+interface CheckpointEntry {
+  __type: typeof CHECKPOINT_SENTINEL;
+  name: string;
+}
+
+function isCheckpoint<T>(entry: T | CheckpointEntry): entry is CheckpointEntry {
+  return (
+    typeof entry === "object" &&
+    entry !== null &&
+    "__type" in entry &&
+    (entry as CheckpointEntry).__type === CHECKPOINT_SENTINEL
+  );
+}
+
+/**
+ * Generic cursor-based event log with undo/redo and named checkpoints.
+ *
+ * Events are appended at the cursor position. The cursor always points
+ * one past the last applied event. Undo moves the cursor back; redo
+ * moves it forward. Appending a new event truncates the redo tail.
+ *
+ * Checkpoint sentinels are stored in the log but skipped during
+ * undo/redo traversal.
+ */
+export class EventLog<T> {
+  private events: Array<T | CheckpointEntry> = [];
+  private _cursor = 0;
+  private checkpoints = new Map<string, number>();
+
+  /**
+   * Append an event, truncating any redo history beyond the cursor.
+   */
+  append(event: T): void {
+    if (this._cursor < this.events.length) {
+      this.events.length = this._cursor;
+      // Remove checkpoints pointing beyond new length
+      for (const [name, idx] of this.checkpoints) {
+        if (idx > this._cursor) {
+          this.checkpoints.delete(name);
+        }
+      }
+    }
+    this.events.push(event);
+    this._cursor = this.events.length;
+  }
+
+  /**
+   * Create a named checkpoint at the current cursor position.
+   */
+  checkpoint(name: string): void {
+    this.checkpoints.set(name, this._cursor);
+    const sentinel: CheckpointEntry = { __type: CHECKPOINT_SENTINEL, name };
+    this.events.push(sentinel);
+    this._cursor = this.events.length;
+  }
+
+  /**
+   * Undo up to `count` non-checkpoint events. Returns events in reverse
+   * order (most recent first) for the caller to reverse-apply.
+   */
+  undo(count: number = 1): T[] {
+    const result: T[] = [];
+    let pos = this._cursor - 1;
+    let undone = 0;
+
+    while (pos >= 0 && undone < count) {
+      const entry = this.events[pos];
+      if (!isCheckpoint(entry)) {
+        result.push(entry);
+        undone++;
+      }
+      pos--;
+    }
+
+    this._cursor = pos + 1;
+    return result;
+  }
+
+  /**
+   * Undo to a named checkpoint. Returns events in reverse order.
+   * Returns null if the checkpoint doesn't exist or is at/beyond cursor.
+   */
+  undoTo(name: string): T[] | null {
+    const target = this.checkpoints.get(name);
+    if (target === undefined || target >= this._cursor) return null;
+
+    const result: T[] = [];
+    for (let i = this._cursor - 1; i >= target; i--) {
+      const entry = this.events[i];
+      if (!isCheckpoint(entry)) {
+        result.push(entry);
+      }
+    }
+    this._cursor = target;
+    return result;
+  }
+
+  /**
+   * Redo up to `count` non-checkpoint events. Returns events in forward
+   * order for the caller to re-apply.
+   */
+  redo(count: number = 1): T[] {
+    const result: T[] = [];
+    let pos = this._cursor;
+    let redone = 0;
+
+    while (pos < this.events.length && redone < count) {
+      const entry = this.events[pos];
+      if (!isCheckpoint(entry)) {
+        result.push(entry);
+        redone++;
+      }
+      pos++;
+    }
+
+    this._cursor = pos;
+    return result;
+  }
+
+  /**
+   * Get the last N non-checkpoint events (up to cursor). Returned in
+   * chronological order (oldest first).
+   */
+  recent(count?: number): T[] {
+    const limit = count ?? this._cursor;
+    const result: T[] = [];
+    for (let i = this._cursor - 1; i >= 0 && result.length < limit; i--) {
+      const entry = this.events[i];
+      if (!isCheckpoint(entry)) {
+        result.push(entry);
+      }
+    }
+    return result.reverse();
+  }
+
+  /**
+   * Current cursor position (one past last applied event).
+   */
+  get cursor(): number {
+    return this._cursor;
+  }
+
+  /**
+   * Total number of entries in the log (including checkpoints).
+   */
+  get length(): number {
+    return this.events.length;
+  }
+
+  /**
+   * Whether there are events before the cursor that can be undone.
+   */
+  canUndo(): boolean {
+    for (let i = this._cursor - 1; i >= 0; i--) {
+      if (!isCheckpoint(this.events[i])) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Whether there are events after the cursor that can be redone.
+   */
+  canRedo(): boolean {
+    return this._cursor < this.events.length;
+  }
+
+  /**
+   * Get the event index for a named checkpoint.
+   * Returns undefined if the checkpoint doesn't exist.
+   */
+  getCheckpointIndex(name: string): number | undefined {
+    return this.checkpoints.get(name);
+  }
+
+  /**
+   * Number of named checkpoints.
+   */
+  get checkpointCount(): number {
+    return this.checkpoints.size;
+  }
+
+  /**
+   * Get all checkpoint names and their indices.
+   */
+  getCheckpoints(): Map<string, number> {
+    return new Map(this.checkpoints);
+  }
+
+  /**
+   * Get non-checkpoint events from a given index to the cursor.
+   * Used for diff queries.
+   */
+  eventsSince(fromIndex: number): T[] {
+    const result: T[] = [];
+    const end = Math.min(this._cursor, this.events.length);
+    for (let i = fromIndex; i < end; i++) {
+      const entry = this.events[i];
+      if (!isCheckpoint(entry)) {
+        result.push(entry);
+      }
+    }
+    return result;
+  }
+}

package/src/formatter.ts

@@ -0,0 +1,70 @@
+/**
+ * Format a result message with a prefix character.
+ *
+ * Prefix conventions:
+ *   + created
+ *   ~ modified (edge/connection)
+ *   * changed (property)
+ *   - removed
+ *   ! meta/group operation
+ *   @ bulk/layout operation
+ */
+export function formatResult(
+  success: boolean,
+  message: string,
+  prefix?: string,
+): string {
+  if (!success) return `ERROR: ${message}`;
+  if (prefix) return `${prefix} ${message}`;
+  return message;
+}
+
+/**
+ * Suggest a correction for a misspelled input by finding the closest
+ * candidate using Levenshtein distance. Returns null if no candidate
+ * is close enough (distance > 3).
+ */
+export function suggest(input: string, candidates: string[]): string | null {
+  if (candidates.length === 0) return null;
+
+  let best: string | null = null;
+  let bestDist = Infinity;
+
+  for (const candidate of candidates) {
+    const dist = levenshtein(input.toLowerCase(), candidate.toLowerCase());
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = candidate;
+    }
+  }
+
+  return bestDist <= 3 ? best : null;
+}
+
+/**
+ * Compute Levenshtein distance between two strings.
+ */
+function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+
+  // Use a single-row DP array
+  const prev = new Array<number>(n + 1);
+  for (let j = 0; j <= n; j++) prev[j] = j;
+
+  for (let i = 1; i <= m; i++) {
+    let prevDiag = prev[0];
+    prev[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const temp = prev[j];
+      if (a[i - 1] === b[j - 1]) {
+        prev[j] = prevDiag;
+      } else {
+        prev[j] = 1 + Math.min(prevDiag, prev[j - 1], prev[j]);
+      }
+      prevDiag = temp;
+    }
+  }
+
+  return prev[n];
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+// Tokenizer
+export {
+  tokenize,
+  isKeyValue,
+  parseKeyValue,
+  isArrow,
+  isSelector,
+} from "./tokenizer.js";
+
+// Parsed operation
+export {
+  parseOp,
+  isParseError,
+  type ParsedOp,
+  type ParseError,
+} from "./parsed-op.js";
+
+// Event log
+export { EventLog } from "./event-log.js";
+
+// Verb registry
+export { VerbRegistry, type VerbSpec } from "./verb-registry.js";
+
+// Session
+export {
+  SessionDispatcher,
+  type SessionHooks,
+} from "./session.js";
+
+// Formatter
+export { formatResult, suggest } from "./formatter.js";
+
+// Server
+export {
+  createFcpServer,
+  type FcpServerConfig,
+  type FcpDomainAdapter,
+  type OpResult,
+  type QueryResult,
+} from "./server.js";

package/src/parsed-op.ts

@@ -0,0 +1,64 @@
+import { tokenize, isKeyValue, parseKeyValue, isSelector, isArrow } from "./tokenizer.js";
+
+/**
+ * A successfully parsed operation.
+ */
+export interface ParsedOp {
+  verb: string;
+  positionals: string[];
+  params: Record<string, string>;
+  selectors: string[];
+  raw: string;
+}
+
+/**
+ * A parse failure.
+ */
+export interface ParseError {
+  success: false;
+  error: string;
+  raw: string;
+}
+
+/**
+ * Parse an operation string into a structured ParsedOp.
+ *
+ * First token becomes the verb. Remaining tokens are classified:
+ *   @-prefixed  -> selectors
+ *   key:value   -> params
+ *   everything else -> positionals (in order)
+ */
+export function parseOp(input: string): ParsedOp | ParseError {
+  const raw = input.trim();
+  const tokens = tokenize(raw);
+
+  if (tokens.length === 0) {
+    return { success: false, error: "empty operation", raw };
+  }
+
+  const verb = tokens[0].toLowerCase();
+  const positionals: string[] = [];
+  const params: Record<string, string> = {};
+  const selectors: string[] = [];
+
+  for (let i = 1; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (isSelector(token)) {
+      selectors.push(token);
+    } else if (isKeyValue(token)) {
+      const { key, value } = parseKeyValue(token);
+      params[key] = value;
+    } else {
+      positionals.push(token);
+    }
+  }
+
+  return { verb, positionals, params, selectors, raw };
+}
+
+/**
+ * Type guard: check if a parse result is an error.
+ */
+export function isParseError(result: ParsedOp | ParseError): result is ParseError {
+  return "success" in result && result.success === false;
+}

package/src/server.ts

@@ -0,0 +1,241 @@
+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 type { ParsedOp } from "./parsed-op.js";
+import { VerbRegistry } from "./verb-registry.js";
+import type { VerbSpec } from "./verb-registry.js";
+import { SessionDispatcher, type SessionHooks } from "./session.js";
+import { formatResult, suggest } from "./formatter.js";
+
+/**
+ * Result of executing a single operation.
+ */
+export interface OpResult {
+  success: boolean;
+  message: string;
+  prefix?: string;
+}
+
+/**
+ * Result of a query that may include an image.
+ */
+export interface QueryResult {
+  text: string;
+  image?: { base64: string; mimeType: string };
+}
+
+/**
+ * Domain adapter that an FCP domain must implement.
+ */
+export interface FcpDomainAdapter<Model, Event> {
+  /** Create a new empty model. */
+  createEmpty(title: string, params: Record<string, string>): Model;
+  /** Serialize model to saveable format. */
+  serialize(model: Model): Buffer | string;
+  /** Deserialize from file contents. */
+  deserialize(data: Buffer | string): Model;
+  /** Rebuild derived indices (e.g., after undo/redo). */
+  rebuildIndices(model: Model): void;
+  /** Return a compact digest for drift detection. */
+  getDigest(model: Model): string;
+  /** Execute a parsed operation against the model. */
+  dispatchOp(op: ParsedOp, model: Model, log: EventLog<Event>): OpResult | Promise<OpResult>;
+  /** Execute a query against the model. */
+  dispatchQuery(query: string, model: Model): string | QueryResult | Promise<string | QueryResult>;
+  /** Reverse a single event (for undo). */
+  reverseEvent(event: Event, model: Model): void;
+  /** Replay a single event (for redo). */
+  replayEvent(event: Event, model: Model): void;
+}
+
+/**
+ * Configuration for creating an FCP MCP server.
+ */
+export interface FcpServerConfig<Model, Event> {
+  /** Domain name (e.g., "midi", "studio"). Used as tool name prefix. */
+  domain: string;
+  /** Domain adapter implementing all domain-specific logic. */
+  adapter: FcpDomainAdapter<Model, Event>;
+  /** Verb specifications for this domain. */
+  verbs: VerbSpec[];
+  /** Optional reference card configuration. */
+  referenceCard?: { sections?: Record<string, string> };
+}
+
+/**
+ * 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<Model, Event>(
+  config: FcpServerConfig<Model, Event>,
+): McpServer {
+  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<Event>();
+
+  // Session dispatcher with hooks
+  const sessionHooks: SessionHooks<Model> = {
+    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<Model, Event>(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" as const, text: "error: no model loaded. Use session 'new' or 'open' first." }],
+          isError: true,
+        };
+      }
+
+      const lines: string[] = [];
+      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" as const, 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" as const, text: "error: no model loaded." }],
+          isError: true,
+        };
+      }
+
+      const result = await adapter.dispatchQuery(q, model);
+
+      if (typeof result === "string") {
+        return { content: [{ type: "text" as const, text: result }] };
+      }
+
+      const qr = result as QueryResult;
+      const content: Array<
+        | { type: "text"; text: string }
+        | { type: "image"; data: string; mimeType: string }
+      > = [];
+      if (qr.image) {
+        content.push({ type: "image" as const, data: qr.image.base64, mimeType: qr.image.mimeType });
+      }
+      content.push({ type: "text" as const, 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" as const, text: output }] };
+    },
+  );
+
+  // ── Help tool ──────────────────────────────────────────
+  server.tool(
+    `${domain}_help`,
+    `Returns the ${domain} FCP reference card.`,
+    {},
+    async () => {
+      return { content: [{ type: "text" as const, text: refCard }] };
+    },
+  );
+
+  return server;
+}