@auto-engineer/information-architect 0.13.3 → 0.15.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @auto-engineer/information-architect@0.13.3 build /home/runner/work/auto-engineer/auto-engineer/packages/information-architect
+> @auto-engineer/information-architect@0.15.0 build /home/runner/work/auto-engineer/auto-engineer/packages/information-architect
 > tsc && tsx ../../scripts/fix-esm-imports.ts && cp src/auto-ux-schema.json dist/
 
 Fixed ESM imports in dist/

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @auto-engineer/information-architect
 
+## 0.15.0
+
+### Minor Changes
+
+- version bump
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @auto-engineer/message-bus@0.15.0
+  - @auto-engineer/ai-gateway@0.15.0
+  - @auto-engineer/narrative@0.15.0
+
+## 0.14.0
+
+### Minor Changes
+
+- Rewrite CLI and Pipeline
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @auto-engineer/ai-gateway@0.14.0
+  - @auto-engineer/message-bus@0.14.0
+  - @auto-engineer/narrative@0.14.0
+
 ## 0.13.3
 
 ### Patch Changes

package/README.md

@@ -1,408 +1,216 @@
 # @auto-engineer/information-architect
 
-AI-powered information architecture generation plugin for the Auto Engineer CLI that transforms business requirements into structured application blueprints. This plugin creates information architectures, user experience flows, and content hierarchies from high-level requirements.
+AI-powered Information Architecture generation that transforms narrative models into UI component specifications.
 
-## Installation
+---
+
+## Purpose
+
+Without `@auto-engineer/information-architect`, you would have to manually design component hierarchies from business requirements, maintain consistency across atomic design layers, and validate composition references by hand.
 
-This is a plugin for the Auto Engineer CLI. Install both the CLI and this plugin:
+This package generates structured UI component architectures from business flow models. It uses AI to analyze narrative models and produces specifications for atoms, molecules, organisms, and pages following Atomic Design methodology.
+
+---
+
+## Installation
 
 ```bash
-npm install -g @auto-engineer/cli
-npm install @auto-engineer/information-architect
+pnpm add @auto-engineer/information-architect
 ```
 
-## Configuration
+## Quick Start
 
-Add this plugin to your `auto.config.ts`:
+Register the handler and generate an IA scheme:
+
+### 1. Register the handlers
 
 ```typescript
-export default {
-  plugins: [
-    '@auto-engineer/information-architect',
-    // ... other plugins
-  ],
-};
-```
+import { COMMANDS } from '@auto-engineer/information-architect';
+import { createMessageBus } from '@auto-engineer/message-bus';
 
-## Commands
-
-This plugin provides the following commands:
-
-- `generate:ia` - Generate information architecture from requirements
-
-## What does this plugin do?
-
-The Information Architect plugin analyzes business requirements and generates structured information architectures that serve as blueprints for application development. It creates user experience flows, content hierarchies, navigation structures, and interaction patterns that guide the development of frontend and server systems.
-
-## Key Features
-
-### Requirements Analysis
-
-- Parses business requirements
-- Identifies user personas and use cases
-- Extracts functional and non-functional requirements
-- Maps business processes to application features
-
-### Information Architecture Generation
-
-- Creates content structures
-- Defines navigation patterns and user flows
-- Establishes data relationships and dependencies
-- Generates wireframes and interaction specifications
-
-### User Experience Design
-
-- Maps user journeys and task flows
-- Identifies key interaction points and decision moments
-- Defines responsive design requirements
-- Creates accessibility and usability guidelines
-
-### Technical Specifications
-
-- Generates API requirements and data models
-- Creates component hierarchies for frontend development
-- Defines integration points and external dependencies
-- Establishes performance and scalability requirements
-
-## Generated Architecture Components
-
-### Site Map and Navigation
-
-Creates comprehensive navigation structures:
-
-```json
-{
-  "siteMap": {
-    "root": "/",
-    "sections": [
-      {
-        "name": "Dashboard",
-        "path": "/dashboard",
-        "access": "authenticated",
-        "children": [
-          {
-            "name": "Analytics",
-            "path": "/dashboard/analytics",
-            "description": "Performance metrics and insights"
-          },
-          {
-            "name": "Settings",
-            "path": "/dashboard/settings",
-            "description": "Account and application settings"
-          }
-        ]
-      },
-      {
-        "name": "Products",
-        "path": "/products",
-        "access": "public",
-        "children": [
-          {
-            "name": "Catalog",
-            "path": "/products/catalog",
-            "description": "Browse all available products"
-          },
-          {
-            "name": "Product Details",
-            "path": "/products/:id",
-            "description": "Detailed product information and purchasing options"
-          }
-        ]
-      }
-    ]
-  }
-}
+const bus = createMessageBus();
+COMMANDS.forEach(cmd => bus.registerCommand(cmd));
 ```
 
