cssgrep 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 matias
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# cssgrep
+
+Search HTML by CSS selector and print each match, grep-style — add `-n` to
+report it as `file:line:col`.
+
+Unlike most HTML query tools, `cssgrep` tracks the **source position** of every
+matched node — so it works even on minified, single-line HTML, and (with `-n`)
+its output plugs straight into grep-aware editors.
+
+## Install
+
+From npm (requires Node ≥ 20.19):
+
+```sh
+npm install -g cssgrep
+```
+
+Or from a clone, for development:
+
+```sh
+npm install        # install deps
+npm link           # put `cssgrep` on your PATH (optional)
+```
+
+Check the installed version with `cssgrep --version`. A global install also
+puts a man page on your `MANPATH`, so `man cssgrep` works; from a clone, read it
+with `man ./man/cssgrep.1`.
+
+### Standalone binary (no Node required)
+
+Each release ships self-contained executables — download the one for your
+platform, `chmod +x`, and run it; no Node install needed. To build them yourself
+you need [Bun](https://bun.sh) (used only as a build tool — the project still
+runs on plain Node):
+
+```sh
+bun --version           # https://bun.sh
+npm run build:binaries  # writes dist/cssgrep-{linux,darwin}-{x64,arm64} and -windows-x64.exe
+```
+
+Bun cross-compiles all targets from one machine, so this is what CI uses to
+produce release artifacts. `npm run build:linux-x64` (etc.) builds a single
+target.
+
+If you'd rather not install Bun, `npm run build:sea` produces a binary using
+[Node's built-in SEA](https://nodejs.org/api/single-executable-applications.html)
+(needs the `esbuild`/`postject` devDependencies). The catch: Node SEA **cannot
+cross-compile** — it embeds the node you run it with, so you only get a binary
+for the current OS and architecture. Bun is the better choice for multi-platform
+releases.
+
+## Usage
+
+```sh
+cssgrep <selector> [file ...]      # search the given files
+cssgrep <selector> -r <dir ...>    # recurse directories
+cat page.html | cssgrep <selector> # read from stdin
+```
+
+Output, one line per match. Like `grep`, the matched line is printed on its own;
+a `file:` prefix is added when searching multiple files, and the `line:col`
+locator appears only with `-n`:
+
+```
+{line contents}                         # default; stdin or single file
+{file}:{line contents}                  # default; multiple files
+{line}:{col} {line contents}            # -n; stdin or single file
+{file}:{line}:{col} {line contents}     # -n; multiple files
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-r`, `--recursive` | Recurse into directory arguments (defaults to `.` if none given). |
+| `--ext <list>` | Extensions to scan with `-r` (default `html,htm`). Value attaches with `=`: `--ext htm` or `--ext=htm`. |
+| `-i`, `--ignore <glob>` | Skip files/dirs matching `<glob>` while recursing (repeatable). `node_modules`, `*.min.html`, `build/` (dir-only), or path globs like `src/vendor/**`. |
+| `--ignore-file <path>` | Load ignore globs from a file, one per line (`#` comments and blank lines ignored) — like a `.gitignore`. |
+| `-n`, `--line-number` | Prefix each match with its `line:col` locator. Mutually exclusive with `-c` and `-p`. |
+| `-p`, `--print` | Pretty-print the matched node's HTML, re-indented from scratch (works on minified input). No `line:col` locator is shown. |
+| `--attr <name>` | Print the value of attribute `<name>` for each match (nodes without it are skipped). Honors `-n` and `-w`. |
+| `--text` | Print the matched node's text content, whitespace collapsed. Honors `-n` and `-w`. |
+| `--json` | Print one JSON object per match (NDJSON), with `file`, `line`, `col`, `html`, `text`. |
+| `--parent <n>` | Report the `n`-th element ancestor of each match instead of the match itself (de-duplicated). Pairs well with `-p`. |
+| `-w`, `--max-width <n>` | Truncate the shown line to `n` columns (adds `…`). Value attaches or follows: `-w100`, `-w 100`, `--max-width=100`. |
+| `-A`, `--after-context <n>` | Print `n` source lines after each match. |
+| `-B`, `--before-context <n>` | Print `n` source lines before each match. |
+| `-C`, `--context <n>` | Print `n` source lines before and after each match. |
+| `-m`, `--max-count <n>` | Stop after `n` matches per file (caps `-c` too). |
+| `-M`, `--max-total <n>` | Stop after `n` matches in total across all files. |
+| `-c`, `--count` | Print only the match count (per file when relevant). |
+| `-l`, `--files-with-matches` | Print only the names of files that contain a match. |
+| `-L`, `--files-without-match` | Print only the names of files with no match. |
+| `-q`, `--quiet` | Print nothing; exit `0` on the first match, `1` if none. Stops early. |
+| `-0`, `--null` | Output a NUL after each file name instead of `:` (or, with `-l`/`-L`, instead of the newline) — pipe to `xargs -0`. |
+| `--color[=<when>]` | Colorize output: `auto` (default — color only when stdout is a terminal), `always`, or `never`. A bare `--color` means `always`. |
+| `-h`, `--help` | Show help. |
+| `-V`, `--version` | Print the version and exit. |
+
+Boolean short flags can be combined into one token (`-rn` is `-r -n`), and a
+value-taking flag may close such a cluster (`-rnw100`).
+
+When coloring is on, the matched node is highlighted within its line (grep's
+bold-red); the `file:` prefix and `line:col` locator get their own colors
+(magenta and green, like grep). Plain `-p` prints no color (the whole block is
+the match), but `-p --parent <n>` highlights the original matched node inside
+the printed container, so you can see what matched within its surroundings.
+
+Exit status: `0` if any match was found, `1` if none, `2` on error — same
+convention as `grep`.
+
+The selector and paths can appear in any order — `cssgrep -r src 'div.a'` and
+`cssgrep 'div.a' -r src` are equivalent. The selector is whichever argument
+doesn't name an existing file or directory.
+
+### Examples
+
+```sh
+cssgrep 'a[href^="https"]' testdata/links.html
+cssgrep 'div.card > h2' -r src/ -w 100
+cssgrep 'form input[required]' templates/*.html -c
+curl -s https://example.com | cssgrep 'p a'
+
+# extraction — print attribute values or text instead of source lines
+cssgrep 'a' --attr href testdata/links.html   # every link target
+cssgrep 'h1, h2' --text -r src/               # all heading text
+cssgrep 'img' -l -r .                          # files that contain an <img>
+
+# structural context — show the container the match lives in
+cssgrep '.price' -p --parent 1 testdata/cards.html  # pretty-print each price's card
+
+# ignore noise while recursing
+cssgrep 'script' -r . -i node_modules -i '*.min.html'
+cssgrep 'a' -r . --ignore-file .gitignore
+```
+
+### Structural context (`--parent`)
+
+`--parent <n>` re-targets each match to its `n`-th element ancestor before
+printing — structural context that line-based `-A`/`-B` can't express. Shared
+ancestors are de-duplicated, so `cssgrep '.price' --parent 1 -p` prints each
+containing card once. It composes with every print mode (`-p`, `--attr`,
+`--text`, `--json`, or the default line output).
+
+## Vim / Neovim integration
+
+The `file:line:col text` format produced by `-n` is `:grep`-compatible. Point
+`grepprg` at `cssgrep -n -r` and hits land in the quickfix list:
+
+```vim
+set grepprg=cssgrep\ -n\ -r
+set grepformat=%f:%l:%c\ %m
+
+" :grep 'div.card' src/   then  :copen
+```
+
+For a single buffer's HTML:
+
+```vim
+:cexpr system('cssgrep -n ' . shellescape(input('selector> ')) . ' ' . shellescape(expand('%')))
+```
+
+## Shell completions
+
+Completions for every flag ship in [`completions/`](completions/). Install the
+one for your shell (a global install puts them under
+`"$(npm root -g)/cssgrep/completions/"`):
+
+```sh
+# bash — source it, or copy to your bash-completion completions dir as `cssgrep`
+source completions/cssgrep.bash
+
+# zsh — drop `_cssgrep` onto your $fpath, then run compinit
+cp completions/_cssgrep ~/.zsh/completions/   # a dir on your $fpath
+
+# fish
+cp completions/cssgrep.fish ~/.config/fish/completions/
+```
+
+(The completions are hand-maintained; keep them in step with `--help` if you add
+a flag.)
+
+## How it works
+
+- [`htmlparser2`](https://github.com/fb55/htmlparser2) parses with
+  `withStartIndices`, recording each node's byte offset into the source.
+- [`css-select`](https://github.com/fb55/css-select) matches the selector
+  against that DOM (the same engine cheerio uses).
+- Offsets are converted to 1-based `line:col` via a precomputed line index;
+  `col` points at the opening `<` of the matched tag.

package/completions/_cssgrep

@@ -0,0 +1,35 @@
+#compdef cssgrep
+# zsh completion for cssgrep. Keep in sync with the USAGE string in index.js.
+# Install: place this file (named _cssgrep) in a directory on your $fpath, then
+# ensure `autoload -U compinit && compinit` runs in your ~/.zshrc.
+
+_cssgrep() {
+  _arguments -s -S \
+    '(-r --recursive)'{-r,--recursive}'[recurse into directory arguments]' \
+    '--ext[extensions to scan with -r]:extensions (comma-separated):' \
+    '*'{-i,--ignore}'[skip files/dirs matching glob while recursing]:glob:' \
+    '--ignore-file[read ignore globs from a file]:file:_files' \
+    '(-n --line-number)'{-n,--line-number}'[prefix each match with line:col]' \
+    '(-p --print)'{-p,--print}'[pretty-print the matched node HTML]' \
+    '--attr[print the value of an attribute]:attribute name:' \
+    '--text[print the matched node text content]' \
+    '--json[print one JSON object per match (NDJSON)]' \
+    '--parent[report the n-th ancestor of each match]:depth:' \
+    '(-w --max-width)'{-w,--max-width}'[truncate shown line to n columns]:columns:' \
+    '(-A --after-context)'{-A,--after-context}'[print n lines after each match]:lines:' \
+    '(-B --before-context)'{-B,--before-context}'[print n lines before each match]:lines:' \
+    '(-C --context)'{-C,--context}'[print n lines around each match]:lines:' \
+    '(-m --max-count)'{-m,--max-count}'[stop after n matches per file]:count:' \
+    '(-M --max-total)'{-M,--max-total}'[stop after n matches in total]:count:' \
+    '(-c --count)'{-c,--count}'[print only a count of matches]' \
+    '(-l --files-with-matches)'{-l,--files-with-matches}'[print only names of files with a match]' \
+    '(-L --files-without-match)'{-L,--files-without-match}'[print only names of files without a match]' \
+    '(-q --quiet)'{-q,--quiet}'[print nothing; exit on first match]' \
+    '(-0 --null)'{-0,--null}'[separate the file name with a NUL byte]' \
+    '--color=-[colorize output]::when:(auto always never)' \
+    '(-h --help)'{-h,--help}'[show help and exit]' \
+    '(-V --version)'{-V,--version}'[show version and exit]' \
+    '*:file:_files'
+}
+
+_cssgrep "$@"

package/completions/cssgrep.bash

@@ -0,0 +1,40 @@
+# bash completion for cssgrep. Keep the flag list in sync with the USAGE string
+# in index.js. Install: `source` this file from your ~/.bashrc, or drop it into
+# your bash-completion completions directory renamed to `cssgrep`.
+_cssgrep() {
+    local cur prev opts
+    cur="${COMP_WORDS[COMP_CWORD]}"
+    prev="${COMP_WORDS[COMP_CWORD-1]}"
+
+    opts="-r --recursive --ext -i --ignore --ignore-file -n --line-number \
+-p --print --attr --text --json --parent -w --max-width \
+-A --after-context -B --before-context -C --context \
+-m --max-count -M --max-total -c --count \
+-l --files-with-matches -L --files-without-match -q --quiet -0 --null \
+--color -h --help -V --version"
+
+    case "$prev" in
+        --color)
+            COMPREPLY=( $(compgen -W "auto always never" -- "$cur") )
+            return 0
+            ;;
+        --ignore-file)
+            COMPREPLY=( $(compgen -f -- "$cur") )
+            return 0
+            ;;
+        --ext|-i|--ignore|--attr|--parent|-w|--max-width|-A|--after-context|\
+-B|--before-context|-C|--context|-m|--max-count|-M|--max-total)
+            # value-taking flag with no enumerable completion; offer nothing
+            return 0
+            ;;
+    esac
+
+    if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
+        return 0
+    fi
+
+    COMPREPLY=( $(compgen -f -- "$cur") )
+    return 0
+}
+complete -F _cssgrep cssgrep

