@kidsinai/kids-client 0.0.8 → 0.0.10

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@kidsinai/kids-client",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "type": "module",
   "description": "Own-client TUI for Kids OpenCode — talks to local `opencode serve` via @opencode-ai/sdk v2 with kid-warm rendering, mission progress, permission dialog, and stderr-tail audit pipeline.",
   "license": "MIT",

package/src/core/serve-manager.ts

@@ -14,8 +14,21 @@ import { spawn, type Subprocess } from "bun"
 export type ServeReadiness =
   | { kind: "already_running" }
   | { kind: "spawned"; pid: number }
+  // Someone else is holding the port (TCP accepts) but our password doesn't
+  // unlock /app. Usually a stale `opencode serve` from a previous run with a
+  // different OPENCODE_SERVER_PASSWORD. Telling the kid to retry won't help —
+  // they need to free the port (`kids-opencode --shutdown`).
+  | { kind: "port_taken_auth_mismatch"; port: string }
+  // We spawned a child but it exited before becoming ready (e.g. EADDRINUSE,
+  // missing config). exitCode/stderr surface the real cause instead of
+  // making the kid wait 10s for a generic timeout.
+  | { kind: "spawn_failed"; exitCode: number | null; stderrTail: string }
   | { kind: "timeout"; lastError: string }
 
