@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/server/project-operations.ts

@@ -0,0 +1,343 @@
+/**
+ * Project-operation discovery and execution.
+ *
+ * Project modules stay ordinary TS/JS. This server-side boundary is the only
+ * automatic loader: it recursively scans src/operations for operation modules, asks the
+ * owning Vite server to load each module in Node, validates the exported
+ * OperationDefinition, and dispatches through the existing SDK registry.
+ * Nothing here imports an operation into the editor browser or a game build.
+ */
+
+import type { Dirent } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, relative, resolve, sep } from 'node:path';
+import { z } from 'zod';
+import type { OperationDefinition, OperationOutcome } from '../../vgai-sdk/src/registry';
+import { OperationRegistry } from '../../vgai-sdk/src/registry';
+import { createProjectOutputWriter } from './project-output-writer';
+
+export type ProjectModuleLoader = (absoluteModuleId: string) => Promise<unknown>;
+
+export interface ProjectOperationErrorSummary {
+  code: string;
+  summary: string;
+  dataSchema?: unknown;
+}
+
+export interface ProjectOperationCatalogEntry {
+  name: string;
+  summary: string;
+  description: string;
+  sourcePath: string;
+  inputSchema: unknown;
+  resultSchema: unknown;
+  errors: ProjectOperationErrorSummary[];
+  requires: Record<string, boolean | undefined>;
+  host: 'node' | 'editor-browser' | 'runtime-page';
+  mutates: boolean;
+  supportsDryRun: boolean;
+  longRunning: boolean;
+  permission: { risk: 'read' | 'write' | 'destructive'; summary: string };
+}
+
+export interface ProjectOperationLoadError {
+  sourcePath: string;
+  message: string;
+}
+
+export interface ProjectOperationCatalog {
+  operations: ProjectOperationCatalogEntry[];
+  loadErrors: ProjectOperationLoadError[];
+}
+
+interface LoadedCatalog extends ProjectOperationCatalog {
+  definitions: Map<string, OperationDefinition>;
+}
+
+function projectPath(projectRoot: string, absolutePath: string): string {
+  return relative(projectRoot, absolutePath).split(sep).join('/');
+}
+
+async function findOperationFiles(dir: string): Promise<string[]> {
+  const found: string[] = [];
+  let entries: Dirent[];
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return found;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    const absolute = resolve(dir, entry.name);
+    if (entry.isDirectory()) {
+      found.push(...(await findOperationFiles(absolute)));
+    } else if (entry.name.endsWith('.operation.ts') || entry.name.endsWith('.operation.js')) {
+      found.push(absolute);
+    }
+  }
+  return found;
+}
+
+interface OperationFile {
+  absolutePath: string;
+  sourcePath: string;
+}
+
+interface PackageJsonShape {
+  name?: string;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  vgai?: { operations?: string[] };
+}
+
+async function readPackageJson(path: string): Promise<PackageJsonShape | null> {
+  try {
+    return JSON.parse(await readFile(path, 'utf8')) as PackageJsonShape;
+  } catch {
+    return null;
+  }
+}
+
+function resolveDependencyPackageJson(
+  requireFromProject: ReturnType<typeof createRequire>,
+  dependencyName: string,
+): string | null {
+  try {
+    return requireFromProject.resolve(`${dependencyName}/package.json`);
+  } catch {
+    return null;
+  }
+}
+
+async function advertisedDependencyOperations(
+  requireFromProject: ReturnType<typeof createRequire>,
+  dependencyName: string,
+): Promise<OperationFile[]> {
+  const packageJsonPath = resolveDependencyPackageJson(requireFromProject, dependencyName);
+  if (!packageJsonPath) return [];
+  const dependencyPackage = await readPackageJson(packageJsonPath);
+  const specs = dependencyPackage?.vgai?.operations;
+  if (!Array.isArray(specs)) return [];
+  const packageRoot = dirname(packageJsonPath);
+  return specs.flatMap((spec): OperationFile[] => {
+    if (typeof spec !== 'string' || !spec.startsWith('./')) return [];
+    const absolutePath = resolve(packageRoot, spec);
+    if (!absolutePath.startsWith(`${packageRoot}${sep}`)) return [];
+    return [{ absolutePath, sourcePath: `${dependencyName}:${spec.slice(2)}` }];
+  });
+}
+
+async function dependencyOperationFiles(projectRoot: string): Promise<OperationFile[]> {
+  const projectPackage = await readPackageJson(resolve(projectRoot, 'package.json'));
+  if (!projectPackage) return [];
+  const dependencyNames = [
+    ...Object.keys(projectPackage.dependencies ?? {}),
+    ...Object.keys(projectPackage.devDependencies ?? {}),
+  ].sort();
+  const requireFromProject = createRequire(resolve(projectRoot, 'package.json'));
+  return (
+    await Promise.all(
+      dependencyNames.map((name) => advertisedDependencyOperations(requireFromProject, name)),
+    )
+  ).flat();
+}
+
+function operationShape(value: unknown): value is OperationDefinition {
+  if (value === null || typeof value !== 'object') return false;
+  const candidate = value as Partial<OperationDefinition>;
+  return (
+    typeof candidate.name === 'string' &&
+    typeof candidate.summary === 'string' &&
+    typeof candidate.description === 'string' &&
+    candidate.input !== null &&
+    typeof candidate.input === 'object' &&
+    typeof candidate.input.safeParse === 'function' &&
+    candidate.result !== null &&
+    typeof candidate.result === 'object' &&
+    typeof candidate.result.safeParse === 'function' &&
+    Array.isArray(candidate.errors) &&
+    candidate.requires !== null &&
+    typeof candidate.requires === 'object' &&
+    (candidate.host === 'node' ||
+      candidate.host === 'editor-browser' ||
+      candidate.host === 'runtime-page') &&
+    typeof candidate.mutates === 'boolean' &&
+    typeof candidate.supportsDryRun === 'boolean' &&
+    candidate.permission !== null &&
+    typeof candidate.permission === 'object' &&
+    typeof candidate.impl === 'function'
+  );
+}
+
+function jsonSchema(schema: z.ZodType): unknown {
+  return z.toJSONSchema(schema);
+}
+
+function toCatalogEntry(
+  definition: OperationDefinition,
+  sourcePath: string,
+): ProjectOperationCatalogEntry {
+  return {
+    name: definition.name,
+    summary: definition.summary,
+    description: definition.description,
+    sourcePath,
+    inputSchema: jsonSchema(definition.input),
+    resultSchema: jsonSchema(definition.result),
+    errors: definition.errors.map((error) => ({
+      code: error.code,
+      summary: error.summary,
+      ...(error.data ? { dataSchema: jsonSchema(error.data) } : {}),
+    })),
+    requires: { ...definition.requires },
+    host: definition.host,
+    mutates: definition.mutates,
+    supportsDryRun: definition.supportsDryRun,
+    longRunning: definition.longRunning === true,
+    permission: { ...definition.permission },
+  };
+}
+
+async function loadCatalog(
+  projectRoot: string,
+  loadModule: ProjectModuleLoader | undefined,
+): Promise<LoadedCatalog> {
+  const definitions = new Map<string, OperationDefinition>();
+  const operations: ProjectOperationCatalogEntry[] = [];
+  const loadErrors: ProjectOperationLoadError[] = [];
+  const projectFiles = (await findOperationFiles(resolve(projectRoot, 'src', 'operations')))
+    .sort()
+    .map((absolutePath) => ({ absolutePath, sourcePath: projectPath(projectRoot, absolutePath) }));
+  const files = [...projectFiles, ...(await dependencyOperationFiles(projectRoot))].sort((a, b) =>
+    a.sourcePath.localeCompare(b.sourcePath),
+  );
+
+  if (files.length > 0 && !loadModule) {
+    loadErrors.push({
+      sourcePath: 'src/operations',
+      message:
+        'This editor host cannot load project TypeScript modules. Use the Vite-backed dev or packaged editor.',
+    });
+    return { operations, loadErrors, definitions };
+  }
+
+  const registry = new OperationRegistry();
+  for (const { absolutePath, sourcePath } of files) {
+    try {
+      const imported = (await loadModule?.(absolutePath)) as Record<string, unknown> | undefined;
+      const definition = imported?.['operation'];
+      if (!operationShape(definition)) {
+        throw new Error(
+          'does not export a complete `operation` definition; export `operation = defineOperation({...})` from @vgai/sdk/registry',
+        );
+      }
+      if (!definition.name.startsWith('project.')) {
+        throw new Error(
+          `declares ${JSON.stringify(definition.name)}; project-local operation names must start with "project."`,
+        );
+      }
+      if (definition.mutates && definition.permission.risk === 'read') {
+        throw new Error(
+          `declares mutates:true with read risk; mutating operations must declare write or destructive risk`,
+        );
+      }
+      registry.register(definition);
+      const entry = toCatalogEntry(definition, sourcePath);
+      definitions.set(definition.name, definition);
+      operations.push(entry);
+    } catch (error) {
+      loadErrors.push({
+        sourcePath,
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  operations.sort((a, b) => a.name.localeCompare(b.name));
+  return { operations, loadErrors, definitions };
+}
+
+export async function discoverProjectOperations(
+  projectRoot: string,
+  loadModule: ProjectModuleLoader | undefined,
+): Promise<ProjectOperationCatalog> {
+  const { definitions: _definitions, ...catalog } = await loadCatalog(projectRoot, loadModule);
+  return catalog;
+}
+
+export type ProjectOperationExecution =
+  | { status: 200; body: OperationOutcome; changedProject: boolean }
+  | {
+      status: 404 | 409;
+      body: { ok: false; error: { code: string; message: string } };
+      changedProject: false;
+    };
+
+export async function executeProjectOperation(options: {
+  projectRoot: string;
+  loadModule: ProjectModuleLoader | undefined;
+  name: string;
+  input: unknown;
+  confirmed: boolean;
+  signal?: AbortSignal;
+}): Promise<ProjectOperationExecution> {
+  const loaded = await loadCatalog(options.projectRoot, options.loadModule);
+  const definition = loaded.definitions.get(options.name);
+  if (!definition) {
+    return {
+      status: 404,
+      changedProject: false,
+      body: {
+        ok: false,
+        error: {
+          code: 'PROJECT_OPERATION_NOT_FOUND',
+          message: `No loaded project operation is named ${JSON.stringify(options.name)}.`,
+        },
+      },
+    };
+  }
+  if (definition.host !== 'node') {
+    return {
+      status: 409,
+      changedProject: false,
+      body: {
+        ok: false,
+        error: {
+          code: 'PROJECT_OPERATION_HOST_UNAVAILABLE',
+          message:
+            `Project operation ${JSON.stringify(options.name)} declares host ${JSON.stringify(definition.host)}. ` +
+            'Slice 1 executes Node-hosted project operations; call reusable browser/runtime functions directly.',
+        },
+      },
+    };
+  }
+  if ((definition.mutates || definition.permission.risk !== 'read') && !options.confirmed) {
+    return {
+      status: 409,
+      changedProject: false,
+      body: {
+        ok: false,
+        error: {
+          code: 'PROJECT_OPERATION_CONFIRMATION_REQUIRED',
+          message:
+            `${definition.permission.risk} operation ${JSON.stringify(options.name)} requires explicit confirmation: ` +
+            definition.permission.summary,
+        },
+      },
+    };
+  }
+
+  const registry = new OperationRegistry();
+  registry.register(definition);
+  const outcome = await registry.dispatch(options.name, options.input, {
+    projectRoot: options.projectRoot,
+    projectOutputs: createProjectOutputWriter(options.projectRoot),
+    ...(options.signal ? { signal: options.signal } : {}),
+  });
+  return {
+    status: 200,
+    body: outcome,
+    changedProject: definition.mutates && outcome.ok,
+  };
+}

package/server/project-optimize-deps-entries.ts

@@ -58,8 +58,8 @@ export const SERVER_ONLY_PREBUNDLE_EXCLUDE: readonly string[] = [
 /**
  * The project-relative CLIENT entry files `optimizeDeps.entries` should scope
  * Vite's dependency-DISCOVERY crawl to, for the project rooted at
- * `projectRoot` — every `worlds[].entry` its OWN `vgai.game.json` declares
- * (default-adapter, code-authored worlds; scene-only worlds have no `entry`
+ * `projectRoot` — every `roots[].entry` its OWN `vgai.game.json` declares
+ * (default-adapter, code-authored roots; scene-only roots have no `entry`
  * and contribute nothing here — their gameplay code is registered
  * elsewhere, reached transitively from whichever world DOES declare an
  * `entry`, e.g. the template's single world), deduped, and filtered to paths
@@ -84,7 +84,7 @@ export const SERVER_ONLY_PREBUNDLE_EXCLUDE: readonly string[] = [
  * `packaged.ts`'s ORIGINAL reason for `noDiscovery: true`, verified still
  * true on this Vite version at the time of the C3 fix).
  *
- * A manifest's `worlds[].entry` files never reach that chain: they are the
+ * A manifest's `roots[].entry` files never reach that chain: they are the
  * PER-WORLD mount code the editor's own adapter-resolver dynamically imports
  * directly for Play mode / world mounting (never `src/main.ts` — that
  * bootstrap is the STANDALONE build's concern, unrelated to how the editor
@@ -140,7 +140,7 @@ export function computeProjectOptimizeDepsEntries(projectRoot: string): string[]
   }
 
   const entries = new Set<string>();
-  for (const world of manifest.worlds) {
+  for (const world of manifest.roots) {
     if (!world.entry) continue;
     if (!existsSync(join(projectRoot, world.entry))) continue;
     entries.add(world.entry);

package/server/project-output-writer.ts

@@ -0,0 +1,156 @@
+/**
+ * Atomic persistence boundary for files produced by project operations.
+ *
+ * Generators remain ordinary project/package code. They hand their completed
+ * bytes to this writer only when they are ready to commit; the editor host
+ * validates every path, stages the whole batch, and rolls the batch back if
+ * any rename fails. A half-generated model/prefab pair must never become
+ * visible to the asset watcher.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { copyFile, mkdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, posix, resolve, sep } from 'node:path';
+import type {
+  ProjectGeneratedOutput,
+  ProjectGeneratedOutputFile,
+  ProjectOutputFile,
+  ProjectOutputWriter,
+} from '../../vgai-sdk/src/types';
+
+const MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
+
+type NormalizedOutputFile = ProjectOutputFile & { path: string };
+
+function normalizeOutputPath(path: string): string {
+  const slashPath = path.split(sep).join('/');
+  const normalized = posix.normalize(slashPath).replace(/^\.\//, '');
+  if (
+    normalized.length === 0 ||
+    normalized.startsWith('/') ||
+    normalized === 'public' ||
+    !normalized.startsWith('public/') ||
+    normalized.includes('\0') ||
+    normalized.split('/').includes('..')
+  ) {
+    throw new Error(
+      `Generated output path ${JSON.stringify(path)} is invalid; outputs must be project-relative files under public/.`,
+    );
+  }
+  return normalized;
+}
+
+function byteLength(content: string | Uint8Array): number {
+  return typeof content === 'string' ? Buffer.byteLength(content) : content.byteLength;
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function validateBatch(files: readonly ProjectOutputFile[]): {
+  normalized: NormalizedOutputFile[];
+  summaries: ProjectGeneratedOutputFile[];
+  totalBytes: number;
+} {
+  if (files.length === 0) throw new Error('Generated output batch must contain at least one file.');
+  const normalized = files.map((file) => ({ ...file, path: normalizeOutputPath(file.path) }));
+  const paths = new Set<string>();
+  let totalBytes = 0;
+  for (const file of normalized) {
+    if (paths.has(file.path)) {
+      throw new Error(
+        `Generated output batch contains duplicate path ${JSON.stringify(file.path)}.`,
+      );
+    }
+    paths.add(file.path);
+    totalBytes += byteLength(file.content);
+  }
+  if (totalBytes > MAX_OUTPUT_BYTES) {
+    throw new Error(
+      `Generated output batch is ${totalBytes} bytes; the atomic project-output limit is ${MAX_OUTPUT_BYTES} bytes.`,
+    );
+  }
+  return {
+    normalized,
+    totalBytes,
+    summaries: normalized.map((file) => ({
+      path: file.path,
+      bytes: byteLength(file.content),
+      ...(file.mediaType ? { mediaType: file.mediaType } : {}),
+      ...(file.role ? { role: file.role } : {}),
+    })),
+  };
+}
+
+async function stageBatch(stagedRoot: string, files: readonly NormalizedOutputFile[]) {
+  for (const file of files) {
+    const staged = resolve(stagedRoot, file.path);
+    await mkdir(dirname(staged), { recursive: true });
+    await writeFile(staged, file.content);
+  }
+}
+
+async function commitBatch(
+  projectRoot: string,
+  stagedRoot: string,
+  backupRoot: string,
+  files: readonly NormalizedOutputFile[],
+): Promise<void> {
+  const committed: Array<{ target: string; backup: string | null }> = [];
+  try {
+    for (const file of files) {
+      const staged = resolve(stagedRoot, file.path);
+      const target = resolve(projectRoot, file.path);
+      const backup = resolve(backupRoot, file.path);
+      await mkdir(dirname(target), { recursive: true });
+      let prior: string | null = null;
+      if (await exists(target)) {
+        await mkdir(dirname(backup), { recursive: true });
+        await copyFile(target, backup);
+        prior = backup;
+      }
+      await rename(staged, target);
+      committed.push({ target, backup: prior });
+    }
+  } catch (error) {
+    for (const entry of committed.reverse()) {
+      if (entry.backup) await copyFile(entry.backup, entry.target);
+      else await rm(entry.target, { force: true });
+    }
+    throw error;
+  }
+}
+
+export function createProjectOutputWriter(projectRoot: string): ProjectOutputWriter {
+  return {
+    async write(files, options = {}): Promise<ProjectGeneratedOutput> {
+      const { normalized, summaries, totalBytes } = validateBatch(files);
+      if (options.dryRun === true) {
+        return { files: summaries, totalBytes, dryRun: true };
+      }
+
+      const transactionRoot = resolve(
+        projectRoot,
+        '.vgai',
+        'tmp',
+        `project-output-${randomUUID()}`,
+      );
+      const stagedRoot = resolve(transactionRoot, 'staged');
+      const backupRoot = resolve(transactionRoot, 'backup');
+      try {
+        await stageBatch(stagedRoot, normalized);
+        await commitBatch(projectRoot, stagedRoot, backupRoot, normalized);
+      } finally {
+        await rm(transactionRoot, { recursive: true, force: true });
+      }
+
+      return { files: summaries, totalBytes, dryRun: false };
+    },
+  };
+}

package/server/project-validation.ts

@@ -0,0 +1,140 @@
+/**
+ * Validate-on-change (owner decision, GitHub issue #103): hand-editing
+ * project files is an accepted authoring path, so the dev server validates
+ * `*.vscn.json` / `*.prefab.json` / `vgai.game.json` on every write and
+ * surfaces failures immediately — instead of the previous behavior, where a
+ * bad hand-edit only errored at next load.
+ *
+ * This module owns CONTENT validation only (classify a path, parse+validate
+ * its JSON) — it deliberately reuses the exact Zod-backed parsers
+ * `validate-scenes.ts`/`validate-manifest.ts` ship to every project
+ * (`parseSceneFile`/`parsePrefabFile`/`loadGameManifest`), never
+ * re-implementing schema logic. Debouncing, terminal/SSE/state reporting,
+ * and file-watcher wiring live in `editor-server.ts`, which owns the
+ * chokidar watchers and mutable project state this needs no knowledge of.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { ZodError } from 'zod';
+import { loadGameManifest } from '../../engine/src/manifest/load';
+import { detectUnmanagedReactRoots } from '../../engine/src/react/unmanaged-root-detector';
+import { parsePrefabFile, parseSceneFile, SceneParseError } from '../../engine/src/scene/parse';
+
+export type ValidatableKind = 'scene' | 'prefab' | 'manifest' | 'source';
+
+/**
+ * Classify an absolute file path as one of the three validate-on-change
+ * formats, or `null` if it's none of them. Scene/prefab files can nest
+ * anywhere under a project's `public/` (matched by extension); the manifest
+ * is a single fixed-name file at the project root (matched by basename —
+ * `vgai.game.json` never appears anywhere else in a project).
+ */
+export function classifyValidatableFile(absPath: string): ValidatableKind | null {
+  if (absPath.endsWith('.vscn.json')) return 'scene';
+  if (absPath.endsWith('.prefab.json')) return 'prefab';
+  if (/[/\\]src[/\\].*\.[cm]?[jt]sx?$/.test(absPath)) return 'source';
+  const base = absPath.split(/[/\\]/).pop();
+  if (base === 'vgai.game.json') return 'manifest';
+  return null;
+}
+
+export interface ValidationOk {
+  ok: true;
+}
+
+export interface ValidationFail {
+  ok: false;
+  /** One formatted message per issue — `path.to.field: message` for Zod
+   *  issues, or the raw error message for read/parse/cross-field failures. */
+  errors: string[];
+}
+
+export type ValidationResult = ValidationOk | ValidationFail;
+
+function formatIssues(
+  issues: readonly { path: readonly PropertyKey[]; message: string }[],
+): string[] {
+  // Zod v4's issue `path` is typed `PropertyKey[]` (it can carry a `symbol`
+  // for branded keys) — `Array.prototype.join` calls the implicit `ToString`
+  // coercion on each element, which THROWS for a bare symbol. Map through
+  // `String()` explicitly so this stays safe even on that rare path.
+  return issues.map((issue) => `${issue.path.map(String).join('.') || '(root)'}: ${issue.message}`);
+}
+
+/** Run the one Zod-backed parser `kind` dictates. Throws on failure (same
+ *  contract as `parseSceneFile`/`parsePrefabFile`/`loadGameManifest`) —
+ *  `validateProjectFile` below is the one place that catches it. */
+function parseByKind(json: unknown, kind: ValidatableKind, absPath: string): void {
+  if (kind === 'scene') {
+    parseSceneFile(json, absPath);
+  } else if (kind === 'prefab') {
+    parsePrefabFile(json, absPath);
+  } else {
+    loadGameManifest(json);
+  }
+}
+
+/** Map a thrown parse error to its reported message list — one formatted
+ *  entry per Zod issue for schema violations, or the raw message for a
+ *  manifest cross-field `Error` (`loadGameManifest` throws those directly). */
+function errorsFor(err: unknown): string[] {
+  if (err instanceof SceneParseError) return formatIssues(err.issues);
+  if (err instanceof ZodError) return formatIssues(err.issues);
+  return [err instanceof Error ? err.message : String(err)];
+}
+
+/**
+ * Validate one project file's on-disk content against the same schema the
+ * engine's runtime loader and `validate-scenes.ts`/`validate-manifest.ts`
+ * enforce. Never throws — a file-watcher callback has no caller to catch a
+ * throw, so every failure mode (unreadable file, malformed JSON, schema
+ * violation, manifest cross-field rule) collapses into a `ValidationFail`
+ * with one or more human-readable messages.
+ */
+export async function validateProjectFile(
+  absPath: string,
+  kind: ValidatableKind,
+): Promise<ValidationResult> {
+  let raw: string;
+  try {
+    raw = await readFile(absPath, 'utf-8');
+  } catch (err) {
+    // Most commonly ENOENT — a delete (or a rename's transient unlink) racing
+    // the debounce timer. Not this module's job to distinguish; just report.
+    return {
+      ok: false,
+      errors: [`could not read file: ${err instanceof Error ? err.message : String(err)}`],
+    };
+  }
+
+  let json: unknown;
+  if (kind === 'source') {
+    const findings = detectUnmanagedReactRoots(raw, absPath);
+    return findings.length === 0
+      ? { ok: true }
+      : {
+          ok: false,
+          errors: findings.map(
+            (finding) =>
+              `line ${finding.line}: ${finding.api}() creates an unmanaged React root; ` +
+              'declare a react adapter root in vgai.game.json and default-export the component.',
+          ),
+        };
+  }
+
+  try {
+    json = JSON.parse(raw);
+  } catch (err) {
+    return {
+      ok: false,
+      errors: [`invalid JSON: ${err instanceof Error ? err.message : String(err)}`],
+    };
+  }
+
+  try {
+    parseByKind(json, kind, absPath);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, errors: errorsFor(err) };
+  }
+}