@quickback-dev/cli 0.10.2 → 0.10.5

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 (56) hide show
  1. package/dist/commands/compile.d.ts +9 -1
  2. package/dist/commands/compile.d.ts.map +1 -1
  3. package/dist/commands/compile.js +56 -16
  4. package/dist/commands/compile.js.map +1 -1
  5. package/dist/commands/create.js +108 -55
  6. package/dist/commands/create.js.map +1 -1
  7. package/dist/commands/init.d.ts.map +1 -1
  8. package/dist/commands/init.js +22 -0
  9. package/dist/commands/init.js.map +1 -1
  10. package/dist/cursor/quickback.mdc +61 -46
  11. package/dist/docs/content.js +18 -18
  12. package/dist/docs/content.js.map +1 -1
  13. package/dist/index.js +3 -2
  14. package/dist/index.js.map +1 -1
  15. package/dist/lib/api-client.d.ts +34 -2
  16. package/dist/lib/api-client.d.ts.map +1 -1
  17. package/dist/lib/api-client.js +31 -2
  18. package/dist/lib/api-client.js.map +1 -1
  19. package/dist/lib/api-client.test.js +58 -0
  20. package/dist/lib/api-client.test.js.map +1 -1
  21. package/dist/lib/config-sync.d.ts +55 -0
  22. package/dist/lib/config-sync.d.ts.map +1 -0
  23. package/dist/lib/config-sync.js +207 -0
  24. package/dist/lib/config-sync.js.map +1 -0
  25. package/dist/lib/config-sync.test.d.ts +2 -0
  26. package/dist/lib/config-sync.test.d.ts.map +1 -0
  27. package/dist/lib/config-sync.test.js +151 -0
  28. package/dist/lib/config-sync.test.js.map +1 -0
  29. package/dist/lib/file-loader.d.ts +39 -5
  30. package/dist/lib/file-loader.d.ts.map +1 -1
  31. package/dist/lib/file-loader.js +226 -63
  32. package/dist/lib/file-loader.js.map +1 -1
  33. package/dist/lib/file-loader.test.js +212 -1
  34. package/dist/lib/file-loader.test.js.map +1 -1
  35. package/dist/lib/prepare-output.d.ts +31 -0
  36. package/dist/lib/prepare-output.d.ts.map +1 -0
  37. package/dist/lib/prepare-output.js +95 -0
  38. package/dist/lib/prepare-output.js.map +1 -0
  39. package/dist/lib/prepare-output.test.d.ts +2 -0
  40. package/dist/lib/prepare-output.test.d.ts.map +1 -0
  41. package/dist/lib/prepare-output.test.js +105 -0
  42. package/dist/lib/prepare-output.test.js.map +1 -0
  43. package/dist/lib/sweep-stale.d.ts +25 -0
  44. package/dist/lib/sweep-stale.d.ts.map +1 -0
  45. package/dist/lib/sweep-stale.js +179 -0
  46. package/dist/lib/sweep-stale.js.map +1 -0
  47. package/dist/lib/sweep-stale.test.d.ts +2 -0
  48. package/dist/lib/sweep-stale.test.d.ts.map +1 -0
  49. package/dist/lib/sweep-stale.test.js +130 -0
  50. package/dist/lib/sweep-stale.test.js.map +1 -0
  51. package/dist/skill/SKILL.md +327 -103
  52. package/dist/skill/agents/quickback-specialist/AGENT.md +93 -81
  53. package/package.json +14 -14
  54. package/src/cursor/quickback.mdc +61 -46
  55. package/src/skill/SKILL.md +327 -103
  56. package/src/skill/agents/quickback-specialist/AGENT.md +93 -81
@@ -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 `defineActions()` with Zod schemas
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 `defineActions()` with Zod input schemas (if needed)
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` - Custom actions via `defineActions()` with Zod schemas (if needed)
47
- - `handlers/` - Action handler files (if needed)
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`.
@@ -55,68 +55,72 @@ Detect the database dialect from `quickback.config.ts`:
55
55
  - Cloudflare D1 / SQLite: Use `sqliteTable`, `text`, `integer` from `drizzle-orm/sqlite-core`
