cox-protocol-package 1.0.2 → 1.2.0

package/cox_protocol/package_target.py

@@ -0,0 +1,262 @@
+"""Portable, deterministic archives with an independently checkable file inventory."""
+
+from __future__ import annotations
+import hashlib
+import json
+import stat
+import zipfile
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+from . import __version__
+from .cox_lib import (
+    CoxError,
+    TRANSIENT_DIRS,
+    fail,
+    portable_segment,
+    relative_path,
+    walk_files,
+    write_json,
+)
+
+FIXED_ZIP_TIMESTAMP = (1980, 1, 1, 0, 0, 0)
+EXCLUDED_FILENAMES = {
+    ".DS_Store",
+    "cox-guides.zip",
+    "cox_protocol_package_compiled.zip",
+    "llm_agent_zip_skills_bundle.zip",
+}
+
+
+def sha256_bytes(content: bytes) -> str:
+    return hashlib.sha256(content).hexdigest()
+
+
+def excluded(path: Path) -> bool:
+    return (
+        path.name in EXCLUDED_FILENAMES
+        or path.name == ".env"
+        or path.name.startswith(".env.")
+        or path.suffix in (".pyc", ".pyo", ".tgz")
+        or any(p.endswith(".egg-info") for p in path.parts)
+    )
+
+
+def package_filename(summary) -> str:
+    name = (
+        summary.documents[summary.manifest_path].get("PackageName")
+        or summary.documents[summary.manifest_path]["Slug"] + ".zip"
+    )
+    if not portable_segment(name):
+        fail("PACKAGE_NAME", "PackageName must be a portable filename, not a path")
+    return name if name.endswith(".zip") else name + ".zip"
+
+
+def zip_write_bytes(archive, name, content, mode=0o644):
+    info = zipfile.ZipInfo(name, FIXED_ZIP_TIMESTAMP)
+    info.create_system = 3
+    info.compress_type = zipfile.ZIP_DEFLATED
+    info.external_attr = (stat.S_IFREG | mode) << 16
+    archive.writestr(info, content)
+
+
+def emit_package_archive(summary, build_root: Path, target_results) -> dict[str, Any]:
+    archive_root = summary.documents[summary.manifest_path]["Slug"]
+    if not portable_segment(archive_root):
+        fail("PACKAGE_NAME", "Manifest Slug is a reserved archive directory name")
+    entries = {}
+    for reference in [summary.manifest_path, *summary.referenced_paths]:
+        if any(
+            part in TRANSIENT_DIRS
+            for part in reference.relative_to(summary.project_root).parts
+        ):
+            fail(
+                "PACKAGE_EXCLUDED",
+                "Manifest explicitly references a transient directory",
+                str(reference),
+            )
+        files = walk_files(reference) if reference.is_dir() else [reference]
+        for source in files:
+            if excluded(source):
+                if source == reference:
+                    fail(
+                        "PACKAGE_EXCLUDED",
+                        "Manifest explicitly references a transient or secret-like artifact",
+                        str(source),
+                    )
+                continue
+            if source.is_symlink() or not source.is_file():
+                fail(
+                    "PACKAGE_FILE",
+                    "Package sources must be regular files without symlinks",
+                    str(source),
+                )
+            rel = relative_path(summary.project_root, source)
+            if any(not portable_segment(part) for part in rel.split("/")):
+                fail(
+                    "PACKAGE_PATH",
+                    "Package source contains a non-portable archive path",
+                    rel,
+                )
+            if rel == "package.manifest.json" or rel.startswith("build/"):
+                fail("PACKAGE_RESERVED", "Source occupies a reserved archive path", rel)
+            entries[rel] = (
+                source.read_bytes(),
+                0o755 if source.stat().st_mode & 0o111 else 0o644,
+                "source",
+            )
+    # Only this staging directory is scanned, never the old destination directory.
+    for path in sorted(build_root.rglob("*")):
+        if path.is_file():
+            rel = "build/" + path.relative_to(build_root).as_posix()
+            entries[rel] = (path.read_bytes(), 0o644, "generated")
+    records = [
+        {
+            "path": archive_root + "/" + rel,
+            "source": rel,
+            "kind": kind,
+            "size": len(data),
+            "sha256": sha256_bytes(data),
+            "mode": mode,
+        }
+        for rel, (data, mode, kind) in sorted(entries.items())
+    ]
+    archive_path = build_root / "package" / package_filename(summary)
+    manifest = {
+        "generatedWith": f"cox {__version__}",
+        "deterministic": True,
+        "archiveRoot": archive_root,
+        "projectName": summary.documents[summary.manifest_path]["ProjectName"],
+        "packageName": archive_path.name,
+        "fileCount": len(records),
+        "files": records,
+    }
+    all_entries = {
+        archive_root + "/" + rel: (data, mode)
+        for rel, (data, mode, _) in entries.items()
+    }
+    all_entries[archive_root + "/package.manifest.json"] = (
+        (json.dumps(manifest, indent=2, sort_keys=True) + "\n").encode("utf-8"),
+        0o644,
+    )
+    archive_path.parent.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(archive_path, "w") as archive:
+        for name, (content, mode) in sorted(all_entries.items()):
+            zip_write_bytes(archive, name, content, mode)
+    checksum = sha256_bytes(archive_path.read_bytes())
+    manifest_path = archive_path.with_suffix(".manifest.json")
+    write_json(
+        manifest_path,
+        {
+            **manifest,
+            "archive": {
+                "path": archive_path.name,
+                "size": archive_path.stat().st_size,
+                "sha256": checksum,
+            },
+        },
+    )
+    return {
+        "output_root": archive_path.parent,
+        "archive": archive_path,
+        "manifest": manifest_path,
+        "file_count": len(all_entries),
+        "sha256": checksum,
+    }
+
+
+def verify_archive(path: Path) -> dict[str, Any]:
+    try:
+        with zipfile.ZipFile(path) as archive:
+            names = archive.namelist()
+            if len(set(names)) != len(names):
+                fail("ARCHIVE_DUPLICATE", "Archive contains duplicate names")
+            for info in archive.infolist():
+                name = info.filename
+                if (
+                    any(part in ("", ".", "..") for part in name.split("/"))
+                    or any(not portable_segment(part) for part in name.split("/"))
+                    or any(c in name for c in '\\<>:"|?*')
+                    or any(ord(c) < 32 for c in name)
+                    or len(PurePosixPath(name).parts) < 2
+                ):
+                    fail("ARCHIVE_PATH", "Archive contains an invalid path", name)
+                if stat.S_ISLNK(info.external_attr >> 16):
+                    fail("ARCHIVE_SYMLINK", "Symlinks are not supported", name)
+            indexes = [
+                name
+                for name in names
+                if len(PurePosixPath(name).parts) == 2
+                and name.endswith("/package.manifest.json")
+            ]
+            if len(indexes) != 1:
+                fail(
+                    "ARCHIVE_MANIFEST",
+                    "Expected one package.manifest.json at the archive root",
+                )
+            manifest = json.loads(archive.read(indexes[0]))
+            root = manifest["archiveRoot"]
+            if indexes[0] != root + "/package.manifest.json":
+                fail("ARCHIVE_ROOT", "Manifest root differs from archive root")
+            records = manifest["files"]
+            if (
+                not isinstance(root, str)
+                or not isinstance(records, list)
+                or any(not isinstance(record, dict) for record in records)
+            ):
+                fail("ARCHIVE_MANIFEST", "Invalid root or file inventory")
+            for record in records:
+                if (
+                    not isinstance(record.get("path"), str)
+                    or type(record.get("size")) is not int
+                    or not isinstance(record.get("sha256"), str)
+                    or record.get("mode") not in (0o644, 0o755)
+                ):
+                    fail("ARCHIVE_MANIFEST", "Invalid file record")
+            if manifest["fileCount"] != len(records):
+                fail("ARCHIVE_COUNT", "Manifest file count differs from records")
+            declared = [record["path"] for record in records]
+            if len(set(declared)) != len(declared) or set(names) != (
+                set(declared) | set(indexes)
+            ):
+                fail(
+                    "ARCHIVE_CONTENTS", "Archive entries differ from the file inventory"
+                )
+            for record in records:
+                name = record["path"]
+                if not name.startswith(root + "/"):
+                    fail(
+                        "ARCHIVE_ROOT",
+                        "File is outside the declared archive root",
+                        name,
+                    )
+                data = archive.read(name)
+                if (
+                    len(data) != record["size"]
+                    or sha256_bytes(data) != record["sha256"]
+                ):
+                    fail(
+                        "ARCHIVE_HASH",
+                        "File does not match its size/SHA-256 record",
+                        name,
+                    )
+                info = archive.getinfo(name)
+                if stat.S_IMODE(info.external_attr >> 16) != record["mode"]:
+                    fail("ARCHIVE_MODE", "File permissions differ from inventory", name)
+            return {
+                "ok": True,
+                "archive": str(path),
+                "fileCount": len(records),
+                "sha256": sha256_bytes(path.read_bytes()),
+            }
+    except (
+        OSError,
+        zipfile.BadZipFile,
+        ValueError,
+        KeyError,
+        TypeError,
+        RuntimeError,
+    ) as exc:
+        if isinstance(exc, CoxError):
+            raise
+        raise CoxError(f"Could not verify archive: {exc}") from exc

