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

{ordel_cli-0.2.1 → ordel_cli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ordel-cli
-Version: 0.2.1
+Version: 0.2.2
 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
@@ -14,8 +14,8 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Topic :: Software Development :: Testing
 Requires-Python: >=3.11
 Requires-Dist: mcp>=1.0
-Requires-Dist: ordel-engine==0.2.1
-Requires-Dist: ordel-tools==0.2.1
+Requires-Dist: ordel-engine==0.2.2
+Requires-Dist: ordel-tools==0.2.2
 Requires-Dist: typer>=0.12
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == 'dev'

{ordel_cli-0.2.1 → ordel_cli-0.2.2}/ordel_cli/cli.py

@@ -42,34 +42,44 @@ app = typer.Typer(add_completion=False, help="Ordel — local QA automation for
 
 _ORDEL_MD = """# ORDEL.md — testing context for this repo
 
-Tests here are backed by **Ordel**, a deterministic QA engine over MCP (zero Ordel LLM —
-YOU are the brain, Ordel is the truth). Use Ordel's tools rather than hand-rolling
-Playwright. Call `get_app_context` first.
+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).
 
-## The point: FIND BUGS
-Mapping/recording is the MEANS, not the goal. The value is USING the artifacts to run
-tests + scenarios that expose defects. Don't stop at "the app is mapped" — drive the loop:
-
-    risk_rank ─▶ plan_tests ─▶ capture/record ─▶ generate_scenarios ─▶ run_test
-        ▲                                                                  │
-        └──────────── regression_set ◀── coverage_report ◀────────────────┘
-
-- `risk_rank` / `plan_tests` — where a bug would hurt most, and what to test first.
-- `generate_scenarios <flow>` — turn a recorded flow into happy+NEGATIVE+boundary+replay
-  specs. A FAILING negative/boundary test = a real bug (app accepted bad input). THIS is
-  the outcome; run the generated spec, don't just read it.
-- `generate_invariant <flow> parts total` — a DATA-INTEGRITY test: after replaying the flow,
-  assert sum|min|max|count of the labeled cells == the total. Catches bugs URL/path tests
-  can't (e.g. a discount applied twice: charged total != sum of line items).
-- `generate_perf_check <flow> budget_ms` — a PERFORMANCE-BUDGET test: median render <= budget.
-  Catches latency regressions / O(n^2) cliffs. (CLI: `ordel invariant`/`ordel perf` too.)
-- `coverage_report` — which mapped elements a spec asserts vs gaps (ASCII, in-chat).
-- `regression_set <changed pages>` — after a change, the exact specs to re-run (not all).
+## 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).
+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 + record pass/fail. 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 pass/fail over your own reading.
 
 ## Map the app (YOU crawl, Ordel captures)
 Reach auth-gated, wizard, and SPA states that have no unique URL:
@@ -127,6 +137,30 @@ def doctor() -> None:
         raise typer.Exit(1)
 
 
+@app.command()
+def assess() -> None:
+    """Orient: run-mode, lifecycle, existing assets + the required next phase.
+
+    Functional/e2e is Ordel's domain; unit tests (Vitest/Jest) are detected and flagged out of
+    scope. Reads the local project STRUCTURE only (counts/presence), no code comprehension."""
+    store = _store()
+    from ordel_cli.context import assess_context
+    typer.echo(assess_context(store)["ascii"])
+
+
+@app.command()
+def ingest(path: str = typer.Argument("", help="a spec file or dir (relative); omit for the whole project")) -> None:
+    """Import an existing FUNCTIONAL Playwright suite into Ordel flows (REUSE, don't re-record).
+
+    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`")
+        raise typer.Exit(1)
+    from ordel_cli.ingest import ingest as _ingest
+    typer.echo(_ingest(store, path)["ascii"])
+
+
 @app.command()
 def status() -> None:
     """Show local coverage: pages, elements, run history."""

ordel_cli-0.2.2/ordel_cli/context.py

@@ -0,0 +1,99 @@
+"""assess_context adapter — the ORIENT step's I/O.
+
+Reads the .ordel store state + does a read-only walk of the project (node_modules/.git/.ordel and
+other build/output dirs excluded) to count specs, page-objects, CI, and app source, then hands the
+counts to the pure ``ordel_tools.context.assess_context``. No writes; bounded work.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from ordel_tools.context import ContextScan
+from ordel_tools.context import assess_context as _assess
+
+from ordel_cli.store import OrdelStore, StoreError
+
+_SPEC_SUFFIXES = (".spec.ts", ".spec.js", ".spec.mjs", ".test.ts", ".test.js")
+_SRC_SUFFIXES = (".ts", ".tsx", ".js", ".jsx", ".mjs", ".py", ".vue", ".svelte")
+_POM_HINTS = ("page.ts", "page.js", ".po.ts", ".po.js")
+_SKIP_DIRS = {"node_modules", ".git", ".ordel", "dist", "build", ".venv", "venv", ".next",
+              "coverage", "__pycache__", ".pytest_cache", "playwright-report", "test-results"}
+_MAX_SPEC_READS = 500  # cap header reads on huge suites; beyond this, classify by directory only
+
+# Import/usage cues in a spec's header that name its test runner (all lowercased).
+_FUNCTIONAL_CUES = ("@playwright/test", "cypress", "cy.visit", "cy.get", "@wdio", "webdriverio",
+                    "selenium-webdriver", "puppeteer")
+_UNIT_CUES = ("vitest", "@jest/globals", "@testing-library", "from 'jest'", "require('jest",
+              "mocha", "node:test", "'ava'", "\"ava\"")
+
+
+def _classify_spec(head: str, posix_dir: str) -> str:
+    """Classify a *.spec/*.test file as ordel | functional | unit | unknown from its header
+    imports (deterministic). Unit and functional share the extension, so imports — not the name —
+    decide. Ordel builds functional/e2e; unit is out of scope."""
+    if "by ordel" in head:   # "Generated by Ordel" (scenarios/invariant/perf) or "Recorded by Ordel"
+        return "ordel"
+    if any(c in head for c in _FUNCTIONAL_CUES):
+        return "functional"
+    if any(c in head for c in _UNIT_CUES):
+        return "unit"
+    # weak directory fallback when the header didn't name a runner (or was beyond the read cap)
+    if any(seg in posix_dir for seg in ("/e2e", "/cypress", "/playwright", "/integration")):
+        return "functional"
+    if any(seg in posix_dir for seg in ("/__tests__", "/unit")) or "/src/" in posix_dir:
+        return "unit"
+    return "unknown"
+
+
+def assess_context(store: OrdelStore) -> dict[str, Any]:
+    """Scan the project + store and return the pure classifier's orientation."""
+    root = store.root
+    try:
+        pages = len(store.pages()) if store.exists else 0
+        flows = len(store.flows()) if store.exists else 0
+        runs = len(store.runs()) if store.exists else 0
+    except StoreError:
+        pages = flows = runs = 0
+
+    functional = ordel = unit = unknown = page_objects = source_files = 0
+    reads = 0
+    has_ci = False
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in _SKIP_DIRS]
+        posix_dir = Path(dirpath).as_posix()
+        if "/.github/workflows" in posix_dir:
+            has_ci = True
+        for fn in filenames:
+            low = fn.lower()
+            if low.startswith("playwright.config."):
+                has_ci = True
+            if low.endswith(_SPEC_SUFFIXES):
+                head = ""
+                if reads < _MAX_SPEC_READS:
+                    reads += 1
+                    try:
+                        head = (Path(dirpath) / fn).read_text(errors="ignore")[:600].lower()
+                    except OSError:
+                        head = ""
+                kind = _classify_spec(head, posix_dir)
+                if kind == "ordel":
+                    functional += 1
+                    ordel += 1
+                elif kind == "functional":
+                    functional += 1
+                elif kind == "unit":
+                    unit += 1
+                else:
+                    unknown += 1
+                continue  # a spec is not also a POM or generic source
+            if low.endswith(_POM_HINTS):
+                page_objects += 1
+            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))

{ordel_cli-0.2.1 → ordel_cli-0.2.2}/ordel_cli/coverage.py

@@ -34,7 +34,7 @@ def _read_specs(root: Path) -> str:
     return "\n".join(parts).lower()
 
 
-def coverage_report(store: OrdelStore) -> dict[str, Any]:
+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:
@@ -46,6 +46,10 @@ def coverage_report(store: OrdelStore) -> dict[str, Any]:
         all_els = store.load_all_page_elements()
     except StoreError as e:
         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. "
+                        "Map the app first (explore_app / capture_state), or pass force=true."}
     specs = _read_specs(store.root)
     host = ""
     for pg in store.pages_summary():

ordel_cli-0.2.2/ordel_cli/ingest.py

@@ -0,0 +1,95 @@
+"""ingest adapter — the REUSE step's I/O.
+
+Find existing FUNCTIONAL specs (Playwright/Cypress — not unit, not Ordel-generated), parse each
+into Ordel flow docs, and save them so the agent can generate_scenarios / generate_invariant on
+top instead of re-recording. Read-only on the app; the only writes are .ordel/flows/*.json.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from ordel_tools.ingest import flow_name_for, parse_playwright_spec
+
+from ordel_cli.context import _SKIP_DIRS, _SPEC_SUFFIXES, _classify_spec
+from ordel_cli.store import OrdelStore
+
+_MAX_FLOWS = 200  # bound the store: a huge suite ingests up to this many flows, then stops + says so
+
+
+def ingest(store: OrdelStore, path: str = "") -> dict[str, Any]:
+    """Ingest functional specs under ``path`` (a file or dir, relative to the project) or the whole
+    project when omitted. Returns a summary + the created flow names."""
+    if not store.exists:
+        return {"status": "not_initialized", "note": "run `ordel init` first"}
+    root = store.root
+
+    targets: list[Path] = []
+    if path:
+        p = Path(path) if os.path.isabs(path) else (root / path)
+        if p.is_file():
+            targets = [p]
+        elif p.is_dir():
+            targets = [f for f in p.rglob("*") if f.name.lower().endswith(_SPEC_SUFFIXES)]
+        else:
+            return {"status": "not_found", "note": f"no such file/dir: {path}"}
+    else:
+        for dirpath, dirnames, filenames in os.walk(root):
+            dirnames[:] = [d for d in dirnames if d not in _SKIP_DIRS]
+            targets += [Path(dirpath) / fn for fn in filenames
+                        if fn.lower().endswith(_SPEC_SUFFIXES)]
+
+    ingested = flows_created = unparsed = skipped_unit = skipped_ordel = 0
+    created: list[str] = []
+    capped = False
+    for f in sorted(targets):
+        try:
+            src = f.read_text(errors="ignore")
+        except OSError:
+            continue
+        kind = _classify_spec(src[:600].lower(), f.parent.as_posix())
+        if kind == "ordel":
+            skipped_ordel += 1
+            continue
+        if kind == "unit":
+            skipped_unit += 1
+            continue
+        parsed = parse_playwright_spec(src)
+        unparsed += parsed["unparsed_actions"]
+        if not parsed["tests"]:
+            continue
+        ingested += 1
+        for i, t in enumerate(parsed["tests"]):
+            if flows_created >= _MAX_FLOWS:
+                capped = True
+                break
+            name = flow_name_for(f.name, t["title"], i)
+            uniq, n = name, 1
+            while uniq in created:
+                n += 1
+                uniq = f"{name[:60]}-{n}"
+            start = next((s["url"] for s in t["steps"] if s.get("op") == "goto"), "")
+            store.save_flow(uniq, {"name": uniq, "source": "ingested", "spec": f.name,
+                                   "start": start, "final_url": "", "steps": t["steps"]})
+            created.append(uniq)
+            flows_created += 1
+        if capped:
+            break
+
+    lines = [f"Ingested {ingested} functional spec(s) → {flows_created} flow(s)"]
+    if skipped_unit:
+        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")
+    if capped:
+        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")
+    return {"status": "ok", "specs_ingested": ingested, "flows_created": flows_created,
+            "flows": created, "skipped_unit": skipped_unit, "skipped_ordel": skipped_ordel,
+            "unparsed_actions": unparsed, "ascii": "\n".join(lines)}

{ordel_cli-0.2.1 → ordel_cli-0.2.2}/ordel_cli/mcp_server.py

@@ -55,7 +55,7 @@ FREE_TIER_TOOLS: frozenset[str] = frozenset({
     # map / record / heal
     "explore_app", "record_flow", "heal_selector", "heal_element",
     # local context + runs
-    "get_app_context", "list_runs", "run_test",
+    "get_app_context", "assess_context", "ingest", "list_runs", "run_test",
     # deterministic codegen (no Ordel LLM)
     "generate_scenarios", "generate_invariant", "generate_perf_check", "generate_pom",
     # QA-mind planning (pure, map+specs derived)
@@ -110,6 +110,30 @@ def build_server(root: str | Path = ".") -> FastMCP:
         except StoreError as e:
             return {"status": "store_error", "note": str(e)}
 
+    @mcp.tool()
+    def assess_context() -> dict[str, Any]:
+        """ORIENT — assess this project's testing context BEFORE planning or generating. Reads the
+        .ordel map state + a read-only STRUCTURAL scan of the project (file presence/counts only —
+        no code comprehension, zero egress) and returns: run_mode (codebase-present vs
+        artifacts-only), lifecycle (implementation vs maintenance), existing assets, and the
+        REQUIRED NEXT PHASE. Ordel builds FUNCTIONAL / e2e coverage — unit tests (Vitest/Jest/
+        testing-library) are detected and reported OUT OF SCOPE, never counted as the suite. Call
+        this first (with get_app_context) so you don't jump to generation prematurely. No LLM."""
+        from ordel_cli.context import assess_context as _assess_context
+        return _sign(_assess_context(store))
+
+    @mcp.tool()
+    def ingest(path: str = "") -> dict[str, Any]:
+        """REUSE — import an existing FUNCTIONAL suite instead of re-recording it. Parses the
+        common Playwright idioms (goto / getByTestId|getByRole|getByLabel|getByText|locator +
+        fill|click|check|selectOption / toHaveURL) out of each spec into an Ordel flow (one per
+        `test(...)`), so you can generate_scenarios (add negative/boundary) or generate_invariant
+        on top. `path` narrows to a file or directory (relative to the project); omit to scan the
+        whole project. SKIPS unit tests (Vitest/Jest — out of scope) and Ordel's own specs; counts
+        any idioms it couldn't parse (re-record those). Writes .ordel/flows/*.json only. No LLM."""
+        from ordel_cli.ingest import ingest as _ingest
+        return _sign(_ingest(store, path))
+
     @mcp.tool()
     def heal_selector(page_id: str, broken: dict[str, Any], candidates: list[Any]) -> dict[str, Any]:
         """Deterministically heal a broken selector. `broken` is the recorded
@@ -287,24 +311,27 @@ def build_server(root: str | Path = ".") -> FastMCP:
 
     @mcp.tool()
     def generate_pom(page_id: str, write: bool = True) -> dict[str, Any]:
-        """Generate a typed Playwright Page Object Model from the local map for `page_id`.
-        Deterministic codegen: one stable locator per interactive element, picking the most
-        robust selector available (testid > role+name > static id > text). Writes
-        pages/<Class>.ts. Requires the page to have been explored first. Returns
-        {status, class_name, locators, path, source}. No LLM."""
+        """Generate — or UPDATE IN PLACE — a typed Playwright Page Object Model from the local map
+        for `page_id`. Deterministic codegen: one stable locator per interactive element, most
+        robust selector first (testid > role+name > static id > text). Writes pages/<Class>.ts. On
+        re-run it refreshes ONLY Ordel's managed locator block (`// ordel:locators` … `// ordel:end`)
+        and KEEPS your own methods/imports; a hand-written POM with no markers is left untouched
+        (status `exists_unmanaged`). Requires the page explored first. Returns {status (generated|
+        updated|exists_unmanaged), class_name, locators, path, source}. No LLM."""
         from ordel_cli.pom import generate_pom as _gp
         return _sign(_gp(store, page_id, write=write))
 
     @mcp.tool()
-    def coverage_report() -> dict[str, Any]:
+    def coverage_report(force: bool = False) -> dict[str, Any]:
         """What's TESTED vs NOT — cross-reference the captured map against the project's
         Playwright specs (tests/**/*.spec.ts), per page: which mapped elements a spec
         asserts and which are gaps. Deterministic (no LLM). Returns {status, summary,
         ascii, markdown, mermaid} — render `ascii` inline in chat (✓ full / ⚠ partial /
-        ✗ untested); `markdown` is a matrix, `mermaid` a colored app-map. This is the
-        QA-mind answering 'where are we exposed?' before shipping."""
+        ✗ untested); `markdown` is a matrix, `mermaid` a colored app-map. Returns `not_ready`
+        on an empty map (map the app first) unless force=true. The QA-mind answering
+        'where are we exposed?' before shipping."""
         from ordel_cli.coverage import coverage_report as _cov
-        return _sign(_cov(store))
+        return _sign(_cov(store, force))
 
     @mcp.tool()
     def generate_scenarios(flow_name: str, write: bool = True) -> dict[str, Any]:
@@ -351,31 +378,37 @@ def build_server(root: str | Path = ".") -> FastMCP:
         return _sign(_gp(store, flow_name, budget_ms, samples=samples, name=name, write=write))
 
     @mcp.tool()
-    def risk_rank() -> dict[str, Any]:
+    def risk_rank(force: bool = False) -> dict[str, Any]:
         """Rank mapped pages by RISK so effort goes where a bug would hurt most.
-        Deterministic (no LLM): score = sensitive-inputs·5 + untested·4 + forms·2 +
+        Deterministic (no LLM): score = sensitive-inputs·5 + untested·4 + inputs·2 +
         past-failures·3 + interactive-surface. Returns {status, rows, ascii} — render
-        `ascii` (HIGH/MED/LOW bands). The QA-mind answering 'what should I test first?'."""
+        `ascii` (HIGH/MED/LOW bands). Returns `not_ready` on an empty map (map the app first)
+        unless force=true. The QA-mind answering 'what should I test first?'."""
         from ordel_cli.qa_plan import risk_rank as _rr
-        return _sign(_rr(store))
+        return _sign(_rr(store, force))
 
     @mcp.tool()
-    def plan_tests() -> dict[str, Any]:
-        """A prioritized, page-by-page TEST PLAN from the map + coverage (highest risk
-        first): which kind of test each page needs (record+generate_scenarios for untested
-        forms, extend coverage, smoke, spot-check), sensitive pages flagged PRIORITY.
-        Deterministic. Returns {status, rows, ascii}. The judgment the coding agent lacks."""
+    def plan_tests(force: bool = False) -> dict[str, Any]:
+        """A prioritized, page-by-page TEST PLAN from the map + coverage (highest risk first).
+        Classifies each page into a SURFACE (auth / form / table / search / cart / detail) and
+        returns that surface's CHECKLIST — the concrete things to test, each item naming the Ordel
+        tool that performs it (generate_scenarios / generate_invariant / …); sensitive pages
+        flagged PRIORITY. WORK THE CHECKLIST rather than improvising coverage. Returns `not_ready`
+        on an empty map (map the app first) unless force=true. Deterministic (no LLM). Returns
+        {status, rows[{page, score, surface, checklist[]}], ascii}."""
         from ordel_cli.qa_plan import plan_tests as _pt
-        return _sign(_pt(store))
+        return _sign(_pt(store, force))
 
     @mcp.tool()
-    def regression_set(changed_pages: list[str] | None = None) -> dict[str, Any]:
+    def regression_set(changed_pages: list[str] | None = None,
+                       force: bool = False) -> dict[str, Any]:
         """The exact specs to RE-RUN after a change (impact selection): a spec is selected
         if it asserts any element on a changed page. Pass `changed_pages` (page_ids) or omit
-        for the full set. Deterministic. Returns {status, specs, changed, ascii}. Turns
-        'something changed' into 'run precisely these tests', not the whole suite."""
+        for the full set. Returns `not_ready` on an empty map unless force=true. Deterministic.
+        Returns {status, specs, changed, ascii}. Turns 'something changed' into 'run precisely
+        these tests', not the whole suite."""
         from ordel_cli.qa_plan import regression_set as _rs
-        return _sign(_rs(store, changed_pages))
+        return _sign(_rs(store, changed_pages, force))
 
     # ── Option B: persistent agent-driven browser session ──
     # The AGENT is the crawler; these give it a live browser + deterministic capture,

ordel_cli-0.2.2/ordel_cli/pom.py

@@ -0,0 +1,56 @@
+"""Generate a Playwright Page Object Model from the local map — Tier-1 `generate_pom`.
+
+Thin ADAPTER: the deterministic codegen (map elements -> typed POM class with one stable
+locator per interactive element) is the pure `ordel_tools.pom.build_pom`. This module only
+does I/O — load the page's elements from the local ``.ordel/`` store, hand them to the pure
+builder, and (optionally) write the emitted source to ``pages/<class>.ts``. No LLM.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# Re-export the pure selector helper so callers/tests that import it from here keep working.
+from ordel_tools.pom import _selector, build_pom, merge_pom
+
+from ordel_cli.store import OrdelStore, StoreError
+
+__all__ = ["_selector", "build_pom", "merge_pom", "generate_pom"]
+
+
+def generate_pom(store: OrdelStore, page_id: str, write: bool = True) -> dict[str, Any]:
+    """Generate — or UPDATE IN PLACE — a POM class for ``page_id`` from the map. On write, if a
+    page object already exists it refreshes ONLY Ordel's managed locator block and keeps the
+    user's own methods/imports; a hand-written POM with no markers is never overwritten. Returns
+    {status, class_name, locators, path, source}; status is `generated` (new file), `updated`
+    (managed block refreshed), or `exists_unmanaged` (left untouched). Never raises."""
+    try:
+        elements = store.load_page_elements(page_id)  # T2P-2: corrupt graph -> clean status
+    except StoreError as e:
+        return {"status": "store_error", "note": str(e)}
+    result = build_pom(page_id, elements)
+    if result.get("status") != "generated":
+        return result
+    if write:
+        p = store.root / "pages" / f"{result['class_name']}.ts"
+        p.parent.mkdir(parents=True, exist_ok=True)
+        if p.exists():
+            merged, mode = merge_pom(p.read_text(errors="ignore"), result["source"])
+            if mode == "unmanaged":
+                # a hand-written / foreign POM — do NOT clobber the user's file
+                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` … "
+                    "`// ordel:end` markers where locators should refresh, or delete the file to "
+                    "regenerate from scratch.")
+                result["path"] = str(p.relative_to(store.root))
+                return result
+            p.write_text(merged)
+            result["status"] = "updated"  # refreshed the managed block, kept the rest
+        else:
+            p.write_text(result["source"])
+        result["path"] = str(p.relative_to(store.root))
+    else:
+        result["path"] = ""
+    return result

{ordel_cli-0.2.1 → ordel_cli-0.2.2}/ordel_cli/qa_plan.py

@@ -19,6 +19,23 @@ from ordel_cli.store import OrdelStore, StoreError
 __all__ = ["risk_rank", "plan_tests", "regression_set"]
 
 
+def _require_map(store: OrdelStore, force: bool) -> dict[str, Any] | None:
+    """Readiness gate: these tools PLAN from the captured map, so an empty map yields a useless
+    empty result. Return a `not_ready` dict naming the missing prerequisite unless `force`. Called
+    after the store-exists check, so store.pages() is safe."""
+    if force:
+        return 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 "
+                            "(explore_app, or browser_open + goto/click + capture_state), then "
+                            "retry. Pass force=true to run against the empty map anyway."}
+    except StoreError:
+        return None
+    return None
+
+
 def _failed_pages(store: OrdelStore) -> dict[str, int]:
     """page_id -> count of failed runs touching it (best-effort from run payloads)."""
     fails: dict[str, int] = {}
@@ -42,10 +59,12 @@ def _scored_rows(store: OrdelStore) -> list[dict[str, Any]]:
     return score_pages(store.load_all_page_elements(), specs, fails)
 
 
-def risk_rank(store: OrdelStore) -> 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"}
+    if gate := _require_map(store, force):
+        return gate
     try:
         rows = _scored_rows(store)  # T2P-2: corrupt graph -> clean status, not a traceback.
     except StoreError as e:
@@ -53,10 +72,12 @@ def risk_rank(store: OrdelStore) -> dict[str, Any]:
     return build_risk_rank(rows)
 
 
-def plan_tests(store: OrdelStore) -> 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"}
+    if gate := _require_map(store, force):
+        return gate
     try:
         rows = _scored_rows(store)  # T2P-2: corrupt graph -> clean status, not a traceback.
     except StoreError as e:
@@ -77,12 +98,15 @@ def _read_specs_map(root: Path) -> dict[str, str]:
     return out
 
 
-def regression_set(store: OrdelStore, changed_pages: list[str] | None = None) -> dict[str, Any]:
+def regression_set(store: OrdelStore, changed_pages: list[str] | None = None,
+                   force: bool = False) -> dict[str, Any]:
     """Given changed page_ids, the exact specs to re-run (a spec is selected if it asserts
     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"}
+    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"}

{ordel_cli-0.2.1 → ordel_cli-0.2.2}/ordel_cli/record.cjs

@@ -109,8 +109,13 @@ async function hiddenState(page) {
         case 'selectFirst': {
           // pick the first real (non-empty) option — for AJAX-populated selects whose
           // values aren't known ahead of time
+          // T2-REC-2: `option:not([value=""])` = the first non-placeholder option.
+          // The old selector also had a stray `:not([value])` (= has NO value
+          // attribute) — the two clauses CONTRADICT, so on any standard <select>
+          // (every option carries a value=) it matched ZERO options and
+          // getAttribute hung the full 30s before aborting the whole recording.
           const optSel = s.optionSelector
-            || `[data-testid="${s.testid}"] option:not([value=""]):not([value])`;
+            || `[data-testid="${s.testid}"] option:not([value=""])`;
           const v = await page.locator(optSel).first().getAttribute('value');
           await page.selectOption(s.selector || `[data-testid="${s.testid}"]`, v);
           break;

{ordel_cli-0.2.1 → ordel_cli-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ordel-cli"
-version = "0.2.1"
+version = "0.2.2"
 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"
@@ -22,8 +22,8 @@ classifiers = [
     "Topic :: Software Development :: Testing",
 ]
 dependencies = [
-    "ordel-engine==0.2.1",  # pinned: cli + engine version-locked (see version-sync check)
-    "ordel-tools==0.2.1",   # pinned: the shared pure-logic QA tools (data in, spec out)
+    "ordel-engine==0.2.2",  # pinned: cli + engine version-locked (see version-sync check)
+    "ordel-tools==0.2.2",   # pinned: the shared pure-logic QA tools (data in, spec out)
     "mcp>=1.0",
     "typer>=0.12",
 ]

ordel_cli-0.2.1/ordel_cli/pom.py

@@ -1,38 +0,0 @@
-"""Generate a Playwright Page Object Model from the local map — Tier-1 `generate_pom`.
-
-Thin ADAPTER: the deterministic codegen (map elements -> typed POM class with one stable
-locator per interactive element) is the pure `ordel_tools.pom.build_pom`. This module only
-does I/O — load the page's elements from the local ``.ordel/`` store, hand them to the pure
-builder, and (optionally) write the emitted source to ``pages/<class>.ts``. No LLM.
-"""
-
-from __future__ import annotations
-
-from typing import Any
-
-# Re-export the pure selector helper so callers/tests that import it from here keep working.
-from ordel_tools.pom import _selector, build_pom
-
-from ordel_cli.store import OrdelStore, StoreError
-
-__all__ = ["_selector", "build_pom", "generate_pom"]
-
-
-def generate_pom(store: OrdelStore, page_id: str, write: bool = True) -> dict[str, Any]:
-    """Generate a POM class for ``page_id`` from the map. Returns {status, class_name,
-    locators, path, source}. Never raises for expected cases (unknown page)."""
-    try:
-        elements = store.load_page_elements(page_id)  # T2P-2: corrupt graph -> clean status
-    except StoreError as e:
-        return {"status": "store_error", "note": str(e)}
-    result = build_pom(page_id, elements)
-    if result.get("status") != "generated":
-        return result
-    path = ""
-    if write:
-        p = store.root / "pages" / f"{result['class_name']}.ts"
-        p.parent.mkdir(parents=True, exist_ok=True)
-        p.write_text(result["source"])
-        path = str(p.relative_to(store.root))
-    result["path"] = path
-    return result