@seojin08/skill-finder 0.0.0-stage → 0.3.3

package/server/src/search/rank.js

@@ -0,0 +1,138 @@
+import { COMMUNITY_MARKETPLACES, PARTNER_MARKETPLACES } from "../settings.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+const clamp01 = (x) => (Number.isFinite(x) ? Math.min(1, Math.max(0, x)) : 0);
+/** 1 within 90 days of the last commit, linearly down to 0 at 730 days; unknown → 0. */
+export function freshness(lastCommitAt, now = Date.now()) {
+    if (!lastCommitAt)
+        return 0;
+    const t = Date.parse(lastCommitAt);
+    if (Number.isNaN(t))
+        return 0;
+    const days = (now - t) / DAY_MS;
+    if (days <= 90)
+        return 1;
+    if (days >= 730)
+        return 0;
+    return clamp01(1 - (days - 90) / (730 - 90));
+}
+/**
+ * Installs when known (skill-level), else stars × 0.6 — stars are repo-level, and one repo can hold
+ * hundreds of skills, so they say little about a single skill.
+ */
+export function popularity(c, maxInstalls, maxStars) {
+    if (c.installs != null && c.installs > 0 && maxInstalls > 0)
+        return clamp01(Math.log10(1 + c.installs) / Math.log10(1 + maxInstalls));
+    if (c.stars != null && c.stars > 0 && maxStars > 0)
+        return clamp01((0.6 * Math.log10(1 + c.stars)) / Math.log10(1 + maxStars));
+    return 0;
+}
+/** Stored downloads older than this are not ranked on (U4, user decision): a copy no longer listed kept its count. */
+export const INSTALLS_MAX_AGE_MS = 30 * DAY_MS;
+/** A skill's stored downloads, or null when unknown or older than INSTALLS_MAX_AGE_MS. */
+export function freshInstalls(s, now = Date.now()) {
+    if (s.installs == null || !s.installs_at)
+        return null;
+    const t = Date.parse(s.installs_at);
+    return Number.isNaN(t) || now - t > INSTALLS_MAX_AGE_MS ? null : s.installs;
+}
+export function trustTier(skill, plugin) {
+    if (plugin && COMMUNITY_MARKETPLACES.has(plugin.marketplace))
+        return 'community';
+    const owner = skill.repo?.split('/')[0]?.toLowerCase();
+    if (owner === 'anthropics' && !skill.dir_path?.startsWith('external_plugins/'))
+        return 'official';
+    if (plugin && PARTNER_MARKETPLACES.has(plugin.marketplace))
+        return 'partner';
+    return 'other';
+}
+export const TRUST_SCORE = { official: 1.0, partner: 0.8, community: 0.6, other: 0.4 };
+export function totalScore(b, w) {
+    const sum = w.R + w.P + w.F + w.T;
+    if (sum <= 0)
+        return 0;
+    return (w.R * b.R + w.P * b.P + w.F * b.F + w.T * b.T) / sum;
+}
+/** Relevance from bm25 (lower = better in SQLite) normalized against the best hit. */
+export function bm25ToRelevance(bm25, best, worst) {
+    if (!Number.isFinite(bm25))
+        return 0;
+    if (best === worst)
+        return 1;
+    return clamp01(0.3 + 0.7 * ((worst - bm25) / (worst - best)));
+}
+const MATCH_STOPWORDS = new Set('a an the and or for to of in on with from by using use uses skill skills claude code tool tools that this is are be my your how what into as at it its via any can will should'.split(' '));
+/** Crude English stem so "extracting"/"extraction"/"extracts" and "tables"/"table" line up. */
+export function stem(word) {
+    let w = word.toLowerCase();
+    // plurals first: "boxes" → "box", "tables" → "table", "libraries" → "library"
+    if (w.length > 4 && w.endsWith('ies'))
+        w = w.slice(0, -3) + 'y';
+    else if (w.length > 4 && /(s|x|z|ch|sh)es$/.test(w))
+        w = w.slice(0, -2);
+    else if (w.length > 3 && w.endsWith('s') && !w.endsWith('ss'))
+        w = w.slice(0, -1);
+    for (const suffix of ['ation', 'ion', 'ing', 'er', 'ed']) {
+        if (w.length - suffix.length >= 3 && w.endsWith(suffix)) {
+            w = w.slice(0, -suffix.length);
+            break;
+        }
+    }
+    return w;
+}
+export function matchTokens(text) {
+    // A Latin word with a Korean ending attached ("pdf에서", "엑셀로") counts as the Latin word alone, as in ftsQuery.
+    const words = (text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? []).flatMap((t) => (/[a-z0-9]/.test(t) && /\p{Script=Hangul}/u.test(t) ? (t.match(/[a-z0-9]+/g) ?? []) : [t]));
+    return words.filter((t) => t.length >= 2 && !MATCH_STOPWORDS.has(t)).map(stem);
+}
+/**
+ * The query words a result is matched against:
+ * - With an English word present, Korean words are left out: the descriptions are English, so they could
+ *   never match and only lowered every share ("react 성능 최적화" capped at 1/3, below the tier's 0.5).
+ * - A query of stopwords only ("skill", "claude code") keeps them, or nothing would be matched at all.
+ */
+export function queryTokens(query) {
+    const words = matchTokens(query);
+    const latin = words.filter((t) => !/\p{Script=Hangul}/u.test(t));
+    if (latin.length > 0)
+        return [...new Set(latin)];
+    if (words.length > 0)
+        return [...new Set(words)];
+    return [...new Set(genericWords(query))];
+}
+/**
+ * Stopwords that still name something in this domain. Dropped from queries normally, but searched when they
+ * are all there is ("skill", "claude code"); grammar words ("a the") are not.
+ */
+export const GENERIC_WORDS = new Set(['skill', 'skills', 'claude', 'code', 'tool', 'tools']);
+const genericWords = (text) => (text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? []).filter((t) => GENERIC_WORDS.has(t)).map(stem);
+/** Words a name or description is matched on: matchTokens plus the generic words a stopword-only query uses. */
+const textWords = (text) => new Set([...matchTokens(text), ...genericWords(text)]);
+/**
+ * How directly a skill matches the query words: share of query words in the skill name, share in the
+ * description/when_to_use, and whether the description contains the query as a phrase.
+ */
+export function lexicalMatch(query, name, text) {
+    const q = queryTokens(query);
+    if (q.length === 0)
+        return { name: 0, text: 0, any: 0, phrase: 0 };
+    const nameSet = textWords(name.replace(/[-_.]+/g, ' '));
+    const textSet = textWords(text);
+    // a longer query word also matches as a prefix ("docker" in "dockerfile"); short ones ("pdf", "ui") must be exact
+    const has = (set, t) => set.has(t) || (t.length >= 4 && [...set].some((w) => w.startsWith(t)));
+    const cover = (set) => q.filter((t) => has(set, t)).length / q.length;
+    const normalize = (s) => s.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
+    const phrase = q.length >= 2 && normalize(text).includes(normalize(query)) ? 1 : 0;
+    const any = q.filter((t) => has(nameSet, t) || has(textSet, t)).length / q.length;
+    return { name: cover(nameSet), text: cover(textSet), any, phrase };
+}
+/**
+ * Relevance tier (user decision): 1 when the name has a query word and at least half the words appear in the
+ * name or description. Results are ordered by tier first, then downloads → stars → R as before.
+ */
+export function relevanceTier(m) {
+    return m.name > 0 && m.any >= 0.5 ? 1 : 0;
+}
+/** Final R: the search-engine signal blended with direct word matches, so fuzzy hits without the query words sink. */
+export function blendRelevance(base, m) {
+    return clamp01(0.45 * base + 0.25 * m.text + 0.2 * m.name + 0.1 * m.phrase);
+}

