cox-protocol-package 1.0.0

package/COX_FILE_FORMAT_SPECIFICATION_v1.0.md

@@ -0,0 +1,236 @@
+# COX File Format Specification v1.0
+
+## 1. Status
+
+- Format name: `COX`
+- Version: `1.0`
+- File extension: `.cox`
+- MIME type: `application/vnd.cox+yaml`
+- Encoding: `UTF-8`
+- Syntax base: `YAML-compatible structured text`
+- Entry point: `manifest.cox`
+
+## 2. Purpose
+
+COX is a structured file format for UI reconstruction, evidence tracking, component binding, implementation guidance, and agent-readable design specifications. A COX project is manifest-driven and intended to be both human-readable and machine-validatable.
+
+## 3. Common Header
+
+Every `.cox` document must begin with the following versioned metadata header:
+
+```yaml
+CoxVersion: "1.0"
+FileType: "component_spec"
+Slug: "projects_grid_cards"
+Schema: "cox.component.v1"
+```
+
+Required header fields for all COX documents:
+
+- `CoxVersion`
+- `FileType`
+- `Slug`
+- `Schema`
+
+## 4. Supported File Types
+
+### `manifest`
+
+Project entrypoint that defines the package contract, referenced pages, guide documents, protocol documents, skill bundles, schemas, tooling, and build targets.
+
+Required top-level fields:
+
+- `CoxVersion`
+- `FileType`
+- `Slug`
+- `Schema`
+- `ProjectName`
+- `ProtocolExtension`
+- `MimeType`
+- `EntryPoint`
+- `Pages`
+
+Optional manifest file collections:
+
+- `ReferenceDocs`: human-facing root documentation files
+- `GuideDocs`: guide or tutorial files imported into `guides/`
+- `ProtocolDocs`: `.cox` methodology and system protocol documents
+- `SkillBundles`: LLM-agent skill bundle files or directories imported into `skills/`
+- `Schemas`: JSON Schema files used by the validator
+- `ToolingFiles`: compiler, editor, package, and distribution tooling files
+
+Supported build targets:
+
+- `json`
+- `react`
+- `package`
+
+### `page_spec`
+
+Defines page-level evidence, visible regions, child component bindings, layout behavior, and page interactions.
+
+Required top-level fields:
+
+- `CoxVersion`
+- `FileType`
+- `PageName`
+- `Slug`
+- `Schema`
+- `ProjectName`
+- `EvidenceSummary`
+- `VisibleStructure`
+- `Interactions`
+
+### `component_spec`
+
+Defines a reusable UI component, its evidence basis, visible structure, visual style, and interactions.
+
+Required top-level fields:
+
+- `CoxVersion`
+- `FileType`
+- `ComponentName`
+- `Slug`
+- `Schema`
+- `EvidenceSummary`
+- `VisibleStructure`
+- `Interactions`
+
+### `protocol_doc`
+
+Defines COX process rules, naming conventions, orchestration rules, logic notes, design tokens, or validation checklists.
+
+Required top-level fields:
+
+- `CoxVersion`
+- `FileType`
+- `Slug`
+- `Schema`
+- `ProtocolName`
+- `Purpose`
+
+### `crop_metadata`
+
+Defines crop planning metadata for derived screenshots.
+
+Required top-level fields:
+
+- `CoxVersion`
+- `FileType`
+- `Slug`
+- `Schema`
+- `SourceScreenshot`
+- `OutputScreenshot`
+- `BoundaryConfidence`
+- `EstimatedBoundingBox`
+
+## 5. Slug Rules
+
+`Slug` values use lowercase snake case.
+
+Allowed pattern:
+
+```text
+^[a-z0-9]+(_[a-z0-9]+)*$
+```
+
+Examples:
+
+- `dashboard`
+- `projects_grid_cards`
+- `deterministic_naming_convention`
+
+## 6. Evidence Model
+
+When evidence is relevant, COX documents should separate claims into explicit evidence levels:
+
+- `Visible`
+- `UserSpecified`
+- `Inferred`
+- `Intended`
+- `Recommended`
+
+The format does not permit inferred behavior to be represented as certain without explicit visible or user-provided evidence.
+
+## 7. Validation Model
+
+COX documents are parsed as YAML and validated against JSON Schema Draft 2020-12.
+
+Canonical schema ids:
+
+- `cox.manifest.v1`
+- `cox.page.v1`
+- `cox.component.v1`
+- `cox.protocol.v1`
+- `cox.crop_metadata.v1`
+
+Validation must include:
+
+- UTF-8 decoding
+- YAML parsing
+- Schema validation
+- Manifest reference existence checks
+- Page/component path checks
+- Unreferenced `.cox` file detection as a warning
+
+## 8. Compilation Model
+
+The first professional compilation target for COX v1.0 is normalized JSON. The current compiler also supports React stubs and deterministic package ZIP output.
+
+Expected pipeline:
+
+```text
+.cox files
+  -> parse YAML
+  -> validate against schema
+  -> check references and paths
+  -> emit normalized JSON
+  -> generate verification report
+```
+
+Recommended commands:
+
+```bash
+cox validate ./cox_protocol_package
+cox compile ./cox_protocol_package --out ./build
+cox compile ./cox_protocol_package --target react --out ./build
+cox compile ./cox_protocol_package --target json --target react --target package --out ./build
+```
+
+Expected build outputs:
+
+```text
+build/
+  manifest.compiled.json
+  normalized/
+  package/
+    cox_protocol_package_corrected.zip
+    cox_protocol_package_corrected.manifest.json
+  reports/
+    verification_report.txt
+```
+
+Optional React stub output:
+
+```text
+build/
+  react/
+    components/
+    pages/
+    index.ts
+    manifest.react.json
+```
+
+The `react` target consumes the same normalized COX document model used by the JSON target and emits framework-neutral TSX stubs. COX v1.0 does not require the compiler to infer concrete CSS values or executable interaction logic from prose-only layout and evidence sections.
+
+The `package` target emits a deterministic ZIP archive from manifest-referenced source files and any generated outputs produced earlier in the same compilation pass. Package archives must use project-relative paths under a single archive root, sorted file ordering, fixed ZIP timestamps, and SHA-256 records for every packaged file. Local caches, virtual environments, raw intake ZIPs, and package output directories must not be included.
+
+Guide and skill bundle intake is intentionally explicit. The compiler supports `GuideDocs` and `SkillBundles`, but ZIP attachments must be inspected and curated before their paths are added to the manifest.
+
+## 9. Editor Support
+
+COX editor support should register `.cox` as its own language id and may initially inherit YAML-compatible tokenization. Header keys such as `CoxVersion`, `FileType`, `Slug`, and `Schema` should be highlighted distinctly.
+
+## 10. Compatibility
+
+COX v1.0 is compatible with YAML tooling that preserves mappings, lists, strings, and nested objects. COX-specific validity is determined by COX schemas rather than YAML parsing alone.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charbel Malo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,192 @@
+# COX Protocol Package
+
+COX is a versioned, YAML-compatible file format for UI reconstruction, evidence tracking, component binding, implementation guidance, and agent-readable design specifications.
+
+This repository now treats `.cox` as a real format surface rather than renamed text files. COX v1.0 includes:
+
+- 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
+
+## COX v1.0
+
+- 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"
+```
+
+## Repository Contents
+
+- `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
+
+## Commands
+
+Install the toolchain:
+
+```bash
+python -m pip install -e .
+```
+
+Validate a COX project:
+
+```bash
+cox validate .
+```
+
+Compile a COX project to normalized JSON:
+
+```bash
+cox compile . --out build
+```
+
+Compile React stubs from the same normalized COX document model:
+
+```bash
+cox compile . --target react --out build
+```
+
+Compile multiple targets in one pass:
+
+```bash
+cox compile . --target json --target react --target package --out build
+```
+
+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.
+
+## Build Output
+
+Compilation emits:
+
+```text
+build/
+  manifest.compiled.json
+  normalized/
+  reports/
+    verification_report.txt
+  package/
+    cox_protocol_package_corrected.zip
+    cox_protocol_package_corrected.manifest.json
+```
+
+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.
+
+Current imported content:
+
+- `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`.
+
+Use this intake flow for future ZIP files:
+
+```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
+npm pack
+npm install -g ./cox-protocol-package-1.0.0.tgz
+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
+```
+
+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.
+
+## Example Layout
+
+```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
+```
+
+The formal COX rules live in `COX_FILE_FORMAT_SPECIFICATION_v1.0.md`, and the executable contract lives in the schema files under `schemas/`.

