@volter/editor-core 0.5.57

package/server/share-tunnel.ts

@@ -0,0 +1,123 @@
+import { type ChildProcess, spawn } from 'node:child_process';
+
+export type ShareTunnelProvider = 'cloudflared' | 'ngrok';
+
+export interface ShareTunnel {
+  child: ChildProcess;
+  publicUrl: string;
+}
+
+export type ShareTunnelStarter = (port: number) => Promise<ShareTunnel>;
+
+function publicUrl(line: string, pattern: RegExp): string | null {
+  const direct = line.match(pattern)?.[0];
+  if (direct) return direct;
+  try {
+    const parsed = JSON.parse(line) as Record<string, unknown>;
+    for (const value of Object.values(parsed)) {
+      if (typeof value !== 'string') continue;
+      const match = value.match(pattern)?.[0];
+      if (match) return match;
+    }
+  } catch {
+    // Human-readable output is handled by the direct expression.
+  }
+  return null;
+}
+
+export function parseNgrokPublicUrl(line: string): string | null {
+  return publicUrl(line, /https:\/\/[a-zA-Z0-9.-]+\.ngrok(?:-free)?\.(?:app|dev)/);
+}
+
+export function parseCloudflaredPublicUrl(line: string): string | null {
+  return publicUrl(line, /https:\/\/[a-zA-Z0-9-]+\.trycloudflare\.com/);
+}
+
+function startTunnelProcess(input: {
+  provider: ShareTunnelProvider;
+  command: string;
+  args: string[];
+  parseUrl(line: string): string | null;
+  prerequisite: string;
+}): Promise<ShareTunnel> {
+  const child = spawn(input.command, input.args, { stdio: ['ignore', 'pipe', 'pipe'] });
+  return new Promise<ShareTunnel>((resolveUrl, rejectUrl) => {
+    let settled = false;
+    let output = '';
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill('SIGTERM');
+      rejectUrl(
+        new Error(`${input.provider} did not publish a URL within 30 seconds.\n${output.trim()}`),
+      );
+    }, 30_000);
+    const inspect = (chunk: Buffer | string) => {
+      const text = chunk.toString();
+      output = `${output}${text}`.slice(-8_000);
+      for (const line of text.split(/\r?\n/)) {
+        const url = input.parseUrl(line);
+        if (!url || settled) continue;
+        settled = true;
+        clearTimeout(timer);
+        resolveUrl({ child, publicUrl: url });
+        return;
+      }
+    };
+    child.stdout?.on('data', inspect);
+    child.stderr?.on('data', inspect);
+    child.once('error', (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      rejectUrl(new Error(error.message.includes('ENOENT') ? input.prerequisite : error.message));
+    });
+    child.once('exit', (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      rejectUrl(
+        new Error(
+          `${input.provider} exited before publishing a URL (code ${code}).\n${output.trim()}`,
+        ),
+      );
+    });
+  });
+}
+
+export function startNgrokShareTunnel(port: number): Promise<ShareTunnel> {
+  return startTunnelProcess({
+    provider: 'ngrok',
+    command: 'ngrok',
+    args: ['http', `http://127.0.0.1:${port}`, '--log', 'stdout', '--log-format', 'json'],
+    parseUrl: parseNgrokPublicUrl,
+    prerequisite: 'ngrok is required for this share. Install and authenticate ngrok first.',
+  });
+}
+
+export function startCloudflaredShareTunnel(port: number): Promise<ShareTunnel> {
+  return startTunnelProcess({
+    provider: 'cloudflared',
+    command: 'cloudflared',
+    args: [
+      'tunnel',
+      '--url',
+      `http://127.0.0.1:${port}`,
+      '--no-autoupdate',
+      // Quick Tunnels default to QUIC, which is commonly blocked on managed
+      // networks even when ordinary HTTPS works. HTTP/2 preserves the
+      // accountless path without requiring UDP egress.
+      '--protocol',
+      'http2',
+      '--config',
+      process.platform === 'win32' ? 'NUL' : '/dev/null',
+    ],
+    parseUrl: parseCloudflaredPublicUrl,
+    prerequisite:
+      'cloudflared is required for this share. Install cloudflared; Quick Tunnels need no Cloudflare account.',
+  });
+}
+
+export function shareTunnelStarter(provider: ShareTunnelProvider): ShareTunnelStarter {
+  return provider === 'cloudflared' ? startCloudflaredShareTunnel : startNgrokShareTunnel;
+}

