infra-kit 0.1.126 → 0.1.128

package/src/dev/discovery.ts

@@ -0,0 +1,229 @@
+/**
+ * Filesystem discovery helpers for the dev-server.
+ *
+ * These functions read the filesystem (walking for the monorepo root, scanning
+ * `apps/` and `packages/`) but never `chdir` and never resolve ports / prefixes —
+ * that stays with the pure {@link file://./ports.ts} layer. The starting directory
+ * is passed in so discovery is testable against a fixture root.
+ */
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+/** Bare metadata for a discovered API app (no resolved port / prefix). */
+export interface DiscoveredApiApp {
+  /** App folder name (e.g. backoffice, client). */
+  name: string
+  /** Package name from package.json (e.g. sls-trvl-client), or the folder name as fallback. */
+  packageName: string
+  path: string
+}
+
+/** Walk up from `startDir` (max 10 levels) to the dir containing `pnpm-workspace.yaml`. */
+export function findMonorepoRoot(startDir: string): string {
+  let currentDir = startDir
+
+  for (let i = 0; i < 10; i++) {
+    const workspaceFile = path.join(currentDir, 'pnpm-workspace.yaml')
+
+    if (fs.existsSync(workspaceFile)) {
+      return currentDir
+    }
+    currentDir = path.dirname(currentDir)
+  }
+
+  throw new Error('Could not find monorepo root (pnpm-workspace.yaml)')
+}
+
+/** Read the `name` field from `<apiPath>/package.json`, falling back to `appName`. */
+export function getPackageName(apiPath: string, appName: string): string {
+  const pkgPath = path.join(apiPath, 'package.json')
+
+  if (!fs.existsSync(pkgPath)) return appName
+
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')) as { name?: string }
+
+    return typeof pkg.name === 'string' ? pkg.name : appName
+  } catch {
+    return appName
+  }
+}
+
+/** Discover every `apps/<app>` that has an `api/serverless.yml` (bare metadata only). */
+export function discoverApiApps(root: string): DiscoveredApiApp[] {
+  const appsDir = path.join(root, 'apps')
+  const apps: DiscoveredApiApp[] = []
+
+  if (!fs.existsSync(appsDir)) {
+    throw new Error(`Apps directory not found: ${appsDir}`)
+  }
+
+  const appDirs = fs
+    .readdirSync(appsDir, { withFileTypes: true })
+    .filter((dirent) => {
+      return dirent.isDirectory()
+    })
+    .map((dirent) => {
+      return dirent.name
+    })
+
+  for (const appName of appDirs) {
+    const apiPath = path.join(appsDir, appName, 'api')
+    const serverlessPath = path.join(apiPath, 'serverless.yml')
+
+    if (fs.existsSync(serverlessPath)) {
+      apps.push({
+        name: appName,
+        packageName: getPackageName(apiPath, appName),
+        path: apiPath,
+      })
+    }
+  }
+
+  return apps
+}
+
+/** Bare metadata for a discovered UI app (a frontend with its own framework `dev` script). */
+export interface DiscoveredUiApp {
+  /** App folder name (e.g. backoffice, client). */
+  name: string
+  /** package.json `name` — used as the exact `turbo run dev --filter` target. */
+  packageName: string
+  /** Absolute path to `apps/<app>/ui`. */
+  path: string
+}
+
+/** True when `<dir>/package.json` declares a non-empty `scripts.dev`. */
+function hasDevScript(dir: string): boolean {
+  const pkgPath = path.join(dir, 'package.json')
+
+  if (!fs.existsSync(pkgPath)) return false
+
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')) as { scripts?: Record<string, string> }
+
+    return typeof pkg.scripts?.dev === 'string' && pkg.scripts.dev.length > 0
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Discover every `apps/<app>/ui` whose package.json declares a `dev` script — the frontends
+ * `infra-kit dev --ui` runs (via one delegated `turbo run dev`). Lenient: no `apps/` dir → `[]`
+ * (UIs are optional), unlike {@link discoverApiApps} which requires it.
+ */
+export function discoverUiApps(root: string): DiscoveredUiApp[] {
+  const appsDir = path.join(root, 'apps')
+  const apps: DiscoveredUiApp[] = []
+
+  if (!fs.existsSync(appsDir)) return apps
+
+  const appDirs = fs
+    .readdirSync(appsDir, { withFileTypes: true })
+    .filter((dirent) => {
+      return dirent.isDirectory()
+    })
+    .map((dirent) => {
+      return dirent.name
+    })
+
+  for (const appName of appDirs) {
+    const uiPath = path.join(appsDir, appName, 'ui')
+
+    if (fs.existsSync(uiPath) && hasDevScript(uiPath)) {
+      apps.push({
+        name: appName,
+        packageName: getPackageName(uiPath, appName),
+        path: uiPath,
+      })
+    }
+  }
+
+  return apps
+}
+
+/** Normalize the `--app` include list: drop empties, and collapse an empty list to `null`. */
+export function normalizeAppInclude(include?: string[] | null): string[] | null {
+  const filtered = include?.filter(Boolean) ?? []
+
+  return filtered.length > 0 ? filtered : null
+}
+
+/**
+ * Existing `packages/<pkg>/dist` directories under the monorepo root — the compiled
+ * outputs `turbo watch` rewrites. Watched (alongside app dist) because editing a shared
+ * lib rewrites only the lib's `dist`, never the dependent app's, so a package-dist change
+ * is the only signal that a lib was rebuilt.
+ */
+export function getPackageDistDirs(root: string): string[] {
+  const packagesDir = path.join(root, 'packages')
+
+  if (!fs.existsSync(packagesDir)) return []
+
+  const names = fs
+    .readdirSync(packagesDir, { withFileTypes: true })
+    .filter((d) => {
+      return d.isDirectory()
+    })
+    .map((d) => {
+      return d.name
+    })
+  const dirs: string[] = []
+
+  for (const name of names) {
+    const distDir = path.join(packagesDir, name, 'dist')
+
+    if (fs.existsSync(distDir) && fs.statSync(distDir).isDirectory()) {
+      dirs.push(distDir)
+    }
+  }
+
+  return dirs
+}
+
+/** Existing `<app.path>/dist` directories for the given apps (order preserved). */
+export function getAppDistDirs(apps: Array<{ path: string }>): string[] {
+  return apps
+    .map((app) => {
+      return path.join(app.path, 'dist')
+    })
+    .filter((dir) => {
+      return fs.existsSync(dir)
+    })
+}
+
+/** How a watched dist change should be routed. */
+export interface ChangeClassification {
+  kind: 'app' | 'package'
+  /** For app changes: the matched app dist dir (undefined when nothing matched). */
+  app?: string
+}
+
+/**
+ * Route a changed compiled-output path: a `packages/<pkg>/dist` change is a shared-package
+ * rebuild (restart every app), an `<app>/dist` change restarts only that app (the matched
+ * app dist dir is returned; `undefined` when the path matches neither). Package matches take
+ * precedence.
+ */
+export function classifyDistChange(
+  changedPath: string,
+  appDistDirs: string[],
+  packageDistDirs: string[],
+): ChangeClassification {
+  const normalized = path.normalize(changedPath)
+
+  const inPackage = packageDistDirs.some((dir) => {
+    return normalized.startsWith(path.normalize(dir))
+  })
+
+  if (inPackage) {
+    return { kind: 'package' }
+  }
+
+  const matchedDir = appDistDirs.find((dir) => {
+    return normalized.startsWith(path.normalize(dir))
+  })
+
+  return { kind: 'app', app: matchedDir }
+}

package/src/dev/interfaces.ts

@@ -0,0 +1,11 @@
+import type { LogLevel, LoggerInterface } from '@aws-lambda-powertools/logger/types'
+
+/**
+ * Logger handed to local dev handlers as their third `(event, ctx, log)` argument.
+ * Extends AWS Powertools `LoggerInterface` so the real Powertools `Logger` (or any
+ * compatible implementation) is assignable wherever a handler expects it.
+ */
+export interface ILogger extends LoggerInterface {}
+
+// Re-export for consumers that need the Powertools LogLevel type.
+export type { LogLevel }

package/src/dev/managed-child.ts

@@ -0,0 +1,73 @@
+/**
+ * Shared supervision for the dev-server's long-lived, detached child processes
+ * (`turbo watch build`, `turbo run dev`). Both are deep trees
+ * (`sh → pnpm → node → turbo → …`) spawned `detached` so they form their own process
+ * group; teardown signals the whole GROUP (`process.kill(-pid, …)`), not just the wrapper.
+ *
+ * Escalation: SIGTERM first, then — if the group is still alive after a grace window —
+ * SIGKILL. FE dev servers (vite/vike/astro) run async teardown and can straggle on a
+ * lone SIGTERM (orphaned port → next run's `EADDRINUSE`), so the SIGKILL fallback matters.
+ */
+import type { ChildProcess } from 'node:child_process'
+import process from 'node:process'
+
+/** Handle to a supervised child; `kill()` reaps its whole process group and resolves when gone. */
+export interface ManagedChild {
+  kill: () => Promise<void>
+}
+
+/** Default grace before escalating SIGTERM → SIGKILL on a stubborn process group. */
+const DEFAULT_GRACE_MS = 2000
+
+/** Is the process group led by `pid` still alive? (`kill(-pid, 0)` throws ESRCH when gone.) */
+function groupAlive(pid: number): boolean {
+  try {
+    process.kill(-pid, 0)
+
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Wrap a detached child: `unref()` it (so it never keeps the loop alive) and return a
+ * handle whose `kill()` sends a group SIGTERM, polls up to `graceMs` for the group to
+ * exit, and SIGKILLs any survivor. Resolves once the group is gone (or was never spawned).
+ */
+export function superviseChild(child: ChildProcess, graceMs: number = DEFAULT_GRACE_MS): ManagedChild {
+  // Don't keep the parent event loop alive on the child; the runner owns lifecycle via kill().
+  child.unref()
+
+  return {
+    kill: async (): Promise<void> => {
+      const pid = child.pid
+
+      if (pid == null) return
+
+      try {
+        // Negative pid → the whole group (detached made the child a group leader).
+        process.kill(-pid, 'SIGTERM')
+      } catch {
+        // Already exited (ESRCH) — nothing to reap.
+        return
+      }
+
+      const deadline = Date.now() + graceMs
+
+      while (Date.now() < deadline) {
+        await new Promise((r) => {
+          return setTimeout(r, 100)
+        })
+        if (!groupAlive(pid)) return
+      }
+
+      // Still alive after the grace window — force it.
+      try {
+        process.kill(-pid, 'SIGKILL')
+      } catch {
+        // Raced to exit between the last poll and now — fine.
+      }
+    },
+  }
+}

package/src/dev/ports.ts

@@ -0,0 +1,100 @@
+/**
+ * Pure port / URL-prefix resolution for the dev-server.
+ *
+ * These functions are intentionally side-effect free: the environment is passed
+ * in (never read from `process.env` here) and no cwd / fs access happens. That
+ * keeps port precedence and conflict detection unit-testable in isolation.
+ */
+import type { DevConfig } from '../lib/infra-kit-config/index.js'
+
+/** Fallback port when no PORT / {APP}_PORT env var and no config port is set. */
+export const DEFAULT_PORT = 3010
+
+/**
+ * URL prefix applied to each app's routes when nothing is configured. Overridable
+ * per app via `dev.<app>.prefixUrl` in infra-kit.json — this is only the fallback.
+ */
+export const DEFAULT_PREFIX_URL = '/api/v1'
+
+/**
+ * Parse a raw port string (env var or config), stripping a single pair of
+ * surrounding quotes and treating blank / non-numeric input as "unset".
+ */
+export function parsePortString(raw: string | undefined): number | undefined {
+  if (raw == null || raw === '') {
+    return undefined
+  }
+
+  const n = parseInt(raw.trim().replace(/^["']|["']$/g, ''), 10)
+
+  return Number.isNaN(n) ? undefined : n
+}
+
+/**
+ * Resolve the PORT for an API app (highest priority first):
+ *
+ * 1. **`{APP}_PORT`** — e.g. `CLIENT_PORT`, `SEARCH_ENGINE_PORT` (secrets manager or shell)
+ * 2. **`PORT`** — shared fallback (multi-app: use distinct `{APP}_PORT` in env)
+ * 3. **`dev.<app>.port`** from infra-kit.json
+ * 4. Default {@link DEFAULT_PORT}
+ *
+ * Per-app env keys use the app folder name in **UPPER_SNAKE_CASE** (hyphens → underscores).
+ */
+export function resolvePort(appName: string, env: NodeJS.ProcessEnv, devConfig: DevConfig): number {
+  const prefix = appName.replace(/-/g, '_').toUpperCase()
+  const prefixedKey = `${prefix}_PORT`
+
+  const fromPrefixed = parsePortString(env[prefixedKey])
+
+  if (fromPrefixed != null) {
+    return fromPrefixed
+  }
+
+  const fromPort = parsePortString(env.PORT)
+
+  if (fromPort != null) {
+    return fromPort
+  }
+
+  const fromConfig = devConfig[appName]?.port
+
+  if (fromConfig != null) {
+    return fromConfig
+  }
+
+  return DEFAULT_PORT
+}
+
+/**
+ * Resolve the URL prefix for an API app: `dev.<app>.prefixUrl` from
+ * infra-kit.json, falling back to {@link DEFAULT_PREFIX_URL} (`/api/v1`).
+ */
+export function resolvePrefixUrl(appName: string, devConfig: DevConfig): string {
+  return devConfig[appName]?.prefixUrl ?? DEFAULT_PREFIX_URL
+}
+
+/** The apps that collide on a port, plus the raw duplicate-port list for messaging. */
+export interface PortConflicts {
+  /** Ports that appear more than once (one entry per extra occurrence, in scan order). */
+  duplicatePorts: number[]
+  /** Every app whose resolved port is one of the duplicates. */
+  conflictingApps: Array<{ name: string; port: number }>
+}
+
+/**
+ * Find apps that resolve to the same port. Returns empty `duplicatePorts` when
+ * there is no conflict; the caller decides how to surface / throw.
+ */
+export function findPortConflicts(apps: Array<{ name: string; port: number }>): PortConflicts {
+  const ports = apps.map((a) => {
+    return a.port
+  })
+  const duplicatePorts = ports.filter((port, index) => {
+    return ports.indexOf(port) !== index
+  })
+  const conflictingApps = apps.filter((a) => {
+    return duplicatePorts.includes(a.port)
+  })
+
+  return { duplicatePorts, conflictingApps }
+}