@fredlackey/devutils 0.0.18 → 0.1.0

package/src/api/loader.js

@@ -0,0 +1,229 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const DEVUTILS_DIR = path.join(os.homedir(), '.devutils');
+const PLUGINS_FILE = path.join(DEVUTILS_DIR, 'plugins.json');
+const PLUGINS_DIR = path.join(DEVUTILS_DIR, 'plugins');
+
+/**
+ * Reads and parses ~/.devutils/plugins.json.
+ * Returns an empty object if the file does not exist or is unreadable.
+ * Logs a warning to stderr if the file exists but contains invalid JSON.
+ *
+ * @returns {object} A map of plugin names to their entries, or {}.
+ */
+function readPluginsJson() {
+  try {
+    const raw = fs.readFileSync(PLUGINS_FILE, 'utf8');
+    return JSON.parse(raw);
+  } catch (err) {
+    // If the file exists but JSON is invalid, warn the user
+    if (err instanceof SyntaxError && fs.existsSync(PLUGINS_FILE)) {
+      process.stderr.write(`Warning: ${PLUGINS_FILE} contains invalid JSON. Treating as empty.\n`);
+    }
+    return {};
+  }
+}
+
+/**
+ * Validates that a plugin module exports the required contract fields.
+ * Returns null if valid, or a structured error object if something is missing.
+ *
+ * @param {object} pluginModule - The required plugin module.
+ * @param {string} pluginName - The plugin name (for error messages).
+ * @returns {object|null} Null if valid, or { error, code, message } if invalid.
+ */
+function validateContract(pluginModule, pluginName) {
+  const required = ['name', 'description', 'version', 'auth', 'resources'];
+  const missing = required.filter(field => !pluginModule[field]);
+
+  if (missing.length > 0) {
+    return {
+      error: true,
+      code: 'INVALID_CONTRACT',
+      message: `Plugin "${pluginName}" is missing required fields: ${missing.join(', ')}.\nThe plugin may be outdated or incorrectly built.`
+    };
+  }
+
+  if (typeof pluginModule.resources !== 'object') {
+    return {
+      error: true,
+      code: 'INVALID_CONTRACT',
+      message: `Plugin "${pluginName}" has an invalid resources export. Expected an object.`
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Loads a plugin by name from the installed plugins directory.
+ * Reads plugins.json, requires the package, and validates the contract.
+ *
+ * @param {string} pluginName - The short plugin name (e.g., 'gmail').
+ * @returns {object} { error: false, plugin } on success, or { error: true, code, message } on failure.
+ */
+function loadPlugin(pluginName) {
+  const plugins = readPluginsJson();
+  const entry = plugins[pluginName];
+
+  if (!entry) {
+    return {
+      error: true,
+      code: 'NOT_INSTALLED',
+      message: `API plugin "${pluginName}" is not installed.\nRun "dev api enable ${pluginName}" to install it.`
+    };
+  }
+
+  const packagePath = path.join(PLUGINS_DIR, 'node_modules', entry.package);
+
+  let pluginModule;
+  try {
+    pluginModule = require(packagePath);
+  } catch (err) {
+    return {
+      error: true,
+      code: 'LOAD_FAILED',
+      message: `Failed to load plugin "${pluginName}" from ${packagePath}.\nThe package may be corrupted. Try "dev api disable ${pluginName}" then "dev api enable ${pluginName}".`
+    };
+  }
+
+  // Validate the plugin contract
+  const validation = validateContract(pluginModule, pluginName);
+  if (validation) {
+    return validation;
+  }
+
+  return { error: false, plugin: pluginModule };
+}
+
+/**
+ * Resolves a specific command from a plugin's resource tree.
+ * Given a plugin name, resource name, and command name, loads the plugin
+ * and walks the resource/command tree to find the command module.
+ *
+ * @param {string} pluginName - The plugin name (e.g., 'gmail').
+ * @param {string} resourceName - The resource name (e.g., 'messages').
+ * @param {string} commandName - The command name (e.g., 'list').
+ * @returns {object} { error: false, command, plugin } on success, or { error: true, code, message } on failure.
+ */
+function resolveCommand(pluginName, resourceName, commandName) {
+  const result = loadPlugin(pluginName);
+  if (result.error) return result;
+
+  const plugin = result.plugin;
+  const resource = plugin.resources[resourceName];
+
+  if (!resource) {
+    const available = Object.keys(plugin.resources).join(', ');
+    return {
+      error: true,
+      code: 'UNKNOWN_RESOURCE',
+      message: `Plugin "${pluginName}" has no resource "${resourceName}".\nAvailable resources: ${available}`
+    };
+  }
+
+  const commandLoader = resource.commands[commandName];
+  if (!commandLoader) {
+    const available = Object.keys(resource.commands).join(', ');
+    return {
+      error: true,
+      code: 'UNKNOWN_COMMAND',
+      message: `Resource "${resourceName}" in plugin "${pluginName}" has no command "${commandName}".\nAvailable commands: ${available}`
+    };
+  }
+
+  let commandModule;
+  try {
+    commandModule = typeof commandLoader === 'function' ? commandLoader() : commandLoader;
+  } catch (err) {
+    return {
+      error: true,
+      code: 'COMMAND_LOAD_FAILED',
+      message: `Failed to load command "${commandName}" from plugin "${pluginName}": ${err.message}`
+    };
+  }
+
+  return {
+    error: false,
+    command: commandModule,
+    plugin: plugin
+  };
+}
+
+/**
+ * Builds the context object that plugin commands receive.
+ * Reads the auth credential for the plugin's declared auth service
+ * and unwraps the credential envelope so plugins get flat access.
+ *
+ * @param {object} plugin - The plugin's contract object (must have an auth field).
+ * @param {object} coreContext - The core CLI context (output, errors, config, shell, platform).
+ * @returns {object} The enriched plugin context with auth, output, errors, config, shell, platform.
+ */
+function buildPluginContext(plugin, coreContext) {
+  const authService = plugin.auth;
+
+  // Read the auth credential for this plugin's declared service
+  const authFilePath = path.join(DEVUTILS_DIR, 'auth', `${authService}.json`);
+  let authCredential = null;
+  try {
+    const raw = fs.readFileSync(authFilePath, 'utf8');
+    const credentialFile = JSON.parse(raw);
+
+    // Unwrap the credential envelope. The auth system stores files as:
+    //   { service, type, credentials: { ... } }
+    // Plugins expect flat access (e.g., context.auth.accessKeyId), so we
+    // pass credentialFile.credentials directly instead of the full envelope.
+    authCredential = credentialFile.credentials || credentialFile;
+  } catch (err) {
+    // Auth not available - plugin commands will get null
+  }
+
+  return {
+    auth: authCredential,
+    output: coreContext.output,
+    errors: coreContext.errors,
+    config: coreContext.config,
+    shell: coreContext.shell,
+    platform: coreContext.platform
+  };
+}
+
+/**
+ * Returns all installed plugins from plugins.json.
+ * Returns an empty object if no plugins are installed.
+ *
+ * @returns {object} A map of plugin names to their entries.
+ */
+function getInstalledPlugins() {
+  return readPluginsJson();
+}
+
+/**
+ * Returns the list of available plugins from the bundled registry.
+ * Returns an empty array if the registry file is missing or unreadable.
+ *
+ * @returns {Array<object>} An array of registry plugin entries.
+ */
+function getRegistryPlugins() {
+  try {
+    return require('./registry.json');
+  } catch (err) {
+    return [];
+  }
+}
+
+module.exports = {
+  resolveCommand,
+  loadPlugin,
+  buildPluginContext,
+  validateContract,
+  getInstalledPlugins,
+  getRegistryPlugins,
+  readPluginsJson,
+  PLUGINS_FILE,
+  PLUGINS_DIR
+};

package/src/api/registry.json

@@ -0,0 +1,62 @@
+[
+  {
+    "name": "gmail",
+    "package": "@fredlackey/devutils-api-gmail",
+    "description": "Google Gmail (messages, labels, drafts, threads)",
+    "auth": "google"
+  },
+  {
+    "name": "drive",
+    "package": "@fredlackey/devutils-api-drive",
+    "description": "Google Drive (files, folders, permissions)",
+    "auth": "google"
+  },
+  {
+    "name": "sheets",
+    "package": "@fredlackey/devutils-api-sheets",
+    "description": "Google Sheets (spreadsheets, values, sheets)",
+    "auth": "google"
+  },
+  {
+    "name": "docs",
+    "package": "@fredlackey/devutils-api-docs",
+    "description": "Google Docs (documents)",
+    "auth": "google"
+  },
+  {
+    "name": "aws",
+    "package": "@fredlackey/devutils-api-aws",
+    "description": "Amazon Web Services (compute, storage, functions, groups)",
+    "auth": "aws"
+  },
+  {
+    "name": "cloudflare",
+    "package": "@fredlackey/devutils-api-cloudflare",
+    "description": "Cloudflare (zones, DNS records, API tokens)",
+    "auth": "cloudflare"
+  },
+  {
+    "name": "dokploy",
+    "package": "@fredlackey/devutils-api-dokploy",
+    "description": "Dokploy (applications, projects, domains, servers)",
+    "auth": "dokploy"
+  },
+  {
+    "name": "namecheap",
+    "package": "@fredlackey/devutils-api-namecheap",
+    "description": "Namecheap (domains, DNS, SSL certificates)",
+    "auth": "namecheap"
+  },
+  {
+    "name": "flowroute",
+    "package": "@fredlackey/devutils-api-flowroute",
+    "description": "Flowroute (SMS, MMS, phone numbers)",
+    "auth": "flowroute"
+  },
+  {
+    "name": "mailu",
+    "package": "@fredlackey/devutils-api-mailu",
+    "description": "Mailu (email users, aliases, domains)",
+    "auth": "mailu"
+  }
+]

package/src/cli.js

@@ -1,72 +1,305 @@
 #!/usr/bin/env node
+'use strict';
 
 /**
- * @fileoverview CLI setup using Commander.js
- * Registers all commands and handles program execution.
+ * 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 { program } = require('commander');
-const pkg = require('../package.json');
+const TOP_LEVEL_COMMANDS = ['status', 'update', 'version', 'schema', 'help'];
 
-const configureCommand = require('./commands/configure');
-const statusCommand = require('./commands/status');
-const identityCommand = require('./commands/identity');
-const ignoreCommand = require('./commands/ignore');
-const installCommand = require('./commands/install');
-const versionCommand = require('./commands/version');
-const updateCommand = require('./commands/update');
-const { installCompletion, uninstallCompletion } = require('./completion');
+/**
+ * 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 };
+}
 
 /**
- * Run the CLI program
+ * Displays the CLI help message listing all services, commands, and global flags.
  */
-function run() {
-  program
-    .name('dev')
-    .description('CLI toolkit for bootstrapping development environments')
-    .version(pkg.version, '-v, --version', 'Display version number');
-
-  // Global options
-  program
-    .option('--verbose', 'Enable verbose output')
-    .option('-q, --quiet', 'Suppress non-essential output')
-    .option('--no-color', 'Disable colored output');
-
-  // Add commands
-  program.addCommand(configureCommand);
-  program.addCommand(statusCommand);
-  program.addCommand(identityCommand);
-  program.addCommand(ignoreCommand);
-  program.addCommand(installCommand);
-  program.addCommand(versionCommand);
-  program.addCommand(updateCommand);
-
-  // Setup command - install essential tools
-  const setupCommand = require('./commands/setup');
-  program.addCommand(setupCommand);
-
-  // Completion management
-  const completion = program
-    .command('completion')
-    .description('Manage shell tab completion');
-
-  completion
-    .command('install')
-    .description('Install tab completion for your shell')
-    .action(installCompletion);
-
-  completion
-    .command('uninstall')
-    .description('Remove tab completion')
-    .action(uninstallCompletion);
-
-  // Parse and execute
-  program.parse(process.argv);
-
-  // If no command specified, show help
-  if (process.argv.length === 2) {
-    program.help();
+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');
+    }
   }
 }
 
-module.exports = { run };
+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'),
+  }
+};