# purrfold

> purrfold is a CLI that scaffolds a production-ready frontend app with shadcn,
> strict quality tooling (ESLint, Prettier, React Doctor, React Scan), agent
> docs, Claude hooks, and optional unit (Vitest) / e2e (Playwright) / commitlint.
> It starts from `create-next-app@latest`. No install needed — run it with `npx`.

## Install / run

```bash
npx purrfold@latest <target-dir> [options]
```

The generated app self-tests: purrfold runs Prettier and the project's own
`check` (lint + typecheck + format + test + react-doctor) after generating and
fails if it is not green.

## Options

- `--pm <npm|pnpm|bun>` — package manager (default: prompts, or npm with `--yes`).
- `--unit` / `--no-unit` — Vitest + React Testing Library (default: included).
- `--e2e` / `--no-e2e` — Playwright e2e (default: skipped).
- `--commitlint` / `--no-commitlint` — commitlint + commit-msg hook (default: skipped).
- `--yes` — non-interactive defaults (no prompts).
- `--dry-run` — print operations without writing or installing.
- `--skip-install` — generate files without installing extra quality deps.
- `--shadcn-args <args...>` — extra args forwarded to `shadcn init`, including `--preset <id>`.
- `--mcp` / `--no-mcp` — optionally install shadcn MCP for Claude, Codex, and OpenCode (default: skipped).
- `--icons <lucide|phosphor|tabler>` — icon library for the home-page cat (default: shadcn's choice, else lucide).

For a structured schema an agent can parse, run:

```bash
npx purrfold@latest info --json
```

## Intent → command

| The user wants… | Run |
| --- | --- |
| Defaults (unit tests, no e2e/commitlint) | `npx purrfold@latest my-app --yes` |
| No testing at all | `npx purrfold@latest my-app --no-unit --no-e2e --yes` |
| Full setup (unit + e2e + commitlint) | `npx purrfold@latest my-app --unit --e2e --commitlint --yes` |
| A specific package manager | `npx purrfold@latest my-app --pm pnpm --yes` |
| A specific icon library for the cat | `npx purrfold@latest my-app --icons phosphor --yes` |
| shadcn MCP for Claude/Codex/OpenCode | `npx purrfold@latest my-app --mcp --yes` |
| A shadcn preset | `npx purrfold@latest my-app --shadcn-args --preset b3REw8vwo --yes` |
| Preview without writing | `npx purrfold@latest my-app --yes --dry-run` |

## Notes for agents

- Always pass `--yes` when running non-interactively so purrfold does not block on prompts.
- `<target-dir>` is required and becomes the project folder name.
- The default command is `create`; `purrfold my-app` and `purrfold create my-app` are equivalent.
- Maintainers can run `npm run test:e2e:cli:quick` for dry-run CLI coverage and
  `npm run test:e2e:cli -- --work-dir E:\Repositorios\smoke --keep` for the
  heavy real-app matrix. Heavy CLI E2E is intentionally outside `npm run check`.