@taranek/orche 0.0.8

package/src/multiplexer.ts

@@ -0,0 +1,57 @@
+import { execSync } from "node:child_process";
+import type { MultiplexerType } from "./types.js";
+import { TmuxMultiplexer } from "./multiplexers/tmux.js";
+import { CmuxMultiplexer } from "./multiplexers/cmux.js";
+
+export interface Multiplexer {
+  readonly name: string;
+
+  // Session lifecycle
+  createSession(name: string, cwd: string): void;
+  killSession(name: string): void;
+  attach(name: string): void;
+
+  // Pane operations
+  getActivePaneId(session: string): string;
+  listPaneIds(session: string): string[];
+  splitPane(
+    target: string,
+    direction: "horizontal" | "vertical",
+    sizePercent: number,
+    cwd: string
+  ): void;
+  focusPane(paneId: string): void;
+  renamePaneTitle(paneId: string, name: string): void;
+  sendCommand(target: string, command: string): void;
+
+  // Detection
+  isInsideSession(): boolean;
+  detectFirstPane(): string | undefined;
+}
+
+function isAvailable(bin: string): boolean {
+  try {
+    execSync(`which ${bin}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function getMultiplexer(preference: MultiplexerType = "auto"): Multiplexer {
+  if (preference === "tmux") {
+    if (!isAvailable("tmux")) throw new Error("tmux not found — brew install tmux");
+    return new TmuxMultiplexer();
+  }
+
+  if (preference === "cmux") {
+    if (!isAvailable("cmux")) throw new Error("cmux not found — https://cmux.com");
+    return new CmuxMultiplexer();
+  }
+
+  // auto: prefer cmux if available, fall back to tmux
+  if (isAvailable("cmux")) return new CmuxMultiplexer();
+  if (isAvailable("tmux")) return new TmuxMultiplexer();
+
+  throw new Error("no multiplexer found — install tmux (brew install tmux) or cmux (https://cmux.com)");
+}

package/src/multiplexers/cmux.ts

@@ -0,0 +1,143 @@
+import { execSync } from "node:child_process";
+import type { Multiplexer } from "../multiplexer.js";
+
+const DEBUG = !!process.env.ORCHE_DEBUG;
+
+function log(...args: unknown[]): void {
+  if (DEBUG) console.error("[cmux]", ...args);
+}
+
+function run(cmd: string): string {
+  log("$", cmd);
+  const out = execSync(cmd).toString().trim();
+  log("→", out.length > 200 ? out.slice(0, 200) + "…" : out);
+  return out;
+}
+
+export class CmuxMultiplexer implements Multiplexer {
+  readonly name = "cmux";
+
+  // Track surfaces we created so layout can target them
+  private surfaces: string[] = [];
+
+  createSession(_name: string, cwd: string): void {
+    const initial = process.env.CMUX_SURFACE_ID;
+    log("createSession initial surface:", initial);
+    if (initial) {
+      this.surfaces = [initial];
+      this.sendCommand(initial, `cd "${cwd}"`);
+    } else {
+      log("warning: CMUX_SURFACE_ID not set — are you running inside cmux?");
+    }
+  }
+
+  killSession(_name: string): void {
+    // No-op — we didn't create a workspace
+  }
+
+  attach(_name: string): void {
+    // cmux is a native macOS app — already visible
+  }
+
+  getActivePaneId(_session: string): string {
+    const id = this.surfaces[this.surfaces.length - 1] ?? "";
+    log("getActivePaneId →", id);
+    return id;
+  }
+
+  listPaneIds(_session: string): string[] {
+    log("listPaneIds →", this.surfaces);
+    return [...this.surfaces];
+  }
+
+  splitPane(
+    _target: string,
+    direction: "horizontal" | "vertical",
+    _sizePercent: number,
+    cwd: string
+  ): void {
+    const cmuxDir = direction === "horizontal" ? "right" : "down";
+    // new-split returns "OK surface:<ref> workspace:<ref>"
+    const output = run(`cmux new-split ${cmuxDir}`);
+
+    const match = output.match(/surface:(\S+)/);
+    if (match) {
+      const newRef = `surface:${match[1]}`;
+      log("splitPane new surface:", newRef);
+      this.surfaces.push(newRef);
+      // cd into worktree on the new surface
+      this.sendCommand(newRef, `cd "${cwd}"`);
+    } else {
+      log("warning: could not parse surface from new-split output:", output);
+    }
+    log("splitPane surfaces now:", this.surfaces);
+  }
+
+  focusPane(_paneId: string): void {
+    // no-op — cmux auto-focuses after split
+  }
+
+  renamePaneTitle(paneId: string, name: string): void {
+    try {
+      execSync(`cmux rename-tab --surface ${paneId} "${name}"`, { stdio: "ignore" });
+    } catch {
+      // ignore
+    }
+  }
+
+  sendCommand(target: string, command: string): void {
+    if (!command || !target) {
+      log("sendCommand skipped — target:", target, "command:", command);
+      return;
+    }
+    log("sendCommand →", target, command);
+    execSync(
+      `cmux send --surface ${target} "${command.replace(/"/g, '\\"')}"`,
+      { stdio: "ignore" }
+    );
+    execSync(`cmux send-key --surface ${target} enter`, { stdio: "ignore" });
+  }
+
+  isInsideSession(): boolean {
+    return !!process.env.CMUX_WORKSPACE_ID;
+  }
+
+  detectFirstPane(): string | undefined {
+    // Return the first surface in the workspace (where the agent typically runs)
+    // NOT the current surface (which is where `orche review` was called)
+    try {
+      const output = run(`cmux tree --json`);
+      const tree = JSON.parse(output);
+      // Walk the tree to find the first terminal surface
+      const first = this.findFirstSurface(tree);
+      if (first) return first;
+    } catch {
+      // fallback
+    }
+    return process.env.CMUX_SURFACE_ID ?? undefined;
+  }
+
+  private findFirstSurface(node: unknown): string | null {
+    if (!node || typeof node !== 'object') return null;
+    const obj = node as Record<string, unknown>;
+    if (obj.surface_ref && typeof obj.surface_ref === 'string') {
+      // Skip the current surface
+      if (obj.surface_ref !== `surface:${process.env.CMUX_SURFACE_ID}`) {
+        return obj.surface_ref as string;
+      }
+    }
+    // Recurse into arrays and objects
+    for (const val of Object.values(obj)) {
+      if (Array.isArray(val)) {
+        for (const item of val) {
+          const found = this.findFirstSurface(item);
+          if (found) return found;
+        }
+      } else if (val && typeof val === 'object') {
+        const found = this.findFirstSurface(val);
+        if (found) return found;
+      }
+    }
+    return null;
+  }
+}

