FLPATH-4770 - bump control-plane and add check-website-fixtures workflow

[testetson22]

FLPATH-4770: The CLI's go.mod pinned control-plane to a commit predating the multi-resource schema change (FLPATH-4384). This caused parseInputFileAs to silently drop the spec.resources field during YAML → JSON serialization, making it impossible to create catalog items via dcm catalog item create.

check-website-fixtures action is expected to fail until the dcm-project.github.io PR is merged.

Changes

• Bump github.com/dcm-project/control-plane to latest main so the CLI's generated types include the Resources field required by the multi-resource catalog item schema
• Add static contract tests (TC-U154, TC-U155) that validate the CLI correctly serializes documented tutorial YAMLs to the API
• Add testdata/website/ fixtures mirroring the Getting Started tutorial examples
• Add hack/check-website-fixtures.sh script + CI workflow to detect drift between local fixtures and the upstream website repo

Depends on

• FLPATH-4770 - fix getting started examples for multi-resource catalog items dcm-project.github.io#21 - Website: updates tutorial YAMLs to multi-resource schema (dcm-project/dcm-project.github.io branch FLPATH-4770-fix-user-journey)

Test plan

• go test ./... passes (151 specs including 2 new contract tests)
• Contract tests validate the exact YAML→JSON serialization path that was broken
• hack/check-website-fixtures.sh correctly detects drift (verified locally)
• ShellCheck passes on the script
• hugo --minify confirms companion website changes render correctly

Related

• FLPATH-4794 — Add CLI-to-API contract tests to prevent silent schema drift

[qodo-code-review]

PR Summary by Qodo

Bump control-plane types and add website-fixture contract validation

🐞 Bug fix 🧪 Tests ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Bump control-plane dependency so CLI request types include multi-resource schema fields.
• Add contract tests proving tutorial YAML serializes to API without dropping spec.resources.
• Add website YAML fixtures plus CI workflow/script to detect drift from upstream docs.

Diagram

