overmux 0.0.1 → 0.0.2

package/src/internal/cli/commands/desktop-release.ts

@@ -0,0 +1,190 @@
+import { createHash } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+
+export type DesktopArchitecture = "arm64" | "x64";
+
+type GitHubAsset = {
+  browser_download_url: string;
+  name: string;
+  size: number;
+};
+
+type GitHubRelease = {
+  assets: GitHubAsset[];
+  draft: boolean;
+  prerelease: boolean;
+  published_at: string | null;
+  tag_name: string;
+};
+
+export type DesktopRelease = {
+  artifact: GitHubAsset;
+  checksums: GitHubAsset;
+  tag: string;
+  version: string;
+};
+
+const releasesUrl =
+  "https://api.github.com/repos/richardgill/overmux/releases?per_page=100";
+const downloadRoot =
+  "https://github.com/richardgill/overmux/releases/download/";
+
+export const getMacDesktopArtifactName = (
+  version: string,
+  architecture: DesktopArchitecture,
+) => `Overmux-Desktop-${version}-mac-${architecture}.zip`;
+
+const assertOfficialAsset = (asset: GitHubAsset, tag: string) => {
+  const expected = `${downloadRoot}${tag}/${asset.name}`;
+  if (asset.browser_download_url !== expected) {
+    throw new Error(
+      `Refusing unofficial desktop asset URL: ${asset.browser_download_url}`,
+    );
+  }
+  if (!Number.isSafeInteger(asset.size) || asset.size <= 0) {
+    throw new Error(`Desktop release asset ${asset.name} has an invalid size`);
+  }
+};
+
+export const selectDesktopRelease = (
+  releases: readonly GitHubRelease[],
+  architecture: DesktopArchitecture,
+): DesktopRelease => {
+  const candidates = releases
+    .filter(
+      (release) =>
+        !release.draft &&
+        !release.prerelease &&
+        /^desktop-v[^/]+$/.test(release.tag_name),
+    )
+    .sort((left, right) =>
+      (right.published_at ?? "").localeCompare(left.published_at ?? ""),
+    );
+
+  const selected = candidates.find((release) => {
+    const version = release.tag_name.slice("desktop-v".length);
+    return release.assets.some(
+      (asset) =>
+        asset.name === getMacDesktopArtifactName(version, architecture),
+    );
+  });
+  if (!selected) {
+    throw new Error(
+      `No stable Overmux Desktop release supports macOS ${architecture}`,
+    );
+  }
+
+  const version = selected.tag_name.slice("desktop-v".length);
+  const artifactName = getMacDesktopArtifactName(version, architecture);
+  const artifact = selected.assets.find((asset) => asset.name === artifactName);
+  const checksums = selected.assets.find(
+    (asset) => asset.name === "SHA256SUMS",
+  );
+  if (!artifact || !checksums) {
+    throw new Error(`Desktop release ${selected.tag_name} is incomplete`);
+  }
+  assertOfficialAsset(artifact, selected.tag_name);
+  assertOfficialAsset(checksums, selected.tag_name);
+  return { artifact, checksums, tag: selected.tag_name, version };
+};
+
+const fetchOk = async (url: string, fetch: typeof globalThis.fetch) => {
+  if (new URL(url).protocol !== "https:") {
+    throw new Error(`Refusing insecure desktop release URL: ${url}`);
+  }
+  const response = await fetch(url, {
+    headers: { Accept: "application/vnd.github+json" },
+  });
+  if (!response.ok) {
+    throw new Error(`GitHub request failed (${response.status}) for ${url}`);
+  }
+  if (response.url && new URL(response.url).protocol !== "https:") {
+    throw new Error(
+      `Refusing insecure desktop release redirect: ${response.url}`,
+    );
+  }
+  return response;
+};
+
+export const findDesktopRelease = async (
+  architecture: DesktopArchitecture,
+  fetch = globalThis.fetch,
+) => {
+  const response = await fetchOk(releasesUrl, fetch);
+  return selectDesktopRelease(
+    (await response.json()) as GitHubRelease[],
+    architecture,
+  );
+};
+
+export const parseSha256Sums = (contents: string) => {
+  const checksums = new Map<string, string>();
+  contents.split(/\r?\n/).forEach((line) => {
+    if (!line) {
+      return;
+    }
+    const match = /^([a-f0-9]{64})  ([^/\\]+)$/.exec(line);
+    if (!match || checksums.has(match[2])) {
+      throw new Error("Desktop release has an invalid SHA256SUMS file");
+    }
+    checksums.set(match[2], match[1]);
+  });
+  return checksums;
+};
+
+export const downloadTextAsset = async (
+  asset: GitHubAsset,
+  fetch = globalThis.fetch,
+) => {
+  const response = await fetchOk(asset.browser_download_url, fetch);
+  const contents = await response.text();
+  if (Buffer.byteLength(contents) !== asset.size) {
+    throw new Error(
+      `Downloaded ${asset.name} size does not match GitHub metadata`,
+    );
+  }
+  return contents;
+};
+
+export const downloadVerifiedAsset = async ({
+  asset,
+  destination,
+  expectedSha256,
+  fetch = globalThis.fetch,
+}: {
+  asset: GitHubAsset;
+  destination: string;
+  expectedSha256: string;
+  fetch?: typeof globalThis.fetch;
+}) => {
+  const response = await fetchOk(asset.browser_download_url, fetch);
+  if (!response.body) {
+    throw new Error(`Downloaded ${asset.name} has no body`);
+  }
+  const hash = createHash("sha256");
+  let size = 0;
+  const verification = new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      size += chunk.byteLength;
+      hash.update(chunk);
+      callback(null, chunk);
+    },
+  });
+  await pipeline(
+    Readable.fromWeb(
+      response.body as unknown as import("node:stream/web").ReadableStream,
+    ),
+    verification,
+    createWriteStream(destination),
+  );
+  if (size !== asset.size) {
+    throw new Error(
+      `Downloaded ${asset.name} size does not match GitHub metadata`,
+    );
+  }
+  if (hash.digest("hex") !== expectedSha256) {
+    throw new Error(`Downloaded ${asset.name} failed SHA-256 verification`);
+  }
+};

