@volter/editor-core 0.5.57

package/server/routes/logs.ts

@@ -0,0 +1,272 @@
+/**
+ * `/__editor/log-session`, `/__editor/log-entries`, `/__editor/server-log` —
+ * play-mode console log persistence: the per-run JSONL file under the
+ * project's `logs/`, the reader behind the Console panel, and the server-side
+ * `console.*` sink a page can post into.
+ *
+ * The log-session route is also where the build-discipline tripwires get their
+ * SECOND firing moment: the save event alone goes quiet exactly during
+ * end-of-build verification, which is when an uncommitted batch is oldest.
+ */
+
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import type { NextFunction, Request, Response } from 'express';
+import { asPlayLogHeader, playLogHeaderLine } from '../support/play/log-format';
+import { type EditorServerRouter, playLogFilename, playRunSlug } from '../editor-server';
+import { broadcast } from '../editor-sse';
+import { pruneGameplaySessionLogs } from '../gameplay-session-retention';
+import {
+  gameplaySessionRecordingPath,
+  getGameplaySession,
+  listGameplaySessionCatalog,
+} from '../gameplay-sessions';
+import { processSessionId } from '../session-registry';
+import type { RouteContext } from './context';
+
+export function registerLogRoutes(router: EditorServerRouter, ctx: RouteContext): void {
+  const { announceBuildDisciplineTripwires, journalEvent } = ctx;
+
+  // ---- Play-mode console log persistence ----
+  let logSessionSequence = 0;
+  let activeLogStartedAt: number | null = null;
+  let recentlyEndedLog: { file: string; startedAt: number; endedAt: number } | null = null;
+
+  // Play start/stop is the SECOND event the build-discipline tripwires ride
+  // (`announceBuildDisciplineTripwires`, above). The save event alone covers
+  // the authoring stretch and goes quiet exactly where the measured failure
+  // lives: the end-of-build verification phase is play, playtest and eval —
+  // minutes of activity with no file written, which is also the stretch where
+  // an uncommitted batch is at its oldest. Same guarded call, so the read cap
+  // and the announce gate are unchanged; this only adds a moment at which
+  // they can fire.
+  router.post('/__editor/log-session', async (req: Request, res: Response) => {
+    const body = req.body as { action: 'start' | 'end'; name?: string | null };
+
+    if (body.action === 'start') {
+      const logsDir = join(ctx.projectRoot, 'logs');
+      await mkdir(logsDir, { recursive: true });
+
+      // Lexicographic order remains chronological for pruning/tail tooling —
+      // see `playLogFilename` for why an optional run name goes on the END.
+      const slug = playRunSlug(body.name);
+      const startedAt = new Date();
+      const filename = playLogFilename(startedAt, ++logSessionSequence, slug);
+      ctx.activeLogFile = join(logsDir, filename);
+      activeLogStartedAt = startedAt.getTime();
+      // The run's IDENTITY, recorded ONCE (see `play/log-format.ts`): who wrote
+      // this file, for which project, under which run name, when. These four
+      // facts are fixed for the file's whole lifetime, so they are a header
+      // line and not a per-entry stamp — what varies per entry (tick/simT,
+      // simSpeed, world) is stamped by the entry writer instead.
+      await writeFile(
+        ctx.activeLogFile,
+        playLogHeaderLine({
+          session: processSessionId(),
+          project: ctx.projectRoot,
+          run: slug,
+          startedAt: startedAt.getTime(),
+        }),
+        'utf-8',
+      );
+      await pruneGameplaySessionLogs(ctx.projectRoot);
+      journalEvent({ kind: 'play', action: 'start', name: slug, logFile: filename });
+      announceBuildDisciplineTripwires();
+      res.json({ ok: true, file: filename });
+    } else {
+      const ended = ctx.activeLogFile;
+      if (ended !== null) {
+        const endedAt = Date.now();
+        await appendFile(
+          ended,
+          `${JSON.stringify({
+            t: endedAt,
+            level: 'info',
+            source: 'gameplay-session',
+            msg: 'ended',
+            meta: { endedAt },
+          })}\n`,
+          'utf-8',
+        ).catch(() => undefined);
+        if (activeLogStartedAt !== null) {
+          recentlyEndedLog = { file: ended, startedAt: activeLogStartedAt, endedAt };
+        }
+      }
+      ctx.activeLogFile = null;
+      activeLogStartedAt = null;
+      journalEvent({
+        kind: 'play',
+        action: 'stop',
+        name: null,
+        logFile: ended === null ? null : basename(ended),
+      });
+      announceBuildDisciplineTripwires();
+      res.json({ ok: true });
+    }
+  });
+
+  router.get('/__editor/gameplay-sessions', async (_req: Request, res: Response) => {
+    res.json({ sessions: await listGameplaySessionCatalog(ctx.projectRoot, ctx.activeLogFile) });
+  });
+
+  router.get(
+    '/__editor/gameplay-sessions/:id/recording',
+    async (req: Request, res: Response, next: NextFunction) => {
+      const session = await getGameplaySession(
+        ctx.projectRoot,
+        Array.isArray(req.params['id']) ? (req.params['id'][0] ?? '') : (req.params['id'] ?? ''),
+        ctx.activeLogFile,
+      );
+      const path = session ? gameplaySessionRecordingPath(ctx.projectRoot, session) : null;
+      if (!path) {
+        res.status(404).json({ error: 'This Gameplay Session has no recording.' });
+        return;
+      }
+      res.sendFile(path, { dotfiles: 'allow' }, (error) => {
+        if (!error) return;
+        if (!res.headersSent) res.status(404).json({ error: 'Recording file not found.' });
+        else next(error);
+      });
+    },
+  );
+
+  router.get('/__editor/gameplay-sessions/:id', async (req: Request, res: Response) => {
+    const session = await getGameplaySession(
+      ctx.projectRoot,
+      Array.isArray(req.params['id']) ? (req.params['id'][0] ?? '') : (req.params['id'] ?? ''),
+      ctx.activeLogFile,
+    );
+    if (!session) {
+      res.status(404).json({ error: 'Gameplay Session not found.' });
+      return;
+    }
+    res.json({ session });
+  });
+
+  // `entries` is ENTRIES ONLY — the file's first line is the run's identity
+  // header (`play/log-format.ts`), and a reader counting or rendering log
+  // lines must never see it as one. It is reported beside them instead, so a
+  // follower learns which session/project/run it is tailing without a second
+  // request.
+  router.get('/__editor/log-entries', async (_req: Request, res: Response) => {
+    if (!ctx.activeLogFile) {
+      res.json({ entries: [], header: null });
+      return;
+    }
+    // The whole read used to sit in one try/catch whose catch answered the
+    // EMPTY NO-LOG SHAPE — the same bytes as "no session is running". So a log
+    // being APPENDED TO while this route read it (the normal case: the writer
+    // is a live play session, and a read landing mid-append sees a torn last
+    // line) reported the entire run as having produced nothing. A follower
+    // cannot tell that from a quiet session, so it stops asking.
+    let raw: string;
+    try {
+      raw = await readFile(ctx.activeLogFile, 'utf-8');
+    } catch (error) {
+      res.json({
+        entries: [],
+        header: null,
+        file: basename(ctx.activeLogFile),
+        unreadable: error instanceof Error ? error.message : String(error),
+      });
+      return;
+    }
+    const lines = raw.split('\n').filter(Boolean);
+    const records: unknown[] = [];
+    let truncatedTail = false;
+    let unparsableLines = 0;
+    for (const [index, line] of lines.entries()) {
+      try {
+        records.push(JSON.parse(line) as unknown);
+      } catch {
+        // The writer appends WHOLE lines, so the last one is the only one a
+        // concurrent read can catch half-written — that is a torn tail, and
+        // every line before it is real data. An unparsable line anywhere else
+        // is corruption, counted separately; neither discards what did parse.
+        if (index === lines.length - 1) truncatedTail = true;
+        else unparsableLines += 1;
+      }
+    }
+    const header = records.length > 0 ? asPlayLogHeader(records[0]) : null;
+    const entries = header === null ? records : records.slice(1);
+    res.json({
+      entries,
+      header,
+      file: basename(ctx.activeLogFile),
+      ...(truncatedTail ? { truncatedTail: true } : {}),
+      ...(unparsableLines > 0 ? { unparsableLines } : {}),
+    });
+  });
+
+  router.post('/__editor/log-entries', async (req: Request, res: Response) => {
+    const body = req.body as
+      | {
+          entries: Array<{
+            t: number;
+            level: string;
+            source?: string;
+            sub?: string;
+            msg: string;
+            meta?: Record<string, unknown>;
+          }>;
+        }
+      | null
+      | undefined;
+    if (!body || !Array.isArray(body.entries) || body.entries.length === 0) {
+      res.status(400).json({ error: 'Expected a non-empty entries array.' });
+      return;
+    }
+    const batches = new Map<string, typeof body.entries>();
+    for (const entry of body.entries) {
+      const target =
+        recentlyEndedLog &&
+        Number.isFinite(entry.t) &&
+        entry.t >= recentlyEndedLog.startedAt &&
+        entry.t <= recentlyEndedLog.endedAt
+          ? recentlyEndedLog.file
+          : ctx.activeLogFile;
+      if (!target) {
+        res.status(409).json({ error: 'No matching Gameplay Session for these entries.' });
+        return;
+      }
+      const batch = batches.get(target) ?? [];
+      batch.push(entry);
+      batches.set(target, batch);
+    }
+    await Promise.all(
+      [...batches].map(([target, entries]) =>
+        appendFile(
+          target,
+          `${entries.map((entry) => JSON.stringify(entry)).join('\n')}\n`,
+          'utf-8',
+        ),
+      ),
+    );
+    res.json({ ok: true });
+  });
+
+  // ---- External-tool narration relay ----
+  // A tool driving this session (a `@vgai/live` client, say) fires
+  // best-effort lifecycle lines at this route so they land in the
+  // SAME live editor console the `server-log` SSE event feeds
+  // (see `runFileValidation`'s `broadcast('server-log', …)` calls above) — a
+  // human watching the editor sees the script's progress without tailing a
+  // separate terminal. Deliberately dumb: this is a narration RELAY, not an
+  // API — it validates shape, broadcasts, and gets out of the way; no state is
+  // kept here, and a caller with nothing to say just never POSTs.
+  router.post('/__editor/server-log', (req: Request, res: Response) => {
+    const body = req.body as { level?: unknown; message?: unknown };
+    const level = body.level;
+    if (
+      (level !== 'info' && level !== 'warn' && level !== 'error') ||
+      typeof body.message !== 'string'
+    ) {
+      res
+        .status(400)
+        .json({ error: "Expected { level: 'info'|'warn'|'error', message: string }." });
+      return;
+    }
+    broadcast('server-log', { level, message: body.message });
+    res.status(204).end();
+  });
+}

