@vgai/live 0.4.0-canary.20260715.0

package/src/session.ts

@@ -0,0 +1,135 @@
+/**
+ * Session resolution for `connect()` (`index.ts`) — turns a project
+ * directory into `{ port, projectRoot }` for an ALREADY-RUNNING `vgai edit`
+ * session. `@vgai/live` never starts or stops a session (see the module doc
+ * on `index.ts`); this only finds one.
+ *
+ * Two pieces, from two different sources:
+ *
+ *  1. Live-session DISCOVERY + PROBING (`HttpEditorTransport.listSessions`,
+ *     `withTimeout`, `EDITOR_SESSION_DISCOVERY_TIMEOUT_MS`) — reused
+ *     directly from `@vgai/sdk`'s `editor/transport.ts` (B3,
+ *     `resolveEditorSession`'s own sibling machinery). That module is a
+ *     real, tested, PUBLICLY EXPORTED part of `@vgai/sdk` — reading
+ *     `~/.vgai/editor-sessions.json`, PID-liveness-filtering it, and
+ *     verifying each survivor with a live `GET /__editor/project` probe is
+ *     exactly the hard, easy-to-get-subtly-wrong part worth reusing rather
+ *     than re-deriving.
+ *
+ *  2. Project-root discovery (`findProjectRootFrom` below) — LIFTED (not
+ *     imported) from `packages/vgai-cli/src/project-root.ts`. `@vgai/sdk`'s
+ *     `resolveEditorSession` takes an already-known `ctx.projectRoot`; it has
+ *     no "walk up from an arbitrary cwd to find the nearest vgai.game.json"
+ *     step of its own, which `connect(projectDir?)` needs. `@vgai/cli` is
+ *     `"private": true` with no `exports` field to import through (and
+ *     depending on it from here would invert the intended CLI -> SDK ->
+ *     engine direction anyway — see `@vgai/sdk`'s own architecture note),
+ *     so this ~10-line pure function is duplicated verbatim instead. Keep in
+ *     sync if that logic ever changes.
+ *
+ * DELIBERATE DIVERGENCE from `resolveEditorSession` itself: that function's
+ * documented precedence (see its own doc comment) falls back to "the
+ * lowest-numbered port among ALL live sessions" when `ctx.projectRoot` is
+ * given but matches none of them — a reasonable default for a single-agent,
+ * usually-one-session tool context. `@vgai/live` explicitly does NOT reuse
+ * that fallback: CLAUDE.md's editor-first workflow is emphatic that a
+ * project must never be silently retargeted to a DIFFERENT project's editor
+ * session (a real hazard in a multi-project/fleet setup — several unrelated
+ * `vgai edit` sessions can easily be running at once). `resolveSession`
+ * below matches the CLI's own stricter `getClient()` behavior instead: only
+ * a session whose OWN project matches `projectRoot` is ever returned: no
+ * match means a clear, actionable error, never a guess.
+ */
+
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import {
+  EDITOR_SESSION_DISCOVERY_TIMEOUT_MS,
+  type EditorSessionInfo,
+  type EditorTransport,
+  HttpEditorTransport,
+  withTimeout,
+} from '@vgai/sdk';
+
+/**
+ * Lifted verbatim from `packages/vgai-cli/src/project-root.ts` (see this
+ * module's doc comment above for why it's duplicated rather than imported).
+ * Nearest ancestor of `dir` (inclusive) containing a `vgai.game.json`, or
+ * `null` if none.
+ */
+export function findProjectRootFrom(dir: string): string | null {
+  let cur = resolve(dir);
+  for (;;) {
+    if (existsSync(join(cur, 'vgai.game.json'))) return cur;
+    const parent = dirname(cur);
+    if (parent === cur) return null;
+    cur = parent;
+  }
+}
+
+/** The minimal slice of `EditorTransport` `resolveSession` actually needs — narrower than the full interface so a test double only has to implement one method. */
+export type SessionListingTransport = Pick<EditorTransport, 'listSessions'>;
+
+export interface ResolvedSession {
+  /** Editor dev-server port the resolved session is listening on. */
+  port: number;
+  /** Absolute project root — the nearest ancestor of the requested directory containing `vgai.game.json`. */
+  projectRoot: string;
+}
+
+export interface SessionResolutionDeps {
+  /** Session listing + liveness verification — defaults to a real `HttpEditorTransport` (`@vgai/sdk`). Overridable for tests. */
+  transport?: SessionListingTransport;
+  /** Project-root discovery — defaults to the real fs walk (`findProjectRootFrom` above). Overridable for tests. */
+  findProjectRootFrom?: (dir: string) => string | null;
+}
+
+/**
+ * Resolve `projectDir` (default `process.cwd()`) to the port of its already-
+ * running `vgai edit` 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 vgai.game.json is found, or no live session covers it.
+ */
+export async function resolveSession(
+  projectDir: string = process.cwd(),
+  deps: SessionResolutionDeps = {},
+): Promise<ResolvedSession> {
+  const findRoot = deps.findProjectRootFrom ?? findProjectRootFrom;
+  const transport = deps.transport ?? new HttpEditorTransport();
+
+  const projectRoot = findRoot(projectDir);
+  if (projectRoot === null) {
+    throw new Error(
+      `@vgai/live: no vgai.game.json found in ${projectDir} or any parent directory — is this a vgai project?`,
+    );
+  }
+
+  let sessions: EditorSessionInfo[];
+  try {
+    sessions = await withTimeout(
+      transport.listSessions(EDITOR_SESSION_DISCOVERY_TIMEOUT_MS),
+      EDITOR_SESSION_DISCOVERY_TIMEOUT_MS,
+      'editor session discovery',
+    );
+  } catch {
+    sessions = [];
+  }
+
+  const canon = resolve(projectRoot);
+  const match = sessions.find((s) => s.project !== null && resolve(s.project) === canon);
+  if (!match) {
+    const otherCount = sessions.length;
+    throw new Error(
+      `@vgai/live: no live editor session found for ${projectRoot}. @vgai/live only attaches to ` +
+        'an already-running session — it never starts one — so run `vgai edit` in that project ' +
+        'first, then retry.' +
+        (otherCount > 0
+          ? ` (${otherCount} other live session(s) found, but none open this project — @vgai/live ` +
+            'never silently attaches to a different project.)'
+          : ''),
+    );
+  }
+
+  return { port: match.port, projectRoot };
+}

package/src/singleton.ts

@@ -0,0 +1,30 @@
+/**
+ * A tiny memoized-async-factory primitive — the machinery behind
+ * `index.ts`'s lazy top-level `editor`/`game`/`page` 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.
+ */
+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> {
+  let promise: Promise<T> | null = null;
+  return {
+    ensure(): Promise<T> {
+      promise ??= factory();
+      return promise;
+    },
+    reset(): void {
+      promise = null;
+    },
+  };
+}