package/cox_protocol/react_target.py

@@ -0,0 +1,306 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from . import __version__
+from .cox_lib import fail, portable_segment
+
+if TYPE_CHECKING:
+    from .cox_lib import ValidationSummary
+
+
+def pascal_case(value: str) -> str:
+    pieces = value.replace("-", "_").split("_")
+    name = "".join(piece.capitalize() for piece in pieces if piece)
+    return "Cox" + name if name[:1].isdigit() else name
+
+
+def relative_import(from_dir: Path, target_dir: Path) -> str:
+    import_path = os.path.relpath(target_dir, from_dir).replace(os.sep, "/")
+    if import_path.startswith("."):
+        return import_path
+    return f"./{import_path}"
+
+
+def document_for_instruction(
+    summary: "ValidationSummary",
+    instruction_path: str,
+) -> dict[str, Any]:
+    document_path = (summary.project_root / instruction_path).resolve()
+    try:
+        return summary.documents[document_path]
+    except KeyError as exc:
+        raise RuntimeError(
+            f"Missing parsed COX document for {instruction_path}"
+        ) from exc
+
+
+def format_comment_block(lines: list[str]) -> str:
+    body = "\n".join(
+        " * " + line.replace("*/", "* /").replace("\r", " ").replace("\n", "\n * ")
+        for line in lines
+    )
+    return f"/**\n{body}\n */"
+
+
+def format_list(items: list[str]) -> str:
+    if not items:
+        return "none"
+    if not isinstance(items, list):
+        return json.dumps(items, ensure_ascii=True)
+    return ", ".join(
+        item if isinstance(item, str) else json.dumps(item, ensure_ascii=True)
+        for item in items
+    )
+
+
+def evidence_comment_lines(document: dict[str, Any]) -> list[str]:
+    return [
+        f"{section}.{level}: {format_list(values)}"
+        for section in ("EvidenceSummary", "Interactions")
+        for level, values in document.get(section, {}).items()
+    ]
+
+
+def write_text(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+def component_comment_lines(component: dict[str, Any]) -> list[str]:
+    visual_style = component.get("VisualStyle", {})
+    responsive = component.get("Responsive", {})
+    interactions = component.get("Interactions", {})
+    hints = component.get("ImplementationHints", [])
+    return [
+        f"COX component slug: {component.get('Slug', 'unknown')}",
+        f"Role: {component.get('Role', 'unspecified')}",
+        f"Token refs: {format_list(visual_style.get('Tokens', []))}",
+        f"Desktop: {responsive.get('Desktop', 'unspecified')}",
+        f"Tablet: {responsive.get('Tablet', 'unspecified')}",
+        f"Mobile: {responsive.get('Mobile', 'unspecified')}",
+        (f"Interaction notes: {format_list(interactions.get('Inferred', []))}"),
+        f"Implementation hints: {format_list(hints)}",
+    ] + evidence_comment_lines(component)
+
+
+def page_comment_lines(page: dict[str, Any]) -> list[str]:
+    layout = page.get("Layout", {})
+    regions = page.get("VisibleStructure", {}).get("Regions", [])
+    return [
+        f"COX page slug: {page.get('Slug', 'unknown')}",
+        f"Page type: {page.get('PageType', 'unspecified')}",
+        f"Visible regions: {format_list(regions)}",
+        f"Desktop layout: {layout.get('Desktop', 'unspecified')}",
+        f"Tablet layout: {layout.get('Tablet', 'unspecified')}",
+        f"Mobile layout: {layout.get('Mobile', 'unspecified')}",
+    ] + evidence_comment_lines(page)
+
+
+def render_component_stub(component: dict[str, Any]) -> str:
+    component_name = pascal_case(component["Slug"])
+    comment_block = format_comment_block(component_comment_lines(component))
+    role = json.dumps(component.get("Role", "Component"))
+    lines = [
+        'import type { ReactNode } from "react";',
+        "",
+        comment_block,
+        f"export interface {component_name}Props {{",
+        "  children?: ReactNode;",
+        "}",
+        "",
+        f"export function {component_name}({{",
+        "  children,",
+        f"}}: {component_name}Props) {{",
+        "  return (",
+        (f'    <section data-cox-slug="{component["Slug"]}" aria-label={{{role}}}>'),
+        (
+            "      {/* TODO: Replace this structural stub with the real UI "
+            "implementation. */}"
+        ),
+        "      {children}",
+        "    </section>",
+        "  );",
+        "}",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def render_page_stub(
+    page: dict[str, Any],
+    component_entries: list[dict[str, Any]],
+    react_root: Path,
+) -> str:
+    page_name = pascal_case(page["Slug"]) + "Page"
+    page_dir = react_root / "pages" / page["ProjectName"] / pascal_case(page["Slug"])
+    import_lines: list[str] = []
+    render_lines: list[str] = []
+
+    for component_entry in component_entries:
+        component_name = pascal_case(component_entry["Slug"])
+        component_dir = react_root / "components" / component_name
+        import_path = relative_import(page_dir, component_dir)
+        import_lines.append(f'import {{ {component_name} }} from "{import_path}";')
+        render_lines.append(f"      <{component_name} />")
+
+    comment_block = format_comment_block(page_comment_lines(page))
+    imports = "\n".join(import_lines)
+    rendered_components = "\n".join(render_lines)
+    if not rendered_components:
+        rendered_components = (
+            "      {/* TODO: Wire child components from the COX page spec. */}"
+        )
+
+    return (
+        f"{imports}\n\n"
+        f"{comment_block}\n"
+        f"export interface {page_name}Props {{}}\n\n"
+        f"export function {page_name}(_: {page_name}Props) {{\n"
+        "  return (\n"
+        f'    <main data-cox-page="{page["Slug"]}">\n'
+        f"{rendered_components}\n"
+        "    </main>\n"
+        "  );\n"
+        "}\n"
+    )
+
+
+def emit_react_stubs(
+    summary: "ValidationSummary",
+    build_root: Path,
+) -> dict[str, Any]:
+    symbols = {}
+    for entry in summary.build_index["pages"]:
+        payload = document_for_instruction(summary, entry["instruction"])
+        project = payload["ProjectName"]
+        if not portable_segment(project):
+            fail(
+                "REACT_PATH",
+                "ProjectName must be a portable directory name for React output",
+                entry["instruction"],
+            )
+        for symbol, source in [
+            (pascal_case(entry["slug"]) + "Page", entry["instruction"])
+        ] + [(pascal_case(c["slug"]), c["instruction"]) for c in entry["components"]]:
+            if not portable_segment(symbol):
+                fail(
+                    "REACT_PATH",
+                    f"Generated name {symbol} is a reserved filename",
+                    source,
+                )
+            for declared in (symbol, symbol + "Props"):
+                prior = symbols.setdefault(declared.casefold(), source)
+                if prior != source:
+                    fail(
+                        "REACT_COLLISION",
+                        f"Generated identifier {declared} collides with {prior}",
+                        source,
+                    )
+    react_root = build_root / "react"
+    component_records: dict[str, dict[str, Any]] = {}
+    page_records: list[dict[str, Any]] = []
+
+    for page_entry in summary.build_index["pages"]:
+        page_payload = document_for_instruction(
+            summary,
+            page_entry["instruction"],
+        )
+        page_dir = (
+            react_root
+            / "pages"
+            / page_payload["ProjectName"]
+            / pascal_case(page_entry["slug"])
+        )
+        page_output = page_dir / "index.tsx"
+
+        page_component_entries: list[dict[str, Any]] = []
+        for component_entry in page_entry["components"]:
+            slug = component_entry["slug"]
+            component_payload = document_for_instruction(
+                summary,
+                component_entry["instruction"],
+            )
+            component_name = pascal_case(slug)
+            component_dir = react_root / "components" / component_name
+            component_output = component_dir / "index.tsx"
+            if slug not in component_records:
+                write_text(
+                    component_output,
+                    render_component_stub(component_payload),
+                )
+                component_records[slug] = {
+                    "slug": slug,
+                    "componentName": component_name,
+                    "output": component_output.relative_to(react_root).as_posix(),
+                }
+
+            page_component_entries.append(
+                {
+                    "Slug": slug,
+                    "ComponentName": component_name,
+                }
+            )
+
+        write_text(
+            page_output,
+            render_page_stub(page_payload, page_component_entries, react_root),
+        )
+        page_records.append(
+            {
+                "projectName": page_payload["ProjectName"],
+                "slug": page_payload["Slug"],
+                "componentName": pascal_case(page_payload["Slug"]) + "Page",
+                "output": page_output.relative_to(react_root).as_posix(),
+                "children": page_component_entries,
+            }
+        )
+
+    barrel_lines: list[str] = []
+    for component in sorted(
+        component_records.values(),
+        key=lambda item: item["componentName"],
+    ):
+        component_name = component["componentName"]
+        barrel_lines.append(
+            (f'export {{ {component_name} }} from "./components/{component_name}";')
+        )
+        barrel_lines.append(
+            (
+                f"export type {{ {component_name}Props }} "
+                f'from "./components/{component_name}";'
+            )
+        )
+
+    for page in sorted(page_records, key=lambda item: item["componentName"]):
+        page_component_name = page["componentName"]
+        page_path = page["output"].removesuffix("/index.tsx")
+        barrel_lines.append(f'export {{ {page_component_name} }} from "./{page_path}";')
+        barrel_lines.append(
+            (f'export type {{ {page_component_name}Props }} from "./{page_path}";')
+        )
+
+    write_text(react_root / "index.ts", "\n".join(barrel_lines) + "\n")
+
+    manifest_payload = {
+        "generatedWith": f"cox {__version__}",
+        "target": "react",
+        "components": sorted(
+            component_records.values(),
+            key=lambda item: item["componentName"],
+        ),
+        "pages": page_records,
+    }
+    write_text(
+        react_root / "manifest.react.json",
+        json.dumps(manifest_payload, indent=2, ensure_ascii=True) + "\n",
+    )
+
+    return {
+        "output_root": react_root,
+        "component_count": len(component_records),
+        "page_count": len(page_records),
+        "manifest": react_root / "manifest.react.json",
+    }

package/cox_protocol/scaffold.py

@@ -0,0 +1,56 @@
+"""Create a self-contained COX project from the installed starter assets."""
+
+from __future__ import annotations
+from pathlib import Path
+import os
+import re
+import shutil
+import tempfile
+import yaml
+from .cox_lib import CoxError, fail, portable_segment, validate_project
+
+
+def init_project(destination: Path, name: str | None = None) -> Path:
+    if destination.is_symlink():
+        fail("INIT_EXISTS", "Destination must not be a symlink", str(destination))
+    destination = destination.resolve()
+    if destination.exists() and (
+        not destination.is_dir() or any(destination.iterdir())
+    ):
+        fail(
+            "INIT_EXISTS",
+            "Destination must be new or empty; existing files are preserved",
+            str(destination),
+        )
+    title = name or destination.name
+    if not portable_segment(title):
+        fail(
+            "PROJECT_NAME",
+            "Choose a non-empty portable project name, without path separators",
+            title,
+        )
+    slug = re.sub("[^a-z0-9]+", "_", title.lower()).strip("_") or "cox_project"
+    try:
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.TemporaryDirectory(
+            prefix=".cox-init-", dir=destination.parent
+        ) as temp:
+            stage = Path(temp) / "project"
+            shutil.copytree(Path(__file__).parent / "starter", stage)
+            for rel in ["manifest.cox", "page/page.cox"]:
+                path = stage / rel
+                doc = yaml.safe_load(path.read_text(encoding="utf-8"))
+                doc["ProjectName"] = title
+                if rel == "manifest.cox":
+                    doc["Slug"] = slug
+                    doc["PackageName"] = slug + ".zip"
+                path.write_text(
+                    yaml.safe_dump(doc, sort_keys=False, allow_unicode=True),
+                    encoding="utf-8",
+                )
+            validate_project(stage)
+            # rename refuses a concurrently populated destination directory.
+            os.replace(stage, destination)
+        return destination
+    except OSError as exc:
+        raise CoxError(f"Could not create project: {exc}") from exc