@go-to-k/cdkd 0.80.0 → 0.81.0

package/README.md

@@ -584,12 +584,16 @@ containers `cdkd local invoke` uses. Modeled on `sam local start-api`
 but reusing cdkd's synthesis / route-discovery plumbing.
 
 ```bash
-# Auto-allocate a port (printed at startup) and serve every discovered route
+# Auto-allocate one port PER discovered API (printed at startup)
 cdkd local start-api
 
-# Pin to port 3000 (SAM-parity / curl muscle memory)
+# Pin the FIRST server to port 3000; subsequent APIs get 3001, 3002, ...
 cdkd local start-api --port 3000
 
+# Restrict to a single API by its CDK logical id (HTTP API / REST API logical
+# id, or the backing Lambda's logical id for Function URLs)
+cdkd local start-api --api MyAdminApi
+
 # Pre-warm one container per Lambda at server boot — eliminates first-request cold start
 cdkd local start-api --warm
 
@@ -606,6 +610,13 @@ cdkd local start-api --watch
 cdkd local start-api --stage prod
 ```
 
+**One server per API** (since v0.81): every discovered API surface gets its
+own HTTP server on its own port, so authorizers, CORS configs, and stage
+variables stay scoped to the owning API and never bleed across APIs that
+happen to share a path. `cdkd local start-api` prints one
+`Server listening on http://<host>:<port>  (<API> (<kind>))` line per
+server at startup; pass `--api <id>` to launch only one of them.
+
 Scope: REST v1 + HTTP API + Function URL with AWS_PROXY integrations.
 Authorizers (Lambda TOKEN/REQUEST + Cognito User Pool + HTTP v2 JWT),
 VPC-config Lambda warnings, CORS preflight, hot reload, and stage

package/dist/cli.js

