@volter/world 3.0.184 → 3.0.186

package/src/cli.ts

@@ -3,16 +3,16 @@
 // 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, catalogDefaults, CATALOG_INDEX_PACKAGE } from '@volter/world-runtime';
-import { readFileSync, realpathSync } from 'node:fs';
+import { isBuiltinTwinVendor, detectRepoVendors, errorMessage, formatInitReport, resolveCatalog, findInstalledPackage, packCli, serveConsoleFor, catalogDefaults, CATALOG_INDEX_PACKAGE } from '@volter/world-runtime';
+import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { spawn, spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { hostname } from 'node:os';
-import { formatLedgerDelta, inWorldHistory, isWorldPerson, shownPersonFields } from '@volter/world-core/runtime';
+import { inWorldHistory, isWorldPerson, shownPersonFields } from '@volter/world-core/runtime';
 import { existsSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
-import { forgetPlatform, forgetToken, platformOrigin, requireToken, storePlatform, storeToken, tokenFor } from './credentials.ts';
+import { forgetPlatform, forgetToken, platformOrigin, storePlatform, storeToken, tokenFor } from './credentials.ts';
 import { parseOriginUrl, World } from './world.ts';
 import { copyExample, examples } from './examples.ts';
 import { waitForServeShutdown } from './serve-shutdown.ts';
@@ -31,9 +31,10 @@ function openInBrowser(url: string): void {
 
 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)
+world  — a shared simulated internet (the world of the current directory)
   volter world init [--install] [--name <world>] [--twins a,b] [--source vendor=package] [--allow-unknown]   detect or select vendors, choose installed publishers, 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 env [--template <file>]                    render deployment .env.world references into dotenv files
   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
@@ -98,6 +99,10 @@ function value(args: string[], name: string): string | undefined {
   const i = args.indexOf(name);
   return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
 }
+function values(args: string[]): string[] | undefined {
+  const found = args.flatMap((arg, index) => arg === '--template' && args[index + 1] ? [args[index + 1]!] : []);
+  return found.length ? found : undefined;
+}
 function positionals(args: string[], valueFlags: string[]): string[] {
   const out: string[] = [];
   for (let i = 0; i < args.length; i += 1) {
@@ -109,7 +114,7 @@ function positionals(args: string[], valueFlags: string[]): string[] {
   return out;
 }
 function afterDashes(args: string[]): string[] { const i = args.indexOf('--'); return i < 0 ? [] : args.slice(i + 1); }
-const VALUE_FLAGS = ['--world', '--branch', '--name', '--token', '--admin-token', '-m', '--message', '--base', '--org', '--vendors', '--into', '--deploy', '--as', '--note', '--port', '--twins', '--source', '--host', '--origin', '--remote', '--dir', '--scope', '--refresh', '--at-most', '--at'];
+const VALUE_FLAGS = ['--world', '--branch', '--name', '--token', '--admin-token', '-m', '--message', '--base', '--org', '--vendors', '--into', '--deploy', '--as', '--note', '--port', '--twins', '--source', '--host', '--origin', '--remote', '--dir', '--scope', '--refresh', '--at-most', '--at', '--template', '--output-root', '--app', '--app-url', '--template-out'];
 
 /** Help is resolved before opening a World; the child after `run --` owns its own flags. */
 function wantsHelp(noun: string | undefined, verb: string | undefined, args: string[]): boolean {
@@ -130,7 +135,6 @@ function subjectLabel(subject: { type: string; id: string }): string {
 }
 function out(text: string): void { process.stdout.write(text.endsWith('\n') ? text : `${text}\n`); }
 function json(value: unknown): void { out(JSON.stringify(value, null, 2)); }
-function when(iso: string): string { return iso.slice(11, 23); }
 
 /** Run another CLI in the foreground and adopt its exit code; a signal to us is a signal to it. */
 async function passthrough(cmd: string[], cwd = process.cwd()): Promise<number> {
@@ -153,9 +157,11 @@ async function stdinText(): Promise<string> {
 }
 
 async function worldCommand(verb: string, args: string[]): Promise<void> {
-  const worldDir = value(args, '--world');
+  const boundary = args.indexOf('--');
+  const parentOptions = verb === 'run' && boundary >= 0 ? args.slice(0, boundary) : args;
+  const worldDir = value(parentOptions, '--world') ?? (verb === 'up' ? positionals(args, VALUE_FLAGS)[0] : undefined);
   const pos = positionals(args, VALUE_FLAGS);
-  const asJson = flag(args, '--json');
+  const asJson = flag(parentOptions, '--json');
 
   if (verb === 'init' && flag(args, '--bare')) {
     if (args.some(arg => arg === '--source' || arg.startsWith('--source='))) throw new Error('--source selects installed publishers for app initialization; omit --bare and use world init --twins <vendors> --source vendor=package');
@@ -172,7 +178,7 @@ async function worldCommand(verb: string, args: string[]): Promise<void> {
     const app = resolve(worldDir ?? process.cwd());
     const selection = initSelection(args);
     await installDetectedTwins(app, flag(args, '--install'), selection);
-    const { result } = World.init(app, { ...selection, ...(value(args, '--name') ? { name: value(args, '--name')! } : {}), force: flag(args, '--force'), allowUnknown: flag(args, '--allow-unknown') });
+    const { result } = World.init(app, { ...selection, ...(value(args, '--name') ? { name: value(args, '--name')! } : {}), force: flag(args, '--force'), update: flag(args, '--update'), templateOut: value(args, '--template-out'), 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();
@@ -199,7 +205,7 @@ async function worldCommand(verb: string, args: string[]): Promise<void> {
     process.exit(0);
   }
 
-  const world = World.open({ ...(worldDir ? { root: worldDir } : {}), ...(value(args, '--branch') ? { name: value(args, '--branch')! } : {}) });
+  const world = World.open({ ...(worldDir ? { root: worldDir } : {}), ...(value(parentOptions, '--branch') ? { name: value(parentOptions, '--branch')! } : {}) });
 
   switch (verb) {
     case 'up': {
@@ -219,6 +225,13 @@ async function worldCommand(verb: string, args: string[]): Promise<void> {
     }
     case 'activate': { process.stdout.write(world.activateScript()); return; }
     case 'shell': { process.exitCode = await world.shell(); return; }
+    case 'env': {
+      const result = await world.env({ templates: values(args), outputRoot: value(args, '--output-root'), app: value(args, '--app'), appUrl: value(args, '--app-url') });
+      // Admission payloads are private. CLI output reports paths and hashes only.
+      if (asJson) json({ deploymentId: result.deploymentId, outputs: result.outputs.map(({ contents: _private, ...output }) => output) });
+      else for (const output of result.outputs) out(`wrote  ${output.target}`);
+      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)');
@@ -226,7 +239,12 @@ async function worldCommand(verb: string, args: string[]): Promise<void> {
       let running = false; try { running = world.instance()?.running ?? false; } catch { /* never started */ }
       if (!running) { process.stderr.write(`${world.name} is not running: starting it (volter world up)
 `); await world.up({ seed: true }); }
-      process.exitCode = await world.run(command, { verbose: flag(args.slice(0, args.indexOf('--')), '--verbose') });
+      process.exitCode = await world.run(command, {
+        verbose: flag(parentOptions, '--verbose'),
+        templates: values(parentOptions),
+        app: value(parentOptions, '--app'),
+        appUrl: value(parentOptions, '--app-url'),
+      });
       return;
     }
     case 'status': {
@@ -659,9 +677,8 @@ async function remoteCommand(verb: string, args: string[]): Promise<void> {
         // (docs/contributing/architecture.md, "The way in is the app's folder")
         if (made && world.hasSeed()) {
           const seeded = await world.seedServed(body.base, body.token);
-          const issued = Object.entries(seeded.issued).map(([vendor, names]) => `${names.join(', ')} from ${vendor}`);
           if (seeded.exitCode !== 0) throw new Error(`the seed failed on ${served} (${seeded.entry} exited ${seeded.exitCode}): it holds what the seed wrote before it stopped, and is not marked`);
-          out(`seeded   ${served}  ${relative(world.root, seeded.entry)}  through its own twins${issued.length ? ` (${issued.join('; ')}, issued there)` : ''}`);
+          out(`seeded   ${served}  ${relative(world.root, seeded.entry)}  through its own twins`);
           out(`marked   ${served}  its seed is where its changes count from${seeded.mark?.passed ? ` (${seeded.mark.passed} written by the seed)` : ''}`);
         }
         return;
@@ -774,13 +791,13 @@ function initSelection(args: string[]): { vendors?: string[]; sources: Record<st
   return { ...(vendors ? { vendors } : {}), sources };
 }
 
-async function installDetectedTwins(app: string, install: boolean, selection: { vendors?: string[]; sources?: Record<string, string> } = {}): Promise<void> {
+async function installDetectedTwins(app: string, install: boolean, selection: { vendors?: string[]; sources?: Record<string, string> }): Promise<void> {
   let installed = new Set<string>();
   try { installed = new Set(resolveCatalog(app, selection).vendors()); } catch (error) {
     if (!(error instanceof Error) || !error.message.startsWith('No twins found for ')) throw error;
   }
   const found = detectRepoVendors(app).detected;
-  const vendors = (selection.vendors ?? [...found.keys()]).filter((v) => !installed.has(v) && /^[a-z0-9][a-z0-9-]*$/.test(v)).sort();
+  const vendors = (selection.vendors ?? [...found.keys()]).filter((v) => !installed.has(v) && (selection.sources?.[v] !== undefined || !isBuiltinTwinVendor(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 index = findInstalledPackage(app, CATALOG_INDEX_PACKAGE) ?? findInstalledPackage(fileURLToPath(new URL('.', import.meta.url)), CATALOG_INDEX_PACKAGE);
   const recommended = index ? catalogDefaults(index, vendors) : undefined;

package/src/locate.ts

@@ -1,5 +1,5 @@
-// Where the world is (docs/concepts/worlds.md#the-config-and-the-running-world): the nearest `.volter/world.json`
-// above the cwd names the world root — the app repo — and `.volter/current` names the branch that
+// Where the world is (docs/concepts/worlds.md#the-config-and-the-running-world): the nearest standard
+// World folder or `.volter/world.json` above the cwd names the root; `.volter/current` names the branch that
 // is checked out (absent: the main branch, the config's `id`). Every `volter` verb and
 // `World.open()` start here, the way `git` starts from the nearest `.git`.
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
@@ -11,15 +11,19 @@ export const WORLD_FILE = 'world.json';
 
 /** `<root>/.volter` */
 export function stateDir(root: string): string { return join(root, stateDirName()); }
-/** `<root>/.volter/world.json` — the config, relative to the root as `up` takes it. */
+/** The in-repository config path used by initialization. */
 export function worldConfigRelative(): string { return join(stateDirName(), WORLD_FILE); }
-export function worldConfigPath(root: string): string { return join(stateDir(root), WORLD_FILE); }
+/** A standalone World keeps its config at the folder root; an in-repository World uses `.volter`. */
+export function worldConfigPath(root: string): string {
+  const standard = join(root, WORLD_FILE);
+  return existsSync(standard) ? standard : join(stateDir(root), WORLD_FILE);
+}
 /** `<root>/.volter/world.env` — where `up` writes the live env (gitignored by init). */
 export function worldEnvPath(root: string): string { return join(stateDir(root), 'world.env'); }
-/** `<root>/.volter/seed.ts` — the default data, when the world has any. */
-export function worldSeedPath(root: string): string { return join(stateDir(root), 'seed.ts'); }
+/** The standard seed lives beside the selected config. */
+export function worldSeedPath(root: string): string { return join(dirname(worldConfigPath(root)), 'seed.ts'); }
 
-/** The world root above `from`, or null: the nearest directory holding `.volter/world.json`. */
+/** The nearest directory holding a standard World config. */
 export function findWorldRoot(from: string = process.cwd()): string | null {
   let dir = resolve(from);
   for (;;) {
@@ -33,7 +37,7 @@ export function findWorldRoot(from: string = process.cwd()): string | null {
 export function requireWorldRoot(from: string = process.cwd()): string {
   const root = findWorldRoot(from);
   if (root === null) {
-    throw new Error(`Not in a world: no ${worldConfigRelative()} here or above ${resolve(from)}. Run \`volter world init\` in your app, or pass --world <dir>.`);
+    throw new Error(`Not in a world: no world.json or ${worldConfigRelative()} here or above ${resolve(from)}. Run \`volter world init\` in your app, or pass --world <folder>.`);
   }
   return root;
 }

package/src/world.ts

@@ -1,9 +1,10 @@
+import { renderDeploymentTemplates, type DeploymentTemplate } from '@volter/world-runtime/deployment-env';
 // WORLD — the twins an app needs, running together (docs/concepts/the-model.md,
 // docs/concepts/worlds.md#the-config-and-the-running-world): a branch with compute attached. `World.open()` finds the world of the cwd the
 // way git finds its repository; every method is a name for a world-runtime verb, in the words a
 // user reads. The `volter` command is one client of this class and adds nothing.
 import { platformPerson } from './credentials.ts';
-import { rebaseChangeset, worldBootMarker, type Changeset, type ChangesetApplication, type LedgerDelta, type PerformAction, type RemoteExecute, type TwinAction, type WorldMarker, type ApplyReceipt, listActions, inWorldHistory, pushablePendingActions, pendingActions, applyTwinWrite, twinResources, type TwinResource } from '@volter/world-core/runtime';
+import { rebaseChangeset, worldBootMarker, type Changeset, type LedgerDelta, type TwinAction, type WorldMarker, type ApplyReceipt, listActions, inWorldHistory, pushablePendingActions, pendingActions, applyTwinWrite, twinResources, type TwinResource } from '@volter/world-core/runtime';
 import { spawnSync } from 'node:child_process';
 import clockForm from '@volter/world-core/world-clock';
 import {
@@ -15,7 +16,7 @@ import {
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { requireToken, storeToken } from './credentials.ts';
-import { currentBranch, findWorldRoot, mainBranch, requireWorldRoot, setCurrentBranch, worldConfigRelative, worldEnvPath, worldSeedPath } from './locate.ts';
+import { currentBranch, findWorldRoot, mainBranch, requireWorldRoot, setCurrentBranch, worldConfigPath, worldEnvPath, worldSeedPath } from './locate.ts';
 import { destinationOf, parentEntries, rebaseBranch, type Receipt, type RootConfig } from '@volter/world-core/runtime';
 
 export type WorldRef = { name?: string; root?: string };
@@ -65,8 +66,8 @@ export function parseOriginUrl(url: string, worldRoot = process.cwd()): { url: s
   // a PATH is a world on this machine (git's file transport): its directory, and its served name
   if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(url)) {
     const root = resolve(worldRoot, url);
-    const configPath = join(root, '.volter', 'world.json');
-    if (!existsSync(configPath)) throw new Error(`Not a remote URL or world directory: ${url} (want https://<host>/<org>/<world>, or a directory holding .volter/world.json)`);
+    const configPath = worldConfigPath(root);
+    if (!existsSync(configPath)) throw new Error(`Not a remote URL or world directory: ${url} (want https://<host>/<org>/<world>, or a standard World folder)`);
     const config = loadWorldConfig(configPath, root).config;
     return { url: root, namespace: config.bare?.name ?? `${config.id}/${config.id}` };
   }
@@ -80,14 +81,14 @@ export function parseOriginUrl(url: string, worldRoot = process.cwd()): { url: s
 export class World {
   /** The branch this handle is on — the instance name in the kernel. */
   readonly name: string;
-  /** The world root: the app repo. */
+  /** The World folder, or the repository holding its `.volter` config. */
   readonly root: string;
   private constructor(name: string, root: string) { this.name = name; this.root = root; }
 
   // ── finding and making worlds ───────────────────────────────────────────────────────────
   /** The world of the cwd (or of `ref.root`), on its checked-out branch (or `ref.name`). */
   /** The config `loadWorldConfig` resolves for this world: the in-repo world.json, else the world's name. */
-  private configRef(): string { const inRepo = join(this.root, '.volter', 'world.json'); return existsSync(inRepo) ? inRepo : this.name; }
+  private configRef(): string { const config = worldConfigPath(this.root); return existsSync(config) ? config : this.name; }
 
   static open(ref: WorldRef = {}): World {
     const root = ref.root === undefined ? requireWorldRoot() : requireWorldRoot(ref.root);
@@ -133,35 +134,28 @@ export class World {
    * stops compute, up resumes it — `reset` is the way back to the default data); a fresh branch
    * boots clean and loads the default data unless `seed: false`.
    */
-  async up(opts: { mode?: WorldMode; seed?: boolean; cwd?: string } = {}): Promise<WorldInstance> {
+  async up(opts: { mode?: WorldMode; seed?: boolean } = {}): Promise<WorldInstance> {
     const existing = this.instance();
     if (existing?.running) return existing; // already up: nothing to do
-    const instance = await upWorld(worldConfigRelative(), {
+    const instance = await upWorld(this.configRef(), {
       name: this.name, root: this.root, envFile: existing?.envFile ?? worldEnvPath(this.root),
       ...(opts.mode ? { mode: opts.mode } : existing ? { mode: existing.mode } : {}),
-      ...(existing ? { keepState: true } : {}),
+      ...(existing ? { keepState: true } : {}), seed: opts.seed,
     });
-    await this.finishStartup(instance, existing === null, opts);
     return instance;
   }
-  /** Product startup completes its seed sequence; the runtime owns only the boot. */
-  private async finishStartup(instance: WorldInstance, fresh: boolean, opts: { seed?: boolean; cwd?: string } = {}): Promise<void> {
-    try {
-      if (fresh && opts.seed !== false && existsSync(worldSeedPath(this.root))) {
-        // a story that fails is a loud failure: the world is up, but not the world the app expects
-        const seeded = await seedWorld(this.name, { root: this.root, cwd: opts.cwd ?? this.root });
-        if (seeded.exitCode !== 0) throw new Error(`the story failed (${seeded.entry} exited ${seeded.exitCode}); state may be partially seeded — fix the seed, start this World and run \`volter world seed\``);
-      }
-    } finally {
-      // a root set while the world was stopped reaches the twins' state after the default data (which a
-      // fresh boot runs simulated), where the deploy reads it — also when the seed failed
-      materializeRoots(loadWorldConfig(this.configRef(), this.root).config, instance.dirs.data, this.root);
-    }
-  }
   /** Stop the twins; the branch's state stays (`up` resumes). `purge` forgets it. */
   down(opts: { purge?: boolean } = {}): ReturnType<typeof downWorld> { return downWorld(this.name, this.root, opts); }
   /** Run a command inside the world: the app or its tests, with the twins' URLs and fake credentials in its env. */
-  run(command: string[], opts: { cwd?: string; verbose?: boolean } = {}): Promise<number> { return runWithWorldEnv(this.name, command, this.root, { ...opts, cwd: opts.cwd ?? this.root }); }
+  async run(command: string[], opts: { cwd?: string; verbose?: boolean; templates?: DeploymentTemplate[]; app?: string; appUrl?: string } = {}): Promise<number> {
+    const cwd = opts.cwd ?? process.cwd();
+    const rendered = await renderDeploymentTemplates({ world: { name: this.name, root: this.root }, sourceRoot: cwd, mode: 'process', templates: opts.templates, app: opts.app, appUrl: opts.appUrl });
+    return runWithWorldEnv(this.name, command, this.root, { cwd, verbose: opts.verbose, env: rendered.env });
+  }
+  /** Render deployment templates into their selected dotenv files. */
+  env(opts: { cwd?: string; outputRoot?: string; templates?: DeploymentTemplate[]; app?: string; appUrl?: string } = {}): ReturnType<typeof renderDeploymentTemplates> {
+    return renderDeploymentTemplates({ world: { name: this.name, root: this.root }, sourceRoot: opts.cwd ?? process.cwd(), outputRoot: opts.outputRoot, mode: 'files', templates: opts.templates, app: opts.app, appUrl: opts.appUrl });
+  }
   /** The shell script that activates the world in the current shell: `eval "$(volter world activate)"` — vendor CLIs and curl reach the twins. */
   activateScript(): string { return activateScript(this.name, this.root); }
   /** A subshell with the world active; resolves to its exit code. */
@@ -364,7 +358,6 @@ export class World {
   serve(opts: { port?: number; host?: string; consolePort?: number; announce?: (info: { name: string; base: string; token: string; readToken: string; console: string | null }) => void } = {}): Promise<ServedWorld> { return serveWorld(this.name, { root: this.root, ...opts }); }
   /** `volter world view`: this World, its twins' screens, its branches and the console on one origin (docs/contributing/architecture.md, "Viewing a World"). */
   async view(opts: { port?: number; host?: string; console?: ViewConsole; announce?: (line: string) => void; origins?: boolean; origin?: string } = {}): Promise<WorldView> {
-    const fresh = this.instance() === null;
     const person = platformPerson();
     const announced: string[] = [];
     let ready = false;
@@ -372,7 +365,6 @@ export class World {
     try {
       const instance = this.instance();
       if (!instance) throw new Error('the viewer started without a recorded World instance');
-      await this.finishStartup(instance, fresh);
       for (const line of announced) opts.announce?.(line);
       ready = true;
       return view;