pi-env-probe

Cross-platform environment diagnostics for Pi — shell, PATH, runtime, encoding, and non-ASCII path risks in compact JSON.

What this is

pi-env-probe collects lightweight environment diagnostics and returns them as compact JSON. Use it from the CLI, as a Pi slash command, or import probe() in your own tooling.

Features

• Detects the current shell (bash, pwsh, cmd, zsh, or null)
• Reports whether common shells are available in PATH
• Detects non-ASCII file/folder names in the current working directory
• Returns the platform path separator (; on Windows, : on POSIX)
• Aggregates identified risks into a sorted array
• Never throws from probe() — subprocess failures degrade to false / null

Probe result fields

| Field | Type | Description | |---|---|---| | shell | string \| null | Identified shell name ("bash", "pwsh", "cmd", "zsh", or null) | | shell_available | boolean | Whether any shell is available in PATH or detected from environment | | bash_in_path | boolean | Whether bash is found in PATH | | pwsh_in_path | boolean | Whether pwsh is found in PATH | | has_non_ascii_paths_in_cwd | boolean | Whether any direct child of CWD has a non-ASCII name | | path_separator | string | Platform path separator (";" on Windows, ":" on POSIX) | | node_version | string \| null | Node.js version string (e.g. "v22.0.0"), or null if unavailable | | bun_version | string \| null | Bun version string, or null if unavailable | | python_version | string \| null | Python version string, or null if unavailable | | encoding | string | Detected locale encoding from LC_CTYPE / LANG, defaults to "utf8" | | risks | string[] | Ordered list of identified issues, empty [] when none |

Risk strings

The risks array may contain any of the following strings, in order: shell issues first, runtime issues second, path issues last.

| Risk string | Condition | |---|---| | "bash_not_in_path" | bash_in_path is false | | "pwsh_not_in_path" | pwsh_in_path is false | | "node_not_available" | node_version is null | | "bun_not_available" | bun_version is null | | "python_not_available" | python_version is null | | "non_ascii_paths_in_cwd" | has_non_ascii_paths_in_cwd is true |

The risk array is always present. When no issues are detected it is an empty array [].

Install

Install the published npm package with Pi:

pi install npm:pi-env-probe

Install into the current project instead of your user Pi settings:

pi install npm:pi-env-probe -l

Or install from GitHub:

pi install git:github.com/eiei114/pi-env-probe

Try it without permanently installing:

pi -e npm:pi-env-probe

Quick start

Try this package locally:

pi -e .

Then run:

/env-probe

Or use the standalone CLI:

node bin/env-probe.js

Package contents

| Path | Purpose | |---|---| | lib/ | Shared probe logic (probe.ts) | | extensions/ | Pi extension registering /env-probe | | bin/ | Standalone CLI entry point |

Development

npm install
npm run ci

Verification

npm install
npm run typecheck
npm test
node bin/env-probe.js
node bin/env-probe.js | node -e "process.stdin.on('data',d=>{JSON.parse(d);console.log('valid JSON')})"
npm pack --dry-run

Release

This package is set up for npm Trusted Publishing, so no NPM_TOKEN is required.

npm version patch
git push --follow-tags

License

MIT — see LICENSE.