tmux-ide 2.6.0 → 2.7.0

package/bin/cli.ts

@@ -9,8 +9,17 @@ import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
+// The node-runnable CLI path that spawned TUI surfaces shell back to (the app's
+// async fleet poll + `detect --write`). When we're the published `bin/cli.js`
+// this file IS it; under dev (`bun bin/cli.ts`) it's the built sibling
+// `bin/cli.js`. Forwarded to surfaces as TMUX_IDE_CLI so the COMPILED TUI binary
+// — whose own `import.meta.url` is a virtual bunfs path with no real cli.js next
+// to it — can still find the CLI to run its subprocesses.
+const selfPath = fileURLToPath(import.meta.url);
+const nodeCliPath = selfPath.endsWith(".js") ? selfPath : resolve(__dirname, "cli.js");
 import { launch } from "../packages/daemon/src/launch.ts";
-import { shouldOpenCockpit } from "../packages/daemon/src/tui/team/entry.ts";
+import { resolveEntry } from "../packages/daemon/src/tui/team/entry.ts";
+import { loadAppConfig } from "../packages/daemon/src/lib/app-config.ts";
 import {
   resolveTuiLaunch,
   findCompiledTui,
@@ -110,6 +119,7 @@ const knownCommands = new Set([
   "send",
   "settings",
   "team",
+  "app",
   "switcher",
   "wait",
   "events",
@@ -177,6 +187,7 @@ ${bold("Usage:")}
                               ${dim("(--resume-agents revives claude conversations via claude --resume)")}
   ${cyan("tmux-ide attach")}             ${dim("Reattach to a running session")}
   ${cyan("tmux-ide team")} [--json]      ${dim("TUI over all tmux sessions (--json prints fleet state)")}
+  ${cyan("tmux-ide app")} [session]      ${dim("Unified app: fleet home + live session mirror (bare = home)")}
   ${cyan("tmux-ide switcher")}           ${dim("Compact session picker (opens in the M-p popup on adopted sessions)")}
   ${cyan("tmux-ide wait agent-status")} <session> --status <s> [--timeout <ms>]
                               ${dim("Block until a session reaches a status (exit 0 match / 1 timeout)")}
@@ -264,12 +275,17 @@ function execBunWidget(
   if (launch.mode === "unavailable") {
     throw new IdeError(
       `\`tmux-ide ${commandLabel}\` is unavailable because ${launch.reasons.join(" and ")}.\n` +
-        `Run it from a cloned tmux-ide checkout with bun installed, or install a release that ships the compiled binary.`,
+        `Install bun (https://bun.sh) — the TUI surfaces run on it. Sources ship with the npm package since v2.6.1.`,
       { code: "USAGE", exitCode: 1 },
     );
   }
 
-  const env = { ...process.env, TMUX_IDE_CWD: process.cwd(), ...extraEnv };
+  const env = {
+    ...process.env,
+    TMUX_IDE_CWD: process.cwd(),
+    TMUX_IDE_CLI: nodeCliPath,
+    ...extraEnv,
+  };
   if (launch.mode === "bun") {
     // Spawn from the repo root so bun finds `bunfig.toml` (the @opentui/solid
     // JSX preload). Without this, running from any other cwd — e.g. bare
@@ -302,6 +318,7 @@ async function printFleetJson(): Promise<void> {
 }
 
 const teamScriptPath = resolve(__dirname, "../packages/daemon/src/tui/team/index.tsx");
+const appScriptPath = resolve(__dirname, "../packages/daemon/src/tui/mirror/app.tsx");
 
 // `tmux-ide team` runs the standalone full-screen cockpit (the OpenTUI app owns
 // the whole terminal). The floating switcher popup (M-p on adopted sessions)
@@ -310,6 +327,13 @@ function launchTeamCockpit(): void {
   execBunWidget("team", teamScriptPath, [], "team");
 }
 
+// The unified app as the front door (M22.6): bare `tmux-ide` opens `tmux-ide
+// app`'s HOME panel when `app.frontDoor` is on and there's nothing else to
+// launch. Same entry as the explicit `app` command with no session positional.
+function launchApp(): void {
+  execBunWidget("app", appScriptPath, [], "app");
+}
+
 try {
   switch (command) {
     case "start": {
@@ -332,13 +356,23 @@ try {
       }
       const targetDir = resolve(startTargetDir || ".");
       const hasIdeYml = existsSync(join(targetDir, "ide.yml"));
-      if (shouldOpenCockpit(hasIdeYml, values.team === true)) {
-        // No project here (or --team): the cockpit is the front door.
+      // M22.6 — the front-door decision. `--team` always means the classic
+      // cockpit; a present ide.yml still auto-launches the project; otherwise
+      // `app.frontDoor` flips the default no-project entry to the unified app.
+      const entry = resolveEntry({
+        hasIdeYml,
+        teamFlag: values.team === true,
+        frontDoor: loadAppConfig().app.frontDoor,
+      });
+      if (entry !== "project") {
+        // No project to launch here. `--json` is a scripting surface — it always
+        // prints the fleet, whichever interactive front door is configured.
         if (json) {
           await printFleetJson();
           break;
         }
-        launchTeamCockpit();
+        if (entry === "app") launchApp();
+        else launchTeamCockpit();
         break;
       }
       await launch(startTargetDir, { json });
@@ -491,6 +525,16 @@ try {
       break;
     }
 
+    case "app": {
+      // The unified app (M18.1): sidebar fleet + a live tmux-session mirror.
+      // Bare `tmux-ide app` opens the HOME panel (fleet cards); an optional
+      // session positional boots straight into that session's mirror.
+      const session = positionals[1];
+      const appArgs = session ? [`--target=${session}`] : [];
+      execBunWidget("app", appScriptPath, appArgs, "app");
+      break;
+    }
+
     case "switcher": {
       // Runs the team app in PICKER mode inside a tmux `display-popup` (bound to
       // `M-p` on adopt). Picking a session `switch-client`s the invoking client
@@ -1338,6 +1382,19 @@ try {
     }
 
     case "update": {
+      // `--tui-binary`: download the per-platform TUI binary (the fallback that
+      // lets an npm install with no bun run the full cockpit). Explicit opt-in —
+      // never auto-fetched on install (it's ~70MB). See lib/tui-binary.ts.
+      if (values["tui-binary"] === true) {
+        const { downloadTuiBinary } = await import("../packages/daemon/src/lib/tui-binary.ts");
+        const { path } = await downloadTuiBinary({ log: (m) => console.error(m) });
+        if (json) {
+          console.log(JSON.stringify({ ok: true, path }, null, 2));
+        } else {
+          console.log(`TUI binary ready: ${path}`);
+        }
+        break;
+      }
       // Detect how tmux-ide was installed and act on the pending update: a dev
       // checkout prints the `git pull` hint; a global install prints (with
       // --dry-run) or runs its package manager's update command. `__dirname` is

package/bunfig.toml

@@ -0,0 +1,4 @@
+preload = ["@opentui/solid/preload"]
+
+[test]
+root = "./src"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmux-ide",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "Turn any project into a tmux-powered terminal IDE with a simple ide.yml",
   "type": "module",
   "bin": {
@@ -12,7 +12,13 @@
     "skill",
     "templates",
     "packages/daemon/dist",
-    "!packages/daemon/dist/tui"
+    "!packages/daemon/dist/tui",
+    "packages/daemon/src",
+    "bunfig.toml",
+    "packages/contracts/src",
+    "packages/tmux-bridge/src",
+    "packages/tmux-bridge/package.json",
+    "packages/contracts/package.json"
   ],
   "scripts": {
     "build": "pnpm build:cli",
@@ -59,16 +65,15 @@
   "dependencies": {
     "@hono/node-server": "^1.19.11",
     "@hono/zod-validator": "^0.7.6",
-    "@opentui/core": "^0.1.88",
-    "@opentui/core-darwin-arm64": "^0.1.88",
-    "@opentui/solid": "^0.1.88",
+    "@opentui/core": "^0.4.3",
+    "@opentui/solid": "^0.4.3",
     "@parcel/watcher": "^2.5.6",
     "@types/ws": "^8.18.1",
     "hono": "^4.12.8",
     "ignore": "^7.0.5",
     "js-yaml": "^4.1.1",
     "node-pty": "1.2.0-beta.12",
-    "solid-js": "^1.9.11",
+    "solid-js": "1.9.12",
     "ws": "^8.20.0",
     "zod": "^4.3.6"
   },
@@ -77,7 +82,10 @@
       "@parcel/watcher",
       "esbuild",
       "node-pty"
-    ]
+    ],
+    "overrides": {
+      "zod": "^4.3.6"
+    }
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
@@ -93,5 +101,8 @@
     "turbo": "^2.3.3",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0"
+  },
+  "optionalDependencies": {
+    "@opentui/core-darwin-arm64": "^0.4.3"
   }
 }

package/packages/contracts/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@tmux-ide/contracts",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}

package/packages/contracts/src/__tests__/ide-config.test.ts

@@ -0,0 +1,46 @@
+/**
+ * Schema tests for the `sidebar` ide.yml sugar (M15.2).
+ */
+import { describe, expect, it } from "vitest";
+import { IdeConfigSchema, SidebarConfigSchema } from "../ide-config";
+
+const base = { rows: [{ panes: [{ title: "shell" }] }] };
+
+describe("SidebarConfigSchema", () => {
+  it("accepts the boolean form", () => {
+    expect(SidebarConfigSchema.parse(true)).toBe(true);
+    expect(SidebarConfigSchema.parse(false)).toBe(false);
+  });
+
+  it("accepts the object form with an optional width", () => {
+    expect(SidebarConfigSchema.parse({ width: "30" })).toEqual({ width: "30" });
+    expect(SidebarConfigSchema.parse({})).toEqual({});
+  });
+
+  it("rejects a bare number", () => {
+    expect(() => SidebarConfigSchema.parse(30)).toThrow();
+  });
+});
+
+describe("IdeConfigSchema — sidebar", () => {
+  it("parses `sidebar: true`", () => {
+    const cfg = IdeConfigSchema.parse({ ...base, sidebar: true });
+    expect(cfg.sidebar).toBe(true);
+  });
+
+  it("parses `sidebar: { width }`", () => {
+    const cfg = IdeConfigSchema.parse({ ...base, sidebar: { width: "40" } });
+    expect(cfg.sidebar).toEqual({ width: "40" });
+  });
+
+  it("leaves sidebar undefined when omitted", () => {
+    expect(IdeConfigSchema.parse(base).sidebar).toBeUndefined();
+  });
+
+  it("accepts a pane of type sidebar", () => {
+    const cfg = IdeConfigSchema.parse({
+      rows: [{ panes: [{ title: "nav", type: "sidebar" }] }],
+    });
+    expect(cfg.rows[0]!.panes[0]!.type).toBe("sidebar");
+  });
+});

package/packages/contracts/src/__tests__/terminals.test.ts

@@ -0,0 +1,87 @@
+/**
+ * `createScriptTerminalId` determinism tests (G20-P1).
+ *
+ * The whole point of the script-derived id is determinism — two
+ * callers asking for "the run script for project X, scope Y, script
+ * Z" must collapse to one bridge. These tests pin that contract.
+ */
+
+import { describe, expect, it } from "vitest";
+import { createScriptTerminalId } from "../terminals";
+
+describe("createScriptTerminalId", () => {
+  it("is deterministic for the same input", async () => {
+    const a = await createScriptTerminalId({
+      projectId: "proj",
+      scopeId: "feat-x",
+      kind: "run",
+      script: "pnpm dev",
+    });
+    const b = await createScriptTerminalId({
+      projectId: "proj",
+      scopeId: "feat-x",
+      kind: "run",
+      script: "pnpm dev",
+    });
+    expect(a).toBe(b);
+    expect(a).toHaveLength(32);
+  });
+
+  it("changes when scopeId changes (same project + script)", async () => {
+    const a = await createScriptTerminalId({
+      projectId: "proj",
+      scopeId: "feat-x",
+      kind: "run",
+      script: "pnpm dev",
+    });
+    const b = await createScriptTerminalId({
+      projectId: "proj",
+      scopeId: "feat-y",
+      kind: "run",
+      script: "pnpm dev",
+    });
+    expect(a).not.toBe(b);
+  });
+
+  it("changes when kind changes", async () => {
+    const run = await createScriptTerminalId({
+      projectId: "proj",
+      scopeId: "feat-x",
+      kind: "run",
+      script: "pnpm dev",
+    });
+    const setup = await createScriptTerminalId({
+      projectId: "proj",
+      scopeId: "feat-x",
+      kind: "setup",
+      script: "pnpm dev",
+    });
+    expect(run).not.toBe(setup);
+  });
+
+  it("accepts taskId as a backward-compat alias for scopeId", async () => {
+    const viaScope = await createScriptTerminalId({
+      projectId: "proj",
+      scopeId: "feat-x",
+      kind: "run",
+      script: "pnpm dev",
+    });
+    const viaTask = await createScriptTerminalId({
+      projectId: "proj",
+      taskId: "feat-x",
+      kind: "run",
+      script: "pnpm dev",
+    });
+    expect(viaScope).toBe(viaTask);
+  });
+
+  it("rejects calls without scope or task", async () => {
+    await expect(
+      createScriptTerminalId({
+        projectId: "proj",
+        kind: "run",
+        script: "pnpm dev",
+      }),
+    ).rejects.toThrow(/scopeId/);
+  });
+});

package/packages/contracts/src/actions-contract.ts

@@ -0,0 +1,310 @@
+/**
+ * Action contract for the v2 dispatcher.
+ *
+ * CLI and command-center clients import the schemas in this file — input +
+ * output Zod shapes for every action. The server-side dispatcher wires each
+ * name to a handler that consumes the input and returns the typed result.
+ *
+ * Adding a new action:
+ *  1. Define `<Name>InputSchemaZ` and `<Name>ResultSchemaZ` here
+ *  2. Add it to {@link ActionContractsZ} below
+ *  3. Add a handler in `handlers/` and register it in `registry.ts`
+ *
+ * Invariants:
+ *  - Names are dot-namespaced (`<noun>.<verb>`)
+ *  - Both schemas live here so the wire format never drifts between clients
+ *  - Action names ARE the discriminator — keep them stable; never rename
+ */
+
+import { z } from "zod";
+import { IdeConfigSchema, PaneSchema } from "./ide-config.ts";
+
+// ---------------------------------------------------------------------------
+// project.openTerminal
+// ---------------------------------------------------------------------------
+
+export const ProjectOpenTerminalInputZ = z.object({
+  name: z.string().min(1),
+});
+export const ProjectOpenTerminalResultZ = z.object({
+  sessionName: z.string(),
+  cwd: z.string().min(1),
+  terminalTabId: z.string(),
+  /**
+   * `true` when the dispatcher had to launch the tmux session as part of
+   * resolving the terminal. `false` when the session was already running.
+   */
+  launched: z.boolean(),
+});
+
+// ---------------------------------------------------------------------------
+// project.launch
+// ---------------------------------------------------------------------------
+
+export const ProjectLaunchInputZ = z.object({
+  name: z.string().min(1),
+});
+export const ProjectLaunchResultZ = z.object({
+  sessionName: z.string(),
+  /**
+   * `false` when the session was already running (idempotent no-op),
+   * `true` when this call started a fresh session.
+   */
+  started: z.boolean(),
+});
+
+// ---------------------------------------------------------------------------
+// project.stop
+// ---------------------------------------------------------------------------
+
+export const ProjectStopInputZ = z.object({
+  name: z.string().min(1),
+});
+export const ProjectStopResultZ = z.object({
+  sessionName: z.string(),
+  /**
+   * `false` when no session was running (idempotent no-op),
+   * `true` when this call killed a session.
+   */
+  stopped: z.boolean(),
+});
+
+// ---------------------------------------------------------------------------
+// project.restart
+// ---------------------------------------------------------------------------
+
+export const ProjectRestartInputZ = z.object({
+  name: z.string().min(1),
+});
+export const ProjectRestartResultZ = z.object({
+  sessionName: z.string(),
+  restarted: z.literal(true),
+});
+
+// ---------------------------------------------------------------------------
+// project.activate
+// ---------------------------------------------------------------------------
+
+export const ProjectActivateInputZ = z.object({
+  name: z.string().min(1),
+});
+export const ProjectActivateResultZ = z.object({
+  active: z.boolean(),
+  projectName: z.string(),
+});
+
+// ---------------------------------------------------------------------------
+// terminal.respawn
+// ---------------------------------------------------------------------------
+
+export const TerminalRespawnInputZ = z.object({
+  sessionName: z.string().min(1),
+  terminalId: z.string().min(1),
+  /**
+   * Optional cwd override. Omit to respawn at the bridge's current cwd
+   * (re-using the `lastCwd` recorded by the PTY bridge).
+   */
+  cwd: z.string().min(1).optional(),
+});
+export const TerminalRespawnResultZ = z.object({
+  respawned: z.literal(true),
+  cwd: z.string().min(1),
+});
+
+// ---------------------------------------------------------------------------
+// terminal.stop
+// ---------------------------------------------------------------------------
+
+export const TerminalStopInputZ = z.object({
+  sessionName: z.string().min(1),
+  terminalId: z.string().min(1),
+});
+export const TerminalStopResultZ = z.object({
+  stopped: z.literal(true),
+});
+
+// ---------------------------------------------------------------------------
+// config.*
+// ---------------------------------------------------------------------------
+
+export const ConfigSetInputZ = z.object({
+  projectName: z.string().min(1).optional(),
+  path: z.string().min(1),
+  value: z.unknown(),
+});
+export const ConfigResultZ = z.object({
+  config: IdeConfigSchema,
+});
+
+export const ConfigAddPaneInputZ = PaneSchema.partial().extend({
+  projectName: z.string().min(1).optional(),
+  rowIndex: z.number().int().min(0),
+});
+export const ConfigAddPaneResultZ = ConfigResultZ;
+
+export const ConfigRemovePaneInputZ = z.object({
+  projectName: z.string().min(1).optional(),
+  rowIndex: z.number().int().min(0),
+  paneIndex: z.number().int().min(0),
+});
+export const ConfigRemovePaneResultZ = ConfigResultZ;
+
+export const ConfigAddRowInputZ = z.object({
+  projectName: z.string().min(1).optional(),
+  size: z.string().optional(),
+});
+export const ConfigAddRowResultZ = ConfigResultZ;
+
+export const ConfigEnableTeamInputZ = z.object({
+  projectName: z.string().min(1).optional(),
+  name: z.string().min(1).optional(),
+});
+export const ConfigEnableTeamResultZ = ConfigResultZ;
+
+export const ConfigDisableTeamInputZ = z.object({
+  projectName: z.string().min(1).optional(),
+});
+export const ConfigDisableTeamResultZ = ConfigResultZ;
+
+// ---------------------------------------------------------------------------
+// app.*
+// ---------------------------------------------------------------------------
+
+export const AppSetRemoteAccessInputZ = z.object({
+  enabled: z.boolean(),
+});
+export const AppSetRemoteAccessResultZ = z.object({
+  enabled: z.boolean(),
+  url: z.string().nullable(),
+  token: z.string().nullable(),
+  qrPayload: z.string().nullable(),
+});
+
+// ---------------------------------------------------------------------------
+// daemon.*
+// ---------------------------------------------------------------------------
+
+export const DaemonShutdownInputZ = z.object({
+  reason: z.string().optional(),
+});
+export const DaemonShutdownResultZ = z.object({
+  stopping: z.literal(true),
+});
+
+// ---------------------------------------------------------------------------
+// Registry of action contracts (name → input/output schemas)
+// ---------------------------------------------------------------------------
+
+export const ActionContractsZ = {
+  "project.openTerminal": {
+    input: ProjectOpenTerminalInputZ,
+    result: ProjectOpenTerminalResultZ,
+  },
+  "project.launch": {
+    input: ProjectLaunchInputZ,
+    result: ProjectLaunchResultZ,
+  },
+  "project.stop": {
+    input: ProjectStopInputZ,
+    result: ProjectStopResultZ,
+  },
+  "project.restart": {
+    input: ProjectRestartInputZ,
+    result: ProjectRestartResultZ,
+  },
+  "project.activate": {
+    input: ProjectActivateInputZ,
+    result: ProjectActivateResultZ,
+  },
+  "terminal.respawn": {
+    input: TerminalRespawnInputZ,
+    result: TerminalRespawnResultZ,
+  },
+  "terminal.stop": {
+    input: TerminalStopInputZ,
+    result: TerminalStopResultZ,
+  },
+  "config.set": {
+    input: ConfigSetInputZ,
+    result: ConfigResultZ,
+  },
+  "config.addPane": {
+    input: ConfigAddPaneInputZ,
+    result: ConfigAddPaneResultZ,
+  },
+  "config.removePane": {
+    input: ConfigRemovePaneInputZ,
+    result: ConfigRemovePaneResultZ,
+  },
+  "config.addRow": {
+    input: ConfigAddRowInputZ,
+    result: ConfigAddRowResultZ,
+  },
+  "config.enableTeam": {
+    input: ConfigEnableTeamInputZ,
+    result: ConfigEnableTeamResultZ,
+  },
+  "config.disableTeam": {
+    input: ConfigDisableTeamInputZ,
+    result: ConfigDisableTeamResultZ,
+  },
+  "app.setRemoteAccess": {
+    input: AppSetRemoteAccessInputZ,
+    result: AppSetRemoteAccessResultZ,
+  },
+  "daemon.shutdown": {
+    input: DaemonShutdownInputZ,
+    result: DaemonShutdownResultZ,
+  },
+} as const;
+
+export type ActionName = keyof typeof ActionContractsZ;
+
+export const ACTION_NAMES = Object.keys(ActionContractsZ) as ActionName[];
+
+// ---------------------------------------------------------------------------
+// Typed input / result helpers
+// ---------------------------------------------------------------------------
+
+export type ActionInput<N extends ActionName> = z.infer<(typeof ActionContractsZ)[N]["input"]>;
+export type ActionResult<N extends ActionName> = z.infer<(typeof ActionContractsZ)[N]["result"]>;
+
+// ---------------------------------------------------------------------------
+// Wire envelope (what the HTTP endpoint actually returns)
+// ---------------------------------------------------------------------------
+
+export interface ActionErrorEnvelope {
+  ok: false;
+  error: {
+    code: string;
+    message: string;
+    details?: unknown;
+  };
+}
+
+export interface ActionOkEnvelope<R> {
+  ok: true;
+  result: R;
+}
+
+export type ActionResponse<N extends ActionName> =
+  | ActionOkEnvelope<ActionResult<N>>
+  | ActionErrorEnvelope;
+
+/**
+ * Validate that a string is a known action name. Used by the dispatcher to
+ * narrow URL params before looking up the handler.
+ */
+export function isActionName(name: string): name is ActionName {
+  return name in ActionContractsZ;
+}
+
+/**
+ * Helper for a tagged WS broadcast frame so subscribers can decode without
+ * special-casing every action name.
+ */
+export interface ActionCompleteFrame<N extends ActionName = ActionName> {
+  type: "action.complete";
+  name: N;
+  result: ActionResult<N>;
+}