@itz4blitz/agentful 0.3.0 → 0.5.1

package/lib/validation.js

@@ -0,0 +1,460 @@
+import fs from 'fs';
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+
+/**
+ * Centralized Validation Library
+ *
+ * Provides unified validation functions for state files with:
+ * - File existence checks
+ * - JSON parsing validation
+ * - Schema validation using AJV
+ * - Required field validation
+ *
+ * Standardized action codes:
+ * - "missing": File does not exist
+ * - "corrupted": File exists but is not valid JSON
+ * - "invalid": JSON is valid but doesn't match schema
+ * - "incomplete": Schema is valid but required fields are missing
+ */
+
+// Initialize AJV with formats support
+const ajv = new Ajv({ allErrors: true });
+addFormats(ajv);
+
+/**
+ * JSON Schemas for state files
+ */
+export const schemas = {
+  state: {
+    type: 'object',
+    required: ['initialized', 'version', 'agents', 'skills'],
+    properties: {
+      initialized: {
+        type: 'string',
+        format: 'date-time'
+      },
+      version: {
+        type: 'string',
+        pattern: '^\\d+\\.\\d+\\.\\d+$'
+      },
+      agents: {
+        type: 'array',
+        items: {
+          type: 'string'
+        }
+      },
+      skills: {
+        type: 'array',
+        items: {
+          type: 'string'
+        }
+      }
+    },
+    additionalProperties: true
+  },
+
+  completion: {
+    type: 'object',
+    required: ['agents', 'skills', 'lastUpdated'],
+    properties: {
+      agents: {
+        type: 'object',
+        additionalProperties: {
+          type: 'object',
+          properties: {
+            completed: { type: 'boolean' },
+            progress: { type: 'number', minimum: 0, maximum: 100 }
+          }
+        }
+      },
+      skills: {
+        type: 'object',
+        additionalProperties: {
+          type: 'object',
+          properties: {
+            completed: { type: 'boolean' },
+            progress: { type: 'number', minimum: 0, maximum: 100 }
+          }
+        }
+      },
+      lastUpdated: {
+        type: 'string',
+        format: 'date-time'
+      }
+    },
+    additionalProperties: true
+  },
+
+  decisions: {
+    type: 'object',
+    required: ['decisions', 'lastUpdated'],
+    properties: {
+      decisions: {
+        type: 'array',
+        items: {
+          type: 'object',
+          required: ['id', 'question', 'status'],
+          properties: {
+            id: { type: 'string' },
+            question: { type: 'string' },
+            status: {
+              type: 'string',
+              enum: ['pending', 'answered', 'cancelled']
+            },
+            answer: { type: 'string' },
+            context: { type: 'string' },
+            created: { type: 'string', format: 'date-time' },
+            updated: { type: 'string', format: 'date-time' }
+          }
+        }
+      },
+      lastUpdated: {
+        type: 'string',
+        format: 'date-time'
+      }
+    },
+    additionalProperties: false
+  },
+
+  architecture: {
+    type: 'object',
+    required: ['version', 'analyzedAt', 'projectRoot', 'fileCount', 'confidence', 'languages', 'frameworks', 'patterns', 'conventions', 'recommendations'],
+    properties: {
+      version: { type: 'string' },
+      analyzedAt: {
+        type: 'string',
+        format: 'date-time'
+      },
+      duration: { type: 'number' },
+      projectRoot: { type: 'string' },
+      fileCount: { type: 'number', minimum: 0 },
+      isNewProject: { type: 'boolean' },
+      confidence: { type: 'number', minimum: 0, maximum: 100 },
+      languages: {
+        type: 'array',
+        items: {
+          type: 'object',
+          required: ['name', 'confidence', 'files'],
+          properties: {
+            name: { type: 'string' },
+            confidence: { type: 'number' },
+            files: { type: 'number' },
+            percentage: { type: 'number' },
+            extensions: { type: 'array', items: { type: 'string' } }
+          }
+        }
+      },
+      primaryLanguage: { type: ['string', 'null'] },
+      frameworks: {
+        type: 'array',
+        items: {
+          type: 'object',
+          required: ['name', 'confidence'],
+          properties: {
+            name: { type: 'string' },
+            version: { type: 'string' },
+            type: { type: 'string' },
+            category: { type: 'string' },
+            confidence: { type: 'number' },
+            source: { type: 'string' }
+          }
+        }
+      },
+      patterns: {
+        type: 'object',
+        properties: {
+          components: { type: 'object' },
+          api: { type: 'object' },
+          database: { type: 'object' },
+          tests: { type: 'object' },
+          auth: { type: 'object' }
+        }
+      },
+      conventions: {
+        type: 'object'
+      },
+      recommendations: {
+        type: 'array',
+        items: {
+          type: 'object',
+          required: ['type', 'priority', 'message', 'action'],
+          properties: {
+            type: { type: 'string' },
+            priority: { type: 'string' },
+            message: { type: 'string' },
+            action: { type: 'string' }
+          }
+        }
+      }
+    },
+    additionalProperties: true
+  },
+
+  product: {
+    type: 'object',
+    required: ['name', 'description', 'features', 'lastUpdated'],
+    properties: {
+      name: { type: 'string' },
+      description: { type: 'string' },
+      features: {
+        type: 'array',
+        items: {
+          type: 'object',
+          required: ['id', 'name'],
+          properties: {
+            id: { type: 'string' },
+            name: { type: 'string' },
+            description: { type: 'string' },
+            priority: {
+              type: 'string',
+              enum: ['high', 'medium', 'low']
+            }
+          }
+        }
+      },
+      lastUpdated: {
+        type: 'string',
+        format: 'date-time'
+      }
+    },
+    additionalProperties: true
+  }
+};
+
+// Compile all schemas
+const compiledSchemas = {
+  state: ajv.compile(schemas.state),
+  completion: ajv.compile(schemas.completion),
+  decisions: ajv.compile(schemas.decisions),
+  architecture: ajv.compile(schemas.architecture),
+  product: ajv.compile(schemas.product)
+};
+
+/**
+ * Unified validation function for state files
+ *
+ * @param {string} filePath - Absolute path to the file to validate
+ * @param {string} schemaName - Name of schema to use ('state', 'completion', 'decisions', 'architecture', 'product')
+ * @param {string[]} requiredFields - Additional required fields to check beyond schema
+ * @returns {Object} Validation result with standardized structure
+ *
+ * Return format for invalid:
+ * { valid: false, action: "missing" | "corrupted" | "invalid" | "incomplete", errors?: array, missing_field?: string }
+ *
+ * Return format for valid:
+ * { valid: true, content: object }
+ */
+export function validateStateFile(filePath, schemaName, requiredFields = []) {
+  // 1. Check file exists
+  if (!fs.existsSync(filePath)) {
+    return {
+      valid: false,
+      action: 'missing',
+      error: `File not found: ${filePath}`
+    };
+  }
+
+  // 2. Parse JSON
+  let content;
+  try {
+    const fileContent = fs.readFileSync(filePath, 'utf-8');
+    content = JSON.parse(fileContent);
+  } catch (error) {
+    return {
+      valid: false,
+      action: 'corrupted',
+      error: `Invalid JSON in ${filePath}: ${error.message}`
+    };
+  }
+
+  // 3. Validate against schema using AJV
+  const validator = compiledSchemas[schemaName];
+  if (!validator) {
+    throw new Error(`Unknown schema name: ${schemaName}. Valid schemas: ${Object.keys(compiledSchemas).join(', ')}`);
+  }
+
+  const schemaValid = validator(content);
+  if (!schemaValid) {
+    return {
+      valid: false,
+      action: 'invalid',
+      errors: validator.errors,
+      error: `Schema validation failed for ${filePath}`
+    };
+  }
+
+  // 4. Check additional required fields
+  for (const field of requiredFields) {
+    if (!(field in content)) {
+      return {
+        valid: false,
+        action: 'incomplete',
+        missing_field: field,
+        error: `Missing required field '${field}' in ${filePath}`
+      };
+    }
+  }
+
+  // 5. Success
+  return {
+    valid: true,
+    content
+  };
+}
+
+/**
+ * Validate state.json file
+ *
+ * @param {string} filePath - Path to state.json (defaults to .agentful/state.json)
+ * @param {string[]} additionalFields - Additional required fields beyond schema
+ * @returns {Object} Validation result
+ */
+export function validateState(filePath = '.agentful/state.json', additionalFields = []) {
+  return validateStateFile(filePath, 'state', additionalFields);
+}
+
+/**
+ * Validate completion.json file
+ *
+ * @param {string} filePath - Path to completion.json (defaults to .agentful/completion.json)
+ * @param {string[]} additionalFields - Additional required fields beyond schema
+ * @returns {Object} Validation result
+ */
+export function validateCompletion(filePath = '.agentful/completion.json', additionalFields = []) {
+  return validateStateFile(filePath, 'completion', additionalFields);
+}
+
+/**
+ * Validate decisions.json file
+ *
+ * @param {string} filePath - Path to decisions.json (defaults to .agentful/decisions.json)
+ * @param {string[]} additionalFields - Additional required fields beyond schema
+ * @returns {Object} Validation result
+ */
+export function validateDecisions(filePath = '.agentful/decisions.json', additionalFields = []) {
+  return validateStateFile(filePath, 'decisions', additionalFields);
+}
+
+/**
+ * Validate architecture.json file
+ *
+ * @param {string} filePath - Path to architecture.json (defaults to .agentful/architecture.json)
+ * @param {string[]} additionalFields - Additional required fields beyond schema
+ * @returns {Object} Validation result
+ */
+export function validateArchitecture(filePath = '.agentful/architecture.json', additionalFields = []) {
+  return validateStateFile(filePath, 'architecture', additionalFields);
+}
+
+/**
+ * Validate product.json file
+ *
+ * @param {string} filePath - Path to product.json (defaults to .agentful/product.json)
+ * @param {string[]} additionalFields - Additional required fields beyond schema
+ * @returns {Object} Validation result
+ */
+export function validateProduct(filePath = '.agentful/product.json', additionalFields = []) {
+  return validateStateFile(filePath, 'product', additionalFields);
+}
+
+/**
+ * Batch validate multiple state files
+ *
+ * @param {Object[]} files - Array of {filePath, schemaName, requiredFields?}
+ * @returns {Object} Map of filePath to validation result
+ *
+ * Example:
+ * const results = validateBatch([
+ *   { filePath: '.agentful/state.json', schemaName: 'state' },
+ *   { filePath: '.agentful/completion.json', schemaName: 'completion', requiredFields: ['gates'] }
+ * ]);
+ */
+export function validateBatch(files) {
+  const results = {};
+
+  for (const { filePath, schemaName, requiredFields = [] } of files) {
+    results[filePath] = validateStateFile(filePath, schemaName, requiredFields);
+  }
+
+  return results;
+}
+
+/**
+ * Get human-readable error message for validation result
+ *
+ * @param {Object} validationResult - Result from validateStateFile
+ * @returns {string} Human-readable error message
+ */
+export function getErrorMessage(validationResult) {
+  if (validationResult.valid) {
+    return 'Validation passed';
+  }
+
+  switch (validationResult.action) {
+    case 'missing':
+      return `File not found. Initialize it first.`;
+
+    case 'corrupted':
+      return `File is corrupted (invalid JSON). Backup and reset recommended.`;
+
+    case 'invalid':
+      if (validationResult.errors && validationResult.errors.length > 0) {
+        const errorDetails = validationResult.errors
+          .map(err => `  - ${err.instancePath || 'root'}: ${err.message}`)
+          .join('\n');
+        return `Schema validation failed:\n${errorDetails}`;
+      }
+      return `Schema validation failed.`;
+
+    case 'incomplete':
+      return `Missing required field: '${validationResult.missing_field}'`;
+
+    default:
+      return validationResult.error || 'Unknown validation error';
+  }
+}
+
+/**
+ * Suggested action for validation result
+ *
+ * @param {Object} validationResult - Result from validateStateFile
+ * @returns {string} Suggested action to fix the issue
+ */
+export function getSuggestedAction(validationResult) {
+  if (validationResult.valid) {
+    return 'No action needed';
+  }
+
+  switch (validationResult.action) {
+    case 'missing':
+      return 'Run initialization command to create the file';
+
+    case 'corrupted':
+      return 'Backup the file and create a new one with valid JSON';
+
+    case 'invalid':
+      return 'Fix schema validation errors in the file';
+
+    case 'incomplete':
+      return `Add the missing field: '${validationResult.missing_field}'`;
+
+    default:
+      return 'Check the file and fix any issues';
+  }
+}
+
+/**
+ * Export AJV instance for custom schemas
+ */
+export { ajv };
+
+/**
+ * Export action constants for easy reference
+ */
+export const ValidationActions = {
+  MISSING: 'missing',
+  CORRUPTED: 'corrupted',
+  INVALID: 'invalid',
+  INCOMPLETE: 'incomplete'
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itz4blitz/agentful",
-  "version": "0.3.0",
+  "version": "0.5.1",
   "description": "Human-in-the-loop development kit for Claude Code with smart product analysis and natural conversation",
   "type": "module",
   "bin": {
@@ -8,6 +8,12 @@
   },
   "scripts": {
     "init": "node bin/cli.js init",
+    "test": "vitest run",
+    "test:unit": "vitest run test/unit",
+    "test:validation": "vitest run test/validation",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint .",
     "release": "semantic-release",
     "release:dry-run": "semantic-release --dry-run",
     "docs:dev": "vocs dev",
@@ -23,7 +29,6 @@
     "bin/",
     "lib/",
     "template/",
-    ".claude/",
     "version.json",
     "LICENSE"
   ],
@@ -49,6 +54,7 @@
     "node": ">=22.0.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.2",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^13.0.0",
     "@semantic-release/exec": "^6.0.3",
@@ -56,7 +62,18 @@
     "@semantic-release/github": "^11.0.1",
     "@semantic-release/npm": "^13.1.3",
     "@semantic-release/release-notes-generator": "^14.0.1",
+    "@vitest/coverage-v8": "^1.2.0",
+    "ajv": "^8.12.0",
+    "ajv-formats": "^3.0.1",
+    "eslint": "^9.39.2",
+    "qrcode.react": "^4.2.0",
     "semantic-release": "^25.0.2",
+    "vitest": "^1.2.0",
     "vocs": "^1.4.1"
+  },
+  "dependencies": {
+    "@xyflow/react": "^12.10.0",
+    "handlebars": "^4.7.8",
+    "js-yaml": "^4.1.0"
   }
 }