@cordfuse/crosstalk 7.0.0-alpha.1 → 7.0.0-alpha.11

package/commands/init.js

@@ -1,42 +1,73 @@
-// crosstalk init <dir> — scaffold a new transport via docker.
+// crosstalk init — scaffold a transport into <base>/<name>/.
 //
-// Doesn't go through the engine HTTP API — there's no running engine
-// at init time. Instead, runs the engine in a one-shot container with
-// a bind-mount of the target directory, and lets crosstalkd's init
-// subcommand write the template files directly.
+// alpha.7 rewrite: phased + idempotent. Each phase is independent and
+// safe to re-run; re-init detects missing markers and repairs them.
+// Mac caught bug A in alpha.6 where the api-port file was written at
+// the end of the pipeline, so any disruption (image pull, git failure)
+// left storage existing but unstartable — and re-init silently
+// no-op-ed instead of fixing it.
 //
-//   docker run --rm \
-//     -v "$(realpath <dir>):/init-target" \
-//     --user "$(id -u):$(id -g)" \
-//     <image> \
-//     crosstalkd init /init-target
+// Phases:
+//   1. Storage layout — mkdir subdirs + write api-port. Pure FS, fast,
+//      runs first so the resolver-visible marker exists before anything
+//      else can go wrong.
+//   2. Transport scaffold — `crosstalkd init` in a one-shot container.
+//      Skipped if transport/.git already exists. stdout/stderr captured
+//      (mac's bug B — in-container scaffold output was leaking).
+//   3. Git init + initial commit. Skipped if .git exists.
+//   4. Remote setup if --remote given (errors if a different origin
+//      is already set; idempotent on same-value).
+//   5. Summary.
 //
-// The --user flag is critical: without it, the template files would
-// land owned by root (the container's user). Setting it to the
-// operator's UID/GID keeps file ownership sane.
+// Each phase reports created/skipped/repaired so operators can tell
+// what just happened.
 
-import { mkdirSync, existsSync } from 'fs';
-import { resolve } from 'path';
+import { mkdirSync, existsSync, writeFileSync, readFileSync } from 'fs';
 import { spawnSync } from 'child_process';
-import { has, positionals } from '../lib/argv.js';
+import { join } from 'path';
+import { has, flag } from '../lib/argv.js';
+import {
+  parseContainerName,
+  storagePaths,
+  pickFreePort,
+  DEFAULT_CONTAINER_NAME,
+} from '../lib/resolve.js';
 
 const DEFAULT_IMAGE = process.env.CROSSTALK_IMAGE
-  ?? 'ghcr.io/cordfuse/crosstalk-server:7.0.0-alpha.1';
+  ?? '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 init <dir>        # scaffold a new transport at <dir>
+  crosstalk init [--containername <name>] [--remote <url>]
 
-  Image:  ${DEFAULT_IMAGE}
-  Override:  CROSSTALK_IMAGE=<image-tag> crosstalk init <dir>
+Creates a new transport on this machine, or repairs an existing
+incomplete one. Idempotent — re-running fills in any missing markers
+without disturbing existing state.
 
