tmux-ide 2.6.0 → 2.7.0

package/packages/daemon/src/command-center/actions/errors.ts

@@ -0,0 +1,105 @@
+/**
+ * Typed errors for the v2 action dispatcher. Every error path through a
+ * handler funnels into one of these so the dispatcher can map to the
+ * `{ ok: false, error: { code, message, details? } }` envelope without
+ * stringly-typed catches.
+ *
+ * Codes are stable wire identifiers — never rename without a coordinated
+ * dashboard release. New codes go at the bottom of the union.
+ */
+
+import { TerminalCwdError, type TerminalCwdErrorReason } from "../../server/pty-bridge.ts";
+
+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";
+
+export class ActionError extends Error {
+  readonly code: ActionErrorCode;
+  readonly details: unknown | undefined;
+
+  constructor(args: {
+    code: ActionErrorCode;
+    message: string;
+    details?: unknown;
+    cause?: unknown;
+  }) {
+    super(
+      args.message,
+      args.cause !== undefined ? { cause: args.cause as Error | undefined } : undefined,
+    );
+    this.name = "ActionError";
+    this.code = args.code;
+    this.details = args.details;
+  }
+
+  toEnvelope(): {
+    code: ActionErrorCode;
+    message: string;
+    details?: unknown;
+  } {
+    return this.details !== undefined
+      ? { code: this.code, message: this.message, details: this.details }
+      : { code: this.code, message: this.message };
+  }
+}
+
+const CWD_REASON_TO_CODE: Record<TerminalCwdErrorReason, ActionErrorCode> = {
+  notFound: "cwd_not_found",
+  notDirectory: "cwd_not_directory",
+  statFailed: "cwd_stat_failed",
+};
+
+/**
+ * Translate a {@link TerminalCwdError} into an {@link ActionError} with the
+ * matching wire code. The cwd is preserved in `details` so the dashboard can
+ * surface it without re-parsing the error message.
+ */
+export function actionErrorFromCwdError(err: TerminalCwdError): ActionError {
+  return new ActionError({
+    code: CWD_REASON_TO_CODE[err.reason],
+    message: err.message,
+    details: { cwd: err.cwd, reason: err.reason },
+    cause: err,
+  });
+}
+
+/**
+ * Wrap an unknown thrown value as an `internal` ActionError. Used as the
+ * last-resort branch in dispatcher catch blocks so handlers never leak raw
+ * Error stacks across the wire.
+ */
+export function wrapInternalError(err: unknown): ActionError {
+  if (err instanceof ActionError) return err;
+  if (err instanceof TerminalCwdError) return actionErrorFromCwdError(err);
+  const message = err instanceof Error ? err.message : String(err);
+  return new ActionError({ code: "internal", message, cause: err });
+}

package/packages/daemon/src/command-center/actions/handlers/_project-context.ts

@@ -0,0 +1,30 @@
+import { basename } from "node:path";
+import { getSessionName } from "../../../lib/yaml-io.ts";
+import { resolveProject, type ProjectResolverDeps } from "./_resolve-project.ts";
+
+export interface ProjectContextDeps extends ProjectResolverDeps {
+  cwd?: string;
+}
+
+export interface ProjectContextInput {
+  projectName?: string;
+}
+
+export interface ProjectContext {
+  dir: string;
+  sessionName: string;
+}
+
+export function resolveProjectContext(
+  input: ProjectContextInput,
+  deps: ProjectContextDeps = {},
+): ProjectContext {
+  if (input.projectName) {
+    const project = resolveProject(input.projectName, deps);
+    return { dir: project.dir, sessionName: project.sessionName };
+  }
+
+  const dir = deps.cwd ?? process.cwd();
+  const sessionName = getSessionName(dir).name || basename(dir);
+  return { dir, sessionName };
+}

package/packages/daemon/src/command-center/actions/handlers/_resolve-project.ts

