@syntax-syllogism/flow-delta 0.5.0 → 0.5.1

package/README.md

@@ -1,9 +1,14 @@
 # FlowDelta
 
-A semantic, visual diff for Salesforce Flows: parse two versions of a
-`.flow-meta.xml`, diff them by stable node name, and render a self-contained
-interactive HTML artifact (plus `diff.json`) that shows added / deleted /
-modified / unchanged nodes and edges with per-property deltas.
+<img width="1638" height="1392" alt="Screencast Demo" src="https://github.com/user-attachments/assets/b3f5f248-485a-4f62-9955-805a1b57186b" />
+
+[![npm](https://img.shields.io/npm/v/@syntax-syllogism/flow-delta.svg)](https://www.npmjs.com/package/@syntax-syllogism/flow-delta)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Stop reviewing Salesforce Flow changes as raw XML.** FlowDelta parses two
+versions of a `.flow-meta.xml`, diffs them by stable node name, and renders a
+self-contained interactive HTML artifact (plus `diff.json`) that shows added /
+deleted / modified / unchanged nodes and edges with per-property deltas.
 
 Inspired by Google's [Flow Lens](https://github.com/google/flow-lens), with a
 focus on CI review workflows for GitLab merge requests and GitHub pull requests.
@@ -12,21 +17,44 @@ We also opted for our own HTML output over plantuml, graphviz, or mermaid.
 - [Sample GitLab project with artifacts](https://gitlab.com/j.p.richter/flow-delta-example/-/merge_requests/)
 - [Sample GitHub project with artifacts](https://github.com/Syntax-Syllogism/flow-delta-example/pulls)
 
+## Quick Start
+
+No install required:
+
+```bash
+npx @syntax-syllogism/flow-delta --old before.flow-meta.xml --new after.flow-meta.xml --out ./flow-delta-out
+```
+
+Open the generated `.html` file in a browser to see the interactive diff
+shown above.
+
+Prefer a permanent install?
+
+```bash
+npm install -g @syntax-syllogism/flow-delta
+flow-delta --old before.flow-meta.xml --new after.flow-meta.xml --out ./flow-delta-out
+```
+
 ## Usage
 
-Runs as a TypeScript CLI via `tsx` (no build step). See [docs/cli.md](docs/cli.md)
-for full file-mode and git-mode options.
+See [docs/cli.md](docs/cli.md) for full file-mode and git-mode options.
 
 ```bash
-npx tsx src/cli.ts --old before.flow-meta.xml --new after.flow-meta.xml --out ./flow-delta-out --json
+# File mode — compare two local files
+npx @syntax-syllogism/flow-delta --old before.flow-meta.xml --new after.flow-meta.xml --out ./flow-delta-out --json
+
+# Git mode — compare two refs in a repo
+npx @syntax-syllogism/flow-delta --repo /path/to/sfdx-repo --from main --to feature-branch --path 'force-app/**/*.flow-meta.xml' --out ./flow-delta-out
 ```
 
 CI reporters read the generated `flow-delta-out/*.diff.json` files and post a
-sticky review comment:
+sticky review comment. Install the package first (these binaries don't map
+1:1 to the package name, so plain `npx` won't resolve them):
 
 ```bash
-flow-delta-gitlab --in flow-delta-out
-flow-delta-github --in flow-delta-out
+npm install @syntax-syllogism/flow-delta
+npx flow-delta-gitlab --in flow-delta-out
+npx flow-delta-github --in flow-delta-out
 ```
 
 The GitHub reporter can also consume `--artifact-urls <manifest.json>` for
@@ -36,10 +64,14 @@ recipes, private-repo artifact viewing, and smoke harnesses.
 
 ## Development
 
+Working from a clone of this repo? Runs as a TypeScript CLI via `tsx`, no
+build step:
+
 ```bash
 npm install
 npm test                 # parser + semantic diff / render / CLI suites
 npm run render:fixtures  # render every diff fixture to flow-delta-out/fixtures/
+npx tsx src/cli.ts --old before.flow-meta.xml --new after.flow-meta.xml --out ./flow-delta-out --json
 ```
 
 Architecture, testing, and the vendored-parser policy are documented in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syntax-syllogism/flow-delta",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "description": "Semantic visual diff for Salesforce Flows",
   "license": "MIT",