@kardoe/quickback 0.4.4 → 0.5.2

package/src/skill/SKILL.md

@@ -4,28 +4,17 @@ description: Quickback API engine documentation - use when working with Quickbac
 allowed-tools: Read, Grep, Glob
 ---
 
-# Quickback: The Universal API Engine for B2B SaaS
+# Quickback: Backend Compiler for Secure APIs
 
-Quickback gives you a **complete, secure, multi-tenant backend in minutes**.
+Quickback transforms declarative TypeScript definitions into secure, production-ready APIs. You define your database schema and security rules in a single file using Drizzle ORM — Quickback compiles them into a deployable backend with authentication, role-based permissions, tenant isolation, and field-level security.
 
-You define your data model and business rules in TypeScript, and Quickback compiles them into production-ready APIs with authentication, permissions, multi-tenancy, and audit logging—all enforced by **auditable, static code** you can read and verify.
+The output is standard TypeScript (Hono, Drizzle, Better Auth) running on your own infrastructure. Not a managed platform — real code you own and control.
 
-## Getting Started
+## How It Works
 
-**Always use the CLI to initialize new projects:**
-
-```bash
-# Install the CLI
-npm install -g @kardoe/quickback
-
-# Create a new project (scaffolds correct structure)
-quickback create cloudflare my-app
-
-# Or for other templates
-quickback create bun my-app
-```
-
-This creates the correct project structure with all configuration files.
+1. **Define** — Schema + security rules in TypeScript using `defineTable()`
+2. **Compile** — Quickback generates API routes, middleware, migrations, and RLS policies
+3. **Deploy** — Standard tooling to Cloudflare Workers, Supabase, or Neon
 
 ## Architecture
 
@@ -34,33 +23,48 @@ This creates the correct project structure with all configuration files.
 │  YOU DEFINE (in TypeScript)                             │
 │  • Drizzle schema (your data models)                    │
 │  • Security layers (Firewall, Access, Guards, Masking)  │
-│  • CRUD configuration                                   │
+│  • Views (column-level projections)                     │
 │  • Actions (your business operations)                   │
 ├─────────────────────────────────────────────────────────┤
-│  QUICKBACK COMPILES TO (Static, Signed, Auditable Code) │
+│  QUICKBACK COMPILES TO                                  │
 │  • Database migrations (via Drizzle)                    │
-│  • API route handlers (in a Hono project)               │
+│  • API route handlers (Hono)                            │
 │  • Typed client SDK for your frontend                   │
 │  • AI tool definitions                                  │
 │  • OpenAPI specification                                │
