@spencer-kit/coder-studio 0.3.0 → 0.3.2

package/src/cli.ts

@@ -0,0 +1,347 @@
+import { existsSync } from "fs";
+import { dirname, join } from "path";
+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 { getCliVersion } from "./package-manifest.js";
+import { parseArgs } from "./parse-args.js";
+import { startManagedServer } from "./pm2-control.js";
+import { confirmYesNo, isInteractiveSession } from "./prompts.js";
+import { getServerStatus, type ServerStatus, stopRunningServer } from "./server-control.js";
+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);
+}
+
+function formatStatus(status: ServerStatus): string {
+  const listenUrl = getListenUrl(status) ?? "n/a";
+  const browserUrl = getBrowserUrl(status) ?? "n/a";
+  const startedAt = status.startedAt === null ? "n/a" : new Date(status.startedAt).toISOString();
+
+  return [
+    `Status: ${status.status}`,
+    `Listen host: ${status.host ?? "n/a"}`,
+    `Listen IP: ${getListenIp(status) ?? "n/a"}`,
+    `Port: ${status.port ?? "n/a"}`,
+    `Listen URL: ${listenUrl}`,
+    `Local URL: ${browserUrl}`,
+    `PID: ${status.pid ?? "n/a"}`,
+    `Started: ${startedAt}`,
+    `Restarts: ${status.restartCount}`,
+    `Out log: ${status.outFile}`,
+    `Error log: ${status.errFile}`,
+  ].join("\n");
+}
+
+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) => {
+      const content = readLogExcerpt(path, { maxLines: tail, maxChars: null });
+      return content ? [content] : [];
+    });
+
+  console.log(contents.length === 0 ? "No logs available." : contents.join("\n"));
+}
+
+function showHelp(): void {
+  console.log(`
+@spencer-kit/coder-studio - Coder Studio CLI
+
+USAGE:
+  coder-studio [COMMAND]
+
+COMMANDS:
+  serve    Start the Coder Studio server in background (default)
+  server   Alias for serve
+  open     Start the server if needed and open Coder Studio in a browser
+  auth     Manage auth login blocks in local server storage
+  config   Persist CLI host/port/data-dir/password settings
+  stop     Stop the managed Coder Studio server
+  status   Show the managed server status
+  logs     Show the managed server logs
+  help     Show this help message
+  version  Show version
+
+OPTIONS:
+  --host <string>          Save server host for future runs
+  --port, -p <number>      Save server port for future runs
+  --data-dir, -d <path>    Save data directory for future runs
+  --password <string>      Save auth password for future runs
+  --restart                Restart an already running managed server for serve/open
+  --help                   Show help
+  --version, -v            Show version
+
+EXAMPLES:
+  coder-studio
+  coder-studio serve
+  coder-studio server
+  coder-studio auth ban-list
+  coder-studio auth unblock --ip 198.51.100.24
+  coder-studio serve --foreground
+  coder-studio serve --restart
+  coder-studio open
+  coder-studio open --restart
+  coder-studio status
+  coder-studio logs
+  coder-studio stop
+  coder-studio config --host 0.0.0.0 --port 8080
+`);
+}
+
+function showConfigHelp(): void {
+  console.log(`
+@spencer-kit/coder-studio - config
+
+USAGE:
+  coder-studio config [OPTIONS]
+  coder-studio config help
+
+BEHAVIOR:
+  Without options, prints the current saved config.
+  Bare serve reads this saved config for future runs.
+
+OPTIONS:
+  --host <string>          Save server host for future runs
+  --port, -p <number>      Save server port for future runs
+  --data-dir, -d <path>    Save data directory for future runs
+  --password <string>      Save auth password for future runs
+  --help                   Show config help
+
+EXAMPLES:
+  coder-studio config
+  coder-studio config --host 0.0.0.0
+  coder-studio config --port 8080
+  coder-studio config --data-dir /tmp/cs-data
+  coder-studio config --password sekrit
+  coder-studio config --host 0.0.0.0 --port 8080
+`);
+}
+
+function showVersion(): void {
+  console.log(`@spencer-kit/coder-studio v${getCliVersion(import.meta.url)}`);
+}
+
+function formatAuthBlocks(blocks: Awaited<ReturnType<typeof listAuthBlocks>>): string {
+  if (blocks.length === 0) {
+    return "No blocked IPs.";
+  }
+
+  return JSON.stringify(blocks, null, 2);
+}
+
+function resolveManagedScriptPath(): string {
+  const currentFile = fileURLToPath(import.meta.url);
+  const currentDir = dirname(currentFile);
+  const candidates = [
+    join(currentDir, "server-runner.js"),
+    join(currentDir, "server-runner.mjs"),
+    join(currentDir, "../src/server-runner.ts"),
+  ];
+
+  const scriptPath = candidates.find((candidate) => existsSync(candidate));
+  if (!scriptPath) {
+    throw new Error("Unable to locate the managed server entry script");
+  }
+
+  return scriptPath;
+}
+
+function isRunningStatus(status: ServerStatus): boolean {
+  return status.status === "running" || status.status === "starting";
+}
+
+interface ManagedStartupDecision {
+  existingStatus: ServerStatus | null;
+  restartRequested: boolean;
+}
+
+async function shouldRestartRunningServer(status: ServerStatus): Promise<boolean> {
+  const currentUrl = getBrowserUrl(status) ?? getListenUrl(status) ?? "the existing server";
+
+  if (!isInteractiveSession()) {
+    return false;
+  }
+
+  return confirmYesNo(`Coder Studio is already running at ${currentUrl}. Restart it? [y/N] `);
+}
+
+async function prepareManagedStartup(forceRestart = false): Promise<ManagedStartupDecision> {
+  const status = await getServerStatus();
+  if (!isRunningStatus(status)) {
+    return {
+      existingStatus: null,
+      restartRequested: false,
+    };
+  }
+
+  const restart = forceRestart ? true : await shouldRestartRunningServer(status);
+  if (!restart) {
+    const currentUrl = getBrowserUrl(status) ?? getListenUrl(status) ?? "n/a";
+    if (!isInteractiveSession()) {
+      console.log(
+        `Coder Studio is already running at ${currentUrl}. Service already exists and was not restarted.`
+      );
+    } else {
+      console.log(`Leaving the existing Coder Studio server running at ${currentUrl}.`);
+    }
+    return {
+      existingStatus: status,
+      restartRequested: false,
+    };
+  }
+
+  console.log("Restarting the managed Coder Studio server...");
+  return {
+    existingStatus: null,
+    restartRequested: true,
+  };
+}
+
+async function startManagedServerFlow(): Promise<void> {
+  await startManagedServer({
+    script: resolveManagedScriptPath(),
+    cwd: process.cwd(),
+    waitMs: MANAGED_SERVER_WAIT_MS,
+  });
+}
+
+async function openManagedServerInBrowser(existingStatus?: ServerStatus | null): Promise<void> {
+  const status = existingStatus ?? (await getServerStatus());
+  const browserUrl = getBrowserUrl(status);
+
+  if (browserUrl === null) {
+    throw new Error("Unable to determine the running Coder Studio URL.");
+  }
+
+  console.log(`Opening Coder Studio in your browser: ${browserUrl}`);
+  await openBrowser(browserUrl);
+}
+
+export async function main(argv = process.argv.slice(2)): Promise<void> {
+  assertSupportedNodeVersion();
+  const args = parseArgs(argv);
+
+  if (args.command === "config") {
+    if (args.configHelp) {
+      showConfigHelp();
+      return;
+    }
+
+    if (
+      args.host === undefined &&
+      args.port === undefined &&
+      args.dataDir === undefined &&
+      args.password === undefined
+    ) {
+      console.log(formatConfig(readCliConfig()));
+      return;
+    }
+
+    const savedConfig = readCliConfig();
+    const nextConfig: CliConfig = {
+      ...(savedConfig?.host !== undefined ? { host: savedConfig.host } : {}),
+      ...(savedConfig?.port !== undefined && savedConfig.port > 0
+        ? { port: savedConfig.port }
+        : {}),
+      ...(savedConfig?.dataDir !== undefined ? { dataDir: savedConfig.dataDir } : {}),
+      ...(savedConfig?.password !== undefined ? { password: savedConfig.password } : {}),
+      ...(args.host !== undefined ? { host: args.host } : {}),
+      ...(args.port !== undefined ? { port: args.port } : {}),
+      ...(args.dataDir !== undefined ? { dataDir: args.dataDir } : {}),
+      ...(args.password !== undefined ? { password: args.password } : {}),
+    };
+    writeCliConfig(nextConfig);
+    console.log(formatConfig(nextConfig));
+    return;
+  }
+
+  if (args.command === "stop") {
+    const stopped = await stopRunningServer();
+    console.log(stopped ? "Stopped Coder Studio server." : "No running Coder Studio server found.");
+    return;
+  }
+
+  if (args.command === "status") {
+    console.log(formatStatus(await getServerStatus()));
+    return;
+  }
+
+  if (args.command === "logs") {
+    showLogs(await getServerStatus(), { tail: args.tail, errorsOnly: args.errorsOnly });
+    return;
+  }
+
+  if (args.command === "help") {
+    showHelp();
+    return;
+  }
+
+  if (args.command === "version") {
+    showVersion();
+    return;
+  }
+
+  if (args.command === "auth") {
+    if (args.authCommand === "ban-list") {
+      console.log(formatAuthBlocks(await listAuthBlocks()));
+      return;
+    }
+
+    if (args.authCommand === "unblock") {
+      const cleared = await clearAuthBlockByIp(args.ip!);
+      console.log(cleared ? `Unblocked IP: ${args.ip}` : `No block found for IP: ${args.ip}`);
+      return;
+    }
+  }
+
+  if (args.command === "open") {
+    const startup = await prepareManagedStartup(args.restart);
+    if (startup.existingStatus === null) {
+      await startManagedServerFlow();
+    }
+
+    await openManagedServerInBrowser(startup.existingStatus);
+    return;
+  }
+
+  if (args.foreground) {
+    const startup = await prepareManagedStartup(args.restart);
+    if (startup.existingStatus !== null) {
+      return;
+    }
+
+    if (startup.restartRequested) {
+      await stopRunningServer();
+    }
+
+    console.log("Starting Coder Studio Server in foreground...");
+    await startServer();
+    return;
+  }
+
+  const startup = await prepareManagedStartup(args.restart);
+  if (startup.existingStatus !== null) {
+    return;
+  }
+
+  await startManagedServerFlow();
+
+  console.log("Coder Studio server started in background.");
+  console.log("Run `coder-studio status` to inspect the server.");
+}

