apitap copilot-instructions.md

Copilot Instructions for ApiTap

Build and test commands

• Install deps: npm install
• Full test suite: npm test (Node test runner via node --import tsx --test 'test/**/*.test.ts')
• Single test file (example): node --import tsx --test test/capture/filter.test.ts
• Type check: npm run typecheck
• Lint: no dedicated lint script is configured in package.json
• Build: npm run build
• Run CLI from source: npx tsx src/cli.ts <command> [args]
• Install Chromium for browser-required flows (capture / browse): npx playwright install chromium

High-level architecture

ApiTap has two primary execution paths that share skill-file artifacts:

• Capture path (browser required): Playwright/CDP capture in src/capture/monitor.ts and src/capture/session.ts collects traffic, src/capture/filter.ts removes noise, then src/skill/generator.ts deduplicates by method + parameterizedPath and writes skill files through src/skill/store.ts to ~/.apitap/skills/<domain>.json.
• Replay path (browser-free): src/replay/engine.ts loads a skill file, substitutes params, injects credentials from src/auth/manager.ts, applies SSRF/header protections from src/skill/ssrf.ts, then executes requests with stdlib fetch().

Supporting layers:

• src/discovery/ runs framework detection, OpenAPI probing, and endpoint probes in parallel.
• src/orchestration/browse.ts is the high-level pipeline (cache -> disk -> discover -> replay).
• src/read/ provides peek/read text-mode extraction with site-specific decoders and generic fallback.
• src/mcp.ts exposes MCP tools over the same core pipeline; external API responses are marked untrusted.

Key repository conventions

• ESM + NodeNext rules are strict: use .js in TS imports (e.g. import { x } from './y.js').
• CLI-first surface area: keep behavior exposed via src/cli.ts commands, and ensure machine-readable --json output remains consistent.
• Website-fetch workflow priority: when data is needed from a site, prefer apitap show <domain> → apitap replay <domain> <endpoint-id>; if no skill file exists, try apitap read <url> before browser-based capture/browse.
• Skill files are central artifacts: endpoint metadata belongs in skill JSON, but auth secrets must never be stored there; auth stays in encrypted storage.
• Security checks are part of normal flow: preserve SSRF validation, header filtering, DNS/redirect checks during import and replay paths.
• Test layout mirrors source layout: add/update tests under test/ matching src/ paths; use Node's built-in node:test style.
• Dependency discipline: replay path should prefer stdlib fetch; keep Playwright usage scoped to capture/auth browser flows.