octocode-cli 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octocode-cli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Interactive CLI installer for octocode-mcp - Configure MCP servers for Cursor, Claude Desktop, and more",
   "type": "module",
   "main": "out/octocode-cli.js",
@@ -10,6 +10,7 @@
   },
   "files": [
     "out/octocode-cli.js",
+    "skills",
     "assets/example.png",
     "README.md",
     "LICENSE"
@@ -18,13 +19,17 @@
     "build": "yarn lint && vite build",
     "build:dev": "vite build",
     "clean": "rm -rf out/",
-    "lint": "eslint src/**/*.ts",
-    "lint:fix": "eslint src/**/*.ts --fix",
+    "lint": "eslint src/**/*.ts tests/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts tests/**/*.ts --fix",
     "start": "node ./out/octocode-cli.js",
     "test": "vitest run --coverage",
     "test:quiet": "vitest run --reporter=dot --silent",
     "test:watch": "vitest --watch",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "validate:mcp": "npx tsx scripts/validate-mcp-registry.ts",
+    "validate:mcp:json": "npx tsx scripts/validate-mcp-registry.ts --json",
+    "validate:skills": "npx tsx scripts/validate-skills-marketplace.ts",
+    "validate:skills:json": "npx tsx scripts/validate-skills-marketplace.ts --json"
   },
   "keywords": [
     "octocode",
@@ -51,7 +56,12 @@
   "bugs": "https://github.com/bgauryy/octocode-mcp/issues",
   "license": "PolyForm-Small-Business-1.0.0",
   "dependencies": {
-    "@inquirer/prompts": "^7.2.1"
+    "@inquirer/prompts": "^7.2.1",
+    "@octokit/auth-oauth-device": "^8.0.3",
+    "@octokit/oauth-methods": "^6.0.2",
+    "@octokit/request": "^10.0.7",
+    "keytar": "^7.9.0",
+    "open": "^11.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.29",

package/skills/README.md

@@ -0,0 +1,121 @@
+# Octocode Skills
+
+Pre-built Claude Code skills for enhanced AI-assisted research and development.
+
+## Available Skills
+
+| Skill | Description | Flow |
+|-------|-------------|------|
+| `octocode-research` | Evidence-first code forensics (local & GitHub) | PREPARE → DISCOVER → ANALYZE → OUTPUT |
+| `octocode-pr-review` | Defects-first PR review across 6 domains | CONTEXT → CHECKPOINT → ANALYSIS → REPORT |
+| `octocode-plan` | Research-driven planning & implementation | UNDERSTAND → RESEARCH → PLAN → IMPLEMENT → VERIFY |
+| `octocode-generate` | App scaffolding with stack selection | DISCOVERY → STACK → PLAN → SCAFFOLD → VALIDATE |
+
+## Installation
+
+### Option 1: CLI Command
+
+```bash
+octocode skills install
+```
+
+This copies all skills to `~/.claude/skills/` for global availability.
+
+### Option 2: Manual Copy
+
+Copy skill folders to your Claude skills directory:
+
+```bash
+# Global (all projects)
+cp -r skills/octocode-* ~/.claude/skills/
+
+# Project-specific
+cp -r skills/octocode-* .claude/skills/
+```
+
+## Skill Details
+
+### octocode-research
+**Use when**: Answering questions about codebases, implementations, dependencies, or bugs.
+
+Features:
+- Local-first strategy (prefer local tools over shell commands)
+- GitHub code forensics
+- Cross-domain transitions (Local ↔ GitHub)
+- node_modules inspection
+
+### octocode-pr-review
+**Use when**: Reviewing pull requests for issues.
+
+Domain Reviewers:
+- Bug (runtime errors, logic flaws)
+- Architecture (pattern violations, coupling)
+- Performance (O(n²), memory leaks)
+- Code Quality (naming, conventions)
+- Error Handling (swallowed exceptions)
+- Flow Impact (breaking changes)
+
+### octocode-plan
+**Use when**: Planning complex implementations requiring research.
+
+Goal Types:
+- RESEARCH_ONLY - No code changes
+- ANALYSIS - Understand existing code
+- CREATION - New files/features
+- FEATURE / BUG / REFACTOR - Modify existing
+
+### octocode-generate
+**Use when**: Scaffolding new applications.
+
+Supported Frameworks:
+- Fullstack: Next.js, T3 Stack, Remix, Nuxt
+- Frontend: Vite, Angular
+- Mobile: Expo
+- Desktop: Electron Vite
+- Backend: NestJS, Hono, Fastify
+
+## Skill Structure
+
+Each skill follows Anthropic's best practices:
+
+```
+{skill-name}/
+├── SKILL.md           # Main reference (<500 lines)
+└── resources/         # Supporting documentation (optional)
+    ├── tool-reference.md
+    └── workflow-patterns.md
+```
+
+## Shared Principles
+
+All skills follow these core principles:
+
+1. **Local-First**: Prefer local tools over shell commands
+2. **Research Before Action**: Always gather evidence first
+3. **User Checkpoints**: Ask before major actions
+4. **TodoWrite**: Track progress with tasks
+5. **Validation**: Green build required
+6. **No Time Estimates**: Never provide timing
+
+## Creating Custom Skills
+
+See `octocode-research/` as a template. Key guidelines:
+
+1. **SKILL.md** - Main file with YAML frontmatter:
+   ```yaml
+   ---
+   name: skill-name
+   description: Use when [specific triggers]...
+   ---
+   ```
+
+2. **Keep SKILL.md under 500 lines** - Use resources/ for details
+
+3. **Description = When to Use** - Don't describe workflow, describe triggers
+
+4. **Test with pressure scenarios** before deploying
+
+## More Info
+
+- [Claude Skills Documentation](https://support.claude.com/en/articles/12512176-what-are-skills)
+- [Octocode MCP](https://octocode.ai)

package/skills/octocode-generate/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: octocode-generate
+description: Scaffolds new applications with optimal tech stack selection and project boilerplate. Use when creating new projects, setting up frameworks, generating boilerplate, or starting new applications.
+---
+
+# Octocode Generate
+
+Research-driven app scaffolding using Octocode MCP tools.
+
+## Core Principle
+
+```
+MEASURE TWICE, CUT ONCE
+```
+
+1. **Research First**: Validate patterns before scaffolding
+2. **Stack Selection**: Choose optimal framework based on requirements
+3. **Green Build Required**: Scaffold must compile and run
+
+## Flow
+
+```
+DISCOVERY → STACK → PLAN → RESEARCH → SCAFFOLD → VALIDATE
+```
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `githubSearchRepositories` | Find template repos |
+| `githubViewRepoStructure` | Explore structure |
+| `githubSearchCode` | Find config patterns |
+| `githubGetFileContent` | Read implementations |
+| `packageSearch` | Check package info |
+
+## Recommended Frameworks
+
+### Fullstack
+| Name | CLI Command | Best For |
+|------|-------------|----------|
+| Next.js | `npx create-next-app@latest` | React + SSR/SSG |
+| T3 Stack | `npx create-t3-app@latest` | Type-safe fullstack |
+| Remix | `npx create-remix@latest` | Web standards |
+| Nuxt | `npx nuxi@latest init` | Vue + SSR |
+
+### Frontend
+| Name | CLI Command | Best For |
+|------|-------------|----------|
+| Vite | `npm create vite@latest` | Fast SPA |
+| Angular | `npx @angular/cli new` | Enterprise SPA |
+
+### Mobile
+| Name | CLI Command | Best For |
+|------|-------------|----------|
+| Expo | `npx create-expo-app@latest` | React Native |
+
+### Desktop
+| Name | CLI Command | Best For |
+|------|-------------|----------|
+| Electron Vite | `npm create electron-vite` | Cross-platform |
+
+### Backend
+| Name | CLI Command | Best For |
+|------|-------------|----------|
+| NestJS | `npx @nestjs/cli new` | Enterprise API |
+| Hono | `npm create hono@latest` | Edge/lightweight |
+| Fastify | `npx fastify-cli generate` | High-perf Node |
+
+## Execution Phases
+
+### Phase 0: Discovery
+1. Classify app type: Fullstack | SPA | API | Mobile | Desktop
+2. Ask for references (existing apps, designs, specs)
+3. Confirm package manager: npm (default) | yarn | pnpm
+
+**User Checkpoint**: If requirements unclear → STOP & ASK
+
+### Phase 1: Stack Selection
+**Selection Criteria**:
+- Match app type to framework strengths
+- Check framework freshness (avoid stale)
+- Verify TypeScript support if required
+- Consider deployment target (Vercel, AWS, etc.)
+
+### Phase 2: Planning
+Write plan with:
+- Requirements summary
+- Research tasks
+- Scaffold steps
+- Validation checklist
+
+**User Checkpoint**: Present plan → Wait for approval
+
+### Phase 3: Research
+**Research Dimensions**:
+
+| Dimension | Goal | Example Query |
+|-----------|------|---------------|
+| Official Examples | Canonical patterns | `owner:vercel repo:next.js path:examples` |
+| Popular Templates | Community patterns | `topics:starter topics:template stars:>1000` |
+| Integration Code | How libs connect | `filename:trpc extension:ts "createTRPCNext"` |
+| Config Files | Tooling setup | `filename:next.config extension:mjs` |
+
+**Quality Guards**:
+- Prefer repos updated within last 6 months
+- Prefer repos with `stars` > 500
+- Verify active maintenance (recent commits/PRs)
+
+### Phase 4: Scaffold
+**Execution Order**:
+1. **Initialize**: Run framework CLI
+2. **Install**: Add dependencies (from research)
+3. **Configure**: Create/update config files
+4. **Implement**: Add features using researched patterns
+
+**Guidelines**:
+- Follow researched patterns exactly
+- Use explicit file paths
+- Add TypeScript types
+- Create `.env.example` (never commit secrets)
+- Add essential comments for non-obvious code
+
+### Phase 5: Validate
+**Validation Gates (ALL MANDATORY)**:
+- [ ] `npm run build` / `yarn build` - passes
+- [ ] `npx tsc --noEmit` - no errors
+- [ ] Dev server starts without errors
+- [ ] All imports resolve
+- [ ] No TypeScript `any` escapes
+
+**Loop**: Fail → Fix → Re-validate until all gates pass
+
+## Research Flows
+
+| From | Need | Go To |
+|------|------|-------|
+| `githubSearchRepositories` | Structure | `githubViewRepoStructure` |
+| `githubSearchRepositories` | Patterns | `githubSearchCode` |
+| `githubViewRepoStructure` | File content | `githubGetFileContent` |
+| `githubSearchCode` | Full context | `githubGetFileContent` |
+| `packageSearch` | Source code | `githubViewRepoStructure` |
+
+## Confidence Framework
+
+| Decision Type | Confidence Required | Action |
+|---------------|---------------------|--------|
+| Framework choice | HIGH (2+ sources) | Proceed |
+| Config patterns | MED (1 quality source) | Proceed with note |
+| Uncertain practice | LOW | Ask user |
+
+## When to Skip Research
+
+- Standard CLI defaults (Next.js app router, Vite React)
+- User explicitly specified tech stack
+- Common boilerplate (`.env.example`, `tsconfig.json` base)
+- Trivial choices with no architectural impact
+
+## Error Recovery
+
+| Error | Action |
+|-------|--------|
+| Build fails | Fix imports/types, re-validate |
+| Missing types | `npm i -D @types/{package}` |
+| Version conflict | Research compatible versions |
+| Config error | Research correct config pattern |
+| CLI fails | Check framework docs via research |

package/skills/octocode-plan/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: octocode-plan
+description: Plans complex implementations with research-driven analysis and step-by-step breakdowns. Use when planning features, making architectural decisions, designing systems, or implementing multi-step changes.
+---
+
+# Octocode Plan
+
+Research-driven planning and implementation using Octocode MCP tools.
+
+## Core Principle
+
+```
+RESEARCH BEFORE CODE. VERIFY PATTERNS. FOLLOW THE PLAN.
+```
+
+1. **Research First**: Validate patterns in high-quality repos before writing code
+2. **Plan Before Implement**: Break down tasks, identify risks
+3. **Green Build Required**: All changes must pass build/lint/test
+
+## Flow
+
+```
+UNDERSTAND → RESEARCH → PLAN → [IMPLEMENT] → VERIFY
+```
+
+## Tools
+
+**Research**:
+| Tool | Purpose |
+|------|---------|
+| `packageSearch` | Find libs/metadata |
+| `githubSearchRepositories` | Find reference repos |
+| `githubViewRepoStructure` | Map layout |
+| `githubSearchCode` | Find implementations |
+| `githubGetFileContent` | Read code |
+| `localSearchCode` | Search local codebase |
+| `localGetFileContent` | Read local files |
+
+**Execution**: `Read`, `Write`, `Edit`, `Bash`
+
+## Goal Classification
+
+| Type | Description | Action |
+|------|-------------|--------|
+| `RESEARCH_ONLY` | No code changes | Research → Report |
+| `ANALYSIS` | Understand existing code | Research → Document |
+| `CREATION` | New files/features | Research → Plan → Implement |
+| `FEATURE` | Add to existing | Research → Plan → Implement |
+| `BUG` | Fix issue | Research → Plan → Implement |
+| `REFACTOR` | Improve structure | Research → Plan → Implement |
+
+## Execution Phases
+
+### Phase 0: Understand
+1. Classify goal type (above)
+2. Assess complexity: Quick | Medium | Thorough
+3. Gather context: existing code, patterns, dependencies
+4. Define constraints: tech stack, style, testing requirements
+
+**User Checkpoint**: If scope unclear or >2 repos involved → STOP & ASK
+
+### Phase 1: Research
+**Progressive Discovery**: PKG → REPO → STRUCT → PATTERN → READ
+
+| Stage | Tool | Goal |
+|-------|------|------|
+| PKG | `packageSearch` | Find libs/metadata |
+| REPO | `githubSearchRepositories` | Find reference repos |
+| STRUCT | `githubViewRepoStructure` | Map layout |
+| PATTERN | `githubSearchCode` | Find implementations |
+| READ | `githubGetFileContent` | Read code |
+
+**Research Loop (ReAct)**:
+1. **THOUGHT**: What do I need to know next?
+2. **ACTION**: Execute Octocode tool
+3. **OBSERVATION**: Analyze results - hypothesis confirmed?
+4. **DECISION**: Use finding | Research more | Ask user
+
+**Quality Guards**:
+- Key findings need second source unless primary is definitive
+- Prefer repos updated within last year
+- Real code only (no dead code, deprecated, tests unless researching tests)
+
+### Phase 2: Plan
+Write plan with:
+- Summary of approach
+- Step-by-step tasks with file paths
+- Dependencies/prerequisites
+- Risk areas and mitigations
+- Validation checklist
+
+**Plan Template**:
+```markdown
+# Plan: {Title}
+
+## Summary
+[TL;DR of approach]
+
+## Research Findings
+[Key patterns with confidence levels]
+
+## Implementation Steps
+1. [ ] Step 1: [Description] - `path/to/file`
+2. [ ] Step 2: [Description] - `path/to/file`
+
+## Risk Areas
+- [Potential issues and mitigations]
+
+## Validation
+- [ ] Build passes
+- [ ] Tests pass
+- [ ] [Custom checks]
+```
+
+**CRITICAL**: Wait for explicit user approval before implementing
+
+### Phase 3: Implement
+Prerequisite: Approved plan from Phase 2
+
+**Execution Loop**:
+1. **THOUGHT**: Next plan step? Dependencies resolved?
+2. **ACTION**: Read file → Write/Edit → Verify
+3. **OBSERVATION**: Success? Errors? Side effects?
+4. **LOOP**: Success → Next step; Fail → Fix
+
+**Guidelines**:
+- Follow plan sequentially
+- Use explicit file paths
+- Add TypeScript types
+- Handle errors appropriately
+- Minimal changes only
+
+### Phase 4: Verify
+**For Code Changes**:
+- [ ] `npm run build` passes
+- [ ] `npm run lint` clean
+- [ ] `npm test` passes
+- [ ] No TypeScript errors
+
+**Loop**: Fail → Fix → Re-verify until all green
+
+## Confidence Framework
+
+| Finding | Confidence | Action |
+|---------|------------|--------|
+| Single authoritative source | HIGH | Use directly |
+| Multiple consistent sources | HIGH | Use with references |
+| Single non-authoritative source | MED | Seek second source |
+| Conflicting sources | LOW | Ask user |
+| No sources found | LOW | Try semantic variants OR ask user |
+
+## When to Skip Planning
+
+- Single-file, obvious fix
+- User provides exact implementation
+- Trivial changes (typo, comment, formatting)
+
+## Error Recovery
+
+| Situation | Action |
+|-----------|--------|
+| Research returns empty | Try semantic variants, broaden scope |
+| Too many results | Add filters (path, extension, owner/repo) |
+| Conflicting patterns | Find authoritative source OR ask user |
+| Build fails | Check error, fix, re-verify |
+| Blocked >2 attempts | Summarize → Ask user for guidance |

package/skills/octocode-pr-review/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: octocode-pr-review
+description: Reviews pull requests for bugs, security vulnerabilities, architecture problems, performance issues, and code quality. Use when reviewing PRs, analyzing diffs, checking code changes, or performing code review.
+---
+
+# Octocode PR Review
+
+Defects-first PR review using Octocode MCP tools.
+
+## Core Principle
+
+```
+FOCUS ON CHANGED CODE ONLY ('+' prefix lines)
+```
+
+1. **Defects First**: Prioritize bugs, security, and breaking changes
+2. **Unique Suggestions**: Check existing PR comments to avoid duplicates
+3. **Cite Precisely**: Reference exact file paths and line numbers
+
+## Flow
+
+```
+CONTEXT → USER CHECKPOINT → ANALYSIS → FINALIZE → REPORT
+```
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `githubSearchPullRequests` | Fetch PR metadata, diffs, comments |
+| `githubGetFileContent` | Read full file context |
+| `githubSearchCode` | Find patterns in repo |
+| `localSearchCode` | Search local codebase |
+| `localGetFileContent` | Read local files |
+| `packageSearch` | Check dependency info |
+
+## Domain Reviewers
+
+### Bug Domain
+**Detect**: Runtime errors, logic flaws, null access, race conditions, type violations
+**Priority**:
+- HIGH: Crashes, data corruption, security breach
+- MED: Edge-case errors, uncertain race conditions
+- LOW: Theoretical issues without evidence
+
+### Architecture Domain
+**Detect**: Pattern violations, tight coupling, circular dependencies, wrong module placement
+**Priority**:
+- HIGH: Breaking public API, circular dependencies causing bugs
+- MED: Significant pattern deviations, tech debt increase
+- LOW: Minor inconsistencies
+
+### Performance Domain
+**Detect**: O(n²) where O(n) possible, blocking operations, memory leaks, missing cache
+**Priority**:
+- HIGH: O(n²) on large datasets, memory leaks, blocking main thread
+- MED: Moderate inefficiency in frequent paths
+- LOW: Micro-optimizations
+
+### Code Quality Domain
+**Detect**: Naming violations, convention breaks, visible typos, magic numbers
+**Priority**:
+- HIGH: Typos in public API/endpoints
+- MED: Internal naming issues, DRY violations
+- LOW: Comment typos, minor readability
+
+### Error Handling Domain
+**Detect**: Swallowed exceptions, unclear error messages, missing debugging context
+**Priority**:
+- HIGH: Swallowed exceptions hiding critical failures
+- MED: Unclear error messages, missing context in logs
+- LOW: Verbose logging improvements
+
+### Flow Impact Domain
+**Detect**: How changed code alters existing execution flows
+**Priority**:
+- HIGH: Changes that break existing callers, alter critical paths
+- MED: Flow changes requiring updates in dependent code
+- LOW: Internal refactors with same external behavior
+
+## Execution
+
+### Phase 1: Context
+1. Fetch PR metadata and diff: `githubSearchPullRequests(prNumber, type="metadata")`
+2. Review existing PR comments first (avoid duplicates!)
+3. Classify risk: High (Logic/Auth/API/Data) vs Low (Docs/CSS)
+4. Flag large PRs (>500 lines) → suggest splitting
+
+### Phase 2: User Checkpoint (MANDATORY)
+Present to user:
+- **PR Overview**: What this PR does (1-2 sentences)
+- **Files Changed**: Count and key areas
+- **Risk Assessment**: HIGH / MEDIUM / LOW
+- **Key Areas**: List 3-5 main functional areas
+
+Ask: "Which areas would you like me to focus on?"
+
+### Phase 3: Analysis
+For each changed file:
+1. Read full context with `githubGetFileContent`
+2. Apply domain reviewers (Bug, Security, Architecture, Performance, Quality)
+3. Search for patterns in repo with `githubSearchCode`
+4. Check local impact with `localSearchCode`
+
+### Phase 4: Report
+Generate structured review with:
+- Summary of changes
+- Findings by priority (HIGH → MED → LOW)
+- Each finding: Domain, File, Line, Issue, Suggested Fix
+
+## What to Skip
+
+- Compiler/TypeScript/Linter errors (tooling catches these)
+- Unchanged code (no '+' prefix)
+- Test implementation details (unless broken)
+- Generated/vendor files
+- Style preferences (use linters)
+- Issues already raised in existing PR comments
+
+## Research Flows
+
+| From | Need | Go To |
+|------|------|-------|
+| PR Diff | Full file context | `githubGetFileContent` |
+| Changed function | Existing callers | `githubSearchCode` |
+| Import statement | External definition | `packageSearch` → `githubViewRepoStructure` |
+| Changed API | Local impact | `localSearchCode` |
+
+## Confidence Levels
+
+| Level | Certainty | Action |
+|-------|-----------|--------|
+| HIGH | Verified issue exists | Include |
+| MED | Likely issue, missing context | Include with caveat |
+| LOW | Uncertain | Investigate more OR skip |
+
+Note: Confidence ≠ Severity. HIGH confidence typo = Low Priority. LOW confidence security flaw = flag but mark uncertain.