@volter/editor-core 0.5.57

package/server/idle-shutdown.ts

@@ -0,0 +1,170 @@
+/**
+ * Idle self-shutdown — the editor dev server's own lifetime bound.
+ *
+ * THE PROBLEM THIS EXISTS FOR. Nothing ties a dev server's lifetime to the
+ * agent session that started it. The session ends, the server does not: it
+ * squats its port, keeps running whatever tab-lifecycle loop it booted with,
+ * and reopens browser tabs for a game nobody is editing. The agent contract
+ * ("close your session when your task ends") is unenforced and was violated
+ * three times in one evening. A bounded self-heal makes an abandoned server
+ * quieter; it does not make it not-abandoned. So the server ends itself.
+ *
+ * OWNERSHIP (the one-place statement).
+ * - OWNER: the server process. Nothing else creates, shares, or observes this
+ *   timer — there is exactly one per process, created at boot by the host
+ *   (`dev.ts` / `packaged.ts`) right after `listen`.
+ * - THE ONE TEARDOWN PATH: `onIdle` hands back to the host's EXISTING shutdown
+ *   function — the same one SIGINT/SIGTERM use (dereg from the session
+ *   registry, remove `.vgai/session.json`, close the blessed tab, close
+ *   HTTP/router/Vite, exit). Idle shutdown adds no second path and no special
+ *   case; it only supplies a different `why` string, so the server's last-gasp
+ *   line names idleness as the cause and a vanished `vgai sessions` entry is
+ *   explainable from the log. (The session registry is a ledger of what IS
+ *   running — a dead entry is pruned, never annotated — so there is
+ *   deliberately no "close reason" recorded there.)
+ * - `stop()` is called by that same path; the interval is `unref()`ed besides,
+ *   so it can never hold an exiting process open.
+ *
+ * WHAT RESETS THE TIMER — existing signals only, no new heartbeat protocol:
+ * 1. A CONNECTED EDITOR CLIENT. `hasConnectedClients` is the live SSE client
+ *    count (`editor-sse.ts`'s `clientCount()`), the same number `vgai status`
+ *    reports as `connected`. It is polled rather than evented, which makes a
+ *    connected tab PERMANENTLY non-idle while it is open: every tick with a
+ *    client present stamps the clock forward, so the window can only start
+ *    running once the last tab is gone.
+ * 2. AN HTTP REQUEST. The hosts call `noteActivity()` from one `app.use`
+ *    ahead of every route, so the control API (`/__editor/command` relay,
+ *    `/__editor/state`, `/__vgai/*` eval + screenshot) and ordinary page/module
+ *    requests all count. Counting every request rather than only `/__editor/*`
+ *    is deliberate and is the SAFE direction of error: a superset of "control
+ *    traffic" can only delay a shutdown, and anything fetching modules from
+ *    this server is something using it.
+ *
+ * Autosave means a shutdown loses nothing, and `vgai edit` brings the session
+ * back in seconds — which is what makes 45 minutes a cheap default rather than
+ * a risky one.
+ */
+
+/** Idle window when `VGAI_IDLE_SHUTDOWN_MINUTES` is unset. */
+export const DEFAULT_IDLE_SHUTDOWN_MINUTES = 45;
+
+export const IDLE_SHUTDOWN_MINUTES_ENV = 'VGAI_IDLE_SHUTDOWN_MINUTES';
+
+/**
+ * The configured idle window in milliseconds; `0` means "never self-shut".
+ *
+ * Fractional minutes are accepted on purpose (`0.05` = 3s) — that is how the
+ * behaviour is verified live without waiting three quarters of an hour, and a
+ * second seconds-only env var would just be a second thing to keep in sync.
+ *
+ * Disabled when:
+ * - `VGAI_IDLE_SHUTDOWN_MINUTES=0` — the explicit opt-out;
+ * - `CI` is set — a CI runner already owns and reaps its child processes, and
+ *   a lane that pauses longer than the window must not lose its server;
+ * - the session is EPHEMERAL (`VGAI_EPHEMERAL_SESSION`, today `vgai doctor`) —
+ *   a probe's whole lifetime belongs to the tool that spawned it.
+ *
+ * `VGAI_NO_OPEN` deliberately does NOT disable it: a headless session is
+ * exactly the kind that gets abandoned. Harnesses that drive their own server
+ * stay alive because driving it is activity (see the header).
+ *
+ * A malformed value falls back to the default rather than disabling — the
+ * failure mode of a typo must not be an immortal server.
+ */
+export function resolveIdleShutdownMs(env: NodeJS.ProcessEnv = process.env): number {
+  if (env['CI']) return 0;
+  const ephemeral = env['VGAI_EPHEMERAL_SESSION'];
+  if (ephemeral !== undefined && ephemeral !== '' && ephemeral !== '0') return 0;
+  const raw = env[IDLE_SHUTDOWN_MINUTES_ENV];
+  if (raw === undefined || raw.trim() === '') return DEFAULT_IDLE_SHUTDOWN_MINUTES * 60_000;
+  const minutes = Number(raw);
+  if (!Number.isFinite(minutes) || minutes < 0) return DEFAULT_IDLE_SHUTDOWN_MINUTES * 60_000;
+  return Math.round(minutes * 60_000);
+}
+
+/** Human-readable window for the shutdown line (`45m`, `90s`, `1.5s`). */
+export function formatIdleWindow(idleMs: number): string {
+  if (idleMs >= 60_000) {
+    const minutes = idleMs / 60_000;
+    return `${Number.isInteger(minutes) ? minutes : minutes.toFixed(2).replace(/\.?0+$/, '')}m`;
+  }
+  const seconds = idleMs / 1000;
+  return `${Number.isInteger(seconds) ? seconds : seconds.toFixed(2).replace(/\.?0+$/, '')}s`;
+}
+
+export interface IdleShutdownOptions {
+  /** Window in ms; `0` disables (the controller then never arms a timer). */
+  readonly idleMs: number;
+  /** Live SSE client count > 0 — see reset source 1 in the header. */
+  readonly hasConnectedClients: () => boolean;
+  /**
+   * The host's existing shutdown function, called ONCE with a `why` string
+   * naming the idle window. Never a second teardown path.
+   */
+  readonly onIdle: (why: string) => void;
+  /** Poll cadence override; defaults to a tenth of the window (1s–30s). */
+  readonly pollMs?: number;
+}
+
+export interface IdleShutdown {
+  /** Stamp "used just now". Wired to one `app.use` in each host. */
+  noteActivity(): void;
+  /** Stop polling. Called from the host's shutdown path. */
+  stop(): void;
+  /** `false` when the window is 0 — nothing was armed. */
+  readonly armed: boolean;
+}
+
+/**
+ * Poll cadence: fine enough that the observed shutdown lands close to the
+ * configured window, coarse enough that a 45-minute window is not a per-second
+ * wakeup. A tenth of the window, clamped to [1s, 30s].
+ */
+function defaultPollMs(idleMs: number): number {
+  return Math.min(30_000, Math.max(1_000, Math.round(idleMs / 10)));
+}
+
+export function createIdleShutdown(options: IdleShutdownOptions): IdleShutdown {
+  const { idleMs, hasConnectedClients, onIdle } = options;
+  if (idleMs <= 0) {
+    return { noteActivity: () => {}, stop: () => {}, armed: false };
+  }
+
+  let lastActivity = Date.now();
+  let fired = false;
+  let timer: ReturnType<typeof setInterval> | null = null;
+
+  const stop = (): void => {
+    if (timer) clearInterval(timer);
+    timer = null;
+  };
+
+  const tick = (): void => {
+    if (fired) return;
+    // A connected tab is not merely activity, it is continuous occupancy: while
+    // one is open the clock can never start running.
+    if (hasConnectedClients()) {
+      lastActivity = Date.now();
+      return;
+    }
+    if (Date.now() - lastActivity < idleMs) return;
+    fired = true;
+    stop();
+    onIdle(
+      `idle ${formatIdleWindow(idleMs)} — no editor tab connected and no request served ` +
+        `(${IDLE_SHUTDOWN_MINUTES_ENV}=0 disables; \`volter-editor edit\` restarts the session)`,
+    );
+  };
+
+  timer = setInterval(tick, options.pollMs ?? defaultPollMs(idleMs));
+  // Bookkeeping must never be the reason a process stays up.
+  timer.unref?.();
+
+  return {
+    noteActivity: () => {
+      if (!fired) lastActivity = Date.now();
+    },
+    stop,
+    armed: true,
+  };
+}

