@aura3d/cli 1.1.0 → 1.3.1

package/dist/index.js

@@ -1,7 +1,8 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { dirname, extname, join, relative, resolve } from "node:path";
-export { cartoonCliAssetProfiles, getCartoonAssetProfileDefinition } from "./cartoon-asset-profiles.js";
+export { animationCliAssetProfiles, getAnimationAssetProfileDefinition } from "./animation-asset-profiles.js";
+export { validateAnimationAssets, parseAnimationClipMap, DEFAULT_ANIMATION_ACTIONS } from "./animation-asset-validator.js";
 export const DEFAULT_AURA_ASSET_MANIFEST = "aura.assets.json";
 export const DEFAULT_AURA_ASSET_OUTPUT_DIR = "public/aura-assets";
 export const DEFAULT_AURA_ASSET_PUBLIC_PATH = "/aura-assets/";
@@ -14,6 +15,9 @@ export function addAsset(options) {
     }
     const manifestPath = resolve(projectDir, DEFAULT_AURA_ASSET_MANIFEST);
     const current = readAssetManifest(projectDir);
+    // Re-adding (e.g. resolve overwriting) must not silently drop hand-authored
+    // provenance the new add does not re-supply (license/attribution/author/etc.).
+    const existing = current.assets.find((asset) => asset.id === options.name);
     const outputDir = normalizeRelativePath(options.outputDir ?? current.outputDir ?? DEFAULT_AURA_ASSET_OUTPUT_DIR);
     const publicPath = normalizePublicPath(options.publicPath ?? current.assetBasePath ?? DEFAULT_AURA_ASSET_PUBLIC_PATH);
     const typegen = normalizeRelativePath(options.typegen ?? current.typegen ?? DEFAULT_AURA_ASSET_TYPEGEN);
