fix(cli): repoint 15 dead v4-0-0-snapshot and 3.1.0 guide URLs at live v4 pages

[bpamiri]

Summary

Follow-up spotted during the guides-restructure research (#3277): the pre-GA v4-0-0-snapshot docs slug was retired at GA, which killed every templated guide URL still carrying it — including working-with-wheels/* paths that only ever existed in the v3 tree. Freshly scaffolded apps ship comments and READMEs linking 404s, and two runtime CLI messages print dead links. 15 URLs fixed; every replacement target was curl-verified 200 before the swap.

Where	Now points at
scaffold config/settings.cfm + environment.cfm	core-concepts/environments-and-configuration/
scaffold config/routes.cfm + both ConfigRoutes.txt templates	basics/routing/
mailers / jobs / plugins template READMEs	digging-deeper/sending-email/ / background-jobs/ / packages/ (also fixes the bare wheels.dev domain → guides.wheels.dev)
Module.cfc + Doctor.cfc runtime messages	start-here/installing/
cli/README.md (2×)	command-line-tools/
cli/src analyze report footer (wheels.dev/3.1.0-era)	command-line-tools/wheels-commands/code-quality/
demo app config/settings.cfm + environment.cfm (3.1.0-era)	core-concepts/environments-and-configuration/

Spec update

ConfigRoutesStaleDocUrlSpec had the dead snapshot slug pinned as its canonical URL — the guard was enforcing the 404. It now pins the live basics/routing/ URL and gains a structural guard that scans all of cli/lucli/templates/ plus the known runtime-message files for any reintroduction of retired URL shapes (v4-0-0-snapshot, wheels.dev/3.1.0, cfwheels.org-era hosts) — so the next docs-slug migration can't silently strand the templates again.

Verification

• wheels.tests.specs.cli suite passes locally on Lucee 7 + SQLite (127 specs, including the rewritten guard, which fails red if any of the 15 fixed files regresses).
• All 8 distinct replacement URLs verified live (HTTP 200) on guides.wheels.dev.
• Comment/README/message strings only — no executable code paths changed; CI's full CLI suite covers the Module.cfc/Doctor.cfc string touches.

🤖 Generated with Claude Code

[wheels-bot]

Wheels Bot — Reviewer

TL;DR — This PR repoints 15 dead v4-0-0-snapshot / 3.1.0 guide URLs in scaffold templates, runtime CLI messages, and the demo-app config to live guides.wheels.dev/v4-0-0/... pages, and rewrites ConfigRoutesStaleDocUrlSpec into a structural guard against reintroduction. The swaps are correct — I verified all 7 distinct replacement targets exist as real pages under web/sites/guides/src/content/docs/v4-0-0/ (basics/routing.mdx, core-concepts/environments-and-configuration.mdx, digging-deeper/{background-jobs,sending-email,packages}.mdx, start-here/installing.mdx, command-line-tools/wheels-commands/code-quality.mdx). But the sweep and its new guard both miss one demo-app file that carries exactly the shape this PR exists to kill, so my verdict is request changes.

Correctness

config/routes.cfm still ships a dead 3.1.0 URL and the new guard can't catch it.

The demo app's config/routes.cfm:4 still reads:

// See https://wheels.dev/3.1.0/guides/handling-requests-with-controllers/routing for more info.

This is a retired wheels.dev/3.1.0 shape — a 404 — and it was left untouched even though the PR body states "the demo app's config all linked 404s. All were repointed." Its two same-directory siblings (config/settings.cfm, config/environment.cfm) were both fixed and both added to the new guard's extraFiles list (vendor/wheels/tests/specs/cli/ConfigRoutesStaleDocUrlSpec.cfc:72-73), but config/routes.cfm is in neither the fix set nor extraFiles, and it doesn't live under cli/lucli/templates/, so the recursive scan (spec lines 78-87) never reaches it. The new "Retired guide URL shapes" test therefore passes green while a dead link still ships — the exact silent-strand failure the guard is meant to prevent.

Fix: repoint that comment to https://guides.wheels.dev/v4-0-0/basics/routing/ (matching the cli/lucli/templates/app/config/routes.cfm template this PR already fixed), and add "config/routes.cfm" to extraFiles in the spec so the guard actually covers it.

Confirmation command:

$ git grep -nI -e "wheels.dev/3.1.0" -- config/routes.cfm
config/routes.cfm:4:// See https://wheels.dev/3.1.0/guides/handling-requests-with-controllers/routing for more info.

Docs

Minor / non-blocking: this is a user-facing fix (freshly scaffolded apps stop shipping 404 links, and two runtime CLI messages are corrected), so per CLAUDE.md § "Changelog entries" it would normally carry a changelog.d/<slug>.fixed.md fragment. None is present in the diff. Optional, but worth adding for the release notes.

Cross-engine

No concerns. The rewritten spec uses only portable builtins (directoryList, fileRead, fileExists, reFindNoCase, findNoCase, arrayAppend) and the pre-existing IIFE loop-variable capture pattern; no struct member-function collisions, no local in catch/finally, no bare cfabort.

Commits

fix(cli): repoint 15 dead v4-0-0-snapshot and 3.1.0 guide URLs at live v4 pages — valid conventional-commit header, well under 100 chars, describes the why. Good.

Once config/routes.cfm is repointed and added to the guard, this is a clean, self-protecting fix.

[wheels-bot]

Wheels Bot — Reviewer

TL;DR — This PR repoints 15 dead v4-0-0-snapshot / 3.1.0 guide URLs in scaffold templates, two runtime CLI messages, and the demo-app config to live guides.wheels.dev/v4-0-0/... pages, rewrites ConfigRoutesStaleDocUrlSpec into a structural guard against reintroduction, and adds a CI fix so the CommandBox smoke job installs git before checkout. The URL swaps are correct — I re-verified all replacement targets exist under web/sites/guides/src/content/docs/v4-0-0/ (basics/routing.mdx, core-concepts/environments-and-configuration.mdx, digging-deeper/background-jobs.mdx, digging-deeper/sending-email.mdx, digging-deeper/packages.mdx, start-here/installing.mdx, command-line-tools/wheels-commands/code-quality.mdx), and the new CI step is sound. But the blocking finding from the previous review is still unresolved at this head — the new commit (ea73beed) is CI-only — so my verdict remains request changes.

Correctness

config/routes.cfm still ships a dead 3.1.0 URL and the new guard still cannot catch it. (carried over from the prior review — unaddressed by ea73beed)

The demo app's config/routes.cfm:4 still reads:

// See https://wheels.dev/3.1.0/guides/handling-requests-with-controllers/routing for more info.

This is a retired wheels.dev/3.1.0 shape — a 404 — and it is the only remaining retired URL shape anywhere under cli/ or config/:

$ git grep -nI -e "wheels.dev/3.1.0" -e "v4-0-0-snapshot" -- cli/ config/
config/routes.cfm:4:// See https://wheels.dev/3.1.0/guides/handling-requests-with-controllers/routing for more info.

Its two same-directory siblings (config/settings.cfm, config/environment.cfm) were both fixed and added to the guard's extraFiles list (vendor/wheels/tests/specs/cli/ConfigRoutesStaleDocUrlSpec.cfc:72-73), but config/routes.cfm is in neither the fix set (it is not in this PR's file list) nor extraFiles, and it does not live under cli/lucli/templates/, so the recursive scan (ConfigRoutesStaleDocUrlSpec.cfc:78-87) never reaches it. The new "Retired guide URL shapes" test therefore passes green while a dead link still ships — the exact silent-strand failure the guard is meant to prevent. The PR body also asserts "the demo app's config all linked 404s ... All were repointed," which this file contradicts.

