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

• Automated Migration: Batch 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
• Git Integration: Automatic backups and version control
• Comprehensive Reporting: Detailed migration reports in multiple formats

System Requirements

Ubuntu/Debian Dependencies

Required System Packages

Node.js 18+ and npm:

# 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:

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:

# 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:

# 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 for detailed setup instructions.

Installation

npm install -g arkui-migrator

Or use directly with npx:

npx arkui-migrator batch ./my-project

Quick Start

Batch Migration

Migrate an entire project automatically:

migrator batch ./src --dry-run
migrator batch ./src

Conversational Mode

Interactive AI-assisted migration:

migrator chat ./src

Initialize Configuration

Create a configuration file:

migrator init

Configuration

Create a migrator.config.json file:

{
  "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,
    "backup": true,
    "reports": true,
    "logLevel": "info"
  },
  "history": {
    "enabled": true,
    "maxEntries": 10000,
    "maxFileSizeBytes": 5242880,
    "perProject": true
  }
}

CLI Commands

migrator batch <path>

Run automated batch migration on a directory.

Options:

• --dry-run - Preview changes without modifying files
• --rules <rules> - Comma-separated list of rules to apply
• --verbose - Enable verbose logging
• --no-backup - Skip automatic backup

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 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 for detailed rule documentation.

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Run tests
npm test

# Type check
npm run typecheck

# Lint
npm run lint

License

MIT