-  The image must be pullable (or already present locally). For local dev
-  before the GHCR publish pipeline ships, build the image first:
-    docker build -t crosstalk-server:7.0.0-alpha.1 -f server/Dockerfile .
-  Then run:
-    CROSSTALK_IMAGE=crosstalk-server:7.0.0-alpha.1 crosstalk init mytransport
+The transport git repo lives at <base>/<name>/transport/ where <base> is:
+  Linux:   $XDG_DATA_HOME/crosstalk/   (or ~/.local/share/crosstalk/)
+  macOS:   ~/Library/Application Support/crosstalk/
+  Windows: %LOCALAPPDATA%\\crosstalk\\
+
+Set CROSSTALK_STORAGE_MODE=system to use the system-wide path (sudo/UAC
+required; intended for headless multi-operator hosts).
+
+Options:
+  --containername <name>   Container name (default: 'crosstalk'). Must be
+                           lowercase alphanumeric + ._- (no leading . or -).
+                           One default + N named containers per machine.
+  --remote <url>           Set git upstream. If a different remote is
+                           already set, errors instead of overwriting.
+  --image <tag>            Override the engine image (default: bundled
+                           GHCR tag; or CROSSTALK_IMAGE env).
+  -c <name>                Shorthand for --containername.
+
+Examples:
+  crosstalk init                                   # default container
+  crosstalk init --containername uat               # second container
+  crosstalk init --remote git\\@github.com:me/t.git # with upstream
 `,
   );
   process.exit(exit);
@@ -44,62 +75,169 @@ function usage(exit = 0) {
 
 export async function run(argv) {
   if (has(argv, '--help') || has(argv, '-h')) usage(0);
-  const pos = positionals(argv, []);
-  if (pos.length === 0) usage(1);
-
-  const target = resolve(pos[0]);
-  if (!existsSync(target)) mkdirSync(target, { recursive: true });
-
-  // Resolve uid/gid via process.getuid() — POSIX only. On Windows the
-  // --user flag is omitted; Docker Desktop handles ownership differently.
-  const uid = typeof process.getuid === 'function' ? process.getuid() : null;
-  const gid = typeof process.getgid === 'function' ? process.getgid() : null;
-  const userArgs = (uid != null && gid != null) ? ['--user', `${uid}:${gid}`] : [];
-
-  // --entrypoint crosstalkd overrides the image's default ENTRYPOINT
-  // (which is the dispatcher entrypoint.sh requiring TRANSPORT_GIT_URL).
-  // For init we want to call crosstalkd directly with no env requirements.
-  const args = [
-    'run', '--rm',
-    '-v', `${target}:/init-target`,
-    ...userArgs,
-    '--entrypoint', 'crosstalkd',
-    DEFAULT_IMAGE,
-    'init', '/init-target',
-  ];
 
-  const r = spawnSync('docker', args, { stdio: 'inherit' });
-  if (r.status !== 0) {
-    process.stderr.write(`crosstalk init: docker run exited ${r.status}\n`);
-    process.stderr.write(`  command was: docker ${args.join(' ')}\n`);
-    return r.status ?? 1;
+  let name;
+  try {
+    name = parseContainerName(argv);
+  } catch (err) {
+    process.stderr.write(`crosstalk init: ${err.message}\n`);
+    return 1;
+  }
+
+  const remote = flag(argv, '--remote');
+  const image = flag(argv, '--image') ?? DEFAULT_IMAGE;
+  const paths = storagePaths(name);
+  const report = [];
+
+  // ── Phase 1: Storage layout ────────────────────────────────────────
+  // mkdir is idempotent (recursive: true). Write api-port if absent.
+  // This is the load-bearing fix for bug A — port file lands FIRST,
+  // before anything else can go wrong (image pull, git init, etc.).
+  try {
+    mkdirSync(paths.transportDir,   { recursive: true });
+    mkdirSync(paths.crosstalkRoot,  { recursive: true });
+    mkdirSync(paths.crosstalkState, { recursive: true });
+  } catch (err) {
+    process.stderr.write(
+      `crosstalk init: failed to create storage at ${paths.storageRoot} — ${err.message}\n`,
+    );
+    if (paths.mode === 'system') {
+      process.stderr.write(
+        `  System-mode storage requires write access to ${paths.base}.\n` +
+        `  Try: sudo mkdir -p ${paths.storageRoot} && sudo chown -R $USER ${paths.storageRoot}\n`,
+      );
+    }
+    return 1;
+  }
+
+  let port;
+  if (existsSync(paths.portFile)) {
+    const v = Number(readFileSync(paths.portFile, 'utf-8').trim());
+    if (Number.isInteger(v) && v > 0 && v < 65536) {
+      port = v;
+      report.push(`  api port:   ${port} (existing)`);
+    }
+  }
+  if (!port) {
+    try {
+      port = pickFreePort(name);
+      writeFileSync(paths.portFile, `${port}\n`);
+      report.push(`  api port:   ${port} (allocated)`);
+    } catch (err) {
+      process.stderr.write(`crosstalk init: port allocation failed — ${err.message}\n`);
+      return 1;
+    }
+  }
+
+  // ── Phase 2: Transport scaffold ────────────────────────────────────
+  // The template-scaffold check is "does CROSSTALK-VERSION exist?" NOT
+  // ".git exists" — git init is a separate phase, and the engine refuses
+  // to re-scaffold over an existing CROSSTALK-VERSION (without --force).
+  // Decoupling means a disrupted init (template written, git init never
+  // ran) re-enters Phase 3 cleanly on re-run.
+  const transportGitDir      = join(paths.transportDir, '.git');
+  const crosstalkVersionFile = join(paths.transportDir, 'CROSSTALK-VERSION');
+  if (!existsSync(crosstalkVersionFile)) {
+    const uid = typeof process.getuid === 'function' ? process.getuid() : null;
+    const gid = typeof process.getgid === 'function' ? process.getgid() : null;
+    const userArgs = (uid != null && gid != null) ? ['--user', `${uid}:${gid}`] : [];
+
+    const dockerArgs = [
+      'run', '--rm',
+      '-v', `${paths.transportDir}:/init-target`,
+      ...userArgs,
+      '--entrypoint', 'crosstalkd',
+      image,
+      'init', '/init-target',
+    ];
+
+    // Bug B fix: don't inherit stdio — the engine prints next-steps that
+    // confuse operators ("Transport initialized at /init-target" with
+    // container-internal paths). Capture, show only on failure.
+    const initRun = spawnSync('docker', dockerArgs, { stdio: 'pipe' });
+    if (initRun.status !== 0) {
+      const stderr = initRun.stderr?.toString() ?? '';
+      const stdout = initRun.stdout?.toString() ?? '';
+      process.stderr.write(`crosstalk init: docker run exited ${initRun.status}\n`);
+      if (stderr.trim()) process.stderr.write(`  stderr: ${stderr.trim()}\n`);
+      if (stdout.trim()) process.stderr.write(`  stdout: ${stdout.trim()}\n`);
+      process.stderr.write(`  command was: docker ${dockerArgs.join(' ')}\n`);
+      return initRun.status ?? 1;
+    }
+    report.push(`  template:   scaffolded via ${image}`);
+  } else {
+    report.push(`  template:   present (skipped scaffold)`);
+  }
+
+  // ── Phase 3: Git init + initial commit ─────────────────────────────
+  if (!existsSync(crosstalkVersionFile)) {
+    // Engine init succeeded but didn't leave files. Bail clearly — we
+    // won't proceed to git init on an empty dir.
+    process.stderr.write(
+      `crosstalk init: transport template missing at ${paths.transportDir}\n` +
+      `  Engine init didn't write template files. Try 'crosstalk rm' then re-init.\n`,
+    );
+    return 1;
   }
 
