cox-protocol-package 1.0.2 → 1.2.0

package/cox_protocol/compiler.py

@@ -0,0 +1,273 @@
+"""Build into an isolated staging directory, then publish only owned artifacts."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Any, Sequence
+
+from . import __version__
+from .cox_lib import (
+    CoxError,
+    fail,
+    normalize_compile_targets,
+    validate_project,
+    write_json,
+)
+
+MARKER = ".cox-build.json"
+
+
+def digest(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def build_location(summary, out_dir: Path) -> Path:
+    candidate = out_dir if out_dir.is_absolute() else summary.project_root / out_dir
+    if candidate.is_symlink():
+        fail("OUTPUT_SYMLINK", "Output directory must not be a symlink", str(candidate))
+    # Canonicalize parents (including macOS /var and /tmp aliases) before overlap
+    # checks. The chosen root and every managed path inside it reject symlinks.
+    root = candidate.resolve()
+    if summary.project_root.is_relative_to(root):
+        fail(
+            "OUTPUT_OVERLAP",
+            "Output cannot be the project root or an ancestor",
+            str(root),
+        )
+    for source in [summary.manifest_path, *summary.referenced_paths]:
+        if source.is_relative_to(root) or (
+            source.is_dir() and root.is_relative_to(source)
+        ):
+            fail("OUTPUT_OVERLAP", "Output overlaps a manifest input", str(source))
+    if root.exists() and not root.is_dir():
+        fail("OUTPUT_TYPE", "Output must be a directory", str(root))
+    return root
+
+
+def artifact_paths(stage: Path) -> list[Path]:
+    return sorted(p for p in stage.rglob("*") if p.is_file())
+
+
+def load_ownership(build_root: Path) -> dict[str, str]:
+    marker = build_root / MARKER
+    if marker.is_symlink():
+        fail("OUTPUT_SYMLINK", "Build marker must not be a symlink", str(marker))
+    if not marker.exists():
+        return {}
+    try:
+        data = json.loads(marker.read_text(encoding="utf-8"))
+        if data["format"] != "cox-build/1" or not isinstance(data["files"], dict):
+            raise ValueError("Unsupported build marker")
+        for raw, checksum in data["files"].items():
+            if (
+                not raw
+                or any(part in ("", ".", "..") for part in raw.split("/"))
+                or any(c in raw for c in '\\<>:"|?*')
+                or any(ord(c) < 32 for c in raw)
+                or raw == MARKER
+            ):
+                raise ValueError("Invalid owned output path")
+            if not isinstance(checksum, str) or not re.fullmatch(
+                "[0-9a-f]{64}", checksum
+            ):
+                raise ValueError("Invalid checksum in build marker")
+        return data["files"]
+    except (OSError, ValueError, KeyError, TypeError) as exc:
+        fail("OUTPUT_MARKER", f"Invalid build ownership marker: {exc}", str(marker))
+
+
+def publish(stage: Path, build_root: Path) -> None:
+    outputs = {p.relative_to(stage).as_posix(): p for p in artifact_paths(stage)}
+    owned = load_ownership(build_root)
+    # A compiler owns only the exact generated bytes recorded on the previous run.
+    for rel in sorted(set(outputs) | set(owned)):
+        path = build_root / rel
+        for parent in (path, *path.parents):
+            if parent == build_root:
+                break
+            if parent.is_symlink():
+                fail(
+                    "OUTPUT_SYMLINK",
+                    "Refusing to replace an output through a symlink",
+                    str(parent),
+                )
+            if parent != path and parent.exists() and not parent.is_dir():
+                fail("OUTPUT_COLLISION", "Output parent is a file", str(parent))
+        if path.exists():
+            if not path.is_file() or rel not in owned:
+                fail(
+                    "OUTPUT_COLLISION",
+                    "Existing file is not owned by COX; use a fresh --out directory",
+                    str(path),
+                )
+            if digest(path) != owned[rel]:
+                fail(
+                    "OUTPUT_MODIFIED",
+                    "Generated file has local edits; preserve them and use a fresh --out directory",
+                    str(path),
+                )
+    build_root.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(
+        prefix=".cox-backup-", dir=build_root.parent
+    ) as backup_name:
+        backup = Path(backup_name)
+        previous = [rel for rel in owned if (build_root / rel).is_file()]
+        for rel in previous:
+            dest = backup / rel
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(build_root / rel, dest)
+        marker = build_root / MARKER
+        old_marker = marker.read_bytes() if marker.exists() else None
+        installed = []
+        try:
+            hashes = {rel: digest(path) for rel, path in outputs.items()}
+            for rel, source in outputs.items():
+                dest = build_root / rel
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                os.replace(source, dest)
+                installed.append(rel)
+            for rel in set(owned) - set(outputs):
+                (build_root / rel).unlink(missing_ok=True)
+            temporary_marker = backup / "new-marker.json"
+            write_json(temporary_marker, {"format": "cox-build/1", "files": hashes})
+            os.replace(temporary_marker, marker)
+        except OSError as exc:
+            for rel in installed:
+                (build_root / rel).unlink(missing_ok=True)
+            for rel in previous:
+                dest = build_root / rel
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(backup / rel, dest)
+            if old_marker is None:
+                marker.unlink(missing_ok=True)
+            else:
+                marker.write_bytes(old_marker)
+            raise CoxError(
+                f"Could not publish build; previous generated files restored: {exc}"
+            ) from exc
+
+
+def compile_project(
+    target: Path,
+    out_dir: Path,
+    targets: Sequence[str] | None = None,
+    strict: bool = False,
+) -> dict[str, Any]:
+    summary = validate_project(target)
+    if strict and summary.warnings:
+        fail("WARNINGS_AS_ERRORS", "\n".join(summary.warnings))
+    selected = normalize_compile_targets(targets)
+    build_root = build_location(summary, out_dir)
+    try:
+        # Stage on the destination filesystem so publication also works on another volume.
+        build_root.parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.TemporaryDirectory(
+            prefix=".cox-stage-", dir=build_root.parent
+        ) as temporary:
+            stage = Path(temporary)
+            results = {}
+            if "json" in selected:
+                for source, payload in sorted(summary.documents.items()):
+                    if source != summary.manifest_path:
+                        write_json(
+                            (
+                                stage
+                                / "normalized"
+                                / source.relative_to(summary.project_root)
+                            ).with_suffix(".json"),
+                            payload,
+                        )
+                (stage / "normalized").mkdir(exist_ok=True)
+                results["json"] = {
+                    "output_root": stage / "normalized",
+                    "document_count": len(summary.documents) - 1,
+                }
+            if "react" in selected:
+                from .react_target import emit_react_stubs
+
+                results["react"] = emit_react_stubs(summary, stage)
+            if "package" in selected:
+                from .package_target import package_filename
+
+                name = package_filename(summary)
+                results["package"] = {
+                    "output_root": stage / "package",
+                    "archive": stage / "package" / name,
+                    "manifest": stage
+                    / "package"
+                    / (Path(name).stem + ".manifest.json"),
+                }
+            manifest_payload = {
+                "compiledWith": f"cox {__version__}",
+                "mimeType": "application/vnd.cox+yaml",
+                "targets": selected,
+                "manifest": summary.documents[summary.manifest_path],
+                "resolvedFiles": {
+                    key: value
+                    for key, value in summary.build_index.items()
+                    if key not in ("referenced_paths", "cox_documents")
+                },
+                "targetOutputs": {
+                    name: {
+                        key: value.relative_to(stage).as_posix()
+                        if isinstance(value, Path)
+                        else value
+                        for key, value in result.items()
+                    }
+                    for name, result in results.items()
+                },
+                "warnings": summary.warnings,
+            }
+            write_json(stage / "manifest.compiled.json", manifest_payload)
+            report = {
+                "ok": True,
+                "formatVersion": "1.0",
+                "compilerVersion": __version__,
+                "project": summary.documents[summary.manifest_path]["Slug"],
+                "validatedDocuments": len(summary.documents),
+                "referencedPathsChecked": len(summary.referenced_paths),
+                "targets": selected,
+                "warnings": summary.warnings,
+            }
+            write_json(stage / "reports" / "verification_report.json", report)
+            text = (
+                "COX verification report\n"
+                + "\n".join(
+                    f"{key}: {json.dumps(value, ensure_ascii=True)}"
+                    for key, value in report.items()
+                )
+                + "\n"
+            )
+            (stage / "reports" / "verification_report.txt").write_text(
+                text, encoding="utf-8"
+            )
+            if "package" in selected:
+                from .package_target import emit_package_archive
+
+                results["package"] = emit_package_archive(summary, stage, results)
+            final_results = {
+                name: {
+                    key: build_root / value.relative_to(stage)
+                    if isinstance(value, Path)
+                    else value
+                    for key, value in result.items()
+                }
+                for name, result in results.items()
+            }
+            publish(stage, build_root)
+        return {
+            "build_root": build_root,
+            "targets": selected,
+            "target_results": final_results,
+            "compiled_manifest": build_root / "manifest.compiled.json",
+            "report": build_root / "reports" / "verification_report.txt",
+            "warnings": summary.warnings,
+        }
+    except OSError as exc:
+        raise CoxError(f"Build I/O failed: {exc}") from exc

package/cox_protocol/cox_cli.py

@@ -0,0 +1,146 @@
+"""Human-readable and machine-readable interfaces to the same COX contract."""
+
+from __future__ import annotations
+import json
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from . import __version__
+from .cox_lib import CoxError, compile_project, validate_project, fail
+from .package_target import verify_archive
+from .scaffold import init_project
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="Create, validate, compile and verify COX design contracts.",
+)
+console = Console()
+
+
+def serializable(value):
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, dict):
+        return {key: serializable(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [serializable(item) for item in value]
+    return value
+
+
+def output(payload, machine: bool, title: str):
+    if machine:
+        typer.echo(json.dumps(serializable(payload), indent=2))
+    else:
+        console.print(title, style="bold green", markup=False)
+        for key, value in payload.items():
+            if key not in ("ok", "target_results"):
+                console.print(f"{key}: {serializable(value)}", markup=False)
+
+
+def failure(exc: Exception, machine: bool):
+    if not isinstance(exc, CoxError):
+        exc = CoxError(f"I/O operation failed: {exc}")
+    if machine:
+        typer.echo(json.dumps(exc.as_dict(), indent=2))
+    else:
+        console.print("COX failed", style="bold red", markup=False)
+        console.print(str(exc), markup=False)
+    raise typer.Exit(1)
+
+
+def version_callback(value: bool):
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=version_callback,
+        is_eager=True,
+        help="Show the tool version.",
+    ),
+):
+    pass
+
+
+@app.command("validate")
+def validate_command(
+    project_path: Path = typer.Argument(Path(".")),
+    machine: bool = typer.Option(False, "--json", help="Emit JSON diagnostics."),
+    strict: bool = typer.Option(False, "--strict", help="Fail on warnings."),
+):
+    """Check canonical schemas, paths and page/component bindings."""
+    try:
+        summary = validate_project(project_path)
+        if strict and summary.warnings:
+            fail("WARNINGS_AS_ERRORS", "\n".join(summary.warnings))
+        output(
+            {
+                "ok": True,
+                "version": __version__,
+                "project": str(summary.project_root),
+                "documentCount": len(summary.documents),
+                "warnings": summary.warnings,
+            },
+            machine,
+            "COX validation passed",
+        )
+    except (CoxError, OSError) as exc:
+        failure(exc, machine)
+
+
+@app.command("compile")
+def compile_command(
+    project_path: Path = typer.Argument(Path(".")),
+    out_dir: Path = typer.Option(Path("build"), "--out", "-o"),
+    targets: list[str] = typer.Option(
+        [], "--target", "-t", help="json, react, package or all; repeat or use commas."
+    ),
+    machine: bool = typer.Option(False, "--json"),
+    strict: bool = typer.Option(False, "--strict"),
+):
+    """Compile validated contracts into deterministic JSON, React stubs and ZIPs."""
+    try:
+        result = compile_project(project_path, out_dir, targets=targets, strict=strict)
+        output({"ok": True, **result}, machine, "COX compilation passed")
+    except (CoxError, OSError) as exc:
+        failure(exc, machine)
+
+
+@app.command("init")
+def init_command(
+    destination: Path = typer.Argument(...),
+    name: Optional[str] = typer.Option(None, "--name"),
+    machine: bool = typer.Option(False, "--json"),
+):
+    """Create a complete example project in a new or empty directory."""
+    try:
+        output(
+            {"ok": True, "project": init_project(destination, name)},
+            machine,
+            "COX project created",
+        )
+    except (CoxError, OSError) as exc:
+        failure(exc, machine)
+
+
+@app.command("verify-package")
+def verify_command(
+    archive: Path = typer.Argument(...), machine: bool = typer.Option(False, "--json")
+):
+    """Verify ZIP contents against the embedded SHA-256 inventory (not a signature)."""
+    try:
+        output(verify_archive(archive), machine, "COX package verified")
+    except (CoxError, OSError) as exc:
+        failure(exc, machine)
+
+
+if __name__ == "__main__":
+    app()