gambi 0.2.3

package/src/commands/list.ts

@@ -0,0 +1,104 @@
+import { confirm, intro, text } from "@clack/prompts";
+import { Command, Option } from "../utils/option.ts";
+import {
+  handleCancel,
+  hasExplicitFlags,
+  isInteractive,
+} from "../utils/prompt.ts";
+
+interface RoomInfo {
+  id: string;
+  code: string;
+  name: string;
+  hostId: string;
+  createdAt: number;
+  participantCount: number;
+}
+
+interface ListRoomsResponse {
+  rooms: RoomInfo[];
+}
+
+interface ErrorResponse {
+  error: string;
+}
+
+export class ListCommand extends Command {
+  static override paths = [["list"]];
+
+  static override usage = Command.Usage({
+    description: "List available rooms on a hub",
+    examples: [
+      ["List rooms (interactive)", "gambi list"],
+      ["List on custom hub", "gambi list --hub http://192.168.1.10:3000"],
+    ],
+  });
+
+  hub = Option.String("--hub,-H", "http://localhost:3000", {
+    description: "Hub URL",
+  });
+
+  json = Option.Boolean("--json,-j", false, {
+    description: "Output as JSON",
+  });
+
+  async execute(): Promise<number> {
+    let hub = this.hub;
+    let json = this.json;
+
+    if (!hasExplicitFlags() && isInteractive()) {
+      intro("gambi list");
+
+      const hubResult = await text({
+        message: "Hub URL:",
+        defaultValue: "http://localhost:3000",
+        placeholder: "http://localhost:3000",
+      });
+      handleCancel(hubResult);
+      hub = hubResult as string;
+
+      const jsonResult = await confirm({
+        message: "Output as JSON?",
+        initialValue: false,
+      });
+      handleCancel(jsonResult);
+      json = jsonResult as boolean;
+    }
+
+    try {
+      const response = await fetch(`${hub}/rooms`);
+
+      if (!response.ok) {
+        const data = (await response.json()) as ErrorResponse;
+        this.context.stderr.write(`Error: ${data.error}\n`);
+        return 1;
+      }
+
+      const data = (await response.json()) as ListRoomsResponse;
+      const rooms = data.rooms;
+
+      if (json) {
+        this.context.stdout.write(`${JSON.stringify(rooms, null, 2)}\n`);
+      } else if (rooms.length === 0) {
+        this.context.stdout.write("No rooms available.\n");
+      } else {
+        this.context.stdout.write("Available rooms:\n\n");
+        for (const room of rooms) {
+          this.context.stdout.write(`  ${room.code}  ${room.name}\n`);
+          this.context.stdout.write(
+            `    Participants: ${room.participantCount}\n`
+          );
+          this.context.stdout.write(
+            `    Created: ${new Date(room.createdAt).toLocaleString()}\n\n`
+          );
+        }
+      }
+
+      return 0;
+    } catch (err) {
+      this.context.stderr.write(`Failed to connect to hub at ${hub}\n`);
+      this.context.stderr.write(`${err}\n`);
+      return 1;
+    }
+  }
+}

package/src/commands/monitor.ts

@@ -0,0 +1,27 @@
+import { Command, Option } from "../utils/option.ts";
+
+export class MonitorCommand extends Command {
+  static override paths = [["monitor"]];
+
+  static override usage = Command.Usage({
+    description: "Open TUI to monitor rooms in real-time",
+    examples: [
+      ["Monitor local hub", "gambi monitor"],
+      [
+        "Monitor remote hub",
+        "gambi monitor --hub http://192.168.1.100:3000",
+      ],
+    ],
+  });
+
+  hub = Option.String("--hub,-h", "http://localhost:3000", {
+    description: "Hub URL to connect to",
+  });
+
+  async execute(): Promise<number> {
+    this.context.stderr.write(
+      "TUI is not bundled in the standalone binary.\nInstall via npm/bun for TUI support: npm install -g gambi\nThen run: gambi monitor\n",
+    );
+    return 1;
+  }
+}

package/src/commands/serve.ts

