trimprompt 1.0.2 → 1.0.3

package/aicg-spec/insights/git.md

@@ -0,0 +1,85 @@
+# PromptShave.ai - Git Command Insights Specification
+
+This document details the command optimizations, filtering criteria, and output formatting applied to **Git** commands.
+
+---
+
+## 1. `git status`
+
+### Command Optimization
+Before spawning the subprocess, check the user's explicit CLI arguments:
+* **Check compatibility:** If the user passed arguments other than `-b`, `--branch`, `-sb`, `-bs`, `-s`, `--short`, **bypass the filter** and execute the command raw (because arguments like specific file paths or untracked-files flags are incompatible with the default short format).
+* **Rewritten Command:** If compatible, execute `git status --porcelain -b`.
+
+### Output Filtering & Formatting
+1. If the output is empty (excluding whitespace), output:
+   ```text
+   Clean working tree
+   ```
+2. **Branch Header formatting:** The first line of the porcelain output contains the branch status (starts with `## `). Rewrite it to a cleaner, more readable format for the LLM:
+   * Example: `## main...origin/main` is rewritten to `* main...origin/main`.
+   * Example: If detached head, format it as `* (HEAD detached at <commit_hash>)`.
+3. **Change list formatting:** Output the modified/untracked files as is.
+4. **Directory Collapsing (Enterprise Improvement):** If there are more than 10 untracked files inside the same directory:
+   * Instead of listing each file line-by-line, collapse them into a single summary line:
+     `?? path/to/directory/ (N files)`
+   * This prevents context bloating when a developer creates many temporary files or downloads a dataset.
+
+---
+
+## 2. `git log`
+
+### Command Optimization
+Analyze the CLI arguments for formatting and limits:
+* **Format Check:** Check if the user specified a custom format via `--oneline`, `--pretty`, or `--format`.
+* **Limit Check:** Check if the user specified a limit via `-N`, `-n N`, or `--max-count=N`.
+* **Default Formatting:** If no custom format flag is present, append:
+  ```bash
+  --pretty=format:%h %s (%ar) <%an>%n%b%n---END---
+  ```
+  This prints: `<short_hash> <subject> (<relative_time>) <<author_name>>\n<commit_body>\n---END---`.
+* **Default Limits:**
+  * If the user specified a limit, respect it.
+  * If a custom format was passed but no limit, default to `-50`.
+  * If no format and no limit was passed, default to `-10`.
+* **Merge Filtering:** If the user did not explicitly request merges (no `--merges`, `--no-merges`, or `--min-parents`), append `--no-merges` to remove merge commit noise.
+
+---
+
+## 3. `git diff`
+
+### Command Optimization
+* Intercept `git diff`. If the user passes `--no-compact` or `--raw`, bypass and run raw.
+* Run the command and capture the output.
+
+### Output Filtering (Unified Diff Condensation)
+1. **Metadata Stripping:** Strip git-specific metadata headers: `diff --git`, `index`, `similarity index`, `--- `, `+++ `, and `@@` line metadata (except the file path).
+2. **File Summaries:** For each changed file, output a header:
+   ```text
+   [file] path/to/file (+A -B)
+   ```
+3. **Change Limiting:** Output the actual additions (`+`) and removals (`-`) for the file.
+4. **Truncation Threshold:** Limit the displayed changes to **10 lines** per file. If a file has more than 10 lines of diff:
+   * Truncate the rest and append: `  ... +N more` (where N is the true count of remaining changes).
+   * This is critical to prevent lockfiles (e.g. `package-lock.json`) or generated files from eating up the entire token window.
+
+---
+
+## 4. `git show`
+
+### Command Optimization
+* **Bypass cases:** If the user requests stat-only views (`--stat`, `--numstat`, `--shortstat`), a custom format, or a specific file blob (`git show revision:path`), bypass the filter and execute raw.
+* Otherwise, capture the raw output and process it using `compact_diff()`.
+
+### Output Filtering (`compact_diff()`)
+1. **Hunk Header Preservation:** Preserve the unified diff hunk header (`@@`), including any trailing function/symbol context (e.g., `@@ -1,5 +1,6 @@ fn my_function()`). This helps the LLM understand which function is being edited.
+2. **Prefix Context Removal:** Strip any lines of unchanged context before the first addition/removal in each hunk.
+3. **Hunk Truncation:** Limit the displayed changes to a maximum of **100 lines** per hunk. If a hunk has more changes:
+   * Truncate the rest and print: `  ... (X lines truncated)`.
+4. **Global Truncation:** If the overall formatted diff output exceeds `max_lines` (default 500 lines):
+   * Terminate the output and append:
+     ```text
+     ... (more changes truncated)
+     [full diff: pshave git diff --no-compact]
+     ```
+   * This gives the AI agent a direct hint on how to retrieve the full diff if it needs it.

