@forgeax-extension/character-3d 0.1.2

package/server/asset-storage.ts

@@ -0,0 +1,136 @@
+// AssetStorage — adapter boundary for durable per-game 3D asset persistence.
+//
+// M9 (ADR-0002): an asset is a named file in the active game's runtime asset
+// library, identified by its game-relative path (assetPath). The adapter owns
+// all path logic (write file + sidecar, list, delete, name collision) so a
+// future path change touches one place. It does NOT know which provider
+// produced an asset (decoupling rule, ADR-0001). The local impl writes to
+// .forgeax/games/<slug>/assets/3d/{characters|meshes}/; a future COS/S3 adapter
+// could swap without changing this interface or the manifest contract.
+
+import type { AssetSlot, FileFormat, FileRole, Gen3DAssetManifest, MotionRef, QualityReport, RigChain, SkeletonProfile } from '../shared/manifest';
+
+// One produced file (already downloaded into bytes; never a provider URL).
+export interface AssetFileInput {
+  data: Uint8Array;
+  format: FileFormat;
+  role: FileRole;
+}
+
+export interface WriteAssetInput {
+  slug: string;
+  assetSlot: AssetSlot;
+  // Desired base name (without extension). The store sanitizes it and, on a
+  // non-cache name collision, appends a numeric suffix instead of overwriting.
+  assetName: string;
+  files: AssetFileInput[];
+  // gen3d-private metadata persisted under the sidecar `custom` namespace.
+  meta: {
+    provider: Gen3DAssetManifest['provider'];
+    providerMode: Gen3DAssetManifest['providerMode'];
+    mode: Gen3DAssetManifest['mode'];
+    sourceJobId: string | null;
+    prompt: string | null;
+    sourceInputAssetPaths: string[];
+    faceCount?: number;
+    cacheKey?: string;
+    meshyTaskRefs?: Gen3DAssetManifest['meshyTaskRefs'];
+    visviseRefs?: Gen3DAssetManifest['visviseRefs'];
+  };
+}
+
+export interface AssetStorage {
+  // Persist a full asset (main GLB + same-basename sidefiles + sidecar) into the
+  // game's asset tree and return the resulting manifest (assetPath = main GLB).
+  writeAsset(input: WriteAssetInput): Promise<Gen3DAssetManifest>;
+  // Load a manifest by game-relative assetPath (reads the sidecar).
+  getAsset(slug: string, assetPath: string): Promise<Gen3DAssetManifest | null>;
+  // List manifests in a game, optionally filtered by slot (scans the directory).
+  listAssets(slug: string, assetSlot?: AssetSlot): Promise<Gen3DAssetManifest[]>;
+  // Delete the asset file + sidecar + same-basename sidefiles. Returns the
+  // cacheKey recorded in the sidecar (for a cache tombstone) or null.
+  deleteAsset(slug: string, assetPath: string): Promise<{ cacheKey: string | null }>;
+  // Append derived files (rigged_model / animated_model GLB+FBX) to an existing
+  // mesh asset as same-basename sidefiles, update the sidecar dependencies +
+  // skeleton/motion metadata, recompute readiness, and return the updated
+  // manifest. Serialized per asset (read-modify-write) so concurrent appends to
+  // one character (e.g. multiple motions) never drop entries (ADR-0003). The
+  // main GLB identity (assetPath) is unchanged.
+  appendDerivedFiles(input: AppendDerivedFilesInput): Promise<Gen3DAssetManifest>;
+  // Strip every rigged_model / animated_model sidefile + clear custom.rig so a
+  // forced re-rig (possibly on another provider) starts from a clean mesh.
+  // Source mesh / preview / textures are kept. Main GLB identity unchanged.
+  clearRigAndMotions(slug: string, assetPath: string): Promise<Gen3DAssetManifest>;
+  // Persist the five-dimension quality report into the asset sidecar
+  // (custom.quality) and return the refreshed manifest.
+  updateAssetQuality(
+    slug: string,
+    assetPath: string,
+    report: QualityReport,
+  ): Promise<Gen3DAssetManifest>;
+  // Persist a user-defined display label into the asset sidecar
+  // (custom.userLabel) and return the refreshed manifest.
+  updateAssetLabel(
+    slug: string,
+    assetPath: string,
+    label: string | null,
+  ): Promise<Gen3DAssetManifest>;
+  // Read the bytes of one file in an asset, selected by role (+ optional format),
+  // for COS-sharing it as a provider transfer URL. Returns null when absent.
+  readAssetFile(
+    slug: string,
+    assetPath: string,
+    role: FileRole,
+    format?: FileFormat,
+  ): Promise<{ data: Uint8Array; format: FileFormat } | null>;
+  // Persist a transfer/scratch artifact (pose-standardized image, uploaded
+  // input). NOT an asset: lives under .gen3d/tmp/, no manifest, no delete UI.
+  putScratch(input: PutScratchInput): Promise<PutScratchResult>;
+}
+
+// One derived file to append to an existing asset. Bytes already downloaded.
+export interface DerivedFileInput {
+  data: Uint8Array;
+  format: FileFormat;
+  // rigged_model | animated_model (the appended downstream roles).
+  role: FileRole;
+  // For animated_model files: which motion this clip is (any system). Stored
+  // structurally + used as the on-disk file-name variant for readability. A
+  // single append may carry several files with different motionRefs (e.g. a rig
+  // step that also lands the free walk/run clips, ADR-0006 §8-Q6).
+  motionRef?: MotionRef;
+}
+
+export interface AppendDerivedFilesInput {
+  slug: string;
+  // Target mesh asset to append onto (its main GLB stays the identity).
+  assetPath: string;
+  files: DerivedFileInput[];
+  // Skeleton metadata applied to rigged_model files (a verified rig step).
+  skeleton?: {
+    hasSkeleton: boolean;
+    skeletonProfile: SkeletonProfile;
+    animationInputReady: boolean;
+  };
+  // Rig-chain identity (provider + Meshy rig_task_id + rigType + expiry),
+  // persisted on the asset so apply-motion can dispatch by system (ADR-0006).
+  rigChain?: RigChain;
+  visviseRefs?: Gen3DAssetManifest['visviseRefs'];
+}
+
+// Scratch (transfer) artifacts — pose-standardized images, uploaded inputs. NOT
+// assets: they live under .forgeax/games/<slug>/.gen3d/tmp/, never in the asset
+// library, and have no delete UI (CONTEXT.md "临时/中转产物").
+export interface PutScratchInput {
+  slug: string;
+  data: Uint8Array;
+  format: FileFormat;
+}
+
+export interface PutScratchResult {
+  // Scratch storage key (relative to the project root) for same-origin preview.
+  storageKey: string;
+  sha256: string;
+  bytes: number;
+  localUrl: string | null;
+}

