Pactown Live Debug 🚀

Multi-language code analyzer and auto-fixer with real-time feedback and Docker sandbox testing support.

---

📋 Spis treści

• Features
• Quick Start
  • Docker (recommended)
  • Without Docker
• How to Use
• Examples
  • Bash Script Analysis
  • Python Code Analysis
  • Dockerfile Analysis
  • Multi-language Support
• Detected Issues
• API Reference
• Pactfix CLI
• Project Structure
• Development
• Contributing
• License

---

⚡ Features

• ⚡ Real-time analysis - Błędy widoczne podczas pisania
• 🔧 Auto-fix - Automatyczne naprawianie typowych błędów
• 📜 History tracking - Pełna historia wykrytych błędów i poprawek
• 💾 Export options - Pobieranie poprawionego skryptu lub kopiowanie do schowka
• 🐳 Docker sandbox - Testowanie poprawek w izolowanym środowisku
• 🧪 Multi-language - Wsparcie dla 24+ języków i formatów
• 🔄 Live preview - Podgląd poprawek w czasie rzeczywistym
• 📊 Statistics - Liczba linii, znaków, błędów i ostrzeżeń
• 🔗 Share via URL - Udostępnianie kodu przez link

Clone the repository

git clone https://github.com/wronai/pactown-debug.git cd pactown-debug

Build and run with Docker Compose

docker-compose up --build

Or directly with Docker

docker build -t pactown-debug . docker run -p 8081:8081 pactown-debug

Open http://localhost:8081 in your browser.

# Requirements: Python 3.10+ and ShellCheck
sudo apt-get install shellcheck  # Ubuntu/Debian
brew install shellcheck           # macOS

# Clone and run
git clone https://github.com/wronai/pactown-debug.git
cd pactown-debug
pip install -e pactfix-py
python3 server.py

📖 How to Use

1. Paste your code - Insert your script in the left panel
2. Automatic analysis - Errors are detected in real-time
3. View fixes - Right panel shows corrected code with explanations
4. Export - Download or copy the fixed script

Bash Script Analysis

Input (with errors):

#!/usr/bin/bash
OUTPUT=/home/student/output-

for HOST in server{a,b}; do
    echo "$(ssh student@${HOST} hostname -f") >> ${OUTPUT}${HOST}
    if test -f $OUTPUT/$HOST; then
        rm -v $OUTPUT/$HOST
    fi
done

Output (fixed):

#!/usr/bin/bash
OUTPUT=/home/student/output-

for HOST in server{a,b}; do
    echo "$(ssh student@${HOST} hostname -f)" >> ${OUTPUT}${HOST}  # ✅ NAPRAWIONO: Poprawiono pozycję cudzysłowu zamykającego
    if test -f ${OUTPUT}/${HOST}; then  # ✅ NAPRAWIONO: Dodano klamerki do zmiennych
        rm -v ${OUTPUT}/${HOST}  # ✅ NAPRAWIONO: Dodano klamerki do zmiennych
    fi || exit 1  # ✅ NAPRAWIONO: Dodano obsługę błędów dla rm
done || exit 1  # ✅ NAPRAWIONO: Dodano obsługę błędów dla for loop

Python Code Analysis

Input (with issues):

#!/usr/bin/env python3
import os
import sys

def process_data(items=[]):
    for item in items:
        if item == None:
            print "Item is None"
            continue
        try:
            result = item * 2
        except:
            print "Error processing item"
    return items

if __name__ == "__main__":
    data = [1, 2, None, 4]
    process_data(data)

Output (fixed):

#!/usr/bin/env python3
import os
import sys

def process_data(items=None):  # ✅ NAPRAWIONO: Unikaj mutable default arguments
    if items is None:
        items = []
    for item in items:
        if item is None:  # ✅ NAPRAWIONO: Użyj 'is None' zamiast '== None'
            print("Item is None")  # ✅ NAPRAWIONO: Użyj print() z nawiasami (Python 3)
            continue
        try:
            result = item * 2
        except Exception as e:  # ✅ NAPRAWIONO: Unikaj bare except, łap konkretny wyjątek
            print(f"Error processing item: {e}")  # ✅ NAPRAWIONO: Użyj f-string i print()
    return items

if __name__ == "__main__":
    data = [1, 2, None, 4]
    process_data(data)  # ✅ NAPRAWIONO: Dodano docstring do funkcji

Dockerfile Analysis

Input (with issues):

FROM ubuntu:latest
RUN apt-get update
RUN apt-get install -y python3
COPY . /app
WORKDIR /app
CMD python3 app.py

