@fredlackey/devutils 0.0.18 → 0.1.0

package/src/commands/alias/add.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const { loadAliases, saveAliases, generateWrapper, BIN_DIR } = require('./helpers');
+
+const meta = {
+  description: 'Create a global shorthand command that maps to any dev command.',
+  arguments: [
+    { name: 'name', required: true, description: 'The alias name (what the user will type)' },
+    { name: 'command', required: true, description: 'The full command to run (quoted string)' }
+  ],
+  flags: [
+    { name: 'force', type: 'boolean', description: 'Overwrite an existing alias without prompting' }
+  ]
+};
+
+/**
+ * Creates a new alias by writing the mapping to aliases.json and generating
+ * a wrapper script in ~/.devutils/bin/.
+ *
+ * @param {object} args - Parsed command arguments (positional and flags).
+ * @param {object} context - The command context (output, prompt, errors, shell, platform).
+ */
+async function run(args, context) {
+  // Step 1: Parse arguments
+  // The first positional arg is the alias name. Everything after it is the command.
+  const name = args.positional[0];
+  const command = args.positional.slice(1).join(' ');
+
+  if (!name || !command) {
+    context.output.error('Usage: dev alias add <name> "<command>"');
+    context.output.error('');
+    context.output.error('Examples:');
+    context.output.error('  dev alias add gs "dev util run git-status"');
+    context.output.error('  dev alias add clone "dev util run clone"');
+    context.output.error('  dev alias add claude-danger "dev ai launch claude"');
+    return;
+  }
+
+  // Step 2: Validate the alias name
+  // Must be lowercase letters, numbers, and hyphens. Must start with a letter or number.
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) {
+    context.output.error('Alias names must be lowercase letters, numbers, and hyphens only.');
+    return;
+  }
+
+  // Step 3: Check for system command conflicts
+  // Use shell.which to see if the name matches an existing command on the system PATH.
+  // Exclude our own bin directory from the check so re-creating an alias is not a conflict.
+  const binDir = BIN_DIR;
+  const existingPath = context.shell.which(name);
+
+  if (existingPath && !existingPath.startsWith(binDir)) {
+    context.output.error(`Warning: "${name}" already exists on your system at ${existingPath}`);
+    context.output.error('Creating this alias will shadow the existing command.');
+
+    if (!args.flags.force) {
+      const proceed = await context.prompt.confirm(
+        'Create the alias anyway?',
+        false
+      );
+      if (!proceed) {
+        context.output.info('Cancelled.');
+        return;
+      }
+    }
+  }
+
+  // Step 4: Check for existing aliases
+  // If an alias with this name already exists, warn the user unless --force is set.
+  const aliases = loadAliases();
+
+  if (aliases[name] && !args.flags.force) {
+    context.output.error(`Alias "${name}" already exists: ${aliases[name]}`);
+    context.output.error('Use --force to overwrite it.');
+    return;
+  }
+
+  // Step 5: Write the alias to aliases.json
+  aliases[name] = command;
+  saveAliases(aliases);
+
+  // Step 6: Generate the wrapper script
+  const platform = context.platform.detect();
+  generateWrapper(name, command, binDir, platform.type);
+
+  // Step 7: Print confirmation
+  context.output.info(`Alias "${name}" created.`);
+  context.output.info(`  ${name} -> ${command}`);
+  context.output.info('');
+  context.output.info(`You can now run: ${name}`);
+}
+
+module.exports = { meta, run };

