codemod 1.1.0-alpha.1 → 1.1.1

package/README.md

@@ -1,946 +1,264 @@
+<p align="center">
+  <a href="https://codemod.com">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/codemod/codemod/main/apps/docs/images/intro/codemod-docs-hero-dark.jpg">
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/codemod/codemod/main/apps/docs/images/intro/codemod-docs-hero-light.jpg">
+      <img alt="Codemod CLI" src="https://raw.githubusercontent.com/codemod/codemod/main/apps/docs/images/intro/codemod-docs-hero-light.jpg">
+    </picture>
+  </a>
+
+  <p align="center">
+    <br />
+    <a href="https://go.codemod.com/app">Platform</a>
+    ·
+    <a href="https://go.codemod.com/community">Community</a>
+    ·
+    <a href="https://docs.codemod.com">Docs</a>
+  </p>
+</p>
+
 # Codemod CLI
 
-The Codemod CLI is a command-line interface for running and managing Butterflow workflows - a lightweight, self-hostable workflow engine designed for running large-scale code transformation jobs.
+[![Community](https://img.shields.io/badge/slack-join-e9a820)](https://go.codemod.com/community)
+[![License](https://img.shields.io/github/license/codemod/codemod)](https://github.com/codemod/codemod/blob/main/LICENSE)
+[![npm version](https://img.shields.io/npm/v/codemod.svg)](https://www.npmjs.com/package/codemod)
 
-> **NOTE**: This CLI is currently in alpha and may change over time. So be careful when using it in production environments.
-> For more information read the [blog post announcing the CLI](https://codemod.com/blog/new-codemod-cli).
-> And any feedback is welcome!
+**Codemod CLI** is an open-source command-line tool for building, testing, and running **codemod packages**—automated code transformations that help teams modernize codebases, upgrade frameworks, and refactor at scale.
 
-## Installation
+Whether you're an individual developer tackling tech debt, an OSS maintainer shipping upgrade paths, or a platform team coordinating migrations across hundreds of services, Codemod CLI gives you the tools to automate repetitive code changes reliably.
 
-### Building from Source
+## Installation
 
 ```bash
-# Clone the repository
-git clone https://github.com/codemod-com/codemod.git
-cd codemod
-
-# Build the project
-cargo build --release
-
-# The executable will be available at target/release/codemod
+npm install -g codemod@latest
 ```
 
-### From npm registry
+Or use via `npx` without installation:
 
 ```bash
-npm install -g codemod
+npx codemod@latest <command>
 ```
 
 ## Quick Start
 
-1. Create a workflow file `workflow.yaml`:
-
-```yaml
-version: "1"
-nodes:
-  - id: hello-world
-    name: Hello World
-    type: automatic
-    runtime:
-      type: direct
-    steps:
-      - id: hello
-        name: Say Hello
-        run: echo "Hello, World!"
-```
-
-2. Run the workflow:
-
-```bash
-codemod run -w workflow.yaml
-```
-
-## Commands
-
-### `codemod init`
-
-Initialize a new Butterflow workflow project with interactive setup:
-
-```bash
-# Initialize a new project in current directory
-codemod init
-
-# Initialize a new project in a specific directory
-codemod init my-project/
-
-# Initialize with a specific name
-codemod init --name my-workflow
-```
-
-**Options:**
-- `--name <NAME>`: Set the project name (defaults to directory name)
-- `--force`: Overwrite existing files if they exist
-- Positional argument: Target directory path (defaults to current directory)
-
-**Interactive Setup:**
-
-The init command will prompt you with several questions to customize your project:
-
-1. **Project Type Selection:**
-   ```
-   ? What type of workflow would you like to create?
-   ❯ AST-grep with JavaScript/TypeScript rules
-     AST-grep with YAML rules  
-     Blank workflow (custom commands)
-   ```
-
-2. **Language Selection** (if AST-grep is chosen):
-   ```
-   ? Which language would you like to target?
-   ❯ JavaScript/TypeScript
-     Python
-     Rust
-     Go
-     Java
-     C/C++
-     Other
-   ```
-
-3. **Project Configuration:**
-   ```
-   ? Project name: my-codemod
-   ? Description: Converts legacy API calls to new format
-   ? Author: Your Name <your.email@example.com>
-   ```
-
-**Generated Project Structure:**
-
-Depending on your selections, the init command creates different project templates:
-
-#### AST-grep JavaScript Project
-```
-my-codemod/
-├── workflow.yaml           # Main workflow definition
-├── package.json           # Node.js dependencies
-├── rules/
-│   └── example-rule.js    # JavaScript AST transformation rules
-├── scripts/
-│   └── apply-codemod.js   # Script to apply transformations
-├── tests/
-│   ├── input/             # Test input files
-│   └── expected/          # Expected output files
-└── README.md              # Project documentation
-```
-
-#### AST-grep YAML Project
-```
-my-codemod/
-├── workflow.yaml          # Main workflow definition
-├── rules/
-│   └── example-rule.yml   # YAML AST pattern rules
-├── scripts/
-│   └── apply-rules.sh     # Shell script to apply rules
-├── tests/
-│   ├── input/             # Test input files
-│   └── expected/          # Expected output files
-└── README.md              # Project documentation
-```
-
-#### Blank Workflow Project
-```
-my-workflow/
-├── workflow.yaml          # Basic workflow template
-├── scripts/
-│   └── example.sh         # Example script
-└── README.md              # Project documentation
-```
-
-**Example Usage:**
-
-```bash
-# Create a new AST-grep JavaScript project
-$ codemod init my-js-codemod
-? What type of workflow would you like to create? AST-grep with JavaScript/TypeScript rules
-? Which language would you like to target? JavaScript/TypeScript
-? Project name: my-js-codemod
-? Description: Migrate from React class components to hooks
-? Author: John Doe <john@example.com>
-
-✓ Created workflow.yaml
-✓ Created package.json with @ast-grep/cli dependency
-✓ Created rules/migrate-to-hooks.js
-✓ Created scripts/apply-codemod.js
-✓ Created test structure
-✓ Created README.md
-
-Next steps:
-  cd my-js-codemod
-  npm install
-  codemod validate -w workflow.yaml
-  codemod run -w workflow.yaml
-```
-
-### `codemod run`
-
-Execute a workflow from various sources:
-
-```bash
-# Run from a specific workflow file
-codemod run -w workflow.yaml
-codemod run -w path/to/workflow.yaml
-
-# Run from a workflow bundle directory (containing workflow.yaml)
-codemod run ./my-workflow-bundle/
-
-# Run from a registry (Conceptual)
-# codemod run my-registry/react-19-codemods:latest 
-```
-
-**Options:**
-- `-w, --workflow <FILE>`: Path to the workflow definition file
-- Positional argument: Path to workflow file or bundle directory
-
-### `codemod resume`
-
-Resume a paused workflow or trigger manual tasks:
-
-```bash
-# Resume a workflow run by ID
-codemod resume -i <workflow-run-id>
-
-# Trigger a specific task by UUID
-codemod resume -i <workflow-run-id> -t <task-uuid>
-
-# Trigger all tasks currently awaiting manual triggers
-codemod resume -i <workflow-run-id> --trigger-all
-```
-
-**Options:**
-- `-i, --id <UUID>`: Workflow run ID to resume
-- `-t, --task <UUID>`: Specific task UUID to trigger
-- `--trigger-all`: Trigger all tasks in `AwaitingTrigger` state
-
-### `codemod validate`
-
-Validate a workflow definition without executing it:
-
-```bash
-# Validate a workflow file
-codemod validate -w workflow.yaml
-codemod validate -w path/to/workflow.yaml
-
-# Validate a workflow bundle
-codemod validate ./my-workflow-bundle/
-```
-
-**Validation Checks:**
-- Schema validation
-- Node ID uniqueness
-- Step ID uniqueness within nodes  
-- Template ID uniqueness
-- Dependency validation
-- Cyclic dependency detection
-- Template reference validation
-- Matrix strategy validation
-- State schema validation
-- Variable reference syntax validation
-
-**Example Output:**
-
-Valid workflow:
-```bash
-$ codemod validate -w valid-workflow.yaml
-✓ Workflow definition is valid
-Schema validation: Passed
-Node dependencies: Valid (3 nodes, 2 dependency relationships)
-Template references: Valid (2 templates, 3 references)
-Matrix strategies: Valid (1 matrix node)
-State schema: Valid (2 schema definitions)
-```
-
-Invalid workflow:
-```bash
-$ codemod validate -w invalid-workflow.yaml
-✗ Workflow definition is invalid
-Error at nodes[2].strategy: Matrix strategy requires 'values' or 'from_state' property
-Error at nodes[1].depends_on[0]: Referenced node 'non-existent-node' does not exist
-Error: Cyclic dependency detected: node-a → node-b → node-a
-```
-
-### `codemod login`
-
-Authenticate with a Butterflow registry to publish and manage codemods:
-
 ```bash
-# Login to the default registry
-codemod login
-
-# Login to a specific registry
-codemod login --registry https://registry.example.com
-
-# Login with a token (for CI/CD)
-codemod login --token <your-token>
+# 1. Create a codemod package
+npx codemod init my-codemod
+cd my-codemod
 
-# Login with username/password
-codemod login --username <username>
-```
+# You can create codemod packages with the help of AI using Codemod MCP or Studio
 
-**Options:**
-- `--registry <URL>`: Registry URL (defaults to official Butterflow registry)
-- `--token <TOKEN>`: Authentication token (for non-interactive login)
-- `--username <USERNAME>`: Username for interactive login
-- `--scope <SCOPE>`: Organization or user scope for publishing
+# 2. Run it locally
+npx codemod workflow run -w ./example-codemod -t /abs/path/to/repo
 
-**Interactive Login:**
+# 3. Publish to registry
+npx codemod login
+npx codemod publish
 
-```bash
-$ codemod login
-? Registry URL: https://app.butterflow.com(default)
-? Username: john.doe
-? Password: ********
-? Organization (optional): my-org
-✓ Successfully logged in as john.doe
-✓ Default publish scope set to @my-org
+# 4. Run from registry
+npx codemod @your-org/example-codemod
 ```
 
-**Token-based Login (for CI/CD):**
+## What are Codemod Packages?
 
-```bash
-# Set authentication token
-export BUTTERFLOW_TOKEN="your-registry-token"
-codemod login --token $BUTTERFLOW_TOKEN
-```
+**Codemod packages** are portable, reusable code transformation units that can range from simple find-and-replace operations to complex, multi-step migration workflows. Each package includes:
 
-### `codemod publish`
+- **Transformation logic** – Written in JavaScript/TypeScript (jssg), YAML ast-grep rules, or shell scripts
+- **Workflow definition** – Orchestrates steps, handles dependencies, and manages execution
+- **Package manifest** – Defines metadata, target languages, and publishing configuration
 
-Publish a codemod to a registry for sharing and reuse:
+Packages are **fully portable**: run them locally during development, in CI/CD pipelines, or share them via the [Codemod Registry](https://go.codemod.com/registry) for your team or the community.
 
-```bash
-# Publish current directory as a codemod
-codemod publish
+## Why Codemod CLI?
 
-# Publish a specific codemod directory
-codemod publish ./my-codemod/
+- **🎯 Built for Automation** – Scaffold, test, and publish codemod packages from your terminal
+- **📦 Registry Integration** – Share codemods via the [Codemod Registry](https://go.codemod.com/registry) or run community packages instantly
+- **⚡ Powerful Engines** – Leverage ast-grep (YAML + jssg) for fast, accurate AST-based transformations
+- **🤖 AI-Powered Creation** – Use [Codemod MCP](https://go.codemod.com/mcp-docs) in your IDE or [Codemod Studio](https://go.codemod.com/studio-docs) to build codemods with AI assistance
+- **🧪 Built-in Testing** – Validate codemods with snapshot testing before running on production code
+- **🔧 Flexible Runtime** – Run directly on your machine or in Docker/Podman containers
 
-# Publish with specific version
-codemod publish --version 1.2.3
+## Core Concepts
 
-# Publish to specific registry
-codemod publish --registry https://registry.example.com
+### Codemod Packages
 
-# Dry run (validate without publishing)
-codemod publish --dry-run
-```
+A **codemod package** is a directory containing:
 
-**Options:**
-- `--version <VERSION>`: Explicit version (overrides manifest version)
-- `--registry <URL>`: Target registry URL
-- `--tag <TAG>`: Tag for the release (e.g., `beta`, `latest`)
-- `--access <LEVEL>`: Access level (`public` or `private`)
-- `--dry-run`: Validate and pack without uploading
-- `--force`: Override existing version (use with caution)
+- `codemod.yaml` – Package metadata (name, version, description, target languages)
+- `workflow.yaml` – Workflow steps and orchestration logic
+- `scripts/` – JavaScript/TypeScript codemods (jssg)
+- `rules/` – YAML ast-grep rule files
 
-**Publishing Flow:**
+Packages can be as simple as a single transformation or as complex as multi-step migration workflows combining JavaScript codemods, YAML rules, shell scripts, and AI-assisted steps.
 
-```bash
-$ codemod publish
-✓ Validating codemod.yaml manifest
-✓ Validating workflow.yaml
-✓ Running tests (if present)
-✓ Building codemod bundle
-✓ Uploading to registry @my-org/react-hooks-migration@1.0.0
-✓ Published successfully!
-
-Install with: codemod run @my-org/react-hooks-migration@1.0.0
-```
-
-## Codemod Manifest Standard
-
-Published codemods must include a `codemod.yaml` manifest file that defines metadata, dependencies, and publishing information.
-
-### Manifest Schema
-
-```yaml
-# codemod.yaml
-name: react-hooks-migration
-version: 1.0.0
-description: Migrates React class components to functional components with hooks
-author: John Doe <john@example.com>
-license: MIT
-repository: https://github.com/user/react-hooks-migration
-
-registry:
-  access: public
-
-targets:
-  languages:
-    - javascript
-    - typescript
-  frameworks:
-    - react
-  versions:
-    react: ">=16.8.0"
-```
-
-### Required Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | string | Codemod package name (must be unique in scope) |
-| `version` | string | Semantic version (e.g., "1.0.0") |
-| `description` | string | Brief description of what the codemod does |
-| `author` | string | Author name and email |
-
-### Optional Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `license` | string | License identifier (e.g., "MIT", "Apache-2.0") |
-| `repository` | string | Repository URL for the codemod source code |
-| `registry.access` | string | Access level: "public" or "private" |
-| `targets.languages` | array | Supported programming languages |
-| `targets.frameworks` | array | Supported frameworks or libraries |
-| `targets.versions` | object | Version constraints for frameworks |
-
-### Publishing Examples
-
-#### Basic Codemod
-
-```yaml
-name: remove-console-logs
-version: 1.0.0
-description: Removes console.log statements from JavaScript/TypeScript files
-author: Developer <dev@example.com>
-license: MIT
-repository: https://github.com/dev/remove-console-logs
-
-targets:
-  languages: [javascript, typescript]
-```
+[Learn more about codemod packages →](https://docs.codemod.com/cli/packages)
 
-#### Framework-Specific Codemod
+### jssg (JavaScript ast-grep)
 
-```yaml
-name: api-migration-v2
-version: 2.1.0
-description: Migrates legacy API calls to new v2 endpoints
-author: API Team <api-team@company.com>
-license: Apache-2.0
-repository: https://github.com/company/api-migration-v2
-
-registry:
-  access: private
-
-targets:
-  languages: [javascript, typescript]
-  frameworks: [react, vue, angular]
-  versions:
-    react: ">=16.0.0"
-    vue: ">=3.0.0"
-```
+**jssg** enables you to write codemods in JavaScript/TypeScript that transform code in **any language** supported by ast-grep (JavaScript, TypeScript, Python, Rust, Go, Java, C++, and more).
 
-## Workflow Sources
+```typescript
+// Example: Replace console.log with logger.info
+import type { Transform } from "codemod:ast-grep";
+import type TSX from "codemod:ast-grep/langs/tsx";
 
-The CLI supports loading workflows from different sources:
+const transform: Transform<TSX> = (root) => {
+  const rootNode = root.root();
 
-### File Path
-```bash
-codemod run -w path/to/your/workflow.yaml
-```
-Loads the specific file. The base path for execution is the directory containing this file.
+  // Find all console.log calls
+  const consoleCalls = rootNode.findAll({
+    rule: { pattern: "console.log($$$ARGS)" }
+  });
 
-### Directory Path (Bundle)
-```bash
-codemod run path/to/your/bundle/
-```
-Butterflow looks for a standard workflow file (e.g., `workflow.yaml`) inside this directory. The base path for execution is this directory.
+  if (consoleCalls.length === 0) {
+    return null; // No changes needed
+  }
 
-### Registry Identifier
-```bash
-# Install and run a published codemod
-codemod run @my-org/react-hooks-migration@1.0.0
+  // Create edits
+  const edits = consoleCalls.map((node) => {
+    const args = node.getMatch('ARGS')?.text() || '';
+    return node.replace(`logger.info(${args})`);
+  });
 
-# Run latest version
-codemod run @my-org/react-hooks-migration@latest
+  return rootNode.commitEdits(edits);
+};
 
-# Run with custom parameters
-codemod run @my-org/api-migration-v2@2.1.0 --param api_base_url=https://staging-api.example.com
+export default transform;
 ```
 
-When running from a registry, Butterflow:
-1. Downloads the codemod bundle from the registry
-2. Caches it locally for faster subsequent runs
-3. Validates the manifest and workflow
-4. Executes with the bundle directory as the base path
-
-For your information the defautl registry is `https://app.codemod.com/`. and you can visualize codemods on the [Codemod Registry webapp](https://app.codemod.com/registry).
-
-## Workflow Bundles
-
-A workflow bundle is a directory containing:
-1. The main workflow definition file (e.g., `workflow.yaml`)
-2. Any scripts, binaries, or configuration files referenced by the workflow steps
-3. Additional assets needed by the tasks
-
-When running from a directory, Butterflow uses that directory as the root for resolving relative paths during execution.
-
-## Runtime Execution
-
-### Container Runtimes
-
-The CLI supports multiple execution runtimes:
-
-- **Docker**: Uses Docker daemon for container execution
-- **Podman**: Uses Podman for container execution  
-- **Direct**: Runs commands directly on the host machine
-
-When using `runtime: direct`, commands execute with the same working directory as the `codemod` CLI invocation. Use the `$CODEMOD_PATH` environment variable to access files within the workflow bundle.
+jssg combines the power of AST transformations with the flexibility of JavaScript, making complex transformations intuitive and testable.
 
-### Environment Variables
+[Learn more about jssg →](https://docs.codemod.com/jssg)
 
-The CLI provides several environment variables to running tasks:
+### Workflow Orchestration
 
-- `$STATE_OUTPUTS`: File descriptor for writing state updates
-- `$CODEMOD_PATH`: Absolute path to the workflow bundle root (for `direct` runtime)
-- `$BUTTERFLOW_STATE`: Path to state file for programmatic access
-
-## Manual Triggers and Resumption
-
-### Manual Nodes
-
-Nodes with `type: manual` or `trigger: { type: manual }` will pause execution and await manual triggers:
+Workflows define how your codemod package runs. They can orchestrate multiple steps, handle dependencies, manage state, and even include manual approval gates:
 
 ```yaml
-nodes:
-  - id: deploy-prod
-    name: Deploy to Production
-    type: automatic
-    trigger:
-      type: manual  # Requires manual approval
-    steps:
-      - id: deploy
-        run: ./deploy.sh production
-```
-
-### Triggering Manual Tasks
-
-When a workflow pauses for manual triggers:
-
-1. The workflow state is persisted with tasks marked `AwaitingTrigger`
-2. The CLI provides task UUIDs for manual triggering
-3. Use `codemod resume` to trigger specific tasks or all awaiting tasks
-
-```bash
-# Trigger specific deployment task
-codemod resume -i abc123-workflow-run-id -t def456-task-uuid
-
-# Trigger all awaiting tasks and continue
-codemod resume -i abc123-workflow-run-id --trigger-all
-```
-
-## Error Handling
-
-### Automatic Validation
-
-Validation is performed automatically when running workflows:
-
-```bash
-$ codemod run -w invalid-workflow.yaml
-✗ Workflow definition is invalid
-Error: Cyclic dependency detected: node-a → node-b → node-a
-Workflow execution aborted
-```
-
-### Resume After Failures
-
-If a workflow fails or is interrupted:
-
-1. The state is automatically persisted
-2. Use `codemod resume` to continue from the last checkpoint
-3. Failed tasks can be retried while preserving completed work
-
-## Examples
-
-### Basic Workflow Execution
-
-```bash
-# Create and run a simple workflow
-cat > hello.yaml << EOF
 version: "1"
 nodes:
-  - id: greet
-    name: Greeting
+  - id: transform
+    name: Update API Calls
     type: automatic
-    runtime:
-      type: direct
     steps:
-      - id: hello
-        run: echo "Hello from Butterflow!"
-EOF
-
-codemod run -w hello.yaml
-```
-
-### Matrix Workflow with Manual Approval
-
-```bash
-# Run matrix workflow requiring manual triggers
-codemod run -w deploy-workflow.yaml
-
-# When paused, trigger specific environments
-codemod resume -i <run-id> -t <staging-task-uuid>
-codemod resume -i <run-id> -t <prod-task-uuid>
-```
-
-### Workflow Validation and Publishing
-
-```bash
-# Validate before running
-codemod validate -w complex-workflow.yaml
-
-# Run if validation passes
-codemod run -w complex-workflow.yaml
-
-# Login to registry and publish a codemod
-codemod login
-codemod publish ./my-codemod/
-
-# Run published codemod
-codemod run @my-org/my-codemod@1.0.0
-```
-
-### Publishing Workflow
-
-```bash
-# Create and publish a new codemod
-codemod init my-api-migration
-cd my-api-migration
-
-# Develop and test your codemod
-# ... edit workflow.yaml, add rules, scripts, etc.
-
-# Create manifest
-cat > codemod.yaml << EOF
-name: my-api-migration  
-version: 1.0.0
-description: Migrates legacy API calls
-author: Developer <dev@example.com>
-workflow: workflow.yaml
-targets:
-  languages: [javascript, typescript]
-EOF
-
-# Validate and publish
-codemod validate
-codemod publish --dry-run  # Preview
-codemod publish           # Publish to registry
-```
-
-## Global Options
-
-Most commands support these global options:
-
-- `--help, -h`: Show help information
-- `--version, -V`: Show version information
-- `--verbose, -v`: Enable verbose output
-- `--quiet, -q`: Suppress non-essential output
-
-For detailed help on any command, use:
-
-```bash
-codemod <command> --help
-```
-
-## JSSG (JavaScript AST-grep)
-
-JSSG is a JavaScript/TypeScript codemod runner and testing framework inspired by [ast-grep](https://ast-grep.github.io/). It enables you to write codemods in JavaScript and apply them to codebases with powerful CLI and test automation support.
-
-### Running a Codemod
-
-To run a JavaScript codemod on a target directory:
-
-```bash
-codemod jssg run my-codemod.js ./src --language javascript
-```
-
-**Options:**
-- `--language <LANG>`: Target language (javascript, typescript, etc.)
-- `--extensions <ext1,ext2>`: Comma-separated list of file extensions to process
-- `--no-gitignore`: Do not respect .gitignore files
-- `--include-hidden`: Include hidden files and directories
-- `--max-threads <N>`: Maximum number of concurrent threads
-- `--dry-run`: Perform a dry run without making changes
-
-See `codemod jssg run --help` for all options.
-
-### Example
-
-```bash
-codemod jssg run my-codemod.js ./src --language javascript --dry-run
-```
-
----
-
-# JSSG Testing Framework Usage Guide
-
-## Overview
-
-The JSSG Testing Framework provides comprehensive testing capabilities for JavaScript codemods with before/after fixture files. It integrates with the existing ExecutionEngine and provides a familiar test runner interface.
-
-## Quick Start
-
-### 1. Basic Test Structure
-
-Create a test directory with the following structure:
-
-```
-tests/
-├── simple-transform/
-│   ├── input.js
-│   └── expected.js
-├── complex-case/
-│   ├── input.ts
-│   └── expected.ts
-└── multi-file/
-    ├── input/
-    │   ├── file1.js
-    │   └── file2.js
-    └── expected/
-        ├── file1.js
-        └── file2.js
-```
-
-### 2. Running Tests
-
-```bash
-# Basic test run
-codemod jssg test my-codemod.js --language javascript
-
-# With custom test directory
-codemod jssg test my-codemod.js --language typescript --test-directory ./my-tests
-
-# Update snapshots (create/update expected files)
-codemod jssg test my-codemod.js --language javascript --update-snapshots
-
-# Verbose output with detailed diffs
-codemod jssg test my-codemod.js --language javascript --verbose
-
-# Watch mode (re-run tests on file changes)
-codemod jssg test my-codemod.js --language javascript --watch
-```
-
-## CLI Options
-
-### Required Arguments
-- `codemod_file`: Path to the codemod JavaScript file
-- `--language`: Target language (javascript, typescript, etc.)
-
-### Test Discovery
-- `--test-directory`: Test directory (default: "tests")
-- `--filter`: Run only tests matching pattern
-
-### Output Control
-- `--reporter`: Output format (console, json, terse)
-- `--verbose`: Show detailed output
-- `--context-lines`: Number of diff context lines (default: 3)
-- `--ignore-whitespace`: Ignore whitespace in comparisons
-
-### Test Execution
-- `--timeout`: Test timeout in seconds (default: 30)
-- `--max-threads`: Maximum concurrent threads
-- `--sequential`: Run tests sequentially
-- `--fail-fast`: Stop on first failure
-
-### Snapshot Management
-- `--update-snapshots`: Create/update expected files
-- `--expect-errors`: Comma-separated patterns for tests expected to fail
-
-### Development
-- `--watch`: Watch for changes and re-run tests
-
-## Test File Formats
-
-### Single File Format
-Each test case is a directory with `input.{ext}` and `expected.{ext}` files:
-
-```
-test-case-name/
-├── input.js      # Input code
-└── expected.js   # Expected output
-```
-
-### Multi-File Format
-For testing multiple files, use `input/` and `expected/` directories:
-
-```
-test-case-name/
-├── input/
-│   ├── file1.js
-│   └── file2.js
-└── expected/
-    ├── file1.js
-    └── file2.js
-```
-
-## Language Support
-
-The framework automatically detects input files based on language extensions:
-
-- **JavaScript**: `.js`, `.jsx`, `.mjs`
-- **TypeScript**: `.ts`, `.tsx`, `.mts`
-- **Other languages**: Determined by `get_extensions_for_language()`
-
-## Error Handling
-
-### Missing Expected Files
-```bash
-# Error: No expected file found
-codemod jssg test my-codemod.js --language javascript
-# Error: No expected file found for input.js in tests/my-test. Run with --update-snapshots to create it.
-
-# Solution: Create expected files
-codemod jssg test my-codemod.js --language javascript --update-snapshots
-# Created expected file for my-test/input.js
+      - name: "Run jssg codemod"
+        js-ast-grep:
+          js_file: "scripts/update-api.ts"
+          language: "typescript"
+          include:
+            - "**/*.ts"
+            - "**/*.tsx"
+      
+      - name: "Format code"
+        run: npx prettier --write "**/*.{ts,tsx}"
+      
+      - name: "Run tests"
+        run: npm test
 ```
 
-### Ambiguous Input Files
-```bash
-# Error: Multiple input files found
-# tests/my-test/input.js and tests/my-test/input.ts both exist
+[Learn more about workflows →](https://docs.codemod.com/cli/packages/building-workflows)
 
-# Solution: Use only one input file or organize into directories
-```
+## CLI Commands
 
-### Expected Test Failures
-```bash
-# Test cases that should fail
-codemod jssg test my-codemod.js --language javascript --expect-errors "error-case,invalid-syntax"
-```
+### Package Management
 
-## Output Formats
+| Command | Description |
+|---------|-------------|
+| `npx codemod init [path]` | Create a new codemod package with interactive setup |
+| `npx codemod publish [path]` | Publish package to the Codemod Registry |
+| `npx codemod login` | Authenticate with the registry (browser or API key) |
+| `npx codemod logout` | Logout from registry |
+| `npx codemod whoami` | Show current authentication status |
+| `npx codemod search [query]` | Search for packages in the registry |
+| `npx codemod unpublish <package>` | Remove a package from the registry |
 
-### Console (Default)
-```
-test my-test ... ok
-test failing-test ... FAILED
+### Workflow Commands
 
-failures:
+| Command | Description |
+|---------|-------------|
+| `npx codemod workflow run -w <path>` | Run a codemod workflow on your codebase |
+| `npx codemod workflow validate -w <path>` | Validate workflow syntax and structure |
+| `npx codemod workflow resume -i <id>` | Resume a paused workflow |
+| `npx codemod workflow status -i <id>` | Show workflow execution status |
+| `npx codemod workflow list` | List recent workflow runs |
+| `npx codemod workflow cancel -i <id>` | Cancel a running workflow |
 
----- failing-test stdout ----
-Output mismatch for file expected.js:
--const x = 1;
-+const y = 1;
+### jssg Commands
 
-test result: FAILED. 1 passed; 1 failed; 0 ignored
-```
+| Command | Description |
+|---------|-------------|
+| `npx codemod jssg run <file> <target> --language <lang>` | Run a jssg codemod directly |
+| `npx codemod jssg test <file> --language <lang>` | Test jssg codemod with fixtures |
 
-### JSON
-```bash
-codemod jssg test my-codemod.js --language javascript --reporter json
-```
+### Cache Management
 
-```json
-{
-  "type": "suite",
-  "event": "started",
-  "test_count": 2
-}
-{
-  "type": "test",
-  "event": "started",
-  "name": "my-test"
-}
-{
-  "type": "test",
-  "name": "my-test",
-  "event": "ok"
-}
-```
+| Command | Description |
+|---------|-------------|
+| `npx codemod cache info` | Show cache statistics |
+| `npx codemod cache list` | List all cached packages |
+| `npx codemod cache clear [package]` | Clear cache for package or all |
+| `npx codemod cache prune` | Remove old or unused cache entries |
 
-### Terse
-```bash
-codemod jssg test my-codemod.js --language javascript --reporter terse
-```
+**For detailed options and examples, see the [full CLI reference →](https://docs.codemod.com/cli/cli-reference)**
 
-```
-..F
+## Ecosystem & Platform
 
-failures:
-...
-```
+The Codemod CLI is part of a larger ecosystem designed to help teams modernize code at scale:
 
-## Advanced Features
+### Open-Source Tools
 
-### Snapshot Management
-```bash
-# Create initial snapshots
-codemod jssg test my-codemod.js --language javascript --update-snapshots
+- **[Codemod CLI](https://docs.codemod.com/cli)** (this package) – Build, test, and run codemod packages
+- **[Codemod MCP](https://go.codemod.com/mcp-docs)** – Build codemods with AI assistance in your IDE
+- **[Public Registry](https://go.codemod.com/registry)** – Discover and share community codemods
 
-# Update specific test snapshots
-codemod jssg test my-codemod.js --language javascript --filter "specific-test" --update-snapshots
-```
+### Enterprise Platform Features
 
-### Test Filtering
-```bash
-# Run tests matching pattern
-codemod jssg test my-codemod.js --language javascript --filter "transform"
+For teams coordinating migrations across multiple repositories:
 
-# Run specific test
-codemod jssg test my-codemod.js --language javascript --filter "my-specific-test"
-```
+- **[Codemod Studio](https://go.codemod.com/studio)** – AI-powered web interface for creating codemods
+- **[Campaigns](https://docs.codemod.com/migrations)** – Multi-repo orchestration with progress tracking
+- **[Insights](https://docs.codemod.com/insights)** – Analytics dashboards for measuring migration impact
+- **Private Registry** – Secure, organization-scoped codemod packages
 
-### Performance Tuning
-```bash
-# Limit concurrent threads
-codemod jssg test my-codemod.js --language javascript --max-threads 2
+[Learn more about the platform →](https://app.codemod.com)
 
-# Run sequentially for debugging
-codemod jssg test my-codemod.js --language javascript --sequential
+## Resources
 
-# Set custom timeout
-codemod jssg test my-codemod.js --language javascript --timeout 60
-```
+### Documentation
+- **[Full Documentation](https://docs.codemod.com)** – Comprehensive guides and tutorials
+- **[CLI Reference](https://docs.codemod.com/cli/cli-reference)** – Detailed command documentation
+- **[Codemod Packages](https://docs.codemod.com/cli/packages)** – Learn more about codemod packages and workflows
+- **[jssg Documentation](https://docs.codemod.com/jssg)** – JavaScript ast-grep reference
 
-### Diff Customization
-```bash
-# More context in diffs
-codemod jssg test my-codemod.js --language javascript --context-lines 5
+### Get Help
+- **[Slack Community](https://go.codemod.com/community)** – Ask questions and share codemods
+- **[GitHub Discussions](https://github.com/codemod/codemod/discussions)** – Long-form Q&A
+- **[GitHub Issues](https://github.com/codemod/codemod/issues)** – Report bugs or request features
 
-# Ignore whitespace differences
-codemod jssg test my-codemod.js --language javascript --ignore-whitespace
-```
+### Explore
+- **[Codemod Registry](https://go.codemod.com/registry)** – Browse community codemods
+- **[Codemod Studio](https://go.codemod.com/studio)** – Try creating codemods with AI
+- **[Example Codemods](https://github.com/codemod/codemod/tree/main/test-codemods)** – Reference implementations
 
-## Integration with Development Workflow
+## Contributing
 
-### CI/CD Integration
-```yaml
-# GitHub Actions example
-- name: Run codemod tests
-  run: codemod jssg test my-codemod.js --language javascript --reporter json
-```
+Contributions are welcome! Help make codemod automation better for everyone.
 
-### IDE Integration
-The framework outputs standard test results that can be consumed by IDEs and test runners.
+**Ways to contribute:**
+- 🐛 Report bugs via [GitHub Issues](https://github.com/codemod/codemod/issues)
+- 💡 Suggest features on [Feedback Board](https://feedback.codemod.com)
+- 📝 Improve documentation
+- 🔧 Submit pull requests
+- 🌟 Star the repo and spread the word
 
-### Watch Mode Development
-```bash
-# Continuous testing during development
-codemod jssg test my-codemod.js --language javascript --watch --verbose
-```
-
-## Best Practices
-
-1. **Organize tests by functionality**: Group related test cases in descriptive directories
-2. **Use meaningful test names**: Directory names become test names in output
-3. **Start with --update-snapshots**: Generate initial expected files, then review and commit
-4. **Use --expect-errors for negative tests**: Test error conditions explicitly
-5. **Leverage --filter during development**: Focus on specific tests while developing
-6. **Use --watch for rapid iteration**: Get immediate feedback on changes
-
-## Troubleshooting
+Read our [Contributing Guide](https://github.com/codemod/codemod/blob/main/CONTRIBUTING.md) and [Code of Conduct](https://github.com/codemod/codemod/blob/main/CODE_OF_CONDUCT.md).
 
-### Common Issues
+## License
 
-1. **No tests found**: Check test directory path and file extensions
-2. **Ambiguous input files**: Ensure only one input file per test case
-3. **Timeout errors**: Increase timeout for complex codemods
-4. **Memory issues**: Reduce max-threads for large test suites
+MIT License - see [LICENSE](https://github.com/codemod/codemod/blob/main/LICENSE) for details.
 
-### Debug Mode
-```bash
-# Verbose output for debugging
-codemod jssg test my-codemod.js --language javascript --verbose --sequential
-```
+---
 
-This framework provides a robust foundation for testing JavaScript codemods with familiar tooling and comprehensive features.
+<p align="center">
+  <strong>Built with ❤️ by <a href="https://codemod.com">Codemod</a> and the <a href="https://github.com/codemod/codemod/graphs/contributors">open-source community</a></strong>
+</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codemod",
-  "version": "1.1.0-alpha.1",
+  "version": "1.1.1",
   "publishConfig": {
     "access": "public"
   },
@@ -29,11 +29,11 @@
     "postinstall": "node postinstall.js"
   },
   "optionalDependencies": {
-    "@codemod.com/cli-darwin-arm64": "1.1.0-alpha.1",
-    "@codemod.com/cli-darwin-x64": "1.1.0-alpha.1",
-    "@codemod.com/cli-linux-arm64-gnu": "1.1.0-alpha.1",
-    "@codemod.com/cli-linux-x64-gnu": "1.1.0-alpha.1",
-    "@codemod.com/cli-win32-x64-msvc": "1.1.0-alpha.1"
+    "@codemod.com/cli-darwin-arm64": "1.1.1",
+    "@codemod.com/cli-darwin-x64": "1.1.1",
+    "@codemod.com/cli-linux-arm64-gnu": "1.1.1",
+    "@codemod.com/cli-linux-x64-gnu": "1.1.1",
+    "@codemod.com/cli-win32-x64-msvc": "1.1.1"
   },
   "bin": {
     "codemod": "codemod"