@fateforge/archery-cli 1.0.4 → 1.0.5

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.5] - 2026-06-16
+
+### Added
+
+- **`--read-only` global switch (and `ARCHERY_CLI_READONLY` env var).** When set, every write command is refused at the shared write chokepoint with an `E_FORBIDDEN` envelope (exit 4) — before the dry-run preview or any network call. Read commands are unaffected. This lets an agent run safely against production with writes hard-disabled regardless of `--dry-run`/`--confirm`. `doctor` and `context` report the current read-only state.
+- **2FA detection + `--otp` (and `ARCHERY_CLI_OTP`).** Session login now understands Archery's two-factor flow. If an account has 2FA enabled, `/authenticate/` accepts the password but does not log in (it returns a `session_key` in `data` with no `sessionid` cookie); the CLI now detects this:
+  - With `--otp <6-digit code>` it completes the login via `POST /api/v1/user/2fa/` and caches the resulting session, so **subsequent commands need no OTP** until the session expires.
+  - Without an OTP it fails fast with the new **`E_2FA_REQUIRED`** code (exit 9, "human required") and a clear hint to retry with `--otp`, instead of the old opaque "session login failed".
+  - 2FA codes are ~30s-lived: generate the code immediately before running. The cached `sessionid` (keyring) is reused afterwards, so OTP is a one-time cost per session.
+
+### Changed
+
+- **`workflow detail` reworked to surface execution results.** Detail now reads the execution/review result rows from `/sqlworkflow/detail_content/` and exposes them as `result[]` (each row carries `stage`, `stageStatus`, `errLevel`, `error`, `affectedRows`, `executeTime`), plus the string `statusCode` (e.g. `workflow_exception`) backfilled from the workflow list. An agent can now see **why an execution failed** (e.g. `Invalid remote backup information`) straight from the CLI instead of opening the web UI. SQL content is reconstructed from the rows, with inception wrapper statements filtered out.
+- **Unified instance/group flags for `workflow submit` / `sqlcheck` / `auto-review`.** Session mode now also accepts the numeric `--instance` (ID) and `--group` (ID), resolving them to names via the instance/resource-group lists — the same flags JWT mode already used, so agents no longer have to remember a different flag set per transport. The name flags (`--instance-name` / `--group-name`) still work and win when both are given; an unknown ID fails with a clear `E_NOT_FOUND`.
+- **Skill schema-discovery guidance.** The Skill now steers agents to locate tables/columns by **meaning** via `dict tables` / `dict table-info` (which carry table and column comments) instead of `instance resource` / `instance describe` (bare names only), with an explicit "stop guessing, ask the user" rule when no matching column exists. Fixes all `dict` examples that omitted the required `--db-type`, which fail with `Instance.DoesNotExist` on Archery v1.8.5.
+
+### Notes
+
+- **DDL execution and backups.** Executing a DDL workflow with backup enabled needs Archery's backup feature configured (`enable_backup_switch` on and a reachable backup database). On environments without it, execution fails with `Invalid remote backup information` — this is an Archery configuration prerequisite, not a CLI bug. Either have a DBA configure the backup database, or submit with backup disabled (`--backup=false`).
+
 ## [1.0.4] - 2026-06-16
 
 ### Added

package/README.md

@@ -41,6 +41,10 @@ PowerShell uses `$env:NAME = "value"` for the same environment variables. Keep r
 
 **Dual-mode transport — usable by ordinary developer accounts.** By default the CLI logs in and talks to Archery over its **web session + AJAX endpoints** (`/authenticate/`, `/sqlworkflow_list/`, `/sqlquery/`, …). This path works on every Archery version and for plain accounts, where the `/api/v1` REST surface is typically closed (`403`) or simply not enabled. REST + JWT is kept as an opt-in advanced mode: pass `--mode jwt` or set `mode: jwt` on a region. Mode precedence is `--mode` flag → region config → `session` default. Verified live against `hhyo/archery:v1.8.5` with an ordinary account.
 
