@cordfuse/crosstalk 5.0.0-alpha.2

package/src/send.ts

@@ -0,0 +1,80 @@
+import { resolve, join } from 'path';
+import { mkdirSync, writeFileSync } from 'fs';
+import { now, messageFilename } from './filenames.js';
+import { serializeFrontmatter } from './frontmatter.js';
+import { gitCommitAndPush, writeErrorLog } from './transport.js';
+import { withLock } from './turnq.js';
+
+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];
+}
+
+async function main(): Promise<void> {
+  const channelUuid = flag('--channel');
+  const to = flag('--to');
+  const from = flag('--from') ?? 'steve';
+  const tier = flag('--tier');
+  const body = argv[argv.length - 1];
+
+  if (!channelUuid || !to || !body || body.startsWith('--')) {
+    console.error(
+      'Usage: npx tsx runtime/src/send.ts --channel <uuid> --to <actor> [--from <actor>] [--tier <name>] "<message body>"',
+    );
+    process.exit(1);
+  }
+
+  await withLock('dispatch', async () => {
+    const ts = now();
+    const dir = join(transportRoot, 'data', 'channels', channelUuid, ts.pathDate);
+    mkdirSync(dir, { recursive: true });
+
+    const frontmatter: Record<string, unknown> = {
+      from,
+      to,
+      type: 'text',
+      timestamp: ts.iso,
+    };
+    if (tier) frontmatter.tier = tier;
+    const content = serializeFrontmatter(frontmatter, body);
+
+    const filename = messageFilename(ts);
+    writeFileSync(join(dir, filename), content);
+
+    const pushResult = gitCommitAndPush(
+      transportRoot,
+      `send: ${from} -> ${to} in ${channelUuid.slice(0, 8)}`,
+    );
+
+    // Poke dispatch to tick immediately (even if push failed — local cursor still advances).
+    try {
+      const wakeDir = join(transportRoot, '.turnq');
+      mkdirSync(wakeDir, { recursive: true });
+      writeFileSync(join(wakeDir, 'wake.signal'), `${Date.now()}\n`);
+    } catch {
+      /* wake is best-effort */
+    }
+
+    if (!pushResult.ok && pushResult.error) {
+      const kind = pushResult.committed ? 'git_push' : 'git_commit';
+      const errId = writeErrorLog(transportRoot, kind, pushResult.error);
+      console.error(`Wrote locally: ${join(ts.pathDate, filename)}`);
+      console.error(
+        `but git ${kind === 'git_push' ? 'push' : 'commit'} FAILED (errors/${errId}.md):`,
+      );
+      console.error(`  ${pushResult.error.slice(0, 200)}`);
+      console.error(
+        '  Message is in your local clone but not on origin. Resolve the git issue and re-push manually.',
+      );
+      process.exit(3);
+    }
+
+    console.log(`Sent: ${join(ts.pathDate, filename)}`);
+  });
+}
+
+main();

package/src/status.ts

