@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/server/dev.ts

@@ -7,16 +7,27 @@
  * Supports VGAI_PROJECT env var for initial project path.
  */
 
-import { type Dirent, readdirSync, realpathSync, statSync } from 'node:fs';
+import {
+  type Dirent,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import express from 'express';
 import { createServer as createViteServer } from 'vite';
+import { gameGlobalsShadowPlugin } from '../vite-plugin-game-globals';
 import { projectGameStaticPlugin } from '../vite-plugin-project-game-static';
 import { canonicalProjectRoot } from './canonical-path';
 import { createEditorServer } from './editor-server';
-import { gameGlobalsShadowPlugin } from '../vite-plugin-game-globals';
 import { ingestGameShadowRoots } from './game-globals-shadow';
+import { closeHttpServer, createProcessShutdown } from './process-shutdown';
+import { classifyProjectHotUpdate } from './project-hmr-files';
 import { friendlyListenError, resolveBindHost } from './server-utils';
 import { registerSession, unregisterSession } from './session-registry';
 
@@ -24,7 +35,12 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // Port is env-overridable so multiple editor servers (e.g. parallel e2e/capture
 // runs across git worktrees) don't collide on 5173. Defaults preserve behavior.
 const PORT = Number(process.env['VGAI_EDITOR_PORT']) || 5173;
-const HMR_PORT = Number(process.env['VGAI_HMR_PORT']) || (PORT === 5173 ? 24678 : PORT + 100);
+// Scaffolded editor ports live in 20000-29999, reserving the parallel
+// 30000-39999 band for their HMR sockets so two generated projects cannot
+// collide merely because their preferred editor ports differ by 100.
+const DEFAULT_HMR_PORT =
+  PORT >= 20_000 && PORT < 30_100 ? PORT + 10_000 : PORT === 5173 ? 24678 : PORT + 100;
+const HMR_PORT = Number(process.env['VGAI_HMR_PORT']) || DEFAULT_HMR_PORT;
 // S3: bind to loopback by default; opt-in to a wider interface via env.
 const HOST = resolveBindHost();
 // Engine root is three levels up from packages/editor/server/
@@ -77,6 +93,25 @@ async function main(): Promise<void> {
   // 1. Create Vite in middleware mode (before editor routes so we can pass the callback)
   const vite = await createViteServer({
     configFile: path.resolve(engineRoot, 'vite.config.ts'),
+    // Per-project dep-optimize cache. The repo-root config's default cacheDir
+    // (`<engineRoot>/node_modules/.vite`) is SHARED by every editor session
+    // launched from this checkout — and the resolved config varies per session
+    // (projectPath-conditional plugins below, env-var aliases), so alternating
+    // `vgai edit <A>` / `vgai edit <B>` / e2e-fixture boots each see "vite
+    // config has changed", re-optimize, and swap the deps dir out from under
+    // every OTHER live editor sharing it. Connected tabs then full-reload
+    // ("optimized dependencies changed"), which drops in-flight control
+    // commands — dogfooded as `vgai play` timing out ("editor connected but
+    // did not respond") whenever another project's editor booted concurrently.
+    // A project-local cache gives each project a stable hash and isolates
+    // concurrent sessions; `.vite-editor` (not `.vite`) so it never collides
+    // with the project's OWN standalone `npm run game` cache, whose config —
+    // and therefore hash — legitimately differs. Projectless boots keep a
+    // shared-but-separate dir under the checkout (nothing per-project to key
+    // on; a project opened later via open-project keeps this boot-time dir).
+    cacheDir: projectPath
+      ? path.join(projectPath, 'node_modules', '.vite-editor')
+      : path.join(engineRoot, 'node_modules', '.vite-editor-no-project'),
     plugins: [
       // Pipe gated `window`/`document` into game code: prepend a lexical shadow
       // to every project `/src/` module so its globals resolve to the editor's
@@ -111,35 +146,30 @@ async function main(): Promise<void> {
                 file: string;
                 server: { ws: { send: (msg: unknown) => void } };
               }) {
-                // Vite's `file` hook argument is ALWAYS forward-slash normalized
-                // (its cross-platform module-id convention), but `projectPath`
-                // comes from `canonicalProjectRoot` -> `realpathSync`, which on
-                // Windows returns a native backslash path. A naive
-                // `file.startsWith(projectPath)` therefore NEVER matches on
-                // Windows ("C:/Users/...".startsWith("C:\\Users\\...") is
-                // false) — the custom `vgai:script-update` event silently never
-                // fires and every project edit falls through to Vite's default
-                // full-module-reload HMR instead. Compare forward-slash forms
-                // on both sides so this works identically on every OS.
-                const projectPathPosix = projectPath!.split(path.sep).join('/');
-                if (file.startsWith(projectPathPosix)) {
-                  // Data assets (docs/DATA-TOOLS-DESIGN.md §2.3) ride Vite's
-                  // STOCK HMR: fall through so the imported JSON module
-                  // updates and the owning handle module's
-                  // `import.meta.hot.accept('./x.data.json', …)` fires in the
-                  // running game (live tuning). Safe from the full-page-reload
-                  // hazard the swallow below exists for: the template's
-                  // handle module self-accepts the dep, and an unimported
-                  // .data.json maps to zero modules (no-op). Scene/asset
-                  // files stay swallowed — the editor owns those via SSE.
-                  if (/\.data\.json$/.test(file)) return;
-                  if (/\.(ts|tsx|js|jsx)$/.test(file)) {
-                    server.ws.send({ type: 'custom', event: 'vgai:script-update', data: { file } });
-                  }
-                  // Swallow all project file changes — the editor handles
-                  // scene/asset updates via its own SSE channel.
-                  return [];
+                const kind = classifyProjectHotUpdate(
+                  file,
+                  projectPath!,
+                  /\.[jt]sx?$/.test(file) ? readFileSync(file, 'utf-8') : '',
+                );
+                if (kind === 'outside') return;
+                // Data handles below src/ ride stock Vite HMR so their owning
+                // module's import.meta.hot.accept callback can live-tune them.
+                if (kind === 'stock-data') return;
+                if (kind === 'react') return;
+                if (kind === 'component') {
+                  server.ws.send({ type: 'custom', event: 'vgai:script-update', data: { file } });
+                }
+                if (kind === 'restart') {
+                  server.ws.send({
+                    type: 'custom',
+                    event: 'vgai:restart-required',
+                    data: { file },
+                  });
                 }
+                // Other project changes (including scripts/, tests/, dist/)
+                // are not runtime modules. Swallow them; scene/asset changes
+                // are delivered through the editor's own SSE channel.
+                return [];
               },
             },
           ]
@@ -162,7 +192,7 @@ async function main(): Promise<void> {
       __VGAI_PROJECT_PATH__: JSON.stringify(projectPath ?? ''),
       // Track N, N2 (docs/REACT-INGEST-LANDING-DESIGN.md D-N2): the absolute
       // repo root, so `ingest/discovery-react.ts` can build the `projectRoot`
-      // an `ingest-react` fixture's `resolveWorldAdapter` call needs (its
+      // an `ingest-react` fixture's `resolveRootAdapter` call needs (its
       // `entry`'s `/@fs/` dynamic import + `loadProjectGameProvider` lookup)
       // WITHOUT a "current project" — these in-tree fixtures live in THIS
       // package's own source tree, not a project a user opens (mirrors
@@ -178,6 +208,8 @@ async function main(): Promise<void> {
   const editorRouter = createEditorServer({
     engineRoot,
     projectPath,
+    watchEngineSource: true,
+    loadProjectModule: (moduleId) => vite.ssrLoadModule(moduleId),
     onProjectOpened(newProjectPath: string) {
       // Dynamically allow Vite to serve /@fs/ paths from the new project directory
       const allowed = vite.config.server.fs.allow;
@@ -189,6 +221,7 @@ async function main(): Promise<void> {
       // And gate its modules with the game-globals prelude (see vgai-game-globals above).
       projectRoots.add(newProjectPath);
       // And point the project-static route (D-X2) at the newly opened project.
+      const previousProjectRoot = currentProjectRoot;
       currentProjectRoot = newProjectPath;
       // Keep the session registry (D12) pointing at the CURRENT project so
       // `vgai edit` reuse/targeting decisions see switches, not boot state.
@@ -198,6 +231,9 @@ async function main(): Promise<void> {
         pid: process.pid,
         startedAt: sessionStartedAt,
       });
+      // #146: the in-project session file follows the switch too.
+      if (previousProjectRoot !== newProjectPath) removeSessionFile(previousProjectRoot);
+      writeSessionFile(newProjectPath);
     },
   });
   app.use(editorRouter);
@@ -220,12 +256,58 @@ async function main(): Promise<void> {
   // even after 45s; scoped polling mounts fine). Instead: a tiny mtime poller
   // over the CURRENT project only, forwarding synthetic add/change/unlink
   // events into Vite's watcher, which runs the normal invalidate+HMR pipeline.
-  if (process.env['VGAI_WATCH_POLL']) {
+  // AUTO-ENABLED when the project sits on a Windows drvfs mount (/mnt/<drive>/
+  // under WSL) — the one environment where inotify is structurally absent. A
+  // silently-stale dev server reads as "my edit didn't work" to agents and
+  // humans alike (dogfooded 2026-07-12: a one-line CSS fix "didn't apply"
+  // through a whole debugging round because the served transform was stale).
+  // VGAI_WATCH_POLL stays the explicit override: `1`/`<ms>` forces polling on
+  // anywhere, `0` disables it even on drvfs.
+  const watchPollEnv = process.env['VGAI_WATCH_POLL'];
+  const projectOnDrvfs = process.platform === 'linux' && /^\/mnt\/[a-z]\//i.test(projectPath ?? '');
+  if (watchPollEnv ? watchPollEnv !== '0' : projectOnDrvfs) {
     startProjectPollWatcher(vite.watcher, () => currentProjectRoot);
   }
 
   // 3. Start Express
   const sessionStartedAt = new Date().toISOString();
+
+  // #146 — `.vgai/session.json` INSIDE the project: session discovery for
+  // agents becomes `cat .vgai/session.json` (local, obvious, and readable by
+  // a sandboxed agent without leaving the project tree) instead of parsing
+  // the global registry at ~/.vgai/editor-sessions.json and matching cwd.
+  // Written at boot and on every project switch, removed on shutdown. Never
+  // fatal — a read-only project dir must not kill the dev server.
+  const writeSessionFile = (project: string | null | undefined): void => {
+    if (!project) return;
+    try {
+      mkdirSync(path.join(project, '.vgai'), { recursive: true });
+      writeFileSync(
+        path.join(project, '.vgai', 'session.json'),
+        `${JSON.stringify(
+          {
+            port: PORT,
+            pid: process.pid,
+            url: `http://${HOST}:${PORT}/`,
+            startedAt: sessionStartedAt,
+          },
+          null,
+          2,
+        )}\n`,
+      );
+    } catch {
+      // best-effort only
+    }
+  };
+  const removeSessionFile = (project: string | null | undefined): void => {
+    if (!project) return;
+    try {
+      unlinkSync(path.join(project, '.vgai', 'session.json'));
+    } catch {
+      // already gone / never written
+    }
+  };
+
   const server = app.listen(PORT, HOST, () => {
     console.log(
       `\n  \x1b[32mEditor server\x1b[0m running at \x1b[36mhttp://${HOST}:${PORT}\x1b[0m`,
@@ -233,9 +315,7 @@ async function main(): Promise<void> {
     if (projectPath) {
       console.log(`  \x1b[33mProject\x1b[0m: ${projectPath}`);
     }
-    console.log(
-      `  \x1b[33mEditor\x1b[0m: \x1b[36mhttp://${HOST}:${PORT}/\x1b[0m\n`,
-    );
+    console.log(`  \x1b[33mEditor\x1b[0m: \x1b[36mhttp://${HOST}:${PORT}/\x1b[0m\n`);
     // D12: announce this session so `vgai edit` can reuse instead of hijack.
     registerSession({
       project: projectPath ?? null,
@@ -243,6 +323,8 @@ async function main(): Promise<void> {
       pid: process.pid,
       startedAt: sessionStartedAt,
     });
+    // #146: and inside the project itself, for `cat .vgai/session.json`.
+    writeSessionFile(projectPath ?? null);
   });
 
   // SC5: friendly message instead of an opaque crash on port conflict.
@@ -251,15 +333,35 @@ async function main(): Promise<void> {
     process.exit(1);
   });
 
-  // Cleanup on shutdown
-  const shutdown = () => {
+  // Cleanup on shutdown. The last-gasp log line exists because a detached
+  // session once vanished with a log that ended mid-banner (target-blaster
+  // friction #5, #146 ledger) — post-mortems had to GUESS between a signal,
+  // a crash, and a silent WSL OOM kill. Signals and normal exits now name
+  // themselves; an abrupt SIGKILL/OOM remains the one case with no line
+  // (nothing can log through a KILL), which the ABSENCE of this line now
+  // positively identifies.
+  const lastGasp = (why: string) => {
+    console.error(`[vgai-editor] shutting down (${why}) — pid ${process.pid}, port ${PORT}`);
+  };
+  let shutdownStarted = false;
+  const shutdown = createProcessShutdown({
+    tasks: [() => closeHttpServer(server), () => editorRouter.close(), () => vite.close()],
+  });
+  const onShutdownSignal = (signal: string) => {
+    if (shutdownStarted) return;
+    shutdownStarted = true;
+    lastGasp(signal);
     unregisterSession(process.pid);
-    vite.close();
-    server.close();
+    removeSessionFile(currentProjectRoot ?? projectPath ?? null);
+    void shutdown(signal);
   };
-  process.once('SIGINT', shutdown);
-  process.once('SIGTERM', shutdown);
-  process.once('exit', () => unregisterSession(process.pid));
+  process.once('SIGINT', () => onShutdownSignal('SIGINT'));
+  process.once('SIGTERM', () => onShutdownSignal('SIGTERM'));
+  process.once('exit', (code) => {
+    if (!shutdownStarted) lastGasp(`exit ${code}`);
+    unregisterSession(process.pid);
+    removeSessionFile(currentProjectRoot ?? projectPath ?? null);
+  });
 }
 
 /**
@@ -341,7 +443,9 @@ function startProjectPollWatcher(
     setTimeout(tick, interval);
   };
   setTimeout(tick, interval);
-  console.log(`  Project poll-watcher on (VGAI_WATCH_POLL, every ${interval}ms)`);
+  console.log(
+    `  Project poll-watcher on (auto on drvfs projects; VGAI_WATCH_POLL=0/1/<ms> overrides; every ${interval}ms)`,
+  );
 }
 
 main().catch((err) => {