cox-protocol-package 1.0.1 → 1.2.0

package/LocalAppManager/Dashboard/top_header_stats_bar/top_header_stats_bar.cox

@@ -0,0 +1,56 @@
+CoxVersion: "1.0"
+FileType: "component_spec"
+ComponentName: "top_header_stats_bar"
+Slug: "top_header_stats_bar"
+Schema: "cox.component.v1"
+Role: "Page header, search/action controls, and KPI summary cards"
+EvidenceSummary:
+  Visible: []
+  UserSpecified:
+    - "Component name appears in the approved COX naming examples or derived example structure."
+  Inferred:
+    - "Detailed behavior should be adapted to actual screenshots when supplied."
+  Intended: []
+  Recommended: []
+
+NamingDecision:
+  ChosenName: "top_header_stats_bar"
+  Reason: "Combines header and stats because user example binds them."
+  RejectedAlternatives:
+    - "generic_section"
+    - "nested_panel"
+    - "ambiguous_area"
+  AmbiguityRisk: "Low"
+  EvidenceLevel: "UserSpecified"
+
+VisibleStructure:
+  Note: "Placeholder until real screenshot crop is supplied."
+  ExpectedRegions:
+    - "Container surface"
+    - "Primary content group"
+    - "Secondary controls or metadata where visible"
+
+VisualStyle:
+  Tokens:
+    - "Color.SurfaceGlass"
+    - "Shape.CardRadius"
+    - "Typography.Body"
+    - "Motion.General"
+
+Interactions:
+  Visible: []
+  Inferred:
+    - "Hover and selected states may be required if controls are interactive."
+  Intended: []
+  Recommended:
+    - "Add keyboard-focus states and accessible labels."
+
+Responsive:
+  Desktop: "Use page-level placement."
+  Tablet: "Compress spacing and preserve hierarchy."
+  Mobile: "Stack or collapse only if layout requires it."
+
+ImplementationHints:
+  - "Implement as reusable component mapped to this exact slug."
+  - "Do not rename without updating protocols/component_binding_graph.cox and manifest.cox."
+ChildSubcomponents: []

package/LocalAppManager/Dashboard/top_header_stats_bar/top_header_stats_bar_screenshot.placeholder.txt

@@ -0,0 +1 @@
+Replace this placeholder with top_header_stats_bar_screenshot.png after real screenshot partitioning.

package/MANIFEST.in

@@ -0,0 +1,20 @@
+include LICENSE README.md CHANGELOG.md COX_FILE_FORMAT_SPECIFICATION_v1.0.md
+recursive-include cox_protocol/schemas *.json
+recursive-include cox_protocol/starter *
+recursive-include tests *.py
+global-exclude *.py[cod]
+global-exclude __pycache__
+include FINALIZATION.md
+recursive-include scripts *.py *.mjs
+recursive-include schemas *.json
+recursive-include examples *
+recursive-include guides *.md
+include manifest.cox package.json package-lock.json requirements.txt
+recursive-include LocalAppManager *
+recursive-include protocols *.cox
+recursive-include templates *
+recursive-include skills *
+recursive-include editor-support *
+recursive-include bin *.js
+prune editor-support/vscode/node_modules
+recursive-include tools *.py

package/README.md

@@ -1,193 +1,106 @@
-# COX Protocol Package
+# COX Protocol
 
-COX is a versioned, YAML-compatible file format for UI reconstruction, evidence tracking, component binding, implementation guidance, and agent-readable design specifications.
+**A design contract you can inspect, validate, and hand off.** COX records UI structure and the evidence behind a design decision in versioned `.cox` files. Its CLI checks the contract and generates normalized JSON, structural React scaffolds, and a reproducible ZIP with a SHA-256 inventory.
 
-This repository now treats `.cox` as a real format surface rather than renamed text files. COX v1.0 includes:
+Tool release **1.2.0** implements format **1.0**. Python 3.9+ is required; the optional npm wrapper also requires Node 18+.
 
-- a formal file format specification
-- versioned headers on `.cox` documents
-- JSON Schemas for validation
-- a manifest-driven validator/compiler CLI
-- normalized JSON build output
-- deterministic package ZIP output
-- minimal VS Code language support
+## Try it
 
-## COX v1.0
+Install the release wheel in an isolated environment (replace the wheel path with your downloaded artifact):
 
