@seojin08/skill-finder 0.0.0-stage → 0.3.3

package/server/src/routes/recommend.js

@@ -0,0 +1,36 @@
+import { Router } from 'express';
+import { z } from 'zod';
+import { ReadmeError, recommendForProject } from "../recommend/readme.js";
+import { getSettings } from "../settings.js";
+const Body = z.object({
+    projectPath: z.string().trim().min(1).max(1000),
+    /** Keywords turned off on the page, and words added there. */
+    exclude: z.array(z.string().max(60)).max(50).optional(),
+    extra: z.array(z.string().max(60)).max(20).optional(),
+});
+/**
+ * README-based recommendation: reads only `<projectPath>/README*` (≤1MB), or without one its package.json,
+ * pyproject.toml or Cargo.toml, and matches the local skill index.
+ */
+export function recommendRouter(ctx) {
+    const r = Router();
+    r.post('/readme-skills', (req, res) => {
+        const parsed = Body.safeParse(req.body);
+        if (!parsed.success) {
+            res.status(400).json({ error: '프로젝트 폴더 경로를 입력하세요.', code: 'INVALID_PATH' });
+            return;
+        }
+        try {
+            const { projectPath, exclude, extra } = parsed.data;
+            res.json(recommendForProject(ctx.store, projectPath, getSettings(ctx.store).weights, { exclude, extra }));
+        }
+        catch (err) {
+            if (err instanceof ReadmeError) {
+                res.status(err.status).json({ error: err.message, code: err.code });
+                return;
+            }
+            throw err;
+        }
+    });
+    return r;
+}

package/server/src/routes/search.js

@@ -0,0 +1,53 @@
+import { Router } from 'express';
+import { z } from 'zod';
+import { searchActivity } from "../search/activity.js";
+import { runSearch } from "../search/pipeline.js";
+import { searchLogger } from "../search/searchLog.js";
+import { getSettings } from "../settings.js";
+import { searchSkillsSh } from "../sources/skillsSh.js";
+import { ndjson } from "../util/ndjson.js";
+const Body = z.object({
+    query: z.string().trim().min(1).max(300),
+    filters: z
+        .object({
+        sources: z.array(z.enum(['marketplace', 'skillssh', 'github'])).max(3).optional(),
+        maxRisk: z.enum(['low', 'medium', 'high']).optional(),
+        marketplaces: z.array(z.string().max(128)).max(20).optional(),
+        // "별 N개 미만 숨김 · 보기": this search only, the setting stays
+        minStars: z.number().int().min(0).max(10_000_000).optional(),
+    })
+        .optional(),
+});
+export function liveSearchDeps(ctx) {
+    return { ctx, skillsSh: (q) => searchSkillsSh(ctx.store, q, 30) };
+}
+export function searchRouter(ctx, deps = liveSearchDeps(ctx)) {
+    const r = Router();
+    r.post('/search', async (req, res) => {
+        const parsed = Body.safeParse(req.body);
+        if (!parsed.success) {
+            res.status(400).json({ error: '검색어는 1–300자여야 합니다' });
+            return;
+        }
+        const out = ndjson(res);
+        const started = Date.now();
+        const filters = parsed.data.filters ?? {};
+        const log = getSettings(ctx.store).searchLog ? searchLogger(ctx.store, parsed.data.query, filters, started) : null;
+        const send = (e) => out.send(log ? log(e) : e);
+        searchActivity.begin();
+        try {
+            await runSearch(deps, parsed.data.query, filters, send);
+        }
+        catch (err) {
+            console.error('[search]', err);
+            send({ type: 'warning', source: 'server', severity: 'urgent', message: `검색 중 오류: ${String(err.message ?? err).slice(0, 200)}` });
+            send({ type: 'results', items: [], hiddenHighRisk: 0, hiddenNoDescription: 0 });
+            send({ type: 'done', cached: false, elapsedMs: Date.now() - started });
+        }
+        finally {
+            searchActivity.end();
+            out.end();
+        }
+    });
+    return r;
+}

package/server/src/routes/skills.js

