@series-inc/stowkit-cli 0.1.24 → 0.1.26

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() {
@@ -24,7 +25,7 @@ function checkForUpdate() {
             const latest = data.version;
             if (latest && latest !== localVersion) {
                 console.log(`\n  Update available: ${localVersion} → ${latest}`);
-                console.log(`  Run: npm install -g @series-inc/stowkit-cli\n`);
+                console.log(`  Run: stowkit update\n`);
             }
         })
             .catch(() => { clearTimeout(timeout); });
@@ -49,6 +50,9 @@ 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
   stowkit editor [dir]            Open the level editor
   stowkit serve [dir]             Start API server only (no GUI)
@@ -76,6 +80,10 @@ function resolveAppDir(packageName, monorepoFolder) {
     }
     return null;
 }
+function getVersion() {
+    const pkg = JSON.parse(fs.readFileSync(path.resolve(thisDir, '../package.json'), 'utf-8'));
+    return pkg.version;
+}
 function openBrowser(url) {
     import('node:child_process').then(({ exec }) => {
         const cmd = process.platform === 'win32' ? 'start' : process.platform === 'darwin' ? 'open' : 'xdg-open';
@@ -99,6 +107,33 @@ async function main() {
             case 'init':
                 await initProject(projectDir, { update: args.includes('--update') });
                 break;
+            case 'update': {
+                const currentVersion = getVersion();
+                console.log(`Current version: ${currentVersion}`);
+                console.log('Checking for updates...');
+                const res = await fetch('https://registry.npmjs.org/@series-inc/stowkit-cli/latest');
+                const data = await res.json();
+                const latest = data.version;
+                if (latest === currentVersion) {
+                    console.log('Already on the latest version.');
+                }
+                else {
+                    console.log(`Updating: ${currentVersion} → ${latest}`);
+                    const { execSync } = await import('node:child_process');
+                    execSync('npm install -g @series-inc/stowkit-cli@latest', { stdio: 'inherit' });
+                    console.log(`Updated to ${latest}.`);
+                }
+                // Refresh skill files if in a StowKit project
+                const configExists = existsSync(path.resolve(projectDir, '.felicityproject'));
+                if (configExists) {
+                    await initProject(projectDir, { update: true });
+                }
+                break;
+            }
+            case 'version':
+            case '--version':
+                console.log(getVersion());
+                break;
             case 'build':
                 await fullBuild(projectDir, opts);
                 break;
@@ -175,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/server.js

@@ -1473,10 +1473,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.24",
+  "version": "0.1.26",
   "type": "module",
   "bin": {
     "stowkit": "./dist/cli.js"

package/skill.md

@@ -38,6 +38,8 @@ A StowKit project has a `.felicityproject` JSON file at its root:
 ```bash
 stowkit init [dir]              # Scaffold a new project (creates .felicityproject, assets/, public/cdn-assets/)
 stowkit init --update [dir]     # Update AI skill files to match installed CLI version
+stowkit update                  # Update CLI to latest version and refresh skill files
+stowkit version                 # Show installed version
 stowkit build [dir]             # Full build: scan + process + pack
 stowkit scan [dir]              # Detect new assets and generate .stowmeta defaults
 stowkit process [dir]           # Compress assets (respects cache)
@@ -48,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)
@@ -506,17 +509,19 @@ PerfLogger.enable();
 PerfLogger.disable();
 ```
 
-## Updating This Skill File
+## Updating the CLI and This Skill File
 
-This skill file is bundled with the `@series-inc/stowkit-cli` package. When the CLI is updated to a newer version, the local copy of this file may become outdated. To refresh it:
+This skill file is bundled with the `@series-inc/stowkit-cli` package. To update the CLI to the latest version and refresh this file in one step:
 
 ```bash
-stowkit init --update
+stowkit update
 ```
 
-This overwrites `.claude/skills/stowkit/SKILL.md` and `.cursor/rules/stowkit.mdc` with the version shipped in the currently installed CLI. It does not touch the project config, directories, or any asset files.
+This updates the global CLI install, then overwrites `.claude/skills/stowkit/SKILL.md` and `.cursor/rules/stowkit.mdc` with the version shipped in the new CLI. It does not touch the project config, directories, or any asset files.
 
-**When to run this:** After upgrading the CLI (`npm install -g @series-inc/stowkit-cli@latest`), or if you notice this skill file is missing documentation for commands that exist in `stowkit --help`.
+To refresh skill files without updating the CLI: `stowkit init --update`
+
+**When to run this:** If you notice this skill file is missing documentation for commands that exist in `stowkit --help`, or if the user asks you to update StowKit.
 
 ## Common Tasks for AI Agents