pi-ketch 0.1.4 → 0.1.5

package/CONTRIBUTING.md

@@ -0,0 +1,100 @@
+# Contributing to pi-ketch
+
+`pi-ketch` is a small adapter between Pi and the Ketch CLI. Contributions should stay focused on that boundary: tool schemas, argument construction, process handling, bounded output, Pi rendering, and the bundled research skill.
+
+## Before you start
+
+Open an issue before beginning a broad feature or behavioral change. Small bug fixes, tests, and documentation corrections can go directly to a pull request.
+
+Reproduce backend behavior with the Ketch CLI when possible. If the same problem occurs in a direct Ketch command, it probably belongs in the [Ketch repository](https://github.com/1broseidon/ketch). Include that reproduction when opening an issue here so maintainers can confirm which project owns the fix.
+
+Do not report vulnerabilities in a public issue. Follow [SECURITY.md](./SECURITY.md) instead.
+
+## Development setup
+
+You need:
+
+- Node.js 22.14 or newer
+- Pi 0.80.6 or newer for manual integration testing
+- Ketch 0.11 or newer for optional live tests
+
+Clone the repository and install dependencies:
+
+```sh
+git clone https://github.com/sovorn-c/pi-ketch.git
+cd pi-ketch
+npm install
+```
+
+Run the complete local check:
+
+```sh
+npm run validate
+```
+
+This runs the TypeScript checker, unit tests, and `npm pack --dry-run`.
+
+## Repository layout
+
+- `src/tools/`: Pi tool definitions and Ketch argument builders
+- `src/schemas.ts`: tool input schemas and limits
+- `src/ketch.ts`: process execution, cancellation, timeouts, and crawl streaming
+- `src/output.ts`: output bounds and temporary-file handling
+- `src/format.ts`: model-facing Markdown formatting
+- `src/render.ts`: Pi TUI rendering
+- `skills/ketch/`: agent routing and research guidance
+- `test/`: argument, process, and output tests
+
+## Testing changes
+
+The unit tests use a fake Ketch executable. They do not require network access, credentials, Chromium, or a configured Ketch installation.
+
+Add or update tests when changing:
+
+- tool parameters or defaults
+- generated CLI arguments
+- validation and incompatible-option rules
+- exit-code handling
+- cancellation or timeout behavior
+- crawl and output bounds
+- formatted result shapes
+
+Live tests are optional and should remain small. Use low result counts, short crawls, and public test pages. Never add API keys, tokens, local configuration, cache data, or machine-specific browser paths to the repository.
+
+To load the checkout directly in Pi:
+
+```sh
+pi --no-extensions -e ./src/index.ts
+```
+
+Useful operator checks include:
+
+```sh
+ketch version
+ketch doctor
+```
+
+A failed optional backend is not automatically a `pi-ketch` failure. Confirm that the backend is configured, then reproduce the call with Ketch directly.
+
+## Change guidelines
+
+- Keep tool inputs bounded and preserve the limits in `src/schemas.ts`.
+- Spawn commands without a shell and keep free-form input after `--`.
+- Preserve cancellation, timeout, and Ketch exit-code behavior.
+- Accept only HTTP and HTTPS URLs for scrape and crawl inputs.
+- Treat fetched content as untrusted data, not agent instructions.
+- Keep routine search provider-neutral. The operator chooses the default backend; agents should not hardcode one.
+- Separate operator setup instructions from agent behavior in documentation and skills.
+- Avoid adding another service SDK when Ketch already exposes the capability through its CLI.
+
+## Pull requests
+
+Before submitting a pull request:
+
+1. Keep the change focused and explain the user-visible behavior.
+2. Add tests for changed behavior or explain why no test is needed.
+3. Run `npm run validate`.
+4. Update the README or bundled skill when tool behavior changes.
+5. Confirm that no credentials, local paths, generated archives, or cache files are included.
+
+Maintainers handle version bumps, npm publishing, and release tags. Contributors should not change the package version unless a maintainer asks them to.

package/SECURITY.md

@@ -0,0 +1,81 @@
+# Security policy
+
+## Supported versions
+
+`pi-ketch` is a small community package and supports only its latest npm release.
+
+| Version | Security fixes |
+| --- | --- |
+| Latest npm release | Yes |
+| Older releases | No |
+
+Before reporting a problem, confirm the installed version with:
+
+```sh
+npm view pi-ketch version
+node -p "require('$HOME/.pi/agent/npm/node_modules/pi-ketch/package.json').version"
+```
+
+## Report a vulnerability
+
+Do not open a public issue for a suspected vulnerability. Use [GitHub private vulnerability reporting](https://github.com/sovorn-c/pi-ketch/security/advisories/new).
+
+Include enough information to reproduce and assess the report:
+
+- the `pi-ketch`, Pi, Ketch, Node.js, and operating-system versions
+- the affected tool and parameters, with secrets removed
+- expected and observed behavior
+- a minimal reproduction or proof of concept
+- the likely impact
+- whether the behavior also occurs when running Ketch directly
+
+Maintainers will respond and coordinate a fix on a best-effort basis. Please allow time for investigation before publishing details.
+
+## Reporting scope
+
+Report problems here when they are caused by the Pi adapter, including:
+
+- command or argument injection
+- a URL validation bypass
+- credentials or sensitive local data appearing in tool output
+- failures in output bounds, crawl limits, cancellation, or timeout enforcement that create a security impact
+- unsafe temporary-file handling
+- misleading agent guidance that causes a concrete security boundary to be bypassed
+
+If a direct Ketch CLI command reproduces the vulnerability, report it privately to the [Ketch maintainers](https://github.com/1broseidon/ketch/security) as well. Vulnerabilities in Pi itself belong in the [Pi repository](https://github.com/badlogic/pi-mono). Provider account and API issues should be reported to that provider.
+
+The following are usually operational problems rather than vulnerabilities:
+
+- a missing API key or optional backend
+- an unreachable self-hosted service
+- a search provider returning poor or unexpected results
+- authentication, CAPTCHA, rate-limit, or anti-bot failures
+- a target page returning malicious or inaccurate text without escaping the documented untrusted-content boundary
+
+## Security boundaries
+
+### Package execution
+
+Pi packages run with the user's permissions. `pi-ketch` launches the configured Ketch executable directly, without a shell, and places free-form query input after `--`. The `KETCH_BIN` environment variable is operator-controlled and must point to a trusted executable.
+
+### Network access and SSRF
+
+Scrape and crawl inputs accept only absolute HTTP and HTTPS URLs. This protocol check is not complete SSRF protection. Ketch can reach loopback addresses, private networks, cloud metadata services, and other HTTP services available from the host.
+
+Do not expose these tools to untrusted users on a privileged network. Use network isolation or a sandbox when stronger outbound-access controls are required.
+
+### Untrusted content
+
+Search results and fetched pages are untrusted data. They may contain prompt injection, misleading instructions, or hostile markup. Agents must use the content as research material and must not treat it as system or operator instructions.
+
+### Credentials and configuration
+
+`pi-ketch` uses Ketch's existing configuration, environment variables, and supported credential sources such as the `gh` CLI. It does not copy API keys into Pi settings. Do not include credentials in prompts, bug reports, test fixtures, screenshots, or committed configuration.
+
+### Browser rendering
+
+Forced browser rendering starts the Chromium executable configured in Ketch. Browser rendering does not bypass authentication, CAPTCHAs, or strong anti-bot controls. Keep Chromium updated and do not configure an untrusted browser binary.
+
+### Cache and temporary output
+
+Ketch maintains a local page cache. When formatted output exceeds Pi's visible limit, `pi-ketch` may save the full result to a temporary file so Pi can read it later. Cached pages and temporary files can contain sensitive fetched content. Avoid scraping private pages unless the host and local storage are trusted, and remove sensitive cache or temporary data according to your operating environment's policy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ketch",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Agent-native web research tools for Pi: multi-backend search, public code search, library docs, scraping, crawling, and browser rendering, powered by Ketch.",
   "type": "module",
   "license": "MIT",
@@ -28,6 +28,8 @@
     "src/",
     "skills/",
     "README.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
     "LICENSE",
     "tsconfig.json"
   ],