ordel-cli 0.2.2__tar.gz → 0.3.1__tar.gz

ordel_cli-0.3.1/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+*.egg-info/

ordel_cli-0.3.1/CATALOG.md

@@ -0,0 +1,107 @@
+# The Ordel element catalog
+
+The catalog is what Ordel knows about your app's pages and elements.
+It is the baseline a heal compares against, the source page objects are generated from, and the denominator coverage is measured against.
+It lives in `.ordel/graph.json`, and it is plain JSON you can commit, diff and review.
+
+## Where it comes from
+
+- `ordel explore <url>` (or the `explore_app` MCP tool) captures one page.
+- `capture_state` captures whatever page an agent-driven session is on.
+- `ordel record` captures every page a person lands on while recording.
+- `record_flow` adds a thin, element-less page for each URL a flow visits.
+- `ordel adopt --apply` re-captures the page of a heal a human accepted, so the next break heals from the app as it is now.
+
+## `graph.json`
+
+```json
+{
+  "schema_version": 1,
+  "pages": {
+    "HomePage": {
+      "url": "http://localhost:3000/",
+      "title": "Sign up",
+      "elements": {
+        "email": { "tag_canon": "input", "role_canon": "textbox", "testid_canon": "email", "...": "..." }
+      }
+    }
+  }
+}
+```
+
+- `schema_version` is the format version, currently `1`.
+  A file without it is version `0`, which has the same shape and is read as-is.
+  A file with a version newer than the installed `ordel-cli` understands is refused with an error, never guessed at.
+- `pages` maps a page id to the page.
+  A page id is 1 to 64 characters of `A-Z a-z 0-9 . _ -`, derived from the URL path (`/` is `HomePage`, `/cart.html` is `CartHtmlPage`).
+  It also names the page object: `pages/<PageId>.ts`.
+- `url` is the page's URL without query string or fragment when it came from a recording.
+  `title` is the document title.
+- `elements` maps an element key to its fingerprint.
+
+### Element keys
+
+A key is the element's test id when it has one (the project's `testIdAttribute`, `data-testid` by default).
+Otherwise it is `<role>:<name-slug>` (for example `button:create-account`), and failing that `<tag>:<index>`.
+A repeated key gets a `#2`, `#3` suffix.
+The key is what a recorded step, a page object getter and a heal all refer to.
+
+### Fingerprints
+
+Every field is optional; the matcher weighs whatever is present.
+The six `_canon` fields are the element's identity: they are Unicode-normalised, lowercased and whitespace-collapsed, and an exact heal is a match on them.
+The other fields feed the fuzzy match that heals an element whose identity changed.
+
+| Field | Meaning |
+|---|---|
+| `tag_canon` | tag name |
+| `role_canon` | ARIA role, explicit or implicit |
+| `accessible_name_canon` | accessible name (aria-label, label, text, placeholder, alt, title) |
+| `testid_canon` | value of the project's test-id attribute |
+| `name_attr_canon` | the `name` attribute |
+| `id_canon` | the `id` attribute |
+| `id_is_dynamic` | the id looks generated; such an id is left out of the identity |
+| `visible_text` | rendered text |
+| `neighbor_text` | text next to the element |
+| `distinguishing_text` | text that tells repeated elements (table rows, cards) apart |
+| `class_tokens` | class names, as a sorted list |
+| `href`, `alt`, `title`, `type_attr`, `placeholder`, `aria_description` | the attributes of the same name |
+| `xpath`, `id_xpath` | structural paths, when captured |
+| `container_key`, `ordinal` | the repeated container it sits in, and its position there |
+| `bbox` | `[x, y, width, height]` at capture time |
+
+Beside the fingerprint, an element keeps three exact-case fields that the matcher ignores and `get_page` returns.
+A catalog captured before they existed simply lacks them.
+
+| Field | Meaning |
+|---|---|
+| `name_attr` | the `name` attribute as written |
+| `testid` | the test id as written |
+| `options` | a `<select>`'s options as `[{"value", "text"}]`, at most 100 |
+
+## Export and import
+
+```bash
+ordel catalog export catalog.json    # write the portable file
+ordel catalog import catalog.json    # merge it into this project's catalog
+```
+
+An export is the catalog wrapped with what an importer needs to trust it:
+
+```json
+{
+  "format": "ordel.catalog",
+  "schema_version": 1,
+  "exported_at": "2026-09-28T02:40:13+00:00",
+  "test_id_attribute": "data-testid",
+  "pages": { "HomePage": { "url": "...", "title": "...", "elements": { } } }
+}
+```
+
+Import merges and never overwrites.
+A page this catalog lacks is added.
+On a page it already has, new elements are added and an element it already has keeps its local fingerprint.
+Each such conflict is listed, so you can re-capture the page if the import was the fresher one.
+Every imported fingerprint is re-read through the same parser a local capture uses, so unknown fields are dropped.
+Pages with an invalid id are skipped and listed.
+If the export was captured with a different `test_id_attribute` than this project uses, the import says so, because test-id locators may then not match.

