@seomi/ssh 0.1.0

package/src/lib/env-writer.mjs

@@ -0,0 +1,90 @@
+/**
+ * .claude/.env writer — preserves unrelated keys and comments.
+ *
+ * Strategy: parse the existing file line-by-line into a list of items
+ * (each item is either { type: 'comment' | 'blank', text } or
+ * { type: 'kv', key, value, raw }), apply key updates in place, and
+ * append new keys at the end. Comments and ordering are preserved.
+ *
+ * This is what makes N-server setups idempotent: writing `SSH_DEV_*` keys
+ * must never clobber an already-configured `SSH_PROD_*` block.
+ */
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { logger } from './logger.mjs';
+
+const KV_RE = /^([A-Z_][A-Z0-9_]*)=(.*)$/;
+
+export function parseEnv( text ) {
+	return text.split( /\r?\n/ ).map( ( line ) => {
+		const trimmed = line.trim();
+		if ( trimmed === '' ) return { type: 'blank', text: line };
+		if ( trimmed.startsWith( '#' ) ) return { type: 'comment', text: line };
+		const m = trimmed.match( KV_RE );
+		if ( m ) return { type: 'kv', key: m[1], value: m[2], raw: line };
+		return { type: 'other', text: line };
+	} );
+}
+
+export function serializeEnv( items ) {
+	return items.map( ( it ) => {
+		if ( it.type === 'kv' ) return `${ it.key }=${ it.value }`;
+		return it.text;
+	} ).join( '\n' );
+}
+
+/**
+ * Merge `updates` (object) into the file at `filePath`.
+ * Returns { created: boolean, added: string[], updated: string[], unchanged: string[] }.
+ */
+export async function mergeEnv( filePath, updates ) {
+	const added = [];
+	const updated = [];
+	const unchanged = [];
+
+	let items;
+	let created = false;
+
+	if ( ! existsSync( filePath ) ) {
+		created = true;
+		items = [];
+		logger.debug( `env-writer: ${ filePath } does not exist, creating` );
+	} else {
+		const text = await readFile( filePath, 'utf8' );
+		items = parseEnv( text );
+		logger.debug( `env-writer: parsed ${ items.length } lines from ${ filePath }` );
+	}
+
+	const seen = new Set();
+	for ( const it of items ) {
+		if ( it.type !== 'kv' ) continue;
+		if ( ! ( it.key in updates ) ) continue;
+		if ( seen.has( it.key ) ) continue; // only update first occurrence
+		seen.add( it.key );
+		const newValue = updates[ it.key ];
+		if ( it.value === newValue ) {
+			unchanged.push( it.key );
+		} else {
+			it.value = newValue;
+			updated.push( it.key );
+		}
+	}
+
+	for ( const [ key, value ] of Object.entries( updates ) ) {
+		if ( seen.has( key ) ) continue;
+		if ( items.length > 0 && items.at( -1 )?.type !== 'blank' ) {
+			items.push( { type: 'blank', text: '' } );
+		}
+		items.push( { type: 'kv', key, value, raw: `${ key }=${ value }` } );
+		added.push( key );
+	}
+
+	const out = serializeEnv( items );
+	await mkdir( dirname( filePath ), { recursive: true } );
+	await writeFile( filePath, out.endsWith( '\n' ) ? out : out + '\n', 'utf8' );
+
+	logger.debug( `env-writer: created=${ created } added=${ added.length } updated=${ updated.length } unchanged=${ unchanged.length }` );
+	return { created, added, updated, unchanged };
+}

package/src/lib/logger.mjs

