@quickback-dev/cli 0.58.1 → 0.58.3

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 (129) hide show
  1. package/README.md +3 -1
  2. package/dist/commands/compile.d.ts +5 -0
  3. package/dist/commands/compile.d.ts.map +1 -1
  4. package/dist/commands/compile.js +34 -0
  5. package/dist/commands/compile.js.map +1 -1
  6. package/dist/commands/schema.d.ts +16 -0
  7. package/dist/commands/schema.d.ts.map +1 -0
  8. package/dist/commands/schema.js +122 -0
  9. package/dist/commands/schema.js.map +1 -0
  10. package/dist/commands/schema.test.d.ts +2 -0
  11. package/dist/commands/schema.test.d.ts.map +1 -0
  12. package/dist/commands/schema.test.js +57 -0
  13. package/dist/commands/schema.test.js.map +1 -0
  14. package/dist/docs/content.d.ts.map +1 -1
  15. package/dist/docs/content.js +7 -2
  16. package/dist/docs/content.js.map +1 -1
  17. package/dist/index.js +14 -4
  18. package/dist/index.js.map +1 -1
  19. package/dist/lib/action-harvest.d.ts +9 -6
  20. package/dist/lib/action-harvest.d.ts.map +1 -1
  21. package/dist/lib/action-harvest.js +28 -15
  22. package/dist/lib/action-harvest.js.map +1 -1
  23. package/dist/lib/action-harvest.test.js +21 -0
  24. package/dist/lib/action-harvest.test.js.map +1 -1
  25. package/dist/lib/api-client.d.ts +53 -0
  26. package/dist/lib/api-client.d.ts.map +1 -1
  27. package/dist/lib/api-client.js +2 -0
  28. package/dist/lib/api-client.js.map +1 -1
  29. package/dist/lib/api-client.test.js +18 -0
  30. package/dist/lib/api-client.test.js.map +1 -1
  31. package/dist/lib/migrations/command-runner.d.ts +10 -0
  32. package/dist/lib/migrations/command-runner.d.ts.map +1 -0
  33. package/dist/lib/migrations/command-runner.js +66 -0
  34. package/dist/lib/migrations/command-runner.js.map +1 -0
  35. package/dist/lib/migrations/drizzle.d.ts +12 -0
  36. package/dist/lib/migrations/drizzle.d.ts.map +1 -0
  37. package/dist/lib/migrations/drizzle.js +60 -0
  38. package/dist/lib/migrations/drizzle.js.map +1 -0
  39. package/dist/lib/migrations/drizzle.test.d.ts +2 -0
  40. package/dist/lib/migrations/drizzle.test.d.ts.map +1 -0
  41. package/dist/lib/migrations/drizzle.test.js +61 -0
  42. package/dist/lib/migrations/drizzle.test.js.map +1 -0
  43. package/dist/lib/migrations/errors.d.ts +6 -0
  44. package/dist/lib/migrations/errors.d.ts.map +1 -0
  45. package/dist/lib/migrations/errors.js +9 -0
  46. package/dist/lib/migrations/errors.js.map +1 -0
  47. package/dist/lib/migrations/executor.d.ts +52 -0
  48. package/dist/lib/migrations/executor.d.ts.map +1 -0
  49. package/dist/lib/migrations/executor.js +190 -0
  50. package/dist/lib/migrations/executor.js.map +1 -0
  51. package/dist/lib/migrations/executor.test.d.ts +2 -0
  52. package/dist/lib/migrations/executor.test.d.ts.map +1 -0
  53. package/dist/lib/migrations/executor.test.js +241 -0
  54. package/dist/lib/migrations/executor.test.js.map +1 -0
  55. package/dist/lib/migrations/index.d.ts +11 -0
  56. package/dist/lib/migrations/index.d.ts.map +1 -0
  57. package/dist/lib/migrations/index.js +11 -0
  58. package/dist/lib/migrations/index.js.map +1 -0
  59. package/dist/lib/migrations/inventory.d.ts +19 -0
  60. package/dist/lib/migrations/inventory.d.ts.map +1 -0
  61. package/dist/lib/migrations/inventory.js +135 -0
  62. package/dist/lib/migrations/inventory.js.map +1 -0
  63. package/dist/lib/migrations/inventory.test.d.ts +2 -0
  64. package/dist/lib/migrations/inventory.test.d.ts.map +1 -0
  65. package/dist/lib/migrations/inventory.test.js +81 -0
  66. package/dist/lib/migrations/inventory.test.js.map +1 -0
  67. package/dist/lib/migrations/lock.d.ts +6 -0
  68. package/dist/lib/migrations/lock.d.ts.map +1 -0
  69. package/dist/lib/migrations/lock.js +101 -0
  70. package/dist/lib/migrations/lock.js.map +1 -0
  71. package/dist/lib/migrations/lock.test.d.ts +2 -0
  72. package/dist/lib/migrations/lock.test.d.ts.map +1 -0
  73. package/dist/lib/migrations/lock.test.js +35 -0
  74. package/dist/lib/migrations/lock.test.js.map +1 -0
  75. package/dist/lib/migrations/paths.d.ts +12 -0
  76. package/dist/lib/migrations/paths.d.ts.map +1 -0
  77. package/dist/lib/migrations/paths.js +82 -0
  78. package/dist/lib/migrations/paths.js.map +1 -0
  79. package/dist/lib/migrations/paths.test.d.ts +2 -0
  80. package/dist/lib/migrations/paths.test.d.ts.map +1 -0
  81. package/dist/lib/migrations/paths.test.js +32 -0
  82. package/dist/lib/migrations/paths.test.js.map +1 -0
  83. package/dist/lib/migrations/plan.d.ts +7 -0
  84. package/dist/lib/migrations/plan.d.ts.map +1 -0
  85. package/dist/lib/migrations/plan.js +189 -0
  86. package/dist/lib/migrations/plan.js.map +1 -0
  87. package/dist/lib/migrations/plan.test.d.ts +2 -0
  88. package/dist/lib/migrations/plan.test.d.ts.map +1 -0
  89. package/dist/lib/migrations/plan.test.js +104 -0
  90. package/dist/lib/migrations/plan.test.js.map +1 -0
  91. package/dist/lib/migrations/staging.d.ts +18 -0
  92. package/dist/lib/migrations/staging.d.ts.map +1 -0
  93. package/dist/lib/migrations/staging.js +150 -0
  94. package/dist/lib/migrations/staging.js.map +1 -0
  95. package/dist/lib/migrations/staging.test.d.ts +2 -0
  96. package/dist/lib/migrations/staging.test.d.ts.map +1 -0
  97. package/dist/lib/migrations/staging.test.js +73 -0
  98. package/dist/lib/migrations/staging.test.js.map +1 -0
  99. package/dist/lib/migrations/types.d.ts +49 -0
  100. package/dist/lib/migrations/types.d.ts.map +1 -0
  101. package/dist/lib/migrations/types.js +18 -0
  102. package/dist/lib/migrations/types.js.map +1 -0
  103. package/dist/lib/schema-engine-loader.d.ts +8 -0
  104. package/dist/lib/schema-engine-loader.d.ts.map +1 -0
  105. package/dist/lib/schema-engine-loader.js +26 -0
  106. package/dist/lib/schema-engine-loader.js.map +1 -0
  107. package/dist/lib/schema-sync/index.d.ts +41 -0
  108. package/dist/lib/schema-sync/index.d.ts.map +1 -0
  109. package/dist/lib/schema-sync/index.js +246 -0
  110. package/dist/lib/schema-sync/index.js.map +1 -0
  111. package/dist/lib/schema-sync/index.test.d.ts +2 -0
  112. package/dist/lib/schema-sync/index.test.d.ts.map +1 -0
  113. package/dist/lib/schema-sync/index.test.js +128 -0
  114. package/dist/lib/schema-sync/index.test.js.map +1 -0
  115. package/dist/schema-engine/index.d.ts +3 -0
  116. package/dist/schema-engine/index.d.ts.map +1 -0
  117. package/dist/schema-engine/index.js +854 -0
  118. package/dist/schema-engine/index.js.map +7 -0
  119. package/dist/schema-engine/managed-columns.d.ts +82 -0
  120. package/dist/schema-engine/managed-columns.d.ts.map +1 -0
  121. package/dist/schema-engine/source-sync.d.ts +64 -0
  122. package/dist/schema-engine/source-sync.d.ts.map +1 -0
  123. package/dist/skill/docs/compiler/definitions/actions.md +14 -6
  124. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +7 -4
  125. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/typescript.md +141 -0
  126. package/package.json +4 -2
  127. package/src/skill/docs/compiler/definitions/actions.md +14 -6
  128. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +7 -4
  129. package/src/skill/docs/compiler/targets/hono-api/using-the-api/typescript.md +141 -0
