Improve CLI startup failure log surfacing

Author: root

packages/cli/src/bin.test.ts

@@ -212,6 +212,66 @@ describe("main", () => {
     }
   });
 
+  it("prints only the recent tail for logs command", async () => {
+    const logDir = mkdtempSync(join(tmpdir(), "cs-cli-logs-tail-"));
+    const outFile = join(logDir, "server.out.log");
+    const errFile = join(logDir, "server.err.log");
+    const outLines = Array.from({ length: 45 }, (_, index) => `out line ${index + 1}`);
+    const errLines = ["err line 1", "err line 2"];
+    writeFileSync(outFile, `${outLines.join("\n")}\n`, "utf-8");
+    writeFileSync(errFile, `${errLines.join("\n")}\n`, "utf-8");
+    getServerStatus.mockResolvedValue({
+      status: "running",
+      pid: 424242,
+      host: "127.0.0.1",
+      port: 4187,
+      restartCount: 2,
+      outFile,
+      errFile,
+      startedAt: 1000,
+    });
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      await main(["logs"]);
+      expect(logSpy).toHaveBeenCalledWith(
+        `${outLines.slice(-40).join("\n")}\n${errLines.join("\n")}`
+      );
+    } finally {
+      if (existsSync(logDir)) {
+        rmSync(logDir, { recursive: true, force: true });
+      }
+    }
+  });
+
+  it("prints only the requested error log tail for logs command", async () => {
+    const logDir = mkdtempSync(join(tmpdir(), "cs-cli-logs-errors-"));
+    const outFile = join(logDir, "server.out.log");
+    const errFile = join(logDir, "server.err.log");
+    writeFileSync(outFile, "out line 1\nout line 2\n", "utf-8");
+    writeFileSync(errFile, "err line 1\nerr line 2\n", "utf-8");
+    getServerStatus.mockResolvedValue({
+      status: "running",
+      pid: 424242,
+      host: "127.0.0.1",
+      port: 4187,
+      restartCount: 2,
+      outFile,
+      errFile,
+      startedAt: 1000,
+    });
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      await main(["logs", "--errors-only", "--tail", "1"]);
+      expect(logSpy).toHaveBeenCalledWith("err line 2");
+    } finally {
+      if (existsSync(logDir)) {
+        rmSync(logDir, { recursive: true, force: true });
+      }
+    }
+  });
+
   it("prints stop output for stop command", async () => {
     stopRunningServer.mockResolvedValue(true);
     const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
@@ -383,6 +443,18 @@ describe("main", () => {
     expect(openBrowser).toHaveBeenCalledWith("http://127.0.0.1:4190");
   });
 
+  it("rethrows background startup failures for open and does not open the browser", async () => {
+    const startupError = new Error(
+      "Coder Studio failed to start in background: the managed process entered the errored state.\n\nRecent error log excerpt (/tmp/server.err.log):\nError: listen EADDRINUSE: address already in use 127.0.0.1:4187\n\nRun `coder-studio logs` for details or `coder-studio serve --foreground` for interactive debugging."
+    );
+    startManagedServer.mockRejectedValueOnce(startupError);
+
+    await expect(main(["open"])).rejects.toThrow(
+      "Error: listen EADDRINUSE: address already in use 127.0.0.1:4187"
+    );
+    expect(openBrowser).not.toHaveBeenCalled();
+  });
+
   it("does not restart in non-interactive mode and prints a clear message", async () => {
     getServerStatus.mockResolvedValue({
       status: "running",
@@ -512,6 +584,20 @@ describe("parseArgs", () => {
     });
   });
 
+  it("parses logs command with tail count", () => {
+    expect(parseArgs(["logs", "--tail", "100"])).toEqual({
+      command: "logs",
+      tail: 100,
+    });
+  });
+
+  it("parses logs command with errors-only flag", () => {
+    expect(parseArgs(["logs", "--errors-only"])).toEqual({
+      command: "logs",
+      errorsOnly: true,
+    });
+  });
+
   it("parses open command", () => {
     expect(parseArgs(["open"])).toEqual({
       command: "open",
@@ -633,6 +719,26 @@ describe("parseArgs", () => {
     expect(() => parseArgs(["logs", "--port", "4186"])).toThrow("Unknown option: --port");
   });
 
+  it("rejects logs tail with a non-numeric value", () => {
+    expect(() => parseArgs(["logs", "--tail", "nope"])).toThrow("Invalid tail number");
+  });
+
+  it("rejects logs tail with zero", () => {
+    expect(() => parseArgs(["logs", "--tail", "0"])).toThrow("Invalid tail number");
+  });
+
+  it("rejects logs tail with a negative value", () => {
+    expect(() => parseArgs(["logs", "--tail", "-1"])).toThrow("Invalid tail number");
+  });
+
+  it("rejects logs tail with a decimal value", () => {
+    expect(() => parseArgs(["logs", "--tail", "1.5"])).toThrow("Invalid tail number");
+  });
+
+  it("rejects logs tail with trailing garbage", () => {
+    expect(() => parseArgs(["logs", "--tail", "10junk"])).toThrow("Invalid tail number");
+  });
+
   it("rejects stop-time data-dir overrides", () => {
     expect(() => parseArgs(["stop", "--data-dir", "/tmp/cs-data"])).toThrow(
       "Unknown option: --data-dir"

packages/cli/src/bin.ts

@@ -4,6 +4,7 @@ import { fileURLToPath } from "url";
 import { clearAuthBlockByIp, listAuthBlocks } from "./auth-control.js";
 import { openBrowser } from "./browser.js";
 import { type CliConfig, readCliConfig, writeCliConfig } from "./config-store.js";
+import { readLogExcerpt } from "./log-excerpt.js";
 import { assertSupportedNodeVersion } from "./node-version.js";
 import { parseArgs } from "./parse-args.js";
 import { startManagedServer } from "./pm2-control.js";
@@ -13,6 +14,7 @@ import { startServer } from "./server-runner.js";
 import { getBrowserUrl, getListenIp, getListenUrl } from "./server-url.js";
 
 const MANAGED_SERVER_WAIT_MS = 5000;
+const DEFAULT_LOG_TAIL_LINES = 40;
 
 function formatConfig(config: CliConfig | null): string {
   return JSON.stringify(config ?? {}, null, 2);
@@ -38,15 +40,18 @@ function formatStatus(status: ServerStatus): string {
   ].join("\n");
 }
 
-function showLogs(status: ServerStatus): void {
-  const contents = [status.outFile, status.errFile]
+function showLogs(
+  status: ServerStatus,
+  {
+    tail = DEFAULT_LOG_TAIL_LINES,
+    errorsOnly = false,
+  }: { tail?: number; errorsOnly?: boolean } = {}
+): void {
+  const paths = errorsOnly ? [status.errFile] : [status.outFile, status.errFile];
+  const contents = paths
     .filter((path, index, paths) => paths.indexOf(path) === index)
     .flatMap((path) => {
-      if (!existsSync(path)) {
-        return [];
-      }
-
-      const content = readFileSync(path, "utf-8").trim();
+      const content = readLogExcerpt(path, { maxLines: tail, maxChars: null });
       return content ? [content] : [];
     });
 
@@ -303,7 +308,7 @@ export async function main(argv = process.argv.slice(2)): Promise<void> {
   }
 
   if (args.command === "logs") {
-    showLogs(await getServerStatus());
+    showLogs(await getServerStatus(), { tail: args.tail, errorsOnly: args.errorsOnly });
     return;
   }
 

packages/cli/src/log-excerpt.test.ts

@@ -0,0 +1,62 @@
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { getFileSize, readLogExcerpt } from "./log-excerpt";
+
+describe("log-excerpt", () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    testDir = mkdtempSync(join(tmpdir(), "cs-log-excerpt-"));
+  });
+
+  afterEach(() => {
+    if (existsSync(testDir)) {
+      rmSync(testDir, { recursive: true, force: true });
+    }
+  });
+
+  it("returns only the newly appended log lines after the provided offset", () => {
+    const logPath = join(testDir, "server.err.log");
+    writeFileSync(logPath, "stale line 1\nstale line 2\n");
+
+    const startOffset = getFileSize(logPath);
+    writeFileSync(logPath, "fresh line 1\nfresh line 2\n", { flag: "a" });
+
+    expect(readLogExcerpt(logPath, { startOffset })).toBe("fresh line 1\nfresh line 2");
+  });
+
+  it("returns the recent tail when the new content exceeds configured limits", () => {
+    const logPath = join(testDir, "server.err.log");
+    writeFileSync(logPath, "line 1\nline 2\nline 3\nline 4\n");
+
+    expect(
+      readLogExcerpt(logPath, {
+        startOffset: 0,
+        maxBytes: 64,
+        maxLines: 2,
+        maxChars: 8,
+      })
+    ).toBe("…\nline 4");
+  });
+
+  it("reads the replacement file when the previous offset is beyond the new size", () => {
+    const logPath = join(testDir, "server.err.log");
+    writeFileSync(logPath, "stale line 1\nstale line 2\n");
+
+    const startOffset = getFileSize(logPath);
+    writeFileSync(logPath, "fresh replacement line\n", "utf-8");
+
+    expect(readLogExcerpt(logPath, { startOffset })).toBe("fresh replacement line");
+  });
+
+  it("drops a partial leading line when bounded tail reads start mid-line", () => {
+    const logPath = join(testDir, "server.err.log");
+    writeFileSync(logPath, "very long first line\nsecond line\nthird line\n", "utf-8");
+
+    expect(readLogExcerpt(logPath, { maxBytes: 30, maxChars: null })).toBe(
+      "second line\nthird line"
+    );
+  });
+});

packages/cli/src/log-excerpt.ts

@@ -0,0 +1,94 @@
+import { closeSync, existsSync, openSync, readSync, statSync } from "fs";
+
+const DEFAULT_MAX_LINES = 40;
+const DEFAULT_MAX_CHARS = 4000;
+const DEFAULT_MAX_BYTES = 16 * 1024;
+
+export interface LogExcerptOptions {
+  startOffset?: number;
+  maxBytes?: number;
+  maxLines?: number;
+  maxChars?: number | null;
+}
+
+export const getFileSize = (path: string): number => {
+  if (!existsSync(path)) {
+    return 0;
+  }
+
+  try {
+    return statSync(path).size;
+  } catch {
+    return 0;
+  }
+};
+
+export const readLogExcerpt = (
+  path: string,
+  {
+    startOffset = 0,
+    maxBytes = DEFAULT_MAX_BYTES,
+    maxLines = DEFAULT_MAX_LINES,
+    maxChars = DEFAULT_MAX_CHARS,
+  }: LogExcerptOptions = {}
+): string | null => {
+  if (!existsSync(path)) {
+    return null;
+  }
+
+  const fileSize = getFileSize(path);
+  const safeOffset = startOffset > fileSize ? 0 : Math.max(0, startOffset);
+  if (fileSize === safeOffset) {
+    return null;
+  }
+
+  const bytesToRead = Math.min(fileSize - safeOffset, maxBytes);
+  const readStart = fileSize - bytesToRead;
+  const buffer = Buffer.allocUnsafe(bytesToRead);
+  const fd = openSync(path, "r");
+  let content = "";
+  let startsMidLine = false;
+
+  try {
+    const bytesRead = readSync(fd, buffer, 0, bytesToRead, readStart);
+    if (bytesRead === 0) {
+      return null;
+    }
+
+    if (readStart > safeOffset && readStart > 0) {
+      const previousByte = Buffer.alloc(1);
+      const previousBytesRead = readSync(fd, previousByte, 0, 1, readStart - 1);
+      startsMidLine = previousBytesRead === 1 && previousByte[0] !== 0x0a;
+    }
+
+    content = buffer.toString("utf-8", 0, bytesRead).trimEnd();
+  } finally {
+    closeSync(fd);
+  }
+
+  if (startsMidLine) {
+    const firstNewlineIndex = content.indexOf("\n");
+    if (firstNewlineIndex !== -1) {
+      content = content.slice(firstNewlineIndex + 1);
+    }
+  }
+
+  if (content.length === 0) {
+    return null;
+  }
+
+  const lines = content
+    .split(/\r?\n/u)
+    .map((line) => line.trimEnd())
+    .filter((line) => line.length > 0);
+  if (lines.length === 0) {
+    return null;
+  }
+
+  const excerpt = lines.slice(-maxLines).join("\n");
+  if (maxChars === null || excerpt.length <= maxChars) {
+    return excerpt;
+  }
+
+  return `…${excerpt.slice(-maxChars + 1)}`;
+};