@volter/world 2.0.1 → 2.0.2

package/dist/src/cli.js

@@ -3,25 +3,49 @@
 // 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 { detectRepoVendors, 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 { spawn, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { hostname } from 'node:os';
 import { existsSync } from 'node:fs';
-import { relative, resolve } from 'node:path';
-import { platformOrigin, storePlatform, storeToken, tokenFor } from "./credentials.js";
+import { join, relative, resolve } from 'node:path';
+import { forgetPlatform, forgetToken, platformOrigin, storePlatform, storeToken, tokenFor } from "./credentials.js";
 import { parseOriginUrl, World } from "./world.js";
 import { waitForServeShutdown } from "./serve-shutdown.js";
+import { startUpdateCheck } from "./update-notice.js";
+/** Open a URL in the person's browser; a machine without one only loses the convenience. */
+function openInBrowser(url) {
+    // an http(s) URL only, and on Windows through the URL handler rather than cmd.exe, which would read `"`, `&` or `%VAR%`
+    // in it as commands
+    let target;
+    try {
+        const u = new URL(url);
+        if (u.protocol !== 'http:' && u.protocol !== 'https:')
+            return;
+        target = u.href;
+    }
+    catch {
+        return;
+    }
+    const [cmd, ...pre] = process.platform === 'darwin' ? ['open'] : process.platform === 'win32' ? ['rundll32', 'url.dll,FileProtocolHandler'] : ['xdg-open'];
+    try {
+        spawn(cmd, [...pre, target], { windowsHide: true, stdio: 'ignore', detached: true }).on('error', () => undefined).unref();
+    }
+    catch { /* no browser here */ }
+}
 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 init [--install] [--name <world>] [--allow-unknown]   detect the app's vendors (installing their twins when none are), 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 serve [--port <p>] [--console-port <c>]   serve this world on a URL under /<org>/<world>/ for apps; prints the token and the console (on loopback: view's front, no token in the browser)
+  volter world view [--port <p>] [--host <h>] [--no-open] [--no-origins]   step into this world in a browser: its twins' own UIs, timeline, clock, branches (a non-loopback --host serves them on one origin)
   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
@@ -53,9 +77,17 @@ twin   — one twin: in this world, or on its own
   volter twin <vendor> mirror [--port <p>]               the twin's UI mirror
   volter twin <vendor> conformance                       check the twin against the vendor's spec
 
+agents — your coding agent, driving the same verbs
+  volter agents install [--claude] [--cursor] [--vscode] [--codex] [--yes]   put the volter-world skill and the MCP server into the agents found here
+  volter mcp                                             the MCP server (stdio) an agent starts: the verbs above as tools
+
 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 login <platform url> [--token <personal token>]  sign the CLI into the hosted platform: approve it in the browser (or a token made under Account, for CI)
+  volter whoami                                          the platform the CLI is signed into, as whom, and its orgs
+  volter logout                                          revoke the CLI's token at the platform and forget it here
+  volter remote add <name> <url|path|org/world> [--token <token>] [--create]  name a remote; org/world (or world, in one org) resolves through the platform you logged into; --create makes it there from this world's twins
+  volter open [<org>/<world>] [--no-open]                a World's dashboard: a hosted one through the platform, else this world's (as view)
+  volter completion bash|zsh|fish|powershell             print a completion script for your shell
   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)
@@ -96,7 +128,7 @@ 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 child = spawn(cmd[0], cmd.slice(1), { windowsHide: true, cwd, stdio: 'inherit' });
     const forward = (signal) => () => { try {
         child.kill(signal);
     }
@@ -134,6 +166,7 @@ async function worldCommand(verb, args) {
     }
     if (verb === 'init') {
         const app = resolve(worldDir ?? process.cwd());
+        await installDetectedTwins(app, flag(args, '--install'));
         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 });
@@ -141,6 +174,8 @@ async function worldCommand(verb, args) {
             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)
+                await offerAgents();
         }
         if (!result.ok)
             process.exitCode = 1;
