Merge branch 'main' into ownership-metadata-refresh

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

AGENTS.md

@@ -1,7 +1,21 @@
-# AGENTS.md
+# 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

README.md

@@ -40,3 +40,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,6 +7,7 @@
 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
@@ -15,6 +16,7 @@
     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,
@@ -93,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)
 
 
@@ -148,8 +151,9 @@ def main() -> None:
                 friendly_error.show()
                 raise SystemExit(friendly_error.exit_code)
 
-        # Preserve raw exception behavior when debug is enabled but CDA did not
-        # provide a server stack trace.
+        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"]