@cordfuse/crosstalk 7.0.0-alpha.5 → 7.0.0-alpha.6

package/commands/rm.js

@@ -0,0 +1,109 @@
+// crosstalk rm — remove a transport completely.
+//
+// Stops the container if running, removes the container, deletes the
+// entire <base>/<name>/ tree (transport git repo, installed CLIs, auth
+// state, dispatcher state, compose file, port file). Confirmation
+// prompt by default; --force / -f to skip for scripted use.
+//
+// Cannot undo. All message history is lost.
+
+import { existsSync, rmSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { createInterface } from 'readline';
+import { has } from '../lib/argv.js';
+import {
+  parseContainerName,
+  storagePaths,
+  isInitialized,
+  isRunning,
+  containerExists,
+  DEFAULT_CONTAINER_NAME,
+} from '../lib/resolve.js';
+
+function usage(exit = 0) {
+  const w = exit === 0 ? process.stdout : process.stderr;
+  w.write(
+`Usage: crosstalk rm [--containername <name>] [--force]
+
+Stops and removes the engine container, then deletes the entire
+storage tree under <base>/<name>/. Includes the transport git repo
+(all message history), installed agent CLIs + auth tokens, and
+dispatcher state. CANNOT BE UNDONE.
+
+Options:
+  --containername <name>   Container to remove (default: 'crosstalk').
+  --force, -f              Skip the confirmation prompt.
+`,
+  );
+  process.exit(exit);
+}
+
+function confirm(promptText) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(promptText, (ans) => {
+      rl.close();
+      const yes = /^y(es)?$/i.test(ans.trim());
+      resolve(yes);
+    });
+  });
+}
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) usage(0);
+
+  let name;
+  try {
+    name = parseContainerName(argv);
+  } catch (err) {
+    process.stderr.write(`crosstalk rm: ${err.message}\n`);
+    return 1;
+  }
+
+  const paths = storagePaths(name);
+  const haveStorage = isInitialized(name) || existsSync(paths.storageRoot);
+  const haveContainer = containerExists(name);
+
+  if (!haveStorage && !haveContainer) {
+    process.stderr.write(`crosstalk rm: transport '${name}' not found.\n`);
+    return 1;
+  }
+
+  if (!has(argv, '--force') && !has(argv, '-f')) {
+    process.stderr.write(
+      `Remove '${name}'?\n` +
+      `  This deletes:\n` +
+      `    - transport git repo at ${paths.transportDir}\n` +
+      `      (all message history, channels, replies)\n` +
+      `    - installed agent CLIs + auth tokens (claude, codex, ...)\n` +
+      `    - dispatcher state (cursor, heartbeat, errors.log)\n` +
+      `  Cannot undo.\n`,
+    );
+    const ok = await confirm('[y/N]: ');
+    if (!ok) {
+      process.stderr.write('crosstalk rm: cancelled.\n');
+      return 1;
+    }
+  }
+
+  // Stop + remove the container (best-effort).
+  if (isRunning(name) && existsSync(paths.composeFile)) {
+    spawnSync('docker', ['compose', '-f', paths.composeFile, 'down'], { stdio: 'inherit' });
+  } else if (haveContainer) {
+    spawnSync('docker', ['rm', '-f', name], { stdio: 'ignore' });
+  }
+
+  // Wipe storage.
+  try {
+    rmSync(paths.storageRoot, { recursive: true, force: true });
+  } catch (err) {
+    process.stderr.write(
+      `crosstalk rm: failed to remove ${paths.storageRoot} — ${err.message}\n` +
+      `  (container is removed, but storage cleanup needs intervention)\n`,
+    );
+    return 1;
+  }
+
+  process.stdout.write(`Removed '${name}'.\n`);
+  return 0;
+}

package/commands/run.js

@@ -8,11 +8,11 @@
 //                 [--new] <file|->
 
 import { readFileSync, existsSync, statSync } from 'fs';
-import { api } from '../lib/api-client.js';
+import { apiFor } from '../lib/api-client.js';
 import { reportAndExit } from '../lib/errors.js';
 import { flag, has } from '../lib/argv.js';
 
