create-mantiq 0.7.2 → 0.7.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mantiq",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "Scaffold a new MantiqJS application",
   "type": "module",
   "license": "MIT",

package/skeleton/.claude/rules/conventions.md

@@ -0,0 +1,83 @@
+---
+description: MantiqJS framework conventions — loaded every session
+---
+
+# MantiqJS Conventions
+
+This is a MantiqJS project — a full-stack TypeScript web framework for Bun.
+
+## Critical Rules
+
+1. **Always use `override`** — `noImplicitOverride` is enabled. Every method that overrides a base class member MUST use the `override` keyword.
+
+2. **Use `make:*` generators** — never manually create models, controllers, migrations, etc. Run `bun mantiq make:model Post --migration` instead.
+
+3. **ESM only** — use `import`, never `require()`. Use `.ts` extensions in relative imports.
+
+4. **Bun runtime** — use `bun test`, `bun run`, Bun APIs. Not Node.js, not jest, not vitest.
+
+5. **Named exports** — controllers, models, middleware use named exports. Only migrations and seeders use `export default class`.
+
+## Base Class Signatures
+
+These are the most common mistakes. Get these right:
+
+```
+Factory.definition(index: number, fake: Faker)     — NOT (faker)
+Middleware.handle(request, next)                    — next() takes NO arguments
+Controller methods return Promise<Response>         — use MantiqResponse.json()
+Command.handle(args: ParsedArgs): Promise<number>   — return 0 for success
+FormRequest.rules(): Record<string, string>         — rule strings like 'required|email'
+```
+
+## File Placement
+
+```
+Controllers    → app/Http/Controllers/<Name>Controller.ts
+Models         → app/Models/<Name>.ts
+Middleware     → app/Http/Middleware/<Name>Middleware.ts
+Form Requests  → app/Http/Requests/<Action><Name>Request.ts
+Providers      → app/Providers/<Name>ServiceProvider.ts
+Commands       → app/Console/Commands/<Name>Command.ts
+Migrations     → database/migrations/<timestamp>_<name>.ts
+Factories      → database/factories/<Name>Factory.ts
+Seeders        → database/seeders/<Name>Seeder.ts
+Feature tests  → tests/feature/<name>.test.ts
+Unit tests     → tests/unit/<name>.test.ts
+Config         → config/<name>.ts
+Routes         → routes/web.ts, routes/api.ts
+```
+
+## Imports
+
+```typescript
+import type { MantiqRequest } from '@mantiq/core'
+import { MantiqResponse } from '@mantiq/core'
+import { Model } from '@mantiq/database'
+import { Migration } from '@mantiq/database'
+import type { SchemaBuilder } from '@mantiq/database'
+import { Factory } from '@mantiq/database'
+import type { Faker } from '@mantiq/database'
+import { FormRequest } from '@mantiq/validation'
+import { Command } from '@mantiq/cli'
+import type { ParsedArgs } from '@mantiq/cli'
+import { ServiceProvider } from '@mantiq/core'
+import type { Middleware, NextFunction } from '@mantiq/core'
+import { CacheManager } from '@mantiq/core'
+import { cache, config, env } from '@mantiq/core'
+import { TestCase } from '@mantiq/testing'
+```
+
+## Common Commands
+
+```bash
+bun mantiq make:model <Name> [--migration] [--factory] [--seed]
+bun mantiq make:controller <Name>
+bun mantiq make:middleware <Name>
+bun mantiq make:request <Name>
+bun mantiq migrate
+bun mantiq migrate:fresh
+bun mantiq route:list
+bun mantiq serve
+bun test tests/
+```

package/skeleton/.claude/rules/patterns.md

