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

package/lib/credentials.js

@@ -0,0 +1,207 @@
+// credentials.js — CLI-side persisted credentials (multi-profile).
+//
+// Replaces v7's `auth-token.js` (single-token at cli-token). Stores
+// the active profile + all known profiles in a single JSON file. Each
+// profile carries its own server URL + bearer token, so the same CLI
+// can talk to multiple crosstalk engines (e.g. local loopback +
+// hosted prod).
+//
+// Path: $XDG_CONFIG_HOME/crosstalk/credentials.json, falling back to
+// $HOME/.config/crosstalk/credentials.json. File mode 0600.
+//
+// Shape:
+//   {
+//     "activeProfile": "default",
+//     "profiles": {
+//       "default": {
+//         "server":    "http://127.0.0.1:7000",
+//         "username":  "stevekrisjanovs",
+//         "token":     "sas_<id>.<secret>",
+//         "tokenId":   "<id>",
+//         "createdAt": "2026-06-22T16:54:00Z"
+//       }
+//     }
+//   }
+//
+// Legacy migration: on first read, if a v7-era `cli-token` file exists
+// and `credentials.json` does not, the single token is ingested as the
+// `default` profile (server = loopback default) and the legacy file is
+// removed. Migration is best-effort; if it fails the engine just
+// 401s and the operator re-runs `auth login`.
+
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  unlinkSync,
+  mkdirSync,
+  chmodSync,
+} from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const DEFAULT_LOOPBACK_SERVER = 'http://127.0.0.1:7000';
+
+function configDir() {
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+  return join(base, 'crosstalk');
+}
+
+function credentialsPath() {
+  return join(configDir(), 'credentials.json');
+}
+
+function legacyTokenPath() {
+  return join(configDir(), 'cli-token');
+}
+
+function emptyCredentials() {
+  return { activeProfile: null, profiles: {} };
+}
+
+function readJsonOrEmpty(path) {
+  try {
+    const raw = readFileSync(path, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return emptyCredentials();
+    if (!parsed.profiles || typeof parsed.profiles !== 'object') parsed.profiles = {};
+    return parsed;
+  } catch {
+    return emptyCredentials();
+  }
+}
+
+let migrationAttempted = false;
+function maybeMigrate() {
+  if (migrationAttempted) return;
+  migrationAttempted = true;
+  const credPath = credentialsPath();
+  const legacyPath = legacyTokenPath();
+  if (existsSync(credPath)) return;
+  if (!existsSync(legacyPath)) return;
+  let token;
+  try {
+    token = readFileSync(legacyPath, 'utf-8').trim();
+  } catch {
+    return;
+  }
+  if (!token) return;
+  const cred = emptyCredentials();
+  cred.activeProfile = 'default';
+  cred.profiles.default = {
+    server: DEFAULT_LOOPBACK_SERVER,
+    username: null,
+    token,
+    tokenId: null,
+    createdAt: new Date().toISOString(),
+  };
+  writeCredentials(cred);
+  try { unlinkSync(legacyPath); } catch { /* best-effort */ }
+}
+
+export function readCredentials() {
+  maybeMigrate();
+  return readJsonOrEmpty(credentialsPath());
+}
+
+export function writeCredentials(cred) {
+  const dir = configDir();
+  mkdirSync(dir, { recursive: true });
+  const path = credentialsPath();
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, JSON.stringify(cred, null, 2) + '\n', { mode: 0o600 });
+  try { chmodSync(tmp, 0o600); } catch { /* best-effort */ }
+  renameSync(tmp, path);
+  return path;
+}
+
+export function credentialsFilePath() {
+  return credentialsPath();
+}
+
+function profileNameOverride(argv) {
+  if (!Array.isArray(argv)) return null;
+  for (let i = 0; i < argv.length - 1; i++) {
+    if (argv[i] === '--profile') return argv[i + 1];
+  }
+  return null;
+}
+
+export function getActiveProfileName(argv = []) {
+  const override = profileNameOverride(argv);
+  if (override) return override;
+  const cred = readCredentials();
+  return cred.activeProfile || null;
+}
+
+export function getActiveProfile(argv = []) {
+  const name = getActiveProfileName(argv);
+  if (!name) return null;
+  const cred = readCredentials();
+  return cred.profiles[name] || null;
+}
+
+export function listProfiles() {
+  const cred = readCredentials();
+  return Object.entries(cred.profiles).map(([name, p]) => ({
+    name,
+    server: p.server,
+    username: p.username,
+    tokenId: p.tokenId,
+    active: cred.activeProfile === name,
+  }));
+}
+
+export function setActiveProfile(name) {
+  const cred = readCredentials();
+  if (!cred.profiles[name]) {
+    throw new Error(`profile '${name}' not found`);
+  }
+  cred.activeProfile = name;
+  writeCredentials(cred);
+}
+
+export function saveProfile(name, data) {
+  const cred = readCredentials();
+  cred.profiles[name] = {
+    server: data.server || DEFAULT_LOOPBACK_SERVER,
+    username: data.username ?? null,
+    token: data.token,
+    tokenId: data.tokenId ?? null,
+    createdAt: data.createdAt || new Date().toISOString(),
+  };
+  if (!cred.activeProfile) cred.activeProfile = name;
+  writeCredentials(cred);
+}
+
+export function deleteProfile(name) {
+  const cred = readCredentials();
+  if (!cred.profiles[name]) return false;
+  delete cred.profiles[name];
+  if (cred.activeProfile === name) {
+    const remaining = Object.keys(cred.profiles);
+    cred.activeProfile = remaining.length > 0 ? remaining[0] : null;
+  }
+  writeCredentials(cred);
+  return true;
+}
+
+export function deleteActiveProfile() {
+  const cred = readCredentials();
+  const name = cred.activeProfile;
+  if (!name) return null;
+  delete cred.profiles[name];
+  const remaining = Object.keys(cred.profiles);
+  cred.activeProfile = remaining.length > 0 ? remaining[0] : null;
+  writeCredentials(cred);
+  return name;
+}
+
+// Back-compat wrapper preserved so `lib/api-client.js` can keep its
+// readToken()-shaped call site without knowing about profiles. The
+// active profile drives the token; absent active profile → null.
+export function readToken(argv = []) {
+  const p = getActiveProfile(argv);
+  return p ? p.token : null;
+}

