@volter/editor-sdk 0.5.57

package/src/session/registry-format.ts

@@ -0,0 +1,203 @@
+/**
+ * `~/.vgai/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/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 vgai-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(), '.vgai', '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,
+  };
+}
+
+export function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 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, '.vgai', '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, '.vgai', '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;
+}

package/src/session/source-glob.ts

@@ -0,0 +1,15 @@
+/**
+ * One glob → one anchored RegExp, for a finder selection's `include`
+ * (ARCHITECTURE-CORE §The project model): `**` matches any depth, `*` one
+ * segment. No imports, so the editor server and the browser share it.
+ */
+export function globToRegExp(glob: string): RegExp {
+  const GLOBSTAR = '__VGAI_GLOBSTAR__';
+  const escaped = glob
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*\//g, GLOBSTAR)
+    .replace(/\*/g, '[^/]*')
+    .split(GLOBSTAR)
+    .join('(?:.*/)?');
+  return new RegExp(`^${escaped}$`);
+}

package/src/session/tool-contribution-convention.ts

@@ -0,0 +1,116 @@
+/**
+ * The tool-contribution FILENAME CONVENTION — the one definition for every
+ * program that asks "is this file a contribution module?": the dev server's
+ * scanner and `src/`-watcher classifier (`server/server-utils.ts`,
+ * `server/project-tools.ts`), and the page-side readers that must reach the
+ * same verdict about the same files. Lives in `src/` and names no DOM so the
+ * server TypeScript program can import it — the same split
+ * `game-globals-prelude.ts` documents for the globals prelude.
+ */
+
+/**
+ * The two editor-side folders of a project (ARCHITECTURE-CORE §The project
+ * model): `src/contributions/` — what the project adds to the editor
+ * (documents, inspectors, utilities, analytics, kinds, finders) — and
+ * `src/tools/` — the tools a person or an agent invokes (`*.tool.ts`).
+ * Neither is bundled at Play; both reload the editor, never the game.
+ */
+export const CONTRIBUTIONS_DIR = 'src/contributions';
+export const TOOLS_DIR = 'src/tools';
+export const EDITOR_LANE_DIRS = [CONTRIBUTIONS_DIR, TOOLS_DIR] as const;
+
+/** Whether a project-relative (or absolute, `/`-normalized) path sits in the editor's lane. */
+export function isEditorLanePath(path: string): boolean {
+  const normalized = path.replaceAll('\\', '/');
+  return EDITOR_LANE_DIRS.some(
+    (dir) => normalized.startsWith(`${dir}/`) || normalized.includes(`/${dir}/`),
+  );
+}
+
+export const TOOL_CONTRIBUTION_SUFFIXES = [
+  '.document',
+  '.inspector',
+  '.asset-inspector',
+  '.result',
+  '.utility',
+  '.analytics',
+  // A STATUS-BAR item (`workspace-status-registry.ts`): compact, passive,
+  // registered under `tool:<id>` like a utility tab.
+  '.status',
+  // A configuration KIND contribution (ARCHITECTURE-CORE §The project model);
+  // read by the hosts that load the manifest, never mounted as UI.
+  '.kind',
+  // A FINDER contribution — registered into the finder registry by the host
+  // that resolves the document table (the browser), never mounted as UI.
+  '.finder',
+  // The LOOK points (`@volter/editor-sdk/looks`): a workspace layout, a keymap
+  // and a style bundle are DATA — registered by the host, mounted by no UI
+  // point. What makes "the Blender" a build is a package contributing these.
+  '.layout',
+  '.keymap',
+  '.style',
+  // A COMMAND table (`@volter/editor-sdk/commands`): session verbs a package
+  // answers, registered with the host's relay; data, no UI.
+  '.command',
+  // The CHROME points (`@volter/editor-sdk/chrome`): palette actions and
+  // application-menu items; data the host renders in its own chrome.
+  '.action',
+  '.menu',
+  // A HEADER item: a component in the project header's transport cluster.
+  '.header',
+  // A SERVICE (`@volter/editor-sdk/services`): code a package runs while its
+  // contributions are loaded — started after a pass, stopped before the next.
+  '.service',
+] as const;
+
+const TOOL_CONTRIBUTION_EXTENSIONS = ['.tsx', '.jsx', '.ts'] as const;
+
+export type ChromeContributionKind = 'action' | 'menu' | 'header';
+
+/** Which chrome point a contribution file names, or null. */
+export function chromeContributionKind(fileName: string): ChromeContributionKind | null {
+  for (const kind of ['action', 'menu', 'header'] as const)
+    if (TOOL_CONTRIBUTION_EXTENSIONS.some((extension) => fileName.endsWith(`.${kind}${extension}`)))
+      return kind;
+  return null;
+}
+
+export function isServiceContribution(fileName: string): boolean {
+  return TOOL_CONTRIBUTION_EXTENSIONS.some((extension) =>
+    fileName.endsWith(`.service${extension}`),
+  );
+}
+
+export function isCommandContribution(fileName: string): boolean {
+  return TOOL_CONTRIBUTION_EXTENSIONS.some((extension) =>
+    fileName.endsWith(`.command${extension}`),
+  );
+}
+
+export type LookContributionKind = 'layout' | 'keymap' | 'style';
+
+/** Which look point a contribution file names, or null for a module of
+ *  another kind. */
+export function lookContributionKind(fileName: string): LookContributionKind | null {
+  for (const kind of ['layout', 'keymap', 'style'] as const)
+    if (TOOL_CONTRIBUTION_EXTENSIONS.some((extension) => fileName.endsWith(`.${kind}${extension}`)))
+      return kind;
+  return null;
+}
+
+/** A kind contribution: scanned with the rest, mounted by no UI point. */
+/** A finder contribution: registered by the document-table host, mounted by no UI point. */
+export function isFinderContribution(fileName: string): boolean {
+  return TOOL_CONTRIBUTION_EXTENSIONS.some((extension) => fileName.endsWith(`.finder${extension}`));
+}
+
+export function isConfigurationKindContribution(fileName: string): boolean {
+  return TOOL_CONTRIBUTION_EXTENSIONS.some((extension) => fileName.endsWith(`.kind${extension}`));
+}
+
+/** Whether one file name is a contribution module by the convention above. */
+export function isToolContributionModule(fileName: string): boolean {
+  return TOOL_CONTRIBUTION_EXTENSIONS.some((extension) =>
+    TOOL_CONTRIBUTION_SUFFIXES.some((suffix) => fileName.endsWith(`${suffix}${extension}`)),
+  );
+}