archetype-engine 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Archetype Engine Contributors
+
+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

@@ -0,0 +1,241 @@
+<img width="1280" height="640" alt="image" src="https://github.com/user-attachments/assets/eb752f28-ae21-49e6-b0ff-8adc1f4c5cd5" />
+
+# Archetype Engine
+
+[![npm version](https://badge.fury.io/js/archetype-engine.svg)](https://www.npmjs.com/package/archetype-engine)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**The missing backend layer for AI-generated frontends.**
+
+Define entities in TypeScript. Get production-ready backends instantly.
+
+```typescript
+const Product = defineEntity('Product', {
+  fields: {
+    name: text().required().min(1).max(200),
+    price: number().required().positive(),
+    stock: number().integer().min(0).default(0),
+  }
+})
+```
+
+Run `npx archetype generate` → get:
+- ✅ **Drizzle ORM schemas** (type-safe database)
+- ✅ **tRPC routers** (CRUD + pagination + filters)
+- ✅ **Zod validation** (runtime safety)
+- ✅ **React hooks** (useProduct, useCreateProduct, etc.)
+
+---
+
+## Why use this?
+
+| Tool | What it does | What you still write |
+|------|--------------|---------------------|
+| Prisma | Database schema → Types | API, validation, hooks |
+| tRPC | Type-safe API | Schema, validation, CRUD |
+| Zod | Validation schemas | Database, API, hooks |
+| **Archetype** | **Schema → Everything** | Business logic only |
+
+You're not replacing tools—you're **generating** the boilerplate.
+
+---
+
+## Quick Start (2 minutes)
+
+```bash
+# 1. Create a new Next.js project
+npx create-next-app@latest my-app && cd my-app
+
+# 2. Install Archetype
+npm install archetype-engine
+
+# 3. Initialize with a template
+npx archetype init
+
+# Choose from:
+# - SaaS Multi-Tenant (Workspace, Team, Member)
+# - E-commerce (Product, Order, Customer)
+# - Blog/CMS (Post, Author, Comment)
+# - Task Management (Project, Task, Label)
+
+# 4. Generate code
+npx archetype generate
+
+# 5. Push to database and run
+npx drizzle-kit push
+npm run dev
+```
+
+**🎉 Done!** You now have a fully functional backend with type-safe APIs.
+
+---
+
+## What You Get
+
+From a single entity definition, Archetype generates:
+
+```
+generated/
+├── db/
+│   └── schema.ts              # Drizzle ORM tables (type-safe SQL)
+├── schemas/
+│   └── product.ts             # Zod validation schemas
+├── trpc/routers/
+│   ├── product.ts             # Full CRUD API:
+│   │                          #   - list (with pagination, filters, search)
+│   │                          #   - get (by ID)
+│   │                          #   - create, createMany
+│   │                          #   - update, updateMany
+│   │                          #   - remove, removeMany
+│   └── index.ts               # Router aggregation
+└── hooks/
+    └── useProduct.ts          # React Query hooks:
+                               #   - useProducts(), useProduct(id)
+                               #   - useCreateProduct(), useUpdateProduct()
+                               #   - useRemoveProduct(), etc.
+```
+
+**15 lines of entity code → 400+ lines of production-ready backend.**
+
+### Live Example
+
+**Define once:**
+```typescript
+const Order = defineEntity('Order', {
+  fields: {
+    orderNumber: text().required().unique(),
+    status: enumField(['pending', 'paid', 'shipped'] as const),
+    total: number().required().positive(),
+  },
+  relations: {
+    customer: hasOne('Customer'),
+    items: hasMany('OrderItem'),
+  },
+  behaviors: {
+    timestamps: true,
+  },
+  protected: 'all',  // Requires authentication
+})
+```
+
+**Use immediately:**
+```typescript
+// In your React component
+const { data: orders } = useOrders({ 
+  where: { status: 'pending' },
+  orderBy: { field: 'createdAt', direction: 'desc' }
+})
+
+const { mutate: createOrder } = useCreateOrder()
+createOrder({ 
+  orderNumber: 'ORD-001',
+  status: 'pending',
+  total: 99.99 
+})
+```
+
+No API boilerplate. No manual validation. No CRUD repetition. Just works.
+
+---
+
+## Features
+
+- 🎯 **Type-Safe Everything** - Database ↔ API ↔ Frontend sync guaranteed
+- 🚀 **Production-Ready Templates** - SaaS, E-commerce, Blog, Task Management
+- 🔐 **Built-in Auth** - NextAuth v5 integration with multiple providers
+- 🔍 **Smart Filtering** - Pagination, search, sorting out of the box
+- 🪝 **Lifecycle Hooks** - Add business logic before/after CRUD operations
+- 📊 **Auto ERD** - Visual database diagrams with `npx archetype view`
+- 🌍 **i18n Ready** - Multi-language support for generated code
+- ⚡ **Fast** - Generate 1000+ lines of code in seconds
+
+## Use Cases
+
+| Template | Perfect For | Entities Included |
+|----------|-------------|-------------------|
+| **SaaS Multi-Tenant** | Team collaboration apps | Workspace, Team, Member + roles |
+| **E-commerce** | Online stores, marketplaces | Product, Customer, Order, OrderItem |
+| **Blog/CMS** | Content platforms, news sites | Post, Author, Comment |
+| **Task Management** | Todo apps, kanban boards | Project, Task, Label |
+
+## Documentation
+
+📚 **Full docs:** [archetype-engine.vercel.app](https://archetype-engine.vercel.app)
+
+**Popular guides:**
+- [Getting Started](https://archetype-engine.vercel.app/docs/getting-started) - 5-minute tutorial
+- [Fields & Validation](https://archetype-engine.vercel.app/docs/fields) - text(), number(), date(), etc.
+- [Relations](https://archetype-engine.vercel.app/docs/relations) - hasOne, hasMany, belongsToMany
+- [Authentication](https://archetype-engine.vercel.app/docs/authentication) - Protect routes & entities
+- [Filtering & Search](https://archetype-engine.vercel.app/docs/filtering) - Build admin panels
+- [Lifecycle Hooks](https://archetype-engine.vercel.app/docs/hooks) - Custom business logic
+- [AI Integration](https://archetype-engine.vercel.app/docs/ai-module) - Build AI app builders
+
+---
+
+## Why Archetype?
+
+### The Problem: AI Tools Generate Incomplete Backends
+
+Tools like **v0.dev**, **Bolt.new**, and **Cursor** generate beautiful UIs but:
+- ❌ Hardcoded mock data
+- ❌ No database integration
+- ❌ No type safety
+- ❌ No production-ready APIs
+
+You get a gorgeous frontend that doesn't connect to anything real.
+
+### The Solution: Archetype Completes the Stack
+
+Archetype generates the **missing backend layer**:
+- ✅ Real database schemas (Drizzle ORM)
+- ✅ Type-safe APIs (tRPC)
+- ✅ Runtime validation (Zod)
+- ✅ React hooks for data fetching
+
+**Use case:** Generate UI with v0 → Add backend with Archetype → Deploy to production.
+
+---
+
+## Roadmap
+
+- [x] Core entity system with relations
+- [x] Pagination, filtering, search
+- [x] Authentication integration (NextAuth v5)
+- [x] CRUD lifecycle hooks
+- [x] Batch operations (createMany, updateMany, removeMany)
+- [x] Computed fields
+- [x] Enum support
+- [ ] Multi-tenancy utilities (Q1 2026)
+- [ ] RBAC/permissions framework (Q1 2026)
+- [ ] Rate limiting (Q2 2026)
+- [ ] Admin UI generator (Q2 2026)
+
+---
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for:
+- Architecture overview
+- Development setup
+- How to add features
+- Testing guidelines
+
+---
+
+## License
+
+MIT - Use freely in commercial and open-source projects.
+
+---
+
+## Support
+
+- 📖 **Docs:** [archetype-engine.vercel.app](https://archetype-engine.vercel.app)
+- 🐛 **Issues:** [GitHub Issues](https://github.com/IFAKA/archetype-engine/issues)
+- 💬 **Discussions:** [GitHub Discussions](https://github.com/IFAKA/archetype-engine/discussions)
+- 🐦 **Updates:** Follow [@archetype_dev](https://twitter.com/archetype_dev)
+
+---
+
+**Built with ❤️ for developers tired of writing boilerplate.**

package/dist/src/ai/adapters/anthropic.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Anthropic Tool Use Adapter
+ *
+ * Converts tool definitions to Anthropic's tool use format.
+ *
+ * @module ai/adapters/anthropic
+ */
+import type { AnthropicTool, ManifestBuilder, ToolResult } from '../types';
+/**
+ * Get all tools in Anthropic format
+ */
+export declare function getAnthropicTools(): AnthropicTool[];
+/**
+ * Tool input parameters
+ */
+export interface ToolInput {
+    [key: string]: unknown;
+}
+/**
+ * Execute a tool call and return the result
+ * Reuses OpenAI execution logic since the interface is the same
+ */
+export declare function executeAnthropicTool(builder: ManifestBuilder, toolName: string, input: ToolInput): ToolResult;
+/**
+ * Create a handler for Anthropic tool calls
+ */
+export declare function createAnthropicHandler(builder: ManifestBuilder): {
+    tools: AnthropicTool[];
+    execute: (toolName: string, input: ToolInput) => ToolResult;
+};
+//# sourceMappingURL=anthropic.d.ts.map

package/dist/src/ai/adapters/anthropic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.d.ts","sourceRoot":"","sources":["../../../../src/ai/adapters/anthropic.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,UAAU,EAAkB,MAAM,UAAU,CAAA;AAkD1F;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,aAAa,EAAE,CAEnD;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,SAAS,GACf,UAAU,CAEZ;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,eAAe;;wBAGvC,MAAM,SAAS,SAAS;EAG/C"}

package/dist/src/ai/adapters/anthropic.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * Anthropic Tool Use Adapter
+ *
+ * Converts tool definitions to Anthropic's tool use format.
+ *
+ * @module ai/adapters/anthropic
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAnthropicTools = getAnthropicTools;
+exports.executeAnthropicTool = executeAnthropicTool;
+exports.createAnthropicHandler = createAnthropicHandler;
+const tools_1 = require("../tools");
+const openai_1 = require("./openai");
+/**
+ * Convert a tool definition to Anthropic format
+ */
+function toAnthropicSchema(def) {
+    const properties = {};
+    for (const [name, param] of Object.entries(def.parameters)) {
+        if (name.startsWith('['))
+            continue; // Skip placeholder properties
+        const prop = {
+            type: param.type,
+            description: param.description,
+        };
+        if (param.enum) {
+            prop.enum = param.enum;
+        }
+        if (param.type === 'array' && param.items) {
+            prop.items = {
+                type: param.items.type,
+                description: param.items.description,
+            };
+            if (param.items.enum) {
+                prop.items.enum = param.items.enum;
+            }
+        }
+        if (param.type === 'object' && param.properties) {
+            prop.additionalProperties = true;
+        }
+        properties[name] = prop;
+    }
+    return {
+        name: def.name,
+        description: def.description,
+        input_schema: {
+            type: 'object',
+            properties,
+            required: def.required,
+        },
+    };
+}
+/**
+ * Get all tools in Anthropic format
+ */
+function getAnthropicTools() {
+    return Object.values(tools_1.toolDefinitions).map(toAnthropicSchema);
+}
+/**
+ * Execute a tool call and return the result
+ * Reuses OpenAI execution logic since the interface is the same
+ */
+function executeAnthropicTool(builder, toolName, input) {
+    return (0, openai_1.executeOpenAITool)(builder, toolName, input);
+}
+/**
+ * Create a handler for Anthropic tool calls
+ */
+function createAnthropicHandler(builder) {
+    return {
+        tools: getAnthropicTools(),
+        execute: (toolName, input) => executeAnthropicTool(builder, toolName, input),
+    };
+}

package/dist/src/ai/adapters/openai.d.ts

@@ -0,0 +1,33 @@
+/**
+ * OpenAI Function Calling Adapter
+ *
+ * Converts tool definitions to OpenAI's function calling format.
+ *
+ * @module ai/adapters/openai
+ */
+import type { OpenAITool, ManifestBuilder, ToolResult } from '../types';
+/**
+ * Tool input parameters
+ */
+export interface ToolInput {
+    [key: string]: unknown;
+}
+/**
+ * Get all tools in OpenAI format
+ */
+export declare function getOpenAITools(): OpenAITool[];
+/**
+ * Execute a tool call and return the result
+ *
+ * Note: AI frameworks send untyped JSON. We trust the AI to provide correctly-shaped data
+ * and rely on runtime validation within the builder methods to catch errors.
+ */
+export declare function executeOpenAITool(builder: ManifestBuilder, functionName: string, args: ToolInput): ToolResult;
+/**
+ * Create a handler for OpenAI tool calls
+ */
+export declare function createOpenAIHandler(builder: ManifestBuilder): {
+    tools: OpenAITool[];
+    execute: (functionName: string, args: ToolInput) => ToolResult;
+};
+//# sourceMappingURL=openai.d.ts.map

package/dist/src/ai/adapters/openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../../../src/ai/adapters/openai.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAkB,MAAM,UAAU,CAAA;AAGvF;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAmDD;;GAEG;AACH,wBAAgB,cAAc,IAAI,UAAU,EAAE,CAE7C;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,SAAS,GACd,UAAU,CAkDZ;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe;;4BAGhC,MAAM,QAAQ,SAAS;EAGlD"}

package/dist/src/ai/adapters/openai.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * OpenAI Function Calling Adapter
+ *
+ * Converts tool definitions to OpenAI's function calling format.
+ *
+ * @module ai/adapters/openai
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOpenAITools = getOpenAITools;
+exports.executeOpenAITool = executeOpenAITool;
+exports.createOpenAIHandler = createOpenAIHandler;
+const tools_1 = require("../tools");
+/**
+ * Convert a tool definition to OpenAI format
+ */
+function toOpenAISchema(def) {
+    const properties = {};
+    for (const [name, param] of Object.entries(def.parameters)) {
+        if (name.startsWith('['))
+            continue; // Skip placeholder properties
+        const prop = {
+            type: param.type,
+            description: param.description,
+        };
+        if (param.enum) {
+            prop.enum = param.enum;
+        }
+        if (param.type === 'array' && param.items) {
+            prop.items = {
+                type: param.items.type,
+                description: param.items.description,
+            };
+            if (param.items.enum) {
+                prop.items.enum = param.items.enum;
+            }
+        }
+        if (param.type === 'object' && param.properties) {
+            prop.additionalProperties = true;
+        }
+        properties[name] = prop;
+    }
+    return {
+        type: 'function',
+        function: {
+            name: def.name,
+            description: def.description,
+            parameters: {
+                type: 'object',
+                properties,
+                required: def.required,
+            },
+        },
+    };
+}
+/**
+ * Get all tools in OpenAI format
+ */
+function getOpenAITools() {
+    return Object.values(tools_1.toolDefinitions).map(toOpenAISchema);
+}
+/**
+ * Execute a tool call and return the result
+ *
+ * Note: AI frameworks send untyped JSON. We trust the AI to provide correctly-shaped data
+ * and rely on runtime validation within the builder methods to catch errors.
+ */
+function executeOpenAITool(builder, functionName, args) {
+    switch (functionName) {
+        case 'add_entity':
+            // AI sends untyped JSON - type assertion required
+            return builder.addEntity(args);
+        case 'update_entity':
+            return builder.updateEntity(args);
+        case 'remove_entity':
+            return builder.removeEntity(args);
+        case 'set_database':
+            return builder.setDatabase(args);
+        case 'set_auth':
+            return builder.setAuth(args);
+        case 'validate': {
+            const result = builder.validate();
+            return {
+                success: result.valid,
+                message: result.valid
+                    ? 'Manifest is valid'
+                    : `Found ${result.errors.length} error(s)`,
+                data: result,
+                errors: result.errors.map(e => ({
+                    code: e.code,
+                    message: e.message,
+                    suggestion: e.suggestion,
+                })),
+            };
+        }
+        case 'generate':
+            // Note: This is async but we return a sync result for compatibility
+            // Caller should handle the promise
+            return {
+                success: true,
+                message: 'Generation started. Call builder.generate() to get files.',
+                data: { manifest: builder.toManifest() },
+            };
+        default:
+            return {
+                success: false,
+                message: `Unknown function: ${functionName}`,
+                errors: [{ code: 'UNKNOWN_FUNCTION', message: `Unknown function: ${functionName}` }],
+            };
+    }
+}
+/**
+ * Create a handler for OpenAI tool calls
+ */
+function createOpenAIHandler(builder) {
+    return {
+        tools: getOpenAITools(),
+        execute: (functionName, args) => executeOpenAITool(builder, functionName, args),
+    };
+}