@vgai/sdk 0.5.2 → 0.5.3

package/src/project/scene-operations.ts

@@ -1,426 +0,0 @@
-/**
- * `project.scene.*` (B2, §8 B2 "scene read/validate/diff/apply").
- *
- * REUSE, not reimplementation: every op here calls straight into the engine's
- * existing scene machinery — `parseSceneFile`/`SceneParseError`
- * (`@vgai/engine/scene/parse`), `applyDiff`/`ApplyDiffError`
- * (`@vgai/engine/scene/scene-apply`), and `SceneDiffSchema`
- * (`@vgai/engine/scene/scene-diff-schema`) — the exact same functions
- * `vgai apply-diff` (`packages/vgai-cli/src/apply-diff.ts`) already uses. This
- * module only adds the operation-registry envelope (dry-run, external-change
- * detection, files-changed) around that reused core; it does not reimplement
- * scene patching or validation.
- *
- * `project.scene.diff` (mutates:false) previews what a patch WOULD do —
- * applies it in memory, re-validates the result, reports what would change —
- * WITHOUT ever writing. `project.scene.apply` (mutates:true,
- * supportsDryRun:true) is the real (or dry-run) write.
- */
-
-import { existsSync } from 'node:fs';
-import { dereferenceNewAssetRefs } from '@vgai/engine/scene/asset-ref-check';
-import { parseSceneFile, SceneParseError } from '@vgai/engine/scene/parse';
-import { ApplyDiffError, applyDiff } from '@vgai/engine/scene/scene-apply';
-import { SceneDiffSchema } from '@vgai/engine/scene/scene-diff-schema';
-import type { SceneFile } from '@vgai/engine/scene/scene-types';
-import { z } from 'zod';
-import { ToolError } from '../errors.js';
-import { defineTool, type ToolRegistry } from '../registry.js';
-import {
-  BaseHashField,
-  CONFLICT_ERROR,
-  checkNotStale,
-  DryRunField,
-  FILE_NOT_FOUND_ERROR,
-  mutationResultSchema,
-  NO_PROJECT_ROOT_ERROR,
-  PATH_OUTSIDE_PROJECT_ERROR,
-  readFileWithHash,
-  requireProjectRoot,
-  resolveProjectPath,
-  writeFileAtomic,
-} from './shared.js';
-
-/** Format Zod/scene-parse issues the same one-line-per-issue shape the CLI uses. */
-export function formatIssues(issues: { path: PropertyKey[]; message: string }[]): string[] {
-  return issues.map((i) => `${i.path.join('.')}: ${i.message}`);
-}
-
-export const SCENE_INVALID_ERROR = {
-  code: 'SCENE_INVALID',
-  summary: 'The scene file/document fails schema validation.',
-  data: z.object({ issues: z.array(z.string()) }),
-} as const;
-
-export const APPLY_DIFF_FAILED_ERROR = {
-  code: 'APPLY_DIFF_FAILED',
-  summary: 'applyDiff rejected the patch (bad id, bad parent, duplicate id, etc).',
-  data: z.object({
-    opIndex: z.number(),
-    opType: z.string(),
-    entityId: z.string(),
-    message: z.string(),
-  }),
-} as const;
-
-/**
- * B6 follow-up to B2 #20: `project.scene.apply` now shares the SAME
- * asset-reference integrity check `vgai apply-diff` has always run
- * (`@vgai/engine/scene/asset-ref-check`'s `dereferenceNewAssetRefs`) — a
- * patch that introduces a `materialRef`/file-path `prefab`/binary reference
- * to a missing or schema-invalid file is refused BEFORE any write, exactly
- * like the CLI verb, so the two writers can never silently diverge in what
- * they guarantee. (`animation.animGraph` was one such checked ref until E5
- * removed the AnimGraph format entirely — an authored `animGraph` now fails
- * earlier, at scene parse, via the removal-migration guard.)
- */
-export const ASSET_REF_INVALID_ERROR = {
-  code: 'ASSET_REF_INVALID',
-  summary:
-    'The patch introduces one or more asset references (materialRef/prefab/binary) ' +
-    'that are missing on disk or fail their own schema — refused before any write.',
-  data: z.object({
-    errors: z.array(
-      z.object({
-        field: z.string(),
-        path: z.string(),
-        diskPath: z.string(),
-        reason: z.string(),
-      }),
-    ),
-  }),
-} as const;
-
-/** Read + Zod-parse a scene file at `scenePath` (project-relative), returning both the raw hash and the validated document. */
-export function readAndParseScene(
-  projectRoot: string,
-  scenePath: string,
-): { absPath: string; hash: string; scene: SceneFile } {
-  const absPath = resolveProjectPath(projectRoot, scenePath);
-  const { raw, hash } = readFileWithHash(absPath);
-  let json: unknown;
-  try {
-    json = JSON.parse(raw);
-  } catch (err) {
-    throw new ToolError(
-      'SCENE_INVALID',
-      `${scenePath} is not valid JSON: ${err instanceof Error ? err.message : err}`,
-      {
-        issues: [String(err)],
-      },
-    );
-  }
-  try {
-    const scene = parseSceneFile(json, scenePath);
-    return { absPath, hash, scene };
-  } catch (err) {
-    if (err instanceof SceneParseError) {
-      throw new ToolError('SCENE_INVALID', err.message, { issues: formatIssues(err.issues) });
-    }
-    throw err;
-  }
-}
-
-/** Apply `patch` to `scene`, mapping `ApplyDiffError` into the declared `APPLY_DIFF_FAILED` shape. */
-export function applyDiffOrThrow(
-  scene: SceneFile,
-  patch: z.infer<typeof SceneDiffSchema>,
-): SceneFile {
-  try {
-    return applyDiff(scene, patch);
-  } catch (err) {
-    if (err instanceof ApplyDiffError) {
-      throw new ToolError('APPLY_DIFF_FAILED', err.message, {
-        opIndex: err.opIndex,
-        opType: err.opType,
-        entityId: err.entityId,
-        message: err.message,
-      });
-    }
-    throw err;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// project.scene.read
-// ---------------------------------------------------------------------------
-
-const ProjectSceneReadInput = z
-  .object({ scenePath: z.string().describe('Project-relative path to a .vscn.json scene file.') })
-  .describe('Read + validate a scene file.');
-
-const ProjectSceneReadResult = z
-  .object({
-    scenePath: z.string(),
-    contentHash: z
-      .string()
-      .describe('sha256 of the raw file bytes — pass as baseHash to a later mutation.'),
-    scene: z.unknown().describe('The validated scene document (SceneFile).'),
-  })
-  .describe('Scene read result.');
-
-export const projectSceneRead = defineTool({
-  name: 'project.scene.read',
-  summary: 'Read + validate a .vscn.json scene file.',
-  description:
-    'Reuses @vgai/engine/scene/parse’s parseSceneFile — the same validator the runtime loader uses.',
-  input: ProjectSceneReadInput,
-  result: ProjectSceneReadResult,
-  errors: [
-    NO_PROJECT_ROOT_ERROR,
-    PATH_OUTSIDE_PROJECT_ERROR,
-    FILE_NOT_FOUND_ERROR,
-    SCENE_INVALID_ERROR,
-  ],
-  requires: { project: true },
-  host: 'node',
-  mutates: false,
-  supportsDryRun: false,
-  permission: { risk: 'read', summary: 'Reads one scene file; no writes.' },
-  async impl(input, ctx) {
-    const projectRoot = requireProjectRoot(ctx);
-    const { absPath, hash, scene } = readAndParseScene(projectRoot, input.scenePath);
-    return { scenePath: absPath, contentHash: hash, scene };
-  },
-});
-
-// ---------------------------------------------------------------------------
-// project.scene.validate
-// ---------------------------------------------------------------------------
-
-const ProjectSceneValidateInput = z
-  .object({
-    scenePath: z
-      .string()
-      .optional()
-      .describe('Validate this project-relative scene file instead of `scene`.'),
-    scene: z
-      .unknown()
-      .optional()
-      .describe('Validate this raw document instead of reading `scenePath`.'),
-  })
-  .describe('Exactly one of scenePath/scene must be given.');
-
-const ProjectSceneValidateResult = z
-  .object({ valid: z.boolean(), issues: z.array(z.string()) })
-  .describe('Structured validation result — never throws for a malformed scene.');
-
-export const projectSceneValidate = defineTool({
-  name: 'project.scene.validate',
-  summary: 'Validate a scene file or raw scene document against the real scene schema.',
-  description:
-    'Reuses parseSceneFile/SceneParseError. Never throws for a malformed document — failures come back as structured issues.',
-  input: ProjectSceneValidateInput,
-  result: ProjectSceneValidateResult,
-  errors: [
-    NO_PROJECT_ROOT_ERROR,
-    PATH_OUTSIDE_PROJECT_ERROR,
-    {
-      code: 'BAD_INPUT',
-      summary: 'Neither scenePath nor scene was given.',
-      data: z.object({}),
-    },
-  ],
-  requires: { project: true },
-  host: 'node',
-  mutates: false,
-  supportsDryRun: false,
-  permission: {
-    risk: 'read',
-    summary: 'Reads a scene file (or validates a given document); no writes.',
-  },
-  async impl(input, ctx) {
-    let json: unknown;
-    if (input.scene !== undefined) {
-      json = input.scene;
-    } else if (input.scenePath !== undefined) {
-      const projectRoot = requireProjectRoot(ctx);
-      const absPath = resolveProjectPath(projectRoot, input.scenePath);
-      if (!existsSync(absPath)) {
-        return { valid: false, issues: [`File not found: ${absPath}`] };
-      }
-      json = JSON.parse(readFileWithHash(absPath).raw);
-    } else {
-      throw new ToolError('BAD_INPUT', 'One of scenePath or scene must be given.', {});
-    }
-
-    try {
-      parseSceneFile(json, input.scenePath);
-      return { valid: true, issues: [] };
-    } catch (err) {
-      if (err instanceof SceneParseError) return { valid: false, issues: formatIssues(err.issues) };
-      return { valid: false, issues: [err instanceof Error ? err.message : String(err)] };
-    }
-  },
-});
-
-// ---------------------------------------------------------------------------
-// project.scene.diff — preview only, never writes (mutates:false).
-// ---------------------------------------------------------------------------
-
-const ProjectSceneDiffInput = z
-  .object({
-    scenePath: z.string().describe('Project-relative path to the base .vscn.json scene file.'),
-    patch: SceneDiffSchema,
-  })
-  .describe('Preview applying `patch` to the scene at scenePath — computed only, never written.');
-
-const ProjectSceneDiffResult = z
-  .object({
-    wouldBeValid: z.boolean(),
-    issues: z.array(z.string()),
-    opCounts: z.object({
-      add: z.number(),
-      remove: z.number(),
-      update: z.number(),
-      move: z.number(),
-    }),
-    entitiesTouched: z.array(z.string()),
-  })
-  .describe('What applying this patch would do — no write, ever.');
-
-export const projectSceneDiff = defineTool({
-  name: 'project.scene.diff',
-  summary: 'Preview a SceneDiff patch against a scene file without writing anything.',
-  description:
-    'Reuses applyDiff in memory + re-validates the result via parseSceneFile — identical logic to project.scene.apply, minus the write.',
-  input: ProjectSceneDiffInput,
-  result: ProjectSceneDiffResult,
-  errors: [
-    NO_PROJECT_ROOT_ERROR,
-    PATH_OUTSIDE_PROJECT_ERROR,
-    FILE_NOT_FOUND_ERROR,
-    SCENE_INVALID_ERROR,
-  ],
-  requires: { project: true },
-  host: 'node',
-  mutates: false,
-  supportsDryRun: false,
-  permission: {
-    risk: 'read',
-    summary: 'Reads a scene file; computes a hypothetical result; never writes.',
-  },
-  async impl(input, ctx) {
-    const projectRoot = requireProjectRoot(ctx);
-    const { scene } = readAndParseScene(projectRoot, input.scenePath);
-
-    const opCounts = { add: 0, remove: 0, update: 0, move: 0 };
-    const entitiesTouched: string[] = [];
-    for (const op of input.patch.ops) {
-      opCounts[op.type]++;
-      entitiesTouched.push(op.type === 'add' ? (op.entity.id ?? '(auto-generated)') : op.id);
-    }
-
-    try {
-      const result = applyDiffOrThrow(scene, input.patch);
-      parseSceneFile(result, input.scenePath);
-      return { wouldBeValid: true, issues: [], opCounts, entitiesTouched };
-    } catch (err) {
-      const message =
-        err instanceof ToolError
-          ? err.message
-          : err instanceof SceneParseError
-            ? err.message
-            : err instanceof Error
-              ? err.message
-              : String(err);
-      return { wouldBeValid: false, issues: [message], opCounts, entitiesTouched };
-    }
-  },
-});
-
-// ---------------------------------------------------------------------------
-// project.scene.apply — the real (or dry-run) write.
-// ---------------------------------------------------------------------------
-
-const ProjectSceneApplyInput = z
-  .object({
-    scenePath: z.string().describe('Project-relative path to the .vscn.json scene file to modify.'),
-    patch: SceneDiffSchema,
-    dryRun: DryRunField,
-    baseHash: BaseHashField,
-  })
-  .describe('Apply a SceneDiff patch to a scene file.');
-
-const ProjectSceneApplyResult = mutationResultSchema(
-  z
-    .object({ scene: z.unknown() })
-    .describe('The scene document after the patch (or that WOULD result).'),
-);
-
-export const projectSceneApply = defineTool({
-  name: 'project.scene.apply',
-  summary: 'Apply a SceneDiff patch to a scene file — dry-run capable, conflict-checked.',
-  description:
-    'Reuses applyDiff (@vgai/engine/scene/scene-apply) exactly as `vgai apply-diff` does: re-' +
-    'validates the result via parseSceneFile before ever writing, refuses a stale write ' +
-    '(CONFLICT) when baseHash no longer matches, and never writes when dryRun is true.',
-  input: ProjectSceneApplyInput,
-  result: ProjectSceneApplyResult,
-  errors: [
-    NO_PROJECT_ROOT_ERROR,
-    PATH_OUTSIDE_PROJECT_ERROR,
-    FILE_NOT_FOUND_ERROR,
-    SCENE_INVALID_ERROR,
-    APPLY_DIFF_FAILED_ERROR,
-    CONFLICT_ERROR,
-    ASSET_REF_INVALID_ERROR,
-  ],
-  requires: { project: true },
-  host: 'node',
-  mutates: true,
-  supportsDryRun: true,
-  permission: { risk: 'write', summary: 'Writes the target scene file.' },
-  async impl(input, ctx) {
-    const projectRoot = requireProjectRoot(ctx);
-    const { absPath, hash, scene } = readAndParseScene(projectRoot, input.scenePath);
-    checkNotStale(absPath, hash, input.baseHash);
-
-    const result = applyDiffOrThrow(scene, input.patch);
-    try {
-      parseSceneFile(result, input.scenePath);
-    } catch (err) {
-      if (err instanceof SceneParseError) {
-        throw new ToolError(
-          'SCENE_INVALID',
-          `applyDiff produced a scene that fails validation: ${err.message}`,
-          { issues: formatIssues(err.issues) },
-        );
-      }
-      throw err;
-    }
-
-    // Shared asset-ref integrity check (B6 / B2 #20) — refuse BEFORE any
-    // write (dry-run or real) exactly like `vgai apply-diff`.
-    const refErrors = dereferenceNewAssetRefs(scene, result, absPath);
-    if (refErrors.length > 0) {
-      throw new ToolError(
-        'ASSET_REF_INVALID',
-        `The patch introduces ${refErrors.length} broken asset reference(s): ` +
-          refErrors.map((e) => `${e.field} -> "${e.path}": ${e.reason}`).join('; '),
-        { errors: refErrors },
-      );
-    }
-
-    const dryRun = input.dryRun ?? false;
-    if (!dryRun) {
-      writeFileAtomic(absPath, `${JSON.stringify(result, null, 2)}\n`);
-    }
-
-    return {
-      dryRun,
-      written: !dryRun,
-      filesChanged: [absPath],
-      before: { scene },
-      after: { scene: result },
-    };
-  },
-});
-
-/** Register every B2 `project.scene.*` operation onto `registry`. */
-export function registerSceneOperations(registry: ToolRegistry): void {
-  registry.register(projectSceneRead);
-  registry.register(projectSceneValidate);
-  registry.register(projectSceneDiff);
-  registry.register(projectSceneApply);
-}