@quickback-dev/cli 0.59.0 → 0.59.1

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 (97) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +14 -1
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/commands/schema.d.ts +10 -0
  5. package/dist/commands/schema.d.ts.map +1 -1
  6. package/dist/commands/schema.js +48 -16
  7. package/dist/commands/schema.js.map +1 -1
  8. package/dist/commands/schema.test.js +81 -1
  9. package/dist/commands/schema.test.js.map +1 -1
  10. package/dist/docs/content.d.ts.map +1 -1
  11. package/dist/docs/content.js +41 -21
  12. package/dist/docs/content.js.map +1 -1
  13. package/dist/index.js +1 -1
  14. package/dist/lib/file-loader.d.ts +10 -0
  15. package/dist/lib/file-loader.d.ts.map +1 -1
  16. package/dist/lib/file-loader.js +41 -22
  17. package/dist/lib/file-loader.js.map +1 -1
  18. package/dist/lib/file-loader.test.js +20 -1
  19. package/dist/lib/file-loader.test.js.map +1 -1
  20. package/dist/lib/prepare-output.d.ts +2 -0
  21. package/dist/lib/prepare-output.d.ts.map +1 -1
  22. package/dist/lib/prepare-output.js +2 -2
  23. package/dist/lib/prepare-output.js.map +1 -1
  24. package/dist/lib/prepare-state-output.d.ts +33 -4
  25. package/dist/lib/prepare-state-output.d.ts.map +1 -1
  26. package/dist/lib/prepare-state-output.js +71 -12
  27. package/dist/lib/prepare-state-output.js.map +1 -1
  28. package/dist/lib/prepare-state-output.test.js +91 -11
  29. package/dist/lib/prepare-state-output.test.js.map +1 -1
  30. package/dist/lib/schema-sync/index.d.ts.map +1 -1
  31. package/dist/lib/schema-sync/index.js +39 -4
  32. package/dist/lib/schema-sync/index.js.map +1 -1
  33. package/dist/lib/schema-sync/index.test.js +89 -1
  34. package/dist/lib/schema-sync/index.test.js.map +1 -1
  35. package/dist/schema-engine/index.d.ts +1 -0
  36. package/dist/schema-engine/index.d.ts.map +1 -1
  37. package/dist/schema-engine/index.js +50 -0
  38. package/dist/schema-engine/index.js.map +3 -3
  39. package/dist/schema-engine/provider-dialects.d.ts +22 -0
  40. package/dist/schema-engine/provider-dialects.d.ts.map +1 -0
  41. package/dist/schema-engine/source-sync.d.ts +8 -0
  42. package/dist/schema-engine/source-sync.d.ts.map +1 -1
  43. package/dist/skill/SKILL.md +45 -0
  44. package/dist/skill/agents/quickback-specialist/AGENT.md +18 -1
  45. package/dist/skill/docs/changelog/index.md +28 -2
  46. package/dist/skill/docs/changelog/v0.1x.md +2 -2
  47. package/dist/skill/docs/configure/agents.md +19 -0
  48. package/dist/skill/docs/configure/index.md +1 -1
  49. package/dist/skill/docs/define/access.md +23 -820
  50. package/dist/skill/docs/define/actions/access.md +4 -4
  51. package/dist/skill/docs/define/areas.md +307 -4
  52. package/dist/skill/docs/define/authz-roles.md +164 -0
  53. package/dist/skill/docs/define/changesets.md +1 -1
  54. package/dist/skill/docs/define/fga.md +1 -1
  55. package/dist/skill/docs/define/firewall.md +3 -3
  56. package/dist/skill/docs/define/index.md +32 -3
  57. package/dist/skill/docs/define/masking.md +1 -1
  58. package/dist/skill/docs/define/permissions.md +1 -1
  59. package/dist/skill/docs/define/read.md +103 -1
  60. package/dist/skill/docs/define/relationships.md +313 -0
  61. package/dist/skill/docs/define/scopes.md +1 -1
  62. package/dist/skill/docs/platform/realtime/using-realtime.md +1 -1
  63. package/dist/skill/docs/platform/storage/r2.md +39 -0
  64. package/dist/skill/docs/platform/webhooks/inbound.md +17 -6
  65. package/dist/skill/docs/start/deploy-browser.md +118 -0
  66. package/dist/skill/docs/start/deploy-owner-access.md +62 -0
  67. package/dist/skill/docs/start/deploy.md +2 -0
  68. package/dist/skill/docs/tooling/cli.md +22 -0
  69. package/dist/skill/docs/tooling/output.md +64 -0
  70. package/package.json +1 -1
  71. package/src/skill/SKILL.md +45 -0
  72. package/src/skill/agents/quickback-specialist/AGENT.md +18 -1
  73. package/src/skill/docs/changelog/index.md +28 -2
  74. package/src/skill/docs/changelog/v0.1x.md +2 -2
  75. package/src/skill/docs/configure/agents.md +19 -0
  76. package/src/skill/docs/configure/index.md +1 -1
  77. package/src/skill/docs/define/access.md +23 -820
  78. package/src/skill/docs/define/actions/access.md +4 -4
  79. package/src/skill/docs/define/areas.md +307 -4
  80. package/src/skill/docs/define/authz-roles.md +164 -0
  81. package/src/skill/docs/define/changesets.md +1 -1
  82. package/src/skill/docs/define/fga.md +1 -1
  83. package/src/skill/docs/define/firewall.md +3 -3
  84. package/src/skill/docs/define/index.md +32 -3
  85. package/src/skill/docs/define/masking.md +1 -1
  86. package/src/skill/docs/define/permissions.md +1 -1
  87. package/src/skill/docs/define/read.md +103 -1
  88. package/src/skill/docs/define/relationships.md +313 -0
  89. package/src/skill/docs/define/scopes.md +1 -1
  90. package/src/skill/docs/platform/realtime/using-realtime.md +1 -1
  91. package/src/skill/docs/platform/storage/r2.md +39 -0
  92. package/src/skill/docs/platform/webhooks/inbound.md +17 -6
  93. package/src/skill/docs/start/deploy-browser.md +118 -0
  94. package/src/skill/docs/start/deploy-owner-access.md +62 -0
  95. package/src/skill/docs/start/deploy.md +2 -0
  96. package/src/skill/docs/tooling/cli.md +22 -0
  97. package/src/skill/docs/tooling/output.md +64 -0
