@volter/sdk 0.0.0-stage → 0.5.204

package/src/session/registry-format.ts

@@ -0,0 +1,210 @@
+/**
+ * `~/.volter/editor-sessions.json` — the ONE spelling of the editor-session
+ * registry contract, and the shared machinery every reader was hand-copying.
+ *
+ * The registry's WRITE half stays with its owner
+ * (`packages/editor-core/server/session-registry.ts`); this module owns the
+ * FORMAT: the entry shape, the shape guards, the file path, the
+ * liveness-filtered read, the `/__editor/project` answer parser, and the
+ * pending-launch coordination. It existed as FOUR drifting copies
+ * (server registry, the CLI, and both volter-sdk transports) held together by
+ * a "the CLI has no editor dependency" premise that had stopped being true —
+ * and the drift was already real: one copy's `/__editor/project` parser
+ * dropped `manifestError`, reporting a degraded session as belonging to no
+ * project.
+ */
+
+import {
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+
+/** One registry entry, exactly as the server's write half records it. */
+export interface EditorSessionEntry {
+  /** Canonical project root currently open, or null when none. */
+  project: string | null;
+  port: number;
+  /** PID of the dev-server process. */
+  pid: number;
+  /** ISO timestamp of server start. */
+  startedAt: string;
+  sessionId: string | null;
+  /** Private loopback control credential — never returned by an editor HTTP
+   *  route; exists only in this user-private registry. */
+  controlSecret?: string | null;
+  repositoryId: string | null;
+  worktreeId: string | null;
+  worktreeRoot: string | null;
+  projectRelativePath: string | null;
+  branch: string | null;
+  headCommit: string | null;
+  baseCommit: string | null;
+}
+
+export const EDITOR_SESSIONS_REGISTRY_FILE = join(homedir(), '.volter', 'editor-sessions.json');
+
+export function isEditorSessionEntry(v: unknown): v is EditorSessionEntry {
+  if (typeof v !== 'object' || v === null) return false;
+  const s = v as Record<string, unknown>;
+  const optionalIdentity = (value: unknown) =>
+    value === undefined || value === null || typeof value === 'string';
+  return (
+    (typeof s['project'] === 'string' || s['project'] === null) &&
+    typeof s['port'] === 'number' &&
+    typeof s['pid'] === 'number' &&
+    typeof s['startedAt'] === 'string' &&
+    optionalIdentity(s['sessionId']) &&
+    optionalIdentity(s['controlSecret']) &&
+    optionalIdentity(s['repositoryId']) &&
+    optionalIdentity(s['worktreeId']) &&
+    optionalIdentity(s['worktreeRoot']) &&
+    optionalIdentity(s['projectRelativePath']) &&
+    optionalIdentity(s['branch']) &&
+    optionalIdentity(s['headCommit']) &&
+    optionalIdentity(s['baseCommit'])
+  );
+}
+
+export function normalizeEditorSessionEntry(session: EditorSessionEntry): EditorSessionEntry {
+  return {
+    ...session,
+    sessionId: session.sessionId ?? null,
+    controlSecret: session.controlSecret ?? null,
+    repositoryId: session.repositoryId ?? null,
+    worktreeId: session.worktreeId ?? null,
+    worktreeRoot: session.worktreeRoot ?? null,
+    projectRelativePath: session.projectRelativePath ?? null,
+    branch: session.branch ?? null,
+    headCommit: session.headCommit ?? null,
+    baseCommit: session.baseCommit ?? null,
+  };
+}
+
+/**
+ * Whether `pid` is a running process. Signal 0 checks existence only. EPERM means the
+ * process exists but this caller may not signal it: another user's process, or any
+ * process outside a sandboxed agent's shell (Codex on macOS runs commands under
+ * Seatbelt, which denies signals to the editor it did not start). Reading EPERM as
+ * dead made the CLI report "NO live sessions" beside a running editor.
+ */
+export function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+/** The registry's live entries — shape-validated and PID-liveness-filtered. */
+export function readLiveRegisteredSessions(): EditorSessionEntry[] {
+  try {
+    const raw: unknown = JSON.parse(readFileSync(EDITOR_SESSIONS_REGISTRY_FILE, 'utf8'));
+    return Array.isArray(raw)
+      ? raw
+          .filter(isEditorSessionEntry)
+          .map(normalizeEditorSessionEntry)
+          .filter((s) => pidAlive(s.pid))
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Announce a launch before the server can register. Each launcher owns its file. */
+export function announceEditorLaunch(project: string): () => void {
+  const directory = join(project, '.volter', 'editor-launches');
+  mkdirSync(directory, { recursive: true });
+  const file = join(directory, `${process.pid}.json`);
+  writeFileSync(file, JSON.stringify({ pid: process.pid }));
+  const clear = () => {
+    process.removeListener('exit', clear);
+    try {
+      unlinkSync(file);
+    } catch {
+      // Already cleared when the server became ready.
+    }
+  };
+  process.once('exit', clear);
+  return clear;
+}
+
+function hasPendingEditorLaunch(project: string): boolean {
+  const directory = join(project, '.volter', 'editor-launches');
+  try {
+    return readdirSync(directory).some((name) => {
+      if (!/^\d+\.json$/.test(name)) return false;
+      const pid = Number(name.slice(0, -5));
+      return pid !== process.pid && pidAlive(pid);
+    });
+  } catch {
+    return false;
+  }
+}
+
+/** Wait only for an observed live launcher, never for a missing editor. */
+export async function waitForPendingEditorLaunch(project: string): Promise<void> {
+  const canon = canonicalizeProjectPath(project);
+  const ready = () =>
+    readLiveRegisteredSessions().some(
+      (session) => session.project !== null && canonicalizeProjectPath(session.project) === canon,
+    );
+  if (ready() || !hasPendingEditorLaunch(canon)) return;
+  const deadline = Date.now() + 180_000;
+  while (!ready()) {
+    if (!hasPendingEditorLaunch(canon)) {
+      // The launcher clears its announcement only after registration.
+      if (ready()) return;
+      throw new Error(`The editor launch for ${canon} ended before registering a session.`);
+    }
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `The editor launch for ${canon} is still running but has not registered within 180s.`,
+      );
+    }
+    await delay(100);
+  }
+}
+
+/**
+ * WHICH PROJECT a `/__editor/project` body says its server is serving.
+ *
+ * `serving` is that server's own statement of "I AM serving this project, I
+ * just cannot describe it" (its manifest is unparseable or fails strict
+ * validation) — added to the route precisely because a bare
+ * `{ project: null }` is indistinguishable from "no project open". Reading
+ * only `project.path` collapses the two, and the cost is that every
+ * project-matched command loses a live session the moment a save breaks its
+ * manifest, reporting it as belonging to no project rather than as this
+ * project's degraded session.
+ */
+export function servedProjectAnswer(body: unknown): {
+  path: string | null;
+  manifestError: string | null;
+} {
+  const b = body as {
+    project?: { path?: string } | null;
+    serving?: { path?: string; error?: string } | null;
+  };
+  return {
+    path: b.project?.path ?? b.serving?.path ?? null,
+    manifestError: b.project ? null : (b.serving?.error ?? null),
+  };
+}
+
+/** Canonical (realpathed when possible) absolute form of a project path. */
+function canonicalizeProjectPath(p: string): string {
+  const absolute = resolve(p);
+  try {
+    return realpathSync(absolute);
+  } catch {
+    return absolute;
+  }
+}

package/src/session/relative-path-guard.ts

@@ -0,0 +1,56 @@
+/**
+ * THE spelling of "this string is a project-relative path that cannot escape
+ * its root". One helper, because the codebase had four incompatible ones and
+ * the weakest of them was load-bearing on a write route.
+ *
+ * What each of the four missed, and why a single predicate is the fix:
+ *
+ * - `path.includes('..')` (substring) is both too weak and too strong: it
+ *   rejects the innocent `my..file.glb` while accepting nothing extra — but
+ *   its real defect is that it says NOTHING about an ABSOLUTE path. A route
+ *   that then does `resolve(root, 'public', filePath)` gets `filePath` back
+ *   verbatim when it is absolute (that is `resolve`'s contract), so the write
+ *   destination was never inside `root` at all and no `..` ever appeared.
+ * - `rel.startsWith('..')` false-negatives on a real directory named `..bak`.
+ * - `path.split('/').includes('..')` misses `a\..\b` on a Windows-shaped
+ *   input; `path.split(/[\\/]/)` is the form that covers both.
+ * - none of them rejected a NUL byte or a `C:`-rooted path.
+ *
+ * Isomorphic on purpose — no `node:path` — so the browser-side resolver
+ * (`binding-resolver.ts`'s `guardModulePath`) and the Node-side route handlers
+ * enforce the SAME rule instead of two hand-rolled approximations of it. Its
+ * Node-side partner is `server/server-utils.ts`'s `isPathInside`, which
+ * answers the other half of the question (does the RESOLVED absolute path
+ * still land under the root); a write boundary wants both, because this one
+ * cannot see symlinks and that one cannot see intent.
+ */
+
+/** Why a candidate path is not a contained project-relative path. */
+export type RelativePathRejection = 'empty' | 'nul' | 'absolute' | 'traversal';
+
+/**
+ * `null` when `path` is a safe project-relative path, otherwise the reason it
+ * is not. Callers that want a bespoke error message (see `guardModulePath`)
+ * switch on the reason; callers that only gate switch on
+ * {@link isContainedRelativePath}.
+ */
+export function relativePathRejection(path: string): RelativePathRejection | null {
+  if (!path || path.trim() === '') return 'empty';
+  if (path.includes('\0')) return 'nul';
+  // Leading separator (POSIX absolute, UNC) or a Windows drive root. This is
+  // the case a `..` scan structurally cannot see.
+  // The drive form is `C:/…` / `C:\…` specifically — a POSIX file literally
+  // named `C:notes.txt` is relative and stays legal.
+  if (path.startsWith('/') || path.startsWith('\\') || /^[a-zA-Z]:[\\/]/.test(path)) {
+    return 'absolute';
+  }
+  // Segment-wise, over BOTH separators — `..bak` is a legitimate directory
+  // name and must survive; `a\..\b` must not.
+  if (path.split(/[\\/]/).includes('..')) return 'traversal';
+  return null;
+}
+
+/** True when `path` is a non-empty, relative, traversal-free project path. */
+export function isContainedRelativePath(path: string): boolean {
+  return relativePathRejection(path) === null;
+}