pycforge-sdk 0.6.3__py3-none-any.whl

pycforge_sdk/process.py

@@ -0,0 +1,58 @@
+"""Bounded explicit subprocess work; no shell and no Qt event loop."""
+from __future__ import annotations
+from dataclasses import dataclass
+import os
+import signal
+import subprocess
+import tempfile
+import threading
+import time
+from .results import SDKError
+
+
+@dataclass(frozen=True)
+class ProcessResult:
+    returncode: int
+    stdout: bytes
+    stderr: bytes
+
+
+def run(argv, *, input_bytes=b"", cwd=None, timeout=30.0, cancel=None, max_output=8*1024*1024):
+    """Run an explicitly requested tool, bounding time and captured output.
+
+    POSIX work uses a process group so timeout/cancellation also stops child
+    processes. This is supervision, not a security sandbox. Windows terminates
+    the direct process; native fixture qualification is Linux-only in 0.1.
+    """
+    if timeout <= 0 or timeout > 300:
+        raise SDKError("SDK_ARGUMENT", "Timeout must be greater than zero and at most 300 seconds.")
+    if cancel is not None and cancel.is_set():
+        raise SDKError("SDK_CANCELED", "Operation canceled before execution.", status="canceled")
+    tick = threading.Event()
+    with tempfile.TemporaryFile() as source, tempfile.TemporaryFile() as out, tempfile.TemporaryFile() as err:
+        source.write(input_bytes); source.seek(0)
+        process = subprocess.Popen([str(a) for a in argv], stdin=source, stdout=out, stderr=err,
+                                   cwd=cwd, start_new_session=(os.name == "posix"))
+        deadline = time.monotonic() + timeout
+        try:
+            while process.poll() is None:
+                if cancel is not None and cancel.is_set():
+                    raise SDKError("SDK_CANCELED", "Operation canceled.", status="canceled")
+                if time.monotonic() >= deadline:
+                    raise SDKError("SDK_TIMEOUT", "Tool execution exceeded its time limit.", status="incomplete")
+                if max(os.fstat(out.fileno()).st_size, os.fstat(err.fileno()).st_size) > max_output:
+                    raise SDKError("SDK_OUTPUT_LIMIT", "Tool output exceeded the configured budget.", status="incomplete")
+                tick.wait(0.02)
+            out.seek(0); err.seek(0)
+            stdout, stderr = out.read(max_output+1), err.read(max_output+1)
+            if max(len(stdout), len(stderr)) > max_output:
+                raise SDKError("SDK_OUTPUT_LIMIT", "Tool output exceeded the configured budget.", status="incomplete")
+            return ProcessResult(process.returncode, stdout, stderr)
+        finally:
+            if os.name == "posix":
+                try: os.killpg(process.pid, signal.SIGKILL)
+                except ProcessLookupError: pass
+            elif process.poll() is None:
+                process.kill()
+            process.wait()
+

pycforge_sdk/project.py

