@onproper/cli 0.0.0-stage → 1.0.4

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# Proper
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Lightweight, Zero-Knowledge Change Data Capture (CDC) & Dispatcher for PostgreSQL.**
+
+Proper is a blazing-fast, edge-first Go binary that monitors your PostgreSQL database in real-time and triggers local scripts or external webhooks the millisecond a row changes. 
+
+Designed for strict memory safety and enterprise compliance, it runs securely inside your own VPC. Your database credentials never leave your servers.
+
+---
+
+## ✨ Features
+
+* **Zero-Knowledge Architecture:** Reads your database locally. No raw row data is ever transmitted to a third party.
+* **Smart Polymorphic Dispatching:** Automatically routes actions to local scripts (`node handler.js`) or HTTP webhooks based on the target string.
+* **Lock-Free Hot Reloading:** Update your `proper.config.yaml` and the engine hot-swaps your rules in memory using atomic pointers—zero restarts, zero dropped events.
+* **Poison Pill Prevention:** Built-in exponential backoff retries. If a webhook or script repeatedly fails, the event is quarantined to a local Dead Letter Queue (`proper.dlq.log`) to protect the database stream.
+* **Enterprise Audit Logging:** Automatically outputs a structured `JSONL` (JSON Lines) file of every success and failure, instantly ready for Datadog, Splunk, or ELK.
+
+---
+
+## ⚡️ Quick Start
+
+Proper is designed to be deployed as a sidecar to your database using Docker.
+
+### 1. Define Environment Variables
+
+# Your local database connection (Requires logical replication enabled)
+DATABASE_URL=postgres://root:password@host.docker.internal:5432/app_db?replication=database
+
+# A unique identifier for this deployment (prevents replication slot collisions)
+PROPER_PIPELINE_ID=pipe_local_dev
+
+### 2. Define your triggers (`proper.config.yaml`)
+
+triggers:
+  - id: notify_slack_on_large_discount
+    table: purchase_order
+    action: UPDATE
+    condition:
+      field: discount_rate
+      operator: gt
+      value: "0.40"
+    dispatch:
+      # Proper auto-detects webhooks vs local scripts
+      exec: "[https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX](https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX)"
+
+
+### 3. Boot the Engine (`docker-compose.yml`)
+
+version: '3.8'
+services:
+  proper-agent:
+    image: proper/engine:latest
+    container_name: proper_agent
+    env_file:
+      - .env
+    volumes:
+      - ./proper.config.yaml:/proper/proper.config.yaml:ro
+      - ./proper.dlq.log:/proper/proper.dlq.log
+      - ./proper.audit.log:/proper/proper.audit.log
+
+
+
+Run:
+touch proper.dlq.log proper.audit.log && docker compose up -d
+
+---
+
+## 📊 The JSONL Audit Trail
+
+Proper defaults to writing a high-performance, structured audit log to `/proper/proper.audit.log`. Every execution drops a complete JSON object, allowing your security team to easily parse and query your data movement.
+
+{
+  "trigger_id":"notify_slack_on_large_discount",
+  "target":"[https://hooks.slack.com/](https://hooks.slack.com/)...",
+  "status":"success",
+  "payload":{
+    "id": 4, 
+    "email": "test@example.com", 
+    "discount_rate": 0.50},
+    "timestamp":"2026-10-02T14:32:01Z"
+  }
+}
+
+---
+
+## ☁️ Upgrading to Proper Cloud (SaaS)
+
+Managing local YAML files and grepping text logs is fine for side projects, but enterprise compliance (like the **California Delete Act / SB 362**) requires a cryptographically secure chain of custody.
+
+**Proper Cloud** acts as your immutable compliance ledger and control plane.
+
+By simply adding a `PROPER_API_KEY` to your `.env` file, the open-source agent instantly upgrades:
+
+1. **GitOps Sync:** It pushes your local YAML rules to the Cloud Dashboard for version control and one-click rollbacks.
+2. **Visual Dashboard:** Manage your triggers, conditions, and webhooks via a clean web UI without touching code.
+3. **Verified Telemetry:** The agent securely streams its execution batches to our Control Plane, separating them from the unverified local text files.
+4. **Automated Compliance:** Generate legally binding Certificates of Erasure (PDFs) with a single click to prove to regulators that your fan-out deletions executed successfully across HubSpot, Stripe, and your internal DB.
+
+*Proper Cloud is currently in early access.* **[Join the waitlist at onproper.com](https://www.onproper.com)**

package/bin/proper

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: package/bin/proper
+size: 57683810 bytes
+sha256: b83b27287e9fe850a52e14cafd49fc8d41135341afa52891bc5c9e343bb5655e

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@onproper/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.4",
+  "description": "The Zero-Trust Entity Orchestration & Compliance Engine",
+  "main": "index.js",
+  "bin": {
+    "proper": "bin/proper"
+  },
+  "scripts": {
+    "prepublishOnly": "cp ../README.md ./README.md",
+    "postinstall": "node postinstall.js"
+  },
+  "keywords": [
+    "cdc",
+    "postgres",
+    "compliance",
+    "webhook",
+    "proper"
+  ],
+  "author": "Proper",
+  "license": "MIT"
 }

