@rigkit/provider-cmux 0.1.8

package/README.md

@@ -0,0 +1,63 @@
+# @rigkit/provider-cmux
+
+Small SDK and Rigkit provider facade for opening workspaces in local `cmux`.
+
+```ts
+import { createCmuxClient } from "@rigkit/provider-cmux";
+
+const cmux = createCmuxClient();
+
+await cmux.newWorkspace({
+  name: "playground",
+  command: "echo hello world",
+  focus: true,
+});
+```
+
+Commands are printed to stderr before execution:
+
+```text
+$ cmux new-workspace --name playground --command 'echo hello world' --focus true
+```
+
+`cmux new-workspace` and `cmux ssh` are socket commands. With cmux's default socket control mode (`cmuxOnly`), run rigkit from a terminal inside cmux so cmux sets `CMUX_SOCKET_PATH` and accepts the process.
+
+If you intentionally enable external socket control in cmux, opt in explicitly:
+
+```ts
+const cmux = createCmuxClient({ allowExternalAutomation: true });
+```
+
+With `allowExternalAutomation`, the SDK can run `open -a cmux` and retry a workspace command while cmux starts.
+
+Config-defined operations can request the typed `cmux.open` host capability through the provider facade:
+
+```ts
+import { workflow } from "@rigkit/sdk";
+import { cmux } from "@rigkit/provider-cmux";
+
+export default workflow("site", {
+  providers: {
+    cmux: cmux.provider(),
+  },
+})
+  .sequence("site")
+  .operation("open", {
+    requiredHostCapabilities: [cmux.capabilities.open],
+    run: async ({ providers }) => {
+      await providers.cmux.open({
+        name: "site",
+        ssh: {
+          host: "vm-ssh.freestyle.sh",
+          username: "vm_123",
+          auth: { type: "token", token: "token_123" },
+        },
+        cwd: "/workspace/site",
+        command: "pnpm dev",
+        url: "http://localhost:3000",
+      });
+    },
+  });
+```
+
+Local hosts can import `@rigkit/provider-cmux/host` to register the trusted `cmux.open` handler. The Rigkit CLI registers this handler automatically.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@rigkit/provider-cmux",
+  "version": "0.1.8",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/freestyle-sh/rigkit.git",
+    "directory": "packages/provider-cmux"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./host": "./src/host.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@rigkit/engine": "0.1.8",
+    "@rigkit/sdk": "0.1.8"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "latest"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  }
+}

package/src/capabilities.ts

@@ -0,0 +1,56 @@
+export const CMUX_OPEN_CAPABILITY_ID = "cmux.open";
+
+export const CMUX_OPEN_SCHEMA_HASH =
+  "sha256:ed7f74b4fd1101ff87281c0269f9884f85783098d9a727fdfe05491efba2dd28";
+
+export const CMUX_OPEN_CAPABILITY = {
+  id: CMUX_OPEN_CAPABILITY_ID,
+  schemaHash: CMUX_OPEN_SCHEMA_HASH,
+} as const;
+
+export type CmuxOpenSshInput = string | {
+  kind?: "ssh";
+  destination?: string;
+  host?: string;
+  port?: number;
+  username?: string;
+  auth?: { type: "token"; token: string } | { type: "privateKey"; privateKey: string };
+  command?: string;
+  identity?: string;
+  sshOptions?: readonly string[];
+  remoteCommandArgs?: readonly string[];
+  initialCommand?: string;
+  terminalStartupCommand?: string;
+  autoConnect?: boolean;
+  skipDaemonBootstrap?: boolean;
+};
+
+export type CmuxRemoteReadyOptions = {
+  timeoutMs?: number;
+  intervalMs?: number;
+  requireProxy?: boolean;
+};
+
+export type CmuxOpenInput = {
+  name: string;
+  ssh?: CmuxOpenSshInput;
+  cwd?: string;
+  command?: string;
+  url?: string;
+  focus?: boolean;
+  waitForRemoteReady?: boolean | CmuxRemoteReadyOptions;
+};
+
+export type CmuxOpenResult = {
+  sessionId: string;
+  workspaceId: string;
+  workspaceRef?: string;
+  terminalPaneId?: string;
+  terminalSurfaceId?: string;
+  browserPaneId?: string;
+  browserSurfaceId?: string;
+};
+
+export type CmuxOpenSession = CmuxOpenResult & {
+  closed: Promise<void>;
+};

