playground-cli: Instructions file for Codex

AGENTS.md

Project Overview

playground-cli is a TypeScript ESM CLI for Polkadot Playground, installed as the playground command (short alias pg — both invoke the same binary). The CLI uses Commander and Ink/React for its terminal UI, is compiled with Bun, and is tested with Vitest.

CLAUDE.md is the authoritative source for repo-specific invariants and rationale. Read it alongside this file; where the two differ, CLAUDE.md wins.

Commands

• Install dependencies: pnpm install
• Build compiled CLI: pnpm build
• Run tests: pnpm test
• Watch tests: pnpm test:watch
• Type check: pnpm exec tsc --noEmit
• Format: pnpm format
• Check formatting: pnpm format:check
• Check license headers: pnpm lint:license
• Install local binary: pnpm cli:install

Verification before committing

Run all three before claiming work is done, opening a PR, or merging. The first two are enforced by CI; the third catches regressions:

pnpm format:check
pnpm lint:license
pnpm test

pnpm build compiles with Bun, which strips types without checking them — it is NOT a type signal, and there is no tsc step in CI. The tree carries a known baseline of pre-existing tsc --noEmit errors; before claiming a change complete, run pnpm exec tsc --noEmit 2>&1 | grep -c "error TS" and confirm the count did not grow. If lint:license flags a file you authored, run ./scripts/check-license-headers.sh --fix to prepend the Parity Apache-2.0 block (SPDX line + Parity copyright line, both required) — every tracked .ts / .tsx / .rs file must carry it.

Repository Conventions

• Tests live next to the source as *.test.ts. vitest.config.ts only picks up .test.ts; update it before adding .tsx tests.
• Pure logic embedded in .tsx components should be lifted into sibling .ts files so tests can import it without pulling React and Ink into the runner.
• Every user-facing PR needs a changeset in .changeset/*.md. Refactors, tests, and internal tooling-only changes can skip one.
• Do not add AI/tool attribution, signatures, or provenance to commits, PRs, generated files, or repo content.
• Do not commit design docs, brainstorming notes, context dumps, or scratch files.
• Do not mock polkadot-api primitives such as Enum or encoders in tests.
• Long-lived resources such as TerminalAdapter, session signers, and chain clients must be explicitly destroyed in cleanups — the WebSocket keeps the event loop alive, so a forgotten destroy() manifests as playground <cmd> hanging after the work visibly finishes.