tmux-ide 2.1.4 → 2.6.0

package/packages/daemon/dist/lib/session-options.js

@@ -0,0 +1,85 @@
+/**
+ * Composable builders for tmux session configuration.
+ * Each returns an array of tmux command arrays.
+ */
+export function buildSessionOptions(session, { theme = {} } = {}) {
+    return [
+        ...themeOptions(session, theme),
+        ...borderOptions(session, theme),
+        ...behaviorOptions(session),
+        ...statusBarOptions(session, theme),
+        ...keyBindings(),
+    ];
+}
+export function themeOptions(session, theme) {
+    const accent = theme.accent ?? "colour75";
+    const border = theme.border ?? "colour238";
+    const bg = theme.bg ?? "colour235";
+    const fg = theme.fg ?? "colour248";
+    return [
+        ["set-option", "-t", session, "status-style", `bg=${bg},fg=${fg}`],
+        ["set-option", "-t", session, "pane-border-style", `fg=${border}`],
+        ["set-option", "-t", session, "pane-active-border-style", `fg=${accent}`],
+    ];
+}
+export function borderOptions(session, theme) {
+    const accent = theme.accent ?? "colour75";
+    const border = theme.border ?? "colour238";
+    const fg = theme.fg ?? "colour248";
+    return [
+        ["set-option", "-t", session, "pane-border-status", "top"],
+        [
+            "set-option",
+            "-t",
+            session,
+            "pane-border-format",
+            ` #{?pane_active,#[fg=${accent}#,bold]▸ #T  #[fg=${fg}]#{pane_current_path},#[fg=${border}]· #T  #{pane_current_path}} `,
+        ],
+    ];
+}
+export function behaviorOptions(session) {
+    return [
+        ["set-option", "-t", session, "mouse", "on"],
+        ["set-option", "-t", session, "escape-time", "0"],
+        ["set-option", "-t", session, "status-interval", "1"],
+    ];
+}
+export function statusBarOptions(session, theme) {
+    const accent = theme.accent ?? "colour75";
+    const border = theme.border ?? "colour238";
+    const fg = theme.fg ?? "colour248";
+    // Pane tab components — each is a self-contained piece
+    const agentIndicator = [
+        `#{?#{==:#{@agent_busy},1},#[fg=${accent}]⏺ ,`,
+        `#{?#{==:#{@agent_idle},1},#[fg=${border}]● ,}}`,
+    ].join("");
+    const portIndicator = `#{?#{==:#{@has_port},1},#[fg=green]⏺ ,}`;
+    const paneStyle = `#{?pane_active,#[fg=${accent}],#[fg=${border}]}`;
+    const paneTab = `${agentIndicator}${portIndicator}${paneStyle}#[range=pane|#{pane_id}] #T #[norange]#[default]`;
+    const separator = `#{?loop_last_flag,,#[fg=${border}]│}`;
+    return [
+        [
+            "set-option",
+            "-t",
+            session,
+            "status-left",
+            `#[fg=colour0,bg=${accent},bold]  ${session.toUpperCase()} IDE #[default] `,
+        ],
+        ["set-option", "-t", session, "status-left-length", "30"],
+        [
+            "set-option",
+            "-t",
+            session,
+            "status-right",
+            `#[fg=colour243]%H:%M #[fg=${accent}]│ #[fg=${fg}]%b %d `,
+        ],
+        ["set-option", "-t", session, "status-justify", "centre"],
+        ["set-option", "-t", session, "window-status-current-format", `#[fg=${accent},bold]●`],
+        ["set-option", "-t", session, "window-status-format", `#[fg=${border}]○`],
+        ["set-option", "-t", session, "status", "2"],
+        ["set-option", "-t", session, "status-format[1]", `  #{P:${paneTab}${separator}}`],
+    ];
+}
+export function keyBindings() {
+    return [["bind-key", "-n", "MouseDown1StatusDefault", "select-pane", "-t", "="]];
+}