package/server/js-profiling-policy.ts

@@ -0,0 +1,52 @@
+/**
+ * `Document-Policy: js-profiling` — the permission the editor's own diagnostics
+ * assume it already has.
+ *
+ * The `visible-tab-fps-floor` invariant tells the reader, by name, to "find the
+ * cost with the Profiler's Overview (long-animation-frame attribution)"
+ * (`coverage/ontology-invariants.ts`). But `new Profiler(...)` in the editor
+ * page throws `NotAllowedError: JS profiling is disabled by Document Policy`:
+ * the JS Self-Profiling API is gated on a policy the DOCUMENT's own response
+ * has to grant, and no editor server was sending it. The product printed an
+ * instruction its own page forbade.
+ *
+ * A document policy is granted by the response that created the document, so
+ * this is a response header or it is nothing — there is no client-side way to
+ * turn it on. It is set on EVERY response rather than on a sniffed subset:
+ * the header is meaningless on a subresource (browsers read it only when
+ * creating a document), the editor serves its index through three different
+ * paths (`express.static`, the SPA `sendFile` fallback, and Vite's own HTML
+ * middleware in dev), and a heuristic that tried to name "the document one"
+ * would silently miss whichever path a future change routed through. Blanket
+ * is the version that cannot be quietly wrong.
+ *
+ * It also reaches the game's own frame this way, which is the point: a game
+ * mounted in a child document is exactly what the reader is profiling.
+ */
+
+/** The header name and value, together, so a test names them once. */
+export const JS_PROFILING_POLICY_HEADER = 'Document-Policy';
+export const JS_PROFILING_POLICY_VALUE = 'js-profiling';
+
+interface HeaderSink {
+  setHeader(name: string, value: string): unknown;
+}
+
+/**
+ * Express middleware granting {@link JS_PROFILING_POLICY_VALUE} to every
+ * document this server creates.
+ *
+ * Typed against the narrowest shape it uses (`setHeader`) so the unit test can
+ * drive it without an HTTP server, and so both editor hosts can mount it
+ * without agreeing on an express version.
+ */
+export function jsProfilingPolicy(): (
+  request: unknown,
+  response: HeaderSink,
+  next: () => void,
+) => void {
+  return (_request, response, next) => {
+    response.setHeader(JS_PROFILING_POLICY_HEADER, JS_PROFILING_POLICY_VALUE);
+    next();
+  };
+}

