@volter/world 3.0.40 → 3.0.42

package/dist/src/cli.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export declare const HELP = "volter \u2014 run your app against a world of twins\n\nworld  \u2014 the twins your app needs, running together (the world of the current directory)\n  volter world init [--install] [--name <world>] [--allow-unknown]   detect the app's vendors (installing their twins when none are), write .volter/world.json\n  volter world up [--sandbox] [--no-seed]                start the twins on this branch (loads the default data the first time)\n  volter world run [--verbose] -- <command...>           run the app or its tests inside the world\n  volter world activate                                  eval \"$(volter world activate)\": vendor CLIs and curl in this shell reach the twins\n  volter world shell                                     a subshell with the world active\n  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\n  volter world serve [--port <p>] [--console-port <c>] [--origin <url>]   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)\n  volter world view [--port <p>] [--host <h>] [--no-open] [--no-origins] [--origin <url>]   step into this world in a browser: its twins' own UIs, timeline, clock, branches (a non-loopback --host serves them on one origin)\n  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\n  volter world status                                    world, branch, origin, unpushed changes, what is running\n  volter world log [--receipts] [--json]                 every write the app made; --receipts adds each change's receipt\n  volter world diff [--json]                             what changed since the default data (or the last mark)\n  volter world seed                                      load the default data\n  volter world reset                                     back to the default data\n  volter world down [--purge]                            stop the twins (--purge forgets this branch's state)\n  volter world branch [<name>]                           list branches, or make one from here and check it out\n  volter world checkout <name>                           switch branches\n  volter world replay <changeset> --into <branch>        feed a changeset's changes into another branch's twins\n  volter world clock show | set <iso> | advance <N s|m|h|d> | shift <N s|m|h|d> | clear   the world's clock: set, not observed\n  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)\n  volter world fetch                                     what the remote observed since the last fetch\n  volter world origin                                    where this world clones from and pushes to\n  volter world changeset [<name>] -m \"<message>\"         cut the unpushed changes into a reviewable changeset\n  volter world pull [--token <token>]                    fetch, then move this branch onto what came in (git's pull)\n  volter world push [<name>] [--token <token>] [--force] push to the remote, which deploys and answers with receipts\n  volter world rebase [<changeset>]                      rebase this branch onto its moved base, or a changeset onto the moved remote\n  volter world verify <changeset>                        run the world's checks over a changeset and record the result\n  volter world approve <changeset> --as <principal>      sign a changeset's current hash\n  volter world deploy [<changeset>]                      perform landed changes against each twin's root, by its policy\n\ntwin   \u2014 one twin: in this world, or on its own\n  volter twin <vendor>                                   the twin's URL, root, deploy policy, whether a credential is sealed\n  volter twin <vendor> root <url> [--deploy auto|gated|hold] [--scope <path>]   the vendor's real account behind this twin (--none clears it)\n  volter twin <vendor> credential                        seal a credential read from stdin beside the world; never readable back\n  volter twin <vendor> refresh                           observe the root now\n  volter twin <vendor> serve [--port <p>] [--read-only]  serve the twin; your SDK talks to it at http://127.0.0.1:<p>\n\nagents \u2014 your coding agent, driving the same verbs\n  volter agents install [--claude] [--cursor] [--vscode] [--codex] [--yes]   put the volter-world skill and the MCP server into the agents found here\n  volter mcp                                             the MCP server (stdio) an agent starts: the verbs above as tools\n\nremote \u2014 the worlds this one pushes to and fetches from, by name\n  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)\n  volter whoami                                          the platform the CLI is signed into, as whom, and its orgs\n  volter logout                                          revoke the CLI's token at the platform and forget it here\n  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\n  volter open [<org>/<world>] [--no-open]                a World's dashboard: a hosted one through the platform, else this world's (as view)\n  volter completion bash|zsh|fish|powershell             print a completion script for your shell\n  volter remote remove <name>                            forget it\n  volter remote list                                     every remote, with its URL and whether a token is stored\n  (the hosting product's serve answers here for one release: volter remote serve)\n\n  --world <dir>    the world root, when the cwd is not inside it\n  --branch <name>  act on that branch instead of the checked-out one\n  --json           machine-readable output where offered\n  --version        the command's version\n";
+export declare const HELP = "volter \u2014 run your app against a world of twins\n\nworld  \u2014 the twins your app needs, running together (the world of the current directory)\n  volter world init [--install] [--name <world>] [--allow-unknown]   detect the app's vendors (installing their twins when none are), write .volter/world.json\n  volter world up [--sandbox] [--no-seed]                start the twins on this branch (loads the default data the first time)\n  volter world run [--verbose] -- <command...>           run the app or its tests inside the world\n  volter world activate                                  eval \"$(volter world activate)\": vendor CLIs and curl in this shell reach the twins\n  volter world shell                                     a subshell with the world active\n  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\n  volter world serve [--port <p>] [--console-port <c>] [--origin <url>]   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)\n  volter world view [--port <p>] [--host <h>] [--no-open] [--no-origins] [--origin <url>]   step into this world in a browser: its twins' own UIs, timeline, clock, branches (a non-loopback --host serves them on one origin)\n  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\n  volter world status                                    world, branch, origin, unpushed changes, what is running\n  volter world log [--receipts] [--json]                 every write the app made; --receipts adds each change's receipt\n  volter world diff [--json]                             what changed since the default data (or the last mark)\n  volter world seed                                      load the default data\n  volter world reset                                     back to the default data\n  volter world down [--purge]                            stop the twins (--purge forgets this branch's state)\n  volter world branch [<name>]                           list branches, or make one from here and check it out\n  volter world checkout <name>                           switch branches\n  volter world replay <changeset> --into <branch>        feed a changeset's changes into another branch's twins\n  volter world clock show | set <iso> | advance <N s|m|h|d> | shift <N s|m|h|d> | clear   the world's clock: set, not observed\n  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)\n  volter world fetch                                     what the remote observed since the last fetch\n  volter world origin                                    where this world clones from and pushes to\n  volter world changeset [<name>] -m \"<message>\"         cut the unpushed changes into a reviewable changeset\n  volter world pull [--token <token>]                    fetch, then move this branch onto what came in (git's pull)\n  volter world push [<name>] [--token <token>] [--force] push to the remote, which deploys and answers with receipts\n  volter world rebase [<changeset>]                      rebase this branch onto its moved base, or a changeset onto the moved remote\n  volter world verify <changeset>                        run the world's checks over a changeset and record the result\n  volter world approve <changeset> --as <principal>      sign a changeset's current hash\n  volter world deploy [<changeset>]                      perform landed changes against each twin's root, by its policy\n\ntwin   \u2014 one twin: in this world, or on its own\n  volter twin submit --source <id> --vendor <vendor> --package <name> --version <exact>  prepare a catalog submission\n  volter twin <vendor>                                   the twin's URL, root, deploy policy, whether a credential is sealed\n  volter twin <vendor> root <url> [--deploy auto|gated|hold] [--scope <path>]   the vendor's real account behind this twin (--none clears it)\n  volter twin <vendor> credential                        seal a credential read from stdin beside the world; never readable back\n  volter twin <vendor> refresh                           observe the root now\n  volter twin <vendor> serve [--port <p>] [--read-only]  serve the twin; your SDK talks to it at http://127.0.0.1:<p>\n\nagents \u2014 your coding agent, driving the same verbs\n  volter agents install [--claude] [--cursor] [--vscode] [--codex] [--yes]   put the volter-world skill and the MCP server into the agents found here\n  volter mcp                                             the MCP server (stdio) an agent starts: the verbs above as tools\n\nremote \u2014 the worlds this one pushes to and fetches from, by name\n  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)\n  volter whoami                                          the platform the CLI is signed into, as whom, and its orgs\n  volter logout                                          revoke the CLI's token at the platform and forget it here\n  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\n  volter open [<org>/<world>] [--no-open]                a World's dashboard: a hosted one through the platform, else this world's (as view)\n  volter completion bash|zsh|fish|powershell             print a completion script for your shell\n  volter remote remove <name>                            forget it\n  volter remote list                                     every remote, with its URL and whether a token is stored\n  (the hosting product's serve answers here for one release: volter remote serve)\n\n  --world <dir>    the world root, when the cwd is not inside it\n  --branch <name>  act on that branch instead of the checked-out one\n  --json           machine-readable output where offered\n  --version        the command's version\n";

