@fredlackey/devutils 0.0.19 → 0.1.0

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

package/src/commands/status.js

@@ -0,0 +1,276 @@
+'use strict';
+
+/**
+ * status command.
+ * An overall health check that shows the current state of the DevUtils
+ * installation in a single-screen dashboard. Checks config, machine
+ * profile, auth services, aliases, API plugins, and sync status.
+ *
+ * This command is read-only and never modifies any files. It handles
+ * missing files gracefully, showing helpful placeholder messages
+ * instead of crashing.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const meta = {
+  description: 'Overall health check',
+  arguments: [],
+  flags: []
+};
+
+/**
+ * Checks the config.json status. Reports whether the file exists
+ * and whether it contains valid JSON.
+ *
+ * @param {object} config - The context.config module.
+ * @returns {{ exists: boolean, valid: boolean }}
+ */
+function checkConfig(config) {
+  if (!config.exists('config.json')) {
+    return { exists: false, valid: false };
+  }
+  const data = config.read('config.json');
+  if (data === null) {
+    return { exists: true, valid: false };
+  }
+  return { exists: true, valid: true };
+}
+
+/**
+ * Checks the machine profile. Reads machines/current.json and pulls
+ * out key fields like type, arch, hostname, and packageManager.
+ *
+ * @param {object} config - The context.config module.
+ * @returns {{ detected: boolean, type?: string, arch?: string, hostname?: string, packageManager?: string }}
+ */
+function checkMachine(config) {
+  const profile = config.read('machines/current.json');
+  if (!profile) {
+    return { detected: false };
+  }
+
+  return {
+    detected: true,
+    type: profile.os ? profile.os.type : (profile.type || 'unknown'),
+    arch: profile.arch || 'unknown',
+    hostname: profile.hostname || 'unknown',
+    packageManager: profile.packageManagers
+      ? profile.packageManagers[0] || null
+      : (profile.packageManager || null),
+  };
+}
+
+/**
+ * Checks the auth directory for connected services.
+ * Each JSON file (excluding subdirectories) represents a connected service.
+ *
+ * @param {object} config - The context.config module.
+ * @returns {{ services: string[], count: number }}
+ */
+function checkAuth(config) {
+  const authDir = config.getPath('auth');
+  if (!fs.existsSync(authDir)) {
+    return { services: [], count: 0 };
+  }
+
+  try {
+    const entries = fs.readdirSync(authDir);
+    const services = entries
+      .filter(entry => {
+        const fullPath = path.join(authDir, entry);
+        return fs.statSync(fullPath).isFile() && entry.endsWith('.json');
+      })
+      .map(file => path.basename(file, '.json'));
+
+    return { services, count: services.length };
+  } catch {
+    return { services: [], count: 0 };
+  }
+}
+
+/**
+ * Checks the aliases.json file for registered aliases.
+ *
+ * @param {object} config - The context.config module.
+ * @returns {{ count: number }}
+ */
+function checkAliases(config) {
+  const data = config.read('aliases.json');
+  if (!data) {
+    return { count: 0 };
+  }
+
+  // Handle both array and object formats
+  if (Array.isArray(data)) {
+    return { count: data.length };
+  }
+  return { count: Object.keys(data).length };
+}
+
+/**
+ * Checks the plugins.json file for installed API plugins.
+ *
+ * @param {object} config - The context.config module.
+ * @returns {{ count: number, plugins: string[] }}
+ */
+function checkPlugins(config) {
+  const data = config.read('plugins.json');
+  if (!data) {
+    return { count: 0, plugins: [] };
+  }
+
+  // Handle both array and object formats
+  if (Array.isArray(data)) {
+    return { count: data.length, plugins: data };
+  }
+  const plugins = Object.keys(data);
+  return { count: plugins.length, plugins };
+}
+
+/**
+ * Checks the sync.json file for the last backup timestamp.
+ *
+ * @param {object} config - The context.config module.
+ * @returns {{ lastBackup: string|null }}
+ */
+function checkSync(config) {
+  const data = config.read('sync.json');
+  if (!data || !data.lastBackup) {
+    return { lastBackup: null };
+  }
+  return { lastBackup: data.lastBackup };
+}
+
+/**
+ * Formats a human-readable summary line for the config section.
+ *
+ * @param {{ exists: boolean, valid: boolean }} configStatus - The config check result.
+ * @returns {string}
+ */
+function formatConfig(configStatus) {
+  if (!configStatus.exists) {
+    return 'Not found. Run \'dev config init\' to get started.';
+  }
+  if (!configStatus.valid) {
+    return 'Invalid JSON. Check ~/.devutils/config.json for syntax errors.';
+  }
+  return 'OK';
+}
+
+/**
+ * Formats a human-readable summary line for the machine section.
+ *
+ * @param {{ detected: boolean, type?: string, arch?: string, packageManager?: string }} machineStatus - The machine check result.
+ * @returns {string}
+ */
+function formatMachine(machineStatus) {
+  if (!machineStatus.detected) {
+    return 'Not detected. Run \'dev machine detect\' to set up.';
+  }
+  const pm = machineStatus.packageManager ? ` (${machineStatus.packageManager})` : '';
+  return `${machineStatus.type} ${machineStatus.arch}${pm}`;
+}
+
+/**
+ * Formats a human-readable summary line for the auth section.
+ *
+ * @param {{ services: string[], count: number }} authStatus - The auth check result.
+ * @returns {string}
+ */
+function formatAuth(authStatus) {
+  if (authStatus.count === 0) {
+    return 'No services connected.';
+  }
+  return `${authStatus.count} services (${authStatus.services.join(', ')})`;
+}
+
+/**
+ * Formats a human-readable summary line for the aliases section.
+ *
+ * @param {{ count: number }} aliasStatus - The alias check result.
+ * @returns {string}
+ */
+function formatAliases(aliasStatus) {
+  if (aliasStatus.count === 0) {
+    return 'None registered.';
+  }
+  return `${aliasStatus.count} registered`;
+}
+
+/**
+ * Formats a human-readable summary line for the plugins section.
+ *
+ * @param {{ count: number, plugins: string[] }} pluginStatus - The plugin check result.
+ * @returns {string}
+ */
+function formatPlugins(pluginStatus) {
+  if (pluginStatus.count === 0) {
+    return 'None installed.';
+  }
+  return `${pluginStatus.count} installed (${pluginStatus.plugins.join(', ')})`;
+}
+
+/**
+ * Formats a human-readable summary line for the sync section.
+ *
+ * @param {{ lastBackup: string|null }} syncStatus - The sync check result.
+ * @returns {string}
+ */
+function formatSync(syncStatus) {
+  if (!syncStatus.lastBackup) {
+    return 'Never.';
+  }
+  // Format the ISO timestamp into something more readable
+  try {
+    const date = new Date(syncStatus.lastBackup);
+    return date.toLocaleString();
+  } catch {
+    return syncStatus.lastBackup;
+  }
+}
+
+/**
+ * Runs the status health check. Gathers information from config files,
+ * machine profile, auth directory, aliases, plugins, and sync state.
+ * Outputs a compact summary for humans or a structured object for JSON.
+ *
+ * @param {object} args - Parsed command arguments (none expected).
+ * @param {object} context - The CLI context object with config, platform, shell, output, flags.
+ */
+async function run(args, context) {
+  const configStatus = checkConfig(context.config);
+  const machineStatus = checkMachine(context.config);
+  const authStatus = checkAuth(context.config);
+  const aliasStatus = checkAliases(context.config);
+  const pluginStatus = checkPlugins(context.config);
+  const syncStatus = checkSync(context.config);
+
+  const result = {
+    config: configStatus,
+    machine: machineStatus,
+    auth: authStatus,
+    aliases: aliasStatus,
+    plugins: pluginStatus,
+    sync: syncStatus,
+  };
+
+  if (context.flags.format === 'json') {
+    context.output.out(result);
+    return;
+  }
+
+  // Human-friendly output
+  context.output.info('DevUtils Status');
+  context.output.info('---------------');
+  context.output.info(`Config:      ${formatConfig(configStatus)}`);
+  context.output.info(`Machine:     ${formatMachine(machineStatus)}`);
+  context.output.info(`Auth:        ${formatAuth(authStatus)}`);
+  context.output.info(`Aliases:     ${formatAliases(aliasStatus)}`);
+  context.output.info(`API Plugins: ${formatPlugins(pluginStatus)}`);
+  context.output.info(`Last Sync:   ${formatSync(syncStatus)}`);
+}
+
+module.exports = { meta, run };

