Merge branch 'main' into fix/222-update-environment-details

Author: krowvin

.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

@@ -46,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

@@ -7,10 +7,16 @@
 from click.core import ParameterSource
 
 from cwmscli.commands import commands_cwms
+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,
@@ -89,6 +95,7 @@ def cli(
 cli.add_command(commands_cwms.clob_group)
 cli.add_command(commands_cwms.users_group)
 cli.add_command(load.load_group)
+cli.add_command(dss_group)
 add_version_to_help_tree(cli)
 
 
@@ -111,9 +118,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(
@@ -122,14 +139,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/dss/__init__.py

@@ -0,0 +1,5 @@
+"""Batch transfers between HEC-DSS files and CWMS Data API instances."""
+
+from cwmscli.dss.cli import dss_group
+
+__all__ = ["dss_group"]