-│  • Compliance manifest                                  │
 └─────────────────────────────────────────────────────────┘
 ```
 
-## Security & Compliance Pillars
+## Four Security Layers
+
+Every API request passes through four layers in order:
+
+```
+Request → Firewall → Access → Guards → Database → Masking → Response
+```
 
-| Requirement | Quickback Solution |
-|---|---|
-| **Multi-tenant data isolation** | **Firewall** — Enforces multi-tenancy and ownership via compiled WHERE clauses |
-| **Role-based permissions** | **Access** — Declare required authentication status and roles, compiled into middleware |
-| **Protect sensitive fields** | **Guards** — Allow-lists for writable fields, enforced at compile time |
-| **Mask PII in responses** | **Masking** — Declarative PII masks compiled directly into API responses |
-| **Workflow state machines** | **Actions** — Typed state transitions with preconditions |
-| **AI-safe mutation boundaries** | **Actions** — Constrained, typed tools an AI can safely call |
+| Layer | Purpose | Failure |
+|-------|---------|---------|
+| **Firewall** | Tenant isolation via automatic WHERE clauses | 404 |
+| **Access** | Role-based CRUD permissions (deny by default) | 403 |
+| **Guards** | Field modification rules (protected/immutable fields) | 400 |
+| **Masking** | PII redaction for unauthorized viewers | — |
 
 ---
 
-# Project Configuration
+# Project Structure
+
+```
+my-app/
+├── quickback/
+│   ├── quickback.config.ts
+│   └── features/
+│       └── {feature-name}/
+│           ├── {table}.ts        # Schema + security (defineTable)
+│           ├── actions.ts        # Custom actions (optional)
+│           └── handlers/         # Action handlers (optional)
+└── ...
+```
 
 ## quickback.config.ts
 
@@ -86,7 +90,7 @@ Quickback automatically injects these fields into every table:
 - `createdAt`, `modifiedAt`, `deletedAt` (timestamps)
 - `createdBy`, `modifiedBy`, `deletedBy` (user IDs)
 
-Do NOT add these to your schema.ts files.
+**Do NOT add these to your schema files.** They are auto-injected by the compiler.
 
 ---
 
@@ -105,22 +109,29 @@ import { defineTable } from "@quickback/compiler";
 export const todos = sqliteTable("todos", {
   id: integer("id").primaryKey(),
   title: text("title").notNull(),
+  description: text("description"),
   completed: integer("completed", { mode: "boolean" }).default(false),
   userId: text("user_id").notNull(),
   organizationId: text("organization_id").notNull(),
 });
 
 export default defineTable(todos, {
-  crud: ["create", "read", "update", "delete"],
-
   firewall: {
-    organization: { column: "organizationId" },
-    owner: { column: "userId" },
+    organization: {},    // Auto-detects 'organizationId' column
+    owner: {},           // Auto-detects 'userId' column
+  },
+
+  crud: {
+    list: { access: { roles: ["member", "admin"] } },
+    get: { access: { roles: ["member", "admin"] } },
+    create: { access: { roles: ["member", "admin"] } },
+    update: { access: { roles: ["admin"] } },
+    delete: { access: { roles: ["admin"] }, mode: "soft" },
   },
 
   guards: {
-    createable: ["title", "completed"],
-    updatable: ["title", "completed"],
+    createable: ["title", "description", "completed"],
+    updatable: ["title", "description", "completed"],
   },
 
   masking: {
@@ -129,13 +140,25 @@ export default defineTable(todos, {
 });
 ```
 
+## Internal/Junction Tables (No API)
+
+Tables without a `defineTable()` default export get no API routes:
+
+```typescript
+// No default export = no API routes generated
+export const roomAmenities = sqliteTable('room_amenities', {
+  roomId: text('room_id').notNull(),
+  amenityId: text('amenity_id').notNull(),
+});
+```
+
 ---
 
 # Security Pillars
 
-## 1. Firewall - Data Isolation
+## 1. Firewall — Data Isolation
 
-Compiles WHERE clauses to isolate data by ownership.
+Compiles WHERE clauses to isolate data by ownership. Auto-detects column names.
 
 ```typescript
 firewall: {
@@ -147,6 +170,13 @@ firewall: {
 }
 ```
 
+### Auto-Detection
+
+Quickback finds columns by convention:
+- `organization` → looks for `organizationId` or `organization_id`
+- `owner` → looks for `userId` or `user_id`
+- `team` → looks for `teamId` or `team_id`
+
 ### Column Overrides
 
 ```typescript
@@ -158,9 +188,16 @@ firewall: {
 }
 ```
 
-## 2. Access - Permission Checks
+### Owner Modes
+
+| Mode | Behavior |
+|------|----------|
+| (default) | Strict — only own records |
+| `optional` | Own records + records with NULL owner (admin pattern) |
 
-Role-based and record-based access control.
+## 2. Access — Permission Checks
+
+Role-based and record-based access control. Deny by default.
 
 ```typescript
 crud: {
@@ -179,9 +216,28 @@ crud: {
 }
 ```
 
