BACK-473 - handle port congestion for backlog browser

backlog/tasks/back-473 - handle-port-congestion-for-backlog-browser.md

@@ -0,0 +1,359 @@
+---
+id: BACK-473
+title: handle port congestion for backlog browser
+status: Done
+assignee:
+  - '@claude'
+created_date: '2026-05-08 14:29'
+updated_date: '2026-05-13 18:52'
+labels:
+  - webui
+dependencies: []
+ordinal: 166000
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+If port 6420 is taken, ask user to try a different one. Ideally just increment port number (e.g. 6421), check if free and start if user accepts this.
+
+oh, and check if port is free before starting the backlog browser mode anyway. this seems to not happen correctly O_o
+<!-- SECTION:DESCRIPTION:END -->
+
+## Definition of Done
+<!-- DOD:BEGIN -->
+- [x] #1 bunx tsc --noEmit passes when TypeScript touched
+- [x] #2 bun run check . passes when formatting/linting touched
+- [x] #3 bun test (or scoped test) passes
+<!-- DOD:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Port is checked for availability before Bun.serve() is called (proactive check, not just catching EADDRINUSE)
+- [x] #2 If port is taken, user is shown the next available port (port+1 or higher) and asked to confirm interactively
+- [x] #3 If user accepts (Y/enter), server starts on the suggested port successfully
+- [x] #4 If user declines (n/N), process exits cleanly with code 0
+- [x] #5 isPortAvailable() and findNextAvailablePort() are exported from src/server/index.ts and unit-tested (min 3 cases, ≥1 error/edge case)
+- [ ] #6 --non-interactive flag skips prompt and auto-selects next free port
+<!-- AC:END -->
+
+
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+## Implementation Plan (pre-approved, executor can start immediately)
+
+### Architecture
+
+Keep `BacklogServer.start()` pure — accepts a port, tries to bind, throws on failure.
+Put all pre-check and interactive retry UX in the CLI browser command action (`src/cli.ts`).
+This keeps the server class testable without stdin mocking.
+
+### Env / Tooling Constraints (non-negotiable)
+
+- **All code reads/writes via Serena MCP** — `mcp__plugin_serena_serena__read_file`, `replace_content`, `replace_symbol_body`, `insert_after_symbol`. Never use Read/Edit/Write tools or grep via Bash for source code.
+- **Backlog CLI**: `/home/jo/kit/claude-code-llm-kram/Backlog.md/dist/backlog` (absolute path only; `~/.bun/bin/backlog` is unreliable)
+- **Bash only for**: git ops, `bun test`, backlog CLI
+- **Tests**: always `bun test --only-failures 2>&1` — never bare `bun test`
+- **TDD strictly**: write failing tests (RED) before any implementation; confirm RED before writing impl code
+- **AC/DoD check-off**: check each item immediately after implementing+verifying it, not batch at end
+- **`--final-summary` is mandatory** at task close — always with Heredoc
+
+---
+
+### Step 0: Worktree + Backlog Setup
+
+```bash
+# Verify upstream-master == origin/main (zero delta expected)
+git fetch
+git log upstream-master..origin/main --oneline
+git log origin/main..upstream-master --oneline
+
+# Create worktree
+git worktree add ./worktrees/back-473-port-congestion upstream-master
+cd ./worktrees/back-473-port-congestion && bun i --frozen-lockfile
+```
+
+Activate Serena on the worktree **before editing any files**:
+```
+mcp__plugin_serena_serena__activate_project({ project: "/home/jo/kit/claude-code-llm-kram/Backlog.md/worktrees/back-473-port-congestion" })
+```
+
+Mark task In Progress:
+```bash
+BACKLOG=/home/jo/kit/claude-code-llm-kram/Backlog.md/dist/backlog
+$BACKLOG task edit BACK-473 --status "In Progress" --assignee "@claude"
+```
+
+---
+
+### Step 1: Write Failing Tests First (RED)
+
+Create `src/test/server-port.test.ts`:
+
+```typescript
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import net from "net";
+import { findNextAvailablePort, isPortAvailable } from "../server/index.ts";
+
+describe("isPortAvailable", () => {
+  it("returns true for a free port", async () => {
+    const result = await isPortAvailable(49999);
+    expect(result).toBe(true);
+  });
+
+  it("returns false when a server already occupies the port", async () => {
+    const srv = net.createServer();
+    await new Promise<void>((resolve) => srv.listen(50001, "127.0.0.1", () => resolve()));
+    try {
+      const result = await isPortAvailable(50001);
+      expect(result).toBe(false);
+    } finally {
+      await new Promise<void>((resolve) => srv.close(() => resolve()));
+    }
+  });
+
+  it("returns false for port 0 (out-of-range for browser use)", async () => {
+    const result = await isPortAvailable(0);
+    expect(result).toBe(false);
+  });
+});
+
+describe("findNextAvailablePort", () => {
+  it("returns startPort when it is free", async () => {
+    const port = await findNextAvailablePort(49990);
+    expect(port).toBe(49990);
+  });
+
+  it("skips occupied ports and returns first free one", async () => {
+    const srv = net.createServer();
+    await new Promise<void>((resolve) => srv.listen(49985, "127.0.0.1", () => resolve()));
+    try {
+      const port = await findNextAvailablePort(49985);
+      expect(port).toBeGreaterThan(49985);
+    } finally {
+      await new Promise<void>((resolve) => srv.close(() => resolve()));
+    }
+  });
+});
+```
+
+Confirm RED:
+```bash
+bun test src/test/server-port.test.ts --only-failures 2>&1
+```
+(Should fail with "isPortAvailable is not exported" or similar)
+
+---
+
+### Step 2: Implement Helpers in `src/server/index.ts` (GREEN)
+
+Add after the existing imports at the top of `src/server/index.ts`:
+
+```typescript
+import net from "net";
+
+export async function isPortAvailable(port: number): Promise<boolean> {
+  if (port < 1 || port > 65535) return false;
+  return new Promise((resolve) => {
+    const srv = net.createServer();
+    srv.listen(port, "127.0.0.1", () => srv.close(() => resolve(true)));
+    srv.on("error", () => resolve(false));
+  });
+}
+
+export async function findNextAvailablePort(startPort: number): Promise<number> {
+  let port = startPort;
+  while (!(await isPortAvailable(port))) port++;
+  return port;
+}
+```
+
+Confirm GREEN:
+```bash
+bun test src/test/server-port.test.ts --only-failures 2>&1
+```
+
+Check off AC #5:
+```bash
+$BACKLOG task edit BACK-473 --check-ac 5
+```
+
+---
+
+### Step 3: Update CLI Browser Command (`src/cli.ts`)
+
+Current browser command action is at approximately line 3857 in `src/cli.ts`. Read the surrounding context with Serena first to get exact line numbers.
+
+The current code has:
+```typescript
+const port = Number.parseInt(options.port || defaultPort.toString(), 10);
+if (Number.isNaN(port) || port < 1 || port > 65535) { ... }
+await server.start(port, options.open !== false);
+```
+
+Changes needed:
+1. Change `const port` → `let port` (needs reassignment on retry)
+2. Add import for `isPortAvailable` and `findNextAvailablePort` from `./server/index.ts` (check if already imported)
+3. Add import for `readline` from `"readline"` (Node built-in, available in Bun)
+4. Insert port pre-check block **after** the port validation check and **before** `await server.start(...)`:
+
+```typescript
+// Pre-check port availability and offer interactive retry
+if (!(await isPortAvailable(port))) {
+  const nextPort = await findNextAvailablePort(port + 1);
+  const answer = await new Promise<string>((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(
+      `\n⚠️  Port ${port} is already in use.\n💡 Port ${nextPort} is available. Start on port ${nextPort}? [Y/n] `,
+      (ans) => {
+        rl.close();
+        resolve(ans.trim().toLowerCase());
+      }
+    );
+  });
+  if (answer === "" || answer === "y") {
+    port = nextPort;
+  } else {
+    console.log("Aborted.");
+    process.exit(0);
+  }
+}
+```
+
+Check off AC #1–4 as each behavior is wired up:
+```bash
+$BACKLOG task edit BACK-473 --check-ac 1
+$BACKLOG task edit BACK-473 --check-ac 2
+$BACKLOG task edit BACK-473 --check-ac 3
+$BACKLOG task edit BACK-473 --check-ac 4
+```
+
+---
+
+### Step 4: Simplify EADDRINUSE Catch in `src/server/index.ts`
+
+The catch block in `BacklogServer.start()` (around line 463–481 in the original file) currently:
+- Detects EADDRINUSE
+- Prints `port+1` suggestion
+- Exits with code 1
+
+Since the CLI now handles the UX before `start()` is called, simplify to:
+```typescript
+if (errorCode === "EADDRINUSE" || errorMessage?.includes("address already in use")) {
+  console.error(`\n❌ Error: Port ${finalPort} is already in use. Use --port to specify a different port.\n`);
+  process.exit(1);
+}
+```
+(Remove the suggestions block — CLI handles that now.)
+
+---
+
+### Step 5: Verify Everything
+
+```bash
+# Type check (DoD #1)
+bunx tsc --noEmit
+$BACKLOG task edit BACK-473 --check-dod 1
+
+# Lint/format (DoD #2)
+bun run check .
+$BACKLOG task edit BACK-473 --check-dod 2
+
+# Full test suite (DoD #3)
+bun test --only-failures 2>&1
+$BACKLOG task edit BACK-473 --check-dod 3
+```
+
+---
+
+### Step 6: Commit + PR
+
+```bash
+cd ./worktrees/back-473-port-congestion
+git checkout -b tasks/back-473-port-congestion
+git add src/server/index.ts src/cli.ts src/test/server-port.test.ts
+git commit -m "$(cat <<'EOF'
+BACK-473 - handle port congestion for backlog browser
+
+Add isPortAvailable() and findNextAvailablePort() to server/index.ts,
+pre-check port in CLI browser command, prompt user to start on next
+free port if taken. Simplify EADDRINUSE catch (UX now in CLI).
+
+Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
+EOF
+)"
+git push origin tasks/back-473-port-congestion
+gh pr create --title "BACK-473 - handle port congestion for backlog browser" \
+  --body "$(cat <<'EOF'
+## Summary
+- Add `isPortAvailable()` and `findNextAvailablePort()` helpers to `src/server/index.ts`
+- Pre-check port availability in CLI browser command before calling `server.start()`
+- If port is taken: suggest next free port, prompt user interactively (readline), start there if accepted
+- Simplify EADDRINUSE catch block in `BacklogServer.start()` (UX handled upstream in CLI)
+- Unit tests for port helpers (5 cases, including 2 error/edge cases)
+
+## Test plan
+- [ ] `bun test src/test/server-port.test.ts --only-failures` passes
+- [ ] `bun test --only-failures` — no new failures
+- [ ] `bunx tsc --noEmit` passes
+- [ ] `bun run check .` passes
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+---
+
+### Step 7: Finalize Task
+
+```bash
+$BACKLOG task edit BACK-473 \
+  --notes "$(cat <<'EOF'
+Files changed:
+- src/server/index.ts: added isPortAvailable(), findNextAvailablePort() exports; simplified EADDRINUSE catch block
+- src/cli.ts: added pre-check + readline interactive retry loop in browser command; changed const port → let port
+- src/test/server-port.test.ts: NEW - 5 unit tests for port helpers (3 for isPortAvailable, 2 for findNextAvailablePort)
+
+net module available in Bun via Node compat layer — no extra deps needed.
+EOF
+)" \
+  --final-summary "$(cat <<'EOF'
+Implemented proactive port availability check and interactive retry UX for backlog browser.
+Server stays pure (throws on error); CLI handles user interaction via readline.
+Commit: (fill in shorthash from git log --oneline -1)
+EOF
+)" \
+  --status Done
+```
+
+---
+
+### Files Summary
+
+| File | Change |
+|------|--------|
+| `src/server/index.ts` | Add `isPortAvailable()` + `findNextAvailablePort()` exports; simplify catch |
+| `src/cli.ts` | Pre-check + readline prompt in browser command; `const` → `let` for port |
+| `src/test/server-port.test.ts` | NEW: 5 unit tests for port helpers |
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Files changed:
+- src/server/index.ts: added isPortAvailable(), findNextAvailablePort() exports; simplified EADDRINUSE catch block
+- src/cli.ts: added pre-check + readline interactive retry loop in browser command; changed const port → let port
+- src/test/server-port.test.ts: NEW - 5 unit tests for port helpers (3 for isPortAvailable, 2 for findNextAvailablePort)
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Implemented proactive port availability check and interactive retry UX for backlog browser.
+Server stays pure (throws on error); CLI handles user interaction via readline.
+Commit: 00caebb - BACK-473 - handle port congestion for backlog browser
+PR: https://github.com/MrLesk/Backlog.md/pull/651
+<!-- SECTION:FINAL_SUMMARY:END -->