package/aicg-spec/insights/js.md

@@ -0,0 +1,74 @@
+# PromptShave.ai - JavaScript/TypeScript Toolchain Insights Specification
+
+This document details the command optimizations, filtering criteria, and output formatting applied to **JavaScript/TypeScript** developer tools.
+
+---
+
+## 1. `jest` & `vitest` (Test Runners)
+
+### Command Optimization
+* **Non-Interactive Mode:** Force non-interactive execution by appending `--watchAll=false` (for Jest) or `--run` (for Vitest) if the user didn't specify execution flags. This prevents the runners from locking up wait states.
+
+### Output Filtering
+1. **Clean Test Pass Case:** If all test suites and tests pass successfully, collapse the output to:
+   ```text
+   Vitest: N passed
+   ```
+2. **Outcome Counts:** If there are failures, print the summary header:
+   ```text
+   Vitest: X passed, Y failed, Z suites total
+   ```
+3. **Test Failures:**
+   * Extract actual test failures (lines starting with `❯` or containing fail symbols).
+   * Limit the details displayed to a maximum of **3 test failures**.
+   * For each failure, show the test suite name, test name, the failing assertion, and the line numbers. Strip long module dependency load errors.
+
+---
+
+## 2. `npm`, `yarn`, & `pnpm` (Package Managers)
+
+### Command Optimization
+* **Progress Bar Suppression:** Force silent progress displays by appending `--no-progress` or `--loglevel=error` to avoid multi-line terminal rewrite noise.
+
+### Output Filtering
+* **`npm install` / `pnpm install` / `yarn install`:**
+  * Strip terminal spinner symbols, carriage return overrides (`\r`), and folder structures.
+  * Strip `audit` warning tables and upgrade recommendations.
+  * Print only the summary outcomes:
+    ```text
+    npm: added A packages, removed B packages, and audited C packages in S seconds.
+    ```
+* **Script Runs (`npm run`, `pnpm run`):**
+  * Strip script metadata header lines (e.g., `> my-app@1.0.0 lint`, `> eslint .`).
+  * If the script runs a linter (like ESLint), group warning lines by file, showing only lines with errors.
+
+---
+
+## 3. `tsc` (TypeScript Compiler)
+
+### Output Filtering
+* **Compilation Pass:** If compilation succeeds with no warnings/errors, print:
+  ```text
+  tsc: Compilation successful (0 errors)
+  ```
+* **Compilation Errors:**
+  * Parse typescript compiler errors (format: `file(line,col): error TSXXXX: Message`).
+  * Group errors by file.
+  * Limit the output to the first **10 compiler errors**. If there are more, truncate and print:
+    ```text
+    ... +N more TypeScript errors
+    ```
+
+---
+
+## 4. `prettier` (Code Formatter)
+
+### Output Filtering
+* **Formatter output:**
+  * Suppress logs listing files that match formatting style (unchanged files).
+  * Print only files that were reformatted or failed validation:
+    ```text
+    Prettier: Formatted 3 files
+      - path/to/file1.ts
+      - path/to/file2.ts
+    ```

package/aicg-spec/insights/python.md

