@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/commands/index-cmd.d.ts

@@ -1,8 +1,12 @@
 import { Command } from 'commander';
 import { type RunQmdOptions, type SearchCollection, type QmdProcessResult } from '../lib/search-index/index.js';
 import { type BackgroundDependencies, type BackgroundResult, type BackgroundStatus } from '../lib/search-index/background.js';
+import { type EmbedLockDependencies } from '../lib/search-index/embed-lock.js';
+import { type LoadGateDependencies } from '../lib/search-index/load-gate.js';
 export type SearchIndexDependencies = {
     reconcileCollections: (hqRoot: string) => unknown;
+    /** Apply the per-document size cap to qmd's config before the update reads anything. */
+    applyIndexSizeLimit: (hqRoot: string) => unknown;
     deriveCollections: (hqRoot: string) => SearchCollection[];
     listRegisteredCollections: (hqRoot: string, options?: RunQmdOptions) => Set<string>;
     resolveQmdBin: () => string;
@@ -11,9 +15,23 @@ export type SearchIndexDependencies = {
     runBackgroundLauncher?: (dependencies: BackgroundDependencies) => BackgroundResult;
     runBackgroundWorker?: (dependencies: BackgroundDependencies) => BackgroundResult | Promise<BackgroundResult>;
     backgroundStatus?: (dependencies: BackgroundDependencies) => BackgroundStatus;
+    /** Test seams for the lock shared by every hq-cli QMD writer. */
+    embedLockDependencies?: EmbedLockDependencies;
+    /** Test seam for the default-off shared lock around the full reindex pass. */
+    singleFlightEnabled?: () => boolean;
+    /** Test seams for the host load gate consulted while the embed lock is held. */
+    loadGateDependencies?: LoadGateDependencies;
+    writeStderr?: (text: string) => void;
+};
+export type SyncSearchIndexResult = {
+    status: 'updated';
+    embedded: boolean;
+} | {
+    status: 'skipped';
+    reason: 'busy' | 'unavailable';
 };
 /** Incrementally update qmd, embedding only when an operator explicitly asks. */
-export declare function syncSearchIndex(hqRoot: string, embed: boolean, dependencies?: SearchIndexDependencies): void;
+export declare function syncSearchIndex(hqRoot: string, embed: boolean, dependencies?: SearchIndexDependencies): SyncSearchIndexResult;
 export declare function collectionStatusLines(expected: SearchCollection[], registered: ReadonlySet<string>): string[];
 export declare function collectionSummary(expected: SearchCollection[], registered: ReadonlySet<string>): string;
 export declare function registerIndexCommand(program: Command, dependencies?: SearchIndexDependencies): void;

package/dist/commands/index-cmd.js

@@ -1,6 +1,10 @@
 import { Option } from 'commander';
-import { deriveCollections, listRegisteredCollections, packageLocalBin, reconcileCollections, resolveQmdBin, resolveQmdVersion, runQmd, } from '../lib/search-index/index.js';
+import { deriveCollections, listRegisteredCollections, packageLocalBin, reconcileCollections, resolveQmdBin, resolveQmdHome, resolveQmdVersion, runQmd, } from '../lib/search-index/index.js';
 import { backgroundStatus, defaultBackgroundDependencies, runBackgroundLauncher, runBackgroundWorker, } from '../lib/search-index/background.js';
+import { defaultEmbedLockDependencies, runWithEmbedLock, } from '../lib/search-index/embed-lock.js';
+import { checkEmbedLoad, defaultLoadGateDependencies, recordSuccessfulEmbed, } from '../lib/search-index/load-gate.js';
+import { applyIndexSizeLimit } from '../lib/search-index/max-doc-bytes.js';
+import { qmdReindexSingleFlightEnabled } from '../lib/search-index/reindex-single-flight-flag.js';
 import { findHqRoot } from '../utils/manifest.js';
 import { QMD_NATIVE_BINDING_REMEDY, isQmdNativeBindingError, } from '../utils/qmd-native-binding-error.js';
 import { isQmdStoreMissingError, qmdStoreMissingMessage, } from '../utils/qmd-store-missing-error.js';
@@ -8,6 +12,7 @@ import { isQmdStoreUnopenableError, qmdStoreUnopenableMessage, } from '../utils/
 import { isQmdWorkdirMissingError, qmdWorkdirMissingMessage, } from '../utils/qmd-workdir-missing-error.js';
 const defaults = {
     reconcileCollections,
+    applyIndexSizeLimit,
     deriveCollections,
     listRegisteredCollections,
     resolveQmdBin,
@@ -19,10 +24,65 @@ const defaults = {
 };
 /** Incrementally update qmd, embedding only when an operator explicitly asks. */
 export function syncSearchIndex(hqRoot, embed, dependencies = defaults) {
-    dependencies.reconcileCollections(hqRoot);
-    dependencies.runQmd(['update'], { cwd: hqRoot });
-    if (embed)
+    const updateIndex = () => {
+        dependencies.reconcileCollections(hqRoot);
+        // Must precede the update: an oversized file is skipped at glob time or not
+        // at all, so capping after the update would still have paid to read it.
+        //
+        // Best-effort, matching the background worker. The cap writes to qmd's config
+        // and to `.hq/`, either of which can be read-only on a locked-down box. An
+        // index that is merely uncapped is far better than no `qmd update` at all.
+        try {
+            dependencies.applyIndexSizeLimit(hqRoot);
+        }
+        catch {
+            /* capping is an optimisation; indexing is the job */
+        }
+        dependencies.runQmd(['update'], { cwd: hqRoot, entryPath: 'index-sync' });
+    };
+    const writeStderr = dependencies.writeStderr ?? ((text) => process.stderr.write(text));
+    const singleFlightEnabled = (dependencies.singleFlightEnabled ?? qmdReindexSingleFlightEnabled)();
+    const lockDependencies = dependencies.embedLockDependencies ?? defaultEmbedLockDependencies();
+    const home = resolveQmdHome(lockDependencies.env);
+    let embedded = false;
+    const runEmbed = () => {
+        const loadGateDependencies = dependencies.loadGateDependencies ?? defaultLoadGateDependencies(lockDependencies.env);
+        const decision = checkEmbedLoad(home, loadGateDependencies);
+        if (decision.action === 'skip') {
+            writeStderr(decision.notice);
+            return 'skipped';
+        }
+        if (decision.forced)
+            writeStderr(decision.notice);
         dependencies.runQmd(['embed'], { cwd: hqRoot });
+        recordSuccessfulEmbed(home, loadGateDependencies);
+        embedded = true;
+        return undefined;
+    };
+    if (singleFlightEnabled) {
+        const outcome = runWithEmbedLock(home, lockDependencies, () => {
+            updateIndex();
+            return embed ? runEmbed() : undefined;
+        });
+        if (outcome === 'busy') {
+            writeStderr('hq: qmd reindex is already running; skipping this pass.\n');
+            return { status: 'skipped', reason: 'busy' };
+        }
+        if (outcome === 'unavailable') {
+            writeStderr('hq: cannot access the qmd reindex lock; skipping this pass.\n');
+            return { status: 'skipped', reason: 'unavailable' };
+        }
+        return { status: 'updated', embedded };
+    }
+    updateIndex();
+    if (!embed)
+        return { status: 'updated', embedded: false };
+    const outcome = runWithEmbedLock(home, lockDependencies, runEmbed);
+    if (outcome === 'busy')
+        writeStderr('hq: qmd embed is already running; skipping this pass.\n');
+    if (outcome === 'unavailable')
+        writeStderr('hq: cannot access the qmd embed lock; skipping this pass.\n');
+    return { status: 'updated', embedded: outcome === 'ran' && embedded };
 }
 function resolveRoot(hqRoot) {
     return hqRoot ?? findHqRoot();
@@ -32,6 +92,7 @@ function makeBackgroundDependencies(hqRoot, dependencies) {
         ...defaultBackgroundDependencies(hqRoot),
         resolveQmdBin: dependencies.resolveQmdBin,
         reconcileCollections: dependencies.reconcileCollections,
+        applyIndexSizeLimit: dependencies.applyIndexSizeLimit,
         runQmd: dependencies.runQmd,
     };
 }
@@ -58,8 +119,10 @@ export function registerIndexCommand(program, dependencies = defaults) {
         .option('--hq-root <path>', 'HQ root to index (defaults to auto-detected root)')
         .action((options) => {
         const hqRoot = resolveRoot(options.hqRoot);
-        syncSearchIndex(hqRoot, options.embed === true);
-        console.log(`Updated search index for ${hqRoot}${options.embed ? ' (including embeddings)' : ''}.`);
+        const result = syncSearchIndex(hqRoot, options.embed === true, dependencies);
+        if (result.status === 'skipped')
+            return;
+        console.log(`Updated search index for ${hqRoot}${result.embedded ? ' (including embeddings)' : ''}.`);
     });
     index
         .command('collections')
@@ -68,7 +131,11 @@ export function registerIndexCommand(program, dependencies = defaults) {
         .action((options) => {
         const hqRoot = resolveRoot(options.hqRoot);
         const registered = dependencies.listRegisteredCollections(hqRoot);
-        for (const line of collectionStatusLines(dependencies.deriveCollections(hqRoot), registered))
+        const expected = dependencies.deriveCollections(hqRoot);
+        const lines = collectionStatusLines(expected, registered);
+        if (lines.length === 0)
+            console.log(collectionSummary(expected, registered));
+        for (const line of lines)
             console.log(line);
     });
     index

package/dist/commands/integrations-api.d.ts

@@ -163,15 +163,15 @@ export interface InstallInput {
     };
 }
 export declare function installIntegration(token: string, companyUid: string, input: InstallInput): Promise<InstallResult>;
-export declare function uninstallIntegration(token: string, companyUid: string, installationId: string): Promise<{
+export declare function uninstallIntegration(token: string, companyUid: string, target: {
     installationId: string;
+} | {
+    connectionId: string;
+}): Promise<{
+    installationId: string | null;
     connectionId: string;
 }>;
-/**
- * Permanently remove a revoked connection tombstone. The admin purge endpoint
- * deliberately accepts only the connection id: it derives the company and
- * enforces owner authorization from the authenticated connection record.
- */
+/** Permanently remove a revoked connection tombstone for one company. */
 export declare function purgeConnection(token: string, companyUid: string, connectionId: string): Promise<{
     connectionId: string;
 }>;
@@ -288,13 +288,18 @@ export interface PendingApproval {
     requestedByName?: string | null;
     createdAt: string;
     expiresAt: string;
+    /** Queue state is present on history rows; older servers may omit it. */
+    status?: string;
+    /** Owner-facing outcome projected by hq-pro for decided rows. */
+    outcome?: string;
 }
 /**
- * Live open-approval list, read from hq-pro's confirm-queue state (not the
- * audit feed). Unlike the audit-derived reconstruction this replaces, a call
- * that was approved/rejected/expired no longer appears here.
+ * Read open approvals from hq-pro's confirm-queue state (not the audit feed).
+ * Pass `includeHistory` to include recently decided rows alongside open ones.
  */
-export declare function fetchPendingApprovals(token: string, companyUid: string): Promise<PendingApproval[]>;
+export declare function fetchPendingApprovals(token: string, companyUid: string, options?: {
+    includeHistory?: boolean;
+}): Promise<PendingApproval[]>;
 export declare function getConnectionAccess(token: string, companyUid: string, connectionId: string): Promise<ConnectionAccess>;
 export declare function mutateConnectionAccess(token: string, companyUid: string, action: "grant" | "revoke", input: {
     connectionId: string;

package/dist/commands/integrations-api.js

@@ -8,7 +8,7 @@
  * is optional and read defensively.
  */
 import { vaultApiFetch } from "../utils/vault-api.js";
-import { raiseForResponse, } from "./integrations-core.js";
+import { IntegrationsCliError, raiseForResponse, } from "./integrations-core.js";
 export async function listCatalog(token, companyUid, opts = {}) {
     const query = {
         companyUid,
@@ -59,37 +59,39 @@ export async function installIntegration(token, companyUid, input) {
         method: "POST",
         body: { companyUid, ...input },
     });
-    if (!res.ok)
-        await raiseForResponse(res, "Failed to connect the app");
+    if (!res.ok) {
+        try {
+            await raiseForResponse(res, "Failed to connect the app");
+        }
+        catch (error) {
+            if (error instanceof IntegrationsCliError &&
+                error.status === 409 &&
+                error.code === "INTEGRATION_FACTORY_INSTALL_IN_PROGRESS") {
+                throw new IntegrationsCliError("An install for this app is already running. Wait for it to finish before trying again.", { expected: true, status: 409, code: error.code });
+            }
+            throw error;
+        }
+    }
     return (await res.json());
 }
-export async function uninstallIntegration(token, companyUid, installationId) {
+export async function uninstallIntegration(token, companyUid, target) {
     const res = await vaultApiFetch({
         token,
         path: "/v1/integrations/factory/uninstall",
         method: "POST",
-        body: { companyUid, installationId },
+        body: { companyUid, ...target },
     });
     if (!res.ok)
         await raiseForResponse(res, "Failed to disconnect the app");
     return (await res.json());
 }
-/**
- * Permanently remove a revoked connection tombstone. The admin purge endpoint
- * deliberately accepts only the connection id: it derives the company and
- * enforces owner authorization from the authenticated connection record.
- */
+/** Permanently remove a revoked connection tombstone for one company. */
 export async function purgeConnection(token, companyUid, connectionId) {
-    // Keep the company in this client's call signature with the other
-    // connection mutations. It is resolved before the target connection so a
-    // caller cannot use a slug from a different company, but the server's purge
-    // contract intentionally takes only connectionId in its body.
-    void companyUid;
     const res = await vaultApiFetch({
         token,
         path: "/v1/integrations/admin/purge",
         method: "POST",
-        body: { connectionId },
+        body: { companyUid, connectionId },
     });
     if (!res.ok)
         await raiseForResponse(res, "Failed to purge the revoked connection");
@@ -146,20 +148,23 @@ export async function setReadSafe(token, companyUid, connectionId, toolName, rea
         await raiseForResponse(res, "Failed to update the tool's read-safe setting");
 }
 /**
- * Live open-approval list, read from hq-pro's confirm-queue state (not the
- * audit feed). Unlike the audit-derived reconstruction this replaces, a call
- * that was approved/rejected/expired no longer appears here.
+ * Read open approvals from hq-pro's confirm-queue state (not the audit feed).
+ * Pass `includeHistory` to include recently decided rows alongside open ones.
  */
-export async function fetchPendingApprovals(token, companyUid) {
+export async function fetchPendingApprovals(token, companyUid, options = {}) {
     const res = await vaultApiFetch({
         token,
         path: "/v1/integrations/factory/pending",
-        query: { companyUid },
+        query: {
+            companyUid,
+            ...(options.includeHistory ? { include: "history" } : {}),
+        },
     });
     if (!res.ok)
         await raiseForResponse(res, "Failed to list pending approvals");
     const body = (await res.json());
-    return body.pending ?? [];
+    const pending = body.pending ?? [];
+    return options.includeHistory ? [...pending, ...(body.history ?? [])] : pending;
 }
 export async function getConnectionAccess(token, companyUid, connectionId) {
     const res = await vaultApiFetch({

package/dist/commands/integrations-connect.d.ts

@@ -17,7 +17,31 @@
  * "key" but is really OAuth-protected still connects on the first try.
  */
 import { Command } from "commander";
+import { consoleOrigin } from "../utils/console-origin.js";
+export { consoleOrigin };
 import type { AdminConnection } from "./integrations-core.js";
+import { type InstallInput } from "./integrations-api.js";
+interface ConnectOptions {
+    company?: string;
+    entryId?: string;
+    mcpUrl?: string;
+    docsUrl?: string;
+    provider?: string;
+    displayName?: string;
+    token?: string;
+    tokenStdin?: boolean;
+    authHeader?: string;
+    auth?: string;
+    browser?: boolean;
+    timeout?: string;
+    json?: boolean;
+    connect?: boolean;
+    clientId?: string;
+    clientSecretStdin?: boolean;
+    scopes?: string;
+    /** Connect again even when this app is already connected. */
+    force?: boolean;
+}
 /**
  * Validate `--auth` against the supported enum, rejecting an unknown value
  * before anything is installed. A finite provider/runtime option must never be
@@ -25,21 +49,19 @@ import type { AdminConnection } from "./integrations-core.js";
  * than fall through to a default.
  */
 export declare function assertAuthMode(value: string | undefined): void;
+/** RFC 7230 token characters accepted for an HTTP field name. */
+export declare function assertAuthHeader(value: string | undefined): void;
 /** Single-quote a value for a copy-pasteable shell command. */
 export declare function shellQuote(value: string): string;
-/**
- * The console that fronts the control plane this CLI is pointed at.
- *
- * A handoff must land on the console for the SAME backend, because that
- * console starts its own OAuth flow against its own backend. Sending a staging
- * session to the production console would connect the app in the wrong place —
- * so when the control plane is overridden and its console cannot be derived,
- * return undefined and say so rather than guess a host.
- *
- * `HQ_CONSOLE_URL` is the explicit override; otherwise the console is the
- * control-plane host with its `hqapi.` prefix removed.
- */
-export declare function consoleOrigin(vaultApiUrl?: string): string | undefined;
+/** Everything the connect verbs need to name one app to hq-pro. */
+interface ConnectTarget {
+    /** Install/OAuth identity fields, exactly as hq-pro expects them. */
+    ref: Pick<InstallInput, "domain" | "query" | "catalogEntryId" | "discoveryReceiptId" | "mcpUrl" | "provider" | "displayName" | "docsUrl">;
+    /** Best-known auth mode before hq-pro is asked; `undefined` = unknown. */
+    authClass?: "none" | "key" | "oauth";
+    /** Human label for prompts and success lines. */
+    label: string;
+}
 /**
  * The console's Integrations page for a company, the console root when the
  * caller never named one (a single-membership session resolves the company
@@ -47,6 +69,22 @@ export declare function consoleOrigin(vaultApiUrl?: string): string | undefined;
  * by slug), or undefined when the console for this control plane is unknown.
  */
 export declare function consoleIntegrationsUrl(companySlug: string | undefined, origin: string | undefined): string | undefined;
+/**
+ * The provider refuses to register HQ automatically. That is recoverable — an
+ * admin registers their own OAuth app with the provider and pastes its
+ * credentials — but only the console can collect them, so say what is needed
+ * and hand the page over rather than restating the refusal and stopping.
+ */
+export declare function bringYourOwnClientHandoff(target: ConnectTarget, opts: ConnectOptions, reason: string, redirectUri?: string): Promise<null>;
+/**
+ * Google issues "Desktop app" and "Web application" OAuth clients with the
+ * same client-id shape, but only a Web application client accepts HQ's hosted
+ * https callback. A Desktop client fails at Google with `redirect_uri_mismatch`
+ * after the user has already opened the browser, so say it up front
+ * (Undrdog, 2026-09-24). The callback is read from the authorize URL hq-pro
+ * built, so the hint always names the URL Google will actually be sent.
+ */
+export declare function googleClientTypeHint(clientId: string, authorizationUrl: string): string | null;
 export declare function findAlreadyConnected(connections: readonly AdminConnection[], app: string): AdminConnection | undefined;
 export declare function registerConnectCommands(integrations: Command): void;
 //# sourceMappingURL=integrations-connect.d.ts.map