ordel_cli-0.3.1/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.5
+Name: ordel-cli
+Version: 0.3.1
+Summary: Ordel free CLI — local QA-automation for individual devs. Drives the deterministic ordel-engine and exposes it to a BYO coding agent over MCP. No account, no DB, no Ordel LLM.
+Project-URL: Homepage, https://ordel.io
+Author: Ordel
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: coding-agent,mcp,page-object,playwright,qa,self-healing,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: mcp<2.0,>=1.0
+Requires-Dist: ordel-engine==0.3.1
+Requires-Dist: ordel-tools==0.3.1
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ordel (free CLI)
+
+Local QA automation for individual devs — a persistent, deterministic "QA brain" your
+own coding agent (Claude Code / Cursor / Copilot) drives over MCP. **No account, no DB,
+no Ordel LLM.** Your agent is the brain; Ordel is the memory + determinism.
+
+> Status: **early build**. The engine loop (map → record → generate → run) works
+> locally today; a single-command `npx ordel` distribution is planned but not started.
+
+## What works today (local, anonymous)
+
+```bash
+ordel init          # create .ordel/ + an ORDEL.md bridge file. No account.
+ordel doctor        # preflight: Node / npx / @playwright/test / Chromium (+ how to fix)
+ordel status        # local coverage: pages, elements, run history
+ordel graph         # print the local app graph
+ordel adopt         # existing Playwright/Cypress suite -> flake report + heal patches
+ordel record <name> <url>  # click through a flow yourself -> page objects + a spec using them
+ordel run           # run the Playwright suite; one evidence-backed verdict per test
+ordel report        # copy-pasteable Markdown report (Slack/Teams/Jira); --json too
+ordel catalog export catalog.json   # the element catalog as a portable file (CATALOG.md)
+ordel catalog import catalog.json   # merge one in; local elements win, conflicts listed
+ordel mcp-install    # print the MCP config to add to Claude Code / Cursor / Copilot
+ordel mcp-install --skill   # also install the agent skill (Claude Code, Codex)
+```
+
+### Recording a flow yourself
+
+`ordel record signup http://localhost:3000/` opens a visible browser at that URL. Click
+and type through the flow as a user would, then close the window to finish (Ctrl+C
+works too, and keeps what was recorded).
+
+To assert something, Alt+click it (Option+click on a Mac). That records
+`toHaveText(<its text>)`, or `toBeVisible()` when it has no text. The final URL is
+asserted automatically. A recording with no assertion runs `unjudged`, because it
+proves nothing.
+
+Ordel writes back:
+- every page you landed on, into the catalog;
+- a page object per page (`pages/<Class>.ts`, or its managed block updated);
+- `tests/signup.spec.ts`, which drives those page objects (`homePage.submit.click()`).
+
+A hand-written page object is never overwritten: steps on its page use a direct locator
+instead, and the command says so. Passwords are never stored. The spec reads them from
+`ORDEL_PASSWORD`, and query strings (where a GET form puts its fields) are dropped from
+every recorded URL.
+
+### Adopting an existing suite
+
+`ordel adopt` points Ordel at the suite you already have (Playwright, or Cypress `*.cy.*`
+specs) and reports on it without changing it:
+
+- **Ingest:** every functional spec becomes a flow in `.ordel/flows/`. Cypress chains
+  are translated to the same flow format; a chain it cannot represent faithfully is
+  counted, never guessed.
+- **Flake report:** it runs a Playwright suite until `.ordel/runs/` holds `--runs`
+  (default 3) judged runs, then classifies each test as `flaky` (passed only on retry,
+  or flipped twice), `regressed` (passed, then kept failing), `failing`, `recovered`,
+  `stable`, or too few runs to say.
+- **Heal report:** each failing test whose test-id locator no longer resolves is healed
+  against a live capture of the page it was catalogued on. The page must have been
+  captured while the test was green: run `ordel explore <url>` first to build that
+  baseline. A confident heal becomes a unified diff under `.ordel/patches/<heal-id>.patch`.
+  An element that is simply gone is reported as a real failure, not healed to something else.
+
+Nothing in your code changes until you review a patch:
+
+```bash
+ordel adopt --apply heal-0001    # write the fix, mark the heal accepted, refresh the catalog
+ordel adopt --reject heal-0001   # write nothing, record the rejection
+```
+
+`--apply` refuses a patch whose file changed since it was made. Agents get the same
+report through the `adopt_suite` MCP tool. They cannot apply or reject a heal: that is
+the human review step.
+
+### Honest verdicts
+
+`ordel run` (and the `run_test` MCP tool) never reports a green it cannot back. Each
+executed test gets one verdict: `pass`, `fail`, `flaky`, `skipped` or **`unjudged`**,
+with its evidence: the assertions it actually ran and any heal it depends on.
+
+A test that Playwright calls green is `unjudged`, not passed, when:
+- it ran no assertion at all (a vacuous pass),
+- no assertion evidence was captured for it,
+- its spec depends on a heal no human has reviewed yet.
+
+A run that executed no test is `no_tests`, never a pass. `ordel run --json` prints the
+full `ordel.run/v1` document, which is also recorded under `.ordel/runs/`.
+
+| Exit code | Meaning |
+|---|---|
+| 0 | at least one test ran, and every one passed with evidence |
+| 1 | a test failed, no test ran, or the run itself errored |
+| 3 | nothing failed, but at least one test is unjudged |
+
+Then your coding agent, via MCP, drives the loop (needs Node + `@playwright/test` in the
+project — run `ordel doctor` to check):
+- `get_app_context` / `heal_selector` — what Ordel knows + **deterministic self-heal**
+  of a broken selector (fingerprint match, no LLM; ambiguous cases return `needs_agent`
+  with ranked candidates for your agent's *own* LLM to resolve — Ordel never spends inference).
+  Every resolved heal is recorded in `.ordel/heals.json` pending human review.
+- `explore` / `record_flow` — drive the real browser to map the app + record a flow.
+  A value typed into a password-like field (type=password, or named/labelled password,
+  secret, token or api key; a step can also say `"secret": true`) is used for the recording
+  and never written to disk: the flow keeps a reference, and every generated spec reads it
+  from an environment variable such as `ORDEL_SECRET_PASSWORD`, listed in the result's
+  `needs_env`. Set it before running the spec; unset, the test fails naming it.
+- `get_page` — read a mapped page back (inputs, buttons, links or all): each element's
+  test id, name, type, placeholder, href, `<select>` options and visible text, exact case.
+- `generate_scenarios` / `generate_invariant` / `generate_perf_check` / `generate_pom` —
+  turn artifacts into runnable specs (happy/negative/boundary, data-integrity, latency, POM).
+- `run_test` — run a spec via `npx playwright test` and read the evidence-backed verdicts.
+- QA-mind planning: `coverage_report` / `risk_rank` / `plan_tests` / `regression_set`.
+
+## In progress (honest — no fake success)
+
+- Single `npx ordel` distribution — the plan is a compiled Python engine binary wrapped
+  in one npm package; not started (today's install path is `pip`/`uv`, see Dev below).
+- `eject` (one-command raw-Playwright export) — scaffold; but there's no lock-in today
+  either: generated tests are already plain `tests/*.spec.ts` + `pages/*.ts` on disk.
+- Team sync + hosted dashboard = the paid upgrade (this CLI stays free & local).
+
+## The pieces
+
+- **`ordel-engine`** (sibling package) — the pure deterministic core: fingerprint
+  matching + self-heal, stdlib-only, zero backend.
+- **`ordel_cli.store`** — the `.ordel/` file store (the local shell).
+- **`ordel_cli.heal_service`** — heal + per-page circuit-breaker.
+- **`ordel_cli.mcp_server`** — the local stdio MCP server your agent connects to.
+
+## Dev
+
+```bash
+pip install -e packages/ordel-engine -e packages/ordel-cli
+pip install pytest
+pytest packages/ordel-cli/tests packages/ordel-engine/tests -q
+```
+
+## Known limitations (by design)
+
+- **Single-writer.** The `.ordel/` store is for one dev on one machine. Writes are
+  *atomic* (temp-file + `os.replace`, so a crash can't corrupt a file), and a corrupted
+  `graph.json` is reported cleanly (never silently overwritten). But two processes
+  writing the *same* page concurrently is last-writer-wins — there is no file lock. That
+  is deliberate: a single-user local CLI doesn't warrant lock files / their failure
+  modes. Team-scale concurrency is the hosted product's job (`ordel push`).
+- **Browser tools need a local Node + `@playwright/test`** (`explore`/`record_flow`/`run_test`).
+  They don't ship a browser; run `ordel doctor` — if Node/Playwright/Chromium are missing it
+  tells you the exact command to fix. Without them these tools report the missing dependency,
+  never fake success.
+
+## Privacy
+
+Local-first: **no Ordel LLM, no telemetry, no account, no data sent to Ordel.** The only
+network requests are to your own target app and standard package/browser downloads you
+initiate. Full policy: https://ordel.io/privacy (also ships as `PRIVACY.md` next to the
+installed package, and at the repo root here).

ordel_cli-0.3.1/README.md

@@ -0,0 +1,158 @@
+# ordel (free CLI)
+
+Local QA automation for individual devs — a persistent, deterministic "QA brain" your
+own coding agent (Claude Code / Cursor / Copilot) drives over MCP. **No account, no DB,
+no Ordel LLM.** Your agent is the brain; Ordel is the memory + determinism.
+
+> Status: **early build**. The engine loop (map → record → generate → run) works
+> locally today; a single-command `npx ordel` distribution is planned but not started.
+
+## What works today (local, anonymous)
+
+```bash
+ordel init          # create .ordel/ + an ORDEL.md bridge file. No account.
+ordel doctor        # preflight: Node / npx / @playwright/test / Chromium (+ how to fix)
+ordel status        # local coverage: pages, elements, run history
+ordel graph         # print the local app graph
+ordel adopt         # existing Playwright/Cypress suite -> flake report + heal patches
+ordel record <name> <url>  # click through a flow yourself -> page objects + a spec using them
+ordel run           # run the Playwright suite; one evidence-backed verdict per test
+ordel report        # copy-pasteable Markdown report (Slack/Teams/Jira); --json too
+ordel catalog export catalog.json   # the element catalog as a portable file (CATALOG.md)
+ordel catalog import catalog.json   # merge one in; local elements win, conflicts listed
+ordel mcp-install    # print the MCP config to add to Claude Code / Cursor / Copilot
+ordel mcp-install --skill   # also install the agent skill (Claude Code, Codex)
+```
+
+### Recording a flow yourself
+
+`ordel record signup http://localhost:3000/` opens a visible browser at that URL. Click
+and type through the flow as a user would, then close the window to finish (Ctrl+C
+works too, and keeps what was recorded).
+
+To assert something, Alt+click it (Option+click on a Mac). That records
+`toHaveText(<its text>)`, or `toBeVisible()` when it has no text. The final URL is
+asserted automatically. A recording with no assertion runs `unjudged`, because it
+proves nothing.
+
+Ordel writes back:
+- every page you landed on, into the catalog;
+- a page object per page (`pages/<Class>.ts`, or its managed block updated);
+- `tests/signup.spec.ts`, which drives those page objects (`homePage.submit.click()`).
+
+A hand-written page object is never overwritten: steps on its page use a direct locator
+instead, and the command says so. Passwords are never stored. The spec reads them from
+`ORDEL_PASSWORD`, and query strings (where a GET form puts its fields) are dropped from
+every recorded URL.
+
+### Adopting an existing suite
+
+`ordel adopt` points Ordel at the suite you already have (Playwright, or Cypress `*.cy.*`
+specs) and reports on it without changing it:
+
+- **Ingest:** every functional spec becomes a flow in `.ordel/flows/`. Cypress chains
+  are translated to the same flow format; a chain it cannot represent faithfully is
+  counted, never guessed.
+- **Flake report:** it runs a Playwright suite until `.ordel/runs/` holds `--runs`
+  (default 3) judged runs, then classifies each test as `flaky` (passed only on retry,
+  or flipped twice), `regressed` (passed, then kept failing), `failing`, `recovered`,
+  `stable`, or too few runs to say.
+- **Heal report:** each failing test whose test-id locator no longer resolves is healed
+  against a live capture of the page it was catalogued on. The page must have been
+  captured while the test was green: run `ordel explore <url>` first to build that
+  baseline. A confident heal becomes a unified diff under `.ordel/patches/<heal-id>.patch`.
+  An element that is simply gone is reported as a real failure, not healed to something else.
+
+Nothing in your code changes until you review a patch:
+
+```bash
+ordel adopt --apply heal-0001    # write the fix, mark the heal accepted, refresh the catalog
+ordel adopt --reject heal-0001   # write nothing, record the rejection
+```
+
+`--apply` refuses a patch whose file changed since it was made. Agents get the same
+report through the `adopt_suite` MCP tool. They cannot apply or reject a heal: that is
+the human review step.
+
+### Honest verdicts
+
+`ordel run` (and the `run_test` MCP tool) never reports a green it cannot back. Each
+executed test gets one verdict: `pass`, `fail`, `flaky`, `skipped` or **`unjudged`**,
+with its evidence: the assertions it actually ran and any heal it depends on.
+
+A test that Playwright calls green is `unjudged`, not passed, when:
+- it ran no assertion at all (a vacuous pass),
+- no assertion evidence was captured for it,
+- its spec depends on a heal no human has reviewed yet.
+
+A run that executed no test is `no_tests`, never a pass. `ordel run --json` prints the
+full `ordel.run/v1` document, which is also recorded under `.ordel/runs/`.
+
+| Exit code | Meaning |
+|---|---|
+| 0 | at least one test ran, and every one passed with evidence |
+| 1 | a test failed, no test ran, or the run itself errored |
+| 3 | nothing failed, but at least one test is unjudged |
+
+Then your coding agent, via MCP, drives the loop (needs Node + `@playwright/test` in the
+project — run `ordel doctor` to check):
+- `get_app_context` / `heal_selector` — what Ordel knows + **deterministic self-heal**
+  of a broken selector (fingerprint match, no LLM; ambiguous cases return `needs_agent`
+  with ranked candidates for your agent's *own* LLM to resolve — Ordel never spends inference).
+  Every resolved heal is recorded in `.ordel/heals.json` pending human review.
+- `explore` / `record_flow` — drive the real browser to map the app + record a flow.
+  A value typed into a password-like field (type=password, or named/labelled password,
+  secret, token or api key; a step can also say `"secret": true`) is used for the recording
+  and never written to disk: the flow keeps a reference, and every generated spec reads it
+  from an environment variable such as `ORDEL_SECRET_PASSWORD`, listed in the result's
+  `needs_env`. Set it before running the spec; unset, the test fails naming it.
+- `get_page` — read a mapped page back (inputs, buttons, links or all): each element's
+  test id, name, type, placeholder, href, `<select>` options and visible text, exact case.
+- `generate_scenarios` / `generate_invariant` / `generate_perf_check` / `generate_pom` —
+  turn artifacts into runnable specs (happy/negative/boundary, data-integrity, latency, POM).
+- `run_test` — run a spec via `npx playwright test` and read the evidence-backed verdicts.
+- QA-mind planning: `coverage_report` / `risk_rank` / `plan_tests` / `regression_set`.
+
+## In progress (honest — no fake success)
+
+- Single `npx ordel` distribution — the plan is a compiled Python engine binary wrapped
+  in one npm package; not started (today's install path is `pip`/`uv`, see Dev below).
+- `eject` (one-command raw-Playwright export) — scaffold; but there's no lock-in today
+  either: generated tests are already plain `tests/*.spec.ts` + `pages/*.ts` on disk.
+- Team sync + hosted dashboard = the paid upgrade (this CLI stays free & local).
+
+## The pieces
+
+- **`ordel-engine`** (sibling package) — the pure deterministic core: fingerprint
+  matching + self-heal, stdlib-only, zero backend.
+- **`ordel_cli.store`** — the `.ordel/` file store (the local shell).
+- **`ordel_cli.heal_service`** — heal + per-page circuit-breaker.
+- **`ordel_cli.mcp_server`** — the local stdio MCP server your agent connects to.
+
+## Dev
+
+```bash
+pip install -e packages/ordel-engine -e packages/ordel-cli
+pip install pytest
+pytest packages/ordel-cli/tests packages/ordel-engine/tests -q
+```
+
+## Known limitations (by design)
+
+- **Single-writer.** The `.ordel/` store is for one dev on one machine. Writes are
+  *atomic* (temp-file + `os.replace`, so a crash can't corrupt a file), and a corrupted
+  `graph.json` is reported cleanly (never silently overwritten). But two processes
+  writing the *same* page concurrently is last-writer-wins — there is no file lock. That
+  is deliberate: a single-user local CLI doesn't warrant lock files / their failure
+  modes. Team-scale concurrency is the hosted product's job (`ordel push`).
+- **Browser tools need a local Node + `@playwright/test`** (`explore`/`record_flow`/`run_test`).
+  They don't ship a browser; run `ordel doctor` — if Node/Playwright/Chromium are missing it
+  tells you the exact command to fix. Without them these tools report the missing dependency,
+  never fake success.
+
+## Privacy
+
+Local-first: **no Ordel LLM, no telemetry, no account, no data sent to Ordel.** The only
+network requests are to your own target app and standard package/browser downloads you
+initiate. Full policy: https://ordel.io/privacy (also ships as `PRIVACY.md` next to the
+installed package, and at the repo root here).

ordel_cli-0.3.1/ordel_cli/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: ordel-cli
+description: Use when testing this repo's web app with Ordel's local MCP server (`ordel-cli`) - mapping pages, recording flows, generating Playwright specs, running them, adopting an existing Playwright or Cypress suite, or healing a broken locator. Ordel decides correctness; report its verdicts, never your own reading.
+---
+<!-- ordel:skill - written by `ordel mcp-install --skill`; re-run it to update. Delete this line to keep your own edits. -->
+
+# Ordel: testing with the local engine
+
+Tests here are backed by **Ordel**, a deterministic QA engine over MCP (zero Ordel LLM).
+**Division of labor:** YOU navigate and judge ambiguity; **Ordel decides correctness.** Don't
+eyeball whether the app "looks right" — route every correctness claim through an Ordel oracle
+(a generated spec's pass/fail, an invariant, a fingerprint match). Agent-authored assertions
+are notoriously weak; Ordel's are deterministic. Call `get_app_context` first.
+
+> First run: enable the `ordel-cli` MCP server once — the client won't expose Ordel's tools
+> until you approve it. Claude Code: `/mcp` → enable. Cursor / Copilot: enable it in the
+> MCP/tools settings where you added `.mcp.json`. After a NEW Ordel tool ships, reconnect the
+> server to pick it up (or use the equivalent `ordel <cmd>` CLI, which is always current).
+
+## Verdicts: report only what is proven
+`run_test` (and `ordel run`) returns one verdict per test with its evidence:
+
+| verdict | meaning | how to report it |
+|---|---|---|
+| `pass` | ran, and its assertions (listed in `evidence.checks`) held | passed |
+| `fail` | ran and failed; `message` says why | a defect, or a broken locator to heal |
+| `flaky` | failed, then passed on retry | passed, and name it as flaky |
+| `unjudged` | green in Playwright but NOT proven: no assertion ran, no evidence was captured, or it depends on a heal no human has reviewed (`reasons` says which) | **not proven**: never "passed" |
+| `skipped` | did not run | skipped |
+
+A run whose `status` is `no_tests` checked nothing: say so, never "all green". Before you call
+a new test done, run it and confirm its verdict is `pass` with the checks you intended.
+
+## The method — don't stop at "mapped", FIND BUGS
+Mapping is the MEANS; the value is USING the map to run tests that expose defects.
+
+    orient ─▶ map ─▶ risk_rank ─▶ plan_tests ─▶ per-surface: record ─▶ generate_* ─▶ run_test
+       ▲                          (checklists)                                          │
+       └───────────── regression_set ◀── coverage_report ◀───────────────────────────┘
+
+1. **Orient** — `assess_context` (run-mode, lifecycle, existing assets + the REQUIRED next phase;
+   it detects any pre-existing FUNCTIONAL suite to reuse and flags unit tests as out of scope —
+   Ordel builds functional/e2e, not units) then `get_app_context` (what's already mapped).
+   An existing Playwright/Cypress suite? `adopt_suite` returns its flake report and heal
+   patches; show the human the patches, they apply or reject them (`ordel adopt --apply`).
+2. **Map** — YOU crawl, Ordel captures (see below). Reach every surface, not just the landing.
+3. **Prioritize** — `risk_rank` (where a bug would hurt most).
+4. **Plan** — `plan_tests` classifies each page into a SURFACE (auth / form / table / search /
+   cart / detail) and returns that surface's **CHECKLIST** — the exact things to test, each
+   item naming the tool that does it. WORK THE CHECKLIST; don't improvise coverage from memory.
+5. **Execute each checklist item** with the tool it names:
+   - `generate_scenarios <flow>` — happy + NEGATIVE (per constrained field) + boundary + replay.
+     A FAILING negative = a real bug (the app accepted bad input). RUN it; don't just read it.
+   - `generate_invariant <flow> parts total` — data-integrity (sum|min|max|count == total);
+     catches what URL tests can't (a discount applied twice: total != sum of line items).
+   - `generate_perf_check <flow> budget_ms` — median render <= budget (latency cliffs).
+   - `run_test` — execute and judge. This is where a regression is CAUGHT.
+6. **Measure + maintain** — `coverage_report` (map ∩ specs, real gaps), `regression_set
+   <changed pages>` (after a change, the exact specs to re-run, not all).
+
+The generated specs already classify gate-vs-filter, test each constrained field in isolation,
+and default the run target from the recorded flow — trust their verdicts over your own reading.
+
+## Map the app (YOU crawl, Ordel captures — a human can co-drive)
+Reach auth-gated, wizard, and SPA states that have no unique URL:
+- `browser_open` (once) -> `goto`/`click`/`fill`/`select`/`check` to navigate.
+- Read each action's `outcome` before judging it: `summary` in one line, `submit_blocked` +
+  `invalid_fields` (the browser refused the form, with each field's message), `reloaded` (a
+  same-url server re-render, so it WAS submitted), `messages` (new alerts/toasts),
+  `network_errors` (4xx/5xx during the action), `appeared`/`disappeared` test ids.
+  "No visible change" is itself a finding when you expected one.
+- **`browser_open(headed=true)`** opens a visible window that persists between calls, so a
+  HUMAN can watch, join, or take over the same session — they handle a CAPTCHA / a step that
+  needs judgment, you continue and `capture_state`. Offer headed when a human is available.
+- `capture_state` on any page worth mapping (fingerprints the current DOM — whoever drove).
+- `get_page(page_id, filter=inputs|buttons|links|all)` reads a mapped page back: each
+  element's testid, name, type, placeholder, href, `<select>` options (`value` is what
+  `select` takes) and visible text in its exact case. Use it; never parse `.ordel/graph.json`.
+- `dialog(action=accept|dismiss, text)` BEFORE a click that raises an alert/confirm/prompt;
+  Ordel records what fired (click/capture responses carry a `dialog` field — never swallowed).
+- Log in once, then `save_auth`; later `browser_open(use_auth=true)` skips login.
+- `browser_close` when done.
+- A human can record a flow themselves: `ordel record <name> <url>` (they click, Alt+click to
+  assert, close the window). It writes page objects and a spec that drives them.
+
+## Heals: you propose, a human decides
+`heal_selector`/`heal_element` recover a broken selector by fingerprint; pass `spec`, the file
+you'll change. Every heal is recorded pending HUMAN review, and until then `run_test` reports
+that spec's tests as `unjudged`. An `ambiguous`/`needs_agent` answer means pick by hand; a
+`failed`/`gone` answer means the element is really gone: report a real failure, don't hunt
+for a lookalike. You cannot apply or reject a heal yourself.
+
+## Other tools
+`generate_pom` (page objects from the map), `record_flow` (persist a step sequence + a
+happy-path spec that asserts the exact final url and a key element of the landing page; add
+your own assertions for what the flow must prove), `list_runs`. A value `record_flow`
+fills into a password-like field (type=password, or named/labelled password, secret, token,
+api key; mark any other with `"secret": true`) is never written: the flow and every spec read
+it from the variable in `needs_env` (`ORDEL_SECRET_<FIELD>`), so tell the user to set it
+before `run_test`, and never paste the value into a spec yourself. Prefer
+getByRole/getByTestId; read the map (`get_page`) before writing selectors, and heal (don't rewrite) when
+one breaks.
+
+Responses carry a `◉◯ ordel` signature — surface it so the work is attributed.

{ordel_cli-0.2.2 → ordel_cli-0.3.1}/ordel_cli/__init__.py

@@ -5,4 +5,4 @@ from __future__ import annotations
 from ordel_cli.heal_service import CircuitOpenError, HealService
 from ordel_cli.store import OrdelStore
 
-__all__ = ["OrdelStore", "HealService", "CircuitOpenError"]
+__all__ = ["CircuitOpenError", "HealService", "OrdelStore"]