pixelcrew 0.2.2 → 0.2.6

package/src/orchestrator/semantic-reviewer.js

@@ -0,0 +1,179 @@
+/**
+ * PIXEL CREW — Semantic Reviewer
+ * 
+ * Performs deterministic structural and semantic coherence audits on Project ASTs:
+ * - Missing / orphaned entities
+ * - Invalid entity relationships
+ * - Workflows lacking UI views or backend operations
+ * - Critical requirements lacking verifiable acceptance criteria
+ * - Automatically synthesizes missing links to guarantee 100% coherence.
+ */
+
+import { UniversalSoftwareOntology, OPERATION_METHODS, LAYOUT_PRIMITIVES, REQUIREMENT_CATEGORIES } from './ontology.js';
+
+export class SemanticReviewer {
+  /**
+   * Audit and repair an AST for semantic completeness.
+   */
+  static reviewAndRepair(ast) {
+    if (!ast || typeof ast !== 'object') {
+      throw new Error('SemanticReviewer: ast must be a valid object.');
+    }
+
+    const issues = [];
+    const suggestions = [];
+    const repaired = JSON.parse(JSON.stringify(ast));
+
+    const entityNames = new Set((repaired.entities || []).map(e => e.name));
+
+    // 1. Audit Entities & Seed Data
+    if (!repaired.entities || repaired.entities.length === 0) {
+      issues.push({ code: 'EMPTY_ENTITIES', severity: 'error', message: 'AST contains zero domain entities.' });
+      repaired.entities = [UniversalSoftwareOntology.validateEntity({ name: 'SystemRecord' })];
+      entityNames.add('SystemRecord');
+    }
+
+    repaired.entities.forEach(entity => {
+      // Ensure seed data exists
+      if (!entity.seedData || entity.seedData.length === 0) {
+        entity.seedData = this.synthesizeSeedData(entity);
+        suggestions.push({ type: 'SYNTHESIZED_SEED_DATA', entity: entity.name });
+      }
+
+      // Check relationships
+      if (Array.isArray(entity.relationships)) {
+        entity.relationships.forEach(rel => {
+          if (!entityNames.has(rel.targetEntity)) {
+            issues.push({
+              code: 'ORPHANED_RELATIONSHIP',
+              severity: 'warning',
+              message: `Entity '${entity.name}' references non-existent target '${rel.targetEntity}'.`
+            });
+            // Re-target to available entity
+            rel.targetEntity = Array.from(entityNames)[0];
+          }
+        });
+      }
+    });
+
+    // 2. Audit Views (Ensure every primary entity has an interactive view)
+    if (!repaired.views || repaired.views.length === 0) {
+      issues.push({ code: 'NO_VIEWS', severity: 'error', message: 'AST has no UI views defined.' });
+      repaired.views = [];
+    }
+
+    const coveredEntitiesInViews = new Set();
+    repaired.views.forEach(v => {
+      (v.targetEntities || []).forEach(te => coveredEntitiesInViews.add(te));
+    });
+
+    repaired.entities.forEach((entity, idx) => {
+      if (!coveredEntitiesInViews.has(entity.name)) {
+        // Synthesize an interactive view for uncovered entity
+        const newView = {
+          id: `view-${entity.name.toLowerCase()}-management`,
+          componentName: `${entity.name}Explorer`,
+          title: `${entity.title || entity.name} Explorer`,
+          purpose: `Browse, inspect and manage ${entity.plural || entity.name} records`,
+          targetEntities: [entity.name],
+          layout: { type: idx === 0 ? LAYOUT_PRIMITIVES.SPLIT : LAYOUT_PRIMITIVES.GRID, density: 'comfortable' },
+          regions: [
+            { role: 'navigation', components: ['search', 'filter'] },
+            { role: 'content', components: ['collection', 'table'] },
+            { role: 'inspector', components: ['inspector', 'form'] }
+          ],
+          capabilities: ['search', 'filter', 'view', 'create', 'edit', 'delete']
+        };
+        repaired.views.push(UniversalSoftwareOntology.validateView(newView, repaired.entities));
+        suggestions.push({ type: 'SYNTHESIZED_VIEW', entity: entity.name, view: newView.componentName });
+      }
+    });
+
+    // 3. Audit Operations (Ensure backend REST operations exist for all entities)
+    if (!repaired.operations || repaired.operations.length === 0) {
+      repaired.operations = [];
+    }
+
+    const operatedEntities = new Set(repaired.operations.map(o => o.targetEntity));
+    repaired.entities.forEach(entity => {
+      if (!operatedEntities.has(entity.name)) {
+        // Add GET and POST operations
+        repaired.operations.push(UniversalSoftwareOntology.validateOperation({
+          id: `op-get-${entity.name.toLowerCase()}s`,
+          path: `/api/${entity.name.toLowerCase()}s`,
+          method: OPERATION_METHODS.GET,
+          description: `Retrieve all ${entity.plural || entity.name} records`,
+          targetEntity: entity.name
+        }, repaired.entities));
+
+        repaired.operations.push(UniversalSoftwareOntology.validateOperation({
+          id: `op-post-${entity.name.toLowerCase()}`,
+          path: `/api/${entity.name.toLowerCase()}s`,
+          method: OPERATION_METHODS.POST,
+          description: `Create a new ${entity.name} record`,
+          targetEntity: entity.name,
+          requestFields: entity.fields.map(f => f.name)
+        }, repaired.entities));
+
+        suggestions.push({ type: 'SYNTHESIZED_OPERATIONS', entity: entity.name });
+      }
+    });
+
+    // 4. Audit Requirements & Acceptance Criteria
+    if (!repaired.requirements || repaired.requirements.length === 0) {
+      repaired.requirements = [];
+    }
+
+    // Ensure at least 1 requirement per View and 1 per Operation
+    repaired.views.forEach((v, idx) => {
+      const hasReq = repaired.requirements.some(r => r.target === v.componentName || r.description.includes(v.componentName));
+      if (!hasReq) {
+        repaired.requirements.push({
+          id: `REQ-${String(repaired.requirements.length + 1).padStart(3, '0')}`,
+          category: REQUIREMENT_CATEGORIES.UI_COMPONENT,
+          target: v.componentName,
+          description: `Synthesize interactive ${v.title} component with search, filter, and inspector capabilities.`,
+          acceptanceCriteria: [
+            `${v.componentName} renders without runtime errors`,
+            `Displays active ${v.targetEntities.join(', ')} records`,
+            `Supports interactive filtering and state updates`
+          ],
+          priority: idx === 0 ? 'critical' : 'high'
+        });
+      }
+    });
+
+    return {
+      isValid: issues.filter(i => i.severity === 'error').length === 0,
+      issues,
+      suggestions,
+      ast: repaired
+    };
+  }
+
+  /**
+   * Synthesize realistic domain seed data for an entity
+   */
+  static synthesizeSeedData(entity) {
+    const records = [];
+    const count = 4;
+    for (let i = 1; i <= count; i++) {
+      const rec = {};
+      entity.fields.forEach(f => {
+        if (f.name === 'id') {
+          rec.id = `${entity.id || entity.name.toLowerCase()}-${String(i).padStart(3, '0')}`;
+        } else if (f.type === 'number') {
+          rec[f.name] = (i * 12.5) + (f.name.includes('depth') ? 45 : (f.name.includes('count') ? 8 : 100));
+        } else if (f.type === 'boolean') {
+          rec[f.name] = i % 2 === 0;
+        } else if (f.type === 'datetime') {
+          rec[f.name] = new Date(Date.now() - (i * 86400000)).toISOString();
+        } else {
+          rec[f.name] = `${entity.name} ${f.label || f.name} ${i}`;
+        }
+      });
+      records.push(rec);
+    }
+    return records;
+  }
+}

