@cordfuse/crosstalk 6.0.0-alpha.9 → 7.0.0-alpha.10

package/commands/up.js

@@ -0,0 +1,135 @@
+// crosstalk up — bring up the engine container for a transport.
+//
+// alpha.6: no cwd magic. Resolves container by --containername flag
+// (default 'crosstalk') and operates against <base>/<name>/.
+//
+// Three lifecycle cases:
+//   1. Container already running → error (use chat/restart instead).
+//   2. Storage exists, no container → resume; print one-line notice.
+//   3. Storage doesn't exist → error pointing to `crosstalk init`.
+//
+// First-time up generates <base>/<name>/docker-compose.yml from a template.
+// Subsequent ups respect operator edits — only regenerate if missing.
+
+import { writeFileSync, existsSync, readFileSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { has } from '../lib/argv.js';
+import {
+  requireInitialized,
+  isRunning,
+  containerExists,
+  apiPortFor,
+  DEFAULT_CONTAINER_NAME,
+  CROSSTALK_LABEL,
+} from '../lib/resolve.js';
+
+const DEFAULT_IMAGE = process.env.CROSSTALK_IMAGE
+  ?? 'ghcr.io/cordfuse/crosstalk-server:7.0.0-alpha.8';
+
+function usage(exit = 0) {
+  const w = exit === 0 ? process.stdout : process.stderr;
+  w.write(
+`Usage: crosstalk up [--containername <name>]
+
+Starts the engine container for a transport that has already been
+'crosstalk init'd. Default container is 'crosstalk'; pass --containername
+to address a named one.
+
+If the storage at <base>/<name>/ already exists (operator previously
+brought it up then 'crosstalk down'd it), the container resumes against
+that state — installed agent CLIs, OAuth tokens, dispatcher cursor all
+carry over.
+
+Environment:
+  CROSSTALK_IMAGE         Override the engine image
+  CROSSTALK_ALIAS         Override the engine's machine identity
+                          (defaults to the container name)
+`,
+  );
+  process.exit(exit);
+}
+
+function renderCompose({ name, image, apiPort, alias, uid, gid, paths }) {
+  return `# Generated by 'crosstalk up'. Machine-local — runtime-owned.
+# Storage mode: ${paths.mode}
+# transport       (container /var/lib/crosstalk-transport) → ${paths.transportDir}
+# crosstalk-root  (container /crosstalk-root)              → ${paths.crosstalkRoot}
+# crosstalk-state (container /var/lib/crosstalk-state)     → ${paths.crosstalkState}
+
+services:
+  crosstalkd:
+    image: ${image}
+    container_name: ${name}
+    restart: unless-stopped
+    labels:
+      ${CROSSTALK_LABEL.replace('=', ': "')}"
+    ports:
+      - "127.0.0.1:${apiPort}:7000"
+    volumes:
+      - ${paths.transportDir}:/var/lib/crosstalk-transport
+      - ${paths.crosstalkRoot}:/crosstalk-root
+      - ${paths.crosstalkState}:/var/lib/crosstalk-state
+    environment:
+      CROSSTALK_ALIAS: ${alias}
+      CROSSTALK_UID: "${uid}"
+      CROSSTALK_GID: "${gid}"
+      CROSSTALKD_API_PORT: "7000"
+      DISPATCH_JSON: "true"
+      DISPATCH_POLL_SECONDS: "30"
+`;
+}
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) usage(0);
+
+  const { name, paths } = requireInitialized(argv);
+
+  // Case 1: already running → error, don't surprise the operator with
+  // a silent no-op or implicit restart.
+  if (isRunning(name)) {
+    process.stderr.write(
+      `crosstalk up: '${name}' is already running.\n` +
+      `  Use 'crosstalk chat${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}' to attach,\n` +
+      `  'crosstalk restart${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}' to recreate,\n` +
+      `  or 'crosstalk down${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}' first.\n`,
+    );
+    return 1;
+  }
+
+  // Case "stopped but not removed" — `docker stop` without compose down.
+  // Silently remove the dead container so the recreate works.
+  if (containerExists(name)) {
+    spawnSync('docker', ['rm', '-f', name], { stdio: 'ignore' });
+  }
+
+  // Compose file generation. If operator edited theirs, respect it.
+  const generated = !existsSync(paths.composeFile);
+  if (generated) {
+    const alias = process.env.CROSSTALK_ALIAS ?? name;
+    const uid = typeof process.getuid === 'function' ? process.getuid() : 1000;
+    const gid = typeof process.getgid === 'function' ? process.getgid() : 1000;
+    const apiPort = apiPortFor(name);
+    const image = DEFAULT_IMAGE;
+    const content = renderCompose({ name, image, apiPort, alias, uid, gid, paths });
+    writeFileSync(paths.composeFile, content);
+  }
+
+  // Resume notice when storage is non-fresh (operator brought it up
+  // before, has installed CLIs / auth state in crosstalk-root/). Heuristic:
+  // crosstalk-root has more than just a .gitkeep / nothing.
+  if (!generated) {
+    process.stdout.write(`Resuming '${name}' (existing state at ${paths.storageRoot})\n`);
+  }
+
+  const r = spawnSync('docker', ['compose', '-f', paths.composeFile, 'up', '-d'], {
+    stdio: 'inherit',
+  });
+  if (r.status !== 0) {
+    process.stderr.write(`crosstalk up: docker compose exited ${r.status}\n`);
+    return r.status ?? 1;
+  }
+  process.stdout.write(
+    `\n'${name}' starting. Check with 'crosstalk status${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}' (give it ~5s).\n`,
+  );
+  return 0;
+}

