@fredlackey/devutils 0.0.19 → 0.1.0

package/src/commands/schema.js

@@ -0,0 +1,152 @@
+'use strict';
+
+const meta = {
+  description: 'Introspect a command by dot-notation path. Returns description, arguments, and flags.',
+  arguments: [
+    { name: 'path', required: false, description: 'Dot-notation path (e.g., config.set, api.gmail.messages.list)' },
+  ],
+  flags: [],
+};
+
+async function run(args, context) {
+  const schema = require('../lib/schema');
+  const dotPath = args.positional[0];
+
+  if (!dotPath) {
+    // No path given: show top-level listing
+    const registry = schema.getRegistry();
+    const entries = [];
+
+    for (const [name, entry] of Object.entries(registry)) {
+      entries.push({
+        Name: name,
+        Type: entry.type || 'unknown',
+        Description: entry.description || '',
+      });
+    }
+
+    if (entries.length === 0) {
+      context.output.info('No commands found in registry.');
+      return;
+    }
+
+    context.output.out(entries);
+    context.output.info(`\nUse "dev schema <path>" to inspect a specific command.`);
+    context.output.info('Example: dev schema config.set');
+    return;
+  }
+
+  const result = schema.resolve(dotPath);
+
+  if (!result) {
+    // Try to find suggestions by resolving the parent path
+    const parts = dotPath.split('.');
+    if (parts.length > 1) {
+      const parentPath = parts.slice(0, -1).join('.');
+      const parent = schema.resolve(parentPath);
+      if (parent) {
+        const children = parent.commands
+          ? Object.keys(parent.commands)
+          : parent.resources
+            ? Object.keys(parent.resources)
+            : [];
+        if (children.length > 0) {
+          context.output.error(`No command found at "${dotPath}".`);
+          context.output.info(`Available under "${parentPath}": ${children.join(', ')}`);
+          return;
+        }
+      }
+    }
+
+    context.output.error(`No command found at "${dotPath}".`);
+    context.output.info('Run "dev schema" to see all available paths.');
+    return;
+  }
+
+  // Display the result
+  if (result.type === 'service') {
+    const cmds = Object.keys(result.commands || {});
+    if (context.flags.format === 'json') {
+      context.output.out(result);
+      return;
+    }
+    context.output.info(`Service: ${result.name}`);
+    context.output.info(`Description: ${result.description}`);
+    context.output.info('');
+    context.output.info(`Commands (${cmds.length}):`);
+    for (const cmdName of cmds) {
+      const cmd = result.commands[cmdName];
+      context.output.info(`  ${cmdName.padEnd(20)} ${cmd.description || ''}`);
+    }
+    return;
+  }
+
+  if (result.type === 'plugin') {
+    const resources = Object.keys(result.resources || {});
+    if (context.flags.format === 'json') {
+      context.output.out(result);
+      return;
+    }
+    context.output.info(`Plugin: ${result.name} (v${result.version})`);
+    context.output.info(`Description: ${result.description}`);
+    context.output.info(`Auth: ${result.auth || 'none'}`);
+    context.output.info('');
+    context.output.info(`Resources (${resources.length}):`);
+    for (const resName of resources) {
+      const res = result.resources[resName];
+      context.output.info(`  ${resName.padEnd(20)} ${res.description || ''}`);
+    }
+    return;
+  }
+
+  if (result.type === 'resource') {
+    const cmds = Object.keys(result.commands || {});
+    if (context.flags.format === 'json') {
+      context.output.out(result);
+      return;
+    }
+    context.output.info(`Resource: ${result.name}`);
+    context.output.info(`Description: ${result.description}`);
+    context.output.info('');
+    context.output.info(`Commands (${cmds.length}):`);
+    for (const cmdName of cmds) {
+      const cmd = result.commands[cmdName];
+      context.output.info(`  ${cmdName.padEnd(20)} ${cmd.description || ''}`);
+    }
+    return;
+  }
+
+  if (result.type === 'command') {
+    if (context.flags.format === 'json') {
+      context.output.out(result);
+      return;
+    }
+    context.output.info(`Command: ${result.name}`);
+    context.output.info(`Description: ${result.description}`);
+
+    const cmdArgs = result.arguments || [];
+    if (cmdArgs.length > 0) {
+      context.output.info('');
+      context.output.info('Arguments:');
+      for (const arg of cmdArgs) {
+        const req = arg.required ? '(required)' : '(optional)';
+        context.output.info(`  ${(arg.name || '').padEnd(20)} ${req} ${arg.description || ''}`);
+      }
+    }
+
+    const cmdFlags = result.flags || [];
+    if (cmdFlags.length > 0) {
+      context.output.info('');
+      context.output.info('Flags:');
+      for (const flag of cmdFlags) {
+        context.output.info(`  --${(flag.name || '').padEnd(18)} ${flag.description || ''}`);
+      }
+    }
+    return;
+  }
+
+  // Fallback: just output the result
+  context.output.out(result);
+}
+
+module.exports = { meta, run };

