@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/server/asset-catalog-audit.ts

@@ -0,0 +1,268 @@
+import { stat } from 'node:fs/promises';
+import { assetCapabilities } from '../src/asset-workflow/asset-capabilities';
+import type { AssetCatalog } from '../src/asset-workflow/asset-types';
+import { resolveCatalogFile } from './local-asset-catalog';
+
+export type AssetAuditIssueCode =
+  | 'duplicate-family-id'
+  | 'duplicate-variant-id'
+  | 'duplicate-delivery-id'
+  | 'missing-file'
+  | 'missing-dependency'
+  | 'dependency-escape'
+  | 'missing-thumbnail'
+  | 'runtime-ready-drift'
+  | 'catalog-validation';
+
+export interface AssetAuditIssue {
+  readonly code: AssetAuditIssueCode;
+  readonly familyId?: string;
+  readonly variantId?: string;
+  readonly path?: string;
+  readonly message: string;
+}
+
+export interface AssetAuditSummary {
+  readonly version: 1;
+  readonly catalogVersion: 2;
+  readonly generatedAt: string;
+  readonly catalogGeneratedAt: string;
+  readonly totals: {
+    readonly families: number;
+    readonly variants: number;
+    readonly deliveries: number;
+    readonly files: number;
+    readonly dependencies: number;
+    readonly thumbnails: number;
+    readonly cloudVariants: number;
+    readonly unavailableVariants: number;
+  };
+  readonly capabilities: {
+    readonly previewable: number;
+    readonly importable: number;
+    readonly runtimeReady: number;
+    readonly animated: number;
+  };
+  readonly byType: Readonly<Record<string, number>>;
+  readonly byFormat: Readonly<Record<string, number>>;
+  readonly byLicense: Readonly<Record<string, number>>;
+  readonly issues: readonly AssetAuditIssue[];
+  readonly healthy: boolean;
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function increment(target: Record<string, number>, key: string): void {
+  target[key] = (target[key] ?? 0) + 1;
+}
+
+export async function reconcileAssetCatalogAvailability(
+  catalog: AssetCatalog,
+  root: string,
+): Promise<{ catalog: AssetCatalog; unavailableVariants: number }> {
+  let unavailableVariants = 0;
+  const families = await Promise.all(
+    catalog.families.map(async (family) => ({
+      ...family,
+      variants: await Promise.all(
+        family.variants.map(async (variant) => {
+          const paths = variant.files.flatMap((file) => [file.path, ...(file.dependencies ?? [])]);
+          const available = (
+            await Promise.all(
+              paths.map(async (path) => {
+                try {
+                  await stat(resolveCatalogFile(root, path));
+                  return true;
+                } catch {
+                  return false;
+                }
+              }),
+            )
+          ).every(Boolean);
+          if (!available) unavailableVariants++;
+          return {
+            ...variant,
+            deliveries: variant.deliveries.map((delivery) =>
+              delivery.kind === 'local-ssd' ? { ...delivery, available } : delivery,
+            ),
+          };
+        }),
+      ),
+    })),
+  );
+  return { catalog: { ...catalog, families }, unavailableVariants };
+}
+
+export async function auditAssetCatalog(options: {
+  catalog: AssetCatalog;
+  root: string;
+  cloudVariantIds?: ReadonlySet<string>;
+  now?: string;
+}): Promise<AssetAuditSummary> {
+  const { catalog, root } = options;
+  const issues: AssetAuditIssue[] = catalog.issues.map((issue) => ({
+    code: 'catalog-validation',
+    ...(issue.familyId ? { familyId: issue.familyId } : {}),
+    message: `${issue.path.join('.')}: ${issue.message}`,
+  }));
+  const familyIds = new Set<string>();
+  const variantIds = new Set<string>();
+  const deliveryIds = new Set<string>();
+  const byType: Record<string, number> = {};
+  const byFormat: Record<string, number> = {};
+  const byLicense: Record<string, number> = {};
+  let deliveries = 0;
+  let files = 0;
+  let dependencies = 0;
+  let thumbnails = 0;
+  let previewable = 0;
+  let importable = 0;
+  let runtimeReady = 0;
+  let animated = 0;
+  let unavailableVariants = 0;
+  const checks: Array<() => Promise<void>> = [];
+
+  for (const family of catalog.families) {
+    if (familyIds.has(family.id)) {
+      issues.push({ code: 'duplicate-family-id', familyId: family.id, message: 'Duplicate family id' });
+    }
+    familyIds.add(family.id);
+    increment(byLicense, family.license);
+    for (const variant of family.variants) {
+      const localDeliveryAvailable = variant.deliveries.some(
+        (delivery) => delivery.kind === 'local-ssd' && delivery.available,
+      );
+      if (!localDeliveryAvailable) unavailableVariants++;
+      if (variantIds.has(variant.id)) {
+        issues.push({
+          code: 'duplicate-variant-id', familyId: family.id, variantId: variant.id,
+          message: 'Duplicate variant id',
+        });
+      }
+      variantIds.add(variant.id);
+      increment(byType, variant.type);
+      const primaryFormat = variant.files[0]?.format ?? 'unknown';
+      const capability = assetCapabilities(primaryFormat);
+      if (capability.previewable) previewable++;
+      if (capability.importable) importable++;
+      if (capability.runtimeReady) runtimeReady++;
+      if (capability.animated || (variant.animationCount ?? 0) > 0) animated++;
+      if (capability.runtimeReady && !['glb', 'gltf'].includes(primaryFormat)) {
+        issues.push({
+          code: 'runtime-ready-drift', familyId: family.id, variantId: variant.id,
+          message: `${primaryFormat} is not a runtime-native 3D format`,
+        });
+      }
+      for (const delivery of variant.deliveries) {
+        deliveries++;
+        if (deliveryIds.has(delivery.id)) {
+          issues.push({
+            code: 'duplicate-delivery-id', familyId: family.id, variantId: variant.id,
+            message: `Duplicate delivery id: ${delivery.id}`,
+          });
+        }
+        deliveryIds.add(delivery.id);
+      }
+      for (const file of variant.files) {
+        files++;
+        increment(byFormat, file.format);
+        checks.push(async () => {
+          const absolute = resolveCatalogFile(root, file.path);
+          if (!(await exists(absolute))) {
+            issues.push({
+              code: 'missing-file', familyId: family.id, variantId: variant.id, path: file.path,
+              message: 'Catalog file is missing',
+            });
+          }
+        });
+        for (const dependency of file.dependencies ?? []) {
+          dependencies++;
+          checks.push(async () => {
+            let absolute: string;
+            try {
+              absolute = resolveCatalogFile(root, dependency);
+            } catch {
+              issues.push({
+                code: 'dependency-escape', familyId: family.id, variantId: variant.id,
+                path: dependency, message: 'Dependency escapes the library root',
+              });
+              return;
+            }
+            if (localDeliveryAvailable && !(await exists(absolute))) {
+              issues.push({
+                code: 'missing-dependency', familyId: family.id, variantId: variant.id,
+                path: dependency, message: 'Catalog dependency is missing',
+              });
+            }
+          });
+        }
+      }
+      checks.push(async () => {
+        let absolute: string;
+        try {
+          absolute = resolveCatalogFile(root, variant.thumbnail.path);
+        } catch {
+          issues.push({
+            code: 'missing-thumbnail', familyId: family.id, variantId: variant.id,
+            path: variant.thumbnail.path, message: 'Thumbnail path escapes the library root',
+          });
+          return;
+        }
+        if (await exists(absolute)) thumbnails++;
+        else {
+          issues.push({
+            code: 'missing-thumbnail', familyId: family.id, variantId: variant.id,
+            path: variant.thumbnail.path, message: 'Thumbnail is missing',
+          });
+        }
+      });
+    }
+  }
+
+  let cursor = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(32, checks.length) }, async () => {
+      while (cursor < checks.length) {
+        const check = checks[cursor++];
+        if (check) await check();
+      }
+    }),
+  );
+
+  issues.sort(
+    (left, right) =>
+      left.code.localeCompare(right.code) ||
+      (left.familyId ?? '').localeCompare(right.familyId ?? '') ||
+      (left.variantId ?? '').localeCompare(right.variantId ?? '') ||
+      (left.path ?? '').localeCompare(right.path ?? ''),
+  );
+  return {
+    version: 1,
+    catalogVersion: 2,
+    generatedAt: options.now ?? new Date().toISOString(),
+    catalogGeneratedAt: catalog.generatedAt,
+    totals: {
+      families: catalog.families.length,
+      variants: variantIds.size,
+      deliveries,
+      files,
+      dependencies,
+      thumbnails,
+      cloudVariants: options.cloudVariantIds?.size ?? 0,
+      unavailableVariants,
+    },
+    capabilities: { previewable, importable, runtimeReady, animated },
+    byType,
+    byFormat,
+    byLicense,
+    issues,
+    healthy: issues.length === 0,
+  };
+}

