overmux 0.0.1 → 0.0.2

package/src/public/ai-context.ts

@@ -0,0 +1,44 @@
+import {
+  packageSourceSnippet,
+  techStackRecommendationsSnippet,
+  type AiContextSnippet,
+} from "@overmux/shared";
+
+export {
+  packageSourceSnippet,
+  techStackRecommendationsSnippet,
+  type AiContextSnippet,
+};
+export type AiContextSnippetDefinition = readonly AiContextSnippet[];
+
+export const coreAiContextSnippets = [
+  packageSourceSnippet,
+] as const satisfies AiContextSnippetDefinition;
+export const defaultAiContextSnippets = [
+  ...coreAiContextSnippets,
+  techStackRecommendationsSnippet,
+] as const satisfies AiContextSnippetDefinition;
+
+const packageSourceSnippetContent = `Overmux ships with documentation and TypeScript source.
+
+Run \`overmux docs\` to find the installed documentation and source for the overmux cli.
+
+E.g. \`node_modules/overmux\` and \`node_modules/@overmux/xterm\`.
+
+Inspect these files so guidance matches the versions used by the application.`;
+
+const techStackRecommendationsSnippetContent = `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.`;
+
+const aiContextContentBySnippet: Record<AiContextSnippet, string> = {
+  [packageSourceSnippet]: packageSourceSnippetContent,
+  [techStackRecommendationsSnippet]: techStackRecommendationsSnippetContent,
+};
+
+export const composeAiContext = (snippets: AiContextSnippetDefinition) =>
+  snippets.length === 0
+    ? ""
+    : `${snippets
+        .map(
+          (snippet) => `## ${snippet}\n\n${aiContextContentBySnippet[snippet]}`,
+        )
+        .join("\n\n")}\n`;

package/src/public/client.ts

@@ -0,0 +1,53 @@
+export {
+  disableBackgroundNotifications,
+  enableBackgroundNotifications,
+} from "../internal/client/background-notifications";
+export type { OvermuxServerApi } from "../internal/client/browser-api";
+export {
+  createOvermuxHooks,
+  type ResourceResult,
+  type StreamResult,
+} from "../internal/client/overmux-react";
+export { OvermuxHost } from "../internal/client/host/overmux-host";
+export {
+  OvermuxPortal,
+  OvermuxThemeScope,
+} from "../internal/client/theme-scope";
+export type {
+  OvermuxContrast,
+  OvermuxExternalPortalContainer,
+  OvermuxPortalProps,
+  OvermuxScheme,
+  OvermuxThemeScopeProps,
+  OvermuxStyle,
+  OvermuxThemeToken,
+} from "../internal/client/theme-scope";
+export {
+  chordPrefixSchema,
+  commandBindingSchema,
+  defineCommandRegistry,
+  defineOvermuxClient,
+  formatKeyBinding,
+  formatShortcutBinding,
+  keyBindingSchema,
+  matchesKeyBinding,
+  shortcutBindingSchema,
+} from "../internal/client/client-definition";
+export {
+  skipToken,
+  useCommand,
+  useCommands,
+} from "../internal/client/commands";
+export { useShortcutInputTarget } from "../internal/client/shortcuts";
+export type {
+  ChordPrefix,
+  CommandBinding,
+  CommandHandle,
+  ConditionalShortcutBinding,
+  KeyBinding,
+  KeySequence,
+  OvermuxClientAppearance,
+  ShortcutBinding,
+} from "../internal/client/client-definition";
+export type { CommandEntry, SkipToken } from "../internal/client/commands";
+export type { ShortcutInputTarget } from "../internal/client/shortcuts";

package/src/public/config.ts

@@ -0,0 +1,287 @@
+import { z } from "zod";
+
+import type { AiContextSnippetDefinition } from "./ai-context";
+import type { Notifications } from "./notifications";
+import type { ResourceContract, StreamContract } from "./contracts";
+
+export type RuntimeDisposer = () => Promise<void> | void;
+
+export type HandlerContext = {
+  invalidate: (contract: ResourceContract, input?: unknown) => void;
+  signal: AbortSignal;
+};
+
+export type OperationContext = HandlerContext & {
+  notifications: Notifications;
+};
+
+export type OperationDefinition<
+  TInput extends z.ZodType = z.ZodType,
+  TOutput extends z.ZodType = z.ZodVoid,
+> = {
+  handle: (
+    input: z.output<TInput>,
+    context: OperationContext,
+  ) => Promise<z.input<NoInfer<TOutput>>> | z.input<NoInfer<TOutput>>;
+  input: TInput;
+  output: TOutput;
+};
+
+export const defineOperation = <
+  TInput extends z.ZodType,
+  TOutput extends z.ZodType = z.ZodVoid,
+>({
+  handle,
+  input,
+  output,
+}: {
+  handle: OperationDefinition<TInput, TOutput>["handle"];
+  input: TInput;
+  output?: TOutput;
+}): OperationDefinition<TInput, TOutput> => ({
+  handle,
+  input,
+  output: (output ?? z.void()) as TOutput,
+});
+
+export type QueryResourceDefinition<
+  TInput extends z.ZodType = z.ZodType,
+  TOutput extends z.ZodType = z.ZodType,
+> = {
+  contract: ResourceContract<TInput, TOutput>;
+  kind: "query";
+  read: (
+    input: z.output<TInput>,
+    context: HandlerContext,
+  ) => Promise<z.input<NoInfer<TOutput>>> | z.input<NoInfer<TOutput>>;
+};
+
+export type SubscriptionResourceDefinition<
+  TInput extends z.ZodType = z.ZodType,
+  TOutput extends z.ZodType = z.ZodType,
+> = {
+  contract: ResourceContract<TInput, TOutput>;
+  kind: "subscription";
+  read: QueryResourceDefinition<TInput, TOutput>["read"];
+  subscribe: (
+    input: z.output<TInput>,
+    invalidate: () => void,
+    context: HandlerContext,
+  ) => RuntimeDisposer;
+};
+
+export type DerivedResourceDefinition<
+  TInput extends z.ZodType = z.ZodType,
+  TOutput extends z.ZodType = z.ZodType,
+  TDependencies extends Readonly<Record<string, string>> = Readonly<
+    Record<string, string>
+  >,
+  TDependencyOutputs = Readonly<Record<string, unknown>>,
+> = {
+  combine: (dependencies: TDependencyOutputs) => z.input<NoInfer<TOutput>>;
+  contract: ResourceContract<TInput, TOutput>;
+  dependencies: TDependencies;
+  kind: "derived";
+};
+
+type AnyZodType = z.ZodType<any, any, any>;
+
+export type ResourceDefinition =
+  | QueryResourceDefinition<AnyZodType, AnyZodType>
+  | SubscriptionResourceDefinition<AnyZodType, AnyZodType>
+  | DerivedResourceDefinition<AnyZodType, AnyZodType, any, any>;
+
+export type StreamSession<TClientMessage = unknown> = {
+  dispose?: RuntimeDisposer;
+  onMessage?: (message: TClientMessage) => Promise<void> | void;
+};
+
+export type StreamHandlerDefinition<
+  TInput extends z.ZodType = z.ZodType,
+  TClientMessage extends z.ZodType = z.ZodType,
+  TServerMessage extends z.ZodType = z.ZodType,
+> = {
+  contract: StreamContract<TInput, TClientMessage, TServerMessage>;
+  open: (
+    input: z.output<TInput>,
+    context: HandlerContext & {
+      emit: (message: z.input<NoInfer<TServerMessage>>) => void;
+      fail: (cause: unknown) => void;
+    },
+  ) =>
+    | Promise<StreamSession<z.output<TClientMessage>>>
+    | StreamSession<z.output<TClientMessage>>;
+};
+
+export const defineStreamHandler = <
+  TInput extends z.ZodType,
+  TClientMessage extends z.ZodType,
+  TServerMessage extends z.ZodType,
+>(
+  contract: StreamContract<TInput, TClientMessage, TServerMessage>,
+  open: StreamHandlerDefinition<TInput, TClientMessage, TServerMessage>["open"],
+): StreamHandlerDefinition<TInput, TClientMessage, TServerMessage> => ({
+  contract,
+  open,
+});
+
+type ResourceContracts = Record<
+  string,
+  ResourceContract<AnyZodType, AnyZodType>
+>;
+
+type DependencyOutputs<
+  TContracts extends ResourceContracts,
+  TDependencies extends Record<string, unknown>,
+> = {
+  [TName in keyof TDependencies]: TDependencies[TName] extends keyof TContracts
+    ? z.output<TContracts[TDependencies[TName]]["output"]>
+    : never;
+};
+
+type DependencySource<TDependencies> = {
+  [TId in keyof TDependencies]: TDependencies[TId] extends Record<
+    string,
+    string
+  >
+    ? { dependencies: TDependencies[TId] }
+    : { dependencies?: never };
+};
+
+type QueryFor<TContract extends ResourceContract<AnyZodType, AnyZodType>> = {
+  contract: TContract;
+} & Omit<
+  QueryResourceDefinition<TContract["input"], TContract["output"]>,
+  "contract"
+>;
+
+type SubscriptionFor<
+  TContract extends ResourceContract<AnyZodType, AnyZodType>,
+> = { contract: TContract } & Omit<
+  SubscriptionResourceDefinition<TContract["input"], TContract["output"]>,
+  "contract"
+>;
+
+type DerivedFor<
+  TContract extends ResourceContract<AnyZodType, AnyZodType>,
+  TDependencies extends Record<string, string>,
+  TDependencyOutputs,
+> = {
+  combine: (
+    dependencies: TDependencyOutputs,
+  ) => z.input<NoInfer<TContract["output"]>>;
+  contract: TContract;
+  dependencies: TDependencies;
+  kind: "derived";
+};
+
+type ConfiguredResource<
+  TContracts extends ResourceContracts,
+  TDependencies,
+  TId extends keyof TContracts,
+> =
+  | QueryFor<TContracts[TId]>
+  | SubscriptionFor<TContracts[TId]>
+  | (TId extends keyof TDependencies
+      ? TDependencies[TId] extends Record<
+          string,
+          Exclude<keyof TContracts, TId> & string
+        >
+        ? DerivedFor<
+            TContracts[TId],
+            TDependencies[TId],
+            DependencyOutputs<TContracts, NoInfer<TDependencies[TId]>>
+          >
+        : never
+      : never);
+
+type ConfiguredResources<
+  TContracts extends ResourceContracts,
+  TDependencies,
+> = {
+  [TId in keyof TContracts]: ConfiguredResource<TContracts, TDependencies, TId>;
+} & DependencySource<TDependencies>;
+
+export type AuthDuration = `${number}${"m" | "h" | "d"}`;
+
+export type AuthConfigDefinition = {
+  mode: "cli-login";
+  origins?: string[];
+  sessionLifetime?: "never" | AuthDuration;
+  trustedProxyPeer?: string;
+};
+
+export type ServerConfigDefinition = {
+  host?: string;
+  logFile?: string;
+  port?: number;
+  productionWebAssetsDir?: string;
+  watch?: boolean;
+};
+
+type StreamDefinitions = Readonly<
+  Record<string, StreamHandlerDefinition<AnyZodType, AnyZodType, AnyZodType>>
+>;
+
+type OperationDefinitions = Readonly<
+  Record<string, OperationDefinition<AnyZodType, AnyZodType>>
+>;
+
+export type ConfigDefinition<
+  TResources extends Readonly<Record<string, unknown>> = Readonly<
+    Record<string, ResourceDefinition>
+  >,
+  TStreams extends StreamDefinitions = StreamDefinitions,
+  TOperations extends OperationDefinitions = OperationDefinitions,
+> = {
+  operations?: TOperations;
+  resources: TResources;
+  streams?: TStreams;
+};
+
+export type OvermuxConfigDefinition<
+  TServer extends ConfigDefinition = ConfigDefinition,
+> = ServerConfigDefinition & {
+  aiContextSnippets?: AiContextSnippetDefinition;
+  auth: AuthConfigDefinition;
+  debug?: boolean;
+  server: TServer;
+  vite?: string;
+};
+
+export type OvermuxServerResources<TServer> = TServer extends {
+  resources: infer TResources;
+}
+  ? TResources
+  : never;
+
+export type OvermuxServerStreams<TServer> = TServer extends {
+  streams?: infer TStreams;
+}
+  ? NonNullable<TStreams>
+  : never;
+
+export type OvermuxServerOperations<TServer> = TServer extends {
+  operations?: infer TOperations;
+}
+  ? NonNullable<TOperations>
+  : never;
+
+export const defineOvermuxServer = <
+  const TContracts extends ResourceContracts = {},
+  const TDependencies = {},
+  const TStreams extends StreamDefinitions = {},
+  const TOperations extends OperationDefinitions = {},
+>(definition: {
+  operations?: TOperations;
+  resources: ConfiguredResources<TContracts, TDependencies>;
+  streams?: TStreams;
+}): ConfigDefinition<
+  ConfiguredResources<TContracts, TDependencies>,
+  TStreams,
+  TOperations
+> => definition;
+
+export const defineOvermuxConfig = <const TServer extends ConfigDefinition>(
+  definition: OvermuxConfigDefinition<TServer>,
+): OvermuxConfigDefinition<TServer> => definition;

package/src/public/contracts.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+
+export const noInputSchema = z.void();
+
+export const jsonValueSchema: z.ZodType<unknown> = z.lazy(() =>
+  z.union([
+    z.string(),
+    z.number().finite(),
+    z.boolean(),
+    z.null(),
+    z.array(jsonValueSchema),
+    z.record(z.string(), jsonValueSchema),
+  ]),
+);
+
+export const parseJsonValue = <T>(value: T): T =>
+  jsonValueSchema.parse(value) as T;
+
+export type ContractInputArguments<TInput extends z.ZodType> =
+  undefined extends z.input<TInput>
+    ? [input?: Exclude<z.input<TInput>, undefined>]
+    : [input: z.input<TInput>];
+
+export type ResourceContract<
+  TInput extends z.ZodType = z.ZodType,
+  TOutput extends z.ZodType = z.ZodType,
+> = {
+  input: TInput;
+  output: TOutput;
+};
+
+export const defineResourceContract = <
+  TInput extends z.ZodType,
+  TOutput extends z.ZodType,
+>(
+  contract: ResourceContract<TInput, TOutput>,
+): ResourceContract<TInput, TOutput> => contract;
+
+export type StreamContract<
+  TInput extends z.ZodType = z.ZodType,
+  TClientMessage extends z.ZodType = z.ZodType,
+  TServerMessage extends z.ZodType = z.ZodType,
+> = {
+  clientMessage: TClientMessage;
+  input: TInput;
+  serverMessage: TServerMessage;
+};
+
+export const defineStreamContract = <
+  TInput extends z.ZodType,
+  TClientMessage extends z.ZodType,
+  TServerMessage extends z.ZodType,
+>(
+  contract: StreamContract<TInput, TClientMessage, TServerMessage>,
+): StreamContract<TInput, TClientMessage, TServerMessage> => contract;

package/src/public/index.ts

@@ -0,0 +1,57 @@
+export {
+  composeAiContext,
+  coreAiContextSnippets,
+  defaultAiContextSnippets,
+  packageSourceSnippet,
+  techStackRecommendationsSnippet,
+} from "./ai-context";
+export type {
+  AiContextSnippet,
+  AiContextSnippetDefinition,
+} from "./ai-context";
+export {
+  defineOperation,
+  defineOvermuxConfig,
+  defineOvermuxServer,
+  defineStreamHandler,
+} from "./config";
+export type {
+  AuthConfigDefinition,
+  AuthDuration,
+  ConfigDefinition,
+  DerivedResourceDefinition,
+  HandlerContext,
+  OperationContext,
+  OperationDefinition,
+  OvermuxConfigDefinition,
+  OvermuxServerOperations,
+  OvermuxServerResources,
+  OvermuxServerStreams,
+  QueryResourceDefinition,
+  ResourceDefinition,
+  RuntimeDisposer,
+  ServerConfigDefinition,
+  StreamHandlerDefinition,
+  StreamSession,
+  SubscriptionResourceDefinition,
+} from "./config";
+export {
+  defineResourceContract,
+  defineStreamContract,
+  jsonValueSchema,
+  noInputSchema,
+  parseJsonValue,
+} from "./contracts";
+export type {
+  ContractInputArguments,
+  ResourceContract,
+  StreamContract,
+} from "./contracts";
+export { notificationLinkSchema, notificationSchema } from "./notifications";
+export type { Notification, Notifications } from "./notifications";
+export {
+  createOvermuxSettingsPath,
+  overmuxLogoutPath,
+  overmuxSettingsPath,
+  resolveOvermuxReturnTo,
+} from "@overmux/shared";

package/src/public/notifications.ts

@@ -0,0 +1,10 @@
+// Defines notifications shared by operation handlers and delivery transports.
+// Keeping validation here gives every delivery path one public contract.
+import type { Notification } from "@overmux/shared";
+
+export { notificationLinkSchema, notificationSchema } from "@overmux/shared";
+export type { Notification } from "@overmux/shared";
+
+export type Notifications = {
+  send: (notification: Notification) => Promise<void>;
+};

package/src/public/server.ts

@@ -0,0 +1,16 @@
+export {
+  checkOvermux,
+  type CheckDiagnostic,
+  type CheckOvermuxOptions,
+  type CheckResult,
+} from "../internal/server/check-overmux";
+export {
+  getOvermuxPaths,
+  type GetOvermuxPathsOptions,
+  type OvermuxPaths,
+} from "../internal/server/paths";
+export {
+  startOvermuxServer,
+  type OvermuxServer,
+  type OvermuxServerOptions,
+} from "../internal/server/start-overmux-server";

package/dist/public/core.ts

@@ -1,119 +0,0 @@
-import { z } from "zod";
-
-export const paneRefSchema = z.object({
-  muxId: z.string().min(1),
-  target: z.string().min(1),
-});
-
-export type PaneRef = z.infer<typeof paneRefSchema>;
-
-export const clientComponentRefSchema = z.object({
-  kind: z.literal("client-component"),
-  moduleId: z.string().min(1),
-});
-
-export type ClientComponentRef = z.infer<typeof clientComponentRefSchema>;
-
-export const clientComponent = (moduleId: string): ClientComponentRef =>
-  clientComponentRefSchema.parse({ kind: "client-component", moduleId });
-
-export type TabTypeDefinition<
-  TType extends string = string,
-  TSchema extends z.ZodType = z.ZodType,
-> = {
-  component: ClientComponentRef;
-  data: TSchema;
-  type: TType;
-};
-
-export const defineTabType = <
-  const TType extends string,
-  TSchema extends z.ZodType,
->(
-  definition: TabTypeDefinition<TType, TSchema>,
-) => definition;
-
-type ConfiguredTab<TTabTypes extends readonly TabTypeDefinition[]> = {
-  [TIndex in keyof TTabTypes]: TTabTypes[TIndex] extends TabTypeDefinition<
-    infer TType,
-    infer TSchema
-  >
-    ? {
-        data: z.input<TSchema>;
-        id: string;
-        title: string;
-        type: TType;
-      }
-    : never;
-}[number];
-
-export type SidebarEntry<
-  TTabTypes extends readonly TabTypeDefinition[] = readonly TabTypeDefinition[],
-> = {
-  id: string;
-  status?: string;
-  subtitle?: string;
-  tabs: Array<ConfiguredTab<TTabTypes>>;
-  title: string;
-};
-
-export type SidebarContext = {
-  invalidate: () => void;
-};
-
-export type ConfigDefinition<
-  TTabTypes extends readonly TabTypeDefinition[] = readonly TabTypeDefinition[],
-> = {
-  muxes?: Record<string, unknown>;
-  sidebar: (
-    context: SidebarContext,
-  ) => Promise<Array<SidebarEntry<TTabTypes>>> | Array<SidebarEntry<TTabTypes>>;
-  tabTypes: TTabTypes;
-};
-
-export const defineConfig = <
-  const TTabTypes extends readonly TabTypeDefinition[],
->(
-  definition: ConfigDefinition<TTabTypes>,
-) => definition;
-
-const isZodSchema = (value: unknown): value is z.ZodType =>
-  typeof value === "object" &&
-  value !== null &&
-  "safeParse" in value &&
-  typeof value.safeParse === "function";
-
-const sidebarFunctionSchema = z.custom<ConfigDefinition["sidebar"]>(
-  (value) => typeof value === "function",
-  "Expected a sidebar function",
-);
-
-export const tabTypeDefinitionRuntimeSchema = z.object({
-  component: clientComponentRefSchema,
-  data: z.custom<z.ZodType>(isZodSchema, "Expected a Zod schema"),
-  type: z.string().min(1),
-});
-
-export const configDefinitionRuntimeSchema = z
-  .object({
-    muxes: z.record(z.string(), z.unknown()).optional(),
-    sidebar: sidebarFunctionSchema,
-    tabTypes: z.array(tabTypeDefinitionRuntimeSchema),
-  })
-  .superRefine(({ tabTypes }, context) => {
-    const seen = new Set<string>();
-    tabTypes.forEach(({ type }, index) => {
-      if (seen.has(type)) {
-        context.addIssue({
-          code: "custom",
-          message: `Duplicate tab type: ${type}`,
-          path: ["tabTypes", index, "type"],
-        });
-      }
-      seen.add(type);
-    });
-  });
-
-export type RuntimeConfigDefinition = z.infer<
-  typeof configDefinitionRuntimeSchema
->;

package/dist/public/protocol.ts

@@ -1,51 +0,0 @@
-import { z } from "zod";
-
-export const protocolVersion = 1 as const;
-
-export const clientComponentManifestEntrySchema = z.object({
-  id: z.string().min(1),
-  type: z.string().min(1),
-});
-
-export const sidebarTabSnapshotSchema = z.object({
-  data: z.unknown(),
-  id: z.string().min(1),
-  title: z.string().min(1),
-  type: z.string().min(1),
-});
-
-export const sidebarEntrySnapshotSchema = z.object({
-  id: z.string().min(1),
-  status: z.string().optional(),
-  subtitle: z.string().optional(),
-  tabs: z.array(sidebarTabSnapshotSchema),
-  title: z.string().min(1),
-});
-
-export const bootstrapResponseSchema = z.object({
-  generation: z.number().int().positive(),
-  protocolVersion: z.literal(protocolVersion),
-  sidebar: z.array(sidebarEntrySnapshotSchema),
-  tabTypes: z.array(clientComponentManifestEntrySchema),
-});
-
-export const runtimePublishedEventSchema = z.object({
-  generation: z.number().int().positive(),
-  type: z.literal("runtime-published"),
-});
-
-export const runtimeErrorEventSchema = z.object({
-  generation: z.number().int().nonnegative(),
-  message: z.string(),
-  type: z.literal("runtime-error"),
-});
-
-export const runtimeEventSchema = z.discriminatedUnion("type", [
-  runtimePublishedEventSchema,
-  runtimeErrorEventSchema,
-]);
-
-export type BootstrapResponse = z.infer<typeof bootstrapResponseSchema>;
-export type RuntimeEvent = z.infer<typeof runtimeEventSchema>;
-export type SidebarEntrySnapshot = z.infer<typeof sidebarEntrySnapshotSchema>;
-export type SidebarTabSnapshot = z.infer<typeof sidebarTabSnapshotSchema>;