fix(migrator): add addForeignKeyOptions to PostgreSQL adapter so FK migrations run (#2877)

The PostgreSQL migrator was the only adapter missing
addForeignKeyOptions(sql, options), so any migration emitting an inline
foreign-key constraint — e.g. wheels generate scaffold ... --belongsTo=author —
crashed with "Component [wheels.databaseAdapters.PostgreSQL.PostgreSQLMigrator]
has no function with name [addForeignKeyOptions]" when run against PG. The new
implementation mirrors the MySQL signature; CockroachDB inherits the fix via
its PostgreSQLMigrator subclass.

Fixes #2876

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

Author: wheels-bot[bot]

CHANGELOG.md

@@ -22,6 +22,7 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 
 ### Fixed
 
+- `wheels migrate latest` no longer crashes on PostgreSQL (and CockroachDB) when a migration emits an inline foreign-key constraint — e.g. anything `wheels generate scaffold ... --belongsTo=author` produces. `wheels.databaseAdapters.PostgreSQL.PostgreSQLMigrator` was missing the public `addForeignKeyOptions(sql, options)` method that every other adapter implements (`MySQLMigrator`, `SQLiteMigrator`, `MicrosoftSQLServerMigrator`, `OracleMigrator`); `Abstract.createTable()` builds the inline FK clause via `foreignKeys[i].toForeignKeySQL()` → `ForeignKeyDefinition.cfc` → `adapter.addForeignKeyOptions(...)`, so every PostgreSQL FK column threw `Component [wheels.databaseAdapters.PostgreSQL.PostgreSQLMigrator] has no function with name [addForeignKeyOptions]` and aborted the migration. The new implementation mirrors the MySQL signature (`FOREIGN KEY (col) REFERENCES tbl (refCol)`), which PostgreSQL accepts verbatim, and `CockroachDBMigrator` (which extends `PostgreSQLMigrator`) inherits the fix automatically. The reporter's "works on Windows" observation lined up with the `wheels new` SQLite default — only PostgreSQL/CockroachDB targets ever hit the missing method (#2876)
 - CLI services in `Module.cfc` now instantiate via the module-relative path (`new services.X()`) instead of the absolute FQN (`new cli.lucli.services.X()`), so `wheels new` and the other subcommands resolve their service classes when running from the installed distribution. The module tarball is built with `tar -C cli/lucli .`, which flattens the module root so services live at `<module-root>/services/` with no `cli/lucli/` tree and no `cli.lucli` mapping — the absolute form only resolved against the source-tree layout. That split is why the `fast-test` job (which runs from source, where both forms resolve) stayed green while the snapshot smoke test — which installs the built tarball and runs `wheels new` — failed on every `develop` push since #2861 with `could not find component or class with name [cli.lucli.services.ArgSpec]`. All 8 absolute references (7× `ArgSpec`, 1× the latent `TestRunner` call) are converted to the relative form the 17 sibling services already use; the `ArgSpec` docblock example is updated to match so it cannot re-seed the pattern (#2873)
 - Oracle `DROP TABLE` / `DROP VIEW` in the migrator now work on Oracle 19c/21c. `wheels.databaseAdapters.Oracle.OracleMigrator::dropTable()` emitted `DROP TABLE IF EXISTS <name> CASCADE CONSTRAINTS` and `dropView()` inherited `DROP VIEW IF EXISTS` from `Abstract`, but Oracle only added the `IF EXISTS` DDL modifier in 23c — on 19c/21c both are a hard parse error (ORA-00933). Because the `remove-table` migration template re-throws on error, `migrate down`, rollbacks, `force`-create, and migrator test re-runs failed outright on pre-23c Oracle. Both helpers now emit the version-agnostic Oracle PL/SQL idiom — `BEGIN EXECUTE IMMEDIATE 'DROP TABLE <name> CASCADE CONSTRAINTS'; EXCEPTION WHEN OTHERS THEN IF SQLCODE != -942 THEN RAISE; END IF; END;` — which runs the bare DROP and swallows ORA-00942 ("table or view does not exist"), preserving "drop if exists" semantics on every supported Oracle version with no version detection. `$execute` (`vendor/wheels/migrator/Base.cfc`) never splits on `;` and deliberately omits the trailing-semicolon append for Oracle, so the anonymous block reaches the driver intact. Framework-side counterpart to the demo-app test-populate fix in #2864 (#2869)
 - `application.wheels.protectedControllerMethods` is now populated at application start from the public method surface of `wheels.Global` plus the `wheels.controller.*` and `wheels.view.*` mixin components, so framework helpers like `env()`, `model()`, `findAll()`, `redirectTo()`, and `linkTo()` can no longer be invoked as controller actions from a URL. The list was previously initialized to an empty string (the orphaned `local.allowedGlobalMethods = "get,set,mapper"` line in `onapplicationstart.cfc` pointed to the intent but never wired it up), so `$callAction()`'s allow-list check was a no-op. Any unauthenticated `GET /<anyController>/env` request reached the global `env()` helper directly and raised `"The parameter [name] to function [env] is required but was not passed in."` as a 500; other helper names dispatched into unintended code paths. Derived from `getMetaData().functions` on each source component (excluding `$`-prefixed internal methods, which are already gated separately), so the list stays in sync with the framework's mixin surface automatically. Reaching one of these names now throws `Wheels.ActionNotAllowed` and falls through to the missing-action / 404 path, matching every other non-existent action. **Migration note:** applications that defined controller actions with the same name as a public framework helper (e.g. `env`, `model`, `redirectTo`) will need to rename those actions — they now return 404 rather than dispatching, since the protection gate at `processing.cfc:132` fires before the `StructKeyExists(this, action)` lookup that would otherwise reach a same-named user action (#2844)

vendor/wheels/databaseAdapters/PostgreSQL/PostgreSQLMigrator.cfc

@@ -20,6 +20,24 @@ component extends="wheels.databaseAdapters.Abstract" {
 		return "PostgreSQL";
 	}
 
+	/**
+	 * generates sql fragment for inline foreign key constraint definition,
+	 * used by ForeignKeyDefinition.toForeignKeySQL() (which Abstract.createTable()
+	 * splices into the CREATE TABLE body). Without this, any `t.references()`
+	 * or scaffold `--belongsTo=` on PostgreSQL throws at migrate time. See #2876.
+	 */
+	public string function addForeignKeyOptions(required string sql, struct options = {}) {
+		arguments.sql = arguments.sql & " FOREIGN KEY (" & arguments.options.column & ")";
+		if (StructKeyExists(arguments.options, "referenceTable")) {
+			if (StructKeyExists(arguments.options, "referenceColumn")) {
+				arguments.sql = arguments.sql & " REFERENCES ";
+				arguments.sql = arguments.sql & arguments.options.referenceTable;
+				arguments.sql = arguments.sql & " (" & arguments.options.referenceColumn & ")";
+			}
+		}
+		return arguments.sql;
+	}
+
 	/**
 	 * generates sql for primary key options
 	 */

vendor/wheels/tests/specs/migrator/postgreSQLForeignKeyOptionsSpec.cfc

@@ -0,0 +1,103 @@
+/**
+ * Regression coverage for #2876 — `wheels migrate latest` failed on Linux
+ * whenever a migration ran `t.references()` against PostgreSQL with the
+ * error:
+ *
+ *   Component [wheels.databaseAdapters.PostgreSQL.PostgreSQLMigrator]
+ *   has no function with name [addForeignKeyOptions]
+ *
+ * `Abstract.createTable()` builds the inline FK clause via
+ * `foreignKeys[i].toForeignKeySQL()` → `ForeignKeyDefinition.cfc` →
+ * `adapter.addForeignKeyOptions(sql, options)`. Every other adapter
+ * implements that method (MySQL, SQLite, MSSQL, Oracle); only PostgreSQL
+ * was missing it, so any scaffold that produced an FK column blew up at
+ * migrate time. CockroachDB extends PostgreSQLMigrator and inherited the
+ * same gap.
+ *
+ * These specs run at the adapter unit layer — the adapter is instantiated
+ * directly and `addForeignKeyOptions` is called with the same option
+ * struct shape that `ForeignKeyDefinition::addForeignKeyOptions` builds
+ * (`column`, `referenceTable`, `referenceColumn`). That keeps the
+ * assertions adapter-independent of the currently-configured test
+ * datasource — exactly the pattern referencesSpec.cfc uses for
+ * TableDefinition-layer plumbing.
+ */
+component extends="wheels.WheelsTest" {
+
+	function beforeAll() {
+		variables.pgAdapter = CreateObject("component", "wheels.databaseAdapters.PostgreSQL.PostgreSQLMigrator");
+		variables.cockroachAdapter = CreateObject("component", "wheels.databaseAdapters.CockroachDB.CockroachDBMigrator");
+	}
+
+	function run() {
+
+		describe("PostgreSQLMigrator.addForeignKeyOptions()", () => {
+
+			it("exists as a public method on the adapter", () => {
+				var fns = getMetaData(variables.pgAdapter).functions;
+				var found = false;
+				for (var fn in fns) {
+					if (fn.name == "addForeignKeyOptions") {
+						found = true;
+						break;
+					}
+				}
+				expect(found).toBeTrue();
+			});
+
+			it("appends FOREIGN KEY (col) REFERENCES table (refCol) to the constraint sql", () => {
+				var sql = variables.pgAdapter.addForeignKeyOptions(
+					sql = "CONSTRAINT FK_posts_users",
+					options = {
+						column: "userid",
+						referenceTable: "users",
+						referenceColumn: "id"
+					}
+				);
+				expect(sql).toInclude("FOREIGN KEY");
+				expect(sql).toInclude("userid");
+				expect(sql).toInclude("REFERENCES");
+				expect(sql).toInclude("users");
+				expect(sql).toInclude("id");
+			});
+
+		});
+
+		describe("CockroachDBMigrator inherits the PostgreSQL fix", () => {
+
+			it("exposes addForeignKeyOptions via PostgreSQLMigrator inheritance", () => {
+				var sql = variables.cockroachAdapter.addForeignKeyOptions(
+					sql = "CONSTRAINT FK_posts_users",
+					options = {
+						column: "userid",
+						referenceTable: "users",
+						referenceColumn: "id"
+					}
+				);
+				expect(sql).toInclude("FOREIGN KEY");
+				expect(sql).toInclude("REFERENCES");
+			});
+
+		});
+
+		describe("ForeignKeyDefinition.toForeignKeySQL() integrates with PostgreSQLMigrator", () => {
+
+			it("does not throw when toForeignKeySQL() walks through the PG adapter", () => {
+				var fk = CreateObject("component", "wheels.migrator.ForeignKeyDefinition").init(
+					adapter = variables.pgAdapter,
+					table = "posts",
+					referenceTable = "users",
+					column = "userid",
+					referenceColumn = "id"
+				);
+				var sql = fk.toForeignKeySQL();
+				expect(sql).toInclude("CONSTRAINT");
+				expect(sql).toInclude("FOREIGN KEY");
+				expect(sql).toInclude("REFERENCES");
+			});
+
+		});
+
+	}
+
+}