@pikku/deploy-standalone 0.12.13 → 0.12.19

package/src/adapter.ts

@@ -16,8 +16,23 @@
  *   compiles the bundle into a single self-contained executable via
  *   `bun build --compile`. No runtime needed on the target host.
  */
-import type { EntryGenerationContext, ProviderAdapter } from '@pikku/deploy'
-import { nodeBuiltinExternals, SERVER_READY_MARKER } from '@pikku/deploy'
+import type {
+  BindingSource,
+  ContributorPlatform,
+  EntryGenerationContext,
+  PlatformServiceContributor,
+  ProviderAdapter,
+} from '@pikku/deploy'
+import {
+  assertContributorsSupported,
+  collectContributorImports,
+  collectContributorLines,
+  dedupeContributors,
+  nodeBuiltinExternals,
+  SERVER_READY_MARKER,
+} from '@pikku/deploy'
+
+export const STANDALONE_BINDING_SOURCES: readonly BindingSource[] = ['env']
 
 export type StandaloneRuntime = 'node' | 'bun'
 
@@ -49,7 +64,263 @@ const sidecarHandshakeLines = (): string[] => [
   `  console.log(\`${SERVER_READY_MARKER} on http://\${hostname}:\${server.port}\`)`,
 ]
 
-const SIDECAR_RUNTIME_IMPORT = `import { watchParentProcess } from '@pikku/deploy-standalone/runtime'`
+/**
+ * The runtime helpers the entry imports. The database ones are left out of a
+ * build with no database, so the bundle carries no migrator it can never run.
+ */
+const runtimeImport = (ctx: EntryGenerationContext): string => {
+  const names = ['watchParentProcess', 'parseStandaloneCommand']
+  if (ctx.db) names.push('runStandaloneCommand', 'resolveMigrationsDir')
+  return `import { ${names.join(', ')} } from '@pikku/deploy-standalone/runtime'`
+}
+
+/**
+ * Environment variable naming the directory the SQLite file lives in.
+ *
+ * The database has to outlive a release. A deploy that swaps the artifact
+ * directory would take the database with it if the file sat beside the bundle,
+ * so the path comes from the environment and points somewhere the operator
+ * keeps stable across releases, rather than being derived from the bundle's own
+ * location the way the frontend directory is.
+ */
+const DATA_DIR_VAR = 'PIKKU_DATA_DIR'
+
+/**
+ * Full override for the database file, for when it must match a path something
+ * else already decided — notably `pikku db migrate`, which has to open the same
+ * file this opens or the app runs against an unmigrated database.
+ */
+const DATABASE_FILE_VAR = 'PIKKU_DATABASE_FILE'
+
+const DEFAULT_DATABASE_FILENAME = 'pikku.db'
+
+/**
+ * The dialect factory each runtime opens SQLite with. bun cannot use the node
+ * one — `bun:sqlite` is a different driver, and the node build reaches for
+ * `node:sqlite`, which a compiled bun binary does not carry.
+ */
+const SQLITE_FACTORY = {
+  node: {
+    specifier: '@pikku/kysely-node-sqlite',
+    fn: 'createNodeSqliteKysely',
+  },
+  bun: { specifier: '@pikku/kysely-bun-sqlite', fn: 'createBunSqliteKysely' },
+} as const
+
+/**
+ * The environment variable a Postgres build reads its connection string from.
+ *
+ * The same name every other pikku host uses, so an artifact dropped onto a
+ * machine that already runs a pikku app needs no new variable.
+ */
+const DATABASE_URL_VAR = 'DATABASE_URL'
+
+/** Imports the coercion plugin, for an app that generated a map. */
+const coercionImportLines = (coercionImportPath: string): string[] => [
+  `import { createCoercionPlugin } from '@pikku/kysely'`,
+  `import { coercionMap as __pikkuCoercionMap } from '${coercionImportPath}'`,
+]
+
+/** Imports a database-backed entry needs on top of the common set. */
+const dbImportLines = (
+  runtime: 'node' | 'bun',
+  db: NonNullable<EntryGenerationContext['db']>
+): string[] => [
+  ...(db.engine === 'sqlite'
+    ? [
+        `import { ${SQLITE_FACTORY[runtime].fn} } from '${SQLITE_FACTORY[runtime].specifier}'`,
+        `import { mkdirSync as __pikkuMkdirSync } from 'node:fs'`,
+      ]
+    : [`import { PikkuKysely } from '@pikku/kysely-postgres'`]),
+  ...(db.coercionImportPath ? coercionImportLines(db.coercionImportPath) : []),
+]
+
+/**
+ * Opens the database before services are built, so `createSingletonServices`
+ * receives `kysely` exactly as a hosted runtime would hand it over.
+ *
+ * Creating the directory rather than requiring it is deliberate: the artifact
+ * is expected to start on a machine where nothing has run yet, and a missing
+ * parent directory is the difference between a first boot that works and one
+ * that needs a documented mkdir nobody reads.
+ */
+const dbSetupLines = (
+  runtime: 'node' | 'bun',
+  db: NonNullable<EntryGenerationContext['db']>
+): string[] => {
+  const plugins = db.coercionImportPath
+    ? `[createCoercionPlugin({ map: __pikkuCoercionMap })]`
+    : `[]`
+
+  if (db.engine === 'sqlite') {
+    return [
+      `  const __pikkuDbFile = process.env.${DATABASE_FILE_VAR}`,
+      `    ? process.env.${DATABASE_FILE_VAR}`,
+      `    : __pikkuJoin(__pikkuRequireDataDir(), '${DEFAULT_DATABASE_FILENAME}')`,
+      `  __pikkuMkdirSync(__pikkuDirname(__pikkuDbFile), { recursive: true })`,
+      `  const kysely = ${SQLITE_FACTORY[runtime].fn}({`,
+      `    filename: __pikkuDbFile,`,
+      `    plugins: ${plugins},`,
+      `  })`,
+    ]
+  }
+
+  return [
+    `  const __pikkuDbUrl = process.env.${DATABASE_URL_VAR}`,
+    `  if (!__pikkuDbUrl) {`,
+    `    throw new Error(`,
+    `      'This build connects to Postgres, so it needs ${DATABASE_URL_VAR} set to the database it should open.'`,
+    `    )`,
+    `  }`,
+    `  const __pikkuPg = new PikkuKysely(logger, __pikkuDbUrl)`,
+    `  await __pikkuPg.init()`,
+    ...(db.coercionImportPath
+      ? [
+          `  const kysely = __pikkuPg.kysely.withPlugin(`,
+          `    createCoercionPlugin({ map: __pikkuCoercionMap })`,
+          `  )`,
+        ]
+      : [`  const kysely = __pikkuPg.kysely`]),
+  ]
+}
+
+/**
+ * Where the migrations sit relative to the running artifact.
+ *
+ * A node bundle reads them from its own directory. A compiled bun binary has no
+ * directory — `import.meta.url` points inside the embedded filesystem — so it
+ * resolves them beside the executable, which is where an operator unpacking an
+ * artifact puts them.
+ */
+const bundleDirExpression = (runtime: 'node' | 'bun'): string =>
+  runtime === 'node'
+    ? `__pikkuDirname(__pikkuFileURLToPath(import.meta.url))`
+    : `__pikkuDirname(process.execPath)`
+
+/**
+ * The command line, parsed before anything is opened.
+ *
+ * `version` and `help` have to answer without a database, a config factory or a
+ * port, because the machine asking may be one where none of the three work yet
+ * — which is exactly when someone runs them.
+ */
+const commandParseLines = (ctx: EntryGenerationContext): string[] => [
+  `const __pikkuCommand = parseStandaloneCommand(process.argv.slice(2), {`,
+  `  version: '${(ctx.version ?? 'unknown').replace(/'/g, "\\'")}',`,
+  `  hasDb: ${Boolean(ctx.db)},`,
+  ...(ctx.db ? [`  engine: '${ctx.db.engine}',`] : []),
+  `})`,
+  `if (__pikkuCommand.kind === 'exit') process.exit(__pikkuCommand.code)`,
+]
+
+/**
+ * Runs a non-serve command against the database the app itself just opened, and
+ * stops before a port is bound.
+ *
+ * Reusing the app's own connection is the point: a command that resolved its
+ * own would be free to migrate a different database than the next `serve`
+ * reads, and the two would only disagree once in production.
+ */
+const commandDispatchLines = (
+  runtime: 'node' | 'bun',
+  ctx: EntryGenerationContext
+): string[] => {
+  if (!ctx.db) {
+    return [`  if (__pikkuCommand.kind !== 'serve') process.exit(0)`, ``]
+  }
+
+  const dir = `__pikkuJoin(${bundleDirExpression(runtime)}, 'db', '${ctx.db.engine}')`
+  const handle =
+    ctx.db.engine === 'sqlite'
+      ? `databaseFile: __pikkuDbFile,`
+      : `sql: __pikkuPg.sql,`
+
+  return [
+    `  const __pikkuDbCommandTarget = {`,
+    `    engine: '${ctx.db.engine}',`,
+    `    migrationsDir: resolveMigrationsDir(${dir}),`,
+    `    ${handle}`,
+    `  }`,
+    `  if ((await runStandaloneCommand(__pikkuCommand, __pikkuDbCommandTarget)) === 'done') {`,
+    ...(ctx.db.engine === 'postgres' ? [`    await __pikkuPg.close()`] : []),
+    `    return`,
+    `  }`,
+    ``,
+  ]
+}
+
+/** Imports the app's own lifecycle module, when it declares one. */
+const lifecycleImportLines = (
+  lifecycle: NonNullable<EntryGenerationContext['lifecycle']>
+): string[] => [
+  `import { ${lifecycle.variable} as __pikkuLifecycle } from '${lifecycle.importPath}'`,
+]
+
+/**
+ * Runs the app's start hooks around the port opening, the same order and the
+ * same services `pikku dev` gives them.
+ *
+ * `beforeStart` runs after `init` so a hook can rely on everything the server
+ * resolved, and before `start` so work that must finish before the first
+ * request — a seeded admin account, a schema probe — is finished when one
+ * arrives.
+ */
+const lifecycleStartLines = (): string[] => [
+  `  await __pikkuLifecycle?.beforeStart?.(singletonServices)`,
+]
+
+const lifecycleAfterStartLines = (): string[] => [
+  `  await __pikkuLifecycle?.afterStart?.(singletonServices)`,
+]
+
+/**
+ * Hands the stop hooks to the signal handler that owns the shutdown.
+ *
+ * The connection pool is closed in `afterStop`, once the app's own hook and the
+ * server have both finished with it — a pool closed any earlier takes the
+ * queries they are still allowed to make down with it. SQLite needs no
+ * counterpart: the process exiting releases the file.
+ */
+const shutdownHooksArg = (ctx: EntryGenerationContext): string => {
+  const before: string[] = []
+  const after: string[] = []
+
+  if (ctx.lifecycle) {
+    before.push(`await __pikkuLifecycle?.beforeStop?.(singletonServices)`)
+    after.push(`await __pikkuLifecycle?.afterStop?.(singletonServices)`)
+  }
+  if (ctx.db?.engine === 'postgres') {
+    after.push(`await __pikkuPg.close()`)
+  }
+
+  if (before.length === 0 && after.length === 0) return ''
+
+  const hooks: string[] = []
+  if (before.length > 0) {
+    hooks.push(`beforeStop: async () => { ${before.join('; ')} }`)
+  }
+  if (after.length > 0) {
+    hooks.push(`afterStop: async () => { ${after.join('; ')} }`)
+  }
+  return `{ ${hooks.join(', ')} }`
+}
+
+/**
+ * Fails with the variable's name rather than whatever SQLite says about a path
+ * of `undefined/pikku.db`, which is the error an operator would otherwise have
+ * to work backwards from.
+ */
+const dataDirHelperLines = (): string[] => [
+  `function __pikkuRequireDataDir() {`,
+  `  const dir = process.env.${DATA_DIR_VAR}`,
+  `  if (!dir) {`,
+  `    throw new Error(`,
+  `      'This build bundles a SQLite database, so it needs somewhere to keep it. Set ${DATA_DIR_VAR} to a writable directory that survives a release swap, or set ${DATABASE_FILE_VAR} to the database file itself.'`,
+  `    )`,
+  `  }`,
+  `  return dir`,
+  `}`,
+]
 
 /**
  * `rustc -vV`, or nothing when no toolchain is installed. The triple then falls
@@ -84,6 +355,21 @@ export interface StandaloneProviderAdapterOptions {
    * The window is a webview onto that origin and nothing else is shipped.
    */
   desktopUrl?: string