graph TD
  A["GitHub Actions workflow"] --> B["check-website-fixtures.sh"] --> C["Upstream docs markdown"]
  B --> D["Local YAML fixtures"]
  E["Ginkgo contract tests"] --> D --> F["CLI create commands"] --> G["parseInputFileAs"] --> H["control-plane request types"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Strict decode to fail on unknown/missing fields

• ➕ Prevents silent field loss even if generated types are stale
• ➕ Turns schema drift into an actionable CLI error
• ➖ Reduces forward compatibility (new server fields can break older CLIs)
• ➖ Requires careful error messaging and potentially per-command toggles/flags

2. Send unstructured payloads (map[string]any) to API

• ➕ Avoids dropping fields during YAML→typed-struct conversion
• ➕ Naturally supports forward-compatible passthrough
• ➖ Loses client-side schema validation benefits
• ➖ Harder to provide good CLI errors and completions; may allow invalid payloads

3. Pull fixtures directly from website repo in Go tests

• ➕ Eliminates local fixture drift by always testing the canonical docs
• ➕ Avoids extra bash maintenance
• ➖ Makes tests network-dependent and flaky unless vendored/cached
• ➖ Harder to run reliably in hermetic CI environments

Recommendation: The chosen approach (bump control-plane + contract tests + explicit drift-check workflow) is the best balance of correctness and determinism: it fixes the root cause (missing generated fields) and adds regression coverage using stable, versioned fixtures. Consider a follow-up to add optional strict decoding (or a CI-only strict mode) to ensure future schema mismatches fail loudly rather than silently dropping fields.

Files changed (8) +296 / -4

Bug fix (1) +1 / -1

go.modBump control-plane dependency to include multi-resource schema +1/-1

Bump control-plane dependency to include multi-resource schema

• Updates github.com/dcm-project/control-plane to a newer main snapshot. This ensures the CLI’s generated request types include newer fields like spec.resources.

go.mod

Tests (3) +182 / -0

contract_test.goAdd CLI-to-docs contract tests for catalog create serialization +130/-0

Add CLI-to-docs contract tests for catalog create serialization

• Adds Ginkgo tests that run real CLI commands against an httptest server and assert outgoing JSON preserves critical multi-resource fields. Specifically validates spec.resources for catalog items and user_values[].resource for instances.

internal/commands/contract_test.go

my-vm.yamlAdd instance tutorial YAML fixture (my-vm) +14/-0

Add instance tutorial YAML fixture (my-vm)

• Adds a fixture mirroring the Getting Started instance example, including user_values entries with the resource selector field.

testdata/website/my-vm.yaml

small-vm.yamlAdd catalog item tutorial YAML fixture (small-vm) +38/-0

Add catalog item tutorial YAML fixture (small-vm)

• Adds a fixture mirroring the Getting Started catalog item example using the multi-resource schema with spec.resources and documented fields.

testdata/website/small-vm.yaml

Other (4) +113 / -3

check-website-fixtures.yamlAdd CI job to verify website fixture parity +18/-0

Add CI job to verify website fixture parity

• Introduces a workflow that runs on main pushes, PRs, and a weekly schedule. The job executes the fixture validation script to detect drift from upstream docs.

.github/workflows/check-website-fixtures.yaml

MakefileAdd check-fixtures make target +4/-1

Add check-fixtures make target

• Adds a phony make target that runs hack/check-website-fixtures.sh, making fixture validation easy to invoke locally and in CI.

Makefile

go.sumUpdate sums for bumped control-plane version +2/-2

Update sums for bumped control-plane version

• Refreshes module checksums to match the updated control-plane dependency version.

go.sum

check-website-fixtures.shAdd script to diff/update local fixtures from upstream docs +89/-0

Add script to diff/update local fixtures from upstream docs

• Adds a bash script that fetches Getting Started markdown from the website repo, extracts the first fenced YAML block, and diffs it against local fixtures. Supports --update to refresh fixtures and fails CI on drift.

hack/check-website-fixtures.sh

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. check-website-fixtures.sh lacks exit 2 ✓ Resolved 📘 Rule violation ≡ Correctness

Description

The new hack/check-website-fixtures.sh script does not validate/handle unknown CLI arguments and
therefore cannot return exit code 2 for incorrect invocation as required. This makes automation
unable to distinguish usage errors from runtime/verification failures.

Code

hack/check-website-fixtures.sh[R16-19]

+UPDATE=false
+if [[ "${1:-}" == "--update" ]]; then
+    UPDATE=true
+fi

Evidence

PR Compliance ID 2696894 requires standardized exit codes including 2 for usage errors. The script
only checks --update via $1 and otherwise proceeds without argument validation, while failures
exit with 1, so incorrect invocation cannot be represented with exit code 2.

Rule 2696894: Standardize process exit codes for CLI programs
hack/check-website-fixtures.sh[16-19]
hack/check-website-fixtures.sh[82-86]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`hack/check-website-fixtures.sh` only recognizes `--update` (and only in `$1`) and does not reject/handle other arguments, so it cannot emit standardized usage error exit code `2`.

## Issue Context
Per the repo compliance requirement, CLI programs/scripts must use: `0` success, `1` runtime/operational failures, `2` incorrect invocation.

## Fix Focus Areas
- hack/check-website-fixtures.sh[16-19]
- hack/check-website-fixtures.sh[82-86]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Flaky external CI dependency ✓ Resolved 🐞 Bug ☼ Reliability

Description

The new check-website-fixtures workflow runs a script that curl-fetches upstream GitHub raw content
on every PR/push and exits non-zero on any transient network/HTTP failure, making CI fail for
reasons unrelated to this repo’s changes. This introduces avoidable reliability risk (rate limiting,
outages, slow/hanging curl) and can block merges.

Code

hack/check-website-fixtures.sh[R45-48]

+    if ! markdown=$(curl -sf "${url}"); then
+        echo "  ERROR: Could not fetch ${url} (network error or 404)"
+        errors=$((errors + 1))
+        continue

Evidence

The workflow runs the script on PRs/pushes, and the script increments an error counter when `curl
-sf fails to fetch upstream content; any errors cause an exit 1`, failing the job even for
transient network issues.

.github/workflows/check-website-fixtures.yaml[3-9]
.github/workflows/check-website-fixtures.yaml[11-18]
hack/check-website-fixtures.sh[45-49]
hack/check-website-fixtures.sh[82-86]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`hack/check-website-fixtures.sh` hard-fails (`exit 1`) when `curl` cannot fetch upstream markdown (network error/404). Since `.github/workflows/check-website-fixtures.yaml` runs this on `pull_request` and `push`, transient network issues or GitHub rate limiting can fail CI and block merges.

## Issue Context
The workflow is intended to detect drift with `dcm-project/dcm-project.github.io`, but it currently treats fetch failures the same as drift and has no retry/timeout.

## Fix Focus Areas
- Add `curl` timeouts + retry/backoff (and optionally a clearer message for rate limiting).
- Consider distinguishing "fetch failed" from "drift detected" (e.g., allow a soft-fail on PRs, hard-fail on scheduled runs).
- Optionally pin to a specific ref/commit for PR checks, or gate the workflow to scheduled runs only if merge-blocking is undesirable.

### References
- hack/check-website-fixtures.sh[45-49]
- hack/check-website-fixtures.sh[82-86]
- .github/workflows/check-website-fixtures.yaml[3-9]
- .github/workflows/check-website-fixtures.yaml[11-18]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Docs not updated for schema ✓ Resolved 📘 Rule violation ⚙ Maintainability

Description

This PR introduces multi-resource catalog item/instance fixtures and contract tests that require
spec.resources and user_values[].resource, but the repository documentation still shows the
older single-resource YAML formats. This violates the requirement to update AI/user documentation
when behavior/schema expectations change.

Code

testdata/website/small-vm.yaml[R3-6]

+spec:
+  resources:
+    - name: main
+      service_type: vm

Evidence

PR Compliance ID 2696907 requires updating README/CLAUDE/.ai specs/test-plans when behavior or
documented interfaces change. The PR adds fixtures/tests using the new spec.resources and
user_values[].resource schema, while README.md still documents catalog item creation using
spec.service_type/spec.fields and instance creation using user_values entries without
resource, indicating documentation drift introduced/activated by this PR's schema change.

Rule 2696907: Update AI documentation when changing behavior, config, or architecture
testdata/website/small-vm.yaml[1-7]
testdata/website/my-vm.yaml[1-7]
internal/commands/contract_test.go[58-80]
README.md[425-444]
README.md[510-520]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The PR adds fixtures/tests that depend on the multi-resource schema (`spec.resources` and `user_values[].resource`), but the repo documentation examples still document the older schema, creating drift.

## Issue Context
The new fixtures and contract tests codify the expected YAML→JSON serialization contract for the CLI; documentation should match these examples to avoid user and contributor confusion.

## Fix Focus Areas
- testdata/website/small-vm.yaml[1-8]
- testdata/website/my-vm.yaml[1-14]
- internal/commands/contract_test.go[57-92]
- README.md[411-444]
- README.md[495-520]
- CLAUDE.md[16-45]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

⚠️ Tickets: not configured — ticket URL found in PR but could not be fetched — check ticket provider credentials

✅ Compliance rules (platform): 16 rules

Tip of the day

💡 Did you know, you can copy the agent prompt from any finding and feed it to your IDE agent

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