cox-protocol-package 1.0.0

package/editor-support/vscode/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "cox-language-support",
+  "displayName": "COX Language Support",
+  "description": "Syntax highlighting, snippets, and packaging support for COX files.",
+  "version": "1.1.0",
+  "publisher": "charbelmalo",
+  "license": "MIT",
+  "preview": true,
+  "markdown": "github",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/charbelmalo/cox-protocol-package.git"
+  },
+  "homepage": "https://github.com/charbelmalo/cox-protocol-package#readme",
+  "bugs": {
+    "url": "https://github.com/charbelmalo/cox-protocol-package/issues"
+  },
+  "engines": {
+    "vscode": "^1.90.0"
+  },
+  "categories": [
+    "Programming Languages",
+    "Snippets"
+  ],
+  "keywords": [
+    "cox",
+    "yaml",
+    "design-spec",
+    "ui-spec",
+    "component-spec",
+    "agent-readable"
+  ],
+  "scripts": {
+    "package": "vsce package --out ../../build/vscode/cox-language-support-1.1.0.vsix"
+  },
+  "contributes": {
+    "languages": [
+      {
+        "id": "cox",
+        "aliases": [
+          "COX",
+          "cox"
+        ],
+        "extensions": [
+          ".cox"
+        ],
+        "configuration": "./language-configuration.json"
+      }
+    ],
+    "grammars": [
+      {
+        "language": "cox",
+        "scopeName": "source.cox",
+        "path": "./syntaxes/cox.tmLanguage.json"
+      }
+    ],
+    "snippets": [
+      {
+        "language": "cox",
+        "path": "./snippets/cox-common.json"
+      },
+      {
+        "language": "cox",
+        "path": "./snippets/cox-manifest.json"
+      },
+      {
+        "language": "cox",
+        "path": "./snippets/cox-page.json"
+      },
+      {
+        "language": "cox",
+        "path": "./snippets/cox-component.json"
+      },
+      {
+        "language": "cox",
+        "path": "./snippets/cox-protocol.json"
+      },
+      {
+        "language": "cox",
+        "path": "./snippets/cox-crop-metadata.json"
+      }
+    ],
+    "configurationDefaults": {
+      "[cox]": {
+        "editor.insertSpaces": true,
+        "editor.tabSize": 2
+      }
+    }
+  }
+}

package/editor-support/vscode/snippets/cox-common.json

@@ -0,0 +1,12 @@
+{
+  "COX Header": {
+    "prefix": "cox-header",
+    "body": [
+      "CoxVersion: \"1.0\"",
+      "FileType: \"${1|manifest,page_spec,component_spec,protocol_doc,crop_metadata|}\"",
+      "Slug: \"${2:my_slug}\"",
+      "Schema: \"${3|cox.manifest.v1,cox.page.v1,cox.component.v1,cox.protocol.v1,cox.crop_metadata.v1|}\""
+    ],
+    "description": "Insert the common COX v1.0 document header"
+  }
+}

package/editor-support/vscode/snippets/cox-component.json

@@ -0,0 +1,41 @@
+{
+  "COX Component Spec": {
+    "prefix": "cox-component",
+    "body": [
+      "CoxVersion: \"1.0\"",
+      "FileType: \"component_spec\"",
+      "ComponentName: \"${1:projects_grid_cards}\"",
+      "Slug: \"${1:projects_grid_cards}\"",
+      "Schema: \"cox.component.v1\"",
+      "Role: \"${2:Describe the component role}\"",
+      "EvidenceSummary:",
+      "  Visible: []",
+      "  UserSpecified: []",
+      "  Inferred: []",
+      "  Intended: []",
+      "  Recommended: []",
+      "NamingDecision:",
+      "  ChosenName: \"${1:projects_grid_cards}\"",
+      "  Reason: \"${3:Reason for the component name}\"",
+      "  RejectedAlternatives: []",
+      "  AmbiguityRisk: \"Low\"",
+      "  EvidenceLevel: \"UserSpecified\"",
+      "VisibleStructure:",
+      "  Regions: []",
+      "VisualStyle:",
+      "  Tokens: []",
+      "Interactions:",
+      "  Visible: []",
+      "  Inferred: []",
+      "  Intended: []",
+      "  Recommended: []",
+      "Responsive:",
+      "  Desktop: \"\"",
+      "  Tablet: \"\"",
+      "  Mobile: \"\"",
+      "ImplementationHints: []",
+      "ChildSubcomponents: []"
+    ],
+    "description": "Insert a COX component specification skeleton"
+  }
+}

