cox-protocol-package 1.0.0

package/tools/package_target.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import zipfile
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Iterable
+
+from .cox_lib import relative_path
+
+
+if TYPE_CHECKING:
+    from .cox_lib import ValidationSummary
+
+
+FIXED_ZIP_TIMESTAMP = (1980, 1, 1, 0, 0, 0)
+EXCLUDED_PARTS = {
+    ".git",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".venv",
+    "__pycache__",
+    "node_modules",
+}
+EXCLUDED_SUFFIXES = {".pyc", ".pyo", ".tgz"}
+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 sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def package_filename(summary: "ValidationSummary") -> str:
+    manifest = summary.documents[summary.manifest_path]
+    raw_name = str(manifest.get("PackageName") or "cox_protocol_package.zip")
+    file_name = Path(raw_name).name
+    if not file_name.endswith(".zip"):
+        file_name = f"{file_name}.zip"
+    if file_name == ".zip":
+        return "cox_protocol_package.zip"
+    return file_name
+
+
+def is_safe_project_file(
+    path: Path,
+    project_root: Path,
+    package_output: Path,
+) -> bool:
+    resolved = path.resolve()
+    try:
+        relative = resolved.relative_to(project_root.resolve())
+    except ValueError:
+        return False
+
+    if resolved == package_output.resolve():
+        return False
+    if relative.parts[:2] == ("build", "package"):
+        return False
+    if any(part in EXCLUDED_PARTS for part in relative.parts):
+        return False
+    if relative.name in EXCLUDED_FILENAMES:
+        return False
+    if relative.suffix in EXCLUDED_SUFFIXES:
+        return False
+    return True
+
+
+def iter_files(path: Path) -> Iterable[Path]:
+    if path.is_file():
+        yield path
+        return
+    if path.is_dir():
+        for child in path.rglob("*"):
+            if child.is_file() and not child.is_symlink():
+                yield child
+
+
+def collect_package_files(
+    summary: "ValidationSummary",
+    target_results: dict[str, dict[str, Any]],
+    package_output: Path,
+) -> list[Path]:
+    candidates: list[Path] = [summary.manifest_path, *summary.referenced_paths]
+
+    for target_name, result in target_results.items():
+        if target_name == "package":
+            continue
+        for key in ("output_root", "manifest"):
+            value = result.get(key)
+            if isinstance(value, Path):
+                candidates.append(value)
+
+    files_by_relative_path: dict[str, Path] = {}
+    for candidate in candidates:
+        for file_path in iter_files(candidate):
+            if not is_safe_project_file(
+                file_path,
+                summary.project_root,
+                package_output,
+            ):
+                continue
+            relative = relative_path(summary.project_root, file_path)
+            files_by_relative_path[relative] = file_path.resolve()
+
+    return [
+        files_by_relative_path[key]
+        for key in sorted(files_by_relative_path)
+    ]
+
+
+def zip_write_bytes(
+    archive: zipfile.ZipFile,
+    archive_path: str,
+    content: bytes,
+) -> None:
+    info = zipfile.ZipInfo(archive_path, FIXED_ZIP_TIMESTAMP)
+    info.compress_type = zipfile.ZIP_DEFLATED
+    info.external_attr = 0o644 << 16
+    archive.writestr(info, content)
+
+
+def emit_package_archive(
+    summary: "ValidationSummary",
+    build_root: Path,
+    target_results: dict[str, dict[str, Any]],
+) -> dict[str, Any]:
+    output_root = build_root / "package"
+    output_root.mkdir(parents=True, exist_ok=True)
+
+    archive_path = output_root / package_filename(summary)
+    source_files = collect_package_files(
+        summary,
+        target_results,
+        archive_path,
+    )
+    archive_root = summary.project_root.name
+
+    file_records = []
+    for source_file in source_files:
+        relative = relative_path(summary.project_root, source_file)
+        file_records.append(
+            {
+                "path": f"{archive_root}/{relative}",
+                "source": relative,
+                "size": source_file.stat().st_size,
+                "sha256": sha256_file(source_file),
+            }
+        )
+
+    package_manifest = {
+        "generatedWith": "cox 1.0.0",
+        "deterministic": True,
+        "archiveRoot": archive_root,
+        "projectName": summary.documents[summary.manifest_path].get(
+            "ProjectName"
+        ),
+        "packageName": archive_path.name,
+        "fileCount": len(file_records),
+        "files": file_records,
+    }
+    manifest_bytes = (
+        json.dumps(package_manifest, indent=2, sort_keys=True) + "\n"
+    ).encode("utf-8")
+
+    with zipfile.ZipFile(archive_path, "w") as archive:
+        for source_file, file_record in zip(source_files, file_records):
+            zip_write_bytes(
+                archive,
+                str(file_record["path"]),
+                source_file.read_bytes(),
+            )
+        zip_write_bytes(
+            archive,
+            f"{archive_root}/package.manifest.json",
+            manifest_bytes,
+        )
+
+    archive_bytes = archive_path.read_bytes()
+    archive_sha256 = sha256_bytes(archive_bytes)
+    disk_manifest = {
+        **package_manifest,
+        "archive": {
+            "path": relative_path(summary.project_root, archive_path),
+            "size": archive_path.stat().st_size,
+            "sha256": archive_sha256,
+        },
+    }
+    manifest_path = output_root / f"{archive_path.stem}.manifest.json"
+    manifest_path.write_text(
+        json.dumps(disk_manifest, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+
+    return {
+        "output_root": output_root,
+        "archive": archive_path,
+        "manifest": manifest_path,
+        "file_count": len(file_records) + 1,
+        "sha256": archive_sha256,
+    }

package/tools/react_target.py

@@ -0,0 +1,278 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+
+if TYPE_CHECKING:
+    from .cox_lib import ValidationSummary
+
+
+def pascal_case(value: str) -> str:
+    pieces = value.replace("-", "_").split("_")
+    return "".join(piece.capitalize() for piece in pieces if piece)
+
+
+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(f" * {line}" for line in lines)
+    return f"/**\n{body}\n */"
+
+
+def format_list(items: list[str]) -> str:
+    return ", ".join(items) if items else "none"
+
+
+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')}",
+        (
+            "Interaction notes: "
+            f"{format_list(interactions.get('Inferred', []))}"
+        ),
+        f"Implementation hints: {format_list(hints)}",
+    ]
+
+
+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')}",
+    ]
+
+
+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 (",
+        (
+            "    <section "
+            f"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]:
+    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} }} '
+                f'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 }} '
+                f'from "./{page_path}";'
+            )
+        )
+
+    write_text(react_root / "index.ts", "\n".join(barrel_lines) + "\n")
+
+    manifest_payload = {
+        "generatedWith": "cox 1.0.0",
+        "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",
+    }