fix(cli): ship db/ in wheels-base-template by whitelisting db/.keep

changelog.d/3174-base-template-db-directory.fixed.md

@@ -0,0 +1 @@
+- Build: the published `wheels-base-template` zip omitted the conventional `db/` directory because `tools/build/base/.gitignore` carried a `/db/**` rule and CommandBox `package publish` honors `.gitignore`, silently stripping `db/.keep` — so SQLite/H2 file paths under `db/` failed without a manual `mkdir`. The ignore rule now whitelists `!/db/.keep` so the directory ships while end-user db files stay ignored, pinned by a new structural guard spec (`BaseTemplateDbDirectoryShipsSpec`) (#3174)

tools/build/base/.gitignore

@@ -1,2 +1,8 @@
 /vendor/*/
 /db/**
+# Keep the conventional db/ directory in the published template so SQLite/H2
+# file paths under db/ work without a manual `mkdir`. CommandBox `package
+# publish` honors this .gitignore, so without the re-include the `/db/**` rule
+# above strips db/ from the artifact entirely (issue #3174). End-user db files
+# stay ignored; only the directory marker ships.
+!/db/.keep

vendor/wheels/tests/specs/cli/BaseTemplateDbDirectoryShipsSpec.cfc

@@ -0,0 +1,59 @@
+component extends="wheels.WheelsTest" {
+
+	// Regression: the published wheels-base-template 4.0.3 zip omitted the
+	// conventional db/ directory, so SQLite/H2 file paths under db/ failed
+	// without a manual `mkdir`. prepare-base.sh:34 copies db/ into the build
+	// dir, but tools/build/base/.gitignore (shipped as the package .gitignore)
+	// contained `/db/**`, and CommandBox `package publish` honors .gitignore
+	// patterns — so db/.keep was silently stripped from the artifact.
+	//
+	// The fix keeps `/db/**` ignored for end users (their SQLite db files stay
+	// out of git) but whitelists `!/db/.keep` so the directory itself ships.
+	//
+	// A paired presence assertion in the release.yml "Validate Package
+	// Structure" step is deferred to a human follow-up — the wheels-bot
+	// GitHub App token cannot push changes to `.github/workflows/**` without
+	// the `workflows` permission, so the workflow hardening is tracked
+	// separately from this code fix.
+	//
+	// Structural assertion against the source files — actually running
+	// `package publish` from inside a test would require a writable build
+	// context and CommandBox tooling. Reading the source mirrors the
+	// regression-guard pattern in buildArtifactLicenseSpec.cfc and
+	// LinuxPackageStagingSpec.cfc. Issue #3174.
+
+	function run() {
+
+		describe("wheels-base-template ships the conventional db/ directory", () => {
+
+			// expandPath("/wheels") resolves to vendor/wheels via the
+			// configured Lucee mapping; the repo root is two levels above.
+			var repoRoot = expandPath("/wheels/../..");
+			var gitignore = repoRoot & "/tools/build/base/.gitignore";
+
+			it("seeds db/.keep so prepare-base.sh has a directory marker to copy", () => {
+				expect(fileExists(repoRoot & "/db/.keep")).toBeTrue(
+					"db/.keep must exist — prepare-base.sh:34 copies db/ into the build artifact and the keep file is what makes the otherwise-empty directory survive."
+				);
+			});
+
+			it("does not let the template .gitignore strip db/.keep at publish time", () => {
+				expect(fileExists(gitignore)).toBeTrue("Missing file: " & gitignore);
+				var src = fileRead(gitignore);
+
+				// If a /db/ ignore pattern is present, a re-include for the
+				// keep file MUST follow so CommandBox's gitignore-honoring
+				// publish keeps the directory.
+				var ignoresDb = reFindNoCase("(?m)^[[:space:]]*/db/\*\*[[:space:]]*$", src) > 0;
+				var reIncludesKeep = reFindNoCase("(?m)^[[:space:]]*!/db/\.keep[[:space:]]*$", src) > 0;
+
+				expect(!ignoresDb || reIncludesKeep).toBeTrue(
+					"tools/build/base/.gitignore ignores /db/** but does not whitelist !/db/.keep — CommandBox `package publish` honors .gitignore and strips the db/ directory from the published template (issue ##3174). Add `!/db/.keep` so the directory ships while end-user db files stay ignored."
+				);
+			});
+
+		});
+
+	}
+
+}