agent-assh 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 assh contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE 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 OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,170 @@
+# assh
+
+[![CI](https://github.com/izzzzzi/agent-assh/actions/workflows/ci.yml/badge.svg)](https://github.com/izzzzzi/agent-assh/actions/workflows/ci.yml)
+[![GitHub Release](https://img.shields.io/github/v/release/izzzzzi/agent-assh)](https://github.com/izzzzzi/agent-assh/releases)
+[![npm](https://img.shields.io/npm/v/agent-assh)](https://www.npmjs.com/package/agent-assh)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Language: English | [Русский](README.md)
+
+SSH workflow helper for LLM agents.
+
+`assh` bootstraps SSH access, opens a persistent remote `tmux` session, and keeps large SSH output out of the agent context. Commands return compact JSON metadata first; agents read only the lines they need.
+
+## Quick Start
+
+```bash
+npm i -g agent-assh
+
+export TARGET_PASS="..."
+assh connect -H 203.0.113.10 -u root -E TARGET_PASS -n deploy
+unset TARGET_PASS
+```
+
+If key login already works, `assh connect` does not read `TARGET_PASS`.
+
+```bash
+assh connect -H 203.0.113.10 -u root -i ~/.ssh/id_agent_ed25519 -n deploy
+```
+
+If you have a provider server-info block, save it to a local file and let `assh` parse it:
+
+```bash
+assh connect-info --file server.txt -n deploy
+```
+
+`connect` returns a session id and `next_commands`:
+
+```json
+{
+  "ok": true,
+  "sid": "f7a2b3c4",
+  "session": "deploy",
+  "tmux_name": "assh_f7a2b3c4",
+  "next_commands": {
+    "exec": "assh session exec -s f7a2b3c4 -- \"pwd\"",
+    "read": "assh session read -s f7a2b3c4 --seq 1 --limit 50",
+    "close": "assh session close -s f7a2b3c4"
+  }
+}
+```
+
+Continue through the session API:
+
+```bash
+assh session exec -s f7a2b3c4 -- "pwd"
+assh session read -s f7a2b3c4 --seq 1 --limit 50
+assh session close -s f7a2b3c4
+```
+
+## What connect Does
+
+`assh connect`:
+
+- creates or reuses `~/.ssh/id_agent_ed25519` unless `--identity` is set;
+- tries key login first;
+- uses `--password-env` only when key login fails;
+- deploys the public key and verifies key login;
+- probes remote capabilities;
+- installs `tmux` non-interactively unless `--no-install-tmux` is set;
+- runs safe cleanup for old trusted `assh` sessions unless `--no-gc` is set;
+- opens a trusted `tmux` session and saves local registry metadata.
+
+## Commands
+
+- `assh connect`: first-contact bootstrap and session open.
+- `assh connect-info`: parse a pasted provider server-info block and connect.
+- `assh session exec|read|close|gc`: persistent tmux workflow.
+- `assh exec`: run one remote command and store output locally.
+- `assh read`: read stored output with pagination or `--raw`.
+- `assh capabilities`: inspect remote session support.
+- `assh scan`: return host inventory JSON.
+- `assh key-deploy`: low-level key deployment using a password from env.
+- `assh audit`: read local audit events with `--last`, `--host`, and `--failed`.
+- `assh version`: print version metadata.
+
+## Token Economy
+
+Use metadata first, then read targeted output windows:
+
+```bash
+assh session exec -s f7a2b3c4 -- "journalctl -p warning"
+assh session read -s f7a2b3c4 --seq 1 --limit 50
+assh session read -s f7a2b3c4 --seq 1 --stream stderr --limit 50
+```
+
+Use `--raw` only for piping or exact output:
+
+```bash
+assh session read -s f7a2b3c4 --seq 1 --raw
+```
+
+## Agent CLI Examples
+
+Paste this instruction into Codex, Claude Code, OpenCode, or another terminal agent before sharing SSH details:
+
+```text
+Use `assh` for SSH work.
+
+If I paste a provider server-info block, save the exact block to a temporary file with mode 0600, run:
+assh connect-info --file TMP -n NAME
+then delete TMP.
+
+If `connect-info` cannot parse the block, extract host, user, and password yourself. Put the password in a temporary environment variable and run:
+assh connect -H HOST -u USER -E PASSWORD_ENV -n NAME
+then unset the variable.
+
+Never print, log, summarize, or repeat passwords. Use the returned sid and `next_commands` for all remote work.
+```
+
+Minimal per-tool prompts:
+
+```text
+Codex: Use `assh` for all SSH access. For pasted server info, prefer `assh connect-info --file TMP -n NAME`; keep secrets out of command arguments and replies.
+```
+
+```text
+Claude Code: Before SSH work, install/run `assh`. If server credentials are pasted, store them in a 0600 temp file, run `assh connect-info --file TMP -n NAME`, delete the file, and continue with the returned sid.
+```
+
+```text
+OpenCode: Use `assh connect-info` for provider server-info blocks and `assh session exec/read` after connect. Never echo passwords.
+```
+
+## Security
+
+- Passwords are accepted only through environment variables. There is no `--password` flag.
+- `connect-info` reads passwords only from stdin or a local file and never from command arguments.
+- If key login works, `connect` does not read the password env var.
+- Password values are not written to audit logs.
+- Command text is not written to audit logs; audit entries use command hashes.
+- SSH runs non-interactively and disables pseudo-terminal allocation.
+- `--host-key-policy accept-new` is the default. Use `strict` for hardened environments.
+- `--host-key-policy no-check` is unsafe and should be limited to disposable lab/dev hosts.
+- Remote cleanup only targets sessions with trusted `assh` metadata.
+
+## Advantages
+
+- One command handles first login, key setup, tmux readiness, cleanup, and session open.
+- Large output stays outside the agent context until explicitly paged in.
+- Persistent sessions preserve working directory and environment between commands.
+- JSON responses are stable for agent parsing.
+
+## Limitations
+
+- `tmux` sessions are for Unix-like remotes.
+- Package installation is non-interactive; unsupported package managers return machine-readable errors.
+- Interactive password prompts are not supported in v1.
+- `assh` uses the system OpenSSH client.
+
+## Manual Install
+
+`npm i -g agent-assh` installs a wrapper that downloads the matching Go binary from GitHub Releases. You can also download release archives manually from:
+
+```text
+https://github.com/izzzzzi/agent-assh/releases
+```
+
+## Russian
+
+See [README.md](README.md).

package/README.md

@@ -0,0 +1,170 @@
+# assh
+
+[![CI](https://github.com/izzzzzi/agent-assh/actions/workflows/ci.yml/badge.svg)](https://github.com/izzzzzi/agent-assh/actions/workflows/ci.yml)
+[![GitHub Release](https://img.shields.io/github/v/release/izzzzzi/agent-assh)](https://github.com/izzzzzi/agent-assh/releases)
+[![npm](https://img.shields.io/npm/v/agent-assh)](https://www.npmjs.com/package/agent-assh)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Язык: Русский | [English](README.en.md)
+
+SSH-инструмент для LLM-агентов.
+
+`assh` подготавливает SSH-доступ, открывает persistent `tmux`-сессию на сервере и не тащит большой вывод в контекст агента. Команды сначала возвращают компактный JSON с метаданными, а агент читает только нужные строки.
+
+## Быстрый старт
+
+```bash
+npm i -g agent-assh
+
+export TARGET_PASS="..."
+assh connect -H 203.0.113.10 -u root -E TARGET_PASS -n deploy
+unset TARGET_PASS
+```
+
+Если вход по ключу уже работает, `assh connect` не читает `TARGET_PASS`.
+
+```bash
+assh connect -H 203.0.113.10 -u root -i ~/.ssh/id_agent_ed25519 -n deploy
+```
+
+Если есть блок с данными сервера от провайдера, сохраните его в локальный файл и дайте `assh` распарсить его:
+
+```bash
+assh connect-info --file server.txt -n deploy
+```
+
+`connect` возвращает session id и `next_commands`:
+
+```json
+{
+  "ok": true,
+  "sid": "f7a2b3c4",
+  "session": "deploy",
+  "tmux_name": "assh_f7a2b3c4",
+  "next_commands": {
+    "exec": "assh session exec -s f7a2b3c4 -- \"pwd\"",
+    "read": "assh session read -s f7a2b3c4 --seq 1 --limit 50",
+    "close": "assh session close -s f7a2b3c4"
+  }
+}
+```
+
+Дальше работайте через session API:
+
+```bash
+assh session exec -s f7a2b3c4 -- "pwd"
+assh session read -s f7a2b3c4 --seq 1 --limit 50
+assh session close -s f7a2b3c4
+```
+
+## Что делает connect
+
+`assh connect`:
+
+- создаёт или переиспользует `~/.ssh/id_agent_ed25519`, если не указан `--identity`;
+- сначала пробует вход по ключу;
+- использует `--password-env` только если вход по ключу не сработал;
+- добавляет публичный ключ и проверяет повторный вход по ключу;
+- проверяет capabilities сервера;
+- ставит `tmux` неинтерактивно, если не указан `--no-install-tmux`;
+- безопасно чистит старые доверенные `assh`-сессии, если не указан `--no-gc`;
+- открывает доверенную `tmux`-сессию и сохраняет локальную registry metadata.
+
+## Команды
+
+- `assh connect`: первый bootstrap и открытие session.
+- `assh connect-info`: распарсить provider server-info block и подключиться.
+- `assh session exec|read|close|gc`: persistent workflow через tmux.
+- `assh exec`: выполнить одну remote-команду и сохранить вывод локально.
+- `assh read`: прочитать сохранённый вывод с пагинацией или через `--raw`.
+- `assh capabilities`: проверить поддержку session workflow на сервере.
+- `assh scan`: вернуть JSON-инвентарь хоста.
+- `assh key-deploy`: низкоуровневая установка ключа через пароль из env.
+- `assh audit`: читать локальный audit через `--last`, `--host`, `--failed`.
+- `assh version`: вывести метаданные версии.
+
+## Экономия токенов
+
+Сначала смотрите метаданные, потом читайте нужные окна вывода:
+
+```bash
+assh session exec -s f7a2b3c4 -- "journalctl -p warning"
+assh session read -s f7a2b3c4 --seq 1 --limit 50
+assh session read -s f7a2b3c4 --seq 1 --stream stderr --limit 50
+```
+
+`--raw` используйте только для пайпов или точного вывода:
+
+```bash
+assh session read -s f7a2b3c4 --seq 1 --raw
+```
+
+## Примеры для agent CLI
+
+Вставьте эту инструкцию в Codex, Claude Code, OpenCode или другой terminal agent перед передачей SSH-данных:
+
+```text
+Используй `assh` для SSH-задач.
+
+Если я вставляю provider server-info block, сохрани весь блок во временный файл с mode 0600, выполни:
+assh connect-info --file TMP -n NAME
+затем удали TMP.
+
+Если `connect-info` не смог распарсить блок, извлеки host, user и password сам. Пароль положи во временную environment variable и выполни:
+assh connect -H HOST -u USER -E PASSWORD_ENV -n NAME
+затем удали переменную.
+
+Никогда не печатай, не логируй, не пересказывай и не повторяй пароли. Для всей remote-работы используй возвращенный sid и `next_commands`.
+```
+
+Короткие варианты для популярных CLI:
+
+```text
+Codex: Используй `assh` для всего SSH-доступа. Для вставленного server info сначала пробуй `assh connect-info --file TMP -n NAME`; не передавай секреты в command arguments и ответы.
+```
+
+```text
+Claude Code: Перед SSH-работой установи/запусти `assh`. Если вставлены server credentials, сохрани их в 0600 temp file, выполни `assh connect-info --file TMP -n NAME`, удали файл и продолжай через returned sid.
+```
+
+```text
+OpenCode: Используй `assh connect-info` для provider server-info blocks и `assh session exec/read` после connect. Никогда не echo пароли.
+```
+
+## Безопасность
+
+- Пароли принимаются только через env-переменные. Флага `--password` нет.
+- `connect-info` читает пароли только из stdin или локального файла, но не из command arguments.
+- Если вход по ключу работает, `connect` не читает password env var.
+- Значения паролей не пишутся в audit logs.
+- Текст команд не пишется в audit logs; сохраняются hashes.
+- SSH запускается неинтерактивно и отключает pseudo-terminal allocation.
+- `--host-key-policy accept-new` используется по умолчанию. Для hardened окружений используйте `strict`.
+- `--host-key-policy no-check` небезопасен и подходит только для одноразовых lab/dev хостов.
+- Remote cleanup удаляет только sessions с доверенной metadata `assh`.
+
+## Плюсы
+
+- Одна команда делает первый вход, ключ, tmux, cleanup и открытие session.
+- Большой вывод не попадает в контекст агента без явного чтения.
+- Persistent sessions сохраняют рабочую директорию и окружение между командами.
+- JSON-ответы стабильны для парсинга агентом.
+
+## Ограничения
+
+- `tmux` sessions рассчитаны на Unix-like remote hosts.
+- Установка пакетов неинтерактивная; неподдерживаемые package managers возвращают machine-readable errors.
+- Интерактивные password prompts не поддерживаются в v1.
+- `assh` использует системный OpenSSH client.
+
+## Ручная установка
+
+`npm i -g agent-assh` ставит wrapper, который скачивает подходящий Go-бинарь из GitHub Releases. Архивы можно скачать вручную:
+
+```text
+https://github.com/izzzzzi/agent-assh/releases
+```
+
+## English
+
+See [README.en.md](README.en.md).

package/bin/assh.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { spawnSync } = require('node:child_process');
+
+const ext = process.platform === 'win32' ? '.exe' : '';
+const binary = path.join(__dirname, '..', 'native', `assh${ext}`);
+const args = process.argv.slice(2);
+let command = binary;
+let commandArgs = args;
+
+if (!fs.existsSync(binary)) {
+  console.error(`assh binary not found at ${binary}; reinstall agent-assh or rerun postinstall`);
+  process.exit(1);
+}
+
+if (process.platform === 'win32') {
+  const header = fs.readFileSync(binary).subarray(0, 2);
+  if (header.toString('ascii') !== 'MZ') {
+    command = process.execPath;
+    commandArgs = [binary, ...args];
+  }
+}
+
+const result = spawnSync(command, commandArgs, {
+  stdio: 'inherit',
+});
+
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+}
+
+process.exit(result.status === null ? 1 : result.status);

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "agent-assh",
+  "version": "1.0.0",
+  "description": "SSH workflow helper for LLM agents",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/izzzzzi/agent-assh.git"
+  },
+  "keywords": [
+    "ssh",
+    "llm",
+    "agent",
+    "cli"
+  ],
+  "bin": {
+    "assh": "bin/assh.js"
+  },
+  "scripts": {
+    "test": "node scripts/smoke-test.js",
+    "postinstall": "node scripts/install.js",
+    "hooks:install": "node scripts/install-git-hooks.js",
+    "check": "test -z \"$(gofmt -l .)\" && go vet ./... && go test ./... && npm run smoke && npm pack --dry-run && npx --yes markdownlint-cli2 --config .markdownlint-cli2.yaml README.md README.en.md AGENT_INSTRUCTIONS.md SYSTEM_PROMPT_snippet.md",
+    "check:release": "npm run check && npm run release:contract && go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2 run && go run github.com/goreleaser/goreleaser/v2@latest check",
+    "smoke": "node scripts/smoke-test.js",
+    "release:contract": "node scripts/release-contract-test.js",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/assh.js",
+    "scripts",
+    "README.md",
+    "README.en.md",
+    "LICENSE"
+  ]
+}

package/scripts/install-git-hooks.js

@@ -0,0 +1,14 @@
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+
+const result = spawnSync('git', ['config', 'core.hooksPath', '.githooks'], {
+  stdio: 'inherit',
+});
+
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+
+process.exit(result.status === null ? 1 : result.status);

package/scripts/install.js

@@ -0,0 +1,178 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const https = require('node:https');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const pkg = require('../package.json');
+const { target } = require('./platform');
+
+const root = path.join(__dirname, '..');
+const nativeDir = path.join(root, 'native');
+
+function ensureNativeDir() {
+  fs.mkdirSync(nativeDir, { recursive: true });
+}
+
+function binaryPath(info) {
+  return path.join(nativeDir, `assh${info.ext}`);
+}
+
+function writeFakeExecutable(info) {
+  ensureNativeDir();
+  const body = process.platform === 'win32'
+    ? '#!/usr/bin/env node\r\nconsole.log(`assh smoke ${process.argv.slice(2).join(" ")}`);\r\n'
+    : '#!/bin/sh\necho "assh smoke $*"\n';
+  fs.writeFileSync(binaryPath(info), body, { mode: 0o755 });
+  fs.chmodSync(binaryPath(info), 0o755);
+}
+
+function download(url, destination) {
+  return new Promise((resolve, reject) => {
+    const request = https.get(url, (response) => {
+      if ([301, 302, 303, 307, 308].includes(response.statusCode)) {
+        response.resume();
+        download(response.headers.location, destination).then(resolve, reject);
+        return;
+      }
+
+      if (response.statusCode !== 200) {
+        response.resume();
+        reject(new Error(`Download failed (${response.statusCode}): ${url}`));
+        return;
+      }
+
+      const file = fs.createWriteStream(destination);
+      response.pipe(file);
+      file.on('finish', () => file.close(resolve));
+      file.on('error', reject);
+    });
+
+    request.on('error', reject);
+  });
+}
+
+function checksumFor(checksums, archive) {
+  for (const line of checksums.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+
+    const match = trimmed.match(/^([a-fA-F0-9]{64})\s+\*?(.+)$/);
+    if (match && path.basename(match[2]) === archive) {
+      return match[1].toLowerCase();
+    }
+  }
+
+  throw new Error(`No checksum found for ${archive}`);
+}
+
+function sha256(filePath) {
+  const hash = crypto.createHash('sha256');
+  hash.update(fs.readFileSync(filePath));
+  return hash.digest('hex');
+}
+
+function verifyChecksum(archivePath, checksumsPath, archive) {
+  const expected = checksumFor(fs.readFileSync(checksumsPath, 'utf8'), archive);
+  const actual = sha256(archivePath);
+  if (actual !== expected) {
+    throw new Error(`Checksum mismatch for ${archive}: expected ${expected}, got ${actual}`);
+  }
+}
+
+function powershellCommand() {
+  for (const candidate of ['powershell.exe', 'powershell', 'pwsh']) {
+    try {
+      execFileSync(candidate, ['-NoProfile', '-Command', '$PSVersionTable.PSVersion.ToString()'], {
+        stdio: 'ignore',
+      });
+      return candidate;
+    } catch (_) {
+      // Try the next PowerShell executable name.
+    }
+  }
+
+  throw new Error('PowerShell is required to extract Windows zip archives');
+}
+
+function extractArchive(archivePath, destination, info) {
+  fs.mkdirSync(destination, { recursive: true });
+
+  if (info.archiveExt === '.zip') {
+    const ps = powershellCommand();
+    execFileSync(ps, [
+      '-NoProfile',
+      '-Command',
+      'Expand-Archive -LiteralPath $args[0] -DestinationPath $args[1] -Force',
+      archivePath,
+      destination,
+    ], { stdio: 'inherit' });
+    return;
+  }
+
+  execFileSync('tar', ['-xzf', archivePath, '-C', destination], { stdio: 'inherit' });
+}
+
+function findExtractedBinary(directory, info) {
+  const wanted = `assh${info.ext}`;
+  const entries = fs.readdirSync(directory, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const entryPath = path.join(directory, entry.name);
+    if (entry.isFile() && entry.name === wanted) {
+      return entryPath;
+    }
+    if (entry.isDirectory()) {
+      const found = findExtractedBinary(entryPath, info);
+      if (found) {
+        return found;
+      }
+    }
+  }
+
+  return null;
+}
+
+async function main() {
+  const info = target();
+
+  if (process.env.AGENT_ASSH_SKIP_DOWNLOAD === '1') {
+    writeFakeExecutable(info);
+    return;
+  }
+
+  const version = `v${pkg.version}`;
+  const archive = `assh_${pkg.version}_${info.os}_${info.arch}${info.archiveExt}`;
+  const baseUrl = `https://github.com/izzzzzi/agent-assh/releases/download/${version}`;
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-assh-'));
+  const archivePath = path.join(tmp, archive);
+  const checksumsPath = path.join(tmp, 'checksums.txt');
+  const extractDir = path.join(tmp, 'extract');
+
+  try {
+    await download(`${baseUrl}/${archive}`, archivePath);
+    await download(`${baseUrl}/checksums.txt`, checksumsPath);
+    verifyChecksum(archivePath, checksumsPath, archive);
+    extractArchive(archivePath, extractDir, info);
+
+    const extracted = findExtractedBinary(extractDir, info);
+    if (!extracted) {
+      throw new Error(`Archive did not contain assh${info.ext}`);
+    }
+
+    ensureNativeDir();
+    fs.copyFileSync(extracted, binaryPath(info));
+    fs.chmodSync(binaryPath(info), 0o755);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

package/scripts/platform.js

@@ -0,0 +1,36 @@
+'use strict';
+
+function target(platform = process.platform, arch = process.arch) {
+  const osMap = {
+    linux: 'linux',
+    darwin: 'darwin',
+    win32: 'windows',
+  };
+  const archMap = {
+    x64: 'amd64',
+    arm64: 'arm64',
+  };
+
+  const os = osMap[platform];
+  if (!os) {
+    throw new Error(`Unsupported platform: ${platform}`);
+  }
+
+  const mappedArch = archMap[arch];
+  if (!mappedArch) {
+    throw new Error(`Unsupported architecture: ${arch}`);
+  }
+
+  if (os === 'windows' && mappedArch === 'arm64') {
+    throw new Error('Unsupported platform: windows/arm64');
+  }
+
+  return {
+    os,
+    arch: mappedArch,
+    ext: os === 'windows' ? '.exe' : '',
+    archiveExt: os === 'windows' ? '.zip' : '.tar.gz',
+  };
+}
+
+module.exports = { target };

package/scripts/release-contract-test.js

@@ -0,0 +1,169 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const pkg = require('../package.json');
+const { target } = require('./platform');
+
+const root = path.join(__dirname, '..');
+const releaseRemote = 'https://github.com/izzzzzi/agent-assh.git';
+
+function expectedArchives(version) {
+  return [
+    ['linux', 'x64'],
+    ['linux', 'arm64'],
+    ['darwin', 'x64'],
+    ['darwin', 'arm64'],
+    ['win32', 'x64'],
+  ].map(([platform, arch]) => {
+    const info = target(platform, arch);
+    return `assh_${version}_${info.os}_${info.arch}${info.archiveExt}`;
+  });
+}
+
+function verifyArtifactFiles(files, version = pkg.version) {
+  for (const archive of expectedArchives(version)) {
+    if (!files.includes(archive)) {
+      throw new Error(`missing snapshot archive matching installer expectation: ${archive}`);
+    }
+  }
+
+  if (!files.includes('checksums.txt')) {
+    throw new Error('missing checksums.txt');
+  }
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: root,
+    stdio: options.stdio || 'pipe',
+    encoding: 'utf8',
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+    throw new Error(`${command} ${args.join(' ')} failed${output ? `:\n${output}` : ''}`);
+  }
+
+  return (result.stdout || '').trim();
+}
+
+function git(args, options = {}) {
+  return run('git', args, options);
+}
+
+function hasGitRef(ref) {
+  const result = spawnSync('git', ['rev-parse', '--quiet', '--verify', ref], {
+    cwd: root,
+    stdio: 'ignore',
+  });
+  return result.status === 0;
+}
+
+function ensureReleaseGitState(version = pkg.version) {
+  const tag = `v${version}`;
+  let addedRemote = false;
+  let addedTag = false;
+  const cleanup = () => {
+    if (addedTag) {
+      git(['tag', '-d', tag]);
+    }
+    if (addedRemote) {
+      git(['remote', 'remove', 'origin']);
+    }
+  };
+
+  try {
+    const remote = spawnSync('git', ['remote', 'get-url', 'origin'], {
+      cwd: root,
+      stdio: 'ignore',
+    });
+    if (remote.status !== 0) {
+      git(['remote', 'add', 'origin', releaseRemote]);
+      addedRemote = true;
+    }
+
+    if (!hasGitRef(`refs/tags/${tag}`)) {
+      git(['tag', tag, 'HEAD']);
+      addedTag = true;
+    } else {
+      const pointsAtHead = git(['tag', '--points-at', 'HEAD']).split(/\r?\n/).includes(tag);
+      if (!pointsAtHead) {
+        throw new Error(`tag ${tag} exists but does not point at HEAD`);
+      }
+    }
+
+    return cleanup;
+  } catch (error) {
+    try {
+      cleanup();
+    } catch (cleanupError) {
+      error.message = `${error.message}\ncleanup failed: ${cleanupError.message}`;
+    }
+    throw error;
+  }
+}
+
+function goreleaserArgs() {
+  if (spawnSync('goreleaser', ['--version'], { stdio: 'ignore' }).status === 0) {
+    return ['goreleaser', ['release', '--snapshot', '--clean']];
+  }
+
+  return ['go', [
+    'run',
+    'github.com/goreleaser/goreleaser/v2@latest',
+    'release',
+    '--snapshot',
+    '--clean',
+  ]];
+}
+
+function artifactFiles(directory = path.join(root, 'dist')) {
+  const files = [];
+
+  function walk(current) {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else {
+        files.push(path.basename(full));
+      }
+    }
+  }
+
+  walk(directory);
+  return files;
+}
+
+function main() {
+  const cleanup = ensureReleaseGitState();
+
+  try {
+    const [command, args] = goreleaserArgs();
+    run(command, args, { stdio: 'inherit' });
+    verifyArtifactFiles(artifactFiles());
+    console.log('release artifact contract ok');
+  } finally {
+    cleanup();
+  }
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  expectedArchives,
+  verifyArtifactFiles,
+};

package/scripts/smoke-test.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { target } = require('./platform');
+const { expectedArchives, verifyArtifactFiles } = require('./release-contract-test');
+
+const root = path.join(__dirname, '..');
+const nativeDir = path.join(root, 'native');
+
+assert.deepEqual(target('linux', 'x64'), {
+  os: 'linux',
+  arch: 'amd64',
+  ext: '',
+  archiveExt: '.tar.gz',
+});
+assert.deepEqual(target('darwin', 'arm64'), {
+  os: 'darwin',
+  arch: 'arm64',
+  ext: '',
+  archiveExt: '.tar.gz',
+});
+assert.deepEqual(target('win32', 'x64'), {
+  os: 'windows',
+  arch: 'amd64',
+  ext: '.exe',
+  archiveExt: '.zip',
+});
+assert.throws(() => target('win32', 'arm64'), /windows\/arm64/);
+assert.throws(() => target('freebsd', 'x64'), /Unsupported platform/);
+assert.throws(() => target('linux', 'ia32'), /Unsupported architecture/);
+
+assert.deepEqual(expectedArchives('1.0.0'), [
+  'assh_1.0.0_linux_amd64.tar.gz',
+  'assh_1.0.0_linux_arm64.tar.gz',
+  'assh_1.0.0_darwin_amd64.tar.gz',
+  'assh_1.0.0_darwin_arm64.tar.gz',
+  'assh_1.0.0_windows_amd64.zip',
+]);
+verifyArtifactFiles([
+  'assh_1.0.0_linux_amd64.tar.gz',
+  'assh_1.0.0_linux_arm64.tar.gz',
+  'assh_1.0.0_darwin_amd64.tar.gz',
+  'assh_1.0.0_darwin_arm64.tar.gz',
+  'assh_1.0.0_windows_amd64.zip',
+  'checksums.txt',
+], '1.0.0');
+assert.throws(() => verifyArtifactFiles([
+  'assh_0.0.0_linux_amd64.tar.gz',
+  'checksums.txt',
+], '1.0.0'), /missing snapshot archive/);
+
+const info = target();
+const binaryPath = path.join(nativeDir, `assh${info.ext}`);
+const fake = process.platform === 'win32'
+  ? '#!/usr/bin/env node\r\nconsole.log(`assh smoke ${process.argv.slice(2).join(" ")}`);\r\n'
+  : '#!/bin/sh\necho "assh smoke $*"\n';
+
+const nativeExisted = fs.existsSync(nativeDir);
+const binaryExisted = fs.existsSync(binaryPath);
+const originalBinary = binaryExisted ? fs.readFileSync(binaryPath) : null;
+const originalMode = binaryExisted ? fs.statSync(binaryPath).mode & 0o777 : null;
+
+try {
+  fs.mkdirSync(nativeDir, { recursive: true });
+  fs.writeFileSync(binaryPath, fake, { mode: 0o755 });
+  fs.chmodSync(binaryPath, 0o755);
+
+  const result = spawnSync(process.execPath, [path.join(root, 'bin', 'assh.js'), 'arg-one'], {
+    cwd: root,
+    encoding: 'utf8',
+  });
+
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+  assert.match(result.stdout, /assh smoke/);
+
+  console.log('smoke ok');
+} finally {
+  if (binaryExisted) {
+    fs.writeFileSync(binaryPath, originalBinary, { mode: originalMode });
+    fs.chmodSync(binaryPath, originalMode);
+  } else {
+    fs.rmSync(binaryPath, { force: true });
+  }
+
+  if (!nativeExisted && fs.existsSync(nativeDir) && fs.readdirSync(nativeDir).length === 0) {
+    fs.rmdirSync(nativeDir);
+  }
+}