@deveco-test/deveco-cli 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Huawei Device Co., Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# deveco-cli
+
+> HarmonyOS application development command line tool.
+
+`devecocli` is a unified CLI wrapper around the DevEco Studio toolchain — `ohpm`, `hvigor`, `hdc`, `emulator`, `hilog` — plus the HMOS skills installer, a project-scaffolding template, a local HarmonyOS documentation search service, and a bundled MCP server. Drive the full HarmonyOS workflow (create → build → install → run → log → install AI skills) from one binary, with no `PATH` / `DEVECO_SDK_HOME` / `JAVA_HOME` setup.
+
+## Quick Start
+
+**Prerequisites:** Node.js >= 20, DevEco Studio installed (Windows or macOS).
+
+> Not published yet — until then, build from source (see [Development](#development)) and run `node ./dist/cli.js`. After release, self-update via `devecocli update`.
+
+End-to-end on the command line:
+
+```bash
+devecocli create --app-name MyApp   # scaffold (default path: ./MyApp)
+cd MyApp
+devecocli build                                            # package .hap
+devecocli run                                              # install + launch
+devecocli log --level E                                    # tail logs
+```
+
+Run any command with `--help` for full options. Set `DEVECO_CLI_DEBUG=1` to print the raw underlying tool invocations.
+
+### Search offline documentation
+
+```bash
+devecocli doc search List                     # search by keyword
+devecocli doc search @State @Prop --limit 10  # multi-keyword OR search
+devecocli doc read harmonyos-guides/application-models/arkts-page-start-overview  # read a doc
+devecocli doc catalog                         # list all catalogs
+```
+
+### Drive devecocli from an AI agent (opencode example)
+
+Instead of typing the commands above by hand, let an agent (`opencode`, `claude`, `cursor`, …) drive `devecocli` for you. The flow below uses [opencode](https://opencode.ai/):
+
+1. **Teach the agent how `devecocli` works** — install the bundled `deveco-cli` skill into opencode:
+
+   ```bash
+   devecocli init --agent opencode
+   # writes the skill to ~/.config/opencode/skills/deveco-cli/
+   ```
+
+   (Run `devecocli init` with no flags to install into every detected agent at once.)
+
+2. **Enable syntax checking** — configure the `deveco-mcp` MCP server for your project:
+
+   ```bash
+   devecocli init --mcp --project ./MyApp
+   # writes MCP config to MyApp/.opencode/opencode.json, MyApp/.cursor/mcp.json, etc.
+   ```
+
+   The MCP server provides a unified `check` tool (auto-dispatches by file extension: `.ets` → ArkTS LSP, C/C++ → clangd) for syntax checking. Once configured, the AI agent will auto-spawn the MCP server when you open the project.
+
+3. **Open a project and start opencode**:
+
+   ```bash
+   cd MyApp        # any HarmonyOS project (with build-profile.json5 / oh-package.json5)
+   opencode
+   ```
+
+4. **Ask in natural language** — opencode auto-loads the `deveco-cli` skill and turns prompts like the following into the right `devecocli` invocations:
+
+   - `Scaffold a new HarmonyOS app called Demo at ./Demo and build it`
+   - `Build this project in release mode and run it on my emulator`
+   - `Tail the last error logs from this app`
+   - `Check for syntax errors in src/main/ets/pages/Index.ets`
+
+If the agent doesn't pick up the skill automatically, prompt it explicitly: *"Use the `deveco-cli` skill."*
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `devecocli create` | Scaffold a new HarmonyOS application project from the bundled template |
+| `devecocli build` | Build / package a project or modules into `.hap` / `.hsp` / `.har` / `.app`; `build clean` removes build outputs |
+| `devecocli run` | Install (with HSP deps) and launch on a device / emulator; `--skip-build` deploys existing artifacts |
+| `devecocli device` | List / inspect connected devices and emulators |
+| `devecocli emulator` | Manage local emulators: list / start / stop / create / delete, system images (`image download|remove|list`), and license helpers (`license view` / `license accept`) |
+| `devecocli log` | Fetch hilog or crash logs (with level / bundle / keyword / from/to / tail / follow filters) |
+| `devecocli doc` | Search and read HarmonyOS documentation from a local docs directory |
+| `devecocli init` | Install the bundled `deveco-cli` skill into AI agents; `--mcp` configures the `deveco-mcp` MCP server for ArkTS `.ets` and C/C++ syntax checking |
+| `devecocli skills` | List / find / add / remove HMOS skills for AI agents and projects |
+| `devecocli serve mcp` | Host the bundled MCP (Model Context Protocol) server over stdio so AI clients (Trae / Claude / …) can call its unified `check` tool for ArkTS `.ets` and C/C++ syntax checking |
+| `devecocli update` | Update the CLI itself (`npm install -g deveco-cli@latest`) |
+
+Run `devecocli <cmd> --help` for full options, or see [`SKILL.md`](./SKILL.md) for the detailed reference (also consumed by AI agents).
+
+Cross-platform: works on **Windows** and **macOS**; Linux is not yet supported (DevEco Studio's bundled toolchain isn't officially distributed for Linux).
+
+## Development
+
+```bash
+npm install
+npm run dev                  # Watch mode
+npm start -- <command>       # tsx (no build step)
+npm run lint                 # add :fix to autofix
+npm run format
+npm run build                # tsup → dist/cli.js
+```
+
+See [`AGENTS.md`](./AGENTS.md) for the architecture overview.
+
+## License
+
+[MIT](./LICENSE)

package/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: deveco-cli
+description: >-
+  Use 'devecocli' to scaffold, build, run, and debug HarmonyOS apps — managing
+  devices, emulators, hilog/log, and HMOS/HarmonyOS skills. Use when the workspace has
+  build-profile.json5 or oh-package.json5, or the user mentions HarmonyOS/鸿蒙,
+  DevEco, ArkTS, ArkUI, or HMOS/HarmonyOS skills.
+---
+
+# DevEco CLI
+
+`devecocli` wraps DevEco Studio's `hvigor`, `ohpm`, `hdc`, emulator toolchain, and HMOS-skills installer. **Prefer `devecocli` over invoking underlying tools directly.**
+
+Available commands: `build`, `run`, `update`, `device`, `emulator`, `skills`, `log`, `create`, `init`, `serve`, `doc`.
+
+**Sandbox Rule**: Commands tagged `[Outside sandbox]` must be run outside the sandbox.
+
+## 1. Code → Build → Deploy → Run → Debug
+
+### `devecocli create`
+Scaffold a new HarmonyOS project.
+- `--app-name <name>` (Req): 1–200 chars, `^[a-zA-Z][a-zA-Z0-9_]*$`
+- `--project-path <path>`: Auto-created if omitted (`./<app-name>`). Must be empty if exists.
+- `--bundle-name <bundle>`: Default `com.example.<appname-lowercase>`. 7–128 chars, ≥3 segments.
+- `--api-level <level>`: int ≥17 (default: auto or 23).
+*Ex*: `devecocli create --app-name MyApp --project-path ./CustomDir --api-level 23`
+
+### `devecocli build` `[Outside sandbox]`
+Compile and package project/modules. (Defaults: `--product default`, `--build-mode debug`)
+| Goal | Command |
+|---|---|
+| Single-module / single-`entry` | `devecocli build` |
+| Specific modules | `devecocli build --modules <m1> <m2>@<target>` |
+| Whole product bundle (.app) | `devecocli build --product <name>` |
+| Clean build outputs | `devecocli build clean` |
+
+### `devecocli emulator`
+Manage local emulator instances and system images.
+- `list`: Show instances (status, serial, device type).
+- `start <names...>`: Start instances. Quote names with spaces. (See Troubleshooting if blocked).
+- `stop <names...>`: Stop by name or serial (`127.0.0.1:<port>`).
+- `create <name>` (Req: `--device-type`, `--os-version`): Create instance. Optional: `--force`.
+- `delete <name>`: Delete instance.
+- `image list`: List downloaded images. Opts: `--device-type <type>`, `--all`, `--format <table|json>`.
+- `image download` / `image remove` (Req: `--device-type`, `--os-version`): Download/remove image. (Takes 30+ min, set long timeout).
+*Device types*: `phone`, `foldable`, `widefold`, `triplefold`, `tablet`, `2in1`, `2in1 foldable`, `wearable`, `tv`.
+
+### `devecocli doc`
+Search/read local HarmonyOS docs.
+- `search <keywords...>`: Match any keyword. Opts: `--catalog <name>`, `--format <default|json>`, `--limit <n>`.
+- `read <documentId>`: Read full content by ID.
+- `catalog`: List available catalogs.
+
+### `devecocli device`
+- `list`: Show active real devices and running emulators.
+- `view`: Detailed info. Req `-t <name|serial>` on multi-device hosts.
+
+### `devecocli run` `[Outside sandbox]`
+Build, install, and launch.
+- `--module <module>`: Target module (auto-selected if only one runnable).
+- `--device <name|serial>`: Target device (Req if multiple connected).
+- `--product <product>` / `--build-mode <mode>`: Defaults: `default` / `debug`.
+- `--ability <ability>`: Default from `module.json5`.
+- `--uninstall`: Uninstall existing app first (Fixes signing key issues).
+- `--skip-build`: Deploy existing artifacts.
+
+### `devecocli log`
+Fetch hilog or crash logs. Req `--device <name|serial>` on multi-device hosts.
+- `--crash`: Dump crash logs.
+- `--level D|I|W|E|F`: Filter by level.
+- `--bundle-name` / `--keyword`: Filter output.
+- `--from <start>` / `--to <end>`: Relative offsets (`30s`, `5m`).
+- `--tail <num>` / `--follow`: Keep last N lines / stream real-time (no `--to`).
+*Ex*: `devecocli log --crash --bundle-name com.example.app`, `devecocli log --level E --from 5m --tail 200`
+
+## 2. Setup
+
+### `devecocli init`
+MUTUALLY EXCLUSIVE modes for setup:
+1. `--skill` (Default): Install `deveco-cli` skill to AI agents.
+2. `--mcp`: Configure `deveco-mcp` server (ArkTS/C++ syntax checking).
+*Options*:
+- `--agent <agents>`: Comma-separated (e.g. `opencode,cursor`). Omitting targets all.
+- `--project <path>`: Project-level config (Abs path for MCP).
+- `--path <path>`: Direct skill install path.
+- `-f, --force`: Overwrite existing config.
+*MCP Rules*: Global MCP (no `--project`) only supports `opencode` and `cursor`. Others require `--project`.
+
+### `devecocli skills`
+Manage HMOS skills in AI agents/projects.
+- `list [-l|--long]` / `find <keyword>`: List or search skills.
+- `add (--all | --skill <name>) [--agent <a,b…>] [--project <path>] [--path <path>] [-f]`: Install.
+- `remove --skill <name> [...]`: Uninstall.
+
+## 3. Maintenance
+
+- **`devecocli update`** `[Outside sandbox]`: Update CLI to latest version.
+- **`devecocli serve mcp`**: Host stdio MCP server (`check` tool for `.ets`/C/C++). Used via `init --mcp`. (Env: `PROJECT_PATH`, `DEVECO_PATH`, `NODE_MAX_OLD_SPACE_SIZE`, `DEBUG=1`).
+
+## Recipes
+
+- **Fresh checkout to emulator**:
+  `devecocli build` -> `devecocli emulator list` -> `devecocli emulator start "Name"` -> `devecocli run`
+- **Diagnose crash**:
+  `devecocli log --crash --bundle-name <bundle>`
+- **Release build**:
+  `devecocli build --product oversea --build-mode release`
+
+## Troubleshooting
+
+- **"Product / Build mode `<x>` not found"**: Check `build-profile.json5`.
+- **"Multiple entry modules" / "No entry module"**: Pass `--modules` (build) or `--module` (run).
+- **"No active devices" / "Multiple devices connected"**: Connect/start emulator. Pass `-t <serial>` (device view) or `--device <name|serial>` (run/log).
+- **`error:install sign info inconsistent`**: Signing key changed. Run `devecocli run --uninstall`.
+- **`skills add` agent not found**: Valid: `codebuddy`, `cursor`, `opencode`, `qoder`, `trae-cn`.
+- **`emulator start` / `image download` blocked on agreement**: User MUST run `devecocli emulator license accept` in interactive TTY. Agents cannot do this. Do not retry until accepted.
+- **`image download` failure / timeout**: Do NOT auto-retry. Give the command to the user to run manually in their terminal.
+- **`emulator create` timeout**: Treat as user-action step. Ask user to open DevEco Studio -> Device Manager. Check `emulator list` after user confirms. Do NOT auto-retry or edit SDK files.
+- **`image list` duplicate OS rows**: `phone`/`foldable`/`widefold`/`triplefold` share the same image. Download/remove ONCE per OS version.