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