virtualmatter 0.1.0 → 0.3.0

package/README.md

@@ -1,8 +1,9 @@
 # virtualmatter
 
 The command line for building with Virtual Matter - and the MCP server that
-gives coding agents direct hands on a live session: montage files, Lua
-execution, engine errors, and screenshots.
+gives coding agents direct hands on your worlds: listing and creating them,
+their live Montage files, Lua execution, engine errors, screenshots, and the
+native desktop client.
 
 No install needed:
 
@@ -16,76 +17,143 @@ Requires Node 20 or newer. No native modules.
 
 ## Quickstart
 
-```bash
-# 1. Sign in (device code - approve it in your browser)
-npx virtualmatter login
+One command. It signs you in on first use (device code, approved in your
+browser), creates the world, and mirrors its files into `./my-world`:
 
-# 2. Pull a world you can edit. Paste the /edit link from your browser.
-npx virtualmatter pull https://make.virtualmatter.ai/edit/<framing-id> my-world
+```bash
+npx virtualmatter create "My world"
 cd my-world
-
-# 3. Start the hot loop: local edits push instantly, remote edits pull back.
 npx virtualmatter sync
 ```
 
+Already have a world? Paste any link to it - `/edit`, `/play`, `/g`, `/p`,
+`/projects`, with or without the readable name in the URL:
+
+```bash
+npx virtualmatter list
+npx virtualmatter pull https://make.virtualmatter.ai/edit/my-world-<framing-id>
+```
+
 While `sync` runs, saving a Lua script in your editor deploys it - scripts
 hot-reload in the engine. If someone edits the same file in the live session,
 your copy stays put and the remote version lands next to it as
 `<name>.remote-conflict` for you to merge.
 
+Want the native client instead of the browser? This downloads it on first
+use, signs it in with your account, and opens the world:
+
+```bash
+npx virtualmatter open
+```
+
 Poke at the running engine from another terminal:
 
 ```bash
 npx virtualmatter run-lua --code "return Server.GetInfo()"
 npx virtualmatter errors
-npx virtualmatter screenshot -o shot.png
+npx virtualmatter screenshot -o shot.png                  # default overview
+npx virtualmatter screenshot --target "Player" -o p.png   # frame one object
+npx virtualmatter screenshot --at 0,30,40 --rot 0,-35,0    # exact camera
+                                          # --rot is yaw,pitch,roll
 ```
 
-## Hook up a coding agent (MCP)
+Work through these commands rather than driving make.virtualmatter.ai in a
+browser. The built-in agent on that site runs on Virtual Matter's platform
+credits instead of your own subscription, and an anonymous browser session
+cannot be steered after its first turn.
 
-Register the MCP server with Claude Code in one line, from a pulled folder:
+## Hook up a coding agent (MCP)
 
-```bash
-claude mcp add virtualmatter -- npx -y virtualmatter mcp
-```
+A folder created by `create` or `pull` already carries `.mcp.json` (Claude
+Code), `.cursor/mcp.json` (Cursor), `AGENTS.md` (Codex, Cursor, and most
+agents), and a `CLAUDE.md` that imports it - open the folder in your agent
+and it finds the MCP server and the project briefing on its own.
 
-Or point it at a framing directly, no pulled folder needed:
+To register the server by hand, from anywhere:
 
 ```bash
