@fredlackey/devutils 0.0.18 → 0.1.0

package/src/commands/machine/detect.js

@@ -0,0 +1,122 @@
+'use strict';
+
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Formats a byte count into a human-readable string (e.g., "16.0 GB").
+ * Rounds to one decimal place for clarity.
+ *
+ * @param {number} bytes - The number of bytes to format.
+ * @returns {string} A human-readable size string like "16.0 GB".
+ */
+function formatBytes(bytes) {
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  let i = 0;
+  let value = bytes;
+  while (value >= 1024 && i < units.length - 1) {
+    value /= 1024;
+    i++;
+  }
+  return `${value.toFixed(1)} ${units[i]}`;
+}
+
+const meta = {
+  description: 'Detect the current machine\'s OS, architecture, package managers, and capabilities.',
+  arguments: [],
+  flags: []
+};
+
+/**
+ * Detects the current machine's hardware and OS details, then writes
+ * the profile to ~/.devutils/machines/current.json.
+ *
+ * Uses context.platform.detect() for OS type, then layers on hostname,
+ * CPU count, memory, available package managers, and OS version info
+ * from Node.js built-in modules and shell commands.
+ *
+ * @param {object} args - Parsed command arguments (none expected).
+ * @param {object} context - The CLI context object with platform, shell, output, errors.
+ */
+async function run(args, context) {
+  // Step 1: Get base platform detection
+  const platform = context.platform.detect();
+
+  // Step 2: Gather hardware and system info from Node.js os module
+  const hostname = os.hostname();
+  const cpuCount = os.cpus().length;
+  const totalMemory = os.totalmem();
+  const arch = os.arch();
+  const osRelease = os.release();
+
+  // Step 3: Detect which package managers are installed on this machine
+  const packageManagers = [];
+  const candidates = ['brew', 'apt', 'snap', 'dnf', 'yum', 'choco', 'winget', 'npm', 'yarn', 'pnpm'];
+
+  for (const pm of candidates) {
+    if (context.shell.commandExists(pm)) {
+      packageManagers.push(pm);
+    }
+  }
+
+  // Step 4: Get OS-specific version and name info
+  let osVersion = osRelease;
+  let osName = platform.type;
+
+  try {
+    if (platform.type === 'macos') {
+      const result = await context.shell.exec('sw_vers -productVersion');
+      if (result.exitCode === 0 && result.stdout) {
+        osVersion = result.stdout.trim();
+      }
+      osName = 'macOS';
+    } else if (['ubuntu', 'raspbian', 'amazon-linux'].includes(platform.type)) {
+      const releaseFile = fs.readFileSync('/etc/os-release', 'utf8');
+      const nameMatch = releaseFile.match(/^PRETTY_NAME="?(.+?)"?$/m);
+      if (nameMatch) {
+        osName = nameMatch[1];
+      }
+      const versionMatch = releaseFile.match(/^VERSION_ID="?(.+?)"?$/m);
+      if (versionMatch) {
+        osVersion = versionMatch[1];
+      }
+    }
+  } catch (err) {
+    // Keep defaults if detection fails
+  }
+
+  // Step 5: Build the machine profile object
+  const machineProfile = {
+    hostname: hostname,
+    os: {
+      type: platform.type,
+      name: osName,
+      version: osVersion,
+      kernel: osRelease
+    },
+    arch: arch,
+    cpu: {
+      count: cpuCount,
+      model: os.cpus()[0] ? os.cpus()[0].model : 'unknown'
+    },
+    memory: {
+      total: totalMemory,
+      totalHuman: formatBytes(totalMemory)
+    },
+    packageManagers: packageManagers,
+    detectedAt: new Date().toISOString()
+  };
+
+  // Step 6: Write the profile to disk (idempotent — overwrites if exists)
+  const MACHINES_DIR = path.join(os.homedir(), '.devutils', 'machines');
+  const CURRENT_FILE = path.join(MACHINES_DIR, 'current.json');
+
+  fs.mkdirSync(MACHINES_DIR, { recursive: true });
+  fs.writeFileSync(CURRENT_FILE, JSON.stringify(machineProfile, null, 2) + '\n');
+
+  // Step 7: Output the result
+  context.output.out(machineProfile);
+}
+
+module.exports = { meta, run };

package/src/commands/machine/index.js

@@ -0,0 +1,14 @@
+/**
+ * Machine service registration.
+ * Machine profiles and detection.
+ */
+module.exports = {
+  name: 'machine',
+  description: 'Machine profiles and detection',
+  commands: {
+    detect: () => require('./detect'),
+    show:   () => require('./show'),
+    set:    () => require('./set'),
+    list:   () => require('./list'),
+  }
+};

package/src/commands/machine/list.js

