Skip to content

Adopt the CLI-scaffold-parity component baseline (#4)#5

Merged
mbreissi merged 8 commits into
mainfrom
feat/baseline-adoption
Jul 20, 2026
Merged

Adopt the CLI-scaffold-parity component baseline (#4)#5
mbreissi merged 8 commits into
mainfrom
feat/baseline-adoption

Conversation

@mbreissi

Copy link
Copy Markdown
Contributor

Summary

Full remediation for #4 (file-replicator's leg of the org-wide CLI-scaffold-parity baseline sweep). file-replicator is a sink, not a southbound adapter, so only the cross-cutting items 1-6 from #4 apply — no sb/* verbs, no southbound_health, no panel trio. Naming, dependency-pin shape, coverage-seam discipline, and Diátaxis docs already met the baseline per #4's own gap analysis and are unchanged here.

Per the resolved scope decisions in the master remediation plan: full P0+P1+P2, Cargo.lock committed (SD-B), and the Apache-2.0/BUSL-1.1 license mismatch (#2) fixed inline.

Per-item checklist (against #4)

  • P0-1 — commit Cargo.lock. Dropped the /Cargo.lock gitignore rule and its stale rationale comment; committed a lock regenerated against the pinned git rev with no local .cargo [patch] override active.
  • P0-2 — license → BUSL-1.1 (Fixes #2). Cargo.toml's license field and the README's license line now both declare BUSL-1.1, matching the shipped LICENSE.
  • P1-3 — config.schema.json. Authored against src/config.rs/docs/reference/{configuration,destinations}.md: component.global (defaults, limits, onPermissionError — what edgecommons component validate actually checks) plus a full $defs/instance reference covering ingress/readiness, all seven egress backends, schedule, completion, retry, and priority. Validated against the shipped test-configs/config.json instance and a synthetic instance exercising every backend/variant, plus a negative case.
  • P1-4 — .github/workflows/deploy-docs.yml. Added verbatim from modbus-adapterci.yml paths-ignores docs, so doc-only pushes were not refreshing the site.
  • P1-5 — root README.md rewrite. Removed the dev-diary "Implemented through P6... P7 remains undone... docs lag" narration (which also contradicted docs/README.md's own "validated against src/"); replaced wholesale with present-tense current-state text. The phase history already lives in DESIGN.md §21.
  • P2-6 — CLAUDE.md → baseline import shape. Was a near-duplicate of AGENTS.md; now a short header + @AGENTS.md import + this component's own local-dev notes.
  • P2-7 — recipe sample-value sweep. Replaced the shipped Greengrass recipe's tags: {appId: "Test", site: "Chantilly"} with neutral "CHANGE_ME" placeholders.
  • Docker: bump the Rust build base off 1.85 (can't build current Cargo.lock) #3 coordination — Docker build base. rust:1.85-slim could not build the correctly git-resolved locked tree at all (AWS SDK crates need rustc 1.94.1+, crc-fast needs 1.89+); bumped to rust:1.96-slim, matching config-component's precedent cited in Docker: bump the Rust build base off 1.85 (can't build current Cargo.lock) #3. rust-version MSRV in Cargo.toml is untouched.

A bug the validation work turned up and fixed along the way

Two issues surfaced only by actually running the validation gates, not part of the original checklist:

  1. The first committed lock was wrong. This worktree lives nested inside the main file-replicator checkout (file-replicator/.claude/worktrees/...), and Cargo's config discovery walks every ancestor directory for a .cargo/config.toml. The main checkout's own gitignored local-dev [patch] override was therefore still in scope from inside the worktree, so the first lock generation silently recorded edgecommons as a path dependency (version = "0.3.0", no source) instead of the pinned git rev — unresolvable from a fresh clone or CI. Caught by cloning to a directory outside that ancestry and comparing; regenerated correctly there (only the edgecommons package's own entry changed — every transitive dependency was already identical, since the override doesn't touch the rest of the graph).
  2. test-configs/config.json's heartbeat.targets[] predates the heartbeat→state UNS migration (the canonical schema now takes heartbeat.destination; recipe.yaml already used the current shape). This was failing edgecommons component validate outright. Fixed to destination: "local".
  3. The Dockerfile's own comment promised GITHUB_TOKEN support that didn't exist — nothing in the file consumed one, so the image could not be built at all to prove out the Docker: bump the Rust build base off 1.85 (can't build current Cargo.lock) #3 fix. Wired it up via a BuildKit secret mount (--mount=type=secret), not a --build-arg/ENV (Docker's own linter flags those as leaking into image history for exactly this kind of value).

Validation evidence

All run locally (Windows, native Rust toolchain 1.96.0), using an isolated clone outside the worktree's directory ancestry so the local-dev .cargo override could not interfere:

  • cargo build --locked --release --features dest-s3,dest-sftp,dest-ftps,dest-http,dest-azure,dest-gcs — green.
  • cargo test --locked (same features) — all suites green, including the simulator-backed integration tests.
  • cargo clippy --locked --all-targets (same features) — clean, no warnings.
  • cargo llvm-cov --locked --fail-under-lines 90 (CI's exact exclusion set) — 93.41% line coverage, gate passes.
  • Fresh-clone build proof: cloned the pushed branch to a directory with no .cargo/config.toml in its ancestry; cargo build --locked resolves the pinned git dependency and builds clean — proving the committed lock is fit for CI/a real fresh clone.
  • edgecommons component validate (built from the cli-scaffold-parity worktree, per PR CLI scaffold parity: close the ethernet-ip-adapter dogfooding gaps across all 16 templates edgecommons#57): OK — no findings.
  • Docker image build, from a fresh clone, docker build --secret id=github_token,env=GITHUB_TOKEN: builds the locked tree clean on rust:1.96-slim, no linter warnings, confirmed no token in docker history.

Deviations / scope notes

  • Two small fixes (the Docker git-auth wiring, the heartbeat.targets stale test-config) were outside the issue's literal checklist but were necessary to actually prove the checklist items true rather than assert them — both are called out above rather than folded in silently.
  • No live-infra gate applies to this leg (file-replicator's own validation matrix row lists none required beyond the local gates above and the Docker build).

Fixes #4
Fixes #2

🤖 Generated with Claude Code

https://claude.ai/code/session_01DxV5wFi7LCratBERVT6aiL

mbreissi and others added 8 commits July 20, 2026 06:45
Per the org lockfile-commit policy (component repos commit their lockfile):
drop the `/Cargo.lock` gitignore rule and its now-stale rationale comment
("pre-UNS placeholder rev that does not compile" — the pin has long since
been bumped to a compiling rev on core main), and commit a lockfile
regenerated against the pinned git rev with no local `.cargo` `[patch]`
override active. Fresh clones and CI now resolve reproducibly instead of
re-resolving the dependency tree on every build.

The regenerated lock's transitive tree needs a newer rustc than the Docker
build stage's `rust:1.85-slim` (e.g. `time`/`icu_*` pulled in via the
edgecommons dependency require 1.86-1.88), so the image can no longer build
the locked tree — bump the build base to `rust:1.88-slim` and build with
`--locked` so a future lock/manifest mismatch fails loudly in the image
build rather than silently re-resolving. The `rust-version` MSRV floor in
Cargo.toml is untouched (separate concern per #3).

Fixes #3

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DxV5wFi7LCratBERVT6aiL
Model `component.global` (the object `edgecommons component validate`
actually checks) from `src/config.rs`/`docs/reference/configuration.md`:
`defaults` (retry, timezone), `limits` (maxConcurrentFiles, maxBandwidth),
`onPermissionError`. Also document the full `component.instances[]` shape
under `$defs/instance` (ingress/readiness, all seven egress backends,
schedule, completion, retry, limits, permission override, priority) mirroring
`InstanceCfg` and `docs/reference/destinations.md`, for reference and any
future instance-level validation.

Validated against the shipped `test-configs/config.json` instance plus a
synthetic instance exercising every egress backend and schedule/readiness
variant, and against a negative case (an unknown egress `type` is correctly
rejected).

Fixed a real, unrelated defect this surfaced: `test-configs/config.json`'s
`heartbeat.targets[]` predates the heartbeat->state UNS migration (the
canonical schema now takes `heartbeat.destination`; `recipe.yaml` already
uses the current shape) — `edgecommons component validate` was failing on
this stale test config. Updated it to `destination: "local"`.

`edgecommons component validate` now passes clean against this repo.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DxV5wFi7LCratBERVT6aiL
ci.yml paths-ignores docs/**/*.md, so a doc-only push to main was
triggering nothing and the EdgeCommons docs site did not refresh (the repo
is registered in registry/components.json and its docs/ syncs at site
build time). Verbatim from modbus-adapter's deploy-docs.yml: hits the
Cloudflare Workers Builds deploy hook (a no-op until the repo's
CLOUDFLARE_DEPLOY_HOOK secret is set).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DxV5wFi7LCratBERVT6aiL
The root README's "Status" and "Docs" sections were dev-diary narration
("Implemented through P6... only P7 remains undone... docs lag the
implementation in places") — the phase history already lives in
DESIGN.md §21, and the "docs lag" claim directly contradicted
docs/README.md's own "validated against src/". Replace both sections
wholesale with present-tense, current-state text and pointers to
docs/reference/{configuration,destinations}.md and DESIGN.md.

Reconcile the Apache-2.0 vs BUSL-1.1 mismatch: Cargo.toml's `license` field
and the README's license line both said Apache-2.0 while the shipped
LICENSE file is already BSL 1.1 (BUSL-1.1). Both now declare BUSL-1.1.

Fixes #2

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DxV5wFi7LCratBERVT6aiL
CLAUDE.md was a near-duplicate of AGENTS.md (two copies of the same
guidance drifting independently). Convert it to the baseline shape: a
short header, an `@AGENTS.md` import, and this component's own
local-dev notes (the gitignored `.cargo/config.toml` `[patch]` override
used for sibling-checkout development, now contrasted with the committed
Cargo.lock CI/fresh-clones resolve against). AGENTS.md remains the single
source of the full component guidance.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DxV5wFi7LCratBERVT6aiL
…eholder

The shipped Greengrass recipe's default component.tags carried real-looking
sample values (appId: "Test", site: "Chantilly") left over from a specific
deployment. Replace both with "CHANGE_ME" so a fresh deployment is forced to
supply its own values rather than silently inheriting someone else's.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DxV5wFi7LCratBERVT6aiL
The lock committed in 9ba28d6 was wrong: this worktree is nested inside
the main file-replicator checkout (file-replicator/.claude/worktrees/...),
and Cargo's config discovery walks every ancestor directory for a
.cargo/config.toml and merges what it finds. The main checkout's own
gitignored .cargo/config.toml (local-dev sibling override) is therefore
still visible from inside the worktree, so every prior cargo invocation
here silently patched `edgecommons` to the local `core/libs/rust` path
instead of the pinned git rev -- the committed lock recorded `edgecommons
version = "0.3.0"` with no `source` (a path dependency), which cannot
resolve from a fresh clone or CI at all.

Regenerated in a scratch clone outside that directory ancestry (no
.cargo/config.toml in scope), so the `[patch]` override could not apply.
Only the `edgecommons` package's own entry changes (version = "0.2.0",
source = the pinned git rev) -- every transitive dependency resolved
identically, confirming the rest of the graph was never actually affected
by the override.

Re-validated in the same isolated environment: `cargo build/test/clippy
--locked` and the 90%-line coverage gate all green against this corrected
lock; a second fresh clone of this branch builds `--locked` end to end.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DxV5wFi7LCratBERVT6aiL
…cret

Validating the #3 Docker-build-proof requirement turned up two more
problems with the build base bump, on top of the Cargo.lock fix in 2a3e284:

1. `rust:1.88-slim` (the base picked in 9ba28d6) is still not new enough:
   the CORRECTLY git-resolved lock's tree pulls AWS SDK crates that need
   rustc 1.94.1+ (`aws-config`, `aws-sdk-s3`, etc.) and `crc-fast` needs
   1.89+ -- 1.88 was based on the (wrong, path-resolved) lock's older
   transitive versions. Bump to `rust:1.96-slim`, matching config-component's
   `rust:1.96-bookworm` per issue #3's own precedent.

2. The Dockerfile's header comment already promised "pass a GITHUB_TOKEN"
   for the private git dependency, but nothing in the file actually consumed
   one -- there was no way to fetch the dependency in a container with no
   ambient git credentials at all, so the image could not be built to prove
   this out. Wired it up via a BuildKit secret mount (`--mount=type=secret`),
   not a `--build-arg`/`ENV` (Docker's own linter flags build-args as leaking
   into image history/layers for exactly this kind of value).

Verified: `docker build --secret id=github_token,env=GITHUB_TOKEN` builds the
locked tree clean (no linter warnings, no token in `docker history`).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DxV5wFi7LCratBERVT6aiL
@mbreissi
mbreissi marked this pull request as ready for review July 20, 2026 15:31
@mbreissi
mbreissi merged commit 5a2876f into main Jul 20, 2026
4 checks passed
@mbreissi
mbreissi deleted the feat/baseline-adoption branch July 20, 2026 15:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Adopt the CLI-scaffold-parity component baseline License: reconcile license declarations to BSL 1.1 (BUSL-1.1)

1 participant