cdk-local 0.79.0 → 0.81.0

package/dist/{local-studio-CSW1raG0.js → local-studio-KUaxIkpx.js}

@@ -5,7 +5,8 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { Command, Option } from "commander";
 import { spawn } from "node:child_process";
-import { createServer } from "node:http";
+import { connect } from "node:net";
+import { createServer as createServer$1, request } from "node:http";
 import { EventEmitter } from "node:events";
 
 //#region src/local/studio-events.ts
@@ -53,14 +54,17 @@ var StudioEventBus = class {
 * the studio HTTP server (`startStudioServer`) at `GET /`.
 *
 * 3-pane shell (decision D6), framework-free vanilla JS (decision D7):
-*   - left   = target list (from `GET /api/targets`); each runnable
-*     Lambda has an [Invoke] button and a selected-highlight.
-*   - center = the WORKSPACE for the selected target: an event composer
-*     (textarea + Invoke button) with the latest run's Request /
-*     Response / Logs shown BELOW it, so you can edit and re-invoke
-*     repeatedly without losing the composer.
-*   - right  = the timeline (history) of every invocation; clicking a
-*     row loads it back into the workspace.
+*   - left   = target list (from `GET /api/targets`); each Lambda has an
+*     [Invoke] button, each API a [Start] / [Stop] serve control with a
+*     `running ● :port` indicator (slice C1), plus a selected-highlight.
+*   - center = the WORKSPACE for the selected target: for a Lambda, an
+*     event composer (textarea + Invoke button) with the latest run's
+*     Request / Response / Logs shown below; for an API, a Start/Stop
+*     control with the served endpoints + streaming logs.
+*   - right  = the timeline (history) of every invocation AND every
+*     captured serve request (slice C2); clicking a Lambda row reloads
+*     it into the composer, clicking a captured request row opens a
+*     read-only Request / Response detail.
 *
 * The center workspace is deliberately adjacent to the left target list
 * (short eye-travel: pick a target -> compose right next to it), and is
@@ -106,6 +110,13 @@ const STUDIO_CSS = `
   }
   .target .invoke-btn:hover { background: #6fe097; }
   .target.sel .invoke-btn { background: #6fe097; }
+  .target .stop-btn {
+    padding: 2px 10px; font: 11px ui-monospace, Menlo, monospace; font-weight: 700;
+    color: #2a0d0d; background: #e0707a; border: 0; border-radius: 3px; cursor: pointer;
+  }
+  .target .stop-btn:hover { background: #ec8a92; }
+  .target .run-dot { color: #7bd88f; font-size: 11px; white-space: nowrap; }
+  .target .run-dot.starting { color: #e0b54e; }
   .empty { padding: 16px 12px; color: #666; }
   .row {
     padding: 5px 12px; border-bottom: 1px solid #222; cursor: pointer;
@@ -137,6 +148,8 @@ const STUDIO_CSS = `
   .section h3 .ok { color: #7bd88f; }
   .section h3 .bad { color: #e0707a; }
   .section pre { margin: 0; white-space: pre-wrap; word-break: break-word; color: #cfcfcf; }
+  .endpoint { display: block; color: #6aa9ff; text-decoration: none; padding: 2px 0; }
+  .endpoint:hover { text-decoration: underline; }
   #conn { font-size: 11px; }
   #conn.up { color: #7bd88f; }
   #conn.down { color: #e0707a; }
@@ -145,10 +158,14 @@ const STUDIO_SCRIPT = `
   const KIND_LABEL = { lambda: 'Lambda', api: 'API', alb: 'ALB', ecs: 'ECS', agentcore: 'AgentCore' };
   const rowsById = new Map();      // invocationId -> timeline row element
   const invById = new Map();       // invocationId -> latest invocation event
-  const logsById = new Map();      // invocationId -> [log lines]
+  const logsById = new Map();      // invocationId / serve targetId -> [log lines]
   const targetEls = new Map();     // targetId -> left-pane element
+  const serveMeta = new Map();     // serve targetId -> { dot, btnSlot } row controls
+  const serveState = new Map();    // serve targetId -> { status, endpoints }
   let active = null;               // { id, kind, ta, btn, msg, result }
-  let shownInvId = null;           // invocation whose result is in the workspace
+  let shownInvId = null;           // lambda invocation whose result is in the workspace
+  let shownServeId = null;         // serve target whose workspace is shown
+  let shownDetailId = null;        // captured request whose read-only detail is shown
 
   function el(tag, cls, text) {
     const e = document.createElement(tag);
@@ -169,20 +186,32 @@ const STUDIO_SCRIPT = `
         pane.appendChild(el('div', 'group-title', group.title));
         for (const entry of group.entries) {
           total += 1;
-          // Slice B: only Lambda targets are runnable from the UI (single-shot
-          // invoke). Other kinds list but are not yet selectable.
-          const runnable = group.kind === 'lambda';
+          // Lambda targets are single-shot invokes; API targets are
+          // long-running serves (slice C1). Other kinds list but are not
+          // yet runnable.
+          const runnable = group.kind === 'lambda' || group.kind === 'api';
           const t = el('div', runnable ? 'target runnable' : 'target');
           const name = el('span', 'name', entry.id);
           name.title = entry.id; // full path on hover even when truncated
           t.appendChild(name);
           t.appendChild(el('span', 'kind', '(' + (KIND_LABEL[group.kind] || group.kind) + ')'));
-          if (runnable) {
+          if (group.kind === 'lambda') {
             const btn = el('button', 'invoke-btn', 'Invoke');
-            btn.onclick = (e) => { e.stopPropagation(); selectTarget(entry.id, group.kind); };
+            btn.onclick = (e) => { e.stopPropagation(); selectTarget(entry.id, 'lambda'); };
             t.appendChild(btn);
-            t.onclick = () => selectTarget(entry.id, group.kind);
+            t.onclick = () => selectTarget(entry.id, 'lambda');
             targetEls.set(entry.id, t);
+          } else if (group.kind === 'api') {
+            // A serve target: a running-state dot + a Start/Stop button
+            // slot, both refreshed by updateServeRow on serve events.
+            const dot = el('span', 'run-dot');
+            const btnSlot = el('span', 'btn-slot');
+            t.appendChild(dot);
+            t.appendChild(btnSlot);
+            t.onclick = () => selectTarget(entry.id, 'api');
+            targetEls.set(entry.id, t);
+            serveMeta.set(entry.id, { dot, btnSlot });
+            updateServeRow(entry.id);
           }
           pane.appendChild(t);
         }
@@ -193,6 +222,50 @@ const STUDIO_SCRIPT = `
     }
   }
 
+  // Pull any already-running serves (e.g. after a UI reload) so the rows
+  // and workspace reflect them without waiting for a fresh serve event.
+  async function loadRunning() {
+    try {
+      const res = await fetch('/api/running');
+      const data = await res.json();
+      for (const s of (data.running || [])) {
+        serveState.set(s.targetId, { status: s.status, endpoints: s.endpoints || [] });
+        updateServeRow(s.targetId);
+      }
+    } catch (err) {
+      /* best-effort; the serve SSE stream still drives live updates */
+    }
+  }
+
+  function firstPort(endpoints) {
+    const u = (endpoints || [])[0];
+    if (!u) return '';
+    const m = /:(\\d+)/.exec(u);
+    return m ? ':' + m[1] : '';
+  }
+
+  function updateServeRow(id) {
+    const meta = serveMeta.get(id);
+    if (!meta) return;
+    const st = serveState.get(id);
+    const status = st ? st.status : 'stopped';
+    const running = status === 'running';
+    const starting = status === 'starting';
+    meta.dot.textContent = running ? '● ' + firstPort(st.endpoints) : starting ? '○ starting' : '';
+    meta.dot.className = 'run-dot' + (starting ? ' starting' : '');
+    meta.btnSlot.innerHTML = '';
+    const btn = running || starting
+      ? el('button', 'stop-btn', 'Stop')
+      : el('button', 'invoke-btn', 'Start');
+    btn.onclick = (e) => {
+      e.stopPropagation();
+      if (running || starting) stopServe(id); else startServe(id);
+    };
+    meta.btnSlot.appendChild(btn);
+    // Refresh the workspace if it is showing this serve.
+    if (shownServeId === id) renderServeWorkspace(id);
+  }
+
   function highlightTarget(id) {
     document.querySelectorAll('.target.sel').forEach((n) => n.classList.remove('sel'));
     const t = targetEls.get(id);
@@ -201,7 +274,105 @@ const STUDIO_SCRIPT = `
 
   function selectTarget(id, kind) {
     highlightTarget(id);
-    renderComposer(id, kind, '{}');
+    shownDetailId = null;
+    if (kind === 'api') {
+      shownServeId = id;
+      shownInvId = null;
+      active = null;
+      renderServeWorkspace(id);
+    } else {
+      shownServeId = null;
+      renderComposer(id, kind, '{}');
+    }
+  }
+
+  async function startServe(id) {
+    serveState.set(id, { status: 'starting', endpoints: [] });
+    updateServeRow(id);
+    try {
+      const res = await fetch('/api/run', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ targetId: id, kind: 'api' }),
+      });
+      const data = await res.json();
+      if (!res.ok) {
+        // Roll back the optimistic 'starting' on a rejected start.
+        serveState.set(id, { status: 'error', endpoints: [] });
+        updateServeRow(id);
+        if (shownServeId === id) renderServeWorkspace(id, data.error || ('HTTP ' + res.status));
+      }
+      // On success the serve SSE 'running' event fills in the endpoints.
+    } catch (err) {
+      serveState.set(id, { status: 'error', endpoints: [] });
+      updateServeRow(id);
+      if (shownServeId === id) renderServeWorkspace(id, String(err));
+    }
+  }
+
+  async function stopServe(id) {
+    try {
+      await fetch('/api/stop', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ targetId: id }),
+      });
+      // The serve SSE 'stopped' event clears the running state.
+    } catch (err) {
+      /* the stop SSE event (or a later refresh) reconciles state */
+    }
+  }
+
+  function renderServeWorkspace(id, errMsg) {
+    const ws = document.getElementById('workspace');
+    ws.innerHTML = '';
+    const st = serveState.get(id) || { status: 'stopped', endpoints: [] };
+    const running = st.status === 'running';
+    const starting = st.status === 'starting';
+
+    const head = el('div', 'composer');
+    head.appendChild(el('div', 'target-name', 'Serve ' + id));
+    const btn = running || starting
+      ? el('button', null, 'Stop')
+      : el('button', null, starting ? 'Starting…' : 'Start');
+    btn.onclick = () => { if (running || starting) stopServe(id); else startServe(id); };
+    head.appendChild(btn);
+    if (errMsg) {
+      const m = el('div', 'err', errMsg);
+      head.appendChild(m);
+    }
+    ws.appendChild(head);
+
+    const epSec = el('div', 'section');
+    epSec.appendChild(el('h3', null, 'Endpoints'));
+    if (running && st.endpoints.length) {
+      for (const url of st.endpoints) {
+        const link = href(url);
+        epSec.appendChild(link);
+      }
+    } else {
+      epSec.appendChild(el('pre', null, starting ? '(starting…)' : '(not running)'));
+    }
+    ws.appendChild(epSec);
+
+    const logs = logsById.get(id) || [];
+    const logSec = el('div', 'section');
+    logSec.appendChild(el('h3', null, 'Logs'));
+    logSec.appendChild(el('pre', null, logs.length ? logs.join('\\n') : '(none)'));
+    ws.appendChild(logSec);
+  }
+
+  // Build an <a> that opens an http(s) endpoint in a new tab; ws:// URLs
+  // are shown as plain text (not navigable in a browser tab).
+  function href(url) {
+    if (/^https?:/.test(url)) {
+      const a = el('a', 'endpoint', url);
+      a.href = url;
+      a.target = '_blank';
+      a.rel = 'noopener';
+      return a;
+    }
+    return el('div', 'endpoint', url);
   }
 
   function renderComposer(id, kind, eventText) {
@@ -228,6 +399,7 @@ const STUDIO_SCRIPT = `
     active = { id, kind, ta, btn, msg, result };
     btn.onclick = () => runInvoke();
     shownInvId = null;
+    shownDetailId = null;
     ta.focus();
   }
 
@@ -328,8 +500,9 @@ const STUDIO_SCRIPT = `
         : '…';
     statusEl.className = 'status' + (merged.status != null && (merged.status < 200 || merged.status >= 300) ? ' err' : '');
 
-    // Live-refresh the workspace result if it is showing this invocation.
+    // Live-refresh the workspace if it is showing this invocation.
     if (shownInvId === ev.id) renderResult(ev.id);
+    if (shownDetailId === ev.id) renderCapturedDetail(ev.id);
   }
 
   function loadInvocation(id) {
@@ -339,9 +512,49 @@ const STUDIO_SCRIPT = `
     const row = rowsById.get(id);
     if (row) row.classList.add('sel');
     highlightTarget(ev.target);
-    renderComposer(ev.target, ev.kind, ev.request != null ? fmt(ev.request) : '{}');
-    shownInvId = id;
-    renderResult(id);
+    if (ev.kind === 'lambda') {
+      // A Lambda invocation row reloads into the re-invokable composer.
+      shownDetailId = null;
+      shownServeId = null;
+      renderComposer(ev.target, ev.kind, ev.request != null ? fmt(ev.request) : '{}');
+      shownInvId = id;
+      renderResult(id);
+    } else {
+      // A captured serve request (slice C2) opens a READ-ONLY detail —
+      // re-invoking a captured request is Phase 3.
+      shownInvId = null;
+      shownServeId = null;
+      active = null;
+      renderCapturedDetail(id);
+    }
+  }
+
+  // Read-only Request / Response detail for a captured serve request.
+  function renderCapturedDetail(id) {
+    shownDetailId = id;
+    const ev = invById.get(id);
+    const ws = document.getElementById('workspace');
+    ws.innerHTML = '';
+    if (!ev) return;
+
+    const head = el('div', 'composer');
+    head.appendChild(el('div', 'target-name', (ev.label || 'request') + '  —  ' + (ev.target || '')));
+    ws.appendChild(head);
+
+    const reqSec = el('div', 'section');
+    reqSec.appendChild(el('h3', null, 'Request'));
+    reqSec.appendChild(el('pre', null, ev.request != null ? fmt(ev.request) : '(none)'));
+    ws.appendChild(reqSec);
+
+    const respSec = el('div', 'section');
+    const h = el('h3', null, 'Response');
+    if (ev.status != null) {
+      const cls = ev.status >= 200 && ev.status < 300 ? 'ok' : 'bad';
+      h.appendChild(el('span', cls, '  ' + ev.status + (ev.durationMs != null ? ' · ' + ev.durationMs + 'ms' : '')));
+    }
+    respSec.appendChild(h);
+    respSec.appendChild(el('pre', null, ev.response != null ? fmt(ev.response) : '(pending…)'));
+    ws.appendChild(respSec);
   }
 
   function connect() {
@@ -350,15 +563,28 @@ const STUDIO_SCRIPT = `
     es.addEventListener('open', () => { conn.textContent = '● live'; conn.className = 'up'; });
     es.addEventListener('error', () => { conn.textContent = '● disconnected'; conn.className = 'down'; });
     es.addEventListener('invocation', (e) => addInvocation(JSON.parse(e.data)));
+    es.addEventListener('serve', (e) => onServeEvent(JSON.parse(e.data)));
     es.addEventListener('log', (e) => {
       const ev = JSON.parse(e.data);
       const arr = logsById.get(ev.containerId) || [];
       arr.push(ev.line);
       logsById.set(ev.containerId, arr);
       if (shownInvId === ev.containerId) renderResult(ev.containerId);
+      if (shownServeId === ev.containerId) renderServeWorkspace(ev.containerId);
     });
   }
 