-### User Personas and Journeys
-
-Defines target users and their interaction patterns:
-
-```json
-{
-  "personas": [
-    {
-      "name": "End Consumer",
-      "description": "Individual purchasing products for personal use",
-      "goals": ["Find products quickly", "Compare options easily", "Complete purchases securely"],
-      "painPoints": ["Complex checkout process", "Limited product information", "Poor mobile experience"],
-      "journeys": [
-        {
-          "name": "Product Purchase",
-          "steps": [
-            {
-              "stage": "Discovery",
-              "actions": ["Browse catalog", "Search products", "Filter results"],
-              "touchpoints": ["/products", "/search"],
-              "requirements": ["Fast search", "Intuitive filters", "Product recommendations"]
-            },
-            {
-              "stage": "Evaluation",
-              "actions": ["View details", "Compare products", "Read reviews"],
-              "touchpoints": ["/products/:id", "/compare"],
-              "requirements": ["Detailed information", "High-quality images", "Social proof"]
-            },
-            {
-              "stage": "Purchase",
-              "actions": ["Add to cart", "Checkout", "Payment"],
-              "touchpoints": ["/cart", "/checkout"],
-              "requirements": ["Simple checkout", "Multiple payment options", "Security indicators"]
-            }
-          ]
-        }
-      ]
-    }
-  ]
-}
-```
+### 2. Send a command
 
