@rune-kit/rune 2.8.0 → 2.11.0

package/skills/graft/SKILL.md

@@ -0,0 +1,352 @@
+---
+name: graft
+description: "Clone, port, or convert features from any GitHub repo into your project. Understand before copy, challenge before implement. 4 modes: port (rewrite), compare (analysis), copy (transplant), improve (copy + optimize)."
+metadata:
+  author: runedev
+  version: "0.1.0"
+  layer: L2
+  model: sonnet
+  group: creation
+  tools: "Read, Write, Edit, Bash, Glob, Grep, WebFetch"
+  emit: graft.complete
+  listen: codebase.scanned
+---
+
+# graft
+
+## Purpose
+
+External code intelligence — structured workflow for learning from, adapting, and integrating features from any public repository into your project. Graft is NOT a copy-paste tool. It enforces understanding before adoption through a mandatory challenge gate that evaluates license compatibility, stack fit, scope, quality, and maintenance health before any code touches your codebase.
+
+<HARD-GATE>
+Challenge gate (Step 4) MUST complete before adaptation planning (Step 5).
+No implementation without confronting trade-offs. This applies to ALL modes except compare.
+Skip only with --fast flag (user accepts full responsibility).
+</HARD-GATE>
+
+## Modes
+
+### Port (default)
+Rewrite the target feature using YOUR stack and patterns. Source code is a reference, not a template. Output is idiomatic to your codebase.
+
+**When**: Different tech stack (Vue→React, Django→FastAPI), or source patterns conflict with your conventions.
+
+### Compare
+Side-by-side analysis only. No code changes. Outputs a structured comparison report.
+
+**When**: Evaluating whether to adopt a feature, benchmarking your implementation against another, or learning patterns without importing code.
+
+### Copy
+Pure transplant with minimal adaptation. Stays as close to the original as possible — only changes imports, paths, and config to fit your project structure.
+
+**When**: Same tech stack, source code is high quality, you want the exact implementation.
+
+### Improve
+Copy the feature, then refactor and optimize. Fix anti-patterns, add missing tests, adapt to your codebase conventions, upgrade deprecated APIs.
+
+**When**: Same stack but source has quality issues, or you want the feature but better.
+
+## Speed Options
+
+| Flag | Research | Challenge Gate | User Approval |
+|------|----------|---------------|---------------|
+| (default) | ✅ Full | ✅ Yes | ✅ Each step |
+| `--auto` | ✅ Full | ✅ Yes | ❌ Auto-approve |
+| `--fast` | ❌ Skip | ❌ Skip | ❌ Auto-approve |
+
+**`--fast` warning**: Skipping challenge gate means no license check, no quality assessment. User accepts full responsibility. Announce: "Fast mode: skipping challenge gate. You are responsible for license and quality review."
+
+## Smart Intent Detection
+
+| Input Pattern | Detected Mode |
+|---------------|---------------|
+| Contains "compare", "vs", "diff", "analyze" | compare |
+| Contains "copy", "exact", "as-is", "same" | copy |
+| Contains "improve", "better", "adapt", "upgrade" | improve |
+| Contains "port", "convert", "rewrite", "migrate" | port |
+| URL points to specific file/dir (not repo root) | Auto-scope to that path |
+| (default — no keyword match) | port |
+
+## Triggers
+
+- `/rune graft <url> [--port|--compare|--copy|--improve] [--auto|--fast]`
+- Delegated from `cook` when task contains "graft", "port from", "copy from repo", "clone feature from"
+- Auto-trigger: when user pastes a GitHub URL with context like "use this", "like this repo", "steal this"
+
+## Calls (outbound)
+
+- `research` (L3): fetch repo README, docs, understand purpose and architecture
+- `scout` (L2): scan LOCAL codebase for conventions, patterns, stack detection
+- `fix` (L2): implement adapted code (port and improve modes)
+- `review` (L2): post-graft quality check (improve mode only)
+
+## Called By (inbound)
+
+- User: `/rune graft <url>` direct invocation
+- `cook` (L1): delegation when task is "port feature from external repo"
+
+## Data Flow
+
+### Feeds Into →
+
+- `fix` (L2): adaptation plan → fix's implementation targets (port/improve modes)
+- `review` (L2): grafted code → review's analysis targets (improve mode)
+- `test` (L2): new grafted code → test coverage targets
+- `journal` (L3): graft.complete signal → auto-logged for pattern tracking
+
+### Fed By ←
+
+- `scout` (L2): local codebase conventions → graft's adaptation strategy
+- `research` (L3): repo analysis → graft's understanding of source architecture
+
+## Executable Steps
+
+### Step 0 — Parse Input
+<MUST-READ path="references/mode-decision.md" trigger="when auto-detecting mode"/>
+
+Extract from user input:
+1. **URL** — GitHub/GitLab/Bitbucket repo or file URL
+2. **Mode** — explicit flag or auto-detect via intent detection table
+3. **Speed** — `--auto` or `--fast` if present
+4. **Scope** — specific dir/file path if URL points to subdirectory, or user specifies "just the auth module"
+
+Validate URL is accessible. If private repo or URL fails → suggest raw file URLs or manual paste.
+
+### Step 1 — Fetch & Scope
+
+```bash
+# Sparse clone for large repos (skip if small or specific files)
+git clone --depth 1 --filter=blob:none --sparse <url> /tmp/graft-<hash>
+cd /tmp/graft-<hash>
+git sparse-checkout set <target-dir>
+```
+
+For specific files or small repos: use `WebFetch` on raw GitHub URLs instead of cloning.
+
+**Read in this order** (stop when you have enough context):
+1. README.md — purpose, architecture overview
+2. Target dir's files — the actual code to graft
+3. package.json / pyproject.toml / Cargo.toml — dependencies and stack
+4. Tests for target feature — understand expected behavior
+
+**Scope guard**: If target feature spans >15 files or >2000 LOC → WARN user: "Feature is large. Suggest narrowing to [specific module]. Continue anyway?"
+
+### Step 2 — Analyze Source
+
+Understand the target feature's architecture:
+- **What it does** — 2-3 sentence summary
+- **How it works** — key patterns, data flow, core logic
+- **Dependencies** — external packages required, internal imports
+- **Stack** — framework, language version, tooling
+- **Quality signals** — has tests? typed? documented? last commit date?
+
+Output a brief analysis (not full report — save context for later steps).
+
+### Step 3 — Scan Local Codebase
+
+Invoke `rune:scout` (or use cached output if `codebase.scanned` signal received):
+- Local tech stack and version
+- Naming conventions (camelCase vs snake_case, file structure)
+- Existing patterns that overlap with target feature
+- Import style, test framework, state management approach
+
+**Stack comparison**: Produce a quick compatibility matrix:
+```
+| Aspect | Source | Local | Compatible? |
+|--------|--------|-------|-------------|
+| Framework | Next.js 14 | Next.js 15 | ✅ Minor adaptation |
+| Language | TypeScript | TypeScript | ✅ |
+| State | Redux | Zustand | ⚠️ Port needed |
+| Testing | Jest | Vitest | ⚠️ Port needed |
+```
+
+If stack is identical → suggest copy or improve mode (not port).
+If stack differs significantly → force port mode.
+
+### Step 4 — Challenge Gate
+<MUST-READ path="references/challenge-framework.md" trigger="always (unless --fast)"/>
+
+<HARD-GATE>
+Score all 5 dimensions. If 2+ dimensions score ❌ → BLOCK graft.
+If 1 dimension scores ❌ → WARN + require explicit user override.
+Only --fast skips this gate entirely.
+</HARD-GATE>
+
+Present challenge results to user:
+```
+## Challenge Gate Results
+
+| Dimension | Score | Detail |
+|-----------|-------|--------|
+| License | ✅ | MIT — compatible |
+| Stack Fit | ⚠️ | Redux → Zustand migration needed |
+| Scope | ✅ | 6 files, ~400 LOC — manageable |
+| Quality | ✅ | Typed, tested, documented |
+| Maintenance | ⚠️ | Last commit 4 months ago |
+
+**Verdict: PROCEED with caveats** (0 ❌, 2 ⚠️)
+```
+
+Wait for user approval (unless `--auto`).
+
+### Step 5 — Plan Adaptation
+
+Based on mode, produce adaptation plan:
+
+**Compare mode** → skip to output. Write comparison report and STOP.
+
+**Copy mode** → list files to transplant, import path changes, config adjustments. Minimal changes only.
+
+**Port mode** → for each source component, describe the rewrite:
+- Source pattern → local pattern mapping
+- Dependencies to replace (Redux→Zustand, Jest→Vitest)
+- Files to create/modify in local project
+- What to keep vs what to rewrite from scratch
+
+**Improve mode** → copy plan + improvement list:
+- Anti-patterns to fix (mutations, any types, missing error handling)
+- Missing tests to add
+- Deprecated APIs to upgrade
+- Convention mismatches to align
+
+Present plan to user. Wait for approval (unless `--auto`).
+
+### Step 6 — Execute
+
+**Compare mode**: Output report → emit `graft.complete` → done.
+
+**Copy/Port/Improve modes**:
+1. Create/modify files per adaptation plan
+2. For port/improve: invoke `rune:fix` for complex rewrites
+3. For improve: invoke `rune:review` on grafted code
+4. Run project verification (lint, type-check, test if applicable)
+5. Clean up temp clone dir
+
+**Post-execution**: Emit `graft.complete` signal with payload:
+```yaml
+graft.complete:
+  mode: "port|copy|improve|compare"
+  source_url: "<url>"
+  files_changed: ["src/auth/middleware.ts", "src/auth/types.ts"]
+  challenge_score: { license: "pass", stack: "warn", scope: "pass", quality: "pass", maintenance: "warn" }
+```
+
+## Output Format
+
+### Compare Mode Output
+```markdown
+## Graft Comparison: [feature] — [source repo] vs [local]
+
+### Summary
+[2-3 sentences: what was compared, key differences]
+
+### Comparison
+| Aspect | Source | Local | Winner | Notes |
+|--------|--------|-------|--------|-------|
+| [aspect] | [approach] | [approach] | [which] | [why] |
+
+### Recommendations
+- [what to adopt from source]
+- [what to keep from local]
+- [what to graft: specific files/patterns]
+```
+
+### Port/Copy/Improve Output
+```markdown
+## Graft Complete: [feature] from [source]
+
+### Mode: [port|copy|improve]
+### Files Changed
+- `path/file.ts` — [new|modified] — [what changed]
+
+### Adaptations Made
+- [adaptation 1]
+- [adaptation 2]
+
+### Verify
+- [ ] `npm run lint` passes
+- [ ] `npm run test` passes
+- [ ] Feature works as expected
+```
+
+## Returns
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `mode` | enum | port, compare, copy, improve |
+| `source_url` | string | Source repository URL |
+| `files_changed` | string[] | List of created/modified local files |
+| `challenge_score` | object | 5-dimension scores (pass/warn/fail) |
+| `status` | enum | DONE, DONE_WITH_CONCERNS, BLOCKED |
+| `comparison_report` | string? | Markdown report (compare mode only) |
+
+## Constraints
+
+1. MUST run challenge gate before any code changes — no blind copying
+2. MUST clean up temp clone directories after completion
+3. MUST detect and warn about license incompatibility before proceeding
+4. MUST use sparse checkout for repos >100MB — never full clone large repos
+5. MUST respect local conventions — grafted code should look native, not foreign
+6. MUST NOT modify the source repository — read-only access only
+7. MUST NOT graft without scoping — always narrow to specific feature/module
+
+## Mesh Gates
+
+| Gate | Requires | If Missing |
+|------|----------|------------|
+| Challenge Gate | 5-dimension score with 0-1 ❌ | BLOCK if 2+ ❌, WARN if 1 ❌ |
+| Scout Gate | Local codebase scanned | Invoke `rune:scout` first |
+| Scope Gate | Target feature ≤15 files | WARN user, suggest narrowing |
+
+## Sharp Edges
+
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| Grafting GPL code into MIT project | CRITICAL | Challenge gate checks license — blocks incompatible |
+| Blindly copying code without understanding | CRITICAL | HARD-GATE: challenge before implement |
+| Context overflow from large source files | HIGH | Scope guard: >15 files or >2000 LOC triggers warning |
+| Grafted code doesn't match local conventions | HIGH | Step 3 scans local patterns, Step 5 plans adaptation |
+| Stale source (abandoned repo) | MEDIUM | Maintenance dimension in challenge gate |
+| Private repo URL fails | MEDIUM | Fallback to WebFetch raw URLs or manual paste |
+| Port mode when copy would suffice (wasted effort) | MEDIUM | Mode decision tree suggests optimal mode |
+
+## Self-Validation
+
+```
+SELF-VALIDATION (run before emitting graft.complete):
+- [ ] Challenge gate was executed (or --fast acknowledged)
+- [ ] All grafted files follow local naming conventions
+- [ ] No source-specific imports remain (wrong paths, missing packages)
+- [ ] License compatibility confirmed (or user override documented)
+- [ ] Temp clone directory cleaned up
+- [ ] Grafted code compiles/lints without new errors
+IF ANY check fails → fix before reporting done. Do NOT defer to completion-gate.
+```
+
+## Cross-cutting Updates
+
+If this skill is added to the repo (first time):
+- [ ] `README.md` — skill count (61→62), L2 count (28→29)
+- [ ] `docs/ARCHITECTURE.md` — add graft to L2 list
+- [ ] `CLAUDE.md` — add graft to L2 list, routing table, skill count
+- [ ] `docs/index.html` — update meta stats if applicable
+
+## Done When
+
+- Input parsed: URL, mode, speed flags extracted
+- Source fetched and scoped (sparse clone or WebFetch)
+- Source analyzed: patterns, dependencies, stack understood
+- Challenge gate passed (5 dimensions scored, 0-1 ❌)
+- Local codebase scanned for conventions
+- Adaptation plan produced and approved
+- Code grafted per mode (port/copy/improve/compare)
+- Verification passed (lint, type-check, tests)
+- Temp files cleaned up
+- `graft.complete` signal emitted
+- Self-Validation: all checks passed
+
+## Cost Profile
+
+~2000-4000 tokens input (SKILL.md + 1-2 references), ~3000-8000 tokens output (analysis + adaptation + code). Sonnet for execution. Heaviest when port mode rewrites significant code — but that's where the value is highest.
+
+**Scope guardrail**: Do not become a general-purpose code review tool. Graft analyzes external code for adoption purposes only — use `rune:review` for reviewing your own code, `rune:research` for general technology research.

