hone-ai 0.2.0 → 0.9.0

package/README.md

@@ -10,6 +10,8 @@ Transform feature ideas into working code through autonomous development with hu
 
    ```bash
    npm install -g hone-ai
+   # or
+   bun add -g hone-ai
    ```
 
 2. **Install an AI agent** ([OpenCode](https://opencode.ai) or [Claude Code](https://docs.anthropic.com/claude/docs/claude-code))
@@ -41,6 +43,8 @@ That's it! hone will implement the feature, run tests, and commit changes automa
 
 ```bash
 npm install -g hone-ai
+# or
+bun add -g hone-ai
 ```
 
 ### From Source
@@ -55,11 +59,22 @@ Use `bun src/index.ts` instead of `hone` for all commands.
 
 ### Standalone Binary
 
-Build a self-contained executable:
+Download pre-built binaries from [GitHub Releases](https://github.com/oskarhane/hone-ai/releases).
+
+**macOS users**: Remove the quarantine attribute after downloading:
+
+```bash
+unzip hone-v*-macos.zip
+xattr -d com.apple.quarantine hone-v*-macos/hone
+cp hone-v*-macos/hone /usr/local/bin/
+```
+
+Or build from source:
 
 ```bash
 bun run build
-cp hone /usr/local/bin/
+cp hone-macos /usr/local/bin/hone  # macOS
+cp hone-linux /usr/local/bin/hone  # Linux
 ```
 
 ## Common Commands
@@ -72,6 +87,20 @@ hone prd-to-tasks .plans/prd-feature.md     # Generate tasks
 hone run .plans/tasks-feature.yml -i 5      # Implement tasks
 ```
 
+### Reference files and URLs in PRDs
+
+```bash
+# Reference local files in your PRD description
+hone prd "Implement user authentication based on ./docs/auth-spec.md"
+hone prd "Add dashboard following the component in ./src/components/Dashboard.tsx"
+
+# Reference URLs for external specifications
+hone prd "Create payment integration using https://stripe.com/docs/api"
+hone prd "Build social login with https://developers.google.com/identity/protocols/oauth2"
+```
+
+hone automatically reads referenced files and fetches URL content to inform PRD generation.
+
 ### Check progress
 
 ```bash
@@ -114,6 +143,22 @@ hone breaks feature development into 3 phases:
 
 Each `hone run` executes multiple iterations of this cycle automatically.
 
+### File and URL References in PRDs
+
+When creating PRDs, you can reference files and URLs directly in your feature description:
+
+**Local files:**
+- `./docs/api-spec.md` - Read project documentation
+- `src/components/Button.tsx` - Analyze existing components
+- `./database/schema.sql` - Review database structure
+
+**URLs:**
+- `https://docs.stripe.com/api` - External API documentation
+- `https://www.figma.com/design/123/App` - Design specifications
+- `http://localhost:3000/dashboard` - Reference existing pages
+
+The AI agent automatically reads files and fetches web content to generate more accurate PRDs.
+
 ## File Structure
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hone-ai",
-  "version": "0.2.0",
+  "version": "0.9.0",
   "description": "AI coding agent orchestrator - orchestrate AI agents to implement features based on PRDs",
   "keywords": [
     "ai",
@@ -12,7 +12,7 @@
     "claude",
     "opencode"
   ],
-  "author": "Oskar Hane",
+  "author": "Oskar Hane <oskar.hane@gmail.com>",
   "license": "MIT",
   "files": [
     "src/",
@@ -21,7 +21,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/oskarhane/hone-ai.git"
+    "url": "git+https://github.com/oskarhane/hone-ai.git"
   },
   "bugs": {
     "url": "https://github.com/oskarhane/hone-ai/issues"
@@ -30,10 +30,13 @@
   "module": "src/index.ts",
   "type": "module",
   "bin": {
-    "hone": "./src/index.ts"
+    "hone": "src/index.ts"
   },
   "scripts": {
-    "build": "bun build --compile --minify --sourcemap ./src/index.ts --outfile hone",
+    "build": "bun run build:linux && bun run build:macos",
+    "format": "prettier --write \"**/*.ts\"",
+    "build:linux": "bun build --compile --minify --sourcemap --target=bun-linux-x64 ./src/index.ts --outfile hone-linux",
+    "build:macos": "bun build --compile --minify --sourcemap --target=bun-darwin-arm64 ./src/index.ts --outfile hone-macos",
     "format:yaml": "prettier --write \"**/*.yml\" \"**/*.yaml\"",
     "lint:yaml": "yamllint -c .yamllint.yml **/*.yml **/*.yaml",
     "check:yaml": "bun run lint:yaml && prettier --check \"**/*.yml\" \"**/*.yaml\""

package/src/agent-client.integration.test.ts

@@ -1,97 +1,95 @@
-import { describe, test, expect } from 'bun:test';
-import { AgentClient, type AgentMessageRequest } from './agent-client';
+import { describe, test, expect } from 'bun:test'
+import { AgentClient, type AgentMessageRequest } from './agent-client'
 
 describe('AgentClient Integration', () => {
   // Note: These tests verify the API surface is correct.
   // Actual agent subprocess spawning is tested manually or in CI
   // where real agent binaries (opencode/claude) are available.
-  
+
   describe('API compatibility', () => {
     test('mirrors Anthropic SDK interface', () => {
       const client = new AgentClient({
         agent: 'opencode',
-        model: 'claude-sonnet-4-20250514'
-      });
-      
+        model: 'claude-sonnet-4-20250514',
+      })
+
       // Verify the API surface matches Anthropic SDK
-      expect(client.messages).toBeDefined();
-      expect(typeof client.messages.create).toBe('function');
-      
+      expect(client.messages).toBeDefined()
+      expect(typeof client.messages.create).toBe('function')
+
       // Verify request structure matches Anthropic SDK
       const validRequest: AgentMessageRequest = {
         model: 'claude-sonnet-4-20250514',
         max_tokens: 4000,
-        messages: [
-          { role: 'user', content: 'Test message' }
-        ],
-        system: 'You are a helpful assistant'
-      };
-      
+        messages: [{ role: 'user', content: 'Test message' }],
+        system: 'You are a helpful assistant',
+      }
+
       // This shouldn't throw TypeScript errors
-      expect(validRequest.messages).toHaveLength(1);
-    });
-    
+      expect(validRequest.messages).toHaveLength(1)
+    })
+
     test('supports minimal request format', () => {
       const client = new AgentClient({
         agent: 'claude',
-        model: 'claude-sonnet-4-20250514'
-      });
-      
+        model: 'claude-sonnet-4-20250514',
+      })
+
       // Minimal valid request
       const minimalRequest: AgentMessageRequest = {
-        messages: [{ role: 'user', content: 'Hello' }]
-      };
-      
-      expect(minimalRequest.messages).toHaveLength(1);
-    });
-    
+        messages: [{ role: 'user', content: 'Hello' }],
+      }
+
+      expect(minimalRequest.messages).toHaveLength(1)
+    })
+
     test('supports multi-turn conversations', () => {
       const client = new AgentClient({
         agent: 'opencode',
-        model: 'claude-sonnet-4-20250514'
-      });
-      
+        model: 'claude-sonnet-4-20250514',
+      })
+
       const multiTurnRequest: AgentMessageRequest = {
         messages: [
           { role: 'user', content: 'What is 2+2?' },
           { role: 'assistant', content: '4' },
-          { role: 'user', content: 'What about 3+3?' }
-        ]
-      };
-      
-      expect(multiTurnRequest.messages).toHaveLength(3);
-    });
-  });
-  
+          { role: 'user', content: 'What about 3+3?' },
+        ],
+      }
+
+      expect(multiTurnRequest.messages).toHaveLength(3)
+    })
+  })
+
   describe('configuration', () => {
     test('accepts opencode agent configuration', () => {
       const client = new AgentClient({
         agent: 'opencode',
         model: 'claude-opus-4-20250514',
-        workingDir: '/custom/path'
-      });
-      
-      expect(client).toBeDefined();
-      expect(client.messages.create).toBeDefined();
-    });
-    
+        workingDir: '/custom/path',
+      })
+
+      expect(client).toBeDefined()
+      expect(client.messages.create).toBeDefined()
+    })
+
     test('accepts claude agent configuration', () => {
       const client = new AgentClient({
         agent: 'claude',
-        model: 'claude-sonnet-4-20250514'
-      });
-      
-      expect(client).toBeDefined();
-      expect(client.messages.create).toBeDefined();
-    });
-    
+        model: 'claude-sonnet-4-20250514',
+      })
+
+      expect(client).toBeDefined()
+      expect(client.messages.create).toBeDefined()
+    })
+
     test('accepts optional model in config', () => {
       // Model can be omitted if it will be provided per-request
       const client = new AgentClient({
-        agent: 'opencode'
-      });
-      
-      expect(client).toBeDefined();
-    });
-  });
-});
+        agent: 'opencode',
+      })
+
+      expect(client).toBeDefined()
+    })
+  })
+})