Fix: repoint config/routes.cfm:4 to https://guides.wheels.dev/v4-0-0/basics/routing/ (matching the cli/lucli/templates/app/config/routes.cfm template this PR already fixed), and add config/routes.cfm to extraFiles at ConfigRoutesStaleDocUrlSpec.cfc:66-74 so the guard actually covers it.

Cross-engine

No concerns. The rewritten spec uses only portable builtins (directoryList, fileRead, fileExists, reFindNoCase, findNoCase, arrayAppend) plus the pre-existing IIFE loop-variable capture; no struct member-function collisions, no local in catch/finally, no bare cfabort. The CI workflow change is shell/YAML only.

Tests

The new CI step (.github/workflows/commandbox-install-smoke.yml) is correct: tools/ and cli/ are both export-ignore in .gitattributes:5-6, so a tarball checkout would strip tools/build/scripts/prepare-base.sh (which exists) — installing git before actions/checkout and asserting the path checked out is the right guard. Good defensive addition.

Docs

Minor / non-blocking: this is a user-facing fix (freshly scaffolded apps stop shipping 404 links; two runtime CLI messages corrected), so per CLAUDE.md section "Changelog entries" it would normally carry a changelog.d/<slug>.fixed.md fragment. None is present. Optional, but worth adding for the release notes.

