@harperfast/harper 5.0.25 → 5.1.0-beta.1

package/bin/mcp/options.ts

@@ -0,0 +1,122 @@
+/**
+ * Argument and environment resolution for `harper mcp`. The CLI deliberately
+ * avoids pulling in a flag-parsing dep (Harper's no-new-deps policy) — a few
+ * `--key=value` and `--key value` arguments plus a positional subcommand is
+ * the entire vocabulary.
+ *
+ * Two connection modes:
+ *   - **UDS** (default): connects to the locally-running Harper instance via
+ *     the operationsApi domain socket. **Only the operations profile is
+ *     reachable this way** — the application profile is mounted on the
+ *     application HTTP server, which doesn't expose a UDS in v1. Filesystem
+ *     permissions on the operations socket are the access gate; no
+ *     credentials are required or sent.
+ *   - **HTTPS**: `--target https://host:port` connects over the network.
+ *     Required for `--profile application`. Credential precedence
+ *     (highest first):
+ *       `--bearer` > `--username` + `--password` > URL-embedded user/pass
+ *       > saved JWT from `~/.harperdb/credentials.json` (populated by
+ *       `harper login` and looked up via `cliCredentials.normalizeTarget`).
+ */
+
+export interface McpCliOptions {
+	subcommand: 'bridge' | 'print-config' | 'doctor' | 'help';
+	profile: 'operations' | 'application';
+	target?: string;
+	mountPath: string;
+	username?: string;
+	password?: string;
+	bearer?: string;
+	rejectUnauthorized: boolean;
+	client?: 'claude-desktop' | 'cursor' | 'zed';
+	help: boolean;
+}
+
+export function parseArgs(argv: readonly string[]): McpCliOptions {
+	const opts: McpCliOptions = {
+		subcommand: 'bridge',
+		// Operations is the safer default: the typical zero-config path
+		// (`harper mcp` / `harper mcp doctor` on the local machine, no
+		// --target) connects over the operations UDS, which only routes
+		// to the operations MCP endpoint in v1.
+		profile: 'operations',
+		mountPath: '/mcp',
+		rejectUnauthorized: true,
+		help: false,
+	};
+
+	// argv begins after `harper mcp`, i.e. process.argv.slice(3).
+	let i = 0;
+	if (argv[0] && !argv[0].startsWith('-')) {
+		const sub = argv[0];
+		if (sub === 'print-config' || sub === 'doctor' || sub === 'help') {
+			opts.subcommand = sub;
+			i = 1;
+		} else if (sub === 'bridge') {
+			opts.subcommand = 'bridge';
+			i = 1;
+		}
+		// anything else: assume it's a flag-style arg or noise; leave i=0.
+	}
+
+	for (; i < argv.length; i++) {
+		const arg = argv[i];
+		const eq = arg.indexOf('=');
+		const isLong = arg.startsWith('--');
+		const key = isLong ? (eq === -1 ? arg.slice(2) : arg.slice(2, eq)) : arg;
+		const valueInline = eq === -1 ? undefined : arg.slice(eq + 1);
+		const consumeNext = (): string | undefined => {
+			if (valueInline !== undefined) return valueInline;
+			const next = argv[i + 1];
+			if (next === undefined || next.startsWith('-')) return undefined;
+			i++;
+			return next;
+		};
+
+		switch (key) {
+			case '--profile':
+			case 'profile': {
+				const v = consumeNext();
+				if (v === 'operations' || v === 'application') opts.profile = v;
+				break;
+			}
+			case '--target':
+			case 'target':
+				opts.target = consumeNext();
+				break;
+			case '--mount-path':
+			case 'mount-path':
+				opts.mountPath = consumeNext() ?? opts.mountPath;
+				break;
+			case '--username':
+			case 'username':
+				opts.username = consumeNext();
+				break;
+			case '--password':
+			case 'password':
+				opts.password = consumeNext();
+				break;
+			case '--bearer':
+			case 'bearer':
+				opts.bearer = consumeNext();
+				break;
+			case '--insecure':
+			case 'insecure':
+				opts.rejectUnauthorized = false;
+				break;
+			case '--client':
+			case 'client': {
+				const v = consumeNext();
+				if (v === 'claude-desktop' || v === 'cursor' || v === 'zed') opts.client = v;
+				break;
+			}
+			case '--help':
+			case 'help':
+			case '-h':
+				opts.help = true;
+				break;
+		}
+	}
+
+	return opts;
+}

