@compilr-dev/factory 0.1.1

package/README.md

@@ -0,0 +1,131 @@
+# @compilr-dev/factory
+
+AI-driven application scaffolder for the compilr-dev ecosystem. Generates working full-stack MVPs from an Application Model — a declarative description of what an app is (entities, fields, relationships, layout, features).
+
+## Architecture
+
+```
+@compilr-dev/agents → @compilr-dev/sdk → @compilr-dev/factory → @compilr-dev/cli
+                                          ↑ peer dep on SDK
+```
+
+The factory provides **5 tools** (via MetaToolsRegistry) and **1 skill**:
+
+| Tool | Purpose |
+|------|---------|
+| `app_model_get` | Scoped reads of the Application Model |
+| `app_model_update` | Semantic operations (addEntity, updateField, etc.) |
+| `app_model_validate` | Check model health |
+| `factory_scaffold` | Generate files from model + toolkit |
+| `factory_list_toolkits` | List available toolkits |
+
+## Installation
+
+```bash
+npm install @compilr-dev/factory
+```
+
+Peer dependency: `@compilr-dev/sdk ^0.1.11`
+
+## Usage
+
+```typescript
+import { createModelTools } from '@compilr-dev/factory';
+import type { PlatformContext } from '@compilr-dev/sdk';
+
+// Create the 3 model tools (get, update, validate)
+const tools = createModelTools({
+  context: platformContext, // PlatformContext with documents repo
+});
+
+// Or use individual utilities
+import {
+  createDefaultModel,
+  createDefaultEntity,
+  applyOperation,
+  validateModel,
+} from '@compilr-dev/factory';
+
+const model = createDefaultModel({
+  identity: { name: 'Restaurant Manager', description: 'Manage reservations', version: '1.0.0' },
+});
+
+const updated = applyOperation(model, {
+  op: 'addEntity',
+  entity: {
+    name: 'Reservation',
+    pluralName: 'Reservations',
+    icon: '📅',
+    fields: [
+      { name: 'date', label: 'Date', type: 'date', required: true },
+      { name: 'partySize', label: 'Party Size', type: 'number', required: true },
+      { name: 'status', label: 'Status', type: 'enum', required: true, enumValues: ['pending', 'confirmed', 'cancelled'] },
+    ],
+    views: ['card', 'list', 'detail'],
+    relationships: [],
+  },
+});
+
+const result = validateModel(updated);
+// { valid: true, errors: [] }
+```
+
+## Application Model
+
+The model describes **what** an application is, independently of how it's built:
+
+```
+ApplicationModel
+├── identity        — name, description, version
+├── entities[]      — domain objects with fields, views, relationships
+├── layout          — shell type (sidebar-header | header-only)
+├── features        — boolean toggles (dashboard, auth, darkMode, etc.)
+├── theme           — primaryColor (#RRGGBB)
+├── techStack       — toolkit ID (e.g. 'react-node')
+└── meta            — revision, timestamps, factoryVersion
+```
+
+### Semantic Operations
+
+The model is never edited as raw JSON. All changes go through typed operations:
+
+**Entity:** addEntity, updateEntity, removeEntity, renameEntity, reorderEntities
+**Field:** addField, updateField, removeField, renameField
+**Relationship:** addRelationship, removeRelationship (with auto-inverse management)
+**Section:** updateIdentity, updateLayout, updateFeatures, updateTheme, updateTechStack
+
+Every operation follows: **READ → CHECK → APPLY → VALIDATE → WRITE**.
+
+### Key Features
+
+- **Name-based addressing** — `entity: "Reservation"`, not `entities[2]`
+- **Optimistic locking** — revision counter prevents lost updates
+- **Auto-inverse relationships** — adding `belongsTo` auto-adds `hasMany` on target
+- **Cascading operations** — renaming an entity updates all relationship targets
+- **Scoped reads** — `app_model_get({ scope: "summary" })` for lightweight overview
+
+## Development
+
+```bash
+npm run build          # Compile TypeScript
+npm run lint           # ESLint (strict, 0 errors required)
+npm run format:check   # Prettier check
+npm test -- --run      # Run 143 tests
+npm run typecheck      # Type-check without emitting
+```
+
+## Implementation Status
+
+| Phase | Status | Description |
+|-------|--------|-------------|
+| 1 | ✅ | Types, validation, naming, defaults |
+| 2 | ✅ | Model operations, persistence, 3 tools |
+| 3 | 🔲 | Factory infrastructure (toolkit registry, scaffold tool) |
+| 4 | 🔲 | React+Node toolkit (~37 file generators) |
+| 5 | 🔲 | Skill prompt (factory-scaffold) |
+| 6 | 🔲 | SDK integration (DocumentType extension) |
+| 7 | 🔲 | CLI integration |
+
+## License
+
+MIT