@@ -0,0 +1,114 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { resolve, join } from 'path';
+import { findHostFile } from './actor.js';
+import { discoverChannels, countErrorEntries } from './transport.js';
+import { readCursor } from './cursor.js';
+import { parseFrontmatter } from './frontmatter.js';
+import type { DlqEntry } from './dlq.js';
+
+const transportRoot = resolve(process.cwd());
+
+console.log(`Crosstalk transport: ${transportRoot}`);
+console.log('');
+
+let actorNames: string[] = [];
+try {
+  const host = findHostFile(transportRoot);
+  console.log(`Host file: hosts/${host.alias}.md`);
+  actorNames = Object.keys(host.actors);
+  for (const a of actorNames) {
+    const tiers = Object.entries(host.actors[a]);
+    const tierDescs = tiers.map(([t, v]) => {
+      const count = typeof v === 'object' && v.count ? `x${v.count}` : '';
+      return `${t}${count}`;
+    });
+    console.log(`  ${a}: ${tierDescs.join(', ')}`);
+  }
+} catch (err) {
+  console.log(`Host file: ERROR — ${(err as Error).message}`);
+}
+
+console.log('');
+
+const lockPath = join(transportRoot, '.turnq', 'dispatch.lock');
+if (existsSync(lockPath)) {
+  try {
+    const meta = JSON.parse(readFileSync(lockPath, 'utf-8')) as { pid: number; acquired: string };
+    const ageS = Math.floor((Date.now() - new Date(meta.acquired).getTime()) / 1000);
+    console.log(`turnq lock: HELD by pid ${meta.pid} for ${ageS}s (since ${meta.acquired})`);
+  } catch {
+    console.log('turnq lock: HELD (unparseable metadata)');
+  }
+} else {
+  console.log('turnq lock: free');
+}
+
+const heartbeatPath = join(transportRoot, '.turnq', 'heartbeat');
+if (existsSync(heartbeatPath)) {
+  try {
+    const hb = JSON.parse(readFileSync(heartbeatPath, 'utf-8')) as { ts: string; pid: number; version?: string };
+    const ageS = Math.floor((Date.now() - new Date(hb.ts).getTime()) / 1000);
+    const fresh = ageS < 120;
+    const stale = ageS > 300;
+    const label = fresh ? 'LIVE' : stale ? 'STALE' : 'idle';
+    console.log(`dispatch heartbeat: ${label} (pid ${hb.pid}, last tick ${ageS}s ago${hb.version ? `, ${hb.version}` : ''})`);
+  } catch {
+    console.log('dispatch heartbeat: (unparseable)');
+  }
+} else {
+  console.log('dispatch heartbeat: never (no dispatch has run on this clone)');
+}
+
+console.log('');
+
+const channels = discoverChannels(transportRoot);
+console.log(`Channels: ${channels.length}`);
+for (const ch of channels) {
+  const channelDir = join(transportRoot, 'data', 'channels', ch);
+  let name = '(no CHANNEL.md)';
+  const chPath = join(channelDir, 'CHANNEL.md');
+  if (existsSync(chPath)) {
+    const m = readFileSync(chPath, 'utf-8').match(/^name:\s*(.+)$/m);
+    if (m) name = m[1].trim();
+  }
+  let msgCount = 0;
+  const walk = (d: string): void => {
+    for (const e of readdirSync(d)) {
+      const p = join(d, e);
+      if (statSync(p).isDirectory()) walk(p);
+      else if (e.endsWith('.md') && e !== 'CHANNEL.md') msgCount++;
+    }
+  };
+  try { walk(channelDir); } catch { /* ignore */ }
+  console.log(`  ${ch.slice(0, 8)}... — ${name} (${msgCount} msgs)`);
+
+  for (const actor of actorNames) {
+    const cursor = readCursor(transportRoot, actor, ch);
+    if (cursor) console.log(`    cursor[${actor}] → ${cursor}`);
+  }
+}
+
+console.log('');
+
+const dlqDir = join(transportRoot, 'dlq');
+let dlqTotal = 0;
+let dlqQuarantined = 0;
+let dlqDispatch = 0;
+let dlqConfig = 0;
+if (existsSync(dlqDir)) {
+  for (const f of readdirSync(dlqDir).filter((x) => x.endsWith('.md'))) {
+    try {
+      const { data } = parseFrontmatter<DlqEntry>(readFileSync(join(dlqDir, f), 'utf-8'));
+      dlqTotal++;
+      if (data.quarantined) dlqQuarantined++;
+      if (data.kind === 'dispatch') dlqDispatch++;
+      if (data.kind === 'config') dlqConfig++;
+    } catch { /* skip unparseable */ }
+  }
+}
+console.log(
+  `DLQ entries: ${dlqTotal} (${dlqDispatch} dispatch, ${dlqConfig} config, ${dlqQuarantined} quarantined)`,
+);
+
+const errorCount = countErrorEntries(transportRoot);
+console.log(`Infrastructure errors logged: ${errorCount}`);

package/src/transport.ts