package/server/spawn-opener.ts

@@ -0,0 +1,74 @@
+/**
+ * Best-effort launch of an OS "open a URL" command (`open`, `cmd /c start`,
+ * `powershell.exe Start-Process`, `xdg-open`, …), extracted from
+ * `index.ts`'s `openBrowser` into its own module so it's unit-testable
+ * against a REAL spawned child (see `spawn-opener.test.ts`) without pulling
+ * in the whole CLI entry point.
+ */
+
+import { type ChildProcess, spawn } from 'node:child_process';
+
+/** Cap on how much of a failed opener's stderr we buffer before printing —
+ *  enough for a real error message, small enough to never matter for a
+ *  detached fire-and-forget child. */
+export const OPENER_STDERR_CAP_BYTES = 2048;
+
+/** An unref'd child's piped stderr only stays readable for as long as THIS
+ *  process's event loop keeps ticking — normally guaranteed by the caller's
+ *  verified-open poll (>=15s, see waitForVerifiedEditorOpen). Belt-and-
+ *  suspenders bound so a genuinely long-lived/never-exiting opener can't
+ *  hold the pipe (and this process) open indefinitely if the parent exits
+ *  on its own first. */
+export const OPENER_EXIT_WATCH_TIMEOUT_MS = 20_000;
+
+/** Fire one open attempt, NAMING the failure instead of swallowing it.
+ *  Two failure modes, both silent before this fix:
+ *  - meteor-dodge dry-run friction #1: the powershell.exe hand-off died
+ *    silently in a background shell — spawn launch failures arrive on the
+ *    child's 'error' event, which nothing listened to.
+ *  - run-3 dogfood friction #3: a child that LAUNCHES but exits nonzero
+ *    (e.g. Start-Process itself failing inside powershell) was silent too —
+ *    stdio was fully 'ignore'd and nothing checked the exit code.
+ *  Still best-effort: a failure logs one line (stderr captured, capped, and
+ *  included when available) and runs `fallback`, if given — never throws,
+ *  never blocks. */
+export function spawnOpener(cmd: string, cmdArgs: string[], fallback?: () => void): void {
+  let child: ChildProcess;
+  try {
+    child = spawn(cmd, cmdArgs, { stdio: ['ignore', 'ignore', 'pipe'], detached: true });
+  } catch (err) {
+    console.error(`vgai: auto-open via ${cmd} failed: ${(err as Error).message}`);
+    fallback?.();
+    return;
+  }
+
+  const stderrChunks: Buffer[] = [];
+  let stderrBytes = 0;
+  child.stderr?.on('data', (chunk: Buffer) => {
+    if (stderrBytes >= OPENER_STDERR_CAP_BYTES) return;
+    const remaining = OPENER_STDERR_CAP_BYTES - stderrBytes;
+    const slice = chunk.length > remaining ? chunk.subarray(0, remaining) : chunk;
+    stderrChunks.push(slice);
+    stderrBytes += slice.length;
+  });
+
+  child.on('error', (err) => {
+    console.error(`vgai: auto-open via ${cmd} failed to launch: ${err.message}`);
+    fallback?.();
+  });
+
+  child.on('exit', (code) => {
+    if (code !== null && code !== 0) {
+      const stderr = Buffer.concat(stderrChunks).toString('utf8').trim();
+      console.error(`vgai: auto-open via ${cmd} exited ${code}: ${stderr}`);
+      fallback?.();
+    }
+  });
+
+  child.unref();
+
+  const pipeTimeout = setTimeout(() => {
+    child.stderr?.destroy();
+  }, OPENER_EXIT_WATCH_TIMEOUT_MS);
+  pipeTimeout.unref();
+}

