@vgai/sdk 0.4.0-canary.20260715.0

package/src/project/shared.ts

@@ -0,0 +1,299 @@
+/**
+ * Shared plumbing for B2's `project.*` operations
+ * (docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §8 B2).
+ *
+ * Every `project.*` op is file-native (host: 'node', requires: { project: true })
+ * and runs with NO editor process — it resolves `ctx.projectRoot`, reads/writes
+ * plain files on disk, and reuses the engine's existing Zod schemas +
+ * `applyDiff` for anything scene-shaped (see `../../../engine/src/scene/scene-apply.ts`).
+ *
+ * Two cross-cutting decisions (pinned by the B2 task brief) live here so every
+ * operation module applies them identically:
+ *
+ *  - DRY-RUN: every mutation's input carries an optional `dryRun` field
+ *    (`DryRunInputShape`). When true, the impl computes the same
+ *    before/after/filesChanged summary as a real write but returns before
+ *    ever calling `writeFileAtomic` — `MutationEnvelope.written` is `false`
+ *    and the file(s) on disk are provably unchanged (round-tripped by tests).
+ *  - EXTERNAL-CHANGE DETECTION: every mutation's input carries an optional
+ *    `baseHash` field (`BaseHashInputShape`) — the `contentHash` a prior
+ *    `read`-shaped op returned. `checkNotStale` compares it against the hash
+ *    of the file's CURRENT on-disk content (read fresh, inside the mutating
+ *    op, right before the write decision) and throws the declared `CONFLICT`
+ *    error on mismatch — the file changed between the caller's read and this
+ *    write. Omitting `baseHash` skips the check (an agent that never read the
+ *    file first has nothing to compare against; this mirrors optimistic-
+ *    concurrency/ETag conventions, not a hidden requirement).
+ */
+
+import { createHash } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, isAbsolute, join, normalize, relative } from 'node:path';
+import type { SceneEntity } from '@vgai/engine/scene/scene-types';
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import type { ErrorDefinition } from '../registry.js';
+import type { OperationContext } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// Project-root resolution
+// ---------------------------------------------------------------------------
+
+export const NO_PROJECT_ROOT_ERROR: ErrorDefinition = {
+  code: 'NO_PROJECT_ROOT',
+  summary: 'dispatch() was called without ctx.projectRoot.',
+  data: z.object({}).describe('No additional data.'),
+};
+
+/** Every `project.*` op needs `ctx.projectRoot` — this is the one place that enforces it. */
+export function requireProjectRoot(ctx: OperationContext): string {
+  if (!ctx.projectRoot) {
+    throw new OperationError(
+      'NO_PROJECT_ROOT',
+      'dispatch() was called without ctx.projectRoot.',
+      {},
+    );
+  }
+  return ctx.projectRoot;
+}
+
+export const PATH_OUTSIDE_PROJECT_ERROR: ErrorDefinition = {
+  code: 'PATH_OUTSIDE_PROJECT',
+  summary: 'A given relative path escapes ctx.projectRoot (e.g. via "..").',
+  data: z.object({ projectRoot: z.string(), path: z.string() }),
+};
+
+/**
+ * Resolve a project-relative path against `projectRoot`, rejecting absolute
+ * paths and any `..` escape — every `project.*` op that takes a path input
+ * (scene/manifest/input-map/asset) goes through this so an op can never be
+ * pointed outside the project directory.
+ */
+export function resolveProjectPath(projectRoot: string, relativePath: string): string {
+  if (isAbsolute(relativePath)) {
+    throw new OperationError(
+      'PATH_OUTSIDE_PROJECT',
+      `"${relativePath}" must be project-relative, not absolute.`,
+      {
+        projectRoot,
+        path: relativePath,
+      },
+    );
+  }
+  const resolved = normalize(join(projectRoot, relativePath));
+  const rel = relative(projectRoot, resolved);
+  if (rel === '..' || rel.startsWith(`..${'/'}`) || isAbsolute(rel)) {
+    throw new OperationError(
+      'PATH_OUTSIDE_PROJECT',
+      `"${relativePath}" escapes the project root.`,
+      {
+        projectRoot,
+        path: relativePath,
+      },
+    );
+  }
+  return resolved;
+}
+
+// ---------------------------------------------------------------------------
+// Content hashing / atomic write / conflict detection
+// ---------------------------------------------------------------------------
+
+export function sha256Hex(content: string): string {
+  return createHash('sha256').update(content, 'utf-8').digest('hex');
+}
+
+export interface FileRead {
+  raw: string;
+  hash: string;
+}
+
+export const FILE_NOT_FOUND_ERROR: ErrorDefinition = {
+  code: 'FILE_NOT_FOUND',
+  summary: 'The referenced project file does not exist on disk.',
+  data: z.object({ path: z.string() }),
+};
+
+/** Read a file's raw text + its content hash. Throws the declared `FILE_NOT_FOUND` shape when absent. */
+export function readFileWithHash(absPath: string): FileRead {
+  if (!existsSync(absPath)) {
+    throw new OperationError('FILE_NOT_FOUND', `File not found: ${absPath}`, { path: absPath });
+  }
+  const raw = readFileSync(absPath, 'utf-8');
+  return { raw, hash: sha256Hex(raw) };
+}
+
+/** Write `content` to `absPath`, creating parent directories, via a temp-file + rename so a reader never observes a partial write. */
+export function writeFileAtomic(absPath: string, content: string): void {
+  const dir = dirname(absPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const tmp = join(dir, `.${Date.now()}-${process.pid}-${Math.random().toString(36).slice(2)}.tmp`);
+  writeFileSync(tmp, content, 'utf-8');
+  renameSync(tmp, absPath);
+}
+
+export const CONFLICT_ERROR: ErrorDefinition = {
+  code: 'CONFLICT',
+  summary:
+    'The target file changed on disk since it was last read (baseHash mismatch) — the write ' +
+    'was refused rather than silently clobbering the external change.',
+  data: z.object({ path: z.string(), expectedHash: z.string(), actualHash: z.string() }),
+};
+
+/**
+ * External-change detection (see module jsdoc). `actualHash` is the hash of
+ * what THIS op just read from disk; `baseHash` is the caller-supplied hash
+ * from a prior read. A mismatch means something wrote to the file in
+ * between — refuse rather than clobber.
+ */
+export function checkNotStale(
+  path: string,
+  actualHash: string,
+  baseHash: string | undefined,
+): void {
+  if (baseHash !== undefined && actualHash !== baseHash) {
+    throw new OperationError(
+      'CONFLICT',
+      `"${path}" changed on disk since it was last read (baseHash mismatch) — refusing to overwrite an external change.`,
+      { path, expectedHash: baseHash, actualHash },
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Shared Zod input fragments
+// ---------------------------------------------------------------------------
+
+export const DryRunField = z
+  .boolean()
+  .optional()
+  .describe(
+    'When true, compute the before/after summary and the files that WOULD change, but write ' +
+      'nothing to disk. Defaults to false (a real write).',
+  );
+
+export const BaseHashField = z
+  .string()
+  .optional()
+  .describe(
+    'The `contentHash` a prior read-shaped op returned for this file. When given, the write is ' +
+      "refused with a CONFLICT error if the file's current on-disk content hash no longer " +
+      'matches (external-change detection). Omit to skip the check.',
+  );
+
+/** The envelope every mutation op's result carries, parameterized by the op's own `after` shape. */
+export function mutationResultSchema<T extends z.ZodType>(afterSchema: T) {
+  return z.object({
+    dryRun: z.boolean().describe('True when this call computed the change without writing it.'),
+    written: z.boolean().describe('True iff bytes were actually written to disk this call.'),
+    filesChanged: z
+      .array(z.string())
+      .describe('Absolute path(s) written (dryRun:false) or that WOULD be written (dryRun:true).'),
+    before: z.unknown().describe('Summary of the relevant state before this change.'),
+    after: afterSchema.describe(
+      'Summary of the relevant state after this change (or that WOULD result).',
+    ),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Scene entity tree walk (read-side helper shared by entity/component ops)
+// ---------------------------------------------------------------------------
+
+export const ENTITY_NOT_FOUND_ERROR: ErrorDefinition = {
+  code: 'ENTITY_NOT_FOUND',
+  summary: 'No entity with the given id exists in the scene.',
+  data: z.object({ id: z.string() }),
+};
+
+/** Depth-first search for an entity by its stable `id` — the SAME identity `applyDiff` addresses by (never an array index). */
+export function findEntityById(entities: SceneEntity[], id: string): SceneEntity | undefined {
+  for (const e of entities) {
+    if (e.id === id) return e;
+    if (e.children) {
+      const found = findEntityById(e.children, id);
+      if (found) return found;
+    }
+  }
+  return undefined;
+}
+
+/** Require an entity by id, throwing the declared `ENTITY_NOT_FOUND` shape otherwise. */
+export function requireEntityById(entities: SceneEntity[], id: string): SceneEntity {
+  const found = findEntityById(entities, id);
+  if (!found) {
+    throw new OperationError(
+      'ENTITY_NOT_FOUND',
+      `No entity with id "${id}" exists in this scene.`,
+      { id },
+    );
+  }
+  return found;
+}
+
+// ---------------------------------------------------------------------------
+// Project-wide file discovery (shared by project.discover / story / theatre /
+// xstate discovery ops — all "find files matching X under the project" ops).
+// ---------------------------------------------------------------------------
+
+/** Directories never worth descending into for project-content discovery. */
+const SKIP_DIR_NAMES = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'dist-server',
+  '.vgai',
+  '.ci-scaffold',
+]);
+
+/**
+ * Recursively list every file under `projectRoot` for which `matches(relPath)`
+ * is true, returning POSIX-style project-relative paths, sorted. Used for
+ * best-effort discovery ops (stories/Theatre project state/XState machines) —
+ * a plain filename-pattern walk, not a build-tool glob dependency.
+ */
+/** `readdirSync`, swallowing a race/permission error into `[]` (a directory that vanished mid-walk is not this function's problem). */
+function safeReaddir(dir: string): string[] {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+/** `statSync(...).isDirectory()`, swallowing a race/permission error into `false` (skip, don't crash the whole walk). */
+function safeIsDirectory(abs: string): boolean {
+  try {
+    return statSync(abs).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function listProjectFiles(
+  projectRoot: string,
+  matches: (relPath: string) => boolean,
+): string[] {
+  const out: string[] = [];
+  function walk(dir: string): void {
+    for (const name of safeReaddir(dir)) {
+      const abs = join(dir, name);
+      if (safeIsDirectory(abs)) {
+        if (!SKIP_DIR_NAMES.has(name)) walk(abs);
+        continue;
+      }
+      const rel = relative(projectRoot, abs).split('\\').join('/');
+      if (matches(rel)) out.push(rel);
+    }
+  }
+  walk(projectRoot);
+  return out.sort();
+}

package/src/registry.ts

@@ -0,0 +1,285 @@
+import type { z } from 'zod';
+import {
+  CORE_ERROR_CODES,
+  OperationError,
+  type StructuredOperationError,
+  toStructuredIssues,
+} from './errors.js';
+import {
+  type ExecutionHost,
+  type ExecutionRequirements,
+  OPERATION_NAMESPACES,
+  type OperationContext,
+  type OperationNamespace,
+  type PermissionMetadata,
+} from './types.js';
+
+/** One declared, machine-readable failure mode of an operation (§8 B1: "structured error codes and data schemas"). */
+export interface ErrorDefinition<TCode extends string = string> {
+  code: TCode;
+  /** One-line human summary of when this code fires — for docs/help text, never parsed by callers. */
+  summary: string;
+  /** Optional schema for this code's `data` payload. When present, `dispatch()` validates a thrown OperationError's data against it. */
+  data?: z.ZodType;
+}
+
+/**
+ * One operation, fully self-describing: identity, both schemas, every
+ * declared failure mode, where/how it runs, and its own implementation.
+ * Built via `defineOperation` (below), which validates the name shape and
+ * error-code uniqueness at definition time.
+ */
+export interface OperationDefinition<
+  TInput extends z.ZodType = z.ZodType,
+  TResult extends z.ZodType = z.ZodType,
+  TErrorCode extends string = string,
+> {
+  /** Fully qualified dotted name, e.g. "project.scene.read" (§5.7 namespaces). */
+  name: string;
+  /** Short, one-line summary (for CLI help / listOperations tables). */
+  summary: string;
+  /** Longer prose description of behavior, side effects, and caveats. */
+  description: string;
+  /** Zod schema every `dispatch()` input is validated against before `impl` runs. */
+  input: TInput;
+  /** Zod schema every `impl` return value is validated against before `dispatch()` succeeds. */
+  result: TResult;
+  /** Every structured failure mode this operation may raise via `OperationError`. */
+  errors: ReadonlyArray<ErrorDefinition<TErrorCode>>;
+  /** Which live contexts this operation needs (project/editor/play/render). */
+  requires: ExecutionRequirements;
+  /** Which of the three hosts this operation executes on (node / editor-browser / runtime-page). */
+  host: ExecutionHost;
+  /** True if this operation writes/changes state (files, editor, runtime). */
+  mutates: boolean;
+  /** True if this operation supports a dry-run mode (mutations only, meaningful subset). */
+  supportsDryRun: boolean;
+  /** True for jobs that must not ride a short request/response timeout (e.g. `cinematic.render` on the editor relay). */
+  longRunning?: boolean;
+  /** Coarse permission/risk metadata for gated callers (agents, HTTP/MCP auth). */
+  permission: PermissionMetadata;
+  /** The actual implementation. Receives already-schema-validated input. */
+  impl: (input: z.infer<TInput>, ctx: OperationContext) => Promise<z.infer<TResult>>;
+}
+
+/** `listOperations()`'s element shape — every field of `OperationDefinition` except `impl`, so enumerating never risks invoking anything. */
+export type OperationSummary<
+  TInput extends z.ZodType = z.ZodType,
+  TResult extends z.ZodType = z.ZodType,
+  TErrorCode extends string = string,
+> = Omit<OperationDefinition<TInput, TResult, TErrorCode>, 'impl'>;
+
+const NAME_PATTERN = /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$/;
+
+function namespaceOf(name: string): string {
+  const dot = name.indexOf('.');
+  return dot === -1 ? name : name.slice(0, dot);
+}
+
+/**
+ * Typed helper that builds an `OperationDefinition`. Pure and synchronous —
+ * it does not touch a registry (so it can never itself throw "duplicate
+ * name"; that check happens at `OperationRegistry.register`, which has the
+ * cross-operation state to detect it) — but it DOES validate the two things
+ * that are decidable from the definition alone: the name is a valid dotted
+ * `namespace.rest` string under one of the four operation namespaces
+ * (§5.7), and no two declared error codes on the same operation collide.
+ *
+ * Exists mainly for type inference: it pins `impl`'s parameter/return types
+ * to `z.infer<TInput>` / `z.infer<TResult>` so a mismatched implementation
+ * fails to compile rather than failing at runtime.
+ */
+export function defineOperation<
+  TInput extends z.ZodType,
+  TResult extends z.ZodType,
+  TErrorCode extends string = string,
+>(
+  def: OperationDefinition<TInput, TResult, TErrorCode>,
+): OperationDefinition<TInput, TResult, TErrorCode> {
+  if (!NAME_PATTERN.test(def.name)) {
+    throw new Error(
+      `defineOperation: "${def.name}" is not a valid dotted operation name ` +
+        '(expected e.g. "project.scene.read" — lowercase-leading segments joined by dots).',
+    );
+  }
+  const ns = namespaceOf(def.name);
+  if (!(OPERATION_NAMESPACES as readonly string[]).includes(ns)) {
+    throw new Error(
+      `defineOperation: "${def.name}" has unknown namespace "${ns}" — expected one of ` +
+        `${OPERATION_NAMESPACES.join(', ')} (§5.7).`,
+    );
+  }
+  const seen = new Set<string>();
+  for (const err of def.errors) {
+    if (seen.has(err.code)) {
+      throw new Error(
+        `defineOperation: "${def.name}" declares duplicate error code "${err.code}".`,
+      );
+    }
+    seen.add(err.code);
+  }
+  return def;
+}
+
+/** `dispatch()`'s result — a discriminated union, never a thrown exception, so every projection (CLI/HTTP/MCP) gets one uniform JSON-able shape for both success and failure. */
+export type OperationOutcome<TResult = unknown> =
+  | { ok: true; data: TResult }
+  | { ok: false; error: StructuredOperationError };
+
+/**
+ * Normalize whatever an `impl` threw into a `StructuredOperationError`.
+ * Three cases:
+ *  1. A declared `OperationError` whose code IS in `def.errors` and whose
+ *     `data` (if the code declares a schema) validates — forwarded as-is,
+ *     `data` replaced by its *parsed* form.
+ *  2. A declared code whose `data` fails its own schema — that is itself an
+ *     implementation bug, surfaced as INVALID_OUTPUT (never silently
+ *     forwarding unvalidated data).
+ *  3. Anything else — an `OperationError` with an undeclared code, a plain
+ *     `Error`, or a non-Error throw — normalized into INTERNAL_ERROR. The
+ *     raw exception/message is tucked into `data.message`, never used as
+ *     the identifying `code`.
+ */
+function normalizeThrown(def: OperationDefinition, err: unknown): StructuredOperationError {
+  if (err instanceof OperationError) {
+    const declared = def.errors.find((e) => e.code === err.code);
+    if (!declared) {
+      return {
+        code: CORE_ERROR_CODES.INTERNAL_ERROR,
+        message: `"${def.name}" threw undeclared error code "${err.code}".`,
+        data: { undeclaredCode: err.code, message: err.message },
+      };
+    }
+    if (declared.data) {
+      const parsed = declared.data.safeParse(err.data);
+      if (!parsed.success) {
+        return {
+          code: CORE_ERROR_CODES.INVALID_OUTPUT,
+          message:
+            `"${def.name}" threw declared code "${err.code}" but its data failed that ` +
+            "code's own schema.",
+          issues: toStructuredIssues(parsed.error.issues),
+        };
+      }
+      return { code: err.code, message: err.message, data: parsed.data };
+    }
+    return {
+      code: err.code,
+      message: err.message,
+      ...(err.data !== undefined ? { data: err.data } : {}),
+    };
+  }
+
+  const message = err instanceof Error ? err.message : String(err);
+  return {
+    code: CORE_ERROR_CODES.INTERNAL_ERROR,
+    message: `"${def.name}" threw an unstructured exception.`,
+    data: { message },
+  };
+}
+
+function toSummary(def: OperationDefinition): OperationSummary {
+  const { impl: _impl, ...summary } = def;
+  return summary;
+}
+
+/**
+ * The one registry of operation definitions (§8 B1). Holds definitions
+ * keyed by their fully-qualified name; `register` rejects a duplicate name
+ * outright (names are unique and stable per the AC), `listOperations`
+ * enumerates metadata without ever touching `impl`, and `dispatch` is the
+ * single validated call path: input schema -> impl -> result schema, with
+ * every failure normalized into `StructuredOperationError`.
+ */
+export class OperationRegistry {
+  private readonly definitions = new Map<string, OperationDefinition>();
+
+  /** Register a definition. Throws synchronously on a duplicate name — names are unique and stable by construction, not by convention. */
+  register<TInput extends z.ZodType, TResult extends z.ZodType, TErrorCode extends string>(
+    def: OperationDefinition<TInput, TResult, TErrorCode>,
+  ): void {
+    if (this.definitions.has(def.name)) {
+      throw new Error(
+        `OperationRegistry.register: "${def.name}" is already registered — operation names ` +
+          'must be unique and stable.',
+      );
+    }
+    this.definitions.set(def.name, def as unknown as OperationDefinition);
+  }
+
+  /** Enumerate every registered operation's metadata. Never invokes `impl`. */
+  listOperations(): OperationSummary[] {
+    return [...this.definitions.values()].map(toSummary);
+  }
+
+  /** Look up one operation's full definition (including `impl`) by name, or `undefined`. */
+  getOperation(name: string): OperationDefinition | undefined {
+    return this.definitions.get(name);
+  }
+
+  has(name: string): boolean {
+    return this.definitions.has(name);
+  }
+
+  /**
+   * Validate `input` against the named operation's input schema, run its
+   * `impl`, validate the return value against its result schema, and return
+   * a uniform `OperationOutcome` — success or a `StructuredOperationError`.
+   * Never throws for an expected failure (unknown name, bad input, impl
+   * throw, bad output); those are exactly what this method exists to turn
+   * into a machine-readable result instead of an exception a caller has to
+   * parse prose out of.
+   */
+  async dispatch<TResult = unknown>(
+    name: string,
+    input: unknown,
+    ctx: OperationContext = {},
+  ): Promise<OperationOutcome<TResult>> {
+    const def = this.definitions.get(name);
+    if (!def) {
+      return {
+        ok: false,
+        error: {
+          code: CORE_ERROR_CODES.OPERATION_NOT_FOUND,
+          message: `No operation is registered as "${name}".`,
+          data: { name },
+        },
+      };
+    }
+
+    const parsedInput = def.input.safeParse(input);
+    if (!parsedInput.success) {
+      return {
+        ok: false,
+        error: {
+          code: CORE_ERROR_CODES.INVALID_INPUT,
+          message: `Input for "${name}" failed schema validation.`,
+          issues: toStructuredIssues(parsedInput.error.issues),
+        },
+      };
+    }
+
+    let rawResult: unknown;
+    try {
+      rawResult = await def.impl(parsedInput.data, ctx);
+    } catch (err) {
+      return { ok: false, error: normalizeThrown(def, err) };
+    }
+
+    const parsedResult = def.result.safeParse(rawResult);
+    if (!parsedResult.success) {
+      return {
+        ok: false,
+        error: {
+          code: CORE_ERROR_CODES.INVALID_OUTPUT,
+          message: `Result of "${name}" failed schema validation (implementation bug).`,
+          issues: toStructuredIssues(parsedResult.error.issues),
+        },
+      };
+    }
+
+    return { ok: true, data: parsedResult.data as TResult };
+  }
+}
+
+export type { ExecutionHost, ExecutionRequirements, OperationContext, OperationNamespace };