{"_id":"@4meta5/pi-zsh","name":"@4meta5/pi-zsh","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@4meta5/pi-zsh","version":"0.1.0","description":"Allowlist-only zsh script runner extension for pi coding agents.","license":"MIT","author":{"name":"4meta5"},"repository":{"type":"git","url":"git+https://github.com/4meta5/pi-zsh.git"},"homepage":"https://github.com/4meta5/pi-zsh#readme","bugs":{"url":"https://github.com/4meta5/pi-zsh/issues"},"type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"pi":{"extensions":["./src/index.ts"]},"scripts":{"build":"rm -rf dist && tsc -p tsconfig.build.json","check":"tsc -p tsconfig.json --noEmit","test":"vitest run","prepublishOnly":"npm run check && npm test && npm run build"},"keywords":["pi","pi-extension","pi-package","zsh","allowlist","security"],"publishConfig":{"access":"public"},"engines":{"node":">=20.0.0"},"peerDependencies":{"@mariozechner/pi-ai":"*","@mariozechner/pi-coding-agent":"*","@sinclair/typebox":"*"},"devDependencies":{"@mariozechner/pi-ai":"^0.52.12","@mariozechner/pi-coding-agent":"^0.52.12","@sinclair/typebox":"^0.34.40","@types/node":"^24.3.0","typescript":"^5.9.2","vitest":"^3.2.4"},"gitHead":"e62c13218ea6fd54f6ded4ca8b7c8e0fab623ebd","_id":"@4meta5/pi-zsh@0.1.0","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-nnhax1WyckPPqRvsq+EIVFdNzCQKnZUpwfvcujiQG5qL8zbD+TaBcz5Yfqpz7k26GRDppD52xKjNlnnRtJf7zQ==","shasum":"6001827f4a9c0109cf87a1f10f48a6afeba91fd4","tarball":"https://registry.npmjs.org/@4meta5/pi-zsh/-/pi-zsh-0.1.0.tgz","fileCount":20,"unpackedSize":72407,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGJZ/OA3KK40Pk4zoS+RMJKWryT6pWAbwHvvqYCmO1QCAiEA/K4OHSiSR9J6ech9CR062+1bc96OzYwtXyHfHeTRCfs="}]},"_npmUser":{"name":"4meta5","email":"orlandodowntownhome@gmail.com"},"directories":{},"maintainers":[{"name":"4meta5","email":"orlandodowntownhome@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-zsh_0.1.0_1771440301781_0.004060404343531054"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-18T18:45:01.708Z","0.1.0":"2026-02-18T18:45:02.088Z","modified":"2026-02-18T18:45:02.256Z"},"maintainers":[{"name":"4meta5","email":"orlandodowntownhome@gmail.com"}],"description":"Allowlist-only zsh script runner extension for pi coding agents.","homepage":"https://github.com/4meta5/pi-zsh#readme","keywords":["pi","pi-extension","pi-package","zsh","allowlist","security"],"repository":{"type":"git","url":"git+https://github.com/4meta5/pi-zsh.git"},"author":{"name":"4meta5"},"bugs":{"url":"https://github.com/4meta5/pi-zsh/issues"},"license":"MIT","readme":"# pi-zsh\n\n[![npm](https://img.shields.io/npm/v/@4meta5/pi-zsh)](https://www.npmjs.com/package/@4meta5/pi-zsh)\n\nAllowlist-only zsh script runner extension for pi coding agents.\n\n`pi-zsh` does one job: run explicitly allowlisted `.zsh` scripts through one tool, `zsh_script_run`. It does not provide arbitrary shell execution, scheduling, or orchestration.\n\n## Project Docs\n\n- [README](README.md)\n- [Code of Conduct](CODE_OF_CONDUCT.md)\n- [Contributing](CONTRIBUTING.md)\n- [Security](SECURITY.md)\n- [Changelog](CHANGELOG.md)\n- [MIT License](LICENSE)\n\n## Why This Exists\n\nMost shell integrations start tight and then drift into \"run anything.\" `pi-zsh` keeps a stricter boundary:\n\n- only allowlisted `script_id` values can execute\n- each script path must be absolute, executable, and `.zsh`\n- environment variables are allowlisted\n- output is truncated for context safety, with optional full-output file pointer\n- non-zero exit, timeout, and abort are surfaced as `isError: true`\n\n## Install\n\n```bash\nnpm install @4meta5/pi-zsh\n```\n\nThis package includes the `pi-package` keyword so it is discoverable by pi package indexing flows.\n\n## Quick Start\n\n1. Create an allowlist file:\n\n```json\n{\n  \"allowlist\": {\n    \"cron_review\": {\n      \"path\": \"/absolute/path/to/cron-review.zsh\",\n      \"defaultArgs\": [],\n      \"defaultCwdMode\": \"script_root\"\n    }\n  },\n  \"envAllowlist\": [\"PATH\", \"HOME\", \"SHELL\", \"LANG\", \"LC_ALL\"],\n  \"defaultTimeoutMs\": 120000,\n  \"maxTimeoutMs\": 900000\n}\n```\n\n2. Set required config:\n\n```bash\nexport PI_ZSH_ALLOWLIST_FILE=/absolute/path/to/pi-zsh-allowlist.json\n```\n\n3. Load as a pi extension:\n\n```bash\npi -e /absolute/path/to/pi-zsh/src/index.ts\n```\n\n## Tool Contract\n\n### `zsh_script_run`\n\nParameters:\n\n- `script_id` (required): allowlisted script identifier\n- `args` (optional): extra args appended after allowlist defaults\n- `cwd_mode` (optional): `script_root` or `caller_cwd`\n- `timeout_ms` (optional): per-call timeout clamped by config max\n\nReturns:\n\n- text summary plus truncated output preview\n- structured `details` including path, argv, duration, and truncation metadata\n- `isError: true` for non-zero exit, timeout, or abort\n\n## Config\n\nRequired:\n\n- `PI_ZSH_ALLOWLIST_FILE`: absolute path to JSON config\n\nOptional env overrides:\n\n- `PI_ZSH_ENV_ALLOWLIST`\n- `PI_ZSH_DEFAULT_TIMEOUT_MS`\n- `PI_ZSH_MAX_TIMEOUT_MS`\n\nEmpty `envAllowlist` behavior:\n\n- if config sets `\"envAllowlist\": []`, `pi-zsh` requires an interactive decision at runtime\n- in non-UI mode, execution returns an error with remediation guidance\n\nAuthor-convenience default env allowlist:\n\n- `AGENT_DISPATCH_DIR`\n- `AGENT_DISPATCH_CMD`\n- `CLONES_DIR`\n- `GITHUB_TOKEN`\n- `PATH`\n- `HOME`\n- `SHELL`\n- `LANG`\n- `LC_ALL`\n\n## Scope Boundaries\n\nIn scope:\n\n- one extension package\n- one tool (`zsh_script_run`)\n- allowlist-only script execution\n- explicit failure semantics and output truncation\n\nOut of scope:\n\n- arbitrary command execution\n- script discovery frameworks\n- schedulers and orchestrators\n- auth plugin orchestration\n- update and migration surfaces\n\n## Development\n\n```bash\nnpm run check\nnpm test\nnpm run build\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-f15978fb3d1c1b4ba8acc5480483e23d"}