Clarify API errors and add explicit output overwrite support

Author: rsgalloway

README.md

@@ -35,44 +35,22 @@ The client reads `SUBFORK_API_KEY` and connects to [subfork.com](https://subfork
 
 ## Command line
 
-The package also installs `subfork` (or use `python -m subfork`). It reads
-`SUBFORK_API_KEY` from your environment and prints JSON for use in scripts.
+The package includes a `subfork` CLI that uses your `SUBFORK_API_KEY`.
 
 ```bash
 subfork list
 subfork export GRAPH_ID --output graph.json
 subfork validate graph.json
 subfork create graph.json --name "My new graph"
-subfork interface GRAPH_ID
 subfork publish GRAPH_ID --version v1
-subfork execute GRAPH_ID --version v1 --inputs inputs.json
+subfork execute GRAPH_ID --version v1
 subfork execute GRAPH_ID -o results.json
 ```
 
-Export writes a graph's draft definition, which can be passed directly to create.
-It refuses to overwrite an existing file; omit `--output` to print to stdout.
-Descriptions, tags, and published versions are not included in the export.
-JSON input files must contain an object; use `-` to read from stdin.
-Create makes a public draft, publish creates an immutable version, and execute
-waits for completion and prints the graph outputs. Runs consume account quota.
-Use `-o results.json` or `--out results.json` to write result JSON to a new file
-instead of stdout. Progress still goes to stderr. Existing files are not overwritten.
-Use `execute --no-wait` for a submission summary or `execute --raw` for the full
-execution snapshot. Waiting requires read and run scopes; submission alone requires
-run scope. `--wait-timeout` (default 120) and `--poll-interval` (default 2) are in
-seconds. A timeout stops waiting without canceling the remote run.
-A yellow spinner precedes `Graph <name> .......... Running`, with `Running` in
-green. As status snapshots arrive, the line shows the currently running node titles
-(or multiple titles for parallel nodes). Short-lived nodes may finish between polls.
-Set `NO_COLOR` to disable colors. Progress goes to stderr; stdout remains JSON.
-Finished nodes remain on separate stderr lines with their final status before
-the JSON results appear. Redirected progress uses plain text without animation.
-
-Other commands include `get`, `published`, and `versions`. Use `--help` on any
-command. Node discovery and execution monitoring are available through the Python API.
-
-Errors go to stderr. Operational errors and failed validation return exit code 1;
-usage errors return 2. Failed executions and wait timeouts also return exit code 1.
+`execute` waits for completion and returns JSON. Use `-o` to save results to a
+file; progress stays on stderr. Add `-f` / `--force` to overwrite existing output
+files with `execute` or `export`. Run `subfork --help` or `subfork execute --help`
+for more options.
 
 ## Create and run a graph
 

src/subfork/cli.py

@@ -11,7 +11,15 @@
 from pathlib import Path
 from typing import Any, Callable, Dict, Iterator, Optional, Sequence
 
-from . import AuthenticationError, ExecutionTimeout, Subfork, SubforkError, __version__
+from . import APIError, AuthenticationError, ExecutionTimeout, Subfork, SubforkError, __version__
+
+
+def print_api_error(status_code: int, message: str) -> None:
+    """Write a concise API diagnostic, coloring only the status code on terminals."""
+    code = str(status_code)
+    if sys.stderr.isatty() and os.environ.get("TERM") != "dumb" and not os.environ.get("NO_COLOR"):
+        code = "\033[33m" + code + "\033[0m"
+    print("{}: {}".format(code, message), file=sys.stderr)
 
 
 @contextmanager
@@ -161,6 +169,10 @@ def build_parser() -> argparse.ArgumentParser:
     for command in ("get", "versions", "interface", "export", "publish", "execute"):
         child = commands.add_parser(command)
         child.add_argument("graph_id")
+        if command in {"export", "execute"}:
+            child.add_argument(
+                "-f", "--force", action="store_true", help="Overwrite an existing output file"
+            )
         if command == "export":
             child.add_argument(
                 "--output", default="-", help="Definition JSON path, or - for stdout"
@@ -171,9 +183,7 @@ def build_parser() -> argparse.ArgumentParser:
             child.add_argument("--comment", default="")
         elif command == "execute":
             child.add_argument("--version", default="draft")
-            child.add_argument(
-                "-o", "--out", help="Write result JSON to a new file instead of stdout"
-            )
+            child.add_argument("-o", "--out", help="Write result JSON to a file instead of stdout")
             child.add_argument(
                 "--no-wait", action="store_true", help="Return submission status immediately"
             )
@@ -297,8 +307,15 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
     args = build_parser().parse_args(argv)
     try:
         result_file = getattr(args, "out", None)
-        if result_file is not None and Path(result_file).exists():
-            raise ValueError("Output file already exists; choose a new path.")
+        force = getattr(args, "force", False)
+        export_file = getattr(args, "output", "-")
+        destination = (
+            result_file
+            if result_file is not None
+            else (export_file if export_file != "-" else None)
+        )
+        if destination is not None and Path(destination).exists() and not force:
+            raise ValueError("Output file already exists; use --force to overwrite.")
         with Subfork(base_url=args.base_url, timeout=args.timeout) as client:
             result = graph_command(client, args)
         failed = args.command == "execute" and result.get("status") in {
@@ -321,9 +338,9 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
         if result_file is None and output == "-":
             sys.stdout.write(rendered)
         else:
-            # Exclusive creation avoids silently overwriting an existing file.
+            # Open only after the request and serialization succeed.
             with Path(result_file if result_file is not None else output).open(
-                "x", encoding="utf-8", newline="\n"
+                "w" if force else "x", encoding="utf-8", newline="\n"
             ) as stream:
                 stream.write(rendered)
         if failed:
@@ -344,14 +361,21 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
         )
         return 1
     except AuthenticationError:
-        print(
-            "subfork: authentication failed (HTTP 401). Check that SUBFORK_API_KEY "
+        print_api_error(
+            401,
+            "Authentication failed. Check that SUBFORK_API_KEY "
             "is an active key issued by the service selected with --base-url or "
             "SUBFORK_BASE_URL (default: https://subfork.com). "
             "The CLI reads exported environment variables; it does not load .env files.",
-            file=sys.stderr,
         )
         return 1
+    except APIError as exc:
+        message = str(exc)
+        prefix = "Subfork API returned HTTP {}.".format(exc.status_code)
+        if message.startswith(prefix):
+            message = message[len(prefix) :].strip() or "API request failed."
+        print_api_error(exc.status_code, message)
+        return 1
     except (SubforkError, ValueError, OSError) as exc:
         print("subfork: {}".format(exc), file=sys.stderr)
         return 1

src/subfork/client.py

@@ -4,6 +4,7 @@
 
 import math
 import os
+import re
 from types import TracebackType
 from typing import Any, Optional, Type
 
@@ -22,6 +23,29 @@
 from .resources import Executions, Graphs, Nodes
 
 
+def _error_message(response: httpx.Response) -> str:
+    """Translate recognized server errors into fixed, credential-safe guidance."""
+    message = "Subfork API returned HTTP %s." % response.status_code
+    if response.status_code != 409:
+        return message
+    try:
+        payload = response.json()
+    except ValueError:
+        return message
+    detail = payload.get("detail") if isinstance(payload, dict) else None
+    if isinstance(detail, str) and re.fullmatch(
+        r"Graph secret '[^\r\n]*' could not be decrypted\. The server encryption "
+        r"key may have changed; re-enter this secret in Graph Settings\.",
+        detail,
+    ):
+        return (
+            message + " A stored graph secret could not be decrypted. "
+            "The server encryption key may have changed. "
+            "Re-enter and save the affected secret in Graph Settings > Secrets, then retry."
+        )
+    return message
+
+
 class Subfork:
     """Manage authenticated HTTP requests and graph resources.
 
@@ -110,7 +134,7 @@ def _request(self, method: str, path: str, **kwargs: Any) -> Any:
             }
             # Fixed messages avoid reflecting secrets from an untrusted response.
             raise errors.get(response.status_code, APIError)(
-                "Subfork API returned HTTP %s." % response.status_code,
+                _error_message(response),
                 status_code=response.status_code,
                 retry_after=response.headers.get("retry-after"),
             )

tests/test_cli.py

@@ -349,3 +349,72 @@ def test_execute_result_file(
     captured = capsys.readouterr()
     assert captured.out == ""
     assert "already exists" in captured.err
+
+
+@pytest.mark.parametrize(
+    "terminal,no_color,colored", [(True, False, True), (True, True, False), (False, False, False)]
+)
+def test_api_error_display(
+    monkeypatch: pytest.MonkeyPatch, terminal: bool, no_color: bool, colored: bool
+) -> None:
+    """Color only the error code and omit redundant API and program prefixes."""
+
+    class ErrorStream(io.StringIO):
+        """Capture diagnostics with configurable terminal detection."""
+
+        def isatty(self) -> bool:
+            """Return the selected terminal mode."""
+            return terminal
+
+    def factory(**kwargs: Any) -> Subfork:
+        """Raise the SDK's safe conflict explanation."""
+        from subfork import APIError
+
+        raise APIError(
+            "Subfork API returned HTTP 409. A stored graph secret could not be decrypted.",
+            status_code=409,
+        )
+
+    stream = ErrorStream()
+    monkeypatch.setattr("sys.stderr", stream)
+    monkeypatch.setattr(cli, "Subfork", factory)
+    monkeypatch.setenv("TERM", "xterm")
+    monkeypatch.setenv("NO_COLOR", "1" if no_color else "")
+    assert cli.main(["list"]) == 1
+    code = "\033[33m409\033[0m" if colored else "409"
+    assert stream.getvalue() == code + ": A stored graph secret could not be decrypted.\n"
+
+
+@pytest.mark.parametrize("flag", ["-f", "--force"])
+@pytest.mark.parametrize("command,option", [("execute", "-o"), ("export", "--output")])
+def test_force_output(
+    requests: list, tmp_path: Path, capsys: Any, flag: str, command: str, option: str
+) -> None:
+    """Replace the whole output file only when explicitly requested."""
+    output = tmp_path / "existing.json"
+    output.write_text("previous result with extra trailing content")
+    assert cli.main([command, "g_test", option, str(output), flag]) == 0
+    assert json.loads(output.read_text()) == (
+        {} if command == "execute" else {"name": "Greeting", "nodes": [], "edges": []}
+    )
+    assert capsys.readouterr().out == ""
+
+
+def test_force_preserves_output_on_api_failure(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    """Keep the previous result if execution submission fails."""
+
+    def factory(**kwargs: Any) -> Subfork:
+        """Construct a client that receives a server conflict."""
+        return Subfork(
+            "synthetic-key",
+            transport=httpx.MockTransport(lambda request: httpx.Response(409)),
+            **kwargs,
+        )
+
+    monkeypatch.setattr(cli, "Subfork", factory)
+    output = tmp_path / "existing.json"
+    output.write_text("previous result")
+    assert cli.main(["execute", "g_test", "-o", str(output), "--force"]) == 1
+    assert output.read_text() == "previous result"

tests/test_client.py

@@ -1,7 +1,7 @@
 """Exercise client contracts without network access or real credentials."""
 
 import json
-from typing import Type
+from typing import Any, Type
 
 import httpx
 import pytest
@@ -68,6 +68,7 @@ def test_credentials_required(monkeypatch: pytest.MonkeyPatch) -> None:
     [
         (401, AuthenticationError),
         (403, PermissionDeniedError),
+        (409, APIError),
         (422, ValidationError),
         (429, RateLimitError),
         (503, APIError),
@@ -200,3 +201,31 @@ def test_wait_reports_snapshots() -> None:
         result = client.executions.wait("e_test", poll_interval=0.001, on_update=snapshots.append)
     assert [snapshot["status"] for snapshot in snapshots] == ["running", "completed"]
     assert result == snapshots[-1]
+
+
+@pytest.mark.parametrize(
+    "detail,recognized",
+    [
+        (
+            "Graph secret '"
+            + KEY
+            + "' could not be decrypted. The server encryption key may have changed; re-enter this secret in Graph Settings.",
+            True,
+        ),
+        (KEY, False),
+        ({"secret": KEY}, False),
+        (None, False),
+    ],
+)
+def test_decryption_error_guidance(detail: Any, recognized: bool) -> None:
+    """Explain known conflicts without echoing even the server-provided secret name."""
+    with Subfork(
+        KEY,
+        transport=httpx.MockTransport(lambda request: httpx.Response(409, json={"detail": detail})),
+    ) as client:
+        with pytest.raises(APIError) as caught:
+            client.graphs.execute("g_test")
+    message = str(caught.value)
+    assert caught.value.status_code == 409
+    assert KEY not in message
+    assert ("Graph Settings > Secrets" in message) is recognized