package/src/agent-client.test.ts

@@ -1,43 +1,43 @@
-import { describe, test, expect } from 'bun:test';
-import { AgentClient } from './agent-client';
+import { describe, test, expect } from 'bun:test'
+import { AgentClient } from './agent-client'
 
 describe('AgentClient', () => {
   describe('constructor', () => {
     test('creates client with minimal config', () => {
       const client = new AgentClient({
         agent: 'opencode',
-        model: 'claude-sonnet-4-20250514'
-      });
-      
-      expect(client).toBeDefined();
-      expect(client.messages).toBeDefined();
-      expect(typeof client.messages.create).toBe('function');
-    });
-    
+        model: 'claude-sonnet-4-20250514',
+      })
+
+      expect(client).toBeDefined()
+      expect(client.messages).toBeDefined()
+      expect(typeof client.messages.create).toBe('function')
+    })
+
     test('creates client with full config', () => {
       const client = new AgentClient({
         agent: 'claude',
         model: 'claude-opus-4-20250514',
-        workingDir: '/custom/path'
-      });
-      
-      expect(client).toBeDefined();
-      expect(client.messages).toBeDefined();
-    });
-  });
-  
+        workingDir: '/custom/path',
+      })
+
+      expect(client).toBeDefined()
+      expect(client.messages).toBeDefined()
+    })
+  })
+
   describe('messages API', () => {
     test('provides messages.create method', () => {
       const client = new AgentClient({
         agent: 'opencode',
-        model: 'claude-sonnet-4-20250514'
-      });
-      
-      expect(client.messages.create).toBeDefined();
-      expect(typeof client.messages.create).toBe('function');
-    });
-  });
-  
+        model: 'claude-sonnet-4-20250514',
+      })
+
+      expect(client.messages.create).toBeDefined()
+      expect(typeof client.messages.create).toBe('function')
+    })
+  })
+
   // Note: Integration tests with actual agent spawning would test:
   // - Prompt construction with system messages
   // - Model parameter passing to spawnAgent
