From b175e4c8f8fdeae5b09a790a6aadc1c6984d5881 Mon Sep 17 00:00:00 2001 From: Antony Rizzitelli Date: Thu, 19 Nov 2026 12:27:29 +0000 Subject: [PATCH 1/3] chore: delete the verify-dms-api harness --- .../skills/formal-route-statistics/SKILL.md | 2 +- .agents/skills/verify-dms-api/SKILL.md | 99 --------------- .../skills/verify-dms-api/coverage/access.md | 10 -- .../verify-dms-api/coverage/automation.md | 12 -- .../skills/verify-dms-api/coverage/capture.md | 19 --- .../skills/verify-dms-api/coverage/logs.md | 36 ------ .../verify-dms-api/coverage/overview.md | 35 ----- .../skills/verify-dms-api/coverage/package.md | 14 -- .../verify-dms-api/coverage/retention.md | 6 - .../skills/verify-dms-api/coverage/routes.md | 27 ---- .../verify-dms-api/coverage/settings.md | 25 ---- .../skills/verify-dms-api/coverage/smoke.md | 9 -- .../skills/verify-dms-api/coverage/tester.md | 19 --- .../skills/verify-dms-api/features/README.md | 18 --- .../skills/verify-dms-api/features/access.md | 33 ----- .../verify-dms-api/features/automation.md | 33 ----- .../skills/verify-dms-api/features/capture.md | 46 ------- .../skills/verify-dms-api/features/logs.md | 62 --------- .../verify-dms-api/features/overview.md | 70 ---------- .../skills/verify-dms-api/features/package.md | 34 ----- .../verify-dms-api/features/retention.md | 35 ----- .../skills/verify-dms-api/features/routes.md | 64 ---------- .../verify-dms-api/features/settings.md | 42 ------ .../skills/verify-dms-api/features/smoke.md | 32 ----- .../skills/verify-dms-api/features/tester.md | 42 ------ .agents/skills/verify-dms-api/package.json | 1 - .agents/skills/verify-dms-api/tsconfig.json | 20 --- .../skills/verify-dms-api/verify.config.ts | 120 ------------------ .claude/skills/verify-dms-api | 1 - .github/workflows/ci.yml | 2 +- .gitignore | 3 +- AGENTS.md | 4 +- e2e/api.mjs | 4 +- e2e/journeys/automation.mjs | 3 - e2e/journeys/capture.mjs | 3 - e2e/journeys/package.mjs | 3 - e2e/journeys/routes/tree-and-statistics.mjs | 2 +- e2e/playground/antelope.config.ts | 2 +- e2e/playground/package.json | 2 +- e2e/playground/src/automation-stub/routes.ts | 2 +- e2e/playground/src/fixture-members.ts | 4 +- e2e/playground/src/fixture.ts | 2 +- tests/automation.journeys.test.ts | 2 +- tests/capture-redaction.journeys.test.ts | 2 +- tests/capture.journeys.test.ts | 4 +- tests/helpers/automation.ts | 2 +- tests/helpers/backend.ts | 2 +- tests/helpers/dms.ts | 6 +- vitest.journeys.config.ts | 2 +- 49 files changed, 23 insertions(+), 999 deletions(-) delete mode 100644 .agents/skills/verify-dms-api/SKILL.md delete mode 100644 .agents/skills/verify-dms-api/coverage/access.md delete mode 100644 .agents/skills/verify-dms-api/coverage/automation.md delete mode 100644 .agents/skills/verify-dms-api/coverage/capture.md delete mode 100644 .agents/skills/verify-dms-api/coverage/logs.md delete mode 100644 .agents/skills/verify-dms-api/coverage/overview.md delete mode 100644 .agents/skills/verify-dms-api/coverage/package.md delete mode 100644 .agents/skills/verify-dms-api/coverage/retention.md delete mode 100644 .agents/skills/verify-dms-api/coverage/routes.md delete mode 100644 .agents/skills/verify-dms-api/coverage/settings.md delete mode 100644 .agents/skills/verify-dms-api/coverage/smoke.md delete mode 100644 .agents/skills/verify-dms-api/coverage/tester.md delete mode 100644 .agents/skills/verify-dms-api/features/README.md delete mode 100644 .agents/skills/verify-dms-api/features/access.md delete mode 100644 .agents/skills/verify-dms-api/features/automation.md delete mode 100644 .agents/skills/verify-dms-api/features/capture.md delete mode 100644 .agents/skills/verify-dms-api/features/logs.md delete mode 100644 .agents/skills/verify-dms-api/features/overview.md delete mode 100644 .agents/skills/verify-dms-api/features/package.md delete mode 100644 .agents/skills/verify-dms-api/features/retention.md delete mode 100644 .agents/skills/verify-dms-api/features/routes.md delete mode 100644 .agents/skills/verify-dms-api/features/settings.md delete mode 100644 .agents/skills/verify-dms-api/features/smoke.md delete mode 100644 .agents/skills/verify-dms-api/features/tester.md delete mode 100644 .agents/skills/verify-dms-api/package.json delete mode 100644 .agents/skills/verify-dms-api/tsconfig.json delete mode 100644 .agents/skills/verify-dms-api/verify.config.ts delete mode 120000 .claude/skills/verify-dms-api delete mode 100644 e2e/journeys/automation.mjs delete mode 100644 e2e/journeys/capture.mjs delete mode 100644 e2e/journeys/package.mjs diff --git a/.agents/skills/formal-route-statistics/SKILL.md b/.agents/skills/formal-route-statistics/SKILL.md index 40df2e0..0cea88e 100644 --- a/.agents/skills/formal-route-statistics/SKILL.md +++ b/.agents/skills/formal-route-statistics/SKILL.md @@ -39,7 +39,7 @@ The lines that name a changed rule match `^(?:BROKEN|CHANGED|HOLDS) +(\w+)`. A r ## When to run it -Run `--full` when a change touches a file in the coverage record below, or this folder. CI runs the CI configuration on every push (job `formal-route-statistics`, in the `ubuntu` gate). The `verify-dms-api` skill lists this check in its `verify.config.ts`, so `dms-control formal` runs the full configuration on a verdict whose diff touches a covered file or this folder. +Run `--full` when a change touches a file in the coverage record below, or this folder. CI runs the CI configuration on every push (job `formal-route-statistics`, in the `ubuntu` gate). ## The rules diff --git a/.agents/skills/verify-dms-api/SKILL.md b/.agents/skills/verify-dms-api/SKILL.md deleted file mode 100644 index 2fcc6c3..0000000 --- a/.agents/skills/verify-dms-api/SKILL.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -name: verify-dms-api -description: "Drive the AntelopeJS dms-api module (the API console: health verdict, request logs, routes with their statistics and inferred documentation, the tester, and the settings) the way the platform owner does, inside a DMS with free ports and its own MongoDB database, and report a verdict with evidence. Use to prove a change to AntelopeJS/dms-api works before merge, or to verify a PR." ---- - -# Verify dms-api - -Every deterministic step is a `dms-control` command. You choose which journeys to run and judge what they show; you never write a multi-step shell recipe. When a journey you need does not exist, add it to `e2e/journeys/.mjs`, describe it in its feature file, and run it. - -`dms-control` is the bin of `@antelopejs/dms`, a devDependency of this package. Run it with Node 24 after `pnpm install`: - -```bash -C="pnpm exec dms-control" -$C # lists every command -``` - -Give `doors` and `--skill` absolute paths. - -## Launch - -```bash -RUN=$($C up --prepare --skill "$PWD/.agents/skills/verify-dms-api" --base origin/main) -``` - -`--prepare` runs the `prepare` commands of `verify.config.ts`: the frozen install, the build of the module, the playground's install and the TypeScript build of the fixture module. Without it `up` uses the builds already there. `up` starts an isolated DMS from the playground in `playground/`: the DMS, the api, MongoDB, auth, local file storage and mail modules, the module under verification as a `local` source at the checkout, and a fixture module `app`. - -- The checkout is laid out again under `$RUN/root`, every sibling linked, and the playground copied without `node_modules`, so the run's build, `.antelope/` and stored files are its own. The playground names the checkout's real folder as the module's source, because the module's `@/` import alias applies to files under the folder the source names. -- The API, the dashboard and the mail sink get free ports from the kernel; a `mongod` the run owns serves `verify_` databases. -- The api module is the published `@antelopejs/api` (1.7.0 or later, which builds route handlers with `controller`). The `up` of a run needs the npm registry once, for the api and the dashboard's dependencies. - -The fixture module (`playground/src`) serves what a journey cannot do over the console's own routes. `/fx/*` are the project's routes that traffic goes to: `ok`, `slow?ms=`, `boom` (throws), `missing` (404), `echo` (POST, 201), `login` (a token in the answer), `blob`, `items/:id` (GET, PUT, DELETE), `guarded/secret` (behind `auth_check`), `named/page` (behind `checkTicket`), `inline/private` (checks inside), `orders/:shop/lines` (path, query, header and body parameters). `POST /verify-api/member` makes a member whose role holds exactly the permission ids given. - -## Doctor - -```bash -$C doctor "$RUN" # prints only failing checks; --verbose prints all -``` - -Do not drive a run that fails doctor. Its module checks look at this skill folder, not the module (known gap, reported against `dms-control`: the module root is taken from the playground's parent folder), so check that `dist/` is newer than `src/` yourself with `--prepare`. - -## Drive - -```bash -$C map # every user-facing file is covered by a feature -$C plan --base origin/main -$C journey "$RUN" smoke -$C journey "$RUN" overview [journey-id...] -``` - -- Each feature file in [features/](features/README.md) lists its source globs (`covers:`), its docs pages (`docs:`) and its journeys; the journeys are in `e2e/journeys/.mjs` (the `journeys` folder of `verify.config.ts`), with the helpers they share in `e2e/`: `api.mjs` (requests, checks, traffic, settings, members), `seed.mjs` (aged rows written to the run's MongoDB, which the module cannot be made to age), `guard.mjs` (environment loss) and `clock.cjs` (the backend's clock set ahead, so the hourly prune fires within seconds). [coverage/](coverage) holds one table per feature: every documented behaviour, its catching journey and check, or `Not driven` with the reason. -- A journey starts on an empty database with the administrator onboarded and the backend restarted on it. It reads every mutation back through a second view: the API, a reload, the stored documents, or a backend restart. -- A journey may set `tag` (Playwright tags such as `"@smoke"`, the set CI runs on a pull request) and `knownFailures`, which maps the name of each check that fails today to the finding that makes it fail. A listed check that fails is `known` and does not fail the journey. A listed check that passes is `fixed` and fails the journey until the entry is removed. -- The same journeys run as the Playwright suite of `e2e/`, which CI runs (`@smoke` on a ready pull request, every journey in the merge queue, nightly, on a manual run and on a pull request labelled `ci:full`): `TZ=UTC pnpm e2e` prepares and starts a run, runs every journey on it and stops it; `pnpm e2e -g ` or `--grep @smoke` narrows it. `DMS_E2E_PREBUILT=1` skips the prepare commands, and `DMS_E2E_RUN=$RUN` drives a run you started with `up`, which it leaves running. The report attaches each failed step's screenshot and ARIA snapshot and the backend log. -- Statistics and health are written behind the response: journeys wait with `settled` before reading them. -- `withConfig(ctx, { statisticsLifetime: … }, body)` restarts the backend with module options set and restarts it again without them. -- To look at the product yourself: `$C onboard "$RUN"`, `$C browser "$RUN" login`, `goto --path`, `snapshot`, `click --role --name`, `fill`, `press`, `screenshot`, `$C api "$RUN" [--as anon] [--body ]`, `$C reset "$RUN"`. Each writes its evidence under `$RUN/evidence/`. - -## Evidence - -Everything goes under `$RUN/evidence/`: `//NN-/` with `action.json`, `url.txt`, `aria.yml` and `screenshot.png` for a browser step, `request.json` and `response.json` for a request, and `checks.json` for every step that checks something; `//result.json` and `/feature.json`. Read the evidence before you judge a PASS: a check passing proves only what it asserts. Page text checks run on the rendered text, where headings are in capitals. - -## Cleanup - -```bash -$C down "$RUN" -``` - -## Verdict rules - -1. **Run every feature whose `covers:` globs the diff touches, plus the smoke journey.** `plan` prints that list as `run`. -2. **Unmapped surface fails the verdict.** User-facing code is `src/**`, `frontend-vue/**`, `skills/**` and `package.json`, tests and tool configs excluded (`verify.config.ts`). `map` checks the whole tree. -3. **Every registered journey of a feature in `run` must have run and passed.** A check listed in its journey's `knownFailures` reads `known` and does not fail it: name each one in the reply as a note. -4. **Docs.** Judge every `docs:` page of each touched feature against what the journeys showed. -5. **Formal checks.** `verify.config.ts` lists `formal-route-statistics` ([its skill](../formal-route-statistics/SKILL.md)): the per-route statistics rollup, model-checked with TLC. Run `$C formal "$RUN"` before the verdict: when the diff touches a file it covers or its own folder, it runs the full configuration and records it under `evidence/formal/formal-route-statistics/`. The check exiting non-zero, or not running, fails the verdict. It has no recorded finding, so any rule it reports broken fails it. -6. **One-way doors.** The section comes right after the result line and is mandatory. `$C doors` prints the `One-way-door:` line for the diff. -7. **Result.** FAIL if any of rules 1 to 6 fail. PASS+NOTES when something is not verified or needs the owner's attention. PASS otherwise. - -State the verdict in your own reply. Start it with the result, then the doors, then what each rule showed, what was not verified and what needs the owner's attention. - -## Gotchas - -- Every dashboard page renders on the server and hydrates after `load`; `tab.signIn` waits for the sign-in form to hydrate. -- The Routes page keeps its tree and filters behind the button that names the open route; the journeys open it before they filter. -- `mongod` comes from `DMS_CONTROL_MONGOD`, `PATH`, or the mongodb-memory-server cache (`~/.cache/mongodb-binaries`); a verifier with a bare environment passes `DMS_CONTROL_MONGOD` along. -- The host's time zone must be a real one: with `TZ` unknown the dashboard pages answer 500 "Invalid time zone specified". Run with `TZ=UTC` (and `--pass-env TZ` for the agent-skills eval). -- `npm pack` ships `frontend-vue/tests/**` with the Vue layer (the `files` entry is the whole folder); the package journeys do not forbid it. - -## Not driven - -List these as not verified in every verdict. The per-feature reasons are in [coverage/](coverage). - -- The Tester's Copy cURL and the Copy buttons beside a value (the request's URL, ID and error message): no journey presses them yet. The clipboard can be read, as `copy-curl-copies-the-open-request-as-a-command` does. -- The automation runtime: the playground does not load `@antelopejs/dms-automation`. The fixture module stands in for its provider, so the `automation` journeys drive the three nodes' `execute` and `activate`, and the election that runs `api.route-unhealthy` on one node is not driven. -- A second instance behind one console sharing `testerSourceSecret`: the run has one backend. -- The Tester form's query and body editors, and the 30 s timeout of the Tester's forwarding route. - -## Feature map - -[features/README.md](features/README.md). diff --git a/.agents/skills/verify-dms-api/coverage/access.md b/.agents/skills/verify-dms-api/coverage/access.md deleted file mode 100644 index db03870..0000000 --- a/.agents/skills/verify-dms-api/coverage/access.md +++ /dev/null @@ -1,10 +0,0 @@ -# Coverage: access - -| Source | Documented behaviour | Journey | Check | -|---|---|---|---| -| docs/5.extending.md (Access) | Each route is guarded with `@AuthUserWithPermission()` for the block it feeds | `every-console-route-needs-a-session-and-the-block-it-serves` | all 28 routes answer 401 without a session and 403 naming the missing permission to a member with none | -| docs/5.extending.md (Access) | The console is for the owner only: a role cannot be given the console or any block of it | `the-console-is-the-owners-and-a-role-holding-a-block-is-refused` | a role holding the logs table's permission and a role holding the Tester's are refused on every route; the owner opens `GET /logs` and `GET /tester/source` | -| docs/5.extending.md (Access) | The settings summary is for the owner | `every-console-route-needs-a-session-and-the-block-it-serves` | `GET /settings/summary` is 403 for a member and passes for the owner | -| docs/4.usage/4.settings.md (intro) | Module pages are the owner's | `a-member-without-the-modules-permissions-is-sent-to-their-settings` | the owner stays on each of the four pages and sees its heading; the member is sent to `/settings` from each page and from `/modules/api`, sees the `Settings` heading and none of the console's; the routes' answers are asserted by `every-console-route-needs-a-session-and-the-block-it-serves` | -| src/services/request-log/access.ts (TSDoc) | A panel opened from one table reads only a request that table can list; a request out of reach is a 404 | `a-panel-opened-from-one-table-reads-only-a-request-that-table-can-list` | with the scope on the project's routes: a module's request reads 200 on the Request logs panel and 404 on the Overview's, the Routes page's and the Tester's; one the Tester sent reads 200 on the Tester's panel too; the project's request reads 200 everywhere; the refusal answers like an id nothing holds. HTTP only, as the owner: a member holding a table's permission is refused before the panel's rule applies | -| docs/5.extending.md (Access) | The 403 names that block's permission id | `every-console-route-needs-a-session-and-the-block-it-serves` | each of the 27 routes refuses a member with the exact permission id of its own block (`modules.api.monitor.logs.requests`, `...explore.routes.explorer.tabs.tester` for `/logs/tester` and `/tester/source`, `...configure.settings.form` for the settings routes, and so on); `/settings/summary` answers `Owner-only` | diff --git a/.agents/skills/verify-dms-api/coverage/automation.md b/.agents/skills/verify-dms-api/coverage/automation.md deleted file mode 100644 index 0e8559f..0000000 --- a/.agents/skills/verify-dms-api/coverage/automation.md +++ /dev/null @@ -1,12 +0,0 @@ -# Coverage: automation - -The playground's fixture module stands in for the automation provider when a journey restarts the backend with `VERIFY_API_AUTOMATION=1`: it keeps the node types the module registers and runs `execute` and `activate` through `/verify-api/nodes`. The automation runtime itself is not loaded. - -| Source | Documented behaviour | Journey | Check | -|---|---|---|---| -| docs/5.extending.md (Automation nodes) | Without `@antelopejs/dms-automation` the registration is a silent no-op | `without-the-automation-module-the-registration-is-a-silent-no-op` | `the log says the optional automation interface has no provider`, `no error line names the automation nodes`, `no line says dms-api failed`, `the console answers` | -| docs/5.extending.md (Automation nodes) | The module registers three nodes: `api.route-unhealthy`, `api.get-api-health`, `api.query-request-logs`; the trigger runs on one node of a cluster | `the-module-registers-its-three-nodes-with-their-documented-inputs` | the registered ids, `singleton`, and each declared input: `days` minimum 1, `limit` default 50 maximum 200, the three status classes, `intervalSeconds` default 60 minimum 10, the flags and their default, the output fields | -| docs/5.extending.md (Route unhealthy trigger) | Fires when a route enters a bad state by the API health rules; `flags` broken, slow, warn with default broken and slow; `intervalSeconds` default 60, minimum 10; output routeKey, method, uri, flag, errorRate, averageLatencyMs, requestsLast24h | `route-unhealthy-fires-on-the-flags-it-watches-and-never-faster-than-ten-seconds` | four triggers armed before a failing, a noisy and a slow route appear: `broken` only gets the failing route, `warn` only the noisy one, the default gets broken and slow, all three flags get three; the output of a broken route; an interval of 1 second fires nothing in the first seconds and fires after 10 | -| docs/5.extending.md (Route unhealthy trigger) | It runs on one node of a cluster | the same journey (`cluster: singleton`); the election between instances is Not driven: the run has one backend | -| docs/5.extending.md (Get API health action) | Returns the KPIs of the routes in scope and a status breakdown; the optional `days` input restricts the breakdown to the last N days | `get-api-health-restricts-its-breakdown-to-the-last-days` | 4 calls with 1 server error 10 days ago and 6 calls today: without `days` 10 / 1 / 0 / 9; `days` 1 and 5 give 6; `days` 30 gives 10; `totalRoutes`, `callsToday` 6, `failingRoutes` 0, `errors24h` 0, and the KPIs do not follow `days` | -| docs/5.extending.md (Query request logs action) | Inputs routeId, uri, method, statusClass, statusMin, statusMax and limit (default 50, max 200); returns results and a nextCursor | `query-request-logs-pages-caps-and-filters` | 273 seeded rows: default 50 and a cursor, 250 capped to 200, 10; client errors 20, server errors 3, success 50; a status range, one status, a uri, a method with none; ISO timestamps. `routeId` is Not driven (seeded rows carry no route id). The next page: `query-request-logs-next-cursor-reads-the-next-page` lists its check `asking with it returns other rows` in `knownFailures` (the action takes no cursor input, so a second call returns the first page again; issue draft `dms-api-query-request-logs-has-no-cursor-input`) | diff --git a/.agents/skills/verify-dms-api/coverage/capture.md b/.agents/skills/verify-dms-api/coverage/capture.md deleted file mode 100644 index 1c14037..0000000 --- a/.agents/skills/verify-dms-api/coverage/capture.md +++ /dev/null @@ -1,19 +0,0 @@ -# Coverage: capture - -| Source | Documented behaviour | Journey | Check | -|---|---|---|---| -| docs/1.introduction.md | The module records each request: method, path, status, timing | `a-request-is-captured-with-its-facts` | `method`, `the route pattern`, `the raw path`, `the status`, `a duration was measured` | -| docs/1.introduction.md | ... captured headers and bodies, size-capped and redacted | `only-the-listed-headers-are-stored-and-secret-ones-never`, `values-under-secret-looking-keys-are-redacted-before-storage`, `bodies-above-the-cap-are-stored-truncated-and-flagged` | see below | -| docs/1.introduction.md | Its own calls (`/api/monitoring`), the DMS's calls (`/dms`, the realtime channel, page layouts) are neither logged nor counted | `the-consoles-own-and-the-dms-traffic-is-never-captured` | `no /api/monitoring call is stored`, `no /dms call`, `no page layout`, `no realtime call` (under All routes, where module routes show) | -| docs/1.introduction.md | Calls sent from the Tester are logged, marked, and left out of the statistics, the health and the incidents | `a-tester-call-is-logged-and-marked-but-never-counted` (feature tester) | `the call is marked as the Tester's`, `the health counted nothing`, `nothing needs attention` | -| docs/1.introduction.md | Statistics roll up per route per day, pruned every hour | `the-hourly-prune-deletes-what-the-retention-passed` (feature settings) | statistics left after the prune | -| docs/3.configuration.md | `requestLogMaxBodySize`: bodies above it are stored truncated and flagged; 0 turns body capture off | `bodies-above-the-cap-are-stored-truncated-and-flagged` | `the body at the cap is whole` (1024), `the body above the cap is flagged` (1025), `it keeps the first 1024 bytes`, `it records the whole size`, `the echoed response is cut too`, `a cap of 0` | -| docs/3.configuration.md | `requestLogCaptureHeaders`: request headers stored, lower case; default eight headers; secret-looking never stored; empty list stores none | `only-the-listed-headers-are-stored-and-secret-ones-never` | `the stored request headers` (default seven that the client sent), `a header outside the list is absent`, `a secret header is refused`, `stored lower case without repeats`, `authorization is never stored`, `no request header is stored`, `the override stays explicit` | -| docs/3.configuration.md | Values under secret-looking keys (password, token, authorization, cookie, card numbers...) are replaced with `[REDACTED]` in bodies and query strings; the list is fixed | `values-under-secret-looking-keys-are-redacted-before-storage` | one check per word of the 23 in the request body and in the query, `a plain key keeps its value`, `a nested secret is redacted`, the three `redactions` counts | -| src/services/request-log/redaction.ts (TSDoc) | Keys match by words: `clientSecret`, `x-api-key`, `accessToken`, `accesstoken`, `userPin`, `creditCard`, `card_cvc2` are secret; `spin`, `footprint`, `company`, `cardBrand` are not; a payment card number is redacted whatever its key | `a-key-is-secret-by-the-words-it-is-made-of` | one check per key, `a spaced card number is redacted`, `twelve digits are not a card number` | -| src/services/request-log/capture.ts (TSDoc) | A thrown value is stored as an error: an Error's message and stack, a thrown HTTP result's body message | `a-thrown-error-keeps-its-message-and-its-stack` | `boom's message`, `boom's stack names the handler`, `missing's message is its body message`, `ok has no error` | -| docs/5.extending.md | `x-request-id` is the request id found in the logs | `a-request-is-captured-with-its-facts` | `the request id comes from x-request-id` | -| src/services/request-log/redaction.ts (depth 32) | Redaction walks bodies to a depth limit | Not driven: the limit (32) would need a 33-level body and the stored shape past the limit is not documented | -| src/services/statistics-write.ts | Per-route per-day counters (requests, client and server errors, latency histogram) | indirectly: `the-statistics-tab-adds-up-the-period`, `the-blocks-rank-the-routes-by-what-is-wrong-with-them` read them through the API; the stored shape itself is the Format door | -| docs/3.configuration.md | Secret-looking headers (authorization, cookies, API keys) are never stored | `only-the-listed-headers-are-stored-and-secret-ones-never` | authorization, cookie, set-cookie, x-api-key, proxy-authorization and the Tester header are refused in the list (400 each) and absent from the stored headers when sent | -| docs/3.configuration.md (Data handling) | Values under secret-looking keys, and card numbers, are replaced with `[REDACTED]` in bodies and query strings, wherever they sit | `secrets-and-card-numbers-are-redacted-wherever-they-sit` | query values (plain, dashed, spaced, American Express, Mastercard, repeated, in a sentence) and their count of 8; a form body (3 redactions, a Luhn-invalid number kept); arrays and nested arrays of a JSON body (4 redactions, the response too); the 32-level depth limit; text/plain, malformed JSON and a bare JSON string are not stored | diff --git a/.agents/skills/verify-dms-api/coverage/logs.md b/.agents/skills/verify-dms-api/coverage/logs.md deleted file mode 100644 index f69cee2..0000000 --- a/.agents/skills/verify-dms-api/coverage/logs.md +++ /dev/null @@ -1,36 +0,0 @@ -# Coverage: logs - -| Source | Documented behaviour | Journey | Check | -|---|---|---|---| -| docs/4.usage/2.request-logs.md (intro) | The page lists every captured request, newest first | `the-list-is-newest-first-sorts-and-pages` | `newest first` | -| docs/4.usage/2.request-logs.md (Filter) | The chart shows the requests of the period by status class, for all traffic whatever the table filters | `the-histogram-bars-follow-the-period` | `the totals` per preset, `the bars add up to the requests by class`; page text `6 requests` | -| docs/4.usage/2.request-logs.md (Filter) | Over 7D and 30D the past days count every kept request by class, in the bar of its time | `the-histogram-counts-past-days-by-class` | `7D: the totals`, `7D: the bars around 3 days ago hold them`, `30D: the totals, the calls of 10 days ago included` | -| docs/4.usage/2.request-logs.md (Filter) | Bars: a minute over 1H, 15 minutes over 24H, 2 hours over 7D, 6 hours over 30D and All time, 50 to 120 bars | same | `bar length and count` for the five presets (60, 96, 84, 120, 120 bars) | -| docs/4.usage/2.request-logs.md (Filter) | The chart shows the retention and body cap in use | same | page text `Kept 30 days · bodies up to 64 KB` | -| docs/4.usage/2.request-logs.md (Filter) | A period that reaches now updates live and freezes on Pause; a past range is read once and says it is not live | same; `pause-holds-the-table-and-counts-what-was-missed` | `live while the period reaches now`, and for five past ranges `not live and empty`; `Live` is on, then `Pause` | -| docs/4.usage/2.request-logs.md (Filter) | A length is picked the same way for a custom range, 50 to 120 bars | same | five past ranges off the bar boundaries: 1 day 15 min, 5 days 2 h, 10 days 3 h, 48 days 6 h, 6 minutes 1 min, at least 50 bars; the upper bound of 120 is asserted by `a-past-range-draws-at-most-120-bars`; `a bar length asked for within the cap is used`, `...beyond the cap is not used` | -| docs/4.usage/2.request-logs.md (Filter) | Tabs All, 2xx, 4xx, 5xx with counts | `the-tabs-the-filters-and-the-search-narrow-the-list` | API totals per class and the tab buttons `All 11`, `2xx 7`, `4xx 2`, `5xx 2`; the 4xx tab shows only the 404s and hides the 500s | -| docs/4.usage/2.request-logs.md (Filter) | Method and Slow narrow the table; the slow filter follows the slow threshold | same | `a method`, `two methods`, `slow follows the threshold`, button `Slow (≥ 50 ms)` then only `/fx/slow` | -| docs/4.usage/2.request-logs.md (Filter) | The period selector adds All time (ALL) and compares nothing | `counts-are-grouped-and-all-time-compares-nothing`; `the-histogram-bars-follow-the-period` | on `?api.period=all` the All time radio is on, no `Comparison:` control and no previous-period text show; `Requests per 6 h · all kept logs` | -| docs/4.usage/2.request-logs.md (Filter) | `/` opens the search; `?` lists the shortcuts | `slash-opens-the-request-search-and-question-mark-lists-the-shortcuts` | `the question mark` (the `Keyboard shortcuts` dialog and its five lines), `Escape` closes it, `the focused field` is the search after `/` and not before, `typing without a click` narrows the table to `/fx/missing`; the search itself is also driven through the API (`the search matches error words`, `the search matches path words`) | -| docs/4.usage/2.request-logs.md (Open a request) | A click on a row opens the drawer titled with its method and path | `a-request-opens-in-a-drawer-that-steps-through-the-list` | `the newest request` | -| docs/4.usage/2.request-logs.md (Open a request) | Its position over the whole result (`3 of 26,120`); J steps to the next request and K to the previous one | same | `1 of 6`, `Next` to `2 of 6`, `J steps to the next request` (`3 of 6`), `K steps back` | -| docs/4.usage/2.request-logs.md (Open a request) | The URL names it (`?record=`); a link or a reload opens it again | same | `the URL names the record`, `a reload` | -| docs/4.usage/2.request-logs.md (Open a request) | Drag its left edge to widen it: it opens again at that width | `dragging-the-drawers-left-edge-widens-it-and-it-opens-again-at-that-width` | `the drawer is wider after the drag` (600 px to 760 px for a 160 px drag with the real pointer), `its edge reports the width`, `opened again` and `after a reload` at the same width | -| docs/4.usage/2.request-logs.md (Open a request) | Summary: the error and its stack, the general facts, the timing against the route's p50 and p95, the path parameters | same | `Summary`: error message, Route, User agent, Request ID, `500 Internal Server Error`, `Slow threshold 1,000 ms, as set now.` | -| docs/4.usage/2.request-logs.md (Open a request) | Request: the captured headers, query string and body | same | `Request`: `limit 5`, `content-type application/json`, the body | -| docs/4.usage/2.request-logs.md (Open a request) | Response: the status, headers and body | same | `Response` | -| docs/4.usage/2.request-logs.md (Open a request) | Replay in tester opens the route's Tester filled with the request | same | `Replay in tester`: URL `tab=tester&replay=`, the path parameter box, the body | -| docs/4.usage/2.request-logs.md (Open a request) | Copy cURL copies it as a command | `copy-curl-copies-the-open-request-as-a-command` | the clipboard (read with the context's clipboard permission) holds a `curl -X POST` command with the API origin, `/fx/orders/shop1/lines?limit=5`, the captured content type and the body; the toast `cURL copied` | -| docs/4.usage/2.request-logs.md (Open a request) | Same error lists the other requests that failed the same way | same | `Same error`: URL route and error, `All 2` | -| docs/4.usage/2.request-logs.md (note) | Bodies above the cap are stored truncated and flagged; secret-looking values are stored as `[REDACTED]` | feature capture | see coverage/capture.md | -| docs/5.extending.md (Link to the console) | `/modules/api/logs?record=` opens a request; `?since=&until=` the requests of a range; `?api.period=` and `?live=0` | `a-request-opens-in-a-drawer-that-steps-through-the-list`; `a-link-names-a-range-with-since-and-until`; `the-period-and-the-comparison-are-kept-in-the-url-and-shared-by-the-pages` | `a reload`; `All 3` and `5xx 0` for a range holding 3 of 5 requests, `All 5` without it; `?live=0` | -| src/services/request-log/list.ts (TSDoc) | The route filter names the route's method, not the request's; the path filter is the raw path; the error filter is read whole | `the-tabs-the-filters-and-the-search-narrow-the-list` | `the route filter names the route, not the path`, `the path filter is the raw path`, `the error filter` | -| src/services/request-log/list.ts | The list pages by 50 and keeps the total; sorts by time, status and duration | `the-list-is-newest-first-sorts-and-pages` | `the first page holds 50 rows`, `the second page holds the other 10`, `status ascending`, `status descending` | -| src/services/request-log/list.ts | Sorting by duration | `the-list-sorts-by-duration-both-ways` | four seeded durations (0.4, 12, 999, 1234.5 ms) come back in order ascending and descending; the table writes `0 ms`, `12 ms`, `999 ms`, `1,235 ms` and the slow flag follows the 1 s default | -| docs/4.usage/1.overview.md (Live mode) | "Table on hold · search active" while one row is open or a search is active | `an-open-row-or-an-active-search-holds-the-table-and-says-why` | no notice with nothing open; `page shows /Table on hold · search active/` while a search is typed with `/` and no notice once it is cleared; `an open request says the table is on hold, row open` is listed in `knownFailures`: the request panel is a modal `drawer` target and the DMS names the `row open` hold only for a docked `sidePanel` target, so an open request holds the table without saying why | -| docs/4.usage/2.request-logs.md (Filter) | Method and Slow narrow the table further, together with the status tabs and a route | `filters-combine-with-the-status-tab` | nine combinations with their totals and paths: 2xx and POST 2, 2xx and GET 4, 4xx and GET 1, 4xx and POST 0, 5xx and slow 0, 2xx and slow 1, slow and POST 0, 2xx and a route 2, 5xx and a route 0 | -| docs/4.usage/2.request-logs.md (Filter) | The Slow button names the threshold (Slow (≥ 1 s)) | `the-slow-labels-follow-the-threshold-in-seconds-or-milliseconds` | `1 s` by default, `1.05 s`, `2 s`, `950 ms`, `50 ms`, `600 s`; the Overview line `1 slow route (≥ 1 s)` | -| docs/4.usage/2.request-logs.md (Open a request) | Summary shows the URL, date, route, client IP, user agent, request ID and the path parameters | `a-request-opens-in-a-drawer-that-steps-through-the-list` | `URL` with the full address and query, `Date` with milliseconds, `Route`, `Client IP`, `User agent`, `Request ID` (36 characters), `PATH PARAMETERS shop shop1`, `201 Created`, body size `JSON · 25 B` | -| docs/4.usage/2.request-logs.md (intro) | Counts are grouped (`3 of 26,120`) | `counts-are-grouped-and-all-time-compares-nothing` | `All 1,234`, `2xx 1,234`, `1,234 requests`, drawer `1 of 1,234` | -| docs/4.usage/1.overview.md (Live mode) | The Live or Pause choice applies to all three pages | `pause-holds-the-table-and-counts-what-was-missed` | Pause on the logs reads Pause on the Overview and on Routes; Live brings them back | diff --git a/.agents/skills/verify-dms-api/coverage/overview.md b/.agents/skills/verify-dms-api/coverage/overview.md deleted file mode 100644 index be7277d..0000000 --- a/.agents/skills/verify-dms-api/coverage/overview.md +++ /dev/null @@ -1,35 +0,0 @@ -# Coverage: overview - -| Source | Documented behaviour | Journey | Check | -|---|---|---|---| -| docs/4.usage/1.overview.md | The hero shows the verdict (Healthy, Degraded or Down) | the six verdict journeys | `the hero` page text per verdict; `the verdict` in the API | -| docs/4.usage/1.overview.md | Degraded from 1% of server errors over 15 minutes | `one-failing-call-in-a-hundred-is-degraded`; `one-failing-call-in-a-hundred-and-one-is-operational` | 1 in 100 reads degraded, 1 in 101 reads operational (Healthy) | -| docs/4.usage/1.overview.md | Down from 20% over 5 minutes | `a-fifth-of-the-calls-failing-is-down`; `nineteen-percent-failing-is-degraded-not-down`; `down-reads-the-last-five-minutes-and-not-the-last-fifteen`; `errors-older-than-five-minutes-do-not-make-the-api-down` | 20 in 100 reads down, 19 in 100 reads degraded; 10 failures in the last 5 minutes read Down while the 15-minute rate is 8.3%; 40 failures 10 minutes ago read Degraded at 28.6% over 15 minutes | -| docs/4.usage/1.overview.md | The four signals: 5xx rate, p95 latency, traffic, 4xx rate | verdict journeys | `the 5xx rate` (API); the hero text names `5xx · 15 min` only in the idle case | -| src/services/health-rules.ts (TSDoc) | A rate is only read over 20 calls or more | `nineteen-failing-calls-are-too-few-to-judge` | 19 failing calls read operational | -| src/services/health-rules.ts (TSDoc) | No call reads No traffic | `with-no-traffic-the-verdict-is-idle` | `the hero` reads `No traffic` | -| docs/4.usage/1.overview.md | A sentence names the routes above the thresholds; View server errors opens the Request logs narrowed | `the-blocks-rank-the-routes-by-what-is-wrong-with-them` | `1 route failing 1 slow route (≥ 50 ms)`, `View 25 server errors`, `a row opens the logs on the route's 5xx` | -| docs/4.usage/1.overview.md | Needs attention lists failing (5xx), slow (p95 at or above the threshold) and noisy (many 4xx) routes with their main error | same | `attention rows and states, most urgent first`, `the failing route's facts`, `the slow route's p95 and average`, `the noisy route's client error rate`, page text per row | -| docs/4.usage/1.overview.md | Slowest routes ranked by average latency with p95, max and call count | same | `slowest routes start with the slowest`, `slowest routes list the four routes`, page text `p95 81 ms · max 81 ms · 25 calls` | -| docs/4.usage/1.overview.md | Error share is the share of 4xx and 5xx over the period | same | `the error share is 50 of 105 calls` | -| docs/4.usage/1.overview.md | Traffic & errors: calls over time with errors | same | `the traffic block counts 105 calls` | -| docs/4.usage/1.overview.md | Responses by class: calls per status class | same | `the status classes (2xx, 4xx, 5xx)` values and shares | -| docs/4.usage/1.overview.md | The health verdict and Needs attention judge the last 24 hours whatever the period | `a-route-is-flagged-at-the-documented-edges-whatever-the-period` | traffic seeded 3 hours ago is listed in Needs attention on the 1H period while the last hour holds only the 83 fresh calls and the last 24 hours 103 | -| docs/4.usage/1.overview.md | Every route is a link into Routes; a request opens in a drawer; an incident opens the logs on its range (`?since=&until=`) | `the-blocks-rank-the-routes-by-what-is-wrong-with-them` (rows link to the logs narrowed by route and tab), the Overview's route links are `GET /fx/...` anchors; the incident range link is Not driven: it needs an ended incident, which takes 15 minutes of quiet | -| docs/4.usage/1.overview.md | The page toolbar is shared: scope chip, updated ago, Live/Pause, period, comparison | `the-period-and-the-comparison-are-kept-in-the-url-and-shared-by-the-pages` | `the default`, `7D`, `1H`, `30D` | -| docs/4.usage/1.overview.md | The period selector 1H, 24H, 7D, 30D; the URL keeps `?api.period=` | same | `the URL names the period` for each preset | -| docs/4.usage/1.overview.md | vs previous period (default) and No comparison drop the dashed line, delta and "vs" figure | same | `the API honours the comparison`: window comparison, one more series, none after No comparison; `No comparison` menu URL `api.compare=none` | -| docs/4.usage/1.overview.md | A comparison reaching beyond the retention compares with nothing rather than zeros | `a-comparison-beyond-the-kept-statistics-compares-with-nothing` | kept 90 and 60 days: `previousAvailable` true on 30D; kept 30 days: false on 30D and true on 7D; Routes reads `No previous period` against `none over the previous period` | -| docs/4.usage/1.overview.md | The period is kept in the URL and, without one, a page opens on the last choice made on any of the three pages | same | `the Request logs open on the last choice`, `Routes open on the last choice` | -| docs/4.usage/1.overview.md | The scope chip shows the routes the console watches | `the-scope-decides-which-routes-and-requests-every-page-watches` (settings) | `the scope chip` | -| docs/4.usage/1.overview.md | Live: the page follows new requests; each block reads at most every 5 s (logs), 10 s (Overview), 15 s (Routes) | Not driven: read intervals are not observable without a clock; the realtime announcement is observed by `pause-holds-the-table-and-counts-what-was-missed` | -| docs/4.usage/1.overview.md | Paused: nothing is read; the toggle says what was missed; tables offer "N new requests · M in 5xx · Show"; resuming reads once | `pause-holds-the-table-and-counts-what-was-missed` (logs) | `paused`, `shown` | -| docs/4.usage/1.overview.md | The page pauses by itself while the tab is hidden and while typing in the Tester; a table holds its rows while one is open | Not driven: visibility and typing focus are not set by the harness | -| docs/4.usage/1.overview.md | `?live=0` opens a page paused | `the-period-and-the-comparison-are-kept-in-the-url-and-shared-by-the-pages` | `?live=0` | -| docs/4.usage/1.overview.md | `L` toggles Live/Pause | `l-switches-the-page-between-live-and-pause` | `L pauses` (`Pause` is on), `the paused page counts what it did not read` (`Paused · 3 new requests · 1 in 5xx`), the Routes page and the Request logs page open paused, `L makes it live again` and the Overview is live | -| docs/4.usage/1.overview.md | Needs attention flags a route at 5% client errors from 20 calls, a slow route, and not fewer | `a-route-is-flagged-at-the-documented-edges-whatever-the-period` | 19 calls all 404 not flagged; 20 calls with 1 client error flagged at 5%; 25 calls with 1 (4%) not flagged; 19 slow calls not flagged | -| docs/4.usage/1.overview.md | The hero shows the 5xx rate, p95 latency, traffic in requests per minute and the 4xx rate over 15 minutes, with the slow threshold | `a-route-is-flagged-at-the-documented-edges-whatever-the-period` | `0%`, `25.3%`, `5.5 req/min`, `Slow from 50 ms` for 83 calls | -| docs/2.installation.md | `/modules/api` redirects to the Overview; the menu lists Monitor, Explore and Configure | `the-module-path-redirects-to-the-overview` | the path after the redirect, the heading, the four links and their sections | -| docs/4.usage/1.overview.md (Health verdict) | The hero shows the verdict, how long it has held and when it was checked | `the-hero-says-how-long-the-verdict-has-held-and-when-it-was-checked` | `Down`, `for 3 min`, `checked HH:MM:SS` within two minutes of now, the tooltip `Down since at HH:MM` equal to the `datetime` of the verdict's start, and `durationMs` between 2.5 and 4 minutes | -| docs/4.usage/1.overview.md (Period and scope) | A link asking for a year back, or for a comparison the page does not know, compares with nothing | `a-comparison-the-page-does-not-know-compares-with-nothing` | `previous-year`, `year` and an empty name give comparison `none`, no previous period and no compared line; `previous-period` gives one. The page's own selector turns an unknown `?api.compare=` into the default (done by the DMS selector, not asserted here) | -| docs/4.usage/1.overview.md (Blocks) | Slowest routes, Traffic & errors, Error share and Responses by class compare each figure with the period before | `every-figure-compared-with-the-period-before-says-its-change-and-its-value` | 12 calls before and 14 now: `TRAFFIC & ERRORS 14 +16.7% vs 12`, `ERROR SHARE 14.3% vs 0.0%`, the slowest route `+100% vs. 50 ms previous period` (average 100 against 50, not the max 90), `+0% vs. 5 ms`, `none over the previous period`, the class shares | diff --git a/.agents/skills/verify-dms-api/coverage/package.md b/.agents/skills/verify-dms-api/coverage/package.md deleted file mode 100644 index 7af9a51..0000000 --- a/.agents/skills/verify-dms-api/coverage/package.md +++ /dev/null @@ -1,14 +0,0 @@ -# Coverage: package - -| Source | Documented behaviour | Journey | Check | -|---|---|---|---| -| docs/2.installation.md (Add the module) | The `dms-api` entry installs `@antelopejs/dms-api` from a version range | `the-ranges-and-the-skill-match-what-the-docs-name` | `this version is inside the range the installation docs show` | -| docs/1.introduction.md (Requirements) | The renderer range declared in `engines["@antelopejs/dms-frontend"]` of the Vue layer | same | `the renderer installed is inside the Vue layer's engines range` | -| README.md (Compatibility) | The compatibility table lists the interface dependencies | same | `the README table lists each interface dependency` | -| README.md (Documentation) and docs links | Every console link points at a page that exists | `the-docs-links-and-the-two-locales-are-complete` | `every page exists`, `no console link points at a missing page` | -| README.md | The package ships the `dms-api` skill declared under `antelopeJs.skills` | `the-tarball-holds-what-the-manifest-names`; `the-ranges-and-the-skill-match-what-the-docs-name` | `the skills folder is declared`, `the skill is packed`, the skill's frontmatter and nodes, the cases file | -| docs/2.installation.md (Restart the backend) | The module registers its Vue frontend module when it starts | `the-tarball-holds-what-the-manifest-names` | `the frontend module is declared`, `the frontend module is packed`; the registration at start is exercised by every browser journey | -| package.json | `dist` entry, the shipped folders, no sources, tests or playground | same | `main`, `the shipped folders`, `nothing else but the manifest, licence and readme`, `no source, test or playground file is packed` | -| frontend-vue/i18n | English and French locale files hold the same keys | `the-docs-links-and-the-two-locales-are-complete` | both directions | -| docs/2.installation.md (Try it with traffic) | The playground sends demo traffic | Not driven: `pnpm --dir playground traffic` is developer tooling | -| docs/2.installation.md (Open the console) | `/modules/api` redirects to the Overview | `the-module-path-redirects-to-the-overview` (overview) | the path after the redirect is `/modules/api/overview` | diff --git a/.agents/skills/verify-dms-api/coverage/retention.md b/.agents/skills/verify-dms-api/coverage/retention.md deleted file mode 100644 index f1d0673..0000000 --- a/.agents/skills/verify-dms-api/coverage/retention.md +++ /dev/null @@ -1,6 +0,0 @@ -# Coverage: retention - -| Source | Documented behaviour | Journey | Check | -|---|---|---|---| -| docs/4.usage/4.settings.md (Retention) | Data is pruned every hour | `the-hourly-prune-deletes-what-the-retention-passed` | logs older than the log retention and statistics days older than the statistics retention are deleted at the turn of the hour, newer ones are kept | -| docs/4.usage/4.settings.md (Retention) | Lowering a retention shows how much the next prune deletes and asks you to confirm it | `lowering-a-retention-tells-what-the-next-prune-deletes`; `lowering-a-retention-asks-before-it-deletes` | the impact route's exact days and requests for 30, 60, 90 and 366 days, refusals of an unknown field, 0 and 367; the sentence under the field, the `Delete stored data?` dialog with `30 → 7 days` and `≈ 3 requests`, Cancel keeps 30, Save and delete writes 7 | diff --git a/.agents/skills/verify-dms-api/coverage/routes.md b/.agents/skills/verify-dms-api/coverage/routes.md deleted file mode 100644 index fa6a058..0000000 --- a/.agents/skills/verify-dms-api/coverage/routes.md +++ /dev/null @@ -1,27 +0,0 @@ -# Coverage: routes - -| Source | Documented behaviour | Journey | Check | -|---|---|---|---| -| docs/4.usage/3.routes.md (intro) | The page lists every registered route on the left and opens one on the right; the URL names the route and the open tab | `a-route-opens-with-its-header-and-the-url-names-it` | `the named route and tab`, `the detail` | -| docs/4.usage/3.routes.md (intro) | Opened without a route, the page lands on the last route opened in this browser session, else on the route needing attention first | same | `no route named: the one needing attention` (the failing route), `the last route opened` | -| docs/4.usage/3.routes.md (Find a route) | Routes grouped by path prefix with their call count and a health dot | `the-tree-groups-routes-by-folder-and-the-filters-narrow-it` | `the list` (counts and states), `the tree` (treeitem names with count and Failing/Healthy/No traffic) | -| docs/4.usage/3.routes.md (Find a route) | Filter by path or handler, by method, Only routes needing attention, Hide routes without traffic | same | `the path filter`, `the handler filter`, `the method filter`, `only routes needing attention`, `hide routes without traffic` (each with the exact count of routes left) | -| docs/4.usage/3.routes.md (Find a route) | `/` opens the filter | `slash-opens-the-route-filter` | the filter is folded away, then `the slash key` shows it with the focus in it, and `typing without a click` narrows the tree (`3 of 23 routes · 1 folder`) | -| docs/4.usage/3.routes.md (Find a route) | The header: method and path, controller and handler, authenticated or not, project or module code, first seen | `a-route-opens-with-its-header-and-the-url-names-it`; `a-route-from-an-installed-module-names-its-module` | `FixtureController.ok Auth unknown Project code`; `the first-seen date is today`; a module route reads `PublicOnboardingController.getInformations Auth unknown Module dms` | -| docs/4.usage/3.routes.md (Find a route) | Requests opens the Request logs on this route; Copy cURL copies an example call | same; `copy-curl-on-a-route-copies-an-example-call` | `Requests` (URL route). Copy cURL: the clipboard holds a `curl -X POST` command with the API origin, `/fx/orders/shop1/lines?limit=5`, the content type and the example body; the toast `cURL copied` | -| docs/4.usage/3.routes.md (Statistics) | Requests, average latency and p95, error rate, slowest call; error rate by status and response time over time; top errors; recent calls | `the-statistics-tab-adds-up-the-period` | the API reads and the page text `REQUESTS 18`, `ERROR RATE 22.2% 4 × 4xx · 0 × 5xx`, `SLOWEST CALL ... slow above 50 ms`, `TOP ERRORS`, `404 · no such item`, `RECENT REQUESTS` | -| docs/4.usage/3.routes.md (Statistics) | Under the comparison each figure says its change; the error rate chart draws the compared period dashed; each top error says how often it occurred then; No comparison shows the period alone | Not driven for the route page: a compared period needs seeded history and the figures' wording; the Overview's comparison is asserted in feature overview | -| docs/4.usage/3.routes.md (Documentation) | The contract is inferred from the handler's code and the last 7 days of captured requests (Tester calls left out) | `the-documentation-tab-is-inferred-from-the-code-and-the-traffic`; `the-contract-reads-seven-days-of-real-calls-and-never-the-testers` | a call 6 days old documents its field, one 8 days old does not (total 2, fields quantity, recent, sku, status 201 x2); after a Tester call the totals, fields, statuses, query parameters and example are identical | -| docs/4.usage/3.routes.md (Documentation) | An example request in cURL or fetch | same | the exact `curl -X POST '/fx/orders/shop1/lines?limit=5'` text, the `fetch` radio | -| docs/4.usage/3.routes.md (Documentation) | Authentication, path, query and body parameters with examples, and responses; what was never called does not show | same | `the parameters` (name, location, required, example), `the body fields`, `the statuses seen`, `a route never called has no statuses, fields or example` | -| docs/4.usage/3.routes.md (note) | Authentication is detected from the guards before the handler using `authMiddlewareNamePatterns` and `authMiddlewareCallbacks`; a check inside the handler reads Auth unknown | `authentication-is-read-from-the-guards-before-the-handler` | `auth_check is a guard`, `checkTicket matches no default pattern`, `an inline check does not show`, `authMiddlewareCallbacks names checkTicket`, `replacing the patterns drops auth_check` | -| docs/6.faq.md (A route reads Auth unknown) | No guard found and no 401 seen reads unknown; a 401 seen reads probable | same | `a 401 seen turns unknown into probable` | -| docs/5.extending.md (Own routes and module routes) | The console sorts each route by where its controller comes from; the scope picks which ones the pages watch | `the-scope-decides-which-routes-and-requests-every-page-watches` (settings) | own lists the project's routes only, modules the installed modules', all both | -| docs/5.extending.md (Make the documentation tab accurate) | Parameters and bodies come from captured client requests; Tester calls cannot populate missing examples | `the-documentation-tab-is-inferred-from-the-code-and-the-traffic`; `a-tester-call-is-logged-and-marked-but-never-counted` | the contract counts only the one real call; the Tester's call leaves the route idle. A Tester call that must not add an example: Not driven | -| docs/5.extending.md (Link to the console) | `/modules/api/routes?route= &tab=statistics|documentation|tester` opens a route on a tab | `a-route-opens-with-its-header-and-the-url-names-it`; the statistics, documentation and tester journeys | each opens its tab through the URL | -| docs/6.faq.md (cURL snippets point to the wrong host) | The snippets use the DMS `apiBaseUrl` | `a-route-opens-with-its-header-and-the-url-names-it`, `the-documentation-tab-is-inferred-from-the-code-and-the-traffic` | `the snippets use the DMS apiBaseUrl`; the cURL text starts with the detail's `apiOrigin`. Setting `apiBaseUrl` to another value is Not driven | -| docs/3.configuration.md (Public API origin) | `apiBaseUrl` is read with `GetApiBaseUrl()` | same | see above | -| docs/4.usage/3.routes.md (Statistics) | The statistics of a route called less than the health minimum (20) | `the-tree-groups-routes-by-folder-and-the-filters-narrow-it` | `a quiet route` reads healthy with 3 calls | -| docs/4.usage/3.routes.md (Find a route) | The tree shows each route's call count before any filter | `the-tree-groups-routes-by-folder-and-the-filters-narrow-it` | the tree items `GET /fx/boom 25`, `GET /fx/ok 3`, `GET /fx/items/:id 1`, `GET /fx/blob 0 No traffic`, `DEL /fx/items/:id 0 No traffic` | -| docs/4.usage/3.routes.md (Statistics) | Under the comparison each figure says its change and its value then, the error rate in points; each top error says how often it occurred then | `the-route-statistics-compare-in-points-with-the-period-before` | 10 calls with 1 client error before, 10 with 3 now: `REQUESTS 10 +0% vs. 10`, `ERROR RATE 30% ... +20 pt vs. 10% previous period`, the top error `+200% vs. 1 previous period` | -| docs/4.usage/3.routes.md (Documentation) | A field missing from some captured calls is not required | `the-contract-reads-seven-days-of-real-calls-and-never-the-testers` | the flags `[["quantity", false], ["recent", false], ["sku", true]]` | diff --git a/.agents/skills/verify-dms-api/coverage/settings.md b/.agents/skills/verify-dms-api/coverage/settings.md deleted file mode 100644 index c30330a..0000000 --- a/.agents/skills/verify-dms-api/coverage/settings.md +++ /dev/null @@ -1,25 +0,0 @@ -# Coverage: settings - -| Source | Documented behaviour | Journey | Check | -|---|---|---|---| -| docs/4.usage/4.settings.md (intro) | The settings page holds the runtime settings; changes apply immediately without a restart and override the module configuration | `use-default-returns-a-field-to-the-module-option` | `the override wins at once`, `the override survives a restart` | -| docs/4.usage/4.settings.md (Route visibility) | Scope: Own routes, Module routes, All routes; applies to Overview, Routes and Request logs | `the-scope-decides-which-routes-and-requests-every-page-watches` | the routes and the logged paths per scope; `the scope chip` | -| docs/4.usage/4.settings.md (Route visibility) | Scope does not turn internal traffic into application traffic | `the-consoles-own-and-the-dms-traffic-is-never-captured` (capture) | under All routes | -| docs/4.usage/4.settings.md (Route visibility) | The three scope descriptions | `the-form-shows-the-documented-defaults` | `Your project's code only`, `Installed modules only`, `No filtering` | -| docs/4.usage/4.settings.md (Retention) | Request logs 1 to 366 days; statistics 30, 60 or 90 days | `every-bound-of-the-form-is-enforced-on-its-edge` | 0, 1, 366, 367, 1.5; 45, 30, 60, 90, 120 | -| docs/4.usage/4.settings.md (Capture and privacy) | Max body size 0 to 10,240 KB; 0 turns body capture off | `every-bound-of-the-form-is-enforced-on-its-edge`; `bodies-above-the-cap-are-stored-truncated-and-flagged` | -1, 0, 10240, 10241; the cap and 0 | -| docs/4.usage/4.settings.md (Capture and privacy) | Captured headers: only these are stored; secret-looking never stored | `only-the-listed-headers-are-stored-and-secret-ones-never`; `every-bound-of-the-form-is-enforced-on-its-edge` | 50 headers accepted, 51 refused; authorization, cookie, set-cookie, x-api-key, proxy-authorization, X-Authorization and the Tester's source header refused with 400, three ordinary headers accepted; never stored when sent | -| docs/4.usage/4.settings.md (Capture and privacy) | Always redacted: the fixed list, not editable | `the-form-shows-the-documented-defaults`; `values-under-secret-looking-keys-are-redacted-before-storage` | the list of 23 words; `Not editable` | -| docs/4.usage/4.settings.md (Health thresholds) | Slow request 50 to 600,000 ms in steps of 50; requests at or above are flagged slow | `every-bound-of-the-form-is-enforced-on-its-edge`; `the-tabs-the-filters-and-the-search-narrow-the-list` | 49, 50, 75, 100, 600000, 600050; the Slow filter follows the value | -| docs/4.usage/4.settings.md (Health thresholds) | Error rate warning and Down rate are fixed and shown for reference | `the-form-shows-the-documented-defaults` | `5% Fixed in this version`, `20% Fixed in this version`, `errorRateWarning` and `downErrorRate` in the form | -| docs/4.usage/4.settings.md (tip) | Each field shows its module default; Use default removes the override | `use-default-returns-a-field-to-the-module-option` | `Use default follows the module option again`; the button on the page: `the-use-default-button-removes-an-override-on-the-page` (`Use default` puts the module option, 500, in the field and says `Changed · was 250` while the override is still stored, `Save changes` makes the console read 500, a reload shows no `Use default`, and under another module option, 700, the console and the field follow it) | -| docs/3.configuration.md (Options table) | Defaults: 90 days, 30 days, 1000 ms, 64 KB, the eight headers, the three auth patterns | `the-form-shows-the-documented-defaults`; `authentication-is-read-from-the-guards-before-the-handler` | the values of the form; `auth_check` matches `^auth_` | -| docs/3.configuration.md (Options table) | Module options set the values in force | `use-default-returns-a-field-to-the-module-option` | slow 500 and body cap 2 KB read from `config` | -| docs/3.configuration.md (warning) | The module refuses to start with a value the settings page would refuse | `the-module-refuses-to-start-with-a-value-the-form-would-refuse` | six refused options stop the module with the reason; valid options start it | -| docs/3.configuration.md (Settings page overrides) | Retention values have no Use default button; an empty list of captured headers keeps an explicit override | `retention-fields-have-no-use-default-but-the-others-do`; `only-the-listed-headers-are-stored-and-secret-ones-never` | with four fields overridden exactly two `Use default` buttons show (body size, slow threshold), none beside the retentions; `the override stays explicit` | -| docs/3.configuration.md (Settings page overrides) | The route scope is a setting only; it has no configuration option | Not driven: an unknown option key is not refused or ignored observably | -| docs/6.faq.md (console shows no traffic) | Own routes by default; module routes need Module routes or All routes | `the-scope-decides-which-routes-and-requests-every-page-watches` | the scope table | -| docs/6.faq.md (30D comparison unavailable) | With 30 days kept, 30D has no period before it | `a-comparison-beyond-the-kept-statistics-compares-with-nothing` | `previousAvailable` false at 30 days, true at 60 and 90 | -| docs/6.faq.md (invalid configuration) | The error lists each refused value | `the-module-refuses-to-start-with-a-value-the-form-would-refuse` | `the module stops and says so` (the log line `[dms-api] invalid configuration`) | -| docs/6.faq.md (Upgrading from 0.1) | Settings return the error-rate thresholds as ratios (`0.05`) and the health action returns `failingRoutes` | `the-form-shows-the-documented-defaults` | `error rate warning` 0.05, `down rate` 0.2. Dropping the 0.1 tables is Not driven | -| docs/4.usage/4.settings.md (Route visibility) | The scope is a setting that survives a restart | `the-scope-decides-which-routes-and-requests-every-page-watches` | after `restartBackend` the scope still reads `all` | diff --git a/.agents/skills/verify-dms-api/coverage/smoke.md b/.agents/skills/verify-dms-api/coverage/smoke.md deleted file mode 100644 index 3ab1953..0000000 --- a/.agents/skills/verify-dms-api/coverage/smoke.md +++ /dev/null @@ -1,9 +0,0 @@ -# Coverage of `smoke` - -The journey every verdict runs. The other features carry the detail. - -| Source | Documented behaviour | Catching journey and check | -|---|---|---| -| docs/1.introduction.md | The module captures the requests the project's API answers and turns them into a health verdict and request logs under Modules › API | `traffic-shows-in-the-overview-and-the-request-logs`, checks `26 requests are captured`, `the verdict is degraded`, `the Overview` and `the Request logs` | -| docs/1.introduction.md | The Overview answers whether the API is healthy and the hero shows the verdict | same journey, `the Overview`: `Degraded`, `View 1 server error` | -| docs/1.introduction.md | Request logs list every captured request, a request opens with its error | same journey, `the request drawer` | diff --git a/.agents/skills/verify-dms-api/coverage/tester.md b/.agents/skills/verify-dms-api/coverage/tester.md deleted file mode 100644 index c076968..0000000 --- a/.agents/skills/verify-dms-api/coverage/tester.md +++ /dev/null @@ -1,19 +0,0 @@ -# Coverage: tester - -| Source | Documented behaviour | Journey | Check | -|---|---|---|---| -| docs/4.usage/3.routes.md (Tester) | The Tester calls the route through the frontend server; Send | `a-tester-call-is-logged-and-marked-but-never-counted` | `the response` (the page shows the route's 500 and its message) | -| docs/4.usage/3.routes.md (Tester) | Fill the path parameters, headers, query and body, then Send (Ctrl+Enter); Copy cURL | `the-tester-sends-the-form-and-keeps-twenty-five-calls` | a header added in the form reaches the handler (`"extra": "from-the-form"`); Ctrl Enter sends. The query and body editors and Copy cURL: Not driven (clipboard) | -| docs/4.usage/3.routes.md (Tester) | Send with my session sends the call as you; off, no credentials are sent; a header named Authorization replaces your session | `the-tester-sends-the-form-and-keeps-twenty-five-calls` | off: the handler sees no authorization and the note reads `No credentials are sent`; on: `"authorization": "present"`, `Your session token is sent`. | -| docs/4.usage/3.routes.md (Tester) | `x-request-id` and `x-antelopejs-api-source` are added so the call can be found in the logs | `a-tester-call-is-logged-and-marked-but-never-counted`, `the-contract-reads-seven-days-of-real-calls-and-never-the-testers` | `it carries an x-request-id`, `the Tester's read finds it` (by request id); a call under `x-antelopejs-api-source` is marked as the Tester's | -| docs/4.usage/3.routes.md (Tester) | Tester calls are logged and marked, but left out of the statistics and the health | same | `the call is marked as the Tester's`, `the route's statistics hold no request`, `the health counted nothing`, `nothing needs attention`, `the route stays idle` | -| docs/4.usage/3.routes.md (note) | The module serves the Tester's forwarding route itself, `POST /api/_dms-api/tester`, from its `dms.server.ts` | `a-tester-call-is-logged-and-marked-but-never-counted` | the page's Send reaches the route through it. Direct calls to it: `the-forwarding-route-refuses-unsafe-paths-and-never-forwards-blocked-headers` (401 without a session, 403 to a member and from another origin, 400 for eleven unsafe paths and five invalid calls, no `Host`, `Origin`, `Referer`, `Forwarded`, `Via`, `X-Forwarded-For`, `X-DMS-*` or `X-Method-Override` header reaches the API while another one does, 200 for a 60 KB answer and 502 for a 70 KB one). The 30 s timeout of `frontend-vue/server/tester.ts` is Not driven: it would hold a journey for 30 s | -| docs/3.configuration.md (options) | `testerSourceSecret`: the key the tokens are signed with; random per instance; set the same value on every instance | `a-secret-keeps-the-testers-token-valid-across-restarts` | `a token under the secret` survives a restart and still marks the call; without the secret the same token no longer does | -| src/services/tester-source.ts (TSDoc) | The token is valid 15 minutes | same | `valid 15 minutes`, `the header name` | -| docs/6.faq.md (Tester calls rejected on another instance) | Behind several instances the same secret lets every instance accept the others' tokens | Not driven: one backend per run; the single-instance restart stands for it | -| docs/4.usage/3.routes.md (warning) | The Tester sends real requests, not simulations | `a-tester-call-is-logged-and-marked-but-never-counted` | the call reaches the handler (`/fx/boom` throws and is logged) | -| docs/4.usage/3.routes.md (Tester) | The History keeps your last 25 calls in this browser (kept after a reload, in another tab, per route) | `the-tester-sends-the-form-and-keeps-twenty-five-calls` | after 28 sends: 25 entries, 25 again after a reload, 25 in a second tab of the same browser, none on another route | -| docs/4.usage/3.routes.md (Tester) | Click a History entry to restore it | `a-history-entry-restores-its-call-and-a-typed-authorization-beats-the-session` | the older entry restores its header value (`one`, not `two`) and its response (`"extra": "one"`) | -| docs/4.usage/3.routes.md (Tester) | A header named Authorization replaces your session | same | with Send with my session on, a typed `Bearer fixture-token` reaches the handler (`"typed": true`); removing it, only the session's token does (`"typed": false`, `"authorization": "present"`) | -| docs/4.usage/3.routes.md (Tester) | Headers for all routes are sent to every route and kept in this browser; credentials only until the page reloads | `headers-for-all-routes-are-kept-in-the-browser-but-credentials-are-not` | `x-extra: for-all` and a typed Authorization both reach the route; after a reload only `x-extra` does; another route shows the kept header | -| docs/4.usage/3.routes.md (Tester) | A request replayed from the Request logs restores what was captured; redacted values and credentials must be filled by hand; a body cut at capture is replayed as text | `a-replayed-call-needs-its-credentials-and-redacted-values-by-hand` | no Authorization comes back, the content type does, the password reads `[REDACTED]`, the query is restored, a body cut at 1 KB opens as Text | diff --git a/.agents/skills/verify-dms-api/features/README.md b/.agents/skills/verify-dms-api/features/README.md deleted file mode 100644 index bfc27dd..0000000 --- a/.agents/skills/verify-dms-api/features/README.md +++ /dev/null @@ -1,18 +0,0 @@ -# Feature map - -One file per feature. `covers:` lists the source globs it owns, `docs:` the pages a verdict judges, `e2e/journeys/.mjs` its journeys, and `coverage/.md` the documented behaviours and the check that pins each. `dms-control map` checks that every user-facing file is covered and that every feature has its journeys and existing docs pages. - -| Feature | What the user does | Journeys | -|---|---|---| -| [smoke](smoke.md) | The fixed journey every verdict runs: traffic on the project's routes shows as a verdict and as request logs. | traffic-shows-in-the-overview-and-the-request-logs | -| [capture](capture.md) | What the module records of each request: facts, errors, allow-listed headers, redacted and size-capped bodies, and no internal traffic. | a-request-is-captured-with-its-facts, a-thrown-error-keeps-its-message-and-its-stack, the-consoles-own-and-the-dms-traffic-is-never-captured, only-the-listed-headers-are-stored-and-secret-ones-never, values-under-secret-looking-keys-are-redacted-before-storage, bodies-above-the-cap-are-stored-truncated-and-flagged, a-key-is-secret-by-the-words-it-is-made-of | -| [overview](overview.md) | The Overview: the verdict ladder, the attention list, slowest routes, error share, traffic, period and comparison. | with-no-traffic-the-verdict-is-idle, nineteen-failing-calls-are-too-few-to-judge, one-failing-call-in-a-hundred-is-degraded, one-failing-call-in-a-hundred-and-one-is-operational, a-fifth-of-the-calls-failing-is-down, nineteen-percent-failing-is-degraded-not-down, the-blocks-rank-the-routes-by-what-is-wrong-with-them, the-period-and-the-comparison-are-kept-in-the-url-and-shared-by-the-pages, l-switches-the-page-between-live-and-pause | -| [logs](logs.md) | The Request logs: tabs, filters, search, sort, paging, the histogram, the drawer and live mode. | the-tabs-the-filters-and-the-search-narrow-the-list, the-list-is-newest-first-sorts-and-pages, pause-holds-the-table-and-counts-what-was-missed, the-histogram-bars-follow-the-period, a-request-opens-in-a-drawer-that-steps-through-the-list, slash-opens-the-request-search-and-question-mark-lists-the-shortcuts, copy-curl-copies-the-open-request-as-a-command, dragging-the-drawers-left-edge-widens-it-and-it-opens-again-at-that-width, an-open-row-or-an-active-search-holds-the-table-and-says-why | -| [routes](routes.md) | The Routes page: the tree and its filters, a route's header, Statistics, inferred Documentation and authentication. | the-tree-groups-routes-by-folder-and-the-filters-narrow-it, a-route-opens-with-its-header-and-the-url-names-it, the-statistics-tab-adds-up-the-period, the-documentation-tab-is-inferred-from-the-code-and-the-traffic, authentication-is-read-from-the-guards-before-the-handler, slash-opens-the-route-filter, copy-curl-on-a-route-copies-an-example-call | -| [tester](tester.md) | The Tester: real calls logged and marked apart from the traffic, and the token that marks them. | a-tester-call-is-logged-and-marked-but-never-counted, a-secret-keeps-the-testers-token-valid-across-restarts, the-forwarding-route-refuses-unsafe-paths-and-never-forwards-blocked-headers | -| [settings](settings.md) | The API settings page and the module options: defaults, bounds, Use default, refusal at start, scope, retention and the hourly prune. | the-form-shows-the-documented-defaults, every-bound-of-the-form-is-enforced-on-its-edge, use-default-returns-a-field-to-the-module-option, the-module-refuses-to-start-with-a-value-the-form-would-refuse, the-scope-decides-which-routes-and-requests-every-page-watches, the-use-default-button-removes-an-override-on-the-page | -| [retention](retention.md) | Retention: what the next prune deletes, the confirmation before a lower retention, and the hourly prune. | lowering-a-retention-asks-before-it-deletes | -| [access](access.md) | Who may call the console: a session for every route, and the owner only. | every-console-route-needs-a-session-and-the-block-it-serves, the-console-is-the-owners-and-a-role-holding-a-block-is-refused, a-member-without-the-modules-permissions-is-sent-to-their-settings, a-panel-opened-from-one-table-reads-only-a-request-that-table-can-list | -| [package](package.md) | What a project installs: the tarball, the ranges, the skill, the docs links and the locales. | the-tarball-holds-what-the-manifest-names, the-ranges-and-the-skill-match-what-the-docs-name, the-docs-links-and-the-two-locales-are-complete | - -The smoke journey runs on every verdict. diff --git a/.agents/skills/verify-dms-api/features/access.md b/.agents/skills/verify-dms-api/features/access.md deleted file mode 100644 index 20bd9e0..0000000 --- a/.agents/skills/verify-dms-api/features/access.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -covers: - - src/guards.ts - - src/routes/index.ts - - src/routes/tester.ts -docs: - - docs/5.extending.md ---- - -# Access - -Who may call the console: a session for every route, and the platform owner only, since the DMS grants a module page's permissions to the owner alone. - -## Sub-features - -- `every-console-route-needs-a-session-and-the-block-it-serves` -- `the-console-is-the-owners-and-a-role-holding-a-block-is-refused` -- `a-member-without-the-modules-permissions-is-sent-to-their-settings` -- `a-panel-opened-from-one-table-reads-only-a-request-that-table-can-list` - -## How to get to it (user POV) - -- The owner opens Modules › API; a member with any role is refused. - -## Driving it with dms-control - -```bash -dms-control journey "$RUN" access -``` - -## Gotchas - -- The permission ids are read from the refusals, so the journeys follow the module's own block ids. diff --git a/.agents/skills/verify-dms-api/features/automation.md b/.agents/skills/verify-dms-api/features/automation.md deleted file mode 100644 index c1a42ba..0000000 --- a/.agents/skills/verify-dms-api/features/automation.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -covers: - - src/automation/** -docs: - - docs/5.extending.md ---- - -# Automation - -The three nodes the module registers when `@antelopejs/dms-automation` is loaded: the Route unhealthy trigger, the Get API health action and the Query request logs action. Without the automation module the registration is a silent no-op. - -## Sub-features - -- `without-the-automation-module-the-registration-is-a-silent-no-op` -- `the-module-registers-its-three-nodes-with-their-documented-inputs` -- `get-api-health-restricts-its-breakdown-to-the-last-days` -- `query-request-logs-pages-caps-and-filters` -- `query-request-logs-next-cursor-reads-the-next-page` -- `route-unhealthy-fires-on-the-flags-it-watches-and-never-faster-than-ten-seconds` - -## How to get to it (user POV) - -- A procedure in Automation using `api.route-unhealthy`, `api.get-api-health` or `api.query-request-logs`. - -## Driving it with dms-control - -```bash -dms-control journey "$RUN" automation -``` - -## Gotchas - -- The playground's fixture module stands in for the automation provider when `VERIFY_API_AUTOMATION=1` (a journey restarts the backend with it): it keeps the node types the module registers and runs `execute` and `activate` through `/verify-api/nodes`. The automation runtime itself is not loaded. diff --git a/.agents/skills/verify-dms-api/features/capture.md b/.agents/skills/verify-dms-api/features/capture.md deleted file mode 100644 index 9f24e29..0000000 --- a/.agents/skills/verify-dms-api/features/capture.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -covers: - - src/services/request-log/** - - src/db/** - - src/realtime.ts - - src/services/statistics-write.ts - - src/services/statistics-aggregate.ts - - src/services/statistics-utils.ts - - src/services/aggregate-cache.ts - - src/services/traffic-samples.ts - - src/memo.ts - - src/services/index.ts - - src/services/zod-json.ts -docs: - - docs/1.introduction.md - - docs/3.configuration.md ---- - -# Capture - -What the module records of the project's API traffic: each request with its route, timing, allow-listed headers and size-capped, redacted bodies; internal traffic never. - -## Sub-features - -- `a-request-is-captured-with-its-facts` -- `a-thrown-error-keeps-its-message-and-its-stack` -- `the-consoles-own-and-the-dms-traffic-is-never-captured` -- `only-the-listed-headers-are-stored-and-secret-ones-never` -- `values-under-secret-looking-keys-are-redacted-before-storage` -- `bodies-above-the-cap-are-stored-truncated-and-flagged` -- `secrets-and-card-numbers-are-redacted-wherever-they-sit` -- `a-key-is-secret-by-the-words-it-is-made-of` - -## How to get to it (user POV) - -- Modules › API › Request logs, a request's drawer; API settings › Capture & privacy. - -## Driving it with dms-control - -```bash -dms-control journey "$RUN" capture -``` - -## Gotchas - -- Statistics and health are written behind the response: journeys wait with `settled`. diff --git a/.agents/skills/verify-dms-api/features/logs.md b/.agents/skills/verify-dms-api/features/logs.md deleted file mode 100644 index 1dc304a..0000000 --- a/.agents/skills/verify-dms-api/features/logs.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -covers: - - src/routes/logs.ts - - src/pages/logs.ts - - src/pages/request-table.ts - - src/services/request-log/list.ts - - src/services/request-log/read.ts - - src/services/request-log/access.ts - - src/services/live.ts - - src/services/live-feed.ts - - frontend-vue/app/components/blocks/LogsFilters.vue - - frontend-vue/app/components/blocks/LogsEmptyState.vue - - frontend-vue/app/components/blocks/RequestDetail.vue - - frontend-vue/app/components/blocks/LiveTraffic.vue - - frontend-vue/app/components/internal/ApiBody.vue - - frontend-vue/app/components/internal/ApiJsonTree.vue - - frontend-vue/app/components/internal/ApiKeyValues.vue - - frontend-vue/app/components/internal/ApiStatusBadge.vue - - frontend-vue/app/components/internal/ApiTesterBadge.vue - - frontend-vue/app/components/internal/RequestGeneral.vue - - frontend-vue/app/components/internal/RequestTiming.vue - - frontend-vue/app/utils/logsQuery.ts - - frontend-vue/app/utils/requestDrawer.ts - - frontend-vue/app/utils/search.ts - - frontend-vue/app/utils/http.ts -docs: - - docs/4.usage/2.request-logs.md - - docs/4.usage/1.overview.md ---- - -# Request logs - -The Request logs page: the histogram, the status tabs, the filters, the search, the drawer of one request and the live mode that holds the table. - -## Sub-features - -- `the-tabs-the-filters-and-the-search-narrow-the-list` -- `the-list-is-newest-first-sorts-and-pages` -- `pause-holds-the-table-and-counts-what-was-missed` -- `the-histogram-bars-follow-the-period` -- `the-histogram-counts-past-days-by-class` -- `a-link-names-a-range-with-since-and-until` -- `a-past-range-draws-at-most-120-bars` -- `filters-combine-with-the-status-tab` -- `the-list-sorts-by-duration-both-ways` -- `the-slow-labels-follow-the-threshold-in-seconds-or-milliseconds` -- `counts-are-grouped-and-all-time-compares-nothing` -- `a-request-opens-in-a-drawer-that-steps-through-the-list` -- `slash-opens-the-request-search-and-question-mark-lists-the-shortcuts` -- `copy-curl-copies-the-open-request-as-a-command` -- `dragging-the-drawers-left-edge-widens-it-and-it-opens-again-at-that-width` -- `an-open-row-or-an-active-search-holds-the-table-and-says-why` - -## How to get to it (user POV) - -- Modules › API › Request logs; `?record=` and the links of the Overview open it narrowed. - -## Driving it with dms-control - -```bash -dms-control journey "$RUN" logs -``` diff --git a/.agents/skills/verify-dms-api/features/overview.md b/.agents/skills/verify-dms-api/features/overview.md deleted file mode 100644 index e4854b2..0000000 --- a/.agents/skills/verify-dms-api/features/overview.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -covers: - - src/routes/overview.ts - - src/pages/overview.ts - - src/pages/displays.ts - - src/pages/blocks.ts - - src/pages/toolbar.ts - - src/pages/scope-chip.ts - - src/pages/module.ts - - src/pages/index.ts - - src/services/overview.ts - - src/services/overview-lists.ts - - src/services/health-rules.ts - - src/services/attention.ts - - src/services/activity.ts - - src/services/comparison.ts - - src/services/period.ts - - src/services/window.ts - - src/services/traffic.ts - - src/services/live.ts - - src/services/live-feed.ts - - src/services/composed-text.ts - - src/services/zod-json.ts - - frontend-vue/app/components/blocks/HealthHero.vue - - frontend-vue/app/components/blocks/ScopeChip.vue - - frontend-vue/app/components/blocks/BetaBadge.vue - - frontend-vue/app/components/blocks/SplitLayout.vue - - frontend-vue/app/components/internal/HealthHeroMetrics.vue - - frontend-vue/app/composables/useApiPeriod.ts - - frontend-vue/app/composables/useClientValue.ts - - frontend-vue/app/composables/useDateFormat.ts - - frontend-vue/app/composables/useLiveMissedErrors.ts - - frontend-vue/app/utils/health.ts - - frontend-vue/app/utils/format.ts - - frontend-vue/app/utils/minuteHistogram.ts - - frontend-vue/app/plugins/displays.ts - - frontend-vue/app/config/shortcuts-registry.ts -docs: - - docs/4.usage/1.overview.md ---- - -# Overview - -The Overview: the health verdict and why, the attention list, the slowest routes, the error share, traffic, status classes, period, comparison, scope chip and live mode. - -## Sub-features - -- `the-blocks-rank-the-routes-by-what-is-wrong-with-them` -- `the-period-and-the-comparison-are-kept-in-the-url-and-shared-by-the-pages` -- `down-reads-the-last-five-minutes-and-not-the-last-fifteen` -- `errors-older-than-five-minutes-do-not-make-the-api-down` -- `a-comparison-beyond-the-kept-statistics-compares-with-nothing` -- `the-hero-says-how-long-the-verdict-has-held-and-when-it-was-checked` -- `a-comparison-the-page-does-not-know-compares-with-nothing` -- `every-figure-compared-with-the-period-before-says-its-change-and-its-value` -- `the-slowest-routes-are-ranked-by-average-latency-not-by-their-slowest-call` -- `the-module-path-redirects-to-the-overview` -- `a-route-is-flagged-at-the-documented-edges-whatever-the-period` -- `l-switches-the-page-between-live-and-pause` -- the verdict ladder: `with-no-traffic-the-verdict-is-idle`, `nineteen-failing-calls-are-too-few-to-judge`, `one-failing-call-in-a-hundred-is-degraded`, `one-failing-call-in-a-hundred-and-one-is-operational`, `a-fifth-of-the-calls-failing-is-down`, `nineteen-percent-failing-is-degraded-not-down` - -## How to get to it (user POV) - -- Modules › API › Overview (`/modules/api/overview`). - -## Driving it with dms-control - -```bash -dms-control journey "$RUN" overview -``` diff --git a/.agents/skills/verify-dms-api/features/package.md b/.agents/skills/verify-dms-api/features/package.md deleted file mode 100644 index 453f2df..0000000 --- a/.agents/skills/verify-dms-api/features/package.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -covers: - - package.json - - skills/** - - frontend-vue/i18n/** - - frontend-vue/build/** - - frontend-vue/dms.server.ts - - frontend-vue/server/** - - src/frontend-module.ts - - src/guards.ts -docs: - - docs/2.installation.md - - docs/1.introduction.md ---- - -# Package - -What a project installs: the module with its build, the Vue layer, the skill, the locales, and the ranges the docs name. - -## Sub-features - -- `the-tarball-holds-what-the-manifest-names` -- `the-ranges-and-the-skill-match-what-the-docs-name` -- `the-docs-links-and-the-two-locales-are-complete` - -## How to get to it (user POV) - -- `ajs project modules add @antelopejs/dms-api`. - -## Driving it with dms-control - -```bash -dms-control journey "$RUN" package -``` diff --git a/.agents/skills/verify-dms-api/features/retention.md b/.agents/skills/verify-dms-api/features/retention.md deleted file mode 100644 index d2c9118..0000000 --- a/.agents/skills/verify-dms-api/features/retention.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -covers: - - src/services/statistics-prune.ts - - src/services/request-log/prune.ts - - src/services/settings-form.ts - - src/routes/settings.ts - - frontend-vue/app/components/blocks/RetentionInput.vue - - frontend-vue/app/utils/settingsForm.ts -docs: - - docs/4.usage/4.settings.md ---- - -# Retention - -How long data is kept: what the next hourly prune deletes, the confirmation before a lower retention is saved, and the prune itself. - -## Sub-features - -- `lowering-a-retention-tells-what-the-next-prune-deletes` -- `lowering-a-retention-asks-before-it-deletes` -- `the-hourly-prune-deletes-what-the-retention-passed` - -## How to get to it (user POV) - -- Modules › API › API settings › Retention. - -## Driving it with dms-control - -```bash -dms-control journey "$RUN" retention -``` - -## Gotchas - -- The prune runs at the turn of the hour: `e2e/clock.cjs` sets the backend's clock ahead so it fires within seconds. diff --git a/.agents/skills/verify-dms-api/features/routes.md b/.agents/skills/verify-dms-api/features/routes.md deleted file mode 100644 index aa375a1..0000000 --- a/.agents/skills/verify-dms-api/features/routes.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -covers: - - src/routes/routes.ts - - src/pages/routes.ts - - src/services/routes-sync.ts - - src/services/route-catalog.ts - - src/services/route-contract.ts - - src/services/route-statistics.ts - - src/services/route-health.ts - - src/services/scope.ts - - src/services/links.ts - - src/services/api-origin.ts - - src/services/introspection/** - - frontend-vue/app/components/blocks/RouteTree.vue - - frontend-vue/app/components/blocks/RouteHeader.vue - - frontend-vue/app/components/blocks/RouteDocumentation.vue - - frontend-vue/app/components/internal/RouteInternals.vue - - frontend-vue/app/components/internal/RouteTreeFooter.vue - - frontend-vue/app/components/internal/ApiMethodBadge.vue - - frontend-vue/app/components/internal/ApiPath.vue - - frontend-vue/app/composables/useRouteSelection.ts - - frontend-vue/app/composables/useLastRoute.ts - - frontend-vue/app/composables/useRouteDetail.ts - - frontend-vue/app/composables/useApiOrigin.ts - - frontend-vue/app/middleware/defaultRoute.ts - - frontend-vue/app/utils/routeExplorer.ts - - frontend-vue/app/utils/snippets.ts -docs: - - docs/4.usage/3.routes.md - - docs/5.extending.md - - docs/6.faq.md ---- - -# Routes - -The Routes page: the tree of routes with health and filters, a route's header, its Statistics, its inferred Documentation and the URL that names a route and a tab. - -## Sub-features - -- `the-tree-groups-routes-by-folder-and-the-filters-narrow-it` -- `a-route-opens-with-its-header-and-the-url-names-it` -- `the-statistics-tab-adds-up-the-period` -- `the-documentation-tab-is-inferred-from-the-code-and-the-traffic` -- `the-contract-reads-seven-days-of-real-calls-and-never-the-testers` -- `a-route-from-an-installed-module-names-its-module` -- `the-route-statistics-compare-in-points-with-the-period-before` -- `the-documentation-writes-its-snippets-against-the-public-api-origin-and-hides-what-was-never-called` -- `authentication-is-read-from-the-guards-before-the-handler` -- `slash-opens-the-route-filter` -- `copy-curl-on-a-route-copies-an-example-call` - -## How to get to it (user POV) - -- Modules › API › Routes; a route's `?route= &tab=statistics|documentation|tester` link. - -## Driving it with dms-control - -```bash -dms-control journey "$RUN" routes -``` - -## Gotchas - -- Controller internals are not driven. Copy cURL is: the journey grants the browser context the clipboard permission and reads the text back with `navigator.clipboard.readText()`. diff --git a/.agents/skills/verify-dms-api/features/settings.md b/.agents/skills/verify-dms-api/features/settings.md deleted file mode 100644 index 6843e54..0000000 --- a/.agents/skills/verify-dms-api/features/settings.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -covers: - - src/routes/settings.ts - - src/pages/settings.ts - - src/services/settings.ts - - src/services/settings-form.ts - - src/config.ts - - src/db/models/api_settings.model.ts - - src/db/tables/api_settings.table.ts - - frontend-vue/app/utils/settingsForm.ts - - frontend-vue/app/components/blocks/SettingNumberInput.vue - - frontend-vue/app/components/blocks/RetentionInput.vue -docs: - - docs/4.usage/4.settings.md - - docs/3.configuration.md - - docs/6.faq.md ---- - -# Settings - -The API settings page and the module options it overrides: scope, retentions, capture and privacy, the slow threshold and the refusal of an invalid configuration at start. - -## Sub-features - -- `the-form-shows-the-documented-defaults` -- `every-bound-of-the-form-is-enforced-on-its-edge` -- `use-default-returns-a-field-to-the-module-option` -- `the-module-refuses-to-start-with-a-value-the-form-would-refuse` -- `a-log-retention-of-no-day-is-refused-at-start` -- `retention-fields-have-no-use-default-but-the-others-do` -- `the-use-default-button-removes-an-override-on-the-page` -- `the-scope-decides-which-routes-and-requests-every-page-watches` - -## How to get to it (user POV) - -- Modules › API › API settings; the `dms-api` entry of `antelope.config.ts`. - -## Driving it with dms-control - -```bash -dms-control journey "$RUN" settings -``` diff --git a/.agents/skills/verify-dms-api/features/smoke.md b/.agents/skills/verify-dms-api/features/smoke.md deleted file mode 100644 index 593cf4a..0000000 --- a/.agents/skills/verify-dms-api/features/smoke.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -covers: - - src/index.ts - - src/types/** - - src/automation/index.ts - - frontend-vue/dms.frontend.ts - - frontend-vue/dms.frontend.build.ts - - frontend-vue/tsconfig.json - - frontend-vue/package.json - - package.json -docs: - - docs/1.introduction.md - - docs/2.installation.md ---- - -# Smoke - -The fixed journey every verdict runs: the introduction's "captures the requests your project's API answers and turns them into a health verdict, request logs". - -## Sub-features - -- `traffic-shows-in-the-overview-and-the-request-logs`: 25 good calls and one failing call give a Degraded verdict and a failing row. - -## How to get to it (user POV) - -- Modules › API › Overview, then Request logs. - -## Driving it with dms-control - -```bash -dms-control journey "$RUN" smoke -``` diff --git a/.agents/skills/verify-dms-api/features/tester.md b/.agents/skills/verify-dms-api/features/tester.md deleted file mode 100644 index 6817ebe..0000000 --- a/.agents/skills/verify-dms-api/features/tester.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -covers: - - src/services/tester-source.ts - - frontend-vue/server/tester.ts - - frontend-vue/dms.server.ts - - frontend-vue/app/components/blocks/RouteTester.vue - - frontend-vue/app/components/internal/RouteTesterRequest.vue - - frontend-vue/app/components/internal/RouteTesterResponse.vue - - frontend-vue/app/components/internal/routeTester/** - - frontend-vue/app/utils/testerRequest.ts - - frontend-vue/app/utils/testerHistory.ts - - frontend-vue/app/utils/testerMasks.ts - - frontend-vue/app/composables/useLastRoute.ts -docs: - - docs/4.usage/3.routes.md - - docs/3.configuration.md - - docs/6.faq.md ---- - -# Tester - -The Tester tab of a route: real calls through the frontend server, logged and marked apart from the traffic, and the token that marks them. - -## Sub-features - -- `a-tester-call-is-logged-and-marked-but-never-counted` -- `the-tester-sends-the-form-and-keeps-twenty-five-calls` -- `a-history-entry-restores-its-call-and-a-typed-authorization-beats-the-session` -- `headers-for-all-routes-are-kept-in-the-browser-but-credentials-are-not` -- `a-replayed-call-needs-its-credentials-and-redacted-values-by-hand` -- `the-forwarding-route-refuses-unsafe-paths-and-never-forwards-blocked-headers` -- `a-secret-keeps-the-testers-token-valid-across-restarts` - -## How to get to it (user POV) - -- Modules › API › Routes › a route › Tester; Replay in tester from a request. - -## Driving it with dms-control - -```bash -dms-control journey "$RUN" tester -``` diff --git a/.agents/skills/verify-dms-api/package.json b/.agents/skills/verify-dms-api/package.json deleted file mode 100644 index 5ffd980..0000000 --- a/.agents/skills/verify-dms-api/package.json +++ /dev/null @@ -1 +0,0 @@ -{ "type": "module" } diff --git a/.agents/skills/verify-dms-api/tsconfig.json b/.agents/skills/verify-dms-api/tsconfig.json deleted file mode 100644 index 4599508..0000000 --- a/.agents/skills/verify-dms-api/tsconfig.json +++ /dev/null @@ -1,20 +0,0 @@ -{ - "extends": "../../../tsconfig.json", - "compilerOptions": { - "rootDir": "../../..", - "allowJs": true, - "checkJs": false, - "maxNodeModuleJsDepth": 5, - "types": ["node"], - "lib": ["esnext", "dom", "dom.iterable"], - "module": "nodenext", - "moduleResolution": "nodenext", - "allowImportingTsExtensions": true, - "composite": false, - "noEmit": true, - "incremental": false, - "experimentalDecorators": true - }, - "include": ["**/*.mjs", "**/*.cjs", "**/*.ts"], - "exclude": ["node_modules", "playground/node_modules", "playground/dist"] -} diff --git a/.agents/skills/verify-dms-api/verify.config.ts b/.agents/skills/verify-dms-api/verify.config.ts deleted file mode 100644 index ebeafd5..0000000 --- a/.agents/skills/verify-dms-api/verify.config.ts +++ /dev/null @@ -1,120 +0,0 @@ -/** A kind of one-way door. */ -export type DoorKind = "data" | "format" | "contract" | "outbound" | "exposure" | "publish"; - -/** Path rules for one door kind: globs and declared funnel modules. */ -export interface DoorRule { - globs: string[]; - funnels: string[]; - why: string; -} - -/** - * How the gate decides whether a diff changed what the covered code does: - * `emit` compares the JavaScript statements of the covered files on the - * base and on HEAD (types, comments, formatting, imports and export - * keywords left out); `probe` runs a command on a checkout of each, the - * checkout's path as last argument, and compares what it prints. - */ -export type Behaviour = { kind: "emit" } | { kind: "probe"; command: string[] }; - -/** - * A formal check: the source files it covers, the check's own files, the - * command that runs it, how its output names a violated and a passing rule, - * how the gate decides that a diff changed the covered behaviour, and the - * command run on the base when it did or when the check's own files changed - * (`command` when absent). - */ -export interface FormalCheck { - name: string; - covers: string[]; - files: string[]; - command: string[]; - baseCommand?: string[]; - violation: RegExp | null; - passing: RegExp | null; - behaviour: Behaviour; -} - -/** The repo-owned layer of the verification skill, read by `dms-control`. */ -export interface VerifyConfig { - playground: string; - prepare: string[][]; - userFacing: string[]; - notUserFacing: string[]; - smoke: string; - smokeJourney: string; - /** The folder of the journeys modules, relative to the repository root. */ - journeys: string; - doors: Record; - formal: FormalCheck[]; -} - -const config: VerifyConfig = { - playground: "e2e/playground", - prepare: [ - ["pnpm", "install", "--frozen-lockfile", "--prefer-offline", "--ignore-scripts"], - ["pnpm", "run", "build"], - ["pnpm", "--dir", "playground", "install", "--ignore-workspace", "--frozen-lockfile", "--prefer-offline", "--ignore-scripts"], - ["ln", "-sfn", "../../playground/node_modules", "e2e/playground/node_modules"], - ["node_modules/.bin/tsc", "-p", "e2e/playground/tsconfig.build.json"], - ], - userFacing: ["src/**", "frontend-vue/**", "skills/**", "package.json"], - notUserFacing: ["frontend-vue/tests/**", "frontend-vue/.*", "frontend-vue/eslint.config.mjs", "frontend-vue/vitest.config.ts", "frontend-vue/pnpm-lock.yaml"], - smoke: "smoke", - smokeJourney: "onboard, call the fixture routes, read the Overview and the request logs", - journeys: "e2e/journeys", - doors: { - data: { - globs: ["src/services/request-log/prune.ts", "src/services/statistics-prune.ts", "src/db/models/request_log.model.ts", "src/db/models/routes_statistics.model.ts", "src/index.ts"], - funnels: [], - why: "the hourly prune deletes stored request logs and per-day statistics, which a revert of the code does not bring back", - }, - format: { - globs: ["src/db/tables/**", "src/db/models/**", "src/services/statistics-write.ts", "src/services/request-log/capture.ts"], - funnels: [], - why: "the tables, the statistics keys and the stored log shape are read back by the next version of the module", - }, - contract: { - globs: ["package.json", "src/routes/**", "src/config.ts", "frontend-vue/package.json", "frontend-vue/dms.frontend.ts", "skills/**"], - funnels: [], - why: "the dashboard and scripts call the HTTP routes, projects set the config keys and the renderer range, and agents read the skill", - }, - outbound: { - globs: ["frontend-vue/server/tester.ts", "frontend-vue/dms.server.ts", "src/routes/tester.ts", "src/services/tester-source.ts"], - funnels: [], - why: "the Tester sends real requests, with the owner's session when asked, to the project's API", - }, - exposure: { - globs: ["src/services/request-log/redaction.ts", "src/services/request-log/capture.ts", "src/services/request-log/access.ts", "src/services/request-log/console-traffic.ts", "src/guards.ts"], - funnels: [], - why: "what is stored of every request, what is redacted before storage and who may read it back", - }, - publish: { - globs: ["package.json", ".release-it.json", "changelogen.config.json", ".github/workflows/release.yml"], - funnels: [], - why: "the package name, its files and the release workflow claim @antelopejs/dms-api in the npm registry", - }, - }, - formal: [ - { - name: "formal-route-statistics", - covers: [ - "src/services/statistics-write.ts", - "src/services/statistics-prune.ts", - "src/services/statistics-utils.ts", - "src/db/models/routes_statistics.model.ts", - "src/db/tables/routes_statistics.table.ts", - "src/services/request-log/capture.ts", - "src/index.ts", - ], - files: [".agents/skills/formal-route-statistics/**"], - command: ["node", ".agents/skills/formal-route-statistics/check.mjs", "--full"], - baseCommand: ["node", ".agents/skills/formal-route-statistics/check.mjs"], - violation: /^(?:finding|BROKEN|CHANGED|HOLDS) +(\w+)/gm, - passing: /(?<=^holds +(?:\w+, )*)(\w+)(?=,| \()/gm, - behaviour: { kind: "emit" }, - }, - ], -}; - -export default config; diff --git a/.claude/skills/verify-dms-api b/.claude/skills/verify-dms-api deleted file mode 120000 index 2a16d9d..0000000 --- a/.claude/skills/verify-dms-api +++ /dev/null @@ -1 +0,0 @@ -../../.agents/skills/verify-dms-api \ No newline at end of file diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fd2a2a8..d1225ce 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -111,7 +111,7 @@ jobs: - run: pnpm build # The journeys that call the API or run commands, as Vitest integration - # tests against backends of the verification playground on one MongoDB. + # tests against backends of the e2e playground on one MongoDB. journeys: needs: select if: needs.select.outputs.run == 'true' diff --git a/.gitignore b/.gitignore index 578e29f..530497d 100644 --- a/.gitignore +++ b/.gitignore @@ -372,7 +372,6 @@ $RECYCLE.BIN/ # pnpm store .pnpm-store -!.agents/skills/verify-dms-api/coverage !e2e/journeys/logs # Playwright output of the e2e suite @@ -381,7 +380,7 @@ e2e/test-results e2e/blob-report e2e/blob-reports -# What a backend of the verification playground writes when it starts +# What a backend of the e2e playground writes when it starts e2e/playground/antelope-lock e2e/playground/.codex e2e/playground/.mcp.json diff --git a/AGENTS.md b/AGENTS.md index 575a2f1..bb73eed 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,7 @@ - `pnpm test:frontend`, which builds and typechecks the Vue layer with `ajs dms verify-source` against the DMS layer of the `@antelopejs/dms` devDependency. CI runs it in its own job. It needs no backend. - `pnpm --dir frontend-vue typecheck`. It needs a running DMS backend, so that `ajs dms prepare` can generate the Inertia workspace. Set `DMS_FRONTEND_WORKSPACE` to that workspace. - The playground's typecheck and build (oxlint still lints it). Run `pnpm build`, `pnpm --dir playground install --ignore-workspace` and `pnpm --dir playground build`, then `pnpm dev` with a MongoDB running. -- The browser journeys of `e2e/`. CI runs the `@smoke` ones on a ready pull request, and every one in the merge queue, nightly, on a manual run and on a pull request labelled `ci:full`. Run them with `TZ=UTC pnpm e2e` (the verify skill says how to narrow them). +- The browser journeys of `e2e/`. CI runs the `@smoke` ones on a ready pull request, and every one in the merge queue, nightly, on a manual run and on a pull request labelled `ci:full`. Run them with `TZ=UTC pnpm e2e`, narrowed with `--grep @smoke` or `--grep `. - Unused files and exports. `pnpm knip` checks dependencies only. `pnpm knip:all` also reports dead files and exports, and expects findings: confirm each one before you remove it. @@ -37,8 +37,6 @@ CI runs `pnpm run checks` in full on every pull request and reports what failed. - `pnpm exec oxlint ` and `pnpm exec oxfmt ` on the files you changed. - One test file, not the suite. In a module that tests with `ajs module test`: `pnpm run build`, then `pnpm exec ajs module test . -f dist/.test.js`. -Prove a change works with the verification skill in [`.agents/skills/verify-dms-api/SKILL.md`](.agents/skills/verify-dms-api/SKILL.md) before you call it done. - ### Comments Say it in code: a constraint in a type, a lint rule or a test, a public item's contract in TSDoc. Other comments are lint directives naming their rules, `@ts-expect-error `, `SAFETY: ` above a type assertion, and license or tool directives. A reason states what the code does now. diff --git a/e2e/api.mjs b/e2e/api.mjs index 3578f5a..f79cf2d 100644 --- a/e2e/api.mjs +++ b/e2e/api.mjs @@ -11,7 +11,7 @@ import { join } from "node:path"; * @typedef {{ name: string, pass: boolean, detail: string }} Check */ -/** Routes the verification playground registers in the project's scope: 17 under /fx, the member route and the five node routes. */ +/** Routes the e2e playground registers in the project's scope: 17 under /fx, the member route and the five node routes. */ export const FIXTURE_ROUTES = 23; /** The console's HTTP API, which the dashboard calls. */ @@ -331,7 +331,7 @@ export async function withConfig(ctx, config, body) { * @returns {Promise} */ export async function member(ctx, name, permissions) { - const invite = await ctx.api(`invite ${name}`, { method: "POST", path: "/verify-api/member", body: { name, permissions }, as: "anon" }); + const invite = await ctx.api(`invite ${name}`, { method: "POST", path: "/fixture-api/member", body: { name, permissions }, as: "anon" }); const email = text(invite.body, "email"); const password = ctx.password(); const signup = await ctx.api(`${name} signs up`, { method: "POST", path: "/api/auth/signup", body: { name, email, password, lang: "en", token: text(invite.body, "token") }, as: "anon" }); diff --git a/e2e/journeys/automation.mjs b/e2e/journeys/automation.mjs deleted file mode 100644 index e5cb694..0000000 --- a/e2e/journeys/automation.mjs +++ /dev/null @@ -1,3 +0,0 @@ -import { guarded } from "../guard.mjs"; - -export const journeys = guarded([]); diff --git a/e2e/journeys/capture.mjs b/e2e/journeys/capture.mjs deleted file mode 100644 index e5cb694..0000000 --- a/e2e/journeys/capture.mjs +++ /dev/null @@ -1,3 +0,0 @@ -import { guarded } from "../guard.mjs"; - -export const journeys = guarded([]); diff --git a/e2e/journeys/package.mjs b/e2e/journeys/package.mjs deleted file mode 100644 index e5cb694..0000000 --- a/e2e/journeys/package.mjs +++ /dev/null @@ -1,3 +0,0 @@ -import { guarded } from "../guard.mjs"; - -export const journeys = guarded([]); diff --git a/e2e/journeys/routes/tree-and-statistics.mjs b/e2e/journeys/routes/tree-and-statistics.mjs index a52c019..68d0a8e 100644 --- a/e2e/journeys/routes/tree-and-statistics.mjs +++ b/e2e/journeys/routes/tree-and-statistics.mjs @@ -21,7 +21,7 @@ export const treeAndStatistics = [ same("a quiet route", [num(byRef("GET /fx/ok"), "requests"), text(byRef("GET /fx/ok"), "state")], [3, "healthy"]), same("an uncalled route", [num(byRef("GET /fx/blob"), "requests"), text(byRef("GET /fx/blob"), "state")], [0, "idle"]), same("the window health reads", num(listed.body, "healthWindowMinutes"), 1440), - same("the folders: the first static segments up to a parameter, at most two", ["GET /fx/ok", "GET /fx/items/:id", "POST /fx/orders/:shop/lines", "GET /fx/guarded/secret", "POST /verify-api/member"].map((ref) => text(byRef(ref), "folder")), ["/fx/ok", "/fx/items", "/fx/orders", "/fx/guarded", "/verify-api/member"]), + same("the folders: the first static segments up to a parameter, at most two", ["GET /fx/ok", "GET /fx/items/:id", "POST /fx/orders/:shop/lines", "GET /fx/guarded/secret", "POST /fixture-api/member"].map((ref) => text(byRef(ref), "folder")), ["/fx/ok", "/fx/items", "/fx/orders", "/fx/guarded", "/fixture-api/member"]), ]); const tab = await ctx.tab("admin"); await tab.signIn("admin"); diff --git a/e2e/playground/antelope.config.ts b/e2e/playground/antelope.config.ts index 678bcb9..1024fb9 100644 --- a/e2e/playground/antelope.config.ts +++ b/e2e/playground/antelope.config.ts @@ -40,7 +40,7 @@ const moduleRoot = dirname(realpathSync(resolve(__dirname, "../../package.json") * verification built from the checkout. */ export default defineConfig({ - name: "verify-dms-api", + name: "dms-api-e2e", modules: { app: { source: { type: "local", path: "." }, diff --git a/e2e/playground/package.json b/e2e/playground/package.json index dbdb636..41a8473 100644 --- a/e2e/playground/package.json +++ b/e2e/playground/package.json @@ -1,5 +1,5 @@ { - "name": "verify-dms-api-app", + "name": "dms-api-e2e-app", "version": "0.0.0", "private": true, "main": "dist/index.js", diff --git a/e2e/playground/src/automation-stub/routes.ts b/e2e/playground/src/automation-stub/routes.ts index 478a8b5..7dc6b30 100644 --- a/e2e/playground/src/automation-stub/routes.ts +++ b/e2e/playground/src/automation-stub/routes.ts @@ -20,7 +20,7 @@ const activations = new Map(); let counter = 0; /** Under /dms, which the console neither logs nor counts, so running a node adds no traffic. What a journey does with the nodes the module registered: list them, run an action, arm a trigger and read what it emitted. */ -export class AutomationNodesController extends Controller("/dms/verify-api/nodes") { +export class AutomationNodesController extends Controller("/dms/fixture-api/nodes") { @Get("") list() { return asJson({ diff --git a/e2e/playground/src/fixture-members.ts b/e2e/playground/src/fixture-members.ts index 71684b0..6443386 100644 --- a/e2e/playground/src/fixture-members.ts +++ b/e2e/playground/src/fixture-members.ts @@ -28,9 +28,9 @@ function withAncestors(permissions: string[]): string[] { /** * A role holding exactly the permission ids given, and an invitation to it a * journey signs up with: the roles editor of the DMS grants the same ids. - * Only the verification playground serves it. + * Only the e2e playground serves it. */ -export class VerifyMembersController extends Controller("/verify-api") { +export class VerifyMembersController extends Controller("/fixture-api") { @Post("/member") async member(@JSONBody() body: unknown) { const { name, permissions, language } = memberSchema.parse(body); diff --git a/e2e/playground/src/fixture.ts b/e2e/playground/src/fixture.ts index d3ae53a..c246734 100644 --- a/e2e/playground/src/fixture.ts +++ b/e2e/playground/src/fixture.ts @@ -15,7 +15,7 @@ const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)); /** * The routes a journey sends traffic to, so that every status class, a slow * answer, a thrown error, secrets in a body and a body of any size exist on - * demand. Only the verification playground serves them. + * demand. Only the e2e playground serves them. */ export class FixtureController extends Controller("/fx") { @Get("ok") diff --git a/tests/automation.journeys.test.ts b/tests/automation.journeys.test.ts index 065938b..c1778b5 100644 --- a/tests/automation.journeys.test.ts +++ b/tests/automation.journeys.test.ts @@ -85,7 +85,7 @@ async function assertTheModuleRegistersItsThreeNodesWithTheirDocumentedInputs( ): Promise { await dms.withEnv(WITH_NODES, async () => { const { actions, triggers } = apiNodes( - (await dms.api("GET", "/dms/verify-api/nodes", { as: "anon" })).body, + (await dms.api("GET", "/dms/fixture-api/nodes", { as: "anon" })).body, ); const health = actions.find((node) => node.id === HEALTH); const logs = actions.find((node) => node.id === LOGS); diff --git a/tests/capture-redaction.journeys.test.ts b/tests/capture-redaction.journeys.test.ts index 0f328d2..14f7245 100644 --- a/tests/capture-redaction.journeys.test.ts +++ b/tests/capture-redaction.journeys.test.ts @@ -42,7 +42,7 @@ const REDACTED_WORDS = [ const JSON_HEADERS = { "content-type": "application/json", - "user-agent": "verify-agent/1.0", + "user-agent": "fixture-agent/1.0", "x-request-id": "req-capture-1", "x-webhook-signature": "sig-1", authorization: "Bearer top-secret", diff --git a/tests/capture.journeys.test.ts b/tests/capture.journeys.test.ts index 4ea66bd..9631f44 100644 --- a/tests/capture.journeys.test.ts +++ b/tests/capture.journeys.test.ts @@ -5,7 +5,7 @@ import { resultsOf } from "./helpers/json"; const JSON_HEADERS = { "content-type": "application/json", - "user-agent": "verify-agent/1.0", + "user-agent": "fixture-agent/1.0", "x-request-id": "req-capture-1", "x-webhook-signature": "sig-1", authorization: "Bearer top-secret", @@ -35,7 +35,7 @@ describe("capture", () => { pathParams: { id: "42" }, query: { color: "red", size: "l" }, statusCode: 200, - userAgent: "verify-agent/1.0", + userAgent: "fixture-agent/1.0", requestId: "req-capture-1", requestBody: '{"name":"chair"}', responseBody: '{"id":"42","body":{"name":"chair"}}', diff --git a/tests/helpers/automation.ts b/tests/helpers/automation.ts index 996f19d..4a7ca8a 100644 --- a/tests/helpers/automation.ts +++ b/tests/helpers/automation.ts @@ -6,7 +6,7 @@ export const WITH_NODES = { VERIFY_API_AUTOMATION: "1" }; export const HEALTH = "api.get-api-health"; export const LOGS = "api.query-request-logs"; export const UNHEALTHY = "api.route-unhealthy"; -export const TRIGGER_PATH = "/dms/verify-api/nodes/trigger"; +export const TRIGGER_PATH = "/dms/fixture-api/nodes/trigger"; export const INTERVAL_WAIT_MS = 12_000; const propertySchema = z.object({ diff --git a/tests/helpers/backend.ts b/tests/helpers/backend.ts index dda220a..698722d 100644 --- a/tests/helpers/backend.ts +++ b/tests/helpers/backend.ts @@ -13,7 +13,7 @@ import { tmpdir } from "node:os"; import { join, resolve } from "node:path"; import { z } from "zod"; -/** The verification playground: the fixture app, dms-api from this checkout, the DMS, MongoDB and auth modules. */ +/** The e2e playground: the fixture app, dms-api from this checkout, the DMS, MongoDB and auth modules. */ export const PLAYGROUND = resolve(__dirname, "../../e2e/playground"); const READY_TIMEOUT_MS = 90_000; diff --git a/tests/helpers/dms.ts b/tests/helpers/dms.ts index 391191c..7a33340 100644 --- a/tests/helpers/dms.ts +++ b/tests/helpers/dms.ts @@ -13,7 +13,7 @@ declare module "vitest" { /** The console's HTTP API, which the dashboard calls. */ export const MONITOR = "/api/monitoring"; -/** Routes the verification playground registers in the project's scope: 17 under /fx, the member route and the five node routes. */ +/** Routes the e2e playground registers in the project's scope: 17 under /fx, the member route and the five node routes. */ export const FIXTURE_ROUTES = 23; const SETTLE_TIMEOUT_MS = 15_000; @@ -304,7 +304,7 @@ export class Dms { async member(name: string, permissions: string[]): Promise { const invite = invitationSchema.parse( ( - await this.api("POST", "/verify-api/member", { + await this.api("POST", "/fixture-api/member", { body: { name, permissions }, as: "anon", }) @@ -373,7 +373,7 @@ export class Dms { /** Runs an automation action the module registered with the playground's stand-in provider. */ runAction(id: string, input: Json): Promise { - return this.api("POST", `/dms/verify-api/nodes/action/${id}`, { + return this.api("POST", `/dms/fixture-api/nodes/action/${id}`, { body: input, as: "anon", }); diff --git a/vitest.journeys.config.ts b/vitest.journeys.config.ts index d0628bd..ac6137c 100644 --- a/vitest.journeys.config.ts +++ b/vitest.journeys.config.ts @@ -3,7 +3,7 @@ import { defineConfig } from "vitest/config"; /** * The journeys that call the API or run commands, against backends of the - * verification playground on a shared MongoDB. `pnpm e2e:build` builds what + * e2e playground on a shared MongoDB. `pnpm e2e:build` builds what * they start. */ export default defineConfig({ From 472f13ae210df440133d4144c3a49bbcdbb81d60 Mon Sep 17 00:00:00 2001 From: Antony Rizzitelli Date: Thu, 19 Nov 2026 12:49:46 +0000 Subject: [PATCH 2/3] chore: name the e2e fixtures after what they are --- AGENTS.md | 2 +- e2e/playground/antelope.config.ts | 4 ++-- e2e/playground/src/automation-stub/implementation.ts | 8 ++++---- e2e/playground/src/fixture-members.ts | 2 +- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bb73eed..b11e34f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,7 @@ - `pnpm test:frontend`, which builds and typechecks the Vue layer with `ajs dms verify-source` against the DMS layer of the `@antelopejs/dms` devDependency. CI runs it in its own job. It needs no backend. - `pnpm --dir frontend-vue typecheck`. It needs a running DMS backend, so that `ajs dms prepare` can generate the Inertia workspace. Set `DMS_FRONTEND_WORKSPACE` to that workspace. - The playground's typecheck and build (oxlint still lints it). Run `pnpm build`, `pnpm --dir playground install --ignore-workspace` and `pnpm --dir playground build`, then `pnpm dev` with a MongoDB running. -- The browser journeys of `e2e/`. CI runs the `@smoke` ones on a ready pull request, and every one in the merge queue, nightly, on a manual run and on a pull request labelled `ci:full`. Run them with `TZ=UTC pnpm e2e`, narrowed with `--grep @smoke` or `--grep `. +- The browser journeys of `e2e/`. CI runs the `@smoke` ones on a ready pull request, and every one in the merge queue, nightly, on a manual run and on a pull request labelled `ci:full`. Run them with `TZ=UTC pnpm e2e`, narrowed with `--grep @smoke` or `--grep `. - Unused files and exports. `pnpm knip` checks dependencies only. `pnpm knip:all` also reports dead files and exports, and expects findings: confirm each one before you remove it. diff --git a/e2e/playground/antelope.config.ts b/e2e/playground/antelope.config.ts index 1024fb9..7cdf0fe 100644 --- a/e2e/playground/antelope.config.ts +++ b/e2e/playground/antelope.config.ts @@ -37,7 +37,7 @@ const moduleRoot = dirname(realpathSync(resolve(__dirname, "../../package.json") /** * The repository's playground with the ports, origins, secrets and mail * the e2e kit sets for a run, a fixture module (`app`) and the module under - * verification built from the checkout. + * test built from the checkout. */ export default defineConfig({ name: "dms-api-e2e", @@ -57,7 +57,7 @@ export default defineConfig({ }, config: { homepage: "/modules/api/overview", - meta: { title: "AntelopeJS API", description: "API console verification" }, + meta: { title: "AntelopeJS API", description: "API console end-to-end tests" }, auth: { jwtSecret: process.env.DMS_JWT_SECRET ?? "dev", signInCountry: { database: false }, diff --git a/e2e/playground/src/automation-stub/implementation.ts b/e2e/playground/src/automation-stub/implementation.ts index a502e9a..40854a3 100644 --- a/e2e/playground/src/automation-stub/implementation.ts +++ b/e2e/playground/src/automation-stub/implementation.ts @@ -3,7 +3,7 @@ import { actions, dataNodes, triggers } from "./registry"; /** * The part of `@antelopejs/interface-dms-automation` a node-contributing module talks to, without the - * automation runtime: registrations are kept so the verification routes can run each node. + * automation runtime: registrations are kept so the fixture routes can run each node. */ export namespace internal { export const RegisterTriggerType = { @@ -47,13 +47,13 @@ export async function ListDataNodeTypes(): Promise { } export async function InvokeProcedure(): Promise { - throw new Error("the verification stand-in runs no procedure"); + throw new Error("the e2e stand-in runs no procedure"); } export async function RunProcedure(): Promise { - throw new Error("the verification stand-in runs no procedure"); + throw new Error("the e2e stand-in runs no procedure"); } export async function DeclareProcedure(): Promise { - throw new Error("the verification stand-in runs no procedure"); + throw new Error("the e2e stand-in runs no procedure"); } diff --git a/e2e/playground/src/fixture-members.ts b/e2e/playground/src/fixture-members.ts index 6443386..4edce04 100644 --- a/e2e/playground/src/fixture-members.ts +++ b/e2e/playground/src/fixture-members.ts @@ -30,7 +30,7 @@ function withAncestors(permissions: string[]): string[] { * journey signs up with: the roles editor of the DMS grants the same ids. * Only the e2e playground serves it. */ -export class VerifyMembersController extends Controller("/fixture-api") { +export class FixtureMembersController extends Controller("/fixture-api") { @Post("/member") async member(@JSONBody() body: unknown) { const { name, permissions, language } = memberSchema.parse(body); From 6a5d3d26dd443210265ed7d07c0b7c685258516e Mon Sep 17 00:00:00 2001 From: Antony Rizzitelli Date: Thu, 19 Nov 2026 12:49:53 +0000 Subject: [PATCH 3/3] ci: start the checks on the ready pull request