package/server/launcher-settings.ts

@@ -0,0 +1,84 @@
+/**
+ * Launcher settings — the small set of preferences that belong to the PERSON,
+ * not to any one project, and therefore cannot live in a project's
+ * `vgai.project.json` (unit G5).
+ *
+ * Today that is exactly one preference: "Reopen last project on launch". It is
+ * stored next to the recents list in `~/.vgai/`, because the two are the same
+ * kind of state — launcher memory, machine-local, survives every project — and
+ * splitting them across two homes would be arbitrary.
+ *
+ * Deliberately NOT a general settings system. Fields land here only when a
+ * preference is genuinely user-global; anything project-scoped belongs in the
+ * manifest or the workspace layout that already persists per project. Unknown
+ * keys in the file are preserved on write so a newer editor's settings survive
+ * a round-trip through an older one.
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export interface LauncherSettings {
+  /** UE's "Always load last project on startup". Default OFF — see
+   *  `boot-routing.ts` for why the front door is not silently skipped. */
+  reopenLastProject: boolean;
+}
+
+export const DEFAULT_LAUNCHER_SETTINGS: LauncherSettings = {
+  reopenLastProject: false,
+};
+
+export const LAUNCHER_SETTINGS_PATH = join(homedir(), '.vgai', 'launcher.json');
+
+/**
+ * Project a raw parsed file onto the settings shape.
+ *
+ * Anti-shim: a malformed or missing field falls back to its DOCUMENTED default
+ * rather than being invented or guessed from neighbouring state. A corrupt file
+ * therefore degrades to "the defaults", never to a half-applied mix — and
+ * never throws, because a launcher that refuses to boot over a bad preferences
+ * file is a worse failure than one that boots with defaults.
+ */
+export function projectLauncherSettings(raw: unknown): LauncherSettings {
+  if (typeof raw !== 'object' || raw === null) return { ...DEFAULT_LAUNCHER_SETTINGS };
+  const record = raw as Record<string, unknown>;
+  return {
+    reopenLastProject:
+      typeof record['reopenLastProject'] === 'boolean'
+        ? record['reopenLastProject']
+        : DEFAULT_LAUNCHER_SETTINGS.reopenLastProject,
+  };
+}
+
+export async function loadLauncherSettings(
+  path = LAUNCHER_SETTINGS_PATH,
+): Promise<LauncherSettings> {
+  try {
+    return projectLauncherSettings(JSON.parse(await readFile(path, 'utf-8')));
+  } catch {
+    return { ...DEFAULT_LAUNCHER_SETTINGS };
+  }
+}
+
+/**
+ * Merge a partial update over what is on disk and write it back, preserving any
+ * keys this build does not know about (forward compatibility — an older editor
+ * must not silently drop a newer one's preference).
+ */
+export async function saveLauncherSettings(
+  update: Partial<LauncherSettings>,
+  path = LAUNCHER_SETTINGS_PATH,
+): Promise<LauncherSettings> {
+  let existing: Record<string, unknown> = {};
+  try {
+    const parsed: unknown = JSON.parse(await readFile(path, 'utf-8'));
+    if (typeof parsed === 'object' && parsed !== null) existing = parsed as Record<string, unknown>;
+  } catch {
+    // No file yet, or unreadable — the merge base is simply empty.
+  }
+  const merged = { ...existing, ...update };
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(merged, null, 2)}\n`, 'utf-8');
+  return projectLauncherSettings(merged);
+}