@nexart/cli 0.2.2 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
-# @nexart/cli v0.2.2
+# @nexart/cli v0.3.0
 
-Command-line interface for NexArt CodeMode — run, replay, and verify deterministic generative art.
+Command-line interface for NexArt — run, replay, and verify deterministic generative art, plus AI execution certification commands.
 
 ## Installation
 
@@ -12,6 +12,57 @@ npm install -g @nexart/cli
 nexart run sketch.js --seed 12345
 ```
 
+## Quickstart: Run an Example
+
+The SDK includes example sketches in the `examples/` folder:
+
+```bash
+# 1. Set up authentication
+export NEXART_RENDERER_ENDPOINT=https://nexart-canonical-renderer-production.up.railway.app
+export NEXART_API_KEY=nx_live_your_key_here
+
+# 2. Run the main example sketch (outputs to current directory)
+npx @nexart/cli run ./examples/sketch.js --seed 12345 --include-code --out ./out.png
+# Creates: ./out.png and ./out.snapshot.json
+
+# 3. Verify the output is deterministic
+npx @nexart/cli verify ./out.snapshot.json
+# Output: [nexart] Result: PASS
+```
+
+### Output Files
+
+When you run with `--out ./out.png`, the CLI creates:
+- `./out.png` — The rendered PNG image
+- `./out.snapshot.json` — Snapshot for replay/verify
+
+### Example Sketches
+
+| File | Description |
+|------|-------------|
+| `examples/sketch.js` | Main example — VAR controls + random palette, protocol-safe |
+| `examples/sketch-minimal.js` | Simple shapes, no randomness — identical output every run |
+| `examples/sketch-vars.js` | Uses VAR + random() — demonstrates determinism with same seed |
+
+## Canonical Size
+
+The canonical renderer enforces a fixed canvas size:
+
+| Property | Value |
+|----------|-------|
+| Width | 1950 |
+| Height | 2400 |
+
+**Important:** Do not pass custom `--width` or `--height` to the canonical renderer endpoint. The canonical size is enforced server-side for consistent, verifiable output.
+
+```bash
+# Correct: use default canonical size
+nexart run sketch.js --seed 12345
+
+# Avoid: custom sizes may be rejected by canonical renderer
+# nexart run sketch.js --width 800 --height 600  # NOT recommended
+```
+
 ## Quick Start (npx)
 
 Run without installing globally:
@@ -25,14 +76,11 @@ npx @nexart/cli replay out.snapshot.json --out replay.png
 
 ## Overview
 
-The CLI renders Code Mode sketches via a **remote canonical renderer** and creates verifiable snapshots.
+The CLI has two command groups:
+
+**Code Mode commands** — render generative art sketches, create verifiable snapshots, replay and verify them.
 
-**v0.2.2 features:**
-- Authenticated remote rendering with API keys
-- Real PNG output via remote renderer
-- Snapshot v1 format with SHA-256 hashing
-- Verify and replay commands
-- Optional code embedding in snapshots
+**AI certification commands** — create, certify, and verify tamper-evident Canonical Execution Records (CERs) for AI operations via the NexArt node API.
 
 ## Authentication
 
@@ -46,7 +94,7 @@ export NEXART_RENDERER_ENDPOINT=https://nexart-canonical-renderer-production.up.
 export NEXART_API_KEY=nx_live_your_key_here
 
 # Run with authentication
-npx @nexart/cli@0.2.2 run sketch.js --seed 12345 --include-code --out out.png
+npx @nexart/cli run sketch.js --seed 12345 --include-code --out out.png
 ```
 
 ### API Key Options
@@ -71,7 +119,7 @@ If authentication fails:
 
 ## Commands
 
-### Run
+### run
 
 Execute a sketch and create a snapshot:
 
@@ -92,8 +140,8 @@ nexart run sketch.js --renderer local
 | `--out, -o` | out.png | Output PNG path |
 | `--seed, -s` | random | PRNG seed |
 | `--vars, -v` | 0,0,0,0,0,0,0,0,0,0 | VAR values (comma-separated) |
-| `--width, -w` | 1950 | Canvas width |
-| `--height` | 2400 | Canvas height |
+| `--width, -w` | 1950 | Canvas width (use default for canonical) |
+| `--height` | 2400 | Canvas height (use default for canonical) |
 | `--renderer` | remote | `remote` or `local` |
 | `--endpoint` | env/localhost:5000 | Remote renderer URL |
 | `--api-key` | env | API key for authentication |
@@ -104,7 +152,7 @@ nexart run sketch.js --renderer local
 - `render.png` — The rendered image
 - `render.snapshot.json` — Snapshot for replay/verify
 
-### Verify
+### verify
 
 Check that a snapshot produces the expected output:
 
@@ -119,7 +167,7 @@ nexart verify render.snapshot.json --code sketch.js
 - `0` — PASS (hashes match)
 - `1` — FAIL (hashes differ or error)
 
-### Replay
+### replay
 
 Re-execute from a snapshot:
 
