@indigoai-us/hq-cli 5.304.0 → 5.306.0

package/dist/utils/version-gate.js

@@ -28,14 +28,17 @@
  * to silence both check + gate).
  */
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { buildSpawnPlan, quoteForWindowsShell } from "./windows-spawn.js";
-import { accessSync, closeSync, constants as fsConstants, copyFileSync, existsSync, mkdtempSync, openSync, readdirSync, realpathSync, readFileSync, rmSync, } from "node:fs";
+import { accessSync, closeSync, constants as fsConstants, copyFileSync, existsSync, mkdirSync, mkdtempSync, openSync, readdirSync, realpathSync, readFileSync, rmSync, } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import chalk from "chalk";
 import semver from "semver";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
+import { Sentry } from "../sentry.js";
+import { isCliTelemetryDisabled } from "./cli-telemetry.js";
 import { DEFAULT_VAULT_API_URL } from "./cognito-session.js";
 import { acquireUpdateLock, } from "./update-lock.js";
 const CLIENT_ID = "hq-cli";
@@ -385,9 +388,9 @@ export function resolveRunningPrefix() {
     return resolveRunningInstall().prefix;
 }
 /**
- * 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
@@ -416,17 +419,119 @@ export function isPrefixWritable(prefix, access = (target, mode) => accessSync(t
     return false;
 }
 /**
- * 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 function nonWritablePrefixNote(prefix) {
-    return (`The npm global prefix ${prefix} is not writable by the current user, so this update cannot ` +
-        `take effect here. On an agent box this is expected: the CLI is a root-owned global install and ` +
-        `updates land as root — via the box's hq-cli-update timer, or \`sudo npm install -g ${CLI_NAME}@latest\` — ` +
-        `not from the unprivileged runtime.`);
+export function canWriteNpmInstall(prefix, packageRoot, access = (target, mode) => accessSync(target, mode)) {
+    let nodeModulesRoot = path.join(prefix, process.platform === "win32" ? "node_modules" : "lib/node_modules");
+    let cursor = path.resolve(packageRoot);
+    while (true) {
+        if (path.basename(cursor).toLowerCase() === "node_modules") {
+            nodeModulesRoot = cursor;
+            break;
+        }
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    const mode = fsConstants.W_OK | fsConstants.X_OK;
+    // npm needs write access to the directories it replaces or links into. The
+    // prefix root itself need not be writable when those directories already
+    // exist; when one is missing, the nearest-existing-ancestor check below
+    // still verifies permission to create it.
+    const targets = [path.join(prefix, "bin"), nodeModulesRoot, path.dirname(packageRoot)];
+    return targets.every((target) => {
+        let candidate = path.resolve(target);
+        while (true) {
+            try {
+                access(candidate, mode);
+                return true;
+            }
+            catch (error) {
+                if (error?.code !== "ENOENT") {
+                    return false;
+                }
+                const parent = path.dirname(candidate);
+                if (parent === candidate)
+                    return false;
+                candidate = parent;
+            }
+        }
+    });
+}
+const nonWritablePrefixNotices = new Set();
+/** Claim the one local warning/report for this installed version and prefix. */
+export function claimNonWritableNpmPrefixNotice(install, fromVersion, homeDir = os.homedir(), kind = "user") {
+    const installIdentity = path.resolve(install.packageRoot ?? install.prefix ?? `${install.manager}:unknown-install`);
+    const identity = createHash("sha256")
+        .update(`${installIdentity}\0${fromVersion}`)
+        .digest("hex");
+    const localKey = path.join(homeDir, ".hq", "self-update", "prefix-not-writable", `${kind}-${identity}`);
+    if (nonWritablePrefixNotices.has(localKey))
+        return false;
+    try {
+        mkdirSync(path.dirname(localKey), { recursive: true, mode: 0o700 });
+        const descriptor = openSync(localKey, "wx", 0o600);
+        closeSync(descriptor);
+        nonWritablePrefixNotices.add(localKey);
+        return true;
+    }
+    catch (error) {
+        if (error?.code === "EEXIST") {
+            nonWritablePrefixNotices.add(localKey);
+            return false;
+        }
+        // Preserve the warning/report for this process if the home directory is
+        // unavailable. The marker is normally durable across CLI invocations.
+        console.error(chalk.dim("hq: could not persist the self-update permission notice rate limit."));
+        nonWritablePrefixNotices.add(localKey);
+        return true;
+    }
+}
+/** Emit one path-free warning event for a handled non-writable npm prefix. */
+export function captureNonWritableNpmPrefixNotice(input) {
+    if (isCliTelemetryDisabled(input.env ?? process.env))
+        return Promise.resolve();
+    const claimed = claimNonWritableNpmPrefixNotice(input.install, input.fromVersion, input.homeDir, "report");
+    if (!claimed)
+        return Promise.resolve();
+    Sentry.captureMessage("Self-update deferred: npm prefix is not writable", {
+        level: "warning",
+        fingerprint: ["self-update", "npm-prefix-not-writable"],
+        tags: {
+            from_version: input.fromVersion,
+            target_version: input.targetVersion,
+            install_flavor: "npm",
+            error_class: "prefix_not_writable",
+            error_reason: "permission_denied",
+        },
+    });
+    return Sentry.flush(2_000).then((flushed) => {
+        if (!flushed) {
+            console.error(chalk.dim("hq: the self-update permission notice could not be sent to Sentry yet."));
+        }
+    });
+}
+/** One-line repair guidance for a global npm install the current user cannot write. */
+export function nonWritablePrefixNote(prefix, platform = process.platform) {
+    const prefixArg = `'${prefix.replace(/'/g, "'\\''")}'`;
+    if (platform === "win32") {
+        const windowsPrefixArg = `"${prefix.replace(/"/g, '""')}"`;
+        return (`The npm global prefix ${prefix} is not writable by the current user, so hq-cli was not updated. ` +
+            `Open PowerShell as Administrator and run \`npm install -g --prefix ${windowsPrefixArg} ${CLI_NAME}@latest\`, ` +
+            `or set a user-owned prefix with \`npm config set prefix "$env:APPDATA\\npm"\` and run ` +
+            `\`npm install -g ${CLI_NAME}@latest\` from that PowerShell session.`);
+    }
+    return (`The npm global prefix ${prefix} is not writable by the current user, so hq-cli was not updated. ` +
+        `Run \`sudo npm install -g --prefix ${prefixArg} ${CLI_NAME}@latest\` to update this install, ` +
+        `or switch to a user-owned prefix with \`npm config set prefix ~/.npm-global\`, then run ` +
+        `\`npm install -g ${CLI_NAME}@latest\` after adding ~/.npm-global/bin to PATH.`);
 }
 /**
  * Derive `PNPM_HOME` from a pnpm-managed install's own path. pnpm resolves its
@@ -1236,19 +1341,29 @@ function enforceUpdateRequired(decision, deps = {}) {
         console.error(chalk.dim("  Another hq updater is already installing (update lock held); continuing on the current version."));
         return;
     }
-    let exitCode;
+    let attempt;
     try {
-        exitCode = attemptRequiredUpdate(decision, deps, install);
+        attempt = attemptRequiredUpdate(decision, deps, install);
     }
-    finally {
-        // `process.exit` skips `finally` blocks, so the exit itself lives OUTSIDE
-        // the lock scope; this `finally` releases on the normal path and on any
-        // unexpected throw from the install attempt.
+    catch (error) {
         lock.release();
+        throw error;
     }
-    if (exitCode === "continue")
+    if (attempt instanceof Promise) {
+        return attempt.then((exitCode) => {
+            lock.release();
+            if (exitCode !== "continue")
+                process.exit(exitCode);
+        }, (error) => {
+            lock.release();
+            throw error;
+        });
+    }
+    // `process.exit` skips `finally`, so release explicitly before exiting.
+    lock.release();
+    if (attempt === "continue")
         return;
-    process.exit(exitCode);
+    process.exit(attempt);
 }
 /**
  * The install attempt itself (npm/pnpm/bun routing, stale-partial cleanup,
@@ -1290,6 +1405,7 @@ function attemptRequiredUpdate(decision, deps, install) {
     // npm/bun and when PNPM_HOME is already set.
     const updateEnv = pnpmUpdateEnv(install);
     let result;
+    let noticeFlush = null;
     if (isManagedOutsideNpm) {
         console.error(chalk.dim(`  Detected a ${install.manager}-managed global install; updating with ${install.manager}`));
         console.error(chalk.dim(`  Running: ${primaryCmd} ${primaryArgs.join(" ")}`));
@@ -1360,12 +1476,22 @@ function attemptRequiredUpdate(decision, deps, install) {
     }
     if (!result.ok) {
         console.error(chalk.red(`✗ Update failed${result.detail ? `: ${result.detail}` : ""}.`));
-        // A root-owned global prefix the running user cannot write is the agent-box
-        // case: even the `sudo -n` retry above cannot help without passwordless
-        // sudo, so name the wall plainly rather than leaving `exit 75` to read as a
-        // generic failure. Only for npm-prefix installs (pnpm/Bun route elsewhere).
-        if (!isManagedOutsideNpm && prefix && !isPrefixWritable(prefix)) {
+        // If the npm prefix is still unwritable after the unprivileged and sudo
+        // attempts, explain the permission wall plainly instead of leaving exit 75
+        // as a generic failure. Only applies to npm-managed installs.
+        const npmPrefixNotWritable = !isManagedOutsideNpm &&
+            prefix &&
+            install.packageRoot &&
+            !(deps.canWriteNpmInstall ?? ((resolved) => canWriteNpmInstall(resolved.prefix, resolved.packageRoot)))(install);
+        if (npmPrefixNotWritable) {
             console.error(chalk.yellow(`  ${nonWritablePrefixNote(prefix)}`));
+            noticeFlush = captureNonWritableNpmPrefixNotice({
+                fromVersion: CLI_VERSION,
+                targetVersion: decision.latestVersion,
+                install,
+                env: process.env,
+                homeDir: deps.homeDir,
+            });
         }
         // The package manager itself is missing from this environment — the usual
         // cause is a minimal-PATH parent (launchd, cron, a bare systemd unit) that
@@ -1391,7 +1517,7 @@ function attemptRequiredUpdate(decision, deps, install) {
             console.error(chalk.dim("  Continuing on the current hq-cli version."));
             return "continue";
         }
-        return 75;
+        return noticeFlush ? noticeFlush.then(() => 75) : 75;
     }
     // Read-your-writes: a "successful" install into the npm prefix does not
     // prove the user's PATH resolves it. Verify BEFORE announcing, so a ghost
@@ -1427,7 +1553,9 @@ export async function enforceVersionGate(onUpdateRecommended, options = {}) {
             : undefined;
         // Exits the process, EXCEPT when another updater holds the shared update
         // lock — then it returns and the CLI continues on the current version.
-        enforceUpdateRequired(decision, { resolveInstall: () => install, installNpmPackageStaged });
+        const requiredUpdate = enforceUpdateRequired(decision, { resolveInstall: () => install, installNpmPackageStaged });
+        if (requiredUpdate)
+            await requiredUpdate;
         return "continue";
     }
     if (decision.updateRecommended) {
@@ -1468,6 +1596,8 @@ export const __test__ = {
     buildPnpmInstallArgv,
     buildPrefixedInstallArgv,
     buildSpawnPlan,
+    canWriteNpmInstall,
+    claimNonWritableNpmPrefixNotice,
     cleanStalePartialInstall,
     derivePnpmHome,
     enforceUpdateRequired,

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

@@ -13,6 +13,7 @@ export interface VersionReportDeps {
     hqRoot?: string;
     readHq?: (hqRoot: string) => string | null;
     fetchLatest?: () => Promise<string | null>;
+    printUpdateNudge?: (stderr: Pick<NodeJS.WriteStream, "write">) => Promise<void>;
 }
 export declare function normalizeHqCoreTag(tag: string): string | null;
 export declare function fetchLatestHqCoreRelease(fetchImpl?: typeof fetch, timeoutMs?: number): Promise<string | null>;
@@ -22,5 +23,5 @@ export declare function versionReportJson(report: VersionReport): string;
 export { isVersionRequest, wantsJson } from "../version-request.js";
 export declare function runVersionCommand(argv?: readonly string[], deps?: VersionReportDeps, stdout?: {
     write(chunk: string): unknown;
-}): Promise<void>;
+}, stderr?: Pick<NodeJS.WriteStream, "write">): Promise<void>;
 //# sourceMappingURL=version-report.d.ts.map

package/dist/utils/version-report.js

@@ -91,8 +91,15 @@ export function versionReportJson(report) {
     }, null, 2)}\n`;
 }
 export { isVersionRequest, wantsJson } from "../version-request.js";
-export async function runVersionCommand(argv = process.argv, deps = {}, stdout = process.stdout) {
+export async function runVersionCommand(argv = process.argv, deps = {}, stdout = process.stdout, stderr = process.stderr) {
     const report = await collectVersionReport(deps);
     stdout.write(wantsJson(argv) ? versionReportJson(report) : formatVersionReport(report));
+    if (!wantsJson(argv)) {
+        const printUpdateNudge = deps.printUpdateNudge ?? (async (target) => {
+            const { printCachedVersionNudge } = await import("./version-check.js");
+            await printCachedVersionNudge(target);
+        });
+        await printUpdateNudge(stderr);
+    }
 }
 //# sourceMappingURL=version-report.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.304.0",
+  "version": "5.306.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

package/dist/lib/work-context/index.d.ts

@@ -1,26 +0,0 @@
-/**
- * Work Context reconciliation package (consumable by hq-cli).
- * Contract (US-001) + reconcile / outbox / device default (US-007A)
- * + organize / project resolution (US-007B)
- * + cross-company correct / migrate (US-017B).
- */
-export * from "./contract.js";
-export * from "./errors.js";
-export * from "./paths.js";
-export * from "./atomic.js";
-export * from "./config.js";
-export * from "./state.js";
-export * from "./outbox.js";
-export * from "./company.js";
-export { companyBindingChanged, isNonCloudCompanySlug, presenceLeaveFromState, reboundSessionProjection, } from "./company-rebind.js";
-export * from "./project.js";
-export { decisionFromCandidates, digestOrganizePayload, formatOrganizeList, prepareOrganizeDecision, settleOrganizeAskWithoutBind, stableDecisionId, stableOrganizeOperationId, submitOrganizeDecision, } from "./organize.js";
-export type { CandidatesResponse, FetchCandidatesFn, OrganizeCandidate, OrganizeListResult, OrganizeReceipt, OrganizeSubmitDecision, OrganizeSubmitResult, PostOrganizeFn, } from "./organize.js";
-export { digestMigratePayload, formatMigrateConfirmation, stableMigrateOperationId, submitSessionMigration, } from "./migrate.js";
-export type { MigrateDestination, MigrateReceipt, MigrateSubmitResult, PostMigrateFn, } from "./migrate.js";
-export { deriveRemoteOwnerSlug, deriveRepoIdentityKey, findWorkTreeRoot, matchCompanySlugForRepo, normalizeRemoteOwnerName, } from "./repo-remote.js";
-export { matchMembershipAnswer, promptRepoCompany, } from "./repo-prompt.js";
-export type { RepoPromptCompany, RepoPromptDeps, RepoPromptOutcome, RepoPromptSkipReason, } from "./repo-prompt.js";
-export { loadObservationFromFile, markUntracked, parseObservationJson, reconcileObservation, } from "./reconcile.js";
-export type { ReconcileDeps, ReconcileObservation, ReconcileOutcome, } from "./reconcile.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/lib/work-context/index.js

