tmux-ide 2.6.0 → 2.6.1

package/bin/cli.js

@@ -2340,7 +2340,7 @@ function resolveTuiLaunch(input) {
   const reasons = [];
   if (!input.checkoutExists) {
     reasons.push(
-      "the TUI widget sources are absent (they ship only in a cloned tmux-ide checkout)"
+      "the TUI widget sources are absent (reinstall tmux-ide \u2014 releases since v2.6.1 ship them)"
     );
   }
   if (!input.bunAvailable) {
@@ -10975,7 +10975,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "tmux-ide",
-      version: "2.6.0",
+      version: "2.6.1",
       description: "Turn any project into a tmux-powered terminal IDE with a simple ide.yml",
       type: "module",
       bin: {
@@ -10987,7 +10987,13 @@ var require_package = __commonJS({
         "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",
@@ -11035,7 +11041,6 @@ var require_package = __commonJS({
         "@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",
         "@parcel/watcher": "^2.5.6",
         "@types/ws": "^8.18.1",
@@ -11068,6 +11073,9 @@ var require_package = __commonJS({
         turbo: "^2.3.3",
         typescript: "^5.9.3",
         vitest: "^4.1.0"
+      },
+      optionalDependencies: {
+        "@opentui/core-darwin-arm64": "^0.1.88"
       }
     };
   }
@@ -12781,7 +12789,7 @@ function execBunWidget(surface, scriptPath, args, commandLabel, extraEnv = {}) {
   if (launch2.mode === "unavailable") {
     throw new IdeError(
       `\`tmux-ide ${commandLabel}\` is unavailable because ${launch2.reasons.join(" and ")}.
-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) \u2014 the TUI surfaces run on it. Sources ship with the npm package since v2.6.1.`,
       { code: "USAGE", exitCode: 1 }
     );
   }

package/bin/cli.ts

@@ -264,7 +264,7 @@ 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 },
     );
   }

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.6.1",
   "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",
@@ -60,7 +66,6 @@
     "@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",
     "@parcel/watcher": "^2.5.6",
     "@types/ws": "^8.18.1",
@@ -93,5 +98,8 @@
     "turbo": "^2.3.3",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0"
+  },
+  "optionalDependencies": {
+    "@opentui/core-darwin-arm64": "^0.1.88"
   }
 }

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>;
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Wire codes for the v2 action dispatcher's error envelope. Codes are
+ * stable identifiers — never rename without a coordinated dashboard
+ * release. New codes go at the bottom of the union.
+ *
+ * The runtime class that throws these (`ActionError`, `TerminalCwdError`,
+ * etc.) lives in @tmux-ide/daemon's command-center/actions/errors.ts; the
+ * type lives here so dashboards and other UI clients can branch on the
+ * code without reaching into daemon-internal modules.
+ */
+export type ActionErrorCode =
+  | "project_not_found"
+  | "cwd_not_found"
+  | "cwd_not_directory"
+  | "cwd_stat_failed"
+  | "session_already_running"
+  | "session_not_running"
+  | "launch_failed"
+  | "stop_failed"
+  | "terminal_not_found"
+  | "validation_failed"
+  | "task_not_found"
+  | "goal_not_found"
+  | "milestone_not_found"
+  | "mission_not_set"
+  | "task_dependency_unmet"
+  | "task_already_assigned"
+  | "skill_invalid"
+  | "skill_not_found"
+  | "ide_yml_missing"
+  | "config_path_invalid"
+  | "config_validation_failed"
+  | "validation_assertion_not_found"
+  | "webhook_not_found"
+  | "webhook_test_failed"
+  | "remote_access_restart_failed"
+  | "shutdown_already_in_progress"
+  | "bad_request"
+  | "thread_not_found"
+  | "permission_request_not_found"
+  | "internal";

package/packages/contracts/src/domain.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// PaneInfo — live tmux pane metadata (from src/command-center/discovery.ts)
+// ---------------------------------------------------------------------------
+
+export const PaneInfoSchemaZ = z.object({
+  id: z.string(),
+  index: z.number(),
+  title: z.string(),
+  currentCommand: z.string(),
+  width: z.number(),
+  height: z.number(),
+  active: z.boolean(),
+  role: z
+    .enum(["lead", "teammate", "planner", "validator", "researcher", "widget", "shell"])
+    .nullable(),
+  name: z.string().nullable(),
+  type: z.string().nullable(),
+});
+
+// ---------------------------------------------------------------------------
+// SessionOverview — minimal session listing entry
+// ---------------------------------------------------------------------------
+
+export const SessionOverviewSchemaZ = z.object({
+  name: z.string(),
+  dir: z.string(),
+});
+
+// ---------------------------------------------------------------------------
+// Inferred types
+// ---------------------------------------------------------------------------
+
+export type PaneInfo = z.infer<typeof PaneInfoSchemaZ>;
+export type SessionOverview = z.infer<typeof SessionOverviewSchemaZ>;