shortcutxl 0.3.57 → 0.3.58

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [0.3.58]
+
+- **Improved update reliability** - ShortcutXL now shows clearer update errors when Windows blocks a global package upgrade.
+
 ## [0.3.57]
 
 - **Improved Windows reliability** - Improved ShortcutXL install, upgrade, and uninstall behavior on Windows.

package/dist/cli.js

@@ -26528,7 +26528,7 @@ var require_snapshot_recorder = __commonJS({
   "../../node_modules/.pnpm/undici@7.25.0/node_modules/undici/lib/mock/snapshot-recorder.js"(exports, module) {
     "use strict";
     var { writeFile: writeFile10, readFile: readFile11, mkdir: mkdir11 } = __require("node:fs/promises");
-    var { dirname: dirname37, resolve: resolve22 } = __require("node:path");
+    var { dirname: dirname38, resolve: resolve22 } = __require("node:path");
     var { setTimeout: setTimeout2, clearTimeout: clearTimeout2 } = __require("node:timers");
     var { InvalidArgumentError, UndiciError } = require_errors();
     var { hashId, isUrlExcludedFactory, normalizeHeaders: normalizeHeaders2, createHeaderFilters } = require_snapshot_utils();
@@ -26759,7 +26759,7 @@ var require_snapshot_recorder = __commonJS({
           throw new InvalidArgumentError("Snapshot path is required");
         }
         const resolvedPath = resolve22(path21);
-        await mkdir11(dirname37(resolvedPath), { recursive: true });
+        await mkdir11(dirname38(resolvedPath), { recursive: true });
         const data = Array.from(this.#snapshots.entries()).map(([hash2, snapshot]) => ({
           hash: hash2,
           snapshot
@@ -474819,13 +474819,46 @@ var init_shell = __esm({
   }
 });
 
+// src/startup/python-abi.ts
+import { existsSync as existsSync42, readdirSync as readdirSync12 } from "fs";
+function listVersionedPythonRuntimeFiles(pythonDir) {
+  if (!existsSync42(pythonDir)) return /* @__PURE__ */ new Set();
+  try {
+    return new Set(
+      readdirSync12(pythonDir).filter((entry) => VERSIONED_PYTHON_RUNTIME_FILE.test(entry)).map((entry) => entry.toLowerCase())
+    );
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
+function hasVersionedPythonRuntimeFileDrift(sourcePythonDir, destPythonDir) {
+  const sourceFiles = listVersionedPythonRuntimeFiles(sourcePythonDir);
+  if (sourceFiles.size === 0) return false;
+  const destFiles = listVersionedPythonRuntimeFiles(destPythonDir);
+  if (destFiles.size === 0) return false;
+  for (const file2 of destFiles) {
+    if (!sourceFiles.has(file2)) return true;
+  }
+  for (const file2 of sourceFiles) {
+    if (!destFiles.has(file2)) return true;
+  }
+  return false;
+}
+var VERSIONED_PYTHON_RUNTIME_FILE;
+var init_python_abi = __esm({
+  "src/startup/python-abi.ts"() {
+    "use strict";
+    VERSIONED_PYTHON_RUNTIME_FILE = /^python\d{2,}(?:\.dll|\.zip|\._pth)$/i;
+  }
+});
+
 // src/startup/sync-xll.ts
 import { createHash as createHash3 } from "crypto";
 import {
   copyFileSync,
-  existsSync as existsSync42,
+  existsSync as existsSync43,
   mkdirSync as mkdirSync20,
-  readdirSync as readdirSync12,
+  readdirSync as readdirSync13,
   readFileSync as readFileSync33,
   rmSync as rmSync4,
   statSync as statSync11,
@@ -474841,7 +474874,7 @@ function stripMotw(filePath) {
   }
 }
 function filesMatch(src, dest) {
-  if (!existsSync42(dest)) return false;
+  if (!existsSync43(dest)) return false;
   const srcStat = statSync11(src);
   const destStat = statSync11(dest);
   return srcStat.size === destStat.size && srcStat.mtimeMs === destStat.mtimeMs;
@@ -474851,11 +474884,11 @@ function filesContentMatch(src, dest) {
   return hash2(src) === hash2(dest);
 }
 function syncDir(src, dest) {
-  if (!existsSync42(src)) return { updated: 0, staleLocked: false };
+  if (!existsSync43(src)) return { updated: 0, staleLocked: false };
   mkdirSync20(dest, { recursive: true });
   let updated = 0;
   let staleLocked = false;
-  for (const entry of readdirSync12(src)) {
+  for (const entry of readdirSync13(src)) {
     const srcPath = join58(src, entry);
     const destPath = join58(dest, entry);
     const stat8 = statSync11(srcPath);
@@ -474886,28 +474919,8 @@ function syncDir(src, dest) {
   }
   return { updated, staleLocked };
 }
-function listVersionedPythonRuntimeFiles(pythonDir) {
-  if (!existsSync42(pythonDir)) return /* @__PURE__ */ new Set();
-  try {
-    return new Set(
-      readdirSync12(pythonDir).filter((entry) => /^python\d{2,}(?:\.dll|\.zip|\._pth)$/i.test(entry)).map((entry) => entry.toLowerCase())
-    );
-  } catch {
-    return /* @__PURE__ */ new Set();
-  }
-}
 function hasPythonAbiDrift(shippedDir, stableDir) {
-  const shippedRuntimeFiles = listVersionedPythonRuntimeFiles(join58(shippedDir, "python"));
-  if (shippedRuntimeFiles.size === 0) return false;
-  const stableRuntimeFiles = listVersionedPythonRuntimeFiles(join58(stableDir, "python"));
-  if (stableRuntimeFiles.size === 0) return false;
-  for (const file2 of stableRuntimeFiles) {
-    if (!shippedRuntimeFiles.has(file2)) return true;
-  }
-  for (const file2 of shippedRuntimeFiles) {
-    if (!stableRuntimeFiles.has(file2)) return true;
-  }
-  return false;
+  return hasVersionedPythonRuntimeFileDrift(join58(shippedDir, "python"), join58(stableDir, "python"));
 }
 function resetStablePythonRuntime(stableDir) {
   try {
@@ -474937,11 +474950,11 @@ function syncXll() {
   mkdirSync20(stableDir, { recursive: true });
   const pythonRuntimeNeedsReset = hasPythonAbiDrift(shippedDir, stableDir);
   try {
-    if (existsSync42(versionFile)) {
+    if (existsSync43(versionFile)) {
       const stamped = readFileSync33(versionFile, "utf-8").trim();
       if (stamped === VERSION) {
-        const xllReady2 = existsSync42(stableXll);
-        const shippedXllReady = existsSync42(shippedXll);
+        const xllReady2 = existsSync43(stableXll);
+        const shippedXllReady = existsSync43(shippedXll);
         if (!pythonRuntimeNeedsReset && (!shippedXllReady || xllReady2 && filesContentMatch(shippedXll, stableXll))) {
           return { updated: 0, stableDir, xllReady: xllReady2, skipped: true, staleLocked: false };
         }
@@ -474956,7 +474969,7 @@ function syncXll() {
     hasStaleLockedFiles = true;
     syncFailed = true;
   }
-  if (existsSync42(shippedDir)) {
+  if (existsSync43(shippedDir)) {
     try {
       const { updated, staleLocked } = syncDir(shippedDir, stableDir);
       totalUpdated += updated;
@@ -474977,7 +474990,7 @@ function syncXll() {
     } catch {
     }
   }
-  const xllReady = existsSync42(stableXll);
+  const xllReady = existsSync43(stableXll);
   return {
     updated: totalUpdated,
     stableDir,
@@ -474991,13 +475004,14 @@ var init_sync_xll = __esm({
   "src/startup/sync-xll.ts"() {
     "use strict";
     init_config();
+    init_python_abi();
     SYNC_VERSION_FILE = ".sync-version";
     PIP_VERSION_FILE = ".pip-version";
   }
 });
 
 // src/startup/startup-xll.ts
-import { existsSync as existsSync43 } from "fs";
+import { existsSync as existsSync44 } from "fs";
 import { join as join59 } from "path";
 function getSourceCheckoutRequiredPaths() {
   return [
@@ -475011,7 +475025,7 @@ function resolveStartupXll({
   needsSetup
 }) {
   if (sourceCheckout) {
-    const missingPaths = getSourceCheckoutRequiredPaths().filter((p2) => !existsSync43(p2));
+    const missingPaths = getSourceCheckoutRequiredPaths().filter((p2) => !existsSync44(p2));
     return missingPaths.length === 0 ? { kind: "ok", updated: 0 } : { kind: "source-missing", missingPaths };
   }
   const result = syncXll();
@@ -475713,7 +475727,7 @@ var init_mog_command = __esm({
 });
 
 // src/app/permissions/permissions-command.ts
-import { existsSync as existsSync44, statSync as statSync12 } from "fs";
+import { existsSync as existsSync45, statSync as statSync12 } from "fs";
 import { join as join60 } from "path";
 function getGlobalSettingsPath() {
   return join60(getAgentDir(), "settings.json");
@@ -475724,7 +475738,7 @@ function normalizeWorkspaceRoot(input, cwd) {
     return "Workspace path is required";
   }
   const resolved = resolveToCwd(trimmed, cwd);
-  if (!existsSync44(resolved)) {
+  if (!existsSync45(resolved)) {
     return `Path does not exist: ${resolved}`;
   }
   try {
@@ -475746,7 +475760,7 @@ function normalizeFilesystemGrantPath(input, cwd, scope) {
     return "Grant path is required";
   }
   const resolved = resolveToCwd(trimmed, cwd);
-  if (!existsSync44(resolved)) {
+  if (!existsSync45(resolved)) {
     return `Path does not exist: ${resolved}`;
   }
   try {
@@ -476527,9 +476541,9 @@ var init_remote_skill_files = __esm({
 // src/app/sync/skills-download.ts
 import { createHash as createHash4 } from "crypto";
 import {
-  existsSync as existsSync45,
+  existsSync as existsSync46,
   mkdirSync as mkdirSync21,
-  readdirSync as readdirSync13,
+  readdirSync as readdirSync14,
   readFileSync as readFileSync34,
   rmSync as rmSync5,
   statSync as statSync13,
@@ -476543,9 +476557,9 @@ function getSkillsDir() {
   return join61(getAgentDir(), "skills");
 }
 function collectLocalFiles(dir, rootDir = dir) {
-  if (!existsSync45(dir)) return [];
+  if (!existsSync46(dir)) return [];
   const files = [];
-  for (const entry of readdirSync13(dir, { withFileTypes: true })) {
+  for (const entry of readdirSync14(dir, { withFileTypes: true })) {
     const fullPath = join61(dir, entry.name);
     if (entry.isDirectory()) {
       files.push(...collectLocalFiles(fullPath, rootDir));
@@ -476847,7 +476861,7 @@ var init_skills_download = __esm({
 
 // src/app/sync/skills-status.ts
 import { createHash as createHash5 } from "crypto";
-import { existsSync as existsSync46, readdirSync as readdirSync14, readFileSync as readFileSync35 } from "fs";
+import { existsSync as existsSync47, readdirSync as readdirSync15, readFileSync as readFileSync35 } from "fs";
 import { join as join62, relative as relative10 } from "path";
 function sha2562(data) {
   return createHash5("sha256").update(data).digest("hex");
@@ -476856,13 +476870,13 @@ function getSkillsDir2() {
   return join62(getAgentDir(), "skills");
 }
 function listLocalSkillNames(skillsDir) {
-  if (!existsSync46(skillsDir)) return [];
-  return readdirSync14(skillsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map((entry) => entry.name).sort();
+  if (!existsSync47(skillsDir)) return [];
+  return readdirSync15(skillsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map((entry) => entry.name).sort();
 }
 function collectLocalFiles2(dir, rootDir = dir) {
-  if (!existsSync46(dir)) return [];
+  if (!existsSync47(dir)) return [];
   const files = [];
-  for (const entry of readdirSync14(dir, { withFileTypes: true })) {
+  for (const entry of readdirSync15(dir, { withFileTypes: true })) {
     const fullPath = join62(dir, entry.name);
     if (entry.isDirectory()) {
       files.push(...collectLocalFiles2(fullPath, rootDir));
@@ -477104,7 +477118,7 @@ var init_skills_status = __esm({
 
 // src/app/sync/skills-upload.ts
 import { createHash as createHash6 } from "crypto";
-import { existsSync as existsSync47, readdirSync as readdirSync15, readFileSync as readFileSync36, statSync as statSync14 } from "fs";
+import { existsSync as existsSync48, readdirSync as readdirSync16, readFileSync as readFileSync36, statSync as statSync14 } from "fs";
 import { join as join63, relative as relative11 } from "path";
 function sha2563(data) {
   return createHash6("sha256").update(data).digest("hex");
@@ -477113,8 +477127,8 @@ function getSkillsDir3() {
   return join63(getAgentDir(), "skills");
 }
 function listLocalSkillNames2(skillsDir) {
-  if (!existsSync47(skillsDir)) return [];
-  return readdirSync15(skillsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map((entry) => entry.name).sort();
+  if (!existsSync48(skillsDir)) return [];
+  return readdirSync16(skillsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map((entry) => entry.name).sort();
 }
 function validateSkillName2(name, parentDirName) {
   const errors = [];
@@ -477137,7 +477151,7 @@ function validateSkillName2(name, parentDirName) {
 }
 function validateLocalSkill(skillName, skillDir) {
   const skillPath = join63(skillDir, "SKILL.md");
-  if (!existsSync47(skillPath)) {
+  if (!existsSync48(skillPath)) {
     return "missing SKILL.md";
   }
   try {
@@ -477158,7 +477172,7 @@ function validateLocalSkill(skillName, skillDir) {
 }
 function collectLocalFiles3(dir, rootDir = dir) {
   const files = [];
-  for (const entry of readdirSync15(dir, { withFileTypes: true })) {
+  for (const entry of readdirSync16(dir, { withFileTypes: true })) {
     const fullPath = join63(dir, entry.name);
     if (entry.isDirectory()) {
       files.push(...collectLocalFiles3(fullPath, rootDir));
@@ -477409,7 +477423,7 @@ var init_skills_upload = __esm({
 });
 
 // src/startup/interactive-commands.ts
-import { existsSync as existsSync48 } from "fs";
+import { existsSync as existsSync49 } from "fs";
 async function fetchAuthorizedSkillTeamIds(accessToken) {
   const userInfo = await fetchUserInfo(accessToken);
   if (!userInfo) return null;
@@ -477443,7 +477457,7 @@ function createInteractiveCommandHandler(context) {
     }
     if (command === "/docs") {
       const docsFile = getUserDocsPath();
-      if (existsSync48(docsFile)) {
+      if (existsSync49(docsFile)) {
         void openInEditor(docsFile).catch(
           (error2) => showStatus(`Could not open documentation: ${formatOpenError(error2)}`)
         );
@@ -477781,12 +477795,12 @@ var init_install_utils = __esm({
 });
 
 // src/startup/preflight/shared.ts
-import { chmodSync as chmodSync3, existsSync as existsSync49, mkdirSync as mkdirSync22, readFileSync as readFileSync37, unlinkSync as unlinkSync8, writeFileSync as writeFileSync20 } from "fs";
+import { chmodSync as chmodSync3, existsSync as existsSync50, mkdirSync as mkdirSync22, readFileSync as readFileSync37, unlinkSync as unlinkSync8, writeFileSync as writeFileSync20 } from "fs";
 import { dirname as dirname34, join as join64 } from "path";
 async function ensureUv(platformTarget) {
   header("Python Toolchain");
   const uvPath = getUvBinPath();
-  if (existsSync49(uvPath)) {
+  if (existsSync50(uvPath)) {
     const check2 = run(`"${uvPath}" --version`, { timeout: 5e3 });
     if (check2.ok) {
       ok(`uv ${check2.stdout.replace("uv ", "").trim()} installed.`);
@@ -477842,7 +477856,7 @@ async function ensureUvPython() {
   const uvPath = getUvBinPath();
   const venvDir = getUvVenvDir();
   const venvPython = join64(venvDir, "bin", "python3");
-  if (existsSync49(venvPython)) {
+  if (existsSync50(venvPython)) {
     const check2 = run(`"${venvPython}" --version`, { timeout: 5e3 });
     if (check2.ok) {
       ok(`${check2.stdout.trim()} ready.`);
@@ -477877,7 +477891,7 @@ async function ensureUvPackages() {
   const uvPath = getUvBinPath();
   const venvDir = getUvVenvDir();
   const venvPython = join64(venvDir, "bin", "python3");
-  if (!existsSync49(venvPython)) {
+  if (!existsSync50(venvPython)) {
     log2(
       "Shortcut agent will install packages after Python is ready.",
       "Will finish setup automatically."
@@ -477887,7 +477901,7 @@ async function ensureUvPackages() {
   const stampFile = join64(venvDir, ".packages-stamp");
   const stampValue = `${VERSION}:${UV_PIP_PACKAGES.join(",")}`;
   try {
-    if (existsSync49(stampFile) && readFileSync37(stampFile, "utf-8").trim() === stampValue) {
+    if (existsSync50(stampFile) && readFileSync37(stampFile, "utf-8").trim() === stampValue) {
       ok("Packages already installed.", "Ready.");
       return;
     }
@@ -477971,13 +477985,13 @@ __export(mac_exports, {
   ensureUvPython: () => ensureUvPython,
   smokeTestSheetEngine: () => smokeTestSheetEngine
 });
-import { existsSync as existsSync50 } from "fs";
+import { existsSync as existsSync51 } from "fs";
 async function ensureUv2() {
   return ensureUv("apple-darwin");
 }
 function ensureChromeMac() {
   header("Chrome");
-  if (existsSync50("/Applications/Google Chrome.app")) {
+  if (existsSync51("/Applications/Google Chrome.app")) {
     ok("Chrome found \u2014 SEC filing support ready.");
   } else {
     log2("Chrome not installed \u2014 Shortcut agent can set this up for SEC filing support.");
@@ -478001,13 +478015,13 @@ __export(linux_exports, {
   ensureUvPython: () => ensureUvPython,
   smokeTestSheetEngine: () => smokeTestSheetEngine
 });
-import { existsSync as existsSync51 } from "fs";
+import { existsSync as existsSync52 } from "fs";
 async function ensureUv3() {
   return ensureUv("unknown-linux-gnu");
 }
 function ensureChromeLinux() {
   header("Chrome");
-  const found = LINUX_CHROME_PATHS.find((p2) => existsSync51(p2));
+  const found = LINUX_CHROME_PATHS.find((p2) => existsSync52(p2));
   if (found) {
     ok("Chrome found \u2014 SEC filing support ready.");
   } else {
@@ -478039,12 +478053,12 @@ __export(windows_exports, {
   ensureXllRegistry: () => ensureXllRegistry,
   smokeTestExcel: () => smokeTestExcel
 });
-import { existsSync as existsSync52, readFileSync as readFileSync38, writeFileSync as writeFileSync21 } from "fs";
+import { existsSync as existsSync53, readFileSync as readFileSync38, writeFileSync as writeFileSync21 } from "fs";
 import { join as join65, resolve as resolve18 } from "path";
 async function ensurePipPackages() {
   header("Python Packages", "Calculation Engine");
   const pythonExe = getEmbeddedPythonExe();
-  if (!existsSync52(pythonExe)) {
+  if (!existsSync53(pythonExe)) {
     log2("Shortcut agent will set up Python.", "Will finish setup automatically.");
     return;
   }
@@ -478063,7 +478077,7 @@ async function ensurePipPackages() {
   const pipStampFile = join65(getStableXllDir(), ".pip-version");
   let pipUpToDate = false;
   try {
-    pipUpToDate = existsSync52(pipStampFile) && readFileSync38(pipStampFile, "utf-8").trim() === VERSION;
+    pipUpToDate = existsSync53(pipStampFile) && readFileSync38(pipStampFile, "utf-8").trim() === VERSION;
   } catch {
   }
   if (pipUpToDate) {
@@ -478093,7 +478107,7 @@ async function ensureChromeWindows() {
     return;
   }
   const pythonExe = getEmbeddedPythonExe();
-  if (!existsSync52(pythonExe)) {
+  if (!existsSync53(pythonExe)) {
     log2("Shortcut agent will set up Chrome.", "Will finish setup automatically.");
     return;
   }
@@ -478177,7 +478191,7 @@ async function ensureGitBash() {
 function ensureXllRegistry() {
   header("Excel Add-in", "Excel Integration");
   const xllPath = resolve18(getXllPath()).replace(/\//g, "\\");
-  if (!existsSync52(xllPath)) {
+  if (!existsSync53(xllPath)) {
     log2("Shortcut agent will set up the Excel add-in.", "Will finish setup automatically.");
     return;
   }
@@ -478373,7 +478387,7 @@ var diagnostics_exports = {};
 __export(diagnostics_exports, {
   collectPreflightDiagnostics: () => collectPreflightDiagnostics
 });
-import { closeSync as closeSync2, existsSync as existsSync53, openSync as openSync2, readSync as readSync2, statSync as statSync15 } from "fs";
+import { closeSync as closeSync2, existsSync as existsSync54, openSync as openSync2, readSync as readSync2, statSync as statSync15 } from "fs";
 import { resolve as resolve19 } from "path";
 function safeRun(command, timeout = DIAGNOSTIC_TIMEOUT_MS) {
   try {
@@ -478498,7 +478512,7 @@ function collectXllLog() {
     `${process.env.TEMP ?? ""}\\shortcutxl.log`
   ];
   for (const path21 of logPaths) {
-    if (path21 && existsSync53(path21)) {
+    if (path21 && existsSync54(path21)) {
       return readLogTail(path21);
     }
   }
@@ -478550,7 +478564,7 @@ function collectPreflightDiagnostics() {
   setCurrentStep("diagnostics");
   const xllPath = resolve19(getXllPath()).replace(/\//g, "\\");
   const diagnostics = {
-    xllExists: existsSync53(xllPath),
+    xllExists: existsSync54(xllPath),
     xllPath,
     motw: collectMotw(xllPath),
     xllArch: collectXllArch(xllPath),
@@ -478634,7 +478648,7 @@ var init_preflight = __esm({
 });
 
 // src/startup/prune-sessions.ts
-import { readdirSync as readdirSync16, rmSync as rmSync6, statSync as statSync16 } from "node:fs";
+import { readdirSync as readdirSync17, rmSync as rmSync6, statSync as statSync16 } from "node:fs";
 import { join as join66 } from "node:path";
 function pruneStaleFiles() {
   const cutoff = Date.now() - FOURTEEN_DAYS_MS;
@@ -478643,7 +478657,7 @@ function pruneStaleFiles() {
 function pruneSessionFiles(cutoff) {
   try {
     const sessionsRoot = getSessionsDir();
-    for (const projectDir of readdirSync16(sessionsRoot)) {
+    for (const projectDir of readdirSync17(sessionsRoot)) {
       pruneJsonlFilesRecursively(join66(sessionsRoot, projectDir), cutoff);
     }
   } catch {
@@ -478651,7 +478665,7 @@ function pruneSessionFiles(cutoff) {
 }
 function pruneJsonlFilesRecursively(dir, cutoff) {
   try {
-    for (const entry of readdirSync16(dir, { withFileTypes: true })) {
+    for (const entry of readdirSync17(dir, { withFileTypes: true })) {
       const entryPath = join66(dir, entry.name);
       if (entry.isDirectory()) {
         pruneJsonlFilesRecursively(entryPath, cutoff);
@@ -478751,19 +478765,38 @@ var init_session_selection = __esm({
 
 // src/startup/update-action.ts
 import { spawn as spawn12 } from "child_process";
+import { appendFileSync as appendFileSync6, mkdirSync as mkdirSync23 } from "fs";
+import { dirname as dirname35 } from "path";
 async function runForegroundUpdate(request, deps = {}) {
   const resolveShell = deps.resolveShell ?? getShellConfig;
   const resolveEnv = deps.resolveEnv ?? getShellEnv;
   const spawnProcess = deps.spawnProcess ?? spawn12;
+  const resolveLogPath = deps.resolveLogPath ?? getDebugLogPath;
   const shellConfig = resolveShell();
   return await new Promise((resolve22, reject) => {
+    const output = [];
+    let outputBytes = 0;
+    let outputTruncated = false;
     const child = spawnProcess(shellConfig.shell, [...shellConfig.args, request.command], {
       cwd: request.cwd ?? process.cwd(),
       env: resolveEnv(),
-      stdio: "inherit"
+      stdio: ["ignore", "pipe", "pipe"]
     });
+    const capture = (chunk) => {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+      const remaining = MAX_CAPTURED_OUTPUT_BYTES - outputBytes;
+      if (remaining > 0) {
+        output.push(buffer.subarray(0, remaining));
+        outputBytes += Math.min(buffer.length, remaining);
+      }
+      if (buffer.length > remaining) {
+        outputTruncated = true;
+      }
+    };
+    child.stdout?.on("data", capture);
+    child.stderr?.on("data", capture);
     child.once("error", reject);
-    child.once("exit", (exitCode, signal) => {
+    child.once("close", (exitCode, signal) => {
       if (exitCode === 0) {
         resolve22({
           kind: "success",
@@ -478772,24 +478805,83 @@ async function runForegroundUpdate(request, deps = {}) {
         });
         return;
       }
+      const capturedOutput = Buffer.concat(output).toString("utf-8");
+      const logPath = writeUpdateFailureLog({
+        command: request.command,
+        exitCode,
+        signal,
+        output: capturedOutput,
+        truncated: outputTruncated,
+        resolveLogPath
+      });
       resolve22({
         kind: "failed",
         exitCode,
-        signal
+        signal,
+        message: summarizeUpdateFailure(capturedOutput),
+        logPath
       });
     });
   });
 }
+function summarizeUpdateFailure(output) {
+  if (/EEXIST[\s\S]*shortcut\.cmd/i.test(output) || /File exists:[\s\S]*shortcut\.cmd/i.test(output)) {
+    return [
+      "ShortcutXL could not update because an existing global `shortcut` command blocked npm from replacing it.",
+      "Close any running ShortcutXL terminals, then run `npm uninstall -g shortcutxl` followed by `npm install -g shortcutxl@latest`."
+    ].join(" ");
+  }
+  if (/EPERM|ENOTEMPTY|ENOENT/i.test(output) && /AppData[\\/]+Roaming[\\/]+npm[\\/]+node_modules[\\/]+shortcutxl/i.test(output)) {
+    return [
+      "ShortcutXL could not update because npm could not clean up the previous global install.",
+      "Close ShortcutXL terminals and retry `npm install -g shortcutxl@latest`."
+    ].join(" ");
+  }
+  return "ShortcutXL could not update automatically. Retry with `npm install -g shortcutxl@latest`.";
+}
+function writeUpdateFailureLog({
+  command,
+  exitCode,
+  signal,
+  output,
+  truncated,
+  resolveLogPath
+}) {
+  try {
+    const logPath = resolveLogPath();
+    mkdirSync23(dirname35(logPath), { recursive: true });
+    appendFileSync6(
+      logPath,
+      [
+        "",
+        "--- ShortcutXL update failure ---",
+        `time=${(/* @__PURE__ */ new Date()).toISOString()}`,
+        `command=${command}`,
+        `exitCode=${String(exitCode)}`,
+        `signal=${String(signal)}`,
+        truncated ? `outputTruncatedAfterBytes=${MAX_CAPTURED_OUTPUT_BYTES}` : void 0,
+        output
+      ].filter((line) => line !== void 0).join("\n"),
+      "utf-8"
+    );
+    return logPath;
+  } catch {
+    return void 0;
+  }
+}
+var MAX_CAPTURED_OUTPUT_BYTES;
 var init_update_action = __esm({
   "src/startup/update-action.ts"() {
     "use strict";
     init_bash_runtime();
+    init_config();
+    MAX_CAPTURED_OUTPUT_BYTES = 1024 * 1024;
   }
 });
 
 // src/startup/update-manager.ts
-import { mkdirSync as mkdirSync23, readFileSync as readFileSync39, writeFileSync as writeFileSync22 } from "fs";
-import { dirname as dirname35 } from "path";
+import { mkdirSync as mkdirSync24, readFileSync as readFileSync39, writeFileSync as writeFileSync22 } from "fs";
+import { dirname as dirname36 } from "path";
 async function resolveStartupUpdateStatus(options2 = {}, deps = {}) {
   const cachePath = options2.cachePath ?? getUpdateCachePath();
   const currentVersion = options2.currentVersion ?? VERSION;
@@ -478902,7 +478994,7 @@ function readUpdateCache(cachePath) {
   }
 }
 function writeUpdateCache(cachePath, cache) {
-  mkdirSync23(dirname35(cachePath), { recursive: true });
+  mkdirSync24(dirname36(cachePath), { recursive: true });
   writeFileSync22(cachePath, `${JSON.stringify(cache, null, 2)}
 `, "utf-8");
 }
@@ -480350,7 +480442,7 @@ __export(uninstall_exports, {
   removeOwnedInstallArtifacts: () => removeOwnedInstallArtifacts,
   runUninstall: () => runUninstall
 });
-import { existsSync as existsSync54, readdirSync as readdirSync17, rmSync as rmSync7, rmdirSync } from "fs";
+import { existsSync as existsSync55, readdirSync as readdirSync18, rmSync as rmSync7, rmdirSync } from "fs";
 import { isAbsolute as isAbsolute10, join as join67, relative as relative12, resolve as resolve20 } from "path";
 function isWithinDir(parentDir, targetPath) {
   const parent = resolve20(parentDir);
@@ -480360,7 +480452,7 @@ function isWithinDir(parentDir, targetPath) {
 }
 function removeIfInsideAgentDir(agentDir, relativePath) {
   const target = join67(agentDir, relativePath);
-  if (!isWithinDir(agentDir, target) || !existsSync54(target)) {
+  if (!isWithinDir(agentDir, target) || !existsSync55(target)) {
     return false;
   }
   rmSync7(target, { recursive: true, force: true });
@@ -480368,10 +480460,10 @@ function removeIfInsideAgentDir(agentDir, relativePath) {
 }
 function removeEmptyDirIfInsideAgentDir(agentDir, relativePath) {
   const target = join67(agentDir, relativePath);
-  if (!isWithinDir(agentDir, target) || !existsSync54(target)) {
+  if (!isWithinDir(agentDir, target) || !existsSync55(target)) {
     return false;
   }
-  if (readdirSync17(target).length > 0) {
+  if (readdirSync18(target).length > 0) {
     return false;
   }
   rmdirSync(target);
@@ -480398,7 +480490,7 @@ function removeOwnedInstallArtifacts(agentDir) {
     }
   }
   try {
-    if (existsSync54(agentDir) && readdirSync17(agentDir).length === 0) {
+    if (existsSync55(agentDir) && readdirSync18(agentDir).length === 0) {
       rmdirSync(agentDir);
       result.removed.push(".");
     }
@@ -480474,7 +480566,7 @@ function runUninstall() {
   }
   header2("Playwright Browsers");
   const pythonExe = getEmbeddedPythonExe();
-  if (existsSync54(pythonExe)) {
+  if (existsSync55(pythonExe)) {
     const pwResult = run(`"${pythonExe}" -m playwright uninstall --all`, { timeout: 3e4 });
     if (pwResult.ok) {
       ok2("Removed Playwright browsers.");
@@ -480490,7 +480582,7 @@ function runUninstall() {
   }
   header2("Files");
   const agentDir = getAgentDir();
-  if (existsSync54(agentDir)) {
+  if (existsSync55(agentDir)) {
     const cleanup = removeOwnedInstallArtifacts(agentDir);
     if (cleanup.removed.length > 0) {
       ok2(`Removed generated install files from ${agentDir}`);
@@ -480543,7 +480635,7 @@ __export(main_exports, {
   isMogRuntimeEnabledForUser: () => isMogRuntimeEnabledForUser,
   main: () => main
 });
-import { existsSync as existsSync55 } from "fs";
+import { existsSync as existsSync56 } from "fs";
 async function resolveShortcutUserInfo(authStorage) {
   const accessToken = await authStorage.getApiKey(SHORTCUT_PROVIDER_ID);
   return accessToken ? fetchUserInfo(accessToken) : null;
@@ -480968,7 +481060,7 @@ async function main(args) {
   if (sandboxMode === "enabled" && sandboxAvailable) {
     const sandboxFrames = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
     let sandboxFrame = 0;
-    const needsDownload = !existsSync55(getAlpineRootfsPath());
+    const needsDownload = !existsSync56(getAlpineRootfsPath());
     const spinnerMsg = needsDownload ? "Downloading sandbox (~80 MB)..." : "Checking sandbox...";
     const sandboxSpinner = setInterval(() => {
       process.stderr.write(
@@ -481109,6 +481201,12 @@ async function main(args) {
     if (updateResult.kind === "failed") {
       const exitDetail = updateResult.exitCode !== null ? `exit code ${updateResult.exitCode}` : updateResult.signal ? `signal ${updateResult.signal}` : "unknown error";
       console.error(source_default.red(`Update failed (${exitDetail}). ShortcutXL will not launch.`));
+      if (updateResult.message) {
+        console.error(source_default.yellow(updateResult.message));
+      }
+      if (updateResult.logPath) {
+        console.error(source_default.dim(`Details were written to ${updateResult.logPath}`));
+      }
       process.exit(updateResult.exitCode ?? 1);
     }
     console.log(source_default.green(`Update to v${updatePromptOutcome.update.latestVersion} succeeded.`));
@@ -481571,9 +481669,9 @@ ${loop.prompt}`;
 
 // src/cli.ts
 var import_dotenv = __toESM(require_main(), 1);
-import { dirname as dirname36, resolve as resolve21 } from "path";
+import { dirname as dirname37, resolve as resolve21 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
-var __dirname3 = dirname36(fileURLToPath4(import.meta.url));
+var __dirname3 = dirname37(fileURLToPath4(import.meta.url));
 var agentRoot = resolve21(__dirname3, "..");
 import_dotenv.default.config({ path: resolve21(agentRoot, ".env.development") });
 process.title = "shortcut";

package/dist/main.js

@@ -669,6 +669,12 @@ export async function main(args) {
                     ? `signal ${updateResult.signal}`
                     : 'unknown error';
             console.error(chalk.red(`Update failed (${exitDetail}). ShortcutXL will not launch.`));
+            if (updateResult.message) {
+                console.error(chalk.yellow(updateResult.message));
+            }
+            if (updateResult.logPath) {
+                console.error(chalk.dim(`Details were written to ${updateResult.logPath}`));
+            }
             process.exit(updateResult.exitCode ?? 1);
         }
         console.log(chalk.green(`Update to v${updatePromptOutcome.update.latestVersion} succeeded.`));

package/dist/startup/python-abi.d.ts

@@ -0,0 +1,3 @@
+export declare function listVersionedPythonRuntimeFiles(pythonDir: string): Set<string>;
+export declare function hasVersionedPythonRuntimeFileDrift(sourcePythonDir: string, destPythonDir: string): boolean;
+//# sourceMappingURL=python-abi.d.ts.map

package/dist/startup/python-abi.js

@@ -0,0 +1,32 @@
+import { existsSync, readdirSync } from 'fs';
+const VERSIONED_PYTHON_RUNTIME_FILE = /^python\d{2,}(?:\.dll|\.zip|\._pth)$/i;
+export function listVersionedPythonRuntimeFiles(pythonDir) {
+    if (!existsSync(pythonDir))
+        return new Set();
+    try {
+        return new Set(readdirSync(pythonDir)
+            .filter((entry) => VERSIONED_PYTHON_RUNTIME_FILE.test(entry))
+            .map((entry) => entry.toLowerCase()));
+    }
+    catch {
+        return new Set();
+    }
+}
+export function hasVersionedPythonRuntimeFileDrift(sourcePythonDir, destPythonDir) {
+    const sourceFiles = listVersionedPythonRuntimeFiles(sourcePythonDir);
+    if (sourceFiles.size === 0)
+        return false;
+    const destFiles = listVersionedPythonRuntimeFiles(destPythonDir);
+    if (destFiles.size === 0)
+        return false;
+    for (const file of destFiles) {
+        if (!sourceFiles.has(file))
+            return true;
+    }
+    for (const file of sourceFiles) {
+        if (!destFiles.has(file))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=python-abi.js.map

package/dist/startup/sync-xll.js

@@ -22,6 +22,7 @@ import { createHash } from 'crypto';
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, unlinkSync, utimesSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { getPackageDir, getStableXllDir, VERSION } from '../config.js';
+import { hasVersionedPythonRuntimeFileDrift } from './python-abi.js';
 /** Strip the NTFS Zone.Identifier alternate data stream (Mark of the Web). */
 function stripMotw(filePath) {
     try {
@@ -101,34 +102,8 @@ function syncDir(src, dest) {
 }
 const SYNC_VERSION_FILE = '.sync-version';
 const PIP_VERSION_FILE = '.pip-version';
-function listVersionedPythonRuntimeFiles(pythonDir) {
-    if (!existsSync(pythonDir))
-        return new Set();
-    try {
-        return new Set(readdirSync(pythonDir)
-            .filter((entry) => /^python\d{2,}(?:\.dll|\.zip|\._pth)$/i.test(entry))
-            .map((entry) => entry.toLowerCase()));
-    }
-    catch {
-        return new Set();
-    }
-}
 export function hasPythonAbiDrift(shippedDir, stableDir) {
-    const shippedRuntimeFiles = listVersionedPythonRuntimeFiles(join(shippedDir, 'python'));
-    if (shippedRuntimeFiles.size === 0)
-        return false;
-    const stableRuntimeFiles = listVersionedPythonRuntimeFiles(join(stableDir, 'python'));
-    if (stableRuntimeFiles.size === 0)
-        return false;
-    for (const file of stableRuntimeFiles) {
-        if (!shippedRuntimeFiles.has(file))
-            return true;
-    }
-    for (const file of shippedRuntimeFiles) {
-        if (!stableRuntimeFiles.has(file))
-            return true;
-    }
-    return false;
+    return hasVersionedPythonRuntimeFileDrift(join(shippedDir, 'python'), join(stableDir, 'python'));
 }
 function resetStablePythonRuntime(stableDir) {
     try {

package/dist/startup/update-action.d.ts

@@ -1,9 +1,10 @@
 /**
  * Foreground update execution path.
  *
- * Runs the updater command in the startup flow, surfaces real output to the
- * terminal, and returns a structured success/failure result so startup can
- * decide whether to continue into the shell.
+ * Runs the updater command in the startup flow. Updaters such as npm can emit
+ * huge cleanup dumps on Windows when a global install tree is locked or
+ * half-deleted, so stdout/stderr are captured and summarized instead of being
+ * streamed directly into the user's terminal.
  */
 import { spawn } from 'child_process';
 export interface UpdateLaunchRequest {
@@ -14,6 +15,8 @@ export interface ForegroundUpdateResult {
     kind: 'success' | 'failed';
     exitCode: number | null;
     signal: NodeJS.Signals | null;
+    message?: string;
+    logPath?: string;
 }
 interface UpdateActionDeps {
     spawnProcess?: typeof spawn;
@@ -22,6 +25,7 @@ interface UpdateActionDeps {
         args: string[];
     };
     resolveEnv?: () => NodeJS.ProcessEnv;
+    resolveLogPath?: () => string;
 }
 export declare function runForegroundUpdate(request: UpdateLaunchRequest, deps?: UpdateActionDeps): Promise<ForegroundUpdateResult>;
 export {};

package/dist/startup/update-action.js

@@ -1,25 +1,47 @@
 /**
  * Foreground update execution path.
  *
- * Runs the updater command in the startup flow, surfaces real output to the
- * terminal, and returns a structured success/failure result so startup can
- * decide whether to continue into the shell.
+ * Runs the updater command in the startup flow. Updaters such as npm can emit
+ * huge cleanup dumps on Windows when a global install tree is locked or
+ * half-deleted, so stdout/stderr are captured and summarized instead of being
+ * streamed directly into the user's terminal.
  */
 import { spawn } from 'child_process';
+import { appendFileSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
 import { getShellConfig, getShellEnv } from '../app/tools/bash-runtime.js';
+import { getDebugLogPath } from '../config.js';
+const MAX_CAPTURED_OUTPUT_BYTES = 1024 * 1024;
 export async function runForegroundUpdate(request, deps = {}) {
     const resolveShell = deps.resolveShell ?? getShellConfig;
     const resolveEnv = deps.resolveEnv ?? getShellEnv;
     const spawnProcess = deps.spawnProcess ?? spawn;
+    const resolveLogPath = deps.resolveLogPath ?? getDebugLogPath;
     const shellConfig = resolveShell();
     return await new Promise((resolve, reject) => {
+        const output = [];
+        let outputBytes = 0;
+        let outputTruncated = false;
         const child = spawnProcess(shellConfig.shell, [...shellConfig.args, request.command], {
             cwd: request.cwd ?? process.cwd(),
             env: resolveEnv(),
-            stdio: 'inherit'
+            stdio: ['ignore', 'pipe', 'pipe']
         });
+        const capture = (chunk) => {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+            const remaining = MAX_CAPTURED_OUTPUT_BYTES - outputBytes;
+            if (remaining > 0) {
+                output.push(buffer.subarray(0, remaining));
+                outputBytes += Math.min(buffer.length, remaining);
+            }
+            if (buffer.length > remaining) {
+                outputTruncated = true;
+            }
+        };
+        child.stdout?.on('data', capture);
+        child.stderr?.on('data', capture);
         child.once('error', reject);
-        child.once('exit', (exitCode, signal) => {
+        child.once('close', (exitCode, signal) => {
             if (exitCode === 0) {
                 resolve({
                     kind: 'success',
@@ -28,12 +50,62 @@ export async function runForegroundUpdate(request, deps = {}) {
                 });
                 return;
             }
+            const capturedOutput = Buffer.concat(output).toString('utf-8');
+            const logPath = writeUpdateFailureLog({
+                command: request.command,
+                exitCode,
+                signal,
+                output: capturedOutput,
+                truncated: outputTruncated,
+                resolveLogPath
+            });
             resolve({
                 kind: 'failed',
                 exitCode,
-                signal
+                signal,
+                message: summarizeUpdateFailure(capturedOutput),
+                logPath
             });
         });
     });
 }
+function summarizeUpdateFailure(output) {
+    if (/EEXIST[\s\S]*shortcut\.cmd/i.test(output) ||
+        /File exists:[\s\S]*shortcut\.cmd/i.test(output)) {
+        return [
+            'ShortcutXL could not update because an existing global `shortcut` command blocked npm from replacing it.',
+            'Close any running ShortcutXL terminals, then run `npm uninstall -g shortcutxl` followed by `npm install -g shortcutxl@latest`.'
+        ].join(' ');
+    }
+    if (/EPERM|ENOTEMPTY|ENOENT/i.test(output) &&
+        /AppData[\\/]+Roaming[\\/]+npm[\\/]+node_modules[\\/]+shortcutxl/i.test(output)) {
+        return [
+            'ShortcutXL could not update because npm could not clean up the previous global install.',
+            'Close ShortcutXL terminals and retry `npm install -g shortcutxl@latest`.'
+        ].join(' ');
+    }
+    return 'ShortcutXL could not update automatically. Retry with `npm install -g shortcutxl@latest`.';
+}
+function writeUpdateFailureLog({ command, exitCode, signal, output, truncated, resolveLogPath }) {
+    try {
+        const logPath = resolveLogPath();
+        mkdirSync(dirname(logPath), { recursive: true });
+        appendFileSync(logPath, [
+            '',
+            '--- ShortcutXL update failure ---',
+            `time=${new Date().toISOString()}`,
+            `command=${command}`,
+            `exitCode=${String(exitCode)}`,
+            `signal=${String(signal)}`,
+            truncated ? `outputTruncatedAfterBytes=${MAX_CAPTURED_OUTPUT_BYTES}` : undefined,
+            output
+        ]
+            .filter((line) => line !== undefined)
+            .join('\n'), 'utf-8');
+        return logPath;
+    }
+    catch {
+        return undefined;
+    }
+}
 //# sourceMappingURL=update-action.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shortcutxl",
-  "version": "0.3.57",
+  "version": "0.3.58",
   "license": "MIT",
   "type": "module",
   "types": "./dist/index.d.ts",