npm package: @refactor-tool/cli
Description: AI-powered refactoring tool for frontend projects with OpenSpec integration
Author: Refactor Tool Contributors
Latest version: 0.1.1

# Refactor Tool

AI-powered refactoring tool for frontend projects with OpenSpec integration.

## Overview

Refactor Tool helps you refactor frontend projects (React@16.14 + TypeScript + antd@4) using independent refactor capabilities. Each capability can be executed independently without requiring other capabilities to complete first.

**Available Capabilities:**
1. **directory-structure** - Analyze and refactor project/component directory structure
2. **component-design** - Analyze component design, props, and reusability
3. **code-style** - Analyze code style issues (ESLint, Stylelint, TypeScript, JS→TS conversion)
4. **business-logic** - Analyze business logic, state management, and API patterns
5. **styled-jsx-to-css-module** - Convert styled-jsx to CSS Module format

## Features

- ✅ **Independent capabilities** - Execute any refactor capability independently
- ✅ **Optional stage workflow** - Use `--stage-mode` for stage-based workflow if preferred
- ✅ **OpenSpec integration** - Manage refactoring proposals with OpenSpec
- ✅ **Cursor IDE support** - Integrated commands and skills for Cursor
- ✅ **Capability dependencies** - Optional dependency checking with warnings (non-blocking)
- ✅ **Batch analysis** - Support for large projects with incremental analysis

## Installation

```bash
npm install -g @refactor-tool/cli
```

## Quick Start

1. **Initialize the tool in your project:**
```bash
refactor init
```

This creates:
- `refactor/` directory with OpenSpec structure
- 4 refactoring skills in `.cursor/skills/`
- Cursor commands in `.cursor/commands/`

2. **Start refactoring:**
   - Use `/refactor-tool-refactor` command in Cursor to analyze your project
   - Review and apply proposals using `/refactor-tool-apply`
   - Archive completed proposals using `/refactor-tool-archive`

## CLI Commands

- `refactor init [path]` - Initialize refactor tool in your project
- `refactor capabilities` - List all available refactor capabilities
- `refactor list` - List all active refactoring proposals
- `refactor show [proposal-id]` - Show a refactoring proposal
- `refactor archive [proposal-id]` - Archive a completed proposal
- `refactor update [path]` - Update refactor tool instruction files

## Cursor Commands

After running `refactor init`, these commands are available in Cursor:

- `/refactor-tool-refactor` - Start refactoring analysis (shows capability list)
- `/refactor-tool-refactor <capability-id>` - Execute a specific capability directly
- `/refactor-tool-apply` - Apply a refactoring proposal
- `/refactor-tool-archive` - Archive a completed proposal

## Refactoring Capabilities

The tool includes 5 refactor capabilities (each can be executed independently):

1. **directory-structure** - Analyzes directory structure and organization
2. **component-design** - Analyzes component design and architecture
3. **code-style** - Analyzes code style and linting issues
4. **business-logic** - Analyzes business logic and patterns
5. **styled-jsx-to-css-module** - Converts styled-jsx to CSS Module format

## Workflow (Default - Independent Mode)

1. Run `refactor init` to set up the tool
2. Use `/refactor-tool-refactor` to select a capability, or `/refactor-tool-refactor <capability-id>` to run directly
3. Review generated OpenSpec proposals
4. Apply proposals using `/refactor-tool-apply` or manually
5. Archive completed proposals
6. Execute other capabilities as needed (no order required)

## Workflow (Optional - Stage Mode)

If you prefer stage-based workflow:

1. Use `--stage-mode` flag: `refactor run <capability> --stage-mode`
2. Execute capabilities in stage order
3. Complete all proposals in a stage before moving to next
4. Stage gate checks are enforced

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Development mode (watch)
npm run dev

# Run CLI locally
npm run dev:cli

# Test
npm test
```

## Project Structure

```
refactor/
├── AGENTS.md              # Instructions for AI assistants
├── project.md             # Project context and conventions
├── progress.md            # Progress tracking (capability execution history)
├── specs/                 # Refactoring specifications
│   ├── directory-structure/
│   ├── component-design/
│   ├── code-style/
│   └── business-logic/
└── changes/               # OpenSpec proposals
    ├── <change-id>/       # Active proposals
    │   ├── proposal.md    # Proposal details
    │   ├── tasks.md       # Implementation tasks
    │   ├── design.md      # Design decisions (optional)
    │   ├── analysis.md    # Analysis report (generated by AI)
    │   ├── context.md     # Skill execution context
    │   └── specs/         # Specification deltas
    └── archive/           # Archived proposals
        └── YYYY-MM-DD-<change-id>/

.cursor/
├── commands/              # Cursor commands
│   ├── refactor-tool-refactor.md
│   ├── refactor-tool-apply.md
│   └── refactor-tool-archive.md
└── skills/                # Refactoring skills
    ├── directory-structure-refactor/
    ├── component-design-refactor/
    ├── code-style-refactor/
    └── business-logic-refactor/
```

## File Path Conventions

Refactor Tool uses standard file path conventions to ensure AI knows which files to read:

- **Analysis Report**: `refactor/changes/<change-id>/analysis.md` - Generated by AI based on skill capabilities
- **Proposal Context**: `refactor/changes/<change-id>/context.md` - Skill execution context (skill name, capability ID, analysis report path, execution params)
- **Progress Tracking**: `refactor/progress.md` - Capability execution history and proposal associations

**Proposal Completeness**:
- Each proposal directory contains all materials for that requirement (proposal.md, tasks.md, design.md, analysis.md, context.md, specs/)
- When archiving, all files in the proposal directory are archived together to `refactor/changes/archive/YYYY-MM-DD-<proposal-id>/`
- This ensures no redundant files remain in the project after archiving

## Requirements

- Node.js >= 20.19.0
- OpenSpec (installed globally or as dependency)
- Cursor IDE (for full integration)

## License

MIT