@@ -0,0 +1,74 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const meta = {
+  description: 'List all known machine profiles.',
+  arguments: [],
+  flags: []
+};
+
+/**
+ * Lists all machine profiles stored in ~/.devutils/machines/.
+ * Reads every .json file in the directory and builds a summary for each,
+ * including hostname, OS, architecture, and detection timestamp.
+ * The current machine (current.json) is marked in the output.
+ *
+ * Right now this will only show the local machine. When backup/sync is
+ * built, profiles from other computers will also appear here.
+ *
+ * @param {object} args - Parsed command arguments (none expected).
+ * @param {object} context - The CLI context object with output and errors.
+ */
+async function run(args, context) {
+  const MACHINES_DIR = path.join(os.homedir(), '.devutils', 'machines');
+
+  // Check if the machines directory exists
+  if (!fs.existsSync(MACHINES_DIR)) {
+    context.errors.throwError(404, 'No machine profiles found. Run "dev machine detect" first.', 'machine');
+    return;
+  }
+
+  // Find all JSON files in the machines directory
+  const files = fs.readdirSync(MACHINES_DIR).filter(f => f.endsWith('.json'));
+
+  if (files.length === 0) {
+    context.errors.throwError(404, 'No machine profiles found. Run "dev machine detect" first.', 'machine');
+    return;
+  }
+
+  // Load each profile and build a summary
+  const machines = [];
+
+  for (const file of files) {
+    try {
+      const raw = fs.readFileSync(path.join(MACHINES_DIR, file), 'utf8');
+      const profile = JSON.parse(raw);
+
+      machines.push({
+        file: file,
+        current: file === 'current.json',
+        hostname: profile.hostname || 'unknown',
+        os: profile.os ? `${profile.os.name} ${profile.os.version}` : 'unknown',
+        arch: profile.arch || 'unknown',
+        detectedAt: profile.detectedAt || 'unknown'
+      });
+    } catch (err) {
+      // Don't crash on corrupted files — show them as error entries
+      machines.push({
+        file: file,
+        current: file === 'current.json',
+        hostname: 'error',
+        os: `Failed to read: ${err.message}`,
+        arch: 'unknown',
+        detectedAt: 'unknown'
+      });
+    }
+  }
+
+  context.output.out(machines);
+}
+
+module.exports = { meta, run };

package/src/commands/machine/set.js

@@ -0,0 +1,106 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const meta = {
+  description: 'Set a value in the current machine profile.',
+  arguments: [
+    { name: 'key', required: true, description: 'Dot-notation path to the value (e.g., nickname, os.version)' },
+    { name: 'value', required: false, description: 'The value to set. Omit if using --json.' }
+  ],
+  flags: [
+    { name: 'json', type: 'string', description: 'Set a structured value using a JSON string' }
+  ]
+};
+
+/**
+ * Updates a single value in the current machine profile by dot-notation key.
+ * Reads ~/.devutils/machines/current.json, sets the value at the given path,
+ * and writes the file back. Preserves all other existing fields.
+ *
+ * Supports type coercion for simple values: "true"/"false" become booleans,
+ * "null" becomes null, numeric strings become numbers. Use --json for
+ * structured values like arrays or objects.
+ *
+ * @param {object} args - Parsed command arguments with positional[0]=key, positional[1]=value.
+ * @param {object} context - The CLI context object with output and errors.
+ */
+async function run(args, context) {
+  const key = args.positional[0];
+  const rawValue = args.positional[1];
+  const jsonValue = args.flags.json;
+
+  // Validate required arguments
+  if (!key) {
+    context.errors.throwError(400, 'Missing required argument: <key>. Example: dev machine set nickname "my-laptop"', 'machine');
+    return;
+  }
+
+  if (!rawValue && rawValue !== '' && !jsonValue) {
+    context.errors.throwError(400, 'Missing value. Provide a value or use --json for structured data.', 'machine');
+    return;
+  }
+
+  if (rawValue && jsonValue) {
+    context.errors.throwError(400, 'Provide either a positional value or --json, not both.', 'machine');
+    return;
+  }
+
+  // Parse the value with type coercion
+  let value;
+
+  if (jsonValue) {
+    try {
+      value = JSON.parse(jsonValue);
+    } catch (err) {
+      context.errors.throwError(400, `Invalid JSON: ${err.message}`, 'machine');
+      return;
+    }
+  } else {
+    if (rawValue === 'true') {
+      value = true;
+    } else if (rawValue === 'false') {
+      value = false;
+    } else if (rawValue === 'null') {
+      value = null;
+    } else if (!isNaN(rawValue) && rawValue.trim() !== '') {
+      value = Number(rawValue);
+    } else {
+      value = rawValue;
+    }
+  }
+
+  // Read the existing machine profile
+  const CURRENT_FILE = path.join(os.homedir(), '.devutils', 'machines', 'current.json');
+
+  if (!fs.existsSync(CURRENT_FILE)) {
+    context.errors.throwError(404, 'No machine profile found. Run "dev machine detect" first.', 'machine');
+    return;
+  }
+
+  const raw = fs.readFileSync(CURRENT_FILE, 'utf8');
+  const profile = JSON.parse(raw);
+
+  // Walk the dot-notation path and set the value
+  const parts = key.split('.');
+  let target = profile;
+
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i];
+    if (!(part in target) || typeof target[part] !== 'object' || target[part] === null) {
+      target[part] = {};
+    }
+    target = target[part];
+  }
+
+  const lastPart = parts[parts.length - 1];
+  target[lastPart] = value;
+
+  // Write the updated profile back to disk
+  fs.writeFileSync(CURRENT_FILE, JSON.stringify(profile, null, 2) + '\n');
+  context.output.out({ key: key, value: value });
+}
+
+module.exports = { meta, run };

package/src/commands/machine/show.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const meta = {
+  description: 'Display the current machine profile.',
+  arguments: [],
+  flags: []
+};
+
+/**
+ * Reads the current machine profile from ~/.devutils/machines/current.json
+ * and displays it. If the file does not exist, tells the user to run
+ * "dev machine detect" first.
+ *
+ * @param {object} args - Parsed command arguments (none expected).
+ * @param {object} context - The CLI context object with output and errors.
+ */
+async function run(args, context) {
+  const CURRENT_FILE = path.join(os.homedir(), '.devutils', 'machines', 'current.json');
+
+  if (!fs.existsSync(CURRENT_FILE)) {
+    context.errors.throwError(404, 'No machine profile found. Run "dev machine detect" first.', 'machine');
+    return;
+  }
+
+  const raw = fs.readFileSync(CURRENT_FILE, 'utf8');
+  const profile = JSON.parse(raw);
+
+  context.output.out(profile);
+}
+
+module.exports = { meta, run };

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