overmux 0.0.2 → 0.0.4

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/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/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}`);

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,15 @@
+type DesktopHost = {
+  version: 1;
+  platform: string;
+  instance?: { report: (identity: { instanceId: string }) => void; version: 1 };
+  clipboard?: { writeText: (text: string) => void; version: 1 };
+  notifications?: { show: (notification: unknown) => void; version: 1 };
+};
+
+declare global {
+  interface Window {
+    overmuxHost?: DesktopHost;
+  }
+}
+
+export {};

package/src/internal/client/host/environment.ts

@@ -0,0 +1,67 @@
+import "./desktop-host";
+
+type Platform = "macos" | "windows" | "linux" | "android" | "ios" | "unknown";
+type BrowserNavigator = Navigator & {
+  standalone?: boolean;
+  userAgentData?: { platform: string };
+};
+
+const browserPlatform = (navigator: BrowserNavigator): Platform => {
+  const { userAgent, maxTouchPoints } = navigator;
+  const platform = navigator.userAgentData?.platform ?? navigator.platform;
+  const identity = `${platform} ${userAgent}`;
+  // iPadOS can advertise itself as a Mac when requesting desktop websites.
+  if (
+    /iPad|iPhone|iPod/i.test(identity) ||
+    (/Mac/i.test(identity) && maxTouchPoints > 1)
+  ) {
+    return "ios";
+  }
+  if (/Android/i.test(identity)) {
+    return "android";
+  }
+  if (/Win/i.test(identity)) {
+    return "windows";
+  }
+  if (/Mac/i.test(identity)) {
+    return "macos";
+  }
+  return /Linux/i.test(identity) ? "linux" : "unknown";
+};
+
+const desktopPlatform = (platform: string): Platform => {
+  if (platform === "darwin") {
+    return "macos";
+  }
+  if (platform === "win32") {
+    return "windows";
+  }
+  return platform === "linux" ? "linux" : "unknown";
+};
+
+export const installEnvironmentSelectors = () => {
+  const html = document.documentElement;
+  const host = window.overmuxHost;
+  const desktop = host?.version === 1;
+  const navigator: BrowserNavigator = window.navigator;
+  html.dataset.omPlatform = desktop
+    ? desktopPlatform(host.platform)
+    : browserPlatform(navigator);
+  if (desktop) {
+    html.dataset.omHost = "desktop";
+    return () => {};
+  }
+
+  // Fullscreen alone is not evidence of an installed app.
+  const displayMode = window.matchMedia(
+    "(display-mode: standalone), (display-mode: minimal-ui), (display-mode: window-controls-overlay)",
+  );
+  const updateHost = () => {
+    html.dataset.omHost =
+      displayMode.matches || navigator.standalone === true ? "pwa" : "browser";
+  };
+  updateHost();
+  displayMode.addEventListener("change", updateHost);
+  // The document owns these attributes; disposal only releases the live listener.
+  return () => displayMode.removeEventListener("change", updateHost);
+};

package/src/internal/client/host/instance-forwarding.ts

@@ -0,0 +1,21 @@
+import type { ClientTransport } from "../transport";
+import type {} from "./desktop-host";
+
+export const installInstanceForwarding = (transport: ClientTransport) => {
+  const report = () => {
+    const identity = transport.getInstance();
+    const bridge = window.overmuxHost?.instance;
+    if (!identity || bridge?.version !== 1) {
+      return;
+    }
+    try {
+      bridge.report({ instanceId: identity.instanceId });
+    } catch (cause) {
+      // A host integration failure must not interrupt browser discovery or traffic.
+      console.error("Overmux host instance reporting failed", cause);
+    }
+  };
+  const unsubscribe = transport.subscribeInstance(report);
+  report();
+  return unsubscribe;
+};

package/src/internal/client/host/notification-forwarding.ts

@@ -1,18 +1,9 @@
+import "./desktop-host";
 import { notificationEventSchema } from "../../shared/index";
 
 import type { WebSocketTransport } from "../transport";
 
 // Forwards server notifications to the optional desktop host injected at window.overmuxHost.
-type NotificationHost = {
-  notifications?: { show: (notification: unknown) => void; version: 1 };
-};
-
-declare global {
-  interface Window {
-    overmuxHost?: NotificationHost;
-  }
-}
-
 export const installNotificationForwarding = (transport: WebSocketTransport) =>
   transport.subscribeNotification((event) => {
     const notification = notificationEventSchema.safeParse(event);

package/src/internal/client/host/overmux-host.tsx

@@ -21,6 +21,7 @@ import { OvermuxThemeScope } from "../theme-scope";
 import { createOvermuxServerApi } from "../browser-api";
 import { installBrowserLogForwarding } from "./browser-log-forwarding";
 import { installNotificationForwarding } from "./notification-forwarding";
+import { installInstanceForwarding } from "./instance-forwarding";
 import type { ClientAppDefinition } from "../client-definition";
 import { type RegisteredCommand, RuntimeContext } from "../commands";
 import { ShortcutHost } from "../shortcuts";
@@ -29,6 +30,12 @@ import { HostedLogoutPage } from "./hosted-pages/logout-page";
 import { HostedSettingsPage } from "./hosted-pages/settings-page";
 import { RecoveryScreen } from "./recovery-screen";
 import { UpdatePopover } from "./update-popover";
+import { installEnvironmentSelectors } from "./environment";
+
+// Userland owns createRoot. Initialize on import, before any React tree mounts.
+const disposeEnvironment =
+  typeof window === "undefined" ? undefined : installEnvironmentSelectors();
+import.meta.hot?.dispose(() => disposeEnvironment?.());
 
 type ErrorBoundaryProps = {
   children: ReactNode;
@@ -129,6 +136,7 @@ const OvermuxRuntime = ({
     [transport],
   );
   useEffect(() => installNotificationForwarding(transport), [transport]);
+  useEffect(() => installInstanceForwarding(transport), [transport]);
   const refreshCommands = useCallback(
     () => setRegistrationRevision((revision) => revision + 1),
     [],

package/src/internal/client/overmux-react.ts

@@ -1,11 +1,21 @@
-import type { ContractInputArguments } from "../../public/index";
+import type {
+  ContractInputArguments,
+  InstanceIdentity,
+} from "../../public/index";
 import {
   useMutation,
   useQuery,
   useQueryClient,
   type UseMutationResult,
 } from "@tanstack/react-query";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from "react";
 import type { z } from "zod";
 
 import { skipToken, type SkipToken, useRuntime } from "./commands";
@@ -254,7 +264,19 @@ const useStreamById = <TClientMessage, TServerMessage>(
   };
 };
 
+const undiscoveredInstance = () => undefined;
+
+const useInstance = (): InstanceIdentity | undefined => {
+  const { overmuxServerApi } = useRuntime();
+  return useSyncExternalStore(
+    overmuxServerApi.subscribeInstance,
+    overmuxServerApi.getInstance,
+    undiscoveredInstance,
+  );
+};
+
 export const createOvermuxHooks = <TServerConfig>() => ({
+  useInstance,
   useOperation: <TId extends Extract<keyof Operations<TServerConfig>, string>>({
     id,
     signal,