package/dist/factory/file-writer.d.ts

@@ -0,0 +1,11 @@
+/**
+ * File Writer
+ *
+ * Writes generated FactoryFile[] to disk, creating directories as needed.
+ */
+import type { FactoryFile } from '../toolkits/types.js';
+export interface WriteResult {
+    readonly written: number;
+    readonly paths: readonly string[];
+}
+export declare function writeFactoryFiles(files: readonly FactoryFile[], targetDir: string): Promise<WriteResult>;

package/dist/factory/file-writer.js

@@ -0,0 +1,21 @@
+/**
+ * File Writer
+ *
+ * Writes generated FactoryFile[] to disk, creating directories as needed.
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+export async function writeFactoryFiles(files, targetDir) {
+    const absDir = resolve(targetDir);
+    const writtenPaths = [];
+    for (const file of files) {
+        const absPath = join(absDir, file.path);
+        await mkdir(dirname(absPath), { recursive: true });
+        await writeFile(absPath, file.content, 'utf-8');
+        writtenPaths.push(file.path);
+    }
+    return {
+        written: writtenPaths.length,
+        paths: writtenPaths,
+    };
+}

package/dist/factory/list-toolkits-tool.d.ts

@@ -0,0 +1,12 @@
+/**
+ * factory_list_toolkits Tool
+ *
+ * Lists all registered toolkits with their descriptions.
+ */
+import type { Tool } from '@compilr-dev/agents';
+import type { ToolkitRegistry } from './registry.js';
+interface ListToolkitsInput {
+    _unused?: never;
+}
+export declare function createListToolkitsTool(registry: ToolkitRegistry): Tool<ListToolkitsInput>;
+export {};

package/dist/factory/list-toolkits-tool.js

@@ -0,0 +1,35 @@
+/**
+ * factory_list_toolkits Tool
+ *
+ * Lists all registered toolkits with their descriptions.
+ */
+import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/agents';
+export function createListToolkitsTool(registry) {
+    return defineTool({
+        name: 'factory_list_toolkits',
+        description: 'List all available factory toolkits. Each toolkit generates a different type of application (e.g. React+Node, Next.js, etc.).',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+        execute: () => {
+            try {
+                const toolkits = registry.list();
+                return Promise.resolve(createSuccessResult({
+                    count: toolkits.length,
+                    toolkits: toolkits.map((t) => ({
+                        id: t.id,
+                        name: t.name,
+                        description: t.description,
+                        requiredSections: t.requiredSections,
+                    })),
+                }));
+            }
+            catch (error) {
+                return Promise.resolve(createErrorResult(error instanceof Error ? error.message : String(error)));
+            }
+        },
+        readonly: true,
+    });
+}

package/dist/factory/registry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Toolkit Registry
+ *
+ * Manages registered FactoryToolkit implementations.
+ * Toolkits register themselves by ID and are looked up during scaffold.
+ */
+import type { FactoryToolkit } from '../toolkits/types.js';
+export declare class ToolkitRegistry {
+    private readonly toolkits;
+    register(toolkit: FactoryToolkit): void;
+    get(id: string): FactoryToolkit | undefined;
+    list(): FactoryToolkit[];
+    has(id: string): boolean;
+}
+export declare const defaultRegistry: ToolkitRegistry;

