@codersbrew/pi-tools 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CodersBrew
+
+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,118 @@
+# @codersbrew/pi-tools
+
+A publishable [pi](https://github.com/badlogic/pi-mono) package that bundles CodersBrew's custom pi extensions.
+
+## Included extensions
+
+### `security`
+Protects common dangerous tool operations by:
+- warning or blocking risky `bash` commands such as `rm -rf`, `sudo`, and destructive disk operations
+- blocking writes to sensitive paths like `.env`, `.git`, `node_modules`, SSH keys, and common secrets files
+- prompting before lockfile edits such as `package-lock.json`, `yarn.lock`, and `pnpm-lock.yaml`
+
+### `session-breakdown`
+Adds an interactive TUI for analyzing pi session history from `~/.pi/agent/sessions`, including:
+- sessions, messages, tokens, and cost over the last 7 / 30 / 90 days
+- model, cwd, day-of-week, and time-of-day breakdowns
+- contribution-style heatmap visualizations
+
+## Install
+
+Global install:
+
+```bash
+pi install npm:@codersbrew/pi-tools
+```
+
+Project-local install:
+
+```bash
+pi install -l npm:@codersbrew/pi-tools
+```
+
+You can also add it manually to pi settings:
+
+```json
+{
+  "packages": ["npm:@codersbrew/pi-tools"]
+}
+```
+
+## Package structure
+
+This package uses pi's standard package manifest:
+- `extensions/security.ts`
+- `extensions/session-breakdown.ts`
+
+The root `package.json` exposes them through:
+
+```json
+{
+  "pi": {
+    "extensions": ["./extensions"]
+  }
+}
+```
+
+## Local development
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Run local verification:
+
+```bash
+npm run check
+```
+
+Preview the publish tarball:
+
+```bash
+npm pack --dry-run
+```
+
+## Releasing
+
+This repo includes `.github/workflows/release.yml`.
+
+### First release bootstrap
+
+Because npm trusted publishing is configured per existing package, the **first publish** of a brand new package must use an `NPM_TOKEN` GitHub secret.
+
+Bootstrap steps for `@codersbrew/pi-tools`:
+
+1. Create an npm access token with publish rights
+2. Add it to the GitHub repo as `NPM_TOKEN`
+3. Confirm `package.json` has the intended version, currently `0.1.0`
+4. Push a version tag such as `v0.1.0`
+5. GitHub Actions will verify the package, publish it, and create a GitHub release
+
+### Switch to trusted publishing after first release
+
+After the package exists on npm, configure npm Trusted Publisher for this repository:
+
+- **Provider:** GitHub Actions
+- **Organization or user:** `codersbrew`
+- **Repository:** `pi-tools`
+- **Workflow filename:** `release.yml`
+- **Environment name:** leave blank unless you later add a GitHub Environment
+
+After trusted publishing is configured, remove the `NPM_TOKEN` secret if you want future releases to publish via GitHub OIDC instead of a token.
+
+### Ongoing release flow
+
+1. Update the package version in `package.json`
+2. Commit and push the change
+3. Create and push a matching version tag such as `v0.1.1`
+4. GitHub Actions will run verification, publish to npm, and create a GitHub release
+
+The workflow uses Node 24 so the npm CLI is new enough for trusted publishing and provenance support.
+
+If you use manual dispatch, ensure the version in `package.json` has not already been published.
+
+## License
+
+MIT

package/extensions/security.ts

@@ -0,0 +1,113 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import * as path from "node:path";
+
+/**
+ * Comprehensive security hook:
+ * - Blocks dangerous bash commands (rm -rf, sudo, chmod 777, etc.)
+ * - Protects sensitive paths from writes (.env, node_modules, .git, keys)
+ */
+export default function (pi: ExtensionAPI) {
+  const dangerousCommands = [
+    { pattern: /\brm\s+(-[^\s]*r|--recursive)/, desc: "recursive delete" }, // rm -rf, rm -r, rm --recursive
+    { pattern: /\bsudo\b/, desc: "sudo command" }, // sudo anything
+    { pattern: /\b(chmod|chown)\b.*777/, desc: "dangerous permissions" }, // chmod 777, chown 777
+    { pattern: /\bmkfs\b/, desc: "filesystem format" }, // mkfs.ext4, mkfs.xfs
+    { pattern: /\bdd\b.*\bof=\/dev\//, desc: "raw device write" }, // dd if=x of=/dev/sda
+    { pattern: />\s*\/dev\/sd[a-z]/, desc: "raw device overwrite" }, // echo x > /dev/sda
+    { pattern: /\bkill\s+-9\s+-1\b/, desc: "kill all processes" }, // kill -9 -1
+    { pattern: /:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;/, desc: "fork bomb" }, // :(){:|:&};:
+  ];
+
+  const protectedPaths = [
+    { pattern: /\.env($|\.(?!example))/, desc: "environment file" }, // .env, .env.local (but not .env.example)
+    { pattern: /\.dev\.vars($|\.[^/]+$)/, desc: "dev vars file" }, // .dev.vars
+    { pattern: /node_modules\//, desc: "node_modules" }, // node_modules/
+    { pattern: /^\.git\/|\/\.git\//, desc: "git directory" }, // .git/
+    { pattern: /\.pem$|\.key$/, desc: "private key file" }, // *.pem, *.key
+    { pattern: /id_rsa|id_ed25519|id_ecdsa/, desc: "SSH key" }, // id_rsa, id_ed25519
+    { pattern: /\.ssh\//, desc: ".ssh directory" }, // .ssh/
+    { pattern: /secrets?\.(json|ya?ml|toml)$/i, desc: "secrets file" }, // secrets.json, secret.yaml
+    { pattern: /credentials/i, desc: "credentials file" }, // credentials, CREDENTIALS
+  ];
+
+  const softProtectedPaths = [
+    { pattern: /package-lock\.json$/, desc: "package-lock.json" },
+    { pattern: /yarn\.lock$/, desc: "yarn.lock" },
+    { pattern: /pnpm-lock\.yaml$/, desc: "pnpm-lock.yaml" },
+  ];
+
+  const dangerousBashWrites = [
+    />\s*\.env(?!\.example)(\b|$)/, // echo x > .env, .env.local (but not .env.example)
+    />\s*\.dev\.vars/, // echo x > .dev.vars
+    />\s*.*\.pem/, // echo x > key.pem
+    />\s*.*\.key/, // echo x > secret.key
+    /tee\s+.*\.env(?!\.example)(\b|$)/, // cat x | tee .env, .env.local (but not .env.example)
+    /tee\s+.*\.dev\.vars/, // cat x | tee .dev.vars
+    /cp\s+.*\s+\.env(?!\.example)(\b|$)/, // cp x .env, .env.local (but not .env.example)
+    /mv\s+.*\s+\.env(?!\.example)(\b|$)/, // mv x .env, .env.local (but not .env.example)
+  ];
+
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName === "bash") {
+      const command = event.input.command as string;
+
+      for (const { pattern, desc } of dangerousCommands) {
+        if (pattern.test(command)) {
+          if (!ctx.hasUI) {
+            return { block: true, reason: `Blocked ${desc} (no UI to confirm)` };
+          }
+
+          const ok = await ctx.ui.confirm(`⚠️ Dangerous command: ${desc}`, command);
+
+          if (!ok) {
+            return { block: true, reason: `Blocked ${desc} by user` };
+          }
+          break;
+        }
+      }
+
+      for (const pattern of dangerousBashWrites) {
+        if (pattern.test(command)) {
+          ctx.ui.notify(`🛡️ Blocked bash write to protected path`, "warning");
+          return { block: true, reason: "Bash command writes to protected path" };
+        }
+      }
+
+      return undefined;
+    }
+
+    if (event.toolName === "write" || event.toolName === "edit") {
+      const filePath = event.input.path as string;
+      const normalizedPath = path.normalize(filePath);
+
+      for (const { pattern, desc } of protectedPaths) {
+        if (pattern.test(normalizedPath)) {
+          ctx.ui.notify(`🛡️ Blocked write to ${desc}: ${filePath}`, "warning");
+          return { block: true, reason: `Protected path: ${desc}` };
+        }
+      }
+
+      for (const { pattern, desc } of softProtectedPaths) {
+        if (pattern.test(normalizedPath)) {
+          if (!ctx.hasUI) {
+            return { block: true, reason: `Protected path (no UI): ${desc}` };
+          }
+
+          const ok = await ctx.ui.confirm(
+            `⚠️ Modifying ${desc}`,
+            `Are you sure you want to modify ${filePath}?`,
+          );
+
+          if (!ok) {
+            return { block: true, reason: `User blocked write to ${desc}` };
+          }
+          break;
+        }
+      }
+
+      return undefined;
+    }
+
+    return undefined;
+  });
+}