-### Page Specifications
-
-Detailed specifications for each application page:
-
-```json
-{
-  "pages": [
-    {
-      "name": "Product Catalog",
-      "path": "/products",
-      "purpose": "Allow users to browse and discover products",
-      "layout": {
-        "type": "grid",
-        "responsive": true,
-        "components": [
-          {
-            "name": "SearchBar",
-            "position": "header",
-            "functionality": "Real-time product search with autocomplete"
-          },
-          {
-            "name": "FilterSidebar",
-            "position": "left",
-            "functionality": "Category, price, and attribute filtering"
-          },
-          {
-            "name": "ProductGrid",
-            "position": "main",
-            "functionality": "Paginated grid of product cards with sorting options"
-          },
-          {
-            "name": "Pagination",
-            "position": "footer",
-            "functionality": "Navigate through product results"
-          }
-        ]
-      },
-      "dataRequirements": [
-        "Product catalog with metadata",
-        "Category hierarchy",
-        "Search indexing",
-        "User preferences"
-      ],
-      "apiEndpoints": ["GET /api/products", "GET /api/categories", "GET /api/search"]
-    }
-  ]
-}
+```typescript
+const result = await bus.dispatch({
+  type: 'GenerateIA',
+  data: {
+    modelPath: './.context/schema.json',
+    outputDir: './.context',
+  },
+  requestId: 'req-123',
+});
+
+console.log(result);
+// → { type: 'IAGenerated', data: { outputDir: './.context', schemaPath: './.context/auto-ia-scheme.json' } }
 ```
 
-### Component Architecture
-
-Defines reusable component specifications:
-
-```json
-{
-  "components": [
-    {
-      "name": "ProductCard",
-      "type": "organism",
-      "purpose": "Display product information in a card format",
-      "props": [
-        {
-          "name": "product",
-          "type": "Product",
-          "required": true,
-          "description": "Product data object"
-        },
-        {
-          "name": "onAddToCart",
-          "type": "function",
-          "required": false,
-          "description": "Callback when add to cart is clicked"
-        }
-      ],
-      "composition": ["ProductImage", "ProductTitle", "ProductPrice", "AddToCartButton", "ProductRating"],
-      "states": ["loading", "outOfStock", "onSale"],
-      "interactions": [
-        "hover: show quick actions",
-        "click: navigate to product details",
-        "cart button: add to cart with feedback"
-      ]
-    }
-  ]
-}
-```
+The command generates `auto-ia-scheme.json` with atoms, molecules, organisms, and pages.
 
-### Data Models and Relationships
-
-Defines server data structure requirements:
-
-```json
-{
-  "dataModels": [
-    {
-      "name": "Product",
-      "description": "Core product entity",
-      "fields": [
-        {
-          "name": "id",
-          "type": "string",
-          "required": true,
-          "description": "Unique product identifier"
-        },
-        {
-          "name": "name",
-          "type": "string",
-          "required": true,
-          "description": "Product display name"
-        },
-        {
-          "name": "price",
-          "type": "decimal",
-          "required": true,
-          "description": "Product price in base currency"
-        },
-        {
-          "name": "category",
-          "type": "Category",
-          "required": true,
-          "relationship": "many-to-one"
-        }
-      ],
-      "relationships": [
-        {
-          "type": "one-to-many",
-          "target": "Review",
-          "description": "Products can have multiple reviews"
-        },
-        {
-          "type": "many-to-many",
-          "target": "Tag",
-          "description": "Products can have multiple tags for categorization"
-        }
-      ]
-    }
-  ]
-}
+---
+
+## How-to Guides
+
+### Run via CLI
+
+```bash
+auto generate:ia --output-dir=./.context --model-path=./.context/schema.json
 ```
 
-## Configuration Options
+### Run via Script
+
+```bash
+pnpm generate-ia-schema ./.context
+```
 
-Customize IA generation behavior:
+### Run Programmatically
 
 ```typescript
-// auto.config.ts
-export default {
-  plugins: [
-    [
-      '@auto-engineer/information-architect',
-      {
-        // Analysis preferences
-        includeUserPersonas: true,
-        includeUserJourneys: true,
-        includeWireframes: false,
-
-        // Output format
-        outputFormat: 'json', // or 'markdown', 'html'
-
-        // Detail level
-        detailLevel: 'comprehensive', // or 'basic', 'detailed'
-
-        // Target platforms
-        platforms: ['web', 'mobile'],
-
-        // Design system integration
-        useDesignSystem: true,
-        designSystemPath: './design-system',
-      },
-    ],
-  ],
-};
+import { processFlowsWithAI, validateCompositionReferences } from '@auto-engineer/information-architect';
+
+const iaSchema = await processFlowsWithAI(model, uxSchema, undefined, existingAtoms);
+const errors = validateCompositionReferences(iaSchema, atomNames);
 ```
 
-## Integration with Other Plugins
+### Handle Errors
 
-The Information Architect serves as a foundation for other plugins:
+```typescript
+if (result.type === 'IAGenerationFailed') {
+  console.error(result.data.error);
+}
+
+if (result.type === 'IAValidationFailed') {
+  console.error('Composition validation errors:', result.data.errors);
+}
+```
+
+### Enable Debug Logging
 
-- **@auto-engineer/flow**: Uses IA specifications to generate business flows
-- **@auto-engineer/server-generator-apollo-emmett**: Creates server models from IA data specifications
-- **@auto-engineer/frontend-generator-react-graphql**: Generates frontend structure based on IA navigation
-- **@auto-engineer/design-system-importer**: Applies design system constraints to IA components
-- **@auto-engineer/frontend-implementer**: Implements pages and components per IA specifications
+```bash
+DEBUG=auto:information-architect:* pnpm generate-ia-schema ./.context
+```
 
-## Workflow
+---
 
