shellflow 0.1.1__tar.gz → 0.2.0__tar.gz

{shellflow-0.1.1 → 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.1 → shellflow-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellflow
-Version: 0.1.1
+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,6 +42,10 @@ 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
@@ -102,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:
@@ -111,6 +123,7 @@ Example:
 set -euo pipefail
 
 # @LOCAL
+# @EXPORT VERSION=stdout
 echo "runs locally"
 
 # @REMOTE sui
@@ -118,6 +131,7 @@ uname -a
 
 # @LOCAL
 echo "remote output: $SHELLFLOW_LAST_OUTPUT"
+echo "version = $VERSION"
 ```
 
 ## SSH Configuration
@@ -163,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
@@ -176,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
 ```
@@ -190,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.1 → 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,6 +20,10 @@ 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
@@ -80,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:
@@ -89,6 +101,7 @@ Example:
 set -euo pipefail
 
 # @LOCAL
+# @EXPORT VERSION=stdout
 echo "runs locally"
 
 # @REMOTE sui
@@ -96,6 +109,7 @@ uname -a
 
 # @LOCAL
 echo "remote output: $SHELLFLOW_LAST_OUTPUT"
+echo "version = $VERSION"
 ```
 
 ## SSH Configuration
@@ -141,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
@@ -154,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
 ```
@@ -168,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
 ```
 

{shellflow-0.1.1 → shellflow-0.2.0}/SKILL.md

@@ -114,7 +114,60 @@ pwd
 
 Why it is bad: the `cd /srv/app` line becomes part of every block, including remote blocks.
 
-## 4. Assume every block runs in a fresh shell
+## 4. Use block directives for timeout, retry, and exports
+
+Block directives must appear immediately after the `# @LOCAL` or `# @REMOTE <host>` marker, before any command lines. They configure execution behavior for that specific block.
+
+### Timeout Directive
+
+`# @TIMEOUT <seconds>` - Abort the block if it exceeds the specified duration.
+
+```bash
+# @LOCAL
+# @TIMEOUT 30
+sleep 60
+```
+
+### Retry Directive
+
+`# @RETRY <count>` - Retry the block up to N times on failure (0 means no retry).
+
+```bash
+# @LOCAL
+# @RETRY 3
+curl -f https://api.example.com/health
+```
+
+### Export Directive
+
+`# @EXPORT NAME=source` - Capture a value from the block result and pass it to subsequent blocks as an environment variable.
+
+Valid sources:
+
+- `stdout` - The block's standard output
+- `stderr` - The block's standard error
+- `output` - Combined stdout and stderr
+- `exit_code` - The block's exit code (as string)
+
+```bash
+# @LOCAL
+# @EXPORT BUILD_ID=stdout
+echo "build-$(date +%s)"
+
+# @LOCAL
+echo "Building: $BUILD_ID"
+```
+
+You can use multiple exports in a single block:
+
+```bash
+# @LOCAL
+# @EXPORT STATUS_CODE=exit_code
+# @EXPORT RESPONSE=stdout
+curl -s -w "%{http_code}" -o response.txt https://api.example.com
+```
+
+## 5. Assume every block runs in a fresh shell
 
 Each block is isolated.
 
@@ -158,7 +211,7 @@ pwd
 
 Why it is bad: `artifact` and the working directory do not persist.
 
-## 5. Use SHELLFLOW_LAST_OUTPUT for explicit handoff
+## 6. Use SHELLFLOW_LAST_OUTPUT for explicit handoff
 
 Shellflow passes the previous block's combined output into the next block as `SHELLFLOW_LAST_OUTPUT`.
 
@@ -197,7 +250,7 @@ print(payload["release"])
 PY
 ```
 
-## 6. Use SSH config host aliases, not ad-hoc targets
+## 7. Use SSH config host aliases, not ad-hoc targets
 
 `# @REMOTE <ssh-host>` should point to a host that resolves through SSH config.
 
@@ -210,7 +263,7 @@ Avoid assuming Shellflow accepts any arbitrary free-form destination unless it i
 
 If a remote host is unknown, Shellflow fails before execution.
 
-## 7. Keep blocks self-contained and fail-fast
+## 8. Keep blocks self-contained and fail-fast
 
 Shellflow runs blocks in order and stops on the first failure.
 
@@ -243,17 +296,69 @@ docker compose up -d
 
 Why: the second block cannot rely on the first block's `cd`.
 
+## 9. CLI Options and Output Modes
+
+Shellflow provides several CLI options for different use cases:
+
+### Basic Options
+
+```bash
+shellflow run script.sh              # Run a script
+shellflow run script.sh -v          # Run with verbose output
+shellflow run script.sh --dry-run   # Preview execution plan without running
+```
+
+### Structured Output
+
+```bash
+shellflow run script.sh --json       # Single JSON report
+shellflow run script.sh --jsonl       # Streaming JSON Lines events
+```
+
+- `--json`: Outputs a single JSON object with the complete run report
+- `--jsonl`: Outputs one JSON object per event (run_started, block_started, block_finished, run_finished)
+
+### Execution Control
+
+```bash
+shellflow run script.sh --no-input   # Non-interactive mode (stdin closed)
+shellflow run script.sh --ssh-config /path/to/config  # Custom SSH config
+```
+
+- `--no-input`: Closes stdin before running blocks; useful for automation
+- `--ssh-config`: Override the default SSH config path (`~/.ssh/config`)
+
+### Audit Logging
+
+```bash
+shellflow run script.sh --audit-log audit.jsonl --jsonl
+```
+
+The `--audit-log` option writes redacted JSON Lines events to a file. Secret-like exports (containing TOKEN, SECRET, or PASSWORD in the name) are automatically redacted to `[REDACTED]`.
+
+## 10. Exit Codes
+
+Shellflow returns distinct exit codes for different failure types:
+
+- `0`: Success
+- `1`: General execution failure
+- `2`: Parse failure (invalid script syntax)
+- `3`: SSH config failure (host not found)
+- `4`: Timeout failure (block exceeded timeout)
+
 ## Authoring Checklist
 
 Before returning a Shellflow playbook, verify that:
 
 - The script is valid bash without custom DSL syntax.
-- Only `# @LOCAL` and `# @REMOTE <host>` are used.
+- Only `# @LOCAL`, `# @REMOTE <host>`, and block directives (`# @TIMEOUT`, `# @RETRY`, `# @EXPORT`) are used.
+- Block directives appear immediately after the block marker, before any commands.
 - Anything before the first marker is safe to repeat for every block.
 - Every block can run independently in a fresh shell.
-- Cross-block data uses `SHELLFLOW_LAST_OUTPUT` explicitly.
+- Cross-block data uses `SHELLFLOW_LAST_OUTPUT` or `@EXPORT` explicitly.
 - Remote targets match the intended SSH host aliases.
 - Commands that should happen once are not accidentally placed in the shared prelude.
+- Export sources are valid (stdout, stderr, output, exit_code).
 
 ## Reference Example
 
@@ -266,20 +371,25 @@ log() {
 }
 
 # @LOCAL
+# @EXPORT BUILD_ID=stdout
 log "building artifact"
-artifact="$(mktemp /tmp/shellflow-release.XXXXXX)"
-printf 'release-%s\n' "$(date +%Y%m%d%H%M%S)" > "$artifact"
-echo "$artifact"
+build_id="build-$(date +%Y%m%d%H%M%S)"
+echo "$build_id"
+
+# @LOCAL
+# @TIMEOUT 60
+# @RETRY 2
+log "deploying to staging"
+echo "Deploying $BUILD_ID to staging"
 
 # @REMOTE staging
-cd /srv/app
-artifact_path="$SHELLFLOW_LAST_OUTPUT"
-log "receiving artifact path $artifact_path"
-test -n "$artifact_path"
-uname -a
+# @EXPORT DEPLOYED_HOST=stdout
+log "receiving deployment"
+hostname
 
 # @LOCAL
-log "remote said: $SHELLFLOW_LAST_OUTPUT"
+log "deployed to: $DEPLOYED_HOST"
+log "build $BUILD_ID complete"
 ```
 
 ## Common Mistakes
@@ -287,6 +397,10 @@ log "remote said: $SHELLFLOW_LAST_OUTPUT"
 - Putting one-time commands before the first marker, then being surprised when they run for every block.
 - Expecting `cd`, `export`, or local shell variables from one block to exist in the next block.
 - Using an undefined remote host alias.
-- Printing extra debug output from a block whose output is consumed by the next block.
+- Placing block directives after commands instead of immediately after the marker.
+- Using invalid export sources (not stdout, stderr, output, or exit_code).
+- Forgetting that `@RETRY 0` means no retry attempts.
+- Using `@TIMEOUT` with values too small for normal operation.
+- Printing extra debug output from a block whose output is consumed by the next block via `@EXPORT`.
 - Forgetting to quote `"$SHELLFLOW_LAST_OUTPUT"`.
 - Treating Shellflow as a persistent session instead of sequential isolated shells.

shellflow-0.2.0/features/execution_contract.feature

@@ -0,0 +1,29 @@
+Feature: Agent-facing execution contract
+  As an AI agent operating Shellflow
+  I want structured execution results and stable exit codes
+  So that I can observe outcomes and decide what to do next outside Shellflow
+
+  Scenario: JSON report mode returns machine-readable run and block results
+    Given a script file with a local block that prints a release version
+    When I run the script with JSON output enabled
+    Then the command should succeed
+    And the JSON output should contain a run id
+    And the JSON output should contain a schema version
+    And the JSON output should include the first block exit code
+    And the JSON output should include the first block stdout separately from stderr
+
+  Scenario: JSONL mode emits ordered events suitable for live observation
+    Given a script file with two local blocks that both succeed
+    When I run the script with JSON Lines output enabled
+    Then the command should succeed
+    And the output should contain a run_started event before a block_started event
+    And the output should contain a block_finished event for each block
+    And the output should end with a run_finished event
+
+  Scenario: Exit codes distinguish parse, SSH config, runtime, and timeout failures
+    Given the relevant failing scripts for parse, missing SSH host, block failure, and timeout
+    When I run each script in machine-readable mode
+    Then the parse failure should exit with code 2
+    And the missing SSH host failure should exit with code 3
+    And the block execution failure should exit with code 1
+    And the timeout failure should exit with code 4

shellflow-0.2.0/features/resilience_and_context.feature

@@ -0,0 +1,24 @@
+Feature: Resilience and context propagation
+  As an AI agent using Shellflow as an action tool
+  I want bounded retries, timeouts, and named exports
+  So that I can recover from transient failures without turning Shellflow into a workflow engine
+
+  Scenario: Timeout stops a stuck block and reports a timeout-specific failure
+    Given a script file with a local block that exceeds its timeout directive
+    When I run the script in machine-readable mode
+    Then the command should fail with timeout exit code 4
+    And the structured output should mark the block as timed out
+    And the structured output should record the timeout duration policy
+
+  Scenario: Retry reruns a transiently failing block and reports attempts
+    Given a script file with a local block that fails once and then succeeds with a retry directive
+    When I run the script in machine-readable mode
+    Then the command should succeed
+    And the structured output should record 2 attempts for that block
+    And the structured output should include a retrying event before the successful finish event
+
+  Scenario: Named exports become environment variables for later blocks
+    Given a script file whose first block exports VERSION from stdout
+    When I run the script
+    Then the later block should receive VERSION in its environment
+    And SHELLFLOW_LAST_OUTPUT should still be available

shellflow-0.2.0/features/safety_controls.feature

@@ -0,0 +1,24 @@
+Feature: Safety controls for automated runs
+  As an operator delegating execution to an AI agent
+  I want non-interactive and audit-friendly controls
+  So that automated runs are observable without relying on shell heuristics
+
+  Scenario: No-input prevents blocking on stdin
+    Given a script file with a local block that reads from standard input
+    When I run the script with no-input enabled
+    Then the command should fail deterministically instead of waiting for input
+    And the structured output should indicate that no interactive input was available
+
+  Scenario: Dry-run previews execution without running commands
+    Given a script file with local and remote blocks
+    When I run the script in dry-run mode
+    Then no block commands should be executed
+    And the output should describe the planned blocks in order
+    And the output should include structured dry-run events when machine-readable mode is enabled
+
+  Scenario: Audit-log writes structured events for later inspection
+    Given a script file with a named export that looks like a secret
+    When I run the script with an audit log path
+    Then the command should succeed
+    And the audit log file should contain JSON Lines events
+    And the audit log should redact the secret-like exported value