@volter/editor-core 0.5.57

package/server/project-install-roots.ts

@@ -0,0 +1,210 @@
+/**
+ * WHERE A PROJECT'S MODULES REALLY LIVE ON DISK — the directory set a
+ * project-rooted Vite instance must be allowed to serve from
+ * (`server.fs.allow`).
+ *
+ * ## The measured defect
+ *
+ * `packaged.ts` used to allow exactly three paths: the project directory, the
+ * realpath of `<project>/node_modules` *when that directory exists*, and the
+ * editor package root. That set is correct for one shape of install — a
+ * standalone scaffold with its own flat `node_modules` — and wrong for every
+ * other shape a real project takes:
+ *
+ *  - an npm WORKSPACE MEMBER (every `examples/<id>`, and any user monorepo
+ *    game) has no `node_modules` of its own at all; npm hoists the install to
+ *    the workspace root ABOVE the project folder;
+ *  - a workspace member's own sibling packages resolve through SYMLINKS that
+ *    land outside the project entirely (`@vgai/game-runtime` → `<repo>/packages/
+ *    engine`), and Vite's `fs.allow` matches the symlink-RESOLVED path;
+ *  - a git worktree shares one install, so even the walk-up `node_modules`
+ *    can be a tree of links into another checkout.
+ *
+ * Measured live before this module existed, packaged editor + `examples/
+ * retro-shooter`: `/@fs/<repo>/packages/project/src/adapter/index.ts` → HTTP
+ * 403, i.e. the world's own engine imports were unreachable; and
+ * `react-data-grid/lib/styles.css?inline` (the data-tables document's grid
+ * stylesheet) came back `200 text/css` — RAW CSS where the importer expects a
+ * JS module — because with the file outside `fs.allow` the transform never ran
+ * and a raw-file route answered instead, which is what the browser reports as
+ * "Failed to fetch dynamically imported module".
+ *
+ * ## What this computes instead
+ *
+ * The same directories NODE would resolve from, asked the same way Node asks:
+ *
+ *  1. every `node_modules` directory on the walk UP from the project (this is
+ *     literally Node's module lookup path), realpath'd, existing ones only; and
+ *  2. for each dependency the project's own `package.json` DECLARES, the real
+ *     install root that dependency actually resolves to — the enclosing
+ *     `node_modules` directory when it is a normal install (covering hoisting,
+ *     symlinked worktree trees and pnpm's nested store), or the package's own
+ *     real directory when it is a linked workspace sibling that lives outside
+ *     any `node_modules` at all.
+ *
+ * Resolution is Node's (`createRequire` rooted at the project), never a
+ * hand-rolled path guess, so a shape this comment did not anticipate is still
+ * answered correctly. Entries contained in another entry are dropped, so the
+ * result is the smallest set that covers the project's real module graph — it
+ * never widens to "allow the whole filesystem" and never allows a directory no
+ * declared dependency resolves into.
+ */
+
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { searchForWorkspaceRoot } from 'vite';
+import { isPathInside } from './server-utils';
+
+/** Dependency fields whose entries a project's module graph can reach at
+ *  serve time. `devDependencies` counts: the editor serves stories, tools and
+ *  capability source, which import dev-only packages by design. */
+const DEPENDENCY_FIELDS = [
+  'dependencies',
+  'devDependencies',
+  'optionalDependencies',
+  'peerDependencies',
+] as const;
+
+function realDirectory(candidate: string): string | null {
+  try {
+    const real = realpathSync(candidate);
+    return statSync(real).isDirectory() ? real : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Every `node_modules` directory Node would consult on the walk up from `dir`
+ * — BOUNDED by the enclosing workspace root.
+ *
+ * The bound is Vite's own `searchForWorkspaceRoot` (lockfile / `workspaces`
+ * field / `.git`), which is exactly what Vite uses to compute its DEFAULT
+ * `fs.allow`, so this half of the set is no wider than the default a
+ * project-rooted Vite would have chosen for itself. Unbounded, the walk keeps
+ * climbing past the repository into `~/node_modules` and `/node_modules` —
+ * directories no project's resolution meaningfully depends on and which have
+ * no business in a serving allowlist. A dependency that genuinely does resolve
+ * from above the workspace root is still covered, one package at a time, by
+ * {@link packageServingRoot}.
+ */
+function walkUpNodeModules(dir: string): string[] {
+  const found: string[] = [];
+  const bound = path.resolve(searchForWorkspaceRoot(dir));
+  let current = path.resolve(dir);
+  for (;;) {
+    if (path.basename(current) !== 'node_modules') {
+      const real = realDirectory(path.join(current, 'node_modules'));
+      if (real) found.push(real);
+    }
+    const parent = path.dirname(current);
+    if (current === bound || parent === current) return found;
+    current = parent;
+  }
+}
+
+/** The declared dependency names of the project at `projectDir`, or `[]` when
+ *  it has no readable `package.json` (a project that has not been installed
+ *  yet still serves its own source; the walk-up set covers what exists). */
+function declaredDependencies(projectDir: string): string[] {
+  let manifest: Record<string, unknown>;
+  try {
+    manifest = JSON.parse(readFileSync(path.join(projectDir, 'package.json'), 'utf-8')) as Record<
+      string,
+      unknown
+    >;
+  } catch {
+    return [];
+  }
+  const names = new Set<string>();
+  for (const field of DEPENDENCY_FIELDS) {
+    const value = manifest[field];
+    if (value && typeof value === 'object') {
+      for (const name of Object.keys(value)) names.add(name);
+    }
+  }
+  return [...names];
+}
+
+/**
+ * The real directory serving `packageName` for a project rooted at
+ * `projectDir`, or `null` when it does not resolve.
+ *
+ * For an ordinary install this is the ENCLOSING `node_modules` directory (so
+ * one entry covers every package installed beside it, including the ones the
+ * project only reaches transitively). For a linked workspace sibling — whose
+ * real path contains no `node_modules` segment — it is that package's own
+ * directory, which is as tight as the allow entry can honestly be.
+ */
+export function packageServingRoot(projectDir: string, packageName: string): string | null {
+  // Rooted at the project's own `package.json`, the same discipline
+  // `resolveInstalledPackageSrcDir` (server-utils.ts) uses.
+  const require = createRequire(path.join(projectDir, 'package.json'));
+  let resolved: string;
+  try {
+    // The manifest resolves for any package, including one whose `exports`
+    // map hides its entry point from a bare specifier resolve.
+    resolved = require.resolve(`${packageName}/package.json`);
+  } catch {
+    try {
+      resolved = require.resolve(packageName);
+    } catch {
+      return null;
+    }
+  }
+  let real: string;
+  try {
+    real = realpathSync(resolved);
+  } catch {
+    return null;
+  }
+  const segments = real.split(path.sep);
+  const enclosing = segments.lastIndexOf('node_modules');
+  if (enclosing >= 0) return segments.slice(0, enclosing + 1).join(path.sep);
+  // A linked workspace sibling, which lives in no `node_modules` at all: allow
+  // the package's own ROOT. Walking up to the nearest `package.json` rather
+  // than taking the resolved file's directory, because the fallback resolve
+  // above lands on the package's ENTRY (`<pkg>/src/index.ts` for a package
+  // whose `exports` map hides `./package.json`), and allowing `<pkg>/src`
+  // would serve the entry while 403'ing every sibling file it imports.
+  return packageRootOf(path.dirname(real));
+}
+
+/** The nearest ancestor of `dir` (inclusive) that holds a `package.json`. */
+function packageRootOf(dir: string): string | null {
+  let current = dir;
+  for (;;) {
+    if (existsSync(path.join(current, 'package.json'))) return realDirectory(current);
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/** Drop every entry contained in another entry. */
+function minimalRoots(roots: readonly string[]): string[] {
+  const unique = [...new Set(roots)].filter((root) => root.length > 0);
+  return unique.filter(
+    (root) => !unique.some((other) => other !== root && isPathInside(other, root)),
+  );
+}
+
+/**
+ * Every real directory a project-rooted Vite instance must be able to serve
+ * from for the project's own module graph to resolve — the project itself
+ * plus its real install roots.
+ *
+ * Boot-time (and open-project-time) computation: an install that appears
+ * later is a dependency change, which already restarts or invalidates the
+ * module graph through its own path.
+ */
+export function projectServingRoots(projectDir: string): string[] {
+  const projectReal = realDirectory(projectDir) ?? path.resolve(projectDir);
+  const roots = [projectReal, ...walkUpNodeModules(projectReal)];
+  for (const name of declaredDependencies(projectReal)) {
+    const root = packageServingRoot(projectReal, name);
+    if (root && existsSync(root)) roots.push(root);
+  }
+  return minimalRoots(roots);
+}

package/server/project-kinds.ts

@@ -0,0 +1,71 @@
+/**
+ * The editor server's intake of a project's CONFIGURATION-KIND
+ * CONTRIBUTIONS (ARCHITECTURE-CORE §The project model): every
+ * `src/contributions/*.kind.ts` is evaluated through the same Vite SSR loader the
+ * operation catalog uses, and its `kind` export is registered in THIS
+ * process's engine registry before the manifest is read. Memoized on the
+ * modules' paths and mtimes, so a route pays nothing until a kind file
+ * changes.
+ */
+
+import { statSync } from 'node:fs';
+import {
+  contributedKindModulePaths,
+  registerKindModule,
+} from '@volter/editor-project/manifest/kind-modules';
+import type { ProjectModuleLoader } from './project-tools';
+
+let loader: ProjectModuleLoader | null = null;
+let signature = '';
+let unregister: Array<() => void> = [];
+let loadErrors: string[] = [];
+
+/** The loader the server evaluates project modules with; set once at boot. */
+export function setKindModuleLoader(next: ProjectModuleLoader | null): void {
+  loader = next;
+}
+
+export function kindModuleLoader(): ProjectModuleLoader | null {
+  return loader;
+}
+
+function currentSignature(paths: readonly string[]): string {
+  return paths
+    .map((path) => {
+      try {
+        return `${path}@${statSync(path).mtimeMs}`;
+      } catch {
+        return `${path}@gone`;
+      }
+    })
+    .join('|');
+}
+
+/** Register the project's kinds if their files changed since the last call.
+ *  Returns the load errors, which the caller surfaces by name. */
+export async function ensureProjectConfigurationKinds(
+  projectRoot: string,
+): Promise<readonly string[]> {
+  const paths = contributedKindModulePaths(projectRoot);
+  const next = `${projectRoot}::${currentSignature(paths)}`;
+  if (next === signature) return loadErrors;
+  for (const off of unregister) off();
+  unregister = [];
+  loadErrors = [];
+  if (paths.length > 0 && !loader) {
+    loadErrors.push(
+      "configuration kinds need the editor server's module host, which this session has not started",
+    );
+  } else {
+    for (const path of paths) {
+      try {
+        const module = await (loader as ProjectModuleLoader)(path);
+        unregister.push(registerKindModule(module, path));
+      } catch (error) {
+        loadErrors.push(`${path}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  }
+  signature = next;
+  return loadErrors;
+}

package/server/project-mcp-servers.ts

@@ -0,0 +1,82 @@
+/**
+ * THE PROJECT'S OWN MCP SERVERS, handed to the runtime the session starts.
+ *
+ * Every scaffolded project ships `.mcp.json` naming its own two servers — `vgai` and
+ * `blender` — and that file is how a person's Claude Code, run by hand in the project,
+ * reaches them. The AI IN THE TAB is the same agent (ARCHITECTURE-CORE §The core is
+ * Code-OSS, rule 7) and must reach the same servers.
+ *
+ * WHY IT CANNOT BE LEFT TO DISCOVERY, measured 2026-09-21 on a freshly scaffolded model
+ * project: Claude Code records per-project approval of a `.mcp.json` in `~/.claude.json`
+ * (`enabledMcpjsonServers`), and a project the person has never opened by hand has no
+ * entry — so a PROJECT-scoped server is not loaded. The runtime the session starts is
+ * `claude --print …`, which has no trust dialog to answer, so discovery can never turn
+ * into approval there. A freshly created project's agent would simply have no `blender`
+ * tool, silently.
+ *
+ * THE DOOR IS SUPERCODE'S AND ALREADY EXISTS: `RuntimeStartParams.mcp_servers`. Supercode's
+ * Claude backend writes them to a file and passes `--mcp-config <file>`
+ * (`crates/harness/src/runtime/adapters.rs`), which is an EXPLICIT caller-supplied config
+ * and therefore not subject to the project-approval gate at all. This module is only the
+ * read: the project's declaration, in the SDK's shape.
+ *
+ * IT IS NOT A SECOND DECLARATION. `.mcp.json` stays the one place a project names its
+ * servers; nothing here invents, defaults or merges one, and a project without the file
+ * hands over nothing.
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** `RuntimeStartParams.mcp_servers`'s element, structurally — the SDK is an optional peer. */
+export interface ProjectMcpServer {
+  readonly name: string;
+  readonly command: string;
+  readonly arguments?: readonly string[];
+  readonly env?: Readonly<Record<string, string>>;
+}
+
+function stringRecord(value: unknown): Record<string, string> | undefined {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  const entries = Object.entries(value as Record<string, unknown>).filter(
+    (entry): entry is [string, string] => typeof entry[1] === 'string',
+  );
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+
+/**
+ * The project's `.mcp.json`, as the SDK's `mcp_servers`. Empty for a project that declares
+ * none, and empty rather than thrown for a malformed one: a broken `.mcp.json` is the dev
+ * server's to report against the file, and failing the whole runtime start over it would
+ * cost the person their agent to say so.
+ *
+ * Only the STDIO shape is carried, because that is the shape the harnesses take as a
+ * launch: an entry with no string `command` is skipped rather than guessed at.
+ */
+export function projectMcpServers(projectRoot: string): ProjectMcpServer[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(join(projectRoot, '.mcp.json'), 'utf8'));
+  } catch {
+    return [];
+  }
+  const declared = (parsed as { mcpServers?: unknown } | null)?.mcpServers;
+  if (declared === null || typeof declared !== 'object' || Array.isArray(declared)) return [];
+  const servers: ProjectMcpServer[] = [];
+  for (const [name, value] of Object.entries(declared as Record<string, unknown>)) {
+    if (value === null || typeof value !== 'object') continue;
+    const entry = value as { command?: unknown; args?: unknown; env?: unknown };
+    if (typeof entry.command !== 'string' || entry.command === '') continue;
+    const args = Array.isArray(entry.args)
+      ? entry.args.filter((argument): argument is string => typeof argument === 'string')
+      : undefined;
+    const env = stringRecord(entry.env);
+    servers.push({
+      name,
+      command: entry.command,
+      ...(args && args.length > 0 ? { arguments: args } : {}),
+      ...(env ? { env } : {}),
+    });
+  }
+  return servers;
+}

package/server/project-module-freshness.ts

@@ -0,0 +1,109 @@
+/**
+ * A project module loaded ON USE is as fresh as the file on disk — never as
+ * fresh as the file watcher happens to be.
+ *
+ * The problem, measured on the blind modeling bench (2026-09-05): an agent
+ * edits `src/models/barrel.ts` and runs `vgai screenshot src/models/barrel.ts`
+ * in the same breath. The look verb's Node half loads the module through
+ * Vite's SSR runner, whose module graph is invalidated by the FILE WATCHER —
+ * and the watcher's change event lands seconds after the write (FSEvents on
+ * macOS, a poll tick on drvfs). Inside that window the runner hands back the
+ * previous evaluation, the four views come out byte-identical to the last
+ * look, and the agent concludes its edit did nothing. Four sessions in five
+ * hit it; one restarted the editor before every look, one tried to rewrite
+ * the project's own module loader and broke it, one shipped on a stale
+ * picture.
+ *
+ * The fix is the pattern `project-dependency-invalidation.ts` already uses
+ * for installs: check ON USE. Before a load, every module reachable from the
+ * requested one that lives under the project root is stat'ed; a file whose
+ * mtime moved since it was last evaluated has its graph node invalidated
+ * explicitly (the same invalidation the watcher performs — clears the
+ * transform, so the runner's next `fetchModule` re-transforms and
+ * re-evaluates). After a load, the reachable set's mtimes are recorded. A
+ * watcher event that arrives later is harmless: an already-invalidated node
+ * invalidates again for nothing.
+ *
+ * Scope is the PROJECT's own files. `node_modules` and the engine checkout are
+ * not stat'ed: the first is immutable between installs (and installs have
+ * their own door), the second restarts the server when it moves.
+ */
+
+import { statSync } from 'node:fs';
+import { sep } from 'node:path';
+import type { ViteDevServer } from 'vite';
+import type { ProjectModuleLoader } from './project-tools';
+
+interface GraphNode {
+  readonly id: string | null;
+  readonly file: string | null;
+  readonly importedModules: Set<GraphNode>;
+}
+
+interface Graph {
+  getModuleById(id: string): GraphNode | undefined;
+  invalidateModule(node: GraphNode): void;
+}
+
+function mtimeOf(file: string): number | undefined {
+  try {
+    return statSync(file).mtimeMs;
+  } catch {
+    return undefined; // deleted: the load itself will say so
+  }
+}
+
+/** Every graph node reachable from `entry` whose file sits under `root`. */
+function reachableProjectNodes(entry: GraphNode, root: string): GraphNode[] {
+  const prefix = root.endsWith(sep) ? root : `${root}${sep}`;
+  const seen = new Set<GraphNode>();
+  const out: GraphNode[] = [];
+  const stack = [entry];
+  while (stack.length) {
+    const node = stack.pop() as GraphNode;
+    if (seen.has(node)) continue;
+    seen.add(node);
+    const file = node.file;
+    if (!file || !file.startsWith(prefix) || file.includes(`${sep}node_modules${sep}`)) continue;
+    out.push(node);
+    for (const child of node.importedModules) stack.push(child);
+  }
+  return out;
+}
+
+export function freshProjectModuleLoader(
+  vite: ViteDevServer,
+  getProjectRoot: () => string | undefined,
+): ProjectModuleLoader {
+  const graph = vite.environments.ssr.moduleGraph as unknown as Graph;
+  const evaluatedAt = new Map<string, number>();
+  return async (moduleId: string) => {
+    const root = getProjectRoot();
+    if (root) {
+      const entry = graph.getModuleById(moduleId);
+      if (entry) {
+        for (const node of reachableProjectNodes(entry, root)) {
+          const file = node.file as string;
+          const recorded = evaluatedAt.get(file);
+          const current = mtimeOf(file);
+          if (recorded !== undefined && current !== undefined && current !== recorded) {
+            graph.invalidateModule(node);
+            evaluatedAt.delete(file);
+          }
+        }
+      }
+    }
+    const loaded = await vite.ssrLoadModule(moduleId);
+    if (root) {
+      const entry = graph.getModuleById(moduleId);
+      if (entry) {
+        for (const node of reachableProjectNodes(entry, root)) {
+          const file = node.file as string;
+          const current = mtimeOf(file);
+          if (current !== undefined) evaluatedAt.set(file, current);
+        }
+      }
+    }
+    return loaded;
+  };
+}