@volter/world 2.0.0

package/src/cli.ts

@@ -0,0 +1,486 @@
+#!/usr/bin/env node
+// `volter` — the user's command (docs/concepts/worlds.md#the-config-and-the-running-world): a noun, then a
+// verb. `volter world …` acts on the world of the cwd the way git acts on the repository of the
+// cwd; `volter twin <vendor> …` runs one twin on its own; `volter remote …` is the hosted remote.
+// One client of `World`; it adds nothing the SDK does not have.
+import { formatInitReport, resolveCatalog, findInstalledPackage, packCli, serveConsoleFor } from '@volter/world-runtime';
+import { readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { formatLedgerDelta } from '@volter/world-core';
+import { existsSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { platformOrigin, requireToken, storePlatform, storeToken, tokenFor } from './credentials.ts';
+import { parseOriginUrl, World } from './world.ts';
+import { waitForServeShutdown } from './serve-shutdown.ts';
+
+export const HELP = `volter — run your app against a world of twins
+
+world  — the twins your app needs, running together (the world of the current directory)
+  volter world init [--name <world>] [--allow-unknown]   detect the app's vendors, write .volter/world.json
+  volter world up [--sandbox] [--no-seed]                start the twins on this branch (loads the default data the first time)
+  volter world run [--verbose] -- <command...>           run the app or its tests inside the world
+  volter world activate                                  eval "$(volter world activate)": vendor CLIs and curl in this shell reach the twins
+  volter world shell                                     a subshell with the world active
+  volter world init --bare <org>/<world> --twins a,b      a world with no app: a shared world for a team, or one standing in for a vendor
+  volter world serve [--port <p>] [--console-port <c>]   serve this world on a URL under /<org>/<world>/; prints the token and the console (its own origin, port p+1 by default)
+  volter world console [<https://host/org/world>] [--port <p>]  the console on this machine for a World served elsewhere (default: this world's origin); needs @volter/world-console
+  volter world status                                    world, branch, origin, unpushed changes, what is running
+  volter world log [--receipts] [--json]                 every write the app made; --receipts adds each change's receipt
+  volter world diff [--json]                             what changed since the default data (or the last mark)
+  volter world seed                                      load the default data
+  volter world reset                                     back to the default data
+  volter world down [--purge]                            stop the twins (--purge forgets this branch's state)
+  volter world branch [<name>]                           list branches, or make one from here and check it out
+  volter world checkout <name>                           switch branches
+  volter world replay <changeset> --into <branch>        feed a changeset's changes into another branch's twins
+  volter world clock show | set <iso> | advance <N s|m|h|d>   the world's clock: set, not observed
+  volter world clone <url> --token <token> [--admin-token <t>]   connect this world to a remote and fetch its history (the admin token copies the whole tree at once)
+  volter world fetch                                     what the remote observed since the last fetch
+  volter world origin                                    where this world clones from and pushes to
+  volter world changeset [<name>] -m "<message>"         cut the unpushed changes into a reviewable changeset
+  volter world pull [--token <token>]                    fetch, then move this branch onto what came in (git's pull)
+  volter world push [<name>] [--token <token>] [--force] push to the remote, which deploys and answers with receipts
+  volter world rebase [<changeset>]                      rebase this branch onto its moved base, or a changeset onto the moved mirror
+  volter world verify <changeset>                        run the world's checks over a changeset and record the result
+  volter world approve <changeset> --as <principal>      sign a changeset's current hash
+  volter world deploy [<changeset>]                      perform landed changes against each twin's root, by its policy
+
+twin   — one twin: in this world, or on its own
+  volter twin <vendor>                                   the twin's URL, root, deploy policy, whether a credential is sealed
+  volter twin <vendor> root <url> [--deploy auto|gated|hold] [--scope <path>]   the vendor's real account behind this twin (--none clears it)
+  volter twin <vendor> credential                        seal a credential read from stdin beside the world; never readable back
+  volter twin <vendor> refresh                           observe the root now
+  volter twin <vendor> serve [--port <p>] [--read-only]  serve the twin; your SDK talks to it at http://127.0.0.1:<p>
+  volter twin <vendor> mirror [--port <p>]               the twin's UI mirror
+  volter twin <vendor> conformance                       check the twin against the vendor's spec
+
+remote — the worlds this one pushes to and fetches from, by name
+  volter login <platform url> --token <personal token>  sign the CLI into the hosted platform (a personal token from the console)
+  volter remote add <name> <url|path|org/world> [--token <token>]  name a remote; org/world resolves through the platform you logged into
+  volter remote remove <name>                            forget it
+  volter remote list                                     every remote, with its URL and whether a token is stored
+  (the hosting product's serve answers here for one release: volter remote serve)
+
+  --world <dir>    the world root, when the cwd is not inside it
+  --branch <name>  act on that branch instead of the checked-out one
+  --json           machine-readable output where offered
+`;
+
+function flag(args: string[], name: string): boolean { return args.includes(name); }
+function value(args: string[], name: string): string | undefined {
+  const i = args.indexOf(name);
+  return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
+}
+function positionals(args: string[], valueFlags: string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i]!;
+    if (a === '--') break;
+    if (a.startsWith('-')) { if (valueFlags.includes(a)) i += 1; continue; }
+    out.push(a);
+  }
+  return out;
+}
+function afterDashes(args: string[]): string[] { const i = args.indexOf('--'); return i < 0 ? [] : args.slice(i + 1); }
+const VALUE_FLAGS = ['--world', '--branch', '--name', '--token', '--admin-token', '-m', '--message', '--base', '--org', '--vendors', '--into', '--deploy', '--as', '--note', '--port', '--twins', '--host', '--scope', '--refresh', '--at-most', '--at'];
+
+/** A subject as a person names it: an id that already carries its context (`acme/web#1`, `C-ops/ts`) stands alone, with an embedded `<type>:` dropped; a bare id gets its type. */
+function subjectLabel(subject: { type: string; id: string }): string {
+  const id = subject.id.replace(new RegExp(`(^|[#/:])${subject.type}:`), '$1');
+  return /[#/]/.test(id) ? id : `${subject.type}:${id}`;
+}
+function out(text: string): void { process.stdout.write(text.endsWith('\n') ? text : `${text}\n`); }
+function json(value: unknown): void { out(JSON.stringify(value, null, 2)); }
+function when(iso: string): string { return iso.slice(11, 23); }
+
+/** Run another CLI in the foreground and adopt its exit code; a signal to us is a signal to it. */
+async function passthrough(cmd: string[], cwd = process.cwd()): Promise<number> {
+  const child = spawn(cmd[0]!, cmd.slice(1), { cwd, stdio: 'inherit' });
+  const forward = (signal: NodeJS.Signals) => () => { try { child.kill(signal); } catch { /* already gone */ } };
+  for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP'] as const) process.on(signal, forward(signal));
+  return await new Promise<number>((resolve, reject) => { child.once('error', reject); child.once('exit', (code, signal) => resolve(code ?? (signal ? 128 : 1))); });
+}
+/** All of stdin, as text: a synchronous read of fd 0 to EOF — the same on Bun and Node, and it
+ *  holds the process (an async iteration of `process.stdin` here let Bun exit 0 mid-read, the
+ *  credential unsealed and nothing said — found by the deploy-from-a-shared-world page). */
+function stdinText(): string { try { return readFileSync(0, 'utf8'); } catch { return ''; } }
+
+async function worldCommand(verb: string, args: string[]): Promise<void> {
+  const worldDir = value(args, '--world');
+  const pos = positionals(args, VALUE_FLAGS);
+  const asJson = flag(args, '--json');
+
+  if (verb === 'init' && flag(args, '--bare')) {
+    const served = positionals(args, VALUE_FLAGS)[0];
+    if (!served) throw new Error('volter world init --bare <org>/<world> --twins a,b');
+    const twins = (value(args, '--twins') ?? '').split(',').map((t) => t.trim()).filter(Boolean);
+    const { result } = World.initBare(resolve(worldDir ?? process.cwd()), served, twins, { force: flag(args, '--force') });
+    if (asJson) json({ ok: result.ok, plan: result.plan });
+    else out(`bare   ${served}\ntwins  ${twins.join(', ')}\nwrote  .volter/world.json`);
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (verb === 'init') {
+    const app = resolve(worldDir ?? process.cwd());
+    const { result } = World.init(app, { ...(value(args, '--name') ? { name: value(args, '--name')! } : {}), force: flag(args, '--force'), allowUnknown: flag(args, '--allow-unknown') });
+    if (asJson) json({ ok: result.ok, plan: result.plan, coverage: result.coverage, next: result.next });
+    else {
+      const twins = result.plan.vendors.filter((v) => v.service !== null).map((v) => v.vendor).sort();
+      out(`twins  ${twins.join(', ') || '(none)'}\nwrote  ${relative(process.cwd(), result.plan.configPath) || result.plan.configPath}`);
+      out(formatInitReport(result));
+    }
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+
+  if (verb === 'console') {
+    // the console on this machine for a World served elsewhere: the given URL (<origin>/<org>/<world>), else
+    // this world's origin; a URL needs no world here
+    const given = positionals(args, VALUE_FLAGS)[0];
+    const origin = given ? null : World.open({ ...(worldDir ? { root: worldDir } : {}) }).origin();
+    const target = given ?? (origin && /^https?:/.test(origin.url) ? `${origin.url.replace(/\/+$/, '')}/${origin.namespace ?? ''}` : null);
+    if (!target) throw new Error('volter world console <https://host/org/world>: this world has no http(s) origin to open');
+    const port = value(args, '--port');
+    if (port !== undefined && !/^\d{1,5}$/.test(port)) throw new Error(`volter world console: --port ${port} is not a port`);
+    const served = await serveConsoleFor(target, { ...(port !== undefined ? { port: Number(port) } : {}) });
+    out(`console  ${served.url}/-/console/\nworlds   ${served.worlds}  (forwarding to ${new URL(target).origin})\nOpen it and type the World's token.`);
+    await waitForServeShutdown(async () => { for (const s of served.servers) await s.stop(); });
+    process.exit(0);
+  }
+
+  const world = World.open({ ...(worldDir ? { root: worldDir } : {}), ...(value(args, '--branch') ? { name: value(args, '--branch')! } : {}) });
+
+  switch (verb) {
+    case 'up': {
+      const instance = await world.up({ ...(flag(args, '--sandbox') ? { mode: 'sealed' as const } : {}), seed: !flag(args, '--no-seed') });
+      if (asJson) { json(world.status()); return; }
+      const twins = Object.values(instance.services).filter((s) => s.type === 'twin' || s.type === undefined);
+      out(`${world.name}  ${twins.length} twin${twins.length === 1 ? '' : 's'} up${flag(args, '--no-seed') ? '' : ', story loaded'}`);
+      for (const s of Object.values(instance.services)) out(`  ${s.id}: ${s.url ?? '(no listener)'}`);
+      out(`\nRun your app inside it:  volter world run -- <command>\nEnv:                     ${relative(process.cwd(), instance.envFile) || instance.envFile}`);
+      return;
+    }
+    case 'down': {
+      const result = await world.down({ purge: flag(args, '--purge') });
+      out(`Stopped ${result.name}${result.stopped.length ? `: ${result.stopped.join(', ')}` : ''}${result.purged ? ' (state forgotten)' : ''}`);
+      if (result.externalErrors.length) { for (const m of result.externalErrors) process.stderr.write(`${m}\n`); process.exitCode = 1; }
+      return;
+    }
+    case 'activate': { process.stdout.write(world.activateScript()); return; }
+    case 'shell': { process.exitCode = await world.shell(); return; }
+    case 'run': {
+      const command = afterDashes(args);
+      if (command.length === 0) throw new Error('volter world run: give the command after --  (volter world run -- npm test)');
+      process.exitCode = await world.run(command, { verbose: flag(args.slice(0, args.indexOf('--')), '--verbose') });
+      return;
+    }
+    case 'status': {
+      const s = world.status();
+      if (asJson) { json(s); return; }
+      out(`World ${s.world} on branch ${s.branch}: ${s.running ? 'running' : 'stopped'}`);
+      if (s.served) out(`  served:    ${s.served.base} (pid ${s.served.pid}, since ${s.served.startedAt})`);
+      out(`  origin:    ${s.origin ? `${s.origin.url}/${s.origin.namespace}${s.origin.fetchedAt ? ` (fetched ${s.origin.fetchedAt})` : ''}` : 'default data (no remote)'}`);
+      out(`  unpushed:  ${s.unpushed} change${s.unpushed === 1 ? '' : 's'}; changesets: ${s.changesets.pushed}/${s.changesets.total} pushed`);
+      if (s.branches.length > 1) out(`  branches:  ${s.branches.map((b) => (b === s.branch ? `*${b}` : b)).join(' ')}`);
+      for (const [id, svc] of Object.entries(s.services)) out(`  ${id}: ${svc.url ?? '(no listener)'} (${svc.running ? 'running' : 'stopped'})${svc.protocol ? `  protocol ${svc.protocol.major}${svc.protocol.standing === 'current' ? '' : ` (${svc.protocol.standing})`}` : ''}`);
+      return;
+    }
+    case 'log': {
+      const rows = world.log();
+      if (asJson) { json(rows); return; }
+      if (rows.length === 0) { out('(no changes yet)'); return; }
+      const withReceipts = flag(args, '--receipts');
+      for (const r of rows) {
+        // an observed entry is the vendor's history on the root's log: neither pushed nor pushable
+        const v2 = r.operation === 'observed' ? 'observed' : r.landed ? `${r.landed.status}${r.landed.externalId ? ` ${r.landed.externalId}` : ''}${r.landed.reason ? `  ${r.landed.reason}` : ''}` : '';
+        const v1 = r.receipt ? `${r.receipt.status}${r.receipt.externalId ? ` ${r.receipt.externalId}` : ''}${r.changeset ? ` (${r.changeset})` : ''}` : '';
+        const receipt = withReceipts ? `    ${v2 || v1 || 'unpushed'}` : (v1 ? `  → ${v1}` : '');
+        out(`${r.service.padEnd(8)} ${(r.operation ?? r.op).padEnd(22)} ${subjectLabel(r.subject)}${receipt}`);
+      }
+      return;
+    }
+    case 'diff': {
+      const delta = world.diff(value(args, '--base'));
+      if (asJson) { json(delta); return; }
+      const changes = delta.actions.filter((a) => !a.action.subject.type.startsWith('_'));
+      out(`${changes.length} change${changes.length === 1 ? '' : 's'} since ${value(args, '--base') ? delta.base.id : world.diffBase()}`);
+      for (const v of delta.vendors) out(`  ${v.service}: ${v.count} change${v.count === 1 ? '' : 's'}`);
+      return;
+    }
+    case 'seed': {
+      const r = await world.seed();
+      out(`Loaded the default data into ${r.world}: ${Object.entries(r.observed).map(([s, n]) => `${s} ${n}`).join(', ') || 'nothing recorded'}`);
+      if (r.exitCode !== 0) process.exitCode = r.exitCode;
+      return;
+    }
+    case 'reset': {
+      const r = await world.reset();
+      out(`Back to the default data on ${r.world}: ${Object.entries(r.observed).map(([s, n]) => `${s} ${n}`).join(', ') || 'nothing recorded'}`);
+      if (r.exitCode !== 0) process.exitCode = r.exitCode;
+      return;
+    }
+    case 'branch': {
+      const name = pos[0];
+      if (!name) { for (const b of world.branches()) out(`${b === world.name ? '* ' : '  '}${b}`); return; }
+      const atText = value(args, '--at');
+      const at = atText === undefined ? undefined : /^\d{4}-\d\d-\d\d/.test(atText) ? { instant: atText } : (() => {
+        const positions: Record<string, number> = {}; const views: Record<string, string> = {};
+        for (const p of atText.split(',')) {
+          const match = /^([^@]+)@(?:([a-f0-9]{64}):)?(\d+)$/.exec(p);
+          if (!match) throw new Error('--at takes an instant, twin@position, or twin@view:position');
+          positions[match[1]!] = Number(match[3]); if (match[2]) views[match[1]!] = match[2];
+        }
+        return { positions, views };
+      })();
+      const made = await world.branch(name, at ? { at } : {});
+      out(`branch  ${made.name}  from ${world.isMain() ? 'main' : world.name}${at ? `  at ${atText}` : ''}`);
+      return;
+    }
+    case 'checkout': {
+      const name = pos[0];
+      if (!name) throw new Error('volter world checkout: which branch?');
+      const to = await world.checkout(name);
+      out(`Switched to branch ${to.name}`);
+      return;
+    }
+    case 'clock': {
+      const [action, arg] = pos;
+      if (action === 'set') { if (!arg) throw new Error('volter world clock set <iso-8601>'); out(world.setClock(arg)); return; }
+      if (action === 'advance') { if (!arg) throw new Error('volter world clock advance <N s|m|h|d>'); out(world.advanceClock(arg)); return; }
+      if (action === undefined || action === 'show') { const c = world.clock(); out(`${c.at}${c.frozen ? '' : ' (wall clock — not set)'}`); return; }
+      throw new Error('volter world clock show | set <iso> | advance <N s|m|h|d>');
+    }
+    case 'replay': {
+      const name = pos[0]; const into = value(args, '--into');
+      if (!name || !into) throw new Error('volter world replay <changeset> --into <branch>');
+      const r = world.replay(name, into);
+      if (asJson) { json(r); return; }
+      out(`Replayed ${name} into ${into}`);
+      return;
+    }
+    case 'origin': {
+      const o = world.origin();
+      if (asJson) { json(o); return; }
+      out(o ? `origin  ${o.url}/${o.namespace}` : 'origin  default data');
+      return;
+    }
+    case 'clone': {
+      if (!pos[0]) throw new Error('volter world clone <url> --token <token>');
+      const outcome = await world.clone(pos[0], { ...(value(args, '--token') ? { token: value(args, '--token')! } : {}), ...(value(args, '--admin-token') ? { adminToken: value(args, '--admin-token')! } : {}) });
+      if (asJson) { json(outcome); return; }
+      const n = Object.values(outcome.appended).reduce((a, b) => a + b, 0);
+      out(`cloned  ${outcome.origin.url}/${outcome.origin.namespace}  ${n} change${n === 1 ? '' : 's'}`);
+      return;
+    }
+    case 'fetch': {
+      const outcome = await world.fetch({ ...(value(args, '--token') ? { token: value(args, '--token')! } : {}) });
+      if (asJson) { json(outcome); return; }
+      const n = Object.values(outcome.appended).reduce((a, b) => a + b, 0);
+      const behind = Object.values(outcome.behind ?? {}).reduce((a, b) => a + b, 0);
+      out(`fetched  origin  ${n} change${n === 1 ? '' : 's'}${behind ? `  (${behind} past this branch's position — \`volter world rebase\` folds them)` : ''}`);
+      return;
+    }
+    case 'pull': {
+      const r = await world.pull({ ...(value(args, '--token') ? { token: value(args, '--token')! } : {}) });
+      if (asJson) { json(r); return; }
+      const n = Object.values(r.fetched.appended).reduce((a, b) => a + b, 0);
+      const conflicts = r.rebased.flatMap((x) => x.conflicts.map((c) => `${x.service} ${c.subject.type}:${c.subject.id} ${c.field} ${c.op}`));
+      out(`pulled  origin  ${n} change${n === 1 ? '' : 's'}  ${r.rebased.map((x) => `${x.service}@${x.to}`).join(' ')}${conflicts.length ? `\n  conflicts:\n  ${conflicts.join('\n  ')}` : ''}`);
+      return;
+    }
+    case 'changeset': {
+      const message = value(args, '-m') ?? value(args, '--message');
+      if (message === undefined) throw new Error('volter world changeset: say what and why — volter world changeset -m "<message>"');
+      const cs = world.changeset({ ...(pos[0] ? { name: pos[0] } : {}), message, ...(value(args, '--base') ? { base: value(args, '--base')! } : {}), overwrite: flag(args, '--force') });
+      if (asJson) { json(cs); return; }
+      out(`changeset  ${cs.name}  ${cs.actions.length} change${cs.actions.length === 1 ? '' : 's'}\n  ${message}${cs.narration ? `\n${cs.narration.split('\n').map((l) => `  ${l}`).join('\n')}` : ''}`);
+      return;
+    }
+    case 'serve': {
+      const served = await world.serve({ ...(value(args, '--port') ? { port: Number(value(args, '--port')) } : {}), ...(value(args, '--console-port') ? { consolePort: Number(value(args, '--console-port')) } : {}), ...(value(args, '--host') ? { host: value(args, '--host') } : {}), announce: (info) => out(`serving  ${info.name}  ${info.base}\ntoken    ${info.token}\nread     ${info.readToken}${info.console ? `\nconsole  ${info.console}` : ''}`) });
+      await waitForServeShutdown(() => served.stop());
+      process.exit(0); // success follows confirmed shutdown; failures reach main's error path
+      return;
+    }
+    case 'rebase': {
+      const name = positionals(args, VALUE_FLAGS)[0];
+      if (name) {
+        const r = world.rebase(name); if (asJson) { json(r); return; }
+        const conflicts = r.report.actions.flatMap((a) => (a.conflicts ?? []).map((c) => `${a.service} ${c.subject.type}:${c.subject.id} ${c.field} ${c.op}`));
+        out(`rebased  ${name}  ${r.report.outcome}${conflicts.length ? `\n  conflicts:\n  ${conflicts.join('\n  ')}` : ''}`);
+        return;
+      }
+      const results = world.rebaseBranch();
+      if (asJson) { json(results); return; }
+      const conflicts = results.flatMap((r) => r.conflicts.map((c) => `${r.service} ${c.subject.type}:${c.subject.id} ${c.field} ${c.op}`));
+      out(`rebased  ${world.name}  onto ${world.isMain() ? 'origin' : 'its base'}${results.some((r) => r.moved) ? `  ${results.map((r) => `${r.service}@${r.to}`).join(' ')}` : ' (already there)'}${conflicts.length ? `\n  conflicts:\n  ${conflicts.join('\n  ')}` : ''}`);
+      return;
+    }
+    case 'verify': {
+      const name = positionals(args, VALUE_FLAGS)[0]; if (!name) throw new Error('volter world verify: which changeset?');
+      const outcome = await world.verify(name, { ephemeral: true });
+      if (asJson) { json(outcome); return; }
+      const failed = outcome.verification.results.filter((r) => !r.passed);
+      const refusals = outcome.verification.refusals ?? [];
+      if (refusals.length) out(`refused  ${name}  ${refusals.map((r) => `${r.check}: ${r.reason}`).join('; ')}`);
+      else out(failed.length === 0 ? `verified  ${name}  checks passed` : `refused  ${name}  ${failed.map((r) => `${r.service} ${r.assert.subject.type}:${r.assert.subject.id} ${r.assert.field} ${r.assert.op}`).join('; ')}`);
+      return;
+    }
+    case 'approve': {
+      const name = positionals(args, VALUE_FLAGS)[0]; const as = value(args, '--as');
+      if (!name || !as) throw new Error('volter world approve <changeset> --as <principal>');
+      const outcome = world.approve(name, as, value(args, '--note'));
+      if (asJson) { json(outcome); return; }
+      out(`approved  ${name}  by ${as}`);
+      return;
+    }
+    case 'deploy': {
+      const name = positionals(args, VALUE_FLAGS)[0];
+      const outcomes = await world.deploy(name);
+      if (asJson) { json(outcomes); return; }
+      if (outcomes.length === 0) { out('nothing to deploy'); return; }
+      for (const o of outcomes) out(`deployed  ${o.changeset ?? name ?? o.service}  ${o.report.pushed} change${o.report.pushed === 1 ? '' : 's'}${o.report.refused ? `  refused by ${o.report.refused.check}: ${o.report.refused.reason}` : o.report.failed ? `  failed: ${o.report.failed.error}` : ''}`);
+      return;
+    }
+    case 'push': {
+      const remoteName = 'origin';
+      const outcomes = await world.push({ ...(pos[0] ? { name: pos[0] } : {}), ...(value(args, '--token') ? { token: value(args, '--token')! } : {}), force: flag(args, '--force') });
+      if (asJson) { json(outcomes); return; }
+      if (outcomes.length === 0) { out('nothing to push'); return; }
+      for (const o of outcomes) {
+        const n = o.changeset.actions.length;
+        if (o.application.outcome === 'refused') { out(`refused  ${o.changeset.name}  ${(o.application.refusal ?? []).join('; ')}`); continue; }
+        out(`pushed  ${o.changeset.name}  ${n} change${n === 1 ? '' : 's'} → ${remoteName}`);
+        if (o.unsent) process.stderr.write(`warning: ${o.unsent}\n`);
+        for (const r of o.application.receipts) if (r.status === 'failed') out(`  ${r.service}  refused  ${r.error ?? ''}`);
+      }
+      return;
+    }
+    default:
+      throw new Error(`volter world: unknown verb "${verb}"\n\n${HELP}`);
+  }
+}
+
+/** `volter twin <vendor> <verb…>`: the twin's own CLI (serve, mirror, conformance), found the way a world finds it. */
+async function twinCommand(args: string[]): Promise<void> {
+  const [vendor, ...rest] = args;
+  if (!vendor || vendor.startsWith('-')) throw new Error('volter twin: which twin? (volter twin stripe serve --port 12111)');
+  const verb = rest[0];
+  // the twin IN THIS WORLD: its root, its credential, a refresh, its status
+  if (verb === undefined || verb === 'root' || verb === 'credential' || verb === 'refresh' || verb.startsWith('-')) {
+    const world = World.open({ ...(value(rest, '--world') ? { root: value(rest, '--world') } : {}) });
+    if (verb === 'root') {
+      const url = positionals(rest.slice(1), VALUE_FLAGS)[0];
+      if (flag(rest, '--none')) { world.setTwinRoot(vendor, null); out(`${vendor}  no root`); return; }
+      if (!url) throw new Error(`volter twin ${vendor} root <url> [--deploy auto|gated|hold] [--scope <path>] [--refresh <every>] [--at-most <span>]`);
+      const deploy = (value(rest, '--deploy') ?? 'gated') as 'auto' | 'gated' | 'hold';
+      if (!['auto', 'gated', 'hold'].includes(deploy)) throw new Error('--deploy must be auto, gated or hold');
+      const refresh = { ...(value(rest, '--refresh') ? { every: value(rest, '--refresh')! } : {}), ...(value(rest, '--at-most') ? { atMost: value(rest, '--at-most')! } : {}) };
+      world.setTwinRoot(vendor, { url, deploy, ...(value(rest, '--scope') ? { scope: value(rest, '--scope')! } : {}), ...(Object.keys(refresh).length ? { refresh } : {}) });
+    } else if (verb === 'credential') {
+      const input = stdinText();
+      if (input.trim() === '') throw new Error(`volter twin ${vendor} credential: read the credential from stdin (printf '<token>' | volter twin ${vendor} credential)`);
+      await world.sealTwinCredential(vendor, input);
+    } else if (verb === 'refresh') {
+      const r = await world.refreshTwin(vendor, { force: flag(rest, '--force') });
+      out(r.refreshed ? `${vendor}  refreshed  ${r.report?.appended ?? 0} changed, ${r.report?.removed ?? 0} gone, ${r.report?.unchanged ?? 0} unchanged` : `${vendor}  not refreshed: ${r.reason}`);
+      return;
+    }
+    const t = world.twin(vendor);
+    if (flag(rest, '--json')) { json(t); return; }
+    out(`${vendor}  ${t.root ? `root ${t.root.url}${t.root.scope ? `/${t.root.scope}` : ''}  deploy ${t.root.deploy}` : 'no root'}  ${t.credential ? 'credential sealed' : 'no credential'}${t.url ? `  ${t.url}` : ''}`);
+    return;
+  }
+  const dir = resolveCatalog(process.cwd()).packDir(vendor);
+  if (dir === undefined) throw new Error(`No twin "${vendor}" here — \`bun add -d @volter/twin-${vendor}\`, or run from a checkout that has it`);
+  if (rest.length === 0 || rest[0]!.startsWith('-')) throw new Error(`volter twin ${vendor}: which verb? serve | mirror | conformance`);
+  const cli = packCli(dir); if (cli === undefined) throw new Error(`No cli for twin "${vendor}" (its manifest names no bin)`);
+  process.exitCode = await passthrough([process.execPath, cli, ...rest]);
+}
+
+/** The remote's own CLI entry: the installed package, or this checkout's. */
+function remoteCli(): string {
+  const installed = findInstalledPackage(process.cwd(), '@volter/world-host');
+  if (installed !== undefined) { const cli = packCli(installed); if (cli !== undefined) return cli; }
+  const here = resolve(import.meta.dir, '..', '..', 'world-host', 'src', 'cli.ts');
+  if (existsSync(here)) return here;
+  throw new Error('volter remote: the hosting product (@volter/world-host) is not installed — `bun add -d @volter/world-host`');
+}
+
+/** `volter login <platform url> --token <personal token>`: the CLI signed into the hosted platform as you — the
+ *  token is a personal access token from the console (shown once there), kept in your config directory. */
+async function loginCommand(args: string[]): Promise<void> {
+  const url = positionals(args, VALUE_FLAGS)[0]; const token = value(args, '--token');
+  if (!url || !token) throw new Error('volter login <platform url> --token <personal token>  (make one in the console under "You")');
+  const origin = url.replace(/\/+$/, '');
+  const res = await fetch(`${origin}/-/orgs`, { headers: { authorization: `Bearer ${token}` } });
+  const body = (await res.json().catch(() => ({}))) as { person?: { email?: string; id?: string }; orgs?: Array<{ slug: string | null; name: string }>; error?: string };
+  if (!res.ok) throw new Error(`${origin} answered ${res.status}: ${body.error ?? 'not signed in'}`);
+  storeToken(origin, token); storePlatform(origin);
+  out(`signed in  ${origin}  as ${body.person?.email ?? body.person?.id ?? 'you'}\norgs       ${(body.orgs ?? []).map((o) => o.slug ?? o.name).join(', ') || '(none yet)'}\nnext       volter remote add origin <org>/<world>`);
+}
+
+async function remoteCommand(verb: string, args: string[]): Promise<void> {
+  if (verb === 'add' || verb === 'remove' || verb === 'list') {
+    const world = World.open({ ...(value(args, '--world') ? { root: value(args, '--world') } : {}) });
+    const pos = positionals(args, VALUE_FLAGS);
+    if (verb === 'add') {
+      const [name, target] = pos;
+      if (!name || !target) throw new Error('volter remote add <name> <url|path|org/world> [--token <token>]');
+      // `org/world`: a world the hosted platform serves for your org — its address and token come through the platform, never by hand
+      if (/^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/.test(target) && !existsSync(target)) {
+        const platform = platformOrigin(); if (!platform) throw new Error(`${target} looks like a hosted world (org/world) — \`volter login <platform url> --token <personal token>\` first`);
+        const personal = tokenFor(platform); if (!personal) throw new Error(`no personal token stored for ${platform} — \`volter login\` again`);
+        const res = await fetch(`${platform}/-/worlds/${target}/token`, { headers: { authorization: `Bearer ${personal}` } });
+        const body = (await res.json().catch(() => ({}))) as { base?: string; token?: string; error?: string };
+        if (!res.ok || !body.base || !body.token) throw new Error(`the platform answered ${res.status}: ${body.error ?? 'no such world in your orgs'}`);
+        world.addRemote(name, body.base, { token: body.token });
+        out(`remote   ${name}  ${body.base}  (through ${platform})`);
+        return;
+      }
+      world.addRemote(name, target, { ...(value(args, '--token') ? { token: value(args, '--token') } : {}) });
+      out(`remote   ${name}  ${target}`);
+      return;
+    }
+    if (verb === 'remove') { if (!pos[0]) throw new Error('volter remote remove <name>'); world.removeRemote(pos[0]); out(`removed  ${pos[0]}`); return; }
+    const remotes = world.remotes();
+    if (flag(args, '--json')) { json(remotes); return; }
+    if (Object.keys(remotes).length === 0) { out('(no remotes)'); return; }
+    for (const [name, target] of Object.entries(remotes)) out(`${name.padEnd(10)} ${target}${tokenFor(parseOriginUrl(target).url) ? '  (token stored)' : ''}`);
+    return;
+  }
+  if (verb === 'serve') { process.exitCode = await passthrough([process.execPath, remoteCli(), 'serve', ...args]); return; }
+  throw new Error(`volter remote: unknown verb "${verb}"\n\n${HELP}`);
+}
+
+async function main(): Promise<void> {
+  const [noun, verb, ...args] = process.argv.slice(2);
+  if (!noun || noun === '--help' || noun === '-h' || noun === 'help') { out(HELP); return; }
+  if (verb === '--help' || verb === '-h') { out(HELP); return; }
+  switch (noun) {
+    case 'world': {
+      if (!verb) throw new Error(`volter world: which verb?\n\n${HELP}`);
+      await worldCommand(verb, args);
+      return;
+    }
+    case 'login': await loginCommand([verb, ...args].filter((a): a is string => a !== undefined)); return;
+    case 'twin': await twinCommand([verb, ...args].filter((a): a is string => a !== undefined)); return;
+    case 'remote': {
+      if (!verb) throw new Error('volter remote: which verb? add | remove | list | serve');
+      await remoteCommand(verb, args);
+      return;
+    }
+    default:
+      throw new Error(`volter: unknown noun "${noun}" — world, twin or remote\n\n${HELP}`);
+  }
+}
+
+const isEntryPoint = import.meta.main ?? (process.argv[1] !== undefined && existsSync(process.argv[1])
+  && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url));
+if (isEntryPoint) {
+  main().catch((error: unknown) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(process.exitCode && process.exitCode !== 0 ? Number(process.exitCode) : 1);
+  });
+}

package/src/credentials.ts

@@ -0,0 +1,56 @@
+// Tokens, not keys (docs/concepts/worlds.md#the-config-and-the-running-world): the remote's read and admin
+// credentials are TOKENS, kept in the user's config directory keyed by origin URL — written by
+// `clone --token`, read by `fetch` and `push`. Nothing in the repo and nothing in the world holds
+// one; "key" means only the vendor's real API key, which lives in the remote's custody.
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+type Store = Record<string, { token: string; savedAt: string }>;
+
+/** `$XDG_CONFIG_HOME/volter/credentials.json`, else `~/.config/volter/credentials.json`. */
+export function credentialsPath(): string {
+  const base = process.env.XDG_CONFIG_HOME && process.env.XDG_CONFIG_HOME !== '' ? process.env.XDG_CONFIG_HOME : join(homedir(), '.config');
+  return join(base, 'volter', 'credentials.json');
+}
+
+function normalizeOrigin(url: string): string { return url.replace(/\/+$/, ''); }
+
+function readStore(path: string): Store {
+  if (!existsSync(path)) return {};
+  try { return JSON.parse(readFileSync(path, 'utf8')) as Store; } catch { throw new Error(`${path} is not readable as JSON — fix or delete it`); }
+}
+
+/** The token stored for an origin, or undefined. */
+export function tokenFor(origin: string, path: string = credentialsPath()): string | undefined {
+  return readStore(path)[normalizeOrigin(origin)]?.token;
+}
+
+/** Store a token for an origin (0600). */
+export function storeToken(origin: string, token: string, path: string = credentialsPath()): void {
+  if (token === '') throw new Error('an empty token cannot be stored');
+  const store = readStore(path);
+  store[normalizeOrigin(origin)] = { token, savedAt: new Date().toISOString() };
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(path, 0o600);
+}
+
+/** `volter login`: the hosted platform a person signed the CLI into — its origin, beside the credentials. */
+export function platformPath(): string { return join(dirname(credentialsPath()), 'platform.json'); }
+export function storePlatform(origin: string, path: string = platformPath()): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, `${JSON.stringify({ url: normalizeOrigin(origin), savedAt: new Date().toISOString() }, null, 2)}\n`, { mode: 0o600 });
+}
+export function platformOrigin(path: string = platformPath()): string | undefined {
+  if (!existsSync(path)) return undefined;
+  try { return (JSON.parse(readFileSync(path, 'utf8')) as { url?: string }).url; } catch { return undefined; }
+}
+/** The token a verb uses: an explicit one for this call (CI), else the stored one, else a clear error. */
+export function requireToken(origin: string, explicit?: string, path: string = credentialsPath()): string {
+  if (explicit !== undefined && explicit !== '') return explicit;
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(origin)) return ''; // a world at a path needs no token
+  const stored = tokenFor(origin, path);
+  if (stored === undefined) throw new Error(`No token stored for ${normalizeOrigin(origin)} — \`volter world clone <url> --token <token>\` stores one, or pass --token for this call`);
+  return stored;
+}

