@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/lib/report-snapshot.js

@@ -0,0 +1,135 @@
+/**
+ * Report preview snapshot.
+ *
+ * Renders a report's index.html in a browser already installed on this
+ * computer and returns a PNG of the first screen. The snapshot is a nicety:
+ * every failure (no browser, timeout, empty file) returns null and the
+ * publish carries on without a preview.
+ */
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+/** File name of the snapshot inside the published report. */
+export const REPORT_PREVIEW_FILE = "hq-preview.png";
+const REPORT_PREVIEW_WIDTH = 1280;
+const REPORT_PREVIEW_HEIGHT = 720;
+const SNAPSHOT_TIMEOUT_MS = 30_000;
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
+const BROWSER_PATHS = {
+    darwin: [
+        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+        "/Applications/Chromium.app/Contents/MacOS/Chromium",
+        "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+        "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+    ],
+    linux: [
+        "/usr/bin/google-chrome",
+        "/usr/bin/google-chrome-stable",
+        "/usr/bin/chromium",
+        "/usr/bin/chromium-browser",
+        "/snap/bin/chromium",
+    ],
+    win32: [
+        "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+        "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+        "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe",
+    ],
+};
+/** First installed browser that can take a snapshot, or null. */
+export function findSnapshotBrowser(env = process.env, platform = process.platform, exists = fs.existsSync) {
+    const override = (env.HQ_REPORT_BROWSER ?? "").trim();
+    if (override)
+        return exists(override) ? override : null;
+    return (BROWSER_PATHS[platform] ?? []).find((file) => exists(file)) ?? null;
+}
+export function snapshotArgs(indexFile, outFile, profileDir) {
+    return [
+        "--headless=new",
+        "--disable-gpu",
+        "--hide-scrollbars",
+        "--no-first-run",
+        "--no-default-browser-check",
+        "--disable-extensions",
+        `--user-data-dir=${profileDir}`,
+        `--window-size=${REPORT_PREVIEW_WIDTH},${REPORT_PREVIEW_HEIGHT}`,
+        "--virtual-time-budget=5000",
+        `--screenshot=${outFile}`,
+        pathToFileURL(indexFile).toString(),
+    ];
+}
+function stop(child) {
+    if (child.pid === undefined)
+        return;
+    try {
+        // The browser is its own process group, so its helpers stop with it.
+        if (process.platform === "win32")
+            child.kill("SIGKILL");
+        else
+            process.kill(-child.pid, "SIGKILL");
+    }
+    catch {
+        // Already gone.
+    }
+}
+/**
+ * Some browser versions write the snapshot and then never exit. The run is
+ * done when the file is complete, so the browser is stopped at that point
+ * instead of waited on.
+ */
+const runBrowser = (browser, args, outFile, timeoutMs) => new Promise((resolve, reject) => {
+    const child = spawn(browser, args, { stdio: "ignore", detached: process.platform !== "win32" });
+    let lastSize = -1;
+    let settled = false;
+    const finish = (error) => {
+        if (settled)
+            return;
+        settled = true;
+        clearInterval(poll);
+        clearTimeout(limit);
+        stop(child);
+        if (error)
+            reject(error);
+        else
+            resolve();
+    };
+    const poll = setInterval(() => {
+        let size = 0;
+        try {
+            size = fs.statSync(outFile).size;
+        }
+        catch {
+            return;
+        }
+        if (size > 0 && size === lastSize)
+            finish();
+        lastSize = size;
+    }, 250);
+    const limit = setTimeout(() => finish(new Error("The snapshot timed out.")), timeoutMs);
+    child.once("error", (error) => finish(error));
+    child.once("exit", () => finish(fs.existsSync(outFile) ? undefined : new Error("The browser wrote no snapshot.")));
+});
+/** PNG of the report's first screen, or null when one cannot be made. */
+export async function snapshotReport(directory, options = {}) {
+    const browser = options.browser === undefined ? findSnapshotBrowser() : options.browser;
+    if (!browser)
+        return null;
+    const indexFile = path.join(path.resolve(directory), "index.html");
+    if (!fs.existsSync(indexFile))
+        return null;
+    const work = fs.mkdtempSync(path.join(os.tmpdir(), "hq-report-preview-"));
+    try {
+        const outFile = path.join(work, REPORT_PREVIEW_FILE);
+        await (options.run ?? runBrowser)(browser, snapshotArgs(indexFile, outFile, path.join(work, "profile")), outFile, SNAPSHOT_TIMEOUT_MS);
+        const bytes = fs.readFileSync(outFile);
+        return bytes.subarray(0, 4).equals(PNG_MAGIC) ? bytes : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        fs.rmSync(work, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=report-snapshot.js.map

package/dist/lib/report-templates.d.ts

@@ -0,0 +1,9 @@
+export type ReportTemplate = {
+    name: string;
+    path: string;
+    body: string;
+};
+export declare function listReportTemplates(root?: string): ReportTemplate[];
+/** Verbatim runbook. Callers substitute `<reportId>` when the id is known. */
+export declare function loadUpdateReportRunbook(root?: string): string;
+//# sourceMappingURL=report-templates.d.ts.map

package/dist/lib/report-templates.js

@@ -0,0 +1,21 @@
+/** Report templates and the update-report runbook shipped with hq-cli. */
+import { readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+export function listReportTemplates(root = PACKAGE_ROOT) {
+    const dir = path.join(root, "templates", "reports");
+    return readdirSync(dir)
+        .filter((name) => name.endsWith(".md"))
+        .sort()
+        .map((file) => ({
+        name: file.slice(0, -3),
+        path: path.posix.join("templates", "reports", file),
+        body: readFileSync(path.join(dir, file), "utf8"),
+    }));
+}
+/** Verbatim runbook. Callers substitute `<reportId>` when the id is known. */
+export function loadUpdateReportRunbook(root = PACKAGE_ROOT) {
+    return readFileSync(path.join(root, "templates", "runbooks", "update-report.md"), "utf8");
+}
+//# sourceMappingURL=report-templates.js.map

package/dist/lib/scaffold-cli-floor.d.ts

@@ -0,0 +1,8 @@
+export type ScaffoldCliFloorComparison = {
+    status: "pass" | "fail" | "warn" | "skip";
+    message: string;
+    remediation?: string;
+};
+/** Compare an installed CLI version with the scaffold's supported floor. */
+export declare function compareScaffoldCliFloor(required: unknown, currentVersion: string): ScaffoldCliFloorComparison;
+//# sourceMappingURL=scaffold-cli-floor.d.ts.map

package/dist/lib/scaffold-cli-floor.js

@@ -0,0 +1,50 @@
+import semver from "semver";
+const SCAFFOLD_CLI_UPGRADE_COMMAND = "npm install -g @indigoai-us/hq-cli@latest";
+const MINIMUM_VERSION_RANGE = /^>=(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+/** Compare an installed CLI version with the scaffold's supported floor. */
+export function compareScaffoldCliFloor(required, currentVersion) {
+    if (required === undefined) {
+        return {
+            status: "skip",
+            message: "No requiresHqCli floor is declared.",
+        };
+    }
+    const renderedRequired = renderValue(required);
+    if (typeof required !== "string" ||
+        !MINIMUM_VERSION_RANGE.test(required) ||
+        !semver.validRange(required)) {
+        return {
+            status: "warn",
+            message: `requiresHqCli has unsupported value ${renderedRequired}; expected a range in the form \">=X.Y.Z\".`,
+        };
+    }
+    if (!semver.valid(currentVersion)) {
+        return {
+            status: "warn",
+            message: `The running hq-cli version ${renderValue(currentVersion)} is not valid SemVer, so the scaffold CLI floor could not be checked.`,
+        };
+    }
+    if (semver.satisfies(currentVersion, required, { includePrerelease: true })) {
+        return {
+            status: "pass",
+            message: `hq-cli ${currentVersion} satisfies the scaffold requirement ${required}.`,
+        };
+    }
+    const minimum = required.slice(2);
+    return {
+        status: "fail",
+        message: `This scaffold requires hq-cli >= ${minimum} (found ${currentVersion}).`,
+        remediation: SCAFFOLD_CLI_UPGRADE_COMMAND,
+    };
+}
+function renderValue(value) {
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=scaffold-cli-floor.js.map

package/dist/lib/scan-packages/index.d.ts

@@ -1,3 +1,4 @@
+import type { PackContributeKey } from '../../types.js';
 type Logger = (message: string) => void;
 export interface ScanPackagesOptions {
     quiet?: boolean;
@@ -7,6 +8,7 @@ export interface ScanPackagesOptions {
 export interface ScanPackagesResult {
     status: 0 | 1;
 }
+export declare function readContributes(manifest: string): Partial<Record<PackContributeKey, string[]>>;
 /** Wire installed pack contributions into their table-declared host locations. */
 export declare function scanPackages(hqRoot: string, options?: ScanPackagesOptions): ScanPackagesResult;
 export {};

package/dist/lib/scan-packages/index.js

@@ -3,6 +3,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from 'js-yaml';
 import { contributionLinks } from '../../utils/pack-contributions.js';
+import { CONTRIBUTION_TABLE } from '../../utils/contribution-table.js';
 function isDirectory(target) { try {
     return fs.statSync(target).isDirectory();
 }
@@ -17,7 +18,7 @@ catch {
     return false;
 } }
 function normalized(relative) { return relative.replaceAll(path.sep, '/'); }
-function readContributes(manifest) {
+export function readContributes(manifest) {
     // This deliberately mirrors the staging script's shallow awk grammar rather
     // than accepting YAML forms the legacy ABI never recognized (notably a
     // non-empty inline list). Mapping remains single-sourced in
@@ -140,19 +141,61 @@ function workerIdClashes(hqRoot, source) {
     }
     return undefined;
 }
+/**
+ * What a symlink's target resolves to: `present`, `absent`, or the errno of a
+ * lookup that answered neither. Only ENOENT (nothing there) and ENOTDIR (a
+ * path component is not a directory, so the target cannot exist) mean absent.
+ * EACCES, ELOOP and friends mean the question went unanswered, which is not a
+ * licence to destroy what the link points at.
+ */
+function targetLookup(target) {
+    try {
+        fs.statSync(target);
+        return 'present';
+    }
+    catch (error) {
+        const code = error.code;
+        return code === 'ENOENT' || code === 'ENOTDIR' ? 'absent' : code ?? 'unknown error';
+    }
+}
 function ensureSymlink(link, info, warn) {
     if (!existsOrSymlink(link.src)) {
         warn(`payload missing: ${link.src} (declared but not shipped)`);
         return;
     }
+    const relativeSrc = path.relative(path.dirname(link.dst), link.src);
     fs.mkdirSync(path.dirname(link.dst), { recursive: true });
     try {
         const stat = fs.lstatSync(link.dst);
         if (stat.isSymbolicLink()) {
             const existing = fs.readlinkSync(link.dst);
-            if (existing === link.src)
+            // Correct form is relative to the host directory so a tree can move
+            // between machines. An absolute match (this host, pre-relative installer)
+            // is ours and converges. A dangling leftover from another HQ root is
+            // not host content and is rewritten the same way.
+            if (existing === relativeSrc)
+                return;
+            if (existing === link.src) {
+                fs.rmSync(link.dst, { force: true });
+                fs.symlinkSync(relativeSrc, link.dst);
+                info(`relinked ${link.dst} -> ${relativeSrc} (was ${existing})`);
+                return;
+            }
+            // Only a lookup that specifically says "not there" earns a relink.
+            // fs.existsSync also answers false for EACCES, which would read content
+            // this user merely cannot traverse as absent and delete the link to it.
+            const lookup = targetLookup(link.dst);
+            if (lookup === 'absent') {
+                fs.rmSync(link.dst, { force: true });
+                fs.symlinkSync(relativeSrc, link.dst);
+                info(`relinked ${link.dst} -> ${relativeSrc} (was ${existing}, which does not exist here)`);
+                return;
+            }
+            if (lookup !== 'present') {
+                warn(`collision: ${link.dst} points at ${existing}, which could not be checked (${lookup}) — leaving it alone`);
                 return;
-            warn(`collision: ${link.dst} already points at ${existing} (wanted ${link.src}) — skipping`);
+            }
+            warn(`collision: ${link.dst} already points at ${existing} (wanted ${relativeSrc}) — skipping`);
             return;
         }
         warn(`collision: ${link.dst} exists as regular file/dir — host content wins, skipping`);
@@ -162,8 +205,104 @@ function ensureSymlink(link, info, warn) {
         if (error.code !== 'ENOENT')
             throw error;
     }
-    fs.symlinkSync(link.src, link.dst);
-    info(`linked ${link.dst} -> ${link.src}`);
+    fs.symlinkSync(relativeSrc, link.dst);
+    info(`linked ${link.dst} -> ${relativeSrc}`);
+}
+/**
+ * The link text, when `entry` is a symlink whose target is definitively not
+ * there; `undefined` for anything else — a real file or directory, a link that
+ * resolves, or a lookup that failed for a reason other than absence.
+ */
+function danglingLinkTarget(entry) {
+    let link;
+    try {
+        if (!fs.lstatSync(entry).isSymbolicLink())
+            return undefined;
+        link = fs.readlinkSync(entry);
+    }
+    catch {
+        return undefined;
+    }
+    return targetLookup(entry) === 'absent' ? link : undefined;
+}
+/** Host directories the table routes symlinks into, HQ-root relative. */
+function symlinkHostRoots() {
+    const roots = new Set();
+    for (const row of Object.values(CONTRIBUTION_TABLE)) {
+        if (row.wire === 'symlink')
+            roots.add(row.host);
+    }
+    return [...roots].sort();
+}
+/**
+ * Remove host symlinks that point into `core/packages/` at a payload that is
+ * no longer there.
+ *
+ * Wiring only ever adds. A contribution a pack stops shipping, or a pack whose
+ * directory is itself a link into a deleted worktree, leaves its host links
+ * pointing at nothing, and nothing removed them — so they accumulated and
+ * warned on every run forever.
+ *
+ * Scoped three ways so this only reaps what the pack system wired:
+ *   - only inside the host roots the contribution table declares,
+ *   - only symlinks whose target resolves inside `core/packages/`,
+ *   - only when the lookup specifically says the target is absent. EACCES and
+ *     friends mean the question went unanswered, which is not a licence to
+ *     delete (same discipline as the relink path).
+ *
+ * A symlinked directory is classified, never descended into: a Dirent reports
+ * it as a symlink rather than a directory, so the walk cannot wander out of
+ * the host roots through one.
+ */
+function reapOrphanedLinks(hqRoot, info, warn) {
+    const packagesRoot = path.join(hqRoot, 'core/packages') + path.sep;
+    for (const hostRelative of symlinkHostRoots()) {
+        const stack = [path.join(hqRoot, hostRelative)];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            let entries;
+            try {
+                entries = fs.readdirSync(current, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+            for (const entry of entries) {
+                const absolute = path.join(current, entry.name);
+                if (entry.isDirectory()) {
+                    stack.push(absolute);
+                    continue;
+                }
+                if (!entry.isSymbolicLink())
+                    continue;
+                let target;
+                try {
+                    target = fs.readlinkSync(absolute);
+                }
+                catch {
+                    continue;
+                }
+                const resolved = path.resolve(path.dirname(absolute), target);
+                if (!resolved.startsWith(packagesRoot))
+                    continue;
+                const lookup = targetLookup(absolute);
+                if (lookup === 'present')
+                    continue;
+                if (lookup !== 'absent') {
+                    warn(`${absolute} points into core/packages at ${resolved}, which could not be checked (${lookup}) — leaving it alone`);
+                    continue;
+                }
+                try {
+                    fs.rmSync(absolute, { force: true });
+                    info(`unwired ${absolute} (its pack payload ${resolved} is gone)`);
+                }
+                catch (error) {
+                    warn(`could not unwire ${absolute} (${error.message})`);
+                }
+            }
+        }
+    }
 }
 /** Wire installed pack contributions into their table-declared host locations. */
 export function scanPackages(hqRoot, options = {}) {
@@ -174,6 +313,9 @@ export function scanPackages(hqRoot, options = {}) {
     const warn = (message) => warnSink(`  [warn] ${message}`);
     const packages = path.join(hqRoot, 'core/packages');
     if (!isDirectory(packages)) {
+        // Still sweep: a packages directory that is gone entirely is exactly when
+        // every link into it is an orphan.
+        reapOrphanedLinks(hqRoot, info, warn);
         info('[scan-packages] no core/packages/ dir; nothing to wire');
         return { status: 0 };
     }
@@ -190,7 +332,24 @@ export function scanPackages(hqRoot, options = {}) {
         for (const name of packageNames) {
             const packDir = path.join(packages, name);
             const manifest = path.join(packDir, 'package.yaml');
-            if (!isDirectory(packDir) || !fs.existsSync(manifest))
+            if (!isDirectory(packDir)) {
+                // A dangling entry in core/packages/ is not a pack and cannot become
+                // one — typically an install from a worktree that was later removed.
+                // Only a symlink to nothing qualifies: a real directory holds real
+                // files whatever its manifest situation, and is left alone.
+                const danglingTarget = danglingLinkTarget(packDir);
+                if (danglingTarget !== undefined) {
+                    try {
+                        fs.rmSync(packDir, { force: true });
+                        info(`[scan-packages] removed ${name}: its payload is gone (was a link to ${danglingTarget})`);
+                    }
+                    catch (error) {
+                        warn(`could not remove the dangling pack entry ${packDir} (${error.message})`);
+                    }
+                }
+                continue;
+            }
+            if (!fs.existsSync(manifest))
                 continue;
             any = true;
             info(`[scan-packages] wiring ${name}`);
@@ -211,6 +370,9 @@ export function scanPackages(hqRoot, options = {}) {
         warnSink(`[scan-packages] error: ${error.message}`);
         return { status: 1 };
     }
+    // After wiring, so anything just created or repointed is present and only
+    // genuine orphans are left to reap.
+    reapOrphanedLinks(hqRoot, info, warn);
     if (!any)
         info('[scan-packages] no hq-pack manifests found in core/packages');
     return { status: 0 };

package/dist/lib/search-index/background.d.ts

@@ -1,7 +1,8 @@
 import { type StdioOptions } from 'node:child_process';
 import { type QmdProcessResult, type RunQmdOptions } from './index.js';
+import { type LoadGateDependencies } from './load-gate.js';
 export type BackgroundResult = {
-    state: 'skipped-agent' | 'skipped' | 'quiet' | 'busy' | 'completed' | 'update-failed' | 'terminated';
+    state: 'skipped-agent' | 'skipped' | 'quiet' | 'busy' | 'deferred' | 'completed' | 'update-failed' | 'terminated';
 } | {
     state: 'launched';
     pid: number;
@@ -15,6 +16,8 @@ export type BackgroundDependencies = {
     isProcessAlive: (pid: number) => boolean;
     resolveQmdBin: () => string;
     reconcileCollections: (hqRoot: string) => unknown;
+    /** Apply the per-document size cap to qmd's config before the update reads anything. */
+    applyIndexSizeLimit: (hqRoot: string) => unknown;
     runQmd: (args: string[], options?: RunQmdOptions) => QmdProcessResult;
     spawnWorker: (options: {
         logPath: string;
@@ -25,6 +28,9 @@ export type BackgroundDependencies = {
     /** Test seams for signal delivery; production uses the real process. */
     processEvents?: Pick<NodeJS.Process, 'once'>;
     exit?: (code: number) => void;
+    /** Test seams for the host load gate consulted immediately before qmd embed. */
+    loadGateDependencies?: LoadGateDependencies;
+    writeStderr?: (text: string) => void;
 };
 export type BackgroundStatus = {
     lock: 'held' | 'stale' | 'free';
@@ -41,6 +47,7 @@ export type SpawnWorkerIo = {
     closeSync: (fd: number) => void;
     spawn: (command: string, args: string[], options: {
         detached: boolean;
+        windowsHide: boolean;
         stdio: StdioOptions;
     }) => {
         pid?: number;