@ferrflow/doc 7.17.0

package/docs-v2/reference/cli.md

@@ -0,0 +1,130 @@
+---
+title: CLI commands
+description: Full reference for all FerrFlow CLI commands and flags.
+---
+
+## `ferrflow release`
+
+Run the full release pipeline: bump versions, update changelogs, commit, tag, push, and create a release.
+
+```bash
+ferrflow release [OPTIONS]
+```
+
+| Flag                        | Description                                                                                                      |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `--dry-run`                 | Preview all changes without writing, committing, or pushing                                                      |
+| `--force`                   | Allow floating tags to move backward to a lower version                                                          |
+| `--force-version <VERSION>` | Force a specific version, skipping commit analysis. Format: `VERSION` (single repo) or `NAME@VERSION` (monorepo) |
+| `--verbose`, `-v`           | Show detailed output including commit hashes and file diffs                                                      |
+
+**What it does:**
+
+1. Scans commits since the last tag for each package
+2. Determines the version bump from Conventional Commits
+3. Updates all `versionedFiles` with the new version
+4. Appends the new section to `CHANGELOG.md`
+5. Creates a git commit, opens a PR, or skips (depending on `releaseCommitMode`)
+6. Creates and pushes the git tag
+7. Creates a GitHub/GitLab release with the changelog as notes
+
+---
+
+## `ferrflow check`
+
+Preview what `ferrflow release` would do without making any changes. Equivalent to `ferrflow release --dry-run`.
+
+```bash
+ferrflow check
+```
+
+---
+
+## `ferrflow changelog`
+
+Generate or update `CHANGELOG.md` only, without bumping versions or creating tags.
+
+```bash
+ferrflow changelog [OPTIONS]
+```
+
+| Flag        | Description                                       |
+| ----------- | ------------------------------------------------- |
+| `--dry-run` | Print the changelog entry without writing to disk |
+
+---
+
+## `ferrflow init`
+
+Scaffold a config file for the current repository. Detects existing version files (`Cargo.toml`, `package.json`, etc.) and generates the appropriate config.
+
+```bash
+ferrflow init [OPTIONS]
+```
+
+| Flag                | Description                                    |
+| ------------------- | ---------------------------------------------- |
+| `--format <FORMAT>` | Config file format: `json`, `json5`, or `toml` |
+
+---
+
+## `ferrflow status`
+
+Show the current version of each package and whether a release would be triggered.
+
+```bash
+ferrflow status [OPTIONS]
+```
+
+| Flag                | Description                               |
+| ------------------- | ----------------------------------------- |
+| `--output <FORMAT>` | Output format: `text` (default) or `json` |
+
+Example output:
+
+```
+api    1.2.3   minor bump pending (1 feat commit)
+site   0.4.1   no release (only chore commits)
+```
+
+---
+
+## `ferrflow version`
+
+Print the current version of one or all packages. Useful in CI scripts.
+
+```bash
+ferrflow version [PACKAGE] [OPTIONS]
+```
+
+| Flag     | Description    |
+| -------- | -------------- |
+| `--json` | Output as JSON |
+
+Returns the version from the latest git tag matching the package's tag template.
+
+---
+
+## `ferrflow tag`
+
+Print the latest tag for one or all packages.
+
+```bash
+ferrflow tag [PACKAGE] [OPTIONS]
+```
+
+| Flag     | Description    |
+| -------- | -------------- |
+| `--json` | Output as JSON |
+
+---
+
+## Global flags
+
+These flags work with all commands:
+
+| Flag              | Description                                                                                         |
+| ----------------- | --------------------------------------------------------------------------------------------------- |
+| `--config <PATH>` | Path to a custom config file (default: auto-detected). Also accepts `FERRFLOW_CONFIG` env variable. |
+| `--version`       | Print the FerrFlow version and exit                                                                 |
+| `--help`, `-h`    | Print help                                                                                          |

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

@@ -0,0 +1,67 @@
+---
+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.
+
+## 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-v2/reference/errors.md

@@ -0,0 +1,500 @@
+---
+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            |
+| **E4603** | Go modules do not support write |
+
+### 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>