archetype-engine 2.1.0 → 2.3.0

package/README.md

@@ -24,6 +24,9 @@ Run `npx archetype generate` → get:
 - ✅ **tRPC routers** (CRUD + pagination + filters)
 - ✅ **Zod validation** (runtime safety)
 - ✅ **React hooks** (useProduct, useCreateProduct, etc.)
+- ✅ **Vitest tests** (comprehensive test suites)
+- ✅ **OpenAPI docs** (Swagger UI + API docs)
+- ✅ **Seed data** (realistic sample data)
 
 ---
 
@@ -88,14 +91,25 @@ generated/
 │   │                          #   - update, updateMany
 │   │                          #   - remove, removeMany
 │   └── index.ts               # Router aggregation
-└── hooks/
-    └── useProduct.ts          # React Query hooks:
-                               #   - useProducts(), useProduct(id)
-                               #   - useCreateProduct(), useUpdateProduct()
-                               #   - useRemoveProduct(), etc.
+├── hooks/
+│   └── useProduct.ts          # React Query hooks:
+│                              #   - useProducts(), useProduct(id)
+│                              #   - useCreateProduct(), useUpdateProduct()
+│                              #   - useRemoveProduct(), etc.
+├── tests/                     # 🆕 Auto-generated tests
+│   ├── product.test.ts        #   - CRUD operation tests
+│   └── setup.ts               #   - Validation & auth tests
+├── docs/                      # 🆕 Auto-generated API docs
+│   ├── openapi.json           #   - OpenAPI 3.0 specification
+│   ├── swagger.html           #   - Interactive Swagger UI
+│   └── API.md                 #   - Markdown documentation
+└── seeds/                     # 🆕 Auto-generated seed data
+    ├── product.ts             #   - Realistic sample data
+    ├── index.ts               #   - Dependency management
+    └── run.ts                 #   - CLI seed script
 ```
 
-**15 lines of entity code → 400+ lines of production-ready backend.**
+**15 lines of entity code → 1,400+ lines of production-ready backend.**
 
 ### Live Example
 
@@ -148,6 +162,9 @@ No API boilerplate. No manual validation. No CRUD repetition. Just works.
 - 📊 **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
+- 🧪 **Auto-Generated Tests** - Comprehensive Vitest test suites with validation, auth, and CRUD tests
+- 📖 **Auto-Generated Docs** - OpenAPI 3.0 specs + interactive Swagger UI
+- 🌱 **Auto-Generated Seeds** - Realistic sample data with smart field mapping
 
 ## Use Cases
 
@@ -197,6 +214,72 @@ Archetype generates the **missing backend layer**:
 
 ---
 
+## CLI Commands
+
+Archetype provides a suite of commands organized by namespace to avoid conflicts with your Next.js project:
+
+### Archetype Commands (Code Generation & Documentation)
+
+```bash
+npx archetype init                 # Interactive setup with entity templates
+npx archetype generate             # Generate all code from entities
+npx archetype view                 # View ERD diagram in browser (port 3333)
+npx archetype docs                 # View OpenAPI/Swagger UI (port 3334)
+npx archetype validate             # Validate manifest without generating
+```
+
+### Project Scripts (Added by `npx archetype init`)
+
+New projects automatically get these npm scripts:
+
+```json
+{
+  "scripts": {
+    // Archetype - Generation & Docs
+    "archetype:generate": "archetype generate",
+    "archetype:view": "archetype view",
+    "archetype:docs": "archetype docs",
+    "archetype:check": "archetype validate",
+    
+    // Database - Schema & Data
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio",
+    "db:seed": "tsx generated/seeds/run.ts",
+    "db:seed:reset": "tsx generated/seeds/run.ts --reset",
+    
+    // Testing
+    "test:api": "vitest run generated/tests"
+  }
+}
+```
+
+### Common Workflows
+
+**Initial setup:**
+```bash
+npm run archetype:generate   # Generate code
+npm run db:push              # Create database schema
+npm run db:seed              # Add sample data
+npm run dev                  # Start dev server
+```
+
+**Development loop:**
+```bash
+# Edit archetype/entities/product.ts
+npm run archetype:generate   # Regenerate code
+npm run db:push              # Update schema
+npm run dev                  # Test changes
+```
+
+**Documentation & validation:**
+```bash
+npm run archetype:view       # View entity relationships
+npm run archetype:docs       # Browse API endpoints
+npm run archetype:check      # Validate entity definitions
+```
+
+---
+
 ## Roadmap
 
 - [x] Core entity system with relations
@@ -206,10 +289,14 @@ Archetype generates the **missing backend layer**:
 - [x] Batch operations (createMany, updateMany, removeMany)
 - [x] Computed fields
 - [x] Enum support
+- [x] Test generator (Vitest)
+- [x] API documentation generator (OpenAPI + Swagger)
+- [x] Seed data generator
+- [ ] E2E test generator (Playwright) (Q1 2026)
+- [ ] Admin UI generator (Q1 2026)
 - [ ] Multi-tenancy utilities (Q1 2026)
-- [ ] RBAC/permissions framework (Q1 2026)
-- [ ] Rate limiting (Q2 2026)
-- [ ] Admin UI generator (Q2 2026)
+- [ ] RBAC/permissions framework (Q2 2026)
+- [ ] GraphQL template (Q2 2026)
 
 ---
 

package/dist/src/cli.js

@@ -301,6 +301,89 @@ function buildHTML(mermaidCode) {
 </body>
 </html>`;
 }
