@michaelmagan/dnumb 0.1.0

package/dist/cli.cjs

@@ -0,0 +1,755 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+/**
+ * `dnumb` — the bin entrypoint.
+ *
+ * Arg parsing is `node:util`'s `parseArgs`, not a dependency and not
+ * hand-rolled. The prototype hand-rolled it; `parseArgs` has been stable since
+ * Node 18 and this package's floor is 22.12.
+ *
+ * This file does three things and delegates everything else: turn argv into
+ * options, get a `Bundle` off disk, and print one of the two renderings
+ * `src/query.ts` already produced. It holds no formatting of its own, because a
+ * second place that decides what a measurement looks like is a second place for
+ * `--json` and the text to disagree. `capture` is held to the same rule: it
+ * launches a browser and navigates, but the measuring and the serializing are
+ * `dnumb/playwright`'s `capture()` and `serializeBundle`, called here rather
+ * than reimplemented — a second place that decides what a bundle looks like is
+ * the same mistake as a second place that decides what a digest looks like.
+ *
+ * `playwright-core` is loaded with a dynamic `import()` inside the `capture`
+ * verb only, never at module scope. It is an optional peer dependency, and a
+ * static top-level import would make every other verb — `look`, `q`, `diff`,
+ * none of which touch a browser — fail to load for a consumer who never
+ * installed it. Verified empirically, not assumed: a module with a static
+ * `import ... from 'playwright-core'` throws `ERR_MODULE_NOT_FOUND` on load
+ * before any of its exports run, while a module that only imports it inside
+ * one function loads fine and fails only when that function is called.
+ *
+ * Exit codes are the contract a CI script reads: 0 answered, 1 the command was
+ * wrong, 2 the bundle was unreadable, 3 a live capture could not be produced
+ * (no browser installed, DNS failure, connection refused, navigation timeout),
+ * 4 a capture succeeded and then could not be saved (permissions, a full
+ * disk, two capture names colliding on one path — `writeBundle` in
+ * `src/playwright.ts`). 3 and 4 exist as two codes, not one, because they are
+ * opposite failures a CI script needs to tell apart: 3 means nothing was
+ * measured, re-run the capture; 4 means the measurement worked and only the
+ * write did not, so re-running the same capture is exactly the right fix, not
+ * a wasted round trip. Before 4 existed, a write failure after a successful
+ * capture had no wrapped path at all — it escaped as an unhandled promise
+ * rejection with a raw stack trace and exit 1, misreporting an I/O problem as
+ * a bad command after the measurement had already been taken and thrown away.
+ * There is no "found problems" code, and there will not be one — dnumb does
+ * not adjudicate.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_url_1 = require("node:url");
+const node_util_1 = require("node:util");
+const bundle_js_1 = require("./bundle.cjs");
+const index_js_1 = require("./diff/index.cjs");
+const index_js_2 = require("./digest/index.cjs");
+const playwright_js_1 = require("./playwright.cjs");
+const query_js_1 = require("./query.cjs");
+const limits_js_1 = require("./snapshot/limits.cjs");
+const not_measured_js_1 = require("./snapshot/not-measured.cjs");
+const index_js_3 = require("./spec/index.cjs");
+/**
+ * `../package.json` from this file's own location, which is the package root
+ * either way this file runs: `src/cli.ts` in dev/test, `dist/cli.cjs` after
+ * build. Read lazily, only when `--version` is actually asked for, rather
+ * than on every invocation.
+ */
+const PACKAGE_JSON_PATH = (0, node_url_1.fileURLToPath)(new URL('../package.json', require("url").pathToFileURL(__filename)));
+/** `--help` promises "the package and spec versions"; this is the first half. */
+function packageVersion() {
+    try {
+        const pkg = JSON.parse((0, node_fs_1.readFileSync)(PACKAGE_JSON_PATH, 'utf8'));
+        const version = pkg.version;
+        return typeof version === 'string' && version !== '' ? version : 'unknown';
+    }
+    catch {
+        // A missing or unreadable package.json should not take down `--version`
+        // itself -- the spec version, at least, is still answerable.
+        return 'unknown';
+    }
+}
+const OK = 0;
+/** The command was wrong: unknown verb, missing argument, unknown element id. */
+const USAGE_ERROR = 1;
+/** The bundle was wrong: not there, not readable, not a dnumb bundle. */
+const BUNDLE_ERROR = 2;
+/**
+ * `capture` could not produce a bundle: no `playwright-core` installed, no
+ * browser binary downloaded, DNS failure, connection refused, or a navigation
+ * timeout. None of these are a bad command (1) or a bad bundle (2) — the
+ * command was right and there was no bundle to be wrong about yet.
+ */
+const CAPTURE_ERROR = 3;
+/**
+ * `capture` measured the page and then could not save it: a filesystem error
+ * writing the bundle (permissions, a full disk) or `writeBundle`'s own "two
+ * capture names write to one path" collision (`src/playwright.ts`). Distinct
+ * from `CAPTURE_ERROR` on purpose — see the file header for why.
+ */
+const WRITE_ERROR = 4;
+const USAGE = `dnumb — design, in numbers.
+
+Turns a rendered page into measurements an agent can read. It reports facts and
+does not decide whether anything is wrong.
+
+USAGE
+  dnumb capture <url> [--name <name>] [--dir <dir>] [--viewport <WxH>] [--wait <state>]
+                      [--strategy <auto|walk|cdp>]
+  dnumb --from <bundle> look [--focus <id|tag>] [--edges] [--budget-chars <n>] [--budget <n>]
+  dnumb --from <bundle> q <verb> [args]
+  dnumb --from <before> diff <after>
+
+VERBS
+  capture <url>              Launch a browser, navigate, and write a bundle.
+  look                       Render the digest: every element, geometry, facts.
+  diff <bundle>              What changed between two captures, and why.
+  q describe <id>            Everything the capture knows about one element.
+  q find <text|tag|role>     Elements matching, as digest lines.
+  q at <x> <y>               What is at a point. Innermost first.
+  q within <x> <y> <w> <h>   What overlaps a region. Largest overlap first.
+  q distance <idA> <idB>     Edge-to-edge and centre-to-centre distance.
+  q nearest <id>             The closest layout nodes by edge distance.
+  q facts                    Every element carrying a fact, one per line.
+  q color                    fg/bg pairs, ratio ascending, unmeasured last.
+  q color <id>               One element's full composite chain.
+  q color --all              Every gated element's color line.
+
+Capture reports whatever is on screen the instant it runs — a skeleton
+screen, a mid-animation frame, a half-fetched list — with no way to tell
+settled from loading, so choose --wait deliberately and expect to re-run it.
+
+OPTIONS
+      --from <bundle>  The capture bundle to read. Required by every verb but capture.
+      --json           Machine-readable output. Every verb supports it.
+      --limit <n>      Rows the list verbs print (default 50; 0 for all).
+      --k <n>          Neighbours \`q nearest\` returns (default 4).
+      --focus <id>     \`look\` only: scope the digest to one subtree.
+      --edges          \`look\` only: add the edge-cluster histogram header.
+      --budget-chars <n> \`look\` only: soft target for total digest body characters
+                        (default 32768). The standing budget meter -- always active.
+      --budget <n>     \`look\` only: soft target for digest body lines. Additional to
+                        --budget-chars, never a replacement for it -- passing --budget
+                        does not turn the character budget off.
+      --all            \`q color\` only: per-element lines instead of the pair table.
+      --name <name>    \`capture\` only: name for the bundle (default "capture").
+      --dir <dir>      \`capture\` only: directory the bundle is written to (default .dnumb).
+      --viewport <WxH> \`capture\` only: e.g. 375x812 (default: the browser's own default).
+      --wait <state>   \`capture\` only: load|domcontentloaded|networkidle|commit before
+                        capturing (default load). See the hazard above before trusting this.
+      --timeout <ms>   \`capture\` only: navigation timeout (default: Playwright's own, 30s).
+      --strategy <s>   \`capture\` only: auto|walk|cdp (default auto). \`docs/digest.md\` walks
+                        through comparing a cdp capture against a walk capture of the same
+                        page for both the color and the shadow-DOM asymmetry between the two
+                        paths -- this is what lets that comparison happen from the CLI alone.
+                        \`cdp\` on a non-Chromium/non-CDP page is a usage error, not a fallback.
+  -h, --help           Print this and exit.
+  -v, --version        Print the package and spec versions and exit.
+
+Put \`--\` before a negative coordinate: dnumb --from b.json q at -- -8 120
+
+Element ids like e13 are stable within one capture only. They are not DOM ids.
+https://github.com/michaelmagan/dnumb#readme
+`;
+const OPTIONS = {
+    help: { type: 'boolean', short: 'h', default: false },
+    version: { type: 'boolean', short: 'v', default: false },
+    json: { type: 'boolean', default: false },
+    from: { type: 'string' },
+    focus: { type: 'string' },
+    edges: { type: 'boolean', default: false },
+    all: { type: 'boolean', default: false },
+    budget: { type: 'string' },
+    'budget-chars': { type: 'string' },
+    k: { type: 'string' },
+    limit: { type: 'string' },
+    name: { type: 'string' },
+    dir: { type: 'string' },
+    viewport: { type: 'string' },
+    wait: { type: 'string' },
+    timeout: { type: 'string' },
+    strategy: { type: 'string' },
+};
+const out = (text) => {
+    process.stdout.write(text);
+};
+function fail(code, message) {
+    process.stderr.write(`${message}\n`);
+    return code;
+}
+/** A flag value that must be a whole number, with the flag named in the complaint. */
+function integer(raw, flag, minimum) {
+    if (raw === undefined)
+        return undefined;
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isFinite(value) || String(value) !== raw.trim() || value < minimum) {
+        throw new query_js_1.QueryError(`--${flag} takes a whole number ≥ ${minimum}; got "${raw}".`);
+    }
+    return value;
+}
+/** The states Playwright's `page.goto` can wait on before we take the snapshot. */
+const WAIT_STATES = ['load', 'domcontentloaded', 'networkidle', 'commit'];
+/** An error's first line, so a long CDP call-log doesn't drown the one sentence that matters. */
+function firstLine(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return (message.split('\n')[0] ?? message).trim();
+}
+/** `writeFileSync`/`mkdirSync` failure codes `writeBundle` (`src/playwright.ts`) can surface. */
+const FS_ERROR_CODES = new Set([
+    'ENOENT',
+    'EACCES',
+    'EPERM',
+    'ENOSPC',
+    'EROFS',
+    'EEXIST',
+    'EISDIR',
+    'ENOTDIR',
+    'EMFILE',
+    'ENFILE',
+]);
+/**
+ * True for the two failures `writeBundle` can throw: a filesystem error
+ * writing the file, or its own "two capture names write to one path"
+ * collision. Both happen strictly *after* `captureSnapshot` already
+ * succeeded — the measurement was taken — which is what earns them
+ * `WRITE_ERROR` instead of `CAPTURE_ERROR`: the latter means nothing was
+ * measured, and by the time either of these fires, something was. Anything
+ * else `captureToDisk` throws (a page crash mid-measurement, a lost CDP
+ * connection) still means `CAPTURE_ERROR` and falls through to it below.
+ */
+function isWriteFailure(error) {
+    if (error instanceof Error && /^dnumb: capture .+ both write to /.test(error.message)) {
+        return true;
+    }
+    const code = error?.code;
+    return typeof code === 'string' && FS_ERROR_CODES.has(code);
+}
+/**
+ * `capture <url>` needs an absolute URL, not a bare host, because there is no
+ * `baseURL` for a relative one to resolve against. Caught here, before a
+ * browser is launched, it is a usage error (1); caught by the navigation
+ * itself it would be a capture error (3) with no clean way to tell the two
+ * apart from the caller's side.
+ */
+function parseCaptureUrl(raw) {
+    if (raw === undefined || raw === '') {
+        throw new query_js_1.QueryError('capture needs a URL: dnumb capture <url> [options]');
+    }
+    try {
+        new URL(raw);
+    }
+    catch {
+        throw new query_js_1.QueryError(`"${raw}" is not a URL capture can load — it needs a scheme. Did you mean https://${raw}?`);
+    }
+    return raw;
+}
+/** `--viewport 375x812` → `{ width: 375, height: 812 }`, or a usage error naming what was typed. */
+function parseViewport(raw) {
+    if (raw === undefined)
+        return undefined;
+    const match = /^(\d+)x(\d+)$/.exec(raw.trim());
+    if (!match?.[1] || !match[2]) {
+        throw new query_js_1.QueryError(`--viewport takes WIDTHxHEIGHT, e.g. 375x812; got "${raw}".`);
+    }
+    const width = Number.parseInt(match[1], 10);
+    const height = Number.parseInt(match[2], 10);
+    if (width < 1 || height < 1) {
+        throw new query_js_1.QueryError(`--viewport dimensions must be ≥ 1px; got "${raw}".`);
+    }
+    return { width, height };
+}
+function parseWait(raw) {
+    if (raw === undefined)
+        return 'load';
+    if (!WAIT_STATES.includes(raw)) {
+        throw new query_js_1.QueryError(`--wait takes one of ${WAIT_STATES.join(', ')}; got "${raw}".`);
+    }
+    return raw;
+}
+/**
+ * P2-2: `dnumb/playwright`'s `capture()` has always taken a `strategy`
+ * (`auto | walk | cdp`, `snapshot/capture.ts`), but the CLI never exposed it
+ * -- `doCapture` called `captureToDisk` with no strategy at all, always
+ * `auto`. `docs/digest.md` walks a reader through comparing a `cdp` capture
+ * against a `walk` capture of the same page twice over -- once for the color
+ * overlay-detection asymmetry (`centre` sample vs `whole-rect`), once for
+ * shadow DOM (`cdp` can flatten shadow content in, unreliably; `walk` cannot
+ * see into a shadow root at all) -- and a CLI-only user, with no Playwright
+ * suite to write `{ strategy: 'walk' }` into, had no way to run that
+ * comparison. `'auto'` is not in `CaptureOptions['strategy']`'s type as an
+ * omittable default by accident here either: passing it explicitly is
+ * identical to passing nothing, so this validates it without threading a
+ * fourth branch through `doCapture` for no behavioural difference.
+ */
+const CAPTURE_STRATEGIES = ['auto', 'walk', 'cdp'];
+function parseStrategy(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!CAPTURE_STRATEGIES.includes(raw)) {
+        throw new query_js_1.QueryError(`--strategy takes one of ${CAPTURE_STRATEGIES.join(', ')}; got "${raw}".`);
+    }
+    return raw;
+}
+/**
+ * Launch a browser, navigate, and hand the page to `dnumb/playwright`'s own
+ * `capture()` — the same function a Playwright suite calls. Everything below
+ * this line that is not "launch" or "navigate" is that function's job, not
+ * this one's, so a second bundle-writer never drifts from the first.
+ *
+ * `playwright-core` is imported here, inside the verb, and nowhere else in
+ * this file — see the file header for why a top-level import would be wrong.
+ */
+async function doCapture(url, opts, json) {
+    let playwrightCore;
+    try {
+        playwrightCore = await Promise.resolve().then(() => __importStar(require('playwright-core')));
+    }
+    catch {
+        return fail(CAPTURE_ERROR, 'dnumb: capture needs playwright-core, an optional peer dependency that is not installed. ' +
+            "Run `npm install playwright-core` (or your package manager's equivalent), then " +
+            '`npx playwright install chromium` to download a browser.');
+    }
+    let browser;
+    try {
+        browser = await playwrightCore.chromium.launch();
+    }
+    catch (error) {
+        return fail(CAPTURE_ERROR, `dnumb: could not launch a browser: ${firstLine(error)}\n` +
+            'Run `npx playwright install chromium` to download one.');
+    }
+    try {
+        const page = await browser.newPage(opts.viewport ? { viewport: opts.viewport } : {});
+        try {
+            await page.goto(url, {
+                waitUntil: opts.waitUntil,
+                ...(opts.timeoutMs !== undefined ? { timeout: opts.timeoutMs } : {}),
+            });
+        }
+        catch (error) {
+            return fail(CAPTURE_ERROR, `dnumb: could not load ${url}: ${firstLine(error)}`);
+        }
+        let outcome;
+        try {
+            outcome = await (0, playwright_js_1.capture)(page, opts.name, {
+                outputDir: opts.outputDir,
+                ...(opts.strategy !== undefined ? { strategy: opts.strategy } : {}),
+            });
+        }
+        catch (error) {
+            // Whatever comes next, the browser measured the page: `page.goto`
+            // already succeeded above. If this is a save failure, name it as one
+            // and report the path capture was trying to write, computed the same
+            // way `writeBundle` computes it, so nothing about a completed capture
+            // is silently lost — only unresolved. Anything else here is treated as
+            // a genuine capture failure (`CAPTURE_ERROR`) rather than left to
+            // escape as an unhandled rejection, which is what used to turn every
+            // one of these into a misreported exit 1.
+            if (isWriteFailure(error)) {
+                let intended = null;
+                try {
+                    intended = (0, node_path_1.resolve)((0, playwright_js_1.bundlePath)(opts.outputDir, opts.name));
+                }
+                catch {
+                    // `safeName` already validated `opts.name` in `runCapture`; this
+                    // is unreachable in practice, and `intended` staying null just
+                    // drops the path from the message rather than throwing again.
+                }
+                return fail(WRITE_ERROR, `dnumb: captured ${url} but could not save the bundle` +
+                    (intended ? ` to ${intended}` : '') +
+                    `: ${firstLine(error)}\n` +
+                    'The measurement was taken; only the write failed. Fix the write problem ' +
+                    '(permissions, disk space, or rename one of two colliding capture names) and run ' +
+                    'this same capture again — nothing about the page needs to change.');
+            }
+            return fail(CAPTURE_ERROR, `dnumb: captured ${url} but could not finish producing a bundle: ${firstLine(error)}`);
+        }
+        const { bundle, path } = outcome;
+        // `capture` is the first thing a new user runs, so it is also the first
+        // moment the tool discloses its own limits -- the moment where a caller
+        // could still re-run with a different `--strategy` or a narrower page.
+        // Both `truncated` and `notMeasured` were already written into the
+        // bundle either way; only the write's own report of them was missing.
+        const notMeasuredLine = (0, not_measured_js_1.formatNotMeasured)(bundle.notMeasured);
+        const textLines = [`dnumb: wrote ${bundle.elements.length} elements to ${path}`];
+        if (bundle.truncated) {
+            // Named directly from the constant this same process just capped the
+            // walk at, not inferred from `bundle.elements.length` -- the count and
+            // the cap coincide for a bundle this process just wrote, but naming
+            // the cap directly says what is actually true regardless of that, and
+            // matches what a caller needs to know: this is the ceiling to raise.
+            textLines.push(`# TRUNCATED: this capture stopped at the ${limits_js_1.MAX_ELEMENTS}-element cap; the page has more elements than were captured`);
+        }
+        if (notMeasuredLine)
+            textLines.push(`# ${notMeasuredLine}`);
+        out(json
+            ? `${JSON.stringify({
+                verb: 'capture',
+                name: bundle.name,
+                url: bundle.url,
+                path,
+                viewport: bundle.viewport,
+                // P2-3: `look --json` has always called this `records` (`src/
+                // query.ts`'s `look()`), matching what the digest header itself
+                // calls it (`# page: WxH (<N> records → <M> layout nodes ...)`,
+                // `docs/digest.md`). `capture --json` called the identical
+                // count `elements` -- same value, different name, across the
+                // two verbs a caller is most likely to pipe straight into each
+                // other. `records` is the name that already has two other
+                // callers agreeing with it.
+                records: bundle.elements.length,
+                truncated: bundle.truncated,
+                notMeasured: bundle.notMeasured,
+            }, null, 2)}\n`
+            : `${textLines.join('\n')}\n`);
+        return OK;
+    }
+    finally {
+        await browser.close();
+    }
+}
+/**
+ * The synchronous half of `capture`: parse and validate argv. This never
+ * touches a browser, so a bad `--viewport` or a missing URL fails instantly
+ * and exits 1 without the dynamic import of `playwright-core` ever running —
+ * which matters for a caller who does not have it installed and is only here
+ * because they typo'd a flag.
+ */
+function runCapture(positionals, values, json) {
+    let url;
+    let name;
+    let outputDir;
+    let viewport;
+    let waitUntil;
+    let timeoutMs;
+    let strategy;
+    try {
+        url = parseCaptureUrl(positionals[0]);
+        name = typeof values.name === 'string' && values.name !== '' ? values.name : 'capture';
+        (0, playwright_js_1.safeName)(name); // Throws a "dnumb: capture name ..." Error if unusable as a filename.
+        outputDir =
+            typeof values.dir === 'string' && values.dir !== '' ? values.dir : playwright_js_1.DEFAULT_OUTPUT_DIR;
+        viewport = parseViewport(typeof values.viewport === 'string' ? values.viewport : undefined);
+        waitUntil = parseWait(typeof values.wait === 'string' ? values.wait : undefined);
+        timeoutMs = integer(typeof values.timeout === 'string' ? values.timeout : undefined, 'timeout', 1);
+        strategy = parseStrategy(typeof values.strategy === 'string' ? values.strategy : undefined);
+    }
+    catch (error) {
+        if (error instanceof query_js_1.QueryError)
+            return fail(USAGE_ERROR, `dnumb: ${error.message}`);
+        if (error instanceof Error) {
+            return fail(USAGE_ERROR, error.message.startsWith('dnumb:') ? error.message : `dnumb: ${error.message}`);
+        }
+        throw error;
+    }
+    return doCapture(url, {
+        name,
+        outputDir,
+        ...(viewport ? { viewport } : {}),
+        waitUntil,
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        ...(strategy !== undefined ? { strategy } : {}),
+    }, json);
+}
+function optionsFrom(values) {
+    const budgetLines = integer(values.budget, 'budget', 1);
+    // No default threaded through here: an absent `--budget-chars` leaves
+    // `budgetChars` undefined all the way to `renderDigest`, which supplies
+    // `DEFAULT_BUDGET_CHARS` itself (`digest/render.ts`). Hardcoding that
+    // number here would be a second place claiming to know the default, and
+    // the two would silently drift the next time the library's own changed.
+    const budgetChars = integer(values['budget-chars'], 'budget-chars', 1);
+    const k = integer(values.k, 'k', 1);
+    const limit = integer(values.limit, 'limit', 0);
+    return {
+        ...(values.focus !== undefined ? { focus: values.focus } : {}),
+        ...(values.edges ? { edges: true } : {}),
+        ...(values.all ? { all: true } : {}),
+        ...(budgetLines !== undefined ? { budgetLines } : {}),
+        ...(budgetChars !== undefined ? { budgetChars } : {}),
+        ...(k !== undefined ? { k } : {}),
+        ...(limit !== undefined ? { limit } : {}),
+    };
+}
+/**
+ * Read the bundle, or say which path was tried.
+ *
+ * `--from` is the only thing standing between an agent and six-month-old
+ * measurements, so a miss names the resolved absolute path rather than echoing
+ * back whatever relative string was typed — the two differ exactly when the
+ * caller is in the wrong directory, which is the case worth diagnosing.
+ */
+function readBundle(from) {
+    const path = (0, node_path_1.resolve)(from);
+    let text;
+    try {
+        text = (0, node_fs_1.readFileSync)(path, 'utf8');
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT') {
+            return fail(BUNDLE_ERROR, `dnumb: no bundle at ${path}. --from takes a file written by capture() (dnumb/playwright), not a URL or a directory.`);
+        }
+        if (code === 'EISDIR') {
+            return fail(BUNDLE_ERROR, `dnumb: ${path} is a directory. --from takes one bundle file.`);
+        }
+        return fail(BUNDLE_ERROR, `dnumb: could not read ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+        return (0, bundle_js_1.parseBundle)(text, path);
+    }
+    catch (error) {
+        if (error instanceof bundle_js_1.BundleFormatError)
+            return fail(BUNDLE_ERROR, `dnumb: ${error.message}`);
+        throw error;
+    }
+}
+/**
+ * Mirrors `src/diff/render.ts`'s own (unexported) `RANK` and `documentOrder`
+ * -- `renderDiff` decides the text's line order and does not export the
+ * pieces that do, and this file owns the `--json` payload's own ordering
+ * decision (B5). Kept in the same shape on purpose: `--json` and the text
+ * describe the same diff, and a caller comparing the Nth JSON entry against
+ * the Nth text line should never find them disagreeing about what comes
+ * first. `Change['kind']` values are fixed by `diff/types.ts`; this table
+ * cannot silently miss one the compiler wouldn't catch.
+ */
+const DIFF_KIND_RANK = {
+    added: 0,
+    removed: 0,
+    appeared: 1,
+    disappeared: 1,
+    text: 2,
+    attr: 2,
+    clip: 3,
+    overflow: 3,
+    box: 4,
+    style: 5,
+};
+/** Document order, read off the id -- same convention as `render.ts`'s own. */
+function diffDocumentOrder(change) {
+    const id = change.after?.id ?? change.before?.id ?? '';
+    const digits = /^e(\d+)$/.exec(id)?.[1];
+    return digits === undefined ? 0 : Number(digits);
+}
+const diffRank = (change) => change.cause === 'derived' ? DIFF_KIND_RANK.style + 1 : DIFF_KIND_RANK[change.kind];
+/**
+ * The `Change[]` `--json` actually reports: `renderDiff` never prints a
+ * `subsumed` change (`src/diff/render.ts`'s own `live` filter) -- it exists
+ * only to explain the change that absorbed it -- so including it here let
+ * `--json` report entries the text can never produce, and slicing the raw,
+ * unsorted array by `--limit` capped a different, differently-ordered list
+ * than the one `--limit` (as `maxLines`) capped in the text (B5). Filtering
+ * to the same "live" set and sorting it the same way the text is sorted
+ * fixes both: the two now describe the same set of changes, in the same
+ * order, even though the text goes on to fold some of them onto shared
+ * lines (`foldDerived`) where `--json` keeps one entry per change.
+ */
+function reportableChanges(changes) {
+    return [...changes]
+        .filter((change) => change.subsumed === undefined)
+        .sort((a, b) => diffRank(a) - diffRank(b) || diffDocumentOrder(a) - diffDocumentOrder(b));
+}
+function main(argv = process.argv.slice(2)) {
+    let values;
+    let positionals;
+    try {
+        ({ values, positionals } = (0, node_util_1.parseArgs)({
+            args: argv,
+            options: OPTIONS,
+            allowPositionals: true,
+            strict: true,
+        }));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const hint = error.code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION'
+            ? 'If that was a negative coordinate, put `--` before it: dnumb --from b.json q at -- -8 120'
+            : 'Run `dnumb --help` for the verbs and their arguments.';
+        return fail(USAGE_ERROR, `dnumb: ${message}\n${hint}`);
+    }
+    if (values.version === true) {
+        const version = packageVersion();
+        out(values.json === true
+            ? `${JSON.stringify({ package: version, spec: index_js_3.SPEC_VERSION })}\n`
+            : `dnumb ${version} (spec ${index_js_3.SPEC_VERSION})\n`);
+        return OK;
+    }
+    const verb = positionals[0];
+    if (values.help === true || verb === undefined) {
+        out(USAGE);
+        return values.help === true ? OK : USAGE_ERROR;
+    }
+    if (verb !== 'look' && verb !== 'q' && verb !== 'diff' && verb !== 'capture') {
+        return fail(USAGE_ERROR, `dnumb: unknown verb "${verb}". Known: look, diff, capture, q <${query_js_1.Q_VERBS.join(' | ')}>.`);
+    }
+    // `capture` is the one verb with a browser in it and no bundle to read, so
+    // it is dispatched before `--from` is required of everything else.
+    if (verb === 'capture') {
+        return runCapture(positionals.slice(1), values, values.json === true);
+    }
+    let options;
+    try {
+        options = optionsFrom(values);
+    }
+    catch (error) {
+        if (error instanceof query_js_1.QueryError)
+            return fail(USAGE_ERROR, `dnumb: ${error.message}`);
+        throw error;
+    }
+    if (typeof values.from !== 'string' || values.from === '') {
+        return fail(USAGE_ERROR, 'dnumb: --from <bundle> is required. Every verb but `capture` reads a capture bundle; ' +
+            'there is no browser in this command. Use `dnumb capture <url>` to create one.');
+    }
+    const bundle = readBundle(values.from);
+    if (typeof bundle === 'number')
+        return bundle;
+    if (verb === 'diff') {
+        const otherPath = positionals[1];
+        if (otherPath === undefined) {
+            return fail(USAGE_ERROR, 'dnumb: diff needs a second bundle: dnumb --from before.json diff after.json');
+        }
+        const other = readBundle(otherPath);
+        if (typeof other === 'number')
+            return other;
+        let result;
+        try {
+            result = (0, index_js_1.diffCaptures)(bundle, other, {
+                beforeName: bundle.name,
+                afterName: other.name,
+                // `--help` documents `--limit 0` as "0 for all", matching `query.ts`'s
+                // own `cap()` precedent (`limit <= 0` shows everything). `renderDiff`
+                // (`src/diff/render.ts`) does not itself treat 0 that way -- it takes
+                // `maxLines` at face value, so `maxLines: 0` caps the body to zero
+                // lines and prints only the "not listed" notice (B6). `Infinity` is a
+                // cap `body.length` can never exceed, so it reads as "no cap" to the
+                // exact same `shown.length > maxLines` check without this file
+                // reaching into that module to change what it does with the number.
+                ...(options.limit === undefined
+                    ? {}
+                    : { maxLines: options.limit <= 0 ? Number.POSITIVE_INFINITY : options.limit }),
+            });
+        }
+        catch (error) {
+            // Comparing two viewports measures the viewport, not the change --
+            // `diffCaptures` itself refuses this now (`DiffViewportMismatchError`,
+            // worded identically to what this file used to check for itself), so a
+            // second guard here would be a second place deciding what this
+            // measurement means, which is the exact mistake this file's own header
+            // comment rules out.
+            if (error instanceof index_js_1.DiffViewportMismatchError) {
+                return fail(USAGE_ERROR, error.message);
+            }
+            throw error;
+        }
+        // `--limit` already caps `result.text`'s body (`diffCaptures` ->
+        // `renderDiff`); `--json` used to ignore it and always emit every change
+        // regardless, so an agent that passed `--limit` to bound its context got
+        // an unbounded payload back with no sign the flag did nothing.
+        // `result.truncated` already means something else -- whether either
+        // *source capture* hit the 5000-element cap -- so the count `--limit`
+        // itself left out gets its own key, `changesOmitted`, rather than
+        // overloading a key that already answers a different question.
+        //
+        // `reportableChanges` (above) is the fix for B5: capping the raw,
+        // unsorted `result.changes` -- which still carries every `subsumed`
+        // change the text never prints -- against a `maxLines` that bounds text
+        // *lines* gave `--limit 1` a "complete" text diff and a `changesOmitted`
+        // in the double digits on the same response. Capping the same
+        // live-and-sorted list the text is built from keeps the two answering
+        // the same question about the same diff.
+        const reportable = reportableChanges(result.changes);
+        const limit = options.limit;
+        const capChanges = limit !== undefined && limit > 0;
+        const changes = capChanges ? reportable.slice(0, limit) : reportable;
+        const changesOmitted = capChanges ? reportable.length - changes.length : 0;
+        out(values.json === true
+            ? `${JSON.stringify({
+                verb: 'diff',
+                before: bundle.name,
+                after: other.name,
+                truncated: result.truncated,
+                changesOmitted,
+                changes,
+            }, null, 2)}\n`
+            : `${result.text}\n`);
+        return OK;
+    }
+    try {
+        const result = verb === 'look'
+            ? (0, query_js_1.look)(bundle, options)
+            : (0, query_js_1.query)(bundle, positionals[1] ?? '', positionals.slice(2), options);
+        // `docs/notes/07-refusal.md` §2/§7: `look --json` gains `sparseCapture`
+        // so a programmatic caller can branch without string-matching the
+        // digest text. Read off the rendered text's own marker rather than
+        // recomputing the gate here -- `renderDigest` already decided this once
+        // (`elements >= 20 && dropped/total >= 0.9 && page.height <= 2`), and
+        // re-deriving it a second time in this file is exactly the "two places
+        // that decide what a bundle looks like" failure mode this file's own
+        // header comment warns against, one level up. `query`'s other verbs
+        // (`q ...`) are untouched -- the gate governs `look`'s default body
+        // only, not what `q facts`/`q describe`/`q find` return.
+        const json = verb === 'look' && result.json !== null && typeof result.json === 'object'
+            ? { ...result.json, sparseCapture: result.text.includes(index_js_2.SPARSE_CAPTURE_MARKER) }
+            : result.json;
+        out(values.json === true ? `${JSON.stringify(json, null, 2)}\n` : `${result.text}\n`);
+        return OK;
+    }
+    catch (error) {
+        if (error instanceof query_js_1.QueryError)
+            return fail(USAGE_ERROR, `dnumb: ${error.message}`);
+        throw error;
+    }
+}
+// `main` returns a plain number for every verb except `capture`, which needs
+// a browser and a network round trip. Handling both shapes here — rather than
+// making every verb async — keeps the exit code synchronous for the common
+// case and lets tests call `main()` and read `.code` back immediately.
+const mainResult = main();
+if (mainResult instanceof Promise) {
+    mainResult.then((code) => {
+        process.exitCode = code;
+    });
+}
+else {
+    process.exitCode = mainResult;
+}