@@ -0,0 +1,116 @@
+import { hostname as getHostname } from "node:os";
+import { confirm, intro, text } from "@clack/prompts";
+import { createHub } from "@gambi/core/hub";
+import { printLogo } from "@gambi/core/logo";
+import { Command, Option } from "../utils/option.ts";
+import {
+  handleCancel,
+  hasExplicitFlags,
+  isInteractive,
+} from "../utils/prompt.ts";
+
+export class ServeCommand extends Command {
+  static override paths = [["serve"]];
+
+  static override usage = Command.Usage({
+    description: "Start the Gambi hub server",
+    examples: [
+      ["Start with interactive setup", "gambi serve"],
+      ["Start on default port 3000", "gambi serve --port 3000"],
+      ["Start on custom port", "gambi serve --port 8080"],
+      ["Start with mDNS discovery", "gambi serve --mdns"],
+    ],
+  });
+
+  port = Option.String("--port,-p", "3000", {
+    description: "Port to listen on",
+  });
+
+  host = Option.String("--host,-h", "0.0.0.0", {
+    description: "Host to bind to",
+  });
+
+  mdns = Option.Boolean("--mdns,-m", false, {
+    description: "Enable mDNS (Bonjour/Zeroconf) for local network discovery",
+  });
+
+  quiet = Option.Boolean("--quiet,-q", false, {
+    description: "Suppress logo output",
+  });
+
+  async execute(): Promise<number> {
+    let port = this.port;
+    let host = this.host;
+    let mdns = this.mdns;
+
+    if (!hasExplicitFlags() && isInteractive()) {
+      intro("gambi serve");
+
+      const portResult = await text({
+        message: "Port:",
+        defaultValue: "3000",
+        placeholder: "3000",
+      });
+      handleCancel(portResult);
+      port = portResult as string;
+
+      const hostResult = await text({
+        message: "Host:",
+        defaultValue: "0.0.0.0",
+        placeholder: "0.0.0.0",
+      });
+      handleCancel(hostResult);
+      host = hostResult as string;
+
+      const mdnsResult = await confirm({
+        message: "Enable mDNS discovery?",
+        initialValue: false,
+      });
+      handleCancel(mdnsResult);
+      mdns = mdnsResult as boolean;
+    }
+
+    if (!this.quiet) {
+      printLogo();
+    }
+
+    const portNum = Number.parseInt(port, 10);
+    if (Number.isNaN(portNum)) {
+      this.context.stderr.write(`Invalid port: ${port}\n`);
+      return 1;
+    }
+
+    const hub = createHub({
+      port: portNum,
+      hostname: host,
+      mdns,
+    });
+
+    this.context.stdout.write(`Hub started at ${hub.url}\n`);
+    this.context.stdout.write(
+      `Health check: http://${host}:${portNum}/health\n`
+    );
+
+    if (hub.mdnsName) {
+      const localHostname = getHostname();
+      this.context.stdout.write(
+        `mDNS: http://${localHostname}.local:${portNum}\n`
+      );
+      this.context.stdout.write(
+        `      Service: ${hub.mdnsName}._gambi._tcp.local\n`
+      );
+    }
+
+    this.context.stdout.write("\nPress Ctrl+C to stop\n");
+
+    process.on("SIGINT", () => {
+      this.context.stdout.write("\nShutting down...\n");
+      hub.close();
+      process.exit(0);
+    });
+
+    // Keep process running until SIGINT
+    await new Promise(() => undefined);
+    return 0;
+  }
+}