-claude mcp add virtualmatter -- npx -y virtualmatter mcp --framing <framing-id>
+claude mcp add virtualmatter -- npx -y virtualmatter mcp
 ```
 
-The server exposes `list_files`, `read_file`, `write_file`, `run_lua`,
-`get_engine_errors`, `capture_screenshot`, and `world_info`. Writes handle
-etag concurrency internally, and written Lua hot-reloads in the engine - so
-for an agent, writing a script is deploying it.
+It works before a world is selected: `list_projects`, `create_project`, and
+`select_project` (any link or id, optionally mirroring into a folder) pick
+one, then `list_files`, `read_file`, `write_file`, `run_lua`,
+`get_engine_errors`, `capture_screenshot`, `open_native_client`, and
+`world_info` act on it. Writes handle etag concurrency internally, and
+written Lua hot-reloads in the engine - so for an agent, writing a script is
+deploying it.
 
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `login` / `logout` / `whoami` | Device-code sign-in against the Virtual Matter identity server; tokens live in `~/.config/virtualmatter/credentials.json` (mode 0600) and refresh automatically. |
-| `pull <url-or-framing-id> [dir]` | Resolve (cold-starting if needed) the framing's session and download its file tree, plus an `AGENTS.md` briefing for agents. |
+| `create <name> [dir]` | Create a world (region defaults to the nearest; `--region`, `--track`, `--description`, `--no-pull`, `--open`, `--json`) and mirror it into `./<slug>`. |
+| `list` (`ls`, `projects`) | Your worlds with framing ids and edit/play URLs (`--json`). |
+| `pull [target] [dir]` | Mirror a world's file tree. `target` is any Virtual Matter link or a framing id; omitted, it uses this folder's world or your only one. |
 | `sync [dir]` | Watch + two-way sync with the live session. Ctrl-C to stop. |
+| `open [target]` (`client`) | Open a world in the native desktop client, downloading and signing it in on first use. `--install-only`, `--print` (just the download URL), `--force`. |
 | `run-lua [dir] --code "<lua>" [--target server\|client]` | Execute Lua in the running engine. |
 | `errors [dir]` | Recent engine errors. |
 | `screenshot [dir] [-o out.png]` | Capture the engine's current view. |
-| `client` | Print the native client download link for your OS. |
 | `mcp [dir] [--framing <id>]` | Run the stdio MCP server. |
-
-`pull` understands `/edit/<id>`, `/play/<id>`, and `/m/<id>` links from any
-Virtual Matter host, or a bare framing id. Project-level links (`/g/...`,
-`/play/p/...`) point at a whole project - open the project and copy the
-`/edit` link for the framing you want.
+| `login` / `logout` / `whoami` | Device-code sign-in; every other command signs you in automatically when needed. Tokens live in `~/.config/virtualmatter/credentials.json` (mode 0600) and refresh automatically. |
 
 ## Good to know
 
-- **Device sign-in is rolling out.** If `login` reports that device sign-in
-  is not enabled yet for this environment, the server-side toggle has not
-  reached your environment - it is coming.
 - `VIRTUALMATTER_API_BASE` overrides the platform API base (default
   `https://make.virtualmatter.ai`) for dev/staging environments.
-- Sync skips `Uploads/`, `Screenshots/`, `Agent Logs/`, dotfiles, and its own
-  bookkeeping (`.virtualmatter.json`).
+- `VIRTUALMATTER_NO_AUTO_LOGIN=1` turns the automatic first-use sign-in into
+  an error, for scripts that must never block on a browser.
+- The native client is unpacked under `~/.config/virtualmatter/client/<build>`
+  (override with `VIRTUALMATTER_CLIENT_DIR`); each engine build gets its own
+  folder, so a newer build never overwrites the one you are running.
+- Sync skips `Uploads/`, `Screenshots/`, `Agent Logs/`, dotfiles, the
+  harness files the CLI writes (`AGENTS.md`, `CLAUDE.md`, `.mcp.json`,
+  `.cursor/`, `.virtualmatter.json`), and the SDK's in-session tooling at the
+  Montage root (`atomo`, `vm_auth.py`, the agent-log hooks) - those only work
+  inside a running session.
+- The pulled `AGENTS.md` is the platform guide followed by the world's own
+  engine SDK guide (its Skills/ table and engine rules), with a header that
+  maps every `atomo` command the engine guide mentions to the CLI or MCP
+  equivalent.
+- Linux: the client is a tarball started through `run.sh`; `open` does that
+  for you. If no window appears, the newest log under
+  `~/.local/share/Atomontage/Atomontage Studio/UserData/Logs/` says why, and
+  the world keeps working in the browser and through every CLI command.
+- Sandboxed agents (Codex, restricted Claude Code) need network access for
+  every command: the platform, the identity server, and the world's host.
 - `pull` may cold-start a session for the framing; the first one can take a
   minute.
+
+## Websites and Lovable
+
+For a shared world, no account or local engine is needed:
+
+```bash
+npx virtualmatter embed 'https://play.virtualmatter.ai/p/world-a1b2c3d4'
+```
+
+The response contains canonical iframe markup, required **host response
+headers**, and verification instructions. Installing this CLI alone cannot
+configure the website's HTTP headers. Read `/embed-guide.md` on the platform.
+
+To ask VM's own agent to build a new world (using your VM credits):
+
+```bash
+npx virtualmatter build 'Lava Arena' --prompt 'Build a multiplayer lava survival arena' --request-id lava-arena-001
+npx virtualmatter build-status <build-id>
+```
+
+Reuse the same request id if the network drops; changing it requests another
+world. Review the world and enable **Share with friends** before embedding.
+An uncertain delivery is never automatically resubmitted.
+
+The local MCP `create_project` also accepts `prompt` plus `request_id`, and
+exposes `get_embed` and `get_build_status`. Without a prompt it retains the
+existing empty-world creation behavior.
+
+In Lovable, add `https://make.virtualmatter.ai/api/v1/mcp` as a custom MCP
+server with OAuth. Sign in or create a VM account, approve the connection,
+and return to Lovable. Then ask “Embed my Lava Arena world” or “Create a
+Virtual Matter lava survival arena and embed it here.” This remote endpoint
+runs on the platform; users do not install or run this CLI for that flow.

