@volter/live 0.5.211 → 0.5.213

package/src/registry-format.ts

@@ -0,0 +1,248 @@
+/**
+ * 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.
+ *
+ * The registry is also the CREDENTIAL FILE for the owner's own processes: each entry carries its session's
+ * connection token, and `sessionFetch` is how a process on this machine reaches a session with it, as a Code-OSS
+ * client reads its server's `--connection-token-file` (`src/vs/server/node/serverConnectionToken.ts:62-79` in the
+ * `volter-ai/code-oss` fork). The file is the user's alone (0600, written by the session).
+ */
+
+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;
+  /** The session's connection token, which every request to it carries (`sessionFetch`). Never returned by a
+   *  session route; it is in this user-private file and in the page's cookie. */
+  connectionToken?: 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['connectionToken']) &&
+    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,
+    connectionToken: session.connectionToken ?? 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 [];
+  }
+}
+
+/**
+ * The cookie the session reads its connection token from: Code-OSS's own (`connectionTokenCookieName`,
+ * `src/vs/base/common/network.ts:187`). The page's Code-OSS server sets it on the page's host from the address's
+ * `?tkn=` (`src/vs/server/node/webClientServer.ts:313-336`), and the session's routes share that host through its
+ * proxy and the token through the project's token file, so one cookie carries both.
+ */
+export const CONNECTION_TOKEN_COOKIE = 'vscode-tkn';
+
+/** The connection token of the live session listening on `port` of this machine, from its entry; null when no live
+ *  session there registered one. */
+export function registeredConnectionToken(port: number): string | null {
+  return readLiveRegisteredSessions().find((session) => session.port === port)?.connectionToken ?? null;
+}
+
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]']);
+
+/** The port of a session `url` names on this machine, or null for any other address. */
+function loopbackSessionPort(url: string | URL): number | null {
+  const target = new URL(url);
+  return target.protocol === 'http:' && LOOPBACK_HOSTS.has(target.hostname) && target.port !== '' ? Number(target.port) : null;
+}
+
+/** `init` with the connection token of the session `url` names, as the cookie the session reads. Only a loopback
+ *  address gets one, and only a registered session's: the token never leaves this machine. */
+export function withSessionToken(url: string | URL, init: RequestInit = {}): RequestInit {
+  const port = loopbackSessionPort(url);
+  const token = port === null ? null : registeredConnectionToken(port);
+  if (token === null) return init;
+  const headers = new Headers(init.headers);
+  headers.set('cookie', `${CONNECTION_TOKEN_COOKIE}=${token}`);
+  return { ...init, headers };
+}
+
+/**
+ * Say why a session on this machine refused (403) a request this process could send it no token with: its registry
+ * entry, the one place the owner's processes read the token from, is missing or carries none. Throws that; returns
+ * when the refusal is something else (a token was sent, or the address is not a local session's).
+ */
+export function refuseWithoutRegisteredToken(url: string | URL, status: number): void {
+  if (status !== 403) return;
+  const port = loopbackSessionPort(url);
+  if (port === null || registeredConnectionToken(port) !== null) return;
+  throw new Error(
+    `The editor session on port ${port} refused this request: its connection token could not be read, because the ` +
+      `session registry ${EDITOR_SESSIONS_REGISTRY_FILE} has no live entry for port ${port} carrying one. The session ` +
+      "says why its entry could not be written in its terminal and on its console, and writes it again every minute.",
+  );
+}
+
+/** `fetch` to a session on this machine, carrying its connection token (`withSessionToken`). Every request a process
+ *  of the owner's makes to a session goes through here or through `EditorClient`, which does the same, and a refusal
+ *  for want of the token says so (`refuseWithoutRegisteredToken`). */
+export async function sessionFetch(url: string | URL, init?: RequestInit): Promise<Response> {
+  const response = await fetch(url, withSessionToken(url, init));
+  refuseWithoutRegisteredToken(url, response.status);
+  return response;
+}
+
+/** 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,20 +1,17 @@
-/** 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. */
+/** Resolve an existing session for exactly one project, from 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 { existsSync, realpathSync, statSync } from 'node:fs';
+import { dirname, 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,
   type SessionListingTransport as SessionDiscoveryTransport,
   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 {
@@ -42,17 +39,6 @@ export interface SessionResolutionDeps {
   transport?: SessionListingTransport;
   /** Project-root discovery — defaults to the real fs walk (`findProjectRootFrom` above). Overridable for tests. */
   findProjectRootFrom?: (dir: string) => string | null;
