shellflow 0.1.0__tar.gz

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

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.12"
+          - "3.13"
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-dependency-glob: |
+            pyproject.toml
+            uv.lock
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Run tests
+        run: uv run pytest -q
+
+      - name: Run BDD scenarios
+        run: uv run behave features
+
+  quality:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+          enable-cache: true
+          cache-dependency-glob: |
+            pyproject.toml
+            uv.lock
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Run formatting check
+        run: uv run ruff format --check .
+
+      - name: Run lint
+        run: uv run ruff check .
+
+      - name: Run type check
+        run: uv run ty check src tests
+
+      - name: Build distributions
+        run: uv build

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

@@ -0,0 +1,73 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Get version from tag
+        id: tag_version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_ENV
+
+      - name: Check pyproject.toml version
+        run: |
+          FILE_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          
+          echo "pyproject.toml version: $FILE_VERSION"
+          echo "Tag version: ${{ env.VERSION }}"
+          
+          if [ "$FILE_VERSION" != "${{ env.VERSION }}" ]; then
+            echo "Error: pyproject.toml version ($FILE_VERSION) does not match tag version (${{ env.VERSION }})"
+            exit 1
+          fi
+
+      - name: Generate Changelog
+        uses: orhun/git-cliff-action@v4
+        id: git-cliff
+        with:
+          config: cliff.toml
+          args: --verbose --latest --strip header
+        env:
+          OUTPUT: CHANGELOG.md
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body: ${{ steps.git-cliff.outputs.content }}
+          prerelease: ${{ contains(github.ref, 'alpha') || contains(github.ref, 'beta') }}
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Run release verification
+        run: |
+          uv run ruff format --check .
+          uv run ruff check .
+          uv run ty check src tests
+          uv run pytest -q
+          uv run behave features
+
+      - name: Build Package
+        run: uv build
+
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: uv publish

shellflow-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environment
+.venv/
+venv/
+env/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Ruff
+.ruff_cache/
+
+# ty
+.ty/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment variables
+.env
+.env.local
+.rumdl_cache/

shellflow-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

shellflow-0.1.0/.rumdl.toml

@@ -0,0 +1,24 @@
+# rumdl configuration file
+
+# Global configuration options
+[global]
+# List of rules to disable (uncomment and modify as needed)
+disable = ["MD013", "MD033", "MD041", "MD036"]
+
+# List of file/directory patterns to exclude from linting
+exclude = [
+    # Common directories to exclude
+    ".git",
+    ".github",
+    "node_modules",
+    "vendor",
+    "dist",
+    "build",
+    ".venv",
+    "venv",
+    "__pycache__",
+    "*.egg-info",
+
+    # Specific files or patterns
+    "CHANGELOG.md",
+]

shellflow-0.1.0/AGENTS.md

@@ -0,0 +1,67 @@
+# Shellflow Agent Instructions
+
+## Project Overview
+
+Shellflow is a minimal shell script orchestrator with SSH support. It allows users to write shell scripts that execute across local and remote environments using simple comment markers.
+
+## Project Structure
+
+```text
+shellflow/
+├── src/shellflow.py    # Main module with all functionality
+├── tests/               # Unit tests (pytest)
+├── features/            # BDD acceptance tests (behave)
+│   ├── parser.feature
+│   ├── runner.feature
+│   ├── steps/shellflow_steps.py
+│   └── environment.py
+├── behave_runner.py     # Wrapper for running behave
+├── pyproject.toml       # Project configuration
+├── README.md            # Documentation
+└── AGENTS.md           # This file
+```
+
+## Core Concepts
+
+### Script Block Markers
+
+- `# @LOCAL` - Start a local execution block
+- `# @REMOTE <host>` - Start a remote execution block
+
+### Key Modules
+
+- `Block` - Represents an execution block (local or remote)
+- `ExecutionContext` - Passes state between block executions
+- `ExecutionResult` - Result of executing a single block
+- `RunResult` - Result of running a complete script
+- `SSHConfig` - SSH configuration for remote hosts
+
+### CLI Commands
+
+```bash
+shellflow run <script>    # Run a shellflow script
+shellflow run <script> -v # Run with verbose output
+shellflow --version       # Show version
+```
+
+## Development Commands
+
+```bash
+just format      # Format code with ruff
+just lint        # Lint with ruff
+just test        # Run pytest
+just bdd         # Run behave BDD tests
+just test-all   # Run format, lint, test, and bdd
+just typecheck  # Type check with ty
+```
+
+## Testing
+
+- Unit tests: `pytest` under `tests/`
+- BDD tests: `behave` under `features/`
+- Run all: `just test-all`
+
+## Dependencies
+
+- Runtime: `paramiko>=3.0.0`
+- Dev: `pytest`, `behave`, `ruff`, `ty`, `hypothesis`

