chore: bootstrap project scaffold

main.py

@@ -0,0 +1,67 @@
+"""Entry point for the AI sidebar application."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import gi
+
+gi.require_version("Gtk", "4.0")
+from gi.repository import Gtk  # noqa: E402
+
+from sidebar_window import SidebarWindow  # noqa: E402
+
+HEADLESS_ENV_VAR = "AI_SIDEBAR_HEADLESS"
+_STARTUP_FAILED = False
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Launch the GTK application and return the exit status."""
+    args = argv or sys.argv
+
+    if os.environ.get(HEADLESS_ENV_VAR) == "1":
+        print("Headless mode enabled; skipping GTK startup.")
+        return 0
+
+    if not Gtk.init_check():
+        print(
+            "Failed to initialize GTK. Ensure a display server is available.",
+            file=sys.stderr,
+        )
+        return 1
+
+    if not (os.environ.get("WAYLAND_DISPLAY") or os.environ.get("DISPLAY")):
+        print(
+            "No Wayland or X11 display detected. Launch this app inside a graphical session.",
+            file=sys.stderr,
+        )
+        return 1
+
+    app = Gtk.Application(application_id="ai.sidebar")
+    app.connect("activate", _on_activate)
+    status = app.run(args)
+    return 1 if _STARTUP_FAILED else status
+
+
+def _on_activate(app: Gtk.Application) -> None:
+    """Create and present the main sidebar window when the app activates."""
+    try:
+        window = SidebarWindow(application=app)
+    except RuntimeError as exc:
+        if "Gtk couldn't be initialized" in str(exc):
+            print(
+                "Failed to initialize GTK. Ensure a display server is available.",
+                file=sys.stderr,
+            )
+            global _STARTUP_FAILED
+            _STARTUP_FAILED = True
+            app.quit()
+            return
+        raise
+
+    window.present()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())