tmux-ide 2.6.1 → 2.8.0

package/packages/daemon/src/lib/app-config.ts

@@ -20,9 +20,9 @@
  * per-concern readers ({@link ../tui/chrome/notify.ts}, {@link ../restore.ts})
  * now delegate here.
  */
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import type { AgentStatus } from "../tui/detect/classify.ts";
 
 // ---------------------------------------------------------------------------
@@ -96,10 +96,30 @@ export interface AppUpdater {
   snapshotEvery: number;
 }
 
+/** The sound channel's states: ping sound on blocked only, on every ping, or never. */
+export type NotificationSound = "blocked" | "all" | "none";
+
 /** Notification channel toggles. */
 export interface AppNotifications {
   toast: boolean;
   macos: boolean;
+  /**
+   * Terminal-native banners (M25.2): an OSC 9 (kitty: OSC 99) escape written to
+   * each eligible attached client's tty, so terminals that surface them (iTerm2,
+   * Ghostty, WezTerm, kitty) show a native notification even over ssh. Default
+   * true — terminals without support ignore the sequence entirely.
+   */
+  terminal: boolean;
+  /**
+   * Seconds the OS-LEVEL channels (banner / terminal escape / sound / BEL) wait
+   * before firing, re-verifying the pane is STILL in the notified state — a
+   * blocked→working flap inside the window fires nothing. 0 fires immediately.
+   * The in-app toast never waits. Tick-native: the delay rounds up to the
+   * updater's next tick at or after `delaySeconds`.
+   */
+  delaySeconds: number;
+  /** Sound channel (M25.2) — `afplay`/`paplay` + a BEL to eligible client ttys. */
+  sound: NotificationSound;
 }
 
 /** Restore behaviour toggles. */
