fix: Improve Jira export error handling, env var warnings, and CLI test coverage

- Surface Jira API error body (errorMessages, errors fields) as clean ValueError
  instead of raw HTTPError traceback on 4xx/5xx responses
- Warn when ${VAR} reference in workspace.yaml resolves to unset env var
  instead of silently returning None
- Add 7 new tests: _raise_for_status error paths, CLI config wiring, clean error
  display in terminal

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: holy-pharaoh

corbell/core/export/jira.py

@@ -100,7 +100,7 @@ def export_tasks(self, tasks_yaml_path: Path | str) -> List[Dict[str, Any]]:
                     data=json.dumps(payload),
                     timeout=30,
                 )
-                resp.raise_for_status()
+                self._raise_for_status(resp)
                 result = resp.json()
 
                 issue_key = result.get("key", "")
@@ -134,6 +134,20 @@ def _validate_credentials(self) -> None:
                 "Set env vars or add 'integrations.jira.*' to workspace.yaml."
             )
 
+    def _raise_for_status(self, resp: Any) -> None:
+        """Raise ValueError with a clean Jira error message on 4xx/5xx."""
+        if resp.status_code < 400:
+            return
+        try:
+            body = resp.json()
+            messages = body.get("errorMessages", [])
+            errors = body.get("errors", {})
+            parts = list(messages) + [f"{k}: {v}" for k, v in errors.items()]
+            detail = "; ".join(parts) if parts else resp.text[:300]
+        except Exception:
+            detail = resp.text[:300]
+        raise ValueError(f"Jira API {resp.status_code}: {detail}")
+
     def _auth_headers(self) -> Dict[str, str]:
         token = base64.b64encode(f"{self.email}:{self.api_token}".encode()).decode()
         return {"Authorization": f"Basic {token}"}

corbell/core/workspace.py

@@ -224,12 +224,21 @@ def _expand_env(value: Any) -> Any:
     """Recursively expand ${VAR} references in dict/list/str values.
 
     - ``${VAR}``  → value of env var VAR, or None if not set
+                    (a warning is emitted when the var is missing)
     - Any other string → used as-is (literal value)
     """
     if isinstance(value, str):
         if value.startswith("${") and value.endswith("}"):
             var = value[2:-1]
-            return os.environ.get(var, None)  # None when env var is not set
+            resolved = os.environ.get(var)
+            if resolved is None:
+                import warnings
+                warnings.warn(
+                    f"Environment variable '{var}' is referenced in workspace.yaml but is not set.",
+                    UserWarning,
+                    stacklevel=2,
+                )
+            return resolved
         return value
     if isinstance(value, dict):
         return {k: _expand_env(v) for k, v in value.items()}

tests/test_jira_export.py

@@ -1,4 +1,4 @@
-"""Tests for the Jira exporter."""
+"""Tests for the Jira exporter and CLI command."""
 
 from __future__ import annotations
 
@@ -80,6 +80,7 @@ def tasks_yaml_no_files(tmp_path) -> Path:
 
 def _mock_response(key: str = "ENG-1") -> MagicMock:
     resp = MagicMock()
+    resp.status_code = 201
     resp.json.return_value = {"key": key, "id": "10001"}
     resp.raise_for_status.return_value = None
     return resp
@@ -347,3 +348,142 @@ def test_jira_workspace_config_overrides_env(tmp_path):
     assert jira.api_token == "secret-token"
     assert jira.project_key == "ACME"
     assert jira.issue_type == "Story"