package/dist/agentfiles.js

@@ -0,0 +1,114 @@
+/**
+ * The files that make a pulled folder self-describing to whichever harness
+ * opens it: AGENTS.md (Codex, Cursor, and most others read it), CLAUDE.md
+ * (Claude Code reads this one and imports AGENTS.md through it), and the
+ * MCP registrations Claude Code (`.mcp.json`) and Cursor (`.cursor/mcp.json`)
+ * discover on their own. Existing files are never overwritten - a maker's
+ * own notes win - except AGENTS.md, which the CLI owns.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { apiBase } from "./config.js";
+export const AGENTS_MD_STUB = `# Working with Virtual Matter
+
+This folder is a live mirror of a Virtual Matter world's Montage files.
+
+- \`npx virtualmatter sync\` keeps it in sync with the running session.
+- \`npx virtualmatter run-lua --code "..."\` executes Lua in the engine.
+- \`npx virtualmatter errors\` shows recent engine errors.
+- \`npx virtualmatter screenshot -o shot.png\` captures the current view.
+- \`npx virtualmatter open\` opens this world in the native desktop client.
+- Lua scripts under this tree hot-reload in the engine when saved.
+
+Do not edit \`.virtualmatter.json\` - it is sync bookkeeping.
+`;
+export async function fetchAgentsMd(fetchFn = fetch) {
+    try {
+        const res = await fetchFn(`${apiBase()}/AGENTS.md`);
+        if (res.ok) {
+            const text = await res.text();
+            if (text.trim().length > 0 && !text.trimStart().startsWith("<"))
+                return text;
+        }
+    }
+    catch {
+        /* fall through to the stub */
+    }
+    return AGENTS_MD_STUB;
+}
+const CLAUDE_MD = `@AGENTS.md
+
+This folder mirrors a live Virtual Matter world. Keep \`npx virtualmatter sync\`
+running while you edit so saves hot-reload in the running world, or use the
+\`virtualmatter\` MCP server registered in \`.mcp.json\` to read, write, run Lua,
+check engine errors, and take screenshots directly.
+`;
+function mcpServerConfig() {
+    return {
+        command: "npx",
+        args: ["-y", "virtualmatter", "mcp"],
+    };
+}
+/**
+ * The SDK's own AGENTS.md ships inside every Montage tree. It is written for
+ * the in-session agent that drives the engine through `atomo`, which only
+ * works against a running engine bridge - so a local harness must not follow
+ * it literally. Its Skills/ table and engine rules are still the best
+ * reference there is, so the pulled AGENTS.md carries BOTH: the platform
+ * guide first, then the engine doc under a header that translates every
+ * `atomo` step into its CLI equivalent.
+ */
+export function composeAgentsMd(platformDoc, engineDoc) {
+    if (!engineDoc || engineDoc.trim().length === 0)
+        return platformDoc;
+    const bridge = `
+
+---
+
+# Engine reference (the world's SDK AGENTS.md)
+
+The section below is the engine SDK's own agent guide, mirrored from this
+world's Montage tree. It assumes an agent running INSIDE a Virtual Matter
+session, where an \`atomo\` command talks to the live engine. Here, on your own
+machine, there is no engine bridge - use the \`virtualmatter\` CLI (or its MCP
+tools) wherever the text says \`atomo\`:
+
+| Engine doc says | Do this instead |
+| --- | --- |
+| \`atomo run-lua '<code>'\` | \`npx virtualmatter run-lua --code '<code>'\` (MCP: \`run_lua\`) |
+| \`atomo run-lua-client ...\` | \`npx virtualmatter run-lua --target client --code '<code>'\` |
+| \`atomo errors\` | \`npx virtualmatter errors\` (MCP: \`get_engine_errors\`) |
+| \`atomo screenshot\` / \`screenshot-at\` / \`screenshot-obj\` | \`npx virtualmatter screenshot -o shot.png\` (MCP: \`capture_screenshot\`); aim the camera with run-lua first if needed |
+| \`atomo prints\` / \`atomo status\` | not available locally; use \`return\` values from run-lua |
+| edit a .lua file, then check \`atomo errors\` | save the file with \`npx virtualmatter sync\` running (or MCP \`write_file\`), then check errors the same way |
+| \`Skills/git-commit.md\` (git add/commit) | skip it - there is no git here; sync IS the persistence |
+| paths under \`/data/persist/Montage/\` | this folder |
+
+Everything else in it - the Skills/ table, the server/client rules, the Lua
+API rules, the mandatory error check after every change - applies as written.
+The \`Skills/\` files it references are in this folder.
+
+`;
+    return platformDoc.trimEnd() + "\n" + bridge + engineDoc.trimStart();
+}
+/** Write the harness files into a pulled folder. */
+export function writeAgentFiles(dir, agentsMd) {
+    const written = [];
+    const kept = [];
+    const put = (rel, content, overwrite) => {
+        const abs = path.join(dir, rel);
+        if (!overwrite && fs.existsSync(abs)) {
+            kept.push(rel);
+            return;
+        }
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, content);
+        written.push(rel);
+    };
+    put("AGENTS.md", agentsMd, true);
+    put("CLAUDE.md", CLAUDE_MD, false);
+    const mcp = JSON.stringify({ mcpServers: { virtualmatter: mcpServerConfig() } }, null, 2) + "\n";
+    put(".mcp.json", mcp, false);
+    put(path.join(".cursor", "mcp.json"), mcp, false);
+    return { written, kept };
+}

