sshscript 2.0.2__tar.gz → 3.1.5__tar.gz

sshscript-3.1.5/.github/dependabot.yml

@@ -0,0 +1,27 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    target-branch: release
+    schedule:
+      interval: weekly
+    groups:
+      python-patch-and-minor:
+        patterns:
+          - "*"
+        update-types:
+          - patch
+          - minor
+
+  - package-ecosystem: github-actions
+    directory: /
+    target-branch: release
+    schedule:
+      interval: weekly
+    groups:
+      actions-patch-and-minor:
+        patterns:
+          - "*"
+        update-types:
+          - patch
+          - minor

sshscript-3.1.5/.github/workflows/ci.yml

@@ -0,0 +1,85 @@
+name: CI
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  verify:
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ['3.11', '3.12', '3.13', '3.14']
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install test and build dependencies
+        run: python -m pip install 'paramiko>=2.11,<5' 'packaging>=21' build twine
+      - name: Test source
+        run: python tools/run_checks.py
+      - name: Build and verify installed release
+        run: python tools/check_release.py --output '${{ runner.temp }}/verified-artifacts'
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: sshscript-${{ matrix.os }}-${{ matrix.python-version }}
+          path: ${{ runner.temp }}/verified-artifacts/
+
+  openssh-integration:
+    name: OpenSSH integration (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.14']
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install test and build dependencies
+        run: python -m pip install 'paramiko>=2.11,<5' 'packaging>=21' build twine
+      - name: Build and verify wheel
+        run: python tools/check_release.py --output "$RUNNER_TEMP/verified-artifacts"
+      - name: Install verified wheel
+        run: python -m pip install --force-reinstall "$RUNNER_TEMP"/verified-artifacts/*.whl
+      - name: Provision loopback OpenSSH server
+        run: bash tools/setup_openssh_ci.sh "$GITHUB_ENV"
+      - name: Test installed wheel against OpenSSH
+        run: |
+          mkdir -p "$RUNNER_TEMP/openssh-tests"
+          cp src/sshscript/unittest/test_openssh_integration.py "$RUNNER_TEMP/openssh-tests/"
+          cd "$RUNNER_TEMP/openssh-tests"
+          python -I test_openssh_integration.py -v
+      - name: Upload OpenSSH server log
+        if: ${{ failure() && env.SSHSCRIPT_OPENSSH_LOG != '' }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: openssh-log-python-${{ matrix.python-version }}
+          if-no-files-found: warn
+          path: ${{ env.SSHSCRIPT_OPENSSH_LOG }}
+      - name: Remove disposable OpenSSH state
+        if: always()
+        run: |
+          if [[ -n "${SSHSCRIPT_OPENSSH_PID_FILE:-}" && -s "$SSHSCRIPT_OPENSSH_PID_FILE" ]]; then
+            sudo kill "$(cat "$SSHSCRIPT_OPENSSH_PID_FILE")" || true
+          fi
+          if [[ -n "${SSHSCRIPT_OPENSSH_SUDOERS:-}" ]]; then
+            sudo rm -f "$SSHSCRIPT_OPENSSH_SUDOERS"
+          fi
+          if [[ -n "${SSHSCRIPT_OPENSSH_USER:-}" ]]; then
+            sudo userdel -r "$SSHSCRIPT_OPENSSH_USER" 2>/dev/null || true
+          fi
+          if [[ -n "${SSHSCRIPT_OPENSSH_TARGET_USER:-}" ]]; then
+            sudo userdel -r "$SSHSCRIPT_OPENSSH_TARGET_USER" 2>/dev/null || true
+          fi
+          if [[ -n "${SSHSCRIPT_OPENSSH_ROOT:-}" && "$SSHSCRIPT_OPENSSH_ROOT" == "$RUNNER_TEMP"/sshscript-openssh.* ]]; then
+            sudo rm -rf -- "$SSHSCRIPT_OPENSSH_ROOT"
+          fi

sshscript-3.1.5/.github/workflows/codeql.yml

@@ -0,0 +1,30 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [release]
+  pull_request:
+    branches: [release]
+  schedule:
+    - cron: "17 3 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: CodeQL (Python and Actions)
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: github/codeql-action/init@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4
+        with:
+          languages: python, actions
+      - uses: github/codeql-action/analyze@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4

sshscript-3.1.5/.github/workflows/release.yml

@@ -0,0 +1,214 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Verify and attest release artifacts
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: "3.11"
+      - name: Install pinned build dependencies
+        run: >-
+          python -m pip install
+          'paramiko>=2.11,<5' 'packaging>=21'
+          'build==1.6.1' 'twine==7.0.0'
+      - name: Verify tag targets the current release branch
+        run: |
+          git fetch --no-tags --depth=1 origin release
+          test "$(git rev-parse HEAD)" = "$(git rev-parse FETCH_HEAD)"
+      - name: Verify tag and package version
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          PACKAGE_VERSION=$(python -c "import runpy; print(runpy.run_path('src/sshscript/_version.py')['__version__'])")
+          test "$RELEASE_TAG" = "v$PACKAGE_VERSION"
+      - name: Stabilize build timestamps
+        run: echo "SOURCE_DATE_EPOCH=$(git show -s --format=%ct HEAD)" >> "$GITHUB_ENV"
+      - name: Run release gates and build verified artifacts
+        run: |
+          python tools/run_checks.py
+          python tools/check_release.py --output "$RUNNER_TEMP/sshscript-release"
+      - name: Attest wheel and source distribution
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4
+        with:
+          subject-path: |
+            ${{ runner.temp }}/sshscript-release/*.whl
+            ${{ runner.temp }}/sshscript-release/*.tar.gz
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: python-package-distributions
+          if-no-files-found: error
+          path: ${{ runner.temp }}/sshscript-release/
+
+  openssh-integration:
+    name: Release OpenSSH integration (Python ${{ matrix.python-version }})
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.14']
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
+        with:
+          name: python-package-distributions
+          path: dist
+      - name: Install verified wheel
+        run: python -m pip install dist/*.whl
+      - name: Provision loopback OpenSSH server
+        run: bash tools/setup_openssh_ci.sh "$GITHUB_ENV"
+      - name: Test installed wheel against OpenSSH
+        run: |
+          mkdir -p "$RUNNER_TEMP/openssh-tests"
+          cp src/sshscript/unittest/test_openssh_integration.py "$RUNNER_TEMP/openssh-tests/"
+          cd "$RUNNER_TEMP/openssh-tests"
+          python -I test_openssh_integration.py -v
+      - name: Upload OpenSSH server log
+        if: ${{ failure() && env.SSHSCRIPT_OPENSSH_LOG != '' }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: release-openssh-log-python-${{ matrix.python-version }}
+          if-no-files-found: warn
+          path: ${{ env.SSHSCRIPT_OPENSSH_LOG }}
+      - name: Remove disposable OpenSSH state
+        if: always()
+        run: |
+          if [[ -n "${SSHSCRIPT_OPENSSH_PID_FILE:-}" && -s "$SSHSCRIPT_OPENSSH_PID_FILE" ]]; then
+            sudo kill "$(cat "$SSHSCRIPT_OPENSSH_PID_FILE")" || true
+          fi
+          if [[ -n "${SSHSCRIPT_OPENSSH_SUDOERS:-}" ]]; then
+            sudo rm -f "$SSHSCRIPT_OPENSSH_SUDOERS"
+          fi
+          if [[ -n "${SSHSCRIPT_OPENSSH_USER:-}" ]]; then
+            sudo userdel -r "$SSHSCRIPT_OPENSSH_USER" 2>/dev/null || true
+          fi
+          if [[ -n "${SSHSCRIPT_OPENSSH_TARGET_USER:-}" ]]; then
+            sudo userdel -r "$SSHSCRIPT_OPENSSH_TARGET_USER" 2>/dev/null || true
+          fi
+          if [[ -n "${SSHSCRIPT_OPENSSH_ROOT:-}" && "$SSHSCRIPT_OPENSSH_ROOT" == "$RUNNER_TEMP"/sshscript-openssh.* ]]; then
+            sudo rm -rf -- "$SSHSCRIPT_OPENSSH_ROOT"
+          fi
+
+  draft-github-release:
+    name: Create draft GitHub Release
+    needs: [build, openssh-integration]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: "3.11"
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
+        with:
+          name: python-package-distributions
+          path: dist
+      - name: Verify artifact hashes
+        run: |
+          python - <<'PY'
+          import hashlib
+          import json
+          from pathlib import Path
+
+          root = Path("dist")
+          manifest = json.loads((root / "verified.json").read_text())
+          if len(manifest) != 2:
+              raise SystemExit("expected exactly two verified distributions")
+          for name, expected in manifest.items():
+              if Path(name).name != name:
+                  raise SystemExit(f"invalid distribution name: {name}")
+              actual = hashlib.sha256((root / name).read_bytes()).hexdigest()
+              if actual != expected:
+                  raise SystemExit(f"artifact hash mismatch: {name}")
+          PY
+      - name: Create immutable draft with verified assets
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: >-
+          gh release create "$RELEASE_TAG"
+          dist/*.whl dist/*.tar.gz dist/verified.json
+          --repo "$GITHUB_REPOSITORY"
+          --verify-tag --draft --generate-notes
+          --title "SSHScript ${RELEASE_TAG#v}"
+
+  publish-to-pypi:
+    name: Publish distributions to PyPI
+    needs: draft-github-release
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/sshscript
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+        with:
+          python-version: "3.11"
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
+        with:
+          name: python-package-distributions
+          path: dist
+      - name: Recheck hashes and isolate distributions
+        run: |
+          python - <<'PY'
+          import hashlib
+          import json
+          from pathlib import Path
+
+          root = Path("dist")
+          manifest = json.loads((root / "verified.json").read_text())
+          if len(manifest) != 2:
+              raise SystemExit("expected exactly two verified distributions")
+          publish = Path("publish")
+          publish.mkdir()
+          for name, expected in manifest.items():
+              if Path(name).name != name:
+                  raise SystemExit(f"invalid distribution name: {name}")
+              source = root / name
+              actual = hashlib.sha256(source.read_bytes()).hexdigest()
+              if actual != expected:
+                  raise SystemExit(f"artifact hash mismatch: {name}")
+              (publish / name).write_bytes(source.read_bytes())
+          PY
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          packages-dir: publish/
+
+  publish-github-release:
+    name: Publish GitHub Release
+    needs: publish-to-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Publish the verified draft
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: gh release edit "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" --draft=false

sshscript-3.1.5/CHANGELOG.md

@@ -0,0 +1,101 @@
+# Changelog
+
+This project records user-visible changes here. Release artifacts and their
+provenance are available from the linked GitHub Release and PyPI pages.
+
+## [3.1.5] - 2026-09-27
+
+### Command API and SSH configuration
+
+- Accept argv lists/tuples for a single command, with local direct execution
+  and POSIX quoting over SSH; shell mode remains explicit for strings.
+- Return immutable CommandResult snapshots with stdout, stderr, exitcode,
+  host, duration, and command. Unpacking/indexing now yields three values:
+  stdout, stderr, exitcode. Two-value unpacking must be updated.
+  Output values are now strings rather than live buffer objects.
+- Apply check=True consistently to local and remote one-shot commands after
+  preserving results; CalledProcessError carries text output and result.
+- Resolve common ~/.ssh/config settings with explicit API overrides; add
+  config opt-out, alternate files, and a connection-free settings preview.
+  Support ProxyCommand and ProxyJump (the latter uses local OpenSSH).
+- Reject unsupported Match/Include/canonicalization rules; warn about other
+  unapplied config settings. ProxyJump requires noninteractive authentication
+  and verified jump-host keys. Existing host-key checks remain enabled.
+
+### Script validation
+
+- Add check_file(path) and --check FILE to compile Python/dollar syntax without
+  executing user code, imports, or commands. The no-file --check update alias
+  remains compatible; --check-updates is the explicit update command.
+- Map tokenizer indentation errors to the original source file; retain source
+  mapping coverage for nested commands, interpolation, multiline expressions,
+  and imported .spy modules. Editor integration is deferred.
+
+### Documentation and community
+
+- Reorganize the README around installation, secure first use, compatibility,
+  support, and release provenance.
+- Add structured issue forms, a pull request template, and a Code of Conduct.
+- Clarify supported environments, security boundaries, and public test paths.
+
+## [3.1.4] - 2026-09-24
+
+First Production/Stable release in the 3.1 line. Published through
+[PyPI Trusted Publishing](https://pypi.org/project/sshscript/3.1.4/) with
+verified artifacts in the
+[GitHub Release](https://github.com/iapyeh/sshscript/releases/tag/v3.1.4).
+
+### Production hardening
+
+- Require Python 3.11 or newer; CI targets 3.11, 3.12, 3.13, and 3.14.
+- Replace package runtime assertions with the stable exception contract in
+  EXCEPTIONS.md, including validation under `python -O`.
+- Make listener removal, hijack/release, and last-layer checks atomic and
+  non-mutating on failure; fix positive session-stack indexing.
+- Reject invalid command, PTY, pattern, and output arguments before execution
+  or buffer mutation. Disconnected SFTP access raises SSHScriptException.
+- Move embedded stdio tests into the credential-free suite and add normal,
+  optimized, and package AST assertion release gates.
+- AssertionError was never a supported API contract. User-written `.spy`
+  assertions are preserved, but production command-success handling must use
+  explicit checks or `check=True`, because optimized Python removes assertions.
+- Validate closed and hijacked channel operations, AST invariants, persistent
+  commands, PTY modes, and output buffers with stable exception types.
+
+
+### Security
+
+- Verify SSH host keys by default; insecure automatic key acceptance now
+  requires an explicit Paramiko policy.
+- Stop forwarding the complete local environment to interactive SSH sessions.
+- Read remote private keys through SFTP instead of interpolated shell commands.
+- Remove SSH hostnames and complete local/remote paths from upload/download
+  INFO logs.
+- Add CodeQL, Dependabot, private vulnerability reporting guidance, and an
+  OIDC-based trusted publishing workflow.
+- Pin release actions and build tooling, attest distributions, retain their
+  hash manifest, and keep the GitHub Release in draft until PyPI succeeds.
+
+### Fixed
+
+- Drain remote stdout and stderr concurrently and send stdin EOF.
+- Make session cleanup failures observable and optionally strict.
+- Preserve `$.break(code)` as the CLI exit status.
+- Simplify `run_file()` to execute exactly one file; compose scripts through
+  include syntax or Python imports instead of directory/glob execution.
+- Make `.spy` importing explicit with `sshscript.spy_imports()` and scope the
+  importer automatically while `run_file()` is executing.
+- Stop patching `threading.Thread`, `warnings`, and `__main__` during import.
+- Preserve `.spy` thread session inheritance with a context-aware Thread
+  created by the source transformer instead of a process-wide monkey patch.
+- Make `Session()` construction side-effect free and scope stack activation to
+  `run()`, context managers, or an explicit unscoped `$.connect()` operation.
+
+### Project
+
+- Add packaging metadata, license, contributor guidance, and CI configuration.
+- Add a disposable loopback OpenSSH integration gate covering host keys, SFTP,
+  PTY behavior, sudo/su, and timeout handling.
+
+[Unreleased]: https://github.com/iapyeh/sshscript/compare/v3.1.4...release
+[3.1.4]: https://github.com/iapyeh/sshscript/releases/tag/v3.1.4

sshscript-3.1.5/CODE_OF_CONDUCT.md

@@ -0,0 +1,61 @@
+# Code of Conduct
+
+## Our commitment
+
+SSHScript welcomes people of every background and experience level. We are
+committed to a collaborative environment in which participation is respectful,
+constructive, and free from harassment.
+
+## Expected behavior
+
+- Be respectful and assume good faith while still discussing technical risks
+  directly.
+- Give actionable feedback about work rather than making personal judgments.
+- Acknowledge different experience levels, environments, and communication
+  styles.
+- Protect credentials, personal information, internal infrastructure details,
+  and embargoed vulnerability information.
+- Accept moderation decisions and correct harmful behavior promptly.
+
+## Unacceptable behavior
+
+- Harassment, intimidation, threats, stalking, or discriminatory language.
+- Sexualized language, imagery, or unwelcome attention.
+- Personal attacks, deliberate humiliation, or sustained disruption.
+- Publishing another person's private information without permission.
+- Retaliation against someone who reports a concern in good faith.
+- Using project spaces to distribute malware, credentials, or knowingly unsafe
+  instructions.
+
+Reasonable technical disagreement, security review, and criticism of code are
+not harassment when expressed professionally and focused on the work.
+
+## Scope
+
+This policy applies to repository issues, pull requests, reviews, discussions,
+release and documentation spaces, and other public interactions in which a
+person represents the SSHScript project.
+
+## Reporting conduct concerns
+
+Do not post a conduct report publicly. Contact the maintainer at
+[iapyeh@gmail.com](mailto:iapyeh@gmail.com) with links or screenshots, the
+relevant dates, a factual description, and any immediate safety concern. Share
+only information needed to evaluate the report.
+
+Suspected software vulnerabilities belong in
+[GitHub private vulnerability reporting](https://github.com/iapyeh/sshscript/security/advisories/new),
+as described in [SECURITY.md](SECURITY.md).
+
+Reports will be reviewed as privately as practical. A maintainer named in or
+directly involved with a report should not make the enforcement decision when a
+reasonable alternative reviewer is available. Knowingly false reports may
+themselves violate this policy; an unproven good-faith report does not.
+
+## Enforcement
+
+Project maintainers may edit or remove content, request a correction, issue a
+warning, limit participation, or permanently exclude a participant. Responses
+will be based on severity, impact, pattern of behavior, and willingness to
+correct the problem. Illegal activity or a credible threat may be referred to
+the appropriate service provider or authority.

sshscript-3.1.5/CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing
+
+Thank you for helping improve SSHScript. Participation is governed by the
+[Code of Conduct](CODE_OF_CONDUCT.md). Please use a private security advisory,
+not an issue or pull request, for a suspected vulnerability.
+
+## Development setup
+
+Use Python 3.11 or newer. The public release checkout uses a `src/` package
+layout. From the repository root:
+
+```sh
+python3 -m venv .venv
+. .venv/bin/activate
+python3 -m pip install --upgrade pip
+python3 -m pip install -e .
+python3 -m pip install build twine
+```
+
+Keep test credentials, host inventories, local configuration, build output,
+and editor state untracked.
+
+## Required checks
+
+Run the complete credential-free gate before proposing a change:
+
+```sh
+python3 tools/run_checks.py
+python3 tools/check_release.py --output /tmp/sshscript-candidate-UNIQUE
+```
+
+The output path must not already exist. The first command finds the public test
+suite under `src/sshscript/unittest/` and runs normal and optimized tests,
+compile checks, the package assertion scan, and dollar-syntax smoke tests. The
+second command builds the allowlisted wheel and source distribution, checks
+their metadata, installs the wheel in an isolated environment, and performs an
+installed-package smoke test.
+
+Tests under `src/sshscript/unittest/` must not require network access, SSH
+agents, private keys, passwords, or host-specific configuration unless they are
+part of the isolated OpenSSH fixture. A regression fix should add a
+credential-free test whenever the behavior can be reproduced with a fake
+Paramiko client or local subprocess.
+
+## SSH integration tests
+
+Public CI provisions a disposable loopback OpenSSH server and runs
+`src/sshscript/unittest/test_openssh_integration.py` against the built wheel.
+The setup uses ephemeral users, passwords, and keys generated inside the CI
+runner; it must never target a persistent host. See
+`tools/setup_openssh_ci.sh` for the exact environment contract.
+
+Historical site-specific and credentialed tests are intentionally not shipped
+in the public release checkout. Do not add production credentials or internal
+host scenarios to a pull request. Convert a failure into a disposable fixture,
+redacted fake, or credential-free unit test first.
+
+## Compatibility and public APIs
+
+Changes to `Session`, `run_file()`, CLI exit statuses, dollar syntax, logging,
+or SSH security defaults require synchronized implementation, tests, README,
+and changelog updates. Avoid silently accepting insecure behavior.
+
+The module API is the primary public interface. Keep dollar syntax behavior
+aligned with it, and document compatibility aliases or deprecations explicitly.
+Tests should cover both normal Python and `python -O` where the exception
+contract is involved. Do not use runtime `assert` statements for package input
+or lifecycle validation.
+
+Before release, run all normal, optimized, compile, and AST gates listed in
+[EXCEPTIONS.md](EXCEPTIONS.md). CI targets Python 3.11 through 3.14.
+
+## Pull requests
+
+Target the protected `release` branch from a topic branch or fork. Keep each
+pull request focused and include:
+
+- the problem and intended behavior;
+- tests that fail before the change and pass afterward when practical;
+- documentation and changelog updates for user-visible behavior;
+- the commands used to validate the change;
+- any compatibility, security, logging, or migration impact.
+
+Complete the pull request template and respond to review feedback. A passing CI
+run is required but does not guarantee acceptance. By submitting a
+contribution, you agree that it may be distributed under the repository's MIT
+License.

sshscript-3.1.5/EXCEPTIONS.md

@@ -0,0 +1,54 @@
+# Stable exception contract
+
+The following contract applies with and without `python -O`.
+
+| Failure | Exception |
+| --- | --- |
+| Wrong argument type | `TypeError` |
+| Correct type but invalid value, content, or combination | `ValueError` |
+| Invalid session, console, or channel lifecycle state | `RuntimeError` |
+| Operation on a closed channel or transport | `BrokenPipeError` |
+| Channel ends while waiting | `EOFError` |
+| Timeout | `TimeoutError` |
+| Disconnected `Session.sftp`, upload, or download | `SSHScriptException` |
+| Filesystem failure | Appropriate `OSError` subclass |
+| Paramiko failure | Original Paramiko exception and traceback |
+| Internal AST or data-structure invariant failure | Descriptive `RuntimeError` |
+| Stack indexing outside its bounds | `IndexError`, following `deque` |
+
+Nonzero command exit status remains data by default. One-shot local and remote
+`Session.exec_command(..., check=True)` raise `subprocess.CalledProcessError`
+after saving `session.last_result` and channel output/status. The exception's
+`output`/`stdout` and `stderr` are text snapshots on both backends; `cmd` is a
+string or argument tuple, and `result` is the complete immutable CommandResult.
+CommandResult unpacks as exactly three values: stdout, stderr, exitcode; indexing
+and slicing use the same order. Persistent consoles retain two-buffer returns.
+This replaces the local backend's former raw subprocess exception (byte
+output and generated argv). `AssertionError` was never a supported API contract.
+
+User-written `assert` in `.spy` files is preserved as Python syntax. Python's
+optimized mode removes these statements, including any calls inside them.
+Production scripts must not depend on `assert` for command-success handling.
+For local or remote one-shot execution, use `session.exec_command(command, check=True)`, or
+explicitly inspect `session.exitcode` and raise an application exception when
+appropriate. Persistent consoles retain their separate command/prompt contract.
+
+`for_with` must be strictly bool. `get_pty` must be None or bool. Commands must
+be nonempty strings or nonempty lists/tuples of string arguments. Argument
+sequences disallow NUL, an empty executable, and shell mode. Persistent
+commands must contain only one line.
+Compiled bytes regular expressions are not accepted by text-output matching.
+Listener removal requires the identical top listener; failed removal, duplicate
+hijack/release, and last-layer removal leave their associated state unchanged.
+
+Run the canonical credential-free gates from the public release repository root
+using a supported interpreter:
+
+```sh
+python3 tools/run_checks.py
+```
+
+The runner locates the package and tests under `src/sshscript/`, then executes
+normal and optimized test suites, the dollar-syntax smoke suite, compile checks,
+and the package-assertion gate. CI runs these checks on Python 3.11–3.14 on
+Linux and macOS. The AST gate scans package runtime modules and excludes tests.

{sshscript-2.0.2 → sshscript-3.1.5}/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Hsin Yuan Yeh
+Copyright (c) 2022-2026 Hsin Yuan Yeh
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

sshscript-3.1.5/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md LICENSE.txt RELEASING.md
+include CHANGELOG.md CODE_OF_CONDUCT.md CONTRIBUTING.md EXCEPTIONS.md SECURITY.md SUPPORT.md
+recursive-include tools *.py
+include tools/setup_openssh_ci.sh
+include .github/dependabot.yml
+recursive-include .github/workflows *.yml
+recursive-include src/sshscript/unittest *.py *.spy