-const FLAGS_WITH_VALUE = new Set(['--type', '--to', '--as', '--fanout', '--channel', '--from']);
+const FLAGS_WITH_VALUE = new Set(['--type', '--to', '--as', '--fanout', '--channel', '--from', '--containername', '-c']);
 
 function usage(exit = 0) {
   const w = exit === 0 ? process.stdout : process.stderr;
@@ -52,6 +52,7 @@ function resolveBody(arg) {
 export async function run(argv) {
   if (has(argv, '--help') || has(argv, '-h')) usage(0);
 
+  const api = apiFor(argv);
   const type = flag(argv, '--type');
   if (type !== 'primitive' && type !== 'workflow') usage(1);
 
@@ -60,7 +61,7 @@ export async function run(argv) {
   let bodyArg;
   for (let i = argv.length - 1; i >= 0; i--) {
     const a = argv[i];
-    if (a.startsWith('--')) break;
+    if (a.startsWith('-')) break;
     // Make sure we're not the value of a flag like `--to <value>`
     const prev = argv[i - 1];
     if (prev && FLAGS_WITH_VALUE.has(prev)) continue;

package/commands/status.js

@@ -1,9 +1,16 @@
 // crosstalk status — mirror of crosstalkd status output, fetched via API.
+//
+// alpha.6: also prints the host path of the transport git repo as an
+// escape hatch for operators who want to poke around with raw git.
 
-import { api } from '../lib/api-client.js';
+import { apiFor } from '../lib/api-client.js';
 import { reportAndExit } from '../lib/errors.js';
+import { requireInitialized } from '../lib/resolve.js';
+
+export async function run(argv) {
+  const { name, paths } = requireInitialized(argv);
+  const api = apiFor(argv);
 
-export async function run(_argv) {
   let s;
   try {
     s = await api.get('/status');
@@ -11,25 +18,23 @@ export async function run(_argv) {
     reportAndExit(err, 'crosstalk status');
   }
 
-  process.stdout.write(`Crosstalk transport: ${s.transport_root}\n`);
+  process.stdout.write(`Container:           ${name}\n`);
+  process.stdout.write(`Transport host path: ${paths.transportDir}\n`);
   process.stdout.write(`Engine alias:        ${s.alias}\n`);
   process.stdout.write(`Engine version:      ${s.version}\n`);
   process.stdout.write('\n');
 
   process.stdout.write(`Claimed models: ${s.claimed_models.length}\n`);
   if (s.claimed_models.length === 0) {
-    // Two failure shapes look the same in claimed_models=0: (a) no CLIs
-    // installed at all, (b) CLIs installed but data/models.yaml has no
-    // entries referencing them. Ask /agents/installed to distinguish so
-    // the operator gets a directly-actionable hint.
     let installed = null;
     try {
       const r = await api.get('/agents/installed');
       installed = r.installed;
     } catch { /* ignore — fall back to generic message */ }
     if (installed && installed.length > 0) {
+      const verb = installed.length === 1 ? 'references it' : 'references them';
       process.stdout.write(
-        `  (${installed.join(', ')} installed in the container but no data/models.yaml entry references them — add one to claim)\n`,
+        `  (${installed.join(', ')} installed in the container but no data/models.yaml entry ${verb} — add one to claim)\n`,
       );
     } else {
       process.stdout.write('  (no model CLIs found inside the container — install one via `crosstalk chat --shell` and add an entry to data/models.yaml)\n');
@@ -56,9 +61,9 @@ export async function run(_argv) {
 
   process.stdout.write(`Channels: ${s.channels.length}\n`);
   for (const ch of s.channels) {
-    const name = ch.name ?? '(unnamed)';
+    const chName = ch.name ?? '(unnamed)';
     const parentSuffix = ch.parent ? ` [child of ${ch.parent.slice(0, 8)}]` : '';
-    process.stdout.write(`  ${ch.uuid.slice(0, 8)}... — ${name}${parentSuffix}\n`);
+    process.stdout.write(`  ${ch.uuid.slice(0, 8)}... — ${chName}${parentSuffix}\n`);
   }
   process.stdout.write('\n');
 

package/commands/up.js

@@ -1,140 +1,74 @@
-// crosstalk up — bring up the engine container for this transport.
+// crosstalk up — bring up the engine container for a transport.
 //
-// First-time use: generates docker-compose.yml in the transport root from
-// a template (operator can edit freely, subsequent `up`s won't clobber).
-// The compose file bind-mounts the transport root as the engine's working
-// tree so git operations work both ways — engine sees operator's local
-// commits and configured remotes immediately, operator sees engine
-// commits (replies, cursor advances) immediately.
+// alpha.6: no cwd magic. Resolves container by --containername flag
+// (default 'crosstalk') and operates against <base>/<name>/.
 //
-// Subsequent runs: just shell out to `docker compose up -d`.
+// 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, mkdirSync, appendFileSync, readFileSync } from 'fs';
+import { writeFileSync, existsSync, readFileSync } from 'fs';
 import { spawnSync } from 'child_process';
-import { join } from 'path';
-import { homedir } from 'os';
-import { requireTransportRoot, transportName, composeFile } from '../lib/transport.js';
 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.5';
-const DEFAULT_API_PORT = Number(process.env.CROSSTALK_API_PORT) || 7000;
-const STORAGE_MODE = (process.env.CROSSTALK_STORAGE_MODE ?? 'user').toLowerCase();
+  ?? 'ghcr.io/cordfuse/crosstalk-server:7.0.0-alpha.6';
 
 function usage(exit = 0) {
   const w = exit === 0 ? process.stdout : process.stderr;
   w.write(
-`Usage: crosstalk up
+`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.
 
-Brings up the engine container for the transport in the current directory
-(or any ancestor containing CROSSTALK-VERSION). First-time use generates
-docker-compose.yml in the transport root.
+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         Image to pin (default: bundled GHCR tag)
-  CROSSTALK_API_PORT      Host port to map (default: 7000)
-  CROSSTALK_ALIAS         Dispatcher's machine identity in the bus
-  CROSSTALK_STORAGE_MODE  user (default) | system
-                          Where bind-mounted crosstalk-root +
-                          crosstalk-state live on the host. 'system'
-                          uses paths under /var/lib (Linux) / /Library
-                          (macOS) / C:\\ProgramData (Windows) — requires
-                          sudo/UAC and (on macOS) Docker Desktop file-
-                          sharing allowlist. 'user' uses paths under
-                          the operator's home directory with no
-                          escalation.
+  CROSSTALK_IMAGE         Override the engine image
+  CROSSTALK_ALIAS         Override the engine's machine identity
+                          (defaults to the container name)
 `,
   );
   process.exit(exit);
 }
 
-// Resolve the host directories that back the container's /crosstalk-root
-// (operator-installed CLIs + auth) and /var/lib/crosstalk-state
-// (dispatcher state) bind mounts.
-//
-// User-mode (default) keeps everything under the operator's home so no
-// sudo / UAC / Docker Desktop file-sharing allowlist gymnastics are
-// needed. System-mode is for headless production-style deployments
-// where multiple operators share a machine and a service user manages
-// the daemon.
-//
-// Host-side dir names use the same `crosstalk-` prefix as the container
-// paths so things stay identifiable wherever they surface (backup tools,
-// file managers, support-email screenshots).
-function resolveStoragePaths(transportName, mode) {
-  const platform = process.platform;
-  // Per-OS base directories.
-  const bases = (platform === 'darwin')
-    ? {
-        user:   join(homedir(), 'Library', 'Application Support', 'crosstalk'),
-        system: '/Library/Application Support/crosstalk',
-      }
-    : (platform === 'win32')
-    ? {
-        // %LOCALAPPDATA% should always be set on supported Win versions;
-        // fall back to ~/AppData/Local if it isn't.
-        user:   process.env['LOCALAPPDATA']
-                  ? join(process.env['LOCALAPPDATA'], 'crosstalk')
-                  : join(homedir(), 'AppData', 'Local', 'crosstalk'),
-        system: 'C:\\ProgramData\\crosstalk',
-      }
-    : /* linux + other unix */ {
-        // Honor XDG_DATA_HOME silently (no docs surface; the 99% of
-        // operators who haven't set it get ~/.local/share/crosstalk
-        // either way).
-        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 up: CROSSTALK_STORAGE_MODE='${mode}' invalid — must be 'user' or 'system'.`,
-    );
-  }
-  const base = bases[mode];
-  const transportRoot = join(base, transportName);
-  return {
-    crosstalkRoot:  join(transportRoot, 'crosstalk-root'),
-    crosstalkState: join(transportRoot, 'crosstalk-state'),
-    mode,
-  };
-}
-
-function renderCompose({ name, image, apiPort, alias, uid, gid, crosstalkRootHost, crosstalkStateHost, storageMode }) {
-  // Entrypoint runs as root for setup (npm prefix, SSH key import). It
-  // then adjusts a 'crosstalkd' user to match CROSSTALK_UID/GID
-  // (operator's host UID), chowns the bind-mounted transport, state
-  // dir, AND /crosstalk-root to that user, then drops via setpriv before
-  // exec'ing the dispatcher. Net effect: bind-mount files written by
-  // the engine are operator-owned on the host, so \`git remote add\`
-  // and \`rm -rf\` from the host both work without sudo.
-  return `# Generated by \`crosstalk up\`. Safe to edit; subsequent \`up\`s
-# only regenerate when this file is missing. Compose config is machine-
-# local — kept out of git via .gitignore by default.
-#
-# Storage mode: ${storageMode}
-# crosstalk-root  (container /crosstalk-root)              → ${crosstalkRootHost}
-# crosstalk-state (container /var/lib/crosstalk-state)     → ${crosstalkStateHost}
-# transport       (container /var/lib/crosstalk-transport) → \${PWD} (bind to this directory)
+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: crosstalk-${name}
+    container_name: ${name}
     restart: unless-stopped
+    labels:
+      ${CROSSTALK_LABEL.replace('=', ': "')}"
     ports:
       - "127.0.0.1:${apiPort}:7000"
     volumes:
-      # Transport bind-mount: \`git remote add\` from the host is visible
-      # to the engine on the next tick. No clone-on-startup needed.
-      - .:/var/lib/crosstalk-transport
-      # Operator-installed agent CLIs (claude, codex, agy, ...) + auth
-      # state. Chowned to operator UID at entrypoint so host-side
-      # \`rm -rf\` works without sudo.
-      - ${crosstalkRootHost}:/crosstalk-root
-      # Dispatcher's machine-local state: cursor, heartbeat, errors.log,
-      # pidfile, wake.signal. Operator-UID-owned (chowned by entrypoint).
-      - ${crosstalkStateHost}:/var/lib/crosstalk-state
+      - ${paths.transportDir}:/var/lib/crosstalk-transport
+      - ${paths.crosstalkRoot}:/crosstalk-root
+      - ${paths.crosstalkState}:/var/lib/crosstalk-state
     environment:
       CROSSTALK_ALIAS: ${alias}
       CROSSTALK_UID: "${uid}"
@@ -145,73 +79,49 @@ services:
 `;
 }
 
-function ensureGitignored(transportRoot) {
-  const path = join(transportRoot, '.gitignore');
-  const entry = 'docker-compose.yml\n';
-  if (!existsSync(path)) {
-    writeFileSync(path, entry);
-    return;
-  }
-  const current = readFileSync(path, 'utf-8');
-  if (!current.split('\n').includes('docker-compose.yml')) {
-    appendFileSync(path, (current.endsWith('\n') ? '' : '\n') + entry);
-  }
-}
-
 export async function run(argv) {
   if (has(argv, '--help') || has(argv, '-h')) usage(0);
 
-  const root = requireTransportRoot();
-  const composeYml = composeFile(root);
-  const generated = !existsSync(composeYml);
+  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 ?? process.env.HOSTNAME ?? transportName(root);
+    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;
-    let storage;
-    try {
-      storage = resolveStoragePaths(transportName(root), STORAGE_MODE);
-    } catch (err) {
-      process.stderr.write(`${err.message}\n`);
-      return 1;
-    }
-    // Pre-create the host bind-mount directories. Docker would auto-
-    // create them as root-owned otherwise, which would break the
-    // operator-UID chown step inside the container.
-    try {
-      mkdirSync(storage.crosstalkRoot,  { recursive: true });
-      mkdirSync(storage.crosstalkState, { recursive: true });
-    } catch (err) {
-      process.stderr.write(
-        `crosstalk up: failed to create storage directories — ${err.message}\n`,
-      );
-      if (storage.mode === 'system') {
-        process.stderr.write(
-          `  System-mode storage requires write access to ${storage.crosstalkRoot}'s parent.\n` +
-          `  Try: sudo mkdir -p ${storage.crosstalkRoot} ${storage.crosstalkState} && sudo chown -R \$USER ${storage.crosstalkRoot} ${storage.crosstalkState}\n`,
-        );
-      }
-      return 1;
-    }
-    const content = renderCompose({
-      name: transportName(root),
-      image: DEFAULT_IMAGE,
-      apiPort: DEFAULT_API_PORT,
-      alias,
-      uid,
-      gid,
-      crosstalkRootHost:  storage.crosstalkRoot,
-      crosstalkStateHost: storage.crosstalkState,
-      storageMode: storage.mode,
-    });
-    writeFileSync(composeYml, content);
-    ensureGitignored(root);
-    process.stdout.write(`Generated ${composeYml} (storage: ${storage.mode})\n`);
+    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', composeYml, 'up', '-d'], {
-    cwd: root,
+  const r = spawnSync('docker', ['compose', '-f', paths.composeFile, 'up', '-d'], {
     stdio: 'inherit',
   });
   if (r.status !== 0) {
@@ -219,7 +129,7 @@ export async function run(argv) {
     return r.status ?? 1;
   }
   process.stdout.write(
-    `\nEngine starting. Check status with 'crosstalk status' (give it ~5s to settle).\n`,
+    `\n'${name}' starting. Check with 'crosstalk status${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}' (give it ~5s).\n`,
   );
   return 0;
 }

package/commands/version.js

@@ -7,14 +7,15 @@
 import { readFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
-import { api, ConnectError } from '../lib/api-client.js';
+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) {
+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.

package/lib/api-client.js

@@ -1,26 +1,27 @@
 // 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
-// at the same port. Client connects to http://127.0.0.1:<port>/<path>.
+// 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 (in order):
-//   1. --port <n> CLI flag (handled by individual commands)
-//   2. CROSSTALK_API_PORT env var
-//   3. Default 7000
+// 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: the engine binds 127.0.0.1 only and there's no token. Same
-// model as ollama / postgres-on-localhost.
+// 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 it to the client's package.json version on each
-// call and emit one warning per process if they don't match. Pre-1.0
-// client and engine ship in lockstep; mismatches usually mean the
-// operator upgraded one without the other.
+// 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 {
@@ -44,12 +45,13 @@ function checkSkew(engineVersion) {
   );
 }
 
-export const DEFAULT_API_PORT = 7000;
+export { DEFAULT_API_PORT };
 
-export function resolvePort(explicit) {
-  if (typeof explicit === 'number' && Number.isInteger(explicit)) return explicit;
+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;
 }
 
@@ -91,7 +93,7 @@ export class ConnectError extends Error {
 }
 
 async function call(method, path, body, opts = {}) {
-  const port = resolvePort(opts.port);
+  const port = resolvePort(opts);
   const init = {
     method,
     headers: body ? { 'Content-Type': 'application/json' } : undefined,
@@ -107,6 +109,23 @@ async function call(method, path, body, opts = {}) {
   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.
+export function apiFor(argv) {
+  const name = parseContainerName(argv);
+  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),

package/lib/argv.js

@@ -12,13 +12,15 @@ export function has(argv, name) {
   return argv.includes(name);
 }
 
-// All positional (non-flag) args, skipping flag values.
+// 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 (a.startsWith('-')) {
       if (valueFlags.has(a)) i++;
       continue;
     }