-### 1. Requirements Input
+## API Reference
 
-Provide business requirements as natural language:
+### Exports
 
-```bash
-auto generate:ia --requirements="Create an e-commerce platform for selling handmade crafts. Users should be able to browse products, add items to cart, and complete purchases. Include user accounts, order history, and seller management."
+```typescript
+import {
+  COMMANDS,
+  InformationArchitectAgent,
+  processFlowsWithAI,
+  validateCompositionReferences,
+} from '@auto-engineer/information-architect';
+
+import type {
+  GenerateIACommand,
+  IAGeneratedEvent,
+  IAGenerationFailedEvent,
+  IAValidationFailedEvent,
+  AIAgentOutput,
+  UXSchema,
+  ValidationError,
+} from '@auto-engineer/information-architect';
 ```
 
-### 2. IA Generation
+### Commands
+
+| Command | CLI Alias | Description |
+|---------|-----------|-------------|
+| `GenerateIA` | `generate:ia` | Generate IA scheme from narrative model |
+
+### GenerateIACommand
 
-The plugin analyzes requirements and generates:
+```typescript
+type GenerateIACommand = Command<'GenerateIA', {
+  modelPath: string;
+  outputDir: string;
+  previousErrors?: string;
+}>;
+```
 
-- Complete site map and navigation structure
-- User personas and journey maps
-- Page specifications with component breakdowns
-- Data model requirements
-- API endpoint specifications
-- Technical requirements and constraints
+### processFlowsWithAI
 
-### 3. Architecture Review
+```typescript
+function processFlowsWithAI(
+  model: Model,
+  uxSchema: UXSchema,
+  existingSchema?: object,
+  atoms?: { name: string; props: { name: string; type: string }[] }[],
+  previousErrors?: string
+): Promise<AIAgentOutput>
+```
 
-Generated architecture includes:
+### validateCompositionReferences
 
-- Visual site map diagrams
-- User flow documentation
-- Component hierarchy specifications
-- Database schema recommendations
-- Integration requirements
+```typescript
+function validateCompositionReferences(
+  schema: unknown,
+  designSystemAtoms?: string[]
+): ValidationError[]
+```
 
-### 4. Development Guidance
+Returns errors when components reference non-existent dependencies.
 
-The IA serves as input for subsequent development phases:
+### ValidationError
 
-- Frontend scaffolding follows navigation structure
-- Server models implement data specifications
-- Component implementations follow IA component specs
-- User testing validates against defined user journeys
+```typescript
+interface ValidationError {
+  component: string;
+  type: 'molecule' | 'organism';
+  field: string;
+  invalidReferences: string[];
+  message: string;
+}
+```
 
-## Quality Assurance
+---
 
-The plugin ensures architecture through:
+## Architecture
 
-- Requirements Coverage: All stated requirements are addressed in the IA
-- User Experience Validation: Generated flows support identified user goals
-- Technical Feasibility: Architecture recommendations are technically sound
-- Scalability Considerations: Structure supports growth and feature expansion
-- Accessibility Standards: IA includes accessibility requirements and guidelines
+```
+src/
+├── index.ts
+├── ia-agent.ts
+├── types.ts
+├── auto-ux-schema.json
+└── commands/
+    └── generate-ia.ts
+```
 
-## Advanced Features
+The following diagram shows the generation flow:
+
+```mermaid
+flowchart TB
+    A[GenerateIA] --> B[Load Model]
+    B --> C[Flatten Client Specs]
+    C --> D[Extract Design System Atoms]
+    D --> E[Generate via AI]
+    E --> F[Validate Compositions]
+    F --> G{Valid?}
+    G -->|Yes| H[IAGeneratedEvent]
+    G -->|No| I[IAValidationFailedEvent]
+```
 
-### Iterative Refinement
+*Flow: Command loads model, processes specs, generates IA via AI, validates compositions.*
 
-- Analyzes feedback and refines architecture
-- Supports incremental requirement additions
-- Maintains architecture consistency across changes
-- Tracks requirement evolution and impact
+### Composition Rules
 
-### Multi-Platform Support
+- Atoms do NOT compose other atoms
+- Molecules compose ONLY atoms
+- Organisms compose atoms AND molecules (never other organisms)
+- Pages can reference organisms, molecules, and atoms
 
-- Generates platform-specific considerations
-- Addresses responsive design requirements
-- Includes mobile-first considerations
-- Plans for progressive web app features
+### Dependencies
 
-The Information Architect plugin transforms high-level business requirements into actionable development blueprints, ensuring that applications are built with clear structure, user experience, and technical soundness from the start.
+| Package | Usage |
+|---------|-------|
+| `@auto-engineer/ai-gateway` | AI text generation |
+| `@auto-engineer/message-bus` | Command/event infrastructure |
+| `@auto-engineer/narrative` | Model type definitions |
+| `fast-glob` | File pattern matching |

package/dist/src/commands/generate-ia.d.ts

@@ -1,7 +1,9 @@
 import { type Command, type Event } from '@auto-engineer/message-bus';
+import { type ValidationError } from '../index';
 export type GenerateIACommand = Command<'GenerateIA', {
     modelPath: string;
     outputDir: string;
+    previousErrors?: string;
 }>;
 export type IAGeneratedEvent = Event<'IAGenerated', {
     outputPath: string;
@@ -11,12 +13,18 @@ export type IAGenerationFailedEvent = Event<'IAGenerationFailed', {
     error: string;
     outputDir: string;
 }>;
-export type GenerateIAEvents = IAGeneratedEvent | IAGenerationFailedEvent;
+export type IAValidationFailedEvent = Event<'IAValidationFailed', {
+    errors: ValidationError[];
+    outputDir: string;
+    modelPath: string;
+}>;
+export type GenerateIAEvents = IAGeneratedEvent | IAGenerationFailedEvent | IAValidationFailedEvent;
 export declare const commandHandler: import("@auto-engineer/message-bus").UnifiedCommandHandler<Readonly<{
     type: "GenerateIA";
     data: Readonly<{
         modelPath: string;
         outputDir: string;
+        previousErrors?: string;
     }>;
     timestamp?: Date;
     requestId?: string;

package/dist/src/commands/generate-ia.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-ia.d.ts","sourceRoot":"","sources":["../../../src/commands/generate-ia.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,KAAK,EAAwB,MAAM,4BAA4B,CAAC;AAmB5F,MAAM,MAAM,iBAAiB,GAAG,OAAO,CACrC,YAAY,EACZ;IACE,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB,CACF,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,KAAK,CAClC,aAAa,EACb;IACE,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB,CACF,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,KAAK,CACzC,oBAAoB,EACpB;IACE,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB,CACF,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG,uBAAuB,CAAC;AAE1E,eAAO,MAAM,cAAc;;;mBAvBZ,MAAM;mBACN,MAAM;;;;;GAoDnB,CAAC;AAsKH,eAAe,cAAc,CAAC"}
+{"version":3,"file":"generate-ia.d.ts","sourceRoot":"","sources":["../../../src/commands/generate-ia.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,OAAO,EAAwB,KAAK,KAAK,EAAE,MAAM,4BAA4B,CAAC;AAG5F,OAAO,EAAsB,KAAK,eAAe,EAAiC,MAAM,UAAU,CAAC;AAanG,MAAM,MAAM,iBAAiB,GAAG,OAAO,CACrC,YAAY,EACZ;IACE,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CACF,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,KAAK,CAClC,aAAa,EACb;IACE,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB,CACF,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,KAAK,CACzC,oBAAoB,EACpB;IACE,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB,CACF,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,KAAK,CACzC,oBAAoB,EACpB;IACE,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB,CACF,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG,uBAAuB,GAAG,uBAAuB,CAAC;AAEpG,eAAO,MAAM,cAAc;;;mBAjCZ,MAAM;mBACN,MAAM;yBACA,MAAM;;;;;GAsEzB,CAAC;AA4LH,eAAe,cAAc,CAAC"}