-**Record Conditions**: `equals`, `notEquals`, `in`, `notIn`, `greaterThan`, `lessThan`
+### Record Conditions
+
+| Operator | Example |
+|----------|---------|
+| `equals` | `{ status: { equals: 'active' } }` |
+| `notEquals` | `{ status: { notEquals: 'archived' } }` |
+| `in` | `{ status: { in: ['active', 'pending'] } }` |
+| `notIn` | `{ status: { notIn: ['deleted'] } }` |
+| `greaterThan` | `{ amount: { greaterThan: 0 } }` |
+| `lessThan` | `{ amount: { lessThan: 10000 } }` |
+
+### Context Variables
 
-## 3. Guards - Field Protection
+| Variable | Type | Description |
+|----------|------|-------------|
+| `$ctx.userId` | string | Current user's ID |
+| `$ctx.activeOrgId` | string | Active organization ID |
+| `$ctx.activeTeamId` | string \| null | Active team ID |
+| `$ctx.roles` | string[] | User's roles in active org |
+| `$ctx.isAnonymous` | boolean | Anonymous user flag |
+
+## 3. Guards — Field Protection
 
 Controls which fields can be modified.
 
@@ -190,16 +246,38 @@ guards: {
   createable: ['name', 'description'],     // Allowed on POST
   updatable: ['description'],              // Allowed on PATCH
   immutable: ['invoiceNumber'],            // Set once, never change
-  protected: { status: ['approve'] },      // Only via actions
+  protected: { status: ['approve'] },      // Only via named actions
 }
 ```
 
+**Compile-time validation**:
+- Field can't be in both `createable` and `protected`
+- Field can't be in both `updatable` and `immutable`
+- All referenced fields must exist in the schema
+
 **System-managed fields** (always protected):
-- `createdAt`, `createdBy` - Set on INSERT
-- `modifiedAt`, `modifiedBy` - Set on INSERT/UPDATE
-- `deletedAt`, `deletedBy` - Set on soft DELETE
+- `createdAt`, `createdBy` — Set on INSERT
+- `modifiedAt`, `modifiedBy` — Set on INSERT/UPDATE
+- `deletedAt`, `deletedBy` — Set on soft DELETE
+
+### PUT / Upsert
+
+PUT is only available when BOTH conditions are met:
+- `generateId: false` in database config
+- `guards: false` (disables field protection)
+
+```typescript
+export default defineTable(external_orders, {
+  guards: false,
+  crud: {
+    put: { access: { roles: ['sync-service'] } },
+    get: {},
+    list: {},
+  },
+});
+```
 
-## 4. Masking - Response Transformation
+## 4. Masking — PII Redaction
 
 ```typescript
 masking: {
@@ -214,41 +292,157 @@ masking: {
 }
 ```
 
-**Mask types**: `email`, `phone`, `ssn`, `creditCard`, `name`, `redact`, `custom`
+### Mask Types
+
+| Type | Output |
+|------|--------|
+| `email` | `p***@e****.com` |
+| `phone` | `***-***-4567` |
+| `ssn` | `***-**-6789` |
+| `creditCard` | `****-****-****-1234` |
+| `name` | `J*** D**` |
+| `redact` | `[REDACTED]` |
+| `custom` | Your function |
+
+### Auto-Detection
+
+The compiler warns if sensitive columns aren't explicitly configured:
+
+| Column Pattern | Default Mask |
+|---------------|-------------|
+| `email` | `email` |
+| `phone`, `mobile`, `fax` | `phone` |
+| `ssn`, `socialsecurity` | `ssn` |
+| `creditcard`, `cc` | `creditCard` |
+| `password`, `secret`, `token` | `redact` |
 
 ---
 
-# Actions - Custom Business Logic
+# Views — Column-Level Security
 
-Actions are custom API endpoints for business logic beyond CRUD.
+Views are named projections that control which fields are visible based on role.
 
 ```typescript
-// definitions/features/todos/actions.ts
-export default {
-  name: "todos",
-  schema: "./schema",
-
-  actions: {
-    complete: {
-      description: "Mark todo as complete",
-      input: {
-        type: "object",
-        properties: {
-          completedAt: { type: "string", format: "datetime", optional: true },
-        },
-      },
-      guard: {
-        roles: ["owner", "member", "admin"],
-        record: { completed: { equals: false } },
-      },
-      sideEffects: "sync",
+export default defineTable(customers, {
+  // ... firewall, guards, etc.
+
+  views: {
+    summary: {
+      fields: ['id', 'name', 'email'],
+      access: { roles: ['member', 'admin'] },
     },
+    full: {
+      fields: ['id', 'name', 'email', 'phone', 'ssn', 'address'],
+      access: { roles: ['admin'] },
+    },
+  },
+});
+```
+
+**Generated endpoints**:
+- `GET /api/v1/customers/views/summary` — returns only id, name, email
+- `GET /api/v1/customers/views/full` — returns all fields (admin only)
+
+Views support the same query parameters as list (filtering, sorting, pagination). Masking still applies to returned fields.
+
+---
+
+# Validation
+
+Field-level validation rules compiled into the API:
+
+```typescript
+export default defineTable(rooms, {
+  // ... other config
+
+  validation: {
+    name: { minLength: 1, maxLength: 100 },
+    capacity: { min: 1, max: 1000 },
+    roomType: { enum: ['meeting', 'conference', 'breakout'] },
+    email: { email: true },
+    website: { url: true },
+    code: { pattern: '^[A-Z]{3}$' },
   },
-};
+});
+```
+
+---
+
+# Actions — Custom Business Logic
+
+Actions are custom API endpoints for business logic beyond CRUD. Defined in a separate `actions.ts` file using `defineActions()`.
+
+```typescript
+// quickback/features/todos/actions.ts
+import { todos } from './todos';
+import { defineActions } from '@quickback/compiler';
+import { z } from 'zod';
+
+export default defineActions(todos, {
+  complete: {
+    description: "Mark todo as complete",
+    input: z.object({
+      completedAt: z.string().datetime().optional(),
+    }),
+    guard: {
+      roles: ["member", "admin"],
+      record: { completed: { equals: false } },
+    },
+    execute: async ({ db, record, ctx, input }) => {
+      // Inline handler
+      await db.update(todos).set({ completed: true }).where(eq(todos.id, record.id));
+      return { success: true };
+    },
+    sideEffects: "sync",
+  },
+
+  archive: {
+    description: "Archive a todo",
+    input: z.object({}),
+    guard: { roles: ["admin"] },
+    handler: "./handlers/archive",  // OR: external file handler
+  },
+});
 ```
 
 **Generated Route**: `POST /api/v1/todos/:id/complete`
 
+### Record-based vs Standalone Actions
+
+**Record-based** (default) — operates on a specific record via `:id`:
+```typescript
+approve: {
+  description: "Approve an invoice",
+  input: z.object({ notes: z.string().optional() }),
+  guard: { roles: ["admin"] },
+  handler: "./handlers/approve",
+}
+// → POST /api/v1/invoices/:id/approve
+```
+
+**Standalone** — custom endpoint not tied to a record:
+```typescript
+chat: {
+  standalone: true,
+  path: "/chat",
+  method: "POST",
+  responseType: "stream",
+  input: z.object({ message: z.string() }),
+  guard: { roles: ["member"] },
+  handler: "./handlers/chat",
+}
+// → POST /api/v1/todos/chat
+```
+
+### Action Options
+
+| Option | Values | Description |
+|--------|--------|-------------|
+| `standalone` | `true` | Not tied to a record |
+| `method` | `GET`, `POST`, `PUT`, `PATCH`, `DELETE` | HTTP method (default: POST) |
+| `responseType` | `json`, `stream`, `file` | Response format |
+| `sideEffects` | `sync`, `async`, `fire-and-forget` | Execution hint |
+
 ---
 
 # API Reference
@@ -264,6 +458,23 @@ export default {
 | `DELETE` | `/api/v1/{resource}/:id` | Delete record |
 | `PUT` | `/api/v1/{resource}/:id` | Upsert (if enabled) |
 
+## Batch Operations
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/v1/{resource}/batch` | Batch create |
+| `PATCH` | `/api/v1/{resource}/batch` | Batch update |
+| `DELETE` | `/api/v1/{resource}/batch` | Batch delete |
+| `PUT` | `/api/v1/{resource}/batch` | Batch upsert (if enabled) |
+
+```json
+// Request
+{ "records": [{ "title": "A" }, { "title": "B" }], "options": { "atomic": false } }
+
+// Response
+{ "success": [/* ... */], "errors": [/* ... */], "meta": { "total": 2, "succeeded": 2, "failed": 0 } }
+```
+
 ## Query Parameters
 
 ### Pagination
@@ -271,12 +482,13 @@ export default {
 | Param | Default | Max |
 |-------|---------|-----|
 | `limit` | 50 | 100 |
-| `offset` | 0 | - |
+| `offset` | 0 | — |
 
 ### Filtering Operators
 
 | Operator | Example | SQL |
 |----------|---------|-----|
+| (none) | `?status=active` | `status = 'active'` |
 | `.gt` | `?amount.gt=100` | `amount > 100` |
 | `.gte` | `?amount.gte=100` | `amount >= 100` |
 | `.lt` | `?amount.lt=1000` | `amount < 1000` |
@@ -306,44 +518,6 @@ export default {
 
 ---
 
-# Resource Styles
-
-## Controlled Resources (Default)
-
-Server generates IDs, guards restrict modifications.
-
-```typescript
-// HTTP Methods: POST, PATCH, GET, LIST, DELETE
-export default defineTable(invoices, {
-  guards: {
-    createable: ['description', 'amount'],
-    updatable: ['description'],
-  },
-  crud: { create: {}, update: {}, get: {}, list: {}, delete: {} },
-});
-```
-
-## External/Sync Resources (PUT enabled)
-
-Client provides IDs, no field restrictions.
-
-```typescript
-// Database config: generateId: false
-// HTTP Methods: POST, PUT, PATCH, GET, LIST, DELETE
-export default defineTable(external_orders, {
-  guards: false,  // Enables PUT
-  crud: {
-    put: { access: { roles: ['sync-service'] } },
-    get: {},
-    list: {}
-  },
-});
-```
-
-**PUT Rule**: Only available when BOTH `generateId: false` AND `guards: false`.
-
----
-
 # Webhooks
 
 ## Configuration
@@ -353,7 +527,7 @@ export default defineTable(external_orders, {
 providers: {
   database: defineDatabase("cloudflare-d1", {
     splitDatabases: true,
-    webhooksBinding: "WEBHOOKS_DB",  // Enables webhook infrastructure
+    webhooksBinding: "WEBHOOKS_DB",
   }),
 }
 ```
@@ -396,13 +570,46 @@ await emitWebhookEvent(
 
 ---
 
+# CLI Commands
+
+## Core Commands
+
+| Command | Description |
+|---------|-------------|
+| `quickback create <template> <name>` | Create project from template |
+| `quickback compile` | Compile definitions to output |
+| `quickback login` | Authenticate for Pro templates |
+| `quickback logout` | Clear stored credentials |
+| `quickback whoami` | Show current auth status |
+
+## Available Templates
+
+| Template | Stack | Status |
+|----------|-------|--------|
+| `cloudflare` | Cloudflare Workers + D1 + Better Auth | Free |
+| `bun` | Bun + SQLite + Better Auth | Free |
+| `turso` | Turso/LibSQL + Better Auth | Pro |
+
+## Claude Code Integration
+
+| Command | Description |
+|---------|-------------|
+| `quickback claude install` | Interactive install of Claude Code skill |
+| `quickback claude install --global` | Install globally |
+| `quickback claude install --local` | Install for current project |
+| `quickback claude update` | Update to latest skill version |
+| `quickback claude remove` | Remove the skill |
+| `quickback claude status` | Show install status |
+
+---
+
 # Development Workflow
 
 ```bash
 # 1. Create project
 quickback create cloudflare my-app
 
-# 2. Define features in definitions/features/
+# 2. Define features in quickback/features/
 
 # 3. Compile
 quickback compile
@@ -416,32 +623,43 @@ npm run dev
 
 ---
 
-# CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `quickback create <template> <name>` | Create project from template |
-| `quickback compile` | Compile definitions to output |
-| `quickback login` | Authenticate for Pro templates |
-| `quickback logout` | Clear stored credentials |
-| `quickback whoami` | Show current auth status |
+# Deployment Targets
 
----
+## Cloudflare Stack (Full Edge)
 
-# Security Layer Execution Order
+Hono API on Workers, D1 database, Better Auth, R2 file storage, KV, Queues, Durable Objects for realtime.
 
+```typescript
+defineConfig({
+  providers: {
+    runtime: defineRuntime("cloudflare"),
+    database: defineDatabase("cloudflare-d1"),
+    auth: defineAuth("better-auth"),
+  },
+});
 ```
-Request → Firewall → Access → Guards → Database → Masking → Response
+
+## Supabase (RLS Policies)
+
+Compiles Quickback definitions into Row Level Security policies for Postgres-level security.
+
+```typescript
+defineConfig({
+  providers: {
+    runtime: defineRuntime("supabase"),
+    database: defineDatabase("supabase"),
+    auth: defineAuth("supabase"),
+  },
+});
 ```
 
-1. **Firewall**: Filters data by ownership (WHERE clause)
-2. **Access**: Checks role + record permissions (403 on failure)
-3. **Access**: Checks role + record permissions (403 on failure)
-4. **Guards**: Validates field modifications (400 on failure)
-5. **Database**: Executes query
-6. **Masking**: Transforms sensitive fields in response
+## Neon (Serverless Postgres)
 
-## Error Responses
+Serverless Postgres with compiled RLS policies and branching support.
+
+---
+
+# Error Responses
 
 | Status | Layer | Meaning |
 |--------|-------|---------|
@@ -450,3 +668,35 @@ Request → Firewall → Access → Guards → Database → Masking → Response
 | `404` | Firewall | Record not found or outside scope |
 | `400` | Guards | Invalid field modification |
 | `429` | Rate limit | Too many requests |
+
+---
+
+# Database Dialects
+
+Detect from `quickback.config.ts` and use the correct imports:
+
+| Stack | Import | Table Function |
+|-------|--------|----------------|
+| Cloudflare D1 / SQLite | `drizzle-orm/sqlite-core` | `sqliteTable` |
+| Supabase / PostgreSQL | `drizzle-orm/pg-core` | `pgTable` |
+| MySQL | `drizzle-orm/mysql-core` | `mysqlTable` |
+
+---
+
+# Documentation
+
+Full documentation at https://docs.quickback.dev
+
+- [Quick Start](https://docs.quickback.dev/definitions/quick-start)
+- [Concepts](https://docs.quickback.dev/definitions/concepts)
+- [Database Schema](https://docs.quickback.dev/definitions/database-schema)
+- [CRUD Endpoints](https://docs.quickback.dev/definitions/crud-endpoints)
+- [Views](https://docs.quickback.dev/definitions/views)
+- [Actions](https://docs.quickback.dev/definitions/actions)
+- [Firewall](https://docs.quickback.dev/definitions/firewall)
+- [Access](https://docs.quickback.dev/definitions/access)
+- [Guards](https://docs.quickback.dev/definitions/guards)
+- [Masking](https://docs.quickback.dev/definitions/masking)
+- [CLI Reference](https://docs.quickback.dev/compiler/cli)
+- [Cloudflare Stack](https://docs.quickback.dev/stack/cloudflare)
+- [Quick Reference](https://docs.quickback.dev/stack/reference)