@volter/editor-core 0.5.57

package/server/support/project/inspection-node.ts

@@ -0,0 +1,119 @@
+/** Node filesystem binding for the shared, read-only project inspector. */
+
+import { readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import { resolveManifestPath } from '@volter/editor-project/manifest/locate';
+import {
+  createIngestManifest,
+  inspectProject,
+  type ProjectInspection,
+  type ProjectInspectionReader,
+  type SuggestedAdapterSurface,
+} from '@volter/editor-project/inspection';
+import { resolveProjectPath } from './shared.js';
+
+export type { SuggestedAdapterSurface } from '@volter/editor-project/inspection';
+
+export function nodeProjectInspectionReader(root: string): ProjectInspectionReader {
+  return {
+    async exists(path) {
+      try {
+        await stat(resolveProjectPath(root, path));
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    read(path) {
+      return readFile(resolveProjectPath(root, path), 'utf-8');
+    },
+    async list(path) {
+      const entries = await readdir(resolveProjectPath(root, path), { withFileTypes: true });
+      return entries
+        .filter((entry) => !entry.isSymbolicLink())
+        .map((entry) => ({
+          name: entry.name,
+          path: path ? `${path.replace(/\\/g, '/')}/${entry.name}` : entry.name,
+          type: entry.isDirectory() ? ('dir' as const) : ('file' as const),
+        }));
+    },
+  };
+}
+
+export async function inspectProjectFolderPath(path: string): Promise<{
+  path: string;
+  report: ProjectInspection;
+}> {
+  const root = resolve(path);
+  const rootStat = await stat(root);
+  if (!rootStat.isDirectory()) throw new Error(`Project path is not a directory: ${root}`);
+  return { path: root, report: await inspectProject(nodeProjectInspectionReader(root)) };
+}
+
+export async function adaptProjectFolderPath(
+  path: string,
+  options: {
+    engineVersion: string;
+    surface?: SuggestedAdapterSurface | undefined;
+    entry?: string | undefined;
+  },
+): Promise<{ path: string; writes: ['vgai.project.json']; manifest: Record<string, unknown> }> {
+  const preview = await previewAdaptProjectFolderPath(path, options);
+  await writeFile(
+    resolveManifestPath(preview.path),
+    `${JSON.stringify(preview.manifest, null, 2)}\n`,
+    {
+      encoding: 'utf-8',
+      flag: 'wx',
+    },
+  );
+  return { path: preview.path, writes: ['vgai.project.json'], manifest: preview.manifest };
+}
+
+/** Build the exact proposed sidecar without writing it. */
+export async function previewAdaptProjectFolderPath(
+  path: string,
+  options: {
+    engineVersion: string;
+    surface?: SuggestedAdapterSurface | undefined;
+    entry?: string | undefined;
+  },
+): Promise<{
+  path: string;
+  report: ProjectInspection;
+  writes: [];
+  manifest: Record<string, unknown>;
+}> {
+  const root = resolve(path);
+  const rootStat = await stat(root);
+  if (!rootStat.isDirectory()) throw new Error(`Project path is not a directory: ${root}`);
+  const report = await inspectProject(nodeProjectInspectionReader(root));
+  if (report.hasManifest) throw new Error('This folder already has a vgai.project.json manifest.');
+  let name = basename(root);
+  try {
+    const packageJson = JSON.parse(
+      await readFile(resolveProjectPath(root, 'package.json'), 'utf-8'),
+    ) as {
+      name?: unknown;
+    };
+    if (typeof packageJson.name === 'string' && packageJson.name.length > 0)
+      name = packageJson.name;
+  } catch {}
+  const selectedEntry = options.entry ?? report.entryCandidates[0];
+  if (selectedEntry !== undefined) {
+    const entryPath = resolveProjectPath(root, selectedEntry);
+    let entryStat: Awaited<ReturnType<typeof stat>>;
+    try {
+      entryStat = await stat(entryPath);
+    } catch {
+      throw new Error(`Adapter entry does not exist: ${selectedEntry}`);
+    }
+    if (!entryStat.isFile()) throw new Error(`Adapter entry is not a file: ${selectedEntry}`);
+  }
+  const manifest = createIngestManifest(report, {
+    name,
+    ...options,
+    ...(selectedEntry !== undefined ? { entry: selectedEntry } : {}),
+  });
+  return { path: root, report, writes: [], manifest };
+}

package/server/support/project/log-naming.ts

@@ -0,0 +1,54 @@
+/**
+ * The play log's NAMING scheme, defined once. The dev server mints the files
+ * in `routes/logs.ts`, and every downstream reader (`vgai status`'s
+ * play-error banner, `@vgai/sdk/build-discipline`'s evidence walk, the
+ * pruner, the session catalog) sorts them lexicographically and expects
+ * chronological order. Moved here from `server/recent-projects-store.ts`
+ * (which re-exports for its existing importers) so the browser build can
+ * import the functions without that module's `node:os` scope.
+ */
+
+import { MAX_RUN_NAME } from './run-name';
+
+export function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+/** `slugify` under a length bound, or `null` when nothing survives (blank
+ *  name, punctuation only) — an unnamed run and an unnameable one are the
+ *  same case, and both must fall back to the unnamed filename exactly.
+ *
+ *  The bound comes from `@vgai/sdk`'s run-name module rather than a literal
+ *  here: a playtest run derives its own name against the same ceiling, and two
+ *  copies of "40" is how the derived name and the filename it lands in start
+ *  disagreeing. */
+export function playRunSlug(name: string | null | undefined): string | null {
+  if (typeof name !== 'string') return null;
+  const slug = slugify(name).slice(0, MAX_RUN_NAME).replace(/-$/, '');
+  return slug === '' ? null : slug;
+}
+
+/**
+ * A play session's JSONL filename.
+ *
+ * `play-<stamp>-<sequence>.jsonl` unchanged when the run is unnamed — that
+ * shape is depended on by the newest-log readers (`vgai status`'s play-error
+ * banner, `@vgai/sdk/build-discipline`'s evidence walk) and by the pruner, all
+ * of which sort lexicographically and expect chronological order.
+ *
+ * An OPTIONAL name is appended AFTER the sequence for exactly that reason: the
+ * ordering prefix is untouched, so naming a run changes only what a human
+ * greps for. There is deliberately no registry and no uniqueness check —
+ * two runs with the same name are two files with different stamps, and the
+ * filesystem is the query engine.
+ */
+export function playLogFilename(startedAt: Date, sequence: number, name?: string | null): string {
+  // Milliseconds plus a process-local sequence make restart artifacts
+  // distinct even when two sessions begin inside the same millisecond.
+  const ts = startedAt.toISOString().replace(/[:.]/g, '-');
+  const slug = playRunSlug(name);
+  return `play-${ts}-${String(sequence).padStart(4, '0')}${slug ? `-${slug}` : ''}.jsonl`;
+}

package/server/support/project/provenance.ts

@@ -0,0 +1,290 @@
+import { z } from 'zod';
+import { GenerationBillingSchema } from '@volter/editor-sdk/generations';
+
+export const PROJECT_PROVENANCE_PATH = '.vgai/provenance.json';
+
+export const ProjectProvenanceOutputSchema = z
+  .object({
+    path: z.string(),
+    bytes: z.number().int().nonnegative(),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    mediaType: z.string().optional(),
+    role: z.enum(['asset', 'prefab', 'provenance', 'other']).optional(),
+  })
+  .strict();
+
+export const ProjectProvenanceExecutionSchema = z
+  .object({
+    mode: z.enum(['mock', 'direct', 'managed']),
+    provider: z.string(),
+    operation: z.string().optional(),
+    model: z.string().optional(),
+    requestId: z.string().optional(),
+    taskId: z.string().optional(),
+    managedJobId: z.string().optional(),
+    billing: GenerationBillingSchema.optional(),
+  })
+  .strict();
+
+/**
+ * THE KIND FOR A FILE AN EDITOR SESSION WROTE INTO THE PROJECT.
+ *
+ * A generated binary under `public/` normally arrives from an operation that
+ * ran here: a bake, a provider acceptance, a library acquisition. A file a
+ * SESSION produced has no such operation — the bytes were made by a script an
+ * agent ran inside the tab (`export_scene.gltf` in the Blender session's own
+ * worker filesystem) and reached disk through the write-back door that mirrors
+ * the session's files out. Measured 2026-09-18: those landed with no record at
+ * all, which is the one state `scripts/validate-project-provenance.mjs` calls
+ * fatal.
+ *
+ * The producing PROGRAM is the session, so what the record can honestly name is
+ * the session — see {@link ProjectProvenanceSessionSchema}. That block is
+ * REQUIRED on a record of this kind, and the validator enforces it, for the
+ * same reason `project.provenance.unknown` must carry a written reason: a kind
+ * that can be claimed without evidence becomes the cheapest way past the gate.
+ *
+ * `scripts/validate-project-provenance.mjs` spells this literal itself (it is a
+ * plain `.mjs` gate and imports no TypeScript); changing it here means changing
+ * it there.
+ */
+export const PROJECT_SESSION_WRITE_OPERATION = 'project.session.write';
+
+/**
+ * WHICH SESSION wrote the bytes, and what it had modelled at the time.
+ *
+ * Not a provider execution: no vendor ran, nothing was billed, and there is no
+ * request to re-issue. What re-derives the file is the session's own state, so
+ * the identity (which session, reached on which port) and the `revision` that
+ * state was at are the facts worth keeping.
+ */
+export const ProjectProvenanceSessionSchema = z
+  .object({
+    id: z
+      .string()
+      .min(1)
+      .describe(
+        "The session's own id, as the session names itself to the tab in every " +
+          'frame it presents. Distinguishes two sessions of the same project, ' +
+          'including one restarted between two writes to the same path.',
+      ),
+    port: z
+      .number()
+      .int()
+      .positive()
+      .describe(
+        'The machine-local editor port the writer reached that session on — the ' +
+          "project's own reserved port, which is how a person or an agent gets " +
+          'back to the tab this file came out of.',
+      ),
+    revision: z
+      .number()
+      .int()
+      .nonnegative()
+      .describe(
+        "The session's frame revision at the moment the file was listed for " +
+          'write-back: the model state that produced these bytes. It advances ' +
+          'once per present, and a script presents when it finishes, so this is ' +
+          'the revision the writing script left behind.',
+      ),
+    callId: z
+      .string()
+      .min(1)
+      .optional()
+      .describe(
+        "The transport's own id for the call that ran the script, when the " +
+          'transport has one (the MCP request id). Absent when the write did not ' +
+          'arrive through a call the transport numbered.',
+      ),
+  })
+  .strict();
+
+/**
+ * THE KIND FOR BYTES ALREADY ON DISK, RE-RECORDED AGAINST A LIVE DOOR.
+ *
+ * The ledger is an append-only log of operations that really happened, so a
+ * record whose `operation.source` names a tool that has since been deleted or
+ * renamed cannot be rewritten — it is what happened. What it can no longer do
+ * is tell a reader which door rebuilds the file. An ATTEST record is the
+ * append that answers that: nothing ran, nothing was re-baked, the bytes were
+ * hashed where they lie, and `input.attests` names the operation that would
+ * produce them today.
+ *
+ * It is the weakest claim in the vocabulary, so it pays the same price as
+ * `project.provenance.unknown`: `input.reason` is REQUIRED and
+ * `scripts/validate-project-provenance.mjs` enforces it, because a kind that
+ * can be claimed with no evidence is the cheapest way past a gate. An attest
+ * is never a substitute for running the door when the door CAN be run — it
+ * exists for the case where re-running would change the bytes a project
+ * already ships.
+ *
+ * Written by `attestExistingProjectOutputs`
+ * (`packages/editor/server/project-output-writer.ts`), driven by
+ * `scripts/attest-project-output.ts`. The validator spells this literal
+ * itself (it is a plain `.mjs` gate and imports no TypeScript); changing it
+ * here means changing it there.
+ */
+export const PROJECT_ATTEST_OPERATION = 'project.provenance.attest';
+
+export const ProjectProvenanceOperationSchema = z
+  .object({
+    createdAt: z.string().datetime(),
+    operation: z
+      .object({
+        name: z.string(),
+        source: z.string().optional(),
+      })
+      .strict(),
+    execution: ProjectProvenanceExecutionSchema.optional(),
+    executions: z.array(ProjectProvenanceExecutionSchema).min(2).optional(),
+    session: ProjectProvenanceSessionSchema.optional().describe(
+      'The editor session that wrote these bytes. Required on a ' +
+        '`project.session.write` record, and meaningless on any other kind.',
+    ),
+    input: z.json().optional(),
+    inputs: z
+      .array(z.string().min(1))
+      .min(1)
+      .optional()
+      .describe(
+        'Project-relative paths of the project FILES these bytes were produced ' +
+          'from — a session-written GLB names the `src/models/<name>.blend` it ' +
+          'was exported from. This is what lets a reader go DOWN by kind: a ' +
+          'prefab uses a glTF, and opening that glTF\'s model needs the export ' +
+          'to name its input (ARCHITECTURE-CORE §Roots, "Drilling goes DOWN by ' +
+          'kind"). Distinct from `input`, which is the operation\'s ARGUMENTS; ' +
+          'these are files on disk, and `scripts/validate-project-provenance.mjs` ' +
+          'reports one that no longer exists as DANGLING rather than fatal — a ' +
+          'renamed source is history, not a broken ledger.',
+      ),
+    outputs: z.array(ProjectProvenanceOutputSchema).min(1),
+  })
+  .strict();
+
+export const ProjectProvenanceDocumentSchema = z
+  .object({
+    version: z.literal(1),
+    operations: z.record(z.string(), ProjectProvenanceOperationSchema),
+  })
+  .strict();
+
+export type ProjectProvenanceDocument = z.infer<typeof ProjectProvenanceDocumentSchema>;
+export type ProjectProvenanceOperation = z.infer<typeof ProjectProvenanceOperationSchema>;
+export type ProjectProvenanceExecution = z.infer<typeof ProjectProvenanceExecutionSchema>;
+export type ProjectProvenanceSession = z.infer<typeof ProjectProvenanceSessionSchema>;
+
+export const ProjectAttributionEntrySchema = z
+  .object({
+    key: z.string(),
+    name: z.string().optional(),
+    source: z.string().optional(),
+    sourceUrl: z.string().url().optional(),
+    author: z.string(),
+    license: z.string(),
+    text: z.string(),
+    operationIds: z.array(z.string()),
+    outputPaths: z.array(z.string()),
+  })
+  .strict();
+
+export const ProjectAttributionReportSchema = z
+  .object({
+    version: z.literal(1),
+    entries: z.array(ProjectAttributionEntrySchema),
+  })
+  .strict();
+
+export type ProjectAttributionEntry = z.infer<typeof ProjectAttributionEntrySchema>;
+export type ProjectAttributionReport = z.infer<typeof ProjectAttributionReportSchema>;
+
+export function emptyProjectProvenanceDocument(): ProjectProvenanceDocument {
+  return { version: 1, operations: {} };
+}
+
+function objectRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function stringField(record: Record<string, unknown>, key: string): string | undefined {
+  const value = record[key];
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function attributionEntry(
+  operationId: string,
+  operation: ProjectProvenanceOperation,
+): ProjectAttributionEntry | null {
+  const input = objectRecord(operation.input);
+  if (!input) return null;
+  const nested = objectRecord(input['attribution']) ?? {};
+  const author = stringField(nested, 'author') ?? stringField(input, 'author');
+  const license = stringField(nested, 'license') ?? stringField(input, 'license');
+  if (!author || !license) return null;
+  const name = stringField(nested, 'name') ?? stringField(input, 'name');
+  const source = stringField(nested, 'source') ?? stringField(input, 'source');
+  const sourceUrl = stringField(nested, 'sourceUrl') ?? stringField(input, 'sourceUrl');
+  const text = stringField(nested, 'text') ?? `${name ? `${name} by ` : ''}${author} (${license})`;
+  const key = JSON.stringify([sourceUrl ?? '', author, license, text]);
+  return ProjectAttributionEntrySchema.parse({
+    key,
+    ...(name ? { name } : {}),
+    ...(source ? { source } : {}),
+    ...(sourceUrl ? { sourceUrl } : {}),
+    author,
+    license,
+    text,
+    operationIds: [operationId],
+    outputPaths: operation.outputs
+      .filter((output) => output.role !== 'provenance')
+      .map((output) => output.path),
+  });
+}
+
+/**
+ * Project credits are a projection of central provenance, never another
+ * persisted ledger or a set of per-asset files.
+ */
+export function deriveProjectAttributionReport(
+  document: ProjectProvenanceDocument,
+): ProjectAttributionReport {
+  const grouped = new Map<string, ProjectAttributionEntry>();
+  for (const [operationId, operation] of Object.entries(document.operations)) {
+    const entry = attributionEntry(operationId, operation);
+    if (!entry) continue;
+    const prior = grouped.get(entry.key);
+    if (!prior) {
+      grouped.set(entry.key, entry);
+      continue;
+    }
+    prior.operationIds.push(...entry.operationIds);
+    prior.outputPaths.push(...entry.outputPaths);
+  }
+  const entries = [...grouped.values()]
+    .map((entry) => ({
+      ...entry,
+      operationIds: [...new Set(entry.operationIds)].sort(),
+      outputPaths: [...new Set(entry.outputPaths)].sort(),
+    }))
+    .sort(
+      (left, right) => left.text.localeCompare(right.text) || left.key.localeCompare(right.key),
+    );
+  return ProjectAttributionReportSchema.parse({ version: 1, entries });
+}
+
+/** Deterministic human-readable projection of the machine report. */
+export function formatProjectAttributionMarkdown(report: ProjectAttributionReport): string {
+  const sections = report.entries.map((entry) => {
+    const heading = entry.name ?? entry.text;
+    return [
+      `## ${heading}`,
+      '',
+      entry.text,
+      '',
+      `Author: ${entry.author}  `,
+      `License: ${entry.license}${entry.sourceUrl ? `  \nSource: ${entry.sourceUrl}` : ''}`,
+    ].join('\n');
+  });
+  return `# Asset attribution\n${sections.length > 0 ? `\n${sections.join('\n\n')}` : '\nNo attributed project assets are currently present.'}\n`;
+}

package/server/support/project/run-name.ts

@@ -0,0 +1,18 @@
+/**
+ * What a run is CALLED — one owner of the bound.
+ *
+ * WHY THIS EXISTS. `vgai play --name <text>` exists so a run is findable by
+ * what it was testing.
+ *
+ * WHAT STAYS UNNAMED, deliberately: interactive `vgai play` with no `--name`.
+ * A person pressing play is not testing a named thing, and inventing a label
+ * for it would put noise in exactly the directory this makes greppable.
+ *
+ * Pure — no filesystem, no clock. `editor-server.ts`'s `playRunSlug` is the
+ * OTHER half (slugging a name into a filename segment) and reads the bound
+ * from here, so the two can never disagree about how long a run name may be.
+ */
+
+/** Bound on a run's name — long enough to stay recognisable in a directory
+ *  listing, short enough that the timestamp beside it is still readable. */
+export const MAX_RUN_NAME = 40;