package/lib/nativeServer.js

@@ -0,0 +1,173 @@
+// nativeServer.js — host-process control for the crosstalk engine.
+//
+// v8-native replaces the docker lifecycle. The engine main loop is
+// `crosstalk daemon dispatch …`, spawned as a detached child of the
+// operator's host shell. PID is recorded in crosstalk-state/crosstalk.pid
+// and stdio is redirected to crosstalk-state/crosstalk.log.
+//
+// The daemon is an internal subcommand of the `crosstalk` CLI;
+// startEngine() spawns `process.execPath bin/crosstalk.js daemon dispatch …`
+// against the package's own bin script, resolved relative to this file.
+//
+// Trust + isolation notes:
+//   - User mode (default): engine inherits the operator's $HOME, so
+//     agent CLI OAuth tokens land in ~/.claude, ~/.codex, etc. — the
+//     same places the operator's interactive sessions use. Simpler and
+//     less surprising than the v7 container's CROSSTALK_HOME isolation.
+//   - System mode: engine runs as the `crosstalk` system user (per
+//     systemd unit), with $HOME set to /var/lib/crosstalk so agents
+//     write their state under the service user, not /home/*.
+
+import { spawn } from 'child_process';
+import { openSync, existsSync, writeFileSync, mkdirSync, statSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { storagePaths, apiPortFor, runningPid } from './resolve.js';
+
+const _thisDir = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Resolve the path to this package's own `crosstalk` CLI entrypoint.
+ * The daemon is now `crosstalk daemon dispatch …`, so startEngine
+ * re-invokes the very script that called it — using process.execPath
+ * (the running Node) + this bin path.
+ */
+export function resolveSelfBin() {
+  return resolve(_thisDir, '..', 'bin', 'crosstalk.js');
+}
+
+/**
+ * Start the crosstalk engine (`crosstalk daemon dispatch`) as a detached host process for the given transport.
+ * Returns { ok: true, pid } on success, { ok: false, error } otherwise.
+ *
+ * Behavior:
+ *   - Refuses if already running (use stop/restart instead).
+ *   - Creates the state dir if missing.
+ *   - Opens the log file in append mode; stdin/stdout/stderr all go there.
+ *   - Spawns detached so the parent can exit and the engine keeps running.
+ *   - Verifies the PID is alive after a short delay (~150ms) before returning.
+ */
+export function startEngine(name, opts = {}) {
+  const paths = storagePaths(name);
+  if (runningPid(name)) {
+    return { ok: false, error: `'${name}' is already running (pid ${runningPid(name)})` };
+  }
+
+  const selfBin = resolveSelfBin();
+  if (!existsSync(selfBin)) {
+    return {
+      ok: false,
+      error: `crosstalk CLI entry missing at ${selfBin} — package install looks broken`,
+    };
+  }
+
+  mkdirSync(paths.crosstalkState, { recursive: true });
+
+  const alias = opts.alias ?? process.env.CROSSTALK_ALIAS ?? name;
+  const poll = String(opts.pollSeconds ?? process.env.DISPATCH_POLL_SECONDS ?? 30);
+  const port = String(apiPortFor(name));
+
+  const env = {
+    ...process.env,
+    CROSSTALK_API_PORT: port,
+    TRANSPORT_DIR: paths.transportDir,
+  };
+
+  const logFd = openSync(paths.logFile, 'a');
+  const child = spawn(
+    process.execPath,
+    [selfBin, 'daemon', 'dispatch', '--alias', alias, '--poll', poll, '--json'],
+    {
+      cwd: paths.transportDir,
+      env,
+      stdio: ['ignore', logFd, logFd],
+      detached: true,
+    },
+  );
+  if (!child.pid) {
+    return { ok: false, error: 'spawn failed to allocate a pid' };
+  }
+  writeFileSync(paths.pidFile, String(child.pid) + '\n');
+  child.unref(); // let parent exit without waiting on the child
+
+  // Brief verify the child didn't die immediately (missing transport
+  // dir, broken tsx resolution, etc.). 150ms is enough to catch
+  // immediate ENOENT-class failures without making `server start`
+  // feel sluggish.
+  const start = Date.now();
+  while (Date.now() - start < 150) {
+    try { process.kill(child.pid, 0); } catch {
+      return { ok: false, error: 'engine exited immediately — check logs at ' + paths.logFile };
+    }
+  }
+  return { ok: true, pid: child.pid, logFile: paths.logFile, port: Number(port) };
+}
+
+/**
+ * Stop a running crosstalk engine. SIGTERM first, then SIGKILL after a grace
+ * period (default 5s). Returns { ok, wasRunning, killed? }.
+ *
+ * `killed: true` indicates SIGKILL was required (clean shutdown failed).
+ */
+export function stopEngine(name, opts = {}) {
+  const paths = storagePaths(name);
+  const pid = runningPid(name);
+  if (!pid) {
+    // No running engine; mop up any stale pid file and report idempotent success.
+    if (existsSync(paths.pidFile)) {
+      try { writeFileSync(paths.pidFile, ''); } catch { /* best effort */ }
+    }
+    return { ok: true, wasRunning: false };
+  }
+
+  const graceMs = (opts.graceSeconds ?? 5) * 1000;
+  try { process.kill(pid, 'SIGTERM'); } catch { /* already gone */ }
+
+  const deadline = Date.now() + graceMs;
+  let killed = false;
+  while (Date.now() < deadline) {
+    try { process.kill(pid, 0); } catch {
+      // Process is gone — clean exit.
+      try { writeFileSync(paths.pidFile, ''); } catch {}
+      return { ok: true, wasRunning: true, pid };
+    }
+    // Tight spin — 50ms granularity is fine for a 5s window.
+    const until = Date.now() + 50;
+    while (Date.now() < until) { /* idle */ }
+  }
+  // Timed out. Hard-kill.
+  try { process.kill(pid, 'SIGKILL'); killed = true; } catch { /* race: gone */ }
+  try { writeFileSync(paths.pidFile, ''); } catch {}
+  return { ok: true, wasRunning: true, pid, killed };
+}
+
+/**
+ * Snapshot the engine's status for the given transport. Returns
+ * { running, pid?, port?, uptimeSeconds?, apiReachable? }.
+ *
+ * apiReachable requires an HTTP probe; pass { probeApi: true } to opt in.
+ */
+export async function engineStatus(name, opts = {}) {
+  const paths = storagePaths(name);
+  const pid = runningPid(name);
+  if (!pid) return { running: false };
+
+  let uptimeSeconds;
+  try {
+    const stat = statSync(`/proc/${pid}/stat`);
+    uptimeSeconds = Math.round((Date.now() - stat.ctimeMs) / 1000);
+  } catch { /* /proc not available on macOS — leave undefined */ }
+
+  const port = apiPortFor(name);
+  const out = { running: true, pid, port, ...(uptimeSeconds !== undefined ? { uptimeSeconds } : {}) };
+
+  if (opts.probeApi) {
+    try {
+      const resp = await fetch(`http://127.0.0.1:${port}/healthz`, { signal: AbortSignal.timeout(2000) });
+      out.apiReachable = resp.ok;
+    } catch {
+      out.apiReachable = false;
+    }
+  }
+  return out;
+}

package/lib/resolve.js

@@ -10,14 +10,22 @@
 // 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 { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs';
 import { spawnSync } from 'child_process';
-import { join } from 'path';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
 import { homedir } from 'os';
 
 export const DEFAULT_CONTAINER_NAME = 'crosstalk';
 export const DEFAULT_API_PORT = 7000;
-export const CROSSTALK_LABEL = 'crosstalk.transport=true';
+
+// Client version exported for the skew-warn check in api-client.js. The
+// v7 DEFAULT_IMAGE export (resolved CROSSTALK_IMAGE env or
+// ghcr.io/cordfuse/crosstalk-server:<CLIENT_VERSION>) was removed in
+// v8-native — no container image to pull.
+const _thisDir = dirname(fileURLToPath(import.meta.url));
+const _pkg = JSON.parse(readFileSync(join(_thisDir, '..', 'package.json'), 'utf-8'));
+export const CLIENT_VERSION = _pkg.version;
 
 // Per-OS storage bases. User-mode (default) keeps everything under the
 // operator's home — no sudo/UAC, no Docker Desktop file-sharing allowlist
@@ -42,36 +50,83 @@ export function resolveBase(mode) {
       };
 
   if (mode !== 'user' && mode !== 'system') {
-    throw new Error(`CROSSTALK_STORAGE_MODE='${mode}' invalid — must be 'user' or 'system'.`);
+    throw new Error(`storage mode '${mode}' invalid — must be 'user' or 'system' (see CROSSTALK_USER_MODE).`);
   }
   return bases[mode];
 }
 