package/postinstall.js

@@ -0,0 +1,84 @@
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const { execSync } = require('child_process');
+
+// 🔥 THE FIX: Dynamically read the version NPM just installed
+const packageJson = require('./package.json');
+const VERSION = `v${packageJson.version}`; // Translates "1.0.0" to "v1.0.0"
+const REPO = 'vulsys/proper-release';
+
+// 1. Map Node's OS/Arch to Go's OS/Arch
+const platformMap = {
+    darwin: 'darwin',
+    linux: 'linux',
+    win32: 'windows'
+};
+
+const archMap = {
+    x64: 'amd64',
+    arm64: 'arm64'
+};
+
+const platform = platformMap[os.platform()];
+const arch = archMap[os.arch()];
+
+if (!platform || !arch) {
+    console.error(`❌ @onproper/cli does not support ${os.platform()} ${os.arch()}`);
+    process.exit(1);
+}
+
+// 2. Build the exact GitHub Release URL
+let binaryName = `proper-${platform}-${arch}`;
+if (platform === 'windows') {
+    binaryName += '.exe';
+}
+
+const downloadUrl = `https://github.com/${REPO}/releases/download/${VERSION}/${binaryName}`;
+
+// 3. Prepare the destination folder
+const binDir = path.join(__dirname, 'bin');
+if (!fs.existsSync(binDir)) {
+    fs.mkdirSync(binDir);
+}
+
+const destFile = path.join(binDir, platform === 'windows' ? 'proper.exe' : 'proper');
+
+// 4. Download the binary
+console.log(`⬇️  Downloading Proper CDC Engine (${binaryName})...`);
+
+https.get(downloadUrl, (res) => {
+    if (res.statusCode === 301 || res.statusCode === 302) {
+        // Follow GitHub's redirect to the actual AWS S3 bucket
+        https.get(res.headers.location, handleDownload).on('error', handleError);
+    } else {
+        handleDownload(res);
+    }
+}).on('error', handleError);
+
+function handleDownload(res) {
+    if (res.statusCode !== 200) {
+        console.error(`❌ Failed to download binary. Status Code: ${res.statusCode}`);
+        process.exit(1);
+    }
+
+    const fileStream = fs.createWriteStream(destFile);
+    res.pipe(fileStream);
+
+    fileStream.on('finish', () => {
+        fileStream.close();
+        
+        // 5. Make it executable for Mac/Linux
+        if (platform !== 'windows') {
+            execSync(`chmod +x ${destFile}`);
+        }
+        
+        console.log('✅ Proper installed successfully. Run `proper init` to begin.');
+    });
+}
+
+function handleError(err) {
+    console.error(`❌ Download error: ${err.message}`);
+    process.exit(1);
+}