@@ -0,0 +1,78 @@
+/**
+ * Shared helper: resolve a registered project by name and project the
+ * fields the action handlers actually consume.
+ *
+ * Lives in handlers/ so the registry stays the only public surface; tests
+ * import from here directly.
+ */
+
+import { getProject as getRegisteredProject } from "../../../lib/project-registry.ts";
+import {
+  getSessionCwd as getSessionCwdDefault,
+  hasSession as hasSessionDefault,
+} from "@tmux-ide/tmux-bridge";
+import type { RegisteredProject } from "../../../schemas/registry.ts";
+import { ActionError } from "../errors.ts";
+
+export interface ResolvedProject {
+  name: string;
+  dir: string;
+  sessionName: string;
+  /**
+   * `true` when the project was resolved from a live tmux session
+   * (rather than the registry). Useful for handlers that want to
+   * auto-register on first action — out of scope for this slice but
+   * makes the intent explicit at the boundary.
+   */
+  fromLiveSession: boolean;
+}
+
+export interface ProjectResolverDeps {
+  /** Override for tests — must satisfy the same contract as `getProject`. */
+  getProject?: (name: string) => RegisteredProject | null;
+  /** Override the live-session existence probe. */
+  hasSession?: (session: string) => boolean;
+  /** Override the live-session cwd lookup. */
+  getSessionCwd?: (session: string) => string | null;
+}
+
+/**
+ * Resolve a project by name. The registry is the canonical source of
+ * truth, but as a fallback we also accept a live tmux session by the
+ * same name — the dashboard merges registered projects + live sessions
+ * in its sidebar, so action handlers must accept either. Throws an
+ * {@link ActionError} with code `project_not_found` when neither path
+ * succeeds.
+ *
+ * Note: the registry does not currently persist a session name distinct
+ * from the project name, so the session name returned here mirrors the
+ * project name. If they diverge in the future, this is the only call site
+ * that needs to change.
+ */
+export function resolveProject(name: string, deps: ProjectResolverDeps = {}): ResolvedProject {
+  const lookup = deps.getProject ?? getRegisteredProject;
+  const project = lookup(name);
+  if (project) {
+    return {
+      name: project.name,
+      dir: project.dir,
+      sessionName: project.name,
+      fromLiveSession: false,
+    };
+  }
+
+  // Registry miss — fall back to a live tmux session of the same name.
+  const hasSession = deps.hasSession ?? hasSessionDefault;
+  if (hasSession(name)) {
+    const cwd = (deps.getSessionCwd ?? getSessionCwdDefault)(name);
+    if (cwd) {
+      return { name, dir: cwd, sessionName: name, fromLiveSession: true };
+    }
+  }
+
+  throw new ActionError({
+    code: "project_not_found",
+    message: `Project "${name}" not found in registry or as a live tmux session`,
+    details: { name },
+  });
+}

package/packages/daemon/src/command-center/actions/handlers/app-set-remote-access.ts

