@vgai/sdk 0.4.0-canary.20260715.0

package/src/project/asset-operations.ts

@@ -0,0 +1,243 @@
+/**
+ * `project.asset.*` (B2, §8 B2 "asset list/import/inspect" — "list + inspect
+ * real, import may be minimal").
+ *
+ * Asset root convention: `<projectRoot>/public` — the same convention every
+ * scaffolded project and `apply-diff.ts`'s `findAssetRoot` use (scene/asset
+ * paths are web-root-relative; Vite serves a project's `public/` directory at
+ * that root — see `packages/editor/template/public/`).
+ */
+
+import { copyFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { dirname, extname, join } from 'node:path';
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import {
+  DryRunField,
+  mutationResultSchema,
+  NO_PROJECT_ROOT_ERROR,
+  PATH_OUTSIDE_PROJECT_ERROR,
+  readFileWithHash,
+  requireProjectRoot,
+  resolveProjectPath,
+} from './shared.js';
+
+const PUBLIC_DIR = 'public';
+
+/** Small text/data files get a content hash too; large/binary files are identified by size alone (hashing a multi-MB texture on every list() would be wasteful). */
+const HASHABLE_MAX_BYTES = 256 * 1024;
+
+// ---------------------------------------------------------------------------
+// project.asset.list
+// ---------------------------------------------------------------------------
+
+const ProjectAssetListInput = z.object({
+  subdir: z
+    .string()
+    .optional()
+    .describe(
+      'List only under this public/-relative subdirectory (default: the whole public/ dir).',
+    ),
+});
+
+const AssetEntrySchema = z.object({
+  path: z
+    .string()
+    .describe('public/-relative path (the same convention scene asset references use).'),
+  size: z.number().describe('File size in bytes.'),
+  ext: z.string().describe('Lowercased file extension including the leading dot, or "" if none.'),
+});
+
+export const projectAssetList = defineOperation({
+  name: 'project.asset.list',
+  summary: 'List every file under the project’s public/ asset root (or a subdirectory of it).',
+  description:
+    'Read-only recursive listing, public/-relative paths (the same convention scene mesh/material/audio references use).',
+  input: ProjectAssetListInput,
+  result: z.object({ assets: z.array(AssetEntrySchema) }),
+  errors: [NO_PROJECT_ROOT_ERROR, PATH_OUTSIDE_PROJECT_ERROR],
+  requires: { project: true },
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Reads directory listings under public/; no writes.' },
+  async impl(input, ctx) {
+    const projectRoot = requireProjectRoot(ctx);
+    const startRel = input.subdir ? join(PUBLIC_DIR, input.subdir) : PUBLIC_DIR;
+    const startAbs = resolveProjectPath(projectRoot, startRel);
+    const assets: { path: string; size: number; ext: string }[] = [];
+
+    function walk(dir: string): void {
+      if (!existsSync(dir)) return;
+      for (const name of readdirSync(dir)) {
+        const abs = join(dir, name);
+        const stat = statSync(abs);
+        if (stat.isDirectory()) {
+          walk(abs);
+        } else {
+          const relFromPublic = abs
+            .slice(join(projectRoot, PUBLIC_DIR).length + 1)
+            .split('\\')
+            .join('/');
+          assets.push({ path: relFromPublic, size: stat.size, ext: extname(name).toLowerCase() });
+        }
+      }
+    }
+    walk(startAbs);
+    assets.sort((a, b) => a.path.localeCompare(b.path));
+    return { assets };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// project.asset.inspect
+// ---------------------------------------------------------------------------
+
+const ProjectAssetInspectInput = z.object({
+  assetPath: z.string().describe('public/-relative path to inspect.'),
+});
+
+export const projectAssetInspect = defineOperation({
+  name: 'project.asset.inspect',
+  summary:
+    'Inspect one asset under public/ — existence, size, mtime, and a content hash for small files.',
+  description:
+    'Read-only. Small files (<= 256KiB) also get a sha256 content hash; larger files are identified by size/mtime alone.',
+  input: ProjectAssetInspectInput,
+  result: z.object({
+    assetPath: z.string(),
+    exists: z.boolean(),
+    size: z.number().optional(),
+    mtimeMs: z.number().optional(),
+    ext: z.string().optional(),
+    contentHash: z
+      .string()
+      .optional()
+      .describe(`sha256 of the raw bytes, only for files <= ${HASHABLE_MAX_BYTES} bytes.`),
+  }),
+  errors: [NO_PROJECT_ROOT_ERROR, PATH_OUTSIDE_PROJECT_ERROR],
+  requires: { project: true },
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: {
+    risk: 'read',
+    summary:
+      'Reads one file’s metadata (and, for small files, its bytes) under public/; no writes.',
+  },
+  async impl(input, ctx) {
+    const projectRoot = requireProjectRoot(ctx);
+    const absPath = resolveProjectPath(projectRoot, join(PUBLIC_DIR, input.assetPath));
+    if (!existsSync(absPath) || statSync(absPath).isDirectory()) {
+      return { assetPath: input.assetPath, exists: false };
+    }
+    const stat = statSync(absPath);
+    const ext = extname(absPath).toLowerCase();
+    if (stat.size <= HASHABLE_MAX_BYTES) {
+      const { hash } = readFileWithHash(absPath);
+      return {
+        assetPath: input.assetPath,
+        exists: true,
+        size: stat.size,
+        mtimeMs: stat.mtimeMs,
+        ext,
+        contentHash: hash,
+      };
+    }
+    return {
+      assetPath: input.assetPath,
+      exists: true,
+      size: stat.size,
+      mtimeMs: stat.mtimeMs,
+      ext,
+    };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// project.asset.import — minimal: copy bytes from an external source path
+// into public/<destPath>. `sourcePath` is deliberately NOT confined to the
+// project (the whole point of "import" is bringing an external file IN) —
+// only `destPath` goes through resolveProjectPath's escape guard.
+// ---------------------------------------------------------------------------
+
+const ProjectAssetImportInput = z.object({
+  sourcePath: z.string().describe('Absolute path to the file to import (outside the project).'),
+  destPath: z.string().describe('public/-relative destination path.'),
+  overwrite: z
+    .boolean()
+    .optional()
+    .describe('Allow overwriting an existing destination file (default false).'),
+  dryRun: DryRunField,
+});
+
+export const projectAssetImport = defineOperation({
+  name: 'project.asset.import',
+  summary: 'Copy an external file into the project’s public/ asset root.',
+  description:
+    'Minimal byte-copy import (no format conversion/re-encoding). Refuses to overwrite an existing destination unless `overwrite:true`.',
+  input: ProjectAssetImportInput,
+  result: mutationResultSchema(z.object({ destPath: z.string(), size: z.number() })),
+  errors: [
+    NO_PROJECT_ROOT_ERROR,
+    PATH_OUTSIDE_PROJECT_ERROR,
+    {
+      code: 'SOURCE_NOT_FOUND',
+      summary: 'sourcePath does not exist or is not a file.',
+      data: z.object({ sourcePath: z.string() }),
+    },
+    {
+      code: 'DEST_EXISTS',
+      summary: 'destPath already exists and overwrite was not set.',
+      data: z.object({ destPath: z.string() }),
+    },
+  ],
+  requires: { project: true },
+  host: 'node',
+  mutates: true,
+  supportsDryRun: true,
+  permission: { risk: 'write', summary: 'Writes one file under public/.' },
+  async impl(input, ctx) {
+    const projectRoot = requireProjectRoot(ctx);
+    if (!existsSync(input.sourcePath) || statSync(input.sourcePath).isDirectory()) {
+      throw new OperationError('SOURCE_NOT_FOUND', `Source file not found: ${input.sourcePath}`, {
+        sourcePath: input.sourcePath,
+      });
+    }
+    const destAbs = resolveProjectPath(projectRoot, join(PUBLIC_DIR, input.destPath));
+    const destExists = existsSync(destAbs);
+    if (destExists && !input.overwrite) {
+      throw new OperationError(
+        'DEST_EXISTS',
+        `${input.destPath} already exists — pass overwrite:true to replace it.`,
+        {
+          destPath: input.destPath,
+        },
+      );
+    }
+
+    const size = statSync(input.sourcePath).size;
+    const dryRun = input.dryRun ?? false;
+    if (!dryRun) {
+      const destDir = dirname(destAbs);
+      if (!existsSync(destDir)) mkdirSync(destDir, { recursive: true });
+      copyFileSync(input.sourcePath, destAbs);
+    }
+
+    return {
+      dryRun,
+      written: !dryRun,
+      filesChanged: [destAbs],
+      before: { destPath: input.destPath, existed: destExists },
+      after: { destPath: input.destPath, size },
+    };
+  },
+});
+
+/** Register every B2 `project.asset.*` operation onto `registry`. */
+export function registerAssetOperations(registry: OperationRegistry): void {
+  registry.register(projectAssetList);
+  registry.register(projectAssetInspect);
+  registry.register(projectAssetImport);
+}

package/src/project/component-operations.ts

@@ -0,0 +1,337 @@
+/**
+ * `project.scene.component.*` (B2, §8 B2 "component list/add/update/remove").
+ *
+ * A component's identity within an entity is its NAME (the key in
+ * `entity.components`, a `Record<string, Record<string, ComponentValue>>` —
+ * see `packages/engine/src/scene/schema/entity.ts`'s `ComponentsSchema`) — so
+ * "id-aware" here means addressed by that name, never by e.g. iteration
+ * order. Every mutation reuses the exact same path as
+ * `project.scene.entity.update`: read the entity (by stable id), compute a
+ * new `components` record, hand the FULL merged entity to applyDiff's
+ * `update` op. No separate component-patching logic exists.
+ */
+
+import type { SceneEntity } from '@vgai/engine/scene/scene-types';
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import { finalizeSceneMutation } from './entity-operations.js';
+import {
+  APPLY_DIFF_FAILED_ERROR,
+  applyDiffOrThrow,
+  readAndParseScene,
+  SCENE_INVALID_ERROR,
+} from './scene-operations.js';
+import {
+  BaseHashField,
+  CONFLICT_ERROR,
+  checkNotStale,
+  DryRunField,
+  ENTITY_NOT_FOUND_ERROR,
+  FILE_NOT_FOUND_ERROR,
+  mutationResultSchema,
+  NO_PROJECT_ROOT_ERROR,
+  PATH_OUTSIDE_PROJECT_ERROR,
+  requireEntityById,
+  requireProjectRoot,
+} from './shared.js';
+
+const ComponentDataValueSchema = z.union([
+  z.number(),
+  z.string(),
+  z.boolean(),
+  z.array(z.number()),
+  z.array(z.string()),
+  z.array(z.boolean()),
+]);
+const ComponentDataSchema = z.record(z.string(), ComponentDataValueSchema);
+
+export const COMPONENT_NOT_FOUND_ERROR = {
+  code: 'COMPONENT_NOT_FOUND',
+  summary: 'No component with the given name is attached to this entity.',
+  data: z.object({ entityId: z.string(), componentName: z.string() }),
+} as const;
+
+export const COMPONENT_ALREADY_EXISTS_ERROR = {
+  code: 'COMPONENT_ALREADY_EXISTS',
+  summary:
+    'A component with this name is already attached to the entity — use component.update instead.',
+  data: z.object({ entityId: z.string(), componentName: z.string() }),
+} as const;
+
+/** Build the full entity payload applyDiff's `update` op needs, with `components` replaced by `newComponents`. */
+function entityWithComponents(
+  entity: SceneEntity,
+  newComponents: Record<string, Record<string, unknown>>,
+): SceneEntity {
+  const { id: _id, children: _children, ...fields } = entity;
+  return { ...fields, components: newComponents } as SceneEntity;
+}
+
+// ---------------------------------------------------------------------------
+// project.scene.component.list
+// ---------------------------------------------------------------------------
+
+const ProjectSceneComponentListInput = z.object({
+  scenePath: z.string().describe('Project-relative path to the .vscn.json scene file.'),
+  entityId: z.string().describe('Entity to list components for.'),
+});
+
+export const projectSceneComponentList = defineOperation({
+  name: 'project.scene.component.list',
+  summary: 'List every component (by name) attached to an entity.',
+  description: 'Read-only. Resolves the entity by stable id.',
+  input: ProjectSceneComponentListInput,
+  result: z.object({
+    entityId: z.string(),
+    components: z
+      .record(z.string(), ComponentDataSchema)
+      .describe('Component name -> its data record.'),
+  }),
+  errors: [
+    NO_PROJECT_ROOT_ERROR,
+    PATH_OUTSIDE_PROJECT_ERROR,
+    FILE_NOT_FOUND_ERROR,
+    SCENE_INVALID_ERROR,
+    ENTITY_NOT_FOUND_ERROR,
+  ],
+  requires: { project: true },
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Reads a scene file; no writes.' },
+  async impl(input, ctx) {
+    const projectRoot = requireProjectRoot(ctx);
+    const { scene } = readAndParseScene(projectRoot, input.scenePath);
+    const entity = requireEntityById(scene.entities, input.entityId);
+    return { entityId: input.entityId, components: entity.components ?? {} };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// project.scene.component.add
+// ---------------------------------------------------------------------------
+
+const ProjectSceneComponentAddInput = z.object({
+  scenePath: z.string().describe('Project-relative path to the .vscn.json scene file.'),
+  entityId: z.string().describe('Entity to attach the component to.'),
+  componentName: z.string().describe('Component name (record key).'),
+  data: ComponentDataSchema.describe('Initial component data.'),
+  dryRun: DryRunField,
+  baseHash: BaseHashField,
+});
+
+const ComponentAfterSchema = z.object({
+  entityId: z.string(),
+  componentName: z.string(),
+  data: z.unknown(),
+});
+
+export const projectSceneComponentAdd = defineOperation({
+  name: 'project.scene.component.add',
+  summary: 'Attach a new named component to an entity.',
+  description:
+    'Delegates to applyDiff’s `update` op with a merged components record — same reused write path as project.scene.entity.update.',
+  input: ProjectSceneComponentAddInput,
+  result: mutationResultSchema(ComponentAfterSchema),
+  errors: [
+    NO_PROJECT_ROOT_ERROR,
+    PATH_OUTSIDE_PROJECT_ERROR,
+    FILE_NOT_FOUND_ERROR,
+    SCENE_INVALID_ERROR,
+    APPLY_DIFF_FAILED_ERROR,
+    CONFLICT_ERROR,
+    ENTITY_NOT_FOUND_ERROR,
+    COMPONENT_ALREADY_EXISTS_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 entity = requireEntityById(scene.entities, input.entityId);
+    const existing = entity.components ?? {};
+    if (input.componentName in existing) {
+      throw new OperationError(
+        'COMPONENT_ALREADY_EXISTS',
+        `Entity "${input.entityId}" already has a component named "${input.componentName}" — use project.scene.component.update instead.`,
+        { entityId: input.entityId, componentName: input.componentName },
+      );
+    }
+    const newComponents = { ...existing, [input.componentName]: input.data };
+
+    const result = applyDiffOrThrow(scene, {
+      ops: [
+        { type: 'update', id: input.entityId, entity: entityWithComponents(entity, newComponents) },
+      ],
+      environmentChanged: false,
+      metaChanged: false,
+    });
+
+    return finalizeSceneMutation(absPath, input.scenePath, result, input.dryRun ?? false, null, {
+      entityId: input.entityId,
+      componentName: input.componentName,
+      data: input.data,
+    });
+  },
+});
+
+// ---------------------------------------------------------------------------
+// project.scene.component.update — merge new fields onto the existing component's data.
+// ---------------------------------------------------------------------------
+
+const ProjectSceneComponentUpdateInput = z.object({
+  scenePath: z.string().describe('Project-relative path to the .vscn.json scene file.'),
+  entityId: z.string().describe('Entity the component is attached to.'),
+  componentName: z.string().describe('Component name (record key) to update.'),
+  data: ComponentDataSchema.describe(
+    'Fields to overlay onto the component’s current data (a merge).',
+  ),
+  dryRun: DryRunField,
+  baseHash: BaseHashField,
+});
+
+export const projectSceneComponentUpdate = defineOperation({
+  name: 'project.scene.component.update',
+  summary: 'Merge field changes onto an existing named component.',
+  description: 'Delegates to applyDiff’s `update` op with a merged components record.',
+  input: ProjectSceneComponentUpdateInput,
+  result: mutationResultSchema(ComponentAfterSchema),
+  errors: [
+    NO_PROJECT_ROOT_ERROR,
+    PATH_OUTSIDE_PROJECT_ERROR,
+    FILE_NOT_FOUND_ERROR,
+    SCENE_INVALID_ERROR,
+    APPLY_DIFF_FAILED_ERROR,
+    CONFLICT_ERROR,
+    ENTITY_NOT_FOUND_ERROR,
+    COMPONENT_NOT_FOUND_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 entity = requireEntityById(scene.entities, input.entityId);
+    const existing = entity.components ?? {};
+    const currentData = existing[input.componentName];
+    if (currentData === undefined) {
+      throw new OperationError(
+        'COMPONENT_NOT_FOUND',
+        `Entity "${input.entityId}" has no component named "${input.componentName}".`,
+        { entityId: input.entityId, componentName: input.componentName },
+      );
+    }
+    const mergedData = { ...currentData, ...input.data };
+    const newComponents = { ...existing, [input.componentName]: mergedData };
+
+    const result = applyDiffOrThrow(scene, {
+      ops: [
+        { type: 'update', id: input.entityId, entity: entityWithComponents(entity, newComponents) },
+      ],
+      environmentChanged: false,
+      metaChanged: false,
+    });
+
+    return finalizeSceneMutation(
+      absPath,
+      input.scenePath,
+      result,
+      input.dryRun ?? false,
+      { entityId: input.entityId, componentName: input.componentName, data: currentData },
+      { entityId: input.entityId, componentName: input.componentName, data: mergedData },
+    );
+  },
+});
+
+// ---------------------------------------------------------------------------
+// project.scene.component.remove
+// ---------------------------------------------------------------------------
+
+const ProjectSceneComponentRemoveInput = z.object({
+  scenePath: z.string().describe('Project-relative path to the .vscn.json scene file.'),
+  entityId: z.string().describe('Entity the component is attached to.'),
+  componentName: z.string().describe('Component name (record key) to remove.'),
+  dryRun: DryRunField,
+  baseHash: BaseHashField,
+});
+
+export const projectSceneComponentRemove = defineOperation({
+  name: 'project.scene.component.remove',
+  summary: 'Detach a named component from an entity.',
+  description:
+    'Delegates to applyDiff’s `update` op with the component key deleted from the components record.',
+  input: ProjectSceneComponentRemoveInput,
+  result: mutationResultSchema(ComponentAfterSchema),
+  errors: [
+    NO_PROJECT_ROOT_ERROR,
+    PATH_OUTSIDE_PROJECT_ERROR,
+    FILE_NOT_FOUND_ERROR,
+    SCENE_INVALID_ERROR,
+    APPLY_DIFF_FAILED_ERROR,
+    CONFLICT_ERROR,
+    ENTITY_NOT_FOUND_ERROR,
+    COMPONENT_NOT_FOUND_ERROR,
+  ],
+  requires: { project: true },
+  host: 'node',
+  mutates: true,
+  supportsDryRun: true,
+  permission: {
+    risk: 'destructive',
+    summary: 'Removes a component from an entity in 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 entity = requireEntityById(scene.entities, input.entityId);
+    const existing = entity.components ?? {};
+    const currentData = existing[input.componentName];
+    if (currentData === undefined) {
+      throw new OperationError(
+        'COMPONENT_NOT_FOUND',
+        `Entity "${input.entityId}" has no component named "${input.componentName}".`,
+        { entityId: input.entityId, componentName: input.componentName },
+      );
+    }
+    const newComponents = { ...existing };
+    delete newComponents[input.componentName];
+
+    const result = applyDiffOrThrow(scene, {
+      ops: [
+        { type: 'update', id: input.entityId, entity: entityWithComponents(entity, newComponents) },
+      ],
+      environmentChanged: false,
+      metaChanged: false,
+    });
+
+    return finalizeSceneMutation(
+      absPath,
+      input.scenePath,
+      result,
+      input.dryRun ?? false,
+      { entityId: input.entityId, componentName: input.componentName, data: currentData },
+      { entityId: input.entityId, componentName: input.componentName, data: null },
+    );
+  },
+});
+
+/** Register every B2 `project.scene.component.*` operation onto `registry`. */
+export function registerComponentOperations(registry: OperationRegistry): void {
+  registry.register(projectSceneComponentList);
+  registry.register(projectSceneComponentAdd);
+  registry.register(projectSceneComponentUpdate);
+  registry.register(projectSceneComponentRemove);
+}