@gamaze/hicortex 0.20.3 → 0.20.5

package/assets/viz.html

@@ -80,6 +80,68 @@
     background: rgba(128,128,128,0.18); font-size: 11px; color: var(--text-dim);
   }
 
+  /* ---- account menu (#365) ---- */
+  /* Dropdown under the nav account element: token reveal/copy, connect
+     snippets, plan & billing, sign-out. The wrapper (#nav-account) becomes
+     the positioning context; the panel is absolute + right-aligned under it,
+     above graph content (the topbar is z-10, the panel gets 60 within it). */
+  .hc-nav-account { position: relative; }
+  .acct-trigger {
+    display: inline-flex; align-items: center; gap: 6px;
+    background: transparent; color: var(--text); border: none; border-radius: 6px;
+    padding: 4px 8px; font: inherit; cursor: pointer;
+  }
+  .acct-trigger:hover { background: rgba(128,128,128,0.15); }
+  .acct-caret { color: var(--text-dim); font-size: 10px; }
+  .acct-menu {
+    display: none; position: absolute; top: calc(100% + 8px); right: 0;
+    min-width: 320px; max-width: min(420px, calc(100vw - 40px));
+    background: var(--panel); border: 1px solid var(--panel-border); border-radius: 8px;
+    padding: 12px; z-index: 60;
+    box-shadow: 0 8px 24px rgba(0,0,0,0.35);
+    color: var(--text); font-size: 13px; text-align: left;
+  }
+  .acct-menu.open { display: block; }
+  .acct-label {
+    font-size: 11px; text-transform: uppercase; letter-spacing: 0.04em;
+    color: var(--text-dim); margin: 8px 0 4px;
+  }
+  .acct-menu .acct-label:first-child { margin-top: 0; }
+  .acct-token-row { display: flex; align-items: center; gap: 6px; }
+  .acct-token {
+    flex: 1; min-width: 0;
+    font: 12px ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    background: var(--bg); border: 1px solid var(--panel-border); border-radius: 4px;
+    padding: 4px 8px; color: var(--text);
+    overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  }
+  .acct-btn {
+    background: var(--panel); color: var(--text);
+    border: 1px solid var(--panel-border); border-radius: 4px;
+    padding: 4px 10px; font: inherit; font-size: 12px; cursor: pointer;
+  }
+  .acct-btn:hover { border-color: var(--accent); color: var(--accent); }
+  .acct-btn:disabled { opacity: 0.5; cursor: default; }
+  .acct-menu details { border-top: 1px solid var(--panel-border); margin-top: 10px; padding-top: 8px; }
+  .acct-menu summary { cursor: pointer; color: var(--text-dim); font-size: 13px; }
+  .acct-menu summary:hover { color: var(--accent); }
+  .acct-snippet { margin-bottom: 8px; }
+  .acct-snippet pre {
+    background: var(--bg); border: 1px solid var(--panel-border); border-radius: 4px;
+    padding: 8px; margin: 4px 0;
+    font: 11.5px/1.5 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    white-space: pre-wrap; word-break: break-all;
+    max-height: 200px; overflow-y: auto;
+  }
+  .acct-link {
+    display: block; width: 100%; text-align: left;
+    background: transparent; border: none; border-radius: 4px;
+    color: var(--text); font: inherit; font-size: 13px;
+    padding: 6px 8px; cursor: pointer;
+  }
+  .acct-link:hover { background: rgba(128,128,128,0.15); }
+  .acct-link.acct-danger:hover { color: var(--danger); }
+
   /* ---- left control panel ---- */
   #panel {
     position: fixed; top: 48px; left: 12px; width: 236px;
@@ -385,28 +447,43 @@
   });
 
   // =========================================================================