@@ -0,0 +1,112 @@
+---
+description: MantiqJS code patterns — routing, responses, validation, testing
+---
+
+# Code Patterns
+
+## Routing
+
+Route files export a default function:
+
+```typescript
+import type { Router } from '@mantiq/core'
+
+export default function (router: Router) {
+  router.get('/posts', [PostController, 'index'])
+  router.post('/posts', [PostController, 'store'])
+  router.get('/posts/:id', [PostController, 'show']).whereNumber('id')
+
+  router.group({ prefix: '/admin', middleware: ['auth'] }, (r) => {
+    r.resource('/users', UserController)
+  })
+}
+```
+
+## Responses
+
+```typescript
+return MantiqResponse.json({ data: users })          // 200
+return MantiqResponse.json({ data: post }, 201)       // 201 Created
+return MantiqResponse.noContent()                      // 204
+return MantiqResponse.redirect('/login')               // 302
+```
+
+## Validation Rules
+
+```typescript
+override rules(): Record<string, string> {
+  return {
+    name: 'required|string|max:255',
+    email: 'required|email|unique:users,email',
+    password: 'required|min:8|confirmed',
+    age: 'integer|min:18|max:120',
+  }
+}
+```
+
+## Service Container
+
+Use class keys, NOT strings:
+
+```typescript
+import { CacheManager } from '@mantiq/core'
+
+app.make(CacheManager)   // correct — use the class itself as key
+app.make('cache')         // WRONG — string keys will throw
+```
+
+Helper functions are available for common services:
+
+```typescript
+import { cache, config, env } from '@mantiq/core'
+
+await cache().get('key')           // CacheManager
+config('database.connection')       // ConfigRepository
+env('APP_KEY')                      // environment variable
+```
+
+## Config Files
+
+```typescript
+import { env } from '@mantiq/core'
+
+export default {
+  name: env('APP_NAME', 'MantiqJS'),
+  debug: env('APP_DEBUG', false),
+}
+```
+
+## Testing
+
+```typescript
+import { describe, test, expect } from 'bun:test'
+import { TestCase } from '@mantiq/testing'
+
+const t = new TestCase()
+t.refreshDatabase = true
+t.setup()
+
+describe('Posts', () => {
+  test('can list posts', async () => {
+    await t.client.initSession()
+    const res = await t.client.get('/api/posts')
+    res.assertOk()
+  })
+})
+```
+
+- Call `t.client.initSession()` before POST/PUT/DELETE (gets CSRF token)
+- Assertions: `assertOk()`, `assertCreated()`, `assertStatus(n)`, `assertJsonPath()`
+- Database: `assertDatabaseHas('table', { key: 'value' })`
+
+## Don'ts
+
+- Don't use `(faker)` for Factory.definition — it's `(index: number, fake: Faker)`
+- Don't pass arguments to `next()` in middleware — NextFunction takes none
+- Don't use string keys with container — use class keys
+- Don't use `require()` — ESM only
+- Don't use `fs.writeFileSync()` — use `Bun.write()`
+- Don't put controllers in `app/Controllers/` — they go in `app/Http/Controllers/`
+- Don't default export controllers or models — use named exports
+- Don't manually create migration files — use `bun mantiq make:migration`
+- Don't use jest or vitest — use `bun:test`

package/skeleton/.claude/skills/api.md