@@ -130,6 +178,165 @@ nexart replay render.snapshot.json --out replay.png
 nexart replay render.snapshot.json --code sketch.js --out replay.png
 ```
 
+---
+
+## AI Certification Commands (`nexart ai`)
+
+These commands interact with the NexArt node API to manage Canonical Execution Records (CERs) for AI operations. CERs are tamper-evident bundles that cryptographically certify an AI execution (input, output, model, parameters).
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `NEXART_NODE_ENDPOINT` | NexArt node API URL (default: `https://node.nexart.art`) |
+| `NEXART_API_KEY` | Shared API key for authenticated requests |
+
+### `nexart ai create`
+
+Create a CER bundle from an AI execution record.
+
+```bash
+# From file
+nexart ai create execution.json
+
+# From stdin
+cat execution.json | nexart ai create
+
+# With explicit endpoint and API key
+nexart ai create execution.json \
+  --endpoint https://node.nexart.art \
+  --api-key nx_live_...
+
+# Save to file
+nexart ai create execution.json --out cer.json
+```
+
+**Input format** (JSON file or stdin):
+```json
+{
+  "executionId": "exec-001",
+  "provider": "openai",
+  "model": "gpt-4o",
+  "input": "What is 2+2?",
+  "output": "4",
+  "parameters": { "temperature": 0 }
+}
+```
+
+**Output:** CER bundle JSON printed to stdout (or saved via `--out`).
+
+**Options:**
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--endpoint` | env/`https://node.nexart.art` | NexArt node URL |
+| `--api-key` | env | API key |
+| `--out` | stdout | Save bundle to file |
+
+**Exit codes:**
+- `0` — Success
+- `1` — API error or missing input
+
+### `nexart ai certify`
+
+Certify an AI execution and receive an attested CER bundle. The node API signs the bundle and attaches an attestation.
+
+```bash
+# From file
+nexart ai certify execution.json
+
+# From stdin
+cat execution.json | nexart ai certify
+
+# JSON output (machine-readable)
+nexart ai certify execution.json --json
+
+# Save output
+nexart ai certify execution.json --out certified.json
+```
+
+**Default output:**
+```
+[nexart] CER certified successfully
+bundleType : cer.ai.execution.v1
+hash       : sha256:a1b2c3...
+attestation: present
+```
+
+**JSON output** (`--json`):
+```json
+{
+  "ok": true,
+  "bundleType": "cer.ai.execution.v1",
+  "certificateHash": "sha256:a1b2c3...",
+  "hasAttestation": true,
+  "bundle": { ... }
+}
+```
+
+**Options:**
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--endpoint` | env/`https://node.nexart.art` | NexArt node URL |
+| `--api-key` | env | API key |
+| `--out` | stdout | Save bundle to file |
+| `--json` | false | Machine-readable JSON output |
+
+**Exit codes:**
+- `0` — Certified successfully
+- `1` — API error (e.g. 401 Unauthorized), missing input, or invalid response
+
+### `nexart ai verify`
+
+Verify a CER bundle locally. No network call — computes and compares the `certificateHash` against the bundle contents.
+
+```bash
+# From file
+nexart ai verify cer.json
+
+# From stdin
+cat cer.json | nexart ai verify
+
+# JSON output
+nexart ai verify cer.json --json
+```
+
+**Default output (PASS):**
+```
+[nexart] CER verification: PASS
+bundleType : cer.ai.execution.v1
+hash       : sha256:a1b2c3...
+attestation: present
+```
+
+**Default output (FAIL):**
+```
+[nexart] CER verification: FAIL
+reason     : hash mismatch
+expected   : sha256:a1b2c3...
+computed   : sha256:d4e5f6...
+```
+
+**JSON output** (`--json`):
+```json
+{
+  "ok": true,
+  "bundleType": "cer.ai.execution.v1",
+  "certificateHash": "sha256:a1b2c3...",
+  "hasAttestation": true
+}
+```
+
+**Options:**
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--json` | false | Machine-readable JSON output |
+
+**Exit codes:**
+- `0` — PASS (hash matches)
+- `1` — FAIL (hash mismatch or invalid bundle)
+
+---
+
 ## Remote Renderer
 
 The CLI calls a canonical Node.js renderer endpoint for real PNG generation.
@@ -172,7 +379,7 @@ Headers:
 curl -X POST https://nexart-canonical-renderer-production.up.railway.app/api/render \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer nx_live_..." \
-  -d '{"code":"createCanvas(400,400);\nbackground(0);\n","seed":12345,"VAR":[0,0,0,0,0,0,0,0,0,0],"width":400,"height":400,"protocolVersion":"1.2.0"}' \
+  -d '{"code":"createCanvas(1950,2400);\nbackground(0);\n","seed":12345,"VAR":[0,0,0,0,0,0,0,0,0,0],"width":1950,"height":2400,"protocolVersion":"1.2.0"}' \
   --output render.png
 ```
 
@@ -221,7 +428,8 @@ Real local/offline rendering is planned for a future release.
 | Variable | Description |
 |----------|-------------|
 | `NEXART_RENDERER_ENDPOINT` | Remote renderer URL (default: http://localhost:5000) |
-| `NEXART_API_KEY` | API key for authenticated rendering |
+| `NEXART_NODE_ENDPOINT` | NexArt node API URL (default: https://node.nexart.art) |
+| `NEXART_API_KEY` | API key for authenticated requests |
 
 ## License
 

package/dist/__tests__/ai.test.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @nexart/cli v0.3.0 — AI command tests
+ *
+ * Tests:
+ * A) canonicalJson + computeBundleHash (unit)
+ * B) readInputJson — file input
+ * C) readInputJson — stdin input
+ * D) aiCreateCommand — request/response
+ * E) aiCertifyCommand — summary output
+ * F) aiCertifyCommand — --json output
+ * G) aiVerifyCommand — PASS
+ * H) aiVerifyCommand — FAIL (tampered hash)
+ * I) aiVerifyCommand — FAIL (wrong bundleType)
+ * J) aiVerifyCommand — attestation present/absent
+ * K) aiVerifyCommand — --json output
+ * L) backward compat — Code Mode exports exist
+ * M) callNodeApi — sets Authorization header and sends body
+ * N) aiCreateCommand — stdin input
+ * O) aiCertifyCommand — stdin input
+ * P) aiCreateCommand — saves --out file
+ * Q) aiCertifyCommand — 401 handling
+ */
+export {};
+//# sourceMappingURL=ai.test.d.ts.map

package/dist/__tests__/ai.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/ai.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG"}