@aetherwing/fcp-core 0.1.0

package/src/session.ts

@@ -0,0 +1,163 @@
+import { EventLog } from "./event-log.js";
+import { tokenize, isKeyValue, parseKeyValue } from "./tokenizer.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 class SessionDispatcher<Model, Event> {
+  private _model: Model | null = null;
+  private _filePath: string | null = null;
+  private hooks: SessionHooks<Model>;
+  private eventLog: EventLog<Event>;
+  private reverseEvent: (event: Event, model: Model) => void;
+  private replayEvent: (event: Event, model: Model) => void;
+
+  constructor(
+    hooks: SessionHooks<Model>,
+    eventLog: EventLog<Event>,
+    options: {
+      reverseEvent: (event: Event, model: Model) => void;
+      replayEvent: (event: Event, model: Model) => void;
+    },
+  ) {
+    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: string): Promise<string> {
+    const tokens = tokenize(action);
+    if (tokens.length === 0) return "empty action";
+
+    const cmd = tokens[0].toLowerCase();
+
+    switch (cmd) {
+      case "new": {
+        const params: Record<string, string> = {};
+        const positionals: string[] = [];
+        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: unknown) {
+          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: unknown) {
+          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(): Model | null {
+    return this._model;
+  }
+
+  get filePath(): string | null {
+    return this._filePath;
+  }
+}

package/src/tokenizer.ts

@@ -0,0 +1,108 @@
+/**
+ * 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: string): string[] {
+  const tokens: string[] = [];
+  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: string): boolean {
+  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: string): { key: string; value: string } {
+  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: string): boolean {
+  return token === "->" || token === "<->" || token === "--";
+}
+
+/**
+ * Check if a token is a selector (@-prefixed).
+ */
+export function isSelector(token: string): boolean {
+  return token.startsWith("@");
+}

package/src/verb-registry.ts

@@ -0,0 +1,84 @@
+/**
+ * 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 class VerbRegistry {
+  private specs = new Map<string, VerbSpec>();
+  private categories = new Map<string, VerbSpec[]>();
+
+  /**
+   * Register a single verb specification.
+   */
+  register(spec: VerbSpec): void {
+    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: VerbSpec[]): void {
+    for (const spec of specs) {
+      this.register(spec);
+    }
+  }
+
+  /**
+   * Look up a verb specification by name.
+   */
+  lookup(verb: string): VerbSpec | undefined {
+    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?: Record<string, string>): string {
+    const lines: string[] = [];
+
+    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(): VerbSpec[] {
+    return [...this.specs.values()];
+  }
+}

package/tests/event-log.test.ts

@@ -0,0 +1,177 @@
+import { describe, it, expect } from "vitest";
+import { EventLog } from "../src/event-log.js";
+
+describe("EventLog", () => {
+  it("appends events and advances cursor", () => {
+    const log = new EventLog<string>();
+    log.append("a");
+    log.append("b");
+    expect(log.cursor).toBe(2);
+    expect(log.length).toBe(2);
+  });
+
+  it("returns recent events in chronological order", () => {
+    const log = new EventLog<string>();
+    log.append("a");
+    log.append("b");
+    log.append("c");
+    expect(log.recent(2)).toEqual(["b", "c"]);
+    expect(log.recent()).toEqual(["a", "b", "c"]);
+  });
+
+  describe("undo", () => {
+    it("returns most recent event", () => {
+      const log = new EventLog<string>();
+      log.append("a");
+      log.append("b");
+      const undone = log.undo();
+      expect(undone).toEqual(["b"]);
+      expect(log.cursor).toBe(1);
+    });
+
+    it("returns multiple events in reverse order", () => {
+      const log = new EventLog<string>();
+      log.append("a");
+      log.append("b");
+      log.append("c");
+      const undone = log.undo(2);
+      expect(undone).toEqual(["c", "b"]);
+      expect(log.cursor).toBe(1);
+    });
+
+    it("returns empty array when nothing to undo", () => {
+      const log = new EventLog<string>();
+      expect(log.undo()).toEqual([]);
+    });
+
+    it("skips checkpoint sentinels", () => {
+      const log = new EventLog<string>();
+      log.append("a");
+      log.checkpoint("cp1");
+      log.append("b");
+      const undone = log.undo(2);
+      expect(undone).toEqual(["b", "a"]);
+    });
+  });
+
+  describe("redo", () => {
+    it("re-applies undone events in forward order", () => {
+      const log = new EventLog<string>();
+      log.append("a");
+      log.append("b");
+      log.undo(2);
+      const redone = log.redo(2);
+      expect(redone).toEqual(["a", "b"]);
+      expect(log.cursor).toBe(2);
+    });
+
+    it("returns empty array when nothing to redo", () => {
+      const log = new EventLog<string>();
+      log.append("a");
+      expect(log.redo()).toEqual([]);
+    });
+
+    it("skips checkpoint sentinels during redo", () => {
+      const log = new EventLog<string>();
+      log.append("a");
+      log.checkpoint("cp1");
+      log.append("b");
+      log.undo(2);
+      const redone = log.redo(2);
+      expect(redone).toEqual(["a", "b"]);
+    });
+  });
+
+  describe("redo tail truncation", () => {
+    it("truncates redo history on new append", () => {
+      const log = new EventLog<string>();
+      log.append("a");
+      log.append("b");
+      log.undo(); // cursor at 1, "b" is in redo tail
+      log.append("c"); // should truncate "b"
+      expect(log.length).toBe(2); // "a", "c"
+      expect(log.redo()).toEqual([]); // no redo available
+      expect(log.recent()).toEqual(["a", "c"]);
+    });
+  });
+
+  describe("checkpoint", () => {
+    it("creates a checkpoint that can be undone to", () => {
+      const log = new EventLog<string>();
+      log.append("a");
+      log.checkpoint("v1");
+      log.append("b");
+      log.append("c");
+      const undone = log.undoTo("v1");
+      expect(undone).toEqual(["c", "b"]);
+      // cursor should be at checkpoint position
+      expect(log.recent()).toEqual(["a"]);
+    });
+
+    it("returns null for unknown checkpoint", () => {
+      const log = new EventLog<string>();
+      log.append("a");
+      expect(log.undoTo("nonexistent")).toBeNull();
+    });
+
+    it("returns null if checkpoint is at/beyond cursor", () => {
+      const log = new EventLog<string>();
+      log.append("a");
+      log.checkpoint("v1");
+      // Undo past the checkpoint
+      log.undo(); // undo "a" (checkpoint is skipped)
+      // Now cursor is before the checkpoint, so undoTo should still work
+      // Actually: checkpoint is at position 1, cursor after undo of "a" is at 0
+      // So target(1) >= cursor(0) is false, it should work
+      // Let me test a different scenario where checkpoint IS at cursor
+      const log2 = new EventLog<string>();
+      log2.checkpoint("v1"); // checkpoint at position 0
+      log2.append("a");
+      // cursor is 2, checkpoint is 0 — should work
+      const result = log2.undoTo("v1");
+      expect(result).toEqual(["a"]);
+    });
+
+    it("removes checkpoints beyond cursor on truncation", () => {
+      const log = new EventLog<string>();
+      log.append("a");
+      log.checkpoint("v1");
+      log.append("b");
+      log.undo(2); // undo b and a, cursor before checkpoint
+      log.append("x"); // truncates everything including checkpoint
+      expect(log.undoTo("v1")).toBeNull(); // checkpoint gone
+    });
+  });
+
+  describe("cursor management", () => {
+    it("starts at 0", () => {
+      const log = new EventLog<string>();
+      expect(log.cursor).toBe(0);
+    });
+
+    it("advances on append", () => {
+      const log = new EventLog<string>();
+      log.append("a");
+      expect(log.cursor).toBe(1);
+      log.append("b");
+      expect(log.cursor).toBe(2);
+    });
+
+    it("moves back on undo", () => {
+      const log = new EventLog<string>();
+      log.append("a");
+      log.append("b");
+      log.undo();
+      expect(log.cursor).toBe(1);
+    });
+
+    it("moves forward on redo", () => {
+      const log = new EventLog<string>();
+      log.append("a");
+      log.append("b");
+      log.undo();
+      log.redo();
+      expect(log.cursor).toBe(2);
+    });
+  });
+});

package/tests/formatter.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+import { formatResult, suggest } from "../src/formatter.js";
+
+describe("formatResult", () => {
+  it("formats success with prefix", () => {
+    expect(formatResult(true, "svc AuthService", "+")).toBe("+ svc AuthService");
+  });
+
+  it("formats success without prefix", () => {
+    expect(formatResult(true, "done")).toBe("done");
+  });
+
+  it("formats error", () => {
+    expect(formatResult(false, "something broke")).toBe("ERROR: something broke");
+  });
+
+  it("formats error ignoring prefix", () => {
+    expect(formatResult(false, "bad input", "+")).toBe("ERROR: bad input");
+  });
+
+  it("handles standard prefix conventions", () => {
+    expect(formatResult(true, "AuthService", "+")).toBe("+ AuthService"); // created
+    expect(formatResult(true, "edge A->B", "~")).toBe("~ edge A->B");   // modified
+    expect(formatResult(true, "styled A", "*")).toBe("* styled A");     // changed
+    expect(formatResult(true, "A", "-")).toBe("- A");                    // removed
+    expect(formatResult(true, "group Backend", "!")).toBe("! group Backend"); // meta
+    expect(formatResult(true, "layout", "@")).toBe("@ layout");          // bulk
+  });
+});
+
+describe("suggest", () => {
+  const candidates = ["add", "remove", "connect", "style", "label", "badge"];
+
+  it("suggests exact match", () => {
+    expect(suggest("add", candidates)).toBe("add");
+  });
+
+  it("suggests for single-char typo", () => {
+    expect(suggest("ad", candidates)).toBe("add");
+  });
+
+  it("suggests for transposition", () => {
+    expect(suggest("styel", candidates)).toBe("style");
+  });
+
+  it("suggests for substitution", () => {
+    expect(suggest("labek", candidates)).toBe("label");
+  });
+
+  it("returns null for distant strings", () => {
+    expect(suggest("zzzzzzz", candidates)).toBeNull();
+  });
+
+  it("returns null for empty candidates", () => {
+    expect(suggest("test", [])).toBeNull();
+  });
+
+  it("picks closest when multiple are close", () => {
+    expect(suggest("bade", candidates)).toBe("badge");
+  });
+});

package/tests/parsed-op.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from "vitest";
+import { parseOp, isParseError } from "../src/parsed-op.js";
+
+describe("parseOp", () => {
+  it("parses a simple verb with positionals", () => {
+    const result = parseOp("add svc AuthService");
+    expect(isParseError(result)).toBe(false);
+    if (isParseError(result)) return;
+    expect(result.verb).toBe("add");
+    expect(result.positionals).toEqual(["svc", "AuthService"]);
+    expect(result.params).toEqual({});
+    expect(result.selectors).toEqual([]);
+  });
+
+  it("extracts key:value params", () => {
+    const result = parseOp("add svc AuthService theme:blue near:Gateway");
+    if (isParseError(result)) return;
+    expect(result.verb).toBe("add");
+    expect(result.positionals).toEqual(["svc", "AuthService"]);
+    expect(result.params).toEqual({ theme: "blue", near: "Gateway" });
+  });
+
+  it("extracts selectors", () => {
+    const result = parseOp("remove @type:db @recent:3");
+    if (isParseError(result)) return;
+    expect(result.verb).toBe("remove");
+    expect(result.selectors).toEqual(["@type:db", "@recent:3"]);
+    expect(result.positionals).toEqual([]);
+  });
+
+  it("handles mixed token types", () => {
+    const result = parseOp("style @type:svc fill:#ff0000 bold");
+    if (isParseError(result)) return;
+    expect(result.verb).toBe("style");
+    expect(result.selectors).toEqual(["@type:svc"]);
+    expect(result.params).toEqual({ fill: "#ff0000" });
+    expect(result.positionals).toEqual(["bold"]);
+  });
+
+  it("lowercases the verb", () => {
+    const result = parseOp("ADD svc Test");
+    if (isParseError(result)) return;
+    expect(result.verb).toBe("add");
+  });
+
+  it("preserves original input as raw", () => {
+    const result = parseOp("  add svc Test  ");
+    if (isParseError(result)) return;
+    expect(result.raw).toBe("add svc Test");
+  });
+
+  it("handles quoted positionals", () => {
+    const result = parseOp('label Gateway "API Gateway v2"');
+    if (isParseError(result)) return;
+    expect(result.positionals).toEqual(["Gateway", "API Gateway v2"]);
+  });
+
+  it("returns error for empty input", () => {
+    const result = parseOp("");
+    expect(isParseError(result)).toBe(true);
+    if (!isParseError(result)) return;
+    expect(result.error).toBe("empty operation");
+  });
+
+  it("returns error for whitespace-only input", () => {
+    const result = parseOp("   ");
+    expect(isParseError(result)).toBe(true);
+  });
+
+  it("handles arrows as positionals", () => {
+    const result = parseOp("connect A -> B");
+    if (isParseError(result)) return;
+    expect(result.positionals).toEqual(["A", "->", "B"]);
+  });
+
+  it("handles verb-only input", () => {
+    const result = parseOp("undo");
+    if (isParseError(result)) return;
+    expect(result.verb).toBe("undo");
+    expect(result.positionals).toEqual([]);
+    expect(result.params).toEqual({});
+    expect(result.selectors).toEqual([]);
+  });
+});
+
+describe("isParseError", () => {
+  it("returns true for errors", () => {
+    expect(isParseError({ success: false, error: "test", raw: "" })).toBe(true);
+  });
+
+  it("returns false for valid ops", () => {
+    const result = parseOp("add test");
+    expect(isParseError(result)).toBe(false);
+  });
+});