summer-engine 3.8.0 → 4.0.0

package/dist/core/ops/save-files.d.ts

@@ -0,0 +1,78 @@
+import type { Answer } from "./contract.js";
+/**
+ * Generated files on this machine (4.0). The generate operations, assets.get
+ * and jobs.wait take `out` here: a folder or a file path. This package keeps
+ * it (the hosted server never sees it), downloads each file the answer names
+ * and adds `localPath` beside its URL. 3D, video and animation answer with a
+ * job, so their files save when jobs.wait sees the job finish; a generation
+ * that waits for approval keeps its `out` through the approval.
+ *
+ * Without `out`, a session that saves by default (the assets profile and the
+ * CLI) puts a generation's files in the asset folder of the game project it
+ * runs in. assets.get is a read: it saves only with `out`. Sessions with
+ * engine tools never save by default: there summer_import_asset_by_id puts
+ * the file in the project, and a second copy would land next to it.
+ *
+ * A save never overwrites a file, writes only media and model file types,
+ * downloads only from public https hosts, and never fails the answer: what
+ * was not saved is a warning.
+ */
+/** Operations whose answer names files. */
+export declare const SAVES_FILES: ReadonlySet<string>;
+/** Operations that take `out`. */
+export declare const TAKES_OUT: ReadonlySet<string>;
+export declare const OUT_DESCRIPTION: string;
+/** The largest file a save writes. */
+export declare const MAX_DOWNLOAD_BYTES: number;
+/** An operation's input schema with `out`, for the operations that take it. */
+export declare function withOutField(op: string, schema: unknown): unknown;
+export type GameProject = {
+    root: string;
+    engine: "godot" | "unity" | "unreal" | "threejs";
+    assets: string;
+};
+/** The game project at or above `start` and its asset folder, or null. The walk stops below the home folder and at a repository root. */
+export declare function findGameProject(start: string): Promise<GameProject | null>;
+export type LookupHost = (host: string) => Promise<Array<{
+    address: string;
+}>>;
+/** An address in a range a download must not reach; IPv4-mapped IPv6 forms (::ffff:7f00:1) match the IPv4 ranges. Not an address: true. */
+export declare function isPrivateAddress(address: string): boolean;
+export interface FileSaverOptions {
+    /** Save a generation into the project's asset folder when the call has no `out`. */
+    saveByDefault: boolean;
+    /** Where relative paths and project detection start. Default: the working directory. */
+    cwd?: () => string;
+    fetch?: typeof fetch;
+    /** DNS for the public-host check. Default: the system resolver. */
+    lookup?: LookupHost;
+    /** The largest file to save. Default: MAX_DOWNLOAD_BYTES. */
+    maxBytes?: number;
+}
+/** Saves the files of generate, assets.get and jobs.wait answers; one per session (it remembers each job's `out`). */
+export declare class FileSaver {
+    private readonly options;
+    private readonly jobs;
+    /** URL to the file a default save wrote this session: a second wait on a finished job reuses it. */
+    private readonly defaultSaves;
+    constructor(options: FileSaverOptions);
+    /** The input to send on, without `out`, and the `out` it carried. */
+    take(op: string, input: Record<string, unknown>): {
+        input: Record<string, unknown>;
+        out?: string;
+    };
+    /**
+     * The answer with its files saved and `localPath` added, or as it was.
+     * Saving never fails the answer (a paid generation keeps its asset ids):
+     * whatever goes wrong becomes a warning.
+     */
+    finish(op: string, answer: Answer, out?: string): Promise<Answer>;
+    private settle;
+    private save;
+    private cwd;
+    private targetOf;
+    /** Download one file into the target under a free name; notes what changed from the caller's file name. */
+    private download;
+    /** The file in a hidden temp file in `dir` (engines skip dot files), from a public https host, within the size limit. */
+    private fetchToTemp;
+}

package/dist/core/ops/save-files.js

