@indigoai-us/hq-cli 5.345.160 → 5.345.161

package/dist/lib/windows/ps1-shims.js

@@ -0,0 +1,152 @@
+/**
+ * npm writes three launchers for every global bin on Windows: `hq`, `hq.cmd`
+ * and `hq.ps1`. PowerShell prefers `hq.ps1`, and under the default
+ * `Restricted` execution policy it refuses to run it ("running scripts is
+ * disabled on this system", UnauthorizedAccess). `hq.cmd` works under every
+ * policy, so hq-cli removes its own `.ps1` launchers and PowerShell falls
+ * through to `hq.cmd`.
+ *
+ * Only a file whose content is npm's generated launcher for an hq-cli bin is
+ * removed. A `.ps1` written by a person or another package is left alone. The
+ * execution policy is read only, never changed.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawnSync } from "node:child_process";
+/** hq-cli's own bins and the package file each npm launcher runs. */
+export const HQ_CLI_BINS = {
+    hq: "dist/index.js",
+    "hq-auth-refresh": "dist/bin/hq-auth-refresh.js",
+};
+const PACKAGE_PATH = "node_modules/@indigoai-us/hq-cli/";
+/**
+ * True when `content` is npm's (cmd-shim) PowerShell launcher for the hq-cli
+ * bin `bin`. The launcher resolves its own folder, runs node on
+ * `$basedir/node_modules/@indigoai-us/hq-cli/<entry>` and exits with node's
+ * code. Either slash direction is accepted.
+ */
+export function isNpmGeneratedHqCliPs1Shim(content, bin) {
+    const entry = HQ_CLI_BINS[bin];
+    if (!entry)
+        return false;
+    const text = content.replace(/\r\n/g, "\n").replace(/\\/g, "/");
+    if (!text.startsWith("#!/usr/bin/env pwsh\n"))
+        return false;
+    if (!text.includes("$basedir=Split-Path $MyInvocation.MyCommand.Definition -Parent"))
+        return false;
+    if (!text.trimEnd().endsWith("exit $ret"))
+        return false;
+    return text.includes(`"$basedir/${PACKAGE_PATH}${entry}"`);
+}
+const realFs = {
+    readFile: (file) => fs.readFileSync(file, "utf8"),
+    remove: (file) => fs.rmSync(file, { force: true }),
+};
+function isMissing(error) {
+    const code = error?.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+/** The npm-generated hq-cli `.ps1` launchers present in `binDir`. */
+export function findHqCliPs1Shims(binDir, io = realFs) {
+    const found = [];
+    for (const bin of Object.keys(HQ_CLI_BINS)) {
+        const file = path.join(binDir, `${bin}.ps1`);
+        let content;
+        try {
+            content = io.readFile(file);
+        }
+        catch {
+            continue;
+        }
+        if (isNpmGeneratedHqCliPs1Shim(content, bin))
+            found.push(file);
+    }
+    return found;
+}
+/**
+ * Remove the npm-generated `.ps1` launchers for hq-cli's bins from `binDir`
+ * (the npm global prefix on Windows). Safe to run again: a missing file is
+ * not an error. Never touches another package's `.ps1` or a hand-written one.
+ */
+export function removeHqCliPs1Shims(binDir, io = realFs) {
+    const result = { removed: [], kept: [], failed: [] };
+    for (const bin of Object.keys(HQ_CLI_BINS)) {
+        const file = path.join(binDir, `${bin}.ps1`);
+        let content;
+        try {
+            content = io.readFile(file);
+        }
+        catch (error) {
+            if (!isMissing(error)) {
+                result.failed.push({ file, reason: error instanceof Error ? error.message : String(error) });
+            }
+            continue;
+        }
+        if (!isNpmGeneratedHqCliPs1Shim(content, bin)) {
+            result.kept.push(file);
+            continue;
+        }
+        try {
+            io.remove(file);
+            result.removed.push(file);
+        }
+        catch (error) {
+            if (isMissing(error))
+                continue;
+            result.failed.push({ file, reason: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return result;
+}
+/** Policies under which PowerShell refuses to run an unsigned local `.ps1`. */
+const BLOCKING_POLICIES = new Set(["restricted", "allsigned", "undefined"]);
+/**
+ * True when the effective execution policy blocks npm's unsigned launcher.
+ * `Undefined` as the effective policy means no scope set one, which Windows
+ * client editions treat as `Restricted`.
+ */
+export function policyBlocksUnsignedScripts(policy) {
+    return BLOCKING_POLICIES.has(policy.trim().toLowerCase());
+}
+function defaultPolicyRun() {
+    const run = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", "Get-ExecutionPolicy"], { encoding: "utf8", windowsHide: true, timeout: 15_000 });
+    return { status: run.status, stdout: typeof run.stdout === "string" ? run.stdout : "" };
+}
+/**
+ * Read the current user's effective PowerShell execution policy. Read-only:
+ * it runs `Get-ExecutionPolicy` and never sets anything. Null when
+ * PowerShell could not be run or printed nothing usable.
+ */
+export function readExecutionPolicy(run = defaultPolicyRun) {
+    try {
+        const { status, stdout } = run();
+        if (status !== 0)
+            return null;
+        const policy = stdout.trim().split(/\s+/).pop() ?? "";
+        return /^[A-Za-z]+$/.test(policy) ? policy : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Postinstall entry: after a global npm install on Windows, remove hq-cli's
+ * `.ps1` launchers from the prefix holding `packageDir`. Acts only when the
+ * package sits at `<prefix>/node_modules/@indigoai-us/hq-cli`, npm's Windows
+ * global layout. Null when it did nothing. npm 11.16+ may skip lifecycle
+ * scripts, so `hq doctor` reports any launcher left behind.
+ */
+export function removePs1ShimsAfterNpmInstall(packageDir, opts, io = realFs) {
+    if (opts.platform !== "win32" || !opts.global)
+        return null;
+    const dir = path.resolve(packageDir);
+    const scope = path.dirname(dir);
+    const nodeModules = path.dirname(scope);
+    if (path.basename(dir).toLowerCase() !== "hq-cli" ||
+        path.basename(scope).toLowerCase() !== "@indigoai-us" ||
+        path.basename(nodeModules).toLowerCase() !== "node_modules") {
+        return null;
+    }
+    return removeHqCliPs1Shims(path.dirname(nodeModules), io);
+}
+//# sourceMappingURL=ps1-shims.js.map

package/dist/utils/self-update.d.ts

@@ -136,6 +136,8 @@ export declare function acquireUpdateLock(now?: number): (() => void) | null;
 /** Injectable surface so the flow is unit-testable without network or spawns. */
 export interface SelfUpdateDeps {
     env?: NodeJS.ProcessEnv;
+    /** Platform whose npm launcher layout the update cleans up (tests inject win32). */
+    platform?: NodeJS.Platform;
     currentVersion?: string;
     fetchLatest?: () => Promise<string | null>;
     resolveInstall?: () => RunningInstall;

package/dist/utils/self-update.js

@@ -70,6 +70,7 @@ import { canStageInstall, stagedNpmInstall } from "./staged-install.js";
 import { acquireUpdateLock as acquireSharedUpdateLock } from "./update-lock.js";
 import { markLatestIneffective } from "./version-check.js";
 import { fileSelfUpdateBackoff } from "./self-update-backoff.js";
+import { removeHqCliPs1Shims } from "../lib/windows/ps1-shims.js";
 import { restartDaemonServiceIfInstalled } from "../lib/mesh/live/daemon/install.js";
 import { createCurrentPackageUseLeaseHandoff, PACKAGE_USE_LEASE_HANDOFF_ENV, releaseCurrentPackageUseLease, } from "./package-use-lease.js";
 /**
@@ -1041,6 +1042,13 @@ async function attemptUpdateAndReexec(argv, flavor, known, deps, env) {
             if (!bins.ok)
                 result = bins;
         }
+        // npm regenerates hq.ps1 on every Windows install. PowerShell prefers it to
+        // hq.cmd, and a Restricted execution policy then blocks every hq command.
+        if (result.ok && install.manager === "npm" && install.prefix && (deps.platform ?? process.platform) === "win32") {
+            for (const failure of removeHqCliPs1Shims(install.prefix).failed) {
+                console.error(chalk.yellow(`  Could not remove ${failure.file} (${failure.reason}). In PowerShell, run hq.cmd instead of hq.`));
+            }
+        }
         if (!result.ok && installSnapshot) {
             restoredAfterFailure = restoreInstall(installSnapshot, renamePath);
             if (restoredAfterFailure) {

package/dist/utils/staged-npm-install.js

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { isMainModule } from "./is-main-module.js";
+import { removeHqCliPs1Shims } from "../lib/windows/ps1-shims.js";
 const PACKAGE_NAME = "@indigoai-us/hq-cli";
 const RANDOM_HEX_BYTES = 6;
 function packageRoot(prefix, platform) {
@@ -53,6 +54,13 @@ function temporaryRoot() {
 function randomSuffix() {
     return randomBytes(RANDOM_HEX_BYTES).toString("hex");
 }
+/** Best effort: a leftover npm hq .ps1 launcher must never fail an otherwise good update. */
+function removeStalePs1Shims(binDir) {
+    const result = removeHqCliPs1Shims(binDir);
+    for (const failure of result.failed) {
+        console.error("[hq-cli-update] could not remove PowerShell launcher; use hq.cmd", failure);
+    }
+}
 function bestEffortRemove(target) {
     if (!target)
         return;
@@ -149,7 +157,8 @@ export function activateStagedNpmPackage(prefix, stagePrefix, platform = process
                 continue;
             const executable = path.join(targetPackage, entry);
             if (platform === "win32") {
-                for (const extension of ["", ".cmd", ".ps1"]) {
+                // No .ps1: PowerShell prefers it over hq.cmd and a Restricted policy blocks it.
+                for (const extension of ["", ".cmd"]) {
                     const stagedFile = path.join(stageBinDir, `${name}${extension}`);
                     if (!existsSync(stagedFile))
                         continue;
@@ -178,7 +187,7 @@ export function activateStagedNpmPackage(prefix, stagePrefix, platform = process
         renameSync(candidatePackage, targetPackage);
         packageActivated = true;
         for (const name of names) {
-            for (const extension of platform === "win32" ? ["", ".cmd", ".ps1"] : [""]) {
+            for (const extension of platform === "win32" ? ["", ".cmd"] : [""]) {
                 const filename = `${name}${extension}`;
                 const target = path.join(targetBinDir, filename);
                 const staged = path.join(stagedBins, filename);
@@ -193,6 +202,8 @@ export function activateStagedNpmPackage(prefix, stagePrefix, platform = process
                 }
             }
         }
+        if (platform === "win32")
+            removeStalePs1Shims(targetBinDir);
         bestEffortRemove(packageBackedUp ? backupPackage : undefined);
         bestEffortRemove(backupBins);
         return { ok: true };

package/dist/utils/token-keychain.d.ts

@@ -11,14 +11,15 @@
  *   - signer:  Team ID HWFZ2QDTMR (login-keychain partition `teamid:HWFZ2QDTMR`)
  *
  * The read goes through `/usr/bin/security`, so there is no native module.
- * macOS asks the user once whether `security` may read the item; HQ accepts
+ * macOS may ask whether `security` may read the item; HQ accepts
  * that prompt (owner decision) and explains it first:
  *   - Before the first read, a one-line note is printed to stderr. It is only
- *     shown, and the first read only happens, in an interactive terminal, so
- *     a background process never raises the prompt unexplained.
- *   - A denied prompt, a timeout or any other failure falls back to the file
- *     quietly and is remembered in `~/.hq/keychain-access.json`, so HQ does
- *     not ask again on every run. `hq auth keychain --retry` clears it.
+ *     shown, and the first read only happens, in an interactive terminal.
+ *     A prior success may still have been one-time Allow: it does not prove
+ *     future reads cannot prompt. After a failure, background reads stop.
+ *   - A canceled/refused prompt falls back to the file and suppresses reads
+ *     until `hq auth keychain --retry`. Timeouts and other failures clear
+ *     remembered access: only a future interactive command can ask again.
  *   - "Item not found" is a plain miss and is not remembered as a denial.
  *
  * Choosing between the Keychain and the file (writes still go to the file):
@@ -38,7 +39,7 @@ export declare const KEYCHAIN_TEAM_ID = "HWFZ2QDTMR";
 export declare const KEYCHAIN_READ_TIMEOUT_MS = 3000;
 /** First read: long enough for a person to answer the macOS prompt. */
 export declare const KEYCHAIN_FIRST_READ_TIMEOUT_MS = 60000;
-export declare const KEYCHAIN_FIRST_READ_NOTE = "macOS will ask once whether HQ can read your sign-in from the Keychain. Choose Always Allow.";
+export declare const KEYCHAIN_FIRST_READ_NOTE = "macOS may ask whether HQ can read your sign-in from the Keychain. If asked, enter your login keychain password (usually your Mac login password). Choose Always Allow to avoid repeated prompts.";
 export interface KeychainTokenShape {
     accessToken: string;
     idToken: string;
@@ -55,6 +56,8 @@ export interface KeychainAccessState {
     noteShownAt?: string;
     allowedAt?: string;
     deniedAt?: string;
+    lastFailureAt?: string;
+    failureReason?: "timeout" | "unavailable" | "canceled" | "authorization";
 }
 export interface KeychainReadOptions {
     platform?: NodeJS.Platform;
@@ -69,7 +72,7 @@ export interface KeychainReadOptions {
     retry?: boolean;
     now?: () => Date;
 }
-export type KeychainReadOutcome = "hit" | "miss" | "denied" | "skipped-denied" | "skipped-not-interactive" | "disabled";
+export type KeychainReadOutcome = "hit" | "miss" | "denied" | "skipped-denied" | "skipped-not-interactive" | "unavailable" | "disabled";
 export declare function keychainTokenReadEnabled(opts?: KeychainReadOptions): boolean;
 export declare function keychainAccessStateFile(home?: string): string;
 export declare function readKeychainAccessState(home?: string): KeychainAccessState;

package/dist/utils/token-keychain.js

@@ -11,14 +11,15 @@
  *   - signer:  Team ID HWFZ2QDTMR (login-keychain partition `teamid:HWFZ2QDTMR`)
  *
  * The read goes through `/usr/bin/security`, so there is no native module.
- * macOS asks the user once whether `security` may read the item; HQ accepts
+ * macOS may ask whether `security` may read the item; HQ accepts
  * that prompt (owner decision) and explains it first:
  *   - Before the first read, a one-line note is printed to stderr. It is only
- *     shown, and the first read only happens, in an interactive terminal, so
- *     a background process never raises the prompt unexplained.
- *   - A denied prompt, a timeout or any other failure falls back to the file
- *     quietly and is remembered in `~/.hq/keychain-access.json`, so HQ does
- *     not ask again on every run. `hq auth keychain --retry` clears it.
+ *     shown, and the first read only happens, in an interactive terminal.
+ *     A prior success may still have been one-time Allow: it does not prove
+ *     future reads cannot prompt. After a failure, background reads stop.
+ *   - A canceled/refused prompt falls back to the file and suppresses reads
+ *     until `hq auth keychain --retry`. Timeouts and other failures clear
+ *     remembered access: only a future interactive command can ask again.
  *   - "Item not found" is a plain miss and is not remembered as a denial.
  *
  * Choosing between the Keychain and the file (writes still go to the file):
@@ -44,9 +45,15 @@ export const KEYCHAIN_READ_TIMEOUT_MS = 3_000;
 export const KEYCHAIN_FIRST_READ_TIMEOUT_MS = 60_000;
 /** `security` exit status for errSecItemNotFound. */
 const SECURITY_ITEM_NOT_FOUND = 44;
+/** errSecUserCanceled (-128), truncated to the process exit status. This
+ * cannot distinguish Deny from Cancel: do not retry either automatically. */
+const SECURITY_USER_CANCELED = 128;
+/** errSecAuthFailed (-25293). A denied authorization and a wrong password
+ * cannot be distinguished here, so either requires an explicit retry. */
+const SECURITY_AUTH_FAILED = 51;
 /** Reuse a read within one process for this long (avoids a spawn per request). */
 const READ_CACHE_MS = 30_000;
-export const KEYCHAIN_FIRST_READ_NOTE = "macOS will ask once whether HQ can read your sign-in from the Keychain. Choose Always Allow.";
+export const KEYCHAIN_FIRST_READ_NOTE = "macOS may ask whether HQ can read your sign-in from the Keychain. If asked, enter your login keychain password (usually your Mac login password). Choose Always Allow to avoid repeated prompts.";
 const defaultRunner = (args, timeoutMs) => {
     try {
         const result = spawnSync("/usr/bin/security", args, {
@@ -144,8 +151,8 @@ export function readKeychainTokensDetailed(opts = {}) {
         return { tokens, outcome };
     };
     let state = readKeychainAccessState(home);
-    if (opts.retry && state.deniedAt) {
-        const { deniedAt: _cleared, ...rest } = state;
+    if (opts.retry) {
+        const { deniedAt: _cleared, allowedAt: _allowed, ...rest } = state;
         state = rest;
         writeKeychainAccessState(home, state);
     }
@@ -166,15 +173,23 @@ export function readKeychainTokensDetailed(opts = {}) {
     const run = opts.runSecurity ?? defaultRunner;
     const result = run(["find-generic-password", "-s", KEYCHAIN_SERVICE, "-a", KEYCHAIN_ACCOUNT, "-w"], state.allowedAt ? KEYCHAIN_READ_TIMEOUT_MS : KEYCHAIN_FIRST_READ_TIMEOUT_MS);
     if (result.status === 0 && !result.timedOut) {
-        if (!state.allowedAt)
-            writeKeychainAccessState(home, { ...state, allowedAt: now().toISOString() });
+        const { deniedAt: _denied, lastFailureAt: _failed, failureReason: _reason, ...rest } = state;
+        writeKeychainAccessState(home, { ...rest, allowedAt: now().toISOString() });
         return remember(parseTokenJson(decodeSecurityOutput(result.stdout)), "hit");
     }
     if (result.status === SECURITY_ITEM_NOT_FOUND && !result.timedOut)
         return remember(null, "miss");
-    // Denied, timed out, or failed: fall back quietly and don't ask again.
-    writeKeychainAccessState(home, { ...state, deniedAt: now().toISOString() });
-    return remember(null, "denied");
+    // A previous success does not prove Always Allow: another read may prompt.
+    // Clear it on failure so a background process cannot prompt on the next run.
+    const { allowedAt: _allowed, deniedAt: _denied, ...rest } = state;
+    const lastFailureAt = now().toISOString();
+    if (!result.timedOut && (result.status === SECURITY_USER_CANCELED || result.status === SECURITY_AUTH_FAILED)) {
+        writeKeychainAccessState(home, { ...rest, deniedAt: lastFailureAt, lastFailureAt,
+            failureReason: result.status === SECURITY_USER_CANCELED ? "canceled" : "authorization" });
+        return remember(null, "denied");
+    }
+    writeKeychainAccessState(home, { ...rest, lastFailureAt, failureReason: result.timedOut ? "timeout" : "unavailable" });
+    return remember(null, "unavailable");
 }
 export function readKeychainTokens(opts = {}) {
     return readKeychainTokensDetailed(opts).tokens;
@@ -209,10 +224,16 @@ export function readPersonTokensWithKeychain(file = path.join(os.homedir(), ".hq
     catch {
         fromFile = null;
     }
-    const fromKeychain = readKeychainTokens(opts);
+    const result = readKeychainTokensDetailed(opts);
+    const fromKeychain = result.tokens;
     const chosen = pickNewerSession(fromKeychain, fromFile);
     if (!chosen)
         return { tokens: null, source: "none" };
+    if (chosen === fromFile && (result.outcome === "unavailable" || result.outcome === "denied")
+        && (opts.interactive ?? Boolean(process.stderr.isTTY)) && readCache && !readCache.fallbackNotified) {
+        (opts.notify ?? ((line) => process.stderr.write(`${line}\n`)))("Keychain access did not complete. HQ used your saved sign-in instead.");
+        readCache.fallbackNotified = true;
+    }
     return { tokens: chosen, source: chosen === fromKeychain ? "keychain" : "file" };
 }
 //# sourceMappingURL=token-keychain.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.160",
+  "version": "5.345.161",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -52,7 +52,7 @@
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
     "@aws-sdk/dsql-signer": "^3.1146.0",
-    "@indigoai-us/hq-cloud": "6.18.98",
+    "@indigoai-us/hq-cloud": "6.18.99",
     "@indigoai-us/hq-flags-client": "^0.1.2",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@sentry/node": "^10.49.0",
@@ -114,11 +114,11 @@
     "*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}": "eslint --cache --no-error-on-unmatched-pattern"
   },
   "optionalDependencies": {
-    "@indigoai-us/hq-hook-win32-x64": "5.345.160",
-    "@indigoai-us/hq-hook-win32-arm64": "5.345.160",
-    "@indigoai-us/hq-hook-darwin-x64": "5.345.160",
-    "@indigoai-us/hq-hook-darwin-arm64": "5.345.160",
-    "@indigoai-us/hq-hook-linux-x64": "5.345.160",
-    "@indigoai-us/hq-hook-linux-arm64": "5.345.160"
+    "@indigoai-us/hq-hook-win32-x64": "5.345.161",
+    "@indigoai-us/hq-hook-win32-arm64": "5.345.161",
+    "@indigoai-us/hq-hook-darwin-x64": "5.345.161",
+    "@indigoai-us/hq-hook-darwin-arm64": "5.345.161",
+    "@indigoai-us/hq-hook-linux-x64": "5.345.161",
+    "@indigoai-us/hq-hook-linux-arm64": "5.345.161"
   }
 }

package/scripts/install-hook-engine.mjs

@@ -1,4 +1,5 @@
 import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 // A source checkout has not built dist during pnpm install. Published tarballs
 // never contain src; a broken tarball warns and keeps existing bash hooks active.
 if (!existsSync(new URL('../dist/lib/hook-engine/resolve.js', import.meta.url)) && existsSync(new URL('../src/index.ts', import.meta.url))) process.exit(0);
@@ -8,3 +9,14 @@ try {
 } catch (error) {
   console.warn(`HQ native hook engine unavailable: ${error instanceof Error ? error.message : String(error)}. Existing bash hooks remain active. Repair: npm install -g @indigoai-us/hq-cli --include=optional`);
 }
+// npm writes hq.ps1 next to hq.cmd on Windows. PowerShell prefers it and the
+// default Restricted execution policy blocks it, so remove hq-cli's own .ps1
+// launchers. Best effort: hq doctor reports any that remain.
+try {
+  const { removePs1ShimsAfterNpmInstall } = await import('../dist/lib/windows/ps1-shims.js');
+  const packageDir = fileURLToPath(new URL('..', import.meta.url));
+  const result = removePs1ShimsAfterNpmInstall(packageDir, { platform: process.platform, global: process.env.npm_config_global === 'true' });
+  for (const failure of result?.failed ?? []) console.warn(`Could not remove ${failure.file} (${failure.reason}). In PowerShell, run hq.cmd instead of hq.`);
+} catch (error) {
+  console.warn(`HQ PowerShell launcher cleanup skipped: ${error instanceof Error ? error.message : String(error)}. If PowerShell blocks hq, run hq.cmd doctor --fix.`);
+}