package/src/internal/cli/commands/desktop.ts

@@ -0,0 +1,47 @@
+import { buildCommand, buildRouteMap } from "@stricli/core";
+
+import type { CliCommandContext } from "../environment";
+import { installDesktop } from "./desktop-installer";
+
+type InstallFlags = { yes?: boolean };
+
+function runInstallCommand(this: CliCommandContext, flags: InstallFlags) {
+  return installDesktop(
+    { action: "install", yes: flags.yes },
+    {},
+    this.process,
+  );
+}
+
+function runUpgradeCommand(this: CliCommandContext) {
+  return installDesktop({ action: "upgrade" }, {}, this.process);
+}
+
+export const desktopInstallCommand = buildCommand({
+  func: runInstallCommand,
+  parameters: {
+    flags: {
+      yes: {
+        brief: "Accept the unsigned application risk without prompting",
+        kind: "boolean",
+        optional: true,
+      },
+    },
+    positional: { kind: "tuple", parameters: [] },
+  },
+  docs: { brief: "Install the experimental macOS desktop application" },
+});
+
+export const desktopUpgradeCommand = buildCommand({
+  func: runUpgradeCommand,
+  parameters: { positional: { kind: "tuple", parameters: [] } },
+  docs: { brief: "Upgrade the installed macOS desktop application" },
+});
+
+export const desktopRoute = buildRouteMap({
+  docs: { brief: "Install or upgrade Overmux Desktop on macOS" },
+  routes: {
+    install: desktopInstallCommand,
+    upgrade: desktopUpgradeCommand,
+  },
+});

package/src/internal/cli/commands/docs.ts

@@ -0,0 +1,34 @@
+import { buildCommand } from "@stricli/core";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+type DocsOutput = { write: (text: string) => unknown };
+
+export const resolveInstalledDocsRoot = (moduleUrl: string) => {
+  const candidates = ["../docs", "./docs", "../../../docs"].map((path) =>
+    fileURLToPath(new URL(path, moduleUrl)),
+  );
+  const docsRoot = candidates.find((candidate) => existsSync(candidate));
+  if (!docsRoot) {
+    throw new Error("Installed Overmux documentation is missing");
+  }
+  return resolve(docsRoot);
+};
+
+export const createDocsCommand = ({
+  docsRoot,
+  output,
+}: {
+  docsRoot: string;
+  output: DocsOutput;
+}) =>
+  buildCommand({
+    func: () => {
+      output.write(`${resolve(docsRoot)}\n`);
+    },
+    parameters: {},
+    docs: {
+      brief: "Print the installed documentation directory",
+    },
+  });