+**Read-only mode.** Pass `--read-only` (or set `ARCHERY_CLI_READONLY` to any non-empty value) to hard-disable every write command. Writes are refused at the shared chokepoint with an `E_FORBIDDEN` envelope (exit 4) before any network call, regardless of `--dry-run`/`--confirm`; read commands are unaffected. Use it to run safely against production. `doctor` and `context` report the active state.
+
+**Two-factor auth.** For accounts with 2FA enabled, supply a fresh 6-digit code with `--otp <code>` (or `ARCHERY_CLI_OTP`). The CLI detects when Archery requires a second factor and, without a code, fails fast with `E_2FA_REQUIRED` (exit 9) and a hint to retry with `--otp`. Codes are ~30s-lived, so generate one immediately before running; the resulting session is cached, so later commands need no OTP until it expires.
+
 Worst-case risk tier: **T2 high** - can execute and manage SQL workflows against configured database instances. See [SECURITY.md](SECURITY.md) and [.agent/SEC-SPEC.md](.agent/SEC-SPEC.md).
 
 ## Capabilities
@@ -86,6 +90,8 @@ Config location: `~/.archery-cli/config.json`.
 | `ARCHERY_CLI_USERNAME` | Username |
 | `ARCHERY_CLI_PASSWORD` | Password |
 | `ARCHERY_CLI_REGION` | Active region/profile |
+| `ARCHERY_CLI_READONLY` | Any non-empty value disables all write commands (same as `--read-only`) |
+| `ARCHERY_CLI_OTP` | 6-digit 2FA code for accounts with two-factor auth (same as `--otp`) |
 | `NO_COLOR` | Disable colored text output when text mode is explicitly requested |
 
 Saved credentials, when supported, are encrypted or stored in the OS credential store. Environment variables take precedence and are the preferred path for short-lived Agent sessions.

package/README_zh.md

@@ -41,6 +41,10 @@ PowerShell 使用 `$env:NAME = "value"` 设置同样的环境变量。真实密
 
 **双模传输 —— 普通开发者账号即可用。** CLI **默认走 Archery 网页端的 session + AJAX 端点**（`/authenticate/`、`/sqlworkflow_list/`、`/sqlquery/` 等）登录和请求。这条路径在所有 Archery 版本、对普通账号都可用；而 `/api/v1` REST 面通常对普通账号关闭（`403`）或根本未开启。REST + JWT 作为可选的高级模式保留：传 `--mode jwt` 或在 region 配置 `mode: jwt` 即可。模式优先级为 `--mode` 参数 → region 配置 → 默认 `session`。已在 `hhyo/archery:v1.8.5` 上用普通账号真机验证。
 
+**只读模式。** 传 `--read-only`（或将 `ARCHERY_CLI_READONLY` 设为任意非空值）即可硬禁用所有写命令。写命令会在统一入口处被拒，返回 `E_FORBIDDEN`（退出码 4），且发生在任何网络调用之前，不受 `--dry-run`/`--confirm` 影响；读命令不受影响。适合在生产环境安全运行。`doctor` 和 `context` 会显示当前是否只读。
+
+**二次验证（2FA）。** 对开启了 2FA 的账号，用 `--otp <验证码>`（或 `ARCHERY_CLI_OTP`）传入新鲜的 6 位验证码。CLI 会检测到 Archery 要求二次验证；若未提供验证码，会立即失败并返回 `E_2FA_REQUIRED`（退出码 9），提示用 `--otp` 重试。验证码有效期约 30 秒，请在运行前即时生成；验证成功后会话会被缓存，后续命令在会话过期前无需再次输入 OTP。
+
 最坏情况风险等级：**T2 高风险** - 可对已配置数据库实例执行和管理 SQL 工单。参见 [SECURITY.md](SECURITY.md) 和 [.agent/SEC-SPEC.md](.agent/SEC-SPEC.md)。
 
 ## 能力
