@indigoai-us/hq-cli 5.38.2 → 5.39.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [5.39.0]
+
+### Added
+
+- **`hq secrets exists <name>` — HEAD existence probe (HQ-4H).** Checks whether a
+  secret exists without fetching or decrypting its value, so optional-credential
+  readers can HEAD-first instead of blind-`GET`ting:
+  `hq secrets exists FOO && hq secrets get FOO --reveal`. A missing secret no
+  longer fires a spurious server-side `Secret not found` Sentry warning (HQ-4H:
+  706 nameless events / 0 users) — a `HEAD` is by contract an expected-absence
+  probe, so a not-found is its normal answer and is not captured. Exit codes are
+  built for shell chaining: `0` present, `1` absent (the normal "no", not an
+  error), `2` real failure (auth/network/permission) so `&&` chains never
+  mistake an outage for "absent and proceed". `--quiet` suppresses the
+  present/absent line. Backed by the new hq-pro `HEAD
+  /secrets/{companyUid}/name/{proxy+}` route. Callers that genuinely *require* a
+  secret keep `GET`ting directly — their 404s still surface.
+
 ## [5.38.2]
 
 ### Fixed

package/dist/commands/secrets.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b75c8495-7e0e-53f8-a0d2-c92a993e6492")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7e988c72-7dae-5ad2-aaa3-2c5b430fa5ae")}catch(e){}}();
 import chalk from "chalk";
 import * as readline from "node:readline";
 import { spawn } from "node:child_process";
@@ -227,6 +227,48 @@ export function registerSecretsCommand(program) {
             process.exit(1);
         }
     });
+    // HQ-4H: existence probe via the HEAD route. Optional-credential readers
+    // should HEAD-first so a missing secret no longer fires a spurious GET-404
+    // Sentry warning server-side: `hq secrets exists FOO && hq secrets get FOO …`.
+    // A HEAD never decrypts or reveals the value.
+    //
+    // Exit codes are designed for shell chaining:
+    //   0 → secret exists (200)
+    //   1 → secret is absent (404) — the normal "no" answer, NOT an error
+    //   2 → a real failure (auth/network/permission) — distinct from absence so
+    //       `&&` chains don't mistake an outage for "absent and proceed"
+    secrets
+        .command("exists <name>")
+        .description("Check whether a secret exists (HEAD; exit 0=present, 1=absent, 2=error)")
+        .option("--quiet", "Suppress the present/absent line (use the exit code only)")
+        .action(async (name, opts) => {
+        try {
+            const token = await ensureCognitoToken();
+            const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
+            const res = await vaultApiFetch({
+                token,
+                method: "HEAD",
+                path: buildSecretNamePath(companyUid, name),
+            });
+            if (res.status === 200) {
+                if (!opts.quiet)
+                    console.log(chalk.green(`exists: ${name}`));
+                process.exit(0);
+            }
+            if (res.status === 404) {
+                if (!opts.quiet)
+                    console.log(chalk.dim(`absent: ${name}`));
+                process.exit(1);
+            }
+            // Any other status (401/403/5xx) is a real failure, not an absence.
+            console.error(chalk.red(`Failed to check secret '${name}': HTTP ${res.status} ${res.statusText}`));
+            process.exit(2);
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(2);
+        }
+    });
     secrets
         .command("list")
         .description("List all secrets for the company (including nested path-based names)")
@@ -712,4 +754,4 @@ export function registerSecretsCommand(program) {
     });
 }
 //# sourceMappingURL=secrets.js.map
-//# debugId=b75c8495-7e0e-53f8-a0d2-c92a993e6492
+//# debugId=7e988c72-7dae-5ad2-aaa3-2c5b430fa5ae

package/package.json

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

package/src/commands/secrets.test.ts

@@ -62,6 +62,71 @@ function buildProgram(): Command {
   return program;
 }
 
