@sovaria/cli 0.0.0-stage → 0.2.11

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sovaria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# @sovaria/cli
 
-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.
+`sov`, the Sovaria command-line interface: sign in, link a folder to a project, run SQL and migrations,
+manage documents, storage, functions, auth, realtime, keys and logs, and connect AI assistants over MCP.
+
+```bash
+npm install -g @sovaria/cli
+sov --help
+```
+
+Or run it without installing: `npx @sovaria/cli --help`.
+
+**Needs Python 3.11 or newer.** The CLI is written in Python. On first run this package sets up a private
+environment in `~/.sovaria/npm-cli` from the files it ships with (other dependencies come from PyPI) and
+then starts in under a second. It uses [uv](https://docs.astral.sh/uv/) when it is installed. Prefer pip?
+`pip install sovaria-cli` installs the same CLI.
+
+## Get started
+
+```bash
+sov auth login                    # sign in through the browser
+sov link                          # pick the org and project for this folder
+sov db sql "select now()"
+sov fn deploy ./hello             # deploy a function
+sov mcp config --remote --client claude   # connect an AI assistant to your project
+```
+
+Guide: <https://sovaria.in/docs/cli-guide> · Every command: <https://sovaria.in/docs/cli-reference>
+
+## Settings
+
+| Variable | Use |
+|---|---|
+| `SOVARIA_PYTHON` | The Python to use (3.11+), when it isn't on your `PATH` as `python3` |
+| `SOVARIA_CLI_HOME` | Where to keep the environment (default `~/.sovaria/npm-cli`) |
+| `SOVARIA_CLI_REINSTALL=1` | Set the environment up again |
+| `SOVARIA_CLI_NO_UV=1` | Use Python's `venv` and pip even when uv is installed |
+
+On Debian or Ubuntu without uv, Python needs its venv module: `sudo apt install python3-venv`.
+
+## License
+
+MIT

package/bin/sov.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+// The Sovaria CLI (`sov`) from npm. The CLI itself is Python: this launcher keeps it in a private
+// environment under ~/.sovaria/npm-cli (created on first run from the wheels bundled in this package,
+// third-party dependencies from PyPI) and runs it with your arguments, exit code and Ctrl-C.
+//
+//   SOVARIA_PYTHON=/path/to/python3.12   use this Python (3.11 or newer)
+//   SOVARIA_CLI_HOME=/some/dir           keep the environment somewhere else
+//   SOVARIA_CLI_REINSTALL=1              set the environment up again
+//   SOVARIA_CLI_NO_UV=1                  don't use uv even when it is installed
+'use strict';
+
+const { spawn, spawnSync } = require('node:child_process');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+
+const PKG = require('../package.json');
+const WHEELS = path.join(__dirname, '..', 'wheels');
+const WIN = process.platform === 'win32';
+const HOME = process.env.SOVARIA_CLI_HOME || path.join(os.homedir(), '.sovaria', 'npm-cli');
+
+function fail(message) {
+  process.stderr.write(`sov: ${message}\n`);
+  process.exit(1);
+}
+
+function wheelFiles() {
+  let names = [];
+  try {
+    names = fs.readdirSync(WHEELS).filter((f) => f.endsWith('.whl')).sort();
+  } catch {
+    // handled below
+  }
+  if (!names.some((n) => n.startsWith('sovaria_cli-')) || !names.some((n) => n.startsWith('sovaria_sdk-'))) {
+    fail('this package is incomplete (its Python wheels are missing). Reinstall it: npm install -g @sovaria/cli');
+  }
+  return names.map((n) => path.join(WHEELS, n));
+}
+
+function fingerprint(files) {
+  const h = crypto.createHash('sha256');
+  for (const f of files) h.update(path.basename(f)).update(fs.readFileSync(f));
+  return h.digest('hex').slice(0, 12);
+}
+
+function run(cmd, args, opts = {}) {
+  return spawnSync(cmd, args, { encoding: 'utf8', windowsHide: true, ...opts });
+}
+
+function pythonVersion(cmd, pre) {
+  const r = run(cmd, [...pre, '-c', 'import sys; print("%d.%d" % sys.version_info[:2])']);
+  if (r.status !== 0 || !r.stdout) return null;
+  const [major, minor] = r.stdout.trim().split('.').map(Number);
+  return major > 3 || (major === 3 && minor >= 11) ? `${major}.${minor}` : null;
+}
+
+function findPython({ optional = false } = {}) {
+  const candidates = [];
+  if (process.env.SOVARIA_PYTHON) candidates.push([process.env.SOVARIA_PYTHON, []]);
+  if (WIN) candidates.push(['py', ['-3.13']], ['py', ['-3.12']], ['py', ['-3.11']], ['python', []], ['py', ['-3']]);
+  else candidates.push(['python3.13', []], ['python3.12', []], ['python3.11', []], ['python3', []], ['python', []]);
+  for (const [cmd, pre] of candidates) {
+    const version = pythonVersion(cmd, pre);
+    if (version) return { cmd, pre, version };
+  }
+  if (process.env.SOVARIA_PYTHON) fail(`SOVARIA_PYTHON (${process.env.SOVARIA_PYTHON}) isn't Python 3.11 or newer.`);
+  if (optional) return null;
+  return fail('the Sovaria CLI needs Python 3.11 or newer. Install it from https://www.python.org/downloads/ '
+    + '(or with your package manager), or point SOVARIA_PYTHON at one, then run sov again.');
+}
+
+function envPython(dir) {
+  return WIN ? path.join(dir, 'Scripts', 'python.exe') : path.join(dir, 'bin', 'python');
+}
+
+function envSov(dir) {
+  return WIN ? path.join(dir, 'Scripts', 'sov.exe') : path.join(dir, 'bin', 'sov');
+}
+
+function hasUv() {
+  if (process.env.SOVARIA_CLI_NO_UV) return false;
+  return run('uv', ['--version']).status === 0;
+}
+
+function requirements(files) {
+  // Direct references, so both pip and uv install exactly these files (with the SDK's MCP extra).
+  return files.map((f) => {
+    const name = path.basename(f).startsWith('sovaria_sdk-') ? 'sovaria-sdk[mcp]' : 'sovaria-cli';
+    return `${name} @ ${pathToFileURL(f).href}`;
+  });
+}
+
+function sleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function withLock(lockDir, fn) {
+  const deadline = Date.now() + 5 * 60_000;
+  for (;;) {
+    try {
+      fs.mkdirSync(lockDir);
+      break;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      let age = 0;
+      try { age = Date.now() - fs.statSync(lockDir).mtimeMs; } catch { continue; }
+      if (age > 10 * 60_000) { fs.rmSync(lockDir, { recursive: true, force: true }); continue; }
+      if (Date.now() > deadline) fail(`another sov is still setting up (${lockDir}). If none is, delete that folder.`);
+      sleep(500);
+    }
+  }
+  try { return fn(); } finally { fs.rmSync(lockDir, { recursive: true, force: true }); }
+}
+
+function install(dir, files) {
+  const uv = hasUv();
+  // uv can fetch a Python itself when there's no 3.11+ on this machine.
+  const py = findPython({ optional: uv });
+  process.stderr.write(`Setting up the Sovaria CLI ${PKG.version} (first run, about a minute)…\n`);
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(dir), { recursive: true });
+  const reqs = requirements(files);
+  let r;
+  if (uv) {
+    const target = !py ? '3.12' : py.pre.length ? py.version : py.cmd;
+    r = run('uv', ['venv', '--quiet', '--python', target, dir], { stdio: ['ignore', 'pipe', 'pipe'] });
+    if (r.status === 0) r = run('uv', ['pip', 'install', '--quiet', '--compile-bytecode', '--python', envPython(dir), ...reqs], { stdio: ['ignore', 'pipe', 'pipe'] });
+  } else {
+    r = run(py.cmd, [...py.pre, '-m', 'venv', dir], { stdio: ['ignore', 'pipe', 'pipe'] });
+    if (r.status !== 0) {
+      fs.rmSync(dir, { recursive: true, force: true });
+      fail('Python couldn\'t create a virtual environment. On Debian or Ubuntu: sudo apt install python3-venv '
+        + '(or install uv: https://docs.astral.sh/uv/), then run sov again.');
+    }
+    r = run(envPython(dir), ['-m', 'pip', 'install', '--quiet', '--disable-pip-version-check', ...reqs],
+      { stdio: ['ignore', 'pipe', 'pipe'] });
+  }
+  if (r.status !== 0) {
+    fs.rmSync(dir, { recursive: true, force: true });
+    const detail = `${r.stderr || ''}${r.stdout || ''}`.trim().split('\n').slice(-12).join('\n');
+    fail(`setting up the CLI failed:\n${detail}\nCheck your internet connection (dependencies come from PyPI) and run sov again.`);
+  }
+  fs.writeFileSync(path.join(dir, '.sovaria-installed'), `${PKG.version}\n`);
+  // Environments of older versions of this package are no longer used.
+  for (const entry of fs.readdirSync(HOME)) {
+    const full = path.join(HOME, entry);
+    if (full !== dir && /^\d+\.\d+\.\d+.*-[0-9a-f]{12}$/.test(entry)) fs.rmSync(full, { recursive: true, force: true });
+  }
+  process.stderr.write('The Sovaria CLI is ready.\n');
+}
+
+function main() {
+  const files = wheelFiles();
+  const dir = path.join(HOME, `${PKG.version}-${fingerprint(files)}`);
+  const ready = () => fs.existsSync(path.join(dir, '.sovaria-installed')) && fs.existsSync(envSov(dir));
+  if (process.env.SOVARIA_CLI_REINSTALL || !ready()) {
+    fs.mkdirSync(HOME, { recursive: true });
+    withLock(`${dir}.lock`, () => {
+      if (process.env.SOVARIA_CLI_REINSTALL || !ready()) install(dir, files);
+    });
+  }
+  const child = spawn(envSov(dir), process.argv.slice(2), { stdio: 'inherit', windowsHide: false });
+  // Ctrl-C reaches the CLI itself (same terminal); this launcher just waits for it.
+  for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(sig, () => { try { child.kill(sig); } catch { /* gone */ } });
+  child.on('error', (err) => fail(`couldn't start the CLI (${err.message}). Run with SOVARIA_CLI_REINSTALL=1 to set it up again.`));
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      process.removeAllListeners(signal);
+      process.kill(process.pid, signal);
+    } else {
+      process.exit(code ?? 1);
+    }
+  });
+}
+
+main();

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@sovaria/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.11",
+  "description": "The Sovaria command-line interface (sov): log in, link a project, run SQL and migrations, deploy functions, manage auth, storage, realtime and more. Needs Python 3.11+.",
+  "keywords": [
+    "sovaria",
+    "cli",
+    "sov",
+    "baas",
+    "backend",
+    "database",
+    "postgres",
+    "functions",
+    "mcp"
+  ],
+  "homepage": "https://sovaria.in/docs/cli-guide",
+  "bugs": {
+    "url": "https://sovaria.in/contact"
+  },
+  "license": "MIT",
+  "author": "Sovaria (https://sovaria.in)",
+  "bin": {
+    "sov": "bin/sov.js"
+  },
+  "files": [
+    "bin/sov.js",
+    "wheels/*.whl",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "prepublishOnly": "node bin/check-package.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}