@@ -0,0 +1,143 @@
+"""Data-only extension projects and immutable file snapshots."""
+from __future__ import annotations
+from dataclasses import dataclass
+import hashlib
+import json
+import os
+from pathlib import Path, PurePosixPath
+import re
+import tempfile
+from .results import SDKError
+
+PROJECT_SCHEMA = "pycforge-sdk.project/0.1"
+DOCUMENTED_PROJECT_SCHEMA = "pycforge-sdk.project/0.2"
+REPORT_SCHEMA = "pycforge-sdk.verification/0.2"
+MAX_SOURCE = 256 * 1024
+MAX_PROJECT = 4 * 1024 * 1024
+
+
+def canonical(value):
+    return (json.dumps(value, sort_keys=True, indent=2, ensure_ascii=True, allow_nan=False) + "\n").encode("utf-8")
+
+
+def digest(value):
+    return hashlib.sha256(value).hexdigest()
+
+
+def parse(data):
+    def unique(items):
+        result = {}
+        for key, value in items:
+            if key in result:
+                raise SDKError("SDK_PROJECT", "Duplicate JSON key: " + key)
+            result[key] = value
+        return result
+    try:
+        return json.loads(data.decode("utf-8") if isinstance(data, bytes) else data, object_pairs_hook=unique,
+                          parse_constant=lambda value: (_ for _ in ()).throw(ValueError(value)))
+    except (ValueError, UnicodeError, RecursionError) as exc:
+        raise SDKError("SDK_PROJECT", "Invalid UTF-8 JSON document.") from exc
+
+
+def read(path, limit):
+    path = Path(path)
+    if path.is_symlink() or not path.is_file():
+        raise SDKError("SDK_PROJECT", "Expected a regular non-symlink file: " + str(path))
+    with path.open("rb") as stream:
+        data = stream.read(limit+1)
+    if len(data) > limit:
+        raise SDKError("SDK_PROJECT", "File exceeds the size budget: " + str(path))
+    return data
+
+
+def atomic_write(path, data):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.is_symlink():
+        raise SDKError("SDK_PROJECT", "Refusing a symbolic-link destination.")
+    fd, name = tempfile.mkstemp(prefix=".sdk-write-", dir=path.parent)
+    try:
+        with os.fdopen(fd, "wb") as stream:
+            stream.write(data); stream.flush(); os.fsync(stream.fileno())
+        os.replace(name, path)
+    finally:
+        if os.path.exists(name): os.unlink(name)
+
+
+def require(condition, message):
+    if not condition:
+        raise SDKError("SDK_PROJECT", message)
+
+
+@dataclass(frozen=True)
+class Project:
+    root: Path
+    document_bytes: bytes
+    sources: tuple[tuple[str, bytes], ...]
+    sha256: str
+
+    @property
+    def document(self):
+        return parse(self.document_bytes)
+
+    @property
+    def report_path(self):
+        return self.root / ".pycforge-sdk" / "verification.json"
+
+    @classmethod
+    def load(cls, root, *, document_bytes=None):
+        root = Path(root).absolute()
+        require(not root.is_symlink(), "Project root cannot be a symlink.")
+        root = root.resolve()
+        data = read(root / "project.json", MAX_PROJECT) if document_bytes is None else document_bytes
+        document = parse(data)
+        require(type(document) is dict, "Project must be an object.")
+        schema = document.get("schema")
+        require(schema in (PROJECT_SCHEMA, DOCUMENTED_PROJECT_SCHEMA), "Unsupported SDK project schema.")
+        fields = {"schema","declaration","metadata","cases"}
+        if schema == DOCUMENTED_PROJECT_SCHEMA: fields.add("documentation")
+        require(set(document) == fields, "Unknown or missing project fields.")
+        metadata = document["metadata"]
+        require(type(metadata) is dict and set(metadata) == {"author","created","description","license"}
+                and all(type(v) is str and 0 < len(v) <= 4096 for v in metadata.values()), "Invalid author metadata.")
+        cases = document["cases"]
+        require(type(cases) is list and 1 <= len(cases) <= 64, "Projects require 1..64 explicit test cases.")
+        names, sources, total = set(), {}, len(data)
+        for case in cases:
+            require(type(case) is dict and set(case) == {"name","file","expect"}, "Invalid test case fields.")
+            name = case["name"]
+            require(type(name) is str and re.fullmatch(r"[a-zA-Z0-9_-]{1,64}", name) and name not in names, "Test names must be unique simple identifiers.")
+            names.add(name)
+            filename = case["file"]
+            require(filename != "project.json", "A fixture cannot overwrite the project document.")
+            require(type(filename) is str and len(filename) <= 240 and "\\" not in filename and ":" not in filename, "Invalid source path.")
+            parts = PurePosixPath(filename).parts
+            require(parts and not PurePosixPath(filename).is_absolute() and all(p not in (".","..", ".pycforge-sdk") for p in parts), "Source path must stay inside the project.")
+            candidate = root
+            for part in parts:
+                candidate = candidate / part
+                require(not candidate.is_symlink(), "Source paths cannot contain symlinks.")
+            require(candidate.resolve().is_relative_to(root), "Source path escapes the project.")
+            if filename not in sources:
+                content = read(candidate, MAX_SOURCE)
+                try: content.decode("utf-8")
+                except UnicodeError as exc: raise SDKError("SDK_PROJECT", "Sources must be UTF-8.") from exc
+                sources[filename] = content; total += len(content)
+            expected = case["expect"]
+            require(type(expected) is dict, "Test expectations must be an object.")
+            if expected.get("kind") == "run":
+                require(set(expected) == {"kind","stdout","stderr","exit_code"}, "Invalid run expectation.")
+                require(all(type(expected[k]) is str and len(expected[k]) <= MAX_SOURCE for k in ("stdout","stderr")), "Expected output must be bounded text.")
+                require(type(expected["exit_code"]) is int and 0 <= expected["exit_code"] <= 255, "Expected exit status must be 0..255.")
+            elif expected.get("kind") == "reject":
+                require(set(expected) == {"kind","code"} and type(expected["code"]) is str and bool(re.fullmatch(r"PYC[0-9]{4}", expected["code"])), "Rejected cases require an explicit engine diagnostic code.")
+            else:
+                raise SDKError("SDK_PROJECT", "Unsupported case kind; use run or reject.")
+        require(total <= MAX_PROJECT, "Project snapshot exceeds the total budget.")
+        require(not (root/".pycforge-sdk").is_symlink(), "SDK work folder cannot be a symlink.")
+        identity = {"project.json": digest(data), **{name: digest(value) for name,value in sorted(sources.items())}}
+        return cls(root, data, tuple(sorted(sources.items())), digest(canonical(identity)))
+
+    def ensure_current(self):
+        if Project.load(self.root).sha256 != self.sha256:
+            raise SDKError("SDK_STALE_PROJECT", "Project changed during the operation; inspect and verify the new snapshot.")