-- Extension: `.cox`
-- MIME type: `application/vnd.cox+yaml`
-- Encoding: `UTF-8`
-- Syntax base: `YAML-compatible structured text`
-- Entry point: `manifest.cox`
-
-Every `.cox` document starts with a common header:
-
-```yaml
-CoxVersion: "1.0"
-FileType: "component_spec"
-Slug: "projects_grid_cards"
-Schema: "cox.component.v1"
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install /path/to/cox_protocol_package-1.2.0-py3-none-any.whl
+cox --version
+cox init my-contract --name MyProject
+cox validate my-contract --strict
+cox compile my-contract --target all --out build
+cox verify-package my-contract/build/package/myproject.zip
 ```
 
-## Repository Contents
+Relative `--out` paths are resolved **inside the COX project**. Absolute output directories also work. `python -m cox_protocol` provides the same commands as `cox`.
 
-- `COX_FILE_FORMAT_SPECIFICATION_v1.0.md`: formal format rules for COX v1.0
-- `manifest.cox`: manifest entrypoint for validation and compilation
-- `protocols/`: shared protocol documents referenced by the manifest
-- `guides/`: package guides, including imported archive audit notes and NPM installation instructions
-- `skills/`: LLM-agent skill bundles imported from `llm_agent_zip_skills_bundle.zip`
-- `schemas/`: JSON Schemas for manifest, page, component, protocol, and crop metadata documents
-- `tools/`: Python validator/compiler package and CLI
-- `bin/`: NPM wrapper that delegates to the Python COX CLI
-- `editor-support/vscode/`: minimal VS Code language registration for `.cox`
-- `LocalAppManager/`: example manifest-driven project content
-- `templates/`: versioned starter templates for page, component, and crop metadata files
+For a source checkout, replace the wheel installation with `python -m pip install -e '.[dev]'`. The npm installation guide is [here](guides/npm-installation.md). These commands refer to local release artifacts; consult [the release record](FINALIZATION.md) for publication status before assuming 1.2.0 is available on a registry.
 
-## Commands
+## One rule, an observable failure, a correction
 
-Install the toolchain:
+A manifest binds a component to `action_button`. Change the component document's `Slug` to `action_buton` and validation reports `BINDING_MISMATCH`, the file, the `Slug` field, and both values. Restore the slug and all targets compile.
 
-```bash
-python -m pip install -e .
-```
-
-Validate a COX project:
+Run the complete walkthrough from a source checkout after installing the package:
 
 ```bash
-cox validate .
+python scripts/demo.py --out /tmp/cox-contract-demo
 ```
 
-Compile a COX project to normalized JSON:
+It saves the invalid input, actual diagnostic, corrected input, verification result, generated React, and package. Use a new output folder on each run. [Example guide](guides/contract-demo.md).
 
-```bash
-cox compile . --out build
-```
+## What is checked
 
-Compile React stubs from the same normalized COX document model:
-
-```bash
-cox compile . --target react --out build
-```
+- UTF-8 and a JSON-compatible YAML subset, with duplicate keys, aliases, non-string keys, dates and non-finite numbers rejected.
+- Five canonical Draft 2020-12 schemas, shipped with the compiler: manifest, page, component, protocol, crop metadata.
+- Manifest references, file/directory expectations, project boundaries, and page/component identity and folder bindings.
+- Evidence labels: `Visible`, `UserSpecified`, `Inferred`, `Intended`, `Recommended`. Their factual accuracy still requires human evidence review.
+- Generated identifiers, collisions, output ownership and archive inventory integrity.
 
-Compile multiple targets in one pass:
+The contract describes an interface. It does **not** inspect an application's AST, execute design rules against a rendered page, implement interactions, prove accessibility, or provide an MCP server. The React target emits typed structural scaffolds with evidence comments; it does not infer finished styling or behavior. Protocol prose and `VerificationRules` are authoring guidance, not arbitrary executable rules.
 
-```bash
-cox compile . --target json --target react --target package --out build
-```
+## Commands
 
-The `package` target emits a deterministic ZIP archive and package manifest under `build/package/`. The archive uses sorted paths, fixed ZIP timestamps, project-relative names, SHA-256 file records, and excludes transient local artifacts such as `.venv`, `.mypy_cache`, `node_modules`, `*.egg-info`, raw intake ZIPs, and `build/package` itself.
+| Command | Result |
+|---|---|
+| `cox init PATH --name NAME` | Complete small project; destination must be new or empty |
+| `cox validate PATH --json` | Machine-readable diagnostics with exit 1 on invalid input |
+| `cox validate PATH --strict` | Also fail on unreferenced-document warnings |
+| `cox compile PATH --target json` | Normalized JSON (the default target) |
+| `cox compile PATH -t react -t package` | Requested targets in stable order |
+| `cox compile PATH -t all --json` | All three targets and artifact paths as JSON |
+| `cox verify-package FILE.zip --json` | Check every payload against its embedded size/hash/mode record |
+| `cox --version` | Tool version |
 