package/editor-support/vscode/snippets/cox-crop-metadata.json

@@ -0,0 +1,23 @@
+{
+  "COX Crop Metadata": {
+    "prefix": "cox-crop",
+    "body": [
+      "CoxVersion: \"1.0\"",
+      "FileType: \"crop_metadata\"",
+      "Slug: \"${1:component_crop_metadata}\"",
+      "Schema: \"cox.crop_metadata.v1\"",
+      "SourceScreenshot: \"${2:dashboard_screenshot.png}\"",
+      "OutputScreenshot: \"${3:component_screenshot.png}\"",
+      "BoundaryConfidence: \"${4|High,Medium,Low|}\"",
+      "EstimatedBoundingBox:",
+      "  Unit: \"${5|px,percent|}\"",
+      "  X: \"\"",
+      "  Y: \"\"",
+      "  Width: \"\"",
+      "  Height: \"\"",
+      "IncludedPaddingReason: \"${6:Preserve visible shadow and edge spacing}\"",
+      "ExcludedRegions: []"
+    ],
+    "description": "Insert a COX crop metadata skeleton"
+  }
+}

package/editor-support/vscode/snippets/cox-manifest.json

@@ -0,0 +1,39 @@
+{
+  "COX Manifest": {
+    "prefix": "cox-manifest",
+    "body": [
+      "CoxVersion: \"1.0\"",
+      "FileType: \"manifest\"",
+      "Slug: \"${1:project_slug}\"",
+      "Schema: \"cox.manifest.v1\"",
+      "ProjectName: \"${2:ProjectName}\"",
+      "PackageName: \"${3:project.zip}\"",
+      "ProtocolExtension: \".cox\"",
+      "MimeType: \"application/vnd.cox+yaml\"",
+      "Encoding: \"UTF-8\"",
+      "SyntaxBase: \"YAML-compatible structured text\"",
+      "EntryPoint: \"manifest.cox\"",
+      "ReferenceDocs:",
+      "  - \"README.md\"",
+      "ProtocolDocs:",
+      "  - \"${4:protocols/example_protocol.cox}\"",
+      "Schemas:",
+      "  - \"schemas/cox.manifest.v1.schema.json\"",
+      "ToolingFiles:",
+      "  - \"tools/cox_cli.py\"",
+      "Pages:",
+      "  - PageName: \"${5:Dashboard}\"",
+      "    Slug: \"${6:dashboard}\"",
+      "    Folder: \"${7:LocalAppManager/Dashboard}\"",
+      "    PageInstruction: \"${8:LocalAppManager/Dashboard/dashboard.cox}\"",
+      "    PageScreenshotPlaceholder: \"${9:LocalAppManager/Dashboard/dashboard_screenshot.placeholder.txt}\"",
+      "    Components: []",
+      "BuildTargets:",
+      "  - \"json\"",
+      "  - \"react\"",
+      "VerificationRules:",
+      "  - \"${10:Validation must parse YAML, apply JSON Schema, and check referenced paths.}\""
+    ],
+    "description": "Insert a COX manifest skeleton"
+  }
+}

package/editor-support/vscode/snippets/cox-page.json

