@cordfuse/crosstalk 5.0.0-alpha.2

package/src/upgrade.ts

@@ -0,0 +1,213 @@
+// crosstalk upgrade — sync the transport's upstream/ against the runtime's
+// bundled template.
+//
+// The transport's upstream/ contains runtime-managed files: spec, agent
+// orientation prompts, protocol version pin, default actor profiles. When
+// the operator updates their runtime (via `npm update -g @cordfuse/crosstalk`),
+// the bundled template ships with a newer spec; this command copies those
+// files into the operator's transport so they catch up.
+//
+// What this command DOES touch:
+//   - upstream/CROSSTALK.md, PROTOCOL.md, OPERATOR.md, JITTER.md
+//   - upstream/CROSSTALK-VERSION
+//   - upstream/actors/ (default actor profile starter set)
+//
+// What this command NEVER touches:
+//   - local/ — operator-owned actor profiles and identity
+//   - hosts/ — operator-owned host file
+//   - data/ — channels and memories
+//   - cursors/, dlq/, errors/ — dispatcher-owned runtime state
+//   - root pointer files (CLAUDE.md etc.) — only updated if a --pointers flag
+//     is passed, since they rarely change and overwriting them surprises
+//     operators who've customized them
+//
+// Usage:
+//   crosstalk upgrade           — sync upstream/ from runtime template
+//   crosstalk upgrade --dry-run — show what would change, no writes
+//   crosstalk upgrade --pointers — also overwrite the 11 entry pointer files
+
+import { existsSync, readFileSync, writeFileSync, cpSync, statSync, readdirSync } from 'fs';
+import { resolve, join, dirname, relative } from 'path';
+import { fileURLToPath } from 'url';
+
+const transportRoot = resolve(process.cwd());
+const argv = process.argv.slice(2);
+const dryRun = argv.includes('--dry-run');
+const updatePointers = argv.includes('--pointers');
+
+const POINTER_FILES = [
+  'CLAUDE.md', 'AGENTS.md', 'GEMINI.md', 'QWEN.md', 'ANTIGRAVITY.md', 'OPENCODE.md',
+  '.windsurfrules',
+  '.amazonq/rules/crosstalk.md',
+  '.continue/rules/crosstalk.md',
+  '.cursor/rules/crosstalk.mdc',
+  '.github/copilot-instructions.md',
+];
+
+function locateTemplate(): string {
+  const thisFileDir = dirname(fileURLToPath(import.meta.url));
+  const runtimeRoot = resolve(thisFileDir, '..');
+  const candidates = [
+    join(runtimeRoot, 'template'),
+    join(runtimeRoot, '..', 'transport'),
+  ];
+  const found = candidates.find((c) => existsSync(join(c, 'upstream', 'CROSSTALK-VERSION')));
+  if (!found) {
+    console.error('crosstalk upgrade: cannot find the bundled transport template.');
+    console.error('Looked in:');
+    for (const c of candidates) console.error(`  ${c}`);
+    process.exit(1);
+  }
+  return found;
+}
+
+function readVersion(p: string): string | null {
+  try { return readFileSync(p, 'utf-8').trim(); } catch { return null; }
+}
+
+function listFilesRelative(dir: string): string[] {
+  const out: string[] = [];
+  const walk = (d: string, prefix: string): void => {
+    if (!existsSync(d)) return;
+    for (const entry of readdirSync(d)) {
+      const full = join(d, entry);
+      const rel = prefix ? `${prefix}/${entry}` : entry;
+      const st = statSync(full);
+      if (st.isDirectory()) walk(full, rel);
+      else out.push(rel);
+    }
+  };
+  walk(dir, '');
+  return out;
+}
+
+function classifyChange(templatePath: string, transportPath: string): 'add' | 'modify' | 'unchanged' {
+  if (!existsSync(transportPath)) return 'add';
+  const a = readFileSync(templatePath, 'utf-8');
+  const b = readFileSync(transportPath, 'utf-8');
+  return a === b ? 'unchanged' : 'modify';
+}
+
+// ── Sanity checks ─────────────────────────────────────────────────────
+
+const transportVersionPath = join(transportRoot, 'upstream', 'CROSSTALK-VERSION');
+if (!existsSync(transportVersionPath)) {
+  console.error(`crosstalk upgrade: not a transport (no upstream/CROSSTALK-VERSION).`);
+  console.error(`Run from inside a transport directory, or use 'crosstalk init' to scaffold one.`);
+  process.exit(2);
+}
+
+const templateDir = locateTemplate();
+const templateUpstream = join(templateDir, 'upstream');
+const transportUpstream = join(transportRoot, 'upstream');
+
+const fromVersion = readVersion(transportVersionPath) ?? '?';
+const toVersion = readVersion(join(templateUpstream, 'CROSSTALK-VERSION')) ?? '?';
+
+// Detect downgrade.
+const parseMM = (v: string): [number, number] => {
+  const m = v.match(/^(\d+)\.(\d+)/);
+  return m ? [Number(m[1]), Number(m[2])] : [0, 0];
+};
+const [fromMaj, fromMin] = parseMM(fromVersion);
+const [toMaj, toMin] = parseMM(toVersion);
+const isDowngrade = toMaj < fromMaj || (toMaj === fromMaj && toMin < fromMin);
+if (isDowngrade) {
+  console.error(`crosstalk upgrade: bundled template is OLDER than your transport.`);
+  console.error(`  transport: ${fromVersion}`);
+  console.error(`  template:  ${toVersion}`);
+  console.error(`Your runtime is older than the runtime that scaffolded this transport.`);
+  console.error(`To upgrade your runtime: npm update -g @cordfuse/crosstalk`);
+  process.exit(3);
+}
+
+console.log(`crosstalk upgrade${dryRun ? ' (dry-run)' : ''}`);
+console.log('');
+console.log(`  transport CROSSTALK-VERSION: ${fromVersion}`);
+console.log(`  template  CROSSTALK-VERSION: ${toVersion}`);
+console.log('');
+
+// ── Plan the changes ──────────────────────────────────────────────────
+
+const upstreamFiles = listFilesRelative(templateUpstream);
+const changes: { rel: string; kind: 'add' | 'modify' | 'unchanged' }[] = [];
+
+for (const rel of upstreamFiles) {
+  const fromPath = join(templateUpstream, rel);
+  const toPath = join(transportUpstream, rel);
+  changes.push({ rel, kind: classifyChange(fromPath, toPath) });
+}
+
+const adds = changes.filter((c) => c.kind === 'add');
+const mods = changes.filter((c) => c.kind === 'modify');
+const same = changes.filter((c) => c.kind === 'unchanged');
+
+console.log(`upstream/ changes:`);
+console.log(`  ${adds.length} new file${adds.length === 1 ? '' : 's'}`);
+console.log(`  ${mods.length} modified`);
+console.log(`  ${same.length} unchanged`);
+
+if (adds.length > 0 || mods.length > 0) {
+  console.log('');
+  for (const c of [...adds, ...mods].slice(0, 20)) {
+    console.log(`  [${c.kind === 'add' ? '+' : '~'}] upstream/${c.rel}`);
+  }
+  if (adds.length + mods.length > 20) {
+    console.log(`  … and ${adds.length + mods.length - 20} more`);
+  }
+}
+
+if (updatePointers) {
+  console.log('');
+  console.log(`pointer files (with --pointers):`);
+  for (const pf of POINTER_FILES) {
+    const fromPath = join(templateDir, pf);
+    const toPath = join(transportRoot, pf);
+    if (!existsSync(fromPath)) continue;
+    const kind = classifyChange(fromPath, toPath);
+    if (kind !== 'unchanged') console.log(`  [${kind === 'add' ? '+' : '~'}] ${pf}`);
+  }
+}
+
+// ── Apply or stop ─────────────────────────────────────────────────────
+
+if (dryRun) {
+  console.log('');
+  console.log('Dry run — no changes written. Re-run without --dry-run to apply.');
+  process.exit(0);
+}
+
+if (adds.length === 0 && mods.length === 0 && !updatePointers) {
+  console.log('');
+  console.log('Already in sync. Nothing to do.');
+  process.exit(0);
+}
+
+console.log('');
+console.log('Applying...');
+
+// Copy upstream/ recursively. cpSync with force=true handles both add and modify.
+cpSync(templateUpstream, transportUpstream, { recursive: true, force: true });
+console.log(`  ✓ upstream/ synced`);
+
+if (updatePointers) {
+  for (const pf of POINTER_FILES) {
+    const fromPath = join(templateDir, pf);
+    const toPath = join(transportRoot, pf);
+    if (!existsSync(fromPath)) continue;
+    const targetDir = dirname(toPath);
+    if (!existsSync(targetDir)) {
+      cpSync(targetDir, targetDir, { recursive: true });
+    }
+    cpSync(fromPath, toPath, { force: true });
+  }
+  console.log(`  ✓ pointer files synced`);
+}
+
+console.log('');
+console.log(`Spec ${fromVersion} → ${toVersion}.`);
+console.log(`Commit the upstream/ changes when ready:`);
+console.log(`  git add upstream/${updatePointers ? ' ' + POINTER_FILES.slice(0, 3).join(' ') + ' ...' : ''}`);
+console.log(`  git commit -m "spec: upgrade to ${toVersion}"`);
+console.log('');
+console.log('Your local/, hosts/, data/, cursors/, dlq/, errors/ were not touched.');

