@fredlackey/devutils 0.0.18 → 0.1.0

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

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