@fredlackey/devutils 0.0.18 → 0.1.0

package/src/commands/config/init.js

@@ -0,0 +1,143 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const DEVUTILS_DIR = path.join(os.homedir(), '.devutils');
+const CONFIG_FILE = path.join(DEVUTILS_DIR, 'config.json');
+
+const meta = {
+  description: 'First-run onboarding wizard. Sets up ~/.devutils/ and creates config.json.',
+  arguments: [],
+  flags: [
+    { name: 'force', type: 'boolean', description: 'Re-run setup even if already configured' },
+    { name: 'profile', type: 'string', description: 'Set the profile name (skip the prompt)' },
+  ],
+};
+
+/**
+ * Detects the user's shell config file path for PATH modification.
+ * @returns {{ shell: string, file: string }|null}
+ */
+function getShellConfig() {
+  const shell = process.env.SHELL || '';
+  const home = os.homedir();
+
+  if (shell.includes('zsh')) {
+    return { shell: 'zsh', file: path.join(home, '.zshrc') };
+  }
+  if (shell.includes('bash')) {
+    return { shell: 'bash', file: path.join(home, '.bashrc') };
+  }
+  if (shell.includes('fish')) {
+    return { shell: 'fish', file: path.join(home, '.config', 'fish', 'config.fish') };
+  }
+  return null;
+}
+
+/**
+ * Adds the devutils bin directory to the user's PATH via shell config.
+ * Idempotent: checks if the line is already present before adding.
+ * @param {string} shellFile - The shell config file path.
+ */
+function addToPathFile(shellFile) {
+  const exportLine = 'export PATH="$HOME/.devutils/bin:$PATH"';
+
+  // Create the file if it doesn't exist
+  if (!fs.existsSync(shellFile)) {
+    fs.mkdirSync(path.dirname(shellFile), { recursive: true });
+    fs.writeFileSync(shellFile, '', 'utf8');
+  }
+
+  const content = fs.readFileSync(shellFile, 'utf8');
+
+  // Check if the line is already there
+  if (content.includes('.devutils/bin')) {
+    return false; // Already present
+  }
+
+  fs.appendFileSync(shellFile, '\n# DevUtils CLI\n' + exportLine + '\n');
+  return true; // Added
+}
+
+async function run(args, context) {
+  // Check if already configured
+  if (fs.existsSync(CONFIG_FILE) && !args.flags.force) {
+    context.output.info('DevUtils is already configured. Use --force to re-run setup.');
+    return;
+  }
+
+  // Create the directory structure
+  fs.mkdirSync(path.join(DEVUTILS_DIR, 'machines'), { recursive: true });
+  fs.mkdirSync(path.join(DEVUTILS_DIR, 'bin'), { recursive: true });
+  fs.mkdirSync(path.join(DEVUTILS_DIR, 'auth'), { recursive: true });
+  fs.mkdirSync(path.join(DEVUTILS_DIR, 'plugins'), { recursive: true });
+  fs.mkdirSync(path.join(DEVUTILS_DIR, 'utils'), { recursive: true });
+  fs.mkdirSync(path.join(DEVUTILS_DIR, 'cache'), { recursive: true });
+
+  // Prompt for user info
+  const name = await context.prompt.ask('Your full name', '');
+  const email = await context.prompt.ask('Your email address', '');
+  const url = await context.prompt.ask('Your URL (optional)', '');
+
+  // Prompt for backup backend
+  const backupBackend = await context.prompt.choose(
+    'Where should DevUtils store configuration backups?',
+    ['repo', 'gist'],
+    0
+  );
+
+  // Prompt for profile name
+  const profile = args.flags.profile || await context.prompt.ask('Profile name for this machine', 'default');
+
+  // Build and write config
+  const config = {
+    user: {
+      name: name,
+      email: email,
+      url: url,
+    },
+    defaults: {
+      license: 'MIT',
+      packageManager: 'npm',
+    },
+    backup: {
+      backend: backupBackend,
+      location: null,
+    },
+    profile: profile,
+  };
+
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n');
+
+  // Offer to add ~/.devutils/bin to PATH
+  const shellConfig = getShellConfig();
+  if (shellConfig) {
+    const addToPath = await context.prompt.confirm(
+      'Add ~/.devutils/bin to your PATH? (required for aliases to work)',
+      true
+    );
+    if (addToPath) {
+      const added = addToPathFile(shellConfig.file);
+      if (added) {
+        context.output.info(`Added to ${shellConfig.file}. Restart your terminal or run: source ${shellConfig.file}`);
+      } else {
+        context.output.info('PATH entry already exists. No changes made.');
+      }
+    }
+  }
+
+  // Print summary
+  context.output.info('');
+  context.output.info('DevUtils configured successfully!');
+  context.output.info('');
+  context.output.info(`  Name:     ${name || '(not set)'}`);
+  context.output.info(`  Email:    ${email || '(not set)'}`);
+  context.output.info(`  Profile:  ${profile}`);
+  context.output.info(`  Backup:   ${backupBackend}`);
+  context.output.info(`  Config:   ${CONFIG_FILE}`);
+  context.output.info('');
+}
+
+module.exports = { meta, run };

