@indigoai-us/hq-cli 5.77.10 → 5.77.12

package/dist/utils/resolve-vault-credential.js

@@ -0,0 +1,48 @@
+import { ensureCognitoToken } from "./cognito-session.js";
+/** Vault API keys issued by `hq api-keys create` (hq-pro). */
+export const HQ_API_KEY_PREFIX = "hqk_";
+/**
+ * Raw HQ_API_KEY from the environment, trimmed. Undefined when unset/empty.
+ * Does not validate prefix — use {@link resolveVaultCredential} for that.
+ */
+export function peekHqApiKey() {
+    const raw = process.env.HQ_API_KEY;
+    if (raw === undefined)
+        return undefined;
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/**
+ * Resolve vault auth for CLI commands.
+ *
+ * When `HQ_API_KEY` is set it is authoritative: must be a vault key (`hqk_…`)
+ * and Cognito is never used as a fallback (fail-closed). When unset, uses the
+ * cached Cognito session (interactive login if needed).
+ */
+export async function resolveVaultCredential(options) {
+    const apiKey = peekHqApiKey();
+    if (apiKey !== undefined) {
+        if (!apiKey.startsWith(HQ_API_KEY_PREFIX)) {
+            throw new Error(`HQ_API_KEY must start with '${HQ_API_KEY_PREFIX}' (vault API key). ` +
+                `Got a value that is not a vault key — refusing to fall back to Cognito. ` +
+                `Unset HQ_API_KEY to use your session, or create a key with \`hq api-keys create\`.`);
+        }
+        return { kind: "api-key", token: apiKey };
+    }
+    const token = await ensureCognitoToken({
+        interactive: options?.interactive,
+    });
+    return { kind: "cognito", token };
+}
+/**
+ * Throw when HQ_API_KEY is set but the command only supports Cognito sessions
+ * (list, set, ACL, api-keys admin, etc.).
+ */
+export function assertCognitoOnlyCommand(commandLabel) {
+    if (peekHqApiKey() === undefined)
+        return;
+    throw new Error(`HQ_API_KEY is set; '${commandLabel}' is not supported for API keys. ` +
+        `API keys support scoped secret reads via \`hq secrets get\`, \`hq secrets exec\`, ` +
+        `and \`hq secrets env\`. Unset HQ_API_KEY to use your Cognito session.`);
+}
+//# sourceMappingURL=resolve-vault-credential.js.map

package/package.json

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

package/src/commands/api-keys.test.ts

@@ -126,10 +126,78 @@ describe("hq api-keys create", () => {
       .map((call) => call.map((value) => String(value)).join(" "))
       .join("\n");
     expect(printed).toContain("Store this key now");
-    expect(printed.match(/hqk_test_secret_value/g)?.length ?? 0).toBe(1);
+    expect(printed).toContain("export HQ_API_KEY=");
+    expect(printed).toContain("hq secrets get");
+    // Key value appears in Store line + export line only (not in list metadata).
+    expect(printed.match(/hqk_test_secret_value/g)?.length ?? 0).toBe(2);
     expect(errSpy).not.toHaveBeenCalled();
     expect(exitSpy).not.toHaveBeenCalled();
   });
+
+  it("includes deploy scope when --deploy-app is set", async () => {
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      jsonResponse({
+        apiKey: {
+          keyId: "key_deploy",
+          companyUid: "cmp_acme",
+          name: "Deploy key",
+          scope: {
+            allowedPrefixes: ["CI"],
+            permission: "read",
+            deploy: {
+              apps: ["my-app", "other-app"],
+              capabilities: ["deploy:write"],
+            },
+          },
+          status: "active",
+          createdAt: "2026-06-19T12:00:00.000Z",
+          lastUsedAt: null,
+          expiresAt: null,
+        },
+        key: { value: "hqk_deploy_secret" },
+      }),
+    );
+
+    const program = buildProgram();
+    await program.parseAsync(
+      [
+        "api-keys",
+        "create",
+        "--name",
+        "Deploy key",
+        "--scope",
+        "CI",
+        "--deploy-app",
+        "my-app",
+        "--deploy-app",
+        "other-app",
+      ],
+      { from: "user" },
+    );
+
+    expect(vaultApiFetch).toHaveBeenCalledWith({
+      token: "test-token",
+      path: "/v1/api-keys",
+      method: "POST",
+      body: {
+        companyUid: "cmp_acme",
+        name: "Deploy key",
+        allowedPrefixes: ["CI"],
+        permission: "read",
+        deploy: {
+          apps: ["my-app", "other-app"],
+          capabilities: ["deploy:write"],
+        },
+      },
+    });
+
+    const printed = logSpy.mock.calls
+      .map((call) => call.map((value) => String(value)).join(" "))
+      .join("\n");
+    expect(printed).toContain("Deploy apps:");
+    expect(printed).toContain("my-app, other-app");
+    expect(printed).toContain("hq-deploy API");
+  });
 });
 
 describe("hq api-keys list", () => {
@@ -145,6 +213,10 @@ describe("hq api-keys list", () => {
             scope: {
               allowedPrefixes: ["HQ_PRO/HQ_PROD", "HQ_PRO/HQ_DEV"],
               permission: "read",
+              deploy: {
+                apps: ["preview-app"],
+                capabilities: ["deploy:write"],
+              },
             },
             status: "active",
             createdAt: "2026-06-19T12:00:00.000Z",
@@ -173,9 +245,11 @@ describe("hq api-keys list", () => {
       .map((call) => call.map((value) => String(value)).join(" "))
       .join("\n");
     expect(printed).toContain("KEY ID");
+    expect(printed).toContain("DEPLOY");
     expect(printed).toContain("key_123");
     expect(printed).toContain("CI key");
     expect(printed).toContain("HQ_PRO/HQ_PROD, HQ_PRO/HQ_DEV");
+    expect(printed).toContain("preview-app");
     expect(printed).not.toContain("hqk_should_not_print");
     expect(exitSpy).not.toHaveBeenCalled();
   });

package/src/commands/api-keys.ts

@@ -1,8 +1,14 @@
 import { Command } from "commander";
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { assertCognitoOnlyCommand } from "../utils/resolve-vault-credential.js";
 import { getCompanyUid, vaultApiFetch } from "./secrets.js";
 
+async function requireCognitoForApiKeys(label: string): Promise<string> {
+  assertCognitoOnlyCommand(label);
+  return ensureCognitoToken();
+}
+
 type ApiKeyPermission = "read" | "write" | "admin";
 
 interface ApiKeyMetadata {
@@ -12,6 +18,10 @@ interface ApiKeyMetadata {
   scope: {
     allowedPrefixes: string[];
     permission: ApiKeyPermission;
+    deploy?: {
+      apps: string[];
+      capabilities: string[];
+    };
   };
   status: string;
   createdAt: string;
@@ -42,6 +52,7 @@ interface ApiKeysGroupOptions {
 interface CreateApiKeyOptions {
   name: string;
   scope: string[];
+  deployApp: string[];
   permission: string;
   expires?: string;
 }
@@ -58,6 +69,13 @@ function formatPrefixes(prefixes: string[]): string {
   return prefixes.length > 0 ? prefixes.join(", ") : "-";
 }
 
+function formatDeployApps(
+  deploy?: { apps: string[]; capabilities: string[] },
+): string {
+  if (!deploy?.apps?.length) return "-";
+  return deploy.apps.join(", ");
+}
+
 function parsePermission(value: string): ApiKeyPermission {
   if (value === "read" || value === "write" || value === "admin") {
     return value;
@@ -107,6 +125,7 @@ function renderApiKeysTable(apiKeys: ApiKeyMetadata[]): void {
     name: apiKey.name,
     permission: apiKey.scope.permission,
     prefixes: formatPrefixes(apiKey.scope.allowedPrefixes),
+    deployApps: formatDeployApps(apiKey.scope.deploy),
     status: apiKey.status,
     lastUsedAt: formatMaybe(apiKey.lastUsedAt),
     expiresAt: formatMaybe(apiKey.expiresAt),
@@ -119,6 +138,7 @@ function renderApiKeysTable(apiKeys: ApiKeyMetadata[]): void {
     ...rows.map((row) => row.permission.length),
   );
   const prefixesWidth = Math.max(8, ...rows.map((row) => row.prefixes.length));
+  const deployWidth = Math.max(6, ...rows.map((row) => row.deployApps.length));
   const statusWidth = Math.max(6, ...rows.map((row) => row.status.length));
   const lastUsedWidth = Math.max(
     11,
@@ -134,6 +154,7 @@ function renderApiKeysTable(apiKeys: ApiKeyMetadata[]): void {
     "NAME".padEnd(nameWidth),
     "PERMISSION".padEnd(permissionWidth),
     "PREFIXES".padEnd(prefixesWidth),
+    "DEPLOY".padEnd(deployWidth),
     "STATUS".padEnd(statusWidth),
     "LAST USED".padEnd(lastUsedWidth),
     "EXPIRES".padEnd(expiresWidth),
@@ -147,6 +168,7 @@ function renderApiKeysTable(apiKeys: ApiKeyMetadata[]): void {
         row.name.padEnd(nameWidth),
         row.permission.padEnd(permissionWidth),
         row.prefixes.padEnd(prefixesWidth),
+        row.deployApps.padEnd(deployWidth),
         row.status.padEnd(statusWidth),
         row.lastUsedAt.padEnd(lastUsedWidth),
         row.expiresAt.padEnd(expiresWidth),
@@ -163,32 +185,42 @@ export function registerApiKeysCommand(program: Command): Command {
 
   apiKeys
     .command("create")
-    .description("Create a new API key")
+    .description(
+      "Create a new API key (vault secrets and/or scoped deploy via --deploy-app)",
+    )
     .requiredOption("--name <label>", "Human-readable label for the API key")
     .option(
       "--scope <prefix>",
-      "Allowed prefix (repeatable)",
+      "Allowed secret prefix (repeatable)",
+      collectRepeatedOption,
+      [],
+    )
+    .option(
+      "--deploy-app <id>",
+      "Deploy app id/slug allowed for publish (repeatable)",
       collectRepeatedOption,
       [],
     )
     .option(
       "--permission <level>",
-      "Permission level: read | write | admin",
+      "Secret permission level: read | write | admin (required when --scope is set)",
       "read",
     )
     .option("--expires <ISO8601>", "Optional ISO-8601 expiry timestamp")
     .action(async (opts: CreateApiKeyOptions) => {
       try {
-        if (opts.scope.length === 0) {
+        if (opts.scope.length === 0 && opts.deployApp.length === 0) {
           console.error(
-            chalk.red("Error: at least one --scope <prefix> is required."),
+            chalk.red(
+              "Error: provide at least one --scope <prefix> and/or --deploy-app <id>.",
+            ),
           );
           process.exit(1);
         }
 
         const permission = parsePermission(opts.permission);
         const expiresAt = parseExpires(opts.expires);
-        const token = await ensureCognitoToken();
+        const token = await requireCognitoForApiKeys("api-keys create");
         const companyUid = await getCompanyUid(
           token,
           (apiKeys.opts() as ApiKeysGroupOptions).company,
@@ -201,8 +233,20 @@ export function registerApiKeysCommand(program: Command): Command {
           body: {
             companyUid,
             name: opts.name,
-            allowedPrefixes: opts.scope,
-            permission,
+            ...(opts.scope.length > 0
+              ? { allowedPrefixes: opts.scope, permission }
+              : {}),
+            ...(opts.deployApp.length > 0
+              ? {
+                  deploy: {
+                    apps: opts.deployApp,
+                    capabilities: ["deploy:write"],
+                  },
+                }
+              : {}),
+            ...(opts.scope.length === 0 && opts.deployApp.length > 0
+              ? { permission }
+              : {}),
             ...(expiresAt ? { expiresAt } : {}),
           },
         });
@@ -225,10 +269,42 @@ export function registerApiKeysCommand(program: Command): Command {
         console.log(
           `  Prefixes: ${formatPrefixes(data.apiKey.scope.allowedPrefixes)}`,
         );
+        console.log(
+          `  Deploy apps: ${formatDeployApps(data.apiKey.scope.deploy)}`,
+        );
         console.log(`  Status: ${data.apiKey.status}`);
         console.log(`  Created: ${data.apiKey.createdAt}`);
         console.log(`  Last used: ${formatMaybe(data.apiKey.lastUsedAt)}`);
         console.log(`  Expires: ${formatMaybe(data.apiKey.expiresAt)}`);
+        console.log("");
+        console.log(chalk.bold("Usage"));
+        console.log(
+          "  This key acts as you (Cognito identity), limited to the scopes above.",
+        );
+        console.log("  Export it for automation (never falls back to a session):");
+        console.log(`\n  export HQ_API_KEY='${data.key.value}'\n`);
+        console.log("  Vault secrets:");
+        console.log("    hq secrets get <NAME> --reveal");
+        console.log("    hq secrets exec --only <NAME> -- <command>");
+        console.log(
+          "    Or HTTP: POST /v1/keys/secrets/fetch with Authorization: Bearer <key>",
+        );
+        if (data.apiKey.scope.deploy?.apps?.length) {
+          console.log("  Deploy (scoped apps only):");
+          console.log(
+            "    Authorization: Bearer <key> against the hq-deploy API",
+          );
+          console.log(
+            chalk.dim(
+              "    Cannot change access-mode, password, or mint hqd_ keys.",
+            ),
+          );
+        }
+        console.log(
+          chalk.dim(
+            "  Unsupported under HQ_API_KEY: secrets list/set/share/acl (use a Cognito session).",
+          ),
+        );
       } catch (err) {
         console.error(
           chalk.red("Error:"),
@@ -243,7 +319,7 @@ export function registerApiKeysCommand(program: Command): Command {
     .description("List API keys for a company")
     .action(async () => {
       try {
-        const token = await ensureCognitoToken();
+        const token = await requireCognitoForApiKeys("api-keys list");
         const companyUid = await getCompanyUid(
           token,
           (apiKeys.opts() as ApiKeysGroupOptions).company,
@@ -280,7 +356,7 @@ export function registerApiKeysCommand(program: Command): Command {
     .description("Revoke an API key")
     .action(async (keyId: string) => {
       try {
-        const token = await ensureCognitoToken();
+        const token = await requireCognitoForApiKeys("api-keys revoke");
         const res = await vaultApiFetch({
           token,
           path: `/v1/api-keys/${encodeURIComponent(keyId)}/revoke`,

package/src/commands/members.test.ts

@@ -43,6 +43,7 @@ import {
   listPendingInvites,
   registerMembersCommand,
   resendInvite,
+  resolveRoleChangeTarget,
   resolveRevokeTargetToMembershipKey,
   revokeInvite,
 } from "./members.js";
@@ -1092,7 +1093,22 @@ describe("changeMemberRole", () => {
 
 describe("registerMembersCommand promote", () => {
   it("resolves an email target and promotes to a full-set role the old set-role couldn't (admin)", async () => {
-    fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          members: [
+            {
+              membershipKey: "prs_alice#cmp_acme",
+              personUid: "prs_alice",
+              companyUid: "cmp_acme",
+              role: "member",
+              status: "active",
+              personEmail: "Alice@Example.com",
+            },
+          ],
+        }),
+      )
+      .mockResolvedValueOnce(jsonResponse(200, {}));
     const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
 
     await buildMembersProgram().parseAsync(
@@ -1100,14 +1116,18 @@ describe("registerMembersCommand promote", () => {
       { from: "user" },
     );
 
-    const call = fetchSpy.mock.calls[0];
+    expect(String(fetchSpy.mock.calls[0][0])).toMatch(
+      /\/membership\/company\/cmp_acme$/,
+    );
+    const call = fetchSpy.mock.calls[1];
     expect(String(call[0])).toMatch(/\/membership\/role$/);
     const body = JSON.parse((call[1]?.body as string) ?? "{}");
     expect(body).toEqual({
       companyUid: "cmp_acme",
-      membershipKey: "email:alice@example.com#cmp_acme",
+      membershipKey: "prs_alice#cmp_acme",
       newRole: "admin",
     });
+    expect(body.membershipKey).not.toContain("email:");
     expect(logSpy).toHaveBeenCalledWith(
       expect.stringContaining("Updated role for 'alice@example.com' to admin"),
     );
@@ -1123,6 +1143,43 @@ describe("registerMembersCommand promote", () => {
     );
   });
 
+  it("fails clearly when no active member matches an email and never posts a role change", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { members: [] }));
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    vi.spyOn(process, "exit").mockImplementation(((code?: number) => {
+      throw new Error(`__EXIT__:${code ?? 0}`);
+    }) as never);
+
+    await expect(
+      buildMembersProgram().parseAsync(
+        [
+          "members",
+          "--company",
+          "acme",
+          "promote",
+          "missing@example.com",
+          "admin",
+        ],
+        { from: "user" },
+      ),
+    ).rejects.toThrow("__EXIT__:1");
+
+    const errorOutput = errSpy.mock.calls
+      .flatMap((call) => call.map(String))
+      .join(" ");
+    expect(errorOutput).toContain(
+      "No active member has email 'missing@example.com'",
+    );
+    expect(errorOutput).toContain("hq members list");
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    expect(
+      fetchSpy.mock.calls.some(
+        ([url, init]) =>
+          String(url).endsWith("/membership/role") && init?.method === "POST",
+      ),
+    ).toBe(false);
+  });
+
   it("forwards a personUid target and the guest role (beyond set-role's admin|member cap)", async () => {
     fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
     const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
@@ -1189,6 +1246,141 @@ describe("registerMembersCommand promote", () => {
   });
 });
 
+describe("resolveRoleChangeTarget", () => {
+  it("passes through a full membership key without fetching members", async () => {
+    await expect(
+      resolveRoleChangeTarget(
+        "test-token",
+        "cmp_acme",
+        "prs_alice#cmp_acme",
+      ),
+    ).resolves.toBe("prs_alice#cmp_acme");
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("wraps bare person and agent uids without fetching members", async () => {
+    await expect(
+      resolveRoleChangeTarget("test-token", "cmp_acme", "prs_alice"),
+    ).resolves.toBe("prs_alice#cmp_acme");
+    await expect(
+      resolveRoleChangeTarget("test-token", "cmp_acme", "agt_ops"),
+    ).resolves.toBe("agt_ops#cmp_acme");
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("maps agent machine emails to agt_…#companyUid without fetching members", async () => {
+    await expect(
+      resolveRoleChangeTarget(
+        "test-token",
+        "cmp_acme",
+        "agt-01hxyzabcdefghjkmnpqrstvwx@agents.getindigo.ai",
+      ),
+    ).resolves.toBe("agt_01HXYZABCDEFGHJKMNPQRSTVWX#cmp_acme");
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// registerMembersCommand invite — MEMBERSHIP_ALREADY_EXISTS messaging
+// ---------------------------------------------------------------------------
+
+describe("registerMembersCommand invite 409 messaging", () => {
+  function mockCallerIdentity(): void {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        memberships: [
+          {
+            membershipKey: "prs_admin#cmp_acme",
+            personUid: "prs_admin",
+            companyUid: "cmp_acme",
+            role: "owner",
+            status: "active",
+          },
+        ],
+      }),
+    );
+  }
+
+  it("guides --resend when the conflict is a pending invite", async () => {
+    mockCallerIdentity();
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(409, {
+          error: "Membership already exists",
+          code: "MEMBERSHIP_ALREADY_EXISTS",
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          pending: [
+            {
+              membershipKey: "email:alice@example.com#cmp_acme",
+              inviteeEmail: "alice@example.com",
+              companyUid: "cmp_acme",
+              role: "member",
+              status: "pending",
+              invitedBy: "prs_admin",
+              invitedAt: "2026-05-21T12:00:00Z",
+            },
+          ],
+        }),
+      );
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    await buildMembersProgram().parseAsync(
+      ["members", "--company", "acme", "invite", "Alice@Example.com"],
+      { from: "user" },
+    );
+
+    const output = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(output).toContain("already has a pending invite");
+    expect(output).toContain(
+      "hq members invite alice@example.com --company acme --resend",
+    );
+    expect(output).not.toContain("already a member of this company");
+    expect(errSpy).not.toHaveBeenCalled();
+  });
+
+  it("keeps the already-member note when the conflict is an active member", async () => {
+    mockCallerIdentity();
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(409, {
+          error: "Membership already exists",
+          code: "MEMBERSHIP_ALREADY_EXISTS",
+        }),
+      )
+      .mockResolvedValueOnce(jsonResponse(200, { pending: [] }))
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          members: [
+            {
+              membershipKey: "prs_alice#cmp_acme",
+              personUid: "prs_alice",
+              companyUid: "cmp_acme",
+              role: "member",
+              status: "active",
+              personEmail: "alice@example.com",
+            },
+          ],
+        }),
+      );
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+
+    await buildMembersProgram().parseAsync(
+      ["members", "--company", "acme", "invite", "alice@example.com"],
+      { from: "user" },
+    );
+
+    const output = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(output).toContain("already a member of this company");
+    expect(output).not.toContain("pending invite");
+  });
+});
+
 // ---------------------------------------------------------------------------
 // resolveRevokeTargetToMembershipKey
 // ---------------------------------------------------------------------------