@workbasehq/core 0.1.0 → 0.2.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.
@@ -0,0 +1,136 @@
1
+ import type { KernelRegistry } from './kernel/registry'
2
+ import type { Scope } from './types'
3
+ import type { ConsoleWidget, ConsoleDetailItem, ConsoleEntityDisplay, ConsoleFieldDisplay, ConsoleGrant, ConsoleModelUI, ConsoleRegistry } from './console-contract'
4
+ import type { ConsoleAuthorization } from './console-authorization'
5
+
6
+ const safeGrant = (grant: ConsoleGrant): ConsoleGrant => typeof grant === 'string' ? grant : pick(grant, ['entity', 'operation'])
7
+
8
+ function pick<T, K extends keyof T>(source: T, keys: readonly K[]): Pick<T, K> {
9
+ return Object.fromEntries(keys.filter(key => source[key] !== undefined).map(key => [key, source[key]])) as Pick<T, K>
10
+ }
11
+
12
+ /** Project every copy of presentation data through the same live authority.
13
+ * Drop predicates as a whole: pruning Boolean operands would change their meaning. */
14
+ export function consolePresentation(kernel: KernelRegistry, scope: Scope, authority: ConsoleAuthorization) {
15
+ const config = kernel.config
16
+ const { canRead, read, write, literals, relation, predicate } = authority
17
+ function fieldUI<T extends ConsoleFieldDisplay>(entity: string, ui: T): T {
18
+ const signedBy = ui.signedBy
19
+ return { ...pick(ui, ['hidden', 'kind', 'span', 'section']),
20
+ ...('format' in ui && ui.format === 'identifier' ? { format: 'identifier' } : {}),
21
+ ...(signedBy && literals(entity, signedBy.field) ? { signedBy: pick(signedBy, ['field', 'negativeValue']) } : {}) } as T
22
+ }
23
+ function display(entity: string, source: ConsoleEntityDisplay): ConsoleEntityDisplay {
24
+ const readable = (field: string) => read(entity, field)
25
+ const operand = (field: string) => literals(entity, field)
26
+ const fields = (values: string[]) => values.filter(readable)
27
+ const itemAllowed = (item: ConsoleDetailItem) => typeof item === 'string' ? readable(item) : readable(item.field) && (!item.when || operand(item.when.field))
28
+ const detailItems = (items: ConsoleDetailItem[]) => items.filter(itemAllowed).map(item => typeof item === 'string' ? item : {
29
+ ...pick(item, ['field', 'label', 'help']), ...(item.when ? { when: pick(item.when, ['field', 'eq']) } : {}),
30
+ })
31
+ const result: ConsoleEntityDisplay = {}
32
+ if (source.lookup !== undefined) result.lookup = source.lookup
33
+ if (source.fields) result.fields = Object.fromEntries(Object.entries(source.fields).filter(([field]) => readable(field)).map(([field, ui]) => [field, fieldUI(entity, ui)]))
34
+ if (source.views) result.views = source.views.filter(view => [view.startField, view.endField, view.titleField, ...view.titleFields ?? [], view.secondaryField].every(field => !field || readable(field))).map(view => pick(view, ['kind', 'startField', 'endField', 'titleField', 'titleFields', 'secondaryField']))
35
+ if (source.list) {
36
+ const list = source.list
37
+ const relatedColumns = Object.fromEntries(Object.entries(list.relatedColumns ?? {}).filter(([, column]) => {
38
+ const target = config.entities[entity].fields[column.via]?.entity
39
+ const end = target && config.entities[target]?.fields[column.field]?.entity
40
+ return readable(column.via) && target && read(target, column.field) && end && read(end, 'id')
41
+ }).map(([key, column]) => [key, pick(column, ['via', 'field'])]))
42
+ const column = (field: string) => readable(field) || Object.hasOwn(relatedColumns, field)
43
+ result.list = {
44
+ ...pick(list, ['pageSize', 'compact', 'mobileCards']),
45
+ ...(list.defaultSort && operand(list.defaultSort.key) ? { defaultSort: pick(list.defaultSort, ['key', 'direction']) } : {}),
46
+ ...(list.relatedColumns ? { relatedColumns } : {}),
47
+ ...(list.columns ? { columns: list.columns.filter(column) } : {}),
48
+ ...(list.search ? { search: list.search.filter(operand) } : {}),
49
+ ...(list.filter ? { filter: Object.fromEntries(Object.entries(list.filter).filter(([field]) => operand(field))) } : {}),
50
+ ...(list.sort ? { sort: Object.fromEntries(Object.entries(list.sort).filter(([field, hint]) => operand(field) && (!hint || hint.fields.every(operand))).map(([field, hint]) => [field, hint && { fields: [...hint.fields] }])) } : {}),
51
+ ...(list.views ? { views: list.views.filter(view => predicate(entity, view.where)).map(view => pick(view, ['id', 'label', 'where', 'default'])) } : {}),
52
+ }
53
+ if (list.defaultSort && (!operand(list.defaultSort.key) || list.sort?.[list.defaultSort.key] && !result.list.sort?.[list.defaultSort.key])) delete result.list.defaultSort
54
+ }
55
+ if (source.form) result.form = Object.fromEntries(Object.entries(source.form).flatMap(([key, form]) => {
56
+ if (key !== 'create' && key !== 'edit') return []
57
+ const operation = key === 'create' ? 'create' : 'update'
58
+ return authority.operation(entity, operation) ? [[key, { fields: form.fields.filter(field => {
59
+ const through = relation(entity, field)?.through
60
+ return write(entity, field, operation) || through && [through.createCommand, through.deleteCommand].every(authority.command)
61
+ }) }]] : []
62
+ }))
63
+ if (source.sections) result.sections = source.sections.map(section => ({ ...pick(section, ['id', 'label']), fields: section.fields.filter(field => readable(field) || !!relation(entity, field)?.through) })).filter(section => section.fields.length)
64
+ if (source.detail) {
65
+ const detail = source.detail
66
+ const lists = Object.fromEntries(Object.entries(detail.lists ?? {}).filter(([, list]) => read(entity, 'id') && read(list.entity, list.bind.field)).map(([key, list]) => [key, {
67
+ ...pick(list, ['entity', 'label']), bind: pick(list.bind, ['field', 'record']), ...(list.columns ? { columns: list.columns.filter(field => read(list.entity, field)) } : {}),
68
+ ...(list.create !== undefined ? { create: list.create && write(list.entity, list.bind.field, 'create') } : {}),
69
+ }]))
70
+ const relations = Object.fromEntries(Object.entries(detail.relations ?? {}).flatMap(([key, hint]) => {
71
+ const target = relation(entity, key)?.entity
72
+ if (!target) return []
73
+ const defaultSort = hint.defaultSort
74
+ return [[key, { columns: hint.columns.filter(field => read(target, field)), ...(defaultSort && literals(target, defaultSort.key) ? { defaultSort: pick(defaultSort, ['key', 'direction']) } : {}) }]]
75
+ }))
76
+ const card = (key: string) => Object.hasOwn(lists, key) || !!relation(entity, key)
77
+ result.detail = {
78
+ ...(detail.inlineEdit !== undefined && authority.operation(entity, 'update') ? { inlineEdit: detail.inlineEdit } : {}),
79
+ ...(detail.lists ? { lists } : {}),
80
+ ...(detail.relations ? { relations } : {}),
81
+ ...(detail.fields ? { fields: fields(detail.fields) } : {}),
82
+ ...(detail.summary ? { summary: detailItems(detail.summary) } : {}),
83
+ ...(detail.groups ? { groups: detail.groups.map(group => ({ ...pick(group, ['id', 'label', 'help']), fields: detailItems(group.fields) })).filter(group => group.fields.length) } : {}),
84
+ ...(detail.metrics ? { metrics: detail.metrics.filter(metric => readable(metric.field) && (!metric.unitField || readable(metric.unitField))).map(metric => pick(metric, ['field', 'unitField', 'tone'])) } : {}),
85
+ ...(detail.sections ? { sections: detail.sections.map(section => section.row ? { row: section.row.filter(card) } : { fields: 'info' as const }).filter(section => !section.row || section.row.length) } : {}),
86
+ }
87
+ }
88
+ return result
89
+ }
90
+ const permits = authority.grant
91
+ function modelUI(source: ConsoleModelUI): ConsoleModelUI {
92
+ const entities = Object.fromEntries(Object.entries(source.entities ?? {}).filter(([entity]) => canRead(entity)).map(([entity, hints]) => [entity, display(entity, hints)]))
93
+ const navigation = source.navigation
94
+ const items = navigation?.items.filter(item => canRead(item.entity) && !item.hidden && (!item.roles || item.roles.includes(scope.role))
95
+ && (!item.view || entities[item.entity]?.list?.views?.some(view => view.id === item.view)))
96
+ return {
97
+ ...(source.defaultLanguage ? { defaultLanguage: source.defaultLanguage } : {}),
98
+ ...(source.entities ? { entities } : {}),
99
+ ...(navigation ? { navigation: { ...(navigation.routes ? { routes: navigation.routes.map(route => pick(route, ['id', 'icon', 'order'])) } : {}),
100
+ items: items!.map(item => pick(item, ['id', 'entity', 'label', 'icon', 'group', 'order', 'roles', 'view', 'hidden'])),
101
+ groups: navigation.groups.filter(group => items!.some(item => item.group === group.id)).map(group => pick(group, ['id', 'label', 'order', 'icon'])) } } : {}),
102
+ }
103
+ }
104
+ function registry(source: ConsoleRegistry): ConsoleRegistry {
105
+ const entities = Object.fromEntries(Object.entries(source.entities).filter(([entity]) => canRead(entity)).map(([entity, hints]) => [entity, display(entity, hints)]))
106
+ const pages = source.pages.filter(page => permits(page.grant)).flatMap(page => {
107
+ const safePage = { ...pick(page, ['id', 'label', 'path', 'renderer']), ...(page.grant ? { grant: safeGrant(page.grant) } : {}) }
108
+ if (!page.widgets) return [safePage]
109
+ const widgets = page.widgets.flatMap((widget): ConsoleWidget[] => {
110
+ if (!canRead(widget.query.entity)) return []
111
+ const input = widget.kind === 'stat' ? { ...widget.query, select: widget.aggregate.fn === 'sum' ? ['id', widget.aggregate.field] : ['id'], limit: 1 } : widget.query
112
+ const query = authority.query(input)
113
+ if (!query || query.include || query.cursor || 'contextList' in input) return []
114
+ const fieldAllowed = (field: string) => !!query.select?.includes(field) && read(query.entity, field)
115
+ || !!query.labels?.includes(field) && authority.label(query.entity, field)
116
+ const common = pick(widget, ['id', 'label'])
117
+ if (widget.kind === 'stat') return [{ ...common, kind: 'stat', query: pick(query, ['entity', 'where']),
118
+ aggregate: widget.aggregate.fn === 'count' ? { fn: 'count' } : { fn: 'sum', field: widget.aggregate.field } }]
119
+ const safeQuery = { ...pick(query, ['entity', 'where', 'limit', 'select', 'labels', 'search', 'labelWhere', 'orderBy']), select: query.select! }
120
+ if (widget.kind === 'table' && widget.columns.every(fieldAllowed)) return [{ ...common, kind: 'table', query: safeQuery, columns: [...widget.columns] }]
121
+ if (widget.kind === 'list' && fieldAllowed(widget.field)) return [{ ...common, kind: 'list', query: safeQuery, field: widget.field }]
122
+ return []
123
+ })
124
+ return widgets.length ? [{ ...safePage, widgets, ...(page.sections ? { sections: page.sections.map(section => ({ row: section.row.filter(id => widgets.some(widget => widget.id === id)) })).filter(section => section.row.length) } : {}) }] : []
125
+ })
126
+ return {
127
+ entities, pages,
128
+ navigation: source.navigation.filter(item => !!item.page !== !!item.entity && permits(item.grant) && (!item.roles || item.roles.includes(scope.role)) && (!item.page || pages.some(page => page.id === item.page))
129
+ && (!item.entity || canRead(item.entity) && (!item.view || entities[item.entity]?.list?.views?.some(view => view.id === item.view)))).map(item => ({ ...pick(item, ['id', 'placement', 'label', 'icon', 'order', 'roles', 'page', 'entity', 'view']),
130
+ ...(item.grant ? { grant: safeGrant(item.grant) } : {}),
131
+ ...(item.group ? { group: pick(item.group, ['id', 'label', 'order', 'icon']) } : {}) })),
132
+ ...(source.modelUi ? { modelUi: modelUI(source.modelUi) } : {}),
133
+ }
134
+ }
135
+ return { fieldUI, display, modelUI, registry }
136
+ }
package/src/console.ts CHANGED
@@ -17,8 +17,8 @@ export async function buildInfo(config: Pick<InstanceConfig, 'revision'>, env: R
17
17
  return { sha: sha ?? 'unbuilt', builtAt: builtAt ?? 'unbuilt', revision: config.revision }
18
18
  }