package/src/package-manifest.test.ts

@@ -1,5 +1,7 @@
 import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
 import { describe, expect, it } from "vitest";
+import { getCliVersion, resolveCliPackageManifestUrl } from "./package-manifest.js";
 
 interface PackageManifest {
   dependencies?: Record<string, string>;
@@ -12,6 +14,18 @@ function readPackageManifest(relativePath: string): PackageManifest {
 }
 
 describe("cli package manifest", () => {
+  it("resolves the CLI package manifest instead of the workspace root manifest", () => {
+    expect(fileURLToPath(resolveCliPackageManifestUrl(import.meta.url))).toBe(
+      fileURLToPath(new URL("../package.json", import.meta.url))
+    );
+  });
+
+  it("reads the published CLI version from the CLI package manifest", () => {
+    const cliPackage = readPackageManifest("../package.json") as { version?: string };
+
+    expect(getCliVersion(import.meta.url)).toBe(cliPackage.version);
+  });
+
   it("declares every external server runtime dependency", () => {
     const cliPackage = readPackageManifest("../package.json");
     const serverPackage = readPackageManifest("../../server/package.json");

package/src/package-manifest.ts

@@ -0,0 +1,28 @@
+import { existsSync, readFileSync } from "fs";
+
+interface CliPackageManifest {
+  version?: string;
+}
+
+export function resolveCliPackageManifestUrl(importMetaUrl: string): URL {
+  const manifestUrl = [
+    new URL("../package.json", importMetaUrl),
+    new URL("../../package.json", importMetaUrl),
+  ].find((candidate) => existsSync(candidate));
+
+  if (!manifestUrl) {
+    throw new Error("Unable to locate CLI package.json");
+  }
+
+  return manifestUrl;
+}
+
+export function getCliPackageManifest(importMetaUrl: string): CliPackageManifest {
+  return JSON.parse(
+    readFileSync(resolveCliPackageManifestUrl(importMetaUrl), "utf-8")
+  ) as CliPackageManifest;
+}
+
+export function getCliVersion(importMetaUrl: string): string {
+  return getCliPackageManifest(importMetaUrl).version ?? "0.0.0";
+}

package/src/pm2-control.test.ts

@@ -33,15 +33,22 @@ import {
 describe("pm2-control", () => {
   const originalHome = process.env.HOME;
   const originalUserProfile = process.env.USERPROFILE;
+  const originalRuntimeDir = process.env.CODER_STUDIO_RUNTIME_DIR;
+  const originalRuntimeJsonPath = process.env.CODER_STUDIO_RUNTIME_JSON_PATH;
   let testHomeDir: string;
 
   beforeEach(() => {
     testHomeDir = mkdtempSync(join(tmpdir(), "cs-pm2-control-home-"));
     process.env.HOME = testHomeDir;
     process.env.USERPROFILE = testHomeDir;
+    process.env.CODER_STUDIO_RUNTIME_DIR = join(testHomeDir, ".coder-studio");
+    delete process.env.CODER_STUDIO_RUNTIME_JSON_PATH;
 
     connect.mockImplementation((callback: (error: Error | null) => void) => callback(null));
-    disconnect.mockImplementation(() => undefined);
+    disconnect.mockImplementation((callback?: (error: Error | null) => void) => {
+      callback?.(null);
+      return undefined;
+    });
     start.mockImplementation(
       (_config: unknown, callback: (error: Error | null, apps: unknown[]) => void) => {
         writeRuntimeConfig({
@@ -80,6 +87,18 @@ describe("pm2-control", () => {
       process.env.USERPROFILE = originalUserProfile;
     }
 
+    if (originalRuntimeDir === undefined) {
+      delete process.env.CODER_STUDIO_RUNTIME_DIR;
+    } else {
+      process.env.CODER_STUDIO_RUNTIME_DIR = originalRuntimeDir;
+    }
+
+    if (originalRuntimeJsonPath === undefined) {
+      delete process.env.CODER_STUDIO_RUNTIME_JSON_PATH;
+    } else {
+      process.env.CODER_STUDIO_RUNTIME_JSON_PATH = originalRuntimeJsonPath;
+    }
+
     if (existsSync(testHomeDir)) {
       rmSync(testHomeDir, { recursive: true, force: true });
     }
@@ -157,6 +176,67 @@ describe("pm2-control", () => {
     ).resolves.toBe("waiting");
 
     expect(start).not.toHaveBeenCalled();
+    await pendingStart;
+  });
+
+  it("reuses one pm2 session while polling deletion during startup", async () => {
+    describeProcess
+      .mockImplementationOnce(
+        (_name: string, callback: (error: Error | null, result: unknown[]) => void) =>
+          callback(null, [{ pid: 111, pm2_env: { status: "online", restart_time: 0 } }])
+      )
+      .mockImplementationOnce(
+        (_name: string, callback: (error: Error | null, result: unknown[]) => void) =>
+          callback(null, [{ pid: 111, pm2_env: { status: "stopping", restart_time: 0 } }])
+      )
+      .mockImplementationOnce(
+        (_name: string, callback: (error: Error | null, result: unknown[]) => void) =>
+          callback(null, [])
+      );
+
+    await startManagedServer({
+      script: "/cli/dist/esm/server-runner.js",
+      cwd: "/repo",
+      waitMs: 10,
+    });
+
+    expect(connect).toHaveBeenCalledTimes(1);
+    expect(disconnect).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps waiting during startup when delete reports missing but the old app still lingers", async () => {
+    describeProcess
+      .mockImplementationOnce(
+        (_name: string, callback: (error: Error | null, result: unknown[]) => void) =>
+          callback(null, [{ pid: 111, pm2_env: { status: "online", restart_time: 0 } }])
+      )
+      .mockImplementationOnce(
+        (_name: string, callback: (error: Error | null, result: unknown[]) => void) =>
+          callback(null, [{ pid: 111, pm2_env: { status: "stopping", restart_time: 0 } }])
+      )
+      .mockImplementationOnce(
+        (_name: string, callback: (error: Error | null, result: unknown[]) => void) =>
+          callback(null, [])
+      );
+    deleteProcess.mockImplementationOnce((_name: string, callback: (error: Error | null) => void) =>
+      callback(new Error("process or namespace not found"))
+    );
+
+    const pendingStart = startManagedServer({
+      script: "/cli/dist/esm/server-runner.js",
+      cwd: "/repo",
+      waitMs: 10,
+    });
+
+    await expect(
+      Promise.race([
+        pendingStart.then(() => "started"),
+        new Promise((resolve) => setTimeout(() => resolve("waiting"), 20)),
+      ])
+    ).resolves.toBe("waiting");
+
+    expect(start).not.toHaveBeenCalled();
+    await pendingStart;
   });
 
   it("ignores delete-time missing errors when requested", async () => {
@@ -169,6 +249,8 @@ describe("pm2-control", () => {
     );
 
     await expect(deleteManagedServer({ ignoreMissing: true })).resolves.toBe(false);
+    expect(connect).toHaveBeenCalledTimes(1);
+    expect(disconnect).toHaveBeenCalledTimes(1);
   });
 
   it("fails background startup when runtime readiness times out", async () => {
@@ -183,6 +265,10 @@ describe("pm2-control", () => {
           callback(null, [])
       )
       .mockImplementationOnce(
+        (_name: string, callback: (error: Error | null, result: unknown[]) => void) =>
+          callback(null, [])
+      )
+      .mockImplementation(
         (_name: string, callback: (error: Error | null, result: unknown[]) => void) =>
           callback(null, [{ pid: 424242, pm2_env: { status: "online", restart_time: 0 } }])
       );
@@ -243,6 +329,8 @@ describe("pm2-control", () => {
       pm2Pid: null,
       restartCount: 0,
     });
+    expect(connect).toHaveBeenCalledTimes(1);
+    expect(disconnect).toHaveBeenCalledTimes(1);
   });
 
   it("maps an online PM2 app to running status", async () => {