@indigoai-us/hq-cli 5.77.13 → 5.78.0

package/dist/commands/secrets.js

@@ -7,13 +7,18 @@ import { DEFAULT_SECRETS_CACHE_TTL_MS, writeCache, removeCacheEntry, clearAllCac
 import { computeSha256 } from "../utils/integrity.js";
 import { SECRET_NAME_PATTERN, GROUP_ID_PATTERN, EMAIL_PATTERN } from "./_patterns.js";
 import { describeSecretsScope, formatSecretSaved, formatSecretsListEmpty, formatSecretsListHeader, } from "./secrets-scope.js";
-import { vaultApiFetch, getCompanyUid, getEntityUid, } from "../utils/vault-api.js";
-import { HQ_API_KEY_PREFIX, assertCognitoOnlyCommand, resolveVaultCredential, } from "../utils/resolve-vault-credential.js";
+import { vaultApiFetch, getCompanyUid, getEntityUid, looksLikeCompanyUid, } from "../utils/vault-api.js";
+import { HQ_API_KEY_PREFIX, formatApiKeyCapabilityDenial, requireApiKeyCapability, resolveVaultCredentialForCapability, } from "../utils/resolve-vault-credential.js";
 import { SandboxRunnerClient, } from "../utils/sandbox-runner-client.js";
 export { vaultApiFetch, getCompanyUid, getEntityUid };
-/** Cognito session for secrets commands that do not support HQ_API_KEY. */
-async function requireCognitoTokenForSecrets(commandLabel) {
-    assertCognitoOnlyCommand(commandLabel);
+/**
+ * Cognito session for secrets surfaces hq-pro serves on the JWT routes only —
+ * the capability would apply, but there is no Bearer `hqk_` route (no HEAD
+ * probe, no policy/script/sandbox/submit-link parallel). Fails closed under
+ * HQ_API_KEY instead of quietly using the cached session.
+ */
+async function requireCognitoTokenForSecrets(commandLabel, capability = null) {
+    requireApiKeyCapability(capability, commandLabel, { routeAvailable: false });
     return ensureCognitoToken();
 }
 function scopeOpts(opts) {
@@ -35,12 +40,71 @@ function shellSingleQuote(value) {
 // API Gateway v2 URL-decodes `%2F` before route matching, so a full-name
 // `encodeURIComponent` would collapse structural `/` separators into a single
 // segment the `/name/{proxy+}` route can't match.
+function encodeSecretNameSegments(name) {
+    return name.split("/").map(encodeURIComponent).join("/");
+}
 function buildSecretNamePath(companyUid, name) {
-    const encodedName = name
-        .split("/")
-        .map(encodeURIComponent)
-        .join("/");
-    return `/secrets/${encodeURIComponent(companyUid)}/name/${encodedName}`;
+    return `/secrets/${encodeURIComponent(companyUid)}/name/${encodeSecretNameSegments(name)}`;
+}
+/**
+ * Company uid a Bearer `hqk_` secrets call targets.
+ *
+ * The `/v1/keys/secrets/{companyUid}` routes take the uid in the path, and the
+ * server 403s when it is not the key's own company. Slug resolution (and the
+ * "my single active membership" fallback) runs through Cognito-only entity
+ * routes, so under an API key the uid must be supplied explicitly.
+ */
+function resolveApiKeyCompanyUid(scope, commandLabel) {
+    if (scope.personal) {
+        throw new Error(`--personal is not supported with HQ_API_KEY ('${commandLabel}'): a vault ` +
+            `API key is bound to one company. Unset HQ_API_KEY to use your personal vault.`);
+    }
+    const ref = scope.companySlug ?? process.env.HQ_COMPANY_UID?.trim();
+    if (!ref) {
+        throw new Error(`HQ_API_KEY is set; '${commandLabel}' needs the company uid the key is bound ` +
+            `to. Pass --company cmp_… or set HQ_COMPANY_UID (\`hq api-keys list\` shows ` +
+            `it with a Cognito session).`);
+    }
+    if (!looksLikeCompanyUid(ref)) {
+        throw new Error(`HQ_API_KEY is set; --company must be a company uid (cmp_…) — resolving a ` +
+            `slug needs a Cognito session. Got '${ref}'.`);
+    }
+    return ref;
+}
+async function resolveSecretsTarget(capability, commandLabel, scopeOptions) {
+    const cred = await resolveVaultCredentialForCapability(capability, commandLabel);
+    const scope = scopeOpts(scopeOptions);
+    const isApiKey = cred.kind === "api-key";
+    const companyUid = isApiKey
+        ? resolveApiKeyCompanyUid(scope, commandLabel)
+        : await getEntityUid(cred.token, scope);
+    const basePath = isApiKey
+        ? `/v1/keys/secrets/${encodeURIComponent(companyUid)}`
+        : `/secrets/${encodeURIComponent(companyUid)}`;
+    return {
+        token: cred.token,
+        isApiKey,
+        companyUid,
+        scopeLabel: describeSecretsScope({
+            personal: scope.personal,
+            companySlug: scope.companySlug,
+            companyUid,
+        }),
+        basePath,
+        namePath: (name) => `${basePath}/name/${encodeSecretNameSegments(name)}`,
+        aclPath: (action) => action ? `${basePath}/acl/${action}` : `${basePath}/acl`,
+    };
+}
+/**
+ * Failure message for a secrets call. A 403 on an API-key route may carry
+ * hq-pro's `{ granted, missing }` capability report — surface it verbatim so
+ * the caller sees the key's real grants, not just "forbidden".
+ */
+function describeSecretsFailure(target, status, body, fallback) {
+    if (target.isApiKey && status === 403) {
+        return formatApiKeyCapabilityDenial(body, fallback);
+    }
+    return extractApiMessage(body, fallback);
 }
 function parseDuration(input) {
     const match = input.match(/^(\d+)(m|h|d)$/);
@@ -685,17 +749,11 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red(`Secret value exceeds 4096-byte SSM limit (got ${Buffer.byteLength(value, "utf8")} bytes).`));
                 process.exit(1);
             }
-            const token = await requireCognitoTokenForSecrets("secrets set");
-            const scope = scopeOpts(secrets.opts());
-            const companyUid = await getEntityUid(token, scope);
-            const scopeLabel = describeSecretsScope({
-                personal: scope.personal,
-                companySlug: scope.companySlug,
-                companyUid,
-            });
+            const target = await resolveSecretsTarget("secrets:write", "secrets set", secrets.opts());
+            const { token, companyUid, scopeLabel } = target;
             const res = await vaultApiFetch({
                 token,
-                path: `/secrets/${encodeURIComponent(companyUid)}`,
+                path: target.basePath,
                 method: "POST",
                 body: {
                     name,
@@ -710,7 +768,7 @@ export function registerSecretsCommand(program) {
             });
             if (!res.ok) {
                 const body = (await res.json().catch(() => ({})));
-                console.error(chalk.red(`Failed to set secret: ${extractApiMessage(body, res.statusText)}`));
+                console.error(chalk.red(`Failed to set secret: ${describeSecretsFailure(target, res.status, body, res.statusText)}`));
                 process.exit(1);
             }
             removeCacheEntry(companyUid, name);
@@ -730,8 +788,13 @@ export function registerSecretsCommand(program) {
         .option("--reveal", "Include the decrypted secret value")
         .action(async (name, opts) => {
         try {
-            const cred = await resolveVaultCredential();
+            const cred = await resolveVaultCredentialForCapability("secrets:read", "secrets get");
             if (cred.kind === "api-key") {
+                if (!opts.reveal) {
+                    console.error(chalk.red("HQ_API_KEY is set; `hq secrets get` without --reveal is not supported for API keys. " +
+                        "Use --reveal to fetch the value, or unset HQ_API_KEY for metadata-only reads."));
+                    process.exit(1);
+                }
                 const res = await vaultApiFetch({
                     token: cred.token,
                     path: "/v1/keys/secrets/fetch",
@@ -744,7 +807,7 @@ export function registerSecretsCommand(program) {
                         console.error(chalk.red(highSecuritySandboxOnlyMessage(name)));
                         process.exit(1);
                     }
-                    console.error(chalk.red(`Failed to get secret: ${extractApiMessage(body, res.statusText)}`));
+                    console.error(chalk.red(`Failed to get secret: ${describeSecretsFailure({ isApiKey: true }, res.status, body, res.statusText)}`));
                     process.exit(1);
                 }
                 const secret = typeof body.secret === "object" && body.secret !== null
@@ -846,7 +909,7 @@ export function registerSecretsCommand(program) {
         .option("--quiet", "Suppress the present/absent line (use the exit code only)")
         .action(async (name, opts) => {
         try {
-            const token = await requireCognitoTokenForSecrets("secrets exists");
+            const token = await requireCognitoTokenForSecrets("secrets exists", "secrets:read");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -889,26 +952,20 @@ export function registerSecretsCommand(program) {
                 }
                 normalizedPrefix = normalized;
             }
-            const token = await requireCognitoTokenForSecrets("secrets list");
-            const scope = scopeOpts(secrets.opts());
-            const companyUid = await getEntityUid(token, scope);
-            const scopeLabel = describeSecretsScope({
-                personal: scope.personal,
-                companySlug: scope.companySlug,
-                companyUid,
-            });
+            const target = await resolveSecretsTarget("secrets:read", "secrets list", secrets.opts());
+            const { scopeLabel } = target;
             const query = {};
             if (normalizedPrefix) {
                 query.prefix = normalizedPrefix;
             }
             const res = await vaultApiFetch({
-                token,
-                path: `/secrets/${encodeURIComponent(companyUid)}`,
+                token: target.token,
+                path: target.basePath,
                 query: Object.keys(query).length > 0 ? query : undefined,
             });
             if (!res.ok) {
-                const body = await res.json().catch(() => ({}));
-                console.error(chalk.red(`Failed to list secrets: ${body.error ?? res.statusText}`));
+                const body = (await res.json().catch(() => ({})));
+                console.error(chalk.red(`Failed to list secrets: ${describeSecretsFailure(target, res.status, body, res.statusText)}`));
                 process.exit(1);
             }
             const data = (await res.json());
@@ -963,7 +1020,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red(`Invalid secret path '${secretPath}': must match ^[A-Z][A-Z0-9_]*(/[A-Z][A-Z0-9_]+)*$ (e.g. MY_KEY or PROD/DB_PASSWORD)`));
                 process.exit(1);
             }
-            const token = await requireCognitoTokenForSecrets("secrets");
+            const token = await requireCognitoTokenForSecrets("secrets policy get", "secrets:read");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -1024,7 +1081,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red("Error: provide at least one of --tier or --lock-script."));
                 process.exit(1);
             }
-            const token = await requireCognitoTokenForSecrets("secrets");
+            const token = await requireCognitoTokenForSecrets("secrets policy set", "secrets:write");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -1069,7 +1126,7 @@ export function registerSecretsCommand(program) {
                 process.exit(1);
             }
             const usage = await buildSecretUsage("exec", opts.script, opts.id, opts.attestation);
-            const token = await requireCognitoTokenForSecrets("secrets");
+            const token = await requireCognitoTokenForSecrets("secrets script approve", "secrets:write");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -1107,7 +1164,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red(`Invalid secret path '${secretPath}': must match ^[A-Z][A-Z0-9_]*(/[A-Z][A-Z0-9_]+)*$ (e.g. MY_KEY or PROD/DB_PASSWORD)`));
                 process.exit(1);
             }
-            const token = await requireCognitoTokenForSecrets("secrets");
+            const token = await requireCognitoTokenForSecrets("secrets script revoke", "secrets:write");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -1138,7 +1195,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red(`Invalid secret path '${secretPath}': must match ^[A-Z][A-Z0-9_]*(/[A-Z][A-Z0-9_]+)*$ (e.g. MY_KEY or PROD/DB_PASSWORD)`));
                 process.exit(1);
             }
-            const token = await requireCognitoTokenForSecrets("secrets");
+            const token = await requireCognitoTokenForSecrets("secrets script list", "secrets:read");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -1185,16 +1242,16 @@ export function registerSecretsCommand(program) {
                     return;
                 }
             }
-            const token = await requireCognitoTokenForSecrets("secrets");
-            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
+            const target = await resolveSecretsTarget("secrets:write", "secrets delete", secrets.opts());
+            const companyUid = target.companyUid;
             const res = await vaultApiFetch({
-                token,
-                path: buildSecretNamePath(companyUid, name),
+                token: target.token,
+                path: target.namePath(name),
                 method: "DELETE",
             });
             if (!res.ok) {
-                const body = await res.json().catch(() => ({}));
-                console.error(chalk.red(`Failed to delete secret: ${body.error ?? res.statusText}`));
+                const body = (await res.json().catch(() => ({})));
+                console.error(chalk.red(`Failed to delete secret: ${describeSecretsFailure(target, res.status, body, res.statusText)}`));
                 process.exit(1);
             }
             removeCacheEntry(companyUid, name);
@@ -1229,7 +1286,7 @@ export function registerSecretsCommand(program) {
                 process.exit(1);
             }
             const keys = parseSecretNameList(opts.only);
-            const token = await requireCognitoTokenForSecrets("secrets");
+            const token = await requireCognitoTokenForSecrets("secrets sandbox", "secrets:read");
             const scope = scopeOpts(mergeScopeOpts(secrets.opts(), opts));
             const companyUid = await getEntityUid(token, scope);
             const client = new SandboxRunnerClient();
@@ -1282,7 +1339,7 @@ export function registerSecretsCommand(program) {
                 process.exit(1);
             }
             const keys = parseSecretNameList(_opts.only);
-            const cred = await resolveVaultCredential();
+            const cred = await resolveVaultCredentialForCapability("secrets:read", "secrets exec");
             const companyUid = cred.kind === "api-key"
                 ? "__api_key__"
                 : await getEntityUid(cred.token, scopeOpts(secrets.opts()));
@@ -1333,7 +1390,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.yellow("stdout is a terminal — values redacted. Use: source <(hq secrets env --only KEY1,KEY2)"));
             }
             const keys = parseSecretNameList(opts.only);
-            const cred = await resolveVaultCredential();
+            const cred = await resolveVaultCredentialForCapability("secrets:read", "secrets env");
             const companyUid = cred.kind === "api-key"
                 ? "__api_key__"
                 : await getEntityUid(cred.token, scopeOpts(secrets.opts()));
@@ -1376,7 +1433,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red("Maximum expiry is 7 days (7d)."));
                 process.exit(1);
             }
-            const token = await requireCognitoTokenForSecrets("secrets");
+            const token = await requireCognitoTokenForSecrets("secrets generate-link", "secrets:write");
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const res = await vaultApiFetch({
                 token,
@@ -1422,11 +1479,10 @@ export function registerSecretsCommand(program) {
             if (!principal) {
                 process.exit(1);
             }
-            const token = await requireCognitoTokenForSecrets("secrets");
-            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
+            const target = await resolveSecretsTarget("secrets:share", "secrets share", secrets.opts());
             const res = await vaultApiFetch({
-                token,
-                path: `/secrets/${encodeURIComponent(companyUid)}/acl/grant`,
+                token: target.token,
+                path: target.aclPath("grant"),
                 method: "POST",
                 body: {
                     path,
@@ -1441,7 +1497,9 @@ export function registerSecretsCommand(program) {
                     console.error(chalk.red("Not authenticated — please run `hq login`"));
                 }
                 else if (res.status === 403) {
-                    console.error(chalk.red("Not authorized to share this secret"));
+                    console.error(chalk.red(target.isApiKey
+                        ? formatApiKeyCapabilityDenial(body, "Not authorized to share this secret")
+                        : "Not authorized to share this secret"));
                 }
                 else if (res.status === 404) {
                     console.error(chalk.red("ACL record not found for this path — has the secret been created?"));
@@ -1479,11 +1537,10 @@ export function registerSecretsCommand(program) {
             if (!principal) {
                 process.exit(1);
             }
-            const token = await requireCognitoTokenForSecrets("secrets");
-            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
+            const target = await resolveSecretsTarget("secrets:share", "secrets unshare", secrets.opts());
             const res = await vaultApiFetch({
-                token,
-                path: `/secrets/${encodeURIComponent(companyUid)}/acl/revoke`,
+                token: target.token,
+                path: target.aclPath("revoke"),
                 method: "POST",
                 body: {
                     path,
@@ -1497,7 +1554,9 @@ export function registerSecretsCommand(program) {
                     console.error(chalk.red("Not authenticated — please run `hq login`"));
                 }
                 else if (res.status === 403) {
-                    console.error(chalk.red("Not authorized to modify this secret's ACL"));
+                    console.error(chalk.red(target.isApiKey
+                        ? formatApiKeyCapabilityDenial(body, "Not authorized to modify this secret's ACL")
+                        : "Not authorized to modify this secret's ACL"));
                 }
                 else if (res.status === 404) {
                     console.log(chalk.green(`Grant already absent for '${path}' / ${describeSecretAclPrincipal(principal)}`));
@@ -1528,12 +1587,11 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red(`Invalid secret path '${path}': must match ^[A-Z][A-Z0-9_]*(/[A-Z][A-Z0-9_]+)*$ (e.g. MY_KEY or PROD/DB_PASSWORD)`));
                 process.exit(1);
             }
-            const token = await requireCognitoTokenForSecrets("secrets");
-            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
+            const target = await resolveSecretsTarget("secrets:share", "secrets acl", secrets.opts());
             const secretPath = path;
             const res = await vaultApiFetch({
-                token,
-                path: `/secrets/${encodeURIComponent(companyUid)}/acl`,
+                token: target.token,
+                path: target.aclPath(),
                 query: { path: secretPath },
             });
             if (!res.ok) {
@@ -1542,7 +1600,9 @@ export function registerSecretsCommand(program) {
                     console.error(chalk.red("Not authenticated — please run `hq login`"));
                 }
                 else if (res.status === 403) {
-                    console.error(chalk.red("Not authorized to view this secret's ACL"));
+                    console.error(chalk.red(target.isApiKey
+                        ? formatApiKeyCapabilityDenial(body, "Not authorized to view this secret's ACL")
+                        : "Not authorized to view this secret's ACL"));
                 }
                 else if (res.status === 404) {
                     console.error(chalk.red(`No ACL record exists for '${path}'`));

package/dist/main.js

@@ -56,6 +56,7 @@ import { registerAgentsCommand } from "./commands/agents.js";
 import { registerOutpostsCommand } from "./commands/outposts.js";
 import { registerBillingCommand } from "./commands/billing.js";
 import { registerDbCommand } from "./commands/db.js";
+import { registerCoreCommands } from "./commands/core.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import { isExpectedUserError } from "./utils/expected-cli-error.js";
@@ -220,6 +221,11 @@ registerOutpostsCommand(program);
 // mint a shareable Stripe card-capture link — the client side of the paid-
 // provisioning gate for agents & Outposts.
 registerBillingCommand(program);
+// HQ scaffold scripts hosted by the CLI (hidden group — `hq core …`). Not a
+// public surface: every entry is invoked by an HQ skill, hook, or forwarder, and
+// the source-root entries are maintainer tools that must never touch a live
+// install. Registered from a manifest in the module, not wired per script here.
+registerCoreCommands(program);
 program.hook("preAction", async () => {
     await emitCliSessionStarted();
 });

package/dist/utils/api-key-command-gate.d.ts

@@ -0,0 +1,45 @@
+import type { Command } from "commander";
+import { type ApiKeyCapability } from "./resolve-vault-credential.js";
+/**
+ * Capability gate for a whole command group.
+ *
+ * Command groups such as `hq files`, `hq agents`, and `hq members` call
+ * `ensureCognitoToken()` from many subcommand actions. Without a gate, a
+ * caller who exported `HQ_API_KEY` for CI silently gets their cached Cognito
+ * session instead — the key's capability scope is ignored, which is the exact
+ * fail-open the capability model exists to prevent. One inherited `preAction`
+ * hook on the group covers every current and future subcommand rather than
+ * every `ensureCognitoToken()` call site.
+ */
+/**
+ * A capability that names the surface correctly but whose specific route has
+ * no `/v1/keys` parallel in hq-pro — e.g. `hq files acl` is a `files:read`
+ * shape, yet only `/files/{companyUid}/acl` (Cognito-only) serves it. The gate
+ * still names the capability so the message explains WHY the surface exists,
+ * and refuses because the wire does not.
+ */
+export interface ApiKeyUnroutedCapability {
+    capability: ApiKeyCapability;
+    routeAvailable: false;
+}
+/** `null` = no capability governs the surface at all. */
+export type ApiKeyCapabilityRule = ApiKeyCapability | null | ApiKeyUnroutedCapability;
+export interface ApiKeyCapabilityRules {
+    /** Rule for subcommands with no specific override. */
+    default: ApiKeyCapabilityRule;
+    /**
+     * Overrides keyed by the subcommand path RELATIVE to the gated group, e.g.
+     * `share` for `hq files share`, `policy get` for `hq secrets policy get`.
+     */
+    bySubcommand?: Record<string, ApiKeyCapabilityRule>;
+}
+/** Full user-facing command path, e.g. `hq files share`. */
+export declare function commandLabel(command: Command): string;
+export declare function capabilityForAction(group: Command, actionCommand: Command, rules: ApiKeyCapabilityRules): ApiKeyCapabilityRule;
+/**
+ * Attach the capability gate to `group`. Commander runs `preAction` hooks
+ * collected from the actioned command AND its ancestors, so one hook here
+ * fires for every nested subcommand.
+ */
+export declare function gateApiKeyCapabilities(group: Command, rules: ApiKeyCapabilityRules): void;
+//# sourceMappingURL=api-key-command-gate.d.ts.map

package/dist/utils/api-key-command-gate.js

@@ -0,0 +1,51 @@
+import { requireApiKeyCapability, } from "./resolve-vault-credential.js";
+/** Full user-facing command path, e.g. `hq files share`. */
+export function commandLabel(command) {
+    const parts = [];
+    let current = command;
+    while (current) {
+        const name = current.name();
+        if (name)
+            parts.unshift(name);
+        current = current.parent ?? undefined;
+    }
+    if (parts[0] !== "hq")
+        parts.unshift("hq");
+    return parts.join(" ");
+}
+/** Subcommand path relative to `group` (empty when `command` IS the group). */
+function relativePath(group, command) {
+    const parts = [];
+    let current = command;
+    while (current && current !== group) {
+        const name = current.name();
+        if (name)
+            parts.unshift(name);
+        current = current.parent ?? undefined;
+    }
+    return parts.join(" ");
+}
+export function capabilityForAction(group, actionCommand, rules) {
+    const path = relativePath(group, actionCommand);
+    const override = rules.bySubcommand?.[path];
+    return override !== undefined ? override : rules.default;
+}
+/**
+ * Attach the capability gate to `group`. Commander runs `preAction` hooks
+ * collected from the actioned command AND its ancestors, so one hook here
+ * fires for every nested subcommand.
+ */
+export function gateApiKeyCapabilities(group, rules) {
+    group.hook("preAction", (_thisCommand, actionCommand) => {
+        const rule = capabilityForAction(group, actionCommand, rules);
+        const label = commandLabel(actionCommand);
+        if (rule !== null && typeof rule === "object") {
+            requireApiKeyCapability(rule.capability, label, {
+                routeAvailable: false,
+            });
+            return;
+        }
+        requireApiKeyCapability(rule, label);
+    });
+}
+//# sourceMappingURL=api-key-command-gate.js.map

package/dist/utils/hq-roots.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Root resolution for CLI-hosted HQ scaffold code.
+ *
+ * When shell that used to live inside the HQ scaffold moves into this npm
+ * package, it loses the one thing it relied on: `BASH_SOURCE`/`$0` pointed at
+ * the user's live HQ tree, so "where am I" and "where is HQ" were the same
+ * answer. Inside a globally installed package they are three different answers,
+ * and conflating any two of them silently corrupts the wrong tree.
+ *
+ *   liveRoot    The user's HQ installation — companies/, workspace/, personal/,
+ *               the installed .claude/ and core/. This is runtime state. Hidden
+ *               runtime commands operate here.
+ *
+ *   packageRoot This npm package's own directory, where bundled scaffold assets
+ *               ship. Read-only in practice: a global install may sit in a
+ *               root-owned prefix. NEVER usable as liveRoot.
+ *
+ * There is deliberately no third "source root". Release-source tooling — the
+ * linters, generators, and validators that rewrite checked-in artifacts — stays
+ * scaffold-owned, so nothing here ever needs to resolve an hq-core checkout. See
+ * the scaffold-vs-cli-code-ownership policy for why.
+ *
+ * The invariant that matters most: `resolveLiveRoot` never consults
+ * `import.meta.url`. A relocated script asking "where is HQ" must get the live
+ * tree, not the package it happens to be bundled in.
+ */
+/** Where bundled scaffold assets live, relative to the package root. */
+export declare const BUNDLED_ASSET_DIR: string;
+/**
+ * Does this directory look like an HQ tree root?
+ *
+ * `companies/` is the load-bearing marker — it is the source of truth for
+ * tenants and exists in every real install. The second clause tolerates the
+ * three shapes a tree can legitimately be in: a full install, a scaffold
+ * checkout without a personal overlay, and a personal-only overlay.
+ */
+export declare function isHqRoot(dir: string): boolean;
+/**
+ * This package's installed root — the directory holding its `package.json`.
+ *
+ * Walks up from the compiled module (`dist/utils/hq-roots.js`) until it finds a
+ * `package.json` whose name matches, rather than hard-coding `..` hops, so the
+ * answer survives a change in output layout.
+ */
+export declare function packageRoot(): string;
+/** Reset the memoized package root. Tests only. */
+export declare function __resetPackageRootCache(): void;
+export type LiveRootOptions = {
+    /** Explicit `--hq-root` value. Highest precedence. */
+    hqRoot?: string;
+    /** Start the walk-up here instead of `process.cwd()`. Tests only. */
+    cwd?: string;
+    /** Environment to read. Tests only. */
+    env?: NodeJS.ProcessEnv;
+};
+/**
+ * Resolve the user's live HQ installation.
+ *
+ * Precedence: `--hq-root` → `HQ_ROOT` → `CLAUDE_PROJECT_DIR` → walk up from cwd.
+ *
+ * ## An explicit root is trusted; a discovered one must be recognized
+ *
+ * The FIRST explicit candidate present wins outright — there is no fall-through
+ * past it, because silently operating on a different tree than the caller named
+ * is the worst available outcome.
+ *
+ * That explicit candidate is checked only for the two things that are always
+ * wrong: it must be a directory, and it must not be inside {@link packageRoot}
+ * (that is this package, not anyone's HQ). It is deliberately NOT required to
+ * satisfy {@link isHqRoot}.
+ *
+ * Requiring markers here was tried and was wrong: the scripts these roots feed
+ * accepted any `HQ_ROOT` before they moved, and several callers legitimately pass
+ * a minimal tree — e.g. `rebuild-threads-index` against a fixture holding nothing
+ * but `workspace/threads/`. Enforcing markers on an explicit value turned a
+ * relocation into a silent contract change and broke those callers.
+ *
+ * The cwd walk is the opposite case: there the marker check is the only thing
+ * that can identify a root at all, so it stays mandatory.
+ */
+export declare function resolveLiveRoot(opts?: LiveRootOptions): string;
+/**
+ * Absolute path to a scaffold asset bundled in this package.
+ *
+ * Refuses to resolve outside the asset directory so a manifest entry can never
+ * be coaxed into executing an arbitrary path, and fails loudly when the asset
+ * is missing — an absent asset means the packlist dropped it, which is a
+ * packaging bug worth surfacing rather than a runtime fallback.
+ */
+export declare function resolveBundledAsset(relativePath: string): string;
+//# sourceMappingURL=hq-roots.d.ts.map