@seomi/ssh 0.1.2 → 0.2.0

package/README.md

@@ -28,9 +28,12 @@ seomi-ssh init
   `ssh` / `scp` / `rsync` examples, values pulled from `.claude/.env`.
 - **`aif-ssh` skill** — copied into the project's `.claude/skills/` so the agent knows how
   to use the configured access.
+- **`update`** — non-interactive. Re-reads every server from `.claude/.env`, regenerates the
+  managed block, and heals a drifted `SSH_SERVERS` registry (recovering servers whose keys are
+  present but fell out of the registry). No prompts, no key setup.
 - **Idempotent** — re-running never duplicates keys, env entries, or the managed block.
 
-> `update` and `doctor` are declared in `--help` but are not implemented yet (stubs).
+> `doctor` is declared in `--help` but is not implemented yet (stub).
 
 ## Commands
 
@@ -38,10 +41,11 @@ seomi-ssh init
 |---------|--------------|
 | `seomi-ssh init` | Interactive setup (see above) |
 | `seomi-ssh init --dry-run` | Run the prompts without touching disk or SSH; preview the block |
-| `seomi-ssh init --verbose` | Add debug-level logging |
-| `seomi-ssh --help` | Show usage |
-| `seomi-ssh --version` | Print version |
-| `seomi-ssh update` / `doctor` | Reserved (not implemented yet) |
+| `seomi-ssh update` | Regenerate the managed block from `.claude/.env` and heal `SSH_SERVERS` |
+| `seomi-ssh update --dry-run` | Preview the regenerated block without writing |
+| `seomi-ssh <cmd> --verbose` | Add debug-level logging |
+| `seomi-ssh --help` / `--version` | Show usage / print version |
+| `seomi-ssh doctor` | Reserved (not implemented yet) |
 
 ## Requirements
 
@@ -72,14 +76,17 @@ One server = one key group:
 |-----|---------|---------|
 | `SSH_<PREFIX>_HOST` | domain or IP | always |
 | `SSH_<PREFIX>_USER` | SSH user | always |
+| `SSH_<PREFIX>_ROLE` | human role label (as entered) | always |
 | `SSH_<PREFIX>_PORT` | port | if provided |
 | `SSH_<PREFIX>_KEY`  | private key path | always |
 | `SSH_<PREFIX>_ROOT` | remote working directory | if provided |
-| `SSH_SERVERS` | csv registry of all prefixes | always |
+| `SSH_SERVERS` | csv registry (union) of all prefixes | always |
 
 `<PREFIX>` is the role normalized to `UPPER_SNAKE_CASE` (`prod` → `PROD`, `staging-eu` →
-`STAGING_EU`); duplicate roles get a unique suffix (`PROD`, then `PROD_2`). `.claude/.env`
-is the **first place** the agent looks for access details — not `~/.ssh/config`.
+`STAGING_EU`); duplicate roles get a unique suffix (`PROD`, then `PROD_2`). `SSH_<PREFIX>_ROLE`
+preserves the original label verbatim (the prefix alone loses dashes), with a `prefix.toLowerCase()`
+fallback for older files. `.claude/.env` is the **first place** the agent looks for access
+details — not `~/.ssh/config`.
 
 ## Example
 
