infra-kit 0.1.126 → 0.1.128

package/src/dev/__tests__/discovery.test.ts

@@ -0,0 +1,181 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import {
+  classifyDistChange,
+  discoverApiApps,
+  discoverUiApps,
+  findMonorepoRoot,
+  getAppDistDirs,
+  getPackageDistDirs,
+  getPackageName,
+  normalizeAppInclude,
+} from 'src/dev/discovery'
+
+import { createTempTracker, makeMonorepo } from './fixtures'
+
+/**
+ * Filesystem discovery, driven by an explicit `root` argument — no chdir, no cast.
+ * Each spec builds a hermetic monorepo fixture and passes its path straight in.
+ */
+const temp = createTempTracker()
+
+afterEach(() => {
+  temp.cleanup()
+})
+
+describe('discoverApiApps — app discovery', () => {
+  it('discovers every apps/<app> that has an api/serverless.yml', () => {
+    const root = temp.register(makeMonorepo([{ name: 'client' }, { name: 'backoffice' }]))
+
+    const names = discoverApiApps(root)
+      .map((a) => {
+        return a.name
+      })
+      .sort()
+
+    expect(names).toEqual(['backoffice', 'client'])
+  })
+
+  it('ignores app folders that have no serverless.yml', () => {
+    const root = temp.register(makeMonorepo([{ name: 'client' }, { name: 'web', api: false }]))
+
+    const names = discoverApiApps(root).map((a) => {
+      return a.name
+    })
+
+    expect(names).toEqual(['client'])
+  })
+
+  it('reads packageName from package.json, falling back to the folder name', () => {
+    const root = temp.register(
+      makeMonorepo([{ name: 'client', packageName: 'sls-trvl-client' }, { name: 'backoffice' }]),
+    )
+
+    const byName = new Map(
+      discoverApiApps(root).map((a) => {
+        return [a.name, a.packageName]
+      }),
+    )
+
+    expect(byName.get('client')).toBe('sls-trvl-client')
+    expect(byName.get('backoffice')).toBe('backoffice')
+  })
+})
+
+describe('findMonorepoRoot — walk up to pnpm-workspace.yaml', () => {
+  it('returns the dir that holds pnpm-workspace.yaml when starting from a nested api dir', () => {
+    const root = temp.register(makeMonorepo([{ name: 'client' }]))
+    const startDir = path.join(root, 'apps', 'client', 'api')
+
+    expect(findMonorepoRoot(startDir)).toBe(root)
+  })
+})
+
+describe('getPackageName — package.json name with fallback', () => {
+  it('returns the package.json name field when present', () => {
+    const root = temp.register(makeMonorepo([{ name: 'client', packageName: 'sls-trvl-client' }]))
+    const apiDir = path.join(root, 'apps', 'client', 'api')
+
+    expect(getPackageName(apiDir, 'client')).toBe('sls-trvl-client')
+  })
+
+  it('falls back to the given app name when there is no package.json', () => {
+    const root = temp.register(makeMonorepo([{ name: 'backoffice' }]))
+    const apiDir = path.join(root, 'apps', 'backoffice', 'api')
+
+    expect(getPackageName(apiDir, 'backoffice')).toBe('backoffice')
+  })
+})
+
+describe('normalizeAppInclude — --app list normalization', () => {
+  it('normalizes empty, whitespace-only, undefined, and null lists to null', () => {
+    expect(normalizeAppInclude([])).toBeNull()
+    expect(normalizeAppInclude([''])).toBeNull()
+    expect(normalizeAppInclude(undefined)).toBeNull()
+    expect(normalizeAppInclude(null)).toBeNull()
+  })
+
+  it('keeps a non-empty list and drops falsy entries', () => {
+    expect(normalizeAppInclude(['client', ''])).toEqual(['client'])
+  })
+})
+
+describe('classifyDistChange — route a compiled-output path to app vs package', () => {
+  const appDistDirs = ['/repo/apps/client/api/dist']
+  const packageDistDirs = ['/repo/packages/lib-core/dist']
+
+  it('classifies an app-dist path as an app change and returns the matched app dist dir', () => {
+    const change = classifyDistChange('/repo/apps/client/api/dist/controllers/x.js', appDistDirs, packageDistDirs)
+
+    expect(change).toEqual({ kind: 'app', app: '/repo/apps/client/api/dist' })
+  })
+
+  it('classifies a package-dist path as a package change (a lib was rebuilt → restart all)', () => {
+    const change = classifyDistChange('/repo/packages/lib-core/dist/index.js', appDistDirs, packageDistDirs)
+
+    expect(change).toEqual({ kind: 'package' })
+  })
+
+  it('returns an app change with undefined dir when nothing matches', () => {
+    const change = classifyDistChange('/repo/elsewhere/dist/x.js', appDistDirs, packageDistDirs)
+
+    expect(change).toEqual({ kind: 'app', app: undefined })
+  })
+})
+
+describe('getPackageDistDirs / getAppDistDirs — existing dist dirs only', () => {
+  it('returns packages/<pkg>/dist dirs that exist and skips those without a dist', () => {
+    const root = temp.register(makeMonorepo([{ name: 'client', withHandler: true }]))
+
+    // makeMonorepo only scaffolds apps/*; add a packages/ tree with one built + one unbuilt pkg.
+    fs.mkdirSync(path.join(root, 'packages', 'lib-core', 'dist'), { recursive: true })
+    fs.mkdirSync(path.join(root, 'packages', 'lib-unbuilt', 'src'), { recursive: true })
+
+    const distDirs = getPackageDistDirs(root)
+
+    expect(distDirs).toContain(path.join(root, 'packages', 'lib-core', 'dist'))
+    expect(distDirs).not.toContain(path.join(root, 'packages', 'lib-unbuilt', 'dist'))
+  })
+
+  it('returns <app.path>/dist dirs that exist (withHandler apps have one)', () => {
+    const root = temp.register(makeMonorepo([{ name: 'client', withHandler: true }]))
+    const apiDir = path.join(root, 'apps', 'client', 'api')
+
+    const distDirs = getAppDistDirs([{ path: apiDir }])
+
+    expect(distDirs).toEqual([path.join(apiDir, 'dist')])
+  })
+})
+
+describe('discoverUiApps — frontends with a `dev` script', () => {
+  it('discovers apps/<app>/ui that declare a dev script, resolving the package name', () => {
+    const root = temp.register(
+      makeMonorepo([
+        { name: 'backoffice', ui: { packageName: 'backoffice-ui' } },
+        { name: 'client', ui: { packageName: 'website-ui' } },
+      ]),
+    )
+
+    const uiApps = discoverUiApps(root)
+
+    expect(uiApps).toEqual([
+      { name: 'backoffice', packageName: 'backoffice-ui', path: path.join(root, 'apps', 'backoffice', 'ui') },
+      { name: 'client', packageName: 'website-ui', path: path.join(root, 'apps', 'client', 'ui') },
+    ])
+  })
+
+  it('ignores a ui folder that has no dev script', () => {
+    const root = temp.register(makeMonorepo([{ name: 'seo', ui: { dev: false } }]))
+
+    expect(discoverUiApps(root)).toEqual([])
+  })
+
+  it('returns [] when there is no apps/ dir (UIs are optional, unlike api discovery)', () => {
+    const root = temp.register(makeMonorepo([]))
+
+    fs.rmSync(path.join(root, 'apps'), { recursive: true, force: true })
+    expect(discoverUiApps(root)).toEqual([])
+  })
+})

