@seomi/ssh 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) SEOMI. All rights reserved.
+
+This software is proprietary and confidential.
+
+Permitted use:
+- Internal use within SEOMI and on projects developed or maintained by SEOMI.
+- Use by SEOMI clients on their own projects as part of services provided by SEOMI.
+
+Not permitted without prior written consent from SEOMI:
+- Redistribution, sublicensing, or sale of this software or any substantial portion
+  of it.
+- Reverse-engineering for the purpose of creating a competing product.
+- Removal of copyright or license notices.
+
+THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
+ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,13 +1,14 @@
 # @seomi/ssh
 
-> Одной командой настраивает беспарольный SSH-доступ для AI-агента к вашим серверам.
+**English** | [Русский](https://github.com/Mikeekb/seomi-ssh/blob/main/README.ru.md)
 
-`@seomi/ssh` — CLI-инсталлятор: за один интерактивный прогон он настраивает доступ агента
-по SSH-ключу к одному или нескольким серверам (dev / prod / кастомные) и записывает карту
-доступа в инструкции агента (`AGENTS.md` / `CLAUDE.md`). Облегчённый родственник
-[`@seomi/wp-mcp`](../seomi-wp-mcp) — без WordPress и MCP, только SSH.
+> One command sets up passwordless SSH access for an AI agent to your servers.
 
-## Быстрый старт
+`@seomi/ssh` is a CLI installer: in a single interactive pass it configures key-based SSH
+access for an agent to one or more servers (dev / prod / custom) and writes an access map
+into the agent instructions (`AGENTS.md` / `CLAUDE.md`). It's a lightweight sibling of
+[`@seomi/wp-mcp`](https://github.com/Mikeekb/seomi-wp-mcp) — the SSH wizard and agent-instruction
+logic, without the WordPress and MCP parts.
 
 ```bash
 npm install -g @seomi/ssh
@@ -15,47 +16,103 @@ cd my-project
 seomi-ssh init
 ```
 
-## Возможности
+## Features
 
-- **`init`** — интерактивная настройка: спрашивает про серверы **в цикле** (роль, host,
-  user, port, ключ, рабочая директория), повторяет «добавить ещё?» до отказа. 1..N серверов.
-- **SSH-визард** на каждый сервер — генерация ed25519-ключа (или переиспользование),
-  копирование публичного ключа (`ssh-copy-id` → ssh-pipe fallback), проверка по `BatchMode`,
-  при неудаче — печать ручной подсказки с содержимым `.pub`.
-- **Запись инструкций агенту** — managed-блок с картой серверов и готовыми примерами
-  `ssh` / `scp` / `rsync` (значения берутся из `.claude/.env`).
-- **Skill `aif-ssh`** — копируется в `.claude/skills/` целевого проекта и учит агента
-  пользоваться настроенным доступом.
-- **Идемпотентность** — повторный запуск не дублирует ключи, env-записи и managed-блок.
+- **`init`** — interactive setup. Asks about servers **in a loop** (role, host, user, port,
+  key path, optional working directory) and repeats "add another?" until you decline.
+  Supports any number of servers: prod only; dev + prod; or an arbitrary set.
+- **SSH wizard per server** — generates an ed25519 key (or reuses one), copies the public
+  key (`ssh-copy-id` → ssh-pipe fallback), verifies with `ssh -o BatchMode=yes`, and on
+  failure prints a manual hint with the `.pub` contents.
+- **Writes agent instructions** — a managed block with a server map and ready-to-use
+  `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.
+- **Idempotent** — re-running never duplicates keys, env entries, or the managed block.
 
-> `update` и `doctor` объявлены в справке, но пока не реализованы (заглушки).
+> `update` and `doctor` are declared in `--help` but are not implemented yet (stubs).
 
-## Пример
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `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) |
+
+## Requirements
+
+- **Node 20+** for the CLI itself.
+- **OpenSSH client** (`ssh`, `ssh-keygen`) on the local machine. `ssh-copy-id` is optional —
+  without it (typical on Windows OpenSSH) the wizard uses a portable ssh-pipe fallback.
+
+## How the SSH wizard works
+
+For each server, a strategy chain with graceful degradation:
+
+1. **Keygen** — generate `ed25519` if the key is missing (`ssh-keygen -N ''`, empty passphrase
+   so the agent can authenticate non-interactively), otherwise reuse the existing key.
+2. **Copy** — `ssh-copy-id` (asks for the password once). If the binary isn't on PATH, fall
+   back to piping the public key into `~/.ssh/authorized_keys` over `ssh` (deduplicated).
+3. **Verify** — `ssh -o BatchMode=yes ... 'echo ok'`. BatchMode disables password prompts,
+   so a non-zero exit reliably means the key wasn't accepted.
+4. **Fallback** — on failed verification, print a manual hint with the `.pub` contents.
+
+A failure on one server doesn't abort the run — the others continue.
+
+## Configuration
+
+Connection parameters live in `.claude/.env` (gitignored) as flat keys with a **role prefix**.
+One server = one key group:
+
+| Key | Purpose | Written |
+|-----|---------|---------|
+| `SSH_<PREFIX>_HOST` | domain or IP | always |
+| `SSH_<PREFIX>_USER` | SSH user | 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 |
+
+`<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`.
+
+## Example
 
 ```bash
 $ seomi-ssh init
-› Шаг 1: Опрос серверов
-? Роль сервера › prod
-? [prod] Host (домен или IP) › prod.example.com
-? [prod] SSH-пользователь › ai-agent
-? Добавить ещё один сервер? › No
-› Шаг 2: Настройка SSH-ключей
-[ok] «prod»: ключ настроен и проверен
-› Шаг 3: Запись реквизитов в .claude/.env
-› Шаг 4: Инструкции агенту (AGENTS.md / CLAUDE.md)
+› Step 1: Server prompts
+? Server role › prod
+? [prod] Host (domain or IP) › prod.example.com
+? [prod] SSH user › ai-agent
+? Add another server? › No
+› Step 2: SSH keys
+[ok] "prod": key configured and verified
+› Step 4: Agent instructions (AGENTS.md / CLAUDE.md)
 [ok] created: AGENTS.md
 ```
 
-Используйте `seomi-ssh init --dry-run`, чтобы прогнать опрос без записи на диск и SSH-вызовов.
-
 ---
 
-## Документация
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [`init` command](https://github.com/Mikeekb/seomi-ssh/blob/main/docs/init.md) | SSH setup behavior, `.claude/.env` configuration, examples, troubleshooting |
 
-| Раздел | Описание |
-|--------|----------|
-| [Команда `init`](docs/init.md) | Настройка SSH-доступа: поведение, конфигурация `.claude/.env`, примеры, диагностика |
+## License
 
-## Лицензия
+Proprietary — © SEOMI. See `LICENSE`.
+
+## Related projects
+
+- [@seomi/wp-mcp](https://github.com/Mikeekb/seomi-wp-mcp) — the WordPress/MCP sibling this package is derived from.
+- [ai-factory](https://github.com/lee-to/ai-factory) — companion project for AI dev context.
+
+---
 
-Условия лицензии указаны в поле `license` файла `package.json`.
+Built and maintained by [SEOmi.ru — Web Development](https://seomi.ru/).

package/README.ru.md

@@ -0,0 +1,118 @@
+# @seomi/ssh
+
+[English](https://github.com/Mikeekb/seomi-ssh/blob/main/README.md) | **Русский**
+
+> Одной командой настраивает беспарольный SSH-доступ для AI-агента к вашим серверам.
+
+`@seomi/ssh` — CLI-инсталлятор: за один интерактивный прогон он настраивает доступ агента
+по SSH-ключу к одному или нескольким серверам (dev / prod / кастомные) и записывает карту
+доступа в инструкции агента (`AGENTS.md` / `CLAUDE.md`). Облегчённый родственник
+[`@seomi/wp-mcp`](https://github.com/Mikeekb/seomi-wp-mcp) — взяты только SSH-визард и логика
+инструкций агенту, без WordPress и MCP.
+
+```bash
+npm install -g @seomi/ssh
+cd my-project
+seomi-ssh init
+```
+
+## Возможности
+
+- **`init`** — интерактивная настройка. Спрашивает про серверы **в цикле** (роль, host,
+  user, port, путь к ключу, опционально рабочая директория) и повторяет «добавить ещё?»,
+  пока не откажешься. Любое число серверов: только prod; dev + prod; произвольный набор.
+- **SSH-визард на каждый сервер** — генерация ed25519-ключа (или переиспользование),
+  копирование публичного ключа (`ssh-copy-id` → ssh-pipe fallback), проверка по
+  `ssh -o BatchMode=yes`, и при неудаче — печать ручной подсказки с содержимым `.pub`.
+- **Запись инструкций агенту** — managed-блок с картой серверов и готовыми примерами
+  `ssh` / `scp` / `rsync`, значения берутся из `.claude/.env`.
+- **Skill `aif-ssh`** — копируется в `.claude/skills/` проекта и учит агента пользоваться
+  настроенным доступом.
+- **Идемпотентность** — повторный запуск не дублирует ключи, env-записи и managed-блок.
+
+> `update` и `doctor` объявлены в `--help`, но пока не реализованы (заглушки).
+
+## Команды
+
+| Команда | Что делает |
+|---------|------------|
+| `seomi-ssh init` | Интерактивная настройка (см. выше) |
+| `seomi-ssh init --dry-run` | Прогон опроса без записи на диск и SSH-вызовов; превью блока |
+| `seomi-ssh init --verbose` | Включает debug-логирование |
+| `seomi-ssh --help` | Справка |
+| `seomi-ssh --version` | Версия |
+| `seomi-ssh update` / `doctor` | Зарезервированы (пока не реализованы) |
+
+## Требования
+
+- **Node 20+** для самого CLI.
+- **OpenSSH client** (`ssh`, `ssh-keygen`) на локальной машине. `ssh-copy-id` — опционально:
+  без него (типично для Windows OpenSSH) визард использует портируемый ssh-pipe fallback.
+
+## Как работает SSH-визард
+
+Для каждого сервера — цепочка стратегий с graceful degradation:
+
+1. **Keygen** — генерирует `ed25519`, если ключа нет (`ssh-keygen -N ''`, пустая passphrase —
+   агенту нужен неинтерактивный доступ), иначе переиспользует существующий.
+2. **Copy** — `ssh-copy-id` (один раз спросит пароль). Если бинарника нет на PATH — fallback:
+   публичный ключ передаётся в `~/.ssh/authorized_keys` через `ssh` (с дедупликацией).
+3. **Verify** — `ssh -o BatchMode=yes ... 'echo ok'`. BatchMode отключает запрос пароля,
+   поэтому ненулевой код = ключ не принят.
+4. **Fallback** — при неудачной проверке печатается ручная подсказка с содержимым `.pub`.
+
+Ошибка одного сервера не прерывает прогон — остальные продолжают.
+
+## Конфигурация
+
+Параметры доступа лежат в `.claude/.env` (gitignored) плоскими ключами с **префиксом роли**.
+Один сервер = одна группа ключей:
+
+| Ключ | Назначение | Пишется |
+|------|------------|---------|
+| `SSH_<PREFIX>_HOST` | домен или IP | всегда |
+| `SSH_<PREFIX>_USER` | SSH-пользователь | всегда |
+| `SSH_<PREFIX>_PORT` | порт | если задан |
+| `SSH_<PREFIX>_KEY`  | путь к приватному ключу | всегда |
+| `SSH_<PREFIX>_ROOT` | рабочая директория на сервере | если задана |
+| `SSH_SERVERS` | csv-реестр всех префиксов | всегда |
+
+`<PREFIX>` — это роль, нормализованная в `UPPER_SNAKE_CASE` (`prod` → `PROD`, `staging-eu` →
+`STAGING_EU`); при повторе роли префикс получает уникальный суффикс (`PROD`, затем `PROD_2`).
+`.claude/.env` — **первое место**, куда агент смотрит за реквизитами доступа, а не `~/.ssh/config`.
+
+## Пример
+
+```bash
+$ seomi-ssh init
+› Шаг 1: Опрос серверов
+? Роль сервера › prod
+? [prod] Host (домен или IP) › prod.example.com
+? [prod] SSH-пользователь › ai-agent
+? Добавить ещё один сервер? › No
+› Шаг 2: Настройка SSH-ключей
+[ok] «prod»: ключ настроен и проверен
+› Шаг 4: Инструкции агенту (AGENTS.md / CLAUDE.md)
+[ok] created: AGENTS.md
+```
+
+---
+
+## Документация
+
+| Раздел | Описание |
+|--------|----------|
+| [Команда `init`](https://github.com/Mikeekb/seomi-ssh/blob/main/docs/init.md) | Поведение `init`, конфигурация `.claude/.env`, примеры, диагностика |
+
+## Лицензия
+
+Proprietary — © SEOMI. См. `LICENSE`.
+
+## Связанные проекты
+
+- [@seomi/wp-mcp](https://github.com/Mikeekb/seomi-wp-mcp) — родственный WordPress/MCP-пакет, от которого произошёл этот.
+- [ai-factory](https://github.com/lee-to/ai-factory) — спутник для AI-контекста разработки.
+
+---
+
+Разработка и сопровождение — [Разработка сайтов SEOmi.ru](https://seomi.ru/).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seomi/ssh",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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": {
@@ -12,6 +12,7 @@
     "skills",
     "templates",
     "README.md",
+    "README.ru.md",
     "LICENSE"
   ],
   "engines": {
@@ -33,6 +34,14 @@
     "deploy"
   ],
   "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mikeekb/seomi-ssh.git"
+  },
+  "homepage": "https://github.com/Mikeekb/seomi-ssh#readme",
+  "bugs": {
+    "url": "https://github.com/Mikeekb/seomi-ssh/issues"
+  },
   "publishConfig": {
     "access": "public"
   },

package/src/commands/init.mjs

@@ -15,13 +15,14 @@
  */
 
 import { mkdir, copyFile } from 'node:fs/promises';
+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 { ensureSshKey } from '../lib/ssh-key-setup.mjs';
-import { detectAgentMdTargets } from '../lib/agent-md-target.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';
 
@@ -117,6 +118,10 @@ export async function initCommand( options = {} ) {
 	if ( dryRun ) {
 		const { targets } = await detectAgentMdTargets( { cwd, interactive: false } );
 		logger.info( `[dry-run] managed-блок был бы записан в: ${ targets.join( ', ' ) || '(none)' }` );
+		const wouldStub = targets.some( ( f ) => f.endsWith( 'AGENTS.md' ) ) && ! existsSync( join( cwd, 'CLAUDE.md' ) );
+		if ( wouldStub ) {
+			logger.info( '[dry-run] был бы создан CLAUDE.md с импортом @AGENTS.md (Claude Code не читает AGENTS.md)' );
+		}
 		process.stdout.write( '\n--- managed block preview ---\n' + block + '--- end preview ---\n' );
 	} else {
 		const { targets } = await detectAgentMdTargets( {
@@ -128,9 +133,26 @@ export async function initCommand( options = {} ) {
 			logger.warn( 'Целевой файл инструкций не выбран — managed-блок не записан.' );
 		}
 		for ( const file of targets ) {
+			const name = file.split( /[\\/]/ ).pop();
+			// CLAUDE.md, который лишь импортирует AGENTS.md, — это редирект, а не
+			// носитель блока: писать в него блок значит снова продублировать
+			// контент. Оставляем его чистым импортом `@AGENTS.md`.
+			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 }` );
 		}
+		// Claude Code не читает AGENTS.md — если блок лёг туда и CLAUDE.md нет,
+		// создаём однострочный CLAUDE.md с импортом, чтобы Claude Code видел те
+		// же инструкции (включая доступы по SSH).
+		if ( targets.length > 0 ) {
+			const stub = await ensureClaudeImportStub( { cwd } );
+			if ( stub.created ) {
+				logger.success( 'Создан CLAUDE.md (импорт @AGENTS.md) — Claude Code теперь читает AGENTS.md' );
+			}
+		}
 	}
 
 	// --- 6. Copy the access skill ----------------------------------------

package/src/lib/agent-md-target.mjs

@@ -1,11 +1,14 @@
 /**
  * Target-aware detection for AI agent instructions files (AGENTS.md / CLAUDE.md).
  *
- * Claude Code reads `CLAUDE.md` if present and IGNORES `AGENTS.md` next to it.
- * Other agents (e.g. ai-factory tooling) treat `AGENTS.md` as the universal
- * standard. This detector lets `init` / `update` / `doctor` keep the managed
- * `seomi-ssh` block in the file the project actually uses — and, when both
- * coexist, synchronize the block into both so no agent loses context.
+ * Claude Code reads `CLAUDE.md` and NEVER `AGENTS.md` — not even when no
+ * CLAUDE.md exists next to it (see https://code.claude.com/docs/en/memory →
+ * "AGENTS.md"). Other agents (Cursor, ai-factory tooling, etc.) treat
+ * `AGENTS.md` as the universal standard. To satisfy both without duplicating
+ * content, we keep the managed `seomi-ssh` block in `AGENTS.md` (the single
+ * source of truth) and drop a one-line `CLAUDE.md` that imports it via
+ * `@AGENTS.md` — so Claude Code reads the same instructions. See
+ * `ensureClaudeImportStub` below.
  *
  * Decision tree:
  *   1. Both files exist          → targets = [AGENTS.md, CLAUDE.md]      (source='both')
@@ -15,7 +18,8 @@
  *   5. Neither, interactive=true → select prompt → user / skipped        (source='user'|'skipped')
  */
 
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { logger } from './logger.mjs';
 
@@ -23,6 +27,19 @@ export const DEFAULT_TARGET = 'AGENTS.md';
 const AGENTS_FILE = 'AGENTS.md';
 const CLAUDE_FILE = 'CLAUDE.md';
 
+/**
+ * One-line `CLAUDE.md` that imports `AGENTS.md`. The HTML comment is stripped
+ * by Claude Code before the file enters context (it only documents the file for
+ * humans), so the effective payload is just the `@AGENTS.md` import directive.
+ */
+export const CLAUDE_IMPORT_STUB = `<!--
+  Managed by @seomi/ssh. Claude Code loads CLAUDE.md but never AGENTS.md,
+  so this stub imports AGENTS.md — the agent-agnostic source of truth — keeping
+  Claude Code and other agents on the same instructions. Edit AGENTS.md, not this.
+-->
+@AGENTS.md
+`;
+
 /**
  * Detect which agent-instructions file(s) the project uses and return absolute
  * paths to be updated with the managed `seomi-ssh` block.
@@ -105,3 +122,51 @@ export async function detectAgentMdTargets( { cwd, interactive = false, defaultN
 	logger.success( `[agent-md] targets: ${ targets.join( ', ' ) }` );
 	return { targets, source: 'user' };
 }
+
+/**
+ * Is `claudePath` a thin import stub (it imports AGENTS.md and carries no
+ * managed seomi-ssh block of its own)? Lets callers tell an intended
+ * `@AGENTS.md` redirect apart from a real duplicated block.
+ *
+ * @param {string} claudePath — absolute path to the candidate CLAUDE.md
+ * @returns {boolean}
+ */
+export function isClaudeImportStub( claudePath ) {
+	if ( ! existsSync( claudePath ) ) return false;
+	const text = readFileSync( claudePath, 'utf8' );
+	const importsAgents = /(^|\n)[ \t]*@AGENTS\.md[ \t]*(\r?\n|$)/.test( text );
+	const hasManagedBlock = /<!--\s*seomi-ssh:start\s*-->/.test( text );
+	return importsAgents && ! hasManagedBlock;
+}
+
+/**
+ * Ensure Claude Code can read the project's instructions when the managed block
+ * lives in `AGENTS.md`. Claude Code never reads `AGENTS.md`, so when only that
+ * file exists we drop a one-line `CLAUDE.md` that imports it (`@AGENTS.md`).
+ *
+ * Idempotent and non-destructive: does nothing when there is no `AGENTS.md`, or
+ * when a `CLAUDE.md` already exists (we never overwrite a user's CLAUDE.md).
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd — project root
+ * @returns {Promise<{ created: boolean, reason: 'created'|'no-agents'|'claude-exists', path: string }>}
+ */
+export async function ensureClaudeImportStub( { cwd } = {} ) {
+	if ( ! cwd ) throw new Error( 'ensureClaudeImportStub: `cwd` is required' );
+
+	const agentsPath = join( cwd, AGENTS_FILE );
+	const claudePath = join( cwd, CLAUDE_FILE );
+
+	if ( ! existsSync( agentsPath ) ) {
+		logger.debug( '[agent-md] import stub skipped — no AGENTS.md to import' );
+		return { created: false, reason: 'no-agents', path: claudePath };
+	}
+	if ( existsSync( claudePath ) ) {
+		logger.debug( '[agent-md] import stub skipped — CLAUDE.md already exists' );
+		return { created: false, reason: 'claude-exists', path: claudePath };
+	}
+
+	await writeFile( claudePath, CLAUDE_IMPORT_STUB, 'utf8' );
+	logger.success( '[agent-md] created CLAUDE.md (@AGENTS.md import) so Claude Code reads AGENTS.md' );
+	return { created: true, reason: 'created', path: claudePath };
+}