@@ -110,6 +130,14 @@ export interface AppRestore {
 /** Update-check toggles (consumed later by the update-flow card). */
 export interface AppUpdates {
   check: boolean;
+  /**
+   * Whether the daily update check ALSO refreshes the remote agent-detection
+   * manifest pack into `~/.tmux-ide/agent-detection/pack/` (M25.4). Default
+   * FALSE — auto-installing detection rules is opt-in; `tmux-ide update
+   * --manifests` always works explicitly. Requires `check: true` (the refresh
+   * rides the same daily throttle — no timer of its own).
+   */
+  manifests: boolean;
 }
 
 /** First-run welcome toggles. */
@@ -133,6 +161,57 @@ export interface AppIntegrations {
   offer: boolean;
 }
 
+/** The unified-app front-door decision (M22.6). */
+export interface AppApp {
+  /**
+   * Whether bare `tmux-ide` (no ide.yml here, no `--team`) launches the unified
+   * app (`tmux-ide app`) instead of the classic team cockpit. Default false —
+   * the flip is opt-in until the default-entry decision is made. `tmux-ide team`
+   * (the explicit cockpit) and a project's `ide.yml` auto-launch are unaffected.
+   */
+  frontDoor: boolean;
+  /**
+   * Whether `tmux-ide app` runs HOSTED by default (M23.2): the app lives in an
+   * internal `_tmux-ide-app` tmux session and the invoking terminal attaches to
+   * it, so the cockpit survives the terminal and reattaches from anywhere (^q
+   * detaches instead of quitting). Default false — the same behavior as the
+   * explicit `--detachable` flag; `--detachable`/`--hosted` still force it on a
+   * single run.
+   */
+  detachable: boolean;
+  /**
+   * When a plain left drag on an app-mouse pane SELECTS locally instead of
+   * forwarding to the pane's app (M24.2). "agents" (default): panes our own
+   * detection matches to a fleet agent entry select; other app-mouse panes
+   * (vim/htop) forward. "always": every app-mouse pane selects on drag.
+   * "never": every app-mouse pane forwards (the pre-M24.2 behavior). A genuine
+   * click (press+release in one cell) is still forwarded on select-default
+   * panes; shift inverts a pane's default; the right-click pane menu overrides
+   * per pane for the session.
+   */
+  dragSelect: "agents" | "always" | "never";
+  /**
+   * Where a Terminal-surface "New agent" spawn starts (M24.1): `"pane"`
+   * (default) inherits the FOCUSED pane's current working directory —
+   * `#{pane_current_path}`, so the agent lands where you are — while
+   * `"session"` keeps the session/project directory. Home/sidebar spawns
+   * always use the session/project dir (no focused pane exists there).
+   */
+  newAgentCwd: NewAgentCwd;
+  /**
+   * Whether the unified app enables the kitty keyboard protocol on its host
+   * terminal (M24.4). On (default), kitty-capable terminals deliver ⌘-modified
+   * keys — ⌘K opens the command palette — and disambiguated escapes; the app
+   * re-encodes every key for the mirrored panes either way, and terminals
+   * without the protocol ignore the request entirely. Off restores the legacy
+   * key encoding for hosts where the protocol misbehaves.
+   */
+  kittyKeys: boolean;
+}
+
+/** The two Terminal-spawn cwd policies (see {@link AppApp.newAgentCwd}). */
+export type NewAgentCwd = "pane" | "session";
+
 /** Worktree flow config (`tmux-ide worktree`). */
 export interface AppWorktrees {
   /**
@@ -154,6 +233,7 @@ export interface AppConfig {
   welcome: AppWelcome;
   integrations: AppIntegrations;
   worktrees: AppWorktrees;
+  app: AppApp;
 }
 
 // ---------------------------------------------------------------------------
@@ -184,12 +264,19 @@ export const DEFAULT_APP_CONFIG: AppConfig = {
     glyphs: { active: "●", inactive: "○" },
   },
   updater: { tickMs: 2000, snapshotEvery: 15 },
-  notifications: { toast: true, macos: false },
+  notifications: { toast: true, macos: false, terminal: true, delaySeconds: 2, sound: "blocked" },
   restore: { resumeAgents: false },
-  updates: { check: true },
+  updates: { check: true, manifests: false },
   welcome: { show: true },
   integrations: { offer: true },
   worktrees: { dir: "" },
+  app: {
+    frontDoor: false,
+    detachable: false,
+    dragSelect: "agents",
+    newAgentCwd: "pane",
+    kittyKeys: true,
+  },
 };
 
 /** The default theme tokens — the fallback threaded into the pure builders. */
@@ -224,6 +311,18 @@ function pickPosInt(value: unknown, fallback: number): number {
   return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : fallback;
 }
 
+/** A non-negative integer (0 allowed — e.g. "no delay"), else the default. */
+function pickNonNegInt(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : fallback;
+}
+
+/** One of the allowed literals, else the default. */
+function pickChoice<T extends string>(value: unknown, allowed: readonly T[], fallback: T): T {
+  return typeof value === "string" && (allowed as readonly string[]).includes(value)
+    ? (value as T)
+    : fallback;
+}
+
 /**
  * PURE — merge an unknown (typically parsed JSON) over {@link DEFAULT_APP_CONFIG}.
  * Every block/leaf is validated independently: a missing or mistyped field falls
@@ -245,6 +344,7 @@ export function parseAppConfig(input: unknown): AppConfig {
   const welcome = asObject(root.welcome);
   const integrations = asObject(root.integrations);
   const worktrees = asObject(root.worktrees);
+  const app = asObject(root.app);
   return {
     keys: {
       popup: pickString(keys.popup, D.keys.popup),
@@ -281,12 +381,25 @@ export function parseAppConfig(input: unknown): AppConfig {
     notifications: {
       toast: pickBool(notifications.toast, D.notifications.toast),
       macos: pickBool(notifications.macos, D.notifications.macos),
+      terminal: pickBool(notifications.terminal, D.notifications.terminal),
+      delaySeconds: pickNonNegInt(notifications.delaySeconds, D.notifications.delaySeconds),
+      sound: pickChoice(notifications.sound, ["blocked", "all", "none"], D.notifications.sound),
     },
     restore: { resumeAgents: pickBool(restore.resumeAgents, D.restore.resumeAgents) },
-    updates: { check: pickBool(updates.check, D.updates.check) },
+    updates: {
+      check: pickBool(updates.check, D.updates.check),
+      manifests: pickBool(updates.manifests, D.updates.manifests),
+    },
     welcome: { show: pickBool(welcome.show, D.welcome.show) },
     integrations: { offer: pickBool(integrations.offer, D.integrations.offer) },
     worktrees: { dir: pickString(worktrees.dir, D.worktrees.dir) },
+    app: {
+      frontDoor: pickBool(app.frontDoor, D.app.frontDoor),
+      detachable: pickBool(app.detachable, D.app.detachable),
+      dragSelect: pickChoice(app.dragSelect, ["agents", "always", "never"], D.app.dragSelect),
+      newAgentCwd: pickChoice(app.newAgentCwd, ["pane", "session"], D.app.newAgentCwd),
+      kittyKeys: pickBool(app.kittyKeys, D.app.kittyKeys),
+    },
   };
 }
 
@@ -334,3 +447,79 @@ export function getAppConfig(): AppConfig {
 export function _resetForTests(): void {
   cached = null;
 }
+
+// ---------------------------------------------------------------------------
+// Writes (M22.4 — the settings surface persists through here)
+// ---------------------------------------------------------------------------
+
+/**
+ * io — the RAW parsed config file as the user wrote it (`{}` when missing or
+ * malformed). Writers merge over THIS, not over {@link parseAppConfig}'s output:
+ * round-tripping through the parser would materialize every default into the
+ * hand-editable file and silently DROP fields the typed shape doesn't model yet
+ * (e.g. the notification polish fields `notifications.enabled` /
+ * `notifications.quietHours` that {@link ../tui/chrome/notify.ts} reads raw).
+ */
+export function loadRawAppConfig(): Record<string, unknown> {
+  const path = appConfigPath();
+  if (!existsSync(path)) return {};
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+/** A partial config write: plain objects merge recursively, scalars/arrays
+ *  replace, and an explicit `undefined` DELETES the key (how "reset to
+ *  defaults" removes a block so the parser's defaults take over). */
+export type AppConfigPatch = { [key: string]: unknown };
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * PURE — merge `patch` into `raw` without touching either input. Objects merge
+ * key-by-key (recursively), anything else replaces, and a key whose patch value
+ * is `undefined` is REMOVED from the result. Unknown user fields survive — the
+ * merge only visits keys the patch names.
+ */
+export function mergeConfigPatch(
+  raw: Record<string, unknown>,
+  patch: AppConfigPatch,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...raw };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === undefined) {
+      delete out[key];
+    } else if (isPlainObject(value) && isPlainObject(out[key])) {
+      out[key] = mergeConfigPatch(out[key] as Record<string, unknown>, value as AppConfigPatch);
+    } else if (isPlainObject(value)) {
+      out[key] = mergeConfigPatch({}, value as AppConfigPatch);
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+/**
+ * io — apply a patch to the config file ATOMICALLY (temp + rename, the same
+ * discipline as the editor save): read raw → {@link mergeConfigPatch} → write.
+ * Busts the {@link getAppConfig} process cache and returns the new parsed
+ * config. Honors `TMUX_IDE_CONFIG`, so tests never touch the real file.
+ */
+export function updateAppConfig(patch: AppConfigPatch): AppConfig {
+  const path = appConfigPath();
+  const merged = mergeConfigPatch(loadRawAppConfig(), patch);
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf-8");
+  renameSync(tmp, path);
+  cached = null;
+  return parseAppConfig(merged);
+}

package/packages/daemon/src/lib/manifest-pack.ts

@@ -0,0 +1,255 @@
+/**
+ * Remote agent-detection manifest packs — `tmux-ide update --manifests` (M25.4).
+ *
+ * Detection breadth shouldn't wait for an npm release: agent TUIs change their
+ * chrome between our versions, and a re-tuned manifest is pure data. This
+ * module fetches a versioned MANIFEST PACK from a static URL and installs it
+ * where the manifest loader already hot-merges from.
+ *
+ * ## The pack format (publish contract)
+ *
+ * A single JSON document:
+ *
+ * ```json
+ * {
+ *   "schema": 1,                       // this format's version — reject others
+ *   "pack": "2026.07.12",              // pack version (informational, any string)
+ *   "manifests": [                     // one AgentManifest per entry, exactly the
+ *     {                                //   override-file shape manifest-loader.ts
+ *       "id": "claude",                //   documents (id, commands[], states,
+ *       "commands": ["claude"],        //   optional confidence)
+ *       "confidence": "tuned",
+ *       "states": { "working": { "any": [{ "contains": "esc to interrupt" }] } }
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * Publishing: attach the document as the `agent-manifests.json` asset on a
+ * GitHub release — {@link manifestPackUrl} constructs the same
+ * `releases/download/v<version>/<asset>` URL the TUI-binary download uses, so
+ * a pack rides every release and a NEWER pack can be re-attached to the
+ * CURRENT release tag at any time (the fetch always re-downloads; the pane
+ * option cache never pins it).
+ *
+ * ## Precedence (verified by tests)
+ *
+ * The pack installs into `<agent-detection>/pack/manifest-pack.json` — a
+ * SUBDIRECTORY of the user-override dir, so `readOverrideManifests` (which
+ * lists only `*.json` FILES in the top level) never sees it. The loader merges
+ * `bundled → pack → user`: a pack manifest replaces a bundled id or appends a
+ * new one, and a user's own `<agent-detection>/*.json` file ALWAYS beats both.
+ *
+ * ## Safety
+ *
+ * - Https only for remote URLs. `file://` and loopback `http://` are accepted
+ *   ONLY so tests/dev can exercise the flow without the network — anything
+ *   else is rejected before a byte is fetched.
+ * - The pack is schema-validated ({@link validateManifestPack}) BEFORE being
+ *   written; an invalid pack fails loudly and leaves the previous one intact.
+ * - The gated periodic refresh ({@link maybeRefreshManifestPack}) rides the
+ *   existing daily update check (see {@link ./update-check.ts}) — no timers or
+ *   daemons of its own — and is double-gated on `updates.check` (the caller)
+ *   and `updates.manifests` (read here, default false).
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { AgentManifest } from "../tui/detect/manifest.ts";
+import { overrideDir, validateManifestShape } from "../tui/detect/manifest-loader.ts";
+import { getAppConfig } from "./app-config.ts";
+import { getCurrentVersion } from "./update-check.ts";
+import { RELEASE_REPO } from "./tui-binary.ts";
+
+/** The pack-format version this build understands. */
+export const MANIFEST_PACK_SCHEMA = 1;
+
+/** The release asset name a pack is published under. */
+export const MANIFEST_PACK_ASSET = "agent-manifests.json";
+
+/** Env override for the pack URL (tests/dev; may be `file://` or loopback http). */
+export const MANIFEST_PACK_URL_ENV = "TMUX_IDE_MANIFEST_PACK_URL";
+
+/** A fetched/validated manifest pack. */
+export interface ManifestPack {
+  schema: number;
+  /** Pack version — informational (surfaced in logs), any non-empty string. */
+  pack: string;
+  manifests: AgentManifest[];
+}
+
+// ---------------------------------------------------------------------------
+// Pure
+// ---------------------------------------------------------------------------
+
+/**
+ * PURE — the default pack URL for a version:
+ * `https://github.com/<repo>/releases/download/v<version>/agent-manifests.json`
+ * (the same asset-URL construction as the TUI binary download).
+ */
+export function manifestPackUrl(version: string = getCurrentVersion()): string {
+  const v = version.startsWith("v") ? version.slice(1) : version;
+  return `https://github.com/${RELEASE_REPO}/releases/download/v${v}/${MANIFEST_PACK_ASSET}`;
+}
+
+/**
+ * PURE — is `url` an acceptable pack source? `https:` always; `file:` and
+ * LOOPBACK `http:` (127.0.0.1 / localhost / [::1]) only so tests and local
+ * fixtures can drive the flow. Any other scheme/host is rejected.
+ */
+export function isAllowedPackUrl(url: string): boolean {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol === "https:" || parsed.protocol === "file:") return true;
+  if (parsed.protocol === "http:") {
+    return ["127.0.0.1", "localhost", "[::1]", "::1"].includes(parsed.hostname);
+  }
+  return false;
+}
+
+/**
+ * PURE — validate an untrusted pack document. Returns the typed pack or a
+ * human-readable reason. Every manifest entry must pass the SAME structural
+ * validation user override files do ({@link validateManifestShape}) — one bad
+ * entry rejects the whole pack (a partial install would be harder to reason
+ * about than a loud failure). Never throws.
+ */
+export function validateManifestPack(
+  value: unknown,
+): { ok: true; pack: ManifestPack } | { ok: false; reason: string } {
+  if (typeof value !== "object" || value === null) return { ok: false, reason: "not an object" };
+  const v = value as Record<string, unknown>;
+  if (v.schema !== MANIFEST_PACK_SCHEMA) {
+    return {
+      ok: false,
+      reason: `unsupported schema ${JSON.stringify(v.schema)} (want ${MANIFEST_PACK_SCHEMA})`,
+    };
+  }
+  if (typeof v.pack !== "string" || v.pack.trim().length === 0) {
+    return { ok: false, reason: "missing pack version string" };
+  }
+  if (!Array.isArray(v.manifests) || v.manifests.length === 0) {
+    return { ok: false, reason: "manifests must be a non-empty array" };
+  }
+  for (let i = 0; i < v.manifests.length; i++) {
+    if (!validateManifestShape(v.manifests[i])) {
+      return {
+        ok: false,
+        reason: `manifests[${i}] is not a valid AgentManifest (need id, commands[], states)`,
+      };
+    }
+  }
+  return {
+    ok: true,
+    pack: { schema: MANIFEST_PACK_SCHEMA, pack: v.pack, manifests: v.manifests as AgentManifest[] },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// io
+// ---------------------------------------------------------------------------
+
+/** The installed pack's directory: `<agent-detection>/pack/`. */
+export function packDir(): string {
+  return join(overrideDir(), "pack");
+}
+
+/** The installed pack's path: `<agent-detection>/pack/manifest-pack.json`. */
+export function packPath(): string {
+  return join(packDir(), "manifest-pack.json");
+}
+
+/**
+ * io — fetch and validate a pack. `file://` URLs are read from disk (Node's
+ * fetch does not speak file:); everything else goes through fetch with a
+ * timeout. THROWS with an actionable message on a disallowed URL, a failed
+ * fetch, malformed JSON, or a schema-invalid pack — the caller decides whether
+ * that is loud (CLI) or swallowed (the background refresh).
+ */
+export async function fetchManifestPack(url: string, timeoutMs = 5000): Promise<ManifestPack> {
+  if (!isAllowedPackUrl(url)) {
+    throw new Error(
+      `refusing manifest-pack URL ${url} — https only (file:// and loopback http are allowed for local testing)`,
+    );
+  }
+  let body: string;
+  if (url.startsWith("file:")) {
+    body = readFileSync(fileURLToPath(url), "utf8");
+  } else {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetch(url, { signal: controller.signal });
+      if (!res.ok) {
+        throw new Error(
+          `manifest-pack download failed (${url} → HTTP ${res.status} ${res.statusText})`,
+        );
+      }
+      body = await res.text();
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    throw new Error(`manifest pack at ${url} is not valid JSON`);
+  }
+  const verdict = validateManifestPack(parsed);
+  if (!verdict.ok) {
+    throw new Error(`manifest pack at ${url} rejected: ${verdict.reason}`);
+  }
+  return verdict.pack;
+}
+
+/**
+ * io — write a validated pack into place atomically (temp-in-same-dir →
+ * rename, so a crash never leaves a half-written pack the loader would then
+ * warn about every run). Returns the installed path.
+ */
+export function installManifestPack(pack: ManifestPack, dest: string = packPath()): string {
+  mkdirSync(dirname(dest), { recursive: true });
+  const tmp = `${dest}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(pack, null, 2));
+  renameSync(tmp, dest);
+  return dest;
+}
+
+/**
+ * io — the `tmux-ide update --manifests` flow: resolve the URL (env override →
+ * the release-asset default), fetch, validate, install. Throws loudly on any
+ * failure (the CLI surfaces it); returns what was installed for reporting.
+ */
+export async function updateManifestPack(
+  opts: { url?: string; log?: (msg: string) => void } = {},
+): Promise<{ path: string; packVersion: string; count: number }> {
+  const log = opts.log ?? (() => {});
+  const url = opts.url ?? process.env[MANIFEST_PACK_URL_ENV] ?? manifestPackUrl();
+  log(`fetching manifest pack from ${url}`);
+  const pack = await fetchManifestPack(url);
+  const path = installManifestPack(pack);
+  log(`installed pack ${pack.pack} (${pack.manifests.length} manifests) → ${path}`);
+  return { path, packVersion: pack.pack, count: pack.manifests.length };
+}
+
+/**
+ * io — the GATED background refresh the daily update check invokes (see
+ * `runUpdateCheck` in {@link ./update-check.ts}). Opt-in via
+ * `updates.manifests: true` (default false); NEVER throws — a failed refresh
+ * just keeps the previous pack, exactly like a failed version check keeps the
+ * previous `latest`.
+ */
+export async function maybeRefreshManifestPack(): Promise<void> {
+  try {
+    if (!getAppConfig().updates.manifests) return;
+    await updateManifestPack();
+  } catch {
+    // Offline, a missing release asset, or an invalid pack — all degrade to
+    // "keep what we have"; the explicit CLI path reports errors loudly instead.
+  }
+}

package/packages/daemon/src/lib/state-home.ts

@@ -0,0 +1,13 @@
+/**
+ * THE tmux-ide state home — `TMUX_IDE_HOME` when set (tests / per-run
+ * overrides), else `~/.tmux-ide`. The same resolution the welcome marker,
+ * update cache, and app state each grew locally; new state files should
+ * resolve through here so none of them can drift from the override again.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Absolute path to the state home directory (not created here). */
+export function stateHome(): string {
+  return process.env.TMUX_IDE_HOME ?? join(homedir(), ".tmux-ide");
+}