@harperfast/harper 5.0.25 → 5.1.0-beta.1

package/bin/deployRenderer.ts

@@ -0,0 +1,196 @@
+import { Transform } from 'node:stream';
+// cli-progress is already a runtime dep of harper (see package.json); using its
+// SingleBar to render the upload phase here doesn't add a new dependency.
+import cliProgress from 'cli-progress';
+import type { SSEMessage } from './sseConsumer.ts';
+
+interface RendererOptions {
+	uploadTotal?: number;
+	output?: NodeJS.WritableStream;
+}
+
+interface UploadState {
+	bar: cliProgress.SingleBar | null;
+	sent: number;
+	finished: boolean;
+}
+
+interface PhaseState {
+	current?: string;
+	installManager?: string;
+	installLineCount: number;
+}
+
+/**
+ * Deploy-time renderer that owns the progress display across two phases:
+ *
+ *   1. Local upload — driven by `tapUploadStream`, which wraps the multipart body so we
+ *      can update a `cli-progress` bar against the precomputed uncompressed source-tree
+ *      total. The bar moves as gzipped bytes are sent and snaps to 100% on completion.
+ *      In a non-TTY environment a single "Uploaded X MiB" line is printed on completion.
+ *
+ *   2. Server-side phases — driven by `renderEvent`, called for each SSE message the
+ *      CLI receives from the operations API. Phase events print one-liners; live
+ *      `install` events (npm/pnpm/yarn stdout) are throttled to one line under a
+ *      "[install]" header so a noisy `npm install` doesn't drown the terminal.
+ *
+ * Designed so the two phases hand off cleanly: `endUpload()` tears the bar down (so
+ * it doesn't compete with subsequent prints) before any SSE events render.
+ */
+export class DeployRenderer {
+	private upload: UploadState = { bar: null, sent: 0, finished: false };
+	private phase: PhaseState = { installLineCount: 0 };
+	private output: NodeJS.WritableStream;
+	private isTty: boolean;
+	private uploadTotal: number;
+
+	constructor(options: RendererOptions = {}) {
+		this.output = options.output ?? process.stderr;
+		// Only render a bar when stderr is a real terminal. CI runners, log redirection,
+		// and pipes look identical from Node's perspective: !isTTY.
+		this.isTty = Boolean((this.output as NodeJS.WriteStream).isTTY);
+		this.uploadTotal = options.uploadTotal ?? 0;
+	}
+
+	/**
+	 * Wrap an outbound stream so each byte flowing through it advances the upload bar.
+	 * The Transform is identity — chunks pass through unmodified.
+	 */
+	tapUploadStream<T extends NodeJS.ReadableStream>(stream: T): NodeJS.ReadableStream {
+		this.upload.bar = this.isTty
+			? new cliProgress.SingleBar(
+					{
+						// {value_fmt} and {total_fmt} are payload tokens updated in tickUpload/endUpload.
+						// uploadTotal is the uncompressed source size; gzip output is smaller so the
+						// bar won't naturally reach 100% — endUpload() snaps it on completion.
+						format: 'Uploading [{bar}] {percentage}% | {value_fmt} / ~{total_fmt}',
+						barCompleteChar: '█',
+						barIncompleteChar: '░',
+						hideCursor: true,
+						stream: this.output,
+					},
+					cliProgress.Presets.shades_classic
+				)
+			: null;
+		this.upload.bar?.start(this.uploadTotal || 1, 0, {
+			value_fmt: formatBytes(0),
+			total_fmt: formatBytes(this.uploadTotal),
+		});
+
+		const counter = new Transform({
+			transform: (chunk, _enc, cb) => {
+				// Bytes are counted externally via countUploadBytes() on the pre-gzip tar
+				// stream so progress and total are both in uncompressed units. The Transform
+				// is kept here solely to get the flush callback that signals upload completion.
+				cb(null, chunk);
+			},
+			flush: (cb) => {
+				this.endUpload();
+				cb();
+			},
+		});
+		stream.on('error', (err) => counter.destroy(err));
+		stream.pipe(counter);
+		return counter;
+	}
+
+	/**
+	 * Record `n` pre-gzip bytes read from the tar pack stream. Called for each
+	 * raw tar chunk by the `onBytes` callback passed to `streamPackagedDirectory`,
+	 * keeping progress and total in the same (uncompressed) unit so the bar
+	 * tracks smoothly and doesn't terminate far short of 100%.
+	 */
+	countUploadBytes(n: number): void {
+		if (this.upload.finished) return;
+		this.upload.sent += n;
+		this.tickUpload();
+	}
+
+	endUpload(): void {
+		if (this.upload.finished) return;
+		this.upload.finished = true;
+		if (this.upload.bar) {
+			// Snap to total so the bar shows 100% even when our uncompressed-total estimate
+			// is slightly off (gzip output is usually smaller than the source tree).
+			const finalPayload = { value_fmt: formatBytes(this.upload.sent), total_fmt: formatBytes(this.uploadTotal) };
+			if (this.uploadTotal > 0) this.upload.bar.update(this.uploadTotal, finalPayload);
+			this.upload.bar.stop();
+			this.upload.bar = null;
+		} else {
+			// Non-TTY: single completion line, no intermediate chatter.
+			this.output.write(`Uploaded ${formatBytes(this.upload.sent)}\n`);
+		}
+	}
+
+	private tickUpload(): void {
+		if (this.upload.finished) return;
+		if (this.upload.bar) {
+			this.upload.bar.update(this.upload.sent, { value_fmt: formatBytes(this.upload.sent) });
+		}
+		// Non-TTY: no intermediate lines — endUpload() prints the final size on completion.
+	}
+
+	renderEvent(message: SSEMessage): void {
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(message.data);
+		} catch {
+			parsed = message.data;
+		}
+		switch (message.event) {
+			case 'phase':
+				this.renderPhase(parsed as { phase?: string; status?: string; message?: string });
+				break;
+			case 'install':
+				this.renderInstall(parsed as { manager?: string; stream?: string; line?: string });
+				break;
+			case 'error': {
+				const e = parsed as { message?: string; code?: string | number };
+				this.output.write(`error: ${e.message ?? message.data}${e.code ? ` (${e.code})` : ''}\n`);
+				break;
+			}
+			case 'done':
+				// Caller picks up final result via the SSE iterator; nothing to render here.
+				break;
+		}
+	}
+
+	private renderPhase(data: { phase?: string; status?: string; message?: string }): void {
+		const label = data.phase ?? '?';
+		if (data.status === 'start') {
+			if (this.phase.current !== label) {
+				this.output.write(`${label}…\n`);
+				this.phase.current = label;
+				this.phase.installLineCount = 0;
+			}
+		} else if (data.status === 'done') {
+			if (label === 'install' && this.phase.installLineCount > 0) {
+				this.output.write(`install done (${this.phase.installLineCount} log lines)\n`);
+			} else {
+				this.output.write(`${label} done\n`);
+			}
+		} else if (data.status === 'error') {
+			this.output.write(`${label} ERROR: ${data.message ?? 'failed'}\n`);
+		}
+	}
+
+	private renderInstall(data: { manager?: string; stream?: string; line?: string }): void {
+		const line = (data.line ?? '').trimEnd();
+		if (!line) return;
+		if (data.manager && data.manager !== this.phase.installManager) {
+			this.phase.installManager = data.manager;
+			this.output.write(`install: using ${data.manager}\n`);
+		}
+		this.phase.installLineCount++;
+		// Prefix with stream so users can distinguish stderr noise from stdout warnings.
+		const tag = data.stream === 'stderr' ? '!' : '|';
+		this.output.write(`  ${tag} ${line}\n`);
+	}
+}
+
+function formatBytes(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KiB`;
+	if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+	return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GiB`;
+}

