@indigoai-us/hq-cli 5.85.3 → 5.87.0

package/dist/lib/search-index/background.js

@@ -0,0 +1,382 @@
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { reconcileCollections as defaultReconcileCollections, resolveQmdBin as defaultResolveQmdBin, runQmd as defaultRunQmd, } from './index.js';
+const LOCK_NAME = 'qmd-reindex-bg.lock';
+const COMPLETE_NAME = 'qmd-reindex-bg.completed';
+function defaultSpawnWorker({ logPath }) {
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    const log = fs.openSync(logPath, 'a');
+    const entry = process.argv[1];
+    if (!entry)
+        throw new Error('Cannot determine hq CLI entrypoint for background worker');
+    const child = spawn(process.execPath, [entry, 'index', 'background', '--worker', '--log', logPath], {
+        detached: true,
+        stdio: ['ignore', log, log],
+    });
+    fs.closeSync(log);
+    child.unref();
+    if (!child.pid)
+        throw new Error('Unable to start qmd background worker');
+    return child.pid;
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Defaults used by the CLI; tests supply every nondeterministic dependency. */
+export function defaultBackgroundDependencies(hqRoot) {
+    return {
+        env: process.env,
+        hqRoot,
+        now: () => Math.floor(Date.now() / 1_000),
+        pid: process.pid,
+        random: () => Math.random().toString(36).slice(2),
+        isProcessAlive: alive,
+        resolveQmdBin: defaultResolveQmdBin,
+        reconcileCollections: defaultReconcileCollections,
+        runQmd: defaultRunQmd,
+        spawnWorker: defaultSpawnWorker,
+    };
+}
+/** Match the shell forwarder's hosted-agent markers before looking up qmd. */
+export function isHostedAgent(env = process.env) {
+    if (env.HQ_QMD_REINDEX_MODE === 'skip-agent' || env.HQ_QMD_REINDEX_MODE === 'skip')
+        return true;
+    if (env.HQ_AGENT_BOX && env.HQ_AGENT_BOX !== '0')
+        return true;
+    try {
+        fs.accessSync('/usr/local/bin/hq-agent-qmd-index', fs.constants.X_OK);
+        return true;
+    }
+    catch { /* probe next marker */ }
+    try {
+        fs.accessSync('/usr/local/lib/hq-agent/qmd-index-user', fs.constants.X_OK);
+        return true;
+    }
+    catch { /* probe next marker */ }
+    return fs.existsSync('/etc/systemd/system/hq-agent-qmd-index.timer')
+        || fs.existsSync('/etc/systemd/system/hq-agent-qmd-index.service')
+        || fs.existsSync('/var/lib/hq-agent');
+}
+function lockRoot(home) {
+    return path.join(home, '.hq', 'locks');
+}
+function lockPath(home) {
+    return path.join(lockRoot(home), LOCK_NAME);
+}
+function completionPath(home) {
+    return path.join(lockRoot(home), COMPLETE_NAME);
+}
+function parseFields(file) {
+    try {
+        return Object.fromEntries(fs.readFileSync(file, 'utf8').split('\n').flatMap((line) => {
+            const index = line.indexOf('=');
+            return index === -1 ? [] : [[line.slice(0, index), line.slice(index + 1)]];
+        }));
+    }
+    catch {
+        return undefined;
+    }
+}
+function readOwner(directory) {
+    const fields = parseFields(path.join(directory, 'owner'));
+    if (!fields || !/^\d+$/.test(fields.pid ?? '') || !/^\d+$/.test(fields.ts ?? '') || !/^[A-Za-z0-9._-]+$/.test(fields.nonce ?? ''))
+        return undefined;
+    return { pid: Number(fields.pid), ts: Number(fields.ts), nonce: fields.nonce };
+}
+function graceSeconds(dependencies) {
+    const value = dependencies.env.QMD_HANDOFF_LOCK_GRACE_SEC;
+    return value && /^\d+$/.test(value) ? Number(value) : 5;
+}
+function dedupeSeconds(dependencies) {
+    const value = dependencies.env.QMD_HANDOFF_DEDUPE_SEC;
+    return value && /^\d+$/.test(value) ? Number(value) : 90;
+}
+function isRecentCompletion(home, dependencies) {
+    const dedupe = dedupeSeconds(dependencies);
+    if (dedupe === 0)
+        return false;
+    const fields = parseFields(completionPath(home));
+    if (!fields || !/^\d+$/.test(fields.ts ?? ''))
+        return false;
+    const age = dependencies.now() - Number(fields.ts);
+    return age >= 0 && age < dedupe;
+}
+function writeCompletion(home, dependencies) {
+    try {
+        fs.writeFileSync(completionPath(home), `ts=${dependencies.now()}\npid=${dependencies.pid}\nmode=raw\n`);
+    }
+    catch {
+        // Completion is a best-effort dedupe hint, never a worker failure.
+    }
+}
+function isOwnerlessLockWithinGrace(directory, dependencies) {
+    try {
+        const age = Math.max(0, dependencies.now() - Math.floor(fs.statSync(directory).mtimeMs / 1_000));
+        return age < graceSeconds(dependencies);
+    }
+    catch {
+        return true;
+    }
+}
+function lockState(directory, dependencies) {
+    if (!fs.existsSync(directory))
+        return 'free';
+    const owner = readOwner(directory);
+    if (owner)
+        return dependencies.isProcessAlive(owner.pid) ? 'held' : 'stale';
+    return isOwnerlessLockWithinGrace(directory, dependencies) ? 'held' : 'stale';
+}
+function generation(directory) {
+    const owner = readOwner(directory);
+    if (owner)
+        return owner.nonce;
+    if (!fs.existsSync(directory))
+        return undefined;
+    return 'empty';
+}
+function removeDirectoryIfEmpty(directory) {
+    try {
+        fs.rmdirSync(directory);
+    }
+    catch { /* another claimant owns it, or it is already gone */ }
+}
+function claimWithinGrace(directory, dependencies) {
+    try {
+        const age = Math.max(0, dependencies.now() - Math.floor(fs.statSync(directory).mtimeMs / 1_000));
+        return age < Math.max(5, graceSeconds(dependencies));
+    }
+    catch {
+        return true;
+    }
+}
+function acquireClaim(home, observedGeneration, dependencies) {
+    const claim = path.join(lockRoot(home), `qmd-reindex-bg.claim.${observedGeneration}`);
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            fs.mkdirSync(claim);
+        }
+        catch {
+            if (attempt === 1 || !recoverAbandonedClaim(claim, dependencies))
+                return undefined;
+            continue;
+        }
+        const claimant = path.join(claim, `c.${dependencies.pid}.${dependencies.random()}`);
+        try {
+            fs.mkdirSync(claimant);
+            fs.writeFileSync(path.join(claimant, 'owner'), `pid=${dependencies.pid}\nts=${dependencies.now()}\n`);
+            return { claim, claimant };
+        }
+        catch {
+            fs.rmSync(claimant, { recursive: true, force: true });
+            removeDirectoryIfEmpty(claim);
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Reclaim only exact dead claimant names, then remove the claim directory if
+ * empty. This mirrors the shell's no-fixed-path-reclaim rule: a peer that has
+ * recreated claim.G with a new marker makes rmdir fail and wins the race.
+ */
+function recoverAbandonedClaim(claim, dependencies) {
+    let entries;
+    try {
+        entries = fs.readdirSync(claim, { withFileTypes: true });
+    }
+    catch {
+        return true;
+    }
+    for (const entry of entries.filter((entry) => entry.name.startsWith('c.'))) {
+        const marker = path.join(claim, entry.name);
+        const fields = parseFields(path.join(marker, 'owner'));
+        const pid = fields && /^\d+$/.test(fields.pid ?? '') ? Number(fields.pid) : undefined;
+        if (pid !== undefined && dependencies.isProcessAlive(pid))
+            return false;
+        if (pid === undefined && claimWithinGrace(claim, dependencies))
+            return false;
+        const abandoned = `${claim}.stale-claim.${dependencies.pid}.${dependencies.random()}`;
+        try {
+            fs.renameSync(marker, abandoned);
+            fs.rmSync(abandoned, { recursive: true, force: true });
+        }
+        catch {
+            return false;
+        }
+    }
+    if (entries.length === 0 && claimWithinGrace(claim, dependencies))
+        return false;
+    removeDirectoryIfEmpty(claim);
+    return !fs.existsSync(claim);
+}
+function createAndPublishLock(home, dependencies) {
+    const directory = lockPath(home);
+    try {
+        fs.mkdirSync(directory);
+    }
+    catch {
+        return false;
+    }
+    const marker = path.join(directory, `acq.${dependencies.pid}.${dependencies.random()}`);
+    try {
+        fs.mkdirSync(marker);
+    }
+    catch {
+        removeDirectoryIfEmpty(directory);
+        return false;
+    }
+    const nonce = `${dependencies.pid}.${dependencies.random()}`;
+    const ownerFile = path.join(directory, 'owner');
+    const temporary = path.join(directory, `.owner.tmp.${dependencies.pid}.${dependencies.random()}`);
+    try {
+        fs.writeFileSync(temporary, `pid=${dependencies.pid}\nts=${dependencies.now()}\nnonce=${nonce}\n`);
+        fs.renameSync(temporary, ownerFile);
+        dependencies.afterOwnerPublish?.(ownerFile);
+        const verified = readOwner(directory);
+        if (!verified || verified.pid !== dependencies.pid || verified.nonce !== nonce)
+            throw new Error('owner publish verification failed');
+        fs.rmSync(marker, { recursive: true, force: true });
+        return true;
+    }
+    catch {
+        // The marker identifies only the directory this process created.  Do not
+        // recursively remove the fixed lock path after a failed publication.
+        fs.rmSync(marker, { recursive: true, force: true });
+        removeDirectoryIfEmpty(directory);
+        return false;
+    }
+}
+function claimAndReclaim(home, dependencies) {
+    const directory = lockPath(home);
+    const observedGeneration = generation(directory);
+    if (!observedGeneration || lockState(directory, dependencies) !== 'stale')
+        return false;
+    const acquired = acquireClaim(home, observedGeneration, dependencies);
+    if (!acquired)
+        return false;
+    try {
+        // Generation fencing: only move exactly the stale generation we observed.
+        if (generation(directory) !== observedGeneration || lockState(directory, dependencies) !== 'stale')
+            return false;
+        const abandoned = `${directory}.stale.${dependencies.pid}.${dependencies.random()}`;
+        fs.renameSync(directory, abandoned);
+        fs.rmSync(abandoned, { recursive: true, force: true });
+        return createAndPublishLock(home, dependencies);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        fs.rmSync(acquired.claimant, { recursive: true, force: true });
+        removeDirectoryIfEmpty(acquired.claim);
+    }
+}
+function acquireLock(home, dependencies) {
+    fs.mkdirSync(lockRoot(home), { recursive: true });
+    return createAndPublishLock(home, dependencies) || claimAndReclaim(home, dependencies);
+}
+function releaseLock(home, dependencies) {
+    const directory = lockPath(home);
+    if (readOwner(directory)?.pid === dependencies.pid)
+        fs.rmSync(directory, { recursive: true, force: true });
+}
+export function installWorkerCleanup(cleanup, processEvents = process, exit = () => undefined) {
+    processEvents.once('exit', cleanup);
+    // Unlike Bash, Node cannot turn a SIGKILL or an already-defaulted signal into
+    // catchable cleanup. SIGINT/SIGTERM are registered here and the CLI's normal
+    // process exit then runs the same idempotent owner release. Exiting prevents
+    // a synchronous pipeline from continuing after it has released ownership.
+    processEvents.once('SIGINT', () => { cleanup(); exit(0); });
+    processEvents.once('SIGTERM', () => { cleanup(); exit(0); });
+}
+/** Start a detached worker; this public entry never owns the qmd pipeline. */
+export function runBackgroundLauncher(dependencies) {
+    if (isHostedAgent(dependencies.env))
+        return { state: 'skipped-agent' };
+    const home = dependencies.env.HOME;
+    if (!home)
+        return { state: 'quiet' };
+    try {
+        dependencies.resolveQmdBin();
+    }
+    catch {
+        return { state: 'skipped' };
+    }
+    const logPath = dependencies.env.QMD_REINDEX_LOG
+        ?? dependencies.env.QMD_HANDOFF_LOG
+        ?? path.join(dependencies.env.HANDOFF_LOG_DIR ?? '/tmp', 'qmd-handoff.log');
+    return { state: 'launched', pid: dependencies.spawnWorker({ logPath }) };
+}
+/** Run the single-flight cleanup → update → embed pipeline in a worker only. */
+export function runBackgroundWorker(dependencies) {
+    if (isHostedAgent(dependencies.env))
+        return { state: 'skipped-agent' };
+    const home = dependencies.env.HOME;
+    if (!home)
+        return { state: 'quiet' };
+    try {
+        dependencies.resolveQmdBin();
+    }
+    catch {
+        return { state: 'skipped' };
+    }
+    if (isRecentCompletion(home, dependencies) || !acquireLock(home, dependencies))
+        return { state: 'busy' };
+    let released = false;
+    const cleanup = () => {
+        if (released)
+            return;
+        released = true;
+        releaseLock(home, dependencies);
+    };
+    installWorkerCleanup(cleanup, process, (code) => process.exit(code));
+    try {
+        if (isRecentCompletion(home, dependencies))
+            return { state: 'busy' };
+        // Collection reconciliation is the existing #306 seam; cleanup/update/embed
+        // retain their shell-script ordering after that policy setup.
+        try {
+            dependencies.reconcileCollections(dependencies.hqRoot);
+        }
+        catch {
+            // The shell worker has no collection-registration step. Keep this #306
+            // integration best-effort so it cannot suppress a later index update.
+        }
+        try {
+            dependencies.runQmd(['cleanup'], { cwd: dependencies.hqRoot });
+        }
+        catch { /* cleanup is intentionally best-effort */ }
+        try {
+            dependencies.runQmd(['update'], { cwd: dependencies.hqRoot });
+        }
+        catch {
+            return { state: 'update-failed' };
+        }
+        try {
+            dependencies.runQmd(['embed'], { cwd: dependencies.hqRoot });
+        }
+        catch { /* a completed embed attempt still permits the completion stamp */ }
+        writeCompletion(home, dependencies);
+        return { state: 'completed' };
+    }
+    finally {
+        cleanup();
+    }
+}
+/** Report the background lock and latest successful completion for `hq index status`. */
+export function backgroundStatus(dependencies) {
+    const home = dependencies.env.HOME;
+    if (!home)
+        return { lock: 'free' };
+    const fields = parseFields(completionPath(home));
+    const completedAt = fields && /^\d+$/.test(fields.ts ?? '') ? Number(fields.ts) : undefined;
+    return { lock: lockState(lockPath(home), dependencies), ...(completedAt === undefined ? {} : { completedAt }) };
+}
+//# sourceMappingURL=background.js.map

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

@@ -0,0 +1,58 @@
+export type QmdProcessResult = {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error?: Error;
+};
+export type QmdProcessRunner = (bin: string, args: string[], options: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}) => QmdProcessResult;
+export declare class QmdBinaryMissingError extends Error {
+    name: string;
+}
+export declare class QmdExitError extends Error {
+    readonly args: string[];
+    readonly status: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    name: string;
+    constructor(message: string, args: string[], status: number | null, stdout: string, stderr: string);
+}
+export declare class QmdCollectionMissingError extends QmdExitError {
+    name: string;
+}
+export type ResolveQmdBinOptions = {
+    env?: Record<string, string | undefined>;
+    isExecutable?: (candidate: string) => boolean;
+    packageBin?: () => string | undefined;
+    pathBin?: () => string | undefined;
+};
+/** Return the pinned package version when qmd is supplied by this CLI. */
+export declare function resolveQmdVersion(): string | undefined;
+/** Resolve qmd without relying on a globally installed copy. */
+export declare function resolveQmdBin(options?: ResolveQmdBinOptions): string;
+export type RunQmdOptions = {
+    bin?: string;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    runner?: QmdProcessRunner;
+};
+/** Run qmd with captured output and typed failures. */
+export declare function runQmd(args: string[], options?: RunQmdOptions): QmdProcessResult;
+export type SearchCollection = {
+    name: string;
+    path: string;
+    mask: string;
+    context: string;
+};
+/** Derive the local qmd collection policy for one HQ tree. */
+export declare function deriveCollections(hqRoot: string): SearchCollection[];
+export type ReconcileCollectionsOptions = {
+    bin?: string;
+    runner?: QmdProcessRunner;
+};
+/** Register expected collections that qmd does not yet know about. */
+export declare function reconcileCollections(hqRoot: string, options?: ReconcileCollectionsOptions): SearchCollection[];
+export declare function listRegisteredCollections(hqRoot: string, options?: RunQmdOptions): Set<string>;
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/search-index/index.js

@@ -0,0 +1,197 @@
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import { createRequire } from 'node:module';
+import * as path from 'node:path';
+const require = createRequire(import.meta.url);
+export class QmdBinaryMissingError extends Error {
+    name = 'QmdBinaryMissingError';
+}
+export class QmdExitError extends Error {
+    args;
+    status;
+    stdout;
+    stderr;
+    name = 'QmdExitError';
+    constructor(message, args, status, stdout, stderr) {
+        super(message);
+        this.args = args;
+        this.status = status;
+        this.stdout = stdout;
+        this.stderr = stderr;
+    }
+}
+export class QmdCollectionMissingError extends QmdExitError {
+    name = 'QmdCollectionMissingError';
+}
+function isExecutable(candidate) {
+    try {
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function packageLocalBin() {
+    try {
+        const packageJson = require.resolve('@tobilu/qmd/package.json');
+        return path.join(path.dirname(packageJson), 'qmd');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Return the pinned package version when qmd is supplied by this CLI. */
+export function resolveQmdVersion() {
+    try {
+        const packageJson = require('@tobilu/qmd/package.json');
+        return typeof packageJson.version === 'string' ? packageJson.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function pathBin() {
+    const paths = (process.env.PATH ?? '').split(path.delimiter).filter(Boolean);
+    const names = process.platform === 'win32' ? ['qmd.exe', 'qmd.cmd', 'qmd'] : ['qmd'];
+    for (const directory of paths) {
+        for (const name of names) {
+            const candidate = path.join(directory, name);
+            if (isExecutable(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+/** Resolve qmd without relying on a globally installed copy. */
+export function resolveQmdBin(options = {}) {
+    const env = options.env ?? process.env;
+    const executable = options.isExecutable ?? isExecutable;
+    const probes = [];
+    const override = env.HQ_QMD_BIN;
+    if (override) {
+        if (executable(override))
+            return override;
+        probes.push(`HQ_QMD_BIN (${override})`);
+    }
+    else {
+        probes.push('HQ_QMD_BIN (not set)');
+    }
+    const installed = (options.packageBin ?? packageLocalBin)();
+    if (installed && executable(installed))
+        return installed;
+    probes.push(`package-local @tobilu/qmd (${installed ?? 'not found'})`);
+    const onPath = (options.pathBin ?? pathBin)();
+    if (onPath && executable(onPath))
+        return onPath;
+    probes.push(`qmd on PATH (${onPath ?? 'not found'})`);
+    throw new QmdBinaryMissingError(`Unable to resolve qmd. Probed ${probes.join('; ')}. Install @tobilu/qmd or set HQ_QMD_BIN to an executable qmd binary.`);
+}
+function defaultRunner(bin, args, options) {
+    const result = spawnSync(bin, args, { cwd: options.cwd, env: options.env, encoding: 'utf8' });
+    return {
+        status: result.status,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+        error: result.error,
+    };
+}
+/** Run qmd with captured output and typed failures. */
+export function runQmd(args, options = {}) {
+    const bin = options.bin ?? resolveQmdBin({ env: options.env });
+    const result = (options.runner ?? defaultRunner)(bin, args, { cwd: options.cwd, env: options.env });
+    if (result.error) {
+        throw new QmdBinaryMissingError(`Unable to execute qmd at ${bin}: ${result.error.message}`);
+    }
+    if (result.status === 0)
+        return result;
+    const detail = result.stderr || result.stdout || 'qmd returned no diagnostic output';
+    const message = `qmd ${args.join(' ')} exited with ${result.status ?? 'an unknown status'}: ${detail}`;
+    if (/(?:collection|qmd:\/\/).*(?:not found|does not exist|unknown)|(?:not found|does not exist).*collection/i.test(detail)) {
+        throw new QmdCollectionMissingError(message, args, result.status, result.stdout, result.stderr);
+    }
+    throw new QmdExitError(message, args, result.status, result.stdout, result.stderr);
+}
+function containsIndexedMarkdown(directory) {
+    if (!fs.existsSync(directory))
+        return false;
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        const child = path.join(directory, entry.name);
+        if (entry.isDirectory() && containsIndexedMarkdown(child))
+            return true;
+        if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== 'INDEX.md')
+            return true;
+    }
+    return false;
+}
+function containsProjectSource(directory) {
+    if (!fs.existsSync(directory))
+        return false;
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        const child = path.join(directory, entry.name);
+        if (entry.isDirectory() && containsProjectSource(child))
+            return true;
+        if (entry.isFile() && (entry.name.endsWith('.md') || entry.name.endsWith('.json')))
+            return true;
+    }
+    return false;
+}
+/** Derive the local qmd collection policy for one HQ tree. */
+export function deriveCollections(hqRoot) {
+    const root = path.resolve(hqRoot);
+    const companiesDir = path.join(root, 'companies');
+    const companies = fs.existsSync(companiesDir)
+        ? fs.readdirSync(companiesDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .sort((a, b) => a.name.localeCompare(b.name))
+        : [];
+    const collections = [];
+    for (const entry of companies) {
+        const knowledge = path.join(companiesDir, entry.name, 'knowledge');
+        if (!containsIndexedMarkdown(knowledge))
+            continue;
+        collections.push({
+            name: entry.name,
+            path: knowledge,
+            mask: '**/*.md',
+            context: `Knowledge base for ${entry.name}.`,
+        });
+    }
+    for (const entry of companies) {
+        const projects = path.join(companiesDir, entry.name, 'projects');
+        if (!containsProjectSource(projects))
+            continue;
+        collections.push({
+            name: `${entry.name}-projects`,
+            path: projects,
+            mask: '**/*.{md,json}',
+            context: `Project PRDs and documentation for ${entry.name}.`,
+        });
+    }
+    const personalKnowledge = path.join(root, 'personal', 'knowledge');
+    if (containsIndexedMarkdown(personalKnowledge)) {
+        collections.push({
+            name: 'personal-knowledge',
+            path: personalKnowledge,
+            mask: '**/*.md',
+            context: 'Personal knowledge base (owner overlay).',
+        });
+    }
+    return collections;
+}
+/** Register expected collections that qmd does not yet know about. */
+export function reconcileCollections(hqRoot, options = {}) {
+    const runOptions = { bin: options.bin, runner: options.runner, cwd: hqRoot };
+    const registered = listRegisteredCollections(hqRoot, runOptions);
+    const missing = deriveCollections(hqRoot).filter((collection) => !registered.has(collection.name));
+    for (const collection of missing) {
+        runQmd(['collection', 'add', collection.path, '--name', collection.name, '--mask', collection.mask], runOptions);
+        runQmd(['context', 'add', `qmd://${collection.name}`, collection.context], runOptions);
+    }
+    return missing;
+}
+export function listRegisteredCollections(hqRoot, options = {}) {
+    const result = runQmd(['collection', 'list'], { ...options, cwd: options.cwd ?? hqRoot });
+    return new Set([...result.stdout.matchAll(/qmd:\/\/([^/\s]+)/g)].map((match) => match[1]));
+}
+//# sourceMappingURL=index.js.map

package/dist/main.js

@@ -57,6 +57,8 @@ import { registerOutpostsCommand } from "./commands/outposts.js";
 import { registerBillingCommand } from "./commands/billing.js";
 import { registerDbCommand } from "./commands/db.js";
 import { registerCoreCommands } from "./commands/core.js";
+import { registerSearchCommand } from "./commands/search.js";
+import { registerIndexCommand } from "./commands/index-cmd.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import { isExpectedUserError } from "./utils/expected-cli-error.js";
@@ -228,6 +230,10 @@ registerBillingCommand(program);
 // the source-root entries are maintainer tools that must never touch a live
 // install. Registered from a manifest in the module, not wired per script here.
 registerCoreCommands(program);
+// Local qmd search and index management. Kept distinct from `hq reindex`,
+// which converges scaffold-owned files and hooks rather than search data.
+registerSearchCommand(program);
+registerIndexCommand(program);
 program.hook("preAction", async () => {
     await emitCliSessionStarted();
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.85.3",
+  "version": "5.87.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -32,6 +32,7 @@
     "@indigoai-us/hq-cloud": "^6.14.45",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
+    "@tobilu/qmd": "1.0.7",
     "better-sqlite3": "^12.11.1",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",