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

🚀 Quick Start

Docker (recommended)

# 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.

Without Docker

# 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 -r requirements.txt
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

📚 Examples

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

🐛 Detected Issues

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

📡 API Reference

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.2.0",
  "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

Usage Examples

# 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/:

# Run sandbox tests
make test-sandbox

# 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
├── requirements.txt      # Python dependencies
└── README.md             # This file

🧪 Testing

Running Tests

# Run all tests
make test

# Backend tests
make test-backend

# Pactfix CLI tests
make test-pactfix

# E2E tests
make test-frontend

# Sandbox tests
make test-sandbox

# 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

🚀 Development

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

• Support for Python/Node.js/Go/Dockerfile
• 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

   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

Development Setup

# Clone the repo
git clone https://github.com/wronai/pactown-debug.git
cd pactown-debug

# Install dependencies
pip install -r requirements.txt
cd pactfix-py && pip install -e .[dev] && cd ..

# Install playwright browsers
npx playwright install

# Run development server
python3 server.py

# Run tests in watch mode
make test-frontend  # E2E tests
make test-pactfix   # CLI tests

📄 License

Apache 2.0 License - Softreck © 2026

---

⬆ Back to top

Built with ❤️ by the Pactown team

Part of the Pactown project - Educational platform for juniors