@fredlackey/devutils 0.0.19 → 0.1.0

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

package/src/commands/identity/add.js

@@ -0,0 +1,133 @@
+'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: 'Create a new identity profile.',
+  arguments: [
+    { name: 'name', description: 'Short name for this identity (e.g., personal, work)', required: true },
+  ],
+  flags: [
+    { name: 'email', description: 'Git author email (required)' },
+    { name: 'ssh-key', description: 'Path to SSH private key file' },
+    { name: 'gpg-key', description: 'GPG key ID for commit signing' },
+    { name: 'generate-key', description: 'Generate a new SSH key pair for this identity' },
+  ],
+};
+
+async function run(args, context) {
+  const identityName = args.positional[0];
+  if (!identityName) {
+    context.errors.throwError(400, 'Missing identity name. Usage: dev identity add <name> --email <email>', 'identity');
+    return;
+  }
+
+  // Validate name format
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(identityName)) {
+    context.errors.throwError(400, 'Identity name must be lowercase letters, numbers, and hyphens only.', 'identity');
+    return;
+  }
+
+  const email = args.flags.email;
+  if (!email) {
+    context.errors.throwError(400, 'Email is required. Use --email your@email.com.', 'identity');
+    return;
+  }
+
+  // Load config
+  if (!fs.existsSync(CONFIG_FILE)) {
+    context.errors.throwError(404, 'Config not found. Run "dev config init" first.', 'identity');
+    return;
+  }
+  const config = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+  const identities = config.identities || [];
+
+  // Check for duplicates (case-insensitive)
+  if (identities.some(id => id.name.toLowerCase() === identityName.toLowerCase())) {
+    context.errors.throwError(400, `Identity '${identityName}' already exists. Use a different name or remove it first.`, 'identity');
+    return;
+  }
+
+  // Handle SSH key
+  let sshKeyPath = null;
+  const sshKeyFlag = args.flags['ssh-key'];
+  const generateKey = args.flags['generate-key'];
+
+  if (sshKeyFlag && generateKey) {
+    context.errors.throwError(400, 'Provide either --ssh-key or --generate-key, not both.', 'identity');
+    return;
+  }
+
+  if (sshKeyFlag) {
+    const resolved = path.resolve(sshKeyFlag);
+    if (!fs.existsSync(resolved)) {
+      context.errors.throwError(404, `SSH key file not found: ${resolved}`, 'identity');
+      return;
+    }
+    sshKeyPath = resolved;
+  } else if (generateKey) {
+    sshKeyPath = await generateSshKey(identityName, email, context);
+    if (!sshKeyPath) return; // Error already reported
+  }
+
+  // Handle GPG key
+  const gpgKey = args.flags['gpg-key'] || null;
+
+  // Build identity
+  const identity = {
+    name: identityName,
+    email: email,
+    sshKey: sshKeyPath,
+    gpgKey: gpgKey,
+    folders: [],
+  };
+
+  // Save
+  identities.push(identity);
+  config.identities = identities;
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n');
+
+  context.output.info(`Identity '${identityName}' created.`);
+  context.output.out(identity);
+}
+
+/**
+ * Generates an ED25519 SSH key pair for the given identity.
+ * @param {string} name - The identity name (used in the key filename).
+ * @param {string} email - The email (used as the key comment).
+ * @param {object} context - The command context.
+ * @returns {Promise<string|null>} The key path, or null on failure.
+ */
+async function generateSshKey(name, email, context) {
+  const sshDir = path.join(os.homedir(), '.ssh');
+  if (!fs.existsSync(sshDir)) {
+    fs.mkdirSync(sshDir, { mode: 0o700 });
+  }
+
+  const keyPath = path.join(sshDir, `id_ed25519_${name}`);
+  if (fs.existsSync(keyPath)) {
+    context.errors.throwError(400, `SSH key already exists at ${keyPath}. Use --ssh-key ${keyPath} to reference it.`, 'identity');
+    return null;
+  }
+
+  const result = await context.shell.exec(
+    `ssh-keygen -t ed25519 -C "${email}" -f "${keyPath}" -N ""`
+  );
+
+  if (result.exitCode !== 0) {
+    context.errors.throwError(500, `Failed to generate SSH key: ${result.stderr}`, 'identity');
+    return null;
+  }
+
+  context.output.info(`SSH key generated: ${keyPath}`);
+  context.output.info(`Public key: ${keyPath}.pub`);
+  context.output.info('Add the public key to your GitHub account at https://github.com/settings/keys');
+
+  return keyPath;
+}
+
+module.exports = { meta, run };

package/src/commands/identity/index.js

@@ -0,0 +1,17 @@
+/**
+ * Identity service registration.
+ * Git identities, SSH keys, GPG signing.
+ */
+module.exports = {
+  name: 'identity',
+  description: 'Git identities, SSH keys, GPG signing',
+  commands: {
+    add:    () => require('./add'),
+    remove: () => require('./remove'),
+    list:   () => require('./list'),
+    show:   () => require('./show'),
+    link:   () => require('./link'),
+    unlink: () => require('./unlink'),
+    sync:   () => require('./sync'),
+  }
+};

package/src/commands/identity/link.js