@@ -0,0 +1,118 @@
+import { hostname, networkInterfaces } from "node:os";
+import { generateAuthToken } from "../../../lib/auth-token.ts";
+import { readAppSettings, writeAppSettings, type AppSettings } from "../../../lib/app-settings.ts";
+import type { ActionInput, ActionResult } from "../contract.ts";
+
+export interface RemoteAccessRestartRequest {
+  enabled: boolean;
+  bindHostname: "0.0.0.0" | "127.0.0.1";
+  token: string | null;
+  port?: number;
+}
+
+export interface RemoteAccessRestartResult {
+  port?: number;
+  host?: string;
+}
+
+export interface AppSetRemoteAccessDeps {
+  readSettings?: () => AppSettings;
+  writeSettings?: (next: AppSettings) => void;
+  generateToken?: () => string;
+  restartDaemon?: (
+    request: RemoteAccessRestartRequest,
+  ) => Promise<RemoteAccessRestartResult> | RemoteAccessRestartResult;
+  deferRestart?: (restart: () => void) => void;
+  port?: number;
+  host?: string;
+}
+
+let remoteAccessRestartBackend:
+  | ((
+      request: RemoteAccessRestartRequest,
+    ) => Promise<RemoteAccessRestartResult> | RemoteAccessRestartResult)
+  | null = null;
+
+export function setRemoteAccessRestartBackend(
+  backend:
+    | ((
+        request: RemoteAccessRestartRequest,
+      ) => Promise<RemoteAccessRestartResult> | RemoteAccessRestartResult)
+    | null,
+): void {
+  remoteAccessRestartBackend = backend;
+}
+
+function currentPort(deps: AppSetRemoteAccessDeps): number {
+  const envPort = Number(process.env.TMUX_IDE_DAEMON_PORT);
+  return deps.port ?? (Number.isInteger(envPort) && envPort > 0 ? envPort : 6060);
+}
+
+function primaryLanHost(): string {
+  const interfaces = networkInterfaces();
+  for (const entries of Object.values(interfaces)) {
+    for (const entry of entries ?? []) {
+      if (entry.family === "IPv4" && !entry.internal) return entry.address;
+    }
+  }
+  return hostname();
+}
+
+function buildUrl(host: string, port: number): string {
+  return `http://${host}:${port}`;
+}
+
+function defaultDeferRestart(restart: () => void): void {
+  setImmediate(restart);
+}
+
+export async function appSetRemoteAccessHandler(
+  input: ActionInput<"app.setRemoteAccess">,
+  deps: AppSetRemoteAccessDeps = {},
+): Promise<ActionResult<"app.setRemoteAccess">> {
+  const readSettings = deps.readSettings ?? readAppSettings;
+  const writeSettings = deps.writeSettings ?? writeAppSettings;
+  const nextEnabled = input.enabled;
+  const current = readSettings();
+  const token = nextEnabled
+    ? (current.remoteAccess.token ?? (deps.generateToken ?? generateAuthToken)())
+    : null;
+  const next: AppSettings = {
+    ...current,
+    remoteAccess: { enabled: nextEnabled, token },
+  };
+
+  writeSettings(next);
+
+  const port = currentPort(deps);
+  const request: RemoteAccessRestartRequest = {
+    enabled: nextEnabled,
+    bindHostname: nextEnabled ? "0.0.0.0" : "127.0.0.1",
+    token,
+    port,
+  };
+  const restartDaemon = deps.restartDaemon ?? remoteAccessRestartBackend;
+  if (restartDaemon) {
+    (deps.deferRestart ?? defaultDeferRestart)(() => {
+      void Promise.resolve(restartDaemon(request)).catch((err) => {
+        console.error(
+          `[actions] Failed to restart daemon for remote access: ${(err as Error).message ?? String(err)}`,
+        );
+      });
+    });
+  }
+
+  if (!nextEnabled) {
+    return { enabled: false, url: null, token: null, qrPayload: null };
+  }
+
+  const host = deps.host ?? primaryLanHost();
+  const url = buildUrl(host, port);
+
+  return {
+    enabled: true,
+    url,
+    token,
+    qrPayload: `${url}?token=${encodeURIComponent(token ?? "")}`,
+  };
+}

package/packages/daemon/src/command-center/actions/handlers/config-actions.ts