package/src/commands/config/reset.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CONFIG_FILE = path.join(os.homedir(), '.devutils', 'config.json');
+
+const meta = {
+  description: 'Reset configuration to defaults. Clears user info and restores default settings.',
+  arguments: [],
+  flags: [
+    { name: 'confirm', type: 'boolean', description: 'Skip the confirmation prompt' },
+  ],
+};
+
+async function run(args, context) {
+  if (!fs.existsSync(CONFIG_FILE)) {
+    context.errors.throwError(404, 'Config not found. Nothing to reset.', 'config');
+    return;
+  }
+
+  // Ask for confirmation unless --confirm is passed
+  if (!args.flags.confirm) {
+    const proceed = await context.prompt.confirm(
+      'This will reset all configuration to defaults. Your user info will be cleared. Continue?',
+      false
+    );
+    if (!proceed) {
+      context.output.info('Reset cancelled.');
+      return;
+    }
+  }
+
+  // Write default config
+  const defaults = {
+    user: {
+      name: '',
+      email: '',
+      url: '',
+    },
+    defaults: {
+      license: 'MIT',
+      packageManager: 'npm',
+    },
+    backup: {
+      backend: null,
+      location: null,
+    },
+    profile: 'default',
+  };
+
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(defaults, null, 2) + '\n');
+  context.output.info('Configuration reset to defaults.');
+}
+
+module.exports = { meta, run };

