gesso health
Inspect a project and print eight setup checks as TOON (Token-Oriented Object Notation):
pnpm gesso health
Run it from the project root after pnpm install and after applying the manual wiring steps from gesso init.
Checks
| Check | What it verifies | Typical remediation |
|---|---|---|
registry-auth | A usable token assignment is present in project or home npm configuration. | Follow registry authentication, or restore read access to the reported file. |
gesso-installed | The installed @acromedia/gesso package can be resolved and read. | Run pnpm install, or run pnpm gesso init first when the dependency is undeclared. |
dependency-placement | Any declared Gesso dependency is in dependencies, and any declared CLI dependency is in devDependencies. Absence is handled by other checks and can pass this row. | Move misplaced declarations, then run pnpm install. |
version-match | Installed Gesso matches the Gesso version targeted by bundled catalog documentation. | Update Gesso to that target, or use a CLI build whose bundled documentation targets the installed version. |
provider-wiring | A conservative scan finds <ThemeProvider> in known Entry Files or Providers Boundaries. | Add <ThemeProvider> at a known Entry File or Providers Boundary. |
dev-script | package.json has a dev script. | Add "dev": "next dev". |
agent-instructions | Across supported skill directories, unreadable outranks current, outdated outranks user-owned/forked, and current/forked passes. AGENTS.md routing is considered only after outdated/unreadable early failures. | Run pnpm gesso init, or repair the path/read error shown. |
config-deprecations | A present gesso.config.json is readable, valid, and free of known deprecated configuration. | Apply the row's configuration fixes. |
version-match does not compare Gesso with the CLI package's own version. The two package versions are independent; the expected value is gessoVersion from the CLI's bundled catalog index.
Status and exit behavior
Every row has ok, fail, or skip status and a fix field. A passing row has an empty fix. skip means the check is not applicable or cannot be evaluated from missing facts; for example, an absent gesso.config.json skips config-deprecations, and a missing installed Gesso package skips version-match while gesso-installed fails.
If any row fails, the command prints the row-specific remediation, an unhealthy summary, and a final next: instruction, then exits with status 1. If no row fails, it prints Gesso is healthy!, the TOON rows, and exits with status 0.
Apply each failed row's fix and rerun:
pnpm gesso health