@seojin08/skill-finder 0.0.0-stage → 0.3.2

package/server/src/sources/popularRepos.js

@@ -0,0 +1,74 @@
+import { searchActivity } from "../search/activity.js";
+import { getSettings } from "../settings.js";
+import { pool, sleep } from "../util/limiter.js";
+/**
+ * Popular-repo collection: the search's minimum-stars filter (default 5,000) left few results because most
+ * candidates come from small repos. This finds well-starred repos that hold skills via GitHub repository
+ * search (which, unlike code search, filters by stars) and indexes their skills locally, so local search
+ * has plenty of candidates that pass the filter.
+ */
+/** Repository-search terms; each runs with `stars:>=<minimum>`. Topic and keyword searches cover different repos. */
+const QUERIES = [
+    'topic:claude-skills',
+    'topic:agent-skills',
+    'topic:claude-code-skills',
+    'topic:claude-code',
+    'topic:anthropic-claude',
+    '"claude skills"',
+    '"agent skills"',
+    'claude code skills',
+    'SKILL.md in:readme',
+];
+const STATE_KEY = 'popularRepos';
+const RECHECK_MS = 7 * 24 * 60 * 60 * 1000;
+const MAX_REPOS = 150;
+/** Without a star filter the search would be every repo with a matching topic; keep a floor. */
+const MIN_STARS_FLOOR = 1000;
+export function popularState(ctx) {
+    return ctx.store.getSetting(STATE_KEY) ?? { lastRunAt: null, repos: {} };
+}
+export async function collectPopularRepos(ctx, ctl, background, force) {
+    const minStars = Math.max(MIN_STARS_FLOOR, getSettings(ctx.store).minStars);
+    const state = popularState(ctx);
+    // 1. find repos (sequential: the search API allows 30 requests a minute)
+    const found = new Map();
+    for (const q of QUERIES) {
+        await ctl.checkpoint();
+        try {
+            // fresh: the point is to find repos that are new since the last run (and to store their current stars)
+            for (const r of await ctx.github.searchRepos(`${q} stars:>=${minStars}`, 100, { fresh: true }))
+                found.set(r.repo, Math.max(found.get(r.repo) ?? 0, r.stars));
+        }
+        catch (err) {
+            ctl.tick(`검색 "${q}": ${String(err.message ?? err).slice(0, 160)}`);
+        }
+    }
+    const now = Date.now();
+    const top = [...found]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, MAX_REPOS)
+        .map(([repo]) => repo);
+    // Repos with enough stars that only a lookup or two put into the index (a skills.sh or code-search hit):
+    // index them whole once, so their other skills can be found too.
+    const known = new Set([...top, ...Object.keys(state.repos)].map((r) => r.toLowerCase()));
+    const partial = ctx.store.listReposWithGithubSkills(minStars).filter((r) => !known.has(r.toLowerCase()));
+    const due = [...top, ...partial].filter((repo) => force || !state.repos[repo] || now - Date.parse(state.repos[repo].checkedAt) > RECHECK_MS);
+    ctl.addTotal(due.length);
+    // 2. index their skills (yields to searches when running in the background)
+    await pool(due, background ? 3 : 4, async (repo) => {
+        await ctl.checkpoint();
+        while (background && searchActivity.busy() && !ctl.cancelled)
+            await sleep(500);
+        try {
+            const prev = state.repos[repo];
+            const r = await ctx.indexer.indexRepo(repo, { unchangedSince: force ? null : prev?.sha });
+            state.repos[repo] = { checkedAt: new Date().toISOString(), skills: r.unchanged ? (prev?.skills ?? 0) : r.skills, ...(r.sha ? { sha: r.sha } : {}) };
+            ctl.tick();
+        }
+        catch (err) {
+            ctl.tick(`${repo}: ${String(err.message ?? err).slice(0, 200)}`);
+        }
+    }, () => ctl.cancelled);
+    state.lastRunAt = new Date().toISOString();
+    ctx.store.setSetting(STATE_KEY, state);
+}

