npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@witness-engine/cli

v0.9.1

Published

Local-first application truth, behavior memory, safe persona simulation and release governance engine.

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 --help

The repository remains the source-of-truth development path.

Fastest setup

From a checked-out WITNESS repository:

npm install

npm 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 doctor

Or explicitly repair/provision the browser layer:

npx witness setup

For a fresh checkout where you want install + browser setup in one command:

bash ./scripts/install.sh

Then 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-run

Verify the resulting evidence bundle with:

npx witness verify --bundle ./witness-run

Manual 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 \
  --explore

No 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.json

The 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 + Report

The 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.json
  • state-diff data inside result.json / behavior.json
  • persona-simulation.json
  • change-impact.json
  • sentinel.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 --explore

Business-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.80

Or run a scan and use the computed Sentinel gate as the exit policy:

witness scan --url https://staging.example --grant ./grant.json --repo . --explore --gate

Human flow

  1. Generate a one-time challenge with witness target challenge --url <URL>.
  2. Publish the challenge as an HTTPS file or DNS TXT record.
  3. Verify it and save a grant with witness target verify ... --output grant.json.
  4. For authenticated personas, run witness auth --url <URL> --persona customer --grant grant.json --output profiles/customer.storage.json and log in manually in the opened browser.
  5. 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 probe is 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.