ghostfix 0.1.0__tar.gz

ghostfix-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to GhostFix will be documented here.
+
+## 0.1.0
+
+Initial release candidate.
+
+### Added
+
+- `ghostfix watch` command for running and monitoring shell commands.
+- Error detection and stack trace parsing for Python, Node.js, Java, Go, Rust, Ruby, and generic CLI output.
+- Context builder for source snippets, related files, and project tree context.
+- AI provider routing for OpenAI, Claude, Gemini, and custom/local endpoints.
+- Unified-diff patch application with backup support.
+- Project config generation through `ghostfix init`.
+- Global setup and masked config display commands.
+- Release-ready documentation set.
+
+### Changed
+
+- `watch --ai` now asks for provider/API key on every run instead of silently reusing a saved provider.
+
+### Known Limitations
+
+- Patch quality depends on model quality and stack trace context.
+- Manual patch fallback supports simple diffs only.
+- Generic CLI error parsing is partial.

ghostfix-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing
+
+Thanks for helping improve GhostFix.
+
+## Development Setup
+
+```bash
+git clone https://github.com/Shibani987/ghostfix-ai.git
+cd ghostfix-ai
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+## Local Workflow
+
+1. Create a branch for the change.
+2. Keep changes focused.
+3. Add or update tests when behavior changes.
+4. Run `python -m pytest`.
+5. Update docs if commands, config, provider behavior, or safety behavior changes.
+
+## Code Style
+
+- Prefer small, readable functions.
+- Keep CLI behavior explicit and predictable.
+- Avoid broad refactors in bug-fix PRs.
+- Use structured parsing where possible.
+- Keep patch application conservative.
+
+## Documentation Style
+
+- Use short sections.
+- Include copy-pasteable commands.
+- Call out safety and provider/API-key behavior clearly.
+- Keep release docs accurate to the current code.
+
+## Testing
+
+Current tests focus on error parsing. When changing the repair loop, provider routing, or patching behavior, add focused tests around the changed contract.

ghostfix-0.1.0/LICENSE

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

ghostfix-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+include SECURITY.md
+recursive-include docs *.md
+include docs/make_demo_gif.py
+recursive-include docs/assets *.gif
+recursive-include docs/assets *.mp4

ghostfix-0.1.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: ghostfix
+Version: 0.1.0
+Summary: AI-powered terminal error watcher and auto-fixer for any project
+License-Expression: MIT
+Keywords: ai,debugging,cli,auto-fix,developer-tools
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0
+Requires-Dist: httpx>=0.24
+Requires-Dist: pydantic>=2.0
+Requires-Dist: gitpython>=3.1
+Requires-Dist: prompt_toolkit>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: license-file
+
+# GhostFix
+
+**AI-powered terminal error watcher and auto-fixer.**
+
+GhostFix watches any command, detects runtime errors, gathers the relevant code context, asks an AI provider for a focused unified-diff patch, and applies the fix from your terminal.
+
+![GhostFix demo](docs/assets/ghostfix-demo.gif)
+
+## See GhostFix in Action
+
+<video src="docs/assets/Screen%20Recording%202026-06-06%20143114.mp4" controls width="100%">
+  Watch the GhostFix demo video.
+</video>
+
+[Watch the demo video](docs/assets/Screen%20Recording%202026-06-06%20143114.mp4)
+
+[![PyPI](https://img.shields.io/badge/pypi-ghostfix-6d4aff)](https://pypi.org/project/ghostfix/)
+[![Python](https://img.shields.io/badge/python-3.9%2B-2f8fcb)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-111827)](LICENSE)
+[![CLI](https://img.shields.io/badge/cli-rich%20%2B%20click-ff4f87)](https://github.com/Shibani987/ghostfix-ai)
+
+## Why GhostFix?
+
+Development servers, test runners, CLIs, scripts, and training jobs fail in noisy ways. GhostFix sits beside the command, reads the error stream, finds the file and line that matter, then proposes a small patch you can review before applying.
+
+GhostFix is built for developers who want fast repair loops without giving up control.
+
+## Features
+
+- Watch any shell command: Next.js, Django, Flask, pytest, Node, Go, Rust, Java, Ruby, and more.
+- Detect common error signals and parse stack traces across multiple languages.
+- Resolve source files from stack traces and collect nearby code context.
+- Use cloud providers: OpenAI, Claude, or Gemini.
+- Use local/custom models through Ollama, LM Studio, vLLM, or any OpenAI-compatible endpoint.
+- Generate unified-diff patches and apply them with `git apply` first.
+- Create backups in `.ghostfix_backups/` before patching.
+- Restart the watched command after a successful fix.
+- Limit repeated fixes for the same error with retry controls.
+- Keep humans in the loop by default with patch confirmation prompts.
+
+## Install
+
+```bash
+pip install ghostfix
+```
+
+From source:
+
+```bash
+git clone https://github.com/Shibani987/ghostfix-ai.git
+cd ghostfix-ai
+pip install -e .
+```
+
+Python 3.9 or newer is required.
+
+## Quick Start
+
+Cloud AI mode:
+
+```bash
+ghostfix watch "npm run dev" --fix --ai
+```
+
+GhostFix asks for the provider and API key each time `watch --ai` runs. This keeps new terminal sessions from silently reusing an old saved key.
+
+Force a provider but still enter the key for this run:
+
+```bash
+ghostfix watch "python manage.py runserver" --fix --ai --provider gemini
+```
+
+Local/custom model mode:
+
+```bash
+ghostfix init
+ghostfix watch "python app.py" --fix
+```
+
+Edit the generated `ghostfix.config.py` to point at Ollama, LM Studio, vLLM, or your own model server.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `ghostfix watch "CMD"` | Watch a command and print its output. |
+| `ghostfix watch "CMD" --fix --ai` | Watch and fix using a cloud AI provider. |
+| `ghostfix watch "CMD" --fix` | Watch and fix using `ghostfix.config.py` custom model settings. |
+| `ghostfix setup` | Save a default cloud provider/API key for setup workflows. |
+| `ghostfix init` | Create a project-level `ghostfix.config.py`. |
+| `ghostfix config-show` | Show the merged GhostFix configuration with masked API key. |
+
+## Flags
+
+| Flag | Description |
+| --- | --- |
+| `--fix` | Enable the AI repair pipeline when an error is detected. |
+| `--ai` | Use OpenAI, Claude, or Gemini instead of a custom model config. |
+| `--provider <name>` | Force `openai`, `claude`, or `gemini`. |
+| `--auto` | Apply patches without confirmation. Use carefully. |
+| `--config <path>` | Load a specific `ghostfix.config.py`. |
+| `--verbose` | Show extra renderer/debug output. |
+
+## How It Works
+
+```text
+watched command fails
+        |
+        v
+error parser detects language, error type, file, and line
+        |
+        v
+context builder collects source snippets and project tree
+        |
+        v
+AI provider returns root cause, explanation, and unified diff
+        |
+        v
+GhostFix shows the fix and asks before applying
+        |
+        v
+patcher backs up files, applies patch, and restarts command
+```
+
+## Configuration
+
+Create a config file:
+
+```bash
+ghostfix init
+```
+
+Example:
+
+```python
+GHOSTFIX_CONFIG = {
+    "model": {
+        "type": "custom",
+        "endpoint": "http://localhost:11434/api/chat",
+        "model_name": "codellama:13b",
+    },
+    "watch": {
+        "ignore": ["node_modules", ".git", "dist", "__pycache__"],
+        "max_file_size_kb": 500,
+        "context_lines": 60,
+    },
+    "fix": {
+        "auto_apply": False,
+        "create_backup": True,
+        "restart_on_fix": True,
+        "max_retries": 3,
+    },
+}
+```
+
+See [Configuration](docs/CONFIGURATION.md) and [Providers](docs/PROVIDERS.md).
+
+## Supported Error Families
+
+| Ecosystem | Detection | Stack trace parsing |
+| --- | --- | --- |
+| Python, Django, Flask | Yes | Yes |
+| Node.js, TypeScript, Next.js | Yes | Yes |
+| Java | Yes | Yes |
+| Go | Yes | Yes |
+| Rust | Yes | Yes |
+| Ruby | Yes | Yes |
+| Generic CLI output | Yes | Partial |
+
+## Safety
+
+GhostFix is designed to keep you in control:
+
+- Patches are shown before applying unless `--auto` is enabled.
+- Backups are created before patching by default.
+- The same error is not fixed forever; retry limits stop loops.
+- Project scanning ignores common generated folders.
+- API keys are masked in `config-show`.
+
+Read [Security](SECURITY.md) before using GhostFix on sensitive repositories.
+
+## Documentation
+
+- [Installation](docs/INSTALLATION.md)
+- [Configuration](docs/CONFIGURATION.md)
+- [Providers](docs/PROVIDERS.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Troubleshooting](docs/TROUBLESHOOTING.md)
+- [Release Checklist](docs/RELEASE_CHECKLIST.md)
+- [Contributing](CONTRIBUTING.md)
+- [Changelog](CHANGELOG.md)
+
+## Release Status
+
+Current version: `0.1.0`
+
+This is an early release. The core loop is ready for testing, but patch quality depends on the chosen AI model and the context available in the error output.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

ghostfix-0.1.0/README.md

@@ -0,0 +1,201 @@
+# GhostFix
+
+**AI-powered terminal error watcher and auto-fixer.**
+
+GhostFix watches any command, detects runtime errors, gathers the relevant code context, asks an AI provider for a focused unified-diff patch, and applies the fix from your terminal.
+
+![GhostFix demo](docs/assets/ghostfix-demo.gif)
+
+## See GhostFix in Action
+
+<video src="docs/assets/Screen%20Recording%202026-06-06%20143114.mp4" controls width="100%">
+  Watch the GhostFix demo video.
+</video>
+
+[Watch the demo video](docs/assets/Screen%20Recording%202026-06-06%20143114.mp4)
+
+[![PyPI](https://img.shields.io/badge/pypi-ghostfix-6d4aff)](https://pypi.org/project/ghostfix/)
+[![Python](https://img.shields.io/badge/python-3.9%2B-2f8fcb)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-111827)](LICENSE)
+[![CLI](https://img.shields.io/badge/cli-rich%20%2B%20click-ff4f87)](https://github.com/Shibani987/ghostfix-ai)
+
+## Why GhostFix?
+
+Development servers, test runners, CLIs, scripts, and training jobs fail in noisy ways. GhostFix sits beside the command, reads the error stream, finds the file and line that matter, then proposes a small patch you can review before applying.
+
+GhostFix is built for developers who want fast repair loops without giving up control.
+
+## Features
+
+- Watch any shell command: Next.js, Django, Flask, pytest, Node, Go, Rust, Java, Ruby, and more.
+- Detect common error signals and parse stack traces across multiple languages.
+- Resolve source files from stack traces and collect nearby code context.
+- Use cloud providers: OpenAI, Claude, or Gemini.
+- Use local/custom models through Ollama, LM Studio, vLLM, or any OpenAI-compatible endpoint.
+- Generate unified-diff patches and apply them with `git apply` first.
+- Create backups in `.ghostfix_backups/` before patching.
+- Restart the watched command after a successful fix.
+- Limit repeated fixes for the same error with retry controls.
+- Keep humans in the loop by default with patch confirmation prompts.
+
+## Install
+
+```bash
+pip install ghostfix
+```
+
+From source:
+
+```bash
+git clone https://github.com/Shibani987/ghostfix-ai.git
+cd ghostfix-ai
+pip install -e .
+```
+
+Python 3.9 or newer is required.
+
+## Quick Start
+
+Cloud AI mode:
+
+```bash
+ghostfix watch "npm run dev" --fix --ai
+```
+
+GhostFix asks for the provider and API key each time `watch --ai` runs. This keeps new terminal sessions from silently reusing an old saved key.
+
+Force a provider but still enter the key for this run:
+
+```bash
+ghostfix watch "python manage.py runserver" --fix --ai --provider gemini
+```
+
+Local/custom model mode:
+
+```bash
+ghostfix init
+ghostfix watch "python app.py" --fix
+```
+
+Edit the generated `ghostfix.config.py` to point at Ollama, LM Studio, vLLM, or your own model server.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `ghostfix watch "CMD"` | Watch a command and print its output. |
+| `ghostfix watch "CMD" --fix --ai` | Watch and fix using a cloud AI provider. |
+| `ghostfix watch "CMD" --fix` | Watch and fix using `ghostfix.config.py` custom model settings. |
+| `ghostfix setup` | Save a default cloud provider/API key for setup workflows. |
+| `ghostfix init` | Create a project-level `ghostfix.config.py`. |
+| `ghostfix config-show` | Show the merged GhostFix configuration with masked API key. |
+
+## Flags
+
+| Flag | Description |
+| --- | --- |
+| `--fix` | Enable the AI repair pipeline when an error is detected. |
+| `--ai` | Use OpenAI, Claude, or Gemini instead of a custom model config. |
+| `--provider <name>` | Force `openai`, `claude`, or `gemini`. |
+| `--auto` | Apply patches without confirmation. Use carefully. |
+| `--config <path>` | Load a specific `ghostfix.config.py`. |
+| `--verbose` | Show extra renderer/debug output. |
+
+## How It Works
+
+```text
+watched command fails
+        |
+        v
+error parser detects language, error type, file, and line
+        |
+        v
+context builder collects source snippets and project tree
+        |
+        v
+AI provider returns root cause, explanation, and unified diff
+        |
+        v
+GhostFix shows the fix and asks before applying
+        |
+        v
+patcher backs up files, applies patch, and restarts command
+```
+
+## Configuration
+
+Create a config file:
+
+```bash
+ghostfix init
+```
+
+Example:
+
+```python
+GHOSTFIX_CONFIG = {
+    "model": {
+        "type": "custom",
+        "endpoint": "http://localhost:11434/api/chat",
+        "model_name": "codellama:13b",
+    },
+    "watch": {
+        "ignore": ["node_modules", ".git", "dist", "__pycache__"],
+        "max_file_size_kb": 500,
+        "context_lines": 60,
+    },
+    "fix": {
+        "auto_apply": False,
+        "create_backup": True,
+        "restart_on_fix": True,
+        "max_retries": 3,
+    },
+}
+```
+
+See [Configuration](docs/CONFIGURATION.md) and [Providers](docs/PROVIDERS.md).
+
+## Supported Error Families
+
+| Ecosystem | Detection | Stack trace parsing |
+| --- | --- | --- |
+| Python, Django, Flask | Yes | Yes |
+| Node.js, TypeScript, Next.js | Yes | Yes |
+| Java | Yes | Yes |
+| Go | Yes | Yes |
+| Rust | Yes | Yes |
+| Ruby | Yes | Yes |
+| Generic CLI output | Yes | Partial |
+
+## Safety
+
+GhostFix is designed to keep you in control:
+
+- Patches are shown before applying unless `--auto` is enabled.
+- Backups are created before patching by default.
+- The same error is not fixed forever; retry limits stop loops.
+- Project scanning ignores common generated folders.
+- API keys are masked in `config-show`.
+
+Read [Security](SECURITY.md) before using GhostFix on sensitive repositories.
+
+## Documentation
+
+- [Installation](docs/INSTALLATION.md)
+- [Configuration](docs/CONFIGURATION.md)
+- [Providers](docs/PROVIDERS.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Troubleshooting](docs/TROUBLESHOOTING.md)
+- [Release Checklist](docs/RELEASE_CHECKLIST.md)
+- [Contributing](CONTRIBUTING.md)
+- [Changelog](CHANGELOG.md)
+
+## Release Status
+
+Current version: `0.1.0`
+
+This is an early release. The core loop is ready for testing, but patch quality depends on the chosen AI model and the context available in the error output.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

ghostfix-0.1.0/SECURITY.md

@@ -0,0 +1,40 @@
+# Security
+
+GhostFix sends error output and selected source snippets to the configured AI provider. Review your provider's data policy before using GhostFix on private or regulated code.
+
+## Sensitive Data
+
+Before running GhostFix, avoid printing secrets in command output. Error logs may include:
+
+- API keys
+- Database URLs
+- Access tokens
+- User data
+- Internal file paths
+
+If a command may print secrets, prefer a local model endpoint and sanitize logs where possible.
+
+## API Keys
+
+`ghostfix watch --fix --ai` asks for provider/API key on each run.
+
+`ghostfix setup` can save a global provider/API key at:
+
+```text
+~/.ghostfix/config.json
+```
+
+Keep that file private.
+
+## Patches
+
+GhostFix can modify files. By default it asks before applying patches and creates backups. Avoid `--auto` on sensitive repositories unless you trust the configured model and have version control in place.
+
+## Reporting Issues
+
+If you find a security issue, do not open a public issue with exploit details. Contact the maintainers privately and include:
+
+- Affected version
+- Reproduction steps
+- Impact
+- Suggested mitigation, if known

ghostfix-0.1.0/docs/ARCHITECTURE.md

@@ -0,0 +1,75 @@
+# Architecture
+
+GhostFix is a small pipeline-oriented CLI.
+
+## Modules
+
+```text
+ghostfix/
+  cli.py                    command entry points
+  config/manager.py         global and project config loading
+  core/watcher.py           process runner and repair loop
+  core/error_parser.py      language/error/file/line extraction
+  core/context_builder.py   code context and project tree builder
+  core/patcher.py           unified diff application and backups
+  ai/router.py              prompt building and provider dispatch
+  ai/*_provider.py          OpenAI, Claude, Gemini, custom endpoints
+  ui/renderer.py            Rich terminal output
+```
+
+## Runtime Flow
+
+1. `cli.py` loads config and starts `ProcessWatcher`.
+2. `ProcessWatcher` runs the watched command with merged stdout/stderr.
+3. Each output line is passed to `ErrorParser.is_error_signal`.
+4. Error blocks are parsed into `ParsedError`.
+5. `ContextBuilder` resolves the primary file and related stack trace files.
+6. `AIRouter` builds a debugging prompt and calls the configured provider.
+7. The provider returns JSON with root cause, explanation, suggestion, and patch.
+8. `Renderer` shows the result.
+9. `Patcher` creates backups, applies the unified diff, and returns status.
+10. The watcher restarts the command if configured.
+
+## Patch Strategy
+
+`Patcher` tries:
+
+1. `git apply --whitespace=nowarn -`
+2. A minimal manual unified-diff fallback for simple single-file patches
+
+Backups are stored under:
+
+```text
+.ghostfix_backups/<timestamp>/
+```
+
+## Error Parsing
+
+GhostFix recognizes common signals from:
+
+- Python
+- Node.js and TypeScript
+- Java
+- Go
+- Rust
+- Ruby
+- Generic CLI output
+
+The parser chooses the most specific user file from the stack trace, then sends that location to the context builder.
+
+## AI Response Contract
+
+Providers must return content that can be parsed as JSON:
+
+```json
+{
+  "root_cause": "why the error happened",
+  "explanation": "deeper details",
+  "fix_suggestion": "what should change",
+  "patch": "--- a/file.py\n+++ b/file.py\n@@ ...",
+  "confidence": 0.75,
+  "related_files": ["optional.py"]
+}
+```
+
+If no code patch is appropriate, `patch` should be an empty string and `fix_suggestion` should explain the required command or manual action.