pycforge-sdk 0.6.3__py3-none-any.whl

pycforge_sdk/gui/window.py

@@ -0,0 +1,559 @@
+"""Desktop workflow coordinator; conversion and readiness live in the SDK."""
+from pathlib import Path
+import copy
+import json
+import sys
+from PySide6.QtCore import Qt, QSize, QTimer, QFileSystemWatcher, QSettings
+from PySide6.QtGui import QAction, QKeySequence
+from PySide6.QtWidgets import (QMainWindow, QWidget, QVBoxLayout, QHBoxLayout,
+    QLineEdit, QSplitter, QStackedWidget, QListWidget, QToolBar, QPlainTextEdit,
+    QDialog, QFrame, QLabel, QComboBox, QScrollArea)
+from .. import __version__
+from .visual.qt_window_chrome import install_frameless_window_chrome
+from .visual.qt_icons import load_pycforge_icon
+from .identity import SDK_QSS, sdk_icon, brand_panel, PathLabel
+from .startup import StartupDialog
+from .widgets import label, button, SafeBrowser, MenuIconStyle
+from .dialogs import Dialog, Prompt, PathDialog, NewProjectDialog, SourceDialog
+from .editor import ProjectEditor
+from .scanner import ScannerPanel
+from .reference import ReferencePanel
+from .jobs import JobRunner
+
+
+class MainWindow(QMainWindow):
+    def __init__(self, *, engine_python=None, cache=None, compiler=None, timeout=30,
+                 settings=None, parent=None):
+        super().__init__(parent)
+        self.settings = settings if settings is not None else QSettings("PyCForge", "SDK")
+        self.cache = str(cache or Path.home()/".pycforge-sdk"/"cache")
+        self.timeout = timeout
+        self.snapshot = None
+        self.dirty = self.external_change = False
+        self.revision = 0
+        self.ready = False
+        self.connection = "unavailable"
+        self.execution_available = False
+        self.templates = []; self.methods = []; self.operations = []
+        self.workbench = None; self.help_documents = []; self.help_engine = ""
+        self.close_pending = self.close_after_save = False
+        self.after_connect = None
+        self.explicit_engine = str(engine_python) if engine_python else None
+        self.startup_dialog = None
+        self.offline_pending = False
+        self.catalogue_offline = False
+        self.setWindowTitle(f"PyCForge SDK {__version__}")
+        self.setWindowIcon(sdk_icon())
+        self.setStyleSheet(SDK_QSS)
+        self.setMinimumSize(920, 640); self.resize(1320, 860)
+        self.runner = JobRunner(self)
+        self.runner.busy_changed.connect(self.busy_changed)
+        self.runner.finished.connect(self.finished)
+        self.runner.progress.connect(self.progress)
+        self.watcher = QFileSystemWatcher(self)
+        self.watcher.fileChanged.connect(self.disk_changed)
+        self._make_actions()
+        self._make_menus()
+        central = QWidget(); layout = QVBoxLayout(central); layout.setContentsMargins(10, 7, 10, 8)
+        self.link_panel = QFrame(); self.link_panel.setObjectName("SDKEngineLink")
+        link_layout = QHBoxLayout(self.link_panel); link_layout.setContentsMargins(13, 10, 12, 10)
+        mark = QLabel(); mark.setFixedSize(40, 40)
+        mark.setPixmap(sdk_icon().pixmap(mark.size(), self.devicePixelRatioF())); link_layout.addWidget(mark)
+        link_text = QVBoxLayout(); link_text.setSpacing(3)
+        tag = label("ENGINE CONNECTION"); tag.setObjectName("SDKConnectionTag"); link_text.addWidget(tag)
+        self.connection_label = label("Find your PyCForge installation")
+        self.connection_label.setObjectName("SDKConnectionTitle"); link_text.addWidget(self.connection_label)
+        self.connection_path = PathLabel(); link_text.addWidget(self.connection_path)
+        self.connection_summary = label("Conversion capabilities and reference come from PyCForge.", muted=True)
+        link_text.addWidget(self.connection_summary); link_layout.addLayout(link_text, 1)
+        self.locate_button = button("Locate PyCForge…", "open", self.browse_engine)
+        link_layout.addWidget(self.locate_button)
+        self.connect_button = button("Refresh", "history", self.refresh_engine,
+            "Reconnect to PyCForge and refresh its conversion capabilities and reference.")
+        self.connect_button.setProperty("sdkAccent", True); link_layout.addWidget(self.connect_button)
+        self.settings_button = button("Engine and tools", "settings", self.toggle_connection_settings)
+        link_layout.addWidget(self.settings_button); layout.addWidget(self.link_panel)
+        self.connection_settings = QWidget(); self.connection_settings.setObjectName("SDKConnectionSettings")
+        settings_layout = QVBoxLayout(self.connection_settings); settings_layout.setContentsMargins(0, 0, 0, 0)
+        engine_row = QHBoxLayout()
+        self.engine = QLineEdit(str(engine_python or self.settings.value("last_engine", self.settings.value("engine", sys.executable))))
+        self.engine.setAccessibleName("PyCForge Python interpreter")
+        self.engine.setToolTip("Choose the Python interpreter containing your PyCForge installation. The SDK uses it in a separate process.")
+        engine_row.addWidget(label("PyCForge Python")); engine_row.addWidget(self.engine, 1)
+        self.engine_browse = button("Locate…", "open", self.browse_engine)
+        self.search_button = button("Find installed", "diagnostics", self.begin_startup)
+        engine_row.addWidget(self.engine_browse); engine_row.addWidget(self.search_button)
+        self.current_python = button("This Python", "module", lambda: self.engine.setText(sys.executable),
+            "Use the SDK's Python interpreter if PyCForge is installed in this same environment; then Refresh.")
+        engine_row.addWidget(self.current_python)
+        settings_layout.addLayout(engine_row)
+        compiler_row = QHBoxLayout()
+        self.compiler = QLineEdit(str(compiler or self.settings.value("compiler", "gcc")))
+        self.compiler.setAccessibleName("Native verification compiler")
+        self.compiler.setToolTip("External compiler used only when you request native verification. The engine supplies its supported test profile.")
+        compiler_row.addWidget(label("Verify with")); compiler_row.addWidget(self.compiler, 1)
+        self.compiler_browse = button("Browse", "open", self.browse_compiler)
+        compiler_row.addWidget(self.compiler_browse)
+        settings_layout.addLayout(compiler_row)
+        layout.addWidget(self.connection_settings); self.connection_settings.hide()
+        self.identity = label("No extension project open", muted=True); layout.addWidget(self.identity)
+        split = QSplitter(); layout.addWidget(split, 1)
+        self.navigation = QListWidget(); self.navigation.setObjectName("DocumentList")
+        self.navigation.setAccessibleName("SDK workspace")
+        self.navigation.addItems(["Scanner", "Edit extension", "Engine reference", "Activity"])
+        for index in range(self.navigation.count()):
+            self.navigation.item(index).setSizeHint(QSize(170, 44))
+            self.navigation.item(index).setIcon(load_pycforge_icon(("diagnostics", "module", "help", "history")[index]))
+        self.navigation.setIconSize(QSize(24, 24))
+        sidebar = QWidget()
+        sidebar.setMinimumWidth(220); sidebar.setMaximumWidth(250)
+        sidebar_layout = QVBoxLayout(sidebar)
+        sidebar_layout.setContentsMargins(0, 0, 0, 0)
+        sidebar_layout.addWidget(brand_panel(sidebar))
+        sidebar_layout.addWidget(self.navigation, 1)
+        self.pages = QStackedWidget()
+        self.scanner = ScannerPanel(); self.editor = ProjectEditor(); self.reference = ReferencePanel()
+        self.activity = QPlainTextEdit(); self.activity.setReadOnly(True)
+        self.activity.setMaximumBlockCount(4000); self.activity.setAccessibleName("SDK activity and diagnostics")
+        self.scanner_scroll = QScrollArea(); self.scanner_scroll.setWidgetResizable(True)
+        self.scanner_scroll.setFrameShape(QFrame.Shape.NoFrame)
+        self.scanner.setMinimumHeight(max(580, 48 * self.font().pointSize()))
+        self.scanner_scroll.setWidget(self.scanner)
+        for page in (self.scanner_scroll, self.editor, self.reference, self.activity): self.pages.addWidget(page)
+        split.addWidget(sidebar); split.addWidget(self.pages); split.setSizes([220, 1100])
+        self.navigation.currentRowChanged.connect(self.pages.setCurrentIndex); self.navigation.setCurrentRow(0)
+        self.editor.changed.connect(self.edited)
+        self.editor.source_requested.connect(self.edit_source)
+        self.scanner.field_requested.connect(self.open_finding)
+        self.engine.textChanged.connect(self.engine_changed)
+        self.compiler.textChanged.connect(self.compiler_changed)
+        self.setCentralWidget(central)
+        self.chrome = install_frameless_window_chrome(self, self.menuBar())
+        self.statusBar().showMessage("Find PyCForge, then choose or open an extension project.")
+        self.update_actions()
+
+    def _action(self, key, text, icon, callback, shortcut=None, tip=""):
+        action = QAction(load_pycforge_icon(icon), text, self)
+        action.setIconVisibleInMenu(True)
+        action.setObjectName("sdkAction_" + key); action.setToolTip(tip or text)
+        if shortcut: action.setShortcut(QKeySequence(shortcut))
+        action.triggered.connect(callback); self.actions[key] = action
+        return action
+
+    def _make_actions(self):
+        self.actions = {}
+        self._action("new", "New", "add-document", self.new_project, "Ctrl+N")
+        self._action("open", "Open", "open", self.open_project, "Ctrl+O")
+        self._action("save", "Save", "save-python", self.save_project, "Ctrl+S")
+        self._action("reload", "Reload from disk", "history", self.reload_project)
+        self._action("scan", "Scan", "diagnostics", self.scan, "F5", "Check current packaging readiness without running fixture programs.")
+        self._action("verify", "Verify fixtures", "check", self.verify, "F6", "Explicitly convert, compile and run the complete saved fixture suite.")
+        self._action("build", "Package", "save-c", self.build, "Ctrl+B", "Package only the exact project approved by current verification.")
+        self._action("cancel", "Cancel", "cancel", self.cancel)
+        self._action("document", "Add missing Help fields", "help", self.prepare_documentation)
+        self._action("register", "Register a package in PyCForge…", "module", self.register)
+        self._action("help", "SDK Help", "help", self.help, "F1")
+        self._action("exit", "Exit", "exit", self.close, "Ctrl+Q")
+        bar = QToolBar("Extension actions", self); bar.setMovable(False)
+        bar.setToolButtonStyle(Qt.ToolButtonStyle.ToolButtonTextBesideIcon); bar.setIconSize(QSize(24, 24))
+        for key in ("new", "open", "save", "scan", "verify", "build", "cancel"):
+            if key == "scan": bar.addSeparator()
+            bar.addAction(self.actions[key])
+            if key in ("scan", "verify", "build"):
+                bar.widgetForAction(self.actions[key]).setProperty("sdkAccent", True)
+        self.addToolBar(bar)
+
+    def _make_menus(self):
+        for title, keys in (("&File", ("new", "open", "save", "reload", "exit")),
+                            ("&Extension", ("scan", "verify", "build", "cancel")),
+                            ("&Tools", ("document", "register")), ("&Help", ("help",))):
+            menu = self.menuBar().addMenu(title)
+            menu.setObjectName("PyCForgeMenu")
+            menu.setStyle(MenuIconStyle(menu))
+            menu.setStyleSheet("QMenu::icon { width: 24px; height: 24px; } QMenu::item { min-height: 30px; }")
+            for key in keys: menu.addAction(self.actions[key])
+        self.menuBar().setNativeMenuBar(False)
+
+    def configuration(self):
+        return {"engine_python": self.engine.text().strip(), "cache": self.cache, "timeout": self.timeout}
+
+    def update_actions(self):
+        busy = self.runner.busy
+        project = self.snapshot is not None
+        saved = project and not self.dirty and not self.external_change
+        connected = self.connection == "connected" and self.execution_available
+        for key in ("open", "reload", "new", "register", "document", "save", "scan", "verify", "build"):
+            allowed = {"open": True, "reload": project, "new": bool(self.templates),
+                       "register": connected, "document": saved and connected,
+                       "save": project and self.dirty and not self.external_change,
+                       "scan": saved, "verify": saved and connected,
+                       "build": saved and connected and self.ready}[key]
+            self.actions[key].setEnabled(bool(allowed and not busy))
+        self.actions["cancel"].setEnabled(busy)
+        for widget in (self.engine, self.compiler, self.engine_browse, self.compiler_browse, self.connect_button,
+                       self.current_python, self.locate_button, self.search_button):
+            widget.setEnabled(not busy)
+        self.editor.setEnabled(project and (not busy or self.runner.method in ("readiness", "verify")))
+        self.setWindowTitle((self.snapshot["document"]["declaration"].get("namespace", "Extension") +
+                            (" •" if self.dirty else "") + " — " if project else "") + f"PyCForge SDK {__version__}")
+
+    def invalidate(self, message):
+        self.ready = False; self.revision += 1
+        self.scanner.invalidate(message); self.update_actions()
+
+    def edited(self):
+        self.dirty = True
+        self.invalidate("Unsaved edits. Save the project, then scan and verify its new contents.")
+
+    def engine_changed(self):
+        self.connection = "unavailable"
+        self.execution_available = False
+        self.templates = []; self.methods = []; self.operations = []
+        self.connection_label.setText("Engine selection changed. Connect to refresh the reference.")
+        self.connection_path.setText(self.engine.text())
+        self.connection_summary.setText("Refresh to check this installation and load its capabilities.")
+        self.locate_button.show()
+        self.reference.state.setText("Previous engine reference — connect to refresh. Execution approval cleared.")
+        self.invalidate("Engine selection changed. Connect, then scan the saved project.")
+
+    def compiler_changed(self):
+        self.invalidate("Compiler selection changed. Scan to check whether its identity matches verification.")
+
+    def browse_engine(self):
+        path = PathDialog.choose(self.startup_dialog or self, "Locate PyCForge", initial=self.engine.text(), mode="engine")
+        if path:
+            self.begin_startup(locations=[path])
+
+    def toggle_connection_settings(self):
+        self.connection_settings.setVisible(not self.connection_settings.isVisible())
+
+    def refresh_engine(self):
+        if self.connection == "connected" or self.engine.text().strip():
+            self.connect_engine()
+        else:
+            self.begin_startup()
+
+    def begin_startup(self, _checked=False, *, locations=None):
+        if self.runner.busy:
+            return
+        self.offline_pending = False
+        if self.startup_dialog is None:
+            self.startup_dialog = StartupDialog(self)
+            self.startup_dialog.offline_requested.connect(self.continue_offline)
+            self.startup_dialog.locate_requested.connect(self.browse_engine)
+            self.startup_dialog.retry_requested.connect(self.begin_startup)
+            self.startup_dialog.engine_selected.connect(self.select_discovered_engine)
+        self.startup_dialog.search_started(); self.startup_dialog.show()
+        self.ready = False
+        preferred = None
+        if locations is None:
+            if self.explicit_engine:
+                locations = [self.explicit_engine]
+                self.explicit_engine = None
+            else:
+                preferred = self.settings.value("last_engine", self.settings.value("engine", None))
+        self.start("discover", kwargs={"preferred": preferred, "locations": locations,
+                                     "timeout": min(self.timeout, 3), "search_timeout": min(self.timeout, 20)})
+
+    def select_discovered_engine(self, path):
+        if self.close_pending or self.offline_pending:
+            return
+        self.engine.setText(path)
+        if self.startup_dialog:
+            self.startup_dialog.connecting(path)
+        self.connect_engine()
+
+    def continue_offline(self):
+        self.offline_pending = True
+        if self.runner.busy:
+            self.runner.cancel()
+            if self.startup_dialog:
+                self.startup_dialog.status.setText("Stopping the connection search…")
+                self.startup_dialog.offline.setEnabled(False)
+        else:
+            self._load_offline()
+
+    def _load_offline(self):
+        self.offline_pending = False
+        self.catalogue_offline = True
+        self.start("catalogue", kwargs={"offline": True})
+
+    def _reveal_workspace(self):
+        self.show()
+        if self.startup_dialog:
+            dialog, self.startup_dialog = self.startup_dialog, None
+            dialog.accept(); dialog.deleteLater()
+
+    def browse_compiler(self):
+        path = PathDialog.choose(self, "Choose a native verification compiler", initial=self.compiler.text())
+        if path: self.compiler.setText(path)
+
+    def connect_engine(self):
+        self.ready = False
+        self.catalogue_offline = False
+        self.start("catalogue")
+
+    def start(self, method, args=(), kwargs=None):
+        if self.runner.busy: return False
+        if method in ("save_project", "prepare_documentation") and self.watcher.files():
+            self.watcher.removePaths(self.watcher.files())
+        if method in ("readiness", "verify", "build"):
+            self.ready = False; self.navigation.setCurrentRow(0)
+            self.scanner.running({"readiness": "Scanning extension…", "verify": "Verifying fixtures…", "build": "Checking and packaging…"}[method])
+        self.statusBar().showMessage("Working: " + method.replace("_", " "))
+        return self.runner.start(self.configuration(), method, args, kwargs, revision=self.revision)
+
+    def allow_discard(self):
+        if not self.dirty: return True
+        return Prompt.ask(self, "Unsaved project", "Discard your unsaved project edits and continue?",
+                          [("discard", "Discard edits"), ("cancel", "Keep editing")]) == "discard"
+
+    def new_project(self):
+        if not self.allow_discard(): return
+        dlg = NewProjectDialog(self.templates, self)
+        if dlg.exec() == QDialog.DialogCode.Accepted:
+            self.start("create_project", (dlg.directory.text(),), {"author": dlg.author.text(), "template": dlg.template.currentData()})
+
+    def open_project(self, path=None):
+        if not self.allow_discard(): return
+        path = path if isinstance(path, str) else PathDialog.choose(self, "Open extension project", mode="directory",
+            description="Select the SDK extension folder containing project.json.")
+        if path: self.start("open_project", (path,))
+
+    def reload_project(self):
+        if self.snapshot and self.allow_discard(): self.start("open_project", (self.snapshot["directory"],))
+
+    def load_snapshot(self, data):
+        self.snapshot = data; self.dirty = self.external_change = False
+        self.editor.directory = data["directory"]
+        self.editor.expected_sha256 = data["project_sha256"]
+        self.editor.configuration = self.configuration()
+        self.editor.load(data["document"], methods=self.methods, operations=self.operations, workbench=self.workbench)
+        self.identity.setText(data["directory"])
+        self.rewatch()
+        self.invalidate("Saved project loaded. Run Scan to check what is ready for verification or packaging.")
+
+    def rewatch(self):
+        if self.watcher.files(): self.watcher.removePaths(self.watcher.files())
+        if self.snapshot:
+            root = Path(self.snapshot["directory"])
+            paths = [str(root/"project.json"), *[str(root/name) for name in self.snapshot["sources"]]]
+            paths.append(str(root/".pycforge-sdk/verification.json"))
+            self.watcher.addPaths([p for p in paths if Path(p).is_file()])
+
+    def disk_changed(self, path):
+        if path.endswith("/.pycforge-sdk/verification.json") or path.endswith("\\.pycforge-sdk\\verification.json"):
+            if not (self.runner.busy and self.runner.method == "verify"):
+                self.invalidate("Verification evidence changed. Run Scan to check it again.")
+            QTimer.singleShot(0, self.rewatch)
+            return
+        if self.runner.busy and self.runner.method in ("save_project", "save_source", "prepare_documentation"):
+            return
+        self.external_change = True
+        self.invalidate("A project file changed outside this editor. Reload from disk before scanning or saving.")
+        QTimer.singleShot(0, self.rewatch)
+
+    def save_project(self):
+        if self.snapshot:
+            self.start("save_project", (self.snapshot["directory"], copy.deepcopy(self.editor.draft)),
+                       {"expected_sha256": self.snapshot["project_sha256"]})
+
+    def scan(self):
+        if self.snapshot and not self.dirty and not self.external_change:
+            self.start("readiness", (self.snapshot["directory"],), {"compiler": self.compiler.text().strip()})
+
+    def verify(self):
+        if self.snapshot and not self.dirty and not self.external_change:
+            self.start("verify", (self.snapshot["directory"],), {"compiler": self.compiler.text().strip()})
+
+    def build(self):
+        if not self.ready or not self.snapshot or self.dirty or self.external_change: return
+        namespace = self.snapshot["document"]["declaration"].get("namespace", "extension")
+        path = PathDialog.choose(self, "Save verified conversion package", mode="save",
+                                 suffix=".pcfplugin",
+                                 initial=str(Path(self.snapshot["directory"]).parent/(namespace+".pcfplugin")))
+        if not path: return
+        if Path(path).exists() and Prompt.ask(self, "Replace package", "Replace the existing package after the evidence checks pass?",
+                                            [("replace", "Replace"), ("cancel", "Cancel")]) != "replace": return
+        self.start("build", (self.snapshot["directory"], path), {"compiler": self.compiler.text().strip()})
+
+    def prepare_documentation(self):
+        if self.snapshot:
+            self.start("prepare_documentation", (self.snapshot["directory"],))
+
+    def edit_source(self, filename):
+        if self.dirty or self.external_change:
+            self.statusBar().showMessage("Save or reload the project before editing a fixture source."); return
+        if self.runner.busy: return
+        dlg = SourceDialog(self.snapshot, filename, self.configuration(), self)
+        # Its explicit one-file save owns the only mutation while the modal
+        # dialog is open; re-arm watchers after loading the resulting snapshot.
+        self.watcher.blockSignals(True)
+        try: dlg.exec()
+        finally: self.watcher.blockSignals(False)
+        if dlg.saved_snapshot: self.load_snapshot(dlg.saved_snapshot)
+        else:
+            # Re-read to detect external changes while the dialog was open.
+            self.start("open_project", (self.snapshot["directory"],))
+
+    def register(self):
+        path = PathDialog.choose(self, "Register a conversion package", suffix=".pcfplugin")
+        if not path: return
+        if Prompt.ask(self, "Register in PyCForge", "Add this package to the selected PyCForge installation's import registry? This is separate from packaging and does not publish a release.\n\n" + path,
+                      [("register", "Register package"), ("cancel", "Cancel")]) == "register":
+            self.start("register", (path,))
+
+    def open_finding(self, path):
+        if self.editor.focus_path(path): self.navigation.setCurrentRow(1)
+        else: self.statusBar().showMessage("Field " + path + ": review the project data or add missing Help fields.")
+
+    def busy_changed(self, busy):
+        self.update_actions()
+
+    def progress(self, event):
+        if self.startup_dialog and event.get("phase") == "discovery":
+            self.startup_dialog.update_progress(event)
+        self.scanner.update_progress(event)
+        self.statusBar().showMessage(event.get("name", event.get("phase", "Working")))
+
+    def cancel(self):
+        self.runner.cancel(); self.ready = False
+        self.statusBar().showMessage("Canceling; waiting for the supervised operation to finish.")
+
+    def finished(self, method, result, revision):
+        self.activity.appendPlainText(method + " — " + result["status"])
+        if result["diagnostics"]: self.activity.appendPlainText(json.dumps(result["diagnostics"], indent=2))
+        data = result["data"]; success = result["status"] == "succeeded"
+        self.statusBar().showMessage(method.replace("_", " ").title() + ": " + result["status"])
+        if method in ("discover", "catalogue") and self.offline_pending and not self.close_pending:
+            self._load_offline()
+            return
+        if method == "discover":
+            self.activity.appendPlainText(json.dumps(data, indent=2))
+            if not self.close_pending:
+                engines = data.get("engines", [])
+                if len(engines) == 1:
+                    self.select_discovered_engine(engines[0]["engine_python"])
+                elif engines and self.startup_dialog:
+                    self.startup_dialog.show_choices(engines, limited=data.get("limited", False))
+                elif self.startup_dialog:
+                    message = (result["diagnostics"][0]["message"] if result["diagnostics"] else
+                               "No working installation was found in the checked locations.")
+                    if data.get("limited"):
+                        message += " The search reached its limit."
+                    self.startup_dialog.failed(message)
+        elif method == "catalogue":
+            connection = data.get("connection", {})
+            self.connection = connection.get("state", "unavailable")
+            self.execution_available = connection.get("execution_available") is True
+            identity = connection.get("engine") or {}
+            self.connection_label.setText("PyCForge " + identity.get("engine_version", "") + " · " + self.connection)
+            self.connection_path.setText(self.engine.text() if self.connection == "connected" else "Cached reference only" if self.connection == "offline" else "No live engine connection")
+            if self.connection == "connected" and not self.execution_available:
+                self.connection_label.setText(self.connection_label.text() + " · authoring unavailable")
+            self.templates, self.methods, self.operations = data.get("templates", []), data.get("methods", []), data.get("array_operations", [])
+            self.workbench, self.help_documents = data.get("workbench"), data.get("documents", [])
+            self.help_engine = identity.get("engine_version", "")
+            imports = f"{len(self.workbench['imports'])} imports · " if self.workbench else ""
+            self.connection_summary.setText((imports + f"{len(self.templates)} starters · {len(self.methods)} API entries"
+                if self.connection == "connected" else "Local projects and cached reference remain available. Connect to use engine operations."))
+            self.locate_button.setVisible(self.connection != "connected")
+            if self.connection == "connected":
+                # Store only a validated live selection, immediately after success.
+                self.settings.setValue("last_engine", self.engine.text())
+                self.settings.setValue("engine", self.engine.text()); self.settings.sync()
+            self.reference.load(self.methods, self.connection, data.get("limits", []))
+            if self.snapshot:
+                self.editor.load(self.editor.draft, methods=self.methods, operations=self.operations, workbench=self.workbench)
+                self.editor.configuration = self.configuration()
+            self.ready = False; self.revision += 1
+            reveal = self.connection == "connected" or self.catalogue_offline
+            if self.startup_dialog and not self.close_pending:
+                if reveal:
+                    self._reveal_workspace()
+                else:
+                    self.startup_dialog.failed(connection.get("problem") or "The installation could not be connected.")
+            if self.after_connect and (reveal or self.startup_dialog is None) and not self.close_pending:
+                path = self.after_connect; self.after_connect = None
+                self.start("open_project", (path,))
+        elif method in ("open_project", "save_project") and success:
+            self.load_snapshot(data)
+            if method == "save_project" and self.close_after_save:
+                self.close_after_save = False; QTimer.singleShot(0, self.close)
+        elif method == "create_project" and success:
+            self.start("open_project", (data["directory"],))
+        elif method == "prepare_documentation" and success:
+            self.start("open_project", (self.snapshot["directory"],))
+        elif method in ("readiness", "verify", "build"):
+            returned_hash = data.get("readiness", data.get("report", data)).get("project_sha256")
+            if returned_hash and self.snapshot and returned_hash != self.snapshot["project_sha256"]:
+                self.external_change = True
+            if revision != self.revision or self.dirty or self.external_change:
+                self.ready = False
+                self.scanner.invalidate("Project or selection changed during work. This result cannot approve the current editor contents.")
+            elif method == "readiness" and "readiness" in data:
+                self.scanner.show_readiness(data["readiness"])
+                self.ready = success and data["readiness"].get("ready") is True
+            elif method == "verify":
+                if "report" in data: self.scanner.show_report(data["report"])
+                if success and not self.close_pending: self.scan()
+                else:
+                    self.scanner.verdict.setText("Verification did not pass")
+                    self.scanner.explanation.setText("Review the fixture results and Activity. Correct the problem, then verify again.")
+                    self.scanner.progress.setRange(0, 1); self.scanner.progress.setValue(0)
+            elif method == "build" and success:
+                self.scanner.verdict.setText("Package created")
+                self.scanner.explanation.setText(data["package"] + "\nRegistration is a separate action in Tools.")
+                self.scanner.progress.setRange(0, 1); self.scanner.progress.setValue(1)
+                self.activity.appendPlainText(json.dumps(data, indent=2))
+                self.scanner.evidence.setPlainText(json.dumps(data, indent=2))
+                self.ready = True
+            else:
+                self.scanner.invalidate("Operation did not complete. Review Activity for the reason.")
+        elif method == "register":
+            self.activity.appendPlainText(json.dumps(data, indent=2)); self.navigation.setCurrentRow(3)
+        if not success and method == "save_project": self.close_after_save = False
+        if method in ("save_project", "prepare_documentation", "verify"): self.rewatch()
+        if not success and result["diagnostics"]:
+            self.statusBar().showMessage(result["diagnostics"][0]["message"])
+        self.update_actions()
+        if self.close_pending and not self.runner.busy:
+            self.close_pending = False; QTimer.singleShot(0, self.close)
+
+    def help(self):
+        dlg = Dialog("PyCForge SDK Help", self)
+        search = QLineEdit(); search.setPlaceholderText("Find in this guide…"); search.setAccessibleName("Find in SDK Help")
+        browser = SafeBrowser(); browser.setStyleSheet("QScrollBar:vertical { width: 28px; }")
+        documents = [{"title":"Getting started", "html":(Path(__file__).parent/"help/index.html").read_text(encoding="utf-8")}]
+        documents.extend(self.help_documents)
+        choice = QComboBox(); choice.setAccessibleName("SDK and import Help topics")
+        for document in documents:
+            choice.addItem(load_pycforge_icon("module" if document.get("id", "").startswith("import:") else "help"), document["title"])
+        choice.currentIndexChanged.connect(lambda index: browser.setHtml(documents[index]["html"]))
+        browser.setHtml(documents[0]["html"])
+        if self.help_documents: choice.setCurrentIndex(1)
+        dlg.body.addWidget(label("Help from PyCForge " + self.help_engine + " · " + self.connection if self.help_documents else
+                                "Getting started — connect to PyCForge for its SDK guide and conversion-import Help.", muted=True))
+        dlg.body.addWidget(choice)
+        def find():
+            if not browser.find(search.text()):
+                cursor = browser.textCursor(); cursor.movePosition(cursor.MoveOperation.Start)
+                browser.setTextCursor(cursor); browser.find(search.text())
+        search.returnPressed.connect(find)
+        dlg.body.addWidget(search); dlg.body.addWidget(browser, 1)
+        dlg.body.addWidget(button("Close", "close", dlg.accept)); dlg.resize(900, 690); dlg.exec()
+
+    def closeEvent(self, event):
+        if self.runner.busy:
+            self.close_pending = True; self.cancel(); event.ignore(); return
+        if self.dirty:
+            choice = Prompt.ask(self, "Unsaved project", "Save your project edits before closing?",
+                                [("save", "Save"), ("discard", "Discard edits"), ("cancel", "Keep editing")])
+            if choice == "cancel": event.ignore(); return
+            if choice == "save":
+                self.close_after_save = True; self.save_project(); event.ignore(); return
+        if self.startup_dialog:
+            dialog, self.startup_dialog = self.startup_dialog, None
+            dialog.accept(); dialog.deleteLater()
+        self.settings.setValue("compiler", self.compiler.text())
+        event.accept()