package/dist/api.js

@@ -58,3 +58,117 @@ export async function fetchNativeClients(fetchFn = fetch) {
     const body = (await res.json());
     return body.clients ?? [];
 }
+async function readError(res, what) {
+    let detail = "";
+    try {
+        const body = (await res.json());
+        if (typeof body.detail === "string")
+            detail = body.detail;
+        else if (body.detail)
+            detail = JSON.stringify(body.detail);
+    }
+    catch {
+        /* non-JSON */
+    }
+    return new Error(`${what} failed: HTTP ${res.status}${detail ? ` - ${detail}` : ""}`);
+}
+export async function listProjects(fetchFn = fetch) {
+    const res = await authorizedFetch(`${apiBase()}/api/v1/montages`, {}, fetchFn);
+    if (!res.ok)
+        throw await readError(res, "Listing projects");
+    return (await res.json());
+}
+export async function getProject(montageId, fetchFn = fetch) {
+    const res = await authorizedFetch(`${apiBase()}/api/v1/montages/${encodeURIComponent(montageId)}`, {}, fetchFn);
+    if (res.status === 404)
+        throw new Error(`Project ${montageId} was not found (or is not yours).`);
+    if (!res.ok)
+        throw await readError(res, "Loading the project");
+    return (await res.json());
+}
+export async function getProjectByPublicId(publicId, fetchFn = fetch) {
+    const res = await authorizedFetch(`${apiBase()}/api/v1/montages/by-public-id/${encodeURIComponent(publicId)}`, {}, fetchFn);
+    if (res.status === 404)
+        throw new Error(`Project ${publicId} was not found (or is not yours).`);
+    if (!res.ok)
+        throw await readError(res, "Resolving the project link");
+    const identity = (await res.json());
+    return getProject(identity.id, fetchFn);
+}
+export async function createProject(input, fetchFn = fetch) {
+    const res = await authorizedFetch(`${apiBase()}/api/v1/montages`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            name: input.name,
+            description: input.description ?? null,
+            region: input.region,
+            engine_track: input.engine_track ?? "stable",
+        }),
+    }, fetchFn);
+    if (res.status === 409) {
+        throw new Error(`You already have a project named "${input.name}". Pick another name.`);
+    }
+    if (!res.ok)
+        throw await readError(res, "Creating the project");
+    return (await res.json());
+}
+/**
+ * The region a new project should live in when the caller did not say:
+ * the one closest to the machine's clock. Coarse on purpose - a wrong
+ * guess costs some latency, a prompt costs the whole zero-friction flow.
+ */
+export function defaultRegion(now = new Date()) {
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone ?? "";
+    if (tz.startsWith("America/") || tz.startsWith("US/") || tz.startsWith("Canada/") || tz === "Pacific/Honolulu")
+        return "NA";
+    if (tz.startsWith("Asia/") || tz.startsWith("Australia/") || tz.startsWith("Pacific/"))
+        return "AS";
+    if (tz.startsWith("Europe/") || tz.startsWith("Africa/") || tz === "UTC")
+        return "EU";
+    // No zone name: fall back to the UTC offset (minutes WEST of UTC).
+    const offset = now.getTimezoneOffset();
+    if (offset >= 180)
+        return "NA";
+    if (offset <= -300)
+        return "AS";
+    return "EU";
+}
+// ---------------------------------------------------------------- urls
+/** The readable editor link for a framing: `/edit/<slug>-<id>` or `/edit/<id>`. */
+export function editUrl(framingId, slug) {
+    return `${apiBase()}/edit/${slug ? `${slug}-${framingId}` : framingId}`;
+}
+export function playUrl(framingId) {
+    return `${apiBase()}/play/${framingId}`;
+}
+/** The full catalog, version-matched to a framing's running engine when given. */
+export async function fetchNativeClientCatalog(framingId, fetchFn = fetch) {
+    const q = framingId ? `?framing_id=${encodeURIComponent(framingId)}` : "";
+    const res = await fetchFn(`${apiBase()}/api/v1/public/native-clients${q}`);
+    if (!res.ok)
+        throw new Error(`GET /api/v1/public/native-clients failed: HTTP ${res.status}`);
+    const body = (await res.json());
+    return { iteration: body.iteration ?? null, clients: body.clients ?? [] };
+}
+/** Website-builder operations share the hosted integration's canonical contract. */
+export async function getEmbed(target, fetchFn = fetch) {
+    const response = await fetchFn(`${apiBase()}/api/v1/public/embed?target=${encodeURIComponent(target)}`);
+    if (!response.ok)
+        throw await readError(response, "Resolving embed (the world must be shared)");
+    return await response.json();
+}
+export async function createWebsiteBuild(input, fetchFn = fetch) {
+    const response = await authorizedFetch(`${apiBase()}/api/v1/website-builds`, {
+        method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(input),
+    }, fetchFn);
+    if (!response.ok)
+        throw await readError(response, "Starting VM build");
+    return await response.json();
+}
+export async function getWebsiteBuild(buildId, fetchFn = fetch) {
+    const response = await authorizedFetch(`${apiBase()}/api/v1/website-builds/${encodeURIComponent(buildId)}`, {}, fetchFn);
+    if (!response.ok)
+        throw await readError(response, "Reading VM build status");
+    return await response.json();
+}