package/src/commands/tools/check.js

@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * Command: dev tools check <tool-name>
+ *
+ * Checks if a tool is installed and shows its version.
+ */
+
+/**
+ * @type {{ description: string, arguments: Array, flags: Array }}
+ */
+const meta = {
+  description: 'Check if a tool is installed and show its version',
+  arguments: [
+    { name: 'tool', description: 'Name of the tool to check', required: true }
+  ],
+  flags: []
+};
+
+/**
+ * Runs the check command.
+ * @param {{ positional: string[], flags: object }} args - Parsed command arguments.
+ * @param {object} context - The CLI context object.
+ */
+async function run(args, context) {
+  const toolName = args.positional[0];
+
+  if (!toolName) {
+    context.errors.throwError(400, 'Missing required argument: tool. Usage: dev tools check <tool-name>', 'tools');
+    return;
+  }
+
+  const installer = require('../../lib/installer');
+
+  // Look up the tool in the registry
+  const tool = installer.findTool(toolName);
+  if (!tool) {
+    context.output.error(`Tool '${toolName}' not found in registry. Run "dev tools search ${toolName}" to search.`);
+    return;
+  }
+
+  try {
+    // Load the installer and check if the tool is installed
+    const mod = installer.loadInstaller(tool);
+    const installed = await mod.isInstalled(context);
+
+    if (installed) {
+      // Try to get the version
+      let version = 'version unknown';
+      if (typeof mod.getVersion === 'function') {
+        const ver = await mod.getVersion(context);
+        if (ver) {
+          version = `version ${ver}`;
+        }
+      } else {
+        // Fall back to --version
+        try {
+          const result = await context.shell.exec(`${tool.name} --version`);
+          if (result.exitCode === 0 && result.stdout) {
+            const match = result.stdout.trim().match(/(\d+\.\d+[\.\d]*)/);
+            if (match) {
+              version = `version ${match[1]}`;
+            }
+          }
+        } catch {
+          // version remains "version unknown"
+        }
+      }
+
+      context.output.out({ name: tool.name, installed: true, version });
+    } else {
+      context.output.out({ name: tool.name, installed: false, version: null });
+    }
+  } catch (err) {
+    context.output.error(err.message);
+  }
+}
+
+module.exports = { meta, run };

