@totaland/create-starter-kit 1.0.0

package/README.md

@@ -0,0 +1,66 @@
+# create-starter-kit
+
+Scaffolding tool for creating new starter-kit projects.
+
+## Usage
+
+### Using pnpm create (recommended)
+
+```bash
+pnpm create starter-kit my-new-project
+```
+
+### Using pnpm dlx
+
+```bash
+pnpm dlx create-starter-kit my-new-project
+```
+
+### Using npx
+
+```bash
+npx create-starter-kit my-new-project
+```
+
+## What it does
+
+1. Creates a new directory with your project name
+2. Copies the entire starter-kit template
+3. Updates the `package.json` name field to match your project name
+4. Provides next steps for installation and running the project
+
+## Local Development
+
+To test this locally before publishing:
+
+1. Build the template:
+   ```bash
+   cd /path/to/starter-kit
+   ./scripts/sync-template.sh
+   ```
+
+2. Link the package globally:
+   ```bash
+   cd create-starter-kit
+   pnpm link --global
+   ```
+
+3. Test it:
+   ```bash
+   cd /tmp
+   pnpm create starter-kit test-project
+   ```
+
+## Publishing
+
+To publish to npm:
+
+```bash
+cd create-starter-kit
+pnpm publish
+```
+
+Once published, anyone can use:
+```bash
+pnpm create starter-kit my-project
+```