56
56
  - Supabase / PostgreSQL: Use `pgTable`, `text`, `boolean`, `timestamp` from `drizzle-orm/pg-core`
57
57
 
58
- ### Table Definition Pattern
58
+ ### Table Definition Pattern (recommended: `feature()` + `q.scope()`)
59
59
 
60
60
  ```typescript
61
- import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
62
- import { defineTable } from "@quickback/compiler";
63
-
64
- export const todos = sqliteTable("todos", {
65
- id: integer("id").primaryKey(),
66
- title: text("title").notNull(),
67
- completed: integer("completed", { mode: "boolean" }).default(false),
68
- userId: text("user_id").notNull(),
69
- organizationId: text("organization_id").notNull(),
70
- });
71
-
72
- export default defineTable(todos, {
73
- firewall: {
74
- organization: {}, // Auto-detects 'organizationId' column
75
- owner: {}, // Auto-detects 'userId' column
61
+ import { feature, q } from "@quickback/compiler";
62
+
63
+ export default feature("todos", {
64
+ columns: {
65
+ id: q.id(),
66
+ title: q.text().required(),
67
+ completed: q.bool().default(false),
68
+ ownerId: q.scope("owner"), // → ctx.userId, auto-firewalled, auto-populated
69
+ organizationId: q.scope("organization"), // → ctx.activeOrgId, same
76
70
  },
71
+ // firewall block omitted — q.scope() auto-derives:
72
+ // [{ field: 'organizationId', equals: 'ctx.activeOrgId' },
73
+ // { field: 'ownerId', equals: 'ctx.userId' },
74
+ // { field: 'deletedAt', isNull: true }]
75
+ read: { access: { roles: ["member", "admin"] } },
77
76
  crud: {
78
- list: { access: { roles: ["member", "admin"] } },
79
- get: { access: { roles: ["member", "admin"] } },
80
77
  create: { access: { roles: ["member", "admin"] } },
81
78
  update: { access: { roles: ["admin"] } },
82
79
  delete: { access: { roles: ["admin"] }, mode: "soft" },
83
80
  },
84
81
  guards: {
85
82
  createable: ["title", "completed"],
86
- updatable: ["title", "completed"],
87
- },
88
- masking: {
89
- userId: { type: "redact", show: { roles: ["admin"] } },
83
+ updatable: ["title", "completed"],
90
84
  },
91
85
  });
92
86
  ```
93
87
 
88
+ For Drizzle interop (bringing forward existing schemas), use `sqliteTable` + `defineTable` and rely on auto-detection by column name (`organizationId`, `userId`, `ownerId`, `teamId`).
89
+
94
90
  ### Actions Pattern
95
91
 
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.
95
+
96
96
  ```typescript
97
- // quickback/features/todos/actions.ts
98
- import { todos } from './todos';
99
- import { defineActions } from '@quickback/compiler';
100
- import { z } from 'zod';
101
-
102
- export default defineActions(todos, {
103
- complete: {
104
- description: "Mark todo as complete",
105
- input: z.object({
106
- completedAt: z.string().datetime().optional(),
107
- }),
108
- guard: {
109
- roles: ["member", "admin"],
110
- record: { completed: { equals: false } },
111
- },
112
- execute: async ({ db, record, ctx, input }) => {
113
- await db.update(todos).set({ completed: true }).where(eq(todos.id, record.id));
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, auto-injects audit logging).
121
+
122
+ **Retired** (rejected at load time): bundled `actions.ts`, `_feature.ts`, `handlers/` directory, `defineActions()`, `*-actions.ts` filenames.
123
+
120
124
  ## Security Principles
121
125
 
122
126
  1. **Secure by default** - Nothing is accessible until explicitly opened
@@ -128,17 +132,21 @@ export default defineActions(todos, {
128
132
 
129
133
  ### Multi-tenant resource
130
134
  ```typescript
131
- firewall: {
132
- organization: {} // Auto-detects organizationId column
133
- }
135
+ // Auto-derived if organizationId is the only isolation column in the schema —
136
+ // you can omit `firewall:` entirely. Equivalent explicit form:
137
+ firewall: [
138
+ { field: 'organizationId', equals: 'ctx.activeOrgId' },
139
+ { field: 'deletedAt', isNull: true },
140
+ ]
134
141
  ```
135
142
 
136
- ### Owner-scoped with admin override
143
+ ### Owner-scoped, org-aware
137
144
  ```typescript