package/bin/mcp/printConfig.ts

@@ -0,0 +1,89 @@
+/**
+ * Emit a paste-ready config block for each supported MCP client. Output
+ * goes to stdout so the user can pipe or copy directly into their
+ * client's config file.
+ */
+import type { McpCliOptions } from './options.ts';
+
+interface ConfigBlock {
+	target: string;
+	body: object;
+	notes: readonly string[];
+}
+
+export function renderConfig(opts: McpCliOptions): ConfigBlock {
+	const client = opts.client ?? 'claude-desktop';
+	const args = ['mcp'];
+	// Default is 'operations'; only emit the flag when overriding to 'application'.
+	if (opts.profile !== 'operations') args.push('--profile', opts.profile);
+	if (opts.target) args.push('--target', opts.target);
+	if (opts.mountPath !== '/mcp') args.push('--mount-path', opts.mountPath);
+	if (opts.username) args.push('--username', opts.username);
+	if (opts.password) args.push('--password', opts.password);
+	if (opts.bearer) args.push('--bearer', opts.bearer);
+	if (!opts.rejectUnauthorized) args.push('--insecure');
+
+	switch (client) {
+		case 'claude-desktop': {
+			return {
+				target:
+					'~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\\Claude\\claude_desktop_config.json (Windows)',
+				body: {
+					mcpServers: {
+						harper: {
+							command: 'harper',
+							args,
+						},
+					},
+				},
+				notes: [
+					'Restart Claude Desktop after editing the file.',
+					'Merge into an existing `mcpServers` block if you already have one.',
+				],
+			};
+		}
+		case 'cursor': {
+			return {
+				target: '~/.cursor/mcp.json',
+				body: {
+					mcpServers: {
+						harper: {
+							command: 'harper',
+							args,
+						},
+					},
+				},
+				notes: ['Cursor reads this file at startup; restart after editing.'],
+			};
+		}
+		case 'zed': {
+			return {
+				target: 'Zed settings.json',
+				body: {
+					context_servers: {
+						harper: {
+							command: {
+								path: 'harper',
+								args,
+								env: {},
+							},
+						},
+					},
+				},
+				notes: ["Zed's MCP support is behind a feature flag — see the Zed docs for activation."],
+			};
+		}
+		default:
+			throw new Error(`harper mcp print-config: unknown --client '${client as string}'`);
+	}
+}
+
+export function emit(opts: McpCliOptions, stdout: NodeJS.WritableStream = process.stdout): void {
+	const block = renderConfig(opts);
+	stdout.write(`# Target file: ${block.target}\n`);
+	stdout.write(JSON.stringify(block.body, null, 2));
+	stdout.write('\n');
+	for (const note of block.notes) {
+		stdout.write(`# Note: ${note}\n`);
+	}
+}

package/bin/multipartBuilder.ts

