@fateforge/archery-cli 1.0.9 → 1.0.10

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.10] - 2026-06-20
+
+### Fixed
+
+- **`instance list` (`--mode jwt`) now returns every instance, not just the first page.** The REST path (`listInstancesREST`) built the request as DRF *LimitOffset* (`?limit=&offset=&search=`) and read only `next != null` as `has_more` while discarding the `next` link, so it could never page past the first result set and silently ignored `--limit` / `--offset` / `--search`. But Archery's REST API is configured as `PageNumberPagination` (param `page`, `PAGE_SIZE` 5 upstream) with `DjangoFilterBackend` only (no `SearchFilter`) — so against more than 5 instances everything past page 1 was unreachable, which also broke any flow that discovers an instance ID before calling `instance resource` / `dict` / etc. The CLI now paginates via `page`, stops when the contract's `next` is null, filters `--search` client-side (DRF exposes no name-search param), and applies `--limit` / `--offset` client-side — mirroring the existing non-DBA session fallback `listUserAllInstancesSession`. When `--search` is unused the server's `count` is used as the true total (early-stopping once the requested window is filled); when it is used the matched count is the total. A page-walk safety cap guards against a misbehaving paginator. Session mode (the default) was never affected — it uses the Django AJAX `POST /instance/list/`, which genuinely honors `limit`/`offset`. Reproduced and verified live against `hhyo/archery:v1.8.5` in `--mode jwt` (8 instances across 2 pages: full enumeration, client-side `--limit`/`--offset` window, and cross-page `--search` all correct). Fixes #12.
+
 ## [1.0.9] - 2026-06-17
 
 ### Fixed

package/README.md

@@ -1,11 +1,25 @@
-# archery-cli
+<h1 align="center">archery-cli</h1>
 
-[English](README.md) | [中文](README_zh.md)
+<p align="center">
+  <strong>Agent-native Archery SQL audit CLI &middot; JSON-first &middot; dry-run guarded</strong>
+</p>
 