package/bin/{harper.js → harper.ts}

@@ -1,21 +1,25 @@
 #!/usr/bin/env node
 'use strict';
 
-const fs = require('node:fs');
-const path = require('node:path');
-const logger = require('../utility/logging/harper_logger.js');
-const cliOperations = require('./cliOperations.js');
-const { packageJson } = require('../utility/packageUtils.js');
-const checkNode = require('../launchServiceScripts/utility/checkNodeVersion.js');
-const hdbTerms = require('../utility/hdbTerms.ts');
-const { SERVICE_ACTIONS_ENUM } = hdbTerms;
-process.setSourceMapsEnabled(true); // this is necessary for source maps to work, at least on the main thread.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import logger from '../utility/logging/harper_logger.ts';
+import * as cliOperations from './cliOperations.ts';
+import { packageJson } from '../utility/packageUtils.js';
+import checkNode from '../launchServiceScripts/utility/checkNodeVersion.js';
+import * as hdbTerms from '../utility/hdbTerms.ts';
+const { SERVICE_ACTIONS_ENUM } = hdbTerms as any;
+if (typeof process.setSourceMapsEnabled === 'function') {
+	process.setSourceMapsEnabled(true); // this is necessary for source maps to work, at least on the main thread.
+}
 
 const HELP = `
 Usage: harperdb [command]
 
 With no command, harper will simply run Harper (in the foreground)
 
+Documentation: https://docs.harperdb.io/
+
 By default, the CLI also supports certain Operation APIs. Specify the operation name and any required parameters, and omit the 'operation' command.
 
 Commands:
@@ -23,6 +27,9 @@ copy-db <source> <target>       - Copies a database from source path to target p
 dev <path>                      - Run the application in dev mode with debugging, foreground logging, no auth
 install                         - Install harperdb
 <api-operation> <param>=<value> - Run an API operation and return result to the CLI, not all operations are supported
+login [target] [username]       - Login to a remote or local Harper instance
+logout [target]                 - Logout from Harper and clear saved JWT
+mcp [subcommand]                - MCP stdio bridge / print-config / doctor (see 'harper mcp help')
 register                        - Register harperdb
 renew-certs                     - Generate a new set of self-signed certificates
 restart                         - Restart the harperdb background process
@@ -60,15 +67,15 @@ async function harper() {
 		case SERVICE_ACTIONS_ENUM.HELP:
 			return HELP;
 		case SERVICE_ACTIONS_ENUM.START:
-			return require('./run.js').launch();
+			return require('./run').launch();
 		case SERVICE_ACTIONS_ENUM.INSTALL:
-			return require('./install.js')();
+			return (require('./install').default || require('./install'))();
 		case SERVICE_ACTIONS_ENUM.STOP:
-			return require('./stop.js')().then(() => {
+			return (require('./stop').default || require('./stop'))().then(() => {
 				process.exit(0);
 			});
 		case SERVICE_ACTIONS_ENUM.RESTART:
-			return require('./restart.js').restart({});
+			return require('./restart').restart({});
 		case SERVICE_ACTIONS_ENUM.VERSION:
 			return packageJson.version;
 		case SERVICE_ACTIONS_ENUM.UPGRADE:
@@ -78,18 +85,35 @@ async function harper() {
 				.upgrade(null)
 				.then(() => 'Your instance of Harper is up to date!');
 		case SERVICE_ACTIONS_ENUM.STATUS:
-			return require('./status.js')();
+			return (require('./status').default || require('./status'))();
+		case SERVICE_ACTIONS_ENUM.LOGIN: {
+			const target = process.argv[3];
+			const username = process.argv[4];
+			const { login } = require('./login');
+			return login(target, username);
+		}
+		case SERVICE_ACTIONS_ENUM.LOGOUT: {
+			const target = process.argv[3];
+			const { logout } = require('./logout');
+			return logout(target);
+		}
+		case SERVICE_ACTIONS_ENUM.MCP: {
+			const { runMcpCli } = require('./mcp');
+			const code = await runMcpCli(process.argv.slice(3));
+			process.exit(code);
+		}
+		// eslint-disable-next-line no-fallthrough
 		case SERVICE_ACTIONS_ENUM.RENEWCERTS:
-			return require('../security/keys.js')
+			return require('../security/keys')
 				.renewSelfSigned()
 				.then(() => 'Successfully renewed self-signed certificates');
 		case SERVICE_ACTIONS_ENUM.COPYDB: {
 			let sourceDb = process.argv[3];
 			let targetDbPath = process.argv[4];
-			return require('./copyDb.ts').copyDb(sourceDb, targetDbPath);
+			return require('./copyDb').copyDb(sourceDb, targetDbPath);
 		}
 		case SERVICE_ACTIONS_ENUM.DEV:
-			process.env.DEV_MODE = true;
+			process.env.DEV_MODE = 'true';
 		// fall through
 		case SERVICE_ACTIONS_ENUM.RUN: {
 			// Run a specific application folder
@@ -126,7 +150,7 @@ async function harper() {
 		}
 		// fall through
 		case undefined: // run harperdb in the foreground in standard mode
-			return require('./run.js').main();
+			return require('./run').main();
 		default:
 			const cliApiOp = cliOperations.buildRequest();
 			logger.trace('calling cli operations with:', cliApiOp);
@@ -134,7 +158,7 @@ async function harper() {
 			return;
 	}
 }
-exports.harper = harper;
+export { harper };
 if (require.main === module) {
 	harper()
 		.then((message) => {

package/bin/{install.js → install.ts}

@@ -1,7 +1,7 @@
-const installer = require('../utility/install/installer.js');
-const hdbLogger = require('../utility/logging/harper_logger.js');
+import * as installer from '../utility/install/installer.ts';
+import hdbLogger from '../utility/logging/harper_logger.ts';
 
-module.exports = install;
+export default install;
 
 async function install() {
 	try {

package/bin/lite.ts

@@ -0,0 +1,2 @@
+import { startHTTPThreads } from '../server/threads/socketRouter.ts';
+startHTTPThreads(1);

package/bin/login.ts

@@ -0,0 +1,168 @@
+import chalk from 'chalk';
+import dotenv from 'dotenv';
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { saveCredentials, normalizeTarget } from './cliCredentials.ts';
+import { cliOperations } from './cliOperations.ts';
+
+/**
+ * Executes the login command.
+ */
+export async function login(targetArg: string, usernameArg: string): Promise<void> {
+	dotenv.config();
+
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	});
+
+	try {
+		console.log(chalk.cyan('\nHarper login'));
+		console.log(
+			chalk.gray(
+				'Harper apps can be deployed to Fabric for free, where one runtime can house your app, database, cache, and messaging.'
+			)
+		);
+		console.log(chalk.gray('https://fabric.harper.fast/\n'));
+		console.log(
+			chalk.gray('If you create a cluster, you can enter your credentials here. They will be exchanged for a JWT from')
+		);
+		console.log(chalk.gray('your cluster, which will be saved inside ~/.harperdb/credentials.json\n'));
+
+		const defaultTarget = process.env.HARPER_CLI_TARGET || process.env.CLI_TARGET;
+		let target = targetArg || defaultTarget;
+		let skipTargetPrompt = !!targetArg;
+
+		if (!skipTargetPrompt) {
+			if (defaultTarget) {
+				const input = await rl.question(`Cluster Target [${defaultTarget}]: `);
+				if (input.trim()) {
+					target = input.trim();
+				}
+			} else {
+				target = await rl.question(`Cluster Target URL: `);
+			}
+		}
+
+		if (!target) {
+			console.error(chalk.red('Target URL is required.'));
+			process.exit(1);
+		}
+
+		target = normalizeTarget(target);
+
+		let targetUsername = usernameArg;
+		if (!targetUsername) {
+			if (process.env.CLI_TARGET_USERNAME) {
+				targetUsername = process.env.CLI_TARGET_USERNAME;
+				console.log(chalk.gray(`Using username from CLI_TARGET_USERNAME environment variable: ${targetUsername}`));
+			} else if (process.env.HARPER_CLI_USERNAME) {
+				targetUsername = process.env.HARPER_CLI_USERNAME;
+				console.log(chalk.gray(`Using username from HARPER_CLI_USERNAME environment variable: ${targetUsername}`));
+			} else {
+				targetUsername = await rl.question(`Cluster Username: `);
+			}
+		}
+
+		let targetPassword = process.env.CLI_TARGET_PASSWORD || process.env.HARPER_CLI_PASSWORD;
+
+		if (targetPassword) {
+			const envVarName = process.env.CLI_TARGET_PASSWORD ? 'CLI_TARGET_PASSWORD' : 'HARPER_CLI_PASSWORD';
+			console.log(chalk.gray(`Using password from ${envVarName} environment variable.`));
+		} else {
+			targetPassword = await new Promise((resolve) => {
+				process.stdout.write(`Cluster Password: `);
+				process.stdin.setRawMode(true);
+				process.stdin.resume();
+				let password = '';
+				const onData = (data: Buffer) => {
+					for (let i = 0; i < data.length; i++) {
+						const char = data[i];
+						if (char === 13 || char === 10) {
+							// \r or \n
+							process.stdout.write('\n');
+							cleanup();
+							resolve(password);
+							return;
+						} else if (char === 3) {
+							// Ctrl+C
+							process.stdout.write('\n');
+							cleanup();
+							process.exit(1);
+						} else if (char === 8 || char === 127) {
+							// Backspace
+							if (password.length > 0) {
+								password = password.slice(0, -1);
+								process.stdout.write('\b \b');
+							}
+						} else {
+							password += data.toString('utf-8', i, i + 1);
+							process.stdout.write('*');
+						}
+					}
+				};
+
+				const cleanup = () => {
+					process.stdin.removeListener('data', onData);
+					process.stdin.setRawMode(false);
+					process.stdin.pause();
+				};
+
+				process.stdin.on('data', onData);
+			});
+		}
+
+		if (!targetUsername || !targetPassword) {
+			console.error('Username and password are required.');
+			process.exit(1);
+		}
+
+		const req = {
+			operation: 'create_authentication_tokens',
+			username: targetUsername,
+			password: targetPassword,
+			target,
+		};
+
+		const response = await cliOperations(req, true);
+
+		if (response && response.operation_token) {
+			const resolvedTarget = response.target || req.target || response.resolvedTarget || target;
+			try {
+				saveCredentials(resolvedTarget, {
+					operation_token: response.operation_token,
+					refresh_token: response.refresh_token,
+				});
+			} catch (err) {
+				console.error(chalk.red(err.message));
+				process.exit(1);
+			}
+
+			// If CLI_TARGET is not in process.env before we started (meaning it's not in .env or other env vars),
+			// and we just logged in with a target, let's consider adding it to .env
+			const envPath = path.join(process.cwd(), '.env');
+			if (fs.existsSync(envPath)) {
+				const envConfig = dotenv.parse(fs.readFileSync(envPath));
+
+				if (
+					!envConfig.CLI_TARGET &&
+					!envConfig.HARPER_CLI_TARGET &&
+					!process.env.CLI_TARGET &&
+					!process.env.HARPER_CLI_TARGET
+				) {
+					const envLine = `\nHARPER_CLI_TARGET=${resolvedTarget}\n`;
+					fs.appendFileSync(envPath, envLine);
+					console.log(`Added HARPER_CLI_TARGET to .env`);
+				}
+			}
+
+			console.log(`Successfully logged in to ${resolvedTarget} and saved credentials.`);
+			process.exit(0);
+		} else {
+			throw new Error('Failed to retrieve authentication tokens.');
+		}
+	} finally {
+		rl.close();
+	}
+}

package/bin/logout.ts

@@ -0,0 +1,11 @@
+import dotenv from 'dotenv';
+import { clearCredentials } from './cliCredentials.ts';
+
+/**
+ * Executes the logout command.
+ */
+export async function logout(target?: string): Promise<void> {
+	dotenv.config();
+
+	clearCredentials(target);
+}