package/src/utils/network-endpoint.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+import {
+  isLoopbackLikeHost,
+  isRemoteHubUrl,
+  rankNetworkCandidatesForHub,
+  replaceEndpointHost,
+} from "./network-endpoint.ts";
+
+describe("network endpoint helpers", () => {
+  test("detects loopback-like hosts", () => {
+    expect(isLoopbackLikeHost("localhost")).toBe(true);
+    expect(isLoopbackLikeHost("127.0.0.1")).toBe(true);
+    expect(isLoopbackLikeHost("0.0.0.0")).toBe(true);
+    expect(isLoopbackLikeHost("192.168.1.25")).toBe(false);
+  });
+
+  test("distinguishes local and remote hubs", () => {
+    expect(isRemoteHubUrl("http://localhost:3000")).toBe(false);
+    expect(isRemoteHubUrl("http://127.0.0.1:3000")).toBe(false);
+    expect(isRemoteHubUrl("http://192.168.1.10:3000")).toBe(true);
+  });
+
+  test("prioritizes candidates on the same /24 subnet as the hub", () => {
+    const ranked = rankNetworkCandidatesForHub("http://192.168.1.10:3000", [
+      { address: "10.0.0.25", interfaceName: "en1" },
+      { address: "192.168.1.25", interfaceName: "en0" },
+      { address: "192.168.2.30", interfaceName: "en2" },
+    ]);
+
+    expect(ranked).toEqual([
+      { address: "192.168.1.25", interfaceName: "en0" },
+    ]);
+  });
+
+  test("replaces only the endpoint host", () => {
+    expect(
+      replaceEndpointHost("http://localhost:11434/v1/models", "192.168.1.25")
+    ).toBe("http://192.168.1.25:11434/v1/models");
+  });
+});

package/src/utils/network-endpoint.ts

@@ -0,0 +1,136 @@
+import { networkInterfaces } from "node:os";
+
+export interface NetworkCandidate {
+  address: string;
+  interfaceName: string;
+}
+
+const IPV4_FAMILY = "IPv4";
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1", "localhost"]);
+const UNSPECIFIED_HOSTS = new Set(["0.0.0.0", "::"]);
+
+function getIpv4Octets(address: string): number[] | null {
+  const segments = address.split(".");
+  if (segments.length !== 4) {
+    return null;
+  }
+
+  const octets = segments.map((segment) => Number(segment));
+  return octets.every((octet) => Number.isInteger(octet) && octet >= 0 && octet <= 255)
+    ? octets
+    : null;
+}
+
+function isLinkLocalIpv4(address: string): boolean {
+  const octets = getIpv4Octets(address);
+  return octets !== null && octets[0] === 169 && octets[1] === 254;
+}
+
+function isPrivateIpv4(address: string): boolean {
+  const octets = getIpv4Octets(address);
+  if (octets === null) {
+    return false;
+  }
+
+  const first = octets[0];
+  const second = octets[1];
+  if (first === undefined || second === undefined) {
+    return false;
+  }
+
+  return (
+    first === 10 ||
+    (first === 172 && second >= 16 && second <= 31) ||
+    (first === 192 && second === 168)
+  );
+}
+
+function isSameSubnet24(left: string, right: string): boolean {
+  const leftOctets = getIpv4Octets(left);
+  const rightOctets = getIpv4Octets(right);
+  if (!(leftOctets && rightOctets)) {
+    return false;
+  }
+
+  return (
+    leftOctets[0] === rightOctets[0] &&
+    leftOctets[1] === rightOctets[1] &&
+    leftOctets[2] === rightOctets[2]
+  );
+}
+
+export function isLoopbackHost(hostname: string): boolean {
+  return LOOPBACK_HOSTS.has(hostname.toLowerCase());
+}
+
+export function isUnspecifiedHost(hostname: string): boolean {
+  return UNSPECIFIED_HOSTS.has(hostname.toLowerCase());
+}
+
+export function isLoopbackLikeHost(hostname: string): boolean {
+  return isLoopbackHost(hostname) || isUnspecifiedHost(hostname);
+}
+
+export function isRemoteHubUrl(hubUrl: string): boolean {
+  const { hostname } = new URL(hubUrl);
+  return !isLoopbackLikeHost(hostname);
+}
+
+export function listNetworkCandidates(): NetworkCandidate[] {
+  const candidates: NetworkCandidate[] = [];
+  const interfaces = networkInterfaces();
+
+  for (const [interfaceName, entries] of Object.entries(interfaces)) {
+    if (!entries) {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (
+        entry.family !== IPV4_FAMILY ||
+        entry.internal ||
+        isLinkLocalIpv4(entry.address)
+      ) {
+        continue;
+      }
+
+      candidates.push({
+        interfaceName,
+        address: entry.address,
+      });
+    }
+  }
+
+  return candidates;
+}
+
+export function rankNetworkCandidatesForHub(
+  hubUrl: string,
+  candidates: NetworkCandidate[]
+): NetworkCandidate[] {
+  const { hostname } = new URL(hubUrl);
+
+  const sameSubnet = candidates.filter((candidate) =>
+    isSameSubnet24(candidate.address, hostname)
+  );
+  if (sameSubnet.length > 0) {
+    return sameSubnet;
+  }
+
+  if (isPrivateIpv4(hostname)) {
+    const privateCandidates = candidates.filter((candidate) =>
+      isPrivateIpv4(candidate.address)
+    );
+    if (privateCandidates.length > 0) {
+      return privateCandidates;
+    }
+  }
+
+  return candidates;
+}
+
+export function replaceEndpointHost(endpoint: string, hostname: string): string {
+  const url = new URL(endpoint);
+  url.hostname = hostname;
+  return url.toString();
+}