package/server/support/play/log-format.ts

@@ -0,0 +1,76 @@
+/**
+ * THE on-disk shape of `<project>/logs/play-*.jsonl` — one definition, shared
+ * by the writer (`editor-server.ts`'s `/__editor/log-session` +
+ * `/__editor/log-entries` handlers) and every reader (`play.log.*` here,
+ * `vgai status`'s play-error banner, the project Analytics utility).
+ *
+ * A play log is JSONL with TWO record kinds:
+ *
+ *   1. THE HEADER — always the FIRST line, written when the file is opened:
+ *      `{"kind":"session","v":1,"session":…,"project":…,"run":…,"startedAt":…}`.
+ *      This is where the run's IDENTITY lives, recorded ONCE. The alternative
+ *      (stamping session/project onto every entry) pays the same constant
+ *      thousands of times per run for facts that cannot change while the file
+ *      is open — the file is opened by one session, for one project, at one
+ *      instant.
+ *   2. ENTRIES — every later line: `{t, level, source?, sub?, msg, meta?,
+ *      tick?, simT?, world?, simSpeed?}`. Only genuinely per-entry facts go
+ *      here: `tick`/`simT` (the frame the line was written on), `simSpeed`
+ *      (the live time scale, which an instrument can change mid-run) and
+ *      `world` (the world the run is presenting, unknown until the roots
+ *      mount — so the entries written during boot honestly carry none).
+ *
+ * A reader must SKIP the header when counting or listing entries
+ * (`asPlayLogHeader` is the one test), and must tolerate its ABSENCE: logs
+ * written before the header existed are still on disk in real projects, and
+ * "no header" means "this run's identity was never recorded", never an error.
+ */
+
+/** `kind` value marking a play log's header line. */
+export const PLAY_LOG_HEADER_KIND = 'session';
+
+/** Bumped only when the on-disk record shapes change incompatibly. */
+export const PLAY_LOG_FORMAT_VERSION = 1;
+
+/** The run identity a play log carries on its first line. */
+export interface PlayLogHeader {
+  readonly kind: typeof PLAY_LOG_HEADER_KIND;
+  readonly v: number;
+  /** The editor session that opened the file (`processSessionId()`) — the same
+   *  id `vgai sessions` lists, so a log file names the session that wrote it. */
+  readonly session: string;
+  /** Absolute project root the session was serving. */
+  readonly project: string;
+  /** The run's slug (`vgai play --name <text>`), `null` for an unnamed run —
+   *  the same slug that goes in the filename and the session journal. */
+  readonly run: string | null;
+  /** Wall-clock ms at which the file was opened. */
+  readonly startedAt: number;
+}
+
+/** The header line (newline included) for a run's identity. */
+export function playLogHeaderLine(identity: Omit<PlayLogHeader, 'kind' | 'v'>): string {
+  const header: PlayLogHeader = {
+    kind: PLAY_LOG_HEADER_KIND,
+    v: PLAY_LOG_FORMAT_VERSION,
+    ...identity,
+  };
+  return `${JSON.stringify(header)}\n`;
+}
+
+/** The parsed header, or `null` when this record is an ordinary entry (or a
+ *  header from an unreadable/older shape). Every reader's one header test. */
+export function asPlayLogHeader(record: unknown): PlayLogHeader | null {
+  if (typeof record !== 'object' || record === null || Array.isArray(record)) return null;
+  const rec = record as Record<string, unknown>;
+  if (rec['kind'] !== PLAY_LOG_HEADER_KIND) return null;
+  if (typeof rec['session'] !== 'string' || typeof rec['project'] !== 'string') return null;
+  return {
+    kind: PLAY_LOG_HEADER_KIND,
+    v: typeof rec['v'] === 'number' ? rec['v'] : 0,
+    session: rec['session'],
+    project: rec['project'],
+    run: typeof rec['run'] === 'string' ? rec['run'] : null,
+    startedAt: typeof rec['startedAt'] === 'number' ? rec['startedAt'] : 0,
+  };
+}