@@ -0,0 +1,53 @@
+/**
+ * Lightweight logger with configurable level. No external deps.
+ *
+ * Levels: debug < info < warn < error. Default: info.
+ * Toggle to debug with `--verbose` flag in the CLI.
+ *
+ * Singleton: imported by every layer. Secrets (private keys, passwords) must
+ * NEVER be passed to it.
+ */
+
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+
+const ANSI = {
+	reset: '\x1b[0m',
+	gray: '\x1b[90m',
+	cyan: '\x1b[36m',
+	yellow: '\x1b[33m',
+	red: '\x1b[31m',
+	green: '\x1b[32m',
+	bold: '\x1b[1m',
+};
+
+const useColor = process.stdout.isTTY && ! process.env.NO_COLOR;
+const c = ( code, s ) => ( useColor ? `${ code }${ s }${ ANSI.reset }` : s );
+
+class Logger {
+	#level = LEVELS.info;
+
+	setLevel( name ) {
+		if ( LEVELS[ name ] !== undefined ) {
+			this.#level = LEVELS[ name ];
+		}
+	}
+
+	#log( levelName, prefix, color, ...args ) {
+		if ( LEVELS[ levelName ] < this.#level ) return;
+		const head = c( color, `[${ prefix }]` );
+		const time = c( ANSI.gray, new Date().toISOString().slice( 11, 19 ) );
+		process.stdout.write( `${ time } ${ head } ${ args.join( ' ' ) }\n` );
+	}
+
+	debug( ...args ) { this.#log( 'debug', 'debug', ANSI.gray, ...args ); }
+	info( ...args ) { this.#log( 'info', 'info', ANSI.cyan, ...args ); }
+	warn( ...args ) { this.#log( 'warn', 'warn', ANSI.yellow, ...args ); }
+	error( ...args ) { this.#log( 'error', 'error', ANSI.red, ...args ); }
+	success( ...args ) { this.#log( 'info', 'ok', ANSI.green, ...args ); }
+
+	step( msg ) {
+		process.stdout.write( '\n' + c( ANSI.bold, '› ' + msg ) + '\n' );
+	}
+}
+
+export const logger = new Logger();

package/src/lib/markers.mjs

@@ -0,0 +1,132 @@
+/**
+ * Idempotent marker-block management for files like AGENTS.md / CLAUDE.md.
+ *
+ * Wraps a managed block between:
+ *   <!-- seomi-ssh:start --> ... <!-- seomi-ssh:end -->
+ *
+ * - insertOrUpdate(filePath, content, opts) — creates or replaces the block.
+ * - removeBlock(filePath, opts) — strips the block entirely.
+ * - hasBlock(filePath, opts) — boolean check.
+ *
+ * Safe to call repeatedly. Preserves all surrounding content verbatim.
+ *
+ * Matching is GREEDY (first `:start` to LAST `:end`): older non-greedy
+ * versions of this approach shipped templates whose body itself mentioned the
+ * literal markers, which caused the non-greedy regex to match only up to the
+ * first inline `:end` mention and leave orphan tails accumulating on each
+ * `init` run. Greedy matching collapses any such corruption into a single
+ * fresh block, and `stripOrphanMarkers` cleans up stray marker lines left
+ * outside the matched span.
+ */
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { logger } from './logger.mjs';
+
+const DEFAULT_NAMESPACE = 'seomi-ssh';
+
+function escapeRe( s ) {
+	return s.replace( /[.*+?^${}()|[\]\\]/g, '\\$&' );
+}
+
+function buildMarkers( namespace ) {
+	return {
+		start: `<!-- ${ namespace }:start -->`,
+		end: `<!-- ${ namespace }:end -->`,
+	};
+}
+
+/**
+ * GREEDY: from the first `:start` to the LAST `:end`. No `g` flag — we want
+ * a single match covering all corrupted/duplicated content as one span.
+ */
+function buildGreedyRegex( namespace ) {
+	const ns = escapeRe( namespace );
+	return new RegExp(
+		`<!--\\s*${ ns }:start\\s*-->[\\s\\S]*<!--\\s*${ ns }:end\\s*-->\\n?`
+	);
+}
+
+/**
+ * Matches a standalone marker line (whitespace-only line containing just the
+ * start or end marker). Used to clean orphan markers left outside the main
+ * managed span by older broken installs.
+ */
+function buildOrphanLineRegex( namespace ) {
+	const ns = escapeRe( namespace );
+	return new RegExp(
+		`^[ \\t]*<!--\\s*${ ns }:(?:start|end)\\s*-->[ \\t]*\\r?\\n?`,
+		'gm'
+	);
+}
+
+/**
+ * Remove standalone marker lines from `text` EXCEPT inside `block` (the new
+ * managed block we are about to write). When `block` is empty, strip
+ * everywhere.
+ */
+function stripOrphanMarkers( text, namespace, block ) {
+	const lineRegex = buildOrphanLineRegex( namespace );
+	if ( ! block ) return text.replace( lineRegex, '' );
+	const parts = text.split( block );
+	if ( parts.length === 1 ) return text.replace( lineRegex, '' );
+	return parts.map( ( p ) => p.replace( lineRegex, '' ) ).join( block );
+}
+
+export async function hasBlock( filePath, { namespace = DEFAULT_NAMESPACE } = {} ) {
+	if ( ! existsSync( filePath ) ) return false;
+	const text = await readFile( filePath, 'utf8' );
+	return buildGreedyRegex( namespace ).test( text );
+}
+
+export async function insertOrUpdate( filePath, content, { namespace = DEFAULT_NAMESPACE, appendIfNew = true } = {} ) {
+	const { start, end } = buildMarkers( namespace );
+	const block = `${ start }\n${ content.trim() }\n${ end }\n`;
+
+	if ( ! existsSync( filePath ) ) {
+		await mkdir( dirname( filePath ), { recursive: true } );
+		await writeFile( filePath, block, 'utf8' );
+		return { action: 'created', filePath };
+	}
+
+	const text = await readFile( filePath, 'utf8' );
+	const greedyRegex = buildGreedyRegex( namespace );
+
+	if ( greedyRegex.test( text ) ) {
+		let updated = text.replace( greedyRegex, block );
+		updated = stripOrphanMarkers( updated, namespace, block );
+		if ( updated === text ) {
+			return { action: 'unchanged', filePath };
+		}
+		await writeFile( filePath, updated, 'utf8' );
+		logger.debug( `markers: replaced managed block in ${ filePath }` );
+		return { action: 'updated', filePath };
+	}
+
+	// No managed span — but stray marker lines from past corruption may still
+	// linger. Drop them before deciding whether to append.
+	const cleaned = stripOrphanMarkers( text, namespace, '' );
+
+	if ( ! appendIfNew ) {
+		if ( cleaned !== text ) {
+			await writeFile( filePath, cleaned, 'utf8' );
+			return { action: 'cleaned', filePath };
+		}
+		return { action: 'not-found', filePath };
+	}
+
+	const sep = cleaned.length > 0 && ! cleaned.endsWith( '\n' ) ? '\n\n' : '\n';
+	await writeFile( filePath, cleaned + sep + block, 'utf8' );
+	return { action: 'appended', filePath };
+}
+
+export async function removeBlock( filePath, { namespace = DEFAULT_NAMESPACE } = {} ) {
+	if ( ! existsSync( filePath ) ) return { action: 'not-found', filePath };
+	const text = await readFile( filePath, 'utf8' );
+	let updated = text.replace( buildGreedyRegex( namespace ), '' );
+	updated = stripOrphanMarkers( updated, namespace, '' );
+	if ( updated === text ) return { action: 'unchanged', filePath };
+	await writeFile( filePath, updated, 'utf8' );
+	return { action: 'removed', filePath };
+}

package/src/lib/server-prompt.mjs

@@ -0,0 +1,176 @@
+/**
+ * Interactive server-prompt loop for `seomi-ssh init`.
+ *
+ * Repeatedly asks the user to describe a server (role + connection params),
+ * then asks "add another?" — looping until the user declines. Supports 1..N
+ * servers, each addressable by a unique UPPER_SNAKE_CASE env prefix derived
+ * from its role (`prod` → `PROD`, `dev` → `DEV`, custom names normalized).
+ *
+ * Server model (one object per server):
+ *   {
+ *     role:    string,  // human role label as entered ('prod' / 'dev' / 'staging-eu')
+ *     prefix:  string,  // unique UPPER_SNAKE_CASE env prefix ('PROD', 'STAGING_EU', 'PROD_2')
+ *     host:    string,
+ *     user:    string,
+ *     port:    string,  // '' or numeric string; default '22'
+ *     keyPath: string,  // private key path, may contain leading '~'
+ *     root:    string,  // optional remote working directory ('' when skipped)
+ *   }
+ *
+ * The `@inquirer/prompts` module is loaded lazily and can be replaced through
+ * the `_prompts` test seam so the loop is unit-testable without a TTY.
+ *
+ * No external commands are run here — this module is pure I/O over prompts and
+ * has no horizontal lib dependencies (only the shared logger).
+ */
+
+import { logger } from './logger.mjs';
+
+const ROLE_PROD = 'prod';
+const ROLE_DEV = 'dev';
+const ROLE_CUSTOM = '__custom__';
+
+/**
+ * Normalize an arbitrary role label into a bare UPPER_SNAKE_CASE token.
+ * Non-alphanumeric runs collapse to a single `_`; leading/trailing `_` are
+ * trimmed. The result is always usable as the `<PREFIX>` segment of a
+ * `SSH_<PREFIX>_HOST` env key (the `SSH_` literal guarantees the full key
+ * still starts with a letter even if the prefix begins with a digit).
+ *
+ * 'prod' → 'PROD', 'staging-eu' → 'STAGING_EU', '  my server!! ' → 'MY_SERVER'.
+ * Falls back to 'SERVER' when nothing usable remains.
+ */
+export function normalizePrefix( role ) {
+	const cleaned = String( role || '' )
+		.toUpperCase()
+		.replace( /[^A-Z0-9]+/g, '_' )
+		.replace( /^_+|_+$/g, '' );
+	return cleaned || 'SERVER';
+}
+
+/**
+ * Ensure `base` is unique against `used` (a Set of already-taken prefixes).
+ * On collision, append `_2`, `_3`, … until free. Does NOT mutate `used`.
+ */
+export function uniquePrefix( base, used ) {
+	if ( ! used.has( base ) ) return base;
+	let n = 2;
+	while ( used.has( `${ base }_${ n }` ) ) n++;
+	return `${ base }_${ n }`;
+}
+
+/**
+ * Prompt for a single server's role, returning the human label.
+ * `prod` / `dev` are offered directly; anything else is entered free-form.
+ */
+async function promptRole( prompts ) {
+	const choice = await prompts.select( {
+		message: 'Роль сервера',
+		default: ROLE_PROD,
+		choices: [
+			{ name: 'prod — продакшн', value: ROLE_PROD },
+			{ name: 'dev — разработка', value: ROLE_DEV },
+			{ name: 'другое (своё имя)', value: ROLE_CUSTOM },
+		],
+	} );
+
+	if ( choice !== ROLE_CUSTOM ) return choice;
+
+	const custom = await prompts.input( {
+		message: 'Имя роли (например staging, eu-prod)',
+		validate: ( v ) => ( String( v || '' ).trim().length > 0 ? true : 'Имя роли не может быть пустым' ),
+	} );
+	return String( custom ).trim();
+}
+
+/**
+ * Prompt for one server's connection parameters (role already known).
+ */
+async function promptServer( prompts, role, prefix ) {
+	logger.debug( `[server-prompt] collecting params for role=${ role } prefix=${ prefix }` );
+
+	const host = await prompts.input( {
+		message: `[${ role }] Host (домен или IP)`,
+		validate: ( v ) => ( String( v || '' ).trim().length > 0 ? true : 'Host обязателен' ),
+	} );
+	const user = await prompts.input( {
+		message: `[${ role }] SSH-пользователь`,
+		validate: ( v ) => ( String( v || '' ).trim().length > 0 ? true : 'Пользователь обязателен' ),
+	} );
+	const port = await prompts.input( {
+		message: `[${ role }] SSH-порт`,
+		default: '22',
+	} );
+	const keyPath = await prompts.input( {
+		message: `[${ role }] Путь к приватному ключу`,
+		default: '~/.ssh/id_ed25519',
+	} );
+	const root = await prompts.input( {
+		message: `[${ role }] Рабочая директория на сервере (необязательно)`,
+		default: '',
+	} );
+
+	return {
+		role,
+		prefix,
+		host: String( host ).trim(),
+		user: String( user ).trim(),
+		port: String( port ).trim(),
+		keyPath: String( keyPath ).trim(),
+		root: String( root ).trim(),
+	};
+}
+
+/**
+ * Run the interactive loop. Returns the collected server list (possibly empty
+ * if the user declined the very first server).
+ *
+ * @param {object}   [opts]
+ * @param {object}   [opts._prompts] — test seam: replaces `@inquirer/prompts`.
+ *                                      Must expose `select`, `input`, `confirm`.
+ * @returns {Promise<Array<object>>}
+ */
+export async function promptServers( { _prompts } = {} ) {
+	const prompts = _prompts || ( await import( '@inquirer/prompts' ) );
+	const servers = [];
+	const usedPrefixes = new Set();
+
+	let addMore = true;
+	while ( addMore ) {
+		const role = await promptRole( prompts );
+		const prefix = uniquePrefix( normalizePrefix( role ), usedPrefixes );
+		usedPrefixes.add( prefix );
+
+		const server = await promptServer( prompts, role, prefix );
+		servers.push( server );
+		logger.success( `[server-prompt] добавлен сервер «${ role }» → env-префикс SSH_${ prefix }_*` );
+
+		addMore = await prompts.confirm( {
+			message: 'Добавить ещё один сервер?',
+			default: false,
+		} );
+	}
+
+	logger.debug( `[server-prompt] total servers=${ servers.length }` );
+	return servers;
+}
+
+/**
+ * Build the `.claude/.env` updates object for a list of servers.
+ * Writes `SSH_<PREFIX>_HOST/USER/PORT/KEY/ROOT` (optional keys skipped when
+ * blank) plus the `SSH_SERVERS` registry (csv of prefixes) so `update` can
+ * later enumerate every configured server.
+ */
+export function toEnvUpdates( servers ) {
+	const updates = {};
+	for ( const s of servers ) {
+		const p = s.prefix;
+		updates[ `SSH_${ p }_HOST` ] = s.host;
+		updates[ `SSH_${ p }_USER` ] = s.user;
+		if ( s.port ) updates[ `SSH_${ p }_PORT` ] = s.port;
+		updates[ `SSH_${ p }_KEY` ] = s.keyPath;
+		if ( s.root ) updates[ `SSH_${ p }_ROOT` ] = s.root;
+	}
+	updates.SSH_SERVERS = servers.map( ( s ) => s.prefix ).join( ',' );
+	return updates;
+}

package/src/lib/ssh-key-setup.mjs

@@ -0,0 +1,236 @@
+/**
+ * SSH key wizard for `seomi-ssh init`.
+ *
+ * Sets up passwordless SSH access to a remote host in a self-contained
+ * strategy chain:
+ *
+ *   1. Keygen   — generate ed25519 key if missing (`ssh-keygen -N ''`), or
+ *                 reuse an existing one. Empty passphrase is intentional:
+ *                 the agent needs non-interactive auth, the user can encrypt
+ *                 the key later if they want.
+ *   2. Copy     — `ssh-copy-id` (asks for the SSH password ONCE), or a
+ *                 portable `ssh` fallback that pipes the public key through
+ *                 stdin into ~/.ssh/authorized_keys (deduped).
+ *   3. Verify   — `ssh -o BatchMode=yes ... 'echo ok'`. BatchMode disables
+ *                 password prompts, so a non-zero exit reliably means
+ *                 key-auth did not take.
+ *   4. Fallback — if verify fails (typical on shared hosts that only accept
+ *                 keys via a control panel), return a `manualHint` string with
+ *                 the .pub content and a how-to.
+ *
+ * This module is self-contained on purpose — it does NOT import a shared spawn
+ * helper from a sibling lib module (that would create a horizontal lib→lib
+ * dependency the architecture forbids). It carries its own thin spawn() wrapper.
+ *
+ * Private key material is NEVER logged — only the public key appears in hints.
+ */
+
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readFile, mkdir, access } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve as resolvePath, dirname } from 'node:path';
+import { logger } from './logger.mjs';
+
+/**
+ * Resolve a path with a leading `~` to an absolute path using the user's
+ * home directory. Leaving the literal `~` in place breaks on Windows where
+ * the shell does not expand it.
+ */
+function expandHome( p ) {
+	if ( ! p ) return p;
+	if ( p === '~' ) return homedir();
+	if ( p.startsWith( '~/' ) || p.startsWith( '~\\' ) ) {
+		return resolvePath( homedir(), p.slice( 2 ) );
+	}
+	return p;
+}
+
+/**
+ * Spawn a child process and resolve with { code, stdout, stderr }.
+ *
+ * Custom opts (not real spawn options, stripped before the spawn call):
+ *   - `interactive: true` → `stdio: ['inherit', 'pipe', 'inherit']`. Used
+ *     for `ssh-copy-id`, which needs the user's terminal for the password
+ *     prompt but whose stdout we still want to capture in tests.
+ *   - `input: <string>`   → `stdio: ['pipe', 'inherit', 'inherit']`. Used
+ *     for the ssh-pipe fallback: we write the public key to stdin, the
+ *     remote shell appends it to authorized_keys.
+ *
+ * Without either flag the default is fully-piped stdio (stdout/stderr
+ * captured, stdin closed) — used for `ssh-keygen` and the verify step.
+ */
+function exec( cmd, args, opts = {} ) {
+	const { interactive, input, ...spawnOpts } = opts;
+	if ( interactive ) {
+		spawnOpts.stdio = [ 'inherit', 'pipe', 'inherit' ];
+		logger.debug( `ssh-key-setup exec: interactive stdio for ${ cmd }` );
+	} else if ( typeof input === 'string' ) {
+		spawnOpts.stdio = [ 'pipe', 'inherit', 'inherit' ];
+		logger.debug( `ssh-key-setup exec: pipe-stdin stdio for ${ cmd }` );
+	}
+	return new Promise( ( resolve ) => {
+		const child = spawn( cmd, args, { shell: false, windowsHide: true, ...spawnOpts } );
+		let stdout = '';
+		let stderr = '';
+		child.stdout?.on( 'data', ( d ) => { stdout += d.toString(); } );
+		child.stderr?.on( 'data', ( d ) => { stderr += d.toString(); } );
+		child.on( 'error', ( err ) => resolve( { code: -1, stdout, stderr: stderr + err.message } ) );
+		child.on( 'close', ( code ) => resolve( { code: code ?? 0, stdout, stderr } ) );
+		if ( typeof input === 'string' && child.stdin ) {
+			child.stdin.write( input );
+			child.stdin.end();
+		}
+	} );
+}
+
+function portArgs( sshPort ) {
+	return sshPort ? [ '-p', String( sshPort ) ] : [];
+}
+
+/**
+ * Portable ssh-copy-id replacement: pipe the public key through ssh stdin
+ * into ~/.ssh/authorized_keys on the remote host. Deduplicates so repeat
+ * runs don't keep appending the same key.
+ */
+const REMOTE_APPEND_SCRIPT =
+	'mkdir -p ~/.ssh && chmod 700 ~/.ssh && touch ~/.ssh/authorized_keys && '
+	+ 'chmod 600 ~/.ssh/authorized_keys && KEY="$(cat)" && '
+	+ 'grep -qxF "$KEY" ~/.ssh/authorized_keys || printf \'%s\\n\' "$KEY" >> ~/.ssh/authorized_keys';
+
+function buildManualHint( { pubKeyContent, sshUser, sshHost, sshPort, keyPath } ) {
+	const portFragment = sshPort ? ` -p ${ sshPort }` : '';
+	return [
+		'Не удалось автоматически добавить SSH-ключ — добавьте его через панель хостинга (cPanel / Beget / DirectAdmin / ISPmanager и т.п.) или вручную в ~/.ssh/authorized_keys на сервере.',
+		'',
+		'Содержимое публичного ключа:',
+		'',
+		pubKeyContent,
+		'',
+		'После добавления повторите `seomi-ssh init` или проверьте подключение вручную:',
+		`  ssh -i ${ keyPath }${ portFragment } ${ sshUser }@${ sshHost }`,
+	].join( '\n' );
+}
+
+/**
+ * Set up key-based SSH auth for a remote host.
+ *
+ * @param {Object} cfg
+ * @param {string} cfg.sshHost         Remote host (e.g. 'prod.example.com').
+ * @param {string} cfg.sshUser         Remote SSH user.
+ * @param {string} [cfg.sshPort='']    Remote SSH port. Blank = ssh default (22).
+ * @param {string} [cfg.keyPath]       Absolute path to the private key. `~`
+ *                                     is expanded. Default: ~/.ssh/id_ed25519.
+ * @param {string} [cfg.comment]       Key comment. Default: `ai-agent@<host>`.
+ * @returns {Promise<{
+ *   keyPath: string,
+ *   pubKeyPath: string,
+ *   pubKeyContent: string,
+ *   keygenAction: 'created' | 'reused',
+ *   copyAction: 'ssh-copy-id' | 'ssh-fallback' | 'failed' | 'skipped',
+ *   verified: boolean,
+ *   manualHint: string | null,
+ * }>}
+ */
+export async function ensureSshKey( cfg ) {
+	const { sshHost, sshUser } = cfg;
+	const sshPort = cfg.sshPort || '';
+	const keyPath = expandHome( cfg.keyPath ) || resolvePath( homedir(), '.ssh', 'id_ed25519' );
+	const pubKeyPath = keyPath + '.pub';
+	const comment = cfg.comment || `ai-agent@${ sshHost }`;
+	const sshTarget = `${ sshUser }@${ sshHost }`;
+
+	logger.step( 'SSH key setup' );
+	logger.debug( `ssh-key-setup: target=${ sshTarget } port=${ sshPort || '22' } keyPath=${ keyPath }` );
+
+	// --- 1. Keygen --------------------------------------------------------
+	const keyExists = existsSync( keyPath );
+	logger.debug( `keygen: keyPath=${ keyPath } exists=${ keyExists }` );
+	let keygenAction;
+	if ( keyExists ) {
+		try {
+			await access( keyPath );
+		} catch ( err ) {
+			throw new Error( `Private key exists at ${ keyPath } but cannot be read: ${ err.message }` );
+		}
+		keygenAction = 'reused';
+	} else {
+		await mkdir( dirname( keyPath ), { recursive: true } );
+		const r = await _internals.exec( 'ssh-keygen', [
+			'-t', 'ed25519',
+			'-N', '',
+			'-C', comment,
+			'-f', keyPath,
+		] );
+		if ( r.code !== 0 ) {
+			throw new Error( `ssh-keygen failed (exit ${ r.code }): ${ r.stderr.trim() || 'is ssh-keygen on PATH?' }` );
+		}
+		keygenAction = 'created';
+	}
+
+	const pubKeyContent = ( await readFile( pubKeyPath, 'utf8' ) ).trim();
+
+	// --- 2. Copy ----------------------------------------------------------
+	logger.info( 'Copying public key via ssh-copy-id' );
+	const port = portArgs( sshPort );
+	const copyResult = await _internals.exec(
+		'ssh-copy-id',
+		[ '-i', pubKeyPath, ...port, sshTarget ],
+		{ interactive: true },
+	);
+
+	let copyAction;
+	if ( copyResult.code === 0 ) {
+		copyAction = 'ssh-copy-id';
+	} else if ( copyResult.code === -1 ) {
+		// ssh-copy-id binary not on PATH (typical on Windows OpenSSH).
+		logger.warn( 'ssh-copy-id missing — using ssh fallback' );
+		const fb = await _internals.exec(
+			'ssh',
+			[ ...port, sshTarget, REMOTE_APPEND_SCRIPT ],
+			{ input: pubKeyContent + '\n' },
+		);
+		copyAction = fb.code === 0 ? 'ssh-fallback' : 'failed';
+		if ( fb.code !== 0 ) {
+			logger.warn( `ssh fallback copy failed (exit ${ fb.code })` );
+		}
+	} else {
+		logger.warn( `ssh-copy-id failed (exit ${ copyResult.code }): ${ copyResult.stderr.trim() }` );
+		copyAction = 'failed';
+	}
+
+	// --- 3. Verify --------------------------------------------------------
+	const verifyArgs = [
+		'-o', 'BatchMode=yes',
+		'-o', 'StrictHostKeyChecking=accept-new',
+		'-o', 'ConnectTimeout=10',
+		'-i', keyPath,
+		...port,
+		sshTarget,
+		'echo ok',
+	];
+	logger.debug( `verify: command=ssh ${ verifyArgs.join( ' ' ) }` );
+	const verifyResult = await _internals.exec( 'ssh', verifyArgs );
+	const verified = verifyResult.code === 0 && verifyResult.stdout.includes( 'ok' );
+
+	// --- 4. Result --------------------------------------------------------
+	let manualHint = null;
+	if ( verified ) {
+		logger.success( 'SSH key copied and verified' );
+	} else {
+		logger.warn( 'SSH key copy verified=false; printing manual hint' );
+		manualHint = buildManualHint( { pubKeyContent, sshUser, sshHost, sshPort, keyPath } );
+	}
+
+	return {
+		keyPath,
+		pubKeyPath,
+		pubKeyContent,
+		keygenAction,
+		copyAction,
+		verified,
+		manualHint,
+	};
+}
+
+export const _internals = { exec, buildManualHint, expandHome, REMOTE_APPEND_SCRIPT };