glimpse/AGENTS.md

Project Guidelines

Purpose

This project provides small Firefox/Selenium browser utilities packaged by Nix:

• glimpse - headless browser CLI with subcommands for page extraction, JS execution, screenshots, and search

Keep the tools simple, scriptable, and JSON-friendly.

Commands

Prefer relevant checks after changes because the full suite can take time:

npm run lint
npm run test:list
node test/smoke.js <tag-or-name>

For smoke testing without external network dependencies, use focused tags or scripts such as npm run test:wait, npm run test:errors, or node test/smoke.js reader js. Run npm test and nix build .#default --no-link when the change is broad, touches packaging, or needs full validation. Smoke tests require Firefox and geckodriver on PATH and use local data: HTML pages.

Do not attempt a live Kagi test unless KAGI_TOKEN is available.

CLI Conventions

• glimpse is the generic CLI and should use subcommands.
• Keep search as the glimpse search subcommand.
• Do not reintroduce a top-level --search flag to glimpse.
• Browser execution should be headless by default.
• Use --no-headless as the opt-out.
• Keep --url=<server> support for connecting to an existing WebDriver server.
• --timeout=<seconds> is a top-level option for command waits and defaults to 10.
• --wait-js=<code> and --wait-until=<state> are top-level wait options available to every glimpse subcommand.
• --js=<code> and --script=<file> are top-level options available to every glimpse subcommand and run before command-specific behavior.
• Prefer structured JSON output for objects/arrays.
• CLI errors should be structured JSON on stderr with ok: false, stable error.code, error.message, and elapsedMs.

Current glimpse subcommands:

• reader <url> - extract page content as Markdown (tries Firefox Reader View, falls back to raw Turndown conversion); supports --no-reader to skip Reader View, --format=json for structured output
• exec <url> --js=<code> or --script=<file> - execute JavaScript and return the result
• screenshot <url> --output=<file> - save a PNG screenshot
• search <query> - search with a supported provider and output JSON results
• serve - start a persistent browser server (geckodriver + Firefox) for faster repeat commands; auto-discovered via Unix socket, --stop to shut down, --status to check

Runtime Requirements

The Nix package must ensure both firefox and geckodriver are available to installed binaries. The current wrapper does this by prefixing PATH for glimpse.

If running outside Nix, document that Firefox and geckodriver must be on PATH.

Code Style

• Use TypeScript with ES modules; source lives in src/**/*.ts and builds to dist/.
• Keep code direct and minimal; avoid abstractions until they are needed.
• Add short Title Case comments above cohesive logic blocks.
• Prefer exact, actionable error messages.
• Keep command-line parsing simple unless a real need for a parser library appears.

Nix Notes

• Update npmDepsHash whenever package-lock.json changes.
• Keep the source filter excluding .git, .direnv, node_modules, and result.
• packages.default should contain glimpse.
• apps.default should run glimpse.

Kagi Notes

Kagi search requires --token=<token> or KAGI_TOKEN. The token is validated by the Kagi provider and passed to Kagi as the token query parameter. The agent may not have this token, so live search validation is best-effort only.