package/bin/index.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+import { copyFileSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Get the project name from command line arguments
+const projectName = process.argv[2];
+
+if (!projectName) {
+    console.error('Error: Please provide a project name');
+    console.log('Usage: pnpm create starter-kit <project-name>');
+    process.exit(1);
+}
+
+// Resolve paths
+const templateDir = resolve(__dirname, '../template');
+const targetDir = resolve(process.cwd(), projectName);
+
+console.log(`Creating new starter-kit project: ${projectName}`);
+console.log(`Target directory: ${targetDir}`);
+
+// Function to recursively copy directory
+function copyDir(src, dest) {
+    mkdirSync(dest, { recursive: true });
+
+    const entries = readdirSync(src, { withFileTypes: true });
+
+    for (const entry of entries) {
+        const srcPath = join(src, entry.name);
+        const destPath = join(dest, entry.name);
+
+        if (entry.isDirectory()) {
+            copyDir(srcPath, destPath);
+        } else {
+            copyFileSync(srcPath, destPath);
+        }
+    }
+}
+
+try {
+    // Copy template to target directory
+    copyDir(templateDir, targetDir);
+
+    // Update package.json with the new project name
+    const packageJsonPath = join(targetDir, 'package.json');
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+
+    packageJson.name = projectName;
+
+    writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
+
+    console.log('\n✅ Project created successfully!');
+    console.log('\nNext steps:');
+    console.log(`  cd ${projectName}`);
+    console.log('  pnpm install');
+    console.log('  pnpm dev');
+
+} catch (error) {
+    console.error('Error creating project:', error.message);
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@totaland/create-starter-kit",
+  "version": "1.0.0",
+  "description": "Scaffolding tool for creating new starter-kit projects",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "create-starter-kit": "./bin/index.js"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "keywords": [
+    "starter-kit",
+    "scaffold",
+    "template"
+  ],
+  "dependencies": {
+    "fast-glob": "^3.3.2"
+  }
+}

package/template/.env.example

@@ -0,0 +1,8 @@
+# Example .env file for Order System
+
+# Database (Optional - if not set, uses in-memory storage)
+# Uncomment to use PostgreSQL with Drizzle ORM
+# DATABASE_URL=postgres://user:password@localhost:5432/orders_db
+
+# Server Configuration
+PORT=3000

package/template/AGENTS.md

@@ -0,0 +1,23 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+TypeScript sources live in `src/`, with graph traversal logic under `src/graph/` (crawl policy, state hashing, trajectory storage) and telemetry helpers in `src/telemetry.ts`. Example entrypoints such as `src/demo.ts` show how agents orchestrate flows. Generated JavaScript lands in `build/` (never hand-edit). Documentation and design notes are under `docs/`, and replay artifacts persist to `storage/` while running crawls or demo scripts. Keep tests adjacent to the code (for example `src/graph/xstate.test.ts`).
+
+## Build, Test, and Development Commands
+- `pnpm install`: sets up dependencies for both the CLI and Playwright runtime.
+- `pnpm typecheck`: runs `tsc --noEmit` against `tsconfig.json` to catch type regressions early.
+- `pnpm build`: compiles `src/` to ESM output in `build/` via SWC; use `pnpm build:debug` when you need source maps.
+- `pnpm test`, `pnpm test:watch`, `pnpm test:ui`: execute the Vitest suite in batch, watch, or UI mode.
+- `pnpm knip`: detects unused files, exports, and dependencies—fix warnings before raising a PR.
+
+## Coding Style & Naming Conventions
+Follow the repository's Biome configuration (`biome.json`) and run `npx biome check .` if needed. Use 2-space indentation, TypeScript `strict` semantics, and ECMAScript modules (`import/export`). Exported symbols and files should read as actions or nouns (`discoverState`, `persist.ts`). Tests mirror the file under test (`xstate.test.ts`). Prefer descriptive async function names reflecting their side effects.
+
+## Testing Guidelines
+Vitest drives all unit and integration coverage. Name suites after the module (`describe("bfs")`) and isolate Playwright-heavy tests behind capability checks to keep CI fast. New behavior must include at least one test validating failure handling and a corresponding happy path. Run `pnpm test` locally before committing; `storage/` fixtures may be stubbed with lightweight mocks to avoid hitting real browsers.
+
+## Commit & Pull Request Guidelines
+Use imperative, conventional messages observed in history (`feat:`, `chore:`, `fix:`). One logical change per commit, referencing an issue ID when relevant. Pull requests should describe motivation, summarize testing (`pnpm test` output, screenshots for Playwright interactions), and link design docs in `docs/` if expanded. Request review from an owner when touching crawl policy or telemetry layers, and ensure CI (typecheck, build, tests) passes before assignment.
+
+## Environment & Configuration Tips
+Configure credentials through `.env` files consumed by Crawlee/Playwright—never hard-code tokens. For telemetry, set OpenTelemetry exporters via environment variables before running demos. Heavy crawls persist checkpoints to `storage/`; clean stale runs before committing to keep diffs focused.

package/template/ARCHITECTURE.md

@@ -0,0 +1,53 @@
+# Architecture Pattern Examples
+
+This starter kit demonstrates a blend of patterns from **"Designing Data-Intensive Applications"** and **"Patterns of Enterprise Application Architecture"**.
+
+## Order System Example
+
+### From Designing Data-Intensive Applications (DDIA):
+
+1. **Event Sourcing** - All state changes stored as immutable events
+   - `order.entity.ts`: Events are the source of truth
+   - Events: `OrderCreated`, `ItemAdded`, `OrderPlaced`
+
+2. **CQRS (Command Query Responsibility Segregation)**
+   - Commands: `commands.usecase.ts` - Write operations that generate events
+   - Queries: `queries.usecase.ts` - Read operations from materialized views
+
+3. **Materialized Views** - Denormalized data for fast queries
+   - `order.repository.impl.ts`: `readModel` maintains pre-computed summaries
+   - User index for O(1) lookups by user ID
+
+4. **Append-Only Log** - Event store never modifies existing data
+   - New events are appended, never updated or deleted
+
+### From Patterns of Enterprise Application Architecture (PEAA):
+
+1. **Repository Pattern** - Abstract data access
+   - `order.repository.ts`: Interface defining data operations
+   - Separates domain logic from persistence
+
+2. **Domain Model** - Rich business logic in entities
+   - `order.entity.ts`: Order entity with business rules and validation
+
+3. **Use Case / Service Layer** - Application logic orchestration
+   - Commands and queries as separate use cases
+   - Transaction boundaries and workflow management
+
+## API Endpoints
+
+```
+POST   /orders              # Create new order
+POST   /orders/:id/items    # Add item to order
+POST   /orders/:id/place    # Place order
+GET    /orders/:id          # Get order details
+GET    /orders/user/:userId # Get user's orders (fast via materialized view)
+GET    /orders/:id/events   # Get event stream (audit log)
+```
+
+## Key Benefits
+
+- **Scalability**: Read/write separation allows independent scaling
+- **Auditability**: Complete event history for compliance/debugging
+- **Performance**: Materialized views optimize common queries
+- **Maintainability**: Clean architecture with separated concerns

package/template/ORDER_SYSTEM.md

@@ -0,0 +1,93 @@
+# Order System with Drizzle ORM
+
+## Setup
+
+### 1. Environment Variables
+
+Create a `.env` file:
+
+```bash
+# Optional: PostgreSQL connection (if not set, uses in-memory)
+DATABASE_URL=postgres://user:password@localhost:5432/orders_db
+
+PORT=3000
+```
+
+### 2. Database Setup (Optional - for PostgreSQL)
+
+If you want to use PostgreSQL instead of in-memory storage:
+
+```bash
+# Generate migration
+pnpm drizzle-kit generate
+
+# Run migration
+pnpm drizzle-kit migrate
+
+# Or use push for development
+pnpm drizzle-kit push
+```
+
+### 3. Run the Server
+
+```bash
+# Development
+pnpm dev
+
+# Production
+pnpm build
+pnpm start
+```
+
+## API Endpoints
+
+Base URL: `http://localhost:3000/api`
+
+### Create Order
+```bash
+POST /api/orders
+Content-Type: application/json
+
+{
+  "userId": "550e8400-e29b-41d4-a716-446655440000"
+}
+```
+
+### Add Item to Order
+```bash
+POST /api/orders/:orderId/items
+Content-Type: application/json
+
+{
+  "productId": "660e8400-e29b-41d4-a716-446655440000",
+  "quantity": 2,
+  "price": 29.99
+}
+```
+
+### Place Order
+```bash
+POST /api/orders/:orderId/place
+```
+
+### Get Order Details
+```bash
+GET /api/orders/:orderId
+```
+
+### Get User's Orders (Fast - from materialized view)
+```bash
+GET /api/orders/user/:userId
+```
+
+### Get Order Event Stream (Audit log)
+```bash
+GET /api/orders/:orderId/events
+```
+
+## Architecture
+
+- **No DATABASE_URL**: Uses in-memory repository (for testing/demo)
+- **With DATABASE_URL**: Uses Drizzle ORM with PostgreSQL
+- Event Sourcing with materialized views for optimal read performance
+- CQRS pattern with separate command and query operations

package/template/biome.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["../biome.json"]
+}

