virtualmatter 0.1.0 → 0.3.0

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;
+}

package/dist/config.js

@@ -1,5 +1,7 @@
+import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 /** Platform API base. Overridable so dev/staging environments work. */
 export function apiBase() {
     const raw = process.env.VIRTUALMATTER_API_BASE ?? "https://make.virtualmatter.ai";
@@ -18,5 +20,26 @@ export function configDir() {
 export function credentialsPath() {
     return path.join(configDir(), "credentials.json");
 }
+/** Where downloaded native client builds are unpacked: <configDir>/client/<build>. */
+export function clientInstallRoot() {
+    return process.env.VIRTUALMATTER_CLIENT_DIR ?? path.join(configDir(), "client");
+}
 /** Name of the per-directory sync state file. */
 export const STATE_FILE = ".virtualmatter.json";
+/** The package version, read from package.json so it can never drift from npm. */
+export function packageVersion() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        for (const candidate of [path.join(here, "..", "package.json"), path.join(here, "..", "..", "package.json")]) {
+            if (fs.existsSync(candidate)) {
+                const pkg = JSON.parse(fs.readFileSync(candidate, "utf8"));
+                if (pkg.name === "virtualmatter" && typeof pkg.version === "string")
+                    return pkg.version;
+            }
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return "0.0.0";
+}

package/dist/files.js

@@ -3,6 +3,32 @@
  * https://<voxel_host>/s/<session_id>/api/montage/<framing_id>/...
  */
 import { authorizedFetch } from "./api.js";
+/**
+ * The reason an engine call failed, read out of the response body.
+ *
+ * The session API answers a refusal with
+ * `{detail: {error, message}}`, and dropping it left callers staring at a
+ * bare "HTTP 502" - which is exactly what sent test agents off to drive a
+ * browser instead. Falls back to the status when the body says nothing.
+ */
+export async function engineErrorMessage(res, what) {
+    let detail = "";
+    try {
+        const body = (await res.json());
+        const d = body.detail;
+        if (typeof d === "string")
+            detail = d;
+        else if (d && typeof d === "object" && typeof d.message === "string") {
+            detail = d.message;
+        }
+        else if (d)
+            detail = JSON.stringify(d);
+    }
+    catch {
+        /* non-JSON body */
+    }
+    return `${what} failed: HTTP ${res.status}${detail ? ` - ${detail}` : ""}`;
+}
 export class ConflictError extends Error {
     filePath;
     constructor(filePath) {
@@ -93,7 +119,7 @@ export class FilesClient {
             body: JSON.stringify({ code, target }),
         }, this.fetchFn);
         if (!res.ok)
-            throw new Error(`run-lua failed: HTTP ${res.status}`);
+            throw new Error(await engineErrorMessage(res, "run-lua"));
         // Server envelope: {output: <text>} - the engine bridge's text
         // (result/print/error sections) passed through verbatim.
         const body = (await res.json());
@@ -102,14 +128,36 @@ export class FilesClient {
     async engineErrors() {
         const res = await authorizedFetch(`${this.apiRoot}/engine/errors`, {}, this.fetchFn);
         if (!res.ok)
-            throw new Error(`Fetching engine errors failed: HTTP ${res.status}`);
+            throw new Error(await engineErrorMessage(res, "Fetching engine errors"));
         const body = (await res.json());
         return body.output;
     }
-    async screenshot() {
-        const res = await authorizedFetch(`${this.apiRoot}/engine/screenshot`, { method: "POST" }, this.fetchFn);
+    async screenshot(opts = {}) {
+        const body = {};
+        if (opts.target) {
+            body.target_object_id = opts.target;
+            if (opts.distance !== undefined)
+                body.distance = opts.distance;
+        }
+        else if (opts.at || opts.rot) {
+            const [px, py, pz] = opts.at ?? [0, 20, 20];
+            const [rx, ry, rz] = opts.rot ?? [0, -45, 0];
+            Object.assign(body, {
+                camera_pos_x: px,
+                camera_pos_y: py,
+                camera_pos_z: pz,
+                camera_rot_x: rx,
+                camera_rot_y: ry,
+                camera_rot_z: rz,
+            });
+        }
+        const res = await authorizedFetch(`${this.apiRoot}/engine/screenshot`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        }, this.fetchFn);
         if (!res.ok)
-            throw new Error(`Screenshot failed: HTTP ${res.status}`);
+            throw new Error(await engineErrorMessage(res, "Screenshot"));
         return Buffer.from(await res.arrayBuffer());
     }
 }

package/dist/ignore.js

@@ -15,9 +15,30 @@ export function isIgnoredPath(relPath) {
         return true;
     if (norm === STATE_FILE)
         return true;
-    if (norm === "AGENTS.md")
+    // Harness files the CLI drops into a pulled folder; they belong to the
+    // maker's machine, not the world.
+    if (norm === "AGENTS.md" || norm === "CLAUDE.md")
         return true;
     if (norm.endsWith(".remote-conflict"))
         return true;
+    // The SDK's in-session harness tooling at the Montage root. `atomo` only
+    // works against a running engine bridge, so mirroring it invites an agent
+    // to try it and fail; the CLI is the local path. Sync leaves them alone in
+    // both directions.
+    if (segments.length === 1 && isSdkHarnessTooling(first))
+        return true;
     return false;
 }
+const SDK_HARNESS_FILES = new Set([
+    "atomo",
+    "atomo.bat",
+    "atomo_cli.py",
+    "vm_auth.py",
+    "agent_log_sync.py",
+    "atomontage.code-workspace",
+]);
+export function isSdkHarnessTooling(name) {
+    if (SDK_HARNESS_FILES.has(name))
+        return true;
+    return /_agent_log_(sync|setup)\.py$/.test(name);
+}