cd '/home/vm/code/cwms-cli'

Merge remote-tracking branch 'origin/main' into feature/env-man

Author: msweier

.devcontainer/Dockerfile

@@ -0,0 +1,15 @@
+FROM mcr.microsoft.com/devcontainers/python:1-3.12-bookworm
+
+ARG POETRY_VERSION=2.0.1
+
+ENV TZ=Etc/UTC \
+    POETRY_HOME=/opt/poetry \
+    VIRTUAL_ENV=/home/vscode/.venv \
+    POETRY_VIRTUALENVS_CREATE=false
+ENV PATH="${VIRTUAL_ENV}/bin:${POETRY_HOME}/bin:${PATH}"
+
+RUN python -m venv "${POETRY_HOME}" \
+    && "${POETRY_HOME}/bin/python" -m pip install --no-cache-dir \
+        "poetry==${POETRY_VERSION}" \
+    && python -m venv "${VIRTUAL_ENV}" \
+    && chown -R vscode:vscode "${VIRTUAL_ENV}"

.devcontainer/devcontainer.json

@@ -0,0 +1,27 @@
+{
+  "name": "cwms-cli",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "args": {
+      "POETRY_VERSION": "2.0.1"
+    }
+  },
+  "remoteUser": "vscode",
+  "containerEnv": {
+    "TZ": "Etc/UTC",
+    "POETRY_HOME": "/opt/poetry",
+    "VIRTUAL_ENV": "/home/vscode/.venv",
+    "POETRY_VIRTUALENVS_CREATE": "false"
+  },
+  "postCreateCommand": "git config --global --add safe.directory \"$(pwd)\" && poetry install --with dev --no-interaction",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python"
+      ],
+      "settings": {
+        "python.defaultInterpreterPath": "/home/vscode/.venv/bin/python"
+      }
+    }
+  }
+}

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -8,10 +8,11 @@ body:
       label: CLI Script
       description: Select the script this pertains to
       options:
-        - blob
-        - cwms-cli
-        - csv2cwms
-        - getusgs-measurements
+        - blob
+        - cwms-cli
+        - csv2cwms
+        - dss
+        - getusgs-measurements
         - getusgs-ratings
         - getusgs-timeseries
         - shefcritimport

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -8,10 +8,11 @@ body:
       label: CLI Script
       description: Select the script this pertains to
       options:
-        - blob
-        - cwms-cli
-        - csv2cwms
-        - getusgs-measurements
+        - blob
+        - cwms-cli
+        - csv2cwms
+        - dss
+        - getusgs-measurements
         - getusgs-ratings
         - getusgs-timeseries
         - shefcritimport

.github/workflows/cli-tests.yml

@@ -6,13 +6,27 @@ on:
 
 jobs:
   test:
-    name: Test CLI on ${{ matrix.python-version }}
-    runs-on: ubuntu-latest
+    name: Test CLI on ${{ matrix.name }} with Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
 
     strategy:
+      fail-fast: false
       matrix:
-        # Test 3.9 for T7, 3.12 for general/cloud use
-        python-version: ["3.9", "3.12"]
+        include:
+          # Test the supported Python range on Linux and exercise the primary
+          # Python version on each supported desktop operating system.
+          - name: Linux
+            os: ubuntu-latest
+            python-version: "3.9"
+          - name: Linux
+            os: ubuntu-latest
+            python-version: "3.12"
+          - name: Windows
+            os: windows-latest
+            python-version: "3.12"
+          - name: macOS
+            os: macos-latest
+            python-version: "3.12"
 
     steps:
       - name: Checkout repository
@@ -38,3 +52,17 @@ jobs:
 
       - name: Run full test suite
         run: poetry run pytest -q
+
+  test-devcontainer:
+    name: Test dev container on 3.12
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Build dev container and run tests
+        uses: devcontainers/ci@v0.3
+        with:
+          push: never
+          runCmd: poetry run pytest -q

.github/workflows/release-please.yml

@@ -70,7 +70,7 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
 
       - name: Sign Distribution
