@kardoe/quickback 0.5.16 → 0.6.1

package/dist/skill/skill/SKILL.md

@@ -0,0 +1,656 @@
+---
+name: quickback
+description: Quickback API engine documentation - use when working with Quickback projects, defining resources, schemas, security pillars (Firewall, Access, Guards, Masking), actions, webhooks, or deployment
+allowed-tools: Read, Grep, Glob
+---
+
+# Quickback
+
+Quickback is two things:
+
+1. **Compiler** — Transforms declarative TypeScript definitions into secure, production-ready APIs
+2. **Stack** — A Supabase alternative running entirely on Cloudflare (D1, R2, KV, Durable Objects, Queues, Workers AI)
+
+The output is standard TypeScript (Hono, Drizzle, Better Auth) running on your own infrastructure. Not a managed platform — real code you own and control.
+
+## Accessing Documentation
+
+The fastest way to look up detailed docs is via the CLI:
+
+```bash
+quickback docs                    # List all available topics
+quickback docs <topic>            # Show docs for a specific topic
+quickback docs firewall           # Example: firewall docs
+quickback docs cms/record-layouts # Example: CMS record layouts
+```
+
+Full online docs: https://docs.quickback.dev
+
+---
+
+# PART 1: THE COMPILER
+
+The compiler takes your TypeScript definitions and generates API routes, middleware, migrations, typed SDKs, OpenAPI specs, and AI tool definitions.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  YOU DEFINE (in TypeScript)                             │
+│  • Drizzle schema (your data models)                    │
+│  • Security layers (Firewall, Access, Guards, Masking)  │
+│  • Views, Validation, Layouts                           │
+│  • Actions (your business operations)                   │
+├─────────────────────────────────────────────────────────┤
+│  QUICKBACK COMPILES TO                                  │
+│  • Database migrations (via Drizzle)                    │
+│  • API route handlers (Hono)                            │
+│  • Typed client SDK for your frontend                   │
+│  • AI tool definitions                                  │
+│  • OpenAPI specification                                │
+└─────────────────────────────────────────────────────────┘
+```
+
+## 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
+
+```typescript
+import { defineConfig, defineRuntime, defineDatabase, defineAuth } from '@quickback/compiler';
+
+export default defineConfig({
+  name: "my-saas-app",
+  providers: {
+    runtime: defineRuntime("cloudflare"),
+    database: defineDatabase("cloudflare-d1"),
+    auth: defineAuth("better-auth"),
+  },
+  build: {
+    outputDir: "dist",
+    dependencies: {
+      "fast-xml-parser": "^4.5.0",  // Third-party packages used in action handlers
+    },
+  },
+});
+```
+
+## Compile Output and State Artifacts
+
+- Runtime code stays in `build.outputDir` (e.g. `src/`, `wrangler.toml`, `package.json`)
+- Drizzle migration/state artifacts are written to `quickback/drizzle/...`
+- Security contract reports are written to `quickback/reports/...`
+
+## Automatic Audit Fields
+
+Quickback automatically injects these fields into every table:
+- `createdAt`, `modifiedAt`, `deletedAt` (timestamps)
+- `createdBy`, `modifiedBy`, `deletedBy` (user IDs)
+
+**Do NOT add these to your schema files.** They are auto-injected by the compiler.
+
+---
+
+## Feature Definitions
+
+Features live in `quickback/features/{name}/` with one file per table using `defineTable()`.
+
+### Example: todos.ts
+
+```typescript
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+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, {
+  firewall: {
+    organization: {},
+    owner: {},
+  },
+  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", "description", "completed"],
+    updatable: ["title", "description", "completed"],
+  },
+  masking: {
+    userId: { type: "redact", show: { roles: ["admin"] } },
+  },
+  layouts: {
+    default: {
+      sections: [
+        { label: "Details", columns: 2, fields: ["title", "completed"] },
+        { label: "Audit", collapsed: true, fields: ["userId"] },
+      ],
+    },
+  },
+});
+```
+
+### Internal/Junction Tables (No API)
+
+Tables without a `defineTable()` default export get no API routes:
+
+```typescript
+export const roomAmenities = sqliteTable('room_amenities', {
+  roomId: text('room_id').notNull(),
+  amenityId: text('amenity_id').notNull(),
+});
+```
+
+---
+
+## Four Security Layers
+
+Every API request passes through four layers in order:
+
+```
+Request → Firewall → Access → Guards → Database → Masking → Response
+```
+
+| 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 | — |
+
+### 1. Firewall — Data Isolation
+
+Compiles WHERE clauses to isolate data by ownership. Auto-detects column names.
+
+```typescript
+firewall: {
+  organization: {},                    // WHERE organizationId = ctx.activeOrgId
+  owner: { mode: 'optional' },         // AND (ownerId = ctx.userId OR ownerId IS NULL)
+  team: {},                            // WHERE teamId = ctx.activeTeamId
+  softDelete: {},                      // AND deletedAt IS NULL
+  exception: true,                     // No filtering (public resources)
+}
+```
+
+Auto-detection:
+- `organization` → looks for `organizationId` or `organization_id`
+- `owner` → looks for `userId` or `user_id`
+- `team` → looks for `teamId` or `team_id`
+
+Column overrides:
+
+```typescript
+firewall: {
+  organization: {
+    column: 'tenant_id',
+    source: 'ctx.tenant.id',
+  },
+}
+```
+
+Owner modes: default = strict (only own records), `optional` = own + NULL owner (admin pattern).
+
+### 2. Access — Permission Checks
+
+Role-based and record-based access control. Deny by default.
+
+```typescript
+crud: {
+  list: { access: { roles: ['member'] } },
+  get: { access: { roles: ['member'] } },
+  create: { access: { roles: ['admin', 'manager'] } },
+  update: {
+    access: {
+      or: [
+        { roles: ['admin'] },
+        { record: { createdBy: { equals: '$ctx.userId' } } },
+      ],
+    },
+  },
+  delete: { access: { roles: ['admin'] } },
+}
+```
+
+Record condition operators: `equals`, `notEquals`, `in`, `notIn`, `greaterThan`, `lessThan`
+
+Context variables: `$ctx.userId`, `$ctx.activeOrgId`, `$ctx.activeTeamId`, `$ctx.roles`, `$ctx.isAnonymous`
+
+### 3. Guards — Field Protection
+
+```typescript
+guards: {
+  createable: ['name', 'description'],     // Allowed on POST
+  updatable: ['description'],              // Allowed on PATCH
+  immutable: ['invoiceNumber'],            // Set once, never change
+  protected: { status: ['approve'] },      // Only via named actions
+}
+```
+
+System-managed fields (always protected): `createdAt`, `createdBy`, `modifiedAt`, `modifiedBy`, `deletedAt`, `deletedBy`
+
+PUT/Upsert requires both `generateId: false` and `guards: false`.
+
+### 4. Masking — PII Redaction
+
+```typescript
+masking: {
+  ssn: { type: 'ssn', show: { roles: ['admin', 'hr'] } },
+  email: { type: 'email', show: { roles: ['admin'], or: 'owner' } },
+}
+```
+
+Mask types: `email`, `phone`, `ssn`, `creditCard`, `name`, `redact`, `custom`
+
+Auto-detection warns on unmasked sensitive columns (`email`, `phone`, `ssn`, `password`, etc.).
+
+---
+
+## Views — Column-Level Security
+
+Named projections that control which fields are visible based on role.
+
+```typescript
+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/{resource}/views/{viewName}`
+
+---
+
+## Validation
+
+```typescript
+validation: {
+  name: { minLength: 1, maxLength: 100 },
+  capacity: { min: 1, max: 1000 },
+  roomType: { enum: ['meeting', 'conference', 'breakout'] },
+  email: { email: true },
+  code: { pattern: '^[A-Z]{3}$' },
+}
+```
+
+---
+
+## CMS Record Layouts
+
+Control how fields are grouped on the CMS record detail page.
+
+```typescript
+layouts: {
+  default: {
+    sections: [
+      { label: "Contact Info", columns: 2, fields: ["name", "email", "phone"] },
+      { label: "Notes", collapsed: true, fields: ["notes", "internalNotes"] },
+    ],
+  },
+}
+```
+
+Section options: `label` (string), `fields` (string[]), `columns` (1|2, default 1), `collapsed` (boolean, default false). Unassigned fields go to "Other Fields".
+
+---
+
+## Actions — Custom Business Logic
+
+Defined in a separate `actions.ts` file using `defineActions()`.
+
+```typescript
+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 }) => {
+      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",
+  },
+});
+```
+
+**Record-based** (default): `POST /api/v1/{resource}/:id/{action}`
+**Standalone**: `standalone: true`, custom `path` and `method`
+
+Action options: `standalone`, `method` (GET/POST/PUT/PATCH/DELETE), `responseType` (json/stream/file), `sideEffects` (sync/async/fire-and-forget)
+
+### Actions-Only Features
+
+Features that only contain standalone actions (no tables). Use `defineActions(null, { ... })`:
+
+```typescript
+// quickback/features/utilities/actions.ts
+import { defineActions } from '@quickback/compiler';
+import { z } from 'zod';
+
+export default defineActions(null, {
+  healthCheck: {
+    standalone: true,
+    path: "/health",
+    method: "GET",
+    description: "Health check endpoint",
+    input: z.object({}),
+    guard: { roles: ["member", "admin"] },
+    handler: "./handlers/health-check",
+  },
+});
+```
+
+All actions in an actions-only feature must have `standalone: true` (since there's no table for record-based actions).
+
+---
+
+## API Reference
+
+### CRUD Operations
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/v1/{resource}` | List records |
+| `GET` | `/api/v1/{resource}/:id` | Get single record |
+| `POST` | `/api/v1/{resource}` | Create record |
+| `PATCH` | `/api/v1/{resource}/:id` | Update record |
+| `DELETE` | `/api/v1/{resource}/:id` | Delete record |
+| `PUT` | `/api/v1/{resource}/:id` | Upsert (if enabled) |
+
+### Batch Operations
+
+`POST|PATCH|DELETE|PUT /api/v1/{resource}/batch` with `{ "records": [...], "options": { "atomic": false } }`
+
+### Query Parameters
+
+| Feature | Syntax |
+|---------|--------|
+| Pagination | `?limit=50&offset=0` (max 100) |
+| Filter | `?status=active`, `?amount.gt=100`, `?status.in=draft,pending` |
+| Sort | `?sort=status,-createdAt` (multi-sort, `-` = desc) |
+| Fields | `?fields=id,name,status` |
+| Total count | `?total=true` |
+| Search | `?search=conference` (OR'd LIKE across text columns) |
+
+Filter operators: `.gt`, `.gte`, `.lt`, `.lte`, `.ne`, `.like`, `.in`
+
+### Response Format
+
+```json
+{
+  "data": [{ "id": "...", "title": "Todo 1" }],
+  "pagination": { "limit": 10, "offset": 0, "count": 2, "total": 42 }
+}
+```
+
+### Error Responses
+
+| Status | Layer | Meaning |
+|--------|-------|---------|
+| `401` | Auth | Invalid/expired session |
+| `403` | Access | Insufficient permissions |
+| `404` | Firewall | Record not found or outside scope |
+| `400` | Guards | Invalid field modification |
+
+---
+
+## Database Dialects
+
+| 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` |
+
+---
+
+# PART 2: THE QUICKBACK STACK
+
+The Quickback Stack is a production-ready backend platform built entirely on Cloudflare's edge infrastructure. It's a Supabase alternative where everything runs on your own Cloudflare account — your data, your infrastructure, global edge performance.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  QUICKBACK STACK ON CLOUDFLARE                          │
+│                                                         │
+│  Workers     — API runtime (Hono)                       │
+│  D1          — SQLite database at the edge              │
+│  R2          — S3-compatible file storage                │
+│  KV          — Distributed key-value store              │
+│  Durable Objects — Realtime WebSockets                  │
+│  Queues      — Background job processing                │
+│  Workers AI  — Embeddings & vector search               │
+│  Better Auth — Authentication & organizations           │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Authentication (Better Auth)
+
+Built on Better Auth with multi-tenant organization support.
+
+- Email/password, magic links, passkeys, email OTP
+- Three org roles: `owner`, `admin`, `member`
+- Session storage in KV namespace
+- All auth routes at `/auth/v1/*`
+- Extensible via Better Auth plugins
+
+```typescript
+// Config
+providers: {
+  auth: defineAuth("better-auth"),
+}
+```
+
+Docs: `quickback docs stack/auth/using-auth` | https://docs.quickback.dev/stack/auth
+
+## Database (D1)
+
+SQLite at the edge with zero configuration. Multi-database pattern for independent scaling:
+
+| Binding | Purpose |
+|---------|---------|
+| `DB` | Application data (features) |
+| `AUTH_DB` | Auth sessions & users |
+| `FILES_DB` | File metadata |
+| `WEBHOOKS_DB` | Webhook tracking |
+
+- Drizzle ORM for type-safe queries
+- Auto-generated migrations on compile
+- Application-layer security (firewall, access, guards, masking)
+- Local dev with `.wrangler/state/`
+- Neon Postgres available as alternative
+
+```typescript
+providers: {
+  database: defineDatabase("cloudflare-d1", {
+    splitDatabases: true,
+  }),
+}
+```
+
+Docs: `quickback docs stack/database/d1` | https://docs.quickback.dev/stack/database/d1
+
+## File Storage (R2)
+
+S3-compatible object storage with built-in access control.
+
+- Two-worker architecture: API worker (upload/manage) + Files worker (serve)
+- Bucket-scoped access policies (public, organization, user)
+- File metadata tracked in `FILES_DB`
+- Soft deletes with org-level tenant isolation
+- API at `/storage/v1/*`
+
+Docs: `quickback docs stack/storage/r2` | https://docs.quickback.dev/stack/storage/r2
+
+## KV Storage
+
+Distributed key-value store optimized for reads (300+ edge locations, sub-millisecond).
+
+- Use cases: sessions, caching, rate limiting, feature flags
+- Eventually consistent (60 second propagation)
+- TTL/expiration support
+
+Docs: `quickback docs stack/storage/kv` | https://docs.quickback.dev/stack/storage/kv
+
+## Realtime (Durable Objects)
+
+WebSocket connections for live updates via organization-scoped Durable Objects.
+
+- CRUD event broadcasting (insert, update, delete)
+- Custom broadcasts and event namespaces
+- Role-based filtering and per-role field masking
+- Session token or API key authentication
+- Type-safe with `defineRealtime()` for custom events
+- Endpoint: `/realtime/v1/websocket`
+
+Docs: `quickback docs stack/realtime/durable-objects` | https://docs.quickback.dev/stack/realtime
+
+## Queues (Background Processing)
+
+Cloudflare Queues for reliable async job processing.
+
+| Queue | Purpose |
+|-------|---------|
+| `EMBEDDINGS_QUEUE` | Auto-generate embeddings |
+| `WEBHOOKS_QUEUE` | Webhook delivery |
+| Custom queues | Your background jobs |
+
+- Custom handlers via `defineQueue()` in `services/queues/`
+- Auto-retry up to 3 times, max batch 10, 30s timeout
+- Chaining between queues
+
+Docs: `quickback docs stack/queues/using-queues` | https://docs.quickback.dev/stack/queues
+
+## Vector & Embeddings (Workers AI)
+
+Auto-generated embeddings for similarity search and classification.
+
+- Table-level config via `embeddings` in `defineTable()`
+- Service-level config via `defineEmbedding()`
+- Default model: `@cf/baai/bge-base-en-v1.5` (768 dimensions)
+- Async processing via `EMBEDDINGS_QUEUE`
+- Vector storage in D1 + optional Vectorize index
+- API: `/api/v1/embeddings`
+
+Docs: `quickback docs stack/vector/embeddings` | https://docs.quickback.dev/stack/vector
+
+## Webhooks
+
+### Inbound (Receiving)
+
+Receive events from Stripe, Paddle, GitHub, etc. at `POST /webhooks/v1/inbound/:provider`
+
+```typescript
+import { onWebhookEvent } from './lib/webhooks';
+
+onWebhookEvent('stripe:checkout.session.completed', async (ctx) => {
+  const { data, env } = ctx;
+  await createSubscription({ ... });
+});
+```
+
+### Outbound (Sending)
+
+Emit signed events when data changes. HMAC-SHA256 signing, async delivery via queue with exponential backoff retry.
+
+```typescript
+import { emitWebhookEvent } from './lib/webhooks';
+
+await emitWebhookEvent('user.created', { id: user.id, email: user.email }, { organizationId: orgId }, env);
+```
+
+Event patterns: `user.*`, `subscription.*`, `organization.*`, `file.*`, `*`
+Endpoint management: `/webhooks/v1/endpoints`
+
+Docs: `quickback docs stack/webhooks/outbound` | https://docs.quickback.dev/stack/webhooks
+
+---
+
+# CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `quickback create <template> <name>` | Create project from template |
+| `quickback compile` | Compile definitions to output |
+| `quickback docs [topic]` | Browse built-in documentation |
+| `quickback login` | Authenticate for Pro templates |
+| `quickback logout` | Clear stored credentials |
+| `quickback whoami` | Show current auth status |
+| `quickback claude install` | Install Claude Code skill |
+| `quickback claude update` | Update to latest skill version |
+
+## Available Templates
+
+| Template | Stack | Status |
+|----------|-------|--------|
+| `cloudflare` | Cloudflare Workers + D1 + Better Auth | Free |
+| `bun` | Bun + SQLite + Better Auth | Free |
+| `turso` | Turso/LibSQL + Better Auth | Pro |
+
+## Development Workflow
+
+```bash
+quickback create cloudflare my-app   # 1. Create project
+# Define features in quickback/features/
+quickback compile                     # 2. Compile
+npm install && npm run dev            # 3. Run
+```
+
+---
+
+# Online Documentation
+
+- [Getting Started](https://docs.quickback.dev/compiler/getting-started)
+- [Concepts](https://docs.quickback.dev/compiler/definitions/concepts)
+- [Database Schema](https://docs.quickback.dev/compiler/definitions/schema)
+- [Firewall](https://docs.quickback.dev/compiler/definitions/firewall)
+- [Access](https://docs.quickback.dev/compiler/definitions/access)
+- [Guards](https://docs.quickback.dev/compiler/definitions/guards)
+- [Masking](https://docs.quickback.dev/compiler/definitions/masking)
+- [Views](https://docs.quickback.dev/compiler/definitions/views)
+- [Actions](https://docs.quickback.dev/compiler/definitions/actions)
+- [CRUD API](https://docs.quickback.dev/compiler/using-the-api/crud)
+- [Query Parameters](https://docs.quickback.dev/compiler/using-the-api/query-params)
+- [CLI Reference](https://docs.quickback.dev/compiler/cloud-compiler/cli)
+- [Stack Overview](https://docs.quickback.dev/stack)
+- [D1 Database](https://docs.quickback.dev/stack/database/d1)
+- [R2 Storage](https://docs.quickback.dev/stack/storage/r2)
+- [Realtime](https://docs.quickback.dev/stack/realtime)
+- [Queues](https://docs.quickback.dev/stack/queues)
+- [Embeddings](https://docs.quickback.dev/stack/vector)
+- [Webhooks](https://docs.quickback.dev/stack/webhooks)
+- [CMS Overview](https://docs.quickback.dev/cms)
+- [CMS Record Layouts](https://docs.quickback.dev/cms/record-layouts)