@series-inc/stowkit-cli 0.6.20 → 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.20",
+  "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.19",
+    "@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`)
 
@@ -561,19 +562,34 @@ Then run `stowkit publish` from the packer GUI's Publish modal, or programmatica
 
 **Version management:** Bump the `version` field in `assets-package.json` before each publish. Publishing the same version again requires `--force`.
 
-### Searching the store (CLI)
+### 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 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.
+When the server IS running, CLI store commands automatically proxy through it and always output JSON.
 
 ### Search scoring algorithm
 
@@ -720,11 +736,11 @@ 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`
+- **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