@cueloop/schema 0.1.0-alpha.78 → 0.1.0-alpha.79

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/schema",
-  "version": "0.1.0-alpha.78",
+  "version": "0.1.0-alpha.79",
   "description": "The Thread primitive: types, markdown block model, quote-primary anchors, feedback serialization",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from "./types";
 export * from "./participants";
 export * from "./share-access";
+export * from "./share-links";
 export * from "./markdown";
 export * from "./inline";
 export * from "./working-copy";

package/src/markdown.test.ts

@@ -102,13 +102,74 @@ describe("parseBlocks", () => {
 
   test("unknown constructs degrade to paragraphs, no content lost", () => {
     // Arrange
-    const md = "| a | b |\n|---|---|\n| 1 | 2 |";
+    const md = "<div>raw html</div>";
 
     // Act
     const blocks = parseBlocks(md);
 
     // Assert
-    expect(blocks.map((block) => block.text).join("\n")).toContain("| a | b |");
+    expect(blocks.map((block) => block.kind)).toEqual(["p"]);
+    expect(blocks[0]!.text).toBe("<div>raw html</div>");
+  });
+
+  test("a GFM table parses to one table block that keeps its source verbatim", () => {
+    // Arrange
+    const md = "before\n\n| a | b |\n|---|---|\n| 1 | 2 |\n| 3 | 4 |\n\nafter";
+
+    // Act
+    const blocks = parseBlocks(md);
+
+    // Assert
+    expect(blocks.map((block) => block.kind)).toEqual(["p", "table", "p"]);
+    const table = blocks.find((block) => block.kind === "table")!;
+
+    expect(table.text).toBe("| a | b |\n|---|---|\n| 1 | 2 |\n| 3 | 4 |");
+  });
+
+  test("a single-column table and an aligned delimiter still parse as a table", () => {
+    // Assert
+    expect(parseBlocks("| only |\n| --- |\n| one |")[0]!.kind).toBe("table");
+    expect(parseBlocks("| l | r |\n| :--- | ---: |\n| a | b |")[0]!.kind).toBe("table");
+  });
+
+  test("a plain rule line is an hr, never a table", () => {
+    // Assert
+    expect(parseBlocks("above\n\n---\n\nbelow").map((block) => block.kind)).toEqual([
+      "p",
+      "hr",
+      "p",
+    ]);
+  });
+
+  test("leading frontmatter parses to a frontmatter block, closed by its fence", () => {
+    // Arrange
+    const md = "---\ntitle: Plan\nowner: me\n---\n\n# Heading\n";
+
+    // Act
+    const blocks = parseBlocks(md);
+
+    // Assert
+    expect(blocks.map((block) => block.kind)).toEqual(["frontmatter", "h1"]);
+    expect(blocks[0]!.text).toBe("title: Plan\nowner: me");
+  });
+
+  test("a leading fence with no closing fence stays an hr, not frontmatter", () => {
+    // Assert
+    expect(parseBlocks("---\njust a paragraph\n").map((block) => block.kind)).toEqual(["hr", "p"]);
+  });
+
+  test("table and frontmatter round-trip through blockToMd", () => {
+    // Arrange
+    const md = "---\ntitle: Plan\n---\n\n| a | b |\n|---|---|\n| 1 | 2 |";
+    const blocks = parseBlocks(md);
+
+    // Act
+    const rebuilt = blocks.map((block) => blockToMd(block)).join("\n\n");
+
+    // Assert
+    expect(parseBlocks(rebuilt).map((block) => [block.kind, block.text])).toEqual(
+      blocks.map((block) => [block.kind, block.text]),
+    );
   });
 });
 

package/src/markdown.ts

@@ -6,11 +6,22 @@
  * so no content is ever lost.
  */
 