package/skills/graft/references/challenge-framework.md

@@ -0,0 +1,98 @@
+# Challenge Framework
+
+5-dimension evaluation gate. Score each dimension before grafting code into your project.
+
+## Scoring
+
+| Score | Meaning | Action |
+|-------|---------|--------|
+| ✅ Pass | No concerns | Proceed |
+| ⚠️ Warn | Minor concerns | Proceed with documented caveats |
+| ❌ Fail | Blocking concern | Requires user override or blocks graft |
+
+**Decision matrix**: 0 ❌ → PROCEED. 1 ❌ → WARN + require explicit user override. 2+ ❌ → BLOCK.
+
+## Dimensions
+
+### 1. License Compatibility
+
+| Source License | Your Project MIT | Your Project Apache-2.0 | Your Project GPL |
+|---------------|-----------------|------------------------|-----------------|
+| MIT | ✅ | ✅ | ✅ |
+| Apache-2.0 | ✅ | ✅ | ✅ |
+| BSD-2/3 | ✅ | ✅ | ✅ |
+| ISC | ✅ | ✅ | ✅ |
+| GPL-2.0/3.0 | ❌ | ❌ | ✅ |
+| AGPL | ❌ | ❌ | ⚠️ |
+| SSPL/BSL | ❌ | ❌ | ❌ |
+| No license | ❌ | ❌ | ❌ |
+| Unlicense | ✅ | ✅ | ✅ |
+
+**Check**: Read LICENSE file in repo root. If missing → ❌ (no license = all rights reserved).
+
+### 2. Stack Fit
+
+| Scenario | Score |
+|----------|-------|
+| Identical stack (same framework + language + version) | ✅ |
+| Same language, different framework (React→Svelte) | ⚠️ — port mode recommended |
+| Same framework, major version gap (Next 13→15) | ⚠️ — API changes likely |
+| Different language entirely (Python→TypeScript) | ❌ — port is a rewrite |
+| Incompatible paradigm (OOP→FP, REST→GraphQL) | ❌ — fundamental rethink needed |
+
+### 3. Scope
+
+| Scenario | Score |
+|----------|-------|
+| ≤5 files, ≤500 LOC | ✅ — manageable |
+| 6-15 files, 500-2000 LOC | ⚠️ — consider narrowing |
+| >15 files or >2000 LOC | ❌ — too broad, must narrow scope |
+| Feature has clear boundaries (self-contained module) | ✅ bonus |
+| Feature is deeply entangled with source codebase | ❌ — extraction risk high |
+
+### 4. Quality
+
+| Signal | Score |
+|--------|-------|
+| Has tests with >60% coverage | ✅ |
+| Has tests but minimal | ⚠️ |
+| No tests | ❌ |
+| TypeScript strict / fully typed | ✅ bonus |
+| Uses `any` extensively or untyped | ⚠️ |
+| Well-documented (JSDoc, README for module) | ✅ bonus |
+| No documentation | ⚠️ |
+| Known anti-patterns (mutations, god classes, deep nesting) | ⚠️ — improve mode recommended |
+
+**Composite**: ≥2 ✅ signals → ✅. 1 ✅ + warnings → ⚠️. No tests + untyped → ❌.
+
+### 5. Maintenance
+
+| Signal | Score |
+|--------|-------|
+| Last commit < 3 months ago | ✅ |
+| Last commit 3-12 months ago | ⚠️ |
+| Last commit > 12 months ago | ❌ |
+| Active issues being addressed | ✅ |
+| 50+ open issues, no response | ⚠️ |
+| Archived or deprecated | ❌ |
+| Multiple contributors | ✅ |
+| Solo maintainer, inactive | ⚠️ |
+
+**Note**: For compare mode, maintenance is informational only — not blocking.
+
+## Presentation Format
+
+```markdown
+## Challenge Gate Results
+
+| # | Dimension | Score | Detail |
+|---|-----------|-------|--------|
+| 1 | License | ✅ | MIT — compatible with your MIT project |
+| 2 | Stack Fit | ⚠️ | React 18 → React 19 — minor API changes |
+| 3 | Scope | ✅ | 4 files, ~350 LOC — well-scoped |
+| 4 | Quality | ✅ | Typed, 12 tests, documented |
+| 5 | Maintenance | ⚠️ | Last commit 5 months ago, but stable |
+
+**Verdict**: PROCEED with caveats (0 ❌, 2 ⚠️)
+Caveats: React 18→19 useEffect changes, verify repo still works with latest deps.
+```