package/server/src/sources/skillsSh.js

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { USER_AGENT } from "../util/http.js";
+import { sanitizeLine } from "../util/sanitize.js";
+const ResponseSchema = z.object({
+    skills: z.array(z.looseObject({
+        id: z.string(),
+        name: z.string(),
+        source: z.string().optional().default(''),
+        skillId: z.string().optional(),
+        installs: z.number().optional().default(0),
+    })),
+});
+const DAY_MS = 24 * 60 * 60 * 1000;
+export const SKILLS_SH_BASE = 'https://skills.sh';
+/**
+ * Undocumented endpoint used by the official skills CLI (`skills find`). Only called on a user search,
+ * at most a few times per search, with results cached for 24h (robots.txt disallows crawling this path).
+ */
+export async function searchSkillsSh(store, query, limit = 20) {
+    const q = query.trim().replace(/\s+/g, ' ').slice(0, 200);
+    if (!q)
+        return [];
+    const key = `skillssh:${limit}:${q.toLowerCase()}`;
+    const cached = store.getCached(key, DAY_MS);
+    if (cached)
+        return cached;
+    // one request per query at a time (a re-search while the first is still out reuses it)
+    let p = inFlight.get(key);
+    if (!p) {
+        p = fetchSkillsSh(store, key, q, limit)
+            .catch((err) => {
+            // down or slow: an answer from the last week beats none (installs are the first sort key)
+            const stale = store.getCached(key, STALE_OK_MS);
+            if (stale)
+                return stale;
+            throw err;
+        })
+            .finally(() => inFlight.delete(key));
+        inFlight.set(key, p);
+    }
+    return p;
+}
+const inFlight = new Map();
+/** How old an earlier answer may be to stand in when skills.sh fails. */
+const STALE_OK_MS = 7 * DAY_MS;
+async function fetchSkillsSh(store, key, q, limit) {
+    const params = new URLSearchParams({ q, limit: String(limit) });
+    const res = await fetch(`${SKILLS_SH_BASE}/api/search?${params}`, {
+        headers: { 'User-Agent': USER_AGENT, Accept: 'application/json' },
+        signal: AbortSignal.timeout(5000),
+    });
+    if (!res.ok)
+        throw new Error(`skills.sh 응답 ${res.status}`);
+    const body = ResponseSchema.parse(await res.json());
+    const hits = body.skills.map((s) => ({
+        id: sanitizeLine(s.id),
+        source: sanitizeLine(s.source),
+        skillId: s.skillId ? sanitizeLine(s.skillId) : null,
+        name: sanitizeLine(s.name),
+        installs: Math.max(0, Math.floor(s.installs)),
+    }));
+    store.putCached(key, hits);
+    return hits;
+}
+const OWNER_REPO_RE = /^[A-Za-z0-9-]{1,39}\/[A-Za-z0-9._-]{1,100}$/;
+const DOMAIN_RE = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i;
+export function classifySkillsShSource(source) {
+    if (OWNER_REPO_RE.test(source))
+        return { kind: 'github', repo: source };
+    const host = source.replace(/^https?:\/\//, '').replace(/\/.*$/, '');
+    if (DOMAIN_RE.test(host))
+        return { kind: 'domain', domain: host.toLowerCase() };
+    return null;
+}

package/server/src/tasks.js

@@ -0,0 +1,216 @@
+import { RISK_RULES_VERSION, riskLevel } from "./analyze/risk.js";
+import { skillMdPath } from "./discovery/tree.js";
+import { PluginUnavailableError, recheckRisk } from "./indexer.js";
+import { GRAPHQL_BATCH } from "./sources/github.js";
+import { syncMarketplace } from "./sources/marketplace.js";
+import { collectPopularRepos, popularState } from "./sources/popularRepos.js";
+import { searchActivity } from "./search/activity.js";
+import { getSettings, SEARCH_LOG_KEEP_MS } from "./settings.js";
+import { pool, sleep } from "./util/limiter.js";
+const COLLECT_CONCURRENCY = 4;
+const BACKGROUND_CONCURRENCY = 3;
+async function indexPending(ctx, marketplace, ctl, background = false) {
+    const pending = ctx.store.listPluginsNeedingIndex(marketplace);
+    ctl.addTotal(pending.length);
+    await pool(pending, background ? BACKGROUND_CONCURRENCY : COLLECT_CONCURRENCY, async (p) => {
+        await ctl.checkpoint();
+        // Background collection steps aside while a search is running so searches stay fast.
+        while (background && searchActivity.busy() && !ctl.cancelled)
+            await sleep(500);
+        try {
+            await ctx.indexer.indexPlugin(p.id);
+            ctl.tick();
+        }
+        catch (err) {
+            const line = `${p.id}: ${String(err.message ?? err).slice(0, 200)}`;
+            if (err instanceof PluginUnavailableError)
+                ctl.skip(line);
+            else
+                ctl.tick(line);
+        }
+    }, () => ctl.cancelled);
+}
+/** Syncs marketplace.json for one or all enabled marketplaces; eager ones also index their plugins' skills. */
+export function startSync(ctx, marketplace, force = false) {
+    const label = marketplace ?? '*';
+    const running = ctx.jobs.active('sync', label);
+    if (running)
+        return running;
+    return ctx.jobs.start('sync', label, async (ctl) => {
+        const targets = ctx.store
+            .listMarketplaces()
+            .filter((m) => (marketplace ? m.name === marketplace : m.enabled === 1));
+        ctl.setTotal(targets.length);
+        for (const m of targets) {
+            await ctl.checkpoint();
+            try {
+                await syncMarketplace(ctx.store, ctx.github, m.name, force);
+                ctl.tick();
+            }
+            catch (err) {
+                ctl.tick(`${m.name}: ${String(err.message ?? err).slice(0, 200)}`);
+                continue;
+            }
+            if (m.index_mode === 'eager')
+                await indexPending(ctx, m.name, ctl);
+        }
+        ctx.store.clearSearchCache();
+        if (!marketplace && getSettings(ctx.store).autoCollect) {
+            startAutoCollect(ctx);
+            const last = popularState(ctx).lastRunAt;
+            if (!last || Date.now() - Date.parse(last) > POPULAR_EVERY_MS)
+                startPopularCollect(ctx, true);
+        }
+    });
+}
+const POPULAR_EVERY_MS = 24 * 60 * 60 * 1000;
+/** How often repo metadata is refreshed, and what counts as old enough to refresh. */
+export const REPO_META_EVERY_MS = 6 * 60 * 60 * 1000;
+const REPO_META_STALE_MS = 18 * 60 * 60 * 1000;
+let repoMetaRunning = false;
+/**
+ * Keeps star counts of the repos skills come from current (GraphQL, 100 per call), so a search reads them
+ * from the database instead of asking GitHub per repo, and fills repos never fetched (indexed without a
+ * token). Steps aside while a search runs; does nothing without a token.
+ */
+export async function refreshRepoMeta(ctx) {
+    if (repoMetaRunning || !ctx.github.hasToken)
+        return 0;
+    repoMetaRunning = true;
+    let stored = 0;
+    try {
+        const repos = ctx.store.listReposToRefresh(new Date(Date.now() - REPO_META_STALE_MS).toISOString(), 10_000);
+        for (let i = 0; i < repos.length; i += GRAPHQL_BATCH) {
+            while (searchActivity.busy())
+                await sleep(500);
+            stored += await ctx.github.refreshRepoMeta(repos.slice(i, i + GRAPHQL_BATCH));
+        }
+    }
+    catch (err) {
+        console.warn('[repo-meta]', String(err.message ?? err).slice(0, 200));
+    }
+    finally {
+        repoMetaRunning = false;
+    }
+    return stored;
+}
+const RISK_RECHECK_BATCH = 50;
+const RISK_RECHECK_EVERY_MS = 20 * 60 * 60 * 1000;
+/** Setting: when the last risk re-check pass finished. */
+const RISK_RECHECK_KEY = 'riskRecheckAt';
+let riskRecheckRunning = false;
+/**
+ * Checks stored skills again after the risk rules changed (RISK_RULES_VERSION): reads each SKILL.md at the
+ * commit it was indexed from (raw.githubusercontent.com, not the API quota) and recomputes the flags that come
+ * from the text. One pass in id order, 50 rows per transaction, stepping aside while a search runs. Rows that
+ * could not be read (gone, or a different file) keep their old version and are tried on the next pass, at most
+ * once a day (RISK_RECHECK_EVERY_MS) however often the app is restarted. `changed`: rows whose flags changed.
+ */
+export async function recheckRiskRules(ctx, now = Date.now()) {
+    const last = ctx.store.getSetting(RISK_RECHECK_KEY);
+    if (riskRecheckRunning || (last && now - Date.parse(last) < RISK_RECHECK_EVERY_MS))
+        return { checked: 0, changed: 0 };
+    riskRecheckRunning = true;
+    let checked = 0;
+    let changed = 0;
+    try {
+        for (let after = '';;) {
+            const rows = ctx.store.listSkillsForRiskRecheck(RISK_RULES_VERSION, after, RISK_RECHECK_BATCH);
+            if (rows.length === 0)
+                break;
+            after = rows.at(-1).id;
+            const results = await pool(rows, 8, async (row) => {
+                while (searchActivity.busy())
+                    await sleep(500); // raw downloads share their slots with searches
+                const r = await ctx.github.getRawText(row.repo, row.ref, skillMdPath(row.dir_path));
+                return r.text == null ? null : recheckRisk(row, r.text);
+            });
+            ctx.store.transaction(() => {
+                rows.forEach((row, i) => {
+                    const res = results[i];
+                    const next = res?.ok ? res.value : null;
+                    // only onto the same SKILL.md: a row indexed again meanwhile (new commit) already has current flags
+                    if (!next || !ctx.store.setSkillRisk(row.id, row.skill_md_sha256, next.risk_json, next.risk_level, RISK_RULES_VERSION))
+                        return;
+                    checked++;
+                    if (next.risk_json !== row.risk_json || next.risk_level !== row.risk_level)
+                        changed++;
+                });
+            });
+        }
+        ctx.store.setSetting(RISK_RECHECK_KEY, new Date(now).toISOString());
+    }
+    catch (err) {
+        console.warn('[risk recheck]', String(err.message ?? err).slice(0, 200));
+    }
+    finally {
+        riskRecheckRunning = false;
+    }
+    if (changed > 0)
+        ctx.store.clearSearchCache();
+    if (checked > 0)
+        console.log(`[risk recheck] ${checked} skills checked, ${changed} changed`);
+    return { checked, changed };
+}
+/**
+ * Derives every stored level from its stored flags again (at startup). A change to how flags add up to a level,
+ * such as a flag becoming information only (UI debate D-3), needs no download. Returns the rows that moved.
+ */
+export function relevelRisk(ctx) {
+    const moved = ctx.store.listSkillRiskLevels().flatMap((r) => {
+        const level = riskLevel(r.risk_json ? JSON.parse(r.risk_json) : []);
+        return level === r.risk_level ? [] : [{ id: r.id, level }];
+    });
+    for (let i = 0; i < moved.length; i += 500) {
+        ctx.store.transaction(() => {
+            for (const m of moved.slice(i, i + 500))
+                ctx.store.setSkillRiskLevel(m.id, m.level);
+        });
+    }
+    if (moved.length > 0) {
+        ctx.store.clearSearchCache();
+        console.log(`[risk] ${moved.length} skills got a new level from their stored signals`);
+    }
+    return moved.length;
+}
+/** Deletes search-log entries older than 90 days (U5-2; at startup and daily). */
+export function pruneSearchLog(ctx, now = Date.now()) {
+    try {
+        return ctx.store.clearSearchLog(new Date(now - SEARCH_LOG_KEEP_MS).toISOString());
+    }
+    catch (err) {
+        console.warn('[search log]', String(err.message ?? err).slice(0, 200));
+        return 0;
+    }
+}
+export const POPULAR_JOB_LABEL = 'popular-repos';
+/** Finds GitHub repos with many stars that hold skills and indexes them (daily after sync, or on demand). */
+export function startPopularCollect(ctx, background = false, force = false) {
+    const running = ctx.jobs.active('collect', POPULAR_JOB_LABEL);
+    if (running)
+        return running;
+    return ctx.jobs.start('collect', POPULAR_JOB_LABEL, async (ctl) => {
+        await collectPopularRepos(ctx, ctl, background, force);
+        ctx.store.clearSearchCache();
+    });
+}
+/** After a full sync: collect skills of every enabled lazy marketplace in the background (yields to searches). */
+export function startAutoCollect(ctx) {
+    for (const m of ctx.store.listMarketplaces()) {
+        if (m.enabled !== 1 || m.index_mode !== 'lazy')
+            continue;
+        if (ctx.store.listPluginsNeedingIndex(m.name).length === 0)
+            continue;
+        startCollect(ctx, m.name, true);
+    }
+}
+/** Background skill collection for a lazy marketplace; pause/resume via the job controls, restart-safe. */
+export function startCollect(ctx, marketplace, background = false) {
+    const running = ctx.jobs.active('collect', marketplace);
+    if (running)
+        return running;
+    return ctx.jobs.start('collect', marketplace, async (ctl) => {
+        await indexPending(ctx, marketplace, ctl, background);
+        ctx.store.clearSearchCache();
+    });
+}

package/server/src/update.js

@@ -0,0 +1,53 @@
+import { releaseMessage, signedNotes, verifyText } from "./release.js";
+const DEFAULT_BASE = 'https://skill-finder.a01075011775.workers.dev/download/';
+const CHECK_EVERY_MS = 6 * 60 * 60 * 1000;
+let latest = null;
+const parse = (v) => v.split('.').map((n) => Number(n) || 0);
+/** a > b for "1.2.3" versions. */
+export function newerVersion(a, b) {
+    const [x, y] = [parse(a), parse(b)];
+    for (let i = 0; i < 3; i++)
+        if ((x[i] ?? 0) !== (y[i] ?? 0))
+            return (x[i] ?? 0) > (y[i] ?? 0);
+    return false;
+}
+/**
+ * The newest signed version the download page offers (meta.json); kept quietly as it was when the page cannot be
+ * read or the signature does not match. `publicKey`: tests sign with their own key.
+ */
+export async function checkForUpdate(fetchImpl = fetch, publicKey) {
+    if (process.env.SKILL_FINDER_UPDATES !== '1')
+        return null;
+    let base = process.env.SKILL_FINDER_UPDATE_URL || DEFAULT_BASE;
+    if (!base.endsWith('/'))
+        base += '/';
+    try {
+        const res = await fetchImpl(`${base}meta.json`, { signal: AbortSignal.timeout(5000) });
+        const meta = res.ok ? (await res.json()) : {};
+        const { version, bytes, sha256 } = meta;
+        if (typeof version === 'string' &&
+            /^\d{1,4}\.\d{1,4}\.\d{1,6}$/.test(version) &&
+            typeof bytes === 'number' &&
+            typeof sha256 === 'string' &&
+            /^[0-9a-f]{64}$/.test(sha256) &&
+            verifyText(releaseMessage({ version, bytes, sha256 }), meta.signature, publicKey) &&
+            // an older signed release served again does not hide the newer one already seen
+            (!latest || !newerVersion(latest.version, version))) {
+            latest = { version, notes: signedNotes(meta, version, publicKey) };
+        }
+    }
+    catch {
+        // offline: try again later
+    }
+    return latest?.version ?? null;
+}
+export function startUpdateChecks() {
+    if (process.env.SKILL_FINDER_UPDATES !== '1')
+        return;
+    void checkForUpdate();
+    setInterval(() => void checkForUpdate(), CHECK_EVERY_MS).unref();
+}
+/** `{ version, notes }` when the download page has a newer signed version than `current`. */
+export function updateInfo(current) {
+    return latest && current && newerVersion(latest.version, current) ? { ...latest } : null;
+}

package/server/src/util/folderPicker.js

@@ -0,0 +1,208 @@
+import { statSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { run } from "./proc.js";
+// Browsers never reveal a folder's absolute path to a page, so the local server opens the OS folder dialog instead.
+// The initial folder is passed through an environment variable, never spliced into the script text.
+const TITLE = '프로젝트 폴더 선택';
+const TIMEOUT_MS = 10 * 60 * 1000;
+// Explorer-style dialog (IFileOpenDialog with FOS_PICKFOLDERS) through COM interop, owned by an invisible
+// topmost window so it opens in front of the browser. Falls back to FolderBrowserDialog if the COM path fails.
+const WINDOWS_PICKER_CS = `
+using System;
+using System.Runtime.InteropServices;
+public static class SfFolderPicker {
+  [ComImport, Guid("DC1C5A9C-E88A-4dde-A5A1-60F82A20AEF7")] class FileOpenDialogRcw {}
+  [ComImport, Guid("42f85136-db7e-439c-85f1-e4075d135fc8"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+  interface IFileOpenDialog {
+    [PreserveSig] int Show(IntPtr hwndOwner);
+    void SetFileTypes(uint cFileTypes, IntPtr rgFilterSpec);
+    void SetFileTypeIndex(uint iFileType);
+    void GetFileTypeIndex(out uint piFileType);
+    void Advise(IntPtr pfde, out uint pdwCookie);
+    void Unadvise(uint dwCookie);
+    void SetOptions(uint fos);
+    void GetOptions(out uint pfos);
+    void SetDefaultFolder(IShellItem psi);
+    void SetFolder(IShellItem psi);
+    void GetFolder(out IShellItem ppsi);
+    void GetCurrentSelection(out IShellItem ppsi);
+    void SetFileName([MarshalAs(UnmanagedType.LPWStr)] string pszName);
+    void GetFileName([MarshalAs(UnmanagedType.LPWStr)] out string pszName);
+    void SetTitle([MarshalAs(UnmanagedType.LPWStr)] string pszTitle);
+    void SetOkButtonLabel([MarshalAs(UnmanagedType.LPWStr)] string pszText);
+    void SetFileNameLabel([MarshalAs(UnmanagedType.LPWStr)] string pszLabel);
+    void GetResult(out IShellItem ppsi);
+    void AddPlace(IShellItem psi, int fdap);
+    void SetDefaultExtension([MarshalAs(UnmanagedType.LPWStr)] string pszDefaultExtension);
+    void Close(int hr);
+    void SetClientGuid(ref Guid guid);
+    void ClearClientData();
+    void SetFilter(IntPtr pFilter);
+    void GetResults(out IntPtr ppenum);
+    void GetSelectedItems(out IntPtr ppsai);
+  }
+  [ComImport, Guid("43826D1E-E718-42EE-BC55-A1E261C37BFE"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+  interface IShellItem {
+    void BindToHandler(IntPtr pbc, ref Guid bhid, ref Guid riid, out IntPtr ppv);
+    void GetParent(out IShellItem ppsi);
+    void GetDisplayName(uint sigdnName, [MarshalAs(UnmanagedType.LPWStr)] out string ppszName);
+    void GetAttributes(uint sfgaoMask, out uint psfgaoAttribs);
+    void Compare(IShellItem psi, uint hint, out int piOrder);
+  }
+  [DllImport("shell32.dll", CharSet = CharSet.Unicode, PreserveSig = false)]
+  static extern void SHCreateItemFromParsingName(string pszPath, IntPtr pbc, ref Guid riid, out IShellItem ppv);
+
+  // Bringing the dialog forward: a background process may not take the foreground on its own
+  // (foreground lock), so a synthetic Alt key press unlocks SetForegroundWindow, and the dialog
+  // window is made topmost once it exists.
+  [DllImport("user32.dll", CharSet = CharSet.Unicode)] static extern IntPtr FindWindow(string cls, string title);
+  [DllImport("user32.dll")] static extern uint GetWindowThreadProcessId(IntPtr hWnd, out uint pid);
+  [DllImport("user32.dll")] static extern bool SetWindowPos(IntPtr hWnd, IntPtr after, int x, int y, int cx, int cy, uint flags);
+  [DllImport("user32.dll")] static extern bool SetForegroundWindow(IntPtr hWnd);
+  [DllImport("user32.dll")] static extern bool BringWindowToTop(IntPtr hWnd);
+  [DllImport("user32.dll")] static extern void keybd_event(byte vk, byte scan, uint flags, UIntPtr extra);
+  [DllImport("user32.dll")] static extern bool FlashWindow(IntPtr hWnd, bool invert);
+  [DllImport("user32.dll")] static extern IntPtr GetForegroundWindow();
+
+  static void Raise(string title) {
+    uint me = (uint)System.Diagnostics.Process.GetCurrentProcess().Id;
+    for (int i = 0; i < 100; i++) {
+      System.Threading.Thread.Sleep(50);
+      IntPtr h = FindWindow("#32770", title);
+      if (h == IntPtr.Zero) continue;
+      uint pid;
+      GetWindowThreadProcessId(h, out pid);
+      if (pid != me) continue;
+      SetWindowPos(h, new IntPtr(-1), 0, 0, 0, 0, 0x0001 | 0x0002 | 0x0040); // HWND_TOPMOST, NOSIZE|NOMOVE|SHOWWINDOW
+      FlashWindow(h, true);
+      // The browser can take focus back right after the click that opened us; keep asking for ~1.5s.
+      for (int k = 0; k < 10 && GetForegroundWindow() != h; k++) {
+        keybd_event(0x12, 0, 0, UIntPtr.Zero);       // Alt down
+        keybd_event(0x12, 0, 0x0002, UIntPtr.Zero);  // Alt up
+        BringWindowToTop(h);
+        SetForegroundWindow(h);
+        System.Threading.Thread.Sleep(150);
+      }
+      return;
+    }
+  }
+
+  const uint FOS_PICKFOLDERS = 0x20, FOS_FORCEFILESYSTEM = 0x40, FOS_PATHMUSTEXIST = 0x800;
+  const uint SIGDN_FILESYSPATH = 0x80058000;
+
+  public static string Pick(IntPtr owner, string title, string initial) {
+    IFileOpenDialog dlg = (IFileOpenDialog)new FileOpenDialogRcw();
+    System.Threading.Thread raiser = new System.Threading.Thread(() => Raise(title));
+    raiser.IsBackground = true;
+    raiser.Start();
+    try {
+      uint opts;
+      dlg.GetOptions(out opts);
+      dlg.SetOptions(opts | FOS_PICKFOLDERS | FOS_FORCEFILESYSTEM | FOS_PATHMUSTEXIST);
+      dlg.SetTitle(title);
+      if (!String.IsNullOrEmpty(initial)) {
+        try {
+          Guid iid = typeof(IShellItem).GUID;
+          IShellItem folder;
+          SHCreateItemFromParsingName(initial, IntPtr.Zero, ref iid, out folder);
+          dlg.SetFolder(folder);
+        } catch (Exception) { }
+      }
+      if (dlg.Show(owner) != 0) return null;
+      IShellItem result;
+      dlg.GetResult(out result);
+      string path;
+      result.GetDisplayName(SIGDN_FILESYSPATH, out path);
+      return path;
+    } finally {
+      Marshal.ReleaseComObject(dlg);
+    }
+  }
+}
+`;
+const WINDOWS_SCRIPT = `
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+Add-Type -AssemblyName System.Windows.Forms
+$initial = ''
+if ($env:SF_INITIAL_DIR -and (Test-Path -LiteralPath $env:SF_INITIAL_DIR -PathType Container)) { $initial = $env:SF_INITIAL_DIR }
+# Invisible (fully transparent) topmost owner at the screen centre, so the dialog opens centred and above other windows.
+$owner = New-Object System.Windows.Forms.Form
+$owner.TopMost = $true
+$owner.ShowInTaskbar = $false
+$owner.FormBorderStyle = 'None'
+$owner.Opacity = 0
+$owner.StartPosition = 'CenterScreen'
+$owner.Size = New-Object System.Drawing.Size(1, 1)
+$owner.Show()
+$owner.Activate()
+try {
+  Add-Type -TypeDefinition @'
+${WINDOWS_PICKER_CS}
+'@
+  $picked = [SfFolderPicker]::Pick($owner.Handle, '${TITLE}', $initial)
+} catch {
+  $dialog = New-Object System.Windows.Forms.FolderBrowserDialog
+  $dialog.Description = '${TITLE}'
+  $dialog.ShowNewFolderButton = $true
+  if ($initial) { $dialog.SelectedPath = $initial }
+  $picked = $null
+  if ($dialog.ShowDialog($owner) -eq [System.Windows.Forms.DialogResult]::OK) { $picked = $dialog.SelectedPath }
+}
+$owner.Close()
+if ($picked) { [Console]::Out.Write($picked) }
+`;
+function encodePowerShell(script) {
+    return Buffer.from(script, 'utf16le').toString('base64');
+}
+function validDir(p) {
+    if (!p || !isAbsolute(p) || /[\0\r\n]/.test(p))
+        return undefined;
+    try {
+        return statSync(p).isDirectory() ? p : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export class FolderPickerUnavailable extends Error {
+}
+/** Opens the native folder dialog; resolves the chosen absolute path, or null when cancelled. */
+export async function pickFolder(initial) {
+    const env = { ...process.env, SF_INITIAL_DIR: validDir(initial) ?? '' };
+    let result;
+    if (process.platform === 'win32') {
+        result = await run('powershell.exe', ['-NoProfile', '-NonInteractive', '-STA', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encodePowerShell(WINDOWS_SCRIPT)], {
+            env,
+            timeoutMs: TIMEOUT_MS,
+        });
+    }
+    else if (process.platform === 'darwin') {
+        const script = `set p to system attribute "SF_INITIAL_DIR"
+if p is not "" then
+  POSIX path of (choose folder with prompt "${TITLE}" default location (POSIX file p))
+else
+  POSIX path of (choose folder with prompt "${TITLE}")
+end if`;
+        result = await run('osascript', ['-e', script], { env, timeoutMs: TIMEOUT_MS });
+    }
+    else {
+        const start = env.SF_INITIAL_DIR ? `${env.SF_INITIAL_DIR}/` : '';
+        try {
+            result = await run('zenity', ['--file-selection', '--directory', `--title=${TITLE}`, ...(start ? [`--filename=${start}`] : [])], { env, timeoutMs: TIMEOUT_MS });
+        }
+        catch {
+            try {
+                result = await run('kdialog', ['--getexistingdirectory', env.SF_INITIAL_DIR || '.', '--title', TITLE], { env, timeoutMs: TIMEOUT_MS });
+            }
+            catch {
+                throw new FolderPickerUnavailable('zenity 또는 kdialog가 없어 폴더 선택 창을 열 수 없습니다');
+            }
+        }
+    }
+    const raw = result.stdout.trim();
+    if (!raw)
+        return null;
+    // macOS returns "/path/"; keep drive roots ("C:\") and "/" intact.
+    const chosen = /^([A-Za-z]:[\\/]|\/)$/.test(raw) ? raw : raw.replace(/[\\/]+$/, '');
+    return validDir(chosen) ?? null;
+}

package/server/src/util/http.js

@@ -0,0 +1,41 @@
+export const USER_AGENT = 'skill-finder/0.1 (+local)';
+/** GET with a timeout and a byte cap; `text` is null on non-2xx. */
+export async function fetchText(url, opts = {}) {
+    const res = await fetch(url, {
+        headers: { 'User-Agent': USER_AGENT, ...opts.headers },
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 15_000),
+        redirect: 'follow',
+    });
+    const etag = res.headers.get('etag');
+    if (!res.ok || !res.body) {
+        await res.body?.cancel().catch(() => { });
+        return { status: res.status, text: null, truncated: false, etag };
+    }
+    const max = opts.maxBytes ?? 2 * 1024 * 1024;
+    const reader = res.body.getReader();
+    const chunks = [];
+    let size = 0;
+    let truncated = false;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > max) {
+            truncated = true;
+            chunks.push(value.subarray(0, value.byteLength - (size - max)));
+            await reader.cancel().catch(() => { });
+            break;
+        }
+        chunks.push(value);
+    }
+    return { status: res.status, text: Buffer.concat(chunks).toString('utf8'), truncated, etag };
+}
+/** Heuristic binary check: NUL bytes or a high share of replacement characters. */
+export function looksBinary(text) {
+    if (text.includes('\u0000'))
+        return true;
+    const sample = text.slice(0, 4096);
+    const bad = (sample.match(/�/g) ?? []).length;
+    return sample.length > 0 && bad / sample.length > 0.02;
+}