feat: add headless --lint CLI mode

Adds `--lint <file>` flag that runs flake8/pylint/AST linting without
starting the GUI. Output follows standard `file:line:col: code message`
format. Exit codes: 0 clean, 1 findings, 2 error.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Lukas Geiger

CHANGELOG.md

@@ -10,6 +10,9 @@ Format basiert auf [Keep a Changelog](https://keepachangelog.com/de/1.1.0/).
 - EXE neu gebaut 2026-06-01 (PyInstaller `--onefile`, `PythonBox.exe`); 14/14 Tests grün, Smoke-Test bestanden. Vorherige EXE: 2026-04-29.
 
 ### Hinzugefügt / Added
+- CLI-Lint-Modus: `python PythonBox_v8.py --lint <datei>` führt headless Linting durch (flake8 → pylint → AST-Fallback) und gibt Ergebnisse auf stdout aus. Exit-Codes: 0 = sauber, 1 = Findings, 2 = Fehler. Kein GUI-Start. Nützlich für CI, Automationen und LLM-Agenten.
+- `tests/test_cli_lint.py` mit 5 Tests für den CLI-Lint-Modus.
+- CLI-Parsing mit `argparse` (`parse_cli_args()`), rückwärtskompatibel zu `--open` und nackten Dateipfaden.
 - `llms.txt` mit kanonischem Repo-Kontext, Zielgruppe, Suchphrasen und Abgrenzung zu Devbox/Python-Box/Pybricks.
 - README-Starttabelle und GitHub-Actions-Badge für schnellere Nutzerführung.
 - App- und Fenstericon über `PythonBox.ico`.

PythonBox_v8.py

@@ -38,6 +38,7 @@
 import shutil
 import json
 import ast
+import argparse
 import subprocess
 import re
 import threading
@@ -195,6 +196,69 @@ def parse_startup_file_argument(argv: Optional[List[str]] = None) -> Optional[st
 
     return None
 
+
+def parse_cli_args(argv: Optional[List[str]] = None) -> argparse.Namespace:
+    """Parse CLI arguments for GUI and headless modes."""
+    parser = argparse.ArgumentParser(
+        prog="PythonBox",
+        description="Python Code Architect — Editor und Linter",
+        add_help=False,
+    )
+    parser.add_argument("--open", metavar="DATEI", help="Datei im Editor öffnen")
+    parser.add_argument("--lint", metavar="DATEI", help="Datei headless linten (kein GUI)")
+    parser.add_argument("file", nargs="?", default=None, help="Datei im Editor öffnen")
+    parser.add_argument("-h", "--help", action="help", default=argparse.SUPPRESS,
+                        help="Diese Hilfe anzeigen")
+
+    args = parser.parse_args(sys.argv[1:] if argv is None else argv)
+    if args.open is None and args.file:
+        args.open = args.file
+    return args
+
+
+def run_lint_cli(file_path: str) -> int:
+    """Run linter on a file in headless mode and print results to stdout."""
+    path = Path(file_path)
+    if not path.is_file():
+        print(f"Fehler: Datei nicht gefunden: {file_path}", file=sys.stderr)
+        return 2
+
+    try:
+        code = path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        try:
+            code = path.read_text(encoding="latin-1")
+        except Exception as exc:
+            print(f"Fehler: Datei nicht lesbar: {exc}", file=sys.stderr)
+            return 2
+
+    runner = LinterRunner()
+    results = runner.run_linter(code, str(path))
+
+    results.sort(key=lambda r: (r.get("line", 0), r.get("column", 0)))
+
+    errors = 0
+    warnings = 0
+    for r in results:
+        severity = r.get("severity", "warning")
+        if severity == "error":
+            errors += 1
+        else:
+            warnings += 1
+        line = r.get("line", 0)
+        col = r.get("column", 0)
+        code_id = r.get("code", "?")
+        msg = r.get("message", "").strip()
+        print(f"{path}:{line}:{col}: {code_id} {msg}")
+
+    if results:
+        print(f"\n{errors} Fehler, {warnings} Warnungen")
+        return 1
+    else:
+        print(f"{path}: Keine Findings")
+        return 0
+
+
 # ============================================================================
 # MODERN UI THEME
 # ============================================================================
@@ -4068,20 +4132,25 @@ def run_external_tool(self, path):
 # ============================================================================
 
 def main(argv: Optional[List[str]] = None):
+    args = parse_cli_args(argv)
+
+    if args.lint:
+        sys.exit(run_lint_cli(args.lint))
+
     cli_args = list(sys.argv[1:] if argv is None else argv)
-    startup_file = parse_startup_file_argument(cli_args)
+    startup_file = args.open
     app = QApplication([sys.argv[0], *cli_args])
     icon_path = Path(__file__).with_name("PythonBox.ico")
     icon = QIcon(str(icon_path)) if icon_path.exists() else QIcon()
     if not icon.isNull():
         app.setWindowIcon(icon)
     set_dark_theme(app)
-    
+
     window = PythonArchitect(startup_file=startup_file)
     if not icon.isNull():
         window.setWindowIcon(icon)
     window.show()
-    
+
     sys.exit(app.exec())
 
 

llms.txt

@@ -21,9 +21,16 @@ PythonBox is a lightweight local-first Python IDE for Windows. It combines a PyS
 - `PythonBox_v8.py`: main PySide6 application.
 - `README.md`: user-facing overview, installation, features, privacy boundary, and discovery keywords.
 - `PORTIERUNGSPLAN.md`: platform strategy for Windows-first desktop use and source-smoke portability.
-- `tests/`: regression tests for Qt6 compatibility, execution routing, Git diff/status handling, minimap settings, and an offscreen window smoke test.
+- `tests/`: regression tests for Qt6 compatibility, execution routing, Git diff/status handling, minimap settings, CLI lint mode, and an offscreen window smoke test.
 - `.github/workflows/tests.yml`: Windows regression test workflow for Python 3.10, 3.11, and 3.12.
 
+## CLI usage
+
+- `python PythonBox_v8.py` — start GUI
+- `python PythonBox_v8.py --open <file>` — start GUI with file open
+- `python PythonBox_v8.py <file>` — start GUI with file open (shorthand)
+- `python PythonBox_v8.py --lint <file>` — headless lint (no GUI), exit 0/1/2
+
 ## Search phrases
 
 python ide; lightweight python editor; pyside6 code editor; windows python ide; local-first developer tool; pdb debugger gui; python linting; code folding; git diff editor; offline python editor; VS Code handoff; PyCharm handoff.
@@ -36,4 +43,4 @@ PythonBox is not Jetify Devbox, Microsoft Dev Box, Box Python SDK, Pybricks, or
 
 PythonBox does not include telemetry, cloud sync, bundled credentials, or built-in external service API calls. It opens, saves, and executes files only through user-triggered local workflows.
 
-## Last-checked: 2026-06-12
+## Last-checked: 2026-06-19

tests/test_cli_lint.py

@@ -0,0 +1,84 @@
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPT = ROOT / "PythonBox_v8.py"
+
+
+def run_lint(target: str, timeout: int = 30) -> subprocess.CompletedProcess:
+    env = {**os.environ, "PYTHONIOENCODING": "utf-8"}
+    return subprocess.run(
+        [sys.executable, str(SCRIPT), "--lint", target],
+        capture_output=True, text=True, timeout=timeout, env=env,
+    )
+
+
+class TestCLILint(unittest.TestCase):
+
+    def test_lint_clean_file(self):
+        with tempfile.NamedTemporaryFile(suffix=".py", mode="w",
+                                         encoding="utf-8", delete=False) as f:
+            f.write("x = 1\n")
+            f.flush()
+            path = f.name
+        try:
+            result = run_lint(path)
+            self.assertIn("Keine Findings", result.stdout)
+            self.assertEqual(result.returncode, 0)
+        finally:
+            os.unlink(path)
+
+    def test_lint_syntax_error(self):
+        with tempfile.NamedTemporaryFile(suffix=".py", mode="w",
+                                         encoding="utf-8", delete=False) as f:
+            f.write("def foo(\n")
+            f.flush()
+            path = f.name
+        try:
+            result = run_lint(path)
+            self.assertEqual(result.returncode, 1)
+            self.assertTrue(len(result.stdout.strip()) > 0)
+        finally:
+            os.unlink(path)
+
+    def test_lint_nonexistent_file(self):
+        result = run_lint("nonexistent_file_xyz_12345.py")
+        self.assertEqual(result.returncode, 2)
+        self.assertIn("nicht gefunden", result.stderr)
+
+    def test_lint_output_format(self):
+        with tempfile.NamedTemporaryFile(suffix=".py", mode="w",
+                                         encoding="utf-8", delete=False) as f:
+            f.write("import os\nimport os\n")
+            f.flush()
+            path = f.name
+        try:
+            result = run_lint(path)
+            if result.returncode == 1:
+                lines = result.stdout.strip().split("\n")
+                finding_lines = [l for l in lines if path in l]
+                for line in finding_lines:
+                    self.assertRegex(line, r".+:\d+:\d+: \S+ .+")
+        finally:
+            os.unlink(path)
+
+    def test_no_gui_started(self):
+        with tempfile.NamedTemporaryFile(suffix=".py", mode="w",
+                                         encoding="utf-8", delete=False) as f:
+            f.write("x = 1\n")
+            f.flush()
+            path = f.name
+        try:
+            result = run_lint(path)
+            self.assertNotIn("QApplication", result.stderr)
+            self.assertNotIn("Traceback", result.stderr)
+        finally:
+            os.unlink(path)
+
+
+if __name__ == "__main__":
+    unittest.main()