sphere-cli 0.1.2

package/README.md

@@ -0,0 +1,130 @@
+# SPHERE CLI
+
+Command-line interface for **SPHERE** — synthetic data generation, evaluation, and certification. Designed for business workflows, data pipelines, and HPC environments.
+
+> For the desktop application (individual users), see [SPHERE App](https://github.com/statzihuai/SPHERE).
+
+---
+
+## Install
+
+**npm (recommended):**
+
+```sh
+npm install -g sphere-cli
+```
+
+No Python, no curl, no PATH editing. Requires Node.js ≥ 16.
+
+**curl (no Node.js required):**
+
+```sh
+curl -fsSL https://github.com/statzihuai/sphere-cli/releases/latest/download/install.sh | sh
+```
+
+For HPC / cloud with no sudo:
+
+```sh
+curl -fsSL https://github.com/statzihuai/sphere-cli/releases/latest/download/install.sh | sh -s -- --prefix ~/.local
+# then add to ~/.bashrc or ~/.zshrc:
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+**Uninstall:**
+
+```sh
+sh install.sh --uninstall
+```
+
+### Supported platforms
+
+| Platform | Architecture |
+|---|---|
+| macOS | Apple Silicon (arm64) |
+| Linux | x86\_64 |
+| Linux | arm64 (AWS Graviton, etc.) |
+
+---
+
+## Quick start
+
+```sh
+# Generate synthetic data
+sphere generate real.csv -o synth.csv
+
+# Evaluate fidelity and privacy
+sphere evaluate real.csv synth.csv
+
+# Generate a certification report (HTML)
+sphere certify real.csv synth.csv -o report.html
+```
+
+---
+
+## Commands
+
+### `sphere generate`
+
+```
+sphere generate <real.csv> [options]
+
+Options:
+  -o, --output PATH        Output CSV path (default: <input>_sphere.csv)
+  -n, --rows INT           Number of synthetic rows (default: same as input)
+  -k INT                   SPHERE rotations (default: 2)
+  --seed INT               Random seed for reproducibility
+  --mix-prob FLOAT         Mixture probability 0–1 (default: 0.75)
+  --json                   Machine-readable JSON output
+```
+
+A `.sphere.json` provenance file is written alongside every output CSV and is automatically read by `sphere certify`.
+
+### `sphere evaluate`
+
+```
+sphere evaluate <real.csv> <synth.csv> [options]
+
+Options:
+  --skip-privacy           Skip privacy metrics (faster)
+  --json                   Machine-readable JSON output
+```
+
+### `sphere certify`
+
+```
+sphere certify <real.csv> <synth.csv> [options]
+
+Options:
+  -o, --output PATH        Output HTML report path (default: cert.html)
+  --json                   Machine-readable JSON output
+```
+
+Generation parameters (`k`, `seed`, `theta`, etc.) are loaded automatically from the `.sphere.json` sidecar. Pass flags explicitly to override.
+
+---
+
+## Machine-readable output
+
+Every command supports `--json` for pipeline integration:
+
+```sh
+sphere generate real.csv -o synth.csv --json | jq .fidelity
+sphere evaluate real.csv synth.csv --json > metrics.json
+```
+
+---
+
+## Environment variables
+
+| Variable | Description |
+|---|---|
+| `SPHERE_PREFIX` | Override install prefix |
+| `SPHERE_VERSION` | Pin a release tag, e.g. `v0.1.0` |
+| `SPHERE_BUNDLE_URL` | Full URL to a `sphere-cli-*.tar.gz` (skip auto-detect) |
+| `SPHERE_GITHUB_REPO` | Override GitHub repo for downloads |
+
+---
+
+## License
+
+Proprietary — see [LICENSE](LICENSE).

package/bin/sphere.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const binaryPath = path.join(__dirname, '..', 'native', 'sphere-cli', 'sphere');
+
+if (!fs.existsSync(binaryPath)) {
+  console.error(
+    'SPHERE CLI binary not found.\n' +
+    'This usually means the postinstall step failed or was skipped.\n' +
+    'Try reinstalling:  npm install -g sphere-cli'
+  );
+  process.exit(1);
+}
+
+const result = spawnSync(binaryPath, process.argv.slice(2), {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+process.exit(result.status ?? 1);

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "sphere-cli",
+  "version": "0.1.2",
+  "description": "SPHERE CLI — synthetic data generation, evaluation, and certification",
+  "keywords": ["synthetic-data", "privacy", "cli", "data-science"],
+  "homepage": "https://github.com/statzihuai/sphere-cli",
+  "bugs": "https://github.com/statzihuai/sphere-cli/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/statzihuai/sphere-cli.git"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "bin": {
+    "sphere": "./bin/sphere.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "os": ["darwin", "linux"],
+  "cpu": ["arm64", "x64"]
+}

package/scripts/postinstall.js

@@ -0,0 +1,127 @@
+'use strict';
+
+/**
+ * Downloads the correct platform-specific SPHERE CLI binary from GitHub
+ * Releases and extracts it to native/ inside the npm package directory.
+ *
+ * Tarball structure (built by CI):
+ *   sphere-cli/        ← PyInstaller onedir bundle
+ *     sphere           ← the executable
+ *     _internal/       ← Python runtime + deps
+ *   install.sh
+ *
+ * After extraction, bin/sphere.js invokes native/sphere-cli/sphere.
+ */
+
+const https   = require('https');
+const fs      = require('fs');
+const path    = require('path');
+const os      = require('os');
+const { execFileSync } = require('child_process');
+
+const REPO    = 'statzihuai/sphere-cli';
+const VERSION = require('../package.json').version;
+const PKG_DIR = path.join(__dirname, '..');
+
+// ── Map Node.js platform/arch to our release tarball names ───────────────────
+function getPlatformKey() {
+  const p = process.platform;
+  const a = process.arch;
+  if (p === 'darwin' && a === 'arm64') return 'macos-arm64';
+  if (p === 'linux'  && a === 'x64')   return 'linux-x86_64';
+  if (p === 'linux'  && a === 'arm64') return 'linux-arm64';
+  throw new Error(
+    `Unsupported platform: ${p}-${a}\n` +
+    'Supported: macOS arm64, Linux x86_64, Linux arm64.\n' +
+    'Use the curl installer instead: https://github.com/statzihuai/sphere-cli#install'
+  );
+}
+
+// ── HTTPS GET with redirect following ────────────────────────────────────────
+function download(url, destPath) {
+  return new Promise((resolve, reject) => {
+    function get(url, redirects) {
+      if (redirects > 5) { reject(new Error('Too many redirects')); return; }
+      https.get(url, { headers: { 'User-Agent': 'sphere-cli-npm-installer' } }, res => {
+        if (res.statusCode === 301 || res.statusCode === 302) {
+          get(res.headers.location, redirects + 1);
+          return;
+        }
+        if (res.statusCode !== 200) {
+          reject(new Error(`HTTP ${res.statusCode} downloading ${url}`));
+          res.resume();
+          return;
+        }
+        const out = fs.createWriteStream(destPath);
+        res.pipe(out);
+        out.on('finish', () => out.close(resolve));
+        out.on('error', reject);
+        res.on('error', reject);
+      }).on('error', reject);
+    }
+    get(url, 0);
+  });
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+async function main() {
+  // Skip in CI environments where binaries are built fresh
+  if (process.env.SPHERE_SKIP_POSTINSTALL === '1') {
+    console.log('SPHERE_SKIP_POSTINSTALL=1 — skipping binary download.');
+    return;
+  }
+
+  const platform = getPlatformKey();
+  const tarball  = `sphere-cli-${platform}.tar.gz`;
+  const url      = `https://github.com/${REPO}/releases/download/v${VERSION}/${tarball}`;
+  const nativeDir = path.join(PKG_DIR, 'native');
+  const tmpTar    = path.join(os.tmpdir(), `sphere-cli-install-${process.pid}.tar.gz`);
+
+  // Already installed (e.g. re-running postinstall manually)
+  const binaryPath = path.join(nativeDir, 'sphere-cli', 'sphere');
+  if (fs.existsSync(binaryPath)) {
+    console.log('✓ SPHERE CLI binary already present — skipping download.');
+    return;
+  }
+
+  console.log(`\nDownloading SPHERE CLI v${VERSION} for ${platform} …`);
+  console.log(`  ${url}\n`);
+
+  try {
+    await download(url, tmpTar);
+  } catch (err) {
+    throw new Error(
+      `Failed to download SPHERE CLI binary: ${err.message}\n\n` +
+      'Alternatives:\n' +
+      `  • curl installer: curl -fsSL https://github.com/${REPO}/releases/latest/download/install.sh | sh\n` +
+      `  • Manual download: ${url}`
+    );
+  }
+
+  fs.mkdirSync(nativeDir, { recursive: true });
+
+  try {
+    execFileSync('tar', ['-xzf', tmpTar, '-C', nativeDir]);
+  } finally {
+    try { fs.unlinkSync(tmpTar); } catch {}
+  }
+
+  // Ensure the binary is executable
+  fs.chmodSync(binaryPath, 0o755);
+
+  console.log('✓ SPHERE CLI installed.\n');
+  console.log('  Quick start:');
+  console.log('    sphere generate data.csv -o synth.csv');
+  console.log('    sphere evaluate real.csv synth.csv');
+  console.log('    sphere certify  real.csv synth.csv -o report.html');
+  console.log('');
+  console.log("  Run 'sphere --help' for full options.\n");
+}
+
+main().catch(err => {
+  console.error('\n✗ SPHERE CLI postinstall failed:\n  ' + err.message);
+  console.error('\nThe npm package was installed but the binary was not downloaded.');
+  console.error('Running `sphere` will show an error until you reinstall.\n');
+  // Exit 0 so npm install doesn't fail — user can fix later
+  process.exit(0);
+});