+  contributors?: PlatformServiceContributor[]
+}
+
+const contributorPlatform = (
+  ctx: EntryGenerationContext
+): ContributorPlatform => {
+  const services = ctx.unit.services ?? []
+  return {
+    serviceNames: services.map((s) => s.sourceServiceName),
+    needsQueue: services.some((s) => s.capability === 'queue'),
+    needsWorkflow: services.some((s) => s.capability === 'workflow-state'),
+    needsAgent: services.some(
+      (s) => s.capability === 'ai-storage' || s.capability === 'ai-model'
+    ),
+  }
 }
 
 export class StandaloneProviderAdapter implements ProviderAdapter {
@@ -95,6 +381,7 @@ export class StandaloneProviderAdapter implements ProviderAdapter {
   readonly projectDir?: string
   readonly desktopIdentifier?: string
   readonly desktopUrl?: string
+  readonly contributors: PlatformServiceContributor[]
 
   constructor(options: StandaloneProviderAdapterOptions = {}) {
     this.runtime = options.runtime ?? 'node'
@@ -102,6 +389,48 @@ export class StandaloneProviderAdapter implements ProviderAdapter {
     this.projectDir = options.projectDir
     this.desktopIdentifier = options.desktopIdentifier
     this.desktopUrl = options.desktopUrl
+    this.contributors = dedupeContributors(options.contributors)
+    assertContributorsSupported(
+      this.contributors,
+      STANDALONE_BINDING_SOURCES,
+      this.name
+    )
+  }
+
+  private contributorImportLines(ctx: EntryGenerationContext): string[] {
+    if (this.contributors.length === 0) return []
+    return collectContributorImports(
+      this.contributors,
+      contributorPlatform(ctx)
+    )
+  }
+
+  private platformServicesBlock(ctx: EntryGenerationContext): string[] {
+    if (this.contributors.length === 0) return []
+    return [
+      `const createPlatformServices = async (env: Record<string, string | undefined>): Promise<${ctx.servicesType}> => {`,
+      `  const services: ${ctx.servicesType} = {}`,
+      ...collectContributorLines(this.contributors, {
+        ctx,
+        platform: contributorPlatform(ctx),
+        isGateway: false,
+      }),
+      `  return services`,
+      `}`,
+      ``,
+    ]
+  }
+
+  private platformServicesCallLines(): string[] {
+    if (this.contributors.length === 0) return []
+    return [
+      `  const platformServices = await createPlatformServices(process.env as Record<string, string | undefined>)`,
+    ]
+  }
+
+  private platformServicesSpreadLines(): string[] {
+    if (this.contributors.length === 0) return []
+    return [`    ...platformServices,`]
   }
 
   generateEntrySource(ctx: EntryGenerationContext): string {
@@ -122,13 +451,16 @@ export class StandaloneProviderAdapter implements ProviderAdapter {
       `import { PikkuNodeHTTPServer } from '@pikku/node-http-server'`,
       `import { DEFAULT_WS_MAX_PAYLOAD, pikkuWebsocketHandler } from '@pikku/ws'`,
       `import { WebSocketServer } from 'ws'`,
-      SIDECAR_RUNTIME_IMPORT,
-      ...(ctx.frontend
+      runtimeImport(ctx),
+      ...(ctx.frontend || ctx.db
         ? [
             `import { dirname as __pikkuDirname, join as __pikkuJoin } from 'node:path'`,
             `import { fileURLToPath as __pikkuFileURLToPath } from 'node:url'`,
           ]
         : []),
+      ...(ctx.db ? dbImportLines('node', ctx.db) : []),
+      ...(ctx.lifecycle ? lifecycleImportLines(ctx.lifecycle) : []),
+      ...this.contributorImportLines(ctx),
       ``,
       ctx.configImport,
       ctx.servicesImport,
@@ -140,8 +472,12 @@ export class StandaloneProviderAdapter implements ProviderAdapter {
       `const port = parseInt(process.env.PORT || '3000', 10)`,
       `const hostname = process.env.HOST || '0.0.0.0'`,
       ``,
+      ...commandParseLines(ctx),
+      ``,
+      ...this.platformServicesBlock(ctx),
       `async function main() {`,
       `  const config = await ${ctx.configVar}()`,
+      ...this.platformServicesCallLines(),
       `  const schedulerService = new InMemorySchedulerService()`,
       `  const queueService = new InMemoryQueueService()`,
       `  const workflowService = new InMemoryWorkflowService()`,
@@ -149,14 +485,18 @@ export class StandaloneProviderAdapter implements ProviderAdapter {
       `  const eventHub = new LocalEventHubService()`,
       `  workflowService.wireQueueWorkers()`,
       `  wireAgentScorerQueueWorkers()`,
+      ...(ctx.db ? dbSetupLines('node', ctx.db) : []),
+      ...commandDispatchLines('node', ctx),
       `  const singletonServices = await ${ctx.servicesVar}(config, {`,
       `    logger,`,
+      ...(ctx.db ? [`    kysely,`] : []),
       `    schedulerService,`,
       `    queueService,`,
       `    workflowService,`,
       `    workflowRunService: workflowService,`,
       `    triggerService,`,
       `    eventHub,`,
+      ...this.platformServicesSpreadLines(),
       `  })`,
       `  pikkuState(null, 'package', 'singletonServices', singletonServices)`,
       ``,
@@ -185,8 +525,10 @@ export class StandaloneProviderAdapter implements ProviderAdapter {
       `  await server.init()`,
       `  await schedulerService.start()`,
       `  await triggerService.start()`,
-      `  server.enableExitOnSignals()`,
+      ...(ctx.lifecycle ? lifecycleStartLines() : []),
+      `  server.enableExitOnSignals(${shutdownHooksArg(ctx)})`,
       `  await server.start()`,
+      ...(ctx.lifecycle ? lifecycleAfterStartLines() : []),
       ...sidecarHandshakeLines(),
       `}`,
       ``,
@@ -195,6 +537,7 @@ export class StandaloneProviderAdapter implements ProviderAdapter {
       `  process.exit(1)`,
       `})`,
       ``,
+      ...(ctx.db?.engine === 'sqlite' ? [...dataDirHelperLines(), ``] : []),
     ].join('\n')
   }
 
@@ -202,7 +545,7 @@ export class StandaloneProviderAdapter implements ProviderAdapter {
     return [
       `// Generated standalone entry (bun runtime) — all functions in one process`,
       `import { ConsoleLogger, InMemoryQueueService, InMemoryTriggerService, InMemoryWorkflowService } from '@pikku/core/services'`,
-      SIDECAR_RUNTIME_IMPORT,
+      runtimeImport(ctx),
       `import { pikkuState } from '@pikku/core/state'`,
       `import { wireAgentScorerQueueWorkers } from '@pikku/core/agent-scorer'`,
       `import { InMemorySchedulerService } from '@pikku/schedule'`,
@@ -210,6 +553,14 @@ export class StandaloneProviderAdapter implements ProviderAdapter {
       ...(ctx.frontend
         ? [`import { frontendAssets } from '${STANDALONE_FRONTEND_MANIFEST}'`]
         : []),
+      ...(ctx.db
+        ? [
+            `import { dirname as __pikkuDirname, join as __pikkuJoin } from 'node:path'`,
+          ]
+        : []),
+      ...(ctx.db ? dbImportLines('bun', ctx.db) : []),
+      ...(ctx.lifecycle ? lifecycleImportLines(ctx.lifecycle) : []),
+      ...this.contributorImportLines(ctx),
       ``,
       ctx.configImport,
       ctx.servicesImport,
@@ -221,8 +572,12 @@ export class StandaloneProviderAdapter implements ProviderAdapter {
       `const port = parseInt(process.env.PORT || '3000', 10)`,
       `const hostname = process.env.HOST || '0.0.0.0'`,
       ``,
+      ...commandParseLines(ctx),
+      ``,
+      ...this.platformServicesBlock(ctx),
       `async function main() {`,
       `  const config = await ${ctx.configVar}()`,
+      ...this.platformServicesCallLines(),
       `  const schedulerService = new InMemorySchedulerService()`,
       `  const queueService = new InMemoryQueueService()`,
       `  const workflowService = new InMemoryWorkflowService()`,
@@ -230,14 +585,18 @@ export class StandaloneProviderAdapter implements ProviderAdapter {
       `  const eventHub = new BunEventHubService()`,
       `  workflowService.wireQueueWorkers()`,
       `  wireAgentScorerQueueWorkers()`,
+      ...(ctx.db ? dbSetupLines('bun', ctx.db) : []),
+      ...commandDispatchLines('bun', ctx),
       `  const singletonServices = await ${ctx.servicesVar}(config, {`,
       `    logger,`,
+      ...(ctx.db ? [`    kysely,`] : []),
       `    schedulerService,`,
       `    queueService,`,
       `    workflowService,`,
       `    workflowRunService: workflowService,`,
       `    triggerService,`,
       `    eventHub,`,
+      ...this.platformServicesSpreadLines(),
       `  })`,
       `  pikkuState(null, 'package', 'singletonServices', singletonServices)`,
       ``,
@@ -258,8 +617,10 @@ export class StandaloneProviderAdapter implements ProviderAdapter {
       `  await server.init()`,
       `  await schedulerService.start()`,
       `  await triggerService.start()`,
-      `  server.enableExitOnSignals()`,
+      ...(ctx.lifecycle ? lifecycleStartLines() : []),
+      `  server.enableExitOnSignals(${shutdownHooksArg(ctx)})`,
       `  await server.start()`,
+      ...(ctx.lifecycle ? lifecycleAfterStartLines() : []),
       ...sidecarHandshakeLines(),
       `}`,
       ``,
@@ -268,6 +629,7 @@ export class StandaloneProviderAdapter implements ProviderAdapter {
       `  process.exit(1)`,
       `})`,
       ``,
+      ...(ctx.db?.engine === 'sqlite' ? [...dataDirHelperLines(), ``] : []),
     ].join('\n')
   }
 
@@ -294,6 +656,31 @@ export class StandaloneProviderAdapter implements ProviderAdapter {
     return externals
   }
 
+  /**
+   * The SQLite driver this runtime cannot load.
+   *
+   * `loadSqliteRuntime` picks its driver by looking for `globalThis.Bun`, so a
+   * node process never runs the bun branch — but esbuild still follows the
+   * import, and `bun:sqlite` sits at the top of that module as a static import
+   * it cannot resolve. Left in, the bundle fails to build; marked external, it
+   * becomes a top-level import node fails to load. Stubbing removes the branch
+   * that was already dead.
+   */
+  getStubModules(): string[] {
+    if (this.runtime === 'bun') return []
+    return ['sqlite-runtime-bun']
+  }
+
+  /**
+   * The bun bundle is not the artifact that runs — `bun build --compile` turns
+   * it into the binary — so esbuild must not rename anything bun will rename
+   * again. See `getMangleIdentifiers` on the adapter interface for the boot
+   * failure the two passes produce together.
+   */
+  getMangleIdentifiers(): boolean {
+    return this.runtime !== 'bun'
+  }
+
   getPlatform(): 'node' {
     return 'node'
   }

package/src/contributors.test.ts

@@ -0,0 +1,96 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import type { PlatformServiceContributor } from '@pikku/deploy'
+
+import { StandaloneProviderAdapter } from './adapter.js'
+
+const ctx = {
+  unit: {
+    name: 'app',
+    role: 'function',
+    services: [{ capability: 'kv', sourceServiceName: 'browser' }],
+  },
+  unitDir: '/build/app',
+  bootstrapPath: './.pikku/pikku-bootstrap.gen.js',
+  configImport: `import { createConfig } from './config.js'`,
+  configVar: 'createConfig',
+  servicesImport: `import { createSingletonServices } from './services.js'`,
+  servicesVar: 'createSingletonServices',
+  singletonServicesImport: '',
+  servicesType: 'Record<string, unknown>',
+  mcpImport: '',
+  mcpServerOption: '',
+} as never
+
+const kysely: PlatformServiceContributor = {
+  name: 'kysely',
+  imports: [`import { Kysely } from 'kysely'`],
+  emit: () => [`  if (env.DATABASE_URL) services.kysely = new Kysely({})`],
+}
+
+const browser: PlatformServiceContributor = {
+  name: 'browser',
+  imports: (platform) =>
+    platform.serviceNames.includes('browser')
+      ? [`import { Browser } from './browser.js'`]
+      : [],
+  emit: () => [`  services.browser = new Browser(env, logger)`],
+}
+
+const queueBinding: PlatformServiceContributor = {
+  name: 'queue-binding',
+  requires: ['cloudflare'],
+  emit: () => [`  services.queue = env.QUEUE`],
+}
+
+for (const runtime of ['node', 'bun'] as const) {
+  describe(`StandaloneProviderAdapter contributors (${runtime})`, () => {
+    test('without contributors the entry has no platform services block', () => {
+      const source = new StandaloneProviderAdapter({
+        runtime,
+      }).generateEntrySource(ctx)
+
+      assert.doesNotMatch(source, /createPlatformServices/)
+      assert.doesNotMatch(source, /platformServices/)
+    })
+
+    test('contributor imports, lines and the spread are all emitted', () => {
+      const source = new StandaloneProviderAdapter({
+        runtime,
+        contributors: [kysely, browser],
+      }).generateEntrySource(ctx)
+
+      assert.match(source, /import { Kysely } from 'kysely'/)
+      assert.match(source, /import { Browser } from '\.\/browser\.js'/)
+      assert.match(
+        source,
+        /const createPlatformServices = async \(env: Record<string, string \| undefined>\): Promise<Record<string, unknown>> => \{/
+      )
+      assert.match(
+        source,
+        /if \(env\.DATABASE_URL\) services\.kysely = new Kysely\(\{\}\)/
+      )
+      assert.match(source, /services\.browser = new Browser\(env, logger\)/)
+      assert.match(
+        source,
+        /const platformServices = await createPlatformServices\(process\.env as Record<string, string \| undefined>\)/
+      )
+      assert.match(
+        source,
+        /eventHub,\n    \.\.\.platformServices,\n  \}\)/,
+        'contributed services must be spread last so they override the defaults'
+      )
+    })
+
+    test('a contributor that needs cloudflare bindings is refused up front', () => {
+      assert.throws(
+        () =>
+          new StandaloneProviderAdapter({
+            runtime,
+            contributors: [kysely, queueBinding],
+          }),
+        /standalone adapter only provides env bindings; unsupported contributors: queue-binding \(requires cloudflare\)/
+      )
+    })
+  })
+}

package/src/index.ts

@@ -17,6 +17,7 @@ import {
 
 export { StandaloneProviderAdapter }
 export type { StandaloneProviderAdapterOptions } from './adapter.js'
+export type { PlatformServiceContributor } from '@pikku/deploy'
 
 export const createAdapter = (options?: StandaloneProviderAdapterOptions) =>
   new StandaloneProviderAdapter(options)