package/dist/auth.js

@@ -17,7 +17,7 @@ export class DeviceFlowDisabledError extends Error {
 }
 export class NotLoggedInError extends Error {
     constructor() {
-        super("Not signed in. Run `virtualmatter login` first.");
+        super("Not signed in. Run `npx virtualmatter login` first.");
         this.name = "NotLoggedInError";
     }
 }
@@ -48,7 +48,13 @@ function form(params) {
 /** Start the device flow: returns the codes to show the user, plus the token endpoint. */
 export async function startDeviceFlow(fetchFn = fetch) {
     const disco = await fetchDiscovery(fetchFn);
-    const res = await fetchFn(disco.device_authorization_endpoint, form({ client_id: OAUTH_CLIENT_ID, scope: "openid" }));
+    const res = await fetchFn(disco.device_authorization_endpoint, 
+    // offline_access is what makes this a CLI session rather than a
+    // browser tab: without it the refresh token dies with the SSO
+    // session's idle timeout (~30 min) and users get signed out
+    // overnight. With it, Keycloak issues an offline refresh token
+    // (realm default: 30-day idle) that survives browser logout.
+    form({ client_id: OAUTH_CLIENT_ID, scope: "openid offline_access" }));
     if (!res.ok) {
         let body = {};
         try {
@@ -78,7 +84,7 @@ export async function pollForToken(tokenEndpoint, auth, opts = {}) {
     const deadline = now() + auth.expires_in * 1000;
     for (;;) {
         if (now() > deadline) {
-            throw new Error("Device sign-in timed out before the code was approved. Run `virtualmatter login` again.");
+            throw new Error("Device sign-in timed out before the code was approved. Run `npx virtualmatter login` again.");
         }
         await sleep(intervalMs);
         const res = await fetchFn(tokenEndpoint, form({
@@ -109,7 +115,7 @@ export async function pollForToken(tokenEndpoint, auth, opts = {}) {
                 intervalMs += 5000;
                 continue;
             case "expired_token":
-                throw new Error("The sign-in code expired before it was approved. Run `virtualmatter login` again.");
+                throw new Error("The sign-in code expired before it was approved. Run `npx virtualmatter login` again.");
             case "access_denied":
                 throw new Error("Sign-in was denied.");
             case "unauthorized_client":