@seojin08/skill-finder 0.0.0-stage → 0.3.3

package/server/src/indexer.js

@@ -0,0 +1,502 @@
+import { createHash } from 'node:crypto';
+import { extractSkillMeta } from "./analyze/frontmatter.js";
+import { qualityWarnings } from "./analyze/quality.js";
+import { pluginRiskFlags, RISK_RULES_VERSION, riskLevel, skillRiskFlags, TEXT_RISK_FLAGS } from "./analyze/risk.js";
+import { discoverRepo, parseJsonObject, PLUGIN_JSON } from "./discovery/classifyRepo.js";
+import { genericAcceptor } from "./discovery/genericRules.js";
+import { discoverPluginSkills } from "./discovery/pluginRules.js";
+import { basename, joinPath, skillMdPath, TreeIndex } from "./discovery/tree.js";
+import { RAW_MAX_BYTES } from "./sources/github.js";
+import { normalizeSource, resolveRelativeRoot } from "./sources/pluginSource.js";
+import { pool } from "./util/limiter.js";
+import { sanitizeText } from "./util/sanitize.js";
+import { SizedCache } from "./util/sizedCache.js";
+/**
+ * The marketplace entry points at something that is not there (deleted/private repo, a pinned commit
+ * erased from history, a folder that does not exist). Claude Code could not install it either; it is
+ * recorded as 설치 불가 and not retried until the marketplace changes the entry.
+ */
+export class PluginUnavailableError extends Error {
+}
+const sha256 = (s) => createHash('sha256').update(s).digest('hex');
+const now = () => new Date().toISOString();
+const MAX_FILES_STORED = 500;
+export const skillId = (repo, dirPath) => `gh:${repo.toLowerCase()}:${dirPath}`;
+export function normalizeSkillName(name) {
+    return name.toLowerCase().replace(/[\s_]+/g, '-');
+}
+/** The validator used in generic mode: name and description must be non-empty strings (skills CLI rule). */
+export function genericValidator(raw) {
+    const meta = extractSkillMeta(raw, '');
+    if (!meta.nameFromFrontmatter || !meta.descriptionFromFrontmatter)
+        return null;
+    const internal = meta.frontmatter.metadata?.internal === true;
+    return internal ? null : { name: meta.nameFromFrontmatter, description: meta.descriptionFromFrontmatter };
+}
+export function buildSkillRow(a) {
+    const folderName = a.dirPath ? basename(a.dirPath) : (a.repo.split('/')[1] ?? '');
+    const meta = extractSkillMeta(a.raw, folderName);
+    const files = a.tree.filesUnder(a.dirPath);
+    const relPaths = files.map((f) => f.path);
+    const flags = [
+        ...new Set([
+            ...skillRiskFlags({
+                files: relPaths,
+                allowedTools: meta.allowedTools,
+                body: meta.body,
+                hasHooks: meta.hasHooks,
+                raw: a.raw,
+                partial: checkedInPart(meta, a.raw),
+            }),
+            ...a.extraFlags,
+        ]),
+    ];
+    const stored = {
+        files: files.slice(0, MAX_FILES_STORED).map((f) => ({ path: f.path, size: f.size })),
+        total: files.length,
+    };
+    return {
+        id: skillId(a.repo, a.dirPath),
+        origin: a.origin,
+        plugin_id: a.pluginId,
+        repo: a.repo,
+        ref: a.sha,
+        dir_path: a.dirPath,
+        name: meta.name || folderName,
+        description: meta.description || null,
+        when_to_use: meta.whenToUse,
+        frontmatter_json: JSON.stringify(meta.frontmatter),
+        body_lines: meta.bodyLines,
+        skill_md_sha256: sha256(a.raw.replace(/\r\n/g, '\n')),
+        name_desc_sha256: sha256(`${meta.name}\n${meta.description}`),
+        installs: null,
+        quality_json: JSON.stringify(qualityWarnings(meta, folderName)),
+        risk_json: JSON.stringify(flags),
+        risk_level: riskLevel(flags),
+        risk_rules: RISK_RULES_VERSION,
+        last_commit_at: a.lastCommitAt,
+        fetched_at: now(),
+        files_json: JSON.stringify(stored),
+        install_json: a.install ? JSON.stringify(a.install) : null,
+    };
+}
+/** A download cut at the limit (a split multi-byte character at the end costs at most 3 bytes), or a frontmatter too large to parse. */
+const checkedInPart = (meta, raw) => meta.frontmatterTooLarge || Buffer.byteLength(raw) >= RAW_MAX_BYTES - 3;
+/**
+ * A stored row's risk under the current rules, from its SKILL.md text: the text flags are computed again, the
+ * others (scripts from the file list, the plugin's own flags) are kept. Null when `raw` is not the file the row
+ * was built from (its hash differs), so nothing is judged on another version of the skill.
+ */
+export function recheckRisk(row, raw) {
+    if (!row.skill_md_sha256 || sha256(raw.replace(/\r\n/g, '\n')) !== row.skill_md_sha256)
+        return null;
+    const folderName = row.dir_path ? basename(row.dir_path) : (row.repo?.split('/')[1] ?? '');
+    const meta = extractSkillMeta(raw, folderName);
+    const fromText = skillRiskFlags({ files: [], allowedTools: meta.allowedTools, body: meta.body, hasHooks: meta.hasHooks, raw, partial: checkedInPart(meta, raw) });
+    const old = (row.risk_json ? JSON.parse(row.risk_json) : []);
+    // the stored order is kept, so a row whose flags did not change is stored exactly as before
+    const flags = [...old.filter((f) => !TEXT_RISK_FLAGS.has(f) || fromText.includes(f)), ...fromText.filter((f) => !old.includes(f))];
+    return { risk_json: JSON.stringify(flags), risk_level: riskLevel(flags) };
+}
+export function pluginFtsText(p) {
+    if (!p)
+        return '';
+    return [p.name, p.display_name, p.description, p.category, p.keywords].filter(Boolean).join(' ');
+}
+/** Rows written per transaction when a whole repo is indexed. */
+const WRITE_BATCH = 50;
+const RUN_CONFIG_MAX_CHARS = 16_000;
+export class Indexer {
+    store;
+    github;
+    /** Bounded by tree entries (perf debate 1-3): a lookup holds its tree and the SKILL.md texts read, ~770B each. */
+    discoveryCache = new SizedCache({ maxSize: 60_000, ttlMs: 10 * 60 * 1000, sizeOf: (l) => l.snap.index.files.size });
+    constructor(store, github) {
+        this.store = store;
+        this.github = github;
+    }
+    async snapshot(repo, sha) {
+        const tree = sha === 'HEAD' ? await this.github.getTreeAtHead(repo) : await this.github.getTree(repo, sha);
+        sha = tree.sha;
+        const index = new TreeIndex(tree.entries);
+        const memo = new Map();
+        // null only means "not there" (not in the tree, or a 404). A failed download throws, so a busy
+        // GitHub is never mistaken for a missing SKILL.md (that used to drop real skills from results).
+        const read = (path) => {
+            let p = memo.get(path);
+            if (!p) {
+                p = index.hasFile(path)
+                    ? this.github.getRawText(repo, sha, path).then((r) => {
+                        if (r.text != null || r.status === 404)
+                            return r.text;
+                        throw new Error(`${repo}/${path} 읽기 실패 (${r.status})`);
+                    })
+                    : Promise.resolve(null);
+                p.catch(() => memo.delete(path));
+                memo.set(path, p);
+            }
+            return p;
+        };
+        return { tree, index, read };
+    }
+    async lastCommitAt(repo, tree) {
+        const meta = await this.github.getRepoMeta(repo).catch(() => null);
+        return meta?.pushed_at ?? tree.commitDate;
+    }
+    /** A GitHub plugin's marketplace entry, commit, tree, folder and plugin.json, as the index reads them. */
+    async openPlugin(plugin) {
+        const repo = plugin.repo;
+        const stored = (plugin.entry_json ? JSON.parse(plugin.entry_json) : null);
+        const entry = stored?.entry ?? { name: plugin.name, source: JSON.parse(plugin.source_json) };
+        const src = normalizeSource(entry.source, stored?.pluginRoot);
+        const sha = plugin.sha ?? (await this.github.resolveRef(repo, plugin.ref))?.sha;
+        if (!sha)
+            throw new Error('커밋을 찾을 수 없습니다');
+        const snap = await this.snapshot(repo, sha);
+        const root = src.kind === 'relative' ? resolveRelativeRoot(src.raw, stored?.pluginRoot ?? null, snap.index) : (plugin.path ?? '');
+        if (root == null || !snap.index.hasDir(root))
+            throw new Error(`플러그인 경로가 없습니다: ${root ?? '?'}`);
+        const manifestPath = joinPath(root, PLUGIN_JSON);
+        const manifest = snap.index.hasFile(manifestPath) ? parseJsonObject(await snap.read(manifestPath)) : null;
+        return { entry, src, sha, snap, root, manifest };
+    }
+    /**
+     * What a plugin runs once installed, as written in it (project review F1): its hooks, MCP servers, monitors and
+     * bin/ files, from hooks/hooks.json, .mcp.json, monitors/monitors.json, plugin.json and the marketplace entry.
+     * Only read and shown; nothing here is run.
+     */
+    async pluginRunConfig(pluginId) {
+        const plugin = this.store.getPlugin(pluginId);
+        if (!plugin?.repo)
+            throw new Error('GitHub에 있는 플러그인이 아니라 읽을 수 없습니다');
+        const { entry, sha, snap, root, manifest } = await this.openPlugin(plugin);
+        const items = [];
+        const show = (kind, source, value) => {
+            const text = sanitizeText(typeof value === 'string' ? value : JSON.stringify(value, null, 2));
+            items.push({ kind, source, text: text.slice(0, RUN_CONFIG_MAX_CHARS), truncated: text.length > RUN_CONFIG_MAX_CHARS });
+        };
+        const readFile = async (kind, rel) => {
+            const path = joinPath(root, rel.replace(/^\.\//, ''));
+            const text = await snap.read(path).catch(() => null);
+            if (text != null)
+                show(kind, path, text);
+        };
+        // a component field is inline config, or a path (or paths) to it inside the plugin
+        const fromField = async (kind, field, source) => {
+            if (field == null)
+                return;
+            if (typeof field === 'string')
+                await readFile(kind, field);
+            else if (Array.isArray(field) && field.every((f) => typeof f === 'string'))
+                for (const f of field)
+                    await readFile(kind, f);
+            else
+                show(kind, source, field);
+        };
+        const manifestPath = joinPath(root, PLUGIN_JSON);
+        if (snap.index.hasFile(joinPath(root, 'hooks/hooks.json')))
+            await readFile('hooks', 'hooks/hooks.json');
+        await fromField('hooks', manifest?.hooks, `${manifestPath} hooks`);
+        await fromField('hooks', entry.hooks, 'marketplace.json hooks');
+        if (snap.index.hasFile(joinPath(root, '.mcp.json')))
+            await readFile('mcp', '.mcp.json');
+        await fromField('mcp', manifest?.mcpServers, `${manifestPath} mcpServers`);
+        await fromField('mcp', entry.mcpServers, 'marketplace.json mcpServers');
+        if (snap.index.hasFile(joinPath(root, 'monitors/monitors.json')))
+            await readFile('monitors', 'monitors/monitors.json');
+        await fromField('monitors', manifest?.monitors, `${manifestPath} monitors`);
+        const bin = [...snap.index.files.keys()].filter((f) => f.startsWith(joinPath(root, 'bin') + '/'));
+        if (bin.length)
+            show('bin', joinPath(root, 'bin'), bin.slice(0, 50).join('\n') + (bin.length > 50 ? `\n… 외 ${bin.length - 50}개` : ''));
+        return { commit: sha, items };
+    }
+    /** Indexes the skills of one marketplace plugin; replaces its previous skill rows. Returns the skill count. */
+    async indexPlugin(pluginId) {
+        const plugin = this.store.getPlugin(pluginId);
+        if (!plugin)
+            throw new Error(`unknown plugin ${pluginId}`);
+        if (!plugin.repo) {
+            this.store.markPluginIndexed(pluginId, null, null, 'GitHub 외 출처라 스킬을 색인하지 않습니다');
+            return 0;
+        }
+        try {
+            const { entry, src, sha, snap, root, manifest } = await this.openPlugin(plugin);
+            const d = discoverPluginSkills(snap.index, root, manifest, entry, {
+                entryAtMarketplaceRoot: src.kind === 'relative' && root === '',
+            });
+            const extraFlags = pluginRiskFlags(d.signals, plugin.source_kind);
+            const lastCommitAt = await this.lastCommitAt(plugin.repo, snap.tree);
+            const results = await pool(d.skillDirs, 8, async (dirPath) => {
+                const raw = await snap.read(skillMdPath(dirPath));
+                if (raw == null)
+                    return null;
+                return buildSkillRow({
+                    repo: plugin.repo,
+                    sha,
+                    dirPath,
+                    raw,
+                    tree: snap.index,
+                    origin: 'plugin',
+                    pluginId,
+                    extraFlags,
+                    install: null,
+                    lastCommitAt,
+                });
+            });
+            const rows = results.flatMap((r) => (r?.ok && r.value ? [r.value] : []));
+            // A SKILL.md that could not be downloaded (busy GitHub) is not a removed skill: its old row stays, and no
+            // commit is recorded so the next sync reads the plugin again. Dropping it hid a high-risk sibling from the
+            // plugin-wide warning until the plugin changed (project review 2026-11-02), as indexRepo already avoids.
+            const failed = results.filter((r) => !r?.ok).length;
+            const text = pluginFtsText(plugin);
+            this.store.transaction(() => {
+                const keep = new Set(rows.map((r) => r.id));
+                if (!failed)
+                    for (const old of this.store.listSkillsByPlugin(pluginId))
+                        if (!keep.has(old.id))
+                            this.store.deleteSkill(old.id);
+                for (const row of rows)
+                    this.store.upsertSkill(row, text);
+                this.store.markPluginIndexed(pluginId, failed ? null : (plugin.sha ?? sha), { ...d.signals, strictConflict: d.strictConflict }, failed ? `SKILL.md ${failed}개를 읽지 못해 다음 동기화 때 다시 읽습니다` : null);
+            });
+            return rows.length;
+        }
+        catch (err) {
+            const reason = await this.unavailableReason(plugin.repo, err);
+            if (reason) {
+                // Indexed "as of" the marketplace's pinned commit, so it is skipped until the entry changes (an unpinned
+                // entry is read again every sync, like a working one).
+                this.store.markPluginIndexed(pluginId, plugin.sha, null, `설치 불가: ${reason}`);
+                throw new PluginUnavailableError(reason);
+            }
+            // No indexed sha → the next sync retries it.
+            this.store.markPluginIndexed(pluginId, null, null, String(err.message ?? err).slice(0, 300));
+            throw err;
+        }
+    }
+    /** Why a plugin can never be indexed as listed, or null for failures worth retrying (network, quota). */
+    async unavailableReason(repo, err) {
+        const msg = String(err?.message ?? err);
+        const path = msg.match(/^플러그인 경로가 없습니다: (.*)$/);
+        if (path)
+            return `마켓플레이스가 가리키는 폴더가 저장소에 없습니다 (${path[1]})`;
+        if (/^tree 422|^tree 409/.test(msg))
+            return '마켓플레이스가 고정한 커밋이 저장소 기록에서 지워졌습니다';
+        if (/^tree 404|커밋을 찾을 수 없습니다/.test(msg)) {
+            const exists = await this.github.repoExists(repo);
+            if (exists === false)
+                return '저장소가 삭제됐거나 비공개입니다';
+            if (exists === true && msg.startsWith('tree 404'))
+                return '마켓플레이스가 고정한 커밋이 저장소에 없습니다';
+        }
+        return null;
+    }
+    /**
+     * A repo at its default branch head, prepared for single-skill lookups; memoized for 10 minutes.
+     * Plugin layouts come from the manifests; generic folders are judged one at a time on demand.
+     */
+    discoverAtHead(repo) {
+        const key = repo.toLowerCase();
+        let p = this.discoveryCache.get(key);
+        if (!p) {
+            p = (async () => {
+                void this.github.getRepoMeta(repo).catch(() => null); // needed for the row's last commit; fetch alongside the tree
+                const snap = await this.snapshot(repo, 'HEAD');
+                const discovery = await discoverRepo(snap.index, snap.read, genericValidator, { genericSkills: false });
+                return { snap, discovery, generic: genericAcceptor(snap.index, snap.read, genericValidator) };
+            })();
+            this.discoveryCache.set(key, p);
+        }
+        return p;
+    }
+    async rowFromDiscovery(repo, snap, discovery, dirPath, raw) {
+        const b = await this.buildFromDiscovery(repo, snap, discovery, dirPath, raw);
+        if ('existing' in b)
+            return b.existing;
+        this.store.upsertSkill(b.row, b.text);
+        return this.store.getSkill(b.row.id);
+    }
+    /** The row for one discovered folder, unwritten; or the marketplace-indexed row already there, which wins. */
+    async buildFromDiscovery(repo, snap, discovery, dirPath, raw) {
+        const plugin = discovery.plugins.find((p) => p.skillDirs.includes(dirPath)) ?? null;
+        const install = {
+            mode: discovery.mode,
+            marketplaceName: discovery.marketplaceName,
+            marketplaceRepo: repo,
+            pluginName: plugin?.name || null,
+            signals: plugin?.signals ?? null,
+        };
+        const pluginRootDep = /\$\{?CLAUDE_PLUGIN_ROOT\}?/.test(raw);
+        const viaPlugin = pluginRootDep && !!discovery.marketplaceName && !!plugin?.name;
+        const row = buildSkillRow({
+            repo,
+            sha: snap.tree.sha,
+            dirPath,
+            raw,
+            tree: snap.index,
+            origin: 'generic',
+            pluginId: null,
+            extraFlags: viaPlugin ? pluginRiskFlags(plugin.signals) : [],
+            install,
+            lastCommitAt: await this.lastCommitAt(repo, snap.tree),
+        });
+        const existing = this.store.getSkill(row.id);
+        // A marketplace-indexed row for the same folder wins; only fill in what is new.
+        if (existing?.origin === 'plugin')
+            return { existing };
+        return { row, text: plugin ? `${plugin.name}` : '' };
+    }
+    /**
+     * SKILL.md text if `dir` is installable: listed by a marketplace plugin, or else by the skills CLI's
+     * generic rules (which is how `skills add --skill` would find it). null otherwise.
+     */
+    acceptDir(lookup, dir) {
+        if (lookup.discovery.plugins.some((p) => p.skillDirs.includes(dir)))
+            return lookup.snap.read(skillMdPath(dir));
+        return lookup.generic.accepts(dir);
+    }
+    /**
+     * Finds a skill in a repo by name or folder name (skills.sh hits). Folders named like the skill are read
+     * first (almost always the hit); the rest are read in small batches only if that fails.
+     * Returns null when the repo has no such installable skill; throws when GitHub could not be read.
+     */
+    async findInRepo(repo, name, folderHint) {
+        const lookup = await this.discoverAtHead(repo);
+        const want = new Set([normalizeSkillName(name), ...(folderHint ? [normalizeSkillName(folderHint)] : [])]);
+        const dirs = [...new Set([...lookup.discovery.plugins.flatMap((p) => p.skillDirs), ...lookup.generic.candidates])];
+        const byFolder = dirs.filter((d) => want.has(normalizeSkillName(basename(d || repo))));
+        const matches = (dir, raw, folderMatch) => {
+            const meta = extractSkillMeta(raw, basename(dir || repo));
+            return normalizeSkillName(meta.name) === normalizeSkillName(name) || (folderMatch && !meta.nameFromFrontmatter);
+        };
+        for (const dir of byFolder) {
+            const raw = await this.acceptDir(lookup, dir);
+            if (raw != null && matches(dir, raw, true))
+                return this.rowFromDiscovery(repo, lookup.snap, lookup.discovery, dir, raw);
+        }
+        // Folder named differently from the skill: read folders whose path shares a word with the name
+        // (or every folder in a small repo). Scanning hundreds of SKILL.md files for a name that is not
+        // there cost ~10s and almost never found anything.
+        const others = dirs.filter((d) => !byFolder.includes(d));
+        const words = normalizeSkillName(name)
+            .split(/[-.]+/)
+            .filter((w) => w.length >= 3);
+        const overlap = (d) => words.filter((w) => d.toLowerCase().includes(w)).length;
+        const rest = others.length <= 48
+            ? others
+            : others
+                .map((d) => ({ d, n: overlap(d) }))
+                .filter((x) => x.n > 0)
+                .sort((a, b) => b.n - a.n)
+                .slice(0, 48)
+                .map((x) => x.d);
+        for (let i = 0; i < rest.length; i += 24) {
+            const batch = rest.slice(i, i + 24);
+            const raws = await Promise.all(batch.map((d) => this.acceptDir(lookup, d)));
+            const hit = batch.findIndex((d, j) => raws[j] != null && matches(d, raws[j], false));
+            if (hit >= 0)
+                return this.rowFromDiscovery(repo, lookup.snap, lookup.discovery, batch[hit], raws[hit]);
+        }
+        return null;
+    }
+    /**
+     * Accepts a code-search hit only if a plugin or the generic rules list that folder (filters templates,
+     * examples, invalid SKILL.md). Returns null when not installable; throws when GitHub could not be read.
+     */
+    async findByPath(repo, skillMdFile) {
+        const dirPath = skillMdFile === 'SKILL.md' ? '' : skillMdFile.replace(/\/SKILL\.md$/, '');
+        const lookup = await this.discoverAtHead(repo);
+        if (!lookup.snap.index.hasFile(skillMdPath(dirPath)))
+            return null;
+        const raw = await this.acceptDir(lookup, dirPath);
+        return raw == null ? null : this.rowFromDiscovery(repo, lookup.snap, lookup.discovery, dirPath, raw);
+    }
+    /**
+     * Indexes every installable skill of one GitHub repo at its default branch (popular-repo collection):
+     * marketplace/plugin layouts by their manifests, otherwise the skills CLI's generic rules. Rows already
+     * indexed from a registered marketplace are left as they are.
+     * - `unchangedSince`: the head commit last indexed; when the head is still that commit nothing is read.
+     * - Rows are written 50 per transaction, yielding in between (20 autocommitted upserts took 111ms, one
+     *   transaction 4.9ms, and a big repo no longer holds the event loop while it is written).
+     * - After an index without failures, GitHub rows whose SKILL.md is no longer in the repo are deleted
+     *   (rows an install was logged for stay).
+     */
+    async indexRepo(repo, opts = {}) {
+        const head = await this.github.resolveRef(repo, null);
+        if (!head)
+            throw new Error(`저장소를 찾을 수 없습니다: ${repo}`);
+        if (opts.unchangedSince && head.sha === opts.unchangedSince)
+            return { skills: 0, sha: head.sha, unchanged: true, removed: 0 };
+        const snap = await this.snapshot(repo, head.sha);
+        if (!snap.tree.entries.some((e) => e.path === 'SKILL.md' || e.path.endsWith('/SKILL.md'))) {
+            return { skills: 0, sha: snap.tree.sha, unchanged: false, removed: this.removeVanished(repo, snap.index) };
+        }
+        const discovery = await discoverRepo(snap.index, snap.read, genericValidator);
+        const found = [
+            ...discovery.generic.map((g) => ({ dir: g.dirPath, raw: g.raw })),
+            ...[...new Set(discovery.plugins.flatMap((p) => p.skillDirs))].map((dir) => ({ dir, raw: null })),
+        ].slice(0, 500);
+        const built = await pool(found, 8, async ({ dir, raw }) => {
+            const text = raw ?? (await snap.read(skillMdPath(dir)));
+            return text == null ? null : this.buildFromDiscovery(repo, snap, discovery, dir, text);
+        });
+        const writes = built.flatMap((b) => (b?.ok && b.value && 'row' in b.value ? [b.value] : []));
+        for (let i = 0; i < writes.length; i += WRITE_BATCH) {
+            this.store.transaction(() => {
+                for (const w of writes.slice(i, i + WRITE_BATCH))
+                    this.store.upsertSkill(w.row, w.text);
+            });
+            await new Promise((resolve) => setImmediate(resolve));
+        }
+        const failed = built.some((b) => !b?.ok);
+        return {
+            skills: built.filter((b) => b?.ok && b.value).length,
+            sha: failed ? null : snap.tree.sha,
+            unchanged: false,
+            removed: failed ? 0 : this.removeVanished(repo, snap.index),
+        };
+    }
+    /** Deletes this repo's GitHub-indexed rows whose SKILL.md the (complete) tree no longer has. */
+    removeVanished(repo, index) {
+        const gone = this.store
+            .findSkillsByRepo(repo)
+            .filter((s) => s.origin === 'generic' && s.dir_path != null && !index.hasFile(skillMdPath(s.dir_path)))
+            .map((s) => s.id);
+        return gone.length ? this.store.deleteSkillsUnlessInstalled(gone) : 0;
+    }
+    /** Placeholder row for a skills.sh hit served from a well-known endpoint (no preview in the MVP). */
+    wellKnownRow(domain, name, installs) {
+        const row = {
+            id: `wk:${domain.toLowerCase()}:${name}`,
+            origin: 'wellknown',
+            plugin_id: null,
+            repo: null,
+            ref: null,
+            dir_path: null,
+            name,
+            description: null,
+            when_to_use: null,
+            frontmatter_json: null,
+            body_lines: null,
+            skill_md_sha256: null,
+            name_desc_sha256: null,
+            installs,
+            quality_json: '[]',
+            risk_json: '[]',
+            risk_level: 'low',
+            last_commit_at: null,
+            fetched_at: now(),
+            files_json: null,
+            install_json: JSON.stringify({ domain }),
+        };
+        this.store.upsertSkill(row, '');
+        return this.store.getSkill(row.id);
+    }
+    /** Fresh tree for a stored skill (detail view file listing / file reads). */
+    async treeFor(skill) {
+        if (!skill.repo || !skill.ref)
+            return null;
+        const tree = await this.github.getTree(skill.repo, skill.ref);
+        return new TreeIndex(tree.entries);
+    }
+}