package/src/multiplexers/tmux.ts

@@ -0,0 +1,96 @@
+import { execSync } from "node:child_process";
+import type { Multiplexer } from "../multiplexer.js";
+
+function esc(str: string): string {
+  return `"${str.replace(/"/g, '\\"')}"`;
+}
+
+export class TmuxMultiplexer implements Multiplexer {
+  readonly name = "tmux";
+
+  createSession(name: string, cwd: string): void {
+    // Kill existing session with same name
+    try {
+      execSync(`tmux kill-session -t "${name}"`, { stdio: "ignore" });
+    } catch {
+      // no existing session
+    }
+    execSync(`tmux new-session -d -s "${name}" -c "${cwd}"`, { stdio: "ignore" });
+    execSync(`tmux set-option -t "${name}" mouse on`, { stdio: "ignore" });
+  }
+
+  killSession(name: string): void {
+    try {
+      execSync(`tmux kill-session -t "${name}"`, { stdio: "ignore" });
+    } catch {
+      // ignore
+    }
+  }
+
+  attach(name: string): void {
+    if (process.env.TMUX) {
+      execSync(`tmux switch-client -t "${name}"`, { stdio: "inherit" });
+    } else {
+      execSync(`tmux attach-session -t "${name}"`, { stdio: "inherit" });
+    }
+  }
+
+  getActivePaneId(session: string): string {
+    return execSync(`tmux display-message -t ${session} -p "#{pane_id}"`)
+      .toString()
+      .trim();
+  }
+
+  listPaneIds(session: string): string[] {
+    return execSync(`tmux list-panes -t ${session} -F "#{pane_id}"`)
+      .toString()
+      .trim()
+      .split("\n");
+  }
+
+  splitPane(
+    target: string,
+    direction: "horizontal" | "vertical",
+    sizePercent: number,
+    cwd: string
+  ): void {
+    const flag = direction === "horizontal" ? "-h" : "-v";
+    execSync(
+      `tmux split-window ${flag} -t ${target} -p ${sizePercent} -c "${cwd}"`,
+      { stdio: "ignore" }
+    );
+  }
+
+  focusPane(paneId: string): void {
+    execSync(`tmux select-pane -t ${paneId}`, { stdio: "ignore" });
+  }
+
+  renamePaneTitle(paneId: string, name: string): void {
+    execSync(`tmux select-pane -t ${paneId} -T ${esc(name)}`, { stdio: "ignore" });
+  }
+
+  sendCommand(target: string, command: string): void {
+    execSync(`tmux send-keys -t ${target} ${esc(command)} Enter`);
+  }
+
+  isInsideSession(): boolean {
+    return !!process.env.TMUX;
+  }
+
+  detectFirstPane(): string | undefined {
+    if (!process.env.TMUX) return undefined;
+    try {
+      const sessionName = execSync("tmux display-message -p '#S'")
+        .toString()
+        .trim();
+      const paneId = execSync(
+        `tmux list-panes -t "${sessionName}" -F "#{pane_id}" | head -1`
+      )
+        .toString()
+        .trim();
+      return paneId || undefined;
+    } catch {
+      return undefined;
+    }
+  }
+}

