@selvajs/cli 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Selva FelixBrunold VektorNode
+
+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

@@ -0,0 +1,36 @@
+# @selvajs/cli
+
+CLI for white-label Selva deployments.
+
+## Bootstrap a new deployment
+
+```bash
+npx @selvajs/cli my-deployment
+```
+
+Interactive scaffolder. Prompts for provider, tenancy, flags, brand name, admin email. Generates `SELVA_HMAC_KEY` + `SELVA_AT_REST_KEY`. Writes `.env`, `selva.config.js`, `ecosystem.config.cjs`, `package.json`. Runs `npm install`.
+
+## Operate an existing deployment
+
+After install, the package exposes a `selva` bin:
+
+```bash
+selva init                  # reconfigure prompts; preserves existing secrets
+selva doctor                # validate env + providers + paths
+selva start | stop | restart | logs
+selva update                # npm update @selvajs/selva + pm2 restart
+selva keys rotate hmac      # rotate SELVA_HMAC_KEY (logs everyone out)
+selva keys rotate at-rest   # rotate SELVA_AT_REST_KEY (compute API key needs re-entry)
+```
+
+All operator commands run inside the deployment directory (the one that contains `.env` and `ecosystem.config.cjs`).
+
+## Idempotency rules
+
+- `npx @selvajs/cli` refuses to overwrite a non-empty directory without `--force`.
+- `selva init` reads the current `.env`, lets the user edit, and **never** regenerates `SELVA_HMAC_KEY` / `SELVA_AT_REST_KEY` if they're already set.
+- A `.selva-version` marker is written so future CLI versions can migrate config schema cleanly.
+
+## Relationship to `@selvajs/selva`
+
+The CLI generates a deployment directory whose `package.json` depends on `@selvajs/selva`. The runtime ships the prebuilt SvelteKit `node` build plus PM2 / config templates; the CLI's job is to fill in the template values and wire everything together.

package/bin/create.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCreate } from '../src/commands/create.js';
+
+runCreate(process.argv.slice(2)).catch((err) => {
+	console.error(err instanceof Error ? err.message : err);
+	process.exit(1);
+});

package/bin/selva.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runSelva } from '../src/cli.js';
+
+runSelva(process.argv.slice(2)).catch((err) => {
+	console.error(err instanceof Error ? err.message : err);
+	process.exit(1);
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@selvajs/cli",
+  "version": "2.0.0",
+  "description": "Scaffold and operate a Selva white-label deployment. `npx @selvajs/cli <dir>` to bootstrap, `selva <cmd>` to manage.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "create": "./bin/create.js",
+    "selva": "./bin/selva.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "picocolors": "^1.1.1"
+  },
+  "scripts": {
+    "start": "node ./bin/create.js",
+    "selva": "node ./bin/selva.js",
+    "test": "node --input-type=module -e \"for (const m of ['./src/cli.js','./src/prompts.js','./src/env.js','./src/paths.js','./src/secrets.js','./src/commands/create.js','./src/commands/init.js','./src/commands/doctor.js','./src/commands/pm2.js','./src/commands/keys.js']) { await import(m); }\""
+  }
+}

package/src/cli.js

@@ -0,0 +1,78 @@
+// `selva <command>` dispatcher.
+//
+// Kept deliberately flat — each command is a leaf module that gets imported
+// only when its command runs. No global state, no shared parser; commands
+// own their own argv handling.
+
+import pc from 'picocolors';
+
+const COMMANDS = {
+	init: () => import('./commands/init.js').then((m) => m.runInit),
+	doctor: () => import('./commands/doctor.js').then((m) => m.runDoctor),
+	start: () => import('./commands/pm2.js').then((m) => m.runStart),
+	stop: () => import('./commands/pm2.js').then((m) => m.runStop),
+	restart: () => import('./commands/pm2.js').then((m) => m.runRestart),
+	logs: () => import('./commands/pm2.js').then((m) => m.runLogs),
+	update: () => import('./commands/pm2.js').then((m) => m.runUpdate),
+	keys: () => import('./commands/keys.js').then((m) => keysDispatch(m))
+};
+
+function keysDispatch(m) {
+	return async (argv) => {
+		const sub = argv[0];
+		if (sub === 'rotate') return m.runKeysRotate(argv.slice(1));
+		console.error(`Usage: selva keys rotate <hmac|at-rest>`);
+		process.exit(1);
+	};
+}
+
+export async function runSelva(argv) {
+	const [command, ...rest] = argv;
+	if (!command || command === 'help' || command === '--help' || command === '-h') {
+		printHelp();
+		return;
+	}
+
+	if (command === '--version' || command === '-v') {
+		// We don't pin a version here — selva is installed transitively, so
+		// the deployment's package.json doesn't list us directly. Read our
+		// own package.json instead.
+		const { readFileSync } = await import('node:fs');
+		const { fileURLToPath } = await import('node:url');
+		const { dirname, join } = await import('node:path');
+		const here = dirname(fileURLToPath(import.meta.url));
+		const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+		console.log(pkg.version);
+		return;
+	}
+
+	const loader = COMMANDS[command];
+	if (!loader) {
+		console.error(`${pc.red('✗')} Unknown command: ${command}\n`);
+		printHelp();
+		process.exit(1);
+	}
+
+	const run = await loader();
+	await run(rest);
+}
+
+function printHelp() {
+	console.log(
+		[
+			pc.bold('selva') + ' — operate a Selva deployment',
+			'',
+			pc.bold('Commands:'),
+			'  init                    Reconfigure this deployment (prompts again)',
+			'  doctor                  Validate env, providers, and installed packages',
+			'  start                   pm2 start ecosystem.config.cjs',
+			'  stop                    pm2 stop selva-compute',
+			'  restart                 pm2 restart selva-compute --update-env',
+			'  logs                    pm2 logs selva-compute',
+			'  update                  npm update @selvajs/selva + restart',
+			'  keys rotate <hmac|at-rest>   Rotate a secret in .env (destructive)',
+			'',
+			pc.dim('To scaffold a new deployment: ') + pc.cyan('npx @selvajs/cli <dir>')
+		].join('\n')
+	);
+}