package/src/utils/option.ts

@@ -0,0 +1,10 @@
+// Workaround for Bun bundler bug: Clipanion's ESM barrel export of `String`
+// collides with the global `String` during `bun build --compile`.
+// Using require() instead of import bypasses the ESM re-export resolution.
+// See: https://github.com/oven-sh/bun/issues — Bun bundler String collision
+const clipanion = require("clipanion");
+
+export const Command: typeof import("clipanion").Command = clipanion.Command;
+export const Option: typeof import("clipanion").Option = clipanion.Option;
+export const Builtins: typeof import("clipanion").Builtins = clipanion.Builtins;
+export const Cli: typeof import("clipanion").Cli = clipanion.Cli;

package/src/utils/prompt.ts

@@ -0,0 +1,24 @@
+import { cancel, isCancel } from "@clack/prompts";
+
+export function isInteractive(): boolean {
+  return !!process.stdin.isTTY && !!process.stdout.isTTY;
+}
+
+export function handleCancel(value: unknown): void {
+  if (isCancel(value)) {
+    cancel("Operation cancelled.");
+    process.exit(0);
+  }
+}
+
+export function hasExplicitFlags(): boolean {
+  const args = process.argv.slice(2);
+  // First arg is the command name, check if there are more args after it
+  return args.length > 1;
+}
+
+export const LLM_PROVIDERS = [
+  { name: "Ollama", port: 11_434 },
+  { name: "LM Studio", port: 1234 },
+  { name: "vLLM", port: 8000 },
+] as const;

package/src/utils/runtime-config.ts