@@ -45,4 +45,4 @@ describe('AgentClient', () => {
   // - Error handling for non-zero exit codes
   // - Retry logic with retryWithBackoff
   // These are covered in integration tests that mock child_process
-});
+})

package/src/agent-client.ts

@@ -3,26 +3,32 @@
  * Mirrors Anthropic SDK API but routes through agent subprocess spawning
  */
 
-import { spawnAgent } from './agent';
-import { retryWithBackoff, parseAgentError, ErrorMessages, exitWithError, isNetworkError } from './errors';
-import type { AgentType } from './config';
-import { logVerbose, logVerboseError } from './logger';
+import { spawnAgent } from './agent'
+import {
+  retryWithBackoff,
+  parseAgentError,
+  ErrorMessages,
+  exitWithError,
+  isNetworkError,
+} from './errors'
+import type { AgentType } from './config'
+import { logVerbose, logVerboseError } from './logger'
 
 export interface AgentClientConfig {
-  agent: AgentType;
-  model?: string;
-  workingDir?: string;
+  agent: AgentType
+  model?: string
+  workingDir?: string
 }
 
 export interface AgentMessageRequest {
-  model?: string;
-  max_tokens?: number;
-  messages: Array<{ role: 'user' | 'assistant'; content: string }>;
-  system?: string;
+  model?: string
+  max_tokens?: number
+  messages: Array<{ role: 'user' | 'assistant'; content: string }>
+  system?: string
 }
 
 export interface AgentMessageResponse {
-  content: Array<{ type: 'text'; text: string }>;
+  content: Array<{ type: 'text'; text: string }>
 }
 
 /**
@@ -30,12 +36,12 @@ export interface AgentMessageResponse {
  * Routes message creation through agent subprocess calls
  */
 export class AgentClient {
-  private config: AgentClientConfig;
-  
+  private config: AgentClientConfig
+
   constructor(config: AgentClientConfig) {
-    this.config = config;
+    this.config = config
   }
-  
+
   /**
    * Messages API with create method
    * Mirrors Anthropic client.messages.create() interface
@@ -44,19 +50,23 @@ export class AgentClient {
     return {
       create: async (request: AgentMessageRequest): Promise<AgentMessageResponse> => {
         // Use model from request, fall back to client config
-        const model = request.model || this.config.model;
-        
+        const model = request.model || this.config.model
+
         // Log agent request initiation
-        logVerbose(`[AgentClient] Initiating request to ${this.config.agent}${model ? ` with model ${model}` : ''}`);
-        
+        logVerbose(
+          `[AgentClient] Initiating request to ${this.config.agent}${model ? ` with model ${model}` : ''}`
+        )
+
         // Construct prompt from request
-        const prompt = constructPromptFromRequest(request);
-        
+        const prompt = constructPromptFromRequest(request)
+
         // Log request details
-        const messageCount = request.messages.length;
-        const hasSystem = !!request.system;
-        logVerbose(`[AgentClient] Request: ${messageCount} message(s)${hasSystem ? ' + system prompt' : ''}`);
-        
+        const messageCount = request.messages.length
+        const hasSystem = !!request.system
+        logVerbose(
+          `[AgentClient] Request: ${messageCount} message(s)${hasSystem ? ' + system prompt' : ''}`
+        )
+
         // Execute with retry logic for network errors only
         try {
           const result = await retryWithBackoff(async () => {
@@ -66,63 +76,83 @@ export class AgentClient {
               workingDir: this.config.workingDir || process.cwd(),
               model,
               silent: true,
-              timeout: 120000 // 2 minute timeout for PRD questions
-            });
-            
+              timeout: 120000, // 2 minute timeout for PRD questions
+            })
+
             // Only retry network errors, throw immediately for other failures
             if (spawnResult.exitCode !== 0) {
               // Parse error type from stderr
-              const errorInfo = parseAgentError(spawnResult.stderr, spawnResult.exitCode);
-              logVerboseError(`[AgentClient] Agent exited with code ${spawnResult.exitCode}, error type: ${errorInfo.type}`);
-              
+              const errorInfo = parseAgentError(spawnResult.stderr, spawnResult.exitCode)
+              logVerboseError(
+                `[AgentClient] Agent exited with code ${spawnResult.exitCode}, error type: ${errorInfo.type}`
+              )
+
               // Handle specific error types with user-friendly messages
               if (errorInfo.type === 'model_unavailable') {
-                const { message, details } = ErrorMessages.MODEL_UNAVAILABLE(model || 'unknown', this.config.agent);
-                exitWithError(message, details);
+                const { message, details } = ErrorMessages.MODEL_UNAVAILABLE(
+                  model || 'unknown',
+                  this.config.agent
+                )
+                exitWithError(message, details)
               } else if (errorInfo.type === 'rate_limit') {
-                const { message, details } = ErrorMessages.RATE_LIMIT_ERROR(this.config.agent, errorInfo.retryAfter);
-                exitWithError(message, details);
+                const { message, details } = ErrorMessages.RATE_LIMIT_ERROR(
+                  this.config.agent,
+                  errorInfo.retryAfter
+                )
+                exitWithError(message, details)
               } else if (errorInfo.type === 'spawn_failed') {
-                const { message, details } = ErrorMessages.AGENT_SPAWN_FAILED(this.config.agent, spawnResult.stderr);
-                exitWithError(message, details);
+                const { message, details } = ErrorMessages.AGENT_SPAWN_FAILED(
+                  this.config.agent,
+                  spawnResult.stderr
+                )
+                exitWithError(message, details)
               } else if (errorInfo.type === 'timeout') {
-                const timeoutMs = 120000; // Default timeout
-                const { message, details } = ErrorMessages.AGENT_TIMEOUT(this.config.agent, timeoutMs);
-                exitWithError(message, details);
+                const timeoutMs = 120000 // Default timeout
+                const { message, details } = ErrorMessages.AGENT_TIMEOUT(
+                  this.config.agent,
+                  timeoutMs
+                )
+                exitWithError(message, details)
               }
-              
+
               // For network errors, allow retry
               if (errorInfo.retryable) {
-                logVerbose(`[AgentClient] Network error detected, will retry`);
-                throw new Error(`Agent exited with code ${spawnResult.exitCode}: ${spawnResult.stderr}`);
+                logVerbose(`[AgentClient] Network error detected, will retry`)
+                throw new Error(
+                  `Agent exited with code ${spawnResult.exitCode}: ${spawnResult.stderr}`
+                )
               }
-              
+
               // For other unknown errors, provide generic agent error message
-              const { message, details } = ErrorMessages.AGENT_ERROR(this.config.agent, spawnResult.exitCode, spawnResult.stderr);
-              exitWithError(message, details);
+              const { message, details } = ErrorMessages.AGENT_ERROR(
+                this.config.agent,
+                spawnResult.exitCode,
+                spawnResult.stderr
+              )
+              exitWithError(message, details)
             }
-            
-            logVerbose(`[AgentClient] Request completed successfully`);
-            return spawnResult;
-          });
-          
+
+            logVerbose(`[AgentClient] Request completed successfully`)
+            return spawnResult
+          })
+
           // Log response details
-          const responseLength = result.stdout.trim().length;
-          logVerbose(`[AgentClient] Response: ${responseLength} characters`);
-          
+          const responseLength = result.stdout.trim().length
+          logVerbose(`[AgentClient] Response: ${responseLength} characters`)
+
           // Parse response into Anthropic-compatible format
-          return parseAgentResponse(result.stdout);
+          return parseAgentResponse(result.stdout)
         } catch (error) {
           // Network errors that exhausted retries
           if (error instanceof Error && error.message.includes('Agent exited with code')) {
-            logVerboseError(`[AgentClient] All retry attempts exhausted`);
-            const { message, details } = ErrorMessages.NETWORK_ERROR_FINAL(error);
-            exitWithError(message, details);
+            logVerboseError(`[AgentClient] All retry attempts exhausted`)
+            const { message, details } = ErrorMessages.NETWORK_ERROR_FINAL(error)
+            exitWithError(message, details)
           }
-          throw error;
+          throw error
         }
-      }
-    };
+      },
+    }
   }
 }
 
@@ -131,26 +161,26 @@ export class AgentClient {
  * Converts Anthropic message format to agent prompt string
  */
 function constructPromptFromRequest(request: AgentMessageRequest): string {
-  const parts: string[] = [];
-  
+  const parts: string[] = []
+
   // Add system prompt if present
   if (request.system) {
-    parts.push('# System');
-    parts.push(request.system);
-    parts.push('');
+    parts.push('# System')
+    parts.push(request.system)
+    parts.push('')
   }
-  
+
   // Add conversation messages
   for (const message of request.messages) {
     if (message.role === 'user') {
-      parts.push(message.content);
+      parts.push(message.content)
     } else {
       // Handle assistant messages (for multi-turn conversations)
-      parts.push(`Previous response: ${message.content}`);
+      parts.push(`Previous response: ${message.content}`)
     }
   }
-  
-  return parts.join('\n');
+
+  return parts.join('\n')
 }
 
 /**
@@ -158,9 +188,11 @@ function constructPromptFromRequest(request: AgentMessageRequest): string {
  */
 function parseAgentResponse(stdout: string): AgentMessageResponse {
   return {
-    content: [{
-      type: 'text',
-      text: stdout.trim()
-    }]
-  };
+    content: [
+      {
+        type: 'text',
+        text: stdout.trim(),
+      },
+    ],
+  }
 }

