refactor: split sync-engine CLI and serve binaries (#310)

Separate the bundled server startup path from the full OpenAPI CLI bootstrap so Docker and local development can use a minimal server entrypoint without CLI-only connector discovery behavior.

Constraint: Keep connector discovery policy at the entrypoint boundary
Confidence: medium
Scope-risk: moderate
Not-tested: Docker daemon-based checks unavailable in this environment
Made-with: Cursor
Committed-By-Agent: cursor

Author: tonyxiao

Dockerfile

@@ -49,8 +49,7 @@ ENV NODE_ENV=production
 ENV GIT_COMMIT=$GIT_COMMIT
 ENV BUILD_DATE=$BUILD_DATE
 ENV COMMIT_URL=$COMMIT_URL
-ENTRYPOINT ["node", "--use-env-proxy", "dist/cli/index.js"]
-CMD ["serve"]
+ENTRYPOINT ["node", "--use-env-proxy", "dist/bin/serve.js"]
 
 # ===========================================================================
 # Service (also used for the worker container — same image, different CMD)

apps/engine/package.json

@@ -5,7 +5,8 @@
   "description": "Stripe Sync Engine — sync Stripe data to Postgres",
   "type": "module",
   "bin": {
-    "sync-engine": "./dist/cli/index.js"
+    "sync-engine": "./dist/bin/sync-engine.js",
+    "sync-engine-serve": "./dist/bin/serve.js"
   },
   "exports": {
     ".": {
@@ -19,9 +20,9 @@
       "import": "./dist/cli/command.js"
     },
     "./api": {
-      "bun": "./src/api/app.ts",
-      "types": "./dist/api/app.d.ts",
-      "import": "./dist/api/app.js"
+      "bun": "./src/api/index.ts",
+      "types": "./dist/api/index.d.ts",
+      "import": "./dist/api/index.js"
     },
     "./api/openapi-utils": {
       "bun": "./src/api/openapi-utils.ts",
@@ -32,7 +33,7 @@
   "scripts": {
     "build": "tsc",
     "x:watch": "sh -c 'if command -v bun > /dev/null 2>&1; then bun --watch \"$@\"; else tsx --watch --conditions bun \"$@\"; fi' --",
-    "dev": "LOG_LEVEL=${LOG_LEVEL:-trace} LOG_PRETTY=${LOG_PRETTY:-true} DANGEROUSLY_VERBOSE_LOGGING=true pnpm x:watch src/api/index.ts",
+    "dev": "LOG_LEVEL=${LOG_LEVEL:-trace} LOG_PRETTY=${LOG_PRETTY:-true} DANGEROUSLY_VERBOSE_LOGGING=true pnpm x:watch src/bin/serve.ts",
     "test": "vitest run",
     "generate:types": "openapi-typescript src/__generated__/openapi.json -o src/__generated__/openapi.d.ts"
   },

apps/engine/src/__tests__/bin-serve.test.ts

@@ -0,0 +1,55 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const bootstrap = vi.fn()
+const resolver = {
+  resolveSource: vi.fn(),
+  resolveDestination: vi.fn(),
+  sources: () => new Map(),
+  destinations: () => new Map(),
+}
+const createConnectorResolver = vi.fn(async () => resolver)
+const startApiServer = vi.fn()
+const defaultConnectors = {
+  sources: { stripe: {} },
+  destinations: { postgres: {}, google_sheets: {} },
+}
+
+vi.mock('../bin/bootstrap.js', () => ({
+  bootstrap,
+}))
+
+vi.mock('../lib/index.js', () => ({
+  createConnectorResolver,
+}))
+
+vi.mock('../lib/default-connectors.js', () => ({
+  defaultConnectors,
+}))
+
+vi.mock('../api/server.js', () => ({
+  startApiServer,
+}))
+
+describe('serve bin', () => {
+  beforeEach(() => {
+    vi.resetModules()
+    vi.clearAllMocks()
+    delete process.env.PORT
+  })
+
+  it('starts the bundled-only server with dynamic discovery disabled', async () => {
+    process.env.PORT = '4010'
+
+    await import('../bin/serve.js')
+
+    expect(bootstrap).toHaveBeenCalledOnce()
+    expect(createConnectorResolver).toHaveBeenCalledWith(defaultConnectors, {
+      path: false,
+      npm: false,
+    })
+    expect(startApiServer).toHaveBeenCalledWith({
+      resolver,
+      port: 4010,
+    })
+  })
+})

apps/engine/src/__tests__/docker.test.ts

@@ -32,12 +32,12 @@ describe('Docker image', { timeout: 180_000 }, () => {
   })
 
   it('--version prints version and exits', () => {
-    const out = docker('run', '--rm', IMAGE, '--version')
+    const out = docker('run', '--rm', '--entrypoint', 'node', IMAGE, 'dist/bin/sync-engine.js', '--version')
     expect(out).toMatch(/\d+\.\d+\.\d+/)
   })
 
   it('--help prints usage and exits', () => {
-    const out = docker('run', '--rm', IMAGE, '--help')
+    const out = docker('run', '--rm', '--entrypoint', 'node', IMAGE, 'dist/bin/sync-engine.js', '--help')
     expect(out).toContain('sync-engine')
     expect(out).toContain('serve')
     expect(out).toContain('sync')
@@ -73,7 +73,17 @@ describe('Docker image', { timeout: 180_000 }, () => {
 
   it('check exits non-zero without valid config', () => {
     expect(() =>
-      docker('run', '--rm', IMAGE, 'check', '--postgres-url', 'postgres://invalid:5432/db')
+      docker(
+        'run',
+        '--rm',
+        '--entrypoint',
+        'node',
+        IMAGE,
+        'dist/bin/sync-engine.js',
+        'check',
+        '--postgres-url',
+        'postgres://invalid:5432/db'
+      )
     ).toThrow()
   })
 })

apps/engine/src/api/index.test.ts

@@ -0,0 +1,49 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const createConnectorResolver = vi.fn(async () => ({}))
+const createApp = vi.fn(async () => ({ fetch: vi.fn() }))
+const startApiServer = vi.fn()
+const serve = vi.fn()
+
+vi.mock('../lib/index.js', () => ({
+  createConnectorResolver,
+}))
+
+vi.mock('./app.js', () => ({
+  createApp,
+}))
+
+vi.mock('./server.js', () => ({
+  startApiServer,
+}))
+
+vi.mock('@hono/node-server', () => ({
+  serve,
+}))
+
+vi.mock('../logger.js', () => ({
+  logger: {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  },
+}))
+
+describe('api/index', () => {
+  beforeEach(() => {
+    vi.resetModules()
+    vi.clearAllMocks()
+    Reflect.deleteProperty(globalThis as Record<string, unknown>, 'Bun')
+  })
+
+  it('exports the API surface without starting a server', async () => {
+    const mod = await import('./index.js')
+
+    expect(typeof mod.createApp).toBe('function')
+    expect(typeof mod.startApiServer).toBe('function')
+    expect(createConnectorResolver).not.toHaveBeenCalled()
+    expect(createApp).not.toHaveBeenCalled()
+    expect(startApiServer).not.toHaveBeenCalled()
+    expect(serve).not.toHaveBeenCalled()
+  })
+})

apps/engine/src/api/index.ts

@@ -1,55 +1,3 @@
-#!/usr/bin/env node
-
-import source from '@stripe/sync-source-stripe'
-import pgDestination from '@stripe/sync-destination-postgres'
-import sheetsDestination from '@stripe/sync-destination-google-sheets'
-import { createConnectorResolver } from '../lib/index.js'
-import { createApp } from './app.js'
-import { logger } from '../logger.js'
-import { ENGINE_SERVER_OPTIONS } from '../http-server-options.js'
-
-const port = Number(process.env.PORT || 3001)
-
-async function main() {
-  if (process.env.DANGEROUSLY_VERBOSE_LOGGING === 'true') {
-    logger.warn(
-      '⚠️  DANGEROUSLY_VERBOSE_LOGGING is enabled — all request headers and message payloads will be logged. Do not use in production.'
-    )
-  }
-
-  const resolver = await createConnectorResolver({
-    sources: { stripe: source },
-    destinations: { postgres: pgDestination, google_sheets: sheetsDestination },
-  })
-  const app = await createApp(resolver)
-
-  // Use the web-standard fetch handler with the runtime's native server.
-  // Bun.serve() properly cancels ReadableStreams on client disconnect;
-  // @hono/node-server is the fallback for Node.js / tsx.
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  if (typeof (globalThis as any).Bun !== 'undefined') {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    ;(globalThis as any).Bun.serve({ fetch: app.fetch, port, idleTimeout: 60 })
-    logger.warn(
-      { port, server: 'Bun.serve' },
-      `Sync Engine API listening on http://localhost:${port}`
-    )
-  } else {
-    const { serve } = await import('@hono/node-server')
-    serve(
-      {
-        fetch: app.fetch,
-        port,
-        serverOptions: ENGINE_SERVER_OPTIONS,
-      },
-      (info) => {
-        logger.info(
-          { port: info.port },
-          `Sync Engine API listening on http://localhost:${info.port}`
-        )
-      }
-    )
-  }
-}
-
-main()
+export { createApp } from './app.js'
+export { startApiServer } from './server.js'
+export type { StartApiServerOptions } from './server.js'

apps/engine/src/api/server.ts

@@ -0,0 +1,56 @@
+import { serve } from '@hono/node-server'
+import type { ConnectorResolver } from '../lib/index.js'
+import { createApp } from './app.js'
+import { logger } from '../logger.js'
+import { ENGINE_SERVER_OPTIONS } from '../http-server-options.js'
+
+export interface StartApiServerOptions {
+  resolver: ConnectorResolver
+  port?: number
+}
+
+type BunLike = {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  serve: (options: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    fetch: (...args: any[]) => unknown
+    port: number
+    idleTimeout?: number
+  }) => unknown
+}
+
+export async function startApiServer({ resolver, port }: StartApiServerOptions) {
+  const listenPort = port ?? Number(process.env['PORT'] || 3000)
+
+  if (process.env.DANGEROUSLY_VERBOSE_LOGGING === 'true') {
+    logger.warn(
+      '⚠️  DANGEROUSLY_VERBOSE_LOGGING is enabled — all request headers and message payloads will be logged. Do not use in production.'
+    )
+  }
+
+  const app = await createApp(resolver)
+  const bun = (globalThis as typeof globalThis & { Bun?: BunLike }).Bun
+
+  if (bun) {
+    bun.serve({ fetch: app.fetch, port: listenPort, idleTimeout: 60 })
+    logger.warn(
+      { port: listenPort, server: 'Bun.serve' },
+      `Sync Engine API listening on http://localhost:${listenPort}`
+    )
+    return
+  }
+
+  return serve(
+    {
+      fetch: app.fetch,
+      port: listenPort,
+      serverOptions: ENGINE_SERVER_OPTIONS,
+    },
+    (info) => {
+      logger.info(
+        { port: info.port },
+        `Sync Engine API listening on http://localhost:${info.port}`
+      )
+    }
+  )
+}

apps/engine/src/bin/bootstrap.ts

@@ -0,0 +1,6 @@
+import 'dotenv/config'
+import { assertUseEnvProxy } from '@stripe/sync-ts-cli/env-proxy'
+
+export function bootstrap() {
+  assertUseEnvProxy()
+}

apps/engine/src/bin/serve.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { startApiServer } from '../api/server.js'
+import { defaultConnectors } from '../lib/default-connectors.js'
+import { createConnectorResolver } from '../lib/index.js'
+import { bootstrap } from './bootstrap.js'
+
+bootstrap()
+
+const resolver = await createConnectorResolver(defaultConnectors, {
+  path: false,
+  npm: false,
+})
+
+await startApiServer({
+  resolver,
+  port: process.env['PORT'] ? Number(process.env['PORT']) : undefined,
+})

apps/engine/src/bin/sync-engine.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runMain } from 'citty'
+import { createProgram } from '../cli/command.js'
+import { bootstrap } from './bootstrap.js'
+
+bootstrap()
+
+const program = await createProgram()
+runMain(program)