@jgengine/assets 0.7.0 → 0.9.0

package/dist/download.js

@@ -26,11 +26,11 @@ function score(candidate) {
         value += 1;
     return value;
 }
-export async function resolveArchiveUrl(source) {
+export async function resolveArchiveUrl(source, fetchImpl = fetch) {
     const download = source.download;
     if (!isScrapeDownload(download))
         return download.url;
-    const response = await fetch(download.scrape, { redirect: "follow" });
+    const response = await fetchImpl(download.scrape, { redirect: "follow" });
     if (!response.ok)
         throw new Error(`scrape ${download.scrape} -> HTTP ${response.status}`);
     const html = await response.text();
@@ -40,12 +40,101 @@ export async function resolveArchiveUrl(source) {
     }
     return url;
 }
-export async function downloadArchive(url) {
-    const response = await fetch(url, { redirect: "follow" });
+export async function downloadArchive(url, fetchImpl = fetch) {
+    const response = await fetchImpl(url, { redirect: "follow" });
     if (!response.ok)
         throw new Error(`download ${url} -> HTTP ${response.status}`);
     return new Uint8Array(await response.arrayBuffer());
 }
+/**
+ * Layout for the `--mirror` / `JGENGINE_ASSETS_MIRROR` base URL override: the
+ * archive for a pack is expected at `<baseUrl>/<provider>/<packId>.zip`, e.g.
+ * `https://my-mirror.example.com/kenney/kenney-nature.zip`.
+ */
+export function mirrorOverrideUrl(baseUrl, source) {
+    const base = baseUrl.replace(/\/+$/, "");
+    return `${base}/${source.provider}/${source.id}.zip`;
+}
+/**
+ * Default asset mirror: this repo's own GitHub Releases, reachable from every
+ * cloud sandbox without network-policy changes (github.com is on the default
+ * allowlist). Assets live on the rolling `packs` release, one flat zip per
+ * pack named `<provider>-<packId>.zip`, kept in sync with the source catalog
+ * by `.github/workflows/mirror-assets.yml` — adding a catalog entry is the
+ * whole publishing step. Override the chain with `--mirror` /
+ * `JGENGINE_ASSETS_MIRROR`, or disable this hop with
+ * `JGENGINE_ASSETS_NO_DEFAULT_MIRROR=1`.
+ */
+export const DEFAULT_RELEASE_BASE = "https://github.com/Noisemaker111/jgengine/releases/download/packs";
+/** URL of `source`'s archive on the default GitHub-release mirror. */
+export function defaultReleaseUrl(source) {
+    return `${DEFAULT_RELEASE_BASE}/${source.provider}-${source.id}.zip`;
+}
+async function verifyPinnedSha(source, archive) {
+    const download = source.download;
+    if (isScrapeDownload(download) || download.sha256 === undefined)
+        return;
+    const actual = await sha256Hex(archive);
+    if (actual !== download.sha256) {
+        throw new Error(`sha256 mismatch: expected ${download.sha256}, got ${actual}`);
+    }
+}
+/**
+ * Resolves and downloads a pack's archive, trying sources in order until one
+ * succeeds: (1) the mirror base override at `mirrorOverrideUrl`, (2) the
+ * default GitHub-release mirror at `defaultReleaseUrl` (skipped when
+ * `JGENGINE_ASSETS_NO_DEFAULT_MIRROR=1`), (3) the primary provider path
+ * (`resolveArchiveUrl`: scrape or pinned URL), (4) the pack's own `mirror`
+ * URL. A pinned `sha256` is verified against whichever
+ * source supplied the bytes; a mismatch is treated as a failed attempt so the
+ * next source in the chain is tried. Throws with every attempted URL and its
+ * failure reason when all sources fail.
+ */
+export async function downloadPackArchive(source, options = {}) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const attempted = [];
+    const errors = [];
+    const tryUrl = async (url) => {
+        attempted.push(url);
+        try {
+            const archive = await downloadArchive(url, fetchImpl);
+            await verifyPinnedSha(source, archive);
+            return { archive, url, attempted };
+        }
+        catch (error) {
+            errors.push(`${url}: ${error instanceof Error ? error.message : String(error)}`);
+            return undefined;
+        }
+    };
+    if (options.mirrorBase !== undefined) {
+        const result = await tryUrl(mirrorOverrideUrl(options.mirrorBase, source));
+        if (result !== undefined)
+            return result;
+    }
+    if (process.env.JGENGINE_ASSETS_NO_DEFAULT_MIRROR !== "1") {
+        const result = await tryUrl(defaultReleaseUrl(source));
+        if (result !== undefined)
+            return result;
+    }
+    try {
+        const primaryUrl = await resolveArchiveUrl(source, fetchImpl);
+        const result = await tryUrl(primaryUrl);
+        if (result !== undefined)
+            return result;
+    }
+    catch (error) {
+        const label = isScrapeDownload(source.download) ? source.download.scrape : source.download.url;
+        errors.push(`${label}: ${error instanceof Error ? error.message : String(error)}`);
+        attempted.push(label);
+    }
+    if (source.mirror !== undefined) {
+        const result = await tryUrl(source.mirror);
+        if (result !== undefined)
+            return result;
+    }
+    throw new Error(`failed to download ${source.id} from all ${attempted.length} source(s):\n` +
+        errors.map((line) => `  - ${line}`).join("\n"));
+}
 export function extractGlbs(archive) {
     const entries = unzipSync(archive, {
         filter: (file) => /\.glb$/i.test(file.name),

package/dist/find.d.ts

@@ -0,0 +1,35 @@
+export type AssetKind = "model" | "pack" | "component" | "icon";
+export type AssetMatch = {
+    kind: "model";
+    id: string;
+    source: string;
+    file?: string;
+    via: "index" | "alias" | "single";
+} | {
+    kind: "pack";
+    source: string;
+    title: string;
+    categories: readonly string[];
+} | {
+    kind: "component";
+    name: string;
+    title: string;
+    description: string;
+} | {
+    kind: "icon";
+    name: string;
+};
+export interface FindOptions {
+    /** Restrict results to one kind. */
+    kind?: AssetKind;
+    /** Cap the number of matches returned (default 12). */
+    limit?: number;
+}
+export interface RankedMatch {
+    match: AssetMatch;
+    score: number;
+}
+/** Rank every catalog entry — models, packs, HUD components, icons — against one query. */
+export declare function rankAssets(query: string, options?: FindOptions): RankedMatch[];
+/** The ranked matches for a query — models, packs, HUD components, and icons in one list. */
+export declare function findAssets(query: string, options?: FindOptions): AssetMatch[];

package/dist/find.js

@@ -0,0 +1,147 @@
+import { aliases } from "./aliases.js";
+import { generatedIndex } from "./generated/index.js";
+import { keyFromFile } from "./indexGen.js";
+import { registryCatalog } from "./registry.js";
+import { singles } from "./singles.js";
+import { sources } from "./sources/index.js";
+function normalize(value) {
+    return value.toLowerCase().replace(/[\s_/-]+/g, " ").trim();
+}
+function tokenScore(token, hay, words) {
+    if (words.includes(token))
+        return 70;
+    if (hay.startsWith(token))
+        return 55;
+    if (words.some((word) => word.startsWith(token)))
+        return 45;
+    if (hay.includes(token))
+        return 30;
+    return 0;
+}
+/**
+ * 0 (no match) … 100 (exact). Single-word queries reward whole-word and prefix
+ * hits over loose substrings; a multi-word query ("mana bar") scores by the mean
+ * of its tokens and only counts when *every* token lands in the field.
+ */
+function scoreText(needle, hay) {
+    const n = normalize(needle);
+    const h = normalize(hay);
+    if (n.length === 0 || h.length === 0)
+        return 0;
+    if (h === n)
+        return 100;
+    const words = h.split(" ");
+    const tokens = n.split(" ").filter((token) => token.length > 0);
+    if (tokens.length <= 1)
+        return tokenScore(n, h, words);
+    let sum = 0;
+    for (const token of tokens) {
+        const score = tokenScore(token, h, words);
+        if (score === 0)
+            return 0;
+        sum += score;
+    }
+    return Math.min(90, Math.round(sum / tokens.length));
+}
+function best(needle, ...hays) {
+    let top = 0;
+    for (const hay of hays) {
+        if (hay === undefined)
+            continue;
+        top = Math.max(top, scoreText(needle, hay));
+    }
+    return top;
+}
+function sourceOf(id) {
+    const slash = id.indexOf("/");
+    return slash === -1 ? id : id.slice(0, slash);
+}
+/** Rank every catalog entry — models, packs, HUD components, icons — against one query. */
+export function rankAssets(query, options = {}) {
+    const q = query.trim();
+    const ranked = [];
+    const push = (score, match) => {
+        if (score > 0)
+            ranked.push({ score, match });
+    };
+    if (options.kind === undefined || options.kind === "model") {
+        for (const entry of generatedIndex) {
+            push(best(q, entry.id, keyFromFile(entry.file), ...entry.categories), {
+                kind: "model",
+                id: entry.id,
+                source: entry.source,
+                file: entry.file,
+                via: "index",
+            });
+        }
+        for (const alias of aliases) {
+            push(best(q, alias.key, alias.target), {
+                kind: "model",
+                id: alias.target,
+                source: sourceOf(alias.target),
+                via: "alias",
+            });
+        }
+        for (const single of singles) {
+            push(best(q, single.id, ...single.categories), {
+                kind: "model",
+                id: single.id,
+                source: sourceOf(single.id),
+                via: "single",
+            });
+        }
+    }
+    if (options.kind === undefined || options.kind === "pack") {
+        for (const source of sources) {
+            push(best(q, source.id, source.title, source.provider, ...source.categories), {
+                kind: "pack",
+                source: source.id,
+                title: source.title,
+                categories: source.categories,
+            });
+        }
+    }
+    if (options.kind === undefined || options.kind === "component") {
+        for (const component of registryCatalog.components) {
+            push(best(q, component.name, component.title, component.description), {
+                kind: "component",
+                name: component.name,
+                title: component.title,
+                description: component.description,
+            });
+        }
+    }
+    if (options.kind === undefined || options.kind === "icon") {
+        for (const icon of registryCatalog.icons) {
+            push(best(q, icon), { kind: "icon", name: icon });
+        }
+    }
+    ranked.sort((a, b) => b.score - a.score || matchKey(a.match).localeCompare(matchKey(b.match)));
+    return dedupe(ranked).slice(0, options.limit ?? 12);
+}
+function matchKey(match) {
+    switch (match.kind) {
+        case "model":
+            return `model:${match.id}`;
+        case "pack":
+            return `pack:${match.source}`;
+        default:
+            return `${match.kind}:${match.name}`;
+    }
+}
+function dedupe(ranked) {
+    const seen = new Set();
+    const out = [];
+    for (const entry of ranked) {
+        const key = matchKey(entry.match);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(entry);
+    }
+    return out;
+}
+/** The ranked matches for a query — models, packs, HUD components, and icons in one list. */
+export function findAssets(query, options = {}) {
+    return rankAssets(query, options).map((entry) => entry.match);
+}

package/dist/index.d.ts

@@ -6,4 +6,7 @@ export { generatedIndex, generatedBySource } from "./generated/index.js";
 export { readGlbDims } from "./dims.js";
 export { buildCatalog, entryUrl, type BuildCatalogOptions } from "./catalogs/build.js";
 export { createStarterCatalog } from "./catalogs/starter.js";
+export { findAssets, rankAssets, type AssetKind, type AssetMatch, type FindOptions, type RankedMatch, } from "./find.js";
+export { registryCatalog, componentInstallUrl, type RegistryCatalog, type RegistryComponent } from "./registry.js";
+export { modelWiringSnippet, componentWiringSnippet, iconWiringSnippet, type ModelSnippetOptions } from "./snippet.js";
 export { verifyManifest, type VerifyResult } from "./verify.js";

package/dist/index.js

@@ -6,4 +6,7 @@ export { generatedIndex, generatedBySource } from "./generated/index.js";
 export { readGlbDims } from "./dims.js";
 export { buildCatalog, entryUrl } from "./catalogs/build.js";
 export { createStarterCatalog } from "./catalogs/starter.js";
+export { findAssets, rankAssets, } from "./find.js";
+export { registryCatalog, componentInstallUrl } from "./registry.js";
+export { modelWiringSnippet, componentWiringSnippet, iconWiringSnippet } from "./snippet.js";
 export { verifyManifest } from "./verify.js";

package/dist/indexGen.js

@@ -49,7 +49,7 @@ export function indexSourceDir(source, dir) {
 function safeIdentifier(sourceId) {
     return `s_${sourceId.replace(/[^a-zA-Z0-9]/g, "_")}`;
 }
-function renderBarrel(sourceIds) {
+function renderTsBarrel(sourceIds) {
     const ordered = [...sourceIds].sort((a, b) => a.localeCompare(b));
     const imports = ordered
         .map((id) => `import ${safeIdentifier(id)} from "./${id}.json" with { type: "json" };`)
@@ -68,6 +68,22 @@ ${table}
 export const generatedIndex: IndexEntry[] = Object.values(generatedBySource).flat();
 `;
 }
+function renderJsBarrel(sourceIds) {
+    const ordered = [...sourceIds].sort((a, b) => a.localeCompare(b));
+    const imports = ordered
+        .map((id) => `import ${safeIdentifier(id)} from "./${id}.json" with { type: "json" };`)
+        .join("\n");
+    const table = ordered.map((id) => `  ${JSON.stringify(id)}: ${safeIdentifier(id)},`).join("\n");
+    return `// AUTO-GENERATED by \`assets reindex\`. Do not edit by hand.
+${imports}
+
+export const generatedBySource = {
+${table}
+};
+
+export const generatedIndex = Object.values(generatedBySource).flat();
+`;
+}
 export function reindex(modelsDir, outDir) {
     mkdirSync(outDir, { recursive: true });
     const perSource = [];
@@ -86,6 +102,11 @@ export function reindex(modelsDir, outDir) {
         sourceIds.push(sourceId);
         perSource.push({ source: sourceId, count: entries.length });
     }
-    writeFileSync(join(outDir, "index.ts"), renderBarrel(sourceIds));
+    writeFileSync(join(outDir, "index.ts"), renderTsBarrel(sourceIds));
+    // Published installs only ship dist/; write a JS barrel there so buildCatalog can re-import after reindex.
+    // Source-tree reindex keeps the TypeScript barrel that the package build compiles.
+    if (!/[/\\]src[/\\]generated$/i.test(outDir)) {
+        writeFileSync(join(outDir, "index.js"), renderJsBarrel(sourceIds));
+    }
     return { perSource, total: perSource.reduce((sum, entry) => sum + entry.count, 0) };
 }

package/dist/manifest.d.ts

@@ -19,6 +19,8 @@ export interface AssetSource {
     categories: readonly string[];
     download: AssetDownload;
     homepage?: string;
+    /** Direct archive URL tried as a last resort when the primary provider path fails; see `downloadPackArchive`. */
+    mirror?: string;
 }
 export interface IndexEntry {
     id: string;