-## Build Output
+`--target` accepts repeated flags and comma-separated values. `BuildTargets` records supported project intent; the command selects which targets to emit and defaults to JSON. Usage errors exit 2; validation, compilation and verification failures exit 1. JSON mode applies to command results; argument parsing errors retain the CLI's normal usage format.
 
-Compilation emits:
+## Build artifacts and ownership
 
 ```text
 build/
+  .cox-build.json                 # exact files owned by this compiler run
   manifest.compiled.json
-  normalized/
-  reports/
-    verification_report.txt
-  package/
-    cox_protocol_package_corrected.zip
-    cox_protocol_package_corrected.manifest.json
+  normalized/                    # selected json target
+  react/                         # selected react target
+  package/                       # selected package target
+  reports/verification_report.json
+  reports/verification_report.txt
 ```
 
-When the `react` target is requested, compilation also emits:
-
-```text
-build/
-  react/
-    components/
-    pages/
-    index.ts
-    manifest.react.json
-```
-
-The React target is intentionally stub-oriented. It uses COX structure, roles, token references, layout notes, and implementation hints to generate TSX placeholders, but it does not invent concrete CSS values, event handlers, or runtime data contracts from prose-only fields.
-
-## Guide and Skill Bundle Intake
-
-The manifest has first-class `GuideDocs` and `SkillBundles` sections.
+The package includes manifest-referenced inputs and artifacts generated in the current run, under the manifest slug. Entries have sorted names, fixed timestamps, normalized permissions, and SHA-256 records. The external inventory also records the ZIP's checksum. Neither inventory is a digital signature. Determinism is verified for identical input bytes/modes and toolchain; ZIP compression bytes may differ between compression-library versions.
 
-Current imported content:
+Recompilation replaces only the exact generated files recorded in `.cox-build.json`. Files from deselected targets are removed; unrelated files are preserved. A collision, edited generated file, or symlink produces an error before publication. Use a fresh `--out` directory for legacy builds without an ownership marker or when preserving edits. There is no force-overwrite mode. Publication attempts rollback on I/O failure; it is not a concurrent-writer or power-loss transaction.
 
-- `cox_protocol_package_compiled.zip` was audited as a legacy snapshot of this same package. It was not extracted over the live source because the current repository has the newer COX v1.0 manifest, schema, compiler, package target, and `protocols/` layout. See `guides/imported-packages/cox_protocol_package_compiled.md`.
-- `llm_agent_zip_skills_bundle.zip` was expanded into six skill directories under `skills/`.
-- NPM installation instructions for another device live in `guides/npm-installation.md`.
+## Development and release checks
 
-Use this intake flow for future ZIP files:
+Use Node 22+ for development packaging; Node 18+ remains sufficient for the runtime wrapper.
 
 ```bash
-unzip -l cox_protocol_package_compiled.zip
-unzip -l llm_agent_zip_skills_bundle.zip
-```
-
-Inspect the listings before extraction. Reject or rename entries with absolute paths, `..` path segments, root-level collisions such as `README.md` or `manifest.cox`, generated caches, or unrelated build artifacts. Curated guide content should land in `guides/`; curated skill bundle content should land in `skills/`. After that, add concrete paths to `GuideDocs` and `SkillBundles`, then rerun validation and compilation.
-
-## Protocol Readiness Score
-
-| Attribute | Meter | Score | Notes |
-| --- | --- | ---: | --- |
-| Determinism | `[########--]` | 8/10 | Versioned headers, schema-backed manifests, stable package ordering, fixed ZIP timestamps, and SHA-256 records are now in place. Remaining work is an optional generated artifact policy for release bundles. |
-| Validation rigor | `[########--]` | 8/10 | YAML parsing, JSON Schema, manifest path checks, target enums, referenced guides, referenced skill bundle directories, and unreferenced `.cox` warnings are active. |
-| Evidence traceability | `[########--]` | 8/10 | Evidence and uncertainty protocols are explicit, and the package manifest records exact file hashes. Runtime visual evidence still depends on real screenshots replacing placeholders. |
-| Distribution readiness | `[#######---]` | 7/10 | Local Python CLI, NPM wrapper metadata, deterministic package output, VSIX packaging, guide docs, and skill bundle content are present. Public publishing still needs final repository URLs and account tokens. |
-| Interoperability | `[#######---]` | 7/10 | COX works as YAML-compatible structured text with JSON, React stub, VS Code, NPM, and ZIP surfaces. A TypeScript-native compiler and concrete design-token CSS layer remain future improvements. |
-
-COX complements Vercel v0 and Stitch-style AI design tools rather than replacing them. Those tools optimize prompt-to-app generation, visual iteration, repo sync, and deployment. COX optimizes deterministic file contracts, evidence tracking, schema validation, reproducible package output, and agent-to-agent handoff.
-
-## Publication and Local Testing
-
-Install and test the Python CLI locally:
-
-```bash
-python -m pip install -e .
-cox validate .
-cox compile . --target json --target react --target package --out build
-```
-
-Check the NPM package contents before publishing:
-
-```bash
-npm pack --dry-run
+python -m pip install -e '.[dev]'
+npm ci
+COX_REQUIRE_TYPESCRIPT=1 python -m pytest
+python scripts/release_check.py
+python -m build
 npm pack
-npm install -g ./cox-protocol-package-<version>.tgz
-python3 -m pip install PyYAML jsonschema typer rich
-cox-protocol validate .
-```
-
-The NPM wrapper delegates to the Python CLI, so the Python dependencies in `requirements.txt` must be installed in the environment used by `cox-protocol`. Set `COX_PYTHON=/path/to/python` if the desired interpreter is not `python3`.
-
-For a device-by-device installation walkthrough, see `guides/npm-installation.md`.
-
-Package the VS Code extension locally:
-
-```bash
-cd editor-support/vscode
-npm run package
+npm run package:vscode
 ```
 
