overmux 0.0.1 → 0.0.3

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/init-template.ts

@@ -0,0 +1,146 @@
+export type InitToolchain = "mise" | "pnpm";
+
+export const initScaffoldPaths = [
+  ".gitignore",
+  "AGENTS.md",
+  "CLAUDE.md",
+  "mise.toml",
+  "package.json",
+  "pnpm-lock.yaml",
+  "overmux.config.ts",
+  "src/server/index.ts",
+  "src/ui/app.tsx",
+  "src/ui/index.html",
+  "src/ui/main.tsx",
+  "src/ui/styles.css",
+  "vite.config.ts",
+] as const;
+
+const packageJson = (overmuxVersion: string) =>
+  `${JSON.stringify(
+    {
+      name: "my-overmux",
+      private: true,
+      type: "module",
+      scripts: {
+        build: "vite build",
+        check: "overmux check --config ./overmux.config.ts",
+        dev: "overmux serve --config ./overmux.config.ts",
+      },
+      dependencies: {
+        overmux: overmuxVersion,
+        react: "^19.0.0",
+        "react-dom": "^19.0.0",
+      },
+      devDependencies: {
+        "@types/react": "^19.0.0",
+        "@types/react-dom": "^19.0.0",
+        "@vitejs/plugin-react": "^6.0.0",
+        typescript: "^5.9.0",
+        vite: "^8.0.0",
+      },
+    },
+    null,
+    2,
+  )}\n`;
+
+export const createInitScaffold = ({
+  overmuxVersion,
+  toolchain,
+}: {
+  overmuxVersion: string;
+  toolchain: InitToolchain;
+}): Readonly<Record<string, string>> => ({
+  ".gitignore": "node_modules\ndist\n",
+  "AGENTS.md":
+    "Immediately run `overmux ai context` for documentation about Overmux.\n",
+  "CLAUDE.md": "@AGENTS.md\n",
+  ...(toolchain === "mise"
+    ? {
+        "mise.toml": `[tools]
+node = "22"
+pnpm = "10"
+"npm:overmux" = "${overmuxVersion}"
+`,
+      }
+    : {}),
+  "package.json": packageJson(overmuxVersion),
+  "overmux.config.ts": `import { defineOvermuxConfig } from "overmux";
+
+import server from "./src/server/index";
+
+export default defineOvermuxConfig({
+  auth: { mode: "cli-login" },
+  productionWebAssetsDir: "./dist",
+  server,
+  vite: "./vite.config.ts",
+});
+`,
+  "src/server/index.ts": `import { defineOvermuxServer } from "overmux";
+
+export default defineOvermuxServer({ resources: {} });
+`,
+  "src/ui/app.tsx": `import { defineOvermuxClient } from "overmux/client";
+
+const App = () => <main>Overmux is running.</main>;
+
+export default defineOvermuxClient({
+  commands: {},
+  component: App,
+});
+`,
+  "src/ui/index.html": `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Overmux</title>
+  </head>
+  <body>
+    <div id="root">
+      <p>Loading Overmux…</p>
+      <button type="button" onclick="location.reload()">Retry</button>
+    </div>
+    <script type="module" src="/main.tsx"></script>
+  </body>
+</html>
+`,
+  "src/ui/main.tsx": `import { OvermuxHost } from "overmux/client";
+import { createRoot } from "react-dom/client";
+
+import definition from "./app";
+import "./styles.css";
+
+const root = document.querySelector("#root");
+if (!root) {
+  throw new Error("Missing root element");
+}
+
+createRoot(root).render(<OvermuxHost definition={definition} />);
+`,
+  "src/ui/styles.css": `:root {
+  color: #f5f5f5;
+  background: #111;
+  font-family: system-ui, sans-serif;
+}
+
+body {
+  margin: 0;
+}
+
+main {
+  display: grid;
+  min-height: 100vh;
+  place-items: center;
+}
+`,
+  "vite.config.ts": `import viteReact from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  build: { emptyOutDir: true, outDir: "../../dist" },
+  plugins: [viteReact()],
+  root: "src/ui",
+});
+`,
+});

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