package/packages/daemon/dist/lib/shell.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Quote a string for safe embedding in POSIX sh/bash commands as a single word.
+ * Wraps in single quotes; embedded `'` becomes `'\''` (end quote, literal quote, resume).
+ */
+export declare function shellEscape(s: string): string;

package/{src/lib/shell.ts → packages/daemon/dist/lib/shell.js}

@@ -2,7 +2,7 @@
  * Quote a string for safe embedding in POSIX sh/bash commands as a single word.
  * Wraps in single quotes; embedded `'` becomes `'\''` (end quote, literal quote, resume).
  */
-export function shellEscape(s: string): string {
-  // Each "'" in the input becomes '\'' outside a single-quoted string.
-  return "'" + s.replace(/'/g, "'\\''") + "'";
+export function shellEscape(s) {
+    // Each "'" in the input becomes '\'' outside a single-quoted string.
+    return "'" + s.replace(/'/g, "'\\''") + "'";
 }

package/packages/daemon/dist/lib/sizes.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Compute absolute sizes for items where some have explicit sizes and others don't.
+ * Items with `size` (e.g. "70%") keep their value; remaining space is split equally
+ * among items without a size.
+ */
+export declare function computeSizes(items: {
+    size?: string;
+}[]): number[];
+/**
+ * Convert absolute sizes (e.g. [70, 30]) to tmux split percentages for sequential splits.
+ * Returns array of -p values (one per split after the first item).
+ *
+ * Each tmux split divides the current pane. The percentage given to -p is
+ * the portion allocated to the NEW (bottom/right) pane.
+ */
+export declare function toSplitPercents(sizes: number[]): number[];

package/packages/daemon/dist/lib/sizes.js

@@ -0,0 +1,36 @@
+/**
+ * Compute absolute sizes for items where some have explicit sizes and others don't.
+ * Items with `size` (e.g. "70%") keep their value; remaining space is split equally
+ * among items without a size.
+ */
+export function computeSizes(items) {
+    let claimed = 0;
+    let unclaimed = 0;
+    for (const item of items) {
+        if (item.size) {
+            claimed += parseFloat(item.size);
+        }
+        else {
+            unclaimed++;
+        }
+    }
+    const remaining = Math.max(0, 100 - claimed);
+    const defaultSize = unclaimed > 0 ? remaining / unclaimed : 0;
+    return items.map((item) => (item.size ? parseFloat(item.size) : defaultSize));
+}
+/**
+ * Convert absolute sizes (e.g. [70, 30]) to tmux split percentages for sequential splits.
+ * Returns array of -p values (one per split after the first item).
+ *
+ * Each tmux split divides the current pane. The percentage given to -p is
+ * the portion allocated to the NEW (bottom/right) pane.
+ */
+export function toSplitPercents(sizes) {
+    const percents = [];
+    for (let i = 1; i < sizes.length; i++) {
+        const remaining = sizes.slice(i - 1).reduce((a, b) => a + b, 0);
+        const topShare = sizes[i - 1];
+        percents.push(Math.round(((remaining - topShare) / remaining) * 100));
+    }
+    return percents;
+}

package/packages/daemon/dist/lib/skill-sync.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Claude Code's config dir: `TMUX_IDE_CLAUDE_DIR` when set (tests / per-run
+ * overrides), else `~/.claude`. Mirrors the {@link ../tui/integrations/claude.ts}
+ * settings override so both halves of the agent setup honor the same scratch dir.
+ */
+export declare function claudeDir(): string;
+/** The fully-managed tmux-ide skill dir: `<claudeDir>/skills/tmux-ide`. */
+export declare function skillTargetDir(): string;
+/** The installed SKILL.md path (inside {@link skillTargetDir}). */
+export declare function skillTargetFile(): string;
+/**
+ * io — the bundled SKILL.md that ships in the package. Resolved relative to this
+ * module, handling BOTH the esbuild-bundled CLI (this file inlines into
+ * `bin/cli.js`, so `here` is `bin/` and the skill is one level up) AND the dev
+ * source tree (`packages/daemon/src/lib/`, four levels below the repo root) — the
+ * same dual-candidate trick as {@link getCurrentVersion}. Returns the first that
+ * exists, else the bundled-layout guess.
+ */
+export declare function defaultSkillSource(): string;
+/**
+ * The version marker line (an HTML comment on line 2 of SKILL.md). The sync
+ * machinery reads it to know which version an installed copy is, and rewrites it
+ * to the installed package version at copy time.
+ */
+export declare const VERSION_MARKER_RE: RegExp;
+/** PURE — render the marker line for a given version. */
+export declare function versionMarker(version: string): string;
+/** PURE — the version in a SKILL.md body, or null when the marker is absent. */
+export declare function parseSkillVersion(content: string): string | null;
+/**
+ * PURE — return `content` with its version marker rewritten to `version`. When no
+ * marker is present the content is returned unchanged (the bundled SKILL.md
+ * always carries one; this just never corrupts a hand-stripped file).
+ */
+export declare function rewriteVersionMarker(content: string, version: string): string;
+/** The version marker read off an installed SKILL.md, or null if absent/unreadable. */
+export declare function installedSkillVersion(dir?: string): string | null;
+/** What a {@link syncSkill} did. */
+export interface SyncResult {
+    /** `installed` = target was absent; `updated` = content changed; `unchanged` = no-op. */
+    action: "installed" | "updated" | "unchanged";
+    /** The written SKILL.md path. */
+    path: string;
+    /** The installed version before an `updated` (the marker we replaced), if any. */
+    from?: string | null;
+    /** The version written into the copy's marker. */
+    to: string;
+}
+/**
+ * io — copy the bundled SKILL.md into the managed skill dir with its version
+ * marker rewritten to `version`. Content-driven and idempotent: the RENDERED
+ * source (marker substituted) is compared byte-for-byte against the installed
+ * copy — identical → `unchanged` (no write), absent → `installed`, otherwise
+ * `updated`. Only ever writes inside {@link skillTargetDir}; nothing outside it
+ * is read or touched.
+ */
+export declare function syncSkill({ source, version, }?: {
+    source?: string;
+    version?: string;
+}): SyncResult;

package/packages/daemon/dist/lib/skill-sync.js

@@ -0,0 +1,128 @@
+/**
+ * Managed sync of the bundled Claude Code skill → `~/.claude/skills/tmux-ide`.
+ *
+ * `skill/SKILL.md` is the manual a coding agent loads to drive tmux-ide. It ships
+ * IN the package, but the copy that agents actually read lives in the user's
+ * `~/.claude/skills/` — so every install AND every update has to keep that copy
+ * fresh, or agents drive an old CLI. This module is that refresh: it copies the
+ * bundled SKILL.md into the tmux-ide skill dir with the version marker rewritten
+ * to the installed package version, and reports whether that was an install, an
+ * update, or a no-op.
+ *
+ * The dir is FULLY MANAGED: overwriting our own `~/.claude/skills/tmux-ide` is
+ * correct, and this NEVER touches anything outside it (user-authored skills in
+ * sibling dirs are safe). The version marker is line 2 of SKILL.md, an HTML
+ * comment ({@link VERSION_MARKER_RE}); {@link parseSkillVersion} reads it and
+ * {@link rewriteVersionMarker} substitutes it at copy time.
+ *
+ * The parse/render helpers are PURE and tested against fixtures; {@link syncSkill}
+ * is the thin io wrapper (tested with tmp dirs). Wired from three places — the
+ * npm `postinstall` (which re-implements the marker rewrite in plain JS since it
+ * can't import TS — see scripts/postinstall.js), `tmux-ide skill-sync` / the dev
+ * path of `tmux-ide update`, and `tmux-ide integration install claude`.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getCurrentVersion } from "./update-check.js";
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+/**
+ * Claude Code's config dir: `TMUX_IDE_CLAUDE_DIR` when set (tests / per-run
+ * overrides), else `~/.claude`. Mirrors the {@link ../tui/integrations/claude.ts}
+ * settings override so both halves of the agent setup honor the same scratch dir.
+ */
+export function claudeDir() {
+    return process.env.TMUX_IDE_CLAUDE_DIR ?? join(homedir(), ".claude");
+}
+/** The fully-managed tmux-ide skill dir: `<claudeDir>/skills/tmux-ide`. */
+export function skillTargetDir() {
+    return join(claudeDir(), "skills", "tmux-ide");
+}
+/** The installed SKILL.md path (inside {@link skillTargetDir}). */
+export function skillTargetFile() {
+    return join(skillTargetDir(), "SKILL.md");
+}
+/**
+ * io — the bundled SKILL.md that ships in the package. Resolved relative to this
+ * module, handling BOTH the esbuild-bundled CLI (this file inlines into
+ * `bin/cli.js`, so `here` is `bin/` and the skill is one level up) AND the dev
+ * source tree (`packages/daemon/src/lib/`, four levels below the repo root) — the
+ * same dual-candidate trick as {@link getCurrentVersion}. Returns the first that
+ * exists, else the bundled-layout guess.
+ */
+export function defaultSkillSource() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        join(here, "../skill/SKILL.md"), // bundled bin/cli.js → repo root
+        join(here, "../../../../skill/SKILL.md"), // dev src/lib → repo root
+    ];
+    return candidates.find((c) => existsSync(c)) ?? candidates[0];
+}
+// ---------------------------------------------------------------------------
+// Pure — version marker
+// ---------------------------------------------------------------------------
+/**
+ * The version marker line (an HTML comment on line 2 of SKILL.md). The sync
+ * machinery reads it to know which version an installed copy is, and rewrites it
+ * to the installed package version at copy time.
+ */
+export const VERSION_MARKER_RE = /<!--\s*tmux-ide-skill-version:\s*([^\s]+)\s*-->/;
+/** PURE — render the marker line for a given version. */
+export function versionMarker(version) {
+    return `<!-- tmux-ide-skill-version: ${version} -->`;
+}
+/** PURE — the version in a SKILL.md body, or null when the marker is absent. */
+export function parseSkillVersion(content) {
+    const match = content.match(VERSION_MARKER_RE);
+    return match ? match[1] : null;
+}
+/**
+ * PURE — return `content` with its version marker rewritten to `version`. When no
+ * marker is present the content is returned unchanged (the bundled SKILL.md
+ * always carries one; this just never corrupts a hand-stripped file).
+ */
+export function rewriteVersionMarker(content, version) {
+    if (!VERSION_MARKER_RE.test(content))
+        return content;
+    return content.replace(VERSION_MARKER_RE, versionMarker(version));
+}
+// ---------------------------------------------------------------------------
+// io
+// ---------------------------------------------------------------------------
+/** The version marker read off an installed SKILL.md, or null if absent/unreadable. */
+export function installedSkillVersion(dir = skillTargetDir()) {
+    const file = join(dir, "SKILL.md");
+    if (!existsSync(file))
+        return null;
+    try {
+        return parseSkillVersion(readFileSync(file, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * io — copy the bundled SKILL.md into the managed skill dir with its version
+ * marker rewritten to `version`. Content-driven and idempotent: the RENDERED
+ * source (marker substituted) is compared byte-for-byte against the installed
+ * copy — identical → `unchanged` (no write), absent → `installed`, otherwise
+ * `updated`. Only ever writes inside {@link skillTargetDir}; nothing outside it
+ * is read or touched.
+ */
+export function syncSkill({ source = defaultSkillSource(), version = getCurrentVersion(), } = {}) {
+    const rendered = rewriteVersionMarker(readFileSync(source, "utf-8"), version);
+    const dir = skillTargetDir();
+    const target = join(dir, "SKILL.md");
+    const existing = existsSync(target) ? readFileSync(target, "utf-8") : null;
+    if (existing === rendered) {
+        return { action: "unchanged", path: target, to: version };
+    }
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(target, rendered, "utf-8");
+    if (existing === null)
+        return { action: "installed", path: target, to: version };
+    return { action: "updated", path: target, from: parseSkillVersion(existing), to: version };
+}

package/packages/daemon/dist/lib/slugify.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Convert text to a URL/filename-safe slug.
+ */
+export declare function slugify(text: string, maxLen?: number): string;

package/packages/daemon/dist/lib/slugify.js

@@ -0,0 +1,10 @@
+/**
+ * Convert text to a URL/filename-safe slug.
+ */
+export function slugify(text, maxLen = 40) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, maxLen);
+}

package/packages/daemon/dist/lib/terminals-store.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Terminals registry (G20-P1).
+ *
+ * JSON-backed persistence for tab-strip metadata — names, scopes, and
+ * kind. The actual PTY process lives in `PtyBridgeRegistry`; this
+ * store only persists what the UI needs to restore tab labels across
+ * reloads. Atomic writes (temp + rename) so a crash mid-write leaves
+ * the previous list intact.
+ */
+import type { Terminal, TerminalKind } from "@tmux-ide/contracts";
+/** Load the full list for a session. Missing file → empty list. */
+export declare function loadTerminals(dir: string): Terminal[];
+export interface CreateInput {
+    id: string;
+    projectId: string;
+    scopeId: string;
+    name: string;
+    kind: TerminalKind;
+    scripted?: boolean;
+}
+/** Insert OR replace a terminal record by id. Idempotent — calling
+ *  `createTerminal` twice with the same deterministic id is a no-op
+ *  on the canonical fields and updates `updatedAt`. */
+export declare function upsertTerminal(dir: string, input: CreateInput): Terminal;
+export declare function renameTerminal(dir: string, id: string, name: string): Terminal | null;
+export declare function deleteTerminal(dir: string, id: string): boolean;
+export declare function findTerminal(dir: string, id: string): Terminal | null;

package/packages/daemon/dist/lib/terminals-store.js

@@ -0,0 +1,111 @@
+/**
+ * Terminals registry (G20-P1).
+ *
+ * JSON-backed persistence for tab-strip metadata — names, scopes, and
+ * kind. The actual PTY process lives in `PtyBridgeRegistry`; this
+ * store only persists what the UI needs to restore tab labels across
+ * reloads. Atomic writes (temp + rename) so a crash mid-write leaves
+ * the previous list intact.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+const TERMINALS_FILE = ".tmux-ide/terminals.json";
+const SAFE_ID = /^[A-Za-z0-9_-]+$/u;
+function path(dir) {
+    return join(dir, TERMINALS_FILE);
+}
+function ensureDir(dir) {
+    mkdirSync(dirname(path(dir)), { recursive: true });
+}
+/** Load the full list for a session. Missing file → empty list. */
+export function loadTerminals(dir) {
+    const file = path(dir);
+    if (!existsSync(file))
+        return [];
+    try {
+        const body = readFileSync(file, "utf-8");
+        const parsed = JSON.parse(body);
+        if (!parsed.terminals || !Array.isArray(parsed.terminals))
+            return [];
+        return parsed.terminals.filter((t) => isTerminal(t)).map((t) => ({ ...t }));
+    }
+    catch {
+        return [];
+    }
+}
+function isTerminal(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    return (typeof v.id === "string" &&
+        SAFE_ID.test(v.id) &&
+        typeof v.projectId === "string" &&
+        typeof v.scopeId === "string" &&
+        typeof v.name === "string" &&
+        (v.kind === "shell" || v.kind === "setup" || v.kind === "run" || v.kind === "teardown") &&
+        typeof v.createdAt === "string" &&
+        typeof v.updatedAt === "string");
+}
+function writeAtomic(dir, terminals) {
+    ensureDir(dir);
+    const file = path(dir);
+    const tmp = `${file}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ terminals }, null, 2) + "\n");
+    renameSync(tmp, file);
+}
+/** Insert OR replace a terminal record by id. Idempotent — calling
+ *  `createTerminal` twice with the same deterministic id is a no-op
+ *  on the canonical fields and updates `updatedAt`. */
+export function upsertTerminal(dir, input) {
+    if (!SAFE_ID.test(input.id)) {
+        throw new Error(`invalid terminal id "${input.id}"`);
+    }
+    const existing = loadTerminals(dir);
+    const idx = existing.findIndex((t) => t.id === input.id);
+    const now = new Date().toISOString();
+    const next = {
+        id: input.id,
+        projectId: input.projectId,
+        scopeId: input.scopeId,
+        name: input.name,
+        kind: input.kind,
+        createdAt: existing[idx]?.createdAt ?? now,
+        updatedAt: now,
+        ...(input.scripted ? { scripted: true } : {}),
+    };
+    if (idx === -1)
+        existing.push(next);
+    else
+        existing[idx] = next;
+    writeAtomic(dir, existing);
+    return next;
+}
+export function renameTerminal(dir, id, name) {
+    const all = loadTerminals(dir);
+    const idx = all.findIndex((t) => t.id === id);
+    if (idx === -1)
+        return null;
+    const trimmed = name.trim();
+    if (!trimmed)
+        throw new Error("name required");
+    const next = {
+        ...all[idx],
+        name: trimmed,
+        updatedAt: new Date().toISOString(),
+    };
+    all[idx] = next;
+    writeAtomic(dir, all);
+    return next;
+}
+export function deleteTerminal(dir, id) {
+    const all = loadTerminals(dir);
+    const next = all.filter((t) => t.id !== id);
+    if (next.length === all.length)
+        return false;
+    writeAtomic(dir, next);
+    return true;
+}
+export function findTerminal(dir, id) {
+    const all = loadTerminals(dir);
+    return all.find((t) => t.id === id) ?? null;
+}

package/packages/daemon/dist/lib/update-check.d.ts

@@ -0,0 +1,118 @@
+/** The npm dist-tag endpoint that returns `{ "version": "x.y.z", … }`. */
+export declare const REGISTRY_URL = "https://registry.npmjs.org/tmux-ide/latest";
+/** Re-check no more than once per this window (24h). */
+export declare const CHECK_INTERVAL_MS: number;
+/** The cheap, cache-derived answer every surface reads. */
+export interface UpdateStatus {
+    /** The latest published version the last check saw, or null when unknown. */
+    latest: string | null;
+    /** True when {@link latest} is strictly newer than the running version. */
+    updateAvailable: boolean;
+}
+/** The on-disk cache shape (`~/.tmux-ide/update-check.json`). */
+export interface UpdateCache {
+    /** Epoch ms of the last network check (throttles {@link shouldCheck}). */
+    lastCheckedAt: number | null;
+    /** The latest version that check saw, or null. */
+    latest: string | null;
+    /** Versions we've already toasted about (one-time-per-version debounce). */
+    notified?: string[];
+}
+/**
+ * PURE — order two semver strings: `-1` if `a < b`, `1` if `a > b`, else `0`.
+ *
+ * Numeric core (major, minor, patch) compares field-by-field, so `2.10.0` sorts
+ * ABOVE `2.6.0` (numeric, not lexical). Prerelease follows semver's rule: a
+ * release outranks a prerelease of the same core (`1.0.0` > `1.0.0-rc`); two
+ * prereleases fall back to a plain lexical compare of their tags (a simple, good-
+ * enough ordering — we never need to rank `rc.2` vs `rc.10` precisely).
+ */
+export declare function compareSemver(a: string, b: string): -1 | 0 | 1;
+/** PURE — is `latest` strictly newer than `current`? */
+export declare function isNewer(latest: string, current: string): boolean;
+/**
+ * PURE — should we hit the network again? True when we've never checked
+ * (`lastCheckedAt` null) or the last check was at least {@link CHECK_INTERVAL_MS}
+ * ago. A future `lastCheckedAt` (clock skew) reads as "recent" and skips — the
+ * daily tick self-heals once the clock passes it.
+ */
+export declare function shouldCheck(lastCheckedAt: number | null, nowMs: number): boolean;
+/**
+ * PURE — pull the `version` string out of a raw npm dist-tag response body.
+ * Returns null (never throws) for malformed JSON, a non-object, or a
+ * missing/empty/non-string `version`.
+ */
+export declare function parseRegistryResponse(json: string): string | null;
+/**
+ * PURE — derive the {@link UpdateStatus} for a running version from a (possibly
+ * null) cached latest. The single place "is there an update?" is decided, so
+ * every surface agrees.
+ */
+export declare function deriveStatus(latest: string | null, currentVersion: string): UpdateStatus;
+/**
+ * Absolute path to the cache file: `<home>/update-check.json`, where `<home>` is
+ * `TMUX_IDE_HOME` when set (tests / per-run overrides), else `~/.tmux-ide` — the
+ * same home resolution the welcome marker uses.
+ */
+export declare function updateCachePath(): string;
+/** io — read + parse the cache, or null when absent/unreadable/malformed. */
+export declare function readUpdateCache(): UpdateCache | null;
+/** io — write the cache (creating `<home>` if needed). Best-effort, never throws. */
+export declare function writeUpdateCache(cache: UpdateCache): void;
+/**
+ * io — ask npm for the latest published version, or null on ANY failure (offline,
+ * timeout, non-200, garbage body). Aborts after `timeoutMs` so a slow registry
+ * can never stall the updater tick. This is the ONLY network call in the module.
+ */
+export declare function fetchLatestVersion(timeoutMs?: number): Promise<string | null>;
+/**
+ * The running tmux-ide version, read from the nearest `package.json`. Handles
+ * BOTH the bundled CLI (`bin/cli.js`, so the repo-root package.json is one level
+ * up) AND the dev source tree (this file at `packages/daemon/src/lib/`, so the
+ * root is four levels up). The workspace `packages/daemon/package.json` is
+ * deliberately NOT a candidate — it carries a placeholder version. Falls back to
+ * `"0.0.0"` when nothing is readable (so an unknown version simply never shows an
+ * update rather than crashing).
+ */
+export declare function getCurrentVersion(): string;
+/**
+ * The cheap, network-FREE status read every surface uses: derive
+ * {@link UpdateStatus} from the cache against the current version. `now`/
+ * `currentVersion` are injectable for tests; the defaults read the live clock +
+ * package version.
+ */
+export declare function getUpdateStatus({ currentVersion, }?: {
+    now?: number;
+    currentVersion?: string;
+}): UpdateStatus;
+/**
+ * io — the throttled network refresh (called fire-and-forget from the updater
+ * tick). Does nothing if the last check was inside {@link CHECK_INTERVAL_MS};
+ * otherwise fetches the latest version and rewrites the cache with a fresh
+ * `lastCheckedAt`. On a failed fetch it still stamps `lastCheckedAt` (so we don't
+ * hammer a flaky/offline registry every tick) while KEEPING the previously known
+ * `latest`. Never throws.
+ */
+export declare function runUpdateCheck({ now }?: {
+    now?: number;
+}): Promise<void>;
+/**
+ * The tick's entry point: return the cheap cache-derived {@link UpdateStatus} NOW,
+ * and (when `enabled`) kick off the throttled network refresh in the background so
+ * the NEXT tick sees a fresh answer. Disabled (`updates.check: false`) → always
+ * "no update", no network. The background refresh is deliberately un-awaited: the
+ * tick must never block on the registry.
+ */
+export declare function maybeCheckForUpdate({ enabled, now, currentVersion, }: {
+    enabled: boolean;
+    now?: number;
+    currentVersion?: string;
+}): UpdateStatus;
+/**
+ * io — record that we've toasted about `version` and report whether this is the
+ * FIRST time (so the caller should actually toast). Persisted in the cache file's
+ * `notified` list so the one-time guarantee survives updater restarts — the old
+ * in-memory notify debounce would re-fire on every respawn. Best-effort: if the
+ * cache can't be written we still return the in-memory verdict.
+ */
+export declare function markUpdateNotified(version: string): boolean;