# [Tool Name]

A small TypeScript CLI. Installs from npm, runs anywhere Node 22+ runs.

## Source of truth
GitHub. Published to npm under your scope (`@yourname/your-tool`). Every release is a git tag plus an `npm publish`.

## Tech stack
Node 22 + TypeScript + tsx (for dev; ships compiled to ESM in `dist/`). `commander` for arg parsing. `kleur` for colors (small, no deps). `ora` for spinners. `prompts` for interactive input. `execa` for spawning subprocesses. Tests via Vitest.

## Deploy
- Local dev: `npm run dev -- your-args` (tsx watches and re-runs)
- Build: `npm run build` (tsc -> `dist/`)
- Release: `npm version patch && npm publish && git push --follow-tags`

## File map
- `src/cli.ts` shebang line, commander setup, command routing
- `src/commands/` one file per subcommand
- `src/lib/` shared helpers (config loader, fs ops)
- `package.json` `"bin"` field pointing at `dist/cli.js`
- `tsconfig.json` ESM + NodeNext + strict
- `vitest.config.ts`

## .env keys
None at runtime. CLI reads config from `~/.config/yourtool/config.json` (xdg-compliant) and CLI flags.

## Hard rules
- Shebang line on `src/cli.ts` is `#!/usr/bin/env node` (NOT `node22` or any version). Lets users with any modern Node run it.
- `package.json` `"bin"` points at the BUILT file in `dist/`, not `src/`.
- `"type": "module"` and ESM only. Don't dual-publish CJS in 2026.
- Every command has a `--help` example in the description. Test it.
- Exit codes: 0 on success, 1 on user error, 2 on internal error. Catch unhandled rejections and exit cleanly.
- No `process.cwd()` for finding the package root. Use `import.meta.url` resolution.

## Recent significant changes
- 2026-04-28: Scaffolded. Locked: tsx for dev, plain tsc for build, commander for parsing (yargs is overkill).

## Next session: start here
1. Set `name` in `package.json` (scoped is safest: `@yourname/tool`).
2. `npm init -w` for the bin entry, set `"bin"` mapping.
3. Implement first command under `src/commands/`.
4. `npm link` locally to test the binary as if installed.
5. `npm publish --access public` when ready.