@@ -0,0 +1,113 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import {
+  configAddPane,
+  configAddRow,
+  configDisableTeam,
+  configEnableTeam,
+  configRemovePane,
+  configSetValue,
+} from "../../../config.ts";
+import { broadcastConfigChanged as broadcastConfigChangedDefault } from "../../ws-events.ts";
+import { ActionError } from "../errors.ts";
+import type { ActionInput, ActionResult } from "../contract.ts";
+import { resolveProjectContext, type ProjectContextDeps } from "./_project-context.ts";
+
+interface ConfigActionDeps extends ProjectContextDeps {
+  broadcastConfigChanged?: (sessionName: string) => void;
+}
+
+function mutateConfigAction<Result>(
+  input: { projectName?: string },
+  deps: ConfigActionDeps,
+  fn: (dir: string) => Result,
+): Result {
+  const context = resolveProjectContext(input, deps);
+  if (!existsSync(join(context.dir, "ide.yml"))) {
+    throw new ActionError({
+      code: "ide_yml_missing",
+      message: "ide.yml was not found",
+      details: { dir: context.dir },
+    });
+  }
+  try {
+    const result = fn(context.dir);
+    (deps.broadcastConfigChanged ?? broadcastConfigChangedDefault)(context.sessionName);
+    return result;
+  } catch (err) {
+    const message = (err as Error).message ?? String(err);
+    throw new ActionError({
+      code: message.toLowerCase().includes("path")
+        ? "config_path_invalid"
+        : "config_validation_failed",
+      message,
+      cause: err,
+    });
+  }
+}
+
+export function configSetHandler(
+  input: ActionInput<"config.set">,
+  deps: ConfigActionDeps = {},
+): ActionResult<"config.set"> {
+  const config = mutateConfigAction(input, deps, (dir) =>
+    configSetValue(dir, input.path, input.value),
+  );
+  return { config };
+}
+
+export function configAddPaneHandler(
+  input: ActionInput<"config.addPane">,
+  deps: ConfigActionDeps = {},
+): ActionResult<"config.addPane"> {
+  const pane = {
+    title: input.title,
+    command: input.command,
+    type: input.type,
+    target: input.target,
+    dir: input.dir,
+    size: input.size,
+    focus: input.focus,
+    env: input.env,
+    role: input.role,
+    task: input.task,
+    specialty: input.specialty,
+    skill: input.skill,
+  };
+  const config = mutateConfigAction(input, deps, (dir) => configAddPane(dir, input.rowIndex, pane));
+  return { config };
+}
+
+export function configRemovePaneHandler(
+  input: ActionInput<"config.removePane">,
+  deps: ConfigActionDeps = {},
+): ActionResult<"config.removePane"> {
+  const config = mutateConfigAction(input, deps, (dir) =>
+    configRemovePane(dir, input.rowIndex, input.paneIndex),
+  ).config;
+  return { config };
+}
+
+export function configAddRowHandler(
+  input: ActionInput<"config.addRow">,
+  deps: ConfigActionDeps = {},
+): ActionResult<"config.addRow"> {
+  const config = mutateConfigAction(input, deps, (dir) => configAddRow(dir, input.size));
+  return { config };
+}
+
+export function configEnableTeamHandler(
+  input: ActionInput<"config.enableTeam">,
+  deps: ConfigActionDeps = {},
+): ActionResult<"config.enableTeam"> {
+  const config = mutateConfigAction(input, deps, (dir) => configEnableTeam(dir, input.name));
+  return { config };
+}
+
+export function configDisableTeamHandler(
+  input: ActionInput<"config.disableTeam">,
+  deps: ConfigActionDeps = {},
+): ActionResult<"config.disableTeam"> {
+  const config = mutateConfigAction(input, deps, (dir) => configDisableTeam(dir));
+  return { config };
+}

package/packages/daemon/src/command-center/actions/handlers/daemon-shutdown.ts

@@ -0,0 +1,38 @@
+import { ActionError } from "../errors.ts";
+import type { ActionInput, ActionResult } from "../contract.ts";
+
+export interface DaemonShutdownDeps {
+  shutdown?: (reason: string | null) => Promise<void> | void;
+}
+
+let shutdownBackend: ((reason: string | null) => Promise<void> | void) | null = null;
+let shutdownInProgress = false;
+
+export function setDaemonShutdownBackend(
+  backend: ((reason: string | null) => Promise<void> | void) | null,
+): void {
+  shutdownBackend = backend;
+  if (!backend) shutdownInProgress = false;
+}
+
+export function daemonShutdownHandler(
+  input: ActionInput<"daemon.shutdown">,
+  deps: DaemonShutdownDeps = {},
+): ActionResult<"daemon.shutdown"> {
+  if (shutdownInProgress) {
+    throw new ActionError({
+      code: "shutdown_already_in_progress",
+      message: "Daemon shutdown is already in progress",
+    });
+  }
+
+  shutdownInProgress = true;
+  const shutdown = deps.shutdown ?? shutdownBackend;
+  process.nextTick(() => {
+    void Promise.resolve(shutdown?.(input.reason ?? null)).catch((err) => {
+      console.error("[daemon] shutdown action failed:", err);
+    });
+  });
+
+  return { stopping: true };
+}

package/packages/daemon/src/command-center/actions/handlers/project-activate.ts