+function serveOpenAPIDocs(port = 3334, maxAttempts = 10) {
+    // Check if generated/docs/openapi.json exists
+    const openapiPath = path.resolve('generated/docs/openapi.json');
+    if (!fs.existsSync(openapiPath)) {
+        console.error('OpenAPI spec not found at: generated/docs/openapi.json');
+        console.error('Run "npx archetype generate" first to generate API documentation');
+        process.exit(1);
+    }
+    const openapiSpec = fs.readFileSync(openapiPath, 'utf-8');
+    const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>API Documentation - Swagger UI</title>
+  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui.css" />
+  <style>
+    body { margin: 0; padding: 0; }
+  </style>
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  
+  <script src="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-bundle.js"></script>
+  <script src="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-standalone-preset.js"></script>
+  <script>
+    window.onload = function() {
+      window.ui = SwaggerUIBundle({
+        spec: ${openapiSpec},
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          SwaggerUIStandalonePreset
+        ],
+        plugins: [
+          SwaggerUIBundle.plugins.DownloadUrl
+        ],
+        layout: 'StandaloneLayout',
+        defaultModelsExpandDepth: 1,
+        defaultModelExpandDepth: 1,
+      });
+    };
+  </script>
+</body>
+</html>`;
+    const server = http.createServer((req, res) => {
+        // Serve OpenAPI JSON spec at /openapi.json
+        if (req.url === '/openapi.json') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(openapiSpec);
+        }
+        else {
+            // Serve Swagger UI HTML
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end(html);
+        }
+    });
+    server.on('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+            const nextPort = port + 1;
+            if (nextPort - 3334 < maxAttempts) {
+                console.log(`Port ${port} is in use, trying ${nextPort}...`);
+                serveOpenAPIDocs(nextPort, maxAttempts);
+            }
+            else {
+                console.error(`Could not find an available port (tried ${3334}-${port})`);
+                console.error('Try killing the process using the port:');
+                console.error(`  lsof -i :3334 | grep LISTEN | awk '{print $2}' | xargs kill -9`);
+                process.exit(1);
+            }
+        }
+        else {
+            console.error('Server error:', err.message);
+            process.exit(1);
+        }
+    });
+    server.listen(port, () => {
+        console.log(`http://localhost:${port}`);
+        console.log('Ctrl+C to stop');
+        openBrowser(`http://localhost:${port}`);
+    });
+}
 async function runGenerate(manifest) {
     // Determine template: CLI flag > config > error
     const templateId = templateOverride || manifest.template;
@@ -503,6 +586,10 @@ async function main() {
         const erd = (0, erd_ir_1.generateERDFromIR)(manifest);
         serveERD(erd);
     }
+    else if (command === 'docs') {
+        // Serve OpenAPI documentation
+        serveOpenAPIDocs();
+    }
     else if (command === 'init') {
         // Run the TUI init flow
         await (0, init_1.init)({ yes: yesFlag, headless: headlessFlag });
@@ -520,6 +607,7 @@ async function main() {
         console.log('  archetype generate [config]    - Generate code from entities');
         console.log('  archetype validate [config]    - Validate manifest without generating');
         console.log('  archetype view [config]        - View ERD diagram in browser');
+        console.log('  archetype docs                 - View OpenAPI/Swagger documentation in browser');
         console.log('  archetype mcp                  - Start MCP server (for Claude Desktop/Code)');
         console.log('');
         console.log('Flags:');

package/dist/src/init/dependencies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dependencies.d.ts","sourceRoot":"","sources":["../../../src/init/dependencies.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAA;AAC1D,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAA;AAC1C,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAA;AAE1E,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,QAAQ,CAAA;IACd,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,IAAI,EAAE,OAAO,CAAA;IACb,aAAa,CAAC,EAAE,YAAY,EAAE,CAAA;IAC9B,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;IACrB,eAAe,EAAE,OAAO,CAAA;IACxB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAGD,eAAO,MAAM,gBAAgB,UAS5B,CAAA;AAGD,eAAO,MAAM,mBAAmB,UAE/B,CAAA;AAGD,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAa5F,CAAA;AAGD,eAAO,MAAM,gBAAgB;;;CAG5B,CAAA;AAGD,eAAO,MAAM,oBAAoB,UAQhC,CAAA;AAGD,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAiCzF;AAGD,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,QAAiB,GAAG,UAAU,CAoB5F"}
+{"version":3,"file":"dependencies.d.ts","sourceRoot":"","sources":["../../../src/init/dependencies.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAA;AAC1D,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAA;AAC1C,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAA;AAE1E,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,QAAQ,CAAA;IACd,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,IAAI,EAAE,OAAO,CAAA;IACb,aAAa,CAAC,EAAE,YAAY,EAAE,CAAA;IAC9B,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;IACrB,eAAe,EAAE,OAAO,CAAA;IACxB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAGD,eAAO,MAAM,gBAAgB,UAS5B,CAAA;AAGD,eAAO,MAAM,mBAAmB,UAI/B,CAAA;AAGD,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAa5F,CAAA;AAGD,eAAO,MAAM,gBAAgB;;;CAG5B,CAAA;AAGD,eAAO,MAAM,oBAAoB,UAQhC,CAAA;AAGD,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAiCzF;AAGD,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,QAAiB,GAAG,UAAU,CAoB5F"}

package/dist/src/init/dependencies.js

@@ -18,6 +18,8 @@ exports.coreDependencies = [
 // Dev dependencies (always installed)
 exports.coreDevDependencies = [
     'drizzle-kit',
+    'tsx', // For running seed scripts
+    'vitest', // For running tests
 ];
 // Database-specific dependencies
 exports.databaseDependencies = {

package/dist/src/init/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/init/templates.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAI9D,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CA2G5D;AAGD,wBAAgB,qBAAqB,IAAI,MAAM,CAe9C;AAGD,wBAAgB,wBAAwB,IAAI,MAAM,CAejD;AAGD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CA2B5D;AAGD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAyGhE;AAGD,wBAAgB,qBAAqB,IAAI,MAAM,CAM9C;AAGD,wBAAgB,oBAAoB,IAAI,MAAM,CAyB7C;AAGD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAgC9D;AAGD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAsBvE;AAGD,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CA6E1D;AAGD,wBAAgB,oBAAoB,IAAI,MAAM,CAK7C;AAGD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAkChE;AAGD,wBAAgB,oBAAoB,IAAI,MAAM,CA6B7C;AAGD,wBAAgB,mBAAmB,IAAI,MAAM,CAgN5C;AAGD,wBAAgB,sBAAsB,IAAI,MAAM,CAyM/C;AAGD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,gBAAgB,GAAG,YAAY,EAAE,CAsFnG;AAGD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAahF"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/init/templates.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAI9D,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CA2G5D;AAGD,wBAAgB,qBAAqB,IAAI,MAAM,CAe9C;AAGD,wBAAgB,wBAAwB,IAAI,MAAM,CAejD;AAGD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CA2B5D;AAGD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAyGhE;AAGD,wBAAgB,qBAAqB,IAAI,MAAM,CAM9C;AAGD,wBAAgB,oBAAoB,IAAI,MAAM,CAyB7C;AAGD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAgC9D;AAGD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAsBvE;AAGD,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CA6E1D;AAGD,wBAAgB,oBAAoB,IAAI,MAAM,CAK7C;AAGD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAkChE;AAGD,wBAAgB,oBAAoB,IAAI,MAAM,CA6B7C;AAGD,wBAAgB,mBAAmB,IAAI,MAAM,CAyN5C;AAGD,wBAAgB,sBAAsB,IAAI,MAAM,CAyM/C;AAGD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,gBAAgB,GAAG,YAAY,EAAE,CAsFnG;AAGD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBhF"}

package/dist/src/init/templates.js

@@ -614,11 +614,20 @@ npm run db:push
 ## Available Commands
 
 \`\`\`bash
+# Archetype commands
 npm run archetype:generate   # Generate code from entities
-npm run archetype:view       # View ERD in browser
+npm run archetype:view       # View ERD diagram in browser
+npm run archetype:docs       # View API docs (Swagger UI)
+npm run archetype:check      # Validate manifest without generating
+
+# Database commands
 npm run db:push              # Push schema to database
-npm run db:studio            # Open Drizzle Studio
-npx archetype validate manifest.json --json  # Validate manifest
+npm run db:studio            # Open Drizzle Studio (database GUI)
+npm run db:seed              # Seed database with sample data
+npm run db:seed:reset        # Reset database and seed
+
+# Testing
+npm run test:api             # Run generated API tests
 \`\`\`
 
 ## Examples
@@ -851,20 +860,20 @@ When discussing code, use \`file:line\` format: \`archetype/entities/user.ts:12\
 
 ## Commands Reference
 \`\`\`bash
-# Generate code from entities
-npm run archetype:generate
-
-# View ERD diagram
-npm run archetype:view
-
-# Push schema to database (full mode)
-npm run db:push
+# Archetype - Generate & View
+npm run archetype:generate   # Generate code from entities
+npm run archetype:view       # View ERD diagram in browser
+npm run archetype:docs       # View API docs (Swagger UI)
+npm run archetype:check      # Validate manifest without generating
 
-# Open Drizzle Studio (full mode)
-npm run db:studio
+# Database (full mode only)
+npm run db:push              # Push schema to database
+npm run db:studio            # Open Drizzle Studio (database GUI)
+npm run db:seed              # Seed database with sample data
+npm run db:seed:reset        # Reset database and seed
 
-# Validate manifest
-npx archetype validate manifest.json --json
+# Testing
+npm run test:api             # Run generated API tests
 \`\`\`
 
 ## Examples
@@ -993,13 +1002,19 @@ function getAllTemplateFiles(config, structure) {
 // package.json scripts to add
 function getPackageJsonScripts(config) {
     const scripts = {
+        // Archetype - core commands
         'archetype:generate': 'archetype generate',
         'archetype:view': 'archetype view',
+        'archetype:docs': 'archetype docs',
+        'archetype:check': 'archetype validate',
     };
     // Only add database scripts for full mode
     if (config.mode === 'full') {
         scripts['db:push'] = 'drizzle-kit push';
         scripts['db:studio'] = 'drizzle-kit studio';
+        scripts['db:seed'] = 'tsx generated/seeds/run.ts';
+        scripts['db:seed:reset'] = 'tsx generated/seeds/run.ts --reset';
+        scripts['test:api'] = 'vitest run generated/tests';
     }
     return scripts;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archetype-engine",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Type-safe backend generator for Next.js. Define entities once, get Drizzle schemas, tRPC APIs, Zod validation, and React hooks instantly.",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",