package/template/drizzle.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'drizzle-kit';
+
+export default defineConfig({
+  schema: './src/infrastructure/database/schema.ts',
+  out: './drizzle',
+  dialect: 'postgresql',
+  dbCredentials: {
+    url: process.env.DATABASE_URL || 'postgres://localhost:5432/orders_db',
+  },
+});

package/template/knip.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://unpkg.com/knip@5/schema.json",
+  "ignoreExportsUsedInFile": {
+    "interface": true,
+    "type": true
+  },
+  "tags": [
+    "-lintignore"
+  ]
+}

package/template/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "ultimate-express-starter",
+  "version": "1.0.0",
+  "description": "Fast TypeScript backend starter kit with Ultimate Express, Scalar API docs, and Drizzle ORM.",
+  "type": "module",
+  "main": "build/index.js",
+  "scripts": {
+    "start": "node build/index.js",
+    "dev": "swc src -d build --strip-leading-paths --copy-files --watch & node --watch build/index.js",
+    "typecheck": "npx tsc --noEmit",
+    "build": "swc src -d build --strip-leading-paths --copy-files",
+    "build:debug": "swc src -d build --strip-leading-paths --copy-files --source-maps",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "prebuild": "rm -rf build",
+    "knip": "knip",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio"
+  },
+  "files": [
+    "build"
+  ],
+  "devDependencies": {
+    "@biomejs/biome": "2.0.6",
+    "@swc-node/register": "^1.11.1",
+    "@swc/cli": "0.7.7",
+    "@swc/core": "^1.10.1",
+    "@types/bun": "1.2.14",
+    "@types/cors": "^2.8.19",
+    "@types/node": "24.0.7",
+    "@vitest/ui": "^3.2.4",
+    "knip": "^5.69.1",
+    "tsx": "^4.20.6",
+    "typescript": "^5.8.3",
+    "vitest": "^4.0.10"
+  },
+  "dependencies": {
+    "@scalar/express-api-reference": "^0.8.25",
+    "cors": "^2.8.5",
+    "dotenv": "17.0.0",
+    "drizzle-kit": "^0.31.7",
+    "drizzle-orm": "^0.44.7",
+    "lru-cache": "^11.2.2",
+    "postgres": "^3.4.7",
+    "ultimate-express": "^2.0.12",
+    "ultimate-ws": "^2.0.6",
+    "zod": "^4.1.12"
+  },
+  "trustedDependencies": [
+    "@swc/core"
+  ]
+}

package/template/playwright.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from "@playwright/test";
+import { config as loadEnv } from "dotenv";
+
+// Load environment variables (e.g. PLAYWRIGHT_BASE_URL) before tests spin up.
+loadEnv();
+
+export default defineConfig({
+  testDir: "src/generated/tests",
+  reporter: [
+    ["line"],
+    ["html", { outputFolder: "playwright-report", open: "never" }],
+  ],
+  use: {
+    baseURL: process.env.PLAYWRIGHT_BASE_URL ?? "http://localhost:3000",
+  },
+});

package/template/pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+onlyBuiltDependencies:
+  - '@swc/core'
+  - esbuild

package/template/src/features/health/controller.ts

@@ -0,0 +1,5 @@
+import type { Request, Response } from 'ultimate-express';
+
+export const getHealth = (req: Request, res: Response) => {
+    res.json({ status: 'ok', timestamp: new Date().toISOString() });
+};

