@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/utils/version-gate.d.ts

@@ -29,6 +29,9 @@
  */
 import { buildSpawnPlan, quoteForWindowsShell } from "./windows-spawn.js";
 import { type UpdateLockHandle } from "./update-lock.js";
+export type VersionGatePhase = "preflight" | "lock_acquired" | "installer_running" | "verifying" | "rollback" | "complete" | "failed" | "unknown";
+/** The last closed version-gate phase observed in this process. */
+export declare function getVersionGatePhase(): VersionGatePhase;
 /** Which package manager owns the running global install. */
 export type InstallManager = "npm" | "pnpm" | "bun";
 export interface VersionCheckResponse {
@@ -52,8 +55,8 @@ export declare function npmPrefixFromPackageDir(pkgDir: string): string | null;
  * on PATH:
  *
  *   $PNPM_HOME/hq                                        <- shim on PATH
- *   $PNPM_HOME/global/5/node_modules/@indigoai-us/hq-cli <- symlink
- *   $PNPM_HOME/global/5/.pnpm/@indigoai-us+hq-cli@5.61.0/node_modules/…
+ *   pnpm through v10: $PNPM_HOME/global/5/node_modules/@indigoai-us/hq-cli
+ *   pnpm v11+:       $PNPM_HOME/global/v11/<hash>/node_modules/@indigoai-us/hq-cli
  *
  * Both the symlinked and the resolved (`.pnpm`) form are recognised, because
  * whether `import.meta.url` reports the link or its target depends on how node
@@ -67,7 +70,7 @@ export declare function npmPrefixFromPackageDir(pkgDir: string): string | null;
  * i.e. the gate would re-fire and re-install globally on every subsequent run.
  * Those layouts fall through to the ordinary npm-prefix/manual handling.
  */
-export declare function isPnpmManagedPackageDir(pkgDir: string): boolean;
+export declare function isPnpmManagedPackageDir(pkgDir: string, acceptVersionPrefixedGlobalDir?: boolean): boolean;
 /** Whether the running package lives inside Bun's global install tree. */
 export declare function isBunManagedPackageDir(pkgDir: string): boolean;
 /**
@@ -151,9 +154,9 @@ export declare function resolveRunningManager(): InstallManager;
 /** Convenience view of {@link resolveRunningInstall} for callers needing one field. */
 export declare function resolveRunningPrefix(): string | null;
 /**
- * Whether the current process can write the npm global `prefix` — i.e. whether
- * an `npm install -g --prefix <prefix>` could actually replace the installed
- * CLI, or would fail with EACCES.
+ * Whether the current process can write the npm global install targets — i.e.
+ * whether an `npm install -g --prefix <prefix>` could actually replace the
+ * installed CLI, or would fail with EACCES.
  *
  * The path npm rewrites is the prefix's `bin` dir (`<prefix>/bin/hq` on unix
  * globals — the `rename /usr/bin/hq` EACCES the agent boxes hit), so that is
@@ -167,13 +170,27 @@ export declare function resolveRunningPrefix(): string | null;
  */
 export declare function isPrefixWritable(prefix: string, access?: (target: string, mode: number) => void): boolean;
 /**
- * One-line operator explanation for a failed global update whose prefix the
- * running user cannot write. This is the agent-box case: the CLI is a
- * root-owned `/usr` global install and the runtime is unprivileged, so the
- * update genuinely cannot converge from here and re-trying it silently would
- * loop. Says so plainly and points at the paths that CAN update it.
+ * Check the directories an npm global update must mutate before spawning npm.
+ * Npm replaces the package under node_modules and writes executable links
+ * under prefix/bin. The package's parent must be writable because npm renames
+ * the old package there.
+ *
+ * When one of those directories has not been created yet, check its nearest
+ * existing ancestor: npm can create a child only if that ancestor is writable.
  */
-export declare function nonWritablePrefixNote(prefix: string): string;
+export declare function canWriteNpmInstall(prefix: string, packageRoot: string, access?: (target: string, mode: number) => void): boolean;
+/** Claim the one local warning/report for this installed version and prefix. */
+export declare function claimNonWritableNpmPrefixNotice(install: Pick<RunningInstall, "manager" | "prefix" | "packageRoot">, fromVersion: string, homeDir?: string, kind?: "user" | "report"): boolean;
+/** Emit one path-free warning event for a handled non-writable npm prefix. */
+export declare function captureNonWritableNpmPrefixNotice(input: {
+    fromVersion: string;
+    targetVersion: string;
+    install: Pick<RunningInstall, "manager" | "prefix" | "packageRoot">;
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+}): Promise<void>;
+/** One-line repair guidance for a global npm install the current user cannot write. */
+export declare function nonWritablePrefixNote(prefix: string, platform?: NodeJS.Platform): string;
 /**
  * Derive `PNPM_HOME` from a pnpm-managed install's own path. pnpm resolves its
  * global bin directory from `PNPM_HOME` (or an explicit `global-bin-dir`), and
@@ -256,6 +273,9 @@ export type UpdateResult = {
     ok: boolean;
     detail?: string;
     code?: string;
+    /** Sanitized installer error code for diagnostics; never drives retry or exit behavior. */
+    diagnosticCode?: string;
+    failureKind?: "package_manager_exit";
 };
 type UpdateRunner = (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => UpdateResult;
 export { buildSpawnPlan, quoteForWindowsShell };
@@ -283,6 +303,22 @@ export { buildSpawnPlan, quoteForWindowsShell };
  * protection silently disappearing.
  */
 export declare function inOwnProcessGroup<T extends object>(options: T): T;
+declare function updateTimeoutMs(env?: NodeJS.ProcessEnv): number;
+/** The supervisor script the next install runs under. */
+export declare function updateSupervisorPath(): string;
+export interface DetachedUpdateSupervisor {
+    path: string;
+    dispose(): void;
+}
+/**
+ * Copies the supervisor to a temp dir and runs installs through the copy until
+ * disposed. The in-place self-update moves the whole hq-cli package aside
+ * before it starts the installer, and the supervisor ships inside that package
+ * (5.290.0-5.292.0 failed every npm global self-update with MODULE_NOT_FOUND).
+ * The script needs only Node builtins, so the copy runs on its own. Returns
+ * null when the copy cannot be made; the caller then keeps the bundled path.
+ */
+export declare function detachUpdateSupervisor(): DetachedUpdateSupervisor | null;
 /**
  * Where an install's output goes — the other half of surviving a killed parent.
  *
@@ -307,9 +343,25 @@ export interface InstallOutput {
     stdio: ("ignore" | "inherit" | number)[];
     /** Captured stderr tail, or "" when output was inherited by a terminal. */
     stderrTail: () => string;
+    /** Allowlisted npm error code from captured stderr, when output was captured. */
+    diagnosticCode: () => string | undefined;
+    /** Supervisor marker used to inspect npm errors while forwarding terminal stderr. */
+    diagnosticMarker?: string;
+    /** Private side-channel from the supervisor, kept out of installer output. */
+    timeoutMarker: string;
+    /** Private spawn-error side-channel that preserves the prior result contract. */
+    errorMarker: string;
+    /** Whether the asynchronous installer supervisor reported a deadline expiry. */
+    timedOut: () => boolean;
+    /** Original package-manager launch error, if the supervisor could start. */
+    spawnError: () => {
+        code?: string;
+        detail?: string;
+    } | undefined;
     dispose: () => void;
 }
 export declare function openInstallOutput(verbose: boolean, isTty?: boolean): InstallOutput;