+/**
+ * Resolve the runtime mode: 'user' or 'system'.
+ *
+ * v8-native env-var convention: `CROSSTALK_USER_MODE=1` opts into user
+ * mode. Without it, the default is 'system' (matches @cordfuse/llmux's
+ * `LLMUX_USER_MODE` pattern — boolean opt-in to user mode, system is
+ * the production default).
+ *
+ * v7 used `CROSSTALK_STORAGE_MODE=user|system` and defaulted to 'user'.
+ * That string form is still honored for one transition release so
+ * operator scripts don't break instantly — a one-time stderr deprecation
+ * notice fires when it's read. v9 cuts the back-compat path.
+ *
+ * Truthy values for CROSSTALK_USER_MODE: '1', 'true', 'yes' (case
+ * insensitive). Anything else (including '0', 'false', empty) → false.
+ */
 export function storageMode() {
-  return (process.env.CROSSTALK_STORAGE_MODE ?? 'user').toLowerCase();
+  // v7 back-compat path (one transition release).
+  const legacy = process.env.CROSSTALK_STORAGE_MODE;
+  if (legacy !== undefined) {
+    const v = legacy.toLowerCase();
+    if (v === 'user' || v === 'system') {
+      if (!process.env._CROSSTALK_LEGACY_MODE_WARNED) {
+        process.stderr.write(
+          `crosstalk: CROSSTALK_STORAGE_MODE='${v}' is deprecated.\n` +
+          `  Use CROSSTALK_USER_MODE=1 to opt into user mode; otherwise system mode is the default.\n`,
+        );
+        process.env._CROSSTALK_LEGACY_MODE_WARNED = '1';
+      }
+      return v;
+    }
+    throw new Error(`CROSSTALK_STORAGE_MODE='${legacy}' invalid — must be 'user' or 'system'.`);
+  }
+  // v8 path: boolean opt-in to user mode, default system.
+  const userVar = (process.env.CROSSTALK_USER_MODE ?? '').toLowerCase();
+  const userMode = userVar === '1' || userVar === 'true' || userVar === 'yes';
+  return userMode ? 'user' : 'system';
 }
 