package/server/routes/project-identity.ts

@@ -0,0 +1,302 @@
+/**
+ * WHAT PROJECT IS THIS, and what does the editor know about it:
+ * `/__editor/compatibility`, `/__editor/project`, `/__editor/project-verbs`,
+ * `/__editor/project-attribution`, and the three `/__editor/manifest` verbs.
+ *
+ * `/__editor/project` is BOOT ROUTING — every caller of it is on the critical
+ * path — which is why `/__editor/project-verbs` is a separate route despite
+ * reading the same two files: it is a periodic vitals read, and its failures
+ * must never be able to make a session look projectless.
+ *
+ * The manifest write is the one route in the whole server that HARD-CODES its
+ * destination rather than deriving it from the request. `validateManifestWrite`
+ * rejects a different filename, a traversal path, or a non-JSON body before
+ * the handler touches the filesystem.
+ */
+
+import { readFile, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import type { Request, Response } from 'express';
+import { MANIFEST_FILENAME } from '@volter/editor-project/manifest/filename';
+import { resolveManifestPath } from '@volter/editor-project/manifest/locate';
+import {
+  deriveProjectAttributionReport,
+  emptyProjectProvenanceDocument,
+  formatProjectAttributionMarkdown,
+  PROJECT_PROVENANCE_PATH,
+  ProjectProvenanceDocumentSchema,
+} from '../support/project/provenance';
+import type { EditorServerRouter } from '../editor-server';
+import type { EngineProvenance } from '../engine-provenance';
+import { projectEnginePackageOrigin } from '../project-package-origin';
+import { readProjectVerbFacts } from '../project-verbs';
+import { readProjectViewResult } from '../project-view';
+import {
+  isCanonicalPathInside,
+  isMonorepoScaffoldRoot,
+  isPathInside,
+  validateManifestWrite,
+} from '../server-utils';
+import { isEphemeralSession, processSessionId } from '../session-registry';
+import type { RouteContext } from './context';
+
+/**
+ * Registered SEPARATELY, and before the project-file-serving middleware,
+ * because that is where it sat: this is a read of the project's own
+ * provenance document, not a file the middleware should get a chance at.
+ */
+export function registerProjectAttributionRoute(
+  router: EditorServerRouter,
+  ctx: RouteContext,
+): void {
+  const { engineRoot } = ctx;
+
+  // Derived credits view. The sole durable source is central project provenance.
+  router.get('/__editor/project-attribution', async (req: Request, res: Response) => {
+    if (ctx.projectRoot === engineRoot) {
+      res.status(400).json({ error: 'No project is open.' });
+      return;
+    }
+    try {
+      const raw = await readFile(join(ctx.projectRoot, PROJECT_PROVENANCE_PATH), 'utf8').catch(
+        (error: NodeJS.ErrnoException) => {
+          if (error.code === 'ENOENT') return null;
+          throw error;
+        },
+      );
+      const provenance = raw
+        ? ProjectProvenanceDocumentSchema.parse(JSON.parse(raw))
+        : emptyProjectProvenanceDocument();
+      const activeOperations = Object.fromEntries(
+        (
+          await Promise.all(
+            Object.entries(provenance.operations).map(async ([operationId, operation]) => {
+              const present = await Promise.all(
+                operation.outputs.map(async (output) => {
+                  const absolute = resolve(ctx.projectRoot, output.path);
+                  if (!isPathInside(ctx.projectRoot, absolute)) return false;
+                  return stat(absolute).then(
+                    (info) => info.isFile(),
+                    () => false,
+                  );
+                }),
+              );
+              return present.some(Boolean) ? ([operationId, operation] as const) : null;
+            }),
+          )
+        ).filter((entry): entry is readonly [string, (typeof provenance.operations)[string]] =>
+          Boolean(entry),
+        ),
+      );
+      const report = deriveProjectAttributionReport({ version: 1, operations: activeOperations });
+      const format = typeof req.query['format'] === 'string' ? req.query['format'] : 'json';
+      if (format === 'markdown' || req.accepts(['json', 'text/markdown']) === 'text/markdown') {
+        res.type('text/markdown').send(formatProjectAttributionMarkdown(report));
+        return;
+      }
+      res.json(report);
+    } catch (error) {
+      res.status(500).json({ error: `Project attribution failed: ${error}` });
+    }
+  });
+}
+
+export function registerProjectIdentityRoutes(router: EditorServerRouter, ctx: RouteContext): void {
+  const {
+    commitProjectMutation,
+    compatibilityIdentity,
+    currentSessionIdentity,
+    engineRoot,
+    enginePromise,
+    options,
+    projectMutationError,
+    trustedShareIdentity,
+  } = ctx;
+
+  // ---- Browser/server compatibility identity ----
+  router.get('/__editor/compatibility', (_req: Request, res: Response) => {
+    res.set('Cache-Control', 'no-store');
+    res.json(compatibilityIdentity());
+  });
+
+  // ---- Current project info ----
+  /**
+   * Who is answering — the server's own pid, and whether it is a throwaway
+   * probe (`VGAI_EPHEMERAL_SESSION`, today `vgai doctor`) rather than a
+   * session anyone owns.
+   *
+   * FX-1: `vgai edit` decided "this project's editor is already open" from the
+   * `project.path` above alone, and a probe server answers with exactly that
+   * path for the few seconds it lives — so an attach could succeed, exit 0,
+   * and leave every control command with nothing to talk to. The CLI now ASKS
+   * the session what it is instead of inferring it from the port; the
+   * registry's pid is the same `process.pid` reported here
+   * (`session-registry.ts`), which is what makes the two views comparable.
+   */
+  const serverSessionIdentity = (shared = false) => {
+    const identity = currentSessionIdentity();
+    const value = {
+      pid: process.pid,
+      ephemeral: isEphemeralSession(),
+      sessionId: processSessionId(),
+      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,
+    };
+    if (!shared) return value;
+    return {
+      ephemeral: value.ephemeral,
+      sessionId: value.sessionId,
+      repositoryId: value.repositoryId,
+      worktreeId: value.worktreeId,
+      projectRelativePath: value.projectRelativePath,
+      branch: value.branch,
+    };
+  };
+
+  router.get('/__editor/project', async (req: Request, res: Response) => {
+    const session = serverSessionIdentity(trustedShareIdentity(req) !== null);
+    // On EVERY branch, including "no project open": the question "what code is
+    // this port serving?" is the one a caller asks precisely when nothing else
+    // about the session makes sense (engine-provenance.ts).
+    const engine: EngineProvenance = await enginePromise;
+    // A SERVER fact, not a project one, so it rides at the top level and is
+    // answered on every branch: whether this host serves the `/__ui-source/*`
+    // recorder decides whether an authoring edit is written to the game's own
+    // source or is honestly live-only, and the client asks that question
+    // (`src/ui-source/tier-source-write-backend.ts`) about the PORT, not about
+    // whatever project happens to be open on it.
+    const sourceWrite = options.sourceWriteRoutes === true;
+    // The ingest lane's own route, stated beside it and on every branch for the
+    // same reason: `/__ingest-source/*` comes from a DIFFERENT plugin, so a host
+    // can serve one and not the other, and the client must not infer either
+    // from the other.
+    const ingestSourceWrite = options.ingestSourceWriteRoutes === true;
+    if (ctx.projectRoot === engineRoot) {
+      // No project open
+      res.json({ project: null, session, engine, sourceWrite, ingestSourceWrite });
+      return;
+    }
+    const configResult = await readProjectViewResult(ctx.projectRoot);
+    if (!configResult.ok) {
+      // Boot routing: this server IS serving a project — it just cannot
+      // describe it. Answering a bare `{ project: null }` here is
+      // indistinguishable from "no project open", which is how a page for a
+      // live, project-serving session ended up rendering the launcher.
+      // `serving` names the path and the reason so the client fails loudly
+      // instead (boot-routing.ts, `decideServerProjectBoot`).
+      res.json({
+        project: null,
+        serving: { path: ctx.projectRoot, error: configResult.error },
+        session,
+        engine,
+        sourceWrite,
+        ingestSourceWrite,
+      });
+      return;
+    }
+    const config = configResult.view;
+    // hasUiRegistry: whether the project ships an OPTIONAL src/ui/registry.ts
+    // (scene-UI project mode, D9). The client must not
+    // probe /@fs for it — a dev server answers 200 (SPA fallback) for missing
+    // files, and a dynamic import of a missing module logs an unsuppressible
+    // browser network error on every registry-less project.
+    const hasUiRegistry = await stat(join(ctx.projectRoot, 'src', 'ui', 'registry.ts')).then(
+      (s) => s.isFile(),
+      () => false,
+    );
+    // `packaged`: true iff this server is the no-monorepo-checkout runtime
+    // (`packages/editor/server/packaged.ts`) — same `isMonorepoScaffoldRoot`
+    // check the "New Project" packaged-mode guard already uses server-side
+    // (server-utils.ts). Client-side, `binding-resolver.ts`'s react-world
+    // mount reads this to decide whether it must resolve its
+    // `react`/`react-dom/client`/`WorldProvider` wrapper from the PROJECT's
+    // own module graph (packaged: the editor's prebuilt SPA bundles its OWN
+    // separate react copy, so a react world would dual-instance otherwise)
+    // or keep the existing static-import path (dev: one shared Vite
+    // instance + root `vite.config.ts`'s `resolve.dedupe` — including
+    // `@vgai/game-runtime` itself, so `WorldProvider`/`useGame` are one context
+    // object — already collapses them, so this flag is `false` there and
+    // that path stays unchanged).
+    const packaged = !isMonorepoScaffoldRoot(engineRoot);
+    const enginePackage = projectEnginePackageOrigin(ctx.projectRoot);
+    res.json({
+      project: { path: ctx.projectRoot, config, hasUiRegistry, packaged, enginePackage },
+      session,
+      engine,
+      sourceWrite,
+      ingestSourceWrite,
+    });
+  });
+
+  // The two project files behind the `project.*` coverage family, as raw facts
+  // (`server/project-verbs.ts`). A separate route from `/__editor/project`
+  // deliberately: that one is BOOT routing and every caller of it is on the
+  // critical path, while this is a periodic vitals read whose failures must
+  // never be able to make a session look projectless.
+  router.get('/__editor/project-verbs', async (_req: Request, res: Response) => {
+    res.json(await readProjectVerbFacts(ctx.projectRoot === engineRoot ? null : ctx.projectRoot));
+  });
+  // ---- Manifest write (A4, D8 — the ONE manifest-write verb) ----
+  // Unlike every other write route above, this one HARD-CODES its
+  // destination: `join(ctx.projectRoot, 'vgai.project.json')`, NEVER derived from
+  // `req.body`. `validateManifestWrite` (server-utils.ts, unit-tested there)
+  // rejects anything else (a different filename, a traversal path, a
+  // non-string/non-JSON body) before this handler ever touches the
+  // filesystem — see `server-security.test.ts` for the rejection matrix.
+  router.post('/__editor/manifest', async (req: Request, res: Response) => {
+    const body = req.body as { path?: unknown; content?: unknown };
+    const result = validateManifestWrite(ctx.projectRoot, engineRoot, body);
+    if (!result.ok) {
+      res.status(result.status).json({ error: result.error });
+      return;
+    }
+    try {
+      const revision = await commitProjectMutation(req, [
+        { path: MANIFEST_FILENAME, content: result.content },
+      ]);
+      res.json({ ok: true, revision: revision?.revision ?? null });
+    } catch (error) {
+      projectMutationError(res, error);
+    }
+  });
+
+  router.get('/__editor/manifest', async (req: Request, res: Response) => {
+    if (ctx.projectRoot === engineRoot) {
+      res.status(404).json({ error: 'No project open.' });
+      return;
+    }
+    try {
+      const manifestPath = resolveManifestPath(ctx.projectRoot);
+      if (
+        trustedShareIdentity(req) &&
+        !(await isCanonicalPathInside(ctx.projectRoot, manifestPath))
+      ) {
+        res.status(403).json({ error: 'Shared manifest path leaves the project root.' });
+        return;
+      }
+      res.type('application/json').send(await readFile(manifestPath));
+    } catch {
+      res.status(404).json({ error: 'Not found.' });
+    }
+  });
+
+  router.delete('/__editor/manifest', async (req: Request, res: Response) => {
+    if (ctx.projectRoot === engineRoot) {
+      res.status(400).json({ error: 'No project open.' });
+      return;
+    }
+    try {
+      const revision = await commitProjectMutation(req, [
+        { path: MANIFEST_FILENAME, content: null },
+      ]);
+      res.json({ ok: true, revision: revision?.revision ?? null });
+    } catch (error) {
+      projectMutationError(res, error);
+    }
+  });
+}