infra-kit 0.1.126 → 0.1.128

package/src/dev/serverless-local-run.ts

@@ -0,0 +1,329 @@
+import { Logger } from '@aws-lambda-powertools/logger'
+import type { APIGatewayProxyEvent, APIGatewayProxyEventQueryStringParameters, Context } from 'aws-lambda'
+import fastify from 'fastify'
+import * as fs from 'node:fs'
+import type { Server } from 'node:http'
+import * as path from 'node:path'
+import process from 'node:process'
+import { pathToFileURL } from 'node:url'
+import { parse as parseYaml } from 'yaml'
+
+import type { ILogger } from './interfaces.js'
+
+export interface IServerConfig {
+  controllersPath: string
+  prefixUrl?: string
+  port: number
+  /** App folder name, surfaced by the `/__health` endpoint. Optional. */
+  appName?: string
+}
+
+type HandlerResult = Promise<{ body: string; headers: Record<string, string>; statusCode: number }>
+
+/** Default simulated Lambda timeout; overridable via `DEV_SERVER_TIMEOUT_MS`. */
+const DEFAULT_LAMBDA_TIMEOUT_MS = 30_000
+
+/** Resolve the simulated Lambda timeout (ms), honoring `DEV_SERVER_TIMEOUT_MS` when it parses. */
+const resolveLambdaTimeoutMs = (): number => {
+  const raw = Number.parseInt(process.env.DEV_SERVER_TIMEOUT_MS ?? '', 10)
+
+  return Number.isNaN(raw) ? DEFAULT_LAMBDA_TIMEOUT_MS : raw
+}
+
+/**
+ * Whether to emit a one-line `<method> <url> → <status> <ms>ms` log per request.
+ * Off by default; opt in with `DEV_SERVER_REQUEST_LOG=1` (kept out of the Powertools
+ * JSON logger so the line stays terminal-readable). Mirrors the env-reader precedent
+ * of {@link resolveLambdaTimeoutMs}.
+ */
+const isRequestLogEnabled = (): boolean => {
+  return process.env.DEV_SERVER_REQUEST_LOG === '1'
+}
+
+export class ServerlessLocalRun {
+  /** Busts Node ESM `import()` cache on each new server instance (watch restart). */
+  private readonly importCacheBust: string
+  private readonly logger: Logger
+  private readonly server: ReturnType<typeof fastify>
+  private readonly controllers: Record<
+    string,
+    {
+      action: Record<string, (event: APIGatewayProxyEvent, ctx: Context, log: ILogger) => HandlerResult>
+      handler: string
+    }
+  > = {}
+
+  /** `method urlAction` keys reserved synchronously, so duplicates are caught before any async import. */
+  private readonly registeredRouteKeys = new Set<string>()
+
+  constructor(private readonly serverConfig: IServerConfig) {
+    this.importCacheBust = `${Date.now()}`
+    this.logger = new Logger({ serviceName: 'LocalServer', logLevel: 'DEBUG' })
+    this.serverConfig.prefixUrl = this.serverConfig.prefixUrl ?? ''
+    this.server = fastify({ logger: false })
+
+    // Add CORS support for local development
+    this.server.addHook(
+      'onRequest',
+      async (
+        request: { method: string },
+        reply: { header: (k: string, v: string) => unknown; status: (n: number) => { send: () => void } },
+      ) => {
+        reply.header('Access-Control-Allow-Origin', '*')
+        reply.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH, OPTIONS')
+        reply.header('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Requested-With')
+
+        // Handle preflight OPTIONS requests
+        if (request.method === 'OPTIONS') {
+          reply.status(204).send()
+        }
+      },
+    )
+
+    // Opt-in per-request log line (raw stdout, not the Powertools JSON logger) so live
+    // traffic is visible in the dev terminal. Off unless DEV_SERVER_REQUEST_LOG=1.
+    if (isRequestLogEnabled()) {
+      this.server.addHook(
+        'onResponse',
+        async (request: { method: string; url: string }, reply: { statusCode: number; elapsedTime: number }) => {
+          const ms = Math.round(reply.elapsedTime)
+
+          process.stdout.write(`${request.method} ${request.url} → ${reply.statusCode} ${ms}ms\n`)
+        },
+      )
+    }
+  }
+
+  /**
+   * The registered `METHOD /path` route keys (sorted). Excludes the internal
+   * `/__health` liveness route, which is registered outside {@link defineRoute} and
+   * never added to {@link registeredRouteKeys}. Used by the runner's startup route dump.
+   */
+  public getRegisteredRoutes(): string[] {
+    return [...this.registeredRouteKeys].sort()
+  }
+
+  public async start(): Promise<void> {
+    this.registerHealthRoute()
+
+    await Promise.all(this.loadRoutes())
+
+    await this.server.listen({ port: this.serverConfig.port, host: '127.0.0.1' })
+
+    this.logger.info(`Server listening on http://127.0.0.1:${this.serverConfig.port}`, {
+      address: `http://127.0.0.1:${this.serverConfig.port}`,
+    })
+  }
+
+  /** Close the server (for watch/restart). */
+  public async close(): Promise<void> {
+    const raw = this.server.server as Server
+
+    if (typeof raw.closeAllConnections === 'function') {
+      raw.closeAllConnections()
+    }
+    await this.server.close()
+  }
+
+  /**
+   * Register a fixed `GET /__health` liveness route returning 200. The path is
+   * unprefixed (serverless.yml routes carry the `prefixUrl`, e.g. `/api/v1/...`),
+   * so it never collides with a handler route.
+   */
+  private registerHealthRoute(): void {
+    this.server.route({
+      method: 'GET',
+      url: '/__health',
+      handler: (_request: unknown, reply: { code: (n: number) => { send: (body: unknown) => void } }) => {
+        return reply.code(200).send({
+          status: 'ok',
+          app: this.serverConfig.appName ?? null,
+          port: this.serverConfig.port,
+        })
+      },
+    })
+  }
+
+  private loadRoutes(): Promise<void>[] {
+    const serverlessYmlPath = path.join(this.serverConfig.controllersPath, 'serverless.yml')
+    const fileContents = fs.readFileSync(serverlessYmlPath, 'utf8')
+    const data = parseYaml(fileContents) as {
+      functions: Record<string, { events?: Array<{ http?: { method: string; path: string } }>; handler?: string }>
+    }
+    const p: Promise<void>[] = []
+
+    if (!data?.functions) return p
+
+    for (const [funcName, funcDef] of Object.entries(data.functions)) {
+      if (!funcDef?.events?.length) continue
+      for (const element of funcDef.events) {
+        const http = element?.http
+
+        if (!http) continue
+        this.logger.debug(`Registering route: ${http.method} /${http.path} -> ${funcName}`)
+        p.push(this.defineRoute(http, funcDef))
+      }
+    }
+
+    return p
+  }
+
+  private async defineRoute(http: { method: string; path: string }, funcDef: { handler?: string }): Promise<void> {
+    let url = http.path.toString()
+
+    url = url.replaceAll('{', ':').replaceAll('}', '')
+
+    let urlAction = path.posix.join(this.serverConfig.prefixUrl ?? '', url)
+
+    urlAction = urlAction[0] === '/' ? urlAction : `/${urlAction}`
+
+    const validMethods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']
+    const method = String(http.method).toUpperCase()
+
+    if (!validMethods.includes(method)) {
+      throw new Error(`Invalid HTTP method: "${http.method}" for URL: ${urlAction}`)
+    }
+
+    // Key on method + path: two events can share a path but differ by method (e.g. GET/POST /users),
+    // so keying on the path alone would let one handler overwrite the other. Reserve the key
+    // synchronously (before the first `await`) so concurrent route loads detect a true duplicate.
+    const routeKey = `${method} ${urlAction}`
+
+    if (this.registeredRouteKeys.has(routeKey)) {
+      throw new Error(`Duplicate route: ${routeKey}`)
+    }
+    this.registeredRouteKeys.add(routeKey)
+
+    const handlerStr = funcDef.handler ?? ''
+    const parts = handlerStr.split('.')
+    const filepath = parts[0] ?? ''
+    const handler = parts[1] ?? ''
+
+    const controllerPath = path.join(this.serverConfig.controllersPath, `${filepath}.js`)
+    const fileUrl = pathToFileURL(controllerPath)
+
+    // Search params bust Node's ESM import cache so watch rebuilds load new `dist` output.
+    fileUrl.searchParams.set('v', this.importCacheBust)
+    const action = (await import(fileUrl.href)) as Record<
+      string,
+      (event: APIGatewayProxyEvent, ctx: Context, log: ILogger) => HandlerResult
+    >
+
+    this.controllers[routeKey] = { action, handler }
+
+    const traceLogger = this.logger.createChild({ serviceName: 'RequestLogger' })
+
+    this.logger.debug(`Adding fastify route: ${method} ${urlAction}`)
+
+    this.server.route({
+      method: method as 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS',
+      url: urlAction,
+      handler: async (
+        request: { body?: unknown; query?: unknown; params?: unknown; headers?: unknown },
+        reply: {
+          headers: (h: Record<string, string>) => unknown
+          code: (n: number) => { send: (body: unknown) => void }
+        },
+      ) => {
+        const controller = this.controllers[routeKey]
+
+        if (!controller) throw new Error(`No controller for ${routeKey}`)
+        const handlerFn = controller.action[controller.handler]
+
+        if (!handlerFn) throw new Error(`No handler ${controller.handler} for ${urlAction}`)
+        const retVal = await handlerFn(
+          this.getEventObj(request.body, request.query, request.params, request.headers, method, urlAction),
+          this.getContext(),
+          traceLogger,
+        )
+        const responseBody = JSON.parse(retVal.body)
+
+        reply.headers(retVal.headers ?? {})
+
+        return reply.code(retVal?.statusCode ?? 500).send(responseBody)
+      },
+    })
+
+    this.logger.debug(`Route added successfully: ${method} ${urlAction}`)
+  }
+
+  private getEventObj(
+    requestBody?: unknown,
+    queryParams?: unknown,
+    pathParameters?: unknown,
+    headers?: unknown,
+    httpMethod = '',
+    path = '',
+  ): APIGatewayProxyEvent {
+    const retVal = {
+      body: requestBody ? JSON.stringify(requestBody) : null,
+      headers: (headers ?? {}) as APIGatewayProxyEvent['headers'],
+      multiValueHeaders: {},
+      httpMethod,
+      isBase64Encoded: false,
+      path,
+      pathParameters: pathParameters ?? null,
+      queryStringParameters: (queryParams as APIGatewayProxyEventQueryStringParameters) ?? null,
+      multiValueQueryStringParameters: null,
+      stageVariables: null,
+      requestContext: {
+        accountId: '',
+        apiId: '',
+        authorizer: undefined,
+        protocol: '',
+        httpMethod,
+        identity: {
+          accessKey: null,
+          accountId: null,
+          apiKey: null,
+          apiKeyId: null,
+          caller: null,
+          clientCert: null,
+          cognitoAuthenticationProvider: null,
+          cognitoAuthenticationType: null,
+          cognitoIdentityId: null,
+          cognitoIdentityPoolId: null,
+          principalOrgId: null,
+          sourceIp: 'devIp',
+          user: null,
+          userAgent: null,
+          userArn: null,
+        },
+        path,
+        stage: '',
+        requestId: '',
+        requestTimeEpoch: 0,
+        resourceId: '',
+        resourcePath: path,
+      },
+      resource: path,
+    }
+
+    ;(retVal as APIGatewayProxyEvent & { source: string }).source = 'aws.events'
+
+    return retVal as APIGatewayProxyEvent
+  }
+
+  private getContext(): Context {
+    const startTime = Date.now()
+    const timeoutMs = resolveLambdaTimeoutMs()
+    const datePart = new Date().toISOString().split('T')[0] ?? ''
+
+    return {
+      callbackWaitsForEmptyEventLoop: false,
+      functionName: 'local-dev',
+      functionVersion: '1.0.0',
+      invokedFunctionArn: 'arn:aws:lambda:local:000000000000:function:local-dev',
+      memoryLimitInMB: '1024',
+      awsRequestId: `local-${Date.now()}`,
+      logGroupName: '/aws/lambda/local-dev',
+      logStreamName: `${datePart}/local`,
+      getRemainingTimeInMillis: (): number => {
+        return Math.max(0, timeoutMs - (Date.now() - startTime))
+      },
+      done: (_error?: Error, _result?: unknown): void => {},
+      fail: (_error: string | Error): void => {},
+      succeed: (_messageOrObject: unknown): void => {},
+    }
+  }
+}

