assh-toolkit 0.1.0__tar.gz

assh_toolkit-0.1.0/.assh/README.md

@@ -0,0 +1,9 @@
+# assh repo-local state
+
+This directory is created and managed by `assh init`.
+
+- `state.db` stores repo-local targets, env sets, k8s overrides, and task cache
+- `config.toml` stores repo-local defaults
+- `scripts/` contains tracked reusable repo workflows
+- `templates/` contains tracked repo templates
+- `logs/` and `sockets/` contain runtime artifacts and are ignored

assh_toolkit-0.1.0/.assh/scripts/README.md

@@ -0,0 +1,3 @@
+# Repo workflow scripts
+
+Put shared `.sh` or `.py` workflows here and run them with `assh script run <name>`.

assh_toolkit-0.1.0/.assh/templates/README.md

@@ -0,0 +1,3 @@
+# Repo templates
+
+Put tracked reusable remote templates here for later script or bootstrap workflows.

assh_toolkit-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

assh_toolkit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  checks:
+    name: Lint, Typecheck, Test, Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Sync dependencies
+        run: uv sync --group dev
+
+      - name: Ruff
+        run: uv run ruff check .
+
+      - name: Mypy
+        run: uv run mypy src
+
+      - name: Pytest
+        run: uv run pytest
+
+      - name: Build
+        run: uv build