-  // Account identity in the nav — GET /account (the lightweight endpoint, the
-  // same shape the dashboard payload carries). Fail-soft: 401/fetch error
-  // leaves the span empty (fetchGraph owns the 401 token prompt); an all-null
-  // account (self-hosted default) renders nothing. textContent only — this
-  // page uses innerHTML exclusively for the escaped 3D-force-graph tooltips.
+  // Account identity in the nav + the ACCOUNT MENU (#365) — GET /account (the
+  // lightweight endpoint, the same shape the dashboard payload carries).
+  // Fail-soft: 401/fetch error leaves the span empty (fetchGraph owns the 401
+  // token prompt); an all-null account (self-hosted default) renders nothing —
+  // no menu either. createElement/textContent only — this page uses innerHTML
+  // exclusively for the escaped 3D-force-graph tooltips.
   // =========================================================================
   function renderAccount(a) {
     var host = document.getElementById("nav-account");
     if (!host) return;
     host.textContent = "";
     if (!a || (a.name === null && a.org === null && a.plan === null)) return;
+    var trigger = document.createElement("button");
+    trigger.type = "button";
+    trigger.id = "acct-trigger";
+    trigger.className = "acct-trigger";
+    trigger.setAttribute("aria-haspopup", "menu");
+    trigger.setAttribute("aria-expanded", "false");
     var who = [a.name, a.org].filter(function (s) { return typeof s === "string" && s !== ""; });
     who.forEach(function (s, i) {
-      if (i > 0) host.appendChild(document.createTextNode(" · "));
-      host.appendChild(document.createTextNode(s));
+      if (i > 0) trigger.appendChild(document.createTextNode(" · "));
+      trigger.appendChild(document.createTextNode(s));
     });
     if (typeof a.plan === "string" && a.plan !== "") {
       var pill = document.createElement("span");
       pill.className = "plan";
       pill.textContent = a.plan;
-      host.appendChild(pill);
+      trigger.appendChild(pill);
     }
+    var caret = document.createElement("span");
+    caret.className = "acct-caret";
+    caret.setAttribute("aria-hidden", "true");
+    caret.textContent = "▾";
+    trigger.appendChild(caret);
+    host.appendChild(trigger);
+    host.appendChild(buildAcctMenu());
+    wireAcctMenu();
   }
   function loadAccount() {
     var headers = {};
@@ -417,6 +494,273 @@
       .catch(function () { /* leave the span empty — nav is never worth an error */ });
   }
 