package/src/review-manager.ts

@@ -0,0 +1,283 @@
+import { execSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+  createWriteStream,
+} from "node:fs";
+import path from "node:path";
+import https from "node:https";
+
+const REPO = "taranek/orche";
+const TAG_PREFIX = "review-v";
+
+// Pin review binary version to the CLI version
+const CLI_VERSION = (() => {
+  try {
+    const pkgPath = new URL("../package.json", import.meta.url).pathname;
+    return JSON.parse(readFileSync(pkgPath, "utf-8")).version as string;
+  } catch {
+    return null;
+  }
+})();
+const ORCHE_DIR = path.join(
+  process.env.HOME || process.env.USERPROFILE || "~",
+  ".orche",
+  "review"
+);
+const BIN_DIR = path.join(ORCHE_DIR, "bin");
+const VERSION_FILE = path.join(ORCHE_DIR, "version.json");
+const LOCK_FILE = path.join(ORCHE_DIR, ".downloading");
+
+interface VersionInfo {
+  version: string;
+  downloadedAt: string;
+  lastCheckedAt: string;
+}
+
+interface ReleaseAsset {
+  name: string;
+  browser_download_url: string;
+}
+
+interface GitHubRelease {
+  tag_name: string;
+  assets: ReleaseAsset[];
+}
+
+function readVersionInfo(): VersionInfo | null {
+  if (!existsSync(VERSION_FILE)) return null;
+  try {
+    return JSON.parse(readFileSync(VERSION_FILE, "utf-8")) as VersionInfo;
+  } catch {
+    return null;
+  }
+}
+
+function writeVersionInfo(info: VersionInfo): void {
+  mkdirSync(ORCHE_DIR, { recursive: true });
+  writeFileSync(VERSION_FILE, JSON.stringify(info, null, 2));
+}
+
+function getPlatformKey(): { platform: string; arch: string; ext: string } {
+  const arch = process.arch === "arm64" ? "arm64" : "x64";
+  if (process.platform === "darwin") {
+    return { platform: "mac", arch, ext: "zip" };
+  }
+  if (process.platform === "linux") {
+    return { platform: "linux", arch, ext: "tar.gz" };
+  }
+  throw new Error(`unsupported platform: ${process.platform}`);
+}
+
+function getExecutablePath(): string {
+  if (process.platform === "darwin") {
+    return path.join(BIN_DIR, "orche-review.app", "Contents", "MacOS", "orche-review");
+  }
+  return path.join(BIN_DIR, "orche-review", "orche-review");
+}
+
+function fetchJson<T>(url: string): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const get = (requestUrl: string) => {
+      https.get(
+        requestUrl,
+        { headers: { "User-Agent": "orche-cli", Accept: "application/vnd.github+json" } },
+        (res) => {
+          if (res.statusCode === 301 || res.statusCode === 302) {
+            get(res.headers.location!);
+            return;
+          }
+          if (res.statusCode !== 200) {
+            reject(new Error(`HTTP ${res.statusCode} from ${requestUrl}`));
+            return;
+          }
+          let data = "";
+          res.on("data", (chunk) => (data += chunk));
+          res.on("end", () => resolve(JSON.parse(data) as T));
+          res.on("error", reject);
+        }
+      ).on("error", reject);
+    };
+    get(url);
+  });
+}
+
+function download(url: string, dest: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    mkdirSync(path.dirname(dest), { recursive: true });
+    const file = createWriteStream(dest);
+
+    const get = (requestUrl: string) => {
+      https.get(requestUrl, { headers: { "User-Agent": "orche-cli" } }, (res) => {
+        if (res.statusCode === 301 || res.statusCode === 302) {
+          get(res.headers.location!);
+          return;
+        }
+        if (res.statusCode !== 200) {
+          file.close();
+          reject(new Error(`HTTP ${res.statusCode} downloading ${requestUrl}`));
+          return;
+        }
+
+        const totalBytes = parseInt(res.headers["content-length"] || "0", 10);
+        let downloadedBytes = 0;
+
+        res.on("data", (chunk: Buffer) => {
+          downloadedBytes += chunk.length;
+          if (totalBytes > 0) {
+            const pct = Math.round((downloadedBytes / totalBytes) * 100);
+            const mb = (downloadedBytes / 1024 / 1024).toFixed(1);
+            const totalMb = (totalBytes / 1024 / 1024).toFixed(1);
+            process.stderr.write(`\r  downloading: ${mb}/${totalMb} MB (${pct}%)`);
+          }
+        });
+
+        res.pipe(file);
+        file.on("finish", () => {
+          if (totalBytes > 0) process.stderr.write("\n");
+          file.close();
+          resolve();
+        });
+        file.on("error", reject);
+      }).on("error", reject);
+    };
+    get(url);
+  });
+}
+
+async function findRelease(): Promise<{
+  version: string;
+  downloadUrl: string;
+} | null> {
+  const releases = await fetchJson<GitHubRelease[]>(
+    `https://api.github.com/repos/${REPO}/releases`
+  );
+
+  // Find release matching CLI version, or fall back to latest review release
+  const targetTag = CLI_VERSION ? `${TAG_PREFIX}${CLI_VERSION}` : null;
+  const reviewRelease = targetTag
+    ? releases.find((r) => r.tag_name === targetTag)
+    : releases.find((r) => r.tag_name.startsWith(TAG_PREFIX));
+
+  if (!reviewRelease) return null;
+
+  const version = reviewRelease.tag_name.slice(TAG_PREFIX.length);
+  const { platform, arch, ext } = getPlatformKey();
+
+  // Match asset by platform and arch in filename
+  const asset = reviewRelease.assets.find((a) => {
+    const name = a.name.toLowerCase();
+    if (!name.includes(platform) || !name.endsWith(`.${ext}`) || name.includes("blockmap")) return false;
+    if (arch === "arm64") return name.includes("arm64");
+    return !name.includes("arm64");
+  });
+
+  if (!asset) return null;
+  return { version, downloadUrl: asset.browser_download_url };
+}
+
+async function downloadAndExtract(
+  url: string,
+  version: string
+): Promise<void> {
+  const tmpDir = path.join(ORCHE_DIR, ".tmp");
+  mkdirSync(tmpDir, { recursive: true });
+
+  const { ext } = getPlatformKey();
+  const archivePath = path.join(tmpDir, `orche-review.${ext}`);
+
+  await download(url, archivePath);
+
+  // Clean existing bin directory
+  execSync(`rm -rf "${BIN_DIR}"`);
+  mkdirSync(BIN_DIR, { recursive: true });
+
+  // Extract
+  if (ext === "zip") {
+    execSync(`unzip -q -o "${archivePath}" -d "${BIN_DIR}"`);
+    // Clear macOS quarantine
+    try {
+      execSync(`xattr -cr "${BIN_DIR}"`, { stdio: "ignore" });
+    } catch {
+      // xattr may not exist on all systems
+    }
+  } else {
+    execSync(`tar xzf "${archivePath}" -C "${BIN_DIR}"`);
+  }
+
+  // Ensure executable permissions on Linux
+  if (process.platform === "linux") {
+    const executablePath = getExecutablePath();
+    if (existsSync(executablePath)) {
+      execSync(`chmod +x "${executablePath}"`);
+    }
+  }
+
+  // Write version info
+  writeVersionInfo({
+    version,
+    downloadedAt: new Date().toISOString(),
+    lastCheckedAt: new Date().toISOString(),
+  });
+
+  // Cleanup
+  execSync(`rm -rf "${tmpDir}"`);
+}
+
+function acquireLock(): boolean {
+  if (existsSync(LOCK_FILE)) {
+    try {
+      const lockTime = parseInt(readFileSync(LOCK_FILE, "utf-8"), 10);
+      // Stale if older than 10 minutes
+      if (Date.now() - lockTime < 10 * 60 * 1000) return false;
+    } catch {
+      // corrupt lock, proceed
+    }
+  }
+  mkdirSync(ORCHE_DIR, { recursive: true });
+  writeFileSync(LOCK_FILE, String(Date.now()));
+  return true;
+}
+
+function releaseLock(): void {
+  try {
+    unlinkSync(LOCK_FILE);
+  } catch {
+    // ignore
+  }
+}
+
+export async function getReviewBinaryPath(): Promise<string> {
+  const executablePath = getExecutablePath();
+  const info = readVersionInfo();
+  const needsDownload = !info || !existsSync(executablePath)
+    || (CLI_VERSION && info.version !== CLI_VERSION);
+
+  if (!needsDownload) return executablePath;
+
+  if (info && CLI_VERSION && info.version !== CLI_VERSION) {
+    console.log(`review app version mismatch (${info.version} → ${CLI_VERSION}), updating...`);
+  } else {
+    console.log("review app not found, downloading...");
+  }
+
+  if (!acquireLock()) {
+    throw new Error("another download is in progress — try again in a moment");
+  }
+  try {
+    const release = await findRelease();
+    if (!release) {
+      throw new Error(
+        "no review app release found — check https://github.com/taranek/orche/releases"
+      );
+    }
+    await downloadAndExtract(release.downloadUrl, release.version);
+  } finally {
+    releaseLock();
+  }
+
+  return executablePath;
+}

package/src/types.ts

@@ -0,0 +1,24 @@
+export interface PaneConfig {
+  name: string;
+  command: string;
+  /** Percentage size of this pane (optional, defaults to equal) */
+  size?: number;
+}
+
+export interface SplitConfig {
+  direction: "horizontal" | "vertical";
+  panes: (PaneConfig | SplitConfig)[];
+  /** Percentage size of this split (optional, defaults to equal) */
+  size?: number;
+}
+
+export type MultiplexerType = "tmux" | "cmux" | "auto";
+
+export interface AgentsConfig {
+  multiplexer?: MultiplexerType;
+  layout: PaneConfig | SplitConfig;
+}
+
+export function isSplit(node: PaneConfig | SplitConfig): node is SplitConfig {
+  return "direction" in node && "panes" in node;
+}