@robota-sdk/agent-cli 3.0.0-beta.60 → 3.0.0-beta.62

package/README.ko.md

@@ -0,0 +1,297 @@
+**Language:** [English](README.md) | [한국어](README.ko.md)
+
+# @robota-sdk/agent-cli
+
+Robota SDK 기반의 AI 코딩 어시스턴트 CLI. AGENTS.md/CLAUDE.md를 로드하여 프로젝트 컨텍스트를 파악하고, Claude Code 호환 권한 모드를 갖춘 도구 호출 REPL을 제공합니다.
+
+## 시스템 요구사항
+
+**Node.js 22 이상** 필요합니다.
+
+```bash
+node --version  # v22.x.x 이상이어야 합니다
+```
+
+Node.js 버전이 22 미만이라면 [nvm](https://github.com/nvm-sh/nvm)으로 업그레이드:
+
+```bash
+nvm install 22
+nvm use 22
+```
+
+## 설치
+
+```bash
+# 전역 설치
+npm install -g @robota-sdk/agent-cli
+
+# 또는 npx로 직접 실행
+npx @robota-sdk/agent-cli
+```
+
+> **macOS Terminal.app 사용자**: 한국어/중국어/일본어 입력 시 크래시가 발생할 수 있습니다. **[iTerm2](https://iterm2.com/)** 사용을 권장합니다. 이는 Ink + Terminal.app의 알려진 문제로 Claude Code와 동일합니다.
+
+전역 설치 후 시스템 전체에서 `robota` 명령어를 사용할 수 있습니다:
+
+```bash
+robota                        # 인터랙티브 REPL
+robota "프롬프트"              # 초기 프롬프트와 함께 REPL 시작
+robota -p "파일 목록 출력"     # 출력 모드 (단발성, 응답 후 종료)
+```
+
+### 환경 변수
+
+| 변수                | 설명                                     | 필수 여부      |
+| ------------------- | ---------------------------------------- | -------------- |
+| `ANTHROPIC_API_KEY` | Anthropic 프로바이더용 API 키            | Anthropic 전용 |
+| `DEEPSEEK_API_KEY`  | DeepSeek 프로바이더용 API 키             | DeepSeek 전용  |
+| `DASHSCOPE_API_KEY` | Qwen(알리바바 클라우드) 모델 스튜디오 키 | Qwen 전용      |
+
+실행 전 키를 설정하세요:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+## 개발 환경 설정 (모노레포)
+
+```bash
+# 의존성 및 CLI 빌드
+pnpm build:deps
+pnpm --filter @robota-sdk/agent-cli build
+```
+
+## 실행 (모노레포)
+
+```bash
+# 모노레포 루트에서
+cd packages/agent-cli
+
+# 개발 모드 (빌드 불필요)
+pnpm dev
+
+# 프로덕션 모드 (빌드 필요)
+pnpm start
+
+# 인자 포함 실행
+pnpm dev -- --version
+pnpm dev -- --permission-mode plan
+pnpm dev -- -p "src/ 내 모든 TypeScript 파일 목록"
+```
+
+## CLI 플래그
+
+```
+robota                              # 인터랙티브 REPL (기본 모드)
+robota "프롬프트"                   # 초기 프롬프트와 함께 REPL 시작
+robota -p "프롬프트"                # 출력 모드 (단발성, 응답 후 종료)
+robota -c                           # 마지막 세션 이어서 시작
+robota -r <session-id>              # 세션 ID로 세션 재개
+robota --model <모델>               # 모델 지정 (예: claude-sonnet-4-6)
+robota --language <언어>            # 응답 언어 (ko, en, ja, zh)
+robota --permission-mode <모드>     # plan | default | acceptEdits | bypassPermissions
+robota --max-turns <n>              # 인터랙션당 에이전틱 턴 제한
+robota --output-format <형식>       # text | json | stream-json (출력 모드)
+robota --system-prompt <텍스트>     # 시스템 프롬프트 교체 (출력 모드)
+robota --append-system-prompt <텍스트> # 시스템 프롬프트에 추가 (출력 모드)
+robota --reset                      # 사용자 설정 삭제 후 종료
+robota --check-update               # npm에서 최신 CLI 버전 확인 후 종료
+robota --disable-update-check       # 이번 실행에서 시작 시 업데이트 확인 건너뜀
+robota --version                    # 버전 표시
+```
+
+### CLI 업데이트 확인
+
+```bash
+robota --check-update
+```
+
+업데이트가 있으면 npm 전역 설치 명령어를 출력합니다:
+
+```bash
+npm install -g '@robota-sdk/agent-cli@latest'
+```
+
+### 출력 모드 형식
+
+출력 모드(`-p`)는 `--output-format`으로 세 가지 형식을 지원합니다:
+
+| 형식          | 설명                                                             |
+| ------------- | ---------------------------------------------------------------- |
+| `text`        | 표준 출력에 일반 텍스트 응답 (기본값)                            |
+| `json`        | 단일 JSON 객체: `{ type, result, session_id, subtype }`          |
+| `stream-json` | `content_block_delta` 스트리밍 이벤트를 줄바꿈으로 구분한 NDJSON |
+
+### 표준 입력(Stdin) 파이프
+
+`-p`와 위치 인자 없이 stdin이 파이프되면 CLI가 stdin에서 읽습니다:
+
+```bash
+echo "이 오류를 설명해줘" | robota -p
+cat file.ts | robota -p "이 코드를 검토해줘" --output-format json
+git diff | robota -p "변경 사항 요약" --output-format stream-json
+```
+
+## 최초 실행 설정
+
+사용 가능한 설정 파일이 없으면 CLI가 다음을 안내합니다:
+
+1. **프로바이더 선택** — CLI 바이너리에 포함된 프로바이더 중 선택
+2. **프로바이더별 설정** — 모델, base URL, 마스킹된 API 키 등
+3. **응답 언어** (ko/en/ja/zh, 기본값: en)
+
+`~/.robota/settings.json`에 설정이 저장됩니다. `robota --reset`으로 최초 실행 상태로 되돌릴 수 있습니다.
+
+## 내장 도구
+
+AI 에이전트는 8개의 로컬 도구를 호출할 수 있습니다:
+
+| 도구        | 설명                          | 주요 인자  |
+| ----------- | ----------------------------- | ---------- |
+| `Bash`      | 셸 명령 실행                  | `command`  |
+| `Read`      | 줄 번호와 함께 파일 내용 읽기 | `filePath` |
+| `Write`     | 파일에 내용 쓰기              | `filePath` |
+| `Edit`      | 파일의 문자열 교체            | `filePath` |
+| `Glob`      | 패턴으로 파일 검색            | `pattern`  |
+| `Grep`      | 정규식으로 파일 내용 검색     | `pattern`  |
+| `WebFetch`  | URL 내용을 텍스트로 가져오기  | `url`      |
+| `WebSearch` | 인터넷 검색                   | `query`    |
+
+## 권한 시스템
+
+모든 도구 호출은 세 단계 권한 게이트를 통과합니다:
+
+1. **거부 목록** — 거부 패턴이 일치하면 차단
+2. **허용 목록** — 허용 패턴이 일치하면 자동 승인
+3. **모드 정책** — 활성 권한 모드에 따라 결정
+
+### 권한 모드
+
+| 모드                | Read/Glob/Grep | Write/Edit | Bash |
+| ------------------- | :------------: | :--------: | :--: |
+| `plan`              |      자동      |    거부    | 거부 |
+| `default`           |      자동      |    승인    | 승인 |
+| `acceptEdits`       |      자동      |    자동    | 승인 |
+| `bypassPermissions` |      자동      |    자동    | 자동 |
+
+### 런타임 모드 변경
+
+`/permissions` 슬래시 커맨드 사용:
+
+```
+> /permissions                    # 현재 모드 및 세션 승인 도구 표시
+> /permissions plan               # 읽기 전용 모드로 전환
+> /permissions bypassPermissions  # 모든 프롬프트 건너뜀
+```
+
+또는 시작 시 설정:
+
+```bash
+robota --permission-mode plan
+```
+
+### 권한 패턴
+
+`.robota/settings.json` 또는 `.robota/settings.local.json`에 설정:
+
+```json
+{
+  "permissions": {
+    "allow": ["Bash(pnpm *)", "Bash(git status)", "Read(/src/**)"],
+    "deny": ["Bash(rm -rf *)", "Write(.env)"]
+  }
+}
+```
+
+패턴 문법: `ToolName`은 모든 호출에 매칭; `ToolName(pattern)`은 셸 스타일 글로브(`*`, `**`)로 주요 인자에 매칭.
+
+## 키보드 단축키
+
+| 키        | 동작                                       |
+| --------- | ------------------------------------------ |
+| Enter     | 입력 제출                                  |
+| ESC       | 현재 실행 중단 (부분 응답 저장)            |
+| Ctrl+C    | 즉시 프로세스 종료                         |
+| Up/Down   | 여러 줄 입력에서 줄 탐색                   |
+| 화살표 키 | 슬래시 커맨드 자동완성, 권한 프롬프트 탐색 |
+
+## 주요 슬래시 커맨드
+
+| 커맨드                | 설명                                            |
+| --------------------- | ----------------------------------------------- |
+| `/help`               | 사용 가능한 커맨드 표시                         |
+| `/clear`              | 대화 기록 초기화                                |
+| `/model [모델명]`     | AI 모델 변경 (확인 프롬프트, CLI 재시작)        |
+| `/language [언어]`    | 응답 언어 설정 (ko, en, ja, zh), 저장 후 재시작 |
+| `/compact [지시사항]` | 컨텍스트 창 압축                                |
+| `/cost`               | 세션 정보 표시                                  |
+| `/context`            | 컨텍스트 창 상세, 참조 목록, 자동 압축 설정     |
+| `/agent`              | 백그라운드 서브에이전트 작업 실행 및 관리       |
+| `/permissions [모드]` | 권한 규칙 표시 또는 권한 모드 변경              |
+| `/plugin [하위명령]`  | 플러그인 관리                                   |
+| `/resume`             | 최근 세션 목록 표시 및 재개                     |
+| `/rename <이름>`      | 현재 세션 이름 변경                             |
+| `/exit`               | CLI 종료                                        |
+
+## 세션 관리
+
+### CLI 플래그
+
+| 플래그                | 설명                                     |
+| --------------------- | ---------------------------------------- |
+| `-c`, `--continue`    | 가장 최근 세션 이어서 시작               |
+| `-r`, `--resume <id>` | 특정 세션 ID로 재개                      |
+| `--fork-session <id>` | 세션 포크 (복사된 기록으로 새 세션 시작) |
+| `--name <이름>`       | 시작 시 세션에 이름 지정                 |
+
+## 설정
+
+설정은 다음 순서로 병합됩니다 (낮은 우선순위 → 높은 우선순위):
+
+1. `~/.robota/settings.json` (사용자 전역)
+2. `~/.claude/settings.json` (사용자 전역, Claude Code 호환)
+3. `.robota/settings.json` (프로젝트, 공유)
+4. `.robota/settings.local.json` (로컬, gitignore 대상)
+5. `.claude/settings.json` (프로젝트, Claude Code 호환)
+6. `.claude/settings.local.json` (로컬, gitignore 대상, Claude Code 호환)
+
+```json
+{
+  "defaultMode": "default",
+  "language": "ko",
+  "currentProvider": "claude-sonnet-4-6",
+  "providers": {
+    "claude-sonnet-4-6": {
+      "type": "anthropic",
+      "model": "claude-sonnet-4-6",
+      "apiKey": "$ENV:ANTHROPIC_API_KEY"
+    }
+  },
+  "permissions": {
+    "allow": ["Bash(pnpm *)"],
+    "deny": ["Bash(rm -rf *)"]
+  }
+}
+```
+
+## 컨텍스트 자동 탐색
+
+CLI는 다음을 자동으로 탐색하고 로드합니다:
+
+- **AGENTS.md** — cwd에서 파일시스템 루트까지 상위 디렉토리 탐색
+- **CLAUDE.md** — 동일한 상위 탐색
+- **프로젝트 메타데이터** — `package.json`, `tsconfig.json`
+
+모든 컨텍스트가 시스템 프롬프트로 조합됩니다.
+
+## 세션 로깅
+
+세션 로그는 JSONL 형식으로 `.robota/logs/{sessionId}.jsonl`에 기록됩니다. 재개 가능한 세션 JSON은 `.robota/sessions/{sessionId}.json`에 저장됩니다.
+
+## 아키텍처
+
+CLI는 순수 TUI 레이어입니다. 모든 비즈니스 로직은 `@robota-sdk/agent-sdk`의 `InteractiveSession`에 있습니다. `useInteractiveSession`이 유일한 React↔SDK 브릿지입니다.
+
+## 라이선스
+
+MIT

package/README.md

@@ -1,10 +1,25 @@
+**Language:** [English](README.md) | [한국어](README.ko.md)
+
 # @robota-sdk/agent-cli
 
 AI coding assistant CLI built on Robota SDK. Loads AGENTS.md/CLAUDE.md for project context and provides a tool-calling REPL with Claude Code-compatible permission modes.
 
-## Installation
+## Prerequisites
 
-Requires Node.js 22+.
+Node.js **22 or higher** is required.
+
+```bash
+node --version  # Must output v22.x.x or higher
+```
+
+If your version is below 22, upgrade using [nvm](https://github.com/nvm-sh/nvm):
+
+```bash
+nvm install 22
+nvm use 22
+```
+
+## Installation
 
 ```bash
 # Global install
@@ -29,6 +44,7 @@ robota -p "List all files"    # Print mode (one-shot, exit after response)
 | Variable            | Description                                    | Required       |
 | ------------------- | ---------------------------------------------- | -------------- |
 | `ANTHROPIC_API_KEY` | Anthropic API key for the `anthropic` provider | Anthropic only |
+| `DEEPSEEK_API_KEY`  | DeepSeek API key for the `deepseek` provider   | DeepSeek only  |
 | `DASHSCOPE_API_KEY` | Alibaba Cloud Model Studio key for `qwen`      | Qwen only      |
 
 Set your key before running:
@@ -130,7 +146,14 @@ When no usable settings file exists, the CLI prompts for:
 
 Creates `~/.robota/settings.json`. Use `robota --reset` to return to first-run state.
 
-Provider setup is generated from provider definitions. The default CLI build includes Anthropic, OpenAI-compatible, Gemma, and Qwen providers; other embeddings can inject their own provider definitions.
+Provider setup is generated from provider definitions. The default CLI build includes Anthropic,
+OpenAI-compatible, DeepSeek, Gemma, and Qwen providers; other embeddings can inject their own
+provider definitions.
+Interactive setup creates a readable profile key from the selected model id, such as
+`claude-sonnet-4-6` or `gpt-4o`, and appends `-2`, `-3`, etc. when that key already exists. Generated
+profile keys never include API keys or credential hints.
+
+Inside the TUI, `/provider` and `/provider list` show configured profiles as an interactive picker. Selecting a profile opens command-owned actions for switch, edit, test, duplicate, delete, and cancel. Headless mode prints the same profile list text without opening prompts.
 
 Non-interactive/headless mode never prompts. Configure a provider ahead of time with `robota --configure` in an interactive terminal, or use `robota --configure-provider <profile> --type <type> ... --set-current`.
 
@@ -151,12 +174,14 @@ The AI agent can invoke 8 local tools:
 
 ## Recent TUI Capabilities
 
-- Provider setup is generated from provider definitions, so the default CLI build can configure Anthropic, OpenAI-compatible, Gemma, and Qwen profiles without provider-specific UI branches.
+- Provider setup and profile management are generated from provider definitions, so the default CLI
+  build can configure, switch, edit, test, duplicate, and delete Anthropic, OpenAI-compatible,
+  DeepSeek, Gemma, and Qwen profiles without provider-specific UI branches.
 - Interactive startup can check npm for newer CLI versions; print/headless mode skips startup update checks to keep scripted output deterministic.
 - Long-running sessions show provider usage summaries, status activity, background job tree rows, and collapsed command-output transcripts.
 - Edit results render as context hunks with markdown-friendly diff blocks.
 - Background subagents are real runtime jobs with transcripts and resumable task snapshots.
-- Explicit multi-agent requests can use the Agent tool `jobs` batch path through the SDK runtime.
+- Explicit multi-agent requests use the `/agent` command module batch path through the SDK runtime.
 
 ## Permission System
 
@@ -177,12 +202,12 @@ Every tool call passes through a three-step permission gate:
 
 ### Changing Mode at Runtime
 
-Use the `/mode` slash command:
+Use the `/permissions` slash command:
 
 ```
-> /mode                    # Show current mode
-> /mode plan               # Switch to plan (read-only)
-> /mode bypassPermissions  # Skip all prompts
+> /permissions                    # Show current mode and session-approved tools
+> /permissions plan               # Switch to plan (read-only)
+> /permissions bypassPermissions  # Skip all prompts
 ```
 
 Or set it at startup:
@@ -261,28 +286,27 @@ When a session has a name, it appears in three places:
 
 - **Input border** — session name shown in the input area border
 - **Terminal title** — updated via ANSI escape sequences
-- **StatusBar** — displayed alongside mode, model, and context usage
+- **StatusBar** — displayed alongside activity, model, and context usage
 
 ## Slash Commands
 
-| Command                   | Description                                                |
-| ------------------------- | ---------------------------------------------------------- |
-| `/help`                   | Show available commands                                    |
-| `/clear`                  | Clear conversation history                                 |
-| `/mode [mode]`            | Show or change permission mode                             |
-| `/model [model]`          | Select AI model (confirmation prompt, CLI restarts)        |
-| `/language [lang]`        | Set response language (ko, en, ja, zh), saves and restarts |
-| `/compact [instructions]` | Compress context window                                    |
-| `/cost`                   | Show session info                                          |
-| `/context`                | Context window details                                     |
-| `/agent`                  | Run and manage background subagent jobs                    |
-| `/permissions`            | Show permission rules                                      |
-| `/plugin [subcommand]`    | Plugin management                                          |
-| `/resume`                 | List recent sessions and resume one                        |
-| `/rename <name>`          | Rename the current session                                 |
-| `/exit`                   | Exit CLI                                                   |
-
-Typing `/` triggers an autocomplete popup with arrow-key navigation and Esc to dismiss. Tab inserts the highlighted command into the input field without executing — continue typing args or press Enter to execute. Enter selects and executes immediately. Commands with subcommands (e.g., `/mode`, `/model`) show a nested submenu. Skill commands discovered from `.agents/skills/` and `.claude/commands/` appear alongside built-in commands.
+| Command                   | Description                                                            |
+| ------------------------- | ---------------------------------------------------------------------- |
+| `/help`                   | Show available commands                                                |
+| `/clear`                  | Clear conversation history                                             |
+| `/model [model]`          | Select AI model (confirmation prompt, CLI restarts)                    |
+| `/language [lang]`        | Set response language (ko, en, ja, zh), saves and restarts             |
+| `/compact [instructions]` | Compress context window                                                |
+| `/cost`                   | Show session info                                                      |
+| `/context`                | Context window details, reference inventory, and auto-compact controls |
+| `/agent`                  | Run and manage background subagent jobs                                |
+| `/permissions [mode]`     | Show permission rules or change permission mode                        |
+| `/plugin [subcommand]`    | Plugin management                                                      |
+| `/resume`                 | List recent sessions and resume one                                    |
+| `/rename <name>`          | Rename the current session                                             |
+| `/exit`                   | Exit CLI                                                               |
+
+Typing `/` triggers an autocomplete popup with arrow-key navigation and Esc to dismiss. Tab inserts the highlighted command into the input field without executing — continue typing args or press Enter to execute. Enter selects and executes immediately. Commands with subcommands (e.g., `/permissions`, `/model`) show a nested submenu. Skill commands discovered from `.agents/skills/` and `.claude/commands/` appear alongside built-in commands.
 
 ## Plugin Management
 
@@ -315,26 +339,26 @@ Settings are merged in this order, from lowest to highest priority:
 {
   "defaultMode": "default",
   "language": "en",
-  "currentProvider": "qwen",
+  "currentProvider": "qwen-plus",
   "providers": {
-    "qwen": {
+    "qwen-plus": {
       "type": "qwen",
       "model": "qwen-plus",
       "apiKey": "$ENV:DASHSCOPE_API_KEY",
       "baseURL": "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
     },
-    "gemma": {
+    "supergemma4-26b-uncensored-v2": {
       "type": "gemma",
       "model": "supergemma4-26b-uncensored-v2",
       "apiKey": "lm-studio",
       "baseURL": "http://localhost:1234/v1"
     },
-    "openai": {
+    "gpt-4o": {
       "type": "openai",
-      "model": "<openai-compatible-model>",
+      "model": "gpt-4o",
       "apiKey": "$ENV:OPENAI_API_KEY"
     },
-    "anthropic": {
+    "claude-sonnet-4-6": {
       "type": "anthropic",
       "model": "claude-sonnet-4-6",
       "apiKey": "$ENV:ANTHROPIC_API_KEY"
@@ -347,7 +371,17 @@ Settings are merged in this order, from lowest to highest priority:
 }
 ```
 
-`currentProvider` selects a profile from `providers`. Qwen Model Studio profiles use `type: "qwen"` with a DashScope-compatible `baseURL`; the API key is usually stored as `$ENV:DASHSCOPE_API_KEY`. Gemma-family LM Studio models use `type: "gemma"` so Robota can apply Gemma-specific channel-marker projection while still talking to the OpenAI-compatible `/v1/chat/completions` API through `baseURL`. Generic OpenAI-compatible profiles use `type: "openai"` and do not apply provider-specific projection. The legacy single-provider shape remains supported:
+`currentProvider` selects a profile key from `providers`. The key is the stable profile identity, not
+the provider type; multiple profile keys may use the same provider type and model when they represent
+different credentials, endpoints, accounts, or operational defaults. Qwen Model Studio profiles use
+`type: "qwen"` with a DashScope-compatible `baseURL`; the API key is usually stored as
+`$ENV:DASHSCOPE_API_KEY`. DeepSeek profiles use `type: "deepseek"` with
+`https://api.deepseek.com` and `$ENV:DEEPSEEK_API_KEY`. Gemma-family LM Studio models use
+`type: "gemma"` so Robota can apply Gemma-specific channel-marker projection while still talking to
+the OpenAI-compatible `/v1/chat/completions` API through `baseURL`. Generic OpenAI-compatible profiles use
+`type: "openai"` and do not apply provider-specific projection. Use `--provider <profile>` for a
+one-shot invocation override; add `--set-current` only when the selected profile should become the
+persisted default. The legacy single-provider shape remains supported:
 
 ```json
 {
@@ -369,6 +403,11 @@ The CLI automatically discovers and loads:
 
 All context is assembled into the system prompt.
 
+Ordinary prompts may also reference workspace-local files with path-like `@file` tokens, for
+example `@AGENTS.md` or `@docs/SPEC.md`. The CLI passes those prompts through unchanged; the SDK
+resolves bounded file content under the active `cwd`, sends the enriched prompt to the model, and
+records a structured file-reference event in the session history.
+
 ## Memory Management
 
 - **Message windowing** — React state keeps the most recent 100 messages. Older messages are dropped from the render tree; full history remains in the session store.
@@ -392,14 +431,14 @@ bin.ts → cli.ts (arg parsing)
                     │   ├── InteractiveSession (SDK)
                     │   ├── CommandRegistry    (SDK, re-exported by CLI)
                     │   │   ├── BuiltinCommandSource  (SDK, empty by default)
-                    │   │   ├── SkillCommandSource    (SDK, discovers from 4 paths)
+                    │   │   ├── agent-command-skills  (/skills command + virtual skill aliases)
                     │   │   ├── PluginCommandSource   (SDK, plugin skills)
                     │   │   └── ICommandModule sources (/help, /compact, ...)
                     │   └── SystemCommandExecutor (SDK)
                     ├── plugin-hooks-merger.ts (merges plugin hooks into SDK config)
                     ├── MessageList.tsx
                     ├── InputArea.tsx          (CjkTextInput, bracketed paste, slash detection)
-                    ├── StatusBar.tsx          (mode, model, context %, message count)
+                    ├── StatusBar.tsx          (activity, conditional mode, model, context %)
                     ├── PermissionPrompt.tsx   (arrow-key Allow/Deny)
                     ├── SlashAutocomplete.tsx  (command popup with scroll)
                     ├── DiffBlock.tsx          (Edit tool diff display)

package/bin/robota.cjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+'use strict';
+// CJS wrapper — runs synchronously before any ESM module is loaded.
+// Static ESM imports in dist/node/bin.js are hoisted by the JS engine,
+// so version/env checks placed there would execute too late.
+
+const REQUIRED_NODE_MAJOR = 22;
+const nodeMajor = parseInt(process.versions.node.split('.')[0], 10);
+if (nodeMajor < REQUIRED_NODE_MAJOR) {
+  process.stderr.write(
+    '\n  Robota requires Node.js ' +
+      REQUIRED_NODE_MAJOR +
+      ' or higher.\n' +
+      '  Current version: ' +
+      process.versions.node +
+      '\n\n' +
+      '  Upgrade options:\n' +
+      '    nvm: nvm install ' +
+      REQUIRED_NODE_MAJOR +
+      ' && nvm use ' +
+      REQUIRED_NODE_MAJOR +
+      '\n' +
+      '    Download: https://nodejs.org/en/download\n\n',
+  );
+  process.exit(1);
+}
+
+if (process.env.TERM_PROGRAM === 'Apple_Terminal') {
+  process.stderr.write(
+    '\n  ⚠️  Warning: macOS Terminal.app detected.\n' +
+      '  CJK input (Korean/Chinese/Japanese) may cause crashes.\n' +
+      '  Recommended: use iTerm2 or another terminal emulator.\n\n',
+  );
+}
+
+// Load ESM main entry only after synchronous checks pass.
+// CJS can dynamic-import ESM in Node.js 12+. This is the only way to load
+// an ESM module from CJS — eslint-disable is intentional and required.
+// eslint-disable-next-line no-restricted-syntax
+import(new URL('../dist/node/bin.js', 'file://' + __filename)).catch(function (err) {
+  process.stderr.write((err && err.message ? err.message : String(err)) + '\n');
+  process.exit(1);
+});