+/** Tri-state probe result; lets ensureReady() distinguish "nobody home"
+ *  from "someone's home but won't let me in". */
+export type ProbeResult = "ok" | "auth_mismatch" | "offline"
+
 export interface ServeManagerOptions {
   baseUrl: string
   serverPassword: string
@@ -31,17 +44,30 @@ export interface ServeManagerOptions {
 export class ServeManager {
   private child: Subprocess | null = null
   private opts: ServeManagerOptions
+  // Recent stderr lines from the spawned child, used for spawn_failed
+  // diagnostics. Bounded so it doesn't grow unbounded over a long session.
+  private stderrTail: string[] = []
+  private static STDERR_TAIL_MAX = 20
 
   constructor(opts: ServeManagerOptions) {
     this.opts = opts
   }
 
   /**
-   * Probe baseUrl. If already up, no-op. Otherwise spawn `opencode serve`
-   * as a child, hook stderr parsing, poll until /app responds 200.
+   * Probe baseUrl. If already up, no-op. If something else holds the port
+   * with a different password, return port_taken_auth_mismatch (don't try
+   * to spawn — bind would just fail with EADDRINUSE). Otherwise spawn
+   * `opencode serve`, hook stderr parsing, and race the readiness poll
+   * against the child's exit so port conflicts surface in <1s instead of
+   * timing out after 10s.
    */
   async ensureReady(): Promise<ServeReadiness> {
-    if (await this.probe()) return { kind: "already_running" }
+    const initial = await this.probe()
+    if (initial === "ok") return { kind: "already_running" }
+    if (initial === "auth_mismatch") {
+      const url = new URL(this.opts.baseUrl)
+      return { kind: "port_taken_auth_mismatch", port: url.port || "4096" }
+    }
 
     const url = new URL(this.opts.baseUrl)
     const proc = spawn({
@@ -61,9 +87,19 @@ export class ServeManager {
     const start = Date.now()
     let lastError = "no response"
     while (Date.now() - start < timeout) {
-      if (await this.probe()) return { kind: "spawned", pid: proc.pid ?? -1 }
+      // If the child died on its own (bind failure, bad args), don't keep
+      // polling — surface the exit immediately with whatever stderr we got.
+      if (proc.exitCode !== null) {
+        return {
+          kind: "spawn_failed",
+          exitCode: proc.exitCode,
+          stderrTail: this.stderrTail.join("\n"),
+        }
+      }
+      const status = await this.probe()
+      if (status === "ok") return { kind: "spawned", pid: proc.pid ?? -1 }
       await new Promise((r) => setTimeout(r, 200))
-      lastError = "still booting"
+      lastError = status === "auth_mismatch" ? "auth mismatch on /app" : "still booting"
     }
     return { kind: "timeout", lastError }
   }
@@ -77,17 +113,20 @@ export class ServeManager {
     this.child = null
   }
 
-  /** GET /app with Basic Auth. Returns true on 200. */
-  private async probe(): Promise<boolean> {
+  /** GET /app with Basic Auth.
+   *  200 → "ok"; 401/403 → "auth_mismatch" (port owned by another instance
+   *  whose password differs); anything else (network refused, 5xx, timeout)
+   *  → "offline". */
+  private async probe(): Promise<ProbeResult> {
     try {
       const res = await fetch(`${this.opts.baseUrl}/app`, {
         headers: {
           authorization: "Basic " + btoa(`:${this.opts.serverPassword}`),
         },
       })
-      return res.ok
+      return classifyProbeStatus(res.status)
     } catch {
-      return false
+      return "offline"
     }
   }
 
@@ -112,11 +151,24 @@ export class ServeManager {
   private handleLine(line: string): void {
     if (!line) return
     const audit = parseAuditLine(line)
-    if (audit) this.opts.onAuditLine?.(audit)
-    else this.opts.onDebugLine?.(line)
+    if (audit) {
+      this.opts.onAuditLine?.(audit)
+      return
+    }
+    this.stderrTail.push(line)
+    if (this.stderrTail.length > ServeManager.STDERR_TAIL_MAX) {
+      this.stderrTail.shift()
+    }
+    this.opts.onDebugLine?.(line)
   }
 }
 
+export function classifyProbeStatus(status: number): ProbeResult {
+  if (status >= 200 && status < 300) return "ok"
+  if (status === 401 || status === 403) return "auth_mismatch"
+  return "offline"
+}
+
 export function parseAuditLine(line: string): unknown | null {
   const prefixes = ["[kids-audit] ", "[kids-tui-audit] "]
   for (const prefix of prefixes) {

package/src/core/store.ts

@@ -28,6 +28,7 @@ export type Screen =
 
 export type ErrorVariant =
   | "serve_unreachable"
+  | "port_taken"
   | "network_down"
   | "stars_exhausted"
   | "auth_failed"

package/src/index.tsx

@@ -254,6 +254,26 @@ async function bootServices(env: KidsClientEnv, store: Store): Promise<ServiceSe
   })
 
   const readiness = await serve.ensureReady()
+  if (readiness.kind === "port_taken_auth_mismatch") {
+    store.update({
+      screen: {
+        kind: "error",
+        variant: "port_taken",
+        detail: `port ${readiness.port} held by another opencode serve`,
+      },
+    })
+    return null
+  }
+  if (readiness.kind === "spawn_failed") {
+    store.update({
+      screen: {
+        kind: "error",
+        variant: "serve_unreachable",
+        detail: `opencode serve exited (${readiness.exitCode}): ${readiness.stderrTail || "no stderr"}`,
+      },
+    })
+    return null
+  }
   if (readiness.kind === "timeout") {
     store.update({ screen: { kind: "error", variant: "serve_unreachable", detail: readiness.lastError } })
     return null
@@ -491,7 +511,23 @@ function makeFullHandlers(
         },
       })
       const again = await serve.ensureReady()
-      if (again.kind === "timeout") {
+      if (again.kind === "port_taken_auth_mismatch") {
+        store.update({
+          screen: {
+            kind: "error",
+            variant: "port_taken",
+            detail: `port ${again.port} held by another opencode serve`,
+          },
+        })
+      } else if (again.kind === "spawn_failed") {
+        store.update({
+          screen: {
+            kind: "error",
+            variant: "serve_unreachable",
+            detail: `opencode serve exited (${again.exitCode}): ${again.stderrTail || "no stderr"}`,
+          },
+        })
+      } else if (again.kind === "timeout") {
         store.update({ screen: { kind: "error", variant: "serve_unreachable", detail: again.lastError } })
       } else {
         store.update({ screen: { kind: "startup" } })

package/src/render/ink/components/KidsLogo.tsx

@@ -31,11 +31,13 @@ const SPARKLE_ROW_BOTTOM = "    ⭐      ✦        ⭐       ✦       "
 
 export function KidsLogo(): React.ReactElement {
   const theme = getTheme()
-  // Colors approximate the brand logo. Use "Bright" variants so dark terminals pop.
-  const cK = "cyanBright"
-  const cI = "yellow"
-  const cD = "greenBright"
-  const cS = "magentaBright"
+  // Theme-driven — DARK uses cyanBright/yellow/greenBright/magentaBright,
+  // LIGHT swaps to non-Bright variants (blue/yellow/green/magenta) that
+  // hold contrast on white macOS Terminal default.
+  const cK = theme.logoK
+  const cI = theme.logoI
+  const cD = theme.logoD
+  const cS = theme.logoS
   const gap = "  " // 2-col gap between letters
   return (
     <Box flexDirection="column" alignItems="center">

package/src/render/ink/screens/ErrorScreen.tsx

@@ -71,6 +71,11 @@ const STRINGS = {
       body: "后台 AI 服务好像没启动。要不要再试一次？",
       retry: "重试",
     },
+    port_taken: {
+      title: "另一个 AI 老师还在占着位子",
+      body: "请家长打开终端，跑一下：\n\n  kids-opencode --shutdown\n\n然后按 Enter 再试。",
+      retry: "已经关掉了，再试",
+    },
     network_down: {
       title: "网络有点问题",
       body: "我没办法连上 AI。等会儿再来，或者问家长检查网络。",
@@ -104,6 +109,11 @@ const STRINGS = {
       body: "The background AI service isn't running. Try again?",
       retry: "Retry",
     },
+    port_taken: {
+      title: "Another AI teacher is still holding the seat",
+      body: "Ask a parent to open a terminal and run:\n\n  kids-opencode --shutdown\n\nThen press Enter to try again.",
+      retry: "Done — try again",
+    },
     network_down: {
       title: "Network trouble",
       body: "I can't reach the AI. Try later, or ask an adult to check the connection.",

package/src/render/ink/theme.ts

@@ -1,10 +1,17 @@
 /**
- * Kid-warm color tokens. Hand-tuned to satisfy WCAG AA on most terminals
- * with dark backgrounds. High-contrast variant available via $KIDS_HC=1.
+ * Kid-warm color tokens. Three themes, picked automatically based on the
+ * terminal's background color (white-bg macOS Terminal vs dark-bg iTerm2
+ * vs anything we can't infer).
  *
- * Sourced conceptually from kids-tui-plugin/themes/kids-warm.json but
- * inlined here because Ink consumes raw ANSI/chalk color names, not
- * opentui theme JSON.
+ * Pick order:
+ *   1. KIDS_THEME=dark|light|hc  (explicit override; wins)
+ *   2. KIDS_HC=1                 (legacy flag, maps to "hc")
+ *   3. COLORFGBG env var         (terminal hint; "fg;bg" — macOS Terminal,
+ *                                  iTerm2, VS Code, gnome-terminal all set this)
+ *   4. fallback                  : "dark"
+ *
+ * Logo colors (logoK/I/D/S) are part of the theme so KidsLogo doesn't
+ * have to know which terminal it's on.
  */
 
 export interface Theme {
@@ -20,9 +27,15 @@ export interface Theme {
   system: string
   border: string
   stars: string
+  // Kids OpenCode brand mark, per-letter
+  logoK: string
+  logoI: string
+  logoD: string
+  logoS: string
 }
 
-const DEFAULT: Theme = {
+/** Default — vibrant on a dark terminal. */
+const DARK: Theme = {
   fg: "white",
   bg: "black",
   fgDim: "gray",
@@ -35,9 +48,39 @@ const DEFAULT: Theme = {
   system: "blueBright",
   border: "yellow",
   stars: "yellowBright",
+  logoK: "cyanBright",
+  logoI: "yellow",
+  logoD: "greenBright",
+  logoS: "magentaBright",
 }
 
-const HIGH_CONTRAST: Theme = {
+/**
+ * Light terminal (macOS Terminal.app default, light VS Code, etc.).
+ * Avoids Bright variants — they wash out to near-invisible on white.
+ * Uses non-Bright ANSI codes (33/32/36/35) which most terminals render
+ * as darker shades that hold contrast against white.
+ */
+const LIGHT: Theme = {
+  fg: "black",
+  bg: "white",
+  fgDim: "blackBright",   // dark gray — still readable on white
+  accent: "magenta",       // not yellow/cyan, those wash out
+  warn: "red",             // yellow text is unreadable on white
+  danger: "red",
+  success: "green",
+  agent: "blue",           // not cyan
+  kid: "magenta",
+  system: "blue",
+  border: "blackBright",   // medium gray frame
+  stars: "yellow",         // ANSI 33 = olive/brown on white = "gold-ish"
+  logoK: "blue",           // brand K — blue instead of teal
+  logoI: "yellow",         // olive on white, readable
+  logoD: "green",          // dark green
+  logoS: "magenta",        // dark magenta
+}
+
+/** High-contrast on dark — for poor-vision / low-light. */
+const HC: Theme = {
   fg: "whiteBright",
   bg: "black",
   fgDim: "white",
@@ -50,9 +93,56 @@ const HIGH_CONTRAST: Theme = {
   system: "blueBright",
   border: "whiteBright",
   stars: "yellowBright",
+  logoK: "cyanBright",
+  logoI: "yellowBright",
+  logoD: "greenBright",
+  logoS: "magentaBright",
+}
+
+export type ThemeKind = "dark" | "light" | "hc"
+
+export function resolveThemeKind(): ThemeKind {
+  // 1. Explicit env var
+  const explicit = (process.env.KIDS_THEME ?? "").toLowerCase()
+  if (explicit === "dark" || explicit === "light" || explicit === "hc") return explicit
+  // 2. Legacy flag
+  if (process.env.KIDS_HC === "1") return "hc"
+  // 3. COLORFGBG terminal hint
+  const detected = detectFromColorFgBg(process.env.COLORFGBG)
+  if (detected) return detected
+  // 4. Fallback
+  return "dark"
 }
 
 export function getTheme(): Theme {
-  if (process.env.KIDS_HC === "1") return HIGH_CONTRAST
-  return DEFAULT
+  const kind = resolveThemeKind()
+  if (kind === "light") return LIGHT
+  if (kind === "hc") return HC
+  return DARK
+}
+
+/**
+ * Parse the COLORFGBG env var. Format: "fg;bg" or "fg;default;bg" — a
+ * semicolon-separated list where the LAST field is the background color
+ * code (ANSI 0-15). 0-6 are dark; 7 is light gray; 8 is "bright black"
+ * (dark gray); 9-14 are bright dark-family; 15 is bright white.
+ *
+ * Empirically: macOS Terminal.app sets COLORFGBG=0;15 in light mode and
+ * 15;0 in Pro/Homebrew dark themes. iTerm2 mirrors. VS Code's integrated
+ * terminal also sets it.
+ *
+ * We treat 7 (light gray) and 15 (white) as "light"; everything else
+ * (incl. 8 dark-gray) as dark. Some terminals send "default" instead of
+ * a digit — we return null and let the caller fall through.
+ */
+export function detectFromColorFgBg(raw: string | undefined): ThemeKind | null {
+  if (!raw) return null
+  const parts = raw.split(";").map((s) => s.trim()).filter(Boolean)
+  if (parts.length === 0) return null
+  const bgStr = parts[parts.length - 1]!
+  if (bgStr === "default") return null
+  const bg = Number.parseInt(bgStr, 10)
+  if (!Number.isFinite(bg)) return null
+  if (bg === 7 || bg === 15) return "light"
+  return "dark"
 }