@cordfuse/crosstalk 7.0.0-alpha.9 → 7.0.0-beta.1

package/src/dispatch.ts

@@ -0,0 +1,492 @@
+// crosstalk daemon dispatch — the engine main loop.
+//
+// Tick: pull → scan channels for messages past the global cursor → for each
+// addressed message that wakes a claimed model, invoke the model CLI →
+// write reply (success body or failed:true + error) → commit + push.
+//
+// v7 changes vs v6 dispatch:
+//  - No host file. Machine identity is the --alias flag; claimed models
+//    come from data/crosstalk.yaml + PATH self-selection (models.ts).
+//  - Single global cursor (state.ts), not per-actor-per-channel.
+//  - No DLQ. Failures land in the channel as normal messages with
+//    failed:true + error: in frontmatter — wake-loud.
+//  - No turnq. Git rebase-retry is the correctness mechanism; turnq was
+//    a churn-reducer that didn't earn its weight.
+//  - No host-file commit / waterline logic. Cursors seed to HEAD on first
+//    boot; pre-join history is ignored (same effect as v6 waterline).
+
+import { resolve, join, dirname } from 'path';
+import { readFileSync, existsSync, appendFileSync } from 'fs';
+import { watch } from 'fs/promises';
+import { fileURLToPath } from 'url';
+
+import { loadRegistry, type ModelEntry, type ModelsRegistry } from './models.js';
+import {
+  discoverChannels,
+  listChannelMessages,
+  gitPull,
+  gitCommitAndPush,
+  cursorBaseline,
+  newFilesSince,
+  type ChannelMessage,
+} from './transport.js';
+import {
+  stateDir,
+  readCursor,
+  writeCursor,
+  writeHeartbeat,
+  writePidfile,
+  removePidfile,
+  logError,
+} from './state.js';
+import {
+  recipients,
+  reList,
+  extractActor,
+  decideWake,
+} from './activation.js';
+import {
+  loadProtocolPrompt,
+  loadActorPersona,
+  composeSystemPrompt,
+  invokeModelCli,
+  formatBatchedUserMessage,
+  messageSender,
+  writeReply,
+} from './invoke.js';
+import { workflowTick } from './workflow.js';
+import { writeRegistryEntry, removeRegistryEntry } from './dispatchers.js';
+import { startApi } from './api.js';
+import { logBuffer } from './log-buffer.js';
+import { FileUserStore } from './auth/users.js';
+import { FileTokenStore } from './auth/tokens.js';
+import { SetupState } from './auth/setup.js';
+import type { Server as HttpServer } from 'http';
+
+const RUNTIME_VERSION: string = (() => {
+  try {
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+    return (JSON.parse(readFileSync(pkgPath, 'utf-8')) as { version?: string }).version ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+})();
+
+const transportRoot = resolve(process.cwd());
+const argv = process.argv.slice(2);
+
+function flag(name: string): string | undefined {
+  const i = argv.indexOf(name);
+  if (i === -1 || i === argv.length - 1) return undefined;
+  return argv[i + 1];
+}
+
+const alias = flag('--alias');
+const onceMode = argv.includes('--once');
+const jsonMode = argv.includes('--json');
+const pollSeconds = Number(flag('--poll')) || 30;
+const logFile = flag('--log-file');
+
+if (!alias) {
+  console.error('crosstalk daemon dispatch: --alias <name> is required (machine identity in the bus).');
+  process.exit(1);
+}
+
+function log(event: string, fields: Record<string, unknown> = {}): void {
+  let line: string;
+  if (jsonMode) {
+    line = JSON.stringify({ ts: new Date().toISOString(), event, ...fields });
+  } else {
+    const tail = Object.entries(fields)
+      .map(([k, v]) => `${k}=${typeof v === 'string' ? v : JSON.stringify(v)}`)
+      .join(' ');
+    line = `[${new Date().toISOString()}] ${event}${tail ? ' ' + tail : ''}`;
+  }
+  console.log(line);
+  if (logFile) {
+    try { appendFileSync(logFile, line + '\n'); } catch { /* best-effort */ }
+  }
+  // Tee into the in-memory ring buffer so the /logs web page + the
+  // /api/logs/stream SSE endpoint can serve a live tail without
+  // re-parsing stdout from another process.
+  logBuffer.push(event, fields);
+}
+
+// One pending dispatch = one message → one CLI invocation → one reply.
+// v6 grouped by (channel, model) into batches; v7 doesn't (see V7-SPEC
+// post-M2 fanout note). Each fanout sibling, each operator-piled-up
+// request, each fan-in reply gets its own invocation in parallel — N
+// model calls, N replies, fanout works as designed.
+interface PendingDispatch {
+  channelUuid: string;
+  modelName: string;
+  model: ModelEntry;
+  msg: ChannelMessage;
+  // Persona resolved by dispatchTick: prefers msg.as, falls back to the
+  // re:'d message's wake_as (workflow persona continuity).
+  invokeAs?: string;
+}
+
+async function dispatchOne(d: PendingDispatch, protocolPrompt: string): Promise<boolean> {
+  const childChannel = typeof d.msg.data['child_channel'] === 'string'
+    ? (d.msg.data['child_channel'] as string)
+    : undefined;
+  const actorName = d.invokeAs;
+  const persona = loadActorPersona(transportRoot, actorName);
+  const systemPrompt = composeSystemPrompt([protocolPrompt, persona]);
+  const fromIdentity = `${d.modelName}@${alias}`;
+  const sender = messageSender(d.msg);
+
+  log('dispatch', {
+    model: d.modelName,
+    alias,
+    channel: d.channelUuid.slice(0, 8),
+    actor: actorName ?? null,
+    child_channel: childChannel ? childChannel.slice(0, 8) : null,
+    msg: d.msg.relPath,
+  });
+
+  const env: Record<string, string> = {
+    CROSSTALK_DISPATCH_ACTOR: fromIdentity,
+    CROSSTALK_DISPATCH_CHANNEL: d.channelUuid,
+    CROSSTALK_DISPATCH_RE: d.msg.relPath,
+  };
+  if (childChannel) env['CROSSTALK_CHILD_CHANNEL'] = childChannel;
+
+  const result = await invokeModelCli(d.model, systemPrompt, d.msg.body, env);
+
+  if (result.status !== 0) {
+    // Some CLIs (claude --print, codex exec, others) write auth/config
+    // errors to stdout, not stderr. Surface both so failures aren't a
+    // black box when only one stream has the message.
+    const errBody = result.stderr.trim() || result.stdout.trim() || '(no output captured)';
+    const errDetail = [
+      `model exit=${result.status}`,
+      result.stderr.trim() ? `stderr:\n${result.stderr.slice(0, 1000)}` : '',
+      result.stdout.trim() ? `stdout:\n${result.stdout.slice(0, 1000)}` : '',
+    ].filter(Boolean).join('\n');
+    writeReply({
+      transportRoot,
+      channelUuid: d.channelUuid,
+      fromModel: fromIdentity,
+      to: sender === 'unknown' ? messageSender(d.msg) : sender,
+      re: d.msg.relPath,
+      body: errBody.slice(0, 4000),
+      failed: { error: errDetail },
+    });
+    log('dispatch_failed', {
+      model: d.modelName,
+      channel: d.channelUuid.slice(0, 8),
+      msg: d.msg.relPath,
+      exit: result.status,
+    });
+    return true;
+  }
+
+  const reply = result.stdout.trim();
+  if (reply.length === 0) {
+    // Actor routed its answer via `crosstalk message send` (which auto-links re:).
+    // If it truly did nothing, the asker's `crosstalk message replies` stays
+    // PENDING — visible, never silently lost.
+    log('dispatch_silent', { model: d.modelName, channel: d.channelUuid.slice(0, 8), msg: d.msg.relPath });
+    return true;
+  }
+
+  writeReply({
+    transportRoot,
+    channelUuid: d.channelUuid,
+    fromModel: fromIdentity,
+    to: sender,
+    re: d.msg.relPath,
+    body: reply,
+  });
+  log('dispatch_done', { model: d.modelName, channel: d.channelUuid.slice(0, 8), msg: d.msg.relPath });
+  return true;
+}
+
+async function dispatchTick(registry: ModelsRegistry, protocolPrompt: string): Promise<boolean> {
+  const claimed = registry.claimed;
+  writeHeartbeat(transportRoot, RUNTIME_VERSION, alias!);
+
+  const pullResult = gitPull(transportRoot);
+  if (!pullResult.ok) {
+    logError(transportRoot, `git pull failed: ${pullResult.error}`, 'warn');
+    log('git_pull_failed', { error: (pullResult.error ?? '').slice(0, 200) });
+    return false;
+  }
+
+  const head = cursorBaseline(transportRoot);
+  if (!head) {
+    logError(transportRoot, 'git rev-parse failed for origin/HEAD and HEAD — skipping tick');
+    return false;
+  }
+
+  let cursor = readCursor(transportRoot);
+  if (cursor === null) {
+    // First-boot seed to HEAD: pre-join history is ignored. Operators
+    // sending messages BEFORE this dispatcher first booted are not
+    // delivered — ephemeral-alias semantics: an alias only exists from
+    // its first boot onward (no committed per-host "join" marker).
+    writeCursor(transportRoot, head);
+    cursor = head;
+    log('cursor_seeded', { commit: head.slice(0, 12) });
+  }
+  const channels = discoverChannels(transportRoot);
+  const activationDue = cursor !== head;
+
+  let didWork = false;
+  if (activationDue) {
+    didWork = await runActivationPass(claimed, protocolPrompt, channels, cursor, head);
+  }
+
+  // Workflow tick runs unconditionally — an open workflow may need to
+  // advance (e.g. compile a freshly-committed marker, or progress to the
+  // synthesize phase now that all fanout replies have landed) regardless
+  // of whether the activation pass had new messages this tick.
+  const workflowProgressed = await workflowTick({ transportRoot, alias: alias!, registry, claimed, log }, channels);
+
+  // Advance cursor regardless of per-batch success: at-least-once was
+  // attempted; failure replies are committed alongside successes. A
+  // crash mid-tick leaves the cursor where it was — next tick replays.
+  writeCursor(transportRoot, head);
+
+  const writeNeeded = didWork || workflowProgressed;
+  if (writeNeeded) {
+    const push = gitCommitAndPush(transportRoot, `dispatch(${alias}): replies ${new Date().toISOString()}`);
+    if (!push.ok && push.error) {
+      // Commit failed is a real error (local state out of sync); push
+      // failed with the commit landing is a warning (push will retry).
+      logError(transportRoot, `${push.committed ? 'push' : 'commit'} failed: ${push.error}`, push.committed ? 'warn' : 'error');
+      log('git_push_failed', { committed: push.committed, error: push.error.slice(0, 200) });
+    }
+  }
+
+  return writeNeeded;
+}
+
+async function runActivationPass(
+  claimed: Map<string, ModelEntry>,
+  protocolPrompt: string,
+  channels: string[],
+  cursor: string,
+  head: string,
+): Promise<boolean> {
+  const addedList = newFilesSince(transportRoot, cursor);
+  if (addedList === null) {
+    logError(transportRoot, `cursor ${cursor.slice(0, 12)} unknown — re-scanning all channels`, 'warn');
+  }
+  const added: Set<string> | null = addedList === null ? null : new Set(addedList);
+
+  void head;  // head is the diff's upper bound implicitly (newFilesSince uses HEAD).
+  const pending: PendingDispatch[] = [];
+
+  for (const channelUuid of channels) {
+    const messages = listChannelMessages(transportRoot, channelUuid);
+    const senderByRelPath = new Map(messages.map((m) => [m.relPath, messageSender(m)]));
+    // Normalize asker identity the same way self-suppression does: strip
+    // the @machine suffix before comparing against actorName. Without
+    // this, an actor that sent a sub-message never wakes for its reply,
+    // because asker='alice@cachy' never matches actorName='alice'. The
+    // bug was masked by the workflow smoke test, which used direct
+    // stdout replies — fan-out + fan-in is the case that surfaces it.
+    const senderOf = (relPath: string) => {
+      const raw = senderByRelPath.get(relPath);
+      return raw === undefined ? undefined : extractActor(raw);
+    };
+
+    let post: ChannelMessage[];
+    if (added === null) {
+      post = messages;
+    } else {
+      const prefix = `data/channels/${channelUuid}/`;
+      post = messages.filter((m) => added.has(prefix + m.relPath));
+    }
+
+    for (const msg of post) {
+      const recipientList = recipients(msg.data['to']);
+      for (const [modelName, model] of claimed) {
+        const decision = decideWake(
+          {
+            from: extractActor(messageSender(msg)),   // self-suppression: model name, not model@alias
+            to: recipientList,
+            re: reList(msg.data['re']),
+          },
+          modelName,
+          alias!,
+          senderOf,
+        );
+        if (decision === 'wake') {
+          const invokeAs: string | undefined = typeof msg.data['as'] === 'string'
+            ? (msg.data['as'] as string)
+            : undefined;
+          pending.push({ channelUuid, modelName, model, msg, invokeAs });
+        }
+      }
+    }
+  }
+
+  // Fire all pending dispatches in parallel. Each is one model CLI call,
+  // captured by detached spawn with SIGKILL timeout (invoke.ts). N parallel
+  // claude/gemini/etc. invocations comfortably saturate one machine; if it
+  // ever becomes a problem, dispatch.ts can grow a per-model concurrency
+  // semaphore — for now KISS wins, every message gets its own dispatch.
+  const results = pending.length === 0
+    ? []
+    : await Promise.all(pending.map((d) => dispatchOne(d, protocolPrompt)));
+  return results.some(Boolean);
+}
+
+async function waitForWakeOrTimeout(ms: number): Promise<void> {
+  const dir = stateDir(transportRoot);
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), ms);
+  try {
+    const watcher = watch(dir, { signal: ac.signal });
+    for await (const ev of watcher) {
+      if (ev.filename === 'wake.signal') return;
+    }
+  } catch {
+    /* abort = timeout */
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function main(): Promise<void> {
+  writePidfile(transportRoot);
+  // Regular exit: drop the pidfile only. Do NOT drop the registry entry —
+  // (a) `--once` mode exits cleanly every tick and would churn the file
+  // between tick runs, and (b) an uncommitted local delete breaks the
+  // next `git pull --rebase` until something else commits. Registry
+  // entries should live until explicit shutdown.
+  process.on('exit', () => removePidfile(transportRoot));
+  // Explicit shutdown signals: remove pidfile + registry entry, commit
+  // the deregistration so other machines stop routing to us. Hard crash
+  // skips this and leaves a stale entry — operator-cleanup concern,
+  // not runtime correctness.
+  let apiServer: HttpServer | null = null;
+  const cleanupShutdown = () => {
+    if (apiServer) {
+      try { apiServer.close(); } catch { /* best-effort */ }
+    }
+    removePidfile(transportRoot);
+    if (alias) removeRegistryEntry(transportRoot, alias);
+    const push = gitCommitAndPush(transportRoot, `dispatch(${alias}): deregister entry`);
+    if (!push.ok && push.error) {
+      logError(transportRoot, `registry deregister failed: ${push.error}`, 'warn');
+    }
+  };
+  process.on('SIGTERM', () => { cleanupShutdown(); process.exit(0); });
+  process.on('SIGINT',  () => { cleanupShutdown(); process.exit(0); });
+
+  // Load the model registry. On parse failure (operator-edited
+  // crosstalk.yaml broken mid-flight, missing file, malformed YAML),
+  // log the error and continue with an empty claimed set rather than
+  // exiting. The container's restart: unless-stopped would otherwise
+  // crash-loop forever; this way the engine stays up, the API keeps
+  // serving /status, and the operator can `crosstalk status` to see
+  // the diagnostic without needing `crosstalk logs`.
+  //
+  // Note: alpha.11 made the parser skip-bad-provider — a single typo'd
+  // provider no longer throws; it logs a warning and the rest of the
+  // registry loads. This whole-registry catch now fires only on truly
+  // unrecoverable errors (missing file, top-level shape broken, etc.).
+  let registry: ReturnType<typeof loadRegistry>;
+  try {
+    registry = loadRegistry(transportRoot);
+  } catch (err) {
+    const msg = (err as Error).message;
+    logError(transportRoot, `crosstalk.yaml load failed — running with empty claimed set: ${msg}`);
+    console.error(`crosstalk daemon dispatch: ${msg}`);
+    console.error(`crosstalk daemon dispatch: continuing with EMPTY claimed-model set. Fix data/crosstalk.yaml, then 'crosstalk server restart' to reload.`);
+    registry = {
+      all: new Map(),
+      byBareName: new Map(),
+      claimed: new Map(),
+    };
+  }
+
+  const protocolPrompt = loadProtocolPrompt(transportRoot);
+
+  // Publish our registry entry so workflow.ts (running on this or any
+  // other machine) can scope fanout sub-primitives to specific dispatchers
+  // instead of broadcasting bare-recipient fanouts that every claimant
+  // races to duplicate. Commit+push immediately so cross-machine
+  // visibility doesn't wait for first reply traffic.
+  writeRegistryEntry(transportRoot, alias!, [...registry.claimed.keys()], RUNTIME_VERSION);
+  const registryPush = gitCommitAndPush(transportRoot, `dispatch(${alias}): register entry`);
+  if (!registryPush.ok && registryPush.error) {
+    logError(transportRoot, `registry publish failed: ${registryPush.error}`, 'warn');
+  }
+
+  log('dispatch_start', {
+    transport: transportRoot,
+    alias,
+    version: RUNTIME_VERSION,
+    state_dir: stateDir(transportRoot),
+    claimed_models: [...registry.claimed.keys()],
+    total_models: registry.all.size,
+  });
+
+  // Start the HTTP API on 127.0.0.1 so the host-side `crosstalk` client
+  // can talk to us. --once mode skips this — short-lived processes don't
+  // serve, and the test harnesses that invoke --once would conflict on
+  // the port. Operators get the API when running the continuous loop.
+  if (!onceMode) {
+    // v8 auth stores — gate the web UI behind a passphrase. JSON API
+    // stays open on loopback (matches v7 trust model).
+    // Storage lives under the transport state dir so it travels with
+    // the transport but stays out of the git repo (it's not committed).
+    const authDir = join(transportRoot, '..', 'crosstalk-state', 'auth');
+    const userStore = new FileUserStore(join(authDir, 'users.json'));
+    const tokenStore = new FileTokenStore(join(authDir, 'tokens.json'));
+    const setupState = new SetupState(join(authDir, 'setup-token'));
+    // First-run: mint setup token + log the URL so the operator can
+    // bootstrap from the browser. Subsequent boots: leave the
+    // existing token if present (operator may have stalled mid-setup).
+    if (await userStore.isEmpty() && !setupState.hasActiveToken) {
+      const rec = setupState.mint();
+      log('auth_first_run_setup_token', {
+        url: `http://127.0.0.1:<port>/setup?token=${rec.token}`,
+        note: 'Visit this URL in a browser to create the admin account. Replace <port> with the bound API port.',
+      });
+    }
+    apiServer = startApi(
+      {
+        transportRoot,
+        alias: alias!,
+        version: RUNTIME_VERSION,
+        registry,
+        claimed: registry.claimed,
+        userStore,
+        tokenStore,
+        setupState,
+      },
+      { log },
+    );
+  }
+
+  if (onceMode) {
+    await dispatchTick(registry, protocolPrompt);
+    process.exit(0);
+  }
+  log('dispatch_running', { poll_s: pollSeconds });
+
+  while (true) {
+    try {
+      const didWork = await dispatchTick(registry, protocolPrompt);
+      if (didWork) {
+        await new Promise((res) => setTimeout(res, 1_000));
+      } else {
+        await waitForWakeOrTimeout(pollSeconds * 1_000);
+      }
+    } catch (err) {
+      const msg = (err as Error).message;
+      logError(transportRoot, `tick error: ${msg}`);
+      log('tick_error', { message: msg });
+      await new Promise((res) => setTimeout(res, pollSeconds * 1_000));
+    }
+  }
+}
+
+main();

package/src/dispatchers.ts

@@ -0,0 +1,91 @@
+// dispatchers.ts — the shared dispatcher registry.
+//
+// Each running dispatcher publishes its identity + claimed models to
+// `data/dispatchers/<alias>.yaml` so workflow.ts can scope fanout
+// sub-primitives across the actually-running dispatcher set instead of
+// addressing every fanout to bare `<model>` and watching every claimant
+// race for it.
+//
+// Lifecycle:
+//   - dispatcher startup → writeRegistryEntry (committed alongside other
+//     state changes by the next tick's gitCommitAndPush)
+//   - dispatcher SIGTERM/SIGINT → removeRegistryEntry (committed same way)
+//   - hard crash → entry stays; operator runs cleanup, or restarts
+//
+// Liveness is best-effort. v7.0.0-alpha.1 does NOT track per-tick
+// heartbeats in the registry — the timestamp would force a commit every
+// tick on every machine, which is far more push traffic than the system
+// otherwise generates. Heartbeats live in the machine-local state dir
+// (state.ts) for "is THIS dispatcher alive" checks; the registry answers
+// "which dispatchers exist on the bus." A stale registry entry from a
+// crashed dispatcher is an operator-cleanup concern, not a runtime concern.
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+
+export interface RegistryEntry {
+  alias: string;
+  claims: string[];        // model names this dispatcher has on PATH
+  version: string;
+}
+
+export function registryDir(transportRoot: string): string {
+  return join(transportRoot, 'data', 'dispatchers');
+}
+
+export function registryFile(transportRoot: string, alias: string): string {
+  return join(registryDir(transportRoot), `${alias}.yaml`);
+}
+
+export function writeRegistryEntry(
+  transportRoot: string,
+  alias: string,
+  claims: string[],
+  version: string,
+): void {
+  mkdirSync(registryDir(transportRoot), { recursive: true });
+  const entry: RegistryEntry = { alias, claims, version };
+  writeFileSync(registryFile(transportRoot, alias), stringifyYaml(entry));
+}
+
+export function removeRegistryEntry(transportRoot: string, alias: string): void {
+  try {
+    unlinkSync(registryFile(transportRoot, alias));
+  } catch { /* already gone */ }
+}
+
+export function readAllRegistry(transportRoot: string): RegistryEntry[] {
+  const dir = registryDir(transportRoot);
+  if (!existsSync(dir)) return [];
+  const out: RegistryEntry[] = [];
+  for (const entry of readdirSync(dir)) {
+    if (!entry.endsWith('.yaml')) continue;
+    try {
+      const raw = readFileSync(join(dir, entry), 'utf-8');
+      const parsed = parseYaml(raw) as Partial<RegistryEntry> | null;
+      if (
+        !parsed ||
+        typeof parsed.alias !== 'string' ||
+        !Array.isArray(parsed.claims) ||
+        typeof parsed.version !== 'string'
+      ) continue;
+      out.push({
+        alias: parsed.alias,
+        claims: parsed.claims.map(String),
+        version: parsed.version,
+      });
+    } catch { /* skip malformed */ }
+  }
+  return out;
+}
+
+// Aliases of dispatchers currently claiming the given model, sorted for
+// deterministic ordering — round-robin assignment becomes reproducible,
+// which makes the test path predictable.
+export function dispatchersForModel(transportRoot: string, modelName: string): string[] {
+  return readAllRegistry(transportRoot)
+    .filter((e) => e.claims.includes(modelName))
+    .map((e) => e.alias)
+    .sort();
+}

package/src/filenames.ts

@@ -0,0 +1,28 @@
+import { randomBytes } from 'crypto';
+
+export interface Timestamp {
+  iso: string;
+  pathDate: string;
+  fileTime: string;
+  hex: string;
+}
+
+export function now(): Timestamp {
+  const d = new Date();
+  const iso = d.toISOString();
+  const yyyy = iso.slice(0, 4);
+  const mm = iso.slice(5, 7);
+  const dd = iso.slice(8, 10);
+  const time = iso.slice(11, 13) + iso.slice(14, 16) + iso.slice(17, 19);
+  const ms = iso.slice(20, 23);
+  return {
+    iso,
+    pathDate: `${yyyy}/${mm}/${dd}`,
+    fileTime: `${time}${ms}Z`,
+    hex: randomBytes(4).toString('hex'),
+  };
+}
+
+export function messageFilename(ts: Timestamp = now()): string {
+  return `${ts.fileTime}-${ts.hex}.md`;
+}

package/src/frontmatter.ts

@@ -0,0 +1,26 @@
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+
+export interface ParsedDocument<T = Record<string, unknown>> {
+  data: T;
+  body: string;
+}
+
+export function parseFrontmatter<T = Record<string, unknown>>(raw: string): ParsedDocument<T> {
+  if (!raw.startsWith('---')) return { data: {} as T, body: raw };
+  const lines = raw.split('\n');
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') { end = i; break; }
+  }
+  if (end === -1) return { data: {} as T, body: raw };
+  const yamlBlock = lines.slice(1, end).join('\n');
+  const body = lines.slice(end + 1).join('\n').replace(/^\n/, '');
+  const data = (parseYaml(yamlBlock) as T) ?? ({} as T);
+  return { data, body };
+}
+
+export function serializeFrontmatter(data: Record<string, unknown>, body: string): string {
+  const yaml = stringifyYaml(data).trimEnd();
+  const trailing = body.endsWith('\n') ? '' : '\n';
+  return `---\n${yaml}\n---\n\n${body}${trailing}`;
+}