ctx-bridge 0.1.0__tar.gz

ctx_bridge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maaz Korejo
+
+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.

ctx_bridge-0.1.0/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: ctx-bridge
+Version: 0.1.0
+Summary: CLI tool to snapshot project context, git state, diffs, and progress logs for AI assistant session handoffs.
+Author: Maaz Korejo
+License-Expression: MIT
+Project-URL: Repository, https://github.com/Maazkorejo/CTX-Bridge
+Keywords: ai,cli,context,prompt,git,developer-tools,handoff,bridge
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: gitpython>=3.1.0
+Requires-Dist: pyperclip>=1.8.0
+Requires-Dist: pathspec>=0.11.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Dynamic: license-file
+
+# 🌁 CTX-Bridge (`ctx-bridge` / `bridge`)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
+[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+> **Bridge the context gap between AI coding assistants.**  
+> Snapshot your git state, code diffs, directory structure, project metadata, and running progress logs into a clean, paste-ready handoff summary — so your next AI session picks up **exactly where the last one left off.**
+
+---
+
+## ⚡ The Problem
+
+When coding with AI assistants (**Cursor, GitHub Copilot, Windsurf, Claude Code, ChatGPT**), you inevitably hit context window limits or session resets mid-task. Switching tools or starting a fresh chat forces you to re-explain everything from scratch — wasting **time, tokens, and focus**.
+
+## 🚀 The Solution: `CTX-Bridge`
+
+`CTX-Bridge` acts as persistent cognitive memory for your developer workspace. With simple terminal commands, it captures what was done, what files were touched, uncommitted git diffs, project dependencies, and an ASCII tree structure — framing it instantly into your clipboard and a saved snapshot document.
+
+```
+       [ AI Assistant Session 1 ]
+                   │
+                   ▼  (Run: bridge export)
+       ┌───────────────────────┐
+       │   CTX-Bridge Engine   │ ──► Saved .ctx/exports/handoff.md
+       └───────────────────────┘ ──► Copied to Clipboard
+                   │
+                   ▼  (Paste into New Chat)
+       [ AI Assistant Session 2 ]
+```
+
+---
+
+## ✨ Features
+
+- 🌐 **Web Chat Session Handoff (`bridge chat`)**: Purpose-built for web browser AI chats. Wrap copied code/notes into a formatted prompt instantly.
+- 🌿 **Git State Integration**: Extracts active branch, recent commit logs, staged, unstaged, and untracked files.
+- 📝 **Code Diff Capture**: Captures working tree `git diff` output with configurable line limit truncation.
+- 🌲 **Smart Directory Tree**: Generates ASCII project structure respecting `.gitignore` patterns with directory symlink loop protection.
+- 🔍 **Multi-Language Auto-Detection**: Automatically identifies project language and framework:
+  - **Python** (FastAPI, Django, Flask, `pyproject.toml`, `requirements.txt`)
+  - **JavaScript / TypeScript** (Next.js, React, Vue, Express, NestJS)
+  - **Rust** (`Cargo.toml`) | **Go** (`go.mod`) | **Java/Kotlin** (Maven, Gradle)
+  - **C# / .NET** (`*.csproj`, `*.sln`) | **Ruby** (`Gemfile`) | **PHP** (`composer.json`)
+- 📋 **Running Session Logs**: Add timestamped progress notes while coding (`bridge log "..."`).
+- 🤖 **AI Assistant Presets**: Tailored prompt framing preambles for **Cursor**, **GitHub Copilot**, **Claude**, **ChatGPT**, and **Generic AI**.
+- 🛡️ **Security Safeguards**:
+  - Automatically appends `.ctx/` to `.gitignore` on initialization.
+  - Automatically redacts sensitive files (`.env*`, `*.pem`, `*.key`, `id_rsa*`, `credentials.json`) from diffs and status reports.
+
+---
+
+## 📦 Installation
+
+```bash
+# Clone repository
+git clone https://github.com/Maazkorejo/CTX-Bridge.git
+cd CTX-Bridge
+
+# Install locally in editable mode
+pip install -e .
+```
+
+After installation, both `ctx-bridge` and the shortcut `bridge` are available in your terminal:
+```bash
+bridge --version
+# Output: ctx-bridge, version 0.1.0
+```
+
+---
+
+## 🛠️ Detailed Command Reference
+
+You can invoke commands using either `bridge` or `ctx-bridge`.
+
+### 1. `bridge chat`
+Purpose-built for web browser AI chat sessions (no repository required). Formats copied code and task goals into a paste-ready handoff prompt and copies it to your clipboard.
+
+```bash
+# Interactive mode (prompts for goal, code/clipboard, and next task)
+bridge chat
+
+# Auto-grab whatever you just copied from your browser chat:
+bridge chat --from-clipboard
+
+# Command-line flags mode:
+bridge chat --goal "FastAPI Auth Service" --task "Add password hashing" --template claude
+```
+
+### 2. `bridge init`
+Initializes `.ctx/` configuration directory and `progress.md` in your project root. Automatically appends `.ctx/` to `.gitignore`.
+
+```bash
+bridge init
+# Custom project name:
+bridge init --name "my-awesome-service"
+```
+
+### 2. `bridge log <message>`
+Appends a timestamped progress note to `.ctx/progress.md` so the AI knows what has already been accomplished.
+
+```bash
+bridge log "Created user authentication endpoints in /api/auth"
+bridge log "Fixed JWT token verification bug in middleware"
+```
+
+### 3. `bridge status`
+Displays a rich terminal table showing project metadata, active git branch, modified files count, and logged entries.
+
+```bash
+bridge status
+```
+
+### 4. `bridge export`
+Generates the complete context snapshot markdown report, copies it to your **system clipboard**, and saves a snapshot copy to `.ctx/exports/handoff_<timestamp>.md`.
+
+```bash
+# Export with default generic AI framing
+bridge export
+
+# Export framed specifically for Cursor IDE or Claude
+bridge export --template cursor
+bridge export --template claude
+
+# Export Flags:
+bridge export --no-clipboard  # Do not copy to system clipboard
+bridge export --no-file       # Do not save .md file to disk
+bridge export --stdout        # Output markdown directly to stdout
+```
+
+### 5. `bridge reset`
+Clears current progress entries in `.ctx/progress.md` for a fresh session.
+
+```bash
+bridge reset
+```
+
+---
+
+## 📄 Example Export Snapshot Output
+
+Here is what `bridge export` copies to your clipboard:
+
+```markdown
+# 🔄 Context Handoff — my-fastapi-app
+
+> **Generated at**: 2026-08-13 05:15:00
+> [CURSOR HANDOFF SESSION] You are Cursor AI assistant. Resume the active coding task using the project context below.
+
+## 📋 Session Progress Log
+- **[2026-08-13 04:30:12]** Created database schema for users and auth tokens
+- **[2026-08-13 05:10:45]** Implemented JWT token verification middleware
+
+## 🌿 Git State
+- **Branch**: `feature/auth`
+- **Staged Files**: `app/auth.py`, `app/main.py`
+- **Unstaged Files**: `tests/test_auth.py`
+
+**Recent Commits**:
+- `a1b2c3d` — Initial project structure
+- `e5f6g7h` — Add database config
+
+## 📝 Code Changes (git diff)
+```diff
+--- a/app/auth.py
++++ b/app/auth.py
+@@ -12,4 +12,4 @@ def verify_token(token: str):
+-    return jwt.decode(token, SECRET)
++    return jwt.decode(token, SECRET, algorithms=["HS256"])
+```
+
+## 📁 Project Structure (`*` = modified)
+```
+my-fastapi-app/
+├── app/
+│   ├── __init__.py
+│   ├── auth.py *
+│   └── main.py *
+├── tests/
+│   └── test_auth.py *
+├── pyproject.toml
+└── requirements.txt
+```
+
+## 🔧 Project Info
+- **Type**: Python
+- **Framework**: FastAPI
+- **Key Dependencies**: fastapi, uvicorn, pyjwt, pydantic
+```
+
+---
+
+## ⚙️ Configuration (`.ctx/config.json`)
+
+When you run `bridge init`, `.ctx/config.json` is created:
+
+```json
+{
+  "project_name": "my-project",
+  "project_type": "Python",
+  "template": "generic",
+  "export_format": "markdown",
+  "max_diff_lines": 300,
+  "max_tree_depth": 4,
+  "ignore_patterns": [
+    "node_modules",
+    ".git",
+    "__pycache__",
+    ".venv",
+    "venv",
+    "dist",
+    "build",
+    ".ctx"
+  ]
+}
+```
+
+---
+
+## 🧪 Running Tests
+
+```bash
+# Install development dependencies
+pip install -e .[dev]
+
+# Run full test suite
+python -m pytest tests/ -v
+```
+
+---
+
+## 👤 Author & Maintainer
+
+**Maaz Korejo**
+- GitHub: [@Maazkorejo](https://github.com/Maazkorejo)
+- Repository: [CTX-Bridge](https://github.com/Maazkorejo/CTX-Bridge)
+
+---
+
+## 📜 License
+
+Distributed under the [MIT License](LICENSE).

ctx_bridge-0.1.0/README.md

@@ -0,0 +1,242 @@
+# 🌁 CTX-Bridge (`ctx-bridge` / `bridge`)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
+[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+> **Bridge the context gap between AI coding assistants.**  
+> Snapshot your git state, code diffs, directory structure, project metadata, and running progress logs into a clean, paste-ready handoff summary — so your next AI session picks up **exactly where the last one left off.**
+
+---
+
+## ⚡ The Problem
+
+When coding with AI assistants (**Cursor, GitHub Copilot, Windsurf, Claude Code, ChatGPT**), you inevitably hit context window limits or session resets mid-task. Switching tools or starting a fresh chat forces you to re-explain everything from scratch — wasting **time, tokens, and focus**.
+
+## 🚀 The Solution: `CTX-Bridge`
+
+`CTX-Bridge` acts as persistent cognitive memory for your developer workspace. With simple terminal commands, it captures what was done, what files were touched, uncommitted git diffs, project dependencies, and an ASCII tree structure — framing it instantly into your clipboard and a saved snapshot document.
+
+```
+       [ AI Assistant Session 1 ]
+                   │
+                   ▼  (Run: bridge export)
+       ┌───────────────────────┐
+       │   CTX-Bridge Engine   │ ──► Saved .ctx/exports/handoff.md
+       └───────────────────────┘ ──► Copied to Clipboard
+                   │
+                   ▼  (Paste into New Chat)
+       [ AI Assistant Session 2 ]
+```
+
+---
+
+## ✨ Features
+
+- 🌐 **Web Chat Session Handoff (`bridge chat`)**: Purpose-built for web browser AI chats. Wrap copied code/notes into a formatted prompt instantly.
+- 🌿 **Git State Integration**: Extracts active branch, recent commit logs, staged, unstaged, and untracked files.
+- 📝 **Code Diff Capture**: Captures working tree `git diff` output with configurable line limit truncation.
+- 🌲 **Smart Directory Tree**: Generates ASCII project structure respecting `.gitignore` patterns with directory symlink loop protection.
+- 🔍 **Multi-Language Auto-Detection**: Automatically identifies project language and framework:
+  - **Python** (FastAPI, Django, Flask, `pyproject.toml`, `requirements.txt`)
+  - **JavaScript / TypeScript** (Next.js, React, Vue, Express, NestJS)
+  - **Rust** (`Cargo.toml`) | **Go** (`go.mod`) | **Java/Kotlin** (Maven, Gradle)
+  - **C# / .NET** (`*.csproj`, `*.sln`) | **Ruby** (`Gemfile`) | **PHP** (`composer.json`)
+- 📋 **Running Session Logs**: Add timestamped progress notes while coding (`bridge log "..."`).
+- 🤖 **AI Assistant Presets**: Tailored prompt framing preambles for **Cursor**, **GitHub Copilot**, **Claude**, **ChatGPT**, and **Generic AI**.
+- 🛡️ **Security Safeguards**:
+  - Automatically appends `.ctx/` to `.gitignore` on initialization.
+  - Automatically redacts sensitive files (`.env*`, `*.pem`, `*.key`, `id_rsa*`, `credentials.json`) from diffs and status reports.
+
+---
+
+## 📦 Installation
+
+```bash
+# Clone repository
+git clone https://github.com/Maazkorejo/CTX-Bridge.git
+cd CTX-Bridge
+
+# Install locally in editable mode
+pip install -e .
+```
+
+After installation, both `ctx-bridge` and the shortcut `bridge` are available in your terminal:
+```bash
+bridge --version
+# Output: ctx-bridge, version 0.1.0
+```
+
+---
+
+## 🛠️ Detailed Command Reference
+
+You can invoke commands using either `bridge` or `ctx-bridge`.
+
+### 1. `bridge chat`
+Purpose-built for web browser AI chat sessions (no repository required). Formats copied code and task goals into a paste-ready handoff prompt and copies it to your clipboard.
+
+```bash
+# Interactive mode (prompts for goal, code/clipboard, and next task)
+bridge chat
+
+# Auto-grab whatever you just copied from your browser chat:
+bridge chat --from-clipboard
+
+# Command-line flags mode:
+bridge chat --goal "FastAPI Auth Service" --task "Add password hashing" --template claude
+```
+
+### 2. `bridge init`
+Initializes `.ctx/` configuration directory and `progress.md` in your project root. Automatically appends `.ctx/` to `.gitignore`.
+
+```bash
+bridge init
+# Custom project name:
+bridge init --name "my-awesome-service"
+```
+
+### 2. `bridge log <message>`
+Appends a timestamped progress note to `.ctx/progress.md` so the AI knows what has already been accomplished.
+
+```bash
+bridge log "Created user authentication endpoints in /api/auth"
+bridge log "Fixed JWT token verification bug in middleware"
+```
+
+### 3. `bridge status`
+Displays a rich terminal table showing project metadata, active git branch, modified files count, and logged entries.
+
+```bash
+bridge status
+```
+
+### 4. `bridge export`
+Generates the complete context snapshot markdown report, copies it to your **system clipboard**, and saves a snapshot copy to `.ctx/exports/handoff_<timestamp>.md`.
+
+```bash
+# Export with default generic AI framing
+bridge export
+
+# Export framed specifically for Cursor IDE or Claude
+bridge export --template cursor
+bridge export --template claude
+
+# Export Flags:
+bridge export --no-clipboard  # Do not copy to system clipboard
+bridge export --no-file       # Do not save .md file to disk
+bridge export --stdout        # Output markdown directly to stdout
+```
+
+### 5. `bridge reset`
+Clears current progress entries in `.ctx/progress.md` for a fresh session.
+
+```bash
+bridge reset
+```
+
+---
+
+## 📄 Example Export Snapshot Output
+
+Here is what `bridge export` copies to your clipboard:
+
+```markdown
+# 🔄 Context Handoff — my-fastapi-app
+
+> **Generated at**: 2026-08-13 05:15:00
+> [CURSOR HANDOFF SESSION] You are Cursor AI assistant. Resume the active coding task using the project context below.
+
+## 📋 Session Progress Log
+- **[2026-08-13 04:30:12]** Created database schema for users and auth tokens
+- **[2026-08-13 05:10:45]** Implemented JWT token verification middleware
+
+## 🌿 Git State
+- **Branch**: `feature/auth`
+- **Staged Files**: `app/auth.py`, `app/main.py`
+- **Unstaged Files**: `tests/test_auth.py`
+
+**Recent Commits**:
+- `a1b2c3d` — Initial project structure
+- `e5f6g7h` — Add database config
+
+## 📝 Code Changes (git diff)
+```diff
+--- a/app/auth.py
++++ b/app/auth.py
+@@ -12,4 +12,4 @@ def verify_token(token: str):
+-    return jwt.decode(token, SECRET)
++    return jwt.decode(token, SECRET, algorithms=["HS256"])
+```
+
+## 📁 Project Structure (`*` = modified)
+```
+my-fastapi-app/
+├── app/
+│   ├── __init__.py
+│   ├── auth.py *
+│   └── main.py *
+├── tests/
+│   └── test_auth.py *
+├── pyproject.toml
+└── requirements.txt
+```
+
+## 🔧 Project Info
+- **Type**: Python
+- **Framework**: FastAPI
+- **Key Dependencies**: fastapi, uvicorn, pyjwt, pydantic
+```
+
+---
+
+## ⚙️ Configuration (`.ctx/config.json`)
+
+When you run `bridge init`, `.ctx/config.json` is created:
+
+```json
+{
+  "project_name": "my-project",
+  "project_type": "Python",
+  "template": "generic",
+  "export_format": "markdown",
+  "max_diff_lines": 300,
+  "max_tree_depth": 4,
+  "ignore_patterns": [
+    "node_modules",
+    ".git",
+    "__pycache__",
+    ".venv",
+    "venv",
+    "dist",
+    "build",
+    ".ctx"
+  ]
+}
+```
+
+---
+
+## 🧪 Running Tests
+
+```bash
+# Install development dependencies
+pip install -e .[dev]
+
+# Run full test suite
+python -m pytest tests/ -v
+```
+
+---
+
+## 👤 Author & Maintainer
+
+**Maaz Korejo**
+- GitHub: [@Maazkorejo](https://github.com/Maazkorejo)
+- Repository: [CTX-Bridge](https://github.com/Maazkorejo/CTX-Bridge)
+
+---
+
+## 📜 License
+
+Distributed under the [MIT License](LICENSE).

ctx_bridge-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ctx-bridge"
+version = "0.1.0"
+description = "CLI tool to snapshot project context, git state, diffs, and progress logs for AI assistant session handoffs."
+readme = "README.md"
+authors = [
+    { name = "Maaz Korejo" }
+]
+urls = { Repository = "https://github.com/Maazkorejo/CTX-Bridge" }
+license = "MIT"
+keywords = ["ai", "cli", "context", "prompt", "git", "developer-tools", "handoff", "bridge"]
+requires-python = ">=3.8"
+dependencies = [
+    "click>=8.0.0",
+    "rich>=13.0.0",
+    "gitpython>=3.1.0",
+    "pyperclip>=1.8.0",
+    "pathspec>=0.11.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+]
+
+[project.scripts]
+ctx-bridge = "ctx_tool.cli:cli"
+bridge = "ctx_tool.cli:cli"
+
+[tool.setuptools.packages.find]
+where = ["src"]

ctx_bridge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+