@@ -0,0 +1,118 @@
1
+ # Deploy from your browser
2
+
3
+ Build a backend in [Quickback Start](https://start.quickback.dev), get a green compile, and ship it to **your own Cloudflare account** with one click — databases created, migrations applied, secrets minted, Worker live on a `workers.dev` URL. No local tooling required.
4
+
5
+ This page covers the browser flow. For local projects, or anything the browser flow doesn't support yet, use [`quickback deploy`](/start/deploy) — the CLI covers every resource type and is always available.
6
+
7
+ > Browser deployment is rolling out. The hosted deploy service ships fail-closed behind a kill switch while the final authentication work lands; if the Deploy card doesn't appear in Start, your session isn't in the rollout yet. `quickback deploy` works for everyone today.
8
+
9
+
10
+ ## Browser vs CLI
11
+
12
+ | | Deploy from Start | `quickback deploy` |
13
+ |---|---|---|
14
+ | Where you work | start.quickback.dev chat | Your terminal, local project |
15
+ | Cloudflare auth | OAuth consent (no tokens handled by you) | `wrangler login` / `CLOUDFLARE_API_TOKEN` |
16
+ | Resource coverage | The supported matrix below, fail-closed | Everything the compiler emits |
17
+ | Custom domains | Not yet — `workers.dev` only | Yes, via your `wrangler.toml` routes |
18
+ | Best for | Chat-built apps, first deploys, demos | Local development, full-featured apps, CI |
19
+
20
+ ## How a deploy runs
21
+
22
+ When you click **Deploy this app**, the pipeline runs four phases and reports each one:
23
+
24
+ 1. **Compile** — your project compiles on the hosted compiler and emits a *deployment manifest*: the exact set of resources, migrations, and secrets the deploy will touch. Anything the browser flow can't deploy fails **here**, with a named reason — never as a half-deployed app.
25
+ 2. **Provision** — each D1 database, KV namespace, and R2 bucket is created in your account, or **adopted** if a resource with the same name already exists. Retries and redeploys never create duplicates. Nothing is ever deleted automatically.
26
+ 3. **Package** — the project recompiles with the real resource ids folded in and is bundled into Worker modules (plus your CMS/Account SPA assets, when enabled). Every byte is hash-verified against the manifest before anything is uploaded.
27
+ 4. **Finalize** — migrations apply, the Worker uploads with its bindings, secrets are set, and the `workers.dev` route is enabled. Start probes the URL and only shows **Live** once it actually answers.
28
+
29
+ A typical deploy takes one to two minutes, most of it compilation.
30
+
31
+ ## What deploys
32
+
33
+ Supported today, end to end:
34
+
35
+ | Resource | Notes |
36
+ |---|---|
37
+ | D1 databases | All of a project's databases — auth, features, and (when your features pull them in) audit, webhooks, and file-metadata |
38
+ | KV namespace | The `KV` binding for rate limiting and session overflow |
39
+ | R2 bucket | Managed file storage (`managed: true`) |
40
+ | Realtime | The inline Broadcaster Durable Object, including its class registration |
41
+ | Email binding | The Cloudflare Email Service binding is attached (see the delivery caveat below) |
42
+ | CMS / Account UI | The bundled SPAs upload as static assets on the same Worker, with your app's real URL baked in |
43
+
44
+ Blocked, fail-closed at the compile phase — the deploy stops with the reason, and `quickback deploy` remains the path for these:
45
+
46
+ | Blocked | Why |
47
+ |---|---|
48
+ | Webhooks, embeddings | Need queue and Workers AI bindings the broker can't create yet |
49
+ | Vectorize | Not yet supported |
50
+ | Neon / Postgres | Browser deploys are D1-only; Neon projects deploy via the CLI |
51
+ | Separate-worker realtime | Needs a second Worker + service binding |
52
+ | Custom `apps:` mounts | Typically need custom domains |
53
+ | Custom `bindings:` (Durable Objects, queues, services, extra R2 buckets) | Not represented by the deploy contract yet |
54
+ | Secrets you supply (third-party API keys, etc.) | The browser flow has no way to collect them yet — a project that *requires* one is refused rather than deployed broken |
55
+ | Hyperdrive, public R2 buckets, containers, workflows | Out of MVP scope |
56
+
57
+ > **Email delivery**: the email *binding* is attached so your app boots and auth works, but actually sending mail requires Email Sending to be configured on your Cloudflare account with a verified sending domain — which a fresh `workers.dev` app doesn't have. Start's builder defaults new apps to email + password **without** email verification for exactly this reason; enable verification, OTP, or magic links after you've configured a sending domain.
58
+
59
+
60
+ ## Connecting your Cloudflare account
61
+
62
+ The first deploy starts with **Continue with Cloudflare** — a standard OAuth consent against Cloudflare's own dashboard, shown by the **Quickback** OAuth client. You pick the account, see exactly which permissions are requested, and can revoke at any time from Cloudflare under **My Profile → Access Management → Connected Applications** (or disconnect from Start).
63
+
64
+ What's requested, and why:
65
+
66
+ | Scope | Used for |
67
+ |---|---|
68
+ | `openid`, `user-details.read` | Identifying the connection (your email is stored masked, e.g. `p***@example.com`) |
69
+ | `memberships.read` | The account picker — so you never copy a 32-character account id |
70
+ | `account-settings.read` | Looking up your `workers.dev` subdomain to build your app's URL |
71
+ | `workers-scripts.write` | Uploading the Worker, enabling its route, setting its secrets |
72
+ | `d1.write` | Creating databases and applying migrations |
73
+ | `workers-kv-storage.write` | Creating the KV namespace |
74
+ | `workers-r2.write` | Creating file-storage buckets |
75
+
76
+ Nothing broader is requested — no zone, DNS, billing, or account-management access.
77
+
78
+ ## Where your token lives
79
+
80
+ The OAuth token never reaches your browser, the chat model, or the compiler. It is held by the deploy service and:
81
+
82
+ - encrypted at rest with AES-256-GCM under a versioned key-encryption key;
83
+ - bound to its connection record (the ciphertext is unusable if copied elsewhere);
84
+ - decrypted only inside the API calls of an active deploy, then discarded.
85
+
86
+ Tokens expire; when one does, Start shows a reconnect prompt and a fresh consent re-issues it onto the same connection. Revoking in Cloudflare kills the token immediately — the stored ciphertext becomes useless.
87
+
88
+ ## Secrets on the deployed app
89
+
90
+ - `BETTER_AUTH_SECRET` is minted by the deploy service — 256 bits of fresh entropy per app — and set on the Worker directly. It's never shown to the browser or stored in your project.
91
+ - **Existing Worker secrets are always preserved.** Cloudflare's upload API replaces a Worker's bindings wholesale; the deploy explicitly carries every existing secret across, so a redeploy can never silently delete a secret you set by hand.
92
+
93
+ ## Redeploys are safe by construction
94
+
95
+ Click Deploy as often as you like:
96
+
97
+ - **Provisioning adopts** — existing resources are matched by name and reused, never duplicated, never deleted.
98
+ - **Migrations apply exactly once** — a ledger in each database records every applied migration with a content hash. Already-applied migrations are skipped (even when a recompile renames the file), and a migration whose *content changed after it ran* refuses the deploy outright instead of corrupting the schema.
99
+ - **Assets are content-addressed** — a redeploy with unchanged CMS/Account assets uploads zero bytes.
100
+ - **Realtime classes register once** — Durable Object registrations follow Cloudflare's append-only chronology; a redeploy sends nothing new.
101
+
102
+ ## After it's live
103
+
104
+ Your app answers at `https://<app-name>.<your-subdomain>.workers.dev`:
105
+
106
+ - **API-only apps** serve a small landing page at `/` (browsers) and a JSON service descriptor (everything else), linking `/api/v1`, `/openapi.json`, and `/health` — never a bare 404 on first visit.
107
+ - **Apps with the Account UI or CMS** redirect `/` to the login page or CMS.
108
+ - `/health` reports status and whether email is configured.
109
+
110
+ The deployed app is a normal Worker in *your* account: logs, metrics, and settings live in your Cloudflare dashboard, and you can take over management with the CLI at any time — download the project from Start and `quickback deploy` picks up the same resources by name.
111
+
112
+ ## Not yet available
113
+
114
+ - **Owner login in deployed apps** ("Continue with Cloudflare" as the app's admin sign-in) — the UI half ships with the Account SPA, but the server half and its per-app OAuth client are still in progress.
115
+ - **Custom domains** for browser-deployed apps — `workers.dev` only for now.
116
+ - The blocked resources listed above.
117
+
118
+ These all work — or will work first — through [`quickback deploy`](/start/deploy).
@@ -0,0 +1,62 @@
1
+ # Owner access after a browser deploy
2
+
3
+ When you deploy from Quickback Start's **Deploy to Cloudflare** card, the very
4
+ first deploy seeds your app's first administrator (an `appmanager` user) and
5
+ shows a **one-time claim link** next to the live URL:
6
+
7
+ ```
8
+ https://<your-app>.<subdomain>.workers.dev/__quickback/claim#token=…
9
+ ```
10
+
11
+ Opening it lets you set your email and a password, and you're the app's admin.
12
+ That's the whole setup.
13
+
14
+ ## What the claim link is
15
+
16
+ - **One-time and short-lived.** The link works once and expires about six
17
+ hours after the deploy. It's shown exactly once, in the deploy card —
18
+ Quickback keeps no copy of it.
19
+ - **Owner-only.** The link can only claim the admin account the deploy
20
+ seeded. It can never create a new account or elevate an existing one.
21
+ - **Fragment-carried.** The token rides the URL fragment (`#token=…`), which
22
+ browsers never send to servers — it stays out of request logs entirely.
23
+ - **Closed once it's used.** The claim page checks the link before it renders
24
+ anything: a spent, expired, or unrecognised token gets a "this app has
25
+ already been claimed" message instead of a form. Visiting
26
+ `/__quickback/claim` without a valid token never shows a working signup.
27
+
28
+ The record of a used link lives in your app's own database, so single-use is
29
+ enforced exactly — there's no window in which a spent link claims again.
30
+
31
+ ## What happens when you claim
32
+
33
+ 1. You open the link and choose your **email** and a **password** (the seeded
34
+ placeholder email is synthetic — deployed apps can't send mail, so your
35
+ chosen address is marked verified directly).
36
+ 2. From that moment you sign in through **your app's own auth** — the same
37
+ email + password login every other user of your app gets. If your app has
38
+ the Account UI enabled, you land on `/account`; API-only apps sign in via
39
+ `POST /auth/v1/sign-in/email`.
40
+
41
+ **Quickback is not your app's identity provider.** The claim link is a
42
+ bootstrap window, not a login method: once claimed (or expired), your app has
43
+ no runtime dependency on Quickback or the deploy broker for authentication.
44
+
45
+ ## Lost access? Re-issue from Start
46
+
47
+ Deployed apps on `workers.dev` can't send password-reset email, so your
48
+ Cloudflare account is the recovery root: in the deploy card, **Re-issue admin
49
+ claim link** mints a fresh link — authorized by the same Cloudflare connection
50
+ that deployed the app. Re-claiming resets the admin password.
51
+
52
+ Every issue **rotates the signing key**, so any older link immediately stops
53
+ working, claimed or not. A fresh link re-opens the claim page on its own —
54
+ nothing has to be reset first, because "claimable" just means a signed,
55
+ unexpired, unused token exists.
56
+
57
+ ## For CLI deploys
58
+
59
+ The claim route only activates when the `QUICKBACK_CLAIM_KEY` Worker secret is
60
+ set — the browser-deploy broker mints it automatically. Apps deployed with
61
+ `quickback deploy` don't get a claim link (the route answers 404); create your
62
+ admin through your own flow, or deploy once through Start to bootstrap.
@@ -1,5 +1,7 @@
1
1
  # Deploying
2
2
 
3
+ Building in [Quickback Start](https://start.quickback.dev) instead of locally? You can also [deploy straight from the browser](/start/deploy-browser) — no CLI needed.
4
+
3
5
  A freshly compiled project's `wrangler.toml` contains **placeholder resource ids** — the compiler can't know your D1 database ids or KV namespace id until those resources exist in your Cloudflare account. Historically that meant a manual dance: `wrangler d1 create`, copy the id, paste it into `quickback.config.ts`, repeat for every database, recompile, deploy.
4
6
 
5
7
  `quickback deploy` does the whole dance for you:
@@ -130,6 +130,28 @@ Exit codes: `0` clean · `1` type errors · `2` setup missing. A fresh clone
130
130
  resolves against. Re-run `quickback compile` after schema changes so the
131
131
  helpers track your tables.
132
132
 
133
+ ### Synchronize Managed Columns
134
+
135
+ ```bash
136
+ quickback schema check # report missing managed-column declarations; read-only
137
+ quickback schema sync # write the safe additive declarations into authored files
138
+ quickback schema sync --dry-run # show the sync diff without writing
139
+ ```
140
+
141
+ Checks every authored table under `quickback/features/` for the managed
142
+ columns the compiler expects (audit timestamps, soft-delete markers) and —
143
+ on `sync` — writes the missing declarations into your source. `check` never
144
+ writes; anything that needs a human decision is reported as a diagnostic and
145
+ blocks the write.
146
+
147
+ The SQL dialect for written declarations comes from your configured database
148
+ provider — the same provider→dialect table the compiler uses. Postgres
149
+ providers (`supabase`, `neon`, `vercel-postgres`, `postgres`, `postgresql`)
150
+ get Postgres declarations; SQLite providers (`cloudflare-d1`,
151
+ `better-sqlite3`, `bun-sqlite`, `libsql`, `turso`) get SQLite. MySQL
152
+ providers are refused with an error rather than written in the wrong
153
+ dialect; no provider (or an unrecognized one) defaults to SQLite.
154
+
133
155
  ### Authored-Source Codemods
134
156
 
135
157
  ```bash
@@ -74,6 +74,49 @@ Not every per-feature file is always emitted:
74
74
  - `schema.ts`, `{feature}.ts`, and `{feature}.resource.ts` are skipped for tableless features.
75
75
  - A multi-table feature gets one alias file per table (`{feature}.ts`, `{other_table}.ts`) alongside the single `schema.ts`.
76
76
 
77
+ ## Spec Blobs Load As Text
78
+
79
+ The generated `wrangler.toml` contains a rule you did not configure:
80
+
81
+ ```toml
82
+ [[rules]]
83
+ type = "Text"
84
+ globs = ["**/openapi.json", "**/asyncapi.json", "**/schema-registry.json"]
85
+ ```
86
+
87
+ This is deliberate, and it exists to protect cold-start time.
88
+
89
+ A Worker has a limited CPU budget for its **startup window** — the module
90
+ evaluation that runs before the first request is served. A plain JSON import is
91
+ inlined by the bundler as a JavaScript object literal, so the runtime parses it
92
+ as source and builds the entire object graph during that window. For a large
93
+ API the spec is the single biggest thing in the bundle, and the cost is paid on
94
+ every cold start to serve discovery routes that most callers never request.
95
+
96
+ Loading the blobs as text means startup only allocates a string. The generated
97
+ `src/index.ts` parses each one lazily, on first request, and memoizes it:
98
+
99
+ ```ts
100
+ import openapiSpecText from '../openapi.json';
101
+
102
+ let __openapiSpec: unknown;
103
+ const openapiSpec = () => (__openapiSpec ??= JSON.parse(openapiSpecText as unknown as string));
104
+
105
+ app.get('/openapi.json', (c) => c.json(openapiSpec()));
106
+ ```
107
+
108
+ Behavior is unchanged — the same routes return the same payloads. Only *when*
109
+ the parse happens moves.
110
+
111
+ The saving scales with spec size. On a ~7 MB spec this cut measured startup CPU
112
+ by roughly 40%; below ~0.5 MB it is within measurement noise. Projects that
113
+ emit no spec are unaffected, because bundler rules only apply to files that are
114
+ actually imported.
115
+
116
+ **Warning:** Do not hand-edit this rule out. Without it the `…Text` imports
117
+ resolve to parsed objects and `JSON.parse` receives an object instead of a
118
+ string.
119
+
77
120
  ## Generated Package Dependency Security
78
121
 
79
122
  For projects using Better Auth, the generated `package.json` keeps the stable
@@ -298,6 +341,27 @@ Migration and report artifacts are written to the `quickback/` state directory:
298
341
  - `quickback/drizzle/...` for Drizzle migration SQL/meta artifacts
299
342
  - `quickback/reports/...` for security contract report artifacts
300
343
 
344
+ ### Migration history is never wiped
345
+
346
+ Unlike `src/`, the `quickback/drizzle/` tree is **not** hermetic — it is history,
347
+ and history is only ever appended to or superseded.
348
+
349
+ To keep compile payloads small, the CLI uploads every migration `.sql` and
350
+ `_journal.json` but only the **newest** `NNNN_snapshot.json` per meta directory.
351
+ The compiler's response is therefore a partial view by construction, and a file
352
+ missing from it carries no instruction. Compile removes a file only when the
353
+ compiler was actually shown it and left it out; anything never uploaded — every
354
+ historical snapshot — is preserved untouched.
355
+
356
+ When something is removed, the previous tree is archived to
357
+ `quickback/.archives/drizzle-<timestamp>/` (the three most recent are kept) and
358
+ the compile prints what it removed and what it preserved.
359
+
360
+ > If `quickback migrations doctor` reports snapshot drift — more journal entries
361
+ > than snapshot files — that drift came from your project's history, not from
362
+ > compiling. Compile does not delete snapshots it was never given.
363
+
364
+
301
365
  For non-interactive environments (cloud compile, CI), table/column renames must be declared with `compiler.migrations.renames` in `quickback.config.ts`. This avoids interactive rename prompts during migration generation.
302
366
 
303
367
  Migration files follow the Drizzle Kit naming convention: