@fredlackey/devutils 0.0.18 → 0.1.0

package/src/commands/search/get.js

@@ -0,0 +1,71 @@
+'use strict';
+
+const shell = require('../../lib/shell');
+const { checkQmd } = require('./qmd');
+
+const meta = {
+  description: 'Retrieve a document by file path or QMD document ID',
+  arguments: [
+    { name: 'target', description: 'File path or document ID (e.g., #abc123)', required: true }
+  ],
+  flags: [
+    { name: 'full', type: 'boolean', description: 'Return the entire document instead of a snippet' },
+    { name: 'line', type: 'number', description: 'Start at a specific line number' },
+    { name: 'max-lines', type: 'number', description: 'Maximum number of lines to return' }
+  ]
+};
+
+/**
+ * Retrieves a document by file path or QMD document ID.
+ * Passes the target through to QMD as-is (QMD handles both
+ * file paths and #id-style document IDs).
+ *
+ * @param {object} args - Parsed CLI arguments { positional, flags }.
+ * @param {object} context - CLI context { output, errors }.
+ */
+async function run(args, context) {
+  // Check for QMD availability first
+  const qmd = checkQmd();
+  if (!qmd.available) {
+    context.errors.throwError(1, qmd.message, 'search');
+    return;
+  }
+
+  const target = args.positional[0];
+
+  if (!target) {
+    context.errors.throwError(400, 'Missing required argument: <target>. Example: dev search get path/to/document.md', 'search');
+    return;
+  }
+
+  // Build the QMD command
+  let cmd = `qmd get "${target}"`;
+
+  if (args.flags.full) {
+    cmd += ' --full';
+  }
+  if (args.flags.line) {
+    cmd += ` --line ${args.flags.line}`;
+  }
+  if (args.flags['max-lines']) {
+    cmd += ` --max-lines ${args.flags['max-lines']}`;
+  }
+
+  // Execute and capture output
+  const result = await shell.exec(cmd);
+
+  if (result.exitCode !== 0) {
+    context.errors.throwError(1, result.stderr || `Document not found: ${target}`, 'search');
+    return;
+  }
+
+  // For get, the output is document content, not search results
+  const output = {
+    target: target,
+    content: result.stdout
+  };
+
+  context.output.out(output);
+}
+
+module.exports = { meta, run };

package/src/commands/search/index-cmd.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const shell = require('../../lib/shell');
+const { checkQmd } = require('./qmd');
+
+const meta = {
+  description: 'Rebuild or update the search index and generate embeddings',
+  arguments: [],
+  flags: [
+    { name: 'force', type: 'boolean', description: 'Re-index everything from scratch (ignores incremental updates)' }
+  ]
+};
+
+/**
+ * Rebuilds or updates the QMD search index.
+ * Triggers re-indexing of all collections and embedding generation.
+ * Use --force to ignore incremental updates and rebuild from scratch.
+ *
+ * @param {object} args - Parsed CLI arguments { positional, flags }.
+ * @param {object} context - CLI context { output, errors }.
+ */
+async function run(args, context) {
+  // Check for QMD availability first
+  const qmd = checkQmd();
+  if (!qmd.available) {
+    context.errors.throwError(1, qmd.message, 'search');
+    return;
+  }
+
+  // Build the command
+  let cmd = 'qmd index';
+  if (args.flags.force) {
+    cmd += ' --force';
+  }
+
+  // Print progress messages before starting
+  context.output.info('Updating search index...');
+  if (args.flags.force) {
+    context.output.info('Force flag set -- re-indexing all documents from scratch.');
+  }
+
+  // Execute the index command
+  const result = await shell.exec(cmd);
+
+  if (result.exitCode !== 0) {
+    context.errors.throwError(1, result.stderr || 'Index update failed.', 'search');
+    return;
+  }
+
+  // Pass through QMD's output (informational, not structured data)
+  context.output.info(result.stdout || 'Index updated successfully.');
+}
+
+module.exports = { meta, run };

package/src/commands/search/index.js

@@ -0,0 +1,21 @@
+/**
+ * Search service registration.
+ * Markdown search via QMD (requires separate install).
+ *
+ * All commands in this service check for QMD availability first.
+ * If QMD is not installed, they return an error with installation
+ * instructions: bun install -g @tobilu/qmd
+ */
+module.exports = {
+  name: 'search',
+  description: 'Markdown search via QMD',
+  commands: {
+    query:       () => require('./query'),
+    keyword:     () => require('./keyword'),
+    semantic:    () => require('./semantic'),
+    get:         () => require('./get'),
+    collections: () => require('./collections'),
+    index:       () => require('./index-cmd'),
+    status:      () => require('./status'),
+  }
+};

