@volter/world 3.0.185 → 3.0.186

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;