impel-cli 0.14.3 → 0.15.1

package/src/installRecovery/loop.js

@@ -0,0 +1,258 @@
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { promptText } from "../prompt.js";
+import {
+  deterministicInstallRecoveryAction,
+  executeInstallRecoveryAction,
+  installRecoveryActionMutates,
+  validateInstallRecoveryAction,
+} from "./actions.js";
+import {
+  clearInstallRecoveryCheckpoint,
+  loadInstallRecoveryCheckpoint,
+  saveInstallRecoveryCheckpoint,
+} from "./checkpoint.js";
+import { createInstallRecoveryClient } from "./client.js";
+import {
+  installRecoveryFingerprint,
+  installRecoveryStateFingerprint,
+  sanitizeInstallFailureEnvelope,
+} from "./redact.js";
+
+const CLI_VERSION = JSON.parse(
+  fs.readFileSync(
+    fileURLToPath(new URL("../../package.json", import.meta.url)),
+    "utf8"
+  )
+).version;
+const TERMINAL_STATUSES = new Set(["fixed", "blocked", "aborted"]);
+const POLL_INTERVAL_MS = 1_000;
+
+function recoveryDisabled(environment) {
+  return ["1", "true", "yes"].includes(
+    String(environment.IMPEL_DISABLE_INSTALL_RECOVERY || "").toLowerCase()
+  );
+}
+
+function yes(answer) {
+  return /^(?:y|yes)$/iu.test(String(answer || "").trim());
+}
+
+async function confirmMutation(action, io) {
+  if (!installRecoveryActionMutates(action.id)) return true;
+  if (!io.isTTY) return false;
+  const answer = await io.promptText(
+    `Install recovery proposes ${action.id}: ${action.reason}\nRun this allowlisted local action? [y/N] `
+  );
+  return yes(answer);
+}
+
+function checkpointFrom(state, fingerprint) {
+  return {
+    protocolVersion: 1,
+    sessionId: state.sessionId,
+    recoveryToken: state.recoveryToken,
+    fingerprint,
+    status: state.status,
+    turn: state.turn,
+    expiresAt: state.expiresAt,
+    updatedAt: Date.now(),
+  };
+}
+
+function terminalOutcome(status) {
+  if (status === "fixed") return "fixed";
+  if (status === "aborted") return "aborted";
+  return "blocked";
+}
+
+async function uploadConsent(io, explicit, failure) {
+  io.log(
+    "Install recovery can send a sanitized failure envelope to Impel. Credentials, home paths, email addresses, ANSI controls, and raw tokens are removed."
+  );
+  io.log(
+    "The hosted agent selects typed action IDs; the Impel CLI runs the corresponding reviewed commands on this machine after local policy and confirmation checks."
+  );
+  io.log("Sanitized payload preview:");
+  io.log(JSON.stringify(failure, null, 2));
+  if (explicit) return true;
+  if (!io.isTTY) return false;
+  return yes(await io.promptText("Send the sanitized failure and start assisted recovery? [y/N] "));
+}
+
+export async function runInstallRecovery(options, overrides = {}) {
+  const environment = options.environment || process.env;
+  const io = {
+    promptText,
+    isTTY: process.stdin.isTTY,
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    loadCheckpoint: loadInstallRecoveryCheckpoint,
+    saveCheckpoint: saveInstallRecoveryCheckpoint,
+    clearCheckpoint: clearInstallRecoveryCheckpoint,
+    client:
+      options.client ||
+      createInstallRecoveryClient({
+        appUrl: options.config.appUrl,
+        fetchImpl: options.fetchImpl || fetch,
+      }),
+    executeAction: executeInstallRecoveryAction,
+    now: () => Date.now(),
+    log: console.log,
+    warn: console.warn,
+    ...overrides,
+  };
+
+  if (options.noRecovery || recoveryDisabled(environment)) {
+    return { status: "disabled", fixed: false, uploaded: false };
+  }
+
+  const failure = sanitizeInstallFailureEnvelope(options.failure);
+  const fingerprint = installRecoveryFingerprint(failure);
+  const encounteredErrors = [failure.message];
+  const actionContext = {
+    ...(options.actionContext || {}),
+    platform: failure.platform,
+    environment,
+    isTTY: io.isTTY,
+  };
+
+  // Always attempt one deterministic, allowlisted local diagnostic first. A
+  // mutation still needs the same explicit confirmation as a hosted proposal.
+  const deterministicAction = deterministicInstallRecoveryAction(failure);
+  const deterministicConfirmed = await confirmMutation(deterministicAction, io);
+  const deterministicResult = await io.executeAction(deterministicAction, {
+    ...actionContext,
+    confirmed: deterministicConfirmed,
+  });
+  io.log(`Install recovery local check: ${deterministicResult.summary}`);
+  if (deterministicResult.outcome === "failed") {
+    encounteredErrors.push(deterministicResult.summary);
+  }
+
+  const consented = await uploadConsent(io, options.explicit === true, failure);
+  if (!consented) {
+    io.log("Install recovery stayed local; no diagnostic data was uploaded.");
+    return {
+      status: "local_only",
+      fixed: false,
+      uploaded: false,
+      localResult: deterministicResult,
+    };
+  }
+
+  let state;
+  const existing = io.loadCheckpoint();
+  if (existing?.fingerprint === fingerprint) {
+    state = existing;
+    io.log(`Resuming install recovery session ${existing.sessionId}.`);
+  } else {
+    state = await io.client.create(options.config.pat, {
+      protocolVersion: 1,
+      orgId: options.config.tenantId,
+      cliVersion: CLI_VERSION,
+      consent: true,
+      fingerprint,
+      stateFingerprint: installRecoveryStateFingerprint({
+        failure,
+        deterministicResult,
+      }),
+      failure: {
+        ...failure,
+        diagnostics: {
+          ...(failure.diagnostics || {}),
+          localCheck: deterministicResult.summary,
+          localCheckOutcome: deterministicResult.outcome,
+        },
+      },
+    });
+    io.saveCheckpoint(checkpointFrom(state, fingerprint));
+  }
+
+  const deadline = Math.min(
+    state.expiresAt || io.now() + 15 * 60 * 1_000,
+    io.now() + 15 * 60 * 1_000
+  );
+  let terminal = false;
+  try {
+    while (io.now() < deadline) {
+      if (!TERMINAL_STATUSES.has(state.status)) {
+        state = await io.client.read(state.sessionId, state.recoveryToken);
+        io.saveCheckpoint(checkpointFrom(state, fingerprint));
+      }
+
+      if (state.status === "awaiting_action") {
+        const action = validateInstallRecoveryAction(state.proposal?.action);
+        if (!action || !state.actionNonce) {
+          encounteredErrors.push("Hosted recovery returned an invalid typed action.");
+          state.status = "blocked";
+          state.terminalSummary = "Hosted recovery returned an invalid typed action.";
+          continue;
+        }
+        io.log(`Install recovery: ${state.proposal.userMessage || state.proposal.summary}`);
+        const confirmed = await confirmMutation(action, io);
+        const result = await io.executeAction(action, {
+          ...actionContext,
+          confirmed,
+        });
+        if (result.outcome === "failed") encounteredErrors.push(result.summary);
+        state = await io.client.submitResult(
+          state.sessionId,
+          state.recoveryToken,
+          {
+            actionNonce: state.actionNonce,
+            actionId: action.id,
+            outcome: result.outcome,
+            stateFingerprint: installRecoveryStateFingerprint({
+              failure,
+              actionId: action.id,
+              result,
+            }),
+            summary: result.summary,
+            exitCode: result.exitCode,
+            ...(result.stdout ? { stdout: result.stdout } : {}),
+            ...(result.stderr ? { stderr: result.stderr } : {}),
+          }
+        );
+        io.saveCheckpoint(checkpointFrom(state, fingerprint));
+        continue;
+      }
+
+      if (TERMINAL_STATUSES.has(state.status)) {
+        terminal = true;
+        const summary =
+          state.terminalSummary || state.proposal?.summary || "Install recovery finished.";
+        await io.client.complete(state.sessionId, state.recoveryToken, {
+          outcome: terminalOutcome(state.status),
+          summary,
+          encounteredErrors: [...new Set(encounteredErrors)].slice(0, 20),
+        });
+        io.log(`Install recovery ${state.status}: ${summary}`);
+        return {
+          status: state.status,
+          fixed: state.status === "fixed",
+          uploaded: true,
+          summary,
+        };
+      }
+
+      await io.sleep(POLL_INTERVAL_MS);
+    }
+    const summary = terminal
+      ? state.terminalSummary
+      : "Install recovery reached its 15-minute local safety limit.";
+    io.warn(summary);
+    return { status: "blocked", fixed: false, uploaded: true, summary };
+  } catch (error) {
+    io.warn(`Install recovery paused: ${error?.message || error}`);
+    io.warn("Re-run `impel setup --repair` to resume the short-lived session.");
+    return {
+      status: "paused",
+      fixed: false,
+      uploaded: true,
+      summary: String(error?.message || error),
+    };
+  } finally {
+    if (terminal) io.clearCheckpoint();
+  }
+}

