@series-inc/stowkit-cli 0.6.20 → 0.6.22

package/dist/cli.js

@@ -110,6 +110,7 @@ Options:
   --dry-run     Show what would be published without uploading
   --json        Output store results as JSON (for AI agents)
   --type        Filter store search by asset type
+  --limit       Max number of results to return (default: all)
   --help        Show this help message
 `.trim());
 }
@@ -167,6 +168,8 @@ async function main() {
     const bucket = bucketIdx >= 0 ? args[bucketIdx + 1] : undefined;
     const typeIdx = args.indexOf('--type');
     const typeFilter = typeIdx >= 0 ? args[typeIdx + 1] : undefined;
+    const limitIdx = args.indexOf('--limit');
+    const limitFilter = limitIdx >= 0 ? parseInt(args[limitIdx + 1], 10) : undefined;
     const opts = { force, verbose };
     try {
         switch (command) {
@@ -301,17 +304,37 @@ async function main() {
                 break;
             case 'store': {
                 const subCmd = args[1];
-                const storeOpts = { json: jsonOutput, bucket };
+                const serverUrl = `http://localhost:${port}`;
+                const serverUp = await isStowKitRunning(port);
                 if (subCmd === 'search') {
                     const query = args.filter(a => !a.startsWith('-') && a !== 'store' && a !== 'search').join(' ');
                     if (!query) {
-                        console.error('Usage: stowkit store search <query> [--type <type>] [--json]');
+                        console.error('Usage: stowkit store search <query> [--type <type>] [--limit <n>] [--json]');
                         process.exit(1);
                     }
-                    await storeSearch(query, { ...storeOpts, type: typeFilter });
+                    if (serverUp) {
+                        const params = new URLSearchParams({ q: query });
+                        if (typeFilter)
+                            params.set('type', typeFilter);
+                        if (limitFilter)
+                            params.set('limit', String(limitFilter));
+                        const res = await fetch(`${serverUrl}/api/asset-store/search?${params}`);
+                        const results = await res.json();
+                        console.log(JSON.stringify(results, null, 2));
+                    }
+                    else {
+                        await storeSearch(query, { json: jsonOutput, bucket, type: typeFilter, limit: limitFilter });
+                    }
                 }
                 else if (subCmd === 'list') {
-                    await storeList(storeOpts);
+                    if (serverUp) {
+                        const res = await fetch(`${serverUrl}/api/asset-store/packages`);
+                        const packages = await res.json();
+                        console.log(JSON.stringify(packages, null, 2));
+                    }
+                    else {
+                        await storeList({ json: jsonOutput, bucket });
+                    }
                 }
                 else if (subCmd === 'info') {
                     const pkgName = args.find(a => !a.startsWith('-') && a !== 'store' && a !== 'info');
@@ -319,7 +342,14 @@ async function main() {
                         console.error('Usage: stowkit store info <package-name> [--json]');
                         process.exit(1);
                     }
-                    await storeInfo(pkgName, storeOpts);
+                    if (serverUp) {
+                        const res = await fetch(`${serverUrl}/api/asset-store/package/${encodeURIComponent(pkgName)}`);
+                        const info = await res.json();
+                        console.log(JSON.stringify(info, null, 2));
+                    }
+                    else {
+                        await storeInfo(pkgName, { json: jsonOutput, bucket });
+                    }
                 }
                 else {
                     console.error('Usage: stowkit store <search|list|info> [args]');

package/dist/server.js

@@ -1785,9 +1785,13 @@ async function handleRequest(req, res, staticApps) {
             const type = url.searchParams.get('type') ?? undefined;
             const pkg = url.searchParams.get('package') ?? undefined;
             const bucketParam = url.searchParams.get('bucket') ?? undefined;
+            const limitParam = url.searchParams.get('limit');
+            const limit = limitParam ? parseInt(limitParam, 10) : undefined;
             const { fetchRegistry, searchAssets } = await import('./store.js');
             const registry = await fetchRegistry(bucketParam);
-            const results = searchAssets(registry, query, { type, package: pkg });
+            let results = searchAssets(registry, query, { type, package: pkg });
+            if (limit && limit > 0)
+                results = results.slice(0, limit);
             json(res, results);
         }
         catch (err) {
@@ -1809,6 +1813,34 @@ async function handleRequest(req, res, staticApps) {
         }
         return;
     }
+    // GET /api/asset-store/package/:name — get package details
+    if (pathname.startsWith('/api/asset-store/package/') && req.method === 'GET') {
+        try {
+            const packageName = decodeURIComponent(pathname.slice('/api/asset-store/package/'.length));
+            const bucketParam = url.searchParams.get('bucket') ?? undefined;
+            const { fetchRegistry } = await import('./store.js');
+            const registry = await fetchRegistry(bucketParam);
+            const pkg = registry.packages[packageName];
+            if (!pkg) {
+                json(res, { error: `Package "${packageName}" not found` }, 404);
+                return;
+            }
+            const ver = pkg.versions[pkg.latest];
+            json(res, {
+                name: packageName,
+                description: pkg.description,
+                author: pkg.author,
+                tags: pkg.tags ?? [],
+                latest: pkg.latest,
+                versions: Object.keys(pkg.versions),
+                assets: ver?.assets ?? [],
+            });
+        }
+        catch (err) {
+            json(res, { error: err.message }, 500);
+        }
+        return;
+    }
     // POST /api/asset-store/download — download assets (with transitive deps) into project
     if (pathname === '/api/asset-store/download' && req.method === 'POST') {
         if (!projectConfig) {

package/dist/store.d.ts

@@ -12,6 +12,7 @@ export interface SearchResult {
     thumbnail: boolean;
     thumbnailFormat: 'png' | 'webp' | 'webm';
     thumbnailUrl: string | null;
+    audioUrl: string | null;
     filtering?: 'linear' | 'nearest';
 }
 export interface PackageInfo {
@@ -39,6 +40,7 @@ export declare function storeSearch(query: string, opts?: {
     type?: string;
     json?: boolean;
     bucket?: string;
+    limit?: number;
 }): Promise<void>;
 export declare function storeList(opts?: {
     json?: boolean;

package/dist/store.js

@@ -52,6 +52,9 @@ export function searchAssets(registry, query, opts) {
                     thumbnailUrl: asset.thumbnail
                         ? `https://storage.googleapis.com/${bucket}/packages/${pkgName}/${verStr}/thumbnails/${asset.stringId.split('/').map(encodeURIComponent).join('/')}.${asset.thumbnailFormat ?? 'png'}`
                         : null,
+                    audioUrl: asset.type === 'audio'
+                        ? `https://storage.googleapis.com/${bucket}/packages/${pkgName}/${verStr}/${asset.file.split('/').map(encodeURIComponent).join('/')}`
+                        : null,
                     ...(asset.filtering ? { filtering: asset.filtering } : {}),
                 },
             });
@@ -219,7 +222,9 @@ export function resolveAssetDeps(registry, packageName, stringIds, version) {
 // ─── CLI Commands ────────────────────────────────────────────────────────────
 export async function storeSearch(query, opts) {
     const registry = await fetchRegistry(opts?.bucket);
-    const results = searchAssets(registry, query, { type: opts?.type });
+    let results = searchAssets(registry, query, { type: opts?.type });
+    if (opts?.limit && opts.limit > 0)
+        results = results.slice(0, opts.limit);
     if (opts?.json) {
         console.log(JSON.stringify(results, null, 2));
         return;

package/package.json

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

package/skill.md

@@ -2,17 +2,38 @@
 
 StowKit is a game asset pipeline that compresses and packs assets into `.stow` binary files for runtime loading.
 
-## CRITICAL: Never manually create .stowmeta files
+## How "Adding an Asset" Works
 
-`.stowmeta` files are **auto-generated by the CLI**. To add any asset to the project:
+When the user says "add this asset" or "use this model/texture/sound", this is always a two-step process:
 
-1. Place the source file (GLB, PNG, FBX, WAV, etc.) into the `srcArtDir`
-2. Run `stowkit build` (or `stowkit scan`)
-3. The CLI detects the new file, generates the correct `.stowmeta` with proper defaults, and processes it
+**Step 1 — Pipeline (this skill):** Place the source file (FBX, GLB, PNG, WAV, etc.) into the project's `srcArtDir` folder, then run `stowkit build`. The CLI compresses it and packs it into a `.stow` file. That's it for this step.
 
-**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.
+**Step 2 — Runtime (three-loader skill):** In the game code, load the asset from the `.stow` pack using `StowKitLoader` and the asset's `stringId`. For example: `pack.loadMesh('hero_model')`.
 
-To create materials, use `stowkit create-material <path>` — this scaffolds a `.stowmat` file with the right structure. You can also create `.stowmat` files manually if needed.
+**Never load raw source files (FBX, PNG, GLB, WAV) directly in game code.** No `THREE.FBXLoader`, no `THREE.TextureLoader` on raw PNGs, no `fetch('assets/model.fbx')`. All assets go through the StowKit pipeline first and are loaded from `.stow` packs at runtime.
+
+**Never use the asset store to find local project files.** The store is a remote registry for shared reusable packs. To find what assets are in the current project, read `.stowmeta` files, glob for files in `srcArtDir`, or run `stowkit status`.
+
+## Quick Decision Guide
+
+| User wants to... | Do this |
+|---|---|
+| Add a new asset (texture, mesh, audio, GLB) | Place file in `srcArtDir`, run `stowkit build`, then load from pack in game code |
+| Change compression/quality settings | Edit the **existing** `.stowmeta` (never create one), run `stowkit build` |
+| Create a new material | `stowkit create-material <path>` then `stowkit build` |
+| Rename / move / delete an asset | `stowkit rename`, `stowkit move`, or `stowkit delete` |
+| See what's in a built pack | `stowkit inspect <file.stow>` |
+| Check project health | `stowkit status` |
+| Visually browse/edit assets | `stowkit packer` |
+| Load assets at runtime (Three.js) | Use `@series-inc/stowkit-three-loader` — see Runtime Reader section |
+
+## CRITICAL Rules
+
+1. **Never manually create `.stowmeta` files.** They are auto-generated by `stowkit build` / `stowkit scan`. Only **edit** an existing one (to change quality, pack, stringId, etc.).
+2. **Never manually create GLB `children` arrays.** The build populates them automatically on first run.
+3. **Never load raw FBX/PNG/GLB/WAV files directly in game code.** Everything goes through the pipeline (`stowkit build`) and is loaded from `.stow` packs at runtime via `StowKitLoader`.
+4. **To create materials, use `stowkit create-material`** — don't hand-write `.stowmat` unless you have a specific reason.
+5. **Always run `stowkit build` after changes** — the CLI handles scanning, processing, and packing in one step.
 
 ## Project Structure
 
@@ -53,9 +74,6 @@ stowkit move <path> <folder>    # Move an asset to a different folder (updates G
 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 store search <query>    # Search the asset store (add --json for machine-readable output)
-stowkit store list              # List all packages in the store
-stowkit store info <package>    # Show package details and all assets
 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)
@@ -66,8 +84,6 @@ All commands default to the current directory.
 **Options:**
 - `--force` — Ignore cache and reprocess everything
 - `--verbose` / `-v` — Detailed output
-- `--json` — Output store results as JSON (for programmatic/AI use)
-- `--type <type>` — Filter store search by asset type (e.g. `staticMesh`, `texture`)
 - `--port <number>` — Server port (default 3210)
 - `--schema <name>` — Material schema template for `create-material` (default: `pbr`)
 
@@ -530,130 +546,17 @@ 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.
 
-## Asset Store
-
-StowKit includes a shared asset store for publishing, searching, and importing reusable asset packs across projects. Assets are stored in a GCS bucket with a central `registry.json` manifest.
-
-### Publishing to the store
-
-To publish a pack, you need an `assets-package.json` in the project root:
-
-```json
-{
-  "name": "my-pack",
-  "version": "1.0.0",
-  "author": "your-name",
-  "description": "A short description of what's in this pack",
-  "tags": ["environment", "fantasy", "low-poly"],
-  "bucket": "gs://venus-shared-assets-test"
-}
-```
-
-Then run `stowkit publish` from the packer GUI's Publish modal, or programmatically via the CLI server's `/api/publish` endpoint. The publish flow:
-
-1. Scans all assets in the `srcArtDir` and builds a dependency graph
-2. Uploads all source files to `packages/{name}/{version}/` in GCS
-3. Uploads per-asset thumbnails (captured in the packer GUI)
-4. Uploads a pack-level thumbnail if present (see below)
-5. Updates the central `registry.json` with the new version
-
-**Pack-level thumbnail:** Place a `thumbnail.webp`, `thumbnail.png`, or `thumbnail.jpg` in the project root directory. During publish, this file is uploaded alongside the package and displayed as the pack's cover image in the store. If no custom thumbnail is provided, the store shows a collage of individual asset thumbnails.
-
-**Version management:** Bump the `version` field in `assets-package.json` before each publish. Publishing the same version again requires `--force`.
-
-### Searching the store (CLI)
-
-```bash
-stowkit store search coral                    # Find assets matching "coral"
-stowkit store search "boss, idle"             # AND search — both terms must match
-stowkit store search ocean --type texture     # Find textures tagged/named "ocean"
-stowkit store search staticMesh --json        # Machine-readable JSON output
-stowkit store list                            # List all published packages
-stowkit store info ninja-adventure            # Show all assets in a package
-stowkit store info ninja-adventure --json     # Full package details as JSON
-```
-
-The `--json` flag outputs structured data for programmatic/AI consumption.
-
-### Search scoring algorithm
-
-Search uses a ranked scoring system with AND semantics. Each search term must independently clear a minimum threshold — weak matches alone won't surface results.
-
-**Scoring tiers (per term, highest match wins):**
-
-| Score | Match type | Example |
-|-------|-----------|---------|
-| 100 | Exact stringId match | "boss" matches asset "boss" |
-| 90 | Exact package name match | "ninja-adventure" matches the pack |
-| 80 | Exact asset tag match | "coral" matches tag "coral" |
-| 60 | Word match in stringId or tag | "boss" matches "actor/boss/idle" |
-| 50 | stringId starts with term | "act" matches "actor/boss/idle" |
-| 45-50 | Word match in package name/tag | "ninja" matches pack "ninja-adventure" |
-| 40 | Word prefix in stringId | "att" matches "attack" |
-| 25-35 | Substring/prefix matches | Various partial matches |
-| < 20 | File path, type, description | Below threshold — boost only |
-
-**Key behaviors:**
-- **AND semantics:** Multi-term queries (comma-separated) require ALL terms to match. "boss, idle" only returns assets matching both words.
-- **Minimum threshold (20):** Weak signals like file path matches or type name matches can't surface assets on their own. They only boost already-qualifying results.
-- **Tags score high:** Asset tags are curated metadata and rank just below exact name matches. If an asset has a tag that matches your query, it will surface prominently.
-- **Package metadata scoped:** When searching within a specific pack, package-level fields (name, description, tags) are excluded from scoring to prevent every asset from matching.
-
-**Word splitting:** StringIds and names are split on underscores, hyphens, dots, slashes, camelCase, and spaces. "NinjaBoss_Attack" becomes ["ninja", "boss", "attack"].
-
-### Searching in the Packer GUI
-
-The packer GUI has a **Store** button that opens a full-featured asset store browser:
-
-- **Global search:** Type a query without selecting a pack — shows matching **packs** (not individual assets), sorted by number of matches. Click a pack to browse its assets with the search term preserved.
-- **In-pack search:** Select a pack first, then search — shows individual assets within that pack, flat (no folder grouping), with AND scoring.
-- **Type filters:** Filter by asset type (texture, staticMesh, skinnedMesh, audio, materialSchema, animationClip) using toggle pills.
-- **Show All:** Checkbox to flatten the folder hierarchy and see all assets in the current pack at once. Combines with type filters.
-- **Folder browsing:** When not searching, navigate the pack's folder structure. Breadcrumbs below the filter bar show your current path.
-- **Thumbnail size:** Slider in the footer to adjust grid card size.
-- **Selection + dependencies:** Click assets to select them. Transitive dependencies are auto-resolved and shown with amber badges. The Import button downloads all selected assets and their deps into the project's `srcArtDir`.
-
-### JSON search result format
-
-```json
-[
-  {
-    "stringId": "coral_1",
-    "type": "staticMesh",
-    "packageName": "ocean_pack",
-    "version": "1.0.0",
-    "file": "Meshes/Coral_1.fbx",
-    "size": 59952,
-    "tags": ["coral", "environment"],
-    "dependencies": ["M_Sea_Floor"],
-    "thumbnail": true,
-    "thumbnailFormat": "png",
-    "thumbnailUrl": "https://storage.googleapis.com/venus-shared-assets-test/packages/ocean_pack/1.0.0/thumbnails/coral_1.png"
-  }
-]
-```
-
-### Dependency resolution
-
-Assets have dependency chains: meshes depend on materials, materials depend on textures. When importing an asset, all transitive dependencies are automatically resolved and downloaded. If two assets share the same dependency, it's only downloaded once.
-
-### Importing from the store
-
-The packer GUI's Store modal handles importing. Selected assets and their transitive dependencies are downloaded directly into the project's `srcArtDir`. Already-imported assets are marked with a green "Imported" badge.
-
-### Thumbnail URLs
-
-Per-asset thumbnails (captured in the packer GUI during publish):
-```
-https://storage.googleapis.com/{bucket}/packages/{packageName}/{version}/thumbnails/{stringId}.{format}
-```
-
-Pack-level thumbnails (from project root `thumbnail.webp`):
-```
-https://storage.googleapis.com/{bucket}/packages/{packageName}/{version}/thumbnail.webp
-```
+## Common AI Mistakes to Avoid
 
-Check the `thumbnail` boolean in search results to know if an asset has a thumbnail. Pack-level thumbnails are returned as `thumbnailUrl` in the package listing.
+| Mistake | Why it's wrong | What to do instead |
+|---|---|---|
+| Loading raw FBX/PNG/GLB in game code (`THREE.FBXLoader`, `THREE.TextureLoader`, `fetch('assets/...')`) | StowKit projects never load raw source files at runtime — they're compressed and packed | Place file in `srcArtDir`, `stowkit build`, then `pack.loadMesh()`/`pack.loadTexture()` from the `.stow` pack |
+| Searching the asset store to find files in the local project | The store is a remote registry for shared packs, not the local project | Glob for files in `srcArtDir`, read `.stowmeta` files, or run `stowkit status` |
+| Creating a `.stowmeta` file from scratch | The CLI generates these with correct defaults and cache stamps | Place the source file in `srcArtDir`, run `stowkit build` |
+| Writing a `.stowmat` by hand when `create-material` exists | Hand-written materials often have wrong structure | `stowkit create-material <path>` |
+| Running `stowkit process` without `stowkit scan` first | New files won't have `.stowmeta` yet | Just use `stowkit build` — it does scan + process + pack |
+| Editing a GLB's `children` array before first build | The array doesn't exist yet — it's populated by the build | Run `stowkit build` first, then edit the generated children |
+| Deleting files manually instead of using `stowkit delete` | Orphans the `.stowmeta` and `.stowcache` sidecars | `stowkit delete <path>` handles everything |
 
 ## Common Tasks for AI Agents
 
@@ -720,12 +623,3 @@ This is useful for verifying build output, checking which assets ended up in whi
 - **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`
-- **Search the asset store:** `stowkit store search sword --json` (returns JSON array of matching assets with thumbnailUrls)
-- **AND search:** `stowkit store search "boss, idle" --json` (both terms must match)
-- **Find all meshes in the store:** `stowkit store search mesh --type staticMesh --json`
-- **List all published packages:** `stowkit store list --json`
-- **Get package details:** `stowkit store info ocean_pack --json`
-- **Show a thumbnail to the user:** Use the `thumbnailUrl` from search results — it's a public URL
-- **Add a pack thumbnail:** Place `thumbnail.webp` (or `.png`/`.jpg`) in the project root before publishing
-- **Publish a pack:** Open the packer GUI (`stowkit packer`), click Publish, fill in version/description/tags, and publish
-- **Browse the store visually:** Open the packer GUI, click the Store button to browse, search, filter by type, and import assets