@aetherwing/fcp-core 0.1.0

package/tests/server.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect } from "vitest";
+import { createFcpServer, type FcpDomainAdapter, type OpResult } from "../src/server.js";
+import { EventLog } from "../src/event-log.js";
+import type { ParsedOp } from "../src/parsed-op.js";
+import type { VerbSpec } from "../src/verb-registry.js";
+
+// A minimal test domain
+interface TestModel {
+  title: string;
+  items: string[];
+}
+
+type TestEvent = { type: "add"; item: string } | { type: "remove"; item: string };
+
+const testVerbs: VerbSpec[] = [
+  { verb: "add", syntax: "add ITEM", category: "create", description: "Add an item" },
+  { verb: "remove", syntax: "remove ITEM", category: "modify", description: "Remove an item" },
+  { verb: "list", syntax: "list", category: "query", description: "List all items" },
+];
+
+const testAdapter: FcpDomainAdapter<TestModel, TestEvent> = {
+  createEmpty(title) {
+    return { title, items: [] };
+  },
+  serialize(model) {
+    return JSON.stringify(model);
+  },
+  deserialize(data) {
+    return JSON.parse(typeof data === "string" ? data : data.toString());
+  },
+  rebuildIndices() {},
+  getDigest(model) {
+    return `[${model.title}: ${model.items.length} items]`;
+  },
+  dispatchOp(op: ParsedOp, model: TestModel, log: EventLog<TestEvent>): OpResult {
+    switch (op.verb) {
+      case "add": {
+        const item = op.positionals[0];
+        if (!item) return { success: false, message: "add requires an item" };
+        model.items.push(item);
+        log.append({ type: "add", item });
+        return { success: true, message: item, prefix: "+" };
+      }
+      case "remove": {
+        const item = op.positionals[0];
+        if (!item) return { success: false, message: "remove requires an item" };
+        const idx = model.items.indexOf(item);
+        if (idx === -1) return { success: false, message: `"${item}" not found` };
+        model.items.splice(idx, 1);
+        log.append({ type: "remove", item });
+        return { success: true, message: item, prefix: "-" };
+      }
+      default:
+        return { success: false, message: `unhandled verb "${op.verb}"` };
+    }
+  },
+  dispatchQuery(query: string, model: TestModel) {
+    if (query === "list") {
+      return model.items.length === 0 ? "empty" : model.items.join(", ");
+    }
+    return `unknown query: ${query}`;
+  },
+  reverseEvent(event: TestEvent, model: TestModel) {
+    if (event.type === "add") {
+      const idx = model.items.indexOf(event.item);
+      if (idx !== -1) model.items.splice(idx, 1);
+    } else if (event.type === "remove") {
+      model.items.push(event.item);
+    }
+  },
+};
+
+describe("createFcpServer", () => {
+  it("creates an MCP server without errors", () => {
+    const server = createFcpServer({
+      domain: "test",
+      adapter: testAdapter,
+      verbs: testVerbs,
+    });
+    expect(server).toBeDefined();
+  });
+
+  it("creates a server with reference card sections", () => {
+    const server = createFcpServer({
+      domain: "test",
+      adapter: testAdapter,
+      verbs: testVerbs,
+      referenceCard: {
+        sections: { "Notes": "Some additional notes" },
+      },
+    });
+    expect(server).toBeDefined();
+  });
+});

package/tests/session.test.ts

