sparkecoder 0.1.58 → 0.1.60

package/dist/skills/default/browser.md

@@ -0,0 +1,143 @@
+---
+name: Browser Automation
+description: Web browser automation using agent-browser for navigation, interaction, screenshots, and testing
+---
+
+# Browser Automation Skill
+
+Use `agent-browser` for all web browser automation tasks including navigation, form filling, clicking, screenshots, and testing.
+
+## Setup
+
+If Chromium hasn't been installed yet, run:
+```bash
+agent-browser install
+```
+
+## Core Workflow
+
+Every browser automation follows this pattern:
+
+```bash
+# 1. Navigate to a page
+agent-browser open <url>
+
+# 2. Snapshot to get element refs
+agent-browser snapshot -i
+
+# 3. Interact using refs from the snapshot
+agent-browser click @e2
+agent-browser fill @e3 "text"
+
+# 4. Re-snapshot after page changes
+agent-browser snapshot -i
+
+# 5. Close when done
+agent-browser close
+```
+
+## Element Refs
+
+The `snapshot -i` command returns a compact accessibility tree where each interactive element has a unique ref like `@e1`, `@e2`. Use these refs for all interactions - they are deterministic and point to the exact element from the snapshot.
+
+```bash
+agent-browser snapshot -i
+# Output:
+# @e1 [heading] "Example Domain"
+# @e2 [link] "More information..."
+# @e3 [textbox] "Email"
+# @e4 [button] "Submit"
+```
+
+## Common Commands
+
+### Navigation
+```bash
+agent-browser open example.com
+agent-browser open example.com --headed    # Show browser window for debugging
+agent-browser back                         # Go back
+agent-browser forward                      # Go forward
+agent-browser reload                       # Reload page
+```
+
+### Interaction
+```bash
+agent-browser click @e2                    # Click by ref
+agent-browser fill @e3 "test@example.com"  # Fill input
+agent-browser select @e4 "option1"         # Select dropdown option
+agent-browser check @e5                    # Check checkbox
+agent-browser uncheck @e5                  # Uncheck checkbox
+agent-browser hover @e2                    # Hover over element
+agent-browser focus @e3                    # Focus element
+```
+
+### Reading Content
+```bash
+agent-browser get text @e1                 # Get text content of element
+agent-browser get value @e3                # Get input value
+agent-browser get attribute @e2 href       # Get attribute value
+agent-browser snapshot                     # Full page accessibility tree
+agent-browser snapshot -i                  # Interactive elements only
+```
+
+### Screenshots
+```bash
+agent-browser screenshot                   # Save to temp directory
+agent-browser screenshot page.png          # Save to specific path
+agent-browser screenshot --fullpage        # Full page screenshot
+```
+
+After taking a screenshot, use `read_file` to view it:
+```
+read_file({ path: "page.png" })
+```
+The `read_file` tool supports images (png, jpg, gif, webp) and will display them visually so you can analyze the page.
+
+### Waiting
+```bash
+agent-browser wait @e1                     # Wait for element to appear
+agent-browser wait --load networkidle      # Wait for network idle
+agent-browser wait --url "**/dashboard"    # Wait for URL pattern
+agent-browser wait 2000                    # Wait milliseconds
+```
+
+### Sessions
+```bash
+agent-browser sessions                     # List active sessions
+agent-browser close                        # Close current session
+agent-browser close --all                  # Close all sessions
+```
+
+## Command Chaining
+
+Chain commands with `&&` when you don't need intermediate output:
+
+```bash
+# Open, wait, and snapshot in one call
+agent-browser open example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
+
+# Fill a form
+agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "password" && agent-browser click @e3
+```
+
+Run commands separately when you need to parse output first (e.g., snapshot to discover refs before interacting).
+
+## CSS Selectors
+
+CSS selectors and semantic locators also work:
+
+```bash
+agent-browser click "#submit"
+agent-browser fill "#email" "test@example.com"
+agent-browser find role button click --name "Submit"
+```
+
+## Best Practices
+
+1. **Always snapshot before interacting** - You need refs to click/fill elements
+2. **Re-snapshot after navigation or page changes** - Refs become stale after the page changes
+3. **Use `--headed` for debugging** - Shows the browser window so you can see what's happening
+4. **Use `wait` for dynamic content** - Pages with async loading need waits before snapshots
+5. **Chain when possible** - Reduces round trips for simple sequences
+6. **Close when done** - Always close the browser session when finished
+7. **Use refs over CSS selectors** - Refs from snapshots are more reliable and context-efficient

package/dist/skills/default/code-review.md