+export declare function runSupervisedUpdateCommand(cmd: string, args: string[], output: InstallOutput, env?: NodeJS.ProcessEnv): UpdateResult;
 export declare function runUpdateCommand(cmd: string, args: string[], env?: NodeJS.ProcessEnv): UpdateResult;
 declare function performUpdateCommand(cmd: string, args: string[], runner?: UpdateRunner, env?: NodeJS.ProcessEnv): UpdateResult;
 declare function performUpdate(command: string, runner?: UpdateRunner): UpdateResult;
@@ -334,6 +386,19 @@ declare function nudgeUpdateRecommended(decision: VersionCheckResponse, install?
  * see what the USER's next invocation resolves.
  */
 export declare function resolveHqOnPath(): string | null;
+/**
+ * Pull the CLI version out of `hq --version` / `hq version` output.
+ *
+ * Compare CLI to CLI. Never take the first version-shaped token: 5.119.13–
+ * 5.121.0 printed `HQ <core>` above `CLI <cli>`, and scraping the HQ line
+ * made a successful install look like a PATH shadow.
+ *
+ * Accepts:
+ *   - bare semver (historical `--version`, and `--version` again after this fix)
+ *   - labelled `CLI x.y.z` (those 5.119.13–5.121.0 builds)
+ *   - JSON `{ "cli": "x.y.z", ... }` from `--json`
+ */
+export declare function parseReportedCliVersion(stdout: string): string | null;
 /** `<bin> --version` output (trimmed), or null on any failure/timeout. */
 export declare function probeCliVersion(bin: string): string | null;
 /**
@@ -345,9 +410,10 @@ export declare function probeCliVersion(bin: string): string | null;
  * pnpm-global shim at `~/Library/pnpm/bin/hq` shadowing the npm bin dir),
  * every updater on the box probes the ghost's version, sees it stale, installs
  * into the npm prefix, reports success, and repeats forever — the production
- * updater-war this fix exists for. Detect the divergence here, warn ONCE with
- * the exact shadowing path, and never retry: no number of retries into the
- * same prefix can change what PATH resolves.
+ * updater-war this fix exists for. Detect a stale PATH result here, identify a
+ * distinct package managed by a supported global manager before calling it a
+ * shadow, and never retry: no number of retries into the same prefix can change
+ * what PATH resolves.
  *
  * Advisory only — resolution failure warns once and continues; nothing in
  * here may crash or block the CLI.
@@ -355,12 +421,17 @@ export declare function probeCliVersion(bin: string): string | null;
 export declare function checkUpdateConvergence(targetVersion: string, deps?: {
     resolveBin?: () => string | null;
     probeVersion?: (bin: string) => string | null;
+    currentInstall?: () => RunningInstall;
+    packageRootForBin?: (bin: string) => string | null;
 }): boolean;
 /** Injectable surface for {@link enforceUpdateRequired} (unit tests). */
 interface EnforceUpdateDeps {
     performUpdateString?: (command: string) => UpdateResult;
     resolveInstall?: () => RunningInstall;
+    canWriteNpmInstall?: (install: RunningInstall) => boolean;
+    homeDir?: string;
     runner?: UpdateRunner;
+    platform?: NodeJS.Platform;
     cleanStale?: (prefix: string) => string[];
     acquireLock?: () => UpdateLockHandle | null;
     /**
@@ -369,6 +440,7 @@ interface EnforceUpdateDeps {
      * returns nothing still exercises the success path.
      */
     checkConvergence?: (targetVersion: string) => boolean | void;
+    installNpmPackageStaged?: typeof import("./staged-npm-install.js").installNpmPackageStaged;
 }
 /**
  * Hard enforcement when the server says we're below `minVersion`. Print a
@@ -385,8 +457,11 @@ interface EnforceUpdateDeps {
  * Exit codes:
  *   0 — update succeeded; user must rerun their command
  *   75 — update failed (EX_TEMPFAIL; common for sudo/EACCES on system npm)
+ *
+ * A timed-out updater is the exception: it has been forcibly reaped, so the
+ * gate returns and lets the user's command run on the current version.
  */
-declare function enforceUpdateRequired(decision: VersionCheckResponse, deps?: EnforceUpdateDeps): void;
+declare function enforceUpdateRequired(decision: VersionCheckResponse, deps?: EnforceUpdateDeps): void | Promise<void>;
 /**
  * Public entry point. Call before commander parses argv. Blocks the CLI on
  * network IO for up to FETCH_TIMEOUT_MS — acceptable because the alternative
@@ -404,7 +479,11 @@ declare function enforceUpdateRequired(decision: VersionCheckResponse, deps?: En
  * must exit rather than running the command a second time.
  */
 export type VersionGateOutcome = "continue" | "reexec";
-export declare function enforceVersionGate(onUpdateRecommended?: (decision: VersionCheckResponse, install: RunningInstall) => Promise<boolean>): Promise<VersionGateOutcome>;
+/** Optional caller-owned bound for the network-only version decision. */
+export interface VersionGateOptions {
+    timeoutMs?: number;
+}
+export declare function enforceVersionGate(onUpdateRecommended?: (decision: VersionCheckResponse, install: RunningInstall) => Promise<boolean>, options?: VersionGateOptions): Promise<VersionGateOutcome>;
 /**
  * Cheap argv pre-check: skip the gate for `--version` / `-V` so users
  * inspecting a broken install can still see what they have without being
@@ -413,7 +492,9 @@ export declare function enforceVersionGate(onUpdateRecommended?: (decision: Vers
 export declare function shouldSkipGate(argv: readonly string[]): boolean;
 export declare const __test__: {
     CLIENT_ID: string;
+    getVersionGatePhase: typeof getVersionGatePhase;
     CONVERGENCE_TIMEOUT_MS: number;
+    DEFAULT_UPDATE_TIMEOUT_MS: number;
     ENDPOINT_PATH: string;
     FETCH_TIMEOUT_MS: number;
     checkUpdateConvergence: typeof checkUpdateConvergence;
@@ -423,6 +504,8 @@ export declare const __test__: {
     buildPnpmInstallArgv: typeof buildPnpmInstallArgv;
     buildPrefixedInstallArgv: typeof buildPrefixedInstallArgv;
     buildSpawnPlan: typeof buildSpawnPlan;
+    canWriteNpmInstall: typeof canWriteNpmInstall;
+    claimNonWritableNpmPrefixNotice: typeof claimNonWritableNpmPrefixNotice;
     cleanStalePartialInstall: typeof cleanStalePartialInstall;
     derivePnpmHome: typeof derivePnpmHome;
     enforceUpdateRequired: typeof enforceUpdateRequired;
@@ -444,5 +527,6 @@ export declare const __test__: {
     resolveRunningInstall: typeof resolveRunningInstall;
     resolveRunningManager: typeof resolveRunningManager;
     resolveRunningPrefix: typeof resolveRunningPrefix;
+    updateTimeoutMs: typeof updateTimeoutMs;
 };
 //# sourceMappingURL=version-gate.d.ts.map