@@ -0,0 +1,210 @@
+import { describe, it, expect, vi } from "vitest";
+import { SessionDispatcher, type SessionHooks } from "../src/session.js";
+import { EventLog } from "../src/event-log.js";
+
+interface MockModel {
+  title: string;
+  data: string[];
+}
+
+function createMockSession() {
+  const eventLog = new EventLog<string>();
+  const hooks: SessionHooks<MockModel> = {
+    onNew: vi.fn((params) => ({
+      title: params["title"] ?? "Untitled",
+      data: [],
+    })),
+    onOpen: vi.fn(async (path) => ({
+      title: path,
+      data: ["loaded"],
+    })),
+    onSave: vi.fn(async () => {}),
+    onRebuildIndices: vi.fn(),
+    getDigest: vi.fn((model) => `[${model.title}: ${model.data.length} items]`),
+  };
+  const reverseEvent = vi.fn();
+  const replayEvent = vi.fn();
+  const session = new SessionDispatcher<MockModel, string>(hooks, eventLog, {
+    reverseEvent,
+    replayEvent,
+  });
+  return { session, hooks, eventLog, reverseEvent, replayEvent };
+}
+
+describe("SessionDispatcher", () => {
+  describe("new", () => {
+    it("creates a new model with title", async () => {
+      const { session, hooks } = createMockSession();
+      const result = await session.dispatch('new "My Song"');
+      expect(result).toBe('new "My Song" created');
+      expect(session.model).not.toBeNull();
+      expect(session.model?.title).toBe("My Song");
+      expect(hooks.onNew).toHaveBeenCalledWith({ title: "My Song" });
+    });
+
+    it("creates a new model with params", async () => {
+      const { session, hooks } = createMockSession();
+      await session.dispatch('new "Test" tempo:120');
+      expect(hooks.onNew).toHaveBeenCalledWith({ title: "Test", tempo: "120" });
+    });
+
+    it("defaults to Untitled", async () => {
+      const { session } = createMockSession();
+      const result = await session.dispatch("new");
+      expect(result).toBe('new "Untitled" created');
+    });
+
+    it("clears file path", async () => {
+      const { session } = createMockSession();
+      await session.dispatch("new Test");
+      expect(session.filePath).toBeNull();
+    });
+  });
+
+  describe("open", () => {
+    it("opens a file and sets model", async () => {
+      const { session, hooks } = createMockSession();
+      const result = await session.dispatch("open ./test.mid");
+      expect(result).toBe('opened "./test.mid"');
+      expect(session.model).not.toBeNull();
+      expect(session.filePath).toBe("./test.mid");
+      expect(hooks.onOpen).toHaveBeenCalledWith("./test.mid");
+    });
+
+    it("returns error when no path given", async () => {
+      const { session } = createMockSession();
+      const result = await session.dispatch("open");
+      expect(result).toBe("open requires a file path");
+    });
+
+    it("returns error message on failure", async () => {
+      const { session, hooks } = createMockSession();
+      (hooks.onOpen as ReturnType<typeof vi.fn>).mockRejectedValue(new Error("file not found"));
+      const result = await session.dispatch("open ./missing.mid");
+      expect(result).toBe("error: file not found");
+    });
+  });
+
+  describe("save", () => {
+    it("saves to the open file path", async () => {
+      const { session, hooks } = createMockSession();
+      await session.dispatch("open ./test.mid");
+      const result = await session.dispatch("save");
+      expect(result).toBe('saved "./test.mid"');
+      expect(hooks.onSave).toHaveBeenCalled();
+    });
+
+    it("saves to a new path with as:", async () => {
+      const { session } = createMockSession();
+      await session.dispatch("new Test");
+      const result = await session.dispatch("save as:./output.mid");
+      expect(result).toBe('saved "./output.mid"');
+      expect(session.filePath).toBe("./output.mid");
+    });
+
+    it("returns error when no model", async () => {
+      const { session } = createMockSession();
+      const result = await session.dispatch("save");
+      expect(result).toBe("error: no model to save");
+    });
+
+    it("returns error when no path", async () => {
+      const { session } = createMockSession();
+      await session.dispatch("new Test");
+      const result = await session.dispatch("save");
+      expect(result).toBe("error: no file path. Use save as:./file");
+    });
+  });
+
+  describe("checkpoint", () => {
+    it("creates a checkpoint", async () => {
+      const { session, eventLog } = createMockSession();
+      const result = await session.dispatch("checkpoint v1");
+      expect(result).toBe('checkpoint "v1" created');
+      expect(eventLog.cursor).toBeGreaterThan(0);
+    });
+
+    it("requires a name", async () => {
+      const { session } = createMockSession();
+      const result = await session.dispatch("checkpoint");
+      expect(result).toBe("checkpoint requires a name");
+    });
+  });
+
+  describe("undo", () => {
+    it("undoes events", async () => {
+      const { session, eventLog } = createMockSession();
+      await session.dispatch("new Test");
+      eventLog.append("event1");
+      eventLog.append("event2");
+      const result = await session.dispatch("undo");
+      expect(result).toBe("undone 1 event");
+    });
+
+    it("returns nothing to undo when empty", async () => {
+      const { session } = createMockSession();
+      const result = await session.dispatch("undo");
+      expect(result).toBe("nothing to undo");
+    });
+
+    it("undoes to a checkpoint", async () => {
+      const { session, eventLog } = createMockSession();
+      await session.dispatch("new Test");
+      eventLog.append("event1");
+      await session.dispatch("checkpoint v1");
+      eventLog.append("event2");
+      eventLog.append("event3");
+      const result = await session.dispatch("undo to:v1");
+      expect(result).toContain("undone");
+      expect(result).toContain("checkpoint");
+    });
+
+    it("calls onRebuildIndices after undo", async () => {
+      const { session, hooks, eventLog } = createMockSession();
+      await session.dispatch("new Test");
+      eventLog.append("event1");
+      await session.dispatch("undo");
+      expect(hooks.onRebuildIndices).toHaveBeenCalled();
+    });
+  });
+
+  describe("redo", () => {
+    it("redoes events", async () => {
+      const { session, eventLog } = createMockSession();
+      await session.dispatch("new Test");
+      eventLog.append("event1");
+      eventLog.undo();
+      const result = await session.dispatch("redo");
+      expect(result).toBe("redone 1 event");
+    });
+
+    it("returns nothing to redo when at end", async () => {
+      const { session } = createMockSession();
+      const result = await session.dispatch("redo");
+      expect(result).toBe("nothing to redo");
+    });
+
+    it("calls onRebuildIndices after redo", async () => {
+      const { session, hooks, eventLog } = createMockSession();
+      await session.dispatch("new Test");
+      eventLog.append("event1");
+      eventLog.undo();
+      await session.dispatch("redo");
+      expect(hooks.onRebuildIndices).toHaveBeenCalled();
+    });
+  });
+
+  describe("unknown commands", () => {
+    it("returns error for unknown actions", async () => {
+      const { session } = createMockSession();
+      const result = await session.dispatch("explode");
+      expect(result).toBe('unknown session action "explode"');
+    });
+
+    it("returns error for empty action", async () => {
+      const { session } = createMockSession();
+      const result = await session.dispatch("");
+      expect(result).toBe("empty action");
+    });
+  });
+});

