@volter/live 0.5.210 → 0.5.212

package/src/registry-format.ts

@@ -0,0 +1,185 @@
+/**
+ * Shared editor-session registry format: entry shape, guards, path,
+ * liveness-filtered reads, served-project parsing and pending launches.
+ * The server’s session-registry module owns writes to this format.
+ */
+
+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 exists. Signal 0's EPERM means it exists but this caller cannot signal it. */
+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);
+  }
+}
+
+/** Read the project identity reported by /__editor/project. A serving path
+ * identifies an open project even when its manifest cannot be parsed or
+ * validated; project: null alone denotes no described project. */
+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.ts

@@ -1,12 +1,11 @@
 /** Resolve an existing session for exactly one project.
  * Prefer the project's hint, verify it against the served canonical path,
- * then consult the shared registry. Never fall back to another project.
- * Storage identifiers move with the server in the coordinated migration. */
+ * then consult the shared registry. Never fall back to another project. */
 
 import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { resolveManifestPath } from '@volter/project/manifest/locate';
-import { resolveProductForProject } from '@volter/sdk/session/product-locator';
+import { resolveProductForProject } from './product-locator.js';
 import {
   EDITOR_SESSION_DISCOVERY_TIMEOUT_MS,
   type EditorSessionInfo,
@@ -14,7 +13,7 @@ import {
   HttpSessionDiscovery,
   servedProjectAnswer,
   withTimeout,
-} from '@volter/sdk/session/discovery';
+} from './discovery.js';
 
 /** Nearest ancestor containing the project's canonical manifest. */
 export function findProjectRootFrom(dir: string): string | null {
@@ -78,6 +77,8 @@ function sameDirectory(a: string, b: string): boolean {
 /** The code a refusal carries when the registry was read and no session opens the project: the
  *  one state in which "no editor is open here" is a fact, which `close` answers as done. */
 export const NO_SESSION_FOR_PROJECT = 'VOLTER_NO_SESSION_FOR_PROJECT';
+/** The `code` of the refusal for this project's session whose manifest does not load; it carries `session`. */
+export const SESSION_MANIFEST_UNREADABLE = 'VOLTER_SESSION_MANIFEST_UNREADABLE';
 
 function readProjectSession(projectRoot: string): ProjectSessionHint | null {
   try {
@@ -103,24 +104,10 @@ function readProjectSession(projectRoot: string): ProjectSessionHint | null {
 }
 
 /**
- * WHICH PROJECT a `/__editor/project` body says its server is serving, and the
- * reason it cannot describe it.
- *
- * `serving` is the server's own statement of "I AM serving this project, I
- * just cannot describe it" — its manifest is unparseable or fails strict
- * validation. The route added it because a bare `{ project: null }` there is
- * indistinguishable from "no project open"; reading only `project.path`
- * reproduces that collapse on this side, and the cost is the worst kind of
- * wrong answer: this door refused a session that WAS open on the caller's
- * project with "no live editor session found … (N other live session(s) found,
- * but none open this project)" — sending the operator to start an editor that
- * was already running, with the real defect (their own manifest) never named.
- */
-
-/**
- * What the server on `port` says it serves — `undefined` when it did not
- * answer at all. One probe: the manifest failure arrives with the path, so
- * neither the hint path nor the refusal path pays a second round trip.
+ * Read project identity and manifest failure in one `/__editor/project` probe.
+ * A serving path identifies the project even when its manifest is unreadable;
+ * `project: null` without that path denotes no described project. Return
+ * `undefined` when the server does not answer successfully.
  */
 async function probeServedProject(
   port: number,
@@ -141,46 +128,26 @@ async function probeServedProject(
  * because the project's manifest does not load.
  *
  * A refusal, not an attach: with no readable manifest the editor page itself
- * renders its startup-error screen, so there is no editor and no game behind
- * this door to bind `{ editor, game, page, tools, session }` to. What changed
- * is only that it now says the true thing — the failing file and key — instead
- * of "no live editor session found", which sent operators to start an editor
- * that was already running while their actual defect went unnamed.
+ * renders its startup-error screen, so there is no editor behind this door to
+ * bind `{ editor, session }` to. It names the failing file and key, so an
+ * operator fixes the manifest rather than starting a second editor.
  */
-function manifestRefusal(projectRoot: string, manifestError: string): Error {
-  return new Error(
-    `@volter/live: the editor session for ${projectRoot} is live, but its volter.project.json does ` +
-      'not load, so there is no editor or game to drive — the editor page is showing this same ' +
-      `error. Fix the manifest and retry; the session recovers on save, no restart needed.\n${manifestError}`,
+function manifestRefusal(projectRoot: string, manifestError: string, port: number): Error {
+  return Object.assign(
+    new Error(
+      `@volter/live: the editor session for ${projectRoot} is live, but its volter.project.json does ` +
+        'not load, so there is no editor or project to drive — the editor page is showing this same ' +
+        `error. Fix the manifest and retry; the session recovers on save, no restart needed.\n${manifestError}`,
+    ),
+    // The session is still this project's, so a caller that only needs to END it (`close`) can.
+    { code: SESSION_MANIFEST_UNREADABLE, session: { port, projectRoot } },
   );
 }
 
 /**
- * Resolve `projectDir` (default `process.cwd()`) to the port of its already-
- * running the editor's `edit` command session. Throws a descriptive error (never hangs
- * indefinitely — bounded by `EDITOR_SESSION_DISCOVERY_TIMEOUT_MS`, and never
- * silently attaches to an unrelated project's session — see the module doc
- * above) when no volter.project.json is found, or no live session covers it.
- */
-/**
- * THE REFUSAL WHEN NOTHING MATCHED — and it says WHICH nothing.
- *
- * "No live editor session found … run the editor's `edit` command" used to be the answer to
- * four different states, only one of which it described. The other three sent
- * the operator to start an editor that was already running:
- *
- *  - discovery FAILED (a probe timeout under load) — nothing was learned, so
- *    "no session is running" is not a fact anyone established;
- *  - the registry was read and is genuinely empty — the one case the old text
- *    was right about;
- *  - sessions exist, but every one resolves to a different canonical path. In
- *    a repo worked through git worktrees this is the ORDINARY miss: two
- *    checkouts of the same project differ only in a path prefix, and a
- *    symlinked worktree's `realpath` diverges from the path the caller typed.
- *    Naming both sides is what makes it a two-second diagnosis instead of a
- *    hunt.
- *
- * Each branch prescribes only what its own state supports.
+ * Distinguish failed discovery, a readable empty registry and sessions serving
+ * other canonical paths. Include the requested and listed paths for a path
+ * mismatch; only a confirmed absence carries `NO_SESSION_FOR_PROJECT`.
  */
 function noMatchingSessionRefusal(
   projectRoot: string,
@@ -192,8 +159,10 @@ function noMatchingSessionRefusal(
     return new Error(
       `@volter/live: could not complete editor session discovery while looking for ${projectRoot} — ` +
         `${discoveryFailure}. This is not the answer "no editor is running": the question went ` +
-        'unanswered, so nothing is known about what is live. Retry (a probe can time out while ' +
-        `the box is loaded); if it keeps failing, ${sessionsCommandFor(projectRoot)} asks the same question directly.`,
+        'unanswered, so nothing is known about what is live. The step named above is the one that ' +
+        'did not answer: that session\'s server holds its port but did not reply to the request. ' +
+        'Its own log (logs/editor-<port>.log in the project it serves) says how far its start got; ' +
+        `${sessionsCommandFor(projectRoot)} asks the same question directly.`,
     );
   }
   if (sessions.length === 0) {
@@ -221,6 +190,12 @@ function noMatchingSessionRefusal(
   ), thisFolderElsewhere ? {} : { code: NO_SESSION_FOR_PROJECT });
 }
 
+/**
+ * Resolve `projectDir` (default `process.cwd()`) to its already-running editor
+ * session. Verify the project hint, then consult the shared registry, with
+ * each discovery probe bounded by `EDITOR_SESSION_DISCOVERY_TIMEOUT_MS`.
+ * Throw when no project manifest or matching live session is found.
+ */
 export async function resolveSession(
   projectDir: string = process.cwd(),
   deps: SessionResolutionDeps = {},
@@ -253,18 +228,15 @@ export async function resolveSession(
     } else {
       const served = await probeServedProject(localHint.port);
       if (served?.path != null && canonicalPath(served.path) === canonicalPath(projectRoot)) {
-        if (served.manifestError !== null) throw manifestRefusal(projectRoot, served.manifestError);
+        if (served.manifestError !== null) throw manifestRefusal(projectRoot, served.manifestError, localHint.port);
         return { port: localHint.port, projectRoot };
       }
     }
   }
 
   let sessions: EditorSessionInfo[];
-  // A FAILED discovery is not an empty one. Collapsing the two into `[]` is
-  // what made this door answer "no live editor session found" — and prescribe
-  // the editor's `edit` command — for a probe that merely timed out under load, sending the
-  // operator to start an editor that was already running while the real defect
-  // went unnamed. The same collapse the manifest refusal above was added for.
+  // Retain discovery failures separately from an empty session list so the
+  // refusal names an unanswered probe rather than claiming no session exists.
   let discoveryFailure: string | null = null;
   try {
     sessions = await withTimeout(
@@ -281,7 +253,7 @@ export async function resolveSession(
   const match = sessions.find((s) => s.project !== null && canonicalPath(s.project) === canon);
   if (!match) throw noMatchingSessionRefusal(projectRoot, canon, sessions, discoveryFailure);
 
-  if (match.manifestError != null) throw manifestRefusal(projectRoot, match.manifestError);
+  if (match.manifestError != null) throw manifestRefusal(projectRoot, match.manifestError, match.port);
 
   return { port: match.port, projectRoot };
 }

package/src/singleton.ts

@@ -1,19 +1,7 @@
-/**
- * A tiny memoized-async-factory primitive — the machinery behind
- * `index.ts`'s lazy top-level `editor`/`tools` singletons. Pulled into
- * its own module (rather than inlined) so it's independently unit-testable
- * with a fake factory, with no need to exercise a real `connect()` (session
- * discovery, network) just to prove "two accesses, one connect".
- *
- * Caches the in-flight PROMISE, not just the resolved value — two callers
- * racing `ensure()` before the first resolves still share the SAME
- * connection attempt, not two independent ones.
- */
+/** Memoized async connection. Concurrent ensure calls share the same in-flight promise. */
 export interface LazySession<T> {
   /** Returns the memoized promise, creating it via `factory()` on first call. */
   ensure(): Promise<T>;
-  /** Clears the memo — the NEXT `ensure()` calls `factory()` again. Exposed for tests (and for a caller that deliberately wants to reconnect); not needed in ordinary use. */
-  reset(): void;
 }
 
 export function createLazySession<T>(factory: () => Promise<T>): LazySession<T> {
@@ -23,8 +11,5 @@ export function createLazySession<T>(factory: () => Promise<T>): LazySession<T>
       promise ??= factory();
       return promise;
     },
-    reset(): void {
-      promise = null;
-    },
   };
 }

package/src/volter-manifest.ts

@@ -0,0 +1,97 @@
+import { readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { readPageEntry, readVolterContributions } from '@volter/sdk/volter-contributions';
+
+/**
+ * THE NODE READER of a package's `package.json` as Volter reads it: its name, its dependency
+ * names and its `contributes.volter` declarations, which `@volter/sdk/volter-contributions` reads as the workbench and
+ * the page read them. The build's product plugin, the session's catalog and
+ * serving doors, the shared-React scope and the pre-bundle crawl all read a package here, so a
+ * declaration means one thing everywhere it is read.
+ *
+ * It parses and does no policy. What an unusable declaration costs is the caller's to say: a
+ * product build refuses it, the catalog reports it as a load error, a scope decision treats it
+ * as no declaration. {@link declaredContributions} is the one test of "this package contributes".
+ */
+export interface VolterManifest {
+  /** The `package.json`, absolute. */
+  readonly path: string;
+  /** Its package's directory. */
+  readonly dir: string;
+  readonly name: string | null;
+  readonly version: string | null;
+  readonly private: boolean;
+  readonly bin: unknown;
+  /** Every name in `dependencies`, `devDependencies` and `optionalDependencies`, in that order,
+   *  each once. */
+  readonly dependencyNames: readonly string[];
+  /** `package.json#contributes.volter`, unchecked: the package's contribution modules, an object
+   *  keyed by kind, and its declarations (`serving`, `viewRoutes`, `product`). It is where Code-OSS's extension
+   *  service reads them too, through the kit's `volter` extension point. */
+  readonly contributions: unknown;
+  /** `package.json#contributes.languageModelTools`, unchecked: the agent tools Code-OSS registers from it. */
+  readonly languageModelTools: unknown;
+  /** `package.json#contributes.volter.product`, a product's declaration, read and checked by `product-locator.ts`;
+   *  `undefined` when the package declares none or it is not an object. */
+  readonly product: ProductDeclaration | undefined;
+}
+
+/** `package.json#contributes.volter.product`, as declared and unchecked. */
+export interface ProductDeclaration {
+  readonly entry?: unknown;
+  readonly composes?: unknown;
+  readonly colorTheme?: unknown;
+  readonly workbench?: unknown;
+  readonly displayName?: unknown;
+  readonly install?: unknown;
+  readonly upgrade?: unknown;
+  readonly adapterRequired?: unknown;
+}
+
+/** `path`'s manifest, or `null` when there is no file there or it is not a JSON object. */
+export function readVolterManifest(path: string): VolterManifest | null {
+  let json: unknown;
+  try {
+    json = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+  if (json === null || typeof json !== 'object' || Array.isArray(json)) return null;
+  const record = json as Record<string, unknown>;
+  const names = (key: string): string[] => {
+    const section = record[key];
+    return section !== null && typeof section === 'object' ? Object.keys(section) : [];
+  };
+  const contributes = record['contributes'];
+  const contributions = contributes !== null && typeof contributes === 'object' ? (contributes as Record<string, unknown>)['volter'] : undefined;
+  const declared = contributions !== null && typeof contributions === 'object' ? (contributions as Record<string, unknown>) : {};
+  const product = declared['product'];
+  return {
+    path,
+    dir: dirname(path),
+    name: typeof record['name'] === 'string' ? record['name'] : null,
+    version: typeof record['version'] === 'string' ? record['version'] : null,
+    private: record['private'] === true,
+    bin: record['bin'],
+    dependencyNames: [...new Set([...names('dependencies'), ...names('devDependencies'), ...names('optionalDependencies')])],
+    contributions,
+    languageModelTools: contributes !== null && typeof contributes === 'object' ? (contributes as Record<string, unknown>)['languageModelTools'] : undefined,
+    product: product !== null && typeof product === 'object' && !Array.isArray(product) ? (product as ProductDeclaration) : undefined,
+  };
+}
+
+/**
+ * The package's declared modules, each contribution's and its page half's, with why any entry is refused; `null` when
+ * it declares none (an absent `contributes.volter`, or one that is not an object). A package with the object, even an
+ * empty one, is a contributing package: its modules are editor-tree code.
+ */
+export function declaredContributions(manifest: VolterManifest | null): { readonly modules: readonly string[]; readonly errors: readonly string[] } | null {
+  const declared = manifest?.contributions;
+  if (declared === null || typeof declared !== 'object' || Array.isArray(declared)) return null;
+  const { entries, errors } = readVolterContributions(declared);
+  const page = readPageEntry(manifest?.name ?? manifest?.path ?? '', (declared as Record<string, unknown>)['page']);
+  return {
+    modules: [...entries.map(({ entry }) => entry), ...('entry' in page && page.entry !== null ? [page.entry] : [])],
+    errors: 'malformed' in page ? [...errors, page.malformed] : errors,
+  };
+}