package/src/orchestrator/skills-registry.js

@@ -0,0 +1,194 @@
+/**
+ * PIXEL CREW — Modular Skill Registry
+ * 
+ * Reusable capability definitions across Frontend, Design, Motion, Quality, Backend, and Content.
+ */
+
+export const SKILL_DEFINITIONS = {
+  // Frontend Skills
+  'frontend/nextjs': {
+    id: 'frontend/nextjs',
+    name: 'Next.js 14/15 App Router',
+    category: 'frontend',
+    description: 'Server Components, Streaming SSR, Layout hierarchy, and Metadata APIs',
+    targetAgents: ['frontend']
+  },
+  'frontend/react': {
+    id: 'frontend/react',
+    name: 'React 18/19 Primitives',
+    category: 'frontend',
+    description: 'Custom React hooks, client-side state management, and component islands',
+    targetAgents: ['frontend']
+  },
+  'frontend/tailwind': {
+    id: 'frontend/tailwind',
+    name: 'Tailwind CSS & Token System',
+    category: 'frontend',
+    description: 'Utility-first styling, design token mapping, fluid clamp scales, and dark mode',
+    targetAgents: ['frontend', 'designSystem']
+  },
+  'frontend/accessibility': {
+    id: 'frontend/accessibility',
+    name: 'WCAG 2.1 AA/AAA Accessibility',
+    category: 'frontend',
+    description: 'ARIA landmarks, keyboard focus management, and color contrast compliance',
+    targetAgents: ['frontend', 'qa']
+  },
+
+  // Design Skills
+  'design/ui-design': {
+    id: 'design/ui-design',
+    name: 'Bespoke UI & Asymmetric Layouts',
+    category: 'design',
+    description: 'High-contrast visual hierarchy, intentional whitespace, and Bento grid topologies',
+    targetAgents: ['creativeDirector', 'uxPlanner']
+  },
+  'design/typography': {
+    id: 'design/typography',
+    name: 'Expressive Typography Scales',
+    category: 'design',
+    description: 'Mathematical fluid clamp() type scales, display serif and geometric sans pairings',
+    targetAgents: ['creativeDirector', 'designSystem']
+  },
+  'design/design-system': {
+    id: 'design/design-system',
+    name: 'Design System Architecture',
+    category: 'design',
+    description: 'CSS Custom Properties, HSL color tokens, surface elevation tiers, and borders',
+    targetAgents: ['designSystem']
+  },
+
+  // Motion & Animation Skills
+  'motion/framer-motion': {
+    id: 'motion/framer-motion',
+    name: 'Framer Motion & View Transitions',
+    category: 'motion',
+    description: 'Smooth scroll-driven reveals, staggered entrance choreography, and gesture physics',
+    targetAgents: ['animationSpecialist', 'frontend']
+  },
+  'motion/micro-interactions': {
+    id: 'motion/micro-interactions',
+    name: 'Interactive Micro-Interactions',
+    category: 'motion',
+    description: 'Hover states, magnetic buttons, live filter transitions, and interactive terminal state',
+    targetAgents: ['animationSpecialist', 'frontend']
+  },
+
+  // Quality & Review Skills
+  'quality/responsive-design': {
+    id: 'quality/responsive-design',
+    name: 'Adaptive Responsive Design',
+    category: 'quality',
+    description: 'Fluid viewports from 360px mobile to 4K desktop with zero horizontal overflow',
+    targetAgents: ['responsiveSpecialist', 'frontend']
+  },
+  'quality/visual-review': {
+    id: 'quality/visual-review',
+    name: '6-Dimension Anti-AI Rubric Review',
+    category: 'quality',
+    description: 'Originality, Typography, Layout, Hierarchy, Brand Consistency, and AI Slop Penalty audit',
+    targetAgents: ['visualCritic', 'qa']
+  },
+  'quality/browser-testing': {
+    id: 'quality/browser-testing',
+    name: 'Build Verification & Smoke Testing',
+    category: 'quality',
+    description: 'Syntax validation, TypeScript type-checking, and layout integrity checks',
+    targetAgents: ['qa']
+  },
+
+  // Backend & Data Skills
+  'backend/route-handlers': {
+    id: 'backend/route-handlers',
+    name: 'TypeScript Route Handlers',
+    category: 'backend',
+    description: 'Next.js App Router API routes, JSON schema validation, and RFC 7807 error envelopes',
+    targetAgents: ['backend']
+  },
+  'backend/data-models': {
+    id: 'backend/data-models',
+    name: 'Structured Data Modeling',
+    category: 'backend',
+    description: 'Domain entities, TypeScript interfaces, and static fixtures',
+    targetAgents: ['backend', 'database']
+  },
+
+  // Content & Anti-AI Skills
+  'content/copywriting': {
+    id: 'content/copywriting',
+    name: 'Grounded Technical Copywriting',
+    category: 'content',
+    description: 'Zero AI cliché copy, authentic product propositions, and real technical metrics',
+    targetAgents: ['contentStrategist', 'uxPlanner']
+  },
+  'anti-ai/slop-guardian': {
+    id: 'anti-ai/slop-guardian',
+    name: 'Anti-AI Pattern Detection Guardian',
+    category: 'quality',
+    description: 'Bans purple/blue mesh gradient blobs, repeating 3-card grids, and fake AI sparkles',
+    targetAgents: ['creativeDirector', 'visualCritic']
+  }
+};
+
+export class SkillRegistry {
+  constructor() {
+    this.skills = new Map(Object.entries(SKILL_DEFINITIONS));
+  }
+
+  getSkill(skillId) {
+    return this.skills.get(skillId) || null;
+  }
+
+  getAllSkills() {
+    return Array.from(this.skills.values());
+  }
+
+  getSkillsByCategory(category) {
+    return Array.from(this.skills.values()).filter(s => s.category === category);
+  }
+
+  /**
+   * Matches task requirements to skill IDs
+   */
+  matchSkills(taskRequirement) {
+    const text = (taskRequirement || '').toLowerCase();
+    const matched = new Set();
+
+    if (text.includes('next') || text.includes('component') || text.includes('page')) {
+      matched.add('frontend/nextjs');
+      matched.add('frontend/react');
+      matched.add('frontend/tailwind');
+    }
+    if (text.includes('design') || text.includes('visual') || text.includes('artistic')) {
+      matched.add('design/ui-design');
+      matched.add('design/typography');
+      matched.add('design/design-system');
+      matched.add('anti-ai/slop-guardian');
+    }
+    if (text.includes('animation') || text.includes('motion') || text.includes('interaction')) {
+      matched.add('motion/framer-motion');
+      matched.add('motion/micro-interactions');
+    }
+    if (text.includes('responsive') || text.includes('mobile') || text.includes('tablet')) {
+      matched.add('quality/responsive-design');
+    }
+    if (text.includes('api') || text.includes('backend') || text.includes('route')) {
+      matched.add('backend/route-handlers');
+      matched.add('backend/data-models');
+    }
+    if (text.includes('qa') || text.includes('test') || text.includes('review') || text.includes('rubric')) {
+      matched.add('quality/visual-review');
+      matched.add('quality/browser-testing');
+    }
+    if (text.includes('copy') || text.includes('content') || text.includes('text')) {
+      matched.add('content/copywriting');
+    }
+
+    if (matched.size === 0) {
+      matched.add('frontend/nextjs');
+      matched.add('frontend/tailwind');
+    }
+
+    return Array.from(matched);
+  }
+}

