@quickback-dev/cli 0.10.4 → 0.10.8

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.
@@ -58,8 +58,10 @@ my-app/
58
58
  │ └── features/
59
59
  │ └── {feature-name}/
60
60
  │ ├── {table}.ts # Schema + security (defineTable)
61
- │ ├── actions.ts # Custom actions (optional)
62
- │ ├── handlers/ # Action handlers (optional)
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: false)
94
- emailOTP: true, // Email OTP login (default: true)
95
- passkey: true, // WebAuthn passkeys (default: true)
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
  },
@@ -157,11 +159,54 @@ export default defineConfig({
157
159
 
158
160
  ## Automatic Audit Fields
159
161
 
160
- Quickback automatically injects these fields into every table:
161
- - `createdAt`, `modifiedAt`, `deletedAt` (timestamps)
162
- - `createdBy`, `modifiedBy`, `deletedBy` (user IDs)
162
+ Quickback injects four **audit columns** into every table at compile time, and the runtime hard-stamps them on every write:
163
163
 
164
- **Do NOT add these to your schema files.** They are auto-injected by the compiler.
164
+ - `createdAt`, `createdBy` — set on insert
165
+ - `modifiedAt`, `modifiedBy` — set on every insert and every update
166
+
167
+ `deletedAt` / `deletedBy` are **soft-delete fields**, not audit fields. They're a separate per-table mechanism, injected only when the resource uses soft delete (the default). When `crud.delete.mode` and `crud.batchDelete.mode` are both `'hard'`, the columns aren't injected and the soft-delete firewall predicate is dropped.
168
+
169
+ **Do NOT add any of these six to your schema files.** They are injected by the compiler.
170
+
171
+ ### Caller contract (write through the request-context `db`)
172
+
173
+ The wrapper around `db` overwrites all four audit fields on every `.insert().values()` and `.set()` call — caller-supplied values are silently dropped. So in custom actions:
174
+
175
+ ✅ INSERT — set `id` and domain fields only:
176
+
177
+ ```ts
178
+ await db.insert(records).values({ id: createId(), name: input.name });
179
+ ```
180
+
181
+ ✅ UPDATE — set domain fields only:
182
+
183
+ ```ts
184
+ await db.update(records).set({ status: 'closed' }).where(...);
185
+ ```
186
+
187
+ ✅ SOFT DELETE — pass `deletedAt` as the *signal* of intent (any value works; the wrapper overwrites with `now`/`ctx.userId`):
188
+
189
+ ```ts
190
+ await db.update(records).set({ deletedAt: new Date() }).where(...);
191
+ ```
192
+
193
+ ❌ Don't pass `createdAt`, `createdBy`, `modifiedAt`, `modifiedBy`, or `deletedBy` — they're not yours to set.
194
+
195
+ ### Actor convention (`ctx.userId` for non-user writes)
196
+
197
+ The wrapper throws `audit-wrapper: <op> reached without ctx.userId` if a write reaches it without a userId. For user-driven requests, auth middleware fills it in. For non-user entry points, mint a synthetic actor id at the boundary:
198
+
199
+ | Boundary | Actor id |
200
+ |---|---|
201
+ | Inbound webhook | `system:webhook-<provider>` |
202
+ | Cron / scheduled | `system:cron-<job>` |
203
+ | Queue worker | `system:queue-<queue>` |
204
+ | Quickback platform-internal write | `system:quickback` |
205
+ | Out-of-band operator script | `system:script-<name>` |
206
+
207
+ **Inherit before you mint.** A user request that triggers cascades, hooks, or enqueues background jobs should carry the user's id through every downstream write. Only mint when there is genuinely no upstream user.
208
+
209
+ For migrations / schema repair / backfill scripts that genuinely should not be audited at all, use the unwrapped `createDb` directly instead of the request-context `db`. That bypasses the wrapper entirely; `createdBy`/`modifiedBy` will be `NULL` on those rows.
165
210
 
166
211
  ---
167
212
 
@@ -310,22 +355,28 @@ export const roomAmenities = q.table('roomAmenities', {
310
355
 
311
356
  The compiler warns once per such table so you confirm the opt-out is intentional.
312
357
 
313
- ### Handlers use `q.*` for query helpers too
358
+ ### Action files use `q.*` for query helpers too
314
359
 
315
- Custom action handlers query via the same `q` namespace:
360
+ Action `execute` functions query via the same `q` namespace:
316
361
 
317
362
  ```typescript
318
- // quickback/features/mail/handlers/inbound.ts
363
+ // quickback/features/mail/actions/inbound.ts
364
+ import { defineAction } from "../.quickback/define-action";
319
365
  import { q } from "../../../lib/q";
320
- import mailboxes from "../mailboxes";
321
- import messages from "../messages";
322
-
323
- export const execute = async ({ unsafeDb, input }) => {
324
- const mailbox = await unsafeDb.query.mailboxes.findFirst({
325
- where: q.eq(mailboxes.address, input.mailboxAddress),
326
- });
327
- // …
328
- };
366
+ import { mailboxes } from "../mailboxes";
367
+ import { messages } from "../messages";
368
+
369
+ export default defineAction({
370
+ description: "Process inbound mail",
371
+ path: "/inbound",
372
+ /* ... */
373
+ async execute({ unsafeDb, input }) {
374
+ const mailbox = await unsafeDb.query.mailboxes.findFirst({
375
+ where: q.eq(mailboxes.address, input.mailboxAddress),
376
+ });
377
+ // …
378
+ },
379
+ });
329
380
  ```
330
381
 
331
382
  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 +401,18 @@ export const execute = async ({ unsafeDb, input }) => {
350
401
 
351
402
  ### Import style
352
403
 
353
- With `feature()`, tables are **default exports** — use default imports in actions/other files:
404
+ With `feature()`, tables are **default exports** — use default imports:
354
405
 
355
406
  ```typescript
356
- // features/applications/actions.ts
357
- import applications from "./applications";
358
- import { defineActions } from "@quickback/compiler";
407
+ // features/applications/actions/advance.ts
408
+ import applications from "../applications";
409
+ import { defineAction } from "../.quickback/define-action";
359
410
  ```
360
411
 
361
- With the two-export form, tables are **named exports** — use named imports:
412
+ With the two-export form (`defineTable`), tables are **named exports** — use named imports:
362
413
 
363
414
  ```typescript
364
- import { applications } from "./applications";
415
+ import { applications } from "../applications";
365
416
  ```
366
417
 
367
418
  Both produce the same typed handle.
@@ -434,7 +485,7 @@ columns: {
434
485
  | `organizationId` / `organisationId` | `{ field: '...', equals: 'ctx.activeOrgId' }` |
435
486
  | `userId` (or `ownerId`) | `{ field: '...', equals: 'ctx.userId' }` |
436
487
  | `teamId` | `{ field: 'teamId', equals: 'ctx.activeTeamId' }` |
437
- | `deletedAt` (always present via audit injection) | `{ field: 'deletedAt', isNull: true }` |
488
+ | `deletedAt` (present whenever the resource uses soft delete, which is the default) | `{ field: 'deletedAt', isNull: true }` |
438
489
 
439
490
  - Exactly one isolation column → auto-derived.
440
491
  - Two or more → compile-time error; declare `firewall: [...]` explicitly OR use `q.scope()` to lock semantics in the source.
@@ -663,41 +714,47 @@ Docs: `quickback docs account-ui` | https://docs.quickback.dev/account-ui
663
714
 
664
715
  ## Actions — Custom Business Logic
665
716
 
666
- Defined in a separate `actions.ts` file using `defineActions()`. Per-action permissions live under `access:` (same shape as resource-level access).
717
+ Defined with `defineAction()` (singular). Per-action permissions live under `access:` (same shape as resource-level access).
718
+
719
+ **One file per action.** Each action is its own module under the feature's `actions/` directory:
720
+
721
+ - `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.
722
+ - `actions/<table>/<name>.ts` — binds to the sibling table file `<table>.ts` at the feature root. Use this in multi-table features.
723
+
724
+ 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.
725
+
726
+ For shared Zod schemas or helpers, put them under `<feature>/lib/` and import from each action file.
727
+
728
+ **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.
729
+
730
+ `execute:` must be an **async arrow function** (`async (ctx) => { … }`). `async function` declarations and non-async forms are rejected at parse time.
667
731
 
668
732
  ```typescript
669
- import todos from './todos'; // default import: feature() exports
670
- // import { todos } from './todos'; // named import: two-export form
671
- import { defineActions } from '@quickback/compiler';
672
- import { q } from '../../lib/q'; // generated namespace; same as drizzle-orm
673
- import { z } from 'zod';
674
-
675
- export default defineActions(todos, {
676
- complete: {
677
- description: "Mark todo as complete",
678
- input: z.object({ completedAt: z.string().datetime().optional() }),
679
- access: { roles: ["member", "admin"], record: { completed: { equals: false } } },
680
- execute: async ({ db, record, whereRecord, auditFields }) => {
681
- await db.update(todos)
682
- .set({ completed: true, modifiedAt: auditFields.modifiedAt })
683
- .where(whereRecord!(todos)); // firewall + soft-delete + id, in one
684
- return { success: true };
685
- },
686
- sideEffects: "sync",
687
- },
688
- archive: {
689
- description: "Archive a todo",
690
- input: z.object({}),
691
- access: { roles: ["admin"] },
692
- handler: "./handlers/archive",
733
+ // features/todos/actions/complete.ts
734
+ import { z } from "zod";
735
+ import { defineAction } from "../.quickback/define-action";
736
+ import { q } from "../../../lib/q"; // generated namespace; same as drizzle-orm
737
+ import todos from "../todos"; // default import: feature() exports
738
+ // import { todos } from "../todos"; // named import: two-export form
739
+
740
+ export default defineAction({
741
+ description: "Mark todo as complete",
742
+ input: z.object({ completedAt: z.string().datetime().optional() }),
743
+ access: { roles: ["member", "admin"], record: { completed: { equals: false } } },
744
+ sideEffects: "sync",
745
+ async execute({ db, record, whereRecord, auditFields }) {
746
+ await db.update(todos)
747
+ .set({ completed: true, modifiedAt: auditFields!.modifiedAt })
748
+ .where(whereRecord!(todos)); // firewall + soft-delete + id, in one
749
+ return { success: true };
693
750
  },
694
751
  });
695
752
  ```
696
753
 
697
- **Record-based** (default): `POST /api/v1/{resource}/:id/{action}` — record is loaded, firewall + access checks run, then `execute` is called with `record`, `whereRecord`, scoped `db`.
698
- **Standalone**: `standalone: true`, custom `path` and `method`. No record context, no firewall preload.
754
+ **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`.
755
+ **Standalone** (`path:` set): custom `path` and `method`. No record context, no firewall preload.
699
756
 
700
- Action options: `standalone`, `method` (GET/POST/PUT/PATCH/DELETE), `responseType` (json/stream/file), `sideEffects` (sync/async/fire-and-forget), `transition`, `unsafe`, `allowRawSql`.
757
+ Action options: `path`, `method` (GET/POST/PUT/PATCH/DELETE), `responseType` (json/stream/file), `sideEffects` (sync/async/fire-and-forget), `transition`, `unsafe`, `allowRawSql`, `cms`.
701
758
 
702
759
  ### `whereRecord(table)` — explicit, scope-safe WHERE
703
760
 
@@ -708,7 +765,12 @@ In record-based actions, `whereRecord(table)` returns a Drizzle expression that
708
765
  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
766
 
710
767
  ```typescript
711
- advance: {
768
+ // features/applications/actions/advance.ts
769
+ import { z } from "zod";
770
+ import { defineAction } from "../.quickback/define-action";
771
+ import { applications } from "../applications";
772
+
773
+ export default defineAction({
712
774
  description: "Move application forward",
713
775
  input: z.object({ nextStatus: z.enum(['screening', 'interview', 'offer']) }),
714
776
  access: { roles: ['owner', 'admin'] },
@@ -721,9 +783,18 @@ advance: {
721
783
  interview: ['offer'],
722
784
  },
723
785
  },
724
- handler: './handlers/advance',
725
- },
726
- hire: {
786
+ async execute({ db, record, input, auditFields, whereTransition }) { /* … */ },
787
+ });
788
+ ```
789
+
790
+ ```typescript
791
+ // features/applications/actions/hire.ts
792
+ import { z } from "zod";
793
+ import { defineAction } from "../.quickback/define-action";
794
+ import { applications } from "../applications";
795
+
796
+ export default defineAction({
797
+ description: "Finalize an offer",
727
798
  input: z.object({}),
728
799
  access: { roles: ['owner'] },
729
800
  transition: {
@@ -731,8 +802,8 @@ hire: {
731
802
  to: 'hired', // fixed target — same value every call
732
803
  fromTo: { offer: ['hired'] },
733
804
  },
734
- handler: './handlers/hire',
735
- },
805
+ async execute({ db, record, auditFields, whereTransition }) { /* … */ },
806
+ });
736
807
  ```
737
808
 
738
809
  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 +813,31 @@ Exactly one of `via` or `to` must be provided. On a bad transition the runtime r
742
813
  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
814
 
744
815
  ```typescript
745
- adminReport: {
816
+ // features/admin/actions/admin-report.ts
817
+ import { z } from "zod";
818
+ import { defineAction } from "../.quickback/define-action";
819
+ import { applications } from "../../applications/applications";
820
+
821
+ export default defineAction({
746
822
  description: "Cross-org hiring report",
823
+ path: "/admin/cross-org-report",
824
+ input: z.object({ startDate: z.string() }),
825
+ access: { roles: ['owner'] },
747
826
  unsafe: {
748
827
  reason: "Support investigation for enterprise customer",
749
828
  adminOnly: true, // default true — gates on ctx.userRole === 'admin'
750
829
  crossTenant: true, // default true — bypasses firewall
751
830
  targetScope: 'all', // 'all' | 'organization'
752
831
  },
753
- input: z.object({ startDate: z.string() }),
754
- access: { roles: ['owner'] },
755
- execute: async ({ db, unsafeDb, ctx, input }) => {
832
+ async execute({ db, unsafeDb, ctx, input }) {
756
833
  // db is still scoped (safety net for accidental writes)
757
834
  // unsafeDb bypasses scoped filters
758
835
  return await unsafeDb.select().from(applications);
759
836
  },
760
- },
837
+ });
761
838
  ```
762
839
 
763
- Generated runtime auto-injects: Better Auth required, platform admin gate, mandatory audit logging on deny/success/error. Without unsafe mode, `unsafeDb` is `undefined`. Legacy `unsafe: true` still works but object form is preferred.
840
+ Generated runtime auto-injects: Better Auth required, platform admin gate, mandatory audit logging on deny/success/error. Without unsafe mode, `unsafeDb` is `undefined`.
764
841
 
765
842
  ### Soft-delete cascade (cross-feature)
766
843
 
@@ -768,28 +845,25 @@ When a parent is soft-deleted, every child table that holds an FK to it — both
768
845
 
769
846
  ### Actions-Only Features
770
847
 
771
- Features that only contain standalone actions (no tables). Use `defineActions(null, { ... })`:
848
+ 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
849
 
773
850
  ```typescript
774
- // quickback/features/utilities/actions.ts
775
- import { defineActions } from '@quickback/compiler';
776
- import { z } from 'zod';
777
-
778
- export default defineActions(null, {
779
- healthCheck: {
780
- standalone: true,
781
- path: "/health",
782
- method: "GET",
783
- description: "Health check endpoint",
784
- input: z.object({}),
785
- access: { roles: ["member", "admin"] },
786
- handler: "./handlers/health-check",
851
+ // quickback/features/utilities/actions/health-check.ts
852
+ import { z } from "zod";
853
+ import { defineAction } from "../.quickback/define-action";
854
+
855
+ export default defineAction({
856
+ description: "Health check endpoint",
857
+ path: "/health",
858
+ method: "GET",
859
+ input: z.object({}),
860
+ access: { roles: ["member", "admin"] },
861
+ async execute() {
862
+ return { ok: true };
787
863
  },
788
864
  });
789
865
  ```
790
866
 
791
- All actions in an actions-only feature must have `standalone: true` (since there's no table for record-based actions).
792
-
793
867
  ---
794
868
 
795
869
  ## 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 `defineActions()` with Zod schemas
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 `defineActions()` with Zod input schemas (if needed)
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` - Custom actions via `defineActions()` with Zod schemas (if needed)
47
- - `handlers/` - Action handler files (if needed)
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 todos from './todos'; // default import: feature() exports
97
- import { defineActions } from '@quickback/compiler';
98
- import { z } from 'zod';
99
-
100
- export default defineActions(todos, {
101
- complete: {
102
- description: "Mark todo as complete",
103
- input: z.object({
104
- completedAt: z.string().datetime().optional(),
105
- }),
106
- access: {
107
- roles: ["member", "admin"],
108
- record: { completed: { equals: false } },
109
- },
110
- execute: async ({ db, record, whereRecord, auditFields }) => {
111
- await db.update(todos)
112
- .set({ completed: true, modifiedAt: auditFields.modifiedAt })
113
- .where(whereRecord!(todos));
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 is required for new code — auto-injects audit logging).
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 defineActions() for approve/reject
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
- // In actions.ts
185
- chat: {
186
- standalone: true,
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
- handler: "./handlers/chat",
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 { defineActions } from '@quickback/compiler';
200
- import { z } from 'zod';
201
-
202
- export default defineActions(null, {
203
- healthCheck: {
204
- standalone: true,
205
- path: "/health",
206
- method: "GET",
207
- description: "Health check endpoint",
208
- input: z.object({}),
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
- standalone: true,
221
- path: "/submit",
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
- handler: "./handlers/submit",
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 `defineActions()` with Zod schemas (not JSON schema)
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