-// All storage paths for a given container name, derived from the resolved
+// All storage paths for a given transport 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).
+// based on context (init pre-creates, server start verifies, etc).
+//
+// v8-native: `composeFile` retained for transitional reads of legacy
+// state directories (compose-mode upgrades), but no new compose files
+// are generated. `pidFile` and `logFile` are written by the host-spawned
+// engine (now `crosstalk daemon dispatch`) so `crosstalk server status`
+// and `crosstalk server stop` have a single source of truth without
+// querying docker.
 export function storagePaths(name, mode = storageMode()) {
   const base = resolveBase(mode);
   const root = join(base, name);
+  const state = join(root, 'crosstalk-state');
   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'),
+    crosstalkState: state,
+    composeFile:    join(root, 'docker-compose.yml'),  // legacy; not generated by v8
     portFile:       join(root, 'api-port'),
+    pidFile:        join(state, 'crosstalk.pid'),
+    logFile:        join(state, 'crosstalk.log'),
   };
 }
 
-// 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.
+// Transport name from --containername (preferred: --name in v8) flag,
+// defaulting to `crosstalk`. The flag is still --containername for now
+// to keep operator muscle memory + scripted invocations working through
+// the v7→v8 transition. Validates the name is sane 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;
@@ -139,30 +194,42 @@ export function isInitialized(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.
+// True if the crosstalk engine is running for this transport. Source of truth:
+// the PID file in crosstalk-state/. PID is verified alive with kill(0)
+// (no signal sent, just an EPERM/ESRCH probe). Stale PID files (e.g.,
+// after an unclean shutdown) are treated as not-running and the file is
+// best-effort removed.
+//
+// v8-native: replaces the docker-ps query. The legacy isRunning that
+// shelled out to docker for v7 lifecycle has been removed; if you find
+// a caller that still expects container semantics, it's a leftover from
+// the docker era and should be migrated to PID semantics.
 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);