@@ -0,0 +1,214 @@
+import { Router } from 'express';
+import { existingSkillFolder } from "../install/installed.js";
+import { scanSkillFiles } from "../install/scan.js";
+import { buildSteps, installLocation, planInstall } from "../install/plan.js";
+import { isProjectDir } from "../install/validate.js";
+import { freshness, TRUST_SCORE, trustTier } from "../search/rank.js";
+import { githubSource, marketplaceSource, treeUrl } from "../search/result.js";
+import { getSettings } from "../settings.js";
+import { looksBinary } from "../util/http.js";
+import { sanitizeText } from "../util/sanitize.js";
+import { isTextPath, MAX_FILE_BYTES } from "../util/textFiles.js";
+import { skillTokens } from "../util/tokens.js";
+/**
+ * Where an opened result was in its search (U5-2): the search's `sid`, its 1-based place in the list, the page,
+ * and whether it was still an early card. Only well-formed values are kept; undefined when there are none.
+ */
+function viewMeta(q) {
+    const int = (v, max) => (typeof v === 'string' && /^\d{1,4}$/.test(v) && Number(v) >= 1 && Number(v) <= max ? Number(v) : undefined);
+    const meta = {
+        sid: typeof q.sid === 'string' && /^[0-9a-f-]{36}$/.test(q.sid) ? q.sid : undefined,
+        pos: int(q.pos, 1000),
+        page: int(q.page, 1000),
+        provisional: q.prov === '1' ? true : undefined,
+    };
+    return Object.values(meta).some((v) => v !== undefined) ? meta : undefined;
+}
+export function skillsRouter(ctx) {
+    const r = Router();
+    const { store, github } = ctx;
+    r.get('/skills/:id', async (req, res) => {
+        const skill = store.getSkill(req.params.id);
+        if (!skill) {
+            res.status(404).json({ error: '스킬을 찾을 수 없습니다' });
+            return;
+        }
+        // Only results opened from a logged search (UI debate 1-6): a page reload, a pasted link or a script reading
+        // the API would otherwise fill the log with views no search led to.
+        const meta = viewMeta(req.query);
+        if (getSettings(store).searchLog && meta?.sid)
+            store.logEvent('view', skill.id, typeof req.query.q === 'string' ? req.query.q.slice(0, 300) : null, meta);
+        const plugin = skill.plugin_id ? (store.getPlugin(skill.plugin_id) ?? null) : null;
+        const marketplace = plugin ? (store.getMarketplace(plugin.marketplace) ?? null) : null;
+        const plan = planInstall(skill, plugin, marketplace);
+        const files = (skill.files_json ? JSON.parse(skill.files_json) : { files: [], total: 0 });
+        let skillMd = null;
+        let skillMdError = null;
+        if (skill.repo && skill.ref && skill.dir_path != null) {
+            try {
+                const res2 = await github.getRawText(skill.repo, skill.ref, skill.dir_path ? `${skill.dir_path}/SKILL.md` : 'SKILL.md', MAX_FILE_BYTES);
+                if (res2.text == null)
+                    skillMdError = `SKILL.md를 가져오지 못했습니다 (${res2.status})`;
+                else
+                    skillMd = sanitizeText(res2.text) + (res2.truncated ? '\n\n…(256KB에서 잘림)' : '');
+            }
+            catch (err) {
+                skillMdError = `SKILL.md를 가져오지 못했습니다 (${String(err.message ?? err).slice(0, 100)})`;
+            }
+        }
+        const signals = plugin?.signals_json ? JSON.parse(plugin.signals_json) : null;
+        const repoMeta = skill.repo ? (store.getRepo(skill.repo) ?? null) : null;
+        // skills.sh lists it (it has a download count from there): its page also shows Gen·Socket·Snyk audits.
+        // Its page is named after the skill's folder (skillId), not the frontmatter name.
+        const skillsShId = skill.dir_path ? (skill.dir_path.split('/').pop() ?? skill.name) : skill.name;
+        const skillsSh = skill.installs != null && skill.repo
+            ? { kind: 'skillssh', label: 'skills.sh', url: `https://skills.sh/${[...skill.repo.split('/'), skillsShId].map(encodeURIComponent).join('/')}` }
+            : null;
+        const sources = [plugin ? marketplaceSource(skill, plugin) : null, githubSource(skill), skillsSh].filter(Boolean);
+        res.json({
+            id: skill.id,
+            name: skill.name,
+            description: skill.description,
+            whenToUse: skill.when_to_use,
+            // context taken: name and description with every request once installed, SKILL.md when used (estimate)
+            tokens: skillTokens(skill.name, skill.description, skillMd),
+            origin: skill.origin,
+            repo: skill.repo,
+            ref: skill.ref,
+            dirPath: skill.dir_path,
+            url: skill.repo ? treeUrl(skill.repo, skill.ref, skill.dir_path) : null,
+            sources,
+            installs: skill.installs,
+            stars: repoMeta?.stars ?? null,
+            license: repoMeta?.license ?? null,
+            archived: repoMeta?.archived === 1,
+            lastCommitAt: skill.last_commit_at,
+            frontmatter: skill.frontmatter_json ? JSON.parse(skill.frontmatter_json) : {},
+            bodyLines: skill.body_lines,
+            /** Absolute parts of the score; R and P are relative to a result set and come from the result card. */
+            partialBreakdown: { F: freshness(skill.last_commit_at), T: TRUST_SCORE[trustTier(skill, plugin)] },
+            riskLevel: skill.risk_level,
+            riskFlags: skill.risk_json ? JSON.parse(skill.risk_json) : [],
+            qualityWarnings: skill.quality_json ? JSON.parse(skill.quality_json) : [],
+            skillMd,
+            skillMdError,
+            files: files.files.map((f) => ({ path: f.path, size: f.size, isText: isTextPath(f.path) })),
+            filesTotal: files.total,
+            plugin: plugin
+                ? {
+                    id: plugin.id,
+                    name: plugin.name,
+                    displayName: plugin.display_name,
+                    description: plugin.description,
+                    marketplace: plugin.marketplace,
+                    sourceKind: plugin.source_kind,
+                    // with their risk: installing any one of them installs all (UI debate 1-1)
+                    skills: store.listSkillsByPlugin(plugin.id).map((s) => ({
+                        id: s.id,
+                        name: s.name,
+                        riskLevel: s.risk_level,
+                        riskFlags: s.risk_json ? JSON.parse(s.risk_json) : [],
+                    })),
+                    hooks: !!signals?.hooks,
+                    mcp: !!signals?.mcp,
+                    bin: !!signals?.bin,
+                    monitors: !!signals?.monitors,
+                    strictConflict: !!signals?.strictConflict,
+                }
+                : null,
+            install: plan,
+        });
+    });
+    r.get('/skills/:id/file', async (req, res) => {
+        const skill = store.getSkill(req.params.id);
+        const path = typeof req.query.path === 'string' ? req.query.path : '';
+        if (!skill || !skill.repo || !skill.ref || skill.dir_path == null) {
+            res.status(404).json({ error: '스킬을 찾을 수 없습니다' });
+            return;
+        }
+        const files = (skill.files_json ? JSON.parse(skill.files_json) : { files: [] });
+        const entry = files.files.find((f) => f.path === path);
+        if (!entry) {
+            res.status(404).json({ error: '스킬 폴더에 없는 파일입니다' });
+            return;
+        }
+        if (!isTextPath(path)) {
+            res.status(415).json({ error: '텍스트 파일만 열 수 있습니다' });
+            return;
+        }
+        if (entry.size != null && entry.size > MAX_FILE_BYTES) {
+            res.status(413).json({ error: '256KB를 넘는 파일은 열 수 없습니다' });
+            return;
+        }
+        const full = skill.dir_path ? `${skill.dir_path}/${path}` : path;
+        const out = await github.getRawText(skill.repo, skill.ref, full, MAX_FILE_BYTES).catch(() => null);
+        if (!out || out.text == null) {
+            res.status(502).json({ error: '파일을 가져오지 못했습니다' });
+            return;
+        }
+        if (out.truncated) {
+            res.status(413).json({ error: '256KB를 넘는 파일은 열 수 없습니다' });
+            return;
+        }
+        if (looksBinary(out.text)) {
+            res.status(415).json({ error: '텍스트 파일이 아닙니다' });
+            return;
+        }
+        res.json({ path, content: sanitizeText(out.text) });
+    });
+    // What the install brings besides SKILL.md (project review F1): the folder's other text files checked with the
+    // same rules, or what a plugin runs (hooks, MCP servers). Read only; asked once when the install tab opens.
+    r.get('/skills/:id/install-scan', async (req, res) => {
+        const skill = store.getSkill(req.params.id);
+        if (!skill) {
+            res.status(404).json({ error: '스킬을 찾을 수 없습니다' });
+            return;
+        }
+        const plugin = skill.plugin_id ? (store.getPlugin(skill.plugin_id) ?? null) : null;
+        const plan = planInstall(skill, plugin, plugin ? (store.getMarketplace(plugin.marketplace) ?? null) : null);
+        try {
+            if (plan.method === 'skills-cli' && skill.repo && skill.ref && skill.dir_path != null) {
+                res.json({ kind: 'files', pinned: !!plan.pinnedRef, scan: await scanSkillFiles(github, skill) });
+            }
+            else if (plan.method === 'plugin' && plan.pluginId && store.getPlugin(plan.pluginId)?.repo) {
+                res.json({ kind: 'plugin', pluginId: plan.pluginId, config: await ctx.indexer.pluginRunConfig(plan.pluginId) });
+            }
+            else {
+                res.json({ kind: 'none', reason: plan.method === 'plugin' ? '색인한 마켓플레이스에 없는 플러그인이라 실행 설정을 읽지 못했습니다' : '앱에서 설치하지 않는 스킬입니다' });
+            }
+        }
+        catch (err) {
+            res.status(502).json({ error: `설치될 파일을 읽지 못했습니다: ${String(err.message ?? err).slice(0, 200)}` });
+        }
+    });
+    r.get('/install/preview', async (req, res) => {
+        const id = typeof req.query.id === 'string' ? req.query.id : '';
+        const scope = req.query.scope;
+        const projectPath = typeof req.query.projectPath === 'string' && req.query.projectPath.trim() ? req.query.projectPath.trim() : null;
+        const skill = store.getSkill(id);
+        if (!skill) {
+            res.status(404).json({ error: '스킬을 찾을 수 없습니다' });
+            return;
+        }
+        const plugin = skill.plugin_id ? (store.getPlugin(skill.plugin_id) ?? null) : null;
+        const plan = planInstall(skill, plugin, plugin ? (store.getMarketplace(plugin.marketplace) ?? null) : null);
+        if (!plan.scopes.includes(scope)) {
+            res.json({ plan, steps: [], location: '', error: plan.method === 'manual-only' ? plan.reason : '이 방식에서 지원하지 않는 범위입니다' });
+            return;
+        }
+        if (scope !== 'user' && !isProjectDir(projectPath)) {
+            res.json({ plan, steps: [], location: '', error: '프로젝트 경로는 존재하는 디렉터리의 절대경로여야 합니다' });
+            return;
+        }
+        const steps = buildSteps(plan, scope, projectPath);
+        res.json({
+            plan,
+            steps: steps.map((s) => ({ display: s.display, cwd: s.cwd, note: s.note })),
+            location: installLocation(plan, scope, projectPath),
+            createsLockFile: plan.method === 'skills-cli' && scope === 'project',
+            // the skills CLI replaces a folder of the same name without asking (-y, D-5): say so before the install
+            existing: plan.method === 'skills-cli' && scope !== 'local' ? await existingSkillFolder(store, skill.id, plan.skillName, scope, projectPath) : null,
+        });
+    });
+    return r;
+}