@@ -0,0 +1,303 @@
+import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { spawnSync } from 'child_process';
+import { parseFrontmatter, serializeFrontmatter } from './frontmatter.js';
+import { now } from './filenames.js';
+
+export interface ChannelMessage {
+  relPath: string;
+  fullPath: string;
+  data: Record<string, unknown>;
+  body: string;
+}
+
+export interface GitResult {
+  ok: boolean;
+  error?: string;
+}
+
+export interface GitPushResult {
+  ok: boolean;
+  committed: boolean;
+  pushed: boolean;
+  error?: string;
+}
+
+function captureGit(cwd: string, args: string[]): { status: number; stdout: string; stderr: string } {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf-8' });
+  return { status: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+}
+
+// Detect and auto-recover from an interrupted rebase/merge in the working tree.
+// Returns true if recovery was performed (caller should treat as a non-fatal
+// infrastructure event). The error log surfaces the recovery in errors/.
+export function recoverInterruptedGit(transportRoot: string): boolean {
+  const halfStates: { dir: string; abortArgs: string[] }[] = [
+    { dir: '.git/rebase-merge', abortArgs: ['rebase', '--abort'] },
+    { dir: '.git/rebase-apply', abortArgs: ['rebase', '--abort'] },
+    { dir: '.git/MERGE_HEAD', abortArgs: ['merge', '--abort'] },
+    { dir: '.git/CHERRY_PICK_HEAD', abortArgs: ['cherry-pick', '--abort'] },
+  ];
+  for (const { dir, abortArgs } of halfStates) {
+    if (existsSync(join(transportRoot, dir))) {
+      const r = captureGit(transportRoot, abortArgs);
+      writeErrorLog(
+        transportRoot,
+        'git_pull',
+        `recovered from interrupted git state at ${dir} via 'git ${abortArgs.join(' ')}' (exit=${r.status})`,
+      );
+      return true;
+    }
+  }
+  return false;
+}
+
+export function gitPull(transportRoot: string): GitResult {
+  recoverInterruptedGit(transportRoot);
+  const r = captureGit(transportRoot, ['pull', '--rebase', '--quiet']);
+  if (r.status !== 0) {
+    return { ok: false, error: (r.stderr || r.stdout).trim().slice(0, 500) };
+  }
+  return { ok: true };
+}
+
+export function gitCommitAndPush(transportRoot: string, message: string): GitPushResult {
+  const status = captureGit(transportRoot, ['status', '--porcelain']);
+  if (status.status !== 0) {
+    return { ok: false, committed: false, pushed: false, error: status.stderr.trim().slice(0, 500) };
+  }
+  if (!status.stdout.trim()) {
+    return { ok: true, committed: false, pushed: false };
+  }
+
+  const add = captureGit(transportRoot, ['add', '-A']);
+  if (add.status !== 0) {
+    return { ok: false, committed: false, pushed: false, error: add.stderr.trim().slice(0, 500) };
+  }
+
+  const commit = captureGit(transportRoot, ['commit', '-m', message]);
+  if (commit.status !== 0) {
+    return { ok: false, committed: false, pushed: false, error: commit.stderr.trim().slice(0, 500) };
+  }
+
+  const push = captureGit(transportRoot, ['push', '--quiet']);
+  if (push.status !== 0) {
+    return {
+      ok: false,
+      committed: true,
+      pushed: false,
+      error: (push.stderr || push.stdout).trim().slice(0, 500),
+    };
+  }
+  return { ok: true, committed: true, pushed: true };
+}
+
+export function discoverChannels(transportRoot: string): string[] {
+  const channelsDir = join(transportRoot, 'data', 'channels');
+  if (!existsSync(channelsDir)) return [];
+  let entries: string[];
+  try {
+    entries = readdirSync(channelsDir);
+  } catch (err) {
+    writeErrorLog(
+      transportRoot,
+      'fs',
+      `discoverChannels readdir failed on ${channelsDir}: ${(err as Error).message}`,
+    );
+    return [];
+  }
+  return entries.filter((name) => {
+    const dir = join(channelsDir, name);
+    try {
+      return statSync(dir).isDirectory();
+    } catch (err) {
+      writeErrorLog(
+        transportRoot,
+        'fs',
+        `discoverChannels stat failed on ${dir}: ${(err as Error).message}`,
+      );
+      return false;
+    }
+  });
+}
+
+function isValidMessageFrontmatter(data: Record<string, unknown>): boolean {
+  // Required: from (string), to (string or string[]), type (string), timestamp (string)
+  if (typeof data.from !== 'string') return false;
+  if (typeof data.to !== 'string' && !Array.isArray(data.to)) return false;
+  if (typeof data.type !== 'string') return false;
+  if (typeof data.timestamp !== 'string') return false;
+  return true;
+}
+
+export function listChannelMessages(transportRoot: string, channelUuid: string): ChannelMessage[] {
+  const channelDir = join(transportRoot, 'data', 'channels', channelUuid);
+  if (!existsSync(channelDir)) return [];
+  const results: ChannelMessage[] = [];
+  const walk = (dir: string, prefix: string): void => {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      const rel = prefix ? `${prefix}/${entry}` : entry;
+      let stat;
+      try { stat = statSync(full); } catch { continue; }
+      if (stat.isDirectory()) {
+        walk(full, rel);
+      } else if (entry.endsWith('.md') && entry !== 'CHANNEL.md') {
+        const raw = readFileSync(full, 'utf-8');
+        let parsed;
+        try {
+          parsed = parseFrontmatter(raw);
+        } catch (err) {
+          writeErrorLog(
+            transportRoot,
+            'parse',
+            `frontmatter parse failed in ${channelUuid}/${rel}: ${(err as Error).message}`,
+          );
+          continue;
+        }
+        if (!isValidMessageFrontmatter(parsed.data)) {
+          writeErrorLog(
+            transportRoot,
+            'parse',
+            `invalid message frontmatter in ${channelUuid}/${rel}: missing required field(s) (from, to, type, timestamp)`,
+          );
+          continue;
+        }
+        results.push({ relPath: rel, fullPath: full, data: parsed.data, body: parsed.body });
+      }
+    }
+  };
+  walk(channelDir, '');
+  return results.sort((a, b) => a.relPath.localeCompare(b.relPath));
+}
+
+// ── errors/ log — infrastructure failures (git, fs, etc.) ──
+// Deduped by (kind + signature). If a matching entry exists, increment count
+// + update lastAt. Otherwise create a new entry.
+
+export type ErrorKind = 'git_pull' | 'git_push' | 'git_commit' | 'fs' | 'parse' | 'other';
+
+interface ErrorEntry {
+  id: string;
+  kind: ErrorKind;
+  signature: string;
+  count: number;
+  firstAt: string;
+  lastAt: string;
+  error: string;
+}
+
+function errorSignature(kind: ErrorKind, error: string): string {
+  const firstLine = error.split('\n')[0] ?? '';
+  return `${kind}::${firstLine.trim().slice(0, 120)}`;
+}
+
+export function writeErrorLog(transportRoot: string, kind: ErrorKind, error: string): string {
+  const dir = join(transportRoot, 'errors');
+  mkdirSync(dir, { recursive: true });
+  const sig = errorSignature(kind, error);
+
+  const files = existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith('.md')) : [];
+  for (const f of files) {
+    const path = join(dir, f);
+    try {
+      const { data } = parseFrontmatter<ErrorEntry>(readFileSync(path, 'utf-8'));
+      if (data.signature === sig) {
+        const updated: ErrorEntry = {
+          ...data,
+          count: (data.count ?? 1) + 1,
+          lastAt: new Date().toISOString(),
+          error: error.slice(0, 500),
+        };
+        writeFileSync(path, serializeFrontmatter(updated as unknown as Record<string, unknown>, error));
+        return data.id;
+      }
+    } catch { /* skip unparseable */ }
+  }
+
+  const ts = now();
+  const id = `${ts.fileTime}-${ts.hex}`;
+  const entry: ErrorEntry = {
+    id, kind, signature: sig,
+    count: 1,
+    firstAt: ts.iso, lastAt: ts.iso,
+    error: error.slice(0, 500),
+  };
+  writeFileSync(
+    join(dir, `${id}.md`),
+    serializeFrontmatter(entry as unknown as Record<string, unknown>, error),
+  );
+  return id;
+}
+
+export function countErrorEntries(transportRoot: string): number {
+  const dir = join(transportRoot, 'errors');
+  if (!existsSync(dir)) return 0;
+  return readdirSync(dir).filter((f) => f.endsWith('.md')).length;
+}
+
+// Sweep channels for read receipts older than `thresholdMs` that lack a
+// corresponding `type: text` reply from the same actor referencing the same
+// original message. Each stale receipt is logged once to errors/ kind=parse
+// (we reuse 'parse' rather than introduce another kind for one weak signal).
+// Returns the number of stale receipts surfaced.
+export function sweepStaleReadReceipts(
+  transportRoot: string,
+  thresholdMs: number,
+): number {
+  const channelsDir = join(transportRoot, 'data', 'channels');
+  if (!existsSync(channelsDir)) return 0;
+  let channels: string[];
+  try {
+    channels = readdirSync(channelsDir).filter((name) => {
+      try { return statSync(join(channelsDir, name)).isDirectory(); }
+      catch { return false; }
+    });
+  } catch { return 0; }
+
+  const now = Date.now();
+  let surfaced = 0;
+
+  for (const channelUuid of channels) {
+    const messages = listChannelMessages(transportRoot, channelUuid);
+
+    // Build: for each (fromActor, refRelPath), did a text reply follow the read receipt?
+    const readReceipts: { actor: string; ref: string; ts: number; relPath: string }[] = [];
+    const replyKeys = new Set<string>();
+
+    for (const msg of messages) {
+      const from = typeof msg.data['from'] === 'string' ? msg.data['from'] : null;
+      const type = typeof msg.data['type'] === 'string' ? msg.data['type'] : null;
+      const timestamp = typeof msg.data['timestamp'] === 'string' ? msg.data['timestamp'] : null;
+      const ref = typeof msg.data['ref'] === 'string' ? msg.data['ref'] : null;
+      if (!from || !type || !timestamp) continue;
+
+      if (type === 'read' && ref) {
+        readReceipts.push({
+          actor: from,
+          ref,
+          ts: new Date(timestamp).getTime(),
+          relPath: msg.relPath,
+        });
+      } else if (type === 'text') {
+        // A text reply doesn't carry a ref field. We approximate "did this
+        // actor reply after the read receipt" by keying on actor only; if
+        // any later text exists from the same actor in this channel, treat
+        // earlier read receipts as resolved. Imperfect but cheap.
+        replyKeys.add(from);
+      }
+    }
+
+    for (const rr of readReceipts) {
+      if (replyKeys.has(rr.actor)) continue;
+      if (now - rr.ts <= thresholdMs) continue;
+      writeErrorLog(
+        transportRoot,
+        'parse',
+        `stale read receipt ${channelUuid}/${rr.relPath}: actor=${rr.actor} claimed ref=${rr.ref} ${Math.floor((now - rr.ts) / 60000)}min ago, no reply yet`,
+      );
+      surfaced++;
+    }
+  }
+  return surfaced;
+}