-  // Auto git init + initial commit so the transport is ready for
-  // `crosstalk up` immediately. Engine expects a git repo (cursor +
-  // commit operations on every tick). Doing this on the host so the
-  // commit author uses the operator's local git config — not the
-  // container's default.
-  //
-  // Best-effort: if any git step fails, print a warning but don't fail
-  // the init (operator can complete the steps manually).
   const gitSteps = [
     ['init', '--quiet', '--initial-branch=main'],
     ['add', '-A'],
     ['commit', '--quiet', '-m', 'initial transport'],
   ];
+  let gitOk = true;
   for (const args of gitSteps) {
-    const gr = spawnSync('git', args, { cwd: target, stdio: 'pipe' });
+    const gr = spawnSync('git', args, { cwd: paths.transportDir, stdio: 'pipe' });
     if (gr.status !== 0) {
-      const stderr = gr.stderr?.toString().trim() ?? '';
+      // 'git init' on existing repo is fine (it re-runs idempotently);
+      // 'add -A' is also idempotent. 'commit' fails when there's
+      // nothing to commit — that means a previous run already committed.
+      // Only the first call (git init) is load-bearing; the rest are
+      // best-effort to populate the initial state.
+      gitOk = false;
+      break;
+    }
+  }
+  report.push(gitOk ? `  git:        initialized + committed` : `  git:        already present (skipped)`);
+
+  // ── Phase 4: Remote setup ──────────────────────────────────────────
+  if (remote) {
+    const cur = spawnSync('git', ['remote', 'get-url', 'origin'], {
+      cwd: paths.transportDir,
+      stdio: 'pipe',
+    });
+    const currentUrl = cur.status === 0 ? cur.stdout.toString().trim() : null;
+    if (!currentUrl) {
+      const rr = spawnSync('git', ['remote', 'add', 'origin', remote], {
+        cwd: paths.transportDir,
+        stdio: 'pipe',
+      });
+      if (rr.status !== 0) {
+        process.stderr.write(
+          `crosstalk init: 'git remote add origin ${remote}' failed — ${rr.stderr?.toString().trim()}\n`,
+        );
+      } else {
+        report.push(`  remote:     ${remote} (added)`);
+      }
+    } else if (currentUrl === remote) {
+      report.push(`  remote:     ${remote} (already set)`);
+    } else {
       process.stderr.write(
-        `crosstalk init: \`git ${args.join(' ')}\` failed (transport scaffolded but not committed)\n`,
+        `crosstalk init: remote already set to '${currentUrl}'; refusing to overwrite with '${remote}'.\n` +
+        `  Use 'crosstalk status' to see the transport path; cd there and adjust git config manually if intended.\n`,
       );
-      if (stderr) process.stderr.write(`  ${stderr.split('\n').join('\n  ')}\n`);
-      process.stderr.write(`  Finish manually: cd ${target} && git init && git add -A && git commit -m "initial transport"\n`);
-      return 0;  // not fatal — scaffold succeeded
+      return 1;
     }
   }