-Public publishing still requires verified NPM, PyPI, and VS Code Marketplace credentials. Before publishing, confirm the repository URLs in `package.json`, `pyproject.toml`, and `editor-support/vscode/package.json` point to the final public repository.
+The tests exercise format errors, bindings, generated TypeScript, deterministic archives, tamper detection, safe rebuilds, CLI behavior and snippet validity. CI additionally installs a wheel and an sdist into separate environments, installs the npm tarball locally, and verifies their CLIs away from the checkout. Python schemas and starter files must work from the installed package alone.
 
-## Example Layout
+## Contents
 
-```text
-LocalAppManager/
-  Dashboard/
-    dashboard.cox
-    dashboard_screenshot.placeholder.txt
-    left_navigation_sidebar/
-      left_navigation_sidebar.cox
-      left_navigation_sidebar_screenshot.placeholder.txt
-    top_header_stats_bar/
-      top_header_stats_bar.cox
-      top_header_stats_bar_screenshot.placeholder.txt
-    projects_grid_cards/
-      projects_grid_cards.cox
-      projects_grid_cards_screenshot.placeholder.txt
-    analytics_sidebar_panels/
-      analytics_sidebar_panels.cox
-      analytics_sidebar_panels_screenshot.placeholder.txt
-```
+- `cox_protocol/`: installed compiler, canonical schema resources, starter assets.
+- `schemas/`: matching public schemas for external tooling.
+- `examples/quickstart/`: independent, small project with reference illustrations.
+- `LocalAppManager/` and root `manifest.cox`: larger sample with explicitly labelled screenshot placeholders.
+- `protocols/`, `templates/`, `skills/`, `guides/`: human/agent authoring material.
+- `editor-support/vscode/`: syntax highlighting and snippets; CLI validation is separate.
+- `tools/`: compatibility entry points for older source-checkout commands.
 
-The formal COX rules live in `COX_FILE_FORMAT_SPECIFICATION_v1.0.md`, and the executable contract lives in the schema files under `schemas/`.
+The [format specification](COX_FILE_FORMAT_SPECIFICATION_v1.0.md), [changelog](CHANGELOG.md), and [finalisation record](FINALIZATION.md) describe the implemented contract and release evidence. The [historical intake guide](guides/imported-packages/cox_protocol_package_compiled.md) records earlier archive provenance.

package/bin/cox-protocol.js

@@ -1,101 +1,27 @@
 #!/usr/bin/env node