@@ -0,0 +1,91 @@
+---
+name: api
+description: Add a new API endpoint with controller, validation, and tests
+user_invocable: true
+---
+
+# Add API Endpoint
+
+Create a new API endpoint with proper controller, validation, and tests.
+
+## Arguments
+
+`<method> <path> [description]` — e.g., `POST /api/orders "Create a new order"`
+
+## Process
+
+### 1. Determine the Controller
+
+- If a matching controller exists (e.g., `OrderController` for `/api/orders`), add the method there
+- Otherwise, generate one: `bun mantiq make:controller <Name>Controller`
+
+### 2. Add Controller Method
+
+```typescript
+async methodName(request: MantiqRequest): Promise<Response> {
+  // Validate if needed
+  // Business logic
+  return MantiqResponse.json({ data: result })
+}
+```
+
+- Import `MantiqRequest` as type, `MantiqResponse` as value from `@mantiq/core`
+- Use appropriate status codes: 200 (get/update), 201 (create), 204 (delete)
+- For validation, create a FormRequest: `bun mantiq make:request <Name>Request`
+
+### 3. Add Route
+
+Edit `routes/api.ts`:
+
+```typescript
+router.get('/api/endpoint', [Controller, 'method'])
+// Or with middleware:
+router.post('/api/endpoint', [Controller, 'method']).middleware('auth')
+```
+
+- API routes should be prefixed with `/api/`
+- Protected endpoints need `auth` middleware
+- Use parameter constraints: `.whereNumber('id')`, `.whereAlpha('slug')`
+
+### 4. Add Validation (if mutating)
+
+For POST/PUT/PATCH endpoints, generate and fill a FormRequest:
+
+```bash
+bun mantiq make:request <Name>Request
+```
+
+```typescript
+override rules(): Record<string, string> {
+  return {
+    field: 'required|string|max:255',
+  }
+}
+```
+
+### 5. Add Tests
+
+Create or update a test file in `tests/feature/`:
+
+```typescript
+import { describe, test, expect } from 'bun:test'
+import { TestCase } from '@mantiq/testing'
+
+const t = new TestCase()
+t.setup()
+
+describe('Endpoint', () => {
+  test('returns expected response', async () => {
+    await t.client.initSession()
+    const res = await t.client.get('/api/endpoint')
+    res.assertOk()
+  })
+})
+```
+
+### 6. Verify
+
+```bash
+bun mantiq route:list
+bun test tests/feature/<name>.test.ts
+```

package/skeleton/.claude/skills/crud.md

@@ -0,0 +1,136 @@
+---
+name: crud
+description: Generate a complete CRUD — model, migration, controller, routes, form requests, factory, seeder, tests
+user_invocable: true
+---
+
+# Full CRUD Generator
+
+Generate all files needed for a complete resource CRUD.
+
+## Arguments
+
+`<ModelName>` — e.g., `Post`, `Article`, `Product`
+
+Optionally include fields: `Post title:string body:text published:boolean`
+
+## Process
+
+### 1. Generate Files Using CLI
+
+Run these commands in order:
+
+```bash
+bun mantiq make:model <Name> --migration --factory
+bun mantiq make:controller <Name>Controller --resource
+bun mantiq make:request Store<Name>Request
+bun mantiq make:request Update<Name>Request
+bun mantiq make:seeder <Name>Seeder
+bun mantiq make:test <Name>
+```
+
+### 2. Fill in the Migration
+
+Edit the generated migration file in `database/migrations/`. Add columns based on the provided fields (or sensible defaults):
+
+```typescript
+override async up(schema: SchemaBuilder): Promise<void> {
+  await schema.create('<table_name>', (t) => {
+    t.id()
+    // Add columns here based on the provided fields
+    t.timestamps()
+  })
+}
+```
+
+- Use `snake_case` plural for table names (`blog_posts`, not `BlogPosts`)
+- Always include `t.id()` and `t.timestamps()`
+- Add `t.softDeletes()` if the model should support soft deletion
+
+### 3. Fill in the Model
+
+Edit `app/Models/<Name>.ts`:
+
+```typescript
+import { Model } from '@mantiq/database'
+
+export class Post extends Model {
+  static override table = 'posts'
+  static override fillable = ['title', 'body', 'published']
+  static override casts = { published: 'boolean' }
+}
+```
+
+### 4. Fill in the Controller
+
+Edit `app/Http/Controllers/<Name>Controller.ts` with full CRUD methods:
+- `index` — list with pagination (`Model.paginate(page, perPage)`)
+- `store` — create (validate with `Store<Name>Request`, return 201)
+- `show` — find by ID (return 404 if not found)
+- `update` — update (validate with `Update<Name>Request`)
+- `destroy` — delete (return 204)
+
+Use `MantiqResponse.json()` for all responses.
+
+### 5. Fill in Form Requests
+
+`Store<Name>Request` — all required fields:
+```typescript
+override rules(): Record<string, string> {
+  return { title: 'required|string|max:255', body: 'required' }
+}
+```
+
+`Update<Name>Request` — same fields but optional where appropriate.
+
+### 6. Add Routes
+
+Add to `routes/api.ts`:
+```typescript
+router.group({ prefix: '/api', middleware: ['auth'] }, (r) => {
+  r.resource('/<plural_name>', <Name>Controller)
+})
+```
+
+Or for web routes with pages, add to `routes/web.ts`.
+
+### 7. Fill in Factory
+
+Edit `database/factories/<Name>Factory.ts`:
+```typescript
+override definition(index: number, fake: Faker): Record<string, any> {
+  return {
+    title: fake.sentence(),
+    body: fake.paragraph(),
+  }
+}
+```
+
+### 8. Fill in Seeder
+
+Edit `database/seeders/<Name>Seeder.ts` to use the factory:
+```typescript
+override async run(): Promise<void> {
+  await new <Name>Factory().count(10).create()
+}
+```
+
+### 9. Fill in Tests
+
+Edit `tests/feature/<name>.test.ts` with CRUD tests:
+- Can list resources
+- Can create with valid data
+- Cannot create with invalid data (422)
+- Can update
+- Can delete
+- Unauthenticated requests return 401
+
+### 10. Run Migration
+
+```bash
+bun mantiq migrate
+```
+
+### 11. Report
+
+Show a summary of all generated files and their locations.