@@ -398,10 +433,58 @@ async function worldCommand(verb, args) {
             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 'view':
         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
+            // `view` steps into the World in a browser; `serve` serves it for apps and scripts. Bound to this machine's
+            // loopback both are the same local front (the World's own origin, its console beside it) and the browser never
+            // needs a token (served-world.ts localSession); `serve` only leaves the browser closed. A non-loopback --host,
+            // or `serve --console-port`, is a World served for others: its console asks for a token.
+            const host = value(args, '--host');
+            const local = host === undefined || host === '127.0.0.1' || host === 'localhost' || host === '::1';
+            if (verb === 'serve' && (!local || value(args, '--console-port') !== undefined)) {
+                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;
+            }
+            // the console mounts when it is installed beside the CLI; without it the World serves its doors and mirrors
+            const console = await (async () => {
+                try {
+                    const mod = await import('@volter/world-console');
+                    return mod.createConsole();
+                }
+                catch (error) {
+                    // not installed is one thing; installed and broken is another, and says why
+                    const missing = /ERR_MODULE_NOT_FOUND|Cannot find (package|module)/.test(`${error.code ?? ''} ${String(error)}`);
+                    if (!missing)
+                        process.stderr.write(`the console failed to load (the World is served without it): ${error instanceof Error ? error.message : String(error)}\n`);
+                    return undefined;
+                }
+            })();
+            // `serve` says what it always said first (`serving <name> <url>`, then the tokens: scripts and the guides read
+            // those lines), and the local front's own lines after them; `view` says `viewing` as it goes
+            const later = [];
+            const view = await world.view({ ...(value(args, '--port') ? { port: Number(value(args, '--port')) } : {}), ...(host ? { host } : {}), ...(console ? { console } : {}), ...(args.includes('--no-origins') ? { origins: false } : {}), announce: (line) => { if (verb !== 'serve')
+                    out(line);
+                else if (!line.startsWith('viewing'))
+                    later.push(line); } });
+            if (verb === 'serve') {
+                out(`serving  ${view.served}  ${view.base}\ntoken    ${view.token}\nread     ${view.readToken}`);
+                for (const line of later)
+                    out(line);
+            }
+            // a local World's page opens itself; a World served for others is handed its token in the URL's fragment
+            // (which the browser never sends), taken once
+            // (with --no-origins every World shares one origin, where no page is handed a session: the token again)
+            const open = view.console ? (local && view.origin ? view.console : `${view.console}#token=${encodeURIComponent(view.token)}`) : null;
+            // the read token's own one-line way in, for handing to someone who should look and not touch
+            // (not on a local World: any of its pages can open a write session there, so a read-only link restricts nothing)
+            const readOnly = view.console && !(local && view.origin) ? `${view.console}#token=${encodeURIComponent(view.readToken)}` : null;
+            out(`${local && view.origin ? `apps     the World's tokens are in .volter/token and .volter/token.read (apps and scripts present them; the browser needs none)` : verb === 'serve' ? '' : `token    ${view.token}\nread     ${view.readToken}`}${readOnly ? `\nread-only view  ${readOnly}` : ''}${view.console ? '' : '\n(no console installed: `npm install -D @volter/world-console` to look around in a browser)'}${view.origin ? '\n(the World opens at its own *.localhost origin; if your browser cannot reach *.localhost, run again with --no-origins)' : ''}`);
+            if (open && verb === 'view' && !args.includes('--no-open'))
+                openInBrowser(open);
+            await waitForServeShutdown(() => view.stop());
+            process.exit(0);
             return;
         }
         case 'rebase': {
@@ -566,21 +649,130 @@ function remoteCli() {
         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. */
+/** `volter login <platform url>`: the CLI signed into the hosted platform as you, through the browser (the device
+ *  authorization grant, as `gh auth login`): the platform shows a code, you approve it there signed in as yourself,
+ *  and the command collects a personal token named for this machine. `--token <personal token>` (one made in the
+ *  platform under Account) signs in without a browser, for CI. Either way it is 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(/\/+$/, '');
+    if (!url)
+        throw new Error('volter login <platform url> [--token <personal token>] [--no-open]');
+    let origin;
+    try {
+        const u = new URL(url);
+        if (u.protocol !== 'https:' && u.protocol !== 'http:')
+            throw new Error();
+        origin = u.origin;
+    }
+    catch {
+        throw new Error(`${url} is not a platform address (https://…)`);
+    }
+    const token = value(args, '--token') ?? await deviceSignIn(origin, !flag(args, '--no-open'));
     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>`);
+    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       in your app's folder: volter world init, then volter remote add origin ${(body.orgs ?? [])[0]?.slug ?? '<org>'}/<world> --create`);
+}
+/** `volter whoami`: which platform the command is signed into, as whom, and the orgs it reaches. */
+async function whoamiCommand() {
+    const origin = platformOrigin();
+    const token = origin ? tokenFor(origin) : undefined;
+    if (!origin || !token) {
+        out('not signed in  (volter login <platform url>)');
+        process.exitCode = 1;
+        return;
+    }
+    const res = await fetch(`${origin}/-/orgs`, { headers: { authorization: `Bearer ${token}` } }).catch(() => null);
+    if (!res)
+        throw new Error(`${origin} did not answer`);
+    const body = (await res.json().catch(() => ({})));
+    // a token the platform no longer takes is signed out; one it takes but that may not read orgs is still signed in
+    if (res.status === 403) {
+        out(`signed in  ${origin}  (this token may not read your orgs: ${body.error ?? 'refused'})`);
+        return;
+    }
+    if (!res.ok) {
+        out(`signed out  ${origin}: ${body.error ?? res.status} — volter login ${origin}`);
+        process.exitCode = 1;
+        return;
+    }
+    out(`signed in  ${origin}  as ${body.person?.email ?? body.person?.id ?? 'you'}\norgs       ${(body.orgs ?? []).map((o) => `${o.slug ?? o.name}${o.role === 'org:admin' ? ' (admin)' : ''}`).join(', ') || '(none yet)'}`);
+}
+/** `volter logout`: the command's token is revoked at the platform (a token may always revoke itself) and forgotten here. */
+async function logoutCommand() {
+    const origin = platformOrigin();
+    const token = origin ? tokenFor(origin) : undefined;
+    if (!origin || !token) {
+        out('not signed in');
+        return;
+    }
+    const id = createHash('sha256').update(token).digest('hex');
+    const res = await fetch(`${origin}/-/tokens/${id}`, { method: 'DELETE', headers: { authorization: `Bearer ${token}` } }).catch(() => null);
+    forgetToken(origin);
+    forgetPlatform();
+    out(res?.ok ? `signed out  ${origin}  (its token is revoked)` : `signed out  ${origin}  (forgotten here; the platform did not revoke the token${res ? ` — ${res.status}` : ''}, so revoke it under Account)`);
+}
+/** The browser half of `volter login`: ask the platform for a code, send the person to approve it, and wait (at the
+ *  platform's pace) for the personal token it hands over once they do. */
+async function deviceSignIn(origin, openBrowser) {
+    const started = await fetch(`${origin}/-/cli/device`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ name: hostname() }) }).catch((e) => { throw new Error(`${origin} did not answer: ${e instanceof Error ? e.message : String(e)}`); });
+    const grant = (await started.json().catch(() => ({})));
+    if (!started.ok || !grant.device_code || !grant.user_code || !/^[A-Z]{4}-[A-Z]{4}$/.test(grant.user_code))
+        throw new Error(`${origin} cannot sign the command in through the browser (${started.status}${grant.error ? `: ${grant.error}` : ''}) — make a token on the platform under Account and use --token`);
+    // the page is this platform's own, built here from the address you gave and the code: nothing the platform answers is
+    // opened as it stands
+    const page = `${origin}/-/cli/approve?code=${grant.user_code}`;
+    process.stderr.write(`approve    ${page}\ncode       ${grant.user_code}  (check the page shows the same)\n`);
+    if (openBrowser)
+        openInBrowser(page);
+    const until = Date.now() + (grant.expires_in ?? 600) * 1000;
+    const every = Math.max(1, grant.interval ?? 5) * 1000;
+    while (Date.now() < until) {
+        await new Promise((r) => setTimeout(r, every));
+        const res = await fetch(`${origin}/-/cli/token`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ device_code: grant.device_code }) }).catch(() => null);
+        if (!res)
+            continue;
+        const body = (await res.json().catch(() => ({})));
+        if (res.ok && body.token)
+            return body.token;
+        if (body.error === 'authorization_pending' || body.error === 'slow_down')
+            continue;
+        if (body.error === 'access_denied')
+            throw new Error('refused in the browser: the command was not signed in');
+        throw new Error(`the code expired or was already used (${body.error ?? res.status}) — run volter login again`);
+    }
+    throw new Error('the code expired before it was approved — run volter login again');
+}
+/** "a, b and c". */
+const listed = (names) => (names.length <= 1 ? names.join('') : `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`);
+/** A yes from the person at the terminal; no terminal is a no (a script says --create instead). */
+async function confirm(question) {
+    if (!process.stdin.isTTY || !process.stderr.isTTY)
+        return false;
+    const { createInterface } = await import('node:readline/promises');
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return /^y(es)?$/i.test((await rl.question(question)).trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+/** The org a bare world name belongs to: the one org the person is in, else a question they answer by naming it. */
+async function onlyOrg(platform, personal, world) {
+    const res = await fetch(`${platform}/-/orgs`, { headers: { authorization: `Bearer ${personal}` } });
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok)
+        throw new Error(`${platform} answered ${res.status}: ${body.error ?? 'not signed in'} — volter login ${platform}`);
+    const orgs = (body.orgs ?? []).map((o) => o.slug ?? o.id ?? '').filter(Boolean);
+    if (orgs.length === 1)
+        return orgs[0];
+    if (orgs.length === 0)
+        throw new Error(`you are in no org on ${platform} yet — make one there, then volter remote add origin <org>/${world}`);
+    throw new Error(`you are in ${orgs.length} orgs (${listed(orgs)}): say which, volter remote add origin <org>/${world}`);
 }
 async function remoteCommand(verb, args) {
     if (verb === 'add' || verb === 'remove' || verb === 'list') {
@@ -589,21 +781,43 @@ async function remoteCommand(verb, args) {
         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)) {
+                throw new Error('volter remote add <name> <url|path|org/world> [--token <token>] [--create]');
+            // `org/world` (or `world`, when you are in one org): a world the hosted platform serves for your org — its address
+            // and token come through the platform, never by hand; one that is not there yet is made there from this world's
+            // vendors, asked first, or at once with --create (a script's or an agent's way)
+            // a bare word is a hosted world only when this command is signed into a platform; otherwise it is a folder, as ever
+            const hosted = !existsSync(target) && (/^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/.test(target) || (/^[a-z0-9][a-z0-9-]*$/.test(target) && Boolean(platformOrigin())));
+            if (hosted) {
                 const platform = platformOrigin();
                 if (!platform)
-                    throw new Error(`${target} looks like a hosted world (org/world) — \`volter login <platform url> --token <personal token>\` first`);
+                    throw new Error(`${target} looks like a hosted world (org/world) — \`volter login <platform url>\` 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(() => ({})));
+                const served = target.includes('/') ? target : `${await onlyOrg(platform, personal, target)}/${target}`;
+                const key = () => fetch(`${platform}/-/worlds/${served}/token`, { headers: { authorization: `Bearer ${personal}` } });
+                let res = await key();
+                let body = (await res.clone().json().catch(() => ({})));
+                if (res.status === 404 && /^no world /.test(body.error ?? '')) {
+                    const vendors = world.vendors();
+                    if (vendors.length === 0)
+                        throw new Error(`${served} is not on ${platform} yet, and this world names no twins to make it with — \`volter world init\` first`);
+                    if (!flag(args, '--create') && !(await confirm(`${served} is not on ${platform}. Make it there with ${listed(vendors)}? [y/N] `))) {
+                        throw new Error(`${served} is not on ${platform}${process.stdin.isTTY ? '' : ' — add --create to make it with this world\'s twins'}${target.includes('/') ? '' : ` (a folder? name it ./${target})`}`);
+                    }
+                    const [org, worldName] = served.split('/');
+                    const made = await fetch(`${platform}/-/worlds`, { method: 'POST', headers: { authorization: `Bearer ${personal}`, 'content-type': 'application/json' }, body: JSON.stringify({ org, world: worldName, vendors }) });
+                    const madeBody = (await made.json().catch(() => ({})));
+                    if (!made.ok)
+                        throw new Error(`the platform did not make ${served} (${made.status}): ${madeBody.error ?? 'refused'}`);
+                    out(`made     ${madeBody.name ?? served}  on ${platform}  (${listed(vendors)})`);
+                    res = await key();
+                    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})`);
+                out(`remote   ${name}  ${body.base}  (through ${platform}${body.scope === 'read' ? ', read only: this token may not write Worlds' : ''})`);
                 return;
             }
             world.addRemote(name, target, { ...(value(args, '--token') ? { token: value(args, '--token') } : {}) });
@@ -636,8 +850,157 @@ async function remoteCommand(verb, args) {
     }
     throw new Error(`volter remote: unknown verb "${verb}"\n\n${HELP}`);
 }
+/** `volter open [<org>/<world>] [--no-open]`: a World's dashboard. A hosted World (named, or this world's origin on the
+ *  platform the command is signed into) opens through the platform, which signs the person in with a pass; otherwise
+ *  it is this world's own, as `volter world view` serves it. */
+async function openCommand(args) {
+    const named = positionals(args, VALUE_FLAGS)[0];
+    const platform = platformOrigin();
+    let served = named && /^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/.test(named) ? named : null;
+    if (!served && !named && platform) {
+        // this world's origin, when it is a World the platform serves: its namespace is <org>/<world>
+        try {
+            const origin = World.open({ ...(value(args, '--world') ? { root: value(args, '--world') } : {}) }).remote();
+            if (origin && tokenFor(origin.url) && /^[a-z0-9-]+\/[a-z0-9-]+$/.test(origin.namespace))
+                served = origin.namespace;
+        }
+        catch { /* no world here */ }
+    }
+    if (named && !served)
+        throw new Error(`volter open ${named}: name a hosted World as <org>/<world>, or run it in the app's folder for this world`);
+    if (served) {
+        if (!platform)
+            throw new Error(`${served} is a hosted World — \`volter login <platform url>\` first`);
+        const url = `${platform}/-/worlds/${served}/open`;
+        out(url);
+        if (!flag(args, '--no-open'))
+            openInBrowser(url);
+        return;
+    }
+    await worldCommand('view', args);
+}
+/** The command tree for completion, read from HELP (the one list of commands): noun → its verbs. */
+function commandTree() {
+    const tree = { open: [], completion: ['bash', 'zsh', 'fish', 'powershell'] };
+    for (const m of HELP.matchAll(/^\s+volter ([a-z]+)(?: ([a-z][a-z-]*))?/gm)) {
+        const [, noun, verb] = m;
+        (tree[noun] ??= []);
+        if (verb && !tree[noun].includes(verb))
+            tree[noun].push(verb);
+    }
+    return tree;
+}
+/** `volter completion bash|zsh|fish|powershell`: a script that completes volter's nouns and verbs in that shell. */
+function completionScript(shell) {
+    const tree = commandTree();
+    const nouns = Object.keys(tree).join(' ');
+    const cases = (fmt) => Object.entries(tree).filter(([, v]) => v.length).map(([n, v]) => fmt(n, v.join(' '))).join('\n');
+    switch (shell) {
+        case 'bash':
+        case 'zsh':
+            return `${shell === 'zsh' ? 'autoload -U +X bashcompinit && bashcompinit\n' : ''}# volter completion (${shell}): eval "$(volter completion ${shell})"
+_volter() {
+  local cur=\${COMP_WORDS[COMP_CWORD]}
+  if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=($(compgen -W "${nouns}" -- "$cur")); return; fi
+  if [ "$COMP_CWORD" -eq 2 ]; then
+    case "\${COMP_WORDS[1]}" in
+${cases((n, v) => `      ${n}) COMPREPLY=($(compgen -W "${v}" -- "$cur")) ;;`)}
+    esac
+  fi
+}
+complete -o default -F _volter volter
+`;
+        case 'fish':
+            return `# volter completion (fish): volter completion fish | source
+complete -c volter -f -n '__fish_use_subcommand' -a '${nouns}'
+${cases((n, v) => `complete -c volter -f -n '__fish_seen_subcommand_from ${n}; and test (count (commandline -opc)) -eq 2' -a '${v}'`)}
+`;
+        case 'powershell':
+            return `# volter completion (PowerShell): volter completion powershell | Out-String | Invoke-Expression
+Register-ArgumentCompleter -Native -CommandName volter -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+  $words = @($commandAst.CommandElements | ForEach-Object { $_.ToString() })
+  $tree = @{
+${Object.entries(tree).map(([n, v]) => `    '${n}' = @(${v.map((x) => `'${x}'`).join(', ')})`).join('\n')}
+  }
+  $choices = if ($words.Count -le 1 -or ($words.Count -eq 2 -and $wordToComplete)) { $tree.Keys } elseif ($tree.ContainsKey($words[1])) { $tree[$words[1]] } else { @() }
+  $choices | Where-Object { $_ -like "$wordToComplete*" } | Sort-Object | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }
+}
+`;
+        default:
+            throw new Error('volter completion bash|zsh|fish|powershell');
+    }
+}
+/** A fresh app has no twins installed, so `init` has nothing to plan with: its vendors are found from what the app
+ *  depends on and names in its env (the signatures ship with the command), and the twins for them are installed with
+ *  the app's own package manager: asked at a terminal, or at once with `--install` (a script's or an agent's way). */
+async function installDetectedTwins(app, install) {
+    try {
+        if (resolveCatalog(app).vendors().length > 0)
+            return;
+    }
+    catch { /* no twins here yet */ }
+    const found = detectRepoVendors(app).detected;
+    const vendors = [...found.keys()].filter((v) => /^[a-z0-9][a-z0-9-]*$/.test(v)).sort();
+    if (vendors.length === 0)
+        return; // init says what it found and how to add a twin by hand
+    const pkgs = vendors.map((v) => `@volter/twin-${v}`);
+    const has = (file) => existsSync(join(app, file));
+    // the app's own package manager, by its lockfile; npm where there is none
+    const command = has('bun.lock') || has('bun.lockb') ? `bun add -d ${pkgs.join(' ')}` : has('pnpm-lock.yaml') ? `pnpm add -D ${pkgs.join(' ')}` : has('yarn.lock') ? `yarn add -D ${pkgs.join(' ')}` : `npm install -D ${pkgs.join(' ')}`;
+    out(`detected  ${vendors.map((v) => `${v} (${(found.get(v) ?? []).slice(0, 2).join(', ')})`).join('; ')}`);
+    out(`twins     ${pkgs.join(' ')}`);
+    let yes = install;
+    if (!yes && process.stdin.isTTY && process.stdout.isTTY) {
+        process.stdout.write(`Install them now (${command})? [Y/n] `);
+        const answer = await new Promise((done) => { process.stdin.once('data', (d) => done(String(d).trim().toLowerCase())); });
+        process.stdin.pause();
+        yes = answer === '' || answer === 'y' || answer === 'yes';
+    }
+    if (!yes)
+        throw new Error(`install the twins first: ${command}
+then run volter world init again (or volter world init --install does both)`);
+    // one command line built from the checked names above: nothing of anyone's input reaches the shell
+    const ran = spawnSync(command, { cwd: app, stdio: 'inherit', shell: true, windowsHide: true });
+    if (ran.status !== 0)
+        throw new Error(`${command} failed (exit ${ran.status ?? 'none'})`);
+}
+/** After `volter world init`: a person at a terminal is asked whether to set up their coding agents; anyone else is
+ *  told the command. */
+async function offerAgents() {
+    const { detectAgents, installAgents } = await import("./agents.js");
+    const found = detectAgents(process.cwd());
+    if (found.length === 0)
+        return;
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        out('\nagents   volter agents install --yes   (the volter-world skill and MCP server for your coding agents)');
+        return;
+    }
+    process.stdout.write(`\nSet up your coding agent${found.length === 1 ? '' : 's'} (${found.join(', ')}) to drive this World? [y/N] `);
+    const answer = await new Promise((done) => { process.stdin.once('data', (d) => done(String(d).trim().toLowerCase())); });
+    process.stdin.pause();
+    if (answer === 'y' || answer === 'yes')
+        for (const line of installAgents(found, process.cwd()))
+            out(`  ${line}`);
+    else
+        out('later: volter agents install');
+}
+/** This package's version, for the MCP server's handshake. */
+function ownVersion() {
+    try {
+        return JSON.parse(readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8')).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
 async function main() {
     const [noun, verb, ...args] = process.argv.slice(2);
+    const notice = startUpdateCheck(process.argv.slice(2));
+    await dispatch(noun, verb, args);
+    await notice();
+}
+async function dispatch(noun, verb, args) {
     if (!noun || noun === '--help' || noun === '-h' || noun === 'help') {
         out(HELP);
         return;
@@ -656,17 +1019,41 @@ async function main() {
         case 'login':
             await loginCommand([verb, ...args].filter((a) => a !== undefined));
             return;
+        case 'logout':
+            await logoutCommand();
+            return;
+        case 'whoami':
+            await whoamiCommand();
+            return;
         case 'twin':
             await twinCommand([verb, ...args].filter((a) => a !== undefined));
             return;
+        case 'mcp': {
+            const { serveMcp } = await import("./mcp.js");
+            await serveMcp(ownVersion());
+            return;
+        }
+        case 'agents': {
+            const { agentsCommand } = await import("./agents.js");
+            await agentsCommand(verb, args, out);
+            return;
+        }
         case 'remote': {
             if (!verb)
                 throw new Error('volter remote: which verb? add | remove | list | serve');
             await remoteCommand(verb, args);
             return;
         }
+        case 'open':
+            await openCommand([verb, ...args].filter((a) => a !== undefined));
+            return;
+        case 'completion':
+            process.stdout.write(completionScript(verb));
+            return;
         default:
-            throw new Error(`volter: unknown noun "${noun}" — world, twin or remote\n\n${HELP}`);
+            throw new Error(`volter: unknown noun "${noun}" — world, twin, remote, open, completion, agents or mcp
+
+${HELP}`);
     }
 }
 const isEntryPoint = import.meta.main ?? (process.argv[1] !== undefined && existsSync(process.argv[1])

package/dist/src/credentials.d.ts

@@ -4,9 +4,13 @@ export declare function credentialsPath(): string;
 export declare function tokenFor(origin: string, path?: string): string | undefined;
 /** Store a token for an origin (0600). */
 export declare function storeToken(origin: string, token: string, path?: string): void;
+/** Forget the token stored for an origin; whether one was stored. */
+export declare function forgetToken(origin: string, path?: string): boolean;
 /** `volter login`: the hosted platform a person signed the CLI into — its origin, beside the credentials. */
 export declare function platformPath(): string;
 export declare function storePlatform(origin: string, path?: string): void;
+/** Forget which platform the CLI is signed into. */
+export declare function forgetPlatform(path?: string): void;
 export declare function platformOrigin(path?: string): string | undefined;
 /** The token a verb uses: an explicit one for this call (CI), else the stored one, else a clear error. */
 export declare function requireToken(origin: string, explicit?: string, path?: string): string;

package/dist/src/credentials.js

@@ -35,12 +35,25 @@ export function storeToken(origin, token, path = credentialsPath()) {
     writeFileSync(path, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
     chmodSync(path, 0o600);
 }
+/** Forget the token stored for an origin; whether one was stored. */
+export function forgetToken(origin, path = credentialsPath()) {
+    const store = readStore(path);
+    const key = normalizeOrigin(origin);
+    if (!(key in store))
+        return false;
+    delete store[key];
+    writeFileSync(path, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
+    return true;
+}
 /** `volter login`: the hosted platform a person signed the CLI into — its origin, beside the credentials. */
 export function platformPath() { return join(dirname(credentialsPath()), 'platform.json'); }
 export function storePlatform(origin, path = platformPath()) {
     mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
     writeFileSync(path, `${JSON.stringify({ url: normalizeOrigin(origin), savedAt: new Date().toISOString() }, null, 2)}\n`, { mode: 0o600 });
 }
+/** Forget which platform the CLI is signed into. */
+export function forgetPlatform(path = platformPath()) { if (existsSync(path))
+    writeFileSync(path, '{}\n', { mode: 0o600 }); }
 export function platformOrigin(path = platformPath()) {
     if (!existsSync(path))
         return undefined;

package/dist/src/mcp.d.ts

@@ -0,0 +1 @@
+export declare function serveMcp(version: string): Promise<void>;