@@ -47,7 +51,7 @@ export function addAsset(options) {
         humanoid: inspection.humanoid,
         skeleton: inspection.skeleton,
         morphTargets: inspection.morphTargets,
-        provenance: createAssetProvenance(projectDir, sourcePath, options, inspection.provenance),
+        provenance: createAssetProvenance(projectDir, sourcePath, options, mergeDetectedProvenance(existing?.provenance, inspection.provenance)),
         textures: inspection.textures,
         dependencies: inspection.dependencies,
         orientation: inspection.orientation,
@@ -305,8 +309,8 @@ export function checkDeploy(options = {}) {
 export function validateGameAssets(options = {}) {
     return validateAssetReadiness("game", options);
 }
-export function validateCartoonAssets(options = {}) {
-    return validateAssetReadiness("cartoon", options);
+export function validateAnimationStudioAssets(options = {}) {
+    return validateAssetReadiness("animation", options);
 }
 export function createCharacterAssemblyPlan(options) {
     const projectDir = resolve(options.projectDir ?? process.cwd());
@@ -468,7 +472,7 @@ function validateAssetReadiness(profile, options) {
         pushUnique(warnings, [...readinessIssues.warnings, ...profileIssues.warnings]);
         const gameReady = asset.type === "model" && Boolean(asset.bounds) && asset.materials.length > 0 && asset.sizeBytes <= 50 * 1024 * 1024 && readinessIssues.failures.length === 0 && profileIssues.failures.length === 0;
         const profileReady = profileTarget && gameReady;
-        const cartoonReady = asset.type === "model"
+        const animationReady = asset.type === "model"
             ? Boolean(asset.bounds) && (asset.animations.length > 0 || /prop|set|stage|background|environment/i.test(asset.id))
             : asset.type === "audio" || asset.type === "texture";
         const artifactPaths = artifacts.assetFiles.find((entry) => entry.id === asset.id) ?? createReadinessAssetArtifacts(projectDir, manifest, asset);
@@ -499,7 +503,7 @@ function validateAssetReadiness(profile, options) {
             nodeNames: asset.nodeNames,
             artifactPaths,
             gameReady,
-            cartoonReady,
+            animationReady,
             ...(gameProfile === "fighting-character" ? { profileTarget, profileReady, ...(profileSkippedReason ? { profileSkippedReason } : {}) } : {}),
             warnings: assetWarnings
         };
@@ -544,25 +548,25 @@ function validateAssetReadiness(profile, options) {
     }
     else {
         if (modelAssets.length === 0)
-            failures.push("Cartoon readiness requires at least one typed model/set/prop GLB or GLTF.");
+            failures.push("Animation readiness requires at least one typed model/set/prop GLB or GLTF.");
         if (animatedModels.length === 0)
             warnings.push("No animated character clips detected. Prompt-to-episode output can use transform animation, but character acting needs skeletal or pose clips.");
         if (animatedModels.length > 0 && humanoidModels === 0)
-            warnings.push("No humanoid model metadata detected. Acting-heavy cartoon routes should confirm character rigs with assets inspect --humanoid.");
+            warnings.push("No humanoid model metadata detected. Acting-heavy animation routes should confirm character rigs with assets inspect --humanoid.");
         const audioAssets = manifest.assets.filter((asset) => asset.type === "audio");
         if (audioAssets.length === 0)
             warnings.push("No audio assets detected. AuraVoice bridge can still reference external narration manifests, but local episode proof is stronger with audio registered.");
     }
-    const cartoonEpisode = profile === "cartoon"
-        ? createCartoonEpisodeReadinessReport(manifest, assets, options)
+    const animationEpisode = profile === "animation"
+        ? createAnimationEpisodeReadinessReport(manifest, assets, options)
         : undefined;
-    if (cartoonEpisode && options.episode) {
-        pushUnique(failures, cartoonEpisode.failures);
-        pushUnique(warnings, cartoonEpisode.warnings);
+    if (animationEpisode && options.episode) {
+        pushUnique(failures, animationEpisode.failures);
+        pushUnique(warnings, animationEpisode.warnings);
     }
     const ok = failures.length === 0;
     const baseMessage = ok
-        ? `${profile === "game" ? "Game" : "Cartoon"} asset readiness report completed.`
+        ? `${profile === "game" ? "Game" : "Animation"} asset readiness report completed.`
         : failures;
     const messages = [
         ...(Array.isArray(baseMessage) ? baseMessage : [baseMessage]),
@@ -579,7 +583,7 @@ function validateAssetReadiness(profile, options) {
         manifestPath,
         artifacts,
         contracts: createReadinessValidationContracts(profile),
-        ...(cartoonEpisode ? { cartoonEpisode } : {}),
+        ...(animationEpisode ? { animationEpisode } : {}),
         summary: {
             totalAssets: manifest.assets.length,
             modelAssets: modelAssets.length,
@@ -589,14 +593,14 @@ function validateAssetReadiness(profile, options) {
             environmentAssets: manifest.assets.filter((asset) => asset.type === "environment").length,
             animationClips,
             humanoidModels,
-            ...(cartoonEpisode
+            ...(animationEpisode
                 ? {
-                    cartoonCharacters: cartoonEpisode.selectedCharacters.length,
-                    cartoonSets: cartoonEpisode.selectedSets.length,
-                    cartoonProps: cartoonEpisode.selectedProps.length,
-                    episodeReadyCharacters: cartoonEpisode.readiness.filter((entry) => entry.role === "character" && entry.episodeReady).length,
-                    mouthReadyCharacters: cartoonEpisode.readiness.filter((entry) => entry.role === "character" && entry.mouthReady).length,
-                    animationReadyCharacters: cartoonEpisode.readiness.filter((entry) => entry.role === "character" && entry.animationReady).length
+                    animationCharacters: animationEpisode.selectedCharacters.length,
+                    animationSets: animationEpisode.selectedSets.length,
+                    animationProps: animationEpisode.selectedProps.length,
+                    episodeReadyCharacters: animationEpisode.readiness.filter((entry) => entry.role === "character" && entry.episodeReady).length,
+                    mouthReadyCharacters: animationEpisode.readiness.filter((entry) => entry.role === "character" && entry.mouthReady).length,
+                    animationReadyCharacters: animationEpisode.readiness.filter((entry) => entry.role === "character" && entry.animationReady).length
                 }
                 : {}),
             ...(gameProfile === "fighting-character"
@@ -660,9 +664,9 @@ function createReadinessValidatorEvidence(profile) {
             label: "AuraClash game asset validator"
         }
         : {
-            id: "aura-voice-cartoon-assets",
-            command: "assets validate-cartoon",
-            label: "AuraVoice cartoon asset validator"
+            id: "aura-voice-animation-assets",
+            command: "assets validate-animation",
+            label: "AuraVoice animation asset validator"
         };
 }
 function createReadinessValidationContracts(profile) {
@@ -694,11 +698,11 @@ function createReadinessValidationContracts(profile) {
     }
     return [
         {
-            id: "auravoice-cartoon-character-asset-validation-contract",
-            label: "AuraVoice cartoon asset validation contract",
-            profile: "cartoon",
+            id: "auravoice-animation-character-asset-validation-contract",
+            label: "AuraVoice animation asset validation contract",
+            profile: "animation",
             sourceFamily: "AuraVoice",
-            intendedUse: "cartoon-character",
+            intendedUse: "animation-character",
             sourceOnly: true,
             requiredChecks: [
                 "typed Aura model, texture, audio, or environment asset entry",
@@ -706,7 +710,7 @@ function createReadinessValidationContracts(profile) {
                 "animation or transform-ready character metadata",
                 "audio or external AuraVoice manifest references for stronger episode proof"
             ],
-            evidenceBoundary: "This CLI contract is source-only. It does not prove cartoon route readiness until validate-cartoon output, rendered frames, timing proof, and AuraVoice evidence are archived."
+            evidenceBoundary: "This CLI contract is source-only. It does not prove animation route readiness until validate-animation output, rendered frames, timing proof, and AuraVoice evidence are archived."
         }
     ];
 }
@@ -744,8 +748,8 @@ function createReadinessAnimationMetadata(animations) {
         clips: animations.map((name, index) => ({ index, name }))
     };
 }
-function createCartoonEpisodeReadinessReport(manifest, assets, options) {
-    const readiness = assets.map(createCartoonEpisodeAssetReadiness);
+function createAnimationEpisodeReadinessReport(manifest, assets, options) {
+    const readiness = assets.map(createAnimationEpisodeAssetReadiness);
     const characters = readiness.filter((entry) => entry.role === "character");
     const sets = readiness.filter((entry) => entry.role === "set");
     const props = readiness.filter((entry) => entry.role === "prop");
@@ -756,26 +760,26 @@ function createCartoonEpisodeReadinessReport(manifest, assets, options) {
     const readyCharacters = characters.filter((entry) => entry.episodeReady);
     const readySets = sets.filter((entry) => entry.episodeReady);
     if (characters.length < 2) {
-        failures.push(`cartoon episode validation requires at least 2 typed cartoon character assets; found ${characters.length}${characters.length ? `: ${characters.map((entry) => entry.id).join(", ")}` : ""}.`);
+        failures.push(`animation episode validation requires at least 2 typed animation character assets; found ${characters.length}${characters.length ? `: ${characters.map((entry) => entry.id).join(", ")}` : ""}.`);
     }
     if (characters.length >= 2 && distinctCharacterHashes.size < characters.length) {
-        failures.push("cartoon episode validation requires distinct character files/hashes; duplicated character assets cannot prove a two-character episode cast.");
+        failures.push("animation episode validation requires distinct character files/hashes; duplicated character assets cannot prove a two-character episode cast.");
     }
     if (readyCharacters.length < 2) {
-        failures.push(`cartoon episode validation found only ${readyCharacters.length} episode-ready character asset${readyCharacters.length === 1 ? "" : "s"}; required 2 with license, provenance, animation, and mouth readiness.`);
+        failures.push(`animation episode validation found only ${readyCharacters.length} episode-ready character asset${readyCharacters.length === 1 ? "" : "s"}; required 2 with license, provenance, animation, and mouth readiness.`);
     }
     if (sets.length < 1) {
-        failures.push("cartoon episode validation requires at least 1 typed cartoon set/location asset.");
+        failures.push("animation episode validation requires at least 1 typed animation set/location asset.");
     }
     if (readySets.length < 1) {
-        failures.push("cartoon episode validation requires at least 1 episode-ready set with license, provenance, bounds, readable materials, and walkable scale.");
+        failures.push("animation episode validation requires at least 1 episode-ready set with license, provenance, bounds, readable materials, and walkable scale.");
     }
     for (const entry of readiness) {
         pushUnique(failures, entry.failures);
         pushUnique(warnings, entry.warnings);
     }
     if (audio.length === 0) {
-        warnings.push("cartoon episode validation found no typed audio assets; publish-ready dialogue/audio proof will need registered dialogue, music, or SFX stems.");
+        warnings.push("animation episode validation found no typed audio assets; publish-ready dialogue/audio proof will need registered dialogue, music, or SFX stems.");
     }
     const evidenceDirectory = options.output ? dirname(normalizeRelativePath(options.output)) : "artifacts/aura3d";
     return {
@@ -801,56 +805,56 @@ function createCartoonEpisodeReadinessReport(manifest, assets, options) {
         warnings
     };
 }
-function createCartoonEpisodeAssetReadiness(asset) {
-    const role = inferCartoonEpisodeAssetRole(asset);
+function createAnimationEpisodeAssetReadiness(asset) {
+    const role = inferAnimationEpisodeAssetRole(asset);
     const failures = [];
     const warnings = [];
     const provenanceReady = Boolean(asset.provenance?.sourceUrl || asset.provenance?.sourceFamily || asset.provenance?.sourcePath);
-    const animationReady = role === "character" ? isCartoonCharacterAnimationReady(asset) : asset.animations.length > 0;
-    const mouthMode = role === "character" ? inferCartoonMouthMode(asset) : undefined;
+    const animationReady = role === "character" ? isAnimationCharacterAnimationReady(asset) : asset.animations.length > 0;
+    const mouthMode = role === "character" ? inferAnimationMouthMode(asset) : undefined;
     const mouthReady = role === "character" ? mouthMode !== "missing-mouth-motion" : false;
-    const setReady = role === "set" ? isCartoonSetReady(asset) : undefined;
+    const setReady = role === "set" ? isAnimationSetReady(asset) : undefined;
     if (role === "character") {
         if (asset.type !== "model")
-            failures.push(`${asset.id}: cartoon character must be a typed model asset, found ${asset.type}.`);
+            failures.push(`${asset.id}: animation character must be a typed model asset, found ${asset.type}.`);
         if (!asset.licenseVerified)
-            failures.push(`${asset.id}: cartoon character requires verified redistributable license evidence.`);
+            failures.push(`${asset.id}: animation character requires verified redistributable license evidence.`);
         if (!provenanceReady)
-            failures.push(`${asset.id}: cartoon character requires source provenance for episode packaging.`);
+            failures.push(`${asset.id}: animation character requires source provenance for episode packaging.`);
         if (!asset.placeholderFree)
-            failures.push(`${asset.id}: cartoon character is placeholder-tagged and cannot satisfy episode-ready validation.`);
+            failures.push(`${asset.id}: animation character is placeholder-tagged and cannot satisfy episode-ready validation.`);
         if (!asset.boundsMetadata && !asset.bounds)
-            failures.push(`${asset.id}: cartoon character requires bounds metadata for framing and motion analysis.`);
+            failures.push(`${asset.id}: animation character requires bounds metadata for framing and motion analysis.`);
         if (!animationReady)
-            failures.push(`${asset.id}: cartoon character requires embedded animation clips or explicit segmented-rig metadata.`);
+            failures.push(`${asset.id}: animation character requires embedded animation clips or explicit segmented-rig metadata.`);
         if (!mouthReady)
-            failures.push(`${asset.id}: cartoon character requires blendshape, mouth-card, viseme, talk, face, or primitive mouth fallback metadata.`);
+            failures.push(`${asset.id}: animation character requires blendshape, mouth-card, viseme, talk, face, or primitive mouth fallback metadata.`);
         if (asset.materials.length === 0)
-            failures.push(`${asset.id}: cartoon character requires at least one readable material.`);
+            failures.push(`${asset.id}: animation character requires at least one readable material.`);
         if (asset.sizeBytes > 45 * 1024 * 1024)
-            failures.push(`${asset.id}: cartoon character payload is ${asset.sizeBytes} bytes; expected <= 47185920 for browser episode playback.`);
+            failures.push(`${asset.id}: animation character payload is ${asset.sizeBytes} bytes; expected <= 47185920 for browser episode playback.`);
         if (mouthMode === "amplitude-only")
             warnings.push(`${asset.id}: mouth readiness is amplitude-only; add blendshape or mouth-card metadata for stronger lip-sync proof.`);
     }
     else if (role === "set") {
         if (asset.type !== "model")
-            failures.push(`${asset.id}: cartoon set must be a typed model asset, found ${asset.type}.`);
+            failures.push(`${asset.id}: animation set must be a typed model asset, found ${asset.type}.`);
         if (!asset.licenseVerified)
-            failures.push(`${asset.id}: cartoon set requires verified redistributable license evidence.`);
+            failures.push(`${asset.id}: animation set requires verified redistributable license evidence.`);
         if (!provenanceReady)
-            failures.push(`${asset.id}: cartoon set requires source provenance for episode packaging.`);
+            failures.push(`${asset.id}: animation set requires source provenance for episode packaging.`);
         if (!asset.placeholderFree)
-            failures.push(`${asset.id}: cartoon set is placeholder-tagged and cannot satisfy episode-ready validation.`);
+            failures.push(`${asset.id}: animation set is placeholder-tagged and cannot satisfy episode-ready validation.`);
         if (!setReady)
-            failures.push(`${asset.id}: cartoon set requires bounds, readable materials, and at least 1.5m walkable/framing scale.`);
+            failures.push(`${asset.id}: animation set requires bounds, readable materials, and at least 1.5m walkable/framing scale.`);
         if (asset.sizeBytes > 90 * 1024 * 1024)
-            failures.push(`${asset.id}: cartoon set payload is ${asset.sizeBytes} bytes; expected <= 94371840 for browser episode playback.`);
+            failures.push(`${asset.id}: animation set payload is ${asset.sizeBytes} bytes; expected <= 94371840 for browser episode playback.`);
     }
     else if (role === "prop" || role === "environment") {
         if (!asset.licenseVerified)
-            warnings.push(`${asset.id}: optional cartoon ${role} lacks verified license evidence; publish packages should include provenance for every visible asset.`);
+            warnings.push(`${asset.id}: optional animation ${role} lacks verified license evidence; publish packages should include provenance for every visible asset.`);
         if (!provenanceReady)
-            warnings.push(`${asset.id}: optional cartoon ${role} lacks source provenance.`);
+            warnings.push(`${asset.id}: optional animation ${role} lacks source provenance.`);
     }
     return {
         id: asset.id,
@@ -872,12 +876,12 @@ function createCartoonEpisodeAssetReadiness(asset) {
         failures
     };
 }
-function inferCartoonEpisodeAssetRole(asset) {
+function inferAnimationEpisodeAssetRole(asset) {
     if (asset.type === "audio")
         return "audio";
     if (asset.type === "texture")
         return "texture";
-    const text = cartoonAssetText(asset);
+    const text = animationAssetText(asset);
     if (asset.type === "environment" || /\b(environment|skybox|backdrop|background|world|terrain|horizon)\b/i.test(text))
         return "environment";
     if (/\b(set|stage|room|garden|park|school|street|house|classroom|moon garden|walkable|floor|location)\b/i.test(text))
@@ -894,17 +898,17 @@ function inferCartoonEpisodeAssetRole(asset) {
         return "prop";
     return "unknown";
 }
-function isCartoonCharacterAnimationReady(asset) {
+function isAnimationCharacterAnimationReady(asset) {
     if (asset.animations.length > 0)
         return true;
-    return /\b(segmented rig|segmented-rig|puppet rig|body parts|armature|skinned|skeleton)\b/i.test(cartoonAssetText(asset));
+    return /\b(segmented rig|segmented-rig|puppet rig|body parts|armature|skinned|skeleton)\b/i.test(animationAssetText(asset));
 }
-function inferCartoonMouthMode(asset) {
+function inferAnimationMouthMode(asset) {
     const morphNames = asset.morphTargets?.targetNames ?? [];
     if (morphNames.some((name) => /\b(aa|oh|ee|mouth|lip|jaw|viseme|smile|frown|blink|expression)\b/i.test(name))) {
         return "blendshape-lip-sync";
     }
-    const text = cartoonAssetText(asset);
+    const text = animationAssetText(asset);
     if (/\b(primitive mouth|mouth card|mouth-card|mouth sprite|face card|viseme card|2d mouth)\b/i.test(text)) {
         return "primitive-mouth-card";
     }
@@ -913,14 +917,14 @@ function inferCartoonMouthMode(asset) {
     }
     return "missing-mouth-motion";
 }
-function isCartoonSetReady(asset) {
+function isAnimationSetReady(asset) {
     const size = asset.boundsMetadata?.size ?? asset.bounds;
     if (!size)
         return false;
     const largest = Math.max(...size);
     return largest >= 1.5 && asset.materials.length > 0;
 }
-function cartoonAssetText(asset) {
+function animationAssetText(asset) {
     return [
         asset.id,
         asset.source,
@@ -1553,10 +1557,35 @@ function createAssetProvenance(projectDir, sourcePath, options, detected) {
         ...(options.author ?? detected?.author ? { author: options.author ?? detected?.author } : {}),
         ...(options.sourceFamily ?? detected?.sourceFamily ? { sourceFamily: options.sourceFamily ?? detected?.sourceFamily } : {}),
         ...(options.attribution ?? detected?.attribution ? { attribution: options.attribution ?? detected?.attribution } : {}),
+        ...(options.sha256 ?? detected?.sha256 ? { sha256: options.sha256 ?? detected?.sha256 } : {}),
+        ...(options.retrievedAt ?? detected?.retrievedAt ? { retrievedAt: options.retrievedAt ?? detected?.retrievedAt } : {}),
         ...(detected?.evidence && detected.evidence.length > 0 ? { evidence: detected.evidence } : {}),
         checkedAt: new Date().toISOString()
     };
 }
+/**
+ * Merge a freshly inspected asset's auto-detected provenance over the entry that
+ * already exists in the manifest, so a re-add/re-resolve preserves hand-authored
+ * fields (license, attribution, author, sourceUrl, sourceFamily, evidence,
+ * sha256) that the new pass did not re-detect. Freshly detected values win over
+ * the prior entry; explicit `addAsset` options still win over both (applied in
+ * {@link createAssetProvenance}). (#26)
+ */
+function mergeDetectedProvenance(existing, detected) {
+    if (!existing)
+        return detected;
+    const evidence = [...(detected?.evidence ?? []), ...(existing.evidence ?? [])];
+    return {
+        sourceUrl: detected?.sourceUrl ?? existing.sourceUrl,
+        license: detected?.license ?? existing.license,
+        author: detected?.author ?? existing.author,
+        sourceFamily: detected?.sourceFamily ?? existing.sourceFamily,
+        attribution: detected?.attribution ?? existing.attribution,
+        sha256: detected?.sha256 ?? existing.sha256,
+        retrievedAt: detected?.retrievedAt ?? existing.retrievedAt,
+        ...(evidence.length > 0 ? { evidence: [...new Set(evidence)] } : {})
+    };
+}
 function readExternalProvenance(projectDir, provenanceFile) {
     if (!provenanceFile)
         return new Map();
@@ -1586,6 +1615,8 @@ function readExternalProvenance(projectDir, provenanceFile) {
         const sourceFamily = stringValue(record.sourceFamily ?? nestedProvenance?.sourceFamily ?? nestedProvenance?.sourcePack);
         const author = stringValue(record.author ?? nestedProvenance?.author);
         const attribution = stringValue(record.attribution ?? record.credit ?? nestedProvenance?.attribution);
+        const sha256 = stringValue(record.sha256 ?? nestedProvenance?.sha256);
+        const retrievedAt = stringValue(record.retrievedAt ?? nestedProvenance?.retrievedAt);
         const evidence = [
             ...stringArrayValue(record.evidence),
             ...stringArrayValue(record.intendedRouteUsage),
@@ -1598,6 +1629,8 @@ function readExternalProvenance(projectDir, provenanceFile) {
             ...(author ? { author } : {}),
             ...(sourceFamily ? { sourceFamily } : {}),
             ...(attribution ? { attribution } : {}),
+            ...(sha256 ? { sha256 } : {}),
+            ...(retrievedAt ? { retrievedAt } : {}),
             ...(evidence.length > 0 ? { evidence } : {}),
             checkedAt
         });