package/src/dev/turbo-watch.ts

@@ -0,0 +1,62 @@
+/*
+ * `pnpm` is resolved from PATH — the same trust posture as the rest of the dev-server, which
+ * already shells out to `pnpm exec turbo …`; the args are fixed literals plus discovered package
+ * names, never shell-interpolated. Matches the file-level disable in `scripts/build.js`.
+ */
+/* eslint-disable sonarjs/no-os-command-from-path */
+/**
+ * `turbo watch build` engine for `infra-kit dev --watch`.
+ *
+ * Spawns ONE long-lived `turbo watch build` child that owns incremental rebuilds and
+ * dependency-graph fan-out. Its stdout is teed to the runner log but NEVER parsed for
+ * control flow: piped `turbo watch` block-buffers stdout and emits no per-task completion
+ * marker for `tsc -b` tasks, so the dev-server derives "a build finished" from watching
+ * `dist/` output instead (see {@link file://./dev-server.ts} `setupWatch`).
+ *
+ * The child is a 5-deep tree (`sh → pnpm → node → turbo → native binary`); killing the
+ * wrapper PID orphans the rest. So it is spawned `detached` (its own process group) and
+ * torn down with a process-GROUP signal — verified to fully reap the tree.
+ */
+import { spawn } from 'node:child_process'
+import * as fs from 'node:fs'
+
+import { superviseChild } from './managed-child.js'
+import type { ManagedChild } from './managed-child.js'
+
+/** Handle to the running `turbo watch` child; `kill()` reaps the whole process group. */
+export type TurboWatchHandle = ManagedChild
+
+/** Injectable spawn seam so tests run the orchestrator without a real turbo child. */
+export type TurboWatchFactory = (opts: TurboWatchOptions) => TurboWatchHandle
+
+export interface TurboWatchOptions {
+  /** App package names; each becomes a `--filter=...<pkg>` (dependency-inclusive) arg. */
+  packageNames: string[]
+  /** Consumer repo cwd the child runs in (turbo resolves the consumer's own pin here). */
+  cwd: string
+  /** Runner log file; the child's stdout+stderr are appended to it. */
+  logFile: string
+}
+
+/**
+ * Default factory: spawn `pnpm exec turbo watch build --filter=...<pkg> ... --continue=dependencies-successful
+ * --env-mode=loose` detached, tee output to `logFile`, and reap the process group on `kill()`.
+ *
+ * `--filter=...<pkg>` (the leading `...`) includes each app's dependencies, so editing a
+ * shared lib triggers a rebuild. `--continue=dependencies-successful` keeps the watcher
+ * alive when one package fails to compile, so a shared-lib type error never tears down the
+ * whole engine and the last-good `dist/` keeps serving.
+ */
+export const defaultTurboWatchFactory: TurboWatchFactory = ({ packageNames, cwd, logFile }) => {
+  const filters = packageNames.map((name) => {
+    return `--filter=...${name}`
+  })
+  const out = fs.openSync(logFile, 'a')
+  const child = spawn(
+    'pnpm',
+    ['exec', 'turbo', 'watch', 'build', ...filters, '--continue=dependencies-successful', '--env-mode=loose'],
+    { cwd, detached: true, stdio: ['ignore', out, out] },
+  )
+
+  return superviseChild(child)
+}

