@witness-engine/cli
v0.9.1
Published
Local-first application truth, behavior memory, safe persona simulation and release governance engine.
Maintainers
Readme
WITNESS Engine — v0.9.0
Application Truth Engine — give it an application URL and, optionally, the source repository. WITNESS builds a behavioral map, explores safe user paths, compares visible behavior with machine behavior, and preserves evidence that can be replayed and verified.
What this is trying to become
The goal is simple enough to explain to a non-engineer:
“Give WITNESS your website or app. Let it experience the product like real users, find what is wrong or inconsistent, show you exactly what happened, and remember what changed next time.”
The system is intentionally built around proof rather than AI theater. A result is separated into:
- Observed — something directly recorded by the browser/runtime.
- Confirmed — a problem reproduced during the run with evidence.
- Review required — suspicious behavior that needs policy or human judgment.
- Blocked — an action WITNESS intentionally refused for safety or missing authorization.
AI can become a planning layer later, but the evidence layer remains deterministic.
v0.4: from scanning pages to testing user journeys
1. Auto persona planning
Use --personas auto and WITNESS reads the repository's role signals to choose relevant profiles. Built-ins include Guest, Customer, Seller, Admin, Owner, Unauthorized, Mobile, RTL and Desktop.
Authentication is never fabricated. If a role has no real Playwright session profile, WITNESS records that fact and still tests what can legitimately be observed.
2. Behavior truth model
Each explored action now produces a compact contract observation connecting:
persona → page → action → before state → network → after state → transition
The scanner records route changes, visible state changes, no-visible-change outcomes and degraded transitions caused by failed requests.
3. Contradiction + invariant engine
WITNESS does more than count HTTP errors. It looks for contradictions such as:
- visible success after a failed operation;
- error UI after otherwise successful responses;
- a safe action that produces no observable browser/network change;
- a navigation action that lands on a not-found state.
These are designed to be evidence-backed observations, not guesses produced by a model.
4. Replay artifacts
When a browser finding is confirmed, WITNESS can write a standalone Playwright replay script next to the screenshot and structured evidence. The intent is that a developer can reproduce the same issue instead of reading a vague bug report.
5. Source + runtime together
Repository inspection now records more than file names: candidate routes, backend/network surfaces, role vocabulary, state vocabulary and UI action signals. Runtime findings can therefore be read alongside the source map.
6. Behavior memory
Baseline comparison remains part of the core. A second run can show what changed from the previous proof:
old behavior → new behavior → new findings → resolved findings
This is the beginning of making WITNESS useful in CI, not just useful once.
7. Stateful journey + re-entry testing
With --explore, WITNESS now keeps the same browser session while it follows a bounded chain of safe interactions. Safe navigation actions are also probed for re-entry: WITNESS returns to the original page and tries the same navigation again. This targets a class of bugs that one-shot crawlers often miss, including stale UI state, broken back-navigation, missing targets and dashboard re-entry failures.
8. Coverage and CI output
Every scan now emits coverage.json with repository-route coverage and per-persona execution counts, plus results.sarif for CI systems that understand SARIF. policy.json records the safety contract used for the run.
Modes
Full Scan — broad discovery and safe exploration.
Focus Scan — concentrate on a named feature, route or area.
Change Scan — start from the repository diff and use it to guide investigation.
CLI
Published-package path
After the public npm package is published, the CLI can be invoked without checking out the repository:
npx --yes @witness-engine/cli doctor
npx --yes @witness-engine/cli setup
npx --yes @witness-engine/cli --helpThe repository remains the source-of-truth development path.
Fastest setup
From a checked-out WITNESS repository:
npm installnpm install automatically attempts to provision the Playwright Chromium browser. It is safe to skip the download with WITNESS_SKIP_BROWSER_SETUP=1. If Playwright Chromium is unavailable but a system Chromium exists, WITNESS uses its native CDP fallback.
Check the runtime:
npx witness doctorOr explicitly repair/provision the browser layer:
npx witness setupFor a fresh checkout where you want install + browser setup in one command:
bash ./scripts/install.shThen a scan is a single command:
npx witness scan \
--url https://your-staging-app.example \
--repo /path/to/repo \
--mode full \
--personas auto \
--explore \
--output ./witness-runVerify the resulting evidence bundle with:
npx witness verify --bundle ./witness-runManual interactive authentication still requires Playwright because the user must complete the sign-in flow in a visible browser.
Authenticated sessions can be supplied without printing their contents:
node ./bin/witness.js scan \
--url https://your-staging-app.example \
--profiles ./profiles.example.json \
--personas customer,seller,admin,owner \
--exploreNo default telemetry or source upload exists in the core.
v0.8: Business Truth Evidence
WITNESS can now join a safe browser observation to a configured, read-only, same-origin API/state observation. A business-truth check declares the browser claim, the API endpoint, and the state assertions that must agree.
Example contract:
browser success claim → GET /api/order/42 → payment_status=paid + status=paid
The engine records a tamper-evident observation. If the browser claims success while the read-only API/state assertions disagree, WITNESS emits BUSINESS-TRUTH-001 as a confirmed contradiction. API reads are limited to GET/HEAD, same-origin, credential-free URLs, and use the current browser session; destructive methods are rejected.
Run with:
witness scan --url <authorized-target> --grant grant.json --personas customer --explore --truth ./examples/business-truth.example.jsonThe v0.8 core does not treat the API read as permission: the surrounding WITNESS authorization grant is still mandatory.
Safety contract
WITNESS is designed for local or staging use first. Destructive actions remain blocked by default: payment, purchase, delete, refund, publish, approve/reject, account removal, transfer, charge and similar actions are not automatically executed.
The engine never invents authentication. Real session state may be supplied through a Playwright storageState file, but its contents are not written into evidence.
Current architecture
Application URL ────────┐
├─ Discovery ──> Behavior Map
Repository ─────────────┘ │
▼
Persona Exploration Plan
│
▼
Real Browser Run
│
┌──────────────────┼──────────────────┐
▼ ▼ ▼
DOM Network Runtime
│ │ │
└──────────────────┼──────────────────┘
▼
Truth / Invariant Layer
│
┌─────────────────┴─────────────────┐
▼ ▼
Confirmed Finding Evidence Timeline
│ │
└───────────────┬───────────────────┘
▼
Replay + ReportThe long-term graph is:
source → route → persona → state → action → request → result → side effect → evidence → replay
Product philosophy
The product should be useful before AI, safer than an uncontrolled browser agent, and increasingly valuable as its behavior memory grows. The core asset is the application behavior/evidence graph, not a specific model provider.
The commercial direction is intentionally secondary to proof of user value. A future paid layer can add team history, CI orchestration, parallel browsers, enterprise policy, private runners, audit exports and optional hosted intelligence while the local engine stays usable.
v0.7 Application Sentinel + Truth Contracts
A URL is not permission. Deep scans now require an explicit WITNESS authorization grant.
v0.6: from behavior logging to application memory + governance
WITNESS now emits a durable State Model that records observed states and transitions by persona. A compatible baseline can be compared to detect added/removed states, new divergences, and resolved divergences.
A Change Impact layer translates the Git diff into affected product surfaces (auth, commerce, inventory, role surfaces, localization, notifications, etc.) and recommended personas/routes to investigate.
A Persona Simulation Plan generates safe, deterministic investigation objectives. This is deliberately provider-neutral: an AI model may expand the plan later, but model output never bypasses authorization or safety policy.
An Application Sentinel combines behavior memory, change impact, persona simulation, evidence and release policy into sentinel.json. The release gate fails on confirmed high-severity issues and confirmed truth/authorization/journey contradictions, blocks on safety/authorization conditions, and can optionally enforce stricter medium-severity or coverage thresholds.
New artifacts include:
state-model.jsonstate-diffdata insideresult.json/behavior.jsonpersona-simulation.jsonchange-impact.jsonsentinel.json
The key principle is evidence first, intelligence second.
v0.7: Truth Contracts
A team can generate contract candidates from its repository and review them into a witness-contracts.v1 file. Supported types include role-route protection, document locale consistency, no-success-after-network-error, and visible-text assertions. Contracts run against observed evidence and cannot bypass safety or authorization.
witness contracts init --repo . --output ./witness-contracts.json
witness scan --url https://staging.example --grant ./grant.json --repo . --contracts ./witness-contracts.json --exploreBusiness-specific database invariants are not guessed. A later adapter layer can prove approved invariants through read-only evidence sources.
Explicit CI/release gate
Use an explicit gate when you want WITNESS to participate in release governance:
witness gate --result ./witness-run/result.json
witness gate --result ./witness-run/result.json --fail-on-medium --min-route-coverage 0.80Or run a scan and use the computed Sentinel gate as the exit policy:
witness scan --url https://staging.example --grant ./grant.json --repo . --explore --gateHuman flow
- Generate a one-time challenge with
witness target challenge --url <URL>. - Publish the challenge as an HTTPS file or DNS TXT record.
- Verify it and save a grant with
witness target verify ... --output grant.json. - For authenticated personas, run
witness auth --url <URL> --persona customer --grant grant.json --output profiles/customer.storage.jsonand log in manually in the opened browser. - Run the scan with
witness scan --url <URL> --grant grant.json --profiles profiles.json --explore.
For local/private development, use witness target authorize-local --url <URL> --repo <git-repository>.
Control Plane UI
Run npm start and open the printed local URL. The dashboard can generate challenges and launch authorized scans without requiring a cloud account.
Safety boundary
- No deep scan or browser exploration on an arbitrary URL without authorization.
witness target probeis the only pre-authorization network action and is read-only.- Public discovery is explicitly separated and read-only.
- Private network addresses are blocked unless local authorization/explicit flags are used.
- Browser passwords are never requested or uploaded.
- Destructive/commercial actions remain denied by default.
Public release
The public-release contract is documented in docs/public-release.md. A release must pass unit tests, package-safety validation, runtime doctor, and the repository CI workflow before publication.
