@volter/world 2.0.0 → 2.0.2

package/skills/volter-world/AGENTS.md

@@ -0,0 +1,155 @@
+# volter-world — operating a World
+
+A World contains only the vendors deliberately selected for substitution in the current workflow.
+Review detected vendors before including them. The app uses its real SDKs unchanged;
+environment injection, a Node preload and a scoped HTTPS proxy route configured vendors to twins.
+
+The state model is **Neon for every SaaS**: a log, checkpoints and branches over a parent position.
+Git-inspired verbs describe operations; there is no staging or commit step. Push moves entries
+between Worlds. Deploy performs them against a vendor at a real-system root under its policy.
+The canonical [model](https://github.com/volter-ai/twin/blob/main/docs/concepts/the-model.md),
+[lifecycle](https://github.com/volter-ai/twin/blob/main/docs/concepts/worlds.md) and
+[CLI reference](https://github.com/volter-ai/twin/blob/main/docs/reference/cli.md) own the details.
+
+## Set up a World for an app
+
+In the app's folder (the [guide](https://github.com/volter-ai/twin/blob/main/docs/guides/use-with-a-coding-agent.md)):
+
+```bash
+npm install -g @volter/world     # once; `volter agents install` then adds this skill and the MCP server to your agents
+volter world init                # detects the vendors from the app's manifests and env names; writes .volter/world.json
+volter world up
+volter world run -- npm test     # the app's own test command
+volter world log                 # what the app did at each vendor
+```
+
+Show the person the vendors `init` detected, and why, before keeping them. Keys the app reads
+(named in `.env.example`) get throwaway values in the World's env; never put real credentials in
+a World to get a test past validation. `volter world view --no-open` runs the World with its
+dashboard and prints its link for the person; it keeps running, so start it in the background,
+and stop a World you started with `up` first (`down` keeps its state).
+
+## Share it on a platform
+
+A team shares Worlds on a Volter World platform (Volter's cloud, or one the team runs):
+
+```bash
+volter login <platform url>                     # prints a link and a code: the PERSON approves it in their browser
+volter remote add origin <org>/<world> --create  # links this World to that one, making it from world.json's vendors
+volter world changeset -m "<what and why>"       # the unpushed changes, as one reviewable changeset
+volter world push                                # sends it; the platform answers with receipts
+```
+
+You cannot approve a sign-in; hand the link and code to the person and wait. Ask the person for
+`<org>/<world>` rather than guessing it. Keys for apps and CI are made on the platform.
+
+## The MCP tools
+
+`volter mcp` serves the same verbs to an agent: `world_init`, `world_up`, `world_run`,
+`world_status`, `world_log`, `world_diff`, `world_view`, `world_branch`, `world_checkout`,
+`world_reset`, `world_down`, `platform_login`, `platform_whoami`, `remote_link`, `world_changeset` and
+`world_push`,
+each taking the app's folder as `dir`. They run the `volter` command itself, so their answers and
+refusals are the command's: act on a refusal's reason rather than working around it.
+
+## Run through the World
+
+Run apps and tests inside a World, never bare. For a repo with `.volter/world.json`:
+
+```bash
+volter world up
+volter world run -- npm test
+volter world down
+```
+
+`volter world up` resumes a stopped branch's state and seeds a fresh branch.
+`volter world run` runs a command inside that World; it does not own teardown.
+`reset` discards the current branch's state and reloads default data. `down` retains state;
+`down --purge` removes it after verified teardown, unless another local branch references it.
+Fresh boot, reset and prune also refuse to remove a referenced parent; stop compute with
+ordinary `down`, or remove dependent branches first.
+
+For existing operator configs, use the explicit name and root:
+
+```bash
+volter-world up <config> --root <twins-checkout> --env-file <live-env> --owner <task>
+# From the app repo so the seed's SDK dependencies resolve:
+volter-world attach <world> --root <twins-checkout> -- bun <seed-entry>
+volter-world attach <world> --root <twins-checkout> -- <command...>
+volter-world down <world> --root <twins-checkout>
+```
+
+The lower-level `volter-world up` starts a fresh instance: reseed after each successful boot.
+Do not confuse this with the resumable `volter world up` API. The env file passed to `up` is the
+live env; an init-generated preview is not. Use `url` and `app-url` to discover endpoints rather
+than parsing env files. Registered commands carry `VOLTER_WORLD`.
+
+For a task that owns the entire lifecycle, use:
+
+```bash
+volter-world run <config> --root <twins-checkout> --env-file <live-env> --owner <task> -- <command...>
+```
+
+This operator command owns boot, its command and teardown. `--keep` makes it persistent.
+Its cleanup process handles caller loss if it survives; uncertain teardown retains diagnostics
+and lifecycle evidence. Stop registered consumers before explicitly bringing their World down.
+
+## State and behavior
+
+Create stored data through the vendor's own API using the real SDK pointed at the twin.
+Identity comes from credentials in the vendor's manner; inspect `GET /twin` for the twin's
+identity and time rules. Use `clock set` and `clock advance` for backdated history. Without a
+frozen World clock, the runtime uses wall time.
+
+Author judgment, stateless lookups and faults in `handlers/<vendor>.json` in the World config
+directory (typically `.volter/handlers/`). These are ordered, first-match scenario rules.
+Edit the file and restart to load changes; a handler must never fake success for a stored
+mutation. `GET /twin/scenario` shows handler matches and misses; `tail` records misses to author.
+Model twins serve deterministic scripts or labeled stubs, so verify calls and state changes,
+not the quality of prose from an unconfigured model.
+
+Local default data is synthetic. A World cloned or refreshed from a real root may contain real
+records; treat its files accordingly. Fake opaque keys are intentional. If an SDK parses a key
+locally, use `fake-env` to produce a structurally valid throwaway credential; never substitute
+real credentials to get a local test past validation.
+
+## Capacity and ownership
+
+Use `resources` to inspect actual filesystem capacity and registered lifecycle owners/consumers.
+Runtime v3 does not reserve speculative per-World memory or storage. Configure supported limits
+in the execution backend; deprecated `resources` declarations are not enforced limits.
+On a storage failure, inspect the actual destination and backend error. Preview `prune` for
+eligible stopped instance files; it never stops a running World. Inspect ownership before apply.
+Unknown use remains unknown; age never proves safety. Preserve cleanup evidence and parent
+history. Never delete another actor's World, worktree, package cache or rate-budget ledger.
+Migrate an old installation only after verified teardown with its pinned runtime, then pin all
+entrypoints to the new version and resume retained state. Never run two runtime versions over
+one instance or erase legacy ownership records to make startup pass.
+
+Worlds own their declared infrastructure. Start, inspect and stop it through World commands;
+never operate its underlying process, container or database separately. Install locked repository
+dependencies from the normal registry/cache; use a registry twin only when registry behavior
+needs substitution. Build workspace packages when needed. Do not delete `node_modules` as a World repair.
+
+When booting an app, register its URL as the last step with `app-url --set <url>` (or `--detect`).
+An app declared as a World service supplies its own endpoint record. Consumers read `app-url`.
+An app that answers as its own production hostnames (`app.example.com`) records them with
+`app-url --host <name>`: inside the World they reach the app with their Host, `x-forwarded-host` and
+`x-forwarded-proto` (https when the caller used TLS).
+
+## Diagnose before changing the app
+
+1. Check whether the failing vendor belongs in this World before seeding or repairing its twin.
+   For app/test execution, check `VOLTER_WORLD` and the intended World environment.
+2. Run `doctor`, then `tail --no-follow`, and inspect the twin's `GET /twin` manifest.
+3. Run `covers <world> --repo <app>` for missing vendor coverage.
+4. Determine whether the failure belongs to the app, twin fidelity, scenario, routing or runtime.
+
+Sandbox mode refuses untwinned destinations in cooperating clients, including Node sockets a
+client opens around the injector. It does not constrain binaries or non-Node processes that
+ignore the injector/proxy; network isolation needs an enforced boundary.
+Do not disable routing to hide a coverage gap.
+
+Current packages are `@volter/world`, `@volter/world-core`, `@volter/world-runtime`,
+`@volter/world-access`, `@volter/world-attach` and `@volter/twin-<vendor>`. Use the CLI reference for commands instead of
+retired `volter-twin`, `plan` or `review` examples.

package/skills/volter-world/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: volter-world
+description: Set up, run and diagnose an app inside a Volter World (twins of Stripe, Slack, GitHub, OpenAI and the other SaaS APIs it calls), share it on a Volter World platform, with explicit ownership and cleanup. Use when asked to set up Volter World, run an app or its tests against twins, look at what an app did at a vendor, branch or reset that state, or link a World to a team's platform.
+---
+
+# Operating a World
+
+Read [AGENTS.md](./AGENTS.md) before setting up, running or changing a World. It is the single
+operator instruction source shipped with this skill: setting a World up for an app, linking it
+to a platform, the `volter mcp` tools, and the lifecycle distinction between the product command
+`volter world` and the explicit operator command `volter-world`.
+
+The [documentation map](https://github.com/volter-ai/twin/blob/main/docs/README.md) links the
+canonical model, task guides and command reference. Do not maintain a second copy here.

package/src/agent-prompt.ts

@@ -0,0 +1,35 @@
+// The prompt a person hands their coding agent to set Volter World up for their app (docs/contributing/architecture.md,
+// "The way in is the app's folder"): one text for every place it is offered (the landing page, the platform's Get
+// started, the dashboard's Connect, `volter mcp`'s get-started prompt). Pure, with no imports: browser bundles use it.
+
+export type AgentPromptOptions = {
+  /** A platform to share the World on: its address. */
+  platform?: string;
+  /** The World on that platform, `<org>/<world>`; without it, the agent asks. */
+  world?: string;
+  /** Phrase the steps for an agent that has `volter mcp`'s tools rather than a shell. */
+  tools?: boolean;
+};
+
+/** The prompt, as plain text a person copies. */
+export function agentPrompt(o: AgentPromptOptions = {}): string {
+  const cmd = (shell: string, tool: string): string => (o.tools ? `${tool} (\`${shell}\`)` : `\`${shell}\``);
+  const steps = [
+    'Set up Volter World for this app, so its calls to Stripe, Slack, GitHub, OpenAI and the other services it uses go to local twins instead of the real APIs. The app keeps its real SDKs and code.',
+    '',
+    o.tools
+      ? '1. You have the Volter World tools (volter mcp). If the `volter` command is missing, install it: `npm install -g @volter/world`.'
+      : '1. Install the command and your agent tooling: `npm install -g @volter/world`, then `volter agents install --yes`.',
+    `2. In the app's folder, ${cmd('volter world init --install', 'world_init')}: it detects the vendors the app calls and installs their twins. Show me the vendors it detected and why, before keeping them.`,
+    `3. ${o.tools ? 'Start it with world_up' : 'Start it: `volter world up`'}, then run the tests inside it: ${cmd('volter world run -- <the test command>', 'world_run')}. Fix anything that fails because a call went to the real service.`,
+    `4. Tell me what the app did at each vendor (${cmd('volter world log', 'world_log')}), and give me the dashboard link (${o.tools ? 'world_view' : '`volter world view --no-open`, started in the background: it keeps running'}).`,
+  ];
+  if (o.platform) {
+    const target = o.world ?? '<org>/<world>';
+    steps.push(
+      `5. Share it with my team on ${o.platform}: ${cmd(`volter login ${o.platform}`, 'platform_login')} gives a link and a code for me to approve in my browser. Once I have, link it with ${cmd(`volter remote add origin ${target} --create`, 'remote_link with create: true')}${o.world ? '' : ' (ask me for <org>/<world>)'}, then send what the app did: ${cmd('volter world changeset -m "<what and why>"', 'world_changeset')} and ${cmd('volter world push', 'world_push')}.`,
+    );
+  }
+  steps.push('', 'The guide: https://github.com/volter-ai/twin/blob/main/docs/guides/use-with-a-coding-agent.md');
+  return steps.join('\n');
+}

package/src/agents.ts

@@ -0,0 +1,166 @@
+// `volter agents install` (docs/contributing/architecture.md, "The way in is the app's folder"): the skill
+// (skills/volter-world) and the MCP server (`volter mcp`) put into the coding agents on this machine. Each change is
+// idempotent and said; an entry another tool wrote is never touched: only our own `volter` entry and our own skill
+// folder or marked block are written.
+import { spawnSync } from 'node:child_process';
+import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export type Agent = 'claude' | 'cursor' | 'vscode' | 'codex';
+export const AGENTS: readonly Agent[] = ['claude', 'cursor', 'vscode', 'codex'];
+const NAMES: Record<Agent, string> = { claude: 'Claude Code', cursor: 'Cursor', vscode: 'VS Code', codex: 'Codex' };
+
+/** A command on PATH (with Windows' extensions), or null. */
+function which(cmd: string): string | null {
+  const exts = process.platform === 'win32' ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT').split(';').map((e) => e.toLowerCase()) : [''];
+  for (const dir of (process.env.PATH ?? '').split(delimiter)) {
+    if (!dir) continue;
+    for (const ext of ['', ...exts]) { const p = join(dir, `${cmd}${ext}`); if (existsSync(p)) return p; }
+  }
+  return null;
+}
+
+/** The skill's folder: the one shipped in the package (skills/, copied in at pack time), else this checkout's. */
+export function skillSource(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  for (const candidate of [resolve(here, '..', 'skills', 'volter-world'), resolve(here, '..', '..', 'skills', 'volter-world'), resolve(here, '..', '..', '..', 'skills', 'volter-world'), resolve(here, '..', '..', '..', '..', 'skills', 'volter-world')]) {
+    if (existsSync(join(candidate, 'SKILL.md'))) return candidate;
+  }
+  throw new Error('the volter-world skill is not in this installation (skills/volter-world)');
+}
+
+/** How an agent starts the server: `volter mcp` when the command is on PATH, else this installation by its path. */
+export function mcpCommand(): { command: string; args: string[] } {
+  if (which('volter')) return { command: 'volter', args: ['mcp'] };
+  const cli = fileURLToPath(new URL(`./cli${import.meta.url.endsWith('.ts') ? '.ts' : '.js'}`, import.meta.url));
+  return { command: process.execPath, args: [cli, 'mcp'] };
+}
+
+/** The agents this machine (and this project) shows signs of. */
+export function detectAgents(project: string): Agent[] {
+  const home = homedir();
+  const found: Agent[] = [];
+  if (existsSync(join(home, '.claude')) || which('claude')) found.push('claude');
+  if (existsSync(join(home, '.cursor')) || which('cursor')) found.push('cursor');
+  if (existsSync(join(project, '.vscode')) || which('code')) found.push('vscode');
+  if (existsSync(join(home, '.codex')) || which('codex')) found.push('codex');
+  return found;
+}
+
+/** A path as a person reads it: inside the project relative to it, inside the home folder from ~, with forward slashes. */
+function shown(path: string): string {
+  const within = (base: string): string | null => { const r = relative(base, path); return r && !r.startsWith('..') && !isAbsolute(r) ? r.replace(/\\/g, '/') : null; };
+  const inProject = within(process.cwd()); if (inProject) return inProject;
+  const inHome = within(homedir()); if (inHome) return `~/${inHome}`;
+  return path;
+}
+
+const readJson = (path: string): Record<string, unknown> => {
+  if (!existsSync(path)) return {};
+  const raw = readFileSync(path, 'utf8').trim();
+  if (!raw) return {};
+  try { const v = JSON.parse(raw) as unknown; return v && typeof v === 'object' && !Array.isArray(v) ? v as Record<string, unknown> : {}; } catch { throw new Error(`${path} is not JSON; not changing it (add the volter server by hand)`); }
+};
+/** A config file replaced whole in one step (written beside it, then renamed over it): a reader never sees half of it. */
+const writeAtomic = (path: string, text: string): void => { mkdirSync(dirname(path), { recursive: true }); const tmp = `${path}.volter-${process.pid}.tmp`; writeFileSync(tmp, text); renameSync(tmp, path); };
+const writeJson = (path: string, value: unknown): void => writeAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
+/** A command run as itself; on Windows, where `claude` is a .cmd that runs only in cmd, one line to cmd with each argument
+ *  quoted (a path with a space stays one argument), as cross-spawn does. */
+const runTool = (bin: string, args: string[]): ReturnType<typeof spawnSync> => process.platform === 'win32'
+  ? spawnSync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', `"${[bin, ...args].map((a) => `"${a.replace(/"/g, '""')}"`).join(' ')}"`], { windowsHide: true, encoding: 'utf8', windowsVerbatimArguments: true })
+  : spawnSync(bin, args, { windowsHide: true, encoding: 'utf8' });
+const same = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b);
+
+/** Our entry under `key` in a JSON config's server map: added, or already there; someone else's `volter` is left alone. */
+function mergeServer(path: string, key: 'mcpServers' | 'servers', entry: Record<string, unknown>): string {
+  const doc = readJson(path);
+  const servers = (doc[key] && typeof doc[key] === 'object' ? doc[key] : {}) as Record<string, unknown>;
+  const mine = servers.volter as Record<string, unknown> | undefined;
+  if (mine && same(mine, entry)) return `${shown(path)}: the volter server is already there`;
+  if (mine && !(typeof mine.command === 'string' && /volter|cli\.[tj]s/.test(`${mine.command} ${JSON.stringify(mine.args ?? [])}`))) return `${shown(path)}: a "volter" server someone else configured is there; left alone`;
+  doc[key] = { ...servers, volter: entry };
+  writeJson(path, doc);
+  return `${shown(path)}: ${mine ? 'updated' : 'added'} the volter server`;
+}
+
+/** The skill copied into an agent's skills folder: our own folder, replaced whole. */
+function copySkill(target: string): string {
+  const dest = join(target, 'volter-world');
+  rmSync(dest, { recursive: true, force: true });
+  mkdirSync(target, { recursive: true });
+  cpSync(skillSource(), dest, { recursive: true });
+  return `${shown(dest)}: the volter-world skill`;
+}
+
+const BEGIN = '<!-- volter-world:begin -->';
+const END = '<!-- volter-world:end -->';
+/** The skill's instructions as a marked block in a Markdown instructions file; the rest of the file untouched. */
+function markedBlock(path: string): string {
+  const body = readFileSync(join(skillSource(), 'AGENTS.md'), 'utf8').trimEnd();
+  const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  const start = existing.indexOf(BEGIN); const end = existing.indexOf(END);
+  const outside = start >= 0 && end > start ? `${existing.slice(0, start)}${existing.slice(end + END.length)}`.replace(/\n{3,}$/, '\n\n') : existing;
+  const next = `${outside.trimEnd()}${outside.trim() ? '\n\n' : ''}${BEGIN}\n${body}\n${END}\n`;
+  if (next === existing) return `${shown(path)}: the volter-world instructions are already there`;
+  writeAtomic(path, next);
+  return `${shown(path)}: ${start >= 0 ? 'updated' : 'added'} the volter-world instructions`;
+}
+
+/** Codex's config.toml: a [mcp_servers.volter] table appended when there is none; an existing one is left alone. */
+function codexServer(path: string, entry: { command: string; args: string[] }): string {
+  const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  if (/^\s*\[mcp_servers\.(?:volter|"volter"|'volter')\]\s*$/m.test(existing)) return `${shown(path)}: a [mcp_servers.volter] table is already there; left alone`;
+  const q = (s: string): string => JSON.stringify(s);
+  const table = `[mcp_servers.volter]\ncommand = ${q(entry.command)}\nargs = [${entry.args.map(q).join(', ')}]\n`;
+  mkdirSync(dirname(path), { recursive: true });
+  writeAtomic(path, `${existing.trimEnd()}${existing.trim() ? '\n\n' : ''}${table}`);
+  return `${shown(path)}: added the volter server`;
+}
+
+/** Claude Code: `claude mcp add` at user scope when the command is here (it owns its config file), else ~/.claude.json. */
+function claudeServer(entry: { command: string; args: string[] }): string {
+  const claude = which('claude');
+  if (claude) {
+    const has = runTool(claude, ['mcp', 'get', 'volter']);
+    if (has.status === 0) return 'Claude Code: the volter server is already registered (claude mcp get volter)';
+    const add = runTool(claude, ['mcp', 'add', '--scope', 'user', 'volter', '--', entry.command, ...entry.args]);
+    if (add.status === 0) return 'Claude Code: registered the volter server (claude mcp add --scope user volter)';
+  }
+  return mergeServer(join(homedir(), '.claude.json'), 'mcpServers', { type: 'stdio', command: entry.command, args: entry.args });
+}
+
+/** Install into each agent: what changed, one line each. */
+export function installAgents(agents: Agent[], project: string): string[] {
+  const entry = mcpCommand(); const home = homedir(); const lines: string[] = [];
+  for (const a of agents) {
+    try {
+      if (a === 'claude') { lines.push(copySkill(join(home, '.claude', 'skills'))); lines.push(claudeServer(entry)); }
+      if (a === 'cursor') lines.push(mergeServer(join(home, '.cursor', 'mcp.json'), 'mcpServers', { command: entry.command, args: entry.args }));
+      if (a === 'vscode') lines.push(mergeServer(join(project, '.vscode', 'mcp.json'), 'servers', { type: 'stdio', command: entry.command, args: entry.args }));
+      if (a === 'codex') { lines.push(markedBlock(join(home, '.codex', 'AGENTS.md'))); lines.push(codexServer(join(home, '.codex', 'config.toml'), entry)); }
+    } catch (e) { lines.push(`${NAMES[a]}: not changed: ${e instanceof Error ? e.message : String(e)}`); }
+  }
+  return lines;
+}
+
+/** `volter agents install [--claude] [--cursor] [--vscode] [--codex] [--yes]`. */
+export async function agentsCommand(verb: string | undefined, args: string[], out: (s: string) => void): Promise<void> {
+  if (verb !== 'install') throw new Error('volter agents install [--claude] [--cursor] [--vscode] [--codex] [--yes]');
+  const project = process.cwd();
+  const named = AGENTS.filter((a) => args.includes(`--${a}`));
+  const agents = named.length ? named : detectAgents(project);
+  if (agents.length === 0) { out('no coding agent found here (Claude Code, Cursor, VS Code, Codex); name one: volter agents install --claude'); process.exitCode = 1; return; }
+  const entry = mcpCommand();
+  out(`for      ${agents.map((a) => NAMES[a]).join(', ')}\nskill    volter-world\nserver   ${[entry.command, ...entry.args].join(' ')}`);
+  if (!args.includes('--yes')) {
+    if (!process.stdin.isTTY) { out('\nnothing changed: run again with --yes to install'); return; }
+    process.stdout.write('\nInstall? [y/N] ');
+    const answer = await new Promise<string>((done) => { process.stdin.once('data', (d) => done(String(d).trim().toLowerCase())); });
+    process.stdin.pause();
+    if (answer !== 'y' && answer !== 'yes') { out('nothing changed'); return; }
+  }
+  for (const line of installAgents(agents, project)) out(`  ${line}`);
+  out('\nRestart the agent, then ask it to "set up Volter World for this app".');
+}