package/src/handlers-in-repo.test.ts

@@ -0,0 +1,45 @@
+// A world in the app repo carries its handlers as ROOT-RELATIVE paths (docs/concepts/worlds.md
+// #the-config-and-the-running-world): init copies a twin's starter handlers to .volter/handlers/<vendor>.json and
+// names that path relative to the world root, so the committed config reads the same on every
+// machine; `up` resolves it against the root on both the spawn path (--scenario) and the colocated
+// host (scenarioPath). Proven against the real anthropic twin, which ships starter handlers.
+import { afterAll, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, readFileSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { World } from './index.ts';
+
+const PACKS = resolve(import.meta.dir, '..', '..', 'twin');
+
+function app(): string {
+  const parent = mkdtempSync(join(tmpdir(), 'handlers-in-repo-'));
+  const dir = join(parent, 'agent');
+  mkdirSync(dir);
+  writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'agent', dependencies: { '@anthropic-ai/sdk': '^0.30' } }));
+  writeFileSync(join(dir, '.env.example'), 'ANTHROPIC_API_KEY=\n');
+  mkdirSync(join(parent, 'node_modules', '@volter'), { recursive: true });
+  symlinkSync(join(PACKS, 'anthropic'), join(parent, 'node_modules', '@volter', 'twin-anthropic'));
+  return dir;
+}
+
+const root = app();
+const world = World.init(root).world;
+afterAll(async () => { await world.down().catch(() => undefined); });
+
+describe('handlers in the app repo', () => {
+  test('init copies the starter handlers and names them relative to the root', () => {
+    expect(readFileSync(join(root, '.volter', 'handlers', 'anthropic.json'), 'utf8')).toContain('"handlers"');
+    const config = JSON.parse(readFileSync(join(root, '.volter', 'world.json'), 'utf8')) as { schemaVersion: number; services: Array<{ id: string; execution?: { process?: { args?: string[] }; colocate?: { scenarioPath?: string } } }> };
+    expect(config.schemaVersion).toBe(2);
+    const anthropic = config.services.find((s) => s.id === 'anthropic')!;
+    expect(anthropic.execution?.process?.args).toEqual(['--scenario', '.volter/handlers/anthropic.json']);
+    expect(anthropic.execution?.colocate?.scenarioPath).toBe('.volter/handlers/anthropic.json');
+  });
+
+  test('up resolves them against the root, and the twin serves them', async () => {
+    const instance = await world.up({ seed: false });
+    const url = instance.services.anthropic!.url!;
+    const scenario = await fetch(`${url}/twin/scenario`).then((r) => r.json()) as { handlers?: Array<{ id: string }> };
+    expect((scenario.handlers ?? []).map((h) => h.id)).toContain('demo-answer');
+  });
+});

