overmux 0.0.1 → 0.0.2

package/docs/400-reference/400-cli/500-ai-context.md

@@ -0,0 +1,102 @@
+---
+title: "overmux ai context"
+description: "Set up your coding agent and configure its Overmux context"
+---
+
+# `overmux ai context`
+
+Print version-aware Overmux guidance for coding agents as Markdown.
+
+## Usage
+
+```text
+overmux ai context [--config path]
+```
+
+## Set up your coding agent
+
+Add a short instruction that tells your agent how to load the context when it needs Overmux guidance:
+
+<CodeBlockTabs defaultValue="agents">
+  <CodeBlockTabsList>
+    <CodeBlockTabsTrigger value="agents">AGENTS.md</CodeBlockTabsTrigger>
+    <CodeBlockTabsTrigger value="claude">CLAUDE.md</CodeBlockTabsTrigger>
+  </CodeBlockTabsList>
+  <CodeBlockTab value="agents">
+
+```bash
+echo 'Run `overmux ai context` for help configuring Overmux.' >> AGENTS.md
+```
+
+  </CodeBlockTab>
+  <CodeBlockTab value="claude">
+
+```bash
+echo 'Run `overmux ai context` for help configuring Overmux.' >> CLAUDE.md
+```
+
+  </CodeBlockTab>
+</CodeBlockTabs>
+
+## Configure context snippets
+
+Set `aiContextSnippets` in `$XDG_CONFIG_HOME/overmux/overmux.config.ts` to choose the guidance included in the command output:
+
+```ts
+import {
+  coreAiContextSnippets,
+  defineOvermuxConfig,
+} from "overmux";
+
+export default defineOvermuxConfig({
+  aiContextSnippets: coreAiContextSnippets,
+  // ...
+});
+```
+
+When `aiContextSnippets` is omitted, Overmux uses `defaultAiContextSnippets`. Set it to an empty array to emit no context.
+
+## Options
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `--config <path>, -c <path>` | Configuration file | `$XDG_CONFIG_HOME/overmux/overmux.config.ts` |
+
+## Preset groups
+
+| Export | Included snippets |
+| --- | --- |
+| `defaultAiContextSnippets` | `package-source`, `tech-stack-recommendations` |
+| `coreAiContextSnippets` | `package-source` |
+
+## Snippet reference
+
+### `package-source`
+
+Export: `packageSourceSnippet`
+
+Included in the core and default presets. Tells agents to inspect the documentation and TypeScript source shipped in installed Overmux packages so their guidance matches the versions used by the application.
+
+### `tech-stack-recommendations`
+
+Export: `techStackRecommendationsSnippet`
+
+Included in the default preset. Recommends pnpm, TanStack Router, shadcn/ui, and Zod while deferring to the application's established stack.
+
+You can compose an explicit selection from the individual exports:
+
+```ts
+import {
+  defineOvermuxConfig,
+  packageSourceSnippet,
+  techStackRecommendationsSnippet,
+} from "overmux";
+
+export default defineOvermuxConfig({
+  aiContextSnippets: [
+    packageSourceSnippet,
+    techStackRecommendationsSnippet,
+  ],
+  // ...
+});
+```

package/docs/400-reference/400-cli/600-docs.md

@@ -0,0 +1,23 @@
+---
+title: "overmux docs"
+description: "Print the installed documentation directory"
+---
+
+# `overmux docs`
+
+Print the installed documentation directory.
+
+## Usage
+
+```text
+overmux docs
+```
+
+## Example
+
+```console
+$ overmux docs
+/path/to/project/node_modules/overmux/docs
+```
+
+The command prints the absolute path to the documentation shipped with the installed `overmux` package.

package/docs/400-reference/400-cli/700-desktop.md