package/completions/cssgrep.fish

@@ -0,0 +1,27 @@
+# fish completion for cssgrep. Keep in sync with the USAGE string in index.js.
+# Install: place this file in ~/.config/fish/completions/ (named cssgrep.fish).
+
+complete -c cssgrep -s r -l recursive -d 'Recurse into directory arguments'
+complete -c cssgrep -l ext -x -d 'Extensions to scan with -r (comma-separated)'
+complete -c cssgrep -s i -l ignore -x -d 'Skip files/dirs matching glob while recursing'
+complete -c cssgrep -l ignore-file -r -F -d 'Read ignore globs from a file'
+complete -c cssgrep -s n -l line-number -d 'Prefix each match with line:col'
+complete -c cssgrep -s p -l print -d 'Pretty-print the matched node HTML'
+complete -c cssgrep -l attr -x -d 'Print the value of an attribute'
+complete -c cssgrep -l text -d 'Print the matched node text content'
+complete -c cssgrep -l json -d 'Print one JSON object per match (NDJSON)'
+complete -c cssgrep -l parent -x -d 'Report the n-th ancestor of each match'
+complete -c cssgrep -s w -l max-width -x -d 'Truncate shown line to n columns'
+complete -c cssgrep -s A -l after-context -x -d 'Print n lines after each match'
+complete -c cssgrep -s B -l before-context -x -d 'Print n lines before each match'
+complete -c cssgrep -s C -l context -x -d 'Print n lines around each match'
+complete -c cssgrep -s m -l max-count -x -d 'Stop after n matches per file'
+complete -c cssgrep -s M -l max-total -x -d 'Stop after n matches in total'
+complete -c cssgrep -s c -l count -d 'Print only a count of matches'
+complete -c cssgrep -s l -l files-with-matches -d 'Print only names of files with a match'
+complete -c cssgrep -s L -l files-without-match -d 'Print only names of files without a match'
+complete -c cssgrep -s q -l quiet -d 'Print nothing; exit on first match'
+complete -c cssgrep -s 0 -l null -d 'Separate the file name with a NUL byte'
+complete -c cssgrep -l color -x -a 'auto always never' -d 'Colorize output'
+complete -c cssgrep -s h -l help -d 'Show help and exit'
+complete -c cssgrep -s V -l version -d 'Show version and exit'

