@ferrflow/doc 7.17.0

package/docs-v6/reference/conventional-commits.md

@@ -0,0 +1,88 @@
+---
+title: Conventional Commits
+description: How FerrFlow interprets commit messages to determine version bumps.
+---
+
+FerrFlow follows the [Conventional Commits](https://www.conventionalcommits.org/) specification to determine how much to bump the version.
+
+## Bump rules
+
+| Commit type                   | Version bump | Example                             |
+| ----------------------------- | ------------ | ----------------------------------- |
+| `feat:`                       | **minor**    | `feat: add wallet subscriptions`    |
+| `fix:`                        | patch        | `fix: correct pagination offset`    |
+| `perf:`                       | patch        | `perf: cache user queries`          |
+| `refactor:`                   | patch        | `refactor: extract auth middleware` |
+| `feat!:` or `BREAKING CHANGE` | **major**    | `feat!: remove deprecated endpoint` |
+| `chore:`                      | none         | `chore: update dependencies`        |
+| `docs:`                       | none         | `docs: update README`               |
+| `ci:`                         | none         | `ci: add linting step`              |
+| `style:`                      | none         | `style: format code`                |
+| `test:`                       | none         | `test: add unit tests`              |
+
+## Breaking changes
+
+A breaking change can be indicated in two ways:
+
+**Exclamation mark suffix:**
+
+```
+feat!: remove the /v1/users endpoint
+fix!: change authentication header format
+```
+
+**`BREAKING CHANGE` footer:**
+
+```
+feat: redesign the API
+
+BREAKING CHANGE: The /v1/users endpoint has been removed. Use /v2/users instead.
+```
+
+Both produce a **major** version bump.
+
+### Accepted footer variants
+
+FerrFlow recognises the common real-world spellings of the footer, not just the strict spec form:
+
+| Footer                                      | Detected               |
+| ------------------------------------------- | ---------------------- |
+| `BREAKING CHANGE: …`                        | yes (spec)             |
+| `BREAKING-CHANGE: …`                        | yes (spec synonym)     |
+| `breaking-change: …` / `breaking change: …` | yes (case-insensitive) |
+| `Breaking Change: …`                        | yes (case-insensitive) |
+
+It also treats a `!` placed **inside** the scope — `feat(api!):`, a common typo for `feat(api)!:` — as a breaking marker. The footer may sit after any number of body paragraphs.
+
+### What is _not_ a breaking change
+
+Detection stays strict, so a stray mention never triggers an accidental major bump:
+
+- The footer must start a line, use a single space or hyphen (`BREAKING CHANGE` / `BREAKING-CHANGE`), and be followed by a colon **and a space**. `BREAKING CHANGE:no-space` and the plural `BREAKING CHANGES:` are ignored.
+- A prose mention mid-line — "this fixes a breaking change in the parser" — is not a footer.
+- A `!` that is not immediately before the closing paren — `feat(a!b):` — is not a marker.
+
+## Scope
+
+Scopes are optional and ignored for bump calculation. They're useful for readability:
+
+```
+feat(auth): add OAuth2 support       → minor bump
+fix(db): correct index on user table  → patch bump
+```
+
+## No release
+
+Commits with types `chore`, `docs`, `ci`, `style`, or `test` do not trigger a release. If all commits since the last tag are of these types, FerrFlow exits without creating a new version.
+
+## Multiple commits
+
+When multiple commits are present since the last tag, FerrFlow takes the **highest** bump across all of them:
+
+```
+fix: correct typo       → patch
+feat: add export button → minor   ← wins
+chore: lint             → none
+```
+
+Result: **minor** bump.

package/docs-v6/reference/errors.md

@@ -0,0 +1,508 @@
+---
+title: Error codes
+description: Reference for all FerrFlow error codes with causes and fixes.
+---
+
+When FerrFlow encounters an error, it displays a code like `error[E2001]` with a link to this page. Use the code to find the cause and fix.
+
+## Configuration Errors
+
+### E1001: Config file not found
+
+<span id="e1001"></span>
+
+The config file specified via `--config` does not exist.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Run <code>ferrflow init</code> to create a config file, or check the path.</p>
+</div></aside>
+
+### E1002: Failed to parse ferrflow.json
+
+<span id="e1002"></span>
+
+The `ferrflow.json` file contains invalid JSON (missing commas, trailing commas, unquoted keys).
+
+### E1003: Failed to parse ferrflow.json5
+
+<span id="e1003"></span>
+
+The `ferrflow.json5` file contains invalid JSON5.
+
+### E1004: Failed to parse ferrflow.toml
+
+<span id="e1004"></span>
+
+The `ferrflow.toml` file contains invalid TOML.
+
+### E1005: Failed to serialize to TOML
+
+<span id="e1005"></span>
+
+Internal error when writing TOML output.
+
+### E1006: Failed to parse .ferrflow
+
+<span id="e1006"></span>
+
+The `.ferrflow` dotfile contains invalid JSON.
+
+### E1007: Failed to serialize .ferrflow
+
+<span id="e1007"></span>
+
+Internal error when writing the dotfile.
+
+### E1008: Failed to resolve path
+
+<span id="e1008"></span>
+
+A path in the config could not be resolved to an absolute path.
+
+### E1009: Failed to write temporary loader file
+
+<span id="e1009"></span>
+
+Could not write the temporary JS/TS loader during config evaluation.
+
+### E1010: Failed to execute tsx
+
+<span id="e1010"></span>
+
+The `tsx` runtime could not be found or executed for `.ts` config files.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Install tsx: <code>npm install -g tsx</code>, or use a JSON/TOML config instead.</p>
+</div></aside>
+
+### E1011: Failed to execute node
+
+<span id="e1011"></span>
+
+The `node` runtime could not be found or executed for `.js` config files.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Install Node.js or use a JSON/TOML config instead.</p>
+</div></aside>
+
+### E1012: Config evaluation failed
+
+<span id="e1012"></span>
+
+The JS/TS config file threw an error during evaluation.
+
+### E1013: Invalid config output
+
+<span id="e1013"></span>
+
+The JS/TS config file produced non-UTF-8 output.
+
+### E1014: Invalid JSON from config
+
+<span id="e1014"></span>
+
+The JS/TS config file did not produce valid JSON output.
+
+### E1015: Failed to read config file
+
+<span id="e1015"></span>
+
+The config file exists but could not be read (permissions, encoding).
+
+### E1016: Multiple config files found
+
+<span id="e1016"></span>
+
+More than one config file was found in the project root (e.g. both `ferrflow.json` and `ferrflow.toml`).
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Keep only one config file and delete the others.</p>
+</div></aside>
+
+### E1017: Config file already exists
+
+<span id="e1017"></span>
+
+Running `ferrflow init` when a config file already exists.
+
+## Validation Errors
+
+### E1100: Invalid repo spec
+
+<span id="e1100"></span>
+
+The `--repo` argument does not match the expected format `owner/repo` or `host/owner/repo`.
+
+### E1101: GitHub API error
+
+<span id="e1101"></span>
+
+The GitHub API returned an error during remote config validation.
+
+### E1102: GitLab API error
+
+<span id="e1102"></span>
+
+The GitLab API returned an error during remote config validation.
+
+### E1103: Invalid UTF-8 in config
+
+<span id="e1103"></span>
+
+The remote config file contains invalid UTF-8 encoding.
+
+### E1104: Failed to parse remote config
+
+<span id="e1104"></span>
+
+The remote config file could not be parsed.
+
+### E1105: Remote config file not found
+
+<span id="e1105"></span>
+
+The specified config file path does not exist in the remote repository.
+
+### E1106: No config file found
+
+<span id="e1106"></span>
+
+No FerrFlow config file was found in the remote repository.
+
+### E1107: --ref requires --repo
+
+<span id="e1107"></span>
+
+The `--ref` flag was used without specifying `--repo`.
+
+## Git Operation Errors
+
+### E2001: Not a git repository
+
+<span id="e2001"></span>
+
+The current directory is not inside a git repository.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Run FerrFlow from within a git repository, or check the <code>--config</code> path.</p>
+</div></aside>
+
+### E2002: Bare repository not supported
+
+<span id="e2002"></span>
+
+FerrFlow does not support bare git repositories.
+
+### E2003: Tag already exists
+
+<span id="e2003"></span>
+
+The tag that FerrFlow wants to create already exists.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Delete the existing tag or use <code>--force</code> to overwrite.</p>
+</div></aside>
+
+### E2004: Failed to push branch
+
+<span id="e2004"></span>
+
+Could not push the release branch to the remote.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Check that you have push access and the branch is not protected.</p>
+</div></aside>
+
+### E2005: Push rejected by remote
+
+<span id="e2005"></span>
+
+The remote rejected the push (non-fast-forward, branch protection, hooks).
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Pull the latest changes and retry, or check branch protection rules.</p>
+</div></aside>
+
+### E2006: Failed to push tags
+
+<span id="e2006"></span>
+
+Could not push tags to the remote.
+
+### E2007: Failed to push floating tags
+
+<span id="e2007"></span>
+
+Could not force-push floating tags (e.g. `v1`, `v1.2`).
+
+### E2008: Remote not found
+
+<span id="e2008"></span>
+
+The configured git remote (default: `origin`) does not exist.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Check <code>git remote -v</code> and update the <code>remote</code> field in your config.</p>
+</div></aside>
+
+### E2009: Post-push verification failed
+
+<span id="e2009"></span>
+
+After pushing, the release commit could not be verified on the remote branch.
+
+### E2010: Remote branch not found
+
+<span id="e2010"></span>
+
+The remote branch was not found after a push operation.
+
+## GitHub API Errors
+
+### E3001: Failed to create release
+
+<span id="e3001"></span>
+
+The GitHub Releases API returned an error when creating a release.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Check that <code>GITHUB_TOKEN</code> or <code>FERRFLOW_TOKEN</code> has <code>contents: write</code> permission.</p>
+</div></aside>
+
+### E3002: Failed to list releases
+
+<span id="e3002"></span>
+
+Could not fetch existing releases from the GitHub API.
+
+### E3003: Failed to parse releases response
+
+<span id="e3003"></span>
+
+The GitHub API returned an unexpected response format.
+
+### E3004: Failed to publish release
+
+<span id="e3004"></span>
+
+Could not publish (un-draft) a GitHub release.
+
+### E3005: Failed to create pull request
+
+<span id="e3005"></span>
+
+The GitHub API returned an error when creating a PR.
+
+### E3006: Failed to parse PR response
+
+<span id="e3006"></span>
+
+The GitHub API returned an unexpected PR response format.
+
+### E3007: PR response missing required field
+
+<span id="e3007"></span>
+
+The GitHub API PR response was missing the `number` or `node_id` field.
+
+### E3008: Failed to enable auto-merge
+
+<span id="e3008"></span>
+
+Could not enable auto-merge on the release PR via the GraphQL API.
+
+### E3009: Failed to parse GraphQL response
+
+<span id="e3009"></span>
+
+The GitHub GraphQL API returned an unexpected response.
+
+### E3010: Auto-merge failed
+
+<span id="e3010"></span>
+
+The GraphQL mutation to enable auto-merge returned an error.
+
+## GitLab API Errors
+
+### E3101: Failed to create release
+
+<span id="e3101"></span>
+
+The GitLab Releases API returned an error.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Check that the CI token has API access and the project allows release creation.</p>
+</div></aside>
+
+### E3102: Failed to create merge request
+
+<span id="e3102"></span>
+
+The GitLab API returned an error when creating an MR.
+
+### E3103: Failed to parse MR response
+
+<span id="e3103"></span>
+
+The GitLab API returned an unexpected MR response format.
+
+### E3104: MR response missing iid field
+
+<span id="e3104"></span>
+
+The GitLab MR response was missing the `iid` field.
+
+### E3105: Failed to merge MR
+
+<span id="e3105"></span>
+
+Could not merge the release MR via the GitLab API.
+
+## Version File Errors
+
+### TOML (E4101 to E4105)
+
+| Code      | Error                             |
+| --------- | --------------------------------- |
+| **E4101** | Cannot read TOML version file     |
+| **E4102** | Invalid TOML syntax               |
+| **E4103** | No `version` field found          |
+| **E4104** | Failed to write TOML version file |
+| **E4105** | Invalid UTF-8 in TOML file        |
+
+### JSON (E4201 to E4205)
+
+| Code      | Error                             |
+| --------- | --------------------------------- |
+| **E4201** | Cannot read JSON version file     |
+| **E4202** | Invalid JSON syntax               |
+| **E4203** | No `version` field found          |
+| **E4204** | Failed to write JSON version file |
+| **E4205** | Invalid UTF-8 in JSON file        |
+
+### Helm / YAML (E4301 to E4304)
+
+| Code      | Error                       |
+| --------- | --------------------------- |
+| **E4301** | Cannot read Chart.yaml      |
+| **E4302** | No `version` field found    |
+| **E4303** | Failed to write Chart.yaml  |
+| **E4304** | Invalid UTF-8 in Chart.yaml |
+
+### XML (E4401 to E4404)
+
+| Code      | Error                        |
+| --------- | ---------------------------- |
+| **E4401** | Cannot read XML version file |
+| **E4402** | No `<version>` tag found     |
+| **E4403** | Failed to write XML file     |
+| **E4404** | Invalid UTF-8 in XML file    |
+
+### CSProj (E4410 to E4413)
+
+| Code      | Error                         |
+| --------- | ----------------------------- |
+| **E4410** | Cannot read .csproj file      |
+| **E4411** | No `<Version>` tag found      |
+| **E4412** | Failed to write .csproj file  |
+| **E4413** | Invalid UTF-8 in .csproj file |
+
+### Gradle (E4501 to E4504)
+
+| Code      | Error                         |
+| --------- | ----------------------------- |
+| **E4501** | Cannot read build.gradle      |
+| **E4502** | No `version` field found      |
+| **E4503** | Failed to write build.gradle  |
+| **E4504** | Invalid UTF-8 in build.gradle |
+
+### Go mod (E4601 to E4603)
+
+| Code      | Error                                              |
+| --------- | -------------------------------------------------- |
+| **E4601** | Failed to run `git describe`                       |
+| **E4602** | No version tag found — handled internally since v3 |
+| **E4603** | Go modules do not support write                    |
+
+**On `E4602`**: starting with FerrFlow v3 the release flow catches this case and falls back to the strategy's bootstrap baseline (`0.0.0` / `0` / …), so the first release on a brand-new repo succeeds without a pre-seeded tag. The error code still exists for programs that import `GoModVersionFile` directly, but end users running `ferrflow release` should not see it anymore.
+
+### Text (E4701 to E4704)
+
+| Code      | Error                         |
+| --------- | ----------------------------- |
+| **E4701** | Cannot read text version file |
+| **E4702** | No version found              |
+| **E4703** | Failed to write text file     |
+| **E4704** | Invalid UTF-8 in text file    |
+
+## Pre-release Errors
+
+### E5001: Empty channel name
+
+<span id="e5001"></span>
+
+The pre-release channel name is empty.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Provide a non-empty channel name: <code>--channel beta</code></p>
+</div></aside>
+
+### E5002: Invalid channel name
+
+<span id="e5002"></span>
+
+The channel name contains invalid characters. Only alphanumeric characters and hyphens are allowed.
+
+## Versioning Errors
+
+### E5010: Invalid semver
+
+<span id="e5010"></span>
+
+The current version string is not valid semantic versioning.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Ensure the version in your versioned file follows <code>MAJOR.MINOR.PATCH</code> format.</p>
+</div></aside>
+
+## Hook Errors
+
+### E6001: Hook execution failed
+
+<span id="e6001"></span>
+
+A lifecycle hook exited with a non-zero status code and `on_failure` is set to `abort`.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Check the hook command output, or set <code>on_failure: &quot;continue&quot;</code> to ignore failures.</p>
+</div></aside>
+
+## Query Errors
+
+### E7001: No packages configured
+
+<span id="e7001"></span>
+
+No packages are defined in the config file.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Run <code>ferrflow init</code> to create a config, or add packages manually.</p>
+</div></aside>
+
+### E7002: Package not found
+
+<span id="e7002"></span>
+
+The specified package name does not exist in the config.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Run <code>ferrflow version</code> to list all configured packages.</p>
+</div></aside>
+
+## Monorepo Errors
+
+### E8001: Package not found in config
+
+<span id="e8001"></span>
+
+A package referenced during release was not found in the configuration.
+
+### E8002: Floating tag backward move
+
+<span id="e8002"></span>
+
+A floating tag would move to an older version.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Use <code>--force</code> to override the safety check.</p>
+</div></aside>
+
+### E8003: Dependency cycle
+
+<span id="e8003"></span>
+
+Two or more packages depend on each other through `dependsOn`, directly or transitively, so there is no order in which to release them. The message names the loop, e.g. `cycle detected: api → web → api`. Remove one of the `dependsOn` edges to break it. The check runs before any version is written, so a cyclic configuration never leaves a partial release behind.

package/docs-v6/verifying-releases.md

@@ -0,0 +1,97 @@
+---
+title: Verifying releases
+description: Every FerrFlow release ships Sigstore signatures, a CycloneDX SBOM, and a SLSA provenance attestation. Here's how to verify them.
+---
+
+Every release tarball, the Docker image, the binary completions archive, and the SBOM that ships alongside them are signed via [Sigstore](https://www.sigstore.dev/) keyless signing. There are no public keys to track — the signing identity is the GitHub Actions workload identity running in `FerrLabs/FerrFlow`, anchored in the public [Rekor](https://docs.sigstore.dev/logging/overview/) transparency log.
+
+Available since v5.2.
+
+## What ships per release
+
+| Artifact                           | Sidecar                          |
+| ---------------------------------- | -------------------------------- |
+| `ferrflow-linux-x64.tar.gz`        | `.bundle`                        |
+| `ferrflow-linux-arm64.tar.gz`      | `.bundle`                        |
+| `ferrflow-linux-armv7.tar.gz`      | `.bundle`                        |
+| `ferrflow-darwin-x64.tar.gz`       | `.bundle`                        |
+| `ferrflow-darwin-arm64.tar.gz`     | `.bundle`                        |
+| `ferrflow-windows-x64.zip`         | `.bundle`                        |
+| `ferrflow-windows-arm64.zip`       | `.bundle`                        |
+| `ferrflow-completions.tar.gz`      | `.bundle`                        |
+| `sbom.cdx.json`                    | `.bundle`                        |
+| `ghcr.io/ferrlabs/ferrflow:vX.Y.Z` | Cosign signature in GHCR + Rekor |
+
+All sidecars are downloadable from the GitHub Release page next to the binary.
+
+> Releases up to **v5.47.4** ship a `.sig` + `.crt` pair instead of a single `.bundle`. Verify those with `--certificate <file>.crt --signature <file>.sig` in place of `--bundle`. The switch came with cosign v3, which replaced the separate signature and certificate outputs with one bundle.
+
+## Verifying a tarball
+
+```bash
+# install cosign (one-time)
+curl -L https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64 \
+  -o /usr/local/bin/cosign && chmod +x /usr/local/bin/cosign
+
+# download the artifact + sidecars from the release page
+TAG=v5.2.3
+gh release download "$TAG" --repo FerrLabs/FerrFlow \
+  -p 'ferrflow-linux-x64.tar.gz*'
+
+# verify
+cosign verify-blob \
+  --bundle ferrflow-linux-x64.tar.gz.bundle \
+  --certificate-identity-regexp "https://github.com/FerrLabs/FerrFlow/.*" \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  ferrflow-linux-x64.tar.gz
+# → Verified OK
+```
+
+A passing verification means:
+
+- The tarball bytes haven't been tampered with since the release workflow signed them.
+- The signing identity was a workflow running in `FerrLabs/FerrFlow` triggered by GitHub Actions' OIDC issuer.
+- The signature is recorded in the public Rekor log — search [search.sigstore.dev](https://search.sigstore.dev/) for the `.sig` value.
+
+## Verifying the Docker image
+
+```bash
+cosign verify ghcr.io/ferrlabs/ferrflow:v5.2.3 \
+  --certificate-identity-regexp "https://github.com/FerrLabs/FerrFlow/.*" \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com
+```
+
+## Verifying the SBOM
+
+The SBOM (`sbom.cdx.json`) is a [CycloneDX](https://cyclonedx.org/) document listing every transitive dependency of the published binary. It's signed the same way as the tarballs:
+
+```bash
+cosign verify-blob \
+  --bundle sbom.cdx.json.bundle \
+  --certificate-identity-regexp "https://github.com/FerrLabs/FerrFlow/.*" \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  sbom.cdx.json
+```
+
+Feed the verified SBOM into your scanner of choice — Grype, Trivy, Snyk, JFrog Xray, Anchore, anything CycloneDX-aware.
+
+## SLSA build provenance
+
+In addition to Sigstore signatures, every release also ships a [SLSA build provenance attestation](https://slsa.dev/) generated via [`actions/attest-build-provenance`](https://github.com/actions/attest-build-provenance). It records the workflow run, the source commit SHA, and the build inputs.
+
+```bash
+gh attestation verify ferrflow-linux-x64.tar.gz --repo FerrLabs/FerrFlow
+```
+
+## What's not signed
+
+Source tarballs from `git archive` (the auto-generated "Source code (zip)" and "Source code (tar.gz)" assets on the GitHub Release page) come from GitHub, not from the release workflow, and have no signature sidecar. If you need an attestation for source, use `gh attestation verify` against the build provenance bundle instead.
+
+## Why this matters
+
+- **Supply-chain attacks.** An attacker who compromises a CDN, a mirror, or pushes a typosquat package can't forge the signature — the signing identity is anchored to the GitHub Actions OIDC flow.
+- **Compliance.** SOC 2 / ISO 27001 customers can attest that the binary they pulled is what their auditor approved.
+- **No key management.** Nobody at FerrLabs has a private signing key to lose or rotate. The workflow proves its identity at the moment of signing.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>If you&#39;re shipping FerrFlow into a regulated environment, pin both the version <strong>and</strong> the <code>.sig</code>/<code>.crt</code> pair into your provisioning step. A future workflow compromise can&#39;t backdate a signature that already exists in Rekor.</p>
+</div></aside>