@uvrn/cli 1.0.1 → 1.0.3

package/README.md

@@ -2,6 +2,8 @@
 
 Command-line interface for the UVRN Delta Engine. Transform data bundles into verifiable receipts using deterministic comparison and canonical hashing.
 
+**Disclaimer:** UVRN is in Alpha testing. The engine measures whether your sources agree with each other — not whether they’re correct. Final trust of output rests with the user. Use at your own risk. Have fun.
+
 ## Install
 
 ### Global Installation (Recommended)
@@ -10,10 +12,10 @@ Command-line interface for the UVRN Delta Engine. Transform data bundles into ve
 npm install -g @uvrn/cli
 ```
 
-After installation, the `delta-engine` command will be available globally:
+After installation, the `uvrn` command will be available globally (the `delta-engine` alias also works):
 
 ```bash
-delta-engine --version
+uvrn --version
 ```
 
 ### Local Installation
@@ -25,7 +27,7 @@ npm install @uvrn/cli
 Then use with npx:
 
 ```bash
-npx delta-engine --version
+npx uvrn --version
 ```
 
 ## Quick Start
@@ -331,6 +333,8 @@ MIT
 
 ## Links
 
+**Open source:** Source code and issues: [GitHub (uvrn-packages)](https://github.com/UVRN-org/uvrn-packages). Project landing: [UVRN](https://github.com/UVRN-org/uvrn).
+
 - [Repository](https://github.com/UVRN-org/uvrn-packages) — monorepo (this package: `uvrn-cli`)
 - [CLI Guide](docs/CLI_GUIDE.md) — full command reference
 - [@uvrn/core](https://www.npmjs.com/package/@uvrn/core) — core engine library

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@uvrn/cli",
-  "version": "1.0.1",
+  "version": "1.0.3",
+  "publishConfig": {
+    "access": "public"
+  },
   "description": "UVRN CLI — bundle to receipt",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "uvrn": "dist/cli.js"
+    "uvrn": "dist/cli.js",
+    "delta-engine": "dist/cli.js"
   },
   "keywords": [
     "uvrn",
@@ -22,7 +26,7 @@
   "homepage": "https://github.com/UVRN-org/uvrn-packages#readme",
   "dependencies": {
     "commander": "^11.1.0",
-    "@uvrn/core": "1.0.1"
+    "@uvrn/core": "^1.0.3"
   },
   "devDependencies": {
     "@types/jest": "^29.5.0",
@@ -37,6 +41,10 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "scripts": {
     "build": "tsc",
     "test": "jest",

package/docs/CLI_GUIDE.md

@@ -1,618 +0,0 @@
-# Loosechain Delta Engine CLI - Comprehensive Guide
-
-## Table of Contents
-
-1. [Introduction](#introduction)
-2. [Installation](#installation)
-3. [Core Concepts](#core-concepts)
-4. [Command Reference](#command-reference)
-5. [Input/Output Formats](#inputoutput-formats)
-6. [Workflows & Examples](#workflows--examples)
-7. [Integration Patterns](#integration-patterns)
-8. [Advanced Usage](#advanced-usage)
-9. [Troubleshooting](#troubleshooting)
-
----
-
-## Introduction
-
-The Loosechain Delta Engine CLI provides command-line access to Layer-1 protocol functionality. It transforms data bundles into cryptographically verifiable receipts without requiring any adapter code or external data sources.
-
-### What Does It Do?
-
-The CLI performs three core operations:
-
-1. **Validation** - Verify bundle structure conforms to protocol schema
-2. **Execution** - Run the delta engine and produce a receipt
-3. **Verification** - Replay receipt hash computation to ensure integrity
-
-### Protocol Guarantees
-
-- **Determinism**: Same bundle → same receipt → same hash
-- **No External Calls**: Pure computation, no network/file I/O during execution
-- **Layer-1 Only**: No adapter logic, no data collection, no enrichment
-
----
-
-## Installation
-
-### Global Installation
-
-```bash
-npm install -g @uvrn/cli
-```
-
-Verify installation:
-
-```bash
-delta-engine --version
-# Output: 1.0.0
-```
-
-### Local/Project Installation
-
-```bash
-npm install @uvrn/cli --save-dev
-```
-
-Use with npx:
-
-```bash
-npx delta-engine --version
-```
-
-### From Source
-
-```bash
-git clone https://github.com/uvrn/lc_delta-core.git
-cd lc_delta-core
-git checkout phase-a/cli-v1
-npm install
-npm run build --workspace=@uvrn/cli
-node packages/uvrn-cli/dist/cli.js --version
-```
-
----
-
-## Core Concepts
-
-### Bundles
-
-A **DeltaBundle** is the input to the engine. It contains:
-
-- Multiple data sources (DataSpec[])
-- A claim being verified
-- A variance threshold
-
-### Receipts
-
-A **DeltaReceipt** is the output. It contains:
-
-- Computed deltas (variances)
-- Round-by-round analysis
-- Consensus outcome
-- Cryptographic hash
-
-### The Delta Engine
-
-The engine compares metrics across sources and computes variances. If variance stays within the threshold, the bundle achieves **consensus**. Otherwise, it's **indeterminate**.
-
----
-
-## Command Reference
-
-### `delta-engine run`
-
-**Purpose**: Execute the delta engine on a bundle.
-
-**Syntax**:
-```bash
-delta-engine run [bundle] [options]
-```
-
-**Arguments**:
-- `[bundle]` - Path to bundle file, URL, or omit for stdin
-
-**Options**:
-- `-o, --output <file>` - Write receipt to file
-- `-q, --quiet` - Suppress console messages
-- `-p, --pretty` - Pretty-print JSON
-
-**Examples**:
-
-```bash
-# File input
-delta-engine run bundle.json
-
-# Pretty output to file
-delta-engine run bundle.json --output receipt.json --pretty
-
-# Stdin input
-cat bundle.json | delta-engine run
-
-# URL input
-delta-engine run https://example.com/data/bundle.json
-
-# Quiet mode (only JSON output)
-delta-engine run bundle.json --quiet
-```
-
-**Exit Codes**:
-- `0` - Success (consensus achieved)
-- `1` - Invalid bundle structure
-- `2` - Engine error
-- `3` - I/O error
-
----
-
-### `delta-engine validate`
-
-**Purpose**: Validate bundle structure without running engine.
-
-**Syntax**:
-```bash
-delta-engine validate [bundle] [options]
-```
-
-**Arguments**:
-- `[bundle]` - Path to bundle file, URL, or omit for stdin
-
-**Options**:
-- `-o, --output <file>` - Write result to file
-- `-q, --quiet` - Suppress console messages
-- `-p, --pretty` - Pretty-print JSON
-
-**Examples**:
-
-```bash
-# Basic validation
-delta-engine validate bundle.json
-
-# With detailed output
-delta-engine validate bundle.json --pretty
-```
-
-**Output Format**:
-
-Valid bundle:
-```json
-{
-  "valid": true
-}
-```
-
-Invalid bundle:
-```json
-{
-  "valid": false,
-  "error": "thresholdPct must be > 0 and <= 1"
-}
-```
-
-**Exit Codes**:
-- `0` - Bundle is valid
-- `1` - Bundle is invalid
-- `3` - I/O error
-
----
-
-### `delta-engine verify`
-
-**Purpose**: Verify receipt integrity by recomputing hash.
-
-**Syntax**:
-```bash
-delta-engine verify [receipt] [options]
-```
-
-**Arguments**:
-- `[receipt]` - Path to receipt file, URL, or omit for stdin
-
-**Options**:
-- `-o, --output <file>` - Write result to file
-- `-q, --quiet` - Suppress console messages
-- `-p, --pretty` - Pretty-print JSON
-
-**Examples**:
-
-```bash
-# Verify receipt
-delta-engine verify receipt.json
-
-# Pretty output
-delta-engine verify receipt.json --pretty
-```
-
-**Output Format**:
-
-Valid receipt:
-```json
-{
-  "verified": true,
-  "hash": "36247244c63f58e0b2908d2fad115f60677f29b59b67665579b9b6e8db727791"
-}
-```
-
-Invalid receipt:
-```json
-{
-  "verified": false,
-  "error": "Hash mismatch. Provided: abc..., Computed: def...",
-  "providedHash": "abc123...",
-  "recomputedHash": "def456..."
-}
-```
-
-**Exit Codes**:
-- `0` - Receipt is valid
-- `2` - Receipt verification failed
-- `3` - I/O error
-
----
-
-## Input/Output Formats
-
-### Reading Input
-
-The CLI supports three input methods:
-
-#### 1. File Path
-```bash
-delta-engine run /path/to/bundle.json
-```
-
-Both relative and absolute paths work:
-```bash
-delta-engine run ./data/bundle.json
-delta-engine run ~/bundles/bundle.json
-```
-
-#### 2. Stdin
-```bash
-cat bundle.json | delta-engine run
-echo '{"bundleId":"test",...}' | delta-engine run
-curl https://api.example.com/bundle | delta-engine run
-```
-
-Use `-` explicitly:
-```bash
-delta-engine run - < bundle.json
-```
-
-#### 3. URL
-```bash
-delta-engine run https://example.com/bundle.json
-delta-engine run http://localhost:3000/api/bundle
-```
-
-Supports both HTTP and HTTPS.
-
-### Writing Output
-
-#### 1. Stdout (Default)
-```bash
-delta-engine run bundle.json
-# Prints JSON to console
-```
-
-#### 2. File
-```bash
-delta-engine run bundle.json --output receipt.json
-# Writes to receipt.json
-```
-
-#### 3. Pretty Print
-```bash
-delta-engine run bundle.json --pretty
-# Formatted JSON with indentation
-```
-
-#### 4. Quiet Mode
-```bash
-delta-engine run bundle.json --quiet
-# No status messages, only JSON
-```
-
----
-
-## Workflows & Examples
-
-### Basic Verification Workflow
-
-```bash
-# Step 1: Validate bundle structure
-delta-engine validate bundle.json
-# ✓ Bundle is valid
-
-# Step 2: Run engine
-delta-engine run bundle.json --output receipt.json
-# Generates receipt
-
-# Step 3: Verify receipt
-delta-engine verify receipt.json
-# ✓ Receipt is valid
-```
-
-### CI/CD Integration
-
-```bash
-#!/bin/bash
-# verify-security-scan.sh
-
-BUNDLE="security-scan-bundle.json"
-RECEIPT="security-scan-receipt.json"
-
-# Validate bundle
-if ! delta-engine validate "$BUNDLE" --quiet; then
-  echo "ERROR: Invalid bundle structure"
-  exit 1
-fi
-
-# Run engine
-if delta-engine run "$BUNDLE" --output "$RECEIPT" --quiet; then
-  echo "✓ Security scan achieved consensus"
-
-  # Verify receipt integrity
-  delta-engine verify "$RECEIPT" --quiet
-
-  # Archive receipt with timestamp
-  cp "$RECEIPT" "archive/receipt-$(date +%Y%m%d-%H%M%S).json"
-else
-  echo "✗ Security scan failed to reach consensus"
-  echo "Review variance in receipt details"
-  exit 1
-fi
-```
-
-### Batch Processing
-
-```bash
-#!/bin/bash
-# Process multiple bundles
-
-for bundle in bundles/*.json; do
-  name=$(basename "$bundle" .json)
-  receipt="receipts/${name}-receipt.json"
-
-  echo "Processing $name..."
-
-  if delta-engine run "$bundle" --output "$receipt" --quiet; then
-    echo "  ✓ Generated $receipt"
-  else
-    echo "  ✗ Failed to process $bundle"
-  fi
-done
-```
-
-### Data Pipeline Integration
-
-```bash
-# Fetch data → Build bundle → Run engine → Store receipt
-
-curl -X POST https://api.example.com/collect \
-  -H "Content-Type: application/json" \
-  -d '{"sources": ["github", "npm", "security-db"]}' | \
-  delta-engine run --output receipt.json --pretty
-
-# Then push receipt to storage
-aws s3 cp receipt.json s3://receipts/$(date +%Y-%m-%d)/receipt.json
-```
-
----
-
-## Integration Patterns
-
-### Node.js Scripts
-
-```javascript
-const { execSync } = require('child_process');
-const fs = require('fs');
-
-// Build bundle
-const bundle = {
-  bundleId: 'script-001',
-  claim: 'Verify metrics',
-  thresholdPct: 0.05,
-  dataSpecs: [/* ... */]
-};
-
-fs.writeFileSync('bundle.json', JSON.stringify(bundle));
-
-// Run CLI
-try {
-  const receipt = execSync('delta-engine run bundle.json --quiet', {
-    encoding: 'utf-8'
-  });
-
-  const receiptObj = JSON.parse(receipt);
-  console.log('Outcome:', receiptObj.outcome);
-  console.log('Hash:', receiptObj.hash);
-} catch (error) {
-  console.error('Engine failed:', error.message);
-}
-```
-
-### Python Integration
-
-```python
-import subprocess
-import json
-
-# Load bundle
-with open('bundle.json', 'r') as f:
-    bundle = json.load(f)
-
-# Run CLI
-result = subprocess.run(
-    ['delta-engine', 'run', 'bundle.json', '--quiet'],
-    capture_output=True,
-    text=True
-)
-
-if result.returncode == 0:
-    receipt = json.loads(result.stdout)
-    print(f"Outcome: {receipt['outcome']}")
-    print(f"Hash: {receipt['hash']}")
-else:
-    print(f"Error: {result.stderr}")
-```
-
-### Shell Functions
-
-```bash
-# Add to .bashrc or .zshrc
-
-# Shorthand for validate + run + verify
-verify-bundle() {
-  local bundle="$1"
-  local receipt="${2:-receipt.json}"
-
-  delta-engine validate "$bundle" && \
-  delta-engine run "$bundle" --output "$receipt" && \
-  delta-engine verify "$receipt"
-}
-
-# Usage:
-# verify-bundle bundle.json output-receipt.json
-```
-
----
-
-## Advanced Usage
-
-### Combining with jq
-
-```bash
-# Extract specific fields
-delta-engine run bundle.json | jq '.outcome'
-# "consensus"
-
-delta-engine run bundle.json | jq '.deltaFinal'
-# 0.01980198
-
-# Filter rounds
-delta-engine run bundle.json | jq '.rounds[] | select(.withinThreshold == false)'
-```
-
-### Environment Variables
-
-```bash
-# Set default output directory
-export DELTA_ENGINE_OUTPUT_DIR="./receipts"
-
-# Wrapper script
-delta-engine run bundle.json --output "$DELTA_ENGINE_OUTPUT_DIR/receipt.json"
-```
-
-### Parallel Execution
-
-```bash
-# Process multiple bundles in parallel (GNU parallel)
-ls bundles/*.json | parallel -j 4 \
-  'delta-engine run {} --output receipts/{/.}-receipt.json'
-```
-
-### Streaming JSON
-
-```bash
-# Process newline-delimited JSON
-while IFS= read -r bundle; do
-  echo "$bundle" | delta-engine run --quiet
-done < bundles.ndjson > receipts.ndjson
-```
-
----
-
-## Troubleshooting
-
-### Common Issues
-
-#### Issue: "Cannot find module '@uvrn/core'"
-
-**Solution**: Rebuild the workspace:
-```bash
-cd /path/to/monorepo
-npm run build
-```
-
-#### Issue: "Invalid JSON for bundle"
-
-**Solution**: Validate JSON syntax:
-```bash
-cat bundle.json | jq .
-```
-
-#### Issue: "thresholdPct must be > 0 and <= 1"
-
-**Solution**: Check your threshold value:
-```json
-{
-  "thresholdPct": 0.05  // Valid: 5%
-}
-```
-
-Not:
-```json
-{
-  "thresholdPct": 5  // Invalid: Must be 0.0 to 1.0
-}
-```
-
-#### Issue: "dataSpecs must be an array with at least 2 items"
-
-**Solution**: Ensure at least 2 data sources:
-```json
-{
-  "dataSpecs": [
-    { "id": "source-1", /* ... */ },
-    { "id": "source-2", /* ... */ }
-  ]
-}
-```
-
-### Debug Mode
-
-Enable verbose logging:
-
-```bash
-# Node.js debug
-NODE_DEBUG=* delta-engine run bundle.json
-```
-
-### Checking Exit Codes
-
-```bash
-delta-engine run bundle.json
-case $? in
-  0) echo "Success" ;;
-  1) echo "Invalid bundle" ;;
-  2) echo "Engine error" ;;
-  3) echo "I/O error" ;;
-esac
-```
-
----
-
-## Best Practices
-
-1. **Always validate before running**: Use `validate` to catch structural issues early
-2. **Use --quiet in scripts**: Suppress console output for cleaner automation
-3. **Store receipts with timestamps**: Archive receipts for audit trails
-4. **Verify receipts after generation**: Ensure hash integrity immediately
-5. **Use semantic bundle IDs**: Make bundleId descriptive (e.g., `security-scan-2024-01-14`)
-
----
-
-## Next Steps
-
-- Explore the [API Server](../../uvrn-api/README.md) for HTTP access
-- Learn about [MCP Integration](../../uvrn-mcp/README.md) for AI agents
-- Read the [Protocol Specification](../../../admin/docs/compass/PROTOCOL.md)
-
----
-
-## Support
-
-- Repository: https://github.com/uvrn/lc_delta-core
-- Issues: https://github.com/uvrn/lc_delta-core/issues
-- Protocol Docs: See `/admin/docs/compass/` in repository

package/jest.config.js

@@ -1,12 +0,0 @@
-module.exports = {
-  preset: 'ts-jest',
-  testEnvironment: 'node',
-  roots: ['<rootDir>/tests'],
-  testMatch: ['**/*.test.ts'],
-  collectCoverageFrom: [
-    'src/**/*.ts',
-    '!src/**/*.d.ts'
-  ],
-  coverageDirectory: 'coverage',
-  coverageReporters: ['text', 'lcov', 'html']
-};