@series-inc/stowkit-cli 0.1.30 → 0.6.14

package/dist/cli.js

@@ -38,7 +38,9 @@ checkForUpdate();
 function printUsage() {
     console.log(`
 Usage:
-  stowkit init [dir]              Initialize a StowKit project
+  stowkit init [dir]              Initialize a StowKit project (interactive menu)
+  stowkit init --with-engine      Initialize with 3D engine included
+  stowkit init --no-engine        Initialize without 3D engine (skip prompt)
   stowkit init --update [dir]     Update AI skill files to match installed CLI version
   stowkit build [dir]             Full build: scan + process + pack
   stowkit scan [dir]              Detect new assets, generate .stowmeta defaults
@@ -105,7 +107,11 @@ async function main() {
     try {
         switch (command) {
             case 'init':
-                await initProject(projectDir, { update: args.includes('--update') });
+                await initProject(projectDir, {
+                    update: args.includes('--update'),
+                    withEngine: args.includes('--with-engine'),
+                    noEngine: args.includes('--no-engine'),
+                });
                 break;
             case 'update': {
                 const currentVersion = getVersion();

package/dist/index.d.ts

@@ -26,3 +26,4 @@ export { startServer } from './server.js';
 export type { ServerOptions } from './server.js';
 export { initProject } from './init.js';
 export { cleanupProject } from './cleanup.js';
+export { syncRuntimeAssets } from './sync-runtime-assets.js';

package/dist/index.js

@@ -33,3 +33,5 @@ export { startServer } from './server.js';
 export { initProject } from './init.js';
 // Cleanup
 export { cleanupProject } from './cleanup.js';
+// Runtime asset sync
+export { syncRuntimeAssets } from './sync-runtime-assets.js';

package/dist/init.d.ts

@@ -1,4 +1,6 @@
 export interface InitOptions {
     update?: boolean;
+    withEngine?: boolean;
+    noEngine?: boolean;
 }
 export declare function initProject(projectDir: string, opts?: InitOptions): Promise<void>;

package/dist/init.js

@@ -1,6 +1,36 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
+import * as readline from 'node:readline';
 import { fileURLToPath } from 'node:url';
+async function promptMenu(question, choices) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        console.log(`\n${question}\n`);
+        for (let i = 0; i < choices.length; i++) {
+            console.log(`  ${i + 1}) ${choices[i]}`);
+        }
+        console.log('');
+        const ask = () => {
+            rl.question('Choose [1]: ', (answer) => {
+                const trimmed = answer.trim();
+                if (trimmed === '') {
+                    rl.close();
+                    resolve(0);
+                    return;
+                }
+                const num = parseInt(trimmed, 10);
+                if (num >= 1 && num <= choices.length) {
+                    rl.close();
+                    resolve(num - 1);
+                    return;
+                }
+                console.log(`  Please enter 1-${choices.length}`);
+                ask();
+            });
+        };
+        ask();
+    });
+}
 export async function initProject(projectDir, opts) {
     const absDir = path.resolve(projectDir);
     const configPath = path.join(absDir, '.felicityproject');
@@ -15,6 +45,7 @@ export async function initProject(projectDir, opts) {
             process.exit(1);
         }
         await copySkillFiles(absDir);
+        await copyEngineSkillFiles(absDir);
         console.log('Updated AI skill files:');
         console.log('  .claude/skills/stowkit/SKILL.md');
         console.log('  .cursor/rules/stowkit.mdc');
@@ -29,6 +60,16 @@ export async function initProject(projectDir, opts) {
     catch {
         // Does not exist — create it
     }
+    // Prompt for engine setup unless explicitly set via flag
+    let withEngine = opts?.withEngine ?? false;
+    const noEngine = opts?.noEngine ?? false;
+    if (!withEngine && !noEngine && process.stdin.isTTY) {
+        const choice = await promptMenu('What would you like to set up?', [
+            'StowKit (asset pipeline only)',
+            'StowKit + 3D Engine (includes @series-inc/rundot-3d-engine)',
+        ]);
+        withEngine = choice === 1;
+    }
     // Create srcArtDir with .gitignore for cache files
     const srcArtDir = 'assets';
     await fs.mkdir(path.join(absDir, srcArtDir), { recursive: true });
@@ -72,10 +113,36 @@ export async function initProject(projectDir, opts) {
     console.log(`  Output dir:     public/cdn-assets/`);
     console.log(`  Config:         .felicityproject`);
     console.log(`  AI skills:      .claude/skills/stowkit/SKILL.md, .cursor/rules/stowkit.mdc`);
+    // Install engine if selected
+    if (withEngine) {
+        await installEngine(absDir);
+    }
     console.log('');
     console.log('Drop your assets (PNG, JPG, FBX, WAV, etc.) into assets/');
     console.log('Then run: stowkit build');
 }
+async function installEngine(absDir) {
+    console.log('');
+    console.log('Installing @series-inc/rundot-3d-engine and three...');
+    const { execSync } = await import('node:child_process');
+    try {
+        execSync('npm install @series-inc/rundot-3d-engine three', {
+            cwd: absDir,
+            stdio: 'inherit',
+        });
+    }
+    catch {
+        console.error('Failed to install engine packages. You can install manually:');
+        console.error('  npm install @series-inc/rundot-3d-engine three');
+        return;
+    }
+    await copyEngineSkillFiles(absDir);
+    console.log('');
+    console.log('  3D Engine installed:');
+    console.log('    @series-inc/rundot-3d-engine');
+    console.log('    three');
+    console.log('  AI skills: .claude/skills/stowkit-engine/SKILL.md, .cursor/rules/stowkit-engine.mdc');
+}
 async function copySkillFiles(absDir) {
     const thisDir = path.dirname(fileURLToPath(import.meta.url));
     const skillSrc = path.resolve(thisDir, '../skill.md');
@@ -92,3 +159,34 @@ async function copySkillFiles(absDir) {
         // Skill file not found in package — skip silently
     }
 }
+async function copyEngineSkillFiles(absDir) {
+    const thisDir = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        // Monorepo dev: sibling folder
+        path.resolve(thisDir, '../../stowkit-engine/SKILL.md'),
+        // Installed in project's node_modules
+        path.join(absDir, 'node_modules/@series-inc/rundot-3d-engine/SKILL.md'),
+        // Installed as dep of CLI: nested node_modules
+        path.resolve(thisDir, '../node_modules/@series-inc/rundot-3d-engine/SKILL.md'),
+        // Hoisted in global node_modules
+        path.resolve(thisDir, '../../../@series-inc/rundot-3d-engine/SKILL.md'),
+    ];
+    let skillContent = null;
+    for (const candidate of candidates) {
+        try {
+            skillContent = await fs.readFile(candidate, 'utf-8');
+            break;
+        }
+        catch {
+            // not found, try next
+        }
+    }
+    if (!skillContent)
+        return;
+    const claudeDir = path.join(absDir, '.claude', 'skills', 'stowkit-engine');
+    await fs.mkdir(claudeDir, { recursive: true });
+    await fs.writeFile(path.join(claudeDir, 'SKILL.md'), skillContent);
+    const cursorDir = path.join(absDir, '.cursor', 'rules');
+    await fs.mkdir(cursorDir, { recursive: true });
+    await fs.writeFile(path.join(cursorDir, 'stowkit-engine.mdc'), `---\ndescription: Rundot 3D Engine — VenusGame, GameObject, Component, physics, animations, StowKit asset loading\nalwaysApply: true\n---\n\n${skillContent}`);
+}

package/dist/orchestrator.js

@@ -11,6 +11,7 @@ import { readStowmat, stowmatToMaterialConfig } from './app/stowmat-io.js';
 import { readCacheBlobs, writeCacheBlobs, buildCacheStamp, isCacheValid, } from './app/process-cache.js';
 import { buildPack, processExtractedAnimations, validatePackDependencies } from './pipeline.js';
 import { WorkerPool } from './workers/worker-pool.js';
+import { syncRuntimeAssets } from './sync-runtime-assets.js';
 export async function scanProject(projectDir, opts) {
     const config = await readProjectConfig(projectDir);
     const scan = await scanDirectory(config.srcArtDir);
@@ -46,6 +47,8 @@ export async function fullBuild(projectDir, opts) {
         console.log(`Project: ${config.projectName}`);
     if (verbose)
         console.log(`Source dir: ${config.srcArtDir}`);
+    // 0. Sync WASM/Basis/Draco from node_modules → public/stowkit/
+    syncRuntimeAssets(projectDir, verbose);
     // 1. Scan
     const scan = await scanDirectory(config.srcArtDir);
     if (verbose)

package/dist/server.js

@@ -10,6 +10,7 @@ import { detectAssetType, readStowmeta, writeStowmeta, stowmetaToAssetSettings,
 import { readStowmat, writeStowmat, stowmatToMaterialConfig, materialConfigToStowmat } from './app/stowmat-io.js';
 import { readCacheBlobs, writeCacheBlobs, buildCacheStamp, isCacheValid, } from './app/process-cache.js';
 import { buildPack, validatePackDependencies, processExtractedAnimations } from './pipeline.js';
+import { syncRuntimeAssets } from './sync-runtime-assets.js';
 import { parseGlb, pbrToMaterialConfig } from './encoders/glb-loader.js';
 import { WorkerPool } from './workers/worker-pool.js';
 async function scanPrefabFiles(dir, prefix) {
@@ -1577,6 +1578,7 @@ export async function startServer(opts = {}) {
     }
     // Open project if specified (skip if already loaded — e.g. stowkit editor starts two servers)
     if (opts.projectDir && (!projectConfig || projectConfig.projectDir !== opts.projectDir)) {
+        syncRuntimeAssets(opts.projectDir);
         await openProject(opts.projectDir);
         queueProcessing({ force: opts.force });
     }

package/dist/sync-runtime-assets.d.ts

@@ -0,0 +1,11 @@
+interface SyncResult {
+    wasm: boolean;
+    basis: boolean;
+    draco: boolean;
+}
+/**
+ * Copy stowkit_reader.wasm, basis/, and draco/ decoders from node_modules
+ * into `<projectDir>/public/stowkit/`.
+ */
+export declare function syncRuntimeAssets(projectDir: string, verbose?: boolean): SyncResult;
+export {};

package/dist/sync-runtime-assets.js

@@ -0,0 +1,65 @@
+/**
+ * Sync WASM, Basis, and Draco runtime assets from node_modules to public/stowkit/.
+ *
+ * Postinstall scripts are unreliable for keeping these in sync (they don't re-run
+ * on transitive dep updates). This module is called by `stowkit build` and
+ * `stowkit serve/packer/editor` so the files are always fresh.
+ */
+import { existsSync, mkdirSync, readdirSync, copyFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+/**
+ * Copy stowkit_reader.wasm, basis/, and draco/ decoders from node_modules
+ * into `<projectDir>/public/stowkit/`.
+ */
+export function syncRuntimeAssets(projectDir, verbose = false) {
+    const dest = join(projectDir, 'public', 'stowkit');
+    const result = { wasm: false, basis: false, draco: false };
+    // ── WASM ────────────────────────────────────────────────────────────────────
+    const wasmCandidates = [
+        join(projectDir, 'node_modules', '@series-inc', 'stowkit-reader', 'dist', 'stowkit_reader.wasm'),
+    ];
+    for (const src of wasmCandidates) {
+        if (existsSync(src)) {
+            mkdirSync(dest, { recursive: true });
+            copyFileSync(src, join(dest, 'stowkit_reader.wasm'));
+            result.wasm = true;
+            if (verbose)
+                console.log('  Synced stowkit_reader.wasm → public/stowkit/');
+            break;
+        }
+    }
+    // ── Basis & Draco decoders ──────────────────────────────────────────────────
+    const loaderCandidates = [
+        join(projectDir, 'node_modules', '@series-inc', 'stowkit-three-loader', 'public'),
+    ];
+    for (const loaderPublic of loaderCandidates) {
+        if (!existsSync(loaderPublic))
+            continue;
+        // Guard against recursive copy
+        const srcAbs = resolve(loaderPublic);
+        const destAbs = resolve(dest);
+        if (destAbs.startsWith(srcAbs + '/') || destAbs.startsWith(srcAbs + '\\') || destAbs === srcAbs)
+            continue;
+        for (const subdir of ['basis', 'draco']) {
+            const src = join(loaderPublic, subdir);
+            if (!existsSync(src))
+                continue;
+            const subdirDest = join(dest, subdir);
+            mkdirSync(subdirDest, { recursive: true });
+            for (const file of readdirSync(src)) {
+                if (statSync(join(src, file)).isFile()) {
+                    copyFileSync(join(src, file), join(subdirDest, file));
+                }
+            }
+            result[subdir] = true;
+            if (verbose)
+                console.log(`  Synced ${subdir}/ → public/stowkit/${subdir}/`);
+        }
+        break;
+    }
+    if (result.wasm || result.basis || result.draco) {
+        const parts = [result.wasm && 'WASM', result.basis && 'Basis', result.draco && 'Draco'].filter(Boolean);
+        console.log(`Synced runtime assets (${parts.join(', ')}) → public/stowkit/`);
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@series-inc/stowkit-cli",
-  "version": "0.1.30",
+  "version": "0.6.14",
   "type": "module",
   "bin": {
     "stowkit": "./dist/cli.js"
@@ -17,8 +17,8 @@
     "dev": "tsc --watch"
   },
   "dependencies": {
-    "@series-inc/stowkit-packer-gui": "^0.1.16",
-    "@series-inc/stowkit-editor": "^0.1.2",
+    "@series-inc/stowkit-packer-gui": "^0.1.17",
+    "@series-inc/stowkit-editor": "^0.1.3",
     "draco3d": "^1.5.7",
     "fbx-parser": "^2.1.3",
     "@strangeape/ffmpeg-audio-wasm": "^0.1.0",

package/skill.md

@@ -36,7 +36,9 @@ A StowKit project has a `.felicityproject` JSON file at its root:
 ## CLI Commands
 
 ```bash
-stowkit init [dir]              # Scaffold a new project (creates .felicityproject, assets/, public/cdn-assets/)
+stowkit init [dir]              # Scaffold a new project (interactive menu: pipeline only or with 3D engine)
+stowkit init --with-engine      # Scaffold with 3D engine pre-installed (@series-inc/rundot-3d-engine + three)
+stowkit init --no-engine        # Scaffold without 3D engine (skip interactive prompt)
 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
@@ -558,6 +560,17 @@ The CLI always re-extracts GLB containers on every build, so changes to `preserv
 - **true:** The original scene graph node hierarchy is preserved with local transforms (position, rotation, scale) per node. Use this for complex multi-part models where you need individual nodes at runtime (e.g. a vehicle with doors, a character with attachable accessories).
 - Skinned meshes are always excluded from hierarchy preservation regardless of this setting.
 
+### Inspecting built packs
+
+Use `stowkit inspect` to examine the contents of a built `.stow` pack file:
+
+```bash
+stowkit inspect public/cdn-assets/default.stow       # Show manifest (asset names, types, sizes)
+stowkit inspect public/cdn-assets/default.stow -v     # Verbose — includes metadata details per asset
+```
+
+This is useful for verifying build output, checking which assets ended up in which pack, and debugging asset loading issues at runtime.
+
 ### Other common tasks
 
 - **Add a texture:** Place PNG/JPG into `assets/`, run `stowkit build`. The CLI auto-generates the `.stowmeta`. Do NOT create it yourself.
@@ -571,6 +584,9 @@ The CLI always re-extracts GLB containers on every build, so changes to `preserv
 - **Move an asset:** `stowkit move textures/hero.png characters` (moves to `characters/hero.png`, updates GLB child refs if container)
 - **Delete an asset:** `stowkit delete textures/unused.png` (removes source + .stowmeta + .stowcache, cascades for GLB containers)
 - **Change an asset's stringId:** `stowkit set-id textures/hero.png hero_diffuse`
+- **Inspect a built pack:** `stowkit inspect public/cdn-assets/default.stow` (shows manifest; add `-v` for detailed metadata)
 - **Check project health:** Run `stowkit status`
 - **Full rebuild:** `stowkit build --force`
 - **Clean orphaned files:** `stowkit clean`
+- **Set up with engine:** `stowkit init --with-engine` (installs `@series-inc/rundot-3d-engine` + `three`)
+- **Update CLI + skill files:** `stowkit update`