@hasna/terminal 2.3.0 → 2.3.1

package/temp/rtk/docs/TROUBLESHOOTING.md

@@ -1,309 +0,0 @@
-# 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

@@ -1,102 +0,0 @@
-# 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
-```