package/src/internal/cli/commands/serve.ts

@@ -0,0 +1,322 @@
+import { loadOvermuxConfig } from "@overmux/shared/node";
+import { buildCommand } from "@stricli/core";
+import { access } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import type { CliCommandContext, CliEnvironment } from "../environment";
+import { issueLoginGrant, printLoginFallback, printLoginGrant } from "../login";
+import {
+  loadViteRoot,
+  startManagedVite,
+  watchTrustedFiles,
+  type ViteApi,
+} from "../managed-vite";
+import { parsePort } from "../parse-port";
+import { startOvermuxServer } from "../../server/index";
+import { getDefaultConfigPath } from "../../server/paths";
+
+export type ServeFlags = {
+  config: string;
+  host?: string;
+  login?: boolean;
+  noBuild?: boolean;
+  noLogin?: boolean;
+  port?: number;
+  production?: boolean;
+};
+
+export type RunningServe = {
+  close: () => Promise<void>;
+  port: number;
+  url: string;
+};
+
+const loadApplicationVite = async (
+  viteConfigPath: string,
+): Promise<ViteApi> => {
+  const require = createRequire(viteConfigPath);
+  const viteEntry = require.resolve("vite");
+  return import(pathToFileURL(viteEntry).href) as Promise<ViteApi>;
+};
+
+// Register before startup resolves so signals still clean up partially started servers.
+const registerShutdown = (
+  running: Promise<RunningServe>,
+  process: NodeJS.Process,
+) => {
+  let shuttingDown = false;
+  const shutdown = async () => {
+    if (shuttingDown) {
+      return;
+    }
+    shuttingDown = true;
+    try {
+      const server = await running;
+      await server.close();
+      process.exitCode = 0;
+    } catch {
+      process.exitCode = 1;
+    }
+  };
+  const onSignal = () => void shutdown();
+  process.once("SIGINT", onSignal);
+  process.once("SIGTERM", onSignal);
+  return () => {
+    process.off("SIGINT", onSignal);
+    process.off("SIGTERM", onSignal);
+  };
+};
+
+const startDevelopmentServer = async ({
+  configPath,
+  host,
+  port,
+  shouldWatch,
+  vite,
+  viteConfigPath,
+}: {
+  configPath: string;
+  host?: string;
+  port?: number;
+  shouldWatch: boolean;
+  vite: ViteApi;
+  viteConfigPath: string;
+}): Promise<RunningServe> => {
+  const managedVite = await startManagedVite({
+    api: vite,
+    configPath: viteConfigPath,
+  });
+  let server: Awaited<ReturnType<typeof startOvermuxServer>> | undefined;
+  let stopWatching: () => void = () => undefined;
+  try {
+    if (shouldWatch) {
+      stopWatching = await watchTrustedFiles({
+        configPath,
+        onUpdate: () => server?.announceUpdateAvailable(),
+        server: managedVite.server,
+      });
+    }
+    server = await startOvermuxServer({
+      configPath,
+      developmentWebTarget: managedVite.target,
+      ...(host === undefined ? {} : { host }),
+      ...(port === undefined ? {} : { port }),
+      watch: false,
+    });
+    return {
+      close: async () => {
+        stopWatching();
+        await Promise.all([server?.close(), managedVite.close()]);
+      },
+      port: server.port,
+      url: server.url,
+    };
+  } catch (cause) {
+    stopWatching();
+    await Promise.all([server?.close(), managedVite.close()]);
+    throw cause;
+  }
+};
+
+const startProductionServer = async ({
+  configPath,
+  host,
+  noBuild,
+  port,
+  productionWebAssetsDir,
+  vite,
+  viteConfigPath,
+}: {
+  configPath: string;
+  host?: string;
+  noBuild: boolean;
+  port?: number;
+  productionWebAssetsDir: string;
+  vite: ViteApi;
+  viteConfigPath: string;
+}): Promise<RunningServe> => {
+  if (noBuild) {
+    const entryPath = join(productionWebAssetsDir, "index.html");
+    try {
+      await access(entryPath);
+    } catch {
+      throw new Error(`Production entry does not exist: ${entryPath}`);
+    }
+  } else {
+    const { root } = await loadViteRoot({
+      api: vite,
+      command: "build",
+      configPath: viteConfigPath,
+    });
+    await vite.build({ configFile: viteConfigPath, root });
+  }
+  const server = await startOvermuxServer({
+    configPath,
+    ...(host === undefined ? {} : { host }),
+    ...(port === undefined ? {} : { port }),
+  });
+  return { close: server.close, port: server.port, url: server.url };
+};
+
+export const resolveServeLogin = (
+  flags: Pick<ServeFlags, "login" | "noLogin">,
+  environment: Pick<CliEnvironment, "isHumanUser">,
+) => {
+  if (flags.login && flags.noLogin) {
+    throw new Error("Only set one of: --login and --no-login");
+  }
+  return flags.login || (!flags.noLogin && environment.isHumanUser);
+};
+
+const announceServeLogin = async ({
+  createLogin,
+  port,
+  process,
+}: {
+  createLogin: boolean;
+  port: number;
+  process: NodeJS.Process;
+}) => {
+  if (!createLogin) {
+    printLoginFallback(port, process);
+    return;
+  }
+  printLoginGrant({ ...(await issueLoginGrant(port)), output: process });
+};
+
+export const runServe = async ({
+  environment,
+  flags,
+  process,
+}: {
+  environment: Pick<CliEnvironment, "isHumanUser">;
+  flags: ServeFlags;
+  process: NodeJS.Process;
+}) => {
+  if (flags.noBuild && !flags.production) {
+    throw new Error("--no-build requires --production");
+  }
+  const createLogin = resolveServeLogin(flags, environment);
+  const configPath = resolve(flags.config);
+  const { config } = await loadOvermuxConfig({ configPath });
+  if (!config.vite) {
+    throw new Error("Overmux config must define a Vite config path in `vite`");
+  }
+  const viteConfigPath = resolve(dirname(configPath), config.vite);
+  const vite = await loadApplicationVite(viteConfigPath);
+  let runningPromise: Promise<RunningServe>;
+  if (flags.production) {
+    if (!config.productionWebAssetsDir) {
+      throw new Error(
+        "Overmux config must define `productionWebAssetsDir` for production serving",
+      );
+    }
+    runningPromise = startProductionServer({
+      configPath,
+      host: flags.host,
+      noBuild: flags.noBuild ?? false,
+      port: flags.port,
+      productionWebAssetsDir: resolve(
+        dirname(configPath),
+        config.productionWebAssetsDir,
+      ),
+      vite,
+      viteConfigPath,
+    });
+  } else {
+    runningPromise = startDevelopmentServer({
+      configPath,
+      host: flags.host,
+      port: flags.port,
+      shouldWatch: config.watch ?? true,
+      vite,
+      viteConfigPath,
+    });
+  }
+  const unregisterShutdown = registerShutdown(runningPromise, process);
+  let running: RunningServe | undefined;
+  try {
+    running = await runningPromise;
+    process.stdout.write(
+      `Overmux listening on ${config.auth.origins?.[0] ?? running.url}\n`,
+    );
+    await announceServeLogin({ createLogin, port: running.port, process });
+  } catch (cause) {
+    unregisterShutdown();
+    await running?.close().catch(() => undefined);
+    throw cause;
+  }
+};
+
+function runServeCommand(this: CliCommandContext, flags: ServeFlags) {
+  return runServe({
+    environment: this.environment,
+    flags,
+    process: this.process,
+  });
+}
+
+export const serveCommand = buildCommand({
+  func: runServeCommand,
+  parameters: {
+    aliases: { c: "config" },
+    flags: {
+      config: {
+        brief: "Configuration file",
+        default: getDefaultConfigPath(),
+        kind: "parsed",
+        parse: String,
+        placeholder: "path",
+      },
+      host: {
+        brief: "Override the public listener host",
+        kind: "parsed",
+        optional: true,
+        parse: String,
+        placeholder: "host",
+      },
+      login: {
+        brief: "Create a browser login grant after startup",
+        kind: "boolean",
+        optional: true,
+        withNegated: false,
+      },
+      noBuild: {
+        brief: "Serve existing production assets without building",
+        kind: "boolean",
+        optional: true,
+      },
+      noLogin: {
+        brief: "Do not create a browser login grant after startup",
+        kind: "boolean",
+        optional: true,
+        withNegated: false,
+      },
+      port: {
+        brief: "Override the public listener port",
+        kind: "parsed",
+        optional: true,
+        parse: (value) => {
+          const port = parsePort(value);
+          if (port instanceof Error) {
+            throw port;
+          }
+          return port;
+        },
+        placeholder: "port",
+      },
+      production: {
+        brief: "Build and serve the production web application",
+        kind: "boolean",
+        optional: true,
+      },
+    },
+  },
+  docs: {
+    brief: "Serve the Overmux web application",
+    fullDescription:
+      "Starts private Vite behind the authenticated Overmux gateway, or builds and serves production assets with --production.",
+  },
+});

