@series-inc/stowkit-cli 0.6.19 → 0.6.21

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

@@ -39,6 +39,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

@@ -219,7 +219,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.19",
+  "version": "0.6.21",
   "type": "module",
   "bin": {
     "stowkit": "./dist/cli.js"
@@ -17,7 +17,7 @@
     "dev": "tsc --watch"
   },
   "dependencies": {
-    "@series-inc/stowkit-packer-gui": "^0.1.18",
+    "@series-inc/stowkit-packer-gui": "^0.1.21",
     "@series-inc/stowkit-editor": "^0.1.8",
     "draco3d": "^1.5.7",
     "fbx-parser": "^2.1.3",

package/skill.md

@@ -68,6 +68,7 @@ All commands default to the current directory.
 - `--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`)
+- `--limit <n>` — Max number of store search results to return
 - `--port <number>` — Server port (default 3210)
 - `--schema <name>` — Material schema template for `create-material` (default: `pbr`)
 
@@ -532,20 +533,101 @@ To refresh skill files without updating the CLI: `stowkit init --update`
 
 ## Asset Store
 
-StowKit includes a shared asset store for publishing, searching, and importing reusable asset packs across projects. Assets are stored in a public GCS bucket with a central `registry.json` manifest.
+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.
 
-### Searching the store
+### 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 (REST API — preferred for AI)
+
+When the StowKit server is running, use the REST endpoints directly for clean JSON — no CLI parsing needed:
+
+```
+GET /api/asset-store/search?q=coral&limit=10           # Search assets, returns JSON array
+GET /api/asset-store/search?q=ocean&type=texture        # Filter by type
+GET /api/asset-store/search?q=boss,idle&limit=5         # AND search (comma-separated)
+GET /api/asset-store/packages                            # List all packages
+GET /api/asset-store/package/<name>                      # Package details + all assets
+```
+
+All responses are JSON. Search results include `thumbnailUrl` for assets that have thumbnails.
+
+### Searching the store (CLI fallback)
+
+If the server isn't running, the CLI falls back to direct registry fetch:
 
 ```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 search sword --json --limit 10  # Top 10 results as JSON
 stowkit store list                            # List all published packages
-stowkit store info package_test               # Show all assets in a package
-stowkit store info package_test --json        # Full package details as JSON
+stowkit store info ninja-adventure --json     # Full package details as JSON
 ```
 
-The `--json` flag outputs structured data with `stringId`, `type`, `packageName`, `version`, `file`, `size`, `tags`, `dependencies`, `thumbnail`, and `thumbnailUrl` for each asset. This is the recommended format for AI agents to consume.
+When the server IS running, CLI store commands automatically proxy through it and always output JSON.
+
+### 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
 
@@ -561,6 +643,7 @@ The `--json` flag outputs structured data with `stringId`, `type`, `packageName`
     "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"
   }
 ]
@@ -572,16 +655,21 @@ Assets have dependency chains: meshes depend on materials, materials depend on t
 
 ### Importing from the store
 
-The packer GUI has a **Store** button to browse, search, and import assets. Selected assets and their transitive dependencies are downloaded directly into the project's `srcArtDir`.
+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
 
-Published assets may have thumbnails at:
+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}/thumbnails/{stringId}.png
+https://storage.googleapis.com/{bucket}/packages/{packageName}/{version}/thumbnail.webp
 ```
 
-Check the `thumbnail` boolean in search results to know if a thumbnail exists.
+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.
 
 ## Common Tasks for AI Agents
 
@@ -648,8 +736,12 @@ 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)
-- **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 PNG URL
+- **Search the asset store (REST):** `curl http://localhost:3210/api/asset-store/search?q=sword&limit=10` (returns JSON array with thumbnailUrls)
+- **AND search (REST):** `curl "http://localhost:3210/api/asset-store/search?q=boss,idle&limit=10"` (both terms must match)
+- **Find all meshes (REST):** `curl "http://localhost:3210/api/asset-store/search?q=mesh&type=staticMesh&limit=10"`
+- **List all packages (REST):** `curl http://localhost:3210/api/asset-store/packages`
+- **Get package details (REST):** `curl http://localhost:3210/api/asset-store/package/ocean_pack`
+- **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