Commits

Both commits are valid conventional-commit headers well under 100 chars and describe the why:

• fix(cli): repoint 15 dead v4-0-0-snapshot and 3.1.0 guide URLs at live v4 pages
• ci: install git before checkout in the CommandBox smoke container

Once config/routes.cfm:4 is repointed and added to the guard's extraFiles, this is a clean, self-protecting fix.

[wheels-bot]

Wheels Bot — Reviewer

TL;DR — This PR repoints the dead v4-0-0-snapshot / wheels.dev/3.1.0 guide URLs across scaffold templates, two runtime CLI messages, cli/README.md, the analyze report footer, and the demo-app config to live guides.wheels.dev/v4-0-0/... pages, rewrites ConfigRoutesStaleDocUrlSpec into a structural guard against reintroduction, adds a changelog fragment, and adds a CI fix so the CommandBox smoke job installs git before checkout. The one blocking finding from my previous two reviews is now resolved by 315ad1822, and no new blocking issue fires — verdict approve. (This approval also supersedes the still-active CHANGES_REQUESTED from the earlier heads; per issue #3048 a --comment re-review could not clear it.)

Resolved (previously blocking)

config/routes.cfm dead 3.1.0 URL + guard gap — FIXED. My two prior reviews (on 00faa6c2 and ea73beed) blocked on the demo app's config/routes.cfm:4 still shipping https://wheels.dev/3.1.0/guides/handling-requests-with-controllers/routing while sitting outside both the fix set and the new guard's scan. Commit 315ad1822 closes both halves:

• config/routes.cfm:4 now reads // See https://guides.wheels.dev/v4-0-0/basics/routing/ for more info. — matching the cli/lucli/templates/app/config/routes.cfm template.
• config/routes.cfm was added to extraFiles in vendor/wheels/tests/specs/cli/ConfigRoutesStaleDocUrlSpec.cfc:74, so the guard now actually covers it.

Confirmed clean — no retired shapes remain anywhere under cli/ or config/:

```
$ git grep -nI -e "wheels.dev/3.1.0" -e "v4-0-0-snapshot" -e "docs.cfwheels.org" -- cli/ config/
(no output)
```

Correctness

All replacement targets exist as real pages under web/sites/guides/src/content/docs/v4-0-0/: basics/routing.mdx, core-concepts/environments-and-configuration.mdx, digging-deeper/{background-jobs,sending-email,packages}.mdx, start-here/installing.mdx, and command-line-tools/wheels-commands/code-quality.mdx. No dead-link risk in the swaps.

Cross-engine

No concerns. The rewritten spec uses only portable builtins (directoryList, fileRead, fileExists, reFindNoCase, findNoCase, arrayAppend, arrayToList) plus the pre-existing IIFE loop-variable capture; the second describe block doesn't loop, so its it closure references to repoRoot/extraFiles/templateRoot are safe. No struct member-function collisions, no local in catch/finally, no bare cfabort. The CI change is shell/YAML only.

Tests

The guard is now self-protecting and covers the file that previously slipped through. The CI step is sound: cli/ and tools/ are both export-ignore (.gitattributes:5-6), so a tarball checkout would strip tools/build/scripts/prepare-base.sh (which exists) — installing git before actions/checkout@v5 and asserting the path checked out is the correct guard against the exit-127 failures described.

Docs

Non-blocking nit: the changelog fragment (changelog.d/fix-dead-guide-urls.fixed.md) and PR body say "16" URLs, but the PR title still reads "15" — the demo-app config/routes.cfm fix in 315ad1822 was the 16th. Since the repo squash-merges, consider bumping the title to ...16 dead... for an accurate landing-commit subject. Not a commitlint violation and not merge-blocking.

Commits

All three commits are valid conventional-commit headers, well under 100 chars, and describe the why:

• fix(cli): repoint 15 dead v4-0-0-snapshot and 3.1.0 guide URLs at live v4 pages
• ci: install git before checkout in the CommandBox smoke container
• fix: repoint the demo app routes.cfm guide URL and cover it in the guard

Clean, self-protecting fix. Nice work closing the guard gap.