package/src/orchestrator/task-planner.js

@@ -0,0 +1,111 @@
+/**
+ * PIXEL CREW — Dynamic Task Planner
+ * 
+ * Compiles a Directed Acyclic Graph (DAG) of specialized agent tasks from
+ * Project AST, RequirementContract, and DesignSpec.
+ */
+
+export class TaskPlanner {
+  /**
+   * Compile DAG task graph
+   */
+  static planTaskGraph({ ast, requirementContract, designSpec }) {
+    const tasks = [];
+    const views = ast.views || [];
+    const operations = ast.operations || [];
+    const entities = ast.entities || [];
+
+    // Phase 1: Semantic Review & Design Direction
+    tasks.push({
+      id: 'task-semantic-review',
+      title: 'Review Project AST & Semantic Coherence',
+      role: 'orchestrator',
+      phase: 'analysis',
+      dependencies: [],
+      inputs: ['Project AST'],
+      outputs: ['Normalized AST', 'Requirement Contract']
+    });
+
+    tasks.push({
+      id: 'task-design-spec',
+      title: 'Synthesize Bespoke Visual Design Specification',
+      role: 'creativeDirector',
+      phase: 'design',
+      dependencies: ['task-semantic-review'],
+      inputs: ['Normalized AST'],
+      outputs: ['DesignSpec']
+    });
+
+    // Phase 2: Domain Modeling & Database Fixtures
+    tasks.push({
+      id: 'task-data-modeling',
+      title: `Synthesize TypeScript Models & Seed Data for ${entities.length} Entities`,
+      role: 'database',
+      phase: 'foundation',
+      dependencies: ['task-semantic-review'],
+      inputs: entities.map(e => e.name),
+      outputs: ['src/types/index.ts', 'src/lib/data.ts']
+    });
+
+    // Phase 3: Global Design Tokens & App Layout
+    tasks.push({
+      id: 'task-design-tokens',
+      title: 'Compile Tailwind Tokens & Global CSS',
+      role: 'designSystem',
+      phase: 'foundation',
+      dependencies: ['task-design-spec'],
+      inputs: ['DesignSpec'],
+      outputs: ['src/app/globals.css', 'tailwind.config.ts']
+    });
+
+    // Phase 4: Parallel View & Backend API Construction
+    views.forEach((v, idx) => {
+      tasks.push({
+        id: `task-view-${v.componentName.toLowerCase()}`,
+        title: `Implement ${v.componentName} (${v.title})`,
+        role: 'frontend',
+        phase: 'implementation',
+        dependencies: ['task-data-modeling', 'task-design-tokens'],
+        inputs: [v.componentName, ...v.targetEntities],
+        outputs: [`src/components/sections/${v.componentName}.tsx`]
+      });
+    });
+
+    tasks.push({
+      id: 'task-backend-routes',
+      title: `Synthesize ${operations.length} REST Route Handlers (RFC 7807)`,
+      role: 'backend',
+      phase: 'implementation',
+      dependencies: ['task-data-modeling'],
+      inputs: operations.map(o => o.path),
+      outputs: operations.map(o => `src/app${o.path}/route.ts`)
+    });
+
+    // Phase 5: Root Page Assembly
+    tasks.push({
+      id: 'task-page-assembly',
+      title: 'Assemble Dynamic Root Page & Navigation',
+      role: 'frontend',
+      phase: 'assembly',
+      dependencies: views.map(v => `task-view-${v.componentName.toLowerCase()}`),
+      inputs: views.map(v => v.componentName),
+      outputs: ['src/app/page.tsx', 'src/components/sections/PortalHeader.tsx']
+    });
+
+    // Phase 6: Requirement & Visual Quality Validation
+    tasks.push({
+      id: 'task-validation-gate',
+      title: 'Run Requirement Contract & Visual Critic Quality Gate',
+      role: 'qa',
+      phase: 'validation',
+      dependencies: ['task-page-assembly', 'task-backend-routes'],
+      inputs: ['RequirementContract', 'All Generated Files'],
+      outputs: ['QualityGateReport']
+    });
+
+    return {
+      totalTasks: tasks.length,
+      tasks
+    };
+  }
+}