package/src/commands/create.js

@@ -0,0 +1,326 @@
+// `npx @selvajs/cli <dir>` — scaffold a fresh deployment.
+//
+// What this writes into <dir>:
+//   .env                    merged from runtime's .env.example + prompt values
+//   selva.config.js         copied from runtime's templates (operator can edit)
+//   ecosystem.config.cjs    copied verbatim
+//   package.json            depends on @selvajs/selva + providers
+//   .selva-version          marker for future CLI migrations
+//   node_modules/           after `npm install`
+//
+// The runtime templates are the source of truth — we don't carry our own
+// copies in @selvajs/cli. We install @selvajs/selva first, then copy
+// from node_modules/@selvajs/selva/templates/.
+
+import { writeFileSync, existsSync, mkdirSync, readFileSync, cpSync } from 'node:fs';
+import { resolve, join, basename } from 'node:path';
+import { spawn } from 'node:child_process';
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { collectConfig, collectConfigFromEnv } from '../prompts.js';
+import { generateKey } from '../secrets.js';
+import { writeEnvFile } from '../env.js';
+import { isEmptyOrMissing } from '../paths.js';
+
+const CLI_VERSION = '0.1.0';
+
+export async function runCreate(argv) {
+	const { dir: rawDir, force, skipInstall, yes } = parseArgs(argv);
+
+	const targetDir = resolve(rawDir);
+	if (!isEmptyOrMissing(targetDir) && !force) {
+		console.error(
+			`${pc.red('✗')} ${targetDir} already exists and isn't empty. ` +
+				`Pass --force to overwrite, or choose another directory.`
+		);
+		process.exit(1);
+	}
+	mkdirSync(targetDir, { recursive: true });
+
+	// 1. Collect config. --yes (or CI=1) takes everything from the
+	//    environment instead of prompting — for Terraform startup scripts,
+	//    Dockerfiles, and any other unattended bootstrap.
+	const nonInteractive = yes || envBool(process.env.CI);
+	const values = nonInteractive
+		? collectConfigFromEnv(process.env)
+		: await collectConfig({ defaults: {}, mode: 'create' });
+
+	// 2. Always generate fresh secrets for a new install. They MUST be stable
+	//    across restarts; the env-merge logic below writes them once and
+	//    `selva init` later refuses to regenerate them.
+	values.SELVA_HMAC_KEY = generateKey();
+	values.SELVA_AT_REST_KEY = generateKey();
+
+	const deployName = basename(targetDir);
+
+	// 3. Write package.json before installing so npm has something to read.
+	const pkgJson = buildPackageJson(deployName, values);
+	writeFileSync(join(targetDir, 'package.json'), pkgJson + '\n', 'utf8');
+
+	// 4. Install. We need @selvajs/selva on disk to copy templates from it.
+	if (!skipInstall) {
+		await runNpmInstall(targetDir);
+	} else {
+		p.log.warn(
+			'--skip-install was passed: dependencies not installed. Run `npm install` manually before starting.'
+		);
+	}
+
+	// 5. Now copy templates from the installed runtime and fill them in.
+	const runtimeTemplates = join(targetDir, 'node_modules', '@selvajs', 'selva', 'templates');
+	if (skipInstall || !existsSync(runtimeTemplates)) {
+		p.log.warn(
+			`Couldn't read runtime templates from ${runtimeTemplates}. ` +
+				`Run \`npm install\`, then \`selva init\` to finish setup.`
+		);
+		writeFileSync(join(targetDir, '.selva-version'), CLI_VERSION + '\n', 'utf8');
+		p.outro(`Partial scaffold at ${pc.cyan(targetDir)}.`);
+		return;
+	}
+
+	const envTemplate = readFileSync(join(runtimeTemplates, '.env.example'), 'utf8');
+	writeEnvFile(join(targetDir, '.env'), envTemplate, values);
+
+	cpSync(join(runtimeTemplates, 'selva.config.example.js'), join(targetDir, 'selva.config.js'));
+	cpSync(join(runtimeTemplates, 'ecosystem.config.cjs'), join(targetDir, 'ecosystem.config.cjs'));
+
+	writeFileSync(join(targetDir, '.selva-version'), CLI_VERSION + '\n', 'utf8');
+	writeGitignore(targetDir);
+
+	// 6. Outro with next steps.
+	p.outro(
+		[
+			pc.green('Scaffolded ' + pc.cyan(targetDir)),
+			'',
+			pc.bold('Next steps:'),
+			`  cd ${rawDir}`,
+			`  npm run doctor         # sanity-check the install`,
+			`  npm start              # pm2 start ecosystem.config.cjs`,
+			'',
+			values.ORIGIN
+				? `Then visit ${pc.cyan(values.ORIGIN)} (set up your reverse proxy first).`
+				: `Then visit ${pc.cyan('http://localhost:3000')}.`
+		].join('\n')
+	);
+}
+
+// Run `npm install` with live progress and a real error report.
+//
+// The previous implementation used execSync + stdio:'pipe' which buffered
+// everything in memory and discarded it on failure — operators saw "Command
+// failed: npm install" with no clue what went wrong. We stream stdout/stderr
+// into a ring buffer instead, and on failure dump the last lines so they can
+// act on the actual error (sharp's libvips missing, registry timeout, etc.)
+// without fishing through /home/user/.npm/_logs/.
+//
+// Cache-bust hint: if npm prints a placeDep for @selvajs/selva@0.10.2
+// (which was published broken and unpublished), surface that so the operator
+// knows to `npm cache clean --force`.
+function runNpmInstall(cwd) {
+	return new Promise((resolveP, rejectP) => {
+		const s = p.spinner();
+		s.start('Installing dependencies (this can take a minute)');
+
+		// Ring buffer — keep the last 80 lines so we can show them on failure.
+		const tail = [];
+		const maxTail = 80;
+		const remember = (line) => {
+			tail.push(line);
+			if (tail.length > maxTail) tail.shift();
+		};
+
+		// Visible progress milestones. npm doesn't emit a clean progress
+		// stream; we cherry-pick recognizable transitions and pass them to
+		// the spinner so the operator sees movement.
+		const updateProgress = (line) => {
+			const trimmed = line.trim();
+			if (!trimmed) return;
+			// "added 412 packages" — final summary
+			if (/^added \d+ packages/.test(trimmed)) {
+				s.message('Finalizing installation');
+				return;
+			}
+			// "reify:foo: timing reifyNode..." — npm 8/9/10 progress lines.
+			// Pull the package name out and show it.
+			const reify = trimmed.match(/^reify:([^:]+):/);
+			if (reify) {
+				s.message(`Installing ${pc.cyan(reify[1])}`);
+				return;
+			}
+			// "npm WARN ..." / "npm error ..." — pass through prefixed.
+			if (/^npm (WARN|error|notice)/.test(trimmed)) {
+				// Don't change the spinner message for these — they're noisy.
+				return;
+			}
+		};
+
+		// Spawn npm with --loglevel=info so we get reify: progress lines.
+		// We DO NOT use stdio: 'inherit' because that would interleave with
+		// the spinner; we DO want a live read so we can update the message.
+		const child = spawn('npm', ['install', '--loglevel=info'], {
+			cwd,
+			stdio: ['ignore', 'pipe', 'pipe'],
+			shell: process.platform === 'win32'
+		});
+
+		let sawBrokenVersion = false;
+		const handleStream = (stream) => {
+			let buf = '';
+			stream.setEncoding('utf8');
+			stream.on('data', (chunk) => {
+				buf += chunk;
+				const lines = buf.split('\n');
+				buf = lines.pop() ?? '';
+				for (const line of lines) {
+					remember(line);
+					updateProgress(line);
+					if (line.includes('@selvajs/selva@0.10.2')) sawBrokenVersion = true;
+				}
+			});
+			stream.on('end', () => {
+				if (buf) {
+					remember(buf);
+					updateProgress(buf);
+				}
+			});
+		};
+		handleStream(child.stdout);
+		handleStream(child.stderr);
+
+		child.on('error', (err) => {
+			s.stop(pc.red('npm install could not start'));
+			rejectP(err);
+		});
+
+		child.on('close', (code) => {
+			if (code === 0) {
+				s.stop(pc.green('Dependencies installed'));
+				resolveP();
+				return;
+			}
+			s.stop(pc.red(`npm install failed (exit ${code})`));
+
+			// Show what npm actually said. Without this the operator has to
+			// dig through ~/.npm/_logs/*-debug-0.log to find a single line.
+			console.error('');
+			console.error(pc.dim('── last lines of npm output ──'));
+			for (const line of tail) console.error(line);
+			console.error(pc.dim('──────────────────────────────'));
+
+			if (sawBrokenVersion) {
+				console.error('');
+				console.error(
+					pc.yellow(
+						'npm resolved @selvajs/selva@0.10.2 — that version is broken (unresolved\n' +
+							"workspace:* / catalog: specs) and has been unpublished. Your local npm\n" +
+							'cache is stale. Clear it and retry:\n\n' +
+							'  npm cache clean --force\n' +
+							'  rm -rf node_modules package-lock.json\n' +
+							'  npm install --prefer-online'
+					)
+				);
+			}
+
+			rejectP(new Error(`npm install exited with code ${code}`));
+		});
+	});
+}
+
+function parseArgs(argv) {
+	let dir;
+	let force = false;
+	let skipInstall = false;
+	let yes = false;
+	for (const arg of argv) {
+		if (arg === '--force') force = true;
+		else if (arg === '--skip-install') skipInstall = true;
+		else if (arg === '--yes' || arg === '-y') yes = true;
+		else if (arg.startsWith('--')) {
+			throw new Error(`Unknown flag: ${arg}`);
+		} else if (!dir) {
+			dir = arg;
+		} else {
+			throw new Error(`Unexpected argument: ${arg}`);
+		}
+	}
+	if (!dir) {
+		throw new Error(
+			'Usage: npx @selvajs/cli <directory> [--force] [--skip-install] [--yes]'
+		);
+	}
+	return { dir, force, skipInstall, yes };
+}
+
+function envBool(v) {
+	if (!v) return false;
+	return ['1', 'true', 'yes'].includes(String(v).toLowerCase());
+}
+
+// The deployment's package.json depends on @selvajs/selva (prebuilt
+// SvelteKit app) plus whichever providers the operator picked. Providers are
+// imported by selva.config.js — npm needs them resolvable from node_modules.
+//
+// We also list @selvajs/cli itself as a dep so the `selva` bin gets linked
+// into node_modules/.bin/. Without this the operator's only way to run
+// `selva doctor` / `selva start` is a global install of the CLI.
+function buildPackageJson(name, values) {
+	const deps = {
+		'@selvajs/cli': 'latest',
+		'@selvajs/platform': 'latest',
+		'@selvajs/selva': 'latest',
+		// pm2 lives in the deployment's own node_modules so `selva start` can
+		// resolve it via node_modules/.bin/pm2 without a global install. The
+		// pm2.js wrapper already prefers the local binary (see pm2Bin()).
+		pm2: '^5.4.0'
+	};
+
+	const providers = new Set([
+		values.SELVA_AUTH_PROVIDER,
+		values.SELVA_DATA_PROVIDER,
+		values.SELVA_STORAGE_PROVIDER
+	]);
+
+	if (providers.has('local')) deps['@selvajs/local-provider'] = 'latest';
+	if (providers.has('supabase')) deps['@selvajs/supabase-provider'] = 'latest';
+	if (providers.has('header')) deps['@selvajs/header-auth-provider'] = 'latest';
+
+	// Use `selva` (resolved via node_modules/.bin) in the npm scripts. Running
+	// them as `npm run start` / `npm run doctor` works without remembering the
+	// ./node_modules/.bin/ prefix.
+	const pkg = {
+		name: sanitizePackageName(name),
+		version: '0.1.0',
+		private: true,
+		type: 'module',
+		scripts: {
+			start: 'selva start',
+			stop: 'selva stop',
+			restart: 'selva restart',
+			logs: 'selva logs',
+			doctor: 'selva doctor',
+			update: 'selva update'
+		},
+		dependencies: deps
+	};
+	return JSON.stringify(pkg, null, 2);
+}
+
+function sanitizePackageName(name) {
+	// npm package names: lowercase, no spaces, limited punctuation.
+	return (
+		name
+			.toLowerCase()
+			.replace(/[^a-z0-9._-]+/g, '-')
+			.replace(/^[-._]+|[-._]+$/g, '') || 'selva-deployment'
+	);
+}
+
+function writeGitignore(dir) {
+	const path = join(dir, '.gitignore');
+	if (existsSync(path)) return;
+	writeFileSync(
+		path,
+		['node_modules/', '.env', '.env.local', '.selva-data/', 'logs/', '*.log', ''].join('\n'),
+		'utf8'
+	);
+}