@series-inc/stowkit-cli 0.6.16 → 0.6.18

package/dist/store.d.ts

@@ -0,0 +1,48 @@
+import type { Registry } from './assets-package.js';
+export declare function fetchRegistry(bucket?: string): Promise<Registry>;
+export interface SearchResult {
+    stringId: string;
+    type: string;
+    packageName: string;
+    version: string;
+    file: string;
+    size: number;
+    tags: string[];
+    dependencies: string[];
+    thumbnail: boolean;
+    thumbnailFormat: 'png' | 'webp' | 'webm';
+    thumbnailUrl: string | null;
+    filtering?: 'linear' | 'nearest';
+}
+export interface PackageInfo {
+    name: string;
+    description: string;
+    author: string;
+    tags: string[];
+    latest: string;
+    versions: string[];
+    assetCount: number;
+    totalSize: number;
+}
+export declare function searchAssets(registry: Registry, query: string, opts?: {
+    type?: string;
+    package?: string;
+}): SearchResult[];
+export declare function listPackages(registry: Registry): PackageInfo[];
+export declare function resolveAssetDeps(registry: Registry, packageName: string, stringIds: string[], version?: string): {
+    resolvedIds: string[];
+    files: string[];
+};
+export declare function storeSearch(query: string, opts?: {
+    type?: string;
+    json?: boolean;
+    bucket?: string;
+}): Promise<void>;
+export declare function storeList(opts?: {
+    json?: boolean;
+    bucket?: string;
+}): Promise<void>;
+export declare function storeInfo(packageName: string, opts?: {
+    json?: boolean;
+    bucket?: string;
+}): Promise<void>;

package/dist/store.js

