flecto 4.0.0 → 4.1.0

package/CHANGELOG.md

@@ -7,6 +7,76 @@ The format is based on [Keep a Changelog], and this project adheres to
 
 ## [Unreleased]
 
+## [4.1.0] - 2026-09-29
+
+### Added
+
+- **A root [`action.yml`](action.yml), so the Action can be listed on the GitHub
+  Marketplace.** GitHub only lists an action whose metadata file sits at a public
+  repository's root; Flecto's Actions live in `.github/actions/`, which is why
+  they were never listable. The listed action is `flecto-pr-risk` — the pull
+  request risk comment — with branding and the wedge description.
+
+  `.github/actions/flecto-pr-risk/action.yml` **stays exactly where it is**, so
+  nothing referencing that path changes. The two files' `runs:` blocks are
+  byte-identical and a test enforces it, so a fix to one is a CI failure until it
+  lands in both.
+
+  Docs continue to reference
+  `myselfsiddharth/Flecto/.github/actions/flecto-pr-risk@v4.0.0` until a release
+  carrying the root file exists. The shorter `myselfsiddharth/Flecto@vX.Y.Z` form
+  becomes correct at that point; see [RELEASE.md](RELEASE.md) step 5.
+
+- **`flecto-pr-risk` takes a Terraform plan directly.** A new `terraform-plan`
+  input points at `terraform show -json` output and switches the Action to
+  `flecto plan`, so reviewing a plan on every pull request is two steps:
+
+  ```yaml
+  - run: terraform plan -out=tf.plan && terraform show -json tf.plan > plan.json
+  - uses: myselfsiddharth/Flecto/.github/actions/flecto-pr-risk@v4.0.0
+    with:
+      terraform-plan: plan.json
+      fail-on: error
+  ```
+
+  Because a plan JSON carries its own before and after, **no baseline is resolved
+  and no git history is needed** in this mode — the `fetch-depth: 0` that config
+  mode wants does not apply, and the Action runs on events with no pull request
+  base commit. A missing plan file fails the step rather than letting Flecto
+  report nothing. `targets` is ignored; add a second step without
+  `terraform-plan` to also check config files.
+
+  Config mode is unchanged, including its fail-closed behaviour when no baseline
+  can be resolved. A complete workflow is in
+  [`examples/github-action/flecto-terraform-plan.yml`](examples/github-action/flecto-terraform-plan.yml).
+
+- [docs/stability.md](docs/stability.md): what the public contract covers (the
+  `schema_version: "2.0"` envelope, exit codes, `.flectorc`, the CLI surface),
+  what it deliberately does not, and the deprecation sequence — one minor release
+  carrying a warning before any removal, with security fixes the stated
+  exception.
+
+### Fixed
+
+- **The bundled GitHub Actions installed the pre-4.0 CLI.** `flecto-ci`
+  hardcoded `npx --yes flecto@3` and `flecto-pr-risk` defaulted
+  `flecto-version: "3"`, so both shipped Actions ran the 3.x line after 4.0.0
+  released. Two consequences: `flecto-ci`'s advertised `snapshot-file:` input
+  passed a flag that does not exist before 4.0, and its default
+  `snapshot-ref: HEAD~1` against a 3.x CLI is the baseline-shadowing bypass 4.0
+  closed — a pull request commits a file named `HEAD~1`, it is read instead of
+  the revision, the diff comes back empty and no `--fail-on` value catches it.
+
+  Both now default to `4`. `flecto-ci` gains a `flecto-version` input so the CLI
+  can be pinned without forking, matching `flecto-pr-risk`. A test asserts the
+  floor across both Actions, including hardcoded installs that would bypass the
+  input.
+
+  **If you copied an earlier README example you are affected**: the examples
+  referenced the Actions `@main`, which resolved to a 3.x install. Re-pin to
+  `@v4.0.0` — every example in the README and [docs/ci.md](docs/ci.md) now does,
+  with SHA pinning documented for security-sensitive users.
+
 ## [4.0.0] - 2026-09-23
 
 **A security release.** Every breaking change below exists because a pull
@@ -1222,7 +1292,8 @@ fixed — those runs were never actually gated — but the failure is new.
 - Misconfigured policy packs/plugins cause `watch` to exit non-zero instead of
   continuing with no policies.
 
-[Unreleased]: https://github.com/myselfsiddharth/Flecto/compare/v3.1.0...HEAD
+[Unreleased]: https://github.com/myselfsiddharth/Flecto/compare/v4.1.0...HEAD
+[4.1.0]: https://github.com/myselfsiddharth/Flecto/compare/v4.0.0...v4.1.0
 [4.0.0]: https://github.com/myselfsiddharth/Flecto/compare/v3.1.0...v4.0.0
 [3.1.0]: https://github.com/myselfsiddharth/Flecto/compare/v3.0.2...v3.1.0
 [3.0.2]: https://github.com/myselfsiddharth/Flecto/compare/v3.0.1...v3.0.2

package/README.md