+  function onServeEvent(ev) {
+    // A 'stopped' / 'error' transition clears the running state; otherwise
+    // record the latest status + endpoints for the row + workspace.
+    if (ev.status === 'stopped' || ev.status === 'error') {
+      serveState.set(ev.target, { status: ev.status, endpoints: [] });
+    } else {
+      serveState.set(ev.target, { status: ev.status, endpoints: ev.endpoints || [] });
+    }
+    updateServeRow(ev.target);
+  }
+
   function initSplitters() {
     const main = document.querySelector('main');
     let left = 280, right = 320;
@@ -389,7 +615,7 @@ const STUDIO_SCRIPT = `
     wire('split-right', (dx, l0, r0) => { right = clamp(r0 - dx); });
   }
 
-  loadTargets();
+  loadTargets().then(loadRunning);
   connect();
   initSplitters();
 `;
@@ -418,7 +644,7 @@ function renderStudioHtml(appLabel, cliName) {
 <main>
   <section class="pane" id="targets"><h2>Targets</h2></section>
   <div class="splitter" id="split-left"></div>
-  <section class="pane" id="workspace"><div class="empty">Pick a Lambda on the left to invoke it.</div></section>
+  <section class="pane" id="workspace"><div class="empty">Pick a Lambda to invoke, or an API to serve, on the left.</div></section>
   <div class="splitter" id="split-right"></div>
   <section class="pane" id="timeline"><h2>Timeline</h2><div class="empty">No requests yet.</div></section>
 </main>
@@ -489,7 +715,7 @@ async function startStudioServer(options) {
 	const maxBump = options.maxPortBump ?? 20;
 	const html = renderStudioHtml(options.appLabel, options.cliName);
 	const targetsJson = JSON.stringify({ groups: options.targetGroups });
-	const server = createServer((req, res) => handleRequest(req, res, options.bus, html, targetsJson, options.onRun));
+	const server = createServer$1((req, res) => handleRequest(req, res, options.bus, html, targetsJson, options));
 	const boundPort = await listenWithBump(server, host, options.port, maxBump);
 	return {
 		url: `http://${host}:${boundPort}`,
@@ -500,7 +726,7 @@ async function startStudioServer(options) {
 		})
 	};
 }
-function handleRequest(req, res, bus, html, targetsJson, onRun) {
+function handleRequest(req, res, bus, html, targetsJson, options) {
 	const path = (req.url ?? "/").split("?")[0];
 	if (req.method === "GET" && (path === "/" || path === "/index.html")) {
 		res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
@@ -512,25 +738,40 @@ function handleRequest(req, res, bus, html, targetsJson, onRun) {
 		res.end(targetsJson);
 		return;
 	}
+	if (req.method === "GET" && path === "/api/running") {
+		const running = options.getRunning ? options.getRunning() : { running: [] };
+		res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+		res.end(JSON.stringify(running));
+		return;
+	}
 	if (req.method === "GET" && path === "/api/events") {
 		serveSse(req, res, bus);
 		return;
 	}
 	if (req.method === "POST" && path === "/api/run") {
-		handleRun(req, res, onRun);
+		handleDispatch(req, res, options.onRun);
+		return;
+	}
+	if (req.method === "POST" && path === "/api/stop") {
+		handleDispatch(req, res, options.onStop);
 		return;
 	}
 	res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
 	res.end("Not found");
 }
 const MAX_RUN_BODY_BYTES = 5 * 1024 * 1024;
-/** Reply to `POST /api/run`: parse the JSON body, dispatch via `onRun`. */
-async function handleRun(req, res, onRun) {
+/**
+* Reply to a JSON POST endpoint (`/api/run` / `/api/stop`): parse the
+* bounded JSON body and dispatch via `handler`. 501 when no handler is
+* wired (the observe-only shell), 400 on a malformed body, 500 when the
+* handler throws.
+*/
+async function handleDispatch(req, res, handler) {
 	const sendJson = (statusCode, payload) => {
 		res.writeHead(statusCode, { "content-type": "application/json; charset=utf-8" });
 		res.end(JSON.stringify(payload));
 	};
-	if (!onRun) {
+	if (!handler) {
 		sendJson(501, { error: "Running targets is not supported by this studio server." });
 		return;
 	}
@@ -542,7 +783,7 @@ async function handleRun(req, res, onRun) {
 		return;
 	}
 	try {
-		sendJson(200, await onRun(body));
+		sendJson(200, await handler(body));
 	} catch (err) {
 		sendJson(500, { error: err instanceof Error ? err.message : String(err) });
 	}
@@ -600,12 +841,16 @@ function serveSse(req, res, bus) {
 	const onLog = (ev) => {
 		safeWrite(`event: log\ndata: ${JSON.stringify(ev)}\n\n`);
 	};
+	const onServe = (ev) => {
+		safeWrite(`event: serve\ndata: ${JSON.stringify(ev)}\n\n`);
+	};
 	function cleanup() {
 		if (closed) return;
 		closed = true;
 		clearInterval(heartbeat);
 		bus.off("invocation", onInvocation);
 		bus.off("log", onLog);
+		bus.off("serve", onServe);
 	}
 	function safeWrite(chunk) {
 		if (closed || res.writableEnded || res.destroyed) {
@@ -616,6 +861,7 @@ function serveSse(req, res, bus) {
 	}
 	bus.on("invocation", onInvocation);
 	bus.on("log", onLog);
+	bus.on("serve", onServe);
 	req.on("close", cleanup);
 	res.on("close", cleanup);
 	res.on("error", cleanup);
@@ -857,6 +1103,480 @@ function tryParseJson(raw) {
 	}
 }
 
+//#endregion
+//#region src/local/studio-proxy.ts
+let proxyIdCounter = 0;
+/**
+* Start a capturing reverse proxy in front of a studio serve target
+* (decision D4a: because every request to the served port flows through
+* `cdkl studio`, the timeline observes them regardless of source —
+* browser, curl, or the in-UI pad alike).
+*
+* Each HTTP request is forwarded to `upstream` and, in parallel,
+* captured (method / path / headers / bounded body) and emitted as an
+* `invocation` start event; when the upstream response completes, an end
+* event carries the status / headers / bounded body / duration. The full
+* bodies stream through untouched — only the captured copies are bounded.
+* `Upgrade` (WebSocket) requests are bridged raw to the upstream without
+* capture so they keep working.
+*
+* Studio is a control plane over the CLI, so this proxy sits in front of
+* the long-running `cdkl start-api` child the serve manager spawned; it
+* does NOT re-implement any routing — it forwards verbatim.
+*/
+function startStudioProxy(config) {
+	const host = config.host ?? "127.0.0.1";
+	const clock = config.clock ?? Date.now;
+	const maxCapture = config.maxCaptureBytes ?? 64 * 1024;
+	const idFactory = config.idFactory ?? (() => {
+		proxyIdCounter += 1;
+		return `req-${clock()}-${proxyIdCounter}`;
+	});
+	const upstreamUrl = new URL(config.upstream);
+	const upstreamHost = upstreamUrl.hostname;
+	const upstreamPort = Number(upstreamUrl.port) || 80;
+	const server = createServer$1((clientReq, clientRes) => {
+		const id = idFactory();
+		const startedAt = clock();
+		const path = clientReq.url ?? "/";
+		const method = clientReq.method ?? "GET";
+		const label = `${method} ${path.split("?")[0]}`;
+		const reqBody = boundedCollector(maxCapture);
+		config.bus.emit("invocation", {
+			id,
+			ts: startedAt,
+			target: config.target,
+			kind: config.kind,
+			label,
+			request: {
+				method,
+				path,
+				headers: { ...clientReq.headers }
+			}
+		});
+		let ended = false;
+		const emitEnd = (status, response) => {
+			if (ended) return;
+			ended = true;
+			config.bus.emit("invocation", {
+				id,
+				ts: startedAt,
+				target: config.target,
+				kind: config.kind,
+				label,
+				request: {
+					method,
+					path,
+					headers: { ...clientReq.headers },
+					body: reqBody.text()
+				},
+				response,
+				status,
+				durationMs: clock() - startedAt
+			});
+		};
+		const upstreamReq = request({
+			host: upstreamHost,
+			port: upstreamPort,
+			method,
+			path,
+			headers: clientReq.headers
+		}, (upstreamRes) => {
+			const respBody = boundedCollector(maxCapture);
+			clientRes.writeHead(upstreamRes.statusCode ?? 502, stripHopByHop(upstreamRes.headers));
+			upstreamRes.on("data", (chunk) => respBody.push(chunk));
+			upstreamRes.pipe(clientRes);
+			upstreamRes.on("end", () => emitEnd(upstreamRes.statusCode ?? 502, {
+				status: upstreamRes.statusCode,
+				headers: { ...upstreamRes.headers },
+				body: respBody.text()
+			}));
+			upstreamRes.on("error", () => emitEnd(502, "upstream response stream error"));
+		});
+		upstreamReq.on("error", (err) => {
+			if (!clientRes.headersSent) clientRes.writeHead(502, { "content-type": "text/plain" });
+			clientRes.end(`studio proxy: upstream error: ${err.message}`);
+			emitEnd(502, `upstream error: ${err.message}`);
+		});
+		clientReq.on("data", (chunk) => reqBody.push(chunk));
+		clientReq.on("error", () => {
+			upstreamReq.destroy();
+			emitEnd(499, "client aborted the request");
+		});
+		clientReq.pipe(upstreamReq);
+	});
+	const upgradeSockets = /* @__PURE__ */ new Set();
+	server.on("upgrade", (req, clientSocket, head) => {
+		const sock = clientSocket;
+		upgradeSockets.add(sock);
+		sock.on("close", () => upgradeSockets.delete(sock));
+		bridgeUpgrade(req, sock, head, upstreamHost, upstreamPort);
+	});
+	return new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(0, host, () => {
+			server.removeListener("error", reject);
+			const port = server.address().port;
+			resolve({
+				url: `http://${host}:${port}`,
+				port,
+				close: () => new Promise((resolveClose, rejectClose) => {
+					for (const sock of upgradeSockets) sock.destroy();
+					upgradeSockets.clear();
+					server.close((err) => err ? rejectClose(err) : resolveClose());
+					server.closeAllConnections?.();
+				})
+			});
+		});
+	});
+}
+/** RFC 7230 hop-by-hop headers — never forwarded across a proxy. */
+const HOP_BY_HOP = new Set([
+	"connection",
+	"keep-alive",
+	"proxy-authenticate",
+	"proxy-authorization",
+	"te",
+	"trailer",
+	"transfer-encoding",
+	"upgrade"
+]);
+/** Copy `headers` without the hop-by-hop ones (which describe one connection). */
+function stripHopByHop(headers) {
+	const out = {};
+	for (const [k, v] of Object.entries(headers)) if (!HOP_BY_HOP.has(k.toLowerCase())) out[k] = v;
+	return out;
+}
+/** A bounded byte collector that decodes to a (possibly truncated) utf8 string. */
+function boundedCollector(maxBytes) {
+	const chunks = [];
+	let size = 0;
+	let truncated = false;
+	return {
+		push: (c) => {
+			if (size >= maxBytes) {
+				truncated = true;
+				return;
+			}
+			const room = maxBytes - size;
+			if (c.length > room) {
+				chunks.push(c.subarray(0, room));
+				size = maxBytes;
+				truncated = true;
+			} else {
+				chunks.push(c);
+				size += c.length;
+			}
+		},
+		text: () => {
+			const s = Buffer.concat(chunks).toString("utf8");
+			return truncated ? `${s}… (truncated)` : s;
+		}
+	};
+}
+/** Raw-bridge an `Upgrade` request (e.g. WebSocket) to the upstream. */
+function bridgeUpgrade(req, clientSocket, head, upstreamHost, upstreamPort) {
+	const upstream = connect(upstreamPort, upstreamHost, () => {
+		let raw = `${req.method} ${req.url} HTTP/1.1\r\n`;
+		for (let i = 0; i < req.rawHeaders.length; i += 2) raw += `${req.rawHeaders[i]}: ${req.rawHeaders[i + 1]}\r\n`;
+		raw += "\r\n";
+		upstream.write(raw);
+		if (head && head.length > 0) upstream.write(head);
+		clientSocket.pipe(upstream);
+		upstream.pipe(clientSocket);
+	});
+	const teardown = () => {
+		clientSocket.destroy();
+		upstream.destroy();
+	};
+	upstream.on("error", teardown);
+	upstream.on("close", teardown);
+	clientSocket.on("error", teardown);
+	clientSocket.on("close", teardown);
+}
+
+//#endregion
+//#region src/local/studio-serve-manager.ts
+/** Kinds the serve manager can start in this build. */
+const SERVE_SUPPORTED = ["api"];
+/** `Server listening on <url>` is the stable ready marker `start-api` prints. */
+const LISTENING_RE = /Server listening on (\S+)/;
+/**
+* Build the studio serve manager. Slice C1 drives a long-running
+* `cdkl start-api <target>` child — studio is a control plane over the
+* CLI (the same pattern as the single-shot invoke dispatcher), so it
+* spawns the SAME headless serve command rather than re-wiring its
+* internals. This preserves byte-for-byte parity and isolates the
+* server's process-global behavior in a child.
+*
+* `start()` spawns the child with `--port 0` (OS-assigned, collision
+* free), streams its stdout/stderr onto the bus as `log` events keyed by
+* the target id, and resolves once the child prints its first
+* `Server listening on <url>` line — emitting a `serve` `running` event
+* with the discovered endpoints. `stop()` SIGTERMs the child (SIGKILL
+* after a grace window) and emits `stopped`.
+*
+* Slice C2 fronts each HTTP serve endpoint with a capture proxy
+* ({@link startStudioProxy}) so every request to the served port lands
+* on the studio timeline (decision D4a); the `endpoints` the UI is
+* handed are the proxy URLs. Full-text log search and alb / ecs serve
+* kinds are still to come.
+*/
+function createStudioServeManager(config) {
+	const spawnFn = config.spawnFn ?? spawn;
+	const nodeBin = config.nodeBin ?? process.execPath;
+	const clock = config.clock ?? Date.now;
+	const readyTimeoutMs = config.readyTimeoutMs ?? 12e4;
+	const stopGraceMs = config.stopGraceMs ?? 1e4;
+	const setTimeoutFn = config.setTimeoutFn ?? setTimeout;
+	const clearTimeoutFn = config.clearTimeoutFn ?? clearTimeout;
+	const cwd = config.cwd ?? process.cwd();
+	const proxyFactory = config.proxyFactory ?? startStudioProxy;
+	const captureRequests = config.captureRequests ?? true;
+	const entries = /* @__PURE__ */ new Map();
+	/** Close every capture proxy fronting `e` (best-effort; idempotent). */
+	async function closeProxies(e) {
+		const proxies = e.proxies.splice(0);
+		await Promise.all(proxies.map((p) => p.close().catch(() => void 0)));
+	}
+	function publicState(e) {
+		const s = {
+			targetId: e.targetId,
+			kind: e.kind,
+			status: e.status,
+			endpoints: [...e.endpoints],
+			startedAt: e.startedAt
+		};
+		if (e.pid !== void 0) s.pid = e.pid;
+		return s;
+	}
+	function emitServe(e, message) {
+		const ev = {
+			ts: clock(),
+			target: e.targetId,
+			kind: e.kind,
+			status: e.status,
+			endpoints: [...e.endpoints]
+		};
+		if (e.pid !== void 0) ev.pid = e.pid;
+		if (message !== void 0) ev.message = message;
+		config.bus.emit("serve", ev);
+	}
+	function buildArgs(targetId) {
+		const args = [
+			"start-api",
+			targetId,
+			"--port",
+			"0",
+			"--host",
+			"127.0.0.1"
+		];
+		if (config.app) args.push("--app", config.app);
+		if (config.profile) args.push("--profile", config.profile);
+		if (config.region) args.push("--region", config.region);
+		for (const [k, v] of Object.entries(config.context ?? {})) args.push("-c", `${k}=${v}`);
+		return args;
+	}
+	async function start(req) {
+		if (!SERVE_SUPPORTED.includes(req.kind)) throw new Error(`Serving '${req.kind}' targets from studio is not supported yet (API only in this build).`);
+		const existing = entries.get(req.targetId);
+		if (existing && existing.status !== "stopped" && existing.status !== "error") throw new Error(`'${req.targetId}' is already running.`);
+		const startedAt = clock();
+		let child;
+		try {
+			child = spawnFn(nodeBin, [config.cliEntry, ...buildArgs(req.targetId)], { cwd });
+		} catch (err) {
+			throw err instanceof Error ? err : new Error(String(err));
+		}
+		const entry = {
+			targetId: req.targetId,
+			kind: req.kind,
+			status: "starting",
+			endpoints: [],
+			startedAt,
+			child,
+			proxies: []
+		};
+		if (child.pid !== void 0) entry.pid = child.pid;
+		entries.set(req.targetId, entry);
+		emitServe(entry);
+		return new Promise((resolve, reject) => {
+			let settled = false;
+			child.stdout.setEncoding("utf8");
+			child.stderr.setEncoding("utf8");
+			const timer = setTimeoutFn(() => {
+				if (settled) return;
+				settled = true;
+				entry.status = "error";
+				emitServe(entry, `Timed out after ${readyTimeoutMs}ms waiting for the server to listen.`);
+				stopChild(child, stopGraceMs, setTimeoutFn, clearTimeoutFn);
+				closeProxies(entry);
+				entries.delete(req.targetId);
+				reject(/* @__PURE__ */ new Error(`'${req.targetId}' did not start within ${readyTimeoutMs}ms.`));
+			}, readyTimeoutMs);
+			timer.unref?.();
+			const becomeRunning = () => {
+				if (settled) return;
+				settled = true;
+				clearTimeoutFn(timer);
+				entry.status = "running";
+				emitServe(entry);
+				resolve(publicState(entry));
+			};
+			const onListening = async (childUrl) => {
+				let endpoint = childUrl;
+				if (captureRequests && /^https?:/i.test(childUrl)) try {
+					const proxy = await proxyFactory({
+						bus: config.bus,
+						target: req.targetId,
+						kind: req.kind,
+						upstream: childUrl
+					});
+					entry.proxies.push(proxy);
+					endpoint = proxy.url;
+				} catch {
+					endpoint = childUrl;
+				}
+				if (entry.stopping || settled && !entries.has(req.targetId)) {
+					await closeProxies(entry);
+					return;
+				}
+				if (!entry.endpoints.includes(endpoint)) entry.endpoints.push(endpoint);
+				if (settled) emitServe(entry);
+				else becomeRunning();
+			};
+			streamLines(child.stdout, (line) => {
+				const m = LISTENING_RE.exec(line);
+				if (m?.[1]) onListening(m[1]);
+				emitLog(config.bus, clock, req.targetId, line, "stdout");
+			});
+			streamLines(child.stderr, (line) => {
+				emitLog(config.bus, clock, req.targetId, line, "stderr");
+			});
+			child.on("error", (err) => {
+				if (settled) {
+					entry.status = "error";
+					emitServe(entry, err.message);
+					closeProxies(entry);
+					entries.delete(req.targetId);
+					return;
+				}
+				settled = true;
+				clearTimeoutFn(timer);
+				entry.status = "error";
+				emitServe(entry, err.message);
+				closeProxies(entry);
+				entries.delete(req.targetId);
+				reject(err);
+			});
+			child.on("close", (code) => {
+				if (!settled) {
+					settled = true;
+					clearTimeoutFn(timer);
+					if (entry.stopping) {
+						reject(/* @__PURE__ */ new Error(`'${req.targetId}' was stopped before it finished starting.`));
+						return;
+					}
+					entry.status = "error";
+					const msg = `Server exited before listening (code ${code ?? "null"}).`;
+					emitServe(entry, msg);
+					closeProxies(entry);
+					entries.delete(req.targetId);
+					reject(new Error(msg));
+					return;
+				}
+				if (entries.get(req.targetId) === entry && entry.status === "running") {
+					entry.status = "stopped";
+					emitServe(entry, `Server process exited (code ${code ?? "null"}).`);
+					closeProxies(entry);
+					entries.delete(req.targetId);
+				}
+			});
+		});
+	}
+	async function stop(req) {
+		const entry = entries.get(req.targetId);
+		if (!entry) throw new Error(`'${req.targetId}' is not running.`);
+		entry.stopping = true;
+		entries.delete(req.targetId);
+		await Promise.all([closeProxies(entry), stopChild(entry.child, stopGraceMs, setTimeoutFn, clearTimeoutFn)]);
+		entry.status = "stopped";
+		emitServe(entry);
+	}
+	function list() {
+		return [...entries.values()].map(publicState);
+	}
+	async function stopAll() {
+		const targets = [...entries.keys()];
+		await Promise.all(targets.map((targetId) => stop({ targetId }).catch(() => void 0)));
+	}
+	return {
+		start,
+		stop,
+		list,
+		stopAll
+	};
+}
+/** Emit one container log line onto the bus, keyed by the serve target id. */
+function emitLog(bus, clock, target, line, stream) {
+	bus.emit("log", {
+		ts: clock(),
+		containerId: target,
+		target,
+		line,
+		stream
+	});
+}
+/**
+* Line-buffer a child stream and invoke `onLine` per complete line
+* (trailing newline stripped, blank lines dropped). Flushes any partial
+* final line on stream end.
+*/
+function streamLines(stream, onLine) {
+	let buf = "";
+	stream.on("data", (chunk) => {
+		buf += chunk;
+		let nl = buf.indexOf("\n");
+		while (nl !== -1) {
+			const line = buf.slice(0, nl).replace(/\r$/, "");
+			buf = buf.slice(nl + 1);
+			if (line.length > 0) onLine(line);
+			nl = buf.indexOf("\n");
+		}
+	});
+	stream.on("end", () => {
+		const line = buf.replace(/\r$/, "");
+		if (line.length > 0) onLine(line);
+		buf = "";
+	});
+}
+/**
+* SIGTERM a child and resolve once it exits, escalating to SIGKILL after
+* `graceMs`. Resolves immediately if the child has already exited.
+*/
+function stopChild(child, graceMs, setTimeoutFn, clearTimeoutFn) {
+	return new Promise((resolve) => {
+		let done = false;
+		let kill;
+		const finish = () => {
+			if (done) return;
+			done = true;
+			if (kill) clearTimeoutFn(kill);
+			resolve();
+		};
+		child.once("close", finish);
+		if (child.exitCode !== null || child.signalCode !== null) {
+			finish();
+			return;
+		}
+		kill = setTimeoutFn(() => {
+			if (!done) child.kill("SIGKILL");
+		}, graceMs);
+		kill.unref?.();
+		child.kill("SIGTERM");
+	});
+}
+
 //#endregion
 //#region src/cli/commands/local-studio.ts
 const STUDIO_TARGET_KINDS = [
@@ -883,6 +1603,17 @@ function coerceRunRequest(body) {
 		event
 	};
 }
+/**
+* Validate + narrow the untyped `POST /api/stop` body into a
+* {@link StudioStopRequest}. Throws (→ 400 from the server) on a missing
+* / empty target id.
+*/
+function coerceStopRequest(body) {
+	if (typeof body !== "object" || body === null) throw new Error("Request body must be a JSON object.");
+	const { targetId } = body;
+	if (typeof targetId !== "string" || targetId.trim() === "") throw new Error("Request body must include a non-empty \"targetId\" string.");
+	return { targetId };
+}
 const DEFAULT_STUDIO_PORT = 9999;
 /**
 * Parse + validate the `--studio-port` value. Accepts `0` (OS-assigned)
@@ -918,7 +1649,7 @@ async function localStudioCommand(options) {
 	const targetGroups = toStudioTargetGroups(listTargets(stacks));
 	const appLabel = stacks.map((s) => s.stackName).join(", ") || appCmd;
 	const bus = new StudioEventBus();
-	const dispatcher = createStudioDispatcher({
+	const childConfig = {
 		cliEntry: process.argv[1] ?? "",
 		bus,
 		cwd: process.cwd(),
@@ -926,20 +1657,31 @@ async function localStudioCommand(options) {
 		...options.profile ? { profile: options.profile } : {},
 		...options.region ? { region: options.region } : {},
 		...Object.keys(context).length > 0 ? { context } : {}
-	});
+	};
+	const dispatcher = createStudioDispatcher(childConfig);
+	const serveManager = createStudioServeManager(childConfig);
 	const server = await startStudioServer({
 		port,
 		bus,
 		targetGroups,
 		appLabel,
 		cliName: getEmbedConfig().cliName,
-		onRun: (body) => dispatcher.run(coerceRunRequest(body))
+		onRun: (body) => {
+			const req = coerceRunRequest(body);
+			return req.kind === "lambda" ? dispatcher.run(req) : serveManager.start(req);
+		},
+		onStop: async (body) => {
+			const req = coerceStopRequest(body);
+			await serveManager.stop(req);
+			return { stopped: req.targetId };
+		},
+		getRunning: () => ({ running: serveManager.list() })
 	});
 	const cliName = getEmbedConfig().cliName;
 	logger.info(`${cliName} studio is running at ${server.url}`);
 	logger.info("Press Ctrl-C to stop.");
 	if (options.open && process.stdout.isTTY) openBrowser(server.url);
-	await blockUntilShutdown(server, cliName);
+	await blockUntilShutdown(server, serveManager, cliName);
 }
 /** Best-effort cross-platform browser open. Failures are non-fatal. */
 function openBrowser(url) {
@@ -955,17 +1697,20 @@ function openBrowser(url) {
 	} catch {}
 }
 /**
-* Block until SIGINT / SIGTERM, then close the studio server and resolve.
-* Mirrors the long-running serve commands' graceful-shutdown contract.
+* Block until SIGINT / SIGTERM, then stop every running serve child,
+* close the studio server, and resolve. Mirrors the long-running serve
+* commands' graceful-shutdown contract — the serve children are killed
+* BEFORE the server closes so their RIE containers are torn down rather
+* than orphaned.
 */
-function blockUntilShutdown(server, cliName) {
+function blockUntilShutdown(server, serveManager, cliName) {
 	return new Promise((resolveShutdown) => {
 		let shuttingDown = false;
 		const shutdown = (signal) => {
 			if (shuttingDown) return;
 			shuttingDown = true;
 			getLogger().info(`Received ${signal}; stopping ${cliName} studio...`);
-			server.close().catch((err) => getLogger().warn(`Error stopping studio server: ${String(err)}`)).finally(() => resolveShutdown());
+			serveManager.stopAll().catch((err) => getLogger().warn(`Error stopping serve targets: ${String(err)}`)).then(() => server.close()).catch((err) => getLogger().warn(`Error stopping studio server: ${String(err)}`)).finally(() => resolveShutdown());
 		};
 		process.on("SIGINT", () => shutdown("SIGINT"));
 		process.on("SIGTERM", () => shutdown("SIGTERM"));
@@ -1000,5 +1745,5 @@ function addStudioSpecificOptions(cmd) {
 }
 
 //#endregion
-export { startStudioServer as a, StudioEventBus as c, createStudioDispatcher as i, coerceRunRequest as n, toStudioTargetGroups as o, createLocalStudioCommand as r, renderStudioHtml as s, addStudioSpecificOptions as t };
-//# sourceMappingURL=local-studio-CSW1raG0.js.map
+export { createStudioServeManager as a, startStudioServer as c, StudioEventBus as d, createLocalStudioCommand as i, toStudioTargetGroups as l, coerceRunRequest as n, startStudioProxy as o, coerceStopRequest as r, createStudioDispatcher as s, addStudioSpecificOptions as t, renderStudioHtml as u };
+//# sourceMappingURL=local-studio-KUaxIkpx.js.map