@seojin08/skill-finder 0.0.0-stage → 0.3.2

package/.env.example

@@ -0,0 +1,3 @@
+# GitHub fine-grained PAT (public repo read only; no extra permissions needed)
+GITHUB_TOKEN=
+PORT=4317

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# 변경 기록
+
+새 버전의 항목은 `npm run package`가 내려받기 페이지의 meta.json에 서명과 함께 넣고, 앱의 "새 버전" 표시를 누르면 보입니다. 한 줄이 한 항목입니다.
+
+## 0.3.2 (2026-11-02)
+
+- 영어·일본어 화면에서 숫자·이름·명령이 끼는 문장이 그 언어의 어순으로 자연스럽게 나옵니다.
+- 검색이 아직 확인 중인 결과에도 즐겨찾기 별을 누를 수 있습니다. 별을 바꾸지 못하면 별 아래에 이유가 보입니다.
+- 설치 확인 창의 skills CLI 명령이 어디서나 실행할 수 있는 npx skills@1.7.4 모양으로 보입니다.
+- 설정 화면에서 라이선스(MIT)와 함께 들어 있는 오픈소스의 라이선스 목록을 볼 수 있습니다.
+
+## 0.3.1 (2026-11-02)
+
+- 즐겨찾기에 로그인이 필요 없습니다. 별을 누르면 바로 모이고, 위쪽 메뉴의 즐겨찾기(★)에서 봅니다.
+- 0.3.0에서 만든 계정의 즐겨찾기는 그대로 옮겨지고, 계정 정보는 지워집니다.
+
+## 0.3.0 (2026-11-02)
+
+- 영어·일본어 화면을 고를 수 있습니다(설정).
+- 회원가입·로그인 뒤 스킬에 별을 눌러 즐겨찾기로 모읍니다. 계정은 이 PC 안에만 저장됩니다.
+- 팀 프리셋: 설치된 스킬을 파일로 내보내고, 팀원의 파일로 같은 스킬을 확인 창을 거쳐 설치합니다.
+- 공유 링크: 앱이 없는 사람도 스킬의 위험 신호와 설치 명령을 볼 수 있는 페이지를 만듭니다.
+- npx로 macOS·Linux에서도 실행하고, Claude Code 안에서 쓰는 읽기 전용 명령(skill-finder search 등)을 더했습니다.
+- 업데이트는 서명을 확인한 뒤에만 설치합니다.
+- Anthropic 공식·파트너 스킬은 별 기준과 상관없이 보입니다.
+- "스크립트 포함"만 있는 스킬은 이제 "주의"가 아니라 "낮음"입니다(공식 pdf·docx 등).
+- 한 단어 검색에서 같은 이름 저장소의 기여자용 스킬이 위를 채우지 않습니다.
+- README가 없으면 CLAUDE.md·AGENTS.md로 추천합니다.
+- 결과 카드의 점수 막대를 빼고, 쪽당 결과는 기본 10개입니다.
+
+## 0.2.0 (2026-10-30)
+
+- 실행기(SkillFinder.exe): 바탕화면 바로가기, 쓰는 중인 포트를 피하는 포트 선택, 자동 업데이트와 실패 시 되돌리기.
+- 설치 확인 창이 함께 들어오는 파일을 검사하고, 같은 이름 폴더를 덮어쓰기 전에 묻습니다.
+- 검색·설치 화면의 접근성·좁은 화면·공유·내보내기를 다듬었습니다.
+
+## 0.1.0 (2026-10-27)
+
+- 첫 배포: 마켓플레이스·skills.sh·GitHub 통합 검색, 위험 신호와 점수, README 추천, 설치·삭제.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Parkseojin08
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# Skill Finder
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Claude Code 스킬을 한곳에서 찾아 점수·위험 신호와 함께 보고, 설치 전에 무엇이 함께 들어오는지 확인한 뒤 설치·삭제하는 로컬 웹 앱입니다. 화면은 한국어·영어·일본어입니다.
+
+> **English:** A local web app (127.0.0.1) that searches Claude Code skills across plugin marketplaces, skills.sh and GitHub, scores them, flags risky signals, and installs or removes them only after showing the exact command, the install location and the files that come along. No AI calls; the UI is in Korean, English or Japanese (Settings). Run it with `npx @seojin08/skill-finder` on Windows, macOS or Linux.
+
+## 무엇을 하나요
+
+- **세 곳을 한 번에 검색**: Claude Code 플러그인 마켓플레이스, skills.sh, GitHub(토큰을 넣으면 코드 검색까지). 같은 스킬의 사본은 하나로 묶습니다.
+- **설치 전에 보여 주기**: 실행할 정확한 명령, 설치 위치, 함께 들어오는 파일 검사(내려받아 실행하는 코드 등), 위험 신호(훅, MCP 서버, Bash 사전 승인, 셸 명령 주입, 원격 스크립트 실행). 위험 등급은 규칙으로 판정한 것이며 안전 보증이 아닙니다.
+- **점수**: 관련도·인기(다운로드·별)·최신성·신뢰도(Anthropic 공식·파트너·커뮤니티). 결과는 이름 일치 → 다운로드 → 별 순서로 정렬합니다.
+- **README 추천**: 프로젝트 폴더의 README(없으면 package.json 같은 설명 파일과 CLAUDE.md·AGENTS.md)에서 단어를 뽑아 비슷한 스킬을 보여 줍니다.
+- **설치됨**: 설치된 플러그인·스킬, 매 턴·사용 시 컨텍스트 토큰 추정, 설치 기록, 삭제.
+- **공유·내보내기**: 설치 명령·Markdown 한 줄·공유용 글·공유 링크(앱 없이 열리는 페이지) 복사, 검색 결과와 설치 목록을 JSON·Markdown으로 저장(브라우저 안에서만).
+- **팀 프리셋·즐겨찾기**: 설치된 스킬을 파일로 내보내 팀원이 같은 스킬을 확인 창을 거쳐 설치하고, 별을 눌러 즐겨찾기를 모읍니다(로그인 없음, 이 PC에만 저장).
+- **언어**: 한국어·English·日本語 (설정에서 고름).
+
+## 설치
+
+### Windows
+
+[소개 페이지](https://skill-finder.a01075011775.workers.dev)에서 zip을 받아 압축을 풀고 `SkillFinder.exe`를 실행합니다. 서버를 켜고 브라우저를 열며, 새 버전이 나오면 서명을 확인한 뒤 업데이트합니다.
+
+### macOS·Linux·Windows (npx)
+
+Node.js 22.18 이상이 있으면 설치 없이 실행합니다. 데이터는 사용자 폴더(macOS `~/Library/Application Support/Skill Finder`, Linux `~/.local/share/skill-finder`, Windows `%LOCALAPPDATA%\SkillFinder\npx-data`)에 남습니다.
+
+```bash
+npx @seojin08/skill-finder
+```
+
+### Claude Code 안에서 쓰기
+
+같은 명령에 읽기 전용 하위 명령이 있습니다. 앱이 꺼져 있으면 백그라운드로 켜고 결과만 출력하므로, Claude Code에게 "skill-finder로 pdf 스킬 찾아 줘"처럼 시킬 수 있습니다. 설치·삭제는 하지 않습니다(앱 화면의 확인 창에서만).
+
+```bash
+npx @seojin08/skill-finder search "pdf tables" --limit 5
+npx @seojin08/skill-finder show gh:anthropics/skills:skills/pdf
+npx @seojin08/skill-finder recommend          # 지금 폴더의 README와 비슷한 스킬
+npx @seojin08/skill-finder installed --json
+npx @seojin08/skill-finder stop               # 백그라운드로 켠 앱 끄기
+```
+
+`--json`은 기계가 읽는 출력, `--lang ko|en|ja`는 출력 언어입니다. 자주 쓰면 `npm install -g @seojin08/skill-finder`로 설치해 `skill-finder search …`처럼 짧게 부를 수 있습니다.
+
+### 소스에서
+
+필요한 것: Node.js 22.18 이상(24 권장), git, Claude Code(`claude` 명령).
+
+```bash
+npm install
+npm start
+```
+
+이 저장소를 내려받은 폴더에서 실행한 뒤 브라우저로 http://127.0.0.1:4317 을 엽니다. 첫 실행 때는 스킬 색인을 모으느라 몇 분 걸립니다.
+
+GitHub 토큰은 선택입니다. 설정 화면에서 넣거나 `.env`의 `GITHUB_TOKEN`에 적습니다(`.env.example` 참고). 공개 저장소 읽기만 되는 fine-grained 토큰이면 되고, GitHub 코드 검색과 빠른 색인에 쓰입니다.
+
+## 안전과 개인 정보
+
+- 서버는 127.0.0.1에만 열리고, Host 허용 목록·전용 요청 헤더·같은 출처 검사로 다른 사이트의 요청을 막습니다.
+- 설치·삭제는 확인 창을 거친 뒤 `claude plugin` 또는 skills CLI를 셸 없이 실행합니다. 앱이 원격 스킬의 코드를 직접 실행하지 않습니다.
+- 검색·추천에 AI를 부르지 않습니다. 설명 번역은 브라우저에 들어 있는 Translator API만 씁니다.
+- 밖으로 나가는 요청은 GitHub API, skills.sh 검색, 마켓플레이스 저장소, 업데이트 확인뿐입니다.
+- 색인과 설정은 `data/`(SQLite)에 남습니다. 검색 기록은 설정에서 끌 수 있습니다.
+
+## 개발
+
+```bash
+npm run dev        # 서버(--watch) + Vite
+npm test           # 서버·웹 테스트
+npm run typecheck
+```
+
+- `server/`: Node가 TypeScript를 그대로 실행합니다(타입만 지우는 문법, import에 `.ts`). Express 5, `node:sqlite`.
+- `web/`: React 19 + Vite, Tailwind v4 + shadcn/ui.
+- `docs/DECISIONS.md`: 처음 명세와 다르게 정한 것들의 기록입니다. 고칠 때 먼저 확인하세요.
+
+## 문제 신고
+
+버그와 제안은 GitHub 이슈로 남겨 주세요. 설정 화면의 "진단 정보 복사" 내용을 붙이면 원인을 찾기 쉽습니다. 보안 문제는 [SECURITY.md](SECURITY.md)를 보세요.
+
+## 라이선스
+
+[MIT](LICENSE) © 2026 Parkseojin08. 누구나 쓰고 고치고 배포할 수 있으며, 복사본에는 저작권 표시와 라이선스 문구를 함께 두면 됩니다(보증 없음).
+
+웹 화면에 함께 묶이는 오픈소스(React, Base UI, react-markdown 등)의 라이선스는 빌드할 때 `web/dist/THIRD-PARTY-LICENSES.txt`로 만들어지고, 앱의 설정 화면 "라이선스"에서 볼 수 있습니다.

package/bin/skill-finder.mjs

@@ -0,0 +1,389 @@
+#!/usr/bin/env node
+// Skill Finder on Windows, macOS and Linux: `npx @seojin08/skill-finder` (the npm package) or `node bin/skill-finder.mjs`
+// (a checkout). With no command it starts the local app and opens the browser. `search`, `show`, `recommend` and
+// `installed` read from the app, starting it in the background when it is not running, and print text or --json,
+// so Claude Code can call them from its shell. Nothing here installs or removes a skill: that stays in the app,
+// behind its confirm dialog (user decision 2026-11-02).
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const VERSION = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version ?? '?';
+// the npm package ships compiled JavaScript (Node does not strip types under node_modules); a checkout runs the TS
+const PACKAGED = existsSync(join(ROOT, 'server', 'src', 'index.js'));
+const ENTRY = join(ROOT, 'server', 'src', PACKAGED ? 'index.js' : 'index.ts');
+const DEFAULT_PORT = 4317;
+
+// ── messages ─────────────────────────────────────────────────────────────────────────────────────────────────
+const LANGS = ['ko', 'en', 'ja'];
+const T = {
+  ko: {
+    usage: `Skill Finder ${VERSION} — Claude Code 스킬 검색 (읽기 전용 명령)
+
+사용법:
+  skill-finder                     앱을 켜고 브라우저를 엽니다
+  skill-finder search <검색어>     스킬을 찾습니다 (--limit N, --risk low|medium|high)
+  skill-finder show <id>           스킬 하나의 위험 신호와 설치 명령
+  skill-finder recommend [폴더]    프로젝트 README와 비슷한 스킬 (기본: 지금 폴더)
+  skill-finder installed [폴더]    설치된 플러그인·스킬
+  skill-finder stop                이 명령이 백그라운드로 켠 앱을 끕니다
+
+공통: --json(기계가 읽는 출력), --port N, --no-open, --lang ko|en|ja
+설치·삭제는 앱 화면의 확인 창에서만 합니다.`,
+    node: (v) => `Node.js ${v}는 너무 오래됐습니다. 22.18 이상이 필요합니다: https://nodejs.org`,
+    noWeb: '웹 화면이 빌드되지 않았습니다. 먼저 npm run build를 실행하세요.',
+    starting: (p) => `Skill Finder를 켜는 중입니다 (127.0.0.1:${p})…`,
+    background: (p) => `Skill Finder를 백그라운드로 켰습니다 (127.0.0.1:${p}). 끄려면: skill-finder stop`,
+    running: (p) => `Skill Finder가 이미 켜져 있습니다: http://127.0.0.1:${p}`,
+    ready: (p) => `준비됐습니다: http://127.0.0.1:${p}  (끄려면 Ctrl+C)`,
+    busy: (p, q) => `포트 ${p}를 다른 프로그램이 쓰고 있어 ${q}를 씁니다.`,
+    timeout: '서버가 60초 안에 응답하지 않았습니다.',
+    first: '처음 켜면 스킬 색인을 모으느라 몇 분 걸릴 수 있습니다.',
+    stopped: 'Skill Finder를 껐습니다.',
+    notMine: '이 명령이 켠 Skill Finder가 없습니다 (앱 창이나 실행기로 켠 것은 거기서 끄세요).',
+    none: '결과가 없습니다.',
+    needQuery: '검색어를 넣으세요. 예: skill-finder search "pdf tables"',
+    needId: '스킬 id를 넣으세요 (search 결과의 id). 예: skill-finder show gh:anthropics/skills:skills/pdf',
+    install: '설치',
+    noInstall: '앱에서 설치 불가',
+    risk: { low: '위험 낮음', medium: '주의', high: '위험 높음' },
+    note: '위험 등급은 규칙 판정이며 안전 보증이 아닙니다. 설치는 앱의 확인 창에서 하세요.',
+    plugins: '플러그인',
+    skills: '스킬',
+    readFrom: (f) => `읽은 파일: ${f}`,
+    failed: (m) => `실패: ${m}`,
+  },
+  en: {
+    usage: `Skill Finder ${VERSION} — find Claude Code skills (read-only commands)
+
+Usage:
+  skill-finder                     start the app and open the browser
+  skill-finder search <query>      find skills (--limit N, --risk low|medium|high)
+  skill-finder show <id>           one skill's risk signals and install command
+  skill-finder recommend [folder]  skills like the project's README (default: this folder)
+  skill-finder installed [folder]  installed plugins and skills
+  skill-finder stop                stop the app this command started in the background
+
+Common: --json (machine-readable), --port N, --no-open, --lang ko|en|ja
+Installing and removing happen only in the app's confirm dialog.`,
+    node: (v) => `Node.js ${v} is too old. 22.18 or later is needed: https://nodejs.org`,
+    noWeb: 'The web app is not built. Run npm run build first.',
+    starting: (p) => `Starting Skill Finder (127.0.0.1:${p})…`,
+    background: (p) => `Started Skill Finder in the background (127.0.0.1:${p}). To stop it: skill-finder stop`,
+    running: (p) => `Skill Finder is already running: http://127.0.0.1:${p}`,
+    ready: (p) => `Ready: http://127.0.0.1:${p}  (Ctrl+C to stop)`,
+    busy: (p, q) => `Port ${p} is used by another program; using ${q}.`,
+    timeout: 'The server did not answer within 60 seconds.',
+    first: 'The first start gathers the skill index and can take a few minutes.',
+    stopped: 'Stopped Skill Finder.',
+    notMine: 'No Skill Finder started by this command (stop one started by the app or launcher there).',
+    none: 'No results.',
+    needQuery: 'Give a query. Example: skill-finder search "pdf tables"',
+    needId: 'Give a skill id (the id in search results). Example: skill-finder show gh:anthropics/skills:skills/pdf',
+    install: 'Install',
+    noInstall: 'not installable from the app',
+    risk: { low: 'Low risk', medium: 'Caution', high: 'High risk' },
+    note: 'Risk levels come from rules and are not a safety guarantee. Install from the app’s confirm dialog.',
+    plugins: 'Plugins',
+    skills: 'Skills',
+    readFrom: (f) => `Read: ${f}`,
+    failed: (m) => `Failed: ${m}`,
+  },
+  ja: {
+    usage: `Skill Finder ${VERSION} — Claude Code スキル検索(読み取り専用のコマンド)
+
+使い方:
+  skill-finder                     アプリを起動してブラウザを開く
+  skill-finder search <検索語>     スキルを探す (--limit N, --risk low|medium|high)
+  skill-finder show <id>           スキルのリスク信号とインストールコマンド
+  skill-finder recommend [フォルダ] プロジェクトの README に似たスキル(既定: 今のフォルダ)
+  skill-finder installed [フォルダ] インストール済みのプラグイン・スキル
+  skill-finder stop                このコマンドがバックグラウンドで起動したアプリを止める
+
+共通: --json(機械向け出力), --port N, --no-open, --lang ko|en|ja
+インストールと削除はアプリの確認画面でのみ行います。`,
+    node: (v) => `Node.js ${v} は古すぎます。22.18 以上が必要です: https://nodejs.org`,
+    noWeb: 'Web 画面がビルドされていません。先に npm run build を実行してください。',
+    starting: (p) => `Skill Finder を起動しています (127.0.0.1:${p})…`,
+    background: (p) => `Skill Finder をバックグラウンドで起動しました (127.0.0.1:${p})。止めるには: skill-finder stop`,
+    running: (p) => `Skill Finder はすでに起動しています: http://127.0.0.1:${p}`,
+    ready: (p) => `準備ができました: http://127.0.0.1:${p}  (Ctrl+C で終了)`,
+    busy: (p, q) => `ポート ${p} は別のプログラムが使っているため ${q} を使います。`,
+    timeout: 'サーバーが 60 秒以内に応答しませんでした。',
+    first: '初回起動ではスキルの索引を集めるため数分かかることがあります。',
+    stopped: 'Skill Finder を止めました。',
+    notMine: 'このコマンドが起動した Skill Finder はありません(アプリやランチャーで起動したものはそちらで止めてください)。',
+    none: '結果がありません。',
+    needQuery: '検索語を入れてください。例: skill-finder search "pdf tables"',
+    needId: 'スキル id を入れてください(search 結果の id)。例: skill-finder show gh:anthropics/skills:skills/pdf',
+    install: 'インストール',
+    noInstall: 'アプリからインストールできません',
+    risk: { low: 'リスク低', medium: '注意', high: 'リスク高' },
+    note: 'リスクの判定はルールによる目安で、安全の保証ではありません。インストールはアプリの確認画面で行ってください。',
+    plugins: 'プラグイン',
+    skills: 'スキル',
+    readFrom: (f) => `読んだファイル: ${f}`,
+    failed: (m) => `失敗: ${m}`,
+  },
+};
+
+// ── arguments ────────────────────────────────────────────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+const flag = (name) => {
+  const i = args.indexOf(name);
+  if (i < 0) return false;
+  args.splice(i, 1);
+  return true;
+};
+const option = (name) => {
+  const i = args.indexOf(name);
+  if (i < 0 || i === args.length - 1) return null;
+  const v = args[i + 1];
+  args.splice(i, 2);
+  return v;
+};
+const json = flag('--json');
+const noOpen = flag('--no-open');
+const langArg = option('--lang');
+const portArg = option('--port');
+const limit = Math.min(50, Math.max(1, Number(option('--limit')) || 10));
+const risk = option('--risk');
+const systemLang = (process.env.SKILL_FINDER_LANG || Intl.DateTimeFormat().resolvedOptions().locale || 'en').slice(0, 2).toLowerCase();
+const lang = LANGS.includes(langArg) ? langArg : LANGS.includes(systemLang) ? systemLang : 'en';
+const t = T[lang];
+const [command = 'start', ...rest] = args;
+
+// ── where the app lives ──────────────────────────────────────────────────────────────────────────────────────
+/** A checkout keeps its data in ./data as `npm start` does; the package keeps it per user, outside the npm cache. */
+function dataDir() {
+  if (process.env.SKILL_FINDER_DATA_DIR) return process.env.SKILL_FINDER_DATA_DIR;
+  if (!PACKAGED) return join(ROOT, 'data');
+  if (process.platform === 'win32') return join(process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local'), 'SkillFinder', 'npx-data');
+  if (process.platform === 'darwin') return join(homedir(), 'Library', 'Application Support', 'Skill Finder');
+  return join(process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share'), 'skill-finder');
+}
+const DATA = dataDir();
+const PID_FILE = join(DATA, 'cli-server.json');
+
+async function health(port) {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/api/health`, { headers: { 'X-Skill-Finder': '1' }, signal: AbortSignal.timeout(1500) });
+    const h = res.ok ? await res.json() : null;
+    return h?.app === 'skill-finder' ? h : null;
+  } catch {
+    return null;
+  }
+}
+const portFree = (port) =>
+  new Promise((done) => {
+    const s = createServer();
+    s.once('error', () => done(false));
+    s.listen(port, '127.0.0.1', () => s.close(() => done(true)));
+  });
+
+/** A running Skill Finder's port, or null. */
+async function findRunning() {
+  // a port given with --port is the only one: another Skill Finder elsewhere is not the one asked for
+  const ports = Number(portArg) ? [Number(portArg)] : [...new Set([Number(process.env.PORT) || 0, DEFAULT_PORT, readPid()?.port ?? 0].filter(Boolean))];
+  for (const p of ports) if (await health(p)) return p;
+  return null;
+}
+
+function readPid() {
+  try {
+    return JSON.parse(readFileSync(PID_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Starts the server: in this terminal (`start`), or detached for the read commands. Resolves its port. */
+async function startServer(background) {
+  const [major, minor] = process.versions.node.split('.').map(Number);
+  if (major < 22 || (major === 22 && minor < 18)) throw new Error(t.node(process.versions.node));
+  if (!existsSync(join(ROOT, 'web', 'dist', 'index.html'))) throw new Error(t.noWeb);
+  let port = Number(portArg) || Number(process.env.PORT) || DEFAULT_PORT;
+  if (!(await portFree(port))) {
+    let next = port + 1;
+    while (next < port + 50 && !(await portFree(next))) next++;
+    if (!json) console.error(t.busy(port, next));
+    port = next;
+  }
+  mkdirSync(DATA, { recursive: true });
+  const env = { ...process.env, PORT: String(port), SKILL_FINDER_DATA_DIR: DATA };
+  if (PACKAGED) env.SKILL_FINDER_ENV_PATH = process.env.SKILL_FINDER_ENV_PATH || join(DATA, '.env');
+  if (!json) console.error(background ? t.starting(port) : `${t.starting(port)}\n${t.first}`);
+  const child = spawn(process.execPath, ['--disable-warning=ExperimentalWarning', ENTRY], {
+    cwd: ROOT,
+    env,
+    stdio: background ? 'ignore' : 'inherit',
+    detached: background,
+    windowsHide: true,
+  });
+  if (background) {
+    writeFileSync(PID_FILE, JSON.stringify({ pid: child.pid, port }));
+    child.unref();
+  }
+  const until = Date.now() + 60_000;
+  while (Date.now() < until) {
+    if (await health(port)) return { port, child };
+    if (child.exitCode != null) break;
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  throw new Error(t.timeout);
+}
+
+function openBrowser(url) {
+  const [cmd, cmdArgs] =
+    process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] : process.platform === 'darwin' ? ['open', [url]] : ['xdg-open', [url]];
+  spawn(cmd, cmdArgs, { stdio: 'ignore', detached: true, windowsHide: true }).on('error', () => {}).unref();
+}
+
+/** The app's API, the way its own page calls it (header, same origin). */
+async function api(port, method, path, body) {
+  const res = await fetch(`http://127.0.0.1:${port}/api${path}`, {
+    method,
+    headers: { 'X-Skill-Finder': '1', Origin: `http://127.0.0.1:${port}`, ...(body ? { 'Content-Type': 'application/json' } : {}) },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  if (!res.ok) throw new Error((() => { try { return JSON.parse(text).error; } catch { return `${res.status}`; } })());
+  return text;
+}
+
+async function ensureRunning() {
+  const running = await findRunning();
+  if (running) return running;
+  const { port } = await startServer(true);
+  if (!json) console.error(t.background(port));
+  return port;
+}
+
+// ── output ───────────────────────────────────────────────────────────────────────────────────────────────────
+const count = (n) => (n == null ? '-' : n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : n >= 1e3 ? `${(n / 1e3).toFixed(1)}K` : String(n));
+const repoOf = (id) => id.match(/^gh:([^:]+):/)?.[1] ?? '';
+const brief = (it) => ({
+  id: it.id,
+  name: it.name,
+  description: it.description,
+  repo: repoOf(it.id) || null,
+  installs: it.installs ?? null,
+  stars: it.stars ?? null,
+  riskLevel: it.riskLevel,
+  riskFlags: it.riskFlags,
+  installMethod: it.install?.method ?? null,
+  installCommand: it.install?.command || null,
+  url: it.sources?.find((s) => s.url)?.url ?? null,
+});
+function printItems(items) {
+  if (json) return console.log(JSON.stringify(items.map(brief), null, 2));
+  if (!items.length) return console.log(t.none);
+  for (const it of items) {
+    const b = brief(it);
+    console.log(`${b.name}  [${t.risk[b.riskLevel] ?? b.riskLevel}]  ↓${count(b.installs)} ★${count(b.stars)}${b.repo ? `  ${b.repo}` : ''}`);
+    if (b.description) console.log(`  ${b.description.replace(/\s+/g, ' ').slice(0, 160)}`);
+    console.log(`  id: ${b.id}`);
+  }
+  console.log(`\n${t.note}`);
+}
+
+// ── commands ─────────────────────────────────────────────────────────────────────────────────────────────────
+async function main() {
+  if (command === '--help' || command === '-h' || command === 'help') return console.log(t.usage);
+  if (command === '--version' || command === '-v') return console.log(VERSION);
+
+  if (command === 'start') {
+    const running = await findRunning();
+    if (running) {
+      console.log(t.running(running));
+      if (!noOpen) openBrowser(`http://127.0.0.1:${running}`);
+      return;
+    }
+    const { port, child } = await startServer(false);
+    console.log(t.ready(port));
+    if (!noOpen) openBrowser(`http://127.0.0.1:${port}`);
+    for (const sig of ['SIGINT', 'SIGTERM']) process.on(sig, () => child.kill(sig));
+    await new Promise((r) => child.on('exit', r));
+    return;
+  }
+
+  if (command === 'stop') {
+    const p = readPid();
+    // only the server this command started, still running as the same process (a stale pid may be anything now)
+    const h = p?.pid ? await health(p.port) : null;
+    if (!h || h.pid !== p.pid) {
+      rmSync(PID_FILE, { force: true });
+      return console.log(t.notMine);
+    }
+    process.kill(p.pid);
+    rmSync(PID_FILE, { force: true });
+    return console.log(t.stopped);
+  }
+
+  if (command === 'search') {
+    const query = rest.join(' ').trim();
+    if (!query) throw new Error(t.needQuery);
+    const port = await ensureRunning();
+    const filters = ['low', 'medium', 'high'].includes(risk) ? { maxRisk: risk } : undefined;
+    const lines = (await api(port, 'POST', '/search', { query, filters })).trim().split('\n').map((l) => JSON.parse(l));
+    // the last one: a slow search sends interim results first, then the final ones
+    const results = lines.filter((e) => e.type === 'results').at(-1);
+    return printItems((results?.items ?? []).slice(0, limit));
+  }
+
+  if (command === 'show') {
+    const id = rest[0];
+    if (!id) throw new Error(t.needId);
+    const port = await ensureRunning();
+    const d = JSON.parse(await api(port, 'GET', `/skills/${encodeURIComponent(id)}`));
+    if (json) return console.log(JSON.stringify({ ...brief(d), whenToUse: d.whenToUse ?? null }, null, 2));
+    printItems([d]);
+    const cmd = d.install?.command;
+    console.log(cmd ? `${t.install}: ${cmd}` : t.noInstall);
+    return;
+  }
+
+  if (command === 'recommend') {
+    const projectPath = resolve(rest[0] ?? process.cwd());
+    const port = await ensureRunning();
+    const r = JSON.parse(await api(port, 'POST', '/readme-skills', { projectPath }));
+    if (!json && r.readmePath) console.log(t.readFrom([r.readmePath, ...(r.alsoRead ?? [])].join(' + ')));
+    return printItems(r.skills.map((s) => s.item).slice(0, limit));
+  }
+
+  if (command === 'installed') {
+    const projectPath = rest[0] ? resolve(rest[0]) : undefined;
+    const port = await ensureRunning();
+    const q = projectPath ? `?projectPath=${encodeURIComponent(projectPath)}` : '';
+    const d = JSON.parse(await api(port, 'GET', `/installed${q}`));
+    if (json) {
+      return console.log(
+        JSON.stringify(
+          {
+            plugins: d.plugins.map((p) => ({ id: p.id, scope: p.scope, version: p.version, topRisk: p.topRisk })),
+            skills: d.skills.map((s) => ({ name: s.name, scope: s.scope, path: s.path, riskLevel: s.risk.level, id: s.skillId })),
+          },
+          null,
+          2,
+        ),
+      );
+    }
+    console.log(`${t.plugins} (${d.plugins.length})`);
+    for (const p of d.plugins) console.log(`  ${p.id}  [${p.scope}]${p.topRisk ? `  ${t.risk[p.topRisk]}` : ''}`);
+    console.log(`${t.skills} (${d.skills.length})`);
+    for (const s of d.skills) console.log(`  ${s.name}  [${s.scope}]  ${t.risk[s.risk.level]}`);
+    return;
+  }
+
+  console.log(t.usage);
+  process.exitCode = 2;
+}
+
+main().catch((e) => {
+  console.error(t.failed(String(e?.message ?? e)));
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@seojin08/skill-finder",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.2",
+  "description": "Find Claude Code skills across marketplaces, skills.sh and GitHub, see their risk signals, and install them after checking what comes along. Local web app and read-only CLI.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "skill-finder": "bin/skill-finder.mjs"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "dependencies": {
+    "express": "5.3.0",
+    "skills": "1.7.4",
+    "yaml": "2.9.1",
+    "zod": "4.6.7"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Parkseojin08/skill-finder.git"
+  },
+  "homepage": "https://skill-finder.a01075011775.workers.dev",
+  "bugs": "https://github.com/Parkseojin08/skill-finder/issues",
+  "keywords": [
+    "claude-code",
+    "claude-skills",
+    "agent-skills",
+    "skills",
+    "cli"
+  ],
+  "files": [
+    "bin",
+    "server",
+    "web/dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    ".env.example"
+  ]
+}