Skip to content
xtarter
Blog

Preflight & Diagnostics

Every project command runs preflight before doing work, and check and doctor additionally run tooling diagnostics.

Preflight checks

Section titled “Preflight checks”

Preflight requires:

  • A package.json in the project root (MISSING_PACKAGE_JSON when absent)
  • A name field in package.json (INVALID_PACKAGE_JSON when absent)
  • A git repository (MISSING_GIT when absent)

Covered commands are init, sync, diff, check, add, list, query, restore, undo, and doctor. When a check fails, the CLI prints every error with a hint and exits with code 1, and conformance tasks do not run. doctor continues so it can still report diagnostics. The CLI can maintain .gitignore so the internal .xtarterize/ directory stays out of version control even when preflight fails.

Diagnostics

Section titled “Diagnostics”
  • Conflicting tools: Biome alongside ESLint or Prettier, and legacy .eslintrc files, are reported as warnings.
  • Tool installation: for each tool declared in package.json (Biome, ESLint, TypeScript, Commitlint, Knip), the tool’s version command confirms it is installed.

check runs the tools and configuration groups. doctor runs every group (environment, tools, project, and configuration), and --verbose adds a system group with host platform information. Checks report pass, warn, or fail with a message. A check that throws becomes a single failure entry, so one broken check never hides the others, and a failing diagnostic sets exit code 1.

CI mode

Section titled “CI mode”

In CI (CI=true or CI=1), xtarterize enables quiet mode for all commands, suppressing prompts and verbose output. Quiet mode is also enabled by --quiet, --json, and --format json.