@vgai/editor 0.4.0 → 0.4.1

package/server/project-operations.ts

@@ -1,343 +0,0 @@
-/**
- * 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/src/components/project-operation-documents.tsx

@@ -1,226 +0,0 @@
-import { useMemo, useState, useSyncExternalStore } from 'react';
-import type { EditorAction } from '../action-registry';
-import { Button, bg, border, danger, fontSize, radius, text } from '../design-system';
-import {
-  getProjectOperations,
-  projectOperationsVersion,
-  runProjectOperation,
-  subscribeProjectOperations,
-} from '../project-operations';
-import {
-  openWorkspaceDocument,
-  type WorkspaceDocumentContentProps,
-} from '../workspace-document-registry';
-
-const CATALOG_DOCUMENT_ID = 'project-operations';
-const OPERATION_DOCUMENT_PREFIX = 'project-operation:';
-
-export interface ProjectOperationDocumentStore {
-  setActiveViewportTab(tab: 'scene' | 'game'): void;
-}
-
-function operationDocumentId(name: string): string {
-  return `${OPERATION_DOCUMENT_PREFIX}${name}`;
-}
-
-export function openProjectOperationsDocument(store: ProjectOperationDocumentStore): void {
-  openWorkspaceDocument({
-    id: CATALOG_DOCUMENT_ID,
-    title: 'Project Commands',
-    kind: 'operation',
-    Content: ProjectOperationDocumentContent,
-    closeable: true,
-    onActivate: () => store.setActiveViewportTab('scene'),
-  });
-}
-
-export function openProjectOperationDocument(
-  store: ProjectOperationDocumentStore | null,
-  name: string,
-): boolean {
-  const operation = getProjectOperations().operations.find((entry) => entry.name === name);
-  if (!operation) return false;
-  openWorkspaceDocument({
-    id: operationDocumentId(name),
-    title: operation.summary || operation.name,
-    kind: 'operation',
-    provenance: { sourcePath: operation.sourcePath, origin: operation.name },
-    Content: ProjectOperationDocumentContent,
-    closeable: true,
-    ...(store ? { onActivate: () => store.setActiveViewportTab('scene') } : {}),
-  });
-  return true;
-}
-
-export function buildProjectOperationActions(store: ProjectOperationDocumentStore): EditorAction[] {
-  return [
-    {
-      id: 'project-operations:open',
-      label: 'Open Project Commands',
-      category: 'action',
-      execute: () => openProjectOperationsDocument(store),
-    },
-    ...getProjectOperations().operations.map((operation) => ({
-      id: `project-operation:${operation.name}`,
-      label: `Run: ${operation.summary || operation.name}`,
-      category: 'action' as const,
-      execute: () => void openProjectOperationDocument(store, operation.name),
-    })),
-  ];
-}
-
-function JsonBlock({ value }: { value: unknown }) {
-  return <pre style={jsonStyle}>{JSON.stringify(value, null, 2)}</pre>;
-}
-
-export function ProjectOperationDocumentContent({ documentId }: WorkspaceDocumentContentProps) {
-  useSyncExternalStore(subscribeProjectOperations, projectOperationsVersion);
-  const snapshot = getProjectOperations();
-  const operationName = documentId.startsWith(OPERATION_DOCUMENT_PREFIX)
-    ? documentId.slice(OPERATION_DOCUMENT_PREFIX.length)
-    : null;
-  const operation = operationName
-    ? snapshot.operations.find((entry) => entry.name === operationName)
-    : null;
-  const [inputText, setInputText] = useState('{}');
-  const [result, setResult] = useState<unknown>(null);
-  const [running, setRunning] = useState(false);
-  const [inputError, setInputError] = useState<string | null>(null);
-  const parsedSchema = useMemo(() => operation?.inputSchema ?? {}, [operation]);
-
-  if (!operationName) {
-    return (
-      <div style={rootStyle} data-testid="project-operations-catalog">
-        <h2 style={headingStyle}>Project Commands</h2>
-        <p style={mutedStyle}>
-          Auto-discovered from nested <code>src/operations/*.operation.ts</code> files. Commands are
-          ordinary project functions with a validated tooling boundary; custom interfaces live in{' '}
-          <code>src/tools/</code>.
-        </p>
-        {snapshot.operations.map((entry) => (
-          <Button
-            key={entry.name}
-            type="button"
-            className="vgai-operation-card"
-            onClick={() => openProjectOperationDocument(null, entry.name)}
-            data-testid={`project-command-card:${entry.name}`}
-          >
-            <div style={{ color: text[1] }}>{entry.summary}</div>
-            <code style={mutedStyle}>{entry.name}</code>
-            <div style={mutedStyle}>
-              {entry.host} · {entry.permission.risk} · {entry.sourcePath}
-            </div>
-          </Button>
-        ))}
-        {snapshot.operations.length === 0 && snapshot.loadErrors.length === 0 && (
-          <div style={mutedStyle}>No project commands found.</div>
-        )}
-        {snapshot.loadErrors.map((error) => (
-          <div key={`${error.sourcePath}:${error.message}`} style={errorStyle}>
-            {error.sourcePath}: {error.message}
-          </div>
-        ))}
-      </div>
-    );
-  }
-
-  if (!operation) {
-    return <div style={rootStyle}>This operation is no longer available.</div>;
-  }
-
-  const runnable = operation.host === 'node';
-  const execute = async () => {
-    let input: unknown;
-    try {
-      input = JSON.parse(inputText);
-      setInputError(null);
-    } catch (error) {
-      setInputError(error instanceof Error ? error.message : String(error));
-      return;
-    }
-    const confirm =
-      operation.permission.risk === 'read' ||
-      window.confirm(`${operation.permission.summary}\n\nRun ${operation.name}?`);
-    if (!confirm) return;
-    setRunning(true);
-    try {
-      setResult(await runProjectOperation(operation.name, input, { confirm: true }));
-    } catch (error) {
-      setResult({ ok: false, error: { code: 'REQUEST_FAILED', message: String(error) } });
-    } finally {
-      setRunning(false);
-    }
-  };
-
-  return (
-    <div style={rootStyle} data-testid={`project-operation:${operation.name}`}>
-      <h2 style={headingStyle}>{operation.summary}</h2>
-      <code style={{ color: text[2] }}>{operation.name}</code>
-      <p style={{ color: text[2] }}>{operation.description}</p>
-      <div style={mutedStyle}>
-        {operation.host} · {operation.permission.risk} · {operation.sourcePath}
-      </div>
-      {!runnable && (
-        <div style={errorStyle}>
-          This command runner supports Node-hosted operations. Import the underlying function
-          directly in browser or runtime code.
-        </div>
-      )}
-      <label style={labelStyle} htmlFor={`operation-input:${operation.name}`}>
-        Input JSON
-      </label>
-      <textarea
-        id={`operation-input:${operation.name}`}
-        value={inputText}
-        onChange={(event) => setInputText(event.target.value)}
-        rows={10}
-        style={textareaStyle}
-      />
-      {inputError && <div style={errorStyle}>{inputError}</div>}
-      <Button type="button" disabled={!runnable || running} onClick={() => void execute()}>
-        {running ? 'Running…' : 'Run command'}
-      </Button>
-      <details>
-        <summary style={labelStyle}>Input schema</summary>
-        <JsonBlock value={parsedSchema} />
-      </details>
-      {result !== null && (
-        <section>
-          <div style={labelStyle}>Result</div>
-          <JsonBlock value={result} />
-        </section>
-      )}
-    </div>
-  );
-}
-
-const rootStyle: React.CSSProperties = {
-  padding: 16,
-  overflow: 'auto',
-  pointerEvents: 'auto',
-  color: text[1],
-  fontSize: fontSize.base,
-};
-const headingStyle: React.CSSProperties = { margin: '0 0 8px', fontSize: 18 };
-const mutedStyle: React.CSSProperties = { color: text[2], fontSize: fontSize.sm };
-const labelStyle: React.CSSProperties = { display: 'block', margin: '14px 0 6px', color: text[1] };
-const errorStyle: React.CSSProperties = { marginTop: 10, color: danger, whiteSpace: 'pre-wrap' };
-const textareaStyle: React.CSSProperties = {
-  width: '100%',
-  boxSizing: 'border-box',
-  padding: 10,
-  resize: 'vertical',
-  background: bg.inset,
-  color: text[1],
-  border: `1px solid ${border[2]}`,
-  borderRadius: radius.sm,
-  fontFamily: 'monospace',
-};
-const jsonStyle: React.CSSProperties = {
-  overflow: 'auto',
-  padding: 10,
-  background: bg.inset,
-  border: `1px solid ${border[1]}`,
-  borderRadius: radius.sm,
-  color: text[2],
-};

package/template/src/operations/README.md

@@ -1,88 +0,0 @@
-# src/operations — discoverable project scripts
-
-Put tooling-facing operations in `*.operation.ts` files here. They remain
-ordinary TypeScript modules. Keep reusable implementation in a normal project
-module, then wrap it with one thin `operation` definition.
-
-```ts
-// src/automation/inspect-something.ts
-export async function inspectSomething(input: { path: string }) {
-  return { path: input.path };
-}
-```
-
-```ts
-// src/operations/inspect-something.operation.ts
-import { defineOperation } from '@vgai/sdk/registry';
-import { z } from 'zod';
-import { inspectSomething } from '../automation/inspect-something';
-
-export const operation = defineOperation({
-  name: 'project.inspectSomething',
-  summary: 'Inspect something owned by this project.',
-  description: 'A project-local operation. The implementation remains directly importable.',
-  input: z.object({ path: z.string() }),
-  result: z.object({ path: z.string() }),
-  errors: [],
-  requires: { project: true },
-  host: 'node',
-  mutates: false,
-  supportsDryRun: false,
-  permission: { risk: 'read', summary: 'Reads project-local information.' },
-  impl: inspectSomething,
-});
-```
-
-The editor discovers these files without a registry. List them for agents with
-`npm run vgai -- run --list --json`; inspect one with
-`npm run vgai -- run project.inspectSomething --describe`; run it with
-`npm run vgai -- run project.inspectSomething --input input.json` while the
-project editor is running. The editor also provides a directly clickable
-Project Commands catalog and a default JSON/schema UI.
-
-For a frequent workflow, an ordinary package script may be a shortcut:
-
-```json
-{
-  "scripts": {
-    "inspect-project": "npm run vgai -- run project.inspectSomething"
-  }
-}
-```
-
-That script is convenience, not registration; deleting it does not remove the
-capability from the editor or catalog.
-
-For a custom UI, add an ordinary `src/tools/*.tool.tsx` project tool and call
-the same operation through the public editor SDK:
-
-```ts
-import { EditorClient } from '@vgai/editor-sdk';
-
-const editor = new EditorClient({ url: window.location.origin });
-const result = await editor.runProjectOperation('project.buildCharacter', input, {
-  confirm: true,
-});
-if (result.ok) await editor.openAsset('/characters/generated.glb', 'model');
-```
-
-Keep React/editor imports out of the operation module. If the operation writes
-ordinary files under `public/`, a successful declared mutation refreshes the
-project's Assets navigator automatically. The generator is a tool/command; its
-persisted files are assets. It does not become an Asset Library tile.
-
-Game/runtime code should import the underlying function directly rather than
-calling through the tooling registry.
-
-Installed packages can advertise operations from their own `package.json`
-using `{"vgai":{"operations":["./path/to/file.operation.js"]}}`. The editor
-loads direct dependencies only and reports the package-qualified source path.
-This is how a library can provide an optional author-time bake/import command
-without adding a domain switch to the editor or copying wrappers into every
-project.
-
-Node operations that generate assets receive `ctx.projectOutputs`. Hand it a
-complete batch of ordinary files under `public/`; the host validates all paths,
-stages the batch, commits it atomically, and returns a JSON-safe output
-manifest. Use `{ dryRun: true }` to validate without writing. Successful writes
-refresh the Assets navigator automatically.