@@ -63,7 +63,7 @@ flecto doctor
 ```
 
 Prefer not to install globally? Every example below works with
-`npx --yes flecto@3` instead of `flecto`.
+`npx --yes flecto@4` instead of `flecto`.
 
 ---
 
@@ -173,7 +173,7 @@ steps:
   - uses: actions/checkout@v7
     with:
       fetch-depth: 2
-  - uses: myselfsiddharth/Flecto/.github/actions/flecto-ci@main
+  - uses: myselfsiddharth/Flecto/.github/actions/flecto-ci@v4.0.0
     with:
       targets: config/**/*.{yaml,yml,json,toml,ini}
       snapshot-ref: HEAD~1
@@ -197,7 +197,7 @@ steps:
   - uses: actions/checkout@v7
     with:
       fetch-depth: 0
-  - uses: myselfsiddharth/Flecto/.github/actions/flecto-pr-risk@main
+  - uses: myselfsiddharth/Flecto/.github/actions/flecto-pr-risk@v4.0.0
 ```
 
 GitLab and Bitbucket work the same way — Flecto detects the host from CI
@@ -537,6 +537,7 @@ Explicit CLI flags win over profiles, which win over `defaults`.
 | **[Plugins](docs/plugins.md)** · **[Cookbook](docs/plugin-cookbook.md)** | Rules that need real code |
 | **[Live drift](docs/drift.md)** | `flecto-drift`: comparing a declared config against what is actually running |
 | **[Troubleshooting](docs/troubleshooting.md)** | When something doesn't behave |
+| **[Stability](docs/stability.md)** | What you can build against, what you cannot, and the deprecation sequence |
 | **[Migrating to 4.0](docs/migrating-to-4.md)** | The five breaking changes, and how to tell whether they affect you |
 | **[Changelog](CHANGELOG.md)** | Release history and migration notes |
 
@@ -556,6 +557,40 @@ leaves the process unless you configure a webhook or command.
 
 ---
 
+## Stability
+
+Flecto runs inside your merge path, so here is what you can build against.
+These follow [semver](https://semver.org/) and are covered by the deprecation
+sequence below:
+
+- **The JSON envelope** (`schema_version: "2.0"`) — existing fields keep their
+  name, type, and meaning; new fields are additive. Schemas in [`schemas/`](schemas).
+- **Exit codes** — `0` clean, `1` a fail trigger matched or the run could not
+  complete. That is the whole set, and Flecto fails closed.
+- **`.flectorc`** — documented keys keep their name, meaning, and default.
+- **Command and flag names**, and what a flag accepts.
+
+**No breaking change to those ships without a minor release that warns first**,
+names the replacement, and says which version removes the old form. The one
+exception is a security fix: if a surface can make `flecto ci` report a clean run
+on a change that is not clean, it gets closed in the next release with an
+advisory. 4.0 was exactly that — five breaking changes, every one a bypass.
+
+Deliberately **not** stable: terminal and `pr-comment` output (presentation —
+parse `--format json` instead), message wording, anything under `src/`, and
+snapshot file internals. Built-in packs gain rules in minor releases; rule IDs
+never change meaning.
+
+Flecto reached 4.0 in four months, which is fast. That churn was front-loaded
+into a period with no real users, and 4.0 was forced by a
+[security review](docs/security-review.md) finding real bypasses. The intent now
+is minor releases only — anything needing a 5.0 waits in
+[`docs/v5-proposals.md`](docs/v5-proposals.md).
+
+→ **[Full stability policy](docs/stability.md)**
+
+---
+
 ## Project
 
 - **Questions and ideas** — [Discussions](https://github.com/myselfsiddharth/Flecto/discussions)

package/package.json

@@ -4,17 +4,24 @@
     "access": "public",
     "provenance": true
   },
-  "version": "4.0.0",
-  "description": "Flecto \u2014 semantic config watcher that reports meaningful changes in plain English",
+  "version": "4.1.0",
+  "description": "Reads your Terraform plan and Kubernetes changes and posts a plain-English risk summary on every pull request, blocking the dangerous ones",
   "license": "MIT",
   "keywords": [
-    "flecto",
-    "cli",
-    "watcher",
-    "config",
+    "terraform",
+    "terraform-plan",
+    "kubernetes",
+    "helm",
+    "pull-request",
+    "code-review",
+    "policy-as-code",
+    "github-actions",
     "semantic-diff",
+    "config",
     "devops",
-    "ci"
+    "ci",
+    "cli",
+    "flecto"
   ],
   "homepage": "https://github.com/myselfsiddharth/Flecto#readme",
   "bugs": {
@@ -56,7 +63,7 @@
     "chalk": "^5.3.0",
     "chokidar": "^5.0.0",
     "commander": "^12.1.0",
-    "dotenv": "^17.4.2",
+    "dotenv": "^18.0.1",
     "fast-glob": "^3.3.3",
     "js-yaml": "^4.3.0",
     "re2js": "^2.8.6"

package/src/positions.js

@@ -655,9 +655,15 @@ function readJsonValue(state) {
 // dotenv
 
 /**
- * dotenv's own line pattern (dotenv/lib/main.js), with match indices. Reading
- * keys with the parser's exact pattern is what makes the positions agree with
- * it; verification catches a future dotenv that changes it.
+ * dotenv's own line pattern, with match indices. Reading keys with the parser's
+ * exact pattern is what makes the positions agree with it; verification catches
+ * a future dotenv that changes it.
+ *
+ * Upstream source moved in dotenv 18: it was `dotenv/lib/main.js`, and is now
+ * bundled and minified into `dotenv/dist/index.cjs`. The pattern itself is
+ * unchanged between 17.4.2 and 18.0.1 -- byte-identical apart from the `d` flag
+ * added here for match indices. To re-check it after a bump, grep the bundle for
+ * `export\s+`, which is distinctive enough to find the regex in minified code.
  */
 const DOTENV_LINE = /(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/dgm;