package/commands/version.js

@@ -0,0 +1,33 @@
+// crosstalk version — print client and (if reachable) engine versions.
+//
+// Doesn't fail if the engine isn't reachable; just prints "(engine
+// unreachable)" since you might be running `version` before bringing
+// the container up.
+
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { apiFor, ConnectError } from '../lib/api-client.js';
+
+const thisDir = dirname(fileURLToPath(import.meta.url));
+const pkgPath = join(thisDir, '..', 'package.json');
+const clientPkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+
+export async function run(argv) {
+  process.stdout.write(`crosstalk client: ${clientPkg.version}\n`);
+  const api = apiFor(argv);
+  try {
+    // Skew detection happens passively in api-client.js via the
+    // X-Crosstalk-Engine-Version response header — no duplication here.
+    const v = await api.get('/version');
+    process.stdout.write(`crosstalkd engine: ${v.version} (alias: ${v.alias})\n`);
+  } catch (err) {
+    if (err instanceof ConnectError) {
+      process.stdout.write(`crosstalkd engine: (unreachable on 127.0.0.1:${err.port})\n`);
+      return 0;
+    }
+    process.stdout.write(`crosstalkd engine: (error: ${err.message})\n`);
+    return 0;
+  }
+  return 0;
+}

package/lib/api-client.js

