initial commit

AGENTS.md

@@ -0,0 +1,70 @@
+# Project Guidelines
+
+## Purpose
+
+This project provides small Firefox/Selenium browser utilities packaged by Nix:
+
+- `glimpse` - generic page utilities with subcommands, including provider-backed search
+
+Keep the tools simple, scriptable, and JSON-friendly.
+
+## Commands
+
+Prefer relevant checks after changes because the full suite can take time:
+
+```bash
+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:snapshot`, `npm run test:wait`, `npm run test:errors`, or `node test/smoke.js snapshot 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=<ms>` is a top-level option for command waits and defaults to `10000`.
+- `--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:
+
+- `snapshot <url>` - return an agent-friendly page snapshot as JSON
+- `exec <url> --js=<code>` or `--script=<file>` - execute JavaScript and return the result
+- `screenshot <url> --output=<file>` - save a PNG screenshot
+- `reader <url>` - open Firefox Reader View and output readable content as Markdown
+- `search <query>` - search with a supported provider and output JSON results
+
+## 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 ES modules.
+- 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.