@itz4blitz/agentful 0.4.0 → 1.0.0

package/lib/pipeline/schemas.js

@@ -0,0 +1,288 @@
+/**
+ * JSON Schemas for Pipeline Definitions
+ *
+ * Provides validation schemas for pipeline YAML files
+ */
+
+export const pipelineSchema = {
+  type: 'object',
+  required: ['name', 'jobs'],
+  properties: {
+    name: {
+      type: 'string',
+      description: 'Pipeline name',
+      pattern: '^[a-z0-9-]+$'
+    },
+    version: {
+      type: 'string',
+      description: 'Pipeline version',
+      pattern: '^\\d+\\.\\d+(\\.\\d+)?$',
+      default: '1.0'
+    },
+    description: {
+      type: 'string',
+      description: 'Pipeline description'
+    },
+    triggers: {
+      type: 'array',
+      description: 'Pipeline triggers',
+      items: {
+        $ref: '#/definitions/trigger'
+      }
+    },
+    env: {
+      type: 'object',
+      description: 'Environment variables',
+      additionalProperties: { type: 'string' }
+    },
+    jobs: {
+      type: 'array',
+      description: 'Pipeline jobs',
+      minItems: 1,
+      items: {
+        $ref: '#/definitions/job'
+      }
+    },
+    concurrency: {
+      type: 'object',
+      description: 'Concurrency settings',
+      properties: {
+        maxConcurrentJobs: {
+          type: 'integer',
+          minimum: 1,
+          maximum: 10,
+          default: 3
+        },
+        cancelInProgress: {
+          type: 'boolean',
+          default: false
+        }
+      }
+    },
+    timeout: {
+      type: 'integer',
+      description: 'Default job timeout in milliseconds',
+      minimum: 1000,
+      default: 1800000 // 30 minutes
+    }
+  },
+  definitions: {
+    trigger: {
+      type: 'object',
+      required: ['type'],
+      properties: {
+        type: {
+          type: 'string',
+          enum: ['push', 'pull_request', 'schedule', 'manual', 'webhook']
+        },
+        branches: {
+          type: 'array',
+          items: { type: 'string' }
+        },
+        cron: {
+          type: 'string',
+          description: 'Cron expression for scheduled triggers'
+        },
+        webhook: {
+          type: 'object',
+          properties: {
+            secret: { type: 'string' },
+            filters: { type: 'object' }
+          }
+        }
+      }
+    },
+    job: {
+      type: 'object',
+      required: ['id', 'agent'],
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Unique job identifier',
+          pattern: '^[a-z0-9-]+$'
+        },
+        name: {
+          type: 'string',
+          description: 'Human-readable job name'
+        },
+        agent: {
+          type: 'string',
+          description: 'Agent to execute (name or path)'
+        },
+        task: {
+          type: 'string',
+          description: 'Task description for the agent'
+        },
+        prompt: {
+          type: 'string',
+          description: 'Additional prompt instructions'
+        },
+        dependsOn: {
+          oneOf: [
+            { type: 'string' },
+            { type: 'array', items: { type: 'string' } }
+          ],
+          description: 'Job dependencies'
+        },
+        when: {
+          type: 'string',
+          description: 'Conditional execution expression'
+        },
+        inputs: {
+          type: 'object',
+          description: 'Job-specific inputs',
+          additionalProperties: true
+        },
+        timeout: {
+          type: 'integer',
+          description: 'Job timeout in milliseconds',
+          minimum: 1000
+        },
+        retry: {
+          $ref: '#/definitions/retry'
+        },
+        continueOnError: {
+          type: 'boolean',
+          description: 'Continue pipeline even if this job fails',
+          default: false
+        },
+        execution: {
+          type: 'object',
+          description: 'Execution configuration',
+          properties: {
+            method: {
+              type: 'string',
+              enum: ['subprocess', 'api'],
+              default: 'subprocess'
+            },
+            isolation: {
+              type: 'string',
+              enum: ['shared', 'isolated'],
+              default: 'shared'
+            }
+          }
+        },
+        runsOn: {
+          type: 'string',
+          description: 'Runner environment (for CI/CD integrations)',
+          default: 'ubuntu-latest'
+        },
+        stage: {
+          type: 'string',
+          description: 'Pipeline stage (for GitLab CI)',
+          default: 'test'
+        },
+        setup: {
+          type: 'array',
+          description: 'Setup steps before job execution',
+          items: {
+            type: 'object',
+            required: ['command'],
+            properties: {
+              name: { type: 'string' },
+              command: { type: 'string' }
+            }
+          }
+        }
+      }
+    },
+    retry: {
+      type: 'object',
+      description: 'Retry policy',
+      properties: {
+        maxAttempts: {
+          type: 'integer',
+          minimum: 0,
+          maximum: 5,
+          default: 0
+        },
+        backoff: {
+          type: 'string',
+          enum: ['exponential', 'linear', 'fixed'],
+          default: 'exponential'
+        },
+        delayMs: {
+          type: 'integer',
+          minimum: 0,
+          default: 2000
+        }
+      }
+    }
+  }
+};
+
+/**
+ * Validate pipeline definition
+ *
+ * @param {Object} pipeline - Pipeline definition
+ * @returns {Object} Validation result { valid: boolean, errors: array }
+ */
+export function validatePipeline(pipeline) {
+  // Basic validation
+  const errors = [];
+
+  if (!pipeline || typeof pipeline !== 'object') {
+    errors.push('Pipeline must be a valid object');
+    return { valid: false, errors };
+  }
+
+  if (!pipeline.name) {
+    errors.push('Pipeline must have a name');
+  }
+
+  if (!pipeline.jobs || !Array.isArray(pipeline.jobs) || pipeline.jobs.length === 0) {
+    errors.push('Pipeline must have at least one job');
+  }
+
+  // Collect all job IDs first
+  const jobIds = new Set();
+  for (const job of pipeline.jobs || []) {
+    if (job.id) {
+      if (jobIds.has(job.id)) {
+        errors.push(`Duplicate job id: ${job.id}`);
+      } else {
+        jobIds.add(job.id);
+      }
+    }
+  }
+
+  // Validate jobs
+  for (const job of pipeline.jobs || []) {
+    // Check if job is a valid object
+    if (!job || typeof job !== 'object') {
+      errors.push('Each job must be a valid object');
+      continue;
+    }
+
+    if (!job.id) {
+      errors.push('Each job must have an id');
+    }
+
+    if (!job.agent) {
+      errors.push(`Job ${job.id} must specify an agent`);
+    }
+
+    // Validate dependencies
+    if ('dependsOn' in job) {
+      const deps = Array.isArray(job.dependsOn) ? job.dependsOn : [job.dependsOn];
+      for (const depId of deps) {
+        // Check for empty string or invalid values
+        if (typeof depId !== 'string' || depId === '') {
+          errors.push(`Job ${job.id} depends on unknown job: ${depId}`);
+        } else if (!jobIds.has(depId)) {
+          errors.push(`Job ${job.id} depends on unknown job: ${depId}`);
+        }
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+export default {
+  pipelineSchema,
+  validatePipeline
+};

package/lib/presets.js

@@ -0,0 +1,207 @@
+/**
+ * Preset configurations for agentful initialization
+ *
+ * SIMPLIFIED: Only two concepts
+ * 1. "default" (or no preset) - Everything installed (recommended)
+ * 2. "minimal" - Minimal setup for simple scripts/CLIs
+ *
+ * Tech stack is auto-detected on first run, irrelevant to installation.
+ *
+ * Each preset defines:
+ * - agents: array of agent names to include
+ * - skills: array of skill names to include
+ * - hooks: array of hook identifiers to configure
+ * - gates: array of quality gate identifiers
+ */
+
+export const presets = {
+  default: {
+    description: 'Complete agentful installation (recommended)',
+    agents: ['orchestrator', 'architect', 'backend', 'frontend', 'tester', 'reviewer', 'fixer', 'product-analyzer'],
+    skills: ['product-tracking', 'validation', 'testing', 'conversation', 'product-planning', 'deployment'],
+    hooks: ['health-check'],
+    gates: ['types', 'tests', 'coverage', 'lint', 'security', 'dead-code']
+  },
+
+  minimal: {
+    description: 'Minimal setup for simple scripts/CLIs (orchestrator + backend only)',
+    agents: ['orchestrator', 'backend'],
+    skills: ['validation'],
+    hooks: [],
+    gates: ['types', 'tests']
+  }
+};
+
+/**
+ * Hook configurations mapping
+ * Maps hook identifiers to actual hook configurations
+ */
+export const hookConfigurations = {
+  'health-check': {
+    event: 'SessionStart',
+    config: {
+      type: 'command',
+      command: 'node bin/hooks/health-check.js',
+      timeout: 5,
+      description: 'Quick agentful health check'
+    }
+  },
+
+  'typescript-validation': {
+    event: 'PostToolUse',
+    matcher: 'Write|Edit',
+    config: {
+      type: 'command',
+      command: 'npx tsc --noEmit 2>&1 | head -5 || true',
+      description: 'TypeScript validation after file changes'
+    }
+  },
+
+  'notifications': {
+    event: 'PostToolUse',
+    matcher: 'Write|Edit',
+    config: {
+      type: 'command',
+      command: 'osascript -e \'display notification "File updated: $FILE" with title "agentful"\' 2>/dev/null || true',
+      description: 'Desktop notifications for file changes'
+    }
+  },
+
+  'format-on-save': {
+    event: 'PostToolUse',
+    matcher: 'Write|Edit',
+    config: {
+      type: 'command',
+      command: 'npx prettier --write "$FILE" 2>/dev/null || true',
+      description: 'Auto-format files on save'
+    }
+  }
+};
+
+/**
+ * Parse comma-separated CLI flag into array
+ * @param {string} value - Comma-separated values
+ * @returns {string[]}
+ */
+export function parseArrayFlag(value) {
+  if (!value) return [];
+  return value.split(',').map(v => v.trim()).filter(Boolean);
+}
+
+/**
+ * Merge preset with CLI flags (flags take precedence)
+ * @param {Object} preset - Preset configuration
+ * @param {Object} flags - CLI flags
+ * @returns {Object} Merged configuration
+ */
+export function mergePresetWithFlags(preset, flags) {
+  return {
+    agents: flags.agents || preset.agents,
+    skills: flags.skills || preset.skills,
+    hooks: flags.hooks || preset.hooks,
+    gates: flags.gates || preset.gates,
+    techStack: flags.techStack || preset.techStack
+  };
+}
+
+/**
+ * Get preset by name
+ * @param {string} presetName - Name of preset
+ * @returns {Object|null} Preset configuration or null if not found
+ */
+export function getPreset(presetName) {
+  return presets[presetName] || null;
+}
+
+/**
+ * List all available presets
+ * @returns {Object[]} Array of preset info
+ */
+export function listPresets() {
+  return Object.entries(presets).map(([name, config]) => ({
+    name,
+    description: config.description,
+    agents: config.agents.length,
+    skills: config.skills.length,
+    hooks: config.hooks.length,
+    gates: config.gates.length
+  }));
+}
+
+/**
+ * Validate configuration
+ * @param {Object} config - Configuration to validate
+ * @returns {{valid: boolean, errors: string[]}}
+ */
+export function validateConfiguration(config) {
+  const errors = [];
+  const availableAgents = ['orchestrator', 'architect', 'backend', 'frontend', 'tester', 'reviewer', 'fixer', 'product-analyzer'];
+  const availableSkills = ['product-tracking', 'validation', 'testing', 'conversation', 'product-planning', 'deployment'];
+  const availableHooks = Object.keys(hookConfigurations);
+
+  // Always require orchestrator
+  if (!config.agents || !config.agents.includes('orchestrator')) {
+    errors.push('orchestrator agent is required and will be added automatically');
+  }
+
+  // Validate agents
+  if (config.agents) {
+    const invalidAgents = config.agents.filter(a => !availableAgents.includes(a));
+    if (invalidAgents.length > 0) {
+      errors.push(`Invalid agents: ${invalidAgents.join(', ')}`);
+    }
+  }
+
+  // Validate skills
+  if (config.skills) {
+    const invalidSkills = config.skills.filter(s => !availableSkills.includes(s));
+    if (invalidSkills.length > 0) {
+      errors.push(`Invalid skills: ${invalidSkills.join(', ')}`);
+    }
+  }
+
+  // Validate hooks
+  if (config.hooks) {
+    const invalidHooks = config.hooks.filter(h => !availableHooks.includes(h));
+    if (invalidHooks.length > 0) {
+      errors.push(`Invalid hooks: ${invalidHooks.join(', ')}`);
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * Generate settings.json hooks section from hook identifiers
+ * @param {string[]} hookIds - Array of hook identifiers
+ * @returns {Object} Settings.json hooks section
+ */
+export function generateHooksConfig(hookIds) {
+  const hooks = {};
+
+  for (const hookId of hookIds) {
+    const hookConfig = hookConfigurations[hookId];
+    if (!hookConfig) continue;
+
+    const event = hookConfig.event;
+    if (!hooks[event]) {
+      hooks[event] = [];
+    }
+
+    const hookEntry = {
+      hooks: [hookConfig.config]
+    };
+
+    // Add matcher if specified
+    if (hookConfig.matcher) {
+      hookEntry.matcher = hookConfig.matcher;
+    }
+
+    hooks[event].push(hookEntry);
+  }
+
+  return hooks;
+}