@@ -31,14 +31,17 @@ Each endpoint includes request/response schemas derived from your Drizzle column
31
31
 
32
32
  The generated component schemas carry enough type information that strict validators (zod, openapi-typescript, openapi-fetch) produce non-optional, narrowed types out of the box:
33
33
 
34
- - **`required[]` on response components** — every non-nullable column is listed, so generated SDKs treat them as guaranteed-present rather than optional.
34
+ - **`required[]` on response components** — every selected column is listed; nullable columns are present as `T | null`, not optional.
35
+ - **Logical q types survive database lowering** — `q.bool()` remains `boolean`, `q.timestamp()` remains an ISO date-time string, and `q.url()` retains its URI format even when D1 stores the value as text or integer.
35
36
  - **Closed enums on `text(_, { enum: [...] })` columns** — emitted as `{ type: "string", enum: [...] }`, narrowing to a literal union in TS.
36
37
  - **`Error.code` is a closed enum** — every `code` value the API can emit (`AUTH_MISSING`, `DB_UNIQUE_VIOLATION`, `BATCH_SIZE_EXCEEDED`, …) is enumerated so consumers can `switch` exhaustively.
37
38
  - **ID `format`** — only emitted as `format: "uuid"` when your project's `generateId` actually produces UUIDs. cuid2 / prefixed / nanoid / serial generators get plain `{ type: "string" }`, keeping strict OpenAPI validators happy.