package/tests/tokenizer.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect } from "vitest";
+import { tokenize, isKeyValue, parseKeyValue, isArrow, isSelector } from "../src/tokenizer.js";
+
+describe("tokenize", () => {
+  it("splits simple tokens", () => {
+    expect(tokenize("add svc AuthService")).toEqual(["add", "svc", "AuthService"]);
+  });
+
+  it("handles quoted strings", () => {
+    expect(tokenize('add svc "Auth Service" theme:blue')).toEqual([
+      "add", "svc", "Auth Service", "theme:blue",
+    ]);
+  });
+
+  it("handles escaped quotes inside quoted strings", () => {
+    expect(tokenize('label A "say \\"hello\\""')).toEqual([
+      "label", "A", 'say "hello"',
+    ]);
+  });
+
+  it("handles empty input", () => {
+    expect(tokenize("")).toEqual([]);
+  });
+
+  it("handles whitespace-only input", () => {
+    expect(tokenize("   ")).toEqual([]);
+  });
+
+  it("handles multiple spaces between tokens", () => {
+    expect(tokenize("add   svc   A")).toEqual(["add", "svc", "A"]);
+  });
+
+  it("converts literal \\n to newline in unquoted tokens", () => {
+    expect(tokenize("add svc Container\\nRegistry")).toEqual([
+      "add", "svc", "Container\nRegistry",
+    ]);
+  });
+
+  it("converts literal \\n to newline in quoted strings", () => {
+    expect(tokenize('add svc "Container\\nRegistry"')).toEqual([
+      "add", "svc", "Container\nRegistry",
+    ]);
+  });
+
+  it("handles embedded quoted values (key:\"value\")", () => {
+    expect(tokenize('label:"Line1\\nLine2"')).toEqual(["label:Line1\nLine2"]);
+  });
+
+  it("converts multiple \\n sequences", () => {
+    expect(tokenize("add svc A\\nB\\nC")).toEqual(["add", "svc", "A\nB\nC"]);
+  });
+
+  it("handles single token", () => {
+    expect(tokenize("add")).toEqual(["add"]);
+  });
+
+  it("handles empty quoted string", () => {
+    expect(tokenize('""')).toEqual([""]);
+  });
+
+  it("handles unclosed quote (takes rest as token)", () => {
+    expect(tokenize('"hello world')).toEqual(["hello world"]);
+  });
+
+  it("handles escaped backslash in quotes", () => {
+    expect(tokenize('"path\\\\dir"')).toEqual(["path\\dir"]);
+  });
+
+  it("handles key:value with colons in value", () => {
+    expect(tokenize("url:http://example.com")).toEqual(["url:http://example.com"]);
+  });
+});
+
+describe("isKeyValue", () => {
+  it("returns true for key:value", () => {
+    expect(isKeyValue("theme:blue")).toBe(true);
+  });
+
+  it("returns true for key:value with colons in value", () => {
+    expect(isKeyValue("url:http://x")).toBe(true);
+  });
+
+  it("returns false for selectors", () => {
+    expect(isKeyValue("@type:db")).toBe(false);
+  });
+
+  it("returns false for arrows", () => {
+    expect(isKeyValue("->")).toBe(false);
+  });
+
+  it("returns false for plain words", () => {
+    expect(isKeyValue("hello")).toBe(false);
+  });
+
+  it("returns false for trailing colon", () => {
+    expect(isKeyValue("key:")).toBe(false);
+  });
+
+  it("returns false for leading colon", () => {
+    expect(isKeyValue(":value")).toBe(false);
+  });
+});
+
+describe("parseKeyValue", () => {
+  it("parses simple key:value", () => {
+    expect(parseKeyValue("theme:blue")).toEqual({ key: "theme", value: "blue" });
+  });
+
+  it("parses value with colons", () => {
+    expect(parseKeyValue("url:http://x:8080")).toEqual({ key: "url", value: "http://x:8080" });
+  });
+});
+
+describe("isArrow", () => {
+  it("recognizes ->", () => {
+    expect(isArrow("->")).toBe(true);
+  });
+
+  it("recognizes <->", () => {
+    expect(isArrow("<->")).toBe(true);
+  });
+
+  it("recognizes --", () => {
+    expect(isArrow("--")).toBe(true);
+  });
+
+  it("rejects other tokens", () => {
+    expect(isArrow("=>")).toBe(false);
+    expect(isArrow("add")).toBe(false);
+  });
+});
+
+describe("isSelector", () => {
+  it("recognizes @-prefixed tokens", () => {
+    expect(isSelector("@type:db")).toBe(true);
+    expect(isSelector("@all")).toBe(true);
+    expect(isSelector("@recent:5")).toBe(true);
+  });
+
+  it("rejects non-@ tokens", () => {
+    expect(isSelector("type:db")).toBe(false);
+    expect(isSelector("add")).toBe(false);
+  });
+});

