pilotignore 0.1.0

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,152 @@
+<p align="center">
+  <img src="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="assets/copilot-vscode.png" alt="Copilot VS Code Chat blocked" width="49%">
+  &nbsp;
+  <img src="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 (add this 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

package/assets/logo.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 130" width="120" height="156">
+  <path d="M 10,15 
+           L 90,15 
+           C 90,65 75,105 50,120 
+           C 25,105 10,65 10,15 
+           Z" 
+        fill="#000000" />
+</svg>

package/bin/cli.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+import fs from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+
+// ESM equivalents for __dirname
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+async function init() {
+  const args = process.argv.slice(2);
+
+  if (args[0] !== "init") {
+    console.log("Usage: npx pilotignore init");
+    process.exit(1);
+  }
+
+  const targetDir = process.cwd();
+  const githubHooksDir = path.join(targetDir, ".github", "hooks");
+  const templatesDir = path.join(__dirname, "..", "templates");
+
+  try {
+    // 1. Create the directory structure
+    await fs.mkdir(githubHooksDir, { recursive: true });
+    console.log("✅ Ensured directory: .github/hooks");
+
+    // 2. Copy the configuration file
+    await fs.copyFile(
+      path.join(templatesDir, "pilotignore.json"),
+      path.join(githubHooksDir, "pilotignore.json"),
+    );
+    console.log("✅ Copied: .github/hooks/pilotignore.json");
+
+    // 3. Copy the actual firewall script
+    await fs.copyFile(
+      path.join(templatesDir, "pilotignore.js"),
+      path.join(githubHooksDir, "pilotignore.js"),
+    );
+    console.log("✅ Copied: .github/hooks/pilotignore.js");
+
+    // 4. Create .pilotignore only if it doesn't exist
+    const targetPilotignore = path.join(targetDir, ".pilotignore");
+    try {
+      await fs.access(targetPilotignore);
+      console.log("ℹ️  .pilotignore already exists, skipping creation.");
+    } catch {
+      await fs.copyFile(
+        path.join(templatesDir, "default.pilotignore"),
+        targetPilotignore,
+      );
+      console.log("✅ Created default file: .pilotignore");
+    }
+
+    console.log("\n🚀 pilotignore initialization complete!");
+    console.log(
+      "Add your sensitive files to the .pilotignore file at the root of your project.",
+    );
+  } catch (error) {
+    console.error("❌ Installation error:", error.message);
+    process.exit(1);
+  }
+}
+
+init();

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "pilotignore",
+  "version": "0.1.0",
+  "description": "Prevent Copilot from reading your secrets using .pilotignore. Works like .gitignore but for GitHub Copilot.",
+  "type": "module",
+  "main": "bin/cli.js",
+  "bin": {
+    "pilotignore": "./bin/cli.js"
+  },
+  "keywords": [
+    "copilot",
+    "github",
+    "hook",
+    "ignore",
+    "security",
+    "copilotignore",
+    "firewall",
+    "agent",
+    "pre-tool-use",
+    "copilot-hooks"
+  ],
+  "author": "Valtteri Kerttula",
+  "license": "MIT"
+}

package/templates/default.pilotignore

@@ -0,0 +1,6 @@
+# Add files here to hide them from GitHub Copilot
+# Examples:
+# secrets.json
+# .env
+# Block from reading this file
+.pilotignore

package/templates/pilotignore.js

