refactor(cli): finish #2861 ArgSpec migration and remove the getArgs round-trip (#2875)

* feat(cli): add ArgSpec.toArgv() non-lossy collection->argv passthrough (#2861)

* refactor(cli): migrate generate/create/db/browser/deploy/packages/migrate/start to ArgSpec.toArgv (#2861)

* refactor(cli): remove getArgs()/argsFromCollection() shim now that every call site is on ArgSpec (#2861)

* docs(cli): update ArgSpec header for completed #2861 migration

* test(cli): assert wheels new --no-sqlite creates no datasource end-to-end (#2861)

* docs(cli): changelog for completed #2861 ArgSpec migration + shim removal

Author: bpamiri

CHANGELOG.md

@@ -38,6 +38,7 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 
 - The `console` and `test` CLI subcommands now consume LuCLI's structured `argCollection` directly via `cli.lucli.services.ArgSpec` (`parseConsoleArgs` / `parseTestArgs` calling `.parse(structuredArgs(arguments))`), continuing the #2861 migration (whose `ArgSpec` foundation shipped in #2862) past the eight leaf commands. `console` reads `--password=<value>`; `test` reads `--filter` (and its documented `--directory` alias), `--reporter`, `--db` (tracked as explicit so the runner distinguishes an implicit default from a chosen one), the `--verbose` / `--ci` / `--core` flags, `--no-test-db` (test-db=false), a bare positional filter, and the `-v` shorthand (which LuCLI delivers as a positional). Both also fix the latent `arg1`-gate the round trip masked: named-only invocations like `wheels console --password=x` and `wheels test --core` (no positional) now take effect instead of silently running with defaults. **One deliberate behavioral delta per command:** the space-separated option forms (`wheels console --password secret`, `wheels test --filter models`) are dropped for the `--key=value` forms — LuCLI delivers a space-separated value as a bare flag plus a separate positional, never a named value. Everything else is preserved: `test`'s APP-vs-`--core` mode default, `$normalizeTestFilter` short-name normalization, and the full `runTests(...)` argument set; `console`'s reload-password auto-detection when none is supplied. Covered by 13 new server-free specs in `cli/lucli/tests/specs/commands/CommandArgParsingSpec.cfc` (via `ModuleArgvProbe`). This leaves the dispatchers (`generate`, `create`, `db`, `browser`), the parser-delegating `deploy` / `packages` / `migrate`, and the LuCLI-passthrough `start` on the `getArgs()` shim, which is removed once those are converted (#2861)
 - Eight leaf CLI subcommands — `new`, `seed`, `notes`, `analyze`, `doctor`, `stats`, `upgrade`, and `destroy` — now consume LuCLI's structured `argCollection` directly via `cli.lucli.services.ArgSpec` (`.parse(structuredArgs(arguments))`) instead of flattening it back to argv and re-parsing with a hand-rolled token loop (the round trip tracked in #2861, whose `ArgSpec` foundation shipped in #2862). Beyond removing the per-command parsing duplication, this fixes a latent bug the round trip masked: the legacy `getArgs()` only rebuilt argv when a positional `arg1` was present, so **named-only** invocations were silently dropped one layer in — `wheels seed --environment=production`, `wheels doctor --verbose`, `wheels stats --verbose`, and `wheels notes --annotations=...` all ran with defaults regardless of what the user passed. Consuming the structured map directly means the named keys (and `--no-X` negations) survive. **One deliberate behavioral delta:** `wheels new` with options but no app name (e.g. `wheels new --no-sqlite`) now errors with the #2214 `Wheels.InvalidArguments` "app name required" exception instead of falling through to the usage guide — previously the `arg1`-gate dropped the named-only args, leaving an empty arg list that took the usage branch. Everything else is preserved: each command keeps its usage branches and the #2214 throw, `destroy`'s `<type> <name>` / `<name> <type>` smart reorder (now gap-tolerant, so `--force` may appear before or after the positionals), `upgrade`'s `check`-gate and `--dry-run` / `--to` "did you mean" nudge, and `doctor` / `stats`'s `-v` shorthand (which LuCLI delivers as a positional, not a flag). A new private `structuredArgs()` / `argvToCollection()` helper pair sources the collection — preferring LuCLI's live handoff and reconstructing it from the instance-level `__arguments` fallback for internal delegation (e.g. `create` → `new`) and unit tests. The migrated parse logic is covered by server-free specs in `cli/lucli/tests/specs/commands/CommandArgParsingSpec.cfc` (via `ModuleArgvProbe`). `getArgs()` / `argsFromCollection()` remain as the deprecated shim for the not-yet-migrated commands — the dispatchers (`generate`, `create`, `db`, `browser`), the parser-delegating `deploy` / `packages`, `migrate`, and the space-separated-flag `test` / `console` — and the shim is removed once those are converted (#2861)
+- The final eight CLI subcommands — the dispatchers `generate`, `create`, `db`, `browser`; the parser-delegating `deploy`, `packages`, `migrate`; and the LuCLI-passthrough `start` — now source LuCLI's structured `argCollection` through `structuredArgs(arguments)` and reconstruct argv once via the new `cli.lucli.services.ArgSpec.toArgv()` passthrough, instead of the per-command `getArgs()` / `argsFromCollection()` round trip. With every call site converted, the `getArgs()` / `argsFromCollection()` shim is **removed** from `Module.cfc`, completing the #2861 migration (whose `ArgSpec` foundation shipped in #2862 and whose leaf/`console`/`test` batches landed in #2872 and #2874). These commands forward to downstream consumers that take a flat argv array (the deep `generate` sub-handlers, the unit-tested `DeployArgsParser` and packages parsers, `runForgetOrPretend`, and LuCLI's own `server start`), so the maintainer-chosen passthrough keeps those parsers — and their dedicated test suites — unchanged rather than rewriting them. `toArgv()` is non-lossy: it re-emits `--no-X` for `key=false` (the #2856 fix, now centralized in one tested place) so negations like `--no-routes` / `--no-migration` survive. The migration is behavior-preserving — `structuredArgs()` and the deleted `getArgs()` read the `__arguments` fallback identically, and `toArgv()` copies `argsFromCollection()`'s emit logic exactly — and incidentally retires the same `arg1`-gate latent bug the leaf-command migration did: `wheels start --force` with no positional previously fell through to an empty arg list. The #2855 `--no-sqlite` negation is now pinned end-to-end by a new assertion in `tools/test-onboarding.sh` (real CLI → LuCLI → ArgSpec → scaffolder: no `db/*.sqlite` files, `lucee.json` `configuration.datasources == {}`), closing the test-robustness gap the #2856 unit test left open. `argsFromCollection`'s unit coverage moved to `ArgSpec.toArgv` specs; the `getArgs` arg1-gate regression spec was retired with the function. Closes #2861
 - Reconcile bot pipeline unblock plan doc with shipped implementation: mark checkboxes as historically complete and align the allowlist note with the final `classify-conflicts.sh`
 - Version switcher now labels the 4.0 stable docs "v4.0 (current)" (was "v4.0.0"); the vestigial pre-GA `v4-0-1-snapshot` guides tree is removed and its one unique page, "Reading the Changelog", is salvaged into `v4-0-0/upgrading/`. Both sites deploy from `develop`, so in-progress patch docs already live in the `v4-0-0` tree; a separate `*-snapshot` tree is only warranted when a different minor/major (e.g. `v4-1-snapshot`) is under development. Courtesy redirects cover the high-traffic `/v4-0-1-snapshot/*` paths (#2827)
 - CLI path normalisation now lives in a single, unit-tested `Helpers.normalizePath()`; `Module.$normalizePath()` (added in #2835 to fix the Windows `Resource provider [c]` crash) delegates to it instead of carrying a private copy, so the regression coverage exercises the real bootstrap path rather than a decoy. The CLI installation guide also gains a Windows troubleshooting entry for the original `there is no Resource provider available with the name [c]` error (#2841)

cli/lucli/Module.cfc

@@ -83,69 +83,6 @@ component extends="modules.BaseModule" {
 		}
 	}
 
-	/**
-	 * Extract positional arguments from LuCLI's argCollection or __arguments.
-	 *
-	 * LuCLI dispatches module subcommands as:
-	 *   module.subcommand(argumentCollection={arg1:"val1", arg2:"val2", ...})
-	 * where argCollection contains positional args as arg1..argN keys.
-	 *
-	 * Falls back to __arguments (minus the subcommand at index 1) for
-	 * direct CFC invocation in tests.
-	 */
-	private array function getArgs(struct callerArgs = {}) {
-		// Prefer caller's arguments (LuCLI passes argCollection which spreads
-		// positional args as arg1, arg2, ... into the function's arguments scope)
-		if (structKeyExists(callerArgs, "arg1")) {
-			return argsFromCollection(callerArgs);
-		}
-
-		// Fallback: __arguments (direct invocation / tests)
-		var raw = __arguments ?: [];
-		if (isArray(raw) && arrayLen(raw) > 0) {
-			return raw;
-		}
-		return [];
-	}
-
-	/**
-	 * Reconstruct args array from LuCLI's argCollection.
-	 * Positional args are stored as arg1, arg2, ... (order matters).
-	 * Named args (--key=value) are stored as key=value and must be
-	 * re-prefixed with -- so parseGeneratorArgs() can parse them.
-	 */
-	private array function argsFromCollection(required struct coll) {
-		var result = [];
-
-		// Extract positional args in order
-		var i = 1;
-		while (structKeyExists(coll, "arg#i#")) {
-			arrayAppend(result, coll["arg#i#"]);
-			i++;
-		}
-
-		// Re-add named args as --key=value flags
-		for (var key in coll) {
-			if (reFindNoCase("^arg\d+$", key)) continue; // skip positional
-			var value = coll[key];
-			if (isSimpleValue(value) && value == "true") {
-				// Boolean flag: --key
-				arrayAppend(result, "--" & key);
-			} else if (isSimpleValue(value) && value == "false") {
-				// LuCLI converts the user's `--no-key` into key=false on the
-				// argCollection it hands modules. Re-emit `--no-key` so the
-				// downstream literal-token matchers (`wheels new --no-sqlite`,
-				// `wheels g admin --no-routes`, etc.) see the user's negation
-				// instead of silently dropping it. Issue #2855.
-				arrayAppend(result, "--no-" & key);
-			} else if (isSimpleValue(value)) {
-				arrayAppend(result, "--" & key & "=" & value);
-			}
-		}
-
-		return result;
-	}
-
 	/**
 	 * Source the structured argument collection LuCLI handed this command.
 	 *
@@ -364,7 +301,7 @@ component extends="modules.BaseModule" {
 	 * hint: Generate Wheels components (model, controller, view, migration, scaffold, route, test, property, api-resource, helper, snippets)
 	 */
 	public string function generate() {
-		var args = getArgs(arguments);
+		var args = new services.ArgSpec().toArgv(structuredArgs(arguments));
 
 		if (!arrayLen(args)) {
 			out("Usage: wheels generate <type> <name> [attributes...]", "yellow");
@@ -457,7 +394,7 @@ component extends="modules.BaseModule" {
 	 * hint: Run database migrations (latest, up, down, info)
 	 */
 	public string function migrate() {
-		var args = getArgs(arguments);
+		var args = new services.ArgSpec().toArgv(structuredArgs(arguments));
 		var action = arrayLen(args) ? lCase(args[1]) : "latest";
 
 		switch (action) {
@@ -724,7 +661,7 @@ component extends="modules.BaseModule" {
 	 * hint: Start the Wheels development server via LuCLI
 	 */
 	public string function start() {
-		var args = getArgs(arguments);
+		var args = new services.ArgSpec().toArgv(structuredArgs(arguments));
 
 		// Refuse to start from a non-Wheels-project directory. LuCLI's
 		// `server start` derives the server name from the cwd basename and
@@ -983,7 +920,7 @@ component extends="modules.BaseModule" {
 	 * hint: Create application components (wheels create app <name> [options])
 	 */
 	public string function create() {
-		var args = getArgs(arguments);
+		var args = new services.ArgSpec().toArgv(structuredArgs(arguments));
 
 		if (!arrayLen(args)) {
 			out("Usage: wheels create <type> <name> [options]", "yellow");
@@ -1980,7 +1917,7 @@ component extends="modules.BaseModule" {
 	 *   wheels deploy version                  - show version pinning
 	 */
 	public string function deploy() {
-		var args = getArgs(arguments);
+		var args = new services.ArgSpec().toArgv(structuredArgs(arguments));
 		var opts = $deployArgsToOptions(args);
 		if (!structKeyExists(opts, "configPath") || !len(opts.configPath)) {
 			opts.configPath = expandPath("config/deploy.yml");
@@ -2289,7 +2226,7 @@ component extends="modules.BaseModule" {
 	 *   wheels packages registry info
 	 */
 	public string function packages() {
-		var args = getArgs(arguments);
+		var args = new services.ArgSpec().toArgv(structuredArgs(arguments));
 		var opts = $packagesArgsToOptions(args);
 		var positional = $packagesStripFlags(args);
 		var sub = arrayLen(positional) >= 1 ? positional[1] : "list";
@@ -2603,7 +2540,7 @@ component extends="modules.BaseModule" {
 	 * hint: Database management commands (reset, status, version)
 	 */
 	public string function db() {
-		var args = getArgs(arguments);
+		var args = new services.ArgSpec().toArgv(structuredArgs(arguments));
 
 		if (!arrayLen(args)) {
 			out("Usage: wheels db <command>", "yellow");
@@ -2720,7 +2657,7 @@ component extends="modules.BaseModule" {
 	 * hint: Browser testing commands (setup, test)
 	 */
 	public string function browser() {
-		var args = getArgs(arguments);
+		var args = new services.ArgSpec().toArgv(structuredArgs(arguments));
 
 		if (!arrayLen(args)) {
 			out("Usage: wheels browser <command>", "yellow");

cli/lucli/services/ArgSpec.cfc

@@ -9,12 +9,14 @@
  * loop — a round trip that silently dropped `false` values (the root cause
  * of #2855) and could not distinguish `--no-X` from an explicit `--X=false`.
  *
- * `ArgSpec` consumes LuCLI's structured map directly. Each command declares
- * its positionals, flags, and options up front; `.parse(arguments)` returns
- * a typed result struct. No flatten, no re-parse, no lossy `false` round
- * trip. Designed to be adopted incrementally — `getArgs()` and
- * `argsFromCollection()` stay in place as a deprecated shim until every
- * call site is converted.
+ * `ArgSpec` consumes LuCLI's structured map directly. Each command either
+ * declares its positionals, flags, and options up front and calls
+ * `.parse(arguments)` for a typed result struct, or — when it forwards to its
+ * own downstream argv parser (generate, deploy, packages, ...) — calls
+ * `.toArgv(arguments)` for a non-lossy collection->argv reconstruction. Either
+ * way: no per-command flatten, no re-parse, no lossy `false` round trip. The
+ * Module.cfc getArgs()/argsFromCollection() shim this replaced has been removed
+ * now that every call site is converted (#2861).
  *
  * Usage:
  *
@@ -114,6 +116,52 @@ component {
 		return result;
 	}
 
+	/**
+	 * Reconstruct LuCLI's ordered argv from a structured argCollection.
+	 *
+	 * The inverse of LuCLI's parse: positionals (arg1, arg2, ...) emit first
+	 * in index order, then named keys emit as `--key` (true), `--no-key`
+	 * (false), or `--key=value`. This is the non-lossy passthrough that
+	 * commands with their own downstream argv parsers (generate, create, db,
+	 * browser, deploy, packages, migrate, start) use to forward LuCLI's
+	 * structured handoff to a flat-array parser — replacing the Module.cfc
+	 * getArgs()/argsFromCollection() round trip (#2855, #2861).
+	 *
+	 * Contract dependency: LuCLI's parseArguments() normalizes `--no-X` to
+	 * `X=false` and bare `--X` to `X=true` before dispatch. The `value=="false"`
+	 * arm re-emits `--no-X` so downstream literal-token matchers (e.g.
+	 * `--no-routes`, `--no-migration`) still see the user's negation (#2856).
+	 */
+	public array function toArgv(required struct coll) {
+		var result = [];
+
+		// Positionals in arg1..argN order. Stops at the first index gap,
+		// mirroring the legacy argsFromCollection — dispatchers always pass
+		// the sub-verb as the leading positional, so a gap never elides one.
+		var i = 1;
+		while (structKeyExists(arguments.coll, "arg" & i)) {
+			arrayAppend(result, arguments.coll["arg" & i]);
+			i++;
+		}
+
+		// Named keys, re-prefixed. --no-X for false preserves the negation.
+		for (var key in arguments.coll) {
+			if (reFindNoCase("^arg\d+$", key)) {
+				continue;
+			}
+			var value = arguments.coll[key];
+			if (isSimpleValue(value) && value == "true") {
+				arrayAppend(result, "--" & key);
+			} else if (isSimpleValue(value) && value == "false") {
+				arrayAppend(result, "--no-" & key);
+			} else if (isSimpleValue(value)) {
+				arrayAppend(result, "--" & key & "=" & value);
+			}
+		}
+
+		return result;
+	}
+
 	private any function $coerce(required any v, required string type) {
 		switch (arguments.type) {
 			case "boolean":

cli/lucli/tests/_fixtures/commands/ModuleArgvProbe.cfc

@@ -7,9 +7,7 @@
  * public pass-throughs so specs can unit-test the parsing layer without
  * booting a server or triggering command side effects.
  *
- *   - $argsFromCollection : the legacy argv-rebuild shim (issue #2855)
  *   - $structuredArgs / $argvToCollection : the ArgSpec sourcing layer (#2861)
- *   - $getArgs : the legacy flat-argv accessor, for regression characterization
  *   - $parse<Command>Args : per-command parse helpers migrated to ArgSpec
  *
  * Some helpers read the instance-level __arguments fallback. That value lives
@@ -22,15 +20,6 @@
  */
 component extends="cli.lucli.Module" {
 
-	public array function $argsFromCollection(required struct coll) {
-		return argsFromCollection(arguments.coll);
-	}
-
-	public array function $getArgs(struct callerArgs = {}, array underscoreArguments = []) {
-		variables.__arguments = arguments.underscoreArguments;
-		return getArgs(arguments.callerArgs);
-	}
-
 	public struct function $argvToCollection(required array argv) {
 		return argvToCollection(arguments.argv);
 	}

cli/lucli/tests/specs/commands/CommandArgParsingSpec.cfc

@@ -3,16 +3,14 @@
  *
  * These specs exercise Module.cfc's arg-sourcing layer ($structuredArgs /
  * $argvToCollection) and the per-command parse helpers that replaced the
- * hand-rolled getArgs() token loops. They run against the structured
- * argCollection LuCLI actually hands each command — no server, no command
- * side effects — via ModuleArgvProbe.
+ * hand-rolled token loops. They run against the structured argCollection LuCLI
+ * actually hands each command — no server, no command side effects — via
+ * ModuleArgvProbe.
  *
- * Two behavioral facts they pin:
- *   1. The legacy getArgs() arg1-gate silently dropped named-only invocations
- *      (e.g. `wheels seed --environment=x`, `wheels doctor --verbose`) because
- *      those collections carry no positional arg1. ArgSpec consumes the named
- *      keys directly, so the migration fixes that latent drop.
- *   2. `--no-X` negations survive structurally (no flatten/re-parse round trip).
+ * The behavioral fact they pin: `--no-X` negations and named-only invocations
+ * (e.g. `wheels seed --environment=x`, `wheels doctor --verbose`) survive
+ * structurally, because ArgSpec consumes the named keys directly instead of the
+ * old flatten/re-parse round trip that dropped them.
  */
 component extends="wheels.wheelstest.system.BaseSpec" {
 
@@ -75,17 +73,6 @@ component extends="wheels.wheelstest.system.BaseSpec" {
 
 		});
 
-		describe("regression: legacy getArgs() dropped named-only invocations", () => {
-
-			it("returns [] for a named-only collection (no arg1) — the latent bug ArgSpec fixes", () => {
-				// `wheels seed --environment=x` / `wheels doctor --verbose` arrive as
-				// {environment:"x"} / {verbose:"true"} with no arg1, so the arg1-gated
-				// getArgs() fell through to the empty __arguments fallback.
-				expect(probe.$getArgs({verbose: "true"}, [])).toBeEmpty();
-			});
-
-		});
-
 		describe("parseNewArgs", () => {
 
 			it("binds the app name positional", () => {