@series-inc/stowkit-cli 0.1.15 → 0.1.16

package/dist/asset-commands.d.ts

@@ -0,0 +1,4 @@
+export declare function renameAsset(projectDir: string, assetPath: string, newName: string): Promise<void>;
+export declare function moveAsset(projectDir: string, assetPath: string, targetFolder: string): Promise<void>;
+export declare function deleteAsset(projectDir: string, assetPath: string): Promise<void>;
+export declare function setStringId(projectDir: string, assetPath: string, newStringId: string): Promise<void>;

package/dist/asset-commands.js

@@ -0,0 +1,122 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { readProjectConfig, renameFile, deleteFile, readFile, } from './node-fs.js';
+import { readStowmeta, writeStowmeta, } from './app/stowmeta-io.js';
+// ─── Rename ──────────────────────────────────────────────────────────────────
+export async function renameAsset(projectDir, assetPath, newName) {
+    const config = await readProjectConfig(projectDir);
+    // Build new ID: same folder, new filename (preserve original extension)
+    const folder = assetPath.includes('/') ? assetPath.slice(0, assetPath.lastIndexOf('/') + 1) : '';
+    const oldBase = assetPath.split('/').pop() ?? assetPath;
+    const extMatch = oldBase.match(/\.[^.]+$/);
+    const ext = extMatch ? extMatch[0] : '';
+    const fullNewName = ext && !newName.endsWith(ext) ? newName + ext : newName;
+    const newId = folder + fullNewName;
+    if (newId === assetPath) {
+        console.log('Nothing to rename — same name.');
+        return;
+    }
+    // Verify source exists
+    const sourceData = await readFile(config.srcArtDir, assetPath);
+    if (!sourceData) {
+        console.error(`Asset not found: ${assetPath}`);
+        process.exit(1);
+    }
+    // Rename source, stowmeta, stowcache
+    await renameFile(config.srcArtDir, assetPath, newId);
+    await renameFile(config.srcArtDir, `${assetPath}.stowmeta`, `${newId}.stowmeta`);
+    await renameFile(config.srcArtDir, `${assetPath}.stowcache`, `${newId}.stowcache`);
+    // For GLB containers, rename the .children cache directory
+    const meta = await readStowmeta(config.srcArtDir, newId);
+    if (meta && meta.type === 'glbContainer') {
+        await renameFile(config.srcArtDir, `${assetPath}.children`, `${newId}.children`);
+    }
+    console.log(`Renamed: ${assetPath} → ${newId}`);
+}
+// ─── Move ────────────────────────────────────────────────────────────────────
+export async function moveAsset(projectDir, assetPath, targetFolder) {
+    const config = await readProjectConfig(projectDir);
+    const fileName = assetPath.split('/').pop() ?? assetPath;
+    const newId = targetFolder ? `${targetFolder}/${fileName}` : fileName;
+    if (newId === assetPath) {
+        console.log('Nothing to move — already in target folder.');
+        return;
+    }
+    // Verify source exists
+    const sourceData = await readFile(config.srcArtDir, assetPath);
+    if (!sourceData) {
+        console.error(`Asset not found: ${assetPath}`);
+        process.exit(1);
+    }
+    // Move source, stowmeta, stowcache
+    await renameFile(config.srcArtDir, assetPath, newId);
+    await renameFile(config.srcArtDir, `${assetPath}.stowmeta`, `${newId}.stowmeta`);
+    await renameFile(config.srcArtDir, `${assetPath}.stowcache`, `${newId}.stowcache`);
+    // For GLB containers, move the .children cache directory and update child references
+    const meta = await readStowmeta(config.srcArtDir, newId);
+    if (meta && meta.type === 'glbContainer') {
+        await renameFile(config.srcArtDir, `${assetPath}.children`, `${newId}.children`);
+        // Update texture references in material configs
+        const glbMeta = meta;
+        const oldPrefix = assetPath + '/';
+        const newPrefix = newId + '/';
+        let updated = false;
+        for (const child of glbMeta.children ?? []) {
+            if (child.materialConfig) {
+                for (const prop of child.materialConfig.properties) {
+                    if (prop.textureAsset?.startsWith(oldPrefix)) {
+                        prop.textureAsset = newPrefix + prop.textureAsset.slice(oldPrefix.length);
+                        updated = true;
+                    }
+                }
+            }
+            if (child.materialOverrides) {
+                for (const [k, v] of Object.entries(child.materialOverrides)) {
+                    if (v?.startsWith(oldPrefix)) {
+                        child.materialOverrides[k] = newPrefix + v.slice(oldPrefix.length);
+                        updated = true;
+                    }
+                }
+            }
+        }
+        if (updated) {
+            await writeStowmeta(config.srcArtDir, newId, glbMeta);
+        }
+    }
+    console.log(`Moved: ${assetPath} → ${newId}`);
+}
+// ─── Delete ──────────────────────────────────────────────────────────────────
+export async function deleteAsset(projectDir, assetPath) {
+    const config = await readProjectConfig(projectDir);
+    // Verify source exists
+    const sourceData = await readFile(config.srcArtDir, assetPath);
+    if (!sourceData) {
+        console.error(`Asset not found: ${assetPath}`);
+        process.exit(1);
+    }
+    // For GLB containers, also delete the .children cache directory
+    const meta = await readStowmeta(config.srcArtDir, assetPath);
+    if (meta && meta.type === 'glbContainer') {
+        const childrenDir = path.join(config.srcArtDir, `${assetPath}.children`);
+        await fs.rm(childrenDir, { recursive: true, force: true }).catch(() => { });
+    }
+    // Delete source, stowmeta, stowcache
+    await deleteFile(config.srcArtDir, assetPath);
+    await deleteFile(config.srcArtDir, `${assetPath}.stowmeta`);
+    await deleteFile(config.srcArtDir, `${assetPath}.stowcache`);
+    console.log(`Deleted: ${assetPath}`);
+}
+// ─── Set stringId ────────────────────────────────────────────────────────────
+export async function setStringId(projectDir, assetPath, newStringId) {
+    const config = await readProjectConfig(projectDir);
+    const meta = await readStowmeta(config.srcArtDir, assetPath);
+    if (!meta) {
+        console.error(`No .stowmeta found for: ${assetPath}`);
+        console.error('Run `stowkit build` or `stowkit scan` first to generate it.');
+        process.exit(1);
+    }
+    const oldStringId = meta.stringId;
+    meta.stringId = newStringId;
+    await writeStowmeta(config.srcArtDir, assetPath, meta);
+    console.log(`Updated stringId: "${oldStringId}" → "${newStringId}" (${assetPath})`);
+}

