@quickback-dev/cli 0.66.22 → 0.66.23
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/check.js +1 -1
- package/dist/commands/check.js.map +1 -1
- package/dist/commands/create.js +82 -165
- package/dist/commands/create.js.map +1 -1
- package/dist/commands/mcp.d.ts.map +1 -1
- package/dist/commands/mcp.js +92 -1
- package/dist/commands/mcp.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/api-client.d.ts +3 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/file-writer.d.ts +2 -0
- package/dist/lib/file-writer.d.ts.map +1 -1
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/lib/harness.d.ts +59 -0
- package/dist/lib/harness.d.ts.map +1 -0
- package/dist/lib/harness.js +178 -0
- package/dist/lib/harness.js.map +1 -0
- package/dist/skill/docs/start/template-blog.md +36 -58
- package/dist/skill/docs/start/templates.md +3 -3
- package/dist/skill/docs/tooling/claude-skill.md +10 -1
- package/dist/skill/docs/tooling/cli.md +5 -1
- package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +10 -0
- package/dist/templates/registry.js +1 -1
- package/dist/templates/registry.js.map +1 -1
- package/package.json +1 -1
- package/src/skill/docs/start/template-blog.md +36 -58
- package/src/skill/docs/start/templates.md +3 -3
- package/src/skill/docs/tooling/claude-skill.md +10 -1
- package/src/skill/docs/tooling/cli.md +5 -1
- package/src/skill/docs/tooling/cloud-compiler/endpoints.md +10 -0
|
@@ -23,9 +23,9 @@ Cloudflare Workers + D1 + Better Auth with the organization plugin and a `member
|
|
|
23
23
|
| Template | Includes | Command |
|
|
24
24
|
|----------|----------|---------|
|
|
25
25
|
| `cloudflare` | Bare scaffold — auth + DB + Hono, no example feature | `quickback create cloudflare my-app` |
|
|
26
|
-
| `todos` | Working todos feature: schema, masking, two
|
|
26
|
+
| `todos` | Working todos feature: schema, masking, two transitions (`complete` / `uncomplete`), and a `dashboard` named view | `quickback create todos my-app` |
|
|
27
27
|
|
|
28
|
-
The **todos** template is the recommended first read — it exercises every security pillar (firewall, access, guards, masking) plus
|
|
28
|
+
The **todos** template is the recommended first read — it exercises every security pillar (firewall, access, guards, masking) plus transitions and views in ~80 lines you can scan in five minutes.
|
|
29
29
|
|
|
30
30
|
### Fixed-org starter
|
|
31
31
|
|
|
@@ -70,7 +70,7 @@ Best when you already know the conventions and want empty walls. Multi-tenant or
|
|
|
70
70
|
|
|
71
71
|
### Todos (recommended for newcomers)
|
|
72
72
|
|
|
73
|
-
Best for learning by reading. Full multi-tenant security pillars, two
|
|
73
|
+
Best for learning by reading. Full multi-tenant security pillars, two transitions (`complete` / `uncomplete`), a named view (`/api/v1/todos/views/dashboard`), and field masking on the `description` column — all in a single ~80-line file you can copy-edit into your own table.
|
|
74
74
|
|
|
75
75
|
### Blog (pinned-organization CMS)
|
|
76
76
|
|
|
@@ -45,8 +45,15 @@ Add to your AI tool's MCP config:
|
|
|
45
45
|
|
|
46
46
|
### Available Tools
|
|
47
47
|
|
|
48
|
+
The server is a harness, not just a docs index: the agent scaffolds, edits, validates, and builds your project through it, and every compiler error comes back as the tool result. That closed loop is what makes an AI tool converge on a working Quickback backend — the same loop that powers [start.quickback.dev](https://start.quickback.dev), pointed at the project on your disk.
|
|
49
|
+
|
|
48
50
|
| Tool | Description |
|
|
49
51
|
|------|-------------|
|
|
52
|
+
| `status` | Onboarding diagnostic: is this a project, are you logged in, is the compiler reachable, what to do next |
|
|
53
|
+
| `create` | Scaffold a new project from a template (`todos`, `saas`, `blog`, `empty`, `cloudflare`) |
|
|
54
|
+
| `validate` | Validation compile of `quickback/` — seconds, no migrations. Returns `DEFINITIONS VALID` plus warnings or the exact errors to fix, and on success writes the authoring surface the compiler tags: the authored-tree types (`quickback/tsconfig.json`, `.quickback/` helpers and the `src/` modules they type against), `api-types.gen.ts` / `quickback.gen.ts`, and the OpenAPI, AsyncAPI, and schema-registry specs. After three consecutive failures the result tells the agent to stop patching and replan |
|
|
55
|
+
| `check` | Typecheck the authored tree against the generated helpers (`quickback check`) — tables, config, and action files all check right after `validate`, no build needed |
|
|
56
|
+
| `build` | Full compile: the deployable runtime in `src/`, migrations, `wrangler.toml` (`quickback build`) |
|
|
50
57
|
| `list_topics` | List all 100+ documentation topics |
|
|
51
58
|
| `get_doc` | Get a specific doc (supports fuzzy matching — e.g., "firewall") |
|
|
52
59
|
| `search_docs` | Search documentation by keyword |
|
|
@@ -57,6 +64,8 @@ Add to your AI tool's MCP config:
|
|
|
57
64
|
|
|
58
65
|
All documentation topics are also registered as MCP resources at `quickback://docs/{topic}`.
|
|
59
66
|
|
|
67
|
+
`validate` and `build` use your CLI login (`quickback login`, one-time device auth) or `QUICKBACK_API_KEY`. The server reads the directory it was started in, so start it from your project root — or, for a brand-new project, call `create` and then restart it from the new folder.
|
|
68
|
+
|
|
60
69
|
## Claude Code Skill
|
|
61
70
|
|
|
62
71
|
### Installation
|
|
@@ -263,7 +272,7 @@ Make sure the skill file exists and Claude Code is restarted. You can also invok
|
|
|
263
272
|
|
|
264
273
|
### Generated code has errors
|
|
265
274
|
|
|
266
|
-
|
|
275
|
+
Ask the agent to call the `validate` tool (or run `quickback build` yourself and paste the errors). The compiler's messages name the file and the fix.
|
|
267
276
|
|
|
268
277
|
## Cursor IDE Rules
|
|
269
278
|
|
|
@@ -165,7 +165,11 @@ Exit codes: `0` clean · `1` type errors · `2` setup missing. A fresh clone
|
|
|
165
165
|
(or a project that has never compiled) exits `2` with a pointer at
|
|
166
166
|
`quickback build`, which generates the tsconfig, helpers, and compiler types
|
|
167
167
|
the check resolves against. Re-run `quickback build` after schema changes so
|
|
168
|
-
they track your tables
|
|
168
|
+
they track your tables — or, in an AI tool, let the [MCP `validate` tool](/tooling/claude-skill#available-tools)
|
|
169
|
+
refresh them: it writes the same typing files, client types, and specs from a
|
|
170
|
+
validation compile without producing the runtime — including the handful of
|
|
171
|
+
`src/` modules the `define-action` helper types `db`, `ctx`, and the table
|
|
172
|
+
against, so action files check too.
|
|
169
173
|
|
|
170
174
|
Within a feature, the single helper import
|
|
171
175
|
(`import { defineAction, tickets } from "../.quickback/define-action"`) is
|
|
@@ -45,6 +45,16 @@ Raw-files requests work with both `?complete=true` and `?complete=false`
|
|
|
45
45
|
(validation-only) compiles. The v2 action-schema completeness gate applies to
|
|
46
46
|
both modes; `complete=false` is not an escape hatch for a partial harvest.
|
|
47
47
|
|
|
48
|
+
Every generated file carries `path`, `content`, and `type`. Files that make up
|
|
49
|
+
the **authoring surface** additionally carry `authoring: true`: the `quickback/`
|
|
50
|
+
typing files (`tsconfig.json`, the `@quickback/compiler` declaration twin, the
|
|
51
|
+
per-feature `.quickback/define-action` helpers), the root client types
|
|
52
|
+
(`api-types.gen.ts`, `quickback.gen.ts`), the specs under
|
|
53
|
+
`src/apps/__quickback/spec/`, and the transitive import closure each helper
|
|
54
|
+
needs from `src/`. A thin client that wants types and specs during development
|
|
55
|
+
without producing a runtime writes exactly the tagged files from a
|
|
56
|
+
`complete=false` compile — that is what the CLI's [MCP `validate` tool](/tooling/claude-skill#available-tools) does.
|
|
57
|
+
|
|
48
58
|
## Edge validation backend
|
|
49
59
|
|
|
50
60
|
Validation compiles (`POST /compile?complete=false`) may be served by an edge Worker instead of the compiler container. This is **transparent to clients**: same endpoint, same auth, same request and response shapes (plain or gzipped JSON, raw-files or parsed input, identical payload limits, error shapes, and generated-file envelopes) — just no container cold start.
|
|
@@ -14,7 +14,7 @@ export const TEMPLATE_REGISTRY = {
|
|
|
14
14
|
},
|
|
15
15
|
"todos-cloudflare": {
|
|
16
16
|
name: "Todos Example (Cloudflare)",
|
|
17
|
-
description: "Working todos example — schema with masking, two
|
|
17
|
+
description: "Working todos example — schema with masking, two transitions (complete / uncomplete), a named view, Better Auth, D1. Read the source as a learning template.",
|
|
18
18
|
tags: ["example", "todos", "actions", "cloudflare", "d1"],
|
|
19
19
|
includes: ["betterauth", "d1", "hono", "drizzle"],
|
|
20
20
|
preset: "cloudflare",
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/templates/registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH,MAAM,CAAC,MAAM,iBAAiB,GAAuC;IACjE,0BAA0B,EAAE;QACxB,IAAI,EAAE,+BAA+B;QACrC,WAAW,EAAE,qHAAqH;QAClI,IAAI,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,CAAC;QAC1C,QAAQ,EAAE,CAAC,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC;QACjD,MAAM,EAAE,YAAY;QACpB,kBAAkB,EAAE,IAAI;KAC3B;IACD,kBAAkB,EAAE;QAChB,IAAI,EAAE,4BAA4B;QAClC,WAAW,EAAE,
|
|
1
|
+
{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/templates/registry.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.66.
|
|
3
|
+
"version": "0.66.23",
|
|
4
4
|
"description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
|
|
5
5
|
"author": "Kardoe Incorporated <paul@kardoe.com>",
|
|
6
6
|
"license": "MIT",
|
|
@@ -19,10 +19,7 @@ my-site/
|
|
|
19
19
|
│ ├── quickback.config.ts # Pinned-organization config
|
|
20
20
|
│ └── features/
|
|
21
21
|
│ └── posts/
|
|
22
|
-
│
|
|
23
|
-
│ └── actions/
|
|
24
|
-
│ ├── publish.ts # Publish action
|
|
25
|
-
│ └── unpublish.ts # Unpublish action
|
|
22
|
+
│ └── posts.ts # Schema, security, and publish/unpublish transitions
|
|
26
23
|
├── src/ # Compiled output (generated)
|
|
27
24
|
├── package.json
|
|
28
25
|
├── tsconfig.json
|
|
@@ -59,17 +56,16 @@ Replace `org_replace_me` with a real Better Auth organization id before deployin
|
|
|
59
56
|
The template includes a `posts` feature with public read access and admin-only write access:
|
|
60
57
|
|
|
61
58
|
```typescript
|
|
62
|
-
import {
|
|
63
|
-
import { defineTable } from "@quickback/compiler";
|
|
59
|
+
import { q, defineTable } from "@quickback/compiler";
|
|
64
60
|
|
|
65
|
-
export const posts =
|
|
66
|
-
id:
|
|
67
|
-
title: text(
|
|
68
|
-
slug: text(
|
|
69
|
-
content: text(
|
|
70
|
-
excerpt: text(
|
|
71
|
-
status: text(
|
|
72
|
-
publishedAt:
|
|
61
|
+
export const posts = q.table("posts", {
|
|
62
|
+
id: q.id(),
|
|
63
|
+
title: q.text().required(),
|
|
64
|
+
slug: q.text().required().unique(),
|
|
65
|
+
content: q.text().optional(),
|
|
66
|
+
excerpt: q.text().optional(),
|
|
67
|
+
status: q.text().default("draft").required(),
|
|
68
|
+
publishedAt: q.timestamp().optional(),
|
|
73
69
|
|
|
74
70
|
// Author tracking only — this is metadata, not access control.
|
|
75
71
|
// Named "authorId" (not "userId") because a `userId` column on a feature
|
|
@@ -77,16 +73,13 @@ export const posts = sqliteTable("posts", {
|
|
|
77
73
|
// column (that name is `ownerId`), and it errors when it is the only
|
|
78
74
|
// candidate column on the table. Reads here are gated by PUBLIC; writes by
|
|
79
75
|
// the admin access check below.
|
|
80
|
-
authorId: text(
|
|
76
|
+
authorId: q.text().required(),
|
|
81
77
|
|
|
82
|
-
// Compiler-managed columns —
|
|
83
|
-
//
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
modifiedBy: text("modified_by"),
|
|
88
|
-
deletedAt: text("deleted_at"),
|
|
89
|
-
deletedBy: text("deleted_by"),
|
|
78
|
+
// Compiler-managed columns — declared, not magic. `...q.audit()` is the
|
|
79
|
+
// audit quartet on every table; `...q.softDelete()` adds the soft-delete
|
|
80
|
+
// pair because `delete.mode` is "soft".
|
|
81
|
+
...q.audit(),
|
|
82
|
+
...q.softDelete(),
|
|
90
83
|
});
|
|
91
84
|
|
|
92
85
|
export default defineTable(posts, {
|
|
@@ -97,9 +90,21 @@ export default defineTable(posts, {
|
|
|
97
90
|
softDelete: {},
|
|
98
91
|
},
|
|
99
92
|
guards: {
|
|
100
|
-
createable: ["title", "slug", "content", "excerpt"
|
|
101
|
-
updatable: ["title", "slug", "content", "excerpt"
|
|
93
|
+
createable: ["title", "slug", "content", "excerpt"],
|
|
94
|
+
updatable: ["title", "slug", "content", "excerpt"],
|
|
102
95
|
immutable: ["id", "authorId"],
|
|
96
|
+
// `status` is workflow-owned: only the transitions below write it.
|
|
97
|
+
protected: { status: ["publish", "unpublish"] },
|
|
98
|
+
},
|
|
99
|
+
// Transitions generate POST /api/v1/posts/:id/publish and its inverse,
|
|
100
|
+
// stamping publishedAt on publish and clearing it on unpublish.
|
|
101
|
+
transitions: {
|
|
102
|
+
publish: {
|
|
103
|
+
field: "status", from: "draft", to: "published",
|
|
104
|
+
stamp: { at: "publishedAt" },
|
|
105
|
+
undo: "unpublish",
|
|
106
|
+
access: { roles: ["admin"] },
|
|
107
|
+
},
|
|
103
108
|
},
|
|
104
109
|
read: {
|
|
105
110
|
access: { roles: ["PUBLIC"] },
|
|
@@ -117,42 +122,15 @@ export default defineTable(posts, {
|
|
|
117
122
|
- **`authorId`** is plain metadata recording who wrote the post — it is deliberately *not* a firewall scope, because an owner predicate would hide every post from anonymous readers
|
|
118
123
|
- **`softDelete`** marks posts as deleted rather than removing them from the database
|
|
119
124
|
|
|
120
|
-
### Post
|
|
125
|
+
### Post Transitions (publish / unpublish)
|
|
121
126
|
|
|
122
|
-
The template
|
|
127
|
+
The template declares the post lifecycle as [transitions](/define/transitions) on the table instead of hand-written action files. The compiler generates both actions — `POST /api/v1/posts/:id/publish` and `POST /api/v1/posts/:id/unpublish` — with the from/to guard, idempotency, and CMS buttons built in:
|
|
123
128
|
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
import { eq } from "drizzle-orm";
|
|
128
|
-
// The generated per-feature helper re-exports the bound table, so one import
|
|
129
|
-
// gets you both — and `posts` here is the GENERATED table, with the audit
|
|
130
|
-
// columns visible on `record` without `as any`.
|
|
131
|
-
import { defineAction, posts } from "../.quickback/define-action";
|
|
132
|
-
|
|
133
|
-
export default defineAction({
|
|
134
|
-
description: "Publish a draft post",
|
|
135
|
-
input: z.object({}),
|
|
136
|
-
access: {
|
|
137
|
-
roles: ["admin"],
|
|
138
|
-
record: { status: { equals: "draft" } },
|
|
139
|
-
},
|
|
140
|
-
sideEffects: "sync",
|
|
141
|
-
async execute({ db, record }) {
|
|
142
|
-
const [updated] = await db
|
|
143
|
-
.update(posts)
|
|
144
|
-
.set({
|
|
145
|
-
status: "published",
|
|
146
|
-
publishedAt: new Date().toISOString(),
|
|
147
|
-
})
|
|
148
|
-
.where(eq(posts.id, record.id))
|
|
149
|
-
.returning();
|
|
150
|
-
return updated;
|
|
151
|
-
},
|
|
152
|
-
});
|
|
153
|
-
```
|
|
129
|
+
- **`publish`** requires `status: "draft"`, sets `status: "published"`, and stamps `publishedAt`.
|
|
130
|
+
- **`unpublish`** is the generated `undo` pair: it requires `status: "published"`, reverts to `draft`, and clears `publishedAt`.
|
|
131
|
+
- Both are admin-only via `access: { roles: ["admin"] }`; `guards.protected` means nothing else can write `status`, not even a plain `PATCH`.
|
|
154
132
|
|
|
155
|
-
|
|
133
|
+
Need custom logic in the handler? Write `actions/publish.ts` yourself — an explicit action file always wins over the generated one — and keep the same `transition:` block so the guard stays compiler-owned. See [Actions](/define/actions).
|
|
156
134
|
|
|
157
135
|
## Setup Steps
|
|
158
136
|
|
|
@@ -23,9 +23,9 @@ Cloudflare Workers + D1 + Better Auth with the organization plugin and a `member
|
|
|
23
23
|
| Template | Includes | Command |
|
|
24
24
|
|----------|----------|---------|
|
|
25
25
|
| `cloudflare` | Bare scaffold — auth + DB + Hono, no example feature | `quickback create cloudflare my-app` |
|
|
26
|
-
| `todos` | Working todos feature: schema, masking, two
|
|
26
|
+
| `todos` | Working todos feature: schema, masking, two transitions (`complete` / `uncomplete`), and a `dashboard` named view | `quickback create todos my-app` |
|
|
27
27
|
|
|
28
|
-
The **todos** template is the recommended first read — it exercises every security pillar (firewall, access, guards, masking) plus
|
|
28
|
+
The **todos** template is the recommended first read — it exercises every security pillar (firewall, access, guards, masking) plus transitions and views in ~80 lines you can scan in five minutes.
|
|
29
29
|
|
|
30
30
|
### Fixed-org starter
|
|
31
31
|
|
|
@@ -70,7 +70,7 @@ Best when you already know the conventions and want empty walls. Multi-tenant or
|
|
|
70
70
|
|
|
71
71
|
### Todos (recommended for newcomers)
|
|
72
72
|
|
|
73
|
-
Best for learning by reading. Full multi-tenant security pillars, two
|
|
73
|
+
Best for learning by reading. Full multi-tenant security pillars, two transitions (`complete` / `uncomplete`), a named view (`/api/v1/todos/views/dashboard`), and field masking on the `description` column — all in a single ~80-line file you can copy-edit into your own table.
|
|
74
74
|
|
|
75
75
|
### Blog (pinned-organization CMS)
|
|
76
76
|
|
|
@@ -45,8 +45,15 @@ Add to your AI tool's MCP config:
|
|
|
45
45
|
|
|
46
46
|
### Available Tools
|
|
47
47
|
|
|
48
|
+
The server is a harness, not just a docs index: the agent scaffolds, edits, validates, and builds your project through it, and every compiler error comes back as the tool result. That closed loop is what makes an AI tool converge on a working Quickback backend — the same loop that powers [start.quickback.dev](https://start.quickback.dev), pointed at the project on your disk.
|
|
49
|
+
|
|
48
50
|
| Tool | Description |
|
|
49
51
|
|------|-------------|
|
|
52
|
+
| `status` | Onboarding diagnostic: is this a project, are you logged in, is the compiler reachable, what to do next |
|
|
53
|
+
| `create` | Scaffold a new project from a template (`todos`, `saas`, `blog`, `empty`, `cloudflare`) |
|
|
54
|
+
| `validate` | Validation compile of `quickback/` — seconds, no migrations. Returns `DEFINITIONS VALID` plus warnings or the exact errors to fix, and on success writes the authoring surface the compiler tags: the authored-tree types (`quickback/tsconfig.json`, `.quickback/` helpers and the `src/` modules they type against), `api-types.gen.ts` / `quickback.gen.ts`, and the OpenAPI, AsyncAPI, and schema-registry specs. After three consecutive failures the result tells the agent to stop patching and replan |
|
|
55
|
+
| `check` | Typecheck the authored tree against the generated helpers (`quickback check`) — tables, config, and action files all check right after `validate`, no build needed |
|
|
56
|
+
| `build` | Full compile: the deployable runtime in `src/`, migrations, `wrangler.toml` (`quickback build`) |
|
|
50
57
|
| `list_topics` | List all 100+ documentation topics |
|
|
51
58
|
| `get_doc` | Get a specific doc (supports fuzzy matching — e.g., "firewall") |
|
|
52
59
|
| `search_docs` | Search documentation by keyword |
|
|
@@ -57,6 +64,8 @@ Add to your AI tool's MCP config:
|
|
|
57
64
|
|
|
58
65
|
All documentation topics are also registered as MCP resources at `quickback://docs/{topic}`.
|
|
59
66
|
|
|
67
|
+
`validate` and `build` use your CLI login (`quickback login`, one-time device auth) or `QUICKBACK_API_KEY`. The server reads the directory it was started in, so start it from your project root — or, for a brand-new project, call `create` and then restart it from the new folder.
|
|
68
|
+
|
|
60
69
|
## Claude Code Skill
|
|
61
70
|
|
|
62
71
|
### Installation
|
|
@@ -263,7 +272,7 @@ Make sure the skill file exists and Claude Code is restarted. You can also invok
|
|
|
263
272
|
|
|
264
273
|
### Generated code has errors
|
|
265
274
|
|
|
266
|
-
|
|
275
|
+
Ask the agent to call the `validate` tool (or run `quickback build` yourself and paste the errors). The compiler's messages name the file and the fix.
|
|
267
276
|
|
|
268
277
|
## Cursor IDE Rules
|
|
269
278
|
|
|
@@ -165,7 +165,11 @@ Exit codes: `0` clean · `1` type errors · `2` setup missing. A fresh clone
|
|
|
165
165
|
(or a project that has never compiled) exits `2` with a pointer at
|
|
166
166
|
`quickback build`, which generates the tsconfig, helpers, and compiler types
|
|
167
167
|
the check resolves against. Re-run `quickback build` after schema changes so
|
|
168
|
-
they track your tables
|
|
168
|
+
they track your tables — or, in an AI tool, let the [MCP `validate` tool](/tooling/claude-skill#available-tools)
|
|
169
|
+
refresh them: it writes the same typing files, client types, and specs from a
|
|
170
|
+
validation compile without producing the runtime — including the handful of
|
|
171
|
+
`src/` modules the `define-action` helper types `db`, `ctx`, and the table
|
|
172
|
+
against, so action files check too.
|
|
169
173
|
|
|
170
174
|
Within a feature, the single helper import
|
|
171
175
|
(`import { defineAction, tickets } from "../.quickback/define-action"`) is
|
|
@@ -45,6 +45,16 @@ Raw-files requests work with both `?complete=true` and `?complete=false`
|
|
|
45
45
|
(validation-only) compiles. The v2 action-schema completeness gate applies to
|
|
46
46
|
both modes; `complete=false` is not an escape hatch for a partial harvest.
|
|
47
47
|
|
|
48
|
+
Every generated file carries `path`, `content`, and `type`. Files that make up
|
|
49
|
+
the **authoring surface** additionally carry `authoring: true`: the `quickback/`
|
|
50
|
+
typing files (`tsconfig.json`, the `@quickback/compiler` declaration twin, the
|
|
51
|
+
per-feature `.quickback/define-action` helpers), the root client types
|
|
52
|
+
(`api-types.gen.ts`, `quickback.gen.ts`), the specs under
|
|
53
|
+
`src/apps/__quickback/spec/`, and the transitive import closure each helper
|
|
54
|
+
needs from `src/`. A thin client that wants types and specs during development
|
|
55
|
+
without producing a runtime writes exactly the tagged files from a
|
|
56
|
+
`complete=false` compile — that is what the CLI's [MCP `validate` tool](/tooling/claude-skill#available-tools) does.
|
|
57
|
+
|
|
48
58
|
## Edge validation backend
|
|
49
59
|
|
|
50
60
|
Validation compiles (`POST /compile?complete=false`) may be served by an edge Worker instead of the compiler container. This is **transparent to clients**: same endpoint, same auth, same request and response shapes (plain or gzipped JSON, raw-files or parsed input, identical payload limits, error shapes, and generated-file envelopes) — just no container cold start.
|