@@ -1,22 +0,0 @@
-/**
- * Work Context reconciliation package (consumable by hq-cli).
- * Contract (US-001) + reconcile / outbox / device default (US-007A)
- * + organize / project resolution (US-007B)
- * + cross-company correct / migrate (US-017B).
- */
-export * from "./contract.js";
-export * from "./errors.js";
-export * from "./paths.js";
-export * from "./atomic.js";
-export * from "./config.js";
-export * from "./state.js";
-export * from "./outbox.js";
-export * from "./company.js";
-export { companyBindingChanged, isNonCloudCompanySlug, presenceLeaveFromState, reboundSessionProjection, } from "./company-rebind.js";
-export * from "./project.js";
-export { decisionFromCandidates, digestOrganizePayload, formatOrganizeList, prepareOrganizeDecision, settleOrganizeAskWithoutBind, stableDecisionId, stableOrganizeOperationId, submitOrganizeDecision, } from "./organize.js";
-export { digestMigratePayload, formatMigrateConfirmation, stableMigrateOperationId, submitSessionMigration, } from "./migrate.js";
-export { deriveRemoteOwnerSlug, deriveRepoIdentityKey, findWorkTreeRoot, matchCompanySlugForRepo, normalizeRemoteOwnerName, } from "./repo-remote.js";
-export { matchMembershipAnswer, promptRepoCompany, } from "./repo-prompt.js";
-export { loadObservationFromFile, markUntracked, parseObservationJson, reconcileObservation, } from "./reconcile.js";
-//# sourceMappingURL=index.js.map