-  process.stdout.write(`\nGit initialized; transport is ready for \`crosstalk up\`.\n`);
+
+  // ── Phase 5: Summary ───────────────────────────────────────────────
+  process.stdout.write(
+    `\nTransport '${name}' ready:\n` +
+    `  storage:    ${paths.storageRoot}\n` +
+    `  transport:  ${paths.transportDir}\n` +
+    `  image:      ${image}\n` +
+    report.join('\n') + '\n' +
+    `\nNext: crosstalk up${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}\n`,
+  );
   return 0;
 }

package/commands/logs.js

@@ -1,14 +1,14 @@
-// crosstalk logs — tail the engine container's logs.
+// crosstalk logs — tail a transport's engine logs.
 
 import { existsSync } from 'fs';
 import { spawnSync } from 'child_process';
-import { requireTransportRoot, composeFile } from '../lib/transport.js';
 import { has } from '../lib/argv.js';
+import { requireInitialized } from '../lib/resolve.js';
 
 function usage(exit = 0) {
   const w = exit === 0 ? process.stdout : process.stderr;
   w.write(
-`Usage: crosstalk logs [-f|--follow] [-n <lines>]
+`Usage: crosstalk logs [--containername <name>] [-f|--follow] [-n <lines>]
 
 Streams the engine container's stdout/stderr. -f to follow (Ctrl-C to stop).
 `,
@@ -19,21 +19,19 @@ Streams the engine container's stdout/stderr. -f to follow (Ctrl-C to stop).
 export async function run(argv) {
   if (has(argv, '--help') || has(argv, '-h')) usage(0);
 
-  const root = requireTransportRoot();
-  const composeYml = composeFile(root);
-  if (!existsSync(composeYml)) {
-    process.stderr.write(`crosstalk logs: no docker-compose.yml — run 'crosstalk up' first.\n`);
+  const { name, paths } = requireInitialized(argv);
+  if (!existsSync(paths.composeFile)) {
+    process.stderr.write(`crosstalk logs: '${name}' has no compose file — run 'crosstalk up' first.\n`);
     return 1;
   }
-  const args = ['compose', '-f', composeYml, 'logs'];
+  const args = ['compose', '-f', paths.composeFile, 'logs'];
   if (has(argv, '-f') || has(argv, '--follow')) args.push('--follow');
-  // Pass through tail count if provided.
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '-n' || argv[i] === '--tail') {
       args.push('--tail', argv[i + 1] ?? '100');
       i++;
     }
   }
-  const r = spawnSync('docker', args, { cwd: root, stdio: 'inherit' });
+  const r = spawnSync('docker', args, { stdio: 'inherit' });
   return r.status ?? 1;
 }

package/commands/pull.js

@@ -1,23 +1,21 @@
-// crosstalk pull — refresh the engine image.
+// crosstalk pull — refresh the engine image for a transport.
 
 import { existsSync } from 'fs';
 import { spawnSync } from 'child_process';
-import { requireTransportRoot, composeFile } from '../lib/transport.js';
 import { has } from '../lib/argv.js';
+import { requireInitialized } from '../lib/resolve.js';
 
 export async function run(argv) {
   if (has(argv, '--help') || has(argv, '-h')) {
-    process.stdout.write('Usage: crosstalk pull\n');
+    process.stdout.write('Usage: crosstalk pull [--containername <name>]\n');
     return 0;
   }
-  const root = requireTransportRoot();
-  const composeYml = composeFile(root);
-  if (!existsSync(composeYml)) {
-    process.stderr.write(`crosstalk pull: no docker-compose.yml — run 'crosstalk up' first.\n`);
+  const { name, paths } = requireInitialized(argv);
+  if (!existsSync(paths.composeFile)) {
+    process.stderr.write(`crosstalk pull: '${name}' has no compose file — run 'crosstalk up' first.\n`);
     return 1;
   }
-  const r = spawnSync('docker', ['compose', '-f', composeYml, 'pull'], {
-    cwd: root,
+  const r = spawnSync('docker', ['compose', '-f', paths.composeFile, 'pull'], {
     stdio: 'inherit',
   });
   return r.status ?? 1;

package/commands/replies.js

@@ -3,19 +3,20 @@
 // Exit 0 if all targets have REPLIED or FAILED, exit 2 while any PENDING
 // — agents can poll cheaply in a loop. Mirrors crosstalkd replies.
 
-import { api } from '../lib/api-client.js';
+import { apiFor } from '../lib/api-client.js';
 import { reportAndExit } from '../lib/errors.js';
 import { positionals, has } from '../lib/argv.js';
 
 function usage(exit = 0) {
   const w = exit === 0 ? process.stdout : process.stderr;
-  w.write('Usage: crosstalk replies <relPath> [<relPath>...]\n');
+  w.write('Usage: crosstalk replies [--containername <name>] <relPath> [<relPath>...]\n');
   process.exit(exit);
 }
 
 export async function run(argv) {
   if (has(argv, '--help') || has(argv, '-h')) usage(0);
-  const targets = positionals(argv, []);
+  const api = apiFor(argv);
+  const targets = positionals(argv, ['--containername', '-c']);
   if (targets.length === 0) usage(1);
 
   let resp;

package/commands/restart.js

@@ -1,24 +1,29 @@
-// crosstalk restart — restart the engine container.
+// crosstalk restart — restart a transport's engine container.
+//
+// Uses `compose up -d --force-recreate` (not `compose restart`) so
+// changes to env_file (e.g. tokens added via `crosstalk auth paste`)
+// are picked up. Plain `compose restart` just stops + starts the same
+// container without re-reading config.
 
 import { existsSync } from 'fs';
 import { spawnSync } from 'child_process';
-import { requireTransportRoot, composeFile } from '../lib/transport.js';
 import { has } from '../lib/argv.js';
+import { requireInitialized } from '../lib/resolve.js';
 
 export async function run(argv) {
   if (has(argv, '--help') || has(argv, '-h')) {
-    process.stdout.write('Usage: crosstalk restart\n');
+    process.stdout.write('Usage: crosstalk restart [--containername <name>]\n');
     return 0;
   }
-  const root = requireTransportRoot();
-  const composeYml = composeFile(root);
-  if (!existsSync(composeYml)) {
-    process.stderr.write(`crosstalk restart: no docker-compose.yml — run 'crosstalk up' first.\n`);
+  const { name, paths } = requireInitialized(argv);
+  if (!existsSync(paths.composeFile)) {
+    process.stderr.write(`crosstalk restart: '${name}' has no compose file — run 'crosstalk up' first.\n`);
     return 1;
   }
-  const r = spawnSync('docker', ['compose', '-f', composeYml, 'restart'], {
-    cwd: root,
-    stdio: 'inherit',
-  });
+  const r = spawnSync(
+    'docker',
+    ['compose', '-f', paths.composeFile, 'up', '-d', '--force-recreate'],
+    { stdio: 'inherit' },
+  );
   return r.status ?? 1;
 }

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';
+import { flag, has, positionals } 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,21 +52,15 @@ 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);
 
-  // The body is the last non-flag arg. Walk argv backwards skipping
-  // flag values.
-  let bodyArg;
-  for (let i = argv.length - 1; i >= 0; i--) {
-    const a = argv[i];
-    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;
-    bodyArg = a;
-    break;
-  }
+  // Body is the last positional. positionals() skips flag values so the
+  // body resolves regardless of flag order — `--containername a8 hello`
+  // and `hello --containername a8` both work.
+  const pos = positionals(argv, [...FLAGS_WITH_VALUE]);
+  const bodyArg = pos[pos.length - 1];
 
   const body = resolveBody(bodyArg);
   if (body == null || body.length === 0) {