package/src/index.ts

@@ -0,0 +1,6 @@
+// @volter/world — the product surface (docs/concepts/the-model.md, docs/concepts/worlds.md#the-config-and-the-running-world):
+// World and Repo, one method per verb in the user's words, over core and the kernel, with no
+// mechanism of its own. The `volter` command is one client of this package.
+export { World, parseOriginUrl, worldNameFor, type LogEntry, type WorldMode, type WorldRef, type WorldStatus } from './world.ts';
+export { findWorldRoot, requireWorldRoot, currentBranch, setCurrentBranch, mainBranch, worldConfigPath, worldEnvPath, worldSeedPath, WORLD_FILE } from './locate.ts';
+export { credentialsPath, requireToken, storeToken, tokenFor } from './credentials.ts';

package/src/journeys/kit.ts

@@ -0,0 +1,12 @@
+// What the tutorial runner and the docs' recorder share: where the commands and the twins are.
+// A tutorial page is its own journey (tutorial.ts); nothing here runs a step of its own.
+import { resolve } from 'node:path';
+
+/** The `volter` command. */
+export const CLI = resolve(import.meta.dir, '..', 'cli.ts');
+/** The operator's `volter-world` command, which ships with @volter/world-runtime. */
+export const OPERATOR_CLI = resolve(import.meta.dir, '..', '..', '..', 'world-runtime', 'src', 'cli.ts');
+/** The twins, as this checkout holds them. */
+export const PACKS = resolve(import.meta.dir, '..', '..', '..', 'twin');
+/** @volter/world itself. */
+export const SDK = resolve(import.meta.dir, '..', '..');