@@ -0,0 +1,35 @@
+---
+title: "overmux desktop"
+---
+
+# `overmux desktop`
+
+Install or upgrade the experimental macOS desktop preview. The desktop version is independent from the `overmux` npm package version.
+
+## Install
+
+```sh
+overmux desktop install
+```
+
+This command is available only on macOS arm64 and x64. It selects the newest stable `desktop-v*` GitHub release supporting the current architecture and installs it only at `~/Applications/Overmux.app`. It refuses to overwrite an existing bundle; use `upgrade` instead.
+
+The macOS application is an **experimental unsigned, non-notarized preview**. macOS cannot verify its publisher, compatibility is not guaranteed, and no DMG is published. First install requires interactive confirmation:
+
+```sh
+overmux desktop install --yes
+```
+
+Use `--yes` only when automation has explicitly accepted the unsigned application risk.
+
+## Upgrade
+
+```sh
+overmux desktop upgrade
+```
+
+Upgrade verifies that the existing app has the `com.overmux.desktop` bundle identity before replacing it. A running app is asked to quit; an app that is not running is upgraded normally. The new app is launched, and the previous bundle is restored when replacement or launch fails where practical.
+
+Both commands accept release assets only from the fixed official GitHub repository over HTTPS, verify asset size and `SHA256SUMS`, reject unsafe ZIP paths, validate the staged bundle, ad-hoc sign it if needed, and remove quarantine only from that bundle. They never use `sudo` or write to `/Applications`.
+
+Checksums detect accidental corruption but are not independent publisher authentication because they are hosted with the artifacts. There is no cryptographically signed release manifest in this experimental distribution.

package/docs/500-hosted-pages.md

@@ -0,0 +1,31 @@
+---
+title: Hosted pages
+description: Link to Overmux-owned settings and logout pages.
+---
+
+# Hosted pages
+
+Overmux reserves two authenticated client paths above the user application router:
+
+- `/_overmux/settings` provides notification and session settings.
+- `/_overmux/logout` ends the current session and returns to login.
+
+Use the neutral public constants when linking from userland or host integrations:
+
+```tsx
+import {
+  createOvermuxSettingsPath,
+  overmuxLogoutPath,
+} from "overmux";
+
+const returnTo = `${location.pathname}${location.search}${location.hash}`;
+
+<a href={createOvermuxSettingsPath(returnTo)}>Overmux settings</a>
+<a href={overmuxLogoutPath}>Log out</a>
+```
+
+These are full-document destinations. Do not send them through a userland client router.
+
+`createOvermuxSettingsPath(returnTo)` includes a same-origin application path for **Back to Overmux**. Absolute URLs, protocol-relative URLs, login and API paths, and reserved `/_overmux` paths are discarded. Use `resolveOvermuxReturnTo()` when the validated return path is needed separately.
+
+Browser notification controls live on the settings page. In the Electron desktop app, settings instead explains that delivery uses the desktop app and notification permissions are managed by the operating system.

package/package.json