+  const paths = storagePaths(name);
+  if (!existsSync(paths.pidFile)) return false;
+  let pid;
+  try { pid = Number(readFileSync(paths.pidFile, 'utf-8').trim()); }
+  catch { return false; }
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0); // no-op signal; throws if not alive / not ours
+    return true;
+  } catch {
+    // Stale PID file — sweep it so subsequent start doesn't get confused.
+    try { writeFileSync(paths.pidFile, ''); } catch { /* best effort */ }
+    return false;
+  }
 }
 
-// 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);
+/** Read the recorded PID for a running transport, or undefined. */
+export function runningPid(name) {
+  const paths = storagePaths(name);
+  if (!existsSync(paths.pidFile)) return undefined;
+  let pid;
+  try { pid = Number(readFileSync(paths.pidFile, 'utf-8').trim()); }
+  catch { return undefined; }
+  if (!Number.isInteger(pid) || pid <= 0) return undefined;
+  try { process.kill(pid, 0); return pid; } catch { return undefined; }
 }
 
 // Look up the resolved name+paths from argv, validate that init has run,
@@ -183,7 +250,7 @@ export function requireInitialized(argv) {
   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`,
+      `  Run 'crosstalk transport init${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}' to set one up.\n`,
     );
     process.exit(2);
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cordfuse/crosstalk",
-  "version": "7.0.0-alpha.8",
-  "description": "Crosstalk client — host-side CLI that talks to the crosstalkd daemon running inside the crosstalk-server container.",
+  "version": "7.0.0-beta.1",
+  "description": "Crosstalk — agent-agnostic swarm communication protocol built on git. Operator CLI + daemon in one binary.",
   "type": "module",
   "license": "MIT",
   "homepage": "https://github.com/cordfuse/crosstalk",
@@ -14,10 +14,33 @@
   },
   "files": [
     "bin/",
-    "lib/",
     "commands/",
-    "README.md"
+    "lib/",
+    "src/",
+    "template/",
+    "deploy/",
+    "README.md",
+    "GUIDE-CLI.md",
+    "GUIDE-PROMPTS.md"
   ],
+  "scripts": {
+    "build": "tsc --noEmit",
+    "lint": "tsc --noEmit",
+    "test": "bun test",
+    "prepack": "cp -r transport template",
+    "postpack": "rm -rf template"
+  },
+  "dependencies": {
+    "@types/ws": "^8.18.1",
+    "node-pty": "^1.1.0",
+    "tsx": "^4.20.0",
+    "ws": "^8.21.0",
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  },
   "engines": {
     "node": ">=20"
   },