cox-protocol-package 1.0.0

package/skills/zip-packager/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: zip-packager
+description: >
+  Expert at assembling, verifying, and delivering the final design-spec ZIP package for the
+  LLMAgentZipRecreation workflow. Use this skill for Step 09, or any time a user needs to
+  compress a structured documentation folder into a verified, downloadable ZIP. Trigger on:
+  "zip up the design specs", "create the final package", "compress and verify the output folder",
+  "make a downloadable zip from these files", or when the zip-design-orchestrator delegates Step 09.
+  Also useful standalone when a user has a folder of files they want packaged and verified before
+  download.
+---
+
+# ZIP Packager
+
+You are the expert for **Step 09** of the LLMAgentZipRecreation workflow. Your job is to assemble
+all generated files into a verified, clean ZIP archive and deliver it to the user as a download link.
+
+## Pre-Zip Quality Gate
+
+Before creating the ZIP, run through this checklist. Report any failures to the orchestrator
+rather than zipping a broken package.
+
+### File Completeness Check
+
+```bash
+# List the project folder contents
+ls -la {project_slug}_design_specs/
+```
+
+Verify:
+- [ ] Every screenshot file (`*.png`, `*.jpg`, `*.webp`) has a matching `.design.md`
+- [ ] Every screenshot file has a matching `.yaml`
+- [ ] `README.md` is present
+- [ ] `website_logic_and_functionality.md` is present
+- [ ] `coding_agent_starting_point.md` is present
+- [ ] `llm_agent_zip_recreation_instructions.yaml` is present
+- [ ] No files named with timestamps (`image001`, `screenshot_2024...`, `crop_...`)
+- [ ] No temp or partial files (`.tmp`, `.partial`, empty files)
+
+### UTF-8 Check
+
+```bash
+# Verify text files are valid UTF-8
+file {project_slug}_design_specs/*.md {project_slug}_design_specs/*.yaml
+```
+
+If any file shows encoding issues, flag it for the orchestrator to regenerate.
+
+---
+
+## Zip Assembly
+
+```bash
+# Create ZIP from the root design-specs folder
+cd /home/claude  # or wherever the project folder lives
+zip -r {project_slug}_full_design_and_build_docs.zip {project_slug}_design_specs/
+
+# Verify the zip was created
+ls -lh {project_slug}_full_design_and_build_docs.zip
+```
+
+---
+
+## Zip Verification
+
+After creating the ZIP, always verify its contents:
+
+```bash
+# List zip contents
+unzip -l {project_slug}_full_design_and_build_docs.zip
+```
+
+Confirm:
+- [ ] All expected files appear in the listing
+- [ ] No paths outside the root folder (no absolute paths, no `..` traversal)
+- [ ] File sizes look reasonable (non-zero for all files)
+- [ ] ZIP opens successfully (no corruption)
+
+---
+
+## Extending an Existing ZIP
+
+If the user already has a ZIP from a previous run:
+
+```bash
+# Unzip to a temp directory
+mkdir -p /tmp/zip_extend_work
+unzip existing_package.zip -d /tmp/zip_extend_work/
+
+# Copy new/updated files into the unzipped folder
+cp new_files/* /tmp/zip_extend_work/{existing_root_folder}/
+
+# Recompress with a new descriptive name (don't overwrite original)
+cd /tmp/zip_extend_work
+zip -r /home/claude/{project_slug}_full_design_and_build_docs_v2.zip {existing_root_folder}/
+```
+
+**Never overwrite the original ZIP** unless the user explicitly requests it.
+
+---
+
+## Delivery
+
+After successful verification, present the ZIP file to the user using `present_files`. Then provide
+a brief completion note:
+
+```
+✓ ZIP package ready:
+  • {N} screenshots renamed and included
+  • {N} .design.md + .yaml spec pairs
+  • 4 package-level docs (README, logic, build guide, recreation instructions)
+  • Total size: {X}MB
+```
+
+Keep the note short — the user can inspect the file themselves.
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| ZIP too large (>50MB) | Check for uncompressed video/image artifacts; exclude with `zip -x` |
+| Missing spec pair | Flag to orchestrator; regenerate before zipping |
+| Encoding error | Re-save file with `iconv -f latin1 -t utf-8` or regenerate |
+| ZIP opens as empty | Check working directory; ensure relative path used in `zip` command |
+| Duplicate filenames | Review slug uniqueness; one screenshot per slug only |

package/templates/ComponentName.cox.template

@@ -0,0 +1,33 @@
+CoxVersion: "1.0"
+FileType: "component_spec"
+ComponentName: "{component_slug}"
+Slug: "{component_slug}"
+Schema: "cox.component.v1"
+Role: "{component_role}"
+EvidenceSummary:
+  Visible: []
+  UserSpecified: []
+  Inferred: []
+  Intended: []
+  Recommended: []
+NamingDecision:
+  ChosenName: "{component_slug}"
+  Reason: ""
+  RejectedAlternatives: []
+  AmbiguityRisk: "Low|Medium|High"
+  EvidenceLevel: "Visible|UserSpecified|Inferred"
+VisibleStructure:
+  Regions: []
+VisualStyle:
+  Tokens: []
+Interactions:
+  Visible: []
+  Inferred: []
+  Intended: []
+  Recommended: []
+Responsive:
+  Desktop: ""
+  Tablet: ""
+  Mobile: ""
+ImplementationHints: []
+ChildSubcomponents: []

package/templates/Page.cox.template