package/server/support/play/session-record.ts

@@ -0,0 +1,199 @@
+/**
+ * The Gameplay Session RECORD, as pure functions over the play log's text.
+ * The server derives the catalog from `logs/*.jsonl` on disk
+ * (`server/gameplay-sessions.ts`, which keeps its stat-keyed cache and fs
+ * wiring and calls in here); the functions themselves touch no filesystem, so
+ * the rules live in one place. They are subtle enough to fork badly — the
+ * torn live-append tail, the
+ * `ended` marker, the three-message recording lifecycle — which is why they
+ * live HERE and nowhere twice.
+ *
+ * Also home to the retention budgets, for the same reason: two copies of a
+ * byte budget is how two readers start keeping different histories.
+ */
+
+import { asPlayLogHeader } from './log-format';
+
+/** Structured logs are the durable Analytics source. At the current event
+ * density this keeps hundreds of substantial sessions, without allowing one
+ * project to grow forever. */
+export const GAMEPLAY_SESSION_LOG_BUDGET_BYTES = 256 * 1024 * 1024;
+
+/** Automatically named session clips are working evidence, not keepsakes.
+ * Two GiB provides a useful history while making long recordings pay their
+ * actual disk cost. Explicitly named recordings are outside this budget. */
+export const GAMEPLAY_SESSION_CLIP_BUDGET_BYTES = 2 * 1024 * 1024 * 1024;
+
+export interface GameplaySessionRecording {
+  readonly format: 'composite-webm' | 'canvas-dom';
+  readonly replay: string | null;
+  readonly file: string;
+  readonly url: string;
+  readonly startedAt: number | null;
+  readonly finalized: boolean;
+  readonly bytes: number | null;
+}
+
+export interface GameplaySessionRecord {
+  readonly id: string;
+  readonly run: string | null;
+  readonly status: 'live' | 'completed';
+  readonly startedAt: number;
+  readonly endedAt: number | null;
+  readonly durationMs: number;
+  readonly logFile: string;
+  readonly entries: readonly Record<string, unknown>[];
+  readonly recording: GameplaySessionRecording | null;
+}
+
+export interface ParsedGameplaySession {
+  readonly id: string;
+  readonly run: string | null;
+  readonly startedAt: number;
+  readonly endedAt: number | null;
+  readonly logFile: string;
+  readonly entries: readonly Record<string, unknown>[];
+  readonly recording: GameplaySessionRecording | null;
+  readonly fallbackEndedAt: number;
+}
+
+function numberField(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+/** A bare filename — no path separators. The same refusal the server's
+ *  `basename(file) !== file` check made, path-module-free. */
+function isBareFilename(file: string): boolean {
+  return file.length > 0 && !file.includes('/') && !file.includes('\\');
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: this is a small single-pass reducer over three recording lifecycle messages.
+function recordingEvent(
+  entries: readonly Record<string, unknown>[],
+): Omit<GameplaySessionRecording, 'url'> | null {
+  type RecordingState = Omit<GameplaySessionRecording, 'url'>;
+  let current: RecordingState | null = null;
+  for (const entry of entries) {
+    if (entry['source'] !== 'gameplay-recording') continue;
+    const meta = entry['meta'];
+    if (typeof meta !== 'object' || meta === null || Array.isArray(meta)) continue;
+    const fields = meta as Record<string, unknown>;
+    const file = fields['file'];
+    if (typeof file !== 'string' || !isBareFilename(file)) continue;
+    if (entry['msg'] === 'started') {
+      current = {
+        file,
+        format: fields['format'] === 'canvas-dom' ? 'canvas-dom' : 'composite-webm',
+        replay: null,
+        startedAt: numberField(fields['startedAt']),
+        finalized: false,
+        bytes: null,
+      };
+    } else if (entry['msg'] === 'finalized') {
+      const existing = current as RecordingState | null;
+      if (existing?.file === file) {
+        current = {
+          ...existing,
+          finalized: true,
+          bytes: numberField(fields['bytes']),
+          replay:
+            typeof fields['replay'] === 'string' && isBareFilename(fields['replay'])
+              ? fields['replay']
+              : null,
+        };
+      }
+    } else if (
+      (current as RecordingState | null)?.file === file &&
+      (entry['msg'] === 'aborted' || entry['msg'] === 'evicted')
+    ) {
+      current = null;
+    }
+  }
+  return current;
+}
+
+export interface ParsePlayLogOptions {
+  /** The log's bare filename, e.g. `play-2026-…-0001.jsonl`. */
+  readonly file: string;
+  /** What "ended" means when the log carries no `ended` marker (a crashed
+   *  run): the file's own last-modified time on tiers that know it, or the
+   *  read time otherwise. */
+  readonly fallbackEndedAt: number;
+  /** How this tier addresses the session's recording, when one survives the
+   *  lifecycle reduce — the server serves a route, the browser has none. */
+  readonly recordingUrl: (sessionId: string, recordingFile: string) => string;
+}
+
+/**
+ * Parse one play log's raw text into the session record's parsed half, or
+ * `null` when the first line is not a play-log identity header (any other
+ * JSONL in `logs/` is not a session).
+ */
+export function parsePlayLogText(
+  raw: string,
+  options: ParsePlayLogOptions,
+): ParsedGameplaySession | null {
+  const records: unknown[] = [];
+  for (const line of raw.split('\n')) {
+    if (line.trim() === '') continue;
+    try {
+      records.push(JSON.parse(line) as unknown);
+    } catch {
+      // A live append may expose a torn tail. Everything before it remains a
+      // valid session record and the next poll will pick up the completed row.
+    }
+  }
+  const header = asPlayLogHeader(records[0]);
+  if (!header) return null;
+  const entries = records
+    .slice(1)
+    .filter(
+      (value): value is Record<string, unknown> =>
+        typeof value === 'object' && value !== null && !Array.isArray(value),
+    );
+  const end = [...entries]
+    .reverse()
+    .find((entry) => entry['source'] === 'gameplay-session' && entry['msg'] === 'ended');
+  const endMeta =
+    typeof end?.['meta'] === 'object' && end['meta'] !== null && !Array.isArray(end['meta'])
+      ? (end['meta'] as Record<string, unknown>)
+      : null;
+  const recording = recordingEvent(entries);
+  const id = options.file.replace(/\.[^.]*$/, '');
+  return {
+    id,
+    run: header.run,
+    startedAt: header.startedAt,
+    endedAt: numberField(endMeta?.['endedAt']),
+    fallbackEndedAt: options.fallbackEndedAt,
+    logFile: `logs/${options.file}`,
+    entries,
+    recording: recording ? { ...recording, url: options.recordingUrl(id, recording.file) } : null,
+  };
+}
+
+/**
+ * Project a parsed session against the tier's live state: the active log (if
+ * this is it, the session is `live` and its edge is `now`) or the recorded /
+ * fallback end.
+ */
+export function materializeGameplaySession(
+  parsed: ParsedGameplaySession,
+  options: { readonly activeLogBaseName: string | null; readonly now: number },
+): GameplaySessionRecord {
+  const active =
+    options.activeLogBaseName !== null && parsed.logFile === `logs/${options.activeLogBaseName}`;
+  const endedAt = active ? null : (parsed.endedAt ?? parsed.fallbackEndedAt);
+  const liveEdge = active ? options.now : (endedAt ?? parsed.fallbackEndedAt);
+  return {
+    id: parsed.id,
+    run: parsed.run,
+    status: active ? 'live' : 'completed',
+    startedAt: parsed.startedAt,
+    endedAt,
+    durationMs: Math.max(0, liveEdge - parsed.startedAt),
+    logFile: parsed.logFile,
+    entries: parsed.entries,
+    recording: parsed.recording,
+  };
+}