package/src/commands/search/keyword.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const { checkQmd, runQmdSearch } = require('./qmd');
+
+const meta = {
+  description: 'Fast BM25 full-text keyword search',
+  arguments: [
+    { name: 'query', description: 'Search query text', required: true }
+  ],
+  flags: [
+    { name: 'collection', type: 'string', description: 'Restrict search to a specific collection' },
+    { name: 'limit', type: 'number', description: 'Maximum number of results to return (default: 10)' }
+  ]
+};
+
+/**
+ * Runs a BM25 keyword search via QMD.
+ * Fast exact-term matching without vector similarity or LLM re-ranking.
+ *
+ * @param {object} args - Parsed CLI arguments { positional, flags }.
+ * @param {object} context - CLI context { output, errors }.
+ */
+async function run(args, context) {
+  // Check for QMD availability first
+  const qmd = checkQmd();
+  if (!qmd.available) {
+    context.errors.throwError(1, qmd.message, 'search');
+    return;
+  }
+
+  const query = args.positional[0];
+
+  if (!query) {
+    context.errors.throwError(400, 'Missing required argument: <query>. Example: dev search keyword "SSH key"', 'search');
+    return;
+  }
+
+  // Build the QMD command
+  let cmd = `qmd keyword "${query}"`;
+
+  if (args.flags.collection) {
+    cmd += ` --collection "${args.flags.collection}"`;
+  }
+  if (args.flags.limit) {
+    cmd += ` --limit ${args.flags.limit}`;
+  }
+
+  // Execute and parse results
+  const results = await runQmdSearch(cmd, context);
+  if (results === null) return; // error already reported
+
+  if (results.length === 0) {
+    context.output.info('No results found.');
+    return;
+  }
+
+  context.output.out(results);
+}
+
+module.exports = { meta, run };

package/src/commands/search/qmd.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const shell = require('../../lib/shell');
+
+/**
+ * Checks if QMD is installed and available on the system PATH.
+ * Every search command calls this before doing anything else.
+ *
+ * @returns {object} { available: true } if found, or { available: false, message: '...' } if not.
+ */
+function checkQmd() {
+  const isInstalled = shell.commandExists('qmd');
+
+  if (!isInstalled) {
+    return {
+      available: false,
+      message: 'QMD is not installed. Install it with: bun install -g @tobilu/qmd'
+    };
+  }
+
+  return { available: true };
+}
+
+/**
+ * Parses search results from QMD output.
+ * Tries JSON first, then falls back to line-delimited text.
+ * Returns an empty array for empty or null output.
+ *
+ * Output format may vary by QMD version.
+ *
+ * @param {string} output - The raw stdout from a QMD search command.
+ * @returns {Array<object>} Parsed search results.
+ */
+function parseSearchResults(output) {
+  if (!output || !output.trim()) {
+    return [];
+  }
+
+  // Try JSON first
+  try {
+    const parsed = JSON.parse(output);
+    return Array.isArray(parsed) ? parsed : [parsed];
+  } catch (err) {
+    // Fall back to line-delimited text
+  }
+
+  // Parse as line-delimited results
+  return output.trim().split('\n').filter(Boolean).map(line => ({ raw: line }));
+}
+
+/**
+ * Runs a QMD search command and parses the results.
+ * Returns null if the command fails (error is reported via context.errors).
+ *
+ * @param {string} cmd - The full QMD command to run.
+ * @param {object} context - The CLI context (needs context.errors).
+ * @returns {Promise<Array<object>|null>} Parsed results, or null on failure.
+ */
+async function runQmdSearch(cmd, context) {
+  const result = await shell.exec(cmd);
+
+  if (result.exitCode !== 0) {
+    context.errors.throwError(1, result.stderr || `QMD command failed: ${cmd}`, 'search');
+    return null;
+  }
+
+  return parseSearchResults(result.stdout);
+}
+
+module.exports = { checkQmd, parseSearchResults, runQmdSearch };

