@fredlackey/devutils 0.0.19 → 0.1.0

package/src/cli.js

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Command router. Parses arguments, resolves the service and method, applies
+ * global flags, runs output format detection, and dispatches to the right
+ * command file.
+ *
+ * This file should not contain business logic. It's routing only.
+ */
+
+const TOP_LEVEL_COMMANDS = ['status', 'update', 'version', 'schema', 'help'];
+
+/**
+ * Extracts global flags from the argument list and returns the remaining args.
+ * Global flags can appear anywhere in the argument list.
+ *
+ * @param {string[]} args - Raw arguments from process.argv.slice(2).
+ * @returns {{ flags: object, remaining: string[] }}
+ */
+function parseGlobalFlags(args) {
+  const flags = {
+    format: null,
+    dryRun: false,
+    verbose: false,
+    quiet: false,
+    help: false,
+    version: false,
+    jsonInput: null,
+  };
+
+  const remaining = [];
+  let i = 0;
+
+  while (i < args.length) {
+    const arg = args[i];
+
+    if (arg === '--format' && i + 1 < args.length) {
+      flags.format = args[i + 1];
+      i += 2;
+    } else if (arg === '--dry-run') {
+      flags.dryRun = true;
+      i++;
+    } else if (arg === '--verbose') {
+      flags.verbose = true;
+      i++;
+    } else if (arg === '--quiet') {
+      flags.quiet = true;
+      i++;
+    } else if (arg === '--help' || arg === '-h') {
+      flags.help = true;
+      i++;
+    } else if (arg === '--version' || arg === '-v') {
+      flags.version = true;
+      i++;
+    } else if (arg === '--json' && i + 1 < args.length) {
+      flags.jsonInput = args[i + 1];
+      i += 2;
+    } else {
+      remaining.push(arg);
+      i++;
+    }
+  }
+
+  return { flags, remaining };
+}
+
+/**
+ * Parses remaining command arguments into a structured object.
+ * --key value pairs go into flags, everything else into positional.
+ *
+ * @param {string[]} rawArgs - Arguments after service/method have been stripped.
+ * @returns {{ positional: string[], flags: object }}
+ */
+function parseCommandArgs(rawArgs) {
+  const positional = [];
+  const flags = {};
+  let i = 0;
+
+  while (i < rawArgs.length) {
+    const arg = rawArgs[i];
+
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+
+      // Check if next arg exists and is not itself a flag
+      if (i + 1 < rawArgs.length && !rawArgs[i + 1].startsWith('--')) {
+        flags[key] = rawArgs[i + 1];
+        i += 2;
+      } else {
+        flags[key] = true;
+        i++;
+      }
+    } else {
+      positional.push(arg);
+      i++;
+    }
+  }
+
+  return { positional, flags };
+}
+
+/**
+ * Displays the CLI help message listing all services, commands, and global flags.
+ */
+function showHelp() {
+  const pkg = require('../package.json');
+  console.log(`DevUtils CLI v${pkg.version}`);
+  console.log('');
+  console.log('Usage: dev <service> <method> [arguments] [flags]');
+  console.log('');
+  console.log('Services:');
+  console.log('  config      User configuration and onboarding');
+  console.log('  machine     Machine profiles and detection');
+  console.log('  identity    Git identities, SSH keys, GPG signing');
+  console.log('  tools       Tool installation and management');
+  console.log('  ignore      .gitignore pattern management');
+  console.log('  util        Utility functions');
+  console.log('  alias       Shorthand bin entries');
+  console.log('  auth        OAuth and credential management');
+  console.log('  api         API plugin system');
+  console.log('  ai          AI coding assistant launcher');
+  console.log('  search      Markdown search');
+  console.log('');
+  console.log('Commands:');
+  console.log('  status      Overall health check');
+  console.log('  version     Show current version');
+  console.log('  help        Show this help message');
+  console.log('');
+  console.log('Global Flags:');
+  console.log('  --format <json|table|yaml|csv>  Output format');
+  console.log('  --dry-run                       Show what would happen');
+  console.log('  --verbose                       Increase output detail');
+  console.log('  --quiet                         Suppress non-essential output');
+  console.log('  --json <data>                   Pass structured input as JSON');
+  console.log('  --help, -h                      Show help');
+  console.log('  --version, -v                   Show version');
+}
+
+/**
+ * Resolves a command from the remaining arguments.
+ * Checks top-level commands first, then service/method routing.
+ *
+ * @param {string[]} remaining - Arguments with global flags stripped.
+ * @returns {object|null} The resolved command, args, and optional service.
+ */
+function resolveCommand(remaining) {
+  const serviceName = remaining[0];
+  const methodName = remaining[1];
+  const commandArgs = remaining.slice(2);
+
+  // Check for top-level command first
+  if (TOP_LEVEL_COMMANDS.includes(serviceName)) {
+    try {
+      const cmd = require(`./commands/${serviceName}`);
+      return { command: cmd, args: parseCommandArgs(remaining.slice(1)) };
+    } catch {
+      return null;
+    }
+  }
+
+  // Try to load the service index
+  let service;
+  try {
+    service = require(`./commands/${serviceName}/index`);
+  } catch {
+    return null;
+  }
+
+  // If no method specified, show service help
+  if (!methodName) {
+    return { service, command: null, args: parseCommandArgs([]) };
+  }
+
+  // Look up the method in the service's commands
+  if (!service.commands || !service.commands[methodName]) {
+    return { service, command: null, unknownMethod: methodName, args: parseCommandArgs(commandArgs) };
+  }
+
+  // Lazy-load the command
+  const command = service.commands[methodName]();
+  return { command, args: parseCommandArgs(commandArgs), service };
+}
+
+/**
+ * Builds the context object that every command receives.
+ * Contains all foundation modules pre-configured for the current invocation.
+ *
+ * @param {object} flags - The parsed global flags.
+ * @returns {object} The context object.
+ */
+function buildContext(flags) {
+  const detect = require('./lib/detect');
+  const output = require('./lib/output');
+  const errors = require('./lib/errors');
+  const platform = require('./lib/platform');
+  const shell = require('./lib/shell');
+  const config = require('./lib/config');
+  const prompt = require('./lib/prompt');
+
+  // Determine output format: flag override > detection
+  const detected = detect.detectOutputMode();
+  const format = flags.format || detected.format;
+  const caller = detected.caller;
+
+  // Create pre-configured formatter
+  const formatter = output.createFormatter({ format, caller });
+
+  let jsonInput = null;
+  if (flags.jsonInput) {
+    try {
+      jsonInput = JSON.parse(flags.jsonInput);
+    } catch {
+      jsonInput = null;
+    }
+  }
+
+  return {
+    platform,
+    shell,
+    config,
+    prompt,
+    errors,
+    output: formatter,
+    flags: {
+      format,
+      caller,
+      dryRun: flags.dryRun,
+      verbose: flags.verbose,
+      quiet: flags.quiet,
+      jsonInput,
+    },
+  };
+}
+
+/**
+ * Main entry point. Parses args, resolves the command, builds context, and runs.
+ */
+async function main() {
+  const { flags, remaining } = parseGlobalFlags(process.argv.slice(2));
+
+  // Handle --version
+  if (flags.version) {
+    const pkg = require('../package.json');
+    console.log(pkg.version);
+    return;
+  }
+
+  // Handle --help or no arguments
+  if (flags.help || remaining.length === 0) {
+    showHelp();
+    return;
+  }
+
+  // Resolve the command
+  const resolved = resolveCommand(remaining);
+
+  if (!resolved || !resolved.command) {
+    const errors = require('./lib/errors');
+    if (resolved && resolved.unknownMethod) {
+      const methods = Object.keys(resolved.service.commands || {}).join(', ');
+      errors.throwError(
+        404,
+        `Unknown method "${resolved.unknownMethod}" for service "${resolved.service.name}". Available methods: ${methods}`,
+        resolved.service.name
+      );
+    } else if (resolved && resolved.service && !resolved.command) {
+      // Service exists but no method given -- show service commands
+      const methods = Object.keys(resolved.service.commands || {});
+      console.log(`${resolved.service.name}: ${resolved.service.description}`);
+      console.log('');
+      console.log('Methods:');
+      for (const method of methods) {
+        console.log(`  dev ${resolved.service.name} ${method}`);
+      }
+      return;
+    } else {
+      const serviceName = remaining[0];
+      errors.throwError(
+        404,
+        `Unknown command "${serviceName}". Run "dev help" to see available commands.`,
+        'cli'
+      );
+    }
+    return;
+  }
+
+  // Build context and run
+  const context = buildContext(flags);
+  try {
+    await resolved.command.run(resolved.args, context);
+  } catch (err) {
+    const errors = require('./lib/errors');
+    if (errors.isDevUtilsError(err)) {
+      context.output.err(err);
+    } else {
+      errors.throwError(500, err.message || 'An unexpected error occurred', 'cli');
+    }
+  }
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/src/commands/ai/index.js

@@ -0,0 +1,16 @@
+/**
+ * AI service registration.
+ * AI coding assistant launcher and session management.
+ */
+module.exports = {
+  name: 'ai',
+  description: 'AI coding assistant launcher and session management',
+  commands: {
+    launch:   () => require('./launch'),
+    resume:   () => require('./resume'),
+    list:     () => require('./list'),
+    sessions: () => require('./sessions'),
+    show:     () => require('./show'),
+    set:      () => require('./set'),
+  }
+};

package/src/commands/ai/launch.js

@@ -0,0 +1,112 @@
+'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: 'Start an AI coding tool with configured defaults',
+  arguments: [
+    { name: 'tool', description: 'AI tool to launch (e.g., claude, gemini)', required: true }
+  ],
+  flags: [
+    { name: 'mode', type: 'string', description: 'Override the launch mode (e.g., danger, yolo, default)' },
+    { name: 'model', type: 'string', description: 'Override the model selection' },
+    { name: 'prompt', type: 'string', description: 'Pass an initial prompt to the AI tool' }
+  ]
+};
+
+/**
+ * Launches an AI coding tool with configured defaults.
+ * Reads user preferences from ai.json, builds the command with
+ * mode/model/flags, and spawns the tool with stdio inherit.
+ *
+ * @param {object} args - Parsed CLI arguments { positional, flags, extra }.
+ * @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 launch 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;
+  }
+
+  // Check that the tool is installed
+  const isInstalled = shell.commandExists(toolConfig.binary);
+  if (!isInstalled) {
+    context.output.info(`${toolConfig.displayName} is not installed.`);
+    context.output.info(`Install it and make sure "${toolConfig.binary}" is on your PATH.`);
+    return;
+  }
+
+  // Read user configuration
+  const aiConfig = readAiConfig();
+  const toolUserConfig = aiConfig[toolName] || {};
+
+  // Build the command
+  const parts = [toolConfig.binary];
+
+  // Determine mode: command-line flag overrides config, config overrides default
+  const mode = args.flags.mode || toolUserConfig.mode || 'default';
+  const modeFlags = toolConfig.modes[mode];
+  if (!modeFlags) {
+    const available = Object.keys(toolConfig.modes).join(', ');
+    context.output.info(`Unknown mode "${mode}" for ${toolConfig.displayName}. Available: ${available}`);
+    return;
+  }
+  parts.push(...modeFlags);
+
+  // Model flag
+  const model = args.flags.model || toolUserConfig.model;
+  if (model) {
+    parts.push(toolConfig.modelFlag, model);
+  }
+
+  // Prompt flag
+  if (args.flags.prompt) {
+    parts.push(toolConfig.promptFlag, JSON.stringify(args.flags.prompt));
+  }
+
+  // User's default flags from config
+  if (toolUserConfig.flags && toolUserConfig.flags.length > 0) {
+    parts.push(...toolUserConfig.flags);
+  }
+
+  // Pass through any remaining unrecognized flags from the command line
+  if (args.extra && args.extra.length > 0) {
+    parts.push(...args.extra);
+  }
+
+  const command = parts.join(' ');
+  context.output.info(`Launching ${toolConfig.displayName}...`);
+  await shell.exec(command, { stdio: 'inherit' });
+}
+
+module.exports = { meta, run };

package/src/commands/ai/list.js

@@ -0,0 +1,54 @@
+'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: 'List available AI coding tools and their install status',
+  arguments: [],
+  flags: []
+};
+
+/**
+ * Lists all known AI coding tools with their install status,
+ * current mode, and available modes.
+ *
+ * @param {object} args - Parsed CLI arguments { positional, flags }.
+ * @param {object} context - CLI context { output }.
+ */
+async function run(args, context) {
+  const aiConfig = readAiConfig();
+
+  const results = Object.entries(AI_TOOLS).map(([name, tool]) => ({
+    name: name,
+    displayName: tool.displayName,
+    binary: tool.binary,
+    installed: shell.commandExists(tool.binary),
+    configured: !!aiConfig[name],
+    mode: (aiConfig[name] && aiConfig[name].mode) || 'default',
+    availableModes: Object.keys(tool.modes)
+  }));
+
+  context.output.out(results);
+}
+
+module.exports = { meta, run };