assh_toolkit-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,60 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - docs/**
+      - pyproject.toml
+      - .github/workflows/docs.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: docs-pages
+  cancel-in-progress: true
+
+env:
+  DOCS_SITE_URL: ${{ vars.DOCS_SITE_URL }}
+  DOCS_CUSTOM_DOMAIN: ${{ vars.DOCS_CUSTOM_DOMAIN }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Setup Python
+        run: uv python install 3.12
+      - name: Install Python dependencies
+        run: uv sync --group dev
+      
+      - name: Build docs with Sparkify action
+        uses: SparkAIUR/sparkify@v1
+        with:
+          docs-dir: ./docs
+          out-dir: ./site
+          site: ${{ env.DOCS_SITE_URL }}
+          base: ""
+          strict: "true"
+      - name: Write CNAME
+        if: ${{ env.DOCS_CUSTOM_DOMAIN != '' }}
+        run: echo "${DOCS_CUSTOM_DOMAIN}" > site/CNAME
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

assh_toolkit-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,65 @@
+name: Release
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  verify:
+    name: Verify release candidate
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Sync dependencies
+        run: uv sync --group dev
+
+      - name: Ruff
+        run: uv run ruff check .
+
+      - name: Mypy
+        run: uv run mypy src
+
+      - name: Pytest
+        run: uv run pytest
+
+  pypi:
+    name: Build and Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: verify
+    environment:
+      # Create this environment in the GitHub repository under Settings -> Environments
+      name: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+      
+      - name: "Set up Python"
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish

assh_toolkit-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+/target
+/artifacts
+/dist-docs
+/dist-docs-local
+/.sparkify-docs
+/tmp
+/.venv
+/.pytest_cache
+/.ruff_cache
+/.mypy_cache
+**/__pycache__/
+*.pyc
+.DS_Store
+.assh/*
+!.assh/README.md
+!.assh/scripts/
+!.assh/scripts/**
+!.assh/templates/
+!.assh/templates/**
+refs/docs/*
+refs/tasks/*
+refs/notes*
+/.astro

assh_toolkit-0.1.0/AGENTS.md

@@ -0,0 +1,88 @@
+# AGENTS
+
+`assh` is an agentic SSH toolkit for stateful, token-efficient infrastructure workflows. This file is the tracked entrypoint for contributors and agentic tooling. If local internal docs exist under `refs/docs/`, start there for the detailed private source of truth; otherwise use this file and `docs/`.
+
+<!-- assh:managed:start -->
+## assh Remote Execution Policy
+
+Use `assh` instead of raw `ssh`, `scp`, `docker exec`, or `kubectl`
+when you are operating on managed remote infrastructure for this repository.
+
+- Run commands with `assh run "<command>" --target <alias>`
+- Start long-running jobs with `assh task start "<command>" --target <alias>`
+- Use `assh docker ...` and `assh k8s ...` helpers instead of composing
+  nested shell invocations manually
+- Use `assh script run <name> --target <alias>` for tracked shared workflows
+- Check `assh status` and `assh doctor` before inventing local state or
+  connection assumptions
+
+Key rules:
+
+- Prefer explicit `--target`, `--env-set`, `--namespace`, and `--context`
+  flags over hidden assumptions
+- Do not invoke interactive full-screen commands such as `vim`, `nano`, `top`, or `less`
+- `assh` tracks remote working directories and truncates oversized output automatically
+- Default output is structured for non-TTY use and Rich-formatted for TTY use
+<!-- assh:managed:end -->
+
+
+## Source map
+
+- Public docs live in `docs/` and are written in Mintlify-compatible MDX.
+- Private local docs live in `refs/docs/` and are gitignored by design.
+- The internal scenario matrix lives in `refs/docs/SCENARIOS.md` when available locally.
+- Runtime code lives under `src/assh/`.
+- Tests live under `tests/`.
+- Repo-local tracked workflow assets belong in `.assh/scripts/` and `.assh/templates/`.
+
+## Runtime architecture
+
+- CLI orchestrator: `src/assh/cli.py`
+- config resolver and settings loader: `src/assh/settings.py`
+- state manager and SQLite layer: `src/assh/state.py`
+- SSH transport worker: `src/assh/transport.py`
+- output normalizer and serializers: `src/assh/output.py`
+- repo/global workflow helpers: `src/assh/workflows.py`
+- Docker and Kubernetes adapters: `src/assh/integrations/`
+- remote worker payload: `src/assh/remote_worker.py`
+- local worker client: `src/assh/worker_client.py`
+
+## Current command surface
+
+- Top level: `init`, `doctor`, `status`, `version`, `run`, `chain`, `bg`, `push`, `fetch`, `logs`
+- Target management: `target add`, `target remove`, `target list`, `target resolve`, `target import`
+- Environment sets: `env set`, `env unset`, `env enable`, `env disable`, `env list`, `env show`
+- Scripts: `script list`, `script validate`, `script run`
+- Docker helpers: `docker ps`, `docker exec`, `docker logs`, `docker inspect`
+- Kubernetes helpers: `k8s context set`, `k8s context clear`, `k8s context show`, `k8s get`, `k8s exec`, `k8s logs`
+- Worker lifecycle: `worker deploy`, `worker health`, `worker upgrade`, `worker remove`
+- Task lifecycle: `task start`, `task status`, `task logs`, `task kill`, `task list`
+
+## Contributing workflow
+
+- Use `uv` for everything. `pyproject.toml` is the package and tooling source of truth.
+- Install the dev environment with `uv sync --group dev`.
+- Run the CLI with `uv run assh --help`.
+- Run checks with `uv run pytest`, `uv run ruff check .`, and `uv run mypy src`.
+- Run scenario coverage with `uv run pytest tests/scenarios`.
+- Use `ASSH_E2E_ENABLE=1 uv run pytest -m e2e tests/e2e/test_vm_manual.py` only for intentional real-VM validation gates.
+- Update `docs/*` when user-facing behavior changes.
+- Update local `refs/docs/*` and `refs/docs/KB.md` when architecture, behavior, or operational knowledge changes.
+- No Nexus- or Vela-derived scenario may execute `kubectl`.
+
+## Roadmap
+
+- Sprint 0: source-of-truth docs, governance, and repo entrypoint
+- Sprint 1: package skeleton, typed models, and settings
+- Sprint 2: repo/global SQLite state, init flow, and legacy import
+- Sprint 3: async SSH transport, output shaping, and batch execution
+- Sprint 4: workflow scripts, Docker helpers, Kubernetes helpers, `doctor`, and `status`
+- Sprint 5: remote worker deployment and task lifecycle
+- Sprint 6: docs hardening, release validation, and MVP ship gate
+
+## Implementation status
+
+- The initial package, CLI surface, state layer, output layer, transport, Docker/Kubernetes helpers, and remote worker client/payload are implemented.
+- Public docs in `docs/` describe the current package surface.
+- Internal private docs in `refs/docs/` are expected to carry deeper operational detail and ongoing knowledge capture.
+- The scenario-driven validation suite now uses Astra and Nexus as executable SSH sources and Vela as modeled SSH edge-case input.

assh_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: assh-toolkit
+Version: 0.1.0
+Summary: Agentic SSH toolkit for stateful, token-efficient infrastructure workflows.
+Author: Codex
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: pydantic-settings<3.0.0,>=2.13.1
+Requires-Dist: pydantic<3.0.0,>=2.12.5
+Requires-Dist: pyyaml<7.0.0,>=6.0.3
+Requires-Dist: rich<15.0.0,>=14.3.3
+Requires-Dist: typer<0.25.0,>=0.24.1
+Description-Content-Type: text/markdown
+
+# assh
+
+`assh` is an agentic SSH toolkit for stateful, token-efficient remote execution.
+
+`assh` provides a typed Python package and CLI for:
+
+- repo and global target resolution
+- stateful remote execution with output shaping
+- environment-set injection
+- reusable workflow scripts
+- Docker and Kubernetes helpers
+- SSH-driven remote worker deployment and task lifecycle management
+
+## Status
+
+`v0.1.0` is the first MVP release.
+
+The current release includes:
+
+- async-first SSH transport with persisted remote working directory state
+- JSON, XML, and Rich output from a shared canonical result model
+- repo-local and global SQLite-backed target and env-set state
+- `push` and `fetch` helpers for remote file transfer
+- deployable remote worker support for long-running task lifecycle control
+- automated scenario coverage derived from Astra and Nexus workflows
+- a guarded real-VM validation suite exercised against `root@192.237.244.107`
+
+## Install
+
+### Local development
+
+```bash
+uv sync --group dev
+uv run assh --help
+```
+
+### Install as a tool
+
+```bash
+uv tool install --from . assh
+```
+
+## Quick start
+
+```bash
+uv run assh init
+uv run assh target add vm root@192.237.244.107
+uv run assh run "uname -a && whoami && pwd" --target vm
+```
+
+Persist a remote workspace across commands:
+
+```bash
+uv run assh chain \
+  --target vm \
+  --step "mkdir -p /tmp/assh-demo" \
+  --step "cd /tmp/assh-demo" \
+  --step "printf 'hello from assh\n' > note.txt"
+
+uv run assh run "pwd && cat note.txt" --target vm
+```
+
+Use env sets with automatic redaction:
+
+```bash
+uv run assh env set deploy APP_ENV production
+uv run assh env set deploy API_TOKEN super-secret-token
+uv run assh env enable deploy
+uv run assh run "printf 'APP_ENV=%s\nTOKEN=%s\n' \"\$APP_ENV\" \"\$API_TOKEN\"" --target vm
+```
+
+Use the remote worker for long-running tasks:
+
+```bash
+uv run assh worker deploy --target vm
+uv run assh task start "printf 'start\n'; sleep 10; printf 'done\n'" --target vm
+uv run assh task list --target vm
+uv run assh task logs <task-id> --target vm
+```
+
+## Validation
+
+Core local checks:
+
+```bash
+uv run ruff check .
+uv run mypy src
+uv run pytest
+uv build
+```
+
+Guarded real-VM validation:
+
+```bash
+ASSH_E2E_ENABLE=1 \
+ASSH_E2E_TARGET=root@192.237.244.107 \
+ASSH_E2E_WORKDIR=/tmp/assh-scenarios \
+ASSH_E2E_STRICT_HOSTKEY=accept-new \
+uv run pytest -m e2e tests/e2e/test_vm_manual.py -vv
+```
+
+## Documentation
+
+- [AGENTS.md](AGENTS.md) is the tracked repo entrypoint.
+- [docs/](docs/) contains the public Mintlify docs.
+- [docs/examples.mdx](docs/examples.mdx) contains copy-paste usage examples.
+
+## Release workflow
+
+- `.github/workflows/ci.yml` runs lint, typecheck, tests, and package builds on pushes and pull requests.
+- `.github/workflows/release.yml` verifies the tagged revision before publishing to PyPI.

assh_toolkit-0.1.0/README.md

@@ -0,0 +1,111 @@
+# assh
+
+`assh` is an agentic SSH toolkit for stateful, token-efficient remote execution.
+
+`assh` provides a typed Python package and CLI for:
+
+- repo and global target resolution
+- stateful remote execution with output shaping
+- environment-set injection
+- reusable workflow scripts
+- Docker and Kubernetes helpers
+- SSH-driven remote worker deployment and task lifecycle management
+
+## Status
+
+`v0.1.0` is the first MVP release.
+
+The current release includes:
+
+- async-first SSH transport with persisted remote working directory state
+- JSON, XML, and Rich output from a shared canonical result model
+- repo-local and global SQLite-backed target and env-set state
+- `push` and `fetch` helpers for remote file transfer
+- deployable remote worker support for long-running task lifecycle control
+- automated scenario coverage derived from Astra and Nexus workflows
+- a guarded real-VM validation suite exercised against `root@192.237.244.107`
+
+## Install
+
+### Local development
+
+```bash
+uv sync --group dev
+uv run assh --help
+```
+
+### Install as a tool
+
+```bash
+uv tool install --from . assh
+```
+
+## Quick start
+
+```bash
+uv run assh init
+uv run assh target add vm root@192.237.244.107
+uv run assh run "uname -a && whoami && pwd" --target vm
+```
+
+Persist a remote workspace across commands:
+
+```bash
+uv run assh chain \
+  --target vm \
+  --step "mkdir -p /tmp/assh-demo" \
+  --step "cd /tmp/assh-demo" \
+  --step "printf 'hello from assh\n' > note.txt"
+
+uv run assh run "pwd && cat note.txt" --target vm
+```
+
+Use env sets with automatic redaction:
+
+```bash
+uv run assh env set deploy APP_ENV production
+uv run assh env set deploy API_TOKEN super-secret-token
+uv run assh env enable deploy
+uv run assh run "printf 'APP_ENV=%s\nTOKEN=%s\n' \"\$APP_ENV\" \"\$API_TOKEN\"" --target vm
+```
+
+Use the remote worker for long-running tasks:
+
+```bash
+uv run assh worker deploy --target vm
+uv run assh task start "printf 'start\n'; sleep 10; printf 'done\n'" --target vm
+uv run assh task list --target vm
+uv run assh task logs <task-id> --target vm
+```
+
+## Validation
+
+Core local checks:
+
+```bash
+uv run ruff check .
+uv run mypy src
+uv run pytest
+uv build
+```
+
+Guarded real-VM validation:
+
+```bash
+ASSH_E2E_ENABLE=1 \
+ASSH_E2E_TARGET=root@192.237.244.107 \
+ASSH_E2E_WORKDIR=/tmp/assh-scenarios \
+ASSH_E2E_STRICT_HOSTKEY=accept-new \
+uv run pytest -m e2e tests/e2e/test_vm_manual.py -vv
+```
+
+## Documentation
+
+- [AGENTS.md](AGENTS.md) is the tracked repo entrypoint.
+- [docs/](docs/) contains the public Mintlify docs.
+- [docs/examples.mdx](docs/examples.mdx) contains copy-paste usage examples.
+
+## Release workflow
+
+- `.github/workflows/ci.yml` runs lint, typecheck, tests, and package builds on pushes and pull requests.
+- `.github/workflows/release.yml` verifies the tagged revision before publishing to PyPI.