cox-protocol-package 1.0.2 → 1.2.0

package/guides/npm-installation.md

@@ -1,296 +1,25 @@
-# Publishing And Installing COX With NPM
+# Installing the npm wrapper
 
-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.
+The npm package ships the same Python compiler and schema resources. It requires Node 18+, Python 3.9+, and the Python dependencies in the interpreter selected by `COX_PYTHON`. It never installs Python packages automatically.
 
-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.9+ 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.9 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.1",
-  "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.
-
-For this repository, `cox-protocol-package` is already in use. That is expected once the package has been published. For updates, keep the name and publish a new version.
-
-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:
+For the local 1.2.0 release artifacts on macOS/Linux:
 
 ```bash
-npm pack
-tar -tzf cox-protocol-package-<version>.tgz
+python3 -m venv .cox-venv
+.cox-venv/bin/python -m pip install /path/to/cox_protocol_package-1.2.0-py3-none-any.whl
+export COX_PYTHON="$PWD/.cox-venv/bin/python"
+npm install --prefix ./cox-tools /path/to/cox-protocol-package-1.2.0.tgz
+./cox-tools/node_modules/.bin/cox-protocol --version
+./cox-tools/node_modules/.bin/cox-protocol init my-contract --name MyProject
+./cox-tools/node_modules/.bin/cox-protocol validate my-contract --strict
+./cox-tools/node_modules/.bin/cox-protocol compile my-contract --target all --out build
+./cox-tools/node_modules/.bin/cox-protocol verify-package my-contract/build/package/myproject.zip
 ```
 
-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-<version>.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
-```
+The local npm prefix avoids changing global packages. On Windows, use the virtual environment's `Scripts/python.exe`, set `$env:COX_PYTHON`, and invoke the `.cmd` launcher from PowerShell. Windows execution is not covered by the local macOS release check.
 
-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-<version>.tgz` to the other device, then install it there:
-
-```bash
-npm install -g ./cox-protocol-package-<version>.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-<version>.tgz
-python3 -m pip install PyYAML jsonschema typer rich
-cox-protocol --help
-npm publish
-npm view cox-protocol-package
-```
+If using the npm tarball without a wheel, install its `requirements.txt` into that virtual environment using `python -m pip install -r cox-tools/node_modules/cox-protocol-package/requirements.txt`. Runtime source and canonical schemas are bundled in the npm package.
 
-## Current Limitation
+`cox-protocol --version` works without Python. Other commands explain a missing interpreter or dependencies. The wrapper removes the caller's current directory and PYTHONPATH from module resolution before loading the bundled CLI to avoid accidental module shadowing.
 
-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.
+Use a version available in the selected registry when installing by package name. Building a local 1.2.0 artifact does not publish it; see the release record for status.

package/manifest.cox

@@ -10,11 +10,12 @@ Encoding: "UTF-8"
 SyntaxBase: "YAML-compatible structured text"
 EntryPoint: "manifest.cox"
 ReferenceDocs:
+  - "CHANGELOG.md"
+  - "FINALIZATION.md"
   - "README.md"
   - "COX_FILE_FORMAT_SPECIFICATION_v1.0.md"
-  - "verification_report.txt"
-  - "zip_content_listing.txt"
 GuideDocs:
+  - "guides/contract-demo.md"
   - "guides/imported-packages/cox_protocol_package_compiled.md"
   - "guides/npm-installation.md"
 ProtocolDocs:
@@ -43,9 +44,11 @@ Schemas:
   - "schemas/cox.protocol.v1.schema.json"
   - "schemas/cox.crop_metadata.v1.schema.json"
 ToolingFiles:
+  - "cox_protocol"
+  - "scripts"
+  - "tests"
+  - "MANIFEST.in"
   - "LICENSE"
-  - ".gitignore"
-  - ".npmignore"
   - "package.json"
   - "bin/cox-protocol.js"
   - "pyproject.toml"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cox-protocol-package",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "NPM wrapper and distribution package for the COX protocol CLI.",
   "license": "MIT",
   "type": "module",
@@ -9,22 +9,32 @@
   },
   "files": [
     "bin",
-    "COX_FILE_FORMAT_SPECIFICATION_v1.0.md",
-    "LICENSE",
-    "README.md",
-    "editor-support/vscode",
+    "cox_protocol",
+    "tools",
+    "schemas",
+    "protocols",
+    "templates",
+    "examples",
     "guides",
+    "skills",
+    "editor-support/vscode",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "COX_FILE_FORMAT_SPECIFICATION_v1.0.md",
     "manifest.cox",
-    "protocols",
+    "LocalAppManager",
     "pyproject.toml",
     "requirements.txt",
-    "schemas",
-    "skills",
-    "templates",
-    "tools",
+    "FINALIZATION.md",
+    "scripts",
+    "tests",
+    "MANIFEST.in",
     "!**/__pycache__/**",
     "!**/*.pyc",
-    "!**/*.pyo"
+    "!**/.cox-build.json",
+    "!**/node_modules/**",
+    "!**/build/**"
   ],
   "keywords": [
     "cox",
@@ -43,11 +53,17 @@
     "url": "https://github.com/charbelmalo/cox-protocol-package/issues"
   },
   "scripts": {
+    "test": "python3 -m pytest",
     "pack:dry-run": "npm pack --dry-run",
-    "package:vscode": "cd editor-support/vscode && npm run package",
-    "smoke:python": "cox validate . && cox compile . --target json --target react --target package --out build"
+    "package:vscode": "npm --prefix editor-support/vscode run package",
+    "smoke:python": "python3 scripts/release_check.py"
   },
   "engines": {
     "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "@vscode/vsce": "4.0.0",
+    "typescript": "7.0.2"
   }
