@volter/world 2.0.0

package/dist/src/cli.js

@@ -0,0 +1,669 @@
+#!/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 { existsSync } from 'node:fs';
+import { relative, resolve } from 'node:path';
+import { platformOrigin, storePlatform, storeToken, tokenFor } from "./credentials.js";
+import { parseOriginUrl, World } from "./world.js";
+import { waitForServeShutdown } from "./serve-shutdown.js";
+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, name) { return args.includes(name); }
+function value(args, name) {
+    const i = args.indexOf(name);
+    return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
+}
+function positionals(args, valueFlags) {
+    const out = [];
+    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) { 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) {
+    const id = subject.id.replace(new RegExp(`(^|[#/:])${subject.type}:`), '$1');
+    return /[#/]/.test(id) ? id : `${subject.type}:${id}`;
+}
+function out(text) { process.stdout.write(text.endsWith('\n') ? text : `${text}\n`); }
+function json(value) { out(JSON.stringify(value, null, 2)); }
+function when(iso) { 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, cwd = process.cwd()) {
+    const child = spawn(cmd[0], cmd.slice(1), { cwd, stdio: 'inherit' });
+    const forward = (signal) => () => { try {
+        child.kill(signal);
+    }
+    catch { /* already gone */ } };
+    for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP'])
+        process.on(signal, forward(signal));
+    return await new Promise((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() { try {
+    return readFileSync(0, 'utf8');
+}
+catch {
+    return '';
+} }
+async function worldCommand(verb, args) {
+    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' } : {}), 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 = {};
+                const views = {};
+                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) {
+    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');
+            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() {
+    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) {
+    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(() => ({})));
+    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, args) {
+    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(() => ({})));
+                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() {
+    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 !== undefined));
+            return;
+        case 'twin':
+            await twinCommand([verb, ...args].filter((a) => 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) => {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(process.exitCode && process.exitCode !== 0 ? Number(process.exitCode) : 1);
+    });
+}