opencodekit 0.12.7 → 0.13.1

package/dist/template/.opencode/skill/source-code-research/SKILL.md

@@ -0,0 +1,537 @@
+---
+name: source-code-research
+description: >
+  Use when researching library implementation details beyond API docs. Fetches package source code
+  using opensrc to understand internals, edge cases, and implementation patterns. Complements
+  documentation-based research with actual code inspection.
+version: "1.0.0"
+license: MIT
+---
+
+# Source Code Research - Deep Library Investigation
+
+Fetch and analyze package source code when documentation is insufficient.
+
+## When to Use This Skill
+
+Use source code research when:
+
+- **Documentation gaps**: API docs don't explain behavior clearly
+- **Edge cases**: Need to understand how library handles corner cases
+- **Implementation details**: Need to see actual code, not just interfaces
+- **Debugging**: Library behaving unexpectedly, need to trace internals
+- **Evaluation**: Deciding if library fits requirements, need to assess quality
+- **Type definitions**: TypeScript types exist but implementation unclear
+
+**Don't use when:**
+
+- Official docs answer your question (check Context7 first)
+- You only need API syntax (codesearch is faster)
+- Library is too large to analyze in session (>50k LOC)
+
+## Prerequisites
+
+OpenSrc must be available:
+
+```bash
+npx opensrc --help
+```
+
+If not installed, it will be fetched via npx automatically.
+
+## Workflow
+
+### Step 1: Identify What to Fetch
+
+Determine the minimal package/repo needed:
+
+```typescript
+// If researching a specific npm package
+const target = "zod"; // Just the package name
+
+// If researching Python library
+const target = "pypi:requests";
+
+// If researching Rust crate
+const target = "crates:serde";
+
+// If researching GitHub repo directly
+const target = "vercel/ai"; // or "github:vercel/ai@v3.0.0"
+```
+
+### Step 2: Fetch Source Code
+
+Run opensrc to clone the repository:
+
+```bash
+npx opensrc <package>
+```
+
+**Examples:**
+
+```bash
+npx opensrc zod                    # Fetch latest zod from npm
+npx opensrc zod@3.22.0             # Fetch specific version
+npx opensrc pypi:requests          # Fetch Python package
+npx opensrc vercel/ai              # Fetch GitHub repo
+npx opensrc vercel/ai@v3.0.0       # Fetch specific tag
+```
+
+**What happens:**
+
+- Clones source to `opensrc/repos/<host>/<owner>/<repo>/`
+- Auto-detects version from lockfiles if no version specified
+- Updates `opensrc/sources.json` with metadata
+- Adds `opensrc/` to `.gitignore` automatically (asks once)
+
+### Step 3: Locate Relevant Code
+
+Use search tools to find the code you need:
+
+```typescript
+// Find all TypeScript source files
+glob({ pattern: "opensrc/**/src/**/*.ts" });
+
+// Search for specific function/class
+grep({
+  pattern: "class ValidationError",
+  path: "opensrc/",
+  include: "*.ts",
+});
+
+// Use AST search for precise patterns
+ast_grep({
+  pattern: "export function parse($$$) { $$$ }",
+  path: "opensrc/",
+});
+```
+
+### Step 4: Read and Analyze
+
+Read the implementation:
+
+```typescript
+// Read the file
+read({ filePath: "opensrc/repos/github.com/colinhacks/zod/src/types.ts" });
+
+// Use LSP for navigation (if available)
+lsp_lsp_goto_definition({
+  filePath: "opensrc/.../file.ts",
+  line: 42,
+  character: 10,
+});
+
+// Find all references
+lsp_lsp_find_references({
+  filePath: "opensrc/.../file.ts",
+  line: 42,
+  character: 10,
+});
+```
+
+### Step 5: Document Findings
+
+Write research findings to bead artifact:
+
+````markdown
+# Research: [Library Name] Implementation
+
+**Package:** [name@version]
+**Source:** opensrc/repos/[path]
+**Focus:** [What you were investigating]
+
+## Key Findings
+
+### [Topic 1]: [Function/Pattern Name]
+
+**Location:** `opensrc/repos/.../file.ts:42`
+
+**Implementation:**
+
+```typescript
+// Paste relevant code snippet
+```
+````
+
+**Insights:**
+
+- [What you learned]
+- [Edge cases discovered]
+- [Performance implications]
+
+**Confidence:** High (direct source code)
+
+---
+
+### [Topic 2]: [Another Discovery]
+
+[Same structure]
+
+## Answers to Original Questions
+
+1. **Q:** [Original question]
+   **A:** [Answer based on source code]
+   **Evidence:** `file.ts:123-145`
+
+2. **Q:** [Another question]
+   **A:** [Answer]
+
+## Recommendations
+
+Based on source analysis:
+
+- [Recommendation 1]
+- [Recommendation 2]
+
+## Caveats
+
+- Version analyzed: [version]
+- Code may have changed in newer versions
+- Private APIs discovered may change without notice
+
+````
+
+## Common Patterns
+
+### Pattern 1: Understanding Error Handling
+
+```typescript
+// 1. Fetch package
+// bash: npx opensrc zod
+
+// 2. Find error classes
+grep({ pattern: "class.*Error", path: "opensrc/", include: "*.ts" });
+
+// 3. Read error implementation
+read({ filePath: "opensrc/repos/.../errors.ts" });
+
+// 4. Find where errors are thrown
+grep({ pattern: "throw new", path: "opensrc/", include: "*.ts" });
+````
+
+### Pattern 2: Tracing Function Behavior
+
+```typescript
+// 1. Fetch source
+// bash: npx opensrc react-hook-form
+
+// 2. Find function definition
+ast_grep({
+  pattern: "export function useForm($$$) { $$$ }",
+  path: "opensrc/",
+});
+
+// 3. Read implementation
+read({ filePath: "opensrc/.../useForm.ts" });
+
+// 4. Find dependencies
+grep({ pattern: "import.*from", path: "opensrc/.../useForm.ts" });
+```
+
+### Pattern 3: Evaluating Library Quality
+
+```typescript
+// 1. Fetch source
+// bash: npx opensrc candidate-library
+
+// 2. Check test coverage
+glob({ pattern: "opensrc/**/*.test.ts" });
+glob({ pattern: "opensrc/**/*.spec.ts" });
+
+// 3. Read tests for usage patterns
+read({ filePath: "opensrc/.../feature.test.ts" });
+
+// 4. Check for TypeScript usage
+glob({ pattern: "opensrc/**/tsconfig.json" });
+
+// 5. Review package.json for dependencies
+read({ filePath: "opensrc/.../package.json" });
+```
+
+## Source Structure Guide
+
+### npm Packages
+
+```
+opensrc/
+└── repos/
+    └── github.com/              # npm packages resolve to GitHub
+        └── owner/
+            └── repo/
+                ├── src/         # Source code (usually)
+                ├── dist/        # Built output (ignore)
+                ├── test/        # Tests (useful for examples)
+                ├── package.json # Dependencies, scripts
+                └── README.md    # Often has examples
+```
+
+### Python Packages (PyPI)
+
+```
+opensrc/
+└── repos/
+    └── github.com/              # Most PyPI packages on GitHub
+        └── owner/
+            └── repo/
+                ├── src/         # or package_name/
+                ├── tests/       # Python tests
+                ├── setup.py     # Package config
+                └── pyproject.toml
+```
+
+### Rust Crates
+
+```
+opensrc/
+└── repos/
+    └── github.com/
+        └── owner/
+            └── repo/
+                ├── src/
+                │   └── lib.rs   # Main library file
+                ├── tests/
+                ├── Cargo.toml   # Dependencies
+                └── examples/    # Usage examples
+```
+
+## Tips for Efficient Analysis
+
+### 1. Start with Tests
+
+Tests often show real-world usage better than docs:
+
+```typescript
+glob({ pattern: "opensrc/**/*.test.{ts,js}" });
+read({ filePath: "opensrc/.../feature.test.ts" });
+```
+
+### 2. Check Examples Directory
+
+Many repos have `examples/` or `samples/`:
+
+```typescript
+glob({ pattern: "opensrc/**/examples/**/*" });
+```
+
+### 3. Read CHANGELOG for Context
+
+Understand recent changes:
+
+```typescript
+read({ filePath: "opensrc/.../CHANGELOG.md" });
+```
+
+### 4. Check TypeScript Definitions
+
+Often more accurate than docs:
+
+```typescript
+glob({ pattern: "opensrc/**/*.d.ts" });
+read({ filePath: "opensrc/.../index.d.ts" });
+```
+
+### 5. Use Blame for History (if needed)
+
+```bash
+cd opensrc/repos/github.com/owner/repo
+git log --oneline -- src/file.ts
+git show <commit>:src/file.ts
+```
+
+## Limitations
+
+### When Source Code Won't Help
+
+- **Build-time transforms**: Source may differ from runtime (Babel, webpack)
+- **Native modules**: C/C++ code requires different analysis
+- **Minified code**: Some packages don't publish source
+- **Monorepos**: May need to navigate complex structure
+
+### Alternatives
+
+If opensrc doesn't work:
+
+1. **GitHub web interface**: Browse online at github.com/owner/repo
+2. **npm unpacked**: `npm pack <package>` then extract
+3. **node_modules**: If already installed, check `node_modules/<package>/`
+4. **Source maps**: If debugging, browser DevTools may show original source
+
+## Integration with Other Research Methods
+
+Source code research complements other tools:
+
+| Method         | Best For                   | Source Code Adds               |
+| -------------- | -------------------------- | ------------------------------ |
+| **Context7**   | API docs, official guides  | Implementation details         |
+| **codesearch** | Usage patterns in the wild | Canonical implementation       |
+| **gh_grep**    | Real-world examples        | How library itself works       |
+| **Web search** | Tutorials, blog posts      | Ground truth from source       |
+| **Codebase**   | Project-specific patterns  | How dependencies actually work |
+
+**Recommended flow:**
+
+1. Context7 - Check official docs
+2. Codebase - Check existing usage
+3. **Source code** - If still unclear, fetch source
+4. codesearch/gh_grep - See how others use it
+5. Web search - Last resort for context
+
+## Cleanup
+
+After research is complete:
+
+```bash
+# Remove specific package
+npx opensrc remove <package>
+
+# Remove all sources
+npx opensrc clean
+
+# Remove just npm packages
+npx opensrc clean --npm
+
+# Keep sources for documentation
+# (opensrc/ is gitignored, won't be committed)
+```
+
+## Example: Complete Workflow
+
+**Scenario:** Need to understand how zod handles async refinements.
+
+```bash
+# 1. Fetch source
+npx opensrc zod
+```
+
+```typescript
+// 2. Find refinement code
+grep({
+  pattern: "refine.*async",
+  path: "opensrc/",
+  include: "*.ts",
+});
+
+// 3. Locate implementation
+ast_grep({
+  pattern: "refine($$$) { $$$ }",
+  path: "opensrc/repos/github.com/colinhacks/zod/",
+});
+
+// 4. Read the implementation
+read({
+  filePath: "opensrc/repos/github.com/colinhacks/zod/src/types.ts",
+  offset: 500,
+  limit: 100,
+});
+
+// 5. Check tests for usage examples
+glob({
+  pattern: "opensrc/**/zod/**/*.test.ts",
+});
+
+read({
+  filePath: "opensrc/repos/.../async.test.ts",
+});
+
+// 6. Document findings
+write({
+  filePath: ".beads/artifacts/bd-xxx/research.md",
+  content: `# Zod Async Refinements
+
+**Finding:** Async refinements use \`parseAsync()\` not \`parse()\`
+
+**Evidence:** \`src/types.ts:842-856\`
+
+Async refinements return Promise<Output> and require:
+- Use \`.parseAsync()\` method
+- Refinement function must return Promise<boolean>
+- Errors handled via Promise rejection
+
+**Code snippet:**
+[paste relevant code]
+
+**Recommendation:** Use \`.refine(async (val) => {...})\` with \`.parseAsync()\`
+`,
+});
+```
+
+## Success Criteria
+
+You've successfully used this skill when:
+
+- [ ] Fetched correct package/version source
+- [ ] Located relevant implementation code
+- [ ] Understood behavior from reading source
+- [ ] Documented findings with file:line references
+- [ ] Answered original research question with high confidence
+- [ ] Provided code evidence for claims
+
+## Anti-Patterns
+
+### ❌ Don't: Fetch Entire Ecosystem
+
+```bash
+# Bad: Fetching everything
+npx opensrc react
+npx opensrc react-dom
+npx opensrc react-router
+npx opensrc react-query
+# ... (too much code)
+```
+
+**Do:** Fetch only what you need to answer specific question.
+
+### ❌ Don't: Read Random Files
+
+```typescript
+// Bad: Reading without purpose
+read({ filePath: "opensrc/.../index.ts" });
+read({ filePath: "opensrc/.../utils.ts" });
+read({ filePath: "opensrc/.../helpers.ts" });
+// ... (unfocused exploration)
+```
+
+**Do:** Use grep/ast-grep to find relevant code first, then read.
+
+### ❌ Don't: Ignore Version Mismatch
+
+```bash
+# Bad: Fetching latest when project uses old version
+npx opensrc zod  # Fetches 3.23.x
+# But project uses zod@3.20.0 (different behavior)
+```
+
+**Do:** Specify version matching your lockfile, or let opensrc auto-detect.
+
+## Quick Reference
+
+```bash
+# Fetch package source
+npx opensrc <package>                    # npm (auto-detect version)
+npx opensrc <package>@<version>          # npm (specific version)
+npx opensrc pypi:<package>               # Python
+npx opensrc crates:<package>             # Rust
+npx opensrc <owner>/<repo>               # GitHub
+npx opensrc <owner>/<repo>@<tag>         # GitHub (specific tag)
+
+# List fetched sources
+npx opensrc list
+npx opensrc list --json
+
+# Remove sources
+npx opensrc remove <package>
+npx opensrc clean
+npx opensrc clean --npm --pypi --crates
+
+# Source location
+opensrc/repos/<host>/<owner>/<repo>/
+
+# Metadata
+opensrc/sources.json
+```
+
+## Further Reading
+
+- OpenSrc Docs: https://github.com/vercel-labs/opensrc
+- When to read source vs docs: https://danluu.com/read-code/
+- Code reading techniques: https://www.codeproject.com/Articles/10/Code-Reading

package/dist/template/.opencode/tool/ast-grep.ts

@@ -6,8 +6,8 @@
  * Requires: npm install -g @ast-grep/cli (or brew install ast-grep)
  */
 
-import { exec } from "child_process";
-import { promisify } from "util";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
 import { tool } from "@opencode-ai/plugin";
 
 const execAsync = promisify(exec);
@@ -224,7 +224,7 @@ Install via:
 						preview += `... and ${count - 10} more matches\n`;
 					}
 
-					preview += `\n**To apply:** Run again with dryRun: false`;
+					preview += "\n**To apply:** Run again with dryRun: false";
 					return preview;
 				} catch {
 					return `Dry run preview:\n${stdout}`;

package/dist/template/.opencode/tool/bd-inbox.ts

@@ -1,6 +1,6 @@
-import path from "path";
+import fs from "node:fs/promises";
+import path from "node:path";
 import { tool } from "@opencode-ai/plugin";
-import fs from "fs/promises";
 
 const RESERVATIONS_DIR = ".reservations";
 const MESSAGES_FILE = "messages.jsonl";
@@ -84,7 +84,7 @@ export default tool({
 				}
 				await fs.writeFile(
 					messagesPath,
-					allMsgs.map((m) => JSON.stringify(m)).join("\n") + "\n",
+					`${allMsgs.map((m) => JSON.stringify(m)).join("\n")}\n`,
 					"utf-8",
 				);
 			}
@@ -99,11 +99,12 @@ export default tool({
 			messages = messages.slice(-limit).reverse();
 
 			return JSON.stringify({ msgs: messages, count: messages.length });
-		} catch (e: any) {
-			if (e.code === "ENOENT") {
+		} catch (e) {
+			const err = e as NodeJS.ErrnoException;
+			if (err.code === "ENOENT") {
 				return JSON.stringify({ msgs: [], count: 0 });
 			}
-			return JSON.stringify({ error: e.message });
+			return JSON.stringify({ error: (e as Error).message });
 		}
 	},
 });

package/dist/template/.opencode/tool/bd-msg.ts

@@ -1,6 +1,6 @@
-import path from "path";
+import fs from "node:fs/promises";
+import path from "node:path";
 import { tool } from "@opencode-ai/plugin";
-import fs from "fs/promises";
 
 const RESERVATIONS_DIR = ".reservations";
 const MESSAGES_FILE = "messages.jsonl";
@@ -56,7 +56,7 @@ export default tool({
 			read: false,
 		};
 
-		await fs.appendFile(messagesPath, JSON.stringify(msg) + "\n", "utf-8");
+		await fs.appendFile(messagesPath, `${JSON.stringify(msg)}\n`, "utf-8");
 		return JSON.stringify({ ok: 1, id: msg.id });
 	},
 });

package/dist/template/.opencode/tool/bd-release.ts

@@ -1,6 +1,6 @@
-import path from "path";
+import fs from "node:fs/promises";
+import path from "node:path";
 import { tool } from "@opencode-ai/plugin";
-import fs from "fs/promises";
 
 const RESERVATIONS_DIR = ".reservations";
 

package/dist/template/.opencode/tool/bd-reserve.ts

@@ -1,6 +1,6 @@
-import path from "path";
+import fs from "node:fs/promises";
+import path from "node:path";
 import { tool } from "@opencode-ai/plugin";
-import fs from "fs/promises";
 
 const RESERVATIONS_DIR = ".reservations";
 
@@ -69,8 +69,9 @@ export default tool({
 				};
 				await fs.writeFile(metaPath, JSON.stringify(lockData), "utf-8");
 				granted.push(filePath);
-			} catch (e: any) {
-				if (e.code === "EEXIST") {
+			} catch (e) {
+				const err = e as NodeJS.ErrnoException;
+				if (err.code === "EEXIST") {
 					// Lock exists - check if expired or ours
 					try {
 						const content = await fs.readFile(metaPath, "utf-8");

package/dist/template/.opencode/tool/memory-read.ts

@@ -1,6 +1,6 @@
-import path from "path";
+import fs from "node:fs/promises";
+import path from "node:path";
 import { tool } from "@opencode-ai/plugin";
-import fs from "fs/promises";
 
 export default tool({
 	description:

package/dist/template/.opencode/tool/memory-search.ts

@@ -1,6 +1,6 @@
-import path from "path";
+import fs from "node:fs/promises";
+import path from "node:path";
 import { tool } from "@opencode-ai/plugin";
-import fs from "fs/promises";
 
 interface SearchResult {
 	file: string;

package/dist/template/.opencode/tool/memory-update.ts

@@ -1,6 +1,6 @@
-import path from "path";
+import fs from "node:fs/promises";
+import path from "node:path";
 import { tool } from "@opencode-ai/plugin";
-import fs from "fs/promises";
 
 export default tool({
 	description:
@@ -41,21 +41,20 @@ export default tool({
 				const appendContent = `\n\n---\n**Updated:** ${timestamp}\n\n${args.content}`;
 				await fs.appendFile(filePath, appendContent, "utf-8");
 				return `Successfully appended to ${normalizedFile}.md\n[Written to: ${filePath}]`;
-			} else {
-				// Replace mode - update timestamp
-				const timestamp = new Date().toISOString();
-				const updatedContent = args.content.replace(
-					/\*\*Last Updated:\*\* \[Timestamp\]/,
-					`**Last Updated:** ${timestamp}`,
-				);
-				await fs.writeFile(filePath, updatedContent, "utf-8");
-				return `Successfully updated ${normalizedFile}.md\n[Written to: ${filePath}]`;
 			}
+			// Replace mode - update timestamp
+			const timestamp = new Date().toISOString();
+			const updatedContent = args.content.replace(
+				/\*\*Last Updated:\*\* \[Timestamp\]/,
+				`**Last Updated:** ${timestamp}`,
+			);
+			await fs.writeFile(filePath, updatedContent, "utf-8");
+			return `Successfully updated ${normalizedFile}.md\n[Written to: ${filePath}]`;
 		} catch (error) {
 			if (error instanceof Error) {
 				return `Error updating memory: ${error.message}`;
 			}
-			return `Unknown error updating memory file`;
+			return "Unknown error updating memory file";
 		}
 	},
 });