@giuseppe.trisciuoglio/pi-prevent-destructive-commands 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- New per-project read-only mode (`/read-only on|off|status`): when enabled, every mutating tool call is blocked — `write`, `edit`, any patch-style tool (`*apply_patch`), `bash`, and `powershell` — while read-only tools (`read`, `grep`, `find`, `ls`) keep working. The flag lives in `.pi/prevent-destructive-commands.json` under `readOnly` (default `false` when the file is missing or invalid), `/read-only` toggles it while preserving unrelated JSON keys, and it is independent of the destructive-command, git, migration, Nx, and comment guards. Adds `test/read-only-command-test.ts` (`npm run test:read-only-command`) and `docs/adr/0001-read-only-mode.md`.
+- New guard: new comments in source files are blocked. Any tool call that would introduce a new comment into a source file (Java, TypeScript/JavaScript, Dart, Go, Rust, C/C++, C#, Swift, Kotlin, Scala, PHP, CSS/SCSS, Python, Ruby, shell, YAML, TOML, Terraform, GraphQL, SQL, Lua, Haskell, Elm, HTML/XML/SVG/Markdown) is stopped, covering `write`, `edit`, `apply_patch` (unified diff and `*** Begin Patch` formats), and bash write vectors (`cat > a.ts <<EOF`, `tee b.py <<EOF`, `echo "// x" >> c.ts`). Detection is string-aware (comment markers inside string literals are not comments), comments a file already contains may be carried over untouched, and shebang lines, tooling directives (`@ts-ignore`, `eslint-disable`, `biome-ignore`, `noqa`, …) and purely decorative lines are exempt. Opt out per project with `{"disableCommentGuard": true}` in the opt-out file. Adds `test/comment-guard-test.ts` (`npm run test:comment-guard`).
+- New guard: interactive `git commit` without a message option (bare `git commit`, `git commit -a`, `git commit --amend`, ...) is blocked because it opens the editor and hangs the session when the agent runs unattended. Applies unconditionally, even on projects that opted out of the git add/commit/push guards; commits with a message (`git commit -m x`, `-F file`, `--amend --no-edit`, ...) are unaffected.
+
+### Changed
+
+- Extracted shared helpers to remove all code clones reported by jscpd (≥ 50 tokens): `src/rules/args.ts` (positional-argument scanning and longest-subcommand matching for the checker and the aws/gh/file-reading rules), `src/patch-paths.ts` (patch/file-path extraction shared by the extension entry point and the Nx guard), `src/token-segments.ts` (command-chain segmentation for the bash-level guards), and `test/helpers.ts` (shared test utilities: `check`, `makeProject`, `isBlocked`, `runCheckCases`, `runIsolatedTest`). No behavior change.
+
 ## [1.2.0] - 2026-09-28
 
 ### Added

package/README.md

@@ -18,6 +18,8 @@ A faithful port of Claude's [`prevent-destructive-commands.py`](https://github.c
 - **Works in all modes** — Protection is active even in non-interactive sessions (`-p`, JSON, RPC).
 - **Recursive analysis** — Traverses command wrappers, shell invocations, pipelines, and nested commands to catch obfuscated attacks.
 - **Nx configuration guard** — In Nx workspaces, existing `package.json` and TypeScript configuration files are immutable to the agent; missing ones can still be created.
+- **Source comment guard** — The agent cannot introduce new comments into source files (Java, TypeScript, Dart, Python, SQL, HTML, and more) through writing tools or bash write vectors; existing comments may be carried over untouched and tooling directives (`@ts-ignore`, `eslint-disable`, …) stay allowed.
+- **Read-only mode** — `/read-only on` turns the project into an inspection-only workspace: `write`, `edit`, patch tools, `bash`, and `powershell` are blocked while `read`, `grep`, `find`, and `ls` keep working.
 - **Configurable** — Tune protection levels via simple flags in `src/config.ts`.
 - **Zero dependencies** — Lightweight, fast, and self-contained.
 - **79+ test cases** — Comprehensive smoke test suite validates all blocking rules.
@@ -30,6 +32,7 @@ All rules are defined in [`src/config.ts`](src/config.ts) and can be customized.
 |----------|----------|
 | **Destructive Git** | `git reset --hard`, `git clean`, `git push --force` / `-f` / `--delete`, `git branch -D`, `git tag -d`, `git checkout -f`, `git rebase`, `git filter-branch`, `git filter-repo`, `git reflog expire`, `git update-ref -d` |
 | **Git add/commit/push** | `git add`, `git commit`, `git push` *(see `ENABLE_GIT_ADD_COMMIT_BLOCK` flag and the per-project opt-out below; force/delete push variants are always blocked)* |
+| **Interactive git commit** | `git commit` without a message option (`-m`/`--message`, `-F`/`--file`, `-C`/`--reuse-message`, `-c`/`--reedit-message`, `--no-edit`, `--fixup`, or combined short forms like `-am`) — it would open the editor and hang the session. Always blocked, even when the project opts out of the git add/commit/push guards. |
 | **rm / path-sensitive** | `rm`, `rmdir`, `shred`, `unlink` targeting paths **outside** the working directory (e.g., `/etc`, `~`, `..`). Targets inside cwd are allowed. |
 | **find outside cwd** | `find` whose search root is **outside** the working directory (e.g., `find /etc`, `find ~`, `find ..`). Search roots inside cwd are allowed; `-exec` payloads are analyzed recursively as before. |
 | **Destructive Docker** | `docker rm` / `rmi`, `docker container/image/volume/network rm`, `docker * prune`, `docker compose down -v`, `docker compose rm`, `docker context rm`, `docker swarm leave --force` |
@@ -37,6 +40,7 @@ All rules are defined in [`src/config.ts`](src/config.ts) and can be customized.
 | **Destructive AWS CLI** | `aws s3 rm`, `aws ec2 terminate-instances`, `aws rds delete-db-instance`, `aws cloudformation delete-stack`, and 50+ more subcommands (full list in `src/config.ts`) |
 | **Sensitive file reads** | `cat`, `grep`, etc. on `.env`, SSH keys, `.pem` files — **disabled by default** via `ENABLE_SENSITIVE_FILE_CHECK` *(see Configuration)* |
 | **Existing Nx configuration** | `package.json`, `tsconfig.json`, `tsconfig.base.json`, `tsconfig.lib.json`, and `tsconfig.spec.json` anywhere below a workspace containing `nx.json`. Creating a missing file is allowed; changing or deleting an existing file is blocked. |
+| **New comments in source files** | Any tool call that introduces a **new** comment into a source file: `write`/`edit`/`apply_patch` touching Java, TypeScript/JavaScript, Dart, Go, Rust, C/C++, C#, Swift, Kotlin, Scala, PHP, CSS/SCSS, Python, Ruby, shell, YAML, TOML, Terraform, GraphQL, SQL, Lua, Haskell, Elm, HTML/XML/SVG/Markdown files, plus bash write vectors (`cat > a.ts <<EOF`, `tee b.py <<EOF`, `echo "// x" >> c.ts`). Comments already in the file may be carried over; shebang lines, tooling directives (`@ts-ignore`, `eslint-disable`, `biome-ignore`, `noqa`, …) and purely decorative lines are exempt *(see the per-project opt-out below)* |
 
 ### Recursive Analysis
 
@@ -64,7 +68,7 @@ Anything the extractor cannot parse unambiguously (here-strings `<<<`, variable
 ### Via pi Marketplace
 
 ```bash
-pi install @giuseppetrisciuoglio/pi-prevent-destructive-commands
+pi install npm:@giuseppe.trisciuoglio/pi-prevent-destructive-commands
 ```
 
 ### Manual Installation
@@ -104,14 +108,22 @@ pi /reload
 
 ### Per-Project Opt-Out
 
-Create `.pi/prevent-destructive-commands.json` in the project root to disable the `git add` / `git commit` / `git push` guards **for that project only**:
+Create `.pi/prevent-destructive-commands.json` in the project root to tune the guards **for that project only**:
 
 ```json
 {
-	"disableGitGuards": true
+	"disableGitGuards": true,
+	"disableCommentGuard": true,
+	"readOnly": false
 }
 ```
 
+| Flag | Default | Effect |
+|------|---------|--------|
+| `disableGitGuards` | `false` | Disables the `git add` / `git commit` / `git push` guards. |
+| `disableCommentGuard` | `false` | Disables the source comment guard, allowing the agent to write comments into source files again. |
+| `readOnly` | `false` | When `true`, blocks every mutating tool call (`write`, `edit`, patch tools, `bash`, `powershell`) while read-only tools keep working. |
+
 Or use the `/git-guards` slash command from the pi TUI:
 
 | Command | Effect |
@@ -120,6 +132,18 @@ Or use the `/git-guards` slash command from the pi TUI:
 | `/git-guards off` | Write `{"disableGitGuards": true}` (unrelated JSON keys are preserved). |
 | `/git-guards on` | Write `{"disableGitGuards": false}`. |
 
+### Read-Only Mode
+
+Use the `/read-only` slash command to make the project inspection-only:
+
+| Command | Effect |
+|---------|--------|
+| `/read-only` | Show whether read-only mode is active for the current project, and the state of the configuration file. |
+| `/read-only on` | Write `{"readOnly": true}` (unrelated JSON keys are preserved). |
+| `/read-only off` | Write `{"readOnly": false}`. |
+
+While read-only mode is active, the agent can inspect files with `read`, `grep`, `find`, and `ls`, but `write`, `edit`, every patch-style tool, `bash`, and `powershell` are blocked with a clear reason. Read-only mode is independent of the destructive-command, git, migration, Nx, and comment guards, and it defaults to off when the configuration file is missing or invalid.
+
 Notes:
 
 - Forceful and deleting push variants (`--force`, `-f`, `--force-with-lease`, `-d`, `--delete`) are **always blocked** and cannot be opted out.
@@ -138,10 +162,15 @@ prevent-destructive-commands/
 │   ├── config.ts         # Blacklists and behavior flags — tune protection here
 │   ├── tokenizer.ts      # Shell tokenizer (shlex-like)
 │   ├── checker.ts        # Recursive command walker (wrappers/shell/find/xargs)
+│   ├── read-only-command.ts # /read-only toggle and read-only tool-call gate
 │   ├── migration-guard.ts
 │   ├── nx-guard.ts       # Protects existing Nx package and TypeScript configuration files
+│   ├── comment-guard.ts  # Blocks new comments written into source files
+│   ├── patch-paths.ts    # Shared patch/file-path extraction from tool inputs
+│   ├── token-segments.ts # Shared command-segment splitting for bash-level guards
 │   └── rules/            # Per-category destructive-command handlers
 │       ├── types.ts          # Shared CheckResult type + helpers
+│       ├── args.ts           # Token-scanning helpers (positional args, subcommand matching)
 │       ├── path-utils.ts      # cwd-relative path resolution
 │       ├── git.ts             # git reset --hard, push --force, ...
 │       ├── docker.ts          # docker rm, system prune, ...
@@ -150,8 +179,10 @@ prevent-destructive-commands/
 │       └── path-sensitive.ts  # rm/rmdir/... outside-cwd detection
 ├── test/
 │   ├── smoke-test.ts        # Standalone test suite (79+ cases)
+│   ├── helpers.ts           # Shared test utilities (check, makeProject, runCheckCases, ...)
 │   ├── migration-guard-test.ts
 │   ├── nx-guard-test.ts     # Verifies Nx configuration protection and allowed creation
+│   ├── comment-guard-test.ts # Verifies new-comment blocking across write, edit, patch, bash
 │   └── e2e-install-test.ts  # End-to-end: verifies real installation/discovery by pi
 ├── tsconfig.json     # TypeScript configuration
 ├── package.json      # Package metadata for pi marketplace
@@ -176,6 +207,8 @@ Standalone tests for the tokenizer/checker logic (no dependency on pi itself):
 npm run test:smoke
 npm run test:heredoc
 npm run test:nx-guard
+npm run test:comment-guard
+```
 
 # Or directly with tsx
 npx tsx test/smoke-test.ts
@@ -203,6 +236,7 @@ npx tsx test/e2e-install-test.ts
 The test suite covers:
 - All destructive Git operations
 - Existing Nx package and TypeScript configuration protection, including direct tool writes, patches, shell redirection, and package-manager dependency changes
+- Source comment blocking across `write`, `edit`, `apply_patch`, and bash write vectors (heredoc, `tee`, `echo`/`printf`), including string-literal false-positive checks and the per-project opt-out
 - Path-sensitive `rm` protection
 - Docker destructive commands
 - AWS CLI destructive subcommands
@@ -223,6 +257,7 @@ As with the original Claude plugin, the analysis is static and therefore cannot
 | Limitation | Example | Explanation |
 |------------|---------|-------------|
 | **Unknown wrappers** | Custom destructive tools | The extension covers known patterns; unknown wrappers or custom destructive tools are not intercepted. |
+| **Comment guard scope** | `python -c`, `sed` insertion; `.vue`/`.svelte`/`.astro` files | The comment guard covers writing tools and the common bash write vectors (heredoc, `tee`, `echo`/`printf` arguments); other generators are not intercepted. Mixed-language single-file components are excluded to avoid false positives across template/script/style blocks. A bash rewrite of an existing file counts every comment in the heredoc body as new. |
 
 Two cases that used to be listed here are now handled:
 
@@ -233,13 +268,14 @@ Two cases that used to be listed here are now handled:
 
 ## How It Works
 
-When pi attempts to execute a bash command, this extension intercepts the `tool_call` event and:
+When pi attempts to execute a tool call, this extension intercepts the `tool_call` event and:
 
 1. **Extracts heredoc bodies** so prose fed through `cat > file <<'EOF'` is treated as data, keeping bodies under analysis only when an executor on the command line would run them.
 2. **Tokenizes** the command string using a shlex-like shell tokenizer that respects quotes and escapes.
 3. **Analyzes** the token stream recursively, traversing wrappers, shell invocations, and pipelines.
-4. **Blocks** if any destructive pattern is detected, returning a clear reason to the agent.
-5. **Allows** safe commands to pass through without modification.
+4. **Checks writing tool calls** against the file-content guards: immutable Nx configuration, and new comments introduced into source files (string-aware, per language family, with only-newly-introduced comments blocked).
+5. **Blocks** if any destructive pattern is detected, returning a clear reason to the agent.
+6. **Allows** safe commands to pass through without modification.
 
 The agent never receives an interactive prompt — the block is final and must be handled by finding a safe alternative.
 

package/docs/adr/0001-read-only-mode.md

@@ -0,0 +1,53 @@
+# ADR 0001: Read-only mode blocks shell execution wholesale
+
+- Status: accepted
+- Date: 2026-10-23
+- Author: Giuseppe Trisciuoglio
+
+## Context
+
+The extension guards against destructive commands and protected paths, but there
+is no way to declare a project inspection-only. Users wanted a per-project flag
+that lets the agent read files and explore the codebase while preventing any
+modification. The natural home for the flag is the existing per-project
+configuration file, `.pi/prevent-destructive-commands.json`, and the `/git-guards`
+command already established the pattern of a user-invoked toggle that writes that
+file from the extension process.
+
+Tools that can mutate state are `write`, `edit`, any patch-style variant such as
+`apply_patch`, `bash`, and `powershell`. Read-only tools are `read`, `grep`,
+`find`, `ls`, and similar non-mutating tools.
+
+The open design question was whether read-only mode should keep allowing
+"obviously read-only" shell commands such as `cat`, `ls`, or `grep` invoked
+through `bash`. Classifying a shell command line as read-only is the same
+unsolved problem the destructive-command checker already deals with: commands
+can hide mutations behind wrappers, redirects, command substitution, heredocs,
+and arbitrary binaries.
+
+## Decision
+
+Read-only mode blocks `bash` and `powershell` entirely, without attempting to
+classify individual shell commands as safe. It also blocks `write`, `edit`, and
+every tool whose name ends with `apply_patch`. Read-only tools keep working.
+
+The mode is stored as a `readOnly` boolean in
+`.pi/prevent-destructive-commands.json`. It defaults to `false` when the file is
+missing or invalid, so the agent stays writable until the user explicitly turns
+it on. The `/read-only on|off|status` slash command toggles the flag while
+preserving unrelated JSON keys, mirroring `/git-guards`.
+
+When read-only mode is active, the `tool_call` handler checks it first and
+short-circuits the other write-related guards: a rejected write needs no further
+analysis.
+
+## Consequences
+
+- Inspection-only projects are safe: no shell invocation can mutate the
+  workspace while the mode is on.
+- Users lose the convenience of running read-only shell commands through `bash`
+  in read-only mode; they use `read`, `grep`, `find`, and `ls` instead.
+- The mode is per project, so different projects can be in different modes at
+  the same time.
+- Read-only mode is independent of the destructive-command, git, migration, Nx,
+  and comment guards; those behaviors are unchanged when the mode is off.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giuseppe.trisciuoglio/pi-prevent-destructive-commands",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Unconditionally blocks destructive bash commands before execution. A pi extension that guards against rm, git reset --hard, docker rm, aws delete operations, and more.",
   "keywords": [
     "pi-package",
@@ -32,7 +32,7 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "test": "npm run test:smoke && npm run test:heredoc && npm run test:migration-guard && npm run test:nx-guard && npm run test:project-config && npm run test:find-start-path && npm run test:git-guards-command && npm run test:gh-guard && npm run test:e2e",
+    "test": "npm run test:smoke && npm run test:heredoc && npm run test:migration-guard && npm run test:nx-guard && npm run test:project-config && npm run test:find-start-path && npm run test:git-guards-command && npm run test:read-only-command && npm run test:gh-guard && npm run test:comment-guard && npm run test:e2e",
     "test:smoke": "npx tsx test/smoke-test.ts",
     "test:heredoc": "npx tsx test/heredoc-test.ts",
     "test:e2e": "npx tsx test/e2e-install-test.ts",
@@ -41,7 +41,9 @@
     "test:project-config": "npx tsx test/project-config-test.ts",
     "test:find-start-path": "npx tsx test/find-start-path-test.ts",
     "test:git-guards-command": "npx tsx test/git-guards-command-test.ts",
+    "test:read-only-command": "npx tsx test/read-only-command-test.ts",
     "test:gh-guard": "npx tsx test/gh-guard-test.ts",
+    "test:comment-guard": "npx tsx test/comment-guard-test.ts",
     "lint": "tsc --noEmit",
     "typecheck": "tsc --noEmit"
   },

package/src/checker.ts

@@ -9,6 +9,7 @@
  */
 
 import { tokenize } from "./tokenizer";
+import { forEachPositionalArg } from "./rules/args";
 import {
 	DELEGATION_COMMANDS,
 	FILE_READING_COMMANDS,
@@ -186,18 +187,15 @@ export function checkTokens(
 
 		// Quoted-command wrappers: the first positional argument is a command
 		if (QUOTED_COMMAND_WRAPPERS.has(token)) {
-			let j = i + 1;
-			while (j < tokens.length) {
-				const arg = tokens[j];
-				if (!arg || SHELL_OPERATORS.has(arg)) break;
-				if (arg.startsWith("-")) {
-					j++;
-					continue;
-				}
+			let dangerous: CheckResult | undefined;
+			forEachPositionalArg(tokens, i, (arg) => {
 				const r = checkCommand(arg, currentCwd ?? cwd, depth + 1, boundaryCwd, options);
-				if (r.dangerous) return r;
-				break;
-			}
+				if (r.dangerous) {
+					dangerous = r;
+					return false;
+				}
+			});
+			if (dangerous) return dangerous;
 			i++;
 			continue;
 		}