package/server/asset-upload.ts

@@ -0,0 +1,123 @@
+// Transfer-artifact upload. Input images / mesh files exist only so a
+// URL-fetching provider can reach a local file.
+//
+// Preferred path (2026-08 group contract): POST the bytes to the LiteLLM
+// virtual-key endpoint `/v1/assets` (`purpose=model_input`). The returned URL
+// is valid for 24h. Fallback: plugin-local COS_* via CosUploader.
+//
+// Video still uses CosUploader.presignPut — the gateway contract is POST file,
+// not a browser presign.
+
+import { createHash } from 'node:crypto';
+
+import { CosUploader, extForMime, type CosUploadResult } from './cos-uploader';
+import { getCosEnv, getLitellmEnv, type LitellmEnv } from './env';
+import { httpError, type FetchLike } from './providers/gateway-client';
+
+const DEFAULT_EXPIRES_SEC = 24 * 3600;
+
+export function extractAssetUrl(resp: Record<string, unknown>): { url: string; expiresInSec: number } | null {
+  const url = firstString(
+    resp.url,
+    resp.signed_url,
+    resp.asset_url,
+    resp.file_url,
+    nestedString(resp.data, 'url'),
+    nestedString(resp.file, 'url'),
+    firstArrayUrl(resp.data),
+  );
+  if (!url) return null;
+  const expiresInSec = firstPositiveInt(resp.expires_in, resp.expiresInSec, resp.expires_in_sec) ?? DEFAULT_EXPIRES_SEC;
+  return { url, expiresInSec };
+}
+
+export async function uploadViaLitellmAssets(opts: {
+  env: LitellmEnv;
+  data: Uint8Array;
+  mimetype: string;
+  filename?: string;
+  fetchImpl?: FetchLike;
+}): Promise<CosUploadResult> {
+  const filename = opts.filename ?? `upload.${extForMime(opts.mimetype)}`;
+  const form = new FormData();
+  form.append(
+    'file',
+    new Blob([Uint8Array.from(opts.data)], { type: opts.mimetype }),
+    filename,
+  );
+  form.append('purpose', 'model_input');
+  const fetchImpl = opts.fetchImpl ?? ((url, init) => fetch(url, init));
+  const resp = await fetchImpl(`${opts.env.baseUrl.replace(/\/+$/, '')}/v1/assets`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${opts.env.apiKey}` },
+    body: form,
+  });
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => '');
+    throw httpError(resp.status, body);
+  }
+  const json = (await resp.json()) as Record<string, unknown>;
+  const extracted = extractAssetUrl(json);
+  if (!extracted) {
+    throw Object.assign(new Error('LiteLLM /v1/assets returned no url'), { code: 'cos_not_configured' });
+  }
+  return {
+    url: extracted.url,
+    bytes: opts.data.byteLength,
+    sha256: createHash('sha256').update(opts.data).digest('hex'),
+    expiresInSec: extracted.expiresInSec,
+  };
+}
+
+export async function uploadTransferArtifact(
+  data: Uint8Array,
+  mimetype: string,
+  fetchImpl?: FetchLike,
+): Promise<CosUploadResult> {
+  const litellm = getLitellmEnv();
+  const cos = getCosEnv();
+  if (litellm) {
+    try {
+      return await uploadViaLitellmAssets({ env: litellm, data, mimetype, fetchImpl });
+    } catch (error) {
+      if (cos) return new CosUploader(cos).upload(data, mimetype);
+      throw Object.assign(
+        new Error('file upload failed (LiteLLM /v1/assets) and COS is not configured'),
+        { code: 'cos_not_configured', cause: error },
+      );
+    }
+  }
+  if (!cos) {
+    throw Object.assign(
+      new Error('file upload is not configured (LiteLLM /v1/assets or COS)'),
+      { code: 'cos_not_configured' },
+    );
+  }
+  return new CosUploader(cos).upload(data, mimetype);
+}
+
+function firstString(...values: unknown[]): string | null {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return null;
+}
+
+function nestedString(obj: unknown, key: string): string | null {
+  if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) return null;
+  const value = (obj as Record<string, unknown>)[key];
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function firstArrayUrl(value: unknown): string | null {
+  if (!Array.isArray(value) || value.length === 0) return null;
+  return nestedString(value[0], 'url');
+}
+
+function firstPositiveInt(...values: unknown[]): number | null {
+  for (const value of values) {
+    const n = typeof value === 'number' ? value : typeof value === 'string' ? Number.parseInt(value, 10) : NaN;
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return null;
+}

package/server/audit.ts

@@ -0,0 +1,58 @@
+// Audit — append-only JSONL trail of provider activity, per-game (ADR-0002).
+// Records timing and outcome only; NEVER writes the api key, full request
+// payload, or raw provider response. Lives under the game's .gen3d/ dir so it
+// stays out of source control and is removed when the game is deleted.
+
+import { appendFile, mkdir } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+import type { GenerationMode, ProviderId } from '../shared/manifest';
+
+export type AuditEvent =
+  | 'submit'
+  | 'poll_succeeded'
+  | 'poll_failed'
+  | 'poll_timeout'
+  | 'cache_hit'
+  | 'rate_blocked'
+  | 'rest_succeeded'
+  | 'rest_failed'
+  | 'rest_no_output'
+  | 'asset_deleted';
+
+export interface AuditRecord {
+  ts: string;
+  provider: ProviderId;
+  mode: GenerationMode;
+  event: AuditEvent;
+  sourceJobId?: string | null;
+  assetPath?: string;
+  cacheKey?: string;
+  model?: string;
+  httpStatus?: number;
+  durationMs?: number;
+  errorCode?: string;
+  // Short, non-secret detail (e.g. status string, error class). Never payloads.
+  detail?: string;
+}
+
+function projectRoot(): string {
+  return process.env.FORGEAX_PROJECT_ROOT ?? resolve(process.cwd(), '.forgeax-runtime');
+}
+
+function safeSlug(slug: string): string {
+  if (!slug || slug.includes('/') || slug.includes('\\') || slug === '..' || slug.includes('\0')) {
+    throw Object.assign(new Error(`unsafe slug ${JSON.stringify(slug)}`), { code: 'invalid_slug' });
+  }
+  return slug;
+}
+
+function auditPath(slug: string): string {
+  return resolve(projectRoot(), '.forgeax', 'games', safeSlug(slug), '.gen3d', 'audit.jsonl');
+}
+
+export async function audit(slug: string, record: AuditRecord): Promise<void> {
+  const path = auditPath(slug);
+  await mkdir(dirname(path), { recursive: true });
+  await appendFile(path, `${JSON.stringify(record)}\n`, 'utf8');
+}

package/server/cache.ts

@@ -0,0 +1,75 @@
+// Cache — request-level dedup, per-game (ADR-0002 / CONTEXT.md). Stores ONLY
+// cacheKey -> assetPath mappings (+ delete tombstones), never provider responses
+// or URLs. On hit, the caller loads the manifest from the per-game store by
+// assetPath, so a hit never returns a dead provider URL.
+//
+// Per-game: cache.jsonl lives under .forgeax/games/<slug>/.gen3d/ so game-A and
+// game-B never mis-hit each other (entries hold game-relative paths). The cache
+// is naturally slug-isolated, so cacheKey need not include the slug, and
+// deleting a game removes its cache with the directory.
+//
+// Append-only JSONL; last write for a key wins. A tombstone ({cacheKey,
+// deleted:true}) written by gen3d:delete-asset makes lookup() miss so a
+// deliberately deleted asset never resurrects / re-burns quota.
+
+import { mkdir, readFile, appendFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+function projectRoot(): string {
+  return process.env.FORGEAX_PROJECT_ROOT ?? resolve(process.cwd(), '.forgeax-runtime');
+}
+
+function safeSlug(slug: string): string {
+  if (!slug || slug.includes('/') || slug.includes('\\') || slug === '..' || slug.includes('\0')) {
+    throw Object.assign(new Error(`unsafe slug ${JSON.stringify(slug)}`), { code: 'invalid_slug' });
+  }
+  return slug;
+}
+
+function cachePath(slug: string): string {
+  return resolve(projectRoot(), '.forgeax', 'games', safeSlug(slug), '.gen3d', 'cache.jsonl');
+}
+
+interface CacheEntry {
+  cacheKey: string;
+  assetPath?: string;
+  deleted?: boolean;
+}
+
+// Returns the live assetPath for a cacheKey, or null if unseen or tombstoned.
+export async function lookup(slug: string, cacheKey: string): Promise<string | null> {
+  let raw: string;
+  try {
+    raw = await readFile(cachePath(slug), 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw error;
+  }
+  let hit: string | null = null;
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    const entry = JSON.parse(line) as CacheEntry;
+    if (entry.cacheKey !== cacheKey) continue;
+    // Last write wins: a later tombstone clears an earlier mapping, and a later
+    // mapping (regenerate after delete) clears an earlier tombstone.
+    hit = entry.deleted ? null : (entry.assetPath ?? null);
+  }
+  return hit;
+}
+
+// Append a mapping only AFTER provider call + file write all succeeded
+// (write-after-success).
+export async function remember(slug: string, cacheKey: string, assetPath: string): Promise<void> {
+  const path = cachePath(slug);
+  await mkdir(dirname(path), { recursive: true });
+  const entry: CacheEntry = { cacheKey, assetPath };
+  await appendFile(path, `${JSON.stringify(entry)}\n`, 'utf8');
+}
+
+// Append a tombstone so a deleted asset's cacheKey no longer resolves.
+export async function tombstone(slug: string, cacheKey: string): Promise<void> {
+  const path = cachePath(slug);
+  await mkdir(dirname(path), { recursive: true });
+  const entry: CacheEntry = { cacheKey, deleted: true };
+  await appendFile(path, `${JSON.stringify(entry)}\n`, 'utf8');
+}

package/server/cos-uploader.ts

@@ -0,0 +1,141 @@
+// COS uploader — hosts a local input image on cloud object storage (COS) and returns a
+// time-limited presigned URL. Input images are TRANSFER artifacts, not assets:
+// they exist only so a provider (Hunyuan/Meshy) whose API fetches by URL can
+// reach a user's local file. Rodin takes bytes directly and never needs this.
+//
+// The key is content-addressed (sha256) under a fixed prefix so repeated
+// uploads of the same image are idempotent. Nothing here is logged.
+
+import COS from 'cos-nodejs-sdk-v5';
+import { createHash, randomUUID } from 'node:crypto';
+
+import type { CosEnv } from './env';
+
+const KEY_PREFIX = 'gen3d/inputs';
+
+export interface CosUploadResult {
+  url: string;
+  bytes: number;
+  sha256: string;
+  // Seconds until the presigned URL expires (from now).
+  expiresInSec: number;
+}
+
+function sha256Hex(data: Uint8Array): string {
+  return createHash('sha256').update(data).digest('hex');
+}
+
+// Map a small set of input mimetypes to a file extension for the COS key.
+// Covers images (pose/views inputs) and 3D models (rig/motion transfer URLs).
+// Unknown types fall back to .bin; the presigned URL still works for fetchers.
+export function extForMime(mime: string): string {
+  switch (mime.toLowerCase()) {
+    case 'image/png':
+      return 'png';
+    case 'image/jpeg':
+    case 'image/jpg':
+      return 'jpg';
+    case 'image/webp':
+      return 'webp';
+    case 'image/gif':
+      return 'gif';
+    case 'model/gltf-binary':
+      return 'glb';
+    case 'model/fbx':
+    case 'application/octet-stream':
+      return 'fbx';
+    case 'video/mp4':
+      return 'mp4';
+    case 'video/webm':
+      return 'webm';
+    default:
+      return 'bin';
+  }
+}
+
+// Mimetype to send when COS-hosting a model file of a known format, so the
+// content-addressed key carries the right extension for URL-fetching providers.
+export function mimeForModelFormat(format: 'glb' | 'fbx'): string {
+  return format === 'glb' ? 'model/gltf-binary' : 'model/fbx';
+}
+
+export class CosUploader {
+  private readonly env: CosEnv;
+  private readonly cos: COS;
+
+  constructor(env: CosEnv) {
+    this.env = env;
+    this.cos = new COS({ SecretId: env.secretId, SecretKey: env.secretKey });
+  }
+
+  async upload(data: Uint8Array, mimetype: string): Promise<CosUploadResult> {
+    const sha256 = sha256Hex(data);
+    const key = `${KEY_PREFIX}/${sha256}.${extForMime(mimetype)}`;
+    const body = Buffer.from(data);
+
+    await new Promise<void>((resolvePut, rejectPut) => {
+      this.cos.putObject(
+        {
+          Bucket: this.env.bucket,
+          Region: this.env.region,
+          Key: key,
+          Body: body,
+          ContentType: mimetype,
+        },
+        (err) => (err ? rejectPut(err) : resolvePut()),
+      );
+    });
+
+    const url = await new Promise<string>((resolveUrl, rejectUrl) => {
+      this.cos.getObjectUrl(
+        {
+          Bucket: this.env.bucket,
+          Region: this.env.region,
+          Key: key,
+          Sign: true,
+          Expires: this.env.signExpiresSec,
+        },
+        (err, dataOut) => (err ? rejectUrl(err) : resolveUrl(dataOut.Url)),
+      );
+    });
+
+    return { url, bytes: data.byteLength, sha256, expiresInSec: this.env.signExpiresSec };
+  }
+
+  async presignPut(mimetype: string): Promise<{
+    uploadUrl: string;
+    publicUrl: string;
+    expiresInSec: number;
+    key: string;
+  }> {
+    const key = `${KEY_PREFIX}/video/${randomUUID()}.${extForMime(mimetype)}`;
+    const expiresInSec = this.env.signExpiresSec;
+    const uploadUrl = await new Promise<string>((resolveUrl, rejectUrl) => {
+      this.cos.getObjectUrl(
+        {
+          Bucket: this.env.bucket,
+          Region: this.env.region,
+          Key: key,
+          Method: 'PUT',
+          Sign: true,
+          Expires: expiresInSec,
+          Headers: { 'Content-Type': mimetype },
+        },
+        (err, dataOut) => (err ? rejectUrl(err) : resolveUrl(dataOut.Url)),
+      );
+    });
+    const publicUrl = await new Promise<string>((resolveUrl, rejectUrl) => {
+      this.cos.getObjectUrl(
+        {
+          Bucket: this.env.bucket,
+          Region: this.env.region,
+          Key: key,
+          Sign: true,
+          Expires: expiresInSec,
+        },
+        (err, dataOut) => (err ? rejectUrl(err) : resolveUrl(dataOut.Url)),
+      );
+    });
+    return { uploadUrl, publicUrl, expiresInSec, key };
+  }
+}