38
39
 
39
- ### Action input schemas
40
+ ### Action input and output schemas
40
41
 
41
- Actions defined with [`defineAction({ input: z.object(...) })`](/compiler/definitions/actions) get their full input schema lifted into the operation's `requestBody`. Simple `z.object({...})` shapes are extracted at compile time; for discriminated unions, refinements, recursive schemas, and bare-identifier references (`input: createPersonInput`), the compiler runs your action file through Zod 4's native `z.toJSONSchema()` during compilation so the OpenAPI request body and the MCP tool's `inputSchema` round-trip exactly what your Zod expression declares — no static translator to maintain.
42
+ Actions defined with [`defineAction({ input, output })`](/compiler/definitions/actions) get both Zod schemas lifted into the operation. `GET` inputs become typed query parameters; other methods use a JSON request body. A declared `output` becomes the success response schema and the generated helper requires `execute` to return a compatible value.
43
+
44
+ The CLI evaluates only the schema declarations in an isolated local bundle and converts them with Zod 4's `z.toJSONSchema()`. It never invokes `execute`, and the hosted compiler only receives plain JSON Schema data. Discriminated unions, refinements, recursive schemas, and shared schema references therefore flow to OpenAPI and generated TypeScript without relying on the compiler's static fallback parser.
42
45
 
43
46
  ## Configuration
44
47
 
