tmux-ide 2.6.1 → 2.8.0

package/packages/daemon/dist/lib/app-config.js

@@ -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";
 // ---------------------------------------------------------------------------
 // Defaults
 // ---------------------------------------------------------------------------
@@ -50,12 +50,19 @@ export const DEFAULT_APP_CONFIG = {
         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. */
 export const DEFAULT_THEME = DEFAULT_APP_CONFIG.theme;
@@ -82,6 +89,16 @@ function pickBool(value, fallback) {
 function pickPosInt(value, fallback) {
     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, fallback) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : fallback;
+}
+/** One of the allowed literals, else the default. */
+function pickChoice(value, allowed, fallback) {
+    return typeof value === "string" && allowed.includes(value)
+        ? value
+        : 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
@@ -103,6 +120,7 @@ export function parseAppConfig(input) {
     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),
@@ -139,12 +157,25 @@ export function parseAppConfig(input) {
         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),
+        },
     };
 }
 // ---------------------------------------------------------------------------
@@ -189,3 +220,71 @@ export function getAppConfig() {
 export function _resetForTests() {
     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() {
+    const path = appConfigPath();
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function isPlainObject(value) {
+    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, patch) {
+    const out = { ...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], value);
+        }
+        else if (isPlainObject(value)) {
+            out[key] = mergeConfigPatch({}, value);
+        }
+        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) {
+    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/dist/lib/manifest-pack.d.ts

@@ -0,0 +1,79 @@
+import type { AgentManifest } from "../tui/detect/manifest.ts";
+/** The pack-format version this build understands. */
+export declare const MANIFEST_PACK_SCHEMA = 1;
+/** The release asset name a pack is published under. */
+export declare const MANIFEST_PACK_ASSET = "agent-manifests.json";
+/** Env override for the pack URL (tests/dev; may be `file://` or loopback http). */
+export declare 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 — 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 declare function manifestPackUrl(version?: string): string;
+/**
+ * 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 declare function isAllowedPackUrl(url: string): boolean;
+/**
+ * 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 declare function validateManifestPack(value: unknown): {
+    ok: true;
+    pack: ManifestPack;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The installed pack's directory: `<agent-detection>/pack/`. */
+export declare function packDir(): string;
+/** The installed pack's path: `<agent-detection>/pack/manifest-pack.json`. */
+export declare function packPath(): string;
+/**
+ * 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 declare function fetchManifestPack(url: string, timeoutMs?: number): Promise<ManifestPack>;
+/**
+ * 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 declare function installManifestPack(pack: ManifestPack, dest?: string): string;
+/**
+ * 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 declare function updateManifestPack(opts?: {
+    url?: string;
+    log?: (msg: string) => void;
+}): Promise<{
+    path: string;
+    packVersion: string;
+    count: number;
+}>;
+/**
+ * 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 declare function maybeRefreshManifestPack(): Promise<void>;

package/packages/daemon/dist/lib/manifest-pack.js

@@ -0,0 +1,232 @@
+/**
+ * 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 { overrideDir, validateManifestShape } from "../tui/detect/manifest-loader.js";
+import { getAppConfig } from "./app-config.js";
+import { getCurrentVersion } from "./update-check.js";
+import { RELEASE_REPO } from "./tui-binary.js";
+/** 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";
+// ---------------------------------------------------------------------------
+// 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 = getCurrentVersion()) {
+    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) {
+    let parsed;
+    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) {
+    if (typeof value !== "object" || value === null)
+        return { ok: false, reason: "not an object" };
+    const v = value;
+    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 },
+    };
+}
+// ---------------------------------------------------------------------------
+// io
+// ---------------------------------------------------------------------------
+/** The installed pack's directory: `<agent-detection>/pack/`. */
+export function packDir() {
+    return join(overrideDir(), "pack");
+}
+/** The installed pack's path: `<agent-detection>/pack/manifest-pack.json`. */
+export function packPath() {
+    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, timeoutMs = 5000) {
+    if (!isAllowedPackUrl(url)) {
+        throw new Error(`refusing manifest-pack URL ${url} — https only (file:// and loopback http are allowed for local testing)`);
+    }
+    let body;
+    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;
+    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, dest = packPath()) {
+    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 = {}) {
+    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() {
+    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/dist/lib/state-home.d.ts

@@ -0,0 +1,2 @@
+/** Absolute path to the state home directory (not created here). */
+export declare function stateHome(): string;

package/packages/daemon/dist/lib/state-home.js

@@ -0,0 +1,12 @@
+/**
+ * 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() {
+    return process.env.TMUX_IDE_HOME ?? join(homedir(), ".tmux-ide");
+}

package/packages/daemon/dist/lib/tui-binary.d.ts

@@ -0,0 +1,57 @@
+/** The `<os>-<arch>` tags we publish a prebuilt TUI binary for. */
+export type TuiPlatformTag = "darwin-arm64" | "darwin-x64" | "linux-x64" | "linux-arm64";
+/** The GitHub repo the release assets live under. */
+export declare const RELEASE_REPO = "wavyrai/tmux-ide";
+/** A downloaded binary smaller than this is treated as corrupt/truncated. */
+export declare const MIN_TUI_BINARY_BYTES: number;
+/**
+ * PURE — map a Node `process.platform`/`process.arch` pair to the release tag,
+ * or null when we don't publish a binary for it (e.g. windows, freebsd) so the
+ * caller can fall back to the "install bun" message.
+ */
+export declare function tuiPlatformTag(platform?: NodeJS.Platform, arch?: string): TuiPlatformTag | null;
+/** PURE — the `bun build --compile --target` flag for a tag (`bun-<tag>`). */
+export declare function bunTargetForTag(tag: TuiPlatformTag): string;
+/** PURE — the release asset filename for a tag (gzip-compressed binary). */
+export declare function releaseAssetName(tag: TuiPlatformTag): string;
+/** PURE — strip a leading `v` from a version string; `2.6.1` and `v2.6.1` both → `2.6.1`. */
+export declare function normalizeVersion(version: string): string;
+/**
+ * PURE — the GitHub download URL for a platform's asset at a given version:
+ * `https://github.com/<repo>/releases/download/v<version>/tmux-ide-tui-<tag>.gz`.
+ */
+export declare function releaseAssetUrl(version: string, tag: TuiPlatformTag): string;
+/**
+ * PURE — where a downloaded binary lives: `<home>/bin/tmux-ide-tui-<tag>-<version>`.
+ * The version is stamped INTO the name so a `tmux-ide update` to a new version
+ * misses the old download and re-fetches (rather than launching a stale binary).
+ */
+export declare function downloadedTuiPath(home: string, tag: TuiPlatformTag, version: string): string;
+/**
+ * io — the tmux-ide state home (`TMUX_IDE_HOME` override, else `~/.tmux-ide`),
+ * the same resolution the update-check cache and welcome marker use.
+ */
+export declare function tuiStateHome(): string;
+/**
+ * io — locate a previously downloaded per-platform binary for THIS version and
+ * platform, or null. Feeds the resolution order in `tui/compiled.ts` after the
+ * shipped/local compiled binary and before the honest "unavailable" error.
+ */
+export declare function findDownloadedTui(version?: string): string | null;
+/**
+ * io — download, verify, and install the per-platform TUI binary for the running
+ * version. Fetches the gzip asset, inflates it, rejects anything under
+ * {@link MIN_TUI_BINARY_BYTES} (a truncated download or an HTML error page),
+ * writes it `0o755`, and atomically renames it into place (temp-in-same-dir →
+ * rename, so a crashed download never leaves a half-written executable).
+ *
+ * Throws with an actionable message on an unsupported platform or a failed
+ * fetch. Returns the installed path and byte size.
+ */
+export declare function downloadTuiBinary(opts?: {
+    version?: string;
+    log?: (msg: string) => void;
+}): Promise<{
+    path: string;
+    bytes: number;
+}>;

package/packages/daemon/dist/lib/tui-binary.js

@@ -0,0 +1,130 @@
+/**
+ * Per-platform TUI binary: the runtime-download fallback that lets a clean
+ * `npm i -g tmux-ide` run the full OpenTUI/Solid cockpit WITHOUT `bun`.
+ *
+ * The dev checkout runs the `.tsx` surfaces via bun; an npm install with no bun
+ * needs a self-contained binary. We do NOT bundle that ~70MB blob in the npm
+ * tarball (a surprise on every install) — instead the release workflow
+ * (`.github/workflows/release-binaries.yml`) cross-compiles one per platform and
+ * uploads them as GitHub release assets, and this module downloads the right one
+ * on demand (explicit `tmux-ide update --tui-binary`, or a consented first run).
+ *
+ * The mapping/URL/path helpers are PURE (unit-tested); {@link downloadTuiBinary}
+ * and {@link findDownloadedTui} are the thin io that fetch and probe.
+ */
+import { chmodSync, existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { gunzipSync } from "node:zlib";
+import { getCurrentVersion } from "./update-check.js";
+/** The GitHub repo the release assets live under. */
+export const RELEASE_REPO = "wavyrai/tmux-ide";
+/** A downloaded binary smaller than this is treated as corrupt/truncated. */
+export const MIN_TUI_BINARY_BYTES = 10 * 1024 * 1024;
+const SUPPORTED = {
+    "darwin-arm64": "darwin-arm64",
+    "darwin-x64": "darwin-x64",
+    "linux-x64": "linux-x64",
+    "linux-arm64": "linux-arm64",
+};
+// ---------------------------------------------------------------------------
+// Pure
+// ---------------------------------------------------------------------------
+/**
+ * PURE — map a Node `process.platform`/`process.arch` pair to the release tag,
+ * or null when we don't publish a binary for it (e.g. windows, freebsd) so the
+ * caller can fall back to the "install bun" message.
+ */
+export function tuiPlatformTag(platform = process.platform, arch = process.arch) {
+    return SUPPORTED[`${platform}-${arch}`] ?? null;
+}
+/** PURE — the `bun build --compile --target` flag for a tag (`bun-<tag>`). */
+export function bunTargetForTag(tag) {
+    return `bun-${tag}`;
+}
+/** PURE — the release asset filename for a tag (gzip-compressed binary). */
+export function releaseAssetName(tag) {
+    return `tmux-ide-tui-${tag}.gz`;
+}
+/** PURE — strip a leading `v` from a version string; `2.6.1` and `v2.6.1` both → `2.6.1`. */
+export function normalizeVersion(version) {
+    return version.startsWith("v") ? version.slice(1) : version;
+}
+/**
+ * PURE — the GitHub download URL for a platform's asset at a given version:
+ * `https://github.com/<repo>/releases/download/v<version>/tmux-ide-tui-<tag>.gz`.
+ */
+export function releaseAssetUrl(version, tag) {
+    return `https://github.com/${RELEASE_REPO}/releases/download/v${normalizeVersion(version)}/${releaseAssetName(tag)}`;
+}
+/**
+ * PURE — where a downloaded binary lives: `<home>/bin/tmux-ide-tui-<tag>-<version>`.
+ * The version is stamped INTO the name so a `tmux-ide update` to a new version
+ * misses the old download and re-fetches (rather than launching a stale binary).
+ */
+export function downloadedTuiPath(home, tag, version) {
+    return join(home, "bin", `tmux-ide-tui-${tag}-${normalizeVersion(version)}`);
+}
+// ---------------------------------------------------------------------------
+// io
+// ---------------------------------------------------------------------------
+/**
+ * io — the tmux-ide state home (`TMUX_IDE_HOME` override, else `~/.tmux-ide`),
+ * the same resolution the update-check cache and welcome marker use.
+ */
+export function tuiStateHome() {
+    return process.env.TMUX_IDE_HOME ?? join(homedir(), ".tmux-ide");
+}
+/**
+ * io — locate a previously downloaded per-platform binary for THIS version and
+ * platform, or null. Feeds the resolution order in `tui/compiled.ts` after the
+ * shipped/local compiled binary and before the honest "unavailable" error.
+ */
+export function findDownloadedTui(version = getCurrentVersion()) {
+    const tag = tuiPlatformTag();
+    if (!tag)
+        return null;
+    const path = downloadedTuiPath(tuiStateHome(), tag, version);
+    return existsSync(path) ? path : null;
+}
+/**
+ * io — download, verify, and install the per-platform TUI binary for the running
+ * version. Fetches the gzip asset, inflates it, rejects anything under
+ * {@link MIN_TUI_BINARY_BYTES} (a truncated download or an HTML error page),
+ * writes it `0o755`, and atomically renames it into place (temp-in-same-dir →
+ * rename, so a crashed download never leaves a half-written executable).
+ *
+ * Throws with an actionable message on an unsupported platform or a failed
+ * fetch. Returns the installed path and byte size.
+ */
+export async function downloadTuiBinary(opts = {}) {
+    const log = opts.log ?? (() => { });
+    const version = normalizeVersion(opts.version ?? getCurrentVersion());
+    const tag = tuiPlatformTag();
+    if (!tag) {
+        throw new Error(`no prebuilt TUI binary is published for ${process.platform}-${process.arch} — ` +
+            `install bun (https://bun.sh) to run the TUI surfaces from source instead`);
+    }
+    const url = releaseAssetUrl(version, tag);
+    const dest = downloadedTuiPath(tuiStateHome(), tag, version);
+    mkdirSync(dirname(dest), { recursive: true });
+    log(`downloading ${url}`);
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`could not download the TUI binary (${url} → HTTP ${res.status} ${res.statusText}). ` +
+            `Check that release v${version} exists and published its assets.`);
+    }
+    const gz = Buffer.from(await res.arrayBuffer());
+    const bin = gunzipSync(gz);
+    if (bin.byteLength < MIN_TUI_BINARY_BYTES) {
+        throw new Error(`the downloaded TUI binary is only ${bin.byteLength} bytes (expected >10MB) — ` +
+            `treating it as corrupt and leaving the previous binary (if any) in place`);
+    }
+    const tmp = `${dest}.${process.pid}.tmp`;
+    writeFileSync(tmp, bin, { mode: 0o755 });
+    chmodSync(tmp, 0o755);
+    renameSync(tmp, dest);
+    const mb = (bin.byteLength / 1024 / 1024).toFixed(1);
+    log(`installed ${dest} (${mb} MB)`);
+    return { path: dest, bytes: bin.byteLength };
+}