package/src/wake.ts

@@ -0,0 +1,8 @@
+import { writeFileSync, mkdirSync } from 'fs';
+import { resolve, join } from 'path';
+
+const transportRoot = resolve(process.cwd());
+const wakeDir = join(transportRoot, '.turnq');
+mkdirSync(wakeDir, { recursive: true });
+writeFileSync(join(wakeDir, 'wake.signal'), `${Date.now()}\n`);
+console.log('wake signal sent');

package/template/.amazonq/rules/crosstalk.md

@@ -0,0 +1,2 @@
+Read [local/CROSSTALK.md](local/CROSSTALK.md) for your identity configuration (if you are a dispatched actor).
+Read [upstream/CROSSTALK.md](upstream/CROSSTALK.md) for the protocol specification.

package/template/.continue/rules/crosstalk.md

@@ -0,0 +1,7 @@
+---
+name: Crosstalk Transport
+alwaysApply: true
+---
+
+Read [local/CROSSTALK.md](local/CROSSTALK.md) for your identity configuration (if you are a dispatched actor).
+Read [upstream/CROSSTALK.md](upstream/CROSSTALK.md) for the protocol specification.

package/template/.cursor/rules/crosstalk.mdc

@@ -0,0 +1,7 @@
+---
+description: Crosstalk transport agent instructions
+applyTo: "**"
+---
+
+Read [local/CROSSTALK.md](local/CROSSTALK.md) for your identity configuration (if you are a dispatched actor).
+Read [upstream/CROSSTALK.md](upstream/CROSSTALK.md) for the protocol specification.