@@ -0,0 +1,36 @@
+CoxVersion: "1.0"
+FileType: "page_spec"
+PageName: "{PageName}"
+Slug: "{page_slug}"
+Schema: "cox.page.v1"
+ProjectName: "{ProjectName}"
+PageType: "{CanonicalPageType}"
+EvidenceSummary:
+  Visible: []
+  UserSpecified: []
+  Inferred: []
+  Intended: []
+  Recommended: []
+VisibleStructure:
+  Regions: []
+NamingDecision:
+  ChosenName: "{PageName}"
+  Reason: "{Reason}"
+  RejectedAlternatives: []
+  AmbiguityRisk: "Low|Medium|High"
+  EvidenceLevel: "Visible|UserSpecified|Inferred"
+Layout:
+  Desktop: ""
+  Tablet: ""
+  Mobile: ""
+Children:
+  Components: []
+Interactions:
+  Visible: []
+  Inferred: []
+  Intended: []
+  Recommended: []
+RecursiveDecompositionDecision:
+  Complexity: "SimplePage|ModeratePage|ComplexPage"
+  Reason: ""
+  Action: ""

package/templates/crop_metadata.cox.template

@@ -0,0 +1,15 @@
+CoxVersion: "1.0"
+FileType: "crop_metadata"
+Slug: "{component_slug}_crop_metadata"
+Schema: "cox.crop_metadata.v1"
+SourceScreenshot: "dashboard_screenshot.png"
+OutputScreenshot: "{component_slug}_screenshot.png"
+BoundaryConfidence: "High"
+EstimatedBoundingBox:
+  Unit: "px|percent"
+  X: ""
+  Y: ""
+  Width: ""
+  Height: ""
+IncludedPaddingReason: ""
+ExcludedRegions: []

package/tools/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "1.0.0"

package/tools/cox_cli.py

@@ -0,0 +1,127 @@
+# pyright: reportMissingTypeStubs=false
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer  # type: ignore[import-untyped]
+from rich.console import Console  # type: ignore[import-untyped]
+from rich.table import Table  # type: ignore[import-untyped]
+
+from . import __version__
+from .cox_lib import CoxError, compile_project, validate_project
+
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="Validate and compile COX projects.",
+)
+console = Console()
+
+
+def print_validation_summary(
+    project_label: str,
+    document_count: int,
+    warnings: list[str],
+) -> None:
+    table = Table(show_header=False, box=None)
+    table.add_row("Project", project_label)
+    table.add_row("Validated documents", str(document_count))
+    table.add_row("Warnings", str(len(warnings)))
+    console.print(table)
+    for warning in warnings:
+        console.print(f"[yellow]- {warning}[/yellow]")
+
+
+@app.command("validate")
+def validate_command(
+    project_path: Path = typer.Argument(
+        Path("."),
+        exists=True,
+        resolve_path=True,
+    ),
+) -> None:
+    """Validate all COX documents referenced by manifest.cox."""
+    try:
+        summary = validate_project(project_path)
+    except CoxError as exc:
+        console.print(f"[bold red]Validation failed[/bold red]\n{exc}")
+        raise typer.Exit(code=1) from exc
+
+    console.print(
+        "[bold green]COX validation passed[/bold green] "
+        f"[dim](v{__version__})[/dim]"
+    )
+    print_validation_summary(
+        summary.project_root.as_posix(),
+        len(summary.documents),
+        summary.warnings,
+    )
+
+
+@app.command("compile")
+def compile_command(
+    project_path: Path = typer.Argument(
+        Path("."),
+        exists=True,
+        resolve_path=True,
+    ),
+    out_dir: Path = typer.Option(
+        Path("build"),
+        "--out",
+        "-o",
+        resolve_path=False,
+    ),
+    targets: list[str] = typer.Option(
+        [],
+        "--target",
+        "-t",
+        help="Compilation target(s) to emit. Repeat the flag or use commas.",
+    ),
+) -> None:
+    """Validate the project and emit normalized JSON outputs."""
+    try:
+        result = compile_project(project_path, out_dir, targets=targets)
+    except CoxError as exc:
+        console.print(f"[bold red]Compilation failed[/bold red]\n{exc}")
+        raise typer.Exit(code=1) from exc
+
+    console.print(
+        "[bold green]COX compilation passed[/bold green] "
+        f"[dim](v{__version__})[/dim]"
+    )
+    table = Table(show_header=False, box=None)
+    table.add_row("Build root", result["build_root"].as_posix())
+    table.add_row("Targets", ", ".join(result["targets"]))
+    json_result = result["target_results"].get("json")
+    if json_result is not None:
+        table.add_row(
+            "Normalized documents",
+            str(json_result["document_count"]),
+        )
+    react_result = result["target_results"].get("react")
+    if react_result is not None:
+        table.add_row("React pages", str(react_result["page_count"]))
+        table.add_row(
+            "React components",
+            str(react_result["component_count"]),
+        )
+        table.add_row(
+            "React manifest",
+            react_result["manifest"].as_posix(),
+        )
+    package_result = result["target_results"].get("package")
+    if package_result is not None:
+        table.add_row("Package archive", package_result["archive"].as_posix())
+        table.add_row("Package files", str(package_result["file_count"]))
+        table.add_row("Package sha256", package_result["sha256"])
+    table.add_row("Compiled manifest", result["compiled_manifest"].as_posix())
+    table.add_row("Verification report", result["report"].as_posix())
+    console.print(table)
+    for warning in result["warnings"]:
+        console.print(f"[yellow]- {warning}[/yellow]")
+
+
+if __name__ == "__main__":
+    app()