@defrex/autobuild-hosted-dispatcher 0.9.0

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/README.md ADDED
@@ -0,0 +1,89 @@
1
+ # `@defrex/autobuild-hosted-dispatcher`
2
+
3
+ The optional package that lets a hosted deployment own the dispatch kernel: a
4
+ cron-authenticated endpoint — `GET /api/dispatch` — runs one bounded dispatcher
5
+ tick per configured repository per invocation. It drives the same core
6
+ `abDispatch` entry point a local `ab dispatch --once --repository <origin>`
7
+ pass runs — claim, provision, launch, observe, settle, merge PRs, janitor,
8
+ lease sweep — and reuses `@defrex/autobuild-hosted-store-service`'s validated
9
+ store environment for the signing secret. See the
10
+ [operator procedure](../../docs/hosted-dispatcher.md) for the schedule,
11
+ incident pauses, and behavior details.
12
+
13
+ A deployment opts into building by installing the package and mounting the
14
+ route: the Next.js app's `app/api/dispatch/route.ts` (in the hosted store
15
+ service package) imports `dispatcherEndpoint` from
16
+ `@defrex/autobuild-hosted-dispatcher/runtime` and keeps a module-scope
17
+ instance. A deployment that only hosts state does not install it and never
18
+ attempts a dispatch tick. The package peers on `@defrex/autobuild` (the core
19
+ it drives) and `@defrex/autobuild-hosted-store-service` (the environment
20
+ parser and types); a deployment that installs it adds
21
+ `bun add @defrex/autobuild-hosted-dispatcher`.
22
+
23
+ Besides the endpoint driver, the package owns two deploy-time helpers:
24
+
25
+ - the `ab-hosted-dispatcher` bin with the `pack-distribution` command, which
26
+ packs the running distribution into `<root>/.autobuild-dist/autobuild-<version>.tgz`
27
+ during the deployment build (the hosted store service's `deploy:build` runs
28
+ it by path from the package directory:
29
+ `bun ../../packages/hosted-dispatcher/src/bin.ts pack-distribution --root .`); and
30
+ - the `ship-packed-distribution` trace helper, which appends that archive to
31
+ the dispatch route's Next.js trace file so the function bundle carries it
32
+ (the same `deploy:build` runs it by path from the package directory as its
33
+ final step: `bun ../../packages/hosted-dispatcher/src/ship-packed-distribution.ts`).
34
+
35
+ ## Dispatcher environment variables
36
+
37
+ Dispatcher variables (server-only, like every secret; none reach the browser):
38
+
39
+ - `AB_DISPATCHER_ORIGIN`: the deployment's public origin, used as `AB_STORE`
40
+ for the kernel, the hosted ticket source, and guests. Absolute http(s)
41
+ origin; https required in production.
42
+ - `AB_DISPATCHER_REPOSITORIES`: comma-separated repositories the dispatcher
43
+ serves, normalized `https://` identities exactly like `AB_WEB_REPOSITORIES`.
44
+ When unset, the deployment's `AB_WEB_REPOSITORIES` set is used, so a
45
+ deployment configures its repository set once.
46
+ - `AB_DISPATCHER_BUDGET_SECONDS`: per-invocation work budget (default 240,
47
+ clamped 10–780); pair it with the route's `maxDuration` as described in the
48
+ operator procedure.
49
+ - `AB_DISPATCHER_TOKEN_TTL_SECONDS`: the TTL of the per-tick deployment
50
+ operator token minted for guests (default 604800 — 7 days; minimum 3600).
51
+ It must outlive your largest guest `timeoutSeconds` (e.g. 14400).
52
+ - `CRON_SECRET`: the cron authorization shared secret. Unset or blank disables
53
+ the endpoint entirely. It is never a signing input and is unrelated to
54
+ `AB_STORE_SECRET`.
55
+ - `GITHUB_TOKEN` or `GH_TOKEN`: the shared forge credentials the kernel (and
56
+ its publication settlement) use. They stay on the service; guests never
57
+ receive one.
58
+ - `AB_DISPATCHER_GITHUB_TOKENS`: optional per-repository forge credential
59
+ overrides — a JSON object mapping repository identities to GitHub token
60
+ material, e.g.
61
+ `{"https://github.com/acme/one":"github_pat_…","git@github.com:acme/two.git":"ghp_…"}`.
62
+ Keys accept the same spellings as the repository set and must name a served
63
+ repository; a repository with an override authenticates its dispatcher tick
64
+ with that token (both `GITHUB_TOKEN` and `GH_TOKEN`), every other repository
65
+ keeps the shared `GITHUB_TOKEN`/`GH_TOKEN`. Unset means shared-only, and a
66
+ repository with neither fails its tick — origin-mode dispatch never uses the
67
+ gh CLI login of whoever runs the service, unlike a local checkout-mode
68
+ dispatcher. Tokens
69
+ never appear in logs, responses, or artifacts; server-only like every secret
70
+ above.
71
+ - Guest-forwarded variables such as `AI_GATEWAY_API_KEY` flow through from the
72
+ service environment to the guest session untouched.
73
+ - `AB_DISTRIBUTION_ARCHIVE`: optional explicit path to the guest distribution
74
+ archive. Unset, the kernel uses the archive
75
+ `ab-hosted-dispatcher pack-distribution` wrote to `.autobuild-dist/` during
76
+ the deployment build (required for a bundled deployment, which has no `bun`
77
+ to pack with at runtime — see the operator procedure).
78
+
79
+ The Sandbox SDK authenticates with the deployment's own OIDC identity inside
80
+ Vercel functions (the `x-vercel-oidc-token` request header, forwarded to the
81
+ kernel as `VERCEL_OIDC_TOKEN` for the tick), so **no `VERCEL_TOKEN`
82
+ belongs on the service**. Each invocation deposits a
83
+ `dispatcher-effective-config` repository artifact and durable tick/run facts
84
+ under the `hosted-dispatcher-<uuid>` run id — the web dashboard shows hosted
85
+ activity exactly as it shows a local dispatcher. The repository journal's
86
+ events keep growing by roughly one tick per minute per repository (intentional);
87
+ the run/config artifacts themselves are retention-bounded — the store keeps the
88
+ latest 200 revisions per dispatcher artifact kind and prunes older revisions at
89
+ deposit time, overridable with `AB_ARTIFACT_RETENTION_MAX_REVISIONS`.
package/package.json ADDED
@@ -0,0 +1,45 @@
1
+ {
2
+ "name": "@defrex/autobuild-hosted-dispatcher",
3
+ "version": "0.9.0",
4
+ "type": "module",
5
+ "license": "Apache-2.0",
6
+ "engines": {
7
+ "bun": ">=1.4.0"
8
+ },
9
+ "exports": {
10
+ ".": {
11
+ "types": "./src/index.ts",
12
+ "import": "./src/index.ts"
13
+ },
14
+ "./dispatcher": {
15
+ "types": "./src/dispatcher.ts",
16
+ "import": "./src/dispatcher.ts"
17
+ },
18
+ "./runtime": {
19
+ "types": "./src/runtime.ts",
20
+ "import": "./src/runtime.ts"
21
+ },
22
+ "./distribution": {
23
+ "types": "./src/ship-packed-distribution.ts",
24
+ "import": "./src/ship-packed-distribution.ts"
25
+ }
26
+ },
27
+ "bin": {
28
+ "ab-hosted-dispatcher": "./src/bin.ts"
29
+ },
30
+ "peerDependencies": {
31
+ "@defrex/autobuild": ">=0.9.0",
32
+ "@defrex/autobuild-hosted-store-service": ">=0.9.0"
33
+ },
34
+ "publishConfig": {
35
+ "access": "public"
36
+ },
37
+ "files": [
38
+ "src",
39
+ "README.md",
40
+ "!src/**/*.test.ts",
41
+ "!src/**/*.test.tsx",
42
+ "!src/**/*.spec.ts",
43
+ "!src/**/*.spec.tsx"
44
+ ]
45
+ }
package/src/bin.ts ADDED
@@ -0,0 +1,47 @@
1
+ #!/usr/bin/env bun
2
+ import { writePrebuiltDistributionArchive } from '@defrex/autobuild/distribution'
3
+
4
+ const USAGE = `Usage:
5
+ ab-hosted-dispatcher pack-distribution [--root DIR]`
6
+
7
+ function option(args: string[], name: string): string | undefined {
8
+ const indexes = args.flatMap((value, index) => (value === name ? [index] : []))
9
+ if (indexes.length > 1) throw new Error(`${name} may only be supplied once`)
10
+ const index = indexes[0]
11
+ if (index === undefined) return undefined
12
+ const value = args[index + 1]
13
+ if (value === undefined || value.startsWith('--')) throw new Error(`${name} requires a value`)
14
+ return value
15
+ }
16
+
17
+ /** `pack-distribution`: pack the running distribution into
18
+ * `<root>/.autobuild-dist/autobuild-<version>.tgz` for a deployment whose
19
+ * runtime has neither `bun` nor a source tree (the hosted service on Vercel).
20
+ * Run it in the deployment's build step; the archive is what guests install. */
21
+ export async function runPackDistribution(
22
+ args: string[],
23
+ write: (text: string) => void = (text) => console.log(text),
24
+ writeError: (text: string) => void = (text) => console.error(text),
25
+ ): Promise<number> {
26
+ try {
27
+ const root = option(args, '--root')
28
+ const allowed = new Set(['pack-distribution', '--root', root])
29
+ for (const arg of args) if (!allowed.has(arg)) throw new Error(`unknown argument: ${arg}`)
30
+ const path = await writePrebuiltDistributionArchive(root)
31
+ write(path)
32
+ return 0
33
+ } catch (error) {
34
+ writeError(`${error instanceof Error ? error.message : String(error)}\n${USAGE}`)
35
+ return 2
36
+ }
37
+ }
38
+
39
+ if (import.meta.main) {
40
+ const args = process.argv.slice(2)
41
+ if (args[0] === 'pack-distribution') {
42
+ process.exitCode = await runPackDistribution(args)
43
+ } else {
44
+ console.error(`unknown command: ${args[0] ?? '(none)'}\n${USAGE}`)
45
+ process.exitCode = 2
46
+ }
47
+ }
@@ -0,0 +1,505 @@
1
+ /**
2
+ * The hosted dispatcher (AUT-303): a cron-authenticated HTTP surface that
3
+ * makes this deployment the kernel owner. One authorized invocation runs, per
4
+ * configured repository, one bounded origin-mode dispatcher tick by re-driving
5
+ * the SAME dispatch kernel an operator runs locally (`abDispatch` with
6
+ * `--repository`, AUT-302) — claim, provision, launch, observe, settle, merge
7
+ * PRs, janitor, lease sweep. Nothing about the loop is reimplemented here;
8
+ * overlap safety stays in the durable repository lease (a losing invocation
9
+ * records `dispatcher.tick-yielded`) and missed ticks stay a resume decision.
10
+ *
11
+ * Identity: each repository tick mints `hosted-dispatcher-<uuid>` as the
12
+ * kernelRunId. That id is the repository-lease holder and it tags every tick
13
+ * report, run boundary, and deposited `dispatcher-effective-config` artifact,
14
+ * so the web dashboard's repository journal shows hosted activity exactly as
15
+ * it shows a local one. Guests authenticate with a short-TTL unattributed
16
+ * deployment operator token (`operator: true`) signed with the deployment's
17
+ * own store signing secret — the exact secret both the Store and ticket
18
+ * servers verify tokens against — so one credential covers store, tickets, and
19
+ * the guest session, and store identity still travels via the run id. The
20
+ * secret and minted tokens never appear in logs, responses, or error messages.
21
+ *
22
+ * This surface is deliberately NOT routed through `createHostedStoreService`:
23
+ * the machine routes gate on Autobuild version headers a bare cron request
24
+ * cannot send, and cron authorization is the deployment's `CRON_SECRET`, not a
25
+ * minted token. It is its own small protocol beside the store, ticket, and
26
+ * operator servers.
27
+ */
28
+ import { createHash, randomUUID, timingSafeEqual } from 'node:crypto'
29
+ import { normalizeGitRemoteUrl } from '@defrex/autobuild/origin'
30
+ import type { Clock } from '@defrex/autobuild/plugin-sdk'
31
+ import { spawnExec } from '@defrex/autobuild/git-worktree'
32
+ import { abDispatch, type DispatchOpts } from '@defrex/autobuild/cli'
33
+ import { mintToken } from '@defrex/autobuild/remote-store'
34
+ import { parseHostedStoreEnv, type HostedStoreEnv } from '@defrex/autobuild-hosted-store-service'
35
+
36
+ /** The service environment the dispatcher reads. Secrets are only ever taken
37
+ * through `parseHostedStoreEnv`'s already-validated fields. */
38
+ export type HostedDispatcherEnv = HostedStoreEnv
39
+
40
+ export interface HostedDispatcherConfig {
41
+ /** The deployment's `AB_STORE_SECRET` — the signing secret the Store and
42
+ * ticket servers verify tokens with, reused so a minted credential is
43
+ * accepted everywhere it is presented. `CRON_SECRET` is never a signing
44
+ * input and the two are never coupled. */
45
+ secret: string
46
+ /** The deployment's public origin, used as `AB_STORE` for the kernel, the
47
+ * hosted ticket source, and guests. */
48
+ origin: string
49
+ /** Normalized https repository identities, configured order preserved. */
50
+ repositories: readonly string[]
51
+ /** Optional per-repository GitHub token overrides (`AB_DISPATCHER_GITHUB_TOKENS`),
52
+ * keyed by the same normalized https identities as `repositories`. A
53
+ * repository with an override authenticates its forge operations with it;
54
+ * every other repository keeps the shared service-environment credential.
55
+ * Values are never logged, echoed, or deposited. */
56
+ githubTokenOverrides: ReadonlyMap<string, string>
57
+ /** Tick budget per invocation in seconds (default 240, inside Vercel's
58
+ * 300 s default function duration). */
59
+ budgetSeconds: number
60
+ /** Minted guest-token TTL in seconds (default 7 days). */
61
+ tokenTtlSeconds: number
62
+ /** The cron authorization shared secret; blank/unset disables the endpoint. */
63
+ cronSecret?: string
64
+ }
65
+
66
+ const DEFAULT_BUDGET_SECONDS = 240
67
+ const MIN_BUDGET_SECONDS = 10
68
+ const MAX_BUDGET_SECONDS = 780
69
+ const DEFAULT_TOKEN_TTL_SECONDS = 604800
70
+ const MIN_TOKEN_TTL_SECONDS = 3600
71
+
72
+ function required(env: HostedDispatcherEnv, name: string): string {
73
+ const value = env[name]?.trim()
74
+ if (!value) throw new Error(`${name} is required and must be nonblank`)
75
+ return value
76
+ }
77
+
78
+ function integerSetting(env: HostedDispatcherEnv, name: string, fallback: number): number {
79
+ const raw = env[name]?.trim()
80
+ if (raw === undefined || raw === '') return fallback
81
+ const value = Number(raw)
82
+ if (!Number.isInteger(value)) throw new Error(`${name} must be an integer`)
83
+ return value
84
+ }
85
+
86
+ /** Parse one repository-CSV variable into normalized https identities. */
87
+ function repositoryList(raw: string, name: string): string[] {
88
+ const values = raw
89
+ .split(',')
90
+ .map((value) => value.trim())
91
+ .filter((value) => value !== '')
92
+ if (values.length === 0) throw new Error(`${name} must name at least one repository`)
93
+ const repositories: string[] = []
94
+ for (const value of values) {
95
+ // Entries are repository identities — normalized https origins — so an
96
+ // operator-spelled `git@github.com:acme/app.git` still matches the Store's
97
+ // identity for this repository (same rule as AB_WEB_REPOSITORIES).
98
+ const normalized = normalizeGitRemoteUrl(value)
99
+ if (!/^https:\/\/[^\s]+$/.test(normalized)) {
100
+ throw new Error(`${name} contains an unsafe repository name: ${JSON.stringify(value)}`)
101
+ }
102
+ if (!repositories.includes(normalized)) repositories.push(normalized)
103
+ }
104
+ return repositories
105
+ }
106
+
107
+ /** Parse the optional per-repository forge-credential override map
108
+ * (`AB_DISPATCHER_GITHUB_TOKENS`): a JSON object mapping repository identities
109
+ * (same normalization as the repository set, so an operator may spell either
110
+ * form) to GitHub token material. Unset or blank means no overrides —
111
+ * behavior is byte-identical to the shared-credential-only deployment. Every
112
+ * key must name a repository in the resolved served set, so a typo fails
113
+ * loudly instead of silently leaving a repository on the shared identity.
114
+ * Error messages name the variable and the offending identity — never a value. */
115
+ function githubTokenOverrides(
116
+ env: HostedDispatcherEnv,
117
+ repositories: readonly string[],
118
+ ): Map<string, string> {
119
+ const raw = env.AB_DISPATCHER_GITHUB_TOKENS?.trim()
120
+ if (raw === undefined || raw === '') return new Map()
121
+ let parsed: unknown
122
+ try {
123
+ parsed = JSON.parse(raw)
124
+ } catch {
125
+ // JSON.parse error text can embed fragments of its input; rethrow a fixed
126
+ // message so token material never reaches a log or response.
127
+ throw new Error(
128
+ 'AB_DISPATCHER_GITHUB_TOKENS must be a JSON object mapping repository identities to GitHub tokens',
129
+ )
130
+ }
131
+ if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
132
+ throw new Error(
133
+ 'AB_DISPATCHER_GITHUB_TOKENS must be a JSON object mapping repository identities to GitHub tokens',
134
+ )
135
+ }
136
+ const overrides = new Map<string, string>()
137
+ for (const [rawKey, value] of Object.entries(parsed as Record<string, unknown>)) {
138
+ // Entries are repository identities — normalized https origins, exactly
139
+ // like the repository set — so an operator-spelled
140
+ // `git@github.com:acme/app.git` matches the served `https://` identity.
141
+ const identity = normalizeGitRemoteUrl(rawKey)
142
+ if (!/^https:\/\/[^\s]+$/.test(identity) || !repositories.includes(identity)) {
143
+ throw new Error(
144
+ `AB_DISPATCHER_GITHUB_TOKENS contains a key that is not a served repository: ${JSON.stringify(rawKey)}`,
145
+ )
146
+ }
147
+ if (typeof value !== 'string' || value.trim() === '') {
148
+ throw new Error(
149
+ `AB_DISPATCHER_GITHUB_TOKENS contains a blank value for repository ${JSON.stringify(identity)}`,
150
+ )
151
+ }
152
+ // Two spellings can normalize to one identity; a duplicate would make the
153
+ // effective credential depend on JSON key order, so it is rejected.
154
+ if (overrides.has(identity)) {
155
+ throw new Error(
156
+ `AB_DISPATCHER_GITHUB_TOKENS names repository ${JSON.stringify(identity)} more than once`,
157
+ )
158
+ }
159
+ overrides.set(identity, value.trim())
160
+ }
161
+ return overrides
162
+ }
163
+
164
+ /** Parse the dispatcher configuration from the service environment. Called per
165
+ * tick, so a misconfigured deployment fails loudly per invocation (naming the
166
+ * offending variable, never a value) rather than at module load. */
167
+ export function parseHostedDispatcherEnv(env: HostedDispatcherEnv): HostedDispatcherConfig {
168
+ // The signing secret is NOT a new variable: it is the deployment's
169
+ // AB_STORE_SECRET, validated once here together with the rest of the store
170
+ // configuration.
171
+ const secret = parseHostedStoreEnv(env).secret
172
+ const rawOrigin = required(env, 'AB_DISPATCHER_ORIGIN')
173
+ let origin: URL
174
+ try {
175
+ origin = new URL(rawOrigin)
176
+ } catch {
177
+ throw new Error('AB_DISPATCHER_ORIGIN must be an absolute http(s) origin')
178
+ }
179
+ if (
180
+ !['http:', 'https:'].includes(origin.protocol) ||
181
+ origin.username ||
182
+ origin.password ||
183
+ origin.pathname !== '/' ||
184
+ origin.search ||
185
+ origin.hash
186
+ ) {
187
+ throw new Error(
188
+ 'AB_DISPATCHER_ORIGIN must be an absolute http(s) origin without credentials or a path',
189
+ )
190
+ }
191
+ if (env.NODE_ENV === 'production' && origin.protocol !== 'https:') {
192
+ throw new Error('AB_DISPATCHER_ORIGIN must use https in production')
193
+ }
194
+ const rawRepositories = env.AB_DISPATCHER_REPOSITORIES?.trim()
195
+ const repositories =
196
+ rawRepositories === undefined || rawRepositories === ''
197
+ ? // Fall back to the web configuration so a deployment configures its
198
+ // repository set once.
199
+ repositoryList(required(env, 'AB_WEB_REPOSITORIES'), 'AB_WEB_REPOSITORIES')
200
+ : repositoryList(rawRepositories, 'AB_DISPATCHER_REPOSITORIES')
201
+ const rawBudget = integerSetting(env, 'AB_DISPATCHER_BUDGET_SECONDS', DEFAULT_BUDGET_SECONDS)
202
+ const budgetSeconds = Math.min(MAX_BUDGET_SECONDS, Math.max(MIN_BUDGET_SECONDS, rawBudget))
203
+ const tokenTtlSeconds = integerSetting(
204
+ env,
205
+ 'AB_DISPATCHER_TOKEN_TTL_SECONDS',
206
+ DEFAULT_TOKEN_TTL_SECONDS,
207
+ )
208
+ if (tokenTtlSeconds < MIN_TOKEN_TTL_SECONDS) {
209
+ throw new Error(
210
+ `AB_DISPATCHER_TOKEN_TTL_SECONDS must be at least ${MIN_TOKEN_TTL_SECONDS} — the minted ` +
211
+ 'credential must outlive a guest build lifetime',
212
+ )
213
+ }
214
+ const githubTokenOverridesMap = githubTokenOverrides(env, repositories)
215
+ const cronSecret = env.CRON_SECRET?.trim()
216
+ return {
217
+ secret,
218
+ origin: origin.origin,
219
+ repositories,
220
+ githubTokenOverrides: githubTokenOverridesMap,
221
+ budgetSeconds,
222
+ tokenTtlSeconds,
223
+ ...(cronSecret !== undefined && cronSecret !== '' ? { cronSecret } : {}),
224
+ }
225
+ }
226
+
227
+ /** One configured repository's outcome inside one invocation. */
228
+ export interface HostedDispatcherRepositoryOutcome {
229
+ repository: string
230
+ /** `ticked` — the kernel ran one tick; `failed` — the tick threw (the error
231
+ * message names variables, never secret values); `skipped` — the invocation
232
+ * budget no longer covers a minimum-remaining floor, so the next invocation
233
+ * resumes the work. */
234
+ outcome: 'ticked' | 'failed' | 'skipped'
235
+ /** This tick's durable run identity (`hosted-dispatcher-<uuid>`). */
236
+ runId?: string
237
+ error?: string
238
+ }
239
+
240
+ export interface HostedDispatcherTickSummary {
241
+ /** Epoch ms this invocation's work was bounded by. */
242
+ deadlineAt: number
243
+ repositories: HostedDispatcherRepositoryOutcome[]
244
+ }
245
+
246
+ export interface HostedDispatcherOptions {
247
+ /** Service environment; defaults to `process.env`. */
248
+ env?: HostedDispatcherEnv
249
+ clock?: Clock
250
+ /** The kernel entry. Defaults to the real `abDispatch`; integration tests
251
+ * wrap it with `wire`/`nonStoreWire` fakes and `originConfigTransport`. */
252
+ dispatch?: (opts: DispatchOpts) => Promise<void>
253
+ /** Where the kernel's own report lines go. Unset, they are forwarded to
254
+ * `log`/`logError` prefixed with the repository so a deployment's runtime
255
+ * logs carry every tick report and warning the kernel prints locally. */
256
+ stdout?: (line: string) => void
257
+ stderr?: (line: string) => void
258
+ /** Operational log sink for the endpoint and per-repository outcomes
259
+ * (default `console.log`). Every line starts with `hosted-dispatcher` and
260
+ * carries the invocation id; secrets and minted tokens never reach it. */
261
+ log?: (line: string) => void
262
+ /** Error-level sink (default `console.error`): rejected invocations,
263
+ * configuration failures with the offending variable, and failed repository
264
+ * ticks with the kernel error's stack. */
265
+ logError?: (line: string) => void
266
+ }
267
+
268
+ /** Below this much remaining budget a further repository is recorded as
269
+ * `skipped` instead of started, so one invocation always answers and the
270
+ * unfinished repository resumes on the next one. */
271
+ const MIN_REMAINING_MS = 20_000
272
+
273
+ const LOG_PREFIX = 'hosted-dispatcher'
274
+
275
+ function invocationId(): string {
276
+ return `inv_${randomUUID().slice(0, 8)}`
277
+ }
278
+
279
+ function errorDetail(error: unknown): string {
280
+ if (error instanceof Error) {
281
+ const cause =
282
+ error.cause instanceof Error
283
+ ? `\n caused by: ${error.cause.stack ?? error.cause.message}`
284
+ : error.cause !== undefined
285
+ ? `\n caused by: ${String(error.cause)}`
286
+ : ''
287
+ return `${error.stack ?? `${error.name}: ${error.message}`}${cause}`
288
+ }
289
+ return String(error)
290
+ }
291
+
292
+ /** The kernel owner. One `tick()` per authorized invocation; repositories run
293
+ * sequentially and fully isolated — one repository's failure never stops
294
+ * another. Overlap correctness lives in the durable journal: the repository
295
+ * supervisor lease makes a loser record `dispatcher.tick-yielded`; the
296
+ * response does not re-derive it. */
297
+ /** Per-invocation credentials that arrive with the request rather than the
298
+ * environment. */
299
+ export interface HostedDispatcherInvocation {
300
+ /** The Vercel OIDC token a Vercel Function receives on the
301
+ * `x-vercel-oidc-token` request header. It becomes the kernel's
302
+ * `VERCEL_OIDC_TOKEN` when the environment carries none, so the Sandbox SDK
303
+ * authenticates as the deployment. Never logged. */
304
+ oidcToken?: string
305
+ }
306
+
307
+ /** Which Sandbox credential the kernel will present, for the tick log line. */
308
+ function sandboxAuthSource(
309
+ env: HostedDispatcherEnv,
310
+ invocation: HostedDispatcherInvocation,
311
+ ): 'oidc-env' | 'oidc-header' | 'token' | 'none' {
312
+ if (env.VERCEL_OIDC_TOKEN) return 'oidc-env'
313
+ if (invocation.oidcToken) return 'oidc-header'
314
+ if (env.VERCEL_TOKEN && env.VERCEL_TEAM_ID && env.VERCEL_PROJECT_ID) return 'token'
315
+ return 'none'
316
+ }
317
+
318
+ export function createHostedDispatcher(options: HostedDispatcherOptions = {}): {
319
+ tick(
320
+ invocation?: string,
321
+ credentials?: HostedDispatcherInvocation,
322
+ ): Promise<HostedDispatcherTickSummary>
323
+ } {
324
+ const env = options.env ?? process.env
325
+ const clock: Clock = options.clock ?? (() => new Date())
326
+ const dispatch = options.dispatch ?? ((opts: DispatchOpts) => abDispatch(opts))
327
+ const log = options.log ?? ((line: string) => console.log(line))
328
+ const logError = options.logError ?? ((line: string) => console.error(line))
329
+ return {
330
+ async tick(
331
+ invocation = invocationId(),
332
+ credentials: HostedDispatcherInvocation = {},
333
+ ): Promise<HostedDispatcherTickSummary> {
334
+ const config = parseHostedDispatcherEnv(env)
335
+ const now = clock().getTime()
336
+ const deadlineAt = now + config.budgetSeconds * 1000
337
+ const sandboxAuth = sandboxAuthSource(env, credentials)
338
+ log(
339
+ `${LOG_PREFIX} ${invocation}: tick start repositories=${config.repositories.length} budgetSeconds=${config.budgetSeconds} origin=${config.origin} sandboxAuth=${sandboxAuth}`,
340
+ )
341
+ const repositories: HostedDispatcherRepositoryOutcome[] = []
342
+ for (const repository of config.repositories) {
343
+ if (clock().getTime() + MIN_REMAINING_MS > deadlineAt) {
344
+ repositories.push({ repository, outcome: 'skipped' })
345
+ log(`${LOG_PREFIX} ${invocation}: ${repository} skipped (invocation budget exhausted)`)
346
+ continue
347
+ }
348
+ const runId = `hosted-dispatcher-${randomUUID()}`
349
+ const kernelPrefix = `${LOG_PREFIX} ${invocation}: ${repository} [kernel]`
350
+ const stdout = options.stdout ?? ((line: string) => log(`${kernelPrefix} ${line}`))
351
+ const stderr = options.stderr ?? ((line: string) => logError(`${kernelPrefix} ${line}`))
352
+ const startedAt = Date.now()
353
+ log(`${LOG_PREFIX} ${invocation}: ${repository} tick run=${runId}`)
354
+ // Unattributed deployment operator credential: it covers store and
355
+ // ticket operations (attributed operator tokens are operator-API-only
356
+ // and cannot write store events). It names nothing because store
357
+ // identity travels via the run id. Never logged, never returned.
358
+ const token = mintToken(config.secret, {
359
+ operator: true,
360
+ session: '*',
361
+ exp: clock().getTime() + config.tokenTtlSeconds * 1000,
362
+ })
363
+ const childEnv: Record<string, string | undefined> = {
364
+ ...env,
365
+ AB_STORE: config.origin,
366
+ AB_TOKEN: token,
367
+ }
368
+ // A Vercel Function receives the deployment's OIDC token as a request
369
+ // header, not as VERCEL_OIDC_TOKEN; hand it to the kernel under that
370
+ // name so the Sandbox SDK authenticates as the deployment. An explicit
371
+ // environment token keeps precedence.
372
+ if (!childEnv.VERCEL_OIDC_TOKEN && credentials.oidcToken) {
373
+ childEnv.VERCEL_OIDC_TOKEN = credentials.oidcToken
374
+ }
375
+ // Per-repository forge identity: both variables are set to the
376
+ // override so no reader (`githubTokenFromEnv` prefers GITHUB_TOKEN,
377
+ // the publication path and init-validation accept either) can straddle
378
+ // the override and the shared credential within one tick. Repositories
379
+ // without an override keep the shared credential untouched.
380
+ const forgeOverride = config.githubTokenOverrides.get(repository)
381
+ if (forgeOverride !== undefined) {
382
+ childEnv.GITHUB_TOKEN = forgeOverride
383
+ childEnv.GH_TOKEN = forgeOverride
384
+ }
385
+ try {
386
+ await dispatch({
387
+ // `targetRepo` here is a caller-facing identity token, not a
388
+ // path: origin mode (AUT-302) has no checkout. `abDispatch`
389
+ // replaces it with the per-origin scratch root before plugin
390
+ // loading or any other filesystem consumer runs, so the token
391
+ // never participates in cwd-relative disk resolution (AUT-604).
392
+ targetRepo: '<hosted-dispatcher>',
393
+ repository,
394
+ once: true,
395
+ plain: true,
396
+ env: childEnv,
397
+ exec: spawnExec,
398
+ stdout,
399
+ stderr,
400
+ kernelRunId: runId,
401
+ deadlineAt,
402
+ })
403
+ repositories.push({ repository, outcome: 'ticked', runId })
404
+ log(
405
+ `${LOG_PREFIX} ${invocation}: ${repository} ticked run=${runId} ms=${Date.now() - startedAt}`,
406
+ )
407
+ } catch (error) {
408
+ const message = error instanceof Error ? error.message : String(error)
409
+ repositories.push({ repository, outcome: 'failed', runId, error: message })
410
+ logError(
411
+ `${LOG_PREFIX} ${invocation}: ${repository} failed run=${runId} ms=${Date.now() - startedAt}: ${errorDetail(error)}`,
412
+ )
413
+ }
414
+ }
415
+ const counts = { ticked: 0, failed: 0, skipped: 0 }
416
+ for (const entry of repositories) counts[entry.outcome] += 1
417
+ log(
418
+ `${LOG_PREFIX} ${invocation}: tick complete ticked=${counts.ticked} failed=${counts.failed} skipped=${counts.skipped}`,
419
+ )
420
+ return { deadlineAt, repositories }
421
+ },
422
+ }
423
+ }
424
+
425
+ function timingSafeStringEqual(a: string, b: string): boolean {
426
+ const digestA = createHash('sha256').update(a).digest()
427
+ const digestB = createHash('sha256').update(b).digest()
428
+ return timingSafeEqual(digestA, digestB)
429
+ }
430
+
431
+ function jsonError(status: number, kind: string, error: string): Response {
432
+ return Response.json({ error, kind }, { status })
433
+ }
434
+
435
+ /** The cron endpoint: one authorized GET runs one bounded tick per configured
436
+ * repository. `CRON_SECRET` unset/blank disables the endpoint entirely — work
437
+ * never runs without authorization configured. A wrong or missing bearer is
438
+ * rejected without performing any work, compared timing-safe. */
439
+ export function createDispatcherEndpoint(options: HostedDispatcherOptions = {}): {
440
+ fetch(request: Request): Promise<Response>
441
+ } {
442
+ const dispatcher = createHostedDispatcher(options)
443
+ const env = options.env ?? process.env
444
+ const log = options.log ?? ((line: string) => console.log(line))
445
+ const logError = options.logError ?? ((line: string) => console.error(line))
446
+ return {
447
+ async fetch(request: Request): Promise<Response> {
448
+ const invocation = invocationId()
449
+ const startedAt = Date.now()
450
+ // The user agent tells a Vercel Cron invocation (`vercel-cron/1.0`)
451
+ // apart from an operator's curl in the runtime logs; it is not trusted.
452
+ const agent = request.headers.get('user-agent') ?? '-'
453
+ log(
454
+ `${LOG_PREFIX} ${invocation}: ${request.method} ${new URL(request.url).pathname} agent=${JSON.stringify(agent)}`,
455
+ )
456
+ const reject = (status: number, kind: string, error: string): Response => {
457
+ logError(`${LOG_PREFIX} ${invocation}: rejected ${status} ${kind}: ${error}`)
458
+ return jsonError(status, kind, error)
459
+ }
460
+ if (request.method !== 'GET') {
461
+ return reject(405, 'method-not-allowed', 'the dispatcher endpoint answers GET only')
462
+ }
463
+ // Endpoint disabled: never run work without authorization configured.
464
+ const cronSecret = env.CRON_SECRET?.trim()
465
+ if (cronSecret === undefined || cronSecret === '') {
466
+ return reject(
467
+ 403,
468
+ 'disabled',
469
+ 'the dispatcher endpoint is disabled: CRON_SECRET is not configured',
470
+ )
471
+ }
472
+ const authorization = request.headers.get('authorization') ?? ''
473
+ if (!timingSafeStringEqual(authorization, `Bearer ${cronSecret}`)) {
474
+ return reject(
475
+ 401,
476
+ 'unauthorized',
477
+ `dispatcher endpoint requires the cron bearer token (authorization header ${authorization === '' ? 'absent' : 'present but wrong'})`,
478
+ )
479
+ }
480
+ try {
481
+ const oidcToken = request.headers.get('x-vercel-oidc-token')?.trim()
482
+ const summary = await dispatcher.tick(
483
+ invocation,
484
+ oidcToken !== undefined && oidcToken !== '' ? { oidcToken } : {},
485
+ )
486
+ log(`${LOG_PREFIX} ${invocation}: 200 ok ms=${Date.now() - startedAt}`)
487
+ return Response.json(
488
+ { ok: true, repositories: summary.repositories },
489
+ { headers: { 'cache-control': 'private, no-store' } },
490
+ )
491
+ } catch (error) {
492
+ // A misconfigured deployment names the offending variable, never a
493
+ // value: every parser error is written that way.
494
+ logError(
495
+ `${LOG_PREFIX} ${invocation}: 500 configuration invalid ms=${Date.now() - startedAt}: ${errorDetail(error)}`,
496
+ )
497
+ return jsonError(
498
+ 500,
499
+ 'internal',
500
+ error instanceof Error ? error.message : 'dispatcher configuration is invalid',
501
+ )
502
+ }
503
+ },
504
+ }
505
+ }
package/src/index.ts ADDED
@@ -0,0 +1,15 @@
1
+ export {
2
+ createDispatcherEndpoint,
3
+ createHostedDispatcher,
4
+ parseHostedDispatcherEnv,
5
+ } from './dispatcher'
6
+ export type {
7
+ HostedDispatcherConfig,
8
+ HostedDispatcherEnv,
9
+ HostedDispatcherOptions,
10
+ HostedDispatcherRepositoryOutcome,
11
+ HostedDispatcherTickSummary,
12
+ } from './dispatcher'
13
+ export { ensureDistributionArchiveInTrace } from './ship-packed-distribution'
14
+ export type { EnsureOptions, EnsureResult } from './ship-packed-distribution'
15
+ export { dispatcherEndpoint } from './runtime'
package/src/runtime.ts ADDED
@@ -0,0 +1,7 @@
1
+ import { createDispatcherEndpoint } from './dispatcher'
2
+
3
+ let dispatcher: ReturnType<typeof createDispatcherEndpoint> | undefined
4
+ export function dispatcherEndpoint() {
5
+ dispatcher ??= createDispatcherEndpoint({ env: process.env })
6
+ return dispatcher
7
+ }
@@ -0,0 +1,230 @@
1
+ #!/usr/bin/env bun
2
+ /**
3
+ * Guarantee the packaged guest distribution and the canonical operate skill
4
+ * ship in the hosted deployment.
5
+ *
6
+ * Next 16's default Turbopack builds never apply `outputFileTracingIncludes`
7
+ * (see docs/hosted-dispatcher.md), so a `next build` alone cannot be relied on
8
+ * to carry `.autobuild-dist/autobuild-<version>.tgz` into the `/api/dispatch`
9
+ * function bundle. This post-build step appends the archive to the dispatch
10
+ * route's `route.js.nft.json` — the trace file Vercel's Next builder consumes
11
+ * when assembling the function bundle — computing the entry exactly the way
12
+ * Next itself computes `outputFileTracingIncludes` entries (relative from the
13
+ * trace file's directory). It fails loudly when pack-distribution has not run
14
+ * or the trace file is missing, so a deployment can never silently ship
15
+ * without the archive.
16
+ *
17
+ * It appends the distribution manifest the same way. Provisioning reads the
18
+ * running version from the repository root's package.json, which no import
19
+ * traces; it reached the bundle only while the Next.js project directory was
20
+ * the repository root, and a Root Directory below it drops the file.
21
+ *
22
+ * The archive and the manifest are appended to the dispatch route's trace
23
+ * only — the operator function never reads them, so it never carries the
24
+ * multi-megabyte tarball.
25
+ *
26
+ * It also appends `skills/operate/SKILL.md` — the canonical `ab-operate`
27
+ * skill the embedded orchestrator reads at runtime through
28
+ * `distributionPath` (AUT-342) — to BOTH function bundles that execute
29
+ * turns: the operator route's trace (message and answer invocations run
30
+ * there) and the dispatch route's trace (the tick's resume and wake passes
31
+ * run the turn loop inside `/api/dispatch`, which otherwise traces only
32
+ * `.autobuild-dist/**`). A dynamic fs read is invisible to tracing, so
33
+ * without these appends the system prompt could not load in production while
34
+ * every in-process test passed. Both entries are computed the same relative
35
+ * way, and the step fails loudly when a trace file or the skill file is
36
+ * missing — a deployment can never silently ship without the skill.
37
+ */
38
+ import { createHash } from 'node:crypto'
39
+ import { readdir, readFile, stat, writeFile } from 'node:fs/promises'
40
+ import { basename, dirname, join, relative } from 'node:path'
41
+ import { distributionManifestPath, distributionPath } from '@defrex/autobuild/distribution'
42
+
43
+ export interface EnsureOptions {
44
+ root?: string
45
+ distDir?: string
46
+ /** Distribution manifest to carry; defaults to the file provisioning reads. */
47
+ manifest?: string
48
+ /** Canonical operate skill to carry; defaults to the distribution tree the
49
+ * turn runner reads at runtime. */
50
+ skill?: string
51
+ log?: (message: string) => void
52
+ }
53
+
54
+ export interface EnsureResult {
55
+ archive: string
56
+ bytes: number
57
+ sha256: string
58
+ /** Whether the archive entry was appended to the dispatch route's trace. */
59
+ appended: boolean
60
+ /** Whether the manifest entry was appended to the dispatch route's trace. */
61
+ manifestAppended: boolean
62
+ /** The canonical operate skill file carried into the turn-executing bundles. */
63
+ skill: string
64
+ /** Route names whose trace got the skill appended ('dispatch', 'operator'). */
65
+ skillAppended: string[]
66
+ }
67
+
68
+ const DIST_DIRECTORY = '.autobuild-dist'
69
+ const TRACE_FILE = 'route.js.nft.json'
70
+ const ROUTE_DIRECTORY = join('server', 'app', 'api', 'dispatch')
71
+ /** The operator route — message and approval-answer invocations run turns
72
+ * inside this function bundle. */
73
+ const OPERATOR_ROUTE_DIRECTORY = join('server', 'app', 'operator', '[[...path]]')
74
+
75
+ async function findArchive(root: string): Promise<string> {
76
+ const dist = join(root, DIST_DIRECTORY)
77
+ let entries: string[]
78
+ try {
79
+ entries = await readdir(dist)
80
+ } catch {
81
+ throw new Error(
82
+ `no ${DIST_DIRECTORY}/ directory under ${root} — run ` +
83
+ '`bun ../../packages/hosted-dispatcher/src/bin.ts pack-distribution --root .` before building',
84
+ )
85
+ }
86
+ const archives = entries.filter((name) => /^autobuild-.+\.tgz$/.test(name)).sort()
87
+ if (archives.length === 0) {
88
+ throw new Error(
89
+ `no autobuild-*.tgz in ${DIST_DIRECTORY}/ — run ` +
90
+ '`bun ../../packages/hosted-dispatcher/src/bin.ts pack-distribution --root .` before building',
91
+ )
92
+ }
93
+ if (archives.length > 1) {
94
+ throw new Error(
95
+ `expected exactly one archive in ${DIST_DIRECTORY}/, found ${archives.length}: ` +
96
+ `${archives.join(', ')} — rerun pack-distribution to remove stale archives`,
97
+ )
98
+ }
99
+ return join(dist, archives[0]!)
100
+ }
101
+
102
+ async function readTrace(path: string): Promise<string[]> {
103
+ let raw: string
104
+ try {
105
+ raw = await readFile(path, 'utf8')
106
+ } catch {
107
+ throw new Error(
108
+ `missing Next.js trace file ${path} — run this tool after \`next build\`; ` +
109
+ 'if the dispatch route was renamed, update packages/hosted-dispatcher/src/ship-packed-distribution.ts',
110
+ )
111
+ }
112
+ const parsed: unknown = JSON.parse(raw)
113
+ if (
114
+ typeof parsed !== 'object' ||
115
+ parsed === null ||
116
+ !Array.isArray((parsed as { files?: unknown }).files)
117
+ ) {
118
+ throw new Error(`unexpected trace file layout in ${path}: "files" array not found`)
119
+ }
120
+ return (parsed as { files: string[] }).files
121
+ }
122
+
123
+ /** Append the packed distribution archive, the distribution manifest, and the
124
+ * canonical operate skill to the turn-executing routes' trace files — the
125
+ * archive and manifest to the dispatch route's trace only, the skill to both. */
126
+ export async function ensureDistributionArchiveInTrace({
127
+ root = process.cwd(),
128
+ distDir = '.next',
129
+ manifest = distributionManifestPath(),
130
+ skill = distributionPath('skills', 'operate', 'SKILL.md'),
131
+ log = (message) => console.log(message),
132
+ }: EnsureOptions = {}): Promise<EnsureResult> {
133
+ const archive = await findArchive(root)
134
+ try {
135
+ await stat(manifest)
136
+ } catch {
137
+ throw new Error(
138
+ `missing distribution manifest ${manifest} — provisioning reads the version from it`,
139
+ )
140
+ }
141
+ try {
142
+ await stat(skill)
143
+ } catch {
144
+ throw new Error(
145
+ `missing canonical operate skill ${skill} — the orchestrator's system prompt ` +
146
+ 'cannot load in production without it',
147
+ )
148
+ }
149
+ // Each route declares the trace entries it requires, matching the intent
150
+ // recorded in packages/hosted-store-service/next.config.ts: the archive and
151
+ // the manifest belong to the dispatch route alone (the operator function
152
+ // never reads them), while both turn-executing routes carry the operate
153
+ // skill (AUT-342).
154
+ const routes: {
155
+ name: string
156
+ directory: string
157
+ extras: ('archive' | 'manifest' | 'skill')[]
158
+ }[] = [
159
+ { name: 'dispatch', directory: ROUTE_DIRECTORY, extras: ['archive', 'manifest', 'skill'] },
160
+ { name: 'operator', directory: OPERATOR_ROUTE_DIRECTORY, extras: ['skill'] },
161
+ ]
162
+ const skillAppended: string[] = []
163
+ let appended = false
164
+ let manifestAppended = false
165
+ for (const route of routes) {
166
+ const trace = join(root, distDir, route.directory, TRACE_FILE)
167
+ const files = await readTrace(trace)
168
+
169
+ const entry = relative(dirname(trace), archive)
170
+ const manifestEntry = relative(dirname(trace), manifest)
171
+ const skillEntry = relative(dirname(trace), skill)
172
+ const appendedHere = route.extras.includes('archive') && !files.includes(entry)
173
+ const manifestAppendedHere = route.extras.includes('manifest') && !files.includes(manifestEntry)
174
+ const skillMissing = route.extras.includes('skill') && !files.includes(skillEntry)
175
+ if (skillMissing) skillAppended.push(route.name)
176
+ if (appendedHere || manifestAppendedHere || skillMissing) {
177
+ const parsed = JSON.parse(await readFile(trace, 'utf8'))
178
+ const added = [
179
+ ...(appendedHere ? [entry] : []),
180
+ ...(manifestAppendedHere ? [manifestEntry] : []),
181
+ ...(skillMissing ? [skillEntry] : []),
182
+ ]
183
+ await writeFile(
184
+ trace,
185
+ `${JSON.stringify({ ...parsed, files: [...files, ...added] }, null, 2)}\n`,
186
+ )
187
+ }
188
+
189
+ if (route.name === 'dispatch') {
190
+ appended = appended || appendedHere
191
+ manifestAppended = manifestAppended || manifestAppendedHere
192
+ const bytes = (await stat(archive)).size
193
+ const sha256 = createHash('sha256')
194
+ .update(await readFile(archive))
195
+ .digest('hex')
196
+ log(
197
+ `distribution archive ${basename(archive)} (${bytes} bytes, sha256 ${sha256}) ` +
198
+ `${appendedHere ? 'appended to' : 'already present in'} ${trace}`,
199
+ )
200
+ log(
201
+ `distribution manifest ${manifest} ` +
202
+ `${manifestAppendedHere ? 'appended to' : 'already present in'} ${trace}`,
203
+ )
204
+ }
205
+ log(
206
+ `operate skill ${basename(skill)} ` +
207
+ `${skillMissing ? 'appended to' : 'already present in'} ${trace}`,
208
+ )
209
+ }
210
+ return {
211
+ archive,
212
+ bytes: (await stat(archive)).size,
213
+ sha256: createHash('sha256')
214
+ .update(await readFile(archive))
215
+ .digest('hex'),
216
+ appended,
217
+ manifestAppended,
218
+ skill,
219
+ skillAppended,
220
+ }
221
+ }
222
+
223
+ if (import.meta.main) {
224
+ try {
225
+ await ensureDistributionArchiveInTrace()
226
+ } catch (error) {
227
+ console.error(error instanceof Error ? error.message : error)
228
+ process.exit(1)
229
+ }
230
+ }
@@ -0,0 +1,323 @@
1
+ #!/usr/bin/env bun
2
+ /**
3
+ * Ship the provider plugin package into the hosted deployment (AUT-517).
4
+ *
5
+ * A bare package specifier resolves only through a `node_modules/` path, so
6
+ * appending the plugin's source files to the dispatch route's trace alone
7
+ * cannot make `@defrex/autobuild-vercel-sandbox` resolvable inside the
8
+ * deployed `/api/dispatch` function (build extract-the-vercel,
9
+ * finding f_0b59ab99). The runtime resolution root is `distributionRoot()`,
10
+ * which — derived from this repository's own compiled Turbopack output — is
11
+ * the REPOSITORY ROOT, not the Next project directory: the chunk holding
12
+ * `distribution.ts` synthesizes `import.meta.url` from the source path and
13
+ * resolves its absolute root six file-relative ups from the runtime chunk
14
+ * (`<repoRoot>/packages/hosted-store-service/.next/server/chunks/`), which is
15
+ * the repository root. `loadPlugins` therefore resolves bare specifiers
16
+ * against `<repoRoot>/node_modules`.
17
+ *
18
+ * The deployment's repo-root `node_modules` carries no `@defrex/autobuild`
19
+ * either (the trace has zero `@defrex` entries — core is Turbopack-inlined),
20
+ * so this step stages a self-contained `bun build` bundle of the plugin: the
21
+ * bundle inlines the plugin-sdk closure (the shared capability object, its
22
+ * validators, and transitive dependencies including `@vercel/sandbox`) and
23
+ * evaluates with zero external module imports; node builtins stay external.
24
+ *
25
+ * Staging targets `<repoRoot>/node_modules/@defrex/autobuild-vercel-sandbox/`
26
+ * and every staged file is appended to the dispatch route's
27
+ * `route.js.nft.json` computed relative to the trace file's directory —
28
+ * seven `'..'` components up to the repository root (what `path.relative()`
29
+ * yields from `…/.next/server/app/api/dispatch`), the same depth class as
30
+ * the trace's existing `node_modules/.bun/**` entries. It fails loudly when the package, bundle
31
+ * input, or trace is missing, so a deployment can never silently ship
32
+ * without the plugin. Idempotent ACROSS PROCESSES: the bundle input is
33
+ * located through the workspace tree, never through `node_modules`, so a
34
+ * re-run in a fresh process still finds the source after a previous run
35
+ * replaced the workspace symlink with the staged directory (finding
36
+ * f_5b9ade16).
37
+ *
38
+ * The npm published package remains the real `src` — only the deployment
39
+ * stages the bundle. In a Vercel deployment build the staged directory
40
+ * replaces the workspace symlink and persists there (the deployment never
41
+ * runs `bun install` again). A developer-local run of `deploy:build` (no
42
+ * `VERCEL` environment) removes the staged directory afterwards and restores
43
+ * the workspace symlink, so a local run leaves the checkout exactly as
44
+ * `bun install` had it and local test runs keep resolving the workspace
45
+ * source. Staged files are build-time artifacts under `node_modules`
46
+ * (gitignored, never committed).
47
+ */
48
+ import { lstat, mkdir, readdir, readFile, rm, symlink, writeFile } from 'node:fs/promises'
49
+ import { dirname, join, relative, resolve } from 'node:path'
50
+ import type { Dirent } from 'node:fs'
51
+
52
+ export interface ShipProviderPluginOptions {
53
+ /** Working directory the repository root is derived from; deploy:build
54
+ * runs in the Next project directory. */
55
+ cwd?: string
56
+ /** Next build output directory under the project directory. */
57
+ distDir?: string
58
+ /** The plugin package specifier to stage. */
59
+ packageName?: string
60
+ /** Remove the staged directory after the trace append and re-create the
61
+ * workspace symlink it replaced. The deployment build (the default) must
62
+ * keep the staged bundle — its runtime resolution needs it; only a
63
+ * developer-local run (no `VERCEL` environment) should restore the link. */
64
+ restoreWorkspaceLink?: boolean
65
+ log?: (message: string) => void
66
+ }
67
+
68
+ export interface ShipProviderPluginResult {
69
+ repoRoot: string
70
+ /** Directory the bundle was staged into (absolute). */
71
+ staging: string
72
+ /** Staged files appended to (or already present in) the trace, relative to
73
+ * the trace file's directory — exactly the strings written into `files`. */
74
+ traceEntries: string[]
75
+ appended: number
76
+ bytes: number
77
+ /** Whether the staged directory was removed and the workspace symlink
78
+ * restored after staging (local runs only). */
79
+ restoredWorkspaceLink?: boolean
80
+ }
81
+
82
+ /** True when the run is a developer-local build: Vercel sets `VERCEL` in
83
+ * every build environment — including a local `vercel build` — so an absent
84
+ * `VERCEL` identifies exactly the plain local runs this tool's restore is
85
+ * for. */
86
+ export function restoresWorkspaceLinkIn(env: Record<string, string | undefined>): boolean {
87
+ return env.VERCEL === undefined
88
+ }
89
+
90
+ const TRACE_FILE = 'route.js.nft.json'
91
+ const ROUTE_DIRECTORY = join('server', 'app', 'api', 'dispatch')
92
+
93
+ /** Nearest ancestor directory whose package.json declares `workspaces` — the
94
+ * same root manifest `readWorkspaceManifests` reads. Never a hardcoded
95
+ * up-count. */
96
+ export async function findWorkspaceRoot(start: string): Promise<string> {
97
+ let current = resolve(start)
98
+ while (true) {
99
+ try {
100
+ const manifest = JSON.parse(await readFile(join(current, 'package.json'), 'utf8')) as {
101
+ workspaces?: unknown
102
+ }
103
+ if (Array.isArray(manifest.workspaces) && manifest.workspaces.length > 0) return current
104
+ } catch {
105
+ // Not a manifest (or unreadable): keep walking up.
106
+ }
107
+ const parent = dirname(current)
108
+ if (parent === current) {
109
+ throw new Error(
110
+ `no workspace root (a package.json declaring "workspaces") above ${resolve(start)}`,
111
+ )
112
+ }
113
+ current = parent
114
+ }
115
+ }
116
+
117
+ /** Directory of the plugin package's SOURCE, located through the repository
118
+ * root's `workspaces` tree — never through `node_modules`. Resolving through
119
+ * the installation would find the workspace link on the first run but the
120
+ * STAGED bundle directory on every later run (staging replaces the symlink
121
+ * and `bun install` does not relink a pre-existing directory, so the checkout
122
+ * never self-heals), making the second deploy build target the staged
123
+ * directory's nonexistent `src/` (finding f_5b9ade16). The workspace tree is
124
+ * stable across runs. Pattern support mirrors tools/workspace-manifest-check.ts:
125
+ * `directory/*` globs only. */
126
+ async function resolvePackageSourceDirectory(
127
+ repoRoot: string,
128
+ packageName: string,
129
+ ): Promise<string> {
130
+ let rootManifest: { workspaces?: unknown }
131
+ try {
132
+ rootManifest = JSON.parse(await readFile(join(repoRoot, 'package.json'), 'utf8'))
133
+ } catch (error) {
134
+ throw new Error(
135
+ `cannot read the workspace root manifest ${join(repoRoot, 'package.json')}: ` +
136
+ (error instanceof Error ? error.message : String(error)),
137
+ )
138
+ }
139
+ if (!Array.isArray(rootManifest.workspaces) || rootManifest.workspaces.length === 0) {
140
+ throw new Error(
141
+ `${join(repoRoot, 'package.json')}: workspaces must be a non-empty array — ` +
142
+ `the plugin source is located through the workspace tree`,
143
+ )
144
+ }
145
+ const candidates: string[] = []
146
+ for (const pattern of rootManifest.workspaces) {
147
+ const normalized = typeof pattern === 'string' ? pattern.replaceAll('\\', '/') : ''
148
+ if (!normalized.endsWith('/*') || normalized.slice(0, -2).includes('*')) {
149
+ throw new Error(
150
+ `${join(repoRoot, 'package.json')}: unsupported workspace pattern "${String(pattern)}"; ` +
151
+ 'expected a directory/* glob',
152
+ )
153
+ }
154
+ const parent = resolve(repoRoot, normalized.slice(0, -2))
155
+ let entries: Dirent[]
156
+ try {
157
+ entries = await readdir(parent, { withFileTypes: true })
158
+ } catch (error) {
159
+ throw new Error(
160
+ `${join(repoRoot, 'package.json')}: cannot read workspace directory ` +
161
+ `${normalized.slice(0, -2)}: ${error instanceof Error ? error.message : String(error)}`,
162
+ )
163
+ }
164
+ for (const entry of entries) {
165
+ if (entry.isDirectory()) candidates.push(join(parent, entry.name))
166
+ }
167
+ }
168
+ for (const directory of candidates) {
169
+ try {
170
+ const manifest = JSON.parse(await readFile(join(directory, 'package.json'), 'utf8')) as {
171
+ name?: unknown
172
+ }
173
+ if (manifest.name === packageName) return directory
174
+ } catch {
175
+ // Not a package manifest: keep scanning the workspace tree.
176
+ }
177
+ }
178
+ throw new Error(
179
+ `plugin package "${packageName}" not found in the workspace tree of ${repoRoot} ` +
180
+ '(workspaces patterns: ' +
181
+ rootManifest.workspaces.map((pattern) => String(pattern)).join(', ') +
182
+ ') — is the package a workspace member?',
183
+ )
184
+ }
185
+
186
+ /** Single self-contained ESM bundle of the plugin's entrypoint for the Bun
187
+ * runtime. The plugin-sdk closure inlines; node builtins stay external. */
188
+ async function buildBundle(entry: string): Promise<string> {
189
+ const result = await Bun.build({
190
+ entrypoints: [entry],
191
+ target: 'bun',
192
+ format: 'esm',
193
+ sourcemap: 'none',
194
+ minify: false,
195
+ })
196
+ if (!result.success) {
197
+ const details = result.logs
198
+ .map((log) => (typeof log === 'string' ? log : `${log.level}: ${log.message}`))
199
+ .join('\n')
200
+ throw new Error(`bundling ${entry} failed:\n${details}`)
201
+ }
202
+ const script = result.outputs.find((artifact) => artifact.path.endsWith('.js'))
203
+ if (script === undefined) {
204
+ throw new Error(`bundling ${entry} produced no JavaScript output`)
205
+ }
206
+ return await script.text()
207
+ }
208
+
209
+ async function traceFiles(trace: string): Promise<string[]> {
210
+ let raw: string
211
+ try {
212
+ raw = await readFile(trace, 'utf8')
213
+ } catch {
214
+ throw new Error(
215
+ `missing Next.js trace file ${trace} — run this tool after \`next build\`; ` +
216
+ 'if the dispatch route was renamed, update packages/hosted-dispatcher/src/ship-provider-plugin.ts',
217
+ )
218
+ }
219
+ const parsed: unknown = JSON.parse(raw)
220
+ if (
221
+ typeof parsed !== 'object' ||
222
+ parsed === null ||
223
+ !Array.isArray((parsed as { files?: unknown }).files)
224
+ ) {
225
+ throw new Error(`unexpected trace file layout in ${trace}: "files" array not found`)
226
+ }
227
+ return (parsed as { files: string[] }).files
228
+ }
229
+
230
+ /** Bundle the provider plugin, stage it into the repository-root
231
+ * `node_modules`, and append the staged files to the dispatch route's trace. */
232
+ export async function shipProviderPlugin({
233
+ cwd = process.cwd(),
234
+ distDir = '.next',
235
+ packageName = '@defrex/autobuild-vercel-sandbox',
236
+ restoreWorkspaceLink = false,
237
+ log = (message) => console.log(message),
238
+ }: ShipProviderPluginOptions = {}): Promise<ShipProviderPluginResult> {
239
+ const repoRoot = await findWorkspaceRoot(cwd)
240
+ const packageDirectory = await resolvePackageSourceDirectory(repoRoot, packageName)
241
+ const packageManifest = JSON.parse(
242
+ await readFile(join(packageDirectory, 'package.json'), 'utf8'),
243
+ ) as { name?: unknown; version?: unknown }
244
+ if (typeof packageManifest.name !== 'string' || typeof packageManifest.version !== 'string') {
245
+ throw new Error(`${join(packageDirectory, 'package.json')} must declare name and version`)
246
+ }
247
+
248
+ const bundle = await buildBundle(join(packageDirectory, 'src', 'index.ts'))
249
+
250
+ // Stage into the repository-root node_modules. bun install leaves a
251
+ // workspace symlink there for the root devDependency; it must be replaced
252
+ // by a real directory (the deployment never runs bun install again). A
253
+ // pre-existing real directory — a previous run's staging, which bun install
254
+ // does not relink — is replaced too, so re-runs are clean.
255
+ const staging = join(repoRoot, 'node_modules', ...packageName.split('/'))
256
+ const existing = await lstat(staging).catch(() => undefined)
257
+ if (existing !== undefined) {
258
+ await rm(staging, { recursive: true })
259
+ }
260
+ await mkdir(join(staging, 'dist'), { recursive: true })
261
+ const stagedManifest = {
262
+ name: packageManifest.name,
263
+ version: packageManifest.version,
264
+ type: 'module',
265
+ exports: { '.': './dist/index.js' },
266
+ }
267
+ const stagedFiles = [
268
+ { name: 'package.json', contents: `${JSON.stringify(stagedManifest, null, 2)}\n` },
269
+ { name: join('dist', 'index.js'), contents: bundle },
270
+ ]
271
+ for (const file of stagedFiles) {
272
+ await writeFile(join(staging, file.name), file.contents)
273
+ }
274
+ const bytes = stagedFiles.reduce((total, file) => total + Buffer.byteLength(file.contents), 0)
275
+
276
+ const trace = join(cwd, distDir, ROUTE_DIRECTORY, TRACE_FILE)
277
+ const files = await traceFiles(trace)
278
+ const entries = stagedFiles.map((file) => relative(dirname(trace), join(staging, file.name)))
279
+ const missing = entries.filter((entry) => !files.includes(entry))
280
+ if (missing.length > 0) {
281
+ const parsed = JSON.parse(await readFile(trace, 'utf8'))
282
+ await writeFile(
283
+ trace,
284
+ `${JSON.stringify({ ...parsed, files: [...files, ...missing] }, null, 2)}\n`,
285
+ )
286
+ }
287
+ log(
288
+ `plugin package ${packageName} (${bytes} bytes, ${stagedFiles.length} file(s)) ` +
289
+ `${missing.length > 0 ? `appended ${missing.length} entr${missing.length === 1 ? 'y' : 'ies'} to` : 'already present in'} ${trace}`,
290
+ )
291
+ if (restoreWorkspaceLink) {
292
+ // A local run must leave the checkout as `bun install` had it: the staged
293
+ // directory would otherwise satisfy the manifest and keep `bun install`
294
+ // from ever relinking the workspace, so later local runs would resolve
295
+ // the plugin to the staged bundle instead of the workspace source. The
296
+ // link target is computed from the link's OWN directory (a relative
297
+ // symlink resolves from the directory containing the link):
298
+ // `<repoRoot>/node_modules/@defrex` + `../../packages/...` — exactly what
299
+ // `bun install` leaves.
300
+ const target = relative(dirname(staging), packageDirectory)
301
+ await rm(staging, { recursive: true })
302
+ await symlink(target, staging, 'dir')
303
+ log(`restored workspace symlink ${staging} -> ${target} (local run, no VERCEL environment)`)
304
+ return {
305
+ repoRoot,
306
+ staging,
307
+ traceEntries: entries,
308
+ appended: missing.length,
309
+ bytes,
310
+ restoredWorkspaceLink: true,
311
+ }
312
+ }
313
+ return { repoRoot, staging, traceEntries: entries, appended: missing.length, bytes }
314
+ }
315
+
316
+ if (import.meta.main) {
317
+ try {
318
+ await shipProviderPlugin({ restoreWorkspaceLink: restoresWorkspaceLinkIn(process.env) })
319
+ } catch (error) {
320
+ console.error(error instanceof Error ? error.message : error)
321
+ process.exit(1)
322
+ }
323
+ }