niyogilabs/SkillSpectorWeb

SkillSpector 브라우저 포팅 및 업그레이드 방법론

이 스킬은 SkillSpector Python 보안 스캐너의 새 버전을 100% 브라우저에서 실행되는 WebAssembly / 자바스크립트 웹 애플리케이션(SkillSpectorWeb)으로 포팅하는 단계별 지침을 제공합니다.

---

🎯 아키텍처 원칙

1. 100% 클라이언트 측 브라우저 실행:

   • 스캐너는 백엔드 서버 없이 사용자의 브라우저에서 완전히 실행되어야 합니다.
   • 모든 GitHub 리포지토리 콘텐츠는 GitHub REST API(api.github.com 및 raw.githubusercontent.com)를 통해 가져옵니다.

2. 엄격한 모듈 격리:

   • 코어 스캐너 엔진 (docs/js/skillspector-engine.js): Python nodes/analyzers/와 일치하는 순수 번역된 정적 분석 규칙.
   • 격리된 저장소 필터 (docs/js/repo-filter.js): 사용자 정의 비스킬 파일 필터링(README.md, CHANGELOG.md, .git/ 등)을 번역된 스캐너 코드와 분리하여 유지.
   • GitHub 가져오기 (docs/js/github-fetcher.js): URL 파싱, 트리 확장, 배치 다운로드 처리.

3. 멀티 스킬 리포지토리 지원:

   • src/skillspector/multi_skill.py를 미러링하여 리포지토리 전체(resources/skills/*.md, skills/*.md, agents/*.md)에서 중첩된 모든 스킬을 발견해야 합니다.

4. 라이선스 및 버전 일치:

   • 업스트림 Python SkillSpector 릴리스와 일치하는 정확한 버전 번호(vX.Y.Z)를 유지합니다.
   • 편집되지 않은 업스트림 LICENSE(Apache 2.0)를 보존합니다.

---

📋 단계별 포팅 워크플로우

1단계: 규칙 및 AST 분석 추출

1. 업스트림 src/skillspector/nodes/analyzers/의 새 분석기 규칙을 검사합니다.
   • pattern_defaults.py (규칙 ID: P1-P8, E1-E5, PE1-PE3, SC1-SC7, EA1-EA4, OH1-OH3, MP1-MP3, TM1-TM4, RA1-RA2, TR1-TR3, MCP1).
2. 새 Python 정규식 및 AST 검사를 docs/js/skillspector-engine.js 내부의 JavaScript RegExp 패턴으로 변환합니다.
3. 카테고리 목록, 규칙 설명, 설명 및 수정 가이드를 업데이트합니다.

2단계: GitHub 가져오기 및 트리 확장

1. docs/js/github-fetcher.js가 https://api.github.com/repos/{owner}/{repo}/git/trees/{branch}?recursive=1를 통해 재귀적 트리 구조를 가져오도록 합니다.
2. 작은 임의 파일 제한으로 가져오기를 제한하지 마십시오 (대규모 멀티 스킬 리포지토리를 지원하기 위해 최대 250개 파일까지 높은 임계값 사용).
3. 라이브 UI 진행 콜백(onProgress(current, total, filename))과 함께 병렬 배치 가져오기(예: 배치당 10개 파일)를 사용합니다.

3단계: 멀티 스킬 발견 엔진

1. skillspector-engine.js에 discoverSkills(filesMap)를 구현합니다.
2. 리포지토리의 모든 .md 파일에 대해 Markdown 프론트매터 YAML(--- name: ... description: ... ---)을 구문 분석합니다.
3. index.html에 멀티 스킬 선택기 막대를 렌더링하여 사용자가 개별 발견된 스킬별로 결과를 필터링하거나 전체 리포지토리 컨텍스트를 검사할 수 있도록 합니다.

4단계: 격리된 리포지토리 파일 필터링

1. docs/js/repo-filter.js를 코어 스캐너 엔진과 완전히 분리하여 유지합니다.
2. index.html에 UI 체크박스를 제공합니다.
   • 표준 저장소 문서 생략 (README, CHANGELOG, LICENSE)
   • 시스템 메타데이터 생략 (.git/, .github/, dotfiles)
3. 생략된 파일을 검사 원장에 skipped 항목으로 명시적 이유와 함께 기록합니다.

5단계: GitHub Pages 패키징 (docs/)

1. 모든 정적 웹사이트 자산이 SkillSpectorWeb/docs/ 안에 있는지 확인합니다.
   • docs/index.html
   • docs/css/styles.css
   • docs/js/*.js
   • docs/CNAME (skillspector.niyogilabs.com)
   • docs/sitemap.xml
   • docs/robots.txt
   • docs/.nojekyll
   • docs/LICENSE
2. server.py가 기본적으로 docs/ 디렉토리를 제공하는지 확인합니다.

---

🧪 검증 체크리스트

• python3 server.py 8090가 실행되고 docs/에서 깨끗하게 제공됩니다.
• 멀티 스킬 리포지토리(예: Bhanunamikaze/Agentic-SEO-Skill)를 스캔하면 모든 중첩 스킬이 발견됩니다.
• 라이트 테마가 기본으로 설정되어 있습니다. 다크 테마 토글이 작동하고 localStorage에 지속됩니다.
• SEO 엔드포인트(/sitemap.xml, /robots.txt, /CNAME)가 200 OK를 반환합니다.
• SARIF 2.1.0, JSON 및 Markdown 내보내기 기능이 깔끔하게 실행됩니다.
• 편집되지 않은 루트 LICENSE 파일이 그대로 유지됩니다.