@@ -0,0 +1,300 @@
+import { resolveTransitiveDeps, resolveFiles } from './assets-package.js';
+const DEFAULT_BUCKET = 'venus-shared-assets-test';
+// ─── Fetch Registry ──────────────────────────────────────────────────────────
+export async function fetchRegistry(bucket) {
+    const bucketName = (bucket ?? DEFAULT_BUCKET).replace(/^gs:\/\//, '').replace(/\/$/, '');
+    const url = `https://storage.googleapis.com/${bucketName}/registry.json?t=${Date.now()}`;
+    const res = await fetch(url);
+    if (!res.ok) {
+        if (res.status === 404)
+            return { schemaVersion: 1, packages: {} };
+        throw new Error(`Failed to fetch registry: ${res.status}`);
+    }
+    return res.json();
+}
+// ─── Search ──────────────────────────────────────────────────────────────────
+export function searchAssets(registry, query, opts) {
+    // Support comma-separated terms: "coral, sea, ocean" matches any term
+    const terms = query.split(',').map(t => t.toLowerCase().trim()).filter(Boolean);
+    const scored = [];
+    const bucket = DEFAULT_BUCKET;
+    // When searching within a specific package, skip package-level metadata
+    // (name, description, tags) — it matches every asset and adds noise.
+    const skipPkgMeta = !!opts?.package;
+    for (const [pkgName, pkg] of Object.entries(registry.packages)) {
+        if (opts?.package && pkgName !== opts.package)
+            continue;
+        const verStr = pkg.latest;
+        const ver = pkg.versions[verStr];
+        if (!ver)
+            continue;
+        for (const asset of ver.assets) {
+            if (opts?.type && asset.type !== opts.type)
+                continue;
+            const score = terms.length === 0
+                ? 1
+                : scoreAsset(terms, asset, pkg, pkgName, skipPkgMeta);
+            if (score === 0)
+                continue;
+            scored.push({
+                score,
+                result: {
+                    stringId: asset.stringId,
+                    type: asset.type,
+                    packageName: pkgName,
+                    version: verStr,
+                    file: asset.file,
+                    size: asset.size,
+                    tags: asset.tags,
+                    dependencies: asset.dependencies,
+                    thumbnail: !!asset.thumbnail,
+                    thumbnailFormat: asset.thumbnailFormat ?? 'png',
+                    thumbnailUrl: asset.thumbnail
+                        ? `https://storage.googleapis.com/${bucket}/packages/${pkgName}/${verStr}/thumbnails/${asset.stringId.split('/').map(encodeURIComponent).join('/')}.${asset.thumbnailFormat ?? 'png'}`
+                        : null,
+                    ...(asset.filtering ? { filtering: asset.filtering } : {}),
+                },
+            });
+        }
+    }
+    // Sort by score descending, then alphabetically by stringId
+    scored.sort((a, b) => b.score - a.score || a.result.stringId.localeCompare(b.result.stringId));
+    return scored.map(s => s.result);
+}
+/**
+ * Split a string into lowercase words on common boundaries:
+ * underscores, hyphens, dots, slashes, camelCase, spaces.
+ * e.g. "NinjaBoss_Attack" → ["ninja", "boss", "attack"]
+ */
+function splitWords(s) {
+    return s
+        // insert boundary before uppercase runs: "NinjaBoss" → "Ninja Boss"
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+        .split(/[_\-./\\\s]+/)
+        .map(w => w.toLowerCase())
+        .filter(Boolean);
+}
+/**
+ * Minimum per-term score for a term to count as matched.
+ * Prevents weak incidental hits (file-path substring, type contains)
+ * from surfacing assets on their own — they can only boost an
+ * already-qualifying match.
+ */
+const TERM_THRESHOLD = 20;
+/**
+ * Score an asset against search terms. Returns 0 if the asset should
+ * not appear in results.
+ *
+ * Design principles:
+ * - Curated metadata (tags) scores highest after exact name matches,
+ *   because someone intentionally labelled the asset.
+ * - AND semantics: every term must clear TERM_THRESHOLD independently.
+ *   "coral reef" only matches assets that match BOTH "coral" AND "reef".
+ * - Weak signals (file-path word, type name) act as tiebreaker boosts
+ *   but can't qualify an asset on their own.
+ *
+ * Per-term scoring (best match wins):
+ *   100 — exact stringId match
+ *    80 — exact tag match (curated, high-intent)
+ *    60 — exact word in stringId  ("boss" in "actor/boss/idle")
+ *    50 — stringId starts with term
+ *    45 — word in tag starts with term  ("bos" → "boss" tag)
+ *    40 — word in stringId starts with term ("att" → "attack")
+ *    30 — stringId contains term as substring
+ *    25 — tag contains term as substring
+ *    90 — exact package name match (cross-pack only)
+ *    50 — word in package name matches (cross-pack only)
+ *    45 — exact package tag match (cross-pack only)
+ *    35 — package name/tag word prefix (cross-pack only)
+ *    25 — package name/tag substring (cross-pack only)
+ *  ── below TERM_THRESHOLD — boost only, can't qualify alone ──
+ *    15 — exact word in file path
+ *    12 — word in file path starts with term
+ *    10 — asset type / package description contains term
+ */
+function scoreAsset(terms, asset, pkg, pkgName, skipPkgMeta = false) {
+    let total = 0;
+    const sid = asset.stringId.toLowerCase();
+    const sidWords = splitWords(asset.stringId);
+    const fileWords = splitWords(asset.file);
+    for (const t of terms) {
+        let best = 0;
+        // ── Strong signals (can qualify on their own) ──────────────────
+        // stringId
+        if (sid === t)
+            best = 100;
+        else if (sidWords.some(w => w === t))
+            best = Math.max(best, 60);
+        else if (sid.startsWith(t))
+            best = Math.max(best, 50);
+        else if (sidWords.some(w => w.startsWith(t)))
+            best = Math.max(best, 40);
+        else if (sid.includes(t))
+            best = Math.max(best, 30);
+        // tags (curated — score high)
+        if (asset.tags.some(tag => tag.toLowerCase() === t))
+            best = Math.max(best, 80);
+        else if (asset.tags.some(tag => splitWords(tag).some(w => w === t)))
+            best = Math.max(best, 60);
+        else if (asset.tags.some(tag => splitWords(tag).some(w => w.startsWith(t))))
+            best = Math.max(best, 45);
+        else if (asset.tags.some(tag => tag.toLowerCase().includes(t)))
+            best = Math.max(best, 25);
+        // ── Weak signals (boost only, below threshold) ─────────────────
+        // file path (word-level only, no raw substring)
+        if (fileWords.some(w => w === t))
+            best = Math.max(best, 15);
+        else if (fileWords.some(w => w.startsWith(t)))
+            best = Math.max(best, 12);
+        // asset type
+        if (asset.type.toLowerCase().includes(t))
+            best = Math.max(best, 10);
+        // package metadata (cross-pack discovery only)
+        if (!skipPkgMeta) {
+            const pkgLower = pkgName.toLowerCase();
+            const pkgWords = splitWords(pkgName);
+            // Pack name — strongest cross-pack signal
+            if (pkgLower === t)
+                best = Math.max(best, 90);
+            else if (pkgWords.some(w => w === t))
+                best = Math.max(best, 50);
+            else if (pkgWords.some(w => w.startsWith(t)))
+                best = Math.max(best, 35);
+            else if (pkgLower.includes(t))
+                best = Math.max(best, 25);
+            // Pack tags — curated, high signal
+            if ((pkg.tags ?? []).some(tag => tag.toLowerCase() === t))
+                best = Math.max(best, 45);
+            else if ((pkg.tags ?? []).some(tag => splitWords(tag).some(w => w === t || w.startsWith(t))))
+                best = Math.max(best, 35);
+            else if ((pkg.tags ?? []).some(tag => tag.toLowerCase().includes(t)))
+                best = Math.max(best, 25);
+            // Pack description — weakest, just a boost
+            if (pkg.description.toLowerCase().includes(t))
+                best = Math.max(best, 10);
+        }
+        // AND semantics: if this term didn't clear the threshold,
+        // the asset doesn't qualify — bail out early.
+        if (best < TERM_THRESHOLD)
+            return 0;
+        total += best;
+    }
+    return total;
+}
+// ─── List Packages ───────────────────────────────────────────────────────────
+export function listPackages(registry) {
+    return Object.entries(registry.packages).map(([name, pkg]) => {
+        const ver = pkg.versions[pkg.latest];
+        return {
+            name,
+            description: pkg.description,
+            author: pkg.author,
+            tags: pkg.tags ?? [],
+            latest: pkg.latest,
+            versions: Object.keys(pkg.versions),
+            assetCount: ver?.assets.length ?? 0,
+            totalSize: ver?.totalSize ?? 0,
+        };
+    });
+}
+// ─── Resolve Dependencies ────────────────────────────────────────────────────
+export function resolveAssetDeps(registry, packageName, stringIds, version) {
+    const pkg = registry.packages[packageName];
+    if (!pkg)
+        throw new Error(`Package "${packageName}" not found`);
+    const verStr = version ?? pkg.latest;
+    const ver = pkg.versions[verStr];
+    if (!ver)
+        throw new Error(`Version "${verStr}" not found`);
+    const resolvedIds = resolveTransitiveDeps(stringIds, ver.assets);
+    const files = resolveFiles(resolvedIds, ver.assets);
+    return { resolvedIds, files };
+}
+// ─── CLI Commands ────────────────────────────────────────────────────────────
+export async function storeSearch(query, opts) {
+    const registry = await fetchRegistry(opts?.bucket);
+    const results = searchAssets(registry, query, { type: opts?.type });
+    if (opts?.json) {
+        console.log(JSON.stringify(results, null, 2));
+        return;
+    }
+    if (results.length === 0) {
+        console.log(`No assets found matching "${query}"`);
+        return;
+    }
+    console.log(`\nFound ${results.length} asset${results.length !== 1 ? 's' : ''} matching "${query}":\n`);
+    for (const r of results) {
+        const tags = r.tags.length > 0 ? ` [${r.tags.join(', ')}]` : '';
+        const deps = r.dependencies.length > 0 ? ` → ${r.dependencies.join(', ')}` : '';
+        const thumb = r.thumbnail ? ' (has thumbnail)' : '';
+        console.log(`  [${r.type}] ${r.stringId} — ${r.packageName}@${r.version}${tags}${deps}${thumb}`);
+        console.log(`    ${r.file} (${formatBytes(r.size)})`);
+    }
+    console.log('');
+}
+export async function storeList(opts) {
+    const registry = await fetchRegistry(opts?.bucket);
+    const packages = listPackages(registry);
+    if (opts?.json) {
+        console.log(JSON.stringify(packages, null, 2));
+        return;
+    }
+    if (packages.length === 0) {
+        console.log('No packages published yet.');
+        return;
+    }
+    console.log(`\n${packages.length} package${packages.length !== 1 ? 's' : ''} in the asset store:\n`);
+    for (const p of packages) {
+        const tags = p.tags.length > 0 ? ` [${p.tags.join(', ')}]` : '';
+        const desc = p.description ? ` — ${p.description}` : '';
+        console.log(`  ${p.name}@${p.latest}${desc}${tags}`);
+        console.log(`    ${p.assetCount} assets, ${formatBytes(p.totalSize)}, ${p.versions.length} version${p.versions.length !== 1 ? 's' : ''}`);
+    }
+    console.log('');
+}
+export async function storeInfo(packageName, opts) {
+    const registry = await fetchRegistry(opts?.bucket);
+    const pkg = registry.packages[packageName];
+    if (!pkg) {
+        console.error(`Package "${packageName}" not found.`);
+        process.exit(1);
+    }
+    const ver = pkg.versions[pkg.latest];
+    if (opts?.json) {
+        console.log(JSON.stringify({
+            name: packageName,
+            description: pkg.description,
+            author: pkg.author,
+            tags: pkg.tags ?? [],
+            latest: pkg.latest,
+            versions: Object.keys(pkg.versions),
+            assets: ver?.assets ?? [],
+        }, null, 2));
+        return;
+    }
+    console.log(`\n${packageName}@${pkg.latest}`);
+    if (pkg.description)
+        console.log(`  ${pkg.description}`);
+    if (pkg.author)
+        console.log(`  Author: ${pkg.author}`);
+    if (pkg.tags?.length)
+        console.log(`  Tags: ${pkg.tags.join(', ')}`);
+    console.log(`  Versions: ${Object.keys(pkg.versions).join(', ')}`);
+    if (ver) {
+        console.log(`\nAssets (${ver.assets.length}):\n`);
+        for (const a of ver.assets) {
+            const tags = a.tags.length > 0 ? ` [${a.tags.join(', ')}]` : '';
+            const deps = a.dependencies.length > 0 ? ` → ${a.dependencies.join(', ')}` : '';
+            console.log(`  [${a.type}] ${a.stringId}${tags}${deps} (${formatBytes(a.size)})`);
+        }
+    }
+    console.log('');
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@series-inc/stowkit-cli",
-  "version": "0.6.16",
+  "version": "0.6.18",
   "type": "module",
   "bin": {
     "stowkit": "./dist/cli.js"
@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "@series-inc/stowkit-packer-gui": "^0.1.17",
-    "@series-inc/stowkit-editor": "^0.1.6",
+    "@series-inc/stowkit-editor": "^0.1.8",
     "draco3d": "^1.5.7",
     "fbx-parser": "^2.1.3",
     "@strangeape/ffmpeg-audio-wasm": "^0.1.0",

package/skill.md

@@ -53,6 +53,9 @@ 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)
@@ -63,6 +66,8 @@ 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`)
 
@@ -525,6 +530,59 @@ 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 public GCS bucket with a central `registry.json` manifest.
+
+### Searching the store
+
+```bash
+stowkit store search coral                    # Find assets matching "coral"
+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 package_test               # Show all assets in a package
+stowkit store info package_test --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.
+
+### 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,
+    "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 has a **Store** button to browse, search, and import assets. Selected assets and their transitive dependencies are downloaded directly into the project's `srcArtDir`.
+
+### Thumbnail URLs
+
+Published assets may have thumbnails at:
+```
+https://storage.googleapis.com/{bucket}/packages/{packageName}/{version}/thumbnails/{stringId}.png
+```
+
+Check the `thumbnail` boolean in search results to know if a thumbnail exists.
+
 ## Common Tasks for AI Agents
 
 ### Adding a GLB model (recommended 3D workflow)
@@ -590,3 +648,8 @@ 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