codemodctl

A CLI tool for workflow engine operations, providing handy commands to interact with codemod APIs and process workflow data.

Installation

pnpm install @acme/codemodctl

Usage

codemodctl <command> [options]

Commands

`pr create`

Create a pull request using the codemod API.

codemodctl pr create --title "feat: implement new feature" [options]

Options

--title <title> (required): The title of the pull request
--body <body> (optional): The body/description of the pull request
--head <branch> (optional): The head branch for the pull request
--base <branch> (optional): The base branch to merge into (defaults to 'main')

Examples

# Create a simple PR with just a title
codemodctl pr create --title "feat: implement new feature"

# Create a PR with title and body
codemodctl pr create --title "feat: implement new feature" --body "This PR implements a new feature that improves performance"

# Create a PR with custom branches
codemodctl pr create --title "feat: implement new feature" --head "feature-branch" --base "develop"

# Create a comprehensive PR
codemodctl pr create \
  --title "feat: implement new feature" \
  --body "This PR implements a new feature that improves performance by 50%" \
  --head "feature-branch" \
  --base "main"

`shard codeowner`

Analyze a GitHub CODEOWNERS file and generate sharding output for teams based on file ownership.

codemodctl shard codeowner --shard-size <size> --state-prop <property-name> [--codeowners <path>]

Options

--shard-size <size> (required): Number of files per shard
--state-prop <property> (required): Property name to use in the state output
--codeowners <path> (optional): Path to CODEOWNERS file. If not provided, searches in current directory, .github/, or docs/

Examples

# Create shards with 10 files per shard (auto-discover CODEOWNERS file)
codemodctl shard codeowner --shard-size 10 --state-prop teamShards

# Create shards with custom CODEOWNERS path
codemodctl shard codeowner --shard-size 25 --state-prop migrationShards --codeowners ./custom/CODEOWNERS

# Create shards for a specific team distribution
codemodctl shard codeowner --shard-size 50 --state-prop deploymentShards

How it works

CODEOWNERS Discovery: Automatically finds CODEOWNERS file in common locations (root, .github/, docs/) or uses provided path
File Analysis: Uses the codeowners npm package to parse the GitHub CODEOWNERS file and determine file ownership
File Counting: Scans the repository and counts files owned by each team/user (excluding common ignore patterns)
Shard Calculation: Divides the total files by the shard size to determine number of shards needed per team
Output Generation: Creates a JSON array with team and shard information
State Output: Writes the result to the file specified by $STATE_OUTPUTS environment variable

CODEOWNERS File Format

The tool works with standard GitHub CODEOWNERS syntax:

# Global owners
* @global-team

# Frontend files  
src/components/ @frontend-team
*.tsx @frontend-team @design-team

# Backend files
src/api/ @backend-team
*.sql @database-team @backend-team

# DevOps files
.github/ @devops-team
Dockerfile @devops-team

Example Output

For teams with the following file ownership:

frontend-team: 100 files
backend-team: 75 files
devops-team: 25 files

With --shard-size 25:

[
  {"team": "frontend-team", "shard": "1/4"},
  {"team": "frontend-team", "shard": "2/4"}, 
  {"team": "frontend-team", "shard": "3/4"},
  {"team": "frontend-team", "shard": "4/4"},
  {"team": "backend-team", "shard": "1/3"},
  {"team": "backend-team", "shard": "2/3"},
  {"team": "backend-team", "shard": "3/3"},
  {"team": "devops-team", "shard": "1/1"}
]

The tool will write to the state output file:

teamShards=[{"team": "frontend-team", "shard": "1/4"}, {"team": "frontend-team", "shard": "2/4"}, ...]

Environment Variables

For PR Creation

BUTTERFLOW_API_ENDPOINT: The API endpoint for codemod services
BUTTERFLOW_API_AUTH_TOKEN: Authentication token for API requests
CODEMOD_TASK_ID: Current task ID for the workflow

For State Output

STATE_OUTPUTS: Path to the file where state outputs should be written

Integration with Workflow Engine

codemodctl is designed to work seamlessly with the workflow engine:

PR Creation: Automatically uses workflow context (task ID, project name) when available
State Management: Writes outputs to the workflow state file for use in subsequent steps
Error Handling: Provides clear error messages and appropriate exit codes for workflow integration

Development

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run tests
pnpm test

# Run in development mode
pnpm dev

License

MIT