+// HQ-4H: `hq secrets exists` — HEAD existence probe with shell-chaining exit
+// codes (0=present, 1=absent, 2=error). process.exit is spied so the command's
+// terminal exit doesn't kill the runner; we assert the code it requested.
+describe("secrets exists (HQ-4H HEAD probe)", () => {
+  let exitSpy: MockInstance<typeof process.exit>;
+
+  beforeEach(() => {
+    // Throw so the command stops at its first process.exit (the real runtime
+    // terminates there). The action's own try/catch re-invokes exit(2) on the
+    // thrown sentinel, so we assert on the FIRST recorded exit code — the one
+    // the command actually intended — not the last.
+    exitSpy = vi.spyOn(process, "exit").mockImplementation((() => {
+      throw new Error("__exit__");
+    }) as never);
+  });
+
+  async function firstExitCode(name: string): Promise<number | undefined> {
+    const program = buildProgram();
+    try {
+      await program.parseAsync(["node", "hq", "secrets", "exists", name]);
+    } catch {
+      // sentinel(s) from the exit spy
+    }
+    return exitSpy.mock.calls[0]?.[0] as number | undefined;
+  }
+
+  it("issues a HEAD and intends exit 0 when the secret exists (200)", async () => {
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      new Response(null, { status: 200 }),
+    );
+
+    const code = await firstExitCode("MY_KEY");
+
+    expect(vaultApiFetch).toHaveBeenCalledWith({
+      token: "test-token",
+      method: "HEAD",
+      path: "/secrets/prs_alice/name/MY_KEY",
+    });
+    expect(code).toBe(0);
+  });
+
+  it("intends exit 1 (absent, not an error) on 404", async () => {
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({ error: "Secret not found", name: "MISSING" }),
+        { status: 404, headers: { "Content-Type": "application/json" } },
+      ),
+    );
+
+    const code = await firstExitCode("MISSING");
+
+    expect(code).toBe(1);
+  });
+
+  it("intends exit 2 (real failure, distinct from absence) on a 5xx", async () => {
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      new Response("boom", { status: 503 }),
+    );
+
+    const code = await firstExitCode("MY_KEY");
+
+    expect(code).toBe(2);
+  });
+});
+
 describe("secrets generate-link", () => {
   it("mints one-time submission links for personal secrets", async () => {
     const program = buildProgram();

package/src/commands/secrets.ts

@@ -294,6 +294,58 @@ export function registerSecretsCommand(program: Command): void {
       }
     });
 
+  // HQ-4H: existence probe via the HEAD route. Optional-credential readers
+  // should HEAD-first so a missing secret no longer fires a spurious GET-404
+  // Sentry warning server-side: `hq secrets exists FOO && hq secrets get FOO …`.
+  // A HEAD never decrypts or reveals the value.
+  //
+  // Exit codes are designed for shell chaining:
+  //   0 → secret exists (200)
+  //   1 → secret is absent (404) — the normal "no" answer, NOT an error
+  //   2 → a real failure (auth/network/permission) — distinct from absence so
+  //       `&&` chains don't mistake an outage for "absent and proceed"
+  secrets
+    .command("exists <name>")
+    .description("Check whether a secret exists (HEAD; exit 0=present, 1=absent, 2=error)")
+    .option("--quiet", "Suppress the present/absent line (use the exit code only)")
+    .action(async (name: string, opts: { quiet?: boolean }) => {
+      try {
+        const token = await ensureCognitoToken();
+        const companyUid = await getEntityUid(
+          token,
+          scopeOpts(secrets.opts()),
+        );
+
+        const res = await vaultApiFetch({
+          token,
+          method: "HEAD",
+          path: buildSecretNamePath(companyUid, name),
+        });
+
+        if (res.status === 200) {
+          if (!opts.quiet) console.log(chalk.green(`exists: ${name}`));
+          process.exit(0);
+        }
+        if (res.status === 404) {
+          if (!opts.quiet) console.log(chalk.dim(`absent: ${name}`));
+          process.exit(1);
+        }
+        // Any other status (401/403/5xx) is a real failure, not an absence.
+        console.error(
+          chalk.red(
+            `Failed to check secret '${name}': HTTP ${res.status} ${res.statusText}`,
+          ),
+        );
+        process.exit(2);
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(2);
+      }
+    });
+
   secrets
     .command("list")
     .description("List all secrets for the company (including nested path-based names)")