overmux 0.0.3 → 0.0.5

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

@@ -0,0 +1,128 @@
+---
+title: "`overmux docs`"
+---
+
+Overmux documentation and AI context commands
+
+## `overmux docs path`
+
+`overmux docs path` prints the installed Overmux CLI’s absolute documentation path.
+
+```console
+$ overmux docs path
+/path/to/somewhere/node_modules/overmux/docs
+```
+
+## `overmux docs ai-context`
+
+`overmux docs ai-context` prints `CLAUDE.md`/`AGENTS.md` guidance for coding agents.
+
+### Usage
+
+```text
+overmux docs ai-context
+```
+
+Prints the selected snippets shown in [available snippets](#available-snippets).
+
+### Set up your coding agent
+
+Tell your agent how to load Overmux guidance using `overmux docs ai-context`.
+
+<CodeBlockTabs defaultValue="agents">
+  <CodeBlockTabsList>
+    <CodeBlockTabsTrigger value="agents">AGENTS.md</CodeBlockTabsTrigger>
+    <CodeBlockTabsTrigger value="claude">CLAUDE.md</CodeBlockTabsTrigger>
+  </CodeBlockTabsList>
+  <CodeBlockTab value="agents">
+
+```bash
+echo 'Run `overmux docs ai-context` for help configuring Overmux.' >> AGENTS.md
+```
+
+  </CodeBlockTab>
+  <CodeBlockTab value="claude">
+
+```bash
+echo 'Run `overmux docs ai-context` for help configuring Overmux.' >> CLAUDE.md
+```
+
+  </CodeBlockTab>
+</CodeBlockTabs>
+
+### Configure context snippets
+
+Use `aiContextSnippets` in `overmux.config.ts` to select which snippets `overmux docs ai-context` prints.
+
+```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.
+
+You can compose an explicit selection from the individual exports:
+
+```ts
+import {
+  defineOvermuxConfig,
+  packageSourceSnippet,
+  techStackRecommendationsSnippet,
+} from "overmux";
+
+export default defineOvermuxConfig({
+  aiContextSnippets: [
+    packageSourceSnippet,
+    techStackRecommendationsSnippet,
+  ],
+  // ...
+});
+```
+
+### Options
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `--config <path>, -c <path>` | Configuration file | `$XDG_CONFIG_HOME/overmux/overmux.config.ts` |
+
+### Snippet presets
+
+[//]: # (BEGIN GENERATED AI CONTEXT PRESETS)
+
+| Export | Included snippets |
+| --- | --- |
+| `defaultAiContextSnippets` | `package-source`, `tech-stack-recommendations` |
+| `coreAiContextSnippets` | `package-source` |
+
+[//]: # (END GENERATED AI CONTEXT PRESETS)
+
+### Available snippets
+
+[//]: # (BEGIN GENERATED AI CONTEXT)
+
+#### `package-source`
+
+```text
+Overmux ships with documentation and TypeScript source.
+
+Run `overmux docs path` to find the installed documentation directory for the Overmux CLI. This prints a documentation directory, not source paths.
+
+Inspect TypeScript source in installed packages, e.g. `node_modules/overmux/src` and `node_modules/@overmux/xterm/src`.
+
+Inspect these files so guidance matches the versions used by the application.
+```
+
+#### `tech-stack-recommendations`
+
+```text
+Prefer pnpm as the package manager, TanStack Router for routing, shadcn/ui for UI components, and Zod for schemas and runtime validation. Follow the application's established stack when it already differs.
+```
+
+[//]: # (END GENERATED AI CONTEXT)

package/{dist/docs/400-reference/400-cli → docs/400-reference/700-cli}/700-desktop.md

@@ -1,9 +1,7 @@
 ---
-title: "overmux desktop"
+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

package/docs/500-hosted-pages.md

@@ -1,6 +1,5 @@
 ---
 title: Hosted pages
-description: Link to Overmux-owned settings and logout pages.
 ---
 
 # Hosted pages

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overmux",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "homepage": "https://github.com/richardgill/overmux",
   "repository": {
     "type": "git",
@@ -65,6 +65,7 @@
     "react-dom": "19.2.3",
     "vite": "8.2.2",
     "vitest": "4.1.10",
+    "@overmux/ai-context": "0.0.1",
     "@overmux/lib": "0.0.1",
     "@overmux/shared": "0.0.1",
     "@overmux/tsconfig": "0.0.1"
@@ -78,7 +79,7 @@
     "access": "public"
   },
   "scripts": {
-    "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",
+    "build": "node ../../../scripts/generate-ai-context-docs.ts && 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",

package/src/internal/cli/app.ts

@@ -6,14 +6,14 @@ import {
   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 { createDocsRoute, resolveInstalledDocsRoot } from "./commands/docs";
 import { createInitCommand } from "./commands/init";
 import { integrationCommand } from "./commands/integration";
+import { createInstanceCommand } from "./commands/instance";
 import { serveCommand } from "./commands/serve";
 import { detectCliEnvironment, type CliCommandContext } from "./environment";
 
@@ -22,17 +22,17 @@ export const createCliApp = (process = globalThis.process) =>
     buildRouteMap<string, CliCommandContext>({
       docs: { brief: "Initialize and manage Overmux applications" },
       routes: {
-        ai: createAiRoute(process),
         auth: authRoute,
         check: checkCommand,
         call: callCommand,
         desktop: desktopRoute,
-        docs: createDocsCommand({
+        docs: createDocsRoute({
           docsRoot: resolveInstalledDocsRoot(import.meta.url),
-          output: process.stdout,
+          process,
         }),
         init: createInitCommand(process),
         integration: integrationCommand,
+        instance: createInstanceCommand(process.stdout),
         serve: serveCommand,
       },
     }),

package/src/internal/cli/commands/docs-ai-context.ts

@@ -0,0 +1,33 @@
+import { loadOvermuxConfig } from "@overmux/shared/node";
+import { buildCommand } from "@stricli/core";
+
+import {
+  composeAiContext,
+  defaultAiContextSnippets,
+} from "../../../public/ai-context";
+import { getDefaultConfigPath } from "../../server/paths";
+
+type AiContextFlags = { config: string };
+
+export const createAiContextCommand = (process: NodeJS.Process) =>
+  buildCommand({
+    func: async (flags: AiContextFlags) => {
+      const { config } = await loadOvermuxConfig({ configPath: flags.config });
+      process.stdout.write(
+        composeAiContext(config.aiContextSnippets ?? defaultAiContextSnippets),
+      );
+    },
+    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" },
+  });

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

@@ -1,8 +1,10 @@
-import { buildCommand } from "@stricli/core";
+import { buildCommand, buildRouteMap } from "@stricli/core";
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { createAiContextCommand } from "./docs-ai-context";
+
 type DocsOutput = { write: (text: string) => unknown };
 
 export const resolveInstalledDocsRoot = (moduleUrl: string) => {
@@ -16,7 +18,7 @@ export const resolveInstalledDocsRoot = (moduleUrl: string) => {
   return resolve(docsRoot);
 };
 
-export const createDocsCommand = ({
+const createDocsPathCommand = ({
   docsRoot,
   output,
 }: {
@@ -32,3 +34,18 @@ export const createDocsCommand = ({
       brief: "Print the installed documentation directory",
     },
   });
+
+export const createDocsRoute = ({
+  docsRoot,
+  process,
+}: {
+  docsRoot: string;
+  process: NodeJS.Process;
+}) =>
+  buildRouteMap({
+    docs: { brief: "Find documentation and print coding-agent guidance" },
+    routes: {
+      path: createDocsPathCommand({ docsRoot, output: process.stdout }),
+      "ai-context": createAiContextCommand(process),
+    },
+  });

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

@@ -53,7 +53,7 @@ export const createInitScaffold = ({
 }): Readonly<Record<string, string>> => ({
   ".gitignore": "node_modules\ndist\n",
   "AGENTS.md":
-    "Immediately run `overmux ai context` for documentation about Overmux.\n",
+    "Immediately run `overmux docs ai-context` for documentation about Overmux.\n",
   "CLAUDE.md": "@AGENTS.md\n",
   ...(toolchain === "mise"
     ? {

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

@@ -0,0 +1,58 @@
+import { buildCommand } from "@stricli/core";
+
+import {
+  discoverInstance,
+  sendControlRequest,
+} from "../../server/auth/instance-control";
+import { createInstanceIdentity } from "../../shared/index";
+import { parsePort } from "../parse-port";
+
+type InstanceFlags = { json?: boolean; port?: string };
+
+// Read the already-resolved identity through the private same-user control socket.
+// Config may have changed since startup, and re-evaluating it can repeat side effects.
+// The running server resolved its identity once using the actual bound port.
+const runInstance = async (
+  flags: InstanceFlags,
+  output: Pick<NodeJS.WriteStream, "write">,
+) => {
+  const port = flags.port === undefined ? undefined : parsePort(flags.port);
+  if (port instanceof Error) {
+    throw port;
+  }
+  const instance = await discoverInstance(port);
+  const response = await sendControlRequest(instance, {
+    type: "get-instance",
+  });
+  const identity = createInstanceIdentity(response.instanceId);
+  output.write(
+    flags.json
+      ? `${JSON.stringify(identity)}\n`
+      : `Instance ID: ${identity.instanceId}\nDeep-link prefix: ${identity.deepLinkPrefix}\n`,
+  );
+};
+
+export const createInstanceCommand = (
+  output: Pick<NodeJS.WriteStream, "write">,
+) =>
+  buildCommand({
+    func: (flags: InstanceFlags) => runInstance(flags, output),
+    parameters: {
+      aliases: { p: "port" },
+      flags: {
+        json: {
+          brief: "Print machine-readable JSON",
+          kind: "boolean",
+          optional: true,
+        },
+        port: {
+          brief: "Running local server port",
+          kind: "parsed",
+          optional: true,
+          parse: String,
+        },
+      },
+      positional: { kind: "tuple", parameters: [] },
+    },
+    docs: { brief: "Print the identity of a running Overmux server" },
+  });

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

@@ -184,6 +184,9 @@ const announceServeLogin = async ({
     return;
   }
   printLoginGrant({ ...(await issueLoginGrant(port)), output: process });
+  process.stdout.write(
+    `\nNeed another grant? Run \`overmux auth login --port ${port}\`.\n`,
+  );
 };
 
 export const runServe = async ({

package/src/internal/cli/login.ts

@@ -19,11 +19,9 @@ export const printLoginFallback = (port: number, { stdout }: CliOutput) => {
 export const printLoginGrant = ({
   login,
   output,
-  port,
 }: {
   login: LoginGrant;
   output: CliOutput;
-  port: number;
 }) => {
   const expiresIn = Math.max(
     0,
@@ -31,16 +29,18 @@ export const printLoginGrant = ({
   );
   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}\`.`,
+      `Code: ${login.code} (enter on the login page)`,
+      "",
+      ...(login.urls.length === 1
+        ? [`Login URL: ${login.urls[0]}`]
+        : ["Login URLs:", ...login.urls.map((url) => `  ${url}`)]),
+      "",
+      `Expiry in ${expiresIn} minutes (at ${login.expiresAt}).`,
+      "",
       "",
     ].join("\n"),
   );
   output.stderr.write(
-    "The login URL is a temporary credential; avoid sharing terminal output or screenshots.\n",
+    `Keep the code and link${login.urls.length === 1 ? "" : "s"} private.\n`,
   );
 };

package/src/internal/cli/parse-port.ts

@@ -2,7 +2,8 @@ import { serverConfigRuntimeSchema } from "@overmux/shared/node";
 
 export const parsePort = (value: string): Error | number => {
   const port = Number(value);
-  return serverConfigRuntimeSchema.shape.port.safeParse(port).success
+  return port > 0 &&
+    serverConfigRuntimeSchema.shape.port.safeParse(port).success
     ? port
     : new Error(`Invalid port: ${value}`);
 };

package/src/internal/client/auth/auth-shell.css

@@ -46,10 +46,26 @@ body {
   border: 1px solid #666;
   background: #111;
   color: inherit;
-  letter-spacing: 0.08em;
+  font-family: ui-monospace, monospace;
+  font-size: 1.25rem;
+  letter-spacing: 0.12em;
   text-transform: uppercase;
 }
 
+[data-om-auth-shell] input[aria-invalid="true"] {
+  border-color: #ff9b9b;
+}
+
+#auth-code-error {
+  margin: 0;
+  color: #ff9b9b;
+  font-size: 0.875rem;
+}
+
+#auth-code-error:not(:empty) {
+  margin-top: 0.5rem;
+}
+
 [data-om-auth-shell] button {
   margin-top: 1rem;
   border: 0;

package/src/internal/client/auth/auth-shell.tsx

@@ -15,6 +15,7 @@ import {
 // React Query is intentionally excluded to keep the public pre-authentication shell lightweight.
 // Its mutations may still run concurrently, so it would not replace latest-request cancellation.
 import { getAuthState, login, type LoginInput } from "./auth-api";
+import { LoginCodeInput } from "./login-code-input";
 import "./auth-shell.css";
 
 type AuthStatus =
@@ -147,17 +148,7 @@ export const AuthShell = ({ ticket }: AuthShellProps) => {
       </p>
       <form aria-busy={pending} onSubmit={submitCode}>
         <label htmlFor="auth-code">Login code</label>
-        <input
-          aria-describedby="auth-status"
-          autoCapitalize="characters"
-          autoComplete="one-time-code"
-          disabled={pending}
-          id="auth-code"
-          name="code"
-          pattern="[A-Za-z0-9]{4}-[A-Za-z0-9]{4}"
-          required
-          spellCheck={false}
-        />
+        <LoginCodeInput disabled={pending} />
         <button disabled={pending} type="submit">
           Unlock Overmux
         </button>

package/src/internal/client/auth/login-code-input.tsx

@@ -0,0 +1,140 @@
+import { useState, type ClipboardEvent, type KeyboardEvent } from "react";
+
+type LoginCodeInputProps = {
+  disabled: boolean;
+};
+
+const maxCodeLength = 8;
+const codeError = "Enter 8 letters or numbers, with no spaces inside the code.";
+
+const formatCode = (value: string) => {
+  const trimmed = value.trim();
+  const ungrouped = trimmed.replace("-", "");
+  if (!/^[A-Za-z0-9]*$/.test(ungrouped)) {
+    return trimmed;
+  }
+  const characters = ungrouped.slice(0, maxCodeLength).toUpperCase();
+  return characters.length < 4
+    ? characters
+    : `${characters.slice(0, 4)}-${characters.slice(4)}`;
+};
+
+const formatInput = (input: HTMLInputElement) => {
+  const { value, selectionStart, selectionEnd, selectionDirection } = input;
+  const formatted = formatCode(value);
+  if (formatted === value) {
+    return;
+  }
+  // Formatting the prefix maps the native selection past an inserted dash without
+  // moving edits in the middle of the code to the end of the field.
+  const start = formatCode(
+    value.slice(0, selectionStart ?? value.length),
+  ).length;
+  const end = formatCode(value.slice(0, selectionEnd ?? value.length)).length;
+  input.value = formatted;
+  input.setSelectionRange(start, end, selectionDirection ?? undefined);
+};
+
+const pasteCode = (event: ClipboardEvent<HTMLInputElement>) => {
+  event.preventDefault();
+  const input = event.currentTarget;
+  // Text inputs silently remove line breaks; preserve internal ones as invalid
+  // spaces rather than accidentally accepting a code with embedded whitespace.
+  const pasted = event.clipboardData
+    .getData("text/plain")
+    .trim()
+    .replace(/[\r\n]/g, " ");
+  // A whole code replaces both groups regardless of the caret. Reject oversized
+  // pastes before changing the field, including partial pastes that would overflow.
+  const replaceWholeCode = pasted.length >= maxCodeLength;
+  const start = replaceWholeCode ? 0 : (input.selectionStart ?? 0);
+  const end = replaceWholeCode ? input.value.length : (input.selectionEnd ?? 0);
+  const nextValue =
+    input.value.slice(0, start) + pasted + input.value.slice(end);
+  if (nextValue.trim().replace("-", "").length > maxCodeLength) {
+    input.setCustomValidity(codeError);
+    return false;
+  }
+  input.setCustomValidity("");
+  input.setRangeText(pasted, start, end, "end");
+  formatInput(input);
+  return true;
+};
+
+const editSeparator = (event: KeyboardEvent<HTMLInputElement>) => {
+  const input = event.currentTarget;
+  const caret = input.selectionStart;
+  if (
+    event.ctrlKey ||
+    event.metaKey ||
+    event.altKey ||
+    caret !== input.selectionEnd ||
+    input.value[4] !== "-"
+  ) {
+    return;
+  }
+  if (event.key === "-" && (caret === 4 || caret === 5)) {
+    event.preventDefault();
+    input.setSelectionRange(5, 5);
+  }
+  // Treat the separator as formatting: deletion at its boundary removes the
+  // adjacent character rather than restoring the dash without making progress.
+  if (event.key === "Backspace" && caret === 5) {
+    event.preventDefault();
+    input.setRangeText("", 3, 5, "end");
+    formatInput(input);
+  }
+  if (event.key === "Delete" && caret === 4) {
+    event.preventDefault();
+    input.setRangeText("", 4, Math.min(6, input.value.length), "end");
+    formatInput(input);
+  }
+};
+
+export const LoginCodeInput = ({ disabled }: LoginCodeInputProps) => {
+  const [invalid, setInvalid] = useState(false);
+
+  return (
+    <>
+      <input
+        aria-describedby="auth-code-error auth-status"
+        aria-invalid={invalid || undefined}
+        autoCapitalize="characters"
+        autoComplete="one-time-code"
+        disabled={disabled}
+        id="auth-code"
+        maxLength={maxCodeLength + 1}
+        name="code"
+        onBlur={(event) => formatInput(event.currentTarget)}
+        onInput={(event) => {
+          event.currentTarget.setCustomValidity("");
+          // Do not discard a typed space before learning whether it is internal.
+          if (!/\s$/.test(event.currentTarget.value)) {
+            formatInput(event.currentTarget);
+          }
+          setInvalid(false);
+        }}
+        onInvalid={() => setInvalid(true)}
+        onKeyDown={(event) => {
+          if (event.key === "Enter") {
+            formatInput(event.currentTarget);
+          }
+          editSeparator(event);
+          if (event.defaultPrevented) {
+            event.currentTarget.setCustomValidity("");
+            setInvalid(false);
+          }
+        }}
+        onPaste={(event) => setInvalid(!pasteCode(event))}
+        pattern="[A-Za-z0-9]{4}-[A-Za-z0-9]{4}"
+        placeholder="XXXX-XXXX"
+        required
+        spellCheck={false}
+        type="text"
+      />
+      <p aria-live="polite" id="auth-code-error">
+        {invalid ? codeError : undefined}
+      </p>
+    </>
+  );
+};

package/src/internal/client/browser-api.ts

@@ -1,5 +1,8 @@
 import type { RuntimeManifest } from "../shared/index";
-import type { ContractInputArguments } from "../../public/index";
+import type {
+  ContractInputArguments,
+  InstanceIdentity,
+} from "../../public/index";
 import type { z } from "zod";
 
 import type { ClientTransport } from "./transport";
@@ -25,14 +28,21 @@ type OperationArguments<TInput extends z.ZodType> = [
   signal?: AbortSignal,
 ];
 
-export type OvermuxServerApi<TServerConfig> = {
+type InstanceGetters = {
+  getInstanceId: () => string | undefined;
+  getDeepLinkPrefix: () => string | undefined;
+};
+
+export type OvermuxServerApi<TServerConfig> = InstanceGetters & {
   executeOperation: <TId extends OperationId<TServerConfig>>(
     id: TId,
     ...args: OperationArguments<OperationInput<TServerConfig, TId>>
   ) => Promise<OperationOutput<TServerConfig, TId>>;
 };
 
-export type RuntimeOvermuxServerApi = {
+export type RuntimeOvermuxServerApi = InstanceGetters & {
+  getInstance: () => InstanceIdentity | undefined;
+  subscribeInstance: (listener: () => void) => () => void;
   executeOperation: (
     id: string,
     input?: unknown,
@@ -73,6 +83,10 @@ export const createOvermuxServerApi = ({
   manifest: RuntimeManifest;
   transport: ClientTransport;
 }): RuntimeOvermuxServerApi => ({
+  getInstance: transport.getInstance,
+  subscribeInstance: transport.subscribeInstance,
+  getInstanceId: () => transport.getInstance()?.instanceId,
+  getDeepLinkPrefix: () => transport.getInstance()?.deepLinkPrefix,
   executeOperation: (id, input, signal) => {
     if (!manifest.operations.includes(id)) {
       throw new Error(`Operation is not available: ${id}`);