shellflow-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+## [0.1.0] - 2026-03-15
+
+### Features
+
+- Add public key to context7.json
+
+### Miscellaneous Tasks
+
+- Update release workflow to improve version check and changelog generation
+
+<!-- generated by git-cliff -->

shellflow-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

shellflow-0.1.0/Justfile

@@ -0,0 +1,90 @@
+# Default recipe to display help
+default:
+  @just --list
+
+# Sync all dependencies
+sync:
+  uv sync --all-groups
+
+# Format all code
+format:
+  rumdl fmt .
+  uv run ruff format .
+  uv run ruff check --fix .
+
+# Auto-fix linting issues
+fix:
+  rumdl check --fix .
+  uv run ruff check --fix .
+
+# Run all lints
+lint:
+  typos
+  rumdl check .
+  uv run ruff check .
+  uv run ruff format --check .
+  uv run ty check src tests
+
+# Run tests
+test:
+  uv run pytest
+
+# Run BDD scenarios
+bdd:
+  uv run behave
+
+# Run both TDD and BDD suites
+test-all:
+  uv run pytest
+  uv run behave
+
+# Run tests with coverage
+test-coverage:
+  uv run pytest --cov=uv_app --cov-report=term-missing --cov-report=html
+
+# Run benchmarks
+bench:
+  uv run pytest -m benchmark --benchmark-only
+
+# Build the package
+build:
+  uv build
+
+# Publish the package to PyPI
+publish:
+  uv build
+  uv publish
+
+# Type check with ty
+typecheck:
+  uv run ty check src tests
+
+# Check for Chinese characters
+check-cn:
+  rg --line-number --column "\p{Han}"
+
+# Full CI check
+ci: lint test-all build
+
+# ============================================================
+# Maintenance & Tools
+# ============================================================
+
+# Clean build artifacts
+clean:
+  rm -rf dist/ .pytest_cache/ .ruff_cache/ htmlcov/ .coverage
+  find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+  find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
+
+# Install all required development tools
+setup:
+  uv sync --all-groups
+  cargo install typos-cli
+
+# Lock dependencies
+lock:
+  uv lock
+
+# Update all dependencies
+update:
+  uv lock --upgrade

