@itz4blitz/agentful 0.3.0 → 0.5.1

package/bin/hooks/pre-feature.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// pre-feature.js
+// Validates feature readiness before implementation
+
+import fs from 'fs';
+
+/**
+ * Validate feature readiness before implementation
+ * @param {string} feature - Feature name
+ * @param {string} domain - Domain name (optional)
+ * @returns {object} - { errors, warnings, exitCode }
+ */
+export function validateFeatureReadiness(feature, domain = '') {
+  // Exit successfully if no feature specified
+  if (!feature) {
+    return { errors: 0, warnings: 0, exitCode: 0 };
+  }
+
+  let errors = 0;
+  let warnings = 0;
+
+  // Check 1: Feature file exists
+  let featureFile = '';
+  if (domain) {
+    // Hierarchical structure
+    featureFile = `.claude/product/domains/${domain}/features/${feature}.md`;
+  } else {
+    // Flat structure
+    featureFile = `.claude/product/features/${feature}.md`;
+  }
+
+  if (!fs.existsSync(featureFile)) {
+    console.error(`ERROR: Feature file not found: ${featureFile}`);
+    errors++;
+  }
+
+  // Check 2: Verify completion.json exists
+  const completionJsonPath = '.agentful/completion.json';
+  if (!fs.existsSync(completionJsonPath)) {
+    console.error('ERROR: .agentful/completion.json not found');
+    errors++;
+  }
+
+  // Check 3: Check feature dependencies
+  if (fs.existsSync(completionJsonPath)) {
+    try {
+      const completionContent = fs.readFileSync(completionJsonPath, 'utf8');
+      const completion = JSON.parse(completionContent);
+
+      // Check if feature has dependencies that are incomplete
+      if (domain) {
+        // Hierarchical: check domain-level dependencies
+        const domainStatus = completion.domains?.[domain]?.status || 'unknown';
+        if (domainStatus === 'blocked') {
+          console.error(`ERROR: Domain '${domain}' is blocked`);
+          errors++;
+        }
+      }
+
+      // Check for blocking decisions
+      const decisionsJsonPath = '.agentful/decisions.json';
+      if (fs.existsSync(decisionsJsonPath)) {
+        try {
+          const decisionsContent = fs.readFileSync(decisionsJsonPath, 'utf8');
+          const decisions = JSON.parse(decisionsContent);
+
+          const featurePath = domain ? `${domain}/${feature}` : feature;
+          const blockingDecisions = (decisions.pending || [])
+            .filter(d => (d.blocking || []).some(b => b.includes(featurePath)))
+            .map(d => d.id);
+
+          if (blockingDecisions.length > 0) {
+            console.error(`ERROR: Feature '${feature}' is blocked by decisions: ${blockingDecisions.join(', ')}`);
+            console.error('Run /agentful-decide to resolve blocking decisions');
+            errors++;
+          }
+        } catch (err) {
+          // Ignore JSON parse errors for decisions.json
+        }
+      }
+    } catch (err) {
+      // Ignore JSON parse errors for completion.json
+    }
+  }
+
+  // Check 4: Tech stack compatibility (if architecture.json exists)
+  const architectureJsonPath = '.agentful/architecture.json';
+  if (fs.existsSync(architectureJsonPath)) {
+    try {
+      const archContent = fs.readFileSync(architectureJsonPath, 'utf8');
+      const arch = JSON.parse(archContent);
+      const techStack = arch.techStack;
+
+      if (!techStack || techStack === null) {
+        console.log('WARNING: Tech stack not analyzed. Run /agentful-generate');
+        warnings++;
+      }
+    } catch (err) {
+      // Ignore JSON parse errors
+    }
+  }
+
+  // Check 5: Verify required agents exist
+  const requiredAgents = ['backend', 'frontend', 'tester', 'reviewer'];
+  for (const agent of requiredAgents) {
+    const agentPath = `.claude/agents/${agent}.md`;
+    if (!fs.existsSync(agentPath)) {
+      console.log(`WARNING: Core agent missing: ${agentPath}`);
+      warnings++;
+    }
+  }
+
+  // Exit with error if critical checks failed
+  if (errors > 0) {
+    console.log('');
+    console.log(`Pre-feature validation failed with ${errors} error(s)`);
+    console.log(`Feature: ${feature}`);
+    if (domain) console.log(`Domain: ${domain}`);
+    return { errors, warnings, exitCode: 1 };
+  }
+
+  if (warnings > 0) {
+    console.log('');
+    console.log(`Pre-feature validation passed with ${warnings} warning(s)`);
+  }
+
+  // All checks passed
+  return { errors: 0, warnings, exitCode: 0 };
+}
+
+// CLI entrypoint
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const FEATURE = process.env.AGENTFUL_FEATURE || '';
+  const DOMAIN = process.env.AGENTFUL_DOMAIN || '';
+
+  const result = validateFeatureReadiness(FEATURE, DOMAIN);
+  process.exit(result.exitCode);
+}