package/src/internal/cli/environment.ts

@@ -0,0 +1,54 @@
+import type { CommandContext } from "@stricli/core";
+import { determineAgent } from "@vercel/detect-agent";
+import * as ciInfo from "ci-info";
+
+export type CliEnvironment = {
+  readonly agent?: string;
+  readonly isAgent: boolean;
+  readonly isCI: boolean;
+  readonly isHumanUser: boolean;
+  readonly isInteractiveTerminal: boolean;
+};
+
+export type CliCommandContext = CommandContext & {
+  readonly environment: CliEnvironment;
+  readonly process: NodeJS.Process;
+};
+
+type CliEnvironmentSignals = {
+  readonly agent?: string;
+  readonly isAgent: boolean;
+  readonly isCI: boolean;
+  readonly stdinIsTTY?: boolean;
+  readonly stdoutIsTTY?: boolean;
+};
+
+export const classifyCliEnvironment = ({
+  agent,
+  isAgent,
+  isCI,
+  stdinIsTTY,
+  stdoutIsTTY,
+}: CliEnvironmentSignals): CliEnvironment => {
+  const isInteractiveTerminal = stdinIsTTY === true && stdoutIsTTY === true;
+  return {
+    agent,
+    isAgent,
+    isCI,
+    isHumanUser: isInteractiveTerminal && !isCI && !isAgent,
+    isInteractiveTerminal,
+  };
+};
+
+export const detectCliEnvironment = async (
+  process: Pick<NodeJS.Process, "stdin" | "stdout"> = globalThis.process,
+): Promise<CliEnvironment> => {
+  const detectedAgent = await determineAgent();
+  return classifyCliEnvironment({
+    agent: detectedAgent.agent?.name,
+    isAgent: detectedAgent.isAgent,
+    isCI: ciInfo.isCI,
+    stdinIsTTY: process.stdin.isTTY,
+    stdoutIsTTY: process.stdout.isTTY,
+  });
+};