package/src/dev/ui-dev.ts

@@ -0,0 +1,62 @@
+/*
+ * `pnpm` is resolved from PATH — same trust posture as the rest of the dev-server (which already
+ * shells out to `pnpm exec turbo …`); args are fixed literals plus discovered package names, never
+ * shell-interpolated. Matches the file-level disable in `scripts/build.js`.
+ */
+/* eslint-disable sonarjs/no-os-command-from-path */
+/**
+ * Frontend dev engine for `infra-kit dev --ui`.
+ *
+ * Delegates FE to ONE `turbo run dev` child (turbo owns the `dev` fan-out, `^build` ordering
+ * and concurrency) rather than infra-kit spawning each framework itself — the same delegation
+ * choice already made for builds via `turbo watch`. infra-kit treats UIs opaquely: it runs their
+ * `dev` script (vite/vike/astro/…) and never encodes per-framework knowledge.
+ *
+ * Unlike the `turbo watch` child, this one's stdio is INHERITED — the framework dev servers own
+ * their own TTY output (HMR overlays, URLs, spinners), so it streams raw to the terminal below the
+ * BE server table rather than being teed into the runner log (which would corrupt it with ANSI).
+ *
+ * Detached → its own process group; reaped as a group (SIGTERM→SIGKILL) via {@link superviseChild}.
+ */
+import { spawn } from 'node:child_process'
+
+import { superviseChild } from './managed-child.js'
+import type { ManagedChild } from './managed-child.js'
+
+/** Handle to the running `turbo run dev` child; `kill()` reaps the whole process group. */
+export type UiDevHandle = ManagedChild
+
+/** Injectable spawn seam so tests run the orchestrator without a real turbo child. */
+export type UiDevFactory = (opts: UiDevOptions) => UiDevHandle
+
+export interface UiDevOptions {
+  /** UI app package names; each becomes an exact `--filter=<pkg>` (turbo runs its `dev` task). */
+  packageNames: string[]
+  /** Consumer repo cwd the child runs in. */
+  cwd: string
+  /**
+   * Concurrency cap. Must be ≥ the number of selected UI `dev` tasks (they're persistent) —
+   * turbo hard-errors when persistent tasks exceed concurrency (default 10).
+   */
+  concurrency: number
+}
+
+/**
+ * Default factory: spawn `pnpm exec turbo run dev --filter=<pkg> … --concurrency=N --env-mode=loose`
+ * detached, streaming to the parent terminal, and reap the process group on `kill()`.
+ *
+ * Exact `--filter=<pkg>` (no `...`) selects only the UI packages, so an API app that also defines a
+ * `dev` task is never picked up.
+ */
+export const defaultUiDevFactory: UiDevFactory = ({ packageNames, cwd, concurrency }) => {
+  const filters = packageNames.map((name) => {
+    return `--filter=${name}`
+  })
+  const child = spawn(
+    'pnpm',
+    ['exec', 'turbo', 'run', 'dev', ...filters, `--concurrency=${concurrency}`, '--env-mode=loose'],
+    { cwd, detached: true, stdio: ['ignore', 'inherit', 'inherit'] },
+  )
+
+  return superviseChild(child)
+}

