@series-inc/stowkit-cli 0.1.0 → 0.1.2

package/dist/cli.js

@@ -11,34 +11,42 @@ const args = process.argv.slice(2);
 const thisDir = path.dirname(fileURLToPath(import.meta.url));
 const req = createRequire(import.meta.url);
 function printUsage() {
-    console.log(`
-Usage:
-  stowkit init [dir]              Initialize a StowKit project
-  stowkit build [dir]             Full build: scan + process + pack
-  stowkit scan [dir]              Detect new assets, generate .stowmeta defaults
-  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 packer [dir]            Open the packer GUI
-  stowkit editor [dir]            Open the level editor
-  stowkit serve [dir]             Start API server only (no GUI)
-
-Options:
-  --force       Ignore cache and reprocess everything
-  --verbose     Detailed output
-  --port        Server port (default 3210)
-  --help        Show this help message
+    console.log(`
+Usage:
+  stowkit init [dir]              Initialize a StowKit project
+  stowkit build [dir]             Full build: scan + process + pack
+  stowkit scan [dir]              Detect new assets, generate .stowmeta defaults
+  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 packer [dir]            Open the packer GUI
+  stowkit editor [dir]            Open the level editor
+  stowkit serve [dir]             Start API server only (no GUI)
+
+Options:
+  --force       Ignore cache and reprocess everything
+  --verbose     Detailed output
+  --port        Server port (default 3210)
+  --help        Show this help message
 `.trim());
 }
 function resolveAppDir(packageName, monorepoFolder) {
     const candidates = [
         path.resolve(thisDir, `../../${monorepoFolder}/dist`), // monorepo dev
     ];
+    // Try resolving from CLI package location
     try {
         const pkgJson = req.resolve(`${packageName}/package.json`);
         candidates.push(path.join(path.dirname(pkgJson), 'dist'));
     }
-    catch { /* not installed */ }
+    catch { /* not installed next to CLI */ }
+    // Try resolving from user's project (npx runs CLI from global cache)
+    try {
+        const projectReq = createRequire(path.join(process.cwd(), 'package.json'));
+        const pkgJson = projectReq.resolve(`${packageName}/package.json`);
+        candidates.push(path.join(path.dirname(pkgJson), 'dist'));
+    }
+    catch { /* not installed in project */ }
     for (const dir of candidates) {
         if (existsSync(path.join(dir, 'index.html')))
             return dir;

package/package.json

@@ -1,35 +1,35 @@
-{
-  "name": "@series-inc/stowkit-cli",
-  "version": "0.1.0",
-  "type": "module",
-  "bin": {
-    "stowkit": "./dist/cli.js"
-  },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist",
-    "skill.md"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch"
-  },
-  "dependencies": {
-    "draco3d": "^1.5.7",
-    "fbx-parser": "^2.1.3",
-    "ffmpeg-static": "^5.2.0",
-    "sharp": "^0.33.5",
-    "three": "^0.182.0",
-    "ws": "^8.18.0"
-  },
-  "devDependencies": {
-    "@types/node": "^24.10.1",
-    "@types/three": "^0.182.0",
-    "@types/ws": "^8.5.13",
-    "typescript": "~5.9.3"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@series-inc/stowkit-cli",
+  "version": "0.1.2",
+  "type": "module",
+  "bin": {
+    "stowkit": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "skill.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "draco3d": "^1.5.7",
+    "fbx-parser": "^2.1.3",
+    "ffmpeg-static": "^5.2.0",
+    "sharp": "^0.33.5",
+    "three": "^0.182.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@types/three": "^0.182.0",
+    "@types/ws": "^8.5.13",
+    "typescript": "~5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skill.md

@@ -1,211 +1,211 @@
-# StowKit Asset Pipeline
-
-StowKit is a game asset pipeline that compresses and packs assets into `.stow` binary files for runtime loading.
-
-## Project Structure
-
-A StowKit project has a `.felicityproject` JSON file at its root:
-
-```json
-{
-  "srcArtDir": "assets",
-  "name": "My Game",
-  "cdnAssetsPath": "public/cdn-assets",
-  "packs": [{ "name": "default" }]
-}
-```
-
-- `srcArtDir` — directory containing source art files (PNG, JPG, FBX, WAV, etc.)
-- `cdnAssetsPath` — output directory for built `.stow` packs
-- `packs` — named packs to split assets into
-
-## CLI Commands
-
-```bash
-npx stowkit init              # Scaffold a new project (creates .felicityproject, assets/, public/cdn-assets/)
-npx stowkit build             # Full build: scan + compress + pack (reads from cwd)
-npx stowkit scan              # Detect new assets and generate .stowmeta defaults
-npx stowkit status            # Show project info and how many assets need processing
-npx stowkit packer            # Open the visual packer GUI in browser
-npx stowkit build --force     # Reprocess everything, ignore cache
-```
-
-All commands default to the current directory. Pass a path as second argument to target a different directory.
-
-## Supported Asset Types
-
-| Type | Extensions | Compression |
-|------|-----------|-------------|
-| Texture2D | png, jpg, jpeg, bmp, tga, webp, gif | KTX2 (Basis Universal) |
-| Audio | wav, mp3, ogg, flac, aac, m4a | AAC (M4A container) |
-| StaticMesh | fbx, obj, gltf, glb | Draco |
-| SkinnedMesh | fbx | Uncompressed interleaved vertex data |
-| AnimationClip | fbx | v2 format (Three.js-native tracks) |
-| MaterialSchema | .stowmat | Metadata only (no data blob) |
-
-## .stowmeta Files
-
-Every source asset gets a `.stowmeta` sidecar file (JSON) that controls processing settings:
-
-**Texture example:**
-```json
-{
-  "version": 1,
-  "type": "texture",
-  "stringId": "hero_diffuse",
-  "tags": [],
-  "pack": "default",
-  "quality": "normal",
-  "resize": "full",
-  "generateMipmaps": false
-}
-```
-
-**Quality values:** fastest, fast, normal, high, best
-**Resize values:** full, half, quarter, eighth
-
-**Audio example:**
-```json
-{
-  "version": 1,
-  "type": "audio",
-  "stringId": "bgm_main",
-  "tags": [],
-  "pack": "default",
-  "aacQuality": "medium",
-  "sampleRate": "auto"
-}
-```
-
-**AAC quality:** lowest, low, medium, high, best
-**Sample rate:** auto, 48000, 44100, 22050, 11025
-
-**Static mesh example:**
-```json
-{
-  "version": 1,
-  "type": "staticMesh",
-  "stringId": "level_geometry",
-  "tags": [],
-  "pack": "default",
-  "dracoQuality": "balanced",
-  "materialOverrides": {}
-}
-```
-
-**Draco quality:** fast, balanced, high, maximum
-
-**Skinned mesh example:**
-```json
-{
-  "version": 1,
-  "type": "skinnedMesh",
-  "stringId": "hero_model",
-  "tags": [],
-  "pack": "default",
-  "materialOverrides": {}
-}
-```
-
-**Animation clip example:**
-```json
-{
-  "version": 1,
-  "type": "animationClip",
-  "stringId": "hero_idle",
-  "tags": [],
-  "pack": "default",
-  "targetMeshId": null
-}
-```
-
-## .stowmat Files (Material Schemas)
-
-Materials are defined as `.stowmat` JSON files placed in the source art directory:
-
-```json
-{
-  "version": 1,
-  "schemaName": "StandardPBR",
-  "properties": [
-    {
-      "fieldName": "Diffuse",
-      "fieldType": "texture",
-      "previewFlag": "mainTex",
-      "value": [1, 1, 1, 1],
-      "textureAsset": "textures/hero_diffuse.png"
-    },
-    {
-      "fieldName": "Tint",
-      "fieldType": "color",
-      "previewFlag": "tint",
-      "value": [1, 0.8, 0.6, 1],
-      "textureAsset": null
-    }
-  ]
-}
-```
-
-**Field types:** texture, color, float, vec2, vec3, vec4, int
-**Preview flags:** none, mainTex, tint, alphaTest
-**textureAsset:** relative path to a texture in the project (e.g. "textures/hero.png")
-
-## Material Overrides on Meshes
-
-To assign materials to mesh sub-meshes, set `materialOverrides` in the mesh's `.stowmeta`:
-
-```json
-{
-  "materialOverrides": {
-    "0": "materials/HeroSkin.stowmat",
-    "1": "materials/HeroArmor.stowmat"
-  }
-}
-```
-
-Keys are sub-mesh indices (as strings), values are relative paths to `.stowmat` files.
-
-## Setting Up a New Project
-
-1. Run `npx stowkit init` in the project root
-2. Place source art files in `assets/` (or whatever `srcArtDir` is set to)
-3. Run `npx stowkit build` to process and pack everything
-4. Output `.stow` files appear in `public/cdn-assets/`
-
-## Modifying Asset Settings
-
-Edit the `.stowmeta` file for any asset, then run `npx stowkit build`.
-The build respects cache — only assets whose settings or source files changed get reprocessed.
-Use `--force` to reprocess everything.
-
-## Multi-Pack Setup
-
-Split assets into multiple packs by editing `.felicityproject`:
-
-```json
-{
-  "packs": [
-    { "name": "core" },
-    { "name": "level1" },
-    { "name": "level2" }
-  ]
-}
-```
-
-Then set `"pack": "level1"` in each asset's `.stowmeta` to assign it to a pack.
-
-## Cache
-
-Processed assets are cached in `.stowcache` sidecar files next to the source.
-The `.stowmeta` file stores a cache stamp (source size, modified time, settings hash).
-Cache is automatically invalidated when source files or settings change.
-Add `*.stowcache` to `.gitignore`.
-
-## Common Tasks for AI Agents
-
-- **Add a texture:** Drop a PNG/JPG into `assets/`, run `npx stowkit scan` to generate its `.stowmeta`, optionally edit settings, then `npx stowkit build`
-- **Change compression quality:** Edit the `.stowmeta` file's quality/resize fields, then `npx stowkit build`
-- **Create a material:** Create a `.stowmat` JSON file in `assets/`, run `npx stowkit scan`
-- **Assign material to mesh:** Edit the mesh's `.stowmeta` to add `materialOverrides`
-- **Check project health:** Run `npx stowkit status`
-- **Full rebuild:** `npx stowkit build --force`
+# StowKit Asset Pipeline
+
+StowKit is a game asset pipeline that compresses and packs assets into `.stow` binary files for runtime loading.
+
+## Project Structure
+
+A StowKit project has a `.felicityproject` JSON file at its root:
+
+```json
+{
+  "srcArtDir": "assets",
+  "name": "My Game",
+  "cdnAssetsPath": "public/cdn-assets",
+  "packs": [{ "name": "default" }]
+}
+```
+
+- `srcArtDir` — directory containing source art files (PNG, JPG, FBX, WAV, etc.)
+- `cdnAssetsPath` — output directory for built `.stow` packs
+- `packs` — named packs to split assets into
+
+## CLI Commands
+
+```bash
+npx stowkit init              # Scaffold a new project (creates .felicityproject, assets/, public/cdn-assets/)
+npx stowkit build             # Full build: scan + compress + pack (reads from cwd)
+npx stowkit scan              # Detect new assets and generate .stowmeta defaults
+npx stowkit status            # Show project info and how many assets need processing
+npx stowkit packer            # Open the visual packer GUI in browser
+npx stowkit build --force     # Reprocess everything, ignore cache
+```
+
+All commands default to the current directory. Pass a path as second argument to target a different directory.
+
+## Supported Asset Types
+
+| Type | Extensions | Compression |
+|------|-----------|-------------|
+| Texture2D | png, jpg, jpeg, bmp, tga, webp, gif | KTX2 (Basis Universal) |
+| Audio | wav, mp3, ogg, flac, aac, m4a | AAC (M4A container) |
+| StaticMesh | fbx, obj, gltf, glb | Draco |
+| SkinnedMesh | fbx | Uncompressed interleaved vertex data |
+| AnimationClip | fbx | v2 format (Three.js-native tracks) |
+| MaterialSchema | .stowmat | Metadata only (no data blob) |
+
+## .stowmeta Files
+
+Every source asset gets a `.stowmeta` sidecar file (JSON) that controls processing settings:
+
+**Texture example:**
+```json
+{
+  "version": 1,
+  "type": "texture",
+  "stringId": "hero_diffuse",
+  "tags": [],
+  "pack": "default",
+  "quality": "normal",
+  "resize": "full",
+  "generateMipmaps": false
+}
+```
+
+**Quality values:** fastest, fast, normal, high, best
+**Resize values:** full, half, quarter, eighth
+
+**Audio example:**
+```json
+{
+  "version": 1,
+  "type": "audio",
+  "stringId": "bgm_main",
+  "tags": [],
+  "pack": "default",
+  "aacQuality": "medium",
+  "sampleRate": "auto"
+}
+```
+
+**AAC quality:** lowest, low, medium, high, best
+**Sample rate:** auto, 48000, 44100, 22050, 11025
+
+**Static mesh example:**
+```json
+{
+  "version": 1,
+  "type": "staticMesh",
+  "stringId": "level_geometry",
+  "tags": [],
+  "pack": "default",
+  "dracoQuality": "balanced",
+  "materialOverrides": {}
+}
+```
+
+**Draco quality:** fast, balanced, high, maximum
+
+**Skinned mesh example:**
+```json
+{
+  "version": 1,
+  "type": "skinnedMesh",
+  "stringId": "hero_model",
+  "tags": [],
+  "pack": "default",
+  "materialOverrides": {}
+}
+```
+
+**Animation clip example:**
+```json
+{
+  "version": 1,
+  "type": "animationClip",
+  "stringId": "hero_idle",
+  "tags": [],
+  "pack": "default",
+  "targetMeshId": null
+}
+```
+
+## .stowmat Files (Material Schemas)
+
+Materials are defined as `.stowmat` JSON files placed in the source art directory:
+
+```json
+{
+  "version": 1,
+  "schemaName": "StandardPBR",
+  "properties": [
+    {
+      "fieldName": "Diffuse",
+      "fieldType": "texture",
+      "previewFlag": "mainTex",
+      "value": [1, 1, 1, 1],
+      "textureAsset": "textures/hero_diffuse.png"
+    },
+    {
+      "fieldName": "Tint",
+      "fieldType": "color",
+      "previewFlag": "tint",
+      "value": [1, 0.8, 0.6, 1],
+      "textureAsset": null
+    }
+  ]
+}
+```
+
+**Field types:** texture, color, float, vec2, vec3, vec4, int
+**Preview flags:** none, mainTex, tint, alphaTest
+**textureAsset:** relative path to a texture in the project (e.g. "textures/hero.png")
+
+## Material Overrides on Meshes
+
+To assign materials to mesh sub-meshes, set `materialOverrides` in the mesh's `.stowmeta`:
+
+```json
+{
+  "materialOverrides": {
+    "0": "materials/HeroSkin.stowmat",
+    "1": "materials/HeroArmor.stowmat"
+  }
+}
+```
+
+Keys are sub-mesh indices (as strings), values are relative paths to `.stowmat` files.
+
+## Setting Up a New Project
+
+1. Run `npx stowkit init` in the project root
+2. Place source art files in `assets/` (or whatever `srcArtDir` is set to)
+3. Run `npx stowkit build` to process and pack everything
+4. Output `.stow` files appear in `public/cdn-assets/`
+
+## Modifying Asset Settings
+
+Edit the `.stowmeta` file for any asset, then run `npx stowkit build`.
+The build respects cache — only assets whose settings or source files changed get reprocessed.
+Use `--force` to reprocess everything.
+
+## Multi-Pack Setup
+
+Split assets into multiple packs by editing `.felicityproject`:
+
+```json
+{
+  "packs": [
+    { "name": "core" },
+    { "name": "level1" },
+    { "name": "level2" }
+  ]
+}
+```
+
+Then set `"pack": "level1"` in each asset's `.stowmeta` to assign it to a pack.
+
+## Cache
+
+Processed assets are cached in `.stowcache` sidecar files next to the source.
+The `.stowmeta` file stores a cache stamp (source size, modified time, settings hash).
+Cache is automatically invalidated when source files or settings change.
+Add `*.stowcache` to `.gitignore`.
+
+## Common Tasks for AI Agents
+
+- **Add a texture:** Drop a PNG/JPG into `assets/`, run `npx stowkit scan` to generate its `.stowmeta`, optionally edit settings, then `npx stowkit build`
+- **Change compression quality:** Edit the `.stowmeta` file's quality/resize fields, then `npx stowkit build`
+- **Create a material:** Create a `.stowmat` JSON file in `assets/`, run `npx stowkit scan`
+- **Assign material to mesh:** Edit the mesh's `.stowmeta` to add `materialOverrides`
+- **Check project health:** Run `npx stowkit status`
+- **Full rebuild:** `npx stowkit build --force`