pyplines-cli-common 2026.9.3a1__tar.gz

pyplines_cli_common-2026.9.3a1/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: pyplines-cli-common
+Version: 2026.9.3a1
+Summary: Shared presentation and interaction contract for Pyplines command-line tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: typer<1,>=0.24
+Requires-Dist: rich<15,>=13
+Requires-Dist: PyYAML<7,>=6
+
+# Pyplines CLI standard
+
+`pyplines-cli-common` provides the shared Typer application boundary, safe
+errors, and presentation used by the CLI and Builder. It has no Server dependency.
+
+Human output is the default. `AUTOMATION_MODE=enabled` or `--json` selects
+automation output: one JSON result on stdout, JSON errors and progress on stderr,
+and no interactive prompts. Log-stream commands emit newline-delimited JSON.
+Empty invocation and help show readable help and exit zero without credentials.
+Redirecting stdout does not change the output format.
+
+Exit codes: 0 success, 1 operation failure, 2 invalid usage, 130 interruption.
+Unexpected exceptions never print arbitrary exception values; optional diagnostics
+identify their type without leaking tokens or signed URLs.
+
+The shared package follows the release's CalVer version and is published before
+CLI and Builder. Configure its PyPI Trusted Publisher for repository
+`pyplines/pyplines`, workflow `publish-release.yml`, environment `pypi`.

pyplines_cli_common-2026.9.3a1/README.md

@@ -0,0 +1,18 @@
+# Pyplines CLI standard
+
+`pyplines-cli-common` provides the shared Typer application boundary, safe
+errors, and presentation used by the CLI and Builder. It has no Server dependency.
+
+Human output is the default. `AUTOMATION_MODE=enabled` or `--json` selects
+automation output: one JSON result on stdout, JSON errors and progress on stderr,
+and no interactive prompts. Log-stream commands emit newline-delimited JSON.
+Empty invocation and help show readable help and exit zero without credentials.
+Redirecting stdout does not change the output format.
+
+Exit codes: 0 success, 1 operation failure, 2 invalid usage, 130 interruption.
+Unexpected exceptions never print arbitrary exception values; optional diagnostics
+identify their type without leaking tokens or signed URLs.
+
+The shared package follows the release's CalVer version and is published before
+CLI and Builder. Configure its PyPI Trusted Publisher for repository
+`pyplines/pyplines`, workflow `publish-release.yml`, environment `pypi`.

pyplines_cli_common-2026.9.3a1/pyplines_cli_common/__init__.py

@@ -0,0 +1,15 @@
+"""Common CLI behavior without platform or resource operations."""
+
+import os
+from contextvars import ContextVar
+
+current_automation = ContextVar("automation", default=False)
+
+
+def automation_mode(json_output: bool = False) -> bool:
+    """Explicit JSON or the standard environment flag enables automation."""
+    return (
+        json_output
+        or current_automation.get()
+        or os.environ.get("AUTOMATION_MODE", "").lower() == "enabled"
+    )

pyplines_cli_common-2026.9.3a1/pyplines_cli_common/application.py

@@ -0,0 +1,79 @@
+"""Use the exception types belonging to Typer's active Click implementation."""
+
+import os
+import sys
+from importlib.metadata import version
+from typer.core import TyperCommand, TyperGroup
+
+try:
+    from typer import _click as click
+except ImportError:
+    import click
+
+try:
+    from typer.exceptions import Abort
+except ImportError:
+    from click.exceptions import Abort
+
+from .errors import ClientError
+from .presentation import Presenter
+from . import current_automation
+
+
+class Command(TyperCommand):
+    pass
+
+
+class Group(TyperGroup):
+    package_name = None
+
+    def main(self, args=None, standalone_mode=True, **kwargs):
+        arguments = list(sys.argv[1:] if args is None else args)
+        options = arguments[: arguments.index("--")] if "--" in arguments else arguments
+        presenter = Presenter(sys.stdout, sys.stderr, "--json" in options)
+        verbose = "--verbose-errors" in options or os.environ.get(
+            "PYPLINES_VERBOSE_ERRORS", ""
+        ).lower() in ("true", "enabled", "1")
+        if "--verbose-errors" in options:
+            arguments.remove("--verbose-errors")
+        if "--version" in options and self.package_name:
+            presenter.outcome(
+                {"version": version(self.package_name)}, version(self.package_name)
+            )
+            if standalone_mode:
+                raise SystemExit(0)
+            return 0
+        mode_token = current_automation.set(presenter.json_output)
+        try:
+            result = super().main(args=arguments, standalone_mode=False, **kwargs)
+        except click.exceptions.NoArgsIsHelpError as error:
+            sys.stdout.write(error.ctx.get_help() + "\n")
+            result = 0
+        except click.ClickException as error:
+            presenter.error(
+                ClientError("invalid-usage", error.format_message(), error.exit_code)
+            )
+            result = error.exit_code
+        except ClientError as error:
+            presenter.error(error)
+            result = error.exit_code
+        except (KeyboardInterrupt, EOFError, Abort):
+            presenter.error(
+                ClientError(
+                    "interrupted", "Interrupted; remote work may still be running", 130
+                )
+            )
+            result = 130
+        except Exception as error:
+            # Arbitrary exception strings can contain passwords or signed URLs.
+            # Expose only the exception type in optional diagnostics.
+            message = "Operation failed unexpectedly"
+            if verbose:
+                message += f" ({type(error).__name__})"
+            presenter.error(ClientError("internal-error", message))
+            result = 1
+        finally:
+            current_automation.reset(mode_token)
+        if standalone_mode:
+            raise SystemExit(result if isinstance(result, int) else 0)
+        return result