package/src/commands/alias/helpers.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+/**
+ * Path to the aliases.json file in the user's .devutils directory.
+ * This is the source of truth for all alias definitions.
+ * @type {string}
+ */
+const ALIASES_FILE = path.join(os.homedir(), '.devutils', 'aliases.json');
+
+/**
+ * Path to the bin directory where wrapper scripts are generated.
+ * This directory should be on the user's PATH.
+ * @type {string}
+ */
+const BIN_DIR = path.join(os.homedir(), '.devutils', 'bin');
+
+/**
+ * Reads aliases.json and returns the parsed object.
+ * Returns an empty object if the file does not exist or cannot be parsed.
+ *
+ * @returns {object} A flat object mapping alias names to command strings.
+ */
+function loadAliases() {
+  if (!fs.existsSync(ALIASES_FILE)) {
+    return {};
+  }
+  try {
+    return JSON.parse(fs.readFileSync(ALIASES_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Writes the aliases object to aliases.json.
+ * Creates the parent directory if it does not exist.
+ *
+ * @param {object} aliases - A flat object mapping alias names to command strings.
+ */
+function saveAliases(aliases) {
+  const dir = path.dirname(ALIASES_FILE);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(ALIASES_FILE, JSON.stringify(aliases, null, 2) + '\n');
+}
+
+/**
+ * Generates a wrapper script for an alias in the bin directory.
+ * On Unix (macOS, Linux, Git Bash), writes a shell script with exec.
+ * On Windows, writes a .cmd file.
+ *
+ * @param {string} name - The alias name (used as the filename).
+ * @param {string} command - The full command the alias maps to.
+ * @param {string} binDir - The directory to write the wrapper script into.
+ * @param {string} platformType - The platform type from platform.detect().type.
+ */
+function generateWrapper(name, command, binDir, platformType) {
+  if (!fs.existsSync(binDir)) {
+    fs.mkdirSync(binDir, { recursive: true });
+  }
+
+  if (platformType === 'windows') {
+    // Windows .cmd file
+    const scriptPath = path.join(binDir, name + '.cmd');
+    const content = `@${command} %*\r\n`;
+    fs.writeFileSync(scriptPath, content);
+  } else {
+    // Unix shell script (macOS, Linux, Git Bash)
+    const scriptPath = path.join(binDir, name);
+    const content = `#!/bin/sh\nexec ${command} "$@"\n`;
+    fs.writeFileSync(scriptPath, content, { mode: 0o755 });
+  }
+}
+
+/**
+ * Deletes wrapper scripts for an alias from the bin directory.
+ * Removes both Unix (no extension) and Windows (.cmd) formats to handle
+ * cross-platform scenarios.
+ *
+ * @param {string} name - The alias name to delete.
+ * @param {string} binDir - The directory containing the wrapper scripts.
+ */
+function deleteWrapper(name, binDir) {
+  const unixPath = path.join(binDir, name);
+  const windowsPath = path.join(binDir, name + '.cmd');
+
+  if (fs.existsSync(unixPath)) {
+    fs.unlinkSync(unixPath);
+  }
+  if (fs.existsSync(windowsPath)) {
+    fs.unlinkSync(windowsPath);
+  }
+}
+
+module.exports = {
+  ALIASES_FILE,
+  BIN_DIR,
+  loadAliases,
+  saveAliases,
+  generateWrapper,
+  deleteWrapper,
+};

package/src/commands/alias/index.js

@@ -0,0 +1,14 @@
+/**
+ * Alias service registration.
+ * Shorthand bin entries (user-controlled).
+ */
+module.exports = {
+  name: 'alias',
+  description: 'Shorthand bin entries (user-controlled)',
+  commands: {
+    add:    () => require('./add'),
+    remove: () => require('./remove'),
+    list:   () => require('./list'),
+    sync:   () => require('./sync'),
+  }
+};

package/src/commands/alias/list.js

@@ -0,0 +1,55 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { loadAliases, BIN_DIR } = require('./helpers');
+
+const meta = {
+  description: 'List all registered aliases and the commands they map to.',
+  arguments: [],
+  flags: []
+};
+
+/**
+ * Lists all registered aliases from aliases.json, sorted alphabetically.
+ * Shows a status indicator for aliases that are missing their wrapper script.
+ *
+ * @param {object} args - Parsed command arguments (positional and flags).
+ * @param {object} context - The command context (output).
+ */
+async function run(args, context) {
+  // Step 1: Load aliases.json
+  const aliases = loadAliases();
+  const entries = Object.entries(aliases);
+
+  // Step 2: Handle the empty case
+  if (entries.length === 0) {
+    context.output.info('No aliases registered.');
+    context.output.info('');
+    context.output.info('Create one with: dev alias add <name> "<command>"');
+    context.output.info('Example: dev alias add gs "dev util run git-status"');
+    return;
+  }
+
+  // Step 3: Sort alphabetically by name
+  entries.sort((a, b) => a[0].localeCompare(b[0]));
+
+  // Step 4: Display the aliases
+  const binDir = BIN_DIR;
+
+  context.output.info(`Aliases (${entries.length}):`);
+  context.output.info('');
+
+  for (const [name, command] of entries) {
+    // Check if the wrapper script exists (either Unix or Windows format)
+    const scriptExists = fs.existsSync(path.join(binDir, name))
+      || fs.existsSync(path.join(binDir, name + '.cmd'));
+    const status = scriptExists ? '' : ' (no script -- run dev alias sync)';
+    const nameCol = name.padEnd(25);
+    context.output.info(`  ${nameCol} -> ${command}${status}`);
+  }
+
+  context.output.info('');
+}
+
+module.exports = { meta, run };

package/src/commands/alias/remove.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const { loadAliases, saveAliases, deleteWrapper, BIN_DIR } = require('./helpers');
+
+const meta = {
+  description: 'Remove an alias and delete its wrapper script from ~/.devutils/bin/.',
+  arguments: [
+    { name: 'name', required: true, description: 'The alias name to remove' }
+  ],
+  flags: [
+    { name: 'confirm', type: 'boolean', description: 'Skip the confirmation prompt' }
+  ]
+};
+
+/**
+ * Removes an alias by deleting its entry from aliases.json and removing
+ * the wrapper script from ~/.devutils/bin/.
+ *
+ * @param {object} args - Parsed command arguments (positional and flags).
+ * @param {object} context - The command context (output, prompt, errors).
+ */
+async function run(args, context) {
+  // Step 1: Validate the name and check it exists
+  const name = args.positional[0];
+  if (!name) {
+    context.output.error('Usage: dev alias remove <name>');
+    return;
+  }
+
+  const aliases = loadAliases();
+
+  if (!aliases[name]) {
+    context.output.error(`Alias "${name}" is not registered.`);
+    context.output.error('Run "dev alias list" to see all aliases.');
+    return;
+  }
+
+  // Step 2: Confirm removal unless --confirm flag is set
+  if (!args.flags.confirm) {
+    const ok = await context.prompt.confirm(
+      `Remove alias "${name}" (${aliases[name]})?`,
+      true
+    );
+    if (!ok) {
+      context.output.info('Cancelled.');
+      return;
+    }
+  }
+
+  // Step 3: Delete the wrapper script (both Unix and Windows formats)
+  const binDir = BIN_DIR;
+  deleteWrapper(name, binDir);
+
+  // Step 4: Remove from aliases.json
+  delete aliases[name];
+  saveAliases(aliases);
+
+  // Step 5: Print confirmation
+  context.output.info(`Alias "${name}" removed.`);
+}
+
+module.exports = { meta, run };

package/src/commands/alias/sync.js

@@ -0,0 +1,109 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { loadAliases, generateWrapper, BIN_DIR } = require('./helpers');
+
+const meta = {
+  description: 'Rebuild all alias wrapper scripts from aliases.json. Cleans up orphaned scripts.',
+  arguments: [],
+  flags: [
+    { name: 'dry-run', type: 'boolean', description: 'Show what would be done without doing it' }
+  ]
+};
+
+/**
+ * Regenerates all wrapper scripts from aliases.json and removes orphaned
+ * scripts that no longer have a matching alias entry. This is the repair
+ * command for the alias system -- after importing config on a new machine,
+ * run sync to rebuild all the wrapper scripts.
+ *
+ * @param {object} args - Parsed command arguments (positional and flags).
+ * @param {object} context - The command context (output, platform, flags).
+ */
+async function run(args, context) {
+  // Step 1: Load aliases.json
+  const aliases = loadAliases();
+
+  // Step 2: Ensure the bin directory exists
+  const binDir = BIN_DIR;
+  if (!fs.existsSync(binDir)) {
+    fs.mkdirSync(binDir, { recursive: true });
+  }
+
+  // Step 3: Scan existing scripts in the bin directory
+  const existingFiles = fs.readdirSync(binDir);
+
+  // Step 4: Determine what to create and what to remove
+  const platform = context.platform.detect();
+
+  // Find orphans: files in bin/ that are not in aliases.json
+  const orphans = existingFiles.filter(file => {
+    // Strip .cmd extension for comparison
+    const baseName = file.endsWith('.cmd') ? file.slice(0, -4) : file;
+    return !aliases[baseName];
+  });
+
+  // Find missing: aliases that do not have a wrapper script yet
+  const missing = Object.keys(aliases).filter(name => {
+    return !fs.existsSync(path.join(binDir, name))
+      && !fs.existsSync(path.join(binDir, name + '.cmd'));
+  });
+
+  // Step 5: Handle dry-run mode
+  // --dry-run is a global flag (context.flags.dryRun) or a command flag (args.flags['dry-run'])
+  const isDryRun = context.flags.dryRun || args.flags['dry-run'];
+
+  if (isDryRun) {
+    if (missing.length === 0 && orphans.length === 0) {
+      context.output.info('Everything is in sync. Nothing to do.');
+      return;
+    }
+
+    if (missing.length > 0) {
+      context.output.info(`Would create ${missing.length} wrapper script(s):`);
+      for (const name of missing) {
+        context.output.info(`  + ${name} -> ${aliases[name]}`);
+      }
+    }
+
+    if (orphans.length > 0) {
+      context.output.info(`Would remove ${orphans.length} orphaned script(s):`);
+      for (const file of orphans) {
+        context.output.info(`  - ${file}`);
+      }
+    }
+    return;
+  }
+
+  // Step 6: Generate all wrapper scripts
+  // Regenerate every script (not just missing ones) to ensure they are all up to date.
+  // This handles cases where the command mapping changed in aliases.json.
+  let created = 0;
+  for (const [name, command] of Object.entries(aliases)) {
+    generateWrapper(name, command, binDir, platform.type);
+    created++;
+  }
+
+  // Step 7: Remove orphaned scripts
+  let removed = 0;
+  for (const file of orphans) {
+    const filePath = path.join(binDir, file);
+    fs.unlinkSync(filePath);
+    removed++;
+  }
+
+  // Step 8: Report results
+  context.output.info('Alias sync complete.');
+  context.output.info(`  ${created} script(s) generated`);
+  if (removed > 0) {
+    context.output.info(`  ${removed} orphaned script(s) removed`);
+  }
+  context.output.info('');
+
+  if (created > 0) {
+    context.output.info('Make sure ~/.devutils/bin is in your PATH.');
+  }
+}
+
+module.exports = { meta, run };

package/src/commands/api/disable.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const fs = require('fs');
+const shell = require('../../lib/shell');
+const loader = require('../../api/loader');
+
+const meta = {
+  description: 'Remove an installed API plugin',
+  arguments: [
+    { name: 'name', description: 'Plugin name to remove', required: true }
+  ],
+  flags: [
+    { name: 'confirm', type: 'boolean', description: 'Skip confirmation prompt' }
+  ]
+};
+
+/**
+ * Removes an installed API plugin.
+ * Runs npm uninstall, removes the entry from plugins.json,
+ * and asks for confirmation unless --confirm is passed.
+ *
+ * @param {object} args - Parsed CLI arguments { positional, flags }.
+ * @param {object} context - CLI context { output, errors, prompt }.
+ */
+async function run(args, context) {
+  const pluginName = args.positional[0];
+
+  if (!pluginName) {
+    context.errors.throwError(400, 'Missing required argument: <name>. Example: dev api disable gmail', 'api');
+    return;
+  }
+
+  // Check if the plugin is installed
+  const plugins = loader.readPluginsJson();
+  const entry = plugins[pluginName];
+
+  if (!entry) {
+    context.output.info(`Plugin "${pluginName}" is not installed.`);
+    return;
+  }
+
+  // Ask for confirmation unless --confirm is passed
+  if (!args.flags.confirm) {
+    const ok = await context.prompt.confirm(
+      `Remove plugin "${pluginName}" (${entry.package})?`,
+      false
+    );
+    if (!ok) {
+      context.output.info('Cancelled.');
+      return;
+    }
+  }
+
+  // Run npm uninstall
+  const result = await shell.exec(`npm uninstall ${entry.package}`, { cwd: loader.PLUGINS_DIR });
+
+  if (result.exitCode !== 0) {
+    context.errors.throwError(
+      500,
+      `Failed to uninstall plugin "${pluginName}".\n${result.stderr || result.stdout}`,
+      'api'
+    );
+    return;
+  }
+
+  // Remove the entry from plugins.json
+  delete plugins[pluginName];
+  fs.writeFileSync(loader.PLUGINS_FILE, JSON.stringify(plugins, null, 2) + '\n');
+
+  context.output.info(`Plugin "${pluginName}" removed.`);
+}
+
+module.exports = { meta, run };

package/src/commands/api/enable.js

@@ -0,0 +1,148 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const shell = require('../../lib/shell');
+const loader = require('../../api/loader');
+
+const meta = {
+  description: 'Install an API plugin from npm or a git repository',
+  arguments: [
+    { name: 'name', description: 'Plugin name or full package name', required: true }
+  ],
+  flags: [
+    { name: 'source', type: 'string', description: 'Install source type: "npm" or "git" (default: npm)' },
+    { name: 'url', type: 'string', description: 'Package name or git URL when using a non-registry plugin' }
+  ]
+};
+
+/**
+ * Installs an API plugin from npm or a git repository.
+ * Resolves short names (like "gmail") through the registry, or accepts
+ * full package names (starting with "@") and git URLs directly.
+ *
+ * @param {object} args - Parsed CLI arguments { positional, flags }.
+ * @param {object} context - CLI context { output, errors, prompt }.
+ */
+async function run(args, context) {
+  const pluginName = args.positional[0];
+
+  if (!pluginName) {
+    context.errors.throwError(400, 'Missing required argument: <name>. Example: dev api enable gmail', 'api');
+    return;
+  }
+
+  // Resolve the package name from the registry or direct input
+  const registry = loader.getRegistryPlugins();
+  const registryEntry = registry.find(entry => entry.name === pluginName);
+  let packageName;
+
+  if (registryEntry) {
+    // Found in registry - use the registry package name
+    packageName = registryEntry.package;
+  } else if (args.flags.url) {
+    // Not in registry but user provided a URL/package name
+    packageName = args.flags.url;
+  } else if (pluginName.startsWith('@') || pluginName.includes('/')) {
+    // Looks like a scoped npm package or git URL - use directly
+    packageName = pluginName;
+  } else {
+    context.errors.throwError(
+      404,
+      `Plugin "${pluginName}" not found in the registry. Use --source git --url <git-url> to install from a git repository, or --url <package-name> to install a non-registry npm package.`,
+      'api'
+    );
+    return;
+  }
+
+  // Check if already installed
+  const installed = loader.readPluginsJson();
+  if (installed[pluginName]) {
+    context.output.info(
+      `Plugin "${pluginName}" is already installed (version ${installed[pluginName].version || 'unknown'}). Use "dev api update ${pluginName}" to update.`
+    );
+    return;
+  }
+
+  // Ensure the plugins directory exists with a package.json
+  const pluginsDir = loader.PLUGINS_DIR;
+  const pkgJsonPath = path.join(pluginsDir, 'package.json');
+
+  if (!fs.existsSync(pkgJsonPath)) {
+    fs.mkdirSync(pluginsDir, { recursive: true });
+    fs.writeFileSync(pkgJsonPath, JSON.stringify({
+      name: 'devutils-plugins',
+      version: '1.0.0',
+      private: true,
+      description: 'DevUtils CLI plugin packages'
+    }, null, 2) + '\n');
+  }
+
+  // Determine the install target
+  const installTarget = args.flags.url || packageName;
+
+  // Run npm install
+  context.output.info(`Installing ${pluginName} (${installTarget})...`);
+  const result = await shell.exec(`npm install ${installTarget}`, { cwd: pluginsDir });
+
+  if (result.exitCode !== 0) {
+    context.errors.throwError(
+      500,
+      `Failed to install plugin "${pluginName}".\n${result.stderr || result.stdout}`,
+      'api'
+    );
+    return;
+  }
+
+  // Read the installed version from the plugin's package.json
+  let installedVersion = 'unknown';
+  try {
+    const pluginPkgPath = path.join(pluginsDir, 'node_modules', packageName, 'package.json');
+    const pluginPkg = JSON.parse(fs.readFileSync(pluginPkgPath, 'utf8'));
+    installedVersion = pluginPkg.version || 'unknown';
+  } catch (err) {
+    // Could not read version, continue with 'unknown'
+  }
+
+  // Update plugins.json
+  const plugins = loader.readPluginsJson();
+  const sourceType = args.flags.source || 'npm';
+  plugins[pluginName] = {
+    package: packageName,
+    version: installedVersion,
+    source: sourceType,
+    installedAt: new Date().toISOString()
+  };
+
+  // Only store the URL if one was explicitly provided
+  if (args.flags.url) {
+    plugins[pluginName].url = args.flags.url;
+  }
+
+  // Ensure the parent directory exists for plugins.json
+  const pluginsFileDir = path.dirname(loader.PLUGINS_FILE);
+  if (!fs.existsSync(pluginsFileDir)) {
+    fs.mkdirSync(pluginsFileDir, { recursive: true });
+  }
+
+  fs.writeFileSync(loader.PLUGINS_FILE, JSON.stringify(plugins, null, 2) + '\n');
+
+  // Validate the plugin contract
+  const loadResult = loader.loadPlugin(pluginName);
+  if (loadResult.error) {
+    context.output.info(
+      `Warning: Plugin installed but does not follow the expected contract. It may not work correctly.\n${loadResult.message}`
+    );
+  }
+
+  // Print success
+  context.output.info(`Plugin "${pluginName}" installed (v${installedVersion}).`);
+
+  // Show auth hint if available from the registry entry
+  const authService = registryEntry ? registryEntry.auth : null;
+  if (authService) {
+    context.output.info(`This plugin requires "${authService}" authentication. Run "dev auth login ${authService}" if you haven't already.`);
+  }
+}
+
+module.exports = { meta, run };

package/src/commands/api/index.js

@@ -0,0 +1,15 @@
+/**
+ * API service registration.
+ * API plugin system — manages plugin installation, removal, and updates.
+ * Plugin commands are loaded at runtime from ~/.devutils/plugins/.
+ */
+module.exports = {
+  name: 'api',
+  description: 'API plugin system',
+  commands: {
+    list:    () => require('./list'),
+    enable:  () => require('./enable'),
+    disable: () => require('./disable'),
+    update:  () => require('./update'),
+  }
+};