@kardoe/quickback 0.5.16 → 0.6.0

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

@@ -0,0 +1,220 @@
+---
+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 (deny by default)
+- **Guards**: Field protection (createable, updatable, immutable, protected)
+- **Masking**: PII redaction with role-based visibility and auto-detection
+- **Actions**: Custom endpoints using `defineActions()` with Zod schemas
+- **Views**: Column-level security with named projections
+- **Validation**: Field-level validation rules
+- **Layouts**: CMS record page field grouping with sections, columns, and collapsed state
+
+## 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
+   - `defineTable()` with all security layers in a single file
+   - Actions via `defineActions()` with Zod input schemas (if needed)
+4. **Validate the configuration** - Check for common mistakes
+5. **Explain your decisions** - Help users understand the security model
+
+## Code Generation
+
+Schema + security config in a single file using `defineTable()`.
+
+Generate files in `quickback/features/{name}/`:
+- `{table}.ts` - Drizzle schema + security config via `defineTable()` (DO NOT add audit fields - they're auto-injected)
+- `actions.ts` - Custom actions via `defineActions()` with Zod schemas (if needed)
+- `handlers/` - Action handler files (if needed)
+
+When explaining compile outputs:
+- Runtime outputs remain in `build.outputDir`.
+- Drizzle and migration state artifacts should live in `quickback/drizzle/...` when a `quickback/` folder exists.
+- Security contract reports should live in `quickback/reports/...` when a `quickback/` folder exists.
+
+Detect the database dialect from `quickback.config.ts`:
+- Cloudflare D1 / SQLite: Use `sqliteTable`, `text`, `integer` from `drizzle-orm/sqlite-core`
+- Supabase / PostgreSQL: Use `pgTable`, `text`, `boolean`, `timestamp` from `drizzle-orm/pg-core`
+
+### Table Definition Pattern
+
+```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, {
+  firewall: {
+    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"],
+  },
+  masking: {
+    userId: { type: "redact", show: { roles: ["admin"] } },
+  },
+});
+```
+
+### Actions Pattern
+
+```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 }) => {
+      await db.update(todos).set({ completed: true }).where(eq(todos.id, record.id));
+      return { success: true };
+    },
+  },
+});
+```
+
+## 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: {}  // Auto-detects organizationId column
+}
+```
+
+### 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 defineActions() for approve/reject
+```
+
+### PII masking
+```typescript
+masking: {
+  email: { type: 'email', show: { roles: ['admin'] } },
+  ssn: { type: 'ssn', show: { roles: ['hr'] } }
+}
+```
+
+### Views (column-level security)
+```typescript
+views: {
+  summary: {
+    fields: ['id', 'name', 'email'],
+    access: { roles: ['member', 'admin'] },
+  },
+  full: {
+    fields: ['id', 'name', 'email', 'phone', 'ssn'],
+    access: { roles: ['admin'] },
+  },
+}
+```
+
+### Standalone actions (not record-based)
+```typescript
+// In actions.ts
+chat: {
+  standalone: true,
+  path: "/chat",
+  method: "POST",
+  responseType: "stream",
+  input: z.object({ message: z.string() }),
+  guard: { roles: ["member"] },
+  handler: "./handlers/chat",
+}
+```
+
+## 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
+- [ ] Views for different visibility levels (if needed)
+- [ ] Validation rules for constrained fields (if needed)
+- [ ] Layouts for CMS record page field grouping (if needed)
+- [ ] No audit fields in schema (auto-injected)
+- [ ] Using `defineTable()` (not separate schema.ts + resource.ts)
+- [ ] Actions use `defineActions()` with Zod schemas (not JSON schema)
+
+## Accessing Documentation
+
+When you need to look up Quickback docs, use the CLI — it bundles all docs offline:
+
+```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
+
+## Response Style
+
+- Be direct and practical
+- Show complete, working code
+- Explain security decisions briefly
+- Suggest improvements when relevant

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kardoe/quickback",
-  "version": "0.5.16",
+  "version": "0.6.0",
   "description": "CLI for Quickback - one-shot backend generator",
   "author": "Paul Stenhouse",
   "license": "MIT",
@@ -11,22 +11,27 @@
   "main": "./dist/index.js",
   "files": [
     "dist/**/*",
-    "src/skill/**/*"
+    "src/skill/**/*",
+    "src/cursor/**/*"
   ],
   "scripts": {
     "prebuild": "npx tsx scripts/inject-version.ts && npm run bundle:docs && npm run bundle:skill",
     "build": "tsc",
+    "postbuild": "npx tsx scripts/bundle-cursor.ts && cp -r src/skill dist/skill 2>/dev/null; true",
     "dev": "tsc --watch",
     "test": "bun test",
     "typecheck": "tsc --noEmit",
     "bundle:docs": "npx tsx scripts/bundle-docs.ts",
-    "bundle:skill": "npx tsx scripts/bundle-skill.ts"
+    "bundle:skill": "npx tsx scripts/bundle-skill.ts",
+    "bundle:cursor": "npx tsx scripts/bundle-cursor.ts"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.0",
     "esbuild": "^0.27.2",
     "ora": "^9.0.0",
     "picocolors": "^1.0.0",
-    "prompts": "^2.4.2"
+    "prompts": "^2.4.2",
+    "zod": "^3.24.0"
   },
   "devDependencies": {
     "@types/node": "^22.7.5",

package/src/cursor/quickback.mdc

@@ -0,0 +1,235 @@
+---
+description: Quickback API engine - use when defining tables, schemas, security (Firewall, Access, Guards, Masking), actions, views, validation, or deploying Quickback projects
+globs: quickback/**/*.ts
+---
+
+# 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.
+
+## 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"),
+  },
+});
+```
+
+## Automatic Audit Fields
+
+Quickback auto-injects: `createdAt`, `modifiedAt`, `deletedAt`, `createdBy`, `modifiedBy`, `deletedBy`. Do NOT define these in schemas.
+
+## defineTable() — Schema + Security
+
+Each feature file exports a Drizzle table and a `defineTable()` default export with security config:
+
+```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"] } },
+  },
+});
+```
+
+## Four Security Layers
+
+Every request passes through: `Request → Firewall → Access → Guards → Database → Masking → Response`
+
+### 1. Firewall — Data Isolation
+
+Auto WHERE clauses for tenant isolation:
+
+```typescript
+firewall: {
+  organization: {},          // WHERE organizationId = ctx.activeOrgId
+  owner: {},                 // AND userId = ctx.userId
+  team: {},                  // WHERE teamId = ctx.activeTeamId
+  softDelete: {},            // AND deletedAt IS NULL
+  exception: true,           // No filtering (public)
+}
+```
+
+### 2. Access — Permission Checks
+
+Role-based and record-based (deny by default):
+
+```typescript
+crud: {
+  list: { access: { roles: ['member'] } },
+  update: {
+    access: {
+      or: [
+        { roles: ['admin'] },
+        { record: { createdBy: { equals: '$ctx.userId' } } },
+      ],
+    },
+  },
+}
+```
+
+Operators: `equals`, `notEquals`, `in`, `notIn`, `greaterThan`, `lessThan`
+Context: `$ctx.userId`, `$ctx.activeOrgId`, `$ctx.roles`
+
+### 3. Guards — Field Protection
+
+```typescript
+guards: {
+  createable: ['name', 'description'],
+  updatable: ['description'],
+  immutable: ['invoiceNumber'],
+  protected: { status: ['approve'] },  // Only via named actions
+}
+```
+
+### 4. Masking — PII Redaction
+
+```typescript
+masking: {
+  ssn: { type: 'ssn', show: { roles: ['admin'] } },
+  email: { type: 'email', show: { roles: ['admin'], or: 'owner' } },
+}
+```
+
+Types: `email`, `phone`, `ssn`, `creditCard`, `name`, `redact`, `custom`
+
+## Views — Column Projections
+
+```typescript
+views: {
+  summary: { fields: ['id', 'name'], access: { roles: ['member'] } },
+  full: { fields: ['id', 'name', 'phone', 'ssn'], access: { roles: ['admin'] } },
+}
+```
+
+## Validation
+
+```typescript
+validation: {
+  name: { minLength: 1, maxLength: 100 },
+  capacity: { min: 1, max: 1000 },
+  roomType: { enum: ['meeting', 'conference'] },
+  email: { email: true },
+}
+```
+
+## Actions — Custom Business Logic
+
+Separate `actions.ts` file:
+
+```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"] },
+    execute: async ({ db, record, ctx, input }) => {
+      await db.update(todos).set({ completed: true }).where(eq(todos.id, record.id));
+      return { success: true };
+    },
+  },
+});
+```
+
+Record-based: `POST /api/v1/{resource}/:id/{action}`
+Standalone: `standalone: true`, custom `path` and `method`
+
+## CMS Layouts
+
+```typescript
+layouts: {
+  default: {
+    sections: [
+      { label: "Details", columns: 2, fields: ["name", "email"] },
+      { label: "Notes", collapsed: true, fields: ["notes"] },
+    ],
+  },
+}
+```
+
+## API Reference
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/v1/{resource}` | List |
+| `GET` | `/api/v1/{resource}/:id` | Get |
+| `POST` | `/api/v1/{resource}` | Create |
+| `PATCH` | `/api/v1/{resource}/:id` | Update |
+| `DELETE` | `/api/v1/{resource}/:id` | Delete |
+
+Query params: `?limit=50&offset=0`, `?status=active`, `?sort=-createdAt`, `?fields=id,name`, `?search=text`
+Filter operators: `.gt`, `.gte`, `.lt`, `.lte`, `.ne`, `.like`, `.in`
+
+## Database Dialects
+
+| Stack | Import | Table Function |
+|-------|--------|----------------|
+| Cloudflare D1 / SQLite | `drizzle-orm/sqlite-core` | `sqliteTable` |
+| Supabase / PostgreSQL | `drizzle-orm/pg-core` | `pgTable` |
+
+## CLI Commands
+
+```bash
+quickback create <template> <name>   # Create project
+quickback compile                     # Compile definitions
+quickback docs [topic]                # Show documentation
+quickback claude install              # Install Claude Code skill
+quickback cursor install              # Install Cursor rules
+```
+
+## Full Documentation
+
+https://docs.quickback.dev