package/skeleton/.claude/skills/debug.md

@@ -0,0 +1,71 @@
+---
+name: debug
+description: Framework-aware debugging — check routes, middleware, config, database, logs
+user_invocable: true
+---
+
+# Debug Helper
+
+Systematically diagnose issues in the MantiqJS application.
+
+## Arguments
+
+- No args: run full diagnostic
+- `routes`: check route registration
+- `db`: check database connection and migrations
+- `config`: check configuration
+
+## Step 1: Environment Check
+
+```bash
+cat .env | grep -E "APP_ENV|APP_DEBUG|APP_KEY|DB_CONNECTION|SESSION_DRIVER"
+```
+
+Verify:
+- `APP_KEY` is set (not empty)
+- `APP_DEBUG=true` for development
+- `DB_CONNECTION` matches available driver
+
+## Step 2: Route Check
+
+```bash
+bun mantiq route:list
+```
+
+- Verify the route in question is registered
+- Check middleware is correct (auth on protected routes, guest on login/register)
+- Check HTTP method matches (GET vs POST)
+
+## Step 3: Database Check
+
+```bash
+bun mantiq migrate:status
+```
+
+- Are all migrations ran?
+- If "pending", run `bun mantiq migrate`
+- Check if the SQLite file exists: `ls -la database/database.sqlite`
+
+## Step 4: Config Check
+
+Read the relevant config file in `config/`:
+- `config/app.ts` — app name, key, debug
+- `config/database.ts` — connection settings
+- `config/auth.ts` — guards, providers
+- `config/session.ts` — driver, lifetime, cookie name
+
+## Step 5: Server Boot Check
+
+```bash
+bun run index.ts &
+sleep 2
+curl -s http://localhost:3000/ -w "\nHTTP %{http_code}"
+curl -s http://localhost:3000/api/ping -w "\nHTTP %{http_code}"
+kill %1
+```
+
+Check for boot errors, port conflicts, 500 errors.
+
+## Report
+
+Summarize: what's working, what's broken, suggested fix with exact commands.

package/skeleton/.claude/skills/page.md

