Skip to content

AGENTS.md

Latest commit

 

History

History
43 lines (31 loc) · 2.44 KB

AGENTS.md

File metadata and controls

43 lines (31 loc) · 2.44 KB

Repository Guidelines

Project Structure & Module Organization

  • src/ TypeScript source (ESM). Entry: src/index.ts → main.ts; shared helpers in src/shared/.
  • bin/ CLI launcher (openrouter) that loads dist/index.js.
  • dist/ build output (generated by npm run build). Do not edit.
  • tests/ Vitest specs (e.g., config.spec.ts, openrouter.spec.ts).
  • docs/ design and configuration notes; scripts/ release/build helpers.
  • Config files: global ~/.config/openrouter-cli/config.json; project overrides .openrouterrc(.json|.yaml|.yml).

Build, Test, and Development Commands

  • npm run dev — run CLI in TS directly (ts-node ESM). Example: npm run dev -- ask "Hello".
  • npm run build — compile TypeScript to dist/.
  • npm test / npm run test:watch — run Vitest once / in watch mode.
  • npm run lint — ESLint over src/**.
  • npm run commit — Commitizen prompt for Conventional Commits.
  • After build: openrouter --help (via bin/openrouter) or node dist/index.js.

Coding Style & Naming Conventions

  • TypeScript, ESM, 2-space indentation, single quotes allowed; prefer explicit return types for exported functions.
  • File names: lowercase (e.g., main.ts, repl.ts, shared/openrouter.ts).
  • ESM import paths in TS include .js (e.g., import { x } from './main.js').
  • Use helpers to protect secrets; never log API keys. Config files are written with chmod 600 when possible.
  • Linting via flat-config ESLint (eslint.config.js); pre-commit runs lint-staged.

Testing Guidelines

  • Framework: Vitest. Place tests in tests/*.spec.ts with clear, isolated cases.
  • Cover config precedence, URL joining, and CLI option parsing. Example: see tests/openrouter.spec.ts for joinUrl.
  • Run npm test locally; keep tests deterministic (no network). Mock I/O when needed.

Commit & Pull Request Guidelines

  • Follow Conventional Commits: feat:, fix:, chore:, docs:, refactor:, test:; use scopes when helpful (e.g., feat(config): ...). Use npm run commit.
  • PRs: concise description, linked issues, CLI examples (commands/output), and updated docs when behavior changes. Ensure lint, test, and build pass.

Security & Configuration Tips

  • Prefer OPENROUTER_API_KEY/OPENAI_API_KEY; avoid committing secrets. Use openrouter config --api-key only if persistence is required.
  • Example: openrouter config --model meta-llama/llama-3.1-8b-instruct --domain https://openrouter.ai/api/v1.