agent-log-viewer 0.11.7 → 1.0.0

package/bin/mcp-server.test.ts

@@ -0,0 +1,264 @@
+import { afterEach, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const sandboxes: string[] = [];
+
+afterEach(() => {
+  for (const sandbox of sandboxes.splice(0)) fs.rmSync(sandbox, { recursive: true, force: true });
+});
+
+function installedPackage(serverSource = `
+  process.stdout.write(JSON.stringify({ bun: process.versions.bun ?? null }) + "\\n");
+  process.stdin.pipe(process.stdout);
+`): { root: string; launcher: string } {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "llv-installed-mcp-"));
+  sandboxes.push(root);
+  fs.mkdirSync(path.join(root, "bin"), { recursive: true });
+  fs.mkdirSync(path.join(root, "dist"), { recursive: true });
+  fs.copyFileSync(path.join(import.meta.dir, "mcp-server.mjs"), path.join(root, "bin", "mcp-server.mjs"));
+  fs.copyFileSync(path.join(import.meta.dir, "server-runtime.mjs"), path.join(root, "bin", "server-runtime.mjs"));
+  fs.writeFileSync(path.join(root, "dist", "mcp-server.mjs"), serverSource, "utf8");
+  return { root, launcher: path.join(root, "bin", "mcp-server.mjs") };
+}
+
+async function launchInstalled(env: Record<string, string>): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  const { root, launcher } = installedPackage();
+  return launchFrom(root, launcher, env, "initialize-handshake\n");
+}
+
+async function launchFrom(
+  root: string,
+  launcher: string,
+  env: Record<string, string>,
+  input: string,
+  runtime: "node" | "bun" = "node",
+): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  const node = Bun.which("node");
+  const bun = Bun.which("bun");
+  if (!node || !bun) throw new Error("Node and Bun are required for the launcher test");
+  const child = Bun.spawn({
+    cmd: [runtime === "bun" ? bun : node, launcher],
+    cwd: root,
+    env: { ...process.env, ...env, LLV_BUN_EXECUTABLE: bun },
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  child.stdin.write(input);
+  child.stdin.end();
+  const [exitCode, stdout, stderr] = await Promise.all([
+    child.exited,
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+  ]);
+  return { exitCode, stdout, stderr };
+}
+
+test("fresh Claude and Codex hosts load the exact MCP runtime named by the promoted release", async () => {
+  const previousRevision = "8".repeat(40);
+  const candidateRevision = "7".repeat(40);
+  const { root, launcher } = installedPackage(`
+    process.stdout.write(JSON.stringify({
+      revision: "${previousRevision}",
+      tools: ["deploy_exact_sha", "get_pipeline"],
+      host: process.env.LLV_TEST_HOST,
+    }) + "\\n");
+    process.stdin.pipe(process.stdout);
+  `);
+  const stateDir = path.join(root, "state");
+  const releaseId = `deploy-${candidateRevision}`;
+  const releaseRoot = path.join(stateDir, "mcp-runtime", "releases", releaseId);
+  const candidateBundle = `
+    process.stdout.write(JSON.stringify({
+      revision: "${candidateRevision}",
+      tools: ["deployment_status", "board_snapshot"],
+      host: process.env.LLV_TEST_HOST,
+    }) + "\\n");
+    process.stdin.pipe(process.stdout);
+  `;
+  fs.mkdirSync(path.join(releaseRoot, "dist"), { recursive: true });
+  fs.writeFileSync(path.join(releaseRoot, "dist", "mcp-server.mjs"), candidateBundle, "utf8");
+  const targetFile = path.join(root, "targets", "viewer-release.json");
+  fs.mkdirSync(path.dirname(targetFile), { recursive: true });
+  fs.writeFileSync(targetFile, JSON.stringify({
+    revision: candidateRevision,
+    image: `viewer:${candidateRevision}`,
+    container: "viewer-candidate",
+    endpoint: "http://127.0.0.1:18001",
+    mcpRuntime: {
+      source: "managed",
+      revision: candidateRevision,
+      releaseId,
+      artifactDigest: createHash("sha256").update(candidateBundle).digest("hex"),
+      stagedAt: "2026-07-23T08:00:00.000Z",
+    },
+  }), "utf8");
+
+  for (const host of ["claude", "codex"]) {
+    const result = await launchFrom(root, launcher, {
+      LLV_TEST_HOST: host,
+      LLV_STATE_DIR: stateDir,
+      LLV_VIEWER_DEPLOY_TARGET: targetFile,
+    }, `${host}-initialize\n`, "bun");
+    expect(result).toMatchObject({ exitCode: 0, stderr: "" });
+    const [runtime, handshake] = result.stdout.trim().split("\n");
+    expect(JSON.parse(runtime!)).toEqual({
+      revision: candidateRevision,
+      tools: ["deployment_status", "board_snapshot"],
+      host,
+    });
+    expect(handshake).toBe(`${host}-initialize`);
+  }
+}, 15_000);
+
+test("a fresh host rejects a managed MCP runtime whose bundle differs from the published digest", async () => {
+  const revision = "7".repeat(40);
+  const { root, launcher } = installedPackage();
+  const stateDir = path.join(root, "state");
+  const releaseId = `deploy-${revision}`;
+  const releaseRoot = path.join(stateDir, "mcp-runtime", "releases", releaseId);
+  fs.mkdirSync(path.join(releaseRoot, "dist"), { recursive: true });
+  fs.writeFileSync(path.join(releaseRoot, "dist", "mcp-server.mjs"), "process.stdout.write('tampered\\n');", "utf8");
+  const targetFile = path.join(stateDir, "viewer-release.json");
+  fs.writeFileSync(targetFile, JSON.stringify({
+    revision,
+    image: `viewer:${revision}`,
+    container: "viewer-candidate",
+    endpoint: "http://127.0.0.1:18001",
+    mcpRuntime: {
+      source: "managed",
+      revision,
+      releaseId,
+      artifactDigest: "a".repeat(64),
+      stagedAt: "2026-07-23T08:00:00.000Z",
+    },
+  }), "utf8");
+
+  const result = await launchFrom(root, launcher, {
+    LLV_STATE_DIR: stateDir,
+    LLV_VIEWER_DEPLOY_TARGET: targetFile,
+  }, "", "bun");
+  expect(result.exitCode).toBe(1);
+  expect(result.stdout).toBe("");
+  expect(result.stderr).toContain("MCP runtime bundle digest does not match the active release");
+});
+
+test("an existing malformed release target fails closed instead of loading the legacy runtime", async () => {
+  const { root, launcher } = installedPackage("process.stdout.write('legacy\\n');");
+  const stateDir = path.join(root, "state");
+  const targetFile = path.join(stateDir, "viewer-release.json");
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(targetFile, "{}\n", "utf8");
+
+  const result = await launchFrom(root, launcher, {
+    LLV_STATE_DIR: stateDir,
+    LLV_VIEWER_DEPLOY_TARGET: targetFile,
+  }, "", "bun");
+  expect(result.exitCode).toBe(1);
+  expect(result.stdout).toBe("");
+  expect(result.stderr).toContain("active Viewer release target is invalid");
+});
+
+test("the installed MCP launcher selects Bun for Bun-only Viewer configuration and preserves stdio", async () => {
+  const configurations: Record<string, string>[] = [
+    { LLV_AGENT_REGISTRY_SQLITE: "read" },
+    { LLV_STRUCTURED_HOSTS: "1" },
+  ];
+  for (const env of configurations) {
+    const result = await launchInstalled(env);
+    expect(result).toMatchObject({ exitCode: 0, stderr: "" });
+    const [runtime, handshake] = result.stdout.trim().split("\n");
+    expect(JSON.parse(runtime!)).toMatchObject({ bun: expect.any(String) });
+    expect(handshake).toBe("initialize-handshake");
+  }
+}, 15_000);
+
+test("the installed MCP launcher forwards termination to its Bun child", async () => {
+  const readyPath = path.join(os.tmpdir(), `llv-mcp-ready-${crypto.randomUUID()}`);
+  const signalPath = path.join(os.tmpdir(), `llv-mcp-signal-${crypto.randomUUID()}`);
+  sandboxes.push(readyPath, signalPath);
+  const { root, launcher } = installedPackage(`
+    const fs = await import("node:fs");
+    fs.writeFileSync(process.env.LLV_TEST_READY, "ready\\n", "utf8");
+    process.once("SIGTERM", () => {
+      fs.writeFileSync(process.env.LLV_TEST_SIGNAL, "SIGTERM\\n", "utf8");
+      process.exit(0);
+    });
+    setInterval(() => {}, 1_000);
+  `);
+  const node = Bun.which("node");
+  const bun = Bun.which("bun");
+  if (!node || !bun) throw new Error("Node and Bun are required for the launcher test");
+  const child = Bun.spawn({
+    cmd: [node, launcher],
+    cwd: root,
+    env: {
+      ...process.env,
+      LLV_STRUCTURED_HOSTS: "1",
+      LLV_BUN_EXECUTABLE: bun,
+      LLV_TEST_READY: readyPath,
+      LLV_TEST_SIGNAL: signalPath,
+    },
+    stdout: "ignore",
+    stderr: "pipe",
+  });
+  const deadline = Date.now() + 5_000;
+  while (!fs.existsSync(readyPath)) {
+    if (Date.now() >= deadline) throw new Error("timed out waiting for the Bun MCP child");
+    await Bun.sleep(5);
+  }
+  child.kill("SIGTERM");
+  await child.exited;
+  expect(fs.readFileSync(signalPath, "utf8")).toBe("SIGTERM\n");
+}, 15_000);
+
+test("the installed MCP launcher forwards escalating signals until its Bun child exits", async () => {
+  const readyPath = path.join(os.tmpdir(), `llv-mcp-ready-${crypto.randomUUID()}`);
+  const signalPath = path.join(os.tmpdir(), `llv-mcp-signals-${crypto.randomUUID()}`);
+  sandboxes.push(readyPath, signalPath);
+  const { root, launcher } = installedPackage(`
+    const fs = await import("node:fs");
+    fs.writeFileSync(process.env.LLV_TEST_READY, "ready\\n", "utf8");
+    process.on("SIGINT", () => fs.appendFileSync(process.env.LLV_TEST_SIGNAL, "SIGINT\\n", "utf8"));
+    process.on("SIGTERM", () => {
+      fs.appendFileSync(process.env.LLV_TEST_SIGNAL, "SIGTERM\\n", "utf8");
+      process.exit(0);
+    });
+    setTimeout(() => process.exit(7), 1_500);
+    setInterval(() => {}, 1_000);
+  `);
+  const node = Bun.which("node");
+  const bun = Bun.which("bun");
+  if (!node || !bun) throw new Error("Node and Bun are required for the launcher test");
+  const child = Bun.spawn({
+    cmd: [node, launcher],
+    cwd: root,
+    env: {
+      ...process.env,
+      LLV_STRUCTURED_HOSTS: "1",
+      LLV_BUN_EXECUTABLE: bun,
+      LLV_TEST_READY: readyPath,
+      LLV_TEST_SIGNAL: signalPath,
+    },
+    stdout: "ignore",
+    stderr: "pipe",
+  });
+  const deadline = Date.now() + 5_000;
+  while (!fs.existsSync(readyPath)) {
+    if (Date.now() >= deadline) throw new Error("timed out waiting for the Bun MCP child");
+    await Bun.sleep(5);
+  }
+  child.kill("SIGINT");
+  while (!fs.existsSync(signalPath) || !fs.readFileSync(signalPath, "utf8").includes("SIGINT\n")) {
+    if (Date.now() >= deadline) throw new Error("timed out waiting for SIGINT forwarding");
+    await Bun.sleep(5);
+  }
+  child.kill("SIGTERM");
+  const exitCode = await child.exited;
+  const stderr = await new Response(child.stderr).text();
+  expect({ exitCode, stderr }).toEqual({ exitCode: 0, stderr: "" });
+  expect(fs.readFileSync(signalPath, "utf8")).toBe("SIGINT\nSIGTERM\n");
+}, 15_000);

package/bin/server-runtime.mjs

@@ -0,0 +1,57 @@
+export const WAKATIME_CREDENTIAL_ENV = "WAKATIME_API_KEY";
+
+/** @param {Record<string, string | undefined>} environment */
+export function discardWakatimeEnvironmentCredential(environment = process.env) {
+  delete environment[WAKATIME_CREDENTIAL_ENV];
+}
+
+/**
+ * @param {Readonly<Record<string, string | undefined>>} base
+ * @returns {Record<string, string | undefined>}
+ */
+export function withoutWakatimeCredential(base) {
+  const env = { NODE_ENV: base.NODE_ENV };
+  for (const key of Object.keys(base)) {
+    if (key === WAKATIME_CREDENTIAL_ENV) continue;
+    env[key] = base[key];
+  }
+  return env;
+}
+
+/**
+ * @param {Record<string, unknown> & { env?: Readonly<Record<string, string | undefined>> }} options
+ */
+export function viewerChildProcessOptions(options = {}) {
+  return {
+    ...options,
+    env: withoutWakatimeCredential(options.env ?? process.env),
+  };
+}
+
+/**
+ * Mirror of `structuredHostsEnabled` (and its rollback normalisation) from
+ * `src/lib/runtime/flags.ts`. `bin/` is plain JS outside the TS build and
+ * cannot import that module, so the predicate is duplicated — never diverged:
+ * `bin/server-runtime.test.ts` pins the two to one truth table. Structured
+ * hosting is on unless explicitly rolled back, and it genuinely requires Bun
+ * (the journal runs on `bun:sqlite`; macOS process ownership needs the kernel
+ * start token), so the launcher must select Bun on the same answer.
+ *
+ * @param {Readonly<Record<string, string | undefined>>} [env]
+ */
+export function structuredHostsEnabled(env = process.env) {
+  const raw = env.LLV_STRUCTURED_HOSTS;
+  if (raw === undefined) return true;
+  const normalized = raw.trim().replace(/^(["'])([\s\S]*)\1$/, "$2").trim().toLowerCase();
+  return !(normalized === "0" || normalized === "false" || normalized === "off" || normalized === "no");
+}
+
+export function viewerServerBunRuntime(options = {}) {
+  const env = options.env ?? process.env;
+  const versions = options.versions ?? process.versions;
+  const execPath = options.execPath ?? process.execPath;
+  const sqliteMode = env.LLV_AGENT_REGISTRY_SQLITE ?? "off";
+  const requiresBun = sqliteMode !== "off" || structuredHostsEnabled(env);
+  if (!requiresBun) return null;
+  return versions.bun ? execPath : (env.LLV_BUN_EXECUTABLE || "bun");
+}

package/bin/server-runtime.test.ts

@@ -0,0 +1,122 @@
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { expect, test } from "bun:test";
+
+import { structuredHostsEnabled as structuredHostsEnabledInApp } from "@/lib/runtime/flags";
+
+import {
+  structuredHostsEnabled as structuredHostsEnabledInLauncher,
+  viewerServerBunRuntime,
+  viewerChildProcessOptions,
+  WAKATIME_CREDENTIAL_ENV,
+  withoutWakatimeCredential,
+} from "./server-runtime.mjs";
+
+test("structured hosts select Bun for a CLI process launched by Node", () => {
+  expect(viewerServerBunRuntime({
+    env: { LLV_STRUCTURED_HOSTS: "1" },
+    versions: { node: "20.9.0" },
+    execPath: "/usr/bin/node",
+  })).toBe("bun");
+  expect(viewerServerBunRuntime({
+    env: { LLV_STRUCTURED_HOSTS: "1", LLV_BUN_EXECUTABLE: "/opt/bun/bin/bun" },
+    versions: { node: "20.9.0" },
+    execPath: "/usr/bin/node",
+  })).toBe("/opt/bun/bin/bun");
+});
+
+test("the packaged helper makes the same structured-runtime choice under Node", () => {
+  const helper = path.join(path.dirname(fileURLToPath(import.meta.url)), "server-runtime.mjs");
+  const probe = Bun.spawnSync([
+    "node",
+    "--input-type=module",
+    "--eval",
+    `import { viewerServerBunRuntime } from ${JSON.stringify(pathToFileURL(helper).href)}; process.stdout.write(String(viewerServerBunRuntime()));`,
+  ], {
+    env: { ...process.env, LLV_STRUCTURED_HOSTS: "1", LLV_BUN_EXECUTABLE: "/verified/bun" },
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  expect(probe.exitCode).toBe(0);
+  expect(probe.stdout.toString()).toBe("/verified/bun");
+});
+
+/* Structured hosting is on by default, and it genuinely needs Bun (`bun:sqlite`
+   journal, kernel start tokens on macOS). A launcher that still keyed on a
+   literal "1" would run the default configuration under Node — where startup
+   adoption throws the Darwin runtime requirement and the release controllers
+   never start. */
+test("an unset structured-hosts variable still selects Bun for the launcher", () => {
+  expect(viewerServerBunRuntime({
+    env: {},
+    versions: { node: "20.9.0" },
+    execPath: "/usr/bin/node",
+  })).toBe("bun");
+});
+
+/* `bin/` is plain JS outside the TS build, so its predicate is a copy. This
+   pins the copy to the original: one truth table, both readers. */
+test.each([
+  [undefined],
+  [""],
+  ["1"],
+  ["0"],
+  [" 0 "],
+  ["\"0\""],
+  ["'0'"],
+  ["false"],
+  ["OFF"],
+  ["no"],
+  ["yes"],
+] as const)("the launcher mirror and the app definition agree on %p", (value) => {
+  const env = value === undefined ? {} : { LLV_STRUCTURED_HOSTS: value };
+  expect(structuredHostsEnabledInLauncher(env)).toBe(structuredHostsEnabledInApp(env));
+  // …and the launcher's Bun selection follows that one answer.
+  expect(viewerServerBunRuntime({ env, versions: { node: "20.9.0" }, execPath: "/usr/bin/node" }) !== null)
+    .toBe(structuredHostsEnabledInApp(env));
+});
+
+test("legacy Node mode stays available when Bun-only features are disabled", () => {
+  expect(viewerServerBunRuntime({
+    env: { LLV_AGENT_REGISTRY_SQLITE: "off", LLV_STRUCTURED_HOSTS: "0" },
+    versions: { node: "20.9.0" },
+    execPath: "/usr/bin/node",
+  })).toBeNull();
+});
+
+test("Viewer child processes receive no ambient WakaTime key material", () => {
+  const placeholder = ["child", "fixture", "value"].join("-");
+  const env = withoutWakatimeCredential({
+    PATH: process.env.PATH,
+    KEEP_ME: "kept",
+    [WAKATIME_CREDENTIAL_ENV]: placeholder,
+  });
+  const probe = Bun.spawnSync([
+    process.execPath,
+    "--eval",
+    "process.stdout.write(JSON.stringify({ keep: process.env.KEEP_ME, key: process.env.WAKATIME_API_KEY ?? null }))",
+  ], { env, stdout: "pipe", stderr: "pipe" });
+
+  expect(probe.exitCode).toBe(0);
+  expect(JSON.parse(probe.stdout.toString())).toEqual({ keep: "kept", key: null });
+  expect(JSON.stringify(env)).not.toContain(placeholder);
+});
+
+test("published launcher child options capture no ambient WakaTime key material", () => {
+  const placeholder = ["launcher", "fixture", "value"].join("-");
+  const options = viewerChildProcessOptions({
+    cwd: "/viewer",
+    env: {
+      PATH: process.env.PATH,
+      KEEP_ME: "kept",
+      [WAKATIME_CREDENTIAL_ENV]: placeholder,
+    },
+    stdio: "ignore",
+  });
+
+  expect(options.env.KEEP_ME).toBe("kept");
+  expect(options.env[WAKATIME_CREDENTIAL_ENV]).toBeUndefined();
+  expect(JSON.stringify(options)).not.toContain(placeholder);
+});

package/bin/tailscale-credential-isolation.test.ts

@@ -0,0 +1,56 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { once } from "node:events";
+
+import { discardWakatimeEnvironmentCredential, WAKATIME_CREDENTIAL_ENV } from "./server-runtime.mjs";
+import { readStatus, serve } from "./tailscale.mjs";
+
+afterEach(() => {
+  discardWakatimeEnvironmentCredential();
+});
+
+function tailscaleProbe(): { directory: string; executable: string } {
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), "llv-tailscale-env-"));
+  const executable = path.join(directory, "tailscale-probe");
+  fs.writeFileSync(executable, `#!/bin/sh
+if [ -n "\${WAKATIME_API_KEY+x}" ]; then
+  echo "ambient WakaTime credential reached Tailscale" >&2
+  exit 41
+fi
+if [ "$1" = "status" ]; then
+  printf '{"BackendState":"Running","Self":{"DNSName":"viewer.tail.test."}}'
+fi
+`, { mode: 0o700 });
+  return { directory, executable };
+}
+
+describe("published launcher auxiliary child credential isolation", () => {
+  test("Tailscale status receives no ambient WakaTime credential", async () => {
+    const probe = tailscaleProbe();
+    discardWakatimeEnvironmentCredential();
+    process.env[WAKATIME_CREDENTIAL_ENV] = ["tailscale", "status", "fixture"].join("-");
+    try {
+      await expect(readStatus(probe.executable)).resolves.toEqual({
+        backendState: "Running",
+        dnsName: "viewer.tail.test",
+      });
+    } finally {
+      fs.rmSync(probe.directory, { recursive: true, force: true });
+    }
+  });
+
+  test("Tailscale serve receives no ambient WakaTime credential", async () => {
+    const probe = tailscaleProbe();
+    discardWakatimeEnvironmentCredential();
+    process.env[WAKATIME_CREDENTIAL_ENV] = ["tailscale", "serve", "fixture"].join("-");
+    try {
+      const handle = serve(probe.executable, 8898);
+      const [code] = await once(handle.child, "exit");
+      expect(code).toBe(0);
+    } finally {
+      fs.rmSync(probe.directory, { recursive: true, force: true });
+    }
+  });
+});

package/bin/tailscale.mjs

@@ -5,6 +5,8 @@ import { homedir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
 
+import { viewerChildProcessOptions } from "./server-runtime.mjs";
+
 /* Dependency-free localization, mirroring bin/cli.mjs: English by default,
    Ukrainian when LLV_LANG=uk or the locale is a uk_* / uk.* variant. */
 function detectLang() {
@@ -162,9 +164,9 @@ export async function detectTailscale() {
 
 function runJson(command, args) {
   return new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
+    const child = spawn(command, args, viewerChildProcessOptions({
       stdio: ["ignore", "pipe", "pipe"],
-    });
+    }));
 
     let stdout = "";
     let stderr = "";
@@ -216,9 +218,9 @@ export async function readStatus(tailscalePath) {
 }
 
 export function serve(tailscalePath, port) {
-  const child = spawn(tailscalePath, ["serve", String(port)], {
+  const child = spawn(tailscalePath, ["serve", String(port)], viewerChildProcessOptions({
     stdio: ["ignore", "ignore", "pipe"],
-  });
+  }));
 
   const state = {
     stopping: false,