package/src/commands/config/set.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CONFIG_FILE = path.join(os.homedir(), '.devutils', 'config.json');
+
+const meta = {
+  description: 'Write a config value by dot-notation key.',
+  arguments: [
+    { name: 'key', required: true, description: 'Dot-notation path to the config value (e.g., user.email)' },
+    { 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' },
+  ],
+};
+
+async function run(args, context) {
+  const key = args.positional[0];
+  const rawValue = args.positional[1];
+  const jsonValue = args.flags.json;
+
+  if (!key) {
+    context.errors.throwError(400, 'Missing required argument: <key>. Example: dev config set user.email fred@example.com', 'config');
+    return;
+  }
+
+  if (!rawValue && rawValue !== '' && !jsonValue) {
+    context.errors.throwError(400, 'Missing value. Provide a value or use --json for structured data.', 'config');
+    return;
+  }
+
+  if (rawValue && jsonValue) {
+    context.errors.throwError(400, 'Provide either a positional value or --json, not both.', 'config');
+    return;
+  }
+
+  // Parse the value
+  let value;
+  if (jsonValue) {
+    try {
+      value = JSON.parse(jsonValue);
+    } catch (err) {
+      context.errors.throwError(400, `Invalid JSON: ${err.message}`, 'config');
+      return;
+    }
+  } else {
+    // Coerce simple types
+    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 existing config
+  if (!fs.existsSync(CONFIG_FILE)) {
+    context.errors.throwError(404, 'Config not found. Run "dev config init" first.', 'config');
+    return;
+  }
+
+  const raw = fs.readFileSync(CONFIG_FILE, 'utf8');
+  const config = JSON.parse(raw);
+
+  // Set value by dot-notation key
+  const parts = key.split('.');
+  let target = config;
+
+  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 config back
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n');
+  context.output.out({ key: key, value: value });
+}
+
+module.exports = { meta, run };

package/src/commands/config/show.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CONFIG_FILE = path.join(os.homedir(), '.devutils', 'config.json');
+
+const meta = {
+  description: 'Display the current configuration.',
+  arguments: [],
+  flags: [
+    { name: 'profile', type: 'string', description: 'Show a specific profile instead of the active one' },
+  ],
+};
+
+async function run(args, context) {
+  if (!fs.existsSync(CONFIG_FILE)) {
+    context.errors.throwError(404, 'Config not found. Run "dev config init" first.', 'config');
+    return;
+  }
+
+  const raw = fs.readFileSync(CONFIG_FILE, 'utf8');
+  const config = JSON.parse(raw);
+
+  // Handle --profile flag
+  if (args.flags.profile && args.flags.profile !== config.profile) {
+    context.errors.throwError(404, `Profile "${args.flags.profile}" not found. Current profile is "${config.profile}".`, 'config');
+    return;
+  }
+
+  context.output.out(config);
+}
+
+module.exports = { meta, run };

package/src/commands/help.js

@@ -0,0 +1,338 @@
+'use strict';
+
+/**
+ * help command.
+ * Lists all services and top-level commands, or shows detailed help
+ * for a specific service or command when given arguments.
+ *
+ * Examples:
+ *   dev help              - List all services and top-level commands
+ *   dev help config       - List all commands in the config service
+ *   dev help config set   - Show detailed help for config set
+ *   dev help version      - Show help for the version command
+ */
+
+const path = require('path');
+
+const meta = {
+  description: 'Show usage information',
+  arguments: [
+    { name: 'command', description: 'Command path to get help for (e.g., config set)', required: false, variadic: true }
+  ],
+  flags: []
+};
+
+/**
+ * Known service directory names. Each one has an index.js that exports
+ * name, description, and a commands map.
+ * @type {string[]}
+ */
+const SERVICE_NAMES = [
+  'config', 'machine', 'identity', 'tools', 'ignore',
+  'util', 'alias', 'auth', 'api', 'ai', 'search'
+];
+
+/**
+ * Top-level commands (not inside a service folder). Each entry has a
+ * name and a description. Descriptions are read from the command's
+ * meta export when available, with fallbacks for stubs that haven't
+ * been filled in yet.
+ * @type {Array<{ name: string, fallback: string }>}
+ */
+const TOP_LEVEL_COMMANDS = [
+  { name: 'status',  fallback: 'Overall health check' },
+  { name: 'update',  fallback: 'Update DevUtils CLI' },
+  { name: 'version', fallback: 'Show the current installed version' },
+  { name: 'schema',  fallback: 'Show or validate config schema' },
+  { name: 'help',    fallback: 'Show usage information' },
+];
+
+/**
+ * Loads a service index.js and returns { name, description, commands }.
+ * Returns null if the service cannot be loaded.
+ *
+ * @param {string} serviceName - The service directory name (e.g., 'config').
+ * @returns {object|null}
+ */
+function loadService(serviceName) {
+  try {
+    return require(path.join(__dirname, serviceName, 'index'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Loads a top-level command module and returns it.
+ * Returns null if the module cannot be loaded.
+ *
+ * @param {string} commandName - The command file name (e.g., 'version').
+ * @returns {object|null}
+ */
+function loadTopLevelCommand(commandName) {
+  try {
+    return require(path.join(__dirname, commandName));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Gets the description for a top-level command. Reads from the command's
+ * meta.description if available, otherwise uses the fallback.
+ *
+ * @param {{ name: string, fallback: string }} entry - The top-level command entry.
+ * @returns {string}
+ */
+function getTopLevelDescription(entry) {
+  const cmd = loadTopLevelCommand(entry.name);
+  if (cmd && cmd.meta && cmd.meta.description) {
+    return cmd.meta.description;
+  }
+  return entry.fallback;
+}
+
+/**
+ * Builds a list of all services with their names and descriptions.
+ *
+ * @returns {Array<{ name: string, description: string }>}
+ */
+function buildServiceList() {
+  const services = [];
+  for (const name of SERVICE_NAMES) {
+    const svc = loadService(name);
+    if (svc) {
+      services.push({ name: svc.name, description: svc.description });
+    }
+  }
+  return services;
+}
+
+/**
+ * Builds a list of all top-level commands with their names and descriptions.
+ *
+ * @returns {Array<{ name: string, description: string }>}
+ */
+function buildTopLevelCommandList() {
+  return TOP_LEVEL_COMMANDS.map(entry => ({
+    name: entry.name,
+    description: getTopLevelDescription(entry),
+  }));
+}
+
+/**
+ * Pads a string to the given width with trailing spaces.
+ *
+ * @param {string} str - The string to pad.
+ * @param {number} width - The target width.
+ * @returns {string}
+ */
+function pad(str, width) {
+  return str + ' '.repeat(Math.max(0, width - str.length));
+}
+
+/**
+ * Shows the top-level help listing: all services and top-level commands.
+ *
+ * @param {object} context - The CLI context object.
+ */
+function showTopLevelHelp(context) {
+  const services = buildServiceList();
+  const commands = buildTopLevelCommandList();
+
+  if (context.flags.format === 'json') {
+    context.output.out({ services, commands });
+    return;
+  }
+
+  // Find the longest name for alignment
+  const allNames = [...services.map(s => s.name), ...commands.map(c => c.name)];
+  const maxLen = Math.max(...allNames.map(n => n.length));
+  const colWidth = maxLen + 4;
+
+  context.output.info('Usage: dev <service> <command> [arguments] [flags]');
+  context.output.info('');
+  context.output.info('Services:');
+  for (const svc of services) {
+    context.output.info(`  ${pad(svc.name, colWidth)}${svc.description}`);
+  }
+  context.output.info('');
+  context.output.info('Commands:');
+  for (const cmd of commands) {
+    context.output.info(`  ${pad(cmd.name, colWidth)}${cmd.description}`);
+  }
+  context.output.info('');
+  context.output.info('Run "dev help <service>" to see commands within a service.');
+  context.output.info('Run "dev help <service> <command>" for detailed command help.');
+}
+
+/**
+ * Shows help for a specific service, listing all its commands.
+ *
+ * @param {object} service - The service module (with name, description, commands).
+ * @param {object} context - The CLI context object.
+ */
+function showServiceHelp(service, context) {
+  const commandNames = Object.keys(service.commands || {});
+  const commandList = [];
+
+  for (const name of commandNames) {
+    let description = '';
+    try {
+      const cmd = service.commands[name]();
+      if (cmd && cmd.meta && cmd.meta.description) {
+        description = cmd.meta.description;
+      }
+    } catch {
+      // Command module may not be fully implemented yet
+    }
+    commandList.push({ name, description });
+  }
+
+  if (context.flags.format === 'json') {
+    context.output.out({
+      service: service.name,
+      description: service.description,
+      commands: commandList,
+    });
+    return;
+  }
+
+  const maxLen = Math.max(...commandList.map(c => c.name.length));
+  const colWidth = maxLen + 4;
+
+  context.output.info(`${service.name}: ${service.description}`);
+  context.output.info('');
+  context.output.info('Commands:');
+  for (const cmd of commandList) {
+    const desc = cmd.description ? `${pad(cmd.name, colWidth)}${cmd.description}` : cmd.name;
+    context.output.info(`  dev ${service.name} ${desc}`);
+  }
+  context.output.info('');
+  context.output.info(`Run "dev help ${service.name} <command>" for detailed help.`);
+}
+
+/**
+ * Shows detailed help for a specific command, including its description,
+ * arguments, and flags.
+ *
+ * @param {object} command - The command module (with meta.description, meta.arguments, meta.flags).
+ * @param {string} commandPath - The full command path for display (e.g., "config set").
+ * @param {object} context - The CLI context object.
+ */
+function showCommandHelp(command, commandPath, context) {
+  const m = command.meta || {};
+  const args = m.arguments || [];
+  const flags = m.flags || [];
+
+  if (context.flags.format === 'json') {
+    context.output.out({
+      command: commandPath,
+      description: m.description || '',
+      arguments: args,
+      flags: flags,
+    });
+    return;
+  }
+
+  context.output.info(`dev ${commandPath}`);
+  context.output.info('');
+  if (m.description) {
+    context.output.info(`  ${m.description}`);
+    context.output.info('');
+  }
+
+  if (args.length > 0) {
+    context.output.info('Arguments:');
+    const maxLen = Math.max(...args.map(a => a.name.length));
+    const colWidth = maxLen + 4;
+    for (const arg of args) {
+      const req = arg.required ? '(required)' : '(optional)';
+      context.output.info(`  ${pad(arg.name, colWidth)}${arg.description || ''} ${req}`);
+    }
+    context.output.info('');
+  }
+
+  if (flags.length > 0) {
+    context.output.info('Flags:');
+    const maxLen = Math.max(...flags.map(f => `--${f.name}`.length));
+    const colWidth = maxLen + 4;
+    for (const flag of flags) {
+      const name = `--${flag.name}`;
+      const parts = [flag.description || ''];
+      if (flag.type) {
+        parts.push(`(${flag.type})`);
+      }
+      if (flag.default !== undefined) {
+        parts.push(`[default: ${flag.default}]`);
+      }
+      context.output.info(`  ${pad(name, colWidth)}${parts.join(' ')}`);
+    }
+    context.output.info('');
+  }
+}
+
+/**
+ * Main entry point for the help command.
+ *
+ * @param {object} args - Parsed command arguments. Positional args are the command path.
+ * @param {object} context - The CLI context object.
+ */
+async function run(args, context) {
+  const positional = args.positional || [];
+
+  // No arguments: show top-level help
+  if (positional.length === 0) {
+    showTopLevelHelp(context);
+    return;
+  }
+
+  const firstName = positional[0];
+  const secondName = positional[1];
+
+  // Check if the first argument is a service name
+  const service = loadService(firstName);
+  if (service) {
+    if (!secondName) {
+      // Show service-level help (list all commands in the service)
+      showServiceHelp(service, context);
+      return;
+    }
+
+    // Show help for a specific command within the service
+    if (service.commands && service.commands[secondName]) {
+      try {
+        const cmd = service.commands[secondName]();
+        showCommandHelp(cmd, `${firstName} ${secondName}`, context);
+        return;
+      } catch {
+        // Fall through to unknown command error
+      }
+    }
+
+    // Unknown command within the service
+    const methods = Object.keys(service.commands || {}).join(', ');
+    context.errors.throwError(
+      404,
+      `Unknown command "${secondName}" for service "${firstName}". Available commands: ${methods}`,
+      'help'
+    );
+    return;
+  }
+
+  // Check if the first argument is a top-level command
+  const topCmd = loadTopLevelCommand(firstName);
+  if (topCmd) {
+    showCommandHelp(topCmd, firstName, context);
+    return;
+  }
+
+  // Unknown command
+  context.errors.throwError(
+    404,
+    `Unknown command "${firstName}". Run "dev help" to see available commands.`,
+    'help'
+  );
+}
+
+module.exports = { meta, run };