ordel-cli 0.4.2__tar.gz → 0.4.4__tar.gz

{ordel_cli-0.4.2 → ordel_cli-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ordel-cli
-Version: 0.4.2
+Version: 0.4.4
 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
@@ -24,13 +24,28 @@ Description-Content-Type: text/markdown
 
 # ordel (free CLI)
 
-Local QA automation for individual devs — a persistent, deterministic "QA brain" your
+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.
 
+## Quick start
+
+You need [uv](https://docs.astral.sh/uv/). No separate install step: `uvx` fetches and runs
+the CLI on demand. In your project folder:
+
+```bash
+uvx --from ordel-cli ordel doctor   # checks Node, @playwright/test and Chromium, with fixes
+uvx --from ordel-cli ordel init     # creates .ordel/ and ORDEL.md
+uvx --from ordel-cli ordel mcp-install --client claude-code --write   # connects your agent
+```
+
+Other clients: `--client cursor`, `copilot`, `codex` or `claude-desktop`.
+To keep `ordel` on your PATH instead, run `uv tool install ordel-cli`; then every command
+below works as plain `ordel ...`.
+
 ## What works today (local, anonymous)
 
 ```bash
@@ -119,12 +134,12 @@ full `ordel.run/v1` document, which is also recorded under `.ordel/runs/`.
 | 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**
+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).
+  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.
+- `explore_app` / `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
@@ -133,28 +148,28 @@ project — run `ordel doctor` to check):
   init` gitignores it, and `run_test` loads it). Unset, those tests are skipped and the run
   reports `blocked` with the variable's name; Ordel scrubs the value from everything it
   stores, and `run_test` lists any spec or note you copied it into (`secret_leaks`).
-- `get_page` — read a mapped page back (inputs, buttons, links or all): each element's
+- `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` —
+- `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.
+- `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)
+## 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
+- Single `npx ordel` distribution: the plan is a compiled Python engine binary wrapped
+  in one npm package; not started (today's install path is `uv`, see Quick start above).
+- `eject` (one-command raw-Playwright export): not built yet, 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
+- **`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.
+- **`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
 
@@ -169,11 +184,11 @@ pytest packages/ordel-cli/tests packages/ordel-engine/tests -q
 - **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
+  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
+  modes. Team-scale concurrency is the hosted product's job.
+- **Browser tools need a local Node + `@playwright/test`** (`explore_app`/`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.
 

{ordel_cli-0.4.2 → ordel_cli-0.4.4}/README.md

@@ -1,12 +1,27 @@
 # ordel (free CLI)
 
-Local QA automation for individual devs — a persistent, deterministic "QA brain" your
+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.
 
+## Quick start
+
+You need [uv](https://docs.astral.sh/uv/). No separate install step: `uvx` fetches and runs
+the CLI on demand. In your project folder:
+
+```bash
+uvx --from ordel-cli ordel doctor   # checks Node, @playwright/test and Chromium, with fixes
+uvx --from ordel-cli ordel init     # creates .ordel/ and ORDEL.md
+uvx --from ordel-cli ordel mcp-install --client claude-code --write   # connects your agent
+```
+
+Other clients: `--client cursor`, `copilot`, `codex` or `claude-desktop`.
+To keep `ordel` on your PATH instead, run `uv tool install ordel-cli`; then every command
+below works as plain `ordel ...`.
+
 ## What works today (local, anonymous)
 
 ```bash
@@ -95,12 +110,12 @@ full `ordel.run/v1` document, which is also recorded under `.ordel/runs/`.
 | 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**
+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).
+  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.
+- `explore_app` / `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
@@ -109,28 +124,28 @@ project — run `ordel doctor` to check):
   init` gitignores it, and `run_test` loads it). Unset, those tests are skipped and the run
   reports `blocked` with the variable's name; Ordel scrubs the value from everything it
   stores, and `run_test` lists any spec or note you copied it into (`secret_leaks`).
-- `get_page` — read a mapped page back (inputs, buttons, links or all): each element's
+- `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` —
+- `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.
+- `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)
+## 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
+- Single `npx ordel` distribution: the plan is a compiled Python engine binary wrapped
+  in one npm package; not started (today's install path is `uv`, see Quick start above).
+- `eject` (one-command raw-Playwright export): not built yet, 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
+- **`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.
+- **`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
 
@@ -145,11 +160,11 @@ pytest packages/ordel-cli/tests packages/ordel-engine/tests -q
 - **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
+  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
+  modes. Team-scale concurrency is the hosted product's job.
+- **Browser tools need a local Node + `@playwright/test`** (`explore_app`/`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.
 

{ordel_cli-0.4.2 → ordel_cli-0.4.4}/ordel_cli/SKILL.md

@@ -118,8 +118,8 @@ These are where agents most often go wrong. The references expand on them.
 ## Scope
 
 Ordel covers browser-based functional testing. Unit and component tests stay with you and the
-project's own framework. Performance and load testing are outside this workflow (Ordel Cloud
-covers them). There is no first-class API testing tool here: do not promise API, security,
+project's own framework. Load testing is outside this workflow (Ordel Cloud covers it);
+`generate_perf_check` only asserts that a page's median render time stays within a budget. There is no first-class API testing tool here: do not promise API, security,
 accessibility or migration assurance from browser checks. Never claim exhaustive coverage or
 defect-free software. No account, cloud upload or endorsement is needed for any of this.
 

