virtualmatter 0.1.0 → 0.2.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,23 +17,35 @@ 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
@@ -43,49 +56,51 @@ npx virtualmatter screenshot -o shot.png
 
 ## Hook up a coding agent (MCP)
 
-Register the MCP server with Claude Code in one line, from a pulled folder:
-
-```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, and the
+  harness files the CLI writes (`AGENTS.md`, `CLAUDE.md`, `.mcp.json`,
+  `.cursor/`, `.virtualmatter.json`).
 - `pull` may cold-start a session for the framing; the first one can take a
   minute.

package/dist/agentfiles.js

@@ -0,0 +1,72 @@
+/**
+ * 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"],
+    };
+}
+/** 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,96 @@ 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 ?? [] };
+}

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":

package/dist/client.js

@@ -0,0 +1,317 @@
+/**
+ * The native client, without the human in the loop: pick the build for this
+ * OS, download it, unpack it, hand it the world URL, and sign it in with the
+ * credentials the CLI already holds.
+ *
+ * Builds are unpacked under <configDir>/client/<dir_uid>/ so re-running
+ * `open` is instant, and a newer build lands next to the old one instead
+ * of over it. Archives are removed after extraction.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fetchNativeClientCatalog } from "./api.js";
+import { loadCredentials } from "./auth.js";
+import { OAUTH_CLIENT_ID, clientInstallRoot, oidcDiscoveryUrl } from "./config.js";
+export function detectPlatform(p = process.platform) {
+    if (p === "darwin")
+        return "macos";
+    if (p === "win32")
+        return "windows";
+    return "linux";
+}
+/** The build the catalog offers for a platform, or null when there is none. */
+export function pickBuild(clients, platform) {
+    return clients.find((c) => c.platform.toLowerCase() === platform && c.kind === "download") ?? null;
+}
+/** A stable per-build install directory name derived from the download path. */
+export function buildKey(client) {
+    const m = /\/download\/([^/]+)\//.exec(client.url);
+    if (m?.[1])
+        return m[1];
+    const base = client.filename ?? path.basename(client.url);
+    return base.replace(/[^A-Za-z0-9._-]/g, "_").replace(/\.(zip|tgz|tar\.gz|tar\.xz|dmg)$/i, "");
+}
+const MARKER = "installed.json";
+/**
+ * Locate the launch target inside an unpacked tree. Mirrors the platform's
+ * `_ENTRYPOINT_CANDIDATES`, plus the .app bundle on macOS since `open`
+ * wants the bundle, not the Mach-O inside it.
+ */
+export function findEntrypoint(dir, platform) {
+    const walk = (root, depth) => {
+        if (depth < 0)
+            return [];
+        let entries;
+        try {
+            entries = fs.readdirSync(root, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+        const out = [];
+        for (const e of entries) {
+            const full = path.join(root, e.name);
+            out.push(full);
+            if (e.isDirectory() && !e.name.endsWith(".app"))
+                out.push(...walk(full, depth - 1));
+        }
+        return out;
+    };
+    const all = walk(dir, 2);
+    const byName = (names) => {
+        for (const n of names) {
+            const hit = all.find((p) => path.basename(p).toLowerCase() === n);
+            if (hit)
+                return hit;
+        }
+        return null;
+    };
+    if (platform === "macos") {
+        const app = all.find((p) => p.endsWith(".app") && fs.statSync(p).isDirectory());
+        return app ?? null;
+    }
+    if (platform === "windows")
+        return byName(["atomontage client.exe", "client.exe", "studio.exe"]);
+    return byName(["run.sh", "client", "studio"]);
+}
+export function loadInstalled(dir) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(dir, MARKER), "utf8"));
+        if (raw.entrypoint && fs.existsSync(raw.entrypoint))
+            return { ...raw, dir };
+    }
+    catch {
+        /* not installed */
+    }
+    return null;
+}
+async function download(url, dest, onProgress, fetchFn = fetch) {
+    const res = await fetchFn(url);
+    if (!res.ok || !res.body)
+        throw new Error(`Download failed: HTTP ${res.status} for ${url}`);
+    const total = Number(res.headers.get("content-length")) || null;
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    const tmp = `${dest}.part`;
+    const out = fs.createWriteStream(tmp);
+    let received = 0;
+    const reader = res.body.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            received += value.byteLength;
+            if (!out.write(value))
+                await new Promise((r) => out.once("drain", () => r()));
+            onProgress(received, total);
+        }
+    }
+    finally {
+        await new Promise((resolve, reject) => {
+            out.end(() => resolve());
+            out.on("error", reject);
+        });
+    }
+    fs.renameSync(tmp, dest);
+}
+/** Unpack with the OS's own tools: ditto keeps bundle symlinks + bits on macOS; bsdtar handles zip + tgz elsewhere. */
+export function extractArchive(archive, dest, platform) {
+    fs.mkdirSync(dest, { recursive: true });
+    const lower = archive.toLowerCase();
+    let cmd;
+    let args;
+    if (platform === "macos" && lower.endsWith(".zip")) {
+        cmd = "ditto";
+        args = ["-x", "-k", archive, dest];
+    }
+    else if (lower.endsWith(".zip")) {
+        cmd = "tar";
+        args = ["-xf", archive, "-C", dest];
+    }
+    else if (/\.(tgz|tar\.gz|tar\.xz|tar\.bz2|tar)$/.test(lower)) {
+        cmd = "tar";
+        args = ["-xf", archive, "-C", dest];
+    }
+    else {
+        throw new Error(`Don't know how to unpack ${path.basename(archive)}.`);
+    }
+    const res = spawnSync(cmd, args, { stdio: ["ignore", "ignore", "pipe"] });
+    if (res.error)
+        throw new Error(`Could not run ${cmd}: ${res.error.message}`);
+    if (res.status !== 0) {
+        throw new Error(`${cmd} failed (${res.status}): ${res.stderr?.toString().trim()}`);
+    }
+}
+function formatMb(bytes) {
+    return `${(bytes / 1048576).toFixed(0)} MB`;
+}
+/** Download + unpack the right build unless it is already here. */
+export async function ensureClientInstalled(opts = {}) {
+    const platform = opts.platform ?? detectPlatform();
+    const log = opts.log ?? ((m) => console.error(m));
+    const fetchFn = opts.fetchFn ?? fetch;
+    const catalog = await fetchNativeClientCatalog(opts.framingId, fetchFn);
+    const build = pickBuild(catalog.clients, platform);
+    if (!build) {
+        const others = catalog.clients.map((c) => `${c.platform} (${c.kind})`).join(", ");
+        throw new Error(`No native client build is published for ${platform} yet. Available: ${others || "none"}.`);
+    }
+    const dir = path.join(clientInstallRoot(), buildKey(build));
+    const existing = opts.force ? null : loadInstalled(dir);
+    if (existing)
+        return existing;
+    const url = build.url.startsWith("http") ? build.url : `${apiBaseFor(build)}${build.url}`;
+    const archive = path.join(clientInstallRoot(), build.filename ?? path.basename(build.url));
+    log(`Downloading the Virtual Matter client for ${platform}${build.file_size ? ` (${formatMb(build.file_size)})` : ""} ...`);
+    let lastPct = -1;
+    await download(url, archive, (received, total) => {
+        if (!total)
+            return;
+        const pct = Math.floor((received / total) * 100);
+        if (pct !== lastPct && (pct % 10 === 0 || pct === 100)) {
+            lastPct = pct;
+            log(`  ${pct}%`);
+        }
+    }, fetchFn);
+    log(`Unpacking into ${dir} ...`);
+    fs.rmSync(dir, { recursive: true, force: true });
+    extractArchive(archive, dir, platform);
+    fs.rmSync(archive, { force: true });
+    const entrypoint = findEntrypoint(dir, platform);
+    if (!entrypoint)
+        throw new Error(`Unpacked ${build.filename ?? "the build"} but found nothing to launch in ${dir}.`);
+    if (platform !== "windows") {
+        // Archives produced on Windows CI can lose the executable bit.
+        for (const p of [entrypoint, path.join(dir, "Client"), path.join(dir, "crashpad_handler")]) {
+            try {
+                if (fs.statSync(p).isFile())
+                    fs.chmodSync(p, 0o755);
+            }
+            catch {
+                /* absent */
+            }
+        }
+    }
+    const installed = { platform, dir, entrypoint, build };
+    fs.writeFileSync(path.join(dir, MARKER), JSON.stringify(installed, null, 2) + "\n");
+    return installed;
+}
+function apiBaseFor(_build) {
+    // Download paths are relative to the platform origin the catalog came from.
+    return (process.env.VIRTUALMATTER_API_BASE ?? "https://make.virtualmatter.ai").replace(/\/+$/, "");
+}
+/** Launch the client into a world, detached from this process. */
+export function launchClient(installed, montageUrl) {
+    const arg = `--montage-url=${montageUrl}`;
+    let cmd;
+    let args;
+    if (installed.platform === "macos") {
+        cmd = "open";
+        args = ["-n", "-a", installed.entrypoint, "--args", arg];
+    }
+    else {
+        cmd = installed.entrypoint;
+        args = [arg];
+    }
+    const child = spawn(cmd, args, {
+        cwd: installed.platform === "macos" ? undefined : path.dirname(installed.entrypoint),
+        detached: true,
+        stdio: "ignore",
+        windowsHide: false,
+    });
+    child.on("error", (err) => {
+        console.error(`Could not launch the client: ${err.message}`);
+    });
+    child.unref();
+}
+// ---------------------------------------------------------------- sign-in hand-over
+/**
+ * Where the client keeps its sign-in file. Installer builds use the
+ * per-user app-data folder (SDL_GetPrefPath("Atomontage", "Atomontage
+ * Studio")); portable builds keep UserData next to the executable. Both
+ * are seeded so whichever the build reads, it finds a session.
+ */
+export function nativeUserDataDirs(installed, platform, home = os.homedir()) {
+    const dirs = [];
+    if (platform === "macos") {
+        dirs.push(path.join(home, "Library", "Application Support", "Atomontage", "Atomontage Studio", "UserData"));
+    }
+    else if (platform === "windows") {
+        const appData = process.env.APPDATA ?? path.join(home, "AppData", "Roaming");
+        dirs.push(path.join(appData, "Atomontage", "Atomontage Studio", "UserData"));
+    }
+    else {
+        const dataHome = process.env.XDG_DATA_HOME ?? path.join(home, ".local", "share");
+        dirs.push(path.join(dataHome, "Atomontage", "Atomontage Studio", "UserData"));
+    }
+    if (installed && platform !== "macos")
+        dirs.push(path.join(path.dirname(installed.entrypoint), "UserData"));
+    return dirs;
+}
+function decodeJwtClaims(token) {
+    try {
+        const payload = token.split(".")[1] ?? "";
+        return JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** The session file shape `vm_auth.py` (in the engine SDK) reads and refreshes. */
+export function nativeAuthSession(creds) {
+    const claims = decodeJwtClaims(creds.access_token);
+    const disco = new URL(oidcDiscoveryUrl());
+    const m = /^(.*)\/realms\/([^/]+)\//.exec(disco.pathname);
+    const authBase = `${disco.origin}${m?.[1] ?? "/auth"}`;
+    const realm = m?.[2] ?? "Atomontage";
+    return {
+        access_token: creds.access_token,
+        refresh_token: creds.refresh_token ?? "",
+        id_token: "",
+        access_expires_at: Math.floor(creds.expires_at / 1000),
+        // 0 = "no known expiry": an offline refresh token from the CLI's
+        // device flow does not carry one, and a stamped-but-past value would
+        // read as expired.
+        refresh_expires_at: 0,
+        auth_base: authBase,
+        realm,
+        client_id: OAUTH_CLIENT_ID,
+        user: claims.preferred_username || claims.email || claims.sub || "",
+        email: claims.email || "",
+        sub: claims.sub || "",
+    };
+}
+/**
+ * Sign the native client in with the CLI's session. Skipped when the
+ * client already holds a session for the same account, so a sign-in done
+ * inside the app is never clobbered. Returns the files written.
+ */
+export function seedNativeAuth(installed, platform = detectPlatform()) {
+    const creds = loadCredentials();
+    if (!creds?.refresh_token)
+        return [];
+    const session = nativeAuthSession(creds);
+    const written = [];
+    for (const dir of nativeUserDataDirs(installed, platform)) {
+        const file = path.join(dir, "vm_auth.json");
+        try {
+            const existing = JSON.parse(fs.readFileSync(file, "utf8"));
+            if (existing.refresh_token && existing.sub === session.sub)
+                continue;
+        }
+        catch {
+            /* absent or unreadable: write */
+        }
+        try {
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(file, JSON.stringify(session) + "\n", { mode: 0o600 });
+            written.push(file);
+        }
+        catch {
+            /* a read-only location is not worth failing the launch over */
+        }
+    }
+    return written;
+}