create-fullstack-scaffold 0.4.22 → 0.4.24

package/README.md

@@ -1,154 +1,281 @@
-# create-biomimic-app
+# create-fullstack-scaffold
 
-A full-stack React + Hono application template with TypeScript, demonstrating best practices for monorepo-style architecture with single-port development.
+[![npm version](https://img.shields.io/npm/v/create-fullstack-scaffold.svg)](https://www.npmjs.com/package/create-fullstack-scaffold)
 
-## Features
+Zero-config fullstack app generator with type-safe RPC, 15+ modules, and 8 production-ready presets. One command, zero `.env`, instant `npm run dev`.
 
-- **Frontend**: React with TypeScript, Vite
-- **Backend**: Hono with TypeScript
-- **Database**: SQLite with Drizzle ORM
-- **State Management**: Zustand
-- **Real-time**: WebSocket + SSE support
-- **Testing**: Vitest (unit + integration tests)
-- **Code Quality**: ESLint, Prettier, pre-commit hooks
-- **Type Safety**: End-to-end type safety with Hono RPC
+## Quick Start
 
-## Architecture
-
-```
-src/
-├── client/          # React frontend
-│   ├── components/  # UI components
-│   ├── stores/     # Zustand state management
-│   ├── services/    # API clients (apiClient)
-│   ├── hooks/      # Custom hooks
-│   ├── pages/      # Page components
-│   └── App.tsx
-├── server/          # Hono backend
-│   ├── module-todos/     # Todo module
-│   ├── module-chat/      # WebSocket chat module
-│   ├── module-notifications/ # SSE notifications module
-│   ├── core/             # Core services (runtime, realtime)
-│   ├── middleware/       # Express middleware
-│   ├── test-utils/       # Test utilities
-│   └── entries/          # Entry points (node.ts, cloudflare.ts)
-└── shared/              # Shared types
-    ├── core/             # Framework layer (ws-client, sse-client)
-    ├── modules/          # Business layer (chat, todos, notifications)
-    └── schemas/          # Unified exports
+```bash
+npx create-fullstack-scaffold@latest my-app
+cd my-app && npm install && npm run dev
 ```
 
-## Getting Started
+Open http://localhost:3010 — that's it. No `.env` required.
 
-### Installation
+## Tech Stack
 
-```bash
-npm install
-```
+React + Hono + Vite + Zustand + TypeScript + Ant Design + Zod
 
-### Development
+| Layer      | Technology           | Purpose                             |
+| ---------- | -------------------- | ----------------------------------- |
+| Frontend   | React 19 + Vite      | Client SPA with HMR                 |
+| Admin      | Ant Design 5         | Admin/merchant/tenant dashboards    |
+| Backend    | Hono (OpenAPI)       | Type-safe RPC server                |
+| State      | Zustand              | Client-side state management        |
+| Validation | Zod                  | Shared schemas, end-to-end          |
+| DB         | Drizzle ORM + SQLite | Pluggable data layer                |
+| Realtime   | WebSocket + SSE      | Built-in typed protocols            |
+| CLI        | Commander            | `biomimic` CLI for agent automation |
 
-```bash
-npm run dev
-```
+## Presets
 
-The application will be available at http://localhost:3010
+8 presets. Each generates a different app by including/excluding modules.
 
-### Build
+| Preset                 | Modules                                                                                                                            | Use Case                     |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
+| `fullstack-admin`      | todos, chat, notifications, file, captcha, permission, admin, auth, plugin, tenant, order, ticket, dispute, content, merchant (15) | Full-featured admin platform |
+| `todo-app`             | todos, chat, notifications, auth (4)                                                                                               | Learning / simple app        |
+| `ecommerce`            | todos, chat, notifications, file, permission, order, ticket, dispute, content (9)                                                  | E-commerce store             |
+| `xbrowser-marketplace` | notifications, file, captcha, auth, permission, admin, plugin, order, ticket, dispute, content (11)                                | Plugin marketplace           |
+| `forum`                | content, auth, permission, admin, notifications (5)                                                                                | Community forum              |
+| `cli-only`             | todos, chat, notifications, auth (4)                                                                                               | CLI agent / no browser UI    |
+| `minimal`              | todos (1)                                                                                                                          | Bare minimum starting point  |
+| `saas`                 | todos, notifications, file, captcha, permission, auth, tenant, content (8)                                                         | Multi-tenant SaaS            |
 
 ```bash
-npm run build
+# Choose a preset
+npx create-fullstack-scaffold@latest my-app --preset ecommerce
 ```
 
-### Testing
+## Type-Safe RPC
 
-```bash
-# Run all tests
-npm test
+Every API call is fully typed — zero code generation, powered by Hono RPC.
+
+```typescript
+import { apiClient } from '@client/services/apiClient'
+
+// HTTP — typed request + response
+const res = await apiClient.api.todos.$get()
+const { data } = await res.json() // data: Todo[]
 
-# Run unit tests only
-npm run test:unit
+// WebSocket — typed RPC + events
+const ws = apiClient.api.chat.ws.$ws()
+const result = await ws.call('echo', { message: 'hello' })
 
-# Run integration tests only
-npm run test:integration
+// SSE — typed server-push
+const conn = await apiClient.api.notifications.stream.$sse()
+conn.on('notification', n => console.log(n.title))
+
+// Media — typed binary responses
+const blob = await apiClient.api.avatar[':id'].$image({ param: { id: '123' } })
+const svg = await apiClient.api.icon[':name'].$svg({ param: { name: 'home' } })
+const file = await apiClient.api.export.$download()
 ```
 
-## Key Concepts
+| Protocol      | Method                                     | Return Type           |
+| ------------- | ------------------------------------------ | --------------------- |
+| HTTP JSON     | `$get()`, `$post()`, `$put()`, `$delete()` | `ClientResponse<T>`   |
+| WebSocket     | `$ws()`                                    | `WSClient<Protocol>`  |
+| SSE           | `$sse()`                                   | `SSEClient<Protocol>` |
+| Image         | `$image()`                                 | `Promise<Blob>`       |
+| SVG           | `$svg()`                                   | `Promise<string>`     |
+| File Download | `$download()`                              | `Promise<Blob>`       |
 
-### Path Aliases
+## Architecture
 
-- `@shared/*` → src/shared/\*
-- `@client/*` → src/client/\*
-- `@server/*` → src/server/\*
+```
+┌─────────────────────────────────────────────────────────┐
+│                     Generated App                        │
+│                                                          │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
+│  │  Client   │  │  Admin   │  │  Tenant  │  │Merchant │ │
+│  │ (React)   │  │(Ant Design)│ │(Ant Design)│ │(Ant Design)│
+│  │ index.html│  │admin.html│  │tenant.html│  │merchant │ │
+│  └─────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬────┘ │
+│        │              │              │              │      │
+│        └──────────────┴──────────────┴──────────────┘      │
+│                              │                              │
+│                     apiClient (hc)                         │
+│                     type-safe RPC                          │
+│                              │                              │
+│  ┌───────────────────────────┴───────────────────────────┐ │
+│  │              Hono Server (Single Port)                  │ │
+│  │                                                         │ │
+│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────┐ │ │
+│  │  │module-  │ │module-  │ │module-  │ │module-      │ │ │
+│  │  │todos    │ │chat     │ │notifi-  │ │admin        │ │ │
+│  │  │         │ │         │ │cations  │ │             │ │ │
+│  │  │routes/  │ │routes/  │ │routes/  │ │routes/      │ │ │
+│  │  │services/│ │services/│ │services/│ │services/    │ │ │
+│  │  │__tests__/│ │__tests__/│ │__tests__/│ │__tests__/  │ │ │
+│  │  └─────────┘ └─────────┘ └─────────┘ └─────────────┘ │ │
+│  │  + 11 more modules (order, ticket, dispute, ...)      │ │
+│  └───────────────────────────────────────────────────────┘ │
+│                              │                              │
+│                     ┌────────┴────────┐                     │
+│                     │    Shared /     │                     │
+│                     │  core/ (Zod)    │                     │
+│                     │ modules/ (types)│                     │
+│                     └─────────────────┘                     │
+└─────────────────────────────────────────────────────────────┘
+```
 
-### Single-Port Development
+### Module System
 
-Uses "@hono/vite-dev-server" to run both frontend and backend on port 3010.
+15 modules with declarative manifests (`module.ts`). Each declares routes, dependencies, DB schemas, CLI commands, and pages.
 
-### Framework Layer vs Business Layer
+| Category      | Modules                                                              |
+| ------------- | -------------------------------------------------------------------- |
+| Core          | `todos`                                                              |
+| Communication | `chat`, `notifications`                                              |
+| System        | `permission`, `admin`, `auth`, `captcha`, `file`, `tenant`, `plugin` |
+| Business      | `order`, `ticket`, `dispute`, `content`, `merchant`                  |
 
-The project has clear separation between framework and business layers:
+### Multi-Entry HTML
 
-- **Framework Layer** (`src/shared/core/`): Generic, reusable infrastructure
-- **Business Layer** (`src/shared/modules/`): Business-specific schemas and protocols
+Up to 4 independent SPAs, generated based on preset modules:
 
-### Hono RPC
+| Entry    | File            | Included When                          |
+| -------- | --------------- | -------------------------------------- |
+| Client   | `index.html`    | Always                                 |
+| Admin    | `admin.html`    | `admin` or `permission` module present |
+| Tenant   | `tenant.html`   | `tenant` module present                |
+| Merchant | `merchant.html` | `merchant` module present              |
 
-Provides type-safe API calls from frontend to backend:
+Each entry has its own `App.tsx`, router, and layout — fully isolated.
 
-```typescript
-import { apiClient } from '@client/services/apiClient'
+### Module Dependency Graph
 
-// HTTP API
-const response = await apiClient.api.todos.$get()
-const result = await response.json()
+```
+todos ──── (standalone)
+chat ──── (standalone)
+notifications ──── (standalone)
+file ──── (standalone)
+captcha ──── (standalone)
+auth ──── (standalone)
+permission ──── (standalone, foundational)
+admin ────→ permission + notifications
+plugin ────→ auth + permission + notifications
+tenant ────→ auth + permission
+order ────→ permission
+ticket ────→ permission
+dispute ────→ permission
+content ────→ permission
+merchant ────→ auth + permission
+```
 
-// WebSocket
-const ws = apiClient.api.chat.ws.$ws()
-const result = await ws.call('echo', { message: 'hello' })
+## Deployment
 
-// SSE
-const conn = await apiClient.api.notifications.stream.$sse()
-conn.on('notification', n => console.log(n))
+| Platform               | Entry                              | Command                                                |
+| ---------------------- | ---------------------------------- | ------------------------------------------------------ |
+| **Cloudflare Workers** | `src/server/entries/cloudflare.ts` | `wrangler deploy`                                      |
+| **Node.js**            | `src/server/entries/node.ts`       | `node dist/server/entries/node.js`                     |
+| **shanbox**            | Dockerfile included                | `docker build -t app . && docker run -p 3010:3010 app` |
+
+```bash
+# Build for production
+npm run build
+
+# Preview production build
+npm run preview
 ```
 
-### Real-time Features
+## Development
 
-| Feature   | Method              | Type Safety | Testing          |
-| --------- | ------------------- | ----------- | ---------------- |
-| HTTP API  | `$get()`, `$post()` | ✅          | No server needed |
-| WebSocket | `$ws()`             | ✅          | Requires server  |
-| SSE       | `$sse()`            | ✅          | No server needed |
+```bash
+npm run dev            # Start dev server on :3010 (no .env needed)
+npm run build          # Production build
+npm run typecheck      # TypeScript type check
+npm run lint           # ESLint
+npm run test           # Vitest (all tests)
+npm run test:unit      # Unit tests only
+npm run test:integration  # Integration tests only
+npm run validate:modules   # Validate module manifests
+```
+
+## Project Structure
 
-### Module Structure
+```
+template/src/
+├── client/              # React SPA (index.html)
+│   ├── components/      # UI components
+│   ├── stores/          # Zustand state
+│   ├── services/        # apiClient
+│   ├── hooks/           # Custom hooks
+│   └── pages/           # Page components
+├── admin/               # Admin dashboard (admin.html, Ant Design)
+│   ├── components/
+│   ├── stores/
+│   ├── layouts/
+│   └── pages/
+├── tenant/              # Tenant dashboard (tenant.html, Ant Design)
+│   └── ...
+├── merchant/            # Merchant dashboard (merchant.html, Ant Design)
+│   └── ...
+├── server/              # Hono backend
+│   ├── module-{name}/   # Feature modules (15+)
+│   │   ├── module.ts    # Declarative manifest
+│   │   ├── routes/      # API endpoints
+│   │   ├── services/    # Business logic
+│   │   └── __tests__/   # Module tests
+│   ├── core/            # Runtime, realtime scanner
+│   ├── middleware/      # Auth, CORS, logger, captcha
+│   ├── db/              # Drizzle schema + migrations
+│   ├── entries/         # node.ts, cloudflare.ts
+│   └── test-utils/      # createTestClient, createTestServer
+├── shared/              # Shared types (client + server)
+│   ├── core/            # Framework: ws-client, sse-client, api-schemas
+│   ├── modules/         # Business: todos, chat, notifications, ...
+│   └── schemas/         # Unified re-exports
+└── cli/                 # CLI agent (biomimic command)
+    ├── modules/         # todo, notification, config, ...
+    └── rpc/             # hc RPC client
+```
 
-Backend is organized by feature modules:
+### Path Aliases
 
-- `module-todos/` - Todo CRUD
-- `module-chat/` - WebSocket chat
-- `module-notifications/` - SSE notifications
+| Alias       | Resolves To    |
+| ----------- | -------------- |
+| `@shared/*` | `src/shared/*` |
+| `@client/*` | `src/client/*` |
+| `@server/*` | `src/server/*` |
+| `@admin/*`  | `src/admin/*`  |
 
-Each module contains:
+## Testing
 
-- `routes/` - API endpoints
-- `services/` - Business logic
-- `__tests__/` - Unit tests
+```typescript
+import { createTestClient } from '@server/test-utils/test-client'
 
-## Pre-commit Hooks
+const client = createTestClient() // No server needed for HTTP/SSE
 
-The project uses Husky for Git hooks:
+const res = await client.api.todos.$get() // Fully typed
+const { data } = await res.json()
+```
 
-- **lint-staged** - Format staged files
-- **npm test** - Run test suite
-- **validate-all** - Custom validation script
+| Test Type | Needs Server | Tool                                           |
+| --------- | ------------ | ---------------------------------------------- |
+| HTTP API  | No           | `createTestClient()`                           |
+| SSE       | No           | `$sse()` via `createTestClient()`              |
+| WebSocket | Yes          | `createTestServer()` + `createTestClient(url)` |
+| E2E       | Yes          | Playwright                                     |
 
-## Environment Variables
+## Quality Gates
 
-See `.env.example` for required environment variables.
+- **TypeScript strict mode** — no `any`, explicit return types
+- **ESLint** — 17 custom rules (chain syntax, layer boundaries, no inline schemas, ...)
+- **Pre-commit hooks** — typecheck + lint-staged + smart tests
+- **Module validation** — `npm run validate:modules` checks manifests
+- **Production verified** — all 7 client presets pass `typecheck` + `build`
 
 ## Documentation
 
-- `QUICKSTART.md` - Quick start guide
-- `DESIGN.md` - Technical architecture
-- `CLAUDE.md` - Development guidelines
-- `.claude/rules/` - Detailed development constraints
+| File                 | Content                                   |
+| -------------------- | ----------------------------------------- |
+| `CLAUDE.md`          | Development guidelines for AI agents      |
+| `.claude/rules/`     | 20+ detailed development constraint files |
+| `template/CLAUDE.md` | Template-specific development guide       |
+
+## License
+
+MIT