@@ -0,0 +1,30 @@
+import { activateProject as activateProjectDefault } from "../../../lib/active-projects.ts";
+import type { ProjectActivationOptions } from "../../../lib/active-projects.ts";
+import { ActionError } from "../errors.ts";
+import type { ActionInput, ActionResult } from "../contract.ts";
+import { resolveProject, type ProjectResolverDeps } from "./_resolve-project.ts";
+
+export interface ProjectActivateDeps extends ProjectResolverDeps {
+  activateProject?: (name: string, options?: ProjectActivationOptions) => Promise<void>;
+}
+
+export async function projectActivateHandler(
+  input: ActionInput<"project.activate">,
+  deps: ProjectActivateDeps = {},
+): Promise<ActionResult<"project.activate">> {
+  const project = resolveProject(input.name, deps);
+  const activateProject = deps.activateProject ?? activateProjectDefault;
+
+  try {
+    await activateProject(project.name);
+  } catch (err) {
+    throw new ActionError({
+      code: "internal",
+      message: `Failed to activate project "${project.name}": ${(err as Error).message ?? String(err)}`,
+      details: { projectName: project.name },
+      cause: err,
+    });
+  }
+
+  return { active: true, projectName: project.name };
+}

package/packages/daemon/src/command-center/actions/handlers/project-launch.ts

@@ -0,0 +1,70 @@
+/**
+ * Handler: `project.launch`.
+ *
+ * Idempotent programmatic launch. Resolves the project from the registry,
+ * checks whether a session is already running, and returns
+ * `{ started: false }` without invoking the launcher when so. Otherwise
+ * delegates to `src/launch.ts` with `attach: false`.
+ */
+
+import { hasSession as hasSessionDefault } from "@tmux-ide/tmux-bridge";
+import { launch as launchDefault } from "../../../launch.ts";
+import { ActionError } from "../errors.ts";
+import { type ActionInput, type ActionResult } from "../contract.ts";
+import { resolveProject, type ProjectResolverDeps } from "./_resolve-project.ts";
+import { getDefaultWorkspaceRegistry } from "../../../lib/workspace-registry.ts";
+
+export interface ProjectLaunchDeps extends ProjectResolverDeps {
+  hasSession?: (session: string) => boolean;
+  launch?: (dir: string, options: { json: boolean; attach: boolean }) => Promise<void>;
+}
+
+/**
+ * Ensure the workspace registry knows about this project. The project
+ * registry (`registerProject`) only updates the project-list — but
+ * `discoverSessions` / `/api/project/:name` consult the WORKSPACE registry
+ * before returning anything. Without this sync, every dashboard fetch
+ * 404s for projects that weren't passed as the daemon's primary sessionName.
+ */
+function ensureWorkspaceRegistered(name: string, sessionName: string, dir: string): void {
+  const reg = getDefaultWorkspaceRegistry();
+  if (reg.has(name)) return;
+  try {
+    reg.add({ name, sessionName, projectDir: dir });
+  } catch {
+    // ALREADY_EXISTS or persistence error — non-fatal; the next discover
+    // pass will pick it up if persistence eventually succeeds.
+  }
+}
+
+export async function projectLaunchHandler(
+  input: ActionInput<"project.launch">,
+  deps: ProjectLaunchDeps = {},
+): Promise<ActionResult<"project.launch">> {
+  const project = resolveProject(input.name, deps);
+  const hasSession = deps.hasSession ?? hasSessionDefault;
+
+  if (hasSession(project.sessionName)) {
+    // Session already running — but the workspace registry may still be
+    // stale (e.g. tmux session created via curl, or daemon restarted).
+    // Sync before returning so /api/project/:name resolves.
+    ensureWorkspaceRegistered(project.name, project.sessionName, project.dir);
+    return { sessionName: project.sessionName, started: false };
+  }
+
+  const launch = deps.launch ?? launchDefault;
+  try {
+    await launch(project.dir, { json: false, attach: false });
+  } catch (err) {
+    throw new ActionError({
+      code: "launch_failed",
+      message: `Failed to launch session "${project.sessionName}": ${(err as Error).message ?? String(err)}`,
+      details: { sessionName: project.sessionName, dir: project.dir },
+      cause: err,
+    });
+  }
+
+  // Freshly launched — workspace registry definitely needs the entry.
+  ensureWorkspaceRegistered(project.name, project.sessionName, project.dir);
+  return { sessionName: project.sessionName, started: true };
+}

