@kardoe/quickback 0.5.11 → 0.5.12

package/src/skill/SKILL.md

@@ -100,42 +100,40 @@ Features live in `quickback/features/{name}/` with one file per table using `def
 
 **Important**: Legacy mode (separate schema.ts + resource.ts) is no longer supported.
 
-## Example: todos.ts
+## Example: candidates.ts
 
 ```typescript
-import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+import { sqliteTable, text } 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(),
+export const candidates = sqliteTable("candidates", {
+  id: text("id").primaryKey(),
   organizationId: text("organization_id").notNull(),
+  name: text("name").notNull(),
+  email: text("email").notNull(),
+  phone: text("phone"),
+  resumeUrl: text("resume_url"),
+  source: text("source"),
 });
 
-export default defineTable(todos, {
+export default defineTable(candidates, {
   firewall: {
-    organization: {},    // Auto-detects 'organizationId' column
-    owner: {},           // Auto-detects 'userId' column
+    organization: {},
   },
-
   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" },
+    list: { access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] } },
+    get: { access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] } },
+    create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
+    update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
+    delete: { access: { roles: ["owner", "hiring-manager"] }, mode: "soft" },
   },
-
   guards: {
-    createable: ["title", "description", "completed"],
-    updatable: ["title", "description", "completed"],
+    createable: ["name", "email", "phone", "resumeUrl", "source"],
+    updatable: ["name", "phone"],
   },
-
   masking: {
-    userId: { type: "redact", show: { roles: ["admin"] } },
+    email: { type: "email", show: { roles: ["hiring-manager", "recruiter"] } },
+    phone: { type: "phone", show: { roles: ["hiring-manager", "recruiter"] } },
   },
 });
 ```
@@ -146,9 +144,12 @@ 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(),
+export const interviewScores = sqliteTable('interview_scores', {
+  applicationId: text('application_id').notNull(),
+  interviewerId: text('interviewer_id').notNull(),
+  score: integer('score').notNull(),
+  feedback: text('feedback'),
+  organizationId: text('organization_id').notNull(),  // Always scope junction tables
 });
 ```
 
@@ -201,18 +202,18 @@ 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'] } },
+  list: { access: { roles: ['owner', 'hiring-manager', 'recruiter', 'interviewer'] } },
+  get: { access: { roles: ['owner', 'hiring-manager', 'recruiter', 'interviewer'] } },
+  create: { access: { roles: ['owner', 'hiring-manager', 'recruiter'] } },
   update: {
     access: {
       or: [
-        { roles: ['admin'] },
+        { roles: ['owner', 'hiring-manager'] },
         { record: { createdBy: { equals: '$ctx.userId' } } },
       ],
     },
   },
-  delete: { access: { roles: ['admin'] } },
+  delete: { access: { roles: ['owner', 'hiring-manager'] } },
 }
 ```
 
@@ -243,10 +244,10 @@ 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 named actions
+  createable: ['candidateId', 'jobId', 'notes'],
+  updatable: ['notes'],
+  immutable: ['appliedAt'],
+  protected: { stage: ['advance-stage'] },
 }
 ```
 