-[![CI](https://github.com/fatecannotbealtered/archery-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/fatecannotbealtered/archery-cli/actions/workflows/ci.yml)
-[![Go Report Card](https://goreportcard.com/badge/github.com/fatecannotbealtered/archery-cli)](https://goreportcard.com/report/github.com/fatecannotbealtered/archery-cli)
-[![npm version](https://img.shields.io/npm/v/@fateforge/archery-cli.svg)](https://www.npmjs.com/package/@fateforge/archery-cli)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+<p align="center">
+  <a href="README.md">English</a> &middot; <a href="README_zh.md">中文</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/fatecannotbealtered/archery-cli/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/fatecannotbealtered/archery-cli/ci.yml?branch=main&style=for-the-badge&logo=githubactions&logoColor=white&label=CI"></a>
+  <a href="https://goreportcard.com/report/github.com/fatecannotbealtered/archery-cli"><img alt="Go Report" src="https://img.shields.io/badge/Go%20Report-checked-00ADD8?style=for-the-badge&logo=go&logoColor=white"></a>
+  <a href="https://www.npmjs.com/package/@fateforge/archery-cli"><img alt="npm" src="https://img.shields.io/npm/v/@fateforge/archery-cli?style=for-the-badge&logo=npm&logoColor=white&label=npm&color=CB3837"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-7C3AED?style=for-the-badge"></a>
+</p>
+
+<p align="center">
+  <img alt="Agent native" src="https://img.shields.io/badge/agent-native-111827?style=for-the-badge">
+  <img alt="JSON first" src="https://img.shields.io/badge/output-JSON--first-0891B2?style=for-the-badge">
+  <img alt="Dry-run guarded" src="https://img.shields.io/badge/writes-dry--run%20guarded-F59E0B?style=for-the-badge">
+</p>
 
 > Agent-native CLI for the Archery SQL audit platform. It gives AI Agents deterministic control over SQL workflows, queries, instances, diagnostics, binlog, archive jobs, and data dictionaries.
 
@@ -14,8 +28,9 @@
 Paste this block into the AI Agent that will operate Archery SQL audit. It installs the CLI and bundled Skill, provides the minimum runtime context, and runs the self-description preflight.
 
 ```bash
-# Install CLI and Agent Skill.
+# Install the CLI (global npm).
 npm install -g @fateforge/archery-cli
+# Install the Agent Skill — copies into your agent-supported skills directory.
 npx skills add fatecannotbealtered/archery-cli -y -g
 
 # Provide runtime context. Replace placeholders in the local shell/secret manager.

package/README_zh.md

@@ -1,11 +1,25 @@
-# archery-cli
+<h1 align="center">archery-cli</h1>
 
-[English](README.md) | [中文](README_zh.md)
+<p align="center">
+  <strong>面向 AI Agent 的 Archery SQL 审核 CLI &middot; JSON 优先 &middot; dry-run 防护</strong>
+</p>
 
-[![CI](https://github.com/fatecannotbealtered/archery-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/fatecannotbealtered/archery-cli/actions/workflows/ci.yml)
-[![Go Report Card](https://goreportcard.com/badge/github.com/fatecannotbealtered/archery-cli)](https://goreportcard.com/report/github.com/fatecannotbealtered/archery-cli)
-[![npm version](https://img.shields.io/npm/v/@fateforge/archery-cli.svg)](https://www.npmjs.com/package/@fateforge/archery-cli)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+<p align="center">
+  <a href="README.md">English</a> &middot; <a href="README_zh.md">中文</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/fatecannotbealtered/archery-cli/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/fatecannotbealtered/archery-cli/ci.yml?branch=main&style=for-the-badge&logo=githubactions&logoColor=white&label=CI"></a>
+  <a href="https://goreportcard.com/report/github.com/fatecannotbealtered/archery-cli"><img alt="Go Report" src="https://img.shields.io/badge/Go%20Report-checked-00ADD8?style=for-the-badge&logo=go&logoColor=white"></a>
+  <a href="https://www.npmjs.com/package/@fateforge/archery-cli"><img alt="npm" src="https://img.shields.io/npm/v/@fateforge/archery-cli?style=for-the-badge&logo=npm&logoColor=white&label=npm&color=CB3837"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-7C3AED?style=for-the-badge"></a>
+</p>
+
+<p align="center">
+  <img alt="Agent native" src="https://img.shields.io/badge/agent-native-111827?style=for-the-badge">
+  <img alt="JSON first" src="https://img.shields.io/badge/output-JSON--first-0891B2?style=for-the-badge">
+  <img alt="Dry-run guarded" src="https://img.shields.io/badge/writes-dry--run%20guarded-F59E0B?style=for-the-badge">
+</p>
 
 > 面向 AI Agent 的 Archery SQL 审核 CLI。它让 Agent 能以确定性的机器契约操作 SQL 工单、查询、实例、诊断、binlog、归档任务和数据字典。
 
@@ -14,8 +28,9 @@
 把下面整段交给负责操作 Archery SQL 审核平台 的 AI Agent。它会安装 CLI 和内置 Skill，提供最小运行上下文，并执行自描述预检。
 
 ```bash
-# 安装 CLI 和 Agent Skill。
+# 安装 CLI（全局 npm）。
 npm install -g @fateforge/archery-cli
+# 安装 Agent Skill —— 复制到你 agent 支持的 skills 目录。
 npx skills add fatecannotbealtered/archery-cli -y -g
 
 # 提供运行上下文。把占位符替换为本地 shell/密钥管理器里的值。

package/docs/LIVE-SMOKE-EVIDENCE.md

@@ -432,6 +432,38 @@ leave the container clean.
   is fully green, and `golangci-lint run` reports 0 issues.
 - **2FA is mock-verified only** for the reason above.
 
+## 2026-06-20 — 1.0.10 `instance list` REST/JWT pagination (issue #12)
+
+Live verification of the `instance list` pagination fix against the running
+`tools-e2e-archery` (`hhyo/archery:v1.8.5`) on `localhost:9123`, **`--mode jwt`**,
+superuser `cli_verify` (added to the `api_user_whitelist` SysConfig). The fleet
+was seeded to **8 instances** so it spans more than one REST page (upstream
+`PAGE_SIZE` 5 → 2 pages), then cleaned back down afterward.
+
+### Result by scenario
+
+| Scenario | Command | Status | Result |
+|---|---|---|---|
+| Full enumeration | `instance list --limit 20` | **live PASS** | all 8 returned (`count:8, total:8, has_more:false`); pre-fix returned only 5 |
+| Client-side window | `instance list --limit 3 --offset 2` | **live PASS** | ids 3,4,5; `total:8`; `has_more:true` |
+| Cross-page search | `instance list --search page-test` | **live PASS** | 6 matches (ids 3–8 span both pages); `total:6` |
+| Exact search | `instance list --search page-test-mysql-5` | **live PASS** | exactly id 7; `total:1` |
+| Server-side filter | `instance list --db-type redis` | **live PASS** | id 2 only; `--db-type` still filtered upstream |
+
+Raw `GET /api/v1/instance/?page=1` confirmed the contract: `PageNumberPagination`
+envelope `{count:8, next:"…?page=2", previous:null, results:[…]}` with `id` as a
+bare JSON number (coerced to string by `instanceResult.UnmarshalJSON`).
+
+### 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, `go vet ./...` is clean, and `golangci-lint run` reports 0
+  issues. CI runs `-race` on Linux.
+- The new mock-contract test (`TestListInstancesREST_PageNumberPagination`)
+  encodes the real `PageNumberPagination` semantics observed above (page walk,
+  null `next` terminator, numeric `id`, no server-side search/limit/offset).
+
 ## Reproduce
 
 ```bash

package/package.json

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

package/skills/archery-cli/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: archery-cli
-version: "1.0.9"
+version: "1.0.10"
 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.9"}}
+metadata: {"requires":{"bins":["archery-cli"],"min_version":"1.0.10"}}
 ---
 
 # archery-cli

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

@@ -224,3 +224,4 @@ archery-cli instance describe --instance prod-mysql --db mydb --table orders
 - `instance users` lists database-level users, not Archery platform users
 - `instance table-instances` searches across all registered instances for a given table name
 - JSON output IDs are strings per the CLI contract, even when input flags accept numeric IDs; all instance names are strings
+- `instance list` behaves the same in both transports. In `--mode jwt` the REST API paginates server-side in small pages (Archery's `PageNumberPagination`) and has no name search, so the CLI walks all pages and applies `--search` / `--limit` / `--offset` client-side; `--db-type` is filtered server-side. For a very large fleet, prefer `--db-type` (and `--search`) to narrow results.