@compilr-dev/agents-coding 0.0.1

package/README.md

@@ -0,0 +1,788 @@
+# @compilr-dev/agents-coding
+
+Coding-specific tools for [@compilr-dev/agents](https://github.com/scozzola/compilr-dev-agents) - Git operations, project detection, smart runners, and code search.
+
+## Overview
+
+This extension package provides tools specifically designed for building AI coding assistants. It complements the core `@compilr-dev/agents` library with:
+
+- **Git Tools** - Structured git operations with parsed output
+- **Project Detection** - Auto-detect project type, package manager, and tooling
+- **Smart Runners** - Auto-detect and run tests, lint, build, format
+- **Code Search** - Find definitions, references, and TODO comments
+
+## Installation
+
+```bash
+npm install @compilr-dev/agents-coding @compilr-dev/agents
+```
+
+## Quick Start
+
+```typescript
+import { Agent } from '@compilr-dev/agents';
+import { allCodingTools } from '@compilr-dev/agents-coding';
+
+// Create an agent with coding tools
+const agent = new Agent({
+  provider: yourProvider,
+  tools: allCodingTools,
+});
+
+// Or register specific tools
+import {
+  gitStatusTool,
+  gitCommitTool,
+  gitBranchTool,
+  detectProjectTool,
+  runTestsTool,
+  runLintTool,
+  findDefinitionTool,
+  findReferencesTool,
+  findTodosTool,
+} from '@compilr-dev/agents-coding';
+
+const agent = new Agent({
+  provider: yourProvider,
+  tools: [gitStatusTool, detectProjectTool],
+});
+```
+
+## Available Tools
+
+### Project Detection
+
+#### `detectProjectTool`
+
+Detect project type and available tooling in a directory.
+
+```typescript
+const result = await detectProjectTool.execute({ path: '/path/to/project' });
+// Returns:
+// {
+//   type: 'node',
+//   types: ['node'],
+//   packageManager: 'pnpm',
+//   testFramework: 'vitest',
+//   linter: 'eslint',
+//   formatter: 'prettier',
+//   buildTool: 'vite',
+//   configFiles: ['package.json', 'tsconfig.json'],
+//   name: 'my-project'
+// }
+```
+
+**Supported Project Types:**
+- `node` - package.json
+- `python` - pyproject.toml, setup.py, requirements.txt
+- `rust` - Cargo.toml
+- `go` - go.mod
+- `java` - pom.xml, build.gradle
+- `ruby` - Gemfile
+- `php` - composer.json
+- `dotnet` - *.csproj, *.sln
+
+#### `findProjectRootTool`
+
+Find the root directory of a project by looking for marker files.
+
+```typescript
+const result = await findProjectRootTool.execute({
+  path: '/path/to/project/src/components',
+  markers: ['.git', 'package.json'] // optional, uses defaults
+});
+// Returns:
+// {
+//   root: '/path/to/project',
+//   foundMarker: 'package.json',
+//   depth: 2
+// }
+```
+
+### Git Tools
+
+#### `gitStatusTool`
+
+Get structured git working tree status.
+
+```typescript
+const result = await gitStatusTool.execute({ path: '/path/to/repo' });
+// Returns:
+// {
+//   branch: 'main',
+//   tracking: { remote: 'origin/main', ahead: 2, behind: 0 },
+//   staged: [{ path: 'src/index.ts', status: 'modified' }],
+//   modified: [{ path: 'README.md', status: 'modified' }],
+//   untracked: ['temp.txt'],
+//   isClean: false
+// }
+```
+
+**Options:**
+- `includeUntracked` - Include untracked files (default: true)
+- `short` - Also return short format status string
+
+#### `gitDiffTool`
+
+Show changes between commits, working tree, etc.
+
+```typescript
+// Unstaged changes
+const result = await gitDiffTool.execute({ path: '/path/to/repo' });
+
+// Staged changes
+const result = await gitDiffTool.execute({ path: '/path/to/repo', staged: true });
+
+// Compare with a ref
+const result = await gitDiffTool.execute({ path: '/path/to/repo', ref: 'HEAD~3' });
+
+// Compare two refs
+const result = await gitDiffTool.execute({
+  path: '/path/to/repo',
+  refA: 'main',
+  refB: 'feature-branch'
+});
+
+// Returns:
+// {
+//   diff: '--- a/file.txt\n+++ b/file.txt\n...',
+//   files: [{ path: 'file.txt', additions: 10, deletions: 3 }],
+//   stats: { filesChanged: 1, insertions: 10, deletions: 3 }
+// }
+```
+
+**Options:**
+- `staged` - Show staged changes instead of unstaged
+- `file` - Diff a specific file
+- `ref` - Compare with a commit/branch
+- `refA`, `refB` - Compare two refs
+- `context` - Number of context lines (default: 3)
+- `statOnly` - Show only statistics, no diff content
+- `nameOnly` - Show only names of changed files
+
+#### `gitLogTool`
+
+Show commit history with filtering options.
+
+```typescript
+const result = await gitLogTool.execute({
+  path: '/path/to/repo',
+  limit: 10,
+  author: 'john',
+  since: '2 weeks ago',
+  grep: 'feat:'
+});
+// Returns:
+// {
+//   commits: [
+//     {
+//       hash: 'abc123...',
+//       shortHash: 'abc123',
+//       author: 'John Doe',
+//       email: 'john@example.com',
+//       date: '2024-01-15T10:30:00Z',
+//       message: 'feat: add new feature',
+//       body: 'Detailed description...'
+//     }
+//   ]
+// }
+```
+
+**Options:**
+- `limit` - Number of commits (default: 10)
+- `file` - Filter by file path
+- `author` - Filter by author name/email
+- `since`, `until` - Date range filters
+- `grep` - Filter by message pattern
+- `ref` - Branch/ref to show log for
+- `stat` - Include diff statistics
+
+#### `gitCommitTool`
+
+Create a git commit with safety features.
+
+```typescript
+const result = await gitCommitTool.execute({
+  path: '/path/to/repo',
+  message: 'feat: add new feature',
+  files: ['src/index.ts', 'src/utils.ts'], // specific files to stage
+  // OR
+  addAll: true, // stage all including untracked
+  // OR
+  addModified: true, // stage only modified tracked files
+});
+// Returns:
+// {
+//   hash: 'abc123def456...',
+//   shortHash: 'abc123d',
+//   branch: 'main',
+//   filesCommitted: 2,
+//   insertions: 45,
+//   deletions: 12,
+//   message: 'feat: add new feature'
+// }
+```
+
+**Safety Features:**
+- Automatically blocks commits containing potential secrets (`.env`, `credentials.json`, `.pem`, etc.)
+- Warns about large files (>1MB)
+- Requires explicit confirmation for `amend` and `noVerify` options
+
+**Options:**
+- `message` (required) - Commit message
+- `files` - Specific files to stage before committing
+- `addAll` - Stage all files including untracked (`git add -A`)
+- `addModified` - Stage modified/deleted tracked files only (`git add -u`)
+- `allowEmpty` - Allow creating an empty commit
+- `amend` - Amend the previous commit (dangerous)
+- `noVerify` - Skip pre-commit hooks (dangerous)
+
+#### `gitBranchTool`
+
+Manage git branches.
+
+```typescript
+// List all branches
+const result = await gitBranchTool.execute({
+  path: '/path/to/repo',
+  action: 'list',
+  remotes: true, // include remote branches
+});
+// Returns:
+// {
+//   current: 'main',
+//   branches: [
+//     { name: 'main', isCurrent: true, tracking: 'origin/main', lastCommit: 'abc123' },
+//     { name: 'feature-x', isCurrent: false, tracking: 'origin/feature-x' }
+//   ],
+//   message: 'Found 2 branch(es)'
+// }
+
+// Create a new branch
+await gitBranchTool.execute({
+  path: '/path/to/repo',
+  action: 'create',
+  name: 'feature-y',
+  startPoint: 'main', // optional base
+});
+
+// Switch branches
+await gitBranchTool.execute({
+  path: '/path/to/repo',
+  action: 'switch',
+  name: 'feature-y',
+});
+
+// Delete a branch
+await gitBranchTool.execute({
+  path: '/path/to/repo',
+  action: 'delete',
+  name: 'feature-y',
+  force: true, // delete even if not merged
+});
+
+// Rename a branch
+await gitBranchTool.execute({
+  path: '/path/to/repo',
+  action: 'rename',
+  name: 'old-name',
+  newName: 'new-name',
+});
+```
+
+**Actions:**
+- `list` - Show all branches
+- `create` - Create a new branch
+- `delete` - Delete a branch (protects current branch)
+- `switch` - Switch to a branch
+- `rename` - Rename a branch
+
+#### `gitStashTool`
+
+Manage git stashes.
+
+```typescript
+// Stash current changes
+const result = await gitStashTool.execute({
+  path: '/path/to/repo',
+  action: 'push',
+  message: 'WIP: feature work',
+  includeUntracked: true,
+});
+// Returns:
+// { message: 'Stashed changes: WIP: feature work' }
+
+// List all stashes
+const result = await gitStashTool.execute({
+  path: '/path/to/repo',
+  action: 'list',
+});
+// Returns:
+// {
+//   stashes: [
+//     { ref: 'stash@{0}', index: 0, branch: 'main', message: 'WIP: feature work' },
+//     { ref: 'stash@{1}', index: 1, branch: 'main', message: 'backup' }
+//   ],
+//   message: 'Found 2 stash(es)'
+// }
+
+// Pop stash (apply and remove)
+await gitStashTool.execute({
+  path: '/path/to/repo',
+  action: 'pop',
+  index: 0, // optional, defaults to 0
+});
+
+// Apply stash (keep in stash list)
+await gitStashTool.execute({
+  path: '/path/to/repo',
+  action: 'apply',
+  index: 0,
+});
+
+// Show stash contents
+const result = await gitStashTool.execute({
+  path: '/path/to/repo',
+  action: 'show',
+  index: 0,
+});
+// Returns:
+// { diff: '--- a/file.txt\n...', message: ' file.txt | 5 ++---\n 1 file changed...' }
+
+// Drop a specific stash
+await gitStashTool.execute({
+  path: '/path/to/repo',
+  action: 'drop',
+  index: 1,
+});
+
+// Clear all stashes
+await gitStashTool.execute({
+  path: '/path/to/repo',
+  action: 'clear',
+});
+```
+
+**Actions:**
+- `push` - Save changes to stash
+- `pop` - Apply and remove stash
+- `apply` - Apply stash without removing
+- `list` - Show all stashes
+- `drop` - Remove a specific stash
+- `clear` - Remove all stashes
+- `show` - Display stash contents
+
+### Smart Runner Tools
+
+All runner tools support a `dryRun` option to detect the tool/framework and return the command without actually executing it. This is useful for:
+- Previewing what command would run
+- Testing detection logic without side effects
+- Implementing "rehearsal" patterns for safety
+
+```typescript
+// Dry run - just detect, don't execute
+const result = await runBuildTool.execute({
+  path: '/path/to/project',
+  dryRun: true,
+});
+// Returns detected tool and command without running it:
+// { buildTool: 'vite', command: 'npx vite build', output: '(dry run - command not executed)' }
+```
+
+#### `runTestsTool`
+
+Auto-detect and run tests using the appropriate test framework.
+
+```typescript
+const result = await runTestsTool.execute({
+  path: '/path/to/project',
+  pattern: 'src/**/*.test.ts', // optional filter
+  coverage: true,
+  verbose: true,
+});
+// Returns:
+// {
+//   command: 'npx vitest run --coverage',
+//   output: '...',
+//   exitCode: 0,
+//   duration: 5230,
+//   success: true,
+//   framework: 'vitest',
+//   passed: 42,
+//   failed: 0,
+//   total: 42
+// }
+```
+
+**Supported Frameworks:**
+- `vitest` - vitest.config.ts/js or dependency
+- `jest` - jest.config.ts/js/json or dependency
+- `mocha` - .mocharc.json/js/yaml or dependency
+- `ava` - ava.config.js/cjs or dependency
+- `npm test` - package.json scripts.test
+- `pytest` - pytest.ini, pyproject.toml, conftest.py
+- `unittest` - setup.py, setup.cfg
+- `cargo test` - Cargo.toml
+- `go test` - go.mod
+
+**Options:**
+- `pattern` - Test file pattern or name filter
+- `watch` - Run in watch mode
+- `coverage` - Generate coverage report
+- `verbose` - Verbose output
+- `updateSnapshots` - Update test snapshots (jest/vitest)
+- `timeout` - Command timeout in milliseconds
+
+#### `runLintTool`
+
+Auto-detect and run linter.
+
+```typescript
+const result = await runLintTool.execute({
+  path: '/path/to/project',
+  fix: true,
+  files: ['src/index.ts'],
+});
+// Returns:
+// {
+//   command: 'npx eslint src/index.ts --fix',
+//   output: '...',
+//   exitCode: 0,
+//   duration: 1230,
+//   success: true,
+//   linter: 'eslint',
+//   errors: 0,
+//   warnings: 2
+// }
+```
+
+**Supported Linters:**
+- `eslint` - eslint.config.js/mjs/cjs, .eslintrc.* or dependency
+- `biome` - biome.json/jsonc or dependency
+- `npm lint` - package.json scripts.lint
+- `ruff` - ruff.toml, .ruff.toml
+- `pylint` - .pylintrc, pylintrc
+- `flake8` - .flake8, setup.cfg
+- `clippy` - Cargo.toml
+- `golangci-lint` - .golangci.yml/yaml/json or go.mod
+
+**Options:**
+- `files` - Specific files to lint
+- `fix` - Auto-fix issues
+- `format` - Output format (json, stylish, etc.)
+- `timeout` - Command timeout
+
+#### `runBuildTool`
+
+Auto-detect and run build.
+
+```typescript
+const result = await runBuildTool.execute({
+  path: '/path/to/project',
+  production: true,
+});
+// Returns:
+// {
+//   command: 'npx vite build --mode production',
+//   output: '...',
+//   exitCode: 0,
+//   duration: 8500,
+//   success: true,
+//   buildTool: 'vite'
+// }
+```
+
+**Supported Build Tools:**
+- `vite` - vite.config.ts/js/mjs or dependency
+- `next` - next.config.js/mjs/ts or dependency
+- `tsc` - tsconfig.json with typescript dependency
+- `webpack` - webpack.config.js/ts or dependency
+- `rollup` - rollup.config.js/mjs or dependency
+- `esbuild` - esbuild.config.js/mjs or dependency
+- `turbo` - turbo.json or dependency
+- `npm build` - package.json scripts.build
+- `cargo build` - Cargo.toml
+- `go build` - go.mod
+- `python build` - setup.py, pyproject.toml
+- `maven` - pom.xml
+- `gradle` - build.gradle, build.gradle.kts
+
+**Options:**
+- `production` - Build for production
+- `clean` - Clean before build
+- `timeout` - Command timeout
+
+#### `runFormatTool`
+
+Auto-detect and run formatter.
+
+```typescript
+const result = await runFormatTool.execute({
+  path: '/path/to/project',
+  check: true, // check only, don't write
+});
+// Returns:
+// {
+//   command: 'npx prettier --check .',
+//   output: '...',
+//   exitCode: 0,
+//   duration: 2100,
+//   success: true,
+//   formatter: 'prettier',
+//   filesProcessed: 45
+// }
+```
+
+**Supported Formatters:**
+- `prettier` - .prettierrc.* or prettier.config.* or dependency
+- `biome` - biome.json/jsonc or dependency
+- `dprint` - dprint.json, .dprint.json or dependency
+- `npm format` - package.json scripts.format
+- `black` - pyproject.toml, .black
+- `ruff format` - ruff.toml, .ruff.toml
+- `autopep8` - .pep8, setup.cfg
+- `rustfmt` - Cargo.toml
+- `gofmt` - go.mod
+- `goimports` - go.mod
+
+**Options:**
+- `files` - Specific files to format
+- `check` - Check only, don't write changes
+- `timeout` - Command timeout
+
+### Code Search Tools
+
+#### `findDefinitionTool`
+
+Find where a symbol is defined in the codebase.
+
+```typescript
+const result = await findDefinitionTool.execute({
+  path: '/path/to/project',
+  symbol: 'calculateSum',
+  fileType: 'ts', // optional filter
+});
+// Returns:
+// {
+//   definitions: [
+//     {
+//       file: 'src/utils.ts',
+//       line: 8,
+//       column: 17,
+//       context: 'export function calculateSum(a: number, b: number): number {',
+//       type: 'function',
+//       isExported: true
+//     }
+//   ],
+//   totalFound: 1,
+//   symbol: 'calculateSum'
+// }
+```
+
+**Supported Languages:**
+- TypeScript/JavaScript - functions, classes, interfaces, types, const, enums
+- Python - functions, classes, async functions
+- Rust - fn, struct, enum, trait, type
+- Go - func, type, const, var
+- Java/Kotlin - classes, interfaces, methods
+
+**Options:**
+- `symbol` (required) - Symbol name to find
+- `path` - Working directory
+- `fileType` - File type filter (ts, py, rs, go, java, etc.)
+- `limit` - Maximum results (default: 20)
+
+#### `findReferencesTool`
+
+Find all usages of a symbol in the codebase.
+
+```typescript
+const result = await findReferencesTool.execute({
+  path: '/path/to/project',
+  symbol: 'calculateSum',
+  excludeDefinitions: true,
+});
+// Returns:
+// {
+//   references: [
+//     { file: 'src/main.ts', line: 5, column: 18, context: '  const sum = calculateSum(1, 2);' },
+//     { file: 'src/calc.ts', line: 12, column: 10, context: '  return calculateSum(a, b);' }
+//   ],
+//   totalFound: 2,
+//   symbol: 'calculateSum'
+// }
+```
+
+**Options:**
+- `symbol` (required) - Symbol name to find
+- `path` - Working directory
+- `fileType` - File type filter
+- `excludeDefinitions` - Exclude definition lines, show only usages (default: false)
+- `limit` - Maximum results (default: 50)
+
+#### `findTodosTool`
+
+Find TODO, FIXME, HACK, and other comment markers in code.
+
+```typescript
+const result = await findTodosTool.execute({
+  path: '/path/to/project',
+  types: ['TODO', 'FIXME'],
+  includeAuthor: true,
+});
+// Returns:
+// {
+//   todos: [
+//     {
+//       type: 'TODO',
+//       file: 'src/utils.ts',
+//       line: 5,
+//       text: 'Add error handling',
+//       author: 'John Doe' // if includeAuthor: true
+//     },
+//     {
+//       type: 'FIXME',
+//       file: 'src/api.ts',
+//       line: 42,
+//       text: 'This needs optimization'
+//     }
+//   ],
+//   summary: { TODO: 1, FIXME: 1 },
+//   totalFound: 2
+// }
+```
+
+**Supported Comment Types:**
+- `TODO` - Tasks to be done
+- `FIXME` - Bugs to fix
+- `HACK` - Workarounds
+- `XXX` - Critical issues
+- `NOTE` - Important notes
+- `BUG` - Known bugs
+- `WARN` - Warnings
+
+**Options:**
+- `path` - Working directory
+- `types` - Comment types to find (default: all)
+- `fileType` - File type filter (ts, py, rs, go, etc.)
+- `includeAuthor` - Include git blame author info (slower, limited to first 20 results)
+- `limit` - Maximum results (default: 100)
+
+## Factory Functions
+
+Each tool has a factory function for customization:
+
+```typescript
+import { createGitStatusTool, createDetectProjectTool } from '@compilr-dev/agents-coding';
+
+// Custom base directory
+const customGitStatus = createGitStatusTool({
+  baseDir: '/workspace',
+  defaultIncludeUntracked: false,
+});
+
+const customDetectProject = createDetectProjectTool({
+  baseDir: '/workspace',
+});
+```
+
+## Design Principles
+
+1. **Zero Dependencies** - Only peer dependency on `@compilr-dev/agents`
+2. **Structured Output** - All tools return parsed, typed data (not raw strings)
+3. **CLI-First** - Uses git CLI directly for predictable behavior
+4. **Safety First** - Git tools include protections against dangerous operations
+5. **TypeScript Native** - Full type safety throughout
+
+## Roadmap
+
+### Phase 1: Foundation ✅
+- [x] detectProjectTool
+- [x] findProjectRootTool
+- [x] gitStatusTool
+- [x] gitDiffTool
+- [x] gitLogTool
+
+### Phase 2: Core Git ✅
+- [x] gitCommitTool - Create commits with safety features
+- [x] gitBranchTool - Branch management
+- [x] gitStashTool - Stash operations
+
+### Phase 3: Smart Runners ✅
+- [x] runTestsTool - Auto-detect and run tests
+- [x] runLintTool - Auto-detect and run linter
+- [x] runBuildTool - Auto-detect and run build
+- [x] runFormatTool - Auto-detect and run formatter
+
+### Phase 4: Code Search ✅
+- [x] findDefinitionTool - Find symbol definitions
+- [x] findReferencesTool - Find symbol usages
+- [x] findTodosTool - Find TODO/FIXME comments
+
+### Phase 5: Skills & Polish ✅
+- [x] Coding-specific skills (6 skills)
+- [x] Comprehensive documentation
+
+## Skills
+
+Coding-specific skills for specialized workflows. Use with `SkillRegistry` from `@compilr-dev/agents`.
+
+```typescript
+import { SkillRegistry } from '@compilr-dev/agents';
+import { codingSkills } from '@compilr-dev/agents-coding';
+
+const registry = new SkillRegistry();
+registry.registerAll(codingSkills);
+
+// Invoke a skill
+const result = registry.invoke('git-workflow');
+console.log(result.prompt); // Expanded skill prompt
+```
+
+### Available Skills
+
+| Skill | Description |
+|-------|-------------|
+| `git-workflow` | Best practices for git operations with safety checks |
+| `test-driven` | Test-driven development workflow with smart runners |
+| `code-navigation` | Effectively navigate and understand codebases |
+| `pr-workflow` | Pull request creation and review workflow |
+| `project-onboarding` | Quickly understand and navigate a new project |
+| `code-optimization` | Performance optimization workflow |
+
+### Skill Details
+
+#### `git-workflow`
+Safe git operations including verification before destructive actions, commit workflow, and recovery strategies.
+
+#### `test-driven`
+Red-Green-Refactor cycle with integration of `runTests`, `runLint`, `runBuild`, and `runFormat` tools.
+
+#### `code-navigation`
+Using `findDefinition`, `findReferences`, and `findTodos` to understand and navigate code.
+
+#### `pr-workflow`
+Complete PR workflow from branch preparation through review and merge, with pre-flight checks.
+
+#### `project-onboarding`
+Systematic approach to understanding new codebases using `detectProject` and search tools.
+
+#### `code-optimization`
+Performance optimization with measurement-first approach and common optimization patterns.
+
+## Runtime Dependencies
+
+Some tools require external programs to be installed:
+
+| Tool | Dependency | Installation |
+|------|------------|--------------|
+| Code Search tools | `ripgrep` (rg) | `apt install ripgrep` or `brew install ripgrep` |
+| Git tools | `git` | Usually pre-installed |
+
+## License
+
+MIT
+
+## Related
+
+- [@compilr-dev/agents](https://github.com/scozzola/compilr-dev-agents) - Core agent library