@openparachute/hub 0.3.0-rc.1

package/src/__tests__/port-assign.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { assignPort, assignServicePort } from "../port-assign.ts";
+import { CANONICAL_PORT_MAX, CANONICAL_PORT_MIN } from "../service-spec.ts";
+
+function makeTempDir(): { dir: string; cleanup: () => void } {
+  const dir = mkdtempSync(join(tmpdir(), "pcli-port-assign-"));
+  return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+describe("assignPort (pure)", () => {
+  test("returns the canonical slot when free", () => {
+    const result = assignPort(1940, []);
+    expect(result.port).toBe(1940);
+    expect(result.source).toBe("canonical");
+    expect(result.warning).toBeUndefined();
+  });
+
+  test("returns canonical even when other unrelated ports are taken", () => {
+    const result = assignPort(1940, [1939, 1942, 1943, 5173]);
+    expect(result.port).toBe(1940);
+    expect(result.source).toBe("canonical");
+  });
+
+  test("walks the unassigned reservation range when canonical is occupied", () => {
+    // 1940 is taken; canonical reserved range starts at 1944 → first hit.
+    const result = assignPort(1940, [1940]);
+    expect(result.port).toBe(1944);
+    expect(result.source).toBe("fallback-in-range");
+    expect(result.warning).toMatch(/canonical port 1940 is in use/);
+    expect(result.warning).toMatch(/1944/);
+  });
+
+  test("skips reservations that are also occupied", () => {
+    // Canonical 1940 + the first three reserved slots are all in use.
+    const result = assignPort(1940, [1940, 1944, 1945, 1946]);
+    expect(result.port).toBe(1947);
+    expect(result.source).toBe("fallback-in-range");
+  });
+
+  test("falls outside the range with a warning when reservations are exhausted", () => {
+    const occupied = [];
+    for (let p = CANONICAL_PORT_MIN; p <= CANONICAL_PORT_MAX; p++) occupied.push(p);
+    const result = assignPort(1940, occupied);
+    expect(result.port).toBe(CANONICAL_PORT_MAX + 1);
+    expect(result.source).toBe("fallback-out-of-range");
+    expect(result.warning).toMatch(/canonical range/);
+    expect(result.warning).toMatch(/1950/);
+    expect(result.warning).toMatch(/may conflict/);
+  });
+
+  test("walks past out-of-range collisions too", () => {
+    const occupied = [];
+    for (let p = CANONICAL_PORT_MIN; p <= CANONICAL_PORT_MAX + 2; p++) occupied.push(p);
+    const result = assignPort(1940, occupied);
+    expect(result.port).toBe(CANONICAL_PORT_MAX + 3);
+    expect(result.source).toBe("fallback-out-of-range");
+  });
+
+  test("third-party (no canonical slot) jumps straight to the reservation range", () => {
+    const result = assignPort(undefined, []);
+    expect(result.port).toBe(1944);
+    expect(result.source).toBe("fallback-in-range");
+    expect(result.warning).toMatch(/no canonical slot/);
+    expect(result.warning).toMatch(/1944/);
+  });
+
+  test("third-party with reservations occupied walks further in the range", () => {
+    const result = assignPort(undefined, [1944, 1945]);
+    expect(result.port).toBe(1946);
+    expect(result.source).toBe("fallback-in-range");
+  });
+});
+
+describe("assignServicePort (.env round-trip)", () => {
+  test("preserves an existing PORT in .env (idempotent re-install)", () => {
+    const { dir, cleanup } = makeTempDir();
+    try {
+      const envPath = join(dir, ".env");
+      writeFileSync(envPath, "PORT=1944\nOTHER=keepme\n");
+      const result = assignServicePort({
+        envPath,
+        canonical: 1940,
+        // Even though canonical is free, the existing .env wins.
+        occupied: [],
+      });
+      expect(result.port).toBe(1944);
+      expect(result.source).toBe("preserved");
+      expect(result.written).toBe(false);
+      // File untouched — no rewrite means OTHER stays as-is.
+      const text = readFileSync(envPath, "utf8");
+      expect(text).toContain("PORT=1944");
+      expect(text).toContain("OTHER=keepme");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("writes PORT into a fresh .env when canonical is free", () => {
+    const { dir, cleanup } = makeTempDir();
+    try {
+      const envPath = join(dir, "subdir", ".env");
+      const result = assignServicePort({
+        envPath,
+        canonical: 1940,
+        occupied: [],
+      });
+      expect(result.port).toBe(1940);
+      expect(result.source).toBe("canonical");
+      expect(result.written).toBe(true);
+      expect(result.warning).toBeUndefined();
+      expect(existsSync(envPath)).toBe(true);
+      expect(readFileSync(envPath, "utf8")).toContain("PORT=1940");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("writes a fallback PORT and surfaces the warning when canonical is occupied", () => {
+    const { dir, cleanup } = makeTempDir();
+    try {
+      const envPath = join(dir, ".env");
+      const result = assignServicePort({
+        envPath,
+        canonical: 1940,
+        occupied: [1940],
+      });
+      expect(result.port).toBe(1944);
+      expect(result.source).toBe("fallback-in-range");
+      expect(result.written).toBe(true);
+      expect(result.warning).toMatch(/canonical port 1940 is in use/);
+      expect(readFileSync(envPath, "utf8")).toContain("PORT=1944");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("ignores a non-numeric PORT and assigns a fresh one", () => {
+    const { dir, cleanup } = makeTempDir();
+    try {
+      const envPath = join(dir, ".env");
+      writeFileSync(envPath, "PORT=garbage\n");
+      const result = assignServicePort({
+        envPath,
+        canonical: 1940,
+        occupied: [],
+      });
+      expect(result.port).toBe(1940);
+      expect(result.written).toBe(true);
+      // The garbage value got upserted to a real number.
+      expect(readFileSync(envPath, "utf8")).toContain("PORT=1940");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("preserves surrounding lines on rewrite", () => {
+    const { dir, cleanup } = makeTempDir();
+    try {
+      const envPath = join(dir, ".env");
+      writeFileSync(envPath, "FOO=bar\nBAZ=qux\n");
+      const result = assignServicePort({
+        envPath,
+        canonical: 1940,
+        occupied: [],
+      });
+      expect(result.written).toBe(true);
+      const text = readFileSync(envPath, "utf8");
+      expect(text).toContain("FOO=bar");
+      expect(text).toContain("BAZ=qux");
+      expect(text).toContain("PORT=1940");
+    } finally {
+      cleanup();
+    }
+  });
+});

package/src/__tests__/process-state.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import {
+  clearPid,
+  defaultAlive,
+  ensureLogPath,
+  formatUptime,
+  logPath,
+  pidPath,
+  processState,
+  readPid,
+  writePid,
+} from "../process-state.ts";
+
+function makeTempConfig(): { dir: string; cleanup: () => void } {
+  const dir = mkdtempSync(join(tmpdir(), "pcli-proc-"));
+  return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+describe("process-state paths", () => {
+  test("pidPath / logPath land under <configDir>/<svc>/{run,logs}", () => {
+    expect(pidPath("vault", "/cfg")).toBe("/cfg/vault/run/vault.pid");
+    expect(logPath("notes", "/cfg")).toBe("/cfg/notes/logs/notes.log");
+  });
+});
+
+describe("writePid / readPid / clearPid", () => {
+  test("round-trips through the filesystem", () => {
+    const { dir, cleanup } = makeTempConfig();
+    try {
+      expect(readPid("vault", dir)).toBeUndefined();
+      writePid("vault", 12345, dir);
+      expect(readPid("vault", dir)).toBe(12345);
+      clearPid("vault", dir);
+      expect(readPid("vault", dir)).toBeUndefined();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("readPid ignores garbage pid files", () => {
+    const { dir, cleanup } = makeTempConfig();
+    try {
+      const p = pidPath("vault", dir);
+      mkdirSync(dirname(p), { recursive: true });
+      writeFileSync(p, "not-a-number\n");
+      expect(readPid("vault", dir)).toBeUndefined();
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("processState", () => {
+  test("no pid file → unknown (externally-managed is possible)", () => {
+    const { dir, cleanup } = makeTempConfig();
+    try {
+      expect(processState("vault", dir).status).toBe("unknown");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("pid file + alive pid → running with pid + startedAt", () => {
+    const { dir, cleanup } = makeTempConfig();
+    try {
+      writePid("vault", 4242, dir);
+      const state = processState("vault", dir, () => true);
+      expect(state.status).toBe("running");
+      expect(state.pid).toBe(4242);
+      expect(state.startedAt).toBeInstanceOf(Date);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("pid file + dead pid → stopped (known-dead, not unknown)", () => {
+    const { dir, cleanup } = makeTempConfig();
+    try {
+      writePid("vault", 4242, dir);
+      const state = processState("vault", dir, () => false);
+      expect(state.status).toBe("stopped");
+      expect(state.pid).toBe(4242);
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("defaultAlive", () => {
+  test("current process is alive", () => {
+    expect(defaultAlive(process.pid)).toBe(true);
+  });
+
+  test("absurd pid is not alive", () => {
+    // PIDs above 2^22 don't exist on mainstream OSes.
+    expect(defaultAlive(99_999_999)).toBe(false);
+  });
+});
+
+describe("formatUptime", () => {
+  test("sub-minute → seconds", () => {
+    const now = new Date("2026-04-19T12:00:45Z");
+    const start = new Date("2026-04-19T12:00:00Z");
+    expect(formatUptime(start, now)).toBe("45s");
+  });
+
+  test("sub-hour → minutes", () => {
+    const now = new Date("2026-04-19T12:13:00Z");
+    const start = new Date("2026-04-19T12:00:00Z");
+    expect(formatUptime(start, now)).toBe("13m");
+  });
+
+  test("sub-day → h+m", () => {
+    const now = new Date("2026-04-19T14:13:00Z");
+    const start = new Date("2026-04-19T12:00:00Z");
+    expect(formatUptime(start, now)).toBe("2h 13m");
+  });
+
+  test("multi-day → d+h", () => {
+    const now = new Date("2026-04-23T18:00:00Z");
+    const start = new Date("2026-04-19T12:00:00Z");
+    expect(formatUptime(start, now)).toBe("4d 6h");
+  });
+});
+
+describe("ensureLogPath", () => {
+  test("creates logs dir and returns the log-file path", () => {
+    const { dir, cleanup } = makeTempConfig();
+    try {
+      const p = ensureLogPath("vault", dir);
+      expect(p).toBe(logPath("vault", dir));
+      expect(existsSync(join(dir, "vault", "logs"))).toBe(true);
+    } finally {
+      cleanup();
+    }
+  });
+});

package/src/__tests__/scribe-config.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  SCRIBE_DEFAULT_PROVIDER,
+  SCRIBE_PROVIDERS,
+  apiKeyEnvFor,
+  isKnownScribeProvider,
+  readScribeProviderState,
+  scribeConfigPath,
+  scribeEnvPath,
+  writeScribeApiKey,
+  writeScribeProvider,
+} from "../scribe-config.ts";
+
+function makeHarness(): { dir: string; cleanup: () => void } {
+  const dir = mkdtempSync(join(tmpdir(), "pcli-scribecfg-"));
+  return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+describe("provider catalog", () => {
+  test("default provider is in the catalog", () => {
+    expect(SCRIBE_PROVIDERS.some((p) => p.key === SCRIBE_DEFAULT_PROVIDER)).toBe(true);
+  });
+
+  test("isKnownScribeProvider matches every catalog key", () => {
+    for (const p of SCRIBE_PROVIDERS) {
+      expect(isKnownScribeProvider(p.key)).toBe(true);
+    }
+    expect(isKnownScribeProvider("not-a-provider")).toBe(false);
+    expect(isKnownScribeProvider("cloudflare")).toBe(false);
+  });
+
+  test("apiKeyEnvFor maps cloud providers to env keys, locals to undefined", () => {
+    expect(apiKeyEnvFor("groq")).toBe("GROQ_API_KEY");
+    expect(apiKeyEnvFor("openai")).toBe("OPENAI_API_KEY");
+    expect(apiKeyEnvFor("parakeet-mlx")).toBeUndefined();
+    expect(apiKeyEnvFor("onnx-asr")).toBeUndefined();
+    expect(apiKeyEnvFor("whisper")).toBeUndefined();
+  });
+});
+
+describe("readScribeProviderState", () => {
+  test("missing file: configExists false, no provider", () => {
+    const h = makeHarness();
+    try {
+      const state = readScribeProviderState(h.dir);
+      expect(state.configExists).toBe(false);
+      expect(state.provider).toBeUndefined();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("file exists without transcribe block: configExists true, no provider", () => {
+    const h = makeHarness();
+    try {
+      mkdirSync(join(h.dir, "scribe"), { recursive: true });
+      writeFileSync(scribeConfigPath(h.dir), JSON.stringify({ auth: { required_token: "x" } }));
+      const state = readScribeProviderState(h.dir);
+      expect(state.configExists).toBe(true);
+      expect(state.provider).toBeUndefined();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("transcribe.provider set: returns it", () => {
+    const h = makeHarness();
+    try {
+      mkdirSync(join(h.dir, "scribe"), { recursive: true });
+      writeFileSync(
+        scribeConfigPath(h.dir),
+        JSON.stringify({ transcribe: { provider: "groq" }, auth: { required_token: "x" } }),
+      );
+      const state = readScribeProviderState(h.dir);
+      expect(state.provider).toBe("groq");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("malformed JSON: configExists true, provider undefined (no throw)", () => {
+    const h = makeHarness();
+    try {
+      mkdirSync(join(h.dir, "scribe"), { recursive: true });
+      writeFileSync(scribeConfigPath(h.dir), "{ not valid json");
+      const state = readScribeProviderState(h.dir);
+      expect(state.configExists).toBe(true);
+      expect(state.provider).toBeUndefined();
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("writeScribeProvider", () => {
+  test("creates new config with transcribe.provider when none exists", () => {
+    const h = makeHarness();
+    try {
+      writeScribeProvider(h.dir, "groq");
+      const parsed = JSON.parse(readFileSync(scribeConfigPath(h.dir), "utf8"));
+      expect(parsed).toEqual({ transcribe: { provider: "groq" } });
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("preserves auth.required_token written by auto-wire", () => {
+    const h = makeHarness();
+    try {
+      mkdirSync(join(h.dir, "scribe"), { recursive: true });
+      writeFileSync(
+        scribeConfigPath(h.dir),
+        JSON.stringify({ auth: { required_token: "secret-token" } }),
+      );
+      writeScribeProvider(h.dir, "openai");
+      const parsed = JSON.parse(readFileSync(scribeConfigPath(h.dir), "utf8"));
+      expect(parsed.auth).toEqual({ required_token: "secret-token" });
+      expect(parsed.transcribe).toEqual({ provider: "openai" });
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("merges into an existing transcribe block", () => {
+    const h = makeHarness();
+    try {
+      mkdirSync(join(h.dir, "scribe"), { recursive: true });
+      writeFileSync(
+        scribeConfigPath(h.dir),
+        JSON.stringify({ transcribe: { provider: "parakeet-mlx", language: "en" } }),
+      );
+      writeScribeProvider(h.dir, "groq");
+      const parsed = JSON.parse(readFileSync(scribeConfigPath(h.dir), "utf8"));
+      expect(parsed.transcribe).toEqual({ provider: "groq", language: "en" });
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("overwrites malformed config (does not throw)", () => {
+    const h = makeHarness();
+    try {
+      mkdirSync(join(h.dir, "scribe"), { recursive: true });
+      writeFileSync(scribeConfigPath(h.dir), "{ broken");
+      writeScribeProvider(h.dir, "whisper");
+      const parsed = JSON.parse(readFileSync(scribeConfigPath(h.dir), "utf8"));
+      expect(parsed).toEqual({ transcribe: { provider: "whisper" } });
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("writeScribeApiKey", () => {
+  test("creates scribe/.env with the key when missing", () => {
+    const h = makeHarness();
+    try {
+      writeScribeApiKey(h.dir, "GROQ_API_KEY", "gsk_test_123");
+      expect(readFileSync(scribeEnvPath(h.dir), "utf8")).toBe("GROQ_API_KEY=gsk_test_123\n");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("upserts in place when the key is already present", () => {
+    const h = makeHarness();
+    try {
+      mkdirSync(join(h.dir, "scribe"), { recursive: true });
+      writeFileSync(scribeEnvPath(h.dir), "OTHER=keep\nGROQ_API_KEY=old_value\nLAST=tail\n");
+      writeScribeApiKey(h.dir, "GROQ_API_KEY", "new_value");
+      const text = readFileSync(scribeEnvPath(h.dir), "utf8");
+      expect(text).toBe("OTHER=keep\nGROQ_API_KEY=new_value\nLAST=tail\n");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("preserves unrelated lines on first-time write", () => {
+    const h = makeHarness();
+    try {
+      mkdirSync(join(h.dir, "scribe"), { recursive: true });
+      writeFileSync(scribeEnvPath(h.dir), "EXISTING=value\n");
+      writeScribeApiKey(h.dir, "OPENAI_API_KEY", "sk-test");
+      const text = readFileSync(scribeEnvPath(h.dir), "utf8");
+      expect(text).toBe("EXISTING=value\nOPENAI_API_KEY=sk-test\n");
+    } finally {
+      h.cleanup();
+    }
+  });
+});