cf-bootstrap-core 0.1.8__py3-none-any.whl

cf_bootstrap_core/__init__.py

@@ -0,0 +1,35 @@
+"""Pure bootstrap planning primitives."""
+
+from pathlib import Path
+
+PACKAGE_DISTRIBUTION = "cf-bootstrap-core"
+PYTHON_PACKAGE = "cf_bootstrap_core"
+PACKAGE_VERSION = "0.1.8"
+
+
+def package_root() -> Path:
+    return Path(__file__).resolve().parent
+
+
+def semantics_dir() -> Path:
+    return package_root() / "semantics"
+
+
+def semantic_files() -> tuple[Path, ...]:
+    return (semantics_dir() / "package.trig",)
+
+from .model import (
+    ArtifactSource,
+    BootstrapPlan,
+    BootstrapRequest,
+    LifecycleStage,
+    PlanError,
+    build_plan,
+    canonical_json,
+    validate_lifecycle_stages,
+)
+
+__all__ = [
+    "ArtifactSource", "BootstrapPlan", "BootstrapRequest", "LifecycleStage",
+    "PlanError", "build_plan", "canonical_json", "validate_lifecycle_stages",
+]

cf_bootstrap_core/model.py

@@ -0,0 +1,234 @@
+"""Strict, side-effect-free bootstrap request and plan models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from pathlib import PurePosixPath, PureWindowsPath
+import re
+from typing import Any
+
+REQUEST_SCHEMA = "cf.bootstrap.request.v1"
+PLAN_SCHEMA = "cf.bootstrap.plan.v1"
+REQUEST_SCHEMA_V2 = "cf.bootstrap.request.v2"
+PLAN_SCHEMA_V2 = "cf.bootstrap.plan.v2"
+PROTOCOL = "cf.bootstrap.provider.v1"
+STAGES = (
+    "validate-inputs",
+    "select-artifact-source",
+    "prepare-installation",
+    "install-artifacts",
+    "verify-installation",
+    "handoff-to-service",
+)
+MAX_INSTANCE_ID_LENGTH = 64
+_IDENTIFIER = re.compile(r"[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?\Z")
+_VERSION = re.compile(r"[0-9]+(?:\.[0-9]+){0,2}(?:[-+][A-Za-z0-9.-]+)?\Z")
+_IRI = re.compile(r"[A-Za-z][A-Za-z0-9+.-]*:[^\s]+\Z")
+
+
+class PlanError(ValueError):
+    """A request cannot be represented as a canonical plan."""
+
+
+def _object(value: object, fields: set[str], label: str) -> dict[str, Any]:
+    if not isinstance(value, dict) or any(not isinstance(k, str) for k in value):
+        raise PlanError(f"{label} must be an object")
+    unknown = set(value) - fields
+    if unknown:
+        raise PlanError(f"{label} contains unknown fields: {sorted(unknown)}")
+    return value
+
+
+def _text(value: object, label: str, pattern: re.Pattern[str] | None = None) -> str:
+    if not isinstance(value, str) or not value or value != value.strip() or "\x00" in value:
+        raise PlanError(f"{label} must be a nonempty string")
+    if pattern and not pattern.fullmatch(value):
+        raise PlanError(f"invalid {label}")
+    return value
+
+
+def _canonical_path(value: object, label: str) -> str:
+    text = _text(value, label)
+    if "://" in text:
+        raise PlanError(f"invalid {label}")
+    windows = PureWindowsPath(text)
+    is_windows = bool(windows.drive) or "\\" in text
+    path = windows if is_windows else PurePosixPath(text)
+    if not path.is_absolute() or str(path) == path.anchor:
+        raise PlanError(f"{label} must be an absolute non-root path")
+    # PurePath removes ``.`` lexically; ``..`` is rejected before containment.
+    if ".." in path.parts:
+        raise PlanError(f"{label} cannot contain '..' segments")
+    normalized = str(path).replace("/", "\\") if is_windows else str(path)
+    return normalized
+
+
+def _path_contains(parent: str, child: str) -> bool:
+    wp, wc = PureWindowsPath(parent), PureWindowsPath(child)
+    if wp.drive or wc.drive:
+        if wp.drive.lower() != wc.drive.lower():
+            return False
+        try:
+            wc.relative_to(wp)
+            return True
+        except ValueError:
+            return False
+    try:
+        PurePosixPath(child).relative_to(PurePosixPath(parent))
+        return True
+    except ValueError:
+        return False
+
+
+def _identity(value: object) -> str:
+    result = _text(value, "instance_id", _IDENTIFIER)
+    if len(result) > MAX_INSTANCE_ID_LENGTH:
+        raise PlanError(f"instance_id must be at most {MAX_INSTANCE_ID_LENGTH} ASCII characters")
+    return result
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactSource:
+    mode: str
+    data: dict[str, str]
+
+    @classmethod
+    def from_dict(cls, value: object) -> "ArtifactSource":
+        raw = _object(value, {"mode", "checkout_path", "package", "version"}, "artifact_source")
+        mode = raw.get("mode")
+        if mode == "local-repository":
+            if set(raw) != {"mode", "checkout_path"}:
+                raise PlanError("local-repository source requires only checkout_path")
+            return cls(mode, {"checkout_path": _canonical_path(raw["checkout_path"], "checkout_path")})
+        if mode == "pypi":
+            if set(raw) != {"mode", "package", "version"}:
+                raise PlanError("pypi source requires package and version")
+            package = _text(raw["package"], "package", _IDENTIFIER)
+            version = _text(raw["version"], "version", _VERSION)
+            return cls(mode, {"package": package, "version": version})
+        raise PlanError("source mode must be local-repository or pypi")
+
+    def as_dict(self) -> dict[str, str]:
+        return {"mode": self.mode, **self.data}
+
+
+@dataclass(frozen=True, slots=True)
+class LifecycleStage:
+    name: str
+    ordinal: int
+    handoff: bool = False
+
+    def as_dict(self) -> dict[str, Any]:
+        return {"name": self.name, "ordinal": self.ordinal, "handoff": self.handoff}
+
+
+def validate_lifecycle_stages(value: object) -> tuple[LifecycleStage, ...]:
+    if not isinstance(value, list) or any(not isinstance(item, dict) for item in value):
+        raise PlanError("stages must be a list of objects")
+    names: list[str] = []
+    result: list[LifecycleStage] = []
+    for index, item in enumerate(value):
+        raw = _object(item, {"name", "ordinal", "handoff"}, "stage")
+        name = _text(raw.get("name"), "stage name")
+        ordinal = raw.get("ordinal")
+        handoff = raw.get("handoff")
+        if name not in STAGES or name in names:
+            raise PlanError("stages contain an unknown or duplicate stage")
+        if type(ordinal) is not int or type(handoff) is not bool:
+            raise PlanError("stage ordinal and handoff marker have invalid types")
+        if ordinal != index or handoff is not (name == "handoff-to-service"):
+            raise PlanError("stage ordinal or handoff marker is invalid")
+        names.append(name)
+        result.append(LifecycleStage(name, index, name == "handoff-to-service"))
+    if tuple(names) != STAGES:
+        raise PlanError("stages must contain the canonical ordered lifecycle including handoff-to-service")
+    return tuple(result)
+
+
+@dataclass(frozen=True, slots=True)
+class BootstrapRequest:
+    instance_id: str
+    installation_root: str
+    cogniflow_home: str
+    artifact_source: ArtifactSource
+
+    @classmethod
+    def from_dict(cls, value: object) -> "BootstrapRequest":
+        raw = _object(value, {"schema", "instance_id", "installation_root", "cogniflow_home", "artifact_source"}, "request")
+        if raw.get("schema") != REQUEST_SCHEMA:
+            raise PlanError("unsupported request schema version")
+        home = _canonical_path(raw.get("cogniflow_home"), "cogniflow_home")
+        install = _canonical_path(raw.get("installation_root"), "installation_root")
+        if install == home or _path_contains(home, install):
+            raise PlanError("installation_root must be outside Cogniflow home")
+        return cls(_identity(raw.get("instance_id")), install, home, ArtifactSource.from_dict(raw.get("artifact_source")))
+
+
+@dataclass(frozen=True, slots=True)
+class BootstrapRequestV2(BootstrapRequest):
+    profile: str
+
+    @classmethod
+    def from_dict(cls, value: object) -> "BootstrapRequestV2":
+        raw = _object(value, {"schema", "instance_id", "installation_root", "cogniflow_home", "artifact_source", "profile"}, "request")
+        if raw.get("schema") != REQUEST_SCHEMA_V2:
+            raise PlanError("unsupported request schema version")
+        profile = _text(raw.get("profile"), "profile")
+        if not _IRI.fullmatch(profile):
+            raise PlanError("profile must be an absolute IRI")
+        base = BootstrapRequest.from_dict({key: value for key, value in raw.items() if key != "profile"} | {"schema": REQUEST_SCHEMA})
+        return cls(base.instance_id, base.installation_root, base.cogniflow_home, base.artifact_source, profile)
+
+
+@dataclass(frozen=True, slots=True)
+class BootstrapPlan:
+    instance_id: str
+    installation_root: str
+    cogniflow_home: str
+    artifact_source: ArtifactSource
+    stages: tuple[LifecycleStage, ...]
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "schema": PLAN_SCHEMA,
+            "instance_id": self.instance_id,
+            "installation_root": self.installation_root,
+            "cogniflow_home": self.cogniflow_home,
+            "artifact_source": self.artifact_source.as_dict(),
+            "stages": [stage.as_dict() for stage in self.stages],
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class BootstrapPlanV2(BootstrapPlan):
+    profile: str
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "schema": PLAN_SCHEMA_V2,
+            "instance_id": self.instance_id,
+            "installation_root": self.installation_root,
+            "cogniflow_home": self.cogniflow_home,
+            "artifact_source": self.artifact_source.as_dict(),
+            "profile": self.profile,
+            "stages": [stage.as_dict() for stage in self.stages],
+        }
+
+
+def build_plan(request: BootstrapRequest | dict[str, Any]) -> BootstrapPlan:
+    if isinstance(request, (BootstrapRequest, BootstrapRequestV2)):
+        checked = request
+    elif isinstance(request, dict) and request.get("schema") == REQUEST_SCHEMA_V2:
+        checked = BootstrapRequestV2.from_dict(request)
+    else:
+        checked = BootstrapRequest.from_dict(request)
+    stages = tuple(LifecycleStage(name, index, name == "handoff-to-service") for index, name in enumerate(STAGES))
+    if isinstance(checked, BootstrapRequestV2):
+        return BootstrapPlanV2(checked.instance_id, checked.installation_root, checked.cogniflow_home, checked.artifact_source, stages, checked.profile)
+    return BootstrapPlan(checked.instance_id, checked.installation_root, checked.cogniflow_home, checked.artifact_source, stages)
+
+
+def canonical_json(value: object) -> bytes:
+    payload = value.as_dict() if hasattr(value, "as_dict") else value
+    return (json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + "\n").encode("utf-8")

cf_bootstrap_core/provider.py

@@ -0,0 +1,65 @@
+"""Internal versioned JSON-lines bootstrap-plan provider."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from .model import PROTOCOL, REQUEST_SCHEMA, PlanError, build_plan
+
+_FIELDS = {"jsonrpc", "protocol", "id", "method", "params"}
+_REQUEST_FIELDS = {"schema", "instance_id", "installation_root", "cogniflow_home", "artifact_source", "profile"}
+
+
+def _envelope(request_id: object, **body: object) -> dict[str, object]:
+    return {"jsonrpc": "2.0", "protocol": PROTOCOL, "id": request_id, **body}
+
+
+def handle(payload: object) -> dict[str, object]:
+    request_id: object = None
+    try:
+        if not isinstance(payload, dict):
+            return _envelope(None, error={"code": "INVALID_ENVELOPE", "message": "request envelope must be an object"})
+        unknown = set(payload) - _FIELDS
+        if unknown:
+            return _envelope(payload.get("id"), error={"code": "UNKNOWN_ENVELOPE_FIELD", "message": "request envelope contains unknown fields"})
+        missing = _FIELDS - set(payload)
+        if missing:
+            return _envelope(payload.get("id"), error={"code": "INVALID_ENVELOPE", "message": "request envelope is missing required fields"})
+        request_id = payload["id"]
+        if payload["jsonrpc"] != "2.0" or not isinstance(request_id, (str, int)) or isinstance(request_id, bool):
+            return _envelope(request_id, error={"code": "INVALID_ENVELOPE", "message": "request envelope field types are invalid"})
+        if not isinstance(payload["protocol"], str) or not isinstance(payload["method"], str):
+            return _envelope(request_id, error={"code": "INVALID_ENVELOPE", "message": "request envelope field types are invalid"})
+        if payload["protocol"] != PROTOCOL:
+            return _envelope(request_id, error={"code": "PROTOCOL_VERSION_UNSUPPORTED", "message": "unsupported bootstrap protocol version"})
+        if payload["method"] != "bootstrap/plan":
+            return _envelope(request_id, error={"code": "UNKNOWN_OPERATION", "message": "unknown bootstrap operation"})
+        params = payload["params"]
+        if isinstance(params, dict) and params.get("schema") == REQUEST_SCHEMA and "profile" in params:
+            return _envelope(request_id, error={"code": "SCHEMA_INVALID", "message": "v1 request cannot contain profile"})
+        if isinstance(params, dict) and (set(params) - _REQUEST_FIELDS):
+            return _envelope(request_id, error={"code": "UNKNOWN_REQUEST_FIELD", "message": "request body contains unknown fields"})
+        return _envelope(request_id, result=build_plan(params).as_dict())
+    except PlanError as error:
+        return _envelope(request_id, error={"code": "SCHEMA_INVALID", "message": str(error)})
+    except Exception:
+        return _envelope(request_id, error={"code": "INTERNAL_ERROR", "message": "bootstrap provider failed unexpectedly"})
+
+
+def main() -> int:
+    # Exit code 0 is stable for every processed line, including structured errors.
+    for line in sys.stdin:
+        try:
+            payload = json.loads(line)
+        except json.JSONDecodeError:
+            response = _envelope(None, error={"code": "MALFORMED_JSON", "message": "request must be valid JSON"})
+        else:
+            response = handle(payload)
+        sys.stdout.write(json.dumps(response, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + "\n")
+        sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cf_bootstrap_core/semantics/package.trig

@@ -0,0 +1,13 @@
+@prefix cfpkg: <https://cogniflow.odea-project.org/cf#> .
+@prefix contribution: <urn:cf:contribution:> .
+@prefix pkg: <urn:cf:pkg:> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+
+pkg:cf_bootstrap_core {
+  pkg:cf_bootstrap_core a cfpkg:CfPackage ;
+    cfpkg:hasPackageManifest [ a cfpkg:PackageManifest ; cfpkg:hasDistributionName [ a cfpkg:DistributionName ; rdf:value "cf-bootstrap-core" ] ; cfpkg:hasPythonPackageName [ a cfpkg:PythonPackageName ; rdf:value "cf_bootstrap_core" ] ; cfpkg:hasPackageVersion [ a cfpkg:PackageVersion ; rdf:value "0.1.8" ] ; cfpkg:hasImplementationLanguage [ a cfpkg:ImplementationLanguage ; rdf:value "Python" ] ] ;
+    cfpkg:hasPackageRole [ a cfpkg:PackageRole ; rdf:value cfpkg:SpecificationPackageRole ] ;
+    cfpkg:hasPackageContribution contribution:adopted_package ;
+    skos:prefLabel "cf-bootstrap-core" ; skos:definition "An adopted Cogniflow package conforming to the basic package template." ; skos:scopeNote "Package semantics were restored through the package conformance repair service." ; skos:example "The installed package publishes its package.trig semantic source." .
+}

cf_bootstrap_core-0.1.8.dist-info/METADATA

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: cf-bootstrap-core
+Version: 0.1.8
+Summary: Pure canonical Cogniflow bootstrap lifecycle and instance-plan model.
+Author: Cogniflow Maintainers
+License: GPL-3
+Requires-Python: >=3.11
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# cf-bootstrap-core
+
+`cf_bootstrap_core` is a pure, standard-library-only model for the deterministic bootstrap plan. It validates versioned requests and returns a canonical plan without creating files, directories, locks, environments, manifests, or runtime state.
+
+## Boundary
+
+A bootstrap plan is intended lifecycle data before side effects: identity, caller-supplied Cogniflow home context, external installation root, artifact source, and the ordered stages `validate-inputs`, `select-artifact-source`, `prepare-installation`, `install-artifacts`, `verify-installation`, and `handoff-to-service`. The handoff is ordinally explicit and is the end of imperative bootstrap responsibility. Stage names describe future work only; this package does not perform it.
+
+A runtime manifest is operational state owned solely by `cf_runtime`. This package never creates or interprets one, writes beneath `.cogniflow`, duplicates `CogniflowHome` or `RuntimePaths`, or derives the internal `.cogniflow` layout. The installation root is an explicit external location and is not created during planning. Paths are validated lexically without filesystem access; `.` segments are normalized by `PurePath`, while `..` segments are rejected before component-aware containment, so nonexistent targets remain valid and traversal cannot bypass containment.
+
+## Identity and protocol
+
+`instance_id` is caller-supplied ASCII text of 1-64 characters matching `[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?`. It is case-sensitive, may contain internal dots, hyphens, and underscores, and has no path or environment meaning. No random, timestamp, process, host, working-directory, or checkout-derived identity is generated.
+
+The package-local `cf-bootstrap-core-provider` accepts `cf.bootstrap.provider.v1` JSON-RPC-shaped JSON-lines requests with method `bootstrap/plan`. Each input line produces one response line. Exit code is `0` for empty input, successful requests, schema/protocol errors, malformed JSON, and unexpected internal errors after the lines are processed. stdout contains only compact canonical JSON; diagnostics are not written to stdout. Error codes are `MALFORMED_JSON`, `INVALID_ENVELOPE`, `PROTOCOL_VERSION_UNSUPPORTED`, `UNKNOWN_OPERATION`, `SCHEMA_INVALID`, and `INTERNAL_ERROR`.
+
+`UNKNOWN_ENVELOPE_FIELD` means an envelope contains an unrecognized field; `INVALID_ENVELOPE` means its object shape, required fields, or field types are invalid; `UNKNOWN_REQUEST_FIELD` means the plan request body contains an unrecognized field; `SCHEMA_INVALID` means the request values violate the versioned model. `MALFORMED_JSON`, `PROTOCOL_VERSION_UNSUPPORTED`, `UNKNOWN_OPERATION`, and `INTERNAL_ERROR` retain their literal meanings.
+
+Canonical JSON is UTF-8 JSON with sorted object keys, compact separators, deterministic list order, no volatile values, and exactly one LF terminator. Only `local-repository` and `pypi` source modes are accepted. No package is built, resolved, downloaded, installed, or started.
+
+The public `cogniflow` launcher discovers this provider through the
+`cogniflow.bootstrap_providers.v1` distribution entry-point group and invokes
+the matching `cf-bootstrap-core-provider` console script as an external
+process. The launcher does not import this package. Artifact resolver and
+frontend discovery groups are reserved as `cogniflow.artifact_resolvers.v1`
+and `cogniflow.frontends.v1`; they are not implemented here.

cf_bootstrap_core-0.1.8.dist-info/RECORD

@@ -0,0 +1,8 @@
+cf_bootstrap_core/__init__.py,sha256=klFSZWs6XvEgZyrlvYvO9yudMT3ftPYhUl9thpJBOeE,802
+cf_bootstrap_core/model.py,sha256=N0Y_g-yUzNKFDJOBIfHygE0ekKw4yEtstDMZOQs9CNE,9810
+cf_bootstrap_core/provider.py,sha256=6e0vYGISRbd8nwv9L2Rescdgbaypo3Z1aMm_z3J5iyE,3517
+cf_bootstrap_core/semantics/package.trig,sha256=8nbEh50HlUAC2fgG53YaGe0wkNf95H1plBqeIbhHD7E,1208
+cf_bootstrap_core-0.1.8.dist-info/METADATA,sha256=aErPfztwF2SRf9GFoLQGiPCBr36Vc7BKaemjQCBcBXA,3743
+cf_bootstrap_core-0.1.8.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+cf_bootstrap_core-0.1.8.dist-info/entry_points.txt,sha256=Y8GzfgXclRNi9yeIu8hWhdg6nTQgwJ6ugSKB5Rwqy0c,259
+cf_bootstrap_core-0.1.8.dist-info/RECORD,,

cf_bootstrap_core-0.1.8.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cf_bootstrap_core-0.1.8.dist-info/entry_points.txt

@@ -0,0 +1,8 @@
+[console_scripts]
+cf-bootstrap-core-provider = cf_bootstrap_core.provider:main
+
+[cogniflow.bootstrap_providers.v1]
+cf-bootstrap-core-provider = cf_bootstrap_core.provider:main
+
+[cogniflow.semantic_sources]
+cf-bootstrap-core = cf_bootstrap_core:semantic_files