package/dist/factory/registry.js

@@ -0,0 +1,28 @@
+/**
+ * Toolkit Registry
+ *
+ * Manages registered FactoryToolkit implementations.
+ * Toolkits register themselves by ID and are looked up during scaffold.
+ */
+export class ToolkitRegistry {
+    toolkits = new Map();
+    register(toolkit) {
+        if (this.toolkits.has(toolkit.id)) {
+            throw new Error(`Toolkit "${toolkit.id}" is already registered`);
+        }
+        this.toolkits.set(toolkit.id, toolkit);
+    }
+    get(id) {
+        return this.toolkits.get(id);
+    }
+    list() {
+        return [...this.toolkits.values()];
+    }
+    has(id) {
+        return this.toolkits.has(id);
+    }
+}
+export const defaultRegistry = new ToolkitRegistry();
+// Register built-in toolkits
+import { reactNodeToolkit } from '../toolkits/react-node/index.js';
+defaultRegistry.register(reactNodeToolkit);

package/dist/factory/scaffold-tool.d.ts

@@ -0,0 +1,21 @@
+/**
+ * factory_scaffold Tool
+ *
+ * Reads the Application Model, validates it, generates files via the toolkit,
+ * and writes them to disk.
+ */
+import type { Tool } from '@compilr-dev/agents';
+import type { PlatformContext } from '@compilr-dev/sdk';
+import type { ToolkitRegistry } from './registry.js';
+export interface ScaffoldToolConfig {
+    readonly context: PlatformContext;
+    readonly cwd?: string;
+    readonly registry: ToolkitRegistry;
+}
+interface ScaffoldInput {
+    dry_run?: boolean;
+    output_dir?: string;
+    project_id?: number;
+}
+export declare function createScaffoldTool(config: ScaffoldToolConfig): Tool<ScaffoldInput>;
+export {};

package/dist/factory/scaffold-tool.js

@@ -0,0 +1,95 @@
+/**
+ * factory_scaffold Tool
+ *
+ * Reads the Application Model, validates it, generates files via the toolkit,
+ * and writes them to disk.
+ */
+import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/agents';
+import { ModelStore } from '../model/persistence.js';
+import { validateModel } from '../model/schema.js';
+import { writeFactoryFiles } from './file-writer.js';
+export function createScaffoldTool(config) {
+    return defineTool({
+        name: 'factory_scaffold',
+        description: 'Generate a full application from the Application Model. Reads the model, validates it, runs the toolkit generators, and writes files to disk. Use dry_run: true to preview without writing.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                dry_run: {
+                    type: 'boolean',
+                    description: 'Preview generated files without writing to disk. Default: false.',
+                },
+                output_dir: {
+                    type: 'string',
+                    description: 'Directory to write generated files. Defaults to current working directory.',
+                },
+                project_id: {
+                    type: 'number',
+                    description: 'Project ID. Uses active project if omitted.',
+                },
+            },
+            required: [],
+        },
+        execute: async (input) => {
+            try {
+                const projectId = input.project_id ?? config.context.currentProjectId;
+                if (!projectId) {
+                    return createErrorResult('No active project. Use project_create or project_get first.');
+                }
+                // 1. Read model
+                const store = new ModelStore({
+                    documents: config.context.documents,
+                    projectId,
+                });
+                const model = await store.get();
+                if (!model) {
+                    return createErrorResult('No Application Model found. Use app_model_update to build one first.');
+                }
+                // 2. Validate
+                const validation = validateModel(model);
+                if (!validation.valid) {
+                    const msgs = validation.errors.map((e) => `${e.path}: ${e.message}`).join('; ');
+                    return createErrorResult(`Model validation failed: ${msgs}`);
+                }
+                // 3. Look up toolkit
+                const toolkit = config.registry.get(model.techStack.toolkit);
+                if (!toolkit) {
+                    const available = config.registry
+                        .list()
+                        .map((t) => t.id)
+                        .join(', ');
+                    return createErrorResult(`Toolkit "${model.techStack.toolkit}" not found. Available: ${available || 'none'}`);
+                }
+                // 4. Generate
+                const result = toolkit.generate(model);
+                // 5. Write (unless dry_run)
+                if (!input.dry_run) {
+                    const targetDir = input.output_dir ?? config.cwd ?? process.cwd();
+                    await writeFactoryFiles(result.files, targetDir);
+                    // 6. Update generatedAt
+                    const updatedModel = {
+                        ...model,
+                        meta: {
+                            ...model.meta,
+                            generatedAt: new Date().toISOString(),
+                        },
+                    };
+                    await store.save(updatedModel);
+                }
+                return createSuccessResult({
+                    toolkit: result.toolkit,
+                    fileCount: result.files.length,
+                    files: result.files.map((f) => f.path),
+                    warnings: result.warnings,
+                    dryRun: input.dry_run ?? false,
+                    message: input.dry_run
+                        ? `Dry run: ${String(result.files.length)} files would be generated.`
+                        : `Generated ${String(result.files.length)} files using "${result.toolkit}" toolkit.`,
+                });
+            }
+            catch (error) {
+                return createErrorResult(error instanceof Error ? error.message : String(error));
+            }
+        },
+    });
+}

