impel-cli 0.14.3 → 0.15.1

package/src/commands/setup.js

@@ -16,7 +16,8 @@ import {
 import { promptSecret, promptText } from "../prompt.js";
 import { fetchTenants, normalizeTenantId, tenantCredential } from "../tenants.js";
 import { cmdApps } from "./apps.js";
-import { prepareWindowsClis, windowsCliInstallCommand } from "../windowsSetup.js";
+import { prepareWindowsClis, windowsCliInstallCommands } from "../windowsSetup.js";
+import { runInstallRecovery } from "../installRecovery/loop.js";
 
 const HELP = `impel setup - guided end-to-end gateway setup
 
@@ -34,6 +35,8 @@ Usage:
   impel setup --tenant <org>        Preselect the organization
   impel setup --skip-apps           Skip the desktop-app installation step
   impel setup --skip-clis           On Windows, don't install missing vendor CLIs
+  impel setup --repair              Explicitly opt into sanitized assisted recovery on failure
+  impel setup --no-recovery         Disable local and hosted recovery for this run
 `;
 
 /**
@@ -104,6 +107,7 @@ export async function cmdSetup(argv, overrides = {}) {
     installApps: cmdApps,
     prepareWindowsClis,
     probe: probeGateway,
+    recoverInstall: runInstallRecovery,
     isTTY: process.stdin.isTTY,
     platform: process.platform,
     ...overrides,
@@ -115,6 +119,8 @@ export async function cmdSetup(argv, overrides = {}) {
     app: { type: "string" },
     "skip-apps": { type: "boolean" },
     "skip-clis": { type: "boolean" },
+    repair: { type: "boolean" },
+    "no-recovery": { type: "boolean" },
     help: { type: "boolean" },
   });
   if (flags.help) {
@@ -174,6 +180,15 @@ export async function cmdSetup(argv, overrides = {}) {
   console.log(`    ✓ stored in ~/.config/impel/config.json (mode 0600)`);
   console.log("");
 
+  const setupFailures = [];
+  const recordSetupFailure = (failure) => {
+    setupFailures.push({
+      platform: io.platform,
+      architecture: process.arch,
+      ...failure,
+    });
+  };
+
   // ── Step 2: organization ─────────────────────────────────────────────────
   // A successful tenant fetch also proves the token: the app verifies it
   // against impel-identity before answering.
@@ -249,23 +264,42 @@ export async function cmdSetup(argv, overrides = {}) {
       }
       if (result.missingAfter.length > 0 && !flags["skip-clis"]) {
         platformSetupFailed = true;
-        if (result.installSucceeded === false) {
-          const failure = result.installFailure;
-          const detail = failure?.message
-            ? `: ${redactSecretText(failure.message)}`
-            : Number.isInteger(failure?.status)
-              ? ` (exit code ${failure.status})`
-              : failure?.signal
-                ? ` (signal ${failure.signal})`
-                : "";
-          console.error(`    npm could not install the missing vendor CLIs${detail}.`);
-          console.error("    Retry this command in the same PowerShell window:");
-          console.error(`      ${result.installCommand || windowsCliInstallCommand(result.missingAfter)}`);
-        } else {
-          console.error("    npm completed, but the installed commands are not discoverable.");
-          console.error("    Close and reopen PowerShell, then re-run `impel setup`.");
-          console.error("    If they are still missing, run `npm prefix --global` and add that directory to your user PATH.");
+        const fallbackCommands = windowsCliInstallCommands(result.missingAfter);
+        for (const tool of result.missingAfter) {
+          const label = tool === "claude" ? "Claude Code" : "Codex";
+          const installation = result.installations?.[tool];
+          const failure = installation?.failure;
+          if (installation?.succeeded === false || (!installation && result.installSucceeded === false)) {
+            const detail = failure?.message
+              ? `: ${redactSecretText(failure.message)}`
+              : Number.isInteger(failure?.status)
+                ? ` (exit code ${failure.status})`
+                : failure?.signal
+                  ? ` (signal ${failure.signal})`
+                  : "";
+            console.error(`    ${label}'s native installer failed${detail}.`);
+            recordSetupFailure({
+              step: `install.vendor_cli.${tool}`,
+              command: installation?.command || result.installCommands?.[tool] || fallbackCommands[tool],
+              exitCode: failure?.status,
+              signal: failure?.signal,
+              errorCode: failure?.code,
+              message: failure?.message
+                ? `${label}'s native installer failed: ${failure.message}`
+                : `${label}'s native installer did not reach a verified state.`,
+            });
+          } else {
+            console.error(`    ${label}'s native installer completed, but Impel could not verify the command.`);
+            recordSetupFailure({
+              step: `verify.vendor_cli.${tool}`,
+              command: installation?.command || result.installCommands?.[tool] || fallbackCommands[tool],
+              message: `${label}'s installer completed but the command was not discoverable or did not pass its version check.`,
+            });
+          }
+          console.error("    Retry its official installer in the same PowerShell window:");
+          console.error(`      ${installation?.command || result.installCommands?.[tool] || fallbackCommands[tool]}`);
         }
+        console.error("    Then close and reopen PowerShell and re-run `impel setup`.");
       } else if (result.missingAfter.length > 0) {
         console.log("    Vendor CLI installation was skipped; install it before using the matching launcher.");
       } else {
@@ -275,6 +309,11 @@ export async function cmdSetup(argv, overrides = {}) {
       platformSetupFailed = true;
       console.error(`    ✗ Windows CLI setup failed (${redactSecretText(error?.message || error)})`);
       console.error("    Fix the issue, then re-run `impel setup`.");
+      recordSetupFailure({
+        step: "setup.windows_clis",
+        errorCode: error?.code,
+        message: `Windows CLI setup failed: ${error?.message || error}`,
+      });
     }
     if (flags["skip-apps"]) {
       console.log("    Windows desktop apps: skipped (--skip-apps).");
@@ -285,13 +324,22 @@ export async function cmdSetup(argv, overrides = {}) {
         if (installed === false) {
           platformSetupFailed = true;
           console.error("    ✗ Windows desktop app setup failed; fix the issue above, then re-run `impel app install all`.");
+          recordSetupFailure({
+            step: "install.vendor_app.all",
+            message: "Windows desktop app setup returned an unsuccessful result.",
+          });
         } else {
-          console.log("    ✓ Impel Claude and Impel ChatGPT profiles are ready");
+          console.log("    ✓ available Impel desktop app profiles are ready");
         }
       } catch (error) {
         platformSetupFailed = true;
         console.error(`    ✗ Windows desktop app setup failed (${redactSecretText(error?.message || error)})`);
         console.error("    Fix the issue, then re-run `impel app install all`.");
+        recordSetupFailure({
+          step: "install.vendor_app.all",
+          errorCode: error?.code,
+          message: `Windows desktop app setup failed: ${error?.message || error}`,
+        });
       }
     }
   } else if (flags["skip-apps"]) {
@@ -306,13 +354,18 @@ export async function cmdSetup(argv, overrides = {}) {
     );
     try {
       await io.installApps(["install", "all"]);
-      console.log("    ✓ Impel Claude and Impel ChatGPT installed");
+      console.log("    ✓ available Impel desktop apps installed");
     } catch (error) {
       platformSetupFailed = true;
       console.error(
         `    ✗ app installation failed (${redactSecretText(error?.message || error)})`
       );
       console.error("    Fix the issue, then re-run `impel app install`.");
+      recordSetupFailure({
+        step: "install.vendor_app.all",
+        errorCode: error?.code,
+        message: `Desktop app installation failed: ${error?.message || error}`,
+      });
     }
   }
   console.log("");
@@ -326,15 +379,113 @@ export async function cmdSetup(argv, overrides = {}) {
     verificationFailed = true;
     console.log(`4/4 Verify: ✗ gateway reachable but it rejected the token (HTTP ${probe.status}).`);
     console.log("    Mint a fresh token and re-run `impel setup`.");
-    process.exitCode = 1;
+    recordSetupFailure({
+      step: "verify.gateway",
+      exitCode: probe.status,
+      message: `The gateway rejected the configured credential with HTTP ${probe.status}.`,
+    });
   } else {
     verificationFailed = true;
     console.log(`4/4 Verify: ✗ gateway unreachable (${probe.error}).`);
     console.log("    Check your network, then run `impel status` to retry.");
-    process.exitCode = 1;
+    recordSetupFailure({
+      step: "verify.gateway",
+      message: `The gateway could not be reached: ${probe.error}.`,
+    });
+  }
+
+  if (platformSetupFailed || verificationFailed) {
+    const aggregateFailure = {
+      platform: io.platform,
+      architecture: process.arch,
+      step: setupFailures.length === 1 ? setupFailures[0].step : "setup.multiple",
+      message:
+        setupFailures.length === 1
+          ? setupFailures[0].message
+          : `${setupFailures.length} setup checks failed.`,
+      diagnostics: Object.fromEntries(
+        setupFailures.slice(0, 20).map((failure, index) => [
+          `failure${index + 1}`,
+          `${failure.step}: ${failure.message}`,
+        ])
+      ),
+    };
+    try {
+      const recovery = await io.recoverInstall(
+        {
+          failure: aggregateFailure,
+          config,
+          explicit: Boolean(flags.repair),
+          noRecovery: Boolean(flags["no-recovery"]),
+          actionContext: {
+            probeGateway: () => io.probe(gatewayUrl, pat, tenant.id),
+            installVendorClis: (tool) =>
+              io.prepareWindowsClis({
+                gatewayUrl,
+                tenantId: tenant.id,
+                skipInstall: false,
+                installTools: [tool],
+              }),
+            repairProfiles: async () => {
+              if (io.platform !== "win32") return false;
+              const result = await io.prepareWindowsClis({
+                gatewayUrl,
+                tenantId: tenant.id,
+                skipInstall: true,
+              });
+              return result.missingAfter.length === 0;
+            },
+            installVendorApp: (target) => io.installApps(["install", target]),
+            retryStep: async (step) => {
+              if (/vendor_cli|windows_clis/iu.test(step || "")) {
+                const result = await io.prepareWindowsClis({
+                  gatewayUrl,
+                  tenantId: tenant.id,
+                  skipInstall: false,
+                });
+                return result.missingAfter.length === 0;
+              }
+              if (/vendor_app/iu.test(step || "")) {
+                return (await io.installApps(["install", "all"])) !== false;
+              }
+              if (/gateway/iu.test(step || "")) {
+                const result = await io.probe(gatewayUrl, pat, tenant.id);
+                return Boolean(result.reachable && !result.rejected);
+              }
+              return false;
+            },
+          },
+        },
+        {
+          isTTY: io.isTTY,
+          promptText: io.promptText,
+          ...(overrides.recoveryOverrides || {}),
+        }
+      );
+      if (recovery.fixed) {
+        if (io.platform === "win32" && setupFailures.some((failure) => /vendor_cli|windows_clis/iu.test(failure.step))) {
+          const checked = await io.prepareWindowsClis({
+            gatewayUrl,
+            tenantId: tenant.id,
+            skipInstall: true,
+          });
+          platformSetupFailed = checked.missingAfter.length > 0;
+        } else {
+          platformSetupFailed = false;
+        }
+        if (setupFailures.some((failure) => failure.step === "verify.gateway")) {
+          const checked = await io.probe(gatewayUrl, pat, tenant.id);
+          verificationFailed = !checked.reachable || checked.rejected;
+        } else {
+          verificationFailed = false;
+        }
+      }
+    } catch (error) {
+      console.warn(`Install recovery could not start (${redactSecretText(error?.message || error)}).`);
+    }
   }
 
-  if (platformSetupFailed) process.exitCode = 1;
+  if (platformSetupFailed || verificationFailed) process.exitCode = 1;
 
   console.log("");
   if (platformSetupFailed || verificationFailed) {

package/src/commands/update.js

@@ -16,6 +16,7 @@ import { nativeCommandInvocation } from "../nativeProcess.js";
 import { windowsClaudeUserData } from "../windowsApps.js";
 import { withProgress } from "../progress.js";
 import { installedAppTenantIds } from "./apps.js";
+import { runInstallRecovery } from "../installRecovery/loop.js";
 import {
   fetchRemoteVersion,
   installedVersion,
@@ -38,6 +39,8 @@ Usage:
   impel update              Update the CLI, then cascade to apps, skills, and agents
   impel update --check      Report whether an update is available; change nothing
   impel update --skip-apps  Skip the desktop-app step of the cascade
+  impel update --repair     Explicitly opt into sanitized assisted recovery on failure
+  impel update --no-recovery  Disable local and hosted recovery for this run
 `;
 
 function reportProcessFailure(stage, result) {
@@ -166,12 +169,16 @@ export async function cmdUpdate(argv, overrides = {}) {
     appsInstalled: anyAppInstalled,
     platform: process.platform,
     progress: withProgress,
+    recoverInstall: runInstallRecovery,
+    loadConfig,
     ...overrides,
   };
   const { flags } = parseFlags(argv, {
     check: { type: "boolean" },
     "skip-apps": { type: "boolean" },
     "refresh-cache": { type: "boolean" },
+    repair: { type: "boolean" },
+    "no-recovery": { type: "boolean" },
     help: { type: "boolean" },
   });
   if (flags.help) {
@@ -211,8 +218,39 @@ export async function cmdUpdate(argv, overrides = {}) {
         console.error("  Verify `npm --version` in PowerShell, then retry `impel update`.");
         console.error("  Manual recovery: `npm install --global impel-cli@latest`.");
       }
-      process.exitCode = 1;
-      return;
+      const config = io.loadConfig();
+      let recovered = false;
+      if (config?.pat && config?.tenantId && config?.appUrl) {
+        try {
+          const recovery = await io.recoverInstall(
+            {
+              failure: {
+                platform: io.platform,
+                architecture: process.arch,
+                step: "install.impel_cli",
+                command: "npm install --global impel-cli@latest",
+                message: "The npm-verified global impel-cli update failed.",
+              },
+              config,
+              explicit: Boolean(flags.repair),
+              noRecovery: Boolean(flags["no-recovery"]),
+              actionContext: {
+                retryStep: async () =>
+                  io.selfUpdate(updateInstallSpec()) === true,
+              },
+            },
+            overrides.recoveryOverrides || {}
+          );
+          recovered = recovery.fixed;
+        } catch (error) {
+          console.warn(`impel update: assisted recovery could not start (${redactSecretText(error?.message || error)}).`);
+        }
+      }
+      if (!recovered) {
+        process.exitCode = 1;
+        return;
+      }
+      console.log("CLI: recovery verified the update path.");
     }
     console.log(`CLI: updated${remote ? ` to v${remote}` : ""}.`);
   }