ework-aio 0.2.8 → 0.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ework-aio",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "All-in-one installer for ework (issue tracker) + ework-daemon (AI bridge) + opencode-ework (plugin). One command: npm i -g ework-aio && ework-aio install.",
   "type": "module",
   "license": "MIT",

package/scripts/e2e-browser.sh

@@ -0,0 +1,322 @@
+#!/usr/bin/env bash
+# End-to-end browser test: install → fake LLM → opencode config → Playwright.
+#
+# This is the "full product path" test. Compared to e2e-install.sh (which
+# covers install/subcommand/lifecycle), this script:
+#   - Starts a fake OpenAI-compatible LLM server (scripts/fake-llm-server.ts)
+#   - Configures opencode.json to use it (no external API needed)
+#   - Creates an issue (which triggers daemon → opencode → fake LLM)
+#   - Drives a headless browser through ework-web UI
+#   - Verifies the resulting session is browsable and shows content
+#
+# Requires Docker image with Chromium pre-installed. The Dockerfile.regression
+# image handles this; pass via IMAGE env or rely on the default.
+#
+# Usage: ./scripts/e2e-browser.sh [container-runtime] [npm-tag]
+
+set -euo pipefail
+
+RUNTIME="${1:-docker}"
+NPM_TAG="${2:-latest}"
+IMAGE="${IMAGE:-ework-aio:e2e}"
+
+c_grn=$'\033[32m'; c_red=$'\033[31m'; c_ylw=$'\033[33m'; c_rst=$'\033[0m'
+pass() { printf '%sPASS%s %s\n' "$c_grn" "$c_rst" "$*"; }
+fail() { printf '%sFAIL%s %s\n' "$c_red" "$c_rst" "$*"; exit 1; }
+info() { printf '%s…%s %s\n' "$c_ylw" "$c_rst" "$*" >&2; }
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+if ! "$RUNTIME" image inspect "$IMAGE" >/dev/null 2>&1; then
+  info "Building $IMAGE (with Chromium deps — first build is slow)"
+  "$RUNTIME" build --network=host -f "$REPO_ROOT/Dockerfile.regression" \
+    -t "$IMAGE" "$REPO_ROOT"
+fi
+
+info "Using image: $IMAGE"
+
+# Hardcoded ports — see e2e-install.sh for why we don't inherit from host.
+WORK_PORT="14002"
+DAEMON_PORT="14101"
+FAKE_LLM_PORT="8400"
+
+OPENCODE_HOST_BIN="${OPENCODE_HOST_BIN:-/home/dog/.local/bin/opencode}"
+
+"$RUNTIME" run --rm -i --network host \
+  -v "$OPENCODE_HOST_BIN:/usr/local/bin/opencode:ro" \
+  -v "$REPO_ROOT/scripts:/host-scripts:ro" \
+  -v "$REPO_ROOT/test:/host-test:ro" \
+  -e WORK_PORT="$WORK_PORT" \
+  -e DAEMON_PORT="$DAEMON_PORT" \
+  -e FAKE_LLM_PORT="$FAKE_LLM_PORT" \
+  -e NPM_TAG="$NPM_TAG" \
+  -e HTTP_PROXY="${HTTP_PROXY:-}" \
+  -e HTTPS_PROXY="${HTTPS_PROXY:-}" \
+  -e http_proxy="${HTTP_PROXY:-}" \
+  -e https_proxy="${HTTPS_PROXY:-}" \
+  -e NO_PROXY="127.0.0.1,localhost" \
+  "$IMAGE" bash -euo pipefail <<'EOSCRIPT'
+set -euo pipefail
+
+
+c_grn=$'\033[32m'; c_red=$'\033[31m'; c_ylw=$'\033[33m'; c_rst=$'\033[0m'
+pass() { printf '%sPASS%s %s\n' "$c_grn" "$c_rst" "$*"; }
+fail() { printf '%sFAIL%s %s\n' "$c_red" "$c_rst" "$*"; exit 1; }
+info() { printf '%s…%s %s\n' "$c_ylw" "$c_rst" "$*" >&2; }
+
+WORK_PORT="${WORK_PORT:-14002}"
+DAEMON_PORT="${DAEMON_PORT:-14101}"
+FAKE_LLM_PORT="${FAKE_LLM_PORT:-8400}"
+NPM_TAG="${NPM_TAG:-latest}"
+DATA_DIR=/tmp/aio-browser
+
+info "clean state"
+rm -rf "$DATA_DIR"
+mkdir -p "$DATA_DIR"
+
+info "opencode binary on PATH"
+opencode --version | head -1
+
+info "install ework-aio@${NPM_TAG} + deps"
+for pkg in ework-web ework-daemon opencode-ework; do
+  npm install -g "$pkg@latest" 2>&1 | tail -2
+done
+npm install -g "ework-aio@${NPM_TAG}" 2>&1 | tail -2
+
+info "install Playwright npm package (browser itself is pre-baked into image)"
+# Install into a local node_modules so module resolution works regardless of
+# whether we drive the test via `node` or `bun`. Global installs don't get
+# picked up by Node's import resolver.
+mkdir -p /tmp/test-runner
+cd /tmp/test-runner
+npm init -y >/dev/null
+npm install playwright 2>&1 | tail -2
+
+info "start fake LLM server in background"
+PORT="$FAKE_LLM_PORT" bun run /host-scripts/fake-llm-server.ts 2>/tmp/fake-llm.log &
+FAKE_LLM_PID=$!
+# Wait for server to come up.
+for i in $(seq 1 30); do
+  if curl -sf "http://127.0.0.1:$FAKE_LLM_PORT/v1/models" >/dev/null; then
+    pass "fake LLM up (pid $FAKE_LLM_PID, port $FAKE_LLM_PORT)"
+    break
+  fi
+  sleep 0.5
+  [[ $i -eq 30 ]] && { tail /tmp/fake-llm.log; fail "fake LLM did not come up"; }
+done
+
+info "run ework-aio install (writes opencode.json with plugin only)"
+ework-aio install \
+  --allow-root \
+  --data-dir "$DATA_DIR" \
+  --port "$WORK_PORT" \
+  --daemon-port "$DAEMON_PORT" \
+  --bot-name e2e-bot \
+  --yes 2>&1 | tee /tmp/install.log | tail -5
+
+pass "install exited 0"
+
+info "verify services respond"
+for i in $(seq 1 60); do
+  curl -sf "http://127.0.0.1:$WORK_PORT/login" >/dev/null && break
+  sleep 0.5
+  [[ $i -eq 60 ]] && fail "ework-web did not come up"
+done
+for i in $(seq 1 60); do
+  curl -sf "http://127.0.0.1:$DAEMON_PORT/api/status" >/dev/null && break
+  sleep 0.5
+  [[ $i -eq 60 ]] && fail "daemon did not come up"
+done
+pass "both services responding"
+
+info "configure opencode to use fake LLM"
+# Overwrite ~/.config/opencode/opencode.json with fake provider + plugin.
+# install.ts only registers the plugin; we add the fake provider here so
+# the test stays isolated from any real API credentials.
+OPENCODE_CONFIG_DIR="$HOME/.config/opencode"
+mkdir -p "$OPENCODE_CONFIG_DIR"
+cat > "$OPENCODE_CONFIG_DIR/opencode.json" <<OCJSON
+{
+  "\$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-ework@latest"],
+  "provider": {
+    "fake": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Fake (E2E test)",
+      "options": {
+        "baseURL": "http://127.0.0.1:$FAKE_LLM_PORT/v1"
+      },
+      "models": {
+        "fake-model": {
+          "name": "Fake Model"
+        }
+      }
+    }
+  },
+  "model": "fake/fake-model"
+}
+OCJSON
+pass "opencode.json points at fake LLM"
+
+info "warm up opencode (first-run DB migration takes minutes)"
+# Opencode prints "Performing one time database migration, may take a few
+# minutes..." on its first invocation against a fresh DB. If we don't warm
+# it up here, both the smoke test AND the daemon's spawned opencode get
+# killed mid-migration and never reach the chat step. Running any cheap
+# command against the DB triggers the migration once; subsequent runs are
+# fast. `session list` is the cheapest touch we can do.
+# </dev/null: opencode session list reads stdin (cosmetic for list mode,
+# but defensive — see smoke test comment for the heredoc-eof trap).
+timeout -s KILL 300 opencode session list </dev/null >/dev/null 2>&1 || true
+pass "opencode warm-up done (migration triggered if needed)"
+
+info "verify opencode can reach fake LLM (manual smoke)"
+# SIGKILL after 90s — opencode can hang on tool-call prompts if the LLM
+# response shape is wrong; SIGTERM is caught for cleanup and takes longer.
+# 90s because even post-migration, first stream response can take 10-20s.
+#
+# </dev/null is critical: this script's heredoc provides bash's stdin.
+# opencode run reads stdin when waiting for prompts, which would silently
+# consume the rest of the heredoc — bash then hits EOF and exits without
+# running any subsequent step.
+cd /tmp && timeout -s KILL 90 opencode run --format json --model fake/fake-model --dir /tmp "manual smoke test" </dev/null > /tmp/smoke.json 2>&1 || true
+pass "opencode smoke test ran (output captured)"
+echo "  events: $(wc -l < /tmp/smoke.json)"
+echo "  --- smoke.json content (first 1000 chars) ---"
+head -c 1000 /tmp/smoke.json
+echo
+echo "  --- fake-llm log tail ---"
+tail -5 /tmp/fake-llm.log
+
+info "create issue that triggers daemon → opencode → fake LLM"
+# Build admin cookie (same recipe as e2e-install.sh).
+WORK_TOKEN=$(grep ^WORK_TOKEN= "$DATA_DIR/ework-web/.env" | cut -d= -f2-)
+WORK_COOKIE_SECRET=$(grep ^WORK_COOKIE_SECRET= "$DATA_DIR/ework-web/.env" | cut -d= -f2-)
+COOKIE_SIG=$(printf '%s' "$WORK_TOKEN" \
+  | openssl dgst -sha256 -hmac "$WORK_COOKIE_SECRET" -binary \
+  | base64 | tr '+/' '-_' | tr -d '=')
+AUTH_COOKIE="ework_auth=${WORK_TOKEN}.${COOKIE_SIG}"
+
+# Create project (idempotent — if it exists, 303 is still returned).
+curl -sS -o /dev/null -w 'project: %{http_code}\n' -X POST \
+  "http://127.0.0.1:$WORK_PORT/projects" \
+  -H "Cookie: $AUTH_COOKIE" \
+  --data-urlencode 'owner=e2e' \
+  --data-urlencode 'name=browser-test'
+
+# Create issue (triggers webhook → daemon → opencode).
+ISSUE_TITLE="Browser E2E $(date +%s)"
+curl -sS -o /dev/null -w 'issue: %{http_code}\n' -X POST \
+  "http://127.0.0.1:$WORK_PORT/e2e/browser-test/issues" \
+  -H "Cookie: $AUTH_COOKIE" \
+  --data-urlencode "title=$ISSUE_TITLE" \
+  --data-urlencode 'body=please reply with anything'
+
+info "wait for daemon to process the issue + spawn opencode"
+# daemon polls every few seconds; opencode run takes a few seconds against
+# fake LLM. Give it generous room.
+for i in $(seq 1 60); do
+  ACTIVE=$(curl -sS "http://127.0.0.1:$DAEMON_PORT/api/status" | jq -r '.issues // 0')
+  if [[ "$ACTIVE" -ge 1 ]]; then
+    pass "daemon registered issue after ${i} seconds (issues=$ACTIVE)"
+    break
+  fi
+  sleep 1
+  [[ $i -eq 60 ]] && fail "daemon did not register issue"
+done
+
+info "wait for opencode to write a session"
+OPENCODE_DB="$HOME/.local/share/opencode/opencode.db"
+# Query opencode.db via bun (bun:sqlite ships with the runtime, no extra
+# dependency to apt install). One-line JS keeps the bash flow readable.
+sql_query() {
+  bun -e "const db=require('bun:sqlite');const d=new db.Database('$1',{readonly:true,create:false});try{process.stdout.write(JSON.stringify(d.prepare(\`$2\`).all()))}catch(e){process.stdout.write('')}" 2>/dev/null
+}
+SESSION_ID=""
+# 180s window: opencode spawn + fake-LLM roundtrip + write to DB. The
+# daemon's poller picks up the issue within ~30s, then opencode takes
+# 5-30s depending on warm-up state.
+for i in $(seq 1 180); do
+  ROWS=$(sql_query "$OPENCODE_DB" "SELECT id FROM session ORDER BY time_updated DESC LIMIT 1;")
+  SESSION_ID=$(echo "$ROWS" | jq -r '.[0].id // empty' 2>/dev/null || echo "")
+  if [[ -n "$SESSION_ID" ]]; then
+    pass "session created: $SESSION_ID (after ${i}s)"
+    break
+  fi
+  sleep 1
+  [[ $i -eq 180 ]] && {
+    echo "--- daemon.log (last 40) ---"
+    tail -40 "$DATA_DIR/run/daemon.log" 2>/dev/null || echo "(no daemon.log)"
+    echo "--- fake-llm log (last 10) ---"
+    tail -10 /tmp/fake-llm.log
+    fail "opencode did not write a session";
+  }
+done
+
+info "wait for session to have assistant content (fake LLM reply)"
+for i in $(seq 1 30); do
+  ROWS=$(sql_query "$OPENCODE_DB" "SELECT COUNT(*) AS n FROM message WHERE session_id='${SESSION_ID}';")
+  MSG_COUNT=$(echo "$ROWS" | jq -r '.[0].n // 0' 2>/dev/null || echo 0)
+  if [[ "$MSG_COUNT" -ge 2 ]]; then
+    pass "session has $MSG_COUNT messages (user + assistant)"
+    break
+  fi
+  sleep 1
+  [[ $i -eq 30 ]] && fail "session never got assistant reply (msgs=$MSG_COUNT)";
+done
+
+info "verify session is browsable via awork-web"
+# awork-web's OpencodeClient reads opencode.db and calls `opencode export`.
+# Hit the /sessions list and the specific session page. Both require the
+# admin auth cookie (otherwise 302 → /login).
+SESSIONS_RESP=$(curl -sS -i -H "Cookie: $AUTH_COOKIE" "http://127.0.0.1:$WORK_PORT/sessions")
+SESSIONS_HTML=$(echo "$SESSIONS_RESP" | tail -n +5)
+SESSIONS_STATUS=$(echo "$SESSIONS_RESP" | head -1)
+if ! echo "$SESSIONS_HTML" | grep -q "$SESSION_ID"; then
+  echo "--- HTTP status: $SESSIONS_STATUS ---"
+  echo "--- /sessions response (first 2000 chars of body) ---"
+  echo "$SESSIONS_HTML" | head -c 2000
+  echo
+  echo "--- sessions actually in opencode.db ---"
+  sql_query "$OPENCODE_DB" "SELECT id, time_created, time_archived FROM session ORDER BY time_created DESC LIMIT 5;" | jq . 2>/dev/null
+  echo "--- ework-web access log (last 20) ---"
+  tail -20 "$DATA_DIR/run/web-access.log" 2>/dev/null || echo "(no access log)"
+  fail "/sessions list does not contain the new session ID"
+fi
+pass "/sessions lists the new session"
+
+SESSION_PAGE_HTML=$(curl -sS -H "Cookie: $AUTH_COOKIE" "http://127.0.0.1:$WORK_PORT/sessions/$SESSION_ID")
+# Look for any marker that the fake LLM reply rendered. The reply body always
+# starts with "E2E fake-LLM reply" so we grep for that substring.
+echo "$SESSION_PAGE_HTML" | grep -q "E2E fake-LLM" \
+  || fail "session page does not contain fake-LLM reply text"
+pass "session page renders fake-LLM reply content"
+
+info "drive headless browser through the UI"
+# bun (not tsx) because the script imports `bun:sqlite` to peek at opencode.db.
+cp /host-test/browser-flow.ts /tmp/test-runner/
+WORK_PORT="$WORK_PORT" \
+WORK_DATA_DIR="$DATA_DIR" \
+OPENCODE_DB="$OPENCODE_DB" \
+HEADLESS=1 \
+bun /tmp/test-runner/browser-flow.ts
+pass "browser flow test PASSED"
+
+info "fake LLM log tail"
+tail -10 /tmp/fake-llm.log
+
+echo
+echo "====================================================="
+echo "BROWSER E2E PASSED"
+echo "====================================================="
+echo "  session ID:       $SESSION_ID"
+echo "  session URL:      http://127.0.0.1:$WORK_PORT/sessions/$SESSION_ID"
+echo "  fake LLM log:     /tmp/fake-llm.log"
+echo "  data dir:         $DATA_DIR"
+
+# Kill fake LLM (container exit also does this, but explicit is clearer).
+kill "$FAKE_LLM_PID" 2>/dev/null || true
+EOSCRIPT
+
+echo
+echo "${c_grn}BROWSER E2E COMPLETE${c_rst}"