package/src/installRecovery/redact.js

@@ -0,0 +1,83 @@
+import crypto from "node:crypto";
+import os from "node:os";
+
+import { redactSecretText } from "../config.js";
+
+const JWT_RE = /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/gu;
+const BEARER_RE = /\bBearer\s+[A-Za-z0-9._~+\/-]{8,}/giu;
+const SECRET_ASSIGNMENT_RE = /\b(api[_-]?key|authorization|password|secret|token)\s*[:=]\s*([^\s,;]+)/giu;
+const EMAIL_RE = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/giu;
+const WINDOWS_USER_PATH_RE = /\b[A-Za-z]:\\Users\\[^\\\s]+/giu;
+
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+
+export function redactInstallRecoveryText(value, { homeDir = os.homedir() } = {}) {
+  let text = redactSecretText(value);
+  if (homeDir) {
+    text = text.replace(new RegExp(escapeRegex(homeDir), "giu"), "~");
+  }
+  return text
+    .replace(WINDOWS_USER_PATH_RE, "%USERPROFILE%")
+    .replace(JWT_RE, "[REDACTED TOKEN]")
+    .replace(BEARER_RE, "Bearer [REDACTED]")
+    .replace(SECRET_ASSIGNMENT_RE, (_match, name) => `${name}=[REDACTED]`)
+    .replace(EMAIL_RE, "[REDACTED EMAIL]")
+    .slice(0, 12_000);
+}
+
+function boundedText(value, max, options) {
+  return redactInstallRecoveryText(value, options).trim().slice(0, max);
+}
+
+export function sanitizeInstallFailureEnvelope(input, options = {}) {
+  const diagnostics = Object.fromEntries(
+    Object.entries(input?.diagnostics || {})
+      .slice(0, 24)
+      .map(([key, value]) => [
+        boundedText(key, 64, options) || "diagnostic",
+        boundedText(value, 2_000, options),
+      ])
+  );
+  return {
+    platform: ["win32", "darwin", "linux"].includes(input?.platform)
+      ? input.platform
+      : "unknown",
+    architecture: boundedText(input?.architecture || process.arch, 32, options),
+    step: boundedText(input?.step || "unknown", 128, options) || "unknown",
+    ...(input?.command ? { command: boundedText(input.command, 256, options) } : {}),
+    exitCode: Number.isInteger(input?.exitCode) ? input.exitCode : null,
+    signal: input?.signal ? boundedText(input.signal, 32, options) : null,
+    errorCode: input?.errorCode ? boundedText(input.errorCode, 96, options) : null,
+    message: boundedText(input?.message || "Installation failed.", 4_000, options)
+      || "Installation failed.",
+    ...(input?.stdout ? { stdout: boundedText(input.stdout, 12_000, options) } : {}),
+    ...(input?.stderr ? { stderr: boundedText(input.stderr, 12_000, options) } : {}),
+    ...(Object.keys(diagnostics).length ? { diagnostics } : {}),
+  };
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([, child]) => child !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, child]) => [key, canonical(child)])
+    );
+  }
+  return value;
+}
+
+export function installRecoveryFingerprint(value) {
+  return crypto
+    .createHash("sha256")
+    .update(JSON.stringify(canonical(value)))
+    .digest("hex");
+}
+
+export function installRecoveryStateFingerprint(value) {
+  return installRecoveryFingerprint(value);
+}

