@quickback-dev/cli 0.10.4 → 0.10.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +12 -3
- package/dist/commands/compile.js.map +1 -1
- package/dist/commands/create.js +108 -55
- package/dist/commands/create.js.map +1 -1
- package/dist/cursor/quickback.mdc +37 -33
- package/dist/docs/content.js +7 -7
- package/dist/docs/content.js.map +1 -1
- package/dist/lib/api-client.d.ts +19 -2
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/file-loader.d.ts +39 -5
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +226 -63
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-loader.test.js +212 -1
- package/dist/lib/file-loader.test.js.map +1 -1
- package/dist/skill/SKILL.md +111 -80
- package/dist/skill/agents/quickback-specialist/AGENT.md +60 -54
- package/package.json +14 -14
- package/src/cursor/quickback.mdc +37 -33
- package/src/skill/SKILL.md +111 -80
- package/src/skill/agents/quickback-specialist/AGENT.md +60 -54
package/src/skill/SKILL.md
CHANGED
|
@@ -58,8 +58,10 @@ my-app/
|
|
|
58
58
|
│ └── features/
|
|
59
59
|
│ └── {feature-name}/
|
|
60
60
|
│ ├── {table}.ts # Schema + security (defineTable)
|
|
61
|
-
│ ├── actions
|
|
62
|
-
│ ├──
|
|
61
|
+
│ ├── actions/ # One file per action — defineAction({...})
|
|
62
|
+
│ │ ├── {action}.ts # Binds to primary table (or standalone if path: is set)
|
|
63
|
+
│ │ └── {table}/{action}.ts # Binds to sibling <table>.ts (multi-table features)
|
|
64
|
+
│ ├── lib/ # Feature-local helpers, copied verbatim (optional)
|
|
63
65
|
│ └── pages/ # Custom CMS pages (optional)
|
|
64
66
|
│ └── {slug}.ts # definePage() call
|
|
65
67
|
├── src/ # ← compiled output
|
|
@@ -90,11 +92,11 @@ export default defineConfig({
|
|
|
90
92
|
tagline: "Build faster, ship sooner",
|
|
91
93
|
build: true, // Set false to skip SPA rebuild on subsequent compiles
|
|
92
94
|
auth: {
|
|
93
|
-
password: true, // Email/password login (default:
|
|
94
|
-
emailOTP: true, // Email OTP login (default:
|
|
95
|
-
passkey: true, // WebAuthn passkeys (default:
|
|
95
|
+
password: true, // Email/password login (default: true)
|
|
96
|
+
emailOTP: true, // Email OTP login (default: false)
|
|
97
|
+
passkey: true, // WebAuthn passkeys (default: false)
|
|
96
98
|
signup: true, // User registration (default: true)
|
|
97
|
-
organizations: true, // Multi-tenant org management (default: true)
|
|
99
|
+
organizations: true, // Multi-tenant org management UI (default: false; the orgs plugin itself is enabled by `features.organizations` which defaults true)
|
|
98
100
|
admin: true, // Admin panel (default: true)
|
|
99
101
|
emailVerification: true, // Require email verification (default: true)
|
|
100
102
|
},
|
|
@@ -310,22 +312,28 @@ export const roomAmenities = q.table('roomAmenities', {
|
|
|
310
312
|
|
|
311
313
|
The compiler warns once per such table so you confirm the opt-out is intentional.
|
|
312
314
|
|
|
313
|
-
###
|
|
315
|
+
### Action files use `q.*` for query helpers too
|
|
314
316
|
|
|
315
|
-
|
|
317
|
+
Action `execute` functions query via the same `q` namespace:
|
|
316
318
|
|
|
317
319
|
```typescript
|
|
318
|
-
// quickback/features/mail/
|
|
320
|
+
// quickback/features/mail/actions/inbound.ts
|
|
321
|
+
import { defineAction } from "../.quickback/define-action";
|
|
319
322
|
import { q } from "../../../lib/q";
|
|
320
|
-
import mailboxes from "../mailboxes";
|
|
321
|
-
import messages from "../messages";
|
|
322
|
-
|
|
323
|
-
export
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
323
|
+
import { mailboxes } from "../mailboxes";
|
|
324
|
+
import { messages } from "../messages";
|
|
325
|
+
|
|
326
|
+
export default defineAction({
|
|
327
|
+
description: "Process inbound mail",
|
|
328
|
+
path: "/inbound",
|
|
329
|
+
/* ... */
|
|
330
|
+
async execute({ unsafeDb, input }) {
|
|
331
|
+
const mailbox = await unsafeDb.query.mailboxes.findFirst({
|
|
332
|
+
where: q.eq(mailboxes.address, input.mailboxAddress),
|
|
333
|
+
});
|
|
334
|
+
// …
|
|
335
|
+
},
|
|
336
|
+
});
|
|
329
337
|
```
|
|
330
338
|
|
|
331
339
|
Available: `q.and`, `q.or`, `q.not`, `q.eq`, `q.ne`, `q.gt`, `q.gte`, `q.lt`, `q.lte`, `q.like`, `q.ilike`, `q.inArray`, `q.notInArray`, `q.isNull`, `q.isNotNull`, `q.between`, `q.desc`, `q.asc`, `q.sql`. Pure re-export of Drizzle's query builder under the Quickback namespace — users can still `import { eq } from "drizzle-orm"` directly if they prefer.
|
|
@@ -350,18 +358,18 @@ export const execute = async ({ unsafeDb, input }) => {
|
|
|
350
358
|
|
|
351
359
|
### Import style
|
|
352
360
|
|
|
353
|
-
With `feature()`, tables are **default exports** — use default imports
|
|
361
|
+
With `feature()`, tables are **default exports** — use default imports:
|
|
354
362
|
|
|
355
363
|
```typescript
|
|
356
|
-
// features/applications/actions.ts
|
|
357
|
-
import applications from "
|
|
358
|
-
import {
|
|
364
|
+
// features/applications/actions/advance.ts
|
|
365
|
+
import applications from "../applications";
|
|
366
|
+
import { defineAction } from "../.quickback/define-action";
|
|
359
367
|
```
|
|
360
368
|
|
|
361
|
-
With the two-export form, tables are **named exports** — use named imports:
|
|
369
|
+
With the two-export form (`defineTable`), tables are **named exports** — use named imports:
|
|
362
370
|
|
|
363
371
|
```typescript
|
|
364
|
-
import { applications } from "
|
|
372
|
+
import { applications } from "../applications";
|
|
365
373
|
```
|
|
366
374
|
|
|
367
375
|
Both produce the same typed handle.
|
|
@@ -663,41 +671,47 @@ Docs: `quickback docs account-ui` | https://docs.quickback.dev/account-ui
|
|
|
663
671
|
|
|
664
672
|
## Actions — Custom Business Logic
|
|
665
673
|
|
|
666
|
-
Defined
|
|
674
|
+
Defined with `defineAction()` (singular). Per-action permissions live under `access:` (same shape as resource-level access).
|
|
675
|
+
|
|
676
|
+
**One file per action.** Each action is its own module under the feature's `actions/` directory:
|
|
677
|
+
|
|
678
|
+
- `actions/<name>.ts` — binds to the feature's primary table (the `<feature>.ts` file at the feature root). If `path:` is set, becomes a standalone action.
|
|
679
|
+
- `actions/<table>/<name>.ts` — binds to the sibling table file `<table>.ts` at the feature root. Use this in multi-table features.
|
|
680
|
+
|
|
681
|
+
The action's filename (sans `.ts`) is the action name AND the URL segment. Uniqueness is enforced per **`(bound table, name)` pair** — sibling-bound actions on different tables may share a verb (e.g. `actions/episodes/publish.ts` + `actions/shows/publish.ts` mount at `/episodes/:id/publish` and `/shows/:id/publish`). The compiler errors only when two action files would mount at the same URL.
|
|
682
|
+
|
|
683
|
+
For shared Zod schemas or helpers, put them under `<feature>/lib/` and import from each action file.
|
|
684
|
+
|
|
685
|
+
**Retired layouts** (rejected at load time with migration guidance): `actions.ts` (bundle), `_feature.ts`, `handlers/` directory, `defineActions(table, {...})`, `defineActions(null, {...})`, `*-actions.ts` / `*.actions.ts` filenames.
|
|
686
|
+
|
|
687
|
+
`execute:` must be an **async arrow function** (`async (ctx) => { … }`). `async function` declarations and non-async forms are rejected at parse time.
|
|
667
688
|
|
|
668
689
|
```typescript
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
import {
|
|
672
|
-
import { q } from
|
|
673
|
-
import
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
}
|
|
686
|
-
sideEffects: "sync",
|
|
687
|
-
},
|
|
688
|
-
archive: {
|
|
689
|
-
description: "Archive a todo",
|
|
690
|
-
input: z.object({}),
|
|
691
|
-
access: { roles: ["admin"] },
|
|
692
|
-
handler: "./handlers/archive",
|
|
690
|
+
// features/todos/actions/complete.ts
|
|
691
|
+
import { z } from "zod";
|
|
692
|
+
import { defineAction } from "../.quickback/define-action";
|
|
693
|
+
import { q } from "../../../lib/q"; // generated namespace; same as drizzle-orm
|
|
694
|
+
import todos from "../todos"; // default import: feature() exports
|
|
695
|
+
// import { todos } from "../todos"; // named import: two-export form
|
|
696
|
+
|
|
697
|
+
export default defineAction({
|
|
698
|
+
description: "Mark todo as complete",
|
|
699
|
+
input: z.object({ completedAt: z.string().datetime().optional() }),
|
|
700
|
+
access: { roles: ["member", "admin"], record: { completed: { equals: false } } },
|
|
701
|
+
sideEffects: "sync",
|
|
702
|
+
async execute({ db, record, whereRecord, auditFields }) {
|
|
703
|
+
await db.update(todos)
|
|
704
|
+
.set({ completed: true, modifiedAt: auditFields!.modifiedAt })
|
|
705
|
+
.where(whereRecord!(todos)); // firewall + soft-delete + id, in one
|
|
706
|
+
return { success: true };
|
|
693
707
|
},
|
|
694
708
|
});
|
|
695
709
|
```
|
|
696
710
|
|
|
697
|
-
**Record-based** (
|
|
698
|
-
**Standalone
|
|
711
|
+
**Record-based** (no `path:`): `POST /api/v1/{resource}/:id/{action}` — record is loaded, firewall + access checks run, then `execute` is called with `record`, `whereRecord`, scoped `db`.
|
|
712
|
+
**Standalone** (`path:` set): custom `path` and `method`. No record context, no firewall preload.
|
|
699
713
|
|
|
700
|
-
Action options: `
|
|
714
|
+
Action options: `path`, `method` (GET/POST/PUT/PATCH/DELETE), `responseType` (json/stream/file), `sideEffects` (sync/async/fire-and-forget), `transition`, `unsafe`, `allowRawSql`, `cms`.
|
|
701
715
|
|
|
702
716
|
### `whereRecord(table)` — explicit, scope-safe WHERE
|
|
703
717
|
|
|
@@ -708,7 +722,12 @@ In record-based actions, `whereRecord(table)` returns a Drizzle expression that
|
|
|
708
722
|
For protected fields that follow a state machine (status, lifecycle, fulfilment), enforce the *from/to pair*, not just the current state. Without `transition`, an `advance` action whose access allows `status in ['applied', 'screening']` will happily run `applied → offer` (a skip) or `screening → applied` (a regression).
|
|
709
723
|
|
|
710
724
|
```typescript
|
|
711
|
-
advance
|
|
725
|
+
// features/applications/actions/advance.ts
|
|
726
|
+
import { z } from "zod";
|
|
727
|
+
import { defineAction } from "../.quickback/define-action";
|
|
728
|
+
import { applications } from "../applications";
|
|
729
|
+
|
|
730
|
+
export default defineAction({
|
|
712
731
|
description: "Move application forward",
|
|
713
732
|
input: z.object({ nextStatus: z.enum(['screening', 'interview', 'offer']) }),
|
|
714
733
|
access: { roles: ['owner', 'admin'] },
|
|
@@ -721,9 +740,18 @@ advance: {
|
|
|
721
740
|
interview: ['offer'],
|
|
722
741
|
},
|
|
723
742
|
},
|
|
724
|
-
|
|
725
|
-
}
|
|
726
|
-
|
|
743
|
+
async execute({ db, record, input, auditFields, whereTransition }) { /* … */ },
|
|
744
|
+
});
|
|
745
|
+
```
|
|
746
|
+
|
|
747
|
+
```typescript
|
|
748
|
+
// features/applications/actions/hire.ts
|
|
749
|
+
import { z } from "zod";
|
|
750
|
+
import { defineAction } from "../.quickback/define-action";
|
|
751
|
+
import { applications } from "../applications";
|
|
752
|
+
|
|
753
|
+
export default defineAction({
|
|
754
|
+
description: "Finalize an offer",
|
|
727
755
|
input: z.object({}),
|
|
728
756
|
access: { roles: ['owner'] },
|
|
729
757
|
transition: {
|
|
@@ -731,8 +759,8 @@ hire: {
|
|
|
731
759
|
to: 'hired', // fixed target — same value every call
|
|
732
760
|
fromTo: { offer: ['hired'] },
|
|
733
761
|
},
|
|
734
|
-
|
|
735
|
-
}
|
|
762
|
+
async execute({ db, record, auditFields, whereTransition }) { /* … */ },
|
|
763
|
+
});
|
|
736
764
|
```
|
|
737
765
|
|
|
738
766
|
Exactly one of `via` or `to` must be provided. On a bad transition the runtime returns **409 `ACCESS_ACTION_NOT_ALLOWED_FOR_STATE`** with `field`, `current`, `target`, `allowedTargets`. The same 409 fires when a plain `access.record` precondition fails (was 403 before — splitting it lets clients tell *"you can't do this"* from *"you can't do this **yet**"*).
|
|
@@ -742,25 +770,31 @@ Exactly one of `via` or `to` must be provided. On a bad transition the runtime r
|
|
|
742
770
|
For platform-level support / cross-tenant operations, opt out of the scoped DB. The object form is required for new code — it makes the policy explicit and forces an audit reason:
|
|
743
771
|
|
|
744
772
|
```typescript
|
|
745
|
-
|
|
773
|
+
// features/admin/actions/admin-report.ts
|
|
774
|
+
import { z } from "zod";
|
|
775
|
+
import { defineAction } from "../.quickback/define-action";
|
|
776
|
+
import { applications } from "../../applications/applications";
|
|
777
|
+
|
|
778
|
+
export default defineAction({
|
|
746
779
|
description: "Cross-org hiring report",
|
|
780
|
+
path: "/admin/cross-org-report",
|
|
781
|
+
input: z.object({ startDate: z.string() }),
|
|
782
|
+
access: { roles: ['owner'] },
|
|
747
783
|
unsafe: {
|
|
748
784
|
reason: "Support investigation for enterprise customer",
|
|
749
785
|
adminOnly: true, // default true — gates on ctx.userRole === 'admin'
|
|
750
786
|
crossTenant: true, // default true — bypasses firewall
|
|
751
787
|
targetScope: 'all', // 'all' | 'organization'
|
|
752
788
|
},
|
|
753
|
-
|
|
754
|
-
access: { roles: ['owner'] },
|
|
755
|
-
execute: async ({ db, unsafeDb, ctx, input }) => {
|
|
789
|
+
async execute({ db, unsafeDb, ctx, input }) {
|
|
756
790
|
// db is still scoped (safety net for accidental writes)
|
|
757
791
|
// unsafeDb bypasses scoped filters
|
|
758
792
|
return await unsafeDb.select().from(applications);
|
|
759
793
|
},
|
|
760
|
-
}
|
|
794
|
+
});
|
|
761
795
|
```
|
|
762
796
|
|
|
763
|
-
Generated runtime auto-injects: Better Auth required, platform admin gate, mandatory audit logging on deny/success/error. Without unsafe mode, `unsafeDb` is `undefined`.
|
|
797
|
+
Generated runtime auto-injects: Better Auth required, platform admin gate, mandatory audit logging on deny/success/error. Without unsafe mode, `unsafeDb` is `undefined`.
|
|
764
798
|
|
|
765
799
|
### Soft-delete cascade (cross-feature)
|
|
766
800
|
|
|
@@ -768,28 +802,25 @@ When a parent is soft-deleted, every child table that holds an FK to it — both
|
|
|
768
802
|
|
|
769
803
|
### Actions-Only Features
|
|
770
804
|
|
|
771
|
-
|
|
805
|
+
A feature directory with no top-level `*.ts` files is "tableless" — every action under `actions/` must be standalone (have `path:`). Use this for utility endpoints like webhooks, reports, or integrations.
|
|
772
806
|
|
|
773
807
|
```typescript
|
|
774
|
-
// quickback/features/utilities/actions.ts
|
|
775
|
-
import {
|
|
776
|
-
import {
|
|
777
|
-
|
|
778
|
-
export default
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
handler: "./handlers/health-check",
|
|
808
|
+
// quickback/features/utilities/actions/health-check.ts
|
|
809
|
+
import { z } from "zod";
|
|
810
|
+
import { defineAction } from "../.quickback/define-action";
|
|
811
|
+
|
|
812
|
+
export default defineAction({
|
|
813
|
+
description: "Health check endpoint",
|
|
814
|
+
path: "/health",
|
|
815
|
+
method: "GET",
|
|
816
|
+
input: z.object({}),
|
|
817
|
+
access: { roles: ["member", "admin"] },
|
|
818
|
+
async execute() {
|
|
819
|
+
return { ok: true };
|
|
787
820
|
},
|
|
788
821
|
});
|
|
789
822
|
```
|
|
790
823
|
|
|
791
|
-
All actions in an actions-only feature must have `standalone: true` (since there's no table for record-based actions).
|
|
792
|
-
|
|
793
824
|
---
|
|
794
825
|
|
|
795
826
|
## API Reference
|
|
@@ -16,7 +16,7 @@ You deeply understand:
|
|
|
16
16
|
- **Access**: Role-based and record-level permissions (deny by default)
|
|
17
17
|
- **Guards**: Field protection (createable, updatable, immutable, protected)
|
|
18
18
|
- **Masking**: PII redaction with role-based visibility and auto-detection
|
|
19
|
-
- **Actions**: Custom endpoints using `
|
|
19
|
+
- **Actions**: Custom endpoints using `defineAction()` (one file per action under `actions/`)
|
|
20
20
|
- **Views**: Column-level security with named projections
|
|
21
21
|
- **Validation**: Field-level validation rules
|
|
22
22
|
- **Layouts**: CMS record page field grouping with sections, columns, and collapsed state
|
|
@@ -33,7 +33,7 @@ You deeply understand:
|
|
|
33
33
|
3. **Generate complete configuration** including:
|
|
34
34
|
- Drizzle schema with correct dialect
|
|
35
35
|
- `defineTable()` with all security layers in a single file
|
|
36
|
-
- Actions via `
|
|
36
|
+
- Actions via `defineAction()` — one file per action under `actions/<name>.ts` (if needed)
|
|
37
37
|
4. **Validate the configuration** - Check for common mistakes
|
|
38
38
|
5. **Explain your decisions** - Help users understand the security model
|
|
39
39
|
|
|
@@ -43,8 +43,8 @@ Schema + security config in a single file using `defineTable()`.
|
|
|
43
43
|
|
|
44
44
|
Generate files in `quickback/features/{name}/`:
|
|
45
45
|
- `{table}.ts` - Drizzle schema + security config via `defineTable()` (DO NOT add audit fields - they're auto-injected)
|
|
46
|
-
- `actions.ts` -
|
|
47
|
-
- `
|
|
46
|
+
- `actions/{action}.ts` - One file per custom action via `defineAction()` (if needed)
|
|
47
|
+
- `lib/` - Shared Zod schemas / helpers, copied verbatim into the generated output (if needed)
|
|
48
48
|
|
|
49
49
|
When explaining compile outputs:
|
|
50
50
|
- Runtime outputs remain in `build.outputDir`.
|
|
@@ -89,35 +89,37 @@ For Drizzle interop (bringing forward existing schemas), use `sqliteTable` + `de
|
|
|
89
89
|
|
|
90
90
|
### Actions Pattern
|
|
91
91
|
|
|
92
|
-
Per-action permissions live under `access:` (same shape as resource-level access). Use `whereRecord(table)` for protected-field writes — it AND-merges firewall + soft-delete + the record id in one expression.
|
|
92
|
+
One file per action under `actions/<name>.ts`. The filename (sans `.ts`) is the action name AND URL segment. Per-action permissions live under `access:` (same shape as resource-level access). Use `whereRecord(table)` for protected-field writes — it AND-merges firewall + soft-delete + the record id in one expression.
|
|
93
|
+
|
|
94
|
+
`actions/<name>.ts` binds to the feature's primary table (the `<feature>.ts` file). For multi-table features, use `actions/<table>/<name>.ts` to bind to a sibling table. Setting `path:` makes the action standalone.
|
|
93
95
|
|
|
94
96
|
```typescript
|
|
95
|
-
// quickback/features/todos/actions.ts
|
|
96
|
-
import
|
|
97
|
-
import {
|
|
98
|
-
import
|
|
99
|
-
|
|
100
|
-
export default
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
return { success: true };
|
|
115
|
-
},
|
|
97
|
+
// quickback/features/todos/actions/complete.ts
|
|
98
|
+
import { z } from "zod";
|
|
99
|
+
import { defineAction } from "../.quickback/define-action";
|
|
100
|
+
import todos from "../todos"; // default import: feature() exports
|
|
101
|
+
|
|
102
|
+
export default defineAction({
|
|
103
|
+
description: "Mark todo as complete",
|
|
104
|
+
input: z.object({
|
|
105
|
+
completedAt: z.string().datetime().optional(),
|
|
106
|
+
}),
|
|
107
|
+
access: {
|
|
108
|
+
roles: ["member", "admin"],
|
|
109
|
+
record: { completed: { equals: false } },
|
|
110
|
+
},
|
|
111
|
+
async execute({ db, record, whereRecord, auditFields }) {
|
|
112
|
+
await db.update(todos)
|
|
113
|
+
.set({ completed: true, modifiedAt: auditFields!.modifiedAt })
|
|
114
|
+
.where(whereRecord!(todos));
|
|
115
|
+
return { success: true };
|
|
116
116
|
},
|
|
117
117
|
});
|
|
118
118
|
```
|
|
119
119
|
|
|
120
|
-
For state-machine fields (status, lifecycle), add `transition: { field, via|to, fromTo }` so the runtime enforces the from→to pair and returns 409 `ACCESS_ACTION_NOT_ALLOWED_FOR_STATE` on illegal transitions. For cross-tenant or platform-level work, use `unsafe: { reason, adminOnly, crossTenant, targetScope }` (object form
|
|
120
|
+
For state-machine fields (status, lifecycle), add `transition: { field, via|to, fromTo }` so the runtime enforces the from→to pair and returns 409 `ACCESS_ACTION_NOT_ALLOWED_FOR_STATE` on illegal transitions. For cross-tenant or platform-level work, use `unsafe: { reason, adminOnly, crossTenant, targetScope }` (object form, auto-injects audit logging).
|
|
121
|
+
|
|
122
|
+
**Retired** (rejected at load time): bundled `actions.ts`, `_feature.ts`, `handlers/` directory, `defineActions()`, `*-actions.ts` filenames.
|
|
121
123
|
|
|
122
124
|
## Security Principles
|
|
123
125
|
|
|
@@ -152,7 +154,7 @@ firewall: [
|
|
|
152
154
|
guards: {
|
|
153
155
|
protected: { status: ['approve', 'reject'] }
|
|
154
156
|
}
|
|
155
|
-
// Plus
|
|
157
|
+
// Plus actions/approve.ts and actions/reject.ts via defineAction()
|
|
156
158
|
```
|
|
157
159
|
|
|
158
160
|
### PII masking
|
|
@@ -180,50 +182,54 @@ views: {
|
|
|
180
182
|
> Use `+` suffix with `auth.roleHierarchy` configured (e.g., `['member', 'admin', 'owner']`) to expand roles at compile time. `"member+"` → `["member", "admin", "owner"]`.
|
|
181
183
|
|
|
182
184
|
### Standalone actions (not record-based)
|
|
185
|
+
Setting `path:` makes an action standalone — no record loading or firewall preload.
|
|
183
186
|
```typescript
|
|
184
|
-
//
|
|
185
|
-
|
|
186
|
-
|
|
187
|
+
// features/sessions/actions/chat.ts
|
|
188
|
+
import { z } from "zod";
|
|
189
|
+
import { defineAction } from "../.quickback/define-action";
|
|
190
|
+
|
|
191
|
+
export default defineAction({
|
|
192
|
+
description: "AI chat",
|
|
187
193
|
path: "/chat",
|
|
188
194
|
method: "POST",
|
|
189
195
|
responseType: "stream",
|
|
190
196
|
input: z.object({ message: z.string() }),
|
|
191
197
|
access: { roles: ["member"] },
|
|
192
|
-
|
|
193
|
-
}
|
|
198
|
+
async execute({ input, c }) { /* … */ },
|
|
199
|
+
});
|
|
194
200
|
```
|
|
195
201
|
|
|
196
202
|
### Actions-only features (no tables)
|
|
203
|
+
A feature directory with no top-level `*.ts` files is "tableless" — every action under `actions/` must be standalone.
|
|
197
204
|
```typescript
|
|
198
|
-
// quickback/features/utilities/actions.ts
|
|
199
|
-
import {
|
|
200
|
-
import {
|
|
201
|
-
|
|
202
|
-
export default
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
access: { roles: ["member", "admin"] },
|
|
210
|
-
handler: "./handlers/health-check",
|
|
211
|
-
},
|
|
205
|
+
// quickback/features/utilities/actions/health-check.ts
|
|
206
|
+
import { z } from "zod";
|
|
207
|
+
import { defineAction } from "../.quickback/define-action";
|
|
208
|
+
|
|
209
|
+
export default defineAction({
|
|
210
|
+
description: "Health check endpoint",
|
|
211
|
+
path: "/health",
|
|
212
|
+
method: "GET",
|
|
213
|
+
input: z.object({}),
|
|
214
|
+
access: { roles: ["member", "admin"] },
|
|
215
|
+
async execute() { return { ok: true }; },
|
|
212
216
|
});
|
|
213
217
|
```
|
|
214
|
-
All actions must have `standalone: true` when there is no table.
|
|
215
218
|
|
|
216
219
|
### Public actions (no auth required)
|
|
217
220
|
Use `roles: ["PUBLIC"]` for unauthenticated endpoints. Every invocation is mandatory audit logged.
|
|
218
221
|
```typescript
|
|
219
|
-
submit
|
|
220
|
-
|
|
221
|
-
|
|
222
|
+
// features/contact/actions/submit.ts
|
|
223
|
+
import { z } from "zod";
|
|
224
|
+
import { defineAction } from "../.quickback/define-action";
|
|
225
|
+
|
|
226
|
+
export default defineAction({
|
|
222
227
|
description: "Public contact form",
|
|
228
|
+
path: "/submit",
|
|
223
229
|
input: z.object({ name: z.string(), email: z.string().email(), message: z.string() }),
|
|
224
230
|
access: { roles: ["PUBLIC"] },
|
|
225
|
-
|
|
226
|
-
}
|
|
231
|
+
async execute({ db, input }) { /* persist submission */ return { ok: true }; },
|
|
232
|
+
});
|
|
227
233
|
```
|
|
228
234
|
The wildcard `"*"` is NOT supported and will throw a compile error. Use `"PUBLIC"` explicitly.
|
|
229
235
|
|
|
@@ -280,7 +286,7 @@ Before finishing, verify:
|
|
|
280
286
|
- [ ] Layouts for CMS record page field grouping (if needed)
|
|
281
287
|
- [ ] No audit fields in schema (auto-injected)
|
|
282
288
|
- [ ] Using `defineTable()` (not separate schema.ts + resource.ts)
|
|
283
|
-
- [ ] Actions use `
|
|
289
|
+
- [ ] Actions use `defineAction()` (one file per action under `actions/`) with Zod schemas (not JSON schema)
|
|
284
290
|
- [ ] Account UI configured if auth UI needed (`account: true` or `account: { ... }`)
|
|
285
291
|
|
|
286
292
|
## Accessing Documentation
|