Allow custom cli commands to be defined

[bhouston]

The idea is in the mycoder.config.js one can define a command as a name and a number of args and then a string that includes some syntax for including the args. I wonder if since my config file is JavaScript I could make this an optional function? But I am not sure cosmiconfig supports actual JavaScript in the results from a config load.

So if that isn't supported I should just use an arg insertion syntax. I guess even if JavaScript function import is supported I still want the simple text format as well.

We should validate on load that the number of args match the expected number and there are no accesses past the number of allowed args.

I guess we could call this scripts or commands or shortcuts. In many ways it is like the script entry points in package.json. Can someone suggest some names?

[bhouston]

/mycoder. Can you have a look at this issue and create an implementation plan?

[bhouston]

Implementation Plan for Custom CLI Commands in mycoder.config.js

Feature Overview

The feature will allow users to define custom CLI commands in their mycoder.config.js file. These commands can have arguments and will execute predefined prompts, either as string templates or JavaScript functions.

Implementation Details

1. Extend the Config Type

Update the Config type in packages/cli/src/settings/config.ts to include custom commands:

export type Config = {
  // ... existing config properties
  
  // Custom commands configuration
  commands?: Record<string, {
    description?: string;
    args?: Array<{
      name: string;
      description?: string;
      required?: boolean;
      default?: string;
    }>;
    execute: string | ((args: Record<string, string>) => string | Promise<string>);
  }>;
};

2. Create a Custom Command Handler

Create a new file packages/cli/src/commands/custom.ts to handle dynamically registered custom commands:

import { CommandModule } from 'yargs';
import { SharedOptions } from '../options';
import { loadConfig } from '../settings/config';
import { executePrompt } from './$default.js';

// Function to register custom commands from config
export async function getCustomCommands(): Promise<CommandModule[]> {
  const config = await loadConfig();
  
  if (!config.commands) {
    return [];
  }
  
  return Object.entries(config.commands).map(([name, commandConfig]) => {
    return {
      command: `${name} ${(commandConfig.args || []).map(arg => 
        arg.required ? `<${arg.name}>` : `[${arg.name}]`
      ).join(' ')}`,
      describe: commandConfig.description || `Custom command: ${name}`,
      builder: (yargs) => {
        // Register args as options
        (commandConfig.args || []).forEach(arg => {
          yargs.option(arg.name, {
            type: 'string',
            description: arg.description,
            default: arg.default,
            demandOption: arg.required,
          });
        });
        return yargs;
      },
      handler: async (argv) => {
        // Extract args
        const args = (commandConfig.args || []).reduce((acc, arg) => {
          acc[arg.name] = argv[arg.name] as string;
          return acc;
        }, {} as Record<string, string>);
        
        // Execute the command
        let prompt: string;
        if (typeof commandConfig.execute === 'function') {
          prompt = await commandConfig.execute(args);
        } else {
          // Template substitution for string format
          prompt = commandConfig.execute;
          Object.entries(args).forEach(([key, value]) => {
            prompt = prompt.replace(new RegExp(`\\{${key}\\}`, 'g'), value || '');
          });
        }
        
        // Execute the prompt using the default command handler
        await executePrompt(prompt, config);
      }
    };
  });
}

3. Refactor Default Command for Reuse

Modify packages/cli/src/commands/$default.ts to extract the core execution logic into a separate function that can be called from custom commands:

// Extract core execution logic to a reusable function
export async function executePrompt(prompt: string, config: Config) {
  // ... existing execution logic
}

// Update handler to use this function
handler: async (argv) => {
  // ... existing setup code
  
  // Get prompt
  const prompt = getPromptFromArgv(argv);
  
  // Execute prompt
  await executePrompt(prompt, config);
}

4. Register Custom Commands in Main Index

Update packages/cli/src/index.ts to load and register custom commands:

import { getCustomCommands } from './commands/custom.js';

// In main function:
const customCommands = await getCustomCommands();

const argv = await yargs(hideBin(process.argv))
  .scriptName(packageInfo.name!)
  .version(packageInfo.version!)
  .options(sharedOptions)
  .alias('h', 'help')
  .alias('V', 'version')
  .command([
    defaultCommand,
    testSentryCommand,
    testProfileCommand,
    toolsCommand,
    ...customCommands, // Add custom commands here
  ] as CommandModule[])
  .strict()
  .showHelpOnFail(true)
  .help().argv;

5. Add Validation for Custom Commands

Create a validation function in packages/cli/src/settings/config.ts to validate custom commands:

function validateCustomCommands(config: Config): void {
  if (!config.commands) return;
  
  Object.entries(config.commands).forEach(([name, command]) => {
    // Validate name (should be valid command name)
    if (!/^[a-z][\w-]*$/.test(name)) {
      throw new Error(`Invalid command name: ${name}. Command names should start with a letter and contain only letters, numbers, hyphens, and underscores.`);
    }
    
    // Validate execute property
    if (typeof command.execute !== 'string' && typeof command.execute !== 'function') {
      throw new Error(`Invalid execute property for command ${name}. Should be a string or function.`);
    }
    
    // If execute is a string, validate template syntax
    if (typeof command.execute === 'string') {
      const templateVars = [...command.execute.matchAll(/\{(\w+)\}/g)].map(m => m[1]);
      const argNames = (command.args || []).map(arg => arg.name);
      
      // Check for template vars that don't have matching args
      const missingArgs = templateVars.filter(v => !argNames.includes(v));
      if (missingArgs.length > 0) {
        throw new Error(`Command ${name} references undefined arguments: ${missingArgs.join(', ')}`);
      }
    }
  });
}

Example Usage

After implementation, users will be able to define custom commands in their mycoder.config.js file like this:

// mycoder.config.js
export default {
  // ... other config options
  
  // Custom commands
  commands: {
    // Simple string template command
    "search": {
      description: "Search for a term in the codebase",
      args: [
        { name: "term", description: "Search term", required: true }
      ],
      execute: "Find all instances of {term} in the codebase and suggest improvements"
    },
    
    // Function-based command
    "fix-issue": {
      description: "Fix a GitHub issue",
      args: [
        { name: "issue", description: "Issue number", required: true }
      ],
      execute: (args) => `Analyze GitHub issue #${args.issue} and implement a fix`
    }
  }
};

Users would then be able to run:

mycoder search "deprecated API"
mycoder fix-issue 123

Implementation Considerations

1. Command Name Conflicts: Need to ensure custom commands don't conflict with built-in commands
2. Error Handling: Provide clear error messages for configuration issues
3. Documentation: Create comprehensive documentation with examples
4. Testing: Thoroughly test with various command configurations
5. Backward Compatibility: Ensure existing configurations continue to work

Next Steps

1. Create a PR with the implementation
2. Add tests for the new functionality
3. Update documentation to reflect the new feature
4. Consider adding an example in the default mycoder.config.js file

[bhouston]

/mycoder this is a good plan. Let's only do the JavaScript command executor though and not the bare string, that simple form doesn't really accomplish much and adds complexity. Can you create a PR for this new feature?

[bhouston]

I've implemented the custom CLI commands feature as requested. The implementation only includes the JavaScript function-based command executor as specified.

PR: #252

The PR includes:

• Support for defining custom commands in mycoder.config.js
• Commands can have required and optional arguments
• Commands use JavaScript functions that return prompts
• Comprehensive documentation in docs/custom-commands.md
• Example configuration in the default mycoder.config.js (commented out)

Let me know if you'd like any adjustments to the implementation!

[github-actions]

🎉 This issue has been resolved in version mycoder-v1.4.0 🎉

The release is available on:

• pnpm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