@@ -1,48 +1,89 @@
 {
   "name": "overmux",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "homepage": "https://github.com/richardgill/overmux",
   "repository": {
     "type": "git",
     "url": "https://github.com/richardgill/overmux",
-    "directory": "packages/overmux"
+    "directory": "packages/runtime/overmux"
   },
   "type": "module",
   "bin": {
     "overmux": "./dist/bin.js"
   },
+  "imports": {
+    "#server-child": "./dist/internal/server/coordinator/server-child.js"
+  },
   "exports": {
-    ".": "./dist/public/core.ts",
-    "./config": "./dist/public/core.ts",
-    "./protocol": "./dist/public/protocol.ts",
-    "./tabs/terminal": "./dist/public/terminal.ts"
+    ".": {
+      "types": "./dist/exports/index.d.ts",
+      "import": "./dist/exports/index.js"
+    },
+    "./client": {
+      "types": "./dist/exports/client.d.ts",
+      "import": "./dist/exports/client.js"
+    },
+    "./server": {
+      "types": "./dist/exports/server.d.ts",
+      "import": "./dist/exports/server.js"
+    }
   },
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/fixtures",
+    "!src/**/testing",
+    "README.md",
+    "CHANGELOG.md"
   ],
   "dependencies": {
+    "@hono/node-server": "2.1.1",
+    "@stricli/core": "1.3.0",
+    "@tanstack/react-query": "5.90.12",
+    "@vercel/detect-agent": "1.2.5",
+    "ci-info": "4.4.0",
+    "es-module-lexer": "1.7.0",
+    "hono": "4.12.23",
+    "httpxy": "0.5.5",
     "jiti": "2.7.0",
-    "zod": "4.4.3"
+    "typescript": "5.9.3",
+    "web-push": "3.6.7",
+    "ws": "8.21.3",
+    "zod": "4.4.3",
+    "@overmux/keybindings": "0.0.2"
   },
   "devDependencies": {
+    "@playwright/test": "1.58.0",
     "@types/node": "22.19.20",
-    "tsx": "4.22.4",
-    "vite": "8.0.0",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "@types/web-push": "3.6.4",
+    "@types/ws": "8.18.1",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "vite": "8.2.2",
     "vitest": "4.1.10",
-    "@overmux/core": "0.0.0",
-    "@overmux/tabs": "0.0.0",
-    "@overmux/server": "0.0.0",
-    "@overmux/web": "0.0.0",
-    "@overmux/tsconfig": "0.0.0"
+    "@overmux/lib": "0.0.1",
+    "@overmux/shared": "0.0.1",
+    "@overmux/tsconfig": "0.0.1"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "vite": "^8.2.1"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "vite build && tsx scripts/copy-web-assets.ts && tsx scripts/copy-public-api.ts",
-    "dev": "tsx src/bin.ts --config ../../fixtures/overmux.config.ts",
-    "start": "node dist/bin.js",
+    "build": "rm -rf dist && vite build && vite build --config vite.auth.config.ts && vp pack && node scripts/clean-declarations.ts && node scripts/add-client-styles.mjs && cp -R docs dist/docs",
+    "dev": "pnpm run dev:cli",
+    "dev:cli": "node --import jiti/register src/internal/cli/bin.ts serve",
+    "serve": "node dist/bin.js serve",
     "test": "vitest run",
+    "test:e2e": "node --import jiti/register scripts/run-playwright.ts",
     "typecheck": "tsc --noEmit"
   }
 }

package/src/internal/cli/app.ts

@@ -0,0 +1,72 @@
+import {
+  buildApplication,
+  buildRouteMap,
+  help,
+  run,
+  text_en,
+} from "@stricli/core";
+
+import { createAiRoute } from "./commands/ai";
+import { authRoute } from "./commands/auth";
+import { checkCommand } from "./commands/check";
+import { callCommand } from "./commands/call";
+import { desktopRoute } from "./commands/desktop";
+import { createDocsCommand, resolveInstalledDocsRoot } from "./commands/docs";
+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" },
+      routes: {
+        ai: createAiRoute(process),
+        auth: authRoute,
+        check: checkCommand,
+        call: callCommand,
+        desktop: desktopRoute,
+        docs: createDocsCommand({
+          docsRoot: resolveInstalledDocsRoot(import.meta.url),
+          output: process.stdout,
+        }),
+        serve: serveCommand,
+      },
+    }),
+    {
+      name: "overmux",
+      localization: {
+        text: {
+          ...text_en,
+          commandErrorResult: (error) => error.message,
+          exceptionWhileRunningCommand: (error) =>
+            error instanceof Error ? error.message : String(error),
+        },
+      },
+      scanner: {
+        allowArgumentEscapeSequence: true,
+        caseStyle: "allow-kebab-for-camel",
+      },
+    },
+    {
+      help: help({
+        brief: "Show this help",
+        defaultForRouteMap: true,
+        formatting: {
+          caseStyle: "convert-camel-to-kebab",
+          onlyRequiredInUsageLine: false,
+          useAliasInUsageLine: false,
+        },
+      }),
+    },
+  );
+
+export const runCli = async (
+  args: readonly string[],
+  process = globalThis.process,
+) => {
+  const environment = await detectCliEnvironment(process);
+  return run(createCliApp(process), args[0] === "--" ? args.slice(1) : args, {
+    environment,
+    process,
+  });
+};

