@volter/editor-core 0.5.57

package/server/session-product.ts

@@ -0,0 +1,112 @@
+/**
+ * WHICH PRODUCT THIS SESSION IS SERVING — the session's half of the resolution
+ * the CLI already did.
+ *
+ * `vgai edit` resolves the product from the project's own dependencies
+ * (`@volter/editor-sdk/session/product-locator`) so a bad or missing declaration
+ * is named before a server exists, then hands the directory over in
+ * `VGAI_PRODUCT_DIR`, beside `VGAI_WORKBENCH_DIR`. The session reads it back
+ * for the two things only it can do: SERVE the product's entry through
+ * `/__editor/served-modules`, and REPORT it (`EditorState.product`, printed by
+ * `vgai status` on the workbench's line) — a process reports what it is running.
+ *
+ * A session started without the variable resolves from the project itself
+ * rather than guessing, so `npx tsx packages/editor/server/dev.ts` by hand
+ * behaves the same as a CLI launch and fails with the same sentence.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import {
+  productComposedPackages as composedPackages,
+  type ProductIdentity,
+  readProductManifest,
+  resolveProductForProject,
+} from '@volter/editor-sdk/session/product-locator';
+
+/** The product directory the CLI resolved and handed over. */
+export const PRODUCT_DIR_ENV = 'VGAI_PRODUCT_DIR';
+
+/**
+ * The product this session serves, or `null` when there is none to find — a
+ * session with no project open yet, or one whose project declares none. The
+ * served-modules door turns that `null` into its own refusal, naming the
+ * install line, rather than serving nothing silently.
+ */
+export function sessionProduct(projectPath: string | null): ProductIdentity | null {
+  const handed = process.env[PRODUCT_DIR_ENV];
+  if (handed !== undefined && handed !== '' && existsSync(handed)) {
+    const product = readProductManifest(handed);
+    if (product !== null) return product;
+  }
+  if (projectPath === null) return null;
+  try {
+    return resolveProductForProject(projectPath);
+  } catch {
+    // The refusal belongs to the door that was asked, not to this read: the CLI
+    // already prints it at launch, and `served-modules` prints it to the frame.
+    return null;
+  }
+}
+
+/** `resolveProductForProject` — the same resolution, refusal and all, for the
+ *  door that must say why. `productComposedPackages` — what that product
+ *  mounts, read through the manifest mirror the estate gate keeps equal to the
+ *  composition in its entry. */
+export {
+  productComposedPackages,
+  resolveProductForProject,
+} from '@volter/editor-sdk/session/product-locator';
+
+/**
+ * EVERY CONTRIBUTION MODULE THE PRODUCT COMPOSES, as absolute files — what
+ * Vite's dependency crawl has to be HANDED, because it cannot walk to them.
+ *
+ * The product names a package as `vgai:contributions/<name>`, and that module
+ * is synthesized (`vite-plugin-product-contributions.ts`): it hangs off no file
+ * on disk, so `optimizeDeps`' esbuild scanner never reaches the `import()` rows
+ * inside it. `vite-plugin-module-doorways.ts`'s header records the same failure
+ * class from the other synthesized module and the same cure — read the entries
+ * out of the SAME declaration the browser is served, rather than letting the
+ * optimizer discover them when a lane first mounts.
+ *
+ * MEASURED 2026-09-21 on a `--template game` scaffold, before this existed: the
+ * boot pass prebundled the kit's own graph, the game editor's five packages
+ * then dragged in `storybook/internal/preview-api`, `storybook/internal/csf`,
+ * `@gltf-transform/{core,extensions,functions}` and `axe-core` as their
+ * contributions loaded, and Vite answered with `optimized dependencies changed.
+ * reloading` — a hard reload of the one tab, mid-boot, which drops the
+ * session's editor and every command with it.
+ */
+export function productContributionFiles(product: ProductIdentity): string[] {
+  const resolveFrom = createRequire(pathToFileURL(join(product.dir, 'package.json')));
+  const files: string[] = [];
+  for (const name of composedPackages(product)) {
+    let manifestPath: string;
+    try {
+      manifestPath = resolveFrom.resolve(`${name}/package.json`);
+    } catch {
+      continue;
+    }
+    let declared: unknown;
+    try {
+      declared = (JSON.parse(readFileSync(manifestPath, 'utf8')) as ContributingManifest).vgai
+        ?.contributions;
+    } catch {
+      continue;
+    }
+    if (!Array.isArray(declared)) continue;
+    const dir = dirname(manifestPath);
+    for (const entry of declared) {
+      if (typeof entry !== 'string') continue;
+      const file = join(dir, entry);
+      if (existsSync(file)) files.push(file);
+    }
+  }
+  return files;
+}
+
+interface ContributingManifest {
+  vgai?: { contributions?: unknown };
+}