pycforge_sdk/native.py

@@ -0,0 +1,42 @@
+"""Generic fixture orchestration using the selected engine's build profile."""
+from pathlib import Path
+import platform
+import shutil
+from .process import run
+from .project import digest, read
+from .results import SDKError
+
+
+def compiler_identity(compiler, profile, *, timeout, cancel):
+    if type(profile) is not dict or platform.system() not in profile.get("hosts", []):
+        raise SDKError("SDK_TARGET", "Native verification is not qualified for this host by the selected engine profile.")
+    for key in ("compile_args", "link_args", "compiler_version_args"):
+        if type(profile.get(key)) is not list or any(type(a) is not str or len(a) > 4096 for a in profile[key]):
+            raise SDKError("SDK_CAPABILITY", "Malformed native toolchain profile.")
+    executable = shutil.which(str(compiler))
+    if not executable:
+        raise SDKError("SDK_COMPILER", "C compiler not found: " + str(compiler), status="incomplete")
+    executable = str(Path(executable).resolve())
+    binary = read(executable, 128*1024*1024)
+    result = run([executable, *profile["compiler_version_args"]], timeout=timeout, cancel=cancel)
+    if result.returncode:
+        raise SDKError("SDK_COMPILER", "Cannot identify the selected C compiler.", status="incomplete")
+    return {"executable": executable, "sha256": digest(binary), "version": result.stdout.decode("utf-8", "replace"),
+            "system": platform.system(), "machine": platform.machine(), "profile": profile}
+
+
+def execute_fixture(c_text, expected, compiler, work, *, timeout, cancel):
+    source, executable = Path(work)/"program.c", Path(work)/"program"
+    source.write_text(c_text, encoding="utf-8", newline="\n")
+    profile = compiler["profile"]
+    build = run([compiler["executable"], *profile["compile_args"], str(source), *profile["link_args"], "-o", str(executable)],
+                cwd=work, timeout=timeout, cancel=cancel)
+    result = {"compiler_exit_code": build.returncode, "compiler_stderr": build.stderr.decode("utf-8", "replace")}
+    if build.returncode or not executable.is_file():
+        return {**result, "passed": False, "reason": "Native compilation did not produce an executable."}
+    native = run([executable], cwd=work, timeout=timeout, cancel=cancel)
+    actual = {"stdout": native.stdout.decode("utf-8", "replace"), "stderr": native.stderr.decode("utf-8", "replace"), "exit_code": native.returncode}
+    passed = (native.stdout == expected["stdout"].encode("utf-8") and native.stderr == expected["stderr"].encode("utf-8")
+              and native.returncode == expected["exit_code"])
+    return {**result, "actual": actual, "passed": passed,
+            "reason": "Fixture matched." if passed else "Native result differs from the fixture expectation."}

pycforge_sdk/package_metadata.py

@@ -0,0 +1,21 @@
+"""Report the engine-produced archive's identity without guessing its family."""
+import io
+import json
+import zipfile
+from .results import SDKError
+
+
+def archive_format(content):
+    """Read inert metadata after engine admission; this is not package admission."""
+    try:
+        with zipfile.ZipFile(io.BytesIO(content)) as archive:
+            member=archive.getinfo('manifest.json')
+            if member.file_size > 65536:
+                raise ValueError('Manifest exceeds the reporting budget')
+            data=json.loads(archive.read(member))
+        value=data['format']
+        if type(value) is not str or not value.strip() or len(value)>200:
+            raise ValueError('Missing package format')
+        return value
+    except (ValueError,TypeError,KeyError,zipfile.BadZipFile,RuntimeError) as error:
+        raise SDKError('SDK_ENGINE_ERROR','Cannot read the engine-produced package identity: '+str(error)) from error