virtualmatter 0.1.0 → 0.3.0

package/dist/pull.js

@@ -2,53 +2,74 @@
 import fs from "node:fs";
 import path from "node:path";
 import { resolveSession, sessionBaseUrl } from "./api.js";
-import { apiBase } from "./config.js";
+import { composeAgentsMd, fetchAgentsMd, writeAgentFiles } from "./agentfiles.js";
 import { FilesClient } from "./files.js";
 import { isIgnoredPath } from "./ignore.js";
 import { saveState } from "./state.js";
-const AGENTS_MD_STUB = `# Working with Virtual Matter
-
-This folder is a live mirror of a Virtual Matter framing's Montage files.
-
-- \`virtualmatter sync\` keeps it in sync with the running session.
-- \`virtualmatter run-lua --code "..."\` executes Lua in the engine.
-- \`virtualmatter errors\` shows recent engine errors.
-- \`virtualmatter screenshot -o shot.png\` captures the current view.
-- 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) {
+export { AGENTS_MD_STUB, fetchAgentsMd } from "./agentfiles.js";
+/** Download workers per pull. The tree is ~1000 small files; sequential
+ *  GETs left the command silent for minutes. Eight in flight keeps a
+ *  single origin comfortable while cutting wall clock roughly 6-8x. */
+const PULL_CONCURRENCY = 8;
+/** One mutable status line on a TTY (`\r`-overwritten); on a plain
+ *  pipe, a heartbeat line every 100 files instead of 1000 spam lines. */
+function makeProgress(total) {
+    const tty = process.stderr.isTTY === true;
+    let count = 0;
+    return {
+        tick(current) {
+            count++;
+            if (tty) {
+                const label = current.length > 60 ? `...${current.slice(-57)}` : current;
+                process.stderr.write(`\r\x1b[2K[${count}/${total}] ${label}`);
+            }
+            else if (count % 100 === 0 || count === total) {
+                process.stderr.write(`[${count}/${total}] files pulled\n`);
+            }
+        },
+        done() {
+            if (tty)
+                process.stderr.write("\r\x1b[2K");
+        },
+    };
+}
+/** The engine SDK's AGENTS.md from the Montage tree, or null when the world has none. */
+export async function fetchEngineAgentsMd(client) {
     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;
-        }
+        const listing = await client.list();
+        if (!listing.some((f) => f.path === "AGENTS.md"))
+            return null;
+        const { bytes } = await client.get("AGENTS.md");
+        return bytes.toString("utf8");
     }
     catch {
-        /* fall through to the stub */
+        return null;
     }
-    return AGENTS_MD_STUB;
 }
 export async function pullTree(client, dir, framingId) {
     fs.mkdirSync(dir, { recursive: true });
-    const remote = await client.list();
+    const remote = (await client.list()).filter((f) => !isIgnoredPath(f.path));
     const state = { framing_id: framingId, etags: {} };
-    let count = 0;
-    for (const file of remote) {
-        if (isIgnoredPath(file.path))
-            continue;
-        const { bytes, etag } = await client.get(file.path);
-        const absPath = path.join(dir, file.path);
-        fs.mkdirSync(path.dirname(absPath), { recursive: true });
-        fs.writeFileSync(absPath, bytes);
-        state.etags[file.path] = etag ?? file.etag;
-        count++;
-    }
+    const progress = makeProgress(remote.length);
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            const index = next++;
+            if (index >= remote.length)
+                return;
+            const file = remote[index];
+            const { bytes, etag } = await client.get(file.path);
+            const absPath = path.join(dir, file.path);
+            fs.mkdirSync(path.dirname(absPath), { recursive: true });
+            fs.writeFileSync(absPath, bytes);
+            state.etags[file.path] = etag ?? file.etag;
+            progress.tick(file.path);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(PULL_CONCURRENCY, remote.length) }, () => worker()));
+    progress.done();
     saveState(dir, state);
-    return { dir, framingId, fileCount: count };
+    return { dir, framingId, fileCount: remote.length };
 }
 export async function pullCommand(framingId, dir) {
     console.log(`Resolving session for framing ${framingId} (this can cold-start one) ...`);
@@ -56,7 +77,7 @@ export async function pullCommand(framingId, dir) {
     const client = new FilesClient(sessionBaseUrl(session), framingId);
     console.log(`Session ready at ${sessionBaseUrl(session)}. Downloading files ...`);
     const result = await pullTree(client, dir, framingId);
-    const agentsMd = await fetchAgentsMd();
-    fs.writeFileSync(path.join(dir, "AGENTS.md"), agentsMd);
+    const [platformDoc, engineDoc] = await Promise.all([fetchAgentsMd(), fetchEngineAgentsMd(client)]);
+    result.agentFiles = writeAgentFiles(dir, composeAgentsMd(platformDoc, engineDoc));
     return result;
 }

package/dist/resolve.js

@@ -0,0 +1,65 @@
+/**
+ * Turn whatever the user handed us (a URL of any shape, a bare id, or
+ * nothing) into the one framing id every other command needs.
+ */
+import { getProject, getProjectByPublicId, listProjects } from "./api.js";
+import { loadState } from "./state.js";
+import { parseTarget } from "./urls.js";
+/** The make framing of a project row, or a clear error when it has none. */
+export function makeFramingOf(project) {
+    if (!project.make_framing_id) {
+        throw new Error(`Project "${project.name}" has no editing framing yet - open it in the browser once.`);
+    }
+    return project.make_framing_id;
+}
+export async function resolveParsedTarget(parsed, fetchFn = fetch) {
+    if (parsed.kind === "invalid")
+        throw new Error(parsed.reason);
+    if (parsed.kind === "framing")
+        return { framingId: parsed.framingId };
+    const project = parsed.publicId
+        ? await getProjectByPublicId(parsed.publicId, fetchFn)
+        : await getProject(parsed.montageId, fetchFn);
+    return { framingId: makeFramingOf(project), project };
+}
+/** Resolve a pasted target string. */
+export async function resolveTarget(target, fetchFn = fetch) {
+    return resolveParsedTarget(parseTarget(target), fetchFn);
+}
+/**
+ * No target given: the folder's state file wins; otherwise, when the
+ * account has exactly one project, that one - nothing to choose between.
+ * Anything else throws with the list, so the caller can print it.
+ */
+export async function resolveImplicitTarget(dir, fetchFn = fetch) {
+    const state = loadState(dir);
+    if (state)
+        return { framingId: state.framing_id };
+    const projects = (await listProjects(fetchFn)).filter((p) => p.make_framing_id);
+    if (projects.length === 1)
+        return { framingId: projects[0].make_framing_id, project: projects[0] };
+    if (projects.length === 0) {
+        throw new Error('You have no projects yet. Create one with `npx virtualmatter create "My world"`.');
+    }
+    throw new NeedsChoiceError(projects);
+}
+export class NeedsChoiceError extends Error {
+    projects;
+    constructor(projects) {
+        super("Which project? Pass its URL or id. Yours:\n" + formatProjectList(projects));
+        this.projects = projects;
+        this.name = "NeedsChoiceError";
+    }
+}
+export function formatProjectList(projects) {
+    if (projects.length === 0)
+        return "(no projects yet)";
+    const width = Math.min(40, Math.max(...projects.map((p) => p.name.length)));
+    return projects
+        .map((p) => {
+        const name = p.name.length > width ? p.name.slice(0, width - 1) + "…" : p.name.padEnd(width);
+        const fid = p.make_framing_id ?? "(no editing framing)";
+        return `  ${name}  ${fid}  ${p.region}`;
+    })
+        .join("\n");
+}

package/dist/urls.js

@@ -1,14 +1,34 @@
 /**
- * Parse the URL shapes a user may paste and extract a framing id.
+ * Parse anything a user (or an agent) may paste and say what it names.
  *
- * Framing-shaped (id resolves locally):
- *   /edit/<framingId>   /play/<framingId>   /m/<framingId>
- * Project-shaped (v1 does not resolve these):
- *   /g/<montageId>      /play/p/<montageId>
- * Accepted on any virtualmatter.ai / virtualmatter.dev host, and a bare
- * framing id (UUID) is accepted as-is.
+ * Framing-shaped - the id is right there:
+ *   /edit/<framingId>          /edit/<slug>-<framingId>
+ *   /play/<framingId>          /m/<framingId>
+ *   a bare framing id (21-char nanoid, or a legacy UUID)
+ * Project-shaped - resolved through the API to the project's make framing:
+ *   /g/<montageUuid>           /play/p/<montageUuid>
+ *   /projects/<slug>-<publicId> /projects/<publicId>  /projects/<montageUuid>
+ *   /p/<slug>-<publicId>        /p/<publicId>
+ * Accepted on any virtualmatter.ai / virtualmatter.dev host (plus localhost
+ * for dev), on the make.* and play.* subdomains alike.
+ *
+ * Readable segments are `<slug>-<identity>` with the identity FIXED-WIDTH and
+ * ANCHORED AT THE RIGHT END, mirroring `frontend/src/lib/readable-routes.ts`:
+ * framing ids are nanoids that routinely contain `-` (and can start with
+ * one), so splitting on any hyphen is wrong on real ids. Only `/edit/` is
+ * slug-aware; `/play/` and `/m/` are exact, so their segment is the whole id.
  */
 const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+/** Length of a minted `Framing.id` - mirrors `services/ids.py::FRAMING_ID_SIZE`. */
+export const FRAMING_ID_LENGTH = 21;
+/** Length of `Montage.public_id` - lowercase base36. */
+export const PUBLIC_ID_LENGTH = 8;
+const FRAMING_ID_CHARS_RE = /^[A-Za-z0-9_-]+$/;
+const PUBLIC_ID_RE = /^[0-9a-z]{8}$/;
+// Framing ids are nanoids (URL-safe alphabet, 21 chars as minted),
+// case-SENSITIVE - never lowercase them. 15-32 keeps obvious typos and
+// full URLs out while accepting every id shape the platform mints.
+const NANOID_RE = /^[A-Za-z0-9_-]{15,32}$/;
 function isVirtualmatterHost(host) {
     const h = host.toLowerCase();
     return (h === "virtualmatter.ai" ||
@@ -18,10 +38,34 @@ function isVirtualmatterHost(host) {
         h === "localhost" ||
         h === "127.0.0.1");
 }
-// Framing ids are nanoids (URL-safe alphabet, typically 21 chars),
-// case-SENSITIVE - never lowercase them. 15-32 keeps obvious typos and
-// full URLs out while accepting every id shape the platform mints.
-const NANOID_RE = /^[A-Za-z0-9_-]{15,32}$/;
+/** `<slug>-<identity>` with a fixed-width identity anchored at the right end. */
+function splitFixedWidth(value, length) {
+    if (value.length < length + 2)
+        return null;
+    if (value[value.length - length - 1] !== "-")
+        return null;
+    return { slug: value.slice(0, value.length - length - 1), identity: value.slice(value.length - length) };
+}
+/** The framing id inside an `/edit/` segment: bare, or `<slug>-<id>`. */
+export function framingIdFromEditSegment(segment) {
+    if (segment.length === FRAMING_ID_LENGTH)
+        return segment;
+    const split = splitFixedWidth(segment, FRAMING_ID_LENGTH);
+    if (split && FRAMING_ID_CHARS_RE.test(split.identity))
+        return split.identity;
+    return segment;
+}
+/** A `/p/` or `/projects/` segment as a project reference, or null. */
+function projectFromReadableSegment(segment) {
+    if (UUID_RE.test(segment))
+        return { kind: "project", montageId: segment.toLowerCase() };
+    if (PUBLIC_ID_RE.test(segment))
+        return { kind: "project", publicId: segment };
+    const split = splitFixedWidth(segment, PUBLIC_ID_LENGTH);
+    if (split && PUBLIC_ID_RE.test(split.identity))
+        return { kind: "project", publicId: split.identity };
+    return null;
+}
 export function parseTarget(input) {
     const trimmed = input.trim();
     if (UUID_RE.test(trimmed)) {
@@ -41,22 +85,33 @@ export function parseTarget(input) {
         return { kind: "invalid", reason: `Not a Virtual Matter host: ${url.hostname}` };
     }
     const parts = url.pathname.split("/").filter((p) => p.length > 0);
-    // Project-level shapes first: /g/<montageId> and /play/p/<montageId>
-    if (parts.length >= 2 && parts[0] === "g" && parts[1]) {
-        return { kind: "project", montageId: parts[1] };
+    const [first, second, third] = parts;
+    // Project-level shapes: /g/<uuid>, /play/p/<uuid>, /projects/<seg>, /p/<seg>
+    if (first === "g" && second) {
+        return projectFromReadableSegment(second) ?? { kind: "project", montageId: second };
+    }
+    if (first === "play" && second === "p" && third) {
+        return projectFromReadableSegment(third) ?? { kind: "project", montageId: third };
+    }
+    if ((first === "projects" || first === "p") && second) {
+        const project = projectFromReadableSegment(second);
+        if (project)
+            return project;
+        return { kind: "invalid", reason: `Not a readable project link: ${url.pathname}` };
+    }
+    // Framing shapes: /edit/<id or slug-id>, /play/<id>, /m/<id>
+    if (first === "edit" && second) {
+        const id = framingIdFromEditSegment(second);
+        return { kind: "framing", framingId: UUID_RE.test(id) ? id.toLowerCase() : id };
     }
-    if (parts.length >= 3 && parts[0] === "play" && parts[1] === "p" && parts[2]) {
-        return { kind: "project", montageId: parts[2] };
+    if ((first === "play" || first === "m") && second) {
+        return { kind: "framing", framingId: UUID_RE.test(second) ? second.toLowerCase() : second };
     }
-    // Framing shapes: /edit/<id>, /play/<id>, /m/<id>
-    if (parts.length >= 2 && parts[1] && ["edit", "play", "m"].includes(parts[0])) {
-        const id = parts[1];
-        if (UUID_RE.test(id)) {
-            return { kind: "framing", framingId: id.toLowerCase() };
-        }
-        return { kind: "framing", framingId: id };
+    if (first === "new" || parts.length === 0) {
+        return {
+            kind: "invalid",
+            reason: "That link is the home page, not a world. Run `npx virtualmatter create \"My world\"` to make one, or `npx virtualmatter list` to see yours.",
+        };
     }
     return { kind: "invalid", reason: `Unrecognized Virtual Matter URL path: ${url.pathname}` };
 }
-/** Human guidance for project-shaped URLs (v1 keeps it simple). */
-export const PROJECT_URL_HELP = "That link points at a whole project, not a single framing. Open the project in your browser and copy the /edit/<id> link for the framing you want, then try again.";

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "virtualmatter",
-  "version": "0.1.0",
-  "description": "CLI + MCP server for building with Virtual Matter - sync montage files, run Lua, capture screenshots, and wire coding agents into a live session.",
+  "version": "0.3.0",
+  "description": "CLI + MCP server for building with Virtual Matter - list and create worlds, sync their files, run Lua, capture screenshots, open the native client, and wire coding agents into a live session.",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "virtualmatter": "./dist/index.js",
-    "vm": "./dist/index.js"
+    "virtualmatter": "dist/index.js",
+    "vm": "dist/index.js"
   },
   "files": [
     "dist",