@@ -0,0 +1,44 @@
+{
+  "COX Page Spec": {
+    "prefix": "cox-page",
+    "body": [
+      "CoxVersion: \"1.0\"",
+      "FileType: \"page_spec\"",
+      "PageName: \"${1:Dashboard}\"",
+      "Slug: \"${2:dashboard}\"",
+      "Schema: \"cox.page.v1\"",
+      "ProjectName: \"${3:LocalAppManager}\"",
+      "PageType: \"${4:dashboard_overview}\"",
+      "EvidenceSummary:",
+      "  Visible: []",
+      "  UserSpecified: []",
+      "  Inferred: []",
+      "  Intended: []",
+      "  Recommended: []",
+      "VisibleStructure:",
+      "  Regions: []",
+      "NamingDecision:",
+      "  ChosenName: \"${1:Dashboard}\"",
+      "  Reason: \"${5:Reason for the page name}\"",
+      "  RejectedAlternatives: []",
+      "  AmbiguityRisk: \"Low\"",
+      "  EvidenceLevel: \"UserSpecified\"",
+      "Layout:",
+      "  Desktop: \"\"",
+      "  Tablet: \"\"",
+      "  Mobile: \"\"",
+      "Children:",
+      "  Components: []",
+      "Interactions:",
+      "  Visible: []",
+      "  Inferred: []",
+      "  Intended: []",
+      "  Recommended: []",
+      "RecursiveDecompositionDecision:",
+      "  Complexity: \"ModeratePage\"",
+      "  Reason: \"\"",
+      "  Action: \"\""
+    ],
+    "description": "Insert a COX page specification skeleton"
+  }
+}

package/editor-support/vscode/snippets/cox-protocol.json

@@ -0,0 +1,16 @@
+{
+  "COX Protocol Doc": {
+    "prefix": "cox-protocol",
+    "body": [
+      "CoxVersion: \"1.0\"",
+      "FileType: \"protocol_doc\"",
+      "Slug: \"${1:protocol_slug}\"",
+      "Schema: \"cox.protocol.v1\"",
+      "ProtocolName: \"${2:Protocol Name}\"",
+      "Purpose: \"${3:Describe the protocol purpose}\"",
+      "${4:SectionName}:",
+      "  ${5:Key}: \"${6:Value}\""
+    ],
+    "description": "Insert a COX protocol document skeleton"
+  }
+}

package/editor-support/vscode/syntaxes/cox.tmLanguage.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://raw.githubusercontent.com/martinring/tmlanguage/master/tmlanguage.json",
+  "name": "COX",
+  "scopeName": "source.cox",
+  "patterns": [
+    {
+      "match": "^(CoxVersion|FileType|Slug|Schema|PageName|ProjectName|ComponentName|ProtocolName|MimeType|Encoding|SyntaxBase|EntryPoint)(?=:\\s)",
+      "name": "keyword.control.cox"
+    },
+    {
+      "match": "^(EvidenceSummary|VisibleStructure|Interactions|NamingDecision|Layout|Children|Responsive|VisualStyle|ImplementationHints|BuildTargets|VerificationRules|ReferenceDocs|ProtocolDocs|Schemas|ToolingFiles)(?=:\\s)",
+      "name": "entity.name.section.cox"
+    },
+    {
+      "match": "\b(manifest|page_spec|component_spec|protocol_doc|crop_metadata)\b",
+      "name": "storage.type.cox"
+    },
+    {
+      "match": "\bcox\\.(manifest|page|component|protocol|crop_metadata)\\.v1\b",
+      "name": "support.type.schema.cox"
+    },
+    {
+      "match": "\b(Visible|UserSpecified|Inferred|Intended|Recommended|High|Medium|Low)\b",
+      "name": "constant.language.cox"
+    },
+    {
+      "include": "source.yaml"
+    }
+  ]
+}

package/guides/imported-packages/cox_protocol_package_compiled.md