package/template/.github/copilot-instructions.md

@@ -0,0 +1,2 @@
+Read [local/CROSSTALK.md](local/CROSSTALK.md) for your identity configuration (if you are a dispatched actor).
+Read [upstream/CROSSTALK.md](upstream/CROSSTALK.md) for the protocol specification.

package/template/.windsurfrules

@@ -0,0 +1,2 @@
+Read [local/CROSSTALK.md](local/CROSSTALK.md) for your identity configuration (if you are a dispatched actor).
+Read [upstream/CROSSTALK.md](upstream/CROSSTALK.md) for the protocol specification.

package/template/AGENTS.md

@@ -0,0 +1,2 @@
+Read [local/CROSSTALK.md](local/CROSSTALK.md) for your identity configuration (if you are a dispatched actor).
+Read [upstream/CROSSTALK.md](upstream/CROSSTALK.md) for the protocol specification.

package/template/ANTIGRAVITY.md

@@ -0,0 +1,2 @@
+Read [local/CROSSTALK.md](local/CROSSTALK.md) for your identity configuration (if you are a dispatched actor).
+Read [upstream/CROSSTALK.md](upstream/CROSSTALK.md) for the protocol specification.

package/template/CLAUDE.md

@@ -0,0 +1,2 @@
+Read [local/CROSSTALK.md](local/CROSSTALK.md) for your identity configuration (if you are a dispatched actor).
+Read [upstream/CROSSTALK.md](upstream/CROSSTALK.md) for the protocol specification.

package/template/GEMINI.md

@@ -0,0 +1,2 @@
+Read [local/CROSSTALK.md](local/CROSSTALK.md) for your identity configuration (if you are a dispatched actor).
+Read [upstream/CROSSTALK.md](upstream/CROSSTALK.md) for the protocol specification.

package/template/OPENCODE.md

@@ -0,0 +1,2 @@
+Read [local/CROSSTALK.md](local/CROSSTALK.md) for your identity configuration (if you are a dispatched actor).
+Read [upstream/CROSSTALK.md](upstream/CROSSTALK.md) for the protocol specification.

package/template/QWEN.md

@@ -0,0 +1,2 @@
+Read [local/CROSSTALK.md](local/CROSSTALK.md) for your identity configuration (if you are a dispatched actor).
+Read [upstream/CROSSTALK.md](upstream/CROSSTALK.md) for the protocol specification.

package/template/README.md

@@ -0,0 +1,22 @@
+# Transport template
+
+This directory is the scaffold for a Crosstalk transport — the markdown + folder structure that becomes an operator's transport when they run:
+
+```sh
+crosstalk init my-transport
+```
+
+## What's here
+
+- `upstream/` — runtime-managed. Protocol spec (`CROSSTALK.md`, `PROTOCOL.md`, `OPERATOR.md`, `JITTER.md`), version pin (`CROSSTALK-VERSION`), default actor profiles (`actors/`). **Operators don't edit these.** The runtime can re-sync them when a new spec version ships.
+- `local/` — operator-owned. Custom actor profiles (`actors/`), local identity config (`CROSSTALK.md`). Operators edit these freely.
+- `hosts/` — host files declaring which actors run where, per-actor tier configurations.
+- Agent entry pointer files at root (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, etc.) — these direct agents to the right files when their CLI starts up in the transport directory.
+
+## How a transport is born
+
+`crosstalk init` copies this entire `transport/` tree to the operator's chosen directory, then initializes it as a git repo. From that moment on, the operator's transport is independent — they own it, customize `local/`, declare hosts in `hosts/`, and dispatch runs against it.
+
+## Spec reference
+
+The canonical protocol specification lives in `upstream/CROSSTALK.md`. The version pin lives in `upstream/CROSSTALK-VERSION`.

package/template/local/CROSSTALK.md

@@ -0,0 +1,4 @@
+---
+name: CONFIGURE
+email: CONFIGURE
+---

package/template/upstream/CROSSTALK-VERSION

@@ -0,0 +1 @@
+5.0