package/index.js

@@ -0,0 +1,738 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseDocument } = require('htmlparser2');
+const { selectAll } = require('css-select');
+const render = require('dom-serializer').default;
+const { html: beautify } = require('js-beautify');
+
+// Single source of truth for the version. A constant rather than a read of
+// package.json, so it survives compilation into a standalone binary (Bun
+// --compile / Node SEA), where package.json won't sit next to the executable.
+// Keep in sync with package.json on release.
+const VERSION = '1.0.0';
+
+const USAGE = `cssgrep - search HTML by CSS selector, grep-style.
+
+Usage:
+  cssgrep <selector> [file ...]
+  cssgrep <selector> -r <dir ...>
+  cat file.html | cssgrep <selector>
+
+Output (one line per match):
+  {line contents}                           (default; stdin or single file)
+  {file}:{line contents}                    (default; multiple files)
+  {line}:{col} {line contents}              (with -n; stdin or single file)
+  {file}:{line}:{col} {line contents}       (with -n; multiple files)
+
+Options:
+  -r, --recursive        Recurse into directory arguments.
+      --ext <list>       Comma-separated extensions for -r (default: html,htm).
+  -i, --ignore <glob>    Skip files/dirs matching <glob> when recursing (repeatable).
+      --ignore-file <path>   Read ignore globs from <path> (one per line, # comments).
+  -n, --line-number      Prefix each match with its line:col (excludes -c, -p).
+  -p, --print            Pretty-print the matched node's HTML above its location.
+      --attr <name>      Print the value of attribute <name> (skips nodes without it).
+      --text             Print the matched node's text content (whitespace collapsed).
+      --json             Print one JSON record per match (NDJSON: file,line,col,html,text).
+      --parent <n>       Report the n-th ancestor of each match instead (dedup'd).
+  -w, --max-width <n>    Truncate the shown line to <n> columns (ellipsis added).
+  -A, --after-context <n>    Print <n> source lines after each match.
+  -B, --before-context <n>   Print <n> source lines before each match.
+  -C, --context <n>          Print <n> source lines before and after each match.
+  -m, --max-count <n>    Stop after <n> matches per file.
+  -M, --max-total <n>    Stop after <n> matches in total (across all files).
+  -c, --count            Print only a count of matches (per file when relevant).
+  -l, --files-with-matches   Print only the names of files that have a match.
+  -L, --files-without-match  Print only the names of files with no match.
+  -q, --quiet            Print nothing; exit 0 on first match, 1 if none.
+  -0, --null             Separate the file name with a NUL byte (for xargs -0).
+      --color[=<when>]   Colorize output: auto (default), always or never.
+  -h, --help             Show this help.
+  -V, --version          Show version and exit.
+
+Short flags combine (-rn) and a value attaches to its flag (-w100) or follows it
+(-w 100); a value-taking flag may close a cluster (-rnw100). Long options take a
+value with = or as the next word (--max-width=100, --ext htm).
+
+Exit status: 0 if any match was found, 1 if none, 2 on error.`;
+
+function fail(msg) {
+  process.stderr.write(`cssgrep: ${msg}\n`);
+  process.exit(2);
+}
+
+// ANSI SGR codes matching grep's default scheme: bold-red match, magenta
+// filename, green line/col numbers, cyan separators.
+const COLORS = {
+  match: '1;31',
+  file: '35',
+  line: '32',
+  sep: '36',
+};
+
+function paint(code, str) {
+  return `\x1b[${code}m${str}\x1b[0m`;
+}
+
+function parseArgs(argv) {
+  const opts = {
+    selector: null,
+    positionals: [],
+    paths: [],
+    recursive: false,
+    exts: ['html', 'htm'],
+    lineNumber: false,
+    print: false,
+    maxWidth: 0,
+    maxCount: 0,
+    maxTotal: 0,
+    count: false,
+    filesWithMatches: false,
+    filesWithoutMatch: false,
+    quiet: false,
+    attr: null,
+    text: false,
+    json: false,
+    nul: false,
+    parent: 0,
+    before: 0,
+    after: 0,
+    ignore: [],
+    color: 'auto',
+  };
+  const setExts = v => {
+    opts.exts = (v || '').split(',').map(s => s.trim().replace(/^\./, '')).filter(Boolean);
+  };
+  const boundedInt = (v, what, min) => {
+    const n = parseInt(v, 10);
+    if (!Number.isFinite(n) || n < min) fail(`invalid ${what} value`);
+    return n;
+  };
+  const positiveInt = (v, what) => boundedInt(v, what, 1);
+  const setMaxWidth = v => { opts.maxWidth = positiveInt(v, '--max-width'); };
+  const setMaxCount = v => { opts.maxCount = positiveInt(v, '--max-count'); };
+  const setMaxTotal = v => { opts.maxTotal = positiveInt(v, '--max-total'); };
+  const setParent = v => { opts.parent = positiveInt(v, '--parent'); };
+  const setAfter = v => { opts.after = boundedInt(v, '--after-context', 0); };
+  const setBefore = v => { opts.before = boundedInt(v, '--before-context', 0); };
+  const setContext = v => { opts.after = opts.before = boundedInt(v, '--context', 0); };
+  const addIgnore = v => { const c = compileIgnore(v); if (c) opts.ignore.push(c); };
+  const addIgnoreFile = v => {
+    let content;
+    try { content = fs.readFileSync(v, 'utf8'); }
+    catch (e) { fail(`cannot read ignore file: ${v}`); }
+    for (const line of content.split('\n')) { const c = compileIgnore(line); if (c) opts.ignore.push(c); }
+  };
+  // Short flags that take a value (rest of the cluster, or the next argument).
+  const shortValueFlags = {
+    w: setMaxWidth, m: setMaxCount, M: setMaxTotal, A: setAfter, B: setBefore, C: setContext,
+    i: addIgnore,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+
+    // Long options: --name or --name=value. A missing inline value is taken
+    // from the next argument (except --color, where a bare flag means "always").
+    if (a.startsWith('--') && a.length > 2) {
+      const eq = a.indexOf('=');
+      const name = eq === -1 ? a : a.slice(0, eq);
+      const inline = eq === -1 ? null : a.slice(eq + 1);
+      const value = () => (inline != null ? inline : argv[++i]);
+      switch (name) {
+        case '--help': process.stdout.write(USAGE + '\n'); process.exit(0); break;
+        case '--version': process.stdout.write(`cssgrep ${VERSION}\n`); process.exit(0); break;
+        case '--recursive': opts.recursive = true; break;
+        case '--line-number': opts.lineNumber = true; break;
+        case '--print': opts.print = true; break;
+        case '--count': opts.count = true; break;
+        case '--files-with-matches': opts.filesWithMatches = true; break;
+        case '--files-without-match': opts.filesWithoutMatch = true; break;
+        case '--quiet': case '--silent': opts.quiet = true; break;
+        case '--null': opts.nul = true; break;
+        case '--ext': setExts(value()); break;
+        case '--ignore': addIgnore(value()); break;
+        case '--ignore-file': addIgnoreFile(value()); break;
+        case '--max-width': setMaxWidth(value()); break;
+        case '--max-count': setMaxCount(value()); break;
+        case '--max-total': setMaxTotal(value()); break;
+        case '--attr': opts.attr = value(); break;
+        case '--text': opts.text = true; break;
+        case '--json': opts.json = true; break;
+        case '--parent': setParent(value()); break;
+        case '--after-context': setAfter(value()); break;
+        case '--before-context': setBefore(value()); break;
+        case '--context': setContext(value()); break;
+        case '--color': case '--colour': opts.color = inline != null ? inline : 'always'; break;
+        default: fail(`unknown option: ${name}`);
+      }
+      continue;
+    }
+
+    // Short options, getopt-style: flags cluster (`-rn`) and a value-taking
+    // option consumes the rest of the cluster (`-w100`) or the next argument
+    // (`-w 100`), which means it must come last in a cluster (`-rnw100`).
+    if (a.startsWith('-') && a !== '-') {
+      for (let j = 1; j < a.length; j++) {
+        const ch = a[j];
+        if (shortValueFlags[ch]) {
+          const rest = a.slice(j + 1);          // attached value, if any
+          shortValueFlags[ch](rest !== '' ? rest : argv[++i]);
+          break;                                // value swallowed the cluster tail
+        }
+        switch (ch) {
+          case 'h': process.stdout.write(USAGE + '\n'); process.exit(0); break;
+          case 'V': process.stdout.write(`cssgrep ${VERSION}\n`); process.exit(0); break;
+          case 'r': opts.recursive = true; break;
+          case 'n': opts.lineNumber = true; break;
+          case 'p': opts.print = true; break;
+          case 'c': opts.count = true; break;
+          case 'l': opts.filesWithMatches = true; break;
+          case 'L': opts.filesWithoutMatch = true; break;
+          case 'q': opts.quiet = true; break;
+          case '0': case 'Z': opts.nul = true; break;
+          default: fail(`unknown option: -${ch}`);
+        }
+      }
+      continue;
+    }
+
+    opts.positionals.push(a);
+  }
+  if (opts.positionals.length === 0) fail('no selector given (try --help)');
+  // Aggregate modes each suppress per-match output, so at most one may apply.
+  const aggregates = [opts.count, opts.filesWithMatches, opts.filesWithoutMatch, opts.quiet]
+    .filter(Boolean).length;
+  if (aggregates > 1) fail('only one of -c, -l, -L, -q may be given');
+  // Per-match print modes choose what is printed for each match; only one.
+  const printModes = [opts.print, opts.attr != null, opts.text, opts.json].filter(Boolean).length;
+  if (printModes > 1) fail('only one of -p, --attr, --text, --json may be given');
+  // Context surrounds source lines, so it only makes sense for the default line
+  // output — not the print modes or the content-suppressing aggregate modes.
+  if (opts.before > 0 || opts.after > 0) {
+    if (printModes > 0) fail('context (-A/-B/-C) cannot be combined with -p/--attr/--text/--json');
+    if (aggregates > 0) fail('context (-A/-B/-C) cannot be combined with -c/-l/-L/-q');
+  }
+  if (opts.lineNumber && opts.count) fail('-n cannot be combined with -c');
+  if (opts.lineNumber && opts.print) fail('-n cannot be combined with -p');
+  if (!['auto', 'always', 'never'].includes(opts.color)) {
+    fail(`invalid --color value: ${opts.color} (expected auto, always or never)`);
+  }
+  // Resolve the tri-state into a single boolean: color only when forced on, or
+  // 'auto' and stdout is an interactive terminal. Plain -p still prints no
+  // color (it has nothing to highlight) — that's gated where it prints, not
+  // here, so --parent -p can highlight the matched node inside the container.
+  opts.colorOn = opts.color === 'always' || (opts.color === 'auto' && Boolean(process.stdout.isTTY));
+  return opts;
+}
+
+// The selector and the path list share the same positional slots, so their
+// order on the command line is ambiguous (`<selector> <dir>` vs `<dir>
+// <selector>`). Resolve it by what actually exists on disk: paths are the
+// positionals that name a real file/dir, and the selector is the one that
+// doesn't. This makes argument order not matter (important for vim's
+// `grepprg`, which appends args in its own order). Fall back to
+// "selector is the first positional" when the split is unclear.
+function resolveSelectorAndPaths(opts) {
+  const pos = opts.positionals;
+  const onDisk = [];
+  const notOnDisk = [];
+  for (const p of pos) {
+    if (fs.statSync(p, { throwIfNoEntry: false })) onDisk.push(p);
+    else notOnDisk.push(p);
+  }
+  if (notOnDisk.length === 1) {
+    opts.selector = notOnDisk[0];
+    opts.paths = onDisk;
+  } else {
+    // 0 non-existent (selector also happens to name a file) or several
+    // (a mistyped path, reported later): keep positional order.
+    opts.selector = pos[0];
+    opts.paths = pos.slice(1);
+  }
+}
+
+// Precompute the byte offset at which each line starts, so offset->line/col
+// is a binary search rather than a re-scan per match.
+function lineIndex(src) {
+  const starts = [0];
+  for (let i = 0; i < src.length; i++) {
+    if (src.charCodeAt(i) === 10 /* \n */) starts.push(i + 1);
+  }
+  return starts;
+}
+
+function offsetToPosition(starts, src, offset) {
+  // binary search for the greatest line start <= offset
+  let lo = 0, hi = starts.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (starts[mid] <= offset) lo = mid;
+    else hi = mid - 1;
+  }
+  const lineStart = starts[lo];
+  let lineEnd = src.indexOf('\n', lineStart);
+  if (lineEnd === -1) lineEnd = src.length;
+  // strip a trailing \r so CRLF files render cleanly
+  let text = src.slice(lineStart, lineEnd);
+  if (text.endsWith('\r')) text = text.slice(0, -1);
+  return {
+    line: lo + 1,            // 1-based
+    col: offset - lineStart + 1, // 1-based
+    text,
+  };
+}
+
+// Text of a 1-based line number, with the trailing \r stripped (CRLF), plus the
+// line's byte start (so a node's offset maps to a column within it).
+function lineTextAt(starts, src, lineNo) {
+  const lineStart = starts[lineNo - 1];
+  let lineEnd = src.indexOf('\n', lineStart);
+  if (lineEnd === -1) lineEnd = src.length;
+  let text = src.slice(lineStart, lineEnd);
+  if (text.endsWith('\r')) text = text.slice(0, -1);
+  return { lineStart, text };
+}
+
+function truncate(text, maxWidth) {
+  if (!maxWidth || text.length <= maxWidth) return text;
+  if (maxWidth <= 1) return text.slice(0, maxWidth);
+  return text.slice(0, maxWidth - 1) + '…'; // …
+}
+
+// Produce the visible match text: truncate first (so --max-width still measures
+// real columns, never escape sequences), then — when coloring — wrap the part
+// of the matched node that falls on this line in the match color. A node can
+// span multiple lines while we only print its opening line, so the highlight is
+// clamped to what's visible; a match scrolled past the truncation point isn't
+// highlighted at all (and the trailing ellipsis is never colored).
+function renderText(pos, off, nodeEnd, opts) {
+  const vis = truncate(pos.text, opts.maxWidth);
+  if (!opts.colorOn) return vis;
+  const truncated = opts.maxWidth && pos.text.length > opts.maxWidth;
+  const effLen = truncated ? Math.max(0, opts.maxWidth - 1) : vis.length;
+  let s = pos.col - 1;             // match start within the line (0-based)
+  let e = s + (nodeEnd - off);     // match end within the line
+  s = Math.max(0, Math.min(s, effLen));
+  e = Math.max(s, Math.min(e, effLen));
+  if (e <= s) return vis;          // nothing of the match is visible
+  return vis.slice(0, s) + paint(COLORS.match, vis.slice(s, e)) + vis.slice(e);
+}
+
+// Concatenate the text of a node and all its descendants (dependency-free,
+// rather than pulling in domutils). Used by --text.
+function textOf(node) {
+  if (node.type === 'text') return node.data || '';
+  if (!node.children) return '';
+  let s = '';
+  for (const child of node.children) s += textOf(child);
+  return s;
+}
+
+const collapseWs = s => s.replace(/\s+/g, ' ').trim();
+
+const isElement = n => n && (n.type === 'tag' || n.type === 'script' || n.type === 'style');
+
+// Climb n element levels from el, clamping at the document root.
+function ancestor(el, n) {
+  let node = el;
+  for (let k = 0; k < n; k++) {
+    if (!isElement(node.parent)) break;
+    node = node.parent;
+  }
+  return node;
+}
+
+// --parent re-points each match to its n-th ancestor; dedup by identity so a
+// shared container is reported once, preserving first-seen order.
+function retarget(nodes, opts) {
+  if (!opts.parent) return nodes;
+  const seen = new Set();
+  const result = [];
+  for (const el of nodes) {
+    const a = ancestor(el, opts.parent);
+    if (!seen.has(a)) { seen.add(a); result.push(a); }
+  }
+  return result;
+}
+
+// Sentinels marking where a highlighted node begins/ends. They are injected as
+// HTML *comment* nodes (not text) so js-beautify keeps the surrounding block
+// layout — text markers would make adjacent block elements collapse inline.
+// The private-use payload can't occur in real content, so it never collides.
+// After beautifying, each `<!--…-->` marker is swapped for an ANSI code.
+const HL_START = '';
+const HL_END = '';
+
+// Re-indent a matched node's HTML from scratch (so minified input still comes
+// out readable). dom-serializer turns the parsed node back into a string;
+// js-beautify does the formatting. When `origins` (descendant nodes to
+// highlight) is given and coloring is on, those nodes are wrapped in the match
+// color within the printed block.
+function prettyPrint(el, origins, opts) {
+  const highlight = origins && origins.length && opts && opts.colorOn;
+  const inserted = [];
+  if (highlight) {
+    // Bracket each origin with sentinel comment nodes among its siblings.
+    for (const m of origins) {
+      if (!m.parent) continue;
+      const kids = m.parent.children;
+      const i = kids.indexOf(m);
+      if (i < 0) continue;
+      const start = { type: 'comment', data: HL_START };
+      const end = { type: 'comment', data: HL_END };
+      kids.splice(i, 0, start);
+      kids.splice(i + 2, 0, end);
+      inserted.push({ kids, start, end });
+    }
+  }
+  let html;
+  try {
+    html = beautify(render(el, { encodeEntities: false }), {
+      indent_size: 2,
+      wrap_line_length: 0, // never wrap long lines (e.g. long text/attributes)
+      preserve_newlines: false,
+    });
+  } finally {
+    // Always restore the DOM so the markers don't leak into later matches.
+    for (const { kids, start, end } of inserted) {
+      let k = kids.indexOf(start); if (k >= 0) kids.splice(k, 1);
+      k = kids.indexOf(end); if (k >= 0) kids.splice(k, 1);
+    }
+  }
+  if (!highlight) return html;
+  const startCode = `\x1b[${COLORS.match}m`;
+  const resetCode = '\x1b[0m';
+  html = html
+    .replace(new RegExp(`<!--\\s*${HL_START}\\s*-->`, 'g'), startCode)
+    .replace(new RegExp(`<!--\\s*${HL_END}\\s*-->`, 'g'), resetCode);
+  return foldStandaloneCodes(html, startCode, resetCode);
+}
+
+// beautify sometimes parks a marker comment on its own line (e.g. when the
+// matched node followed source whitespace), leaving a line of just indent + a
+// zero-width ANSI code — a spurious blank line. Fold such a code onto the
+// adjacent content line: a start code onto the next line, a reset onto the
+// previous one.
+function foldStandaloneCodes(html, startCode, resetCode) {
+  const lines = html.split('\n');
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^([ \t]*)(\x1b\[[0-9;]*m)[ \t]*$/);
+    if (m) {
+      const code = m[2];
+      if (code === startCode && i + 1 < lines.length) {
+        lines[i + 1] = lines[i + 1].replace(/^[ \t]*/, ws => ws + startCode);
+        continue; // drop the standalone line
+      }
+      if (code === resetCode && out.length) {
+        out[out.length - 1] += resetCode;
+        continue;
+      }
+    }
+    out.push(lines[i]);
+  }
+  return out.join('\n');
+}
+
+// -A/-B/-C: emit each match line plus its surrounding context lines, grep-style.
+// Match lines use `:` field separators and keep the match-node highlight;
+// context lines use `-` and no highlight. Overlapping context windows merge,
+// and `--` separates non-contiguous groups.
+function emitContext(src, starts, name, showLabel, targets, opts, out) {
+  const label = showLabel ? name : null;
+  const c = opts.colorOn ? paint : (_, s) => s;
+  const lineCount = src.length === 0 ? 0 : (src.endsWith('\n') ? starts.length - 1 : starts.length);
+
+  // Map each match line to a representative node span (the first match on it),
+  // which drives the in-line highlight when coloring.
+  const info = new Map();
+  for (const el of targets) {
+    const off = el.startIndex == null ? 0 : el.startIndex;
+    const pos = offsetToPosition(starts, src, off);
+    if (info.has(pos.line)) continue;
+    const nodeEnd = (el.endIndex == null ? off : el.endIndex) + 1;
+    info.set(pos.line, { off, nodeEnd, pos });
+  }
+
+  // Expand match lines to [L-before, L+after] windows and merge adjacent ones.
+  const ranges = [];
+  for (const L of [...info.keys()].sort((a, b) => a - b)) {
+    const lo = Math.max(1, L - opts.before);
+    const hi = Math.min(lineCount, L + opts.after);
+    const last = ranges[ranges.length - 1];
+    if (last && lo <= last.hi + 1) last.hi = Math.max(last.hi, hi);
+    else ranges.push({ lo, hi });
+  }
+
+  let firstGroup = true;
+  for (const { lo, hi } of ranges) {
+    if (!firstGroup) out.push('--');
+    firstGroup = false;
+    for (let L = lo; L <= hi; L++) {
+      const m = info.get(L);
+      const sepColored = c(COLORS.sep, m ? ':' : '-');
+      let prefix = '';
+      if (label) prefix += c(COLORS.file, label) + (opts.nul ? '\0' : sepColored);
+      if (opts.lineNumber) {
+        prefix += c(COLORS.line, String(L));
+        prefix += m ? c(COLORS.sep, ':') + c(COLORS.line, String(m.pos.col)) + ' '
+                    : c(COLORS.sep, '-');
+      }
+      const body = m
+        ? renderText(m.pos, m.off, m.nodeEnd, opts)        // highlight + truncate
+        : truncate(lineTextAt(starts, src, L).text, opts.maxWidth);
+      out.push(prefix + body);
+    }
+  }
+}
+
+// `name` is the source's display name (file path, or "(standard input)"); it is
+// used by the aggregate modes (-l/-L/-c). `showLabel` decides whether per-match
+// lines carry a `file:` prefix (only when more than one file is searched).
+function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
+  const dom = parseDocument(src, {
+    withStartIndices: true,
+    withEndIndices: true,
+  });
+  const matches = selectAll(opts.selector, dom);
+  const found = matches.length;
+  // Aggregate modes suppress per-match output entirely.
+  if (opts.quiet) return found;                                  // status only
+  if (opts.filesWithMatches) { if (found) out.push(name); return found; }
+  if (opts.filesWithoutMatch) { if (!found) out.push(name); return found; }
+
+  const label = showLabel ? name : null;
+  // -m/--max-count caps matches per source; `limit` is the remaining global
+  // budget from -M/--max-total (Infinity when neither applies).
+  const cap = Math.min(opts.maxCount || Infinity, limit);
+  const limited = Number.isFinite(cap) ? matches.slice(0, cap) : matches;
+  if (opts.count) {
+    if (limited.length) {
+      const fileSep = opts.nul ? '\0' : ':';
+      out.push(label ? `${label}${fileSep}${limited.length}` : String(limited.length));
+    }
+    return limited.length;
+  }
+  const starts = opts.print ? null : lineIndex(src);
+  // --parent re-targets matches to ancestors (no-op without it). Aggregate
+  // modes above operate on the raw matches; targeting only affects what prints.
+  const targets = retarget(limited, opts);
+  // For --parent + -p, remember which original matches sit under each ancestor
+  // so they can be highlighted inside the printed container.
+  const originsByTarget = new Map();
+  if (opts.parent && opts.print) {
+    for (const el of limited) {
+      const a = ancestor(el, opts.parent);
+      if (!originsByTarget.has(a)) originsByTarget.set(a, []);
+      originsByTarget.get(a).push(el);
+    }
+  }
+  if (opts.before > 0 || opts.after > 0) {
+    emitContext(src, starts, name, showLabel, targets, opts, out);
+    return limited.length;
+  }
+  if (opts.json) {
+    // NDJSON: one self-contained record per match. `html` is the exact source
+    // slice; newlines are escaped by JSON.stringify, so each record stays on
+    // one line. Ignores --color and -n (line/col are always present).
+    for (const el of targets) {
+      const off = el.startIndex == null ? 0 : el.startIndex;
+      const pos = offsetToPosition(starts, src, off);
+      const nodeEnd = (el.endIndex == null ? off : el.endIndex) + 1;
+      out.push(JSON.stringify({
+        file: name,
+        line: pos.line,
+        col: pos.col,
+        html: src.slice(off, nodeEnd),
+        text: collapseWs(textOf(el)),
+      }));
+    }
+    return limited.length;
+  }
+  for (const el of targets) {
+    if (opts.print) {
+      // -p shows the re-indented node only; no line:col locator. With --parent,
+      // the original matched descendants are highlighted inside the container.
+      out.push(prettyPrint(el, originsByTarget.get(el), opts), ''); // blank separator
+      continue;
+    }
+    const off = el.startIndex == null ? 0 : el.startIndex;
+    const pos = offsetToPosition(starts, src, off);
+    const c = opts.colorOn ? paint : (_, s) => s;
+
+    // Choose the content printed for this match. --attr/--text replace the
+    // source line with the extracted value (whole value highlighted as the
+    // match); both honor -w truncation. Nodes lacking the attribute are skipped.
+    let text;
+    if (opts.attr != null) {
+      if (!el.attribs || !(opts.attr in el.attribs)) continue;
+      text = c(COLORS.match, truncate(el.attribs[opts.attr], opts.maxWidth));
+    } else if (opts.text) {
+      text = c(COLORS.match, truncate(collapseWs(textOf(el)), opts.maxWidth));
+    } else {
+      const nodeEnd = (el.endIndex == null ? off : el.endIndex) + 1; // exclusive
+      text = renderText(pos, off, nodeEnd, opts);
+    }
+    // grep-style: a `file:` prefix appears with multiple files; the line:col
+    // locator only with -n. The locator is separated from the text by a space
+    // so the output stays :grep-compatible (grepformat %f:%l:%c %m).
+    const sep = c(COLORS.sep, ':');
+    // -0/--null: the char after the file name becomes NUL (grep -Z), for
+    // unambiguous machine parsing (e.g. xargs -0).
+    const fileSep = opts.nul ? '\0' : sep;
+    let prefix = '';
+    if (label) prefix += c(COLORS.file, label) + fileSep;
+    if (opts.lineNumber) {
+      prefix += c(COLORS.line, String(pos.line)) + sep + c(COLORS.line, String(pos.col)) + ' ';
+    }
+    out.push(prefix + text);
+  }
+  return limited.length;
+}
+
+// Translate a glob to a regex body. `*` matches within a path segment, `**`
+// across segments, `?` a single non-slash char; everything else is literal.
+function globToRegex(glob) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {            // **  (crosses /)
+        re += '.*';
+        i++;
+        if (glob[i + 1] === '/') i++;       // consume the slash in **/
+      } else {
+        re += '[^/]*';
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+    } else if (/[.+^${}()|[\]\\]/.test(c)) {
+      re += '\\' + c;
+    } else {
+      re += c;
+    }
+  }
+  return re;
+}
+
+// Compile one ignore pattern (gitignore-flavored). A trailing `/` makes it
+// match directories only; a pattern containing `/` matches against the path
+// (anchored at a segment boundary), otherwise against the basename.
+function compileIgnore(pattern) {
+  const p = pattern.trim().replace(/\/$/, '');
+  if (!p || pattern.trim().startsWith('#')) return null;  // blank / comment line
+  const dirOnly = /\/$/.test(pattern.trim());
+  const hasSlash = p.includes('/');
+  const body = globToRegex(p);
+  const re = hasSlash ? new RegExp('(^|/)' + body + '$') : new RegExp('^' + body + '$');
+  return { re, dirOnly, hasSlash };
+}
+
+function isIgnored(name, full, isDir, matchers) {
+  for (const m of matchers) {
+    if (m.dirOnly && !isDir) continue;
+    if (m.re.test(m.hasSlash ? full : name)) return true;
+  }
+  return false;
+}
+
+function* walk(dir, opts) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (e) {
+    process.stderr.write(`cssgrep: ${dir}: ${e.code || e.message}\n`);
+    return;
+  }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    const isDir = e.isDirectory();
+    if (opts.ignore.length && isIgnored(e.name, full, isDir, opts.ignore)) continue;
+    if (isDir) {
+      yield* walk(full, opts);
+    } else if (e.isFile()) {
+      const ext = path.extname(e.name).slice(1).toLowerCase();
+      if (opts.exts.includes(ext)) yield full;
+    }
+  }
+}
+
+function readStdin() {
+  return fs.readFileSync(0, 'utf8');
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  resolveSelectorAndPaths(opts);
+
+  // Resolve the list of files to search.
+  let files = [];
+  let useStdin = false;
+  if (opts.recursive) {
+    // No path given with -r means "search here", like ripgrep.
+    const targets = opts.paths.length ? opts.paths : ['.'];
+    for (const p of targets) {
+      const st = fs.statSync(p, { throwIfNoEntry: false });
+      if (!st) { process.stderr.write(`cssgrep: ${p}: no such file or directory\n`); continue; }
+      if (st.isDirectory()) files.push(...walk(p, opts));
+      else files.push(p);
+    }
+  } else if (opts.paths.length > 0) {
+    files = opts.paths;
+  } else {
+    useStdin = true;
+  }
+
+  // A label (file prefix) is shown when searching more than one file.
+  const showLabel = !useStdin && files.length > 1;
+
+  const out = [];
+  let total = 0;
+
+  // -M/--max-total: remaining matches allowed across all files (Infinity = off).
+  const room = () => (opts.maxTotal ? Math.max(0, opts.maxTotal - total) : Infinity);
+
+  try {
+    if (useStdin) {
+      total += searchSource(readStdin(), '(standard input)', false, opts, out, room());
+    } else {
+      for (const f of files) {
+        if (room() <= 0) break;               // -M: global budget exhausted
+        let src;
+        try {
+          src = fs.readFileSync(f, 'utf8');
+        } catch (e) {
+          process.stderr.write(`cssgrep: ${f}: ${e.code || e.message}\n`);
+          continue;
+        }
+        total += searchSource(src, f, showLabel, opts, out, room());
+        if (opts.quiet && total > 0) break;   // -q: first match decides the status
+      }
+    }
+  } catch (e) {
+    if (e && e.message && /selector|tokeniz|parse/i.test(e.message)) {
+      fail(`invalid selector: ${opts.selector}`);
+    }
+    fail(e.message);
+  }
+
+  if (out.length) {
+    // For -l/-L, -0 NUL-terminates each file name (no newline) so the list is
+    // safe for `xargs -0`. Other modes keep newline-separated records (with -0
+    // the NUL appears only as the in-record file-name separator).
+    if (opts.nul && (opts.filesWithMatches || opts.filesWithoutMatch)) {
+      process.stdout.write(out.map(s => s + '\0').join(''));
+    } else {
+      process.stdout.write(out.join('\n') + '\n');
+    }
+  }
+  // Normally success means "a match was found". With -L it means "a file
+  // without a match was printed", which is decoupled from the match total.
+  const success = opts.filesWithoutMatch ? out.length > 0 : total > 0;
+  process.exit(success ? 0 : 1);
+}
+
+main();