package/dist/cli.js

@@ -6,6 +6,8 @@ import { fullBuild, scanProject, showStatus } from './orchestrator.js';
 import { startServer } from './server.js';
 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';
 const args = process.argv.slice(2);
 const thisDir = path.dirname(fileURLToPath(import.meta.url));
 function printUsage() {
@@ -17,6 +19,11 @@ Usage:
   stowkit process [dir]           Compress assets (respects cache)
   stowkit status [dir]            Show project summary, stale asset count
   stowkit clean [dir]             Delete orphaned .stowcache and .stowmeta files
+  stowkit create-material <path>  Create a .stowmat material file
+  stowkit rename <path> <name>    Rename an asset file
+  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 packer [dir]            Open the packer GUI
   stowkit editor [dir]            Open the level editor
   stowkit serve [dir]             Start API server only (no GUI)
@@ -25,6 +32,7 @@ Options:
   --force       Ignore cache and reprocess everything
   --verbose     Detailed output
   --port        Server port (default 3210)
+  --schema      Material schema template: pbr (default), unlit, or custom name
   --help        Show this help message
 `.trim());
 }
@@ -94,6 +102,54 @@ async function main() {
             case 'clean':
                 await cleanupProject(projectDir, { verbose });
                 break;
+            case 'create-material': {
+                // For create-material, the positional arg is the material path, not project dir
+                const matPath = args.find(a => !a.startsWith('-') && a !== command);
+                if (!matPath) {
+                    console.error('Usage: stowkit create-material <path> [--schema pbr|unlit|<name>]');
+                    process.exit(1);
+                }
+                const schemaIdx = args.indexOf('--schema');
+                const schema = schemaIdx >= 0 ? args[schemaIdx + 1] : undefined;
+                await createMaterial('.', matPath, { schema });
+                break;
+            }
+            case 'rename': {
+                const positional = args.filter(a => !a.startsWith('-') && a !== command);
+                if (positional.length < 2) {
+                    console.error('Usage: stowkit rename <asset-path> <new-name>');
+                    process.exit(1);
+                }
+                await renameAsset('.', positional[0], positional[1]);
+                break;
+            }
+            case 'move': {
+                const positional = args.filter(a => !a.startsWith('-') && a !== command);
+                if (positional.length < 2) {
+                    console.error('Usage: stowkit move <asset-path> <target-folder>');
+                    process.exit(1);
+                }
+                await moveAsset('.', positional[0], positional[1]);
+                break;
+            }
+            case 'delete': {
+                const assetPath = args.find(a => !a.startsWith('-') && a !== command);
+                if (!assetPath) {
+                    console.error('Usage: stowkit delete <asset-path>');
+                    process.exit(1);
+                }
+                await deleteAsset('.', assetPath);
+                break;
+            }
+            case 'set-id': {
+                const positional = args.filter(a => !a.startsWith('-') && a !== command);
+                if (positional.length < 2) {
+                    console.error('Usage: stowkit set-id <asset-path> <new-string-id>');
+                    process.exit(1);
+                }
+                await setStringId('.', positional[0], positional[1]);
+                break;
+            }
             case 'packer': {
                 const packerDir = resolveAppDir('@series-inc/stowkit-packer-gui', 'stowkit-packer-gui');
                 if (!packerDir) {

package/dist/create-material.d.ts

@@ -0,0 +1,3 @@
+export declare function createMaterial(projectDir: string, relativePath: string, opts?: {
+    schema?: string;
+}): Promise<void>;

package/dist/create-material.js

@@ -0,0 +1,47 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { readProjectConfig } from './node-fs.js';
+const TEMPLATES = {
+    pbr: [
+        { fieldName: 'BaseColor', fieldType: 'texture', previewFlag: 'mainTex', value: [1, 1, 1, 1], textureAsset: null },
+        { fieldName: 'Normal', fieldType: 'texture', previewFlag: 'none', value: [0, 0, 1, 0], textureAsset: null },
+        { fieldName: 'Tint', fieldType: 'color', previewFlag: 'tint', value: [1, 1, 1, 1], textureAsset: null },
+        { fieldName: 'AlphaTest', fieldType: 'float', previewFlag: 'alphaTest', value: [0.5, 0, 0, 0], textureAsset: null },
+    ],
+    unlit: [
+        { fieldName: 'BaseColor', fieldType: 'texture', previewFlag: 'mainTex', value: [1, 1, 1, 1], textureAsset: null },
+        { fieldName: 'Tint', fieldType: 'color', previewFlag: 'tint', value: [1, 1, 1, 1], textureAsset: null },
+    ],
+};
+export async function createMaterial(projectDir, relativePath, opts) {
+    const config = await readProjectConfig(projectDir);
+    // Ensure .stowmat extension
+    if (!relativePath.endsWith('.stowmat')) {
+        relativePath += '.stowmat';
+    }
+    const fullPath = path.join(config.srcArtDir, relativePath);
+    // Don't overwrite existing
+    try {
+        await fs.access(fullPath);
+        console.error(`Material already exists: ${relativePath}`);
+        process.exit(1);
+    }
+    catch {
+        // Does not exist — good
+    }
+    const schemaName = opts?.schema ?? 'pbr';
+    const properties = TEMPLATES[schemaName] ?? [];
+    const mat = {
+        version: 1,
+        schemaName,
+        properties,
+    };
+    await fs.mkdir(path.dirname(fullPath), { recursive: true });
+    await fs.writeFile(fullPath, JSON.stringify(mat, null, 2) + '\n');
+    console.log(`Created material: ${relativePath}`);
+    console.log(`  Schema: ${schemaName}`);
+    console.log(`  Properties: ${properties.map(p => p.fieldName).join(', ') || '(none)'}`);
+    if (!TEMPLATES[schemaName]) {
+        console.log(`  (Custom schema — no template properties. Edit the file to add properties.)`);
+    }
+}

package/dist/orchestrator.js

@@ -98,58 +98,8 @@ export async function fullBuild(projectDir, opts) {
         }
         assets.push(asset);
         assetsById.set(id, asset);
-        // Expand GlbContainer children
-        if (type === AssetType.GlbContainer && meta.type === 'glbContainer') {
-            const glbMeta = meta;
-            if (glbMeta.children && glbMeta.children.length > 0) {
-                asset.status = 'ready'; // Container itself is always "ready"
-                for (const child of glbMeta.children) {
-                    const childId = `${id}/${child.name}`;
-                    const baseName = child.name.replace(/\.[^.]+$/, '');
-                    // Read settings from inline child entry
-                    const { type: cType, settings: cSettings } = glbChildToAssetSettings(child);
-                    const childAsset = {
-                        id: childId,
-                        fileName: child.name,
-                        stringId: child.stringId || baseName,
-                        type: cType,
-                        status: 'pending',
-                        settings: cSettings,
-                        sourceSize: 0,
-                        processedSize: 0,
-                        parentId: id,
-                        locked: true,
-                    };
-                    // Check cache
-                    if (!force && child.cache) {
-                        const cached = await readCacheBlobs(config.srcArtDir, childId);
-                        if (cached) {
-                            for (const [key, data] of cached) {
-                                if (key === `${childId}:__metadata__`) {
-                                    try {
-                                        childAsset.metadata = JSON.parse(new TextDecoder().decode(data));
-                                    }
-                                    catch { /* skip */ }
-                                }
-                                else {
-                                    BlobStore.setProcessed(key, data);
-                                }
-                            }
-                            childAsset.status = 'ready';
-                            childAsset.processedSize = BlobStore.getProcessed(childId)?.length ?? 0;
-                            if (verbose)
-                                console.log(`  [cached] ${childId}`);
-                        }
-                    }
-                    assets.push(childAsset);
-                    assetsById.set(childId, childAsset);
-                }
-            }
-            else {
-                // No children manifest yet — need to parse GLB to discover them
-                // This will be handled during processing
-            }
-        }
+        // GlbContainers are always extracted in section 2b (even if children exist in manifest)
+        // so that preserveHierarchy changes, re-exports, etc. are always reflected.
     }
     // Materials from .stowmat files
     for (const matFile of scan.matFiles) {
@@ -178,10 +128,9 @@ export async function fullBuild(projectDir, opts) {
         assets.push(asset);
         assetsById.set(id, asset);
     }
-    // 2b. Process GLB containers that need extraction (no children yet)
-    // Store extract results so mesh/animation children can be processed after encoder init
+    // 2b. Extract all GLB containers (always re-parse so preserveHierarchy etc. are reflected)
     const glbExtracts = new Map();
-    const glbContainers = assets.filter(a => a.type === AssetType.GlbContainer && a.status === 'pending');
+    const glbContainers = assets.filter(a => a.type === AssetType.GlbContainer);
     for (const container of glbContainers) {
         try {
             const sourceData = await readFile(config.srcArtDir, container.id);
@@ -237,8 +186,6 @@ export async function fullBuild(projectDir, opts) {
             // Create child assets from inline entries
             for (const child of childrenManifest) {
                 const childId = `${container.id}/${child.name}`;
-                if (assetsById.has(childId))
-                    continue;
                 const baseName = child.name.replace(/\.[^.]+$/, '');
                 const { type: cType, settings: cSettings } = glbChildToAssetSettings(child);
                 const childAsset = {
@@ -274,6 +221,27 @@ export async function fullBuild(projectDir, opts) {
                         childAsset.processedSize = result.processedSize;
                     }
                 }
+                // Check cache for texture/mesh children (skip if --force)
+                if (childAsset.status === 'pending' && !force && child.cache) {
+                    const cached = await readCacheBlobs(config.srcArtDir, childId);
+                    if (cached) {
+                        for (const [key, data] of cached) {
+                            if (key === `${childId}:__metadata__`) {
+                                try {
+                                    childAsset.metadata = JSON.parse(new TextDecoder().decode(data));
+                                }
+                                catch { /* skip */ }
+                            }
+                            else {
+                                BlobStore.setProcessed(key, data);
+                            }
+                        }
+                        childAsset.status = 'ready';
+                        childAsset.processedSize = BlobStore.getProcessed(childId)?.length ?? 0;
+                        if (verbose)
+                            console.log(`  [cached] ${childId}`);
+                    }
+                }
                 assets.push(childAsset);
                 assetsById.set(childId, childAsset);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@series-inc/stowkit-cli",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "type": "module",
   "bin": {
     "stowkit": "./dist/cli.js"
@@ -17,7 +17,7 @@
     "dev": "tsc --watch"
   },
   "dependencies": {
-    "@series-inc/stowkit-packer-gui": "^0.1.8",
+    "@series-inc/stowkit-packer-gui": "^0.1.9",
     "@series-inc/stowkit-editor": "^0.1.2",
     "draco3d": "^1.5.7",
     "fbx-parser": "^2.1.3",

package/skill.md

@@ -12,7 +12,7 @@ StowKit is a game asset pipeline that compresses and packs assets into `.stow` b
 
 **Do not write `.stowmeta` files by hand.** Only edit an existing `.stowmeta` after it has been generated by the CLI (e.g. to change quality settings, pack assignment, or stringId). The same applies to GLB children — the `children` array is populated automatically on the first build.
 
-The only file you should manually create is `.stowmat` (material schema) files — these are user-authored material definitions, not generated metadata.
+To create materials, use `npx stowkit create-material <path>` — this scaffolds a `.stowmat` file with the right structure. You can also create `.stowmat` files manually if needed.
 
 ## Project Structure
 
@@ -42,6 +42,11 @@ npx stowkit scan [dir]              # Detect new assets and generate .stowmeta d
 npx stowkit process [dir]           # Compress assets (respects cache)
 npx stowkit status [dir]            # Show project summary, stale asset count
 npx stowkit clean [dir]             # Delete orphaned .stowcache and .stowmeta files
+npx stowkit create-material <path>  # Create a .stowmat material file (--schema pbr|unlit|<name>)
+npx stowkit rename <path> <name>    # Rename an asset file (preserves extension, updates sidecars)
+npx stowkit move <path> <folder>    # Move an asset to a different folder (updates GLB child refs)
+npx stowkit delete <path>           # Delete an asset and its .stowmeta/.stowcache files
+npx stowkit set-id <path> <id>      # Change an asset's stringId
 npx stowkit packer [dir]            # Open the packer GUI in browser
 npx stowkit editor [dir]            # Open the level editor in browser
 npx stowkit serve [dir]             # Start API server only (no GUI)
@@ -53,6 +58,7 @@ All commands default to the current directory.
 - `--force` — Ignore cache and reprocess everything
 - `--verbose` / `-v` — Detailed output
 - `--port <number>` — Server port (default 3210)
+- `--schema <name>` — Material schema template for `create-material` (default: `pbr`)
 
 ## Supported Asset Types
 
@@ -359,6 +365,18 @@ Add `*.stowcache` to `.gitignore`.
 5. To exclude a child from packing, set `"excluded": true` on that child entry
 6. To preserve the scene graph hierarchy in static meshes, set `"preserveHierarchy": true` on the container
 
+### Enabling preserveHierarchy from CLI
+
+To enable hierarchy preservation on a GLB, edit its `.stowmeta` and set `"preserveHierarchy": true`, then rebuild:
+
+```bash
+# After the first build has generated the .stowmeta, edit it:
+# Set "preserveHierarchy": true in assets/models/hero.glb.stowmeta
+npx stowkit build
+```
+
+The CLI always re-extracts GLB containers on every build, so changes to `preserveHierarchy` take effect immediately — no `--force` needed.
+
 ### When to use preserveHierarchy
 
 - **Default (false):** All mesh geometry is baked to world space and flattened into a single mesh. Use this for simple props and environment pieces.
@@ -370,9 +388,14 @@ Add `*.stowcache` to `.gitignore`.
 - **Add a texture:** Place PNG/JPG into `assets/`, run `npx stowkit build`. The CLI auto-generates the `.stowmeta`. Do NOT create it yourself.
 - **Add audio:** Place WAV/MP3/OGG into `assets/`, run `npx stowkit build`. Same rule — never manually create `.stowmeta`.
 - **Add an FBX mesh:** Place FBX into `assets/`, run `npx stowkit build`.
+- **Enable preserve hierarchy on a GLB:** Edit the `.stowmeta` for the GLB container, set `"preserveHierarchy": true`, then `npx stowkit build`
 - **Change compression quality:** Edit the **existing** `.stowmeta` file's quality/resize fields (after it was generated by a build/scan), then `npx stowkit build`
-- **Create a material:** Create a `.stowmat` JSON file in `assets/` (this is the one file type you DO create manually), then run `npx stowkit build`
+- **Create a material:** Run `npx stowkit create-material materials/MyMat` (creates `assets/materials/MyMat.stowmat` with PBR template). Use `--schema unlit` for unlit materials, or `--schema <name>` for a custom schema. Then run `npx stowkit build`.
 - **Assign material to mesh:** Edit the mesh's **existing** `.stowmeta` to add `materialOverrides`
+- **Rename an asset:** `npx stowkit rename textures/old_name.png new_name` (extension preserved automatically, sidecars renamed too)
+- **Move an asset:** `npx stowkit move textures/hero.png characters` (moves to `characters/hero.png`, updates GLB child refs if container)
+- **Delete an asset:** `npx stowkit delete textures/unused.png` (removes source + .stowmeta + .stowcache, cascades for GLB containers)
+- **Change an asset's stringId:** `npx stowkit set-id textures/hero.png hero_diffuse`
 - **Check project health:** Run `npx stowkit status`
 - **Full rebuild:** `npx stowkit build --force`
 - **Clean orphaned files:** `npx stowkit clean`