package/server/src/search/activity.js

@@ -0,0 +1,13 @@
+// Counts searches in flight so background skill collection can step aside while the user is searching.
+let active = 0;
+export const searchActivity = {
+    begin() {
+        active++;
+    },
+    end() {
+        active = Math.max(0, active - 1);
+    },
+    busy() {
+        return active > 0;
+    },
+};

package/server/src/search/category.js

@@ -0,0 +1,109 @@
+import { matchTokens, stem } from "./rank.js";
+/** Result categories for the search sidebar. Korean labels live in the web app (labels.ts). */
+export const CATEGORIES = ['testing', 'review', 'git', 'ops', 'security', 'data', 'docs', 'design', 'ai', 'productivity', 'business', 'dev', 'other'];
+/**
+ * Keyword rules, no AI: a strong keyword scores 1, a weak one (common in unrelated descriptions) 0.5,
+ * doubled when it is in the skill name. Words are stemmed with the search stemmer so "tests"/"testing"
+ * and "test" line up.
+ */
+const RULES = [
+    { cat: 'testing', strong: 'test testing tests e2e playwright cypress jest vitest pytest mocha unittest coverage qa tdd mock mocks', weak: 'assertion fixture' },
+    { cat: 'review', strong: 'review reviewer lint linter eslint refactor refactoring smell smells', weak: 'quality clean cleanup readability' },
+    { cat: 'git', strong: 'git github gitlab commit commits branch branches merge rebase pr changelog worktree', weak: 'release issue issues' },
+    {
+        cat: 'ops',
+        strong: 'deploy deployment docker dockerfile container kubernetes k8s helm aws gcp azure terraform ansible ci cd devops infrastructure infra serverless vercel netlify cloudflare monitoring observability sentry datadog grafana prometheus incident sre nginx',
+        weak: 'cloud pipeline server log logs logging',
+    },
+    {
+        cat: 'security',
+        strong: 'security secure vulnerability vulnerabilities owasp cve authentication oauth secret secrets encryption threat pentest penetration exploit malware xss csrf compliance',
+        weak: 'auth audit',
+    },
+    {
+        cat: 'data',
+        strong: 'database sql postgres postgresql mysql sqlite mongodb redis supabase prisma migration migrations analytics csv pandas etl warehouse bigquery snowflake dbt dashboard visualization statistics',
+        weak: 'data query queries schema chart charts analysis',
+    },
+    {
+        cat: 'docs',
+        strong: 'pdf docx document documents documentation readme excel xlsx pptx powerpoint slide slides presentation markdown blog article copywriting spreadsheet translate translation resume',
+        weak: 'writing write content report reports docs',
+    },
+    {
+        cat: 'design',
+        // "design" is weak: "designed to …" (same stem) is common filler in descriptions.
+        strong: 'ui ux figma css tailwind styling theme accessibility a11y brand branding logo typography illustration animation canva responsive frontend landing',
+        weak: 'design designer style layout component components color colors icon icons',
+    },
+    { cat: 'ai', strong: 'llm llms subagent subagents prompt prompts mcp rag embedding embeddings openai anthropic gpt gemini chatbot eval evals', weak: 'agent agents ai model models' },
+    {
+        cat: 'productivity',
+        strong: 'productivity email gmail calendar meeting meetings notion obsidian slack jira linear asana todo standup',
+        weak: 'note notes task tasks project planning plan schedule workflow automation organize',
+    },
+    {
+        cat: 'business',
+        strong: 'seo marketing sales crm finance financial accounting legal contract contracts ecommerce shopify stripe payment payments pricing invoice recruiting',
+        weak: 'customer customers support ads growth product startup',
+    },
+    {
+        cat: 'dev',
+        strong: 'typescript javascript python rust golang java kotlin swift ruby php node nodejs react vue angular svelte nextjs django flask rails spring api apis backend debug debugging bug bugs cli sdk mobile ios android flutter',
+        weak: 'library framework architecture implement implementation function',
+    },
+];
+const KEYWORDS = new Map();
+for (const r of RULES) {
+    for (const [words, w] of [
+        [r.strong, 1],
+        [r.weak ?? '', 0.5],
+    ]) {
+        for (const word of words.split(' ').filter(Boolean)) {
+            const key = stem(word);
+            const list = KEYWORDS.get(key) ?? [];
+            if (!list.some((x) => x.cat === r.cat))
+                list.push({ cat: r.cat, w });
+            KEYWORDS.set(key, list);
+        }
+    }
+}
+/** Marketplace `category` values seen in the index. Generic ones only count when no keyword matches. */
+const MARKETPLACE_SPECIFIC = {
+    productivity: 'productivity',
+    automation: 'productivity',
+    database: 'data',
+    math: 'data',
+    migration: 'data',
+    monitoring: 'ops',
+    deployment: 'ops',
+    security: 'security',
+    design: 'design',
+    testing: 'testing',
+    finance: 'business',
+};
+const MARKETPLACE_GENERIC = { development: 'dev', 'developer tools': 'dev' };
+const MAX_CATEGORIES = 2;
+export function categorize(skill) {
+    const scores = new Map();
+    const name = new Set(matchTokens(skill.name.replace(/[-_.]+/g, ' ')));
+    const text = new Set(matchTokens([skill.description ?? '', skill.whenToUse ?? ''].join(' ')));
+    for (const token of new Set([...name, ...text])) {
+        for (const { cat, w } of KEYWORDS.get(token) ?? [])
+            scores.set(cat, (scores.get(cat) ?? 0) + w * (name.has(token) ? 2 : 1));
+    }
+    const mp = skill.marketplaceCategory?.trim().toLowerCase() ?? '';
+    const out = [];
+    if (MARKETPLACE_SPECIFIC[mp])
+        out.push(MARKETPLACE_SPECIFIC[mp]);
+    const ranked = [...scores].filter(([, s]) => s >= 1).sort((a, b) => b[1] - a[1] || CATEGORIES.indexOf(a[0]) - CATEGORIES.indexOf(b[0]));
+    // A second category must be more than half as strong as the first: one stray word in the
+    // description ("encrypting" in the pdf skill) should not add 보안 next to a name match.
+    const top = ranked[0]?.[1] ?? 0;
+    for (const [c, s] of ranked)
+        if (out.length < MAX_CATEGORIES && !out.includes(c) && (s === top || s > top / 2))
+            out.push(c);
+    if (out.length === 0)
+        out.push(MARKETPLACE_GENERIC[mp] ?? 'other');
+    return out;
+}