@quickback-dev/cli 0.47.12 → 0.47.14

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.
Files changed (39) hide show
  1. package/dist/docs/content.js +5 -5
  2. package/dist/docs/content.js.map +1 -1
  3. package/dist/index.js +1 -1
  4. package/dist/lib/action-harvest.d.ts.map +1 -1
  5. package/dist/lib/action-harvest.js +110 -46
  6. package/dist/lib/action-harvest.js.map +1 -1
  7. package/dist/lib/action-harvest.test.js +97 -0
  8. package/dist/lib/action-harvest.test.js.map +1 -1
  9. package/dist/lib/api-client.d.ts.map +1 -1
  10. package/dist/lib/api-client.js +18 -1
  11. package/dist/lib/api-client.js.map +1 -1
  12. package/dist/skill/docs/changelog.md +89 -0
  13. package/dist/skill/docs/compiler/config/agents.md +1 -1
  14. package/dist/skill/docs/compiler/definitions/access.md +2 -0
  15. package/dist/skill/docs/compiler/definitions/scopes.md +249 -2
  16. package/dist/skill/docs/stack/schedules/index.md +17 -0
  17. package/package.json +1 -1
  18. package/src/skill/docs/changelog.md +89 -0
  19. package/src/skill/docs/compiler/config/agents.md +1 -1
  20. package/src/skill/docs/compiler/definitions/access.md +2 -0
  21. package/src/skill/docs/compiler/definitions/scopes.md +249 -2
  22. package/src/skill/docs/stack/schedules/index.md +17 -0
  23. package/dist/codex/AGENTS.md +0 -290
  24. package/dist/commands/codex.d.ts +0 -16
  25. package/dist/commands/codex.d.ts.map +0 -1
  26. package/dist/commands/codex.js +0 -159
  27. package/dist/commands/codex.js.map +0 -1
  28. package/dist/commands/init.d.ts +0 -6
  29. package/dist/commands/init.d.ts.map +0 -1
  30. package/dist/commands/init.js +0 -405
  31. package/dist/commands/init.js.map +0 -1
  32. package/dist/lib/sweep-stale.d.ts +0 -25
  33. package/dist/lib/sweep-stale.d.ts.map +0 -1
  34. package/dist/lib/sweep-stale.js +0 -179
  35. package/dist/lib/sweep-stale.js.map +0 -1
  36. package/dist/lib/sweep-stale.test.d.ts +0 -2
  37. package/dist/lib/sweep-stale.test.d.ts.map +0 -1
  38. package/dist/lib/sweep-stale.test.js +0 -130
  39. package/dist/lib/sweep-stale.test.js.map +0 -1
@@ -15,6 +15,8 @@ Reach for a scope when a principal must touch a bounded slice of an instance **w
15
15
 
16
16
  Each is *event-scoped* but a **distinct least-privilege role**. Org members are unaffected — they keep their normal tenant access.
17
17
 