package/dist/factory/skill.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Factory Skill — Guided Model-First Scaffold
+ *
+ * The factory-scaffold skill guides the agent through:
+ * 1. Reading project context (PRD, architecture, existing docs)
+ * 2. Checking toolkit availability
+ * 3. Building the Application Model incrementally
+ * 4. Scaffolding the application
+ * 5. Post-generation verification
+ */
+import { type Skill } from '@compilr-dev/agents';
+export declare const factoryScaffoldSkill: Skill;
+/** All factory skills. */
+export declare const factorySkills: readonly Skill[];

package/dist/factory/skill.js

@@ -0,0 +1,146 @@
+/**
+ * Factory Skill — Guided Model-First Scaffold
+ *
+ * The factory-scaffold skill guides the agent through:
+ * 1. Reading project context (PRD, architecture, existing docs)
+ * 2. Checking toolkit availability
+ * 3. Building the Application Model incrementally
+ * 4. Scaffolding the application
+ * 5. Post-generation verification
+ */
+import { defineSkill } from '@compilr-dev/agents';
+export const factoryScaffoldSkill = defineSkill({
+    name: 'factory-scaffold',
+    description: 'Guide the user through building an Application Model and scaffolding a full-stack app',
+    tags: ['factory', 'scaffold', 'model'],
+    prompt: `You are in FACTORY SCAFFOLD MODE. Your goal is to build an Application Model from the user's project description and generate a working full-stack application.
+
+## Overview
+
+The factory system works in two phases:
+1. **Model Building** — You build an Application Model that describes WHAT the app is
+2. **Code Generation** — The factory toolkit deterministically generates code from the model
+
+You have access to these tools:
+- \`app_model_get\` — Read the current Application Model (or sections of it)
+- \`app_model_update\` — Apply semantic operations to the model (addEntity, updateField, etc.)
+- \`app_model_validate\` — Check model health and get error details
+- \`factory_scaffold\` — Generate code from the model using a toolkit
+- \`factory_list_toolkits\` — List available code generation toolkits
+
+## PHASE 1: Context Gathering
+
+Before building the model, understand the project:
+
+1. Check for existing context:
+   - Use \`project_document_get_by_type\` to look for PRD, architecture, and design docs
+   - Read any existing Application Model with \`app_model_get\`
+
+2. If NO model exists, gather requirements from the user:
+   - What is the app? (name, one-sentence description)
+   - Who uses it? What are the main things they manage? (→ entities)
+   - What information does each thing have? (→ fields)
+   - How do things relate to each other? (→ relationships)
+   - Any special features? (dashboard, dark mode, settings)
+
+3. If a model EXISTS, show a summary and ask what to change.
+
+## PHASE 2: Check Toolkit Availability
+
+Call \`factory_list_toolkits\` to see what's available.
+- If a suitable toolkit exists → proceed with automated generation
+- If no toolkit matches → inform the user and offer to build the model anyway (useful as a spec for manual implementation)
+
+## PHASE 3: Build the Application Model
+
+Build the model incrementally using \`app_model_update\`:
+
+### Step 1: Set Identity
+\`\`\`json
+{ "op": "updateIdentity", "updates": { "name": "App Name", "description": "..." } }
+\`\`\`
+
+### Step 2: Set Tech Stack
+\`\`\`json
+{ "op": "updateTechStack", "updates": { "toolkit": "react-node" } }
+\`\`\`
+
+### Step 3: Add Entities (one at a time)
+\`\`\`json
+{
+  "op": "addEntity",
+  "entity": {
+    "name": "Customer",
+    "pluralName": "Customers",
+    "icon": "👤",
+    "fields": [
+      { "name": "name", "label": "Name", "type": "string", "required": true },
+      { "name": "email", "label": "Email", "type": "string", "required": true }
+    ],
+    "views": ["list", "detail", "card"],
+    "relationships": []
+  }
+}
+\`\`\`
+
+### Step 4: Add Relationships (after all entities exist)
+\`\`\`json
+{ "op": "addRelationship", "entity": "Reservation", "relationship": { "type": "belongsTo", "target": "Customer" } }
+\`\`\`
+Note: The inverse hasMany is added automatically.
+
+### Step 5: Configure Features
+\`\`\`json
+{ "op": "updateFeatures", "updates": { "dashboard": true, "darkMode": true } }
+\`\`\`
+
+### Step 6: Set Theme
+\`\`\`json
+{ "op": "updateTheme", "updates": { "primaryColor": "#1976D2" } }
+\`\`\`
+
+### Step 7: Set Layout
+\`\`\`json
+{ "op": "updateLayout", "updates": { "shell": "sidebar-header" } }
+\`\`\`
+
+### Step 8: Validate
+Call \`app_model_validate\` and fix any errors.
+
+## PHASE 4: Generate Code
+
+Once the model is valid:
+
+1. **Dry run first:**
+   Call \`factory_scaffold\` with \`{ "dry_run": true }\` to preview files.
+
+2. **Show the user** the file list and confirm they want to proceed.
+
+3. **Generate:**
+   Call \`factory_scaffold\` without dry_run to write files.
+
+## PHASE 5: Post-Generation
+
+After code generation:
+
+1. Tell the user what was generated (file count, structure)
+2. Suggest next steps:
+   - \`cd <project-dir> && npm install && npm run dev\`
+   - The app will be at http://localhost:5173
+   - API at http://localhost:3001
+3. Mention what can be customized (theme, features, adding entities)
+4. If backlog tools are available, offer to seed backlog with enhancement items
+
+## IMPORTANT RULES
+
+- **Never guess field types** — ask if unclear (e.g., is "status" a string or enum?)
+- **Entities use PascalCase** names (Customer, not customer)
+- **Fields use camelCase** names (firstName, not first_name)
+- **Always validate** before scaffolding
+- **Show progress** — after adding each entity, show a brief summary
+- **Relationships come last** — all entities must exist before adding relationships
+- **Use \`belongsTo\`** for the FK side — the inverse \`hasMany\` is automatic
+`,
+});
+/** All factory skills. */
+export const factorySkills = [factoryScaffoldSkill];