-import { spawnSync } from "node:child_process";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const scriptPath = fileURLToPath(import.meta.url);
-const packageRoot = path.resolve(path.dirname(scriptPath), "..");
-const python = process.env.COX_PYTHON || "python3";
-const pythonPath = [packageRoot, process.env.PYTHONPATH]
-  .filter(Boolean)
-  .join(path.delimiter);
-const pythonEnv = {
-  ...process.env,
-  PYTHONPATH: pythonPath,
-};
-
-const versionCheck = spawnSync(
-  python,
-  [
-    "-c",
-    "import sys; print('.'.join(map(str, sys.version_info[:3]))); raise SystemExit(0 if sys.version_info >= (3, 9) else 1)",
-  ],
-  {
-    cwd: process.cwd(),
-    env: pythonEnv,
-    stdio: "pipe",
-  },
-);
-
-if (versionCheck.error) {
-  console.error(
-    `Unable to run the configured Python interpreter ${python}: ${versionCheck.error.message}`,
-  );
-  console.error(
-    "Install Python 3.9 or newer, or set COX_PYTHON to a working interpreter.",
-  );
-  process.exit(1);
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+if (process.argv.length === 3 && process.argv[2] === '--version') {
+  console.log(JSON.parse(readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version);
+  process.exit(0);
 }
-
-if (versionCheck.status !== 0) {
-  const detectedVersion = versionCheck.stdout.toString().trim() || "unknown";
-  console.error(
-    `COX requires Python 3.9 or newer, but ${python} resolved to ${detectedVersion}.`,
-  );
-  console.error(
-    "Install Python 3.9+ or point COX_PYTHON at a supported interpreter.",
-  );
-  process.exit(versionCheck.status ?? 1);
-}
-
-const dependencyCheck = spawnSync(
-  python,
-  ["-c", "import typer, yaml, jsonschema, rich"],
-  {
-    cwd: process.cwd(),
-    env: pythonEnv,
-    stdio: "pipe",
-  },
-);
-
-if (dependencyCheck.error) {
-  console.error(
-    `Unable to run the configured Python interpreter ${python}: ${dependencyCheck.error.message}`,
-  );
-  console.error(
-    "Install Python 3.9+ or point COX_PYTHON at a working interpreter.",
-  );
+const python = process.env.COX_PYTHON || (process.platform === 'win32' ? 'python' : 'python3');
+const env = { ...process.env };
+delete env.PYTHONPATH;
+// Remove the caller's directory before importing dependencies or the bundled CLI.
+const bootstrap = "import sys; root=sys.argv.pop(1); cwd=sys.argv.pop(1); sys.path=[root]+[p for p in sys.path if p and p!=cwd]; ";
+const probe = spawnSync(python, ['-c', bootstrap + "print('.'.join(map(str,sys.version_info[:3]))); sys.exit(3) if sys.version_info < (3,9) else None; import yaml,jsonschema,typer,rich", packageRoot, process.cwd()], { env, encoding: 'utf8' });
+if (probe.error || probe.status !== 0) {
+  console.error(`COX needs Python 3.9+ with its dependencies in the selected interpreter: ${python}`);
+  if (probe.error) console.error(probe.error.message);
+  else if (probe.status === 3) console.error(`Detected Python ${probe.stdout.trim()}.`);
+  else console.error('Install the Python package in a virtual environment, or install its requirements there; set COX_PYTHON to that environment’s Python executable.');
   process.exit(1);
 }
-
-if (dependencyCheck.status !== 0) {
-  console.error(
-    `Python dependencies for COX are missing in ${python}.`,
-  );
-  console.error(
-    "Install them with `python3 -m pip install PyYAML jsonschema typer rich` or point COX_PYTHON at an environment that already has them.",
-  );
-  process.exit(dependencyCheck.status ?? 1);
-}
-
-const result = spawnSync(
-  python,
-  ["-m", "tools.cox_cli", ...process.argv.slice(2)],
-  {
-    cwd: process.cwd(),
-    env: pythonEnv,
-    stdio: "inherit",
-  },
-);
-
-if (result.error) {
-  console.error(
-    `Unable to run COX Python CLI with ${python}: ${result.error.message}`,
-  );
-  console.error(
-    "Install Python dependencies with `python -m pip install PyYAML jsonschema typer rich` or set COX_PYTHON.",
-  );
-  process.exit(1);
-}
-
-process.exit(result.status ?? 1);
+const result = spawnSync(python, ['-c', bootstrap + "sys.argv[0]='cox-protocol'; import runpy; runpy.run_module('cox_protocol.cox_cli',run_name='__main__')", packageRoot, process.cwd(), ...process.argv.slice(2)], { env, stdio: 'inherit' });
+if (result.error) console.error(`Could not start COX: ${result.error.message}`);
+process.exit(result.status ?? 1);

package/cox_protocol/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "1.2.0"
+__all__ = ["__version__"]

package/cox_protocol/__main__.py

@@ -0,0 +1,3 @@
+from .cox_cli import app
+
+app()