@compilr-dev/factory 0.1.4 → 0.1.6

package/LICENSE

@@ -0,0 +1,108 @@
+Functional Source License, Version 1.1, MIT Future License
+
+Abbreviation: FSL-1.1-MIT
+
+Notice
+
+Copyright 2026 Carmelo Scozzola
+
+Terms and Conditions
+
+Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,23 +1,40 @@
 # @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
+      \|/
+    ╭══════════╮     ___  ___  _ __ ___  _ __ (_) |_ __
+    ║'  ▐▌  ▐▌ │    / __|/ _ \| '_ ` _ \| '_ \| | | '__|
+    ║          │   | (__| (_) | | | | | | |_) | | | |
+    ╰─═──────═─╯    \___|\___/|_| |_| |_| .__/|_|_|_|
+      \________\                        | | .dev
+                                        |_| factory
 ```
 
-The factory provides **5 tools** (via MetaToolsRegistry) and **1 skill**:
+> AI-driven application scaffolder — from declarative model to working full-stack MVP
 
-| 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 |
+[![npm version](https://img.shields.io/npm/v/@compilr-dev/factory.svg)](https://www.npmjs.com/package/@compilr-dev/factory)
+[![License: FSL-1.1-MIT](https://img.shields.io/badge/License-FSL--1.1--MIT-blue.svg)](https://fsl.software/)
+
+> [!WARNING]
+> This package is in beta. APIs may change between minor versions.
+
+## Overview
+
+The factory takes an **Application Model** — a declarative description of what an app is (entities, fields, relationships, layout, features, theme) — and generates a complete, working full-stack project. It provides tools and skills that let AI agents design and scaffold applications through conversation.
+
+## Features
+
+- **Application Model** — declarative schema for entities, fields, relationships, layout, theme
+- **Semantic Operations** — type-safe mutations (addEntity, updateField, addRelationship, etc.)
+- **Optimistic Locking** — revision counter prevents lost updates
+- **Auto-Inverse Relationships** — adding `belongsTo` auto-creates `hasMany` on target
+- **Cascading Operations** — renaming an entity updates all relationship targets
+- **Validation** — comprehensive model health checks with actionable error messages
+- **Toolkit Registry** — extensible generator system (React+Node built-in)
+- **5 Agent Tools** — model CRUD, validation, scaffolding, toolkit listing
+- **1 Skill** — guided scaffolding workflow for AI agents
+- **Full Color Palette** — auto-generates 50–950 Tailwind shades from single hex
+- **Implicit Timestamps** — `createdAt`/`updatedAt` on all entity records
 
 ## Installation
 
@@ -25,31 +42,28 @@ The factory provides **5 tools** (via MetaToolsRegistry) and **1 skill**:
 npm install @compilr-dev/factory
 ```
 
-Peer dependency: `@compilr-dev/sdk ^0.1.11`
+Peer dependency:
 
-## Usage
-
-```typescript
-import { createModelTools } from '@compilr-dev/factory';
-import type { PlatformContext } from '@compilr-dev/sdk';
+```bash
+npm install @compilr-dev/sdk
+```
 
-// Create the 3 model tools (get, update, validate)
-const tools = createModelTools({
-  context: platformContext, // PlatformContext with documents repo
-});
+## Quick Start
 
-// Or use individual utilities
+```typescript
 import {
   createDefaultModel,
-  createDefaultEntity,
   applyOperation,
   validateModel,
 } from '@compilr-dev/factory';
 
+// Define your application
 const model = createDefaultModel({
   identity: { name: 'Restaurant Manager', description: 'Manage reservations', version: '1.0.0' },
+  theme: { primaryColor: '#E65100' },
 });
 
+// Add entities through semantic operations
 const updated = applyOperation(model, {
   op: 'addEntity',
   entity: {
@@ -66,10 +80,34 @@ const updated = applyOperation(model, {
   },
 });
 
+// Validate
 const result = validateModel(updated);
 // { valid: true, errors: [] }
 ```
 
+### Agent Tools
+
+```typescript
+import { createModelTools, createFactoryTools } from '@compilr-dev/factory';
+import type { PlatformContext } from '@compilr-dev/sdk';
+
+// 3 model tools (get, update, validate)
+const modelTools = createModelTools({ context: platformContext });
+
+// 2 factory tools (scaffold, list-toolkits)
+const factoryTools = createFactoryTools({ context: platformContext });
+```
+
+## Agent Tools Reference
+
+| Tool | Purpose |
+|------|---------|
+| `app_model_get` | Scoped reads of the Application Model (summary, entities, identity, etc.) |
+| `app_model_update` | Semantic operations with optimistic locking |
+| `app_model_validate` | Check model health and get actionable errors |
+| `factory_scaffold` | Generate files from model + toolkit |
+| `factory_list_toolkits` | List available toolkits with descriptions |
+
 ## Application Model
 
 The model describes **what** an application is, independently of how it's built:
@@ -87,45 +125,86 @@ ApplicationModel
 
 ### Semantic Operations
 
-The model is never edited as raw JSON. All changes go through typed operations:
+All model changes go through typed operations — never raw JSON editing:
 
-**Entity:** addEntity, updateEntity, removeEntity, renameEntity, reorderEntities
-**Field:** addField, updateField, removeField, renameField
-**Relationship:** addRelationship, removeRelationship (with auto-inverse management)
-**Section:** updateIdentity, updateLayout, updateFeatures, updateTheme, updateTechStack
+| Category | Operations |
+|----------|------------|
+| **Entity** | addEntity, updateEntity, removeEntity, renameEntity, reorderEntities |
+| **Field** | addField, updateField, removeField, renameField |
+| **Relationship** | addRelationship, removeRelationship (with auto-inverse) |
+| **Section** | updateIdentity, updateLayout, updateFeatures, updateTheme, updateTechStack |
 
 Every operation follows: **READ → CHECK → APPLY → VALIDATE → WRITE**.
 
-### Key Features
+### Key Design Choices
 
 - **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
+- **Cascading renames** — renaming an entity updates all FK references
 - **Scoped reads** — `app_model_get({ scope: "summary" })` for lightweight overview
 
+## Toolkits
+
+### React + Node (`react-node`)
+
+Generates a complete full-stack application:
+
+| Category | Generated Files |
+|----------|----------------|
+| **Config** | package.json, vite.config.ts, tailwind.config.js, tsconfig.json, postcss.config.js |
+| **Server** | Express API with CRUD routes, in-memory data stores, seed data |
+| **Pages** | List (card + table views), Detail, Dashboard |
+| **Components** | Cards, Forms, SearchBar, ViewToggle, FilterBar, DarkModeToggle |
+| **Routing** | React Router with nested layouts |
+| **Shell** | Sidebar + header layout, responsive navigation |
+| **Static** | index.html, global CSS, favicon |
+
+**Highlights:**
+- `@tailwindcss/forms` plugin included
+- Full primary color palette (50–950 shades) auto-generated from theme
+- Implicit `createdAt`/`updatedAt` timestamps on all entities
+- Enum fields get filter bars on list pages
+- `belongsTo` relationships get populated API responses and form dropdowns
+- `hasMany` relationships shown as linked lists on detail pages
+- Deterministic seed data (8 items per entity with realistic values)
+
 ## 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 test -- --run      # Run 290 tests
 npm run typecheck      # Type-check without emitting
 ```
 
-## Implementation Status
+## Requirements
+
+- **Node.js** 18 or higher
+- **@compilr-dev/sdk** ^0.1.12 (peer dependency)
 
-| 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 |
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [@compilr-dev/sdk](https://www.npmjs.com/package/@compilr-dev/sdk) | Universal agent runtime |
+| [@compilr-dev/agents](https://www.npmjs.com/package/@compilr-dev/agents) | Multi-LLM agent library |
+| [@compilr-dev/agents-coding](https://www.npmjs.com/package/@compilr-dev/agents-coding) | Coding-specific tools and language analysis |
+| [@compilr-dev/cli](https://www.npmjs.com/package/@compilr-dev/cli) | AI-powered coding assistant for your terminal |
+
+## Links
+
+- [Website](https://compilr.dev)
+- [npm Package](https://www.npmjs.com/package/@compilr-dev/factory)
+- [Report Issues](https://github.com/compilr-dev/factory/issues)
 
 ## License
 
-MIT
+[FSL-1.1-MIT](https://fsl.software/) - See [LICENSE](LICENSE) for details. Converts to MIT after 2 years per version.
+
+---
+
+<p align="center">
+  <strong>Built with care by <a href="https://compilr.dev">compilr.dev</a></strong>
+</p>

package/dist/toolkits/react-node/api.js

@@ -69,6 +69,8 @@ function generateDataStore(model, entity) {
     for (const rel of belongsToRels(entity)) {
         typeFields.push(`  ${fkFieldName(rel)}: number;`);
     }
+    typeFields.push('  createdAt: string;');
+    typeFields.push('  updatedAt: string;');
     const seedData = generateSeedData(model, entity);
     return {
         path: `server/data/${fileName}.ts`,
@@ -91,8 +93,9 @@ export function getById(id: number): ${typeName}Record | undefined {
   return items.find((item) => item.id === id);
 }
 
-export function create(data: Omit<${typeName}Record, 'id'>): ${typeName}Record {
-  const item = { ...data, id: nextId++ };
+export function create(data: Omit<${typeName}Record, 'id' | 'createdAt' | 'updatedAt'>): ${typeName}Record {
+  const now = new Date().toISOString();
+  const item = { ...data, id: nextId++, createdAt: now, updatedAt: now };
   items.push(item);
   return item;
 }
@@ -100,7 +103,7 @@ export function create(data: Omit<${typeName}Record, 'id'>): ${typeName}Record {
 export function update(id: number, data: Partial<${typeName}Record>): ${typeName}Record | undefined {
   const index = items.findIndex((item) => item.id === id);
   if (index === -1) return undefined;
-  items[index] = { ...items[index], ...data, id };
+  items[index] = { ...items[index], ...data, id, updatedAt: new Date().toISOString() };
   return items[index];
 }
 

package/dist/toolkits/react-node/config.d.ts

@@ -7,3 +7,7 @@
 import type { ApplicationModel } from '../../model/types.js';
 import type { FactoryFile } from '../types.js';
 export declare function generateConfigFiles(model: ApplicationModel): FactoryFile[];
+declare function hexToHsl(hex: string): [number, number, number];
+declare function hslToHex(h: number, s: number, l: number): string;
+declare function generateColorShades(hex: string): string;
+export { hexToHsl, hslToHex, generateColorShades };

package/dist/toolkits/react-node/config.js

@@ -43,6 +43,7 @@ function generatePackageJson(appSlug) {
             cors: '^2.8.5',
             express: '^4.21.1',
             postcss: '^8.4.49',
+            '@tailwindcss/forms': '^0.5.9',
             tailwindcss: '^3.4.15',
             tsx: '^4.19.2',
             typescript: '^5.6.3',
@@ -71,18 +72,20 @@ export default defineConfig({
 function generateTailwindConfig(model) {
     return {
         path: 'tailwind.config.js',
-        content: `/** @type {import('tailwindcss').Config} */
+        content: `import forms from '@tailwindcss/forms';
+
+/** @type {import('tailwindcss').Config} */
 export default {
   content: ['./index.html', './src/**/*.{ts,tsx}'],
   darkMode: 'class',
   theme: {
     extend: {
       colors: {
-        primary: '${model.theme.primaryColor}',
+        primary: ${generateColorShades(model.theme.primaryColor)},
       },
     },
   },
-  plugins: [],
+  plugins: [forms],
 };
 `,
     };
@@ -106,6 +109,90 @@ function generateTsConfig() {
     };
     return { path: 'tsconfig.json', content: JSON.stringify(config, null, 2) + '\n' };
 }
+// =============================================================================
+// Color Shade Utilities
+// =============================================================================
+const SHADE_LIGHTNESS = {
+    '50': 97,
+    '100': 94,
+    '200': 86,
+    '300': 77,
+    '400': 66,
+    '500': 55,
+    '600': 44,
+    '700': 36,
+    '800': 27,
+    '900': 20,
+    '950': 14,
+};
+function hexToHsl(hex) {
+    const raw = hex.replace('#', '');
+    const r = parseInt(raw.substring(0, 2), 16) / 255;
+    const g = parseInt(raw.substring(2, 4), 16) / 255;
+    const b = parseInt(raw.substring(4, 6), 16) / 255;
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    const l = (max + min) / 2;
+    if (max === min)
+        return [0, 0, Math.round(l * 100)];
+    const d = max - min;
+    const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    let h = 0;
+    if (max === r)
+        h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
+    else if (max === g)
+        h = ((b - r) / d + 2) / 6;
+    else
+        h = ((r - g) / d + 4) / 6;
+    return [Math.round(h * 360), Math.round(s * 100), Math.round(l * 100)];
+}
+function hslToHex(h, s, l) {
+    const sN = s / 100;
+    const lN = l / 100;
+    const c = (1 - Math.abs(2 * lN - 1)) * sN;
+    const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+    const m = lN - c / 2;
+    let r = 0, g = 0, b = 0;
+    if (h < 60)
+        [r, g, b] = [c, x, 0];
+    else if (h < 120)
+        [r, g, b] = [x, c, 0];
+    else if (h < 180)
+        [r, g, b] = [0, c, x];
+    else if (h < 240)
+        [r, g, b] = [0, x, c];
+    else if (h < 300)
+        [r, g, b] = [x, 0, c];
+    else
+        [r, g, b] = [c, 0, x];
+    const toHex = (v) => Math.round((v + m) * 255)
+        .toString(16)
+        .padStart(2, '0');
+    return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+function generateColorShades(hex) {
+    const [h, s] = hexToHsl(hex);
+    const entries = [];
+    for (const [shade, lightness] of Object.entries(SHADE_LIGHTNESS)) {
+        entries.push(`          ${shade}: '${hslToHex(h, s, lightness)}',`);
+    }
+    // Find the shade closest to the original for DEFAULT
+    const [, , originalL] = hexToHsl(hex);
+    let closestShade = '500';
+    let closestDiff = Infinity;
+    for (const [shade, lightness] of Object.entries(SHADE_LIGHTNESS)) {
+        const diff = Math.abs(lightness - originalL);
+        if (diff < closestDiff) {
+            closestDiff = diff;
+            closestShade = shade;
+        }
+    }
+    const defaultHex = hslToHex(h, s, SHADE_LIGHTNESS[closestShade]);
+    entries.push(`          DEFAULT: '${defaultHex}',`);
+    return `{\n${entries.join('\n')}\n        }`;
+}
+// Export for testing
+export { hexToHsl, hslToHex, generateColorShades };
 function generatePostCssConfig() {
     return {
         path: 'postcss.config.js',

package/dist/toolkits/react-node/entity.js

@@ -253,6 +253,14 @@ export default function ${entity.name}Detail() {
 
       <dl className="grid grid-cols-1 gap-4 sm:grid-cols-2">
 ${fieldRows}
+          <div>
+            <dt className="text-sm font-medium text-gray-500 dark:text-gray-400">Created</dt>
+            <dd className="mt-1 text-gray-900 dark:text-white">{new Date(item.createdAt).toLocaleString()}</dd>
+          </div>
+          <div>
+            <dt className="text-sm font-medium text-gray-500 dark:text-gray-400">Last Updated</dt>
+            <dd className="mt-1 text-gray-900 dark:text-white">{new Date(item.updatedAt).toLocaleString()}</dd>
+          </div>
 ${relLinks}
       </dl>${hasManyRender}
     </div>

package/dist/toolkits/react-node/seed.js

@@ -136,6 +136,13 @@ export function generateSeedData(model, entity) {
             const targetCount = targetEntity ? SEED_COUNT : SEED_COUNT;
             lines.push(`    ${fk}: ${String((i % targetCount) + 1)},`);
         }
+        // Implicit timestamps (deterministic)
+        const createdDate = new Date('2025-06-01T10:00:00Z');
+        createdDate.setDate(createdDate.getDate() + i * 2);
+        const updatedDate = new Date(createdDate);
+        updatedDate.setDate(updatedDate.getDate() + i);
+        lines.push(`    createdAt: '${createdDate.toISOString()}',`);
+        lines.push(`    updatedAt: '${updatedDate.toISOString()}',`);
         lines.push('  },');
     }
     lines.push('];');

package/dist/toolkits/react-node/types-gen.js

@@ -26,6 +26,9 @@ function generateInterface(entity) {
         lines.push(`  ${fk}: number;`);
         lines.push(`  ${rel.target.charAt(0).toLowerCase() + rel.target.slice(1)}?: ${rel.target};`);
     }
+    // Implicit timestamps
+    lines.push('  createdAt: string;');
+    lines.push('  updatedAt: string;');
     lines.push('}');
     return lines.join('\n');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/factory",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "AI-driven application scaffolder for the compilr-dev ecosystem",
   "type": "module",
   "main": "dist/index.js",
@@ -37,7 +37,7 @@
     "typescript-eslint": "^8.18.1",
     "vitest": "^2.1.8"
   },
-  "license": "MIT",
+  "license": "FSL-1.1-MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/scozzola/compilr-dev-factory"