@indigoai-us/hq-cli 5.103.29 → 5.103.31

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+## [5.103.31] — 2026-08-29
+
+## [5.103.30] — 2026-08-29
+
 ## [5.103.29] — 2026-08-29
 
 ## [5.103.28] — 2026-08-28

package/dist/commands/skill.d.ts

@@ -40,6 +40,48 @@ export declare function makeSkillTemplate(input: {
 /** Replace SKILL.md without exposing a partially-written identity to agents. */
 export declare function writeSkillFileAtomically(filePath: string, content: string): void;
 export declare function mapSkillError(status: number, body: Record<string, unknown>): string;
+/**
+ * Type a failed skills-API response by its HTTP status so the top-level error
+ * boundary can tell a correctly-denied client 4xx (ordinary caller state) from a
+ * genuine fault (an hq-cli defect or a server error). The message is built from
+ * the UNCHANGED `mapSkillError(status, body)` mapping; only the error's CLASS
+ * varies:
+ *
+ *   401 (human)         -> AuthError         (HQ-CLI-8: the caller runs `hq login`)
+ *   401 (machine)       -> unmarked Error    (a company agent never runs `hq login`)
+ *   403, 404, 409, 429  -> ExpectedUserError (HQ-CLI-6: printed, exit 1, not captured)
+ *   everything else     -> unmarked Error    (still captured to Sentry)
+ *
+ * The 4xx allowlist is closed and ENUMERATED, not a `status < 500` range: a 400
+ * or 422 means the CLI itself built a malformed request, and every 5xx is a real
+ * server fault — both must keep reaching Sentry so a genuine defect is never
+ * hidden behind a "caller error" label (HQ-CLI-Z, Sentry 7694457056). Before
+ * this, both call sites threw a bare `new Error(...)`, so a correctly-denied 403
+ * (e.g. an agent principal with no person entity) fell through the boundary's
+ * closed allowlist and filed a crash report for what hq-pro itself deliberately
+ * exempts from Sentry capture.
+ *
+ * `opts.machineIdentity` distinguishes a company agent (`isMachineIdentity()`).
+ * A machine session mints automatically and is never repaired by `hq login`, so
+ * a machine 401 is a disabled-credential or backend-authorizer fault, not
+ * login-repairable caller state — it stays an unmarked, reportable Error rather
+ * than a suppressed `AuthError`.
+ *
+ * The mapped server text is scrubbed and length-bounded through the shared
+ * `redactErrorText` chain BEFORE it is placed on any error, because the
+ * boundary's AuthError/expected branches print `err.message` verbatim — without
+ * this, an upstream 4xx diagnostic would bypass the output-safety boundary that
+ * the unmarked path still gets from `fallbackOperatorMessage`.
+ *
+ * Additive remedy for the observed condition only: a 403 whose machine-readable
+ * body `code` is NO_PERSON_ENTITY gets a CLI-actionable `hq onboard` sentence
+ * appended (wording precedent: src/commands/cloud-provision.ts). Keyed on
+ * `body.code`, never on the prose, so the message is unchanged when the field is
+ * absent.
+ */
+export declare function skillApiError(status: number, body: Record<string, unknown>, opts?: {
+    machineIdentity?: boolean;
+}): Error;
 interface SkillCommandDeps {
     ensureToken?: typeof ensureCognitoToken;
     apiFetch?: typeof vaultApiFetch;

package/dist/commands/skill.js

@@ -13,9 +13,11 @@ import * as path from "node:path";
 import chalk from "chalk";
 import yaml from "js-yaml";
 import { share } from "@indigoai-us/hq-cloud";
-import { ensureCognitoToken, DEFAULT_HQ_ROOT, buildVaultConfig, } from "../utils/cognito-session.js";
+import { ensureCognitoToken, DEFAULT_HQ_ROOT, buildVaultConfig, isMachineIdentity, } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
 import { surfaceCompanySkill } from "../lib/company-skill-wrapper.js";
+import { AuthError } from "../utils/auth-error.js";
+import { redactErrorText } from "../utils/redact-error-text.js";
 export const SKILL_UID_PATTERN = /^skl_[A-Za-z0-9]+$/;
 export const SKILL_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 const COMPANY_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
@@ -95,6 +97,21 @@ export function readCompanyPrefix(hqRoot, companySlug) {
         return undefined;
     }
 }
+/**
+ * A caller-input condition inside `resolveSkillUid` — the target has no
+ * SKILL.md, or the resolved SKILL.md carries no registered skill_uid — is the
+ * user's request/state, not an hq-cli defect. Mark it `expected` so the
+ * top-level boundary prints the actionable message and skips Sentry, exactly as
+ * `skillApiError` does for the remote 4xx siblings (HQ-CLI-Z). Redact at the
+ * throw site: the boundary's expected branch prints `err.message` verbatim, so
+ * these caller-supplied paths must be scrubbed here, not only on the fallback
+ * path they use today.
+ */
+function localSkillError(message) {
+    return Object.assign(new Error(redactErrorText(message) || message), {
+        expected: true,
+    });
+}
 /** Resolve a UID directly, or read the immutable UID from a local SKILL.md. */
 export function resolveSkillUid(target, cwd) {
     if (SKILL_UID_PATTERN.test(target))
@@ -104,11 +121,11 @@ export function resolveSkillUid(target, cwd) {
         filePath = path.join(filePath, "SKILL.md");
     }
     if (!fs.existsSync(filePath)) {
-        throw new Error(`No SKILL.md found at '${target}'. Pass a SKILL.md path, its directory, or a skl_… uid.`);
+        throw localSkillError(`No SKILL.md found at '${target}'. Pass a SKILL.md path, its directory, or a skl_… uid.`);
     }
     const uid = parseSkillUid(fs.readFileSync(filePath, "utf8"));
     if (!uid) {
-        throw new Error(`The SKILL.md at '${filePath}' has no registered skill_uid. Register and stamp it with 'hq skill create <slug> --company <company>', then retry.`);
+        throw localSkillError(`The SKILL.md at '${filePath}' has no registered skill_uid. Register and stamp it with 'hq skill create <slug> --company <company>', then retry.`);
     }
     return uid;
 }
@@ -179,6 +196,60 @@ export function mapSkillError(status, body) {
         return `Server error: ${server || status}`;
     return server || `Request failed (${status})`;
 }
+/**
+ * Type a failed skills-API response by its HTTP status so the top-level error
+ * boundary can tell a correctly-denied client 4xx (ordinary caller state) from a
+ * genuine fault (an hq-cli defect or a server error). The message is built from
+ * the UNCHANGED `mapSkillError(status, body)` mapping; only the error's CLASS
+ * varies:
+ *
+ *   401 (human)         -> AuthError         (HQ-CLI-8: the caller runs `hq login`)
+ *   401 (machine)       -> unmarked Error    (a company agent never runs `hq login`)
+ *   403, 404, 409, 429  -> ExpectedUserError (HQ-CLI-6: printed, exit 1, not captured)
+ *   everything else     -> unmarked Error    (still captured to Sentry)
+ *
+ * The 4xx allowlist is closed and ENUMERATED, not a `status < 500` range: a 400
+ * or 422 means the CLI itself built a malformed request, and every 5xx is a real
+ * server fault — both must keep reaching Sentry so a genuine defect is never
+ * hidden behind a "caller error" label (HQ-CLI-Z, Sentry 7694457056). Before
+ * this, both call sites threw a bare `new Error(...)`, so a correctly-denied 403
+ * (e.g. an agent principal with no person entity) fell through the boundary's
+ * closed allowlist and filed a crash report for what hq-pro itself deliberately
+ * exempts from Sentry capture.
+ *
+ * `opts.machineIdentity` distinguishes a company agent (`isMachineIdentity()`).
+ * A machine session mints automatically and is never repaired by `hq login`, so
+ * a machine 401 is a disabled-credential or backend-authorizer fault, not
+ * login-repairable caller state — it stays an unmarked, reportable Error rather
+ * than a suppressed `AuthError`.
+ *
+ * The mapped server text is scrubbed and length-bounded through the shared
+ * `redactErrorText` chain BEFORE it is placed on any error, because the
+ * boundary's AuthError/expected branches print `err.message` verbatim — without
+ * this, an upstream 4xx diagnostic would bypass the output-safety boundary that
+ * the unmarked path still gets from `fallbackOperatorMessage`.
+ *
+ * Additive remedy for the observed condition only: a 403 whose machine-readable
+ * body `code` is NO_PERSON_ENTITY gets a CLI-actionable `hq onboard` sentence
+ * appended (wording precedent: src/commands/cloud-provision.ts). Keyed on
+ * `body.code`, never on the prose, so the message is unchanged when the field is
+ * absent.
+ */
+export function skillApiError(status, body, opts = {}) {
+    let message = redactErrorText(mapSkillError(status, body)) || `Request failed (${status})`;
+    if (status === 403 && body.code === "NO_PERSON_ENTITY") {
+        message += " Run `hq onboard` first to create your HQ identity, then retry.";
+    }
+    if (status === 401) {
+        return opts.machineIdentity ? new Error(message) : new AuthError(message);
+    }
+    if (status === 403 || status === 404 || status === 409 || status === 429) {
+        return Object.assign(new Error(message), {
+            expected: true,
+        });
+    }
+    return new Error(message);
+}
 export function registerSkillCommand(program, deps = {}) {
     const ensureToken = deps.ensureToken ?? ensureCognitoToken;
     const apiFetch = deps.apiFetch ?? vaultApiFetch;
@@ -245,7 +316,9 @@ export function registerSkillCommand(program, deps = {}) {
         });
         if (!response.ok) {
             const body = (await response.json().catch(() => ({})));
-            throw new Error(mapSkillError(response.status, body));
+            throw skillApiError(response.status, body, {
+                machineIdentity: isMachineIdentity(),
+            });
         }
         const registered = (await response.json());
         if (typeof registered.skillUid !== "string" ||
@@ -316,7 +389,9 @@ export function registerSkillCommand(program, deps = {}) {
         });
         if (!response.ok) {
             const body = (await response.json().catch(() => ({})));
-            throw new Error(mapSkillError(response.status, body));
+            throw skillApiError(response.status, body, {
+                machineIdentity: isMachineIdentity(),
+            });
         }
         const posted = (await response.json());
         console.log(chalk.green(`Improvement posted: ${posted.commentId}`));

package/package.json

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