-  /** Project-local session hint reader. Defaults to `.volter/session.json`. */
-  readProjectSession?: (projectRoot: string) => ProjectSessionHint | null;
-  /** Exact-session verifier. Defaults to GET /__editor/project + canonical project matching. */
-  verifyProjectSession?: (hint: ProjectSessionHint, projectRoot: string) => Promise<boolean>;
-}
-
-export interface ProjectSessionHint {
-  port: number;
-  pid: number;
-  url: string;
-  startedAt: string;
 }
 
 function canonicalPath(path: string): string {
@@ -78,109 +64,34 @@ 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';
-
-function readProjectSession(projectRoot: string): ProjectSessionHint | null {
-  try {
-    const value: unknown = JSON.parse(
-      readFileSync(join(projectRoot, '.volter', 'session.json'), 'utf8'),
-    );
-    if (typeof value !== 'object' || value === null) return null;
-    const hint = value as Record<string, unknown>;
-    if (
-      typeof hint['port'] !== 'number' ||
-      !Number.isInteger(hint['port']) ||
-      hint['port'] <= 0 ||
-      typeof hint['pid'] !== 'number' ||
-      typeof hint['url'] !== 'string' ||
-      typeof hint['startedAt'] !== 'string'
-    ) {
-      return null;
-    }
-    return hint as unknown as ProjectSessionHint;
-  } catch {
-    return 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.
- */
-async function probeServedProject(
-  port: number,
-): Promise<{ path: string | null; manifestError: string | null } | undefined> {
-  try {
-    const response = await fetch(`http://127.0.0.1:${port}/__editor/project`, {
-      signal: AbortSignal.timeout(EDITOR_SESSION_DISCOVERY_TIMEOUT_MS),
-    });
-    if (!response.ok) return undefined;
-    return servedProjectAnswer(await response.json());
-  } catch {
-    return undefined;
-  }
-}
+/** 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';
 
 /**
  * The refusal for a session that IS this project's and cannot be driven,
  * 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 +103,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 +134,12 @@ function noMatchingSessionRefusal(
   ), thisFolderElsewhere ? {} : { code: NO_SESSION_FOR_PROJECT });
 }
 
+/**
+ * Resolve `projectDir` (default `process.cwd()`) to its already-running editor
+ * session from 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 = {},
@@ -235,36 +154,9 @@ export async function resolveSession(
     );
   }
 
-  // The editor writes this exact-project hint at boot and removes it on
-  // shutdown. Prefer it over a global all-session scan: it is both faster and
-  // immune to an unrelated slow/dead registry entry consuming the discovery
-  // deadline. The live probe remains authoritative, so a stale file cannot
-  // attach us to the wrong project or port.
-  const localHint = (deps.readProjectSession ?? readProjectSession)(projectRoot);
-  if (localHint) {
-    // `deps.verifyProjectSession` is the test-only override and keeps its
-    // boolean meaning: "this hint is this project's session, and healthy".
-    // With no override we read the probe ourselves, because the same response
-    // carries WHY a served project cannot be described.
-    if (deps.verifyProjectSession) {
-      if (await deps.verifyProjectSession(localHint, projectRoot)) {
-        return { port: localHint.port, projectRoot };
-      }
-    } 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);
-        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 +173,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,
+  };
+}