@series-inc/stowkit-cli 0.1.25 → 0.1.27

package/dist/cli.js

@@ -9,6 +9,7 @@ import { initProject } from './init.js';
 import { cleanupProject } from './cleanup.js';
 import { createMaterial } from './create-material.js';
 import { renameAsset, moveAsset, deleteAsset, setStringId } from './asset-commands.js';
+import { inspectPack } from './inspect.js';
 const args = process.argv.slice(2);
 const thisDir = path.dirname(fileURLToPath(import.meta.url));
 function checkForUpdate() {
@@ -49,6 +50,7 @@ Usage:
   stowkit move <path> <folder>    Move an asset to a different folder
   stowkit delete <path>           Delete an asset and its sidecar files
   stowkit set-id <path> <id>      Change an asset's stringId
+  stowkit inspect <file.stow>     Show manifest of a built .stow pack
   stowkit update                  Update CLI to latest version and refresh skill files
   stowkit version                 Show installed version
   stowkit packer [dir]            Open the packer GUI
@@ -208,6 +210,15 @@ async function main() {
                 await setStringId('.', positional[0], positional[1]);
                 break;
             }
+            case 'inspect': {
+                const stowPath = args.find(a => !a.startsWith('-') && a !== command);
+                if (!stowPath) {
+                    console.error('Usage: stowkit inspect <file.stow>');
+                    process.exit(1);
+                }
+                await inspectPack(stowPath, { verbose });
+                break;
+            }
             case 'packer': {
                 const packerDir = resolveAppDir('@series-inc/stowkit-packer-gui', 'stowkit-packer-gui');
                 if (!packerDir) {

package/dist/inspect.d.ts

@@ -0,0 +1,3 @@
+export declare function inspectPack(filePath: string, opts?: {
+    verbose?: boolean;
+}): Promise<void>;

package/dist/inspect.js

@@ -0,0 +1,165 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { BinaryReader } from './core/binary.js';
+import { AssetType } from './core/types.js';
+import { STOW_MAGIC, FILE_HEADER_SIZE, STRING_ID_SIZE, } from './core/constants.js';
+import { unwrapMetadata } from './format/metadata.js';
+const ASSET_TYPE_NAMES = {
+    [AssetType.Unknown]: 'unknown',
+    [AssetType.StaticMesh]: 'staticMesh',
+    [AssetType.Texture2D]: 'texture',
+    [AssetType.Audio]: 'audio',
+    [AssetType.MaterialSchema]: 'material',
+    [AssetType.SkinnedMesh]: 'skinnedMesh',
+    [AssetType.AnimationClip]: 'animation',
+    [AssetType.GlbContainer]: 'glbContainer',
+};
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/** Read stringId from the start of unwrapped asset metadata based on type. */
+function readStringIdAndDetails(type, meta) {
+    const r = new BinaryReader(meta);
+    switch (type) {
+        case AssetType.Texture2D: {
+            const width = r.readUint32();
+            const height = r.readUint32();
+            const channels = r.readUint32();
+            r.readUint32(); // channelFormat
+            const stringId = r.readFixedString(STRING_ID_SIZE);
+            return { stringId, details: `${width}x${height}, ${channels}ch` };
+        }
+        case AssetType.Audio: {
+            const stringId = r.readFixedString(STRING_ID_SIZE);
+            const sampleRate = r.readUint32();
+            const channels = r.readUint32();
+            const durationMs = r.readUint32();
+            const durSec = (durationMs / 1000).toFixed(1);
+            return { stringId, details: `${durSec}s, ${sampleRate}Hz, ${channels}ch` };
+        }
+        case AssetType.StaticMesh: {
+            const geoCount = r.readUint32();
+            const matCount = r.readUint32();
+            const nodeCount = r.readUint32();
+            const stringId = r.readFixedString(STRING_ID_SIZE);
+            return { stringId, details: `${geoCount} geo, ${matCount} mat, ${nodeCount} nodes` };
+        }
+        case AssetType.SkinnedMesh: {
+            const geoCount = r.readUint32();
+            const matCount = r.readUint32();
+            const nodeCount = r.readUint32();
+            const boneCount = r.readUint32();
+            const stringId = r.readFixedString(STRING_ID_SIZE);
+            return { stringId, details: `${geoCount} geo, ${boneCount} bones` };
+        }
+        case AssetType.AnimationClip: {
+            const stringId = r.readFixedString(STRING_ID_SIZE);
+            r.readFixedString(STRING_ID_SIZE); // targetMeshId
+            r.readUint32(); // metadataVersion
+            const duration = r.readFloat32();
+            const trackCount = r.readUint32();
+            return { stringId, details: `${duration.toFixed(2)}s, ${trackCount} tracks` };
+        }
+        case AssetType.MaterialSchema: {
+            const stringId = r.readFixedString(STRING_ID_SIZE);
+            const schemaName = r.readFixedString(64);
+            const fieldCount = r.readUint32();
+            return { stringId, details: `schema: ${schemaName}, ${fieldCount} fields` };
+        }
+        default:
+            return { stringId: '?', details: '' };
+    }
+}
+export async function inspectPack(filePath, opts) {
+    const absPath = path.resolve(filePath);
+    const data = await fs.readFile(absPath);
+    const buf = new Uint8Array(data);
+    if (buf.length < FILE_HEADER_SIZE) {
+        throw new Error(`File too small to be a .stow pack: ${buf.length} bytes`);
+    }
+    // Read header
+    const hr = new BinaryReader(buf);
+    const magic = hr.readUint32();
+    if (magic !== STOW_MAGIC) {
+        throw new Error(`Invalid magic: 0x${magic.toString(16)} (expected 0x${STOW_MAGIC.toString(16)})`);
+    }
+    const version = hr.readUint32();
+    const assetCount = hr.readUint32();
+    const dirOffset = hr.readUint64AsNumber();
+    // Read directory entries
+    const entries = [];
+    const dr = new BinaryReader(buf, dirOffset);
+    for (let i = 0; i < assetCount; i++) {
+        entries.push({
+            uid: dr.readUint64(),
+            type: dr.readUint32(),
+            dataOffset: dr.readUint64AsNumber(),
+            dataSize: dr.readUint64AsNumber(),
+            metadataOffset: dr.readUint64AsNumber(),
+            metadataSize: dr.readUint32(),
+        });
+    }
+    // Parse each asset's metadata
+    const assets = [];
+    for (const entry of entries) {
+        const typeName = ASSET_TYPE_NAMES[entry.type] ?? `type(${entry.type})`;
+        let stringId = '?';
+        let tags = [];
+        let details = '';
+        if (entry.metadataOffset > 0 && entry.metadataSize > 0) {
+            const rawMeta = buf.slice(entry.metadataOffset, entry.metadataOffset + entry.metadataSize);
+            // Try tag-wrapped first; if tagCsvLength looks unreasonable, treat as raw metadata
+            let assetMeta;
+            try {
+                const unwrapped = unwrapMetadata(rawMeta);
+                // Sanity check: tagCsvLength should be small (< 4096); if it's huge, it's raw metadata
+                const tagCsvLen = new DataView(rawMeta.buffer, rawMeta.byteOffset, 4).getUint32(0, true);
+                if (tagCsvLen < 4096 && tagCsvLen < rawMeta.length) {
+                    tags = unwrapped.tags;
+                    assetMeta = unwrapped.assetMetadata;
+                }
+                else {
+                    assetMeta = rawMeta;
+                }
+            }
+            catch {
+                assetMeta = rawMeta;
+            }
+            try {
+                const parsed = readStringIdAndDetails(entry.type, assetMeta);
+                stringId = parsed.stringId;
+                details = parsed.details;
+            }
+            catch {
+                // Metadata format not recognized — show what we can
+            }
+        }
+        assets.push({ type: typeName, stringId, dataSize: entry.dataSize, tags, details });
+    }
+    // Sort by type then stringId
+    assets.sort((a, b) => a.type.localeCompare(b.type) || a.stringId.localeCompare(b.stringId));
+    // Print
+    const packName = path.basename(absPath);
+    const totalSize = buf.length;
+    console.log(`\nPack: ${packName} (${formatBytes(totalSize)}, v${version})`);
+    console.log(`Assets: ${assetCount}\n`);
+    // Calculate column widths
+    const typeWidth = Math.max(4, ...assets.map(a => a.type.length));
+    const idWidth = Math.max(8, ...assets.map(a => a.stringId.length));
+    for (const a of assets) {
+        const type = `[${a.type}]`.padEnd(typeWidth + 2);
+        const id = a.stringId.padEnd(idWidth);
+        const size = formatBytes(a.dataSize).padStart(10);
+        let line = `  ${type}  ${id}  ${size}`;
+        if (opts?.verbose && a.details)
+            line += `  ${a.details}`;
+        if (a.tags.length > 0 && a.tags[0] !== '')
+            line += `  [${a.tags.join(', ')}]`;
+        console.log(line);
+    }
+    console.log('');
+}

package/dist/orchestrator.js

@@ -453,22 +453,45 @@ export async function showStatus(projectDir) {
     console.log(`Meta files: ${scan.metaFiles.length}`);
     const packs = config.config.packs ?? [{ name: 'default' }];
     console.log(`Packs: ${packs.map(p => p.name).join(', ')}`);
-    // Count stale
+    // Count stale (including GLB children)
     let cached = 0;
     let stale = 0;
+    const staleIds = [];
     for (const file of scan.sourceFiles) {
         const meta = await readStowmeta(config.srcArtDir, file.relativePath);
         if (!meta) {
             stale++;
+            staleIds.push(file.relativePath);
             continue;
         }
         const { type, settings } = stowmetaToAssetSettings(meta);
         if (meta.cache && isCacheValid(meta, file, type, settings)) {
             cached++;
         }
-        else {
+        else if (type !== AssetType.GlbContainer) {
             stale++;
+            staleIds.push(file.relativePath);
+        }
+        // Check GLB children
+        if (meta.type === 'glbContainer') {
+            const glbMeta = meta;
+            for (const child of glbMeta.children ?? []) {
+                if (child.childType === 'materialSchema')
+                    continue;
+                const childId = `${file.relativePath}/${child.name}`;
+                if (child.cache) {
+                    cached++;
+                }
+                else {
+                    stale++;
+                    staleIds.push(childId);
+                }
+            }
         }
     }
     console.log(`Cached: ${cached}, Needs processing: ${stale}`);
+    if (staleIds.length > 0) {
+        for (const id of staleIds)
+            console.log(`  ${id}`);
+    }
 }

package/dist/server.js

@@ -89,12 +89,18 @@ function queueProcessing(opts = {}) {
                 }
             }
         }
-        // Build the processing queue — process children directly (their source data
-        // is already in BlobStore from the initial GLB extraction). Only promote to
-        // parent container when the container itself is a target (re-export, preserveHierarchy change).
+        // Build the processing queue.
+        // If a GLB container is in the queue, skip its children — processGlbContainer
+        // handles all child processing internally. Without this, drain workers race:
+        // a child worker and the container worker both process the same children,
+        // and the container replaces the assets array mid-flight.
+        const containerIds = new Set(targets.filter(a => a.type === AssetType.GlbContainer).map(a => a.id));
         const queue = [];
         const seen = new Set();
         for (const a of targets) {
+            // Skip children whose parent container is also being processed
+            if (a.parentId && containerIds.has(a.parentId))
+                continue;
             if (!seen.has(a.id)) {
                 seen.add(a.id);
                 queue.push(a.id);
@@ -115,6 +121,16 @@ function queueProcessing(opts = {}) {
             workers.push(drain());
         }
         await Promise.all(workers);
+        // Diagnostic: log any assets that aren't ready after processing completes
+        const notReady = assets.filter(a => a.status !== 'ready' && a.type !== AssetType.MaterialSchema);
+        if (notReady.length > 0) {
+            console.log(`[server] WARNING: ${notReady.length} asset(s) still not ready after processing:`);
+            for (const a of notReady)
+                console.log(`  ${a.id} → ${a.status}${a.error ? ` (${a.error})` : ''}`);
+        }
+        else {
+            console.log(`[server] All ${assets.length} assets ready.`);
+        }
         broadcast({ type: 'processing-complete' });
     })();
     if (opts.await)
@@ -155,7 +171,8 @@ async function expandGlbChildren(srcArtDir, containerId, containerMeta, configur
             fileName: child.name,
             stringId: child.stringId || baseName,
             type: childType,
-            status: 'pending',
+            // Materials are metadata-only — always ready, no processing needed
+            status: childType === AssetType.MaterialSchema ? 'ready' : 'pending',
             settings: childSettings,
             sourceSize: 0,
             processedSize: 0,
@@ -263,7 +280,14 @@ async function processGlbContainer(containerId) {
         const existing = existingChildren.get(anim.name);
         childrenManifest.push(existing ?? generateDefaultGlbChild(anim.name, 'animationClip'));
     }
-    // Update container stowmeta with full inline children
+    // Clear old cache stamps on all children — processGlbContainer always re-processes
+    // everything (the container was marked pending, so children must be reprocessed too).
+    // Without this, expandGlbChildren would restore children from stale cache and skip
+    // re-processing (e.g. after a preserveHierarchy toggle).
+    for (const child of childrenManifest) {
+        delete child.cache;
+    }
+    // Update container stowmeta with full inline children (cache stamps cleared)
     if (containerStowmeta) {
         containerStowmeta.children = childrenManifest;
         await writeStowmeta(projectConfig.srcArtDir, containerId, containerStowmeta);
@@ -271,7 +295,7 @@ async function processGlbContainer(containerId) {
     // Remove old child assets from the list
     const prefix = containerId + '/';
     assets = assets.filter(a => !a.id.startsWith(prefix));
-    // Create child assets from inline entries
+    // Create child assets from inline entries (all will be 'pending' since cache was cleared)
     const childAssets = await expandGlbChildren(projectConfig.srcArtDir, containerId, { ...containerStowmeta, children: childrenManifest }, configuredPacks);
     // Set up material configs for extracted GLB materials (runtime config from inline)
     for (const mat of extract.materials) {
@@ -352,16 +376,56 @@ async function processGlbContainer(containerId) {
             }
         }
     }
-    // Persist updated stowmeta (may have auto-assigned materialOverrides)
+    // Process texture children (their raw image data is in BlobStore from extraction)
+    const pendingTextures = childAssets.filter(a => a.status === 'pending' && a.type === AssetType.Texture2D);
+    await Promise.all(pendingTextures.map(child => processOneAsset(child.id)));
+    // Write cache blobs and stamps for ALL children processed in this container.
+    // Without this, a server restart / rescan would see no cache → children restart as 'pending'.
+    const parentSnapshot = await getFileSnapshot(projectConfig.srcArtDir, containerId);
+    for (const childAsset of childAssets) {
+        if (childAsset.status !== 'ready')
+            continue;
+        if (childAsset.type === AssetType.MaterialSchema)
+            continue;
+        const childName = childAsset.id.split('/').pop();
+        const inlineChild = childrenManifest.find(c => c.name === childName);
+        if (!inlineChild)
+            continue;
+        // Collect cache blobs for this child
+        const cacheEntries = new Map();
+        const processed = BlobStore.getProcessed(childAsset.id);
+        if (processed)
+            cacheEntries.set(childAsset.id, processed);
+        if (childAsset.metadata) {
+            cacheEntries.set(`${childAsset.id}:__metadata__`, new TextEncoder().encode(JSON.stringify(childAsset.metadata)));
+        }
+        for (const suffix of [':skinnedMeta', ':animMeta', ':animCount']) {
+            const blob = BlobStore.getProcessed(`${childAsset.id}${suffix}`);
+            if (blob)
+                cacheEntries.set(`${childAsset.id}${suffix}`, blob);
+        }
+        const animCountBlob = BlobStore.getProcessed(`${childAsset.id}:animCount`);
+        const clipCount = animCountBlob ? animCountBlob[0] : 0;
+        for (let ci = 0; ci < clipCount; ci++) {
+            for (const key of [`${childAsset.id}:anim:${ci}`, `${childAsset.id}:animMeta:${ci}`]) {
+                const blob = BlobStore.getProcessed(key);
+                if (blob)
+                    cacheEntries.set(key, blob);
+            }
+        }
+        if (cacheEntries.size > 0) {
+            await writeCacheBlobs(projectConfig.srcArtDir, childAsset.id, cacheEntries);
+        }
+        // Set cache stamp on the inline child entry (uses parent file snapshot)
+        if (parentSnapshot) {
+            inlineChild.cache = buildCacheStamp(parentSnapshot, childAsset.type, childAsset.settings);
+        }
+    }
+    // Persist updated stowmeta with materialOverrides AND cache stamps
     if (containerStowmeta) {
         containerStowmeta.children = childrenManifest;
         await writeStowmeta(projectConfig.srcArtDir, containerId, containerStowmeta);
     }
-    // Queue texture children for processing (their raw image data is in BlobStore)
-    const pendingTextures = childAssets.filter(a => a.status === 'pending' && a.type === AssetType.Texture2D);
-    for (const child of pendingTextures) {
-        processOneAsset(child.id);
-    }
 }
 async function readBody(req) {
     const chunks = [];
@@ -528,26 +592,21 @@ async function processOneAsset(id) {
                     throw new Error(`Could not read parent GLB: ${asset.parentId}`);
                 parentSource = data;
             }
-            const extract = await parseGlb(parentSource);
+            // Read parent's preserveHierarchy setting
+            const parentMeta = await readStowmeta(projectConfig.srcArtDir, asset.parentId);
+            const preserveHierarchy = parentMeta?.preserveHierarchy ?? false;
+            const extract = await parseGlb(parentSource, { preserveHierarchy });
             const childName = id.split('/').pop();
+            let childResult = null;
             if (asset.type === AssetType.Texture2D) {
                 const tex = extract.textures.find(t => t.name === childName);
                 if (!tex)
                     throw new Error(`Texture "${childName}" not found in GLB`);
                 BlobStore.setSource(id, tex.data);
-                // Process via worker pool
                 const { result, blobs } = await workerPool.processAsset({ id, sourceData: tex.data, type: asset.type, stringId: asset.stringId, settings: asset.settings }, (pid, msg) => broadcast({ type: 'progress', id: pid, message: msg }));
                 for (const [key, data] of blobs)
                     BlobStore.setProcessed(key, data);
-                if (asset.status !== 'pending') {
-                    asset.status = 'ready';
-                    asset.metadata = result.metadata;
-                    asset.processedSize = result.processedSize;
-                    broadcast({
-                        type: 'asset-update', id,
-                        updates: { status: 'ready', metadata: result.metadata, processedSize: result.processedSize },
-                    });
-                }
+                childResult = result;
             }
             else if (asset.type === AssetType.StaticMesh || asset.type === AssetType.SkinnedMesh) {
                 const mesh = extract.meshes.find(m => m.name === childName);
@@ -556,15 +615,7 @@ async function processOneAsset(id) {
                 const { result, blobs } = await workerPool.processExtractedMesh({ childId: id, imported: mesh.imported, hasSkeleton: mesh.hasSkeleton, stringId: asset.stringId, settings: asset.settings }, (pid, msg) => broadcast({ type: 'progress', id: pid, message: msg }));
                 for (const [key, data] of blobs)
                     BlobStore.setProcessed(key, data);
-                if (asset.status !== 'pending') {
-                    asset.status = 'ready';
-                    asset.metadata = result.metadata;
-                    asset.processedSize = result.processedSize;
-                    broadcast({
-                        type: 'asset-update', id,
-                        updates: { status: 'ready', metadata: result.metadata, processedSize: result.processedSize },
-                    });
-                }
+                childResult = result;
             }
             else {
                 // Animation or other — fall back to full container reprocess
@@ -575,7 +626,52 @@ async function processOneAsset(id) {
                 }
                 return;
             }
-            console.log(`[server] Re-processed GLB child ${id}`);
+            if (childResult && asset.status !== 'pending') {
+                asset.status = 'ready';
+                asset.metadata = childResult.metadata;
+                asset.processedSize = childResult.processedSize;
+                broadcast({
+                    type: 'asset-update', id,
+                    updates: { status: 'ready', metadata: childResult.metadata, processedSize: childResult.processedSize },
+                });
+            }
+            // Write cache for this child
+            const cacheEntries = new Map();
+            const processed = BlobStore.getProcessed(id);
+            if (processed)
+                cacheEntries.set(id, processed);
+            if (childResult?.metadata) {
+                cacheEntries.set(`${id}:__metadata__`, new TextEncoder().encode(JSON.stringify(childResult.metadata)));
+            }
+            for (const suffix of [':skinnedMeta', ':animMeta', ':animCount']) {
+                const blob = BlobStore.getProcessed(`${id}${suffix}`);
+                if (blob)
+                    cacheEntries.set(`${id}${suffix}`, blob);
+            }
+            const animCountBlob = BlobStore.getProcessed(`${id}:animCount`);
+            const clipCount = animCountBlob ? animCountBlob[0] : 0;
+            for (let ci = 0; ci < clipCount; ci++) {
+                for (const key of [`${id}:anim:${ci}`, `${id}:animMeta:${ci}`]) {
+                    const blob = BlobStore.getProcessed(key);
+                    if (blob)
+                        cacheEntries.set(key, blob);
+                }
+            }
+            if (cacheEntries.size > 0) {
+                await writeCacheBlobs(projectConfig.srcArtDir, id, cacheEntries);
+                // Update cache stamp in parent's stowmeta for this child
+                if (parentMeta) {
+                    const inlineChild = parentMeta.children.find(c => c.name === childName);
+                    if (inlineChild) {
+                        const parentSnapshot = await getFileSnapshot(projectConfig.srcArtDir, asset.parentId);
+                        if (parentSnapshot) {
+                            inlineChild.cache = buildCacheStamp(parentSnapshot, asset.type, asset.settings);
+                            await writeStowmeta(projectConfig.srcArtDir, asset.parentId, parentMeta);
+                        }
+                    }
+                }
+            }
+            console.log(`[server] Re-processed GLB child ${id} (status: ${asset.status}, in assets: ${assets.some(a => a.id === id)})`);
         }
         catch (err) {
             asset.status = 'error';
@@ -1473,10 +1569,12 @@ export async function startServer(opts = {}) {
         }));
         ws.on('close', () => wsClients.delete(ws));
     });
-    // Initialize worker pool
-    workerPool = initWorkerPool(opts.wasmDir);
-    // Open project if specified
-    if (opts.projectDir) {
+    // Initialize worker pool (shared across servers in the same process)
+    if (!workerPool) {
+        workerPool = initWorkerPool(opts.wasmDir);
+    }
+    // Open project if specified (skip if already loaded — e.g. stowkit editor starts two servers)
+    if (opts.projectDir && (!projectConfig || projectConfig.projectDir !== opts.projectDir)) {
         await openProject(opts.projectDir);
         queueProcessing();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@series-inc/stowkit-cli",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "type": "module",
   "bin": {
     "stowkit": "./dist/cli.js"

package/skill.md

@@ -50,6 +50,7 @@ stowkit rename <path> <name>    # Rename an asset file (preserves extension, upd
 stowkit move <path> <folder>    # Move an asset to a different folder (updates GLB child refs)
 stowkit delete <path>           # Delete an asset and its .stowmeta/.stowcache files
 stowkit set-id <path> <id>      # Change an asset's stringId
+stowkit inspect <file.stow>    # Show manifest of a built .stow pack (use -v for details)
 stowkit packer [dir]            # Open the packer GUI in browser
 stowkit editor [dir]            # Open the level editor in browser
 stowkit serve [dir]             # Start API server only (no GUI)