@@ -281,13 +282,13 @@ export default defineTable(external_orders, {
 
 ```typescript
 masking: {
-  ssn: {
-    type: 'ssn',                          // *****6789
-    show: { roles: ['admin', 'hr'] },
-  },
   email: {
-    type: 'email',                        // p***@e******.com
-    show: { roles: ['admin'], or: 'owner' },
+    type: 'email',
+    show: { roles: ['hiring-manager', 'recruiter'] },
+  },
+  phone: {
+    type: 'phone',
+    show: { roles: ['hiring-manager', 'recruiter'] },
   },
 }
 ```
@@ -323,45 +324,89 @@ The compiler warns if sensitive columns aren't explicitly configured:
 Views are named projections that control which fields are visible based on role.
 
 ```typescript
-export default defineTable(customers, {
+export default defineTable(candidates, {
   // ... firewall, guards, etc.
 
   views: {
-    summary: {
-      fields: ['id', 'name', 'email'],
-      access: { roles: ['member', 'admin'] },
+    pipeline: {
+      fields: ['id', 'name', 'email', 'source'],
+      access: { roles: ['owner', 'hiring-manager', 'recruiter', 'interviewer'] },
     },
     full: {
-      fields: ['id', 'name', 'email', 'phone', 'ssn', 'address'],
-      access: { roles: ['admin'] },
+      fields: ['id', 'name', 'email', 'phone', 'resumeUrl', 'source'],
+      access: { roles: ['owner', 'hiring-manager', 'recruiter'] },
     },
   },
 });
 ```
 
 **Generated endpoints**:
-- `GET /api/v1/customers/views/summary` — returns only id, name, email
-- `GET /api/v1/customers/views/full` — returns all fields (admin only)
+- `GET /api/v1/candidates/views/pipeline` — returns only id, name, email, source
+- `GET /api/v1/candidates/views/full` — returns all fields (recruiters and above)
 
 Views support the same query parameters as list (filtering, sorting, pagination). Masking still applies to returned fields.
 
 ---
 
+# References — FK Target Mapping
+
+When FK columns don't match the target table name by convention (e.g., `vendorId` points to the `contact` table), declare explicit references:
+
+```typescript
+export default defineTable(items, {
+  references: {
+    clientId: "contact",
+    vendorId: "contact",
+    salesCodeId: "salesCode",
+    taxLocationId: "taxLocation",
+  },
+  // ...
+});
+```
+
+Each key is a column name ending in `Id`, value is the camelCase target table name. These flow into schema-registry.json as `fkTarget` on each column, enabling the CMS to render typeahead/lookup inputs.
+
+Convention-based matching (strip `Id` suffix) still works for simple cases like `projectId` → `project`. Use `references` only when the convention doesn't match.
+
+---
+
+# Input Hints — CMS Form Controls
+
+Control how the CMS renders form inputs for specific columns:
+
+```typescript
+export default defineTable(invoice, {
+  inputHints: {
+    status: "select",
+    sortOrder: "radio",
+    isPartialPaymentDisabled: "checkbox",
+    headerMessage: "textarea",
+    footerMessage: "textarea",
+  },
+  // ...
+});
+```
+
+Available values: `select`, `multi-select`, `radio`, `checkbox`, `textarea`, `lookup`, `hidden`, `color`, `date`, `datetime`, `time`, `currency`.
+
+Input hints are emitted in schema-registry.json as `inputHints` on the table metadata.
+
+---
+
 # Validation
 
 Field-level validation rules compiled into the API:
 
 ```typescript
-export default defineTable(rooms, {
+export default defineTable(jobs, {
   // ... 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}$' },
+    title: { minLength: 1, maxLength: 200 },
+    department: { minLength: 1, maxLength: 100 },
+    status: { enum: ['draft', 'open', 'closed'] },
+    salaryMin: { min: 0 },
+    salaryMax: { min: 0 },
   },
 });
 ```
@@ -373,51 +418,54 @@ export default defineTable(rooms, {
 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';
+// quickback/features/applications/actions.ts
+import { applications } from './applications';
 import { defineActions } from '@quickback/compiler';
 import { z } from 'zod';
 
-export default defineActions(todos, {
-  complete: {
-    description: "Mark todo as complete",
+export default defineActions(applications, {
+  'advance-stage': {
+    description: "Move application to the next pipeline stage",
     input: z.object({
-      completedAt: z.string().datetime().optional(),
+      stage: z.enum(["screening", "interview", "offer", "hired"]),
+      notes: z.string().optional(),
     }),
-    guard: {
-      roles: ["member", "admin"],
-      record: { completed: { equals: false } },
+    access: {
+      roles: ["owner", "hiring-manager"],
+      record: { stage: { notEquals: "rejected" } },
     },
     execute: async ({ db, record, ctx, input }) => {
-      // Inline handler
-      await db.update(todos).set({ completed: true }).where(eq(todos.id, record.id));
-      return { success: true };
+      const [updated] = await db.update(applications)
+        .set({ stage: input.stage, notes: input.notes ?? record.notes })
+        .where(eq(applications.id, record.id))
+        .returning();
+      return updated;
     },
     sideEffects: "sync",
   },
 
-  archive: {
-    description: "Archive a todo",
-    input: z.object({}),
-    guard: { roles: ["admin"] },
-    handler: "./handlers/archive",  // OR: external file handler
+  reject: {
+    description: "Reject an application",
+    input: z.object({ reason: z.string() }),
+    access: { roles: ["owner", "hiring-manager"] },
+    handler: "./handlers/reject",  // OR: external file handler
   },
 });
 ```
 
-**Generated Route**: `POST /api/v1/todos/:id/complete`
+**Generated Route**: `POST /api/v1/applications/:id/advance-stage`
 
 ### 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",
+'advance-stage': {
+  description: "Move application to the next pipeline stage",
+  input: z.object({ stage: z.enum(["screening", "interview", "offer", "hired"]) }),
+  access: { roles: ["owner", "hiring-manager"] },
+  handler: "./handlers/advance-stage",
 }
-// → POST /api/v1/invoices/:id/approve
+// → POST /api/v1/applications/:id/advance-stage
 ```
 
 **Standalone** — custom endpoint not tied to a record:
@@ -428,10 +476,10 @@ chat: {
   method: "POST",
   responseType: "stream",
   input: z.object({ message: z.string() }),
-  guard: { roles: ["member"] },
+  access: { roles: ["recruiter", "hiring-manager"] },
   handler: "./handlers/chat",
 }
-// → POST /api/v1/todos/chat
+// → POST /api/v1/applications/chat
 ```
 
 ### Action Options
@@ -535,7 +583,7 @@ OR'd LIKE across all `text()` schema columns (system columns excluded). Combine
 
 ```json
 {
-  "data": [{ "id": "...", "title": "Todo 1" }],
+  "data": [{ "id": "...", "name": "Jane Smith", "source": "linkedin" }],
   "pagination": {
     "limit": 10,
     "offset": 0,
@@ -718,16 +766,15 @@ Detect from `quickback.config.ts` and use the correct imports:
 
 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)
+- [Getting Started](https://docs.quickback.dev/compiler/getting-started)
+- [Concepts](https://docs.quickback.dev/compiler/definitions/concepts)
+- [Full Example](https://docs.quickback.dev/compiler/getting-started/full-example)
+- [Database Schema](https://docs.quickback.dev/compiler/definitions/schema)
+- [CRUD & API](https://docs.quickback.dev/compiler/using-the-api)
+- [Views](https://docs.quickback.dev/compiler/definitions/views)
+- [Actions](https://docs.quickback.dev/compiler/definitions/actions)
+- [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)
+- [CLI Reference](https://docs.quickback.dev/compiler/cloud-compiler/cli)

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

@@ -51,35 +51,37 @@ Detect the database dialect from `quickback.config.ts`:
 ### Table Definition Pattern
 
 ```typescript
-import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+import { sqliteTable, text } 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(),
+export const candidates = sqliteTable("candidates", {
+  id: text("id").primaryKey(),
   organizationId: text("organization_id").notNull(),
+  name: text("name").notNull(),
+  email: text("email").notNull(),
+  phone: text("phone"),
+  resumeUrl: text("resume_url"),
+  source: text("source"),
 });
 
-export default defineTable(todos, {
+export default defineTable(candidates, {
   firewall: {
-    organization: {},    // Auto-detects 'organizationId' column
-    owner: {},           // Auto-detects 'userId' column
+    organization: {},
   },
   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" },
+    list: { access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] } },
+    get: { access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] } },
+    create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
+    update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
+    delete: { access: { roles: ["owner", "hiring-manager"] }, mode: "soft" },
   },
   guards: {
-    createable: ["title", "completed"],
-    updatable: ["title", "completed"],
+    createable: ["name", "email", "phone", "resumeUrl", "source"],
+    updatable: ["name", "phone"],
   },
   masking: {
-    userId: { type: "redact", show: { roles: ["admin"] } },
+    email: { type: "email", show: { roles: ["hiring-manager", "recruiter"] } },
+    phone: { type: "phone", show: { roles: ["hiring-manager", "recruiter"] } },
   },
 });
 ```
@@ -87,24 +89,28 @@ export default defineTable(todos, {
 ### Actions Pattern
 
 ```typescript
-// quickback/features/todos/actions.ts
-import { todos } from './todos';
+// quickback/features/applications/actions.ts
+import { applications } from './applications';
 import { defineActions } from '@quickback/compiler';
 import { z } from 'zod';
 
-export default defineActions(todos, {
-  complete: {
-    description: "Mark todo as complete",
+export default defineActions(applications, {
+  'advance-stage': {
+    description: "Move application to the next pipeline stage",
     input: z.object({
-      completedAt: z.string().datetime().optional(),
+      stage: z.enum(["screening", "interview", "offer", "hired"]),
+      notes: z.string().optional(),
     }),
-    guard: {
-      roles: ["member", "admin"],
-      record: { completed: { equals: false } },
+    access: {
+      roles: ["owner", "hiring-manager"],
+      record: { stage: { notEquals: "rejected" } },
     },
     execute: async ({ db, record, ctx, input }) => {
-      await db.update(todos).set({ completed: true }).where(eq(todos.id, record.id));
-      return { success: true };
+      const [updated] = await db.update(applications)
+        .set({ stage: input.stage, notes: input.notes ?? record.notes })
+        .where(eq(applications.id, record.id))
+        .returning();
+      return updated;
     },
   },
 });
@@ -137,29 +143,29 @@ firewall: {
 ### Workflow with protected status
 ```typescript
 guards: {
-  protected: { status: ['approve', 'reject'] }
+  protected: { stage: ['advance-stage', 'reject'] }
 }
-// Plus defineActions() for approve/reject
+// Plus defineActions() for advance-stage/reject
 ```
 
 ### PII masking
 ```typescript
 masking: {
-  email: { type: 'email', show: { roles: ['admin'] } },
-  ssn: { type: 'ssn', show: { roles: ['hr'] } }
+  email: { type: 'email', show: { roles: ['hiring-manager', 'recruiter'] } },
+  phone: { type: 'phone', show: { roles: ['hiring-manager', 'recruiter'] } },
 }
 ```
 
 ### Views (column-level security)
 ```typescript
 views: {
-  summary: {
-    fields: ['id', 'name', 'email'],
-    access: { roles: ['member', 'admin'] },
+  pipeline: {
+    fields: ['id', 'name', 'source', 'stage'],
+    access: { roles: ['owner', 'hiring-manager', 'recruiter', 'interviewer'] },
   },
   full: {
-    fields: ['id', 'name', 'email', 'phone', 'ssn'],
-    access: { roles: ['admin'] },
+    fields: ['id', 'name', 'email', 'phone', 'resumeUrl', 'source', 'stage'],
+    access: { roles: ['owner', 'hiring-manager', 'recruiter'] },
   },
 }
 ```
@@ -173,7 +179,7 @@ chat: {
   method: "POST",
   responseType: "stream",
   input: z.object({ message: z.string() }),
-  guard: { roles: ["member"] },
+  access: { roles: ["recruiter", "hiring-manager"] },
   handler: "./handlers/chat",
 }
 ```