package/server/asset-catalog-v2.ts

@@ -0,0 +1,146 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import {
+  type AssetCatalog,
+  type AssetFamily,
+  type AssetVariant,
+  AssetFileSchema,
+  parseAssetCatalog,
+} from '../src/asset-workflow/asset-types';
+
+export const LegacyCatalogAssetSchema = z
+  .object({
+    id: z.string().regex(/^[a-f0-9]{24}$/),
+    source: z.string().min(1),
+    name: z.string().min(1),
+    type: z.enum(['model', 'animation', 'source']),
+    categories: z.array(z.string()),
+    tags: z.array(z.string()),
+    license: z.string().min(1),
+    author: z.string().min(1),
+    sourceUrl: z.string().url(),
+    thumbnail: z.string().min(1).optional(),
+    files: z.array(AssetFileSchema).min(1),
+    animationCount: z.number().int().nonnegative().optional(),
+    clipNames: z.array(z.string()).optional(),
+  })
+  .strict();
+
+export const LegacyAssetCatalogSchema = z
+  .object({
+    version: z.literal(1),
+    generatedAt: z.string().datetime(),
+    assets: z.array(LegacyCatalogAssetSchema),
+  })
+  .strict();
+
+export type LegacyCatalogAsset = z.infer<typeof LegacyCatalogAssetSchema>;
+
+function normalizeFamilyName(name: string): string {
+  return name.trim().toLocaleLowerCase('en-US').replace(/\s+/g, ' ').replace(/\s+\(final\)$/, '');
+}
+
+/**
+ * Generator-only semantic key. It is persisted as an explicit family id in v2;
+ * search/preview code never reconstructs it. Collection segments prevent two
+ * unrelated packs with the same display name from aliasing.
+ */
+export function catalogFamilyKey(asset: LegacyCatalogAsset): string {
+  const segments = asset.files[0]!.path.replaceAll('\\', '/').split('/');
+  return JSON.stringify([
+    asset.source,
+    segments[1] ?? '',
+    segments[2] ?? '',
+    normalizeFamilyName(asset.name),
+  ]);
+}
+
+export function makeCatalogFamilyId(key: string): string {
+  return createHash('sha256').update(`family\0${key}`).digest('hex').slice(0, 24);
+}
+
+function uniqueSorted(values: Iterable<string>): string[] {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+function familyType(records: readonly LegacyCatalogAsset[]): AssetFamily['type'] {
+  if (records.some((record) => record.type === 'model')) return 'model';
+  if (records.some((record) => record.type === 'animation')) return 'animation';
+  return 'source';
+}
+
+function variantFromLegacy(record: LegacyCatalogAsset): AssetVariant {
+  return {
+    id: record.id,
+    label: record.files.map((file) => file.label).join(' + '),
+    type: record.type,
+    files: record.files,
+    deliveries: [
+      {
+        id: `local:${record.id}`,
+        kind: 'local-ssd',
+        available: true,
+        fileIndexes: record.files.map((_, index) => index),
+      },
+    ],
+    thumbnail: {
+      path: record.thumbnail ?? `thumbnails/${record.id}.webp`,
+      state: 'generated',
+      profileVersion: 'thumbnail-v1',
+    },
+    ...(record.animationCount !== undefined ? { animationCount: record.animationCount } : {}),
+    ...(record.clipNames !== undefined ? { clipNames: record.clipNames } : {}),
+  };
+}
+
+export function buildAssetCatalogV2(
+  records: readonly LegacyCatalogAsset[],
+  generatedAt: string,
+): AssetCatalog {
+  const grouped = new Map<string, LegacyCatalogAsset[]>();
+  for (const record of records) {
+    const key = catalogFamilyKey(record);
+    const siblings = grouped.get(key);
+    if (siblings) siblings.push(record);
+    else grouped.set(key, [record]);
+  }
+
+  const seenFamilyIds = new Map<string, string>();
+  const seenVariantIds = new Set<string>();
+  const families: AssetFamily[] = [];
+  for (const [key, siblings] of grouped) {
+    siblings.sort((left, right) => left.id.localeCompare(right.id));
+    const first = siblings[0]!;
+    const id = makeCatalogFamilyId(key);
+    const priorKey = seenFamilyIds.get(id);
+    if (priorKey && priorKey !== key) throw new Error(`Catalog family id collision: ${id}`);
+    seenFamilyIds.set(id, key);
+    for (const sibling of siblings) {
+      if (seenVariantIds.has(sibling.id)) throw new Error(`Duplicate catalog variant id: ${sibling.id}`);
+      seenVariantIds.add(sibling.id);
+    }
+    families.push({
+      id,
+      source: first.source,
+      name: first.name.replace(/\s+\(final\)$/, ''),
+      type: familyType(siblings),
+      categories: uniqueSorted(siblings.flatMap((record) => record.categories)),
+      tags: uniqueSorted(siblings.flatMap((record) => record.tags)),
+      license: first.license,
+      author: first.author,
+      sourceUrl: first.sourceUrl,
+      variants: siblings.map(variantFromLegacy),
+    });
+  }
+  families.sort((left, right) => left.name.localeCompare(right.name) || left.id.localeCompare(right.id));
+  return parseAssetCatalog({ version: 2, generatedAt, families });
+}
+
+export function migrateLegacyAssetCatalog(input: unknown): AssetCatalog {
+  const legacy = LegacyAssetCatalogSchema.parse(input);
+  return buildAssetCatalogV2(legacy.assets, legacy.generatedAt);
+}
+
+export function serializableAssetCatalog(catalog: AssetCatalog): object {
+  return { version: 2, generatedAt: catalog.generatedAt, families: catalog.families };
+}