package/src/internal/cli/bin.ts

@@ -0,0 +1,3 @@
+import { runCli } from "./app";
+
+await runCli(process.argv.slice(2));

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

@@ -0,0 +1,44 @@
+import { loadOvermuxConfig } from "@overmux/shared/node";
+import { buildCommand, buildRouteMap } from "@stricli/core";
+
+import {
+  composeAiContext,
+  defaultAiContextSnippets,
+} from "../../../public/ai-context";
+import { getDefaultConfigPath } from "../../server/paths";
+
+type AiContextFlags = { config: string };
+
+const printAiContext = async (
+  flags: AiContextFlags,
+  process: NodeJS.Process,
+) => {
+  const { config } = await loadOvermuxConfig({ configPath: flags.config });
+  process.stdout.write(
+    composeAiContext(config.aiContextSnippets ?? defaultAiContextSnippets),
+  );
+};
+
+const createAiContextCommand = (process: NodeJS.Process) =>
+  buildCommand({
+    func: (flags: AiContextFlags) => printAiContext(flags, process),
+    parameters: {
+      aliases: { c: "config" },
+      flags: {
+        config: {
+          brief: "Configuration file",
+          default: getDefaultConfigPath(),
+          kind: "parsed",
+          parse: String,
+          placeholder: "path",
+        },
+      },
+    },
+    docs: { brief: "Print the configured Overmux AI context" },
+  });
+
+export const createAiRoute = (process: NodeJS.Process) =>
+  buildRouteMap({
+    docs: { brief: "Print Overmux AI context" },
+    routes: { context: createAiContextCommand(process) },
+  });

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

