@patimweb/pi-ssh 1.0.0

package/.node-version

@@ -0,0 +1 @@
+26.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Weppelmann
+
+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.md

@@ -0,0 +1,146 @@
+# pi-ssh
+
+SSH client extension for the [pi coding agent](https://github.com/earendil-works/pi).
+
+Run commands on remote hosts, move files over SFTP, and turn a password login into a key login — all from a pi session.
+
+**Nothing has to be installed.** No `ssh`, no `ssh-keygen`, no `ssh-copy-id`. The SSH protocol comes from [ssh2](https://github.com/mscdex/ssh2), a pure JavaScript implementation, and keys are generated with Node's own crypto. Windows, macOS and Linux behave identically.
+
+## Installation
+
+```bash
+# Install from npm
+pi install npm:@patimweb/pi-ssh
+
+# Install from local path during development
+pi install /path/to/pi-ssh
+```
+
+## Quick Start
+
+```
+ssh_setup:
+  name: staging
+  host: staging.example.com
+  user: deploy
+  password: <password>
+
+ssh_authorize          # generates a key, installs it, verifies passwordless login
+
+ssh_exec:
+  command: systemctl status nginx --no-pager
+```
+
+After `ssh_authorize` the password is no longer needed. It stays in the profile as a fallback until you pass `removePassword: true`.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `ssh_setup` | Store a host: address, user, and a password or key path. |
+| `ssh_status` | List configured hosts and how each authenticates; optionally test a connection. |
+| `ssh_profile` | List, switch, or delete hosts. |
+| `ssh_exec` | Run a command and return its output and exit code. |
+| `ssh_list` | List a remote directory with sizes, permissions and dates over SFTP. |
+| `ssh_upload` | Copy a file to the remote host. |
+| `ssh_download` | Copy a file from the remote host. |
+| `ssh_keygen` | Create an ed25519 key pair in process. |
+| `ssh_authorize` | Install a key on a host and stop needing the password. |
+| `ssh_doctor` | Report what this machine can do and what needs fixing. |
+
+### Passwordless login
+
+`ssh_authorize` is `ssh-copy-id` without the binary:
+
+```yaml
+ssh_authorize:
+  # profile: staging          # defaults to the active one
+  # keyPath: ~/.ssh/id_ed25519_pi_staging
+  # removePassword: true      # only after verification succeeds
+  # authorizedKeysPath: /custom/authorized_keys
+```
+
+It generates a key if the profile has none, appends the public key to the remote `~/.ssh/authorized_keys` with the permissions sshd requires, points the profile at the key, and then opens a **second connection using only the key** to prove it works before reporting success. Running it twice is safe: the key is appended only once.
+
+An existing key at the target path is reused, never overwritten — overwriting would invalidate every other host that already trusts it.
+
+### Running commands
+
+```yaml
+ssh_exec:
+  command: journalctl -u api --since "1 hour ago" --no-pager
+  # cwd: /srv/app
+  # timeoutSeconds: 120
+```
+
+Each call opens a connection, runs one command, and closes it. There is no persistent shell, so `cd` does not carry over — use `cwd` or chain with `&&`. There is also no TTY: anything interactive (a `sudo` password prompt, `top`, an editor) will hang until the timeout.
+
+Output is capped at 200,000 characters per stream and marked as truncated rather than silently cut.
+
+### Files
+
+```yaml
+ssh_list:     { path: /var/log }
+ssh_download: { remotePath: /var/log/app.log, localPath: ./logs/app.log }
+ssh_upload:   { localPath: ./dist/app.tar.gz, remotePath: /tmp/app.tar.gz }
+```
+
+Missing local directories are created on download. Prefer these over `cat` through `ssh_exec`: SFTP handles binary content and does not push the file through the model.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/ssh <command>` | Run a command on the active host. |
+| `/ssh-key` | Set up passwordless login for the active host. |
+
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `ssh-remote-work` | Choosing the right host, the absence of a shell and a TTY, reading before writing, and what each connection error actually means. |
+| `ssh-key-setup` | The password-to-key switch, why an existing key is never overwritten, and why the password stays until the key is proven. |
+
+## Host key verification
+
+Host keys are checked against `~/.ssh/known_hosts` — the same file OpenSSH uses, so hosts you have already visited with `ssh` are recognised, and hosts recorded here are recognised by `ssh`. Hashed entries (`ssh-keygen -H`) and `[host]:port` forms are both understood.
+
+- **Unknown host** → the connection is refused and the fingerprint shown. Confirm it, then re-run with `acceptNewHostKey: true` to record it.
+- **Changed key** → a hard failure with both fingerprints. This is what a machine-in-the-middle looks like; it is also what a reinstalled server looks like. It has to be resolved deliberately with `ssh-keygen -R <host>`.
+- **Revoked key** (`@revoked` in known_hosts) → always refused.
+
+`strictHostKey: false` in a profile turns the check off. It removes the only protection SSH has against an attacker on the network path, so it exists for throwaway lab machines and nothing else.
+
+## Configuration
+
+Profiles live in `~/.pi/ssh-config.json`, written atomically with mode `0600` because it can hold passwords and key passphrases.
+
+```json
+{
+  "profiles": {
+    "staging": {
+      "host": "staging.example.com",
+      "port": 22,
+      "user": "deploy",
+      "privateKeyPath": "/home/pat/.ssh/id_ed25519_pi_staging"
+    }
+  },
+  "activeProfile": "staging"
+}
+```
+
+Every tool also takes a one-off `profile` parameter, so several hosts can be used in one session without switching.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run test:coverage
+```
+
+The suite runs end-to-end against a real OpenSSH server: it starts `sshd` on a loopback port with a host key generated by this package, then exercises the handshake, host key verification (including a simulated key change), exit codes, SFTP, and the full key bootstrap. Those tests skip themselves on machines without `sshd` rather than failing.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,99 @@
+/**
+ * pi SSH Extension
+ *
+ * Runs commands and moves files on remote hosts over SSH, and can turn a
+ * password login into a key login without any external tooling.
+ *
+ * Tools:
+ *   - ssh_setup: Store a host, user and credentials
+ *   - ssh_status: List configured hosts, optionally testing a connection
+ *   - ssh_profile: List, switch or delete hosts
+ *   - ssh_exec: Run a command and return its output and exit code
+ *   - ssh_list: List a remote directory over SFTP
+ *   - ssh_upload: Copy a file to the remote host
+ *   - ssh_download: Copy a file from the remote host
+ *   - ssh_keygen: Create an ed25519 key pair in process
+ *   - ssh_authorize: Install a key on a host and stop needing the password
+ *   - ssh_doctor: Report what the environment can do and what needs fixing
+ *
+ * Nothing here shells out: ssh2 is a pure JavaScript SSH implementation and
+ * keys are generated with Node's own crypto, so Windows, macOS and Linux all
+ * work without ssh, ssh-keygen or ssh-copy-id being installed.
+ *
+ * Data-oriented design:
+ *   - All domain data is represented as plain immutable interfaces (types.ts)
+ *   - I/O is isolated in the client module (clients/)
+ *   - Pure helpers have no sockets in them (keys.ts, known-hosts.ts, formatting/)
+ *   - Each tool is a single-responsibility module (tools/)
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { loadConfig, getConfig } from "./src/config.ts";
+import { SshSetupTool } from "./src/tools/ssh-setup.ts";
+import { SshStatusTool } from "./src/tools/ssh-status.ts";
+import { SshProfileTool } from "./src/tools/ssh-profile.ts";
+import { SshExecTool } from "./src/tools/ssh-exec.ts";
+import { SshListTool } from "./src/tools/ssh-list.ts";
+import { SshUploadTool } from "./src/tools/ssh-upload.ts";
+import { SshDownloadTool } from "./src/tools/ssh-download.ts";
+import { SshKeygenTool } from "./src/tools/ssh-keygen.ts";
+import { SshAuthorizeTool } from "./src/tools/ssh-authorize.ts";
+import { SshDoctorTool } from "./src/tools/ssh-doctor.ts";
+
+export default function (pi: ExtensionAPI) {
+  // Load saved hosts on startup
+  loadConfig();
+
+  // Register all tools
+  pi.registerTool(SshSetupTool);
+  pi.registerTool(SshStatusTool);
+  pi.registerTool(SshProfileTool);
+  pi.registerTool(SshExecTool);
+  pi.registerTool(SshListTool);
+  pi.registerTool(SshUploadTool);
+  pi.registerTool(SshDownloadTool);
+  pi.registerTool(SshKeygenTool);
+  pi.registerTool(SshAuthorizeTool);
+  pi.registerTool(SshDoctorTool);
+
+  // Run something on the active host without spelling out the tool call
+  pi.registerCommand("ssh", {
+    description: "Run a command on the active SSH host",
+    handler: async (args, ctx) => {
+      if (!getConfig()) {
+        ctx.ui.notify("No SSH host configured. Use the ssh_setup tool first.", "error");
+        return;
+      }
+
+      const command = args.trim();
+      if (!command) {
+        ctx.ui.notify("Usage: /ssh <command to run on the remote host>", "info");
+        return;
+      }
+
+      pi.sendUserMessage(
+        `Run this on the active SSH host with ssh_exec and show me the output: ${command}`,
+        { deliverAs: "steer" },
+      );
+      ctx.ui.notify("Running on the remote host...", "info");
+    },
+  });
+
+  // The one-time setup people forget until they are typing a password again
+  pi.registerCommand("ssh-key", {
+    description: "Set up passwordless login for the active SSH host",
+    handler: async (_args, ctx) => {
+      if (!getConfig()) {
+        ctx.ui.notify("No SSH host configured. Use the ssh_setup tool first.", "error");
+        return;
+      }
+
+      pi.sendUserMessage(
+        "Use ssh_authorize on the active SSH profile to generate a key, install it on the host and verify that a key-only login works. Tell me the fingerprint and whether the verification succeeded.",
+        { deliverAs: "steer" },
+      );
+      ctx.ui.notify("Setting up key-based login...", "info");
+    },
+  });
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@patimweb/pi-ssh",
+  "version": "1.0.0",
+  "description": "SSH client extension for the pi coding agent. Run commands, transfer files over SFTP, and set up key-based login on remote hosts.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "ssh",
+    "sftp",
+    "remote",
+    "ssh2"
+  ],
+  "author": "Patrick Weppelmann",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=26.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Smotherer007/pi-ssh.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Smotherer007/pi-ssh/issues"
+  },
+  "scripts": {
+    "build": "echo 'No build step defined'",
+    "test": "node --experimental-test-module-mocks --experimental-test-coverage --test 'tests/**/*.test.ts'",
+    "test:watch": "node --experimental-test-module-mocks --test --watch 'tests/**/*.test.ts'",
+    "test:coverage": "node --experimental-test-module-mocks --experimental-test-coverage --test 'tests/**/*.test.ts'"
+  },
+  "dependencies": {
+    "ssh2": "^1.17.0",
+    "typebox": "^1.2.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@semantic-release/git": "^10.0.0",
+    "@types/ssh2": "^1.15.0",
+    "semantic-release": "^25.0.0"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/release.config.cjs

@@ -0,0 +1,16 @@
+module.exports = {
+    branches: ["main", { name: "next", prerelease: true }],
+    plugins: [
+        "@semantic-release/commit-analyzer",
+        "@semantic-release/release-notes-generator",
+        "@semantic-release/npm",
+        [
+            "@semantic-release/git",
+            {
+                assets: ["package.json", "package-lock.json"],
+                message: "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+            }
+        ],
+        "@semantic-release/github"
+    ]
+};

package/skills/ssh-key-setup/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: ssh-key-setup
+description: Set up SSH key authentication so a host stops asking for a password, and manage the keys involved. Use when the user configures a new server with a password, says they are tired of typing a password, asks about ssh-copy-id, ssh-keygen, "install my key", "passwordless login", "authorized_keys", or when a login fails because a key is missing or not accepted. Also covers what has to be installed for any of this to work, which on every platform is nothing.
+allowed-tools: ssh_setup, ssh_status, ssh_keygen, ssh_authorize, ssh_exec, ssh_doctor
+---
+
+# Key-based login
+
+A password in a config file is a password on disk, and typing one into every
+session is friction. A key fixes both. The whole switch is one tool call.
+
+## The normal path
+
+1. `ssh_setup` with host, user and the password.
+2. `ssh_authorize` on that profile.
+
+`ssh_authorize` does what `ssh-copy-id` does: it generates an ed25519 key if
+the profile has none, appends the public key to the remote
+`~/.ssh/authorized_keys` with the permissions sshd insists on, points the
+profile at the new key, and then **opens a second connection using only the
+key** to prove it works before claiming success.
+
+Report the fingerprint and whether verification succeeded. If it did not, say
+so plainly - the key is installed but something is rejecting it, and the
+password is still there as a fallback.
+
+## What has to be installed
+
+Nothing. Not `ssh`, not `ssh-keygen`, not `ssh-copy-id`. The SSH protocol is
+implemented in JavaScript and keys are generated with Node's own crypto, so
+Windows, macOS and Linux behave identically. If a user asks what to install,
+run `ssh_doctor` and show them the report rather than guessing.
+
+The keys produced are ordinary OpenSSH ed25519 keys, so `ssh -i` and any other
+SSH client can use the same file.
+
+## Things worth getting right
+
+- **Never overwrite an existing key.** Every host that already trusts it would
+  stop accepting it. `ssh_authorize` reuses a key at the given path; `ssh_keygen`
+  refuses to replace one unless explicitly told to.
+- **Keep the password until the key is proven.** `ssh_authorize` leaves it in
+  the profile by default. Only pass `removePassword: true` once verification
+  has succeeded, and prefer to ask the user first: if `authorized_keys` is ever
+  reset, that password is the way back in.
+- **One key per host is a reasonable default.** The default path is
+  `~/.ssh/id_ed25519_pi_<profile>`, which keeps a compromise contained to one
+  host. Pass `keyPath` to reuse an existing key across hosts if the user wants
+  that.
+- **A passphrase-protected key cannot be bootstrapped.** If the user points at
+  one, this flow cannot read it; either use a different key path or configure
+  the passphrase in the profile.
+
+## If the key is not accepted afterwards
+
+The usual causes, in order:
+
+1. Permissions. sshd silently ignores `~/.ssh` or `authorized_keys` if they are
+   group- or world-writable. `ssh_exec` with `ls -ld ~/.ssh ~/.ssh/authorized_keys`
+   shows it; 700 and 600 are what is wanted.
+2. The account's home is not where you think - a different `AuthorizedKeysFile`
+   in `sshd_config`, or a chrooted account. `ssh_authorize` takes an
+   `authorizedKeysPath` for that case.
+3. The server does not allow public key auth at all (`PubkeyAuthentication no`),
+   which needs a change on the server side.
+
+## Keys without a host
+
+`ssh_keygen` just makes a key pair and prints the public key, for cases where
+the user installs it themselves - a cloud provider's web console, a deploy key
+in a Git host, a colleague who will add it for them.

package/skills/ssh-remote-work/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: ssh-remote-work
+description: Work on a remote machine over SSH - run commands, inspect logs and configuration, and move files with SFTP. Use whenever the task is on another host: deploying or restarting a service, reading logs on a server, checking disk or process state, copying a build artefact to or from a machine, or anything the user describes as "on the server", "on the NAS", "on staging", or by a hostname. Also covers what to do when a connection fails and how to read a host key warning.
+allowed-tools: ssh_status, ssh_profile, ssh_exec, ssh_list, ssh_upload, ssh_download, ssh_doctor
+---
+
+# Working on a remote host
+
+Commands run through `ssh_exec` land on someone's actual machine. That is the
+whole value and also the whole risk: there is no undo, and the blast radius is
+whatever the account can reach.
+
+## Before the first command
+
+`ssh_status` shows which hosts are configured and which one is active. **When
+more than one exists, pass `profile` explicitly** rather than relying on
+whichever was active from an earlier session - "restart nginx" on the wrong
+host is not recoverable by apologising.
+
+If the user names a host you have no profile for, say so and ask for the
+details rather than guessing at a hostname.
+
+## Running commands
+
+`ssh_exec` opens a connection, runs one command, and closes it. There is no
+persistent shell, which has two consequences worth remembering:
+
+- **State does not carry over.** `cd /var/log` in one call does not affect the
+  next. Use the `cwd` parameter, or chain with `&&` in a single command.
+- **There is no TTY.** Anything interactive hangs until the timeout: `sudo`
+  that prompts for a password, `top`, `vim`, `apt` without `-y`. Use
+  non-interactive forms (`sudo -n`, `apt-get -y`, `systemctl --no-pager`), and
+  if a password prompt is genuinely needed, tell the user rather than trying to
+  feed it in.
+
+Read the exit code, not just the output. A command that printed nothing and
+exited 1 failed; reporting "done" because stdout was empty is wrong.
+
+## Reading before writing
+
+Prefer commands that observe over commands that change, and look before you
+act: `systemctl status` before `systemctl restart`, `ls` before `rm`, a diff
+before an overwrite.
+
+For anything destructive or disruptive - deleting files, restarting services,
+changing configuration, `chmod`/`chown` on system paths, package installs,
+anything with `sudo` - **say what you are about to run and why, and let the
+user confirm**, unless they already asked for exactly that. Piping a remote
+script into a shell (`curl ... | sh`) is not something to do on someone's
+server on your own initiative.
+
+## Files
+
+`ssh_list` gives a structured listing with sizes, modes and dates - use it
+rather than parsing `ls` output. `ssh_download` and `ssh_upload` move files
+over SFTP; prefer them over `cat`-ing a file through `ssh_exec`, which mangles
+binaries and pushes the whole content through the model for nothing.
+
+## When it does not connect
+
+The error usually says which layer failed. Work from it rather than retrying:
+
+- **"not in known_hosts"** - the host has never been seen. Show the user the
+  fingerprint and ask them to confirm it against the server before re-running
+  with `acceptNewHostKey: true`. Do not pass that flag reflexively; it is the
+  moment the trust decision is made.
+- **"HOST KEY CHANGED"** - stop. This is either a reinstalled server or
+  someone between you and it. Never work around it by disabling host key
+  checking. Relay the message; the user has to resolve it deliberately.
+- **"rejected the credentials"** - user name, password or key is wrong, or the
+  key is not in the remote authorized_keys. `ssh_authorize` fixes the last one.
+- **"refused the connection"** - nothing is listening: wrong port, or sshd is
+  down.
+- Something about the local environment - run `ssh_doctor`, which reports what
+  is missing and what to do about it.
+
+## What to report back
+
+Give the user the command's actual output and its exit code. When a command
+failed, quote stderr rather than summarising it - the exact message is what
+they need. Say which host you ran it on.