package/skills/graft/references/mode-decision.md

@@ -0,0 +1,44 @@
+# Mode Decision Tree
+
+Auto-select the optimal graft mode when user doesn't specify explicitly.
+
+## Decision Flow
+
+```
+1. User wants analysis only? (says "compare", "vs", "analyze")
+   → YES: compare mode
+   → NO: continue
+
+2. Source and local tech stacks match?
+   → NO (different framework/language): port mode (forced)
+   → YES: continue
+
+3. Source code has quality issues? (anti-patterns, no types, no tests)
+   → YES: improve mode (fix issues during graft)
+   → NO: continue
+
+4. User wants exact replica? (says "exact", "as-is", "copy")
+   → YES: copy mode
+   → NO: improve mode (default for same-stack, good-quality)
+```
+
+## Mode Output Contracts
+
+| Mode | Creates Files? | Modifies Files? | Produces Report? | Calls fix? | Calls review? |
+|------|---------------|----------------|-----------------|-----------|--------------|
+| compare | ❌ | ❌ | ✅ comparison report | ❌ | ❌ |
+| copy | ✅ | ⚠️ minimal (imports) | ❌ | ❌ | ❌ |
+| port | ✅ | ✅ | ❌ | ✅ | ❌ |
+| improve | ✅ | ✅ | ❌ | ✅ | ✅ |
+
+## Examples
+
+| Scenario | Auto Mode | Why |
+|----------|-----------|-----|
+| Next.js auth → your Next.js app | improve | Same stack, default to improving |
+| Django REST → FastAPI | port | Different framework, rewrite needed |
+| "How does Stripe handle webhooks in repo X?" | compare | Analysis intent, no code changes |
+| "Copy their date picker component exactly" | copy | User explicitly wants exact replica |
+| Vue component → React project | port | Different framework |
+| Express middleware, has `any` everywhere | improve | Same stack (Node) but quality issues |
+| "Use their testing approach" | compare | Learning intent, not adoption |