package/src/commands/search/collections.js

@@ -0,0 +1,134 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const shell = require('../../lib/shell');
+const { checkQmd } = require('./qmd');
+
+const meta = {
+  description: 'Manage searchable collections (add, remove, list)',
+  arguments: [
+    { name: 'action', description: 'Sub-command: add, remove, or list', required: true },
+    { name: 'target', description: 'Directory path (for add) or collection name (for remove)', required: false }
+  ],
+  flags: [
+    { name: 'name', type: 'string', description: 'Collection name (required for add)' },
+    { name: 'mask', type: 'string', description: 'Glob pattern to filter indexed files (e.g., "**/*.md")' },
+    { name: 'confirm', type: 'boolean', description: 'Skip confirmation prompt (for remove)' }
+  ]
+};
+
+/**
+ * Manages QMD search collections: add, remove, or list.
+ * Each action shells out to the corresponding qmd collections command.
+ *
+ * @param {object} args - Parsed CLI arguments { positional, flags }.
+ * @param {object} context - CLI context { output, errors, prompt }.
+ */
+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 action = args.positional[0];
+
+  if (!action) {
+    context.output.info('Usage: dev search collections <add|remove|list>');
+    return;
+  }
+
+  if (action === 'list') {
+    // List all registered collections
+    const result = await shell.exec('qmd collections list');
+
+    if (result.exitCode !== 0) {
+      context.errors.throwError(1, result.stderr || 'Failed to list collections.', 'search');
+      return;
+    }
+
+    // Try to parse as JSON for structured output
+    const output = result.stdout;
+    try {
+      const parsed = JSON.parse(output);
+      context.output.out(parsed);
+    } catch (err) {
+      // Pass through as-is
+      context.output.info(output || 'No collections registered.');
+    }
+
+  } else if (action === 'add') {
+    // Add a new collection
+    const target = args.positional[1];
+
+    if (!target) {
+      context.errors.throwError(400, 'Missing directory path. Example: dev search collections add /path/to/dir --name docs', 'search');
+      return;
+    }
+
+    const name = args.flags.name;
+    if (!name) {
+      context.errors.throwError(400, 'The --name flag is required when adding a collection.', 'search');
+      return;
+    }
+
+    // Resolve to an absolute path
+    const dirPath = path.resolve(target);
+    if (!fs.existsSync(dirPath)) {
+      context.errors.throwError(1, `Directory does not exist: ${dirPath}`, 'search');
+      return;
+    }
+
+    // Build the qmd command
+    let cmd = `qmd collections add "${dirPath}" --name "${name}"`;
+    if (args.flags.mask) {
+      cmd += ` --mask "${args.flags.mask}"`;
+    }
+
+    const result = await shell.exec(cmd);
+
+    if (result.exitCode !== 0) {
+      context.errors.throwError(1, result.stderr || 'Failed to add collection.', 'search');
+      return;
+    }
+
+    context.output.info(`Collection "${name}" added: ${dirPath}`);
+
+  } else if (action === 'remove') {
+    // Remove a collection
+    const name = args.positional[1];
+
+    if (!name) {
+      context.errors.throwError(400, 'Provide the collection name to remove. Example: dev search collections remove docs', 'search');
+      return;
+    }
+
+    // Ask for confirmation unless --confirm is passed
+    if (!args.flags.confirm) {
+      const ok = await context.prompt.confirm(
+        `Remove collection "${name}"?`,
+        false
+      );
+      if (!ok) {
+        context.output.info('Cancelled.');
+        return;
+      }
+    }
+
+    const result = await shell.exec(`qmd collections remove "${name}"`);
+
+    if (result.exitCode !== 0) {
+      context.errors.throwError(1, result.stderr || `Failed to remove collection "${name}".`, 'search');
+      return;
+    }
+
+    context.output.info(`Collection "${name}" removed.`);
+
+  } else {
+    context.output.info('Usage: dev search collections <add|remove|list>');
+  }
+}
+
+module.exports = { meta, run };

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 };