@volter/editor-core 0.5.57

package/server/checkout-workspace-preflight.ts

@@ -0,0 +1,349 @@
+/**
+ * Refuse a source-checkout editor whose workspace packages resolve into a
+ * different checkout.
+ *
+ * The checkout Vite config deliberately dedupes the runtime packages from its own
+ * root. A whole-directory `node_modules` symlink (or stale individual
+ * workspace links) therefore does more than use old dependencies: generated
+ * project code can import `WorldProvider` from one checkout while its
+ * `useDebugProvider` hook comes from another. The game renders, but all of its
+ * game-scoped command/provider registrations silently see the wrong Context.
+ *
+ * LOCAL-DEV's worktree shim is the one repair owner. The server must not try to
+ * mutate an install tree whose donor it cannot know; it fails before Vite boot
+ * with the exact invariant and repair seam instead.
+ *
+ * WHAT A WORKSPACE MEMBER IS comes from the root `package.json`'s own
+ * `workspaces` globs, and from nothing else — not a package list here, not the
+ * lockfile, and above all not a named package used as a "am I a source
+ * checkout?" probe. Both of those drift with a rename and go VACUOUS-GREEN:
+ * this guard spent the engine split (2026-09-21, `packages/engine` → `project`
+ * + `threejs-runtime` + `game-runtime`) returning `null` on every source
+ * checkout in the estate, because its first line asked for
+ * `packages/engine/package.json` and that package no longer exists — measured
+ * with the five links present AND with `@vgai/project`'s link deleted, both
+ * `null`. A guard that can be switched off by a rename is not a guard, so the
+ * question it asks is now the monorepo's own self-description.
+ */
+
+import {
+  type Dirent,
+  existsSync,
+  lstatSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+} from 'node:fs';
+import path from 'node:path';
+
+function canonical(candidate: string): string {
+  try {
+    return realpathSync(candidate);
+  } catch {
+    return path.resolve(candidate);
+  }
+}
+
+interface WorkspaceIdentity {
+  packageName: string;
+  source: string;
+}
+
+const workspaceIdentityCache = new Map<string, WorkspaceIdentity[]>();
+
+function readJson(file: string): unknown {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8')) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The root manifest's own `workspaces` globs — `packages/*`, `examples/*`, … */
+function workspaceGlobs(engineRoot: string): string[] {
+  const manifest = readJson(path.join(engineRoot, 'package.json')) as
+    | { workspaces?: string[] | { packages?: string[] } }
+    | undefined;
+  const declared = Array.isArray(manifest?.workspaces)
+    ? manifest.workspaces
+    : (manifest?.workspaces?.packages ?? []);
+  return declared.filter((glob): glob is string => typeof glob === 'string');
+}
+
+/**
+ * Expand the globs to the members that are ON DISK. Only the two shapes npm's
+ * own workspaces use here are honoured — a literal directory and a trailing
+ * `/*` — because a member this cannot see is a member this cannot refuse for,
+ * and a half-understood pattern silently becomes the vacuous green above.
+ */
+function expandWorkspaceGlob(engineRoot: string, glob: string): string[] {
+  const normalized = glob.replaceAll('\\', '/').replace(/\/+$/, '');
+  if (!normalized.endsWith('/*')) {
+    return existsSync(path.join(engineRoot, normalized, 'package.json')) ? [normalized] : [];
+  }
+  const parent = normalized.slice(0, -2);
+  let entries: Dirent[];
+  try {
+    entries = readdirSync(path.join(engineRoot, parent), { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => !entry.name.startsWith('.'))
+    .map((entry) => `${parent}/${entry.name}`)
+    .filter((source) => existsSync(path.join(engineRoot, source, 'package.json')));
+}
+
+/**
+ * The workspace globs, not the lockfile and not a maintained package list, own
+ * the topology: a member added to `packages/` before anyone regenerates the
+ * lock is still a member, and a member deleted by a rename stops being one in
+ * the same gesture. A directory whose manifest has no `name` is not a package
+ * and is skipped by name rather than guessed at.
+ */
+function checkoutWorkspaceIdentities(engineRoot: string): WorkspaceIdentity[] {
+  const cacheKey = canonical(engineRoot);
+  const cached = workspaceIdentityCache.get(cacheKey);
+  if (cached) return cached;
+  const identities: WorkspaceIdentity[] = [];
+  for (const glob of workspaceGlobs(engineRoot)) {
+    for (const source of expandWorkspaceGlob(engineRoot, glob)) {
+      const manifest = readJson(path.join(engineRoot, source, 'package.json')) as
+        | { name?: string }
+        | undefined;
+      if (typeof manifest?.name !== 'string' || manifest.name.length === 0) continue;
+      identities.push({ packageName: manifest.name, source });
+    }
+  }
+  identities.sort((a, b) => a.packageName.localeCompare(b.packageName));
+  workspaceIdentityCache.set(cacheKey, identities);
+  return identities;
+}
+
+/**
+ * Canonical top-level symlink topology participating in Vite resolution.
+ * Includes ordinary and scoped packages, but never crawls package contents.
+ */
+function installedLinkTopology(nodeModules: string): string[] {
+  const links: string[] = [];
+  let entries: Dirent[];
+  try {
+    entries = readdirSync(nodeModules, { withFileTypes: true });
+  } catch {
+    return links;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    const installed = path.join(nodeModules, entry.name);
+    if (entry.isSymbolicLink()) {
+      links.push(`${entry.name}=${canonical(installed)}`);
+      continue;
+    }
+    if (!entry.name.startsWith('@') || !entry.isDirectory()) continue;
+    let scopedEntries: Dirent[];
+    try {
+      scopedEntries = readdirSync(installed, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const scopedEntry of scopedEntries) {
+      if (!scopedEntry.isSymbolicLink()) continue;
+      const packageName = `${entry.name}/${scopedEntry.name}`;
+      links.push(`${packageName}=${canonical(path.join(installed, scopedEntry.name))}`);
+    }
+  }
+  return links.sort();
+}
+
+/**
+ * Identity input for the optimizer namespace. Vite's own config/lock hashes do
+ * not include symlink realpaths, so a relinked same-path project otherwise
+ * keeps accepting a cache built from a different checkout.
+ */
+export function editorResolutionTopology(engineRoot: string, projectPath?: string): string {
+  const parts = [
+    `engine-node-modules=${canonical(path.join(engineRoot, 'node_modules'))}`,
+    ...installedLinkTopology(path.join(engineRoot, 'node_modules')).map((v) => `engine:${v}`),
+  ];
+  if (projectPath) {
+    parts.push(
+      `project-node-modules=${canonical(path.join(projectPath, 'node_modules'))}`,
+      ...installedLinkTopology(path.join(projectPath, 'node_modules')).map((v) => `project:${v}`),
+    );
+  }
+  return parts.join('\n');
+}
+
+function repairMessage(engineRoot: string, detail: string): string {
+  return (
+    `Editor startup refused: source-checkout workspace identity is split. ${detail}\n` +
+    `Vite resolves shared @vgai modules from ${engineRoot}/node_modules, so continuing could ` +
+    'render a game with a different WorldProvider/debug registry identity. Recreate this ' +
+    "checkout's node_modules with scripts/worktree-node-modules-shim.mjs as documented in " +
+    'docs/LOCAL-DEV.md; never symlink the whole node_modules directory.'
+  );
+}
+
+function projectRepairMessage(
+  projectPath: string,
+  installed: string,
+  actual: string,
+  expected: string,
+): string {
+  return (
+    `Editor startup refused: ${installed} resolves to ${actual}, but the serving checkout ` +
+    `requires ${expected}. A live editor cannot compose workspace packages from two checkouts. ` +
+    `Either launch this project from the checkout at ${actual} or relink it to this checkout ` +
+    `with \`cd ${projectPath} && npm link --no-save ${expected}\`.`
+  );
+}
+
+/**
+ * Every member the globs found must have a link in the checkout's own
+ * `node_modules`, pointing at the checkout's own source. A member with NO link
+ * is refused by name: nothing later in the boot can tell that absence from a
+ * package nobody imports, and the shim is the one repair.
+ */
+function engineLinkError(
+  normalizedRoot: string,
+  nodeModules: string,
+  identities: WorkspaceIdentity[],
+): string | null {
+  for (const { packageName, source: relativeSource } of identities) {
+    const installed = path.join(nodeModules, ...packageName.split('/'));
+    const expected = path.join(normalizedRoot, relativeSource);
+    if (!existsSync(installed)) {
+      return repairMessage(normalizedRoot, `${installed} is missing; expected ${expected}.`);
+    }
+    const actual = canonical(installed);
+    const expectedCanonical = canonical(expected);
+    if (actual !== expectedCanonical) {
+      return repairMessage(
+        normalizedRoot,
+        `${installed} resolves to ${actual}; expected this checkout's ${expectedCanonical}.`,
+      );
+    }
+  }
+  return null;
+}
+
+/**
+ * A registry-installed project copy is intentionally collapsed by the
+ * checkout's Vite dedupe. A project-local SYMLINK is different: it is an
+ * explicit checkout selection, and if it names another checkout the active
+ * server must restart there rather than compose both graphs. Check every
+ * workspace member, not a hand-maintained `@vgai` subset.
+ */
+function projectLinkError(
+  normalizedRoot: string,
+  identities: WorkspaceIdentity[],
+  projectPath?: string,
+): string | null {
+  if (projectPath === undefined) return null;
+  for (const { packageName, source: relativeSource } of identities) {
+    const installed = path.join(projectPath, 'node_modules', ...packageName.split('/'));
+    try {
+      if (!lstatSync(installed).isSymbolicLink()) continue;
+    } catch {
+      continue;
+    }
+    const actual = canonical(installed);
+    const expected = canonical(path.join(normalizedRoot, relativeSource));
+    if (actual !== expected) {
+      return projectRepairMessage(projectPath, installed, actual, expected);
+    }
+  }
+  return null;
+}
+
+/**
+ * No-op for a packaged editor: a published package declares no `workspaces`,
+ * so it has no members and nothing to split. A source checkout is recognized
+ * by that declaration alone — never by a package name, which a rename deletes.
+ */
+export function checkoutWorkspaceIdentityError(
+  engineRoot: string,
+  projectPath?: string,
+): string | null {
+  const normalizedRoot = path.resolve(engineRoot);
+  if (workspaceGlobs(normalizedRoot).length === 0) return null;
+
+  const nodeModules = path.join(normalizedRoot, 'node_modules');
+  try {
+    if (lstatSync(nodeModules).isSymbolicLink()) {
+      return repairMessage(
+        normalizedRoot,
+        `${nodeModules} is a whole-directory symlink to ${canonical(nodeModules)}.`,
+      );
+    }
+  } catch {
+    // Missing/unreadable node_modules will already make this source server's
+    // dependency imports fail by name. Do not replace that useful native error.
+    return null;
+  }
+
+  const identities = checkoutWorkspaceIdentities(normalizedRoot);
+  if (identities.length === 0) {
+    return repairMessage(
+      normalizedRoot,
+      `${path.join(normalizedRoot, 'package.json')} declares workspace globs ` +
+        `(${workspaceGlobs(normalizedRoot).join(', ')}) that match no package on disk.`,
+    );
+  }
+  return (
+    engineLinkError(normalizedRoot, nodeModules, identities) ??
+    projectLinkError(normalizedRoot, identities, projectPath)
+  );
+}
+
+export function assertCheckoutWorkspaceIdentity(engineRoot: string, projectPath?: string): void {
+  const error = checkoutWorkspaceIdentityError(engineRoot, projectPath);
+  if (error !== null) throw new Error(error);
+}
+
+export interface WorkspaceIdentityRestartMonitor {
+  checkNow(): void;
+  dispose(): void;
+}
+
+/**
+ * Poll the tiny top-level link set because npm relinking replaces symlinks in
+ * node_modules, a path source watchers intentionally ignore. Fires once: the
+ * existing exit-75 handoff owns the actual process replacement.
+ */
+export function createWorkspaceIdentityRestartMonitor(options: {
+  engineRoot: string;
+  projectPath: () => string | undefined;
+  onStale: (change: { changedPath: string; changedAt: string }) => void;
+  intervalMs?: number;
+  now?: () => Date;
+  setInterval?: (callback: () => void, ms: number) => unknown;
+  clearInterval?: (timer: unknown) => void;
+}): WorkspaceIdentityRestartMonitor {
+  let fired = false;
+  const checkNow = (): void => {
+    if (fired) return;
+    if (checkoutWorkspaceIdentityError(options.engineRoot, options.projectPath()) === null) return;
+    fired = true;
+    options.onStale({
+      changedPath: 'node_modules workspace package links',
+      changedAt: (options.now ?? (() => new Date()))().toISOString(),
+    });
+  };
+  const setTimer =
+    options.setInterval ??
+    ((callback: () => void, ms: number): unknown => {
+      const timer = setInterval(callback, ms);
+      timer.unref();
+      return timer;
+    });
+  const clearTimer =
+    options.clearInterval ?? ((timer: unknown): void => clearInterval(timer as NodeJS.Timeout));
+  const timer = setTimer(checkNow, options.intervalMs ?? 1_000);
+  return {
+    checkNow,
+    dispose(): void {
+      clearTimer(timer);
+    },
+  };
+}

package/server/cloud-asset-catalog.ts

@@ -0,0 +1,158 @@
+/**
+ * Node's client for the deployed `cloud-asset-library` Worker: it reads
+ * `VGAI_CLOUD_ASSET_URL` and resolves variants through GraphQL, neither of
+ * which a browser bundle can do — so the FETCHING here is genuinely its own.
+ *
+ * What the worker RETURNS is not. `CloudAssetObject`/`CloudAssetFile`/
+ * `CloudAssetRecord` and the manifest response are declared once, in
+ * `src/asset-workflow/cloud-asset-client.ts` (a browser-safe module `server/`
+ * can import but which cannot import back — see its header), and imported here.
+ * The mirror that used to live in this file had drifted into the worker's
+ * INTERNAL pre-projection shape: `familyId`/`label`/`categories`/`tags`
+ * optional, plus a `key` no editor path reads and this file's own GraphQL
+ * query does not select.
+ */
+
+import type {
+  CloudAssetManifestResponse,
+  CloudAssetRecord,
+} from '../src/asset-workflow/cloud-asset-client';
+
+export const DEFAULT_CLOUD_ASSET_BASE_URL = 'https://vgai-asset-library.aaron-0ed.workers.dev';
+
+export type {
+  CloudAssetFile,
+  CloudAssetManifestResponse,
+  CloudAssetObject,
+  CloudAssetRecord,
+} from '../src/asset-workflow/cloud-asset-client';
+
+let cachedManifest:
+  | { value: CloudAssetManifestResponse; url: string; loadedAt: number }
+  | undefined;
+const CACHE_MS = 5 * 60 * 1000;
+const GRAPHQL_ID_BATCH = 500;
+const graphqlAssetCache = new Map<
+  string,
+  { baseUrl: string; value: CloudAssetRecord | null; loadedAt: number }
+>();
+
+export function getCloudAssetBaseUrl(): string {
+  return (process.env['VGAI_CLOUD_ASSET_URL'] ?? DEFAULT_CLOUD_ASSET_BASE_URL).replace(/\/+$/, '');
+}
+
+export async function loadCloudAssetManifest(): Promise<CloudAssetManifestResponse | null> {
+  const baseUrl = getCloudAssetBaseUrl();
+  if (
+    cachedManifest &&
+    cachedManifest.url === baseUrl &&
+    Date.now() - cachedManifest.loadedAt < CACHE_MS
+  ) {
+    return cachedManifest.value;
+  }
+  try {
+    const response = await fetch(`${baseUrl}/v1/manifest`, { signal: AbortSignal.timeout(5_000) });
+    if (!response.ok) return null;
+    const value = (await response.json()) as CloudAssetManifestResponse;
+    if ((value.version !== 1 && value.version !== 2) || !Array.isArray(value.assets)) return null;
+    cachedManifest = { value, url: baseUrl, loadedAt: Date.now() };
+    return value;
+  } catch {
+    return null;
+  }
+}
+
+export async function findCloudAsset(id: string): Promise<CloudAssetRecord | null> {
+  return (await findCloudAssets([id]))[0] ?? null;
+}
+
+async function queryCloudAssets(ids: readonly string[]): Promise<CloudAssetRecord[] | null> {
+  if (ids.length === 0) return [];
+  const response = await fetch(`${getCloudAssetBaseUrl()}/graphql`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      query: `query CloudAssets($ids: [ID!]!) {
+        assetsByIds(ids: $ids) {
+          id familyId label status source name type license author sourceUrl attribution categories tags
+          files: deliveries {
+            label format
+            main { sha256 sizeBytes contentType relativePath }
+            dependencies { sha256 sizeBytes contentType relativePath }
+          }
+        }
+      }`,
+      variables: { ids },
+    }),
+    signal: AbortSignal.timeout(5_000),
+  });
+  if (!response.ok) return null;
+  const body = (await response.json()) as {
+    data?: { assetsByIds?: CloudAssetRecord[] };
+    errors?: unknown[];
+  };
+  return body.errors || !Array.isArray(body.data?.assetsByIds) ? null : body.data.assetsByIds;
+}
+
+/** Resolve exact hosted variants through GraphQL; REST manifest is rollout fallback only. */
+export async function findCloudAssets(ids: readonly string[]): Promise<CloudAssetRecord[]> {
+  const uniqueIds = [...new Set(ids)];
+  const baseUrl = getCloudAssetBaseUrl();
+  const now = Date.now();
+  const unresolved = uniqueIds.filter((id) => {
+    const cached = graphqlAssetCache.get(id);
+    return !cached || cached.baseUrl !== baseUrl || now - cached.loadedAt >= CACHE_MS;
+  });
+  try {
+    for (let offset = 0; offset < unresolved.length; offset += GRAPHQL_ID_BATCH) {
+      const batch = unresolved.slice(offset, offset + GRAPHQL_ID_BATCH);
+      const found = await queryCloudAssets(batch);
+      if (!found) throw new Error('GraphQL catalog unavailable.');
+      const byId = new Map(found.map((asset) => [asset.id, asset]));
+      for (const id of batch) {
+        graphqlAssetCache.set(id, { baseUrl, value: byId.get(id) ?? null, loadedAt: now });
+      }
+    }
+    return uniqueIds.flatMap((id) => {
+      const asset = graphqlAssetCache.get(id)?.value;
+      return asset ? [asset] : [];
+    });
+  } catch {
+    const manifest = await loadCloudAssetManifest();
+    const requested = new Set(uniqueIds);
+    return manifest?.assets.filter((asset) => requested.has(asset.id)) ?? [];
+  }
+}
+
+export function cloudAssetObjectUrl(
+  assetId: string,
+  fileIndex: number,
+  dependencyIndex?: number,
+): string {
+  const base = `${getCloudAssetBaseUrl()}/v1/assets/${encodeURIComponent(assetId)}/files/${fileIndex}`;
+  return dependencyIndex === undefined ? base : `${base}/dependencies/${dependencyIndex}`;
+}
+
+export function parseCloudAssetObjectUrl(
+  value: string,
+  expectedAssetId: string,
+): { fileIndex: number; dependencyIndex?: number } | null {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return null;
+  }
+  const expectedBase = new URL(getCloudAssetBaseUrl());
+  if (url.protocol !== 'https:' || url.origin !== expectedBase.origin || url.search || url.hash)
+    return null;
+  const prefix = expectedBase.pathname.replace(/\/$/, '');
+  const relativePath = url.pathname.slice(prefix.length);
+  const match = /^\/v1\/assets\/([a-f0-9]{24})\/files\/(\d+)(?:\/dependencies\/(\d+))?$/.exec(
+    relativePath,
+  );
+  if (!match || match[1] !== expectedAssetId) return null;
+  const parsed: { fileIndex: number; dependencyIndex?: number } = { fileIndex: Number(match[2]) };
+  if (match[3] !== undefined) parsed.dependencyIndex = Number(match[3]);
+  return parsed;
+}