package/src/agent.test.ts

@@ -1,26 +1,26 @@
-import { describe, test, expect } from 'bun:test';
-import { isAgentAvailable } from './agent';
+import { describe, test, expect } from 'bun:test'
+import { isAgentAvailable } from './agent'
 
 describe('Agent utilities', () => {
   describe('isAgentAvailable', () => {
     test('should check if claude is available', async () => {
-      const available = await isAgentAvailable('claude');
-      expect(typeof available).toBe('boolean');
-    });
-    
+      const available = await isAgentAvailable('claude')
+      expect(typeof available).toBe('boolean')
+    })
+
     test('should check if opencode is available', async () => {
-      const available = await isAgentAvailable('opencode');
-      expect(typeof available).toBe('boolean');
-    });
-  });
-  
+      const available = await isAgentAvailable('opencode')
+      expect(typeof available).toBe('boolean')
+    })
+  })
+
   describe('spawnAgent', () => {
     // Note: spawnAgent tests require actual agent binaries to be installed
     // and would spawn interactive processes. Testing is done manually or via
     // integration tests with mocked child_process.
     test('should export spawnAgent function', () => {
-      const { spawnAgent } = require('./agent');
-      expect(typeof spawnAgent).toBe('function');
-    });
-  });
-});
+      const { spawnAgent } = require('./agent')
+      expect(typeof spawnAgent).toBe('function')
+    })
+  })
+})