@@ -0,0 +1,74 @@
+import { randomBytes } from 'node:crypto';
+import { Readable } from 'node:stream';
+
+interface MultipartFile {
+	name: string;
+	filename: string;
+	contentType?: string;
+	stream: Readable;
+}
+
+interface MultipartBody {
+	boundary: string;
+	contentType: string;
+	stream: Readable;
+}
+
+/**
+ * Build a streaming multipart/form-data body for the operations API.
+ *
+ * Fields are emitted first, in the order they appear in the `fields` record, then the
+ * single (optional) file part. That ordering is required by the server-side multipart
+ * parser (`server/serverHelpers/multipartParser.ts`): dispatching fields like `operation`
+ * must arrive before the file so preValidation/auth hooks can see them, and the file
+ * always comes last so the route handler streams it into extraction.
+ *
+ * Each field value is JSON-stringified — the server parser will reverse that on values
+ * that look like JSON, otherwise leave them as raw strings.
+ */
+export function buildMultipartBody(fields: Record<string, unknown>, file?: MultipartFile): MultipartBody {
+	const boundary = '----HarperMultipart' + randomBytes(12).toString('hex');
+	const stream = Readable.from(generateParts(boundary, fields, file));
+	return {
+		boundary,
+		contentType: `multipart/form-data; boundary=${boundary}`,
+		stream,
+	};
+}
+
+async function* generateParts(
+	boundary: string,
+	fields: Record<string, unknown>,
+	file: MultipartFile | undefined
+): AsyncGenerator<Buffer> {
+	const dashBoundary = `--${boundary}`;
+	for (const [name, value] of Object.entries(fields)) {
+		if (value === undefined) continue;
+		yield Buffer.from(
+			`${dashBoundary}\r\nContent-Disposition: form-data; name="${escapeFieldName(name)}"\r\n\r\n${serializeFieldValue(value)}\r\n`
+		);
+	}
+	if (file) {
+		const contentType = file.contentType ?? 'application/octet-stream';
+		yield Buffer.from(
+			`${dashBoundary}\r\nContent-Disposition: form-data; name="${escapeFieldName(file.name)}"; filename="${escapeFieldName(file.filename)}"\r\nContent-Type: ${contentType}\r\n\r\n`
+		);
+		for await (const chunk of file.stream) {
+			yield typeof chunk === 'string' ? Buffer.from(chunk) : (chunk as Buffer);
+		}
+		yield Buffer.from('\r\n');
+	}
+	yield Buffer.from(`${dashBoundary}--\r\n`);
+}
+
+function serializeFieldValue(value: unknown): string {
+	if (typeof value === 'string') return value;
+	return JSON.stringify(value);
+}
+
+function escapeFieldName(name: string): string {
+	// Strip CR/LF and quote characters that would break the Content-Disposition header.
+	// Field/file names are caller-controlled CLI values so this is defense-in-depth, not
+	// untrusted-input sanitization.
+	return name.replace(/[\r\n"]/g, '');
+}

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

@@ -1,18 +1,18 @@
 'use strict';
 
-const minimist = require('minimist');
-const { isMainThread, parentPort } = require('worker_threads');
-const hdbTerms = require('../utility/hdbTerms.ts');
-const hdbLogger = require('../utility/logging/harper_logger.js');
-const processMan = require('../utility/processManagement/processManagement.js');
-const { compactOnStart } = require('./copyDb.ts');
-const { restartWorkers, onMessageByType, shutdownWorkersNow } = require('../server/threads/manageThreads.js');
-const { handleHDBError, hdbErrors } = require('../utility/errors/hdbError.js');
+import minimist from 'minimist';
+import { isMainThread, parentPort } from 'worker_threads';
+import * as hdbTerms from '../utility/hdbTerms.ts';
+import hdbLogger from '../utility/logging/harper_logger.ts';
+import * as processMan from '../utility/processManagement/processManagement.js';
+import { compactOnStart } from './copyDb.ts';
+import { restartWorkers, onMessageByType, shutdownWorkersNow } from '../server/threads/manageThreads.js';
+import { handleHDBError, hdbErrors } from '../utility/errors/hdbError.ts';
 const { HTTP_STATUS_CODES } = hdbErrors;
-const envMgr = require('../utility/environment/environmentManager.js');
-const path = require('node:path');
-const { unlinkSync } = require('node:fs');
-const { getThisNodeName } = require('../server/nodeName.ts');
+import * as envMgr from '../utility/environment/environmentManager.ts';
+import * as path from 'node:path';
+import { unlinkSync } from 'node:fs';
+import { getThisNodeName } from '../server/nodeName.ts';
 envMgr.initSync();
 
 const RESTART_RESPONSE = `Restarting Harper. This may take up to ${hdbTerms.RESTART_TIMEOUT_MS / 1000} seconds.`;
@@ -20,10 +20,7 @@ const INVALID_SERVICE_ERR = 'Invalid service';
 
 let calledFromCli;
 
-module.exports = {
-	restart,
-	restartService,
-};
+export { restart, restartService };
 
 // Add ITC event listener to main thread which will be called from child that receives restart request.
 if (isMainThread) {
@@ -40,7 +37,7 @@ if (isMainThread) {
  * @param req
  * @returns {Promise<string>}
  */
-async function restart(req) {
+async function restart(req: any) {
 	calledFromCli = Object.keys(req).length === 0;
 
 	const cliArgs = minimist(process.argv);
@@ -52,7 +49,7 @@ async function restart(req) {
 	if (calledFromCli) {
 		const hdbPid = processMan.getHdbPid();
 		console.error(hdbPid ? 'Restarting Harper...' : 'Starting Harper...');
-		require('./run.js').launch(true);
+		require('./run').launch(true);
 		return RESTART_RESPONSE;
 	}
 
@@ -69,9 +66,11 @@ async function restart(req) {
 			// and shut down.
 			hdbLogger.debug('Shutdown workers');
 			await shutdownWorkersNow();
+			const { closeServers } = require('../server/threads/threadServer.js');
+			await closeServers();
 			await processMan.cleanupChildrenProcesses(false);
 			// remove pid file so it doesn't trip up the launch
-			await unlinkSync(path.join(envMgr.get(hdbTerms.CONFIG_PARAMS.ROOTPATH), hdbTerms.HDB_PID_FILE), `${process.pid}`);
+			unlinkSync(path.join(envMgr.get(hdbTerms.CONFIG_PARAMS.ROOTPATH), hdbTerms.HDB_PID_FILE));
 			hdbLogger.debug('Starting new process...');
 			if (process.env.HARPER_EXIT_ON_RESTART) {
 				// use this to exit the process so that it will be restarted by the
@@ -80,7 +79,7 @@ async function restart(req) {
 				process.exit(0);
 			}
 			// now launch the new process and exit this process
-			require('./run.js').launch(true);
+			require('./run').launch(true);
 		}, 50); // can't await this because it is going to do an exit(), but wait for 50ms so we give the HTTP thread a
 		// chance to return a response
 	} else {
@@ -98,7 +97,7 @@ async function restart(req) {
  * @param req
  * @returns {Promise<string>}
  */
-async function restartService(req) {
+async function restartService(req: any) {
 	let { service } = req;
 	if (hdbTerms.HDB_PROCESS_SERVICES[service] === undefined) {
 		throw handleHDBError(new Error(), INVALID_SERVICE_ERR, HTTP_STATUS_CODES.BAD_REQUEST, undefined, undefined, true);
@@ -106,14 +105,14 @@ async function restartService(req) {
 	processMan.expectedRestartOfChildren();
 	if (!isMainThread) {
 		if (req.replicated) {
-			server.replication.monitorNodeCAs(); // get all the CAs from the nodes we know about
+			(global as any).server.replication.monitorNodeCAs(); // get all the CAs from the nodes we know about
 		}
 		parentPort.postMessage({
 			type: hdbTerms.ITC_EVENT_TYPES.RESTART,
 			workerType: service,
 		});
 		parentPort.ref(); // don't let the parent thread exit until we're done
-		await new Promise((resolve) => {
+		await new Promise<void>((resolve) => {
 			parentPort.on('message', (msg) => {
 				if (msg.type === 'restart-complete') {
 					resolve();
@@ -125,12 +124,12 @@ async function restartService(req) {
 		if (req.replicated) {
 			req.replicated = false; // don't send a replicated flag to the nodes we are sending to
 			replicatedResponses = [];
-			for (let node of server.nodes) {
+			for (let node of (global as any).server.nodes) {
 				if (node.name === getThisNodeName()) continue;
 				// for now, only one at a time
 				let job_id;
 				try {
-					({ job_id } = await server.replication.sendOperationToNode(node, req));
+					({ job_id } = await (global as any).server.replication.sendOperationToNode(node, req));
 				} catch (err) {
 					// If request to node fails, add the error to the response and continue to the next node
 					replicatedResponses.push({ node: node.name, message: err.message });
@@ -144,11 +143,11 @@ async function restartService(req) {
 						let interval = setInterval(async () => {
 							if (retriesLeft-- <= 0) {
 								clearInterval(interval);
-								let error = new Error('Timed out waiting for restart job to complete');
+								let error: any = new Error('Timed out waiting for restart job to complete');
 								error.replicated = replicatedResponses; // report the finished restarts
 								reject(error);
 							}
-							let response = await server.replication.sendOperationToNode(node, {
+							let response = await (global as any).server.replication.sendOperationToNode(node, {
 								operation: 'get_job',
 								id: job_id,
 							});
@@ -159,7 +158,7 @@ async function restartService(req) {
 							}
 							if (jobResult.status === 'ERROR') {
 								clearInterval(interval);
-								let error = new Error(jobResult.message);
+								let error: any = new Error(jobResult.message);
 								error.replicated = replicatedResponses; // report the finished restarts
 								reject(error);
 							}

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

@@ -1,33 +1,34 @@
 'use strict';
 
-const env = require('../utility/environment/environmentManager.js');
+import * as env from '../utility/environment/environmentManager.ts';
 env.initSync();
 
-// This unused restart require is here so that main thread loads ITC event listener defined in restart file. Do not remove.
-require('./restart.js');
-const terms = require('../utility/hdbTerms.ts');
+// This unused restart import is here so that main thread loads ITC event listener defined in restart file. Do not remove.
+import './restart.ts';
+import * as terms from '../utility/hdbTerms.ts';
 const { CONFIG_PARAMS } = terms;
-const hdbLogger = require('../utility/logging/harper_logger.js');
-const fs = require('fs-extra');
-const path = require('path');
-const checkJwtTokens = require('../utility/install/checkJWTTokensExist.js');
-const { install } = require('../utility/install/installer.js');
-const chalk = require('chalk');
-const { packageJson } = require('../utility/packageUtils.js');
-const hdbUtils = require('../utility/common_utils.js');
-const installation = require('../utility/installation.ts');
-const configUtils = require('../config/configUtils.js');
-const assignCMDENVVariables = require('../utility/assignCmdEnvVariables.js');
-const upgrade = require('./upgrade.js');
-const { compactOnStart, migrateOnStart } = require('./copyDb.ts');
-const minimist = require('minimist');
-const keys = require('../security/keys.js');
-const { startHTTPThreads } = require('../server/threads/socketRouter.ts');
-const hdbInfoController = require('../dataLayer/hdbInfoController.js');
-const { getThisNodeName } = require('../server/nodeName.ts');
-const hdbTerms = require('../utility/hdbTerms.ts');
-const { getHdbPid, isProcessRunning } = require('../utility/processManagement/processManagement.js');
-const { PACKAGE_ROOT } = require('../utility/packageUtils');
+import hdbLogger from '../utility/logging/harper_logger.ts';
+import * as fs from 'fs-extra';
+import * as path from 'path';
+import checkJwtTokens from '../utility/install/checkJWTTokensExist.js';
+import { install } from '../utility/install/installer.ts';
+import chalk from 'chalk';
+import { packageJson } from '../utility/packageUtils.js';
+import * as hdbUtils from '../utility/common_utils.ts';
+import * as installation from '../utility/installation.ts';
+import * as configUtils from '../config/configUtils.js';
+import assignCMDENVVariables from '../utility/assignCmdEnvVariables.ts';
+import * as upgrade from './upgrade.js';
+import { compactOnStart, migrateOnStart } from './copyDb.ts';
+import minimist from 'minimist';
+import * as keys from '../security/keys.ts';
+import { startHTTPThreads } from '../server/threads/socketRouter.ts';
+import * as hdbInfoController from '../dataLayer/hdbInfoController.ts';
+import { isReadOnlyMode } from '../resources/databases.ts';
+import { getThisNodeName } from '../server/nodeName.ts';
+import * as hdbTerms from '../utility/hdbTerms.ts';
+import { getHdbPid, isProcessRunning } from '../utility/processManagement/processManagement.js';
+import { PACKAGE_ROOT } from '../utility/packageUtils.js';
 
 let pmUtils;
 let cmdArgs;
@@ -76,6 +77,12 @@ async function initialize(calledByInstall = false, calledByMain = false) {
 	// Check to see if HDB is installed, if it isn't we call install.
 	console.log(chalk.magenta('Starting Harper...'));
 
+	// Display read-only mode warning early, before database initialization
+	if (isReadOnlyMode()) {
+		console.log(chalk.yellow('\n*** RUNNING IN READ-ONLY MODE ***'));
+		console.log(chalk.yellow('Database writes are disabled. Analytics collection is disabled.\n'));
+	}
+
 	addUnhandleRejectionListener();
 
 	hdbLogger.suppressLogging?.(() => {
@@ -101,7 +108,7 @@ async function initialize(calledByInstall = false, calledByMain = false) {
 
 		// If HARPER_SET_CONFIG is present, filter out any config keys that are set in it
 		// to prevent individual env vars from overriding explicit runtime configuration
-		const { filterArgsAgainstRuntimeConfig } = require('../config/harperConfigEnvVars.ts');
+		const { filterArgsAgainstRuntimeConfig } = require('../config/harperConfigEnvVars');
 		parsedArgs = filterArgsAgainstRuntimeConfig(parsedArgs);
 
 		if (!hdbUtils.isEmpty(parsedArgs) && !hdbUtils.isEmptyOrZeroLength(Object.keys(parsedArgs))) {
@@ -241,21 +248,25 @@ async function launch(exit = true) {
 	}
 }
 
-exports.launch = launch;
-exports.main = main;
-exports.startupLog = startupLog;
+export { launch };
+export { main };
+export { startupLog };
 
 /**
  * Logs running services and relevant ports/information.
  * Called by worker thread 1 once all servers have started
  * @param portResolutions
  */
-function startupLog(portResolutions) {
+function startupLog(portResolutions: any) {
 	// Adds padding to a string
 	const padding = 20;
 	const pad = (param) => param.padEnd(padding);
 	let logMsg = '\n';
 
+	if (isReadOnlyMode()) {
+		logMsg += `${pad('Mode:')}${chalk.yellow('READ-ONLY')}\n`;
+	}
+
 	logMsg += `${pad('Hostname:')}${getThisNodeName()}\n`;
 
 	logMsg += `${pad('Worker Threads:')}${env.get(CONFIG_PARAMS.THREADS_COUNT)}\n`;

package/bin/sseConsumer.ts

@@ -0,0 +1,126 @@
+import { StringDecoder } from 'node:string_decoder';
+import type { Readable } from 'node:stream';
+
+export interface SSEMessage {
+	event: string;
+	data: string;
+	id?: string;
+	retry?: number;
+}
+
+/**
+ * Parse a Readable carrying Server-Sent Events into structured messages.
+ *
+ * Yields one `SSEMessage` per blank-line-terminated record. Handles split data: lines,
+ * CRLF or LF line endings, and arbitrary chunk boundaries — the underlying Node http
+ * Readable does not guarantee chunks align with SSE record boundaries.
+ */
+export async function* parseSSE(stream: Readable): AsyncGenerator<SSEMessage> {
+	const decoder = new StringDecoder('utf8');
+	let buffer = '';
+	for await (const chunk of stream) {
+		buffer += typeof chunk === 'string' ? chunk : decoder.write(chunk);
+		while (true) {
+			const recordEnd = buffer.indexOf('\n\n');
+			const crlfEnd = buffer.indexOf('\r\n\r\n');
+			let endIdx = -1;
+			let delimLen = 0;
+			if (recordEnd !== -1 && (crlfEnd === -1 || recordEnd < crlfEnd)) {
+				endIdx = recordEnd;
+				delimLen = 2;
+			} else if (crlfEnd !== -1) {
+				endIdx = crlfEnd;
+				delimLen = 4;
+			}
+			if (endIdx === -1) break;
+			const record = buffer.slice(0, endIdx);
+			buffer = buffer.slice(endIdx + delimLen);
+			const msg = parseRecord(record);
+			if (msg) yield msg;
+		}
+	}
+	buffer += decoder.end();
+	// Any trailing record without a terminating blank line is treated as a final message,
+	// matching the looser behavior browsers exhibit on connection close.
+	if (buffer.trim()) {
+		const msg = parseRecord(buffer);
+		if (msg) yield msg;
+	}
+}
+
+function parseRecord(record: string): SSEMessage | null {
+	const lines = record.split(/\r?\n/);
+	let event = 'message';
+	let id: string | undefined;
+	let retry: number | undefined;
+	const dataLines: string[] = [];
+	for (const line of lines) {
+		if (line === '' || line.startsWith(':')) continue;
+		const colon = line.indexOf(':');
+		const field = colon === -1 ? line : line.slice(0, colon);
+		// Per spec, a leading space after the colon is stripped.
+		let value = colon === -1 ? '' : line.slice(colon + 1);
+		if (value.startsWith(' ')) value = value.slice(1);
+		switch (field) {
+			case 'event':
+				event = value;
+				break;
+			case 'data':
+				dataLines.push(value);
+				break;
+			case 'id':
+				id = value;
+				break;
+			case 'retry': {
+				const n = Number(value);
+				if (Number.isFinite(n)) retry = n;
+				break;
+			}
+		}
+	}
+	if (dataLines.length === 0 && event === 'message') return null;
+	return { event, data: dataLines.join('\n'), id, retry };
+}
+
+interface RenderState {
+	currentPhase?: string;
+}
+
+/**
+ * Render SSE deploy events as terse, line-oriented progress to stderr (so stdout stays
+ * reserved for the final JSON/YAML response document). Phase transitions print once.
+ */
+export function renderDeployProgress(message: SSEMessage, state: RenderState, output: NodeJS.WritableStream): void {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(message.data);
+	} catch {
+		parsed = message.data;
+	}
+	switch (message.event) {
+		case 'phase': {
+			const p = parsed as { phase?: string; status?: string; rolling?: boolean };
+			const label = p.phase ?? '?';
+			if (p.status === 'start') {
+				if (state.currentPhase !== label) {
+					output.write(`${label}…\n`);
+					state.currentPhase = label;
+				}
+			} else if (p.status === 'done') {
+				output.write(`${label} done\n`);
+			} else if (p.status === 'error') {
+				const msg = (parsed as { message?: string }).message ?? 'failed';
+				output.write(`${label} ERROR: ${msg}\n`);
+			}
+			break;
+		}
+		case 'error': {
+			const e = parsed as { message?: string; code?: string | number };
+			output.write(`error: ${e.message ?? message.data}${e.code ? ` (${e.code})` : ''}\n`);
+			break;
+		}
+		case 'done':
+			// Caller picks up the final result via the SSE iterator; nothing to render here.
+			break;
+	}
+}