@indigoai-us/hq-cli 5.345.85 → 5.345.86

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [5.345.86] — 2026-10-11
+- New `hq scan secrets`: an offline secret scanner for the pre-commit gate. It
+  checks the staged changes (or given files) against the gitleaks default rule
+  set, vendored from gitleaks v8.30.1 under its MIT license, plus HQ's own
+  token patterns. It needs no network, account or API quota, and reports the
+  rule, file and line without printing the value. Exit codes: 0 clean, 1
+  possible secret, 2 the scan could not run.
+
 ## [5.345.85] — 2026-10-11
 - Session-start orphan reports and reap leases are keyed by HQ root, report ended-session waiting lanes, and surface the latest completed orphan count in startup context even after a skipped sweep. `hq lanes reap --legacy` also identifies abandoned legacy conduct pool loops and only stops verified process identities when `--stop --reason` is supplied.
 

package/dist/command-catalog.generated.d.ts

@@ -5375,6 +5375,43 @@ export declare const COMMAND_CATALOG: readonly [{
         }];
         readonly subcommands: readonly [];
     }];
+}, {
+    readonly name: "scan";
+    readonly description: "Local, offline scanners";
+    readonly aliases: readonly [];
+    readonly hidden: false;
+    readonly helpOption: true;
+    readonly helpCommand: true;
+    readonly usage: "[options] [command]";
+    readonly helpText: readonly [];
+    readonly arguments: readonly [];
+    readonly options: readonly [];
+    readonly subcommands: readonly [{
+        readonly name: "secrets";
+        readonly description: "Scan staged changes (or files) for secrets; exits 1 on a finding";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly helpOption: true;
+        readonly helpCommand: false;
+        readonly usage: "[options] [files...]";
+        readonly helpText: readonly [];
+        readonly arguments: readonly [{
+            readonly name: "files";
+            readonly required: false;
+            readonly variadic: true;
+            readonly description: "Scan these files instead of the staged changes";
+        }];
+        readonly options: readonly [{
+            readonly flags: "--staged";
+            readonly description: "Scan the staged changes (default when no files are given)";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--json";
+            readonly description: "Print findings as JSON";
+            readonly hidden: false;
+        }];
+        readonly subcommands: readonly [];
+    }];
 }, {
     readonly name: "reindex";
     readonly description: "Surface namespaced skills, materialize legacy knowledge repos, regenerate the workers registry, and trust HQ hooks for Codex, Grok, and Claude Code";

package/dist/command-catalog.generated.js

@@ -6535,6 +6535,51 @@ export const COMMAND_CATALOG = [
             }
         ]
     },