package/src/orchestrator/task-queue.js

@@ -0,0 +1,128 @@
+/**
+ * PIXEL CREW — Autonomous Agent Runtime & DAG Task Queue
+ * 
+ * Manages dynamic DAG task scheduling, parallel execution, and granular event streaming.
+ */
+
+import { EventEmitter } from 'node:events';
+
+export class TaskQueue extends EventEmitter {
+  constructor(tasks = []) {
+    super();
+    this.tasks = new Map(tasks.map(t => [t.id, { ...t }]));
+    this.completedTasks = new Set();
+    this.runningTasks = new Set();
+    this.failedTasks = new Set();
+    this.history = [];
+  }
+
+  /**
+   * Retrieves all tasks currently ready for execution
+   * (all dependencies completed and task is currently queued)
+   */
+  getReadyTasks() {
+    const ready = [];
+    for (const [id, task] of this.tasks.entries()) {
+      if (task.status === 'queued') {
+        const depsMet = task.dependsOn.every(depId => this.completedTasks.has(depId));
+        if (depsMet) {
+          ready.push(task);
+        }
+      }
+    }
+    return ready;
+  }
+
+  isCompleted() {
+    return this.tasks.size === this.completedTasks.size;
+  }
+
+  hasFailed() {
+    return this.failedTasks.size > 0;
+  }
+
+  /**
+   * Executes the entire DAG with autonomous agent dispatching
+   */
+  async execute(runtimeContext = {}, onEvent = () => {}) {
+    const emit = (event) => {
+      this.history.push(event);
+      this.emit('event', event);
+      onEvent(event);
+    };
+
+    while (!this.isCompleted() && !this.hasFailed()) {
+      const readyTasks = this.getReadyTasks();
+
+      if (readyTasks.length === 0 && this.runningTasks.size === 0) {
+        throw new Error('Deadlock detected in Task Graph: cyclic dependency or unmet prerequisite');
+      }
+
+      // Execute all ready tasks in parallel batch
+      const promises = readyTasks.map(async (task) => {
+        task.status = 'running';
+        this.runningTasks.add(task.id);
+
+        emit({
+          type: 'agent.started',
+          agent: task.agentId,
+          taskId: task.id,
+          taskName: task.name,
+          message: `Workstation activated for: ${task.name}`
+        });
+
+        // Activate required skills
+        for (const skill of task.skills) {
+          emit({
+            type: 'skill.activated',
+            agent: task.agentId,
+            taskId: task.id,
+            skill,
+            message: `Applying skill: ${skill}`
+          });
+        }
+
+        // Execute actual agent task payload if handler exists
+        if (runtimeContext.executeTaskHandler) {
+          try {
+            await runtimeContext.executeTaskHandler(task, emit);
+          } catch (err) {
+            task.status = 'failed';
+            this.failedTasks.add(task.id);
+            this.runningTasks.delete(task.id);
+            emit({
+              type: 'task.failed',
+              agent: task.agentId,
+              taskId: task.id,
+              error: err.message
+            });
+            throw err;
+          }
+        } else {
+          await new Promise(r => setTimeout(r, 400));
+        }
+
+        task.status = 'completed';
+        this.runningTasks.delete(task.id);
+        this.completedTasks.add(task.id);
+
+        emit({
+          type: 'task.completed',
+          agent: task.agentId,
+          taskId: task.id,
+          taskName: task.name,
+          message: `Completed: ${task.name}`
+        });
+      });
+
+      await Promise.all(promises);
+    }
+
+    return {
+      success: !this.hasFailed(),
+      completedCount: this.completedTasks.size,
+      totalTasks: this.tasks.size,
+      history: this.history
+    };
+  }
+}