shellflow 0.1.0__tar.gz → 0.2.0__tar.gz

{shellflow-0.1.0 → shellflow-0.2.0}/.gitignore

@@ -41,3 +41,5 @@ Thumbs.db
 .env
 .env.local
 .rumdl_cache/
+.benchmarks/
+.hypothesis/

shellflow-0.2.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+## [0.2.0] - 2026-03-15
+
+### Features
+
+- Introduce agent-native execution contract and resilience features
+- Update SKILL.md with changes to block directives and execution behavior guidelines
+
+<!-- generated by git-cliff -->

{shellflow-0.1.0 → shellflow-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellflow
-Version: 0.1.0
+Version: 0.2.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
@@ -22,6 +22,8 @@ Description-Content-Type: text/markdown
 
 # ShellFlow
 
+> AI agent native DevOps bash script orchestrator.
+
 [![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/)
@@ -40,23 +42,43 @@ ShellFlow is a minimal shell script orchestrator for mixed local and remote exec
 - 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`.
+- Export named scalar values from a block into later block environments.
+- Emit either a final JSON report or streaming JSON Lines events for agents.
+- Support bounded `@TIMEOUT` and `@RETRY` directives without embedding workflow logic.
+- Provide non-interactive, dry-run, and audit-log modes for automated execution.
 - 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 .
+uv tool install shellflow
 
 shellflow run playbooks/hello.sh
 ```
 
-If you do not want a global tool install, use `uv run shellflow run playbooks/hello.sh`.
-
 ## Installation
 
+### User installation (from PyPI)
+
+```bash
+uv tool install shellflow
+shellflow --version
+```
+
+### Install Skill
+
+```bash
+npx skills add longcipher/shellflow
+```
+
+This installs the agent skill from this repository for writing and reviewing Shellflow playbooks.
+
+To upgrade to the latest version:
+
+```bash
+uv tool upgrade shellflow
+```
+
 ### Development checkout
 
 ```bash
@@ -65,14 +87,14 @@ cd shellflow
 uv sync --all-groups # uv sync --refresh --reinstall --no-cache
 ```
 
-### Install as a local tool
+### Install as a local tool (from source)
 
 ```bash
 uv tool install --force .
 shellflow --version
 ```
 
-### Install into the active environment
+### Install into the active environment (from source)
 
 ```bash
 uv pip install -e .
@@ -86,6 +108,12 @@ Shellflow recognizes two markers:
 - `# @LOCAL`
 - `# @REMOTE <ssh-host>`
 
+Shellflow also recognizes bounded block directives at the top of a block body:
+
+- `# @TIMEOUT <seconds>`
+- `# @RETRY <count>`
+- `# @EXPORT NAME=stdout|stderr|output|exit_code`
+
 `<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:
@@ -95,6 +123,7 @@ Example:
 set -euo pipefail
 
 # @LOCAL
+# @EXPORT VERSION=stdout
 echo "runs locally"
 
 # @REMOTE sui
@@ -102,6 +131,7 @@ uname -a
 
 # @LOCAL
 echo "remote output: $SHELLFLOW_LAST_OUTPUT"
+echo "version = $VERSION"
 ```
 
 ## SSH Configuration
@@ -147,6 +177,18 @@ echo "build-123"
 echo "last output = $SHELLFLOW_LAST_OUTPUT"
 ```
 
+Named exports are additive to `SHELLFLOW_LAST_OUTPUT`:
+
+```bash
+# @LOCAL
+# @EXPORT VERSION=stdout
+echo "2026.03.15"
+
+# @REMOTE sui
+echo "deploying $VERSION"
+echo "last output = $SHELLFLOW_LAST_OUTPUT"
+```
+
 Lines before the first marker are treated as a shared prelude and prepended to every executable block:
 
 ```bash
@@ -160,11 +202,41 @@ echo "prelude is active"
 echo "prelude is also active here"
 ```
 
+## Agent-Native Usage
+
+Shellflow is designed to be the execution substrate for an outer agent, not an embedded planner.
+
+- Use `--json` when you want one final machine-readable run report.
+- Use `--jsonl` when you want ordered event records while the script runs.
+- Use `--no-input` for CI or agent runs where interactive prompts must fail deterministically.
+- Use `--dry-run` to preview planned execution without running commands.
+- Use `--audit-log <path>` to mirror the structured event stream into a redacted JSONL file.
+
+Recommended agent flow:
+
+1. Generate or select a plain shell script with `@LOCAL` and `@REMOTE` markers.
+2. Add bounded directives only where needed: `@TIMEOUT`, `@RETRY`, and `@EXPORT`.
+3. Run with `--json` or `--jsonl`.
+4. Let the outer agent decide whether to retry, branch, or stop based on Shellflow's structured result.
+
+Shellflow intentionally does not provide:
+
+- Conditional directives such as `@IF stdout_contains=...`
+- A workflow DSL or embedded ReAct loop
+- Heuristic destructive-command detection
+
+Those decisions belong in the outer agent or automation layer.
+
 ## CLI
 
 ```text
 shellflow run <script>
 shellflow run <script> --verbose
+shellflow run <script> --json
+shellflow run <script> --jsonl
+shellflow run <script> --no-input
+shellflow run <script> --dry-run
+shellflow run <script> --audit-log ./audit.jsonl --jsonl
 shellflow run <script> --ssh-config ./ssh_config
 shellflow --version
 ```
@@ -174,6 +246,10 @@ Examples:
 ```bash
 shellflow run playbooks/hello.sh
 shellflow run playbooks/hello.sh -v
+shellflow run playbooks/hello.sh --json
+shellflow run playbooks/hello.sh --jsonl --no-input
+shellflow run playbooks/hello.sh --dry-run --jsonl
+shellflow run playbooks/hello.sh --audit-log ./audit.jsonl --jsonl
 shellflow run playbooks/hello.sh --ssh-config ~/.ssh/config.work
 ```
 

{shellflow-0.1.0 → shellflow-0.2.0}/README.md

@@ -1,5 +1,7 @@
 # ShellFlow
 
+> AI agent native DevOps bash script orchestrator.
+
 [![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/)
@@ -18,23 +20,43 @@ ShellFlow is a minimal shell script orchestrator for mixed local and remote exec
 - 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`.
+- Export named scalar values from a block into later block environments.
+- Emit either a final JSON report or streaming JSON Lines events for agents.
+- Support bounded `@TIMEOUT` and `@RETRY` directives without embedding workflow logic.
+- Provide non-interactive, dry-run, and audit-log modes for automated execution.
 - 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 .
+uv tool install shellflow
 
 shellflow run playbooks/hello.sh
 ```
 
-If you do not want a global tool install, use `uv run shellflow run playbooks/hello.sh`.
-
 ## Installation
 
+### User installation (from PyPI)
+
+```bash
+uv tool install shellflow
+shellflow --version
+```
+
+### Install Skill
+
+```bash
+npx skills add longcipher/shellflow
+```
+
+This installs the agent skill from this repository for writing and reviewing Shellflow playbooks.
+
+To upgrade to the latest version:
+
+```bash
+uv tool upgrade shellflow
+```
+
 ### Development checkout
 
 ```bash
@@ -43,14 +65,14 @@ cd shellflow
 uv sync --all-groups # uv sync --refresh --reinstall --no-cache
 ```
 
-### Install as a local tool
+### Install as a local tool (from source)
 
 ```bash
 uv tool install --force .
 shellflow --version
 ```
 
-### Install into the active environment
+### Install into the active environment (from source)
 
 ```bash
 uv pip install -e .
@@ -64,6 +86,12 @@ Shellflow recognizes two markers:
 - `# @LOCAL`
 - `# @REMOTE <ssh-host>`
 
+Shellflow also recognizes bounded block directives at the top of a block body:
+
+- `# @TIMEOUT <seconds>`
+- `# @RETRY <count>`
+- `# @EXPORT NAME=stdout|stderr|output|exit_code`
+
 `<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:
@@ -73,6 +101,7 @@ Example:
 set -euo pipefail
 
 # @LOCAL
+# @EXPORT VERSION=stdout
 echo "runs locally"
 
 # @REMOTE sui
@@ -80,6 +109,7 @@ uname -a
 
 # @LOCAL
 echo "remote output: $SHELLFLOW_LAST_OUTPUT"
+echo "version = $VERSION"
 ```
 
 ## SSH Configuration
@@ -125,6 +155,18 @@ echo "build-123"
 echo "last output = $SHELLFLOW_LAST_OUTPUT"
 ```
 
+Named exports are additive to `SHELLFLOW_LAST_OUTPUT`:
+
+```bash
+# @LOCAL
+# @EXPORT VERSION=stdout
+echo "2026.03.15"
+
+# @REMOTE sui
+echo "deploying $VERSION"
+echo "last output = $SHELLFLOW_LAST_OUTPUT"
+```
+
 Lines before the first marker are treated as a shared prelude and prepended to every executable block:
 
 ```bash
@@ -138,11 +180,41 @@ echo "prelude is active"
 echo "prelude is also active here"
 ```
 
+## Agent-Native Usage
+
+Shellflow is designed to be the execution substrate for an outer agent, not an embedded planner.
+
+- Use `--json` when you want one final machine-readable run report.
+- Use `--jsonl` when you want ordered event records while the script runs.
+- Use `--no-input` for CI or agent runs where interactive prompts must fail deterministically.
+- Use `--dry-run` to preview planned execution without running commands.
+- Use `--audit-log <path>` to mirror the structured event stream into a redacted JSONL file.
+
+Recommended agent flow:
+
+1. Generate or select a plain shell script with `@LOCAL` and `@REMOTE` markers.
+2. Add bounded directives only where needed: `@TIMEOUT`, `@RETRY`, and `@EXPORT`.
+3. Run with `--json` or `--jsonl`.
+4. Let the outer agent decide whether to retry, branch, or stop based on Shellflow's structured result.
+
+Shellflow intentionally does not provide:
+
+- Conditional directives such as `@IF stdout_contains=...`
+- A workflow DSL or embedded ReAct loop
+- Heuristic destructive-command detection
+
+Those decisions belong in the outer agent or automation layer.
+
 ## CLI
 
 ```text
 shellflow run <script>
 shellflow run <script> --verbose
+shellflow run <script> --json
+shellflow run <script> --jsonl
+shellflow run <script> --no-input
+shellflow run <script> --dry-run
+shellflow run <script> --audit-log ./audit.jsonl --jsonl
 shellflow run <script> --ssh-config ./ssh_config
 shellflow --version
 ```
@@ -152,6 +224,10 @@ Examples:
 ```bash
 shellflow run playbooks/hello.sh
 shellflow run playbooks/hello.sh -v
+shellflow run playbooks/hello.sh --json
+shellflow run playbooks/hello.sh --jsonl --no-input
+shellflow run playbooks/hello.sh --dry-run --jsonl
+shellflow run playbooks/hello.sh --audit-log ./audit.jsonl --jsonl
 shellflow run playbooks/hello.sh --ssh-config ~/.ssh/config.work
 ```