+  // =========================================================================
+  // Account menu (#365) — dropdown under the nav account element: token
+  // reveal/copy, connect snippets, plan & billing, sign-out. The token shown
+  // is AUTHORITATIVE server truth: a lazy GET /account/token on the FIRST
+  // open (echo-only endpoint — the fetch already proves the caller holds the
+  // token). localStorage is NEVER trusted for the display: it can be stale
+  // after token rotation and is absent entirely for browser sessions the
+  // hosted router authenticates via its session→bearer injection. On fetch
+  // failure the row fails explicitly ("token unavailable", actions disabled).
+  // Built with createElement/textContent only (page convention).
+  // =========================================================================
+  var acctToken = null;             // token from /account/token (server truth)
+  var acctTokenState = "unfetched"; // "unfetched" | "ok" | "unavailable"
+  var acctTokenFetched = false;     // one lazy fetch attempt per page load
+  var acctRevealed = false;         // unmasked while the menu is open
+
+  function maskToken(t) {
+    // hctx-••••••23f9 — first 5 chars + 6 bullets + last 4. Real tokens are
+    // hctx-<32hex>; the guard keeps a degenerate short token from leaking.
+    if (typeof t !== "string" || t.length < 10) return "••••••••••";
+    return t.slice(0, 5) + "••••••" + t.slice(-4);
+  }
+
+  function el(tag, id, cls, text) {
+    var n = document.createElement(tag);
+    if (id) n.id = id;
+    if (cls) n.className = cls;
+    if (text !== undefined) n.textContent = text;
+    return n;
+  }
+
+  // Static menu skeleton — token-dependent values fill in renderAcctToken().
+  function buildAcctMenu() {
+    var menu = el("div", "acct-menu", "acct-menu");
+    menu.appendChild(el("div", null, "acct-label", "Connection token"));
+    var row = el("div", null, "acct-token-row");
+    row.appendChild(el("code", "acct-token-val", "acct-token", "…"));
+    row.appendChild(el("button", "acct-reveal", "acct-btn", "Reveal"));
+    row.appendChild(el("button", "acct-copy-token", "acct-btn", "Copy"));
+    menu.appendChild(row);
+    var details = el("details", "acct-connect");
+    details.appendChild(el("summary", null, null, "Connect an agent"));
+    details.appendChild(el("div", null, "acct-label", "CLI"));
+    var snip1 = el("div", null, "acct-snippet");
+    snip1.appendChild(el("pre", "acct-cli"));
+    snip1.appendChild(el("button", "acct-copy-cli", "acct-btn", "Copy"));
+    details.appendChild(snip1);
+    details.appendChild(el("div", null, "acct-label", "MCP — ~/.claude.json"));
+    var snip2 = el("div", null, "acct-snippet");
+    snip2.appendChild(el("pre", "acct-mcp"));
+    snip2.appendChild(el("button", "acct-copy-mcp", "acct-btn", "Copy"));
+    details.appendChild(snip2);
+    menu.appendChild(details);
+    menu.appendChild(el("button", "acct-plan", "acct-link", "Plan & billing"));
+    menu.appendChild(el("button", "acct-signout", "acct-link acct-danger", "Sign out"));
+    // All menu buttons are type=button (never submit — no form here, but the
+    // page's convention is explicit types).
+    var btns = menu.querySelectorAll("button");
+    for (var i = 0; i < btns.length; i++) btns[i].type = "button";
+    return menu;
+  }
+
+  // The connect line: server URL + token on ONE line, space-separated.
+  function acctConnectLine() {
+    return location.origin + " " + acctToken;
+  }
+
+  // CLI snippet — init has NO --token flag; it prompts interactively. The
+  // comment mirrors init.ts's own printed hint ("When prompted for the token,
+  // paste: …").
+  function acctCliText() {
+    return "# When prompted for the token, paste: " + acctToken +
+      "\nnpx @gamaze/hicortex init --server " + location.origin;
+  }
+
+  // MCP snippet — mirrors EXACTLY what runClientInit writes into
+  // ~/.claude.json (init.ts): SSE transport at <origin>/sse with a bearer
+  // Authorization header.
+  function acctMcpText() {
+    return JSON.stringify({
+      mcpServers: {
+        hicortex: {
+          type: "sse",
+          url: location.origin + "/sse",
+          headers: { Authorization: "Bearer " + acctToken }
+        }
+      }
+    }, null, 2);
+  }
+
+  function renderAcctToken() {
+    var val = document.getElementById("acct-token-val");
+    if (!val) return; // menu not rendered (self-hosted all-null account)
+    var revealBtn = document.getElementById("acct-reveal");
+    var copyToken = document.getElementById("acct-copy-token");
+    var copyCli = document.getElementById("acct-copy-cli");
+    var copyMcp = document.getElementById("acct-copy-mcp");
+    var cli = document.getElementById("acct-cli");
+    var mcp = document.getElementById("acct-mcp");
+    if (acctTokenState !== "ok") {
+      val.textContent = acctTokenState === "unfetched" ? "…" : "token unavailable";
+      revealBtn.disabled = true;
+      copyToken.disabled = true;
+      copyCli.disabled = true;
+      copyMcp.disabled = true;
+      cli.textContent = acctTokenState === "unfetched" ? "" : "token unavailable";
+      mcp.textContent = acctTokenState === "unfetched" ? "" : "token unavailable";
+      return;
+    }
+    revealBtn.disabled = false;
+    copyToken.disabled = false;
+    copyCli.disabled = false;
+    copyMcp.disabled = false;
+    val.textContent = acctRevealed ? acctToken : maskToken(acctToken);
+    revealBtn.textContent = acctRevealed ? "Hide" : "Reveal";
+    cli.textContent = acctCliText();
+    mcp.textContent = acctMcpText();
+  }
+
+  function fetchAcctToken() {
+    if (acctTokenFetched) return;
+    acctTokenFetched = true;
+    var headers = {};
+    if (token) headers["Authorization"] = "Bearer " + token; // same as loadAccount
+    fetch("/account/token", { headers: headers })
+      .then(function (resp) {
+        if (!resp.ok) throw new Error("HTTP " + resp.status);
+        return resp.json();
+      })
+      .then(function (data) {
+        if (typeof data.token !== "string" || !data.token) throw new Error("bad payload");
+        acctToken = data.token;
+        acctTokenState = "ok";
+        renderAcctToken();
+      })
+      .catch(function () {
+        acctTokenState = "unavailable"; // fail explicitly — no localStorage fallback
+        renderAcctToken();
+      });
+  }
+
+  function closeAcctMenu() {
+    var menu = document.getElementById("acct-menu");
+    if (!menu) return;
+    menu.classList.remove("open");
+    var trigger = document.getElementById("acct-trigger");
+    if (trigger) trigger.setAttribute("aria-expanded", "false");
+    // Masked again + connect section collapsed on EVERY close (locked design).
+    acctRevealed = false;
+    var details = document.getElementById("acct-connect");
+    if (details) details.removeAttribute("open");
+    renderAcctToken();
+  }
+
+  function openAcctMenu() {
+    var menu = document.getElementById("acct-menu");
+    if (!menu) return;
+    menu.classList.add("open");
+    document.getElementById("acct-trigger").setAttribute("aria-expanded", "true");
+    fetchAcctToken(); // lazy — one attempt, on first open only
+  }
+
+  // Clipboard helper: async API when available, temporary <textarea> +
+  // execCommand fallback (http remote origins lack the async clipboard API).
+  // Brief "Copied" feedback (label swap for ~1.5 s); total failure alerts.
+  function copyToClipboard(text, btn) {
+    var flash = function () {
+      var orig = btn.dataset.origLabel || (btn.dataset.origLabel = btn.textContent);
+      btn.textContent = "Copied";
+      clearTimeout(btn._copiedTimer);
+      btn._copiedTimer = setTimeout(function () { btn.textContent = orig; }, 1500);
+    };
+    var legacy = function () {
+      try {
+        var ta = document.createElement("textarea");
+        ta.value = text;
+        ta.style.position = "fixed";
+        ta.style.opacity = "0";
+        document.body.appendChild(ta);
+        ta.select();
+        var ok = document.execCommand("copy");
+        document.body.removeChild(ta);
+        return ok;
+      } catch (e) { return false; }
+    };
+    var fallback = function () {
+      if (legacy()) { flash(); return; }
+      alert("Copy failed — select the text and copy it manually.");
+    };
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      navigator.clipboard.writeText(text).then(flash, fallback);
+    } else {
+      fallback();
+    }
+  }
+
+  // Sign-out is CLIENT-SIDE ONLY (#365): there is no server session to
+  // invalidate in the Hicortex server itself — auth is per-request bearer, so
+  // dropping the locally stored tokens IS the sign-out. (The hosted router
+  // separately keeps a Google session cookie and offers /auth/logout — out of
+  // scope here; this only ends the browser's console session.)
+  function signOut() {
+    try {
+      localStorage.removeItem("hicortexToken");
+      localStorage.removeItem("hicortex-dashboard-token");
+    } catch (e) { /* private mode — reload anyway */ }
+    location.reload(); // back to the unauthenticated 401-prompt state
+  }
+
+  function wireAcctMenu() {
+    var trigger = document.getElementById("acct-trigger");
+    if (!trigger) return;
+    trigger.addEventListener("click", function () {
+      var menu = document.getElementById("acct-menu");
+      if (menu && menu.classList.contains("open")) closeAcctMenu();
+      else openAcctMenu();
+    });
+    document.getElementById("acct-reveal").addEventListener("click", function () {
+      acctRevealed = !acctRevealed;
+      renderAcctToken();
+    });
+    var copyToken = document.getElementById("acct-copy-token");
+    copyToken.addEventListener("click", function () {
+      if (acctTokenState === "ok") copyToClipboard(acctConnectLine(), copyToken);
+    });
+    var copyCli = document.getElementById("acct-copy-cli");
+    copyCli.addEventListener("click", function () {
+      if (acctTokenState === "ok") {
+        copyToClipboard("npx @gamaze/hicortex init --server " + location.origin, copyCli);
+      }
+    });
+    var copyMcp = document.getElementById("acct-copy-mcp");
+    copyMcp.addEventListener("click", function () {
+      if (acctTokenState === "ok") copyToClipboard(acctMcpText(), copyMcp);
+    });
+    // Plan & billing lives on the dashboard page — navigate there (append
+    // ?token= when one is known, mirroring the shared-nav link handler) and
+    // land on the digest panel's budget/usage anchor (#371 lands there).
+    document.getElementById("acct-plan").addEventListener("click", function () {
+      var t = null;
+      try {
+        t = token
+          || localStorage.getItem("hicortexToken")
+          || localStorage.getItem("hicortex-dashboard-token");
+      } catch (e) { /* private mode — navigate without a token */ }
+      var u = new URL("/dashboard", location.origin);
+      if (t) u.searchParams.set("token", t);
+      u.hash = "plan-billing";
+      location.href = u.toString();
+    });
+    document.getElementById("acct-signout").addEventListener("click", signOut);
+    renderAcctToken();
+  }
+
+  // Click-outside + Escape close the menu (wired once; the handlers no-op
+  // when the menu isn't rendered).
+  document.addEventListener("click", function (e) {
+    var menu = document.getElementById("acct-menu");
+    if (!menu || !menu.classList.contains("open")) return;
+    var wrap = document.getElementById("nav-account");
+    if (wrap && wrap.contains(e.target)) return;
+    closeAcctMenu();
+  });
+  window.addEventListener("keydown", function (e) {
+    if (e.key === "Escape") closeAcctMenu();
+  });
+
   // =========================================================================
   // DOM references
   // =========================================================================

