71 lines
3.2 KiB
Markdown
71 lines
3.2 KiB
Markdown
# 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 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.
|