+    {
+        "name": "scan",
+        "description": "Local, offline scanners",
+        "aliases": [],
+        "hidden": false,
+        "helpOption": true,
+        "helpCommand": true,
+        "usage": "[options] [command]",
+        "helpText": [],
+        "arguments": [],
+        "options": [],
+        "subcommands": [
+            {
+                "name": "secrets",
+                "description": "Scan staged changes (or files) for secrets; exits 1 on a finding",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options] [files...]",
+                "helpText": [],
+                "arguments": [
+                    {
+                        "name": "files",
+                        "required": false,
+                        "variadic": true,
+                        "description": "Scan these files instead of the staged changes"
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--staged",
+                        "description": "Scan the staged changes (default when no files are given)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Print findings as JSON",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
+            }
+        ]
+    },
     {
         "name": "reindex",
         "description": "Surface namespaced skills, materialize legacy knowledge repos, regenerate the workers registry, and trust HQ hooks for Codex, Grok, and Claude Code",

package/dist/command-registration-plan.d.ts

@@ -358,6 +358,12 @@ export declare const REGISTRATION_PLAN: readonly [{
     readonly parent: "program";
     readonly module: "./commands/import-scan.js";
     readonly exportName: "registerImportCommand";
+}, {
+    readonly type: "registrar";
+    readonly root: "scan";
+    readonly parent: "program";
+    readonly module: "./commands/scan.js";
+    readonly exportName: "registerScanCommand";
 }, {
     readonly type: "registrar";
     readonly root: "reindex";

package/dist/command-registration-plan.js

@@ -62,6 +62,7 @@ export const REGISTRATION_PLAN = [
     { type: "registrar", root: "signals", parent: "program", module: "./commands/signals.js", exportName: "registerSignalsCommand" },
     { type: "registrar", root: "integrations", parent: "program", module: "./commands/integrations.js", exportName: "registerIntegrationsCommand" },
     { type: "registrar", root: "import", parent: "program", module: "./commands/import-scan.js", exportName: "registerImportCommand" },
+    { type: "registrar", root: "scan", parent: "program", module: "./commands/scan.js", exportName: "registerScanCommand" },
     { type: "registrar", root: "reindex", parent: "program", module: "./commands/reindex.js", exportName: "registerReindexCommand" },
     { type: "registrar", root: "rescue", parent: "program", module: "./commands/rescue.js", exportName: "registerRescueCommand" },
     { type: "registrar", root: "mcp", parent: "program", module: "./commands/mcp-status.js", exportName: "registerMcpCommand" },

package/dist/commands/scan.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `hq scan secrets` — offline secret scanner (the HQ pre-commit gate).
+ *
+ *   hq scan secrets               scan the staged changes of the current repo
+ *   hq scan secrets <file...>     scan whole files instead
+ *   hq scan secrets --json        findings as JSON
+ *
+ * Rules: the vendored gitleaks default rule set (MIT, vendor/gitleaks/) plus
+ * HQ's own token patterns. No network, no account, no quota.
+ *
+ * Exit codes: 0 clean, 1 possible secret found, 2 the scan could not run.
+ * A pre-commit hook blocks on any non-zero exit, so the gate fails closed.
+ * Output names the rule, file and line; secret values are never printed.
+ */
+import { Command } from "commander";
+interface ScanSecretsOptions {
+    json?: boolean;
+    staged?: boolean;
+}
+export declare function runScanSecrets(paths: string[], opts: ScanSecretsOptions, cwd?: string): number;
+export declare function registerScanCommand(program: Command): void;
+export {};
+//# sourceMappingURL=scan.d.ts.map

package/dist/commands/scan.js

@@ -0,0 +1,59 @@
+/**
+ * `hq scan secrets` — offline secret scanner (the HQ pre-commit gate).
+ *
+ *   hq scan secrets               scan the staged changes of the current repo
+ *   hq scan secrets <file...>     scan whole files instead
+ *   hq scan secrets --json        findings as JSON
+ *
+ * Rules: the vendored gitleaks default rule set (MIT, vendor/gitleaks/) plus
+ * HQ's own token patterns. No network, no account, no quota.
+ *
+ * Exit codes: 0 clean, 1 possible secret found, 2 the scan could not run.
+ * A pre-commit hook blocks on any non-zero exit, so the gate fails closed.
+ * Output names the rule, file and line; secret values are never printed.
+ */
+import { ScanInputError, scanFiles, scanStaged } from "../lib/secret-scan/staged.js";
+function report(findings, scope) {
+    if (!findings.length)
+        return;
+    const n = findings.length;
+    process.stderr.write(`HQ secret scan: ${n} possible secret${n === 1 ? "" : "s"} in ${scope} (values hidden)\n`);
+    for (const f of findings) {
+        process.stderr.write(`  ${f.file}:${f.line}  ${f.ruleId}  ${f.description}\n`);
+    }
+    process.stderr.write("\nRemove the secret from the change, then stage it again. Keep real credentials in the HQ vault\n" +
+        "(hq secrets, hq run). A known false positive can carry a `gitleaks:allow` comment on that line.\n");
+}
+export function runScanSecrets(paths, opts, cwd = process.cwd()) {
+    let findings;
+    try {
+        findings = paths.length && !opts.staged ? scanFiles(paths) : scanStaged(cwd);
+    }
+    catch (err) {
+        const msg = err instanceof ScanInputError ? err.message : `scan failed: ${err instanceof Error ? err.message : String(err)}`;
+        if (opts.json)
+            process.stdout.write(`${JSON.stringify({ ok: false, error: msg })}\n`);
+        process.stderr.write(`HQ secret scan: ${msg}\n`);
+        return 2;
+    }
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify({ ok: findings.length === 0, findings })}\n`);
+    }
+    else {
+        report(findings, paths.length && !opts.staged ? "the given files" : "staged changes");
+    }
+    return findings.length ? 1 : 0;
+}
+export function registerScanCommand(program) {
+    const scan = program.command("scan").description("Local, offline scanners");
+    scan
+        .command("secrets")
+        .description("Scan staged changes (or files) for secrets; exits 1 on a finding")
+        .argument("[files...]", "Scan these files instead of the staged changes")
+        .option("--staged", "Scan the staged changes (default when no files are given)")
+        .option("--json", "Print findings as JSON")
+        .action((files, opts) => {
+        process.exitCode = runScanSecrets(files ?? [], opts);
+    });
+}
+//# sourceMappingURL=scan.js.map

package/dist/lib/secret-scan/detect.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Secret detection over text fragments, following gitleaks' detection model:
+ * global path allowlist, per-rule path filter, keyword prefilter, regex match,
+ * secret-group selection, Shannon-entropy floor, allowlists (OR/AND; target
+ * secret, match, or line; stopwords), and the inline `gitleaks:allow` marker.
+ *
+ * Findings carry rule, file and line only. The secret value never leaves this
+ * module.
+ */
+import { type CompiledRuleSet } from "./rules.js";
+import type { SecretFinding } from "./types.js";
+/** Inline markers that suppress a finding on that line. */
+export declare const ALLOW_MARKERS: readonly ["gitleaks:allow", "hq-secret-scan:allow"];
+export interface Fragment {
+    file: string;
+    text: string;
+    /** 1-based line number of the first line of `text` in the file. */
+    startLine: number;
+}
+/** Shannon entropy in bits per character (gitleaks' definition). */
+export declare function shannonEntropy(data: string): number;
+/** True when the global allowlist excludes this path from scanning. */
+export declare function pathIgnored(file: string, rules?: CompiledRuleSet): boolean;
+/** Path-only rules (e.g. a committed .p12 keystore); for binary or whole-file adds. */
+export declare function scanPath(file: string, rules?: CompiledRuleSet): SecretFinding[];
+export declare function scanFragment(frag: Fragment, rules?: CompiledRuleSet): SecretFinding[];
+//# sourceMappingURL=detect.d.ts.map

package/dist/lib/secret-scan/detect.js

@@ -0,0 +1,129 @@
+/**
+ * Secret detection over text fragments, following gitleaks' detection model:
+ * global path allowlist, per-rule path filter, keyword prefilter, regex match,
+ * secret-group selection, Shannon-entropy floor, allowlists (OR/AND; target
+ * secret, match, or line; stopwords), and the inline `gitleaks:allow` marker.
+ *
+ * Findings carry rule, file and line only. The secret value never leaves this
+ * module.
+ */
+import { compiledRules } from "./rules.js";
+/** Inline markers that suppress a finding on that line. */
+export const ALLOW_MARKERS = ["gitleaks:allow", "hq-secret-scan:allow"];
+/** Shannon entropy in bits per character (gitleaks' definition). */
+export function shannonEntropy(data) {
+    if (!data)
+        return 0;
+    const counts = new Map();
+    for (const ch of data)
+        counts.set(ch, (counts.get(ch) ?? 0) + 1);
+    const len = Buffer.byteLength(data, "utf8");
+    let entropy = 0;
+    for (const count of counts.values()) {
+        const freq = count / len;
+        entropy -= freq * Math.log2(freq);
+    }
+    return entropy;
+}
+function allowed(al, c) {
+    const target = al.target === "match" ? c.match : al.target === "line" ? c.line : c.secret;
+    const checks = [];
+    if (al.paths.length)
+        checks.push(al.paths.some((p) => p.test(c.file)));
+    if (al.regexes.length)
+        checks.push(al.regexes.some((r) => r.test(target)));
+    if (al.stopwords.length) {
+        const lower = c.secret.toLowerCase();
+        checks.push(al.stopwords.some((s) => lower.includes(s)));
+    }
+    if (!checks.length)
+        return false;
+    return al.condition === "AND" ? checks.every(Boolean) : checks.some(Boolean);
+}
+function lineBounds(text, start, end) {
+    const from = text.lastIndexOf("\n", start - 1) + 1;
+    const nl = text.indexOf("\n", Math.max(end - 1, start));
+    const to = nl < 0 ? text.length : nl;
+    let offset = 0;
+    for (let i = 0; i < from; i++)
+        if (text.charCodeAt(i) === 10)
+            offset++;
+    return { line: text.slice(from, to), offset };
+}
+/** True when the global allowlist excludes this path from scanning. */
+export function pathIgnored(file, rules = compiledRules()) {
+    return rules.global.paths.some((p) => p.test(file));
+}
+/** Path-only rules (e.g. a committed .p12 keystore); for binary or whole-file adds. */
+export function scanPath(file, rules = compiledRules()) {
+    if (pathIgnored(file, rules))
+        return [];
+    return rules.rules
+        .filter((r) => !r.regex && r.path?.test(file))
+        .map((r) => ({ ruleId: r.id, description: r.description, file, line: 1 }));
+}
+export function scanFragment(frag, rules = compiledRules()) {
+    const { file, text, startLine } = frag;
+    if (!text || pathIgnored(file, rules))
+        return [];
+    const lower = text.toLowerCase();
+    const seen = new Set();
+    const findings = [];
+    for (const rule of rules.rules) {
+        if (!rule.regex)
+            continue;
+        if (rule.path && !rule.path.test(file))
+            continue;
+        if (rule.keywords.length && !rule.keywords.some((k) => lower.includes(k)))
+            continue;
+        const re = rule.regex;
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(text)) !== null) {
+            if (m[0].length === 0) {
+                re.lastIndex++;
+                continue;
+            }
+            let secret = m[0];
+            if (m.length > 1) {
+                if (rule.secretGroup && rule.secretGroup > 0)
+                    secret = m[rule.secretGroup] ?? "";
+                else
+                    secret = m.slice(1).find((g) => g !== undefined && g.length > 0) ?? m[0];
+            }
+            if (!secret)
+                continue;
+            if (rule.entropy !== undefined && rule.entropy !== 0 && shannonEntropy(secret) <= rule.entropy)
+                continue;
+            const { line, offset } = lineBounds(text, m.index, m.index + m[0].length);
+            if (ALLOW_MARKERS.some((mk) => line.includes(mk)))
+                continue;
+            const cand = { file, secret, match: m[0], line };
+            if (allowed(rules.global, cand))
+                continue;
+            if (rule.allowlists.some((al) => allowed(al, cand)))
+                continue;
+            const lineNo = startLine + offset;
+            const key = `${rule.id}:${lineNo}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            findings.push({ ruleId: rule.id, description: rule.description, file, line: lineNo });
+        }
+    }
+    return dedupeByLine(findings).sort((a, b) => a.line - b.line || a.ruleId.localeCompare(b.ruleId));
+}
+/**
+ * One line, one report: when a provider-specific rule fired on a line, drop the
+ * catch-all `generic-api-key` and HQ fallback (`hq-*`) findings for that line,
+ * as gitleaks does for its generic rule.
+ */
+function dedupeByLine(findings) {
+    const fallback = (id) => id === "generic-api-key" || id.startsWith("hq-");
+    const specific = new Set(findings.filter((f) => !fallback(f.ruleId)).map((f) => f.line));
+    const out = findings.filter((f) => !fallback(f.ruleId) || !specific.has(f.line));
+    // Between the two fallbacks, prefer the HQ rule (names the provider).
+    const hqLines = new Set(out.filter((f) => f.ruleId.startsWith("hq-")).map((f) => f.line));
+    return out.filter((f) => f.ruleId !== "generic-api-key" || !hqLines.has(f.line));
+}
+//# sourceMappingURL=detect.js.map

package/dist/lib/secret-scan/gitleaks-rules.generated.d.ts

@@ -0,0 +1,6 @@
+import type { GitleaksConfig } from "./types.js";
+export declare const GITLEAKS_UPSTREAM_VERSION = "v8.30.1";
+/** Upstream license; shipped with the derived rules as MIT requires. */
+export declare const GITLEAKS_LICENSE = "MIT License\n\nCopyright (c) 2019 Zachary Rice\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n";
+export declare const GITLEAKS_CONFIG: GitleaksConfig;
+//# sourceMappingURL=gitleaks-rules.generated.d.ts.map