@quickback-dev/cli 0.51.0 → 0.51.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.
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +34 -19
- package/dist/commands/compile.js.map +1 -1
- package/dist/docs/content.js +19 -19
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/action-harvest.d.ts +35 -4
- package/dist/lib/action-harvest.d.ts.map +1 -1
- package/dist/lib/action-harvest.js +233 -50
- package/dist/lib/action-harvest.js.map +1 -1
- package/dist/lib/action-harvest.test.js +130 -2
- package/dist/lib/action-harvest.test.js.map +1 -1
- package/dist/lib/auth.d.ts +6 -0
- package/dist/lib/auth.d.ts.map +1 -1
- package/dist/lib/auth.js +18 -1
- package/dist/lib/auth.js.map +1 -1
- package/dist/lib/auth.test.d.ts +2 -0
- package/dist/lib/auth.test.d.ts.map +1 -0
- package/dist/lib/auth.test.js +19 -0
- package/dist/lib/auth.test.js.map +1 -0
- package/dist/lib/compile-next-steps.d.ts +4 -0
- package/dist/lib/compile-next-steps.d.ts.map +1 -0
- package/dist/lib/compile-next-steps.js +69 -0
- package/dist/lib/compile-next-steps.js.map +1 -0
- package/dist/lib/compile-next-steps.test.d.ts +2 -0
- package/dist/lib/compile-next-steps.test.d.ts.map +1 -0
- package/dist/lib/compile-next-steps.test.js +76 -0
- package/dist/lib/compile-next-steps.test.js.map +1 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +1 -0
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-writer.d.ts +1 -1
- package/dist/lib/file-writer.d.ts.map +1 -1
- package/dist/lib/file-writer.js +20 -5
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/lib/file-writer.test.d.ts +2 -0
- package/dist/lib/file-writer.test.d.ts.map +1 -0
- package/dist/lib/file-writer.test.js +90 -0
- package/dist/lib/file-writer.test.js.map +1 -0
- package/dist/lib/shell.test.d.ts +2 -0
- package/dist/lib/shell.test.d.ts.map +1 -0
- package/dist/lib/shell.test.js +39 -0
- package/dist/lib/shell.test.js.map +1 -0
- package/dist/skill/docs/changelog.md +401 -1
- package/dist/skill/docs/compiler/cloud-compiler/cli.md +16 -0
- package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +4 -2
- package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +17 -5
- package/dist/skill/docs/compiler/config/auth.md +17 -2
- package/dist/skill/docs/compiler/config/index.md +271 -12
- package/dist/skill/docs/compiler/config/output.md +49 -3
- package/dist/skill/docs/compiler/config/providers.md +12 -1
- package/dist/skill/docs/compiler/config/variables.md +5 -0
- package/dist/skill/docs/compiler/definitions/access.md +7 -0
- package/dist/skill/docs/compiler/definitions/actions.md +156 -9
- package/dist/skill/docs/compiler/definitions/firewall.md +6 -1
- package/dist/skill/docs/compiler/definitions/schema.md +12 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +353 -20
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +7 -1
- package/dist/skill/docs/stack/account-ui/hooks.md +104 -1
- package/dist/skill/docs/stack/auth/plugins/aws-sns.md +20 -3
- package/dist/skill/docs/stack/cms/schema-format.md +4 -2
- package/dist/skill/docs/stack/cms/schema-registry.md +4 -2
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +401 -1
- package/src/skill/docs/compiler/cloud-compiler/cli.md +16 -0
- package/src/skill/docs/compiler/cloud-compiler/endpoints.md +4 -2
- package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +17 -5
- package/src/skill/docs/compiler/config/auth.md +17 -2
- package/src/skill/docs/compiler/config/index.md +271 -12
- package/src/skill/docs/compiler/config/output.md +49 -3
- package/src/skill/docs/compiler/config/providers.md +12 -1
- package/src/skill/docs/compiler/config/variables.md +5 -0
- package/src/skill/docs/compiler/definitions/access.md +7 -0
- package/src/skill/docs/compiler/definitions/actions.md +156 -9
- package/src/skill/docs/compiler/definitions/firewall.md +6 -1
- package/src/skill/docs/compiler/definitions/schema.md +12 -0
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +353 -20
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +7 -1
- package/src/skill/docs/stack/account-ui/hooks.md +104 -1
- package/src/skill/docs/stack/auth/plugins/aws-sns.md +20 -3
- package/src/skill/docs/stack/cms/schema-format.md +4 -2
- package/src/skill/docs/stack/cms/schema-registry.md +4 -2
|
@@ -115,12 +115,43 @@ export default defineAction({
|
|
|
115
115
|
|
|
116
116
|
> **`defineAction` import.** Import from `"../.quickback/define-action"` —
|
|
117
117
|
> the `.quickback/` directory is generated alongside your feature with a
|
|
118
|
-
> typed helper
|
|
119
|
-
>
|
|
118
|
+
> typed helper. It infers `record` and Zod `input`, exposes the generated
|
|
119
|
+
> `Services`, types `c` as a Hono request context, binds `whereRecord` and
|
|
120
|
+
> `whereTransition` to the feature table, and preserves the exact value
|
|
121
|
+
> returned by `execute` without imposing an action-output schema. Scoped
|
|
122
|
+
> `db` and interactive `tx` are schema-aware on D1 and Neon Hyperdrive;
|
|
123
|
+
> HTTP/WebSocket Neon keeps its dynamic database escape hatch. `AppContext`
|
|
124
|
+
> also retains its open index for namespace-hydrated fields. Audit fields
|
|
125
|
+
> (`createdAt`, `createdBy`, `modifiedAt`,
|
|
120
126
|
> `modifiedBy`) are hard-stamped by the audit DB wrapper on every
|
|
121
127
|
> `db.insert().values()` and `db.update().set()` — handlers don't pass
|
|
122
128
|
> them and can't override them.
|
|
123
129
|
|
|
130
|
+
### Local input-schema harvest
|
|
131
|
+
|
|
132
|
+
Before sending a compile request, the CLI loads each action in an isolated
|
|
133
|
+
local bundle and converts `action.input` with Zod 4's `z.toJSONSchema`. It does
|
|
134
|
+
not call `execute`; the hosted compiler never evaluates project code. Under
|
|
135
|
+
contract v2, every action must produce a schema. A failure names the exact
|
|
136
|
+
action, whether bundling or evaluation failed, and the underlying local error.
|
|
137
|
+
V1 can still fall back to the lower-fidelity static schema parser.
|
|
138
|
+
|
|
139
|
+
Bare imports are resolved from the generated runtime's configured
|
|
140
|
+
`build.outputDir/node_modules` first. If definitions live in `quickback/` and
|
|
141
|
+
the generated Worker lives in `src/`, install runtime dependencies in `src/`
|
|
142
|
+
as usual; no project-root dependency symlink is required. Shared schema or DTO
|
|
143
|
+
modules may also declare top-level Drizzle selection objects. Quickback
|
|
144
|
+
replaces authored table exports with inert proxies during this schema-only
|
|
145
|
+
evaluation, so reading `records.id` to build a projection does not execute
|
|
146
|
+
application or database logic.
|
|
147
|
+
|
|
148
|
+
Parameterized standalone paths use Hono's `:param` syntax in authored source,
|
|
149
|
+
for example `path: "/events/:eventId/check-in"`. The harvest planner converts
|
|
150
|
+
those segments to the OpenAPI `{param}` form before applying the schema, so
|
|
151
|
+
contract-v2 completeness uses the same route key as the emitted OpenAPI and MCP
|
|
152
|
+
surfaces. The same normalization applies when a record resource path contains
|
|
153
|
+
namespace parameters.
|
|
154
|
+
|
|
124
155
|
### Configuration Options
|
|
125
156
|
|
|
126
157
|
| Option | Required | Description |
|
|
@@ -276,6 +307,14 @@ The `input` is shared across the batch — the action's Zod schema is
|
|
|
276
307
|
validated once, not per id. For per-record input variation, use the
|
|
277
308
|
single-record endpoint (`POST /:id/{action}`) or write a standalone action.
|
|
278
309
|
|
|
310
|
+
The generated OpenAPI document and MCP tools reuse that exact action schema
|
|
311
|
+
in both places: as the single-record request body and as the bulk wrapper's
|
|
312
|
+
nested `input` property. Under contract v2, Quickback considers the action's
|
|
313
|
+
schema harvest complete only after both operations are patched. This also
|
|
314
|
+
holds when the table filename and declared table name use different casing or
|
|
315
|
+
separators (for example, `event-guests.ts` exporting `event_guests`); the
|
|
316
|
+
operations follow the table's declared resource path.
|
|
317
|
+
|
|
279
318
|
**Response (207 Multi-Status when any record fails, 200 when clean):**
|
|
280
319
|
|
|
281
320
|
```json
|
|
@@ -660,6 +699,108 @@ async execute({ db, ctx, input }) {
|
|
|
660
699
|
- **Masking** — actions are backend code that may need raw data
|
|
661
700
|
- **Access** — already checked before action execution
|
|
662
701
|
|
|
702
|
+
### Delegated principals and `databaseAccess`
|
|
703
|
+
|
|
704
|
+
On a contract-v2 Cloudflare + Neon Hyperdrive project, an action can admit a
|
|
705
|
+
configured delegated principal with `access.principals`:
|
|
706
|
+
|
|
707
|
+
```typescript
|
|
708
|
+
export default defineAction({
|
|
709
|
+
description: "Confirm attendance from an event session",
|
|
710
|
+
path: "/attendance/confirm",
|
|
711
|
+
input: z.object({ response: z.enum(["yes", "no"]) }),
|
|
712
|
+
access: { principals: ["event_delegate"] },
|
|
713
|
+
async execute({ ctx, db, input }) {
|
|
714
|
+
// ctx.principal is guaranteed and narrowed by the generated helper.
|
|
715
|
+
const { eventId, personId } = ctx.principal.claims;
|
|
716
|
+
return confirmAttendance(db, { eventId, personId, response: input.response });
|
|
717
|
+
},
|
|
718
|
+
});
|
|
719
|
+
```
|
|
720
|
+
|
|
721
|
+
This is a separate authority lane, not an account impersonation. A delegated
|
|
722
|
+
action context has no `userId`, active organization/team, or membership roles.
|
|
723
|
+
If access has a `PUBLIC` sibling arm, the generated type includes the anonymous
|
|
724
|
+
lane and code must narrow `ctx.principal` before reading it.
|
|
725
|
+
|
|
726
|
+
For an organization- or team-scoped host feature, the standalone route does
|
|
727
|
+
not run the Better Auth `activeOrgId` / `activeTeamId` precondition before a
|
|
728
|
+
principal access tree. Authentication and `evaluateAccessPreRecord` still run;
|
|
729
|
+
the declared `principals` arm is the authority decision. This avoids turning an
|
|
730
|
+
account-session field into an accidental prerequisite for delegated callers.
|
|
731
|
+
|
|
732
|
+
The generated standalone route reuses that action-specific `execute` context
|
|
733
|
+
after its runtime access gates. Account, `event_pass`, and `event_delegate`
|
|
734
|
+
actions therefore keep distinct compile-time authority types all the way into
|
|
735
|
+
the handler. The route also reuses the action's schema-aware scoped `db` type,
|
|
736
|
+
including when an unsafe/service-role client is wrapped before the call. If a
|
|
737
|
+
relationship uses `loads` / `exposeAs`, the loaded row type is
|
|
738
|
+
intersected with the same authority context: a single or shared hydration
|
|
739
|
+
target is required, while targets selected by distinct relationship lanes are
|
|
740
|
+
optional and must be narrowed by the handler.
|
|
741
|
+
|
|
742
|
+
For tables queried by authored actions, `resource.databaseAccess` adds an
|
|
743
|
+
independent Postgres RLS policy without adding HTTP surface. It never mounts a
|
|
744
|
+
read/CRUD route and never adds an OpenAPI operation. The action remains the API
|
|
745
|
+
layer where validation, state transitions, side effects, and business logic
|
|
746
|
+
belong; `databaseAccess` is only the database's row-level upper bound.
|
|
747
|
+
|
|
748
|
+
```typescript
|
|
749
|
+
export default defineTable(attendanceEvidence, {
|
|
750
|
+
// Ordinary account CRUD remains organization-scoped.
|
|
751
|
+
firewall: [
|
|
752
|
+
{ field: "organizationId", equals: "ctx.activeOrgId" },
|
|
753
|
+
],
|
|
754
|
+
|
|
755
|
+
// Authored actions can use their caller-scoped db under one of two exact
|
|
756
|
+
// row lanes. Sibling arms OR; fields in each arm AND.
|
|
757
|
+
databaseAccess: {
|
|
758
|
+
select: {
|
|
759
|
+
or: [
|
|
760
|
+
{
|
|
761
|
+
roles: ["AUTHENTICATED"],
|
|
762
|
+
record: {
|
|
763
|
+
organizationId: { equals: "$ctx.activeOrgId" },
|
|
764
|
+
},
|
|
765
|
+
},
|
|
766
|
+
{
|
|
767
|
+
principals: ["event_delegate"],
|
|
768
|
+
record: {
|
|
769
|
+
eventId: { equals: "$ctx.principal.claims.eventId" },
|
|
770
|
+
personId: { equals: "$ctx.principal.claims.personId" },
|
|
771
|
+
},
|
|
772
|
+
},
|
|
773
|
+
],
|
|
774
|
+
},
|
|
775
|
+
},
|
|
776
|
+
});
|
|
777
|
+
```
|
|
778
|
+
|
|
779
|
+
`databaseAccess` supports `select`, `insert`, `update`, and `delete`. Its rule
|
|
780
|
+
language is intentionally smaller than application access: `principals`,
|
|
781
|
+
`roles`, recursive `or`/`and`, and record `equals` against a DB-visible account
|
|
782
|
+
or principal context value. `userRole`, functions, request/body values, and
|
|
783
|
+
other predicate operators are compile errors.
|
|
784
|
+
|
|
785
|
+
Every authorization path must contain at least one nonempty record equality.
|
|
786
|
+
A principal-only or role-only leaf is rejected; every `or` arm must be bounded.
|
|
787
|
+
An `and` group is bounded when at least one child bounds every expansion (for
|
|
788
|
+
example, a principal child AND an event-id record child). A node cannot mix
|
|
789
|
+
leaf fields with `or`/`and`, because the boolean node is the complete rule.
|
|
790
|
+
This mandatory shape prevents an action declaration from accidentally granting
|
|
791
|
+
the delegated principal an entire table.
|
|
792
|
+
|
|
793
|
+
The supported equality sources are `ctx.userId`, `ctx.activeOrgId`,
|
|
794
|
+
`ctx.activeTeamId`, `ctx.principal.actor.id`, optional principal session/family
|
|
795
|
+
ids, and `ctx.principal.claims.<name>` (with or without a leading `$`). The
|
|
796
|
+
record keys are Drizzle/JavaScript table field names; Quickback resolves them
|
|
797
|
+
through the table metadata and quotes the exact physical PostgreSQL identifier,
|
|
798
|
+
so a field such as `eventId: text("event-id")` is safe. Unknown fields fail the
|
|
799
|
+
compile. `ADMIN` and the app-only `INTERNAL` marker are forbidden on this DB
|
|
800
|
+
surface, while `SYSADMIN` retains its explicit `cms.sysadmin` prerequisite. The
|
|
801
|
+
feature is rejected outside Cloudflare + Neon Hyperdrive because those targets
|
|
802
|
+
cannot guarantee request-scoped Postgres claims.
|
|
803
|
+
|
|
663
804
|
### Relational queries are blocked (fail-closed)
|
|
664
805
|
|
|
665
806
|
Drizzle's relational query API — `db.query.<table>.findFirst()` /
|
|
@@ -720,13 +861,19 @@ Unsafe cross-tenant actions are generated with:
|
|
|
720
861
|
- sysadmin gate (`ctx.userRole === "sysadmin"`)
|
|
721
862
|
- mandatory audit logging on deny/success/error
|
|
722
863
|
|
|
723
|
-
**Provider note (Neon):**
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
`
|
|
728
|
-
|
|
729
|
-
|
|
864
|
+
**Provider note (Neon):** `unsafe.enabled` controls app-layer scoped-query
|
|
865
|
+
bypass, while `unsafe.crossTenant` controls database-layer RLS bypass. An
|
|
866
|
+
unsafe action with `crossTenant: false` receives a raw Drizzle handle backed by
|
|
867
|
+
the request database, so the caller's organization or delegated-principal
|
|
868
|
+
claims remain active—including inside `db.transaction()`. Its code must still
|
|
869
|
+
provide every intended scope predicate explicitly.
|
|
870
|
+
|
|
871
|
+
Only an action with `crossTenant: true` acquires the dedicated service-role
|
|
872
|
+
handle (`createServiceDb`). That handle sets the `quickback.service_role`
|
|
873
|
+
transaction marker instead of caller claims, and generated RLS grants it an
|
|
874
|
+
explicit per-table bypass policy. The sysadmin guard and mandatory audit log
|
|
875
|
+
therefore protect the same boundary that receives the RLS bypass. The
|
|
876
|
+
audit-logging contract is otherwise identical to D1. Neon with
|
|
730
877
|
`connectionMode: 'websocket'` does not support unsafe actions yet and fails
|
|
731
878
|
the compile with a descriptive error.
|
|
732
879
|
|
|
@@ -61,7 +61,7 @@ When you omit the `firewall:` block entirely, the compiler scans the schema for
|
|
|
61
61
|
|
|
62
62
|
```typescript
|
|
63
63
|
type FirewallPredicate =
|
|
64
|
-
| { field: string; equals: string; optional?: boolean } // column = ctx.* (or literal)
|
|
64
|
+
| { field: string; equals: string; optional?: boolean; nullable?: true } // column = ctx.* (or literal)
|
|
65
65
|
| { field: string; isNull: true } // column IS NULL
|
|
66
66
|
| { field: string; in: string[] | string; optional?: boolean } // column IN (...)
|
|
67
67
|
| { field: string; via: string } // column IN (relationship subquery)
|
|
@@ -97,6 +97,11 @@ Null-safe scope semantics make this safe (these apply **inside `all`/`any` group
|
|
|
97
97
|
- Mark an arm `{ optional: true }` to **drop-instead-of-deny** when absent inside an `all` group (the teamless rest-of-org slice — `ctx.activeTeamId` is implicitly optional).
|
|
98
98
|
- **Owner** (`ctx.userId`) and **soft-delete** (`isNull deletedAt`) are always present / always AND'd — never relaxed.
|
|
99
99
|
|
|
100
|
+
`nullable: true` is a separate database-schema opt-in, supported only on an
|
|
101
|
+
owner predicate whose source is exactly `ctx.userId`. It allows the persisted
|
|
102
|
+
owner column to be NULL; NULL rows still do not match the owner arm because SQL
|
|
103
|
+
equality never matches NULL. It does not make the request claim optional.
|
|
104
|
+
|
|
100
105
|
```typescript
|
|
101
106
|
// (org OR event) AND owner AND not-deleted
|
|
102
107
|
firewall: {
|
|
@@ -642,6 +642,18 @@ export const jobsRelations = relations(jobs, ({ one, many }) => ({
|
|
|
642
642
|
}));
|
|
643
643
|
```
|
|
644
644
|
|
|
645
|
+
Drizzle `relations(...)` describe application-side joins; they do not always
|
|
646
|
+
create a database foreign-key constraint. On Neon, use
|
|
647
|
+
[`compiler.migrations.foreignKeys`](/compiler/config#neon-foreign-key-migrations)
|
|
648
|
+
for fully qualified cross-schema or composite constraints that cannot be
|
|
649
|
+
declared alongside a table. The ordered source and target column tuples must
|
|
650
|
+
have equal arity, and the referenced target tuple must have a matching unique
|
|
651
|
+
or primary-key constraint before the foreign key migration runs.
|
|
652
|
+
|
|
653
|
+
Use these constraints for relational integrity only. Authorization, pass
|
|
654
|
+
consumption, state transitions, and other business logic belong in the API
|
|
655
|
+
action layer.
|
|
656
|
+
|
|
645
657
|
## Database Configuration
|
|
646
658
|
|
|
647
659
|
Configure database options in your Quickback config:
|