Add SSHelp remote development skill

Author: nitrazepam01

.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{yml,yaml,json}]
+indent_size = 2
+
+[*.ps1]
+end_of_line = crlf

.github/workflows/tests.yml

@@ -0,0 +1,24 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  unittest:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Run tests
+        env:
+          PYTHONDONTWRITEBYTECODE: "1"
+        run: python -m unittest discover -s tests -v

.gitignore

@@ -0,0 +1,27 @@
+# Local agent and editor state
+/.agents/
+/.codex/
+/.reasonix/
+/.local/
+/.sshelp/
+/.srd-tmp/
+/.vscode/
+/.idea/
+
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.coverage
+htmlcov/
+.venv/
+venv/
+
+# SSHelp runtime state in any example project
+**/.sshelp/
+**/.srd-tmp/
+
+# OS files
+.DS_Store
+Thumbs.db
+Desktop.ini

CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing to SSHelp
+
+Thank you for helping improve SSHelp.
+
+## Before Opening A Change
+
+- Search existing issues and discussions.
+- Keep changes focused on one behavior or documentation concern.
+- Do not include real hostnames, IP addresses, usernames, private paths, credentials, terminal logs, or research data.
+- Discuss destructive behavior, authentication changes, package installation, or new remote write operations before implementation.
+
+## Development Workflow
+
+1. Fork the repository and create a focused branch.
+2. Keep the Skill self-contained under `sshelp/`.
+3. Preserve the single-JSON-object CLI contract.
+4. Keep automated SSH authentication in `BatchMode=yes`.
+5. Add tests proportional to the behavior and risk.
+6. Run:
+
+```powershell
+$env:PYTHONDONTWRITEBYTECODE = "1"
+python -m unittest discover -s tests -v
+```
+
+## Compatibility
+
+New code uses `SSHELP_*`, `sshelp-*`, and `~/.sshelp`. Compatibility with existing `SSH_RESEARCH_*`, `srd-*`, and `~/.ssh-research-debug` state must not be removed without a documented migration plan.
+
+## Pull Requests
+
+Describe:
+
+- The user problem and intended behavior.
+- Security and failure-mode considerations.
+- Tests performed, including whether a real SSH host was used.
+- Any new remote files, processes, ports, packages, or cleanup behavior.
+
+Do not commit generated `.sshelp`, `.srd-tmp`, `__pycache__`, dashboard runtime, SSH configuration, or key material.

README.md

