From 96d45268b53088a363e9221862334452b75fe129 Mon Sep 17 00:00:00 2001 From: Antony Rizzitelli Date: Thu, 19 Nov 2026 14:01:52 +0000 Subject: [PATCH 1/4] chore: drop the verify-dms-database skill --- .agents/skills/formal-table-watch/SKILL.md | 6 +- .agents/skills/verify-dms-database/SKILL.md | 101 -------------- .../verify-dms-database/features/README.md | 22 --- .../verify-dms-database/features/access.md | 57 -------- .../verify-dms-database/features/config.md | 53 ------- .../verify-dms-database/features/data.md | 132 ------------------ .../verify-dms-database/features/diagram.md | 115 --------------- .../verify-dms-database/features/editing.md | 104 -------------- .../verify-dms-database/features/extending.md | 59 -------- .../verify-dms-database/features/external.md | 72 ---------- .../verify-dms-database/features/guard.md | 56 -------- .../verify-dms-database/features/library.md | 65 --------- .../verify-dms-database/features/overview.md | 62 -------- .../verify-dms-database/features/package.md | 45 ------ .../verify-dms-database/features/query.md | 81 ----------- .../verify-dms-database/features/schemas.md | 102 -------------- .../verify-dms-database/features/smoke.md | 26 ---- .../skills/verify-dms-database/package.json | 1 - .../skills/verify-dms-database/tsconfig.json | 14 -- .../verify-dms-database/verify.config.ts | 115 --------------- AGENTS.md | 4 +- 21 files changed, 5 insertions(+), 1287 deletions(-) delete mode 100644 .agents/skills/verify-dms-database/SKILL.md delete mode 100644 .agents/skills/verify-dms-database/features/README.md delete mode 100644 .agents/skills/verify-dms-database/features/access.md delete mode 100644 .agents/skills/verify-dms-database/features/config.md delete mode 100644 .agents/skills/verify-dms-database/features/data.md delete mode 100644 .agents/skills/verify-dms-database/features/diagram.md delete mode 100644 .agents/skills/verify-dms-database/features/editing.md delete mode 100644 .agents/skills/verify-dms-database/features/extending.md delete mode 100644 .agents/skills/verify-dms-database/features/external.md delete mode 100644 .agents/skills/verify-dms-database/features/guard.md delete mode 100644 .agents/skills/verify-dms-database/features/library.md delete mode 100644 .agents/skills/verify-dms-database/features/overview.md delete mode 100644 .agents/skills/verify-dms-database/features/package.md delete mode 100644 .agents/skills/verify-dms-database/features/query.md delete mode 100644 .agents/skills/verify-dms-database/features/schemas.md delete mode 100644 .agents/skills/verify-dms-database/features/smoke.md delete mode 100644 .agents/skills/verify-dms-database/package.json delete mode 100644 .agents/skills/verify-dms-database/tsconfig.json delete mode 100644 .agents/skills/verify-dms-database/verify.config.ts diff --git a/.agents/skills/formal-table-watch/SKILL.md b/.agents/skills/formal-table-watch/SKILL.md index ffba8394..6cba3fad 100644 --- a/.agents/skills/formal-table-watch/SKILL.md +++ b/.agents/skills/formal-table-watch/SKILL.md @@ -5,7 +5,7 @@ description: TLA+ model of the database.table-watch automation trigger of @antel # Formal check: the table-watch trigger -The `database.table-watch` trigger turns a table's change feed into automation runs. `activate()` opens a cursor on the feed and waits up to `ACTIVATION_PROBE_MS` (2 s) for an early failure. A pump then reads the cursor and calls `emit()` for each change. When a read fails, or the feed ends on its own, the pump waits `RECONNECT_DELAY_MS` (5 s), closes the cursor and opens a new one, once. `deactivate()` sets `handle.stopped` and closes the cursor. A break here makes automations stop firing without a sign, fire after `deactivate()`, fire twice, or leave a change stream open on the server. `src/test/table-watch-feed.test.ts` and the `extending` feature of `verify-dms-database` drive a healthy feed on a replica set; neither reaches a feed failure, a reconnect or a `deactivate()` during a read. +The `database.table-watch` trigger turns a table's change feed into automation runs. `activate()` opens a cursor on the feed and waits up to `ACTIVATION_PROBE_MS` (2 s) for an early failure. A pump then reads the cursor and calls `emit()` for each change. When a read fails, or the feed ends on its own, the pump waits `RECONNECT_DELAY_MS` (5 s), closes the cursor and opens a new one, once. `deactivate()` sets `handle.stopped` and closes the cursor. A break here makes automations stop firing without a sign, fire after `deactivate()`, fire twice, or leave a change stream open on the server. `src/test/table-watch-feed.test.ts` and the `extending` spec of `e2e` drive a healthy feed on a replica set; neither reaches a feed failure, a reconnect or a `deactivate()` during a read. Node runs other callbacks at every `await`, so the model makes each stretch of code between two awaits one step, and each answer of a cursor one step. TLC checks every order of those steps, with row changes, feed failures and `deactivate()` calls, within the bounds below. @@ -42,7 +42,7 @@ A finding is judged by the length of its shortest counterexample alone. A change ## When to run it -Run `--full` when a change touches `src/automation/tableWatch.ts` or this folder. CI runs the CI configuration on every push (job `formal-table-watch`, in the `ubuntu` gate). `dms-control formal` runs it when the `formal` list of `.agents/skills/verify-dms-database/verify.config.ts` names `formal-table-watch`. +Run `--full` when a change touches `src/automation/tableWatch.ts` or this folder. CI runs the CI configuration on every push (job `formal-table-watch`, in the `ubuntu` gate). ## The rules @@ -99,7 +99,7 @@ Replay a counterexample with the fake table above, one action per step, and asse | `PumpReopen` | the close's end, then `openFeed` or its throw (lines 241-250) | | `Deactivate`, `DeactivateReturns` | `deactivate()` (lines 360-364) | -The sync commit is `d14f337` on AntelopeJS/dms-database `feat/verify-dms-database-skill`. `tableWatch.ts` last changed in `78f995c`. +The sync commit is `d14f337`. `tableWatch.ts` last changed in `78f995c`. ## Bounds and what is left out diff --git a/.agents/skills/verify-dms-database/SKILL.md b/.agents/skills/verify-dms-database/SKILL.md deleted file mode 100644 index 9e9b4684..00000000 --- a/.agents/skills/verify-dms-database/SKILL.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -name: verify-dms-database -description: "Drive the AntelopeJS dms-database module (the Database console: Overview, Schemas, Diagram, Data browser, Query console, saved and shared queries) the way the platform owner does, inside a DMS with free ports, its own MongoDB database and a playground of schemas, and report a verdict with evidence. Use to prove a change to AntelopeJS/dms-database works before merge, or to verify a PR." ---- - -# Verify dms-database - -The scripted journeys are a Playwright suite in the repository's `e2e/` folder: `e2e/journeys/.mjs` holds a feature's journeys, `e2e/specs/.spec.ts` registers them, and CI runs the ones tagged `@smoke` on a pull request and every journey in the merge queue and the nightly. You choose which features to run, judge what they show, and look at the product yourself with `dms-control`; you never write a multi-step shell recipe. When a journey you need does not exist, add it to `e2e/journeys/.mjs`, describe it in its feature file, and run its spec. - -`dms-control` is the bin of `@antelopejs/dms`, a devDependency of this repository. Run it with Node 24 after `pnpm install`: - -```bash -C="pnpm exec dms-control" -$C # lists every command -``` - -Give `doors` and `--skill` absolute paths when you run them from another folder. - -## Launch - -```bash -RUN=$($C up --prepare --base origin/main) # installs, builds, starts; prints the run folder -``` - -`--prepare` runs the `prepare` commands of `verify.config.ts`: the frozen install, the build of the module, the link of the verification playground's `node_modules` to the repository's, and the TypeScript build of the playground's fixture module. Without it `up` uses the builds already there, and `doctor` fails on a stale one. `up` reads the playground from `verify.config.ts` (`e2e/playground/`, which the Playwright suite starts too) and starts an isolated DMS: - -- the checkout is laid out again under `$RUN/root`, every sibling linked, and the playground copied without `node_modules`, so the run's build and `.antelope/` are its own; -- the API and the dashboard get free ports from the kernel, and `HOME` is `$RUN/home`; -- a `mongod` the run owns serves `verify_` databases, as the only member of a replica set, so change streams work; -- the backend runs `ajs project start -e docs`, the dashboard `ajs dms start -e docs -b `. - -The playground (`e2e/playground/src`) registers the schemas the journeys read: `demo` (posts, comments, tags), `shop` (customers, products, orders, order_items, with the `eu` and `us` instances), `vault` (accounts with hashed, encrypted and localized columns, a 17-column table, related tables), `metrics` (`readings` with 1,250 rows and an empty `empty_log`) and eight schemas named for the built-in labels (`app-site`, `core`, `global`, `staging-eu`, `reviews`, `production`, `billing`, `tenant-acme`). Its fixture controller makes a member with a role of given permissions (`POST /verify-database/member`). - -## Doctor - -```bash -$C doctor "$RUN" # prints only failing checks; --verbose prints all -``` - -Do not drive a run that fails doctor. - -## Drive - -```bash -$C plan --base origin/main # the diff mapped to features; unmapped surfaces -pnpm e2e:build # once: the module, the playground and the dashboard -pnpm e2e:run specs/smoke.spec.ts specs/.spec.ts -pnpm e2e:run -g # one journey -pnpm exec playwright show-trace e2e/test-results//trace.zip -``` - -- Run the spec of every feature `plan` lists as `run`, plus `smoke`, with at most two spec files per command. The suite needs no `up`: each Playwright worker starts its own MongoDB replica set, backend and dashboard on free ports and stops them when the run ends. A feature takes up to several minutes (diagram, schemas, data and editing are the longest), so start it in the background and wait for its output. -- A failed journey keeps its trace and the backend log of its last start under `e2e/test-results//`; read them before you judge the failure. A journey whose backend or dashboard ended by itself says so in its failure. -- Each feature file in [features/](features/README.md) lists its source globs (`covers:`), its docs pages (`docs:`), its journeys and a coverage table; the journeys are in `e2e/journeys/.mjs` and `e2e/journeys/parts/`, with the helpers they share in `e2e/database.mjs` (requests, checks, members, configuration switches). -- A journey starts on an empty database with the administrator onboarded and the backend restarted on it, so configuration switches are gone and the playground has seeded its schemas again. It reads every mutation back through a second view: the API, a reload, another tab, another account, or a backend restart. -- `withConfig(ctx, { VERIFY_DATABASE_*: … }, body)` restarts the backend with module options set (`DRIVER_LABEL`, `SCHEMA_LABELS`; see `e2e/playground/antelope.config.ts`) and restarts it again without them. -- To look at the product yourself, drive the run `up` started: `$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/`. -- `dms-control map`, `journey` and `verdict` read the journeys from this folder, which no longer holds them, so they do not work for this skill; `plan` and `doors` do. `src/test/feature-map.test.ts` in `pnpm test` does what `map` checked. - -## Evidence - -The suite reports each journey as a Playwright test named by its id, its steps named like `admin click button "Login"` and each check as a soft expectation `name: what was seen`. A failed test keeps its trace (`trace.zip`), its error context and the backend log under `e2e/test-results/`. The control commands write theirs under `$RUN/evidence/`: `action.json`, `url.txt`, `aria.yml` and `screenshot.png` for a browser step, `request.json` and `response.json` for a request. Read the evidence before you judge a PASS: a check passing proves only what it asserts. - -## Cleanup - -```bash -$C down "$RUN" -``` - -## Verdict rules - -1. **Run every feature whose `covers:` globs the diff touches, plus the smoke journey.** `plan` prints that list as `run`. -2. **Unmapped surface fails the verdict.** User-facing code is `src/**`, `frontend-vue/**`, `skills/**` and `package.json`, tests and tool configs excluded (`verify.config.ts`). `plan` lists the unmapped surfaces of the diff. -3. **Every registered journey of a feature in `run` must have run and passed.** Read it from the Playwright report of the spec runs: no test failed, was flaky or did not run. A known finding is a check its journey's `knownFailures` names, with the finding the feature file's Gotchas describe: the check is annotated `known failure` while the product still fails it, and fails the test once it passes. Every other check of that journey still counts. -4. **Docs.** Judge every `docs:` page of each touched feature against what the journeys showed. -5. **Formal checks.** [`formal-table-watch`](../formal-table-watch/SKILL.md) covers the table-watch trigger (`src/automation/tableWatch.ts`): `$C formal "$RUN"` runs it when the diff touches its files. Its two recorded findings fail a verdict only when the diff changes the covered behaviour. [`formal-access-write-back`](../formal-access-write-back/SKILL.md) covers the access write-back (`src/service/connectionState.ts`, `src/config.ts`) over any shape of `externalConnections`; it has no recorded finding, so any failure fails the verdict. -6. **One-way doors.** The section comes right after the result line and is mandatory. `$C doors` prints the `One-way-door:` line for the diff. -7. **Result.** FAIL if any of rules 1 to 6 fail. PASS+NOTES when something is not verified or needs the owner's attention. PASS otherwise. - -Report the verdict in your own reply: the result line, the one-way doors, the specs you ran with their passed, failed and expected-failure counts, the docs judged, what is not verified and what needs attention. - -## Gotchas - -- Every dashboard page renders on the server and hydrates after `load`; a click that lands first does nothing. Every `tab` action waits for the page to hydrate before and after it, the journeys click again until what the click opens shows, and `tab.signIn` waits for the sign-in form to hydrate. -- The suite's browser is 1280 px wide. Journeys that need another width set the viewport. -- A journey whose backend or dashboard stopped answering fails, and the failure says which process ended. -- Pages and routes are owner-only: members hold no module permission, so a member is only used to prove a refusal. - -## Not driven - -List these as not verified in every verdict: - -- the Table watch trigger's failure on a standalone MongoDB and its one reconnect: the suite's MongoDB is a replica set, and a journey cannot break its change stream; -- the Overview's empty schema-cards state: the DMS registers its own schemas, so the list is never empty; -- the Diagram's name order of the tables without relations: `frontend-vue/tests/diagramLayout.test.ts` checks it, no journey does (see the diagram feature); -- the supported extension boundary (root barrel exports, no subclassing contract): a statement of non-support has no observable effect; -- the role editor hiding one block per role: pages stay owner-only, so a hidden block has no effect an owner can see. - -## Feature map - -[features/README.md](features/README.md). diff --git a/.agents/skills/verify-dms-database/features/README.md b/.agents/skills/verify-dms-database/features/README.md deleted file mode 100644 index 38463d31..00000000 --- a/.agents/skills/verify-dms-database/features/README.md +++ /dev/null @@ -1,22 +0,0 @@ -# Feature map - -One file per feature. `covers:` lists the source globs it owns, `docs:` the pages a verdict judges, and `e2e/journeys/.mjs` its journeys, which `e2e/specs/.spec.ts` registers with the Playwright suite. `src/test/feature-map.test.ts`, in `pnpm test`, checks that every user-facing file is covered, that every docs page exists and that every journey is named in a feature file. Each file ends with a Coverage table: every documented behaviour either names the journey that asserts it or says why it is not driven. - -| Feature | What the user does | Journeys | -|---|---|---| -| [smoke](smoke.md) | # Smoke | smoke | -| [overview](overview.md) | # Overview | the-connection-card-reads-the-probe, a-configured-driver-label-shows-beside-the-age, without-a-driver-label-the-card-shows-a-dash, the-card-age-counts-up-and-the-probe-repeats-every-thirty-seconds, schema-cards-list-every-schema-largest-first, largest-tables-rank-the-default-instances-by-rows, recent-queries-list-your-last-five-runs, the-header-buttons-lead-to-the-working-pages, an-unreachable-database-shows-unavailable-and-check-again-recovers | -| [config](config.md) | # Config | a-label-takes-each-of-the-seven-tones | -| [access](access.md) | # Access | a-member-sees-neither-the-pages-nor-the-catalog-tile, the-catalog-tile-reads-the-database | -| [schemas](schemas.md) | # Schemas | each-filter-of-the-bar-narrows-the-list-and-sets-its-own-url-key, the-url-restores-every-filter-after-a-reload-and-clear-removes-them, slash-focuses-the-search-field-but-not-while-typing-or-with-a-modifier, a-filter-that-matches-nothing-says-no-result-and-clear-filters-restores-the-list, each-of-the-five-sortable-columns-sorts-both-ways-and-the-third-click-restores-the-default-order, the-relations-and-modifiers-columns-name-the-tables-and-the-flags, a-row-click-opens-the-inspector-and-previous-next-j-and-k-step-through-the-list, dragging-the-drawer-edge-resizes-it-and-it-opens-at-the-width-you-left-it, the-inspector-states-the-counts-and-lists-each-column-with-its-type-null-and-notes, a-column-named-constructor-is-listed-like-any-other-column, the-indexes-and-relations-tabs-list-what-the-table-declares-and-a-relation-opens-the-other-table, the-sample-row-tab-shows-one-row-and-another-row-pages-through-the-table, browse-query-and-diagram-actions-open-the-other-pages-on-the-same-table | -| [diagram](diagram.md) | # Diagram | tables-list-their-columns-with-types-and-icons-and-relations-are-arrows, an-encrypted-column-carries-the-lock-icon-of-the-legend, a-table-of-more-than-twelve-columns-comes-folded-and-folding-is-not-saved, folding-is-a-setting-of-your-own-view-and-is-not-saved-with-the-team-layout, finding-a-column-a-folded-table-hides-unfolds-that-table, the-fold-keeps-the-twelve-column-boundary-and-every-column-an-arrow-ends-on, a-large-schema-opens-at-forty-percent-on-its-top-left-and-fit-view-shows-it-whole, a-relation-to-a-table-not-drawn-ends-on-a-dashed-chip-that-opens-that-table, a-relation-to-another-schema-ends-on-a-chip-that-opens-that-table, the-url-picks-the-schema-and-the-table-and-names-what-it-cannot-find, a-schema-without-a-table-says-so-and-offers-no-note-or-auto-layout, dragging-a-table-saves-the-layout-and-everyone-reads-it, a-table-not-placed-yet-takes-its-automatic-place-and-placed-tables-stay, auto-layout-previews-the-arrangement-and-keep-or-discard-decides, auto-layout-keeps-groups-together-and-clear-of-notes-that-never-move, n-and-the-note-button-drop-a-note-ready-to-write-and-it-is-saved-with-the-schema, a-double-click-edits-a-note-and-the-trash-button-and-delete-remove-it, notes-belong-to-their-schema-and-everyone-reads-them, undo-and-redo-cover-every-move-and-note-and-are-saved, escape-leaves-the-find-field-then-lifts-the-focus-then-clears-the-selection | -| [data](data.md) | # Data | the-sidebar-counts-each-table-in-the-picked-instance, tables-open-as-preview-tabs-and-are-kept-on-demand, links-open-the-table-in-the-instance-they-name, search-filters-and-sort-narrow-and-order-the-rows, the-footer-pages-1250-rows-with-exact-ranges-at-every-size, r-refreshes-the-rows-and-the-search-shortcut-works-from-the-grid, the-row-drawer-steps-through-the-page-with-j-and-k, the-row-drawer-shows-fields-json-and-the-rows-pointing-at-it, the-fields-tab-widens-long-values-and-sets-null-with-the-dashed-circle, all-instances-is-a-read-only-view-with-the-instance-column, recently-opened-tables-are-offered-when-no-tab-is-open, no-match-and-empty-tables-say-so, a-refused-read-shows-the-error-and-try-again-reads-it-again | -| [editing](editing.md) | # Editing | edits-are-staged-then-reviewed-then-written-one-put-per-row, invalid-drafts-are-refused-esc-cancels-and-a-click-away-decides, null-empties-a-cell-and-backslash-null-is-the-text-null, object-and-array-cells-open-the-json-editor-in-a-side-drawer, the-json-editor-is-as-tall-as-the-drawer, discard-and-closing-a-tab-with-staged-changes-ask-first, undo-writes-the-previous-values-back-within-the-window, undo-is-offered-for-ten-seconds-then-the-values-stay, a-row-deleted-meanwhile-drops-its-changes-and-the-rest-is-saved, a-failed-write-stops-the-save-and-the-rows-left-stay-staged, a-saved-row-shows-in-place-unless-the-save-may-move-rows, a-save-under-a-search-or-a-filter-reads-the-page-again, an-edit-and-its-undo-land-in-the-instance-of-the-tab-only, saved-cells-keep-their-type-numbers-booleans-dates-and-objects, hashed-encrypted-and-localized-columns-are-written-as-typed, the-row-drawer-stages-edits-like-the-cells-do, an-undo-whose-write-fails-keeps-the-saved-values-and-offers-undo-again | -| [query](query.md) | # Query | a-query-returns-its-rows-in-the-order-it-asks, an-instance-and-every-instance-are-targeted, a-failed-query-says-what-failed-and-offers-the-nearest-name, the-insert-chips-add-their-operation, ctrl-space-completes-schemas-and-tables-from-the-workspace, an-empty-console-offers-examples-built-on-your-own-tables, results-over-1000-rows-are-cut-at-1000, the-table-view-shows-every-returned-row, an-export-of-uneven-rows-keeps-every-key-in-csv-and-json, csv-quotes-a-comma-a-quote-and-a-line-break-so-the-cell-reads-back, format-strips-trailing-spaces-and-blank-lines, ctrl-space-inside-a-filter-completes-the-columns-of-the-table, the-chart-plots-the-first-numeric-column-with-pickers-for-both-axes, open-in-data-browser-opens-the-target-table-or-the-row, copy-as-json-puts-the-returned-rows-on-the-clipboard, a-link-opens-the-console-on-the-table-in-the-instance-it-names | -| [guard](guard.md) | # Guard | a-delete-names-its-operation-target-and-rows-and-waits-for-the-table-name, every-write-names-its-operation-and-counts-the-rows-it-would-touch, confirming-a-single-row-update-needs-the-table-name-as-the-docs-say, a-confirmed-write-acts-on-the-data-of-that-moment, a-read-query-runs-straight-away | -| [library](library.md) | # Library | history-keeps-your-last-500-runs-newest-first, history-records-failures-and-writes-with-their-status, history-is-searchable-and-clearing-it-keeps-the-saved-queries, a-saved-query-needs-a-name-and-can-be-edited-and-deleted, a-shared-query-reaches-the-team-and-only-its-author-changes-it, history-belongs-to-its-user-and-a-link-restores-a-run, history-groups-runs-by-day-with-yesterday-and-older-dates, a-history-row-without-a-status-reads-as-ok | -| [extending](extending.md) | # Extending | deep-links-open-the-documented-pages-on-the-table, without-the-automation-module-the-trigger-registration-is-a-silent-no-op | -| [external](external.md) | # External | an-external-database-is-picked-browsed-edited-and-left, an-external-database-refuses-what-it-cannot-serve-with-sentences | -| [package](package.md) | # Package | none: `src/test/package.test.ts` checks the tarball, the locales and the ranges | - -The smoke journey runs on every verdict. diff --git a/.agents/skills/verify-dms-database/features/access.md b/.agents/skills/verify-dms-database/features/access.md deleted file mode 100644 index 4454b582..00000000 --- a/.agents/skills/verify-dms-database/features/access.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -covers: - - src/module.ts - - src/routes/index.ts - - src/pages/index.ts - - src/db/** - - src/routes/health.ts - - src/routes/data.ts -docs: - - docs/1.introduction.md - - docs/6.faq.md - - README.md ---- - -# Access - -The pages and the module's API answer to the platform owner only, and the module shows in the Modules catalog. - -## Sub-features - -- `every-route-needs-a-signed-in-session`: every read and write route answers 401 without a session. Integration test in `src/test/access.journeys.test.ts`. -- `a-member-gets-403-from-every-route-and-writes-nothing`: a member with the module's permissions gets 403 from every route and changes nothing. Integration test in `src/test/access.journeys.test.ts`. -- `a-member-sees-neither-the-pages-nor-the-catalog-tile`: no tile and no page for a member; the owner sees the tile. -- `the-catalog-tile-reads-the-database`: the tile's two readout lines, version and category. -- `the-owner-only-gate-is-logged-at-start`: the owner-only gate the start log reports, each of the five pages' layout routes answering the owner and refusing a member with the module's permissions. Integration test in `src/test/access.journeys.test.ts`. - -## How to get to it (user POV) - -- Modules catalog, tile Database; `/modules/database/*`. - -## Driving it - -```bash -pnpm e2e:run specs/access.spec.ts -``` - -The journeys marked integration test run in `pnpm test`; one file alone after `pnpm run build`: - -```bash -pnpm exec ajs module test . -f dist/test/access.journeys.test.js -``` - -## Gotchas - -- The member is made by the playground's fixture (`POST /verify-database/member`) with a role of the given permission ids. -- The integration tests make it with `createMemberWithRole` (`src/test/ownerSession.ts`). - -## Coverage - -| Documented behaviour | Journey and check | -|---|---| -| Pages reserved to the platform owner; routes answer only to the owner | the first three journeys | -| Tenants and their members never see it | `a-member-sees-neither-the-pages-nor-the-catalog-tile` | -| Adds a Database entry to the Modules catalog | `the-catalog-tile-reads-the-database` | -| FAQ: the backend logs the owner-only gate at start | `the-owner-only-gate-is-logged-at-start`: the integration test checks the gate the line reports, each page's layout route under `/modules/database/` answering the owner and refusing a member with the module's permissions; the line itself is written once at start, before a test can listen | -| Own tables (`dms-database` schema) hold layouts, notes, history, saved queries | `schemas` feature lists the schema; persistence journeys of `diagram` and `library` | -| Blocks carry names so the role editor can hide one per role | Not driven: the role editor lists blocks of pages the owner alone reaches; a hidden block has no observable effect on the owner | diff --git a/.agents/skills/verify-dms-database/features/config.md b/.agents/skills/verify-dms-database/features/config.md deleted file mode 100644 index 6a957c7f..00000000 --- a/.agents/skills/verify-dms-database/features/config.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -covers: - - src/config.ts - - src/service/schemaLabels.ts -docs: - - docs/3.configuration.md - - docs/5.extending.md ---- - -# Config - -The `schemaLabels` option and the built-in patterns that badge schemas. - -## Sub-features - -- `built-in-patterns-label-schemas-by-the-start-of-their-id`: with no configuration, app, core, global, staging, reviews and production schemas get their label and tone; others get none. Integration test in `src/test/config.journeys.test.ts`. -- `an-exact-key-beats-a-pattern-which-beats-a-built-in-label`: the resolution order, and that the first matching `*` key wins. Integration test in `src/test/config.journeys.test.ts`. -- `a-glob-key-matches-the-whole-schema-id`: a `*` key labels a schema only when it covers the whole id, from its first to its last character. Integration test in `src/test/config.journeys.test.ts`. -- `a-label-takes-each-of-the-seven-tones`: each tone, the primary default, and that options are read at start. - -## How to get to it (user POV) - -- `config` block of the `dms-database` entry; the badge shows on the Overview's schema cards and in the pickers. - -## Driving it - -```bash -pnpm e2e:run specs/config.spec.ts -``` - -The journeys marked integration test run in `pnpm test`; one file alone after `pnpm run build`: - -```bash -pnpm exec ajs module test . -f dist/test/config.journeys.test.js -``` - -## Gotchas - -- The integration tests read the `schemaLabels` the test harness sets (`src/test/schemaLabelConfig.ts`), whose keys match only their own schemas; the built-in journey removes the option with `setModuleConfig` for its run. -- `withConfig` restarts the backend with `VERIFY_DATABASE_SCHEMA_LABELS` (`key:Label:tone;...`) and again without it. - -## Coverage - -| Documented behaviour | Journey and check | -|---|---| -| Resolution order: exact id, first `*` key, built-in | `an-exact-key-beats-a-pattern-which-beats-a-built-in-label` | -| A `*` key matches the schema ID, `*` standing for any run of characters | `a-glob-key-matches-the-whole-schema-id` (a pattern covering part of the id labels nothing; one covering all of it labels) | -| Built-in table of six prefixes with labels and colours | `built-in-patterns-label-schemas-by-the-start-of-their-id` (app, core, global, staging, reviews, production) | -| Not driven: the `application`, `review` and `prod` spellings of the built-in prefixes | Not driven: the playground registers one schema per label; spellings share the pattern | -| `color` takes the seven DMS tones | `a-label-takes-each-of-the-seven-tones` | -| Options are read at start: restart after a change | `a-label-takes-each-of-the-seven-tones` (last step) | -| `driverLabel` | covered by the `overview` feature | -| No settings page: layouts, notes and queries are data in the module's own schema | `access` feature (the schema `dms-database` is listed) | diff --git a/.agents/skills/verify-dms-database/features/data.md b/.agents/skills/verify-dms-database/features/data.md deleted file mode 100644 index 8e025239..00000000 --- a/.agents/skills/verify-dms-database/features/data.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -covers: - - src/pages/data.ts - - src/routes/data.ts - - src/service/browse.ts - - src/service/declaredFields.ts - - src/service/references.ts - - src/service/rowFilter.ts - - src/utils/query.ts - - src/utils/requestValidation.ts - - frontend-vue/app/components/DataBrowser.vue - - frontend-vue/app/components/DataBrowserSidebar.vue - - frontend-vue/app/components/DataBrowserTabBar.vue - - frontend-vue/app/components/DataFilterBar.vue - - frontend-vue/app/components/DataGrid.vue - - frontend-vue/app/components/DataGridCell.vue - - frontend-vue/app/components/DataGridHeaderCell.vue - - frontend-vue/app/components/RowDrawer.vue - - frontend-vue/app/components/InstancePicker.vue - - frontend-vue/app/components/DrawerTabs.vue - - frontend-vue/app/build/components/DataGridEmpty.vue - - frontend-vue/app/build/components/DataGridFooter.vue - - frontend-vue/app/build/components/DataGridReadOnlyBanner.vue - - frontend-vue/app/build/components/DataGridToolbar.vue - - frontend-vue/app/build/composables/useDataBrowserGrid.ts - - frontend-vue/app/build/composables/useDataBrowserTabs.ts - - frontend-vue/app/build/composables/useTableCounts.ts - - frontend-vue/app/build/composables/useElsewhereInstances.ts - - frontend-vue/app/build/data/gridData.ts - - frontend-vue/app/build/data/instanceOptions.ts - - frontend-vue/app/build/data/pickerMenus.ts - - frontend-vue/app/build/data/recentTables.ts -docs: - - docs/4.usage/4.data-browser.md - - docs/design/redesign-v2-grill.md - - docs/5.extending.md - - README.md ---- - -# Data - -The Data browser's read side: the schema and instance pickers with the row counts of each table, tables opened as preview or kept tabs, search, column filters, sort and paging of any table, the row drawer with its fields, JSON and the rows pointing at the row, the read-only view across all instances, the empty and error states, and the browse API behind them. - -## Sub-features - -- `the-instance-picker-lists-named-instances-with-a-search-and-a-limit`: `tables/instances` sorted, searched without case, cut to the limit with the total, and its 400 and 404. Integration test in `src/test/data.journeys.test.ts`. -- `list-clamps-the-page-and-orders-the-rows`: `browse/list` answers 25 rows by default, clamps `limit` to 1..200 (199, 200, 201 driven) and `offset` to 0, sorts descending only for the word `desc`, and answers the exact total. Integration test in `src/test/data.journeys.test.ts`. -- `list-filters-search-and-counts-follow-the-wire-tokens`: `filter_` with `is:`, `contains:` (a substring on text, the whole value on a number), a bare value, an unknown mode and an empty value; search across the text and number cells; both combined; the totals. Integration test in `src/test/data.journeys.test.ts`. -- `the-selection-decodes-schema-table-and-instance`: `filter_schema`, `filter_table` and `filter_instance` (default, empty, named, `__CROSS_INSTANCE__`, `contains:`), the 400 and 404 refusals, and the `_instance` tag. Integration test in `src/test/data-reads.journeys.test.ts`. -- `columns-get-and-tables-answer-what-the-grid-needs`: `browse/columns` (declared columns in declaration order, then sampled ones; runtime types; primary key), `browse/get` and `browse/tables` with the counts of the default instance, of eu, and across all instances. Integration test in `src/test/data-reads.journeys.test.ts`. -- `references-count-the-rows-pointing-at-a-row`: `browse/references` counts per relation column, in the same instance, for one and many relations, and refuses all instances, a missing id and a missing row. Integration test in `src/test/data-reads.journeys.test.ts`. -- `the-browse-api-answers-the-platform-owner-only`: anonymous 401, a member 403, on every browse route and on the edit route, nothing written. Integration test in `src/test/data.journeys.test.ts`. -- `the-sidebar-counts-each-table-in-the-picked-instance`: the pickers, the counts of default, eu, us and All instances, the footer naming the instance, `T` focusing the table search, `Esc`, the no-match text and the counts that cannot be read. -- `tables-open-as-preview-tabs-and-are-kept-on-demand`: italic preview tab, replaced by the next table; kept by a double-click in the list, the pin button, a double-click on the tab or a Ctrl-click; the hint line; closing; reload; the URL. -- `links-open-the-table-in-the-instance-they-name`: `?schema=&table=`, `instance=eu`, `instance=us`, `instance=all`, a schema alone, and Open in query console for each. -- `search-filters-and-sort-narrow-and-order-the-rows`: `Ctrl /`, Search rows, Add filter with contains and is exactly, chips, Clear all, the header funnel, and the three-state header sort against the API. -- `the-footer-pages-1250-rows-with-exact-ranges-at-every-size`: 25, 50, 100 and 200 rows per page of `metrics.readings`, the page buttons, the last page, Previous and Next, and totals of 99, 100 and 51 rows at the page boundaries. -- `r-refreshes-the-rows-and-the-search-shortcut-works-from-the-grid`: `R`, the Refresh button, `Ctrl /` from a focused cell, `R` typed in a field. -- `the-row-drawer-steps-through-the-page-with-j-and-k`: `Space`, "Row 3 of 50", `J`, `K`, Previous and Next, the ends, and the page's position "Row 3 of 30". -- `the-row-drawer-shows-fields-json-and-the-rows-pointing-at-it`: the tabs, the Fields tab, the JSON tab against the API, Referenced by with its counts and the link that opens the filtered table. -- `the-fields-tab-widens-long-values-and-sets-null-with-the-dashed-circle`: long text and JSON take the width, short text does not, the dashed circle stages null, the footer counts and sits at the bottom. -- `all-instances-is-a-read-only-view-with-the-instance-column`: banner, `_instance` column, no editor, read-only drawer, the 400 of the edit route, Switch to an instance keeping the search. -- `recently-opened-tables-are-offered-when-no-tab-is-open`: the first-visit text, the five recently opened tables, reload, reopening. -- `no-match-and-empty-tables-say-so`: No row matches with Clear filters and Search all instances, a table with no rows. -- `a-refused-read-shows-the-error-and-try-again-reads-it-again`: Couldn't load with its status, Try again, Check connection. -- `rows-per-page-offers-exactly-25-50-100-and-200`: the footer menu lists exactly the four sizes and each pages that many rows. -- `a-filter-is-either-contains-or-is-exactly-in-the-dialog-and-in-a-column-funnel`: Add filter and the header funnels offer exactly the two modes. - -## How to get to it (user POV) - -- Sidebar: Database › Data browser, or `/modules/database/data`; from the Schemas page's Browse data, the diagram and the overview through `?schema=&table=[&instance=|all]`. - -## Driving it - -```bash -pnpm e2e:run specs/data.spec.ts -``` - -The journeys marked integration test run in `pnpm test`; one file alone after `pnpm run build`: - -```bash -pnpm exec ajs module test . -f dist/test/data-reads.journeys.test.js -pnpm exec ajs module test . -f dist/test/data.journeys.test.js -``` - -## Gotchas - -- The playground's `shop` schema has the products of the default instance and of eu and us, with the orders, customers and order items of eu and us only; `metrics.readings` has 1,250 rows; `vault.accounts` has two rows written by `e2e/playground/src/browse-fixtures.ts`. -- Unsorted rows come in stored order, which is not the order of the ids: journeys sort by a column or take the order from the API. -- Single-instance rows carry `_instance` on MongoDB; the grid hides the column outside All instances. -- `columns-get-and-tables-answer-what-the-grid-needs` expects `browse/columns` to list the `_instance` tag last. The e2e run on `@antelopejs/mongodb` 1.8.6 put it after `created_at`; the integration test passes on 1.8.11, the version the harness loads. -- The integration tests of the browse API seed their own copy of the playground's `shop`, `metrics` and `demo` data (`src/test/dataJourneys.ts`), under schema names of their own. -- A journey that needs a failing server injects the failure with a page route (`page.route`) in the browser; the product code is untouched. -- The drawer's J and K and the Previous and Next buttons are the DMS row header's, driven with the focus in the drawer. - -## Coverage - -| Documented behaviour | Journey and check | -|---|---| -| docs/4.usage/4.data-browser.md:8 pick a schema, an instance and a table on the left; open several tables as tabs | `the-sidebar-counts-each-table-in-the-picked-instance`, `tables-open-as-preview-tabs-and-are-kept-on-demand` | -| :14 Search rows (`Ctrl /`) searches the open table | `search-filters-and-sort-narrow-and-order-the-rows` "Search rows"; `list-filters-search-and-counts-follow-the-wire-tokens` | -| :14 Add filter (`contains` or `is exactly`) | `search-filters-and-sort-narrow-and-order-the-rows` "Add filter", "the header funnel" | -| :15 column headers sort | `search-filters-and-sort-narrow-and-order-the-rows` "sorting by a header" | -| :15 25, 50, 100 or 200 rows per page | `the-footer-pages-1250-rows-with-exact-ranges-at-every-size`, `list-clamps-the-page-and-orders-the-rows` (the API caps at 200) | -| :16 `Space` opens the row, "Row 3 of 50", previous and next, `J` and `K` | `the-row-drawer-steps-through-the-page-with-j-and-k` | -| :16 Fields tab, long text or JSON takes the width, dashed circle sets null, the footer counts unsaved changes | `the-fields-tab-widens-long-values-and-sets-null-with-the-dashed-circle` | -| :16 JSON tab and Referenced by tab | `the-row-drawer-shows-fields-json-and-the-rows-pointing-at-it` | -| :17 Open in query console | `links-open-the-table-in-the-instance-they-name` "Open in query console" | -| :19 `?schema=shop&table=products`, `instance=`, `instance=all` | `links-open-the-table-in-the-instance-they-name` | -| :21-23 All instances: read across every instance, read-only | `all-instances-is-a-read-only-view-with-the-instance-column` | -| :53 `T` finds a table | `the-sidebar-counts-each-table-in-the-picked-instance` "T finds a table" | -| :54 `Ctrl /` Search rows | `search-filters-and-sort-narrow-and-order-the-rows`, `r-refreshes-the-rows-and-the-search-shortcut-works-from-the-grid` | -| :55 `R` Refresh | `r-refreshes-the-rows-and-the-search-shortcut-works-from-the-grid` | -| :56 `Enter` edits the cell, :59 `Ctrl S` reviews and saves | the `editing` feature | -| :57 `Space` opens the row, :58 `J` and `K` | `the-row-drawer-steps-through-the-page-with-j-and-k` | -| grill Q18 the browser stays custom, discovers columns at run time | `columns-get-and-tables-answer-what-the-grid-needs` (sampled columns and types) | -| grill Q20 labelled Schema and Instance controls, "all" read-only with a strip offering to switch, `_instance` column, table list with its filter and counts that say which instance | `the-sidebar-counts-each-table-in-the-picked-instance`, `all-instances-is-a-read-only-view-with-the-instance-column` | -| grill Q21 pin button always visible on a preview tab, the one-line hint, open tables dotted in the list | `tables-open-as-preview-tabs-and-are-kept-on-demand` | -| grill Q22 removable chips with Clear all, sort arrows where active | `search-filters-and-sort-narrow-and-order-the-rows` (chips, aria-sort) | -| grill Q23 row drawer, Referenced by counts from `GET /browse/references`, J / K | `the-row-drawer-shows-fields-json-and-the-rows-pointing-at-it`, `references-count-the-rows-pointing-at-a-row` | -| grill Q24 Pick a table to browse with the recently opened tables | `recently-opened-tables-are-offered-when-no-tab-is-open` | -| grill Q24 No match: Clear filters / Search all instances | `no-match-and-empty-tables-say-so` | -| grill Q24 Load error: Try again with the error text | `a-refused-read-shows-the-error-and-try-again-reads-it-again` | -| docs/5.extending.md:77 `/modules/database/data?schema=&table=` opens the table | `links-open-the-table-in-the-instance-they-name` | -| docs/5.extending.md:78 `/modules/database/query?schema=&table=` opens the console on that table | `a-link-opens-the-console-on-the-table-in-the-instance-it-names` (the query feature owns that page) | -| README:21 browses rows in any instance | `the-sidebar-counts-each-table-in-the-picked-instance`, `links-open-the-table-in-the-instance-they-name`, `all-instances-is-a-read-only-view-with-the-instance-column` | -| `GET /browse/list`, `count`, `columns`, `tables`, `references`, `get` | the six API journeys above | -| `GET /tables/instances` (the instance picker) | `the-instance-picker-lists-named-instances-with-a-search-and-a-limit`; the sidebar journey picks eu and us from it and reads No named instance for `metrics` | -| `GET /tables/source` | Not driven here: only the Schemas page reads it | -| Owner only | `the-browse-api-answers-the-platform-owner-only` | -| Footer pages through the rows (25, 50, 100 or 200 per page) | 4.data-browser.md:15 | `rows-per-page-offers-exactly-25-50-100-and-200` | -| Add filter adds a column filter (`contains` or `is exactly`) | 4.data-browser.md:14 | `a-filter-is-either-contains-or-is-exactly-in-the-dialog-and-in-a-column-funnel` | diff --git a/.agents/skills/verify-dms-database/features/diagram.md b/.agents/skills/verify-dms-database/features/diagram.md deleted file mode 100644 index 85c2fd2a..00000000 --- a/.agents/skills/verify-dms-database/features/diagram.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -covers: - - src/pages/diagram.ts - - src/routes/diagram.ts - - src/db/models/diagram_*.ts - - src/db/tables/diagram_*.ts - - frontend-vue/app/components/SchemaDiagram.vue - - frontend-vue/app/build/components/SchemaDiagramBoard.vue - - frontend-vue/app/components/DiagramNoteNode.vue - - frontend-vue/app/components/DiagramRelationEdge.vue - - frontend-vue/app/components/DiagramStubNode.vue - - frontend-vue/app/components/DiagramTableNode.vue - - frontend-vue/app/build/components/Diagram* - - frontend-vue/app/build/components/diagramFloat.css - - frontend-vue/app/build/diagram/** - - frontend-vue/app/build/composables/useCatalogReferences.ts - - frontend-vue/app/build/composables/useDiagram*.ts -docs: - - docs/4.usage/3.diagram.md ---- - -# Diagram - -The Diagram page draws the tables of one schema and the relations between them, folds wide tables, keeps one layout and the notes for the whole team, and previews an automatic arrangement before it is kept. - -## Sub-features - -- `tables-list-their-columns-with-types-and-icons-and-relations-are-arrows`: columns, types, icons against the legend, arrows, labels. -- `an-encrypted-column-carries-the-lock-icon-of-the-legend`: modifier icons. -- `a-table-of-more-than-twelve-columns-comes-folded-and-folding-is-not-saved`: the fold, `+ 5 columns`, click, Enter, Fold columns. -- `folding-is-a-setting-of-your-own-view-and-is-not-saved-with-the-team-layout`: unfolding writes no layout, reload and another tab fold again. -- `finding-a-column-a-folded-table-hides-unfolds-that-table`: search unfolds only for a hidden column. -- `the-fold-keeps-the-twelve-column-boundary-and-every-column-an-arrow-ends-on`: 12 versus 13 columns, singular `+ 1 column`, an arrow end beyond the twelfth. -- `a-large-schema-opens-at-forty-percent-on-its-top-left-and-fit-view-shows-it-whole`: 40 % start, overview map, `1`, `0`, Fit view. -- `a-relation-to-a-table-not-drawn-ends-on-a-dashed-chip-that-opens-that-table`: focus, chip, opens and selects the table. -- `a-relation-to-another-schema-ends-on-a-chip-that-opens-that-table`: the chip opens the other schema with that table selected. -- `the-url-picks-the-schema-and-the-table-and-names-what-it-cannot-find`: deep link, not-found messages, schema picker and Back. -- `a-schema-without-a-table-says-so-and-offers-no-note-or-auto-layout`: No tables in X. -- `dragging-a-table-saves-the-layout-and-everyone-reads-it`: drag, Layout saved, API, reload, second tab. -- `a-table-not-placed-yet-takes-its-automatic-place-and-placed-tables-stay`: placement rule. -- `auto-layout-previews-the-arrangement-and-keep-or-discard-decides`: preview bar, count, Discard, Keep, Undo, Escape. -- `auto-layout-keeps-groups-together-and-clear-of-notes-that-never-move`: arrangement rules, folded height, notes. -- `auto-layout-and-note-wait-until-the-picked-schema-has-loaded`: while a picked schema reads its layout and notes, Auto layout, Note and N do nothing, so no preview or note holds the previous schema. -- `n-and-the-note-button-drop-a-note-ready-to-write-and-it-is-saved-with-the-schema`: add notes. -- `a-double-click-edits-a-note-and-the-trash-button-and-delete-remove-it`: edit and delete. -- `notes-belong-to-their-schema-and-everyone-reads-them`: shared notes. -- `undo-and-redo-cover-every-move-and-note-and-are-saved`: Ctrl Z, Ctrl Shift Z, Ctrl Y and the buttons. -- `escape-steps-back-from-a-selected-table`: a click selects a table and Escape clears the selection. -- `escape-leaves-the-find-field-then-lifts-the-focus-then-clears-the-selection`: Escape in the find field only leaves it, with a table in focus it brings every table back and keeps the selection, and the next Escape clears the selection and its bar. -- `a-double-click-opens-the-inspector-and-a-relation-opens-the-other-table-in-it`: the drawer titled with the table, its four tabs, no position, J and K ignored, and a relation opening the other table in the same drawer. -- `f-focuses-the-find-field-but-not-while-writing-a-note`: F focuses the find field; an f typed into a note stays in the note. -- `h-pans-the-canvas-and-v-selects-again`: the hand moves the view and no table; V restores table dragging. -- `fit-view-keeps-every-table-inside-the-canvas`: `1` and the Fit view button bring all twelve tables of `dms-core` inside the canvas. -- `the-shortcuts-settings-page-lists-the-diagram-shortcuts`: the nine rows of the diagram group on the Shortcuts page. -- `the-layout-and-the-notes-survive-a-backend-restart`: a dragged table and a note are kept over a restart. -- `each-relation-arrow-starts-at-its-own-column`: arrow origins for three relations. - -## Integration tests - -`pnpm test` runs these in `src/test/diagram.journeys.test.ts`, one `it` per id, so `-g ` selects one. - -- `the-layout-api-stores-one-layout-per-schema-and-refuses-bad-positions`: PUT and GET of the layout, replacement, isolation per schema, 400 refusals. -- `the-notes-api-creates-lists-updates-and-deletes-notes-per-schema`: note CRUD and its fields. -- `the-notes-api-refuses-missing-numbers-with-400-and-unknown-notes-with-404`: note refusals. -- `every-diagram-route-answers-the-platform-owner-only`: 401 and 403 on all six routes. - -## How to get to it (user POV) - -- Modules › Database › Diagram, or Show in diagram from a table (`?schema=&table=`). - -## Driving it - -```bash -pnpm e2e:run specs/diagram.spec.ts -``` - -## Gotchas - -- The playground adds `links` (cross-schema relation, 12, 13 and 14 column tables, named instances), `quirks` (a column named `constructor`) and `hollow` (no table), from `e2e/playground/src/bridge-schema.ts`, imported from `index.ts`. -- Icons are inline sprites; journeys compare them with the legend's by sprite id. -- In focus mode the selection bar lies over the chip, so the journey presses the chip through its click handler. -- The auto layout of `vault` is pinned to exact positions at a 1440 by 900 viewport. - -## Coverage - -| Documented behaviour | Doc | Journey and check | -| --- | --- | --- | -| Pick the schema, `?schema=&table=` opens a table | 3.diagram.md:8 | the-url-picks-the-schema... | -| Columns with types; icons for key, relations, objects, encrypted; legend | 3.diagram.md:14-16 | tables-list-their-columns..., an-encrypted-column... | -| Relation arrow from the column to its table | 3.diagram.md:16 | tables-list-their-columns... (edges, labels, markers) | -| Dashed chip to a table not drawn, opens it | 3.diagram.md:16 | a-relation-to-a-table-not-drawn..., a-relation-to-another-schema... | -| Fold rule: 12 columns, key, arrow ends, `+ N columns`, click or Enter, Fold columns | 3.diagram.md:18 | a-table-of-more-than-twelve..., the-fold-keeps-the-twelve... | -| Finding a hidden column unfolds the table | 3.diagram.md:18 | finding-a-column... | -| Folding is not saved with the layout | 3.diagram.md:18 | folding-is-a-setting-of-your-own-view... | -| Large schema opens at 40 %, top-left, overview map, Fit view `1` | 3.diagram.md:20 | a-large-schema-opens-at-forty-percent... | -| Double-click opens the inspector drawer titled with the table, relation opens the other table, no position, no `J`/`K` | 3.diagram.md:22 | `a-double-click-opens-the-inspector-and-a-relation-opens-the-other-table-in-it` | -| Drag tables, Layout saved, shared by everyone | 3.diagram.md:26 | dragging-a-table-saves-the-layout... (everyone means platform owners, the routes are owner-only) | -| Auto layout preview with Keep layout / Discard | 3.diagram.md:26 | auto-layout-previews-the-arrangement... | -| Arrangement rules, folded height, clear of notes, placement of unplaced tables | 3.diagram.md:28 | auto-layout-keeps-groups-together..., a-table-not-placed-yet... | -| Tables without relations sorted by name | 3.diagram.md:26 | Not driven by a journey; `frontend-vue/tests/diagramLayout.test.ts` checks the row order | -| Undo and redo cover every move | 3.diagram.md:26 | undo-and-redo-cover-every-move... | -| Note button and `N`, double-click to write, saved with the schema, shared | 3.diagram.md:32 | n-and-the-note-button..., a-double-click-edits..., notes-belong-to-their-schema... | -| Shortcut `F`, `N` | 3.diagram.md:38-39 | `N`: n-and-the-note-button...; `F`: finding-a-column... (focus by typing in the field) | -| Shortcuts `1`, `0` | 3.diagram.md:41 | a-large-schema-opens-at-forty-percent... | -| Shortcuts `V` / `H` | 3.diagram.md:40 | `h-pans-the-canvas-and-v-selects-again` | -| Shortcuts Ctrl Z, Ctrl Shift Z, Ctrl Y | 3.diagram.md:42-43 | undo-and-redo-cover-every-move... | -| Shortcut `Esc` | 3.diagram.md:44 | auto-layout-previews... (discards the preview); `escape-leaves-the-find-field-then-lifts-the-focus-then-clears-the-selection` (find field, focus, selection) | -| The Shortcuts settings page lists them | 3.diagram.md:46 | `the-shortcuts-settings-page-lists-the-diagram-shortcuts` | -| Schema ... not found, Table ... not found, No tables in X | design, SchemaDiagram.vue | the-url-picks-the-schema..., a-schema-without-a-table... | -| Layout and notes API | routes/diagram.ts | the API journeys | -| Layout and notes survive a backend restart | 3.diagram.md:26 | `the-layout-and-the-notes-survive-a-backend-restart` | -| Shortcut `F` focuses the find field | 3.diagram.md:36 | `f-focuses-the-find-field-but-not-while-writing-a-note` | -| Fit view (`1`) shows the whole of a large schema | 3.diagram.md:20 | `fit-view-keeps-every-table-inside-the-canvas` | -| Shortcut `Esc` steps back from the selection | 3.diagram.md:44 | `escape-steps-back-from-a-selected-table` | -| A relation is drawn as an arrow from the column to the table it points to | 3.diagram.md:14 | `each-relation-arrow-starts-at-its-own-column` | diff --git a/.agents/skills/verify-dms-database/features/editing.md b/.agents/skills/verify-dms-database/features/editing.md deleted file mode 100644 index 72964656..00000000 --- a/.agents/skills/verify-dms-database/features/editing.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -covers: - - src/service/rowEdit.ts - - src/service/stagedSerialization.ts - - src/routes/data.ts - - frontend-vue/app/components/JsonCellPanel.vue - - frontend-vue/app/build/data/stagedEdits.ts - - frontend-vue/app/build/data/stagedWrites.ts - - frontend-vue/app/build/data/useStagedSave.ts - - frontend-vue/app/build/data/cellValues.ts - - frontend-vue/app/build/utils/stagedSerialization.ts - - frontend-vue/app/build/components/DataGridSaveStatus.vue -docs: - - docs/4.usage/4.data-browser.md - - docs/6.faq.md - - README.md ---- - -# Editing - -Staged edits of the Data browser: a cell or a drawer field is staged with the old value struck through, the bar counts the changes, Ctrl S lists every change before anything is written, Save writes one PUT per row, Undo writes the previous values back for ten seconds, and the rows written are read back through the API, the query console, a reload and a fresh tab. - -## Sub-features - -- `edits-are-staged-then-reviewed-then-written-one-put-per-row`: typing a cell stages it (old value struck, tab dot, bar), the review lists row, column, before and after, Keep editing writes nothing, Save sends one PUT per row with all its fields, and the API, the query console, a reload and a fresh tab read the new values. -- `invalid-drafts-are-refused-esc-cancels-and-a-click-away-decides`: the number, boolean and date messages with `Esc to cancel`, the empty and impossible drafts, an unchanged value, a click away. -- `null-empties-a-cell-and-backslash-null-is-the-text-null`: `null`, `\null`, `\\null`, an emptied text, and the editor's escaped display of the text null. -- `object-and-array-cells-open-the-json-editor-in-a-side-drawer`: the JSON editor drawer (resize by its edge), Invalid JSON, the scalar refusal, Cancel, Apply, null, and nested values stored as typed. -- `the-json-editor-is-as-tall-as-the-drawer`: the JSON editor fills the drawer's height down to its footer. -- `discard-and-closing-a-tab-with-staged-changes-ask-first`: Discard, the kept preview tab, the close dialog with the count, singular and plural, and the leave guard. -- `undo-writes-the-previous-values-back-within-the-window`: Undo restores values, null and a nested value in one PUT, announces the undone changes, and a new edit ends the offer. -- `undo-is-offered-for-ten-seconds-then-the-values-stay`: Undo disappears 9.9 to 11.5 seconds after the click on Save, in real time, and the values stay. -- `a-row-deleted-meanwhile-drops-its-changes-and-the-rest-is-saved`: the rows-gone message and partial title, the page read again, and the undo of a row deleted since. -- `a-failed-write-stops-the-save-and-the-rows-left-stay-staged`: a write that fails (injected in the browser), the rows left staged, a retry, and a save where nothing is written. -- `a-saved-row-shows-in-place-unless-the-save-may-move-rows`: the README sentence, with another writer's change as the witness of a page read again. -- `a-save-under-a-search-or-a-filter-reads-the-page-again`: a filtered field and a search read the page again, another field of a filter does not. -- `an-edit-and-its-undo-land-in-the-instance-of-the-tab-only`: a row with one id in the default, eu and us instances. -- `saved-cells-keep-their-type-numbers-booleans-dates-and-objects`: the column types the API infers from the stored rows after a typed edit. -- `the-edit-route-writes-typed-values-and-refuses-the-rest`: the PUT's rules, read from `rowEdit.ts`. Integration test in `src/test/editing.journeys.test.ts`. -- `hashed-encrypted-and-localized-columns-are-written-as-typed`: the warning, driven on `vault.accounts`. -- `the-row-drawer-stages-edits-like-the-cells-do`: the drawer's fields stage with the same messages, and its footer and the bar count the same changes. -- `discard-drops-the-changes-of-every-staged-row`: Discard with changes on three rows empties the bar, restores every cell and writes nothing. -- `an-undo-whose-write-fails-keeps-the-saved-values-and-offers-undo-again`: the undo PUT answered 500 (injected in the browser) after a two-row save, the toast says 2 changes couldn't be undone, the saved names stay stored, Undo is offered again, and the retry writes the previous names back. - -## How to get to it (user POV) - -- Data browser: double-click a cell or press `Enter` on it, `Ctrl S` to review and save; the row drawer (`Space`) edits a row's fields. - -## Driving it - -```bash -pnpm e2e:run specs/editing.spec.ts -``` - -The journeys marked integration test run in `pnpm test`; one file alone after `pnpm run build`: - -```bash -pnpm exec ajs module test . -f dist/test/editing.journeys.test.js -``` - -## Gotchas - -- The bar's status line names the changed fields (`Unsaved changes · name, price`); the count is on the **Review and save N changes** button, the tab dot and the drawer's footer. -- The Undo window is measured from the click on Save; the journey polls for the button and asserts the 9.9 to 11.5 second range. -- Row identities: a cell is found by the text of the row's `_id` cell and the column's header; unsorted rows are in stored order. -- A write that fails is injected with `page.route` in the browser (HTTP 500 for one row's PUT, or for every PUT once a flag is set, as the undo journey does after the save); a deleted row is deleted through the query console's route. -- `e2e/playground/src/browse-fixtures.ts` adds two rows to `vault.accounts` (the stored form of a hashed, an encrypted and a localized column), imported from `e2e/playground/src/index.ts`. -- `src/service/stagedSerialization.ts` and `frontend-vue/app/build/utils/stagedSerialization.ts` are the query console's wire format; the journeys use them to read rows back (`query-wire.mjs` encodes the same way) and to delete and insert rows. - -## Coverage - -| Documented behaviour | Journey and check | -|---|---| -| docs/4.usage/4.data-browser.md:27 edits are staged, never written as you type | `edits-are-staged-then-reviewed-then-written-one-put-per-row` "typed cells are staged" (the API holds the old values) | -| :32 double-click a cell, or press `Enter`, and type | `edits-are-staged-then-reviewed-then-written-one-put-per-row` (double-click), `object-and-array-cells-open-the-json-editor-in-a-side-drawer` (Enter and double-click), `null-empties-a-cell-and-backslash-null-is-the-text-null` (Enter) | -| :32 object and array cells open a JSON editor in a side drawer, wide as you resize it | `object-and-array-cells-open-the-json-editor-in-a-side-drawer` "the drawer" (dragging the edge widens drawer and editor) | -| :32 ... as tall as the drawer | `the-json-editor-is-as-tall-as-the-drawer` (the editor ends within 120 px of the footer and takes over half the drawer) | -| :32 Apply stages the value, `null` empties the cell, Cancel leaves it | `object-and-array-cells-open-the-json-editor-in-a-side-drawer` "Cancel and Apply" | -| :32 edited cells show the old value struck through | `edits-are-staged-then-reviewed-then-written-one-put-per-row` (struck value, hover title) | -| :36 the bar counts the unsaved changes; Review and save (`Ctrl S`) lists every change before anything is written | `edits-are-staged-then-reviewed-then-written-one-put-per-row` "the review lists every change" | -| :36 Discard drops them | `discard-and-closing-a-tab-with-staged-changes-ask-first` "one change, and Discard" | -| :40 saving writes the changes; for ten seconds Undo puts the previous values back | `undo-writes-the-previous-values-back-within-the-window`, `undo-is-offered-for-ten-seconds-then-the-values-stay` | -| :45 warning: a saved edit writes straight to the database, outside any module's business logic | `hashed-encrypted-and-localized-columns-are-written-as-typed` | -| :56 `Enter` edits the cell | `object-and-array-cells-open-the-json-editor-in-a-side-drawer`, `null-empties-a-cell-and-backslash-null-is-the-text-null`, `invalid-drafts-are-refused-esc-cancels-and-a-click-away-decides` | -| :59 `Ctrl S` reviews and saves | `edits-are-staged-then-reviewed-then-written-one-put-per-row` | -| FAQ 'Why can't I edit rows?' read-only in All instances | `data`: `all-instances-is-a-read-only-view-with-the-instance-column` | -| FAQ 'Can I undo a saved edit?' ten seconds, then edit again; no edit log | `undo-is-offered-for-ten-seconds-then-the-values-stay` | -| README:21 staged, reviewed, saved, undone for ten seconds | the journeys above | -| README:24 a saved row shows in place; the page is read again when a save may move rows (a sorted or filtered field, or a search) | `a-saved-row-shows-in-place-unless-the-save-may-move-rows`, `a-save-under-a-search-or-a-filter-reads-the-page-again` | -| grill Q19 a committed cell turns warning-tinted, the old value struck, the tab gets a dot | `edits-are-staged-then-reviewed-then-written-one-put-per-row` (tab dot title), `discard-and-closing-a-tab-with-staged-changes-ask-first` | -| grill Q19 one `PUT /browse/edit` per row with all its changed fields | `edits-are-staged-then-reviewed-then-written-one-put-per-row` (the recorded requests) | -| grill Q19 a toast offers Undo for a few seconds that writes the previous values back | `undo-writes-the-previous-values-back-within-the-window` | -| grill Q19 leaving the page with staged edits asks via the DMS leave guard | `discard-and-closing-a-tab-with-staged-changes-ask-first` "leaving the page" | -| grill Q23 drawer fields editable, staged like cells | `the-row-drawer-stages-edits-like-the-cells-do` | -| invalid number, boolean and date messages with Esc to cancel | `invalid-drafts-are-refused-esc-cancels-and-a-click-away-decides` | -| `null` empties the cell, `\null` is the text null | `null-empties-a-cell-and-backslash-null-is-the-text-null` | -| closing a tab with staged changes asks: Discard and close, Keep editing | `discard-and-closing-a-tab-with-staged-changes-ask-first` | -| rows that no longer exist are dropped, partial writes stay staged, the partial and undo-failed messages | `a-row-deleted-meanwhile-drops-its-changes-and-the-rest-is-saved`, `a-failed-write-stops-the-save-and-the-rows-left-stay-staged` | -| dates stay dates, a text that is no date is refused, `null` clears, the key and `_instance` are never rewritten | `the-edit-route-writes-typed-values-and-refuses-the-rest`, `saved-cells-keep-their-type-numbers-booleans-dates-and-objects` | -| edits only on one instance; an edit lands in its instance only | `an-edit-and-its-undo-land-in-the-instance-of-the-tab-only` | -| read-back through a second view (API, query console, reload, fresh tab) | `edits-are-staged-then-reviewed-then-written-one-put-per-row` and the stored-value checks of the other journeys | -| the Undo of an edit that emptied a cell writes null back | `undo-writes-the-previous-values-back-within-the-window` | -| an undo whose write fails leaves the rows for a retry (source: `useStagedSave.ts` shows `undo_partial`, never the `undo_failed` text) | `an-undo-whose-write-fails-keeps-the-saved-values-and-offers-undo-again` | -| Discard drops the unsaved changes (every staged row) | 4.data-browser.md:36 | `discard-drops-the-changes-of-every-staged-row` | diff --git a/.agents/skills/verify-dms-database/features/extending.md b/.agents/skills/verify-dms-database/features/extending.md deleted file mode 100644 index 21656b7c..00000000 --- a/.agents/skills/verify-dms-database/features/extending.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -covers: - - src/automation/** - - frontend-vue/app/config/shortcuts-registry.ts - - src/utils/guards.ts - - src/types/** - - src/service/introspect.ts -docs: - - docs/5.extending.md - - docs/6.faq.md ---- - -# Extending - -What the module picks up from the rest of the project (registered schemas, their modifiers, the automation module) and the deep links other pages use. - -## Sub-features - -- `deep-links-open-the-documented-pages-on-the-table`: the four links of the Link to the console table, with `instance=` and `instance=all`. -- `without-the-automation-module-the-trigger-registration-is-a-silent-no-op`: a quiet start without `@antelopejs/dms-automation`. - -## Integration tests - -`pnpm test` runs these in `src/test/extending.journeys.test.ts`, one `it` per id, so `-g ` selects one. - -- `a-registered-schema-shows-its-tables-columns-indexes-relations-and-modifiers`: introspection of declared tables, instances and modifiers. -- `the-table-watch-hands-a-procedure-each-insert-update-and-delete`: with the automation module loaded, a procedure on a Table watch runs on each write of the default instance and not on a write of another instance. - -## How to get to it (user POV) - -- A module calls `RegisterSchema` and declares tables; a notification or row action links to a console page. - -## Driving it - -```bash -pnpm e2e:run specs/extending.spec.ts -``` - -## Gotchas - -- The Schemas, Diagram, Data and Query features drive the pages behind the links in depth; this feature checks that each link lands on the right table. -- The playground runs without `@antelopejs/dms-automation`, and the `pnpm test` harness always loads it, so the silent no-op stays a journey and the table watch runs in the integration test. - -## Coverage - -| Documented behaviour | Journey and check | -|---|---| -| Registered schemas appear with tables, columns, indexes, relations | `a-registered-schema-shows-its-tables-columns-indexes-relations-and-modifiers` (integration test) | -| Each instance is listed in the pickers | `a-registered-schema-shows-its-tables-columns-indexes-relations-and-modifiers` (integration test, instances API), Data feature (pickers) | -| Hashed, localized, encrypted columns carry a modifier badge | `a-registered-schema-shows-its-tables-columns-indexes-relations-and-modifiers` (integration test, API), Schemas feature (badge) | -| Deep links with `instance=` and `instance=all` | `deep-links-open-the-documented-pages-on-the-table` | -| Without the automation module the registration is a silent no-op | `without-the-automation-module-the-trigger-registration-is-a-silent-no-op` | -| Table watch trigger: config, output (type, old and new rows without the instance tag) | `the-table-watch-hands-a-procedure-each-insert-update-and-delete` (integration test) | -| Table watch trigger: one node, reconnect once | Not driven: the run has one backend, and a journey cannot break its change stream | -| On a standalone MongoDB activation fails with "$changeStream is only supported on replica sets" | Not driven: the run's `mongod` is a replica set | -| On a collection that records no pre-images activation fails with the store's `collMod` sentence | Not driven: the playground's collections are created by the driver, with pre-images; `src/test/table-watch-feed.test.ts` checks it | -| Supported extension boundary: root barrel exports exist, no subclassing contract | Not driven: a statement of non-support has no observable effect | -| Frontend components `DmsDatabase*` are for the module's own pages | The five pages render in their features | -| FAQ: a missing table needs `RegisterSchema` and `@RegisterTable` | `schemas` feature lists registered tables | diff --git a/.agents/skills/verify-dms-database/features/external.md b/.agents/skills/verify-dms-database/features/external.md deleted file mode 100644 index e99b90b6..00000000 --- a/.agents/skills/verify-dms-database/features/external.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -covers: - - src/connectionAccess.ts - - src/routes/connections.ts - - src/pages/externalLock.ts - - src/service/builderRefusal.ts - - src/service/catalog.ts - - src/service/catalogReferences.ts - - src/service/catalogSchemas.ts - - src/service/connectionRefusals.ts - - src/service/connectionState.ts - - src/service/connections.ts - - src/service/database.ts - - src/utils/deadline.ts - - frontend-vue/app/components/DatabaseSwitcher.vue - - frontend-vue/app/build/components/DatabaseSubtitle.vue - - frontend-vue/app/build/components/DatabaseSwitcherRow.vue - - frontend-vue/app/build/components/DataBrowserAccessBar.vue - - frontend-vue/app/build/components/FeatureLocked.vue - - frontend-vue/app/build/composables/registerDatabaseSwitcher.ts - - frontend-vue/app/build/composables/reloadForSelection.ts - - frontend-vue/app/build/composables/useDatabaseConnections.ts - - frontend-vue/app/build/composables/useGridAccess.ts - - frontend-vue/app/build/data/assistantOnboarding.ts - - frontend-vue/app/build/data/databaseOptions.ts - - frontend-vue/app/build/data/readOnlyReason.ts - - frontend-vue/app/build/composables/useLockedPages.ts - - frontend-vue/app/build/composables/useSelectionRecheck.ts -docs: - - docs/4.usage/6.external-databases.md - - docs/3.configuration.md ---- - -# External - -The databases a project connects to but does not own: the switcher, the Overview, Schemas and Data browser on one, the pages it cannot serve, and the access that lets the console write to it. - -## Sub-features - -- `an-external-database-is-picked-browsed-edited-and-left`: `erp` is listed next to the project database, picked in the switcher, browsed (rows, inspector, sample row, the Diagram link open, the Query console link locked), refused a save while its access is read, switched to read & write and saved, then left for the project database, whose tabs and recents follow it. -- `an-external-database-refuses-what-it-cannot-serve-with-sentences`: the drawn Diagram with a layout of its own and the locked Query console, the routes that answer 409, a stale tab, a project file the writer cannot rewrite, and the API's refusals of an unknown database and a bad body. - -## How to get to it (user POV) - -- The switcher at the top of the Database module's sidebar; the bar at the top of the Data browser; `/modules/database/schemas`, `/overview` and `/data` on the picked database. - -## Driving it - -```bash -pnpm e2e:run specs/external.spec.ts -``` - -## Gotchas - -- Both journeys run the backend in development, since only a development backend loads the `mongodb-erp` provider and its tables module (`VERIFY_DATABASE_EXTERNAL`, see `e2e/playground/antelope.config.ts`) and lets the access change. -- `POST /verify-database-erp/seed` writes the `erp.customers` collection before the backend restarts: a provider in external mode registers only collections that already exist. -- The playground's `antelope.config.ts` holds its modules in a spread, which the DMS configuration writer refuses to rewrite. A journey points the writer at a scratch project folder with `VERIFY_DATABASE_PROJECT_ROOT` (the DMS builder's `projectRoot`), so the access switch writes a real file and the playground's own is never touched. -- Known findings, each a check named in the journey's `knownFailures`: the Overview names instances on an external database, and the save review names `@default`. -- Not driven: `not_development` (the production backend cannot load the external modules, so the switch is never offered or refused there; `src/test/external-access.test.ts` holds it), the account that can only read, a catalog that does not answer, and the 10,000-row cap, which need an authenticated MongoDB the playground does not run. - -## Coverage - -| Documented behaviour | Journey and check | -|---|---| -| The switcher lists the project database, then each external one with its engine and the External badge | `an-external-database-is-picked-browsed-edited-and-left` (the console lists erp, the switcher) | -| Overview, Schemas, Diagram and Data browser read it; the Query console is locked; no instances | the same journey (the Data browser, Schemas and the inspector, the Overview) and `an-external-database-refuses-what-it-cannot-serve-with-sentences` (the locked and the drawn pages) | -| Rows edit only when the access is `read-write`; a refusal says so | `an-external-database-is-picked-browsed-edited-and-left` (a save while the access is read, a save while read-write) | -| The bar changes the access in development; turning on asks once, turning off asks nothing | the same journey (the confirmation, the access switch, a save while read-write) | -| An edit on a stale tab is refused | `an-external-database-refuses-what-it-cannot-serve-with-sentences` (a stale tab) | -| A refusal of the routes answers a translation key the dashboard shows as a sentence | `an-external-database-refuses-what-it-cannot-serve-with-sentences` (the connection routes, the routes for an external database, a project file the writer cannot rewrite) | -| The choice is kept per user; tabs and recents belong to each database | `an-external-database-is-picked-browsed-edited-and-left` (back on the project database, tabs and recents follow each database) | -| A large or slow database: capped search, 504, the catalog deadline | Not driven: needs a table of more than 10,000 rows and a database that does not answer; `src/test/external-bounds.test.ts` holds them | diff --git a/.agents/skills/verify-dms-database/features/guard.md b/.agents/skills/verify-dms-database/features/guard.md deleted file mode 100644 index f396551c..00000000 --- a/.agents/skills/verify-dms-database/features/guard.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -covers: - - src/routes/query.ts - - src/service/queryInspection.ts - - frontend-vue/app/components/QueryConsole.vue - - frontend-vue/app/build/components/QueryConsoleBoard.vue - - frontend-vue/app/components/QueryResultPanel.vue -docs: - - docs/4.usage/5.query-console.md - - docs/6.faq.md - - docs/1.introduction.md ---- - -# Guard - -A query that inserts, updates, replaces or deletes never runs straight away: a dry run measures it and the owner confirms. - -## Sub-features - -- `a-delete-names-its-operation-target-and-rows-and-waits-for-the-table-name`: the dialog, wrong names that do nothing, Cancel, Confirm and the result. -- `every-write-names-its-operation-and-counts-the-rows-it-would-touch`: delete, update and insert counts, the confirm label and a named-instance target. -- `confirming-a-single-row-update-needs-the-table-name-as-the-docs-say`: the docs say every write needs the name, a single-row update and a single-row replace included (dms-database#115). -- `a-confirmed-write-acts-on-the-data-of-that-moment`: the dry run is a preview, not a snapshot. -- `a-read-query-runs-straight-away`: reads open no dialog. -- `a-replace-names-its-operation-and-rows-and-waits-for-the-table-name`: a replace on one row and on every row of a table: dialog, rows, wrong name, Confirm, read back. -- `a-replace-on-a-selection-changes-every-row-the-dry-run-announced`: the replace of a three-row selection must change three rows and say `3 changed`. Fails today: product finding, draft `dms-database-guard-replace-selection-one-row`. - -## How to get to it (user POV) - -- Query console, any query that changes data. - -## Driving it - -```bash -pnpm e2e:run specs/guard.spec.ts -``` - -## Gotchas - -- The guard is client-side: `POST /query/execute` runs a write without a dry run, which is how the journeys add rows between the dry run and the confirmation. -- A replace on a missing row (`get("x").replace`) counts 0 rows and still asks for the name, like every write. -- A replace on a selection of several rows announces them all (`Replace 3 rows`) but changes one: `@antelopejs/mongodb` 1.6.2 runs it as `findOneAndReplace`, while the Database interface documents "Replace documents of this selection" and the module's dry run counts the whole selection. `a-replace-on-a-selection-changes-every-row-the-dry-run-announced` fails until the driver or the count is settled, so its `fails` field makes it an expected failure of the suite; the other replace journey asserts only what holds today (the dialog, the name, at least the picked row). Draft: `~/.cache/campaign/issues/dms-database-guard-replace-selection-one-row.md`. - -## Coverage - -| Documented behaviour | Journey and check | -|---|---| -| A write never runs straight away; a dry run first | the first two journeys | -| Review the operation, the target and the number of rows | `every-write-names-its-operation-and-counts-the-rows-it-would-touch` | -| To confirm, type the table name | first journey (wrong name, other case, right name); `confirming-a-single-row-update-needs-the-table-name-as-the-docs-say` | -| The dry run is a preview, not a rollback or a locked snapshot | `a-confirmed-write-acts-on-the-data-of-that-moment` | -| Confirmation executes the write against the database | first journey (read back through the API) | -| Read queries run straight away (FAQ) | `a-read-query-runs-straight-away` | -| Replace is a measured operation: the rows it would touch are the rows it changes | the dialog and the picked row: `a-replace-names-its-operation-and-rows-and-waits-for-the-table-name`; every announced row: `a-replace-on-a-selection-changes-every-row-the-dry-run-announced` (fails, see Gotchas) | -| A failed write is recorded as failed in the history | `library` feature | -| A query that replaces never runs straight away (all four write kinds: insert, update, replace, delete) | 5.query-console.md:44 | `a-replace-names-its-operation-and-rows-and-waits-for-the-table-name` | diff --git a/.agents/skills/verify-dms-database/features/library.md b/.agents/skills/verify-dms-database/features/library.md deleted file mode 100644 index 0f5c8d7b..00000000 --- a/.agents/skills/verify-dms-database/features/library.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -covers: - - src/db/** - - src/routes/query.ts - - frontend-vue/app/components/QueryLibrary.vue - - frontend-vue/app/build/composables/useQueryStore.ts - - frontend-vue/app/build/query/runs.ts -docs: - - docs/4.usage/5.query-console.md - - docs/6.faq.md - - README.md ---- - -# Library - -The history, saved and team queries beside the console. - -## Sub-features - -- `history-keeps-your-last-500-runs-newest-first`: the 500 cap, order, paging and the sentence that states it. -- `history-records-failures-and-writes-with-their-status`: status, error, mutation and row count, and how the library words them. -- `history-is-searchable-and-clearing-it-keeps-the-saved-queries`: search, the Clear history question, Cancel and Confirm. -- `a-saved-query-needs-a-name-and-can-be-edited-and-deleted`: Ctrl+S, the name rule, description, restore, edit, delete. -- `a-shared-query-reaches-the-team-and-only-its-author-changes-it`: Team tab, 404 for a teammate's edit or delete. -- `history-belongs-to-its-user-and-a-link-restores-a-run`: per-user history and the `?history=` link. -- `history-groups-runs-by-day-with-yesterday-and-older-dates`: runs aged through `ctx.database` list under Today, Yesterday and an older day's date, in that order. -- `a-history-row-without-a-status-reads-as-ok`: a row written without status, mutation or error reads as a successful run (design Q26), in the API and in the library. -- `clear-history-empties-only-your-own-runs`: two owners, each clearing leaves the other's runs. - -## Integration tests - -`pnpm test` runs these in `src/test/library.journeys.test.ts`, one `it` per id, so `-g ` selects one. - -- `the-library-survives-a-backend-restart`: persistence. The harness cannot restart its backend, so the test reads the run and the saved query from the module's own tables through a MongoDB client of its own, then through the routes. - -## How to get to it (user POV) - -- Query console, the library on the left: History, Saved, Team. - -## Driving it - -```bash -pnpm e2e:run specs/library.spec.ts -``` - -## Gotchas - -- The history collection is the one named like `query_history` in the backend's database; `parts/library-legacy.mjs` finds it, then ages rows with `updateMany` on `executedAt` and writes a legacy row with `insertOne`. -- The 500-run journey makes 503 requests, so it takes about a minute. -- A teammate is a second owner (`member(ctx, name, [], true)`): the routes are owner-only, so a plain member sees nothing. - -## Coverage - -| Documented behaviour | Journey and check | -|---|---| -| History: your last 500 runs | `history-keeps-your-last-500-runs-newest-first` | -| History: grouped by day, searchable | `history-records-failures-and-writes-with-their-status` (Today), `history-is-searchable-and-clearing-it-keeps-the-saved-queries` (search). Yesterday and older-day groups: `history-groups-runs-by-day-with-yesterday-and-older-dates` | -| Clear history empties it | `history-is-searchable-and-clearing-it-keeps-the-saved-queries` | -| Saved: the queries you saved (Ctrl S), with a name and a description | `a-saved-query-needs-a-name-and-can-be-edited-and-deleted` | -| Team: shared queries; teammates run them; only the author edits or deletes (README, FAQ) | `a-shared-query-reaches-the-team-and-only-its-author-changes-it` | -| FAQ: only you see your saved queries unless you tick Share with team | same journey (the private query is not in Team) | -| History records failures; old rows without status read as ok (design Q26) | failures: `history-records-failures-and-writes-with-their-status`; old rows: `a-history-row-without-a-status-reads-as-ok` | -| Persistence in the module's own schema | `the-library-survives-a-backend-restart` (integration test) | -| Clear history empties it (yours only; per-user, two users) | 5.query-console.md:60 | `clear-history-empties-only-your-own-runs` | -| The 500 runs are kept per user | 5.query-console.md:60 | `history-keeps-your-last-500-runs-newest-first` (a teammate's runs survive the owner's 503) | diff --git a/.agents/skills/verify-dms-database/features/overview.md b/.agents/skills/verify-dms-database/features/overview.md deleted file mode 100644 index 6c91a31a..00000000 --- a/.agents/skills/verify-dms-database/features/overview.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -covers: - - src/pages/overview.ts - - src/routes/overview.ts - - src/routes/health.ts - - src/service/overview.ts - - src/service/health.ts - - src/service/catalog.ts - - frontend-vue/app/components/ConnectionStatus.vue - - frontend-vue/app/build/composables/useDatabaseHealth.ts - - frontend-vue/app/build/utils/relativeTime.ts -docs: - - docs/4.usage/1.overview.md - - docs/3.configuration.md - - docs/6.faq.md ---- - -# Overview - -The landing page of the module: whether the database answers, what it holds and what was run against it lately. - -## Sub-features - -- `the-connection-card-reads-the-probe`: Healthy, the probe latency, and the table, schema, row and index totals, equal to the sums of the schemas API. -- `a-configured-driver-label-shows-beside-the-age`: `driverLabel` names the database before the age of the check. -- `without-a-driver-label-the-card-shows-a-dash`: the documented dash when no label is set. -- `the-card-age-counts-up-and-the-probe-repeats-every-thirty-seconds`: the age counts up by the second and the page probes again after 30 seconds. -- `schema-cards-list-every-schema-largest-first`: one card per schema, largest first, with instances, tables, rows and relations; a card opens Schemas filtered. -- `largest-tables-rank-the-default-instances-by-rows`: five tables, biggest first, default instances only, each linking to the Data browser. -- `recent-queries-list-your-last-five-runs`: empty state, then the last five runs, newest first, failed flagged, each linking to its run. -- `an-unreachable-database-shows-unavailable-and-check-again-recovers`: the journey stops MongoDB under the running backend; the card turns to Unavailable with Last error and Check again, then Check again shows Healthy once MongoDB is back. Known failure: the health route answers 500 after about 30 s, not `down` within the 3 s probe deadline. -- `the-header-buttons-lead-to-the-working-pages`: Open query console and Browse data. - -## How to get to it (user POV) - -- Modules › Database, or `/modules/database/overview`. - -## Driving it - -```bash -pnpm e2e:run specs/overview.spec.ts -``` - -## Gotchas - -- With MongoDB stopped, the page learns of it at its next 30 s probe, and the health route takes about 30 s (the driver's server selection timeout) to answer 500: expect Unavailable 60 to 120 s after `ctx.stopDatabase()`. Check again is disabled while a request runs. -- Queries for the feed are run through the console's execute route with the staged wire format (`tableQuery` in `e2e/database.mjs`). - -## Coverage - -| Documented behaviour | Journey and check | -|---|---| -| Overview: state Healthy and last check time | `the-connection-card-reads-the-probe` (Healthy), `the-card-age-counts-up-and-the-probe-repeats-every-thirty-seconds` | -| Overview: database name from `driverLabel` | `a-configured-driver-label-shows-beside-the-age` | -| Configuration: no label shows a dash; FAQ | `without-a-driver-label-the-card-shows-a-dash` | -| Overview: probe latency, tables, rows, indexes | `the-connection-card-reads-the-probe` | -| Overview: one card per schema with instances, tables, rows, relations; opens Schemas filtered | `schema-cards-list-every-schema-largest-first` | -| Overview: Largest tables, default instances | `largest-tables-rank-the-default-instances-by-rows` | -| Overview: Recent queries, Query console link | `recent-queries-list-your-last-five-runs` | -| Overview: header buttons | `the-header-buttons-lead-to-the-working-pages` | -| Overview: unreachable database ("Unavailable", Check again) | `an-unreachable-database-shows-unavailable-and-check-again-recovers` | -| Overview: empty schema cards state | Not driven: the DMS registers its own schemas, so the list is never empty | diff --git a/.agents/skills/verify-dms-database/features/package.md b/.agents/skills/verify-dms-database/features/package.md deleted file mode 100644 index 1ae93d92..00000000 --- a/.agents/skills/verify-dms-database/features/package.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -covers: - - package.json - - skills/** - - frontend-vue/package.json - - frontend-vue/tsconfig.json - - frontend-vue/dms.frontend.ts - - frontend-vue/dms.frontend.build.ts - - frontend-vue/build/** - - frontend-vue/i18n/** - - src/frontend-module.ts - - src/i18n/** -docs: - - README.md - - docs/2.installation.md - - docs/5.extending.md ---- - -# Package - -What a project installs from the registry: the module with its build, its Vue dashboard layer with both locales and its agent skill, and the ranges the README compatibility table names. - -## Sub-features - -No browser drives these: they are mocha tests of the backend suite, `src/test/package.test.ts`, not journeys. - -- `the tarball holds what its manifest names`: the packed tarball holds every path the manifest points at, the layer with its components and both locales, the skill and its cases, and holds no test build, no build info and no docs. -- `both locales hold the same texts, none empty`: the English and French locale files hold the same keys and no empty text. -- `the README compatibility table names each interface range and the layer pins one renderer minor`: each `@antelopejs/interface-*` dependency appears in the README compatibility table with the same range, and the layer pins one renderer minor. - -## How to get to it (user POV) - -- `ajs project modules add @antelopejs/dms-database` installs the tarball; nothing is driven in a browser. - -## Driving it - -```bash -pnpm run build -pnpm exec ajs module test . -f dist/test/package.test.js -``` - -## Gotchas - -- The tests run `npm pack --ignore-scripts` on the checkout and read its files, so they need the build of `pnpm run build` and no DMS state. -- The registered component names (`DmsDatabase` prefix) are driven by the page features: a rename would make a page fail to render. diff --git a/.agents/skills/verify-dms-database/features/query.md b/.agents/skills/verify-dms-database/features/query.md deleted file mode 100644 index d1621ffc..00000000 --- a/.agents/skills/verify-dms-database/features/query.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -covers: - - src/pages/query.ts - - src/routes/query.ts - - src/service/queryInspection.ts - - src/utils/requestValidation.ts - - frontend-vue/app/components/QueryConsole.vue - - frontend-vue/app/build/components/QueryConsoleBoard.vue - - frontend-vue/app/components/QueryBuilderPanel.vue - - frontend-vue/app/components/QueryResultPanel.vue - - frontend-vue/app/build/query/completion.ts - - frontend-vue/app/build/query/csv.ts - - frontend-vue/app/build/query/examples.ts - - frontend-vue/app/build/query/failures.ts - - frontend-vue/app/build/query/tableColumns.ts - - frontend-vue/app/build/query/target.ts - - frontend-vue/app/build/composables/useQueryRuntime.ts -docs: - - docs/4.usage/5.query-console.md - - README.md ---- - -# Query - -The Query console, run and read side: write AQL, run it, read the result. - -## Sub-features - -- `a-query-returns-its-rows-in-the-order-it-asks`: rows, order, header, and the Run button. -- `an-instance-and-every-instance-are-targeted`: default, named and every instance. -- `a-failed-query-says-what-failed-and-offers-the-nearest-name`: syntax, unknown schema, unknown table, Replace. -- `the-insert-chips-add-their-operation`: the six chips and their text. -- `ctrl-space-completes-schemas-and-tables-from-the-workspace`: completion lists. -- `an-empty-console-offers-examples-built-on-your-own-tables`: the two examples. -- `results-over-1000-rows-are-cut-at-1000`: the 1,000 boundary, the JSON view and the CSV export. -- `the-table-view-shows-every-returned-row`: the Table view up to 1,000 rows. -- `ctrl-space-inside-a-filter-completes-the-columns-of-the-table`: the column list inside `row.key("`. -- `the-chart-plots-the-first-numeric-column-with-pickers-for-both-axes`: the Chart view, its default axes and the X picker. -- `open-in-data-browser-opens-the-target-table-or-the-row`: the result's header link and each row's link. -- `format-strips-trailing-spaces-and-blank-lines`: Format removes trailing spaces and surrounding blank lines. -- `a-link-opens-the-console-on-the-table-in-the-instance-it-names`: `/query?schema=&table=` with no instance, `instance=eu` and `instance=all`: the prefilled query, the link leaving the URL, and Run. -- `copy-as-json-puts-the-returned-rows-on-the-clipboard`: Copy as JSON and its notice. -- `an-export-of-uneven-rows-keeps-every-key-in-csv-and-json`: first row lacking keys later rows have. -- `csv-quotes-a-comma-a-quote-and-a-line-break-so-the-cell-reads-back`: CSV quoting round trip. - -## How to get to it (user POV) - -- Modules › Database › Query console, `/modules/database/query`. - -## Driving it - -```bash -pnpm e2e:run specs/query.spec.ts -``` - -## Gotchas - -- The editor is CodeMirror: `fill` sets its text and `Control+Enter` runs it. Chips insert at the cursor, so a chip test starts from New. -- Row search of the library, writes and the confirmation are the `guard` and `library` features. -- Known failure, open question: `results-over-1000-rows-are-cut-at-1000` expects the `_instance` tag as the last CSV column; on `@antelopejs/mongodb` 1.8.6 it comes second, and no doc page fixes the order. - -## Coverage - -| Documented behaviour | Journey and check | -|---|---| -| Query starts from `schemas..instance(?)` and chains operations | `a-query-returns-its-rows-in-the-order-it-asks`, `an-instance-and-every-instance-are-targeted` | -| `Ctrl Space` completes schemas, tables (and columns) | `ctrl-space-completes-schemas-and-tables-from-the-workspace` ; columns: `ctrl-space-inside-a-filter-completes-the-columns-of-the-table` | -| Insert chips | `the-insert-chips-add-their-operation` | -| Format tidies the query | `format-strips-trailing-spaces-and-blank-lines` | -| `Ctrl Enter` runs it | `a-query-returns-its-rows-in-the-order-it-asks` (Ctrl+Enter and the Run button) | -| An empty console offers two examples | `an-empty-console-offers-examples-built-on-your-own-tables` ("Latest 10 rows" is Not driven: the first schema `demo` has no date field) | -| The result shows its row count, duration and target | `a-query-returns-its-rows-in-the-order-it-asks` | -| Table / JSON / Export CSV hold the returned rows up to 1,000 | `results-over-1000-rows-are-cut-at-1000`, `the-table-view-shows-every-returned-row` | -| Chart: the first numeric column | `the-chart-plots-the-first-numeric-column-with-pickers-for-both-axes` | -| Server returns at most 1,000 rows; truncated results say so | `results-over-1000-rows-are-cut-at-1000` | -| Open in data browser opens the target table | `open-in-data-browser-opens-the-target-table-or-the-row` | -| `/modules/database/query?schema=&table=` opens the console on that table (docs/5.extending.md:78) | `a-link-opens-the-console-on-the-table-in-the-instance-it-names` ; the link's landing is also checked by `deep-links-open-the-documented-pages-on-the-table` | -| Copy as JSON | `copy-as-json-puts-the-returned-rows-on-the-clipboard` | -| Failures name the problem (Q29b) | `a-failed-query-says-what-failed-and-offers-the-nearest-name` | -| Export CSV holds the same returned rows, whatever keys they have | 5.query-console.md:34 | `an-export-of-uneven-rows-keeps-every-key-in-csv-and-json` | -| A CSV cell with a comma, a quote or a line break reads back whole | 5.query-console.md:34 | `csv-quotes-a-comma-a-quote-and-a-line-break-so-the-cell-reads-back` | diff --git a/.agents/skills/verify-dms-database/features/schemas.md b/.agents/skills/verify-dms-database/features/schemas.md deleted file mode 100644 index f10f4854..00000000 --- a/.agents/skills/verify-dms-database/features/schemas.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -covers: - - src/pages/schemas.ts - - src/routes/tables.ts - - src/routes/schemas.ts - - src/service/schemaFilters.ts - - src/service/introspect.ts - - src/service/declaredFields.ts - - src/service/fieldDescriptor.ts - - src/service/schemaRegistry.ts - - src/service/types.ts - - src/types/** - - src/utils/guards.ts - - frontend-vue/app/components/SchemasFilterBar.vue - - frontend-vue/app/components/SchemaPicker.vue - - frontend-vue/app/components/InstancePicker.vue - - frontend-vue/app/components/TableInspector.vue - - frontend-vue/app/components/DrawerTabs.vue - - frontend-vue/app/build/schemas/** - - frontend-vue/app/build/composables/useDatabaseSchemas.ts - - frontend-vue/app/build/composables/useTableSample.ts - - frontend-vue/app/build/utils/fieldTypes.ts - - frontend-vue/app/build/utils/databaseLinks.ts -docs: - - docs/4.usage/2.schemas.md ---- - -# Schemas - -The Schemas page lists every table the loaded modules register, with the rows counted in the picked instance and the column, index and relation counts. A filter bar narrows the list and keeps its state in the URL, and a row opens an inspector drawer with the table's columns, indexes, relations and a sample row. - -## Sub-features - -- `each-filter-of-the-bar-narrows-the-list-and-sets-its-own-url-key`: every filter in the UI, its URL key, the `N of M tables` count only while filtered. -- `the-url-restores-every-filter-after-a-reload-and-clear-removes-them`: shared link, reload, Clear, Escape, another schema dropping a named instance. -- `slash-focuses-the-search-field-but-not-while-typing-or-with-a-modifier`: the `/` shortcut. -- `a-filter-that-matches-nothing-says-no-result-and-clear-filters-restores-the-list`: the empty state. -- `each-of-the-five-sortable-columns-sorts-both-ways-and-the-third-click-restores-the-default-order`: Table, Schema, Rows, Columns, Indexes; Relations and Modifiers do not sort. -- `the-relations-and-modifiers-columns-name-the-tables-and-the-flags`: the tag columns and the table heading count. -- `a-row-click-opens-the-inspector-and-previous-next-j-and-k-step-through-the-list`: header, `Table N of M`, `?record=`, buttons, `J`/`K`, ends, Close, direct open, a record outside the list, an unknown record. -- `dragging-the-drawer-edge-resizes-it-and-it-opens-at-the-width-you-left-it`: drag the edge both ways, reopen and step. -- `the-inspector-states-the-counts-and-lists-each-column-with-its-type-null-and-notes`: facts in singular and plural, Columns tab, Null, notes. -- `a-column-named-constructor-is-listed-like-any-other-column`: the inspector of `quirks.members` opens by click and by deep link and lists `constructor` as a string column. -- `the-indexes-and-relations-tabs-list-what-the-table-declares-and-a-relation-opens-the-other-table`: compound versus single, out and in, a relation opens the other table, another schema's table, empty tabs. -- `the-sample-row-tab-shows-one-row-and-another-row-pages-through-the-table`: labels, wrap-around, named and default instance, empty and one-row tables. -- `browse-query-and-diagram-actions-open-the-other-pages-on-the-same-table`: the three inspector actions, the row menu, the header Diagram button. -- `with-modifiers-keeps-a-table-with-only-a-hashed-only-a-localized-or-only-an-encrypted-column`: the "or" of the With modifiers filter: three single-modifier tables of the `mods` schema stay in the API and in the list, each flagging only its own modifier. -- `a-narrow-inspector-scrolls-its-columns-table-and-its-tabs-sideways`: the drawer narrowed to its minimum scrolls the columns table and the tab strip sideways. - -## Integration tests - -`pnpm test` runs these in `src/test/schemas.journeys.test.ts`, one `it` per id, so `-g ` selects one. - -- `the-source-counts-rows-columns-indexes-relations-and-modifiers-of-each-table`: the source route's exact figures for ten known tables, `all` equal to the tables the schemas route registers. -- `schema-instance-search-and-structure-filters-narrow-the-source-and-combine`: scope, name or column search (case, trim), relations, modifiers, empty, combinations, unknown flags, `all` unchanged by filters. -- `rows-are-counted-in-the-picked-instance-default-named-or-all`: default, `eu`, `us`, `all` and an unknown instance, and `empty` judged in the picked instance. -- `the-instances-route-searches-sorts-and-limits-the-named-instances-of-a-schema`: search, numeric sort, limit and its clamps, 400 and 404. -- `a-table-is-read-by-its-schema-and-name-id`: the single-table route and its refusals. -- `columns-are-declared-in-code-and-inferred-from-sampled-rows`: declared columns first, sampled columns after, nulls as unions, arrays by element, no instance tag, a column named `constructor`. -- `the-tables-and-schemas-routes-answer-the-platform-owner-only`: 401 without a session, 403 for a member. - -## How to get to it (user POV) - -- Modules › Database › Schemas (`/modules/database/schemas`); `?scope=&instance=&q=&has=` filter, `?record=::
` opens an inspector. - -## Driving it - -```bash -pnpm e2e:run specs/schemas.spec.ts -``` - -## Gotchas - -- The playground registers DMS's own schemas too (`dms-core`, `dms-tenant`, `dms-database`), so unscoped counts move with the run; journeys scope to `shop`, `vault`, `links`, `metrics`, `demo` or read `all` from the API. -- Clicking the header of the column the list is sorted by by default (Rows) does nothing visible; the journey leaves the default sort first. -- The query page drops `schema` and `table` from its URL after it prefills the editor, so its check reads the editor. - -## Coverage - -| Documented behaviour | Doc | Journey and check | -| --- | --- | --- | -| Schema filter shows one schema's tables | 2.schemas.md:20 | filters (API) and each-filter (`scope=shop`, four tables) | -| Instance counts default, a tenant or region, or all | 2.schemas.md:21 | rows-are-counted..., each-filter (eu, all, default) | -| Find a table or column, `/` focuses | 2.schemas.md:22 | filters (name, column, trimmed, any case), each-filter, slash | -| With relations / With modifiers / Empty | 2.schemas.md:23-25 | filters, each-filter (chips, fixed order) | -| Every filter is kept in the URL | 2.schemas.md:16 | each-filter, the-url-restores... (reload) | -| Sort by name, schema, rows, columns, indexes | 2.schemas.md:27 | each-of-the-five-sortable-columns... | -| Relations column names the tables; Modifiers flags | 2.schemas.md:27 | the-relations-and-modifiers-columns... | -| N of M tables count | 2.schemas.md:20 (bar) | each-filter (count text), no-result | -| Click a row opens the inspector; `Table 3 of 87`; previous/next, `J`/`K`; URL `?record=` | 2.schemas.md:31 | a-row-click-opens-the-inspector... | -| Drag the edge to resize; opens at the width last left | 2.schemas.md:31 | dragging-the-drawer-edge... | -| Row, column, index, relation counts | 2.schemas.md:35 | the-inspector-states-the-counts... | -| Columns tab: type naming, Null, notes | 2.schemas.md:37 | the-inspector-states-the-counts... | -| Indexes tab | 2.schemas.md:38 | the-indexes-and-relations-tabs... | -| Relations tab, a relation opens the other table | 2.schemas.md:39 | the-indexes-and-relations-tabs... | -| Sample row tab | 2.schemas.md:40 | the-sample-row-tab... | -| Browse data, Query this table, Show in diagram; same in the row menu | 2.schemas.md:42 | browse-query-and-diagram-actions... | -| No result and Clear filters | design, schemas.ts | a-filter-that-matches-nothing... | -| On a narrow drawer the table and tabs scroll sideways | 2.schemas.md:37 | `a-narrow-inspector-scrolls-its-columns-table-and-its-tabs-sideways` | -| First-run empty state (No table registered yet) | schemas.ts | Not driven: the playground always registers tables | -| API routes and own-key lookups | src/routes/tables.ts, introspect.ts | the API journeys; the own-key case is the `constructor` journey | -| With modifiers keeps the tables with hashed, localized or encrypted columns (single-modifier tables) | 2.schemas.md:24 | `with-modifiers-keeps-a-table-with-only-a-hashed-only-a-localized-or-only-an-encrypted-column` | diff --git a/.agents/skills/verify-dms-database/features/smoke.md b/.agents/skills/verify-dms-database/features/smoke.md deleted file mode 100644 index 0b22f7a3..00000000 --- a/.agents/skills/verify-dms-database/features/smoke.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -covers: - - src/index.ts - - src/module.ts -docs: - - docs/1.introduction.md - - docs/2.installation.md ---- - -# Smoke - -The fixed journey every verdict runs, whatever the diff touches: the introduction's path from the connection check to a row and a query. - -## Sub-features - -- `smoke`: the owner opens the Overview and reads a healthy connection, finds a table in Schemas, browses its rows in the Data browser and runs a query on it in the Query console. - -## How to get to it (user POV) - -- Modules › Database, `/modules/database/overview`. - -## Driving it - -```bash -pnpm e2e:run specs/smoke.spec.ts -``` diff --git a/.agents/skills/verify-dms-database/package.json b/.agents/skills/verify-dms-database/package.json deleted file mode 100644 index 5ffd9800..00000000 --- a/.agents/skills/verify-dms-database/package.json +++ /dev/null @@ -1 +0,0 @@ -{ "type": "module" } diff --git a/.agents/skills/verify-dms-database/tsconfig.json b/.agents/skills/verify-dms-database/tsconfig.json deleted file mode 100644 index e03f4fec..00000000 --- a/.agents/skills/verify-dms-database/tsconfig.json +++ /dev/null @@ -1,14 +0,0 @@ -{ - "extends": "../../../tsconfig.json", - "compilerOptions": { - "rootDir": "../../..", - "types": ["node"], - "lib": ["esnext"], - "module": "nodenext", - "moduleResolution": "nodenext", - "composite": false, - "noEmit": true, - "incremental": false - }, - "include": ["*.ts"] -} diff --git a/.agents/skills/verify-dms-database/verify.config.ts b/.agents/skills/verify-dms-database/verify.config.ts deleted file mode 100644 index 22aab90f..00000000 --- a/.agents/skills/verify-dms-database/verify.config.ts +++ /dev/null @@ -1,115 +0,0 @@ -/** A kind of one-way door. */ -export type DoorKind = "data" | "format" | "contract" | "outbound" | "exposure" | "publish"; - -/** Path rules for one door kind: globs and declared funnel modules. */ -export interface DoorRule { - globs: string[]; - funnels: string[]; - why: string; -} - -/** - * How the formal gate decides that a diff changed the covered behaviour: - * `emit` compares the JavaScript statements of the covered files on the - * base and on HEAD (types, comments, formatting, imports and export - * keywords left out); `probe` runs a command on a checkout of each, the - * checkout's path as last argument, and compares what it prints. - */ -export type Behaviour = { kind: "emit" } | { kind: "probe"; command: string[] }; - -/** - * A formal check: the source files it covers, the check's own files, the - * command that runs it, how its output names a violated and a passing rule, - * how the gate decides that a diff changed the covered behaviour, and the - * command run on the base when it did or when the check's own files changed - * (`command` when absent). - */ -export interface FormalCheck { - name: string; - covers: string[]; - files: string[]; - command: string[]; - baseCommand?: string[]; - violation: RegExp | null; - passing: RegExp | null; - behaviour: Behaviour; -} - -/** The repo-owned layer of the verification skill, read by `dms-control`. */ -export interface VerifyConfig { - playground: string; - prepare: string[][]; - userFacing: string[]; - notUserFacing: string[]; - smoke: string; - smokeJourney: string; - doors: Record; - formal: FormalCheck[]; -} - -const PLAYGROUND = "e2e/playground"; - -const config: VerifyConfig = { - playground: PLAYGROUND, - prepare: [ - ["pnpm", "install", "--frozen-lockfile", "--prefer-offline", "--ignore-scripts"], - ["pnpm", "run", "build"], - ["ln", "-sfn", "../../node_modules", `${PLAYGROUND}/node_modules`], - ["node_modules/.bin/tsc", "-p", `${PLAYGROUND}/tsconfig.build.json`], - ], - userFacing: ["src/**", "frontend-vue/**", "skills/**", "package.json"], - notUserFacing: ["src/test/**", "frontend-vue/tests/**", "frontend-vue/.*", "frontend-vue/eslint.config.mjs", "frontend-vue/vitest.config.ts", "frontend-vue/pnpm-lock.yaml"], - smoke: "smoke", - smokeJourney: "onboard, open the Overview, find a registered schema's table in Schemas, read its rows in the Data browser, run a query on it", - doors: { - data: { - globs: ["src/routes/data.ts", "src/routes/query.ts", "src/routes/diagram.ts", "src/service/rowEdit.ts", "src/service/queryInspection.ts", "frontend-vue/app/build/data/useStagedSave.ts", "frontend-vue/app/build/data/stagedWrites.ts", "frontend-vue/app/components/QueryConsole.vue", "frontend-vue/app/build/components/QueryConsoleBoard.vue"], - funnels: [], - why: "a saved edit and a confirmed write query go straight to the database, and a deleted row, note or layout is not brought back by a revert of the code", - }, - format: { - globs: ["src/db/**", "src/service/stagedSerialization.ts", "frontend-vue/app/build/utils/stagedSerialization.ts"], - funnels: [], - why: "the module's own tables (layouts, notes, history, saved queries) and the staged-query wire format are read back by the next version of the module", - }, - contract: { - globs: ["package.json", "src/routes/**", "src/config.ts", "src/index.ts", "frontend-vue/package.json", "frontend-vue/dms.frontend.ts", "skills/**"], - funnels: [], - why: "the dashboard and scripts call the HTTP routes, projects set the config keys and the renderer range, and agents read the shipped skill", - }, - outbound: null, - exposure: { - globs: ["src/routes/**", "src/pages/**", "src/module.ts"], - funnels: [], - why: "every route and page is owner-only through a decorator; losing one opens the raw database to any signed-in member or visitor", - }, - publish: { - globs: ["package.json", ".release-it.json", "changelogen.config.json", ".github/workflows/release.yml"], - funnels: [], - why: "the package name, its files and the release workflow claim @antelopejs/dms-database in the npm registry", - }, - }, - formal: [ - { - name: "formal-table-watch", - covers: ["src/automation/tableWatch.ts"], - files: [".agents/skills/formal-table-watch/**"], - command: ["node", ".agents/skills/formal-table-watch/check.mjs", "--full"], - baseCommand: ["node", ".agents/skills/formal-table-watch/check.mjs"], - violation: /^(?:finding|BROKEN|CHANGED|HOLDS) +(\w+)/gm, - passing: /(?<=^holds +(?:\w+, )*)(\w+)(?=,| \()/gm, - behaviour: { kind: "emit" }, - }, - { - name: "formal-access-write-back", - covers: ["src/service/connectionState.ts", "src/config.ts"], - files: [".agents/skills/formal-access-write-back/**", "src/test/access-write-back.property.test.ts", "test-fixtures/dms-builder-stub/**"], - command: ["pnpm", "run", "formal:access-write-back"], - violation: null, - passing: null, - behaviour: { kind: "emit" }, - }, - ], -}; - -export default config; diff --git a/AGENTS.md b/AGENTS.md index 4a98e578..e87a51a1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,7 +28,7 @@ - `scripts/check-sources.mts` runs in `pnpm lint`: the components the backend pages name exist, `` reads the global messages, and every text key a page names resolves in each locale. - The playground is linted but not type-checked. Check it with `pnpm --dir playground install --ignore-workspace --frozen-lockfile && pnpm --dir playground build`. -`e2e/` is the Playwright suite of the verify skill's journeys, one spec per feature, run on the `e2e/playground` project with one worker that starts its own MongoDB, backend and dashboard on free ports. `pnpm e2e:smoke` builds once and runs the journeys tagged `@smoke`, as the `e2e` job of `ci.yml` does on a pull request; every other run (the merge queue, the nightly, a manual run, a push and a pull request labelled `ci:full`) runs every journey in two shards, and a draft runs none. After `pnpm e2e:build`, `pnpm e2e:run specs/.spec.ts` runs one feature without a rebuild. +`e2e/` is the Playwright suite of the module's feature journeys, one spec per feature, run on the `e2e/playground` project with one worker that starts its own MongoDB, backend and dashboard on free ports. `pnpm e2e:smoke` builds once and runs the journeys tagged `@smoke`, as the `e2e` job of `ci.yml` does on a pull request; every other run (the merge queue, the nightly, a manual run, a push and a pull request labelled `ci:full`) runs every journey in two shards, and a draft runs none. After `pnpm e2e:build`, `pnpm e2e:run specs/.spec.ts` runs one feature without a rebuild. `pnpm knip` checks dependencies only. `pnpm knip:all` also reports unused files and exports; confirm each finding before you remove it. @@ -43,7 +43,7 @@ CI runs `pnpm run checks` in full on every pull request and reports what failed. - `pnpm exec oxlint ` and `pnpm exec oxfmt ` on the files you changed. - One test file, not the suite. In a module that tests with `ajs module test`: `pnpm run build`, then `pnpm exec ajs module test . -f dist/.test.js`. -Prove a change works with the verification skill in [`.agents/skills/verify-dms-database/SKILL.md`](.agents/skills/verify-dms-database/SKILL.md) before you call it done. +Prove a change works by running the `e2e` journey of the feature you touched before you call it done. ### Comments From 9f5059ac8842e69ad74065cef41024ce30bcd990 Mon Sep 17 00:00:00 2001 From: Antony Rizzitelli Date: Thu, 19 Nov 2026 14:02:14 +0000 Subject: [PATCH 2/4] chore: drop the verify-dms-database skill link --- .claude/skills/verify-dms-database | 1 - 1 file changed, 1 deletion(-) delete mode 120000 .claude/skills/verify-dms-database diff --git a/.claude/skills/verify-dms-database b/.claude/skills/verify-dms-database deleted file mode 120000 index 6f3095ce..00000000 --- a/.claude/skills/verify-dms-database +++ /dev/null @@ -1 +0,0 @@ -../../.agents/skills/verify-dms-database \ No newline at end of file From c109e2621c89991f687c0d1068daea65e17cb5f4 Mon Sep 17 00:00:00 2001 From: Antony Rizzitelli Date: Thu, 19 Nov 2026 14:02:14 +0000 Subject: [PATCH 3/4] ci: start the checks on the ready pull request From c5b589a5ea1fe90700a8eafb2f9d52d1b8509b5f Mon Sep 17 00:00:00 2001 From: Antony Rizzitelli Date: Thu, 19 Nov 2026 14:05:20 +0000 Subject: [PATCH 4/4] chore: sync AGENTS.md --- AGENTS.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e87a51a1..ed3eed80 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -43,8 +43,6 @@ CI runs `pnpm run checks` in full on every pull request and reports what failed. - `pnpm exec oxlint ` and `pnpm exec oxfmt ` on the files you changed. - One test file, not the suite. In a module that tests with `ajs module test`: `pnpm run build`, then `pnpm exec ajs module test . -f dist/.test.js`. -Prove a change works by running the `e2e` journey of the feature you touched before you call it done. - ### Comments Say it in code: a constraint in a type, a lint rule or a test, a public item's contract in TSDoc. Other comments are lint directives naming their rules, `@ts-expect-error `, `SAFETY: ` above a type assertion, and license or tool directives. A reason states what the code does now.