package/dist/factory/tools.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Factory Tools — Public API
+ *
+ * createFactoryTools() returns all 5 tools (3 model + 2 factory).
+ */
+import type { Tool } from '@compilr-dev/agents';
+import type { PlatformContext } from '@compilr-dev/sdk';
+import { ToolkitRegistry } from './registry.js';
+export interface FactoryConfig {
+    readonly context: PlatformContext;
+    readonly cwd?: string;
+    readonly registry?: ToolkitRegistry;
+}
+export declare function createFactoryTools(config: FactoryConfig): Tool<never>[];

package/dist/factory/tools.js

@@ -0,0 +1,17 @@
+/**
+ * Factory Tools — Public API
+ *
+ * createFactoryTools() returns all 5 tools (3 model + 2 factory).
+ */
+import { createModelTools } from '../model/tools.js';
+import { createScaffoldTool } from './scaffold-tool.js';
+import { createListToolkitsTool } from './list-toolkits-tool.js';
+import { defaultRegistry } from './registry.js';
+export function createFactoryTools(config) {
+    const registry = config.registry ?? defaultRegistry;
+    return [
+        ...createModelTools(config),
+        createScaffoldTool({ ...config, registry }),
+        createListToolkitsTool(registry),
+    ];
+}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @compilr-dev/factory
+ *
+ * AI-driven application scaffolder for the compilr-dev ecosystem.
+ */
+export type { ApplicationModel, Entity, Field, FieldType, View, Relationship, RelationshipType, Identity, Layout, ShellType, Features, Theme, TechStack, Meta, } from './model/types.js';
+export { validateModel } from './model/schema.js';
+export type { ValidationError, ValidationResult } from './model/schema.js';
+export { createDefaultModel, createDefaultEntity, createDefaultField } from './model/defaults.js';
+export { toPascalCase, toCamelCase, toKebabCase, toPlural, isPascalCase, isCamelCase, isValidHexColor, } from './model/naming.js';
+export type { FactoryFile, FactoryResult, FactoryToolkit } from './toolkits/types.js';
+export { ModelStore } from './model/persistence.js';
+export { applyOperation } from './model/operations.js';
+export type { ModelOperation } from './model/operations.js';
+export { createModelTools } from './model/tools.js';
+export { createFactoryTools } from './factory/tools.js';
+export type { FactoryConfig } from './factory/tools.js';
+export { ToolkitRegistry, defaultRegistry } from './factory/registry.js';
+export { writeFactoryFiles } from './factory/file-writer.js';
+export type { WriteResult } from './factory/file-writer.js';
+export { reactNodeToolkit } from './toolkits/react-node/index.js';
+export { factoryScaffoldSkill, factorySkills } from './factory/skill.js';

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * @compilr-dev/factory
+ *
+ * AI-driven application scaffolder for the compilr-dev ecosystem.
+ */
+// Validation
+export { validateModel } from './model/schema.js';
+// Defaults
+export { createDefaultModel, createDefaultEntity, createDefaultField } from './model/defaults.js';
+// Naming utilities
+export { toPascalCase, toCamelCase, toKebabCase, toPlural, isPascalCase, isCamelCase, isValidHexColor, } from './model/naming.js';
+// Model persistence (Phase 2)
+export { ModelStore } from './model/persistence.js';
+// Model operations (Phase 2)
+export { applyOperation } from './model/operations.js';
+// Model tools (Phase 2)
+export { createModelTools } from './model/tools.js';
+// Factory tools (Phase 3)
+export { createFactoryTools } from './factory/tools.js';
+export { ToolkitRegistry, defaultRegistry } from './factory/registry.js';
+export { writeFactoryFiles } from './factory/file-writer.js';
+// React+Node Toolkit (Phase 4)
+export { reactNodeToolkit } from './toolkits/react-node/index.js';
+// Factory skill (Phase 5)
+export { factoryScaffoldSkill, factorySkills } from './factory/skill.js';

package/dist/model/defaults.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Default Model Creators
+ *
+ * Factory functions for creating ApplicationModel and Entity instances
+ * with sensible defaults.
+ */
+import type { ApplicationModel, Entity, Field } from './types.js';
+export declare function createDefaultModel(overrides?: Partial<ApplicationModel>): ApplicationModel;
+export declare function createDefaultEntity(name: string, overrides?: Partial<Entity>): Entity;
+export declare function createDefaultField(name: string, label: string, overrides?: Partial<Field>): Field;