@@ -0,0 +1,122 @@
+---
+name: Code Review
+description: Best practices and checklist for reviewing code changes
+---
+
+# Code Review Skill
+
+This skill provides guidelines and checklists for conducting thorough code reviews.
+
+## Code Review Checklist
+
+### Functionality
+- [ ] Does the code do what it's supposed to do?
+- [ ] Are edge cases handled properly?
+- [ ] Is error handling appropriate and complete?
+- [ ] Are there any obvious bugs or logic errors?
+
+### Code Quality
+- [ ] Is the code readable and self-documenting?
+- [ ] Are variable and function names descriptive?
+- [ ] Is there appropriate commenting for complex logic?
+- [ ] Does the code follow DRY (Don't Repeat Yourself) principles?
+- [ ] Is the code modular and well-organized?
+
+### Style & Consistency
+- [ ] Does the code follow the project's style guide?
+- [ ] Is formatting consistent with the rest of the codebase?
+- [ ] Are imports organized properly?
+- [ ] Is there consistent use of language features?
+
+### Performance
+- [ ] Are there any obvious performance issues?
+- [ ] Are database queries optimized?
+- [ ] Is there unnecessary computation in loops?
+- [ ] Are resources properly managed (memory, connections, etc.)?
+
+### Security
+- [ ] Is user input validated and sanitized?
+- [ ] Are there any SQL injection vulnerabilities?
+- [ ] Are secrets/credentials properly handled?
+- [ ] Is authentication/authorization implemented correctly?
+- [ ] Are there any XSS vulnerabilities?
+
+### Testing
+- [ ] Are there adequate unit tests?
+- [ ] Do tests cover edge cases?
+- [ ] Are tests readable and maintainable?
+- [ ] Do all tests pass?
+
+### Documentation
+- [ ] Is public API documented?
+- [ ] Are complex algorithms explained?
+- [ ] Is README updated if needed?
+- [ ] Are breaking changes documented?
+
+## Review Process
+
+### 1. Understand the Context
+- Read the PR description and related issues
+- Understand the motivation for the change
+- Check if the approach aligns with project architecture
+
+### 2. High-Level Review
+- Review the overall structure and approach
+- Check if the solution is appropriate for the problem
+- Look for architectural concerns
+
+### 3. Detailed Review
+- Go through each file change
+- Check for bugs, edge cases, and logic errors
+- Verify code quality and style
+
+### 4. Run the Code
+- Pull the branch and test locally if possible
+- Verify the functionality works as expected
+- Test edge cases and error scenarios
+
+### 5. Provide Feedback
+- Be specific and constructive
+- Explain why something is an issue
+- Suggest alternatives when requesting changes
+- Praise good solutions and improvements
+
+## Giving Good Feedback
+
+### Do
+- Be respectful and constructive
+- Focus on the code, not the person
+- Ask questions to understand intent
+- Provide specific suggestions
+- Acknowledge good work
+
+### Don't
+- Be condescending or dismissive
+- Nitpick on trivial issues
+- Request changes for personal preference
+- Leave vague comments like "fix this"
+
+### Comment Examples
+
+**Good:**
+```
+Consider using a Map instead of an object here for better performance 
+with frequent lookups. Maps have O(1) lookup time and handle 
+non-string keys better.
+```
+
+**Bad:**
+```
+This is wrong.
+```
+
+## Common Issues to Watch For
+
+1. **Null/Undefined Checks** - Missing null checks that could cause runtime errors
+2. **Resource Leaks** - Connections, file handles, or memory not properly released
+3. **Race Conditions** - Concurrent access issues in async code
+4. **Error Swallowing** - Catching errors without proper handling or logging
+5. **Magic Numbers** - Unexplained numeric constants
+6. **Copy-Paste Code** - Duplicated logic that should be extracted
+7. **Over-Engineering** - Unnecessary complexity for simple problems
+8. **Under-Engineering** - Missing error handling, validation, or edge cases

package/dist/skills/default/debugging.md

@@ -0,0 +1,105 @@
+---
+name: Debugging
+description: Systematic approaches for debugging code issues and errors
+---
+
+# Debugging Skill
+
+This skill provides systematic approaches for debugging code issues and errors.
+
+## Debugging Process
+
+### 1. Reproduce the Issue
+- Identify the exact steps to reproduce the bug
+- Note any error messages, stack traces, or unexpected behavior
+- Determine if the issue is consistent or intermittent
+
+### 2. Gather Information
+- Read relevant log files and error output
+- Check recent code changes (use `git log` and `git diff`)
+- Review configuration files and environment variables
+- Examine the state of the system when the error occurs
+
+### 3. Isolate the Problem
+- Use binary search to narrow down the problematic code
+- Create minimal reproduction cases
+- Test individual components in isolation
+- Check for common culprits:
+  - Null/undefined values
+  - Type mismatches
+  - Race conditions
+  - Resource leaks
+  - Configuration errors
+
+### 4. Form and Test Hypotheses
+- Based on gathered information, form theories about the cause
+- Test each hypothesis methodically
+- Keep track of what you've tried and the results
+- Don't assume - verify each step
+
+### 5. Fix and Verify
+- Make the minimal change needed to fix the issue
+- Write tests to prevent regression
+- Verify the fix doesn't introduce new problems
+- Document the root cause and solution
+
+## Common Debugging Techniques
+
+### Console/Log Debugging
+```javascript
+console.log('Variable value:', variable);
+console.log('Reached checkpoint:', checkpointName);
+console.trace('Stack trace at this point');
+```
+
+### Binary Search Debugging
+- Comment out half the suspect code
+- If the problem persists, the bug is in the remaining half
+- Repeat until you isolate the problematic line
+
+### Rubber Duck Debugging
+- Explain the code line by line to yourself (or a rubber duck)
+- Often the act of explaining reveals the issue
+
+### Git Bisect
+```bash
+git bisect start
+git bisect bad  # Current commit is broken
+git bisect good <commit>  # Known good commit
+# Git will checkout commits for you to test
+```
+
+## Error Categories
+
+### Syntax Errors
+- Missing brackets, quotes, or semicolons
+- Typos in variable/function names
+- Invalid language constructs
+
+### Runtime Errors
+- Null pointer exceptions
+- Division by zero
+- Array index out of bounds
+- Type errors
+
+### Logic Errors
+- Incorrect algorithm implementation
+- Wrong conditional logic
+- Off-by-one errors
+- State management issues
+
+### Integration Errors
+- API contract mismatches
+- Configuration problems
+- Dependency version conflicts
+- Environment differences
+
+## Best Practices
+
+1. **Don't panic** - Take a systematic approach
+2. **Read the error message** - It often tells you exactly what's wrong
+3. **Check the obvious first** - Typos, syntax, configuration
+4. **Use version control** - `git diff` to see recent changes
+5. **Keep notes** - Document what you've tried and learned
+6. **Take breaks** - Fresh eyes often spot issues faster
+7. **Ask for help** - A second perspective can be invaluable

package/dist/skills/default/refactoring.md

@@ -0,0 +1,197 @@
+---
+name: Refactoring
+description: Patterns and techniques for safely improving code structure
+---
+
+# Refactoring Skill
+
+This skill provides patterns and techniques for safely improving code structure without changing behavior.
+
+## Refactoring Principles
+
+### 1. Make it Work, Make it Right, Make it Fast
+- First, get the code working correctly
+- Then, clean up and improve structure
+- Finally, optimize for performance if needed
+
+### 2. Small, Incremental Changes
+- Make one small change at a time
+- Test after each change
+- Commit frequently to track progress
+
+### 3. Preserve Behavior
+- The external behavior should remain unchanged
+- Tests should pass before and after refactoring
+- If no tests exist, write them first
+
+## Common Refactoring Patterns
+
+### Extract Function
+**When:** A code block can be grouped and named
+```javascript
+// Before
+function processOrder(order) {
+  // ... lots of code ...
+  let total = 0;
+  for (const item of order.items) {
+    total += item.price * item.quantity;
+  }
+  // ... more code ...
+}
+
+// After
+function calculateTotal(items) {
+  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
+}
+
+function processOrder(order) {
+  // ... lots of code ...
+  const total = calculateTotal(order.items);
+  // ... more code ...
+}
+```
+
+### Extract Variable
+**When:** An expression is complex or used multiple times
+```javascript
+// Before
+if (order.items.length > 0 && order.status === 'pending' && order.total > 100) {
+  applyDiscount(order);
+}
+
+// After
+const isEligibleForDiscount = 
+  order.items.length > 0 && 
+  order.status === 'pending' && 
+  order.total > 100;
+
+if (isEligibleForDiscount) {
+  applyDiscount(order);
+}
+```
+
+### Replace Conditional with Polymorphism
+**When:** Multiple conditionals check the same type
+```javascript
+// Before
+function getArea(shape) {
+  switch (shape.type) {
+    case 'circle': return Math.PI * shape.radius ** 2;
+    case 'rectangle': return shape.width * shape.height;
+    case 'triangle': return (shape.base * shape.height) / 2;
+  }
+}
+
+// After
+class Circle {
+  getArea() { return Math.PI * this.radius ** 2; }
+}
+class Rectangle {
+  getArea() { return this.width * this.height; }
+}
+class Triangle {
+  getArea() { return (this.base * this.height) / 2; }
+}
+```
+
+### Replace Magic Numbers with Constants
+**When:** Numeric literals appear in code
+```javascript
+// Before
+if (user.age >= 18) {
+  allowAccess();
+}
+
+// After
+const MINIMUM_AGE = 18;
+if (user.age >= MINIMUM_AGE) {
+  allowAccess();
+}
+```
+
+### Introduce Parameter Object
+**When:** Multiple parameters are often passed together
+```javascript
+// Before
+function createUser(firstName, lastName, email, phone, address, city, country) {
+  // ...
+}
+
+// After
+function createUser(personalInfo, contactInfo) {
+  // ...
+}
+```
+
+### Replace Nested Conditionals with Guard Clauses
+**When:** Code has deep nesting from conditionals
+```javascript
+// Before
+function getPayAmount(employee) {
+  if (employee.isSeparated) {
+    return separatedAmount();
+  } else {
+    if (employee.isRetired) {
+      return retiredAmount();
+    } else {
+      return normalPayAmount();
+    }
+  }
+}
+
+// After
+function getPayAmount(employee) {
+  if (employee.isSeparated) return separatedAmount();
+  if (employee.isRetired) return retiredAmount();
+  return normalPayAmount();
+}
+```
+
+## Refactoring Process
+
+### 1. Ensure Test Coverage
+- Write tests for existing behavior if none exist
+- All tests should pass before starting
+
+### 2. Identify Code Smells
+- Long functions
+- Large classes
+- Duplicate code
+- Complex conditionals
+- Long parameter lists
+- Feature envy
+- Primitive obsession
+
+### 3. Apply Appropriate Refactoring
+- Choose the right pattern for the smell
+- Make small, incremental changes
+- Run tests after each change
+
+### 4. Review and Iterate
+- Check if the code is clearer
+- Look for further improvements
+- Ensure performance hasn't degraded
+
+## Code Smells Reference
+
+| Smell | Description | Common Refactorings |
+|-------|-------------|---------------------|
+| Long Method | Function does too much | Extract Function |
+| Large Class | Class has too many responsibilities | Extract Class |
+| Duplicate Code | Same code in multiple places | Extract Function, Template Method |
+| Long Parameter List | Too many function parameters | Introduce Parameter Object |
+| Feature Envy | Method uses other class's data too much | Move Method |
+| Data Clumps | Same data items often appear together | Extract Class |
+| Primitive Obsession | Overuse of primitives instead of objects | Replace Primitive with Object |
+| Switch Statements | Complex switch/case logic | Replace with Polymorphism |
+| Speculative Generality | Unused abstraction for "future" use | Remove |
+| Dead Code | Unreachable or unused code | Remove |
+
+## Safety Checklist
+
+- [ ] Tests exist and pass before starting
+- [ ] Making one small change at a time
+- [ ] Running tests after each change
+- [ ] Committing after each successful refactoring
+- [ ] External behavior is preserved
+- [ ] No new features added during refactoring

package/dist/tools/index.d.ts

@@ -1,7 +1,7 @@
 import * as ai from 'ai';
 import { ToolSet } from 'ai';
-import { B as BashToolProgress, W as WriteFileProgress, S as SearchToolProgress } from '../search-DINnDTgj.js';
-export { b as BashToolOptions, d as SearchToolOptions, e as WriteFileToolOptions, c as createBashTool, f as createSearchTool, a as createWriteFileTool } from '../search-DINnDTgj.js';
+import { B as BashToolProgress, W as WriteFileProgress, S as SearchToolProgress } from '../search-BETuS1vh.js';
+export { b as BashToolOptions, d as SearchToolOptions, e as WriteFileToolOptions, c as createBashTool, f as createSearchTool, a as createWriteFileTool } from '../search-BETuS1vh.js';
 
 interface ReadFileToolOptions {
     workingDirectory: string;
@@ -11,6 +11,17 @@ declare function createReadFileTool(options: ReadFileToolOptions): ai.Tool<{
     startLine?: number | undefined;
     endLine?: number | undefined;
 }, {
+    success: boolean;
+    path: string;
+    relativePath: string;
+    content: string;
+    mediaType: string;
+    imageData: string;
+    sizeBytes: number;
+    lineCount?: undefined;
+    wasTruncated?: undefined;
+    error?: undefined;
+} | {
     success: boolean;
     path: string;
     relativePath: string;
@@ -18,6 +29,8 @@ declare function createReadFileTool(options: ReadFileToolOptions): ai.Tool<{
     lineCount: number;
     wasTruncated: boolean;
     sizeBytes: number;
+    mediaType?: undefined;
+    imageData?: undefined;
     error?: undefined;
 } | {
     success: boolean;
@@ -25,9 +38,11 @@ declare function createReadFileTool(options: ReadFileToolOptions): ai.Tool<{
     content: null;
     path?: undefined;
     relativePath?: undefined;
+    mediaType?: undefined;
+    imageData?: undefined;
+    sizeBytes?: undefined;
     lineCount?: undefined;
     wasTruncated?: undefined;
-    sizeBytes?: undefined;
 }>;
 
 interface TodoToolOptions {