package/bin/cox-protocol.js

@@ -0,0 +1,57 @@
+#!/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 dependencyCheck = spawnSync(
+  python,
+  ["-c", "import typer, yaml, jsonschema, rich"],
+  {
+    cwd: process.cwd(),
+    env: pythonEnv,
+    stdio: "pipe",
+  },
+);
+
+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);

package/editor-support/vscode/.vscodeignore

@@ -0,0 +1,9 @@
+dist/**
+*.vsix
+.DS_Store
+node_modules/**
+*.log
+.github/**
+coverage/**
+**/*.test.ts
+**/*.map

package/editor-support/vscode/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 1.1.0
+
+- Added installable extension metadata for COX Language Support
+- Added COX authoring snippets for all primary document types
+- Improved COX keyword highlighting while preserving YAML-derived tokenization
+- Documented local VSIX packaging workflow
+
+## 1.0.0
+
+- Initial language registration, configuration, and basic grammar scaffold

package/editor-support/vscode/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charbel Malo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/editor-support/vscode/README.md

@@ -0,0 +1,32 @@
+# COX Language Support
+
+COX Language Support adds syntax highlighting, editor configuration, and authoring snippets for `.cox` files.
+
+## Features
+
+- Dedicated `cox` language registration for `.cox`
+- YAML-derived tokenization via `source.yaml` grammar inclusion
+- COX header highlighting for versioned metadata fields
+- Authoring snippets for manifest, page, component, protocol, and crop metadata documents
+- Installable VSIX packaging surface for local use or Marketplace preparation
+
+## Included Snippets
+
+- `cox-header`: common COX header
+- `cox-manifest`: manifest skeleton
+- `cox-page`: page spec skeleton
+- `cox-component`: component spec skeleton
+- `cox-protocol`: protocol doc skeleton
+- `cox-crop`: crop metadata skeleton
+
+## Packaging
+
+Create a local VSIX package from this folder:
+
+```bash
+vsce package --out ../../build/vscode/cox-language-support-1.1.0.vsix
+```
+
+## Notes
+
+COX inherits YAML-like syntax highlighting through TextMate grammar inclusion, but native VS Code contribution points do not provide full JSON Schema validation for custom YAML-compatible languages. Schema validation remains available through the repository CLI and bundled schema files in the main COX project.

package/editor-support/vscode/language-configuration.json

@@ -0,0 +1,47 @@
+{
+  "comments": {
+    "lineComment": "#"
+  },
+  "brackets": [
+    [
+      "{",
+      "}"
+    ],
+    [
+      "[",
+      "]"
+    ]
+  ],
+  "autoClosingPairs": [
+    {
+      "open": "{",
+      "close": "}"
+    },
+    {
+      "open": "[",
+      "close": "]"
+    },
+    {
+      "open": "\"",
+      "close": "\""
+    }
+  ],
+  "surroundingPairs": [
+    [
+      "{",
+      "}"
+    ],
+    [
+      "[",
+      "]"
+    ],
+    [
+      "\"",
+      "\""
+    ]
+  ],
+  "indentationRules": {
+    "increaseIndentPattern": "^.*:\\s*$",
+    "decreaseIndentPattern": "^\\s*[\\]}].*$"
+  }
+}