shellflow-0.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: shellflow
+Version: 0.1.0
+Summary: A minimal shell script orchestrator with SSH support
+Project-URL: Homepage, https://github.com/longcipher/shellflow
+Project-URL: Repository, https://github.com/longcipher/shellflow
+Project-URL: Issues, https://github.com/longcipher/shellflow/issues
+Author: Bob Liu
+License-Expression: Apache-2.0
+Keywords: automation,orchestration,shell,ssh
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.12
+Requires-Dist: paramiko>=3.0.0
+Description-Content-Type: text/markdown
+
+# ShellFlow
+
+[![DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/longcipher/shellflow)
+[![Context7](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com/longcipher/shellflow)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/shellflow.svg)](https://pypi.org/project/shellflow/)
+
+![shellflow](https://socialify.git.ci/longcipher/shellflow/image?font=Source+Code+Pro&language=1&name=1&owner=1&pattern=Circuit+Board&theme=Auto)
+
+ShellFlow is a minimal shell script orchestrator for mixed local and remote execution. You write one shell script, mark execution boundaries with comments, and ShellFlow runs each block in order while resolving remote targets from your SSH configuration.
+
+![shellflow-run](assets/shellflow-run.png)
+
+## What It Does
+
+- Split a shell script into `@LOCAL` and `@REMOTE` execution blocks.
+- Run each block fail-fast, in order.
+- Reuse the shared prelude before the first marker for every block.
+- Pass the previous block output forward as `SHELLFLOW_LAST_OUTPUT`.
+- Resolve remote targets from `~/.ssh/config` or a custom SSH config path.
+
+## Quick Start
+
+```bash
+git clone https://github.com/longcipher/shellflow.git
+cd shellflow
+uv sync --all-groups # uv sync --refresh --reinstall --no-cache
+uv tool install --force --reinstall --refresh --no-cache .
+
+shellflow run playbooks/hello.sh
+```
+
+If you do not want a global tool install, use `uv run shellflow run playbooks/hello.sh`.
+
+## Installation
+
+### Development checkout
+
+```bash
+git clone https://github.com/longcipher/shellflow.git
+cd shellflow
+uv sync --all-groups # uv sync --refresh --reinstall --no-cache
+```
+
+### Install as a local tool
+
+```bash
+uv tool install --force .
+shellflow --version
+```
+
+### Install into the active environment
+
+```bash
+uv pip install -e .
+shellflow --version
+```
+
+## Script Format
+
+Shellflow recognizes two markers:
+
+- `# @LOCAL`
+- `# @REMOTE <ssh-host>`
+
+`<ssh-host>` must match a `Host` entry in your SSH config. Shellflow then connects using that SSH host definition, which means the actual machine can be resolved through the configured `HostName`, `User`, `Port`, and `IdentityFile` values.
+
+Example:
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+# @LOCAL
+echo "runs locally"
+
+# @REMOTE sui
+uname -a
+
+# @LOCAL
+echo "remote output: $SHELLFLOW_LAST_OUTPUT"
+```
+
+## SSH Configuration
+
+Example `~/.ssh/config` entry:
+
+```sshconfig
+Host sui
+    HostName 192.168.1.100
+    User deploy
+    Port 22
+    IdentityFile ~/.ssh/id_ed25519
+```
+
+With that config, this block is valid:
+
+```bash
+# @REMOTE sui
+hostname
+```
+
+This is intentional:
+
+- Shellflow accepts configured SSH host names, not arbitrary free-form targets.
+- Unknown remote targets fail early with a clear error before spawning `ssh`.
+- You can override the default config path with `--ssh-config`.
+
+## Execution Model
+
+Each block runs in a fresh shell.
+
+- Shell options from the prelude are copied into every block.
+- Shell state like `cd`, shell variables, aliases, and `export` commands does not persist across blocks.
+- Explicit context values are passed forward through environment variables.
+
+Example:
+
+```bash
+# @LOCAL
+echo "build-123"
+
+# @LOCAL
+echo "last output = $SHELLFLOW_LAST_OUTPUT"
+```
+
+Lines before the first marker are treated as a shared prelude and prepended to every executable block:
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+# @LOCAL
+echo "prelude is active"
+
+# @REMOTE sui
+echo "prelude is also active here"
+```
+
+## CLI
+
+```text
+shellflow run <script>
+shellflow run <script> --verbose
+shellflow run <script> --ssh-config ./ssh_config
+shellflow --version
+```
+
+Examples:
+
+```bash
+shellflow run playbooks/hello.sh
+shellflow run playbooks/hello.sh -v
+shellflow run playbooks/hello.sh --ssh-config ~/.ssh/config.work
+```
+
+## Development
+
+Useful commands:
+
+```bash
+just sync
+just test
+just bdd
+just test-all
+just typecheck
+just build
+just publish
+```
+
+Direct verification commands:
+
+```bash
+uv run pytest -q
+uv run behave features
+uv run ruff check .
+uv run ty check src tests
+uv build
+```
+
+## Release Process
+
+Shellflow supports both local publishing and GitHub Actions release publishing.
+
+### Local publish
+
+```bash
+just publish
+```
+
+`uv publish` uses standard `uv` authentication mechanisms such as `UV_PUBLISH_TOKEN`, or PyPI trusted publishing when supported by the environment.
+
+### GitHub Actions publish on tag push
+
+The repository includes:
+
+- `.github/workflows/ci.yml` for lint, type-check, test, and build verification.
+- `.github/workflows/release.yml` for publishing to PyPI when a tag like `v0.1.0` is pushed.
+
+Recommended release flow:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+To use trusted publishing with PyPI:
+
+1. Create a `pypi` environment in GitHub repository settings.
+2. Add this repository as a trusted publisher in the PyPI project settings.
+3. Push a `v*` tag.
+
+The release workflow then runs verification, builds distributions with `uv build`, and uploads them with `uv publish`.
+
+## Project Layout
+
+```text
+shellflow/
+├── src/shellflow.py
+├── tests/
+├── features/
+├── playbooks/
+├── pyproject.toml
+├── Justfile
+└── README.md
+```
+
+## License
+
+Apache-2.0