package/src/turnq.ts

@@ -0,0 +1,59 @@
+// Thin wrapper around @cordfuse/turnq's coordinator.
+//
+// Two modes, picked automatically by the underlying coordinator:
+//
+//   Local (default, no env vars set): file lock via flock(2). Safe across
+//   multiple processes on the same host; the OS releases the lock if the
+//   process dies, so stale locks are impossible.
+//
+//   Distributed (env var TURNQ_URL set): HTTP coordinator running on a
+//   reachable turnq server. Serializes turns across multiple hosts. If
+//   the server is unreachable, falls back to local silently (default
+//   `fallback: true`).
+//
+// Env vars:
+//   TURNQ_URL      — optional, e.g. http://turnq:3003 (unset → local mode)
+//   TURNQ_API_KEY  — required when TURNQ_URL is set
+//   TURNQ_CHANNEL  — optional namespace prefix (default: "crosstalk").
+//                    Concatenated with the lock name to form the actual
+//                    channel — e.g. "crosstalk/dispatch". Lets multiple
+//                    transports share the same turnq server without
+//                    colliding.
+
+import { createCoordinator } from '@cordfuse/turnq/coordinator';
+
+interface Coordinator {
+  withTurn<T>(channel: string, fn: () => Promise<T>): Promise<T>;
+  close(): void;
+}
+
+let coordinatorPromise: Promise<Coordinator> | null = null;
+
+function getCoordinator(): Promise<Coordinator> {
+  if (!coordinatorPromise) {
+    const url = process.env.TURNQ_URL;
+    const apiKey = process.env.TURNQ_API_KEY;
+    coordinatorPromise = createCoordinator(
+      url ? { url, apiKey, fallback: true } : {},
+    );
+  }
+  return coordinatorPromise;
+}
+
+function channelFor(name: string): string {
+  const prefix = process.env.TURNQ_CHANNEL ?? 'crosstalk';
+  return `${prefix}/${name}`;
+}
+
+/**
+ * Run `fn` while holding the turn for the named lock. Queues if another
+ * caller holds it; runs in FIFO order. The lock auto-releases when `fn`
+ * resolves or rejects.
+ *
+ * In local mode this is a flock(2) on a temp file. In distributed mode
+ * it's an HTTP turn on a cordfuse/turnq server.
+ */
+export async function withLock<T>(name: string, fn: () => Promise<T>): Promise<T> {
+  const coordinator = await getCoordinator();
+  return coordinator.withTurn(channelFor(name), fn);
+}