@@ -0,0 +1,86 @@
+# PromptShave.ai - Python Toolchain Insights Specification
+
+This document details the command optimizations, filtering criteria, and output formatting applied to **Python** developer tools.
+
+---
+
+## 1. `pytest` (Test Runner)
+
+### Command Optimization
+* **Flag Injection:** Automatically append `-rxX` (report extra information on skipped, expected-fail, and unexpected-pass outcomes) to the command if the user didn't specify custom reporting flags.
+* **Quiet Output:** Add `--tb=short -q` (short tracebacks, quiet mode) to minimize raw print volume before parsing.
+
+### Output Filtering
+1. **Clean Test Pass Case:** If all tests pass successfully (with no skipped or xfailed tests), output a single line:
+   ```text
+   Pytest: N passed
+   ```
+   *This collapses hundreds of lines of progress bars and success dots into 3 tokens.*
+2. **Outcome Counts:** If there are failures or skipped tests, display the summary line:
+   ```text
+   Pytest: X passed, Y failed, Z skipped, W xfailed, V xpassed
+   ```
+3. **Unexpected Pass / Expected Failures (XFAIL/XPASS):**
+   * If there are expected-failure results, print a section header `Expected-failure outcomes:` and list the first **5** lines.
+   * If there are more, truncate and append `  … +N more`.
+4. **Test Failures:**
+   * Extract actual test failures (lines starting with `___` or `FAILED`).
+   * Limit the details displayed to a maximum of **3 test failures**.
+   * For each failure:
+     * Extract the test name (e.g., `test_endpoint_auth` from `___ test_endpoint_auth ___`).
+     * Print the test status: `1. [FAIL] test_name`.
+     * Extract the traceback from stdout. Truncate it to include only the file name, line number, the failing line of code, and the assertion error. Strip intermediate system library stack frames.
+
+---
+
+## 2. `pip` & `uv pip` (Package Manager)
+
+### Command Optimization
+* **Bypass logic:** If running commands that don't produce heavy output (e.g. `pip --version`), bypass.
+* **Format:** If running `pip list`, default to raw layout unless it is excessively large (>100 packages), in which case format it as a compact list.
+
+### Output Filtering
+* **`pip install` / `pip uninstall`:**
+  * Strip download progress percentages, transfer speeds, and scroll bars.
+  * Strip package caching and collection messages (`Collecting ...`, `Using cached ...`).
+  * Preserve only the final outcome:
+    ```text
+    Successfully installed package1-version package2-version
+    ```
+* **`pip list` / `pip outdated`:**
+  * Clean up formatting: strip column separators (`---`) and double spaces.
+  * Truncate the list if it exceeds 100 packages, listing only the first 20 and last 20, with a count of skipped packages.
+
+---
+
+## 3. `ruff` (Linter & Formatter)
+
+### Output Filtering
+* **`ruff check`:**
+  * Capture and parse lint errors.
+  * Group findings by file name. For each file, print:
+    ```text
+    path/to/file.py:
+      - Line L: [CODE] Lint warning details
+    ```
+  * If the count of lint errors exceeds 20, display the first 10, the last 5, and append a summary: `... (X lint errors truncated)`.
+* **`ruff format`:**
+  * Suppress verbose logs list of untouched files.
+  * Print only files that were actually modified or reformatted:
+    ```text
+    Formatted: path/to/file.py
+    ```
+
+---
+
+## 4. `poetry` & `uv` (Dependency Managers)
+
+### Output Filtering
+* **`poetry install` / `uv sync`:**
+  * Strip all dependency tree resolution logs and package checksum download states.
+  * Collapse verbose package operations to a clean list of changes:
+    ```text
+    Poetry: +A installed, -B removed, ~C updated
+      - Installing package1 (version)
+      - Updating package2 (old -> new)
+    ```

package/aicg-spec/integrations/claude.md

@@ -0,0 +1,57 @@
+# PromptShave.ai - Claude Code Hook Integration Specification
+
+This document defines how **PromptShave.ai** integrates with **Claude Code** to intercept and rewrite terminal commands.
+
+---
+
+## 1. Integration Hook Details
+* **Hook Hook Name:** `PreToolUse`
+* **Target Configurations:** `~/.claude/settings.json` under `hooks.PreToolUse`.
+* **Execution Path:** The `pshave` hook is called as a subprocess before any bash command runs.
+
+---
+
+## 2. Communication Contract (JSON Schema)
+
+### Input Payload (Stdin)
+Claude Code feeds the hook a JSON object describing the tool being called and its arguments:
+```json
+{
+  "tool_name": "Bash",
+  "tool_input": {
+    "command": "npm test"
+  }
+}
+```
+
+### Output Payload (Stdout)
+If the command matches an optimization pattern, the hook rewrites it and prints the following wrapper response:
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow",
+    "permissionDecisionReason": "PromptShave auto-rewrite",
+    "updatedInput": {
+      "command": "pshave npm test"
+    }
+  }
+}
+```
+
+### Bypass / No-Rewrite Payload
+If no rewrite is needed, the hook should output:
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow"
+  }
+}
+```
+
+---
+
+## 3. Exit Code Contract & Graceful Degradation
+* **Exit Code Rule:** The hook must always return exit code `0`. A non-zero exit code will cause Claude Code to halt execution.
+* **Fallback Behavior:** If `pshave` crashes or fails to parse the incoming JSON, the hook must print the allow-bypass JSON structure (showing permission decision as `"allow"` without modifying `updatedInput`).

