npm package: @idlizer/arkui-migrator
Description: CLI tool to migrate ArkUI/ArkTS projects from version 1.1 to 1.2 and convert dynamic TypeScript to static ArkTS
Latest version: 0.1.9

# ArkUI Migrator CLI

A powerful Node.js CLI tool to migrate ArkUI/ArkTS projects from version 1.1 to 1.2 and convert dynamic TypeScript code to static ArkTS dialect.

## Features

- **AI-Powered Migration**: Process entire projects with intelligent rule-based transformations
- **AI-Powered Assistance**: Interactive conversational mode with Anthropic Claude or Deepseek
- **Dry-Run Mode**: Preview all changes before applying them
- **Configurable Rules**: Customize migration behavior with flexible rule engine
- **Comprehensive Reporting**: Detailed migration reports in multiple formats

## System Requirements

### Ubuntu/Debian Dependencies

#### Required System Packages

**Node.js 18+ and npm:**
```bash
# Option 1: Install from NodeSource (recommended for newer Node.js versions)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Option 2: Install from Ubuntu repositories (may have older version)
sudo apt-get update
sudo apt-get install -y nodejs npm
```

**Build tools and utilities:**
```bash
sudo apt-get install -y ninja-build tree git meson
```

**Optional but recommended:**
- `findutils` (usually pre-installed)

#### Verify Installation

After installing the dependencies, verify they are available:

```bash
# Check Node.js version (should be 18+)
node --version

# Check npm version
npm --version

# Check ninja availability
ninja --version

# Check tree availability
tree --version

# Check git availability
git --version

# Check meson availability
meson --version
```

### ArkTS Compilation Environment

The migration tool uses the `ui2abc` compilation system which requires a **Koala workspace** with ArkTS tools. Set up your environment:

```bash
# Clone or set up your Koala workspace
export KOALA_WORKSPACE="$HOME/koala_projects"

# Set environment variables for ArkTS compilation
export PANDA_SDK_PATH="$KOALA_WORKSPACE/incremental/tools/panda/arkts/../node_modules/@panda/sdk"
export FAST_ARKTSC_PATH="$KOALA_WORKSPACE/fast-arktsc/index.js"
export UI2ABC_PATH="$KOALA_WORKSPACE/incremental/tools/panda/arkts/ui2abc"
```

**Note:** Ensure the Koala workspace contains the required ArkTS compilation tools (`fast-arktsc`, `ui2abc`, Panda SDK). Refer to [UI2ABC.md](UI2ABC.md) for detailed setup instructions.

## Installation

```bash
npm install -g arkui-migrator
```

Or use directly with npx:

```bash
npx arkui-migrator chat ./my-project
```

## Quick Start

### Batch Migration

Automated migration without interaction (equivalent to chat mode's `/migrate` command):

```bash
migrator batch ./src --force
```

### Conversational Mode

Interactive AI-assisted migration:

```bash
migrator chat ./src
```

### Initialize Configuration

Create a configuration file:

```bash
migrator init
```

## Configuration

Create a `migrator.config.json` file:

```json
{
  "version": "1.0",
  "migration": {
    "source": "1.1",
    "target": "1.2",
    "mode": "static"
  },
  "ai": {
    "provider": "anthropic",
    "model": "claude-sonnet-4",
    "apiKey": "${ANTHROPIC_API_KEY}"
  },
  "rules": {
    "enabled": ["all"],
    "disabled": [],
    "custom": []
  },
  "files": {
    "include": ["src/**/*.ets", "src/**/*.ts"],
    "exclude": ["node_modules/**", "**/*.test.ts"]
  },
  "output": {
    "dryRun": false,
    "reports": true,
    "logLevel": "info"
  },
  "history": {
    "enabled": true,
    "maxEntries": 10000,
    "maxFileSizeBytes": 5242880,
    "perProject": true
  }
}
```

## CLI Commands

### `migrator batch <path>`

Run automated batch migration (non-interactive equivalent of `/migrate` command in chat mode).

**Options:**
- `--model <model>` - AI model to use (claude-sonnet-4, deepseek-coder)
- `--provider <provider>` - AI provider (anthropic, deepseek, grok)
- `--verbose` - Enable verbose logging
- `--force` - Automatically clear output directory if it exists

### `migrator chat <path>`

Start interactive conversational mode with bash-like history features.

**Options:**
- `--model <model>` - AI model to use (claude-sonnet-4, deepseek-coder)
- `--provider <provider>` - AI provider (anthropic, deepseek)

**Features:**
- ↑/↓ arrow key navigation through command history
- Ctrl+R reverse-i-search for quick history lookup
- Persistent history across sessions (per-project or global)
- Automatic API key sanitization for security
- Slash commands: `/fix`, `/migrate`, `/help`, `/save`, `/history`, `/clear`, `/allow`, `/safe`, `/exit`, `/validate`, `/list`, `/search`, `/remove`
- Tab completion for slash commands
- Type `history` to view recent entries, `clear history` to reset

See [QUICK_START.md](QUICK_START.md#chat-mode-navigation--history) for detailed usage.

### `migrator init`

Initialize a configuration file in the current directory.

### `migrator validate <path>`

Validate migrated code without making changes.

## Migration Rules

The migrator includes comprehensive rules for:

- **API Changes**: v1.1 → v1.2 API updates
- **State Management**: V1 → V2 state patterns
- **Type System**: Dynamic → Static typing
- **Syntax**: ArkTS language restrictions

See [docs/rules.md](docs/rules.md) for detailed rule documentation.

## Reference Projects

Reference example projects are available in [`example/`](example/README.md):

- **`Hello11/`** – Complete ArkUI 1.1 project (source for migration)
- **`Hello12/`** – Complete ArkUI 1.2 project (target after migration)

These projects demonstrate the key differences between ArkTS versions, including:
- ArkTS version declaration in `build-profile.json5`
- `'use static'` directive requirement
- Import statement updates from `@kit.*` to `@ohos.*` packages
- Explicit component and state management imports

Use these projects as references when developing or testing migration rules.

## Development

```bash
# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Test changes with playground
npm run playground:chat

# Type check
npm run typecheck

# Lint
npm run lint
```

## License

MIT