package/src/nativeProcess.js

@@ -55,6 +55,7 @@ function overrideName(tool, environmentPrefix = "IMPEL") {
   if (tool === "claude") return `${environmentPrefix}_CLAUDE_BIN`;
   if (tool === "codex") return `${environmentPrefix}_CODEX_BIN`;
   if (tool === "npm") return `${environmentPrefix}_NPM_BIN`;
+  if (tool === "powershell") return `${environmentPrefix}_POWERSHELL_BIN`;
   return null;
 }
 
@@ -86,6 +87,7 @@ function commonCandidates(tool, environment, platform) {
     const localAppData = environmentValue(environment, "LOCALAPPDATA");
     const nvmSymlink = environmentValue(environment, "NVM_SYMLINK");
     const programFiles = environmentValue(environment, "ProgramFiles");
+    const systemRoot = environmentValue(environment, "SystemRoot");
     const nodeDirectory = path.win32.isAbsolute(process.execPath)
       ? path.win32.dirname(process.execPath)
       : null;
@@ -110,6 +112,12 @@ function commonCandidates(tool, environment, platform) {
       if (nvmSymlink) locations.push([nvmSymlink, "npm"]);
       if (programFiles) locations.push([paths.join(programFiles, "nodejs"), "npm"]);
     }
+
+    // Windows PowerShell 5.1 is present on supported Windows releases even
+    // when a customized PATH omits its standard directory.
+    if (tool === "powershell" && systemRoot) {
+      locations.push([paths.join(systemRoot, "System32", "WindowsPowerShell", "v1.0"), "powershell"]);
+    }
   }
 
   return locations.flatMap(([directory, name]) => binaryCandidates(directory, name, environment, platform));
