@vgai/sdk 0.4.0-canary.20260715.0

package/src/errors.ts

@@ -0,0 +1,72 @@
+import type { z } from 'zod';
+
+/**
+ * Core, registry-level error codes — always available regardless of which
+ * operation was dispatched. Operation-specific codes are declared per
+ * operation on `OperationDefinition.errors` (see `registry.ts`).
+ */
+export const CORE_ERROR_CODES = {
+  /** `dispatch()` was called with a name no operation is registered under. */
+  OPERATION_NOT_FOUND: 'OPERATION_NOT_FOUND',
+  /** Input failed the operation's Zod input schema. */
+  INVALID_INPUT: 'INVALID_INPUT',
+  /** The impl's return value failed the operation's Zod result schema, or a
+   *  thrown OperationError's `data` failed its declared error-code schema —
+   *  either way, an implementation bug, not a caller bug. */
+  INVALID_OUTPUT: 'INVALID_OUTPUT',
+  /** The impl threw something that isn't a declared, structured error. */
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+} as const;
+
+export type CoreErrorCode = (typeof CORE_ERROR_CODES)[keyof typeof CORE_ERROR_CODES];
+
+/** A single Zod validation failure, reduced to a machine-readable shape. */
+export interface StructuredIssue {
+  path: (string | number | symbol)[];
+  message: string;
+  code: string;
+}
+
+/**
+ * The one error shape every `dispatch()` failure normalizes into. `code` is
+ * always machine-readable and always present — nothing in this codebase may
+ * identify an operation failure by parsing `message` prose (§8 B1 AC).
+ */
+export interface StructuredOperationError {
+  code: string;
+  message: string;
+  /** Present for INVALID_INPUT / INVALID_OUTPUT — the exact failing path(s). */
+  issues?: StructuredIssue[];
+  /** Present when the failing code declares a data schema (or the impl attached data). */
+  data?: unknown;
+}
+
+/**
+ * The only way an operation `impl` should signal an EXPECTED, contractual
+ * failure (as opposed to an unexpected bug/exception). `code` must be one
+ * the operation's `OperationDefinition.errors` declares — `dispatch()`
+ * cross-checks it and validates `data` against that code's schema, so an
+ * undeclared code or mismatched data is itself normalized into a structured
+ * error rather than silently forwarded (see `registry.ts`'s
+ * `normalizeThrown`).
+ */
+export class OperationError extends Error {
+  readonly code: string;
+  readonly data: unknown;
+
+  constructor(code: string, message: string, data?: unknown) {
+    super(message);
+    this.name = 'OperationError';
+    this.code = code;
+    this.data = data;
+  }
+}
+
+/** Reduce a `ZodError`'s issues to the structured, serializable shape above. */
+export function toStructuredIssues(issues: readonly z.ZodIssue[]): StructuredIssue[] {
+  return issues.map((issue) => ({
+    path: [...issue.path],
+    message: issue.message,
+    code: issue.code,
+  }));
+}

package/src/http/http-projection.ts