+
+
+# ─── Jira API error handling ──────────────────────────────────────────────────
+
+def test_raise_for_status_surfaces_jira_error_messages():
+    exporter = JiraExporter(**VALID_CREDS)
+    resp = MagicMock()
+    resp.status_code = 400
+    resp.json.return_value = {
+        "errorMessages": ["Project 'XYZ' does not exist."],
+        "errors": {},
+    }
+    with pytest.raises(ValueError, match="Project 'XYZ' does not exist"):
+        exporter._raise_for_status(resp)
+
+
+def test_raise_for_status_surfaces_field_errors():
+    exporter = JiraExporter(**VALID_CREDS)
+    resp = MagicMock()
+    resp.status_code = 400
+    resp.json.return_value = {
+        "errorMessages": [],
+        "errors": {"issuetype": "Issue type is required."},
+    }
+    with pytest.raises(ValueError, match="issuetype"):
+        exporter._raise_for_status(resp)
+
+
+def test_raise_for_status_401_fallback_to_text():
+    exporter = JiraExporter(**VALID_CREDS)
+    resp = MagicMock()
+    resp.status_code = 401
+    resp.json.side_effect = Exception("not json")
+    resp.text = "Unauthorized"
+    with pytest.raises(ValueError, match="401"):
+        exporter._raise_for_status(resp)
+
+
+def test_raise_for_status_2xx_does_not_raise():
+    exporter = JiraExporter(**VALID_CREDS)
+    resp = MagicMock()
+    resp.status_code = 201
+    exporter._raise_for_status(resp)  # should not raise
+
+
+def test_export_tasks_surfaces_jira_error(tasks_yaml):
+    """HTTPError from Jira should surface as a clean ValueError, not a traceback."""
+    exporter = JiraExporter(**VALID_CREDS)
+
+    bad_resp = MagicMock()
+    bad_resp.status_code = 400
+    bad_resp.json.return_value = {"errorMessages": ["Issue type 'Task' not found."], "errors": {}}
+
+    with patch("requests.Session.post", return_value=bad_resp):
+        with pytest.raises(ValueError, match="Issue type 'Task' not found"):
+            exporter.export_tasks(tasks_yaml)
+
+
+# ─── CLI command ──────────────────────────────────────────────────────────────
+
+def test_cli_export_jira_reads_config_from_workspace(tmp_path, tasks_yaml):
+    """CLI `export jira` must pass workspace.yaml values to JiraExporter."""
+    from typer.testing import CliRunner
+    from corbell.cli.commands.export import app
+
+    # Create a minimal workspace with Jira config
+    ws_dir = tmp_path / "corbell-data"
+    ws_dir.mkdir()
+    (ws_dir / "workspace.yaml").write_text(
+        """\
+version: "1"
+integrations:
+  jira:
+    url: https://test.atlassian.net
+    email: test@test.com
+    api_token: test-token
+    project_key: TEST
+    issue_type: Task
+""",
+        encoding="utf-8",
+    )
+
+    captured = {}
+
+    def fake_export(self, path):
+        captured["url"] = self.url
+        captured["email"] = self.email
+        captured["api_token"] = self.api_token
+        captured["project_key"] = self.project_key
+        return [{"issue_key": "TEST-1", "title": "t", "url": "u"}]
+
+    runner = CliRunner()
+    with patch("corbell.core.export.jira.JiraExporter.export_tasks", fake_export):
+        result = runner.invoke(
+            app,
+            ["jira", str(tasks_yaml), "--workspace", str(tmp_path)],
+        )
+
+    assert result.exit_code == 0, result.output
+    assert captured["url"] == "https://test.atlassian.net"
+    assert captured["email"] == "test@test.com"
+    assert captured["api_token"] == "test-token"
+    assert captured["project_key"] == "TEST"
+
+
+def test_cli_export_jira_shows_clean_error_on_bad_credentials(tmp_path, tasks_yaml):
+    """CLI must show a clean error message, not a Python traceback."""
+    from typer.testing import CliRunner
+    from corbell.cli.commands.export import app
+
+    ws_dir = tmp_path / "corbell-data"
+    ws_dir.mkdir()
+    (ws_dir / "workspace.yaml").write_text(
+        """\
+version: "1"
+integrations:
+  jira:
+    url: https://test.atlassian.net
+    email: test@test.com
+    api_token: bad-token
+    project_key: TEST
+    issue_type: Task
+""",
+        encoding="utf-8",
+    )
+
+    def fake_export(self, path):
+        raise ValueError("Jira API 401: Unauthorized")
+
+    runner = CliRunner()
+    with patch("corbell.core.export.jira.JiraExporter.export_tasks", fake_export):
+        result = runner.invoke(
+            app,
+            ["jira", str(tasks_yaml), "--workspace", str(tmp_path)],
+        )
+
+    assert result.exit_code == 1
+    assert "Jira API 401" in result.output
+    assert "Traceback" not in result.output