wheels-base-template package omits the db/ directory — tools/build/base/.gitignore `/db/**` strips it at publish

[bpamiri]

Repro

box install wheels-base-template   # 4.0.3
ls db/
# => doesn't exist

unzip -l wheels-base-template.zip | grep db/ matches nothing.

Expected

The conventional db/ directory ships (the LuCLI wheels new template ships db/), so SQLite/H2 file paths under db/ work without a manual mkdir.

Actual

No db/ in the published zip, even though tools/build/scripts/prepare-base.sh:34 does cp -r db "${BUILD_DIR}/" and db/.keep exists at the v4.0.3 tag.

Root cause

tools/build/base/.gitignore (copied into the build dir as the package .gitignore) contains /db/**, and CommandBox package publish honors .gitignore patterns — so the directory is silently stripped from the zip. Other .keep files (vendor/.keep, tests/_assets/**/.keep) ship fine, confirming it's the ignore pattern, not a .keep/empty-dir limitation.

Suggested fix

Either drop /db/** from tools/build/base/.gitignore and rely on box.json ignore only for publish-time exclusions, or keep the gitignore for end users but whitelist the keep file (!/db/.keep). Add a publish-time assertion (the release.yml 'Validate Package Structure' step) that db/ is present in the prepared directory AND in the final zip.

Evidence from audit journey j1-template-install (wheels-base-template 4.0.3 zip inspected from CommandBox artifact cache, 2026-06-12).

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

The report describes observable wrong behavior — the published wheels-base-template 4.0.3 zip omits the conventional db/ directory ("doesn't exist" / "matches nothing"), even though it should ship so SQLite/H2 paths under db/ work without a manual mkdir. It has a clear "what happened" + "what I expected" + a verified root-cause analysis.

Suspected layer

cli — see .ai/wheels/cli/ for canonical patterns. The defect lives in the build/packaging tooling that produces the wheels-base-template zip, not in framework runtime code.

Fix sketch

Confirmed locally: tools/build/base/.gitignore contains /db/**, and tools/build/scripts/prepare-base.sh:34 does cp -r db "${BUILD_DIR}/" — CommandBox package publish honors the copied .gitignore, so the directory is silently stripped from the zip. The fix is mechanical and small: in tools/build/base/.gitignore, either drop the /db/** line entirely (relying on box.json ignore for publish-time exclusions) or whitelist the keep file (\!/db/.keep). Pair it with a publish-time assertion in the release workflow's "Validate Package Structure" step that db/ is present both in the prepared build dir and in the final zip, to guard against regression.

Confidence: medium

The root cause is verified and the fix shape is a one-line .gitignore change, but it touches the release/build/publish subsystem (tools/build/** + release.yml validation), so per the auto-downgrade rule for the deploy/build pathway it is capped at medium; propose-fix should also confirm the whitelist-vs-drop choice does not re-introduce unwanted files into the published package.

<!-- wheels-bot:triage:3174 -->
<!-- wheels-bot:triage-class:bug -->
<!-- wheels-bot:triage-confidence:medium -->

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #3188

Spec: vendor/wheels/tests/specs/cli/BaseTemplateDbDirectoryShipsSpec.cfc — failing → passing
Implementation: tools/build/base/.gitignore (whitelist !/db/.keep)

The root-cause fix whitelists !/db/.keep in the template .gitignore so the db/ directory marker survives CommandBox's gitignore-honoring publish, while end-user db files stay ignored. The drop-/db/** alternative was rejected because it would un-ignore users' SQLite files.

Deferred to a human follow-up: the publish-time presence assertion in release.yml's "Validate Package Structure" step. The wheels-bot GitHub App token cannot push .github/workflows/** changes without the workflows permission (the push was rejected), so the PR uses Refs #3174 rather than Fixes to avoid auto-closing this issue while that hardening is still pending.

A human review is required before merge. The Reviewer will weigh in shortly. Doc updates (MDX guides, .ai/wheels/, CLAUDE.md) are handled separately by bot-update-docs.yml.

[bpamiri]

Fixed on develop by #3196 (merged): tools/build/base/.gitignore now ignores only /db/.sqlite + /db/.db (not /db/**), so db/ + db/.keep ship in the package.