package/src/commands/ai/resume.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const shell = require('../../lib/shell');
+const { AI_TOOLS } = require('./tools');
+
+const meta = {
+  description: 'Resume a previous AI coding session by ID',
+  arguments: [
+    { name: 'tool', description: 'AI tool to resume (e.g., claude, gemini)', required: true },
+    { name: 'session', description: 'Session ID to resume', required: true }
+  ],
+  flags: []
+};
+
+/**
+ * Resumes a previous AI coding session by session ID.
+ * Validates the tool name, checks the binary is installed,
+ * and spawns the tool with the resume flag and session ID.
+ *
+ * @param {object} args - Parsed CLI arguments { positional, flags, extra }.
+ * @param {object} context - CLI context { output, errors }.
+ */
+async function run(args, context) {
+  const toolName = args.positional[0];
+  const sessionId = args.positional[1];
+
+  if (!toolName) {
+    context.errors.throwError(400, 'Missing required argument: <tool>. Example: dev ai resume claude abc123', 'ai');
+    return;
+  }
+
+  if (!sessionId) {
+    context.errors.throwError(400, 'Missing required argument: <session>. Example: dev ai resume claude abc123', '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;
+  }
+
+  // Check that the tool is installed
+  const isInstalled = shell.commandExists(toolConfig.binary);
+  if (!isInstalled) {
+    context.output.info(`${toolConfig.displayName} is not installed.`);
+    context.output.info(`Install it and make sure "${toolConfig.binary}" is on your PATH.`);
+    return;
+  }
+
+  // Build the command
+  const parts = [
+    toolConfig.binary,
+    toolConfig.resumeFlag,
+    sessionId
+  ];
+
+  // Pass through extra flags
+  if (args.extra && args.extra.length > 0) {
+    parts.push(...args.extra);
+  }
+
+  const command = parts.join(' ');
+  context.output.info(`Resuming ${toolConfig.displayName} session ${sessionId}...`);
+  await shell.exec(command, { stdio: 'inherit' });
+}
+
+module.exports = { meta, run };

package/src/commands/ai/sessions.js

@@ -0,0 +1,121 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const shell = require('../../lib/shell');
+const { AI_TOOLS } = require('./tools');
+
+const meta = {
+  description: 'List recent sessions for an AI tool',
+  arguments: [
+    { name: 'tool', description: 'AI tool name (e.g., claude, gemini)', required: true }
+  ],
+  flags: [
+    { name: 'limit', type: 'number', description: 'Maximum number of sessions to show (default: 10)' }
+  ]
+};
+
+/**
+ * Scans a directory recursively for session files and returns metadata.
+ * Wraps all file operations in try/catch to handle unreadable files gracefully.
+ *
+ * @param {string} dirPath - The directory to scan.
+ * @param {string} toolName - The tool name (for building resume commands).
+ * @returns {Array<object>} An array of session objects sorted by last-modified date.
+ */
+function findSessions(dirPath, toolName) {
+  const sessions = [];
+
+  try {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dirPath, entry.name);
+
+      try {
+        if (entry.isDirectory()) {
+          // Recurse into subdirectories (e.g., project-specific directories)
+          const nested = findSessions(fullPath, toolName);
+          sessions.push(...nested);
+        } else if (entry.isFile()) {
+          // Extract session ID from filename (strip extension)
+          const sessionId = path.basename(entry.name, path.extname(entry.name));
+          const stats = fs.statSync(fullPath);
+
+          sessions.push({
+            id: sessionId,
+            tool: toolName,
+            path: fullPath,
+            lastActive: stats.mtime.toISOString(),
+            resumeCommand: `dev ai resume ${toolName} ${sessionId}`
+          });
+        }
+      } catch (err) {
+        // Skip unreadable entries
+      }
+    }
+  } catch (err) {
+    // Directory not readable, return empty
+  }
+
+  return sessions;
+}
+
+/**
+ * Lists recent sessions for a specified AI tool by reading
+ * the tool's session storage directory.
+ *
+ * @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 sessions 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;
+  }
+
+  // Find a session directory that exists
+  let sessionDir = null;
+  for (const candidate of toolConfig.sessionPaths) {
+    if (fs.existsSync(candidate)) {
+      sessionDir = candidate;
+      break;
+    }
+  }
+
+  if (!sessionDir) {
+    context.output.info(
+      `No session data found for ${toolConfig.displayName}. Sessions may be stored in a location DevUtils doesn't know about yet.`
+    );
+    return;
+  }
+
+  // Scan for sessions
+  const sessions = findSessions(sessionDir, toolName);
+
+  if (sessions.length === 0) {
+    context.output.info(`No sessions found for ${toolConfig.displayName}.`);
+    return;
+  }
+
+  // Sort by last-modified date, most recent first
+  sessions.sort((a, b) => new Date(b.lastActive) - new Date(a.lastActive));
+
+  // Apply the limit
+  const limit = args.flags.limit || 10;
+  const limited = sessions.slice(0, limit);
+
+  context.output.out(limited);
+}
+
+module.exports = { meta, run };