@@ -0,0 +1,32 @@
+# Imported Package Audit: cox_protocol_package_compiled.zip
+
+## Classification
+
+`cox_protocol_package_compiled.zip` is a legacy compiled/source snapshot of this same COX protocol package. Its contents overlap with the current repository: sample `LocalAppManager` COX files, root protocol `.cox` files, templates, `README.md`, `manifest.cox`, `verification_report.txt`, and `zip_content_listing.txt`.
+
+## Intake Decision
+
+The archive was inspected and staged before any merge. No unsafe absolute paths or `..` traversal entries were found.
+
+The archive was not extracted into the live source tree because its `.cox` protocol files use the older pre-COX-v1 header shape and would conflict with the current `protocols/` layout, schema validation, compiler targets, NPM metadata, and deterministic package emitter.
+
+Current live files are newer and supersede the snapshot. The correct action is to keep this audit note as provenance and continue using the upgraded package source.
+
+## Archive Contents Summary
+
+- `LocalAppManager/Dashboard/**`: sample page and component specs with screenshot placeholders.
+- Root protocol docs: legacy versions of the protocol `.cox` files now stored under `protocols/`.
+- `templates/`: page, component, and crop metadata templates.
+- Root docs: `README.md`, `verification_report.txt`, and `zip_content_listing.txt`.
+- `manifest.cox`: legacy package manifest shape.
+
+## Cross-Examination Result
+
+- Current package target is implemented in `tools/package_target.py`; the archive only documents a package expectation.
+- Current manifest supports `GuideDocs`, `SkillBundles`, and `BuildTargets` values `json`, `react`, and `package`.
+- Current protocol docs include COX v1.0 headers and schema ids; the archive's legacy protocol docs do not.
+- Current build emits normalized protocol outputs under `build/normalized/protocols/`; the archive predates that grouping.
+
+## Status
+
+Accepted as an audited legacy source snapshot. No live source overwrite was performed.

package/guides/npm-installation.md