pyplines_cli_common-2026.9.3a1/pyplines_cli_common/errors.py

@@ -0,0 +1,24 @@
+"""Safe failures shared by the client, commands, and renderers."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ClientError(Exception):
+    code: str
+    message: str
+    exit_code: int = 1
+    violations: list[dict[str, Any]] = field(default_factory=list)
+    correlation_id: str | None = None
+
+    def __str__(self) -> str:
+        return self.message
+
+    def document(self) -> dict[str, Any]:
+        value: dict[str, Any] = {"code": self.code, "message": self.message}
+        if self.violations:
+            value["violations"] = self.violations
+        if self.correlation_id:
+            value["correlation_id"] = self.correlation_id
+        return {"error": value}

pyplines_cli_common-2026.9.3a1/pyplines_cli_common/interaction.py

@@ -0,0 +1,8 @@
+"""Shared prompt eligibility; callers supply operation-specific missing-input errors."""
+
+import sys
+from . import automation_mode
+
+
+def can_prompt():
+    return not automation_mode() and sys.stdin.isatty()

pyplines_cli_common-2026.9.3a1/pyplines_cli_common/presentation.py

@@ -0,0 +1,164 @@
+"""One static visual grammar; contains no API or Typer dependencies."""
+
+from __future__ import annotations
+
+import json
+import unicodedata
+from dataclasses import dataclass
+from typing import Any, Iterable, TextIO
+
+import yaml
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from .errors import ClientError
+from . import automation_mode
+
+
+def safe_text(value: Any) -> str:
+    text = "—" if value is None or value == "" else str(value)
+    return "".join(
+        char if not unicodedata.category(char).startswith("C") else " " for char in text
+    )
+
+
+def display_width(text: str) -> int:
+    return sum(
+        (
+            0
+            if unicodedata.combining(char)
+            else 2 if unicodedata.east_asian_width(char) in "WF" else 1
+        )
+        for char in text
+    )
+
+
+def pad(text: str, width: int, numeric: bool = False) -> str:
+    spaces = " " * max(0, width - display_width(text))
+    return spaces + text if numeric else text + spaces
+
+
+@dataclass(frozen=True)
+class Column:
+    key: str
+    title: str
+    numeric: bool = False
+
+
+class Presenter:
+    def __init__(self, stdout: TextIO, stderr: TextIO, json_output: bool = False):
+        self.stdout = stdout
+        self.stderr = stderr
+        self.json_output = automation_mode(json_output)
+
+    def _json(self, value: Any, stream: TextIO) -> None:
+        stream.write(json.dumps(value, ensure_ascii=True, allow_nan=False) + "\n")
+        stream.flush()
+
+    def collection(
+        self, document: dict, columns: Iterable[Column], empty: str = "No results."
+    ) -> None:
+        if self.json_output:
+            self._json(document, self.stdout)
+            return
+        items = document.get("items", [])
+        if not items:
+            self.stdout.write(safe_text(empty) + "\n")
+            return
+        columns = list(columns)
+        if getattr(self.stdout, "isatty", lambda: False)():
+            table = Table(box=None, pad_edge=False)
+            for column in columns:
+                table.add_column(
+                    column.title, justify="right" if column.numeric else "left"
+                )
+            for item in items:
+                table.add_row(*(Text(safe_text(item.get(c.key))) for c in columns))
+            Console(file=self.stdout).print(table)
+            if document.get("next_cursor"):
+                self.stdout.write(
+                    "Next cursor: " + safe_text(document["next_cursor"]) + "\n"
+                )
+            return
+        rows = [[safe_text(item.get(c.key)) for c in columns] for item in items]
+        widths = [
+            max(display_width(c.title), *(display_width(row[i]) for row in rows))
+            for i, c in enumerate(columns)
+        ]
+        for row in [[c.title for c in columns], *rows]:
+            self.stdout.write(
+                "  ".join(
+                    pad(cell, widths[i], columns[i].numeric)
+                    for i, cell in enumerate(row)
+                ).rstrip()
+                + "\n"
+            )
+        if document.get("next_cursor"):
+            self.stdout.write(
+                "Next cursor: " + safe_text(document["next_cursor"]) + "\n"
+            )
+
+    def detail(self, document: dict, fields: Iterable[tuple[str, Any]]) -> None:
+        if self.json_output:
+            self._json(document, self.stdout)
+            return
+        fields = list(fields)
+        width = max((display_width(label) for label, _ in fields), default=0)
+        for label, value in fields:
+            if isinstance(value, (dict, list)):
+                value = json.dumps(value, ensure_ascii=True)
+            self.stdout.write(
+                pad(safe_text(label), width) + "  " + safe_text(value) + "\n"
+            )
+
+    def outcome(self, document: dict, message: str) -> None:
+        if self.json_output:
+            self._json(document, self.stdout)
+        else:
+            self.stdout.write(safe_text(message) + "\n")
+
+    def config(self, document: dict) -> None:
+        if self.json_output:
+            self._json(document, self.stdout)
+        else:
+            self.stdout.write(yaml.safe_dump(document, sort_keys=False))
+
+    def event(self, event: dict, *, logs: bool = False) -> None:
+        stream = self.stdout if logs else self.stderr
+        if self.json_output:
+            self._json(event, stream)
+        else:
+            context = dict(event)
+            if event.get("attempt") and event.get("step"):
+                context["step"] = f"{event['step']}@{event['attempt']}"
+            if event.get("name") and event.get("number"):
+                context["target"] = f"{event['name']}/{event['number']}"
+            prefix = " ".join(
+                safe_text(context[key])
+                for key in ("timestamp", "level", "target", "step")
+                if context.get(key)
+            )
+            message = str(event.get("message", event.get("status", "")))
+            for i, line in enumerate(message.splitlines() or [""]):
+                stream.write(
+                    (prefix if i == 0 else " " * display_width(prefix))
+                    + "  "
+                    + safe_text(line)
+                    + "\n"
+                )
+            stream.flush()
+
+    def error(self, error: ClientError) -> None:
+        if self.json_output:
+            self._json(error.document(), self.stderr)
+        else:
+            self.stderr.write("Error: " + safe_text(error.message) + "\n")
+            for violation in error.violations:
+                self.stderr.write(
+                    "  "
+                    + safe_text(violation.get("field"))
+                    + ": "
+                    + safe_text(violation.get("message"))
+                    + "\n"
+                )

pyplines_cli_common-2026.9.3a1/pyplines_cli_common.egg-info/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: pyplines-cli-common
+Version: 2026.9.3a1
+Summary: Shared presentation and interaction contract for Pyplines command-line tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: typer<1,>=0.24
+Requires-Dist: rich<15,>=13
+Requires-Dist: PyYAML<7,>=6
+
+# Pyplines CLI standard
+
+`pyplines-cli-common` provides the shared Typer application boundary, safe
+errors, and presentation used by the CLI and Builder. It has no Server dependency.
+
+Human output is the default. `AUTOMATION_MODE=enabled` or `--json` selects
+automation output: one JSON result on stdout, JSON errors and progress on stderr,
+and no interactive prompts. Log-stream commands emit newline-delimited JSON.
+Empty invocation and help show readable help and exit zero without credentials.
+Redirecting stdout does not change the output format.
+
+Exit codes: 0 success, 1 operation failure, 2 invalid usage, 130 interruption.
+Unexpected exceptions never print arbitrary exception values; optional diagnostics
+identify their type without leaking tokens or signed URLs.
+
+The shared package follows the release's CalVer version and is published before
+CLI and Builder. Configure its PyPI Trusted Publisher for repository
+`pyplines/pyplines`, workflow `publish-release.yml`, environment `pypi`.

pyplines_cli_common-2026.9.3a1/pyplines_cli_common.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+uv.lock
+pyplines_cli_common/__init__.py
+pyplines_cli_common/application.py
+pyplines_cli_common/errors.py
+pyplines_cli_common/interaction.py
+pyplines_cli_common/presentation.py
+pyplines_cli_common.egg-info/PKG-INFO
+pyplines_cli_common.egg-info/SOURCES.txt
+pyplines_cli_common.egg-info/dependency_links.txt
+pyplines_cli_common.egg-info/requires.txt
+pyplines_cli_common.egg-info/top_level.txt
+tests/test_application.py

pyplines_cli_common-2026.9.3a1/pyplines_cli_common.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pyplines_cli_common-2026.9.3a1/pyplines_cli_common.egg-info/requires.txt

@@ -0,0 +1,3 @@
+typer<1,>=0.24
+rich<15,>=13
+PyYAML<7,>=6

pyplines_cli_common-2026.9.3a1/pyplines_cli_common.egg-info/top_level.txt

@@ -0,0 +1 @@
+pyplines_cli_common

pyplines_cli_common-2026.9.3a1/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=69", "setuptools-scm>=8", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyplines-cli-common"
+dynamic = ["version"]
+description = "Shared presentation and interaction contract for Pyplines command-line tools"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["typer>=0.24,<1", "rich>=13,<15", "PyYAML>=6,<7"]
+
+[tool.setuptools.packages.find]
+include = ["pyplines_cli_common*"]
+
+[tool.setuptools_scm]
+root = ".."
+fallback_version = "0.0.dev0"
+
+[dependency-groups]
+dev = ["pytest>=8", "black>=25", "twine>=6"]

pyplines_cli_common-2026.9.3a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyplines_cli_common-2026.9.3a1/tests/test_application.py

@@ -0,0 +1,68 @@
+import json
+import io
+import pytest
+import typer
+from typer.testing import CliRunner
+from pyplines_cli_common.application import Group
+from pyplines_cli_common.presentation import Presenter
+
+
+@pytest.mark.parametrize("automation", [False, True])
+def test_help_and_usage(automation, monkeypatch):
+    monkeypatch.setenv("AUTOMATION_MODE", "enabled" if automation else "")
+    app = typer.Typer(cls=Group, no_args_is_help=True)
+
+    @app.callback()
+    def options():
+        pass
+
+    @app.command()
+    def sample():
+        pass
+
+    result = CliRunner().invoke(app, [])
+    assert result.exit_code == 0
+    assert "Usage:" in result.stdout
+    assert "Traceback" not in result.output
+    result = CliRunner().invoke(app, ["unknown"])
+    assert result.exit_code == 2
+    if automation:
+        assert json.loads(result.stderr)["error"]["code"] == "invalid-usage"
+        assert result.stdout == ""
+
+
+def test_automation_streams(monkeypatch):
+    monkeypatch.setenv("AUTOMATION_MODE", "enabled")
+    out, err = io.StringIO(), io.StringIO()
+    presenter = Presenter(out, err)
+    presenter.event({"message": "progress"})
+    presenter.outcome({"ok": True}, "Done")
+    assert json.loads(out.getvalue()) == {"ok": True}
+    assert json.loads(err.getvalue()) == {"message": "progress"}
+
+
+def test_automation_disables_terminal_prompts(monkeypatch):
+    import sys
+    from pyplines_cli_common.interaction import can_prompt
+
+    monkeypatch.setattr(sys.stdin, "isatty", lambda: True)
+    monkeypatch.setenv("AUTOMATION_MODE", "enabled")
+    assert not can_prompt()
+
+
+def test_unexpected_errors_do_not_leak(monkeypatch):
+    monkeypatch.setenv("AUTOMATION_MODE", "enabled")
+    app = typer.Typer(cls=Group, no_args_is_help=True)
+
+    @app.callback()
+    def options():
+        pass
+
+    @app.command()
+    def fail():
+        raise RuntimeError("private-token-in-url")
+
+    result = CliRunner().invoke(app, ["--verbose-errors", "fail"])
+    assert result.exit_code == 1
+    assert "private-token-in-url" not in result.output
+    assert "RuntimeError" in json.loads(result.stderr)["error"]["message"]