package/aicg-spec/integrations/copilot.md

@@ -0,0 +1,69 @@
+# PromptShave.ai - Copilot Hook Integration Specification
+
+This document defines how **PromptShave.ai** integrates with **GitHub Copilot Chat** (VS Code) and **GitHub Copilot CLI** to intercept and optimize terminal commands.
+
+---
+
+## 1. Integration Hook Details
+
+Copilot integrations operate in two distinct modes depending on the execution client:
+1. **VS Code Copilot Chat:** Transparent command rewriting.
+2. **GitHub Copilot CLI:** Deny-with-suggestion interaction.
+
+---
+
+## 2. VS Code Copilot Chat (Transparent Rewrite)
+
+### Input Payload (Stdin)
+The chat client passes the tool information:
+```json
+{
+  "tool_name": "Bash",
+  "tool_input": {
+    "command": "git status"
+  }
+}
+```
+
+### Output Payload (Stdout)
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow",
+    "permissionDecisionReason": "PromptShave auto-rewrite",
+    "updatedInput": {
+      "command": "pshave git status"
+    }
+  }
+}
+```
+
+---
+
+## 3. GitHub Copilot CLI (Deny-With-Suggestion)
+
+The Copilot CLI does not support in-place mutation of the command input. To intercept commands, the hook denies permission to run the raw, expensive command and outputs a suggestion, prompting the AI agent or developer to run the `pshave` variant.
+
+### Input Payload (Stdin)
+```json
+{
+  "toolName": "bash",
+  "toolArgs": "{\"command\": \"git diff\"}"
+}
+```
+
+### Output Payload (Stdout - Denied with Suggestion)
+```json
+{
+  "permissionDecision": "deny",
+  "permissionDecisionReason": "PromptShave Optimization: Please execute `pshave git diff` instead to save 80% tokens."
+}
+```
+*Note: Upon receiving this deny decision, the Copilot agent will automatically retry the execution using the suggested `pshave` command.*
+
+---
+
+## 4. Exit Code & Safety Contract
+* Always exit `0`.
+* If the hook fails internally, pass through the command by returning `"allow"` with no modifications.

package/aicg-spec/integrations/cursor.md

@@ -0,0 +1,59 @@
+# PromptShave.ai - Cursor Hook Integration Specification
+
+This document defines how **PromptShave.ai** integrates with the **Cursor** AI editor to intercept and rewrite terminal commands.
+
+---
+
+## 1. Integration Hook Details
+* **Hook Trigger event:** `preToolUse`
+* **Execution Environment:** Spawned as a shell command wrapper by Cursor.
+* **Hook Configuration File:** `~/.cursor/hooks.json`
+* **Contract Path:** `pshave hook cursor` (compiled CLI subcommand) or a standalone Node.js wrapper script.
+
+---
+
+## 2. Communication Contract (JSON Schema)
+
+### Input Payload (Stdin)
+When Cursor is about to execute a terminal command, it passes the following JSON structure to the hook's standard input:
+```json
+{
+  "tool_name": "Bash",
+  "tool_input": {
+    "command": "git status"
+  }
+}
+```
+
+### Output Payload (Stdout)
+To rewrite the command transparently, the hook must output the following JSON structure to standard output and exit with code `0`:
+```json
+{
+  "permission": "allow",
+  "updated_input": {
+    "command": "pshave git status"
+  }
+}
+```
+
+### Bypass / No-Rewrite Payload
+If the command does not match any optimization patterns, or if PromptShave is bypassed (e.g. `PROMPTSHAVE_DISABLED=1`), the hook **must** output an empty JSON object:
+```json
+{}
+```
+*Note: Cursor requires a valid JSON structure for all outcomes. Outputting nothing or raw text will cause Cursor to fail the execution.*
+
+---
+
+## 3. Graceful Degradation & Exit Codes
+
+* **Strict Exit Code Rule:** The hook must **always exit with code `0`**, even on errors (e.g., JSON parsing failure, missing `pshave` binary, database locks). A non-zero exit code will prevent Cursor from running the developer's command.
+* **Error Fallback:** If any error occurs during hook execution, the hook must print `{}` to stdout, allowing Cursor to execute the command raw without modifications.
+* **Dependencies:** The shell wrapper must not rely on external tools like `jq` if possible. If a shell wrapper script is used, it should degrade gracefully:
+  ```bash
+  # Shell wrapper safety check
+  if ! command -v pshave &> /dev/null; then
+    echo "{}"
+    exit 0
+  fi
+  ```