package/dist/src/cli.js

@@ -3,7 +3,7 @@
 // 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 { detectRepoVendors, errorMessage, formatInitReport, resolveCatalog, findInstalledPackage, packCli, serveConsoleFor } from '@volter/world-runtime';
+import { detectRepoVendors, errorMessage, formatInitReport, resolveCatalog, findInstalledPackage, packCli, serveConsoleFor, catalogDefaults, CATALOG_INDEX_PACKAGE } from '@volter/world-runtime';
 import { readFileSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { spawn, spawnSync } from 'node:child_process';
@@ -70,6 +70,7 @@ world  — the twins your app needs, running together (the world of the current
   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 submit --source <id> --vendor <vendor> --package <name> --version <exact>  prepare a catalog submission
   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
@@ -595,6 +596,14 @@ async function worldCommand(verb, args) {
 /** `volter twin <vendor> <verb…>`: the twin's own CLI (serve), found the way a world finds it. */
 async function twinCommand(args) {
     const [vendor, ...rest] = args;
+    if (vendor === 'submit') {
+        const catalog = findInstalledPackage(process.cwd(), CATALOG_INDEX_PACKAGE);
+        const cli = catalog && join(catalog, 'bin', 'twin-catalog.mjs');
+        if (!cli || !existsSync(cli))
+            throw new Error('Install @volter/twin-catalog to submit a twin; its catalog-owned CLI prepares the submission file.');
+        process.exitCode = await passthrough([process.execPath, cli, 'submit', ...rest]);
+        return;
+    }
     if (!vendor || vendor.startsWith('-'))
         throw new Error('volter twin: which twin? (volter twin stripe serve --port 12111)');
     const verb = rest[0];
@@ -965,19 +974,30 @@ ${Object.entries(tree).map(([n, v]) => `    '${n}' = @(${v.map((x) => `'${x}'`).
  *  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) {
+    let installed = new Set();
     try {
-        if (resolveCatalog(app).vendors().length > 0)
-            return;
+        installed = new Set(resolveCatalog(app).vendors());
+    }
+    catch (error) {
+        if (!(error instanceof Error) || !error.message.startsWith('No twins found for '))
+            throw error;
     }
-    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();
+    const vendors = [...found.keys()].filter((v) => !installed.has(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 index = findInstalledPackage(app, CATALOG_INDEX_PACKAGE) ?? findInstalledPackage(fileURLToPath(new URL('.', import.meta.url)), CATALOG_INDEX_PACKAGE);
+    const recommended = index ? catalogDefaults(index, vendors) : undefined;
+    const pkgs = vendors.map((vendor) => {
+        const choice = recommended?.[vendor];
+        if (recommended && !choice)
+            throw new Error(`${vendor}: no approved stable default in the installed catalog; choose an implementation explicitly`);
+        return choice ? `${choice.name}@${choice.version}` : `@volter/twin-${vendor}`;
+    });
     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(' ')}`;
+    const invocation = has('bun.lock') || has('bun.lockb') ? ['bun', 'add', '-d'] : has('pnpm-lock.yaml') ? ['pnpm', 'add', '-D'] : has('yarn.lock') ? ['yarn', 'add', '-D'] : ['npm', 'install', '-D'];
+    const command = [...invocation, ...pkgs].join(' ');
     out(`detected  ${vendors.map((v) => `${v} (${(found.get(v) ?? []).slice(0, 2).join(', ')})`).join('; ')}`);
     out(`twins     ${pkgs.join(' ')}`);
     let yes = install;
@@ -992,7 +1012,7 @@ async function installDetectedTwins(app, install) {
 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
     // a dependency's install script is not Volter's: it never sees the person's vault sign-in
-    const ran = spawnSync(command, { cwd: app, stdio: 'inherit', shell: true, windowsHide: true, env: withoutVaultSignIn(process.env) });
+    const ran = spawnSync(invocation[0], [...invocation.slice(1), ...pkgs], { cwd: app, stdio: 'inherit', windowsHide: true, env: withoutVaultSignIn(process.env) });
     if (ran.status !== 0)
         throw new Error(`${command} failed (exit ${ran.status ?? 'none'})`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world",
-  "version": "3.0.40",
+  "version": "3.0.42",
   "description": "Run your app against a world of twins. `World` and `Repo` — one method per verb: init, up, run, log, diff, reset, branch, checkout, clone, fetch, changeset, push — and the `volter` command, one client of them.",
   "keywords": [
     "volter",
@@ -30,12 +30,12 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.1",
-    "@volter/world-core": "3.0.40",
-    "@volter/world-runtime": "3.0.40",
+    "@volter/world-core": "3.0.42",
+    "@volter/world-runtime": "3.0.42",
     "zod": "^4.6.5"
   },
   "peerDependencies": {
-    "@volter/world-console": "3.0.35"
+    "@volter/world-console": "3.0.37"
   },
   "peerDependenciesMeta": {
     "@volter/world-console": {
@@ -43,7 +43,7 @@
     }
   },
   "devDependencies": {
-    "@volter/world-console": "3.0.35"
+    "@volter/world-console": "3.0.37"
   },
   "bin": {
     "volter": "dist/src/cli.js"

package/src/cli.ts

@@ -3,7 +3,7 @@
 // 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 { detectRepoVendors, errorMessage, formatInitReport, resolveCatalog, findInstalledPackage, packCli, serveConsoleFor } from '@volter/world-runtime';
+import { detectRepoVendors, errorMessage, formatInitReport, resolveCatalog, findInstalledPackage, packCli, serveConsoleFor, catalogDefaults, CATALOG_INDEX_PACKAGE } from '@volter/world-runtime';
 import { readFileSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { spawn, spawnSync } from 'node:child_process';
@@ -62,6 +62,7 @@ world  — the twins your app needs, running together (the world of the current
   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 submit --source <id> --vendor <vendor> --package <name> --version <exact>  prepare a catalog submission
   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
@@ -429,6 +430,13 @@ async function worldCommand(verb: string, args: string[]): Promise<void> {
 /** `volter twin <vendor> <verb…>`: the twin's own CLI (serve), found the way a world finds it. */
 async function twinCommand(args: string[]): Promise<void> {
   const [vendor, ...rest] = args;
+  if (vendor === 'submit') {
+    const catalog = findInstalledPackage(process.cwd(), CATALOG_INDEX_PACKAGE);
+    const cli = catalog && join(catalog, 'bin', 'twin-catalog.mjs');
+    if (!cli || !existsSync(cli)) throw new Error('Install @volter/twin-catalog to submit a twin; its catalog-owned CLI prepares the submission file.');
+    process.exitCode = await passthrough([process.execPath, cli, 'submit', ...rest]);
+    return;
+  }
   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
@@ -703,14 +711,24 @@ ${Object.entries(tree).map(([n, v]) => `    '${n}' = @(${v.map((x) => `'${x}'`).
  *  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: string, install: boolean): Promise<void> {
-  try { if (resolveCatalog(app).vendors().length > 0) return; } catch { /* no twins here yet */ }
+  let installed = new Set<string>();
+  try { installed = new Set(resolveCatalog(app).vendors()); } catch (error) {
+    if (!(error instanceof Error) || !error.message.startsWith('No twins found for ')) throw error;
+  }
   const found = detectRepoVendors(app).detected;
-  const vendors = [...found.keys()].filter((v) => /^[a-z0-9][a-z0-9-]*$/.test(v)).sort();
+  const vendors = [...found.keys()].filter((v) => !installed.has(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 index = findInstalledPackage(app, CATALOG_INDEX_PACKAGE) ?? findInstalledPackage(fileURLToPath(new URL('.', import.meta.url)), CATALOG_INDEX_PACKAGE);
+  const recommended = index ? catalogDefaults(index, vendors) : undefined;
+  const pkgs = vendors.map((vendor) => {
+    const choice = recommended?.[vendor];
+    if (recommended && !choice) throw new Error(`${vendor}: no approved stable default in the installed catalog; choose an implementation explicitly`);
+    return choice ? `${choice.name}@${choice.version}` : `@volter/twin-${vendor}`;
+  });
   const has = (file: string): boolean => 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(' ')}`;
+  const invocation = has('bun.lock') || has('bun.lockb') ? ['bun', 'add', '-d'] : has('pnpm-lock.yaml') ? ['pnpm', 'add', '-D'] : has('yarn.lock') ? ['yarn', 'add', '-D'] : ['npm', 'install', '-D'];
+  const command = [...invocation, ...pkgs].join(' ');
   out(`detected  ${vendors.map((v) => `${v} (${(found.get(v) ?? []).slice(0, 2).join(', ')})`).join('; ')}`);
   out(`twins     ${pkgs.join(' ')}`);
   let yes = install;
@@ -724,7 +742,7 @@ async function installDetectedTwins(app: string, install: boolean): Promise<void
 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
   // a dependency's install script is not Volter's: it never sees the person's vault sign-in
-  const ran = spawnSync(command, { cwd: app, stdio: 'inherit', shell: true, windowsHide: true, env: withoutVaultSignIn(process.env) });
+  const ran = spawnSync(invocation[0]!, [...invocation.slice(1), ...pkgs], { cwd: app, stdio: 'inherit', windowsHide: true, env: withoutVaultSignIn(process.env) });
   if (ran.status !== 0) throw new Error(`${command} failed (exit ${ran.status ?? 'none'})`);
 }