@quickback-dev/cli 0.66.20 → 0.66.22

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 (102) hide show
  1. package/dist/commands/migrate.js +2 -2
  2. package/dist/commands/migrate.js.map +1 -1
  3. package/dist/index.js +1 -1
  4. package/dist/lib/migrations/drizzle-prompts.d.ts +2 -0
  5. package/dist/lib/migrations/drizzle-prompts.d.ts.map +1 -1
  6. package/dist/lib/migrations/drizzle-prompts.js +11 -0
  7. package/dist/lib/migrations/drizzle-prompts.js.map +1 -1
  8. package/dist/lib/migrations/file-envelopes.d.ts.map +1 -1
  9. package/dist/lib/migrations/file-envelopes.js +21 -51
  10. package/dist/lib/migrations/file-envelopes.js.map +1 -1
  11. package/dist/lib/migrations/prompt-runner.d.ts.map +1 -1
  12. package/dist/lib/migrations/prompt-runner.js +6 -1
  13. package/dist/lib/migrations/prompt-runner.js.map +1 -1
  14. package/dist/skill/docs/api/actions.md +13 -6
  15. package/dist/skill/docs/api/batch-operations.md +6 -2
  16. package/dist/skill/docs/api/crud.md +72 -9
  17. package/dist/skill/docs/api/errors.md +86 -6
  18. package/dist/skill/docs/api/openapi.md +1 -1
  19. package/dist/skill/docs/api/query-params.md +8 -7
  20. package/dist/skill/docs/api/typescript.md +196 -0
  21. package/dist/skill/docs/configure/index.md +36 -2
  22. package/dist/skill/docs/configure/providers.md +37 -9
  23. package/dist/skill/docs/define/actions/defining.md +16 -7
  24. package/dist/skill/docs/define/actions/record-and-standalone.md +10 -0
  25. package/dist/skill/docs/define/actions/scoped-db.md +18 -3
  26. package/dist/skill/docs/define/changesets.md +2 -0
  27. package/dist/skill/docs/define/firewall.md +39 -0
  28. package/dist/skill/docs/define/guards.md +7 -2
  29. package/dist/skill/docs/define/masking.md +14 -0
  30. package/dist/skill/docs/define/read.md +3 -0
  31. package/dist/skill/docs/define/relationships.md +9 -0
  32. package/dist/skill/docs/define/schema.md +14 -10
  33. package/dist/skill/docs/define/transitions.md +12 -5
  34. package/dist/skill/docs/define/triggers.md +2 -1
  35. package/dist/skill/docs/index.md +1 -0
  36. package/dist/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
  37. package/dist/skill/docs/platform/database/neon.md +110 -30
  38. package/dist/skill/docs/platform/payments/index.md +1 -1
  39. package/dist/skill/docs/start/frontend.md +278 -0
  40. package/dist/skill/docs/start/index.md +1 -0
  41. package/dist/skill/docs/tooling/cli.md +28 -7
  42. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
  43. package/dist/skill/docs/tooling/output.md +42 -11
  44. package/dist/skill/docs/tooling/troubleshooting.md +67 -0
  45. package/dist/skill/docs/ui/admin/actions.md +6 -2
  46. package/dist/skill/docs/ui/admin/index.md +1 -1
  47. package/dist/skill/docs/ui/admin/inline-editing.md +6 -2
  48. package/dist/skill/docs/ui/admin/schema-format.md +74 -36
  49. package/dist/skill/docs/ui/admin/schema-registry.md +22 -9
  50. package/dist/skill/docs/ui/admin/security.md +2 -2
  51. package/dist/skill/docs/ui/components/action-dialog.md +62 -0
  52. package/dist/skill/docs/ui/components/auth.md +90 -0
  53. package/dist/skill/docs/ui/components/index.md +48 -0
  54. package/dist/skill/docs/ui/components/install.md +118 -0
  55. package/dist/skill/docs/ui/components/quickback-provider.md +123 -0
  56. package/dist/skill/docs/ui/components/resource-form.md +80 -0
  57. package/dist/skill/docs/ui/components/resource-table.md +46 -0
  58. package/package.json +1 -1
  59. package/src/skill/docs/api/actions.md +13 -6
  60. package/src/skill/docs/api/batch-operations.md +6 -2
  61. package/src/skill/docs/api/crud.md +72 -9
  62. package/src/skill/docs/api/errors.md +86 -6
  63. package/src/skill/docs/api/openapi.md +1 -1
  64. package/src/skill/docs/api/query-params.md +8 -7
  65. package/src/skill/docs/api/typescript.md +196 -0
  66. package/src/skill/docs/configure/index.md +36 -2
  67. package/src/skill/docs/configure/providers.md +37 -9
  68. package/src/skill/docs/define/actions/defining.md +16 -7
  69. package/src/skill/docs/define/actions/record-and-standalone.md +10 -0
  70. package/src/skill/docs/define/actions/scoped-db.md +18 -3
  71. package/src/skill/docs/define/changesets.md +2 -0
  72. package/src/skill/docs/define/firewall.md +39 -0
  73. package/src/skill/docs/define/guards.md +7 -2
  74. package/src/skill/docs/define/masking.md +14 -0
  75. package/src/skill/docs/define/read.md +3 -0
  76. package/src/skill/docs/define/relationships.md +9 -0
  77. package/src/skill/docs/define/schema.md +14 -10
  78. package/src/skill/docs/define/transitions.md +12 -5
  79. package/src/skill/docs/define/triggers.md +2 -1
  80. package/src/skill/docs/index.md +1 -0
  81. package/src/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
  82. package/src/skill/docs/platform/database/neon.md +110 -30
  83. package/src/skill/docs/platform/payments/index.md +1 -1
  84. package/src/skill/docs/start/frontend.md +278 -0
  85. package/src/skill/docs/start/index.md +1 -0
  86. package/src/skill/docs/tooling/cli.md +28 -7
  87. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
  88. package/src/skill/docs/tooling/output.md +42 -11
  89. package/src/skill/docs/tooling/troubleshooting.md +67 -0
  90. package/src/skill/docs/ui/admin/actions.md +6 -2
  91. package/src/skill/docs/ui/admin/index.md +1 -1
  92. package/src/skill/docs/ui/admin/inline-editing.md +6 -2
  93. package/src/skill/docs/ui/admin/schema-format.md +74 -36
  94. package/src/skill/docs/ui/admin/schema-registry.md +22 -9
  95. package/src/skill/docs/ui/admin/security.md +2 -2
  96. package/src/skill/docs/ui/components/action-dialog.md +62 -0
  97. package/src/skill/docs/ui/components/auth.md +90 -0
  98. package/src/skill/docs/ui/components/index.md +48 -0
  99. package/src/skill/docs/ui/components/install.md +118 -0
  100. package/src/skill/docs/ui/components/quickback-provider.md +123 -0
  101. package/src/skill/docs/ui/components/resource-form.md +80 -0
  102. package/src/skill/docs/ui/components/resource-table.md +46 -0