@@ -154,7 +157,7 @@ export default defineConfig({
154
157
 
155
158
  The file is generated by piping the in-memory spec through [openapi-typescript](https://github.com/openapi-ts/openapi-typescript) — you can keep running it manually if you want a different output path or version, but for the typical case there's nothing to wire up. If your API project and SPA live in the same repo, prefer multiple `openapi.types` outputs over a second manual `codegen:api` step so one `quickback compile` keeps both copies in sync. Skipped automatically when `openapi.generate` is `false`.
156
159
 
157
- The bundled Quickback CMS and Account SPAs do not import `api-types.gen.ts`. CMS is driven by `schema-registry.json`, and Account uses Better Auth plus small hand-written fetch helpers. Use `openapi.types` for your own colocated client apps.
160
+ For application code, prefer the compact first-party [`quickback.gen.ts` type tree](/compiler/targets/hono-api/using-the-api/typescript). Keep `api-types.gen.ts` for `openapi-fetch` and third-party OpenAPI tooling.
158
161
 
159
162
  ### External viewer
160
163
 
@@ -0,0 +1,141 @@
1
+ # TypeScript Type Tree
2
+
3
+ Every compile emits `quickback.gen.ts`: a compact, type-only tree designed for application code. It is generated directly from the same compiler model that drives routes and OpenAPI, so there is no runtime package and no code to initialize.
4
+
5
+ ```typescript
6
+ import type { Api, Qb } from "../quickback.gen";
7
+
8
+ type Application = Api.applications.Row;
9
+ type NewApplication = Api.applications.Insert;
10
+ type ApplicationPatch = Api.applications.Update;
11
+ type ApplicationId = Api.applications.Id;
12
+
13
+ type AdvanceInput = Api.applications.actions.advance.Input;
14
+ type AdvanceOutput = Api.applications.actions.advance.Output;
15
+ type PipelineItem = Api.applications.views.pipeline.Item;
16
+ type PipelineResponse = Api.applications.views.pipeline.Response;
17
+
18
+ type Page = Qb.Page<Application>;
19
+ type ApiProblem = Qb.Problem;
20
+ ```
21
+
22
+ Feature areas preserve their authored hierarchy:
23
+
24
+ ```typescript
25
+ type Booking = Api.events.travel.bookings.Row;
26
+ ```
27
+
28
+ ## Table types
29
+
30
+ Each resource table exposes:
31
+
32
+ | Member | Meaning |
33
+ |---|---|
34
+ | `Id` | Nominal table-specific primary-key type |
35
+ | `Row` | Complete selected wire shape |
36
+ | `Insert` | Createable fields, with defaults and nullable fields optional |
37
+ | `Update` | Updatable fields, all optional |
38
+ | `ListResponse` | `Qb.Page<Row>` |
39
+ | `columns.<name>` | Type of one row column |
40
+ | `views.<name>.Item` | A view's projected row |
41
+ | `views.<name>.Response` | Page plus typed aggregations where declared |
42
+ | `actions.<name>.Input` | The action's Zod input contract |
43
+ | `actions.<name>.Output` | The declared Zod output contract, or `unknown` |
44
+
45
+ Primary and foreign keys are branded by default. That makes accidentally passing a candidate ID where a job ID is required a TypeScript error, while both values remain ordinary strings or numbers at runtime.
46
+
47
+ ```typescript
48
+ function loadJob(id: Api.jobs.Id) {}
49
+
50
+ declare const candidateId: Api.candidates.Id;
51
+ loadJob(candidateId); // TypeScript error
52
+ ```
53
+
54
+ At an untyped boundary, validate the value and cast it once:
55
+
56
+ ```typescript
57
+ const jobId = routeParams.id as Api.jobs.Id;
58
+ ```
59
+
60
+ ## Reading collections
61
+
62
+ List and view responses share one envelope: rows under `data`, pagination
63
+ metadata under `pagination`, and `view` naming the projection behind the
64
+ response (`null` for the default collection read).
65
+
66
+ ```typescript
67
+ declare const res: Api.applications.ListResponse; // Qb.Page<Api.applications.Row>
68
+
69
+ res.data; // Api.applications.Row[]
70
+ res.view; // string | null
71
+ res.pagination.count; // rows in this page
72
+ res.pagination.hasMore;
73
+ res.pagination.nextCursor; // pass back as ?starting_after=
74
+ res.pagination.total; // number | undefined — only when ?total=true
75
+ ```
76
+
77
+ `total` and `totalPages` are counted only when the request passes
78
+ `?total=true`, so both are optional; every other member is always present. A
79
+ view that declares aggregations intersects this shape with a typed
80
+ `aggregations` object, and an aggregate-only view returns `{ view,
81
+ aggregations }` with no rows or pagination.
82
+
83
+ ## Declaring action outputs
84
+
85
+ Add an optional `output` Zod schema to make an action end-to-end typed:
86
+
87
+ ```typescript
88
+ export default defineAction({
89
+ description: "Advance an application",
90
+ input: z.object({
91
+ nextStatus: z.enum(["screening", "interview", "offer"]),
92
+ }),
93
+ output: z.object({
94
+ id: z.string(),
95
+ status: z.enum(["screening", "interview", "offer"]),
96
+ }),
97
+ access: { roles: ["recruiter+"] },
98
+ async execute({ record, input }) {
99
+ return { id: record.id, status: input.nextStatus };
100
+ },
101
+ });
102
+ ```
103
+
104
+ The generated feature helper checks `execute` against the declared output. The CLI harvests both schemas locally without invoking `execute`; the resulting contract feeds `quickback.gen.ts`, OpenAPI, and `api-types.gen.ts`.
105
+
106
+ ## Configuration
107
+
108
+ The artifact is on by default:
109
+
110
+ ```typescript
111
+ export default defineConfig({
112
+ // Default: quickback.gen.ts
113
+ types: true,
114
+ });
115
+ ```
116
+
117
+ Use a custom path, fan out identical copies to colocated apps, disable branding, or turn the artifact off:
118
+
119
+ ```typescript
120
+ export default defineConfig({
121
+ types: {
122
+ output: [
123
+ "quickback.gen.ts",
124
+ "apps/web/src/lib/quickback.gen.ts",
125
+ ],
126
+ brandIds: true,
127
+ },
128
+ });
129
+ ```
130
+
131
+ | `types` value | Behavior |
132
+ |---|---|
133
+ | `true` or omitted | Write `quickback.gen.ts` |
134
+ | `false` | Do not emit the first-party type tree |
135
+ | `"src/lib/quickback.gen.ts"` | Write to one custom path |
136
+ | `["quickback.gen.ts", "apps/web/src/quickback.gen.ts"]` | Fan out identical copies |
137
+ | `{ output, brandIds: false }` | Configure paths and use structural IDs |
138
+
139
+ `api-types.gen.ts` remains available through `openapi.types` for `openapi-fetch` and third-party OpenAPI tools. The two artifacts are independent: disabling OpenAPI types does not disable the first-party tree.
140
+
141
+ The compiler also emits `reports/types.parity.gen.ts` when both artifacts exist. Quickback's output-matrix CI compiles that proof separately to require mutual assignability between direct table/action types and the OpenAPI wire types; it is outside the generated application's `src/**/*` build.