package/scripts/fake-llm-server.ts

@@ -0,0 +1,221 @@
+#!/usr/bin/env bun
+// Fake OpenAI-compatible LLM server for E2E tests.
+//
+// Listens on 127.0.0.1:PORT and responds to /v1/chat/completions with a
+// deterministic, context-aware canned reply. Used by the docker E2E test
+// to drive real `opencode run` against a stub LLM — opencode can't tell
+// the difference, writes a real session to opencode.db, and awork-web can
+// then render that session via its normal /sessions/:id route.
+//
+// Why not just stub the opencode binary? Because awork-web reads opencode.db
+// directly (src/opencode.ts:98-139 listSessions) and calls `opencode export`
+// for transcripts — stubbing the binary means re-implementing the SQLite
+// schema, which would silently drift from real opencode. Talking to a fake
+// LLM exercises every piece except the network call to a real model.
+//
+// Usage:
+//   PORT=8400 bun run scripts/fake-llm-server.ts
+//   # or just: bun run scripts/fake-llm-server.ts  (defaults to 8400)
+
+const PORT = parseInt(process.env.PORT ?? "8400", 10);
+const HOST = process.env.HOST ?? "127.0.0.1";
+
+const server = Bun.serve({
+  port: PORT,
+  hostname: HOST,
+  fetch(req) {
+    const url = new URL(req.url);
+    log(`${req.method} ${url.pathname}`);
+
+    if (req.method === "GET" && url.pathname === "/v1/models") {
+      return json({
+        object: "list",
+        data: [
+          {
+            id: "fake-model",
+            object: "model",
+            created: 1_700_000_000_000,
+            owned_by: "e2e-test",
+          },
+        ],
+      });
+    }
+
+    if (req.method === "POST" && url.pathname === "/v1/chat/completions") {
+      return handleChatCompletion(req);
+    }
+
+    return json({ error: `not found: ${req.method} ${url.pathname}` }, 404);
+  },
+});
+
+function log(msg: string): void {
+  process.stderr.write(`[fake-llm] ${new Date().toISOString()} ${msg}\n`);
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "content-type": "application/json",
+      "access-control-allow-origin": "*",
+    },
+  });
+}
+
+async function handleChatCompletion(req: Request): Promise<Response> {
+  let body: any;
+  try {
+    body = await req.json();
+  } catch (err) {
+    return json({ error: `invalid JSON: ${(err as Error).message}` }, 400);
+  }
+
+  // Log the full request so we can see what opencode/@ai-sdk is asking for
+  // (stream vs non-stream, tool definitions, system prompt, etc).
+  log(`  body: stream=${body?.stream} model=${body?.model} msgs=${body?.messages?.length} tools=${body?.tools?.length ?? 0}`);
+
+  const messages = Array.isArray(body?.messages) ? body.messages : [];
+  const userMsgs = messages.filter((m: any) => m?.role === "user");
+  const lastUser = userMsgs[userMsgs.length - 1];
+  const userText = typeof lastUser?.content === "string"
+    ? lastUser.content
+    : Array.isArray(lastUser?.content)
+      ? lastUser.content.map((p: any) => p?.text ?? "").join(" ")
+      : "";
+
+  // Deterministic, context-aware reply: echo a snippet of the user's last
+  // message so the session transcript has traceable content (not just a
+  // fixed string). Truncated so the reply stays readable in the UI.
+  const snippet = userText.slice(0, 120).replace(/\s+/g, " ").trim();
+  const reply =
+    `E2E fake-LLM reply.\n\n` +
+    `You said: "${snippet}${userText.length > 120 ? "…" : ""}"\n\n` +
+    `This is a stub response from scripts/fake-llm-server.ts. ` +
+    `The real value of this test is that opencode wrote a real session row ` +
+    `to opencode.db and awork-web can render it end-to-end.`;
+
+  const promptTokens = roughTokens(JSON.stringify(messages));
+  const completionTokens = roughTokens(reply);
+  const usage = {
+    prompt_tokens: promptTokens,
+    completion_tokens: completionTokens,
+    total_tokens: promptTokens + completionTokens,
+  };
+
+  // opencode (@ai-sdk/openai-compatible) defaults to stream=true. Returning
+  // a non-streaming JSON response silently produces a 0-token session row
+  // with no assistant text — the request completes but the transcript is
+  // empty. Honor the stream flag and emit SSE chunks.
+  if (body?.stream === true) {
+    return streamResponse(body?.model ?? "fake-model", reply, usage);
+  }
+
+  // Non-streaming path (used by curl sanity checks in tests).
+  return json({
+    id: `chatcmpl-fake-${crypto.randomUUID()}`,
+    object: "chat.completion",
+    created: Math.floor(Date.now() / 1000),
+    model: body?.model ?? "fake-model",
+    choices: [
+      {
+        index: 0,
+        message: { role: "assistant", content: reply },
+        finish_reason: "stop",
+      },
+    ],
+    usage,
+  });
+}
+
+function streamResponse(model: string, reply: string, usage: any): Response {
+  const id = `chatcmpl-fake-${crypto.randomUUID()}`;
+  const created = Math.floor(Date.now() / 1000);
+
+  // Split into ~10 chunks so the streaming code path actually streams
+  // (single-chunk streams work but look unrealistic in logs).
+  const chunks: string[] = [];
+  const words = reply.split(/(\s+)/);
+  const perChunk = Math.max(1, Math.ceil(words.length / 10));
+  for (let i = 0; i < words.length; i += perChunk) {
+    chunks.push(words.slice(i, i + perChunk).join(""));
+  }
+
+  const encoder = new TextEncoder();
+  const readable = new ReadableStream({
+    start(controller) {
+      // First chunk: role + opening content.
+      controller.enqueue(
+        encoder.encode(
+          sseLine({
+            id,
+            object: "chat.completion.chunk",
+            created,
+            model,
+            choices: [{ index: 0, delta: { role: "assistant", content: chunks[0] ?? "" }, finish_reason: null }],
+          }),
+        ),
+      );
+      // Subsequent chunks: content deltas only.
+      for (let i = 1; i < chunks.length; i++) {
+        controller.enqueue(
+          encoder.encode(
+            sseLine({
+              id,
+              object: "chat.completion.chunk",
+              created,
+              model,
+              choices: [{ index: 0, delta: { content: chunks[i] }, finish_reason: null }],
+            }),
+          ),
+        );
+      }
+      // Final chunk: empty delta + finish_reason + usage (usage must be on
+      // the final chunk when stream_options.include_usage is set; opencode
+      // sets it so the session row gets non-zero token counts).
+      controller.enqueue(
+        encoder.encode(
+          sseLine({
+            id,
+            object: "chat.completion.chunk",
+            created,
+            model,
+            choices: [{ index: 0, delta: {}, finish_reason: "stop" }],
+            usage,
+          }),
+        ),
+      );
+      controller.enqueue(encoder.encode("data: [DONE]\n\n"));
+      controller.close();
+    },
+  });
+
+  return new Response(readable, {
+    headers: {
+      "content-type": "text/event-stream",
+      "cache-control": "no-cache",
+      "connection": "keep-alive",
+      "access-control-allow-origin": "*",
+    },
+  });
+}
+
+function sseLine(obj: any): string {
+  return `data: ${JSON.stringify(obj)}\n\n`;
+}
+
+function roughTokens(text: string): number {
+  // Crude 4-chars-per-token heuristic. Token counts only need to be >0 for
+  // awork-web's heat bar (which divides by max-peak-token across the session).
+  // Real tokenizer isn't needed for test data.
+  return Math.max(1, Math.ceil(text.length / 4));
+}
+
+process.stderr.write(
+  `[fake-llm] listening on http://${HOST}:${PORT}\n` +
+    `[fake-llm] POST /v1/chat/completions  -> canned OpenAI response\n` +
+    `[fake-llm] GET  /v1/models           -> { fake-model }\n`,
+);
+
+// Keep stderr unbuffered so logs show up immediately in docker output.
+process.stderr.write(`[fake-llm] ready (pid ${process.pid})\n`);