sfn-diagram 1.7.0 → 1.9.0

package/README.md

@@ -6,10 +6,12 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Docs](https://img.shields.io/badge/docs-sfn.yusufaf.dev-brightgreen)](https://sfn.yusufaf.dev)
 
-Generate diagrams from AWS Step Functions ASL (Amazon States Language) definitions, CloudFormation/SAM/CDK templates, or live AWS state machines. Outputs SVG, Mermaid, standalone HTML, and PNG.
+Generate diagrams from AWS Step Functions ASL (Amazon States Language) definitions, CloudFormation/SAM/CDK templates, Terraform configs, or live AWS state machines. Outputs SVG, Mermaid, standalone HTML, and PNG.
 
 **📖 [Documentation](https://sfn.yusufaf.dev)** · **▶ [Live playground](https://sfn.yusufaf.dev/playground/)** — paste any ASL definition and preview the diagram instantly, no install required.
 
+**Use it as:** [CLI & Node library](https://www.npmjs.com/package/sfn-diagram) · VS Code extension ([Marketplace](https://marketplace.visualstudio.com/items?itemName=yusufaf.vscode-sfn-diagram) · [Open VSX](https://open-vsx.org/extension/yusufaf/vscode-sfn-diagram)) · [GitHub Action](https://github.com/marketplace/actions/step-functions-diagram-preview) · [React component](https://www.npmjs.com/package/sfn-diagram-react)
+
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/images/parallel-dark.svg">
   <img src="docs/images/parallel-light.svg" alt="Example diagram of a Parallel state Step Functions workflow generated by sfn-diagram" width="410">
@@ -27,7 +29,7 @@ The core package pulls in **no browser engine or native rasterizer** — SVG and
 npm install sfn-diagram @resvg/resvg-js
 ```
 
-Not a Node project? The CLI also ships as standalone binaries for Linux, macOS, and Windows on every [release](https://github.com/yusufaf/sfn-diagram/releases), or via Homebrew (`brew install yusufaf/tap/sfn-diagram`), and as a [Docker image](https://sfn.yusufaf.dev/guides/cli/#docker). See [using sfn-diagram from other languages](https://sfn.yusufaf.dev/guides/other-languages/).
+Not a Node project? The CLI also ships as standalone binaries for Linux, macOS, and Windows, attached to every core release from v1.6.0 on ([download](https://sfn.yusufaf.dev/installation/#cli-without-node)), or via Homebrew (`brew install yusufaf/tap/sfn-diagram`), and as a [Docker image](https://sfn.yusufaf.dev/guides/cli/#docker). See [using sfn-diagram from other languages](https://sfn.yusufaf.dev/guides/other-languages/).
 
 ## Quick start
 
@@ -61,7 +63,7 @@ There's no shortage of ways to look at a state machine — this is where sfn-dia
 
 | | **sfn-diagram** | AWS Console visualizer | Mermaid Live Editor |
 |---|---|---|---|
-| Input | ASL, CloudFormation/SAM/CDK templates, live AWS state machines | Deployed state machine only | Manual Mermaid you write by hand |
+| Input | ASL, CloudFormation/SAM/CDK templates, Terraform configs, live AWS state machines | Deployed state machine only | Manual Mermaid you write by hand |
 | Output | SVG, Mermaid, PNG, interactive HTML | Static graph in-browser | Mermaid diagram only |
 | CI / PR integration | [GitHub Action](https://sfn.yusufaf.dev/ecosystem/github-action/) or [GitLab CI](https://sfn.yusufaf.dev/ecosystem/gitlab/) posts a diff overlay on every PR/MR that touches ASL | None | None |
 | Execution overlays | Paints a real run's path/status/duration onto the diagram | Basic per-execution highlighting, console-only | Not applicable |
@@ -70,21 +72,62 @@ There's no shortage of ways to look at a state machine — this is where sfn-dia
 
 In short: reach for the AWS Console visualizer to eyeball a state machine you already deployed, reach for Mermaid Live if you're hand-drawing a diagram from scratch — reach for sfn-diagram when you want diagrams generated automatically from your actual definition, checked into CI, and diffed on every pull request.
 
+## Command line
+
+Render what is actually deployed, with `--from-aws`:
+
+```bash
+pnpm add @aws-sdk/client-sfn   # optional peer, only needed for --from-aws
+sfn-diagram --from-aws arn:aws:states:us-east-1:111122223333:stateMachine:Orders -o live.svg
+```
+
+The region comes from the ARN and credentials from the AWS SDK's default chain, so
+`AWS_PROFILE`, SSO and instance roles work as they do for the AWS CLI. The flag takes a
+state machine, version or alias ARN — not a bare name — is repeatable with `--out-dir`,
+and combines with `--diff` (whose baseline may itself be an ARN, for live-against-live
+drift), `--execution` and `--check`. It needs the optional peer above, so it is
+unavailable in the [standalone binary](https://sfn.yusufaf.dev/guides/cli/#standalone-binary).
+See [Rendering a live state machine](https://sfn.yusufaf.dev/guides/cli/#rendering-a-live-state-machine).
+
+`--scale` raises PNG resolution without changing the layout; see
+[PNG resolution and fonts](https://sfn.yusufaf.dev/guides/cli/#png-resolution-and-fonts)
+for the font options.
+
+```bash
+sfn-diagram my-workflow.asl.json --format png --scale 2 -o diagram@2x.png
+```
+
+An HTML document inlines every state's raw ASL for its detail panel. `--redact-fields`
+replaces the named fields with `[redacted]`, and `--no-raw-state` replaces every state's;
+see [Redacting the HTML document](https://sfn.yusufaf.dev/guides/cli/#redacting-the-html-document)
+for what they don't cover.
+
+```bash
+sfn-diagram my-workflow.asl.json --format html --redact-fields Parameters,Arguments -o share.html
+```
+
+The CLI exits `0` on success, `1` when something goes wrong while running — including a failed
+AWS call — and `2` when the invocation itself was wrong, so a CI job can tell a bad flag
+from a bad definition. See
+[Exit codes](https://sfn.yusufaf.dev/guides/cli/#exit-codes).
+
 ## Features
 
-- **Multiple Output Formats**: SVG (D3.js), Mermaid syntax, and PNG
+- **Multiple Output Formats**: SVG, Mermaid syntax, a self-contained interactive HTML viewer, and PNG
 - **Automatic Layout**: Smart graph positioning using Dagre layout engine
 - **Full ASL Support**: All state types (Pass, Task, Choice, Wait, Succeed, Fail, Parallel, Map), both JSONPath and JSONata query languages, plus `Catch`/`Retry` rendering
 - **Modern ASL**: Variables (`Assign`) shown per state, and Distributed Map rendered distinctly from an inline Map — including its `MaxConcurrency`, `ItemReader` source, and `ResultWriter` sink
 - **Visual Diffing**: Compare two definitions and highlight added / modified / removed states — drives the PR-preview GitHub Action
-- **Execution Overlays**: Paint a real execution's history onto the diagram — succeeded/failed/caught/not-reached states, the taken path, and per-state duration & retry counts
-- **Customizable Themes**: AWS light/dark themes plus custom theme support
+- **Linting**: `lintAsl()` returns every structural and semantic finding at once (unreachable states, dangling transitions, `End` with `Next`, JSONPath/JSONata field mixing, …); `sfn-diagram --check` fails CI on errors
+- **Execution Overlays**: Paint a real execution's history onto the diagram — succeeded/failed/caught/not-reached states, the taken path, and per-state duration & retry counts. From a saved history file or live from an execution ARN, and `--follow` keeps re-rendering until the run finishes; with `--format html` it can be painted onto a `--diff` in the same viewer
+- **Customizable Themes**: AWS light/dark themes, an `auto` theme that follows the system colour scheme, plus custom theme support
 - **Flexible Layouts**: Top-bottom, left-right, right-left, bottom-top
 - **Type-Safe**: Full TypeScript support with comprehensive type definitions
-- **AWS SDK Integration**: Direct integration with AWS Step Functions API
+- **AWS SDK Integration**: Direct integration with AWS Step Functions API, from the API (`generateFromAwsResponse`) or the CLI (`--from-aws <arn>`)
 - **Dual APIs**: Function-based and class-based interfaces
 - **Runs Anywhere**: SVG and Mermaid generation has zero platform dependencies — works in Node, the browser, and edge runtimes
 - **Collapse Large Diagrams**: Replace Parallel/Map containers with placeholder nodes before layout so huge diagrams stay readable, with a live toggle in the interactive HTML viewer. See the [configuration guide](https://sfn.yusufaf.dev/guides/configuration/) for `collapse` and every other option.
+- **Layout Cache**: `createLayoutCache()` keeps dagre layouts between renders that don't change geometry, such as a light/dark theme switch, so a long-lived host re-renders a large diagram without laying it out again. Opt-in and bounded; see [Reusing layouts across renders](https://sfn.yusufaf.dev/guides/configuration/#reusing-layouts-across-renders).
 
 ## Supported state types
 
@@ -109,7 +152,7 @@ Full documentation lives at **[sfn.yusufaf.dev](https://sfn.yusufaf.dev)**.
 
 - [Introduction](https://sfn.yusufaf.dev/introduction/) — what it does and how it compares
 - [Quick start](https://sfn.yusufaf.dev/quick-start/) — your first diagram
-- [Command line](https://sfn.yusufaf.dev/guides/cli/) — the `sfn-diagram` CLI, diffs, and execution overlays
+- [Command line](https://sfn.yusufaf.dev/guides/cli/) — the `sfn-diagram` CLI, flags, exit codes, diffs, and execution overlays
 - [Configuration](https://sfn.yusufaf.dev/guides/configuration/) — themes, layouts, edge styles, service icons
 - [Examples](https://sfn.yusufaf.dev/guides/examples/) — complete worked examples
 - [Use with your framework](https://sfn.yusufaf.dev/guides/frameworks/) — Next.js, Remix, SvelteKit, Astro