# Contributing to rinco-pi-effort

Thanks for taking the time to contribute! This is a small [Pi](https://github.com/earendil-works/pi-coding-agent)
extension, so the contributor workflow is intentionally lightweight.

## Development Environment Setup

### Prerequisites

- Node.js `>=22.19.0` (see `engines` in `package.json` — same minimum as
  `@earendil-works/pi-coding-agent` itself, required for the
  `--experimental-strip-types` test runner flag)
- npm (bundled with Node)

### Install

```bash
git clone https://github.com/Rinisnotarobot/rinco-pi-effort.git
cd rinco-pi-effort
npm install
```

`@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui` are declared as
`peerDependencies` (see [Compatibility](../README.md#compatibility) in the
README for the supported version range) and are installed as dev
dependencies locally so tests can import their types and runtime helpers.

## Available Scripts

<!-- AUTO-GENERATED: scripts (source: package.json#scripts) -->
| Command | Description |
|---------|-------------|
| `npm test` | Run the extension's unit tests (Node's built-in test runner, `--experimental-strip-types`) |
<!-- /AUTO-GENERATED -->

## Testing Procedures

### Running tests

```bash
npm test
```

Tests run directly against the TypeScript sources under `tests/*.test.ts`
using Node's built-in test runner (`node:test`) with `--experimental-strip-types` —
no build step or transpiler config is required.

### Writing new tests

- Put new test files under `tests/` and name them `*.test.ts` (the `npm test`
  glob picks them up automatically).
- Follow the existing Arrange-Act-Assert style already used in
  `tests/effort-command.test.ts` and `tests/effort-level.test.ts`.
- Mock only the minimal surface of Pi's `ExtensionAPI` / `ExtensionContext`
  that your code under test actually needs (see the `MockPi` / `MockContext`
  types in `tests/effort-command.test.ts` for the established pattern) rather
  than depending on the real `@earendil-works/pi-coding-agent` runtime.
- Cover boundary conditions explicitly (first/last effort level, narrow
  terminal widths, invalid/undefined input) — see the existing tests for
  examples.

## Code Style

There is currently **no linter or formatter configured** in this repository
(no ESLint/Biome/Prettier config present). Until one is added, please match
the existing style by hand:

- Tabs for indentation (see existing files under `extensions/`)
- `camelCase` for functions/variables, `PascalCase` for types
- Prefer immutable updates (return new objects/values; avoid mutating
  parameters) — see `effort-level.ts` for the pattern used throughout
- Keep functions focused; if a function grows past ~50 lines, consider
  extracting helpers (see the open follow-up noted in
  `.pi/artifacts/reviews/full-project-review.md`)
- Add JSDoc to exported functions/types intended for reuse

There are no pre-commit hooks configured either — running `npm test` before
opening a PR is the only required local check.

## PR Submission Checklist

Before opening a pull request:

- [ ] `npm test` passes locally
- [ ] New/changed behavior has test coverage (unit tests under `tests/`)
- [ ] No `console.log`/debug statements left in source
- [ ] No secrets, tokens, or credentials committed
- [ ] README updated if user-facing behavior (commands, controls, effort
      levels, installation) changed
- [ ] `package.json` `peerDependencies` / `engines` updated if you bumped the
      minimum supported Pi or Node version (see
      [Compatibility](../README.md#compatibility))
- [ ] Commit messages follow `<type>: <description>` (e.g. `feat:`, `fix:`,
      `refactor:`, `docs:`, `test:`, `chore:`)

## Questions or Issues

Open an issue at
[github.com/Rinisnotarobot/rinco-pi-effort/issues](https://github.com/Rinisnotarobot/rinco-pi-effort/issues).