Metadata-Version: 2.4
Name: ordel-cli
Version: 0.2.0
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>=1.0
Requires-Dist: ordel-engine==0.2.0
Requires-Dist: ordel-tools==0.2.0
Requires-Dist: typer>=0.12
Provides-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; packaged `npx ordel` distribution is the remaining in-progress piece —
> see `docs/plans/2026-07-17-free-cli-implementation-plan.md`.

## 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 report        # copy-pasteable Markdown report (Slack/Teams/Jira)
ordel mcp-install    # print the MCP config to add to Claude Code / Cursor / Copilot
```

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).
- `explore` / `record_flow` — drive the real browser to map the app + record a flow.
- `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 real pass/fail.
- QA-mind planning: `coverage_report` / `risk_rank` / `plan_tests` / `regression_set`.

## In progress (honest — no fake success)

- Single `npx ordel` distribution — a compiled Python engine binary wrapped in one npm
  package (built + smoke-tested in CI; `npm/` here is the wrapper).
- `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. See [PRIVACY.md](PRIVACY.md).