@@ -0,0 +1,211 @@
+import { resolve } from "node:path";
+import { confirm, text } from "@clack/prompts";
+import {
+  RuntimeConfig,
+  type RuntimeConfig as RuntimeConfigValue,
+} from "@gambi/core/types";
+import { handleCancel } from "./prompt.ts";
+
+function parseOptionalNumber(
+  input: string,
+  fieldName: string
+): number | undefined {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+
+  const parsed = Number(trimmed);
+  if (Number.isNaN(parsed)) {
+    throw new Error(`Invalid ${fieldName}: expected a number.`);
+  }
+
+  return parsed;
+}
+
+function parseOptionalStopSequences(input: string): string[] | undefined {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+
+  const values = trimmed
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean);
+
+  return values.length > 0 ? values : undefined;
+}
+
+function getCurrentValue<T>(value: T | undefined): string {
+  if (value === undefined) {
+    return "";
+  }
+
+  if (Array.isArray(value)) {
+    return value.join(", ");
+  }
+
+  return String(value);
+}
+
+export function hasRuntimeConfig(
+  config: RuntimeConfigValue | undefined
+): config is RuntimeConfigValue {
+  return config !== undefined && Object.keys(config).length > 0;
+}
+
+export async function loadRuntimeConfigFile(
+  configPath: string
+): Promise<RuntimeConfigValue> {
+  const resolvedPath = resolve(configPath);
+  const file = Bun.file(resolvedPath);
+
+  if (!(await file.exists())) {
+    throw new Error(`Config file not found: ${resolvedPath}`);
+  }
+
+  let parsedJson: unknown;
+  try {
+    parsedJson = JSON.parse(await file.text());
+  } catch (error) {
+    throw new Error(
+      `Invalid JSON in config file ${resolvedPath}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+
+  const parsed = RuntimeConfig.safeParse(parsedJson);
+  if (!parsed.success) {
+    throw new Error(
+      `Invalid runtime config in ${resolvedPath}: ${parsed.error.message}`
+    );
+  }
+
+  return parsed.data;
+}
+
+export async function promptRuntimeConfig(
+  scope: "participant" | "room",
+  initialConfig: RuntimeConfigValue = {}
+): Promise<RuntimeConfigValue> {
+  const shouldConfigure = await confirm({
+    message:
+      scope === "participant"
+        ? "Configure participant defaults (instructions, temperature, etc.)?"
+        : "Configure room defaults (instructions, temperature, etc.)?",
+    initialValue: hasRuntimeConfig(initialConfig),
+  });
+  handleCancel(shouldConfigure);
+
+  if (!shouldConfigure) {
+    return initialConfig;
+  }
+
+  const instructionsResult = await text({
+    message: "Instructions / system prompt:",
+    placeholder: getCurrentValue(initialConfig.instructions),
+  });
+  handleCancel(instructionsResult);
+
+  const temperatureResult = await text({
+    message: "Temperature:",
+    placeholder: getCurrentValue(initialConfig.temperature),
+  });
+  handleCancel(temperatureResult);
+
+  const topPResult = await text({
+    message: "Top-p:",
+    placeholder: getCurrentValue(initialConfig.top_p),
+  });
+  handleCancel(topPResult);
+
+  const maxTokensResult = await text({
+    message: "Max tokens:",
+    placeholder: getCurrentValue(initialConfig.max_tokens),
+  });
+  handleCancel(maxTokensResult);
+
+  const stopResult = await text({
+    message: "Stop sequences (comma-separated):",
+    placeholder: getCurrentValue(initialConfig.stop),
+  });
+  handleCancel(stopResult);
+
+  const frequencyPenaltyResult = await text({
+    message: "Frequency penalty:",
+    placeholder: getCurrentValue(initialConfig.frequency_penalty),
+  });
+  handleCancel(frequencyPenaltyResult);
+
+  const presencePenaltyResult = await text({
+    message: "Presence penalty:",
+    placeholder: getCurrentValue(initialConfig.presence_penalty),
+  });
+  handleCancel(presencePenaltyResult);
+
+  const seedResult = await text({
+    message: "Seed:",
+    placeholder: getCurrentValue(initialConfig.seed),
+  });
+  handleCancel(seedResult);
+
+  const config: RuntimeConfigValue = {
+    ...initialConfig,
+  };
+
+  const instructions = String(instructionsResult).trim();
+  if (instructions) {
+    config.instructions = instructions;
+  }
+
+  const temperature = parseOptionalNumber(
+    String(temperatureResult),
+    "temperature"
+  );
+  if (temperature !== undefined) {
+    config.temperature = temperature;
+  }
+
+  const topP = parseOptionalNumber(String(topPResult), "top_p");
+  if (topP !== undefined) {
+    config.top_p = topP;
+  }
+
+  const maxTokens = parseOptionalNumber(String(maxTokensResult), "max_tokens");
+  if (maxTokens !== undefined) {
+    config.max_tokens = maxTokens;
+  }
+
+  const stop = parseOptionalStopSequences(String(stopResult));
+  if (stop !== undefined) {
+    config.stop = stop;
+  }
+
+  const frequencyPenalty = parseOptionalNumber(
+    String(frequencyPenaltyResult),
+    "frequency_penalty"
+  );
+  if (frequencyPenalty !== undefined) {
+    config.frequency_penalty = frequencyPenalty;
+  }
+
+  const presencePenalty = parseOptionalNumber(
+    String(presencePenaltyResult),
+    "presence_penalty"
+  );
+  if (presencePenalty !== undefined) {
+    config.presence_penalty = presencePenalty;
+  }
+
+  const seed = parseOptionalNumber(String(seedResult), "seed");
+  if (seed !== undefined) {
+    config.seed = seed;
+  }
+
+  const parsed = RuntimeConfig.safeParse(config);
+  if (!parsed.success) {
+    throw new Error(`Invalid runtime config: ${parsed.error.message}`);
+  }
+
+  return parsed.data;
+}