@@ -44850,8 +44850,8 @@ var ApiGatewayV2Provider = class {
   async createRoute(logicalId, resourceType, properties) {
     this.logger.debug(`Creating API Gateway V2 Route ${logicalId}`);
     const apiId = properties["ApiId"];
-    const routeKey2 = properties["RouteKey"];
-    if (!apiId || !routeKey2) {
+    const routeKey = properties["RouteKey"];
+    if (!apiId || !routeKey) {
       throw new ProvisioningError(
         `ApiId and RouteKey are required for API Gateway V2 Route ${logicalId}`,
         resourceType,
@@ -44862,7 +44862,7 @@ var ApiGatewayV2Provider = class {
       const response = await this.getClient().send(
         new CreateRouteCommand2({
           ApiId: apiId,
-          RouteKey: routeKey2,
+          RouteKey: routeKey,
           Target: properties["Target"],
           AuthorizationType: properties["AuthorizationType"],
           AuthorizerId: properties["AuthorizerId"]
@@ -70651,8 +70651,38 @@ async function pullImage(image, skipPull) {
     logger.debug(`Skipping docker pull for ${image} (--no-pull)`);
     return;
   }
-  logger.info(`Pulling ${image}...`);
-  await runForeground("docker", ["pull", image]);
+  if (getLogger().getLevel() === "debug") {
+    logger.info(`Pulling ${image}...`);
+    await runForeground("docker", ["pull", image]);
+    return;
+  }
+  logger.debug(`Pulling ${image} (silent \u2014 pass --verbose to stream progress)`);
+  await runCaptured("docker", ["pull", image], image);
+}
+function runCaptured(cmd, args, image) {
+  return new Promise((resolveProc, rejectProc) => {
+    const proc = spawn3(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    proc.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString("utf-8");
+    });
+    proc.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString("utf-8");
+    });
+    proc.on(
+      "error",
+      (err) => rejectProc(new DockerRunnerError(`${cmd} pull ${image} failed: ${err.message}`))
+    );
+    proc.on("close", (code) => {
+      if (code === 0) {
+        resolveProc();
+        return;
+      }
+      const detail = stderr.trim() || stdout.trim() || "(no output)";
+      rejectProc(new DockerRunnerError(`docker pull ${image} exited with code ${code}: ${detail}`));
+    });
+  });
 }
 async function runDetached(opts) {
   const args = ["run", "-d", "--rm"];
@@ -71367,8 +71397,8 @@ function discoverHttpApiRoute(logicalId, resource, template, stackName) {
       );
     }
   }
-  const routeKey2 = props["RouteKey"];
-  if (typeof routeKey2 !== "string" || routeKey2.length === 0) {
+  const routeKey = props["RouteKey"];
+  if (typeof routeKey !== "string" || routeKey.length === 0) {
     throw new Error(
       `${stackName}/${logicalId} (AWS::ApiGatewayV2::Route): RouteKey must be a string`
     );
@@ -71404,7 +71434,7 @@ function discoverHttpApiRoute(logicalId, resource, template, stackName) {
     integrationProps["IntegrationUri"],
     `${stackName}/${integrationLogicalId}.IntegrationUri`
   );
-  const { method, pathPattern } = parseRouteKey(routeKey2);
+  const { method, pathPattern } = parseRouteKey(routeKey);
   return [
     {
       method,
@@ -71519,14 +71549,14 @@ function parseHttpApiTargetIntegration(target, location) {
     )}).`
   );
 }
-function parseRouteKey(routeKey2) {
-  if (routeKey2 === "$default") {
+function parseRouteKey(routeKey) {
+  if (routeKey === "$default") {
     return { method: "ANY", pathPattern: "$default" };
   }
-  const m = /^([A-Za-z]+)\s+(\S+)$/.exec(routeKey2);
+  const m = /^([A-Za-z]+)\s+(\S+)$/.exec(routeKey);
   if (!m) {
     throw new Error(
-      `RouteKey '${routeKey2}' is malformed: expected '<METHOD> <path>' (e.g. 'GET /items/{id}') or '$default'.`
+      `RouteKey '${routeKey}' is malformed: expected '<METHOD> <path>' (e.g. 'GET /items/{id}') or '$default'.`
     );
   }
   return { method: m[1].toUpperCase(), pathPattern: m[2] };
@@ -71867,10 +71897,10 @@ function buildHttpApiV2Event(req, ctx, opts = {}) {
   const contentType = headers["content-type"] ?? "";
   const { body, isBase64Encoded } = encodeBody(req.body, contentType);
   const now = opts.now ? opts.now() : /* @__PURE__ */ new Date();
-  const routeKey2 = ctx.route.pathPattern === "$default" ? "$default" : `${ctx.route.method} ${ctx.route.pathPattern}`;
+  const routeKey = ctx.route.pathPattern === "$default" ? "$default" : `${ctx.route.method} ${ctx.route.pathPattern}`;
   const event = {
     version: "2.0",
-    routeKey: routeKey2,
+    routeKey,
     rawPath,
     rawQueryString,
     cookies,
@@ -71894,7 +71924,7 @@ function buildHttpApiV2Event(req, ctx, opts = {}) {
         userAgent
       },
       requestId: randomUUID(),
-      routeKey: routeKey2,
+      routeKey,
       stage: ctx.route.stage,
       time: formatRequestTime(now),
       timeEpoch: now.getTime(),
@@ -73798,6 +73828,74 @@ function writeError(res, statusCode, body = '{"message":"Internal server error"}
   res.end(body);
 }
 
+// src/local/api-server-grouping.ts
+function groupRoutesByServer(routes) {
+  const order = [];
+  const byKey = /* @__PURE__ */ new Map();
+  for (const rwa of routes) {
+    const r = rwa.route;
+    let serverKey;
+    let kind;
+    let identifier;
+    let displayName;
+    if (r.source === "function-url") {
+      identifier = r.lambdaLogicalId;
+      serverKey = `function-url:${identifier}`;
+      kind = "function-url";
+      displayName = `${identifier} (Function URL)`;
+    } else if (r.source === "http-api") {
+      identifier = r.apiLogicalId ?? "<unknown>";
+      serverKey = `http-api:${identifier}`;
+      kind = "http-api";
+      displayName = `${identifier} (HTTP API v2)`;
+    } else {
+      identifier = r.apiLogicalId ?? "<unknown>";
+      serverKey = `rest-v1:${identifier}`;
+      kind = "rest-v1";
+      displayName = `${identifier} (REST API v1)`;
+    }
+    const existing = byKey.get(serverKey);
+    if (existing) {
+      existing.routes.push(rwa);
+    } else {
+      byKey.set(serverKey, { displayName, kind, identifier, routes: [rwa] });
+      order.push(serverKey);
+    }
+  }
+  return order.map((key) => {
+    const entry = byKey.get(key);
+    return {
+      serverKey: key,
+      displayName: entry.displayName,
+      kind: entry.kind,
+      identifier: entry.identifier,
+      routes: entry.routes
+    };
+  });
+}
+function filterRoutesByApiIdentifier(routes, identifier) {
+  return routes.filter((rwa) => {
+    const r = rwa.route;
+    if (r.source === "function-url") {
+      return r.lambdaLogicalId === identifier;
+    }
+    return r.apiLogicalId === identifier;
+  });
+}
+function availableApiIdentifiers(routes) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const rwa of routes) {
+    const r = rwa.route;
+    const id = r.source === "function-url" ? r.lambdaLogicalId : r.apiLogicalId ?? "<unknown>";
+    if (!seen.has(id)) {
+      seen.add(id);
+      out.push(id);
+    }
+  }
+  return out;
+}
+
 // src/local/stage-resolver.ts
 function buildStageMap(template, stageOverride) {
   const out = /* @__PURE__ */ new Map();
@@ -75689,92 +75787,6 @@ function createFileWatcher(options) {
   };
 }
 
-// src/local/reload-orchestrator.ts
-function createReloadOrchestrator(deps) {
-  const logger = getLogger().child("start-api-reload");
-  let chain = Promise.resolve();
-  return {
-    reload() {
-      const next = chain.then(() => runOneReload(deps, logger));
-      chain = next.catch(() => void 0);
-      return next;
-    }
-  };
-}
-async function runOneReload(deps, logger) {
-  const previousState = deps.getServerState();
-  const start = Date.now();
-  let material;
-  try {
-    material = await deps.synthesizeAndBuild();
-  } catch (err) {
-    const reason = err instanceof Error ? err.message : String(err);
-    logger.warn(`cdk synth failed during reload; keeping previous version. (${reason})`);
-    return { ok: false, reason, added: [], removed: [], rebuiltLambdas: [] };
-  }
-  const oldRoutes = previousState.routes;
-  const newRoutes = material.routes;
-  const oldKeys = new Set(oldRoutes.map((r) => routeKey(r.route)));
-  const newKeys = new Set(newRoutes.map((r) => routeKey(r.route)));
-  const added = newRoutes.filter((r) => !oldKeys.has(routeKey(r.route)));
-  const removed = oldRoutes.filter((r) => !newKeys.has(routeKey(r.route)));
-  const previousSpecs = pickSpecsFromState(previousState);
-  const rebuiltLambdas = [];
-  for (const [logicalId, newSpec] of material.specs) {
-    const oldSpec = previousSpecs.get(logicalId);
-    if (!oldSpec)
-      continue;
-    if (specSignature(oldSpec) !== specSignature(newSpec)) {
-      rebuiltLambdas.push(logicalId);
-    }
-  }
-  const newPool = deps.buildPool(material.specs);
-  Object.defineProperty(newPool, "__cdkdSpecs", {
-    value: material.specs,
-    enumerable: false,
-    configurable: true
-  });
-  const newState = {
-    routes: material.routes,
-    pool: newPool,
-    corsConfigByApiId: material.corsConfigByApiId
-  };
-  deps.setServerState(newState);
-  void previousState.pool.dispose().catch(
-    (err) => logger.debug(
-      `Previous pool dispose() failed: ${err instanceof Error ? err.message : String(err)}`
-    )
-  );
-  const elapsed = Date.now() - start;
-  logger.info(
-    `Reloaded in ${elapsed}ms: +${added.length} route(s), -${removed.length} route(s), ${rebuiltLambdas.length} Lambda(s) rebuilt.`
-  );
-  return {
-    ok: true,
-    added,
-    removed,
-    rebuiltLambdas,
-    newState
-  };
-}
-function routeKey(route) {
-  return [route.method, route.pathPattern, route.lambdaLogicalId, route.source, route.apiVersion].map((s) => String(s)).join("|");
-}
-function specSignature(spec) {
-  return JSON.stringify({
-    codeDir: spec.codeDir,
-    env: spec.env,
-    handler: spec.lambda.handler,
-    runtime: spec.lambda.runtime,
-    containerHost: spec.containerHost,
-    debugPort: spec.debugPort ?? null
-  });
-}
-function pickSpecsFromState(state) {
-  const tagged = state.pool.__cdkdSpecs;
-  return tagged ?? /* @__PURE__ */ new Map();
-}
-
 // src/local/authorizer-cache.ts
 function createAuthorizerCache(opts = {}) {
   const now = opts.now ?? (() => Date.now());
@@ -75880,7 +75892,17 @@ async function localStartApiCommand(options) {
       }
     }
     attachStageContext(routes, stageMap);
-    const routesWithAuth = attachAuthorizers(targetStacks, routes);
+    let routesWithAuth = attachAuthorizers(targetStacks, routes);
+    if (options.api) {
+      const filtered = filterRoutesByApiIdentifier(routesWithAuth, options.api);
+      if (filtered.length === 0) {
+        const available = availableApiIdentifiers(routesWithAuth).join(", ") || "(none)";
+        throw new Error(
+          `--api '${options.api}' did not match any discovered API. Available identifiers: ${available}.`
+        );
+      }
+      routesWithAuth = filtered;
+    }
     const corsConfigByApiId = /* @__PURE__ */ new Map();
     for (const stack of targetStacks) {
       const m = buildCorsConfigByApiId(stack.template);
@@ -75933,88 +75955,91 @@ async function localStartApiCommand(options) {
     return [...assetPaths];
   };
   const initialMaterial = await synthesizeAndBuild();
-  const initialPool = buildPool(initialMaterial.specs);
   lastAssetPaths.value = computeAssetPaths(initialMaterial.specs);
   await prewarmJwks(initialMaterial.routes, jwksCache);
   warnVpcConfigLambdas(initialMaterial.routes, initialMaterial.stacks ?? []);
-  if (options.warm) {
-    logger.info(`Pre-warming ${initialMaterial.specs.size} container(s)...`);
-    const handles = await Promise.allSettled(
-      [...initialMaterial.specs.keys()].map((id) => initialPool.acquire(id))
-    );
-    for (const result of handles) {
-      if (result.status === "fulfilled") {
-        initialPool.release(result.value);
-      } else {
-        logger.warn(
-          `Pre-warm failed for one Lambda (cold start cost will apply on first request): ${result.reason instanceof Error ? result.reason.message : String(result.reason)}`
-        );
-      }
-    }
-  }
   let maxTimeoutSec = 0;
   for (const spec of initialMaterial.specs.values()) {
     if (spec.lambda.timeoutSec > maxTimeoutSec)
       maxTimeoutSec = spec.lambda.timeoutSec;
   }
   const rieTimeoutMs = Math.max(3e4, maxTimeoutSec * 2 * 1e3);
-  const port = parseInt(options.port, 10);
-  if (!Number.isFinite(port) || port < 0 || port > 65535) {
+  const basePort = parseInt(options.port, 10);
+  if (!Number.isFinite(basePort) || basePort < 0 || basePort > 65535) {
     throw new Error(`--port must be 0..65535 (got ${options.port}).`);
   }
-  const initialState = {
-    routes: initialMaterial.routes,
-    pool: initialPool,
-    corsConfigByApiId: initialMaterial.corsConfigByApiId
-  };
-  const server = await startApiServer({
-    state: initialState,
-    rieTimeoutMs,
-    host: options.host,
-    port,
-    authorizerCache,
-    jwksCache,
-    jwksWarnedUrls
-  });
-  printRouteTable(initialMaterial.routes);
+  const initialGroups = groupRoutesByServer(initialMaterial.routes);
+  const servers = [];
+  let nextPort = basePort;
+  for (const group of initialGroups) {
+    const groupSpecs = filterSpecsForGroup(group, initialMaterial.specs);
+    const groupPool = buildPool(groupSpecs);
+    const groupState = {
+      routes: group.routes,
+      pool: groupPool,
+      corsConfigByApiId: initialMaterial.corsConfigByApiId
+    };
+    if (options.warm) {
+      logger.info(`Pre-warming ${groupSpecs.size} container(s) for ${group.displayName}...`);
+      const handles = await Promise.allSettled(
+        [...groupSpecs.keys()].map((id) => groupPool.acquire(id))
+      );
+      for (const result of handles) {
+        if (result.status === "fulfilled") {
+          groupPool.release(result.value);
+        } else {
+          logger.warn(
+            `Pre-warm failed for one Lambda in ${group.displayName} (cold start cost will apply on first request): ${result.reason instanceof Error ? result.reason.message : String(result.reason)}`
+          );
+        }
+      }
+    }
+    const started = await startApiServer({
+      state: groupState,
+      rieTimeoutMs,
+      host: options.host,
+      // Increment per server; basePort=0 leaves every server on auto-alloc.
+      port: basePort === 0 ? 0 : nextPort,
+      authorizerCache,
+      jwksCache,
+      jwksWarnedUrls
+    });
+    servers.push({ group, server: started });
+    if (basePort !== 0)
+      nextPort += 1;
+  }
+  printPerServerRouteTables(servers);
   logger.info(
     `Per-Lambda concurrency: ${perLambdaConcurrency} (override with --per-lambda-concurrency)`
   );
-  process.stdout.write(`Server listening on http://${server.host}:${server.port}
-`);
+  for (const { group, server } of servers) {
+    process.stdout.write(
+      `Server listening on http://${server.host}:${server.port}  (${group.displayName})
+`
+    );
+  }
   process.stdout.write("^C to stop and clean up containers.\n");
   let watcher;
-  let orchestrator;
+  let reloadChain = Promise.resolve();
   if (options.watch) {
-    orchestrator = createReloadOrchestrator({
-      synthesizeAndBuild,
-      buildPool,
-      setServerState: server.setServerState,
-      getServerState: server.getServerState
-    });
     const initialWatchPaths = [options.output, ...lastAssetPaths.value];
     watcher = createFileWatcher({
       paths: initialWatchPaths,
       onChange: () => {
-        if (!orchestrator)
-          return;
         logger.info("Detected file change; reloading...");
-        void orchestrator.reload().then((result) => {
-          if (result.ok && watcher && result.newState) {
-            const taggedSpecs = result.newState.pool.__cdkdSpecs;
-            if (taggedSpecs) {
-              lastAssetPaths.value = computeAssetPaths(taggedSpecs);
-            }
-            watcher.update([options.output, ...lastAssetPaths.value]);
-            if (result.added.length > 0 || result.removed.length > 0) {
-              printRouteTable(result.newState.routes);
-            }
-          }
-        }).catch((err) => {
-          logger.warn(
-            `Reload failed: ${err instanceof Error ? err.message : String(err)}. Keeping previous version.`
-          );
-        });
+        const next = reloadChain.then(
+          () => reloadAllServers({
+            synthesizeAndBuild,
+            servers,
+            buildPool,
+            computeAssetPaths,
+            lastAssetPaths,
+            watcher,
+            output: options.output,
+            logger
+          })
+        );
+        reloadChain = next.catch(() => void 0);
       }
     });
     logger.info(`Watching ${options.output} (and ${lastAssetPaths.value.length} asset dir(s))`);
@@ -76041,16 +76066,28 @@ async function localStartApiCommand(options) {
         logger.warn(`watcher.close() failed: ${err instanceof Error ? err.message : String(err)}`);
       }
     }
-    try {
-      await server.close();
-    } catch (err) {
-      logger.warn(`server.close() failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    try {
-      await server.getServerState().pool.dispose();
-    } catch (err) {
-      logger.warn(`pool.dispose() failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
+    await Promise.allSettled(
+      servers.map(async ({ server, group }) => {
+        try {
+          await server.close();
+        } catch (err) {
+          logger.warn(
+            `server.close() failed for ${group.displayName}: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      })
+    );
+    await Promise.allSettled(
+      servers.map(async ({ server, group }) => {
+        try {
+          await server.getServerState().pool.dispose();
+        } catch (err) {
+          logger.warn(
+            `pool.dispose() failed for ${group.displayName}: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      })
+    );
     for (const dir of inlineTmpDirs) {
       try {
         rmSync2(dir, { recursive: true, force: true });
@@ -76422,6 +76459,91 @@ function parsePerLambdaConcurrency(raw) {
   }
   return parsed;
 }
+function filterSpecsForGroup(group, allSpecs) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const rwa of group.routes) {
+    ids.add(rwa.route.lambdaLogicalId);
+    const auth = rwa.authorizer;
+    if (auth && (auth.kind === "lambda-token" || auth.kind === "lambda-request")) {
+      ids.add(auth.lambdaLogicalId);
+    }
+  }
+  const out = /* @__PURE__ */ new Map();
+  for (const id of ids) {
+    const spec = allSpecs.get(id);
+    if (spec)
+      out.set(id, spec);
+  }
+  return out;
+}
+function printPerServerRouteTables(servers) {
+  for (const { group, server } of servers) {
+    process.stdout.write(`
+${group.displayName}  (http://${server.host}:${server.port})
+`);
+    printRouteTable(group.routes);
+  }
+}
+async function reloadAllServers(args) {
+  const {
+    synthesizeAndBuild,
+    servers,
+    buildPool,
+    computeAssetPaths,
+    lastAssetPaths,
+    watcher,
+    output,
+    logger
+  } = args;
+  let material;
+  try {
+    material = await synthesizeAndBuild();
+  } catch (err) {
+    logger.warn(
+      `cdk synth failed during reload; keeping previous version. (${err instanceof Error ? err.message : String(err)})`
+    );
+    return;
+  }
+  const newGroups = groupRoutesByServer(material.routes);
+  const newByKey = new Map(newGroups.map((g) => [g.serverKey, g]));
+  const oldKeys = new Set(servers.map((s) => s.group.serverKey));
+  const newKeys = new Set(newByKey.keys());
+  const added = [...newKeys].filter((k) => !oldKeys.has(k));
+  const removed = [...oldKeys].filter((k) => !newKeys.has(k));
+  if (added.length > 0) {
+    logger.warn(
+      `Reload detected new API surface(s): ${added.join(", ")}. Restart 'cdkd local start-api' to serve them.`
+    );
+  }
+  if (removed.length > 0) {
+    logger.warn(
+      `Reload detected removed API surface(s): ${removed.join(", ")}. Their servers will keep serving stale routes until restart.`
+    );
+  }
+  for (const booted of servers) {
+    const group = newByKey.get(booted.group.serverKey);
+    if (!group)
+      continue;
+    const groupSpecs = filterSpecsForGroup(group, material.specs);
+    const newPool = buildPool(groupSpecs);
+    const newState = {
+      routes: group.routes,
+      pool: newPool,
+      corsConfigByApiId: material.corsConfigByApiId
+    };
+    const previousState = booted.server.setServerState(newState);
+    void previousState.pool.dispose().catch((err) => {
+      logger.debug(
+        `Previous pool dispose() failed for ${group.displayName}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    });
+  }
+  lastAssetPaths.value = computeAssetPaths(material.specs);
+  if (watcher) {
+    watcher.update([output, ...lastAssetPaths.value]);
+  }
+  printPerServerRouteTables(servers);
+}
 function parseDebugPort(raw) {
   const parsed = parseInt(raw, 10);
   if (!Number.isFinite(parsed) || parsed < 1 || parsed > 65535) {
@@ -76444,8 +76566,8 @@ function createLocalStartApiCommand() {
   ).addOption(new Option7("--no-pull", "Skip docker pull (cached image)")).addOption(
     new Option7(
       "--container-host <host>",
-      "Hostname/IP the container reaches the host on"
-    ).default("host.docker.internal")
+      "IP the host uses to bind/probe the RIE port (must be a numeric IP \u2014 `docker run -p <ip>:<port>:8080` rejects hostnames). Defaults to 127.0.0.1."
+    ).default("127.0.0.1")
   ).addOption(
     new Option7(
       "--debug-port-base <port>",
@@ -76471,6 +76593,11 @@ function createLocalStartApiCommand() {
       "--stage <name>",
       "Select an API Gateway Stage by its 'StageName'. Default: the first Stage attached to each API. Drives event.stageVariables for both REST v1 and HTTP API v2. NOTE: For HTTP API v2 routes, requestContext.stage is always '$default' regardless of this flag (AWS-side limitation \u2014 HTTP API only exposes one stage to the integration event); only event.stageVariables is affected for v2 routes. For REST v1 routes the selected StageName is also threaded into requestContext.stage."
     )
+  ).addOption(
+    new Option7(
+      "--api <id>",
+      "Restrict to a single API surface by its logical id (HTTP API / REST API logical id, or the backing Lambda's logical id for Function URLs). When unset, every discovered API gets its own server on its own port (basePort, basePort+1, ... when --port is set; auto-allocated otherwise)."
+    )
   ).action(withErrorHandling(localStartApiCommand));
   [...commonOptions, ...appOptions, ...contextOptions].forEach((opt) => startApi.addOption(opt));
   startApi.addOption(deprecatedRegionOption);
@@ -77056,7 +77183,7 @@ function reorderArgs(argv) {
 }
 async function main() {
   const program = new Command16();
-  program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.80.0");
+  program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.81.0");
   program.addCommand(createBootstrapCommand());
   program.addCommand(createSynthCommand());
   program.addCommand(createListCommand());