@fredlackey/devutils 0.0.19 → 0.1.0

package/src/commands/ai/set.js

@@ -0,0 +1,131 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { AI_TOOLS } = require('./tools');
+
+const AI_CONFIG_FILE = path.join(os.homedir(), '.devutils', 'ai.json');
+
+/**
+ * Reads ~/.devutils/ai.json and returns its contents.
+ * Returns an empty object if the file does not exist or is unreadable.
+ *
+ * @returns {object} The parsed AI config, or {}.
+ */
+function readAiConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(AI_CONFIG_FILE, 'utf8'));
+  } catch (err) {
+    return {};
+  }
+}
+
+const VALID_KEYS = ['mode', 'model', 'flags'];
+
+const meta = {
+  description: 'Set a default configuration value for an AI tool',
+  arguments: [
+    { name: 'tool', description: 'AI tool name (e.g., claude, gemini)', required: true },
+    { name: 'key', description: 'Configuration key to set (mode, model, flags)', required: true },
+    { name: 'value', description: 'Value to set', required: true }
+  ],
+  flags: []
+};
+
+/**
+ * Sets a default configuration value for a specified AI tool.
+ * Validates the tool name, key, and value before writing to ai.json.
+ *
+ * @param {object} args - Parsed CLI arguments { positional, flags }.
+ * @param {object} context - CLI context { output, errors }.
+ */
+async function run(args, context) {
+  const toolName = args.positional[0];
+  const key = args.positional[1];
+  const rawValue = args.positional[2];
+
+  if (!toolName) {
+    context.errors.throwError(400, 'Missing required argument: <tool>. Example: dev ai set claude mode danger', 'ai');
+    return;
+  }
+
+  if (!key) {
+    context.errors.throwError(400, 'Missing required argument: <key>. Example: dev ai set claude mode danger', 'ai');
+    return;
+  }
+
+  if (rawValue === undefined || rawValue === null) {
+    context.errors.throwError(400, 'Missing required argument: <value>. Example: dev ai set claude mode danger', 'ai');
+    return;
+  }
+
+  // Validate the tool name
+  const toolConfig = AI_TOOLS[toolName];
+  if (!toolConfig) {
+    const available = Object.keys(AI_TOOLS).join(', ');
+    context.output.info(`Unknown AI tool "${toolName}". Available: ${available}`);
+    return;
+  }
+
+  // Validate the key
+  if (!VALID_KEYS.includes(key)) {
+    context.output.info(`Unknown configuration key "${key}". Valid keys: ${VALID_KEYS.join(', ')}`);
+    return;
+  }
+
+  // Validate and parse the value based on the key
+  let parsedValue;
+
+  if (key === 'mode') {
+    // Mode must be one of the tool's known modes
+    const availableModes = Object.keys(toolConfig.modes);
+    if (!availableModes.includes(rawValue)) {
+      context.output.info(
+        `Unknown mode "${rawValue}" for ${toolConfig.displayName}. Available modes: ${availableModes.join(', ')}`
+      );
+      return;
+    }
+    parsedValue = rawValue;
+  } else if (key === 'model') {
+    // "none" or "null" clears the model
+    if (rawValue === 'none' || rawValue === 'null') {
+      parsedValue = null;
+    } else {
+      parsedValue = rawValue;
+    }
+  } else if (key === 'flags') {
+    // Parse as a comma-separated list, trim whitespace, reject empty strings
+    parsedValue = rawValue
+      .split(',')
+      .map(flag => flag.trim())
+      .filter(flag => flag.length > 0);
+  }
+
+  // Read the current config (or start fresh)
+  const aiConfig = readAiConfig();
+  if (!aiConfig[toolName]) {
+    aiConfig[toolName] = {};
+  }
+  aiConfig[toolName][key] = parsedValue;
+
+  // Ensure the parent directory exists
+  const configDir = path.dirname(AI_CONFIG_FILE);
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true });
+  }
+
+  // Write the updated config
+  fs.writeFileSync(AI_CONFIG_FILE, JSON.stringify(aiConfig, null, 2) + '\n');
+
+  // Print confirmation
+  if (key === 'model' && parsedValue === null) {
+    context.output.info(`Set ${toolName}.${key} = (cleared)`);
+  } else if (key === 'flags') {
+    context.output.info(`Set ${toolName}.${key} = ${JSON.stringify(parsedValue)}`);
+  } else {
+    context.output.info(`Set ${toolName}.${key} = ${parsedValue}`);
+  }
+}
+
+module.exports = { meta, run };

