overmux 0.0.2 → 0.0.3

package/docs/200-getting-started/100-install-and-run-overmux.md

@@ -37,7 +37,7 @@ Once the CLI is installed, create your Overmux setup:
 overmux init
 ```
 
-This creates your setup in `$XDG_CONFIG_HOME/overmux`. Read more about the Overmux [project structure](../300-fundamentals/100-project-structure.md).
+This validates your toolchain, creates a minimal application in `$XDG_CONFIG_HOME/overmux`, installs its dependencies, and checks the result. Existing scaffold files are left unchanged. Read more in the [`overmux init` reference](../400-reference/400-cli/050-init.md) and [project structure](../300-fundamentals/100-project-structure.md).
 
 ## Start the server
 
@@ -48,4 +48,3 @@ overmux serve
 Open Overmux in your browser to confirm it works.
 
 To configure hosts and ports, see [Configuration](../300-fundamentals/200-configuration.md).
-

package/docs/300-fundamentals/100-project-structure.md

@@ -1,3 +1,23 @@
 ---
 title: Project Structure
 ---
+
+`overmux init` creates this minimal userland application:
+
+```text
+.gitignore
+mise.toml               Mise installations only
+package.json
+pnpm-lock.yaml
+overmux.config.ts       authentication, server, Vite, and production settings
+src/server/index.ts     trusted resources, streams, and operations
+src/ui/app.tsx          browser application definition
+src/ui/index.html       browser document
+src/ui/main.tsx         React and Overmux host entry point
+src/ui/styles.css       application styles
+vite.config.ts          browser development and production build configuration
+```
+
+The server and UI are separate trust boundaries. `src/server/index.ts` runs as trusted Node.js code. Files under `src/ui` run in the browser and communicate with the server through Overmux's public APIs.
+
+The generated application has no shared directory. Add browser-safe shared schemas only when both sides need them.

package/docs/400-reference/300-client-api.md

@@ -1,3 +1,20 @@
 ---
 title: Client API
 ---
+
+## Clipboard
+
+```ts
+import { readClipboardText, writeClipboardText } from "overmux/client";
+
+await writeClipboardText("Text to copy");
+const text = await readClipboardText();
+```
+
+`readClipboardText(): Promise<string>` reads the system clipboard through `navigator.clipboard.readText()`. It never reads through the desktop bridge.
+
+`writeClipboardText(text: string): Promise<void>` uses Overmux's version-1 desktop write bridge when present, otherwise `navigator.clipboard.writeText()`. Desktop writes are fire-and-forget: resolution confirms dispatch, not completion or acceptance by the host. Existing host origin and active-frame checks still apply.
+
+Both reject on unavailable browser APIs, browser permission failures, or synchronous desktop dispatch failures. Browser secure-context, focus, permissions, and user-activation restrictions still apply. These APIs target the system clipboard, not the X11 primary selection. Only read clipboard data you need and trust the source of text you write.
+
+For terminal-program access via OSC 52, use the opt-in factories from `@overmux/xterm/client` rather than wiring platform bridges in application code.

package/docs/400-reference/400-cli/050-init.md

@@ -0,0 +1,17 @@
+---
+title: "overmux init"
+---
+
+# `overmux init`
+
+Create a minimal, runnable Overmux application without prompting.
+
+```sh
+overmux init
+```
+
+The application is created in `$XDG_CONFIG_HOME/overmux`.
+
+The command validates the toolchain before writing files. When Mise is installed, it must be [activated in the shell](https://mise.jdx.dev/getting-started.html#activate-mise); the generated `mise.toml` pins Node 22, pnpm 10, and the latest published Overmux version. Without Mise, pnpm 10 or newer must already be available and `mise.toml` is omitted.
+
+The initializer pins the exact latest published `overmux` version in `package.json`, installs dependencies, generates `pnpm-lock.yaml`, and runs `overmux check`. Existing scaffold files cause the command to fail without changing them. Unrelated files are preserved.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overmux",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "homepage": "https://github.com/richardgill/overmux",
   "repository": {
     "type": "git",
@@ -52,7 +52,7 @@
     "web-push": "3.6.7",
     "ws": "8.21.3",
     "zod": "4.4.3",
-    "@overmux/keybindings": "0.0.2"
+    "@overmux/keybindings": "0.0.3"
   },
   "devDependencies": {
     "@playwright/test": "1.58.0",

package/src/internal/cli/app.ts

@@ -12,13 +12,15 @@ import { checkCommand } from "./commands/check";
 import { callCommand } from "./commands/call";
 import { desktopRoute } from "./commands/desktop";
 import { createDocsCommand, resolveInstalledDocsRoot } from "./commands/docs";
+import { createInitCommand } from "./commands/init";
+import { integrationCommand } from "./commands/integration";
 import { serveCommand } from "./commands/serve";
 import { detectCliEnvironment, type CliCommandContext } from "./environment";
 
 export const createCliApp = (process = globalThis.process) =>
   buildApplication<CliCommandContext>(
     buildRouteMap<string, CliCommandContext>({
-      docs: { brief: "Serve, validate, or invoke Overmux operations" },
+      docs: { brief: "Initialize and manage Overmux applications" },
       routes: {
         ai: createAiRoute(process),
         auth: authRoute,
@@ -29,6 +31,8 @@ export const createCliApp = (process = globalThis.process) =>
           docsRoot: resolveInstalledDocsRoot(import.meta.url),
           output: process.stdout,
         }),
+        init: createInitCommand(process),
+        integration: integrationCommand,
         serve: serveCommand,
       },
     }),

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 },
+});

package/src/internal/cli/commands/zellij-install.ts

@@ -0,0 +1,96 @@
+// This hard-coded CLI seam delegates installation to the invoking project's integration.
+// It intentionally resolves one known subpath rather than creating a plugin registry.
+import { readFileSync } from "node:fs";
+import { findPackageJSON } from "node:module";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { buildCommand } from "@stricli/core";
+
+type ZellijInstallModule = {
+  installZellij: (options: { session?: string }) => Promise<{
+    artifactPath: string;
+    pluginVersion: string;
+    protocolVersion: number;
+    session: string;
+    sha256: string;
+  }>;
+};
+
+type ZellijInstallDependencies = {
+  cwd: string;
+  importModule: (specifier: string) => Promise<ZellijInstallModule>;
+  resolveInstall: () => string;
+};
+
+const resolveZellijInstall = (cwd: string) => {
+  const projectUrl = pathToFileURL(resolve(cwd, "package.json"));
+  const packagePath = findPackageJSON("@overmux/zellij/install", projectUrl);
+  if (packagePath === undefined) {
+    throw new Error("package not found");
+  }
+  const packageJson = JSON.parse(readFileSync(packagePath, "utf8")) as {
+    exports?: { "./install"?: { import?: unknown } };
+  };
+  const installExport = packageJson.exports?.["./install"]?.import;
+  if (typeof installExport !== "string") {
+    throw new Error("package has no importable ./install export");
+  }
+  return resolve(dirname(packagePath), installExport);
+};
+
+const defaultDependencies = (): ZellijInstallDependencies => {
+  const cwd = process.cwd();
+  return {
+    cwd,
+    importModule: (specifier) =>
+      import(specifier) as Promise<ZellijInstallModule>,
+    resolveInstall: () => resolveZellijInstall(cwd),
+  };
+};
+
+export const executeZellijInstall = async (
+  { session }: { session?: string },
+  dependencies = defaultDependencies(),
+) => {
+  let modulePath: string;
+  try {
+    modulePath = dependencies.resolveInstall();
+  } catch {
+    throw new Error(
+      `Could not resolve @overmux/zellij/install from ${dependencies.cwd}. Add @overmux/zellij to this project, then run the command again.`,
+    );
+  }
+  const integration = await dependencies.importModule(
+    pathToFileURL(modulePath).href,
+  );
+  if (typeof integration.installZellij !== "function") {
+    throw new Error(
+      "@overmux/zellij/install does not export installZellij. Update @overmux/zellij and run the command again.",
+    );
+  }
+  return integration.installZellij({ session });
+};
+
+const runZellijInstall = async ({ session }: { session?: string }) => {
+  const result = await executeZellijInstall({ session });
+  console.log(
+    `Installed Zellij plugin ${result.pluginVersion} (protocol ${result.protocolVersion})\nSession: ${result.session}\nArtifact: ${result.artifactPath}\nSHA-256: ${result.sha256}`,
+  );
+};
+
+export const zellijInstallCommand = buildCommand({
+  docs: { brief: "Install and approve the @overmux/zellij plugin" },
+  func: runZellijInstall,
+  parameters: {
+    flags: {
+      session: {
+        brief: "Target an active Zellij session",
+        kind: "parsed",
+        optional: true,
+        parse: String,
+        placeholder: "name",
+      },
+    },
+  },
+});

package/src/internal/client/clipboard.ts

@@ -0,0 +1,22 @@
+import "./host/desktop-host";
+
+// Reads the system clipboard through the browser, never through the desktop host.
+export const readClipboardText = async (): Promise<string> => {
+  if (!globalThis.navigator?.clipboard?.readText) {
+    throw new Error("Clipboard reading is unavailable in this browser context");
+  }
+  return navigator.clipboard.readText();
+};
+
+// Desktop writes are fire-and-forget: resolution confirms dispatch, not completion.
+export const writeClipboardText = async (text: string): Promise<void> => {
+  const desktopClipboard = globalThis.window?.overmuxHost?.clipboard;
+  if (desktopClipboard?.version === 1) {
+    desktopClipboard.writeText(text);
+    return;
+  }
+  if (!globalThis.navigator?.clipboard?.writeText) {
+    throw new Error("Clipboard writing is unavailable in this browser context");
+  }
+  await navigator.clipboard.writeText(text);
+};

package/src/internal/client/host/desktop-host.ts

@@ -0,0 +1,12 @@
+type DesktopHost = {
+  clipboard?: { writeText: (text: string) => void; version: 1 };
+  notifications?: { show: (notification: unknown) => void; version: 1 };
+};
+
+declare global {
+  interface Window {
+    overmuxHost?: DesktopHost;
+  }
+}
+
+export {};