@forgehive/forge-cli 0.3.6 → 0.3.8

package/forge.json

@@ -5,6 +5,7 @@
   "paths": {
     "logs": "logs/",
     "fixtures": "fixtures",
+    "fingerprints": "fingerprints/",
     "tasks": "src/tasks/",
     "runners": "src/runners/",
     "tests": "src/tests/"

package/logs/bundle:fingerprint.log

@@ -0,0 +1 @@
+{"input":{"filePath":"/Users/danielzavaladlvega/forgehive/forge-mono-repo/apps/sample-project/src/tasks/test/errors.ts"},"boundaries":{"getCwd":[],"loadConf":[],"readFile":[],"writeFile":[],"ensureFingerprintsFolder":[]},"metadata":{"environment":"cli"},"metrics":[],"type":"error","error":"Invalid input on: descriptorName: Required"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgehive/forge-cli",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "TypeScript CLI application",
   "license": "MIT",
   "main": "dist/index.js",
@@ -10,11 +10,11 @@
   "publishConfig": {
     "access": "public",
     "dependencies": {
-      "@forgehive/hive-sdk": "^0.1.1",
-      "@forgehive/record-tape": "^0.2.4",
-      "@forgehive/runner": "^0.2.4",
+      "@forgehive/hive-sdk": "^0.1.2",
+      "@forgehive/record-tape": "^0.2.5",
+      "@forgehive/runner": "^0.2.5",
       "@forgehive/schema": "^0.1.4",
-      "@forgehive/task": "^0.2.4",
+      "@forgehive/task": "^0.2.5",
       "esbuild": "^0.25.0",
       "handlebars": "^4.7.8",
       "minimist": "^1.2.8"
@@ -27,11 +27,11 @@
     "esbuild": "^0.25.0",
     "handlebars": "^4.7.8",
     "minimist": "^1.2.8",
-    "@forgehive/record-tape": "0.2.4",
+    "@forgehive/hive-sdk": "0.1.2",
+    "@forgehive/record-tape": "0.2.5",
     "@forgehive/schema": "0.1.4",
-    "@forgehive/task": "0.2.4",
-    "@forgehive/hive-sdk": "0.1.1",
-    "@forgehive/runner": "0.2.4"
+    "@forgehive/runner": "0.2.5",
+    "@forgehive/task": "0.2.5"
   },
   "devDependencies": {
     "@types/archiver": "^6.0.3",

package/specs/fingerprint.md

@@ -64,25 +64,65 @@ interface TaskFingerprint {
     type: string
     properties: Record<string, any>
   }
-  outputType: string
-  boundaries: Record<string, {
-    inputTypes: string[]
-    outputType: string
-    signature: string
-  }>
-  functionSource: string
+  outputType: {
+    type: string
+    properties?: Record<string, any>
+    elementType?: OutputType
+  }
+  boundaries: BoundaryFingerprint[]
   hash: string
-  metadata: {
-    extractedAt: string
-    version: string
+}
+
+interface BoundaryFingerprint {
+  name: string
+  input: SchemaProperty[]
+  output: OutputType
+  errors: FingerprintError[]
+}
+
+interface OutputType {
+  type: string
+  properties?: Record<string, SchemaProperty>
+  elementType?: OutputType
+}
+
+interface FingerprintError {
+  type: 'parsing' | 'analysis' | 'boundary' | 'schema'
+  message: string
+  location?: {
+    file: string
+    line?: number
+    column?: number
   }
 }
+
+interface SchemaProperty {
+  name?: string
+  type: string
+  optional?: boolean
+  default?: string
+  properties?: Record<string, SchemaProperty>
+}
 ```
 
-#### FingerprintResult
+#### TaskFingerprintOutput
 ```typescript
+interface TaskFingerprintOutput {
+  description?: string
+  inputSchema: InputSchema
+  outputType: OutputType
+  boundaries: BoundaryFingerprint[]
+  errors: FingerprintError[]
+  analysisMetadata: {
+    timestamp: string
+    filePath: string
+    success: boolean
+    analysisVersion: string
+  }
+}
+
 interface FingerprintResult {
-  tasks: TaskFingerprint[]
+  tasks: TaskFingerprintOutput[]
   buildInfo: {
     entryPoint: string
     outputFile: string
@@ -137,16 +177,57 @@ export const taskName = createTask(schema, boundaries, fn)
 - Generate JSON Schema-compatible output
 
 #### Boundary Analysis
-- Extract function signatures from boundary object
-- Parse parameter types and return types
+- Extract function signatures from boundary object as detailed objects
+- Parse parameter types into structured SchemaProperty arrays
+- Parse return types with support for complex object structures  
 - Handle async functions and Promise return types
-- Truncate function source for readability (200 chars max)
+- Collect runtime errors from throw statements in boundary functions
+- Each boundary becomes a BoundaryFingerprint with name, input, output, and errors
 
 #### Return Type Analysis
 - Extract TypeScript return type annotations
 - Parse Promise wrapper types
 - Infer types from return statements when annotations missing
 - Handle complex object return types
+- Support for array element type detection with `elementType` property
+
+#### Array Element Type Detection
+The system now provides enhanced array type analysis:
+
+**TypeScript Annotation Parsing**: 
+```typescript
+// Boundary function with array return type
+getPortfolio: async (userUUID: string): Promise<{ symbol: string, quantity: number, price: number }[]>
+```
+
+**Generated Fingerprint**:
+```json
+{
+  "type": "array",
+  "elementType": {
+    "type": "object", 
+    "properties": {
+      "symbol": { "type": "string" },
+      "quantity": { "type": "number" },
+      "price": { "type": "number" }
+    }
+  }
+}
+```
+
+**Supported Array Patterns**:
+- `T[]` format: `{ symbol: string, quantity: number }[]`
+- `Array<T>` format: `Array<{ symbol: string, quantity: number }>`
+- Complex nested objects within arrays
+- Propagation from boundary types to task output types
+
+#### Error Collection
+- **Boundary Errors**: Detect `throw` statements in boundary functions
+- **Main Function Errors**: Detect `throw` statements in the main task function
+- **Parsing Errors**: Capture TypeScript AST parsing failures
+- **Schema Errors**: Capture schema analysis failures
+- **Location Tracking**: Include precise line and column information for each error
+- **Error Types**: Categorize errors as 'parsing', 'analysis', 'boundary', or 'schema'
 
 ### 4. Hash Generation Algorithm
 
@@ -193,43 +274,137 @@ const boundaries = {
 
 ```json
 {
-  "tasks": [
-    {
-      "name": "getPrice",
-      "description": "Fetches stock price for a given ticker",
-      "location": {
-        "file": "src/tasks/price.ts",
-        "line": 15,
-        "column": 23
-      },
-      "inputSchema": {
-        "type": "object",
-        "properties": {
-          "ticker": { "type": "string" }
+  "taskFingerprint": {
+    "description": "Test task with intentional runtime errors for error collection testing",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "userId": { "type": "string" }
+      }
+    },
+    "outputType": {
+      "type": "object",
+      "properties": {
+        "user": { "type": "object" },
+        "profile": { "type": "string" },
+        "lastLogin": { "type": "string" },
+        "processed": { "type": "boolean" },
+        "portfolio": {
+          "type": "array",
+          "elementType": {
+            "type": "object",
+            "properties": {
+              "symbol": { "type": "string" },
+              "quantity": { "type": "number" },
+              "price": { "type": "number" }
+            }
+          }
         }
+      }
+    },
+    "boundaries": [
+      {
+        "name": "getUserById",
+        "input": [
+          {
+            "type": "object",
+            "properties": {
+              "userId": { "type": "string" }
+            },
+            "name": "input"
+          }
+        ],
+        "output": { "type": "User | null" },
+        "errors": []
       },
-      "outputType": "Promise<{ ticker: string, price: number }>",
-      "boundaries": {
-        "fetchStockPrice": {
-          "inputTypes": ["string"],
-          "outputType": "Promise<{ price: number }>",
-          "signature": "async (ticker: string): Promise<{ price: number }> => {...}"
-        }
+      {
+        "name": "getPortfolio",
+        "input": [
+          {
+            "type": "string",
+            "name": "userUUID"
+          }
+        ],
+        "output": {
+          "type": "array",
+          "elementType": {
+            "type": "object",
+            "properties": {
+              "symbol": { "type": "string" },
+              "quantity": { "type": "number" },
+              "price": { "type": "number" }
+            }
+          }
+        },
+        "errors": [
+          {
+            "type": "boundary",
+            "message": "Boundary function throws: User not found",
+            "location": {
+              "file": "/path/to/tasks/stock/getPortfolio.ts",
+              "line": 19,
+              "column": 7
+            }
+          }
+        ]
       },
-      "functionSource": "async function ({ ticker }, { fetchStockPrice }) { ... }",
-      "hash": "abc123def",
-      "metadata": {
-        "extractedAt": "2025-01-01T12:00:00.000Z",
-        "version": "1.0.0"
+      {
+        "name": "fetchUserProfile", 
+        "input": [
+          {
+            "type": "object",
+            "properties": {
+              "userId": { "type": "string" }
+            },
+            "name": "input"
+          }
+        ],
+        "output": {
+          "type": "object",
+          "properties": {
+            "profile": { "type": "string" },
+            "lastLogin": { "type": "string" }
+          }
+        },
+        "errors": [
+          {
+            "type": "boundary",
+            "message": "Boundary function throws: API temporarily unavailable",
+            "location": {
+              "file": "/path/to/tasks/test/errors.ts",
+              "line": 40,
+              "column": 7
+            }
+          },
+          {
+            "type": "boundary", 
+            "message": "Boundary function throws: External API authentication failed",
+            "location": {
+              "file": "/path/to/tasks/test/errors.ts",
+              "line": 44,
+              "column": 7
+            }
+          }
+        ]
       }
+    ],
+    "errors": [
+      {
+        "type": "analysis",
+        "message": "Main task function throws: User with ID ${userId} not found",
+        "location": {
+          "file": "/path/to/tasks/test/errors.ts",
+          "line": 65,
+          "column": 7
+        }
+      }
+    ],
+    "analysisMetadata": {
+      "timestamp": "2025-01-18T12:40:18.033Z",
+      "filePath": "/path/to/tasks/test/errors.ts",
+      "success": true,
+      "analysisVersion": "1.0.0"
     }
-  ],
-  "buildInfo": {
-    "entryPoint": "src/index.ts",
-    "outputFile": "dist/bundle.js",
-    "fingerprintsFile": "dist/bundle.fingerprints.json",
-    "totalTasks": 5,
-    "buildTimestamp": "2025-01-01T12:00:00.000Z"
   }
 }
 ```
@@ -291,6 +466,42 @@ console.log(`Generated ${result.taskFingerprints?.totalTasks} task fingerprints`
 
 ## Error Handling
 
+### Runtime Error Collection
+The fingerprinting system now collects runtime errors from task code:
+
+#### Error Types Collected
+1. **Boundary Errors** (`type: "boundary"`): Thrown errors in boundary functions
+   - Detects `throw new Error(...)` statements in boundary function bodies
+   - Captures error messages from string literals and template expressions
+   - Includes precise line and column location information
+
+2. **Main Function Errors** (`type: "analysis"`): Thrown errors in main task functions  
+   - Detects `throw new Error(...)` statements in the main task function
+   - Supports template literal error messages like `\`User with ID ${userId} not found\``
+   - Provides exact source code location
+
+3. **Parsing Errors** (`type: "parsing"`): TypeScript AST parsing failures
+   - Occurs when TypeScript compiler cannot parse source code
+   - Includes error stack traces and detailed error information
+
+4. **Schema Errors** (`type: "schema"`): Schema analysis failures
+   - Captures errors during Schema object analysis
+   - Reports issues with malformed schema definitions
+
+#### Error Location Tracking
+All errors include detailed location information:
+```typescript
+{
+  type: "analysis",
+  message: "Main task function throws: User with ID ${userId} not found", 
+  location: {
+    file: "/path/to/task/file.ts",
+    line: 65,      // 1-based line number
+    column: 7      // 1-based column number
+  }
+}
+```
+
 ### Plugin Error Scenarios
 1. **TypeScript Parsing Errors**: Log warning, continue processing other files
 2. **Invalid createTask Calls**: Skip malformed calls, log warnings
@@ -301,6 +512,7 @@ console.log(`Generated ${result.taskFingerprints?.totalTasks} task fingerprints`
 - If TypeScript analysis fails, include raw source code snippets
 - Provide partial fingerprints when complete type information unavailable
 - Continue build process even if fingerprint generation fails
+- Error collection continues even when main analysis partially fails
 
 ## Performance Considerations
 
@@ -363,18 +575,70 @@ export const testTask = createTask(
 
 ## Implementation Checklist
 
-- [ ] Implement `taskFingerprintPlugin` esbuild plugin
-- [ ] Create TypeScript AST analysis functions
-- [ ] Implement schema extraction logic
-- [ ] Implement boundary analysis logic
-- [ ] Implement return type extraction
-- [ ] Create hash generation function
-- [ ] Implement enhanced bundle task
-- [ ] Add error handling and logging
-- [ ] Write comprehensive tests
-- [ ] Create CLI integration
-- [ ] Generate documentation
-- [ ] Performance optimization
-- [ ] Add configuration validation
+### Core Fingerprinting System
+- [x] Implement `taskFingerprintPlugin` esbuild plugin
+- [x] Create TypeScript AST analysis functions
+- [x] Implement schema extraction logic
+- [x] Implement boundary analysis logic
+- [x] Implement return type extraction
+- [x] Create hash generation function
+- [x] Implement enhanced bundle task
+- [x] Create CLI integration
+
+### Enhanced Boundary Analysis
+- [x] Convert boundaries from string arrays to detailed objects
+- [x] Implement detailed boundary input/output type analysis
+- [x] Add support for complex object structure detection
+- [x] Enhance property access expression analysis (e.g., result1.result)
+- [x] Add schema optional property detection with chained methods
+- [x] Implement array element type detection with `elementType` support
+- [x] Add support for complex array-of-objects type patterns
+- [x] Enable type propagation from boundary arrays to task output arrays
+
+### Runtime Error Collection System
+- [x] Implement boundary error detection (throw statements in boundary functions)
+- [x] Implement main task function error detection (throw statements in main function)
+- [x] Add support for template literal error messages
+- [x] Implement precise error location tracking (line and column numbers)
+- [x] Create structured error categorization (parsing, analysis, boundary, schema)
+- [x] Fix error duplication issues with deduplication logic
+- [x] Clean up error format (remove details object, consistent location format)
+
+### Error Handling and Metadata
+- [x] Add comprehensive error handling and logging
+- [x] Implement TaskFingerprintOutput interface with errors and metadata
+- [x] Add analysisMetadata with timestamp, success status, and version
+- [x] Implement graceful degradation for partial analysis failures
+
+### Storage and Configuration
+- [x] Update fingerprint storage to use project fingerprints folder
+- [x] Add fingerprints path configuration support
+- [x] Implement ensureFingerprintsFolder boundary
+- [x] Update file naming conventions for consistency
+
+### Documentation and Specification
+- [x] Generate comprehensive specification documentation
+- [x] Update core interfaces to reflect enhanced structure
+- [x] Document error collection features and examples
+- [x] Add implementation plan documentation
+
+### Testing and Integration
+- [ ] Write comprehensive unit tests for error collection
+- [ ] Write integration tests for enhanced fingerprinting workflow
+- [ ] Test error scenarios and edge cases
+- [ ] Performance testing and optimization
+- [ ] Add configuration validation tests
+
+### Publish Integration
+- [x] Integrate fingerprint generation into publish workflow
+- [x] Add fingerprint data to publish payload
+- [x] Implement error handling for fingerprint failures in publish
+- [x] Add fingerprint status reporting in publish results
+
+### Future Enhancements (Planned)
+- [ ] Implement watch mode for incremental updates
+- [ ] Create fingerprint comparison and diff tools
+- [ ] Add IDE integration and language service plugin
+- [ ] Add fingerprint validation and consistency checks
 
 This specification provides a complete blueprint for implementing a sophisticated task fingerprinting system that operates at build time and provides comprehensive type introspection capabilities for TypeScript tasks.

package/src/runner.ts

@@ -133,9 +133,15 @@ runner.setHandler(async (data: ParsedArgs): Promise<unknown> => {
         cache
       })
     } else if (taskName === 'task:run') {
+      const { input, ...restArgs } = args as { input?: string }
+
+      // If --input is provided, parse it as JSON and use that
+      // Otherwise, use the regular arguments spread from minimist
+      const taskArgs = input ? JSON.parse(input) : restArgs
+
       result = await task.run({
         descriptorName: action,
-        args
+        args: taskArgs
       })
     } else if (taskName === 'fixture:download') {
       const { uuid } = args as { uuid: string }
@@ -160,6 +166,10 @@ runner.setHandler(async (data: ParsedArgs): Promise<unknown> => {
       })
     } else {
       result = await task.run(args)
+
+      if (taskName === 'info') {
+        silent = true
+      }
     }
 
     if (taskName === 'task:describe' || taskName === 'task:list') {

package/src/tasks/bundle/fingerprint.ts

@@ -7,7 +7,6 @@ import { Schema } from '@forgehive/schema'
 import esbuild from 'esbuild'
 import fs from 'fs/promises'
 import path from 'path'
-import os from 'os'
 
 import { load as loadConf } from '../conf/load'
 import { analyzeTaskFile, TaskFingerprintOutput } from '../../utils/taskAnalysis'
@@ -22,7 +21,9 @@ interface TaskFingerprint {
   }
   inputSchema: TaskFingerprintOutput['inputSchema']
   outputType: TaskFingerprintOutput['outputType']
-  boundaries: string[]
+  boundaries: TaskFingerprintOutput['boundaries']
+  errors: TaskFingerprintOutput['errors']
+  analysisMetadata: TaskFingerprintOutput['analysisMetadata']
   hash: string
 }
 
@@ -59,14 +60,14 @@ const boundaries = {
   writeFile: async (filePath: string, content: string): Promise<void> => {
     return fs.writeFile(filePath, content)
   },
-  ensureForgeFolder: async (): Promise<string> => {
-    const forgePath = path.join(os.homedir(), '.forge')
+  ensureFingerprintsFolder: async (cwd: string, conf: { paths?: { fingerprints?: string } }): Promise<string> => {
+    const fingerprintsPath = path.join(cwd, conf.paths?.fingerprints || 'fingerprints/')
     try {
-      await fs.access(forgePath)
+      await fs.access(fingerprintsPath)
     } catch {
-      await fs.mkdir(forgePath, { recursive: true })
+      await fs.mkdir(fingerprintsPath, { recursive: true })
     }
-    return forgePath
+    return fingerprintsPath
   }
 }
 
@@ -96,6 +97,8 @@ function taskFingerprintPlugin(): esbuild.Plugin {
               inputSchema: taskFingerprint.inputSchema,
               outputType: taskFingerprint.outputType,
               boundaries: taskFingerprint.boundaries,
+              errors: taskFingerprint.errors,
+              analysisMetadata: taskFingerprint.analysisMetadata,
               hash: 'generated-hash'
             }
             fingerprints.push(fullFingerprint)
@@ -121,7 +124,7 @@ export const fingerprint = createTask({
     loadConf,
     readFile,
     writeFile,
-    ensureForgeFolder
+    ensureFingerprintsFolder
   }) {
     // If filePath is provided, analyze that file directly and return JSON
     if (filePath) {
@@ -133,9 +136,23 @@ export const fingerprint = createTask({
         throw new Error('Could not extract fingerprint from task file: ' + filePath)
       }
 
-      return {
+      // Write fingerprint to file for consistency
+      const cwd = await getCwd()
+      const forgeJson = await loadConf({})
+      const fingerprintsPath = await ensureFingerprintsFolder(cwd, forgeJson)
+      const fingerprintFile = path.join(fingerprintsPath, `${descriptorName}.fingerprint.json`)
+
+      const analysis = {
         taskFingerprint: fingerprintOutput
       }
+
+      await writeFile(fingerprintFile, JSON.stringify(analysis, null, 2))
+      console.log(`Fingerprint saved to: ${fingerprintFile}`)
+
+      return {
+        taskFingerprint: fingerprintOutput,
+        fingerprintFile
+      }
     }
 
     // Original bundle logic when no filePath is provided
@@ -149,9 +166,9 @@ export const fingerprint = createTask({
     }
 
     const entryPoint = path.join(cwd, taskDescriptor.path)
-    const forgePath = await ensureForgeFolder()
-    const outputFile = path.join(forgePath, `${descriptorName}.js`)
-    const fingerprintsFile = path.join(forgePath, `${descriptorName}.fingerprints.json`)
+    const fingerprintsPath = await ensureFingerprintsFolder(cwd, forgeJson)
+    const outputFile = path.join(fingerprintsPath, `${descriptorName}.js`)
+    const fingerprintsFile = path.join(fingerprintsPath, `${descriptorName}.fingerprints.json`)
 
     console.log(`Generating bundle with fingerprints for task: ${descriptorName}`)
     console.log(`Entry point: ${entryPoint}`)
@@ -177,7 +194,9 @@ export const fingerprint = createTask({
       description: fp.description,
       inputSchema: fp.inputSchema,
       outputType: fp.outputType,
-      boundaries: fp.boundaries
+      boundaries: fp.boundaries,
+      errors: fp.errors, // Preserve errors from analyzeTaskFile
+      analysisMetadata: fp.analysisMetadata // Preserve metadata from analyzeTaskFile
     }))
 
     // Create fingerprint result