@@ -0,0 +1,267 @@
+import { buildCommand } from "@stricli/core";
+import { spawnSync } from "node:child_process";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+import { getOvermuxPaths } from "../../server/paths";
+import {
+  createInitScaffold,
+  initScaffoldPaths,
+  type InitToolchain,
+} from "./init-template";
+
+const miseActivationDocs =
+  "https://mise.jdx.dev/getting-started.html#activate-mise";
+type CommandResult = {
+  error?: NodeJS.ErrnoException;
+  status: number | null;
+  stderr: string;
+  stdout: string;
+};
+
+export type InitDependencies = {
+  directory: string;
+  getLatestOvermuxVersion: () => Promise<string>;
+  runCommand: (
+    command: string,
+    args: readonly string[],
+    options?: { cwd?: string },
+  ) => CommandResult;
+  stderr: { write: (text: string) => unknown };
+  stdout: { write: (text: string) => unknown };
+};
+
+const runCommand: InitDependencies["runCommand"] = (command, args, options) => {
+  const result = spawnSync(command, args, {
+    cwd: options?.cwd,
+    encoding: "utf8",
+    maxBuffer: 20 * 1024 * 1024,
+  });
+  return {
+    error: result.error,
+    status: result.status,
+    stderr: result.stderr ?? "",
+    stdout: result.stdout ?? "",
+  };
+};
+
+const getLatestOvermuxVersion = async () => {
+  const response = await fetch("https://registry.npmjs.org/overmux/latest", {
+    headers: { accept: "application/json" },
+  });
+  if (!response.ok) {
+    throw new Error(
+      `Could not resolve the latest Overmux version: npm returned ${response.status}`,
+    );
+  }
+  const body: unknown = await response.json();
+  const version =
+    typeof body === "object" && body !== null && "version" in body
+      ? body.version
+      : undefined;
+  if (typeof version !== "string") {
+    throw new Error("Could not resolve the latest Overmux version from npm");
+  }
+  return version;
+};
+
+const commandExists = (result: CommandResult) =>
+  result.error?.code !== "ENOENT";
+
+const isMiseActivated = (dependencies: InitDependencies) => {
+  const doctor = dependencies.runCommand("mise", ["doctor", "--json"]);
+  if (doctor.status !== 0) {
+    return false;
+  }
+  try {
+    const report: unknown = JSON.parse(doctor.stdout);
+    return (
+      typeof report === "object" &&
+      report !== null &&
+      "activated" in report &&
+      report.activated === true
+    );
+  } catch {
+    return false;
+  }
+};
+
+const detectToolchain = (dependencies: InitDependencies): InitToolchain => {
+  const mise = dependencies.runCommand("mise", ["--version"]);
+  if (commandExists(mise)) {
+    if (mise.status !== 0) {
+      throw new Error(
+        `Mise could not be validated. Activate mise and try again. ${miseActivationDocs}`,
+      );
+    }
+    if (!isMiseActivated(dependencies)) {
+      throw new Error(
+        `Mise must be activated in your shell before running overmux init. ${miseActivationDocs}`,
+      );
+    }
+    return "mise";
+  }
+
+  const pnpm = dependencies.runCommand("pnpm", ["--version"]);
+  const major = Number.parseInt(pnpm.stdout.trim().split(".")[0] ?? "", 10);
+  if (!commandExists(pnpm) || pnpm.status !== 0 || !Number.isFinite(major)) {
+    throw new Error("pnpm 10 or newer is required when mise is not installed");
+  }
+  if (major < 10) {
+    throw new Error(
+      `pnpm 10 or newer is required when mise is not installed (found ${pnpm.stdout.trim()})`,
+    );
+  }
+  return "pnpm";
+};
+
+const findCollisions = (directory: string) => {
+  if (existsSync(directory) && !statSync(directory).isDirectory()) {
+    return [directory];
+  }
+  return initScaffoldPaths.filter((path) => existsSync(join(directory, path)));
+};
+
+const writeScaffold = (
+  directory: string,
+  files: Readonly<Record<string, string>>,
+) => {
+  Object.entries(files).forEach(([path, content]) => {
+    const destination = join(directory, path);
+    mkdirSync(dirname(destination), { recursive: true });
+    writeFileSync(destination, content);
+  });
+};
+
+const runProjectCommand = ({
+  args,
+  command,
+  cwd,
+  dependencies,
+}: {
+  args: readonly string[];
+  command: string;
+  cwd: string;
+  dependencies: InitDependencies;
+}) => {
+  const result = dependencies.runCommand(command, args, { cwd });
+  dependencies.stdout.write(result.stdout);
+  dependencies.stderr.write(result.stderr);
+  if (result.error || result.status !== 0) {
+    throw new Error(`Command failed: ${command} ${args.join(" ")}`);
+  }
+};
+
+const pnpmCommands = [
+  ["install", "--ignore-workspace"],
+  ["exec", "overmux", "check", "--config", "./overmux.config.ts"],
+] as const;
+
+const installAndCheck = ({
+  directory,
+  dependencies,
+  toolchain,
+}: {
+  directory: string;
+  dependencies: InitDependencies;
+  toolchain: InitToolchain;
+}) => {
+  const context = { cwd: directory, dependencies };
+  if (toolchain === "mise") {
+    runProjectCommand({
+      ...context,
+      command: "mise",
+      args: ["install", "node@22", "pnpm@10", "--yes"],
+    });
+  }
+  pnpmCommands.forEach((args) =>
+    runProjectCommand({
+      ...context,
+      command: toolchain,
+      args:
+        toolchain === "mise"
+          ? ["exec", "node@22", "pnpm@10", "--", "pnpm", ...args]
+          : args,
+    }),
+  );
+};
+
+const mergeScaffold = (source: string, target: string) => {
+  if (!existsSync(target)) {
+    renameSync(source, target);
+    return;
+  }
+  cpSync(source, target, {
+    errorOnExist: true,
+    force: false,
+    recursive: true,
+  });
+};
+
+export const initializeOvermux = async (dependencies: InitDependencies) => {
+  const directory = resolve(dependencies.directory);
+  const collisions = findCollisions(directory);
+  if (collisions.length > 0) {
+    throw new Error(
+      `Refusing to overwrite existing files:\n${collisions.map((path) => `- ${path}`).join("\n")}`,
+    );
+  }
+
+  const toolchain = detectToolchain(dependencies);
+  const overmuxVersion = await dependencies.getLatestOvermuxVersion();
+  const files = createInitScaffold({ overmuxVersion, toolchain });
+  const parent = dirname(directory);
+  mkdirSync(parent, { recursive: true });
+  const stagingDirectory = mkdtempSync(join(parent, ".overmux-init-"));
+
+  try {
+    // Defer the npm tool entry so dependency installation uses the project-local Overmux binary.
+    const installFiles = Object.fromEntries(
+      Object.entries(files).filter(([path]) => path !== "mise.toml"),
+    );
+    writeScaffold(stagingDirectory, installFiles);
+    installAndCheck({
+      directory: stagingDirectory,
+      dependencies,
+      toolchain,
+    });
+    if (!existsSync(join(stagingDirectory, "pnpm-lock.yaml"))) {
+      throw new Error("pnpm install did not generate pnpm-lock.yaml");
+    }
+    if (files["mise.toml"]) {
+      writeFileSync(join(stagingDirectory, "mise.toml"), files["mise.toml"]);
+    }
+    mergeScaffold(stagingDirectory, directory);
+  } finally {
+    rmSync(stagingDirectory, { force: true, recursive: true });
+  }
+
+  dependencies.stdout.write(
+    `Initialized Overmux in ${directory}\nNext: overmux serve\n`,
+  );
+};
+
+export const createInitCommand = (process: NodeJS.Process) =>
+  buildCommand({
+    func: () =>
+      initializeOvermux({
+        directory: getOvermuxPaths({ environment: process.env }).configDir,
+        getLatestOvermuxVersion,
+        runCommand,
+        stderr: process.stderr,
+        stdout: process.stdout,
+      }),
+    parameters: { flags: {} },
+    docs: {
+      brief: "Create a minimal Overmux application",
+    },
+  });

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

@@ -0,0 +1,15 @@
+// This namespace groups deliberate integration lifecycle commands by verb.
+// Only install zellij exists now; the parser shape leaves later lifecycle verbs explicit.
+import { buildRouteMap } from "@stricli/core";
+
+import { zellijInstallCommand } from "./zellij-install";
+
+const installIntegrationCommand = buildRouteMap({
+  docs: { brief: "Install an Overmux integration" },
+  routes: { zellij: zellijInstallCommand },
+});
+
+export const integrationCommand = buildRouteMap({
+  docs: { brief: "Manage Overmux integrations" },
+  routes: { install: installIntegrationCommand },
+});