@@ -0,0 +1,349 @@
+/**
+ * HTTP projection of the operation registry (B8, §8 B8).
+ *
+ * The SAME `OperationRegistry` that backs the SDK (`dispatch`) and the CLI
+ * (`packages/vgai-cli/src/oclif/*`, B6) is projected here as a small HTTP
+ * server. Routes are GENERATED from `registry.listOperations()` — one route
+ * per operation — never hand-authored per op: adding an operation to the SDK
+ * gives it an HTTP route for free, exactly as it gives it a CLI subcommand
+ * for free (B6).
+ *
+ * ROUTE SHAPE — I project each operation as its own route, dotted-name under a
+ * base path (so `project.scene.read` is `POST /op/project.scene.read`):
+ *  - `POST <basePath>/<name>` — every operation. The JSON request BODY is the
+ *    operation input; it is validated by the op's Zod input schema INSIDE
+ *    `dispatch` (this module never re-implements validation — it hands the
+ *    body straight to the registry), so a bad body comes back as the SAME
+ *    `INVALID_INPUT` structured error the SDK and CLI produce.
+ *  - `GET <basePath>/<name>` — read-only operations only (`mutates: false`).
+ *    Input is taken from the `?input=<url-encoded-json>` query param (or `{}`
+ *    when absent). A GET against a mutating op is refused with a structured
+ *    `METHOD_NOT_ALLOWED` (a projection-level error — see `dispatchRoute`),
+ *    never silently executed.
+ *  - `GET <basePath>` — a machine-readable MANIFEST of every route: name,
+ *    allowed methods, summary/description, the Zod-derived JSON Schema for the
+ *    input, and the declared error codes. This is the HTTP analogue of MCP's
+ *    `tools/list` and is built from the very same `listOperations()` summaries.
+ *
+ * OUTCOME SHAPE: every response body is the registry's own
+ * `OperationOutcome` — `{ ok: true, data }` or `{ ok: false, error }` with a
+ * machine-readable `error.code` — byte-for-byte the shape the SDK returns and
+ * the CLI prints under `--json`. The HTTP STATUS is a secondary, best-effort
+ * signal derived from that code (`httpStatusForOutcome`); the authoritative,
+ * cross-projection-identical fact is always `error.code` in the body (§8 B8
+ * AC: "HTTP and MCP return the same structured error codes as SDK and CLI").
+ *
+ * CONTEXT: an operation's `OperationContext` (projectRoot, editorUrl, an
+ * injected editor transport for tests, ...) is produced per request by the
+ * caller-supplied `createContext(req)` (or the static `context`), so the same
+ * server can serve one project or resolve the project per request — the SDK
+ * package itself stays free of any cwd/env policy (that lives in the CLI).
+ */
+
+import type { IncomingMessage, Server, ServerResponse } from 'node:http';
+import { createServer } from 'node:http';
+import { z } from 'zod';
+import { CORE_ERROR_CODES } from '../errors.js';
+import { operations as defaultRegistry } from '../index.js';
+import type { OperationOutcome, OperationRegistry, OperationSummary } from '../registry.js';
+import type { OperationContext } from '../types.js';
+
+/** Options for building the HTTP projection handler/server. */
+export interface HttpProjectionOptions {
+  /** Registry to project. Defaults to the shared `operations` registry (same one the CLI uses). */
+  registry?: OperationRegistry;
+  /**
+   * URL prefix every operation route lives under. Default `/op`, so
+   * `project.scene.read` is `POST /op/project.scene.read`. No trailing slash.
+   */
+  basePath?: string;
+  /** Static context handed to every `dispatch`. Ignored when `createContext` is given. */
+  context?: OperationContext;
+  /** Per-request context factory (wins over `context`) — e.g. resolve `projectRoot` from a header. */
+  createContext?: (req: IncomingMessage) => OperationContext | Promise<OperationContext>;
+}
+
+/** One entry of the `GET <basePath>` manifest — the HTTP analogue of an MCP tool descriptor. */
+export interface HttpRouteDescriptor {
+  name: string;
+  methods: string[];
+  path: string;
+  summary: string;
+  description: string;
+  mutates: boolean;
+  supportsDryRun: boolean;
+  host: string;
+  requires: OperationSummary['requires'];
+  permission: OperationSummary['permission'];
+  /** Zod-derived JSON Schema for the request body / `?input=` — same conversion MCP tool schemas use. */
+  inputSchema: unknown;
+  errorCodes: string[];
+}
+
+/** Convert an operation's Zod input schema to JSON Schema — the repo's established `z.toJSONSchema` call (see `scripts/generate-schema.ts`). */
+export function inputJsonSchema(summary: OperationSummary): unknown {
+  return z.toJSONSchema(summary.input, { unrepresentable: 'any' });
+}
+
+/** Build the `GET <basePath>` manifest from `listOperations()` — routes are derived, never hand-written. */
+export function buildRouteManifest(
+  registry: OperationRegistry,
+  basePath: string,
+): HttpRouteDescriptor[] {
+  return registry
+    .listOperations()
+    .map((op) => ({
+      name: op.name,
+      methods: op.mutates ? ['POST'] : ['GET', 'POST'],
+      path: `${basePath}/${op.name}`,
+      summary: op.summary,
+      description: op.description,
+      mutates: op.mutates,
+      supportsDryRun: op.supportsDryRun,
+      host: op.host,
+      requires: op.requires,
+      permission: op.permission,
+      inputSchema: inputJsonSchema(op),
+      errorCodes: op.errors.map((e) => e.code),
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** A projection-level (not `dispatch`) failure, still shaped as an `OperationOutcome` so every response body is uniform. */
+function failure(code: string, message: string, data?: unknown): OperationOutcome {
+  return { ok: false, error: { code, message, ...(data !== undefined ? { data } : {}) } };
+}
+
+/**
+ * Map an `OperationOutcome` to an HTTP status. Best-effort ONLY — the
+ * authoritative, cross-projection-identical signal is `error.code` in the
+ * body, not this status. Success is 200; a handful of well-known core codes
+ * get their conventional status; every other structured failure defaults to
+ * 400 (a caller-actionable problem) rather than 500.
+ */
+export function httpStatusForOutcome(outcome: OperationOutcome): number {
+  if (outcome.ok) return 200;
+  switch (outcome.error.code) {
+    case CORE_ERROR_CODES.OPERATION_NOT_FOUND:
+      return 404;
+    case 'METHOD_NOT_ALLOWED':
+      return 405;
+    case CORE_ERROR_CODES.INTERNAL_ERROR:
+    case CORE_ERROR_CODES.INVALID_OUTPUT:
+      return 500;
+    case 'EDITOR_NOT_RUNNING':
+    case 'NO_PROJECT_ROOT':
+      return 503;
+    default:
+      return 400;
+  }
+}
+
+interface ParsedRoute {
+  name: string;
+  method: string;
+  /** Raw input object parsed from body (POST) or `?input=` (GET); `undefined` when none supplied. */
+  input: unknown;
+  /** A parse error to short-circuit with, if the body/query was malformed. */
+  parseError?: string;
+}
+
+/** Read a request body as a UTF-8 string, capped so a projection server can't be trivially flooded. */
+function readBody(req: IncomingMessage, limitBytes = 5_000_000): Promise<string> {
+  return new Promise((resolvePromise, reject) => {
+    const chunks: Buffer[] = [];
+    let total = 0;
+    req.on('data', (chunk: Buffer) => {
+      total += chunk.length;
+      if (total > limitBytes) {
+        reject(new Error(`request body exceeds ${limitBytes} bytes`));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => resolvePromise(Buffer.concat(chunks).toString('utf-8')));
+    req.on('error', (err) => reject(err));
+  });
+}
+
+/** Parse the input object for a route from either the POST body or the GET `?input=` query param. */
+async function parseRouteInput(
+  req: IncomingMessage,
+  method: string,
+  url: URL,
+): Promise<{ input: unknown } | { parseError: string }> {
+  if (method === 'GET') {
+    const raw = url.searchParams.get('input');
+    if (raw === null) return { input: {} };
+    try {
+      return { input: JSON.parse(raw) };
+    } catch (err) {
+      return {
+        parseError: `?input= is not valid JSON: ${err instanceof Error ? err.message : err}`,
+      };
+    }
+  }
+  // POST (and any other method that carries a body).
+  let body: string;
+  try {
+    body = await readBody(req);
+  } catch (err) {
+    return { parseError: err instanceof Error ? err.message : String(err) };
+  }
+  const trimmed = body.trim();
+  if (trimmed === '') return { input: {} };
+  try {
+    return { input: JSON.parse(trimmed) };
+  } catch (err) {
+    return {
+      parseError: `request body is not valid JSON: ${err instanceof Error ? err.message : err}`,
+    };
+  }
+}
+
+/**
+ * The pure routing core, exported for tests: given a method, pathname and
+ * already-parsed input, resolve the target operation and dispatch it —
+ * returning the `OperationOutcome` and the HTTP status, with no `http`
+ * objects involved. `serveHttpRequest` is the thin I/O wrapper around this.
+ */
+export async function dispatchRoute(
+  registry: OperationRegistry,
+  basePath: string,
+  route: ParsedRoute,
+  ctx: OperationContext,
+): Promise<OperationOutcome> {
+  if (route.parseError !== undefined) {
+    // A malformed body is a caller input problem — surface it as the SAME
+    // INVALID_INPUT code the SDK/CLI use for a schema rejection.
+    return failure(CORE_ERROR_CODES.INVALID_INPUT, route.parseError);
+  }
+
+  const def = registry.getOperation(route.name);
+  if (!def) {
+    return failure(
+      CORE_ERROR_CODES.OPERATION_NOT_FOUND,
+      `No operation is registered as "${route.name}".`,
+      { name: route.name },
+    );
+  }
+
+  if (route.method === 'GET' && def.mutates) {
+    return failure(
+      'METHOD_NOT_ALLOWED',
+      `"${route.name}" mutates state; use POST ${basePath}/${route.name}.`,
+      { name: route.name, allowed: ['POST'] },
+    );
+  }
+
+  return registry.dispatch(route.name, route.input, ctx);
+}
+
+/** Send an `OperationOutcome` as a JSON response with the derived status. */
+function sendOutcome(res: ServerResponse, outcome: OperationOutcome): void {
+  const body = `${JSON.stringify(outcome)}\n`;
+  res.writeHead(httpStatusForOutcome(outcome), { 'content-type': 'application/json' });
+  res.end(body);
+}
+
+/** Resolve the per-request `OperationContext` from the options (static or factory). */
+async function resolveHttpContext(
+  options: HttpProjectionOptions,
+  req: IncomingMessage,
+): Promise<OperationContext> {
+  if (options.createContext) return options.createContext(req);
+  if (options.context) return options.context;
+  return {};
+}
+
+/** The full request lifecycle, factored out of the returned closure to keep each step flat. */
+async function handleProjectionRequest(
+  options: HttpProjectionOptions,
+  registry: OperationRegistry,
+  basePath: string,
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<void> {
+  const url = new URL(req.url ?? '/', 'http://localhost');
+  const method = (req.method ?? 'GET').toUpperCase();
+  const pathname = url.pathname.replace(/\/$/, '') || '/';
+
+  // GET <basePath> -> the route manifest (tools/list analogue).
+  if (pathname === basePath && method === 'GET') {
+    const manifest = buildRouteManifest(registry, basePath);
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(`${JSON.stringify({ ok: true, data: { basePath, operations: manifest } })}\n`);
+    return;
+  }
+
+  const prefix = `${basePath}/`;
+  if (!pathname.startsWith(prefix)) {
+    sendOutcome(
+      res,
+      failure(
+        CORE_ERROR_CODES.OPERATION_NOT_FOUND,
+        `No route matches ${method} ${pathname}. Operation routes live under ${prefix}.`,
+      ),
+    );
+    return;
+  }
+
+  const name = pathname.slice(prefix.length);
+  const parsed = await parseRouteInput(req, method, url);
+  const route: ParsedRoute =
+    'parseError' in parsed
+      ? { name, method, input: undefined, parseError: parsed.parseError }
+      : { name, method, input: parsed.input };
+
+  let ctx: OperationContext;
+  try {
+    ctx = await resolveHttpContext(options, req);
+  } catch (err) {
+    sendOutcome(
+      res,
+      failure(
+        CORE_ERROR_CODES.INTERNAL_ERROR,
+        `createContext threw: ${err instanceof Error ? err.message : err}`,
+      ),
+    );
+    return;
+  }
+
+  sendOutcome(res, await dispatchRoute(registry, basePath, route, ctx));
+}
+
+/**
+ * Handle one HTTP request against the projection. Exported so it can be
+ * mounted on an existing `http.Server`/framework, but `createHttpProjectionServer`
+ * is the turnkey path.
+ */
+export function createHttpProjectionHandler(
+  options: HttpProjectionOptions = {},
+): (req: IncomingMessage, res: ServerResponse) => void {
+  const registry = options.registry ?? defaultRegistry;
+  const basePath = (options.basePath ?? '/op').replace(/\/$/, '');
+
+  return (req: IncomingMessage, res: ServerResponse): void => {
+    handleProjectionRequest(options, registry, basePath, req, res).catch((err) => {
+      // Last-resort guard: nothing above should throw, but never leave a
+      // socket hanging — a hung projection would be worse than a 500.
+      if (!res.headersSent) {
+        sendOutcome(
+          res,
+          failure(
+            CORE_ERROR_CODES.INTERNAL_ERROR,
+            `unhandled projection error: ${err instanceof Error ? err.message : err}`,
+          ),
+        );
+      } else {
+        res.end();
+      }
+    });
+  };
+}
+
+/** Build (but do not start) an `http.Server` that serves the registry projection. Call `.listen(port)`. */
+export function createHttpProjectionServer(options: HttpProjectionOptions = {}): Server {
+  return createServer(createHttpProjectionHandler(options));
+}

package/src/http/index.ts

@@ -0,0 +1,11 @@
+/** HTTP projection of the operation registry (B8, §8 B8). See `./http-projection.ts`. */
+export {
+  buildRouteManifest,
+  createHttpProjectionHandler,
+  createHttpProjectionServer,
+  dispatchRoute,
+  type HttpProjectionOptions,
+  type HttpRouteDescriptor,
+  httpStatusForOutcome,
+  inputJsonSchema,
+} from './http-projection.js';

package/src/index.ts

@@ -0,0 +1,67 @@
+export * from './cinematic/index.js';
+export * from './editor/index.js';
+export {
+  CORE_ERROR_CODES,
+  type CoreErrorCode,
+  OperationError,
+  type StructuredIssue,
+  type StructuredOperationError,
+  toStructuredIssues,
+} from './errors.js';
+export * from './http/index.js';
+export * from './mcp/index.js';
+export {
+  ProjectStatusInput,
+  ProjectStatusResult,
+  projectStatus,
+  registerBuiltinOperations,
+} from './operations.js';
+export * from './play/index.js';
+export * from './project/index.js';
+export {
+  defineOperation,
+  type ErrorDefinition,
+  type OperationDefinition,
+  type OperationOutcome,
+  OperationRegistry,
+  type OperationSummary,
+} from './registry.js';
+export * from './render/index.js';
+export {
+  type ExecutionHost,
+  type ExecutionRequirements,
+  OPERATION_NAMESPACES,
+  type OperationContext,
+  type OperationNamespace,
+  type PermissionMetadata,
+  type PermissionRisk,
+} from './types.js';
+
+import { registerCinematicOperations } from './cinematic/index.js';
+import { registerEditorOperations } from './editor/index.js';
+import { registerBuiltinOperations } from './operations.js';
+import { registerPlayOperations } from './play/index.js';
+import { registerProjectOperations } from './project/index.js';
+import { OperationRegistry } from './registry.js';
+
+/**
+ * Build a fresh registry preloaded with B1's sample operations plus B2's
+ * real `project.*` operations, B3's real `editor.*` operations, B4's real
+ * `play.*` operations, and B5's real `cinematic.*` operations. Deliberately
+ * separate register calls (not one function grown to cover all five) —
+ * `registerBuiltinOperations` is B1's own registration function, and its
+ * registry test asserts exactly what it registers; growing it here would
+ * break that assertion for a reason unrelated to what it actually tests.
+ */
+export function createOperationRegistry(): OperationRegistry {
+  const registry = new OperationRegistry();
+  registerBuiltinOperations(registry);
+  registerProjectOperations(registry);
+  registerEditorOperations(registry);
+  registerPlayOperations(registry);
+  registerCinematicOperations(registry);
+  return registry;
+}
+
+/** Convenience default registry — the same one CLI/HTTP/MCP projections (B6-B8) will build on. */
+export const operations = createOperationRegistry();

package/src/mcp/index.ts

@@ -0,0 +1,16 @@
+/** MCP projection of the operation registry (B8, §8 B8). See `./mcp-projection.ts`. */
+export {
+  createMcpProjection,
+  isResourceEligible,
+  type JsonRpcRequest,
+  type JsonRpcResponse,
+  MCP_RESOURCE_PREFIX,
+  type McpProjection,
+  type McpProjectionOptions,
+  type McpResource,
+  type McpTool,
+  operationToResource,
+  operationToTool,
+  outcomeToToolResult,
+  toolInputSchema,
+} from './mcp-projection.js';