pycforge_sdk/readiness.py

@@ -0,0 +1,106 @@
+"""Explainable packaging gate shared by Python, console and desktop clients."""
+from .project import Project, REPORT_SCHEMA, parse, read
+from .results import Outcome, SDKError, SDK_VERSION
+
+SCOPE = ("Readiness covers the saved project and its explicit fixtures on the recorded "
+         "engine, compiler and host. It is not proof of every input or a signed certificate.")
+
+
+def evaluate(sdk, directory, *, compiler=None):
+    result = {"schema": "pycforge-sdk.readiness/0.1", "state": "unavailable",
+              "ready": False, "project_sha256": None, "engine": None,
+              "checks": [], "issues": [], "scope": SCOPE, "evidence_sha256": None}
+    stage = "project"
+
+    def passed(identifier, label):
+        result["checks"].append({"id": identifier, "label": label, "status": "passed"})
+        sdk._notify("check", name=label)
+
+    try:
+        sdk._notify("check", name="Read saved project")
+        project = Project.load(directory)
+        result["project_sha256"] = project.sha256
+        passed("project", "Saved project and fixture files")
+        stage = "engine"
+        sdk._connection.ensure_current()
+        result["engine"] = dict(sdk._connection.snapshot.identity)
+        passed("engine", "Selected engine is available and current")
+        stage = "authoring"
+        scan = sdk._scan(project)
+        result["scan"] = scan
+        passed("declaration", "Declaration and supported contracts")
+        if scan["issues"]:
+            result.update(state="needs-authoring", issues=scan["issues"])
+            result["checks"].append({"id": "documentation", "label": "Help and example links", "status": "incomplete"})
+            return Outcome("rejected", {"readiness": result}, tuple(result["issues"]))
+        passed("documentation", "Offline Help and example links")
+        stage = "fixtures"
+        guide = sdk._connection.reference()
+        policy = guide.get("verification", {})
+        kinds = {c["expect"]["kind"] for c in project.document["cases"]}
+        if policy.get("policy") not in ("scalar-fixtures/0.1", "scalar-fixtures/0.2"):
+            raise SDKError("SDK_CAPABILITY", "Unsupported engine fixture policy.")
+        if not set(policy.get("required_case_kinds", [])) <= kinds:
+            raise SDKError("SDK_INCOMPLETE_SUITE", "Include both native run fixtures and expected conversion rejections.")
+        passed("fixtures", "Required fixture kinds are present")
+        stage = "evidence"
+        report, inspection, _ = sdk._validated_evidence(project, selected_compiler=compiler)
+        passed("native", "Every explicit native and rejection fixture passed")
+        passed("coverage", "Every export and linked Help example is covered")
+        passed("freshness", "Project, SDK, engine, compiler and host match evidence")
+        stage = "package"
+        sdk._package_content(project, report)
+        sdk._connection.ensure_current()
+        passed("package", "Engine validates package metadata and archive")
+        result.update(state="ready-to-package", ready=True,
+                      evidence_sha256=report["evidence_sha256"], compiler=report["compiler"],
+                      coverage=report["coverage"], cases=report["cases"])
+        return Outcome("succeeded", {"readiness": result})
+    except (SDKError, OSError) as exc:
+        code = getattr(exc, "code", "SDK_IO")
+        canceled = getattr(exc, "status", "") == "canceled"
+        missing = code == "SDK_VERIFICATION_REQUIRED"
+        state = ("canceled" if canceled else "ready-to-verify" if missing else
+                 "needs-verification" if stage == "evidence" else
+                 "needs-authoring" if stage in ("project", "authoring", "fixtures", "package") else "unavailable")
+        issue = {"code": code, "message": str(exc), "path": "/metadata" if stage == "package" else "",
+                 "remedy": "Run Verify fixtures, then scan again." if stage == "evidence" else
+                 "Connect to a compatible engine." if stage == "engine" else "Correct the project, save and scan again."}
+        result.update(state=state, issues=[issue])
+        result["checks"].append({"id": stage, "label": str(exc), "status": "not-run" if missing else "incomplete"})
+        if stage == "evidence" and not canceled:
+            last_attempt(result, project)
+        return Outcome("canceled" if canceled else "incomplete" if state in
+                       ("unavailable", "ready-to-verify", "needs-verification") else "rejected",
+                       {"readiness": result}, tuple(result["issues"]))
+
+
+def last_attempt(result, project):
+    """Explain a failed attempt for these exact inputs; never promote it."""
+    try:
+        report = parse(read(project.report_path, 8*1024*1024))
+    except (SDKError, OSError):
+        return
+    if (type(report) is not dict or report.get("schema") != REPORT_SCHEMA
+            or report.get("project_sha256") != project.sha256
+            or report.get("sdk_version") != SDK_VERSION or report.get("engine") != result["engine"]
+            or report.get("status") not in ("failed", "incomplete", "canceled")
+            or type(report.get("cases")) is not list):
+        return
+    result["last_attempt_status"] = report["status"]
+    result["cases"] = []
+    expected = {case["name"]: (index, case) for index, case in enumerate(project.document["cases"])}
+    for case in report["cases"]:
+        if type(case) is not dict or type(case.get("name")) is not str: continue
+        entry = expected.get(case["name"])
+        if entry is None or case.get("file") != entry[1]["file"] or case.get("expected") != entry[1]["expect"]: continue
+        result["cases"].append(case)
+        if case.get("passed") is not True:
+            result["issues"].append({"code": "SDK_FIXTURE_FAILED", "path": f"/cases/{entry[0]}",
+                "message": "Fixture '" + case["name"] + "' did not pass: " + str(case.get("reason", "review its diagnostics")),
+                "remedy": "Review expected and actual results in Fixture results, then correct the declaration, fixture or expectation and verify again."})
+    coverage = report.get("coverage")
+    if isinstance(coverage, dict) and coverage.get("missing"):
+        result["issues"].append({"code": "SDK_INCOMPLETE_COVERAGE", "path": "/declaration/functions",
+            "message": "Exports missing native source-call coverage: " + str(coverage["missing"]),
+            "remedy": "Add calls to these operations in passing native fixtures."})