19
19
  function isConsolePath(path: string) {
20
- return !(/^\/(api|auth|mcp|internal|ops|admin|commands|workflows|query|orgs|invitations|audit|me|health|schema|bootstrap|build\.json)(\/|$)/.test(path)
21
- || /^\/o\/[^/]+\/(bootstrap|capabilities|console-registry|console-pages|config-versions)(\/|$)/.test(path))
20
+ return !(/^\/(api|auth|mcp|internal|ops|admin|commands|workflows|query|orgs|invitations|audit|me|health|schema|console-info|bootstrap|build\.json)(\/|$)/.test(path)
21
+ || /^\/o\/[^/]+\/(bootstrap|capabilities|console-model|console-registry|console-pages|config-versions)(\/|$)/.test(path))
22
22
  }
23
23
 
24
24
  async function serveConsole(request: Request, env: RuntimeEnv) {
@@ -63,7 +63,7 @@ export type Rule<Input, Prepared = undefined> = (ctx: PlanningContext<Prepared>,
63
63
  export interface AtomicOperation<Schema extends z.ZodType = z.ZodType, Prepared = any> {
64
64
  name: string
65
65
  /** Public presentation only; never grants authority or changes execution. */
66
- ui?: { labelKey?: string; label?: string | { en: string; cs: string }; replacesCrud?: 'create' | 'update' | 'delete' }
66
+ ui?: { placement?: { entity: string; action: 'create' }; labelKey?: string; label?: string | { en: string; cs: string }; replacesCrud?: 'create' | 'update' | 'delete' }
67
67
  permission: { entity: string; operation: Operation } | { system: OrganizationAction | 'organizations.create' | 'members.leave' | 'invitations.accept' | 'identity.write' }
68
68
  additionalPermissions?: readonly { entity: string; operation: Operation }[]
69
69
  input: Schema
package/src/index.ts CHANGED
@@ -16,7 +16,7 @@ export * from './authorization-api'
16
16
  export * from './identity'
17
17
 
18
18
  export * from "./authorized-execution"
19
- export * from './execution'
19
+ export * from './execution/index'
20
20
  export * from './identity-providers'
21
21
 
22
22
  export * from './workflow-runtime'
@@ -0,0 +1,206 @@
1
+ # @workbasehq/core/infra
2
+
3
+ SST Cloudflare provisioning, migration and schema tooling for Node deployment
4
+ scripts, isolated from core's Worker runtime entry. The public SDK remains three
5
+ packages: core, plugins, mcp. SST and Pulumi are optional peers used only by the
6
+ provisioner; migrations and dry plans need only the optional `tsx` loader at runtime.
7
+ Migration-only imports from `@workbasehq/core/infra` also typecheck without deployment
8
+ peers. The deployment API lives in `@workbasehq/core/infra/provision`.
9
+
10
+ ## SST provisioner
11
+
12
+ ```ts
13
+ provision(options: ProvisionOptions): Promise<ProvisionResult>
14
+ createProvisionPlan(options: ProvisionOptions): Promise<ProvisionPlan>
15
+ ```
16
+
17
+ Install the tested deployment tools explicitly (Node 22+, TypeScript 5.7+):
18
+
19
+ ```sh
20
+ npm install @workbasehq/core
21
+ npm install -D sst@4.17.1 tsx@4.23.15
22
+ ```
23
+
24
+ Use Cloudflare provider `6.19.0` in `sst.config.ts`. SST's pinned Pulumi version
25
+ supports TypeScript <6; the packed consumer check uses TypeScript 5.7.2.
26
+ With all three SDK packages installed, mcp supplies `tsx` transitively, so only
27
+ `sst` is needed as an additional deployment dependency. Do not install Pulumi or
28
+ the command provider for provisioning: resources and secrets use SST's injected
29
+ globals, and migrations use the command provider resolved from `$cli.paths.platform`.
30
+ SST 4.17.1 supplies command 1.0.1 and Pulumi 3.215.0 there. The provisioner verifies
31
+ that command resolves the same Pulumi module as the platform before loading it;
32
+ it does not force a separate command provider version. Optional Pulumi peers are
33
+ only for consumers that need their types directly.
34
+
35
+ ```ts
36
+ /// <reference path="./.sst/platform/config.d.ts" />
37
+ export default $config({
38
+ app(input) {
39
+ return {
40
+ name: 'neutral-instance', home: 'cloudflare',
41
+ providers: { cloudflare: '6.19.0' },
42
+ removal: input.stage === 'production' ? 'retain' : 'remove',
43
+ protect: input.stage === 'production',
44
+ }
45
+ },
46
+ async run() {
47
+ const { provision } = await import('@workbasehq/core/infra/provision')
48
+ const deployed = await provision({
49
+ configPath: './config.ts', handler: './worker.ts', migrationsDir: './migrations',
50
+ resourcePrefix: 'neutral-instance', stage: $app.stage,
51
+ authSecret: new sst.Secret('AuthSecret').value,
52
+ authBaseUrl: process.env.AUTH_BASE_URL!,
53
+ })
54
+ return { url: deployed.url, databaseId: deployed.databaseId }
55
+ },
56
+ })
57
+ ```
58
+
59
+ The operator supplies `CLOUDFLARE_DEFAULT_ACCOUNT_ID`, `CLOUDFLARE_API_TOKEN`,
60
+ `AUTH_BASE_URL` and a stable SST `AuthSecret` before deployment. The auth secret
61
+ must be at least 32 characters; retain it across redeployments. `authBaseUrl` is
62
+ the exact public HTTPS origin, without credentials, query, fragment or a path.
63
+ Use the known workers.dev origin or supply `domain` with the same hostname.
64
+ The API does not discover the account subdomain or generate an auth secret.
65
+
66
+ | Input | Contract |
67
+ | --- | --- |
68
+ | `configPath`, `handler`, `migrationsDir` | Required application-owned module, Worker entry and ordered SQL directory |
69
+ | `resourcePrefix`, `stage` | Required lowercase DNS-style names; prefix ≤63, stage ≤32 characters |
70
+ | `authSecret`, `authBaseUrl` | Required stable `Input<string>` secret and explicit HTTPS origin |
71
+ | `assetsDir?` | Existing prebuilt console directory; absent means no `ASSETS` binding |
72
+ | `domain?` | Optional Cloudflare custom hostname matching the auth origin |
73
+ | `email?: { from }` | Native `EMAIL` send binding restricted to this sender, plus `EMAIL_FROM` |
74
+ | `webhook?: { url, allowedHosts, service?, events? }` | Explicit URL/host allowlist, optional existing Worker service name and event filter |
75
+ | `internalToken?` | Optional secret `INTERNAL_TOKEN` for protected operations |
76
+ | `accountId?`, `projectRoot?` | Override account environment value or path root; SST normally runs in the app root |
77
+ | `protect?` | Protect/retain primary resources; defaults to true for `production` |
78
+ | `migrationTriggers?` | Extra fingerprints for imported application/plugin verification code |
79
+
80
+ Config modules are trusted application code. Relative paths resolve from
81
+ `projectRoot`, defaulting to `process.cwd()` (the app root inside SST). Secrets
82
+ accept Pulumi Outputs/SST secret values and are marked secret in Pulumi state.
83
+ No secret or webhook destination is included in the dry plan. `ProvisionDiagnostic`
84
+ and `provisionErrorMessage()` expose fixed branded codes, never arbitrary exception
85
+ text or input values.
86
+
87
+ The graph creates D1 `DB`, KV `AUDIT_KV`, `EVENTS_QUEUE`, a DLQ, a consumer on the
88
+ same Worker and the relay cron `*/5 * * * *`. Assets run through the Worker first,
89
+ with native HTML/not-found handling disabled, so the runtime controls auth/CSP and
90
+ SPA fallback. The caller's handler must export fetch, queue and scheduled handlers
91
+ composed with its instance config. This API does not build console assets or create
92
+ a webhook receiver/landing Worker. All physical names and Pulumi logical names
93
+ include the prefix/stage identity; long names retain a deterministic tuple hash.
94
+ Worker names fit SST's 54-character workers.dev limit; other names fit 63 characters.
95
+
96
+ The packaged `workbase-migrate` entry runs SQL and plugin migrations/verification
97
+ before the Worker component **and** the underlying script upload. Inputs travel
98
+ through quoted environment variables; credentials are inherited by the subprocess.
99
+ SQL-chain hash, expected schema, package sources and config source fingerprint the
100
+ migration command; use `migrationTriggers` when imported application verifier code
101
+ changes independently. The migration command is unprotected so trigger changes can
102
+ replace it, while production D1 and other primary resources remain protected.
103
+ The Worker receives the corresponding `SCHEMA_EXPECTED`.
104
+ Migration failure blocks upload. A stable prefix/stage reuses resource addresses
105
+ and receipts; changing either creates a separate instance.
106
+
107
+ `ProvisionResult` contains URL/ID/name Outputs and resource handles for further
108
+ composition. Return only selected Outputs from SST `run()`. `createProvisionPlan`
109
+ evaluates the trusted config and local files without registering resources,
110
+ executing migration commands, contacting Cloudflare or requiring SST/Pulumi.
111
+
112
+ ### Account state and operational prerequisites
113
+
114
+ SST 4.17.1 Cloudflare home uses the shared account-level R2 `sst-state` bucket
115
+ ([pinned implementation](https://github.com/sst/sst/blob/v4.17.1/pkg/project/provider/cloudflare.go)).
116
+ Arrange account/state access and any required exception before deploying. Resource
117
+ prefixes isolate application resources; they do not isolate this state bucket.
118
+ This provisioner does not change SST state storage.
119
+
120
+ Email requires an authorized Cloudflare sender. With magic-link login, configure
121
+ working email delivery or another supported transport even on workers.dev. Omitting
122
+ `email` does not provide a substitute login transport. Omitting `assetsDir` leaves
123
+ the API available while the runtime reports `console_not_built` for the console.
124
+
125
+ Offline tests verify the graph, dependency ordering and installed package bytes.
126
+ Actual deploy, login, redeploy/data retention, queue/cron delivery and stage removal
127
+ require a separately authorized account-level acceptance run.
128
+
129
+ ## Remote migrations
130
+
131
+ Install core and its optional CLI loader, with Node 22+:
132
+
133
+ ```sh
134
+ npm install @workbasehq/core tsx@4.23.15
135
+ export CLOUDFLARE_DEFAULT_ACCOUNT_ID=...
136
+ export CLOUDFLARE_API_TOKEN=...
137
+ workbase-migrate migrate <databaseId> ./migrations --config ./config.ts
138
+ ```
139
+
140
+ The trusted config module must default-export an `InstanceConfig` and can import
141
+ public core/plugin packages and the application's own plugins. Relative input
142
+ paths resolve from the caller's working directory. The CLI resolves the TypeScript
143
+ loader relative to the installed package. There is no instance registry or config
144
+ discovery. Worker consumers can omit the optional `tsx` peer.
145
+
146
+ Omit `--config` for a plain SQL database. With a config, migration verifies the SQL
147
+ ledger and instance revision/core version, applies plugin migrations, and verifies
148
+ their ledger and schema hooks. SQL must already contain the matching
149
+ `instance_meta` revision and core version.
150
+
151
+ Files must be contiguous `0001_name.sql`, `0002_name.sql`, etc. Each SQL file and
152
+ its receipt execute in one D1 HTTP transaction. Changed or missing historical SQL,
153
+ retroactive insertion and changed plugin receipts fail closed. An unchanged chain
154
+ can be reapplied without changing existing receipts. The CLI preserves the
155
+ `infra.migrations.applied` JSON event and suppresses arbitrary transport/config/
156
+ plugin error text to avoid exposing credentials or application data.
157
+
158
+ ## API
159
+
160
+ Migration helpers are exported from `@workbasehq/core/infra`:
161
+
162
+ | Exports | Purpose |
163
+ | --- | --- |
164
+ | `migrateD1`, `Migration`, `D1Query`, `QueryResult` | SQL migration ledger |
165
+ | `httpD1Query` | HTTP adapter (optional fetch adapter for tests) |
166
+ | `migrateInstance`, `queryDatabase` | Instance/plugin migration verification |
167
+ | `readMigrationFiles`, `migrationHash`, `sha256` | File loading and hashing |
168
+ | `expectedSchema`, `ExpectedSchemaOptions` | Expected schema bindings |
169
+ | `runCli`, `migrationErrorMessage` | CLI helpers |
170
+
171
+ Deployment helpers are exported from `@workbasehq/core/infra/provision`:
172
+
173
+ | Exports | Purpose |
174
+ | --- | --- |
175
+ | `provision`, `ProvisionOptions`, `ProvisionResult` | Explicit-input SST Cloudflare resource graph |
176
+ | `createProvisionPlan`, `ProvisionPlan`, `validateProvisionOptions` | Offline input validation and secret-free dry mapping |
177
+ | `ProvisionDiagnostic`, `provisionErrorMessage` | Safe typed provisioning diagnostics |
178
+
179
+ ```ts
180
+ import { expectedSchema } from '@workbasehq/core/infra'
181
+ import config from './config'
182
+
183
+ const schema = await expectedSchema({
184
+ migrationsDirectory: './migrations', revision: config.revision, config,
185
+ })
186
+ // Supply JSON.stringify(schema) as the Worker's SCHEMA_EXPECTED binding.
187
+ ```
188
+
189
+ For non-Workbase databases, omit `config` and pass an explicit `coreVersion` if
190
+ needed. This subpath supplies no owner domains or hosted integration defaults.
191
+
192
+ Tests live in `packages/core/test/infra` and use `vitest.infra.config.ts`. The packed
193
+ CLI test runs `npm pack` on staged core bytes, installs the tarball outside the repo,
194
+ and exercises D1 HTTP against transactional SQLite through a fetch fixture. It
195
+ also typechecks a migration-only consumer before installing deployment peers,
196
+ imports and dry-plans provisioning without SST/Pulumi, typechecks a consumer
197
+ `provision()` call, runs the emitted migration command and executes an SST-style
198
+ bundle from the consumer's `.sst/platform` directory.
199
+
200
+ `bash scripts/sdk-pack.sh && bun run test:sdk-sst` installs the three packed SDK
201
+ packages plus SST in a clean directory and runs real `sst diff` previews with
202
+ local state, dummy credentials and Cloudflare API URLs pointed at loopback. It
203
+ checks every resource (including the Worker/custom domain/migration/consumer/cron)
204
+ and verifies that loaded Pulumi/command modules belong to SST's platform, then
205
+ repeats with conflicting consumer Pulumi/command dependencies installed. CI `check`
206
+ runs this regression alongside `test:infra`.
@@ -0,0 +1,19 @@
1
+ #!/usr/bin/env node
2
+ import { createRequire } from 'node:module'
3
+ import { spawnSync } from 'node:child_process'
4
+ import { fileURLToPath, pathToFileURL } from 'node:url'
5
+
6
+ // Resolve both the TypeScript loader and CLI relative to this installed package.
7
+ const require = createRequire(import.meta.url)
8
+ let loader
9
+ try { loader = require.resolve('tsx/esm') }
10
+ catch {
11
+ console.error('workbase-migrate requires tsx; install tsx@4.23.15')
12
+ process.exit(1)
13
+ }
14
+ const result = spawnSync(process.execPath, [
15
+ '--import', pathToFileURL(loader).href,
16
+ fileURLToPath(new URL('./cli-main.ts', import.meta.url)), ...process.argv.slice(2),
17
+ ], { stdio: 'inherit' })
18
+ if (result.error) console.error('migration_failed')
19
+ process.exitCode = result.status ?? 1
@@ -0,0 +1,8 @@
1
+ import { runCli, migrationErrorMessage } from './cli'
2
+
3
+ // Executable entry only. Keeping this out of the /infra import graph prevents
4
+ // import.meta.url === argv[1] from accidentally running the CLI in an SST bundle.
5
+ const env = { ...process.env }
6
+ runCli(process.argv.slice(2), env).catch(error => {
7
+ console.error(migrationErrorMessage(error, env)); process.exitCode = 1
8
+ })
@@ -0,0 +1,43 @@
1
+ import { resolve } from 'node:path'
2
+ import { pathToFileURL } from 'node:url'
3
+ import { KernelRegistry } from '../kernel/registry'
4
+ import type { InstanceConfig } from '../config'
5
+ import { migrateD1 } from './d1-migrations'
6
+ import { httpD1Query } from './http-d1'
7
+ import { migrateInstance } from './instance-migrations'
8
+ import { readMigrationFiles } from './migration-files'
9
+ import { internalMigrationMessage, MigrationDiagnostic, redactCliOutput } from './diagnostics'
10
+
11
+ /** Config modules are trusted application code and must default-export an InstanceConfig. */
12
+ export async function runCli(args: readonly string[], env: NodeJS.ProcessEnv = process.env) {
13
+ env = { ...env }
14
+ const [command, database, directory, option, configPath, ...extra] = args
15
+ const account = env.CLOUDFLARE_DEFAULT_ACCOUNT_ID; const token = env.CLOUDFLARE_API_TOKEN
16
+ if (command !== 'migrate' || !database || !directory || !account || !token || extra.length ||
17
+ (option !== undefined && (option !== '--config' || !configPath)) || (!option && configPath)) throw new MigrationDiagnostic({ code: 'usage' })
18
+ const query = httpD1Query(account, database, token)
19
+ // Load and validate configuration before the first database mutation.
20
+ const config: InstanceConfig | undefined = configPath ? (await import(pathToFileURL(resolve(configPath)).href)).default : undefined
21
+ if (configPath && !config) throw new MigrationDiagnostic({ code: 'invalid_config_default_export' })
22
+ const kernel = config ? new KernelRegistry(config) : undefined
23
+ const files = await readMigrationFiles(directory)
24
+ const result = kernel ? await migrateInstance(query, files, kernel) : await migrateD1(query, files)
25
+ console.log(redactCliOutput(JSON.stringify({ event: 'infra.migrations.applied', database, ...result }), env))
26
+ return result
27
+ }
28
+
29
+ /** Only branded internal diagnostics carry text; external errors get a fixed class label. */
30
+ export function migrationErrorMessage(error: unknown, env: NodeJS.ProcessEnv = process.env): string {
31
+ let message = internalMigrationMessage(error)
32
+ if (message === undefined) {
33
+ let name = 'UnknownError'
34
+ try {
35
+ // Never read an external error's message, name, code, cause or stack.
36
+ for (const type of [TypeError, RangeError, SyntaxError, ReferenceError, URIError, EvalError, AggregateError, Error]) {
37
+ if (error instanceof type) { name = type.name; break }
38
+ }
39
+ } catch { /* A thrown Proxy may also reject prototype inspection. */ }
40
+ message = `migration_failed:${name}`
41
+ }
42
+ return redactCliOutput(message, env)
43
+ }
@@ -0,0 +1,30 @@
1
+ import { MigrationDiagnostic } from './diagnostics'
2
+ // Shared by the HTTP CLI and SQLite contract tests. One API batch per file, including its receipt.
3
+ export interface Migration { filename: string; sql: string; checksum: string }
4
+ export interface QueryResult { success: boolean; results?: Record<string, unknown>[] }
5
+ export type D1Query = (sql: string) => Promise<QueryResult[]>
6
+ const literal = (value: string) => `'${value.replaceAll("'", "''")}'`
7
+ export async function migrateD1(query: D1Query, input: readonly Migration[]) {
8
+ const migrations = [...input].sort((a, b) => a.filename < b.filename ? -1 : a.filename > b.filename ? 1 : 0)
9
+ if (new Set(migrations.map(m => m.filename)).size !== migrations.length) throw new MigrationDiagnostic({ code: 'duplicate_migration_filename' })
10
+ const execute: D1Query = async sql => {
11
+ const results = await query(sql)
12
+ if (!results.length || results.some(r => !r.success)) throw new MigrationDiagnostic({ code: 'd1_query_failed' })
13
+ return results
14
+ }
15
+ await execute('CREATE TABLE IF NOT EXISTS _migrations (filename TEXT PRIMARY KEY, applied_at TEXT NOT NULL, checksum TEXT NOT NULL);')
16
+ const applied = (await execute('SELECT filename, checksum FROM _migrations ORDER BY filename;'))[0].results ?? []
17
+ const known = new Map(migrations.map(m => [m.filename, m]))
18
+ for (const row of applied) {
19
+ if (known.get(String(row.filename))?.checksum !== row.checksum) throw new MigrationDiagnostic({ code: 'migration_history_mismatch', filename: row.filename })
20
+ }
21
+ const done = new Set(applied.map(row => String(row.filename)))
22
+ // Inserting a new migration before an already-applied file would violate the ordered chain.
23
+ const last = [...done].sort().at(-1)
24
+ for (const migration of migrations) {
25
+ if (done.has(migration.filename)) continue
26
+ if (last && migration.filename < last) throw new MigrationDiagnostic({ code: 'migration_out_of_order', filename: migration.filename })
27
+ await execute(`${migration.sql}\n;\nINSERT INTO _migrations (filename,applied_at,checksum) VALUES (${literal(migration.filename)},strftime('%Y-%m-%dT%H:%M:%fZ','now'),${literal(migration.checksum)});`)
28
+ }
29
+ return { applied: migrations.length - done.size, total: migrations.length }
30
+ }
@@ -0,0 +1,52 @@
1
+ const messages = {
2
+ usage: 'usage: workbase-migrate migrate <database-id> <migration-directory> [--config <module-path>]; requires CLOUDFLARE_DEFAULT_ACCOUNT_ID and CLOUDFLARE_API_TOKEN',
3
+ invalid_config_default_export: 'invalid_config_default_export',
4
+ invalid_cloudflare_ids: 'invalid_cloudflare_ids',
5
+ duplicate_migration_filename: 'duplicate_migration_filename',
6
+ d1_query_failed: 'd1_query_failed',
7
+ d1_api_failed: 'd1_api_failed',
8
+ invalid_ledger_statement: 'invalid_ledger_statement',
9
+ invalid_ledger_bindings: 'invalid_ledger_bindings',
10
+ migration_instance_verification_failed: 'migration_instance_verification_failed',
11
+ migration_instance_revision_mismatch: 'migration_instance_revision_mismatch',
12
+ migration_plugin_verification_failed: 'migration_plugin_verification_failed',
13
+ no_migrations: 'no_migrations',
14
+ } as const
15
+
16
+ type Diagnostic = { code: keyof typeof messages }
17
+ | { code: 'd1_http_status'; status: number }
18
+ | { code: 'migration_history_mismatch' | 'migration_out_of_order' | 'invalid_migration_filename' | 'migration_sequence_gap_or_duplicate'; filename: unknown }
19
+
20
+ const filenameCodes = new Set(['migration_history_mismatch', 'migration_out_of_order', 'invalid_migration_filename', 'migration_sequence_gap_or_duplicate'])
21
+
22
+ // The brand and saved text cannot be forged by setting Error.name/message/prototype.
23
+ const diagnostics = new WeakMap<object, string>()
24
+ export class MigrationDiagnostic extends Error {
25
+ constructor(diagnostic: Diagnostic) {
26
+ let message: string
27
+ if (diagnostic.code === 'd1_http_status') {
28
+ const status = diagnostic.status
29
+ message = `d1_http_status${Number.isInteger(status) && status >= 100 && status <= 599 ? `:${status}` : ''}`
30
+ } else if ('filename' in diagnostic && filenameCodes.has(diagnostic.code)) {
31
+ const filename = diagnostic.filename
32
+ // Filesystem paths and arbitrary ledger/API values are not safe diagnostics.
33
+ message = diagnostic.code + (typeof filename === 'string' && /^[0-9]{4}_[a-zA-Z0-9_-]{1,200}\.sql$/.test(filename) && !filename.includes('\n') ? `:${filename}` : '')
34
+ } else {
35
+ message = Object.hasOwn(messages, diagnostic.code) ? messages[diagnostic.code as keyof typeof messages] : 'migration_failed'
36
+ }
37
+ super(message)
38
+ diagnostics.set(this, message)
39
+ }
40
+ }
41
+
42
+ export function internalMigrationMessage(error: unknown): string | undefined {
43
+ return typeof error === 'object' && error !== null ? diagnostics.get(error) : undefined
44
+ }
45
+
46
+ /** Redact literal and JSON-escaped values, including secrets in otherwise safe fields. */
47
+ export function redactCliOutput(text: string, env: NodeJS.ProcessEnv): string {
48
+ const secrets = Object.entries(env).filter(([name, value]) => value && /TOKEN|SECRET|PASSWORD|PASSWD|API_?KEY|PRIVATE_?KEY|ACCESS_?KEY|CREDENTIAL/i.test(name))
49
+ .flatMap(([, value]) => [value!, JSON.stringify(value!).slice(1, -1)])
50
+ for (const secret of [...new Set(secrets)].sort((a, b) => b.length - a.length)) text = text.replaceAll(secret, '[redacted]')
51
+ return text
52
+ }
@@ -0,0 +1,17 @@
1
+ import { MigrationDiagnostic } from './diagnostics'
2
+ import type { D1Query, QueryResult } from './d1-migrations'
3
+
4
+ export function httpD1Query(account: string, database: string, token: string, fetcher = fetch): D1Query {
5
+ if (!/^[a-f0-9]{32}$/.test(account) || !/^[a-f0-9-]{36}$/.test(database)) throw new MigrationDiagnostic({ code: 'invalid_cloudflare_ids' })
6
+ return async sql => {
7
+ const response = await fetcher(`https://api.cloudflare.com/client/v4/accounts/${account}/d1/database/${database}/query`, {
8
+ method: 'POST', headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
9
+ body: JSON.stringify({ sql }), signal: AbortSignal.timeout(60000),
10
+ })
11
+ // Never print API bodies, SQL or headers: they can contain credentials or customer data.
12
+ if (!response.ok) throw new MigrationDiagnostic({ code: 'd1_http_status', status: response.status })
13
+ const body = await response.json() as { success: boolean; result: QueryResult[] }
14
+ if (!body.success || !Array.isArray(body.result)) throw new MigrationDiagnostic({ code: 'd1_api_failed' })
15
+ return body.result
16
+ }
17
+ }
@@ -0,0 +1,6 @@
1
+ export * from './d1-migrations'
2
+ export * from './http-d1'
3
+ export * from './instance-migrations'
4
+ export * from './migration-files'
5
+ export * from './schema'
6
+ export { runCli, migrationErrorMessage } from './cli'
@@ -0,0 +1,54 @@
1
+ import { MigrationDiagnostic } from './diagnostics'
2
+ import { CORE_VERSION } from '../config'
3
+ import { hashMigrationRows } from '../schema-compatibility'
4
+ import { literal } from '../migrations/schema'
5
+ import { pluginMigrationStatus } from '../kernel/migrations'
6
+ import type { KernelRegistry } from '../kernel/registry'
7
+ import { migrateD1, type D1Query, type Migration } from './d1-migrations'
8
+
9
+ /** D1 HTTP batches execute the migration SQL and its receipt in one transaction.
10
+ * Only ledger statements carry bindings; migration SQL is never interpolated. */
11
+ export function queryDatabase(query: D1Query): D1Database {
12
+ const execute = async (sql: string) => {
13
+ const result = await query(sql)
14
+ if (!result.length || result.some(row => !row.success)) throw new MigrationDiagnostic({ code: 'd1_query_failed' })
15
+ return result
16
+ }
17
+ const prepare = (sql: string) => {
18
+ let values: unknown[] = []
19
+ const statement = {
20
+ bind(...bindings: unknown[]) { values = bindings; return statement },
21
+ sql() {
22
+ if (!values.length) return sql
23
+ // Core's ledger queries contain only positional placeholders and no SQL
24
+ // literals. Refuse any other form instead of treating SQL as a template.
25
+ if (/[\x27\x22`]|--|\/\*/.test(sql)) throw new MigrationDiagnostic({ code: 'invalid_ledger_statement' })
26
+ let index = 0
27
+ const result = sql.replace(/\?/g, () => literal(values[index++]))
28
+ if (index !== values.length) throw new MigrationDiagnostic({ code: 'invalid_ledger_bindings' })
29
+ return result
30
+ },
31
+ async run() { return (await execute(statement.sql()))[0] },
32
+ async all() { return { results: (await execute(statement.sql()))[0].results ?? [] } },
33
+ async first(column?: string) { const row = (await statement.all()).results[0]; return column ? row?.[column] ?? null : row ?? null },
34
+ }
35
+ return statement
36
+ }
37
+ return { prepare, async batch(statements: ReturnType<typeof prepare>[]) {
38
+ return execute(statements.map(statement => statement.sql()).join(';\n') + ';')
39
+ } } as unknown as D1Database
40
+ }
41
+
42
+ export async function migrateInstance(query: D1Query, files: readonly Migration[], kernel: KernelRegistry) {
43
+ const legacy = await migrateD1(query, files)
44
+ const db = queryDatabase(query)
45
+ const rows = await db.prepare('SELECT filename,checksum FROM _migrations ORDER BY filename').all<{ filename: string; checksum: string }>()
46
+ const expectedRows = [...files].sort((a, b) => a.filename < b.filename ? -1 : a.filename > b.filename ? 1 : 0)
47
+ if (await hashMigrationRows(rows.results) !== await hashMigrationRows(expectedRows)) throw new MigrationDiagnostic({ code: 'migration_instance_verification_failed' })
48
+ const meta = await db.prepare('SELECT revision,core_version FROM instance_meta ORDER BY revision DESC LIMIT 1').first<{ revision: number; core_version: string }>()
49
+ if (meta?.revision !== kernel.config.revision || meta.core_version !== CORE_VERSION) throw new MigrationDiagnostic({ code: 'migration_instance_revision_mismatch' })
50
+ await kernel.applyMigrations(db)
51
+ const status = await pluginMigrationStatus(db, kernel.plugins, kernel.config)
52
+ if (status.expected !== status.applied) throw new MigrationDiagnostic({ code: 'migration_plugin_verification_failed' })
53
+ return { ...legacy, pluginMigrations: status.applied }
54
+ }
@@ -0,0 +1,17 @@
1
+ import { MigrationDiagnostic } from './diagnostics'
2
+ import { createHash } from 'node:crypto'
3
+ import { readdir, readFile } from 'node:fs/promises'
4
+ import { join } from 'node:path'
5
+ import type { Migration } from './d1-migrations'
6
+ export const sha256 = (text: string) => createHash('sha256').update(text).digest('hex')
7
+ export async function readMigrationFiles(directory: string): Promise<Migration[]> {
8
+ const names = (await readdir(directory)).filter(name => name.endsWith('.sql')).sort()
9
+ if (!names.length) throw new MigrationDiagnostic({ code: 'no_migrations' })
10
+ return Promise.all(names.map(async (filename, index) => {
11
+ if (!/^[0-9]{4}_[a-zA-Z0-9_-]+\.sql$/.test(filename)) throw new MigrationDiagnostic({ code: 'invalid_migration_filename', filename: filename })
12
+ if (Number(filename.slice(0, 4)) !== index + 1) throw new MigrationDiagnostic({ code: 'migration_sequence_gap_or_duplicate', filename: filename })
13
+ const sql = await readFile(join(directory, filename), 'utf8')
14
+ return { filename, sql, checksum: sha256(sql) }
15
+ }))
16
+ }
17
+ export const migrationHash = (files: readonly Migration[]) => sha256(JSON.stringify(files.map(({ filename, checksum }) => ({ filename, checksum }))))