package/src/commands/tools/index.js

@@ -0,0 +1,14 @@
+/**
+ * Tools service registration.
+ * Tool installation and management.
+ */
+module.exports = {
+  name: 'tools',
+  description: 'Tool installation and management',
+  commands: {
+    install: () => require('./install'),
+    check:   () => require('./check'),
+    list:    () => require('./list'),
+    search:  () => require('./search'),
+  }
+};

package/src/commands/tools/install.js

@@ -0,0 +1,110 @@
+'use strict';
+
+/**
+ * Command: dev tools install <tool-name>
+ *
+ * Installs a development tool using the platform-appropriate method.
+ * Resolves and installs dependencies automatically.
+ */
+
+/**
+ * @type {{ description: string, arguments: Array, flags: Array }}
+ */
+const meta = {
+  description: 'Install a development tool',
+  arguments: [
+    { name: 'tool', description: 'Name of the tool to install', required: true }
+  ],
+  flags: [
+    { name: '--dry-run', description: 'Show what would be installed without doing it' },
+    { name: '--skip-deps', description: 'Skip dependency installation' }
+  ]
+};
+
+/**
+ * Runs the install command.
+ * @param {{ positional: string[], flags: object }} args - Parsed command arguments.
+ * @param {object} context - The CLI context object.
+ */
+async function run(args, context) {
+  const toolName = args.positional[0];
+
+  if (!toolName) {
+    context.errors.throwError(400, 'Missing required argument: tool. Usage: dev tools install <tool-name>', 'tools');
+    return;
+  }
+
+  const installer = require('../../lib/installer');
+
+  // Look up the tool in the registry
+  const tool = installer.findTool(toolName);
+  if (!tool) {
+    context.output.error(`Tool '${toolName}' not found in registry. Run "dev tools search ${toolName}" to search.`);
+    return;
+  }
+
+  // Check platform support
+  const platformType = context.platform.detect().type;
+  if (!tool.platforms.includes(platformType)) {
+    context.output.error(
+      `Tool '${tool.name}' is not supported on ${platformType}. ` +
+      `Supported platforms: ${tool.platforms.join(', ')}`
+    );
+    return;
+  }
+
+  // Dry run: show what would be installed without doing it
+  if (context.flags.dryRun || args.flags['dry-run']) {
+    try {
+      const chain = installer.resolveDependencies(tool.name);
+
+      // Check which tools are already installed
+      const statuses = [];
+      for (const name of chain) {
+        const isAlready = await installer.checkInstalled(name, context);
+        statuses.push({ name, installed: isAlready });
+      }
+
+      const needsInstall = statuses.filter(s => !s.installed);
+      const alreadyInstalled = statuses.filter(s => s.installed);
+
+      if (needsInstall.length === 0) {
+        context.output.info(`${tool.name} is already installed (and all dependencies).`);
+      } else {
+        context.output.info('Would install (in order):');
+        for (const s of needsInstall) {
+          context.output.info(`  - ${s.name}`);
+        }
+        if (alreadyInstalled.length > 0) {
+          context.output.info('Already installed:');
+          for (const s of alreadyInstalled) {
+            context.output.info(`  - ${s.name}`);
+          }
+        }
+      }
+    } catch (err) {
+      context.output.error(err.message);
+    }
+    return;
+  }
+
+  // Actually install
+  try {
+    const result = await installer.installTool(tool.name, context);
+
+    if (result.alreadyInstalled) {
+      context.output.info(`${tool.name} is already installed.`);
+    } else {
+      if (result.dependenciesInstalled.length > 0) {
+        context.output.info(`Dependencies installed: ${result.dependenciesInstalled.join(', ')}`);
+      }
+      if (result.installed) {
+        context.output.info(`${tool.name} installed successfully.`);
+      }
+    }
+  } catch (err) {
+    context.output.error(err.message);
+  }
+}
+
+module.exports = { meta, run };