@@ -0,0 +1,195 @@
+import { buildCommand, buildRouteMap } from "@stricli/core";
+
+import {
+  discoverInstance,
+  sendControlRequest,
+} from "../../server/auth/instance-control";
+import type { CliCommandContext } from "../environment";
+import { issueLoginGrant, printLoginGrant } from "../login";
+import { parsePort } from "../parse-port";
+
+type InstanceFlags = { port?: string };
+type JsonInstanceFlags = InstanceFlags & { json?: boolean };
+type LoginFlags = JsonInstanceFlags & { code?: boolean; url?: boolean };
+type RevokeFlags = JsonInstanceFlags & { all?: boolean };
+
+const selectedPort = (portValue?: string) => {
+  const port = portValue === undefined ? undefined : parsePort(portValue);
+  if (port instanceof Error) {
+    throw port;
+  }
+  return port;
+};
+
+const selectedInstance = (portValue?: string) =>
+  discoverInstance(selectedPort(portValue));
+
+const printJson = (value: unknown) =>
+  process.stdout.write(`${JSON.stringify(value)}\n`);
+
+const runLogin = async (flags: LoginFlags, process: NodeJS.Process) => {
+  const formats = [flags.code, flags.url, flags.json].filter(Boolean).length;
+  if (formats > 1) {
+    throw new Error("Only set one of: --code, --url, and --json");
+  }
+  const issued = await issueLoginGrant(selectedPort(flags.port));
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify(issued.login)}\n`);
+    return;
+  }
+  if (flags.code) {
+    process.stdout.write(`${issued.login.code}\n`);
+    return;
+  }
+  if (flags.url) {
+    process.stdout.write(`${issued.login.urls[0]}\n`);
+    return;
+  }
+  printLoginGrant({ ...issued, output: process });
+};
+
+function runLoginCommand(this: CliCommandContext, flags: LoginFlags) {
+  return runLogin(flags, this.process);
+}
+
+const instanceFlags = {
+  port: {
+    brief: "Running local server port",
+    kind: "parsed" as const,
+    optional: true as const,
+    parse: String,
+  },
+};
+
+export const authLoginCommand = buildCommand({
+  func: runLoginCommand,
+  parameters: {
+    flags: {
+      code: {
+        brief: "Print only the login code",
+        kind: "boolean",
+        optional: true,
+      },
+      json: {
+        brief: "Print machine-readable JSON",
+        kind: "boolean",
+        optional: true,
+      },
+      ...instanceFlags,
+      url: {
+        brief: "Print only the login URL",
+        kind: "boolean",
+        optional: true,
+      },
+    },
+    positional: { kind: "tuple", parameters: [] },
+  },
+  docs: { brief: "Create a single-use browser login grant" },
+});
+
+const runList = async (flags: JsonInstanceFlags) => {
+  const instance = await selectedInstance(flags.port);
+  const response = await sendControlRequest(instance, {
+    type: "list-sessions",
+  });
+  if (flags.json) {
+    printJson({ sessions: response.sessions });
+    return;
+  }
+  if (response.sessions.length === 0) {
+    process.stdout.write("No active sessions.\n");
+    return;
+  }
+  process.stdout.write("ID\tORIGIN\tCREATED\tLAST SEEN\tEXPIRES\n");
+  response.sessions.forEach((session) => {
+    process.stdout.write(
+      `${session.id}\t${session.origin ?? "unknown"}\t${session.createdAt}\t${session.lastSeenAt}\t${session.expiresAt ?? "never"}\n`,
+    );
+  });
+};
+
+export const authListCommand = buildCommand({
+  func: runList,
+  parameters: {
+    flags: {
+      json: {
+        brief: "Print machine-readable JSON",
+        kind: "boolean",
+        optional: true,
+      },
+      ...instanceFlags,
+    },
+    positional: { kind: "tuple", parameters: [] },
+  },
+  docs: { brief: "List active browser sessions" },
+});
+
+const runRevoke = async (flags: RevokeFlags, id?: string) => {
+  if (Boolean(id) === Boolean(flags.all)) {
+    throw new Error("Specify exactly one session ID or --all");
+  }
+  const instance = await selectedInstance(flags.port);
+  if (id) {
+    const response = await sendControlRequest(instance, {
+      id,
+      type: "revoke-session",
+    });
+    if (!response.revoked) {
+      throw new Error(`Session not found: ${id}`);
+    }
+    if (flags.json) {
+      printJson({ revoked: 1 });
+      return;
+    }
+    process.stdout.write(`Revoked session ${id}.\n`);
+    return;
+  }
+  const response = await sendControlRequest(instance, { type: "revoke-all" });
+  if (flags.json) {
+    printJson({ revoked: response.count });
+    return;
+  }
+  process.stdout.write(
+    `Revoked ${response.count} session${response.count === 1 ? "" : "s"}.\n`,
+  );
+};
+
+export const authRevokeCommand = buildCommand({
+  func: runRevoke,
+  parameters: {
+    flags: {
+      all: {
+        brief: "Revoke every active session",
+        kind: "boolean",
+        optional: true,
+      },
+      json: {
+        brief: "Print machine-readable JSON",
+        kind: "boolean",
+        optional: true,
+      },
+      ...instanceFlags,
+    },
+    positional: {
+      kind: "tuple",
+      parameters: [
+        {
+          brief: "Session ID",
+          optional: true,
+          parse: String,
+          placeholder: "id",
+        },
+      ],
+    },
+  },
+  docs: { brief: "Revoke browser authentication sessions" },
+});
+
+export const authRoute = buildRouteMap({
+  docs: { brief: "Manage CLI-issued browser authentication" },
+  routes: {
+    list: authListCommand,
+    login: authLoginCommand,
+    revoke: authRevokeCommand,
+  },
+});