package/packages/daemon/src/command-center/actions/handlers/project-open-terminal.ts

@@ -0,0 +1,87 @@
+/**
+ * Handler: `project.openTerminal`.
+ *
+ * Resolves the project's cwd from the registry, ensures the tmux session is
+ * running (launching it if necessary), and asserts the resolved cwd is a
+ * real directory. Returns the dashboard's stable terminal tab id together
+ * with the resolved cwd so the dashboard does not need to stitch together
+ * the registry / session / cwd paths itself.
+ *
+ * This is the action that swallows the seam where the dashboard previously
+ * juggled `/api/projects` + `/api/project/:name` to figure out where to
+ * open a terminal.
+ */
+
+import { hasSession as hasSessionDefault } from "@tmux-ide/tmux-bridge";
+import { launch as launchDefault } from "../../../launch.ts";
+import { activateProject as activateProjectDefault } from "../../../lib/active-projects.ts";
+import { assertValidCwd, TerminalCwdError } from "../../../server/pty-bridge.ts";
+import type { Stats } from "node:fs";
+import { ActionError, actionErrorFromCwdError } from "../errors.ts";
+import { type ActionInput, type ActionResult } from "../contract.ts";
+import { resolveProject, type ProjectResolverDeps } from "./_resolve-project.ts";
+
+const TERMINAL_TAB_ID_PREFIX = "terminal";
+const TERMINAL_TAB_ID_SUFFIX = "default";
+
+/**
+ * Build the dashboard-facing terminal tab id for a session's default
+ * terminal. Mirrors the layout state convention `terminal:<session>:default`.
+ * Centralised here so both this handler and tests share the source of truth.
+ */
+export function defaultTerminalTabId(sessionName: string): string {
+  return `${TERMINAL_TAB_ID_PREFIX}:${sessionName}:${TERMINAL_TAB_ID_SUFFIX}`;
+}
+
+export interface ProjectOpenTerminalDeps extends ProjectResolverDeps {
+  hasSession?: (session: string) => boolean;
+  launch?: (dir: string, options: { json: boolean; attach: boolean }) => Promise<void>;
+  statCwd?: (cwd: string) => Stats;
+  activateProject?: (name: string) => Promise<void>;
+}
+
+export async function projectOpenTerminalHandler(
+  input: ActionInput<"project.openTerminal">,
+  deps: ProjectOpenTerminalDeps = {},
+): Promise<ActionResult<"project.openTerminal">> {
+  const project = resolveProject(input.name, deps);
+  const activateProject = deps.activateProject ?? activateProjectDefault;
+  await activateProject(project.name);
+
+  // Always validate cwd up-front. A missing/broken project dir is the most
+  // common cause of the bugs this slice exists to eliminate.
+  try {
+    assertValidCwd(project.dir, deps.statCwd);
+  } catch (err) {
+    if (err instanceof TerminalCwdError) {
+      throw actionErrorFromCwdError(err);
+    }
+    throw err;
+  }
+
+  const hasSession = deps.hasSession ?? hasSessionDefault;
+  const launch = deps.launch ?? launchDefault;
+
+  let launched = false;
+  if (!hasSession(project.sessionName)) {
+    try {
+      // attach: false — we run inside the daemon HTTP server, not a TTY.
+      await launch(project.dir, { json: false, attach: false });
+      launched = true;
+    } catch (err) {
+      throw new ActionError({
+        code: "launch_failed",
+        message: `Failed to launch session "${project.sessionName}": ${(err as Error).message ?? String(err)}`,
+        details: { sessionName: project.sessionName, dir: project.dir },
+        cause: err,
+      });
+    }
+  }
+
+  return {
+    sessionName: project.sessionName,
+    cwd: project.dir,
+    terminalTabId: defaultTerminalTabId(project.sessionName),
+    launched,
+  };
+}