@kardoe/quickback 0.4.1 → 0.4.2

package/src/skill/SKILL.md

@@ -0,0 +1,452 @@
+---
+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: The Universal API Engine for B2B SaaS
+
+Quickback gives you a **complete, secure, multi-tenant backend in minutes**.
+
+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.
+
+## Getting Started
+
+**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.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  YOU DEFINE (in TypeScript)                             │
+│  • Drizzle schema (your data models)                    │
+│  • Security layers (Firewall, Access, Guards, Masking)  │
+│  • CRUD configuration                                   │
+│  • Actions (your business operations)                   │
+├─────────────────────────────────────────────────────────┤
+│  QUICKBACK COMPILES TO (Static, Signed, Auditable Code) │
+│  • Database migrations (via Drizzle)                    │
+│  • API route handlers (in a Hono project)               │
+│  • Typed client SDK for your frontend                   │
+│  • AI tool definitions                                  │
+│  • OpenAPI specification                                │
+│  • Compliance manifest                                  │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Security & Compliance Pillars
+
+| 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 |
+
+---
+
+# Project Configuration
+
+## 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",
+  },
+});
+```
+
+## 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.ts files.
+
+---
+
+# Feature Definitions (Combined Mode)
+
+Features live in `quickback/features/{name}/` with one file per table using `defineTable()`.
+
+**Important**: Legacy mode (separate schema.ts + resource.ts) is no longer supported.
+
+## 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(),
+  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" },
+  },
+
+  guards: {
+    createable: ["title", "completed"],
+    updatable: ["title", "completed"],
+  },
+
+  masking: {
+    userId: { type: "redact", show: { roles: ["admin"] } },
+  },
+});
+```
+
+---
+
+# Security Pillars
+
+## 1. Firewall - Data Isolation
+
+Compiles WHERE clauses to isolate data by ownership.
+
+```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)
+}
+```
+
+### Column Overrides
+
+```typescript
+firewall: {
+  organization: {
+    column: 'tenant_id',        // Instead of 'organizationId'
+    source: 'ctx.tenant.id',    // Instead of 'ctx.activeOrgId'
+  },
+}
+```
+
+## 2. Access - Permission Checks
+
+Role-based and record-based access control.
+
+```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 Conditions**: `equals`, `notEquals`, `in`, `notIn`, `greaterThan`, `lessThan`
+
+## 3. Guards - Field Protection
+
+Controls which fields can be modified.
+
+```typescript
+guards: {
+  createable: ['name', 'description'],     // Allowed on POST
+  updatable: ['description'],              // Allowed on PATCH
+  immutable: ['invoiceNumber'],            // Set once, never change
+  protected: { status: ['approve'] },      // Only via actions
+}
+```
+
+**System-managed fields** (always protected):
+- `createdAt`, `createdBy` - Set on INSERT
+- `modifiedAt`, `modifiedBy` - Set on INSERT/UPDATE
+- `deletedAt`, `deletedBy` - Set on soft DELETE
+
+## 4. Masking - Response Transformation
+
+```typescript
+masking: {
+  ssn: {
+    type: 'ssn',                          // ***-**-6789
+    show: { roles: ['admin', 'hr'] },
+  },
+  email: {
+    type: 'email',                        // p***@e****.com
+    show: { roles: ['admin'], or: 'owner' },
+  },
+}
+```
+
+**Mask types**: `email`, `phone`, `ssn`, `creditCard`, `name`, `redact`, `custom`
+
+---
+
+# Actions - Custom Business Logic
+
+Actions are custom API endpoints for business logic beyond CRUD.
+
+```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",
+    },
+  },
+};
+```
+
+**Generated Route**: `POST /api/v1/todos/:id/complete`
+
+---
+
+# 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) |
+
+## Query Parameters
+
+### Pagination
+
+| Param | Default | Max |
+|-------|---------|-----|
+| `limit` | 50 | 100 |
+| `offset` | 0 | - |
+
+### Filtering Operators
+
+| Operator | Example | SQL |
+|----------|---------|-----|
+| `.gt` | `?amount.gt=100` | `amount > 100` |
+| `.gte` | `?amount.gte=100` | `amount >= 100` |
+| `.lt` | `?amount.lt=1000` | `amount < 1000` |
+| `.lte` | `?amount.lte=1000` | `amount <= 1000` |
+| `.ne` | `?status.ne=cancelled` | `status != 'cancelled'` |
+| `.like` | `?title.like=urgent` | `title LIKE '%urgent%'` |
+| `.in` | `?status.in=draft,pending` | `status IN ('draft','pending')` |
+
+### Sorting
+
+```
+?sort=createdAt&order=desc
+```
+
+## Response Format
+
+```json
+{
+  "data": [{ "id": "...", "title": "Todo 1" }],
+  "pagination": {
+    "limit": 10,
+    "offset": 0,
+    "count": 2
+  }
+}
+```
+
+---
+
+# 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
+
+```typescript
+// quickback.config.ts
+providers: {
+  database: defineDatabase("cloudflare-d1", {
+    splitDatabases: true,
+    webhooksBinding: "WEBHOOKS_DB",  // Enables webhook infrastructure
+  }),
+}
+```
+
+## Inbound Webhooks (Receiving)
+
+```typescript
+import { onWebhookEvent } from './lib/webhooks';
+
+onWebhookEvent('stripe:checkout.session.completed', async (ctx) => {
+  const { data, env } = ctx;
+  await createSubscription({ ... });
+});
+```
+
+## Outbound Webhooks (Sending)
+
+```typescript
+import { emitWebhookEvent } from './lib/webhooks';
+
+await emitWebhookEvent(
+  'user.created',
+  { id: user.id, email: user.email },
+  { organizationId: orgId },
+  env
+);
+```
+
+## Available Events
+
+| Event | Description |
+|-------|-------------|
+| `user.created/updated/deleted` | User lifecycle |
+| `subscription.created/updated/cancelled/renewed` | Subscription lifecycle |
+| `organization.created/updated/deleted` | Organization lifecycle |
+| `organization.member_added/removed` | Membership changes |
+| `file.uploaded/deleted` | File storage |
+
+**Wildcards**: `user.*`, `subscription.*`, `organization.*`, `file.*`, `*`
+
+---
+
+# Development Workflow
+
+```bash
+# 1. Create project
+quickback create cloudflare my-app
+
+# 2. Define features in definitions/features/
+
+# 3. Compile
+quickback compile
+
+# 4. Run
+cd dist
+npm install
+npm run db:generate
+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 |
+
+---
+
+# Security Layer Execution Order
+
+```
+Request → Firewall → Access → Guards → Database → Masking → Response
+```
+
+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
+
+## 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 |
+| `429` | Rate limit | Too many requests |

