@indigoai-us/hq-cli 5.85.3 → 5.86.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [5.86.0]
+
+### Added
+
+- Added `hq search` and `hq index` commands for keyword, semantic, and hybrid
+  search across reconciled QMD collections, with explicit opt-in embedding and
+  package-local QMD resolution. Registered unmanaged collections remain
+  untouched and are reported as `registered (unmanaged)`. (#306)
+
 ## [5.85.3]
 
 ### Changed

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

@@ -0,0 +1,16 @@
+import { Command } from 'commander';
+import { type RunQmdOptions, type SearchCollection, type QmdProcessResult } from '../lib/search-index/index.js';
+export type SearchIndexDependencies = {
+    reconcileCollections: (hqRoot: string) => unknown;
+    deriveCollections: (hqRoot: string) => SearchCollection[];
+    listRegisteredCollections: (hqRoot: string, options?: RunQmdOptions) => Set<string>;
+    resolveQmdBin: () => string;
+    resolveQmdVersion: () => string | undefined;
+    runQmd: (args: string[], options?: RunQmdOptions) => QmdProcessResult;
+};
+/** Incrementally update qmd, embedding only when an operator explicitly asks. */
+export declare function syncSearchIndex(hqRoot: string, embed: boolean, dependencies?: SearchIndexDependencies): void;
+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;
+//# sourceMappingURL=index-cmd.d.ts.map

package/dist/commands/index-cmd.js

@@ -0,0 +1,76 @@
+import { deriveCollections, listRegisteredCollections, reconcileCollections, resolveQmdBin, resolveQmdVersion, runQmd, } from '../lib/search-index/index.js';
+import { findHqRoot } from '../utils/manifest.js';
+const defaults = {
+    reconcileCollections,
+    deriveCollections,
+    listRegisteredCollections,
+    resolveQmdBin,
+    resolveQmdVersion,
+    runQmd,
+};
+/** 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)
+        dependencies.runQmd(['embed'], { cwd: hqRoot });
+}
+function resolveRoot(hqRoot) {
+    return hqRoot ?? findHqRoot();
+}
+export function collectionStatusLines(expected, registered) {
+    const expectedNames = new Set(expected.map((collection) => collection.name));
+    const managed = expected.map((collection) => `${registered.has(collection.name) ? 'registered' : 'missing'}  ${collection.name}  ${collection.path}`);
+    const unmanaged = [...registered]
+        .filter((name) => !expectedNames.has(name))
+        .sort((left, right) => left.localeCompare(right))
+        .map((name) => `registered (unmanaged)  ${name}`);
+    return [...managed, ...unmanaged];
+}
+export function collectionSummary(expected, registered) {
+    const expectedNames = new Set(expected.map((collection) => collection.name));
+    const unmanaged = [...registered].filter((name) => !expectedNames.has(name)).length;
+    return `collections: ${registered.size} registered; ${expected.length} expected; ${unmanaged} unmanaged`;
+}
+export function registerIndexCommand(program, dependencies = defaults) {
+    const index = program.command('index').description('Manage the local HQ search index');
+    index
+        .command('sync')
+        .description('Reconcile collections and incrementally update the qmd index')
+        .option('--embed', 'Also rebuild expensive semantic embeddings')
+        .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)' : ''}.`);
+    });
+    index
+        .command('collections')
+        .description('Show expected and registered qmd collections')
+        .option('--hq-root <path>', 'HQ root to inspect (defaults to auto-detected root)')
+        .action((options) => {
+        const hqRoot = resolveRoot(options.hqRoot);
+        const registered = dependencies.listRegisteredCollections(hqRoot);
+        for (const line of collectionStatusLines(dependencies.deriveCollections(hqRoot), registered))
+            console.log(line);
+    });
+    index
+        .command('status')
+        .description('Show qmd binary, collection, and index status')
+        .option('--hq-root <path>', 'HQ root to inspect (defaults to auto-detected root)')
+        .action((options) => {
+        const hqRoot = resolveRoot(options.hqRoot);
+        const bin = dependencies.resolveQmdBin();
+        const registered = dependencies.listRegisteredCollections(hqRoot, { bin, cwd: hqRoot });
+        const expected = dependencies.deriveCollections(hqRoot);
+        const qmdStatus = dependencies.runQmd(['status'], { bin, cwd: hqRoot });
+        const qmdVersion = dependencies.resolveQmdVersion();
+        console.log(`qmd: ${bin}${qmdVersion ? ` (version ${qmdVersion})` : ''}`);
+        console.log(collectionSummary(expected, registered));
+        if (qmdStatus.stdout)
+            process.stdout.write(qmdStatus.stdout);
+        if (qmdStatus.stderr)
+            process.stderr.write(qmdStatus.stderr);
+    });
+}
+//# sourceMappingURL=index-cmd.js.map

package/dist/commands/search.d.ts

@@ -0,0 +1,12 @@
+import { Command } from 'commander';
+export type SearchMode = 'keyword' | 'semantic' | 'hybrid';
+export type SearchOptions = {
+    mode?: SearchMode;
+    collection?: string;
+    count?: number;
+    json?: boolean;
+};
+export declare function buildSearchArgs(query: string, options?: SearchOptions): string[];
+export declare function buildGetArgs(document: string, options?: Pick<SearchOptions, 'collection'>): string[];
+export declare function registerSearchCommand(program: Command): void;
+//# sourceMappingURL=search.d.ts.map

package/dist/commands/search.js

@@ -0,0 +1,48 @@
+import { runQmd } from '../lib/search-index/index.js';
+export function buildSearchArgs(query, options = {}) {
+    const command = { keyword: 'search', semantic: 'vsearch', hybrid: 'query' }[options.mode ?? 'keyword'];
+    const args = [command, query];
+    if (options.collection)
+        args.push('-c', options.collection);
+    if (options.count !== undefined)
+        args.push('-n', String(options.count));
+    if (options.json)
+        args.push('--json');
+    return args;
+}
+export function buildGetArgs(document, options = {}) {
+    const args = ['get', document];
+    if (options.collection)
+        args.push('-c', options.collection);
+    return args;
+}
+function relay(result) {
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+}
+export function registerSearchCommand(program) {
+    const search = program.command('search').description('Search the local HQ qmd index');
+    search
+        .command('get <document>')
+        .description('Retrieve a qmd document by path or document id')
+        .option('-c, --collection <collection>', 'Restrict retrieval to a collection')
+        .action((document, options) => {
+        relay(runQmd(buildGetArgs(document, options)));
+    });
+    search
+        .command('<query>')
+        .description('Search the local HQ qmd index')
+        .option('--mode <mode>', 'Search mode: keyword, semantic, or hybrid', 'keyword')
+        .option('-c, --collection <collection>', 'Restrict search to a collection')
+        .option('-n, --count <count>', 'Maximum result count', (value) => Number(value))
+        .option('--json', 'Request machine-readable qmd output')
+        .action((query, options) => {
+        if (!['keyword', 'semantic', 'hybrid'].includes(options.mode ?? 'keyword')) {
+            throw new Error(`Unknown search mode '${options.mode}'. Expected keyword, semantic, or hybrid.`);
+        }
+        relay(runQmd(buildSearchArgs(query, options)));
+    });
+}
+//# sourceMappingURL=search.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.86.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",