package/man/cssgrep.1

@@ -0,0 +1,217 @@
+.\" Man page for cssgrep. Keep the OPTIONS section in sync with the USAGE
+.\" string in index.js.
+.TH CSSGREP 1 "2026-06-29" "cssgrep 1.0.0" "User Commands"
+.SH NAME
+cssgrep \- search HTML by CSS selector, grep-style
+.SH SYNOPSIS
+.B cssgrep
+.I selector
+.RI [ file ...]
+.br
+.B cssgrep
+.I selector
+.B \-r
+.IR dir ...
+.br
+.B cat
+.I file.html
+| \fBcssgrep\fR \fIselector\fR
+.SH DESCRIPTION
+.B cssgrep
+matches a CSS
+.I selector
+against parsed HTML and prints each hit grep-style. Unlike most HTML query
+tools it tracks the source byte offset of every matched node, so
+.B \-n
+reports an accurate
+.IR line : col
+even on minified, single-line HTML, and the output plugs straight into
+grep-aware editors (vim's
+.BR grepprg ).
+.PP
+Input is read from the
+.I file
+arguments, recursively from directories with
+.BR \-r ,
+or from standard input when no path is given. One line is printed per match.
+As with
+.BR grep ,
+the matched line is printed on its own; a
+.RI " file :"
+prefix is added when searching multiple files, and the
+.IR line : col
+locator appears only with
+.BR \-n .
+.SH OPTIONS
+.TP
+.BR \-r ", " \-\-recursive
+Recurse into directory arguments (defaults to the current directory if none
+are given).
+.TP
+.BI \-\-ext " list"
+Comma-separated extensions to scan with
+.B \-r
+(default:
+.IR html,htm ).
+.TP
+.BR \-i ", " \-\-ignore " \fIglob\fR"
+Skip files/dirs matching
+.I glob
+while recursing (repeatable).
+.TP
+.BI \-\-ignore\-file " path"
+Read ignore globs from
+.IR path ,
+one per line
+.RB ( #
+comments and blank lines ignored), like a
+.IR .gitignore .
+.TP
+.BR \-n ", " \-\-line\-number
+Prefix each match with its
+.IR line : col
+locator. Excludes
+.B \-c
+and
+.BR \-p .
+.TP
+.BR \-p ", " \-\-print
+Pretty-print the matched node's HTML, re-indented from scratch. No
+.IR line : col
+locator is shown.
+.TP
+.BI \-\-attr " name"
+Print the value of attribute
+.I name
+for each match (nodes without it are skipped).
+.TP
+.B \-\-text
+Print the matched node's text content, whitespace collapsed.
+.TP
+.B \-\-json
+Print one JSON object per match (NDJSON) with
+.IR file ", " line ", " col ", " html ", " text .
+.TP
+.BI \-\-parent " n"
+Report the
+.IR n -th
+element ancestor of each match instead of the match itself (de-duplicated).
+.TP
+.BR \-w ", " \-\-max\-width " \fIn\fR"
+Truncate the shown line to
+.I n
+columns (adds an ellipsis).
+.TP
+.BR \-A ", " \-\-after\-context " \fIn\fR"
+Print
+.I n
+source lines after each match.
+.TP
+.BR \-B ", " \-\-before\-context " \fIn\fR"
+Print
+.I n
+source lines before each match.
+.TP
+.BR \-C ", " \-\-context " \fIn\fR"
+Print
+.I n
+source lines before and after each match.
+.TP
+.BR \-m ", " \-\-max\-count " \fIn\fR"
+Stop after
+.I n
+matches per file.
+.TP
+.BR \-M ", " \-\-max\-total " \fIn\fR"
+Stop after
+.I n
+matches in total across all files.
+.TP
+.BR \-c ", " \-\-count
+Print only a count of matches (per file when relevant).
+.TP
+.BR \-l ", " \-\-files\-with\-matches
+Print only the names of files that have a match.
+.TP
+.BR \-L ", " \-\-files\-without\-match
+Print only the names of files with no match.
+.TP
+.BR \-q ", " \-\-quiet
+Print nothing; exit 0 on the first match, 1 if none.
+.TP
+.BR \-0 ", " \-\-null
+Separate the file name with a NUL byte (for
+.BR "xargs \-0" ).
+.TP
+.BR \-\-color [ =\fIwhen\fR ]
+Colorize output:
+.I auto
+(default),
+.IR always ", or " never .
+A bare
+.B \-\-color
+means
+.IR always .
+.TP
+.BR \-h ", " \-\-help
+Show help and exit.
+.TP
+.BR \-V ", " \-\-version
+Show version and exit.
+.PP
+Boolean short flags combine
+.RB ( \-rn
+is
+.BR "\-r \-n" ),
+and a value-taking flag may close such a cluster
+.RB ( \-rnw100 ).
+Long options take a value with
+.B =
+or as the next word
+.RB ( \-\-max\-width=100 ", " "\-\-ext htm" ).
+.SH EXIT STATUS
+.TP
+.B 0
+One or more matches were found.
+.TP
+.B 1
+No matches were found.
+.TP
+.B 2
+An error occurred (bad option, unreadable file, invalid selector).
+.SH EXAMPLES
+.TP
+Find every link in a page:
+.B cssgrep a page.html
+.TP
+Locate inputs with a locator, even in minified HTML:
+.B cssgrep \-n "input[name]" min.html
+.TP
+Recurse a tree, skipping vendored files:
+.B cssgrep \-rn .error \-i node_modules src/
+.TP
+Extract attribute values for scripting:
+.B cssgrep \-\-attr href "a.external" page.html
+.SH VIM INTEGRATION
+Wire
+.B cssgrep
+into vim's
+.B :grep
+by pointing
+.B grepprg
+at it and teaching
+.B grepformat
+the
+.IR file : line : col
+locator:
+.PP
+.RS
+.nf
+set grepprg=cssgrep\e \-n\e \-r
+set grepformat=%f:%l:%c\e %m
+.fi
+.RE
+.SH SEE ALSO
+.BR grep (1)
+.SH AUTHOR
+matias

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "cssgrep",
+  "version": "1.0.0",
+  "description": "Search HTML by CSS selector and print matches grep-style (file:line:col with -n).",
+  "main": "index.js",
+  "bin": {
+    "cssgrep": "index.js"
+  },
+  "man": "./man/cssgrep.1",
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE",
+    "man/cssgrep.1",
+    "completions/"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/msbatarce/cssgrep.git"
+  },
+  "bugs": {
+    "url": "https://github.com/msbatarce/cssgrep/issues"
+  },
+  "homepage": "https://github.com/msbatarce/cssgrep#readme",
+  "scripts": {
+    "test": "node test.js",
+    "build:linux-x64": "bun build ./index.js --compile --target=bun-linux-x64 --outfile dist/cssgrep-linux-x64",
+    "build:linux-arm64": "bun build ./index.js --compile --target=bun-linux-arm64 --outfile dist/cssgrep-linux-arm64",
+    "build:darwin-x64": "bun build ./index.js --compile --target=bun-darwin-x64 --outfile dist/cssgrep-darwin-x64",
+    "build:darwin-arm64": "bun build ./index.js --compile --target=bun-darwin-arm64 --outfile dist/cssgrep-darwin-arm64",
+    "build:windows-x64": "bun build ./index.js --compile --target=bun-windows-x64 --outfile dist/cssgrep-windows-x64.exe",
+    "build:binaries": "npm run build:linux-x64 && npm run build:linux-arm64 && npm run build:darwin-x64 && npm run build:darwin-arm64 && npm run build:windows-x64",
+    "build:sea": "node scripts/build-sea.js"
+  },
+  "keywords": [
+    "css",
+    "selector",
+    "html",
+    "grep",
+    "vim",
+    "cli"
+  ],
+  "author": "matias",
+  "license": "ISC",
+  "dependencies": {
+    "css-select": "^7.0.0",
+    "dom-serializer": "^3.1.1",
+    "htmlparser2": "^12.0.0",
+    "js-beautify": "^1.15.4"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0",
+    "postject": "^1.0.0-alpha.6"
+  }
+}