package/src/commands/ai/show.js

@@ -0,0 +1,74 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const shell = require('../../lib/shell');
+const { AI_TOOLS } = require('./tools');
+
+const AI_CONFIG_FILE = path.join(os.homedir(), '.devutils', 'ai.json');
+
+/**
+ * Reads ~/.devutils/ai.json and returns its contents.
+ * Returns an empty object if the file does not exist or is unreadable.
+ *
+ * @returns {object} The parsed AI config, or {}.
+ */
+function readAiConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(AI_CONFIG_FILE, 'utf8'));
+  } catch (err) {
+    return {};
+  }
+}
+
+const meta = {
+  description: 'Show the current configuration for an AI tool',
+  arguments: [
+    { name: 'tool', description: 'AI tool name (e.g., claude, gemini)', required: true }
+  ],
+  flags: []
+};
+
+/**
+ * Displays the current configuration for a specified AI tool.
+ * Shows defaults when no configuration has been set yet.
+ *
+ * @param {object} args - Parsed CLI arguments { positional, flags }.
+ * @param {object} context - CLI context { output, errors }.
+ */
+async function run(args, context) {
+  const toolName = args.positional[0];
+
+  if (!toolName) {
+    context.errors.throwError(400, 'Missing required argument: <tool>. Example: dev ai show claude', 'ai');
+    return;
+  }
+
+  // Validate the tool name
+  const toolConfig = AI_TOOLS[toolName];
+  if (!toolConfig) {
+    const available = Object.keys(AI_TOOLS).join(', ');
+    context.output.info(`Unknown AI tool "${toolName}". Available: ${available}`);
+    return;
+  }
+
+  // Read the user's config, falling back to defaults
+  const aiConfig = readAiConfig();
+  const config = aiConfig[toolName] || {};
+
+  const result = {
+    tool: toolName,
+    displayName: toolConfig.displayName,
+    binary: toolConfig.binary,
+    installed: shell.commandExists(toolConfig.binary),
+    mode: config.mode || 'default',
+    model: config.model || '(not set)',
+    flags: config.flags || [],
+    availableModes: Object.keys(toolConfig.modes)
+  };
+
+  context.output.out(result);
+}
+
+module.exports = { meta, run };

package/src/commands/ai/tools.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const path = require('path');
+const os = require('os');
+
+/**
+ * Registry of known AI coding tools.
+ * Maps tool names to their CLI configuration, including binary names,
+ * mode flags, session storage paths, and display names.
+ *
+ * Adding a new AI tool is just adding an entry here.
+ */
+const AI_TOOLS = {
+  claude: {
+    binary: 'claude',
+    modes: {
+      default: [],
+      danger: ['--dangerously-skip-permissions']
+    },
+    modelFlag: '--model',
+    promptFlag: '--prompt',
+    resumeFlag: '--resume',
+    displayName: 'Claude Code',
+    sessionPaths: [
+      path.join(os.homedir(), '.claude', 'projects'),
+      path.join(os.homedir(), '.config', 'claude', 'projects')
+    ]
+  },
+  gemini: {
+    binary: 'gemini',
+    modes: {
+      default: [],
+      yolo: ['--sandbox=false']
+    },
+    modelFlag: '--model',
+    promptFlag: '--prompt',
+    resumeFlag: '--resume',
+    displayName: 'Gemini CLI',
+    sessionPaths: [
+      path.join(os.homedir(), '.gemini', 'sessions'),
+      path.join(os.homedir(), '.config', 'gemini', 'sessions')
+    ]
+  }
+};
+
+module.exports = { AI_TOOLS };

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