package/src/dev/__tests__/fixtures.ts

@@ -0,0 +1,257 @@
+/**
+ * Shared test fixtures for the dev-server suites.
+ *
+ * Everything here is hermetic: temp dirs are created under the OS tmp dir and
+ * returned to the caller (register them with a {@link createTempTracker} so an
+ * `afterEach` can remove them). No module-level side effects — importing this
+ * file never touches the filesystem, cwd, or env.
+ */
+import * as fs from 'node:fs'
+import * as net from 'node:net'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import process from 'node:process'
+import { vi } from 'vitest'
+
+import { ServerlessLocalRun } from 'src/dev/serverless-local-run'
+
+/** Default URL prefix the fixtures serve routes under (matches the runner default). */
+export const PREFIX = '/api/v1'
+
+/** serverless.yml exposing ping (GET), echo (POST) and item (GET {id}) routes. */
+const SERVERLESS_YML = [
+  'service: testapp',
+  'functions:',
+  '  ping:',
+  '    handler: dist/handler.ping',
+  '    events:',
+  '      - http:',
+  '          method: get',
+  '          path: ping',
+  '  echo:',
+  '    handler: dist/handler.echo',
+  '    events:',
+  '      - http:',
+  '          method: post',
+  '          path: echo',
+  '  item:',
+  '    handler: dist/handler.item',
+  '    events:',
+  '      - http:',
+  '          method: get',
+  '          path: item/{id}',
+  '',
+].join('\n')
+
+/** serverless.yml with a single ping (GET) route — used for monorepo app fixtures. */
+const MONOREPO_SERVERLESS_YML = [
+  'service: svc',
+  'functions:',
+  '  ping:',
+  '    handler: dist/handler.ping',
+  '    events:',
+  '      - http:',
+  '          method: get',
+  '          path: ping',
+  '',
+].join('\n')
+
+/**
+ * Compiled ESM handler written straight to `dist/*.js` (no build step). Each handler
+ * echoes the Lambda event back as its JSON body so the HTTP->Lambda transform can be
+ * asserted from the response. `version` lets a reload test tell v1 from v2 apart.
+ */
+export function handlerSource(version = 1): string {
+  return [
+    `const version = ${version}`,
+    'const reply = (event, extra) => ({',
+    '  statusCode: 200,',
+    "  headers: { 'content-type': 'application/json', 'x-handler-version': String(version) },",
+    '  body: JSON.stringify({ version, event, ...extra }),',
+    '})',
+    'export const ping = async (event) => reply(event, { route: "ping" })',
+    'export const echo = async (event) => reply(event, { route: "echo" })',
+    'export const item = async (event) => reply(event, { route: "item" })',
+    '',
+  ].join('\n')
+}
+
+/** Create an `apps/testapp/api`-shaped fixture with serverless.yml + a compiled dist handler. */
+export function makeApiFixture(handlerVersion = 1): string {
+  const apiDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ik-sls-run-'))
+
+  fs.writeFileSync(path.join(apiDir, 'serverless.yml'), SERVERLESS_YML)
+  // type:module so Node loads the plain dist/*.js as ESM (named exports available).
+  fs.writeFileSync(path.join(apiDir, 'package.json'), JSON.stringify({ name: 'testapp-api', type: 'module' }))
+  fs.mkdirSync(path.join(apiDir, 'dist'), { recursive: true })
+  fs.writeFileSync(path.join(apiDir, 'dist', 'handler.js'), handlerSource(handlerVersion))
+
+  return apiDir
+}
+
+/** One app inside a monorepo fixture. */
+export interface AppSpec {
+  /** App folder name (e.g. client, backoffice). */
+  name: string
+  /** package.json `name`. Omit to leave package.json out (discovery falls back to the folder name). */
+  packageName?: string
+  /** Set false to create the app folder WITHOUT serverless.yml (should be ignored by discovery). */
+  api?: boolean
+  /** Also write package.json (type:module) + a real dist/handler.js so the app can actually boot. */
+  withHandler?: boolean
+  /**
+   * Also scaffold `apps/<name>/ui/package.json`. `dev` (default true) controls whether it declares a
+   * `scripts.dev` — a UI without one must be ignored by {@link discoverUiApps}.
+   */
+  ui?: { packageName?: string; dev?: boolean }
+}
+
+/** Build a hermetic monorepo: pnpm-workspace.yaml + `apps/<app>/api/serverless.yml` per spec. */
+export function makeMonorepo(apps: AppSpec[]): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ik-monorepo-'))
+
+  fs.writeFileSync(path.join(root, 'pnpm-workspace.yaml'), 'packages:\n  - apps/*\n')
+  fs.mkdirSync(path.join(root, 'apps'), { recursive: true })
+
+  for (const app of apps) {
+    const apiDir = path.join(root, 'apps', app.name, 'api')
+
+    fs.mkdirSync(apiDir, { recursive: true })
+    if (app.api !== false) {
+      fs.writeFileSync(path.join(apiDir, 'serverless.yml'), MONOREPO_SERVERLESS_YML)
+    }
+    if (app.packageName != null || app.withHandler) {
+      fs.writeFileSync(
+        path.join(apiDir, 'package.json'),
+        JSON.stringify({ name: app.packageName ?? `${app.name}-api`, type: 'module' }),
+      )
+    }
+    if (app.withHandler) {
+      fs.mkdirSync(path.join(apiDir, 'dist'), { recursive: true })
+      fs.writeFileSync(path.join(apiDir, 'dist', 'handler.js'), handlerSource(1))
+    }
+    if (app.ui) {
+      const uiDir = path.join(root, 'apps', app.name, 'ui')
+
+      fs.mkdirSync(uiDir, { recursive: true })
+      const pkg: { name: string; scripts?: Record<string, string> } = {
+        name: app.ui.packageName ?? `${app.name}-ui`,
+      }
+
+      if (app.ui.dev !== false) pkg.scripts = { dev: 'vite' }
+      fs.writeFileSync(path.join(uiDir, 'package.json'), JSON.stringify(pkg))
+    }
+  }
+
+  return root
+}
+
+/** Ask the OS for a currently-free TCP port on localhost, then release it. */
+export async function getFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = net.createServer()
+
+    srv.unref()
+    srv.on('error', reject)
+    srv.listen(0, '127.0.0.1', () => {
+      const addr = srv.address()
+      const port = typeof addr === 'object' && addr != null ? addr.port : 0
+
+      srv.close(() => {
+        return resolve(port)
+      })
+    })
+  })
+}
+
+/** True if a fresh listener can bind `port` — i.e. the previous server released it. */
+export async function canBind(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const srv = net.createServer()
+
+    srv.once('error', () => {
+      return resolve(false)
+    })
+    srv.listen(port, '127.0.0.1', () => {
+      return srv.close(() => {
+        return resolve(true)
+      })
+    })
+  })
+}
+
+/**
+ * Boot a server against `apiDir` on `port`. No `chdir`: `ServerlessLocalRun` reads
+ * `serverless.yml` and imports the handler from `controllersPath` (absolute), so booting
+ * is cwd-independent. The caller owns the returned server's lifecycle (call `close()` in teardown).
+ */
+export async function boot(
+  apiDir: string,
+  port: number,
+  appName = 'testapp',
+  prefixUrl = PREFIX,
+): Promise<ServerlessLocalRun> {
+  const server = new ServerlessLocalRun({ controllersPath: apiDir, prefixUrl, port, appName })
+
+  await server.start()
+
+  return server
+}
+
+/** A registry of temp dirs so an `afterEach` can remove everything created in a test. */
+export interface TempTracker {
+  /** Register a dir for cleanup and return it (so calls can be inlined). */
+  register: (dir: string) => string
+  /** Remove every registered dir and clear the registry. */
+  cleanup: () => void
+}
+
+export function createTempTracker(): TempTracker {
+  const dirs: string[] = []
+
+  return {
+    register: (dir: string): string => {
+      dirs.push(dir)
+
+      return dir
+    },
+    cleanup: (): void => {
+      for (const dir of dirs.splice(0)) {
+        fs.rmSync(dir, { recursive: true, force: true })
+      }
+    },
+  }
+}
+
+/** Snapshot `process.env` so tests can restore it after mutating per-app port vars. */
+export function snapshotEnv(): NodeJS.ProcessEnv {
+  return { ...process.env }
+}
+
+/** Restore a `process.env` snapshot taken by {@link snapshotEnv}. */
+export function restoreEnv(snapshot: NodeJS.ProcessEnv): void {
+  process.env = { ...snapshot }
+}
+
+/** Snapshot the current working directory (fixtures chdir for serverless.yml resolution). */
+export function snapshotCwd(): string {
+  return process.cwd()
+}
+
+/** Restore a cwd snapshot taken by {@link snapshotCwd}. */
+export function restoreCwd(dir: string): void {
+  process.chdir(dir)
+}
+
+/**
+ * Spy `process.stdout.write`, pushing every written chunk into `sink`. The caller owns
+ * the returned spy's lifecycle (`spy.mockRestore()` in a `finally`). Used by the dev-server
+ * table / route-dump / request-log tests to assert on captured startup + request output.
+ */
+export function spyStdoutWrite(sink: string[]): ReturnType<typeof vi.spyOn> {
+  return vi.spyOn(process.stdout, 'write').mockImplementation(((chunk: unknown): boolean => {
+    sink.push(String(chunk))
+
+    return true
+  }) as never)
+}

