@compilr-dev/factory 0.1.4 → 0.1.7

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

@@ -4,7 +4,7 @@
  * Generates: server/index.ts, server/routes/{entity}.ts, server/data/{entity}.ts
  */
 import { toCamelCase, toKebabCase } from '../../model/naming.js';
-import { tsType, fkFieldName, belongsToRels } from './helpers.js';
+import { tsType, fkFieldName, belongsToRels, hasManyRels } from './helpers.js';
 import { generateSeedData } from './seed.js';
 export function generateApiFiles(model) {
     return [
@@ -69,6 +69,25 @@ function generateDataStore(model, entity) {
     for (const rel of belongsToRels(entity)) {
         typeFields.push(`  ${fkFieldName(rel)}: number;`);
     }
+    typeFields.push('  createdAt: string;');
+    typeFields.push('  updatedAt: string;');
+    // Collect searchable fields (string + enum types)
+    const searchableFields = entity.fields
+        .filter((f) => f.type === 'string' || f.type === 'enum')
+        .map((f) => `item.${f.name}`);
+    const searchFilter = searchableFields.length > 0
+        ? `    const q = options.search.toLowerCase();
+    result = result.filter((item) =>
+      [${searchableFields.join(', ')}].some((v) =>
+        v !== undefined && String(v).toLowerCase().includes(q),
+      ),
+    );`
+        : `    const q = options.search.toLowerCase();
+    result = result.filter((item) =>
+      Object.values(item).some((v) =>
+        v !== undefined && String(v).toLowerCase().includes(q),
+      ),
+    );`;
     const seedData = generateSeedData(model, entity);
     return {
         path: `server/data/${fileName}.ts`,
@@ -78,6 +97,11 @@ export interface ${typeName}Record {
 ${typeFields.join('\n')}
 }
 
+export interface QueryOptions {
+  search?: string;
+  filters?: Record<string, string>;
+}
+
 ${seedData}
 
 let items: ${typeName}Record[] = [...${varName}SeedData];
@@ -91,8 +115,24 @@ 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 query(options: QueryOptions): { data: ${typeName}Record[]; total: number } {
+  let result = items;
+  if (options.search) {
+${searchFilter}
+  }
+  if (options.filters) {
+    for (const [field, value] of Object.entries(options.filters)) {
+      result = result.filter((item) =>
+        String((item as Record<string, unknown>)[field]) === value,
+      );
+    }
+  }
+  return { data: result, total: result.length };
+}
+
+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 +140,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];
 }
 
@@ -121,6 +161,7 @@ function generateRoutes(model, entity) {
     const varName = toCamelCase(entity.pluralName) + 'Router';
     const dataImport = fileName;
     const btoRels = belongsToRels(entity);
+    const hmRels = hasManyRels(entity);
     // Populate belongsTo entities
     const populateImports = btoRels
         .map((rel) => {
@@ -132,6 +173,17 @@ function generateRoutes(model, entity) {
     })
         .filter(Boolean)
         .join('\n');
+    // Aliased getAll imports for hasMany targets (used by ?include=)
+    const hasManyImports = hmRels
+        .map((rel) => {
+        const targetEntity = model.entities.find((e) => e.name === rel.target);
+        if (!targetEntity)
+            return '';
+        const targetFile = toKebabCase(targetEntity.pluralName).toLowerCase();
+        return `import { getAll as getAll${targetEntity.pluralName} } from '../data/${targetFile}.js';`;
+    })
+        .filter(Boolean)
+        .join('\n');
     const populateLogic = btoRels.length > 0
         ? `
 function populate(item: Record<string, unknown>): Record<string, unknown> {
@@ -148,30 +200,64 @@ ${btoRels
 `
         : '';
     const getListReturn = btoRels.length > 0
-        ? 'res.json(items.map((item) => populate(item as unknown as Record<string, unknown>)));'
-        : 'res.json(items);';
-    const getByIdReturn = btoRels.length > 0
-        ? 'res.json(populate(item as unknown as Record<string, unknown>));'
-        : 'res.json(item);';
+        ? 'res.json({ data: result.data.map((item) => populate(item as unknown as Record<string, unknown>)), total: result.total });'
+        : 'res.json({ data: result.data, total: result.total });';
+    // GET by ID with optional ?include= for hasMany
+    let getByIdBody;
+    if (hmRels.length > 0) {
+        const includeChecks = hmRels
+            .map((rel) => {
+            const targetEntity = model.entities.find((e) => e.name === rel.target);
+            if (!targetEntity)
+                return '';
+            const targetVar = toCamelCase(targetEntity.pluralName);
+            const fkRel = targetEntity.relationships.find((r) => r.type === 'belongsTo' && r.target === entity.name) ?? { type: 'belongsTo', target: entity.name };
+            const fk = fkFieldName(fkRel);
+            return `  if (include.includes('${targetVar}')) {
+    result.${targetVar} = getAll${targetEntity.pluralName}().filter((r) => r.${fk} === item.id);
+  }`;
+        })
+            .filter(Boolean)
+            .join('\n');
+        const populateExpr = btoRels.length > 0 ? 'populate(item as unknown as Record<string, unknown>)' : '{ ...item }';
+        getByIdBody = `  const item = getById(Number(req.params.id));
+  if (!item) return res.status(404).json({ error: 'Not found' });
+  const include = (req.query.include as string ?? '').split(',').filter(Boolean);
+  const result: Record<string, unknown> = ${populateExpr};
+${includeChecks}
+  res.json(result);`;
+    }
+    else {
+        const getByIdReturn = btoRels.length > 0
+            ? 'res.json(populate(item as unknown as Record<string, unknown>));'
+            : 'res.json(item);';
+        getByIdBody = `  const item = getById(Number(req.params.id));
+  if (!item) return res.status(404).json({ error: 'Not found' });
+  ${getByIdReturn}`;
+    }
     return {
         path: `server/routes/${fileName}.ts`,
         content: `import { Router } from 'express';
-import { getAll, getById, create, update, remove } from '../data/${dataImport}.js';
-${populateImports}
+import { getAll, getById, query, create, update, remove } from '../data/${dataImport}.js';
+${populateImports}${hasManyImports ? '\n' + hasManyImports : ''}
 
 export const ${varName} = Router();
 ${populateLogic}
 // GET all
-${varName}.get('/', (_req, res) => {
-  const items = getAll();
+${varName}.get('/', (req, res) => {
+  const search = req.query.search as string | undefined;
+  const filters: Record<string, string> = {};
+  for (const [key, value] of Object.entries(req.query)) {
+    const match = key.match(/^filter\\[(.+)\\]$/);
+    if (match && typeof value === 'string') filters[match[1]] = value;
+  }
+  const result = query({ search, filters });
   ${getListReturn}
 });
 
 // GET by ID
 ${varName}.get('/:id', (req, res) => {
-  const item = getById(Number(req.params.id));
-  if (!item) return res.status(404).json({ error: 'Not found' });
-  ${getByIdReturn}
+${getByIdBody}
 });
 
 // POST create

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

@@ -26,7 +26,12 @@ function generateListPage(model, entity) {
     const hasFilters = enumFields.length > 0;
     const tableHeaders = entity.fields
         .slice(0, 5)
-        .map((f) => `              <th className="px-4 py-2 text-left text-sm font-medium text-gray-500 dark:text-gray-400">${f.label}</th>`)
+        .map((f) => `              <th
+                className="cursor-pointer select-none px-4 py-2 text-left text-sm font-medium text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200"
+                onClick={() => handleSort('${f.name}')}
+              >
+                ${f.label}{sortField === '${f.name}' ? (sortDirection === 'asc' ? ' ↑' : ' ↓') : ''}
+              </th>`)
         .join('\n');
     const tableCells = entity.fields
         .slice(0, 5)
@@ -45,16 +50,27 @@ ${hasFilters ? `const filterOptions = [\n${filterDefs}\n];\n` : ''}
 export default function ${entity.name}List() {
   const [items, setItems] = useState<${entity.name}[]>([]);
   const [view, setView] = useState<'card' | 'list'>('card');
-  const [search, setSearch] = useState('');${hasFilters ? '\n  const [filters, setFilters] = useState<Record<string, string>>({});' : ''}
+  const [search, setSearch] = useState('');
+  const [sortField, setSortField] = useState<string>('');
+  const [sortDirection, setSortDirection] = useState<'asc' | 'desc'>('asc');${hasFilters ? '\n  const [filters, setFilters] = useState<Record<string, string>>({});' : ''}
 
   useEffect(() => {
     fetch('${api}')
       .then((r) => r.json())
-      .then((data: ${entity.name}[]) => setItems(data));
+      .then((res: { data: ${entity.name}[]; total: number }) => setItems(res.data));
   }, []);
 
   const onSearch = useCallback((q: string) => setSearch(q), []);
 
+  const handleSort = useCallback((field: string) => {
+    if (sortField === field) {
+      setSortDirection((d) => (d === 'asc' ? 'desc' : 'asc'));
+    } else {
+      setSortField(field);
+      setSortDirection('asc');
+    }
+  }, [sortField]);
+
   const filtered = items.filter((item) => {
     if (search) {
       const q = search.toLowerCase();
@@ -71,6 +87,14 @@ export default function ${entity.name}List() {
     return true;
   });
 
+  const sorted = [...filtered].sort((a, b) => {
+    if (!sortField) return 0;
+    const aVal = (a as Record<string, unknown>)[sortField];
+    const bVal = (b as Record<string, unknown>)[sortField];
+    const cmp = String(aVal ?? '').localeCompare(String(bVal ?? ''), undefined, { numeric: true });
+    return sortDirection === 'asc' ? cmp : -cmp;
+  });
+
   return (
     <div>
       <div className="mb-6 flex items-center justify-between">
@@ -93,7 +117,7 @@ export default function ${entity.name}List() {
 
       {view === 'card' ? (
         <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
-          {filtered.map((item) => (
+          {sorted.map((item) => (
             <${entity.name}Card key={item.id} item={item} />
           ))}
         </div>
@@ -105,7 +129,7 @@ ${tableHeaders}
             </tr>
           </thead>
           <tbody>
-            {filtered.map((item) => (
+            {sorted.map((item) => (
               <tr key={item.id} className="border-b border-gray-100 hover:bg-gray-50 dark:border-gray-800 dark:hover:bg-gray-800/50">
 ${tableCells}
                 <td className="px-4 py-2">
@@ -160,22 +184,44 @@ function generateDetailPage(model, entity) {
   const [${stateVar}, set${targetEntity.pluralName}] = useState<${rel.target}[]>([]);`;
     })
         .join('');
-    const hasManyFetches = hmRels
+    // Build ?include= param for hasMany targets
+    const includeTargets = hmRels
+        .map((rel) => {
+        const targetEntity = model.entities.find((e) => e.name === rel.target);
+        return targetEntity ? toCamelCase(targetEntity.pluralName) : '';
+    })
+        .filter(Boolean);
+    const includeParam = includeTargets.length > 0 ? `?include=${includeTargets.join(',')}` : '';
+    const hasManySetters = hmRels
         .map((rel) => {
         const targetEntity = model.entities.find((e) => e.name === rel.target);
         if (!targetEntity)
             return '';
-        const fetchApi = apiPath(targetEntity);
-        const fk = fkFieldName(targetEntity.relationships.find((r) => r.type === 'belongsTo' && r.target === entity.name) ?? {
-            type: 'belongsTo',
-            target: entity.name,
-        });
-        return `
-      fetch('${fetchApi}')
-        .then((r) => r.json())
-        .then((data: ${rel.target}[]) => set${targetEntity.pluralName}(data.filter((d) => d.${fk} === Number(id))));`;
+        const varName = toCamelCase(targetEntity.pluralName);
+        return `      set${targetEntity.pluralName}(data.${varName} ?? []);`;
     })
-        .join('');
+        .join('\n');
+    // Build the useEffect block
+    let useEffectBlock;
+    if (hmRels.length > 0) {
+        useEffectBlock =
+            '  useEffect(() => {\n' +
+                `    fetch(\`${api}/\${id as string}${includeParam}\`)\n` +
+                '      .then((r) => r.json())\n' +
+                '      .then((data: Record<string, unknown>) => {\n' +
+                `        setItem(data as unknown as ${entity.name});\n` +
+                hasManySetters +
+                '\n      });\n' +
+                '  }, [id]);';
+    }
+    else {
+        useEffectBlock =
+            '  useEffect(() => {\n' +
+                `    fetch(\`${api}/\${id as string}\`)\n` +
+                '      .then((r) => r.json())\n' +
+                `      .then((data: ${entity.name}) => setItem(data));\n` +
+                '  }, [id]);';
+    }
     const hasManyImports = hmRels.map((rel) => rel.target).join(', ');
     const hasManyTypeImport = hmRels.length > 0 ? `, ${hasManyImports}` : '';
     const hasManyRender = hmRels
@@ -217,11 +263,7 @@ export default function ${entity.name}Detail() {
   const navigate = useNavigate();
   const [item, setItem] = useState<${entity.name} | null>(null);${hasManySection}
 
-  useEffect(() => {
-    fetch(\`${api}/\${id as string}\`)
-      .then((r) => r.json())
-      .then((data: ${entity.name}) => setItem(data));${hasManyFetches}
-  }, [id]);
+${useEffectBlock}
 
   if (!item) return <div className="p-6">Loading...</div>;
 
@@ -253,6 +295,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>
@@ -322,7 +372,7 @@ function generateForm(model, entity) {
         if (!targetEntity)
             return '';
         const targetApi = apiPath(targetEntity);
-        return `    fetch('${targetApi}').then((r) => r.json()).then((d: ${rel.target}[]) => set${rel.target}Options(d));`;
+        return `    fetch('${targetApi}').then((r) => r.json()).then((res: { data: ${rel.target}[]; total: number }) => set${rel.target}Options(res.data));`;
     })
         .join('\n');
     const relTypeImports = btoRels.map((r) => r.target);

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

@@ -4,8 +4,34 @@
  * Generates src/types/index.ts with interfaces for each entity.
  */
 import { tsType, fkFieldName, belongsToRels } from './helpers.js';
+const SHARED_TYPES = `// --- Shared API Types ---
+
+export interface PaginatedResponse<T> {
+  data: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+  totalPages: number;
+}
+
+export interface ApiResponse<T> {
+  data: T;
+  error?: string;
+}
+
+export interface ApiListResponse<T> {
+  data: T[];
+  total: number;
+}
+
+export interface SortParams {
+  field: string;
+  direction: 'asc' | 'desc';
+}`;
 export function generateTypesFile(model) {
     const lines = ['// Auto-generated TypeScript types from Application Model', ''];
+    lines.push(SHARED_TYPES);
+    lines.push('');
     for (const entity of model.entities) {
         lines.push(generateInterface(entity));
         lines.push('');
@@ -26,6 +52,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.7",
   "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"