@volter/world 2.0.0

package/dist/src/credentials.d.ts

@@ -0,0 +1,12 @@
+/** `$XDG_CONFIG_HOME/volter/credentials.json`, else `~/.config/volter/credentials.json`. */
+export declare function credentialsPath(): string;
+/** The token stored for an origin, or undefined. */
+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;
+/** `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;
+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

@@ -0,0 +1,64 @@
+// Tokens, not keys (docs/concepts/worlds.md#the-config-and-the-running-world): the remote's read and admin
+// credentials are TOKENS, kept in the user's config directory keyed by origin URL — written by
+// `clone --token`, read by `fetch` and `push`. Nothing in the repo and nothing in the world holds
+// one; "key" means only the vendor's real API key, which lives in the remote's custody.
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** `$XDG_CONFIG_HOME/volter/credentials.json`, else `~/.config/volter/credentials.json`. */
+export function credentialsPath() {
+    const base = process.env.XDG_CONFIG_HOME && process.env.XDG_CONFIG_HOME !== '' ? process.env.XDG_CONFIG_HOME : join(homedir(), '.config');
+    return join(base, 'volter', 'credentials.json');
+}
+function normalizeOrigin(url) { return url.replace(/\/+$/, ''); }
+function readStore(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        throw new Error(`${path} is not readable as JSON — fix or delete it`);
+    }
+}
+/** The token stored for an origin, or undefined. */
+export function tokenFor(origin, path = credentialsPath()) {
+    return readStore(path)[normalizeOrigin(origin)]?.token;
+}
+/** Store a token for an origin (0600). */
+export function storeToken(origin, token, path = credentialsPath()) {
+    if (token === '')
+        throw new Error('an empty token cannot be stored');
+    const store = readStore(path);
+    store[normalizeOrigin(origin)] = { token, savedAt: new Date().toISOString() };
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+/** `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 });
+}
+export function platformOrigin(path = platformPath()) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8')).url;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The token a verb uses: an explicit one for this call (CI), else the stored one, else a clear error. */
+export function requireToken(origin, explicit, path = credentialsPath()) {
+    if (explicit !== undefined && explicit !== '')
+        return explicit;
+    if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(origin))
+        return ''; // a world at a path needs no token
+    const stored = tokenFor(origin, path);
+    if (stored === undefined)
+        throw new Error(`No token stored for ${normalizeOrigin(origin)} — \`volter world clone <url> --token <token>\` stores one, or pass --token for this call`);
+    return stored;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export { World, parseOriginUrl, worldNameFor, type LogEntry, type WorldMode, type WorldRef, type WorldStatus } from './world.js';
+export { findWorldRoot, requireWorldRoot, currentBranch, setCurrentBranch, mainBranch, worldConfigPath, worldEnvPath, worldSeedPath, WORLD_FILE } from './locate.js';
+export { credentialsPath, requireToken, storeToken, tokenFor } from './credentials.js';

package/dist/src/index.js

@@ -0,0 +1,6 @@
+// @volter/world — the product surface (docs/concepts/the-model.md, docs/concepts/worlds.md#the-config-and-the-running-world):
+// World and Repo, one method per verb in the user's words, over core and the kernel, with no
+// mechanism of its own. The `volter` command is one client of this package.
+export { World, parseOriginUrl, worldNameFor } from "./world.js";
+export { findWorldRoot, requireWorldRoot, currentBranch, setCurrentBranch, mainBranch, worldConfigPath, worldEnvPath, worldSeedPath, WORLD_FILE } from "./locate.js";
+export { credentialsPath, requireToken, storeToken, tokenFor } from "./credentials.js";

package/dist/src/locate.d.ts

@@ -0,0 +1,18 @@
+export declare const WORLD_FILE = "world.json";
+/** `<root>/.volter` */
+export declare function stateDir(root: string): string;
+/** `<root>/.volter/world.json` — the config, relative to the root as `up` takes it. */
+export declare function worldConfigRelative(): string;
+export declare function worldConfigPath(root: string): string;
+/** `<root>/.volter/world.env` — where `up` writes the live env (gitignored by init). */
+export declare function worldEnvPath(root: string): string;
+/** `<root>/.volter/seed.ts` — the default data, when the world has any. */
+export declare function worldSeedPath(root: string): string;
+/** The world root above `from`, or null: the nearest directory holding `.volter/world.json`. */
+export declare function findWorldRoot(from?: string): string | null;
+export declare function requireWorldRoot(from?: string): string;
+/** The main branch: the config's `id`. */
+export declare function mainBranch(root: string): string;
+/** The checked-out branch: `.volter/current`, else main. */
+export declare function currentBranch(root: string): string;
+export declare function setCurrentBranch(root: string, name: string): void;

package/dist/src/locate.js

@@ -0,0 +1,60 @@
+// 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
+// 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';
+import { dirname, join, resolve } from 'node:path';
+import { stateDirName } from '@volter/world-core';
+import { loadWorldConfig } from '@volter/world-runtime';
+export const WORLD_FILE = 'world.json';
+/** `<root>/.volter` */
+export function stateDir(root) { return join(root, stateDirName()); }
+/** `<root>/.volter/world.json` — the config, relative to the root as `up` takes it. */
+export function worldConfigRelative() { return join(stateDirName(), WORLD_FILE); }
+export function worldConfigPath(root) { return join(stateDir(root), WORLD_FILE); }
+/** `<root>/.volter/world.env` — where `up` writes the live env (gitignored by init). */
+export function worldEnvPath(root) { return join(stateDir(root), 'world.env'); }
+/** `<root>/.volter/seed.ts` — the default data, when the world has any. */
+export function worldSeedPath(root) { return join(stateDir(root), 'seed.ts'); }
+/** The world root above `from`, or null: the nearest directory holding `.volter/world.json`. */
+export function findWorldRoot(from = process.cwd()) {
+    let dir = resolve(from);
+    for (;;) {
+        if (existsSync(worldConfigPath(dir)))
+            return dir;
+        const up = dirname(dir);
+        if (up === dir)
+            return null;
+        dir = up;
+    }
+}
+export function requireWorldRoot(from = process.cwd()) {
+    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>.`);
+    }
+    return root;
+}
+/** The main branch: the config's `id`. */
+export function mainBranch(root) {
+    return loadWorldConfig(worldConfigPath(root), root).config.id;
+}
+const CURRENT = 'current';
+/** The checked-out branch: `.volter/current`, else main. */
+export function currentBranch(root) {
+    const file = join(stateDir(root), CURRENT);
+    if (!existsSync(file))
+        return mainBranch(root);
+    const name = readFileSync(file, 'utf8').trim();
+    return name === '' ? mainBranch(root) : name;
+}
+export function setCurrentBranch(root, name) {
+    mkdirSync(stateDir(root), { recursive: true });
+    const file = join(stateDir(root), CURRENT);
+    if (name === mainBranch(root)) {
+        if (existsSync(file))
+            rmSync(file);
+        return;
+    }
+    writeFileSync(file, `${name}\n`);
+}

package/dist/src/serve-shutdown.d.ts

@@ -0,0 +1,6 @@
+import type { EventEmitter } from 'node:events';
+/** Signals request one shutdown; repeated signals never start a competing World teardown. */
+export declare function waitForServeShutdown(stop: () => Promise<void>, options?: {
+    signals?: Pick<EventEmitter, 'on' | 'off'>;
+    timeoutMs?: number;
+}): Promise<void>;

package/dist/src/serve-shutdown.js

@@ -0,0 +1,27 @@
+/** Signals request one shutdown; repeated signals never start a competing World teardown. */
+export async function waitForServeShutdown(stop, options = {}) {
+    const signals = options.signals ?? process;
+    const names = ['SIGTERM', 'SIGINT', 'SIGHUP'];
+    let started = false;
+    let timer;
+    let request;
+    try {
+        await new Promise((resolve, reject) => {
+            request = () => {
+                if (started)
+                    return;
+                started = true;
+                timer = setTimeout(() => reject(new Error('World serve shutdown timed out; cleanup incomplete, instance and reservation retained for explicit down')), options.timeoutMs ?? 8000);
+                Promise.resolve().then(stop).then(resolve, reject);
+            };
+            for (const name of names)
+                signals.on(name, request);
+        });
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        for (const name of names)
+            signals.off(name, request);
+    }
+}

package/dist/src/world.d.ts

@@ -0,0 +1,299 @@
+import { rebaseChangeset, worldBootMarker, type Changeset, type LedgerDelta, type TwinAction, type WorldMarker, type ApplyReceipt, applyTwinWrite, type TwinResource } from '@volter/world-core';
+import { approveWorldChangeset, createWorldChangeset, downWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, replayWorldChangeset, resetWorld, seedWorld, statusWorldChangeset, verifyWorldChangeset, type ServedWorld, type DeployTwinOutcome, type ChangesetLocation, type InitOptions, type InitResult, type WorldInstance } from '@volter/world-runtime';
+import { rebaseBranch, type Receipt, type RootConfig } from '@volter/world-core';
+export type WorldRef = {
+    name?: string;
+    root?: string;
+};
+export type WorldMode = 'local' | 'share' | 'sealed';
+/** One change as `log` shows it: the write, and the receipt the vendor answered with once pushed. */
+/** A twin's branch log as the world reads it: the twin's name, the state service it records under, its control root. */
+export declare class TwinLog {
+    readonly service: string;
+    readonly stateService: string;
+    readonly root: string;
+    constructor(service: string, stateService: string, root: string);
+    /** this branch's own entries, bookkeeping aside */
+    log(): TwinAction[];
+    /** entries the parent does not hold */
+    unpushed(opts?: {
+        pushable?: boolean;
+    }): TwinAction[];
+    /** the tree: this twin's resources as a read sees them */
+    state(): TwinResource[];
+    /** one write through the kernel's write path (the head performs it when this twin's root says so) */
+    change(write: Parameters<typeof applyTwinWrite>[1]): ReturnType<typeof applyTwinWrite>;
+}
+export type LogEntry = TwinAction & {
+    receipt?: ApplyReceipt;
+    changeset?: string; /** v2: the receipt on the landed copy — deployed, refused, failed, landed */
+    landed?: Receipt; /** the entry's POSITION in its twin's whole log (contract "Just like Neon", 2): the parent view then the branch, counted from one */
+    position?: number;
+};
+export type WorldStatus = {
+    world: string;
+    root: string;
+    branch: string;
+    branches: string[];
+    running: boolean;
+    /** the URL this world is served at, when a serve process is alive (contract "Just like Neon", 4) */
+    served: {
+        base: string;
+        pid: number;
+        startedAt: string;
+    } | null;
+    /** the origin this world clones from and pushes to, or null: the default data is its only origin */
+    origin: {
+        url: string;
+        namespace: string;
+        fetchedAt?: string;
+    } | null;
+    unpushed: number;
+    changesets: {
+        total: number;
+        pushed: number;
+    };
+    services: Record<string, {
+        url?: string;
+        running: boolean; /** the pack's protocol major and its standing (protocol 1 is deprecated: served under a warning, its vendor half throws) */
+        protocol?: {
+            major: number;
+            standing: string;
+        };
+    }>;
+    envFile?: string;
+};
+/** `https://host/org/world` → the remote's base URL and the namespace it addresses. */
+export declare function parseOriginUrl(url: string): {
+    url: string;
+    namespace: string;
+};
+export declare class World {
+    /** The branch this handle is on — the instance name in the kernel. */
+    readonly name: string;
+    /** The world root: the app repo. */
+    readonly root: string;
+    private constructor();
+    /** 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;
+    static open(ref?: WorldRef): World;
+    /** Whether `from` (default: the cwd) is inside a world. */
+    static find(from?: string): World | null;
+    /** `volter world init --bare <org>/<world> --twins a,b`: a world with no app — a package.json naming the
+     *  twins (installed with bun), then the world over them, served as `/<org>/<world>/`. */
+    static initBare(dir: string, served: string, twins: string[], opts?: {
+        install?: boolean;
+        force?: boolean;
+    }): {
+        world: World;
+        result: InitResult;
+    };
+    /** `volter world init`: detect the app's vendors and write `.volter/world.json` beside the code. */
+    static init(app?: string, opts?: Omit<InitOptions, 'root'> & {
+        name?: string;
+        root?: string;
+    }): {
+        world: World;
+        result: InitResult;
+    };
+    /**
+     * Start the twins on this branch. A branch that has run before comes back with its state (down
+     * 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`.
+     */
+    up(opts?: {
+        mode?: WorldMode;
+        seed?: boolean;
+        cwd?: string;
+    }): Promise<WorldInstance>;
+    /** Stop the twins; the branch's state stays (`up` resumes). `purge` forgets it. */
+    down(opts?: {
+        purge?: boolean;
+    }): ReturnType<typeof downWorld>;
+    /** 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>;
+    /** The shell script that activates the world in the current shell: `eval "$(volter world activate)"` — vendor CLIs and curl reach the twins. */
+    activateScript(): string;
+    /** A subshell with the world active; resolves to its exit code. */
+    shell(): Promise<number>;
+    /** The kernel's instance record, or null before the first `up`. */
+    instance(): (WorldInstance & {
+        running: boolean;
+        livePids: number[];
+    }) | null;
+    /** The world, the branch, the origin, what is unpushed, what is running. */
+    status(): WorldStatus;
+    /** One twin log per twin the world runs: its branch entries and what is unpushed. */
+    repos(): TwinLog[];
+    repo(service: string): TwinLog;
+    /** Every write the app made, across the twins, oldest first, with the receipt against each pushed one. */
+    log(): LogEntry[];
+    /** Changes not yet pushed (`log origin..HEAD`), across the twins. */
+    unpushed(): TwinAction[];
+    diff(base?: string): LedgerDelta;
+    /** Load the default data: the seed runs with every twin recording what it creates as data that was already there. */
+    seed(opts?: {
+        entry?: string;
+        cwd?: string;
+    }): ReturnType<typeof seedWorld>;
+    /** Back to the default data: forget this branch's state, boot, seed. */
+    reset(opts?: {
+        entry?: string;
+        cwd?: string;
+    }): ReturnType<typeof resetWorld>;
+    /**
+     * A new branch from here — its own log over this branch's mirrors — checked out. One branch runs
+     * at a time in a world (the app's env names one set of twins), so this branch stops as the new
+     * one starts; `checkout` brings it back with its state.
+     */
+    branch(name: string, opts?: {
+        at?: {
+            instant?: string;
+            positions?: Record<string, number>;
+            views?: Record<string, string>;
+        };
+    }): Promise<World>;
+    /** Switch to a branch: its twins come back with their state; this branch's stop. */
+    checkout(name: string): Promise<World>;
+    branches(): string[];
+    /** Is this the main branch? */
+    isMain(): boolean;
+    /** What this branch's changes are measured from, as `diff` says it: the branch point, origin, or the story. */
+    diffBase(): string;
+    /** The world's clock: the frozen instant every twin stamps from, or the wall clock when unset. */
+    clock(): {
+        at: string;
+        frozen: boolean;
+    };
+    /** Set the world's clock to an instant; every twin stamps from it until it moves. */
+    setClock(iso: string): string;
+    /** Move a set clock forward: `30d`, `12h`, `5m`, `90s`. */
+    advanceClock(by: string): string;
+    /** Rebase this branch onto its base's current position, every twin; conflicts named per subject and field. */
+    rebaseBranch(): Array<{
+        service: string;
+    } & ReturnType<typeof rebaseBranch>>;
+    /** Replay a changeset's changes into another branch's twins, in order, with the same ids. */
+    replay(name: string, into: string): ReturnType<typeof replayWorldChangeset>;
+    /** Serve this world on a port under `/<org>/<world>/`; returns when listening. */
+    serve(opts?: {
+        port?: number;
+        host?: string;
+        consolePort?: number;
+        announce?: (info: {
+            name: string;
+            base: string;
+            token: string;
+            readToken: string;
+            console: string | null;
+        }) => void;
+    }): Promise<ServedWorld>;
+    /** The remotes named in world.json (`volter remote add`), name → url or path. */
+    remotes(): Record<string, string>;
+    /** Name a remote; `origin` is the one fetch and push use by default. A token given is remembered for it. */
+    addRemote(name: string, target: string, opts?: {
+        token?: string;
+    }): void;
+    removeRemote(name: string): void;
+    /** The remote a verb uses: the named one, else origin from world.json, else the instance's recorded origin. */
+    remote(name?: string): {
+        url: string;
+        namespace: string;
+    } | null;
+    /** The origin this world clones from and pushes to, or null: the default data is its only origin. */
+    origin(): WorldInstance['origin'] | null;
+    /**
+     * Clone a remote's canonical history into this world: record the origin, remember the token,
+     * fetch everything. With the world's token (namespace or read), the history arrives through the
+     * mirror, from the beginning; with `adminToken` as well, the remote's whole tree is copied in one
+     * move, which is what an admin can do and a reader cannot. Either way one token is remembered:
+     * the world's, which is what `fetch` and `push` use afterwards.
+     */
+    clone(url: string, opts?: {
+        token?: string;
+        adminToken?: string;
+    }): Promise<ReturnType<typeof fetchFromOrigin>>;
+    /** Fetch, then move this branch onto what came in: git's pull. */
+    pull(opts?: {
+        token?: string;
+        services?: string[];
+    }): Promise<{
+        fetched: Awaited<ReturnType<typeof fetchFromOrigin>>;
+        rebased: ReturnType<World['rebaseBranch']>;
+    }>;
+    /** Fetch what the origin observed since the last fetch. */
+    fetch(opts?: {
+        token?: string;
+        services?: string[];
+    }): ReturnType<typeof fetchFromOrigin>;
+    /** Cut a changeset from the unpushed changes: the reviewable unit, with the author's message. */
+    changeset(opts?: {
+        name?: string;
+        message?: string;
+        base?: string;
+        verifiers?: Parameters<typeof createWorldChangeset>[2] extends infer O ? (O extends {
+            verifiers?: infer V;
+        } ? V : never) : never;
+        overwrite?: boolean;
+    }): Changeset;
+    changesets(): ChangesetLocation[];
+    /**
+     * Push to the origin, which deploys to the vendor with its own keys and answers with receipts:
+     * the named changeset, or every changeset not yet pushed, oldest first. A local world never
+     * holds a vendor credential.
+     */
+    push(opts?: {
+        name?: string;
+        token?: string;
+        force?: boolean;
+    }): Promise<Array<Awaited<ReturnType<typeof pushWorldChangeset>>>>;
+    mark(id?: string, now?: Date): WorldMarker;
+    marks(): WorldMarker[];
+    verify(name: string, opts?: {
+        into?: string;
+        ephemeral?: boolean;
+    }): ReturnType<typeof verifyWorldChangeset>;
+    approve(name: string, principal: string, note?: string): ReturnType<typeof approveWorldChangeset>;
+    readiness(name: string): ReturnType<typeof statusWorldChangeset>;
+    rebase(name: string): ReturnType<typeof rebaseWorldChangeset>;
+    /** The twin's root and credential, as `volter twin <vendor>` prints them. */
+    twin(vendor: string): {
+        vendor: string;
+        url?: string;
+        root: RootConfig | null;
+        credential: {
+            placedAt: string;
+            fingerprint: string;
+        } | null;
+    };
+    /** Set (or clear) the twin's root: the vendor's API and the deploy policy, in world.json. Takes effect at the next `up` or `serve`, or now when the world runs. */
+    setTwinRoot(vendor: string, root: RootConfig | null): void;
+    /** Seal the vendor's credential beside the world (a bare token, or a JSON payload). Never readable back. */
+    sealTwinCredential(vendor: string, input: string): Promise<{
+        placedAt: string;
+        fingerprint: string;
+    }>;
+    /** Refresh one twin from its root now. */
+    refreshTwin(vendor: string, opts?: {
+        force?: boolean;
+    }): Promise<{
+        refreshed: boolean;
+        reason?: string;
+        report?: {
+            observed: number;
+            appended: number;
+            unchanged: number;
+            removed: number;
+        };
+    }>;
+    private rootOf;
+    /** DEPLOY: perform landed entries against each root twin's vendor, by policy (runtime `deployWorld`). */
+    deploy(name?: string): Promise<DeployTwinOutcome[]>;
+}
+/** The world's name when none is given: the app directory's basename, made safe. */
+export declare function worldNameFor(app: string): string;
+export { rebaseChangeset, worldBootMarker };