fix: support CodeBox startup file arguments

Author: Lukas Geiger

.github/workflows/linux-platform-smoke.yml

@@ -15,10 +15,10 @@ jobs:
       PYTHONIOENCODING: utf-8
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 

.gitignore

@@ -62,3 +62,8 @@ DIAGNOSE_REPORT.md
 SKILL.md
 tmpclaude-*
 .claude/
+# ---- Interne Steuerungsdateien ----
+DECISIONS.md
+PORTIERUNGSPLAN.md
+TODO.md
+DONE.md

CHANGELOG.md

@@ -5,7 +5,16 @@ Format basiert auf [Keep a Changelog](https://keepachangelog.com/de/1.1.0/).
 
 ## [Unreleased]
 
+### Build / Release
+- EXE aktualisiert 2026-06-01 (OneDrive-Lock aufgelöst nach Beenden alter Prozesse); enthält Startup-/CLI-Bug-Fix (`--open`-Argument + offener Bootstrap-Tab). 13/13 Tests grün, Smoke OK.
+- EXE neu gebaut 2026-06-01 (PyInstaller, `CodeBox.spec` → `C:\_Local_DEV\codex_build\codebox`); 11/12 Tests grün (1 skipped), Smoke-Test bestanden. Vorherige EXE: 2026-05-28.
+
 ### Hinzugefügt
+- Linux-Source-Smoke für offscreen App-Start, Dateiöffnung, Terminalpfad,
+  Projektbaum-`xdg-open` und lokale Python-Run-Commands.
+- Regressionstest für Startup-Dateiübergabe per `--open` und positionalem Pfad.
+- README-Discoverability für GitHub/Web-Suche geschärft: englischer SEO-Einstieg,
+  CodeBox-Namenskollision erklärt, Quickstart und präzisere Suchbegriffe ergänzt.
 - Headless-Smoke-Test für MainWindow-Instanziierung
 - Optionale LSP-Runtime-Tests für `python-lsp-server[all]`:
   Diagnostics bei Syntaxfehlern und Completion über `pylsp`.
@@ -15,6 +24,8 @@ Format basiert auf [Keep a Changelog](https://keepachangelog.com/de/1.1.0/).
   beim Tippen an den aktiven LSP-Client geschickt.
 
 ### Behoben
+- `python main.py --open <datei>` und nackte Dateipfade öffnen jetzt die Datei
+  direkt beim Start und entfernen den leeren Bootstrap-Tab.
 - `QApplication` fehlte im Import von `ui/main_window.py` (wurde in Theme-Lambda verwendet)
 - Diverse ungenutzte Imports entfernt (core, features, languages, ui)
 - Fenstertitel liest die Version jetzt aus `version.py` statt aus einem Hardcode

README.md

@@ -1,10 +1,21 @@
-# CodeBox
+# CodeBox - local PySide6 desktop code editor
 
-Mehrsprachiger Desktop-Codeeditor auf Basis von PySide6.
-Multi-language desktop code editor built with PySide6.
+CodeBox is a local-first desktop IDE for Windows developers who want a
+lightweight PySide6 code editor with tabs, a project tree, an integrated
+terminal, Git helpers, syntax highlighting and Language Server Protocol
+diagnostics.
 
-CodeBox ist aus PythonBox v8 hervorgegangen und bündelt Editor, Projektbaum,
-Terminal sowie erste LSP- und API-Grundlagen in einer lokalen IDE.
+Mehrsprachiger Desktop-Codeeditor auf Basis von PySide6. CodeBox ist aus
+PythonBox v8 hervorgegangen und bündelt Editor, Projektbaum, Terminal sowie
+erste LSP- und API-Grundlagen in einer lokalen IDE.
+
+## Why CodeBox
+
+- Local-first: edit files on your machine without cloud accounts or telemetry.
+- PySide6 desktop stack: native Windows app behavior with a small Python codebase.
+- Multi-language workflow: Python, JavaScript, TypeScript, C++, Rust, Go and Java.
+- LSP-ready: diagnostics and completion can connect to installed language servers.
+- Dev-bricks ecosystem: companion to PythonBox and DevCenter for small local tools.
 
 ## Screenshot
 
@@ -26,10 +37,20 @@ Terminal sowie erste LSP- und API-Grundlagen in einer lokalen IDE.
 ```bash
 pip install -r requirements.txt
 python main.py
+python main.py --open path/to/file.py
 ```
 
 Alternativ per Doppelklick auf `start.bat`.
 
+### Quick start
+
+1. Clone `https://github.com/dev-bricks/CodeBox`.
+2. Install dependencies with `pip install -r requirements.txt`.
+3. Run `python main.py`.
+4. Optional: install language servers such as `python-lsp-server[all]` or
+   `typescript-language-server` for diagnostics and completion.
+5. Open a file directly with `python main.py --open path/to/file.py`.
+
 ### Voraussetzungen / Requirements
 
 - Python 3.10+
@@ -86,6 +107,14 @@ config/            Konfigurationsdateien
 themes/            QSS-Themes
 ```
 
+## Discovery keywords
+
+CodeBox is best described as a local PySide6 code editor, Windows desktop IDE,
+offline code editor, LSP-enabled Python editor and lightweight multi-language
+developer tool. The repository name collides with older projects called
+`codebox`, so searches are most precise with `dev-bricks CodeBox`,
+`CodeBox PySide6`, `CodeBox LSP editor` or `file-bricks/dev-bricks desktop IDE`.
+
 ## Status
 
 Aktueller Stand: `DEV`, Version `0.1.0`

main.py

@@ -7,6 +7,7 @@
 Author: Lukas
 """
 
+import argparse
 import sys
 from pathlib import Path
 
@@ -24,22 +25,54 @@ def load_app_icon() -> QIcon:
     return QIcon(str(icon_path)) if icon_path.exists() else QIcon()
 
 
-def main():
+def parse_launch_args(argv=None):
+    """Extract startup file arguments and leave unknown Qt args untouched."""
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("--open", dest="open_path")
+    args, qt_args = parser.parse_known_args(list(argv or []))
+
+    startup_path = Path(args.open_path).expanduser() if args.open_path else None
+    if startup_path is None and qt_args and not qt_args[0].startswith("-"):
+        startup_path = Path(qt_args[0]).expanduser()
+        qt_args = qt_args[1:]
+    return startup_path, qt_args
+
+
+def _should_replace_startup_placeholder(window) -> bool:
+    """Detect the initial empty tab created during window bootstrap."""
+    tab = window.tab_widget.current_tab()
+    return bool(
+        tab
+        and window.tab_widget.count() == 1
+        and tab.file_path is None
+        and not tab.is_modified
+        and not tab.editor.toPlainText()
+    )
+
+
+def main(argv=None):
     """Entry point for CodeBox."""
-    app = QApplication(sys.argv)
+    startup_path, qt_args = parse_launch_args(sys.argv[1:] if argv is None else argv)
+
+    app = QApplication.instance() or QApplication([sys.argv[0], *qt_args])
     icon = load_app_icon()
     if not icon.isNull():
         app.setWindowIcon(icon)
     apply_theme(app, DEFAULT_THEME)
 
     from ui.main_window import MainWindow
     window = MainWindow()
+    replace_placeholder = _should_replace_startup_placeholder(window)
     if not icon.isNull():
         window.setWindowIcon(icon)
+    if startup_path:
+        opened_tab = window.open_path(startup_path)
+        if opened_tab and replace_placeholder and window.tab_widget.count() > 1:
+            window.tab_widget.close_tab(0)
     window.show()
 
-    sys.exit(app.exec())
+    return app.exec()
 
 
 if __name__ == "__main__":
-    main()
+    sys.exit(main())

tests/test_startup_args.py

@@ -0,0 +1,43 @@
+from unittest.mock import patch
+
+import main
+
+
+def test_parse_launch_args_supports_open_flag_and_positional(tmp_path):
+    target = tmp_path / "script.py"
+
+    startup_path, qt_args = main.parse_launch_args(
+        ["--open", str(target), "--platform", "offscreen"]
+    )
+    assert startup_path == target
+    assert qt_args == ["--platform", "offscreen"]
+
+    startup_path, qt_args = main.parse_launch_args([str(target)])
+    assert startup_path == target
+    assert qt_args == []
+
+
+def test_main_opens_startup_file_from_open_flag(tmp_path):
+    target = tmp_path / "script.py"
+    target.write_text("print('hi')\n", encoding="utf-8")
+    captured = []
+
+    with (
+        patch("features.terminal.TerminalWidget._start_shell", lambda self: None),
+        patch("ui.main_window.MainWindow.show", lambda self: captured.append(self)),
+        patch("PySide6.QtWidgets.QApplication.exec", return_value=0),
+    ):
+        exit_code = main.main(["--open", str(target)])
+
+    assert exit_code == 0
+    assert len(captured) == 1
+
+    window = captured[0]
+    try:
+        assert window.tab_widget.count() == 1
+        tab = window.tab_widget.current_tab()
+        assert tab is not None
+        assert tab.file_path == target
+        assert window.tab_widget.tabText(window.tab_widget.currentIndex()) == "script.py"
+    finally:
+        window.close()

ui/main_window.py

@@ -160,12 +160,22 @@ def open_file(self):
             "Alle Dateien (*);;Python (*.py);;JavaScript (*.js);;C++ (*.cpp *.h)"
         )
         if path:
-            tab = self.tab_widget.open_file(Path(path))
-            if tab and tab.provider:
-                self.lang_label.setText(tab.provider.get_name())
-                self.output.run_btn.setEnabled(True)
-                self._connect_lsp(tab, Path(path))
-            self._connect_cursor(tab)
+            self.open_path(Path(path))
+
+    def open_path(self, file_path: Path):
+        """Öffnet einen konkreten Pfad ohne Dateidialog."""
+        path = Path(file_path)
+        if not path.exists():
+            QMessageBox.warning(self, "Datei öffnen", f"Datei nicht gefunden:\n{path}")
+            return None
+
+        tab = self.tab_widget.open_file(path)
+        if tab and tab.provider:
+            self.lang_label.setText(tab.provider.get_name())
+            self.output.run_btn.setEnabled(True)
+            self._connect_lsp(tab, path)
+        self._connect_cursor(tab)
+        return tab
 
     def _connect_lsp(self, tab, file_path: Path):
         """Verbindet den Tab mit dem LSP-Server für die Sprache."""
@@ -437,12 +447,7 @@ def _connect_cursor(self, tab):
 
     def _open_file_from_project(self, file_path):
         """Öffnet eine Datei aus dem Projektbaum."""
-        tab = self.tab_widget.open_file(file_path)
-        if tab and tab.provider:
-            self.lang_label.setText(tab.provider.get_name())
-            self.output.run_btn.setEnabled(True)
-            self._connect_lsp(tab, file_path)
-        self._connect_cursor(tab)
+        self.open_path(file_path)
 
     def _toggle_project_view(self):
         """Blendet den Projektbaum ein/aus."""