@@ -0,0 +1,92 @@
+---
+name: page
+description: Add a new frontend page with routing and navigation
+user_invocable: true
+---
+
+# Add Page
+
+Add a new frontend page with backend route and controller wiring.
+
+## Arguments
+
+`<PageName> [path]` — e.g., `Settings /settings`, `About /about`
+
+## Process
+
+### 1. Create the Controller Method
+
+Add a method to an existing controller or create a new one:
+
+```bash
+bun mantiq make:controller <Name>Controller
+```
+
+The controller method should return page data as JSON with `_page`:
+
+```typescript
+async settings(request: MantiqRequest): Promise<Response> {
+  return MantiqResponse.json({
+    _page: 'Settings',
+    _url: '/settings',
+    // page-specific data here
+  })
+}
+```
+
+### 2. Add the Route
+
+Edit `routes/web.ts`:
+
+```typescript
+router.get('/settings', [SettingsController, 'settings']).middleware('auth')
+```
+
+### 3. Create the Page Component
+
+Create the page file based on the project's frontend kit:
+
+**React** → `src/pages/Settings.tsx`:
+```tsx
+interface SettingsProps {
+  navigate: (href: string) => void
+  [key: string]: any
+}
+
+export default function Settings({ navigate }: SettingsProps) {
+  return (
+    <div>
+      <h1>Settings</h1>
+    </div>
+  )
+}
+```
+
+**Vue** → `src/pages/Settings.vue`
+**Svelte** → `src/pages/Settings.svelte`
+
+### 4. Register the Page
+
+Add the page to the page registry in the entry file:
+
+**React** → `src/main.tsx`:
+```typescript
+import Settings from './pages/Settings.tsx'
+// Add to pages object:
+const pages = { ..., Settings }
+```
+
+### 5. Add to SPA Router
+
+If the app uses client-side navigation, add the path to the SPA routes array in `src/App.tsx`:
+```typescript
+const spaRoutes = [..., '/settings']
+```
+
+### 6. Verify
+
+```bash
+bun mantiq route:list
+```
+
+Start the server and navigate to the new page.

package/skeleton/.claude/skills/test.md

@@ -0,0 +1,50 @@
+---
+name: test
+description: Run tests, typecheck, and report results
+user_invocable: true
+---
+
+# Test Runner
+
+Run the project test suite and report results clearly.
+
+## Arguments
+
+- No args: run all (typecheck + tests)
+- `unit`: run only unit tests
+- `feature`: run only feature tests
+- `typecheck`: run only typecheck
+- `<file>`: run a specific test file
+
+## Step 1: TypeScript Typecheck
+
+```bash
+npx tsc --noEmit
+```
+
+Report any type errors with file:line.
+
+## Step 2: Tests
+
+```bash
+bun test tests/
+```
+
+Or for specific suites:
+```bash
+bun test tests/unit/
+bun test tests/feature/
+bun test tests/feature/auth.test.ts
+```
+
+## Summary
+
+Report a table:
+
+| Check | Result |
+|-------|--------|
+| Typecheck | pass/fail (N errors) |
+| Unit tests | N pass, N fail |
+| Feature tests | N pass, N fail |
+
+If all pass, say "All green." If any failures, list them with file:line and error message.

package/src/templates.ts

@@ -47,6 +47,7 @@ export function getTemplates(ctx: TemplateContext): Record<string, string> {
   }
 
   const baseDevDeps: Record<string, string> = {
+    '@mantiq/agent-rules': '^0.7.0',
     '@mantiq/testing': '^0.7.0',
     'bun-types': 'latest',
     'typescript': '^5.7.0',

package/stubs/react/vite.config.ts.stub

@@ -1,7 +1,7 @@
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
 import tailwindcss from '@tailwindcss/vite'
-import { mantiq } from '@mantiq/vite'
+import { mantiq } from '@mantiq/vite/plugin'
 import path from 'path'
 import { writeFileSync, unlinkSync } from 'node:fs'