package/src/commands/search/query.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const { checkQmd, runQmdSearch } = require('./qmd');
+
+const meta = {
+  description: 'Hybrid search combining BM25 keyword matching, vector similarity, and LLM re-ranking',
+  arguments: [
+    { name: 'query', description: 'Search query text', required: true }
+  ],
+  flags: [
+    { name: 'collection', type: 'string', description: 'Restrict search to a specific collection' },
+    { name: 'limit', type: 'number', description: 'Maximum number of results to return (default: 10)' },
+    { name: 'min-score', type: 'number', description: 'Minimum relevance score between 0.0 and 1.0' }
+  ]
+};
+
+/**
+ * Runs a hybrid search (BM25 + vector + LLM re-ranking) via QMD.
+ * Provides the highest quality results at the cost of speed.
+ *
+ * @param {object} args - Parsed CLI arguments { positional, flags }.
+ * @param {object} context - CLI context { output, errors }.
+ */
+async function run(args, context) {
+  // Check for QMD availability first
+  const qmd = checkQmd();
+  if (!qmd.available) {
+    context.errors.throwError(1, qmd.message, 'search');
+    return;
+  }
+
+  const query = args.positional[0];
+
+  if (!query) {
+    context.errors.throwError(400, 'Missing required argument: <query>. Example: dev search query "how to configure SSH"', 'search');
+    return;
+  }
+
+  // Build the QMD command
+  let cmd = `qmd query "${query}"`;
+
+  if (args.flags.collection) {
+    cmd += ` --collection "${args.flags.collection}"`;
+  }
+  if (args.flags.limit) {
+    cmd += ` --limit ${args.flags.limit}`;
+  }
+  if (args.flags['min-score']) {
+    cmd += ` --min-score ${args.flags['min-score']}`;
+  }
+
+  // Execute and parse results
+  const results = await runQmdSearch(cmd, context);
+  if (results === null) return; // error already reported
+
+  if (results.length === 0) {
+    context.output.info('No results found.');
+    return;
+  }
+
+  context.output.out(results);
+}
+
+module.exports = { meta, run };

package/src/commands/search/semantic.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const { checkQmd, runQmdSearch } = require('./qmd');
+
+const meta = {
+  description: 'Vector cosine similarity search for conceptually related content',
+  arguments: [
+    { name: 'query', description: 'Search query text', required: true }
+  ],
+  flags: [
+    { name: 'collection', type: 'string', description: 'Restrict search to a specific collection' },
+    { name: 'limit', type: 'number', description: 'Maximum number of results to return (default: 10)' }
+  ]
+};
+
+/**
+ * Runs a vector cosine similarity search via QMD.
+ * Finds conceptually similar content even when the exact words don't match.
+ * Requires embeddings to be generated first (via dev search index).
+ *
+ * @param {object} args - Parsed CLI arguments { positional, flags }.
+ * @param {object} context - CLI context { output, errors }.
+ */
+async function run(args, context) {
+  // Check for QMD availability first
+  const qmd = checkQmd();
+  if (!qmd.available) {
+    context.errors.throwError(1, qmd.message, 'search');
+    return;
+  }
+
+  const query = args.positional[0];
+
+  if (!query) {
+    context.errors.throwError(400, 'Missing required argument: <query>. Example: dev search semantic "remote server access"', 'search');
+    return;
+  }
+
+  // Build the QMD command
+  let cmd = `qmd semantic "${query}"`;
+
+  if (args.flags.collection) {
+    cmd += ` --collection "${args.flags.collection}"`;
+  }
+  if (args.flags.limit) {
+    cmd += ` --limit ${args.flags.limit}`;
+  }
+
+  // Execute and parse results
+  const results = await runQmdSearch(cmd, context);
+  if (results === null) return; // error already reported
+
+  if (results.length === 0) {
+    // Check if this might be an embeddings issue
+    context.output.info('No results found. If embeddings have not been generated, run "dev search index" first.');
+    return;
+  }
+
+  context.output.out(results);
+}
+
+module.exports = { meta, run };

package/src/commands/search/status.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const shell = require('../../lib/shell');
+const { checkQmd, parseSearchResults } = require('./qmd');
+
+const meta = {
+  description: 'Show search index health, collection count, and document count',
+  arguments: [],
+  flags: []
+};
+
+/**
+ * Shows the health and status of the QMD search index.
+ * Displays collection count, document count, last update time, and health.
+ *
+ * @param {object} args - Parsed CLI arguments { positional, flags }.
+ * @param {object} context - CLI context { output, errors }.
+ */
+async function run(args, context) {
+  // Check for QMD availability first
+  const qmd = checkQmd();
+  if (!qmd.available) {
+    context.errors.throwError(1, qmd.message, 'search');
+    return;
+  }
+
+  // Run qmd status and capture the output
+  const result = await shell.exec('qmd status');
+
+  if (result.exitCode !== 0) {
+    context.errors.throwError(1, result.stderr || 'Failed to get search index status.', 'search');
+    return;
+  }
+
+  // Try to parse the output as JSON for structured data
+  const output = result.stdout;
+  try {
+    const parsed = JSON.parse(output);
+    context.output.out(parsed);
+  } catch (err) {
+    // QMD returned non-JSON output, pass it through as-is
+    context.output.info(output || 'No status information available.');
+  }
+}
+
+module.exports = { meta, run };