package/src/skill/agents/quickback-specialist/AGENT.md

@@ -0,0 +1,103 @@
+---
+name: quickback-specialist
+description: Expert at building Quickback applications. Use proactively when creating resources, configuring security layers (Firewall, Access, Guards, Masking), defining actions, or debugging Quickback configurations. Delegates exploration and code generation for Quickback projects.
+tools: Read, Write, Edit, Glob, Grep, Bash
+model: sonnet
+skills:
+  - quickback
+---
+
+You are a Quickback specialist - an expert at building secure, multi-tenant backends using Quickback's security layer system.
+
+## Your Expertise
+
+You deeply understand:
+- **Firewall**: Data isolation via compiled WHERE clauses (organization, owner, team, softDelete)
+- **Access**: Role-based and record-level permissions
+- **Guards**: Field protection (createable, updatable, immutable, protected)
+- **Masking**: PII redaction with role-based visibility
+- **Actions**: Custom endpoints for protected field updates and business logic
+- **Views**: Column-level security with named projections
+
+## When Invoked
+
+1. **Understand the requirement** - What kind of resource? What security pattern?
+2. **Choose the right pattern**:
+   - Multi-tenant B2B → Organization-scoped firewall
+   - Personal data → Owner-scoped firewall
+   - Hierarchical access → Organization + owner-optional
+   - Public/reference data → `exception: true`
+3. **Generate complete configuration** including:
+   - Drizzle schema with correct dialect
+   - Resource definition with all security layers
+   - Actions for protected fields
+4. **Validate the configuration** - Check for common mistakes
+5. **Explain your decisions** - Help users understand the security model
+
+## Code Generation
+
+When creating resources, generate files in `definitions/features/{name}/`:
+- `schema.ts` - Drizzle table definition (DO NOT add audit fields - they're auto-injected)
+- `resource.ts` - Security configuration
+- `actions.ts` - Custom actions (if needed)
+
+Detect the database dialect from `quickback.config.ts`:
+- Cloudflare D1 / SQLite: Use `sqliteTable`, `text`, `integer`
+- Supabase / PostgreSQL: Use `pgTable`, `text`, `boolean`, `timestamp`
+
+## Security Principles
+
+1. **Secure by default** - Nothing is accessible until explicitly opened
+2. **Defense in depth** - Multiple layers work together
+3. **Principle of least privilege** - Grant minimum necessary access
+4. **Explicit over implicit** - Always define access rules clearly
+
+## Common Patterns You Implement
+
+### Multi-tenant resource
+```typescript
+firewall: {
+  organization: { column: 'organizationId' }
+}
+```
+
+### Owner-scoped with admin override
+```typescript
+firewall: {
+  organization: {},
+  owner: { mode: 'optional' }  // Admins see all, users see own
+}
+```
+
+### Workflow with protected status
+```typescript
+guards: {
+  protected: { status: ['approve', 'reject'] }
+}
+// Plus actions for approve/reject
+```
+
+### PII masking
+```typescript
+masking: {
+  email: { type: 'email', show: { roles: ['admin'] } },
+  ssn: { type: 'ssn', show: { roles: ['hr'] } }
+}
+```
+
+## Validation Checklist
+
+Before finishing, verify:
+- [ ] Firewall configured (or explicit `exception: true`)
+- [ ] Access rules for all CRUD operations
+- [ ] Guards define createable/updatable fields
+- [ ] Protected fields have corresponding actions
+- [ ] Masking for any PII fields
+- [ ] No audit fields in schema (auto-injected)
+
+## Response Style
+
+- Be direct and practical
+- Show complete, working code
+- Explain security decisions briefly
+- Suggest improvements when relevant