// Provide Counterfact repository orientation, high-level architecture, and the canonical command reference for install/build/test/lint workflows.
| name | counterfact-repo-basics |
| description | Provide Counterfact repository orientation, high-level architecture, and the canonical command reference for install/build/test/lint workflows. |
| applyTo | ["**/*"] |
Use this skill when you need quick repository orientation, command references, or issue-proposal workflow rules.
Counterfact is a TypeScript-based mock server generator that turns OpenAPI/Swagger specs into live, stateful mock APIs with hot reload, a REPL, and Swagger UI.
npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api
src/
app.ts # Main entry point; generation + server + REPL orchestration
server/ # Koa server, dispatcher, registry, hot-reload internals
typescript-generator/ # OpenAPI parsing and TypeScript generation
counterfact-types/ # Public API types exposed to route-handler authors
repl/ # Interactive terminal for runtime state control
migrate/ # Helpers for migrating generated route files
client/ # Built-in dashboard/docs page templates
util/ # Shared utilities
bin/
counterfact.js # CLI entry point
test/ # Jest unit tests
test-black-box/ # Python black-box integration tests
templates/ # Generator scaffold templates
| Task | Command |
|---|---|
| Install dependencies | yarn install --frozen-lockfile |
| Build | yarn build |
| Unit tests | yarn test |
| Black-box (integration) tests | yarn test:black-box |
| TypeScript type tests | yarn build && yarn test:tsd |
| Lint (check) | yarn lint |
| Lint (auto-fix) | yarn lint:fix |
| Run against Petstore | yarn go:petstore |
Never create GitHub issues directly. Propose them as Markdown files under .github/issue-proposals/ and follow .github/instructions/issue-proposals.instructions.md.
Keep contributor changes aligned with repository test patterns, diagnostics, release/versioning workflow, documentation requirements, and compatibility.
Update Counterfact CLI option behavior, config resolution, telemetry-safe startup handling, and bootstrap/runtime entrypoint flow.
Modify TypeScript generator internals, OpenAPI parsing/schema handling, and generated file writing behavior without regressing regeneration guarantees.
Safely change Counterfact runtime/server internals while preserving module boundaries, hot reload behavior, and backward compatibility guarantees.
Add and evolve Counterfact context classes in _.context.ts files, including required unit test coverage for context behavior.
Edit Counterfact route files to add endpoint behavior while keeping handlers thin and delegating business logic to context classes.