pilotignore 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project follows [Semantic Versioning](https://semver.org/).
+
+## [0.2.0] - 2026-10-10
+
+A rewrite of the rule engine and hook, plus a `verify` command and a test setup for trying pilotignore with a real Copilot agent.
+
+### Upgrading from 0.1.x
+
+1. Update the package and **re-run `npx pilotignore init`**. The hook script in `.github/hooks/` is a copy and won't update otherwise. Your `.pilotignore` is left untouched.
+2. **Check rules that contain a `/`.** These are now anchored to the project root, as in `.gitignore` (see *Changed*). To keep matching at any depth, prefix them with `**/`, e.g. `config/secrets.json` → `**/config/secrets.json`.
+3. **Add the new self-protection rules** to your existing `.pilotignore`. New installs get them by default, but `init` never edits an existing file:
+   ```text
+   .pilotignore
+   .github/hooks/pilotignore.cjs
+   .github/hooks/pilotignore.json
+   ```
+4. Run `npx pilotignore verify` to confirm everything works.
+
+### Changed
+
+- **Rules follow `.gitignore` semantics.** Previously a rule matched by plain path comparison (exact path, path prefix, or path suffix). Now:
+  - A rule with a `/` anywhere in it is **anchored to the project root**. `config/secrets.json` no longer matches `nested/config/secrets.json`; use `**/config/secrets.json` for that. **This can change what an existing rule blocks.**
+  - A rule without a `/` matches that name at any depth, as before.
+  - The last matching rule wins, so `!` negations can re-allow paths.
+- **Allowed tool calls produce no output.** 0.1.x printed an explicit `allow` decision, which could auto-approve tool calls and skip Copilot's own approval prompts. The hook now stays silent unless it denies, so Copilot's normal permission flow applies. pilotignore only ever takes permissions away.
+- **Errors fail closed.** If the hook can't evaluate a call (malformed or empty payload, unreadable `.pilotignore`, unexpected error), the call is now denied instead of allowed. This matches how Copilot treats a failing `preToolUse` hook.
+- **Shell commands are scanned.** Paths inside shell commands are now checked as well, so `cat .env` is denied like a file read. A command that only *mentions* a blocked name (e.g. `git commit -m "fix .env"`) is denied too.
+- **Deny reasons name the path and rule**, e.g. `Access to '.env' is blocked by .pilotignore rule '.env'.` Previously the reason was a generic message.
+- **The default `.pilotignore` protects pilotignore itself.** New installs block reading or changing `.pilotignore` and the two hook files, and include a commented pattern-syntax reference.
+- **Package layout:** the hook moved from `templates/pilotignore.cjs` to `src/pilotignore.cjs`, and the templates to `src/templates/`. Installed files in your project keep their names and locations.
+- **Node.js >= 20** is now declared in `engines`. CI tests Node 20, 22 and 24 on Linux, macOS and Windows.
+- The `main` field was removed from `package.json`. pilotignore is a CLI, not a library, and importing it used to run the CLI. The `pilotignore` command is unaffected.
+- The package description and README now describe pilotignore as a tool-call filter rather than a complete secrets boundary.
+
+### Added
+
+- **`.gitignore`-style patterns:** `*`, `**`, `?`, `[abc]` / `[!abc]` character classes, `!` negation, leading `/` anchoring, trailing `/` directory-only rules, `\` escapes. Matching stays case-insensitive.
+- **Shell glob expansion:** a token like `shop*`, `*.tx?` or `[s]ecret.json` is expanded against the filesystem, so `cat shop*` is denied when it would match a blocked file.
+- **Directory protection:** commands on a directory that contains a blocked path are denied, e.g. `rm -rf .github` or `ls private`. Anchored rules protect their parent directories even before the file exists. The project root is exempt so ordinary commands keep working. Scans stop after 5,000 entries to stay well within the hook timeout.
+- **More path sources:** `~/` home paths, Windows-style `\` separators, paths outside the project (`../…`), `tool_input_as_string` payloads, and command-style fields (`command`, `args`, `script`, …) in any payload shape.
+- **Both hook output formats:** deny decisions are emitted as flat fields for Copilot CLI and inside `hookSpecificOutput` for VS Code. Copilot CLI now shows the deny reason; in 0.1.x it reported that no reason was given.
+- **Cloud-agent-ready hook config:** the cross-platform `command` field was added next to `bash` / `powershell` in `.github/hooks/pilotignore.json`. Cloud agent support is untested.
+- **`pilotignore verify`:** checks the hook config, hook script and rules, then fires real hook calls using your own rules. A read and a `cat` of a blocked path must be denied, and an unrelated path must be allowed.
+- **`pilotignore help`** and usage output for unknown commands.
+- **Clearer logs:** the log records each matched path and rule, and silent allows.
+- **Docs:** pattern-syntax reference, per-surface support table, *Good to know* section on what tool-call filtering can't cover (content search, workspace index, open files, indirect reads) and how to cover it, design decisions, troubleshooting, uninstall, and a [testing guide](tests/README.md).
+- **Development tooling:**
+  - `npm run smoke` packs the package, installs the tarball into a scratch project and exercises `init`, the hook and `verify`.
+  - `npm run sandbox` creates *recipe-box*, a realistic demo project for hands-on testing with Copilot Chat and Copilot CLI.
+  - The automated test suite grew from 10 to 28 tests.
+
+### Fixed
+
+- Rules with a leading `/` (e.g. `/config.json`) never matched in 0.1.x. They now match at the project root.
+- `npm test` failed on Node.js 22 because `tests/` was passed as a module path.
+- The repository's `.gitignore` referenced a non-existent `pilotignore.js` instead of `pilotignore.cjs`.
+- `package-lock.json` still listed version 0.1.0.
+
+### Removed
+
+- Screenshots in the README, replaced with text examples.
+
+### Known limitations
+
+These are documented in the README under *Good to know*:
+
+- Content searches such as `grep -r term .` can return lines from blocked files.
+- The VS Code workspace index, open editor files and inline suggestions don't go through tool calls.
+- Paths built at runtime by scripts or interpreters aren't recognized.
+- Copilot skips hooks that time out (fail-open). This is Copilot's behavior.
+
+## [0.1.2] and earlier
+
+Initial releases: `pilotignore init`, a `preToolUse` hook with exact-path and folder matching, logging to `.copilot/logs/`, and `.gitignore` setup.
+
+[0.2.0]: https://github.com/vkerttula/pilotignore/compare/9c335f9...v0.2.0
+[0.1.2]: https://github.com/vkerttula/pilotignore/commit/9c335f9

package/LICENSE

@@ -1,7 +1,7 @@
-Copyright (c) 2026 Valtteri Kerttula
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Copyright (c) 2026 Valtteri Kerttula
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,152 +1,155 @@
-<p align="center">
-  <img src="https://raw.githubusercontent.com/vkerttula/pilotignore/main/assets/logo.svg" alt="pilotignore logo" width="120" height="156">
-</p>
-
-</p>
-
-<h1 align="center">
-
-`.pilotignore` — keep your secrets secret
-
-</h1>
-
-<p align="center">
-  <strong>like <code>.gitignore</code>, but for github copilot agents</strong>
-</p>
-
-> [!WARNING]
->
-> **EARLY DEVELOPMENT/EXPERIMENTAL PHASE. USE AT YOUR OWN RISK.**
->
-> This project is currently in active development and still contain bugs or unhandled edge cases.
->
-> AI technologies and their capabilities are evolving rapidly and continuously, meaning new bypass methods could emerge. Use this tool strictly at your own risk. It is a supplementary security layer, not a silver bullet. Always follow best practices for secret management: use secure environment vaults, never commit hardcoded secrets to your repository, and **never expose data to an AI agent that you absolutely cannot afford to leak.** Be the boss of your agent, not the other way around.
-
-> [!TIP]
-> **Fun fact:** Some other AI coding assistants already have native, built-in features to prevent the AI from reading specific files. Until GitHub Copilot introduces an official, first-class `.copilotignore` feature, `pilotignore` is here to bridge the gap!
-
-GitHub Copilot Cloud Agent and CLI are powerful tools that can navigate your codebase, read files, and execute commands. But sometimes, they shouldn't see everything. `pilotignore` is a lightweight CLI that sets up a programmatic firewall — actively blocking AI agents from reading `.env` files, API keys, or private configs.
-
-One tool. One philosophy: **Agent boundaries should be simple.**
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/pilotignore"><img src="https://img.shields.io/npm/v/pilotignore?style=flat&color=000000" alt="NPM Version"></a>
-  <a href="https://www.npmjs.com/package/pilotignore"><img src="https://img.shields.io/npm/dt/pilotignore?style=flat&color=000000" alt="Downloads"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/github/license/vkerttula/pilotignore?style=flat&color=000000" alt="License"></a>
-</p>
-
-## Table of Contents
-
-<p align="center">
-  <a href="#before--after">Before/After</a> •
-  <a href="#install">Install</a> •
-  <a href="#what-you-get">What You Get</a> •
-  <a href="#how-it-works">How It Works</a> •
-  <a href="#roadmap">Roadmap</a>
-</p>
-
----
-
-## Before / After
-
-### 🔓 Normal Copilot Agent
-
-> **You:** "What is the database password inside config/secrets.json?"
-> **Copilot:** "Looking at your `config/secrets.json` file, the database password is `super_secret_p4ssw0rd`. I can help you rotate this if you need!"
-
-### 🛡️ Copilot + pilotignore
-
-> **You:** "What is the database password inside config/secrets.json?"
-> **Copilot:** "I'm sorry, I cannot access `config/secrets.json` because my file-reading tool was denied by your `.pilotignore` rules."
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/vkerttula/pilotignore/main/assets/copilot-vscode.png" alt="Copilot VS Code Chat blocked" width="49%">
-  &nbsp;
-  <img src="https://raw.githubusercontent.com/vkerttula/pilotignore/main/assets/copilot-cli.png" alt="Copilot CLI blocked" width="49%">
-</p>
-
-**Same agent. 0% leaked secrets. Peace of mind.**
-
-## Install
-
-Install `pilotignore` as a development dependency. This ensures your project is locked to a specific version and makes updates seamless.
-
-```bash
-# 1. Install the package
-npm install -D pilotignore
-
-# 2. Initialize the hooks and .pilotignore file
-npx pilotignore init
-
-```
-
-## What You Get
-
-After initialization, your project will have the following structure:
-
-```text
-project-root/
-├── .github/
-│   └── hooks/
-│       └── pilotignore.json   <-- Tells Copilot to run the firewall from node_modules
-├── .copilot/
-│   └── logs/
-│       └── pilotignore.log    <-- Action logs accumulate here (automatically added to your .gitignore!)
-├── .pilotignore               <-- Add your sensitive files/folders to this blocklist
-└── package.json               <-- pilotignore is installed as a devDependency
-
-```
-
-Simply add your sensitive files to the generated `.pilotignore` file at the root of your project:
-
-```text
-# Add files here to hide them from GitHub Copilot
-# Examples:
-# secrets.json
-# .env
-# Block from reading this file
-.pilotignore
-
-```
-
-Commit the `.pilotignore` file and the generated `.github/hooks/` directory configuration to Git. That's it.
-
-| Target               | Status         | Note                                                                                                |
-| -------------------- | -------------- | --------------------------------------------------------------------------------------------------- |
-| **Copilot CLI**      | 🛡️ Blocked     | Local commands (`view`, `read_file`) are intercepted.                                               |
-| **IDE Chat**         | 🛡️ Blocked     | Agentic workspace reads are stopped at the tool level.                                              |
-| **Cloud Agent**      | ⏳ Coming soon | Support for GitHub's secure cloud sandbox (see V2 roadmap).                                         |
-| **IDE Autocomplete** | ⏳ Coming soon | Ghost-text autocomplete does not use tools (see V3 roadmap). Already possible with vscode settings. |
-
-## How It Works
-
-1. You install the package and run `npx pilotignore init`.
-2. The tool drops an official Copilot Hooks API configuration script into `.github/hooks/pilotignore.json` that points to the local `node_modules` package.
-3. When a Copilot Agent tries to run a tool (like `view` to read a file), the `preToolUse` hook fires.
-4. If the target file matches an entry in your `.pilotignore`, the hook forcefully returns a `{"permissionDecision": "deny"}` JSON payload and a non-zero exit code.
-5. The Agent gracefully backs off. No files read.
-
-> [!IMPORTANT]
-> While `pilotignore` blocks native file-reading tools, an extremely determined AI could theoretically write a custom script to read a file and execute it via `bash`. **We block the front door, but complex workarounds are always a possibility with AI.** Use at your own risk, and ensure you understand the limitations of agentic boundaries. This is the closest to native, code-level blocking we've achieved so far — be the boss of your agent, not the other way around.
-
-## Roadmap
-
-- [x] Block Copilot Cloud Agent & CLI tools via `preToolUse` hooks.
-- [x] Basic exact-path and glob matching.
-- [ ] **V1.1:** Add global installation support (`pilotignore init --global`) for user-level protection across all local repositories.
-- [ ] **V2:** Cloud Agent support (syncing hooks to GitHub's secure cloud sandbox).
-- [ ] **V2:** Inject `.pilotignore` rules into Copilot Chat's `custom instructions` for double redundancy.
-- [ ] **V3:** Sync `.pilotignore` rules to `.vscode/settings.json` to automatically disable IDE ghost-text autocomplete for sensitive files.
-
-## Links
-
-- [GitHub Copilot Hooks Reference](https://docs.github.com/en/copilot/reference/hooks-reference) — the underlying API
-- [Issues](https://github.com/vkerttula/pilotignore/issues) — bug, feature, weird behavior
-
-## Star This Repo
-
-`.pilotignore` keeps your secrets secret. Star cost zero. Fair trade. ⭐
-
-## License
-
-MIT
+<p align="center">
+  <img src="https://raw.githubusercontent.com/vkerttula/pilotignore/main/assets/logo.svg" alt="pilotignore logo" width="120" height="156">
+</p>
+
+<h1 align="center">
+
+`.pilotignore`
+
+</h1>
+
+<p align="center">
+  <strong>like <code>.gitignore</code>, but for GitHub Copilot agents</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/pilotignore"><img src="https://img.shields.io/npm/v/pilotignore?style=flat&color=000000" alt="NPM Version"></a>
+  <a href="https://www.npmjs.com/package/pilotignore"><img src="https://img.shields.io/npm/dt/pilotignore?style=flat&color=000000" alt="Downloads"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/vkerttula/pilotignore?style=flat&color=000000" alt="License"></a>
+</p>
+
+Copilot agents read files and run commands in your project. `pilotignore` lets you list the files they should leave alone. It installs a Copilot `preToolUse` hook that checks every tool call before it runs and denies the ones that touch a path in your `.pilotignore`. Everything else works exactly as before.
+
+It's a small, zero-dependency tool for keeping an agent out of files it has no business opening: personal notes, local configs, drafts, generated data. It filters tool calls; it doesn't control everything Copilot can see (see [Good to know](#good-to-know)).
+
+## Quick start
+
+```bash
+npm install -D pilotignore
+npx pilotignore init      # adds the hook and a .pilotignore file
+npx pilotignore verify    # checks that blocking actually works
+```
+
+Add paths to `.pilotignore`, then commit it together with `.github/hooks/`.
+
+## Try it first
+
+Want to see it block a real agent before adding it to your project?
+
+```bash
+git clone https://github.com/vkerttula/pilotignore && cd pilotignore
+npm run sandbox
+```
+
+This creates a small demo project with pilotignore installed. Open it in VS Code or Copilot CLI and follow the test prompts in [`tests/README.md`](tests/README.md#test-prompts).
+
+## Writing rules
+
+`.pilotignore` uses `.gitignore` syntax:
+
+```text
+.env                   # this name, at any depth
+*.pem                  # any file ending in .pem
+.env*                  # .env, .env.local, .env.production, ...
+/config.json           # only at the project root
+private/               # everything under any private/ directory
+notes/**               # everything under the root notes/
+!notes/public.md       # ...except this file
+```
+
+Matching is case-insensitive. The default `.pilotignore` also lists itself and the hook files, so the agent can't read the rules, change them, or remove the hook.
+
+## What it looks like
+
+When the agent tries to open a blocked file, the hook denies the tool call and tells the agent why. In Copilot CLI (abbreviated):
+
+```text
+● Read shopping-list.txt
+  Denied by preToolUse hook: Access to 'shopping-list.txt' is blocked by
+  .pilotignore rule 'shopping-list.txt'.
+```
+
+Shell commands are checked too, including globs and directories:
+
+```text
+$ cat shop*            → denied (shopping-list.txt)
+$ rm -rf .github       → denied (contains .github/hooks/pilotignore.cjs)
+$ npm start            → allowed, Copilot asks for approval as usual
+```
+
+Every decision is logged to `.copilot/logs/pilotignore.log`, which `init` adds to your `.gitignore`:
+
+```text
+[2026-10-10T14:02:11.482Z] Candidate paths: ["shopping-list.txt"]
+[2026-10-10T14:02:11.483Z] DECISION: DENY (Blocked) - shopping-list.txt matched rule 'shopping-list.txt'.
+```
+
+## Where it works
+
+| Copilot surface | Status |
+| --- | --- |
+| **Copilot CLI** | ✅ Supported and tested |
+| **VS Code Copilot Chat, agent mode** | ✅ Tested. VS Code agent hooks are in Preview. |
+| **Copilot cloud agent** | Should work (it runs `.github/hooks`), not yet tested |
+| **Inline suggestions, workspace index, open editor files** | ❌ Not covered. These don't go through tool calls. |
+
+## Good to know
+
+pilotignore only sees **tool calls**. Some ways content reaches Copilot don't involve a tool call it can filter:
+
+- **Content searches.** `grep -r milk .` or the agent's search tool can return matching lines from blocked files without opening them, because the search command itself names no blocked path.
+- **Workspace index and open files.** VS Code indexes your workspace for semantic search, and the file open in your editor is sent as context. Neither goes through a hook.
+- **Indirect reads.** A script or interpreter that builds the path at runtime, for example `python3 -c "open('se'+'crets.json').read()"`, isn't recognized.
+
+To cover these as well, also add sensitive paths to `.gitignore` or VS Code's `files.exclude` / `search.exclude` settings. Those keep them out of the index and search results. Organizations on Copilot Business or Enterprise can additionally use GitHub's [content exclusion](https://docs.github.com/en/copilot/concepts/context/content-exclusion). And as always, real credentials belong in a secret manager, not in a workspace an agent works in.
+
+## How it works
+
+`init` writes two files: `.github/hooks/pilotignore.json` registers the hook with Copilot, and `.github/hooks/pilotignore.cjs` is the hook itself. Before each tool call, Copilot passes the call's arguments to the hook. The hook collects every path in them, including paths inside shell commands, and checks them against `.pilotignore`.
+
+A few deliberate design choices:
+
+- **Silent allow.** If nothing matches, the hook prints nothing. Copilot's normal approval prompts and tool rules apply as if pilotignore weren't there. It only ever takes permissions away.
+- **Fail-closed.** If the hook can't evaluate a call (malformed input, unreadable rules), the call is denied. This matches how Copilot treats a failing `preToolUse` hook. One exception comes from Copilot itself: a hook that times out is skipped, so the hook is built to finish well within its 5-second limit.
+- **Shell-aware.** Commands are split into tokens. Globs like `cat shop*` are expanded against the filesystem, and operations on a directory that contains blocked paths (`rm -rf .github`) are denied. The project root is exempt, so `ls .` keeps working.
+- **Explains itself.** A deny always names the rule that matched, so you can tell exactly why a call was blocked.
+- **Errs on the side of blocking.** A command that only *mentions* a blocked name, like `git add .pilotignore`, is denied too. Commit changes to your ruleset yourself.
+
+## Troubleshooting
+
+- **Run `npx pilotignore verify`.** It checks the setup and fires test calls at the installed hook using your own rules.
+- **Nothing in the log** means Copilot didn't run the hook. Check that `.github/hooks/pilotignore.json` exists and that hooks aren't disabled in your Copilot settings.
+- **A blocked file shows `ALLOW` in the log** means the path wasn't found in the tool call. Please [open an issue](https://github.com/vkerttula/pilotignore/issues) with the log lines.
+- **After upgrading pilotignore**, run `npx pilotignore init` again to update the hook script. Your `.pilotignore` is never overwritten. Check the [changelog](CHANGELOG.md) for rule changes.
+
+## Uninstall
+
+```bash
+npm uninstall pilotignore
+rm .pilotignore .github/hooks/pilotignore.json .github/hooks/pilotignore.cjs
+```
+
+Optionally remove `.copilot/logs/pilotignore.log` and the `# pilotignore logs` entry from your `.gitignore`.
+
+## Roadmap
+
+- [x] Block Copilot CLI and VS Code agent tool calls via `preToolUse` hooks
+- [x] `.gitignore`-style rules, shell scanning, directory protection, `verify` (v0.2.0)
+- [ ] Test and document Copilot cloud agent
+- [ ] Optionally sync rules to VS Code `search.exclude` / `files.exclude` to cover search and indexing
+- [ ] Explore filtering blocked files out of search results with a `postToolUse` hook
+
+## Development
+
+```text
+bin/cli.js            CLI: init and verify
+src/pilotignore.cjs   the hook (copied into projects by init)
+src/templates/        hook config and default .pilotignore
+tests/                automated tests, smoke test and a sandbox demo project
+```
+
+`npm test` runs the test suite. [`tests/README.md`](tests/README.md) covers the smoke test and hands-on testing with Copilot in a ready-made demo project.
+
+## License
+
+[MIT](LICENSE). The software is provided "as is", without warranty of any kind, and the authors aren't liable for any damages arising from its use. See the license for the full terms.