@@ -0,0 +1,114 @@
+# SSHelp
+
+SSHelp is an agent-oriented SSH toolkit for running, observing, diagnosing, and safely editing work on remote Linux hosts. It combines bounded SSH commands, persistent tmux jobs, read-only terminal observation, process/resource diagnostics, and transactional remote file editing.
+
+SSHelp is distributed as a repository-local Codex Skill under [`sshelp/`](sshelp/).
+
+## Features
+
+- Run short, non-interactive SSH commands with structured JSON results.
+- Keep long-running or interactive work alive in tmux.
+- Read terminal output incrementally by byte offset.
+- Observe one job in Windows Terminal or a loopback-only ttyd page.
+- Display several jobs in a local read-only dashboard.
+- Diagnose quiet jobs using trusted tmux PIDs, process trees, resources, wait channels, ports, and GPU state.
+- Search remote source trees before downloading files.
+- Checkout selected files locally, edit with normal tools, detect conflicts, and commit with per-file atomic replacement.
+- Bootstrap fixed prerequisites on a new Linux host after explicit authorization.
+
+## Quick Start
+
+Requirements:
+
+- Python 3.11 or newer on the local machine.
+- OpenSSH client with a configured host alias and public-key authentication.
+- A Linux SSH host. SSHelp can install its fixed remote prerequisites with explicit approval.
+
+From the cloned repository, resolve the Skill entry once, then keep your shell in the project you are actually working on:
+
+```powershell
+$SSHelpRepo = (Resolve-Path .).Path
+$SSHelp = Join-Path $SSHelpRepo "sshelp\scripts\sshelp.py"
+$SSHelpWindows = Join-Path $SSHelpRepo "sshelp\scripts\SSHelp.ps1"
+
+Set-Location D:\Project
+python $SSHelp host test --host lab-host
+python $SSHelp exec --host lab-host --cwd /home/user/project -- git status --short
+```
+
+For a new server, install the fixed prerequisite set only after reviewing the action:
+
+```powershell
+python $SSHelp host install --host lab-host --yes
+python $SSHelp host test --host lab-host
+```
+
+Start and monitor a persistent job:
+
+```powershell
+python $SSHelp job start --host lab-host --cwd /home/user/project -- python3 -u train.py
+python $SSHelp job read --host lab-host --job-id JOB_ID --offset 0
+python $SSHelp job status --host lab-host --job-id JOB_ID
+```
+
+Run `python $SSHelp --help` for the complete command tree. See [`sshelp/SKILL.md`](sshelp/SKILL.md) for the Agent workflow.
+
+## Project-Local State
+
+SSHelp does not place file checkouts in the Skill repository. Local state is created under the current project:
+
+```text
+<project>/.sshelp/
+├── checkouts/
+└── runtime/
+```
+
+These paths are ignored by Git. Set `SSHELP_WORK_ROOT` to override the project state root.
+
+## Repository Layout
+
+```text
+sshelp/
+├── README.md
+├── CONTRIBUTING.md
+├── SECURITY.md
+├── docs/
+├── sshelp/                 # Codex Skill
+│   ├── SKILL.md
+│   ├── agents/
+│   ├── assets/
+│   ├── references/
+│   └── scripts/
+└── tests/
+```
+
+The Skill remains self-contained. The root documentation is for contributors and GitHub readers.
+
+## Development
+
+SSHelp has no third-party local runtime dependency. Run the test suite with:
+
+```powershell
+$env:PYTHONDONTWRITEBYTECODE = "1"
+python -m unittest discover -s tests -v
+```
+
+The test suite uses mocked SSH/SFTP for safety. Lenovo-specific integration tests used during development are not encoded as public defaults.
+
+## Security Model
+
+- Public-key or ssh-agent authentication only for automated operations.
+- Host-key verification remains enabled.
+- No private-key contents, stored passwords, arbitrary package names, SIGKILL, or recursive remote cleanup.
+- Web observers bind to loopback on both remote and local machines.
+- File commits use path validation, SHA-256 conflict detection, and same-directory atomic replacement.
+
+Read [`SECURITY.md`](SECURITY.md) before reporting a vulnerability.
+
+## Project Status
+
+The current implementation is tested on Windows clients and Linux SSH hosts. Contributions for additional platforms, distributions, diagnostics, documentation, and test coverage are welcome.
+
+## License
+
+SSHelp is licensed under the [Apache License 2.0](LICENSE).

SECURITY.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+## Reporting A Vulnerability
+
+Use GitHub private vulnerability reporting when it is enabled for the repository. Do not publish credentials, private keys, host addresses, terminal output, or exploit details in a public issue.
+
+Include the affected command, expected boundary, observed behavior, and a minimal reproduction that uses non-sensitive test data.
+
+## Security Boundaries
+
+SSHelp is designed to:
+
+- Use public-key or ssh-agent authentication for automated commands.
+- Keep host-key verification enabled.
+- Avoid reading or transporting private-key contents.
+- Restrict task control to validated SSHelp tmux sessions.
+- Keep observers read-only and bound to loopback.
+- Reject path traversal, symlink writes, secret filenames, and remote file conflicts.
+- Require explicit confirmation for prerequisite installation.
+- Avoid SIGKILL, arbitrary PID control, and recursive remote cleanup.
+
+Report any behavior that crosses these boundaries privately.
+
+## Supported Versions
+
+Until formal releases exist, only the latest commit on the default branch is supported.