summer-engine 2.8.2 → 3.1.0

package/dist/core/launch-posture.js

@@ -0,0 +1,317 @@
+/**
+ * Editor launch posture — the ONE place that decides whether `summer run`
+ * brings the Summer window to the front or leaves it in the background.
+ *
+ * The problem: when an agent drives Summer, every editor launch activates the
+ * app and steals the user's screen, so they cannot keep working while their
+ * game is built. The engine grows a launch posture for this:
+ *
+ *   focus       today's launch — the window appears and takes focus.
+ *   background  `--summer-background` — the window exists but never activates
+ *               or takes focus until the user clicks it.
+ *   offscreen   `--summer-offscreen` (also `--summer-verify`) — never
+ *               activates, never frontmost; on shipped engines an unfocusable
+ *               window pushed off-screen where a sliver may stay visible
+ *               (main.cpp says so), on the background-posture engine a
+ *               no-Dock-icon accessory process. Used by RunVerification /
+ *               offscreen play instances, never by `summer run`.
+ *
+ * Default posture: BACKGROUND when stdout is not a TTY, FOCUS when it is. A
+ * human typing `summer run` in a terminal wants to see the editor come up —
+ * that is the whole point of the command for them. An agent (Claude Code's
+ * Bash tool, an MCP host, a CI shell) never has a TTY on stdout, and for it
+ * the launch is a means to an end: the user is doing something else on the
+ * same Mac and must not be interrupted. `--focus` / `--background` override
+ * the heuristic either way; pass one explicitly in scripts.
+ *
+ * Engine support: the flag ships in a future 0.5.x. Godot's argument parser
+ * passes an unknown `--x` through to main_args instead of rejecting it
+ * (main/main.cpp, final `else` of the parse loop), so an old engine would not
+ * fail — it would silently launch WITH focus while the toolkit claimed a
+ * background launch. That is the lie we refuse to tell: the flag is passed
+ * only when the installed engine is known to honour it, and otherwise the
+ * caller gets a one-line note. The engine is not running before `summer run`,
+ * so /api/health cannot be consulted. Two pre-launch sources, in order:
+ *
+ *   1. `<binary> --help` and look for the flag in the help text — the PRIMARY
+ *      gate. `--help` is handled in Main::setup() before any display server
+ *      exists (main.cpp `arg == "--help"` -> ERR_HELP), and on macOS it is in
+ *      OS_MacOS::headless_args (os_macos.h; godot_main_macos.mm sets
+ *      is_headless and instantiates OS_MacOS_Headless), so the bundle runs
+ *      with no NSApp, no window, no activation, no Dock bounce. Definitive on
+ *      every engine version; the only probe that never lies. The answer is
+ *      cached per binary path + mtime + size in ~/.summer, so it runs once per
+ *      install.
+ *   2. The installed version (macOS Info.plist, Windows Velopack sq.version)
+ *      is ONLY the fallback when `--help` cannot run (spawn error, timeout).
+ *      It is never a pre-check: pre-release and dev builds carry the flag
+ *      while still stamped with the previous version (the first such build
+ *      says 0.5.65), so a version gate would refuse exactly the builds being
+ *      verified. Linux exposes no version file, so there it reads unknown.
+ *
+ * Once the engine is up, /api/health `capabilities.launchPostures`
+ * (["focus","background","offscreen"] on macOS builds, ["focus"] elsewhere,
+ * absent on older engines = ["focus"]) is the authoritative advert and is
+ * used for the post-launch note.
+ *
+ * `summer run` spawns the executable directly (Summer.app/Contents/MacOS/Summer
+ * on macOS), never through `open` — LaunchServices would activate the app and
+ * defeat the posture whatever flags were passed. The same holds for a
+ * `--bin` / SUMMER_BIN override: it must be the in-bundle executable, and the
+ * --help probe below runs against THAT binary (cache key: path + mtime + size).
+ */
+import { spawn } from "node:child_process";
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { platform } from "node:os";
+import { getSummerDir } from "./auth.js";
+/** Engine flag for the background posture (main/main.cpp). */
+export const BACKGROUND_LAUNCH_FLAG = "--summer-background";
+/** First RELEASED engine version expected to honour BACKGROUND_LAUNCH_FLAG.
+ *  Used only when the --help probe cannot run; dev/pre-release builds carry
+ *  the flag while still stamped 0.5.65, which is why the probe is the gate. */
+export const BACKGROUND_LAUNCH_MIN_ENGINE_VERSION = "0.5.66";
+/** BACKGROUND for agents (no TTY), FOCUS for a human at a terminal. */
+export function defaultLaunchPosture(io) {
+    return io.stdoutIsTTY ? "focus" : "background";
+}
+/** Explicit flag wins; both flags together is a caller error. */
+export function resolveLaunchPosture(flags, io) {
+    if (flags.focus && flags.background) {
+        throw new Error("Pass either --focus or --background, not both.");
+    }
+    if (flags.focus)
+        return "focus";
+    if (flags.background)
+        return "background";
+    return defaultLaunchPosture(io);
+}
+function parseVersion(version) {
+    const cleaned = version.trim().replace(/^v/i, "").split(/[-+]/)[0];
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(cleaned);
+    if (!match)
+        return null;
+    return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+function compareVersions(a, b) {
+    if (a.major !== b.major)
+        return a.major - b.major;
+    if (a.minor !== b.minor)
+        return a.minor - b.minor;
+    return a.patch - b.patch;
+}
+/**
+ * Whether the installed engine honours the background flag. The `--help`
+ * probe answer (true/false) is definitive when it ran; a probe that could not
+ * run (null) falls back to the version gate, where an unreadable or
+ * unparseable version is "unknown", never "supported".
+ */
+export function backgroundLaunchSupport(installedVersion, helpProbe = null) {
+    const version = installedVersion?.trim() || null;
+    if (helpProbe === true)
+        return { supported: true, source: "help_probe", version };
+    if (helpProbe === false)
+        return { supported: false, source: "help_probe", reason: "engine_too_old", version };
+    const parsed = version ? parseVersion(version) : null;
+    if (!parsed || !version)
+        return { supported: false, source: "version", reason: "version_unknown", version: null };
+    const min = parseVersion(BACKGROUND_LAUNCH_MIN_ENGINE_VERSION);
+    return compareVersions(parsed, min) >= 0
+        ? { supported: true, source: "version", version }
+        : { supported: false, source: "version", reason: "engine_too_old", version };
+}
+/** True when the help text of an engine binary lists the background flag. */
+export function helpTextListsBackgroundFlag(helpText) {
+    return helpText.includes(BACKGROUND_LAUNCH_FLAG);
+}
+export const HELP_PROBE_TIMEOUT_MS = 5_000;
+/**
+ * Run `<binary> --help` and report whether the flag is listed: true / false,
+ * or null when the probe could not answer (spawn error, timeout). Safe on
+ * every version: --help exits in Main::setup() before a display server exists,
+ * and the macOS bundle runs it headless (OS_MacOS::headless_args), so nothing
+ * appears on screen and nothing is activated.
+ */
+export function probeBackgroundLaunchSupport(binary, timeoutMs = HELP_PROBE_TIMEOUT_MS, spawnImpl = spawn) {
+    return new Promise((resolve) => {
+        let output = "";
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(value);
+        };
+        let child;
+        try {
+            child = spawnImpl(binary, ["--help"], { stdio: ["ignore", "pipe", "pipe"] });
+        }
+        catch {
+            resolve(null);
+            return;
+        }
+        const timer = setTimeout(() => {
+            try {
+                child.kill();
+            }
+            catch {
+                // already gone
+            }
+            finish(null);
+        }, timeoutMs);
+        child.stdout?.on("data", (chunk) => {
+            output += String(chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            output += String(chunk);
+        });
+        child.on("error", () => finish(null));
+        child.on("close", () => finish(output.length > 0 ? helpTextListsBackgroundFlag(output) : null));
+    });
+}
+// ---------------------------------------------------------------------------
+// Probe cache: one --help per install (binary path + mtime + size)
+// ---------------------------------------------------------------------------
+export const HELP_PROBE_CACHE_FILE = "launch-probe-cache.json";
+function binaryStamp(binary) {
+    try {
+        const info = statSync(binary);
+        return { mtimeMs: info.mtimeMs, size: info.size };
+    }
+    catch {
+        return null;
+    }
+}
+function readProbeCache(summerDir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(summerDir, HELP_PROBE_CACHE_FILE), "utf-8"));
+        if (parsed && parsed.version === 1 && parsed.binaries && typeof parsed.binaries === "object") {
+            return { version: 1, binaries: parsed.binaries };
+        }
+    }
+    catch {
+        // missing or corrupt cache: probe again
+    }
+    return { version: 1, binaries: {} };
+}
+function writeProbeCache(summerDir, binary, entry) {
+    try {
+        mkdirSync(summerDir, { recursive: true, mode: 0o700 });
+        const cache = readProbeCache(summerDir);
+        cache.binaries[binary] = entry;
+        writeFileSync(join(summerDir, HELP_PROBE_CACHE_FILE), JSON.stringify(cache, null, 2), { encoding: "utf-8", mode: 0o600 });
+    }
+    catch {
+        // best effort: a failed cache write only costs one more probe next time
+    }
+}
+/**
+ * The pre-launch decision for one binary, in the order the module header
+ * describes: cached `--help` answer, fresh `--help` probe (cached when it
+ * answers), and the version gate ONLY as the fallback when the probe cannot
+ * run. The probe is the sole positive gate — no version pre-check, so a dev
+ * build stamped 0.5.65 that lists the flag launches in the background.
+ */
+export async function detectBackgroundLaunchSupport(binary, options = {}) {
+    const version = options.installedVersion !== undefined ? options.installedVersion : readInstalledEngineVersion(binary);
+    const summerDir = options.summerDir ?? getSummerDir();
+    const stamp = binaryStamp(binary);
+    if (stamp) {
+        const cached = readProbeCache(summerDir).binaries[binary];
+        if (cached && cached.mtimeMs === stamp.mtimeMs && cached.size === stamp.size) {
+            return backgroundLaunchSupport(version, cached.listsBackgroundFlag);
+        }
+    }
+    const probe = options.probe ?? ((path) => probeBackgroundLaunchSupport(path));
+    const answer = await probe(binary);
+    if (answer !== null && stamp) {
+        writeProbeCache(summerDir, binary, { ...stamp, listsBackgroundFlag: answer, probedAt: options.now ?? Date.now() });
+    }
+    return backgroundLaunchSupport(version, answer);
+}
+/**
+ * The running engine's own word, once it is up: /api/health
+ * `capabilities.launchPostures` (engine tool_net_thread.cpp, newer builds;
+ * "focus" always, "background" / "offscreen" only where enforced). true /
+ * false when advertised, null when the engine predates the advert.
+ */
+export function advertisedBackgroundPosture(capabilities) {
+    const postures = capabilities?.launchPostures;
+    if (!postures)
+        return null;
+    return postures.includes("background");
+}
+/** The launch decision: which flags to pass and what to tell the caller. */
+export function planLaunch(posture, support) {
+    if (posture === "focus") {
+        return { posture, extraArgs: [], background: false, note: null };
+    }
+    if (support.supported) {
+        return { posture, extraArgs: [BACKGROUND_LAUNCH_FLAG], background: true, note: null };
+    }
+    const which = support.version ? `Summer Engine ${support.version}` : "this Summer Engine build";
+    const note = support.reason === "engine_too_old"
+        ? support.source === "help_probe"
+            ? `Background launch requested, but ${which} cannot launch without taking focus (its --help does not list ${BACKGROUND_LAUNCH_FLAG}); launching with focus. Update Summer Engine (summer install) for background launches.`
+            : `Background launch requested, but ${which} could not be probed (--help) and its version predates ${BACKGROUND_LAUNCH_MIN_ENGINE_VERSION}, so it most likely cannot launch without taking focus; launching with focus. Update Summer Engine (summer install) for background launches.`
+        : `Background launch requested, but the installed Summer Engine could not be probed (--help) and its version could not be read before launch, so the toolkit cannot tell whether it supports ${BACKGROUND_LAUNCH_FLAG}; launching with focus.`;
+    return { posture, extraArgs: [], background: false, note };
+}
+// ---------------------------------------------------------------------------
+// Installed engine version, read BEFORE launch (no engine to ask)
+// ---------------------------------------------------------------------------
+/** CFBundleShortVersionString out of a macOS Info.plist. */
+export function parseMacBundleVersion(plistText) {
+    const match = plistText.match(/<key>CFBundleShortVersionString<\/key>\s*<string>([^<]+)<\/string>/);
+    return match ? match[1].trim() : null;
+}
+/** Version string of an installed macOS bundle, or null when unreadable. */
+export function readMacBundleVersion(appPath) {
+    try {
+        return parseMacBundleVersion(readFileSync(join(appPath, "Contents", "Info.plist"), "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** `<version>` out of a Velopack `sq.version` file (the nuspec Velopack drops
+ *  next to the current binary on Windows). Best effort: any other shape reads
+ *  as unknown. */
+export function parseVelopackVersion(sqVersionText) {
+    const match = sqVersionText.match(/<version>\s*([^<\s]+)\s*<\/version>/i);
+    return match ? match[1].trim() : null;
+}
+/** Walk up from `.../Summer.app/Contents/MacOS/Summer` to the bundle. */
+function macBundlePathFor(binary) {
+    let current = dirname(binary);
+    for (let depth = 0; depth < 4; depth++) {
+        if (basename(current).endsWith(".app"))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+/**
+ * Installed engine version for a resolved engine binary, or null. macOS reads
+ * the bundle's Info.plist; Windows reads Velopack's sq.version beside the exe;
+ * Linux has no version source today and always reads null.
+ */
+export function readInstalledEngineVersion(binary, os = platform()) {
+    if (os === "darwin") {
+        const bundle = macBundlePathFor(binary);
+        return bundle ? readMacBundleVersion(bundle) : null;
+    }
+    if (os === "win32") {
+        try {
+            return parseVelopackVersion(readFileSync(join(dirname(binary), "sq.version"), "utf-8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}

package/dist/core/library-read.d.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { type LibrarySearchDeps } from "./library-search.js";
+import { type TemplateEntry } from "./templates.js";
+export declare const READ_PARTS: readonly ["skill", "resource", "all"];
+export type ReadPart = (typeof READ_PARTS)[number];
+/** How many content_hash hex chars the footer's entry_id carries. */
+export declare const FOOTER_HASH_LENGTH = 12;
+export declare const FOOTER_SUFFIX = "If this entry is wrong, stale, or you deviate from it, report via summer_library_feedback.";
+export declare const readLibraryInputShape: {
+    id: z.ZodString;
+    part: z.ZodOptional<z.ZodEnum<["skill", "resource", "all"]>>;
+};
+export declare const readLibraryInputSchema: z.ZodObject<{
+    id: z.ZodString;
+    part: z.ZodOptional<z.ZodEnum<["skill", "resource", "all"]>>;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    part?: "all" | "skill" | "resource" | undefined;
+}, {
+    id: string;
+    part?: "all" | "skill" | "resource" | undefined;
+}>;
+export type ReadLibraryArgs = z.infer<typeof readLibraryInputSchema>;
+export interface LibraryReadDeps extends LibrarySearchDeps {
+    /** Root holding library/ (default: the installed package). */
+    packageRoot?: string;
+    templates?: readonly TemplateEntry[];
+}
+export interface LibraryReadOk {
+    ok: true;
+    id: string;
+    kind: string;
+    slug: string;
+    version: string;
+    status: string;
+    content_hash: string;
+    summary: string;
+    use_when: string[];
+    related: Record<string, string[]>;
+    part: ReadPart;
+    /** Package-root-relative resource directory, e.g. "library/skills/<slug>". */
+    path: string;
+    /** Top-level files in the resource directory. */
+    files: string[];
+    /** The file the body came from, when the body is a file. */
+    body_file?: string;
+    /** Tool records: how to reach it. */
+    mcp_tool_name?: string;
+    cli_command?: string;
+    remote?: boolean;
+    authority?: Record<string, boolean>;
+    /** The id to report with (id@hash12); also the last line's subject. */
+    entry_id: string;
+    footer: string;
+    /** The full load as the agent should read it; `footer` is its last line. */
+    text: string;
+}
+export interface LibraryReadNotFound {
+    ok: false;
+    error: "not_found";
+    id: string;
+    nearest: string[];
+    hint: string;
+}
+export type LibraryReadResult = LibraryReadOk | LibraryReadNotFound;
+/** The feedback footer for an entry; `hash` may be empty for a hash-less index. */
+export declare function feedbackFooter(id: string, contentHash: string | undefined): string;
+export declare function entryIdWithHash(id: string, contentHash: string | undefined): string;
+/**
+ * Read one entry. `deps.entries`/`deps.packageRoot`/`deps.templates` let
+ * tests point at a fixture; production reads the installed package.
+ */
+export declare function readLibraryEntry(requestedId: string, part?: ReadPart, deps?: LibraryReadDeps): Promise<LibraryReadResult>;

package/dist/core/library-read.js

@@ -0,0 +1,279 @@
+/**
+ * Library read — the runtime librarian's second half.
+ *
+ * `readLibraryEntry(id, part)` loads one entry from the library shipped under
+ * PACKAGE_ROOT and renders it for an agent:
+ *
+ *   skill      SKILL.md body + metadata (status, use_when, related) + how to
+ *              invoke it in the host (bare slug)
+ *   tool       how to call it (MCP name, `summer tool <slug> --args`, engine
+ *              requirement, authority) + the descriptor (resource.yaml)
+ *   template   the pin (repo @ commit, tree digest) or "built-in" + the
+ *              `summer create <slug>` command
+ *   reference  the markdown body
+ *   example / collection   README.md / collection.yaml when present
+ *
+ * The LAST line of every load is the feedback footer
+ * (SELF_IMPROVING_LIBRARY.md §3.1 "trigger placement"):
+ *   — entry_id: <id>@<content_hash first 12>. If this entry is wrong, stale,
+ *   or you deviate from it, report via summer_library_feedback.
+ * The agent copies that entry_id verbatim into summer_library_feedback, so
+ * feedback attributes to the exact bytes it used (CONTRACT §4).
+ *
+ * Metadata comes from registry/generated/index.json (no YAML parser at
+ * runtime); resource.yaml is returned as text. Unknown id -> not_found with
+ * the three nearest ids from searchLibrary.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { LIBRARY_KIND_DIRS, loadLibraryIndex, searchLibrary, } from "./library-search.js";
+import { PACKAGE_ROOT } from "./package-root.js";
+import { getTemplateRegistry } from "./templates.js";
+export const READ_PARTS = ["skill", "resource", "all"];
+/** How many content_hash hex chars the footer's entry_id carries. */
+export const FOOTER_HASH_LENGTH = 12;
+export const FOOTER_SUFFIX = "If this entry is wrong, stale, or you deviate from it, report via summer_library_feedback.";
+export const readLibraryInputShape = {
+    id: z
+        .string()
+        .min(1)
+        .max(200)
+        .describe("The entry id as returned by summer_search_library: <kind>/<slug>, e.g. skill/vfx-water-ripple or tool/screenshot."),
+    part: z
+        .enum(READ_PARTS)
+        .optional()
+        .describe("'skill' = the body only (SKILL.md for skills; the markdown body for references; how-to-call for tools; the pin for templates). 'resource' = the resource.yaml descriptor only. 'all' (default) = both."),
+};
+export const readLibraryInputSchema = z.object(readLibraryInputShape).strict();
+/** The feedback footer for an entry; `hash` may be empty for a hash-less index. */
+export function feedbackFooter(id, contentHash) {
+    return `— entry_id: ${entryIdWithHash(id, contentHash)}. ${FOOTER_SUFFIX}`;
+}
+export function entryIdWithHash(id, contentHash) {
+    const hash = typeof contentHash === "string" ? contentHash.slice(0, FOOTER_HASH_LENGTH) : "";
+    return hash ? `${id}@${hash}` : id;
+}
+// ── Resolution ─────────────────────────────────────────────────────────────
+/** Exact id, an id with an @hash suffix (as the footer prints it), or a bare
+ *  slug that names exactly one entry. */
+function resolveEntry(requested, entries) {
+    const bare = requested.trim().replace(/@[a-f0-9]+$/i, "");
+    if (!bare)
+        return null;
+    const exact = entries.find((entry) => entry.id === bare);
+    if (exact)
+        return exact;
+    if (!bare.includes("/")) {
+        const bySlug = entries.filter((entry) => entry.id.split("/").pop() === bare);
+        if (bySlug.length === 1)
+            return bySlug[0];
+    }
+    return null;
+}
+// ── Rendering ──────────────────────────────────────────────────────────────
+function readText(file) {
+    try {
+        return existsSync(file) && statSync(file).isFile() ? readFileSync(file, "utf-8") : null;
+    }
+    catch {
+        return null;
+    }
+}
+function listFiles(dir) {
+    try {
+        return readdirSync(dir).sort();
+    }
+    catch {
+        return [];
+    }
+}
+function pickBodyFile(kind, slug, dir) {
+    const files = listFiles(dir);
+    const has = (name) => files.includes(name);
+    switch (kind) {
+        case "skill":
+            return has("SKILL.md") ? "SKILL.md" : null;
+        case "reference": {
+            if (has(`${slug}.md`))
+                return `${slug}.md`;
+            return files.find((f) => f.toLowerCase().endsWith(".md")) ?? null;
+        }
+        case "example":
+            return has("README.md") ? "README.md" : null;
+        case "collection":
+            if (has("README.md"))
+                return "README.md";
+            return has("collection.yaml") ? "collection.yaml" : null;
+        default:
+            return null;
+    }
+}
+function toolBody(entry, slug) {
+    const lines = [];
+    const mcpName = entry.mcp_tool_name ?? `summer_${slug.replace(/-/g, "_")}`;
+    lines.push(`MCP: call \`${mcpName}\` with arguments matching input_schema (in resource.yaml below).`);
+    lines.push(`Shell: summer tool ${slug} --args '<json matching input_schema>'`);
+    if (entry.cli_command)
+        lines.push(`Dedicated command: ${entry.cli_command}`);
+    lines.push(entry.remote === true
+        ? "Engine: not required (remote: true — works without a running Summer Engine)."
+        : "Engine: required — Summer Engine must be running with the project open (start it with `summer run`).");
+    if (entry.authority) {
+        const granted = Object.entries(entry.authority)
+            .filter(([, on]) => on === true)
+            .map(([name]) => name);
+        lines.push(`Authority: ${granted.length > 0 ? granted.join(", ") : "none (read-only)"}.`);
+    }
+    return lines.join("\n");
+}
+function templateBody(slug, templates) {
+    const template = templates.find((t) => t.slug === slug);
+    const lines = [];
+    if (!template) {
+        lines.push("Pin: not present in registry/generated/templates-registry.json (regenerate the registry).");
+    }
+    else if (template.builtin) {
+        lines.push("Built-in template: generated locally by `summer create`, nothing is downloaded.");
+    }
+    else if (template.pin) {
+        lines.push(`Pinned to ${template.pin.repo} @ ${template.pin.commit}`);
+        lines.push(`tree_digest: ${template.pin.tree_digest} (verified after fetch; mismatch writes nothing)`);
+    }
+    if (template && template.systems.length > 0)
+        lines.push(`Systems: ${template.systems.join(", ")}`);
+    if (template && template.do_not_use_when.length > 0) {
+        lines.push("Do not use when:");
+        for (const line of template.do_not_use_when)
+            lines.push(`  - ${line}`);
+    }
+    lines.push(`Create a project from it: summer create ${slug} [name]   (records the pin into .summer/project.json)`);
+    return lines.join("\n");
+}
+function relatedMap(entry) {
+    const out = {};
+    for (const [group, ids] of Object.entries(entry.related ?? {})) {
+        if (Array.isArray(ids) && ids.length > 0)
+            out[group] = [...ids];
+    }
+    return out;
+}
+function header(entry, slug, related) {
+    const lines = [];
+    lines.push(`${entry.id} — ${entry.kind} v${entry.version ?? "?"} (${entry.status ?? "stable"})`);
+    if (entry.summary)
+        lines.push(entry.summary);
+    const useWhen = Array.isArray(entry.use_when) ? entry.use_when : [];
+    if (useWhen.length > 0) {
+        lines.push("use_when:");
+        for (const line of useWhen)
+            lines.push(`  - ${line}`);
+    }
+    const relatedIds = Object.values(related).flat();
+    if (relatedIds.length > 0)
+        lines.push(`related: ${relatedIds.join(", ")}`);
+    if (entry.kind === "skill") {
+        lines.push(`Invoke: the \`${slug}\` skill in your host (Claude Code: /${slug}); installed under its bare slug by \`summer setup\`. The body follows — follow it, do not paraphrase it.`);
+    }
+    return lines.join("\n");
+}
+// ── Entry point ────────────────────────────────────────────────────────────
+/**
+ * Read one entry. `deps.entries`/`deps.packageRoot`/`deps.templates` let
+ * tests point at a fixture; production reads the installed package.
+ */
+export async function readLibraryEntry(requestedId, part = "all", deps = {}) {
+    const entries = deps.entries ?? loadLibraryIndex();
+    const root = deps.packageRoot ?? PACKAGE_ROOT;
+    const entry = resolveEntry(requestedId, entries);
+    if (!entry) {
+        const query = requestedId.replace(/[/@_-]+/g, " ").replace(/[a-f0-9]{8,}/gi, " ").trim() || requestedId;
+        const nearest = (await searchLibrary(query, { limit: 3 }, deps)).map((hit) => hit.id);
+        return {
+            ok: false,
+            error: "not_found",
+            id: requestedId,
+            nearest,
+            hint: nearest.length > 0
+                ? `No library entry has id "${requestedId}". Nearest by search: ${nearest.join(", ")}. Ids are <kind>/<slug>; use summer_search_library to find the right one.`
+                : `No library entry has id "${requestedId}" and nothing similar was found. Ids are <kind>/<slug>; use summer_search_library.`,
+        };
+    }
+    const kind = entry.kind;
+    const slug = entry.id.split("/").pop();
+    const kindDir = LIBRARY_KIND_DIRS[kind] ?? `${kind}s`;
+    const relPath = `library/${kindDir}/${slug}`;
+    const dir = join(root, "library", kindDir, slug);
+    const files = listFiles(dir);
+    const related = relatedMap(entry);
+    let bodyFile;
+    let bodyTitle;
+    let body;
+    if (kind === "tool") {
+        bodyTitle = "how to call";
+        body = toolBody(entry, slug);
+    }
+    else if (kind === "template") {
+        bodyTitle = "pin";
+        body = templateBody(slug, deps.templates ?? safeTemplates());
+    }
+    else {
+        const picked = pickBodyFile(kind, slug, dir);
+        const text = picked ? readText(join(dir, picked)) : null;
+        if (picked && text !== null) {
+            bodyFile = picked;
+            bodyTitle = `${relPath}/${picked}`;
+            body = text.replace(/\s+$/, "");
+        }
+        else {
+            bodyTitle = "body";
+            body = `(no body file shipped for this ${kind}; the descriptor below is all there is)`;
+        }
+    }
+    const resourceYaml = readText(join(dir, "resource.yaml"))?.replace(/\s+$/, "") ?? "(resource.yaml not found in this install)";
+    const footer = feedbackFooter(entry.id, entry.content_hash);
+    const sections = [header(entry, slug, related)];
+    if (part === "skill" || part === "all")
+        sections.push(`--- ${bodyTitle} ---\n${body}`);
+    if (part === "resource" || part === "all")
+        sections.push(`--- ${relPath}/resource.yaml ---\n${resourceYaml}`);
+    sections.push(footer);
+    const result = {
+        ok: true,
+        id: entry.id,
+        kind: entry.kind,
+        slug,
+        version: entry.version ?? "",
+        status: entry.status ?? "stable",
+        content_hash: entry.content_hash ?? "",
+        summary: entry.summary ?? "",
+        use_when: Array.isArray(entry.use_when) ? entry.use_when : [],
+        related,
+        part,
+        path: relPath,
+        files,
+        entry_id: entryIdWithHash(entry.id, entry.content_hash),
+        footer,
+        text: sections.join("\n\n"),
+    };
+    if (bodyFile)
+        result.body_file = bodyFile;
+    if (kind === "tool") {
+        if (entry.mcp_tool_name)
+            result.mcp_tool_name = entry.mcp_tool_name;
+        if (entry.cli_command)
+            result.cli_command = entry.cli_command;
+        result.remote = entry.remote === true;
+        if (entry.authority)
+            result.authority = entry.authority;
+    }
+    return result;
+}
+function safeTemplates() {
+    try {
+        return getTemplateRegistry();
+    }
+    catch {
+        return [];
+    }
+}