From 86386f28b178afa67d154dd577acc88581c8ff87 Mon Sep 17 00:00:00 2001 From: Speculator55005 <50082482+fas89@users.noreply.github.com> Date: Wed, 4 Nov 2026 01:45:31 +0100 Subject: [PATCH] docs(validate,plan): an id the build phase refuses is a validate and plan warning (forge-cli#813) fluid validate warns (--strict fails) and fluid plan warns and still writes the plan for a contract.id or builds[].id the build phase refuses. apply.md's Build ids section said both passed such an id silently; validate.md gets a section, plan.md a note, upgrading.md an entry. --- docs/cli/apply.md | 4 ++-- docs/cli/plan.md | 1 + docs/cli/validate.md | 18 ++++++++++++++++++ docs/upgrading.md | 6 ++++++ 4 files changed, 27 insertions(+), 2 deletions(-) diff --git a/docs/cli/apply.md b/docs/cli/apply.md index 4dfeaec..e849fb9 100644 --- a/docs/cli/apply.md +++ b/docs/cli/apply.md @@ -201,7 +201,7 @@ There is no flag to skip the check. Run `fluid validate --env ` *On forge-cli `main`, not yet in a release ([forge-cli #803](https://github.com/Agenticstiger/forge-cli/pull/803)).* Under `--mode amend-and-build` or `replace-and-build`, `fluid apply` also checks `id` and every `builds[].id` right after the schema check. This happens on both engines, before the apply hooks, `tofu` and any build. -The build phase keeps each build's run records, cursors and watermarks under `.fluid/runs///`, so its rule is narrower than the schema's. An id must start with a letter or `_`, use only letters, digits, `_`, `.` and `-`, and be at most 128 characters. The schema also accepts a leading digit and any length. So `fluid validate` and `fluid plan` pass an id such as `1orders`, and `fluid apply` refuses it: +The build phase keeps each build's run records, cursors and watermarks under `.fluid/runs///`, so its rule is narrower than the schema's. An id must start with a letter or `_`, use only letters, digits, `_`, `.` and `-`, and be at most 128 characters. The schema also accepts a leading digit and any length. So `fluid validate` and `fluid plan` pass an id such as `1orders`, though on forge-cli `main` both [warn about it](./validate.md#an-id-the-build-phase-refuses) ([forge-cli #813](https://github.com/Agenticstiger/forge-cli/pull/813)), and `fluid apply` refuses it: ```bash fluid apply contract.fluid.yaml --mode amend-and-build --yes @@ -211,7 +211,7 @@ fluid apply contract.fluid.yaml --mode amend-and-build --yes ❌ apply_build_identifier_invalid [ERR_APPLY_BUILD_IDENTIFIER_INVALID] field: contract.id value: '1orders' - hint: The build phase keeps each build's run records, cursors and watermarks under .fluid/runs///, so both ids must start with a letter or underscore, use only letters, digits, '_', '.' and '-', and be at most 128 characters. The contract schema allows more, so fluid validate and fluid plan accept it. Nothing was applied. + hint: The build phase keeps each build's run records, cursors and watermarks under .fluid/runs///, so both ids must start with a letter or underscore, use only letters, digits, '_', '.' and '-', and be at most 128 characters. The contract schema allows more, so fluid validate and fluid plan only warn about it. Nothing was applied. 💡 Suggestions: • Rename the id to fit, for example orders_v1 instead of 1orders, and apply again diff --git a/docs/cli/plan.md b/docs/cli/plan.md index 64b4405..e9c7050 100644 --- a/docs/cli/plan.md +++ b/docs/cli/plan.md @@ -174,6 +174,7 @@ fluid apply runtime/plan.json --mode amend --yes ## Notes - `plan` is the safest place to preview a provider override or environment overlay before you run `apply`. +- *On forge-cli `main`, not yet in a release ([forge-cli #813](https://github.com/Agenticstiger/forge-cli/pull/813)).* For a contract with `builds`, `plan` prints the warning [`fluid validate` gives](./validate.md#an-id-the-build-phase-refuses) for an `id` or `builds[].id` the build phase refuses, and still writes the plan, whatever `--mode` says. `fluid apply` in a build mode refuses that id before it applies anything; see [Build ids](./apply.md#build-ids). - The generated plan can be passed to [`fluid apply`](./apply.md) — the digests pin the apply to exactly this plan. - When planning from a tgz bundle directly, `bundleDigest` is populated from `MANIFEST.json`. When planning from a raw YAML contract, `bundleDigest` is an empty string and only `planDigest` is verified. diff --git a/docs/cli/validate.md b/docs/cli/validate.md index df8e836..f90c6f7 100644 --- a/docs/cli/validate.md +++ b/docs/cli/validate.md @@ -400,6 +400,24 @@ For a build of the last kind, `fluid apply --mode amend-and-build` prints: The check runs on the contract file and on a bundle's resolved contract, not in [workspace mode](#validating-without-a-contract-path). +## An id the build phase refuses + +*On forge-cli `main`, not yet in a release ([forge-cli #813](https://github.com/Agenticstiger/forge-cli/pull/813)).* The build phase puts `id` and each `builds[].id` in directory names and generated code, so its rule is narrower than the schema's: an id must start with a letter or `_`, use only letters, digits, `_`, `.` and `-`, and be at most 128 characters. The schema also accepts a leading digit and any length. For a contract with `builds`, `fluid validate` warns about such an id: + +```text +✅ Valid FLUID contract (schema v0.7.5) +⚠️ 1 warning(s) +Validation completed in 0.003s + +Validation Warnings: +==================== + 1. contract.id '1orders' cannot be used by the build phase, which puts it in directory names and generated code, so it must start with a letter or underscore, use only letters, digits, '_', '.' and '-', and be at most 128 characters. fluid apply in a build mode (amend-and-build, replace-and-build) refuses this id before it applies anything. Rename it to fit. +``` + +Without `--strict` it exits `0`; with it, `1`. `--format json` lists it under `warnings`. The warning names the first id that fails, the one [`fluid apply` refuses](./apply.md#build-ids); after a rename, validate again for the next. A contract without `builds` is not checked. [`fluid plan`](./plan.md#notes) prints the same warning and still writes the plan. + +The check runs on the contract file and on a bundle's resolved contract, not in [workspace mode](#validating-without-a-contract-path). + ## Validating a bundle (`.tgz`) Pass a bundle built with `fluid bundle --format tgz` and `fluid validate` checks the bundle itself and the contract inside it: diff --git a/docs/upgrading.md b/docs/upgrading.md index bd57aec..578ec7a 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -642,6 +642,12 @@ These changes are merged and in no release yet. Most fail closed where a contrac `apply_build_id_not_found`, which lists the contract's build ids. The exit code is still `1`. A Command Center run records the event `apply_build_id_not_found` where it recorded `build_not_found:`. See [Build ids](./cli/apply.md#build-ids). +- **`fluid validate` and `fluid plan` warn about an id the build phase refuses** + ([#813](https://github.com/Agenticstiger/forge-cli/pull/813)). For a contract with + `builds`, an `id` or `builds[].id` that starts with a digit or is longer than 128 characters is + a validate warning, so `fluid validate --strict` fails on it. `fluid plan` prints it and still + writes the plan. Rename the id: `fluid apply` in a build mode refuses it anyway. See + [An id the build phase refuses](./cli/validate.md#an-id-the-build-phase-refuses). - **`fluid doctor --strict` and a readable failed apply** ([#786](https://github.com/Agenticstiger/forge-cli/pull/786)). `fluid doctor --strict` exits `1` when the summary says "Action needed", copilot readiness included; the default exit code does not