@@ -0,0 +1,296 @@
+# Publishing And Installing COX With NPM
+
+This package ships an NPM command named `cox-protocol`. The command delegates to the Python COX CLI bundled in the package, so target machines need both Node.js and Python.
+
+If the target machine has multiple Python installations, set `COX_PYTHON` to the interpreter that has the COX dependencies installed.
+
+> Note: This NPM package installs the `cox-protocol` command wrapper and the COX package files. The target machine must also have Python 3.10+ and the required Python packages:
+>
+> ```bash
+> python3 -m pip install PyYAML jsonschema typer rich
+> ```
+>
+> Optional when you need to force a specific interpreter:
+>
+> ```bash
+> export COX_PYTHON=/path/to/python
+> ```
+
+## Prerequisites
+
+- Node.js 18 or newer
+- Python 3.10 or newer
+- `pip` available for the Python interpreter you want COX to use
+- An npm account with two-factor authentication or an appropriate granular publishing token
+
+## Check `package.json`
+
+Run all publishing commands from the repository root folder that contains `package.json`.
+
+The publish metadata should include:
+
+```json
+{
+  "name": "cox-protocol-package",
+  "version": "1.0.0",
+  "description": "NPM wrapper and distribution package for the COX protocol CLI.",
+  "license": "MIT",
+  "bin": {
+    "cox-protocol": "./bin/cox-protocol.js"
+  },
+  "files": [
+    "bin",
+    "COX_FILE_FORMAT_SPECIFICATION_v1.0.md",
+    "LICENSE",
+    "README.md",
+    "guides",
+    "manifest.cox",
+    "protocols",
+    "pyproject.toml",
+    "requirements.txt",
+    "schemas",
+    "skills",
+    "templates",
+    "tools"
+  ]
+}
+```
+
+The `bin` field makes `cox-protocol` available after a global install. The wrapper file must be executable and start with a Node shebang:
+
+```bash
+chmod +x bin/cox-protocol.js
+head -n 1 bin/cox-protocol.js
+```
+
+Expected first line:
+
+```text
+#!/usr/bin/env node
+```
+
+## Check Package Name Availability
+
+Unscoped npm package names are public and globally unique. Check the current package name:
+
+```bash
+npm view cox-protocol-package
+```
+
+If npm returns package info, the name is already taken. If it returns a 404, the name can be used.
+
+As of the last local check for this package, both `cox-protocol-package` and `cox-protocol` returned no package version from `npm view`, so either name appeared available. Recheck immediately before publishing because npm names can be claimed at any time.
+
+A shorter public name may be better if it is available:
+
+```bash
+npm view cox-protocol
+```
+
+If `cox-protocol` is available and you want that name, update `package.json` before publishing:
+
+```json
+{
+  "name": "cox-protocol"
+}
+```
+
+Then users install:
+
+```bash
+npm install -g cox-protocol
+```
+
+## Log In To NPM
+
+Create an npm account, then log in:
+
+```bash
+npm login
+npm whoami
+```
+
+If your account has 2FA enabled, expect an OTP prompt during login or publish. For CI, use a granular npm token with publish permissions.
+
+## Preview The Published Contents
+
+Run a dry run first:
+
+```bash
+npm pack --dry-run
+```
+
+Then create and inspect the actual tarball:
+
+```bash
+npm pack
+tar -tzf cox-protocol-package-1.0.0.tgz
+```
+
+Confirm the tarball includes:
+
+- `package.json`
+- `README.md`
+- `bin/cox-protocol.js`
+- `tools/` Python CLI files
+- `schemas/`, `protocols/`, `templates/`, `guides/`, and `skills/`
+
+Confirm it does not include:
+
+- secrets or `.env` files
+- `.venv/`
+- `.git/`
+- `node_modules/`
+- `__pycache__/` or `*.pyc`
+- generated tarballs or raw intake ZIPs
+- unrelated build or test artifacts
+
+## Test The Tarball Locally
+
+From another temporary folder:
+
+```bash
+npm install -g /path/to/cox-protocol-package-1.0.0.tgz
+python3 -m pip install PyYAML jsonschema typer rich
+cox-protocol --help
+```
+
+Then test a real COX project:
+
+```bash
+cd /path/to/cox/project
+cox-protocol validate .
+cox-protocol compile . --target json --target react --target package --out build
+```
+
+## Publish To NPM
+
+For an unscoped public package such as `cox-protocol-package`:
+
+```bash
+npm publish
+```
+
+NPM publishes unscoped packages to the public registry by default. Publishing fails if the same package name and version already exists. Once a version is published, that exact version cannot be reused, even if it is later unpublished.
+
+For a scoped package, such as `@charbel/cox-protocol`, the first public publish must include `--access public`:
+
+```bash
+npm publish --access public
+```
+
+Scoped packages are not public by default on initial publish.
+
+## Verify Public Installation
+
+After publishing:
+
+```bash
+npm view cox-protocol-package
+npm install -g cox-protocol-package
+cox-protocol --help
+```
+
+Then verify a real project:
+
+```bash
+python3 -m pip install PyYAML jsonschema typer rich
+cd /path/to/cox/project
+cox-protocol validate .
+cox-protocol compile . --target json --target react --target package --out build
+```
+
+## Install From NPM After Publication
+
+```bash
+npm install -g cox-protocol-package
+python3 -m pip install PyYAML jsonschema typer rich
+```
+
+Then validate a COX project:
+
+```bash
+cd /path/to/cox/project
+cox-protocol validate .
+cox-protocol compile . --target json --target react --target package --out build
+```
+
+## Install From A Local NPM Tarball
+
+On the development machine, create the tarball:
+
+```bash
+npm pack
+```
+
+Copy `cox-protocol-package-1.0.0.tgz` to the other device, then install it there:
+
+```bash
+npm install -g ./cox-protocol-package-1.0.0.tgz
+python3 -m pip install PyYAML jsonschema typer rich
+```
+
+Run the same smoke test from any COX project folder:
+
+```bash
+cox-protocol validate .
+cox-protocol compile . --target json --target react --target package --out build
+```
+
+## Use A Specific Python Interpreter
+
+If the device has multiple Python installations, set `COX_PYTHON`:
+
+```bash
+COX_PYTHON=/path/to/python3 cox-protocol validate .
+```
+
+For a virtual environment:
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install PyYAML jsonschema typer rich
+COX_PYTHON="$PWD/.venv/bin/python" cox-protocol validate .
+```
+
+## Publish Updates Later
+
+Every new publish needs a new version:
+
+```bash
+npm version patch
+npm publish
+```
+
+For larger changes:
+
+```bash
+npm version minor
+npm publish
+```
+
+or:
+
+```bash
+npm version major
+npm publish
+```
+
+## Minimum Manual Publish Sequence
+
+```bash
+npm login
+npm whoami
+npm pack --dry-run
+npm pack
+npm install -g ./cox-protocol-package-1.0.0.tgz
+python3 -m pip install PyYAML jsonschema typer rich
+cox-protocol --help
+npm publish
+npm view cox-protocol-package
+```
+
+## Current Limitation
+
+The NPM package is a distribution wrapper, not a TypeScript-native compiler. Python dependencies must be installed separately until the compiler is ported to Node.js or the NPM package gains an installer that manages the Python environment.