-export type BlockKind = "h1" | "h2" | "h3" | "p" | "li" | "oli" | "quote" | "code" | "hr";
+export type BlockKind =
+  | "h1"
+  | "h2"
+  | "h3"
+  | "p"
+  | "li"
+  | "oli"
+  | "quote"
+  | "code"
+  | "hr"
+  | "table"
+  | "frontmatter";
 
 export interface Block {
   kind: BlockKind;
-  /** Content with markers stripped; code blocks keep inner lines verbatim. */
+  /** Content with markers stripped; code, table, and frontmatter blocks keep inner lines verbatim. */
   text: string;
   /** For code blocks: the fence info string ("ts", "diff", ...). */
   lang?: string;
@@ -31,110 +42,193 @@ export function stripLeadingBlockMarker(line: string): string {
   return line.replace(LEADING_BLOCK_MARKER, "");
 }
 
+/** A GFM table delimiter row: one or more dash cells split by pipes, each optionally `:`-aligned. */
+function isTableDelimiterRow(line: string): boolean {
+  if (!line.includes("|")) return false;
+  const cells = line
+    .trim()
+    .replace(/^\||\|$/g, "")
+    .split("|");
+
+  return cells.length >= 1 && cells.every((cell) => /^\s*:?-+:?\s*$/.test(cell));
+}
+
+/** A GFM table opens on a header row of pipe cells whose next line is a delimiter row. */
+function isTableStart(lines: string[], index: number): boolean {
+  const header = lines[index];
+  const delimiter = lines[index + 1];
+
+  return (
+    header !== undefined &&
+    header.includes("|") &&
+    delimiter !== undefined &&
+    isTableDelimiterRow(delimiter)
+  );
+}
+
 function isMarkerLine(line: string): boolean {
   return (
     line.startsWith("```") || LEADING_BLOCK_MARKER.test(line) || /^(---|\*\*\*|___)\s*$/.test(line)
   );
 }
 
+/**
+ * Leading YAML frontmatter: a --- fence on the very first line, closed by a
+ * second --- fence. Null when there is no leading fence or no closing fence -
+ * a lone leading --- then falls through to an hr.
+ */
+function frontmatterBlock(lines: string[]): Block | null {
+  if (lines[0]?.trim() !== "---") return null;
+  let close = 1;
+
+  while (close < lines.length && lines[close]!.trim() !== "---") close++;
+  if (close >= lines.length) return null;
+
+  return {
+    kind: "frontmatter",
+    text: lines.slice(1, close).join("\n"),
+    lineStart: 0,
+    lineEnd: close,
+  };
+}
+
+/** A block consumed from a line span, with the next line to resume parsing at. */
+interface BlockScan {
+  block: Block;
+  next: number;
+}
+
+/** A one-line block - a heading, a rule, a bullet, or an ordered item - at `lineIndex`, or null. */
+function singleLineBlock(line: string, lineIndex: number): Block | null {
+  const marked = (kind: BlockKind): Block => ({
+    kind,
+    text: stripLeadingBlockMarker(line),
+    lineStart: lineIndex,
+    lineEnd: lineIndex,
+  });
+
+  if (line.startsWith("### ")) return marked("h3");
+  if (line.startsWith("## ")) return marked("h2");
+  if (line.startsWith("# ")) return marked("h1");
+  if (/^(---|\*\*\*|___)\s*$/.test(line)) {
+    return { kind: "hr", text: "", lineStart: lineIndex, lineEnd: lineIndex };
+  }
+  if (line.startsWith("- ")) return marked("li");
+  if (/^\d+\. /.test(line)) return marked("oli");
+
+  return null;
+}
+
+/** Consume a fenced code block from its opening ``` at `start`. */
+function codeBlock(lines: string[], start: number): BlockScan {
+  const lang = lines[start]!.slice(3).trim() || undefined;
+  let index = start + 1;
+  const body: string[] = [];
+
+  while (index < lines.length && !lines[index]!.startsWith("```")) {
+    body.push(lines[index]!);
+    index++;
+  }
+  const end = Math.min(index, lines.length - 1);
+
+  return {
+    block: { kind: "code", text: body.join("\n"), lang, lineStart: start, lineEnd: end },
+    next: index + 1,
+  };
+}
+
+/** Consume a blockquote's consecutive `> ` lines from `start`. */
+function quoteBlock(lines: string[], start: number): BlockScan {
+  let index = start;
+  const body: string[] = [];
+
+  while (index < lines.length && lines[index]!.startsWith("> ")) {
+    body.push(stripLeadingBlockMarker(lines[index]!));
+    index++;
+  }
+
+  return {
+    block: { kind: "quote", text: body.join("\n"), lineStart: start, lineEnd: index - 1 },
+    next: index,
+  };
+}
+
+/** Consume a GFM table (header, delimiter, then pipe rows) from `start`. */
+function tableBlock(lines: string[], start: number): BlockScan {
+  const body: string[] = [lines[start]!, lines[start + 1]!];
+  let index = start + 2;
+
+  // body rows run until a blank line, a fence, or a line without a pipe
+  while (
+    index < lines.length &&
+    lines[index]!.trim() !== "" &&
+    lines[index]!.includes("|") &&
+    !lines[index]!.startsWith("```")
+  ) {
+    body.push(lines[index]!);
+    index++;
+  }
+
+  return {
+    block: { kind: "table", text: body.join("\n"), lineStart: start, lineEnd: index - 1 },
+    next: index,
+  };
+}
+
+/** Consume a paragraph: consecutive prose lines until a blank line, a marker, or a table. */
+function paragraphBlock(lines: string[], start: number): BlockScan {
+  let index = start;
+  const body: string[] = [];
+
+  while (
+    index < lines.length &&
+    lines[index]!.trim() !== "" &&
+    !isMarkerLine(lines[index]!) &&
+    !isTableStart(lines, index)
+  ) {
+    body.push(lines[index]!);
+    index++;
+  }
+
+  return {
+    block: { kind: "p", text: body.join("\n"), lineStart: start, lineEnd: index - 1 },
+    next: index,
+  };
+}
+
+/** The next block starting at `lineIndex` (never a blank line, never frontmatter). */
+function nextBlock(lines: string[], lineIndex: number): BlockScan {
+  const line = lines[lineIndex]!;
+
+  if (line.startsWith("```")) return codeBlock(lines, lineIndex);
+  const single = singleLineBlock(line, lineIndex);
+
+  if (single) return { block: single, next: lineIndex + 1 };
+  if (line.startsWith("> ")) return quoteBlock(lines, lineIndex);
+  if (isTableStart(lines, lineIndex)) return tableBlock(lines, lineIndex);
+
+  return paragraphBlock(lines, lineIndex);
+}
+
 export function parseBlocks(markdown: string): Block[] {
   const lines = markdown.split("\n");
   const blocks: Block[] = [];
   let lineIndex = 0;
+  const frontmatter = frontmatterBlock(lines);
 
+  if (frontmatter) {
+    blocks.push(frontmatter);
+    lineIndex = frontmatter.lineEnd + 1;
+  }
   while (lineIndex < lines.length) {
-    const line = lines[lineIndex]!;
-
-    if (line.trim() === "") {
+    if (lines[lineIndex]!.trim() === "") {
       lineIndex++;
       continue;
     }
-    if (line.startsWith("```")) {
-      const start = lineIndex;
-      const lang = line.slice(3).trim() || undefined;
-
-      lineIndex++;
-      const body: string[] = [];
-
-      while (lineIndex < lines.length && !lines[lineIndex]!.startsWith("```")) {
-        body.push(lines[lineIndex]!);
-        lineIndex++;
-      }
-      const end = Math.min(lineIndex, lines.length - 1);
+    const scan = nextBlock(lines, lineIndex);
 
-      lineIndex++;
-      blocks.push({ kind: "code", text: body.join("\n"), lang, lineStart: start, lineEnd: end });
-    } else if (line.startsWith("### ")) {
-      blocks.push({
-        kind: "h3",
-        text: stripLeadingBlockMarker(line),
-        lineStart: lineIndex,
-        lineEnd: lineIndex,
-      });
-      lineIndex++;
-    } else if (line.startsWith("## ")) {
-      blocks.push({
-        kind: "h2",
-        text: stripLeadingBlockMarker(line),
-        lineStart: lineIndex,
-        lineEnd: lineIndex,
-      });
-      lineIndex++;
-    } else if (line.startsWith("# ")) {
-      blocks.push({
-        kind: "h1",
-        text: stripLeadingBlockMarker(line),
-        lineStart: lineIndex,
-        lineEnd: lineIndex,
-      });
-      lineIndex++;
-    } else if (/^(---|\*\*\*|___)\s*$/.test(line)) {
-      blocks.push({ kind: "hr", text: "", lineStart: lineIndex, lineEnd: lineIndex });
-      lineIndex++;
-    } else if (line.startsWith("> ")) {
-      const start = lineIndex;
-      const body: string[] = [];
-
-      while (lineIndex < lines.length && lines[lineIndex]!.startsWith("> ")) {
-        body.push(stripLeadingBlockMarker(lines[lineIndex]!));
-        lineIndex++;
-      }
-      blocks.push({
-        kind: "quote",
-        text: body.join("\n"),
-        lineStart: start,
-        lineEnd: lineIndex - 1,
-      });
-    } else if (line.startsWith("- ")) {
-      blocks.push({
-        kind: "li",
-        text: stripLeadingBlockMarker(line),
-        lineStart: lineIndex,
-        lineEnd: lineIndex,
-      });
-      lineIndex++;
-    } else if (/^\d+\. /.test(line)) {
-      blocks.push({
-        kind: "oli",
-        text: stripLeadingBlockMarker(line),
-        lineStart: lineIndex,
-        lineEnd: lineIndex,
-      });
-      lineIndex++;
-    } else {
-      const start = lineIndex;
-      const body: string[] = [];
-
-      while (
-        lineIndex < lines.length &&
-        lines[lineIndex]!.trim() !== "" &&
-        !isMarkerLine(lines[lineIndex]!)
-      ) {
-        body.push(lines[lineIndex]!);
-        lineIndex++;
-      }
-      blocks.push({ kind: "p", text: body.join("\n"), lineStart: start, lineEnd: lineIndex - 1 });
-    }
+    blocks.push(scan.block);
+    lineIndex = scan.next;
   }
 
   return blocks;
@@ -162,6 +256,10 @@ export function blockToMd(block: Block, ordinal = 1): string {
       return "```" + (block.lang ?? "") + "\n" + block.text + "\n```";
     case "hr":
       return "---";
+    case "frontmatter":
+      return "---\n" + block.text + "\n---";
+    case "table":
+      return block.text;
     default:
       return block.text;
   }

package/src/share-links.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import { SCHEMA_VERSION, type Thread } from "./types";
+import { threadShareLinks, withShareLinks } from "./share-links";
+
+function thread(overrides: Partial<Thread> = {}): Thread {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    id: "ses_1",
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: "plan", content: "# Plan\n", meta: {} },
+    revisions: [{ revision: 1, content: "# Plan\n", submittedAt: "2026-01-01T00:00:00.000Z" }],
+    annotations: [],
+    verdict: null,
+    status: "pending",
+    createdAt: "2026-01-01T00:00:00.000Z",
+    ...overrides,
+  };
+}
+
+describe("share-link migration", () => {
+  test("a never-shared thread has no links", () => {
+    expect(threadShareLinks(thread())).toBeUndefined();
+    expect(withShareLinks(thread()).shares).toBeUndefined();
+  });
+
+  test("a legacy private share migrates into a one-element list", () => {
+    const legacy = thread({
+      shareId: "p_abc123xy",
+      access: { githubLogins: ["octocat"] },
+      owner: "SHA256:owner",
+      shareBranch: "feature",
+    });
+
+    expect(withShareLinks(legacy).shares).toEqual([
+      {
+        id: "p_abc123xy",
+        requireAuth: true,
+        allowlist: ["octocat"],
+        owner: "SHA256:owner",
+        shareBranch: "feature",
+      },
+    ]);
+  });
+
+  test("a legacy public share migrates as requireAuth false with an empty allowlist", () => {
+    const legacy = thread({ shareId: "p_public00", owner: "SHA256:owner" });
+    const [link] = withShareLinks(legacy).shares!;
+
+    expect(link).toMatchObject({ id: "p_public00", requireAuth: false, allowlist: [] });
+  });
+
+  test("a thread that already has shares is returned untouched", () => {
+    const modern = thread({
+      shares: [{ id: "p_modern00", name: "team", requireAuth: false, allowlist: [] }],
+      // stale legacy fields must not override the explicit shares
+      shareId: "p_legacy00",
+    });
+
+    expect(withShareLinks(modern).shares).toEqual([
+      { id: "p_modern00", name: "team", requireAuth: false, allowlist: [] },
+    ]);
+  });
+});

package/src/share-links.ts

@@ -0,0 +1,29 @@
+import type { ShareLink, Thread } from "./types";
+
+/**
+ * A thread's share links, migrating a legacy single share (scalar shareId +
+ * access + owner + shareBranch) into a one-element list. Undefined when the
+ * thread was never shared. Records already carrying `shares` are returned as-is.
+ */
+export function threadShareLinks(session: Thread): ShareLink[] | undefined {
+  if (session.shares !== undefined) return session.shares;
+  if (session.shareId === undefined) return undefined;
+
+  return [
+    {
+      id: session.shareId,
+      requireAuth: session.access !== undefined,
+      allowlist: session.access?.githubLogins ?? [],
+      owner: session.owner,
+      shareBranch: session.shareBranch,
+    },
+  ];
+}
+
+/** The thread with `shares` populated from the legacy fields when absent; a never-shared thread is unchanged. */
+export function withShareLinks(session: Thread): Thread {
+  if (session.shares !== undefined) return session;
+  const shares = threadShareLinks(session);
+
+  return shares ? { ...session, shares } : session;
+}

package/src/types.ts

@@ -237,6 +237,27 @@ export interface ShareAccess {
   githubLogins: string[];
 }
 
+/**
+ * One published share link for a thread. A thread can have several, each an
+ * independent gateway blob keyed by its own `id`. `name` is a local-only label
+ * to tell links apart; `requireAuth` gates the link behind the `allowlist` of
+ * GitHub logins (empty + requireAuth is a private link with no one added yet).
+ */
+export interface ShareLink {
+  /** The share id (`p_…`), the link's address and gateway blob key. */
+  id: string;
+  /** A local, cosmetic label for the list; never leaves the planner's machine. */
+  name?: string;
+  /** True = private (only `allowlist` may open it); false = public. */
+  requireAuth: boolean;
+  /** GitHub logins allowed when `requireAuth`; ignored when public. */
+  allowlist: string[];
+  /** SSH fingerprint that created the link; the gateway stamps it to gate pulls/pushes/revokes. */
+  owner?: string;
+  /** The branch this link follows and shows collaborators; `main` when absent. */
+  shareBranch?: string;
+}
+
 export interface Thread {
   schemaVersion: string;
   id: string;
@@ -277,13 +298,15 @@ export interface Thread {
   shelvedAnnotations?: Annotation[];
   /** The session this one was forked from. */
   parentSessionId?: string;
-  /** Share id once published; lets the planner pull collaborator notes back. */
+  /** Published share links for this thread; each is an independent gateway blob. Migrated from the legacy scalar fields on read. */
+  shares?: ShareLink[];
+  /** @deprecated Legacy single-share id; migrated into `shares` on read. */
   shareId?: string;
-  /** The branch the share follows and shows collaborators; `main` when absent. */
+  /** @deprecated Legacy single-share branch; migrated into `shares` on read. */
   shareBranch?: string;
-  /** SSH fingerprint that created the share; the gateway stamps it to gate pulls. */
+  /** @deprecated Legacy single-share owner fingerprint; migrated into `shares` on read. */
   owner?: string;
-  /** Owner-set allowlist of GitHub logins for a private share; absent = public. */
+  /** @deprecated Legacy single-share allowlist; migrated into `shares` on read. */
   access?: ShareAccess;
   /**
    * Identities that authored annotations here, keyed by id (union-by-id, like