@@ -86,6 +90,8 @@ README 只做地图，不做完整手册。Agent 在执行任务命令前，应
 | `ARCHERY_CLI_USERNAME` | 用户名 |
 | `ARCHERY_CLI_PASSWORD` | 密码 |
 | `ARCHERY_CLI_REGION` | 当前区域/profile |
+| `ARCHERY_CLI_READONLY` | 任意非空值即禁用所有写命令（等价于 `--read-only`） |
+| `ARCHERY_CLI_OTP` | 开启 2FA 账号的 6 位验证码（等价于 `--otp`） |
 | `NO_COLOR` | 显式使用 text 模式时禁用彩色输出 |
 
 支持保存凭据时，凭据会加密或进入 OS 凭据库。环境变量优先级更高，也是短生命周期 Agent 会话的推荐方式。

package/docs/LIVE-SMOKE-EVIDENCE.md

@@ -361,6 +361,37 @@ intermittently returned `用户名或密码错误`. Using `http://127.0.0.1:9123
 defect; the session login flow itself (GET csrf → POST authenticate → cookie)
 matches the verified curl flow byte-for-byte.
 
+## 2026-06-16 — 1.0.5 features (read-only, 2FA, param unification, detail rework)
+
+Verified against the same `tools-e2e-archery` container (`hhyo/archery:v1.8.5`,
+base `http://localhost:9123`) with the ordinary superuser account `cli_verify`,
+binary built from this working tree (`go build -o /tmp/a.exe ./cmd/archery-cli`),
+`ARCHERY_CLI_NO_KEYRING=1`.
+
+### Result by feature
+
+| Feature | Status | Evidence |
+|---------|--------|----------|
+| `--read-only` reflected in `doctor` | live (read) | PASS — `doctor` JSON shows `readOnly:true` and a `read-only` warn check; `auth` still `pass` (logged in to the real server). |
+| `--read-only` reflected in `context` | live (read) | PASS — `context.data.readOnly == true`. |
+| `--read-only` refuses a write | live | PASS — `workflow submit ... --read-only --dry-run` → `E_FORBIDDEN`, exit 4, before any network call. |
+| `ARCHERY_CLI_READONLY` env | live | PASS — read command (`workflow list`) succeeds under the env var; the env is a pure read-allow path. |
+| Param unification: `--instance`/`--group` IDs (session) | live | PASS — `workflow submit --instance 1 --group 1 --dry-run` preview resolves `instanceName:e2e-mysql`, `groupName:smoke-rg`; confirm submitted real workflow id 4. |
+| Unknown instance ID | live | PASS — `--instance 999` → `E_NOT_FOUND` (exit 3) with a clear "check 'instance list'" message. |
+| `workflow detail` result rework | live | PASS — `detail 4` returns `result[]` (real auto-review rejection "仅支持DML和DDL语句…") + `statusCode:workflow_autoreviewwrong` + numeric `status:3`. |
+| `--otp` harmless for non-2FA account | live | PASS — passing `--otp 000000` for `cli_verify` (no 2FA) does not break login; the OTP path only fires when the server signals 2FA. |
+| 2FA detection + `--otp` completion | **mock only** | The `cli_verify` account has **no 2FA enabled**, so the 2FA login branch cannot be exercised live. Covered by unit tests `TestEnsureSession_2FARequiredNoOTP` / `2FAWithOTPSucceeds` / `2FAWrongOTP` against an httptest server that mimics v1.8.5's `/authenticate/` (status 0 + `data` session_key, no sessionid) and `/api/v1/user/2fa/`. **Honest gap: the real `/api/v1/user/2fa/` round-trip is not live-verified.** |
+
+Test workflow id 4 was cancelled after verification (`workflow cancel 4`) to
+leave the container clean.
+
+### Honesty notes
+
+- **Race detector not run on this host:** `go test -race` needs cgo + gcc, which
+  are unavailable on the verifier machine. The non-race suite (`go test ./...`)
+  is fully green, and `golangci-lint run` reports 0 issues.
+- **2FA is mock-verified only** for the reason above.
+
 ## Reproduce
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fateforge/archery-cli",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Archery SQL audit CLI for AI Agents - manage SQL workflows, queries, instances, diagnostics, and data dictionaries with a machine-readable contract",
   "keywords": [
     "archery",
@@ -26,12 +26,12 @@
     "archery-cli": "scripts/run.js"
   },
   "optionalDependencies": {
-    "@fateforge/archery-cli-darwin-arm64": "1.0.4",
-    "@fateforge/archery-cli-darwin-x64": "1.0.4",
-    "@fateforge/archery-cli-linux-arm64": "1.0.4",
-    "@fateforge/archery-cli-linux-x64": "1.0.4",
-    "@fateforge/archery-cli-win32-arm64": "1.0.4",
-    "@fateforge/archery-cli-win32-x64": "1.0.4"
+    "@fateforge/archery-cli-darwin-arm64": "1.0.5",
+    "@fateforge/archery-cli-darwin-x64": "1.0.5",
+    "@fateforge/archery-cli-linux-arm64": "1.0.5",
+    "@fateforge/archery-cli-linux-x64": "1.0.5",
+    "@fateforge/archery-cli-win32-arm64": "1.0.5",
+    "@fateforge/archery-cli-win32-x64": "1.0.5"
   },
   "files": [
     "scripts/run.js",

package/skills/archery-cli/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: archery-cli
-version: "1.0.4"
+version: "1.0.5"
 description: "Archery SQL audit platform CLI for managing SQL workflows, queries, instances, diagnostics. Use when the user asks about SQL审核, database operations, Archery platform management, or needs to submit/review/execute SQL against database instances."
 license: MIT
 user-invocable: true
-metadata: {"requires":{"bins":["archery-cli"],"min_version":"1.0.4"}}
+metadata: {"requires":{"bins":["archery-cli"],"min_version":"1.0.5"}}
 ---
 
 # archery-cli
@@ -58,6 +58,10 @@ First-time setup: ask user for Archery URL + credentials, then run `archery-cli
 | Dangerous writes | If `reference` shows `requiresDangerous`, include `--dangerous` in both dry-run and confirm commands |
 | Discovery | `archery-cli reference` is the machine truth for params, `write`, `requiresConfirmation`, `requiresDangerous`, `riskLevel`, output schemas, and errors |
 | Transport | Defaults to **session** mode (Archery web AJAX endpoints) — works for ordinary accounts on all versions. REST + JWT is opt-in via `--mode jwt` or a region's `mode: jwt`. Precedence: `--mode` flag → region config → `session`. |
+| Read-only | Pass `--read-only` (or set `ARCHERY_CLI_READONLY`) to hard-disable all writes; they fail with `E_FORBIDDEN` (exit 4) before any network call. Use it when the task is read-only/analysis. |
+| 2FA | If a command fails with `E_2FA_REQUIRED` (exit 9), the account has 2FA on. Ask the user for a fresh 6-digit code and retry the **same** command with `--otp <code>` (codes last ~30s). The session is then cached, so later commands need no OTP. |
+| Instance/group IDs | `workflow submit/sqlcheck/auto-review` accept either `--instance`/`--group` (numeric IDs, resolved automatically) **or** `--instance-name`/`--group-name`. IDs work in both transport modes. |
+| Schema discovery | To locate a table/column by **meaning** (not its exact name), use `dict tables` → `{name, comment}` then `dict table-info` → per-column `column_comment`: those carry the human labels (e.g. `班级学生表`, `性别`). `instance resource`/`instance describe` return **bare names with no comments** — use them only when you already know the exact identifier. Already know the table name but not which instance holds it? `instance table-instances --table <name>`. `dict` needs `--instance <name>` (not ID) **and** `--db-type <mysql/...>` (db-type is required on v1.8.5; omitting it fails with `Instance.DoesNotExist`). |
 
 ## Trigger list
 
@@ -99,7 +103,8 @@ First-time setup: ask user for Archery URL + credentials, then run `archery-cli
 | Review slow queries | `archery-cli slowquery review --instance mydb --start "2024-01-01 00:00:00" --end "2024-01-31 23:59:59"` |
 | List processes | `archery-cli diagnostic process --instance mydb` |
 | List binlog files | `archery-cli binlog list --instance mydb` |
-| Browse tables | `archery-cli dict tables --instance mydb --db test` |
+| Find a table/column by meaning | `archery-cli dict tables --instance mydb --db test --db-type mysql` (scan `comment`), then `dict table-info ... --table t` (scan `column_comment`) |
+| Browse tables | `archery-cli dict tables --instance mydb --db test --db-type mysql` |
 | Test instance connectivity | `archery-cli instance test-instance --instance 1 --compact` |
 | Create a database on an instance | `archery-cli instance create-db --instance 1 --db reporting --owner alice --dangerous --dry-run`, then `--dangerous --confirm <token>` |
 | Create a database account | `archery-cli instance create-user --instance 1 --user app --host '%' --password '...' --dangerous --dry-run`, then `--dangerous --confirm <token>` |
@@ -177,6 +182,7 @@ Check `ok` first, then act on exit code:
 | 6 | `E_CONFLICT` | Stale or invalid token | Re-run `--dry-run`, get fresh token, retry |
 | 7 | `E_NETWORK`/`E_RATE_LIMIT`/`E_SERVER` | Transient error | Back off and retry |
 | 8 | `E_TIMEOUT` | Timeout | Back off and retry |
+| 9 | `E_2FA_REQUIRED` | Account needs a 2FA code | Ask user for a fresh 6-digit code, retry same command with `--otp <code>` (~30s validity) |
 
 ## Permission and security boundary declarations
 
@@ -218,8 +224,13 @@ archery-cli workflow detail 42
 # After approval, execute
 archery-cli workflow execute 42 --mode auto --dangerous --dry-run
 archery-cli workflow execute 42 --mode auto --dangerous --confirm ct_...
+
+# If execution fails, `workflow detail 42` now shows the reason in result[]:
+archery-cli workflow detail 42 --compact   # look at result[].error / statusCode
 ```
 
+**DDL execution + backups.** If a DDL execution fails with `result[].error = "Invalid remote backup information"`, the target Archery environment has not configured backups (no `enable_backup_switch` / no reachable backup database). This is an **Archery configuration prerequisite, not a CLI bug**. Either ask a DBA to configure the backup database, or submit the workflow with backup disabled (`--backup=false`). The cause is visible directly from `workflow detail` (as of 1.0.5), so check `result[]` before escalating.
+
 ### 2. Query a database and analyze results
 
 ```bash
@@ -269,23 +280,37 @@ archery-cli diagnostic kill --instance prod-mysql --threads "12345,12346" --dang
 
 ### 5. Browse data dictionary and table structure
 
+**Locating a table/column from a vague ask** (e.g. "how old is 张三") — the comment is your map, don't guess at names:
+
+```bash
+# 1. Scan table comments to find the table that matches the concept ("学生")
+archery-cli dict tables --instance prod-mysql --db mydb --db-type mysql --compact
+#    → [{"name":"students","comment":"班级学生表"}, ...]
+
+# 2. Scan column comments to map the concept to a column ("年龄")
+archery-cli dict table-info --instance prod-mysql --db mydb --db-type mysql --table students --compact
+#    → if no age/birthday column exists, STOP guessing — ask the user or derive it.
+```
+
+Prefer the two steps above over `instance resource` (bare names) and `instance describe` (no comments) whenever the user names a **concept**, not an exact identifier. `dict` requires `--db-type` on v1.8.5.
+
 ```bash
 # List all tables in a database
-archery-cli dict tables --instance prod-mysql --db mydb
+archery-cli dict tables --instance prod-mysql --db mydb --db-type mysql
 
-# Show table metadata and indexes
-archery-cli dict table-info --instance prod-mysql --db mydb --table orders
+# Show table metadata and indexes (includes column_comment)
+archery-cli dict table-info --instance prod-mysql --db mydb --db-type mysql --table orders
 
-# Describe table columns
+# Describe table columns (bare structure, no comments — use when the name is already known)
 archery-cli instance describe --instance prod-mysql --db mydb --table orders
 
 # List views, triggers, procedures
-archery-cli dict views --instance prod-mysql --db mydb
-archery-cli dict triggers --instance prod-mysql --db mydb
-archery-cli dict procedures --instance prod-mysql --db mydb
+archery-cli dict views --instance prod-mysql --db mydb --db-type mysql
+archery-cli dict triggers --instance prod-mysql --db mydb --db-type mysql
+archery-cli dict procedures --instance prod-mysql --db mydb --db-type mysql
 
 # Export data dictionary as HTML
-archery-cli dict export --instance prod-mysql --db mydb --format raw > dict.html
+archery-cli dict export --instance prod-mysql --db mydb --db-type mysql --format raw > dict.html
 ```
 
 ### 6. Binlog parsing and data recovery

package/skills/archery-cli/reference/workflow.md

@@ -46,11 +46,17 @@ archery-cli workflow sqlcheck --instance 1 --db mydb --sql "ALTER TABLE users AD
 |------|------|-------------|
 | `--fields` | string | Comma-separated output fields |
 
+`workflow detail` returns the execution/review result rows in `result[]` (each
+`{stage, stageStatus, errLevel, error, affectedRows, executeTime}`) plus the
+string `statusCode` (e.g. `workflow_exception`). When an execution failed, the
+reason is in `result[].error` — read it before escalating.
+
 ### `workflow sqlcheck` flags
 
 | Flag | Type | Required | Description |
 |------|------|----------|-------------|
-| `--instance` | int | yes | Target instance ID |
+| `--instance` | int | one of | Target instance ID (resolved to a name in session mode) |
+| `--instance-name` | string | one of | Target instance name (session mode; wins over `--instance`) |
 | `--db` | string | yes | Target database name |
 | `--sql` | string | yes | SQL to check |
 
@@ -71,13 +77,21 @@ archery-cli workflow submit --name "Add email index" --instance 1 --db mydb \
 | Flag | Type | Required | Default | Description |
 |------|------|----------|---------|-------------|
 | `--name` | string | yes | -- | Workflow title |
-| `--instance` | int | yes | -- | Target instance ID |
+| `--instance` | int | one of | -- | Target instance ID (resolved to a name in session mode) |
+| `--instance-name` | string | one of | -- | Target instance name (session mode; wins over `--instance`) |
 | `--db` | string | yes | -- | Target database name |
 | `--sql` | string | yes | -- | SQL content |
-| `--group` | int | no | (auto) | Resource group ID |
-| `--backup` | bool | no | true | Require backup before execution |
+| `--group` | int | one of | (auto) | Resource group ID (resolved to a name in session mode) |
+| `--group-name` | string | one of | -- | Resource group name (session mode; wins over `--group`) |
+| `--backup` | bool | no | true | Require backup before execution (needs Archery backups configured; see note below) |
 | `--demand-url` | string | no | -- | Related demand/requirement URL |
 
+> **Backup prerequisite:** with `--backup=true` (the default), DDL execution
+> needs Archery's backup feature configured (`enable_backup_switch` + a reachable
+> backup DB). Without it, execution fails with `Invalid remote backup
+> information` (visible in `workflow detail` → `result[].error`). Submit with
+> `--backup=false` to skip backups, or have a DBA configure the backup database.
+
 ### Audit (approve or reject) a workflow
 
 ```bash