npx botscent check

npx botscent check tests a Botscent install from outside. It requests the page, opens the page in a local Chrome, and scans the project on disk. Each check prints one line with an outcome. For the procedure that uses this command, see Verify your install.

Synopsis

npx botscent check <url> [--origin <url>] [--project <dir>] [--chrome <path>] [--no-browser] [--json] [--report]

<url> is the page to test. It must be an http or https URL, and only one URL is allowed.

Options

npx botscent --version prints the version and exits with code 0.

What it does

The command does three things, in this order:

1. It requests the page twice as a document navigation. The first request uses the check's own user agent. The second request follows at once with an empty user agent, so a cache that stored the first response serves it to the second.
2. It opens the page in a headless Chrome over the DevTools protocol. Two seconds after the load event, it reads the page half's diagnostics and verdict. It also reads the botscent entries that the document received, the console errors and the Content Security Policy violations.
3. It reads the project's declared frameworks and every botscent import. A configuration that names an entry as a string, such as Nuxt's modules: ['botscent/nuxt'], counts as an import.

With --origin, the command also requests the origin with its own user agent. It names a hop that removes Server-Timing only when it saw both sides.

The user agent

The first request sends this User-Agent:

botscent-check/<version> (+https://botscent.nibnalin.me/check)

botscent-check is a registered token. The server half therefore gives the request the reason ua.declared-agent-token and the agent name botscent-check. A working server half with its transport on sends back an entry that names botscent-check.

Chrome under the DevTools protocol sets the webdriver flag, as any automation does. The page half therefore reports the browser as an agent with browser.webdriver-flag.

Checks

The checks run in this order. The ids are stable.

csp

The csp check fails only when a violation names Botscent's own script. The line reports other blocked resources as context, by kind and directive, without their URL and without a fix.

adapters

The adapters check compares a Next.js proxy or Vercel middleware that uses botscent/next or botscent/vercel with its version at git HEAD:

• If the file had code of its own at HEAD and now has only Botscent's lines, the proxy was replaced. The check fails.
• A withBotscent(existing) call is a wrap, also under an imported alias. The check passes.
• Any other edit gives unknown, because a scan of the text cannot tell whether the old code still runs.

Outcomes

Each line gives the outcome, the check id and the observation. For anything but pass, the line also gives the likely cause and the fix. The text of a line is for people and can change in any release.

Note: At an origin with the transport off, server-half is unknown. The verdict is still in the application's code.

JSON output

With --json, the command prints one object:

{
  "check": "<version>",
  "url": "<url>",
  "checks": [{ "id": "", "outcome": "", "observed": "", "detail": "", "cause": "", "fix": "" }],
  "exit": 0
}

The field names are stable. The text of observed, detail, cause and fix can change in any release.

The report block

--report adds a block to paste into an issue. The block has only what Botscent owns or bounds:

• The versions, the stack and the adapters found.
• Botscent's own entry at each hop. Other Server-Timing entries are counted, not copied.
• The diagnostics and the observed text of each check.

The block never has detail, a query string, a cookie or an address. Its text can change in any release.

Exit codes

An error that stops the command also gives code 64.

Stability

These parts are stable across minor versions: the flags, the --json field names, the check ids, the outcome values and the exit codes. A change to one of them is a major version. See Versions and stability.