package/src/entry/cli.ts

@@ -422,6 +422,20 @@ program
     emit(await doctor())
   })
 
+program
+  .command('dev')
+  .description('Run local dev servers for every apps/<app>/api with a serverless.yml (watch, filter by --app)')
+  .option('-w, --watch', 'Rebuild and restart on file save')
+  .option('--app <names>', 'Only run these apps (comma-separated folder names)')
+  .option('--ui', 'Also run frontends (apps/<app>/ui with a `dev` script) via turbo run dev')
+  .action(async (options) => {
+    // Lazy import so fastify/chokidar (and the whole dev stack) never load on the
+    // eager cli graph — they land in a split chunk reached only for `infra-kit dev`.
+    const { runDevServer, toDevServerOptions } = await import('src/entry/dev-server')
+
+    await runDevServer(toDevServerOptions(options))
+  })
+
 program
   .command('version')
   .description('Print the installed infra-kit CLI version')
@@ -461,8 +475,9 @@ program
 program
   .command('env-clear')
   .description('Clear loaded env vars. Source the returned file path to apply.')
-  .action(async () => {
-    emit(await envClear())
+  .option('--purge', "Also delete this project's warm cache outright (durable disable)")
+  .action(async (options) => {
+    emit(await envClear({ purge: Boolean(options.purge) }))
   })
 
 // Internal: driven by the init shell-startup integration (backgrounded). Writes
@@ -471,8 +486,11 @@ program
 program
   .command('env-autoload', { hidden: true })
   .description('Internal: prime env for the shell-startup auto-load trigger')
-  .action(async () => {
-    await envAutoload()
+  // The shell passes its already-canonicalized (`${dir:A}`) project dir so node can
+  // key the warm cache identically; see writeEnvLoadFile / shouldWriteWarm.
+  .option('--project-dir <dir>', 'Canonical project dir for the warm-cache key (shell-startup only)')
+  .action(async (options) => {
+    await envAutoload({ projectDir: options.projectDir })
   })
 
 // Register `--json` on every command, then resolve the flag before each action
@@ -485,9 +503,10 @@ program.commands.forEach(addJsonOption)
 // (avoids recursion — `env-autoload`/`env-load` would re-enter), plus the
 // host-inspecting / meta commands where priming Doppler env would be surprising
 // (`init` bootstraps the shell block, `doctor` inspects auth, `version` prints a
-// string). `--help`/`--version`/the bare-arg menu don't fire preAction at all.
+// string, `dev` is a long-running server that manages its own env). `--help`/
+// `--version`/the bare-arg menu don't fire preAction at all.
 const isAutoLoadExcludedCommand = (name: string): boolean => {
-  return name.startsWith('env-') || name === 'init' || name === 'doctor' || name === 'version'
+  return name.startsWith('env-') || name === 'init' || name === 'doctor' || name === 'version' || name === 'dev'
 }
 
 program.hook('preAction', async (_thisCommand, actionCommand) => {

package/src/entry/dev-server.ts

@@ -0,0 +1,103 @@
+/**
+ * Long-running CLI entry for the local dev-server. Owns flag parsing, OS signal
+ * handling, and process exit — the orchestrator (`src/dev/dev-server`) is signal-
+ * and exit-agnostic. Kept off the eager cli.js graph: entry/cli.ts reaches this
+ * module (and the fastify/chokidar it pulls in) only via `await import(...)`, so
+ * those heavy deps never load on the machine command paths.
+ */
+import { Command } from 'commander'
+import process from 'node:process'
+import { pathToFileURL } from 'node:url'
+
+import { run } from 'src/dev/dev-server'
+import type { DevServerOptions } from 'src/dev/dev-server'
+
+/** Raw option object as produced by Commander (comma-joined strings). */
+export interface DevCliOptions {
+  watch?: boolean
+  app?: string
+  ui?: boolean
+}
+
+/** Split a comma-separated flag value into a trimmed, non-empty list (`null` when unset/empty). */
+const splitList = (value: string | undefined): string[] | null => {
+  if (value == null) return null
+
+  const parts = value
+    .split(',')
+    .map((s) => {
+      return s.trim()
+    })
+    .filter(Boolean)
+
+  return parts.length > 0 ? parts : null
+}
+
+/**
+ * Map raw Commander flags to the orchestrator's typed options. Shared by the
+ * `infra-kit dev` subcommand and the standalone entry so the two never diverge.
+ */
+export const toDevServerOptions = (raw: DevCliOptions): DevServerOptions => {
+  return {
+    watch: raw.watch ?? false,
+    include: splitList(raw.app),
+    ui: raw.ui ?? false,
+  }
+}
+
+/**
+ * Start the dev-server, then wait for an OS signal and shut every server down
+ * cleanly before exiting. This is the ONLY place SIGINT/SIGTERM handlers and
+ * `process.exit` live for the dev-server feature.
+ */
+export const runDevServer = async (options: DevServerOptions): Promise<void> => {
+  const runner = await run(options)
+
+  let shuttingDown = false
+
+  const shutdown = (signal: NodeJS.Signals): void => {
+    if (shuttingDown) return
+    shuttingDown = true
+
+    void (async () => {
+      try {
+        process.stdout.write(`\nReceived ${signal}, shutting down dev-server...\n`)
+        await runner.shutdown()
+      } finally {
+        process.exit(0)
+      }
+    })()
+  }
+
+  process.on('SIGINT', () => {
+    return shutdown('SIGINT')
+  })
+  process.on('SIGTERM', () => {
+    return shutdown('SIGTERM')
+  })
+}
+
+/** Parse `node dist/dev-server.js ...` flags and start the server. */
+const parseAndRun = async (argv: string[]): Promise<void> => {
+  const program = new Command()
+
+  program
+    .name('infra-kit-dev-server')
+    .description('Run local dev servers for every apps/<app>/api that has a serverless.yml')
+    .option('-w, --watch', 'Rebuild and restart on file save')
+    .option('--app <names>', 'Only run these apps (comma-separated folder names)')
+    .option('--ui', 'Also run frontends (apps/<app>/ui with a `dev` script) via turbo run dev')
+
+  program.parse(argv)
+
+  await runDevServer(toDevServerOptions(program.opts<DevCliOptions>()))
+}
+
+// Self-execute only when run directly (`node dist/dev-server.js`), not when the
+// `infra-kit dev` subcommand imports this module for its exported helpers.
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  parseAndRun(process.argv).catch((error: unknown) => {
+    console.error(error)
+    process.exit(1)
+  })
+}

package/src/lib/.omc/state/sessions/f9c17a0e-2dd8-4f7d-badf-631f266c5d4c/pre-tool-advisory-throttle.json

@@ -0,0 +1,18 @@
+{
+  "version": 1,
+  "entries": {
+    "79a93d4a2f8f50b95f852280616242fee1855dc99a3c75211917f55e72e95fae": {
+      "last_emitted_at_ms": 1783339798994,
+      "message": "Use parallel execution for independent tasks. Use run_in_background for long operations (npm install, builds, tests)."
+    },
+    "445ed27a3872b681d98190bae61ccb84954e1bc4e140df5370be958dee776b3a": {
+      "last_emitted_at_ms": 1783339766672,
+      "message": "Verify changes work after editing. Test functionality before marking complete."
+    },
+    "466399dafa2d20f60587180bad0a07358eb7f2bce724df0ff682f038ad33f5ad": {
+      "last_emitted_at_ms": 1783339749887,
+      "message": "Read multiple files in parallel when possible for faster analysis."
+    }
+  },
+  "updated_at": "2026-07-06T12:09:58.994Z"
+}

package/src/lib/command-catalog/__tests__/__snapshots__/command-catalog.test.ts.snap

@@ -18,6 +18,7 @@ exports[`command catalog — MCP exposure policy > matches the golden MCP tools/
     "name": "env-clear",
     "output": [
       "filePath",
+      "purged",
       "unsetStatements",
       "variableCount",
     ],

package/src/lib/command-catalog/command-catalog.ts

@@ -109,6 +109,10 @@ export const commandCatalog: CommandCatalogEntry[] = [
   { cliName: 'vendor', menuGroup: 'environment', mcpTool: null, mcpExposed: false },
   { cliName: 'vendor-config', menuGroup: 'environment', mcpTool: null, mcpExposed: false },
   { cliName: 'doctor', menuGroup: 'environment', mcpTool: doctorMcpTool, mcpExposed: false },
+  // Long-running local dev server (fastify + chokidar). Not an MCP tool — it never
+  // returns, so it can't fit the request/response tool contract. menuGroup null:
+  // the no-arg picker drives one-shot commands, not a blocking foreground process.
+  { cliName: 'dev', menuGroup: null, mcpTool: null, mcpExposed: false },
   { cliName: 'init', menuGroup: 'environment', mcpTool: null, mcpExposed: false },
   { cliName: 'version', menuGroup: 'environment', mcpTool: versionMcpTool, mcpExposed: true },
   { cliName: 'config', menuGroup: 'environment', mcpTool: null, mcpExposed: false },