Output (fixed):

FROM ubuntu:latest  # ✅ NAPRAWIONO: Użyj konkretnego tagu zamiast latest
RUN apt-get update && apt-get install -y python3 && rm -rf /var/lib/apt/lists/*  # ✅ NAPRAWIONO: Połącz RUN i wyczyść cache
COPY . /app
WORKDIR /app
CMD ["python3", "app.py"]  # ✅ NAPRAWIONO: Użyj exec form

Multi-language Support

Pactown Live Debug supports 24+ languages and formats:

Language	Status	Example
Bash/Shell	✅ Full	#!/bin/bash
Python	✅ Full	def hello():
JavaScript	✅ Full	console.log()
Dockerfile	✅ Full	FROM node:18
Docker Compose	✅ Full	version: '3.8'
Kubernetes YAML	✅ Full	apiVersion: v1
Terraform	✅ Full	resource "aws_instance"
SQL	✅ Full	SELECT * FROM
Nginx Config	✅ Full	server { ... }
GitHub Actions	✅ Full	on: [push]
GitLab CI	✅ New	stages: ...
Jenkinsfile	✅ New	pipeline { ... }
Ansible	✅ Full	---\n- hosts:
Markdown	✅ Full	``` fenced blocks
JSON	✅ Full	{ "key": "value" }
TOML	✅ Full	[section]
INI	✅ Full	key=value
And more...	🚧 In Progress	PHP, Go, Rust, Java

Bash/Shell

Code	Description	Example
SC1073	Syntax errors - misplaced quotes, brackets	echo "$(cmd")
SC2086	Unquoted variables	echo $VAR
SC2006	Use backticks instead of $()	cmd
SC2164	cd without error handling	cd /path
SC2162	read without -r flag	read var

Python

Code	Description	Example
PY001	Use print() without parentheses	print "text"
PY002	Mutable default arguments	def func(items=[]):
PY003	Use == None instead of is None	if x == None:
PY004	Bare except clause	except:
PY005	Missing docstring	def func():

Dockerfile

Code	Description	Example
DF001	Use 'latest' tag	FROM ubuntu:latest
DF002	Multiple RUN instructions	RUN apt-get update\nRUN apt-get install
DF003	Missing cache cleanup	RUN apt-get update
DF004	Use shell form of CMD	CMD python app.py

POST /api/analyze

Analyzes code and returns fixes for detected issues.

Request:

{
  "code": "#!/bin/bash\necho $VAR",
  "language": "bash"  // optional, auto-detected if not provided
}

Response:

{
  "originalCode": "#!/bin/bash\necho $VAR",
  "fixedCode": "#!/bin/bash\necho \"$VAR\"",
  "errors": [],
  "warnings": [
    {
      "line": 2,
      "column": 6,
      "code": "SC2086",
      "message": "Double quote to prevent globbing and word splitting",
      "severity": "warning"
    }
  ],
  "fixes": [
    {
      "line": 2,
      "message": "Dodano cudzysłowy wokół zmiennej",
      "before": "echo $VAR",
      "after": "echo \"$VAR\""
    }
  ],
  "language": "bash",
  "context": {}
}

GET /api/health

Health check endpoint.

Response:

{
  "status": "healthy",
  "version": "1.0.5",
  "features": {
    "shellcheck": false,
    "bash_analysis": true,
    "python_analysis": true,
    "auto_fix": true,
    "pactfix_api": false,
    "pactfix_url": "http://pactfix-api:5000"
  }
}

POST /api/snippet

Save or update a code snippet.

Request:

{
  "code": "#!/bin/bash\necho hello",
  "mode": "code"
}

Response:

{
  "id": "abc123def456",
  "url": "http://localhost:8081/#abc123def456"
}

🛠️ Pactfix CLI

The project includes the pactfix CLI tool for analyzing and auto-fixing code in multiple languages.

Key Features

• Project-wide scanning (--path) - Analyze entire projects
• Docker sandbox (--sandbox) - Test fixes in containers
• Automated testing (--test) - Run tests in sandbox
• Multi-language support - Bash, Python, Go, Node.js, Dockerfile, and more

Analyze and fix entire project

pactfix --path ./my-project

Run with Docker sandbox

pactfix --path ./my-project --sandbox

Sandbox with tests

pactfix --path ./my-project --sandbox --test

Insert comments above fixes

pactfix --path ./my-project --comment

Fix specific file

pactfix --file script.sh

List supported languages

pactfix --list-languages

### Testing with Sandboxes

The project includes test projects in `pactfix-py/test-projects/`:

```bash
# Run with in-container tests
make test-sandbox-tests

Each test project has _fixtures/faulty/ with baseline code for deterministic testing.

🏗️ Project Structure

pactown-debug/
├── app/                    # Frontend application
│   ├── index.html         # Main UI
│   └── assets/            # Static assets
├── server.py              # Python backend server
├── pactfix-py/            # Pactfix CLI tool
│   ├── pactfix/           # Main package
│   │   ├── analyzer.py    # Core analysis engine
│   │   ├── analyzers/     # Language-specific analyzers
│   │   └── cli.py         # CLI interface
│   ├── test-projects/     # Test projects with fixtures
│   │   ├── bash-project/
│   │   ├── python-project/
│   │   └── ...
│   └── scripts/           # Test scripts
├── tests/                 # Backend tests
├── e2e/                   # E2E tests (Playwright)
├── Dockerfile             # Container definition
├── docker-compose.yml     # Docker Compose config
├── Makefile              # Build and test targets
├── playwright.config.ts  # Playwright configuration
└── README.md             # This file

Sandbox with in-container tests

make test-sandbox-tests

### Test Coverage

- **Backend**: 8 tests covering API endpoints
- **Pactfix CLI**: 202 tests covering all analyzers
- **E2E**: 41 tests covering UI interactions
- **Sandbox**: Multiple real-world project scenarios

### Tech Stack

- **Frontend**: Vanilla JavaScript, CSS Grid, CSS Variables
- **Backend**: Python 3.10+, http.server
- **Analysis**: ShellCheck (with fallback to built-in analysis)
- **Testing**: Playwright (E2E), pytest (CLI), unittest (Backend)
- **Container**: Docker, Alpine-based

### Roadmap

- [x] Support for Python/Node.js/Go/Dockerfile
- [x] GitLab CI and Jenkinsfile support
- [ ] AI-powered explanations (llama.cpp)
- [ ] Collaborative debugging sessions
- [ ] VSCode extension
- [ ] More auto-fix rules
- [ ] Real-time collaboration
- [ ] Code snippet library
- [ ] Integration with GitHub PRs

### Contributing

We welcome contributions! Here's how to get started:

1. **Fork the repository**
   ```bash
   git clone https://github.com/your-username/pactown-debug.git

2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes

   • Add tests for new features
   • Follow the existing code style
   • Update documentation

4. Run tests

   make test

5. Commit your changes

   git commit -m 'Add amazing feature'

6. Push to branch

   git push origin feature/amazing-feature

7. Open a Pull Request

   • Describe your changes clearly
   • Link any relevant issues
   • Ensure CI passes

Clone the repo

git clone https://github.com/wronai/pactown-debug.git cd pactown-debug

Install dependencies

pip install -e pactfix-py[dev]

Install playwright browsers

npx playwright install

Run tests in watch mode

make test-frontend # E2E tests make test-pactfix # CLI tests

## 📄 License

Apache 2.0 License © 2026 Pactown Team

---

<div align="center">

**[⬆ Back to top](#pactown-live-debug-)**

Built with ❤️ by the [Pactown](https://pactown.dev) team

*Part of the [Pactown](https://pactown.dev) project - Educational platform for juniors*

[![GitHub stars](https://img.shields.io/github/stars/wronai/pactown-debug.svg?style=social&label=Star)](https://github.com/wronai/pactown-debug)
[![GitHub forks](https://img.shields.io/github/forks/wronai/pactown-debug.svg?style=social&label=Fork)](https://github.com/wronai/pactown-debug/fork)
[![GitHub issues](https://img.shields.io/github/issues/wronai/pactown-debug.svg)](https://github.com/wronai/pactown-debug/issues)
[![GitHub pull requests](https://img.shields.io/github/issues-pr/wronai/pactown-debug.svg)](https://github.com/wronai/pactown-debug/pulls)

</div>

<!-- taskill:status:start -->

## Status

_Last updated by [taskill](https://github.com/oqlos/taskill) at 2026-04-25 13:41 UTC_

| Metric | Value |
|---|---|
| HEAD | `5b97217` |
| Coverage | — |
| Failing tests | — |
| Commits in last cycle | 50 |

> A series of release commits plus targeted refactors and docs updates. Notable changes include core architecture cleanup, a new DSL refactor, documentation updates for the changelog (v1.2.0), and addition of code-quality metrics split into six supporting modules.

<!-- taskill:status:end -->