pi-health

Pi-native health checks and diagnostics toolkit for pi.dev extensions: deterministic readiness/liveness probes, pass/warn/fail check results, package/config/dependency/filesystem checks, optional bounded URL probes, and Markdown/JSON status reports.

Installation

pi install npm:pi-health

What It Does

pi-health provides deterministic, offline-first health checks for pi.dev extensions. It's designed for CI pipelines, local debugging, and operational readiness gates — no LLM calls, no hidden network activity.

Key features:

• Deterministic pass/warn/fail severity model with stable output ordering
• Built-in checks: package.json, files, directories, env vars, dependencies, Node.js engine, URL probes, JSON config
• Secret-safe: never prints environment variable values, only presence/absence
• Optional URL/network probes — explicit and timeout-bounded, disabled by default
• Markdown and JSON report generation with remediation hints
• CI-ready probe output with exit codes

Tools

health_check

Run configured health checks and return a deterministic aggregate status.

Parameters:

• projectPath (string, optional) — Project root path (defaults to cwd)
• checks (array, optional) — Explicit check definitions. If omitted, runs default checks.
• configPath (string, optional) — Path to health-check config JSON file
• timeoutMs (number, optional) — Global timeout for all checks (default: 30000)
• includeWarnings (boolean, optional) — Include warning-level checks (default: true)
• now (string, optional) — ISO timestamp for deterministic tests

Example:

Use the health_check tool with projectPath="/path/to/project"

health_report

Generate a comprehensive Markdown or JSON health report for a pi.dev extension/package.

Parameters:

• projectPath (string, optional) — Project root path (defaults to cwd)
• format (string, optional) — "markdown" or "json" (default: "markdown")
• checks (array, optional) — Explicit check definitions
• includePackageMetadata (boolean, optional) — Include package.json metadata (default: true)
• includeIntegrations (boolean, optional) — Include integration notes (default: true)
• outputPath (string, optional) — File path to write report
• timeoutMs (number, optional) — Global timeout (default: 30000)

Example:

Use the health_report tool with projectPath="/path/to/project" format="markdown"

health_probe

CI/local readiness/liveness/startup probe output suitable for automation gates.

Parameters:

• projectPath (string, optional) — Project root path (defaults to cwd)
• mode (string) — "readiness", "liveness", or "startup"
• failOnWarn (boolean, optional) — Treat warnings as failures (exit code 2) (default: false)
• maxFailures (number, optional) — Maximum failures before early exit (default: 10)
• timeoutMs (number, optional) — Global timeout (default: 10000)
• checks (array, optional) — Explicit check definitions

Example:

Use the health_probe tool with mode="readiness" failOnWarn=true

Check Types

| Type | Description | Default Severity | |------|-------------|-----------------| | package_json | package.json present and parseable | critical | | file_exists | File(s) exist at given path(s) | critical/warning | | dir_exists | Directory/directories exist | critical/warning | | env_var | Environment variable(s) present (values never leaked) | critical/warning | | dependency | Dependency listed in package.json | critical/warning | | node_engine | Node.js version satisfies engines constraint | warning | | url_probe | HTTP HEAD request to URL (explicit, timeout-bounded) | warning | | json_parse | JSON file is parseable | critical/warning |

Check Configuration

You can pass custom checks inline or via a config file:

{
  "checks": [
    { "type": "package_json", "severity": "critical" },
    { "type": "file_exists", "paths": ["README.md", "README.txt"], "required": false },
    { "type": "env_var", "names": ["NODE_ENV", "API_KEY"], "severity": "warning" },
    { "type": "dependency", "names": ["vitest", "typescript"] },
    { "type": "node_engine", "severity": "warning" },
    { "type": "url_probe", "url": "https://api.example.com/health", "timeoutMs": 5000 },
    { "type": "json_parse", "filePath": "tsconfig.json" }
  ]
}

CI Usage

Add health probes to your CI pipeline:

# GitHub Actions example
- name: Health check
  run: |
    npx pi-health-probe --mode readiness --fail-on-warn

The health_probe tool returns exit codes:

• 0 — All checks passed (or warnings with failOnWarn=false)
• 1 — Failures detected
• 2 — Warnings detected (when failOnWarn=true)

Secret Safety

pi-health never prints environment variable values. When checking env vars, only the variable name and presence/absence status is reported:

✅ Environment variable present: API_KEY=***
❌ Environment variable missing: MISSING_VAR=***

Integrations

| Package | Integration | |---------|-------------| | @realvendex/pi-config | Load health-check config/policies | | @realvendex/pi-log | Log health events and remediation hints | | pi-rate-limit | Include circuit/rate-limit status as custom health checks | | @realvendex/pi-cache | Check cache persistence path and stale/error ratios | | pi-perf | Enforce latency thresholds | | pi-ci | Add health probes to generated CI workflows | | pi-readme / @realvendex/pi-doc | Include health report in documentation | | pi-token-router | Provider readiness checks when explicitly configured |

Resources

• npm
• GitHub
• pi.dev

License

MIT