@indigoai-us/hq-cli 5.312.2-beta.0 → 5.314.0

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

@@ -29,9 +29,6 @@
  */
 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 {
@@ -55,8 +52,8 @@ export declare function npmPrefixFromPackageDir(pkgDir: string): string | null;
  * on PATH:
  *
  *   $PNPM_HOME/hq                                        <- shim on PATH
- *   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
+ *   $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/…
  *
  * 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
@@ -70,7 +67,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, acceptVersionPrefixedGlobalDir?: boolean): boolean;
+export declare function isPnpmManagedPackageDir(pkgDir: string): boolean;
 /** Whether the running package lives inside Bun's global install tree. */
 export declare function isBunManagedPackageDir(pkgDir: string): boolean;
 /**
@@ -154,9 +151,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 install targets — 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 `prefix` — 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
@@ -170,27 +167,13 @@ export declare function resolveRunningPrefix(): string | null;
  */
 export declare function isPrefixWritable(prefix: string, access?: (target: string, mode: number) => void): boolean;
 /**
- * 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.
+ * 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.
  */
-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;
+export declare function nonWritablePrefixNote(prefix: string): 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
@@ -273,9 +256,6 @@ 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 };
@@ -303,22 +283,6 @@ 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.
  *
@@ -343,25 +307,9 @@ 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;
@@ -386,19 +334,6 @@ 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;
 /**
@@ -410,10 +345,9 @@ 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 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.
+ * 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.
  *
  * Advisory only — resolution failure warns once and continues; nothing in
  * here may crash or block the CLI.
@@ -421,17 +355,12 @@ 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;
     /**
@@ -440,7 +369,6 @@ 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
@@ -457,11 +385,8 @@ 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 | Promise<void>;
+declare function enforceUpdateRequired(decision: VersionCheckResponse, deps?: EnforceUpdateDeps): 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
@@ -479,11 +404,7 @@ declare function enforceUpdateRequired(decision: VersionCheckResponse, deps?: En
  * must exit rather than running the command a second time.
  */
 export type VersionGateOutcome = "continue" | "reexec";
-/** 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>;
+export declare function enforceVersionGate(onUpdateRecommended?: (decision: VersionCheckResponse, install: RunningInstall) => Promise<boolean>): 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
@@ -492,9 +413,7 @@ 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;
@@ -504,8 +423,6 @@ 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;
@@ -527,6 +444,5 @@ export declare const __test__: {
     resolveRunningInstall: typeof resolveRunningInstall;
     resolveRunningManager: typeof resolveRunningManager;
     resolveRunningPrefix: typeof resolveRunningPrefix;
-    updateTimeoutMs: typeof updateTimeoutMs;
 };
 //# sourceMappingURL=version-gate.d.ts.map