@vgai/sdk 0.4.0-canary.20260715.0

package/src/project/input-map-operations.ts

@@ -0,0 +1,233 @@
+/**
+ * `project.inputMap.*` (B2, §8 B2 "input-map read/validate/update").
+ *
+ * REUSE: validates through the engine's real `InputMapFileSchema`
+ * (`@vgai/engine/input/schema`) — the same schema `InputManager.loadMap`
+ * parses `.inputmap.json` through at runtime. Its binding-kind set is
+ * authoritative here: an unknown `type` (not in the discriminated union) is
+ * rejected with a structured issue, while every live kind — including
+ * `mouse_move`/`gamepad_axis_pair`, un-rejected once F2 gave them real
+ * InputManager readers — validates. See that schema's jsdoc.
+ */
+
+import { InputMapFileSchema } from '@vgai/engine/input/schema';
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type OperationRegistry } 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';
+
+function formatIssues(issues: { path: PropertyKey[]; message: string }[]): string[] {
+  return issues.map((i) => `${i.path.join('.')}: ${i.message}`);
+}
+
+export const INPUT_MAP_INVALID_ERROR = {
+  code: 'INPUT_MAP_INVALID',
+  summary: 'The input map file/document fails schema validation.',
+  data: z.object({ issues: z.array(z.string()) }),
+} as const;
+
+// ---------------------------------------------------------------------------
+// project.inputMap.read
+// ---------------------------------------------------------------------------
+
+const ProjectInputMapReadInput = z.object({
+  inputMapPath: z
+    .string()
+    .describe(
+      'Project-relative path to an .inputmap.json file (conventionally under public/inputmaps/).',
+    ),
+});
+
+export const projectInputMapRead = defineOperation({
+  name: 'project.inputMap.read',
+  summary: 'Read + validate an .inputmap.json file.',
+  description:
+    'Reuses @vgai/engine/input/schema’s InputMapFileSchema — the same schema InputManager.loadMap parses through.',
+  input: ProjectInputMapReadInput,
+  result: z.object({
+    inputMapPath: z.string(),
+    contentHash: z
+      .string()
+      .describe('sha256 of the raw file bytes — pass as baseHash to a later update.'),
+    inputMap: z.unknown().describe('The validated input map document.'),
+  }),
+  errors: [
+    NO_PROJECT_ROOT_ERROR,
+    PATH_OUTSIDE_PROJECT_ERROR,
+    FILE_NOT_FOUND_ERROR,
+    INPUT_MAP_INVALID_ERROR,
+  ],
+  requires: { project: true },
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Reads one input map file; no writes.' },
+  async impl(input, ctx) {
+    const projectRoot = requireProjectRoot(ctx);
+    const absPath = resolveProjectPath(projectRoot, input.inputMapPath);
+    const { raw, hash } = readFileWithHash(absPath);
+    const json: unknown = JSON.parse(raw);
+    const parsed = InputMapFileSchema.safeParse(json);
+    if (!parsed.success) {
+      throw new OperationError(
+        'INPUT_MAP_INVALID',
+        `${input.inputMapPath} failed input-map validation.`,
+        {
+          issues: formatIssues(parsed.error.issues),
+        },
+      );
+    }
+    return { inputMapPath: absPath, contentHash: hash, inputMap: parsed.data };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// project.inputMap.validate
+// ---------------------------------------------------------------------------
+
+const ProjectInputMapValidateInput = z.object({
+  inputMapPath: z
+    .string()
+    .optional()
+    .describe('Validate this project-relative file instead of `inputMap`.'),
+  inputMap: z
+    .unknown()
+    .optional()
+    .describe('Validate this raw document instead of reading `inputMapPath`.'),
+});
+
+export const projectInputMapValidate = defineOperation({
+  name: 'project.inputMap.validate',
+  summary: 'Validate an input map file or raw document against the real input-map schema.',
+  description:
+    'Reuses @vgai/engine/input/schema’s InputMapFileSchema. Never throws for a malformed document — failures come back as structured issues.',
+  input: ProjectInputMapValidateInput,
+  result: z.object({ valid: z.boolean(), issues: z.array(z.string()) }),
+  errors: [
+    NO_PROJECT_ROOT_ERROR,
+    PATH_OUTSIDE_PROJECT_ERROR,
+    {
+      code: 'BAD_INPUT',
+      summary: 'Neither inputMapPath nor inputMap was given.',
+      data: z.object({}),
+    },
+  ],
+  requires: { project: true },
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: {
+    risk: 'read',
+    summary: 'Reads an input map file (or validates a given document); no writes.',
+  },
+  async impl(input, ctx) {
+    let json: unknown;
+    if (input.inputMap !== undefined) {
+      json = input.inputMap;
+    } else if (input.inputMapPath !== undefined) {
+      const projectRoot = requireProjectRoot(ctx);
+      const absPath = resolveProjectPath(projectRoot, input.inputMapPath);
+      json = JSON.parse(readFileWithHash(absPath).raw);
+    } else {
+      throw new OperationError('BAD_INPUT', 'One of inputMapPath or inputMap must be given.', {});
+    }
+    const parsed = InputMapFileSchema.safeParse(json);
+    if (!parsed.success) return { valid: false, issues: formatIssues(parsed.error.issues) };
+    return { valid: true, issues: [] };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// project.inputMap.update — merge new/changed actions onto the existing map.
+// ---------------------------------------------------------------------------
+
+const ProjectInputMapUpdateInput = z.object({
+  inputMapPath: z.string().describe('Project-relative path to the .inputmap.json file to modify.'),
+  actions: z
+    .record(z.string(), z.union([z.object({ bindings: z.array(z.unknown()) }), z.null()]))
+    .describe(
+      'Actions to add/replace (by name), or set to null to delete that action. Actions not ' +
+        'mentioned are left unchanged.',
+    ),
+  dryRun: DryRunField,
+  baseHash: BaseHashField,
+});
+
+export const projectInputMapUpdate = defineOperation({
+  name: 'project.inputMap.update',
+  summary: 'Add, replace, or delete actions in an input map — dry-run capable, conflict-checked.',
+  description:
+    'Merges `actions` onto the on-disk input map, re-validates the full merged document via InputMapFileSchema before ever writing, and refuses a stale write (CONFLICT) when baseHash no longer matches.',
+  input: ProjectInputMapUpdateInput,
+  result: mutationResultSchema(z.object({ inputMap: z.unknown() })),
+  errors: [
+    NO_PROJECT_ROOT_ERROR,
+    PATH_OUTSIDE_PROJECT_ERROR,
+    FILE_NOT_FOUND_ERROR,
+    INPUT_MAP_INVALID_ERROR,
+    CONFLICT_ERROR,
+  ],
+  requires: { project: true },
+  host: 'node',
+  mutates: true,
+  supportsDryRun: true,
+  permission: { risk: 'write', summary: 'Writes the target input map file.' },
+  async impl(input, ctx) {
+    const projectRoot = requireProjectRoot(ctx);
+    const absPath = resolveProjectPath(projectRoot, input.inputMapPath);
+    const { raw, hash } = readFileWithHash(absPath);
+    checkNotStale(absPath, hash, input.baseHash);
+
+    const before = JSON.parse(raw) as { version: number; actions: Record<string, unknown> };
+    const mergedActions = { ...before.actions };
+    for (const [name, value] of Object.entries(input.actions)) {
+      if (value === null) delete mergedActions[name];
+      else mergedActions[name] = value;
+    }
+    const merged = { ...before, actions: mergedActions };
+
+    const parsed = InputMapFileSchema.safeParse(merged);
+    if (!parsed.success) {
+      throw new OperationError(
+        'INPUT_MAP_INVALID',
+        'The patched input map failed schema validation.',
+        {
+          issues: formatIssues(parsed.error.issues),
+        },
+      );
+    }
+
+    const dryRun = input.dryRun ?? false;
+    if (!dryRun) {
+      writeFileAtomic(absPath, `${JSON.stringify(parsed.data, null, 2)}\n`);
+    }
+
+    return {
+      dryRun,
+      written: !dryRun,
+      filesChanged: [absPath],
+      before: { inputMap: before },
+      after: { inputMap: parsed.data },
+    };
+  },
+});
+
+/** Register every B2 `project.inputMap.*` operation onto `registry`. */
+export function registerInputMapOperations(registry: OperationRegistry): void {
+  registry.register(projectInputMapRead);
+  registry.register(projectInputMapValidate);
+  registry.register(projectInputMapUpdate);
+}

package/src/project/manifest-operations.ts

@@ -0,0 +1,355 @@
+/**
+ * `project.discover` and `project.manifest.*` (B2,
+ * docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §8 B2 "project
+ * discovery/status" + "manifest read/validate/update").
+ *
+ * REUSE, not reimplementation: `project.manifest.validate`/`.update` both
+ * validate through the real engine manifest schema/loader
+ * (`@vgai/engine/manifest/schema`'s `GameManifestSchema`,
+ * `@vgai/engine/manifest/load`'s `loadGameManifest` — the exact same
+ * cross-field checks `vgai validate`/the editor/the runtime use), never a
+ * second hand-rolled manifest shape check.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadGameManifest } from '@vgai/engine/manifest/load';
+import { GameManifestSchema } from '@vgai/engine/manifest/schema';
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import {
+  BaseHashField,
+  CONFLICT_ERROR,
+  checkNotStale,
+  DryRunField,
+  FILE_NOT_FOUND_ERROR,
+  listProjectFiles,
+  mutationResultSchema,
+  NO_PROJECT_ROOT_ERROR,
+  readFileWithHash,
+  requireProjectRoot,
+  writeFileAtomic,
+} from './shared.js';
+
+const MANIFEST_FILENAME = 'vgai.game.json';
+
+// ---------------------------------------------------------------------------
+// project.discover — richer, real project-native discovery (B1's
+// `project.status` is the boolean existence stand-in this task brief named;
+// this is the "survey the whole project" op — manifest summary plus every
+// other B2 discovery op's own listing, gathered in one call).
+// ---------------------------------------------------------------------------
+
+const ProjectDiscoverInput = z.object({}).describe('No input — surveys ctx.projectRoot.');
+
+const ProjectDiscoverResult = z
+  .object({
+    projectRoot: z.string().describe('Absolute path this discovery ran against.'),
+    hasManifest: z
+      .boolean()
+      .describe('True when vgai.game.json exists directly under projectRoot.'),
+    manifestName: z
+      .string()
+      .optional()
+      .describe("The manifest's declared game name, when present/valid."),
+    rootIds: z
+      .array(z.string())
+      .optional()
+      .describe('Adapter-root ids declared in the manifest, when present/valid.'),
+    sceneFiles: z
+      .array(z.string())
+      .describe('Every *.vscn.json found under the project (project-relative).'),
+    inputMapFiles: z
+      .array(z.string())
+      .describe('Every *.inputmap.json found under the project (project-relative).'),
+    storyFiles: z
+      .array(z.string())
+      .describe('Every *.stories.tsx / *.stories.ts found under the project.'),
+    theatreProjectFiles: z
+      .array(z.string())
+      .describe('Every *.theatre-project.json found under the project.'),
+  })
+  .describe('A one-call survey of the project at ctx.projectRoot.');
+
+export const projectDiscover = defineOperation({
+  name: 'project.discover',
+  summary:
+    "Survey a project's manifest, scenes, input maps, stories, and Theatre project state files.",
+  description:
+    'File-native discovery (no editor process). Reads the manifest (if present, without ' +
+    'throwing on an invalid one — see result.manifestName/rootIds being absent) and walks the ' +
+    'project directory for every other B2-discoverable file family in one call.',
+  input: ProjectDiscoverInput,
+  result: ProjectDiscoverResult,
+  errors: [NO_PROJECT_ROOT_ERROR],
+  requires: { project: true },
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Reads project files; no writes.' },
+  async impl(_input, ctx) {
+    const projectRoot = requireProjectRoot(ctx);
+    const manifestPath = join(projectRoot, MANIFEST_FILENAME);
+    const hasManifest = existsSync(manifestPath);
+
+    let manifestName: string | undefined;
+    let rootIds: string[] | undefined;
+    if (hasManifest) {
+      try {
+        const raw: unknown = JSON.parse(readFileWithHash(manifestPath).raw);
+        const resolved = loadGameManifest(raw);
+        manifestName = resolved.name;
+        rootIds = resolved.roots.map((root) => root.id);
+      } catch {
+        // Manifest present but invalid/unparseable — discovery still reports
+        // hasManifest:true; use project.manifest.validate for the structured
+        // reason why.
+      }
+    }
+
+    return {
+      projectRoot,
+      hasManifest,
+      ...(manifestName !== undefined ? { manifestName } : {}),
+      ...(rootIds !== undefined ? { rootIds } : {}),
+      sceneFiles: listProjectFiles(projectRoot, (p) => p.endsWith('.vscn.json')),
+      inputMapFiles: listProjectFiles(projectRoot, (p) => p.endsWith('.inputmap.json')),
+      storyFiles: listProjectFiles(
+        projectRoot,
+        (p) => p.endsWith('.stories.tsx') || p.endsWith('.stories.ts'),
+      ),
+      theatreProjectFiles: listProjectFiles(projectRoot, (p) =>
+        p.endsWith('.theatre-project.json'),
+      ),
+    };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// project.manifest.read
+// ---------------------------------------------------------------------------
+
+const ProjectManifestReadInput = z
+  .object({})
+  .describe('No input — reads vgai.game.json under ctx.projectRoot.');
+
+const ProjectManifestReadResult = z
+  .object({
+    path: z.string().describe('Absolute path to vgai.game.json.'),
+    contentHash: z
+      .string()
+      .describe(
+        'sha256 of the raw file bytes — pass as baseHash to a later update to detect external changes.',
+      ),
+    manifest: z
+      .unknown()
+      .describe(
+        'The raw parsed JSON (not the resolved/defaulted form — see project.manifest.validate for that).',
+      ),
+  })
+  .describe('Raw manifest read result.');
+
+export const projectManifestRead = defineOperation({
+  name: 'project.manifest.read',
+  summary: 'Read the raw vgai.game.json manifest for the project.',
+  description:
+    'File-native read. Returns the raw parsed JSON plus a content hash for optimistic-concurrency updates.',
+  input: ProjectManifestReadInput,
+  result: ProjectManifestReadResult,
+  errors: [NO_PROJECT_ROOT_ERROR, FILE_NOT_FOUND_ERROR],
+  requires: { project: true },
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Reads vgai.game.json; no writes.' },
+  async impl(_input, ctx) {
+    const projectRoot = requireProjectRoot(ctx);
+    const path = join(projectRoot, MANIFEST_FILENAME);
+    const { raw, hash } = readFileWithHash(path);
+    return { path, contentHash: hash, manifest: JSON.parse(raw) };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// project.manifest.validate
+// ---------------------------------------------------------------------------
+
+const ProjectManifestValidateInput = z
+  .object({
+    manifest: z
+      .unknown()
+      .optional()
+      .describe('Validate this raw value instead of re-reading vgai.game.json from disk.'),
+  })
+  .describe('Validate the on-disk manifest, or a given candidate document.');
+
+const ProjectManifestValidateResult = z
+  .object({
+    valid: z.boolean(),
+    issues: z.array(z.string()).describe('Human-readable validation failures (empty when valid).'),
+    rootIds: z.array(z.string()).optional().describe('Adapter-root ids, when valid.'),
+  })
+  .describe('Structured manifest validation result — never throws for an invalid document.');
+
+export const projectManifestValidate = defineOperation({
+  name: 'project.manifest.validate',
+  summary: 'Validate the project manifest against the real engine schema + cross-field rules.',
+  description:
+    'Reuses @vgai/engine/manifest/load’s loadGameManifest (the same validator the editor/CLI/' +
+    'runtime use) — never a second hand-rolled manifest check. Never throws for a malformed ' +
+    'document; failures come back as structured issues.',
+  input: ProjectManifestValidateInput,
+  result: ProjectManifestValidateResult,
+  errors: [NO_PROJECT_ROOT_ERROR, FILE_NOT_FOUND_ERROR],
+  requires: { project: true },
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: {
+    risk: 'read',
+    summary: 'Reads vgai.game.json (or validates a given document); no writes.',
+  },
+  async impl(input, ctx) {
+    let raw: unknown;
+    if (input.manifest !== undefined) {
+      raw = input.manifest;
+    } else {
+      const projectRoot = requireProjectRoot(ctx);
+      raw = JSON.parse(readFileWithHash(join(projectRoot, MANIFEST_FILENAME)).raw);
+    }
+    try {
+      const resolved = loadGameManifest(raw);
+      return { valid: true, issues: [], rootIds: resolved.roots.map((root) => root.id) };
+    } catch (err) {
+      const issues =
+        err instanceof Error &&
+        'issues' in err &&
+        Array.isArray((err as { issues: unknown }).issues)
+          ? (err as { issues: { path: PropertyKey[]; message: string }[] }).issues.map(
+              (i) => `${i.path.join('.')}: ${i.message}`,
+            )
+          : [err instanceof Error ? err.message : String(err)];
+      return { valid: false, issues };
+    }
+  },
+});
+
+// ---------------------------------------------------------------------------
+// project.manifest.update — a real mutation: dry-run + external-change
+// detection + exact files-changed, restricted to a safe, explicit set of
+// updatable top-level fields (name/version/resolution). Roots are a
+// separate, more structural concern (adapter/scene/entry cross-field rules)
+// out of scope for this generic field-patch op.
+// ---------------------------------------------------------------------------
+
+const ManifestPatchFields = z
+  .object({
+    name: z.string().optional().describe('New game display name.'),
+    version: z
+      .string()
+      .optional()
+      .describe("New game version (the manifest's own, not the engine pin)."),
+    resolution: z
+      .object({ width: z.number(), height: z.number() })
+      .optional()
+      .describe('New canvas resolution.'),
+  })
+  .describe('Top-level manifest fields this op is allowed to change.');
+
+const ProjectManifestUpdateInput = z
+  .object({
+    patch: ManifestPatchFields,
+    dryRun: DryRunField,
+    baseHash: BaseHashField,
+  })
+  .describe('Patch a subset of top-level vgai.game.json fields.');
+
+const ProjectManifestUpdateResult = mutationResultSchema(
+  z
+    .object({ manifest: z.unknown() })
+    .describe('The manifest document after the patch (or that WOULD result).'),
+);
+
+export const projectManifestUpdate = defineOperation({
+  name: 'project.manifest.update',
+  summary: 'Patch name/version/resolution on vgai.game.json, dry-run capable, conflict-checked.',
+  description:
+    'Merges `patch` onto the raw on-disk manifest, re-validates the FULL merged document through ' +
+    'GameManifestSchema (the real schema, cross-field rules included) before ever writing, and ' +
+    'refuses the write if the file changed since `baseHash` was read (CONFLICT).',
+  input: ProjectManifestUpdateInput,
+  result: ProjectManifestUpdateResult,
+  errors: [
+    NO_PROJECT_ROOT_ERROR,
+    FILE_NOT_FOUND_ERROR,
+    CONFLICT_ERROR,
+    {
+      code: 'INVALID_MANIFEST',
+      summary: 'The patched manifest fails GameManifestSchema / cross-field validation.',
+      data: z.object({ issues: z.array(z.string()) }),
+    },
+  ],
+  requires: { project: true },
+  host: 'node',
+  mutates: true,
+  supportsDryRun: true,
+  permission: { risk: 'write', summary: 'Writes vgai.game.json.' },
+  async impl(input, ctx) {
+    const projectRoot = requireProjectRoot(ctx);
+    const path = join(projectRoot, MANIFEST_FILENAME);
+    const { raw, hash } = readFileWithHash(path);
+    checkNotStale(path, hash, input.baseHash);
+
+    const before = JSON.parse(raw) as Record<string, unknown>;
+    const merged: Record<string, unknown> = { ...before };
+    if (input.patch.name !== undefined) merged['name'] = input.patch.name;
+    if (input.patch.version !== undefined) merged['version'] = input.patch.version;
+    if (input.patch.resolution !== undefined) merged['resolution'] = input.patch.resolution;
+
+    const parsed = GameManifestSchema.safeParse(merged);
+    if (!parsed.success) {
+      throw new OperationError(
+        'INVALID_MANIFEST',
+        'The patched manifest failed schema validation.',
+        {
+          issues: parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`),
+        },
+      );
+    }
+    // Cross-field rules (roots uniqueness already inside the schema's
+    // superRefine; engine pin / adapter rules live in loadGameManifest).
+    try {
+      loadGameManifest(merged);
+    } catch (err) {
+      throw new OperationError(
+        'INVALID_MANIFEST',
+        'The patched manifest failed cross-field validation.',
+        {
+          issues: [err instanceof Error ? err.message : String(err)],
+        },
+      );
+    }
+
+    const dryRun = input.dryRun ?? false;
+    if (!dryRun) {
+      writeFileAtomic(path, `${JSON.stringify(merged, null, 2)}\n`);
+    }
+
+    return {
+      dryRun,
+      written: !dryRun,
+      filesChanged: [path],
+      before: { manifest: before },
+      after: { manifest: merged },
+    };
+  },
+});
+
+/** Register every B2 `project.discover` / `project.manifest.*` operation onto `registry`. */
+export function registerManifestOperations(registry: OperationRegistry): void {
+  registry.register(projectDiscover);
+  registry.register(projectManifestRead);
+  registry.register(projectManifestValidate);
+  registry.register(projectManifestUpdate);
+}