package/server/src/search/result.js

@@ -0,0 +1,129 @@
+import { RISK_ORDER } from "../analyze/risk.js";
+import { planInstall } from "../install/plan.js";
+import { truncate } from "../util/sanitize.js";
+import { categorize } from "./category.js";
+import { trustTier } from "./rank.js";
+export const TRUST_LABEL = { official: '공식', partner: '파트너', community: '커뮤니티' };
+export function treeUrl(repo, ref, dir) {
+    const base = `https://github.com/${repo}`;
+    if (!ref)
+        return base;
+    return dir ? `${base}/tree/${ref}/${dir.split('/').map(encodeURIComponent).join('/')}` : `${base}/tree/${ref}`;
+}
+export function marketplaceSource(skill, plugin) {
+    const tier = trustTier(skill, plugin);
+    const label = tier === 'other' ? plugin.marketplace : TRUST_LABEL[tier];
+    return { kind: 'marketplace', label, url: skill.repo ? treeUrl(skill.repo, skill.ref, skill.dir_path) : '' };
+}
+export function githubSource(skill) {
+    if (!skill.repo)
+        return null;
+    return { kind: 'github', label: 'GitHub', url: treeUrl(skill.repo, skill.ref, skill.dir_path) };
+}
+/** `owner/repo` a GitHub or skills.sh page is about; null for other links. */
+function repoOfSource(s) {
+    const m = s.url.match(/^https:\/\/(?:github\.com|skills\.sh)\/([^/?#]+\/[^/?#]+)/i);
+    return m ? decodeURIComponent(m[1]).toLowerCase() : null;
+}
+/** Sources of this skill's own repo, and those of copies in other repos (merged in from duplicates). */
+export function splitCopies(sources, repo) {
+    if (!repo)
+        return { own: sources, copies: [] };
+    const own = [];
+    const copies = [];
+    for (const s of sources) {
+        const r = repoOfSource(s);
+        if (r && r !== repo.toLowerCase() && s.kind !== 'marketplace')
+            copies.push(s);
+        else
+            own.push(s);
+    }
+    return { own, copies };
+}
+/** One link per kind, label and repo: copies in other repos are kept (buildResultItem shows them apart). */
+export function mergeSources(a, b) {
+    const out = [...a];
+    const same = (x, s) => x.kind === s.kind && x.label === s.label && repoOfSource(x) === repoOfSource(s);
+    for (const s of b)
+        if (!out.some((x) => same(x, s)))
+            out.push(s);
+    return out;
+}
+export function storeLookup(store) {
+    const plugins = new Map();
+    const mps = new Map();
+    const skillsOf = new Map();
+    const list = (id) => {
+        if (!skillsOf.has(id))
+            skillsOf.set(id, store.listSkillsByPlugin(id));
+        return skillsOf.get(id);
+    };
+    return {
+        plugin(id) {
+            if (!id)
+                return null;
+            if (!plugins.has(id))
+                plugins.set(id, store.getPlugin(id) ?? null);
+            return plugins.get(id);
+        },
+        marketplace(name) {
+            if (!name)
+                return null;
+            if (!mps.has(name))
+                mps.set(name, store.getMarketplace(name) ?? null);
+            return mps.get(name);
+        },
+        pluginSkillCount(id) {
+            return list(id).length;
+        },
+        pluginTopRisk(id) {
+            return list(id).reduce((top, s) => (RISK_ORDER[s.risk_level] > RISK_ORDER[top] ? s.risk_level : top), 'low');
+        },
+    };
+}
+export function buildResultItem(a) {
+    const { skill } = a;
+    const plugin = a.lookup.plugin(skill.plugin_id);
+    const plan = planInstall(skill, plugin, a.lookup.marketplace(plugin?.marketplace));
+    const desc = skill.description ?? '';
+    const { own, copies } = splitCopies(a.sources, skill.repo);
+    return {
+        id: skill.id,
+        name: skill.name,
+        description: truncate(desc, 300),
+        sources: own,
+        ...(copies.length ? { copies } : {}),
+        ...(a.installs != null ? { installs: a.installs } : {}),
+        ...(a.stars != null ? { stars: a.stars } : {}),
+        ...(skill.last_commit_at ? { lastCommitAt: skill.last_commit_at } : {}),
+        score: Math.round(a.score * 1000) / 1000,
+        breakdown: {
+            R: Math.round(a.breakdown.R * 1000) / 1000,
+            P: Math.round(a.breakdown.P * 1000) / 1000,
+            F: Math.round(a.breakdown.F * 1000) / 1000,
+            T: Math.round(a.breakdown.T * 1000) / 1000,
+        },
+        riskLevel: skill.risk_level ?? 'low',
+        riskFlags: skill.risk_json ? JSON.parse(skill.risk_json) : [],
+        qualityWarnings: skill.quality_json ? JSON.parse(skill.quality_json) : [],
+        install: {
+            method: plan.method,
+            command: plan.command,
+            ...(plan.pluginId ? { pluginId: plan.pluginId } : {}),
+            ...(plan.disabled ? { disabled: true } : {}),
+        },
+        ...(plugin
+            ? {
+                plugin: {
+                    id: plugin.id,
+                    name: plugin.name,
+                    marketplace: plugin.marketplace,
+                    skillCount: a.lookup.pluginSkillCount(plugin.id),
+                    topRisk: a.lookup.pluginTopRisk(plugin.id),
+                },
+            }
+            : {}),
+        trust: trustTier(skill, plugin),
+        categories: categorize({ name: skill.name, description: desc, whenToUse: skill.when_to_use, marketplaceCategory: plugin?.category }),
+    };
+}

package/server/src/search/searchLog.js

@@ -0,0 +1,53 @@
+import { randomUUID } from 'node:crypto';
+/** The hidden minigame's query (docs/arasaka-game.md) is never logged: the screen opens it without searching. */
+const NOT_LOGGED = new Set(['arasaka_in']);
+/**
+ * Watches one search's events and, at `done`, writes one search-log entry (U5-2, user decision): the query, how
+ * many results and hidden ones, how long the first and final results took, failed sources and the filters.
+ * Only on this PC, never sent anywhere; the result list itself is not kept. Returns events to send (done gets `sid`).
+ */
+export function searchLogger(store, query, filters, started) {
+    if (NOT_LOGGED.has(query.trim().toLowerCase()))
+        return (e) => e;
+    const sid = randomUUID();
+    let firstMs = null;
+    let results = null;
+    const srcFail = [];
+    let logged = false;
+    return (e) => {
+        if ((e.type === 'candidates' || e.type === 'results') && firstMs == null)
+            firstMs = Date.now() - started;
+        if (e.type === 'results')
+            results = e;
+        if (e.type === 'source' && (e.state === 'failed' || e.state === 'timeout'))
+            srcFail.push(`${e.source}:${e.state}`);
+        if (e.type !== 'done' || logged)
+            return e;
+        logged = true;
+        try {
+            write(e);
+        }
+        catch (err) {
+            console.error('[search log]', err); // the search itself must not fail over its log entry
+        }
+        return { ...e, sid };
+    };
+    function write(e) {
+        store.logEvent('search', null, query, {
+            sid,
+            n: results?.items.length ?? 0,
+            hidLow: results?.hiddenLowStars ?? 0,
+            // since 2026-11-02 hidLow counts only known star counts below the minimum; unknown ones are here
+            hidUnknown: results?.hiddenUnknownStars ?? 0,
+            hidNoMatch: results?.hiddenNoMatch ?? 0,
+            hidRisk: results?.hiddenHighRisk ?? 0,
+            firstMs,
+            finalMs: e.elapsedMs,
+            cached: e.cached,
+            srcFail,
+            minStars: results?.minStars ?? null,
+            maxRisk: filters.maxRisk ?? 'medium',
+            lift: filters.minStars != null,
+        });
+    }
+}

package/server/src/security.js

@@ -0,0 +1,53 @@
+import { DEV_VITE_PORT } from "./config.js";
+export function allowedHosts({ port, dev }) {
+    const hosts = new Set([`127.0.0.1:${port}`, `localhost:${port}`]);
+    if (dev) {
+        hosts.add(`127.0.0.1:${DEV_VITE_PORT}`);
+        hosts.add(`localhost:${DEV_VITE_PORT}`);
+    }
+    return hosts;
+}
+export function allowedOrigins(opts) {
+    return new Set([...allowedHosts(opts)].map((h) => `http://${h}`));
+}
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+function deny(res, message) {
+    res.status(403).json({ error: message });
+}
+/**
+ * - Host allow-list on every request (DNS rebinding).
+ * - `/api` requires `X-Skill-Finder: 1`, which forces a CORS preflight from other origins; no CORS headers are ever sent.
+ * - State-changing methods require an Origin that is the app's own origin.
+ */
+export function securityMiddleware(opts) {
+    // `opts` may be the live config object; the port is only known for sure after listen().
+    return (req, res, next) => {
+        const hosts = allowedHosts(opts);
+        const origins = allowedOrigins(opts);
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        res.setHeader('Referrer-Policy', 'no-referrer');
+        res.setHeader('X-Frame-Options', 'DENY');
+        const host = (req.headers.host ?? '').toLowerCase();
+        if (!hosts.has(host))
+            return deny(res, 'host not allowed');
+        // Any case: routes match /API as /api unless routing is case-sensitive (it is, in createApp), and the check
+        // must not depend on that (project review 2026-11-02: /API/... skipped every check below).
+        if (req.path.toLowerCase().startsWith('/api')) {
+            if (req.method === 'OPTIONS')
+                return deny(res, 'cors not allowed');
+            // a page on another site; browsers send this on every request they make
+            if (req.get('sec-fetch-site') === 'cross-site')
+                return deny(res, 'cross-site request');
+            if (req.get('x-skill-finder') !== '1')
+                return deny(res, 'missing X-Skill-Finder header');
+            if (!SAFE_METHODS.has(req.method)) {
+                const origin = req.get('origin');
+                if (!origin || !origins.has(origin.toLowerCase()))
+                    return deny(res, 'origin not allowed');
+            }
+        }
+        next();
+    };
+}
+export const CSP = "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; " +
+    "connect-src 'self'; font-src 'self' data:; object-src 'none'; base-uri 'none'; frame-ancestors 'none'; form-action 'self'";

package/server/src/settings.js

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+export const SettingsSchema = z.object({
+    weights: z.object({
+        R: z.number().min(0).max(1),
+        P: z.number().min(0).max(1),
+        F: z.number().min(0).max(1),
+        T: z.number().min(0).max(1),
+    }),
+    telemetryDisabled: z.boolean(),
+    /** Collect skills of lazily indexed marketplaces in the background after each sync. */
+    autoCollect: z.boolean(),
+    defaultScope: z.enum(['user', 'project']),
+    defaultProjectPath: z.string().max(1000),
+    /** Search results must come from a GitHub repo with at least this many stars (0 = no limit). */
+    minStars: z.number().int().min(0).max(1_000_000),
+    /** Keep a search log on this PC (U5-2): what was searched and which results were opened, 90 days. */
+    searchLog: z.boolean(),
+});
+export const DEFAULT_SETTINGS = {
+    weights: { R: 0.55, P: 0.2, F: 0.1, T: 0.15 },
+    telemetryDisabled: true,
+    autoCollect: true,
+    defaultScope: 'user',
+    defaultProjectPath: '',
+    minStars: 5000,
+    searchLog: true,
+};
+/** Search log entries older than this are deleted (at startup and daily). */
+export const SEARCH_LOG_KEEP_MS = 90 * 24 * 60 * 60 * 1000;
+export const DEFAULT_MARKETPLACES = [
+    { name: 'claude-plugins-official', repo: 'anthropics/claude-plugins-official', enabled: true, index_mode: 'eager' },
+    { name: 'anthropic-agent-skills', repo: 'anthropics/skills', enabled: true, index_mode: 'eager' },
+    { name: 'claude-community', repo: 'anthropics/claude-plugins-community', enabled: true, index_mode: 'lazy' },
+    { name: 'knowledge-work-plugins', repo: 'anthropics/knowledge-work-plugins', enabled: false, index_mode: 'lazy' },
+];
+/** Anthropic-run marketplaces whose external plugins count as partners for the trust score. */
+export const PARTNER_MARKETPLACES = new Set(['claude-plugins-official', 'anthropic-agent-skills', 'knowledge-work-plugins']);
+export const COMMUNITY_MARKETPLACES = new Set(['claude-community']);
+export function getSettings(store) {
+    const saved = store.getSetting('app') ?? {};
+    // Weights are no longer a setting (UI debate D-1): they never changed the order, only the card numbers and the
+    // cache. Saved ones from older versions are ignored.
+    const merged = { ...DEFAULT_SETTINGS, ...saved, weights: DEFAULT_SETTINGS.weights };
+    const parsed = SettingsSchema.safeParse(merged);
+    return parsed.success ? parsed.data : DEFAULT_SETTINGS;
+}
+export function saveSettings(store, next) {
+    store.setSetting('app', next);
+}
+export function seedMarketplaces(store) {
+    if (store.getSetting('marketplacesSeeded'))
+        return;
+    for (const m of DEFAULT_MARKETPLACES)
+        store.insertMarketplaceIfMissing({ ...m });
+    store.setSetting('marketplacesSeeded', true);
+}

package/server/src/sources/gitTree.js

@@ -0,0 +1,101 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { run } from "../util/proc.js";
+const REPO_RE = /^[A-Za-z0-9-]{1,39}\/[A-Za-z0-9._-]{1,100}$/;
+const SHA_RE = /^[0-9a-f]{40}$/i;
+const REF_RE = /^[A-Za-z0-9._\/-]{1,200}$/;
+// No prompts, no credential helpers (Git Credential Manager would pop a window for missing repos),
+// and no lazy blob downloads from the partial clone.
+const GIT_ENV = {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_NO_LAZY_FETCH: '1',
+    GCM_INTERACTIVE: 'never',
+    GIT_ASKPASS: '',
+    SSH_ASKPASS: '',
+};
+const GIT_BASE = [
+    '-c', 'credential.helper=',
+    '-c', 'core.askPass=',
+    '-c', 'core.longpaths=true',
+    '-c', 'http.lowSpeedLimit=1000',
+    '-c', 'http.lowSpeedTime=30',
+];
+const repoUrl = (repo) => `https://github.com/${repo}.git`;
+function git(args, cwd, timeoutMs = 90_000, raw = false) {
+    return run('git', [...GIT_BASE, ...args], { cwd, env: GIT_ENV, timeoutMs, raw });
+}
+/** Resolves a ref (or HEAD) to a commit SHA with `git ls-remote`; uses no API quota. */
+export async function lsRemote(repo, ref) {
+    if (!REPO_RE.test(repo))
+        throw new Error(`invalid repo: ${repo}`);
+    if (ref && SHA_RE.test(ref))
+        return { sha: ref.toLowerCase(), defaultBranch: null };
+    if (ref && !REF_RE.test(ref))
+        throw new Error(`invalid ref: ${ref}`);
+    const target = ref || 'HEAD';
+    const r = await git(['ls-remote', '--symref', repoUrl(repo), target], undefined, 30_000);
+    if (r.exitCode !== 0)
+        return null;
+    let sha = null;
+    let peeled = null;
+    let defaultBranch = null;
+    for (const line of r.stdout.split('\n')) {
+        const sym = line.match(/^ref: refs\/heads\/(\S+)\s+HEAD$/);
+        if (sym) {
+            defaultBranch = sym[1];
+            continue;
+        }
+        const m = line.match(/^([0-9a-f]{40})\s+(\S+)$/);
+        if (!m)
+            continue;
+        if (m[2].endsWith('^{}'))
+            peeled = m[1];
+        else if (!sha || m[2] === target || m[2] === `refs/heads/${target}`)
+            sha = m[1];
+    }
+    const resolved = peeled ?? sha;
+    return resolved ? { sha: resolved, defaultBranch } : null;
+}
+/**
+ * Lists every blob path at a commit (or the remote HEAD) using a bare, blob-less, depth-1 fetch.
+ * Nothing is checked out. Passing 'HEAD' saves the separate ls-remote round trip.
+ */
+export async function gitTree(repo, sha, workRoot) {
+    if (!REPO_RE.test(repo))
+        throw new Error(`invalid repo: ${repo}`);
+    if (sha !== 'HEAD' && !SHA_RE.test(sha))
+        throw new Error(`invalid sha: ${sha}`);
+    await mkdir(workRoot, { recursive: true });
+    // Short folder names: Windows paths over 260 chars break pack writes under deep data dirs.
+    const dir = join(workRoot, `${createHash('sha1').update(repo).digest('hex').slice(0, 10)}-${randomBytes(3).toString('hex')}`);
+    try {
+        const init = await git(['init', '--bare', '-q', dir]);
+        if (init.exitCode !== 0)
+            throw new Error(`git init failed: ${init.stderr.trim()}`);
+        const fetch = await git(['fetch', '-q', '--depth', '1', '--filter=blob:none', '--no-tags', repoUrl(repo), sha], dir);
+        if (fetch.exitCode !== 0)
+            throw new Error(`git fetch failed: ${fetch.stderr.trim().split('\n')[0] || fetch.exitCode}`);
+        if (sha === 'HEAD') {
+            const rev = await git(['rev-parse', 'FETCH_HEAD'], dir);
+            sha = rev.stdout.trim();
+            if (rev.exitCode !== 0 || !SHA_RE.test(sha))
+                throw new Error('git rev-parse FETCH_HEAD failed');
+        }
+        const ls = await git(['ls-tree', '-r', '-z', '--full-tree', sha], dir, 90_000, true);
+        if (ls.exitCode !== 0)
+            throw new Error(`git ls-tree failed: ${ls.stderr.trim()}`);
+        const entries = [];
+        for (const rec of ls.stdout.split('\0')) {
+            const m = rec.match(/^\d+ (blob|commit|tree) ([0-9a-f]{40})\t(.+)$/s);
+            if (m && m[1] === 'blob')
+                entries.push({ path: m[3], size: null, sha: m[2] });
+        }
+        const log = await git(['log', '-1', '--format=%cI', sha], dir);
+        return { sha, entries, commitDate: log.exitCode === 0 ? log.stdout.trim() || null : null };
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true }).catch(() => { });
+    }
+}