package/src/host.ts

@@ -0,0 +1,301 @@
+import {
+  createCmuxClient,
+  formatShellCommand,
+  type CmuxBrowserOpenOptions,
+  type CmuxClient,
+  type CmuxClientOptions,
+  type CmuxNewPaneOptions,
+  type CmuxNewWorkspaceOptions,
+  type CmuxPane,
+  type CmuxPortsKickOptions,
+  type CmuxSendOptions,
+  type CmuxSshOptions,
+  type CmuxWaitForRemoteOptions,
+  type CmuxWorkspace,
+} from "./index.ts";
+import { defineHostCapability, type HostCapabilityHandler } from "@rigkit/sdk/host";
+import {
+  CMUX_OPEN_CAPABILITY,
+  type CmuxOpenInput,
+  type CmuxOpenResult,
+  type CmuxOpenSshInput,
+  type CmuxRemoteReadyOptions,
+} from "./capabilities.ts";
+
+export type CmuxHostCapabilityHandler = HostCapabilityHandler;
+
+export type CmuxOpenClient = Pick<
+  CmuxClient,
+  | "newWorkspace"
+  | "ssh"
+  | "newPane"
+  | "send"
+  | "portsKick"
+  | "browserOpen"
+  | "selectWorkspace"
+  | "waitForRemoteReady"
+>;
+
+export type CmuxOpenHostOptions = {
+  client?: CmuxOpenClient;
+  clientOptions?: CmuxClientOptions;
+};
+
+const freestyleTokenSshOptions = [
+  "StrictHostKeyChecking=no",
+  "UserKnownHostsFile=/dev/null",
+  "LogLevel=ERROR",
+  "IdentitiesOnly=yes",
+  "IdentityFile=/dev/null",
+  "ControlMaster=no",
+] as const;
+
+export function createCmuxOpenHostCapability(
+  options: CmuxOpenHostOptions = {},
+): CmuxHostCapabilityHandler {
+  return defineHostCapability(CMUX_OPEN_CAPABILITY.id, {
+    schemaHash: CMUX_OPEN_CAPABILITY.schemaHash,
+    handle: async (params) => await openCmux(params, options),
+  });
+}
+
+export const cmuxHostCapabilities = [createCmuxOpenHostCapability()] as const;
+
+export async function openCmux(
+  params: unknown,
+  options: CmuxOpenHostOptions = {},
+): Promise<CmuxOpenResult> {
+  const input = parseCmuxOpenInput(params);
+  const cmux = options.client ?? createCmuxClient(options.clientOptions);
+  const command = commandForInput(input);
+  let workspace: CmuxWorkspace;
+  let terminalPane: CmuxPane | undefined;
+
+  if (input.ssh) {
+    workspace = await cmux.ssh({
+      ...cmuxSshOptionsForInput(input.ssh),
+      name: input.name,
+      noFocus: input.focus === false,
+    });
+  } else {
+    const workspaceOptions: CmuxNewWorkspaceOptions = {
+      name: input.name,
+      cwd: input.cwd,
+      command: input.command,
+      focus: input.focus,
+    };
+    workspace = await cmux.newWorkspace(workspaceOptions);
+  }
+
+  const workspaceId = workspace.id ?? workspace.handle;
+
+  if (input.ssh && command) {
+    const paneOptions: CmuxNewPaneOptions = {
+      workspace: workspaceId,
+      type: "terminal",
+      direction: "down",
+      focus: true,
+    };
+    terminalPane = await cmux.newPane(paneOptions);
+    const sendOptions: CmuxSendOptions = {
+      workspace: workspaceId,
+      surface: terminalPane.surface,
+      text: command,
+    };
+    await cmux.send(sendOptions);
+  }
+
+  const waitOptions = remoteReadyOptionsForInput(input);
+  if (input.ssh && waitOptions) {
+    await cmux.waitForRemoteReady(workspaceId, waitOptions);
+  }
+
+  if (input.ssh && terminalPane?.surface) {
+    const kickOptions: CmuxPortsKickOptions = {
+      workspace: workspaceId,
+      surface: terminalPane.surface,
+      reason: "command",
+    };
+    await cmux.portsKick(kickOptions);
+  }
+
+  let browserPane: CmuxPane | undefined;
+  if (input.url) {
+    const browserOptions: CmuxBrowserOpenOptions = {
+      workspace: workspaceId,
+      url: input.url,
+      focus: input.focus !== false,
+    };
+    browserPane = await cmux.browserOpen(browserOptions);
+  }
+
+  if (input.focus !== false) {
+    await cmux.selectWorkspace(workspaceId);
+  }
+
+  return {
+    sessionId: workspaceId,
+    workspaceId,
+    ...(workspace.ref ? { workspaceRef: workspace.ref } : {}),
+    ...(terminalPane?.pane ? { terminalPaneId: terminalPane.pane } : {}),
+    ...(terminalPane?.surface ? { terminalSurfaceId: terminalPane.surface } : {}),
+    ...(browserPane?.pane ? { browserPaneId: browserPane.pane } : {}),
+    ...(browserPane?.surface ? { browserSurfaceId: browserPane.surface } : {}),
+  };
+}
+
+export function parseCmuxOpenInput(value: unknown): CmuxOpenInput {
+  if (!isRecord(value)) throw new Error(`cmux.open requires an object input`);
+  const name = requiredString(value, "name");
+  return {
+    name,
+    ...(value.ssh !== undefined ? { ssh: parseSshInput(value.ssh) } : {}),
+    ...optionalStringField(value, "cwd"),
+    ...optionalStringField(value, "command"),
+    ...optionalStringField(value, "url"),
+    ...optionalBooleanField(value, "focus"),
+    ...(value.waitForRemoteReady !== undefined
+      ? { waitForRemoteReady: parseRemoteReadyOptions(value.waitForRemoteReady) }
+      : {}),
+  };
+}
+
+function parseSshInput(value: unknown): CmuxOpenSshInput {
+  if (typeof value === "string" && value.trim()) return value.trim();
+  if (!isRecord(value)) throw new Error(`cmux.open ssh must be a string or object`);
+  if (value.kind !== undefined && value.kind !== "ssh") {
+    throw new Error(`cmux.open ssh.kind must be "ssh"`);
+  }
+  return {
+    ...optionalStringField(value, "destination"),
+    ...optionalStringField(value, "host"),
+    ...optionalNumberField(value, "port"),
+    ...optionalStringField(value, "username"),
+    ...(value.auth !== undefined ? { auth: parseSshAuth(value.auth) } : {}),
+    ...optionalStringField(value, "command"),
+    ...optionalStringField(value, "identity"),
+    ...optionalStringArrayField(value, "sshOptions"),
+    ...optionalStringArrayField(value, "remoteCommandArgs"),
+    ...optionalStringField(value, "initialCommand"),
+    ...optionalStringField(value, "terminalStartupCommand"),
+    ...optionalBooleanField(value, "autoConnect"),
+    ...optionalBooleanField(value, "skipDaemonBootstrap"),
+  };
+}
+
+function parseSshAuth(value: unknown): Exclude<Extract<CmuxOpenSshInput, object>["auth"], undefined> {
+  if (!isRecord(value)) throw new Error(`cmux.open ssh.auth must be an object`);
+  if (value.type === "token") {
+    return { type: "token", token: requiredString(value, "token") };
+  }
+  if (value.type === "privateKey") {
+    return { type: "privateKey", privateKey: requiredString(value, "privateKey") };
+  }
+  throw new Error(`cmux.open ssh.auth.type must be "token" or "privateKey"`);
+}
+
+function parseRemoteReadyOptions(value: unknown): boolean | CmuxRemoteReadyOptions {
+  if (typeof value === "boolean") return value;
+  if (!isRecord(value)) throw new Error(`cmux.open waitForRemoteReady must be a boolean or object`);
+  return {
+    ...optionalNumberField(value, "timeoutMs"),
+    ...optionalNumberField(value, "intervalMs"),
+    ...optionalBooleanField(value, "requireProxy"),
+  };
+}
+
+function cmuxSshOptionsForInput(ssh: CmuxOpenSshInput): CmuxSshOptions {
+  if (typeof ssh === "string") return { destination: ssh };
+
+  const destination = ssh.destination ?? sshDestination(ssh);
+  const sshOptions = [
+    ...(ssh.auth?.type === "token" ? freestyleTokenSshOptions : []),
+    ...(ssh.sshOptions ?? []),
+  ];
+  return {
+    destination,
+    port: ssh.port,
+    identity: ssh.identity,
+    sshOptions,
+    remoteCommandArgs: ssh.remoteCommandArgs,
+    initialCommand: ssh.initialCommand,
+    terminalStartupCommand: ssh.terminalStartupCommand ?? ssh.command,
+    autoConnect: ssh.autoConnect,
+    skipDaemonBootstrap: ssh.skipDaemonBootstrap,
+  };
+}
+
+function sshDestination(ssh: Extract<CmuxOpenSshInput, object>): string {
+  if (!ssh.host) throw new Error(`cmux.open ssh.host is required when ssh.destination is omitted`);
+  if (!ssh.username) throw new Error(`cmux.open ssh.username is required when ssh.destination is omitted`);
+  if (ssh.auth?.type === "token") return `${ssh.username},${ssh.auth.token}@${ssh.host}`;
+  return `${ssh.username}@${ssh.host}`;
+}
+
+function commandForInput(input: CmuxOpenInput): string | undefined {
+  if (!input.command) return undefined;
+  const prefix = input.cwd ? `${formatShellCommand(["cd", input.cwd])} && ` : "";
+  return `${prefix}${input.command}\n`;
+}
+
+function remoteReadyOptionsForInput(input: CmuxOpenInput): CmuxWaitForRemoteOptions | false {
+  if (input.waitForRemoteReady === false) return false;
+  if (input.waitForRemoteReady === true || input.waitForRemoteReady === undefined) {
+    return input.url ? {} : false;
+  }
+  return input.waitForRemoteReady;
+}
+
+function requiredString(record: Record<string, unknown>, key: string): string {
+  const value = record[key];
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`cmux.open ${key} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function optionalStringField(
+  record: Record<string, unknown>,
+  key: string,
+  expected?: string,
+): Record<string, string> {
+  const value = record[key];
+  if (value === undefined) return {};
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`cmux.open ${key} must be a non-empty string`);
+  }
+  const normalized = value.trim();
+  if (expected !== undefined && normalized !== expected) {
+    throw new Error(`cmux.open ${key} must be "${expected}"`);
+  }
+  return { [key]: normalized };
+}
+
+function optionalStringArrayField(record: Record<string, unknown>, key: string): Record<string, string[]> {
+  const value = record[key];
+  if (value === undefined) return {};
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new Error(`cmux.open ${key} must be an array of strings`);
+  }
+  return { [key]: value };
+}
+
+function optionalNumberField(record: Record<string, unknown>, key: string): Record<string, number> {
+  const value = record[key];
+  if (value === undefined) return {};
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`cmux.open ${key} must be a finite number`);
+  }
+  return { [key]: value };
+}
+
+function optionalBooleanField(record: Record<string, unknown>, key: string): Record<string, boolean> {
+  const value = record[key];
+  if (value === undefined) return {};
+  if (typeof value !== "boolean") throw new Error(`cmux.open ${key} must be a boolean`);
+  return { [key]: value };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}