straylight-ai 0.1.0

package/src/__tests__/health.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// Mock global fetch
+const mockFetch = vi.fn();
+vi.stubGlobal("fetch", mockFetch);
+
+import { waitForHealth, checkHealth } from "../health.js";
+
+beforeEach(() => {
+  vi.resetAllMocks();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("checkHealth", () => {
+  it("returns health response when endpoint is healthy", async () => {
+    const healthData = { status: "ok", version: "0.1.0" };
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => healthData,
+    });
+
+    const result = await checkHealth("http://localhost:9470/api/v1/health");
+    expect(result).toEqual(healthData);
+  });
+
+  it("throws when fetch returns non-ok status", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 503,
+    });
+
+    await expect(
+      checkHealth("http://localhost:9470/api/v1/health")
+    ).rejects.toThrow();
+  });
+
+  it("throws when fetch rejects (connection refused)", async () => {
+    mockFetch.mockRejectedValueOnce(new Error("ECONNREFUSED"));
+
+    await expect(
+      checkHealth("http://localhost:9470/api/v1/health")
+    ).rejects.toThrow("ECONNREFUSED");
+  });
+});
+
+describe("waitForHealth", () => {
+  it("resolves immediately when health check passes on first attempt", async () => {
+    const healthData = { status: "ok", version: "0.1.0" };
+    mockFetch.mockResolvedValue({
+      ok: true,
+      json: async () => healthData,
+    });
+
+    const result = await waitForHealth(
+      "http://localhost:9470/api/v1/health",
+      30_000
+    );
+    expect(result).toEqual(healthData);
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("retries until health check passes within timeout", async () => {
+    const healthData = { status: "ok", version: "0.1.0" };
+    // Fail 2 times, then succeed
+    mockFetch
+      .mockRejectedValueOnce(new Error("ECONNREFUSED"))
+      .mockRejectedValueOnce(new Error("ECONNREFUSED"))
+      .mockResolvedValue({
+        ok: true,
+        json: async () => healthData,
+      });
+
+    // Use fake timers so we don't actually wait 2 seconds
+    vi.useFakeTimers();
+    const promise = waitForHealth(
+      "http://localhost:9470/api/v1/health",
+      30_000
+    );
+    // Advance past the sleep intervals
+    await vi.runAllTimersAsync();
+    const result = await promise;
+    vi.useRealTimers();
+
+    expect(result).toEqual(healthData);
+    expect(mockFetch).toHaveBeenCalledTimes(3);
+  });
+
+  it("rejects when health check never passes within timeout", async () => {
+    mockFetch.mockRejectedValue(new Error("ECONNREFUSED"));
+
+    vi.useFakeTimers();
+
+    // Attach rejection handler before advancing timers so the rejection
+    // is never unhandled.
+    const promise = waitForHealth("http://localhost:9470/api/v1/health", 1_000);
+    const rejection = expect(promise).rejects.toThrow(/timed out|timeout/i);
+
+    // Advance time past the deadline and flush all microtasks
+    await vi.advanceTimersByTimeAsync(2_000);
+    vi.useRealTimers();
+
+    await rejection;
+  });
+});

package/src/__tests__/mcp-register.test.ts

@@ -0,0 +1,123 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+vi.mock("child_process", () => ({
+  execSync: vi.fn(),
+  spawnSync: vi.fn(),
+}));
+
+import { execSync, spawnSync } from "child_process";
+import {
+  registerMCP,
+  isClaudeAvailable,
+  manualRegistrationInstructions,
+} from "../mcp-register.js";
+
+const mockExecSync = vi.mocked(execSync);
+const mockSpawnSync = vi.mocked(spawnSync);
+
+beforeEach(() => {
+  vi.resetAllMocks();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("isClaudeAvailable", () => {
+  it("returns true when claude CLI is available", () => {
+    mockExecSync.mockReturnValue(Buffer.from("claude version 1.0.0"));
+    expect(isClaudeAvailable()).toBe(true);
+  });
+
+  it("returns false when claude CLI is not found", () => {
+    mockExecSync.mockImplementation(() => {
+      throw new Error("command not found: claude");
+    });
+    expect(isClaudeAvailable()).toBe(false);
+  });
+});
+
+describe("registerMCP", () => {
+  it("returns true and registers MCP when claude is available", async () => {
+    // First call: claude --version succeeds
+    mockExecSync.mockReturnValue(Buffer.from("claude version 1.0.0"));
+    // spawnSync for the mcp add command
+    mockSpawnSync.mockReturnValue({
+      status: 0,
+      stdout: Buffer.from(""),
+      stderr: Buffer.from(""),
+      pid: 1234,
+      output: [],
+      signal: null,
+    });
+
+    const result = await registerMCP();
+    expect(result).toBe(true);
+    expect(mockSpawnSync).toHaveBeenCalledWith(
+      "claude",
+      expect.arrayContaining(["mcp", "add"]),
+      expect.any(Object)
+    );
+  });
+
+  it("returns false when claude CLI is not available", async () => {
+    mockExecSync.mockImplementation(() => {
+      throw new Error("command not found: claude");
+    });
+
+    const result = await registerMCP();
+    expect(result).toBe(false);
+    expect(mockSpawnSync).not.toHaveBeenCalled();
+  });
+
+  it("returns false when mcp add command fails", async () => {
+    mockExecSync.mockReturnValue(Buffer.from("claude version 1.0.0"));
+    mockSpawnSync.mockReturnValue({
+      status: 1,
+      stdout: Buffer.from(""),
+      stderr: Buffer.from("error: already exists"),
+      pid: 1234,
+      output: [],
+      signal: null,
+    });
+
+    const result = await registerMCP();
+    expect(result).toBe(false);
+  });
+
+  it("includes correct arguments in the registration command", async () => {
+    mockExecSync.mockReturnValue(Buffer.from("claude version 1.0.0"));
+    mockSpawnSync.mockReturnValue({
+      status: 0,
+      stdout: Buffer.from(""),
+      stderr: Buffer.from(""),
+      pid: 1234,
+      output: [],
+      signal: null,
+    });
+
+    await registerMCP();
+
+    const args = mockSpawnSync.mock.calls[0][1] as string[];
+    expect(args).toContain("mcp");
+    expect(args).toContain("add");
+    expect(args).toContain("straylight-ai");
+    expect(args).toContain("--transport");
+    expect(args).toContain("stdio");
+  });
+});
+
+describe("manualRegistrationInstructions", () => {
+  it("returns a non-empty string with the registration command", () => {
+    const instructions = manualRegistrationInstructions();
+    expect(typeof instructions).toBe("string");
+    expect(instructions.length).toBeGreaterThan(0);
+  });
+
+  it("includes the claude mcp add command", () => {
+    const instructions = manualRegistrationInstructions();
+    expect(instructions).toContain("claude mcp add");
+    expect(instructions).toContain("straylight-ai");
+    expect(instructions).toContain("--transport stdio");
+  });
+});

package/src/__tests__/open.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+vi.mock("child_process", () => ({
+  spawn: vi.fn(),
+}));
+
+import { spawn } from "child_process";
+import { openBrowser } from "../open.js";
+
+const mockSpawn = vi.mocked(spawn);
+
+/** Creates a minimal EventEmitter-like mock child process. */
+function makeChildMock() {
+  return {
+    unref: vi.fn(),
+    on: vi.fn(),
+  };
+}
+
+beforeEach(() => {
+  vi.resetAllMocks();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("openBrowser", () => {
+  it("calls spawn with the URL and detached option", async () => {
+    const child = makeChildMock();
+    // Return typed mock - cast needed because spawn returns full ChildProcess
+    mockSpawn.mockReturnValue(child as unknown as ReturnType<typeof spawn>);
+
+    await openBrowser("http://localhost:9470");
+
+    expect(mockSpawn).toHaveBeenCalledWith(
+      expect.any(String),
+      ["http://localhost:9470"],
+      expect.objectContaining({ detached: true })
+    );
+  });
+
+  it("calls unref on the child process to detach it", async () => {
+    const child = makeChildMock();
+    mockSpawn.mockReturnValue(child as unknown as ReturnType<typeof spawn>);
+
+    await openBrowser("http://localhost:9470");
+
+    expect(child.unref).toHaveBeenCalled();
+  });
+
+  it("resolves without error even when spawn fails", async () => {
+    // spawn throws synchronously
+    mockSpawn.mockImplementation(() => {
+      throw new Error("spawn ENOENT");
+    });
+
+    // Should not throw (best-effort open)
+    await expect(openBrowser("http://localhost:9470")).resolves.toBeUndefined();
+  });
+});

package/src/commands/setup.ts

@@ -0,0 +1,72 @@
+import { execSync } from "child_process";
+import {
+  detectRuntime,
+  getContainerStatus,
+  buildRunCommand,
+  buildStartCommand,
+} from "../docker.js";
+import { waitForHealth } from "../health.js";
+import { registerMCP, manualRegistrationInstructions } from "../mcp-register.js";
+import { openBrowser } from "../open.js";
+
+const HEALTH_URL = "http://localhost:9470/api/v1/health";
+const HEALTH_TIMEOUT_MS = 30_000;
+const UI_URL = "http://localhost:9470";
+
+/**
+ * Full bootstrap: pull image if needed, create/start container, wait for
+ * health check, register MCP server, and open the browser.
+ *
+ * This operation is idempotent: calling it when the container is already
+ * running will skip the create/start steps and go straight to health + open.
+ */
+export async function runSetup(): Promise<void> {
+  const runtime = detectRuntime();
+  if (!runtime) {
+    throw new Error(
+      "Neither Docker nor Podman was found on your PATH.\n" +
+        "Install Docker Desktop: https://docs.docker.com/get-docker/\n" +
+        "or Podman: https://podman.io/getting-started/installation"
+    );
+  }
+
+  console.log(`Using container runtime: ${runtime}`);
+
+  const status = await getContainerStatus(runtime);
+
+  if (status === "not_found") {
+    console.log("Creating and starting Straylight-AI container...");
+    execSync(buildRunCommand(runtime), { stdio: "inherit" });
+  } else if (status === "stopped") {
+    console.log("Starting existing Straylight-AI container...");
+    execSync(buildStartCommand(runtime), { stdio: "inherit" });
+  } else {
+    console.log("Straylight-AI container is already running.");
+  }
+
+  console.log("Waiting for Straylight-AI to be ready...");
+  await waitForHealth(HEALTH_URL, HEALTH_TIMEOUT_MS);
+  console.log("Straylight-AI is ready.");
+
+  const registered = await registerMCP();
+  if (registered) {
+    console.log("MCP server registered with Claude Code.");
+  } else {
+    console.log(manualRegistrationInstructions());
+  }
+
+  await openBrowser(UI_URL);
+
+  console.log(
+    [
+      "",
+      "Straylight-AI is running at http://localhost:9470",
+      "",
+      "Next steps:",
+      "  1. Open http://localhost:9470 in your browser",
+      "  2. Add your service credentials via the Web UI",
+      "  3. Use Claude Code with the straylight-ai MCP server",
+      "",
+    ].join("\n")
+  );
+}

package/src/commands/start.ts

@@ -0,0 +1,44 @@
+import { execSync } from "child_process";
+import {
+  detectRuntime,
+  getContainerStatus,
+  buildStartCommand,
+} from "../docker.js";
+import { waitForHealth } from "../health.js";
+
+const HEALTH_URL = "http://localhost:9470/api/v1/health";
+const HEALTH_TIMEOUT_MS = 30_000;
+
+/**
+ * Start an existing stopped container and wait for health.
+ * Errors if the container does not exist (use `setup` instead).
+ */
+export async function runStart(): Promise<void> {
+  const runtime = detectRuntime();
+  if (!runtime) {
+    throw new Error(
+      "Neither Docker nor Podman was found on your PATH.\n" +
+        "Install Docker Desktop: https://docs.docker.com/get-docker/"
+    );
+  }
+
+  const status = await getContainerStatus(runtime);
+
+  if (status === "not_found") {
+    throw new Error(
+      "Straylight-AI container not found. Run `npx straylight-ai setup` first."
+    );
+  }
+
+  if (status === "running") {
+    console.log("Straylight-AI is already running.");
+    return;
+  }
+
+  console.log("Starting Straylight-AI...");
+  execSync(buildStartCommand(runtime), { stdio: "inherit" });
+
+  console.log("Waiting for Straylight-AI to be ready...");
+  await waitForHealth(HEALTH_URL, HEALTH_TIMEOUT_MS);
+  console.log("Straylight-AI is ready at http://localhost:9470");
+}

package/src/commands/status.ts

@@ -0,0 +1,51 @@
+import { detectRuntime, getContainerStatus } from "../docker.js";
+import { checkHealth, HealthResponse } from "../health.js";
+
+const HEALTH_URL = "http://localhost:9470/api/v1/health";
+
+/** Result returned by runStatus */
+export interface StatusResult {
+  containerStatus: "running" | "stopped" | "not_found";
+  health?: HealthResponse;
+}
+
+/**
+ * Check the container status and, if running, fetch and display health info.
+ */
+export async function runStatus(): Promise<StatusResult> {
+  const runtime = detectRuntime();
+  if (!runtime) {
+    throw new Error(
+      "Neither Docker nor Podman was found on your PATH.\n" +
+        "Install Docker Desktop: https://docs.docker.com/get-docker/"
+    );
+  }
+
+  const containerStatus = await getContainerStatus(runtime);
+
+  const result: StatusResult = { containerStatus };
+
+  if (containerStatus === "running") {
+    try {
+      result.health = await checkHealth(HEALTH_URL);
+      console.log("Straylight-AI is running.");
+      console.log(`  Status: ${result.health.status}`);
+      if (result.health.version) {
+        console.log(`  Version: ${result.health.version}`);
+      }
+      console.log("  URL: http://localhost:9470");
+    } catch {
+      console.log("Straylight-AI container is running but not yet healthy.");
+    }
+  } else if (containerStatus === "stopped") {
+    console.log(
+      'Straylight-AI container is stopped. Run `npx straylight-ai start` to start it.'
+    );
+  } else {
+    console.log(
+      'Straylight-AI is not installed. Run `npx straylight-ai setup` to get started.'
+    );
+  }
+
+  return result;
+}

package/src/commands/stop.ts

@@ -0,0 +1,31 @@
+import { execSync } from "child_process";
+import {
+  detectRuntime,
+  isContainerRunning,
+  buildStopCommand,
+} from "../docker.js";
+
+/**
+ * Stop the running Straylight-AI container.
+ * No-op if the container is not currently running.
+ */
+export async function runStop(): Promise<void> {
+  const runtime = detectRuntime();
+  if (!runtime) {
+    throw new Error(
+      "Neither Docker nor Podman was found on your PATH.\n" +
+        "Install Docker Desktop: https://docs.docker.com/get-docker/"
+    );
+  }
+
+  const running = await isContainerRunning(runtime);
+
+  if (!running) {
+    console.log("Straylight-AI is not currently running.");
+    return;
+  }
+
+  console.log("Stopping Straylight-AI...");
+  execSync(buildStopCommand(runtime), { stdio: "inherit" });
+  console.log("Straylight-AI stopped.");
+}

package/src/docker.ts

@@ -0,0 +1,102 @@
+import { execSync } from "child_process";
+import * as os from "os";
+import * as path from "path";
+
+/** Name of the managed container */
+export const CONTAINER_NAME = "straylight-ai";
+
+/** Docker image to pull and run */
+export const CONTAINER_IMAGE = "ghcr.io/aj-geddes/straylight-ai:latest";
+
+/** Host port mapped to container port 9470 */
+export const CONTAINER_PORT = 9470;
+
+/** Host data directory mounted at /data inside the container */
+export const DATA_DIR = path.join(os.homedir(), ".straylight-ai", "data");
+
+/** Container status values */
+export type ContainerStatus = "running" | "stopped" | "not_found";
+
+/** Supported container runtimes */
+export type Runtime = "docker" | "podman";
+
+/**
+ * Detect whether docker or podman is available on the host.
+ * Returns the first available runtime, or null if neither is found.
+ */
+export function detectRuntime(): Runtime | null {
+  for (const runtime of ["docker", "podman"] as Runtime[]) {
+    try {
+      execSync(`${runtime} --version`, { stdio: "pipe" });
+      return runtime;
+    } catch {
+      // try the next one
+    }
+  }
+  return null;
+}
+
+/**
+ * Get the status of the straylight-ai container.
+ */
+export async function getContainerStatus(
+  runtime: string
+): Promise<ContainerStatus> {
+  try {
+    const output = execSync(
+      `${runtime} inspect --format "{{.State.Status}}" ${CONTAINER_NAME}`,
+      { stdio: "pipe" }
+    )
+      .toString()
+      .trim()
+      .replace(/^"|"$/g, ""); // strip surrounding quotes if present
+
+    if (output === "running") return "running";
+    return "stopped";
+  } catch {
+    return "not_found";
+  }
+}
+
+/**
+ * Returns true when the container is currently running.
+ */
+export async function isContainerRunning(runtime: string): Promise<boolean> {
+  return (await getContainerStatus(runtime)) === "running";
+}
+
+/**
+ * Build the docker/podman run command string.
+ */
+export function buildRunCommand(runtime: string): string {
+  return [
+    `${runtime} run`,
+    "-d",
+    `--name ${CONTAINER_NAME}`,
+    `-p ${CONTAINER_PORT}:${CONTAINER_PORT}`,
+    `-v ${DATA_DIR}:/data`,
+    "--restart unless-stopped",
+    CONTAINER_IMAGE,
+  ].join(" ");
+}
+
+/**
+ * Build the docker/podman start command string.
+ */
+export function buildStartCommand(runtime: string): string {
+  return `${runtime} start ${CONTAINER_NAME}`;
+}
+
+/**
+ * Build the docker/podman stop command string.
+ */
+export function buildStopCommand(runtime: string): string {
+  return `${runtime} stop ${CONTAINER_NAME}`;
+}
+
+/**
+ * Pull the container image.
+ */
+export function pullImage(runtime: string): void {
+  execSync(`${runtime} pull ${CONTAINER_IMAGE}`, { stdio: "inherit" });
+}

package/src/health.ts

@@ -0,0 +1,55 @@
+/** Response shape from the health endpoint */
+export interface HealthResponse {
+  status: string;
+  version?: string;
+  [key: string]: unknown;
+}
+
+/** Interval between health-check attempts in milliseconds */
+const POLL_INTERVAL_MS = 1_000;
+
+/**
+ * Perform a single health check against the given URL.
+ * Throws if the endpoint is unreachable or returns a non-ok HTTP status.
+ */
+export async function checkHealth(url: string): Promise<HealthResponse> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Health check failed with HTTP ${response.status}`);
+  }
+  return (await response.json()) as HealthResponse;
+}
+
+/**
+ * Poll the health endpoint until it returns a successful response or the
+ * timeout elapses.
+ *
+ * @param url       Full URL of the health endpoint.
+ * @param timeoutMs Maximum time to wait in milliseconds.
+ * @returns The first successful HealthResponse.
+ * @throws  Error when the timeout is reached without a successful response.
+ */
+export async function waitForHealth(
+  url: string,
+  timeoutMs: number
+): Promise<HealthResponse> {
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() < deadline) {
+    try {
+      return await checkHealth(url);
+    } catch {
+      // Not ready yet — wait before retrying
+      await sleep(POLL_INTERVAL_MS);
+    }
+  }
+
+  throw new Error(
+    `Health check timed out after ${timeoutMs}ms. ` +
+      `Is the container running at ${url}?`
+  );
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}