@seomi/ssh 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/LICENSE +19 -0
  2. package/README.md +93 -36
  3. package/README.ru.md +118 -0
  4. package/package.json +2 -1
package/LICENSE ADDED
@@ -0,0 +1,19 @@
1
+ Copyright (c) SEOMI. All rights reserved.
2
+
3
+ This software is proprietary and confidential.
4
+
5
+ Permitted use:
6
+ - Internal use within SEOMI and on projects developed or maintained by SEOMI.
7
+ - Use by SEOMI clients on their own projects as part of services provided by SEOMI.
8
+
9
+ Not permitted without prior written consent from SEOMI:
10
+ - Redistribution, sublicensing, or sale of this software or any substantial portion
11
+ of it.
12
+ - Reverse-engineering for the purpose of creating a competing product.
13
+ - Removal of copyright or license notices.
14
+
15
+ THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
16
+ INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
17
+ PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
18
+ ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM, OUT OF OR IN CONNECTION WITH THE
19
+ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
package/README.md CHANGED
@@ -1,13 +1,14 @@
1
1
  # @seomi/ssh
2
2
 
3
- > Одной командой настраивает беспарольный SSH-доступ для AI-агента к вашим серверам.
3
+ **English** | [Русский](./README.ru.md)
4
4
 
5
- `@seomi/ssh` — CLI-инсталлятор: за один интерактивный прогон он настраивает доступ агента
6
- по SSH-ключу к одному или нескольким серверам (dev / prod / кастомные) и записывает карту
7
- доступа в инструкции агента (`AGENTS.md` / `CLAUDE.md`). Облегчённый родственник
8
- [`@seomi/wp-mcp`](../seomi-wp-mcp) — без WordPress и MCP, только SSH.
5
+ > One command sets up passwordless SSH access for an AI agent to your servers.
9
6
 