@@ -0,0 +1,76 @@
+'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: 'Link an identity to a folder path.',
+  arguments: [
+    { name: 'name', description: 'Identity name', required: true },
+    { name: 'folder', description: 'Folder path to link (absolute or relative)', required: true },
+  ],
+  flags: [
+    { name: 'remote', description: 'Git remote hostname (default: github.com)' },
+  ],
+};
+
+async function run(args, context) {
+  const name = args.positional[0];
+  const folder = args.positional[1];
+
+  if (!name || !folder) {
+    context.errors.throwError(400, 'Usage: dev identity link <name> <folder> [--remote <host>]', 'identity');
+    return;
+  }
+
+  const absolutePath = path.resolve(folder);
+  if (!fs.existsSync(absolutePath)) {
+    context.errors.throwError(404, `Folder not found: ${absolutePath}`, 'identity');
+    return;
+  }
+
+  if (!fs.existsSync(CONFIG_FILE)) {
+    context.errors.throwError(404, 'Config not found. Run "dev config init" first.', 'identity');
+    return;
+  }
+  const config = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+  const identities = config.identities || [];
+
+  // Find the target identity
+  const identity = identities.find(id => id.name.toLowerCase() === name.toLowerCase());
+  if (!identity) {
+    context.errors.throwError(404, `Identity '${name}' not found.`, 'identity');
+    return;
+  }
+
+  const remote = args.flags.remote || 'github.com';
+
+  // Check if folder is linked to a different identity
+  for (const id of identities) {
+    const existing = (id.folders || []).find(f => f.path === absolutePath);
+    if (existing && id.name.toLowerCase() !== name.toLowerCase()) {
+      context.output.info(`Warning: Folder '${absolutePath}' is currently linked to identity '${id.name}'. Re-linking to '${identity.name}'.`);
+    }
+  }
+
+  // Remove folder from all identities (avoid duplicates)
+  for (const id of identities) {
+    id.folders = (id.folders || []).filter(f => f.path !== absolutePath);
+  }
+
+  // Add the link
+  identity.folders = identity.folders || [];
+  identity.folders.push({ path: absolutePath, remote });
+
+  // Save
+  config.identities = identities;
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n');
+
+  context.output.info(`Linked '${absolutePath}' to identity '${identity.name}' (remote: ${remote}).`);
+  context.output.info("Run 'dev identity sync' to apply changes to SSH and git config.");
+}
+
+module.exports = { meta, run };

package/src/commands/identity/list.js

@@ -0,0 +1,48 @@
+'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: 'List all configured identities.',
+  arguments: [],
+  flags: [],
+};
+
+async function run(args, context) {
+  if (!fs.existsSync(CONFIG_FILE)) {
+    context.errors.throwError(404, 'Config not found. Run "dev config init" first.', 'identity');
+    return;
+  }
+  const config = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+  const identities = config.identities || [];
+
+  if (identities.length === 0) {
+    context.output.info('No identities configured.');
+    context.output.info('');
+    context.output.info('Create one with:');
+    context.output.info('  dev identity add <name> --email <email>');
+    context.output.info('');
+    context.output.info('Example:');
+    context.output.info('  dev identity add personal --email fred@example.com');
+    return;
+  }
+
+  // Build table rows
+  const rows = identities.map(id => ({
+    Name: id.name,
+    Email: id.email,
+    'SSH Key': id.sshKey ? 'yes' : 'no',
+    'GPG Key': id.gpgKey ? 'yes' : 'no',
+    'Linked Folders': (id.folders || []).length,
+  }));
+
+  context.output.out(rows);
+  const count = identities.length;
+  context.output.info(`\n${count} ${count === 1 ? 'identity' : 'identities'} configured.`);
+}
+
+module.exports = { meta, run };

package/src/commands/identity/remove.js

@@ -0,0 +1,72 @@
+'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: 'Remove an identity profile.',
+  arguments: [
+    { name: 'name', description: 'Name of the identity to remove', required: true },
+  ],
+  flags: [
+    { name: 'confirm', description: 'Skip the confirmation prompt' },
+    { name: 'force', description: 'Remove even if the identity has linked folders' },
+  ],
+};
+
+async function run(args, context) {
+  const name = args.positional[0];
+  if (!name) {
+    context.errors.throwError(400, 'Missing identity name. Usage: dev identity remove <name>', 'identity');
+    return;
+  }
+
+  if (!fs.existsSync(CONFIG_FILE)) {
+    context.errors.throwError(404, 'Config not found. Run "dev config init" first.', 'identity');
+    return;
+  }
+  const config = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+  const identities = config.identities || [];
+
+  // Find the identity
+  const identity = identities.find(id => id.name.toLowerCase() === name.toLowerCase());
+  if (!identity) {
+    context.errors.throwError(404, `Identity '${name}' not found.`, 'identity');
+    return;
+  }
+
+  // Check for linked folders
+  const folders = identity.folders || [];
+  if (folders.length > 0 && !args.flags.force) {
+    const folderList = folders.map(f => `  ${f.path || f}`).join('\n');
+    context.errors.throwError(
+      400,
+      `Cannot remove identity '${identity.name}' because it has ${folders.length} linked folder(s):\n${folderList}\nUse --force to remove anyway, or unlink the folders first.`,
+      'identity'
+    );
+    return;
+  }
+
+  // Confirm
+  if (!args.flags.confirm) {
+    const proceed = await context.prompt.confirm(`Remove identity '${identity.name}'? This cannot be undone.`, false);
+    if (!proceed) {
+      context.output.info('Cancelled.');
+      return;
+    }
+  }
+
+  // Remove from array
+  config.identities = identities.filter(id => id.name.toLowerCase() !== name.toLowerCase());
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n');
+
+  context.output.info(`Identity '${identity.name}' removed.`);
+  if (identity.sshKey) {
+    context.output.info(`Note: SSH key at ${identity.sshKey} was not deleted. Remove it manually if no longer needed.`);
+  }
+}
+
+module.exports = { meta, run };