@@ -0,0 +1,419 @@
+import { randomBytes } from "node:crypto";
+import { lookup } from "node:dns/promises";
+import { constants } from "node:fs";
+import { copyFile, link, mkdir, open, readdir, readFile, stat, unlink } from "node:fs/promises";
+import { BlockList, isIP } from "node:net";
+import { homedir } from "node:os";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+/**
+ * Generated files on this machine (4.0). The generate operations, assets.get
+ * and jobs.wait take `out` here: a folder or a file path. This package keeps
+ * it (the hosted server never sees it), downloads each file the answer names
+ * and adds `localPath` beside its URL. 3D, video and animation answer with a
+ * job, so their files save when jobs.wait sees the job finish; a generation
+ * that waits for approval keeps its `out` through the approval.
+ *
+ * Without `out`, a session that saves by default (the assets profile and the
+ * CLI) puts a generation's files in the asset folder of the game project it
+ * runs in. assets.get is a read: it saves only with `out`. Sessions with
+ * engine tools never save by default: there summer_import_asset_by_id puts
+ * the file in the project, and a second copy would land next to it.
+ *
+ * A save never overwrites a file, writes only media and model file types,
+ * downloads only from public https hosts, and never fails the answer: what
+ * was not saved is a warning.
+ */
+/** Operations whose answer names files. */
+export const SAVES_FILES = new Set([
+    "assets.generate_image",
+    "assets.generate_audio",
+    "assets.generate_3d",
+    "assets.generate_video",
+    "assets.generate_motion",
+    "assets.get",
+]);
+const JOBS_WAIT = "jobs.wait";
+/** Operations that take `out`. */
+export const TAKES_OUT = new Set([...SAVES_FILES, JOBS_WAIT]);
+export const OUT_DESCRIPTION = "Save the file on this machine: a folder, or a file path (res:// in a Godot project). The answer adds localPath. " +
+    "Without out, a generation in the assets profile or the CLI saves into the project's asset folder (Godot assets/, Unity Assets/Summer, Unreal Content/Summer, three.js public/assets).";
+const DOWNLOAD_TIMEOUT_MS = 120_000;
+/** The largest file a save writes. */
+export const MAX_DOWNLOAD_BYTES = 500 * 1024 * 1024;
+const MAX_REDIRECTS = 5;
+/** The file types a save writes: media and models, never code or a library a game engine would load. */
+const ALLOWED_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".webp", ".gif", ".mp3", ".wav", ".ogg", ".mp4", ".webm", ".glb", ".gltf", ".fbx", ".obj"]);
+const EXTENSIONS = {
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+    "image/webp": ".webp",
+    "image/gif": ".gif",
+    "audio/mpeg": ".mp3",
+    "audio/mp3": ".mp3",
+    "audio/wav": ".wav",
+    "audio/x-wav": ".wav",
+    "audio/ogg": ".ogg",
+    "video/mp4": ".mp4",
+    "video/webm": ".webm",
+    "model/gltf-binary": ".glb",
+    "model/gltf+json": ".gltf",
+};
+/** An operation's input schema with `out`, for the operations that take it. */
+export function withOutField(op, schema) {
+    if (!TAKES_OUT.has(op) || !schema || typeof schema !== "object" || Array.isArray(schema))
+        return schema;
+    const record = schema;
+    return { ...record, properties: { ...(record.properties ?? {}), out: { type: "string", description: OUT_DESCRIPTION } } };
+}
+/** The game project at or above `start` and its asset folder, or null. The walk stops below the home folder and at a repository root. */
+export async function findGameProject(start) {
+    const home = homedir();
+    let current = resolve(start);
+    while (current !== home) {
+        let names;
+        try {
+            names = await readdir(current);
+        }
+        catch {
+            names = [];
+        }
+        const found = await projectIn(current, names);
+        if (found)
+            return found;
+        const parent = dirname(current);
+        if (parent === current || names.includes(".git"))
+            return null;
+        current = parent;
+    }
+    return null;
+}
+async function projectIn(dir, names) {
+    const has = (name) => names.includes(name);
+    if (has("project.godot"))
+        return { root: dir, engine: "godot", assets: join(dir, "assets") };
+    if (has("Assets") && has("ProjectSettings"))
+        return { root: dir, engine: "unity", assets: join(dir, "Assets", "Summer") };
+    if (names.some((name) => name.endsWith(".uproject")))
+        return { root: dir, engine: "unreal", assets: join(dir, "Content", "Summer") };
+    if (has("package.json") && (await usesThree(join(dir, "package.json"))))
+        return { root: dir, engine: "threejs", assets: join(dir, "public", "assets") };
+    return null;
+}
+async function usesThree(packageJson) {
+    try {
+        const parsed = JSON.parse(await readFile(packageJson, "utf8"));
+        return Boolean(parsed.dependencies?.three ?? parsed.devDependencies?.three);
+    }
+    catch {
+        return false;
+    }
+}
+const asRecord = (value) => (value && typeof value === "object" && !Array.isArray(value) ? value : null);
+const text = (value) => (typeof value === "string" && value.trim() ? value.trim() : undefined);
+const urlOf = (holder) => text(holder.downloadUrl) ?? text(holder.fileUrl);
+const messageOf = (error) => (error instanceof Error ? error.message : String(error)).replace(/\.$/, "");
+/** The objects in a result that carry a file URL: each of `assets`, `asset`, and the result itself. */
+function holdersOf(result) {
+    const record = asRecord(result);
+    if (!record)
+        return [];
+    const list = [...(Array.isArray(record.assets) ? record.assets : []), record.asset, record];
+    return list.map(asRecord).filter((holder) => holder !== null && urlOf(holder) !== undefined);
+}
+function withWarnings(answer, warnings) {
+    return answer.ok && warnings.length ? { ...answer, warnings: [...(answer.warnings ?? []), ...warnings] } : answer;
+}
+async function isFile(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function slug(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60).replace(/-+$/, "");
+}
+const allowed = (ext) => (ext && ALLOWED_EXTENSIONS.has(ext.toLowerCase()) ? ext : undefined);
+const lookupAll = (host) => lookup(host, { all: true });
+/** Unspecified, loopback, private, link-local, carrier-grade NAT, benchmark, multicast, reserved and NAT64 ranges. */
+const PRIVATE_RANGES = new BlockList();
+for (const [network, prefix] of [["0.0.0.0", 8], ["10.0.0.0", 8], ["100.64.0.0", 10], ["127.0.0.0", 8], ["169.254.0.0", 16], ["172.16.0.0", 12], ["192.0.0.0", 24], ["192.168.0.0", 16], ["198.18.0.0", 15], ["224.0.0.0", 3]]) {
+    PRIVATE_RANGES.addSubnet(network, prefix, "ipv4");
+}
+for (const [network, prefix] of [["::", 96], ["fc00::", 7], ["fe80::", 10], ["ff00::", 8], ["64:ff9b::", 96], ["64:ff9b:1::", 48]]) {
+    PRIVATE_RANGES.addSubnet(network, prefix, "ipv6");
+}
+/** An address in a range a download must not reach; IPv4-mapped IPv6 forms (::ffff:7f00:1) match the IPv4 ranges. Not an address: true. */
+export function isPrivateAddress(address) {
+    const family = isIP(address);
+    return family === 0 || PRIVATE_RANGES.check(address, family === 4 ? "ipv4" : "ipv6");
+}
+/** The URL, when it is https on a public host; else why not. */
+async function publicHttps(raw, lookupHost) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error("the file URL is not valid");
+    }
+    if (url.protocol !== "https:")
+        throw new Error(`only https downloads are saved, not ${url.protocol}`);
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    if (host === "localhost" || host.endsWith(".localhost"))
+        throw new Error(`${host} is a local address`);
+    const addresses = isIP(host) ? [host] : (await lookupHost(host)).map((entry) => entry.address);
+    if (addresses.length === 0 || addresses.some(isPrivateAddress))
+        throw new Error(`${host} is a private or local address`);
+    return url;
+}
+/** Link the downloaded file to the first free name (never over an existing file); returns the path. */
+async function claimName(temp, dir, base, ext) {
+    for (let n = 1; n <= 10_000; n++) {
+        const candidate = join(dir, `${base}${n === 1 ? "" : `-${n}`}${ext}`);
+        try {
+            await link(temp, candidate);
+            return candidate;
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                continue;
+            // A disk without hard links (exFAT, some network drives): an exclusive copy.
+            try {
+                await copyFile(temp, candidate, constants.COPYFILE_EXCL);
+                return candidate;
+            }
+            catch (copyError) {
+                if (copyError.code === "EEXIST")
+                    continue;
+                throw copyError;
+            }
+        }
+    }
+    throw new Error(`no free file name for ${base}${ext} in ${dir}`);
+}
+/** Saves the files of generate, assets.get and jobs.wait answers; one per session (it remembers each job's `out`). */
+export class FileSaver {
+    options;
+    jobs = new Map();
+    /** URL to the file a default save wrote this session: a second wait on a finished job reuses it. */
+    defaultSaves = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    /** The input to send on, without `out`, and the `out` it carried. */
+    take(op, input) {
+        if (!TAKES_OUT.has(op) || !("out" in input))
+            return { input };
+        const { out, ...rest } = input;
+        const chosen = text(out);
+        return { input: rest, ...(chosen ? { out: chosen } : {}) };
+    }
+    /**
+     * The answer with its files saved and `localPath` added, or as it was.
+     * Saving never fails the answer (a paid generation keeps its asset ids):
+     * whatever goes wrong becomes a warning.
+     */
+    async finish(op, answer, out) {
+        try {
+            return await this.settle(op, answer, out);
+        }
+        catch (error) {
+            return withWarnings(answer, [`Not saved on this machine: ${messageOf(error)}.`]);
+        }
+    }
+    async settle(op, answer, out) {
+        if (!answer.ok)
+            return answer;
+        if (op === "ops.describe" && answer.status === "done")
+            return describedWithOut(answer);
+        if (!TAKES_OUT.has(op))
+            return answer;
+        // assets.get is a read: it saves only when asked.
+        const byDefault = op !== "assets.get";
+        if (answer.status === "running" || answer.status === "needs_approval") {
+            if (op !== JOBS_WAIT)
+                this.jobs.set(answer.job.id, { out, byDefault });
+            return answer;
+        }
+        if (answer.status !== "done")
+            return answer;
+        if (op !== JOBS_WAIT)
+            return this.save(answer, (copy) => copy.result, out, byDefault);
+        const wait = asRecord(answer.result);
+        const job = asRecord(wait?.job);
+        const id = text(job?.id);
+        if (!job || !id)
+            return answer;
+        const memory = this.jobs.get(id);
+        if (wait?.finished !== true) {
+            if (out)
+                this.jobs.set(id, { out, byDefault: memory?.byDefault ?? true });
+            return answer;
+        }
+        this.jobs.delete(id);
+        if (job.state !== "done")
+            return answer;
+        const chosen = out ?? memory?.out;
+        // An approved generation that runs on as a job: its `out` follows that job.
+        const result = asRecord(job.result);
+        const next = result?.status === "running" ? text(asRecord(result.job)?.id) : undefined;
+        if (next) {
+            if (memory || chosen)
+                this.jobs.set(next, { out: chosen, byDefault: memory?.byDefault ?? true });
+            return answer;
+        }
+        // Generation jobs (and approved generate calls) save by default; another job's result only when asked.
+        const generated = job.kind === "gen" || id.startsWith("gen:");
+        return this.save(answer, (copy) => asRecord(asRecord(copy.result)?.job)?.result, chosen, memory ? memory.byDefault : generated);
+    }
+    async save(answer, resultOf, out, byDefault) {
+        if (holdersOf(resultOf(answer)).length === 0) {
+            return out ? withWarnings(answer, ["out: this answer names no file, so nothing was saved on this machine."]) : answer;
+        }
+        const target = await this.targetOf(out, byDefault && this.options.saveByDefault);
+        if (!target)
+            return answer;
+        if ("error" in target)
+            return withWarnings(answer, [target.error]);
+        const copy = structuredClone(answer);
+        const warnings = [];
+        // With out the caller asked for a copy there; without it, a file this session already saved is reused.
+        const saved = out ? new Map() : this.defaultSaves;
+        let first = true;
+        for (const holder of holdersOf(resultOf(copy))) {
+            const url = urlOf(holder);
+            const known = saved.get(url);
+            if (known && (await isFile(known))) {
+                holder.localPath = known;
+                continue;
+            }
+            try {
+                const path = await this.download(url, holder, target, first, warnings);
+                first = false;
+                saved.set(url, path);
+                holder.localPath = path;
+            }
+            catch (error) {
+                warnings.push(`Not saved on this machine (${text(holder.assetId) ?? text(holder.id) ?? "file"}): ${messageOf(error)}.`);
+            }
+        }
+        return withWarnings(copy, warnings);
+    }
+    cwd() {
+        return this.options.cwd?.() ?? process.cwd();
+    }
+    async targetOf(out, byDefault) {
+        if (!out) {
+            if (!byDefault)
+                return null;
+            const project = await findGameProject(this.cwd());
+            return project ? { dir: project.assets } : null;
+        }
+        let path;
+        if (out.startsWith("res://")) {
+            const cwd = this.cwd();
+            const project = await findGameProject(cwd);
+            if (project?.engine !== "godot")
+                return { error: `out: a res:// path needs a Godot project (project.godot) at or above ${cwd}. Nothing was saved on this machine.` };
+            path = join(project.root, out.slice("res://".length));
+            const inside = relative(project.root, path);
+            if (inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside))
+                return { error: `out: ${out} is outside the Godot project. Nothing was saved on this machine.` };
+        }
+        else if (out === "~" || out.startsWith("~/")) {
+            path = join(homedir(), out.slice(1));
+        }
+        else {
+            path = isAbsolute(out) ? out : resolve(this.cwd(), out);
+        }
+        const folder = /[\\/]$/.test(out) || !extname(path) || (await isDirectory(path));
+        return folder ? { dir: path } : { dir: dirname(path), file: basename(path) };
+    }
+    /** Download one file into the target under a free name; notes what changed from the caller's file name. */
+    async download(url, holder, target, first, warnings) {
+        const { temp, finalUrl, contentType } = await this.fetchToTemp(url, target.dir);
+        try {
+            const detected = allowed(extname(text(holder.fileName) ?? "")) ?? allowed(extname(finalUrl.pathname)) ?? EXTENSIONS[contentType ?? ""] ?? EXTENSIONS[text(holder.mimeType) ?? ""] ?? ".bin";
+            if (target.file) {
+                const asked = extname(target.file);
+                const ext = allowed(asked) ?? detected;
+                const path = await claimName(temp, target.dir, basename(target.file, asked), ext);
+                const wanted = join(target.dir, target.file);
+                if (first && path !== wanted) {
+                    warnings.push(allowed(asked) ? `${wanted} already exists, so the file was saved as ${path}.` : `out: ${asked || "no extension"} is not a media or model file type, so the file was saved as ${path}.`);
+                }
+                return path;
+            }
+            const named = text(holder.fileName);
+            const base = (named && slug(basename(named, extname(named)))) || slug(text(holder.title) ?? "") || slug(text(holder.assetId) ?? text(holder.id) ?? "") || "summer-asset";
+            return await claimName(temp, target.dir, base, detected);
+        }
+        finally {
+            await unlink(temp).catch(() => undefined);
+        }
+    }
+    /** The file in a hidden temp file in `dir` (engines skip dot files), from a public https host, within the size limit. */
+    async fetchToTemp(url, dir) {
+        const lookupHost = this.options.lookup ?? lookupAll;
+        const fetchFile = this.options.fetch ?? fetch;
+        let current = await publicHttps(url, lookupHost);
+        let response;
+        for (let hops = 0;; hops++) {
+            response = await fetchFile(current.href, { redirect: "manual", signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
+            const location = response.headers.get("location");
+            if (response.status < 300 || response.status >= 400 || !location)
+                break;
+            await response.body?.cancel().catch(() => undefined);
+            if (hops >= MAX_REDIRECTS)
+                throw new Error("the download redirected too many times");
+            current = await publicHttps(new URL(location, current).href, lookupHost);
+        }
+        if (!response.ok)
+            throw new Error(`the download answered HTTP ${response.status}`);
+        if (response.url)
+            current = await publicHttps(response.url, lookupHost);
+        const maxBytes = this.options.maxBytes ?? MAX_DOWNLOAD_BYTES;
+        const limit = maxBytes >= 1024 * 1024 ? `${Math.floor(maxBytes / 1024 / 1024)} MB` : `${maxBytes} bytes`;
+        if (Number(response.headers.get("content-length") ?? 0) > maxBytes)
+            throw new Error(`the file is larger than ${limit}`);
+        await mkdir(dir, { recursive: true });
+        const temp = join(dir, `.summer-download-${randomBytes(6).toString("hex")}.part`);
+        const handle = await open(temp, "wx");
+        try {
+            let size = 0;
+            if (response.body) {
+                for await (const chunk of response.body) {
+                    size += chunk.byteLength;
+                    if (size > maxBytes)
+                        throw new Error(`the file is larger than ${limit}`);
+                    await handle.write(chunk);
+                }
+            }
+            await handle.close();
+        }
+        catch (error) {
+            await handle.close().catch(() => undefined);
+            await unlink(temp).catch(() => undefined);
+            throw error;
+        }
+        return { temp, finalUrl: current, contentType: response.headers.get("content-type")?.split(";")[0].trim() };
+    }
+}
+/** ops.describe of an operation that takes `out`: its input shows `out` too. */
+function describedWithOut(answer) {
+    const operation = asRecord(asRecord(answer.result)?.operation);
+    const name = text(operation?.name);
+    if (!operation || !name || !TAKES_OUT.has(name))
+        return answer;
+    return { ...answer, result: { ...asRecord(answer.result), operation: { ...operation, input: withOutField(name, operation.input) } } };
+}

package/dist/core/ops/search.d.ts

@@ -0,0 +1,9 @@
+import type { CatalogEntry } from "./catalog.js";
+import type { Effect } from "./contract.js";
+export declare function words(text: string): string[];
+export declare function scoreEntry(entry: CatalogEntry, query: string): number;
+export declare function searchEntries(entries: readonly CatalogEntry[], query: string, filters: {
+    area?: string;
+    effect?: Effect;
+    limit: number;
+}): CatalogEntry[];

package/dist/core/ops/search.js

@@ -0,0 +1,55 @@
+/**
+ * Plain-words ranking over operations, the same scoring the hosted server
+ * uses, so one list can hold local and cloud hits.
+ */
+const STOP = new Set(["a", "an", "the", "my", "of", "for", "to", "in", "on", "and", "or", "with", "is", "it", "me", "i", "please", "how", "do", "what"]);
+export function words(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((word) => word.length > 1 && !STOP.has(word));
+}
+const stem = (word) => word.length > 3 && word.endsWith("ies") ? `${word.slice(0, -3)}y` : word.length > 3 && word.endsWith("s") && !word.endsWith("ss") ? word.slice(0, -1) : word;
+export function scoreEntry(entry, query) {
+    const terms = words(query);
+    if (!terms.length)
+        return 0;
+    const exact = query.trim().toLowerCase();
+    if (exact === entry.name || entry.legacy?.some((name) => name.split("#")[0] === exact))
+        return 1000;
+    const fields = [
+        [words(entry.name.replace(/[._]/g, " ")), 6],
+        [words(entry.title), 4],
+        [(entry.tags ?? []).flatMap(words), 3],
+        [(entry.legacy ?? []).flatMap((name) => words(name.replace(/^summer_/, "").replace(/[#_]/g, " "))), 2],
+        [words(entry.summary), 1],
+    ];
+    let total = 0;
+    for (const term of terms.map(stem)) {
+        let best = 0;
+        for (const [fieldWords, weight] of fields) {
+            for (const word of fieldWords) {
+                const candidate = stem(word);
+                if (candidate === term)
+                    best = Math.max(best, weight);
+                else if (term.length >= 4 && candidate.length >= 3 && (candidate.startsWith(term) || term.startsWith(candidate)))
+                    best = Math.max(best, weight / 2);
+            }
+        }
+        total += best;
+    }
+    return total;
+}
+const STATUS_RANK = { stable: 0, preview: 1, deprecated: 2 };
+export function searchEntries(entries, query, filters) {
+    const hasTerms = words(query).length > 0;
+    return entries
+        .filter((entry) => entry.status !== "deprecated")
+        .filter((entry) => !filters.area || entry.name === filters.area || entry.name.startsWith(`${filters.area}.`))
+        .filter((entry) => !filters.effect || entry.effect === filters.effect)
+        .map((entry) => ({ entry, score: scoreEntry(entry, query) }))
+        .filter(({ score }) => score > 0 || !hasTerms)
+        .sort((a, b) => b.score - a.score || STATUS_RANK[a.entry.status] - STATUS_RANK[b.entry.status] || Number(b.entry.available) - Number(a.entry.available) || a.entry.name.localeCompare(b.entry.name))
+        .slice(0, filters.limit)
+        .map(({ entry }) => entry);
+}

package/dist/core/skills-registry.d.ts

@@ -25,6 +25,10 @@ export interface SkillRegistryEntry {
     path: string;
     /** facets.domains from resource.yaml; the first is the primary domain. Empty on old registries. */
     domains: string[];
+    /** Bulk installs and the plugin manifests take it. false = library only
+     *  (library-author tools, research digests): readable with
+     *  summer_read_library and installable by name. Absent reads as true. */
+    bundled?: boolean;
 }
 /**
  * Load the generated skill registry (cached after first read).
@@ -34,18 +38,29 @@ export interface SkillRegistryEntry {
 export declare function getSkillRegistry(): readonly SkillRegistryEntry[];
 /** Shape-tolerant parse of skills-registry.json. Exported for unit tests. */
 export declare function parseSkillRegistry(json: unknown): SkillRegistryEntry[];
+/**
+ * The assets-only install (`summer setup --assets-only`, `skills install
+ * --assets`): skills that make sounds, music, voices, images, models,
+ * animation and video on Summer's servers, plus `summer-assets`, the session
+ * skill for that profile. Each says what to do without Summer Engine. The
+ * engine session skill `using-summer` and skills that wire assets into a
+ * running engine stay out.
+ */
+export declare function isAssetSkill(skill: Pick<SkillRegistryEntry, "name" | "domains">): boolean;
 /**
  * The one bulk-install rule (`skills install --all/--recommended` and
  * `summer setup` both use it): `stable` and `preview` skills install —
  * preview is a label ("not yet exercised in-engine by the Summer team"),
  * carried in each skill's own guidance, not a reason to hide contributed work;
- * `deprecated` never installs in bulk. `stableOnly` opts out of preview.
+ * `deprecated` never installs in bulk, and neither does a library-only skill
+ * (`bundled: false`). `stableOnly` opts out of preview.
  * The counts let the caller say how many preview skills it installed (or, with
  * stableOnly, left out) instead of printing a bare total.
  */
 export declare function selectSkillsForBulkInstall(skills: readonly SkillRegistryEntry[], options: {
     recommended?: boolean;
     stableOnly?: boolean;
+    assetsOnly?: boolean;
 }): {
     selected: SkillRegistryEntry[];
     previewIncluded: number;

package/dist/core/skills-registry.js

@@ -78,19 +78,52 @@ export function parseSkillRegistry(json) {
         status: s.status === "preview" || s.status === "deprecated" ? s.status : "stable",
         path: s.path,
         domains: Array.isArray(s.domains) ? s.domains.filter((d) => typeof d === "string") : [],
+        bundled: s.bundled !== false,
     }));
 }
+/** Skills that handle assets but need more than the assets profile: they wire
+ *  assets into a scene, or (store-art) make art for a Summer Games listing. */
+const NOT_ASSETS_ONLY_SKILLS = new Set([
+    "instantiate-asset-pack",
+    "use-widget-asset",
+    "skintokens-auto-rigging",
+    "fabricating-assets",
+    "lumera-single-image-scene-reconstruction",
+    "store-art",
+]);
+/**
+ * The assets-only install (`summer setup --assets-only`, `skills install
+ * --assets`): skills that make sounds, music, voices, images, models,
+ * animation and video on Summer's servers, plus `summer-assets`, the session
+ * skill for that profile. Each says what to do without Summer Engine. The
+ * engine session skill `using-summer` and skills that wire assets into a
+ * running engine stay out.
+ */
+export function isAssetSkill(skill) {
+    if (skill.name === "generate-motion")
+        return true;
+    if (NOT_ASSETS_ONLY_SKILLS.has(skill.name))
+        return false;
+    const domains = skill.domains ?? [];
+    return domains.includes("assets") || domains.includes("generate");
+}
 /**
  * The one bulk-install rule (`skills install --all/--recommended` and
  * `summer setup` both use it): `stable` and `preview` skills install —
  * preview is a label ("not yet exercised in-engine by the Summer team"),
  * carried in each skill's own guidance, not a reason to hide contributed work;
- * `deprecated` never installs in bulk. `stableOnly` opts out of preview.
+ * `deprecated` never installs in bulk, and neither does a library-only skill
+ * (`bundled: false`). `stableOnly` opts out of preview.
  * The counts let the caller say how many preview skills it installed (or, with
  * stableOnly, left out) instead of printing a bare total.
  */
 export function selectSkillsForBulkInstall(skills, options) {
-    const candidates = options.recommended ? skills.filter((skill) => skill.recommended) : [...skills];
+    const bundled = skills.filter((skill) => skill.bundled !== false);
+    const candidates = options.assetsOnly
+        ? bundled.filter(isAssetSkill)
+        : options.recommended
+            ? bundled.filter((skill) => skill.recommended)
+            : bundled;
     const stableOnly = options.stableOnly === true;
     const selected = candidates.filter((skill) => skill.status === "stable" || (!stableOnly && skill.status === "preview"));
     const preview = candidates.filter((skill) => skill.status === "preview").length;