10
- ## Быстрый старт
7
+ `@seomi/ssh` is a CLI installer: in a single interactive pass it configures key-based SSH
8
+ access for an agent to one or more servers (dev / prod / custom) and writes an access map
9
+ into the agent instructions (`AGENTS.md` / `CLAUDE.md`). It's a lightweight sibling of
10
+ [`@seomi/wp-mcp`](https://github.com/Mikeekb/seomi-wp-mcp) — the SSH wizard and agent-instruction
11
+ logic, without the WordPress and MCP parts.
11
12
 
12
13
  ```bash
13
14
  npm install -g @seomi/ssh
@@ -15,47 +16,103 @@ cd my-project
15
16
  seomi-ssh init
16
17
  ```
17
18
 
18
- ## Возможности
19
+ ## Features
19
20
 
20
- - **`init`** — интерактивная настройка: спрашивает про серверы **в цикле** (роль, host,
21
- user, port, ключ, рабочая директория), повторяет «добавить ещё?» до отказа. 1..N серверов.
22
- - **SSH-визард** на каждый сервер — генерация ed25519-ключа (или переиспользование),
23
- копирование публичного ключа (`ssh-copy-id` → ssh-pipe fallback), проверка по `BatchMode`,
24
- при неудаче — печать ручной подсказки с содержимым `.pub`.
25
- - **Запись инструкций агенту** — managed-блок с картой серверов и готовыми примерами
26
- `ssh` / `scp` / `rsync` (значения берутся из `.claude/.env`).
27
- - **Skill `aif-ssh`** — копируется в `.claude/skills/` целевого проекта и учит агента
28
- пользоваться настроенным доступом.
29
- - **Идемпотентность** — повторный запуск не дублирует ключи, env-записи и managed-блок.
21
+ - **`init`** — interactive setup. Asks about servers **in a loop** (role, host, user, port,
22
+ key path, optional working directory) and repeats "add another?" until you decline.
23
+ Supports any number of servers: prod only; dev + prod; or an arbitrary set.
24
+ - **SSH wizard per server** — generates an ed25519 key (or reuses one), copies the public
25
+ key (`ssh-copy-id` → ssh-pipe fallback), verifies with `ssh -o BatchMode=yes`, and on
26
+ failure prints a manual hint with the `.pub` contents.
27
+ - **Writes agent instructions** — a managed block with a server map and ready-to-use
28
+ `ssh` / `scp` / `rsync` examples, values pulled from `.claude/.env`.
29
+ - **`aif-ssh` skill** — copied into the project's `.claude/skills/` so the agent knows how
30
+ to use the configured access.
31
+ - **Idempotent** — re-running never duplicates keys, env entries, or the managed block.
30
32
 
31
- > `update` и `doctor` объявлены в справке, но пока не реализованы (заглушки).
33
+ > `update` and `doctor` are declared in `--help` but are not implemented yet (stubs).
32
34
 
33
- ## Пример
35
+ ## Commands
36
+
37
+ | Command | What it does |
38
+ |---------|--------------|
39
+ | `seomi-ssh init` | Interactive setup (see above) |
40
+ | `seomi-ssh init --dry-run` | Run the prompts without touching disk or SSH; preview the block |
41
+ | `seomi-ssh init --verbose` | Add debug-level logging |
42
+ | `seomi-ssh --help` | Show usage |
43
+ | `seomi-ssh --version` | Print version |
44
+ | `seomi-ssh update` / `doctor` | Reserved (not implemented yet) |
45
+
46
+ ## Requirements
47
+
48
+ - **Node 20+** for the CLI itself.
49
+ - **OpenSSH client** (`ssh`, `ssh-keygen`) on the local machine. `ssh-copy-id` is optional —
50
+ without it (typical on Windows OpenSSH) the wizard uses a portable ssh-pipe fallback.
51
+
52
+ ## How the SSH wizard works
53
+
54
+ For each server, a strategy chain with graceful degradation:
55
+
56
+ 1. **Keygen** — generate `ed25519` if the key is missing (`ssh-keygen -N ''`, empty passphrase
57
+ so the agent can authenticate non-interactively), otherwise reuse the existing key.
58
+ 2. **Copy** — `ssh-copy-id` (asks for the password once). If the binary isn't on PATH, fall
59
+ back to piping the public key into `~/.ssh/authorized_keys` over `ssh` (deduplicated).
60
+ 3. **Verify** — `ssh -o BatchMode=yes ... 'echo ok'`. BatchMode disables password prompts,
61
+ so a non-zero exit reliably means the key wasn't accepted.
62
+ 4. **Fallback** — on failed verification, print a manual hint with the `.pub` contents.
63
+
64
+ A failure on one server doesn't abort the run — the others continue.
65
+
66
+ ## Configuration
67
+
68
+ Connection parameters live in `.claude/.env` (gitignored) as flat keys with a **role prefix**.
69
+ One server = one key group:
70
+
71
+ | Key | Purpose | Written |
72
+ |-----|---------|---------|
73
+ | `SSH_<PREFIX>_HOST` | domain or IP | always |
74
+ | `SSH_<PREFIX>_USER` | SSH user | always |
75
+ | `SSH_<PREFIX>_PORT` | port | if provided |
76
+ | `SSH_<PREFIX>_KEY` | private key path | always |
77
+ | `SSH_<PREFIX>_ROOT` | remote working directory | if provided |
78
+ | `SSH_SERVERS` | csv registry of all prefixes | always |
79
+
80
+ `<PREFIX>` is the role normalized to `UPPER_SNAKE_CASE` (`prod` → `PROD`, `staging-eu` →
81
+ `STAGING_EU`); duplicate roles get a unique suffix (`PROD`, then `PROD_2`). `.claude/.env`
82
+ is the **first place** the agent looks for access details — not `~/.ssh/config`.
83
+
84
+ ## Example
34
85
 
35
86
  ```bash
36
87
  $ seomi-ssh init
37
- › Шаг 1: Опрос серверов
38
- ? Роль сервера › prod
39
- ? [prod] Host (домен или IP) › prod.example.com
40
- ? [prod] SSH-пользователь › ai-agent
41
- ? Добавить ещё один сервер? › No
42
- › Шаг 2: Настройка SSH-ключей
43
- [ok] «prod»: ключ настроен и проверен
44
- › Шаг 3: Запись реквизитов в .claude/.env
45
- › Шаг 4: Инструкции агенту (AGENTS.md / CLAUDE.md)
88
+ › Step 1: Server prompts
89
+ ? Server role › prod
90
+ ? [prod] Host (domain or IP) › prod.example.com
91
+ ? [prod] SSH user › ai-agent
92
+ ? Add another server? › No
93
+ › Step 2: SSH keys
94
+ [ok] "prod": key configured and verified
95
+ › Step 4: Agent instructions (AGENTS.md / CLAUDE.md)
46
96
  [ok] created: AGENTS.md
47
97
  ```
48
98
 
49
- Используйте `seomi-ssh init --dry-run`, чтобы прогнать опрос без записи на диск и SSH-вызовов.
50
-
51
99
  ---
52
100
 
53
- ## Документация
101
+ ## Documentation
102
+
103
+ | Guide | Description |
104
+ |-------|-------------|
105
+ | [`init` command](docs/init.md) | SSH setup behavior, `.claude/.env` configuration, examples, troubleshooting |
54
106
 
55
- | Раздел | Описание |
56
- |--------|----------|
57
- | [Команда `init`](docs/init.md) | Настройка SSH-доступа: поведение, конфигурация `.claude/.env`, примеры, диагностика |
107
+ ## License
58
108
 
59
- ## Лицензия
109
+ Proprietary — © SEOMI. See `LICENSE`.
110
+
111
+ ## Related projects
112
+
113
+ - [@seomi/wp-mcp](https://github.com/Mikeekb/seomi-wp-mcp) — the WordPress/MCP sibling this package is derived from.
114
+ - [ai-factory](https://github.com/lee-to/ai-factory) — companion project for AI dev context.
115
+
116
+ ---
60
117
 
61
- Условия лицензии указаны в поле `license` файла `package.json`.
118
+ Built and maintained by [SEOmi.ru — Web Development](https://seomi.ru/).
package/README.ru.md ADDED
@@ -0,0 +1,118 @@
1
+ # @seomi/ssh
2
+
3
+ [English](./README.md) | **Русский**
4
+
5
+ > Одной командой настраивает беспарольный SSH-доступ для AI-агента к вашим серверам.
6
+
7
+ `@seomi/ssh` — CLI-инсталлятор: за один интерактивный прогон он настраивает доступ агента
8
+ по SSH-ключу к одному или нескольким серверам (dev / prod / кастомные) и записывает карту
9
+ доступа в инструкции агента (`AGENTS.md` / `CLAUDE.md`). Облегчённый родственник
10
+ [`@seomi/wp-mcp`](https://github.com/Mikeekb/seomi-wp-mcp) — взяты только SSH-визард и логика
11
+ инструкций агенту, без WordPress и MCP.
12
+
13
+ ```bash
14
+ npm install -g @seomi/ssh
15
+ cd my-project
16
+ seomi-ssh init
17
+ ```
18
+
19
+ ## Возможности
20
+
21
+ - **`init`** — интерактивная настройка. Спрашивает про серверы **в цикле** (роль, host,
22
+ user, port, путь к ключу, опционально рабочая директория) и повторяет «добавить ещё?»,
23
+ пока не откажешься. Любое число серверов: только prod; dev + prod; произвольный набор.
24
+ - **SSH-визард на каждый сервер** — генерация ed25519-ключа (или переиспользование),
25
+ копирование публичного ключа (`ssh-copy-id` → ssh-pipe fallback), проверка по
26
+ `ssh -o BatchMode=yes`, и при неудаче — печать ручной подсказки с содержимым `.pub`.
27
+ - **Запись инструкций агенту** — managed-блок с картой серверов и готовыми примерами
28
+ `ssh` / `scp` / `rsync`, значения берутся из `.claude/.env`.
29
+ - **Skill `aif-ssh`** — копируется в `.claude/skills/` проекта и учит агента пользоваться
30
+ настроенным доступом.
31
+ - **Идемпотентность** — повторный запуск не дублирует ключи, env-записи и managed-блок.
32
+
33
+ > `update` и `doctor` объявлены в `--help`, но пока не реализованы (заглушки).
34
+
35
+ ## Команды
36
+
37
+ | Команда | Что делает |
38
+ |---------|------------|
39
+ | `seomi-ssh init` | Интерактивная настройка (см. выше) |
40
+ | `seomi-ssh init --dry-run` | Прогон опроса без записи на диск и SSH-вызовов; превью блока |
41
+ | `seomi-ssh init --verbose` | Включает debug-логирование |
42
+ | `seomi-ssh --help` | Справка |
43
+ | `seomi-ssh --version` | Версия |
44
+ | `seomi-ssh update` / `doctor` | Зарезервированы (пока не реализованы) |
45
+
46
+ ## Требования
47
+
48
+ - **Node 20+** для самого CLI.
49
+ - **OpenSSH client** (`ssh`, `ssh-keygen`) на локальной машине. `ssh-copy-id` — опционально:
50
+ без него (типично для Windows OpenSSH) визард использует портируемый ssh-pipe fallback.
51
+
52
+ ## Как работает SSH-визард
53
+
54
+ Для каждого сервера — цепочка стратегий с graceful degradation:
55
+
56
+ 1. **Keygen** — генерирует `ed25519`, если ключа нет (`ssh-keygen -N ''`, пустая passphrase —
57
+ агенту нужен неинтерактивный доступ), иначе переиспользует существующий.
58
+ 2. **Copy** — `ssh-copy-id` (один раз спросит пароль). Если бинарника нет на PATH — fallback:
59
+ публичный ключ передаётся в `~/.ssh/authorized_keys` через `ssh` (с дедупликацией).
60
+ 3. **Verify** — `ssh -o BatchMode=yes ... 'echo ok'`. BatchMode отключает запрос пароля,
61
+ поэтому ненулевой код = ключ не принят.
62
+ 4. **Fallback** — при неудачной проверке печатается ручная подсказка с содержимым `.pub`.
63
+
64
+ Ошибка одного сервера не прерывает прогон — остальные продолжают.
65
+
66
+ ## Конфигурация
67
+
68
+ Параметры доступа лежат в `.claude/.env` (gitignored) плоскими ключами с **префиксом роли**.
69
+ Один сервер = одна группа ключей:
70
+
71
+ | Ключ | Назначение | Пишется |
72
+ |------|------------|---------|
73
+ | `SSH_<PREFIX>_HOST` | домен или IP | всегда |
74
+ | `SSH_<PREFIX>_USER` | SSH-пользователь | всегда |
75
+ | `SSH_<PREFIX>_PORT` | порт | если задан |
76
+ | `SSH_<PREFIX>_KEY` | путь к приватному ключу | всегда |
77
+ | `SSH_<PREFIX>_ROOT` | рабочая директория на сервере | если задана |
78
+ | `SSH_SERVERS` | csv-реестр всех префиксов | всегда |
79
+
80
+ `<PREFIX>` — это роль, нормализованная в `UPPER_SNAKE_CASE` (`prod` → `PROD`, `staging-eu` →
81
+ `STAGING_EU`); при повторе роли префикс получает уникальный суффикс (`PROD`, затем `PROD_2`).
82
+ `.claude/.env` — **первое место**, куда агент смотрит за реквизитами доступа, а не `~/.ssh/config`.
83
+
84
+ ## Пример
85
+
86
+ ```bash
87
+ $ seomi-ssh init
88
+ › Шаг 1: Опрос серверов
89
+ ? Роль сервера › prod
90
+ ? [prod] Host (домен или IP) › prod.example.com
91
+ ? [prod] SSH-пользователь › ai-agent
92
+ ? Добавить ещё один сервер? › No
93
+ › Шаг 2: Настройка SSH-ключей
94
+ [ok] «prod»: ключ настроен и проверен
95
+ › Шаг 4: Инструкции агенту (AGENTS.md / CLAUDE.md)
96
+ [ok] created: AGENTS.md
97
+ ```
98
+
99
+ ---
100
+
101
+ ## Документация
102
+
103
+ | Раздел | Описание |
104
+ |--------|----------|
105
+ | [Команда `init`](docs/init.md) | Поведение `init`, конфигурация `.claude/.env`, примеры, диагностика |
106
+
107
+ ## Лицензия
108
+
109
+ Proprietary — © SEOMI. См. `LICENSE`.
110
+
111
+ ## Связанные проекты
112
+
113
+ - [@seomi/wp-mcp](https://github.com/Mikeekb/seomi-wp-mcp) — родственный WordPress/MCP-пакет, от которого произошёл этот.
114
+ - [ai-factory](https://github.com/lee-to/ai-factory) — спутник для AI-контекста разработки.
115
+
116
+ ---
117
+
118
+ Разработка и сопровождение — [Разработка сайтов SEOmi.ru](https://seomi.ru/).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@seomi/ssh",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "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.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -12,6 +12,7 @@
12
12
  "skills",
13
13
  "templates",
14
14
  "README.md",
15
+ "README.ru.md",
15
16
  "LICENSE"
16
17
  ],
17
18
  "engines": {