virtualmatter 0.1.0 → 0.2.0

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.2.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",