@@ -42,11 +42,16 @@ so an extra database silently splits the bootstrap: the roles look right in
42
42
  separating. Two apps means two Neon projects, not two databases.
43
43
 
44
44
  Mixing providers — for example D1 for auth with Neon for features — is not
45
- supported. The per-service config form is rejected at compile time:
45
+ supported. The per-service config form is a type error under `quickback check`
46
+ (the config type has no `auth` / `features` keys) and is rejected at compile
47
+ time:
46
48
 
47
49
  ```
48
- providers.database service-map form is not supported in v2.
49
- Configure one database provider; auth and feature data use the same database.
50
+ providers.database service-map form is not supported in v2 ({ auth, features } is the retired v1 shape).
51
+ Configure ONE database provider — auth and feature data share it:
52
+ database: defineDatabase("cloudflare-d1", { ... }) or database: { name: "neon", config: { ... } }.
53
+ On D1, auth keeps its own database by default (splitDatabases: true);
54
+ name the bindings with authBinding / featuresBinding.
50
55
  ```
51
56
 
52
57
  ## Configuration
@@ -599,8 +604,12 @@ WITH CHECK (
599
604
 
600
605
  ### The soft-delete lane
601
606
 
602
- `deleted_at IS NULL` keeps soft-deleted rows out of every caller's reach. On its
603
- own it also blocks the delete that put them there.
607
+ `deleted_at IS NULL` keeps soft-deleted rows out of every caller's reach. It is
608
+ in the scope policy of every table that carries `deleted_at`, exactly where the
609
+ API firewall adds its own `isNull(deletedAt)` — including a `firewall: [...]`
610
+ array that never mentions `deletedAt` (declare a predicate on `deletedAt`
611
+ yourself to take it over). On its own it also blocks the delete that put them
612
+ there.
604
613
 
605
614
  PostgreSQL applies a SELECT-applicable policy's `USING` expression to the **new**
606
615
  row of an `UPDATE`, not only the existing one, whenever the statement reads the
@@ -819,6 +828,17 @@ USING (owner_id = auth.user_id())
819
828
  WITH CHECK (owner_id = auth.user_id());
820
829
  ```
821
830
 
831
+ **Relationship-scoped** (`{ field: 'projectId', via: 'projectMemberOf' }`) — see
832
+ [Relationship arms in SQL](#relationship-arms-in-sql):
833
+
834
+ ```sql
835
+ CREATE POLICY "tasks_scope" ON "app"."tasks" FOR ALL TO quickback
836
+ USING (organization_id = public.get_active_org_id()
837
+ AND project_id IN (SELECT r.project_id FROM public.qb_rel_project_member_of() r))
838
+ WITH CHECK (organization_id = public.get_active_org_id()
839
+ AND project_id IN (SELECT r.project_id FROM public.qb_rel_project_member_of() r));
840
+ ```
841
+
822
842
  **Exception tables** (`firewall: [{ exception: true }]`) — no scope predicate,
823
843
  so the restrictive deny-anon policy is the only fence left:
824
844
 
@@ -827,6 +847,77 @@ CREATE POLICY "categories_all" ON "app"."categories" FOR ALL TO quickback
827
847
  USING (true) WITH CHECK (true);
828
848
  ```
829
849
 
850
+ ### Relationship arms in SQL
851
+
852
+ Every relationship lookup is enforced by the database, and the generated API
853
+ reads through the same place. Each declared relationship gets one helper,
854
+ emitted in the RLS migration ahead of the policies that call it:
855
+
856
+ ```sql
857
+ CREATE OR REPLACE FUNCTION public.qb_rel_project_member_of()
858
+ RETURNS SETOF "app"."project_members"
859
+ LANGUAGE sql STABLE SECURITY DEFINER SET search_path = ''
860
+ AS $$
861
+ SELECT a.*
862
+ FROM "app"."project_members" a
863
+ WHERE a."user_id" = auth.user_id()
864
+ AND a."deleted_at" IS NULL
865
+ $$;
866
+ ALTER FUNCTION public.qb_rel_project_member_of() OWNER TO quickback_owner;
867
+ REVOKE ALL ON FUNCTION public.qb_rel_project_member_of() FROM PUBLIC;
868
+ GRANT EXECUTE ON FUNCTION public.qb_rel_project_member_of() TO quickback;
869
+ ```
870
+
871
+ The scope policy calls it as
872
+ `"project_id" IN (SELECT r."project_id" FROM public.qb_rel_project_member_of() r)`,
873
+ and so does the generated API: a firewall `via:` arm, a relationship-role access
874
+ check, the action resolver's match row, the `/scope/v1/enter` probe and the
875
+ ws-ticket probe all read the caller's relationship rows from the helper, never
876
+ from the relationship table under its own policy.
877
+
878
+ - **Same lookup as D1.** The body is the relationship subquery the API runs on
879
+ D1: the subject column against the caller's claim, the `where:` literals
880
+ (SQL-quoted), and the related table's soft-delete filter — the API's
881
+ `skipTenantScopes` body. Multi-hop (`hops`) relationships join the same chain
882
+ and return the first hop's rows.
883
+ - **Why `SECURITY DEFINER`.** Under the relationship table's own policy the
884
+ lookup would recurse for a relationship that reads the table it protects
885
+ (`projectMemberOf` on `project_members`), and the table's tenant scope would
886
+ zero a caller with no active org — the case the API skips on purpose. The
887
+ helper runs as `quickback_owner`, which reads the related table through one
888
+ `<table>_quickback_owner_read` policy (`FOR SELECT TO quickback_owner USING (true)`).
889
+ Feature tables `FORCE ROW LEVEL SECURITY`, so the owner needs it; it grants
890
+ nothing new — an owner can always lift `FORCE` on its own table — and the
891
+ runtime role `quickback` is not a member of `quickback_owner`.
892
+ - **Locked down.** `search_path = ''` and fully-qualified names; `EXECUTE` is
893
+ revoked from `PUBLIC` and granted to `quickback` only. The caller comes from
894
+ the transaction's claims, so a lookup on the service handle (no caller)
895
+ returns nothing.
896
+ - **Evaluated once per statement.** The helper takes no arguments, so
897
+ `col IN (SELECT … FROM helper() r)` is an uncorrelated subquery — one hashed
898
+ subplan per statement, the same InitPlan discipline as the claim helpers. A
899
+ per-row `helper(row.col)` call could never be inlined.
900
+ - **Returns the table's own rows.** One helper serves every projection a lookup
901
+ needs (the resource column, the tenant columns the action resolver stamps,
902
+ scope sub-keys), and `CREATE OR REPLACE` stays valid as the table's columns
903
+ change. A helper whose relationship now returns a different table is dropped
904
+ first — with the generated policies that call it, which the same migration
905
+ re-creates.
906
+ - **Tenant binding.** Beside an org arm in an `any:` group the arm becomes
907
+ `(project_id IN (SELECT …) AND (organization_id = <active org> OR <no active org>))`
908
+ — exactly where the API applies the same binding.
909
+ - **Permissions.** A `{ permission }` arm expands as the API expands it; arrow
910
+ hops become `qb_arrow_…` helpers (recursive arrows are a `maxDepth`-bounded
911
+ closure that re-checks the tenant on every row), called by the API too.
912
+ - **Still API-only.** Literal status filters (a conjunct would refuse
913
+ status-changing updates, because PostgreSQL checks an UPDATE's new row against
914
+ the read policy) and claims the Worker never writes into the transaction —
915
+ `ctx.scope.<kind>.<subKey>`, area anchors such as `ctx.event.id`, and
916
+ relationships whose `subject` binds one. These lower to `true` in the policy,
917
+ and the API keeps the table query for such a relationship.
918
+
919
+ Helpers no compile references any more are dropped at the end of the migration.
920
+
830
921
  ### Helper functions
831
922
 
832
923
  | Function | Purpose |
@@ -963,31 +1054,20 @@ is a compile error everywhere, not a Neon-only concern.
963
1054
 
964
1055
  ### How the read is served
965
1056
 
966
- On **Neon**, a via-relationship reachability predicate cannot be expressed as an
967
- RLS policy — the correlated multi-hop join reaches across intermediate tables
968
- that each `FORCE ROW LEVEL SECURITY`, so caller-claims RLS would deny the attendee
969
- to *zero* rows before the app-layer WHERE ever runs. Quickback resolves this by
970
- routing that resource's **read** handlers through the service-role handle
971
- (`createServiceDb(c.env)`) instead of the caller-claims client. RLS stops denying,
972
- and the compiled `buildFirewallConditions(...)` reachability WHERE — the exact
973
- same clause D1 uses — becomes the **sole** row filter.
974
-
975
- This is the D1 trust model, applied to Neon for exactly these reads: the
976
- application layer is the firewall, and RLS is a coarse tenant backstop that steps
977
- aside where it cannot express the grant. It is surgical and fail-closed:
978
-
979
- - Only the affected resource's reads swap handles. **Org / owner / team reads keep
980
- caller claims + the RLS backstop** — they resolve to policies RLS *can* express.
981
- - The swap is gated on a non-empty firewall carrying the reachability predicate;
982
- a service-handle read with no WHERE is a compile error (it would return every
983
- tenant's rows). Fail closed.
984
- - It applies to the **collection `GET /`, `GET /:id`, and views** alike. **Writes
985
- are unchanged** — creates/updates/deletes keep caller claims and the RLS
986
- backstop.
987
-
988
- The **same config compiles identically on D1**, where there is no RLS to bypass:
989
- the read handlers keep `c.get('db')` and the app-layer reachability WHERE was
990
- already the whole story.
1057
+ Reads keep the **caller-claims** handle and the full RLS backstop, on Neon as
1058
+ everywhere else. The reachability WHERE (`buildFirewallConditions(...)`) and the
1059
+ resource's scope policy both call the relationship's
1060
+ [helper](#relationship-arms-in-sql), which walks the hop chain without the
1061
+ intermediate tables' tenant policies — so an attendee with no active org gets
1062
+ exactly their reachable rows, from the API and from the database alike.
1063
+
1064
+ Earlier releases routed these reads through the service-role handle
1065
+ (`createServiceDb`) instead, because the multi-hop join read the intermediate
1066
+ tables under their own tenant scopes and came back empty. That bypassed RLS for
1067
+ the whole read; the routing is gone.
1068
+
1069
+ The **same config compiles identically on D1**: the read handlers keep
1070
+ `c.get('db')`, and the app-layer reachability WHERE runs the join directly.
991
1071
 
992
1072
  ## Webhooks on Neon
993
1073
 
@@ -39,7 +39,7 @@ Condition 2 is broader than it may look, and deliberately so. There is no
39
39
  per-provider inbound webhook configuration surface: the inbound route registers
40
40
  exactly one provider, Stripe, so *any* project that turned webhooks on is a
41
41
  project that can receive Stripe events. The same condition adds `stripe` to the
42
- generated `package.json` (pinned at `^22.5.0`), so the dependency and the client
42
+ generated `package.json` (pinned at `^22.6.1`), so the dependency and the client
43
43
  can never disagree about whether Stripe is in play.
44
44
 
45
45
  > **Accepted over-trigger.** A project that only *receives* Stripe webhooks and
@@ -0,0 +1,278 @@
1
+ # Build a frontend
2
+
3
+ This guide builds a React app that lists, creates, edits, and closes jobs
4
+ against your API. It uses the [components](/ui/components) (shadcn registry
5
+ items) on top of the emitted [fetch client](/api/typescript#fetch-client).
6
+
7
+ ```
8
+ my-app/
9
+ ├── quickback.config.ts
10
+ ├── quickback/features/jobs/ # your API definitions
11
+ ├── src/ # generated Worker (never edit)
12
+ └── web/ # your React app (you own it)
13
+ └── src/lib/
14
+ ├── quickback.client.ts # emitted every compile
15
+ └── quickback.gen.ts # emitted every compile
16
+ ```
17
+
18
+ ## 1. Scaffold the app
19
+
20
+ From the project root, create a Vite app with a shadcn **base-ui** style. The
21
+ components don't support Radix styles.
22
+
23
+ ```bash
24
+ npx shadcn@latest init -t vite -b base -p nova -n web
25
+ cd web && npm install better-auth && cd ..
26
+ ```
27
+
28
+ ## 2. Emit the client into it
29
+
30
+ Add three keys to the scaffolded config and keep everything else:
31
+
32
+ ```typescript
33
+ // quickback.config.ts
34
+ import { defineConfig } from "@quickback/compiler";
35
+
36
+ export default defineConfig({
37
+ // …name, providers, etc. from the scaffold
38
+ types: { output: "web/src/lib/quickback.gen.ts" },
39
+ client: "web/src/lib/quickback.client.ts",
40
+ // The components read GET /api/v1/schema. Its default ("sysadmin")
41
+ // would 403 every other user; "member" admits organization members.
42
+ schemaRegistry: { access: "member" },
43
+ });
44
+ ```
45
+
46
+ The client imports its types from the first `types` output, so both files
47
+ live inside `web/`.
48
+
49
+ ## 3. Define the API
50
+
51
+ ```typescript
52
+ // quickback/features/jobs/jobs.ts
53
+ import { feature, q } from "@quickback/compiler";
54
+
55
+ export default feature("jobs", {
56
+ columns: {
57
+ id: q.id(),
58
+ title: q.text().required(),
59
+ department: q.text().required(),
60
+ status: q.text().default("open").required(),
61
+ salaryMin: q.int().optional(),
62
+ organizationId: q.scope("organization"),
63
+ ...q.audit(),
64
+ ...q.softDelete(),
65
+ },
66
+ guards: {
67
+ createable: ["title", "department", "salaryMin"],
68
+ updatable: ["title", "department", "salaryMin"],
69
+ protected: { status: ["close"] },
70
+ },
71
+ read: { access: { roles: ["owner", "admin", "member"] } },
72
+ create: { access: { roles: ["owner", "admin"] } },
73
+ update: { access: { roles: ["owner", "admin"] } },
74
+ delete: { access: { roles: ["owner", "admin"] }, mode: "soft" },
75
+ });
76
+
77
+ // quickback/features/jobs/actions/close.ts
78
+ import { z } from "zod";
79
+ import { eq } from "drizzle-orm";
80
+ import { defineAction, jobs } from "../.quickback/define-action";
81
+
82
+ export default defineAction({
83
+ description: "Close the job to new applications",
84
+ input: z.object({ reason: z.string().optional() }),
85
+ access: { roles: ["owner", "admin"], record: { status: { equals: "open" } } },
86
+ async execute({ db, record }) {
87
+ const [row] = await db
88
+ .update(jobs)
89
+ .set({ status: "closed" })
90
+ .where(eq(jobs.id, record.id))
91
+ .returning();
92
+ return row;
93
+ },
94
+ });
95
+ ```
96
+
97
+ `status` is `protected`: the form shows it disabled, and only `close` can
98
+ change it.
99
+
100
+ ```bash
101
+ quickback build # writes src/ and web/src/lib/quickback.{client,gen}.ts
102
+ npm run dev # API on http://localhost:8787
103
+ ```
104
+
105
+ ## 4. Add the components
106
+
107
+ In `web/components.json`, add the registry:
108
+
109
+ ```json
110
+ {
111
+ "registries": {
112
+ "@quickback": "https://docs.quickback.dev/r/{style}/{name}.json"
113
+ }
114
+ }
115
+ ```
116
+
117
+ ```bash
118
+ cd web
119
+ npx shadcn add @quickback/resource-table @quickback/resource-form @quickback/action-dialog
120
+ npx shadcn add dialog
121
+ ```
122
+
123
+ This installs `quickback-provider` too, since every item depends on it.
124
+
125
+ ## 5. Sign in and render
126
+
127
+ ```tsx
128
+ // web/src/lib/api.ts
129
+ import { createAuthClient } from "better-auth/react"
130
+ import { organizationClient } from "better-auth/client/plugins"
131
+ import { createClient } from "@/lib/quickback.client"
132
+
133
+ const baseURL = import.meta.env.VITE_API_URL ?? "http://localhost:8787"
134
+
135
+ export const auth = createAuthClient({ baseURL, basePath: "/auth/v1", plugins: [organizationClient()] })
136
+ export const client = createClient({ baseUrl: baseURL })
137
+ ```
138
+
139
+ ```tsx
140
+ // web/src/App.tsx
141
+ import { useState } from "react"
142
+ import { auth, client } from "@/lib/api"
143
+ import { buttonVariants } from "@/components/ui/button"
144
+ import { Dialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog"
145
+ import { QuickbackProvider } from "@/components/quickback-provider"
146
+ import { ResourceTable } from "@/components/resource-table"
147
+ import { ResourceForm } from "@/components/resource-form"
148
+ import { ActionDialog } from "@/components/action-dialog"
149
+
150
+ export default function App() {
151
+ const session = auth.useSession()
152
+ const member = auth.useActiveMember()
153
+ if (session.isPending) return null
154
+ if (!session.data) return <SignIn />
155
+ // Roles are a UI hint (masking, hiding Delete); the API stays authoritative.
156
+ return (
157
+ <QuickbackProvider client={client} roles={member.data ? [member.data.role] : undefined}>
158
+ <Jobs />
159
+ </QuickbackProvider>
160
+ )
161
+ }
162
+
163
+ function SignIn() {
164
+ const [error, setError] = useState<string>()
165
+ async function submit(form: FormData) {
166
+ const res = await auth.signIn.email({
167
+ email: String(form.get("email")),
168
+ password: String(form.get("password")),
169
+ })
170
+ if (res.error) return setError(res.error.message)
171
+ // Tables are firewalled to the active organization — pick one.
172
+ const orgs = await auth.organization.list()
173
+ const org = orgs.data?.[0] ?? (await auth.organization.create({ name: "Acme", slug: `acme-${Date.now()}` })).data
174
+ if (org) await auth.organization.setActive({ organizationId: org.id })
175
+ }
176
+ return (
177
+ <form action={submit} className="mx-auto flex max-w-sm flex-col gap-2 p-6">
178
+ <label>Email <input name="email" type="email" required /></label>
179
+ <label>Password <input name="password" type="password" required /></label>
180
+ <button className={buttonVariants()}>Sign in</button>
181
+ {error && <p role="alert">{error}</p>}
182
+ </form>
183
+ )
184
+ }
185
+
186
+ function Jobs() {
187
+ const [editing, setEditing] = useState<string | null>() // undefined closed, null create
188
+ const [closing, setClosing] = useState<string>()
189
+ const done = () => setEditing(undefined)
190
+
191
+ return (
192
+ <main className="mx-auto flex max-w-5xl flex-col gap-4 p-6">
193
+ <button className={buttonVariants()} onClick={() => setEditing(null)}>New job</button>
194
+
195
+ <ResourceTable
196
+ table="jobs"
197
+ onRowClick={(row) => setEditing(String(row.id))}
198
+ rowActions={(row) => (
199
+ <button className={buttonVariants({ variant: "outline", size: "sm" })} onClick={() => setClosing(String(row.id))}>
200
+ Close
201
+ </button>
202
+ )}
203
+ />
204
+
205
+ <Dialog open={editing !== undefined} onOpenChange={(open) => !open && done()}>
206
+ <DialogContent>
207
+ <DialogHeader><DialogTitle>{editing ? "Edit job" : "New job"}</DialogTitle></DialogHeader>
208
+ {editing !== undefined && (
209
+ <ResourceForm table="jobs" id={editing ?? undefined} onSuccess={done} onCancel={done} onDeleted={done} />
210
+ )}
211
+ </DialogContent>
212
+ </Dialog>
213
+
214
+ <ActionDialog
215
+ table="jobs"
216
+ action="close"
217
+ id={closing}
218
+ open={closing !== undefined}
219
+ onOpenChange={(open) => !open && setClosing(undefined)}
220
+ />
221
+ </main>
222
+ )
223
+ }
224
+ ```
225
+
226
+ Create an account first. Either `POST /auth/v1/sign-up/email` as in the
227
+ [quickstart](/start/quickstart#test-your-api), or add a sign-up form with
228
+ `auth.signUp.email`. Then run the app:
229
+
230
+ ```bash
231
+ npm run dev # http://localhost:5173
232
+ ```
233
+
234
+ The browser sends the Better Auth session cookie with every request.
235
+ `http://localhost:5173` is a trusted origin by default until the project has
236
+ a production domain, so writes pass the CSRF check. See
237
+ [Auth](/ui/components/auth) for the rules, and for bearer tokens in React
238
+ Native.
239
+
240
+ What you get for free:
241
+
242
+ - **Only permitted fields.** The form shows `guards.createable` /
243
+ `updatable`, and `status` stays locked.
244
+ - **Errors inline.** A guard or validation `400` shows under its field. A
245
+ `403` shows the problem's `detail`.
246
+ - **Close only when open.** The action's `record` precondition runs on the
247
+ server. Closing a closed job shows the rejection in the dialog.
248
+ - **Role-aware.** Delete and `close` both require `owner` or `admin`. A
249
+ `member` therefore sees no Delete button, and the Close dialog shows a role
250
+ message instead of its form. The API enforces the same rules either way.
251
+
252
+ ## 6. Ship it on the same Worker
253
+
254
+ Serve the built app from the API's own Worker. It shares the API's origin, so
255
+ it needs no CORS setup, and its hostname is trusted automatically.
256
+
257
+ ```bash
258
+ cd web && VITE_API_URL=https://app.example.com npm run build && cd ..
259
+ rm -rf quickback/apps/web && cp -r web/dist quickback/apps/web
260
+ ```
261
+
262
+ ```typescript
263
+ // quickback.config.ts — add alongside the rest
264
+ apps: {
265
+ web: { domain: "app.example.com" },
266
+ },
267
+ ```
268
+
269
+ `quickback build` copies `quickback/apps/web/` into the Worker's assets, then
270
+ `quickback deploy` ships both. See
271
+ [App domains](/configure/domains#app-domains). To host the app elsewhere
272
+ instead, add its origin to [`trustedOrigins`](/configure#trusted-origins).
273
+
274
+ ## Next
275
+
276
+ - [Components](/ui/components): every prop and hook
277
+ - [Fetch client](/api/typescript#fetch-client): typed calls beyond the components
278
+ - [Query parameters](/api/query-params): what `useList` params map to
@@ -36,6 +36,7 @@ quickback/
36
36
  - **[Define](/define)** — the DSL: schema, the security pillars, reads, writes, actions
37
37
  - **[Configure](/configure)** — `quickback.config.ts`, providers, domains, bindings
38
38
  - **[Use the API](/api)** — what the generated endpoints look like
39
+ - **[Build a frontend](/start/frontend)** — a React app on your API with the typed client and shadcn components
39
40
 
40
41
  The rest of this page is the vocabulary the other pages assume.
41
42
 
@@ -135,7 +135,29 @@ generated typing surfaces:
135
135
  surface. `import { feature, q, defineTable, defineConfig } from
136
136
  "@quickback/compiler"` resolves in table files and `quickback.config.ts`,
137
137
  so a bad builder call or an unknown resource-config key is a type error at
138
- the desk, not a compile-round-trip later.
138
+ the desk, not a compile-round-trip later. `services/` files' `import {
139
+ defineQueue } from "quickback"` resolves to the same surface, and provider
140
+ entries type-check in both forms the build accepts — `defineDatabase(...)`
141
+ or the literal `{ name: "neon", config: { … } }`.
142
+
143
+ The check resolves imports the way the build does, so a clean check is not
144
+ undone by the compile:
145
+
146
+ - **Named table imports from feature files** —
147
+ `import { mailboxes } from "../../mailboxes/mailboxes"` in an action, a
148
+ `lib/` file, or a queue handler. A `feature()` file has only a default
149
+ export; the build points that path at the generated table module, and
150
+ `quickback/.quickback/feature-tables.d.ts` gives the check the same named
151
+ export, typed from the generated schema.
152
+ - **Queue handlers' dynamic imports** — `await import("./features/…")` is
153
+ written against the generated `src/` (the handler body is inlined into
154
+ `src/queue-consumer.ts`); the tsconfig's `rootDirs` resolves it there too.
155
+ - **Service handler contexts** — queue, schedule and email handlers get the
156
+ `db`, `env` and `services` the generated runners pass them: your project's
157
+ Drizzle handle, `CloudflareBindings` and `Services`
158
+ (`quickback/.quickback/service-runtime.d.ts`). A wrong column on a
159
+ `db.select()` result or an undeclared binding is a check error, as it is in
160
+ the build.
139
161
 
140
162
  No compile, no server: this is your editor's view of the source, on demand.
141
163
 
@@ -145,11 +167,10 @@ Exit codes: `0` clean · `1` type errors · `2` setup missing. A fresh clone
145
167
  the check resolves against. Re-run `quickback build` after schema changes so
146
168
  they track your tables.
147
169
 
148
- Actions that still import a table from the authored feature file
149
- (`import { tickets } from "../tickets"`) fail the check — the q-DSL feature
150
- file has only a default export. Import the table from the typed helper
151
- instead (`import { defineAction, tickets } from "../.quickback/define-action"`);
152
- `quickback migrate helper-imports` rewrites the safe cases for you.
170
+ Within a feature, the single helper import
171
+ (`import { defineAction, tickets } from "../.quickback/define-action"`) is
172
+ still the tidier form; `quickback migrate helper-imports` rewrites the safe
173
+ cases for you.
153
174
 
154
175
  ### Synchronize Managed Columns
155
176
 
@@ -190,7 +211,7 @@ quickback migrate helper-imports [--dry-run] # single typed helper import
190
211
 
191
212
  ```ts
192
213
  import { defineAction } from "../.quickback/define-action";
193
- import { applications } from "../applications"; // resolves to the authored file
214
+ import { applications } from "../applications"; // second import, same feature
194
215
  ```
195
216
 
196
217
  — to the single typed import the helpers are designed for:
@@ -94,6 +94,12 @@ A failed generate or postprocessor leaves existing migration history untouched.
94
94
  Do not use raw `drizzle-kit generate` as an equivalent workaround for an auth
95
95
  upgrade: it skips Quickback's OAuth client backfills and resource-grant cleanup.
96
96
 
97
+ `drizzle-kit exited after answering a rename prompt without writing a migration`
98
+ means the generator process ended mid-prompt. A prompt only appears when there
99
+ is a schema diff, so this is always a failure: nothing was written and the
100
+ existing history is untouched. Re-run the build; if it repeats, report it with
101
+ the Drizzle output from the error.
102
+
97
103
  ## `Critical command failed: Generate features database migrations`
98
104
 
99
105
  drizzle-kit could not load the generated **features** schema. The usual cause on
@@ -50,8 +50,10 @@ src/
50
50
  # Authored-tree typing (regenerated on every compile, gitignored)
51
51
  quickback/tsconfig.json # Typechecks the authored quickback/ tree (`quickback check`)
52
52
  quickback/.quickback/
53
- └── compiler/ # @quickback/compiler declaration snapshot — resolves
54
- └── … # `import { feature, q, defineTable } from "@quickback/compiler"`
53
+ ├── compiler/ # @quickback/compiler declaration snapshot — resolves
54
+ │ └── … # `import { feature, q, defineTable } from "@quickback/compiler"`
55
+ ├── feature-tables.d.ts # Named table exports of feature() files, typed from the generated schema
56
+ └── service-runtime.d.ts # db / env / services types for queue, schedule and email handlers (when any exist)
55
57
  quickback/features/{feature}/
56
58
  └── .quickback/
57
59
  └── define-action.ts # Authored-tree twin of the typed helper below
@@ -257,6 +259,16 @@ projects acquire build and deployment fixes without losing unrelated tooling.
257
259
 
258
260
  These files are generated only when the corresponding features are configured:
259
261
 
262
+ ### TypeScript artifacts
263
+
264
+ | File | Emitted | Config |
265
+ |------|---------|--------|
266
+ | `quickback.gen.ts` | By default | [`types`](/api/typescript#configuration) |
267
+ | `api-types.gen.ts` | By default | [`openapi.types`](/api/openapi) |
268
+ | `quickback.client.ts` | Opt-in | [`client`](/api/typescript#fetch-client) — a zero-dependency `fetch` client typed by `quickback.gen.ts`; the [components](/ui/components) build on it |
269
+
270
+ All three sit outside `src/`, and each accepts a custom path or a list of paths.
271
+
260
272
  ### Database provider setup files
261
273
 
262
274
  Every compile emits an environment example named for the configured provider.
@@ -410,6 +422,15 @@ Set `compiler.securityContracts.report.signature.required: true` to fail compila
410
422
 
411
423
  The report names the compiler that produced it twice: `compilerVersion` is the semver, and `compilerBuildId` is `<version>@<gitSha>@<builtAt>` — the same string the compiler's `/health` endpoint reports as `buildId`. The semver is a floor that can serve several hosted builds, so a drift tripwire should pin on `compilerBuildId`, not `compilerVersion`.
412
424
 
425
+ ### Data Remediation Report
426
+
427
+ `reports/data-remediation.sql` is emitted when the project has something to check. It is **read-only as emitted** — every statement is a `SELECT`, and the compiler never runs it:
428
+
429
+ - **SQLite / D1:** a count of rows whose `.defaultNow()` or audit timestamp holds the `1970-01-01T00:00:00.000Z` epoch sentinel, per column, with a commented-out repair `UPDATE` where the row has a separate `created_at` to approximate from.
430
+ - **Every dialect:** per `q.url()` column, the rows whose value is not an `http(s)` URL (`javascript:`, `data:`, …).
431
+
432
+ How to run it and what the repair means: [Troubleshooting → Data issues](/tooling/troubleshooting#data-issues).
433
+
413
434
  ### Realtime
414
435
 
415
436
  When any feature has `realtime` configured:
@@ -457,24 +478,28 @@ The compiler separates schemas into two files:
457
478
 
458
479
  ## Generated Routes
459
480
 
460
- For each feature, the compiler generates a routes file at `src/features/{name}/routes.ts` containing:
481
+ For each table with routes, the compiler generates `src/features/{feature}/{table}.routes.ts` containing:
461
482
 
462
483
  | Route | Generated When |
463
484
  |-------|----------------|
464
- | `GET /` | `crud.list` configured |
465
- | `GET /:id` | `crud.get` configured |
485
+ | `GET /` | [`read`](/define/read) declared |
486
+ | `GET /:id` | [`read`](/define/read) declared |
487
+ | `GET /views/{name}` | `read.views.{name}` declared |
466
488
  | `POST /` | `crud.create` configured |
467
489
  | `PATCH /:id` | `crud.update` configured |
468
490
  | `DELETE /:id` | `crud.delete` configured |
469
- | `PUT /:id` | `crud.put` configured |
470
- | `POST /batch` | `crud.create` exists (auto-enabled) |
471
- | `PATCH /batch` | `crud.update` exists (auto-enabled) |
472
- | `DELETE /batch` | `crud.delete` exists (auto-enabled) |
473
- | `PUT /batch` | `crud.put` exists (auto-enabled) |
474
- | `GET /views/{name}` | `views` configured |
491
+ | `PUT /:id` | `crud.put` configured, with `generateId: false` and `guards: false` |
492
+ | `POST /batch` | `crud.create` exists (auto-enabled; `crud.batchCreate: false` opts out) |
493
+ | `PATCH /batch` | `crud.update` exists (auto-enabled; `crud.batchUpdate: false` opts out) |
494
+ | `DELETE /batch` | `crud.delete` exists (auto-enabled; `crud.batchDelete: false` opts out) |
495
+ | `PUT /batch` | `crud.batchUpsert`, or `crud.create` + `crud.update` when `PUT` is enabled |
475
496
  | `POST /:id/{action}` | Record-based actions defined |
476
497
  | `POST /{action}` | Standalone actions defined |
477
498
 
499
+ `crud.list` and `crud.get` are rejected at compile time — collection and
500
+ single-record reads come from `read`. A verb with `routes: false` or mapped to
501
+ an action (`crud.create.action`) emits no raw route and no batch variant.
502
+
478
503
  Routes are mounted under `/api/v1/{feature}` by default, or
479
504
  `/api/v2/{feature}` when `contract: { routes: "v2" }` is set. The standard API shape
480
505
  selects semantics and leaves these paths alone.
@@ -541,6 +566,12 @@ is drift on a live database with no clean fix-forward.
541
566
  Only `meta/_journal.json` is expected to change, because that is where a new
542
567
  entry lands.
543
568
 
569
+ The generated header and footer comments count as part of the file. New
570
+ migrations are stamped with the current header; an existing one keeps the
571
+ header it was first stamped with, byte for byte, because deploy ledgers hash
572
+ applied migrations. See [Troubleshooting](/tooling/troubleshooting#recompile-changed-the-comments-at-the-top-of-an-old-migration)
573
+ if an earlier compiler already rewrote one.
574
+
544
575
  > If `quickback migrations doctor` reports snapshot drift — more journal entries
545
576
  > than snapshot files — that drift came from your project's history, not from
546
577
  > compiling. Compile does not delete snapshots it was never given.