@tanishqkancharla/diffmap 0.1.4 → 0.1.5

package/src/serve.test.ts

@@ -0,0 +1,306 @@
+import assert from "node:assert/strict";
+import { execFile, spawn, type ChildProcess } from "node:child_process";
+import fs from "node:fs/promises";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { setTimeout as delay } from "node:timers/promises";
+import test from "node:test";
+import { DiffmapServeError } from "./errors.js";
+import { startServer, type DiffmapServer } from "./serve.js";
+
+const execFileAsync = promisify(execFile);
+const srcDir = fileURLToPath(new URL(".", import.meta.url));
+const packageRoot = path.resolve(srcDir, "..");
+const cliPath = path.join(srcDir, "cli.ts");
+const sampleSpec = path.join(packageRoot, "fixtures", "sample-spec.md");
+const localUrlPattern = /http:\/\/127\.0\.0\.1:\d+/g;
+
+function httpUrlPort(url: string) {
+  const parsed = new URL(url);
+  assert.equal(parsed.hostname, "127.0.0.1");
+  const port = Number(parsed.port);
+  assert.ok(Number.isInteger(port) && port > 0);
+  return port;
+}
+
+function assertStarted(
+  started: Awaited<ReturnType<typeof startServer>>,
+): DiffmapServer {
+  assert.equal(
+    started instanceof Error,
+    false,
+    started instanceof Error ? started.message : "",
+  );
+  if (started instanceof Error) throw started;
+  return started;
+}
+
+async function occupyPort(port: number) {
+  const server = net.createServer();
+  try {
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(port, "127.0.0.1", () => resolve());
+    });
+    return server;
+  } catch {
+    server.close();
+    return undefined;
+  }
+}
+
+async function listenEphemeral() {
+  const server = net.createServer();
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => resolve());
+  });
+  return server;
+}
+
+function boundPort(server: net.Server) {
+  const address = server.address();
+  assert.ok(address !== null && typeof address !== "string");
+  return address.port;
+}
+
+async function closeTcp(server: net.Server | undefined) {
+  if (server === undefined) return;
+  await new Promise<void>((resolve) => {
+    server.close(() => resolve());
+  });
+}
+
+async function fetchOk(url: string) {
+  const response = await fetch(url, {
+    headers: { accept: "text/markdown" },
+  });
+  assert.equal(response.ok, true);
+  const body = await response.text();
+  assert.match(body, /Spec fixture/);
+}
+
+async function waitForClosed(server: DiffmapServer, timeoutMs = 10_000) {
+  await Promise.race([
+    server.closed,
+    delay(timeoutMs).then(() => {
+      throw new Error(`server did not close: ${server.url}`);
+    }),
+  ]);
+}
+
+test(
+  "startServer binds distinct free ports when 4177 is taken",
+  { timeout: 90_000 },
+  async () => {
+    const occupied = await occupyPort(4177);
+    try {
+      const first = assertStarted(
+        await startServer({
+          filePath: sampleSpec,
+          workspaceRoot: packageRoot,
+        }),
+      );
+      const second = assertStarted(
+        await startServer({
+          filePath: sampleSpec,
+          workspaceRoot: packageRoot,
+        }),
+      );
+      try {
+        const firstPort = httpUrlPort(first.url);
+        const secondPort = httpUrlPort(second.url);
+        assert.notEqual(firstPort, secondPort);
+        assert.notEqual(firstPort, 4177);
+        assert.notEqual(secondPort, 4177);
+        await fetchOk(first.url);
+        await fetchOk(second.url);
+      } finally {
+        await first.shutdown();
+        await second.shutdown();
+        await waitForClosed(first);
+        await waitForClosed(second);
+      }
+    } finally {
+      await closeTcp(occupied);
+    }
+  },
+);
+
+test(
+  "startServer --port pins and fails when that port is taken",
+  { timeout: 90_000 },
+  async () => {
+    const holder = await listenEphemeral();
+    const port = boundPort(holder);
+
+    const blocked = await startServer({
+      filePath: sampleSpec,
+      workspaceRoot: packageRoot,
+      port,
+    });
+    assert.equal(blocked instanceof DiffmapServeError, true);
+    if (!(blocked instanceof DiffmapServeError)) return;
+    assert.match(blocked.message, /already in use/i);
+
+    await closeTcp(holder);
+
+    const pinned = assertStarted(
+      await startServer({
+        filePath: sampleSpec,
+        workspaceRoot: packageRoot,
+        port,
+      }),
+    );
+    try {
+      assert.equal(httpUrlPort(pinned.url), port);
+      await fetchOk(pinned.url);
+    } finally {
+      await pinned.shutdown();
+      await waitForClosed(pinned);
+    }
+  },
+);
+
+test(
+  "startServer Close server still stops an ephemeral listener",
+  { timeout: 90_000 },
+  async () => {
+    const started = assertStarted(
+      await startServer({
+        filePath: sampleSpec,
+        workspaceRoot: packageRoot,
+      }),
+    );
+    const response = await fetch(`${started.url}/__diffmap/shutdown`, {
+      method: "POST",
+    });
+    assert.equal(response.ok, true);
+    await waitForClosed(started);
+    await assert.rejects(() => fetch(started.url));
+  },
+);
+
+type SpawnedCli = {
+  child: ChildProcess;
+  output: () => string;
+};
+
+function spawnCli(args: string[]) {
+  let stdout = "";
+  let stderr = "";
+  const child = spawn(process.execPath, ["--import", "tsx", cliPath, ...args], {
+    cwd: packageRoot,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  child.stdout?.on("data", (chunk: Buffer) => {
+    stdout += chunk.toString();
+  });
+  child.stderr?.on("data", (chunk: Buffer) => {
+    stderr += chunk.toString();
+  });
+  return {
+    child,
+    output: () => `${stdout}${stderr}`,
+  };
+}
+
+function firstLocalUrl(text: string) {
+  return text.match(localUrlPattern)?.[0];
+}
+
+async function waitForLocalUrl(spawned: SpawnedCli, timeoutMs = 60_000) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (spawned.child.exitCode !== null) {
+      throw new Error(
+        `cli exited ${spawned.child.exitCode} before listen:\n${spawned.output()}`,
+      );
+    }
+    const url = firstLocalUrl(spawned.output());
+    if (url !== undefined) return url;
+    await delay(50);
+  }
+  throw new Error(`cli printed no listen url:\n${spawned.output()}`);
+}
+
+async function waitForExit(child: ChildProcess, timeoutMs = 15_000) {
+  if (child.exitCode !== null) return;
+  await Promise.race([
+    new Promise<void>((resolve) => {
+      child.once("exit", () => resolve());
+    }),
+    delay(timeoutMs).then(() => {
+      child.kill("SIGKILL");
+      throw new Error("cli did not exit");
+    }),
+  ]);
+}
+
+async function stopCli(spawned: SpawnedCli, url: string) {
+  const response = await fetch(`${url}/__diffmap/shutdown`, {
+    method: "POST",
+  }).catch(() => undefined);
+  if (response === undefined || !response.ok) {
+    spawned.child.kill("SIGTERM");
+  }
+  await waitForExit(spawned.child);
+}
+
+async function withTempSpecs(
+  run: (firstFile: string, secondFile: string) => Promise<void>,
+) {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "diffmap-serve-"));
+  const firstFile = path.join(dir, "one.md");
+  const secondFile = path.join(dir, "two.md");
+  const source = await fs.readFile(sampleSpec, "utf8");
+  await Promise.all([
+    fs.writeFile(firstFile, source),
+    fs.writeFile(secondFile, source),
+  ]);
+  try {
+    await run(firstFile, secondFile);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+}
+
+test(
+  "diffmap serve prints a free port and list tracks both servers",
+  { timeout: 90_000 },
+  async () => {
+    await withTempSpecs(async (firstFile, secondFile) => {
+      const first = spawnCli(["serve", firstFile]);
+      const second = spawnCli([secondFile]);
+      try {
+        const firstUrl = await waitForLocalUrl(first);
+        const secondUrl = await waitForLocalUrl(second);
+        assert.notEqual(firstUrl, secondUrl);
+        await fetchOk(firstUrl);
+        await fetchOk(secondUrl);
+
+        const listed = await execFileAsync(
+          process.execPath,
+          ["--import", "tsx", cliPath, "list"],
+          {
+            cwd: packageRoot,
+            timeout: 20_000,
+            maxBuffer: 1_000_000,
+          },
+        );
+        const listOutput = `${listed.stdout}${listed.stderr}`;
+        assert.equal(listOutput.includes(firstUrl), true);
+        assert.equal(listOutput.includes(secondUrl), true);
+
+        await stopCli(first, firstUrl);
+        await stopCli(second, secondUrl);
+      } finally {
+        first.child.kill("SIGTERM");
+        second.child.kill("SIGTERM");
+      }
+    });
+  },
+);