{ordel_cli-0.4.2 → ordel_cli-0.4.4}/ordel_cli/cli.py

@@ -58,7 +58,7 @@ def _resolve_launcher() -> str:
             return str(cand)
     return sys.executable  # last resort — user may need `ordel` on PATH
 
-app = typer.Typer(add_completion=False, help="Ordel — local QA automation for your coding agent.")
+app = typer.Typer(add_completion=False, help="Ordel: local QA automation for your coding agent.")
 
 
 def _print_version(value: bool) -> None:
@@ -72,7 +72,7 @@ def _main(
     version: bool = typer.Option(False, "--version", callback=_print_version, is_eager=True,
                                  help="Print the installed version and exit"),
 ) -> None:
-    """Ordel — local QA automation for your coding agent."""
+    """Ordel: local QA automation for your coding agent."""
 
 
 # The agent's operating manual has ONE source, the SKILL.md shipped in this package:
@@ -98,7 +98,7 @@ def _build_ordel_md() -> str:
     for name, text in _SKILL_REFS.items():
         title = text.split("\n", 1)[0].lstrip("# ").strip()
         sections = [sec.replace(f"`{name}`", f'the "{title}" section') for sec in sections]
-    return ("# ORDEL.md — testing context for this repo\n" + body
+    return ("# ORDEL.md - testing context for this repo\n" + body
             + "".join(f"\n---\n\n{sec}" for sec in sections))
 
 
@@ -115,7 +115,7 @@ def _store() -> OrdelStore:
 
 @app.command()
 def init() -> None:
-    """Create `.ordel/` + an ORDEL.md bridge file. Anonymous — no account."""
+    """Create `.ordel/` + an ORDEL.md bridge file. Anonymous - no account."""
     store = _store()
     try:
         store.init()
@@ -173,7 +173,7 @@ def ingest(path: str = typer.Argument("", help="a spec file or dir (relative); o
     Unit tests (Vitest/Jest) are skipped as out of scope. Then `ordel scenarios <flow>` etc."""
     store = _store()
     if not store.exists:
-        typer.echo("no .ordel/ here — run `ordel init`")
+        typer.echo("no .ordel/ here - run `ordel init`")
         raise typer.Exit(1)
     from ordel_cli.ingest import ingest as _ingest
     typer.echo(_ingest(store, path)["ascii"])
@@ -237,7 +237,7 @@ def catalog_export(dest: str = typer.Argument(..., help="file to write, e.g. cat
 
     store = _store()
     if not store.exists:
-        typer.echo("no .ordel/ here — run `ordel init`")
+        typer.echo("no .ordel/ here - run `ordel init`")
         raise typer.Exit(1)
     try:
         res = export_catalog(store, Path(dest))
@@ -272,7 +272,7 @@ def status() -> None:
     """Show local coverage: pages, elements, run history."""
     store = _store()
     if not store.exists:
-        typer.echo("no .ordel/ here — run `ordel init`")
+        typer.echo("no .ordel/ here - run `ordel init`")
         raise typer.Exit(1)
     try:
         pages = store.pages()
@@ -294,7 +294,7 @@ def graph(
     """Print the local app graph (.ordel/graph.json), or an ASCII tree with --ascii."""
     store = _store()
     if not store.exists:
-        typer.echo("no .ordel/ here — run `ordel init`")
+        typer.echo("no .ordel/ here - run `ordel init`")
         raise typer.Exit(1)
     if not ascii_:
         typer.echo((store.dir / "graph.json").read_text(encoding="utf-8"))
@@ -303,7 +303,7 @@ def graph(
 
     rows = store.pages_summary()
     if not rows:
-        typer.echo("(empty map — run `ordel explore <url>`)")
+        typer.echo("(empty map - run `ordel explore <url>`)")
         return
     # the same view an agent shows its user after a mapping step
     typer.echo(map_tree(rows, limit=None))
@@ -311,7 +311,7 @@ def graph(
 
 @app.command()
 def coverage(fmt: str = typer.Option("ascii", help="ascii | markdown | mermaid")) -> None:
-    """What's TESTED vs NOT — map ∩ specs, per page (✓ full / ⚠ partial / ✗ untested)."""
+    """What's TESTED vs NOT - map ∩ specs, per page (✓ full / ⚠ partial / ✗ untested)."""
     from ordel_cli.coverage import coverage_report
     store = _store()
     res = coverage_report(store)
@@ -426,7 +426,7 @@ def report(
     Ordel shows but does not verify. It makes no claim the store can't back."""
     store = _store()
     if not store.exists:
-        typer.echo("no .ordel/ here — run `ordel init`")
+        typer.echo("no .ordel/ here - run `ordel init`")
         raise typer.Exit(1)
     try:
         pages = store.pages()
@@ -494,7 +494,7 @@ def report(
         typer.echo(json.dumps(doc, indent=2))
         return
     lines = [
-        "**Ordel — local QA report**",
+        "**Ordel: local QA report**",
         "",
         "| Metric | Value |",
         "|---|---|",
@@ -552,12 +552,12 @@ def report(
 def eject() -> None:
     """Point at your already-plain-Playwright artifacts (there's no lock-in to leave).
 
-    The one-command export is scaffold (M3). But nothing traps you meanwhile: every test
-    Ordel generates is already a plain Playwright file on disk — `tests/*.spec.ts` +
-    `pages/*.ts` — copy them anywhere and run them with `npx playwright test`, no Ordel needed.
+    The one-command export is not built yet. But nothing traps you meanwhile: every test
+    Ordel generates is already a plain Playwright file on disk - `tests/*.spec.ts` +
+    `pages/*.ts` - copy them anywhere and run them with `npx playwright test`, no Ordel needed.
     """
-    typer.echo("eject: the one-command export is not wired yet (M3), but there's no lock-in — "
-               "your generated tests are already plain Playwright at tests/*.spec.ts + pages/*.ts; "
+    typer.echo("eject: the one-command export is not wired yet, but there is no lock-in. "
+               "Your generated tests are already plain Playwright at tests/*.spec.ts + pages/*.ts: "
                "copy them and run `npx playwright test`.")
     raise typer.Exit(2)
 
@@ -670,7 +670,7 @@ def mcp_install(
 ) -> None:
     """Print (or --write) the MCP config that points a coding agent at the local Ordel server.
 
-    The server runs via `uvx --from ordel-cli ordel mcp-serve` — no separate install; uv fetches
+    The server runs via `uvx --from ordel-cli ordel mcp-serve` - no separate install; uv fetches
     + caches on first spawn. Add --installed to use a persistent `uv tool install` instead.
     `--skill` installs the agent skill where the client loads repo skills
     (.claude/skills/ordel-cli/ for Claude Code, .agents/skills/ordel-cli/ for Codex).
@@ -682,7 +682,7 @@ def mcp_install(
     inv = _mcp_invocation(installed)
     # uv preflight: without it, `uvx ...` fails and the client shows only an opaque spawn error.
     if not installed and shutil.which("uv") is None:
-        typer.echo("⚠ `uv` is not on your PATH — the server launches via `uvx`, so your client "
+        typer.echo("⚠ `uv` is not on your PATH - the server launches via `uvx`, so your client "
                    "can't start it until you install uv:")
         typer.echo("    macOS/Linux:  curl -LsSf https://astral.sh/uv/install.sh | sh")
         typer.echo("    Windows:      irm https://astral.sh/uv/install.ps1 | iex")
@@ -706,7 +706,7 @@ def mcp_install(
                 "your Claude Desktop config (claude_desktop_config.json)"
                 if name == "claude-desktop" else "~/.codex/config.toml")
             if write:
-                typer.echo(f"# {name} uses a global config — add manually to {where}:")
+                typer.echo(f"# {name} uses a global config - add manually to {where}:")
             else:
                 typer.echo(f"# {name}: add to {where}"
                            + ("  (or: --write)" if spec["path"] else ""))
@@ -717,7 +717,7 @@ def mcp_install(
             typer.echo(_install_skill(name))
     if not client:
         others = ", ".join(k for k in _MCP_CLIENTS if k != "claude-code")
-        typer.echo(f"# other clients: {others} — re-run with --client <name>")
+        typer.echo(f"# other clients: {others} - re-run with --client <name>")
     typer.echo("\nFirst run: enable the `ordel-cli` server once (one-time approval).\n"
                "  Claude Code: `/mcp` -> enable.  Cursor / Copilot: enable it in MCP/tools settings.")
     if "codex" in names:
@@ -777,13 +777,13 @@ def explore(
     """Explore a running app page and build the local map (.ordel/graph.json).
 
     Drives the project's Playwright to capture the page's meaningful elements so the
-    map reflects the real rendered app — grounding for the agent's assertions.
+    map reflects the real rendered app - grounding for the agent's assertions.
     """
     from ordel_cli.explore import explore as _explore
 
     store = OrdelStore(Path.cwd())
     if not store.exists:
-        typer.echo("no .ordel/ here — run `ordel init` first")
+        typer.echo("no .ordel/ here - run `ordel init` first")
         raise typer.Exit(2)
     res = _explore(store, url, page_id=page or None)
     if res["status"] == "explored":
@@ -804,7 +804,7 @@ def pom(
 
     store = OrdelStore(Path.cwd())
     if not store.exists:
-        typer.echo("no .ordel/ here — run `ordel init` first")
+        typer.echo("no .ordel/ here - run `ordel init` first")
         raise typer.Exit(2)
     res = generate_pom(store, page_id)
     if res["status"] == "generated":

{ordel_cli-0.4.2 → ordel_cli-0.4.4}/ordel_cli/context.py

@@ -97,6 +97,17 @@ def assess_context(store: OrdelStore) -> dict[str, Any]:
             if low.endswith(_SRC_SUFFIXES):
                 source_files += 1
 
-    return _assess(ContextScan(pages=pages, flows=flows, runs=runs, functional_specs=functional,
-                               ordel_specs=ordel, unit_specs=unit, unknown_specs=unknown,
-                               page_objects=page_objects, has_ci=has_ci, source_files=source_files))
+    res = _assess(ContextScan(pages=pages, flows=flows, runs=runs, functional_specs=functional,
+                              ordel_specs=ordel, unit_specs=unit, unknown_specs=unknown,
+                              page_objects=page_objects, has_ci=has_ci, source_files=source_files))
+    # FINDINGS-042 #3: get_app_context said initialized:false while this said "ok, MAP next" in
+    # the same folder, and mapping then failed. Both now say the same thing.
+    res["initialized"] = store.exists
+    if not store.exists:
+        before = str(res.get("required_next_phase", ""))
+        res["required_next_phase"] = ("INIT - this folder has no .ordel/ yet: run `ordel init` "
+                                      "here first (it creates .ordel/ and ORDEL.md); nothing can be "
+                                      "mapped, recorded or run until then")
+        if isinstance(res.get("ascii"), str) and before:
+            res["ascii"] = res["ascii"].replace(before, res["required_next_phase"])
+    return res

{ordel_cli-0.4.2 → ordel_cli-0.4.4}/ordel_cli/coverage.py

@@ -38,7 +38,7 @@ def coverage_report(store: OrdelStore, force: bool = False) -> dict[str, Any]:
     """Compute coverage of the map by the project's specs. Returns
     {status, summary, ascii, markdown, mermaid}."""
     if not store.exists:
-        return {"status": "no_map", "note": "no .ordel/ — run `ordel init` + explore first"}
+        return {"status": "no_map", "note": "no .ordel/ - run `ordel init` + explore first"}
     try:
         # T2P-2/BUG-2215: read the whole graph ONCE (a corrupt/malformed/too-deep
         # graph degrades to a clean store_error here, not a raw traceback; and a
@@ -48,7 +48,7 @@ def coverage_report(store: OrdelStore, force: bool = False) -> dict[str, Any]:
         return {"status": "store_error", "note": str(e)}
     if not all_els and not force:  # readiness gate: nothing to measure coverage against
         return {"status": "not_ready", "missing": "map",
-                "note": "no pages captured yet — coverage measures the map against your specs. "
+                "note": "no pages captured yet - coverage measures the map against your specs. "
                         "Map the app first (explore_app / capture_state), or pass force=true."}
     specs = _read_specs(store.root)
     host = ""

{ordel_cli-0.4.2 → ordel_cli-0.4.4}/ordel_cli/doctor.py

@@ -59,8 +59,8 @@ def check_playwright(cwd: Path) -> Check:
         return Check("Playwright", "warn", "installed but version unreadable",
                      "reinstall: npm i -D @playwright/test@latest")
     if _ver_tuple(v)[:2] < _PW_OK_MIN:
-        return Check("Playwright", "warn", f"{v} — validated on 1.5x/1.6x",
-                     "consider: npm i -D @playwright/test@latest")
+        return Check("Playwright", "warn", f"{v} is older than 1.40",
+                     "upgrade: npm i -D @playwright/test@latest")
     return Check("Playwright", "ok", f"{v}")
 
 
@@ -141,9 +141,9 @@ class Report:
             lines.append(f"  {_MARK[c.status]} {c.name:<{w}}{tail}{fix}")
         fails = sum(c.status == "fail" for c in self.checks)
         warns = sum(c.status == "warn" for c in self.checks)
-        summary = ("ready — all checks passed" if fails == 0 and warns == 0 else
-                   f"{fails} to fix before recording or running, {warns} warning(s) — "
-                   "see fixes above")
+        summary = ("ready: all checks passed" if fails == 0 and warns == 0 else
+                   f"{fails} to fix before recording or running, {warns} warning(s). "
+                   "See the fixes above.")
         return "\n".join(lines) + f"\n  {summary}"
 
 

{ordel_cli-0.4.2 → ordel_cli-0.4.4}/ordel_cli/explore.py

@@ -140,6 +140,16 @@ def persist_capture(store: OrdelStore, doc: dict[str, Any], page_id: str,
     The fingerprint transform is the pure ``fingerprints_from_capture``; this adapter only
     writes the result to the store."""
     fps, url, title = fingerprints_from_capture(doc, fallback_url=fallback_url)
+    # FINDINGS-042 #1: after a failed navigation the browser sits on chrome-error://chromewebdata/;
+    # mapping it under the agent's page_id took that id from the real page, which was then saved
+    # under a site-qualified name, and coverage counted an error page.
+    scheme = url.split(":", 1)[0].lower() if ":" in url else ""
+    if scheme not in ("http", "https", "file"):
+        return {"status": "not_mapped", "page_id": page_id, "url": url, "title": title,
+                "elements": 0,
+                "note": (f"nothing was mapped: the browser is on {url or 'no page'}, not a page of "
+                         "the app (a navigation failed, or nothing is loaded yet); goto a working "
+                         "address and capture again")}
     # A capture replaces its page's elements. When the id already belongs to ANOTHER site (a
     # second app's root is HomePage too), replacing it would silently discard that site's map:
     # save under a site-qualified id and say so. The same site re-captured still refreshes.

{ordel_cli-0.4.2 → ordel_cli-0.4.4}/ordel_cli/ingest.py

@@ -99,16 +99,16 @@ def ingest(store: OrdelStore, path: str = "") -> dict[str, Any]:
         lines.append(f"  {cypress_specs} of them Cypress: parsed into the same flow format, so "
                      "`ordel scenarios <flow>` turns each into a Playwright spec")
     if skipped_unit:
-        lines.append(f"  skipped {skipped_unit} unit test(s) — out of scope (Ordel does functional/e2e)")
+        lines.append(f"  skipped {skipped_unit} unit test(s) - out of scope (Ordel does functional/e2e)")
     if skipped_ordel:
         lines.append(f"  skipped {skipped_ordel} Ordel-generated spec(s) (already ours)")
     if unparsed:
-        lines.append(f"  {unparsed} action line(s) used idioms we couldn't parse — re-record those flows")
+        lines.append(f"  {unparsed} action line(s) used idioms we couldn't parse - re-record those flows")
     lines.append(f"  assertions carried into the flows: {kept_asserts}"
                  + (f"; NOT carried: {dropped_asserts} (the original specs still check them, "
                     "the generated scenarios do not)" if dropped_asserts else ""))
     if capped:
-        lines.append(f"  stopped at the {_MAX_FLOWS}-flow cap — ingest a subdir at a time for the rest")
+        lines.append(f"  stopped at the {_MAX_FLOWS}-flow cap - ingest a subdir at a time for the rest")
     if flows_created:
         lines.append("  next: generate_scenarios <flow> (adds negative/boundary on top) or "
                      "generate_invariant; re-record a flow to capture its final_url + strengthen")

{ordel_cli-0.4.2 → ordel_cli-0.4.4}/ordel_cli/mcp_server.py

@@ -40,7 +40,7 @@ from ordel_cli.runner import run_and_record
 from ordel_cli.store import OrdelStore, StoreError
 
 _INSTRUCTIONS = (
-    "Ordel is this repo's durable QA engine. For any testing task use these tools — "
+    "Ordel is this repo's durable QA engine. For any testing task use these tools - "
     "do NOT hand-roll Playwright. Call get_app_context first; heal_selector recovers "
     "broken selectors deterministically. "
     "Work in the open, one step at a time: before the first tool call, show the user a short "
@@ -89,7 +89,7 @@ _FAILURE_STATUSES: frozenset[str] = frozenset({
     "unknown_element", "record_failed", "capture_failed", "http_error", "no_playwright",
     "no_node", "timeout", "no_session", "session_error", "nav_failed", "failed",
     "circuit_open", "error", "exists", "action_failed", "ambiguous", "not_actionable",
-    "invalid_target", "flow_rejected",
+    "invalid_target", "flow_rejected", "not_mapped",
 })
 
 
@@ -368,10 +368,10 @@ def build_server(root: str | Path = ".") -> FastMCP:
             out = heals.heal(page_id, _fp(broken), cands)
         except AmbiguityError as e:
             return {"status": "needs_agent", "candidates": e.candidates, "best": e.best,
-                    "note": "ambiguous — pick the right element id yourself"}
+                    "note": "ambiguous - pick the right element id yourself"}
         except HealFailedError as e:
             return {"status": "failed", "best": e.best,
-                    "note": "element gone from this snapshot — surface as a real failure"}
+                    "note": "element gone from this snapshot - surface as a real failure"}
         except CircuitOpenError as e:
             return {"status": "circuit_open", "fails": e.fails, "note": str(e)}
         return _healed(page_id, str(broken.get("id") or broken.get("accessible_name_canon") or ""),
@@ -480,7 +480,7 @@ def build_server(root: str | Path = ".") -> FastMCP:
                 u = urlparse(start)
                 if u.scheme and u.netloc:
                     base_url = f"{u.scheme}://{u.netloc}"
-                    note = (f"base_url defaulted to {base_url} from recorded flow '{name}' — the "
+                    note = (f"base_url defaulted to {base_url} from recorded flow '{name}' - the "
                             "specs use relative URLs; pass base_url to run against another target")
                     break
         doc = run_and_record(store, spec=spec or None,
@@ -734,7 +734,7 @@ def build_server(root: str | Path = ".") -> FastMCP:
             # distinct from invalid_input (dogfood V): "no session" is a workflow state, not
             # the APP rejecting input — the old label read as a validation failure, misleading
             # exactly while testing validation.
-            raise _NoSession("no browser session — call browser_open first")
+            raise _NoSession("no browser session - call browser_open first")
         return _session[0]
 
     def _acted(raw: dict[str, Any]) -> dict[str, Any]:
@@ -786,7 +786,7 @@ def build_server(root: str | Path = ".") -> FastMCP:
             _session[0] = sess
             out = {"status": "opened", **res}
             if res.get("auth_expired"):
-                out["warning"] = ("saved auth (.ordel/state.json) has EXPIRED cookies — a gated "
+                out["warning"] = ("saved auth (.ordel/state.json) has EXPIRED cookies - a gated "
                                   "goto will bounce to login. Log in again + save_auth.")
             return out
         return _guard(_do)
@@ -808,10 +808,10 @@ def build_server(root: str | Path = ".") -> FastMCP:
             notes = []
             if res.get("redirected"):
                 notes.append(f"redirected: requested {res.get('requested')} but landed on "
-                             f"{res.get('url')}" + (" (looks like a login page — auth may be "
+                             f"{res.get('url')}" + (" (looks like a login page - auth may be "
                              "missing/expired; re-run save_auth)" if res.get("looks_like_login") else ""))
             if res.get("slow_load"):
-                notes.append("page committed but network stayed active (analytics/ws/ads) — "
+                notes.append("page committed but network stayed active (analytics/ws/ads) - "
                              "loaded OK, not a failure")
             if notes:
                 res["warning"] = " | ".join(notes)
@@ -911,6 +911,9 @@ def build_server(root: str | Path = ".") -> FastMCP:
         Returns {page_id, url, title, elements}. No LLM."""
         from ordel_cli.explore import page_id_from_url, persist_capture
         def _do() -> dict[str, Any]:
+            if not store.exists:
+                return {"status": "not_initialized",
+                        "note": "this folder has no .ordel/ yet: run `ordel init` here first"}
             doc = _sess().capture()
             if not doc.get("ok", True):
                 return {"status": "session_error", "note": doc.get("error", "capture failed")}
@@ -928,7 +931,7 @@ def build_server(root: str | Path = ".") -> FastMCP:
                                f"page_id={twins[0]!r} to update that page instead of keeping "
                                "two copies")
             if doc.get("looks_like_login"):
-                res["warning"] = ("this page looks like a LOGIN page — if you expected a "
+                res["warning"] = ("this page looks like a LOGIN page - if you expected a "
                                   f"different page, you may be mapping the wrong state under '{pid}' "
                                   "(auth missing/expired?)")
             return res
@@ -963,14 +966,21 @@ def build_server(root: str | Path = ".") -> FastMCP:
         if isinstance(results, tuple) and len(results) == 2 and isinstance(results[1], dict):
             content, structured = results
             blocks = list(content)
+            failed = _is_failure(name, structured)
+            if failed and not structured.get("ascii"):
+                # FINDINGS-042 #4: a failure is a milestone the person must see too; the skill's
+                # checkpoints paste `ascii`, which only successes carried.
+                why = str(structured.get("note") or structured.get("error") or "").strip()
+                first = why.splitlines()[0][:300] if why else ""
+                structured = {**structured, "ascii": f"✗ {name}: {structured.get('status') or 'failed'}"
+                              + (f" - {first}" if first else "")}
             summary = structured.get("ascii")
             if isinstance(summary, str) and summary:
                 # The step summary as its own first, plain-text block: a host that shows tool
                 # output shows the map or the verdicts, not an escaped JSON line (the 0.4.0
                 # evaluation's F5: the summary reached the agent but not the person).
                 blocks = [TextContent(type="text", text=summary), *blocks]
-            return CallToolResult(content=blocks, structuredContent=structured,
-                                  isError=_is_failure(name, structured))
+            return CallToolResult(content=blocks, structuredContent=structured, isError=failed)
         return results
 
     mcp._mcp_server.call_tool(validate_input=False)(_wire_call_tool)

{ordel_cli-0.4.2 → ordel_cli-0.4.4}/ordel_cli/pom.py

@@ -41,7 +41,7 @@ def generate_pom(store: OrdelStore, page_id: str, write: bool = True) -> dict[st
                 result["status"] = "exists_unmanaged"
                 result["note"] = (
                     f"pages/{result['class_name']}.ts already exists WITHOUT Ordel's managed block "
-                    "— left untouched (your edits are safe). Add the `// ordel:locators` … "
+                    "- left untouched (your edits are safe). Add the `// ordel:locators` … "
                     "`// ordel:end` markers where locators should refresh, or delete the file to "
                     "regenerate from scratch.")
                 result["path"] = p.relative_to(store.root).as_posix()

{ordel_cli-0.4.2 → ordel_cli-0.4.4}/ordel_cli/qa_plan.py

@@ -33,7 +33,7 @@ def _require_map(store: OrdelStore, force: bool) -> dict[str, Any] | None:
     try:
         if not store.pages():
             return {"status": "not_ready", "missing": "map",
-                    "note": "no pages captured yet — this plans from the map. Map the app first "
+                    "note": "no pages captured yet - this plans from the map. Map the app first "
                             "(explore_app, or browser_open + goto/click + capture_state), then "
                             "retry. Pass force=true to run against the empty map anyway."}
     except StoreError:
@@ -70,7 +70,7 @@ def _scored_rows(store: OrdelStore) -> list[dict[str, Any]]:
 def risk_rank(store: OrdelStore, force: bool = False) -> dict[str, Any]:
     """Rank mapped pages by risk. Returns {status, rows, ascii}."""
     if not store.exists:
-        return {"status": "no_map", "note": "no .ordel/ — explore first"}
+        return {"status": "no_map", "note": "no .ordel/ - explore first"}
     if gate := _require_map(store, force):
         return gate
     try:
@@ -83,7 +83,7 @@ def risk_rank(store: OrdelStore, force: bool = False) -> dict[str, Any]:
 def plan_tests(store: OrdelStore, force: bool = False) -> dict[str, Any]:
     """A prioritized page-by-page test plan. Returns {status, rows, ascii}."""
     if not store.exists:
-        return {"status": "no_map", "note": "no .ordel/ — explore first"}
+        return {"status": "no_map", "note": "no .ordel/ - explore first"}
     if gate := _require_map(store, force):
         return gate
     try:
@@ -112,12 +112,12 @@ def regression_set(store: OrdelStore, changed_pages: list[str] | None = None,
     any element on a changed page). Empty/None changed -> full set. Returns
     {status, specs, changed, ascii}."""
     if not store.exists:
-        return {"status": "no_map", "note": "no .ordel/ — explore first"}
+        return {"status": "no_map", "note": "no .ordel/ - explore first"}
     if gate := _require_map(store, force):
         return gate
     spec_map = _read_specs_map(store.root)
     if not spec_map:
-        return {"status": "no_specs", "note": "no specs in tests/ — nothing to select"}
+        return {"status": "no_specs", "note": "no specs in tests/ - nothing to select"}
     all_pages = set(store.pages())
     # A caller passing specific pages means "just these" — if a typo'd id matched nothing,
     # do NOT silently widen to the whole suite (that would re-run everything, the opposite
@@ -127,8 +127,8 @@ def regression_set(store: OrdelStore, changed_pages: list[str] | None = None,
         unknown = [p for p in changed_pages if p not in all_pages]
         if not targets:
             return {"status": "unknown_pages", "unknown": unknown, "specs": [], "changed": [],
-                    "note": f"none of {changed_pages} are in the map — nothing selected",
-                    "ascii": f"Regression set — 0 specs: none of {', '.join(changed_pages)} "
+                    "note": f"none of {changed_pages} are in the map - nothing selected",
+                    "ascii": f"Regression set - 0 specs: none of {', '.join(changed_pages)} "
                              "are mapped pages"}
     else:
         targets, unknown = store.pages(), []

{ordel_cli-0.4.2 → ordel_cli-0.4.4}/ordel_cli/record.py

@@ -94,7 +94,7 @@ def _selector_testid_hint(store: OrdelStore, steps: list[dict[str, Any]]) -> str
     if not hit:
         return ""
     ex = hit[0]
-    return (f'  hint: {", ".join("#" + h for h in hit)} is a data-testid, not a DOM id — map '
+    return (f'  hint: {", ".join("#" + h for h in hit)} is a data-testid, not a DOM id - map '
             f'keys are testids. Target it with {{"testid": "{ex}"}} instead of '
             f'{{"selector": "#{ex}"}}.')
 
@@ -484,6 +484,8 @@ def record_human(store: OrdelStore, name: str, url: str, headed: bool = True,
         # the id the page was actually saved under (another site may already hold the plain one)
         saved = persist_capture(store, {**page, "url": page_url}, page_id_from_url(page_url),
                                 fallback_url=page_url)
+        if saved.get("status") == "not_mapped":
+            continue
         page_ids[page_url] = str(saved["page_id"])
     for s in steps:
         u = strip_query(str(s.get("url", "")))

{ordel_cli-0.4.2 → ordel_cli-0.4.4}/ordel_cli/runner.py

@@ -90,7 +90,7 @@ def _ephemeral_config(cwd: str, base_url: str) -> str:
         "  testIgnore: ['**/node_modules/**', '**/.ordel/**'],\n"
         "  fullyParallel: true,\n"
         f"  use: {{ baseURL: {json.dumps(base_url)} }},\n"
-        "  // The target app is already running (external) — nothing to launch.\n"
+        "  // The target app is already running (external) - nothing to launch.\n"
         "});\n"
     )
     fd, path = tempfile.mkstemp(prefix="ordel.pw.", suffix=".config.cjs", dir=cwd)
@@ -133,7 +133,7 @@ def run_playwright(cwd: str, spec: str | None = None,
     cwd = str(Path(cwd).resolve())
     npx = _npx_argv()
     if npx is None:
-        return error_outcome("npx not found — is Node/Playwright installed in this project?")
+        return error_outcome("npx not found - is Node/Playwright installed in this project?")
     args = [*npx, "playwright", "test", f"--reporter=json,{_EVIDENCE_REPORTER}"]
     if headed:
         args.append("--headed")
@@ -186,7 +186,7 @@ def run_playwright(cwd: str, spec: str | None = None,
         except FileNotFoundError:
             # npx is pre-resolved via _npx_argv; reaching here means the resolved launcher
             # (or cmd.exe on Windows) could not be spawned.
-            return error_outcome("could not launch npx — is Node/Playwright installed in this project?")
+            return error_outcome("could not launch npx - is Node/Playwright installed in this project?")
         except subprocess.TimeoutExpired as e:
             # Surface what actually ran and whatever it printed before the hang - the
             # generic "timed out after Ns" message hid the command line and any partial

{ordel_cli-0.4.2 → ordel_cli-0.4.4}/ordel_cli/scenarios.py

@@ -47,11 +47,11 @@ def _load_flow_doc(store: OrdelStore, flow_name: str) -> tuple[dict[str, Any] |
     flow file exists, valid JSON, top-level is an object, ``steps`` is a list of
     objects."""
     if not store.exists:
-        return None, {"status": "no_map", "note": "no .ordel/ — run `ordel init` first"}
+        return None, {"status": "no_map", "note": "no .ordel/ - run `ordel init` first"}
     path = store.dir / "flows" / f"{flow_name}.json"
     if not path.exists():
         return None, {"status": "unknown_flow",
-                      "note": f"no recorded flow '{flow_name}' — run `record_flow` first"}
+                      "note": f"no recorded flow '{flow_name}' - run `record_flow` first"}
     try:
         doc = json.loads(path.read_text(encoding="utf-8"))
     except (json.JSONDecodeError, UnicodeDecodeError) as e:
@@ -81,6 +81,17 @@ def _load_flow_doc(store: OrdelStore, flow_name: str) -> tuple[dict[str, Any] |
                 return None, {"status": "invalid_flow",
                               "note": f"flow '{flow_name}': step {i} field '{key}' must be a "
                                       f"string, number or boolean, got {type(value).__name__}"}
+    # FINDINGS-042 #5: a hand-written or 0.3-era flow with "transitions": 4 crashed with
+    # "'int' object is not iterable" when the scenarios read each step's page.
+    transitions = doc.get("transitions")
+    if transitions is not None and (not isinstance(transitions, list)
+                                    or not all(isinstance(t, dict) for t in transitions)):
+        return None, {"status": "invalid_flow",
+                      "note": f"flow '{flow_name}': 'transitions' must be a list of step records "
+                              f"(got {type(transitions).__name__}); record the flow again"}
+    if not isinstance(doc.get("final_url", ""), str):
+        return None, {"status": "invalid_flow",
+                      "note": f"flow '{flow_name}': 'final_url' must be a string"}
     return doc, None
 
 
@@ -157,7 +168,7 @@ def generate_invariant(store: OrdelStore, flow_name: str, parts: str, total: str
             missing = [t for t in (parts, total) if t not in known]
             if missing:
                 result.setdefault("warnings", []).append(
-                    f"testid(s) not in the captured map: {', '.join(missing)} — the check will "
+                    f"testid(s) not in the captured map: {', '.join(missing)} - the check will "
                     "match 0 cells and fail at runtime. Re-capture the page or fix the testid "
                     "(map keys are the element testids).")
     nm = name or f"{flow_name}-invariant"

{ordel_cli-0.4.2 → ordel_cli-0.4.4}/ordel_cli/session_driver.cjs

@@ -563,6 +563,26 @@ function requirePage(msg) {
   if (needsPage && !page) throw new Error("no open session — call 'open' first");
 }
 
+// FINDINGS-042 #2: a click whose request never answered held the chain for as long as the
+// server took (forever, on a hung login POST), so every later command - current_url included -
+// timed out behind it and the session was wedged. Each page command now answers within this
+// deadline (under the MCP side's 60 s) and frees the chain; open and close keep their own.
+const STEP_DEADLINE_MS = 45000;
+function withDeadline(work, cmd) {
+  work.catch(() => {}); // an abandoned step may still fail later: never an unhandled rejection
+  let timer;
+  const deadline = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      const e = new Error(`'${cmd}' did not finish within ${STEP_DEADLINE_MS / 1000}s: the page is still `
+        + 'waiting (a request that has not answered, or a page that never settles). The session is '
+        + 'still usable: current_url, goto another address, or browser_close.');
+      e.deadline = true;
+      reject(e);
+    }, STEP_DEADLINE_MS);
+  });
+  return Promise.race([work, deadline]).finally(() => clearTimeout(timer));
+}
+
 // Serialize commands so overlapping stdin lines can't race the single page.
 let chain = Promise.resolve();
 const rl = readline.createInterface({ input: process.stdin });
@@ -574,10 +594,17 @@ rl.on('line', (line) => {
     try { msg = JSON.parse(text); } catch (e) { write({ ok: false, error: 'bad json' }); return; }
     try {
       requirePage(msg);
-      const res = await handle(msg);
+      const bounded = msg.cmd !== 'open' && msg.cmd !== 'close';
+      const res = bounded ? await withDeadline(handle(msg), msg.cmd) : await handle(msg);
       write({ id: msg.id, ...res });
       if (msg.cmd === 'close') await shutdown(0);
     } catch (e) {
+      if (e && e.deadline) { // no element diagnosis: probing the busy page could hang again
+        let url = '';
+        try { url = page ? page.url() : ''; } catch (_) { /* page gone */ }
+        write({ id: msg.id, ok: false, error_kind: 'no_response', url, error: e.message });
+        return;
+      }
       const res = ELEMENT_CMDS.has(msg.cmd) && page ? await diagnose(msg, e)
         : { ok: false, error: String((e && e.message) || e).replace(ANSI, '') };
       write({ id: msg.id, ...res });

{ordel_cli-0.4.2 → ordel_cli-0.4.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ordel-cli"
-version = "0.4.2"
+version = "0.4.4"
 description = "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."
 readme = "README.md"
 requires-python = ">=3.11"