package/template/src/features/health/index.ts

@@ -0,0 +1,6 @@
+import { Router } from 'ultimate-express';
+import { getHealth } from './controller.js';
+
+export const healthRouter = Router();
+
+healthRouter.get('/', getHealth);

package/template/src/features/orders/controller.ts

@@ -0,0 +1,13 @@
+import type { Request, Response } from 'ultimate-express';
+
+export const getOrders = (req: Request, res: Response) => {
+    res.json([
+        { id: 1, item: 'Laptop', price: 1200 },
+        { id: 2, item: 'Mouse', price: 25 },
+    ]);
+};
+
+export const createOrder = (req: Request, res: Response) => {
+    const { item, price } = req.body;
+    res.status(201).json({ id: 3, item, price });
+};

package/template/src/features/orders/index.ts

@@ -0,0 +1,7 @@
+import { Router } from 'ultimate-express';
+import { createOrder, getOrders } from './controller.js';
+
+export const ordersRouter = Router();
+
+ordersRouter.get('/', getOrders);
+ordersRouter.post('/', createOrder);

package/template/src/index.ts

@@ -0,0 +1,76 @@
+// example backend with ultimate-express
+import 'dotenv/config';
+import express from 'ultimate-express';
+import type { Request, Response } from 'ultimate-express';
+import cors from 'cors';
+import { ordersRouter } from './features/orders/index.js';
+import { healthRouter } from './features/health/index.js';
+import { apiReference } from '@scalar/express-api-reference';
+
+const app = express();
+
+app.use(cors());
+app.use(express.json());
+
+app.get('/', (req: Request, res: Response) => {
+  res.send('Hello, Ultimate Express!');
+});
+
+// Mount feature routes
+app.use('/api/orders', ordersRouter);
+app.use('/api/health', healthRouter);
+
+// API Documentation with Scalar
+app.use(
+  '/api/docs',
+  apiReference({
+    spec: {
+      url: '/openapi.json',
+    },
+  }),
+);
+
+// Example OpenAPI spec endpoint
+app.get('/openapi.json', (req: Request, res: Response) => {
+  res.json({
+    openapi: '3.1.0',
+    info: {
+      title: 'Ultimate Express API',
+      version: '1.0.0',
+      description: 'API documentation for Ultimate Express starter kit',
+    },
+    servers: [
+      {
+        url: `http://localhost:${process.env.PORT || 3000}`,
+        description: 'Development server',
+      },
+    ],
+    paths: {
+      '/': {
+        get: {
+          summary: 'Hello endpoint',
+          description: 'Returns a greeting message',
+          responses: {
+            '200': {
+              description: 'Successful response',
+              content: {
+                'text/html': {
+                  schema: {
+                    type: 'string',
+                    example: 'Hello, Ultimate Express!',
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  });
+});
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Server is running on http://localhost:${PORT}`);
+  console.log(`API Documentation available at http://localhost:${PORT}/api/docs`);
+});

package/template/tsconfig.build.json

@@ -0,0 +1,10 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"noEmit": false,
+		"declaration": true,
+		"declarationMap": true,
+		"sourceMap": true
+	},
+	"exclude": ["node_modules", "build", "**/*.test.ts", "**/*.spec.ts"]
+}

package/template/tsconfig.json

@@ -0,0 +1,30 @@
+{
+	"compilerOptions": {
+		"outDir": "./build",
+		"rootDir": "./",
+		"esModuleInterop": true,
+		"forceConsistentCasingInFileNames": true,
+		"lib": ["ESNext", "DOM"],
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleDetection": "force",
+		"jsx": "react-jsx",
+		"allowJs": true,
+
+		// Node module resolution
+		"moduleResolution": "node",
+		"noEmit": true,
+
+		// Best practices
+		"strict": true,
+		"skipLibCheck": true,
+		"noFallthroughCasesInSwitch": true,
+
+		// Some stricter flags (disabled by default)
+		"noUnusedLocals": false,
+		"noUnusedParameters": false,
+		"noPropertyAccessFromIndexSignature": false
+	},
+	"include": ["src/**/*", "scripts/**/*"],
+	"exclude": ["node_modules, examples"]
+}

package/template/vitest.config.ts

@@ -0,0 +1,24 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.{test,spec}.{js,ts}', 'src/**/*.{test,spec}.{js,ts}'],
+    exclude: ['node_modules', 'build', 'src/generated/tests/**/*'],
+    coverage: {
+      reporter: ['text', 'json', 'html'],
+      exclude: [
+        'node_modules/',
+        'build/',
+        'tests/',
+        '*.config.*'
+      ]
+    }
+  },
+  resolve: {
+    alias: {
+      '@': '/src',
+    }
+  }
+});