---
slug: "pi-health"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/ZachDreamZ/pi-health@master/README.md"
repo: "https://github.com/ZachDreamZ/pi-health"
source_file: "README.md"
branch: "master"
---
# 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

```bash
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:

```json
{
  "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:

```yaml
# 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](https://www.npmjs.com/package/pi-health)
- [GitHub](https://github.com/ZachDreamZ/pi-health)
- [pi.dev](https://pi.dev/packages/pi-health)

## License

MIT