-}
+}

package/protocols/recursive_decomposition_protocol.cox

@@ -32,17 +32,17 @@ ComplexityLevels:
 
 DecompositionDecisionTree:
   - Question: "Can the page be explained accurately in one {page_slug}.cox without becoming long or ambiguous?"
-    Yes: "Do not split."
-    No: "Identify primary components."
+    "Yes": "Do not split."
+    "No": "Identify primary components."
   - Question: "Are component boundaries visually distinguishable?"
-    Yes: "Create component folders."
-    No: "Use {page_slug}.cox with internal regions and mark boundaries as Inferred."
+    "Yes": "Create component folders."
+    "No": "Use {page_slug}.cox with internal regions and mark boundaries as Inferred."
   - Question: "Would a component name need vague or overly specific wording to be unique?"
-    Yes: "Split or rename using purpose/domain; validate sibling names."
-    No: "Keep component as-is."
+    "Yes": "Split or rename using purpose/domain; validate sibling names."
+    "No": "Keep component as-is."
   - Question: "Does the component contain multi-layered visual logic, expandable interactions, nested states, or creative animation?"
-    Yes: "Create ComplexSubcomponentName folders."
-    No: "Keep inside component .cox."
+    "Yes": "Create ComplexSubcomponentName folders."
+    "No": "Keep inside component .cox."
 
 PageCoxResponsibility:
   Includes:

package/pyproject.toml

@@ -1,14 +1,15 @@
 [build-system]
-requires = ["setuptools>=68", "wheel"]
+requires = ["setuptools>=77", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "cox-protocol-package"
-version = "1.0.1"
+version = "1.2.0"
 description = "Validator and compiler for COX design-spec documents"
 readme = "README.md"
 requires-python = ">=3.9"
-license = { file = "LICENSE" }
+license = "MIT"
+license-files = ["LICENSE"]
 authors = [
   { name = "Charbel Malo" },
 ]
@@ -24,7 +25,6 @@ classifiers = [
   "Development Status :: 4 - Beta",
   "Environment :: Console",
   "Intended Audience :: Developers",
-  "License :: OSI Approved :: MIT License",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
@@ -41,7 +41,7 @@ dependencies = [
 ]
 
 [project.scripts]
-cox = "tools.cox_cli:app"
+cox = "cox_protocol.cox_cli:app"
 
 [project.urls]
 Homepage = "https://github.com/charbelmalo/cox-protocol-package#readme"
@@ -49,4 +49,15 @@ Repository = "https://github.com/charbelmalo/cox-protocol-package"
 Issues = "https://github.com/charbelmalo/cox-protocol-package/issues"
 
 [tool.setuptools]
-packages = ["tools"]
+packages = ["cox_protocol"]
+include-package-data = false
+
+[tool.setuptools.package-data]
+cox_protocol = ["schemas/*.json", "starter/*", "starter/page/*", "starter/page/action_button/*"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.4", "build>=1.0", "twine>=5.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

package/schemas/cox.component.v1.schema.json

@@ -99,7 +99,7 @@
           }
         }
       },
-      "additionalProperties": true
+      "additionalProperties": false
     },
     "interactionSummary": {
       "type": "object",
@@ -127,9 +127,15 @@
           "items": {
             "type": "string"
           }
+        },
+        "UserSpecified": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
         }
       },
-      "additionalProperties": true
+      "additionalProperties": false
     },
     "namingDecision": {
       "type": "object",
@@ -157,11 +163,18 @@
           "type": "string"
         },
         "EvidenceLevel": {
-          "type": "string"
+          "type": "string",
+          "enum": [
+            "Visible",
+            "UserSpecified",
+            "Inferred",
+            "Intended",
+            "Recommended"
+          ]
         }
       },
       "additionalProperties": true
     }
   },
   "additionalProperties": true
-}
+}

package/schemas/cox.crop_metadata.v1.schema.json

@@ -80,4 +80,4 @@
     }
   },
   "additionalProperties": true
-}
+}

package/schemas/cox.manifest.v1.schema.json

@@ -169,4 +169,4 @@
     }
   },
   "additionalProperties": true
-}
+}

package/schemas/cox.page.v1.schema.json

@@ -161,7 +161,7 @@
           }
         }
       },
-      "additionalProperties": true
+      "additionalProperties": false
     },
     "interactionSummary": {
       "type": "object",
@@ -189,9 +189,15 @@
           "items": {
             "type": "string"
           }
+        },
+        "UserSpecified": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
         }
       },
-      "additionalProperties": true
+      "additionalProperties": false
     },
     "namingDecision": {
       "type": "object",
@@ -219,11 +225,18 @@
           "type": "string"
         },
         "EvidenceLevel": {
-          "type": "string"
+          "type": "string",
+          "enum": [
+            "Visible",
+            "UserSpecified",
+            "Inferred",
+            "Intended",
+            "Recommended"
+          ]
         }
       },
       "additionalProperties": true
     }
   },
   "additionalProperties": true
-}
+}

package/schemas/cox.protocol.v1.schema.json

@@ -35,4 +35,4 @@
     }
   },
   "additionalProperties": true
-}
+}