138
- firewall: {
139
- organization: {},
140
- owner: { mode: 'optional' } // Admins see all, users see own
141
- }
145
+ firewall: [
146
+ { field: 'organizationId', equals: 'ctx.activeOrgId' },
147
+ { field: 'ownerId', equals: 'ctx.userId' },
148
+ { field: 'deletedAt', isNull: true },
149
+ ]
142
150
  ```
143
151
 
144
152
  ### Workflow with protected status
@@ -146,7 +154,7 @@ firewall: {
146
154
  guards: {
147
155
  protected: { status: ['approve', 'reject'] }
148
156
  }
149
- // Plus defineActions() for approve/reject
157
+ // Plus actions/approve.ts and actions/reject.ts via defineAction()
150
158
  ```
151
159
 
152
160
  ### PII masking
@@ -174,50 +182,54 @@ views: {
174
182
  > Use `+` suffix with `auth.roleHierarchy` configured (e.g., `['member', 'admin', 'owner']`) to expand roles at compile time. `"member+"` → `["member", "admin", "owner"]`.
175
183
 
176
184
  ### Standalone actions (not record-based)
185
+ Setting `path:` makes an action standalone — no record loading or firewall preload.
177
186
  ```typescript
178
- // In actions.ts
179
- chat: {
180
- standalone: true,
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",
181
193
  path: "/chat",
182
194
  method: "POST",
183
195
  responseType: "stream",
184
196
  input: z.object({ message: z.string() }),
185
- guard: { roles: ["member"] },
186
- handler: "./handlers/chat",
187
- }
197
+ access: { roles: ["member"] },
198
+ async execute({ input, c }) { /* … */ },
199
+ });
188
200
  ```
189
201
 
190
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.
191
204
  ```typescript
192
- // quickback/features/utilities/actions.ts
193
- import { defineActions } from '@quickback/compiler';
194
- import { z } from 'zod';
195
-
196
- export default defineActions(null, {
197
- healthCheck: {
198
- standalone: true,
199
- path: "/health",
200
- method: "GET",
201
- description: "Health check endpoint",
202
- input: z.object({}),
203
- guard: { roles: ["member", "admin"] },
204
- handler: "./handlers/health-check",
205
- },
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 }; },
206
216
  });
207
217
  ```
208
- All actions must have `standalone: true` when there is no table.
209
218
 
210
219
  ### Public actions (no auth required)
211
220
  Use `roles: ["PUBLIC"]` for unauthenticated endpoints. Every invocation is mandatory audit logged.
212
221
  ```typescript
213
- submit: {
214
- standalone: true,
215
- path: "/submit",
222
+ // features/contact/actions/submit.ts
223
+ import { z } from "zod";
224
+ import { defineAction } from "../.quickback/define-action";
225
+
226
+ export default defineAction({
216
227
  description: "Public contact form",
228
+ path: "/submit",
217
229
  input: z.object({ name: z.string(), email: z.string().email(), message: z.string() }),
218
230
  access: { roles: ["PUBLIC"] },
219
- handler: "./handlers/submit",
220
- }
231
+ async execute({ db, input }) { /* persist submission */ return { ok: true }; },
232
+ });
221
233
  ```
222
234
  The wildcard `"*"` is NOT supported and will throw a compile error. Use `"PUBLIC"` explicitly.
223
235
 
@@ -274,7 +286,7 @@ Before finishing, verify:
274
286
  - [ ] Layouts for CMS record page field grouping (if needed)
275
287
  - [ ] No audit fields in schema (auto-injected)
276
288
  - [ ] Using `defineTable()` (not separate schema.ts + resource.ts)
277
- - [ ] Actions use `defineActions()` with Zod schemas (not JSON schema)
289
+ - [ ] Actions use `defineAction()` (one file per action under `actions/`) with Zod schemas (not JSON schema)
278
290
  - [ ] Account UI configured if auth UI needed (`account: true` or `account: { ... }`)
279
291
 
280
292
  ## Accessing Documentation