package/dist/backup.d.ts

@@ -129,19 +129,23 @@ export declare function runBackupHook(artifactPath: string, command: string | un
  */
 export declare function newestBackupArtifactMs(dir: string): number | undefined;
 /**
- * Prune a backup dir to the `retention` newest artifacts (#327). Matches ONLY
- * files named `hicortex-*.tar.gz` (the nightly/CLI artifact pattern) — anything
- * else in the dir (operator copies, notes) is never touched. Keeps the newest
- * `retention` by mtime, with the ISO filename (time-ordered by construction)
- * as a DESCENDING tie-break so equal mtimes resolve deterministically (the
- * just-written artifact is the newest and always survives); deletes the rest,
- * oldest first. `retention <= 0` keeps all.
+ * Prune a backup dir to the `retention` newest artifacts (#327). By default
+ * matches ONLY files named `hicortex-*.tar.gz` (the nightly/CLI artifact
+ * pattern); the optional `pattern` override scopes the prune to another
+ * product-owned filename family — e.g. the pre-dedup merge backups
+ * (`pre-dedup-*.db`, #392) keep their own retention count INDEPENDENT of the
+ * full-backup artifacts. Anything else in the dir (operator copies, notes) is
+ * never touched. Keeps the newest `retention` by mtime, with the ISO filename
+ * (time-ordered by construction) as a DESCENDING tie-break so equal mtimes
+ * resolve deterministically (the just-written artifact is the newest and
+ * always survives); deletes the rest, oldest first. `retention <= 0` keeps
+ * all.
  *
  * Best-effort by design: a per-file unlink failure logs and continues (a
  * stale extra artifact is cheap; failing the nightly AFTER a good backup was
  * written is not). Returns the number actually removed.
  */
-export declare function pruneBackupArtifacts(dir: string, retention: number): number;
+export declare function pruneBackupArtifacts(dir: string, retention: number, pattern?: RegExp): number;
 export interface BackupCliOptions {
     /** `--out <dir>` — output directory (the artifact is auto-named). Takes precedence over `config.backupDir`. Mutually exclusive with stdout. */
     outDir?: string;

package/dist/backup.js

@@ -282,19 +282,23 @@ function newestBackupArtifactMs(dir) {
     return newest;
 }
 /**
- * Prune a backup dir to the `retention` newest artifacts (#327). Matches ONLY
- * files named `hicortex-*.tar.gz` (the nightly/CLI artifact pattern) — anything
- * else in the dir (operator copies, notes) is never touched. Keeps the newest
- * `retention` by mtime, with the ISO filename (time-ordered by construction)
- * as a DESCENDING tie-break so equal mtimes resolve deterministically (the
- * just-written artifact is the newest and always survives); deletes the rest,
- * oldest first. `retention <= 0` keeps all.
+ * Prune a backup dir to the `retention` newest artifacts (#327). By default
+ * matches ONLY files named `hicortex-*.tar.gz` (the nightly/CLI artifact
+ * pattern); the optional `pattern` override scopes the prune to another
+ * product-owned filename family — e.g. the pre-dedup merge backups
+ * (`pre-dedup-*.db`, #392) keep their own retention count INDEPENDENT of the
+ * full-backup artifacts. Anything else in the dir (operator copies, notes) is
+ * never touched. Keeps the newest `retention` by mtime, with the ISO filename
+ * (time-ordered by construction) as a DESCENDING tie-break so equal mtimes
+ * resolve deterministically (the just-written artifact is the newest and
+ * always survives); deletes the rest, oldest first. `retention <= 0` keeps
+ * all.
  *
  * Best-effort by design: a per-file unlink failure logs and continues (a
  * stale extra artifact is cheap; failing the nightly AFTER a good backup was
  * written is not). Returns the number actually removed.
  */
-function pruneBackupArtifacts(dir, retention) {
+function pruneBackupArtifacts(dir, retention, pattern = /^hicortex-.*\.tar\.gz$/) {
     if (!Number.isFinite(retention) || retention <= 0)
         return 0;
     let names;
@@ -306,7 +310,7 @@ function pruneBackupArtifacts(dir, retention) {
         return 0;
     }
     const artifacts = names
-        .filter((n) => /^hicortex-.*\.tar\.gz$/.test(n))
+        .filter((n) => pattern.test(n))
         .map((n) => {
         const abs = (0, node_path_1.join)(dir, n);
         let mtimeMs = 0;

package/dist/claude-desktop.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Claude Desktop auto-configuration (#381) — the init-side writer for the
+ * `claude_desktop_config.json` MCP entry.
+ *
+ * Claude Desktop's ONLY stdio MCP route is this hand-edited file (no CLI, no
+ * plugin discovery), which is why Desktop never had an init step while CC
+ * (`claude mcp add`), Pi, and opencode (dropped extension files) did. The
+ * 0.20.4 `hicortex mcp` stdio bridge makes such an entry meaningful, so init
+ * now offers to write it — the same auto-detect pattern as the other
+ * harnesses, gated on the Claude Desktop config DIRECTORY existing (the
+ * config FILE may not exist yet; creating it fresh is in scope).
+ *
+ * Two properties dominate the design:
+ *
+ *   1. IT IS ANOTHER APP'S FILE. `claude_desktop_config.json` is owned by
+ *      Claude Desktop and carries the user's other servers and app settings.
+ *      The write is therefore merge-safe (preserve EVERY top-level key and
+ *      every other server; touch only `mcpServers.hicortex`), takes a
+ *      timestamped `.bak` copy of the existing file first, lands via
+ *      tmp-write + JSON-validate + rename in the same directory (atomic),
+ *      and REFUSES — touching nothing, not even a backup — when the existing
+ *      file is not valid JSON. Unlike our own config.json there is no repair
+ *      flow here (quarantening another app's config would break IT); the
+ *      user fixes the file by hand with the snippet init prints.
+ *
+ *   2. THE COMMAND MUST BE AN ABSOLUTE NPX PATH. Desktop is a GUI app and
+ *      does not inherit the shell PATH — a bare "npx" command is the #1
+ *      Desktop MCP failure mode. Resolution walks PATH plus the common
+ *      install locations and rejects npm's ephemeral `/_npx/` cache (#176: a
+ *      path that dies on the next cache GC — the entry would break silently
+ *      weeks later). Unresolvable → manual instructions, nothing written.
+ *      Windows .cmd shims cannot be spawned by Electron without a shell, so
+ *      they are wrapped in `cmd /c`.
+ *
+ * Every helper is pure/parametrised (platform/env/home/exists injected) so
+ * the suite covers darwin/win32/linux without touching a real machine. This
+ * module deliberately imports NOTHING from init.ts (init imports this — no
+ * cycle); the package spec is passed in from init's getPackageSpec().
+ */
+/**
+ * The Claude Desktop config directory for this platform, or null where no
+ * Desktop build exists (Linux → silent skip). Parametrised so tests cover
+ * the platform matrix without a real machine. Detection in init is
+ * `desktopConfigDir() !== null && existsSync(dir)` — the config FILE itself
+ * may legitimately not exist yet.
+ */
+export declare function desktopConfigDir(platform?: NodeJS.Platform, env?: Record<string, string | undefined>, home?: string): string | null;
+export interface DesktopNpxResolveOptions {
+    /** The PATH string to search (default: process.env.PATH). */
+    pathEnv?: string;
+    /** Platform under test (default: the real one). */
+    platform?: NodeJS.Platform;
+    /** Home dir for the ~-relative common locations (default: homedir()). */
+    home?: string;
+    /** Env for APPDATA on win32 (default: process.env). */
+    env?: Record<string, string | undefined>;
+    /** Existence seam (default: existsSync) — unit tests pass fixture sets. */
+    exists?: (candidatePath: string) => boolean;
+}
+/**
+ * Resolve an ABSOLUTE npx path for the Desktop entry, or null when nothing
+ * durable exists (init then prints manual instructions and writes nothing).
+ * Rejects npm's ephemeral npx cache in BOTH separator spellings — unix
+ * `/_npx/` and Windows `\_npx\` — a bare includes("/_npx/") would let the
+ * win32 form through (#176: the path dies on the next cache GC).
+ */
+export declare function resolveDesktopNpxPath(options?: DesktopNpxResolveOptions): string | null;
+/** The `mcpServers.hicortex` value — a Claude Desktop stdio server entry. */
+export interface DesktopServerEntry {
+    command: string;
+    args: string[];
+    /** Only in remote mode; absent (not empty) in local/loopback mode. */
+    env?: Record<string, string>;
+}
+/**
+ * Build the stdio entry for the `hicortex mcp` bridge. NO "type" field —
+ * stdio is implied for Desktop entries (the CC `.claude.json` writer needs
+ * `"type":"sse"`; this is the other shape). A `.cmd`/`.bat` shim is wrapped
+ * in `cmd /c` because Electron spawns without a shell and cannot exec a cmd
+ * script directly. An empty/absent env omits the key entirely — a local
+ * entry must carry no env (the bridge autostarts the daemon; loopback
+ * bypasses auth).
+ */
+export declare function buildDesktopServerEntry(npxPath: string, packageSpec: string, env?: Record<string, string>): DesktopServerEntry;
+/**
+ * Loopback check for a server URL — decides whether the Desktop entry needs
+ * an env block at all (local: none, the bridge resolves + autostarts the
+ * daemon; remote: URL + token). Mirrors mcp-stdio's isLoopbackHost (kept
+ * local rather than imported to avoid dragging the SDK into init's graph).
+ * An unparseable URL is NOT local — fail toward carrying the env, which
+ * still works everywhere the URL is real.
+ */
+export declare function isLocalServerUrl(url: string): boolean;
+export type DesktopMergeResult = {
+    ok: true;
+    config: Record<string, unknown>;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Parse the existing config text and merge our entry in, preserving every
+ * top-level key and every other server. `rawText === null` means "no file"
+ * (fresh install — a config containing only our entry is created). Malformed
+ * JSON, a non-object document, or a non-object `mcpServers` value returns
+ * `{ ok: false }` — the caller refuses to write, so the ORIGINAL file and
+ * its bytes are what the user keeps.
+ */
+export declare function mergeDesktopServerConfig(rawText: string | null, entry: DesktopServerEntry): DesktopMergeResult;
+export type DesktopWriteResult = {
+    status: "written";
+    backupPath?: string;
+} | {
+    status: "refused";
+    reason: string;
+} | {
+    status: "failed";
+    reason: string;
+};
+/**
+ * Orchestrate the merge-safe, atomic write of our entry into
+ * `claude_desktop_config.json`:
+ *
+ *   1. Read the existing file (ENOENT → fresh-install path).
+ *   2. Merge; a malformed/shape-refused file → `{ status: "refused" }` with
+ *      NOTHING touched — no backup, no tmp, no bytes changed.
+ *   3. Copy the existing file to `<path>.bak-<ISO-colons-stripped>` BEFORE
+ *      writing (the quarantineMalformedConfig naming convention).
+ *   4. Write the serialized payload to a tmp file in the SAME directory
+ *      (same filesystem → the rename is atomic), JSON-parse the exact bytes
+ *      that landed on disk, then renameSync over the target.
+ *
+ * Any unexpected I/O error returns `{ status: "failed" }` after removing the
+ * tmp file — a half-written tmp must never masquerade as a config. Never
+ * throws; the init wiring turns every non-"written" result into a printed
+ * warning and init continues.
+ */
+export declare function writeDesktopServerConfig(configPath: string, entry: DesktopServerEntry): DesktopWriteResult;