package/src/serve.ts

@@ -22,7 +22,7 @@ export type DiffmapServer = {
 export type StartServerInput = {
   filePath: string;
   workspaceRoot: string;
-  port: number;
+  port?: number;
 };
 
 const packageRoot = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
@@ -45,6 +45,7 @@ function createClosedBarrier() {
 export async function startServer(input: StartServerInput) {
   const filePath = path.resolve(input.filePath);
   const workspaceRoot = path.resolve(input.workspaceRoot);
+  const port = input.port ?? 0;
   const source = await fs.readFile(filePath, "utf8").catch(
     (cause) =>
       new DiffmapFileError({
@@ -82,9 +83,9 @@ export async function startServer(input: StartServerInput) {
     configFile: path.join(packageRoot, "vite.config.ts"),
     root: packageRoot,
     server: {
-      port: input.port,
+      port,
       host: "127.0.0.1",
-      strictPort: input.port !== 0,
+      strictPort: port !== 0,
       fs: {
         allow: [packageRoot, workspaceRoot, path.dirname(filePath)],
       },
@@ -138,7 +139,16 @@ export async function startServer(input: StartServerInput) {
     ],
   });
 
-  await vite.listen(input.port);
+  const listened = await vite.listen(port).catch(
+    (cause) =>
+      new DiffmapServeError({
+        reason: cause instanceof Error ? cause.message : "listen failed",
+      }),
+  );
+  if (listened instanceof Error) {
+    await shutdown();
+    return listened;
+  }
   const localUrl = vite.resolvedUrls?.local[0];
   if (localUrl === undefined) {
     await shutdown();

package/src/update.test.ts

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { compareVersions, resolveUpdateArgv } from "./update.js";
+
+test("compareVersions orders versions by semver precedence", () => {
+  assert.equal(compareVersions("0.1.4", "0.1.4"), 0);
+  assert.equal(compareVersions("0.1.4", "0.1.5"), -1);
+  assert.equal(compareVersions("0.1.10", "0.1.9"), 1);
+  assert.equal(compareVersions("1.0.0-rc.1", "1.0.0"), -1);
+});
+
+test("update and --update run the same command", () => {
+  assert.deepEqual(resolveUpdateArgv(["update"]), ["update"]);
+  assert.deepEqual(resolveUpdateArgv(["--update"]), ["update"]);
+  assert.deepEqual(resolveUpdateArgv(["serve", "spec.md"]), [
+    "serve",
+    "spec.md",
+  ]);
+});

package/src/update.ts

@@ -0,0 +1,285 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import { DiffmapUpdateError } from "./errors.js";
+
+// The unscoped `diffmap` package on npm is unrelated; always use the scoped name.
+export const packageName = "@tanishqkancharla/diffmap";
+const latestSpec = `${packageName}@latest`;
+const registryUrl =
+  "https://registry.npmjs.org/@tanishqkancharla%2Fdiffmap/latest";
+
+type InstallMethod = "npm" | "pnpm" | "bun" | "npx" | "unknown";
+
+type Command = { command: string; args: string[] };
+
+type UpdateResult =
+  | { status: "up-to-date"; current: string; latest: string; message: string }
+  | {
+      status: "updated";
+      previous: string;
+      current: string;
+      command: string;
+      message: string;
+    }
+  | {
+      status: "manual";
+      current: string;
+      latest: string;
+      command: string;
+      message: string;
+    };
+
+type UpdateDeps = {
+  currentVersion: string;
+  fetchLatestVersion: () => Promise<string | Error>;
+  detectInstallMethod: () => Promise<InstallMethod>;
+  runCommand: (command: Command) => Promise<void | Error>;
+};
+
+/** Routes `diffmap --update [...]` to the `update` command so incur's built-in updater never runs. */
+export function resolveUpdateArgv(argv: string[]) {
+  const separator = argv.indexOf("--");
+  const flags = separator === -1 ? argv : argv.slice(0, separator);
+  if (!flags.includes("--update")) return argv;
+  const rest = argv.filter((token, index) => {
+    return token !== "--update" || (separator !== -1 && index > separator);
+  });
+  return ["update", ...rest];
+}
+
+type ParsedVersion = {
+  core: [number, number, number];
+  prerelease: string[];
+};
+
+function parseVersion(version: string): ParsedVersion | undefined {
+  const match = version
+    .trim()
+    .replace(/^v/, "")
+    .match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/);
+  if (!match) return undefined;
+  return {
+    core: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4] === undefined ? [] : match[4].split("."),
+  };
+}
+
+/** Semver precedence: negative when `a < b`, positive when `a > b`, 0 when equal. */
+export function compareVersions(a: string, b: string) {
+  const left = parseVersion(a);
+  const right = parseVersion(b);
+  if (!left || !right) {
+    return new DiffmapUpdateError({
+      reason: `cannot compare versions "${a}" and "${b}"`,
+    });
+  }
+  for (let index = 0; index < 3; index++) {
+    const difference = left.core[index]! - right.core[index]!;
+    if (difference !== 0) return Math.sign(difference);
+  }
+  if (left.prerelease.length === 0 || right.prerelease.length === 0) {
+    return Math.sign(right.prerelease.length - left.prerelease.length);
+  }
+  const length = Math.max(left.prerelease.length, right.prerelease.length);
+  for (let index = 0; index < length; index++) {
+    const leftPart = left.prerelease[index];
+    const rightPart = right.prerelease[index];
+    if (leftPart === undefined) return -1;
+    if (rightPart === undefined) return 1;
+    if (leftPart === rightPart) continue;
+    const leftNumeric = /^\d+$/.test(leftPart);
+    const rightNumeric = /^\d+$/.test(rightPart);
+    if (leftNumeric && rightNumeric) {
+      return Math.sign(Number(leftPart) - Number(rightPart));
+    }
+    if (leftNumeric) return -1;
+    if (rightNumeric) return 1;
+    return leftPart < rightPart ? -1 : 1;
+  }
+  return 0;
+}
+
+function normalizePath(value: string) {
+  return value.replaceAll("\\", "/").replace(/\/+$/, "");
+}
+
+/** Infers the install method from the real path of the running entry script. */
+function detectInstallMethodFromPath(input: {
+  entryPath: string;
+  env: Record<string, string | undefined>;
+  npmGlobalRoot?: string | undefined;
+}): InstallMethod {
+  const entry = normalizePath(input.entryPath);
+  if (input.env.npm_command === "exec" || entry.includes("/_npx/")) {
+    return "npx";
+  }
+  if (entry.includes("/.bun/install/global/")) return "bun";
+  const pnpmHome = input.env.PNPM_HOME;
+  if (
+    entry.includes("/pnpm/global/") ||
+    (pnpmHome !== undefined &&
+      pnpmHome !== "" &&
+      entry.startsWith(`${normalizePath(pnpmHome)}/global/`))
+  ) {
+    return "pnpm";
+  }
+  if (input.npmGlobalRoot !== undefined && input.npmGlobalRoot !== "") {
+    const root = normalizePath(input.npmGlobalRoot);
+    if (entry.startsWith(`${root}/${packageName}/`)) return "npm";
+  }
+  return "unknown";
+}
+
+function globalInstallCommand(method: "npm" | "pnpm" | "bun"): Command {
+  if (method === "pnpm") {
+    return { command: "pnpm", args: ["add", "--global", latestSpec] };
+  }
+  if (method === "bun") {
+    return { command: "bun", args: ["add", "--global", latestSpec] };
+  }
+  return { command: "npm", args: ["install", "--global", latestSpec] };
+}
+
+function formatCommand(command: Command) {
+  return [command.command, ...command.args].join(" ");
+}
+
+export async function runUpdate(deps: UpdateDeps) {
+  const current = deps.currentVersion;
+  const latest = await deps.fetchLatestVersion();
+  if (latest instanceof Error) return latest;
+
+  const comparison = compareVersions(current, latest);
+  if (comparison instanceof Error) return comparison;
+  if (comparison >= 0) {
+    return {
+      message: `diffmap is already up to date (${current})`,
+      status: "up-to-date",
+      current,
+      latest,
+    } satisfies UpdateResult;
+  }
+
+  const method = await deps.detectInstallMethod();
+  if (method === "npx") {
+    const command = `npx ${latestSpec}`;
+    return {
+      message: `diffmap ${latest} is available (running ${current} through npx). Run \`${command}\` to use it, or install it globally with \`${formatCommand(globalInstallCommand("npm"))}\`.`,
+      status: "manual",
+      current,
+      latest,
+      command,
+    } satisfies UpdateResult;
+  }
+  if (method === "unknown") {
+    const command = formatCommand(globalInstallCommand("npm"));
+    return {
+      message: `diffmap ${latest} is available (running ${current}), but diffmap could not tell how it was installed. Update it with \`${command}\` or your package manager's equivalent.`,
+      status: "manual",
+      current,
+      latest,
+      command,
+    } satisfies UpdateResult;
+  }
+
+  const install = globalInstallCommand(method);
+  const installed = await deps.runCommand(install);
+  if (installed instanceof Error) return installed;
+  return {
+    message: `Updated diffmap from ${current} to ${latest}`,
+    status: "updated",
+    previous: current,
+    current: latest,
+    command: formatCommand(install),
+  } satisfies UpdateResult;
+}
+
+export async function fetchLatestVersion() {
+  const response = await fetch(registryUrl, {
+    headers: { accept: "application/json" },
+    signal: AbortSignal.timeout(10_000),
+  }).catch(
+    (cause) =>
+      new DiffmapUpdateError({
+        reason: "could not reach the npm registry",
+        cause,
+      }),
+  );
+  if (response instanceof Error) return response;
+  if (!response.ok) {
+    return new DiffmapUpdateError({
+      reason: `npm registry responded ${response.status} for ${packageName}`,
+    });
+  }
+  const body = (await response.json().catch(() => undefined)) as
+    | { version?: unknown }
+    | undefined;
+  if (typeof body?.version !== "string") {
+    return new DiffmapUpdateError({
+      reason: `npm registry returned no version for ${packageName}`,
+    });
+  }
+  return body.version;
+}
+
+function execCommand(command: Command) {
+  return new Promise<{ stdout: string; stderr: string } | Error>((resolve) => {
+    execFile(
+      command.command,
+      command.args,
+      { shell: process.platform === "win32", maxBuffer: 10_000_000 },
+      (cause, stdout, stderr) => {
+        if (cause) {
+          const detail = stderr.trim() || stdout.trim() || cause.message;
+          resolve(
+            new DiffmapUpdateError({
+              reason: `\`${formatCommand(command)}\` failed: ${detail}`,
+              cause,
+            }),
+          );
+          return;
+        }
+        resolve({ stdout, stderr });
+      },
+    );
+  });
+}
+
+async function readNpmGlobalRoot() {
+  const result = await execCommand({
+    command: "npm",
+    args: ["root", "--global"],
+  });
+  if (result instanceof Error) return undefined;
+  const root = result.stdout.trim();
+  if (root === "") return undefined;
+  try {
+    return fs.realpathSync(root);
+  } catch {
+    return root;
+  }
+}
+
+export async function detectInstallMethod() {
+  const entry = process.argv[1];
+  if (entry === undefined) return "unknown" satisfies InstallMethod;
+  let entryPath = entry;
+  try {
+    entryPath = fs.realpathSync(entry);
+  } catch {}
+  const withoutNpm = detectInstallMethodFromPath({
+    entryPath,
+    env: process.env,
+  });
+  if (withoutNpm !== "unknown") return withoutNpm;
+  return detectInstallMethodFromPath({
+    entryPath,
+    env: process.env,
+    npmGlobalRoot: await readNpmGlobalRoot(),
+  });
+}
+
+export async function runCommand(command: Command) {
+  const result = await execCommand(command);
+  if (result instanceof Error) return result;
+}

package/src/viewer/CloseServerButton.tsx

@@ -0,0 +1,16 @@
+import { Button, Close, colors } from "maui";
+import { style, useStyles } from "purse-styles";
+
+const closeIcon = style({
+  color: colors.red[9],
+});
+
+export function CloseServerButton(props: { onClick?: () => void }) {
+  const iconClass = useStyles(closeIcon);
+  return (
+    <Button variant="default" onClick={props.onClick}>
+      <Close className={iconClass} size="sm" />
+      Close server
+    </Button>
+  );
+}