Refactor: unify suews-convert under a single entry point (gh#1304)

The yaml-upgrade subcommand introduced in #1306 was a false split: all
three converter paths (legacy tables, df_state, older YAML) produce the
same artefact - a current-schema YAML - so the CLI only needs one
entry. Per Ting: "output 永远是 current-schema YAML, 没必要分子命令."

  * `src/supy/cmd/table_converter.py`: drop the `yaml-upgrade`
    subcommand; the root `suews-convert -i <in> -o <out> [-f <from>]`
    now auto-detects by file extension and dispatches to
    `upgrade_yaml` for `*.yml`/`*.yaml` inputs in addition to the
    existing table / df_state paths.
  * `-f/--from` loses the hard `click.Choice(list_ver_from)` so it can
    carry a table release, a supy release tag, or a schema version;
    per-input validation now lives in the command body (clear error for
    unknown table releases on nml input).
  * `src/supy/util/converter/__init__.py::detect_input_type` learns
    the `yaml` category so the dispatcher stays ignorant of filename
    conventions.
  * `src/supy/util/converter/yaml_upgrade.py`: drop the unused
    `assume_yes` parameter (YAGNI) and retune the log / error
    messages to reference `-f/--from` instead of the old
    `-f/--from-ver` flag name.
  * `src/supy/data_model/core/config.py`: update the schema-drift hint
    to point at `suews-convert -i <old.yml> -o <new.yml>` (bare
    command when a signature is present, `+ -f <release-tag>` when
    not) - matches the new CLI shape and avoids directing users at a
    command that no longer exists.

Tests updated to exercise the unified path: `test_yaml_upgrade.py::
TestSuewsConvertYamlPath` invokes the root command with a YAML input
(with and without `-f`); `test_from_yaml_errors.py` asserts the
updated hint text. 25 tests in `test/data_model/test_yaml_upgrade.py`
+ `test_release_compat.py` + `test_from_yaml_errors.py` pass; full
`test/data_model/` suite stays at 423 passed / 4 skipped. CLI-surface
tests in `test/core/test_cli_conversion.py` + `test_cli_run.py` still
green (21 passed).

#1306 hadn't been in any release, so no external users are touching
the removed subcommand - the consolidation is pure simplification.

Refs #1301, #1304.

Author: sunt05

CHANGELOG.md

@@ -56,6 +56,10 @@ EXAMPLES:
 
 ### 19 Apr 2026
 
+- [change][experimental] Consolidate `suews-convert` under a single unified entry point (#1304)
+  - Dropped the `yaml-upgrade` subcommand introduced in #1306; the top-level `suews-convert -i <in> -o <out> [-f <from>]` now auto-detects the input type from the file extension and dispatches to the table/`df_state`/YAML-upgrade path accordingly. Output is always a current-schema YAML, regardless of the source format
+  - `-f/--from` loses the `click.Choice(list_ver_from)` constraint so the same flag can carry a table release (`2024a`), a supy release tag (`2026.1.28`) or a schema version (`2025.12`); per-input validation moved into the command body
+  - Loader drift hint in `SUEWSConfig.from_yaml` updated to `suews-convert -i <old.yml> -o <new.yml> [-f <release-tag>]`
 - [feature][experimental] Register `2026.1.28 -> 2025.12` YAML upgrade handler (#1304)
   - New handler `_migrate_pre_setpoint_split_to_2025_12` in `src/supy/util/converter/yaml_upgrade.py` migrates profile-shaped `HeatingSetpointTemperature` / `CoolingSetpointTemperature` fields (pre-#1261) into the post-split `*Profile` + scalar pair, and sets `model.physics.setpointmethod = 2` (SCHEDULED) to preserve the user's profile intent
   - Added vendored release fixture `test/fixtures/release_configs/2026.1.28.yml` (captured from tag `2026.1.28`) and a new `TestReleaseCompat.test_pre_drift_release_upgrades_and_parses` guard that asserts every pre-drift fixture upgrades cleanly and then parses under the current validator

src/supy/cmd/table_converter.py

@@ -15,32 +15,39 @@
     CURRENT_VERSION = None
 
 
-@click.group(
-    invoke_without_command=True,
+@click.command(
     context_settings=dict(show_default=True),
     help=(
-        "Convert between SUEWS input formats.\n\n"
-        "Subcommands:\n"
-        "  yaml-upgrade    Upgrade an existing YAML to the current schema.\n\n"
-        "Default (no subcommand) converts legacy tables or df_state to YAML, "
-        "preserving backward-compatibility with earlier releases. Run "
-        "`suews-convert COMMAND --help` for subcommand-specific help."
+        "Convert any supported SUEWS input into a current-schema YAML.\n\n"
+        "Input type is auto-detected from the file:\n"
+        "  RunControl.nml / *.nml    legacy SUEWS table set\n"
+        "  *.csv / *.pkl             df_state snapshot\n"
+        "  *.yml / *.yaml            older-release YAML (cross-release upgrade)\n\n"
+        "Pass -f/--from to disambiguate the source version when auto-detection "
+        "is ambiguous (table releases for .nml inputs; release tag or schema "
+        "version for .yml inputs)."
     ),
 )
 @click.option(
     "-f",
     "--from",
     "fromVer",
-    help="Version to convert from (auto-detect if not specified)",
-    type=click.Choice(list_ver_from),
+    help=(
+        "Source version. For .nml inputs pick a table release (e.g. 2024a); "
+        "for .yml inputs pass a supy release tag (e.g. 2026.1.28) or a "
+        "schema version. Auto-detected when omitted."
+    ),
     required=False,
     default=None,
 )
 @click.option(
     "-i",
     "--input",
     "input_file",
-    help="Input file: RunControl.nml for tables, or df_state.csv/.pkl",
+    help=(
+        "Input file: RunControl.nml for tables, *.csv/*.pkl for df_state, "
+        "or *.yml/*.yaml for an older YAML config."
+    ),
     type=click.Path(exists=True, dir_okay=False, file_okay=True),
     required=False,
 )
@@ -56,7 +63,10 @@
     "-d",
     "--debug-dir",
     "debug_dir",
-    help="Optional directory to keep intermediate conversion files for debugging. If not provided, temporary directories are removed automatically.",
+    help=(
+        "Optional directory to keep intermediate conversion files for "
+        "debugging table/df_state runs. Ignored for YAML upgrades."
+    ),
     type=click.Path(),
     required=False,
     default=None,
@@ -66,7 +76,10 @@
     "no_validate_profiles",
     is_flag=True,
     default=False,
-    help="Disable automatic profile validation and creation of missing profiles",
+    help=(
+        "Disable automatic profile validation and creation of missing profiles "
+        "(table/df_state paths only)."
+    ),
 )
 @click.pass_context
 def convert_table_cmd(
@@ -77,28 +90,25 @@ def convert_table_cmd(
     debug_dir: str = None,
     no_validate_profiles: bool = False,
 ):
-    """Convert SUEWS inputs to YAML configuration, or upgrade an existing YAML.
+    """Convert any supported SUEWS input to a current-schema YAML.
 
-    Default (no subcommand): converts legacy tables or df_state format to YAML.
-    Input must be a specific file:
-    - RunControl.nml: Converts table-based SUEWS input
-    - *.csv or *.pkl: Converts df_state format
+    The command auto-detects the input format from the file extension and
+    dispatches to the matching converter. All three paths produce a YAML that
+    parses under the current ``SUEWSConfig`` validator.
 
     Examples:
-        # Convert tables to YAML (legacy path)
+        # Legacy tables -> YAML
         suews-convert -i path/to/RunControl.nml -o config.yml
 
-        # Convert old df_state CSV to YAML
+        # df_state snapshot -> YAML
         suews-convert -i df_state.csv -o config.yml
 
-        # Upgrade an existing YAML to the current schema
-        suews-convert yaml-upgrade -i old.yml -o new.yml
-    """
-    if ctx.invoked_subcommand is not None:
-        # A subcommand (e.g. `yaml-upgrade`) handles its own logic; drop
-        # through so Click can dispatch to it.
-        return
+        # Older-release YAML -> current-schema YAML (auto-detect source)
+        suews-convert -i old.yml -o new.yml
 
+        # Older YAML without a schema_version field -> explicit source tag
+        suews-convert -i old.yml -o new.yml -f 2026.1.28
+    """
     if input_file is None or output_file is None:
         click.echo(ctx.get_help())
         sys.exit(0 if (input_file is None and output_file is None) else 2)
@@ -126,7 +136,26 @@ def convert_table_cmd(
             f"Warning: Output file should have .yml or .yaml extension", err=True
         )
 
-    # Handle based on input type
+    # Dispatch on input type
+    if input_type == "yaml":
+        from ..util.converter.yaml_upgrade import YamlUpgradeError, upgrade_yaml
+
+        try:
+            upgrade_yaml(
+                input_path=input_path,
+                output_path=output_path,
+                from_ver=fromVer,
+            )
+        except YamlUpgradeError as e:
+            click.secho(f"[ERROR] {e}", fg="red", err=True)
+            sys.exit(1)
+        except Exception as e:  # noqa: BLE001 - surface unexpected failures verbatim
+            click.secho(f"[ERROR] YAML upgrade failed: {e}", fg="red", err=True)
+            sys.exit(1)
+
+        click.secho(f"\n[OK] Successfully created: {output_path}", fg="green")
+        return
+
     if input_type == "nml":
         # Table conversion
         click.echo(f"Converting SUEWS tables to YAML")
@@ -144,18 +173,24 @@ def convert_table_cmd(
                     "Could not detect version. Use -f to specify.", fg="red", err=True
                 )
                 sys.exit(1)
+        elif fromVer not in list_ver_from:
+            click.secho(
+                f"Unsupported table release: {fromVer}. "
+                f"Supported: {', '.join(list_ver_from)}",
+                fg="red",
+                err=True,
+            )
+            sys.exit(1)
 
     elif input_type == "df_state":
         # df_state conversion
         click.echo(f"Converting df_state to YAML")
         click.echo(f"  Input: {input_path}")
 
         if fromVer:
-            click.echo(
-                "  Note: Version specification ignored for df_state", fg="yellow"
-            )
+            click.echo("  Note: Version specification ignored for df_state")
 
-    # Perform conversion
+    # Perform table / df_state conversion
     try:
         convert_to_yaml(
             input_file=str(input_path),
@@ -171,75 +206,5 @@ def convert_table_cmd(
         sys.exit(1)
 
 
-@convert_table_cmd.command("yaml-upgrade")
-@click.option(
-    "-i",
-    "--input",
-    "input_file",
-    help="Existing YAML configuration to upgrade.",
-    type=click.Path(exists=True, dir_okay=False, file_okay=True),
-    required=True,
-)
-@click.option(
-    "-o",
-    "--output",
-    "output_file",
-    help="Destination for the upgraded YAML.",
-    type=click.Path(dir_okay=False),
-    required=True,
-)
-@click.option(
-    "-f",
-    "--from-ver",
-    "from_ver",
-    help=(
-        "Source release tag or schema version (e.g. '2026.4.3'). "
-        "Omit to auto-detect from the YAML's schema_version field."
-    ),
-    required=False,
-    default=None,
-)
-@click.option(
-    "-y",
-    "--assume-yes",
-    "assume_yes",
-    is_flag=True,
-    default=False,
-    help="Skip confirmation prompts (for CI use).",
-)
-def yaml_upgrade_cmd(
-    input_file: str,
-    output_file: str,
-    from_ver: str,
-    assume_yes: bool,
-):
-    """Upgrade a YAML config from an earlier release to the current schema.
-
-    Examples:
-        # Auto-detect source schema from the YAML's schema_version field
-        suews-convert yaml-upgrade -i old.yml -o new.yml
-
-        # Or specify the release tag explicitly when the file has no signature
-        suews-convert yaml-upgrade -i old.yml -o new.yml -f 2026.4.3
-    """
-    from ..util.converter.yaml_upgrade import YamlUpgradeError, upgrade_yaml
-
-    try:
-        upgrade_yaml(
-            input_path=input_file,
-            output_path=output_file,
-            from_ver=from_ver,
-            assume_yes=assume_yes,
-        )
-    except YamlUpgradeError as e:
-        click.secho(f"[ERROR] {e}", fg="red", err=True)
-        sys.exit(1)
-    except Exception as e:  # noqa: BLE001 - surface unexpected failures verbatim
-        click.secho(f"[ERROR] yaml-upgrade failed: {e}", fg="red", err=True)
-        sys.exit(1)
-
-    click.secho(f"[OK] Upgraded YAML written to {output_file}", fg="green")
-
-
 if __name__ == "__main__":
     convert_table_cmd()

src/supy/data_model/core/config.py

@@ -3667,8 +3667,8 @@ def _transform_validation_error(
 
         `had_signature` carries whether the source YAML actually shipped a
         `schema_version` field. It is forwarded to `_drift_hint` so unsigned
-        YAMLs get a hint that asks for `-f/--from-ver <release-tag>` rather
-        than a bare `yaml-upgrade` command that the CLI would reject.
+        YAMLs get a hint that asks for `-f/--from <release-tag>` rather
+        than a bare `suews-convert` invocation that the CLI would reject.
         """
 
         # Extract GRIDID mapping from sites
@@ -3765,17 +3765,14 @@ def _drift_hint(
             except Exception:  # noqa: BLE001 - detection is best-effort
                 detected = "unspecified"
             detected_line = f"  Detected schema version: {detected}\n"
-            upgrade_cmd = (
-                "suews-convert yaml-upgrade -i <old.yml> -o <new.yml>"
-            )
+            upgrade_cmd = "suews-convert -i <old.yml> -o <new.yml>"
         else:
             detected_line = (
                 "  No schema_version field in YAML "
                 "(predates schema versioning).\n"
             )
             upgrade_cmd = (
-                "suews-convert yaml-upgrade -i <old.yml> -o <new.yml> "
-                "-f <release-tag>"
+                "suews-convert -i <old.yml> -o <new.yml> -f <release-tag>"
             )
 
         return (

src/supy/util/converter/__init__.py

@@ -27,6 +27,7 @@ def detect_input_type(input_file: Union[str, Path]) -> str:
     Returns:
         'nml' for RunControl.nml (table conversion)
         'df_state' for CSV/pickle files
+        'yaml' for an existing YAML configuration (cross-release upgrade)
 
     Raises:
         ValueError: If input is not a file or has unknown extension
@@ -40,18 +41,22 @@ def detect_input_type(input_file: Union[str, Path]) -> str:
         raise ValueError(
             f"Input must be a file, not a directory. Got: {input_path}\n"
             f"For table conversion, specify: path/to/RunControl.nml\n"
-            f"For df_state conversion, specify: path/to/df_state.csv or .pkl"
+            f"For df_state conversion, specify: path/to/df_state.csv or .pkl\n"
+            f"For YAML upgrade, specify: path/to/config.yml"
         )
 
     # Check file type
     if input_path.name == "RunControl.nml" or input_path.suffix == ".nml":
         return "nml"
     elif input_path.suffix in [".csv", ".pkl", ".pickle"]:
         return "df_state"
+    elif input_path.suffix in [".yml", ".yaml"]:
+        return "yaml"
     else:
         raise ValueError(
             f"Unknown input file type: {input_path.suffix}\n"
-            f"Supported: RunControl.nml for tables, .csv/.pkl for df_state"
+            f"Supported: RunControl.nml for tables, .csv/.pkl for df_state, "
+            f".yml/.yaml for cross-release YAML upgrade"
         )
 
 

src/supy/util/converter/yaml_upgrade.py

@@ -206,7 +206,6 @@ def upgrade_yaml(
     input_path: str | Path,
     output_path: str | Path,
     from_ver: str | None = None,
-    assume_yes: bool = False,
 ) -> None:
     """Upgrade a YAML configuration written for an earlier release.
 
@@ -219,9 +218,6 @@ def upgrade_yaml(
     from_ver : str, optional
         Source schema version or release tag. When omitted, the source version
         is auto-detected from the YAML's `schema_version` / `version` field.
-    assume_yes : bool, default False
-        When False and the upgrade path is a no-op, emit a brief status and
-        still write the output. Reserved for future confirmation prompts.
     """
     input_path = Path(input_path)
     output_path = Path(output_path)
@@ -235,7 +231,7 @@ def upgrade_yaml(
         if signature is None:
             raise YamlUpgradeError(
                 "No schema_version field found. This YAML predates the "
-                f"v{CURRENT_SCHEMA_VERSION} schema. Re-run with -f/--from-ver "
+                f"v{CURRENT_SCHEMA_VERSION} schema. Re-run with -f/--from "
                 "<tag> to specify the source version explicitly."
             )
         source_schema = _resolve_package_to_schema(signature)
@@ -244,12 +240,12 @@ def upgrade_yaml(
         source_schema = _resolve_package_to_schema(from_ver)
         if signature is not None and _resolve_package_to_schema(signature) != source_schema:
             _log(
-                f"[yaml-upgrade] WARNING: user-supplied --from-ver={from_ver} "
+                f"[yaml-upgrade] WARNING: user-supplied --from={from_ver} "
                 f"(schema {source_schema}) disagrees with file signature "
                 f"{signature}. Respecting user override."
             )
         else:
-            _log(f"[yaml-upgrade] Using user-supplied --from-ver={from_ver}")
+            _log(f"[yaml-upgrade] Using user-supplied --from={from_ver}")
 
     target_schema = CURRENT_SCHEMA_VERSION
     _log(