package/tests/verb-registry.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from "vitest";
+import { VerbRegistry, type VerbSpec } from "../src/verb-registry.js";
+
+describe("VerbRegistry", () => {
+  function createTestRegistry(): VerbRegistry {
+    const reg = new VerbRegistry();
+    reg.registerMany([
+      { verb: "add", syntax: "add TYPE LABEL [key:value]", category: "create" },
+      { verb: "remove", syntax: "remove SELECTOR", category: "modify" },
+      { verb: "connect", syntax: "connect SRC -> TGT", category: "create", description: "Create an edge" },
+      { verb: "style", syntax: "style REF [fill:#HEX]", category: "modify", params: ["fill", "stroke"] },
+    ]);
+    return reg;
+  }
+
+  describe("register/lookup", () => {
+    it("registers and looks up a verb", () => {
+      const reg = new VerbRegistry();
+      const spec: VerbSpec = { verb: "add", syntax: "add TYPE LABEL", category: "create" };
+      reg.register(spec);
+      expect(reg.lookup("add")).toEqual(spec);
+    });
+
+    it("returns undefined for unknown verbs", () => {
+      const reg = new VerbRegistry();
+      expect(reg.lookup("nonexistent")).toBeUndefined();
+    });
+
+    it("registers many at once", () => {
+      const reg = createTestRegistry();
+      expect(reg.lookup("add")).toBeDefined();
+      expect(reg.lookup("remove")).toBeDefined();
+      expect(reg.lookup("connect")).toBeDefined();
+      expect(reg.lookup("style")).toBeDefined();
+    });
+  });
+
+  describe("verbs", () => {
+    it("returns all registered specs", () => {
+      const reg = createTestRegistry();
+      expect(reg.verbs).toHaveLength(4);
+      const verbs = reg.verbs.map((v) => v.verb);
+      expect(verbs).toContain("add");
+      expect(verbs).toContain("remove");
+      expect(verbs).toContain("connect");
+      expect(verbs).toContain("style");
+    });
+  });
+
+  describe("generateReferenceCard", () => {
+    it("groups verbs by category", () => {
+      const reg = createTestRegistry();
+      const card = reg.generateReferenceCard();
+      expect(card).toContain("CREATE:");
+      expect(card).toContain("MODIFY:");
+      expect(card).toContain("  add TYPE LABEL [key:value]");
+      expect(card).toContain("  connect SRC -> TGT");
+      expect(card).toContain("  remove SELECTOR");
+      expect(card).toContain("  style REF [fill:#HEX]");
+    });
+
+    it("appends additional sections", () => {
+      const reg = createTestRegistry();
+      const card = reg.generateReferenceCard({
+        "Themes": "  blue  #dae8fc\n  red   #f8cecc",
+      });
+      expect(card).toContain("THEMES:");
+      expect(card).toContain("  blue  #dae8fc");
+    });
+
+    it("returns empty string for empty registry", () => {
+      const reg = new VerbRegistry();
+      expect(reg.generateReferenceCard()).toBe("");
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["tests/**/*.test.ts"],
+  },
+});