@@ -0,0 +1,141 @@
+// api-client.js — HTTP client over loopback to crosstalkd's local API.
+//
+// All operator commands route through this. The engine binds 127.0.0.1
+// inside the container; docker-compose maps that to the host loopback.
+// The host port differs per container — default container 'crosstalk'
+// gets 7000; named containers pick a free port at init time, recorded in
+// `<base>/<name>/api-port`. apiPortFor() resolves name → port.
+//
+// Port resolution order:
+//   1. opts.port (explicit override from caller)
+//   2. CROSSTALK_API_PORT env var (test/dev override)
+//   3. apiPortFor(name) — reads `<base>/<name>/api-port` file
+//   4. DEFAULT_API_PORT (7000) as last resort
+//
+// No auth: engine binds 127.0.0.1 only, no token. Same model as ollama.
+//
+// Version skew: engine sets X-Crosstalk-Engine-Version on every response.
+// We compare to client version on each call, emit one warning per process
+// if mismatched. Pre-1.0 client and engine ship in lockstep.
+
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { apiPortFor, DEFAULT_API_PORT, parseContainerName } from './resolve.js';
+
+const CLIENT_VERSION = (() => {
+  try {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    return JSON.parse(readFileSync(join(thisDir, '..', 'package.json'), 'utf-8')).version;
+  } catch {
+    return 'unknown';
+  }
+})();
+
+let skewWarned = false;
+
+function checkSkew(engineVersion) {
+  if (skewWarned || !engineVersion || engineVersion === CLIENT_VERSION) return;
+  skewWarned = true;
+  process.stderr.write(
+    `[WARN] Version skew: client ${CLIENT_VERSION}, engine ${engineVersion}.\n` +
+    `       Pre-1.0 client and engine ship in lockstep. Likely fix:\n` +
+    `         crosstalk pull && crosstalk restart    # if engine is behind\n` +
+    `         npm install -g @cordfuse/crosstalk     # if client is behind\n\n`,
+  );
+}
+
+export { DEFAULT_API_PORT };
+
+export function resolvePort(opts = {}) {
+  if (typeof opts.port === 'number' && Number.isInteger(opts.port)) return opts.port;
+  const fromEnv = Number(process.env.CROSSTALK_API_PORT);
+  if (Number.isInteger(fromEnv) && fromEnv > 0) return fromEnv;
+  if (opts.name) return apiPortFor(opts.name);
+  return DEFAULT_API_PORT;
+}
+
+function apiUrl(path, port) {
+  return `http://127.0.0.1:${port}${path}`;
+}
+
+async function parseJsonOrThrow(res) {
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    throw new ApiError(res.status, 'invalid JSON in response');
+  }
+  if (!res.ok) {
+    const msg = body && typeof body.error === 'string' ? body.error : `HTTP ${res.status}`;
+    throw new ApiError(res.status, msg);
+  }
+  return body;
+}
+
+export class ApiError extends Error {
+  constructor(status, message) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+  }
+}
+
+export class ConnectError extends Error {
+  constructor(port, cause) {
+    super(
+      `cannot reach crosstalkd on 127.0.0.1:${port} — is the container running? ` +
+      `Try 'crosstalk up' to start it. (underlying: ${cause})`,
+    );
+    this.name = 'ConnectError';
+    this.port = port;
+  }
+}
+
+async function call(method, path, body, opts = {}) {
+  const port = resolvePort(opts);
+  const init = {
+    method,
+    headers: body ? { 'Content-Type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  };
+  let res;
+  try {
+    res = await fetch(apiUrl(path, port), init);
+  } catch (err) {
+    throw new ConnectError(port, err.message || String(err));
+  }
+  checkSkew(res.headers.get('x-crosstalk-engine-version'));
+  return parseJsonOrThrow(res);
+}
+
+// Bind an api client to a specific container name. All callers should
+// either pass argv (auto-resolves name) or an explicit name. Internally
+// each call resolves the port via the name's api-port file. Validation
+// errors print cleanly (no stack trace) — bug C fix.
+export function apiFor(argv) {
+  let name;
+  try {
+    name = parseContainerName(argv);
+  } catch (err) {
+    process.stderr.write(`crosstalk: ${err.message}\n`);
+    process.exit(1);
+  }
+  return {
+    name,
+    get:    (path, opts = {})        => call('GET',    path, undefined, { ...opts, name }),
+    post:   (path, body, opts = {})  => call('POST',   path, body,      { ...opts, name }),
+    patch:  (path, body, opts = {})  => call('PATCH',  path, body,      { ...opts, name }),
+    delete: (path, opts = {})        => call('DELETE', path, undefined, { ...opts, name }),
+  };
+}
+
+// Legacy entry point — env-driven port (CROSSTALK_API_PORT or 7000),
+// no name resolution. Kept for harness compatibility; new code should
+// use apiFor(argv) instead.
+export const api = {
+  get:    (path, opts)        => call('GET',    path, undefined, opts),
+  post:   (path, body, opts)  => call('POST',   path, body,       opts),
+  patch:  (path, body, opts)  => call('PATCH',  path, body,       opts),
+  delete: (path, opts)        => call('DELETE', path, undefined,  opts),
+};

package/lib/argv.js

@@ -0,0 +1,30 @@
+// Tiny argv helpers shared across commands. No yargs / commander
+// dependency — the surfaces are simple enough that hand-parsing is
+// shorter than wiring a framework.
+
+export function flag(argv, name) {
+  const i = argv.indexOf(name);
+  if (i === -1 || i === argv.length - 1) return undefined;
+  return argv[i + 1];
+}
+
+export function has(argv, name) {
+  return argv.includes(name);
+}
+
+// All positional (non-flag) args, skipping flag values for the listed
+// flags. Handles both --long and -short forms; flag names in
+// flagsWithValue must match the form they appear in argv.
+export function positionals(argv, flagsWithValue) {
+  const valueFlags = new Set(flagsWithValue);
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('-')) {
+      if (valueFlags.has(a)) i++;
+      continue;
+    }
+    out.push(a);
+  }
+  return out;
+}

package/lib/errors.js

@@ -0,0 +1,19 @@
+// Shared error→stderr formatting for client commands.
+//
+// Pattern: catch known error types (ConnectError, ApiError) and print
+// operator-readable messages with appropriate exit codes. Unknown errors
+// rethrow so they show stack traces — those are real bugs to fix.
+
+import { ApiError, ConnectError } from './api-client.js';
+
+export function reportAndExit(err, contextHint) {
+  if (err instanceof ConnectError) {
+    process.stderr.write(`${contextHint}: ${err.message}\n`);
+    process.exit(4);
+  }
+  if (err instanceof ApiError) {
+    process.stderr.write(`${contextHint}: ${err.message} (HTTP ${err.status})\n`);
+    process.exit(err.status === 400 ? 1 : 3);
+  }
+  throw err;
+}