-        uses: sigstore/gh-action-sigstore-python@v3.4.0
+        uses: sigstore/gh-action-sigstore-python@v3.5.0
         with:
           inputs: |
             ./dist/*.tar.gz

AGENTS.md

@@ -0,0 +1,36 @@
+# Repository instructions
+
+Guidance for coding agents working in `HydrologicEngineeringCenter/cwms-cli`.
+
+- Never push to `origin` unless the user explicitly says they are ready for
+  that push.
+- Use JDK 21 or newer for new work that is not intended to run on T7 systems.
+  On Windows, use JDK 21 at `C:\Program Files\Java\jdk-21`. On Linux or other
+  Unix-like systems, select an installed JDK 21 or newer through `JAVA_HOME`.
+  Use another Java version only when the target or task requires it.
+- Use the `.devcontainer` Linux/Python 3.12 environment for changes involving
+  time zones, paths, native libraries, HEC-DSS, or other operating-system-
+  dependent behavior.
+- Run the full dev-container test suite with
+  `devcontainer exec --workspace-folder . poetry run pytest -q` when the dev
+  container is available. The standard CI matrix separately covers Python 3.9
+  and Python 3.12 package compatibility.
+
+## Terminal colors
+
+- Use the shared helpers in `cwmscli.utils.colors` for user-facing terminal
+  color. Prefer `colors.ok`, `colors.warn`, `colors.err`, and `colors.dim` for
+  their semantic cases, or `colors.c(text, color, bright=...)` when a specific
+  color is needed.
+- Do not embed ANSI escape sequences or initialize Colorama in individual
+  commands. Global logging setup owns Colorama initialization and calls
+  `colors.set_enabled(...)` so `--no-color`, `--log-file`, and non-TTY output
+  remain consistent.
+- Keep the text meaningful without color. Color should clarify status or
+  structure, not carry information that disappears when color is disabled.
+- Reuse the existing conventions: green for success, yellow for warnings,
+  red for errors, cyan or blue for identifiers and commands, and dim text for
+  secondary detail.
+- When testing colored output, cover the plain-text behavior first. Enable the
+  shared color helper explicitly only in tests that need to assert escape codes,
+  and restore its state afterward.

README.md

@@ -14,14 +14,20 @@ Note: You may need to run `python -m pip install cwms-cli` if PIP is not in your
 
 ### Update
 ```sh
-pip install cwms-cli --upgrade
+python -m pip install --upgrade cwms-cli
 ```
 
 Or as of version `0.3.0+`
 ```sh
 cwms-cli update
 ```
 
+`cwms-cli update` displays the Python executable, environment, package metadata
+location, and editable project location when applicable before asking for
+confirmation. It runs pip through the same Python interpreter that is running
+`cwms-cli`, avoiding accidental updates to a different Python installation or
+virtual environment.
+
 To install a specific version:
 ```sh
 cwms-cli update --target-version 0.7.1 --yes
@@ -40,3 +46,21 @@ from cwmscli.usgs.getusgs_cda import getusgs_cda
 from cwmscli.usgs.getusgs_measurements_cda import getusgs_measurements_cda
 from cwmscli.usgs.getUSGS_ratings_cda import getusgs_rating_cda
 ```
+
+## Development environment
+
+The repository includes a Linux/Python 3.12 development container exercised by
+a dedicated CI job. Open the repository with the VS Code Dev Containers
+extension, or use the Dev Container CLI:
+
+```sh
+devcontainer up --workspace-folder .
+devcontainer exec --workspace-folder . poetry run pytest -q
+```
+
+The container installs project dependencies with Poetry and uses
+`/home/vscode/.venv`, so it does not reuse a host operating system's `.venv`.
+Poetry itself is kept in a separate `/opt/poetry` environment. Use the container
+for changes involving time zones, paths, native libraries, or other
+operating-system-dependent behavior. Standard Python 3.9 and Python 3.12
+installations remain covered by the existing CI matrix.

cwmscli/__main__.py

@@ -8,10 +8,16 @@
 
 from cwmscli.commands import commands_cwms
 from cwmscli.commands.env import env_group
+from cwmscli.dss import dss_group
 from cwmscli.load import __main__ as load
 from cwmscli.usgs import usgs_group
 from cwmscli.utils.click_help import add_version_to_help_tree
-from cwmscli.utils.friendly_errors import to_user_facing_error
+from cwmscli.utils.friendly_errors import (
+    cda_stack_trace,
+    format_cda_stack_trace,
+    to_user_facing_error,
+)
+from cwmscli.utils.links import BUG_REPORT_URL
 from cwmscli.utils.logging import (
     LoggingConfig,
     apply_logging_policies,
@@ -91,6 +97,7 @@ def cli(
 cli.add_command(commands_cwms.users_group)
 cli.add_command(env_group)
 cli.add_command(load.load_group)
+cli.add_command(dss_group)
 add_version_to_help_tree(cli)
 
 
@@ -113,9 +120,19 @@ def main() -> None:
     except SystemExit:
         raise
     except click.ClickException as e:
+        debug = debug or logging.getLogger().isEnabledFor(logging.DEBUG)
+        if debug:
+            server_stack_trace = cda_stack_trace(e)
+            if server_stack_trace is not None:
+                click.echo(format_cda_stack_trace(server_stack_trace), err=True)
+                raise SystemExit(e.exit_code)
         e.show()
         raise SystemExit(e.exit_code)
     except Exception as e:
+        # The environment switch supports failures before Click configures logging.
+        # Once CLI setup has run, --log-level DEBUG enables the same behavior.
+        debug = debug or logging.getLogger().isEnabledFor(logging.DEBUG)
+
         if is_cert_verify_error(e) and not debug:
             # Keep this short, no stack trace.
             logging.error(
@@ -124,14 +141,21 @@ def main() -> None:
             click.echo(ssl_help_text(), err=True)
             raise SystemExit(2)
 
-        if not debug:
+        if debug:
+            server_stack_trace = cda_stack_trace(e)
+            if server_stack_trace is not None:
+                click.echo(format_cda_stack_trace(server_stack_trace), err=True)
+                raise SystemExit(1)
+        else:
             friendly_error = to_user_facing_error(e)
             if friendly_error is not None:
                 logging.debug("Suppressed traceback for CLI exception", exc_info=e)
                 friendly_error.show()
                 raise SystemExit(friendly_error.exit_code)
 
-        # If debug is enabled (or it's not a cert verify error), keep the normal failure behavior.
+        click.echo(f"Unexpected error. Report it at {BUG_REPORT_URL}", err=True)
+        # Preserve raw exception behavior when CDA did not provide a server stack
+        # trace so an issue report includes useful diagnostic details.
         raise
 
 

cwmscli/commands/commands_cwms.py

@@ -1,7 +1,6 @@
 import logging
 import os
 import subprocess
-import sys
 import textwrap
 from pathlib import Path
 from typing import Optional
@@ -26,7 +25,9 @@
 from cwmscli.utils.deps import requires
 from cwmscli.utils.update import (
     build_update_package_spec,
+    get_update_environment,
     launch_windows_update,
+    looks_like_externally_managed_environment,
     looks_like_missing_version,
 )
 from cwmscli.utils.version import get_cwms_cli_version
@@ -416,6 +417,7 @@ def csv2cwms_cmd(**kwargs):
 def update_cli_cmd(target_version: Optional[str], pre: bool, yes: bool) -> None:
     current_version = get_cwms_cli_version()
     package_spec = build_update_package_spec(target_version)
+    update_environment = get_update_environment()
 
     click.echo(
         "Current cwms-cli version: " f"{colors.c(current_version, 'cyan', bright=True)}"
@@ -428,12 +430,35 @@ def update_cli_cmd(target_version: Optional[str], pre: bool, yes: bool) -> None:
     else:
         click.echo("Requested cwms-cli version: latest available release")
 
-    cmd = [sys.executable, "-m", "pip", "install", "--upgrade", package_spec]
+    click.echo("Update environment:")
+    click.echo(f"  Python executable: {update_environment.python_executable}")
+    click.echo(
+        f"  Environment: {update_environment.environment_prefix} "
+        f"({update_environment.environment_type})"
+    )
+    click.echo(f"  Package metadata location: {update_environment.package_location}")
+    if update_environment.editable_project_location:
+        click.echo(
+            "  Editable project location: "
+            f"{update_environment.editable_project_location}"
+        )
+
+    cmd = [
+        update_environment.python_executable,
+        "-m",
+        "pip",
+        "install",
+        "--upgrade",
+        package_spec,
+    ]
     if pre:
         cmd.append("--pre")
 
     if not yes:
-        proceed = click.confirm("Proceed with updating cwms-cli via pip?", default=True)
+        proceed = click.confirm(
+            "Proceed with updating cwms-cli in this environment via pip?",
+            default=True,
+        )
         if not proceed:
             click.echo(colors.warn("Update canceled."))
             return
@@ -472,6 +497,16 @@ def update_cli_cmd(target_version: Optional[str], pre: bool, yes: bool) -> None:
 
     if result.returncode != 0:
         pip_output = "\n".join(part for part in [result.stdout, result.stderr] if part)
+        if looks_like_externally_managed_environment(pip_output):
+            raise click.ClickException(
+                colors.err(
+                    "The selected Python installation is externally managed, so pip "
+                    "refused to update cwms-cli. Install cwms-cli in a virtual "
+                    "environment or with pipx, then run that installation's "
+                    "cwms-cli update command. cwms-cli will not use "
+                    "--break-system-packages automatically."
+                )
+            )
         if target_version and looks_like_missing_version(pip_output, package_spec):
             raise click.ClickException(
                 colors.err(