Merge pull request #2 from yuque/harness/agent-harness

Agent harness: doc map, contract locks, toolchain hardening, spec-gap flags

Author: chen201724

.prettierignore

@@ -0,0 +1 @@
+src/client/types.gen.ts

AGENTS.md

@@ -17,24 +17,73 @@ bin.ts → cli.ts (commander program, error → exit code)
                        └── client/http.ts    (auth header, retry/backoff, YuqueError)
 ```
 
-- Command surface is **locked 1:1 against `spec/yuque-openapi.yaml`** by
-  `tests/spec-coverage.test.ts`. Adding/renaming a command or refreshing the spec means
-  updating that table deliberately.
-- Both READMEs are locked by `tests/docs/command-surface-docs.test.ts` (exact command
-  count in the heading, every command mentioned). Keep README.md and README.zh-CN.md
-  strictly isomorphic.
-- Exit codes are a stable contract: 0 ok · 1 API/unknown · 2 usage · 3 auth · 4 not
-  found · 5 rate limited (`src/errors.ts`).
-
-## Rules
-
-- All HTTP goes through `client/http.ts`; command handlers never call axios directly.
-- Destructive commands (`delete`, `member remove`) go through `confirmDestructive` and
-  support `--yes`.
-- Human output via `src/output.ts`; `--json` always prints the full raw payload.
-- `npm run check` (lint + format + typecheck + unit tests + build + dist smoke +
-  functional e2e) must exit 0 — it is the merge gate and matches CI.
-- Functional tests live in `tests/e2e/` (see its README): a mock-server suite that
-  spawns the built binary (always on), plus an env-gated real-API suite that CI
-  (`.github/workflows/ci.yml`) enables when the `YUQUE_E2E_TOKEN` secret exists.
-  New/changed commands need e2e coverage in the mock suite, not just unit tests.
+## Map
+
+- `src/bin.ts` — process entry point; installs quiet `EPIPE` handling and assigns `process.exitCode` from `runCli`.
+- `src/cli.ts` — owns `buildProgram`, global options, domain registration, and the single `runCli` error-to-exit-code mapping.
+- `src/config.ts` — resolves token (`--token` > `YUQUE_TOKEN` > `YUQUE_PERSONAL_TOKEN`), host (`--host` > `YUQUE_HOST` > default), and timeout (`--timeout` > `YUQUE_TIMEOUT_MS` > 30000); `normalizeHost` strips trailing slashes and `/api/v2`.
+- `src/context.ts` — `getContext` builds the per-action HTTP/output context; call it only inside actions so `--help` never requires a token.
+- `src/errors.ts` — sole definition of CLI error classes, API status hints, and the stable exit-code contract.
+- `src/output.ts` — `printJson`/`printOk`/`printTable`/`printRecord`, TTY color honoring `NO_COLOR`, and CJK/emoji display-width alignment.
+- `src/confirm.ts` — `confirmDestructive` enforces the interactive confirmation or `--yes` gate for destructive actions.
+- `src/commands/` — Commander-facing domain modules; each exports one `register<Domain>Commands` function and owns flags, action orchestration, and rendering.
+- `src/commands/auth.ts` — `registerAuthCommands` registers connectivity and authenticated-account status commands.
+- `src/commands/book.ts` — `registerBookCommands` registers book list/get/create/update/delete, pagination, validation, and delete confirmation.
+- `src/commands/doc.ts` — `registerDocCommands` registers document CRUD, body/file handling, pagination, and version reads.
+- `src/commands/group.ts` — `registerGroupCommands` registers group-member list/set/remove, pagination, roles, and removal confirmation.
+- `src/commands/search.ts` — `registerSearchCommands` registers typed doc/book search and maps the book surface name to the API's `repo` value.
+- `src/commands/stats.ts` — `registerStatsCommands` registers aggregate/member/book/doc statistics, filters, sorting, and page draining.
+- `src/commands/toc.ts` — `registerTocCommands` registers TOC tree reads and cross-field-validated node updates.
+- `src/commands/user.ts` — `registerUserCommands` registers current-user and user-group reads with role filtering and pagination.
+- `src/client/http.ts` — the only HTTP exit; adds auth/base URL/timeout, normalizes errors, retries 429 for every method, and retries 502/503/504 or network failures only for GET.
+- `src/client/api/` — thin domain wrappers: `YuqueHttp` is the first argument, typed `ApiEnvelope` responses are awaited, and `res.data` is returned.
+- `src/client/api/book.ts` — book owner collection and id-or-namespace item API wrappers.
+- `src/client/api/doc.ts` — document CRUD, global-id lookup, and published-version API wrappers.
+- `src/client/api/group.ts` — group-member list/update/remove API wrappers.
+- `src/client/api/search.ts` — doc/repo search API wrapper.
+- `src/client/api/stats.ts` — group aggregate and paged member/book/doc statistics API wrappers, including the live-array correction to the spec types.
+- `src/client/api/toc.ts` — book TOC read/update API wrappers and update-body shape.
+- `src/client/api/user.ts` — heartbeat, current-user, and user-groups API wrappers.
+- `src/client/book-ref.ts` — parses a book reference as a numeric id or `group/slug` and produces the encoded `/repos/...` base path.
+- `src/client/paginate.ts` — drains offset-paged endpoints for `--all` until the first short page.
+- `src/client/types.gen.ts` — generated from `spec/yuque-openapi.yaml`; edit the spec and run `npm run gen:types`, never edit this file directly.
+- `src/client/types.ts` — thin compatibility adapter over the generated schemas; preserves public type names, live-API extensions, and index signatures for `--json` pass-through.
+- `spec/yuque-openapi.yaml` — vendored upstream OpenAPI contract and source of truth for the supported operation surface.
+- `scripts/smoke-dist-cli.js` — spawns `dist/bin.js` as an installed CLI would and checks version/help plus representative usage/auth exit codes.
+- `tests/commands/` — mocked command-action unit tests for exact requests, rendering, validation, confirmation, and exit behavior.
+- `tests/client/` — transport retry/error and book-reference unit contracts.
+- `tests/docs/` — programmatic drift locks for README command coverage and this repository guide.
+- `tests/e2e/` — built-binary functional tests: always-on mock-server wire assertions plus env-gated real-API coverage.
+- `tests/spec-coverage.test.ts` — pins every operationId + method + path to registered leaf commands and locks the expected command list.
+
+## Contracts & locks
+
+- Command surface is **locked 1:1 against `spec/yuque-openapi.yaml`** by `tests/spec-coverage.test.ts`; adding/renaming a command or refreshing the spec requires a deliberate mapping update.
+- Both READMEs are locked by `tests/docs/command-surface-docs.test.ts` for the exact heading count and exact registered leaf-command set; keep README.md and README.zh-CN.md strictly isomorphic.
+- Exit codes are stable and scripts may rely on them: `0 success · 1 API/unknown error · 2 usage error · 3 auth error · 4 not found · 5 rate limited` (`src/errors.ts`).
+- All HTTP goes through `src/client/http.ts`; command handlers never call axios directly.
+- Human output goes through `src/output.ts`; `--json` prints the complete unprojected payload returned by the API wrapper.
+- `npm run check` is the merge gate and matches CI: lint, format check, generated-type drift check, typecheck, coverage-enforced unit tests, one build, dist smoke, then functional e2e.
+- New or changed commands need always-on mock-server coverage in `tests/e2e/`, not only unit coverage; see `tests/e2e/README.md` for the optional real-API gates.
+
+## Adding a command
+
+1. Add the typed wrapper in `src/client/api/<domain>.ts`; take `http` first and `return res.data` to unwrap `ApiEnvelope`.
+2. Register the subcommand in `src/commands/<domain>.ts`; action order is local flag validation (`UsageError`) → `confirmDestructive` for destructive work, before `getContext` → `getContext(cmd)` → API call → `if (ctx.json) { printJson(raw); return; }` with the complete wrapper result → `printOk`/`printTable`/`printRecord`.
+3. For a new domain, add the import at the top of `src/cli.ts` and call its register function inside `buildProgram`.
+4. Update the `OPERATION_TO_COMMANDS` operationId + method + path tuples and `EXPECTED_LEAF_COMMANDS` in `tests/spec-coverage.test.ts`.
+5. Update `README.md` and `README.zh-CN.md`: increment each commands-section heading count and add an isomorphic command-table row; `tests/docs/command-surface-docs.test.ts` locks both.
+6. Regenerate the pinned help surface — `UPDATE_HELP_GOLDEN=1 npx vitest run tests/docs/help-surface.test.ts` — and review the `tests/docs/help-surface.golden.json` diff; any new or changed flag must appear there deliberately.
+7. Add `tests/commands/` unit coverage with exact request assertions and the expected process exit code.
+8. Add a `tests/e2e/` mock-suite case with wire-level request assertions against the built binary.
+9. Run `npm run check` and require the complete gate to pass.
+
+## Conventions & gotchas
+
+- ESM is mandatory (`package.json` has `"type": "module"`); relative TypeScript imports use `.js` suffixes because those are the emitted runtime paths.
+- Runtime support is Node >= 20, as pinned by `package.json#engines`.
+- For new flag validation, use `Option.choices` for enums or an argument parser that throws `UsageError`; both map to exit 2 because `buildProgram` calls `exitOverride` before registration and Commander copies that callback into subcommands (`tests/commands/flag-validation.test.ts` locks this). Put cross-field and semantic-required checks inside the action and throw `UsageError`; do not introduce new `InvalidArgumentError` parsers.
+- Destructive actions call `confirmDestructive` before `getContext`, so confirmation precedes auth/client setup; every such command supports `--yes`.
+- Convenience scripts: `npm run lint:fix` fixes lint, `npm run format` writes formatting, `npm run test:watch` watches unit tests, `npm run test:coverage` runs coverage, and `npm run dev` runs `src/bin.ts` directly through tsx.
+- Smoke and e2e exercise built `dist` output: `npm run smoke:dist` and `npm run test:e2e` build first, while `npm run check` builds once then calls their `:built` variants.
+- Release work includes updating `CHANGELOG.md`; npm's `prepublishOnly` lifecycle runs the build before publication.