package/src/internal/cli/login.ts

@@ -0,0 +1,46 @@
+import type { LoginGrant } from "../server/auth/auth-service";
+import {
+  discoverInstance,
+  sendControlRequest,
+} from "../server/auth/instance-control";
+
+type CliOutput = Pick<NodeJS.Process, "stderr" | "stdout">;
+
+export const issueLoginGrant = async (port?: number) => {
+  const instance = await discoverInstance(port);
+  const response = await sendControlRequest(instance, { type: "create-login" });
+  return { login: response.login, port: instance.port };
+};
+
+export const printLoginFallback = (port: number, { stdout }: CliOutput) => {
+  stdout.write(`Login with \`overmux auth login --port ${port}\`\n`);
+};
+
+export const printLoginGrant = ({
+  login,
+  output,
+  port,
+}: {
+  login: LoginGrant;
+  output: CliOutput;
+  port: number;
+}) => {
+  const expiresIn = Math.max(
+    0,
+    Math.ceil((Date.parse(login.expiresAt) - Date.now()) / 60_000),
+  );
+  output.stdout.write(
+    [
+      `Code: ${login.code}`,
+      ...login.urls.map((url) => `Open: ${url}`),
+      "This single-use grant authenticates one origin. Create another grant to authenticate another origin.",
+      "Enter the code on the login page shown by an unauthenticated Overmux origin.",
+      `Expires at ${login.expiresAt} (in ${expiresIn} minutes).`,
+      `Need another grant? Run \`overmux auth login --port ${port}\`.`,
+      "",
+    ].join("\n"),
+  );
+  output.stderr.write(
+    "The login URL is a temporary credential; avoid sharing terminal output or screenshots.\n",
+  );
+};