package/src/commands/tools/list.js

@@ -0,0 +1,91 @@
+'use strict';
+
+/**
+ * Command: dev tools list
+ *
+ * Lists all available tools from the registry, with their install status.
+ * Can filter by --installed, --available, or --platform.
+ */
+
+/**
+ * @type {{ description: string, arguments: Array, flags: Array }}
+ */
+const meta = {
+  description: 'List available tools',
+  arguments: [],
+  flags: [
+    { name: '--installed', description: 'Show only installed tools' },
+    { name: '--available', description: 'Show only tools not yet installed' },
+    { name: '--platform', description: 'Filter by platform (default: current)' }
+  ]
+};
+
+/**
+ * Runs the list command.
+ * @param {{ positional: string[], flags: object }} args - Parsed command arguments.
+ * @param {object} context - The CLI context object.
+ */
+async function run(args, context) {
+  const installer = require('../../lib/installer');
+
+  // Load the full registry
+  const tools = installer.loadRegistry();
+
+  // Determine platform filter
+  const platformFilter = args.flags.platform || context.platform.detect().type;
+
+  // Filter to tools that support the target platform
+  let filtered = tools.filter(t => t.platforms.includes(platformFilter));
+
+  // If --installed or --available, check each tool's install status
+  const showInstalled = args.flags.installed === true;
+  const showAvailable = args.flags.available === true;
+
+  if (showInstalled || showAvailable) {
+    const statusResults = [];
+    for (const tool of filtered) {
+      try {
+        const mod = installer.loadInstaller(tool);
+        const isInst = await mod.isInstalled(context);
+        statusResults.push({ tool, installed: isInst });
+      } catch {
+        // If the installer can't be loaded, treat as not installed
+        statusResults.push({ tool, installed: false });
+      }
+    }
+
+    if (showInstalled) {
+      filtered = statusResults.filter(r => r.installed).map(r => r.tool);
+    } else {
+      filtered = statusResults.filter(r => !r.installed).map(r => r.tool);
+    }
+  }
+
+  if (filtered.length === 0) {
+    context.output.info('No tools match the current filters.');
+    return;
+  }
+
+  // Build output rows with install status
+  const rows = [];
+  for (const tool of filtered) {
+    let status = '-';
+    try {
+      const mod = installer.loadInstaller(tool);
+      const isInst = await mod.isInstalled(context);
+      status = isInst ? 'yes' : 'no';
+    } catch {
+      status = '?';
+    }
+
+    rows.push({
+      Name: tool.name,
+      Description: tool.description,
+      Installed: status,
+    });
+  }
+
+  context.output.out(rows);
+}
+
+module.exports = { meta, run };

package/src/commands/tools/search.js

@@ -0,0 +1,60 @@
+'use strict';
+
+/**
+ * Command: dev tools search <query>
+ *
+ * Searches for tools by name or keyword in the registry.
+ * Matches against tool name and description (case-insensitive).
+ */
+
+/**
+ * @type {{ description: string, arguments: Array, flags: Array }}
+ */
+const meta = {
+  description: 'Search for tools by name or keyword',
+  arguments: [
+    { name: 'query', description: 'Search term (matches name and description)', required: true }
+  ],
+  flags: []
+};
+
+/**
+ * Runs the search command.
+ * @param {{ positional: string[], flags: object }} args - Parsed command arguments.
+ * @param {object} context - The CLI context object.
+ */
+async function run(args, context) {
+  const query = args.positional[0];
+
+  if (!query) {
+    context.errors.throwError(400, 'Missing required argument: query. Usage: dev tools search <query>', 'tools');
+    return;
+  }
+
+  const installer = require('../../lib/installer');
+
+  // Load the registry and search
+  const tools = installer.loadRegistry();
+  const lower = query.toLowerCase();
+
+  const matches = tools.filter(t =>
+    t.name.toLowerCase().includes(lower) ||
+    t.description.toLowerCase().includes(lower)
+  );
+
+  if (matches.length === 0) {
+    context.output.info(`No tools found matching '${query}'.`);
+    return;
+  }
+
+  // Format as table with name, description, and platforms
+  const rows = matches.map(t => ({
+    Name: t.name,
+    Description: t.description,
+    Platforms: t.platforms.join(', '),
+  }));
+
+  context.output.out(rows);
+}
+
+module.exports = { meta, run };