# Contributing to pi-ask

Thanks for helping improve `pi-ask`.

## Requirements

- Node.js 22.19 or newer
- npm
- A recent Pi installation for interactive testing

## Setup

```sh
npm install
npm run validate
```

To test the extension in Pi from a local checkout:

From the repository root:

```sh
pi install "$PWD"
```

Restart Pi or run `/reload` after changing extension code.

## Source layout

- `index.ts` registers the tool, validates execution mode, and formats tool results.
- `src/schema.ts` owns the public schema, limits, normalization, and error types.
- `src/state.ts` contains pure questionnaire state transitions.
- `src/dialog.ts` adapts state to Pi's TUI component API.
- `test/state.test.ts` covers validation, state, dialog behavior, and result envelopes.

Keep state transitions in `src/state.ts` when possible. Pure transitions are easier to reason about and test than behavior embedded directly in keyboard handlers.

## Validation

Run all checks before opening a pull request:

```sh
npm run validate
```

This runs:

1. TypeScript checking with no emitted output.
2. The test suite through `tsx` and Node's test runner.
3. `npm pack --dry-run` to verify published package contents.

## Tests

Add or update tests when changing:

- Tool input or result contracts.
- Validation limits or error codes.
- Selection and tab transitions.
- Custom-answer creation, editing, or removal.
- Keyboard routing.
- Width-aware rendering or focus behavior.
- Cancellation and abort handling.

For TUI changes, include a focused component test and manually exercise the extension in a real Pi session.

## Pull requests

Keep pull requests focused. Explain the user-visible behavior, note any schema or result-contract changes, and include validation evidence.

The initial package intentionally excludes previews, localization, per-option notes, and non-TUI transport. Proposals in those areas should explain the interaction and compatibility trade-offs before implementation.

## License

By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).