README.md

@@ -87,7 +87,7 @@ Each command maps to the [Yuque OpenAPI](https://www.yuque.com/yuque/developer/a
 |            | `stats books <login>`                | Per-book statistics                                                                |
 |            | `stats docs <login>`                 | Per-doc statistics                                                                 |
 
-Books (知识库) accept either a numeric id or an `owner/slug` namespace everywhere. Run `yuque <command> --help` for all flags.
+Books (知识库) accept either a numeric id or an `owner/slug` namespace everywhere. For data-table docs, `doc get` accepts `--page` and `--page-size` to page the content. Run `yuque <command> --help` for all flags.
 
 ## Output & scripting
 
@@ -132,11 +132,11 @@ cd yuque-open-cli
 npm install
 npm test              # unit tests
 npm run build         # compile TypeScript
-npm run test:e2e      # functional tests: the built binary vs a mock Yuque API
+npm run test:e2e      # build, then run the binary against a mock Yuque API
 npm run dev -- --help # run from source
 ```
 
-The command surface is pinned to [spec/yuque-openapi.yaml](./spec/yuque-openapi.yaml) by [tests/spec-coverage.test.ts](./tests/spec-coverage.test.ts); `npm run check` is the merge gate.
+The command surface is pinned to [spec/yuque-openapi.yaml](./spec/yuque-openapi.yaml) by [tests/spec-coverage.test.ts](./tests/spec-coverage.test.ts); `npm run check` is the merge gate (lint, formatting, type checking, coverage-enforced unit tests, one build, dist smoke, and functional e2e).
 
 ## Links
 
@@ -148,7 +148,7 @@ The command surface is pinned to [spec/yuque-openapi.yaml](./spec/yuque-openapi.
 
 [MIT](./LICENSE)
 
-[ci-image]: https://img.shields.io/github/actions/workflow/status/yuque/yuque-cli/ci.yml?style=flat-square&label=CI
+[ci-image]: https://img.shields.io/github/actions/workflow/status/yuque/yuque-open-cli/ci.yml?style=flat-square&label=CI
 [ci-url]: https://github.com/yuque/yuque-open-cli/actions/workflows/ci.yml
 [npm-image]: https://img.shields.io/npm/v/yuque-open-cli?style=flat-square
 [npm-url]: https://www.npmjs.com/package/yuque-open-cli

README.zh-CN.md

@@ -87,7 +87,7 @@ YUQUE_TOKEN=YOUR_TOKEN npx yuque-open-cli auth status
 |            | `stats books <login>`                | 知识库维度统计                                                     |
 |            | `stats docs <login>`                 | 文档维度统计                                                       |
 
-知识库参数在所有命令中都同时接受数字 id 和 `owner/slug` 路径。各命令的完整参数见 `yuque <命令> --help`。
+知识库参数在所有命令中都同时接受数字 id 和 `owner/slug` 路径。对于数据表文档，`doc get` 接受 `--page` 和 `--page-size` 对正文进行分页。各命令的完整参数见 `yuque <命令> --help`。
 
 ## 输出与脚本化
 
@@ -132,11 +132,11 @@ cd yuque-open-cli
 npm install
 npm test              # 单元测试
 npm run build         # 编译 TypeScript
-npm run test:e2e      # 功能测试：构建产物对着 mock 语雀 API 跑
+npm run test:e2e      # 先构建，再让产物对着 mock 语雀 API 跑功能测试
 npm run dev -- --help # 从源码运行
 ```
 
-命令面由 [tests/spec-coverage.test.ts](./tests/spec-coverage.test.ts) 锁定在 [spec/yuque-openapi.yaml](./spec/yuque-openapi.yaml) 上；`npm run check` 是合并门槛。
+命令面由 [tests/spec-coverage.test.ts](./tests/spec-coverage.test.ts) 锁定在 [spec/yuque-openapi.yaml](./spec/yuque-openapi.yaml) 上；`npm run check` 是合并门槛（依次运行 lint、格式检查、类型检查、带覆盖率门槛的单元测试、一次构建、dist 冒烟测试和功能 e2e）。
 
 ## 相关链接
 
@@ -148,7 +148,7 @@ npm run dev -- --help # 从源码运行
 
 [MIT](./LICENSE)
 
-[ci-image]: https://img.shields.io/github/actions/workflow/status/yuque/yuque-cli/ci.yml?style=flat-square&label=CI
+[ci-image]: https://img.shields.io/github/actions/workflow/status/yuque/yuque-open-cli/ci.yml?style=flat-square&label=CI
 [ci-url]: https://github.com/yuque/yuque-open-cli/actions/workflows/ci.yml
 [npm-image]: https://img.shields.io/npm/v/yuque-open-cli?style=flat-square
 [npm-url]: https://www.npmjs.com/package/yuque-open-cli

eslint.config.js

@@ -1,28 +1,41 @@
 import tseslint from '@typescript-eslint/eslint-plugin';
-import tsparser from '@typescript-eslint/parser';
+
+const typedFiles = ['src/**/*.ts', 'tests/**/*.ts', '*.config.ts'];
+const javascriptFiles = ['scripts/**/*.js', '*.config.js'];
 
 export default [
   {
-    files: ['src/**/*.ts', 'tests/**/*.ts'],
+    ignores: ['coverage/', 'dist/', 'node_modules/', 'src/client/types.gen.ts'],
+  },
+  ...tseslint.configs['flat/recommended-type-checked'].map((config) => ({
+    ...config,
+    files: typedFiles,
+  })),
+  {
+    files: typedFiles,
     languageOptions: {
-      parser: tsparser,
       parserOptions: {
         ecmaVersion: 2022,
         sourceType: 'module',
+        project: './tsconfig.eslint.json',
+        tsconfigRootDir: import.meta.dirname,
       },
     },
-    plugins: {
-      '@typescript-eslint': tseslint,
-    },
     rules: {
-      ...tseslint.configs.recommended.rules,
       '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
       '@typescript-eslint/explicit-function-return-type': 'off',
-      '@typescript-eslint/no-explicit-any': 'warn',
-      '@typescript-eslint/no-non-null-assertion': 'warn',
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/no-floating-promises': 'error',
+      '@typescript-eslint/no-misused-promises': 'error',
+      '@typescript-eslint/no-non-null-assertion': 'error',
     },
   },
+  ...tseslint.configs['flat/recommended'].map((config) => ({
+    ...config,
+    files: javascriptFiles,
+  })),
   {
-    ignores: ['dist/', 'node_modules/', '*.js'],
+    ...tseslint.configs['flat/disable-type-checked'],
+    files: javascriptFiles,
   },
 ];