typescript-cli-default-port-shadow

Answer

Root cause: --server (and watch-game's --ws) carried static commander option defaults pointing at :3000. Static defaults bypass env resolution and hardcode the port shadowed by DuckBrain. The fix is one shared config.ts with runtime resolvers (flag > env > default) and no static URL defaults anywhere in the CLI.

1. src/config.ts — single source of truth

/** The real compose API port. :3000 is owned by a foreign daemon — never default to it. */
export const DEFAULT_SERVER_PORT = 3004;
export const DEFAULT_SERVER_URL = `http://localhost:${DEFAULT_SERVER_PORT}`;
export const DEFAULT_WS_URL = `ws://localhost:${DEFAULT_SERVER_PORT}`;

export const ENV_SERVER_URL = "MAFIA_SERVER_URL";
export const ENV_WS_URL = "MAFIA_WS_URL";

export function normalizeBase(url: string): string {
  return url.replace(/\/+$/, "");
}

/** http(s):// -> ws(s):// ; pass ws(s):// through untouched. */
export function httpToWs(url: string): string {
  const u = normalizeBase(url);
  if (/^wss?:\/\//i.test(u)) return u;
  return u.replace(/^https/i, "wss").replace(/^http/i, "ws");
}

/** Precedence: flag > MAFIA_SERVER_URL > http://localhost:3004 */
export function resolveServerUrl(flag?: string): string {
  const f = flag?.trim();
  if (f) return normalizeBase(f);
  const env = process.env[ENV_SERVER_URL]?.trim();
  if (env) return normalizeBase(env);
  return DEFAULT_SERVER_URL;
}

/** Precedence: wsFlag > MAFIA_WS_URL > derived at runtime from resolved server URL. */
export function resolveWsUrl(wsFlag?: string, serverFlag?: string): string {
  const f = wsFlag?.trim();
  if (f) return normalizeBase(f);
  const env = process.env[ENV_WS_URL]?.trim();
  if (env) return normalizeBase(env);
  return httpToWs(resolveServerUrl(serverFlag)); // runtime derivation, NOT a static default
}

2. CLI wiring — static defaults removed, resolved at runtime

program
  .option("--server <url>", "compose API base URL (flag > MAFIA_SERVER_URL > http://localhost:3004)")
  .option("--ws <url>", "WebSocket URL (flag > MAFIA_WS_URL > derived from server)");

program
  .command("watch-game")
  .option("--ws <url>", "WebSocket URL; resolved at runtime")
  .action(async (watchOpts) => {
    const parent = program.opts();
    const server = resolveServerUrl(parent.server);
    const ws = resolveWsUrl(watchOpts.ws ?? parent.ws, parent.server); // runtime, not static
    await guardEndpoint(server);
    console.log(`Watching ${ws} ...`);
  });

Key point: --server/--ws are now plain options (undefined when absent), so MAFIA_SERVER_URL flows into watch-game's WS endpoint at runtime — the old static commander default "ws://localhost:3000" is gone.

3. src/guard.ts — startup identity probe. A naive /health liveness check is insufficient (DuckBrain answers /health with {"status":"healthy"} too). The guard probes the identity route /api/v1 (only the compose API serves Mafia routes) with /health as connectivity fallback; it warns loudly and sets process.exitCode = 1 on mismatch, plus a no-network tripwire for port 3000 — it never guesses the URL for the user.