package/lib/VALIDATION_README.md

@@ -0,0 +1,455 @@
+# Validation Library
+
+Centralized validation library for agentful state files. This library consolidates duplicated validation logic from 8+ command files into a single, well-tested module.
+
+## Features
+
+- File existence checks
+- JSON parsing validation
+- Schema validation using AJV
+- Required field validation
+- Standardized error codes and messages
+- Helper functions for common state files
+- Batch validation support
+
+## Installation
+
+The validation library is already included in the agentful package. Import it from `lib/validation.js`:
+
+```javascript
+import {
+  validateStateFile,
+  validateState,
+  validateCompletion,
+  validateDecisions,
+  validateArchitecture,
+  validateProduct,
+  ValidationActions
+} from './lib/validation.js';
+```
+
+## Standardized Action Codes
+
+All validation functions return a standardized `action` field indicating what went wrong:
+
+- **`missing`**: File does not exist
+- **`corrupted`**: File exists but is not valid JSON
+- **`invalid`**: JSON is valid but doesn't match the schema
+- **`incomplete`**: Schema is valid but required fields are missing
+
+## Basic Usage
+
+### Validate any state file
+
+```javascript
+import { validateStateFile } from './lib/validation.js';
+
+const result = validateStateFile(
+  '.agentful/state.json',
+  'state',
+  ['custom_field'] // optional additional required fields
+);
+
+if (!result.valid) {
+  console.error(`Validation failed: ${result.action}`);
+  console.error(`Error: ${result.error}`);
+
+  // Handle different error types
+  switch (result.action) {
+    case 'missing':
+      // Create the file
+      break;
+    case 'corrupted':
+      // Backup and reset
+      break;
+    case 'invalid':
+      // Show schema errors
+      console.error(result.errors);
+      break;
+    case 'incomplete':
+      // Add missing field
+      console.error(`Missing field: ${result.missing_field}`);
+      break;
+  }
+} else {
+  // Use the validated content
+  const data = result.content;
+  console.log('Valid state:', data);
+}
+```
+
+### Helper Functions
+
+Use dedicated helper functions for common state files:
+
+```javascript
+import {
+  validateState,
+  validateCompletion,
+  validateDecisions
+} from './lib/validation.js';
+
+// Validate state.json (default path: .agentful/state.json)
+const stateResult = validateState();
+
+// Validate completion.json with custom path
+const completionResult = validateCompletion('.agentful/completion.json');
+
+// Validate decisions.json with additional required fields
+const decisionsResult = validateDecisions(
+  '.agentful/decisions.json',
+  ['custom_metadata']
+);
+```
+
+### Batch Validation
+
+Validate multiple files at once:
+
+```javascript
+import { validateBatch } from './lib/validation.js';
+
+const results = validateBatch([
+  { filePath: '.agentful/state.json', schemaName: 'state' },
+  { filePath: '.agentful/completion.json', schemaName: 'completion' },
+  { filePath: '.agentful/decisions.json', schemaName: 'decisions', requiredFields: ['pending'] }
+]);
+
+// Check all results
+for (const [filePath, result] of Object.entries(results)) {
+  if (!result.valid) {
+    console.error(`${filePath}: ${result.action}`);
+  }
+}
+```
+
+### Error Messages
+
+Get human-readable error messages:
+
+```javascript
+import { getErrorMessage, getSuggestedAction } from './lib/validation.js';
+
+const result = validateState();
+
+if (!result.valid) {
+  console.error(getErrorMessage(result));
+  console.log('Suggested action:', getSuggestedAction(result));
+}
+```
+
+## Available Schemas
+
+The library includes schemas for the following state files:
+
+### 1. `state` - state.json
+
+Tracks initialization and available agents/skills.
+
+**Required fields:**
+- `initialized` (string, ISO 8601 date-time)
+- `version` (string, semantic version)
+- `agents` (array of strings)
+- `skills` (array of strings)
+
+**Example:**
+```json
+{
+  "initialized": "2026-01-21T10:00:00.000Z",
+  "version": "1.0.0",
+  "agents": ["frontend", "backend"],
+  "skills": ["react", "nodejs"]
+}
+```
+
+### 2. `completion` - completion.json
+
+Tracks completion progress for agents and skills.
+
+**Required fields:**
+- `agents` (object with completion data)
+- `skills` (object with completion data)
+- `lastUpdated` (string, ISO 8601 date-time)
+
+**Example:**
+```json
+{
+  "agents": {
+    "frontend": { "completed": true, "progress": 100 }
+  },
+  "skills": {
+    "react": { "completed": false, "progress": 75 }
+  },
+  "lastUpdated": "2026-01-21T10:00:00.000Z"
+}
+```
+
+### 3. `decisions` - decisions.json
+
+Tracks pending decisions and their resolutions.
+
+**Required fields:**
+- `decisions` (array of decision objects)
+- `lastUpdated` (string, ISO 8601 date-time)
+
+**Decision object required fields:**
+- `id` (string)
+- `question` (string)
+- `status` (enum: "pending", "answered", "cancelled")
+
+**Example:**
+```json
+{
+  "decisions": [
+    {
+      "id": "decision-1",
+      "question": "Which database should we use?",
+      "status": "pending",
+      "created": "2026-01-21T10:00:00.000Z"
+    }
+  ],
+  "lastUpdated": "2026-01-21T10:00:00.000Z"
+}
+```
+
+### 4. `architecture` - architecture.json
+
+Tracks project architecture decisions.
+
+**Required fields:**
+- `project_type` (string)
+- `technologies` (object)
+- `patterns` (array of strings)
+- `lastUpdated` (string, ISO 8601 date-time)
+
+**Example:**
+```json
+{
+  "project_type": "web-app",
+  "technologies": {
+    "frontend": "React",
+    "backend": "Node.js"
+  },
+  "patterns": ["MVC", "REST"],
+  "lastUpdated": "2026-01-21T10:00:00.000Z"
+}
+```
+
+### 5. `product` - product.json
+
+Tracks product specification and features.
+
+**Required fields:**
+- `name` (string)
+- `description` (string)
+- `features` (array of feature objects)
+- `lastUpdated` (string, ISO 8601 date-time)
+
+**Feature object required fields:**
+- `id` (string)
+- `name` (string)
+
+**Example:**
+```json
+{
+  "name": "Task Manager",
+  "description": "A simple task management app",
+  "features": [
+    {
+      "id": "feature-1",
+      "name": "User Authentication",
+      "priority": "high"
+    }
+  ],
+  "lastUpdated": "2026-01-21T10:00:00.000Z"
+}
+```
+
+## Replacing Duplicated Code
+
+The validation library replaces this duplicated pattern found in 8+ command files:
+
+```javascript
+// OLD - Duplicated in every command
+function validate_state_file(file_path, required_fields) {
+  if (!exists(file_path)) {
+    return { valid: false, error: `File not found: ${file_path}`, action: "initialize" };
+  }
+
+  let content;
+  try {
+    content = JSON.parse(Read(file_path));
+  } catch (e) {
+    return { valid: false, error: `Invalid JSON in ${file_path}`, action: "backup_and_reset" };
+  }
+
+  for (const field of required_fields) {
+    if (!(field in content)) {
+      return { valid: false, error: `Missing field '${field}'`, action: "add_field", missing_field: field };
+    }
+  }
+
+  return { valid: true, content };
+}
+
+// NEW - Single centralized function
+import { validateStateFile } from './lib/validation.js';
+
+const result = validateStateFile(filePath, schemaName, requiredFields);
+```
+
+## Benefits
+
+1. **Consistency**: All commands use the same validation logic
+2. **Maintainability**: Update validation logic in one place
+3. **Testability**: Comprehensive test coverage (35+ tests)
+4. **Type Safety**: AJV schema validation catches type errors
+5. **Standardization**: Consistent error codes and messages
+6. **Documentation**: Clear API with JSDoc comments
+
+## Testing
+
+Run the validation library tests:
+
+```bash
+npm test -- test/unit/validation.test.js
+```
+
+The test suite includes:
+- Missing file validation
+- Corrupted JSON handling
+- Schema validation
+- Required field checks
+- Batch validation
+- Error message generation
+- Edge cases
+
+## Advanced Usage
+
+### Custom Schemas
+
+You can access the raw AJV instance and schemas:
+
+```javascript
+import { ajv, schemas } from './lib/validation.js';
+
+// Compile a custom schema
+const customSchema = ajv.compile({
+  type: 'object',
+  required: ['custom_field'],
+  properties: {
+    custom_field: { type: 'string' }
+  }
+});
+
+// Use it
+const valid = customSchema(data);
+if (!valid) {
+  console.error(customSchema.errors);
+}
+```
+
+### ValidationActions Constants
+
+Use constants instead of strings for action codes:
+
+```javascript
+import { ValidationActions } from './lib/validation.js';
+
+if (result.action === ValidationActions.MISSING) {
+  // Handle missing file
+} else if (result.action === ValidationActions.CORRUPTED) {
+  // Handle corrupted file
+}
+```
+
+## Migration Guide
+
+To migrate existing command validation code to use this library:
+
+1. **Import the validation library**:
+   ```javascript
+   import { validateStateFile } from './lib/validation.js';
+   ```
+
+2. **Replace inline validation with library call**:
+   ```javascript
+   // Before
+   const validation = validate_state_file(".agentful/state.json", ["current_task"]);
+
+   // After
+   const validation = validateStateFile(".agentful/state.json", "state", ["current_task"]);
+   ```
+
+3. **Update action names**:
+   - `"not_found"` → `"missing"`
+   - `"initialize"` → `"missing"`
+   - `"backup_and_reset"` → `"corrupted"`
+   - `"add_field"` → `"incomplete"`
+   - Schema errors → `"invalid"`
+
+4. **Use helper functions for common files**:
+   ```javascript
+   // Before
+   const validation = validate_state_file(".agentful/state.json", []);
+
+   // After
+   const validation = validateState();
+   ```
+
+## API Reference
+
+### `validateStateFile(filePath, schemaName, requiredFields)`
+
+Universal validation function for any state file.
+
+**Parameters:**
+- `filePath` (string): Absolute path to the file
+- `schemaName` (string): Schema to use ('state', 'completion', 'decisions', 'architecture', 'product')
+- `requiredFields` (string[], optional): Additional required fields beyond schema
+
+**Returns:**
+- `{ valid: true, content: object }` on success
+- `{ valid: false, action: string, error: string, ... }` on failure
+
+### `validateState(filePath?, additionalFields?)`
+
+Validate state.json file. Default path: `.agentful/state.json`
+
+### `validateCompletion(filePath?, additionalFields?)`
+
+Validate completion.json file. Default path: `.agentful/completion.json`
+
+### `validateDecisions(filePath?, additionalFields?)`
+
+Validate decisions.json file. Default path: `.agentful/decisions.json`
+
+### `validateArchitecture(filePath?, additionalFields?)`
+
+Validate architecture.json file. Default path: `.agentful/architecture.json`
+
+### `validateProduct(filePath?, additionalFields?)`
+
+Validate product.json file. Default path: `.agentful/product.json`
+
+### `validateBatch(files)`
+
+Validate multiple files at once.
+
+**Parameters:**
+- `files` (array): Array of `{ filePath, schemaName, requiredFields? }`
+
+**Returns:**
+- Object mapping filePath to validation result
+
+### `getErrorMessage(validationResult)`
+
+Get human-readable error message for a validation result.
+
+### `getSuggestedAction(validationResult)`
+
+Get suggested action to fix a validation error.
+
+## License
+
+MIT