@hasna/terminal 2.0.5 → 2.3.0

package/temp/rtk/docs/TROUBLESHOOTING.md

@@ -0,0 +1,309 @@
+# RTK Troubleshooting Guide
+
+## Problem: "rtk gain" command not found
+
+### Symptom
+```bash
+$ rtk --version
+rtk 1.0.0  # (or similar)
+
+$ rtk gain
+rtk: 'gain' is not a rtk command. See 'rtk --help'.
+```
+
+### Root Cause
+You installed the **wrong rtk package**. You have **Rust Type Kit** (reachingforthejack/rtk) instead of **Rust Token Killer** (rtk-ai/rtk).
+
+### Solution
+
+**1. Uninstall the wrong package:**
+```bash
+cargo uninstall rtk
+```
+
+**2. Install the correct one (Token Killer):**
+
+#### Quick Install (Linux/macOS)
+```bash
+curl -fsSL https://github.com/rtk-ai/rtk/blob/master/install.sh | sh
+```
+
+#### Alternative: Manual Installation
+```bash
+cargo install --git https://github.com/rtk-ai/rtk
+```
+
+**3. Verify installation:**
+```bash
+rtk --version
+rtk gain  # MUST show token savings stats, not error
+```
+
+If `rtk gain` now works, installation is correct.
+
+---
+
+## Problem: Confusion Between Two "rtk" Projects
+
+### The Two Projects
+
+| Project | Repository | Purpose | Key Command |
+|---------|-----------|---------|-------------|
+| **Rust Token Killer** ✅ | rtk-ai/rtk | LLM token optimizer for Claude Code | `rtk gain` |
+| **Rust Type Kit** ❌ | reachingforthejack/rtk | Rust codebase query and type generator | `rtk query` |
+
+### How to Identify Which One You Have
+
+```bash
+# Check if "gain" command exists
+rtk gain
+
+# Token Killer → Shows token savings stats
+# Type Kit → Error: "gain is not a rtk command"
+```
+
+---
+
+## Problem: cargo install rtk installs wrong package
+
+### Why This Happens
+If **Rust Type Kit** is published to crates.io under the name `rtk`, running `cargo install rtk` will install the wrong package.
+
+### Solution
+**NEVER use** `cargo install rtk` without verifying.
+
+**Always use explicit repository URLs:**
+
+```bash
+# CORRECT - Token Killer
+cargo install --git https://github.com/rtk-ai/rtk
+
+# OR install from fork
+git clone https://github.com/rtk-ai/rtk.git
+cd rtk && git checkout feat/all-features
+cargo install --path . --force
+```
+
+**After any installation, ALWAYS verify:**
+```bash
+rtk gain  # Must work if you want Token Killer
+```
+
+---
+
+## Problem: RTK not working in Claude Code
+
+### Symptom
+Claude Code doesn't seem to be using rtk, outputs are verbose.
+
+### Checklist
+
+**1. Verify rtk is installed and correct:**
+```bash
+rtk --version
+rtk gain  # Must show stats
+```
+
+**2. Initialize rtk for Claude Code:**
+```bash
+# Global (all projects)
+rtk init --global
+
+# Per-project
+cd /your/project
+rtk init
+```
+
+**3. Verify CLAUDE.md file exists:**
+```bash
+# Check global
+cat ~/.claude/CLAUDE.md | grep rtk
+
+# Check project
+cat ./CLAUDE.md | grep rtk
+```
+
+**4. Install auto-rewrite hook (recommended for automatic RTK usage):**
+
+**Option A: Automatic (recommended)**
+```bash
+rtk init -g
+# → Installs hook + RTK.md automatically
+# → Follow printed instructions to add hook to ~/.claude/settings.json
+# → Restart Claude Code
+
+# Verify installation
+rtk init --show  # Should show "✅ Hook: executable, with guards"
+```
+
+**Option B: Manual (fallback)**
+```bash
+# Copy hook to Claude Code hooks directory
+mkdir -p ~/.claude/hooks
+cp .claude/hooks/rtk-rewrite.sh ~/.claude/hooks/
+chmod +x ~/.claude/hooks/rtk-rewrite.sh
+```
+
+Then add to `~/.claude/settings.json` (replace `~` with full path):
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/Users/yourname/.claude/hooks/rtk-rewrite.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Note**: Use absolute path in `settings.json`, not `~/.claude/...`
+
+---
+
+## Problem: RTK not working in OpenCode
+
+### Symptom
+OpenCode runs commands without rtk, outputs are verbose.
+
+### Checklist
+
+**1. Verify rtk is installed and correct:**
+```bash
+rtk --version
+rtk gain  # Must show stats
+```
+
+**2. Install the OpenCode plugin (global only):**
+```bash
+rtk init -g --opencode
+```
+
+**3. Verify plugin file exists:**
+```bash
+ls -la ~/.config/opencode/plugins/rtk.ts
+```
+
+**4. Restart OpenCode**
+OpenCode must be restarted to load the plugin.
+
+**5. Verify status:**
+```bash
+rtk init --show  # Should show "OpenCode: plugin installed"
+```
+
+---
+
+## Problem: "command not found: rtk" after installation
+
+### Symptom
+```bash
+$ cargo install --path . --force
+   Compiling rtk v0.7.1
+    Finished release [optimized] target(s)
+  Installing ~/.cargo/bin/rtk
+
+$ rtk --version
+zsh: command not found: rtk
+```
+
+### Root Cause
+`~/.cargo/bin` is not in your PATH.
+
+### Solution
+
+**1. Check if cargo bin is in PATH:**
+```bash
+echo $PATH | grep -o '[^:]*\.cargo[^:]*'
+```
+
+**2. If not found, add to PATH:**
+
+For **bash** (`~/.bashrc`):
+```bash
+export PATH="$HOME/.cargo/bin:$PATH"
+```
+
+For **zsh** (`~/.zshrc`):
+```bash
+export PATH="$HOME/.cargo/bin:$PATH"
+```
+
+For **fish** (`~/.config/fish/config.fish`):
+```fish
+set -gx PATH $HOME/.cargo/bin $PATH
+```
+
+**3. Reload shell config:**
+```bash
+source ~/.bashrc  # or ~/.zshrc or restart terminal
+```
+
+**4. Verify:**
+```bash
+which rtk
+rtk --version
+rtk gain
+```
+
+---
+
+## Problem: Compilation errors during installation
+
+### Symptom
+```bash
+$ cargo install --path .
+error: failed to compile rtk v0.7.1
+```
+
+### Solutions
+
+**1. Update Rust toolchain:**
+```bash
+rustup update stable
+rustup default stable
+```
+
+**2. Clean and rebuild:**
+```bash
+cargo clean
+cargo build --release
+cargo install --path . --force
+```
+
+**3. Check Rust version (minimum required):**
+```bash
+rustc --version  # Should be 1.70+ for most features
+```
+
+**4. If still fails, report issue:**
+- GitHub: https://github.com/rtk-ai/rtk/issues
+
+---
+
+## Need More Help?
+
+**Report issues:**
+- Fork-specific: https://github.com/rtk-ai/rtk/issues
+- Upstream: https://github.com/rtk-ai/rtk/issues
+
+**Run the diagnostic script:**
+```bash
+# From the rtk repository root
+bash scripts/check-installation.sh
+```
+
+This script will check:
+- ✅ RTK installed and in PATH
+- ✅ Correct version (Token Killer, not Type Kit)
+- ✅ Available features (pnpm, vitest, next, etc.)
+- ✅ Claude Code integration (CLAUDE.md files)
+- ✅ Auto-rewrite hook status
+
+The script provides specific fix commands for any issues found.