@@ -103,6 +110,7 @@ $ seomi-ssh init
 | Guide | Description |
 |-------|-------------|
 | [`init` command](https://github.com/Mikeekb/seomi-ssh/blob/main/docs/init.md) | SSH setup behavior, `.claude/.env` configuration, examples, troubleshooting |
+| [`update` command](https://github.com/Mikeekb/seomi-ssh/blob/main/docs/update.md) | Regenerate the managed block from `.claude/.env`, heal `SSH_SERVERS` drift |
 
 ## License
 

package/README.ru.md

@@ -28,9 +28,12 @@ seomi-ssh init
   `ssh` / `scp` / `rsync`, значения берутся из `.claude/.env`.
 - **Skill `aif-ssh`** — копируется в `.claude/skills/` проекта и учит агента пользоваться
   настроенным доступом.
+- **`update`** — неинтерактивная. Перечитывает все серверы из `.claude/.env`, перерисовывает
+  managed-блок и лечит рассинхрон реестра `SSH_SERVERS` (восстанавливает серверы, чьи ключи
+  есть, но выпали из реестра). Без вопросов и без настройки ключей.
 - **Идемпотентность** — повторный запуск не дублирует ключи, env-записи и managed-блок.
 
-> `update` и `doctor` объявлены в `--help`, но пока не реализованы (заглушки).
+> `doctor` объявлена в `--help`, но пока не реализована (заглушка).
 
 ## Команды
 
@@ -38,10 +41,11 @@ seomi-ssh init
 |---------|------------|
 | `seomi-ssh init` | Интерактивная настройка (см. выше) |
 | `seomi-ssh init --dry-run` | Прогон опроса без записи на диск и SSH-вызовов; превью блока |
-| `seomi-ssh init --verbose` | Включает debug-логирование |
-| `seomi-ssh --help` | Справка |
-| `seomi-ssh --version` | Версия |
-| `seomi-ssh update` / `doctor` | Зарезервированы (пока не реализованы) |
+| `seomi-ssh update` | Перерисовать managed-блок из `.claude/.env` и вылечить `SSH_SERVERS` |
+| `seomi-ssh update --dry-run` | Превью перерисованного блока без записи |
+| `seomi-ssh <cmd> --verbose` | Включает debug-логирование |
+| `seomi-ssh --help` / `--version` | Справка / версия |
+| `seomi-ssh doctor` | Зарезервирована (пока не реализована) |
 
 ## Требования
 
@@ -72,14 +76,17 @@ seomi-ssh init
 |------|------------|---------|
 | `SSH_<PREFIX>_HOST` | домен или IP | всегда |
 | `SSH_<PREFIX>_USER` | SSH-пользователь | всегда |
+| `SSH_<PREFIX>_ROLE` | человекочитаемая метка роли (как введена) | всегда |
 | `SSH_<PREFIX>_PORT` | порт | если задан |
 | `SSH_<PREFIX>_KEY`  | путь к приватному ключу | всегда |
 | `SSH_<PREFIX>_ROOT` | рабочая директория на сервере | если задана |
-| `SSH_SERVERS` | csv-реестр всех префиксов | всегда |
+| `SSH_SERVERS` | csv-реестр (объединение) всех префиксов | всегда |
 
 `<PREFIX>` — это роль, нормализованная в `UPPER_SNAKE_CASE` (`prod` → `PROD`, `staging-eu` →
 `STAGING_EU`); при повторе роли префикс получает уникальный суффикс (`PROD`, затем `PROD_2`).
-`.claude/.env` — **первое место**, куда агент смотрит за реквизитами доступа, а не `~/.ssh/config`.
+`SSH_<PREFIX>_ROLE` хранит исходную метку дословно (префикс теряет дефисы), с fallback
+`prefix.toLowerCase()` для старых файлов. `.claude/.env` — **первое место**, куда агент
+смотрит за реквизитами доступа, а не `~/.ssh/config`.
 
 ## Пример
 
@@ -103,6 +110,7 @@ $ seomi-ssh init
 | Раздел | Описание |
 |--------|----------|
 | [Команда `init`](https://github.com/Mikeekb/seomi-ssh/blob/main/docs/init.md) | Поведение `init`, конфигурация `.claude/.env`, примеры, диагностика |
+| [Команда `update`](https://github.com/Mikeekb/seomi-ssh/blob/main/docs/update.md) | Перерисовка managed-блока из `.claude/.env`, лечение рассинхрона `SSH_SERVERS` |
 
 ## Лицензия
 

package/bin/seomi-ssh.mjs

@@ -2,13 +2,14 @@
 /**
  * seomi-ssh — entry point.
  *
- * Parses argv, sets the log level, and routes to a subcommand. Only `init` is
- * implemented in this release; `update` and `doctor` are declared stubs so the
- * surface is stable and discoverable.
+ * Parses argv, sets the log level, and routes to a subcommand. `init` and
+ * `update` are implemented; `doctor` is a declared stub so the surface is
+ * stable and discoverable.
  */
 
 import { parseArgs } from 'node:util';
 import { initCommand } from '../src/commands/init.mjs';
+import { updateCommand } from '../src/commands/update.mjs';
 import { logger } from '../src/lib/logger.mjs';
 
 const HELP = `Usage: seomi-ssh <command> [options]
@@ -19,14 +20,17 @@ Commands:
                  the connection params to .claude/.env, render the managed
                  access block into AGENTS.md / CLAUDE.md, and drop the aif-ssh
                  skill into .claude/skills/.
-  update         (not implemented yet) Regenerate the managed block from
-                 .claude/.env and self-update the package.
+  update         Non-interactive: re-read every configured server from
+                 .claude/.env, regenerate the managed access block in the
+                 existing AGENTS.md / CLAUDE.md, and heal a drifted SSH_SERVERS
+                 registry (recovering servers whose keys are present but fell
+                 out of the registry). Supports --dry-run.
   doctor         (not implemented yet) Diagnose configured servers (which are
                  set up, which are reachable by key).
 
 Global options:
   --verbose      Enable debug logging (DEBUG level).
-  --dry-run      init only: run prompts but make no changes; preview the block.
+  --dry-run      init/update only: make no changes; preview the block.
   --help, -h     Show this help.
   --version, -v  Print version.
 `;
@@ -76,9 +80,10 @@ async function main() {
 		case 'init':
 			return await initCommand( opts );
 		case 'update':
+			return await updateCommand( opts );
 		case 'doctor':
 			logger.warn( `Команда «${ command }» ещё не реализована в этой версии.` );
-			logger.info( 'Доступна только `seomi-ssh init`. См. `seomi-ssh --help`.' );
+			logger.info( 'Доступны `seomi-ssh init` и `seomi-ssh update`. См. `seomi-ssh --help`.' );
 			return 1;
 		default:
 			logger.error( `Unknown command: ${ command }` );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seomi/ssh",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "One-command CLI installer that sets up passwordless SSH access for AI agents in any project (dev/prod/custom servers) and writes the access map into AGENTS.md / CLAUDE.md.",
   "type": "module",
   "bin": {

package/src/commands/init.mjs

@@ -4,7 +4,9 @@
  * Thin command: it sequences lib utilities and owns no business logic itself.
  * Flow:
  *   1. promptServers()            — interactive loop (1..N servers)
- *   2. ensureSshKey() per server  — keygen → copy → verify → manual hint
+ *      + mergeServers()           — fold in servers already in .claude/.env so
+ *                                   a re-run adds rather than overwrites
+ *   2. ensureSshKey() per session server — keygen → copy → verify → manual hint
  *   3. mergeEnv()                 — write SSH_<PREFIX>_* + SSH_SERVERS to .claude/.env
  *   4. detectAgentMdTargets()     — pick AGENTS.md / CLAUDE.md / both
  *   5. renderAgentMdBlock() + insertOrUpdate() — managed block per target
@@ -19,8 +21,8 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { logger } from '../lib/logger.mjs';
-import { promptServers, toEnvUpdates } from '../lib/server-prompt.mjs';
-import { mergeEnv } from '../lib/env-writer.mjs';
+import { promptServers, toEnvUpdates, serversFromEnv, mergeServers } from '../lib/server-prompt.mjs';
+import { mergeEnv, readEnv } from '../lib/env-writer.mjs';
 import { ensureSshKey } from '../lib/ssh-key-setup.mjs';
 import { detectAgentMdTargets, ensureClaudeImportStub, isClaudeImportStub } from '../lib/agent-md-target.mjs';
 import { renderAgentMdBlock } from '../lib/agent-md-renderer.mjs';
@@ -69,16 +71,27 @@ export async function initCommand( options = {} ) {
 
 	// --- 1. Prompt for servers -------------------------------------------
 	logger.step( 'Шаг 1: Опрос серверов' );
-	const servers = await promptServers( { _prompts: options._prompts } );
-	if ( servers.length === 0 ) {
+	const session = await promptServers( { _prompts: options._prompts } );
+	if ( session.length === 0 ) {
 		logger.warn( 'Серверы не заданы — нечего настраивать. Выход.' );
 		return 0;
 	}
-	logger.success( `Введено серверов: ${ servers.length }` );
+
+	// Merge with servers already configured in .claude/.env so a re-run that
+	// adds one server never drops the others from the block or SSH_SERVERS.
+	// readEnv is read-only — safe in dry-run too.
+	const existing = serversFromEnv( await readEnv( envPath ) );
+	const servers = mergeServers( existing, session );
+	logger.success(
+		`Введено серверов: ${ session.length }` +
+		( existing.length ? ` (уже настроено: ${ existing.length }, итого: ${ servers.length })` : '' )
+	);
 
 	// --- 2. SSH key wizard per server ------------------------------------
+	// Only the servers entered this session — already-configured ones keep
+	// their existing keys and must not trigger another keygen/copy.
 	logger.step( 'Шаг 2: Настройка SSH-ключей' );
-	for ( const srv of servers ) {
+	for ( const srv of session ) {
 		if ( dryRun ) {
 			logger.info( `[dry-run] ensureSshKey для «${ srv.role }» (${ srv.user }@${ srv.host }) пропущен` );
 			continue;

package/src/commands/update.mjs

@@ -0,0 +1,122 @@
+/**
+ * `seomi-ssh update` — regenerate the managed block from `.claude/.env`.
+ *
+ * Non-interactive companion to `init`: it re-reads every configured server from
+ * `.claude/.env` and re-renders the managed `seomi-ssh` block into the existing
+ * AGENTS.md / CLAUDE.md. As a healing side effect it rewrites `SSH_<PREFIX>_*`
+ * and the `SSH_SERVERS` registry from the full discovered set, so a `.env` that
+ * drifted (orphan prefixes missing from `SSH_SERVERS`, or pre-`ROLE` files) is
+ * brought back in sync on the first run.
+ *
+ * Thin command: it sequences lib utilities and owns no business logic itself.
+ * Flow:
+ *   1. serversFromEnv(readEnv())  — enumerate every configured server
+ *   2. mergeEnv()                 — heal SSH_SERVERS + write SSH_<PREFIX>_ROLE
+ *   3. renderAgentMdBlock() + insertOrUpdate() — refresh the block in place
+ *
+ * Unlike `init`, `update` never creates an instructions file: when neither
+ * AGENTS.md nor CLAUDE.md exists it warns and points the user at `init`.
+ *
+ * Out of scope (by design): npm self-update of the package (the `+ self-update`
+ * note in AGENTS.md) and any interactive prompting.
+ *
+ * `--dry-run` performs NO writes; it prints what would change and the block.
+ */
+
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { logger } from '../lib/logger.mjs';
+import { serversFromEnv, toEnvUpdates } from '../lib/server-prompt.mjs';
+import { readEnv, mergeEnv } from '../lib/env-writer.mjs';
+import { detectAgentMdTargets, ensureClaudeImportStub, isClaudeImportStub } from '../lib/agent-md-target.mjs';
+import { renderAgentMdBlock } from '../lib/agent-md-renderer.mjs';
+import { insertOrUpdate } from '../lib/markers.mjs';
+
+const MARKER_NS = 'seomi-ssh';
+
+function packagePath( ...segments ) {
+	// update.mjs lives at <pkg>/src/commands/ — climb two levels to the package root.
+	return fileURLToPath( new URL( join( '../../', ...segments ), import.meta.url ) );
+}
+
+function printSummary( servers, dryRun ) {
+	logger.info( `Серверов в реестре: ${ servers.length }${ dryRun ? ' (dry-run, без записи)' : '' }` );
+	for ( const s of servers ) {
+		logger.info( `  • ${ s.role } → ${ s.user }@${ s.host }${ s.port && s.port !== '22' ? `:${ s.port }` : '' } (env SSH_${ s.prefix }_*)` );
+	}
+}
+
+/**
+ * @param {object}   [options]
+ * @param {string}   [options.cwd]            — project root (default process.cwd()).
+ * @param {boolean}  [options['dry-run']]     — no side effects, just preview.
+ * @param {string}   [options.envPath]        — override .claude/.env location.
+ * @param {string}   [options.templatePath]   — override bundled template path.
+ * @returns {Promise<number>} process exit code (1 when nothing is configured).
+ */
+export async function updateCommand( options = {} ) {
+	const cwd = options.cwd || process.cwd();
+	const dryRun = Boolean( options[ 'dry-run' ] || options.dryRun );
+	const envPath = options.envPath || join( cwd, '.claude', '.env' );
+	const templatePath = options.templatePath || packagePath( 'templates', 'agent-md-block.md' );
+
+	logger.step( 'seomi-ssh update' + ( dryRun ? ' (dry-run)' : '' ) );
+
+	// --- 1. Re-read every configured server from .claude/.env ------------
+	logger.step( 'Шаг 1: Чтение серверов из .claude/.env' );
+	const servers = serversFromEnv( await readEnv( envPath ) );
+	if ( servers.length === 0 ) {
+		logger.warn( `Серверы в ${ envPath } не найдены — нечего обновлять.` );
+		logger.info( 'Запусти `seomi-ssh init`, чтобы настроить доступ.' );
+		return 1;
+	}
+	logger.success( `Найдено серверов: ${ servers.length }` );
+
+	// --- 2. Heal the .claude/.env registry (SSH_SERVERS + SSH_<P>_ROLE) --
+	logger.step( 'Шаг 2: Синхронизация реестра .claude/.env' );
+	const updates = toEnvUpdates( servers );
+	if ( dryRun ) {
+		logger.info( `[dry-run] mergeEnv пропущен; были бы синхронизированы ключи: ${ Object.keys( updates ).join( ', ' ) }` );
+	} else {
+		const r = await mergeEnv( envPath, updates );
+		logger.success( `.claude/.env: добавлено ${ r.added.length }, обновлено ${ r.updated.length }, без изменений ${ r.unchanged.length }` );
+	}
+
+	// --- 3. Re-render the managed block into existing targets only -------
+	logger.step( 'Шаг 3: Перерисовка managed-блока' );
+	const block = await renderAgentMdBlock( servers, templatePath );
+	const { targets, source } = await detectAgentMdTargets( { cwd, interactive: false } );
+
+	if ( source === 'default' ) {
+		// Neither AGENTS.md nor CLAUDE.md exists. `update` refreshes existing
+		// instructions; it must not create the file from scratch — that's `init`.
+		logger.warn( 'Нет ни AGENTS.md, ни CLAUDE.md — update не создаёт файлы инструкций.' );
+		logger.info( 'Запусти `seomi-ssh init`, чтобы создать файл инструкций агенту.' );
+	} else if ( dryRun ) {
+		logger.info( `[dry-run] managed-блок был бы обновлён в: ${ targets.join( ', ' ) }` );
+		process.stdout.write( '\n--- managed block preview ---\n' + block + '--- end preview ---\n' );
+	} else {
+		for ( const file of targets ) {
+			const name = file.split( /[\\/]/ ).pop();
+			// A CLAUDE.md that merely imports AGENTS.md is a redirect, not a
+			// block host — writing the block into it would duplicate content.
+			if ( name === 'CLAUDE.md' && isClaudeImportStub( file ) ) {
+				logger.info( `${ name }: оставлен как импорт @AGENTS.md (блок живёт в AGENTS.md)` );
+				continue;
+			}
+			const res = await insertOrUpdate( file, block, { namespace: MARKER_NS } );
+			logger.success( `${ res.action }: ${ file }` );
+		}
+		// If the block lives in AGENTS.md and Claude Code has no CLAUDE.md to
+		// read, drop the one-line @AGENTS.md import stub (idempotent no-op
+		// otherwise) — same guarantee `init` provides.
+		const stub = await ensureClaudeImportStub( { cwd } );
+		if ( stub.created ) {
+			logger.success( 'Создан CLAUDE.md (импорт @AGENTS.md) — Claude Code теперь читает AGENTS.md' );
+		}
+	}
+
+	logger.step( 'Готово' );
+	printSummary( servers, dryRun );
+	return 0;
+}

package/src/lib/env-writer.mjs

@@ -35,6 +35,37 @@ export function serializeEnv( items ) {
 	} ).join( '\n' );
 }
 
+/**
+ * Read the file at `filePath` into a flat `{ key: value }` map.
+ *
+ * Comments/blanks are ignored and, on duplicate keys, the FIRST occurrence
+ * wins (mirrors `mergeEnv`, which only updates the first occurrence). Returns
+ * an empty object when the file does not exist — callers treat "no file" and
+ * "no servers" identically, so this keeps them branch-free.
+ *
+ * This is the read half of the env round-trip: `serversFromEnv` turns the map
+ * back into server objects so `init`/`update` can re-render from disk.
+ *
+ * @param {string} filePath
+ * @returns {Promise<Record<string,string>>}
+ */
+export async function readEnv( filePath ) {
+	if ( ! existsSync( filePath ) ) {
+		logger.debug( `env-writer: readEnv — ${ filePath } does not exist, returning {}` );
+		return {};
+	}
+	const text = await readFile( filePath, 'utf8' );
+	const items = parseEnv( text );
+	const map = {};
+	for ( const it of items ) {
+		if ( it.type !== 'kv' ) continue;
+		if ( it.key in map ) continue; // first occurrence wins
+		map[ it.key ] = it.value;
+	}
+	logger.debug( `env-writer: readEnv — ${ Object.keys( map ).length } keys from ${ filePath }` );
+	return map;
+}
+
 /**
  * Merge `updates` (object) into the file at `filePath`.
  * Returns { created: boolean, added: string[], updated: string[], unchanged: string[] }.

package/src/lib/server-prompt.mjs

@@ -30,6 +30,18 @@ const ROLE_PROD = 'prod';
 const ROLE_DEV = 'dev';
 const ROLE_CUSTOM = '__custom__';
 
+/**
+ * Matches a prefixed server key and captures its `<PREFIX>` segment. The `SSH_`
+ * anchor keeps it from ever catching unrelated keys (`WP_PROD_SSH_HOST`,
+ * `OTHER_KEY`); `SSH_SERVERS` (the registry) has no suffix group and never
+ * matches, so it is never mistaken for a server.
+ */
+const SERVER_KEY_RE = /^SSH_(.+)_(HOST|USER|PORT|KEY|ROOT|ROLE)$/;
+
+function present( v ) {
+	return typeof v === 'string' && v.trim().length > 0;
+}
+
 /**
  * Normalize an arbitrary role label into a bare UPPER_SNAKE_CASE token.
  * Non-alphanumeric runs collapse to a single `_`; leading/trailing `_` are
@@ -157,9 +169,14 @@ export async function promptServers( { _prompts } = {} ) {
 
 /**
  * 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.
+ * Writes `SSH_<PREFIX>_HOST/USER/ROLE/PORT/KEY/ROOT` (optional PORT/ROOT keys
+ * skipped when blank) plus the `SSH_SERVERS` registry (csv of prefixes) so
+ * `update` can later enumerate every configured server.
+ *
+ * `SSH_<PREFIX>_ROLE` persists the human role label so it round-trips losslessly
+ * through `serversFromEnv` (the prefix alone loses dashes — `staging-eu` →
+ * `STAGING_EU`). Older `.env` files without it fall back to the lowercased
+ * prefix and self-heal on the next write.
  */
 export function toEnvUpdates( servers ) {
 	const updates = {};
@@ -167,6 +184,7 @@ export function toEnvUpdates( servers ) {
 		const p = s.prefix;
 		updates[ `SSH_${ p }_HOST` ] = s.host;
 		updates[ `SSH_${ p }_USER` ] = s.user;
+		if ( s.role ) updates[ `SSH_${ p }_ROLE` ] = s.role;
 		if ( s.port ) updates[ `SSH_${ p }_PORT` ] = s.port;
 		updates[ `SSH_${ p }_KEY` ] = s.keyPath;
 		if ( s.root ) updates[ `SSH_${ p }_ROOT` ] = s.root;
@@ -174,3 +192,107 @@ export function toEnvUpdates( servers ) {
 	updates.SSH_SERVERS = servers.map( ( s ) => s.prefix ).join( ',' );
 	return updates;
 }
+
+/**
+ * Reconstruct server objects from a flat `.claude/.env` map (the inverse of
+ * `toEnvUpdates`). The set of prefixes is the UNION of the `SSH_SERVERS`
+ * registry and every prefix discovered by scanning keys with `SERVER_KEY_RE` —
+ * so a server whose keys exist but dropped out of `SSH_SERVERS` (the
+ * `os-ndtnew` drift bug) is still recovered. Registry prefixes come first to
+ * keep ordering stable; discovered orphans follow.
+ *
+ * A prefix with no `HOST` is skipped (incomplete, unaddressable). Role falls
+ * back to the lowercased prefix when `SSH_<PREFIX>_ROLE` is absent. Pure: does
+ * not read disk or mutate its input.
+ *
+ * @param {Record<string,string>} envMap — map from `readEnv`.
+ * @returns {Array<object>} server objects (role/prefix/host/user/port/keyPath/root).
+ */
+export function serversFromEnv( envMap ) {
+	const map = envMap || {};
+
+	const fromRegistry = String( map.SSH_SERVERS || '' )
+		.split( ',' )
+		.map( ( s ) => s.trim() )
+		.filter( Boolean );
+
+	const discovered = [];
+	for ( const key of Object.keys( map ) ) {
+		const m = key.match( SERVER_KEY_RE );
+		if ( m ) discovered.push( m[ 1 ] );
+	}
+
+	// Registry-first union, de-duplicated, order-preserving.
+	const prefixes = [];
+	const seen = new Set();
+	for ( const p of [ ...fromRegistry, ...discovered ] ) {
+		if ( seen.has( p ) ) continue;
+		seen.add( p );
+		prefixes.push( p );
+	}
+
+	const servers = [];
+	const skipped = [];
+	for ( const prefix of prefixes ) {
+		const host = map[ `SSH_${ prefix }_HOST` ];
+		if ( ! present( host ) ) {
+			skipped.push( prefix );
+			continue;
+		}
+		const roleKey = map[ `SSH_${ prefix }_ROLE` ];
+		servers.push( {
+			role: present( roleKey ) ? roleKey.trim() : prefix.toLowerCase(),
+			prefix,
+			host: host.trim(),
+			user: ( map[ `SSH_${ prefix }_USER` ] || '' ).trim(),
+			port: ( map[ `SSH_${ prefix }_PORT` ] || '' ).trim(),
+			keyPath: ( map[ `SSH_${ prefix }_KEY` ] || '' ).trim(),
+			root: ( map[ `SSH_${ prefix }_ROOT` ] || '' ).trim(),
+		} );
+	}
+
+	const recovered = servers
+		.map( ( s ) => s.prefix )
+		.filter( ( p ) => ! fromRegistry.includes( p ) );
+	logger.debug(
+		`[server-prompt] serversFromEnv: распознано ${ servers.length }, ` +
+		`восстановлено orphan-префиксов ${ recovered.length }` +
+		( recovered.length ? ` [${ recovered.join( ',' ) }]` : '' ) +
+		`, пропущено без HOST ${ skipped.length }` +
+		( skipped.length ? ` [${ skipped.join( ',' ) }]` : '' )
+	);
+	return servers;
+}
+
+/**
+ * Merge two server lists by `prefix`. `incoming` wins on a prefix collision
+ * (a re-run of `init` re-entered that server), existing servers keep their
+ * original order and come first, and genuinely new incoming servers are
+ * appended. Pure: returns fresh objects, mutates neither argument.
+ *
+ * @param {Array<object>} existing — servers already configured (from `.env`).
+ * @param {Array<object>} incoming — servers from this session.
+ * @returns {Array<object>} merged list.
+ */
+export function mergeServers( existing, incoming ) {
+	const ex = Array.isArray( existing ) ? existing : [];
+	const inc = Array.isArray( incoming ) ? incoming : [];
+	const incByPrefix = new Map( inc.map( ( s ) => [ s.prefix, s ] ) );
+
+	const merged = [];
+	const used = new Set();
+	for ( const s of ex ) {
+		merged.push( { ...( incByPrefix.get( s.prefix ) || s ) } );
+		used.add( s.prefix );
+	}
+	for ( const s of inc ) {
+		if ( used.has( s.prefix ) ) continue;
+		merged.push( { ...s } );
+		used.add( s.prefix );
+	}
+
+	logger.debug(
+		`[server-prompt] mergeServers: existing=${ ex.length }, incoming=${ inc.length }, итого=${ merged.length }`
+	);
+	return merged;
+}