package/src/dev/__tests__/ports.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  DEFAULT_PORT,
+  DEFAULT_PREFIX_URL,
+  findPortConflicts,
+  parsePortString,
+  resolvePort,
+  resolvePrefixUrl,
+} from 'src/dev/ports'
+
+/**
+ * Pure port / prefix resolution. Every function is side-effect free, so these
+ * specs pass `env` and `devConfig` in as plain objects — no fixtures, no cwd,
+ * no process.env mutation.
+ */
+describe('resolvePort — precedence order', () => {
+  it('falls back to the 3010 default when nothing is set', () => {
+    expect(resolvePort('client', {}, {})).toBe(DEFAULT_PORT)
+  })
+
+  it('uses dev.<app>.port from config over the default', () => {
+    expect(resolvePort('client', {}, { client: { port: 3200 } })).toBe(3200)
+  })
+
+  it('lets PORT beat the config port', () => {
+    expect(resolvePort('client', { PORT: '3300' }, { client: { port: 3200 } })).toBe(3300)
+  })
+
+  it('lets {APP}_PORT beat PORT and config', () => {
+    expect(resolvePort('client', { PORT: '3300', CLIENT_PORT: '3400' }, { client: { port: 3200 } })).toBe(3400)
+  })
+
+  it('maps a hyphenated app name to UPPER_SNAKE_CASE for the {APP}_PORT key', () => {
+    expect(resolvePort('search-engine', { SEARCH_ENGINE_PORT: '3500' }, {})).toBe(3500)
+  })
+
+  it('honors {APP}_PORT = 0 and does NOT fall through to a lower tier', () => {
+    // 0 is a valid "pick a free port" request; only null/undefined means "unset".
+    expect(resolvePort('client', { CLIENT_PORT: '0' }, { client: { port: 3200 } })).toBe(0)
+  })
+
+  it('strips surrounding quotes on a {APP}_PORT env value', () => {
+    // Secrets managers can export values wrapped in quotes.
+    expect(resolvePort('client', { CLIENT_PORT: '"3400"' }, {})).toBe(3400)
+  })
+})
+
+describe('resolvePrefixUrl — config over default', () => {
+  it('defaults to /api/v1 when nothing is configured', () => {
+    expect(resolvePrefixUrl('client', {})).toBe(DEFAULT_PREFIX_URL)
+  })
+
+  it('honors dev.<app>.prefixUrl over the default', () => {
+    expect(resolvePrefixUrl('client', { client: { prefixUrl: '/custom/v2' } })).toBe('/custom/v2')
+  })
+})
+
+describe('parsePortString — raw port coercion', () => {
+  it('strips a single pair of surrounding quotes', () => {
+    expect(parsePortString('"3400"')).toBe(3400)
+    expect(parsePortString("'3400'")).toBe(3400)
+  })
+
+  it('returns undefined for non-numeric input', () => {
+    expect(parsePortString('abc')).toBeUndefined()
+  })
+
+  it('returns undefined for undefined and blank input', () => {
+    expect(parsePortString(undefined)).toBeUndefined()
+    expect(parsePortString('')).toBeUndefined()
+  })
+})
+
+describe('findPortConflicts — duplicate detection', () => {
+  it('reports the duplicate port and every colliding app when two apps share a port', () => {
+    const result = findPortConflicts([
+      { name: 'client', port: 3010 },
+      { name: 'backoffice', port: 3010 },
+    ])
+
+    expect(result.duplicatePorts).toEqual([3010])
+    expect(result.conflictingApps).toEqual([
+      { name: 'client', port: 3010 },
+      { name: 'backoffice', port: 3010 },
+    ])
+  })
+
+  it('reports no conflict when every app resolves to a distinct port', () => {
+    const result = findPortConflicts([
+      { name: 'client', port: 3010 },
+      { name: 'backoffice', port: 3011 },
+    ])
+
+    expect(result.duplicatePorts).toEqual([])
+    expect(result.conflictingApps).toEqual([])
+  })
+})