agent-first-data 0.14.2__tar.gz → 0.15.0__tar.gz

{agent_first_data-0.14.2 → agent_first_data-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.14.2
+Version: 0.15.0
 Summary: A naming convention that lets AI agents understand your data without being told what it means.
 License-Expression: MIT
 Project-URL: Repository, https://github.com/agentfirstkit/agent-first-data
@@ -29,7 +29,7 @@ print(output_json(value))
 print(output_plain(value))
 ```
 
-Useful names use Python casing: `output_json`, `output_yaml`, `output_plain`, `output_json_with_options`, `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `parse_size`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `cli_parse_output`, `cli_output`, `build_cli_error`, `build_cli_version`, and `cli_handle_version_or_continue`.
+Useful names use Python casing: `output_json`, `output_yaml`, `output_plain`, `output_json_with_options`, `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `parse_size`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `cli_parse_output`, `cli_output`, `build_cli_error`, `build_cli_version`, `cli_handle_version_or_continue`, `stream_redirect_config_from_raw_args`, and `install_stream_redirect_from_raw_args`.
 
 Logging is available through `init_logging_json`, `init_logging_plain`, `init_logging_yaml`, `span`, and `get_logger`.
 
@@ -47,6 +47,7 @@ init_logging_json("INFO", secret_names=("authorization",))
 - Logging records use `code: "log"` plus a separate `level` field, so error-level logs are not terminal protocol errors.
 - `build_cli_error(message, hint?)` returns `{code:"error", error: message, hint?}` only.
 - Use `cli_handle_version_or_continue()` before argument parsing so bare `--version` stays conventional and `--version --output json|yaml|plain` stays structured.
+- Use `install_stream_redirect_from_raw_args()` before version/help handling if a CLI exposes `--stdout-file` or `--stderr-file`; stderr is redirected as native diagnostics, not JSON.
 
 ## Reference
 

{agent_first_data-0.14.2 → agent_first_data-0.15.0}/README.md

@@ -20,7 +20,7 @@ print(output_json(value))
 print(output_plain(value))
 ```
 
-Useful names use Python casing: `output_json`, `output_yaml`, `output_plain`, `output_json_with_options`, `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `parse_size`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `cli_parse_output`, `cli_output`, `build_cli_error`, `build_cli_version`, and `cli_handle_version_or_continue`.
+Useful names use Python casing: `output_json`, `output_yaml`, `output_plain`, `output_json_with_options`, `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `parse_size`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `cli_parse_output`, `cli_output`, `build_cli_error`, `build_cli_version`, `cli_handle_version_or_continue`, `stream_redirect_config_from_raw_args`, and `install_stream_redirect_from_raw_args`.
 
 Logging is available through `init_logging_json`, `init_logging_plain`, `init_logging_yaml`, `span`, and `get_logger`.
 
@@ -38,6 +38,7 @@ init_logging_json("INFO", secret_names=("authorization",))
 - Logging records use `code: "log"` plus a separate `level` field, so error-level logs are not terminal protocol errors.
 - `build_cli_error(message, hint?)` returns `{code:"error", error: message, hint?}` only.
 - Use `cli_handle_version_or_continue()` before argument parsing so bare `--version` stays conventional and `--version --output json|yaml|plain` stays structured.
+- Use `install_stream_redirect_from_raw_args()` before version/help handling if a CLI exposes `--stdout-file` or `--stderr-file`; stderr is redirected as native diagnostics, not JSON.
 
 ## Reference
 

{agent_first_data-0.14.2 → agent_first_data-0.15.0}/agent_first_data/__init__.py

@@ -65,6 +65,16 @@ from agent_first_data.skill import (
     run_skill_admin,
 )
 
+from agent_first_data.stream_redirect import (
+    STDOUT_FILE_ARG,
+    STDERR_FILE_ARG,
+    StreamRedirectConfig,
+    InstalledStreamRedirect,
+    config_from_raw_args as stream_redirect_config_from_raw_args,
+    install as install_stream_redirect,
+    install_from_raw_args as install_stream_redirect_from_raw_args,
+)
+
 __all__ = [
     "build_json_ok",
     "build_json_error",
@@ -119,4 +129,11 @@ __all__ = [
     "SkillInstallReport",
     "SkillUninstallReport",
     "run_skill_admin",
+    "STDOUT_FILE_ARG",
+    "STDERR_FILE_ARG",
+    "StreamRedirectConfig",
+    "InstalledStreamRedirect",
+    "stream_redirect_config_from_raw_args",
+    "install_stream_redirect",
+    "install_stream_redirect_from_raw_args",
 ]

agent_first_data-0.15.0/agent_first_data/stream_redirect.py

@@ -0,0 +1,159 @@
+"""Optional stdout/stderr file redirection for AFDATA CLIs."""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+from typing import Sequence
+
+STDOUT_FILE_ARG = "--stdout-file"
+STDERR_FILE_ARG = "--stderr-file"
+
+
+@dataclass(frozen=True)
+class StreamRedirectConfig:
+    """Resolved stdout/stderr file redirection config."""
+
+    stdout_file: str | None = None
+    stderr_file: str | None = None
+
+    def validate(self) -> None:
+        if self.stdout_file is not None and self.stdout_file == "":
+            raise ValueError("--stdout-file must not be empty")
+        if self.stderr_file is not None and self.stderr_file == "":
+            raise ValueError("--stderr-file must not be empty")
+
+
+class InstalledStreamRedirect:
+    """Restores original stdout/stderr when closed."""
+
+    def __init__(self, stdout_restore_fd: int | None, stderr_restore_fd: int | None) -> None:
+        self._stdout_restore_fd = stdout_restore_fd
+        self._stderr_restore_fd = stderr_restore_fd
+        self._closed = False
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        sys.stdout.flush()
+        sys.stderr.flush()
+        if self._stdout_restore_fd is not None:
+            os.dup2(self._stdout_restore_fd, sys.stdout.fileno())
+            os.close(self._stdout_restore_fd)
+            self._stdout_restore_fd = None
+        if self._stderr_restore_fd is not None:
+            os.dup2(self._stderr_restore_fd, sys.stderr.fileno())
+            os.close(self._stderr_restore_fd)
+            self._stderr_restore_fd = None
+
+    def __enter__(self) -> "InstalledStreamRedirect":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+def config_from_raw_args(args: Sequence[str]) -> StreamRedirectConfig | None:
+    """Resolve --stdout-file/--stderr-file from raw CLI args."""
+
+    stdout_file: str | None = None
+    stderr_file: str | None = None
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg == "--":
+            break
+        if arg == STDOUT_FILE_ARG:
+            stdout_file, i = _take_value(args, i, STDOUT_FILE_ARG)
+        elif arg.startswith(f"{STDOUT_FILE_ARG}="):
+            stdout_file = arg.split("=", 1)[1]
+        elif arg == STDERR_FILE_ARG:
+            stderr_file, i = _take_value(args, i, STDERR_FILE_ARG)
+        elif arg.startswith(f"{STDERR_FILE_ARG}="):
+            stderr_file = arg.split("=", 1)[1]
+        i += 1
+
+    config = StreamRedirectConfig(stdout_file=stdout_file, stderr_file=stderr_file)
+    config.validate()
+    if config.stdout_file is None and config.stderr_file is None:
+        return None
+    return config
+
+
+def install_from_raw_args(args: Sequence[str] | None = None) -> InstalledStreamRedirect | None:
+    """Install stdout/stderr redirection from raw CLI args."""
+
+    raw = sys.argv[1:] if args is None else args
+    config = config_from_raw_args(raw)
+    if config is None:
+        return None
+    return install(config)
+
+
+def install(config: StreamRedirectConfig) -> InstalledStreamRedirect:
+    """Redirect configured streams to append-only files."""
+
+    config.validate()
+    stdout_target = _prepare_target(sys.stdout.fileno(), config.stdout_file)
+    try:
+        stderr_target = _prepare_target(sys.stderr.fileno(), config.stderr_file)
+    except Exception:
+        _close_prepared(stdout_target)
+        raise
+
+    sys.stdout.flush()
+    sys.stderr.flush()
+
+    try:
+        if stdout_target is not None:
+            os.dup2(stdout_target.file_fd, sys.stdout.fileno())
+        if stderr_target is not None:
+            os.dup2(stderr_target.file_fd, sys.stderr.fileno())
+    except Exception:
+        if stdout_target is not None:
+            os.dup2(stdout_target.restore_fd, sys.stdout.fileno())
+        _close_prepared(stdout_target)
+        _close_prepared(stderr_target)
+        raise
+
+    stdout_restore_fd = stdout_target.restore_fd if stdout_target is not None else None
+    stderr_restore_fd = stderr_target.restore_fd if stderr_target is not None else None
+    if stdout_target is not None:
+        os.close(stdout_target.file_fd)
+    if stderr_target is not None:
+        os.close(stderr_target.file_fd)
+    return InstalledStreamRedirect(stdout_restore_fd, stderr_restore_fd)
+
+
+@dataclass
+class _PreparedTarget:
+    file_fd: int
+    restore_fd: int
+
+
+def _prepare_target(target_fd: int, path: str | None) -> _PreparedTarget | None:
+    if path is None:
+        return None
+    file_fd = os.open(path, os.O_CREAT | os.O_WRONLY | os.O_APPEND, 0o666)
+    try:
+        restore_fd = os.dup(target_fd)
+    except Exception:
+        os.close(file_fd)
+        raise
+    return _PreparedTarget(file_fd=file_fd, restore_fd=restore_fd)
+
+
+def _close_prepared(target: _PreparedTarget | None) -> None:
+    if target is None:
+        return
+    os.close(target.file_fd)
+    os.close(target.restore_fd)
+
+
+def _take_value(args: Sequence[str], idx: int, flag: str) -> tuple[str, int]:
+    next_idx = idx + 1
+    if next_idx >= len(args) or args[next_idx].startswith("--"):
+        raise ValueError(f"{flag} requires a value")
+    return args[next_idx], next_idx

{agent_first_data-0.14.2 → agent_first_data-0.15.0}/agent_first_data.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.14.2
+Version: 0.15.0
 Summary: A naming convention that lets AI agents understand your data without being told what it means.
 License-Expression: MIT
 Project-URL: Repository, https://github.com/agentfirstkit/agent-first-data
@@ -29,7 +29,7 @@ print(output_json(value))
 print(output_plain(value))
 ```
 
-Useful names use Python casing: `output_json`, `output_yaml`, `output_plain`, `output_json_with_options`, `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `parse_size`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `cli_parse_output`, `cli_output`, `build_cli_error`, `build_cli_version`, and `cli_handle_version_or_continue`.
+Useful names use Python casing: `output_json`, `output_yaml`, `output_plain`, `output_json_with_options`, `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `parse_size`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `cli_parse_output`, `cli_output`, `build_cli_error`, `build_cli_version`, `cli_handle_version_or_continue`, `stream_redirect_config_from_raw_args`, and `install_stream_redirect_from_raw_args`.
 
 Logging is available through `init_logging_json`, `init_logging_plain`, `init_logging_yaml`, `span`, and `get_logger`.
 
@@ -47,6 +47,7 @@ init_logging_json("INFO", secret_names=("authorization",))
 - Logging records use `code: "log"` plus a separate `level` field, so error-level logs are not terminal protocol errors.
 - `build_cli_error(message, hint?)` returns `{code:"error", error: message, hint?}` only.
 - Use `cli_handle_version_or_continue()` before argument parsing so bare `--version` stays conventional and `--version --output json|yaml|plain` stays structured.
+- Use `install_stream_redirect_from_raw_args()` before version/help handling if a CLI exposes `--stdout-file` or `--stderr-file`; stderr is redirected as native diagnostics, not JSON.
 
 ## Reference
 

{agent_first_data-0.14.2 → agent_first_data-0.15.0}/agent_first_data.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ agent_first_data/afdata_logging.py
 agent_first_data/cli.py
 agent_first_data/format.py
 agent_first_data/skill.py
+agent_first_data/stream_redirect.py
 agent_first_data.egg-info/PKG-INFO
 agent_first_data.egg-info/SOURCES.txt
 agent_first_data.egg-info/dependency_links.txt
@@ -13,4 +14,5 @@ tests/test_afdata_logging.py
 tests/test_cli.py
 tests/test_format.py
 tests/test_no_stderr_policy.py
-tests/test_skill.py
+tests/test_skill.py
+tests/test_stream_redirect.py

{agent_first_data-0.14.2 → agent_first_data-0.15.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-first-data"
-version = "0.14.2"
+version = "0.15.0"
 description = "A naming convention that lets AI agents understand your data without being told what it means."
 license = "MIT"
 readme = "README.md"

{agent_first_data-0.14.2 → agent_first_data-0.15.0}/tests/test_no_stderr_policy.py

@@ -16,6 +16,8 @@ def test_no_stderr_usage_in_runtime_sources() -> None:
 
     violations: list[str] = []
     for path in files:
+        if path.name == "stream_redirect.py":
+            continue
         for lineno, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
             if DISALLOWED.search(line):
                 violations.append(f"{path.name}:{lineno}: {line.strip()}")

agent_first_data-0.15.0/tests/test_stream_redirect.py

@@ -0,0 +1,47 @@
+"""Tests for stdout/stderr stream redirection argument handling."""
+
+import os
+import sys
+
+import pytest
+
+from agent_first_data.stream_redirect import StreamRedirectConfig, config_from_raw_args, install
+
+
+def test_config_from_raw_args_space_and_equals_values() -> None:
+    config = config_from_raw_args(
+        [
+            "agent-cli",
+            "--stdout-file",
+            "/tmp/agent-cli.out",
+            "--stderr-file=/tmp/agent-cli.err",
+            "ping",
+        ]
+    )
+    assert config is not None
+    assert config.stdout_file == "/tmp/agent-cli.out"
+    assert config.stderr_file == "/tmp/agent-cli.err"
+
+
+def test_config_from_raw_args_disabled() -> None:
+    assert config_from_raw_args(["agent-cli", "ping"]) is None
+
+
+def test_config_from_raw_args_missing_value() -> None:
+    with pytest.raises(ValueError):
+        config_from_raw_args(["agent-cli", "--stderr-file", "--help"])
+
+
+def test_install_redirects_and_restores_output(tmp_path) -> None:
+    stdout_path = tmp_path / "stdout.log"
+    stderr_path = tmp_path / "stderr.log"
+
+    redirect = install(StreamRedirectConfig(stdout_file=str(stdout_path), stderr_file=str(stderr_path)))
+    try:
+        os.write(sys.stdout.fileno(), b"stdout bytes\n")
+        os.write(sys.stderr.fileno(), b"stderr bytes\n")
+    finally:
+        redirect.close()
+
+    assert stdout_path.read_bytes() == b"stdout bytes\n"
+    assert stderr_path.read_bytes() == b"stderr bytes\n"