package/temp/rtk/docs/filter-workflow.md

@@ -0,0 +1,102 @@
+# How a TOML filter goes from file to execution
+
+This document explains what happens between "I created `src/filters/my-tool.toml`" and "RTK filters the output of `my-tool`".
+
+## Build pipeline
+
+```mermaid
+flowchart TD
+    A[["📄 src/filters/my-tool.toml\n(new file)"]] --> B
+
+    subgraph BUILD ["🔨 cargo build"]
+        B["build.rs\n① ls src/filters/*.toml\n② sort alphabetically\n③ concat → schema_version = 1 + all files"] --> C
+        C{"TOML valid?\nDuplicate names?"} -->|"❌ panic! (build fails)"| D[["🛑 Error message\npoints to bad file"]]
+        C -->|"✅ ok"| E[["OUT_DIR/builtin_filters.toml\n(generated file)"]]
+        E --> F["rustc\ninclude_str!(concat!(env!(OUT_DIR),\n'/builtin_filters.toml'))"]
+        F --> G[["🦀 rtk binary\nBUILTIN_TOML embedded"]]
+    end
+
+    subgraph TESTS ["🧪 cargo test"]
+        H["test_builtin_filter_count\nassert_eq!(filters.len(), N)"] -->|"❌ count wrong"| I[["FAIL\n'Expected N, got N+1'\nUpdate the count'"]]
+        J["test_builtin_all_expected_\nfilters_present\nassert!(names.contains('my-tool'))"] -->|"❌ name missing"| K[["FAIL\n'my-tool is missing—\nwas its .toml deleted?'"]]
+        L["test_builtin_all_filters_\nhave_inline_tests\nassert!(tested.contains(name))"] -->|"❌ no tests"| M[["FAIL\n'Add tests.my-tool\nentries'"]]
+    end
+
+    subgraph VERIFY ["✅ rtk verify"]
+        N["runs [[tests.my-tool]]\ninput → filter → compare expected"]
+        N -->|"❌ mismatch"| O[["FAIL\nshows actual vs expected"]]
+        N -->|"✅ pass"| P[["60/60 tests passed"]]
+    end
+
+    G --> H
+    G --> J
+    G --> L
+    G --> N
+
+    subgraph RUNTIME ["⚡ rtk my-tool --verbose"]
+        Q["Claude Code hook\nmy-tool ... → rtk my-tool ..."] --> R
+        R["TomlFilterRegistry::load()\n① .rtk/filters.toml  (project)\n② ~/.config/rtk/filters.toml  (user)\n③ BUILTIN_TOML  (binary)\n④ passthrough"] --> S
+        S{"match_command\n'^my-tool\\b'\nmatches?"} -->|"No match"| T[["exec raw\n(passthrough)"]]
+        S -->|"✅ match"| U["exec command\ncapture stdout"]
+        U --> V
+
+        subgraph PIPELINE ["8-stage filter pipeline"]
+            V["strip_ansi"] --> W["replace"]
+            W --> X{"match_output\nshort-circuit?"}
+            X -->|"✅ pattern matched"| Y[["emit message\nstop pipeline"]]
+            X -->|"no match"| Z["strip/keep_lines"]
+            Z --> AA["truncate_lines_at"]
+            AA --> AB["tail_lines"]
+            AB --> AC["max_lines"]
+            AC --> AD{"output\nempty?"}
+            AD -->|"yes"| AE[["emit on_empty"]]
+            AD -->|"no"| AF[["print filtered\noutput + exit code"]]
+        end
+    end
+
+    G --> Q
+
+    style BUILD fill:#1e3a5f,color:#fff
+    style TESTS fill:#1a3a1a,color:#fff
+    style VERIFY fill:#2d1b69,color:#fff
+    style RUNTIME fill:#3a1a1a,color:#fff
+    style PIPELINE fill:#4a2a00,color:#fff
+    style D fill:#8b0000,color:#fff
+    style I fill:#8b0000,color:#fff
+    style K fill:#8b0000,color:#fff
+    style M fill:#8b0000,color:#fff
+    style O fill:#8b0000,color:#fff
+```
+
+## Step-by-step summary
+
+| Step | Who | What happens | Fails if |
+|------|-----|--------------|----------|
+| 1 | Contributor | Creates `src/filters/my-tool.toml` | — |
+| 2 | `build.rs` | Concatenates all `.toml` files alphabetically | TOML syntax error, duplicate filter name |
+| 3 | `rustc` | Embeds result in binary via `BUILTIN_TOML` const | — |
+| 4 | `cargo test` | 3 guards check count, names, inline test presence | Count not updated, name not in list, no `[[tests.*]]` |
+| 5 | `rtk verify` | Runs each `[[tests.my-tool]]` entry | Filter logic doesn't match expected output |
+| 6 | Runtime | Hook rewrites command, registry looks up filter, pipeline runs | No match → passthrough (not an error) |
+
+## Filter lookup priority at runtime
+
+```mermaid
+flowchart LR
+    CMD["rtk my-tool args"] --> P1
+    P1{"1. .rtk/filters.toml\n(project-local)"}
+    P1 -->|"✅ match"| WIN["apply filter"]
+    P1 -->|"no match"| P2
+    P2{"2. ~/.config/rtk/filters.toml\n(user-global)\n(macOS alt: ~/Library/Application Support/rtk/filters.toml)"}
+    P2 -->|"✅ match"| WIN
+    P2 -->|"no match"| P3
+    P3{"3. BUILTIN_TOML\n(binary)"}
+    P3 -->|"✅ match"| WIN
+    P3 -->|"no match"| P4[["exec raw\n(passthrough)"]]
+```
+
+First match wins. A project filter with the same name as a built-in shadows the built-in and triggers a warning:
+
+```
+[rtk] warning: filter 'make' is shadowing a built-in filter
+```