pycforge_sdk/results.py

@@ -0,0 +1,45 @@
+"""Versioned, UI-independent SDK results and errors."""
+from dataclasses import dataclass, field
+from functools import wraps
+
+SDK_VERSION = "0.6.3"
+RESULT_SCHEMA = "pycforge-sdk.result/0.1"
+
+
+class SDKError(Exception):
+    def __init__(self, code, message, *, status="rejected", details=None):
+        super().__init__(message)
+        self.code, self.status, self.details = code, status, details or {}
+
+
+@dataclass(frozen=True)
+class Outcome:
+    status: str
+    data: dict = field(default_factory=dict)
+    diagnostics: tuple = ()
+
+    @property
+    def ok(self):
+        return self.status == "succeeded"
+
+    def to_dict(self):
+        return {"schema": RESULT_SCHEMA, "sdk_version": SDK_VERSION, "status": self.status,
+                "data": self.data, "diagnostics": list(self.diagnostics)}
+
+
+def operation(function):
+    """Keep failure categories identical for Python, console and GUI."""
+    @wraps(function)
+    def invoke(*args, **kwargs):
+        try:
+            result = function(*args, **kwargs)
+            return result if isinstance(result, Outcome) else Outcome("succeeded", result)
+        except SDKError as exc:
+            return Outcome(exc.status, {}, ({"code": exc.code, "message": str(exc), "details": exc.details},))
+        except OSError as exc:
+            return Outcome("incomplete", {}, ({"code": "SDK_IO", "message": str(exc)},))
+        except Exception as exc:
+            return Outcome("internal_failure", {}, ({"code": "SDK_INTERNAL", "message": str(exc),
+                "details": {"exception_type": type(exc).__name__}},))
+    return invoke
+