@indigoai-us/hq-cli 5.345.85 → 5.345.87

package/dist/lib/bot/lock.js

@@ -0,0 +1,313 @@
+/**
+ * One writer per bot at a time.
+ *
+ * `hq bot create`, `adopt`, `restore`, `rm` and `set` all change the same
+ * bot's folder, and an adopt also rotates the bot's machine secret. Two of
+ * them running at once for the same bot (the desktop's automatic restore and
+ * its first-run create, a minute after sign-in) used to race on a
+ * check-then-write of bot.json: the loser either threw "already set up on this
+ * computer" or, worse, wrote a credential the winner had already rotated away.
+ *
+ * The lock is a file under the bots folder, `~/.hq/bots/.locks/<name>.lock`,
+ * created with O_CREAT|O_EXCL. It sits beside the bot's folder rather than in
+ * it: a folder that exists only to hold a lock would read as "a different bot
+ * already has this name" to the code that picks a restored bot's folder, and
+ * as "something is left here" to `hq bot rm`. Its body names the holder (pid,
+ * host, start time, a random token), so:
+ *   - a holder whose process is gone, or that has held it for longer than
+ *     {@link BOT_LOCK_STALE_MS}, is reclaimed;
+ *   - release only removes the lock it took (the token must match), so a
+ *     reclaim by another process never makes this process remove someone
+ *     else's lock.
+ *
+ * The lock is re-entrant within one async call chain (AsyncLocalStorage):
+ * create holds it and calls the shared adopt path, which takes it again
+ * without waiting on itself. Two separate chains in one process still
+ * serialize, exactly like two processes.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { botsRoot } from "./paths.js";
+/** Not a valid bot name (it starts with a dot), so no bot can collide with it. */
+export const BOT_LOCKS_DIRNAME = ".locks";
+/** A holder older than this is treated as crashed, whatever its pid says. */
+export const BOT_LOCK_STALE_MS = 10 * 60 * 1000;
+/** How long a second writer waits for the first before giving up. */
+export const BOT_LOCK_WAIT_MS = 3 * 60 * 1000;
+/** A lock file with no readable body yet: its creator may still be writing it. */
+const UNREADABLE_GRACE_MS = 5_000;
+export class BotLockBusyError extends Error {
+    botName;
+    holder;
+    expected = true;
+    constructor(botName, holder) {
+        super(`Another hq bot command is changing "${botName}" right now${holder?.command ? ` (${holder.command})` : ""}. Try again in a moment.`);
+        this.botName = botName;
+        this.holder = holder;
+        this.name = "BotLockBusyError";
+    }
+}
+export function botLockPath(name, root) {
+    return path.join(root ?? botsRoot(), BOT_LOCKS_DIRNAME, `${name}.lock`);
+}
+/** Alive unless the OS says there is no such process. EPERM is a live process we may not signal. */
+function defaultIsPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+function parseHolder(raw) {
+    try {
+        const v = JSON.parse(raw);
+        if (typeof v.pid !== "number" || typeof v.startedAt !== "string" || typeof v.token !== "string")
+            return null;
+        return {
+            pid: v.pid,
+            host: typeof v.host === "string" ? v.host : "",
+            startedAt: v.startedAt,
+            token: v.token,
+            command: typeof v.command === "string" ? v.command : "",
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Why an existing lock may be taken over, or null while its holder is live.
+ * Exported for tests.
+ */
+export function botLockStaleReason(raw, mtimeMs, opts) {
+    const holder = parseHolder(raw);
+    if (!holder) {
+        // Created but not yet written, or torn by a crash. Give a live creator a
+        // moment to finish writing before calling it abandoned.
+        return opts.now - mtimeMs > UNREADABLE_GRACE_MS ? "unreadable lock" : null;
+    }
+    const started = Date.parse(holder.startedAt);
+    if (Number.isNaN(started))
+        return "unreadable start time";
+    if (opts.now - started > opts.staleMs)
+        return `held since ${holder.startedAt}`;
+    // ~/.hq/bots is per machine, so the pid is this machine's. The host name is
+    // not compared: macOS changes it with the network, which would leave a
+    // crashed holder blocking for the whole stale age.
+    if (!opts.isPidAlive(holder.pid))
+        return `holder pid ${holder.pid} has exited`;
+    return null;
+}
+const heldStorage = new AsyncLocalStorage();
+/** Locks this process holds, so a hard exit (process.exit in a failure path) still lets go. */
+const heldByProcess = new Map();
+let exitHookInstalled = false;
+function installExitHook() {
+    if (exitHookInstalled)
+        return;
+    exitHookInstalled = true;
+    process.on("exit", releaseAllHeldBotLocks);
+}
+/**
+ * Let go of every lock this process holds. Runs on process exit, so a command
+ * that ends through process.exit (every `hq bot` failure does) frees its bot
+ * at once instead of leaving it to the stale-holder reclaim.
+ */
+export function releaseAllHeldBotLocks() {
+    for (const [file, token] of [...heldByProcess])
+        releaseFile(file, token);
+}
+function releaseFile(file, token) {
+    // Moved aside before it is judged, so a lock someone else took after
+    // reclaiming ours (a very long hold) is put back rather than deleted.
+    const aside = `${file}.release-${process.pid}-${randomUUID()}`;
+    try {
+        fs.renameSync(file, aside);
+        const raw = fs.readFileSync(aside, "utf8");
+        if (parseHolder(raw)?.token !== token) {
+            try {
+                fs.linkSync(aside, file);
+            }
+            catch {
+                /* a newer holder is already in place */
+            }
+        }
+    }
+    catch {
+        /* already gone, or unreadable: nothing of ours to remove */
+    }
+    fs.rmSync(aside, { force: true });
+    heldByProcess.delete(file);
+    // Leave the bots folder as it was when no lock is held. A concurrent
+    // acquirer that loses its folder here gets ENOENT and makes it again.
+    try {
+        fs.rmdirSync(path.dirname(file));
+    }
+    catch {
+        /* other locks are held, or it is already gone */
+    }
+}
+function tryCreate(file, body) {
+    let fd;
+    try {
+        fd = fs.openSync(file, "wx", 0o600);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "EEXIST")
+            return false;
+        // Windows refuses to open a file that is pending deletion (a release in
+        // progress) with EPERM/EACCES rather than EEXIST: that is contention too.
+        if (process.platform === "win32" && (code === "EPERM" || code === "EACCES"))
+            return false;
+        if (code === "ENOENT") {
+            // The locks folder went away between mkdir and open (a wiped ~/.hq).
+            // Make it again and let the caller retry.
+            fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+            return false;
+        }
+        throw err;
+    }
+    try {
+        fs.writeSync(fd, body);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return true;
+}
+/**
+ * Remove a stale lock, but only the one that was judged stale: it is renamed
+ * aside first, and if what was renamed is not what was read (a new holder got
+ * in between), it is put back.
+ */
+function reclaim(file, staleRaw) {
+    // Another waiter may have reclaimed it and taken its own lock since we read
+    // it: only the lock judged stale is ever moved. Either way the file changed,
+    // so the caller may try again at once.
+    try {
+        if (fs.readFileSync(file, "utf8") !== staleRaw)
+            return true;
+    }
+    catch {
+        return true;
+    }
+    const aside = `${file}.stale-${process.pid}-${randomUUID()}`;
+    try {
+        fs.renameSync(file, aside);
+    }
+    catch (err) {
+        // Gone already (someone else reclaimed or released it): try again. Any
+        // other refusal leaves the stale lock in place: wait before trying again.
+        return err.code === "ENOENT";
+    }
+    let moved = "";
+    try {
+        moved = fs.readFileSync(aside, "utf8");
+    }
+    catch {
+        /* treat as different */
+    }
+    if (moved !== staleRaw) {
+        // A live holder's lock: restore it. link fails if yet another holder now
+        // exists, which still leaves exactly one lock in place.
+        try {
+            fs.linkSync(aside, file);
+        }
+        catch {
+            try {
+                fs.writeFileSync(file, moved, { flag: "wx", mode: 0o600 });
+            }
+            catch {
+                /* another holder is in place */
+            }
+        }
+    }
+    fs.rmSync(aside, { force: true });
+    return true;
+}
+/** Take the bot's lock (waiting for a live holder), run `fn`, and let go. */
+export async function withBotLock(name, fn, opts = {}) {
+    const current = heldStorage.getStore();
+    const depth = current?.names.get(name) ?? 0;
+    if (depth > 0) {
+        current.names.set(name, depth + 1);
+        try {
+            return await fn();
+        }
+        finally {
+            current.names.set(name, depth);
+        }
+    }
+    const file = botLockPath(name, opts.root);
+    const now = opts.now ?? Date.now;
+    const isPidAlive = opts.isPidAlive ?? defaultIsPidAlive;
+    const staleMs = opts.staleMs ?? BOT_LOCK_STALE_MS;
+    const waitMs = opts.waitMs ?? BOT_LOCK_WAIT_MS;
+    const pollMs = opts.pollMs ?? 150;
+    const host = os.hostname();
+    const token = randomUUID();
+    const body = JSON.stringify({
+        pid: process.pid,
+        host,
+        startedAt: new Date(now()).toISOString(),
+        token,
+        command: opts.command ?? "",
+    });
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const deadline = now() + waitMs;
+    let waited = false;
+    let lastHolder = null;
+    for (;;) {
+        if (tryCreate(file, body))
+            break;
+        let raw;
+        let mtimeMs = now();
+        try {
+            raw = fs.readFileSync(file, "utf8");
+            mtimeMs = fs.statSync(file).mtimeMs;
+        }
+        catch {
+            raw = null; // released between our create and our read: just retry
+        }
+        if (raw !== null) {
+            lastHolder = parseHolder(raw);
+            const why = botLockStaleReason(raw, mtimeMs, { now: now(), staleMs, isPidAlive, host });
+            // Retry at once only when the stale lock is really gone. A reclaim that
+            // could not move it (Windows refusing a rename, a read-only folder) falls
+            // through to the deadline and the poll wait, so this never spins.
+            if (why) {
+                opts.onReclaim?.(lastHolder, why);
+                if (reclaim(file, raw))
+                    continue;
+            }
+            if (!waited) {
+                waited = true;
+                opts.onWait?.(lastHolder);
+            }
+        }
+        if (now() >= deadline)
+            throw new BotLockBusyError(name, lastHolder);
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+    installExitHook();
+    heldByProcess.set(file, token);
+    const held = { names: new Map(current?.names ?? []) };
+    held.names.set(name, 1);
+    try {
+        return await heldStorage.run(held, fn);
+    }
+    finally {
+        // Work that `fn` started and left running no longer holds the lock.
+        held.names.set(name, 0);
+        releaseFile(file, token);
+    }
+}
+//# sourceMappingURL=lock.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