@@ -0,0 +1,168 @@
+const fs = require("fs");
+const path = require("path");
+
+// Helper function for logging
+function appendLog(cwd, message) {
+  try {
+    const logDir = path.join(cwd, ".copilot", "logs");
+    const logFile = path.join(logDir, "pilotignore.log");
+
+    // Ensure the log directory exists
+    if (!fs.existsSync(logDir)) {
+      fs.mkdirSync(logDir, { recursive: true });
+    }
+
+    const timestamp = new Date().toISOString();
+    fs.appendFileSync(logFile, `[${timestamp}] ${message}\n`);
+  } catch (e) {
+    // If logging fails, do not crash the entire program
+  }
+}
+
+let input = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  input += chunk;
+});
+
+process.stdin.on("end", () => {
+  // Default cwd, updated if a better one is found in the payload
+  let currentCwd = process.cwd();
+  appendLog(currentCwd, `HOOK PROCESS STARTED (pid: ${process.pid})`);
+
+  try {
+    const payload = JSON.parse(input || "{}");
+    currentCwd = payload.cwd || currentCwd; // Use the project root
+
+    const candidates = [];
+    function collect(val) {
+      if (!val) return;
+      if (typeof val === "string") {
+        try {
+          const parsed = JSON.parse(val);
+          if (parsed && typeof parsed === "object") {
+            collect(parsed);
+            return;
+          }
+        } catch (e) {}
+        candidates.push(val);
+        return;
+      }
+      if (Array.isArray(val)) {
+        val.forEach(collect);
+        return;
+      }
+      if (typeof val === "object") {
+        Object.values(val).forEach(collect);
+        return;
+      }
+      candidates.push(String(val));
+    }
+
+    if (payload.tool_input) collect(payload.tool_input);
+    if (
+      payload.tool_input_as_string &&
+      typeof payload.tool_input_as_string === "string"
+    ) {
+      try {
+        collect(JSON.parse(payload.tool_input_as_string));
+      } catch (e) {}
+    }
+
+    if (payload.toolArgs) collect(payload.toolArgs);
+    if (payload.arguments) collect(payload.arguments);
+
+    if (candidates.length === 0) {
+      collect(payload);
+    }
+
+    [
+      "path",
+      "file",
+      "target",
+      "filePath",
+      "args",
+      "files",
+      "targetPath",
+      "file_path",
+    ].forEach((k) => collect(payload[k]));
+
+    appendLog(currentCwd, `Candidate paths: ${JSON.stringify(candidates)}`);
+
+    const ignoreRules = [];
+    const ignoreFilePath = path.join(currentCwd, ".pilotignore");
+    if (fs.existsSync(ignoreFilePath)) {
+      const content = fs.readFileSync(ignoreFilePath, "utf8");
+      content.split(/\r?\n/).forEach((line) => {
+        const trimmed = line.trim();
+        if (trimmed && !trimmed.startsWith("#")) ignoreRules.push(trimmed);
+      });
+      appendLog(
+        currentCwd,
+        `Loaded ${ignoreRules.length} rules from the .pilotignore file.`,
+      );
+    } else {
+      appendLog(
+        currentCwd,
+        `Warning: .pilotignore file not found at path ${ignoreFilePath}`,
+      );
+    }
+
+    const isBlocked = candidates.some((candidate) => {
+      if (!candidate.includes(path.sep) && !candidate.includes("/"))
+        return false;
+      const relative = path.relative(currentCwd, candidate).replace(/\\/g, "/");
+      return ignoreRules.some(
+        (rule) => relative.endsWith(rule) || relative === rule,
+      );
+    });
+
+    if (isBlocked) {
+      const reason = "File reading is blocked based on a .pilotignore rule.";
+      appendLog(
+        currentCwd,
+        `DECISION: DENY (Blocked) - Path found on the blocklist.`,
+      );
+
+      console.log(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "deny",
+            permissionDecisionReason: reason,
+          },
+        }),
+      );
+
+      console.error(reason);
+
+      if (input.includes("vscode") || input.includes("copilot-chat")) {
+        process.exit(0); // copilot chat VS Code IDE
+      } else {
+        process.exit(2); // copilot CLI
+      }
+    }
+
+    appendLog(currentCwd, `DECISION: ALLOW`);
+    console.log(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "allow",
+        },
+      }),
+    );
+    process.exit(0);
+  } catch (err) {
+    appendLog(currentCwd, `ERROR: ${err.message}`);
+    console.log(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "allow",
+        },
+      }),
+    );
+    process.exit(0);
+  }
+});

package/templates/pilotignore.json

@@ -0,0 +1,15 @@
+{
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      {
+        "type": "command",
+        "bash": "node .github/hooks/pilotignore.js",
+        "powershell": "node .github\\hooks\\pilotignore.js",
+        "windows": "node .github\\hooks\\pilotignore.js",
+        "cwd": ".",
+        "timeoutSec": 5
+      }
+    ]
+  }
+}

package/tests/README.md

@@ -0,0 +1 @@
+# Coming