Skip to content

@docsxai/engine

LLM-agnostic engine: flow-file parser + runtime, calibration helpers, target-site auth strategies, and the full docsxai CLI.

The engine never calls a model API. Calibration-time inference is supplied by the host agent (Claude Code, Codex, anything that speaks MCP) through the plugin's skill surface; execution is deterministic and replays a doc pack through headless Playwright.

  • Flow-file: declarative YAML at <workspace>/flows/<name>.flow.yaml, with prerequisites + locators + steps[] (action, target, wait_for, success, annotation / annotations, per-step redactions, timeout_ms). Actions: navigate, click, fill, upload, press, hover, select, check, uncheck, wait, hide, show. Hand-editable; schema-validated. extends: composition for shared preambles (with environment merged per-key, child wins; redactions concatenated).
  • Execution environment: optional environment block (EnvironmentSpec) with frozen clock (Playwright clock API), locale, timezone, viewport (VIEWPORT_PRESETS: desktop / tablet / mobile, or explicit size), color_scheme, reduced_motion. Applied at context creation by launchPlaywrightSession({ environment }); on CDP-attached sessions only the clock applies (one stderr warning lists skipped fields). contextOptions passes httpCredentials / clientCertificates / extraHTTPHeaders through to browser.newContext.
  • Device scale factor: docsxai run --device-scale-factor <1-4> (or DOCSX_DEVICE_SCALE_FACTOR, flag wins; default 1, output unchanged) passes deviceScaleFactor to the browser context (launchPlaywrightSession({ deviceScaleFactor })), so the PNG is the CSS viewport times the factor. bounding_box and obstacles stay in the PNG's device pixels, and annotations.json records device_scale_factor above 1 so docsxai burn can derive its pixel ratio. Not combinable with --cdp.
  • Request guard (opt-in): DOCSX_EGRESS_GUARD=1 (or launchPlaywrightSession({ egressGuard })) routes every request of the browser context through egress-guard.ts: a host that is, or resolves (dns.lookup, all addresses) to, a link-local or cloud-metadata address is aborted, redirect hops and WebSocket connections included, and a failed lookup aborts too (the printed reason is generic: address not allowed); DOCSX_EGRESS_DENY_PRIVATE=1 adds loopback and private ranges. Both take 1, true or yes. Off by default for a local run; the backend runner turns it on for webhook runs, and so does the MCP HTTP transport for the browser run_flows starts. It does not stop DNS rebinding (SECURITY.md). An upload step reads only regular files under the workspace (upload-path.ts). The address rules in address-class.ts are a byte-identical copy of the backend's.
  • Hiding + step timeouts: hide sets visibility: hidden !important on every element its target matches until a show (no target lifts all, a target lifts the hide that used the same selector). PlaywrightDriver marks the elements with a data attribute and adopts a fixed stylesheet keyed on it (page-hide.ts, in-page and engine-owned; the selector is data, never CSS or script). The rule lives on each element's own root, so it reaches shadow trees, and constructable stylesheets are not blocked by a page's CSP. Visibility keeps the box, so nothing reflows; there is deliberately no display: none option and no general CSS-injection step. The driver keeps the selectors and re-marks before every screenshot (halt shots included), so the hiding survives navigations and re-renders. hide waits for the element to exist (attached) and throws when none does, so optional: true covers dev-only UI such as nextjs-portal. A step's timeout_ms (100 to 30000) is passed to the driver call (click(selector, timeoutMs?), hideElements(selector, timeoutMs?), …); unset, nothing is passed and Playwright's 30 s default applies, so existing flows and non-optional steps are unchanged. optional does not shorten the wait by itself, so a missing optional target costs 30 s unless timeout_ms is set; lint R011 says so. BrowserDriver gains optional hideElements? / showElements?; the runtime halts a step that needs a missing one. The pure hiddenAtEachStep (flow-hidden.ts) tells lint (R013) and diagnose which selectors an earlier hide hid.
  • Redactions: flow-level + per-step RedactionSpec[] ({ selector } or { region }, style box | pixelate) masked deterministically before any screenshot (halt shots included) hits disk. The pure pixel transform is applyRedactions in redact.ts.
  • BrowserDriver interface: what the runtime needs from a browser. The PlaywrightDriver implementation includes the actionable() predicate (see docs/actionability-contract.md) that browser-bridge consumers can mirror, plus a real element_stable wait (bounding-box polling, 10 s best-effort budget). waitForSettled?, hideElements?, showElements? and nearbyBoxes? are optional methods (behind wait_for: settled, the hide and show actions and annotations.obstacles), so a driver written before they existed still compiles; the runtime halts a step that needs a missing method with a message naming it (obstacles only when the workspace turned it on), and never calls a method the flow does not use. PlaywrightDriver runs the fixed in-page poll in page-settle.ts (fonts loaded, visible images complete, viewport box geometry unchanged for two consecutive polls, every 50 ms, bounded by the step's timeout_ms, default 10 s) and rejects with settled: page did not settle within N ms ... naming what kept moving; inferHaltCause turns that into the [page never settled: ...] prefix.
  • Annotation obstacles: opt-in (.docsxai.json → "annotations": { "obstacles": true }, default off). After a step's screenshot, runFlow asks the driver for nearbyBoxes(selector, 320): the visible text (per rendered line) and interactive elements around the target, in screenshot pixels, the target's subtree and elements containing it excluded. The pure selectObstacles (obstacles.ts) rounds boxes outward to whole pixels, clips them to the screenshot, drops duplicates, boxes inside the target and boxes covered by another kept box, caps at the 40 nearest and sorts by y, x, width, height. The result lands as obstacles on the annotation record, where the viewer's burn uses it to keep callouts off page content. The scan reads the page's own DOM (no iframe or shadow-root content) and runs only through the driver, so any BrowserDriver must implement nearbyBoxes. Off or absent, records and screenshots are unchanged.
  • Per-annotation placement: a step annotation takes an optional placement object (AnnotationPlacement: inside, side, align, pin_arrow, max_width, obstacle_radius, obstacle_limit), bounded like obstacles (finite numbers in range, max_width 120 to 560, obstacle_radius 0 to 2000 CSS px, obstacle_limit 1 to 40) and copied onto the annotation record when set. runFlow scans with the annotation's own obstacle_radius and keeps its own obstacle_limit nearest boxes; the burner reads the rest. Absent, records and scans are exactly as before.
  • Auth strategies: auth/strategy.yaml descriptor + a catalogue of scripted strategies (api-login, ui-form with a TOTP hop, email-otp, webauthn, jwt-injection, http-basic, pat-header, mtls, test-backdoor) alongside the human-in-the-loop manual-capture. See Auth strategies below.
  • CLI: docsxai <command>. See --help or the top-level README for the full surface; this package's dist/cli.js is the binary.
init scaffold a workspace
capture-auth cache an authed session
add-flow extract a flow-file from a structured guide (formerly calibrate, removed in 0.5.0)
inspect discover [data-testid] locators on the live page
run execute flows headless; emit annotations + screenshots (`--verify-determinism` byte-compares N isolated runs)
render build the static viewer (spawns the @docsxai/viewer bin; `--lang es` for Spanish page text)
burn bake annotations into PNG copies (spawns the same bin's `burn`)
site write an Astro Starlight docs site (spawns the same bin's `site`, same flags)
pack build the screenshot pack: burn, optimise, hash-name, manifest; `--check` compares a rebuild with the committed pack (spawns the viewer bin's `pack`)
lint static checks across flow-files (R001-R017; `extraRules` injectable via `lintFlow`)
flow-tree visualise the `extends` graph
diagnose halt-context + recommendations after a halt
doctor environment + workspace health-check (one ok:/fail: line per check, each with a next: step; no plugin code runs)
style init/validate style.yaml; --check scans for jargon leaks
zip package the doc pack for hand-off
baseline snapshot the doc pack (flows, prose, annotations, screenshots, locators) for drift comparison
diff deterministic drift report against a baseline (--fail-on warn|fail gates CI)
export project the doc pack to a publisher format (`export adf`: Confluence ADF; `export playwright`: Playwright specs)
plugins list / info / sync the workspace plugin set (see Plugins below)
login validate a backend bearer token (`--oauth` runs the OAuth 2.1 + PKCE flow)
push upload the doc pack to the backend as a new revision
pull fetch a backend revision's artifacts into the workspace

A flag a command does not take exits 2 (run --flwo x prints unknown flag --flwo, did you mean --flow?), as does a flag given twice (except burn --flow and site --flow) and a value flag with no value. A flag that takes no value never reads the next argument, so run --pause <workspace> keeps the workspace. The flag table is src/cli-flags.ts; burn, pack, site and doctor read their argv in their own loops, and doctor rejects an unknown or repeated flag the same way. run --start-from and --stop-after check the step id against the selected flows before the browser launches, and a step id no selected flow has exits 2. Ctrl-C (SIGINT) or SIGTERM stops a command with one docsxai: interrupted line and exits 130 or 143. While render, burn, site or pack runs, the signal goes to the viewer child and docsxai waits for it: the child gets SIGKILL after 10 s, and a second signal exits at once.

First-run failures print one reason and one next: line (browser-launch-error.ts, cli-node-guard.ts, cli-shared.ts). A missing Chromium gives the install command, a refused --cdp endpoint gives cannot attach to the browser at <endpoint> (ECONNREFUSED) and the --remote-debugging-port flag, and run --cdp skips the cached-session check. init --app-url and login --backend-url take only http: or https: URLs (isHttpUrl) and exit 2 otherwise; run --base-url also takes file: (isRunnableUrl, for a local static site) and exits 2 on any other scheme; an app_url in .docsxai.json that is not one stops run with exit 1. init on a file and a refused mkdir get their own message, run, lint and flow-tree on a workspace without flows/ print mkdir <dir>/flows (missingFlowsMessage), a cached session that is not a valid session file is called corrupt (cachedSessionIsCorrupt), and a .docsxai.json that exists but cannot be read warns in run and capture-auth and fails doctor with chmod u+r. doctor exits 2 on an unknown flag. cli-node-guard.ts runs first in cli.ts and exits 1 with one line on Node 18 and older (NODE_FLOOR_MAJOR, 20), before Playwright loads.

A flow with a top-level matrix: (locales, color_schemes, viewports; at most 64 variants) expands at parse time (expandFlow in flow-matrix.ts, schema in matrix-spec.ts) into one flow per variant, each under its own environment, with only/skip on steps and annotations and copy_by_locale on annotations. run starts one session per variant (run-flows.ts) and writes docs/<flow>/<variant>/{screenshots/, annotations.json, halts/}; annotations.json records the variant, and a halt message names it. Without a matrix the layout and every output byte are unchanged. lint (R015, R016), flow-tree and diagnose --variant read the matrix.

run has a sub-3-second iteration mode for long-async flows: --start-from <step-id> --cdp <endpoint> skips every step before the target and attaches to an already-warm Chrome.

zip packages the doc pack in-process (via fflate), no system zip binary required, and deterministically: entries are sorted, every entry's mtime is pinned to the zip epoch (1980-01-01), and the compression level is fixed, so the same doc pack always produces a byte-identical archive. Includes flows/, docs/, .docsxai.json, auth/strategy.yaml, README.md; excludes .auth/, **/halts/, and (unless --include-viewer) .viewer/. Symlinks that point outside the workspace are never followed into the archive, the fixed entries included, and the archive is written atomically.

export adf projects the doc pack to Confluence Cloud ADF (projectDocPackToAdf from the library surface), pure and deterministic, zero HTTP. Default --mode single emits one consolidated document (flows as anchored H2 sections); --mode page-tree emits a parent overview plus one document per flow. Output lands in <workspace>/.export/adf/ as projection.json + attachments.json (file name, source path, sha256 per burned screenshot, falling back to the clean screenshot with a warning when no burned PNG exists). A host agent hands these to the Atlassian MCP, or the @docsxai/plugin-confluence publisher (confluence:push) consumes them; all Confluence HTTP lives in that capability-declared plugin, never in the engine.

baseline + diff are the drift-detection pair. baseline snapshots flows/ + docs/ (step .mds, annotations.json, screenshots/, locators.yaml) into <workspace>/.baseline/ (or --out <dir>); diff compares the live workspace against it (diffDocPacks on the library surface) and emits a deterministic docsxai/drift@1 report. Per flow: id-keyed step field deltas, annotation moves beyond a pixel tolerance, screenshot pixel diffs via pngjs (changed-pixel count / pct / changed-region bbox; dimension changes flagged distinctly; ignore_regions excluded), prose line-change counts, and locator changes. --format md (formatDriftReportMarkdown) is PR-comment-ready; --fail-on warn|fail exits 1 at/above the threshold (defaults: ≥1% changed pixels = warn, ≥5% = fail, structural change = warn). The engine detects and reports; proposing flow-file patches stays with the host agent (diagnose).

run --verify-determinism [--runs <2-5>] [--format text|md|json] runs the selected flows N times (default 2) through the same flow loop as a plain run (runFlowsInSessions), each into its own output root under <workspace>/.docsxai-verify/run-<k>/ (PlaywrightSessionOptions.outputRoot redirects the screenshots; upload sources still resolve against the workspace), then byte-compares every file under the roots (compareRuns in verify-compare.ts, exported). The first differing artefact is named by path with a cause: JSON key path, PNG changed-pixel count and region (the diffPngBuffers of diff), first differing text line, or sizes. A halt is recorded as docs/<flow>/halts/halt-context.json in the run root, so halt context is compared like any artefact; a halted flow makes the verdict halted (exit 1). Run 1's tree is copied into the workspace only when every run agrees and none halted; otherwise the workspace is untouched. The roots are removed by their listing (unlink each file, rmdir each directory deepest first; verify-tree.ts), never recursively. The docsxai/verify-determinism@1 report has no timestamps or paths and is ordered by ordinal path then run: exit 0 identical, 1 differing or halted, 2 usage. Nightly recipes for GitHub Actions, GitLab CI and Woodpecker are in docs/ci-recipes.md and examples/ci/.

export playwright renders each flow (with extends resolved) as a self-contained Playwright .spec.ts (exportFlowAsPlaywrightTest) into <workspace>/.export/tests/: locator consts, steps as page actions, wait_for as waits, success as expect() assertions, environment as test.use() + page.clock.setFixedTime, optional steps in try/catch. Deterministic; generated files carry a "regenerate, don't hand-edit" header.

render, burn, site and pack locate the viewer bin in order: DOCSX_VIEWER_BIN (path to the viewer's bin script or an executable), the @docsxai/viewer package installed next to the engine (its bin run with the current Node), then docsxai-viewer on PATH. A launch failure reports all three attempts.

burn <workspace-dir> [--flow <name>] [--out <dir>] [--report <file>] [--no-connector-outline] [--strict-glyphs] bakes the annotations into PNG copies by running the viewer's burn through that same resolution (the engine does not depend on @docsxai/viewer). It checks the workspace has a docs/ directory, passes the flags through, and returns the viewer's exit code; an unknown flag or a path-like --flow exits 2. The viewer skips an annotation whose bounding_box is off the image, has no area or holds NaN (a warning names the selector and step; --report marks it skipped) and clips one that overhangs an edge.

pack <workspace-or-raw-dir> [--from-raw] [--out <dir>] [--public-prefix <path>] [--no-optimise] [--generated-for <text>] and pack <workspace-or-raw-dir> --check --against <pack-dir> [--from-raw] [--threshold <pct>] (cli-commands-pack.ts) are the screenshot-pack pair. The old drift command is retired: cli-retired.ts maps it to pack --check with a deprecation warning (deprecation.ts). Like burn, the engine validates the argv edge (an unknown flag, a flag with no value, a second positional, no --against, a --threshold that is not a number >= 0 all exit 2), then runs the viewer's pack or drift through the same bin resolution (runViewerBin in viewer-bin.ts) and returns its exit code. The viewer owns the logic (burn, oxipng, hashing, manifest, drift); the engine does not import it. See the viewer README.

push reads the whole doc pack before it touches the backend, so an unreadable pack (an invalid docs/style.json) exits 1 with nothing created there, and it leaves out files that are symlinks to a file outside the workspace; the backend ids it records in .docsxai.json are written atomically. pull requests only the artifact names flows, annotations, screenshots, style and locators (a warning for any other name) and writes the doc pack as one transaction (writeDocPack in doc-pack-io.ts, staging through atomic-write.ts): every file is staged next to its target and renamed into place together, a failure while staging changes nothing, and a failed rename puts the swapped files back. export adf and export playwright skip a flow file, step markdown file or screenshot that is a symlink to a file outside the workspace; one that points inside it still works.

lint rule R017 warns when a flow's name: differs from its file name, because extends, --flow and docs/<name>/ use the name. Two flow files with one name: stop run, lint and flow-tree with exit 1. A matrix viewport name may not be screenshots, halts or a Windows device name (con, prn, aux, nul, com1 to com9, lpt1 to lpt9), because it becomes a directory. style on a path that is not a directory exits 1 and writes nothing.

Target-site auth lives in src/auth/ (one module per strategy) behind the src/auth.ts re-export shim. Every strategy implements AuthStrategy.authenticate(ctx) → AuthResult and reduces to the same universal artifact: a storageState (cookies + localStorage) the runtime seeds the browser context with, plus, for connection-level schemes, contextOptions (httpCredentials / extraHTTPHeaders / clientCertificates) passed through to browser.newContext. Roles are declared in <workspace>/auth/strategy.yaml (docsxai/auth-strategy@1): per-role strategy, creds_env (credential keys → env-var names, never values), options, and cache (local/backend store, ttl, auth_cookie expiry pinning). The local cache is <workspace>/.auth/<role>.json, written with mode 0600 (src/auth/storage-state-cache.ts); a role name with characters outside A-Za-z0-9_.-, and backend-token, gets a hash suffix in the file name, so two roles never share a file and none overwrites the OAuth token file.

StrategySchemeBrowser needed
api-loginPOST creds to the login endpoint; cookies collected across the redirect chain (own RFC-6265 jar)no
ui-formdrive the app's own login form: fill, submit, success marker, snapshot; pre_steps dismiss pre-login chrome; options.totp adds an RFC-6238 hop (dep-free generateTotp/verifyTotp primitives exported)headless
email-otpui-form whose code arrives by mail; an InboxProvider polls the inbox (http-json built-in: Mailpit-style { messages: [{to, received_at, body}] }); code_pattern extracts the code (default \b(\d{6})\b)headless
webauthnpasskey via a CDP virtual authenticator (ctap2 / internal / user-verifying), attached before navigation; trigger_selector starts the ceremonyheadless
jwt-injectionstatic token (token_env) or OAuth2 client-credentials mint (token_url); injected into localStorage and/or cookies via {{token}} templatesno
http-basicconnection-level httpCredentialsno
pat-headertoken header via extraHTTPHeaders (value_template, default Bearer {{token}})no
mtlsclient certificate via clientCertificates (creds_env maps cert/key to PEM file paths)no
test-backdoorPOST a shared secret to a test-only endpointno
manual-captureinstrumented Chrome; a human logs in and triggers captureheaded

Cross-cutting contracts:

  • Secrets stay out of band. Strategies read env-var names from the descriptor and resolve values at run time; error messages mask values as <SET>/<UNSET> and never echo them.
  • User pools. Any credential env value may be comma-separated (u1,u2,u3); resolveCreds({ workerIndex }) gives parallel worker N entry N % len, consistently across every pooled variable.
  • expiresAt when derivable. From the named / lone real-expiry cookie (jarAuthExpiry), the JWT exp claim, or the token endpoint's expires_in; the cache's auth_cookie / ttl rules cover the rest.
  • Registries. registerAuthStrategy(name, impl) adds or overrides a scheme (consulted before the built-ins: the plugins-runtime hook); registerInboxProvider(name, factory) adds email-otp inbox shapes.
  • One Playwright import site. Browser-driving strategies depend on the narrow AuthPage interface (src/auth/browser-session.ts); the default launcher routes through launchPlaywrightSession, so unit tests fake the page and playwright-driver.ts remains the engine's single Playwright integration point.

The engine hosts a workspace plugin runtime (v1) with four extension points: publishers, renderers, lint-rules, and auth-strategies. Plugins are normal npm packages: a docsxai field on package.json plus a module exporting register(api). They run in-process and unsandboxed: trust is a review signal, not a boundary. The no-model-API rule binds them exactly as it binds the engine.

{
"name": "@docsxai/plugin-confluence",
"version": "0.1.0",
"docsxai": {
"apiVersion": "1.0.0",
"namespace": "confluence",
"register": "./dist/register.js",
"kinds": ["publisher"],
"capabilities": ["egress:*.atlassian.net"],
"dependsOn": [],
"trust": "example-org"
}
}
  • apiVersion: exact semver of the runtime contract the plugin codes against. Must share the engine's RUNTIME_API_VERSION major with minor ≤ the runtime's, or the plugin load-errors.
  • namespace: mandatory, /^[a-z][a-z0-9-]*$/. Every registered artifact is exposed as <namespace>:<name> (the runtime prefixes; plugins pass bare names). Reserved: site-docs, docsxai, core, plugins. Two plugins claiming one namespace are both disabled.
  • kinds: the extension points the plugin registers (≥1). Registering an undeclared kind throws and load-errors the plugin (capability-disclosure honesty).
  • capabilities: egress:<host-glob> declarations, subset-checked against the workspace's plugin_capabilities. Mismatch disables the plugin (status, not fatal). Publisher plugins are the only wiki/VCS egress path in the engine.
  • dependsOn: { plugin, version } entries (package name + ^/~/exact range). Load order is topological; cycles are rejected as a unit.

The register module exports a register(api) function (named or default). api exposes namespace, declaredKinds, declaredCapabilities, registerPublisher(name, impl), registerRenderer(name, impl), registerLintRules(name, rules), registerAuthStrategy(name, impl), a stderr logger (api.log, prefixed [plugin:<ns>]), and api.workspacePath(...segments), the only filesystem root a plugin may touch (escape attempts throw). The extension-point contracts (PublisherPlugin, RendererPlugin, AuthStrategyPlugin, PluginLintRule) are exported from this package.

Two optional .docsxai.json keys wire plugins into a workspace (a third, annotations.obstacles, switches on obstacle scanning for run; see the engine overview above):

{
"plugins": [{ "package": "@docsxai/plugin-confluence" }, { "path": "../my-local-plugin" }],
"plugin_capabilities": ["egress:*.atlassian.net"]
}

@docsxai/plugin-confluence is repo-only (private: true, not on npm). Build it in a checkout (pnpm -r build) and wire it by path instead: { "path": "<checkout>/packages/plugin-confluence" }. The { "package": ... } form resolves only once the package is installed in the workspace.

plugins-lock.json (schema docsxai/plugins-lock@1, next to the config) pins each plugin's register-module sha256. When it exists, every resolve verifies the bytes before importing; a mismatch fails closed with a "run docsxai plugins sync" message.

docsxai plugins list <workspace> status table (loaded / disabled reasons); exit 1 if any plugin isn't loaded
docsxai plugins info <workspace> <namespace> manifest + registered artifact names
docsxai plugins sync <workspace> (re)write plugins-lock.json, never executes plugin code

All three accept --format json. Plugins are resolved once per CLI invocation, so there is no hot reload.

Apache-2.0.

Made by KalebtecGitHubApache-2.0 licensed