perfect-typescripter

Perfect TypeScripter

Rust-style discipline for TypeScript. Bans null, undefined, optional fields, booleans-as-domain-state, any, unknown, positional args (>1), string widening, phantom type parameters, degenerate comparators, missing @why tags on exports, and other shapes that compile but rot in production. Forces discriminated unions and exhaustive switch everywhere domain state lives.

Quickstart

Pick your runtime, run the one-liner, done.

Claude Code

claude plugin marketplace add https://github.com/CheckPickerUpper/perfect-typescripter
claude plugin install perfect-typescripter@perfect-typescripter --scope user

Codex CLI

git clone https://github.com/CheckPickerUpper/perfect-typescripter \
  ~/.codex/plugins/cache/perfect-typescripter/perfect-typescripter/local

OpenCode

git clone https://github.com/CheckPickerUpper/perfect-typescripter ~/perfect-typescripter

Then add to your opencode.json:

{ "plugin": ["file:///home/you/perfect-typescripter/.opencode/perfect-typescripter-opencode-bundle.js"] }

Skills CLI (any SKILL.md consumer: Cursor, Cline, etc.)

npx skills add CheckPickerUpper/perfect-typescripter

ESLint plugin (cross-file rules)

git clone https://github.com/CheckPickerUpper/perfect-typescripter
npm install --save-dev file:./perfect-typescripter/eslint-plugin

Or run /setup-eslint inside Claude Code to scaffold ESLint config, parser, and pre-commit in one pass.

For full per-surface install detail (project config, custom flags, npm-publish status), jump to Install (full).

What you get

Artifact	Catches	Where it lives
Claude Code / Codex / OpenCode plugin	The file you are writing. PreToolUse Write / Edit hooks block the bad shapes before they land on disk.	this repo's root
eslint-plugin-perfect-typescripter	Patterns that span files: phantom type params, duplicate envelope shapes, shared variant literals across discriminated unions, variant prefix drift.	./eslint-plugin/

Per-file hook plus cross-file ESLint closes the gap that either alone leaves open.

What gets blocked

A taste; full catalogue in docs/RULES.md:

// blocked: optional field
type User = { name: string; email?: string };

// blocked: null / undefined in declared types
type Maybe = string | null;
function find(): User | undefined { ... }

// blocked: boolean as domain state
function setStatus(active: boolean) { ... }

// blocked: positional args (> 1)
function move(x: number, y: number, z: number) { ... }

// blocked: string widening of literal union
type Variant = "Small" | "Medium" | "Large" | string;

// blocked: phantom type parameter (TKind never used in the body)
type Registry<TKind, V> = { entries: V[] };

// blocked: degenerate comparator returning boolean over a typed input
function isSameTransition(prev: Slot, next: Slot): boolean { ... }

The correct shape in each case is a discriminated union with a Kind field and an exhaustive switch. See docs/RULES.md for the rewrite of each example.

Install (full)

The quickstart above gets you running. This section spells out per-surface options (project config, override flags, npm-publish status, etc) for users who need them.

Surface	Status	Quickstart command
Claude Code (plugin marketplace)	✅ ready	claude plugin marketplace add https://github.com/CheckPickerUpper/perfect-typescripter && claude plugin install perfect-typescripter@perfect-typescripter --scope user
Codex CLI	✅ ready	git clone https://github.com/CheckPickerUpper/perfect-typescripter ~/.codex/plugins/cache/perfect-typescripter/perfect-typescripter/local (Codex auto-discovers .codex-plugin/plugin.json)
OpenCode	✅ ready	Clone, then add "file:///.../.opencode/perfect-typescripter-opencode-bundle.js" to opencode.json plugin array (or drop into ~/.config/opencode/plugins/). See OpenCode below.
Skills CLI (skills.sh / npx skills)	✅ ready	npx skills add CheckPickerUpper/perfect-typescripter
npm (ESLint plugin only)	🚧 not yet published	(planned: npm install --save-dev eslint-plugin-perfect-typescripter after first release)

Claude Code (plugin marketplace)

The repo doubles as a single-plugin marketplace via .claude-plugin/marketplace.json + .claude-plugin/plugin.json. Install in one step:

claude plugin marketplace add https://github.com/CheckPickerUpper/perfect-typescripter
claude plugin install perfect-typescripter@perfect-typescripter --scope user