18
+ Most scope principals are signed-in users who prove a relationship at [`/scope/v1/enter`](#2-enter-the-scope). But some have **no account at all** — an attendee who arrives by email + invite code, a kiosk/handout code, a partner token. For those, an action proves the principal its own way and [`ctx.mintScope`](#sessionless-scope-mint--ctxmintscope) mints the same scope, no Better Auth user required.
19
+
18
20
  ## The model
19
21
 
20
22
  ### 1. Declare relationships + scopes
@@ -315,6 +317,240 @@ forge a scope role — the guard, not the flag, is the gate.
315
317
  - **The mint is gated by the same proven-relationship guard as the in-memory stamp.** It runs *after* the gate has granted access, reading the instance id from the proven path param (`:eventId`) — never from request input — so the minted `scope:<kind>:<role>` is backed by exactly the proof `/scope/v1/enter` requires. The token is **byte-identical** to one `/scope/v1/enter` would produce: same shared mint helper, same carry-forward of any *other* verified scope kinds already on the incoming token (the freshly-proven kind takes precedence; siblings survive the re-mint).
316
318
  - **The mint is best-effort.** A mint failure (e.g. a missing signing secret) **never fails the request** — the in-memory stamp already authorized it; the caller simply doesn't receive a refreshed token on that response and can fall back to `/scope/v1/enter`.
317
319
 
320
+ ## `acceptScope` — accept an incoming scope claim as proof of entry
321
+
322
+ `mintScope` is the resolver *minting* a scope claim after a `ctx.userId` lane
323
+ matches. **`acceptScope: '<kind>'` is the inverse: it lets the same resolver
324
+ *accept* an already-minted `ctx.scope.<kind>` claim as its own proof** — so one
325
+ `/event/:eventId/*` handler serves **both** the Better-Auth user (userId
326
+ relationship probe) **and** the sessionless scope principal (verified scope
327
+ JWT, no account). It's the exact fast-path the realtime
328
+ [ws-ticket](/stack/realtime/durable-objects) already has, ported to REST.
329
+
330
+ Without it, every scope-principal-facing namespaced action needs a **parallel
331
+ PUBLIC twin** (a separate handler with a hand-rolled `requireScope` check and
332
+ raw DB writes that bypass scoped-db) — double the surface, and "someone forgot
333
+ the twin" becomes a standing bug class. `acceptScope` retires the twin.
334
+
335
+ ```typescript
336
+ // quickback.config.ts
337
+ authz: {
338
+ relationships: {
339
+ inspectorOf: {
340
+ from: 'site_inspectors',
341
+ subject: { column: 'inspectorUserId', equals: 'ctx.userId' },
342
+ resource: { column: 'locationId' },
343
+ where: { status: 'active' },
344
+ loads: 'locations',
345
+ exposeAs: 'location',
346
+ },
347
+ },
348
+ scopes: {
349
+ location: {
350
+ requestField: 'locationId',
351
+ roles: {
352
+ // supplied-reachable: a signed-in user AND a sessionless principal
353
+ // converge on ONE scope:location:inspector.
354
+ inspector: { via: 'inspectorOf', subKeys: ['inspectorId'], subject: 'both' },
355
+ },
356
+ },
357
+ },
358
+ namespaces: {
359
+ locationScope: {
360
+ prefix: '/location/:locationId',
361
+ via: ['inspectorOf'],
362
+ acceptScope: 'location', // ← honor an incoming ctx.scope.location claim
363
+ // mintScope: true, // ← compose freely: a userId caller also re-mints
364
+ },
365
+ },
366
+ }
367
+ ```
368
+
369
+ A sessionless principal that already minted a token (via
370
+ [`ctx.mintScope`](#sessionless-scope-mint--ctxmintscope) or `/scope/v1/enter`)
371
+ then hits the namespaced action directly, no second round-trip:
372
+
373
+ ```http
374
+ GET /api/v1/location/loc_42/summary
375
+ Authorization: Bearer <scope-only-jwt carrying scope.location = { id: 'loc_42', roles: ['inspector'] }>
376
+
377
+ 200 OK
378
+ ```
379
+
380
+ The resolver reads `ctx.scope.location`, confirms its `id` equals the `:locationId`
381
+ param, sees the `inspector` role a supplied-reachable lane confers, and admits
382
+ the request — no `ctx.userId`, no DB relationship probe. `ctx.location` is
383
+ hydrated through its own firewall exactly as it is for the userId caller.
384
+
385
+ ### Two locks (both required, fail-closed)
386
+
387
+ `acceptScope` is **named-string only** — always the explicit kind, never a bare
388
+ `true` (there's no inference from the `:param`). Default absent → the resolver
389
+ **never** admits a scope principal (unchanged behavior). Beyond naming the kind,
390
+ the compiler enforces a second lock:
391
+
392
+ 1. **`acceptScope: '<kind>'`** opts *this namespace's* REST surface in, **and**
393
+ 2. at least one relationship lane of the namespace confers a `<kind>` role
394
+ declared **`subject: 'supplied' | 'both'`** (supplied-reachable).
395
+
396
+ A `subject: 'user'` role can be *minted* or *refreshed* by the namespace but can
397
+ **never be accepted** from a token — a user-only role must be proven by a live
398
+ `ctx.userId` probe. If `acceptScope` names a kind whose every conferring lane is
399
+ `subject: 'user'`, the **compiler errors** rather than emit a dead fast-path.
400
+ The compiler also checks the kind is declared and its `requestField` equals the
401
+ prefix's first `:param`.
402
+
403
+ ### Forging safety
404
+
405
+ A scope principal can't use `acceptScope` to reach anything its token doesn't
406
+ already authorize:
407
+
408
+ - **The claim is verified, not asserted** — `ctx.scope` is populated only from a
409
+ JWT the auth middleware verified; the action can't write it.
410
+ - **Named kind, not any-kind** — the fast-path reads `ctx.scope['<kind>']` for
411
+ the declared kind (stricter than the ws-ticket's any-key loop); a colliding
412
+ foreign-kind id can't open the gate.
413
+ - **Instance pinned twice** — `entry.id === :param` in the gate, *and*
414
+ `eq(loads.pk, :param)` in hydration. The principal enters exactly the instance
415
+ its claim proved.
416
+ - **Role → lane is exact and supplied-restricted** — each accept arm is one
417
+ `(role, lane)` pair with `subject !== 'user'`; an `inspector` claim matches
418
+ `inspectorOf`, never a sibling lane.
419
+ - **No new enforcement surface** — firewall, masking, `access` arms, and
420
+ scoped-db all read the same `ctx.scope` / `ctx.activeOrgId` they read for a
421
+ userId caller. New proof source, zero new enforcement surface.
422
+
423
+ The tenant (`ctx.activeOrgId`) is sourced from the pinned-loaded resource
424
+ (`ctx.<exposeAs>.organizationId`) — parity with the userId caller, not a new
425
+ grant. Fine-grained "own rows only" stays the resource author's job via a
426
+ firewall arm on `ctx.scope.<kind>.subjectId`, the **same** arm that already
427
+ serves the userId principal.
428
+
429
+ ## Sessionless scope mint — `ctx.mintScope`
430
+
431
+ `POST /scope/v1/enter` and the namespace resolver both prove the relationship by
432
+ **`ctx.userId`** — so they require a Better Auth account. But a legitimate
433
+ principal often has none: an **event attendee who arrives by email + invite
434
+ code**, holding an opaque session token you validate yourself, who must never
435
+ get a global account. The shape is general — magic links, kiosk/handout codes,
436
+ partner-issued API keys, expiring share links that need row-level scope.
437
+
438
+ For these, prove the relationship **your own way** inside an action, then ask
439
+ Quickback to mint a disciplined scope token from the row you proved.
440
+
441
+ ### 1. Opt the role into supplied-subject proof
442
+
443
+ Add `subject` to the scope role (default `'user'`):
444
+
445
+ ```typescript
446
+ authz: {
447
+ scopes: {
448
+ event: {
449
+ requestField: 'eventId',
450
+ roles: {
451
+ // 'both' → the SAME scope:event:attendee for a logged-in user
452
+ // (via /enter) AND a sessionless invite-holder (via ctx.mintScope).
453
+ attendee: { via: 'attendeeOf', subKeys: ['guestId'], subject: 'both' },
454
+ },
455
+ },
456
+ },
457
+ }
458
+ ```
459
+
460
+ - **`'user'`** (default) — `/scope/v1/enter` only, proven by `subject.column = ctx.userId`. Unchanged.
461
+ - **`'supplied'`** — sessionless only. `ctx.mintScope` mints it; `/enter` won't (there's no user to probe).
462
+ - **`'both'`** — either path. A user-attendee and a sessionless invite-attendee converge on **one** `scope:event:attendee` — one firewall arm, one masking rule, both principals.
463
+
464
+ This opt-in is the single fail-closed switch: without `'supplied'` or `'both'`, no relationship is mintable by a supplied id.
465
+
466
+ ### 2. Mint from the proven row
467
+
468
+ `ctx.mintScope` is hydrated on `ctx` in **any action** when a `subject:
469
+ 'supplied' | 'both'` role is declared (including **PUBLIC** actions — the
470
+ canonical caller has no token yet). The action proves the principal however it
471
+ likes, then hands Quickback **only the conferring row's primary key**:
472
+
473
+ ```typescript
474
+ // features/events/actions/enterEvent.ts
475
+ export default defineAction({
476
+ path: '/enter-event',
477
+ method: 'POST',
478
+ input: z.object({ code: z.string() }),
479
+ access: { roles: ['PUBLIC'] }, // unauthenticated entry
480
+ async execute({ ctx, input }) {
481
+ const guestRowId = await validateInviteCode(ctx, input.code); // YOUR proof, YOUR table
482
+ const { token } = await ctx.mintScope({ via: 'attendeeOf', subject: guestRowId });
483
+ return { token }; // client sends it as `Authorization: Bearer …` thereafter
484
+ },
485
+ });
486
+ ```
487
+
488
+ You assert **nothing** about the scope. Quickback re-reads the `attendeeOf` row
489
+ by primary key and takes the role, the resource id (`eventId`), the sub-keys,
490
+ and the subject id **off that row** — so a buggy or hostile action can't forge
491
+ `organizer`, can't pick a different event, and can't widen the slice. The only
492
+ thing delegated to you is *which row* — exactly the opaque-credential check that
493
+ has to be custom code.
494
+
495
+ | What you supply | What Quickback reads off the row |
496
+ |---|---|
497
+ | `via` (a declared `supplied`/`both` relationship) + `subject` (the `from`-row PK you proved) | the role, `id` (resource), sub-keys, and `subjectId` — none caller-asserted |
498
+
499
+ The `where:` filter runs on the mint probe exactly as at `/enter` — a cancelled
500
+ or pending row confers nothing, so flipping a guest's `status` revokes them
501
+ within one mint cycle (**≤180s**). Re-prove by calling `ctx.mintScope` again
502
+ (your own refresh endpoint does exactly that). The by-PK probe does **not** apply
503
+ the relationship's tenant firewall (a sessionless principal has no
504
+ `activeOrgId` yet — the proven row *is* what establishes scope), but matching by
505
+ primary key + the `where:` filter keeps it bounded and fail-closed.
506
+
507
+ ### 3. The scope-only token
508
+
509
+ `ctx.mintScope` signs a **scope-only** JWT — it carries the `scope` claim and
510
+ nothing else. There is **no user identity**: the auth middleware builds a context
511
+ with **`ctx.userId` undefined**, so every user-, org-, and owner-gated path
512
+ **fails closed automatically** (an owner firewall compares against `undefined`
513
+ → matches nothing; org-role gates see empty `ctx.roles`). The `AUTHENTICATED`
514
+ and `USER` pseudo-roles **exclude** a scope principal by design — it is
515
+ authenticated *as a scope*, not as "any signed-in user". Only
516
+ `scope:<kind>:<role>` gates and `ctx.scope.<kind>` firewall arms admit it.
517
+
518
+ Everything downstream — REST firewall, masking, scoped-role access, the realtime
519
+ ws-ticket — then treats the sessionless attendee **identically** to a
520
+ user-proven one. There is no new enforcement surface; the principal is just
521
+ `scope:event:attendee`.
522
+
523
+ ### `subjectId` — scoping to the person, not just the instance
524
+
525
+ A user-proven scope scopes self-data (an attendee's travel, dietary, todos) by
526
+ `ctx.userId`. A sessionless attendee has no `ctx.userId`, so the **proven
527
+ subject's identity rides in the claim** as a reserved **`subjectId`** — the
528
+ conferring row's primary key:
529
+
530
+ ```jsonc
531
+ "scope": { "event": { "id": "evt_123", "roles": ["attendee"], "subjectId": "gst_42" } }
532
+ ```
533
+
534
+ Scope self-data on it with one firewall arm:
535
+
536
+ ```typescript
537
+ { field: 'guestId', equals: 'ctx.scope.event.subjectId' }
538
+ ```
539
+
540
+ `subjectId` is populated on **both** proof paths — `/scope/v1/enter` projects
541
+ the matched row's PK too — so the arm above is **one arm that serves both** a
542
+ logged-in attendee and a sessionless one. (It is distinct from
543
+ `ctx.scope.event.id`, which is the *instance* — the event.)
544
+
545
+ ### Realtime
546
+
547
+ A scope-only token authorizes the realtime
548
+ [ws-ticket](/stack/realtime/durable-objects) directly off its proven
549
+ `ctx.scope` claim — no `ctx.userId` re-probe. The sessionless attendee joins the
550
+ same per-event rooms (and per-attendee rooms keyed on `subjectId`) as a
551
+ user-attendee, carrying the same scope role on the ticket. So the REST gate and
552
+ the socket gate stay identical for accountless principals too.
553
+
318
554
  ## Revocation & TTL
319
555
 
320
556
  The scope claim is trusted between proofs — it is never re-checked against the database while it rides. Two bounds keep that window finite:
@@ -331,17 +567,28 @@ So removing a guest/staff row takes effect within **cap + one TTL** for a client
331
567
 
332
568
  ```typescript
333
569
  // AppContext (generated lib/types.ts)
334
- ctx.scope?: Record<string, { id: string; roles?: string[]; [subKey: string]: string | string[] | undefined }>;
570
+ ctx.scope?: Record<string, { id: string; roles?: string[]; subjectId?: string; [subKey: string]: string | string[] | undefined }>;
335
571
 
336
572
  // authz.scopes.<kind>
337
573
  {
338
574
  requestField: string; // body field carrying the instance id
339
- roles: Record<string, { via: string; subKeys?: string[] }>; // 'col' → eq, 'col[]' → inArray
575
+ roles: Record<string, {
576
+ via: string;
577
+ subKeys?: string[]; // 'col' → eq, 'col[]' → inArray
578
+ subject?: 'user' | 'supplied' | 'both'; // who selects the conferring row (default 'user')
579
+ }>;
340
580
  }
581
+
582
+ // ctx.mintScope — present in actions when a `subject: 'supplied' | 'both'` role is declared
583
+ ctx.mintScope(opts: { via: string; subject: string; setAuthToken?: boolean }):
584
+ Promise<{ token: string; scope: { id: string; roles: string[]; subjectId?: string } }>;
341
585
  ```
342
586
 
343
587
  - `requestField` must equal every role-relationship's `resource.column`.
344
588
  - Each relationship's `from` table must exist and ship a generated firewall (it can't be `exception`).
345
589
  - A `subKeys` entry ending in `[]` is **set-valued** (lowers to `inArray`, minted as `string[]`); without the marker it's scalar (`eq`, minted as `string`).
590
+ - `subject` defaults to `'user'`. `'supplied'`/`'both'` enable [`ctx.mintScope`](#sessionless-scope-mint--ctxmintscope) (sessionless mint); `'supplied'` is **not** mintable via `/scope/v1/enter`.
591
+ - `ctx.mintScope({ via, subject })` mints a **scope-only** token (no user identity, `ctx.userId` undefined) from the `from`-row whose PK is `subject` — reading the role, resource id, sub-keys, and `subjectId` off that row.
592
+ - `subjectId` is the conferring row's primary key, populated on **both** proof paths — scope self-data on `ctx.scope.<kind>.subjectId`.
346
593
  - `q.scope('<kind>')` auto-stamps the column from `ctx.scope.<kind>.id` on insert.
347
594
  - Generated route: `POST /scope/v1/enter` (mounted only when `authz.scopes` is declared).
@@ -7,6 +7,7 @@
7
7
  ```typescript
8
8
  // services/schedules/sweepDigests.ts
9
9
  import { defineSchedule } from "quickback";
10
+ import { runDigestSweep } from "../../features/comms/lib/digest-sweep";
10
11
 
11
12
  export default defineSchedule({
12
13
  name: "sweepDigests", // identifier + audit actor (system:cron-<name>)
@@ -20,6 +21,22 @@ export default defineSchedule({
20
21
 
21
22
  One file per schedule under `services/schedules/*.ts`. Files prefixed with `_` are ignored. `name` must be a valid camelCase identifier (it's used as a generated symbol and the audit actor).
22
23
 
24
+ ## Importing feature code
25
+
26
+ Schedule files live at `quickback/services/schedules/<name>.ts`, so imports are relative to **that** location. To reach a feature table, a feature `lib/` helper, or `db/`, climb up to the `quickback/` root first (`../../`):
27
+
28
+ ```typescript
29
+ // quickback/services/schedules/bookingReminders.ts
30
+ import { bookings } from "../../features/crm/bookings"; // a feature table
31
+ import { generateIcsInvite } from "../../features/crm/lib/ics-generate"; // a feature lib/ helper
32
+ import { runDigestSweep } from "../../lib/digest-sweep"; // a shared lib/ helper
33
+ ```
34
+
35
+ Two `../` — up from `services/schedules/` to `quickback/`, then down into `features/` (or `lib/`, `db/`). The compiler relocates the handler into the generated `src/lib/schedules.ts` and **rewrites these paths to resolve from there automatically** — you always write them relative to your own source file, exactly as your editor resolves them.
36
+
37
+ > A single `../features/…` is the common mistake — from `services/schedules/` that resolves to `services/features/…`, which doesn't exist (the compiler consumes `services/`; there is no `src/services/`). Use `../../features/…`.
38
+
39
+
23
40
  ## What the compiler emits
24
41
 
25
42
  1. **`scheduled(event, env, ctx)`** in the Worker's default export, dispatching to every schedule whose cron matches `event.cron`. Multiple schedules can share a cron; a failure in one is isolated from the others.
@@ -1,290 +0,0 @@
1
- # Quickback
2
-
3
- Quickback is two things:
4
-
5
- 1. **Compiler** — Transforms declarative TypeScript definitions into secure, production-ready APIs
6
- 2. **Stack** — A Supabase alternative running entirely on Cloudflare (D1, R2, KV, Durable Objects, Queues, Workers AI)
7
-
8
- The output is standard TypeScript (Hono, Drizzle, Better Auth) running on your own infrastructure.
9
-
10
- ## Project Structure
11
-
12
- ```
13
- my-app/
14
- ├── quickback/
15
- │ ├── quickback.config.ts
16
- │ └── features/
17
- │ └── {feature-name}/
18
- │ ├── {table}.ts # Schema + security (defineTable)
19
- │ ├── actions/ # One file per action — defineAction({...}) (optional)
20
- │ │ ├── {action}.ts # Binds to primary table (or standalone if path: is set)
21
- │ │ └── {table}/{action}.ts # Binds to sibling <table>.ts (multi-table features)
22
- │ └── lib/ # Feature-local helpers, copied verbatim (optional)
23
- └── ...
24
- ```
25
-
26
- ## quickback.config.ts
27
-
28
- ```typescript
29
- import { defineConfig, defineRuntime, defineDatabase, defineAuth } from '@quickback/compiler';
30
-
31
- export default defineConfig({
32
- name: "my-saas-app",
33
- providers: {
34
- runtime: defineRuntime("cloudflare"),
35
- database: defineDatabase("cloudflare-d1"),
36
- auth: defineAuth("better-auth"),
37
- },
38
- });
39
- ```
40
-
41
- ## Automatic Audit Fields
42
-
43
- Quickback auto-injects: `createdAt`, `modifiedAt`, `deletedAt`, `createdBy`, `modifiedBy`, `deletedBy`. Do NOT define these in schemas.
44
-
45
- ## defineTable() — Schema + Security
46
-
47
- Each feature file exports a Drizzle table and a `defineTable()` default export with security config:
48
-
49
- ```typescript
50
- import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
51
- import { defineTable } from "@quickback/compiler";
52
-
53
- export const todos = sqliteTable("todos", {
54
- id: integer("id").primaryKey(),
55
- title: text("title").notNull(),
56
- description: text("description"),
57
- completed: integer("completed", { mode: "boolean" }).default(false),
58
- userId: text("user_id").notNull(),
59
- organizationId: text("organization_id").notNull(),
60
- });
61
-
62
- export default defineTable(todos, {
63
- firewall: [
64
- { field: "organizationId", equals: "ctx.activeOrgId" },
65
- { field: "userId", equals: "ctx.userId" },
66
- { field: "deletedAt", isNull: true },
67
- ],
68
- read: { access: { roles: ["member", "admin"] } },
69
- create: { access: { roles: ["member", "admin"] } },
70
- update: { access: { roles: ["admin"] } },
71
- delete: { access: { roles: ["admin"] }, mode: "soft" },
72
- guards: {
73
- createable: ["title", "description", "completed"],
74
- updatable: ["title", "description", "completed"],
75
- },
76
- masking: {
77
- userId: { type: "redact", show: { roles: ["admin"] } },
78
- },
79
- });
80
- ```
81
-
82
- ## Four Security Layers
83
-
84
- Every request passes through: `Request → Firewall → Access → Guards → Database → Masking → Response`
85
-
86
- ### 1. Firewall — Data Isolation
87
-
88
- Auto WHERE clauses for tenant isolation. Predicates are AND'd:
89
-
90
- ```typescript
91
- firewall: [
92
- { field: 'organizationId', equals: 'ctx.activeOrgId' }, // WHERE organizationId = ctx.activeOrgId
93
- { field: 'ownerId', equals: 'ctx.userId' }, // AND ownerId = ctx.userId
94
- { field: 'teamId', equals: 'ctx.activeTeamId' }, // AND teamId = ctx.activeTeamId
95
- { field: 'deletedAt', isNull: true }, // AND deletedAt IS NULL
96
- ]
97
-
98
- // Public/system resources opt out of tenant scoping (soft-delete still applied):
99
- firewall: [{ exception: true }]
100
- ```
101
-
102
- Auto-derived when omitted: scans the schema for `organizationId` / `ownerId` / `teamId` and emits matching predicates. Two or more isolation columns → declare explicitly.
103
-
104
- ### 2. Access — Permission Checks
105
-
106
- Role-based and record-based (deny by default). Reads (`GET /` and `GET /:id`) gate via `read.access`; mutations gate via `create.access`, `update.access`, `delete.access`, and `upsert.access`.
107
-
108
- ```typescript
109
- read: { access: { roles: ['member'] } }, // gates GET / and GET /:id
110
- create: { access: { roles: ['admin'] } },
111
- update: {
112
- access: {
113
- or: [
114
- { roles: ['admin'] },
115
- { record: { createdBy: { equals: '$ctx.userId' } } },
116
- ],
117
- },
118
- },
119
- delete: { access: { roles: ['admin'] } },
120
- ```
121
-
122
- > **DSL v2:** `crud.list` and `crud.get` are rejected at compile time. Move them to `read.access`.
123
-
124
- Operators: `equals`, `notEquals`, `in`, `notIn`, `greaterThan`, `lessThan`
125
- Context: `$ctx.userId`, `$ctx.activeOrgId`, `$ctx.roles`
126
-
127
- ### 3. Guards — Field Protection
128
-
129
- ```typescript
130
- guards: {
131
- createable: ['name', 'description'],
132
- updatable: ['description'],
133
- immutable: ['invoiceNumber'],
134
- protected: { status: ['approve'] }, // Only via named actions
135
- }
136
- ```
137
-
138
- ### 4. Masking — PII Redaction
139
-
140
- ```typescript
141
- masking: {
142
- ssn: { type: 'ssn', show: { roles: ['admin'] } },
143
- email: { type: 'email', show: { roles: ['admin'], or: 'owner' } },
144
- }
145
- ```
146
-
147
- Types: `email`, `phone`, `ssn`, `creditCard`, `name`, `redact`, `custom`
148
-
149
- ## Views — Column Projections
150
-
151
- ```typescript
152
- views: {
153
- summary: { fields: ['id', 'name'], access: { roles: ['member'] } },
154
- full: { fields: ['id', 'name', 'phone', 'ssn'], access: { roles: ['admin'] } },
155
- }
156
- ```
157
-
158
- ## Validation
159
-
160
- ```typescript
161
- validation: {
162
- name: { minLength: 1, maxLength: 100 },
163
- capacity: { min: 1, max: 1000 },
164
- roomType: { enum: ['meeting', 'conference'] },
165
- email: { email: true },
166
- }
167
- ```
168
-
169
- ## Actions — Custom Business Logic
170
-
171
- One file per action under `actions/<name>.ts`. The filename is the action name AND URL segment. `actions/<name>.ts` binds to the feature's primary table; `actions/<table>/<name>.ts` binds to a sibling table. Setting `path:` makes the action standalone.
172
-
173
- ```typescript
174
- // features/todos/actions/complete.ts
175
- import { z } from "zod";
176
- import { eq } from "drizzle-orm";
177
- import { defineAction } from "../.quickback/define-action";
178
- import { todos } from "../todos";
179
-
180
- export default defineAction({
181
- description: "Mark todo as complete",
182
- input: z.object({ completedAt: z.string().datetime().optional() }),
183
- access: { roles: ["member", "admin"], record: { completed: { equals: false } } },
184
- async execute({ db, record, auditFields }) {
185
- await db.update(todos)
186
- .set({ completed: true, modifiedAt: auditFields!.modifiedAt })
187
- .where(eq(todos.id, record.id));
188
- return { success: true };
189
- },
190
- });
191
- ```
192
-
193
- Record-based (no `path:`): `POST /api/v1/{resource}/:id/{action}`
194
- Standalone (`path:` set): custom `path` and `method`
195
-
196
- `execute:` must be an `async (ctx) => { … }` arrow function. Retired (rejected at load time): bundled `actions.ts`, `_feature.ts`, `handlers/` directory, `defineActions()`.
197
-
198
- ### Actions-Only Features (no tables)
199
-
200
- A feature with no top-level `*.ts` files is "tableless" — every action must be standalone (have `path:`).
201
-
202
- ```typescript
203
- // quickback/features/utilities/actions/health-check.ts
204
- import { z } from "zod";
205
- import { defineAction } from "../.quickback/define-action";
206
-
207
- export default defineAction({
208
- description: "Health check",
209
- path: "/health",
210
- method: "GET",
211
- input: z.object({}),
212
- access: { roles: ["member", "admin"] },
213
- async execute() { return { ok: true }; },
214
- });
215
- ```
216
-
217
- ### Public Actions
218
-
219
- Use `roles: ["PUBLIC"]` for unauthenticated endpoints. Mandatory audit logged. The wildcard `"*"` is not supported.
220
-
221
- ```typescript
222
- access: { roles: ["PUBLIC"] } // No auth, audit logged
223
- access: { roles: ["member"] } // Requires auth + role
224
- ```
225
-
226
- ## Custom Dependencies
227
-
228
- ```typescript
229
- export default defineConfig({
230
- build: {
231
- dependencies: {
232
- "fast-xml-parser": "^4.5.0",
233
- },
234
- },
235
- });
236
- ```
237
-
238
- ## CMS Layouts
239
-
240
- ```typescript
241
- layouts: {
242
- default: {
243
- sections: [
244
- { label: "Details", columns: 2, fields: ["name", "email"] },
245
- { label: "Notes", collapsed: true, fields: ["notes"] },
246
- ],
247
- },
248
- }
249
- ```
250
-
251
- ## API Reference
252
-
253
- | Method | Endpoint | Description |
254
- |--------|----------|-------------|
255
- | `GET` | `/api/v1/{resource}` | List |
256
- | `GET` | `/api/v1/{resource}/:id` | Get |
257
- | `POST` | `/api/v1/{resource}` | Create |
258
- | `PATCH` | `/api/v1/{resource}/:id` | Update |
259
- | `DELETE` | `/api/v1/{resource}/:id` | Delete |
260
-
261
- Query params: `?limit=50&offset=0`, `?status=active`, `?sort=-createdAt`, `?fields=id,name`, `?search=text`
262
- Filter operators: `.gt`, `.gte`, `.lt`, `.lte`, `.ne`, `.like`, `.in`
263
-
264
- ## Database Dialects
265
-
266
- | Stack | Import | Table Function |
267
- |-------|--------|----------------|
268
- | Cloudflare D1 / SQLite | `drizzle-orm/sqlite-core` | `sqliteTable` |
269
- | Supabase / PostgreSQL | `drizzle-orm/pg-core` | `pgTable` |
270
-
271
- ## Migrations are generated — never hand-merge them
272
-
273
- The files under `quickback/drizzle/` (`*.sql`, `meta/_journal.json`, `meta/*_snapshot.json`) are **generated artifacts**, not source. Never hand-edit them, and never resolve a merge or rebase conflict inside them.
274
-
275
- When integrating a branch: get the feature/schema `.ts` files in first, then run `quickback compile`. The compiler regenerates the migrations from the merged schema and journals them in the correct (append-only) order. Hand-merging migration SQL or snapshots produces schema drift and broken ordering that only surfaces at deploy time. If a migration file conflicts during a merge, take either side to unblock, then recompile and let the compiler restate the migrations.
276
-
277
- ## CLI Commands
278
-
279
- ```bash
280
- quickback create <template> <name> # Create project
281
- quickback compile # Compile definitions
282
- quickback docs [topic] # Show documentation
283
- quickback claude install # Install Claude Code skill
284
- quickback cursor install # Install Cursor rules
285
- quickback codex install # Install Codex AGENTS.md rules
286
- ```
287
-
288
- ## Full Documentation
289
-
290
- https://docs.quickback.dev
@@ -1,16 +0,0 @@
1
- /**
2
- * Codex command - manage ChatGPT Codex AGENTS.md rules.
3
- *
4
- * Codex reads `AGENTS.md` from the project root (merging up the tree), so unlike
5
- * Cursor's dedicated .mdc file the rules live in a file the user may also own.
6
- * We therefore manage only a delimited block, leaving the rest of AGENTS.md
7
- * untouched.
8
- *
9
- * Usage:
10
- * quickback codex install # Add/update the Quickback block in ./AGENTS.md
11
- * quickback codex update # Alias for install (refresh the block)
12
- * quickback codex remove # Strip the Quickback block
13
- * quickback codex status # Check installation status
14
- */
15
- export declare function codex(args: string[]): Promise<void>;
16
- //# sourceMappingURL=codex.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/commands/codex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAwIH,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBzD"}