@quickback-dev/cli 0.10.4 → 0.10.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +19 -3
- package/dist/commands/compile.js.map +1 -1
- package/dist/commands/create.js +108 -55
- package/dist/commands/create.js.map +1 -1
- package/dist/cursor/quickback.mdc +37 -33
- package/dist/docs/content.d.ts.map +1 -1
- package/dist/docs/content.js +248 -233
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/api-client.d.ts +25 -2
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/file-loader.d.ts +52 -5
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +280 -63
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-loader.test.js +212 -1
- package/dist/lib/file-loader.test.js.map +1 -1
- package/dist/skill/SKILL.md +159 -85
- package/dist/skill/agents/quickback-specialist/AGENT.md +60 -54
- package/package.json +1 -1
- package/src/cursor/quickback.mdc +37 -33
- package/src/skill/SKILL.md +159 -85
- package/src/skill/agents/quickback-specialist/AGENT.md +60 -54
|
@@ -16,7 +16,7 @@ You deeply understand:
|
|
|
16
16
|
- **Access**: Role-based and record-level permissions (deny by default)
|
|
17
17
|
- **Guards**: Field protection (createable, updatable, immutable, protected)
|
|
18
18
|
- **Masking**: PII redaction with role-based visibility and auto-detection
|
|
19
|
-
- **Actions**: Custom endpoints using `
|
|
19
|
+
- **Actions**: Custom endpoints using `defineAction()` (one file per action under `actions/`)
|
|
20
20
|
- **Views**: Column-level security with named projections
|
|
21
21
|
- **Validation**: Field-level validation rules
|
|
22
22
|
- **Layouts**: CMS record page field grouping with sections, columns, and collapsed state
|
|
@@ -33,7 +33,7 @@ You deeply understand:
|
|
|
33
33
|
3. **Generate complete configuration** including:
|
|
34
34
|
- Drizzle schema with correct dialect
|
|
35
35
|
- `defineTable()` with all security layers in a single file
|
|
36
|
-
- Actions via `
|
|
36
|
+
- Actions via `defineAction()` — one file per action under `actions/<name>.ts` (if needed)
|
|
37
37
|
4. **Validate the configuration** - Check for common mistakes
|
|
38
38
|
5. **Explain your decisions** - Help users understand the security model
|
|
39
39
|
|
|
@@ -43,8 +43,8 @@ Schema + security config in a single file using `defineTable()`.
|
|
|
43
43
|
|
|
44
44
|
Generate files in `quickback/features/{name}/`:
|
|
45
45
|
- `{table}.ts` - Drizzle schema + security config via `defineTable()` (DO NOT add audit fields - they're auto-injected)
|
|
46
|
-
- `actions.ts` -
|
|
47
|
-
- `
|
|
46
|
+
- `actions/{action}.ts` - One file per custom action via `defineAction()` (if needed)
|
|
47
|
+
- `lib/` - Shared Zod schemas / helpers, copied verbatim into the generated output (if needed)
|
|
48
48
|
|
|
49
49
|
When explaining compile outputs:
|
|
50
50
|
- Runtime outputs remain in `build.outputDir`.
|
|
@@ -89,35 +89,37 @@ For Drizzle interop (bringing forward existing schemas), use `sqliteTable` + `de
|
|
|
89
89
|
|
|
90
90
|
### Actions Pattern
|
|
91
91
|
|
|
92
|
-
Per-action permissions live under `access:` (same shape as resource-level access). Use `whereRecord(table)` for protected-field writes — it AND-merges firewall + soft-delete + the record id in one expression.
|
|
92
|
+
One file per action under `actions/<name>.ts`. The filename (sans `.ts`) is the action name AND URL segment. Per-action permissions live under `access:` (same shape as resource-level access). Use `whereRecord(table)` for protected-field writes — it AND-merges firewall + soft-delete + the record id in one expression.
|
|
93
|
+
|
|
94
|
+
`actions/<name>.ts` binds to the feature's primary table (the `<feature>.ts` file). For multi-table features, use `actions/<table>/<name>.ts` to bind to a sibling table. Setting `path:` makes the action standalone.
|
|
93
95
|
|
|
94
96
|
```typescript
|
|
95
|
-
// quickback/features/todos/actions.ts
|
|
96
|
-
import
|
|
97
|
-
import {
|
|
98
|
-
import
|
|
99
|
-
|
|
100
|
-
export default
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
return { success: true };
|
|
115
|
-
},
|
|
97
|
+
// quickback/features/todos/actions/complete.ts
|
|
98
|
+
import { z } from "zod";
|
|
99
|
+
import { defineAction } from "../.quickback/define-action";
|
|
100
|
+
import todos from "../todos"; // default import: feature() exports
|
|
101
|
+
|
|
102
|
+
export default defineAction({
|
|
103
|
+
description: "Mark todo as complete",
|
|
104
|
+
input: z.object({
|
|
105
|
+
completedAt: z.string().datetime().optional(),
|
|
106
|
+
}),
|
|
107
|
+
access: {
|
|
108
|
+
roles: ["member", "admin"],
|
|
109
|
+
record: { completed: { equals: false } },
|
|
110
|
+
},
|
|
111
|
+
async execute({ db, record, whereRecord, auditFields }) {
|
|
112
|
+
await db.update(todos)
|
|
113
|
+
.set({ completed: true, modifiedAt: auditFields!.modifiedAt })
|
|
114
|
+
.where(whereRecord!(todos));
|
|
115
|
+
return { success: true };
|
|
116
116
|
},
|
|
117
117
|
});
|
|
118
118
|
```
|
|
119
119
|
|
|
120
|
-
For state-machine fields (status, lifecycle), add `transition: { field, via|to, fromTo }` so the runtime enforces the from→to pair and returns 409 `ACCESS_ACTION_NOT_ALLOWED_FOR_STATE` on illegal transitions. For cross-tenant or platform-level work, use `unsafe: { reason, adminOnly, crossTenant, targetScope }` (object form
|
|
120
|
+
For state-machine fields (status, lifecycle), add `transition: { field, via|to, fromTo }` so the runtime enforces the from→to pair and returns 409 `ACCESS_ACTION_NOT_ALLOWED_FOR_STATE` on illegal transitions. For cross-tenant or platform-level work, use `unsafe: { reason, adminOnly, crossTenant, targetScope }` (object form, auto-injects audit logging).
|
|
121
|
+
|
|
122
|
+
**Retired** (rejected at load time): bundled `actions.ts`, `_feature.ts`, `handlers/` directory, `defineActions()`, `*-actions.ts` filenames.
|
|
121
123
|
|
|
122
124
|
## Security Principles
|
|
123
125
|
|
|
@@ -152,7 +154,7 @@ firewall: [
|
|
|
152
154
|
guards: {
|
|
153
155
|
protected: { status: ['approve', 'reject'] }
|
|
154
156
|
}
|
|
155
|
-
// Plus
|
|
157
|
+
// Plus actions/approve.ts and actions/reject.ts via defineAction()
|
|
156
158
|
```
|
|
157
159
|
|
|
158
160
|
### PII masking
|
|
@@ -180,50 +182,54 @@ views: {
|
|
|
180
182
|
> Use `+` suffix with `auth.roleHierarchy` configured (e.g., `['member', 'admin', 'owner']`) to expand roles at compile time. `"member+"` → `["member", "admin", "owner"]`.
|
|
181
183
|
|
|
182
184
|
### Standalone actions (not record-based)
|
|
185
|
+
Setting `path:` makes an action standalone — no record loading or firewall preload.
|
|
183
186
|
```typescript
|
|
184
|
-
//
|
|
185
|
-
|
|
186
|
-
|
|
187
|
+
// features/sessions/actions/chat.ts
|
|
188
|
+
import { z } from "zod";
|
|
189
|
+
import { defineAction } from "../.quickback/define-action";
|
|
190
|
+
|
|
191
|
+
export default defineAction({
|
|
192
|
+
description: "AI chat",
|
|
187
193
|
path: "/chat",
|
|
188
194
|
method: "POST",
|
|
189
195
|
responseType: "stream",
|
|
190
196
|
input: z.object({ message: z.string() }),
|
|
191
197
|
access: { roles: ["member"] },
|
|
192
|
-
|
|
193
|
-
}
|
|
198
|
+
async execute({ input, c }) { /* … */ },
|
|
199
|
+
});
|
|
194
200
|
```
|
|
195
201
|
|
|
196
202
|
### Actions-only features (no tables)
|
|
203
|
+
A feature directory with no top-level `*.ts` files is "tableless" — every action under `actions/` must be standalone.
|
|
197
204
|
```typescript
|
|
198
|
-
// quickback/features/utilities/actions.ts
|
|
199
|
-
import {
|
|
200
|
-
import {
|
|
201
|
-
|
|
202
|
-
export default
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
access: { roles: ["member", "admin"] },
|
|
210
|
-
handler: "./handlers/health-check",
|
|
211
|
-
},
|
|
205
|
+
// quickback/features/utilities/actions/health-check.ts
|
|
206
|
+
import { z } from "zod";
|
|
207
|
+
import { defineAction } from "../.quickback/define-action";
|
|
208
|
+
|
|
209
|
+
export default defineAction({
|
|
210
|
+
description: "Health check endpoint",
|
|
211
|
+
path: "/health",
|
|
212
|
+
method: "GET",
|
|
213
|
+
input: z.object({}),
|
|
214
|
+
access: { roles: ["member", "admin"] },
|
|
215
|
+
async execute() { return { ok: true }; },
|
|
212
216
|
});
|
|
213
217
|
```
|
|
214
|
-
All actions must have `standalone: true` when there is no table.
|
|
215
218
|
|
|
216
219
|
### Public actions (no auth required)
|
|
217
220
|
Use `roles: ["PUBLIC"]` for unauthenticated endpoints. Every invocation is mandatory audit logged.
|
|
218
221
|
```typescript
|
|
219
|
-
submit
|
|
220
|
-
|
|
221
|
-
|
|
222
|
+
// features/contact/actions/submit.ts
|
|
223
|
+
import { z } from "zod";
|
|
224
|
+
import { defineAction } from "../.quickback/define-action";
|
|
225
|
+
|
|
226
|
+
export default defineAction({
|
|
222
227
|
description: "Public contact form",
|
|
228
|
+
path: "/submit",
|
|
223
229
|
input: z.object({ name: z.string(), email: z.string().email(), message: z.string() }),
|
|
224
230
|
access: { roles: ["PUBLIC"] },
|
|
225
|
-
|
|
226
|
-
}
|
|
231
|
+
async execute({ db, input }) { /* persist submission */ return { ok: true }; },
|
|
232
|
+
});
|
|
227
233
|
```
|
|
228
234
|
The wildcard `"*"` is NOT supported and will throw a compile error. Use `"PUBLIC"` explicitly.
|
|
229
235
|
|
|
@@ -280,7 +286,7 @@ Before finishing, verify:
|
|
|
280
286
|
- [ ] Layouts for CMS record page field grouping (if needed)
|
|
281
287
|
- [ ] No audit fields in schema (auto-injected)
|
|
282
288
|
- [ ] Using `defineTable()` (not separate schema.ts + resource.ts)
|
|
283
|
-
- [ ] Actions use `
|
|
289
|
+
- [ ] Actions use `defineAction()` (one file per action under `actions/`) with Zod schemas (not JSON schema)
|
|
284
290
|
- [ ] Account UI configured if auth UI needed (`account: true` or `account: { ... }`)
|
|
285
291
|
|
|
286
292
|
## Accessing Documentation
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quickback-dev/cli",
|
|
3
|
-
"version": "0.10.
|
|
3
|
+
"version": "0.10.8",
|
|
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",
|
package/src/cursor/quickback.mdc
CHANGED
|
@@ -21,8 +21,10 @@ my-app/
|
|
|
21
21
|
│ └── features/
|
|
22
22
|
│ └── {feature-name}/
|
|
23
23
|
│ ├── {table}.ts # Schema + security (defineTable)
|
|
24
|
-
│ ├── actions
|
|
25
|
-
│
|
|
24
|
+
│ ├── actions/ # One file per action — defineAction({...}) (optional)
|
|
25
|
+
│ │ ├── {action}.ts # Binds to primary table (or standalone if path: is set)
|
|
26
|
+
│ │ └── {table}/{action}.ts # Binds to sibling <table>.ts (multi-table features)
|
|
27
|
+
│ └── lib/ # Feature-local helpers, copied verbatim (optional)
|
|
26
28
|
└── ...
|
|
27
29
|
```
|
|
28
30
|
|
|
@@ -175,50 +177,52 @@ validation: {
|
|
|
175
177
|
|
|
176
178
|
## Actions — Custom Business Logic
|
|
177
179
|
|
|
178
|
-
|
|
180
|
+
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.
|
|
179
181
|
|
|
180
182
|
```typescript
|
|
181
|
-
|
|
182
|
-
import {
|
|
183
|
-
import {
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
183
|
+
// features/todos/actions/complete.ts
|
|
184
|
+
import { z } from "zod";
|
|
185
|
+
import { eq } from "drizzle-orm";
|
|
186
|
+
import { defineAction } from "../.quickback/define-action";
|
|
187
|
+
import { todos } from "../todos";
|
|
188
|
+
|
|
189
|
+
export default defineAction({
|
|
190
|
+
description: "Mark todo as complete",
|
|
191
|
+
input: z.object({ completedAt: z.string().datetime().optional() }),
|
|
192
|
+
access: { roles: ["member", "admin"], record: { completed: { equals: false } } },
|
|
193
|
+
async execute({ db, record, auditFields }) {
|
|
194
|
+
await db.update(todos)
|
|
195
|
+
.set({ completed: true, modifiedAt: auditFields!.modifiedAt })
|
|
196
|
+
.where(eq(todos.id, record.id));
|
|
197
|
+
return { success: true };
|
|
194
198
|
},
|
|
195
199
|
});
|
|
196
200
|
```
|
|
197
201
|
|
|
198
|
-
Record-based: `POST /api/v1/{resource}/:id/{action}`
|
|
199
|
-
Standalone
|
|
202
|
+
Record-based (no `path:`): `POST /api/v1/{resource}/:id/{action}`
|
|
203
|
+
Standalone (`path:` set): custom `path` and `method`
|
|
204
|
+
|
|
205
|
+
`execute:` must be an `async (ctx) => { … }` arrow function. Retired (rejected at load time): bundled `actions.ts`, `_feature.ts`, `handlers/` directory, `defineActions()`.
|
|
200
206
|
|
|
201
207
|
### Actions-Only Features (no tables)
|
|
202
208
|
|
|
209
|
+
A feature with no top-level `*.ts` files is "tableless" — every action must be standalone (have `path:`).
|
|
210
|
+
|
|
203
211
|
```typescript
|
|
204
|
-
// quickback/features/utilities/actions.ts
|
|
205
|
-
import {
|
|
206
|
-
import {
|
|
207
|
-
|
|
208
|
-
export default
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
handler: "./handlers/health-check",
|
|
216
|
-
},
|
|
212
|
+
// quickback/features/utilities/actions/health-check.ts
|
|
213
|
+
import { z } from "zod";
|
|
214
|
+
import { defineAction } from "../.quickback/define-action";
|
|
215
|
+
|
|
216
|
+
export default defineAction({
|
|
217
|
+
description: "Health check",
|
|
218
|
+
path: "/health",
|
|
219
|
+
method: "GET",
|
|
220
|
+
input: z.object({}),
|
|
221
|
+
access: { roles: ["member", "admin"] },
|
|
222
|
+
async execute() { return { ok: true }; },
|
|
217
223
|
});
|
|
218
224
|
```
|
|
219
225
|
|
|
220
|
-
All actions must have `standalone: true` when there is no table.
|
|
221
|
-
|
|
222
226
|
### Public Actions
|
|
223
227
|
|
|
224
228
|
Use `roles: ["PUBLIC"]` for unauthenticated endpoints. Mandatory audit logged. The wildcard `"*"` is not supported.
|