package/lib/resolve.js

@@ -0,0 +1,191 @@
+// resolve.js — name-based resolution for the runtime-owned-transport
+// model (alpha.6+).
+//
+// Operator addresses transports by container name, picked at `crosstalk
+// init`. Default container is literally `crosstalk`; named containers
+// are literally whatever the operator typed into --containername.
+// Identity lives with the container; storage lives at <base>/<name>/.
+//
+// Replaces the cwd-walking transport.js from alpha.5 (which derived
+// identity from the operator's filesystem position). The new model is
+// position-independent — operator can be anywhere on disk.
+
+import { existsSync, readFileSync, mkdirSync, readdirSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { join } from 'path';
+import { homedir } from 'os';
+
+export const DEFAULT_CONTAINER_NAME = 'crosstalk';
+export const DEFAULT_API_PORT = 7000;
+export const CROSSTALK_LABEL = 'crosstalk.transport=true';
+
+// Per-OS storage bases. User-mode (default) keeps everything under the
+// operator's home — no sudo/UAC, no Docker Desktop file-sharing allowlist
+// gymnastics. System-mode is for headless multi-operator deployments.
+export function resolveBase(mode) {
+  const platform = process.platform;
+  const bases = (platform === 'darwin')
+    ? {
+        user:   join(homedir(), 'Library', 'Application Support', 'crosstalk'),
+        system: '/Library/Application Support/crosstalk',
+      }
+    : (platform === 'win32')
+    ? {
+        user:   process.env['LOCALAPPDATA']
+                  ? join(process.env['LOCALAPPDATA'], 'crosstalk')
+                  : join(homedir(), 'AppData', 'Local', 'crosstalk'),
+        system: 'C:\\ProgramData\\crosstalk',
+      }
+    : {
+        user:   join(process.env['XDG_DATA_HOME'] ?? join(homedir(), '.local', 'share'), 'crosstalk'),
+        system: '/var/lib/crosstalk',
+      };
+
+  if (mode !== 'user' && mode !== 'system') {
+    throw new Error(`CROSSTALK_STORAGE_MODE='${mode}' invalid — must be 'user' or 'system'.`);
+  }
+  return bases[mode];
+}
+
+export function storageMode() {
+  return (process.env.CROSSTALK_STORAGE_MODE ?? 'user').toLowerCase();
+}
+
+// All storage paths for a given container name, derived from the resolved
+// base. None of these are validated for existence here — callers check
+// based on context (init pre-creates, up verifies, etc).
+export function storagePaths(name, mode = storageMode()) {
+  const base = resolveBase(mode);
+  const root = join(base, name);
+  return {
+    base,
+    mode,
+    storageRoot:    root,
+    transportDir:   join(root, 'transport'),
+    crosstalkRoot:  join(root, 'crosstalk-root'),
+    crosstalkState: join(root, 'crosstalk-state'),
+    composeFile:    join(root, 'docker-compose.yml'),
+    portFile:       join(root, 'api-port'),
+  };
+}
+
+// Container name from --containername flag, defaulting to `crosstalk`.
+// Validates the name is a sane Docker container name + filesystem dir
+// name: lowercase alphanumeric, `_.-`, no leading dot/hyphen.
+const NAME_RE = /^[a-z0-9][a-z0-9_.-]*$/;
+export function parseContainerName(argv) {
+  let name = DEFAULT_CONTAINER_NAME;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--containername' || argv[i] === '-c') {
+      const val = argv[i + 1];
+      if (!val) throw new Error('--containername requires a value');
+      name = val;
+      break;
+    }
+  }
+  if (!NAME_RE.test(name)) {
+    throw new Error(
+      `--containername '${name}' invalid — must be lowercase alphanumeric ` +
+      `with optional ._- (no leading . or -).`,
+    );
+  }
+  return name;
+}
+
+// Read the API port for a given container. Source-of-truth lookup:
+//   1. `<base>/<name>/api-port` file (written at init time)
+//   2. Fallback: DEFAULT_API_PORT
+// We use a file rather than `docker inspect` because the resolver runs
+// before the container exists (`init`) and after it's gone (`rm` cleanup).
+// Docker is authoritative for what's running; the port file is
+// authoritative for which port a given container WOULD use.
+export function apiPortFor(name) {
+  const paths = storagePaths(name);
+  if (existsSync(paths.portFile)) {
+    const v = Number(readFileSync(paths.portFile, 'utf-8').trim());
+    if (Number.isInteger(v) && v > 0 && v < 65536) return v;
+  }
+  return DEFAULT_API_PORT;
+}
+
+// Pick a free TCP port. Default container always gets DEFAULT_API_PORT
+// (7000) so operators have a predictable target. Named containers search
+// upward from 7001 until they find one that doesn't collide with already-
+// allocated containers (any `<base>/*/api-port` file).
+export function pickFreePort(name, mode = storageMode()) {
+  if (name === DEFAULT_CONTAINER_NAME) return DEFAULT_API_PORT;
+  const base = resolveBase(mode);
+  const taken = new Set([DEFAULT_API_PORT]);
+  try {
+    const dirs = readdirSync(base);
+    for (const d of dirs) {
+      const portFile = join(base, d, 'api-port');
+      if (existsSync(portFile)) {
+        const v = Number(readFileSync(portFile, 'utf-8').trim());
+        if (Number.isInteger(v)) taken.add(v);
+      }
+    }
+  } catch { /* base may not exist yet */ }
+  for (let p = 7001; p < 8000; p++) {
+    if (!taken.has(p)) return p;
+  }
+  throw new Error('Could not find a free port between 7001 and 7999.');
+}
+
+// True if `<base>/<name>/transport/.git` exists. The cheapest signal that
+// a transport has been initialized for this name.
+export function isInitialized(name) {
+  const paths = storagePaths(name);
+  return existsSync(join(paths.transportDir, '.git'));
+}
+
+// True if a running container exists for this name. Uses Docker as the
+// source of truth, filtered by our label to avoid confusing
+// operator-named-`crosstalk` containers from other workloads.
+export function isRunning(name) {
+  const r = spawnSync(
+    'docker',
+    ['ps', '--filter', `label=${CROSSTALK_LABEL}`, '--filter', `name=^${name}$`, '--format', '{{.Names}}'],
+    { encoding: 'utf-8' },
+  );
+  if (r.status !== 0) return false;
+  return r.stdout.trim().split('\n').includes(name);
+}
+
+// True if a stopped container exists (less common path; usually `down`
+// removes the container). Checked separately so `up` can decide whether
+// to `docker rm` and recreate.
+export function containerExists(name) {
+  const r = spawnSync(
+    'docker',
+    ['ps', '-a', '--filter', `label=${CROSSTALK_LABEL}`, '--filter', `name=^${name}$`, '--format', '{{.Names}}'],
+    { encoding: 'utf-8' },
+  );
+  if (r.status !== 0) return false;
+  return r.stdout.trim().split('\n').includes(name);
+}
+
+// Look up the resolved name+paths from argv, validate that init has run,
+// and exit with a clear error if not. For verbs that operate on existing
+// transports (up after init, status, chat, down, rm, etc).
+//
+// Validation errors from parseContainerName are caught here and printed
+// cleanly — Mac's bug C from alpha.6 was a raw stack trace when an
+// invalid --containername reached the resolver.
+export function requireInitialized(argv) {
+  let name;
+  try {
+    name = parseContainerName(argv);
+  } catch (err) {
+    process.stderr.write(`crosstalk: ${err.message}\n`);
+    process.exit(1);
+  }
+  if (!isInitialized(name)) {
+    process.stderr.write(
+      `crosstalk: no transport '${name}' on this machine.\n` +
+      `  Run 'crosstalk init${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}' to set one up.\n`,
+    );
+    process.exit(2);
+  }
+  return { name, paths: storagePaths(name) };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cordfuse/crosstalk",
-  "version": "6.0.0-alpha.9",
-  "description": "Crosstalk runtime — async messaging between agents over git, across machines.",
+  "version": "7.0.0-alpha.10",
+  "description": "Crosstalk client — host-side CLI that talks to the crosstalkd daemon running inside the crosstalk-server container.",
   "type": "module",
   "license": "MIT",
   "homepage": "https://github.com/cordfuse/crosstalk",
@@ -14,26 +14,10 @@
   },
   "files": [
     "bin/",
-    "src/",
-    "template/"
+    "lib/",
+    "commands/",
+    "README.md"
   ],
-  "scripts": {
-    "build": "tsc --noEmit",
-    "lint": "tsc --noEmit",
-    "test": "bun test",
-    "prepack": "cp -r ../transport template",
-    "postpack": "rm -rf template"
-  },
-  "dependencies": {
-    "@cordfuse/turnq": "^0.4.2",
-    "@lydell/node-pty": "^1.2.0-beta.12",
-    "tsx": "^4.20.0",
-    "yaml": "^2.8.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.10.0",
-    "typescript": "^5.7.0"
-  },
   "engines": {
     "node": ">=20"
   },