@amaster.ai/runtime-cli 1.1.0-beta.71 → 1.1.0-beta.73

package/dist/skill/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: amaster-runtime-cli
+description: Use this skill when you need to operate or integrate the `@amaster.ai/runtime-cli` (`amaster`) CLI in this repository, especially for non-interactive app initialization, authentication, entity CRUD, BPM, workflow execution, S3 listing/upload, and OpenClaw bootstrap. Prefer the current source code over the README when they differ.
+---
+
+# Amaster Runtime CLI
+
+This skill is for AI agents that need to run or explain the `amaster` CLI from `packages/runtime-cli`.
+
+## Source Of Truth
+
+- Primary source: `packages/runtime-cli/src/cli.ts`
+- Supporting behavior: `packages/runtime-cli/src/commands/*.ts` and `packages/runtime-cli/src/config.ts`
+- The README documents the product intent, but it is currently ahead of the registered CLI surface in several places. When the README and source disagree, follow the source.
+
+## Preferred Invocation
+
+Inside this monorepo, prefer a built local binary instead of assuming a global install:
+
+```bash
+pnpm --filter @amaster.ai/runtime-cli run build
+node packages/runtime-cli/dist/cli.js <command> [options]
+```
+
+If the package is already installed globally, `amaster ...` is fine. For one-off usage outside the repo, `npx @amaster.ai/runtime-cli ...` is acceptable.
+
+## Non-Interactive Rules
+
+- Always prefer explicit flags over prompts.
+- Pass `--app <app-code>` on commands that support it, unless you have already set a default app with `amaster use <app-code>`.
+- For `login`, always pass `--email` and `--password` in automation.
+- For `entity create`, `entity update`, `bpm start`, `bpm complete`, and `workflow execute`, always pass valid JSON strings with shell-safe quoting.
+- For machine-oriented usage, disable color if needed:
+
+```bash
+FORCE_COLOR=0 node packages/runtime-cli/dist/cli.js ...
+```
+
+- Expect non-zero exit codes on validation or API failures; several commands call `process.exit(1)` directly.
+
+## Actual Registered Commands
+
+These commands are registered in `src/cli.ts` today.
+
+### App Selection And Bootstrap
+
+```bash
+amaster apps
+amaster use <app-code>
+amaster init --app-code <code> --url <url> [--api-key <key>] [--oss-endpoint <endpoint>]
+```
+
+Command semantics:
+
+- `apps`: list locally configured apps from `~/.amaster/config.json`, mark the current app, and show whether each app has a valid auth session.
+- `use <app-code>`: set the default app for later commands that omit `--app`.
+- `init`: bootstrap one app into local config and OpenClaw.
+
+Important details:
+
+- `init` requires both `--app-code` and `--url`.
+- `--url` is the app base URL used for all later API calls.
+- `init` checks for `~/.openclaw`. If OpenClaw is not installed, initialization fails.
+- `init` saves app config, downloads app-specific skills, and merges MCP servers into OpenClaw config.
+- `init` is not just metadata setup. It mutates `~/.amaster` and `~/.openclaw`.
+
+Minimal examples:
+
+```bash
+node packages/runtime-cli/dist/cli.js apps
+node packages/runtime-cli/dist/cli.js init --app-code myapp --url https://myapp.example.com
+node packages/runtime-cli/dist/cli.js use myapp
+```
+
+### Authentication
+
+```bash
+amaster login [--app <app-code>] [--email <email>] [--password <password>]
+amaster logout [--app <app-code>]
+amaster whoami [--app <app-code>]
+```
+
+Command semantics:
+
+- `login`: authenticate against the selected app and write `~/.amaster/auth-<appCode>.json`.
+- `logout`: clear the local auth session and best-effort notify the remote auth service.
+- `whoami`: fetch the current authenticated user profile through the SDK client.
+
+Important details:
+
+- If `--app` is omitted, the CLI resolves the current app from local config.
+- `login` will prompt interactively if `--email` or `--password` is missing. Avoid that in automation.
+- `whoami` requires both a configured app and a valid access token.
+
+Minimal examples:
+
+```bash
+node packages/runtime-cli/dist/cli.js login --app myapp --email user@example.com --password 'secret'
+node packages/runtime-cli/dist/cli.js whoami --app myapp
+node packages/runtime-cli/dist/cli.js logout --app myapp
+```
+
+### Entity
+
+```bash
+amaster entity list <namespace> <entity> [--app <app-code>] [--page <n>] [--page-size <n>]
+amaster entity get <namespace> <entity> <id> [--app <app-code>]
+amaster entity create <namespace> <entity> [--app <app-code>] --data '<json>'
+amaster entity update <namespace> <entity> <id> [--app <app-code>] --data '<json>'
+amaster entity delete <namespace> <entity> <id> [--app <app-code>]
+```
+
+Note:
+
+- The first positional argument is `namespace`, not `app-code`. Select the app with `--app <app-code>` or `amaster use <app-code>`.
+
+Command semantics:
+
+- `list`: paginated list query for one entity type under one namespace.
+- `get`: fetch one entity record by ID.
+- `create`: create one entity record from a JSON object.
+- `update`: update one entity record by ID with a JSON object.
+- `delete`: delete one entity record by ID.
+
+Important details:
+
+- `namespace` is a logical data namespace such as `default`; it is not the same as app selection.
+- `entity` is the entity code or collection name.
+- `--data` must be valid JSON. Invalid JSON throws before the API call completes.
+- `list` output is human-oriented and truncated to a subset of fields. Use `get` or the SDK if you need full structured output.
+
+Minimal examples:
+
+```bash
+node packages/runtime-cli/dist/cli.js entity list default users --app myapp --page 1 --page-size 20
+node packages/runtime-cli/dist/cli.js entity get default users 123 --app myapp
+node packages/runtime-cli/dist/cli.js entity create default users --app myapp --data '{"name":"Ada","email":"ada@example.com"}'
+node packages/runtime-cli/dist/cli.js entity update default users 123 --app myapp --data '{"name":"Ada Lovelace"}'
+node packages/runtime-cli/dist/cli.js entity delete default users 123 --app myapp
+```
+
+### BPM
+
+```bash
+amaster bpm processes [--app <app-code>]
+amaster bpm start <key> [--app <app-code>] [--variables '<json>']
+amaster bpm tasks [--app <app-code>] [--assignee <uid>]
+amaster bpm complete <id> [--app <app-code>] [--variables '<json>']
+```
+
+Command semantics:
+
+- `processes`: list process definitions available in the selected app.
+- `start <key>`: start one process instance by process definition key.
+- `tasks`: list current tasks, optionally filtered by assignee.
+- `complete <id>`: complete one task with optional process variables.
+
+Important details:
+
+- `start` expects `key` to be the BPM process definition key, not an instance ID.
+- `complete` expects a task ID, not a process instance ID.
+- `--variables` must be a JSON object.
+
+Minimal examples:
+
+```bash
+node packages/runtime-cli/dist/cli.js bpm processes --app myapp
+node packages/runtime-cli/dist/cli.js bpm start order-approval --app myapp --variables '{"orderId":"123"}'
+node packages/runtime-cli/dist/cli.js bpm tasks --app myapp --assignee u_001
+node packages/runtime-cli/dist/cli.js bpm complete task_123 --app myapp --variables '{"approved":true}'
+```
+
+### Workflow
+
+```bash
+amaster workflow list [--app <app-code>]
+amaster workflow execute <id> [--app <app-code>] [--input '<json>']
+```
+
+Command semantics:
+
+- `list`: list workflow definitions visible to the selected app.
+- `execute <id>`: run one workflow by workflow ID and print the execution result.
+
+Important details:
+
+- `execute` expects a workflow ID as wired by the backend client.
+- `--input` must be valid JSON and defaults to `{}` when omitted.
+
+Minimal examples:
+
+```bash
+node packages/runtime-cli/dist/cli.js workflow list --app myapp
+node packages/runtime-cli/dist/cli.js workflow execute wf_123 --app myapp --input '{"documentId":"abc"}'
+```
+
+### S3
+
+```bash
+amaster s3 list [--app <app-code>] [--bucket <bucket>]
+amaster s3 upload <file> [--app <app-code>] [--bucket <bucket>] [--key <object-key>]
+```
+
+Command semantics:
+
+- `list`: list files in S3-like storage, optionally constrained to one bucket.
+- `upload <file>`: upload one local file and optionally override bucket and object key.
+
+Important details:
+
+- `upload` resolves `<file>` against the current working directory and fails fast if the file does not exist.
+- `list` prints human-readable rows with key, size, and modification time.
+- `upload` prints uploaded key, URL, and bucket.
+
+Minimal examples:
+
+```bash
+node packages/runtime-cli/dist/cli.js s3 list --app myapp --bucket docs
+node packages/runtime-cli/dist/cli.js s3 upload ./report.pdf --app myapp --bucket docs --key reports/2026-03/report.pdf
+```
+
+## Important README Mismatches
+
+Do not assume the following README-documented commands are available unless `src/cli.ts` is updated to register them:
+
+- `amaster config ...`
+- `amaster register ...`
+- `amaster users ...`
+- `amaster doctor`
+- `amaster list`
+- `amaster switch ...`
+- `amaster uninstall ...`
+- `amaster init --force`
+- `amaster entity types ...`
+- `amaster bpm claim ...`
+- `amaster bpm instances`
+- `amaster bpm instance <id>`
+- `amaster workflow get <id>`
+- `amaster workflow executions ...`
+- `amaster workflow execution <id>`
+- `amaster s3 download ...`
+- `amaster s3 delete ...`
+- `amaster s3 url ...`
+
+Some of these behaviors exist as helper functions in command modules, but they are not currently wired into the public CLI.
+
+The README also uses some outdated file names and examples. The source currently writes `~/.amaster/config.json`, not `~/.amaster/cli-config.json`.
+
+## Runtime State And File Locations
+
+Current source uses these paths:
+
+- App config: `~/.amaster/config.json`
+- Per-app auth session: `~/.amaster/auth-<appCode>.json`
+- OpenClaw config: `~/.openclaw/config.json`
+- Installed OpenClaw skills: `~/.openclaw/skills/<appCode>/`
+
+During `init`, the CLI fetches app resources from OSS:
+
+- Skills manifest: `/openclaw/apps/<appCode>/skills/manifest.json`
+- MCP config: `/openclaw/apps/<appCode>/mcp-config.yaml`
+- Default OSS endpoint: `https://amaster.oss-cn-hangzhou.aliyuncs.com`
+
+## Recommended Agent Workflow
+
+1. Build the package if you are operating from source.
+2. Run `amaster init --app-code <code> --url <url>` for first-time app setup.
+3. Run `amaster login --app <code> --email ... --password ...`.
+4. Set a default app with `amaster use <code>` if you will make multiple calls.
+5. Use explicit JSON flags for create, update, start, complete, and execute operations.
+6. Prefer list or get operations before destructive changes.
+
+## When To Use The SDK Instead
+
+Prefer calling `@amaster.ai/client` directly when:
+
+- You need stable structured data instead of human-formatted terminal output.
+- You need command coverage that the CLI has not registered yet.
+- You want richer retries, error handling, or composition inside a larger program.
+
+## Interpretation Guidance For Agents
+
+- Treat this skill as an execution guide, not as proof that every README example is valid.
+- Prefer the command signatures in this file over README prose.
+- Before destructive operations such as `entity delete`, confirm the target exists with `get` or `list` unless the user explicitly asked for blind deletion.
+- If you need structured machine-readable results, switch to `@amaster.ai/client` instead of scraping terminal output.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/runtime-cli",
-  "version": "1.1.0-beta.71",
+  "version": "1.1.0-beta.73",
   "description": "CLI for Amaster SDK - Multi-app support for OpenClaw",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -39,7 +39,7 @@
     "ora": "^8.0.1",
     "yaml": "^2.3.4",
     "inquirer": "^9.2.12",
-    "@amaster.ai/client": "1.1.0-beta.71"
+    "@amaster.ai/client": "1.1.0-beta.73"
   },
   "devDependencies": {
     "@types/inquirer": "^9.0.7",
@@ -55,6 +55,7 @@
   },
   "scripts": {
     "build": "tsup",
+    "postbuild": "node scripts/copy-skill.mjs",
     "dev": "tsup --watch",
     "clean": "rm -rf dist *.tsbuildinfo",
     "type-check": "tsc --noEmit",