diff --git a/.agents/skills/verify-dms-api/SKILL.md b/.agents/skills/verify-dms-api/SKILL.md index 7c77fab..2fcc6c3 100644 --- a/.agents/skills/verify-dms-api/SKILL.md +++ b/.agents/skills/verify-dms-api/SKILL.md @@ -49,8 +49,8 @@ $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 the full CI tier runs) 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 to `main`, a push to `next` and a manual run, every journey nightly): `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. +- 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/`. @@ -89,11 +89,10 @@ State the verdict in your own reply. Start it with the result, then the doors, t List these as not verified in every verdict. The per-feature reasons are in [coverage/](coverage). -- Copy, Copy cURL and Copy the URL buttons: they write to the clipboard. +- 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. -- Pointer drag of the drawer's edge and the persisted drawer width. -- Keyboard shortcuts `L`, `/` and `?`, the Tester's History, Headers for all routes and the form's editors, and a Tester call's forwarding limits. +- The Tester form's query and body editors, and the 30 s timeout of the Tester's forwarding route. ## Feature map diff --git a/.agents/skills/verify-dms-api/coverage/access.md b/.agents/skills/verify-dms-api/coverage/access.md index a90b50f..db03870 100644 --- a/.agents/skills/verify-dms-api/coverage/access.md +++ b/.agents/skills/verify-dms-api/coverage/access.md @@ -5,6 +5,6 @@ | 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 | Not driven: the pages' own redirect for a member is not asserted; the routes' answers are | -| 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 | Not driven: needs a member with the Overview's recent-requests permission and an out-of-scope request | +| 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/logs.md b/.agents/skills/verify-dms-api/coverage/logs.md index 47fc8b4..f69cee2 100644 --- a/.agents/skills/verify-dms-api/coverage/logs.md +++ b/.agents/skills/verify-dms-api/coverage/logs.md @@ -12,23 +12,23 @@ | 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 | Not driven: keyboard shortcuts; the search itself is driven through the API (`the search matches error words`, `the search matches path words`) | +| 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 | Not driven: pointer drag | +| 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 | Not driven: clipboard | +| 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 | Not driven: the hold wording is not asserted | +| 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` | diff --git a/.agents/skills/verify-dms-api/coverage/overview.md b/.agents/skills/verify-dms-api/coverage/overview.md index 1f85119..be7277d 100644 --- a/.agents/skills/verify-dms-api/coverage/overview.md +++ b/.agents/skills/verify-dms-api/coverage/overview.md @@ -26,7 +26,7 @@ | 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 | Not driven: the keyboard shortcut is checked by no journey | +| 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 | diff --git a/.agents/skills/verify-dms-api/coverage/routes.md b/.agents/skills/verify-dms-api/coverage/routes.md index 2104728..fa6a058 100644 --- a/.agents/skills/verify-dms-api/coverage/routes.md +++ b/.agents/skills/verify-dms-api/coverage/routes.md @@ -6,9 +6,9 @@ | 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 | Not driven: keyboard shortcut | +| 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 | `Requests` (URL route). Copy cURL: Not driven, clipboard | +| 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 | diff --git a/.agents/skills/verify-dms-api/coverage/settings.md b/.agents/skills/verify-dms-api/coverage/settings.md index 723a648..c30330a 100644 --- a/.agents/skills/verify-dms-api/coverage/settings.md +++ b/.agents/skills/verify-dms-api/coverage/settings.md @@ -12,7 +12,7 @@ | 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 itself on the page: Not driven | +| 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 | diff --git a/.agents/skills/verify-dms-api/coverage/tester.md b/.agents/skills/verify-dms-api/coverage/tester.md index 7eb6e61..c076968 100644 --- a/.agents/skills/verify-dms-api/coverage/tester.md +++ b/.agents/skills/verify-dms-api/coverage/tester.md @@ -7,7 +7,7 @@ | 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 (blocked headers, unsafe paths, the 64 KB answer limit, the 30 s timeout of `frontend-vue/server/tester.ts`) are Not driven | +| 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 | diff --git a/.agents/skills/verify-dms-api/features/README.md b/.agents/skills/verify-dms-api/features/README.md index 894aca8..bfc27dd 100644 --- a/.agents/skills/verify-dms-api/features/README.md +++ b/.agents/skills/verify-dms-api/features/README.md @@ -6,13 +6,13 @@ One file per feature. `covers:` lists the source globs it owns, `docs:` the page |---|---|---| | [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 | -| [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 | -| [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 | -| [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 | -| [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 | +| [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 | +| [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 index 33ae016..20bd9e0 100644 --- a/.agents/skills/verify-dms-api/features/access.md +++ b/.agents/skills/verify-dms-api/features/access.md @@ -15,6 +15,8 @@ Who may call the console: a session for every route, and the platform 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` ## How to get to it (user POV) diff --git a/.agents/skills/verify-dms-api/features/logs.md b/.agents/skills/verify-dms-api/features/logs.md index 9bc5897..1dc304a 100644 --- a/.agents/skills/verify-dms-api/features/logs.md +++ b/.agents/skills/verify-dms-api/features/logs.md @@ -46,6 +46,10 @@ The Request logs page: the histogram, the status tabs, the filters, the search, - `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) diff --git a/.agents/skills/verify-dms-api/features/overview.md b/.agents/skills/verify-dms-api/features/overview.md index 11bf169..e4854b2 100644 --- a/.agents/skills/verify-dms-api/features/overview.md +++ b/.agents/skills/verify-dms-api/features/overview.md @@ -56,6 +56,7 @@ The Overview: the health verdict and why, the attention list, the slowest routes - `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) diff --git a/.agents/skills/verify-dms-api/features/routes.md b/.agents/skills/verify-dms-api/features/routes.md index 8b21fac..aa375a1 100644 --- a/.agents/skills/verify-dms-api/features/routes.md +++ b/.agents/skills/verify-dms-api/features/routes.md @@ -46,6 +46,8 @@ The Routes page: the tree of routes with health and filters, a route's header, i - `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) @@ -59,4 +61,4 @@ dms-control journey "$RUN" routes ## Gotchas -- Controller internals, Copy and Copy cURL write to the clipboard: not driven. +- 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 index 819bc5f..6843e54 100644 --- a/.agents/skills/verify-dms-api/features/settings.md +++ b/.agents/skills/verify-dms-api/features/settings.md @@ -28,6 +28,7 @@ The API settings page and the module options it overrides: scope, retentions, ca - `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) diff --git a/.agents/skills/verify-dms-api/features/tester.md b/.agents/skills/verify-dms-api/features/tester.md index 04ccf25..6817ebe 100644 --- a/.agents/skills/verify-dms-api/features/tester.md +++ b/.agents/skills/verify-dms-api/features/tester.md @@ -28,6 +28,7 @@ The Tester tab of a route: real calls through the frontend server, logged and ma - `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) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5a96105..e24b2f1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,12 +2,14 @@ name: ci on: pull_request: - types: [opened, synchronize, reopened, ready_for_review] + types: [opened, synchronize, reopened, ready_for_review, labeled, unlabeled] + merge_group: push: - branches: [next] + branches: [main] schedule: - cron: "17 2 * * *" workflow_dispatch: + permissions: contents: read @@ -28,8 +30,11 @@ jobs: # the `@antelopejs/dms` devDependency: no running backend needed. extra-commands: pnpm test:frontend extra-commands-job: true + affected-tests: true permissions: contents: read + secrets: + NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }} select: runs-on: ubuntu-latest @@ -37,6 +42,7 @@ jobs: outputs: tier: ${{ steps.tier.outputs.tier }} run: ${{ steps.tier.outputs.run }} + e2e: ${{ steps.tier.outputs.e2e }} steps: - name: Pick the tier with the shared rule id: pick @@ -45,19 +51,26 @@ jobs: id: tier env: TIER: ${{ steps.pick.outputs.tier }} + EVENT: ${{ github.event_name }} + FULL_LABEL: ${{ contains(github.event.pull_request.labels.*.name, 'ci:full') }} run: | tier="$TIER" run=true + e2e=smoke if [[ "$tier" == none || "$tier" == draft ]]; then run=false + e2e=none + elif [[ "$EVENT" =~ ^(merge_group|schedule|workflow_dispatch)$ || "$FULL_LABEL" == true ]]; then + e2e=all fi { echo "tier=${tier}" echo "run=${run}" + echo "e2e=${e2e}" } >> "$GITHUB_OUTPUT" - echo "Tier \`${tier}\`: own jobs run ${run}" >> "$GITHUB_STEP_SUMMARY" + echo "Tier \`${tier}\`: own jobs run ${run}, browser journeys ${e2e}" >> "$GITHUB_STEP_SUMMARY" formal-route-statistics: needs: select @@ -97,20 +110,21 @@ jobs: - run: pnpm install --frozen-lockfile --ignore-scripts - run: pnpm build - # The journeys of e2e/ as a Playwright suite: the @smoke ones on the full - # tier, every journey in shards on the nightly tier, nothing on a draft or - # the fast tier. Its global setup prepares and starts one dms-control run. + # The journeys of e2e/ as a Playwright suite: the @smoke ones on a pull + # request or a push, every journey in two shards in the merge queue, the + # nightly run, a manual run and a pull request labelled ci:full, nothing on + # a draft. Its global setup prepares and starts one dms-control run. e2e: needs: select - if: needs.select.outputs.tier == 'full' || needs.select.outputs.tier == 'nightly' + if: needs.select.outputs.e2e != 'none' runs-on: ubuntu-latest timeout-minutes: 60 strategy: fail-fast: false matrix: - shard: ${{ fromJSON(needs.select.outputs.tier == 'nightly' && '[1, 2]' || '[1]') }} + shard: ${{ fromJSON(needs.select.outputs.e2e == 'all' && '[1, 2]' || '[1]') }} env: - TIER: ${{ needs.select.outputs.tier }} + E2E: ${{ needs.select.outputs.e2e }} TZ: UTC steps: - uses: actions/checkout@v4 @@ -140,15 +154,15 @@ jobs: fi echo "::warning::Chromium's system packages did not install: installing the browser alone" pnpm exec playwright install --only-shell chromium - - if: env.TIER == 'full' + - if: env.E2E == 'smoke' run: pnpm e2e --grep @smoke - - if: env.TIER == 'nightly' + - if: env.E2E == 'all' run: pnpm e2e --shard=${{ matrix.shard }}/2 --reporter=blob env: PLAYWRIGHT_BLOB_OUTPUT_DIR: e2e/blob-report - if: success() || failure() run: pnpm exec tsc --noEmit -p e2e - - if: always() && env.TIER == 'nightly' + - if: always() && env.E2E == 'all' uses: actions/upload-artifact@v4 with: name: blob-report-${{ matrix.shard }} @@ -165,10 +179,10 @@ jobs: ${{ runner.temp }}/dms-runs/*/logs retention-days: 7 - # One HTML and JSON report of the nightly shards. + # One HTML and JSON report of the shards of a run of every journey. e2e-report: needs: [select, e2e] - if: always() && needs.select.outputs.tier == 'nightly' + if: always() && needs.select.outputs.e2e == 'all' runs-on: ubuntu-latest timeout-minutes: 10 steps: @@ -205,7 +219,7 @@ jobs: timeout-minutes: 5 steps: - if: >- - needs.select.result != 'success' || contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || needs.ci.result == 'skipped' || (needs.select.outputs.run == 'true' && (needs.build.result == 'skipped' || needs.formal-route-statistics.result == 'skipped')) || ((needs.select.outputs.tier == 'full' || needs.select.outputs.tier == 'nightly') && needs.e2e.result == 'skipped') + needs.select.result != 'success' || contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || needs.ci.result == 'skipped' || (needs.select.outputs.run == 'true' && (needs.build.result == 'skipped' || needs.formal-route-statistics.result == 'skipped')) || (needs.select.outputs.e2e != 'none' && needs.e2e.result == 'skipped') run: exit 1 - if: needs.select.outputs.tier == 'draft' run: | diff --git a/.github/workflows/next-sync.yml b/.github/workflows/next-sync.yml deleted file mode 100644 index 2a1228b..0000000 --- a/.github/workflows/next-sync.yml +++ /dev/null @@ -1,16 +0,0 @@ -name: Next sync - -on: - push: - branches: [main] - -permissions: {} - -jobs: - next-sync: - permissions: - issues: write - uses: AntelopeJS/.github/.github/workflows/next-sync.yml@v2 - secrets: - RELEASE_GITHUB_TOKEN: ${{ secrets.RELEASE_GITHUB_TOKEN }} - NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 85dc9fa..0b6f68a 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -2,7 +2,9 @@ name: Release on: push: - branches: [next] + branches: [main] + pull_request: + types: [labeled, synchronize, reopened] workflow_dispatch: inputs: release-version: diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml deleted file mode 100644 index 5faf7ec..0000000 --- a/.github/workflows/stale.yml +++ /dev/null @@ -1,16 +0,0 @@ -name: Close stale issues - -on: - schedule: - - cron: "30 4 * * *" - workflow_dispatch: - -permissions: {} - -jobs: - stale: - permissions: - actions: write - issues: write - pull-requests: write - uses: AntelopeJS/.github/.github/workflows/stale.yml@v2 diff --git a/AGENTS.md b/AGENTS.md index 10b6df8..575a2f1 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 to `main` and a push to `next`, and every one nightly. 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` (the verify skill says how to narrow them). - 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/journeys/access.mjs b/e2e/journeys/access.mjs index 01a8a23..ddc1fdc 100644 --- a/e2e/journeys/access.mjs +++ b/e2e/journeys/access.mjs @@ -1,7 +1,10 @@ import { guarded } from "../guard.mjs"; -import { check, isText, member, mon, same, text, traffic } from "../api.mjs"; +import { check, isText, list, member, mon, raw, same, saveSettings, settled, text, traffic, openPage } from "../api.mjs"; /** @typedef {import("../api.mjs").Ctx} Ctx */ +/** @typedef {import("../api.mjs").Row} Row */ + +const TESTER_HEADER = "x-antelopejs-api-source"; /** Every route of the console: method and path under /api/monitoring. */ const ROUTES = [ @@ -98,4 +101,73 @@ export const journeys = guarded([ await ctx.verify("the owner", ["GET /logs", "GET /tester/source"].map((route) => check(`${route} opens`, owner.find((entry) => entry.route === route)?.status === 200, owner.find((entry) => entry.route === route)))); }, }, + { + id: "a-member-without-the-modules-permissions-is-sent-to-their-settings", + title: "every page of the console sends a member whose role holds none of its permissions to their own Settings page, where none of the console's headings show, while the owner stays on the page", + entryPoint: "/modules/api, /modules/api/overview, /modules/api/logs, /modules/api/routes and /modules/api/settings", + async run(/** @type {Ctx} */ ctx) { + await member(ctx, "plain", []); + const owner = await ctx.tab("admin", "owner"); + await owner.signIn("admin"); + const tab = await ctx.tab("plain"); + await tab.signIn("plain"); + const pages = [["overview", "Overview"], ["logs", "Request logs"], ["routes", "Routes"], ["settings", "API settings"]]; + for (const [page, heading] of pages) { + await openPage(owner, `/modules/api/${page}`); + await ctx.verify(`the owner on ${page}`, [owner.at(new RegExp(`^/modules/api/${page}$`)), owner.visible({ role: "heading", name: heading, level: 1, exact: true })]); + await openPage(tab, `/modules/api/${page}`); + await ctx.verify(`the member on ${page}`, [ + tab.at(/^\/settings$/), + tab.visible({ role: "heading", name: "Settings", level: 1, exact: true }), + tab.visible({ role: "heading", name: heading, level: 1, exact: true }, { hidden: true, timeoutMs: 2000 }), + ]); + } + await openPage(tab, "/modules/api"); + await ctx.verify("the member on the module's own path", [tab.at(/^\/settings$/), tab.visible({ role: "heading", name: "Settings", level: 1, exact: true })]); + }, + }, + { + id: "a-panel-opened-from-one-table-reads-only-a-request-that-table-can-list", + title: "with the scope narrowed to the project's routes, the Request logs panel still reads a module's request, while the Overview's and the Routes page's panels answer 404 for it, the Tester's panel reads it only when the Tester sent it, and every panel reads the project's own request", + entryPoint: "GET /api/monitoring/logs/:id, /logs/recent/:id, /logs/routes/:id and /logs/tester/:id", + async run(/** @type {Ctx} */ ctx) { + await saveSettings(ctx, "watch every route", { scope: "all" }); + await traffic(ctx, "a project request", [{ path: "/fx/ok", count: 1 }]); + await ctx.api("a module request", { method: "GET", path: "/api/onboarding/informations", as: "anon" }); + const token = text((await mon(ctx, "ask a token", "/tester/source")).body, "value"); + await raw(ctx, "a module request the Tester sent", { path: "/api/onboarding/informations?from=tester", headers: { [TESTER_HEADER]: token } }); + const logs = await settled(ctx, "the three requests are logged", "/logs?limit=50", (body) => list(body, "results").length === 3); + const rows = list(logs.body, "results"); + const idOf = (/** @type {(row: Row) => boolean} */ match) => text(rows.find(match), "_id"); + const projectId = idOf((row) => text(row, "path") === "/fx/ok"); + const moduleId = idOf((row) => text(row, "path") === "/api/onboarding/informations" && text(row, "source") !== "tester"); + const sentId = idOf((row) => text(row, "source") === "tester"); + await ctx.verify("the three requests", [check("each has an id", [projectId, moduleId, sentId].every((id) => id !== ""), { projectId, moduleId, sentId })]); + await saveSettings(ctx, "watch the project's routes only", { scope: "own" }); + /** @type {Record>} */ + const answers = {}; + for (const table of ["logs", "recent", "routes", "tester"]) { + answers[table] = {}; + for (const [name, id] of [["project", projectId], ["module", moduleId], ["sent", sentId]]) { + answers[table][name] = (await mon(ctx, `${table} panel reads the ${name} request`, `/logs/${table === "logs" ? "" : `${table}/`}${id}`)).status; + } + } + const unknown = await mon(ctx, "the Overview's panel reads an id nothing holds", "/logs/recent/0123456789abcdef01234567"); + const refused = await mon(ctx, "the Overview's panel reads the module's request", `/logs/recent/${moduleId}`); + await ctx.verify("the project's own request", Object.entries(answers).map(([table, got]) => same(`the ${table} panel reads it`, got.project, 200))); + await ctx.verify("a module's request", [ + same("the Request logs panel reads it: that table lists every request", answers.logs?.module, 200), + same("the Overview's panel does not", answers.recent?.module, 404), + same("the Routes page's panel does not", answers.routes?.module, 404), + same("the Tester's panel does not", answers.tester?.module, 404), + ]); + await ctx.verify("a module's request the Tester sent", [ + same("the Request logs panel reads it", answers.logs?.sent, 200), + same("the Overview's panel does not", answers.recent?.sent, 404), + same("the Routes page's panel does not", answers.routes?.sent, 404), + same("the Tester's panel reads it: it reads back its own calls to any route", answers.tester?.sent, 200), + ]); + await ctx.verify("a request out of reach is not told apart from a missing one", [same("the refusal and the missing id answer alike", [refused.status, refused.body], [unknown.status, unknown.body])]); + }, + }, ]); diff --git a/e2e/journeys/logs.mjs b/e2e/journeys/logs.mjs index e15938c..fb39341 100644 --- a/e2e/journeys/logs.mjs +++ b/e2e/journeys/logs.mjs @@ -2,5 +2,6 @@ import { guarded } from "../guard.mjs"; import { listAndPause } from "./logs/list-and-pause.mjs"; import { histogramAndDrawer } from "./logs/histogram-and-drawer.mjs"; import { filtersAndLabels } from "./logs/filters-and-labels.mjs"; +import { keyboardAndDrawer } from "./logs/keyboard-and-drawer.mjs"; -export const journeys = guarded([...listAndPause, ...histogramAndDrawer, ...filtersAndLabels]); +export const journeys = guarded([...listAndPause, ...histogramAndDrawer, ...filtersAndLabels, ...keyboardAndDrawer]); diff --git a/e2e/journeys/logs/keyboard-and-drawer.mjs b/e2e/journeys/logs/keyboard-and-drawer.mjs new file mode 100644 index 0000000..e94b662 --- /dev/null +++ b/e2e/journeys/logs/keyboard-and-drawer.mjs @@ -0,0 +1,169 @@ +import { check, list, mon, num, same, settled, text, traffic, raw, openPage } from "../../api.mjs"; + +/** @typedef {import("../../api.mjs").Ctx} Ctx */ +/** @typedef {import("../../api.mjs").Tab} Tab */ + +const SEARCH = { role: "textbox", name: "Path, request ID, error…" }; +const DRAWER = { role: "dialog" }; + +/** + * Lets the page read the clipboard the way a user's own browser does once they allowed it. + * + * @param {Tab} tab The tab + * @returns {Promise} + */ +async function allowClipboard(tab) { + await tab.page.context().grantPermissions(["clipboard-read", "clipboard-write"], { origin: new URL(tab.page.url()).origin }); +} + +/** + * @param {Tab} tab The tab + * @returns {Promise} What the clipboard holds + */ +function clipboardText(tab) { + return tab.page.evaluate(() => navigator.clipboard.readText()); +} + +/** + * @param {Tab} tab The tab + * @returns {Promise} The placeholder of the focused field, or the empty string when no field has the focus + */ +function focusedField(tab) { + return tab.page.evaluate(() => (document.activeElement instanceof HTMLInputElement ? document.activeElement.placeholder : "")); +} + +/** + * @param {Tab} tab The tab + * @returns {Promise} The width of the open drawer in pixels + */ +async function drawerWidth(tab) { + const box = await tab.locator(DRAWER).first().boundingBox(); + return box ? Math.round(box.width) : undefined; +} + +/** The logs journeys about the keyboard, the clipboard and the drawer's width. */ +export const keyboardAndDrawer = [ + { + id: "slash-opens-the-request-search-and-question-mark-lists-the-shortcuts", + title: "the slash key focuses the search of the Request logs and what is typed narrows the table; the question mark opens the list of the page's shortcuts, which Escape closes", + entryPoint: "/modules/api/logs", + async run(/** @type {Ctx} */ ctx) { + await traffic(ctx, "two paths", [{ path: "/fx/ok", count: 2 }, { path: "/fx/missing", count: 1 }]); + await settled(ctx, "the logs hold 3", "/logs", (body) => num(body, "total") === 3); + const tab = await ctx.tab("admin"); + await tab.signIn("admin"); + await openPage(tab, "/modules/api/logs"); + await ctx.verify("before any key", [tab.visible({ role: "button", name: "All 3" }), tab.visible({ role: "dialog", name: "Keyboard shortcuts" }, { hidden: true, timeoutMs: 1500 })]); + await tab.press("?"); + await ctx.verify("the question mark", [ + tab.visible({ role: "dialog", name: "Keyboard shortcuts" }), + tab.shows(/Search the requests/), + tab.shows(/Next \/ previous request in the panel/), + tab.shows(/Close the panel/), + tab.shows(/Live or Pause for the whole page/), + tab.shows(/Show these shortcuts/), + ]); + await tab.press("Escape"); + await ctx.verify("Escape", [tab.visible({ role: "dialog", name: "Keyboard shortcuts" }, { hidden: true, timeoutMs: 4000 })]); + await ctx.verify("the search has no focus yet", [same("the focused field", await focusedField(tab), "")]); + await tab.press("/"); + await ctx.verify("the slash key", [tab.visible(SEARCH), same("the focused field", await focusedField(tab), "Path, request ID, error…")]); + await tab.page.keyboard.type("missing"); + await ctx.verify("typing without a click", [ + same("the search holds what was typed", await tab.value(SEARCH), "missing"), + tab.shows(/\/fx\/missing/), + tab.shows(/\/fx\/ok/, { not: true, timeoutMs: 4000 }), + ]); + }, + }, + { + id: "copy-curl-copies-the-open-request-as-a-command", + title: "Copy cURL in the request drawer puts the open request on the clipboard as a curl command naming its method, its path with the query, its content type and body and the API origin, and says so in a toast", + entryPoint: "/modules/api/logs?record=", + async run(/** @type {Ctx} */ ctx) { + await raw(ctx, "a call with a query, a header and a body", { method: "POST", path: "/fx/orders/shop1/lines?limit=5", headers: { "content-type": "application/json", "x-tenant": "t1" }, body: JSON.stringify({ sku: "A1", quantity: 2 }) }); + const logs = await settled(ctx, "the call is logged", "/logs", (body) => num(body, "total") === 1); + const detail = await mon(ctx, "the request in full", `/logs/${text(list(logs.body, "results")[0], "_id")}`); + const origin = text(detail.body, "apiOrigin"); + await ctx.verify("the origin the console writes", [check("it is the API's or the dashboard's", origin === ctx.state.apiUrl || origin === ctx.state.webUrl, origin)]); + const tab = await ctx.tab("admin"); + await tab.signIn("admin"); + await openPage(tab, "/modules/api/logs"); + await allowClipboard(tab); + await tab.click({ role: "button", name: "Open request", nth: 0 }); + await tab.click({ role: "button", name: "Copy cURL" }); + const copied = await clipboardText(tab); + await ctx.verify("the clipboard", [ + check("it is a curl command", /^curl\b/.test(copied), copied), + check("it names the method", /-X POST\b/.test(copied), copied), + check("it names the API origin and the path with its query", copied.includes(`${origin}/fx/orders/shop1/lines?limit=5`), copied), + check("it carries the captured content type", /-H 'content-type: application\/json'/i.test(copied), copied), + check("it carries the captured body", copied.includes(JSON.stringify({ sku: "A1", quantity: 2 })), copied), + tab.shows(/cURL copied/), + ]); + }, + }, + { + id: "dragging-the-drawers-left-edge-widens-it-and-it-opens-again-at-that-width", + title: "dragging the left edge of the request drawer to the left widens it, the width is kept for the next opening, and the drawer opens again at that width after the page is reloaded", + entryPoint: "/modules/api/logs?record=", + async run(/** @type {Ctx} */ ctx) { + await traffic(ctx, "two calls", [{ path: "/fx/ok", count: 2 }]); + await settled(ctx, "the logs hold 2", "/logs", (body) => num(body, "total") === 2); + const tab = await ctx.tab("admin"); + await tab.signIn("admin"); + await openPage(tab, "/modules/api/logs"); + await tab.click({ role: "button", name: "Open request", nth: 0 }); + const handle = tab.locator({ role: "separator", name: "Resize the drawer" }); + await handle.waitFor({ state: "visible", timeout: 15_000 }); + const before = await drawerWidth(tab); + const grip = await handle.boundingBox(); + if (!grip) throw new Error("the drawer's edge has no box"); + const x = grip.x + grip.width / 2; + const y = grip.y + grip.height / 2; + await tab.page.mouse.move(x, y); + await tab.page.mouse.down(); + await tab.page.mouse.move(x - 160, y, { steps: 12 }); + await tab.page.mouse.up(); + const widened = await drawerWidth(tab); + await ctx.verify("the drag", [ + check("the drawer is wider after the drag", (widened ?? 0) >= (before ?? 0) + 120, { before, widened }), + same("its edge reports the width", Number(await handle.getAttribute("aria-valuenow")), widened), + ]); + await tab.press("Escape"); + await ctx.verify("closed", [tab.visible(DRAWER, { hidden: true, timeoutMs: 8000 })]); + await tab.click({ role: "button", name: "Open request", nth: 0 }); + await ctx.verify("opened again", [check("the same width", (await drawerWidth(tab)) === widened, await drawerWidth(tab))]); + await tab.reload(); + await tab.locator({ role: "separator", name: "Resize the drawer" }).waitFor({ state: "visible", timeout: 15_000 }); + await ctx.verify("after a reload", [check("the same width", (await drawerWidth(tab)) === widened, await drawerWidth(tab))]); + }, + }, + { + id: "an-open-row-or-an-active-search-holds-the-table-and-says-why", + title: "while a request is open the table says Table on hold · row open, while a search narrows it Table on hold · search active, and the notice goes with the row and the search", + entryPoint: "/modules/api/logs", + knownFailures: { + "an open request says the table is on hold, row open": + "the request panel is a modal `drawer` target; the DMS names the `row open` hold only for a docked `sidePanel` target (useRowSidePanelContent), so an open request holds the table silently behind the '1 new request · Show' pill, and docs/4.usage/1.overview.md (Live mode) promises the notice", + }, + async run(/** @type {Ctx} */ ctx) { + await traffic(ctx, "two calls", [{ path: "/fx/ok", count: 2 }]); + await settled(ctx, "the logs hold 2", "/logs", (body) => num(body, "total") === 2); + const tab = await ctx.tab("admin"); + await tab.signIn("admin"); + await openPage(tab, "/modules/api/logs"); + await ctx.verify("live and nothing open", [tab.visible({ role: "button", name: "All 2" }), tab.shows(/Table on hold/, { not: true, timeoutMs: 2000 })]); + await tab.press("/"); + await tab.page.keyboard.type("fx"); + await ctx.verify("a search", [tab.shows(/Table on hold · search active/)]); + await tab.fill(SEARCH, ""); + await ctx.verify("the search cleared", [tab.shows(/Table on hold/, { not: true, timeoutMs: 4000 })]); + await tab.click({ role: "button", name: "Open request", nth: 0 }); + const rowOpen = await tab.shows(/Table on hold · row open/, { timeoutMs: 3000 }); + await ctx.verify("a row open", [check("an open request says the table is on hold, row open", rowOpen.pass, rowOpen.pass ? "Table on hold · row open" : "no notice")]); + await tab.press("Escape"); + await ctx.verify("the row closed", [tab.visible(DRAWER, { hidden: true, timeoutMs: 8000 }), tab.shows(/Table on hold/, { not: true, timeoutMs: 2000 })]); + }, + }, +]; diff --git a/e2e/journeys/overview.mjs b/e2e/journeys/overview.mjs index 5483629..8524c3c 100644 --- a/e2e/journeys/overview.mjs +++ b/e2e/journeys/overview.mjs @@ -2,5 +2,6 @@ import { guarded } from "../guard.mjs"; import { verdict } from "./overview/verdict.mjs"; import { blocksAndPeriod } from "./overview/blocks-and-period.mjs"; import { comparison } from "./overview/comparison.mjs"; +import { liveShortcut } from "./overview/live-shortcut.mjs"; -export const journeys = guarded([...verdict, ...blocksAndPeriod, ...comparison]); +export const journeys = guarded([...verdict, ...blocksAndPeriod, ...comparison, ...liveShortcut]); diff --git a/e2e/journeys/overview/live-shortcut.mjs b/e2e/journeys/overview/live-shortcut.mjs new file mode 100644 index 0000000..725ec48 --- /dev/null +++ b/e2e/journeys/overview/live-shortcut.mjs @@ -0,0 +1,32 @@ +import { isOn, num, settled, traffic, openPage } from "../../api.mjs"; + +/** @typedef {import("../../api.mjs").Ctx} Ctx */ + +/** The overview journeys about the Live and Pause key. */ +export const liveShortcut = [ + { + id: "l-switches-the-page-between-live-and-pause", + title: "the L key pauses the Overview, which then counts the requests it did not read, the choice holds on the Routes and Request logs pages, and a second press makes the page live again", + entryPoint: "/modules/api/overview", + async run(/** @type {Ctx} */ ctx) { + await traffic(ctx, "before the pause", [{ path: "/fx/ok", count: 2 }]); + await settled(ctx, "counted", "/overview/health", (body) => num(body, "metrics", "requests") === 2); + const tab = await ctx.tab("admin"); + await tab.signIn("admin"); + await openPage(tab, "/modules/api/overview"); + await ctx.verify("live by default", [isOn(tab, { role: "button", name: "Live" })]); + await tab.press("l"); + await ctx.verify("L pauses", [isOn(tab, { role: "button", name: "Pause" })]); + await traffic(ctx, "while paused", [{ path: "/fx/ok", count: 2 }, { path: "/fx/boom", count: 1 }]); + await ctx.verify("the paused page counts what it did not read", [tab.shows(/Paused · 3 new requests · 1 in 5xx/)]); + await openPage(tab, "/modules/api/routes"); + await ctx.verify("the Routes page is paused too", [isOn(tab, { role: "button", name: "Pause" })]); + await openPage(tab, "/modules/api/logs"); + await ctx.verify("and the Request logs", [isOn(tab, { role: "button", name: "Pause" })]); + await tab.press("l"); + await ctx.verify("L makes it live again", [isOn(tab, { role: "button", name: "Live" })]); + await openPage(tab, "/modules/api/overview"); + await ctx.verify("the Overview is live", [isOn(tab, { role: "button", name: "Live" })]); + }, + }, +]; diff --git a/e2e/journeys/routes.mjs b/e2e/journeys/routes.mjs index 798ca91..b4f1e0c 100644 --- a/e2e/journeys/routes.mjs +++ b/e2e/journeys/routes.mjs @@ -2,5 +2,6 @@ import { guarded } from "../guard.mjs"; import { treeAndStatistics } from "./routes/tree-and-statistics.mjs"; import { documentation } from "./routes/documentation.mjs"; import { comparisonAndSnippets } from "./routes/comparison-and-snippets.mjs"; +import { keyboardAndClipboard } from "./routes/keyboard-and-clipboard.mjs"; -export const journeys = guarded([...treeAndStatistics, ...documentation, ...comparisonAndSnippets]); +export const journeys = guarded([...treeAndStatistics, ...documentation, ...comparisonAndSnippets, ...keyboardAndClipboard]); diff --git a/e2e/journeys/routes/keyboard-and-clipboard.mjs b/e2e/journeys/routes/keyboard-and-clipboard.mjs new file mode 100644 index 0000000..b71b03d --- /dev/null +++ b/e2e/journeys/routes/keyboard-and-clipboard.mjs @@ -0,0 +1,53 @@ +import { FIXTURE_ROUTES, check, list, mon, num, raw, same, settled, text, openPage } from "../../api.mjs"; +import { named } from "./shared.mjs"; + +/** @typedef {import("../../api.mjs").Ctx} Ctx */ + +const FILTER = { role: "textbox", name: "Filter by path or handler" }; + +/** The routes journeys about the keyboard and the clipboard. */ +export const keyboardAndClipboard = [ + { + id: "slash-opens-the-route-filter", + title: "the slash key opens the list of routes and puts the focus in its filter, and what is typed narrows the tree", + entryPoint: "/modules/api/routes", + async run(/** @type {Ctx} */ ctx) { + await raw(ctx, "a call so a route is selected", { path: "/fx/boom" }); + await settled(ctx, "the tree", "/routes/list", (body) => list(body, "routes").some((row) => text(row, "ref") === "GET /fx/boom" && num(row, "requests") === 1)); + const tab = await ctx.tab("admin"); + await tab.signIn("admin"); + await openPage(tab, "/modules/api/routes"); + await ctx.verify("the filter is folded away", [tab.visible(FILTER, { hidden: true, timeoutMs: 3000 })]); + await tab.press("/"); + const focused = await tab.page.evaluate(() => (document.activeElement instanceof HTMLInputElement ? document.activeElement.placeholder : "")); + await ctx.verify("the slash key", [tab.visible(FILTER), same("the focused field", focused, "Filter by path or handler")]); + await tab.page.keyboard.type("items"); + await ctx.verify("typing without a click", [same("the filter holds what was typed", await tab.value(FILTER), "items"), tab.shows(new RegExp(`3 of ${FIXTURE_ROUTES} routes · 1 folder`))]); + }, + }, + { + id: "copy-curl-on-a-route-copies-an-example-call", + title: "Copy cURL in a route's header puts an example call on the clipboard: its method, the API origin, the path and query of the last call it answered and its body, and says so in a toast", + entryPoint: "/modules/api/routes?route=POST /fx/orders/:shop/lines", + async run(/** @type {Ctx} */ ctx) { + const ref = "POST /fx/orders/:shop/lines"; + await raw(ctx, "a call", { method: "POST", path: "/fx/orders/shop1/lines?limit=5", headers: { "content-type": "application/json" }, body: JSON.stringify({ sku: "A1", quantity: 2 }) }); + await settled(ctx, "the route is called", `/routes/detail?${named(ref)}`, (body) => num(body, "contract", "exampleBody", "quantity") === 2 || text(body, "state") !== "idle"); + const detail = await mon(ctx, "the route", `/routes/detail?${named(ref)}`); + const origin = text(detail.body, "apiOrigin"); + const tab = await ctx.tab("admin"); + await tab.signIn("admin"); + await openPage(tab, `/modules/api/routes?${named(ref)}`); + await tab.page.context().grantPermissions(["clipboard-read", "clipboard-write"], { origin: new URL(tab.page.url()).origin }); + await tab.click({ role: "button", name: "Copy cURL" }); + const copied = await tab.page.evaluate(() => navigator.clipboard.readText()); + await ctx.verify("the clipboard", [ + check("it is a curl command", /^curl\b/.test(copied), copied), + check("it names the method", /-X POST\b/.test(copied), copied), + check("it names the API origin and the example path and query", copied.includes(`${origin}/fx/orders/shop1/lines?limit=5`), copied), + check("it carries the example body", copied.includes(JSON.stringify({ sku: "A1", quantity: 2 })), copied), + tab.shows(/cURL copied/), + ]); + }, + }, +]; diff --git a/e2e/journeys/settings.mjs b/e2e/journeys/settings.mjs index 1fd2a38..b384c91 100644 --- a/e2e/journeys/settings.mjs +++ b/e2e/journeys/settings.mjs @@ -222,4 +222,41 @@ export const journeys = guarded([ ]); }, }, + { + id: "the-use-default-button-removes-an-override-on-the-page", + title: "Use default on the settings page puts the module's own value in the field, says what it was, and saving removes the override: the console reads the module option, and follows it when the option changes", + entryPoint: "/modules/api/settings", + async run(/** @type {Ctx} */ ctx) { + const SLOW = { role: "spinbutton", name: "Slow request (ms)" }; + const USE_DEFAULT = { role: "button", name: "Use default" }; + const slowOf = async (/** @type {string} */ label) => pick((await mon(ctx, label, "/settings")).body, "requestSlownessThresholdMs"); + const tab = await ctx.tab("admin"); + await tab.signIn("admin"); + await withConfig(ctx, { requestSlownessThreshold: 500 }, async () => { + await saveSettings(ctx, "override the slow threshold", { requestSlownessThresholdMs: 250 }); + await openPage(tab, "/modules/api/settings"); + await ctx.verify("the override", [ + same("the field holds it", await tab.value(SLOW), "250"), + tab.shows(/Module\s+default:\s*500/i), + tab.count(USE_DEFAULT, 1), + ]); + await tab.click(USE_DEFAULT); + await ctx.verify("Use default", [ + same("the field holds the module's value", await tab.value(SLOW), "500"), + tab.shows(/Changed\s*·\s*was\s*250/), + tab.visible({ role: "button", name: "Save changes" }), + same("nothing is saved yet", await slowOf("the override is still stored"), 250), + ]); + await tab.click({ role: "button", name: "Save changes" }); + await ctx.verify("saved", [tab.visible({ role: "button", name: "Save changes" }, { hidden: true, timeoutMs: 8000 }), same("the console reads the module option", await slowOf("after the save"), 500)]); + await openPage(tab, "/modules/api/settings"); + await ctx.verify("a reload", [same("the field holds the module's value", await tab.value(SLOW), "500"), tab.count(USE_DEFAULT, 0)]); + }); + await withConfig(ctx, { requestSlownessThreshold: 700 }, async () => { + await ctx.verify("the override is gone", [same("the console follows the module option again", await slowOf("under another module option"), 700)]); + await openPage(tab, "/modules/api/settings"); + await ctx.verify("the page follows it", [same("the field holds it", await tab.value(SLOW), "700"), tab.count(USE_DEFAULT, 0)]); + }); + }, + }, ]); diff --git a/e2e/journeys/tester.mjs b/e2e/journeys/tester.mjs index d004130..dca1302 100644 --- a/e2e/journeys/tester.mjs +++ b/e2e/journeys/tester.mjs @@ -1,7 +1,9 @@ import { guarded } from "../guard.mjs"; +import { forwarding } from "./tester/forwarding.mjs"; import { saveSettings, check, list, mon, num, pick, raw, same, settled, text, traffic, withConfig, openPage } from "../api.mjs"; /** @typedef {import("../api.mjs").Ctx} Ctx */ +/** @typedef {import("../api.mjs").Tab} Tab */ const TESTER_HEADER = "x-antelopejs-api-source"; @@ -209,4 +211,5 @@ export const journeys = guarded([ void big; }, }, + ...forwarding, ]); diff --git a/e2e/journeys/tester/forwarding.mjs b/e2e/journeys/tester/forwarding.mjs new file mode 100644 index 0000000..0fe180c --- /dev/null +++ b/e2e/journeys/tester/forwarding.mjs @@ -0,0 +1,85 @@ +import { mkdirSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { saveSettings, check, isRow, list, member, mon, num, parseJson, pick, raw, same, settled, text } from "../../api.mjs"; + +/** @typedef {import("../../api.mjs").Ctx} Ctx */ +/** @typedef {import("../../api.mjs").Tab} Tab */ + +/** The Tester journey about its forwarding route, called directly. */ +export const forwarding = [ + { + id: "the-forwarding-route-refuses-unsafe-paths-and-never-forwards-blocked-headers", + title: "POST /api/_dms-api/tester answers 401 without a session and 403 to a member or from another origin, refuses a path that leaves the API (a second slash, a dot segment, an encoded one, a backslash, a fragment, a control character) and a method or a body it does not allow with 400, forwards no Host, Origin, Referer, Forwarded or X-Forwarded-For header to the API while it forwards the others, and fails an answer above 64 KB", + entryPoint: "POST /api/_dms-api/tester", + async run(/** @type {Ctx} */ ctx) { + const defaults = ["content-type", "content-length", "user-agent", "accept", "accept-encoding", "host", "referer", "origin"]; + await saveSettings(ctx, "capture the headers the Tester must not forward", { requestLogCaptureHeaders: [...defaults, "x-forwarded-for", "forwarded", "via", "x-dms-probe", "x-method-override", "x-kept"] }); + await member(ctx, "plain", []); + const route = `${ctx.state.webUrl}/api/_dms-api/tester`; + const owner = await ctx.tab("admin", "owner"); + await owner.signIn("admin"); + const plain = await ctx.tab("plain"); + await plain.signIn("plain"); + /** + * @param {Tab} tab The signed-in tab whose session the call carries + * @param {string} label What the call does + * @param {unknown} data The JSON the route is posted + * @param {string} [origin] The Origin header, the dashboard's own by default + * @returns {Promise<{ status: number, json: unknown }>} The answer + */ + const forward = async (tab, label, data, origin = ctx.state.webUrl) => { + const folder = ctx.step(label); + const response = await tab.page.request.post(route, { data, headers: { origin }, failOnStatusCode: false }); + const body = await response.text(); + mkdirSync(folder, { recursive: true }); + writeFileSync(join(folder, "request.json"), `${JSON.stringify({ method: "POST", url: route, origin, data }, null, 2)}\n`); + writeFileSync(join(folder, "response.json"), `${JSON.stringify({ status: response.status(), body: body.slice(0, 4000) }, null, 2)}\n`); + return { status: response.status(), json: parseJson(body) }; + }; + const call = { method: "GET", path: "/fx/ok", headers: {}, useSession: false }; + const anonymous = await raw(ctx, "no session", { origin: "web", method: "POST", path: "/api/_dms-api/tester", headers: { "content-type": "application/json", origin: ctx.state.webUrl }, body: JSON.stringify(call) }); + const member403 = await forward(plain, "a member's session", call); + const allowed = await forward(owner, "a plain call", call); + const foreign = await forward(owner, "a call from another origin", call, "https://evil.example"); + await ctx.verify("who may forward", [ + same("another origin, even with the owner's session: 403", [foreign.status, text(foreign.json, "error")], [403, "Forbidden"]), + same("without a session: 401", [anonymous.status, text(anonymous.json, "error")], [401, "Not authenticated"]), + same("a member's session: 403", [member403.status, text(member403.json, "error")], [403, "Forbidden"]), + same("the owner's call is forwarded and answered by the route", [allowed.status, num(allowed.json, "status")], [200, 200]), + ]); + const unsafe = ["//evil.example/fx/ok", "https://evil.example/fx/ok", "fx/ok", "/fx/../fx/ok", "/fx/%2e%2e/ok", "/fx/%252e%252e/ok", "/fx/a%2Fb", "/fx\\ok", "/fx/ok#fragment", "/fx/ok\nx", "/fx/ok x"]; + /** @type {[string, number][]} */ + const refused = []; + for (const path of unsafe) refused.push([path, (await forward(owner, `the path ${JSON.stringify(path)}`, { ...call, path })).status]); + await ctx.verify("unsafe paths", refused.map(([path, status]) => same(`${JSON.stringify(path)} is refused with 400`, status, 400))); + /** @type {[string, unknown][]} */ + const others = [ + ["a method the route does not allow", { ...call, method: "TRACE" }], + ["a body on a GET", { ...call, body: "{}" }], + ["a header value that is not text", { ...call, headers: { "x-kept": 1 } }], + ["no useSession", { method: "GET", path: "/fx/ok", headers: {} }], + ["headers that are not an object", { ...call, headers: [] }], + ]; + /** @type {[string, number][]} */ + const invalid = []; + for (const [label, data] of others) invalid.push([label, (await forward(owner, label, data)).status]); + await ctx.verify("invalid calls", invalid.map(([label, status]) => same(`${label} is refused with 400`, status, 400))); + const probe = await forward(owner, "a call with blocked headers", { method: "GET", path: "/fx/items/probe", headers: { host: "evil.example", origin: "https://evil.example", referer: "https://evil.example/page", "x-forwarded-for": "6.6.6.6", forwarded: "for=6.6.6.6", via: "1.1 evil", "x-dms-probe": "1", "x-method-override": "DELETE", "x-kept": "kept" }, useSession: false }); + const logs = await settled(ctx, "the forwarded call is logged", "/logs?limit=20&filter_path=is:%2Ffx%2Fitems%2Fprobe", (body) => list(body, "results").length === 1); + const stored = await mon(ctx, "the forwarded call in full", `/logs/${text(list(logs.body, "results")[0], "_id")}`); + const headers = pick(stored.body, "requestHeaders"); + const received = isRow(headers) ? Object.keys(headers) : []; + await ctx.verify("blocked headers", [ + same("the route answered", probe.status, 200), + same("the header that is not blocked arrives", pick(headers, "x-kept"), "kept"), + check("no blocked header arrives", ["host", "origin", "referer", "x-forwarded-for", "forwarded", "via", "x-dms-probe", "x-method-override"].every((name) => name === "host" ? pick(headers, name) !== "evil.example" : pick(headers, name) === undefined), received), + ]); + const small = await forward(owner, "an answer of 60 KB", { ...call, path: "/fx/blob?size=60000" }); + const large = await forward(owner, "an answer of 70 KB", { ...call, path: "/fx/blob?size=70000" }); + await ctx.verify("the answer limit", [ + same("60 KB comes back whole", [small.status, num(small.json, "status")], [200, 200]), + same("70 KB fails the call with 502", [large.status, text(large.json, "error")], [502, "DMS tester request failed"]), + ]); + }, + }, +]; diff --git a/frontend-vue/package.json b/frontend-vue/package.json index 58125e9..e886d9d 100644 --- a/frontend-vue/package.json +++ b/frontend-vue/package.json @@ -21,7 +21,7 @@ "vue": "^3.5.18" }, "devDependencies": { - "@antelopejs/tooling-configs": ">=0.7.1 <0.8.0", + "@antelopejs/tooling-configs": ">=0.8.9 <0.9.0", "@typescript-eslint/parser": "^8.0.0", "@vitejs/plugin-vue": "^6.0.0", "eslint": "^9.39.5", diff --git a/frontend-vue/pnpm-lock.yaml b/frontend-vue/pnpm-lock.yaml index 5e28831..3fed960 100644 --- a/frontend-vue/pnpm-lock.yaml +++ b/frontend-vue/pnpm-lock.yaml @@ -13,8 +13,8 @@ importers: version: 3.5.22(typescript@6.0.3) devDependencies: '@antelopejs/tooling-configs': - specifier: '>=0.7.1 <0.8.0' - version: 0.7.1 + specifier: '>=0.8.9 <0.9.0' + version: 0.8.9 '@typescript-eslint/parser': specifier: ^8.0.0 version: 8.27.0(eslint@9.39.5(jiti@2.7.0))(typescript@6.0.3) @@ -45,8 +45,8 @@ importers: packages: - '@antelopejs/tooling-configs@0.7.1': - resolution: {integrity: sha512-X/mr/nQEgmFI2dMr3ThMS7HcPaU1amsTU/RNfEnQv46+l7au8cv7unpypCZ0BggnfJHjpk2QG2CTOOllpwj3cw==} + '@antelopejs/tooling-configs@0.8.9': + resolution: {integrity: sha512-DMar3gDUBy73qpAqv8coGCmvIBrZ12FtyYwD+Igqn6jrb92GMxZAuI2YlW9pED9tS3tdk17+aZRIyVO0oDacHA==} engines: {node: '>=22.18.0'} hasBin: true peerDependencies: @@ -54,8 +54,8 @@ packages: eslint-plugin-perfectionist: '>=5.0.0' knip: '>=6.0.0' mongodb-memory-server: '>=10.0.0' - oxfmt: ^0.66.0 || ^0.77.0 - oxlint: 1.81.0 + oxfmt: ^0.66.0 || ^0.77.0 || ^0.79.0 + oxlint: 1.81.0 || 1.94.0 pixelmatch: '>=7.0.0' playwright-core: '>=1.56.0' sharp: '>=0.34.0' @@ -347,8 +347,8 @@ packages: resolution: {integrity: sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==} engines: {node: '>= 8'} - '@oxlint/plugins@1.81.0': - resolution: {integrity: sha512-HhD8kd3r6XpelZkhxhRty/po8V6yK1VV63Eq4kSsOS2IoHUywG3DV2EX+z/ZHw46aLI74Y6aA604NRiAqLKW9w==} + '@oxlint/plugins@1.94.0': + resolution: {integrity: sha512-YT6htikBOBQ00XDxZpRZLZ0anEDo7h9s4+YvjRU0/Ng/cLd0D6SZQ3tsms4g/GDer/z8UKlegC5iptEfyRXJcw==} engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0} '@rolldown/pluginutils@1.0.1': @@ -507,9 +507,125 @@ packages: resolution: {integrity: sha512-WsXQwMkILJvffP6z4U3FYJPlbf/j07HIxmDjZpbNvBJkMfvwXj5ACRkkHwBDvLBbDbtX5TdU64/rcvKJ/vuInQ==} engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0} - '@typescript/typescript6@6.0.2': - resolution: {integrity: sha512-mbCddXd+jm7hfx7w2YU64/Av4/NqqeG3GoRZgxPcgoTxYjhrcfJRw9ULch71SS4G+Q3bOXFhRvPqjguN0Hyp5w==} - hasBin: true + '@typescript/typescript-aix-ppc64@7.0.2': + resolution: {integrity: sha512-MTKKkWB7p/0E9xi1d1tHtZ5PiLkGEMIq88pK2CubZjOsLtYTLqhgIgi6zepFa+9GHZ6h05NMCkQxGKiPXMxXtQ==} + engines: {node: '>=16.20.0'} + cpu: [ppc64] + os: [aix] + + '@typescript/typescript-darwin-arm64@7.0.2': + resolution: {integrity: sha512-gowzar9MwS/aRWp6f3a4KUqzRjAZjOsmGNCM6LcTgXum+dBfgsBVMN+AgvOCCbguXyick6LJhpBszxMebJ8syA==} + engines: {node: '>=16.20.0'} + cpu: [arm64] + os: [darwin] + + '@typescript/typescript-darwin-x64@7.0.2': + resolution: {integrity: sha512-SZ9xZInqApNlNGc9s0W1VSsktYSOe9cFqNOIqmN1Gs8SmkjKZYFt017G4VwPxASInODuAdbTW7sXiFUf893RgA==} + engines: {node: '>=16.20.0'} + cpu: [x64] + os: [darwin] + + '@typescript/typescript-freebsd-arm64@7.0.2': + resolution: {integrity: sha512-W5NH4y/J0plIIS5b2xvTEkU7JFxyqdMAOgf+Ilhl0vHQXKO5dZoxd+C/jEtq56c4F3wk71RB4BMRQ2XdI+bwYQ==} + engines: {node: '>=16.20.0'} + cpu: [arm64] + os: [freebsd] + + '@typescript/typescript-freebsd-x64@7.0.2': + resolution: {integrity: sha512-UMGDx5sTpzNw3WiPebH7l90IWfJggEd+egHt/q6p7/Cm3zqoV7VxkGXt+3DxPIw8CcmvAB0j3sVVfbhX+M4Tpw==} + engines: {node: '>=16.20.0'} + cpu: [x64] + os: [freebsd] + + '@typescript/typescript-linux-arm64@7.0.2': + resolution: {integrity: sha512-Qh4eU4/y3yDjnfjjyPYihMj5/ODIlmt+Bzu17OI+fiSRDW57QmU5SiN63exPRNJPKUzcc1INa1NXdrJ+MqHjUQ==} + engines: {node: '>=16.20.0'} + cpu: [arm64] + os: [linux] + + '@typescript/typescript-linux-arm@7.0.2': + resolution: {integrity: sha512-gffT3xPz9sR7j/YJExkyPntrI0P2EP9XbOyWzth2/Gs0RstK+90RBcO0ncXoXy/beYll1SXw846Nf2zdnEz0QQ==} + engines: {node: '>=16.20.0'} + cpu: [arm] + os: [linux] + + '@typescript/typescript-linux-loong64@7.0.2': + resolution: {integrity: sha512-uEHck9i8hoAzXPiYRib1O7miOnz23SxIeVl6F4LXox+qov1K35jHcEW6VHKvZI+pyvl7fZEP4MCU5LYvIq1GuQ==} + engines: {node: '>=16.20.0'} + cpu: [loong64] + os: [linux] + + '@typescript/typescript-linux-mips64el@7.0.2': + resolution: {integrity: sha512-R4KvAMnE43W5Qeqb0Ly56O3mWMWIAgsMyz36DCaycd5nbg/9kzm0liw3JocfRqyJY0KPmzFjbswozXyW0DnIYA==} + engines: {node: '>=16.20.0'} + cpu: [mips64el] + os: [linux] + + '@typescript/typescript-linux-ppc64@7.0.2': + resolution: {integrity: sha512-DORx5b3sd/4S7eayxm4FQv+A7CrkUIGRaHiwI8oiHTAI1fAPWhF4J0vAlkC8biAlHSVVwxMQ3tjZ2/DVbnQiiA==} + engines: {node: '>=16.20.0'} + cpu: [ppc64] + os: [linux] + + '@typescript/typescript-linux-riscv64@7.0.2': + resolution: {integrity: sha512-wf0jqEDOjrPRnKwYRyyJDRo11KMbvMFrU+q4zqKyChODBzvlkbhNQfKvLxQCcwTpdDaXSHZTVuh0JoCrKCUMHQ==} + engines: {node: '>=16.20.0'} + cpu: [riscv64] + os: [linux] + + '@typescript/typescript-linux-s390x@7.0.2': + resolution: {integrity: sha512-IkwJc3L7yhytWd/ewjyxNDfOmswCm9GWMJT/ue/dU4aZNbwZeYAetq42VyLmsmSjvoX7z74X6ZaYCtzAr0EuGw==} + engines: {node: '>=16.20.0'} + cpu: [s390x] + os: [linux] + + '@typescript/typescript-linux-x64@7.0.2': + resolution: {integrity: sha512-EYdf2cNg7rgCWJnxCdJ+F3V39O8ihb37eHAu1LK8oAFizgTQbPOK7zHHXbPt8rX24COqODXeI3sIf0fCXG7H/A==} + engines: {node: '>=16.20.0'} + cpu: [x64] + os: [linux] + + '@typescript/typescript-netbsd-arm64@7.0.2': + resolution: {integrity: sha512-+polYF4MF04aPpO5FTkHran9yUQDSXqy5GiSDKpsll5jy3l3+g9QLhpf39T+ePtefhXLOGrLl0QIjkQP6VnelA==} + engines: {node: '>=16.20.0'} + cpu: [arm64] + os: [netbsd] + + '@typescript/typescript-netbsd-x64@7.0.2': + resolution: {integrity: sha512-8YIT0EHM/3dq10ZOVF/A7pc/YSMtbcecct4rWtexrnSCHOPcpC2KTLXfTCR6vDpnSiY12heNb1GiN/wu+T/FyA==} + engines: {node: '>=16.20.0'} + cpu: [x64] + os: [netbsd] + + '@typescript/typescript-openbsd-arm64@7.0.2': + resolution: {integrity: sha512-APT8+ClYnuYm1u9+kgGXoMj2VzWzcymwh2gNSQVySHfkRDGOTVkoWLjCmOQSaO+PoqQ57B0flRp9SA+7GnnkzQ==} + engines: {node: '>=16.20.0'} + cpu: [arm64] + os: [openbsd] + + '@typescript/typescript-openbsd-x64@7.0.2': + resolution: {integrity: sha512-yX7s+Q0Dln0Dt9tEzZsAjXXR/+ytBM7AlglaqyeMPxQszJ1JhlJdZ6jLA+IzldHtflX81em7lDao1xXu+aRRkg==} + engines: {node: '>=16.20.0'} + cpu: [x64] + os: [openbsd] + + '@typescript/typescript-sunos-x64@7.0.2': + resolution: {integrity: sha512-dLJDGaLZ1D4HPQn62u1n8mBDkJREwMsAkCdkwd4Ieqw+x3TUyTsqY0YiBCtE6H6OzzgGk3iuZ3vFWRS+E8/d1g==} + engines: {node: '>=16.20.0'} + cpu: [x64] + os: [sunos] + + '@typescript/typescript-win32-arm64@7.0.2': + resolution: {integrity: sha512-Gyl1Vy6OsWesLzmq+EP0Fb7b4Nid5232AvcA2SFcdYreldpNtYFFofPjnt62y9hQy7VTaZp65ICJjuAQRaVcIQ==} + engines: {node: '>=16.20.0'} + cpu: [arm64] + os: [win32] + + '@typescript/typescript-win32-x64@7.0.2': + resolution: {integrity: sha512-0BQ3HkAHHlKLSp1qRvf3SUhGpGsDuhB/jgFw75guyqbxJqEaS0Cw/VFO8i2nHglJUzQCRtMMR/IBAKE3ETMC4g==} + engines: {node: '>=16.20.0'} + cpu: [x64] + os: [win32] '@vitejs/plugin-vue@6.0.10': resolution: {integrity: sha512-b80aUQh3n+qEzzZm5oQp3rT2QImeCx58K6eFl/RkJ3d65KW0kTuv5lNsLRVAjbW9YRUpo/wzmvzMgV34bTAItA==} @@ -1423,14 +1539,35 @@ packages: snapshots: - '@antelopejs/tooling-configs@0.7.1': + '@antelopejs/tooling-configs@0.8.9': dependencies: - '@oxlint/plugins': 1.81.0 - '@typescript/typescript6': 6.0.2 + '@oxlint/plugins': 1.94.0 dts-bundle-generator: 9.5.1 minimatch: 10.2.6 semver: 7.8.5 + typescript: 6.0.3 yaml: 2.9.1 + optionalDependencies: + '@typescript/typescript-aix-ppc64': 7.0.2 + '@typescript/typescript-darwin-arm64': 7.0.2 + '@typescript/typescript-darwin-x64': 7.0.2 + '@typescript/typescript-freebsd-arm64': 7.0.2 + '@typescript/typescript-freebsd-x64': 7.0.2 + '@typescript/typescript-linux-arm': 7.0.2 + '@typescript/typescript-linux-arm64': 7.0.2 + '@typescript/typescript-linux-loong64': 7.0.2 + '@typescript/typescript-linux-mips64el': 7.0.2 + '@typescript/typescript-linux-ppc64': 7.0.2 + '@typescript/typescript-linux-riscv64': 7.0.2 + '@typescript/typescript-linux-s390x': 7.0.2 + '@typescript/typescript-linux-x64': 7.0.2 + '@typescript/typescript-netbsd-arm64': 7.0.2 + '@typescript/typescript-netbsd-x64': 7.0.2 + '@typescript/typescript-openbsd-arm64': 7.0.2 + '@typescript/typescript-openbsd-x64': 7.0.2 + '@typescript/typescript-sunos-x64': 7.0.2 + '@typescript/typescript-win32-arm64': 7.0.2 + '@typescript/typescript-win32-x64': 7.0.2 '@babel/helper-string-parser@7.27.1': {} @@ -1628,7 +1765,7 @@ snapshots: '@nodelib/fs.scandir': 2.1.5 fastq: 1.19.1 - '@oxlint/plugins@1.81.0': {} + '@oxlint/plugins@1.94.0': {} '@rolldown/pluginutils@1.0.1': {} @@ -1754,9 +1891,65 @@ snapshots: '@typescript-eslint/types': 8.27.0 eslint-visitor-keys: 4.2.0 - '@typescript/typescript6@6.0.2': - dependencies: - '@typescript/old': typescript@6.0.3 + '@typescript/typescript-aix-ppc64@7.0.2': + optional: true + + '@typescript/typescript-darwin-arm64@7.0.2': + optional: true + + '@typescript/typescript-darwin-x64@7.0.2': + optional: true + + '@typescript/typescript-freebsd-arm64@7.0.2': + optional: true + + '@typescript/typescript-freebsd-x64@7.0.2': + optional: true + + '@typescript/typescript-linux-arm64@7.0.2': + optional: true + + '@typescript/typescript-linux-arm@7.0.2': + optional: true + + '@typescript/typescript-linux-loong64@7.0.2': + optional: true + + '@typescript/typescript-linux-mips64el@7.0.2': + optional: true + + '@typescript/typescript-linux-ppc64@7.0.2': + optional: true + + '@typescript/typescript-linux-riscv64@7.0.2': + optional: true + + '@typescript/typescript-linux-s390x@7.0.2': + optional: true + + '@typescript/typescript-linux-x64@7.0.2': + optional: true + + '@typescript/typescript-netbsd-arm64@7.0.2': + optional: true + + '@typescript/typescript-netbsd-x64@7.0.2': + optional: true + + '@typescript/typescript-openbsd-arm64@7.0.2': + optional: true + + '@typescript/typescript-openbsd-x64@7.0.2': + optional: true + + '@typescript/typescript-sunos-x64@7.0.2': + optional: true + + '@typescript/typescript-win32-arm64@7.0.2': + optional: true + + '@typescript/typescript-win32-x64@7.0.2': + optional: true '@vitejs/plugin-vue@6.0.10(vite@7.1.10(@types/node@24.2.0)(jiti@2.7.0)(lightningcss@1.33.0)(terser@5.39.0)(yaml@2.9.1))(vue@3.5.22(typescript@6.0.3))': dependencies: diff --git a/package.json b/package.json index ec5578d..5da39ef 100644 --- a/package.json +++ b/package.json @@ -68,9 +68,10 @@ "@antelopejs/dms": ">=0.20.8 <0.21.0", "@antelopejs/dms-frontend": ">=0.11.4 <0.12.0", "@antelopejs/interface-data-api": ">=0.8.0 <0.9.0", - "@antelopejs/tooling-configs": ">=0.8.1 <0.9.0", + "@antelopejs/tooling-configs": ">=0.8.9 <0.9.0", "@playwright/test": "~1.65.0", "@types/node": "^24.0.0", + "@types/semver": "^7.7.0", "knip": "^6.34.0", "lefthook": "^2.2.2", "mongodb-memory-server-core": "^11.0.1", @@ -80,6 +81,7 @@ "release-it": "^19.2.4", "release-it-changelogen": "^0.1.0", "rimraf": "^6.1.3", + "semver": "^7.8.0", "typescript": "^6.0.3", "vitest": "^3.2.4" }, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 68f351e..090d4f8 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -46,14 +46,17 @@ importers: specifier: '>=0.8.0 <0.9.0' version: 0.8.0(@antelopejs/interface-api-util@0.3.0(@antelopejs/interface-api@0.3.3(@antelopejs/interface-core@0.5.1))(@antelopejs/interface-core@0.5.1))(@antelopejs/interface-api@0.3.3(@antelopejs/interface-core@0.5.1))(@antelopejs/interface-core@0.5.1)(@antelopejs/interface-database-decorators@0.5.2(@antelopejs/interface-api@0.3.3(@antelopejs/interface-core@0.5.1))(@antelopejs/interface-core@0.5.1)(@antelopejs/interface-database@0.4.1(@antelopejs/interface-core@0.5.1)))(@antelopejs/interface-database@0.4.1(@antelopejs/interface-core@0.5.1)) '@antelopejs/tooling-configs': - specifier: '>=0.8.1 <0.9.0' - version: 0.8.1(knip@6.41.0)(oxfmt@0.66.0)(oxlint@1.81.0(oxlint-tsgolint@7.0.2004))(playwright-core@1.65.1) + specifier: '>=0.8.9 <0.9.0' + version: 0.8.9(knip@6.41.0)(oxfmt@0.66.0)(oxlint@1.81.0(oxlint-tsgolint@7.0.2004))(playwright-core@1.65.1) '@playwright/test': specifier: ~1.65.0 version: 1.65.1 '@types/node': specifier: ^24.0.0 version: 24.19.2 + '@types/semver': + specifier: ^7.7.0 + version: 7.8.0 knip: specifier: ^6.34.0 version: 6.41.0 @@ -81,6 +84,9 @@ importers: rimraf: specifier: ^6.1.3 version: 6.1.3 + semver: + specifier: ^7.8.0 + version: 7.8.5 typescript: specifier: ^6.0.3 version: 6.0.3 @@ -201,8 +207,8 @@ packages: peerDependencies: '@antelopejs/interface-core': '>=0.2.4 <1.0.0' - '@antelopejs/tooling-configs@0.8.1': - resolution: {integrity: sha512-n/cqWGg2jow3KdVFuhPxYk6EfizzKLVTu9i47pnuZx97UGOYo1GQ22pYu6xgsxKvxCMKOXTLCLjG4GF4qQXwAw==} + '@antelopejs/tooling-configs@0.8.9': + resolution: {integrity: sha512-DMar3gDUBy73qpAqv8coGCmvIBrZ12FtyYwD+Igqn6jrb92GMxZAuI2YlW9pED9tS3tdk17+aZRIyVO0oDacHA==} engines: {node: '>=22.18.0'} hasBin: true peerDependencies: @@ -210,8 +216,8 @@ packages: eslint-plugin-perfectionist: '>=5.0.0' knip: '>=6.0.0' mongodb-memory-server: '>=10.0.0' - oxfmt: ^0.66.0 || ^0.77.0 - oxlint: 1.81.0 + oxfmt: ^0.66.0 || ^0.77.0 || ^0.79.0 + oxlint: 1.81.0 || 1.94.0 pixelmatch: '>=7.0.0' playwright-core: '>=1.56.0' sharp: '>=0.34.0' @@ -1205,8 +1211,8 @@ packages: cpu: [x64] os: [win32] - '@oxlint/plugins@1.81.0': - resolution: {integrity: sha512-HhD8kd3r6XpelZkhxhRty/po8V6yK1VV63Eq4kSsOS2IoHUywG3DV2EX+z/ZHw46aLI74Y6aA604NRiAqLKW9w==} + '@oxlint/plugins@1.94.0': + resolution: {integrity: sha512-YT6htikBOBQ00XDxZpRZLZ0anEDo7h9s4+YvjRU0/Ng/cLd0D6SZQ3tsms4g/GDer/z8UKlegC5iptEfyRXJcw==} engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0} '@phun-ky/typeof@2.0.3': @@ -1384,6 +1390,9 @@ packages: '@types/retry@0.12.5': resolution: {integrity: sha512-3xSjTp3v03X/lSQLkczaN9UIEwJMoMCA1+Nb5HfbJEQWogdeQIyVtTvxPXDQjZ5zws8rFQfVfRdz03ARihPJgw==} + '@types/semver@7.8.0': + resolution: {integrity: sha512-1mAINjtQCXXeLkJ9ehXkwOcBpqtLxiVtKhpUf83DdRNdQKV0iXZpaHYqRr7nj+wvxuJzoAmAwXI+sCNMv1CzLQ==} + '@types/trusted-types@2.0.7': resolution: {integrity: sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw==} @@ -3691,9 +3700,9 @@ snapshots: - supports-color optional: true - '@antelopejs/tooling-configs@0.8.1(knip@6.41.0)(oxfmt@0.66.0)(oxlint@1.81.0(oxlint-tsgolint@7.0.2004))(playwright-core@1.65.1)': + '@antelopejs/tooling-configs@0.8.9(knip@6.41.0)(oxfmt@0.66.0)(oxlint@1.81.0(oxlint-tsgolint@7.0.2004))(playwright-core@1.65.1)': dependencies: - '@oxlint/plugins': 1.81.0 + '@oxlint/plugins': 1.94.0 dts-bundle-generator: 9.5.1 minimatch: 10.2.6 semver: 7.8.5 @@ -4383,7 +4392,7 @@ snapshots: '@oxlint/binding-win32-x64-msvc@1.81.0': optional: true - '@oxlint/plugins@1.81.0': {} + '@oxlint/plugins@1.94.0': {} '@phun-ky/typeof@2.0.3': {} @@ -4512,6 +4521,8 @@ snapshots: '@types/retry@0.12.5': {} + '@types/semver@7.8.0': {} + '@types/trusted-types@2.0.7': optional: true diff --git a/tests/helpers/package.ts b/tests/helpers/package.ts new file mode 100644 index 0000000..cbf21f8 --- /dev/null +++ b/tests/helpers/package.ts @@ -0,0 +1,111 @@ +import { execFileSync } from "node:child_process"; +import { existsSync, readFileSync } from "node:fs"; +import { createRequire } from "node:module"; +import { join } from "node:path"; +import { z } from "zod"; + +const ROOT = join(__dirname, "..", ".."); + +const dependencies = z.record(z.string()).default({}); + +const manifestSchema = z.object({ + version: z.string(), + main: z.string(), + dmsFrontend: z.string(), + antelopeJs: z.object({ skills: z.array(z.string()) }), + dependencies, + optionalDependencies: dependencies, +}); + +const packSchema = z.tuple([ + z.object({ files: z.array(z.object({ path: z.string() })) }), +]); + +const versionSchema = z.object({ version: z.string() }); + +const frontendSchema = z.object({ + engines: z.object({ "@antelopejs/dms-frontend": z.string() }), +}); + +const casesSchema = z.object({ + version: z.number(), + cases: z.array( + z.object({ + id: z.string(), + expect: z.object({ skills: z.array(z.string()) }), + }), + ), +}); + +/** A locale tree read as the dotted keys of its leaves, the empty key standing for a leaf itself. */ +const localeKeysSchema: z.ZodType = z.lazy( + () => + z.union([ + z.string().transform(() => [""]), + z + .record(localeKeysSchema) + .transform((entries) => + Object.entries(entries).flatMap(([key, inner]) => + inner.map((rest) => (rest ? `${key}.${rest}` : key)), + ), + ), + ]), +); + +/** A file of the checkout as text, line endings normalised. */ +export function readText(path: string): string { + return readFileSync(join(ROOT, path), "utf8").replaceAll("\r\n", "\n"); +} + +/** Whether a file of the checkout exists. */ +export function exists(path: string): boolean { + return existsSync(join(ROOT, path)); +} + +/** Runs a command at the checkout's root and returns what it printed; throws on a non-zero exit. */ +export function run(command: string, args: string[]): string { + return execFileSync(command, args, { + cwd: ROOT, + encoding: "utf8", + shell: process.platform === "win32", + stdio: "pipe", + }); +} + +/** The root `package.json`. */ +export function manifest() { + return manifestSchema.parse(JSON.parse(readText("package.json"))); +} + +/** Builds the package, then lists the paths `npm pack` would put in the tarball. */ +export function packedFiles(): string[] { + run("pnpm", ["run", "build"]); + const packed = packSchema.parse( + JSON.parse(run("npm", ["pack", "--dry-run", "--json", "--ignore-scripts"])), + ); + return packed[0].files.map((file) => file.path); +} + +/** The `@antelopejs/dms-frontend` range the Vue layer declares in `engines`. */ +export function rendererRange(): string { + return frontendSchema.parse(JSON.parse(readText("frontend-vue/package.json"))) + .engines["@antelopejs/dms-frontend"]; +} + +/** The version of an installed package, resolved from the checkout's root. */ +export function installedVersion(name: string): string { + const require = createRequire(join(ROOT, "package.json")); + return versionSchema.parse(require(`${name}/package.json`)).version; +} + +/** The cases file of the published skill. */ +export function skillCases() { + return casesSchema.parse(JSON.parse(readText("skills/dms-api/cases.json"))); +} + +/** The dotted keys of every leaf of a locale file of the Vue layer. */ +export function localeKeys(file: string): string[] { + return localeKeysSchema.parse( + JSON.parse(readText(`frontend-vue/i18n/locales/${file}`)), + ); +} diff --git a/tests/package.test.ts b/tests/package.test.ts new file mode 100644 index 0000000..a6c0a02 --- /dev/null +++ b/tests/package.test.ts @@ -0,0 +1,150 @@ +import { satisfies } from "semver"; +import { beforeAll, describe, expect, it } from "vitest"; +import { + exists, + installedVersion, + localeKeys, + manifest, + packedFiles, + readText, + rendererRange, + run, + skillCases, +} from "./helpers/package"; + +describe("the packed tarball", () => { + let files: string[] = []; + + beforeAll(() => { + files = packedFiles(); + }, 120_000); + + it("holds the built entry, the frontend module, the Vue layer and the skill the manifest names", () => { + const { main, dmsFrontend, antelopeJs } = manifest(); + + expect(main).toBe("dist/index.js"); + expect(dmsFrontend).toBe("dist/frontend-module.js"); + expect(antelopeJs.skills).toEqual(["./skills"]); + expect(files).toEqual( + expect.arrayContaining([ + "dist/index.js", + "dist/frontend-module.js", + "frontend-vue/dms.frontend.ts", + "frontend-vue/package.json", + "skills/dms-api/SKILL.md", + "skills/dms-api/cases.json", + ]), + ); + }); + + it("holds nothing outside dist, the Vue layer and the skill but the manifest, licence and readme", () => { + expect( + files + .filter((path) => !/^(dist|frontend-vue|skills)\//.test(path)) + .sort(), + ).toEqual(["LICENSE", "README.md", "package.json"]); + expect(files.filter((path) => path.includes("node_modules/"))).toEqual([]); + }); +}); + +describe("the ranges the docs name", () => { + it("admit the renderer the Vue layer is built against", () => { + expect( + satisfies(installedVersion("@antelopejs/dms-frontend"), rendererRange()), + ).toBe(true); + }); + + it("admit this version in the installation docs", () => { + const installation = readText("docs/2.installation.md"); + const range = /version: "([^"]+)"/.exec(installation)?.[1] ?? ""; + + expect(installation).toContain('package: "@antelopejs/dms-api"'); + expect(satisfies(manifest().version, range)).toBe(true); + }); + + it("list every interface the module depends on in the README table", () => { + const readme = readText("README.md"); + const table = readme.slice( + readme.indexOf("antelopejs-docs-compat:start"), + readme.indexOf("antelopejs-docs-compat:end"), + ); + const { dependencies, optionalDependencies } = manifest(); + const interfaces = [ + ...Object.keys(dependencies), + ...Object.keys(optionalDependencies), + ].filter((name) => name.startsWith("@antelopejs/interface-")); + + expect(interfaces.length).toBeGreaterThan(0); + expect(interfaces.filter((name) => !table.includes(`\`${name}\``))).toEqual( + [], + ); + }); +}); + +describe("the skill", () => { + it("is named dms-api and names the three automation nodes", () => { + const skill = readText("skills/dms-api/SKILL.md"); + + expect(skill.startsWith("---\nname: dms-api\n")).toBe(true); + for (const node of [ + "api.route-unhealthy", + "api.get-api-health", + "api.query-request-logs", + ]) { + expect(skill).toContain(node); + } + }); + + it("has version 1 cases with unique ids, some expecting the skill", () => { + const { version, cases } = skillCases(); + + expect(version).toBe(1); + expect(cases.length).toBeGreaterThan(0); + expect(new Set(cases.map((entry) => entry.id)).size).toBe(cases.length); + expect(cases.some((entry) => entry.expect.skills.includes("dms-api"))).toBe( + true, + ); + }); +}); + +describe("the docs and the locales", () => { + const pages = new Map([ + ["introduction", "1.introduction.md"], + ["installation", "2.installation.md"], + ["configuration", "3.configuration.md"], + ["extending", "5.extending.md"], + ["faq", "6.faq.md"], + ["usage/overview", "4.usage/1.overview.md"], + ["usage/request-logs", "4.usage/2.request-logs.md"], + ["usage/routes", "4.usage/3.routes.md"], + ["usage/settings", "4.usage/4.settings.md"], + ]); + + it("link only console pages that exist", () => { + const files = [...pages.values()].map((file) => `docs/${file}`); + const docs = files.map(readText).join("\n"); + const targets = [...docs.matchAll(/\/docs\/modules\/api\/([a-z/-]+)/g)].map( + (match) => match[1] ?? "", + ); + + expect(files.filter((file) => !exists(file))).toEqual([]); + expect(targets.filter((target) => !pages.has(target))).toEqual([]); + expect(readText("README.md")).toContain( + "https://dms.antelopejs.com/docs/modules/api", + ); + expect(readText("docs/.navigation.yml")).toContain("title: API"); + }); + + it("hold the same keys in English and French", () => { + const english = localeKeys("api-en-GB.json").sort(); + + expect(english.length).toBeGreaterThan(50); + expect(localeKeys("api-fr-FR.json").sort()).toEqual(english); + }); +}); + +describe("the verify feature map", () => { + it("covers every user-facing file, and every feature has its journeys", () => { + expect(() => run("pnpm", ["exec", "dms-control", "map"])).not.toThrow(); + }); +});