package/server/session-registry.ts

@@ -0,0 +1,230 @@
+/**
+ * Editor session registry — the file-backed ledger of live editor dev servers.
+ * This module is the WRITER (dev.ts registers on listen, re-registers on
+ * project switch, unregisters on shutdown). The FORMAT — entry shape, guards,
+ * path, liveness-filtered read — lives once in `@vgai/sdk`'s
+ * `session-registry-format`, imported by every reader (this file, the CLI,
+ * and both SDK transports) instead of copied.
+ *
+ * Entries are best-effort — every reader must PID-liveness-filter (a crashed
+ * server can't unregister itself), and writers sweep dead entries on write.
+ */
+
+import {
+  EDITOR_SESSIONS_REGISTRY_FILE,
+  type EditorSessionEntry as EditorSession,
+  isEditorSessionEntry,
+  normalizeEditorSessionEntry,
+  pidAlive,
+} from '@volter/editor-sdk/session/registry-format';
+
+export type { EditorSessionEntry as EditorSession } from '@volter/editor-sdk/session/registry-format';
+export { pidAlive } from '@volter/editor-sdk/session/registry-format';
+
+import { randomBytes, randomUUID } from 'node:crypto';
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { resolveWorktreeIdentity, type WorktreeIdentity } from './worktree-identity';
+
+export type EditorSessionAnnouncement = Pick<
+  EditorSession,
+  'project' | 'port' | 'pid' | 'startedAt'
+>;
+
+const PROCESS_SESSION_ID = randomUUID();
+const PROCESS_CONTROL_SECRET = randomBytes(32).toString('base64url');
+
+export function processSessionId(): string {
+  return PROCESS_SESSION_ID;
+}
+
+export function processControlSecret(): string {
+  return PROCESS_CONTROL_SECRET;
+}
+
+export function sessionIdentity(project: string | null): WorktreeIdentity | null {
+  return project === null ? null : resolveWorktreeIdentity(project);
+}
+
+export function materializeSession(
+  announcement: EditorSessionAnnouncement,
+  id: string = PROCESS_SESSION_ID,
+): EditorSession {
+  const identity = sessionIdentity(announcement.project);
+  return {
+    ...announcement,
+    sessionId: id,
+    controlSecret: PROCESS_CONTROL_SECRET,
+    repositoryId: identity?.repositoryId ?? null,
+    worktreeId: identity?.worktreeId ?? null,
+    worktreeRoot: identity?.worktreeRoot ?? null,
+    projectRelativePath: identity?.projectRelativePath ?? null,
+    branch: identity?.branch ?? null,
+    headCommit: identity?.headCommit ?? null,
+    baseCommit: identity?.baseCommit ?? null,
+  };
+}
+
+const REGISTRY_DIR = join(homedir(), '.vgai');
+const REGISTRY_FILE = EDITOR_SESSIONS_REGISTRY_FILE;
+
+export function sessionRegistryPath(): string {
+  return REGISTRY_FILE;
+}
+
+/**
+ * Is this dev server an EPHEMERAL PROBE rather than a session anyone owns?
+ *
+ * `vgai doctor` spawns a real dev server on the target folder for a few
+ * seconds and drives it with its own headless browser. It is not an editing
+ * session: nobody should be able to reuse it, `vgai close` should not list
+ * it, and — the defect this exists for (SimCity ingest dogfood, S-6) — it
+ * must not touch the project's `.vgai/session.json`, which belongs to
+ * whichever `vgai edit` session is actually serving that folder. The probe
+ * used to OVERWRITE that file at boot with its own throwaway port/pid and
+ * then DELETE it on exit, so a live session the user was watching became
+ * undiscoverable (`cat .vgai/session.json` → ENOENT) because they ran a
+ * read-only diagnostic against it.
+ *
+ * Same shape as `VGAI_NO_OPEN`: an env flag the spawning tool sets on the
+ * child, never a mode the server infers. `'0'` explicitly opts back in, so
+ * the variable can be cleared by value in an inherited environment.
+ */
+export function isEphemeralSession(env: NodeJS.ProcessEnv = process.env): boolean {
+  const value = env['VGAI_EPHEMERAL_SESSION'];
+  return value !== undefined && value !== '' && value !== '0';
+}
+
+/**
+ * Does this dev server contribute to the PERSON's launcher memory
+ * (`~/.vgai/recent-projects.json`, read by the Projects hub and by the
+ * opt-in "Reopen last project on launch")?
+ *
+ * Recents is machine-local state that belongs to a
+ * HUMAN at a launcher — it is what the hub shows first and what reopen-last
+ * reaches for. Two kinds of dev server have no such human by construction and
+ * must therefore stay out of it:
+ *
+ * - an EPHEMERAL PROBE (`isEphemeralSession`, today `vgai doctor`), which is
+ *   not an editing session at all; and
+ * - a HEADLESS session (`VGAI_NO_OPEN` — the CLI's `--no-open`), which
+ *   maintains no browser tab whatsoever: CI, headless harnesses, and every
+ *   background-agent session. Measured: an agent's transient session wrote
+ *   its scratchpad project into the owner's Recents, and the owner's next
+ *   launcher boot reached for it.
+ *
+ * The read is the same truthiness `dev.ts`/`packaged.ts` already use for
+ * `tabBijection.enabled`, so "this session maintains a tab" and "this session
+ * is someone's launcher memory" can never disagree.
+ */
+export function writesRecentProjects(env: NodeJS.ProcessEnv = process.env): boolean {
+  if (isEphemeralSession(env)) return false;
+  return !env['VGAI_NO_OPEN'];
+}
+
+/** All recorded sessions, unvalidated beyond shape (callers liveness-filter). */
+export function readSessions(): EditorSession[] {
+  try {
+    const raw: unknown = JSON.parse(readFileSync(REGISTRY_FILE, 'utf8'));
+    return Array.isArray(raw)
+      ? raw.filter(isEditorSessionEntry).map(normalizeEditorSessionEntry)
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Sessions whose server process is still alive. */
+export function liveSessions(): EditorSession[] {
+  return readSessions().filter((s) => pidAlive(s.pid));
+}
+
+/**
+ * Atomic registry replace: write a private temp file, then rename() it over
+ * the registry. rename(2) is atomic on POSIX (and effectively so on NTFS), so
+ * a concurrent reader always parses either the complete old array or the
+ * complete new one — never a torn/truncated file. Torn reads are not
+ * hypothetical: `readSessions()` maps ANY parse failure to `[]`, so a
+ * reader-that-then-writes (register/unregister — which now runs on every
+ * dev-server source-change restart) that catches another writer mid-truncate
+ * would persist that empty view and silently wipe every other live session's
+ * entry. Reproduced live 2026-07-25: two concurrent restart-churn processes
+ * emptied a registry seeded with three entries whose PIDs were still alive —
+ * the wiped sessions kept running but became invisible to `vgai
+ * edit`/`sessions`/`close`, which is the "new editors starting over and over
+ * while strays accumulate" failure mode.
+ */
+function replaceRegistry(sessions: EditorSession[]): void {
+  const tmp = `${REGISTRY_FILE}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(sessions, null, 2)}\n`, { mode: 0o600 });
+  renameSync(tmp, REGISTRY_FILE);
+  // Owner-only is the intent; a filesystem without modes (a browser runtime)
+  // keeps the file and skips the bit.
+  try {
+    chmodSync(REGISTRY_FILE, 0o600);
+  } catch {
+    /* no modes here */
+  }
+}
+
+/**
+ * A registry record whose pid is not alive is HISTORY, not identity.
+ *
+ * A dead record must
+ * never contribute a project — or anything else — to the port it used to
+ * hold, and no live server may inherit one. The registry is a ledger of what
+ * IS running, so every write prunes what is not; a reader that forgets to
+ * liveness-filter can then only ever see stale entries this process has not
+ * swept yet, never entries the registry deliberately kept.
+ *
+ * `isAlive` is injectable so the rule is testable against fabricated pids
+ * without spawning (or killing) real processes.
+ */
+export function pruneDeadSessions(
+  sessions: readonly EditorSession[],
+  isAlive: (pid: number) => boolean = pidAlive,
+): EditorSession[] {
+  return sessions.filter((s) => isAlive(s.pid));
+}
+
+/**
+ * The registry as it must look once `incoming` has taken its port: every dead
+ * record gone, the previous claim on this pid or this port replaced, and
+ * `incoming` appended. Pure, for the same reason as `pruneDeadSessions`.
+ */
+export function registryAfterRegistration(
+  sessions: readonly EditorSession[],
+  incoming: EditorSession,
+  isAlive: (pid: number) => boolean = pidAlive,
+): EditorSession[] {
+  const rest = pruneDeadSessions(sessions, isAlive).filter(
+    (s) => s.pid !== incoming.pid && s.port !== incoming.port,
+  );
+  return [...rest, incoming];
+}
+
+/**
+ * Record (or refresh) this process's session. Sweeps dead entries and any
+ * stale claim on the same port while it's here.
+ */
+export function registerSession(announcement: EditorSessionAnnouncement): void {
+  try {
+    mkdirSync(REGISTRY_DIR, { recursive: true });
+    replaceRegistry(registryAfterRegistration(readSessions(), materializeSession(announcement)));
+  } catch {
+    // Registry is best-effort — never let bookkeeping kill the server.
+  }
+}
+
+export function unregisterSession(pid: number): void {
+  try {
+    // Same rule on the way out: this process's record goes, and so does every
+    // record whose server is already gone. Leaving those behind is what lets a
+    // dead entry outlive the server it described and keep answering "which
+    // project is on port N?" long after nothing is.
+    replaceRegistry(pruneDeadSessions(readSessions().filter((s) => s.pid !== pid)));
+  } catch {
+    // Best-effort (see registerSession).
+  }
+}

package/server/share-claims.ts

@@ -0,0 +1,138 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+export interface ShareGatewayClaims {
+  participantId: string;
+  invitationId: string;
+  credentialId: string;
+  role: 'viewer' | 'commenter' | 'tester' | 'editor' | 'terminal';
+  account: { id: string; email: string; name?: string };
+}
+
+const CLAIM_HEADERS = [
+  'x-vgai-share-participant-id',
+  'x-vgai-share-invitation-id',
+  'x-vgai-share-credential-id',
+  'x-vgai-share-role',
+  'x-vgai-share-account-id',
+  'x-vgai-share-account-email',
+  'x-vgai-share-account-name',
+  'x-vgai-share-signed-at',
+  'x-vgai-share-signature',
+] as const;
+
+export const shareClaimHeaders: readonly string[] = CLAIM_HEADERS;
+
+function payload(
+  method: string,
+  url: string,
+  claims: ShareGatewayClaims,
+  signedAt: string,
+): string {
+  return [
+    method.toUpperCase(),
+    url,
+    claims.participantId,
+    claims.invitationId,
+    claims.credentialId,
+    claims.role,
+    claims.account.id,
+    claims.account.email,
+    claims.account.name ?? '',
+    signedAt,
+  ].join('\n');
+}
+
+function signature(secret: string, content: string): string {
+  return createHmac('sha256', secret).update(content).digest('base64url');
+}
+
+export function signedShareClaimHeaders(
+  secret: string,
+  method: string,
+  url: string,
+  claims: ShareGatewayClaims,
+  now: number = Date.now(),
+): Record<string, string> {
+  const signedAt = String(now);
+  return {
+    'x-vgai-share-participant-id': claims.participantId,
+    'x-vgai-share-invitation-id': claims.invitationId,
+    'x-vgai-share-credential-id': claims.credentialId,
+    'x-vgai-share-role': claims.role,
+    'x-vgai-share-account-id': claims.account.id,
+    'x-vgai-share-account-email': claims.account.email,
+    ...(claims.account.name
+      ? { 'x-vgai-share-account-name': encodeURIComponent(claims.account.name) }
+      : {}),
+    'x-vgai-share-signed-at': signedAt,
+    'x-vgai-share-signature': signature(secret, payload(method, url, claims, signedAt)),
+  };
+}
+
+export function verifyShareClaimHeaders(
+  secret: string,
+  method: string,
+  url: string,
+  read: (name: string) => string | undefined,
+  now: number = Date.now(),
+): ShareGatewayClaims | null {
+  const values = Object.fromEntries(CLAIM_HEADERS.map((name) => [name, read(name)?.trim()]));
+  const any = CLAIM_HEADERS.some((name) => values[name]);
+  if (!any) return null;
+  const participantId = values['x-vgai-share-participant-id'];
+  const invitationId = values['x-vgai-share-invitation-id'];
+  const credentialId = values['x-vgai-share-credential-id'];
+  const role = values['x-vgai-share-role'];
+  const accountId = values['x-vgai-share-account-id'];
+  const accountEmail = values['x-vgai-share-account-email'];
+  const encodedName = values['x-vgai-share-account-name'];
+  const signedAt = values['x-vgai-share-signed-at'];
+  const supplied = values['x-vgai-share-signature'];
+  if (
+    !participantId ||
+    participantId.length > 200 ||
+    !invitationId ||
+    invitationId.length > 200 ||
+    !credentialId ||
+    credentialId.length > 200 ||
+    !role ||
+    !['viewer', 'commenter', 'tester', 'editor', 'terminal'].includes(role) ||
+    !accountId ||
+    accountId.length > 200 ||
+    !accountEmail ||
+    accountEmail.length > 320 ||
+    !signedAt ||
+    !supplied
+  )
+    throw new Error('Invalid share gateway claims.');
+  const signedAtMs = Number(signedAt);
+  if (!Number.isSafeInteger(signedAtMs) || Math.abs(now - signedAtMs) > 30_000) {
+    throw new Error('Expired share gateway claims.');
+  }
+  let name: string | undefined;
+  if (encodedName) {
+    try {
+      name = decodeURIComponent(encodedName);
+    } catch {
+      throw new Error('Invalid share gateway claims.');
+    }
+    if (name.length > 200) throw new Error('Invalid share gateway claims.');
+  }
+  const claims: ShareGatewayClaims = {
+    participantId,
+    invitationId,
+    credentialId,
+    role: role as ShareGatewayClaims['role'],
+    account: { id: accountId, email: accountEmail, ...(name ? { name } : {}) },
+  };
+  const expected = signature(secret, payload(method, url, claims, signedAt));
+  const actualBuffer = Buffer.from(supplied);
+  const expectedBuffer = Buffer.from(expected);
+  if (
+    actualBuffer.length !== expectedBuffer.length ||
+    !timingSafeEqual(actualBuffer, expectedBuffer)
+  ) {
+    throw new Error('Invalid share gateway signature.');
+  }
+  return claims;
+}