steward-cli 0.1.2__py3-none-any.whl

steward/__init__.py

@@ -0,0 +1,11 @@
+"""steward — aligns and maintains resident agents across Culture projects."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _v
+
+try:
+    __version__ = _v("steward-cli")
+except PackageNotFoundError:
+    __version__ = "0.0.0+local"
+
+__all__ = ["__version__"]

steward/__main__.py

@@ -0,0 +1,8 @@
+"""Allow running steward as ``python -m steward``."""
+
+import sys
+
+from steward.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

steward/cli/__init__.py

@@ -0,0 +1,82 @@
+"""Unified CLI entry point for steward.
+
+Every handler raises :class:`steward.cli._errors.StewardError` on failure;
+``main()`` catches it via :func:`_dispatch` and routes through
+:mod:`steward.cli._output`. Argparse errors route through
+``_StewardArgumentParser`` so they share the same structured output.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from steward import __version__
+from steward.cli._errors import EXIT_USER_ERROR, StewardError
+from steward.cli._output import emit_error
+
+
+class _StewardArgumentParser(argparse.ArgumentParser):
+    """ArgumentParser that routes errors through :func:`emit_error`."""
+
+    def error(self, message: str) -> None:  # type: ignore[override]
+        err = StewardError(
+            code=EXIT_USER_ERROR,
+            message=message,
+            remediation=f"run '{self.prog} --help' to see valid arguments",
+        )
+        emit_error(err)
+        raise SystemExit(err.code)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    # Deferred import to avoid coupling the parser module to the command modules
+    # at import time (matches afi-cli's pattern; cheap insurance).
+    from steward.cli._commands import show as _show_cmd
+
+    parser = _StewardArgumentParser(
+        prog="steward",
+        description="steward — align and maintain resident agents across Culture projects",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    sub = parser.add_subparsers(dest="command", parser_class=_StewardArgumentParser)
+
+    _show_cmd.register(sub)
+
+    return parser
+
+
+def _dispatch(args: argparse.Namespace) -> int:
+    try:
+        rc = args.func(args)
+    except StewardError as err:
+        emit_error(err)
+        return err.code
+    except Exception as err:  # noqa: BLE001 - last-resort: wrap so no traceback leaks
+        wrapped = StewardError(
+            code=EXIT_USER_ERROR,
+            message=f"unexpected: {err.__class__.__name__}: {err}",
+            remediation="file a bug at https://github.com/agentculture/steward/issues",
+        )
+        emit_error(wrapped)
+        return wrapped.code
+    return rc if rc is not None else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    return _dispatch(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

steward/cli/_commands/show.py

@@ -0,0 +1,116 @@
+"""``steward show`` — wraps the agent-config skill's show.sh.
+
+The skill (``.claude/skills/agent-config/scripts/show.sh``) is the canonical
+implementation. The CLI is just a typed surface so people can run
+``steward show ../culture`` instead of remembering the script path.
+
+If the skill script is missing (e.g. someone ``pip install``ed steward-cli
+without cloning the repo), the command exits with a clear error pointing at
+where the skill should live.
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+from steward.cli._errors import EXIT_ENV_ERROR, EXIT_USER_ERROR, StewardError
+
+
+def _find_git_root(start: Path) -> Path | None:
+    """Return the nearest enclosing directory containing ``.git`` (or None)."""
+    for directory in (start, *start.parents):
+        if (directory / ".git").exists():
+            return directory
+    return None
+
+
+def _resolve_skill_script() -> Path:
+    """Locate ``.claude/skills/agent-config/scripts/show.sh`` inside the current
+    git repo.
+
+    Walks up from cwd, but **stops at the git repository boundary** so
+    ``steward show`` never executes a script from an ancestor directory
+    outside the user's current checkout. If cwd isn't inside any git repo,
+    only cwd itself is checked. This eliminates the "search-path injection"
+    risk where an attacker-placed ancestor directory could supply the script.
+    """
+    start = Path.cwd().resolve()
+    repo_root = _find_git_root(start)
+
+    current = start
+    while True:
+        candidate = current / ".claude" / "skills" / "agent-config" / "scripts" / "show.sh"
+        if candidate.is_file():
+            return candidate
+        if current == repo_root or current.parent == current:
+            # Hit the git boundary or the filesystem root — stop walking.
+            break
+        if repo_root is None:
+            # Not inside a git repo: only inspect cwd itself, never ancestors.
+            break
+        current = current.parent
+
+    raise StewardError(
+        code=EXIT_ENV_ERROR,
+        message="agent-config skill script not found",
+        remediation=(
+            "run from inside a Steward git checkout that contains "
+            ".claude/skills/agent-config/scripts/show.sh"
+        ),
+    )
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser(
+        "show",
+        help="Show a Culture agent's full configuration in one view.",
+        description=(
+            "Surface a Culture agent's CLAUDE.md, parallel culture.yaml, and "
+            ".claude/skills/ index. Wraps the agent-config skill script."
+        ),
+    )
+    parser.add_argument(
+        "target",
+        help="Path to a project directory or a registered agent suffix.",
+    )
+    parser.set_defaults(func=_handle)
+
+
+def _handle(args: argparse.Namespace) -> int:
+    script = _resolve_skill_script()
+    # Capture and forward via Python streams so pytest's capsys/capfd both
+    # see the output. Going through sys.stdout/sys.stderr.write keeps the
+    # split (skill stdout → CLI stdout, skill stderr → CLI stderr).
+    #
+    # bandit S603: argv is a fixed list; the target is a positional string
+    # passed straight to the script (no shell, no expansion). Resolution
+    # of the script itself is constrained to the current git repo by
+    # _resolve_skill_script(), so an attacker can't substitute a different
+    # show.sh from an ancestor directory.
+    try:
+        completed = subprocess.run(  # noqa: S603
+            [str(script), args.target],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+    except OSError as exc:
+        raise StewardError(
+            code=EXIT_ENV_ERROR,
+            message=f"could not execute {script}: {exc}",
+            remediation="ensure the script is executable (chmod +x)",
+        ) from exc
+    if completed.stdout:
+        sys.stdout.write(completed.stdout)
+    if completed.stderr:
+        sys.stderr.write(completed.stderr)
+    if completed.returncode != 0:
+        raise StewardError(
+            code=EXIT_USER_ERROR if completed.returncode == 2 else EXIT_ENV_ERROR,
+            message=f"agent-config script exited {completed.returncode}",
+            remediation=f"see stderr from {script.name}",
+        )
+    return 0

steward/cli/_errors.py

@@ -0,0 +1,37 @@
+"""StewardError and exit-code policy.
+
+Every failure inside steward raises :class:`StewardError`. The top-level
+``main()`` catches it, formats via :mod:`steward.cli._output`, and exits with
+:attr:`StewardError.code`. This guarantees:
+
+* no Python traceback leaks to stderr;
+* every error has a structured shape ``{code, message, remediation}``;
+* the exit-code policy is centralised in one place.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+EXIT_SUCCESS = 0
+EXIT_USER_ERROR = 1
+EXIT_ENV_ERROR = 2
+
+
+@dataclass
+class StewardError(Exception):
+    """Structured error raised within steward; carries a remediation hint."""
+
+    code: int
+    message: str
+    remediation: str = ""
+
+    def __post_init__(self) -> None:
+        super().__init__(self.message)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "code": self.code,
+            "message": self.message,
+            "remediation": self.remediation,
+        }

steward/cli/_output.py

@@ -0,0 +1,41 @@
+"""stdout / stderr helpers with a strict split.
+
+Rule: results go to stdout, diagnostics and errors go to stderr. Agents
+parsing steward output can rely on this invariant.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, TextIO
+
+from steward.cli._errors import StewardError
+
+
+def emit_result(data: Any, *, stream: TextIO | None = None) -> None:
+    """Write a command result to stdout (default)."""
+    s = stream if stream is not None else sys.stdout
+    text = data if isinstance(data, str) else str(data)
+    s.write(text)
+    if not text.endswith("\n"):
+        s.write("\n")
+
+
+def emit_error(err: StewardError, *, stream: TextIO | None = None) -> None:
+    """Write a :class:`StewardError` to stderr.
+
+    Renders as one or two lines::
+
+        error: <message>
+        hint: <remediation>
+    """
+    s = stream if stream is not None else sys.stderr
+    s.write(f"error: {err.message}\n")
+    if err.remediation:
+        s.write(f"hint: {err.remediation}\n")
+
+
+def emit_diagnostic(message: str, *, stream: TextIO | None = None) -> None:
+    """Write a human diagnostic to stderr."""
+    s = stream if stream is not None else sys.stderr
+    s.write(message if message.endswith("\n") else message + "\n")

steward_cli-0.1.2.dist-info/METADATA

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: steward-cli
+Version: 0.1.2
+Summary: Steward — aligns and maintains resident agents across Culture projects.
+Project-URL: Homepage, https://github.com/agentculture/steward
+Project-URL: Issues, https://github.com/agentculture/steward/issues
+Author: AgentCulture
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# steward
+
+Steward aligns and maintains resident agents across Culture projects.
+
+## Install
+
+```bash
+pip install steward-cli
+```
+
+Or, with [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv tool install steward-cli
+```
+
+## Usage
+
+```bash
+steward --version
+steward --help
+
+# Show a Culture agent's full configuration in one view
+# (CLAUDE.md + the parallel culture.yaml + .claude/skills/ index).
+# Run from inside a Steward checkout — the command finds the agent-config
+# skill script via a walk-up from the current working directory.
+steward show ../culture
+steward show ../daria
+```
+
+`steward show` is a thin wrapper over the `agent-config` skill at
+`.claude/skills/agent-config/scripts/show.sh`. The skill remains the canonical
+implementation; the CLI is the typed entry point.
+
+See [`CLAUDE.md`](CLAUDE.md) for project-shape, build/test/publish details, and
+the skills convention.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

steward_cli-0.1.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+steward/__init__.py,sha256=Jji1ismBtgM9lXW3KygrlhthFuYHlo2o1G1yrEw0-ls,308
+steward/__main__.py,sha256=MZEjt3hBuGmcoGEin37oQyBiS4XHVnmLZvuP1qgXH_g,145
+steward/cli/__init__.py,sha256=61Q2haUoZN7T_aDCtzzIZOFtN1OelUMZDn2Pfx0zJzk,2466
+steward/cli/_errors.py,sha256=3w024MCV-WuwkKU-p8GF_NBUfZXeqDHLbUZVgGtv8AU,971
+steward/cli/_output.py,sha256=054l0nNt-uDUCwUL89NEWFpOdxd31JjRrphVGhZpm-Y,1236
+steward/cli/_commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+steward/cli/_commands/show.py,sha256=TqLyq8Slh8zXgX9Kwvy832bU-09KpmNrtDtt-hfXhw0,4309
+steward_cli-0.1.2.dist-info/METADATA,sha256=AKclOn8wTdCOGVWE0vueRMHEsnyZmwa9RHTfJdVYrzE,1567
+steward_cli-0.1.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+steward_cli-0.1.2.dist-info/entry_points.txt,sha256=6mbfyrAed822bovEbJjnCowTdG_NeIB2LBAwgMf4PnQ,45
+steward_cli-0.1.2.dist-info/licenses/LICENSE,sha256=d-o3g1Varo3ruZBbZUlkdoDVJBoIhutjarID0c0OIyU,1069
+steward_cli-0.1.2.dist-info/RECORD,,

steward_cli-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

steward_cli-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+steward = steward.cli:main

steward_cli-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentculture
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.