@@ -121,10 +129,20 @@ export function findNativeBinary(
   environment = process.env,
   platform = process.platform,
   environmentPrefix = "IMPEL",
+  accept = null,
 ) {
+  const usable = (candidate) => {
+    if (!isExecutable(candidate, platform)) return false;
+    if (!accept) return true;
+    try {
+      return accept(candidate) === true;
+    } catch {
+      return false;
+    }
+  };
   const override = overrideName(tool, environmentPrefix);
   const overriddenBinary = override ? environmentValue(environment, override) : null;
-  if (overriddenBinary) return isExecutable(overriddenBinary, platform) ? overriddenBinary : null;
+  if (overriddenBinary) return usable(overriddenBinary) ? overriddenBinary : null;
 
   for (const rawDirectory of String(environmentValue(environment, "PATH") || "").split(pathDelimiter(platform))) {
     const expandedDirectory = platform === "win32"
@@ -133,11 +151,11 @@ export function findNativeBinary(
     const directory = stripPathEntryQuotes(expandedDirectory);
     if (!directory) continue;
     for (const candidate of binaryCandidates(directory, tool, environment, platform)) {
-      if (isExecutable(candidate, platform)) return candidate;
+      if (usable(candidate)) return candidate;
     }
   }
 
-  return commonCandidates(tool, environment, platform).find((candidate) => isExecutable(candidate, platform)) || null;
+  return commonCandidates(tool, environment, platform).find(usable) || null;
 }
 
 /** Resolve an executable for launch, preserving explicit overrides and useful ENOENT errors. */

package/src/windowsSetup.js

@@ -1,29 +1,84 @@
 import { spawnSync } from "node:child_process";
 
 import { ensureImpelClaudeProfile, ensureImpelCodexProfile } from "./cliProfiles.js";
-import { findNativeBinary, nativeCommandInvocation } from "./nativeProcess.js";
+import {
+  findNativeBinary,
+  nativeCommandInvocation,
+  nativeSpawnInvocation,
+} from "./nativeProcess.js";
 import { syncSkillsSafe } from "./skills.js";
 
-export const WINDOWS_CLI_PACKAGES = {
-  claude: "@anthropic-ai/claude-code@latest",
-  codex: "@openai/codex@latest",
-};
+const POWERSHELL_ARGS = [
+  "-NoLogo",
+  "-NoProfile",
+  "-NonInteractive",
+  "-ExecutionPolicy",
+  "Bypass",
+  "-Command",
+];
 
-export function windowsCliInstallCommand(tools = Object.keys(WINDOWS_CLI_PACKAGES)) {
-  return `npm install --global ${tools.map((tool) => WINDOWS_CLI_PACKAGES[tool]).join(" ")}`;
+/**
+ * Official, checksum-verifying native installers recommended by each vendor.
+ * Keep the copyable command separate from the script passed to PowerShell so
+ * setup errors can offer an exact manual recovery without exposing cmd.exe's
+ * internal escaping.
+ */
+export const WINDOWS_CLI_INSTALLERS = Object.freeze({
+  claude: Object.freeze({
+    command: "powershell -ExecutionPolicy Bypass -NoProfile -Command \"irm https://claude.ai/install.ps1 | iex\"",
+    script: "Invoke-RestMethod -Uri 'https://claude.ai/install.ps1' | Invoke-Expression",
+  }),
+  codex: Object.freeze({
+    command: "powershell -ExecutionPolicy Bypass -NoProfile -Command \"$env:CODEX_NON_INTERACTIVE='1'; irm https://chatgpt.com/codex/install.ps1 | iex\"",
+    script: "$env:CODEX_NON_INTERACTIVE = '1'; Invoke-RestMethod -Uri 'https://chatgpt.com/codex/install.ps1' | Invoke-Expression",
+  }),
+});
+
+export function windowsCliInstallCommands(tools = Object.keys(WINDOWS_CLI_INSTALLERS)) {
+  return Object.fromEntries(tools.map((tool) => {
+    const installer = WINDOWS_CLI_INSTALLERS[tool];
+    if (!installer) throw new Error(`unsupported Windows CLI installer: ${tool}`);
+    return [tool, installer.command];
+  }));
 }
 
-function detectWindowsClis(find, environment) {
+function verifyWindowsCli(_tool, binary, environment) {
+  try {
+    const invocation = nativeSpawnInvocation(binary, ["--version"], environment, "win32");
+    const result = spawnSync(invocation.command, invocation.args, {
+      encoding: "utf8",
+      env: environment,
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 15_000,
+      windowsHide: true,
+      windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+    });
+    return result?.status === 0 && !result?.error;
+  } catch {
+    return false;
+  }
+}
+
+function detectWindowsClis(find, environment, verify) {
+  const detect = (tool) => find(
+    tool,
+    environment,
+    "win32",
+    "IMPEL",
+    (binary) => verify(tool, binary, environment),
+  );
   return {
-    claude: find("claude", environment, "win32"),
-    codex: find("codex", environment, "win32"),
+    claude: detect("claude"),
+    codex: detect("codex"),
   };
 }
 
-function installMissingClis(missing, { environment, run }) {
+function installCli(tool, { environment, run }) {
+  const installer = WINDOWS_CLI_INSTALLERS[tool];
+  if (!installer) throw new Error(`unsupported Windows CLI installer: ${tool}`);
   const invocation = nativeCommandInvocation(
-    "npm",
-    ["install", "--global", ...missing.map((tool) => WINDOWS_CLI_PACKAGES[tool])],
+    "powershell",
+    [...POWERSHELL_ARGS, installer.script],
     environment,
     "win32",
   );
@@ -57,10 +112,16 @@ function installationFailure(result, thrown = null) {
  * vendor CLIs, create the same tenant-isolated profiles used at launch time,
  * and sync the shared Impel skill bundle into each available client.
  */
-export async function prepareWindowsClis({ gatewayUrl, tenantId, skipInstall = false } = {}, dependencies = {}) {
+export async function prepareWindowsClis({
+  gatewayUrl,
+  tenantId,
+  skipInstall = false,
+  installTools = ["claude", "codex"],
+} = {}, dependencies = {}) {
   const io = {
     environment: process.env,
     find: findNativeBinary,
+    verify: verifyWindowsCli,
     run: spawnSync,
     ensureClaudeProfile: ensureImpelClaudeProfile,
     ensureCodexProfile: ensureImpelCodexProfile,
@@ -68,27 +129,52 @@ export async function prepareWindowsClis({ gatewayUrl, tenantId, skipInstall = f
     ...dependencies,
   };
 
-  const before = detectWindowsClis(io.find, io.environment);
+  const before = detectWindowsClis(io.find, io.environment, io.verify);
   const missingBefore = Object.entries(before)
     .filter(([, binary]) => !binary)
     .map(([tool]) => tool);
-  let installAttempted = false;
-  let installSucceeded = null;
-  let installFailure = null;
+  const installations = {};
+  const requestedInstallTools = new Set(installTools);
+  if (
+    requestedInstallTools.size !== installTools.length
+    || [...requestedInstallTools].some((tool) => !WINDOWS_CLI_INSTALLERS[tool])
+  ) {
+    throw new Error("installTools must contain unique supported Windows CLI names");
+  }
 
   if (missingBefore.length > 0 && !skipInstall) {
-    installAttempted = true;
-    try {
-      const result = installMissingClis(missingBefore, io);
-      installSucceeded = result?.status === 0 && !result?.error;
-      if (!installSucceeded) installFailure = installationFailure(result);
-    } catch (error) {
-      installSucceeded = false;
-      installFailure = installationFailure(null, error);
+    // Install independently: one broken vendor endpoint or local conflict must
+    // not prevent the other client from reaching a usable state.
+    for (const tool of missingBefore.filter((candidate) => requestedInstallTools.has(candidate))) {
+      try {
+        const result = installCli(tool, io);
+        const succeeded = result?.status === 0 && !result?.error;
+        installations[tool] = {
+          attempted: true,
+          succeeded,
+          failure: succeeded ? null : installationFailure(result),
+          command: WINDOWS_CLI_INSTALLERS[tool].command,
+        };
+      } catch (error) {
+        installations[tool] = {
+          attempted: true,
+          succeeded: false,
+          failure: installationFailure(null, error),
+          command: WINDOWS_CLI_INSTALLERS[tool].command,
+        };
+      }
     }
   }
 
-  const binaries = installAttempted ? detectWindowsClis(io.find, io.environment) : before;
+  const attemptedInstallations = Object.values(installations);
+  const installAttempted = attemptedInstallations.length > 0;
+  const installSucceeded = installAttempted
+    ? attemptedInstallations.every((installation) => installation.succeeded)
+    : null;
+  const installFailure = attemptedInstallations.find((installation) => installation.failure)?.failure || null;
+  const binaries = installAttempted
+    ? detectWindowsClis(io.find, io.environment, io.verify)
+    : before;
   const claudeProfile = io.ensureClaudeProfile(gatewayUrl, tenantId);
   const codexProfile = io.ensureCodexProfile(gatewayUrl, tenantId);
 
@@ -116,7 +202,8 @@ export async function prepareWindowsClis({ gatewayUrl, tenantId, skipInstall = f
     installAttempted,
     installSucceeded,
     installFailure,
-    installCommand: windowsCliInstallCommand(missingBefore),
+    installations,
+    installCommands: windowsCliInstallCommands(missingBefore),
     profiles: { claude: claudeProfile.configDir, codex: codexProfile.codexHome },
   };
 }