kata-cli 0.7.0__py3-none-any.whl

kata_cli-0.7.0.dist-info/METADATA

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: kata-cli
+Version: 0.7.0
+Summary: seer — codebase lookup and indexing for agent skills (greenfield AgentCulture sibling).
+Project-URL: Homepage, https://github.com/agentculture/seer-cli
+Project-URL: Issues, https://github.com/agentculture/seer-cli/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
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# seer-cli
+
+Codebase lookup and indexing for agent skills.
+
+## What's here
+
+- **`seer/`** — the package that will eventually expose the lookup
+  verbs. Greenfield: `learn` / `explain` / `whoami` are honest
+  placeholder stubs. See [`CLAUDE.md`](./CLAUDE.md) for build / test /
+  architecture details.
+
+- **`experiments/scripts_eval/`** — A/B-test harness for the `repo-map`
+  skill (env-var-gated hooks, three-layer scoring, 5-repo round-1
+  corpus). Round 1 is the validation gate before the verb design
+  lands. See
+  [`experiments/scripts_eval/README.md`](./experiments/scripts_eval/README.md)
+  and
+  [`experiments/scripts_eval/RUNBOOK.md`](./experiments/scripts_eval/RUNBOOK.md).

kata_cli-0.7.0.dist-info/RECORD

@@ -0,0 +1,33 @@
+seer/__init__.py,sha256=JQ3XCmXRjUVkwA0swxrWgXzGa2e4purayRsLYwnT3g0,1300
+seer/__main__.py,sha256=XUPM8sm0etIektS3zDQ8stjfTbdDjDZa_F1VajTKffI,136
+seer/cli/__init__.py,sha256=TDSqi-LbGWN786epJ_DzgYWrLuRuqCebrFGAPYdXyzo,4076
+seer/cli/_errors.py,sha256=mUhHlIlSFH0GsuTD0-oMjmJhjtWQiPseblhUIq6p2Vg,1953
+seer/cli/_output.py,sha256=wjSLvrjf9xFjj0C_flV8bAxAAZAkpgox0LA4NF17w4E,1594
+seer/cli/_commands/__init__.py,sha256=vMVWcay13DFXlUpLhsU-9ZYQ6HpZVerf_3jRXtjdvuA,83
+seer/cli/_commands/classify.py,sha256=hQQTwstftzzW4c0rX2u7u65QIjXUcjKWT9HscZXx6hM,1394
+seer/cli/_commands/explain.py,sha256=LnxkcGWTYXAq-fbSV4WfLJ8yXieGzHRwf_yQIeICt6A,1366
+seer/cli/_commands/grep.py,sha256=M-Mhqz9kK2lBUEmWkk67_6HjraUuDqOxMk_y00_8WW0,1414
+seer/cli/_commands/learn.py,sha256=yqtfOCsSwX-7rduHj0xRCHUtgtdjQep5u-5fgjnYRlg,1580
+seer/cli/_commands/recent.py,sha256=yR0ImB3WOx7FR_phOL5rL-vn7BhiYQSTcEsGtVY90b4,1585
+seer/cli/_commands/whoami.py,sha256=AjZt5W5ugbmUL1s0ZwQCbaLAiCOdeyEC4C6miiEkc50,1248
+seer/lookup/__init__.py,sha256=u9q8wcBDSo472KKbhoQPHRPOM-sTBTpXY0CWKF_Bh4U,799
+seer/lookup/ast_scope.py,sha256=IUgvBjBYlXuZtddK_Os2KxsZS9lCYGEE60i0z3fLMYM,2503
+seer/lookup/classify.py,sha256=lJpnefVxgG9MrBIWjARJEJJCir6nqhMKDRdCn1xaVKI,10293
+seer/lookup/grep_context.py,sha256=CpiEbvKtQQkvgRTDweGGtIU7KMYL7LZKSkuuVKzCR_8,5790
+seer/lookup/recent_outline.py,sha256=D-teevbUHLs8P8N5n7Y8xa6FZA_PPGsR6v-lH9qs5b8,10592
+seer/lookup/render.py,sha256=0wPrnj8dKOZr-_sEWFmuBQnBfcb8bKZq69fF0Amkz4c,1196
+seer/repo/__init__.py,sha256=eHjI3F-h_eI56o9zHINW4SakRFu2G5CWaHLX12fquX4,276
+seer/repo/__main__.py,sha256=kZdp2R-DaNur5w5sX7mUhAn3xnM0d-m4y_IhMqZJcPs,7654
+seer/repo/config.py,sha256=N63dYJ8dKwrIS__pL3AHGFvDZq4_tHCAhfFy2MCMfYo,1857
+seer/repo/connections.py,sha256=JdfX9JrWASZoPWwWN72xW10jwY4ixYJyYQg_qr-OAu8,9532
+seer/repo/detect.py,sha256=zTfdqZAVP_n0RawPEd7zaTmwe9LAEtdpQNCAYCPB4CE,2781
+seer/repo/errors.py,sha256=VaSFXB2_j-ZhuYjL2kszBbjRYS3a9YB_fL87zfHPKfY,2969
+seer/repo/graph.py,sha256=r5AXfjq6dGxGcl0VC31BLoWXZbS6Hscj1W-r2CouHFk,5947
+seer/repo/manifest.py,sha256=2Vc7FvWBTqpXHuX9uKKYqP5LGpqmzRgdszlEcAFzgLo,1264
+seer/repo/profile.py,sha256=BqwOwW_yV-8rW9lNx-8sYrYZouImIdHHPQaePCznZdc,25299
+seer/repo/render.py,sha256=wbfkDG8Wfyp5wzFHZ-aD1u1sl7mMVl_gOzWDs_r0wWc,16205
+kata_cli-0.7.0.dist-info/METADATA,sha256=2sRMh2hZWzRADX_F2ygr-FDPEnhBSFgUcaDW11hdJDg,1364
+kata_cli-0.7.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+kata_cli-0.7.0.dist-info/entry_points.txt,sha256=wXuXJDkd57Utvp9VV6iqRp6I3fojmwdNHcqiHTqx4r4,60
+kata_cli-0.7.0.dist-info/licenses/LICENSE,sha256=wCcdPywGtFXx1P8N0j0eEDINSWfSjrIsU7ds1YZl-MA,1069
+kata_cli-0.7.0.dist-info/RECORD,,

kata_cli-0.7.0.dist-info/WHEEL

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

kata_cli-0.7.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+kata = seer.cli:main
+seer = seer.cli:main

kata_cli-0.7.0.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.

seer/__init__.py

@@ -0,0 +1,34 @@
+"""seer — codebase lookup and indexing for agent skills (greenfield AgentCulture sibling)."""
+
+from importlib.metadata import PackageNotFoundError, packages_distributions
+from importlib.metadata import version as _v
+
+
+def _resolve_version() -> str:
+    """Resolve the installed-distribution version of the ``seer`` package.
+
+    The same source ships under multiple PyPI distribution names (``seer-cli``,
+    ``kata-cli``, ``code-lens-cli``) per the lean dual-publish slice of issue
+    #17. Look up which distribution provides the ``seer`` top-level package
+    via ``importlib.metadata.packages_distributions()`` and return its
+    version. Falls back through a known-name allowlist if that lookup is
+    unavailable, and finally to ``0.0.0+local`` for editable installs without
+    metadata.
+    """
+    dist_map = packages_distributions()
+    for dist in dist_map.get("seer") or []:
+        try:
+            return _v(dist)
+        except PackageNotFoundError:
+            continue
+    for fallback in ("seer-cli", "kata-cli", "code-lens-cli"):
+        try:
+            return _v(fallback)
+        except PackageNotFoundError:
+            continue
+    return "0.0.0+local"  # pragma: no cover  — editable install without metadata
+
+
+__version__ = _resolve_version()
+
+__all__ = ["__version__"]

seer/__main__.py

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

seer/cli/__init__.py

@@ -0,0 +1,117 @@
+"""Unified CLI entry point for seer.
+
+Error-propagation contract: every handler raises
+:class:`seer.cli._errors.SeerError` on failure; ``main()`` catches it via
+:func:`_dispatch` and routes through :mod:`seer.cli._output`. Unknown
+exceptions are wrapped into a ``SeerError`` so no Python traceback leaks.
+
+Argparse errors (unknown verb, missing required arg) also route through the
+structured format — :class:`_SeerArgumentParser` overrides ``.error()``.
+Whether errors render as text or JSON depends on whether ``--json`` appears in
+the raw argv (:func:`main` sets ``_SeerArgumentParser._json_hint`` before
+``parse_args``).
+"""
+
+# pylint: disable=duplicate-code  # _dispatch mirrors seer.repo.__main__ by design
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from seer import __version__
+from seer.cli._errors import EXIT_USER_ERROR, SeerError
+from seer.cli._output import emit_error
+
+
+class _SeerArgumentParser(argparse.ArgumentParser):
+    """ArgumentParser that routes errors through :func:`emit_error`."""
+
+    _json_hint: bool = False
+
+    def error(self, message: str) -> None:  # type: ignore[override]
+        err = SeerError(
+            code=EXIT_USER_ERROR,
+            message=message,
+            remediation=f"run '{self.prog} --help' to see valid arguments",
+        )
+        emit_error(err, json_mode=type(self)._json_hint)
+        raise SystemExit(err.code)
+
+
+def _argv_has_json(argv: list[str] | None) -> bool:
+    tokens = argv if argv is not None else sys.argv[1:]
+    return any(t == "--json" or t.startswith("--json=") for t in tokens)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = _SeerArgumentParser(
+        prog="seer",
+        description="seer — codebase lookup and indexing for agent skills (greenfield).",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    sub = parser.add_subparsers(dest="command", parser_class=_SeerArgumentParser)
+
+    # pylint: disable=import-outside-toplevel
+    from seer.cli._commands import classify as _classify_cmd
+    from seer.cli._commands import explain as _explain_cmd
+    from seer.cli._commands import grep as _grep_cmd
+    from seer.cli._commands import learn as _learn_cmd
+    from seer.cli._commands import recent as _recent_cmd
+    from seer.cli._commands import whoami as _whoami_cmd
+
+    # pylint: enable=import-outside-toplevel
+
+    _learn_cmd.register(sub)
+    _explain_cmd.register(sub)
+    _whoami_cmd.register(sub)
+    _classify_cmd.register(sub)
+    _grep_cmd.register(sub)
+    _recent_cmd.register(sub)
+
+    return parser
+
+
+def _dispatch(args: argparse.Namespace) -> int:  # pylint: disable=duplicate-code
+    """Invoke the registered handler and translate exceptions to exit codes.
+
+    A handler may return ``None`` (treated as success, exit 0) or an ``int``
+    used directly as the exit code. Failures MUST raise :class:`SeerError`;
+    any other exception is wrapped so no Python traceback leaks.
+    """
+    json_mode = bool(getattr(args, "json", False))
+    try:
+        rc = args.func(args)
+    except SeerError as err:
+        emit_error(err, json_mode=json_mode)
+        return err.code
+    except Exception as err:  # noqa: BLE001  # pylint: disable=broad-exception-caught
+        wrapped = SeerError(
+            code=EXIT_USER_ERROR,
+            message=f"unexpected: {err.__class__.__name__}: {err}",
+            remediation="file a bug at https://github.com/agentculture/seer-cli/issues",
+        )
+        emit_error(wrapped, json_mode=json_mode)
+        return wrapped.code
+    return rc if rc is not None else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Parse *argv* (defaults to ``sys.argv[1:]``) and dispatch to a verb handler."""
+    _SeerArgumentParser._json_hint = _argv_has_json(argv)  # pylint: disable=protected-access
+    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())

seer/cli/_commands/__init__.py

@@ -0,0 +1 @@
+"""seer CLI verb modules — one module per verb, each exposing ``register()``."""

seer/cli/_commands/classify.py

@@ -0,0 +1,40 @@
+"""``seer classify [path]`` — project-type classifier.
+
+Returns a deterministic list of tags describing what kind of project the
+repo at *path* is (cli / library / dockerized / tested / packaged-pypi / …),
+each paired with concrete file-grounded evidence.
+"""
+
+# pylint: disable=duplicate-code  # verb-registration boilerplate
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from seer.cli._output import emit_result
+from seer.lookup.classify import classify
+from seer.lookup.render import render_classify_markdown
+
+
+def cmd_classify(args: argparse.Namespace) -> int:
+    """Handle the ``classify`` verb."""
+    path = Path(args.path).resolve()
+    data = classify(path)
+    json_mode = bool(getattr(args, "json", False))
+    if json_mode:
+        emit_result({"ok": True, "data": data}, json_mode=True)
+    else:
+        emit_result(render_classify_markdown(data), json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    """Register the ``classify`` sub-command on *sub*."""
+    p = sub.add_parser(
+        "classify",
+        help="Classify a repo by project-type tags (cli / library / dockerized / …).",
+    )
+    p.add_argument("path", nargs="?", default=".", help="Path to the repo (default: cwd).")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_classify)

seer/cli/_commands/explain.py

@@ -0,0 +1,44 @@
+"""``seer explain`` — placeholder verb.
+
+See :mod:`seer.cli._commands.learn` for why the verbs are stubs. ``explain``
+will eventually print docs for a given topic / command path; today it prints
+an honest "not yet implemented" line.
+"""
+
+# pylint: disable=duplicate-code  # intentional: three stub verbs share the same structure
+
+from __future__ import annotations
+
+import argparse
+
+from seer import __version__
+from seer.cli._output import emit_result
+
+_TEXT = "seer explain — not yet implemented; seer is greenfield. See CLAUDE.md."
+
+
+def _json_payload() -> dict[str, object]:
+    return {
+        "tool": "seer",
+        "version": __version__,
+        "status": "greenfield",
+        "verb": "explain",
+        "message": _TEXT,
+    }
+
+
+def cmd_explain(args: argparse.Namespace) -> int:
+    """Handle the ``explain`` verb — print status and return 0."""
+    json_mode = bool(getattr(args, "json", False))
+    if json_mode:
+        emit_result(_json_payload(), json_mode=True)
+    else:
+        emit_result(_TEXT, json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    """Register the ``explain`` sub-command on *sub*."""
+    p = sub.add_parser("explain", help="Explain a seer topic or command (stub).")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_explain)

seer/cli/_commands/grep.py

@@ -0,0 +1,44 @@
+"""``seer grep <pattern> [path]`` — AST-scope-augmented ripgrep search.
+
+Runs ``rg --json <pattern> <path>`` and pairs every match with the enclosing
+Python function or class name via the AST scope resolver.
+"""
+
+# pylint: disable=duplicate-code  # verb-registration boilerplate
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from seer.cli._output import emit_result
+from seer.lookup.grep_context import grep_with_context, render_grep_markdown
+
+
+def cmd_grep(args: argparse.Namespace) -> int:
+    """Handle the ``grep`` verb."""
+    path = Path(args.path).resolve()
+    data = grep_with_context(args.pattern, path)
+    json_mode = bool(getattr(args, "json", False))
+    if json_mode:
+        emit_result(data, json_mode=True)
+    else:
+        emit_result(render_grep_markdown(data), json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    """Register the ``grep`` sub-command on *sub*."""
+    p = sub.add_parser(
+        "grep",
+        help="Search a codebase with rg and annotate each match with its AST scope.",
+    )
+    p.add_argument("pattern", help="Regex pattern to search for.")
+    p.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="File or directory to search (default: cwd).",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_grep)

seer/cli/_commands/learn.py

@@ -0,0 +1,49 @@
+"""``seer learn`` — placeholder verb.
+
+seer is a greenfield AgentCulture sibling: the scaffold (package, CLI
+chassis, CI, vendored skills) is in place but the codebase lookup and
+indexing engine itself is not implemented yet. This verb prints an honest
+status line so a probing agent or human gets a clear signal rather than a
+misleading response.
+"""
+
+# pylint: disable=duplicate-code  # intentional: three stub verbs share the same structure
+
+from __future__ import annotations
+
+import argparse
+
+from seer import __version__
+from seer.cli._output import emit_result
+
+_TEXT = (
+    "seer — codebase lookup and indexing for agent skills. Not yet implemented; "
+    "seer is a greenfield AgentCulture sibling. See CLAUDE.md."
+)
+
+
+def _json_payload() -> dict[str, object]:
+    return {
+        "tool": "seer",
+        "version": __version__,
+        "status": "greenfield",
+        "verb": "learn",
+        "message": _TEXT,
+    }
+
+
+def cmd_learn(args: argparse.Namespace) -> int:
+    """Handle the ``learn`` verb — print status and return 0."""
+    json_mode = bool(getattr(args, "json", False))
+    if json_mode:
+        emit_result(_json_payload(), json_mode=True)
+    else:
+        emit_result(_TEXT, json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:  # pylint: disable=duplicate-code
+    """Register the ``learn`` sub-command on *sub*."""
+    p = sub.add_parser("learn", help="Print seer's self-teaching status line.")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_learn)

seer/cli/_commands/recent.py

@@ -0,0 +1,52 @@
+"""``seer recent [path] [-n N]`` — git commit log paired with AST symbol diffs.
+
+Runs ``git log -n N`` in *path*, and for each commit pairs every changed file
+with a structural symbol-diff at the AST level (functions/classes added /
+removed / modified).
+"""
+
+# pylint: disable=duplicate-code  # verb-registration boilerplate
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from seer.cli._output import emit_result
+from seer.lookup.recent_outline import recent_with_outline, render_recent_markdown
+
+
+def cmd_recent(args: argparse.Namespace) -> int:
+    """Handle the ``recent`` verb."""
+    path = Path(args.path).resolve()
+    data = recent_with_outline(n=args.count, path=path)
+    json_mode = bool(getattr(args, "json", False))
+    if json_mode:
+        emit_result(data, json_mode=True)
+    else:
+        emit_result(render_recent_markdown(data), json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    """Register the ``recent`` sub-command on *sub*."""
+    p = sub.add_parser(
+        "recent",
+        help="Show recent git commits paired with AST symbol diffs per file.",
+    )
+    p.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="Path to the git repository (default: cwd).",
+    )
+    p.add_argument(
+        "-n",
+        "--count",
+        type=int,
+        default=20,
+        metavar="N",
+        help="Number of commits to show (default: 20).",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_recent)

seer/cli/_commands/whoami.py

@@ -0,0 +1,42 @@
+"""``seer whoami`` — placeholder verb.
+
+See :mod:`seer.cli._commands.learn` for why the verbs are stubs. ``whoami``
+will eventually be the smallest identity / auth probe; today it prints an
+honest "not yet implemented" line.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from seer import __version__
+from seer.cli._output import emit_result
+
+_TEXT = "seer — not yet implemented; seer is greenfield. See CLAUDE.md."
+
+
+def _json_payload() -> dict[str, object]:
+    return {
+        "tool": "seer",
+        "version": __version__,
+        "status": "greenfield",
+        "verb": "whoami",
+        "message": _TEXT,
+    }
+
+
+def cmd_whoami(args: argparse.Namespace) -> int:
+    """Handle the ``whoami`` verb — print status and return 0."""
+    json_mode = bool(getattr(args, "json", False))
+    if json_mode:
+        emit_result(_json_payload(), json_mode=True)
+    else:
+        emit_result(_TEXT, json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    """Register the ``whoami`` sub-command on *sub*."""
+    p = sub.add_parser("whoami", help="Print seer's identity probe (stub).")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_whoami)

seer/cli/_errors.py

@@ -0,0 +1,59 @@
+"""SeerError and exit-code policy.
+
+Every failure inside seer raises :class:`SeerError`. The top-level
+``main()`` catches it, formats via :mod:`seer.cli._output`, and exits with
+:attr:`SeerError.code`. This centralises the exit-code policy and guarantees
+no Python traceback leaks to stderr.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Exit-code policy:
+#   0  = success
+#   1  = user-input error (bad flag, missing required arg, unknown path)
+#   2  = environment / setup error (tool not installed, file unreadable)
+#   3  = internal bug (uncaught exception wrapped by _dispatch)
+#   4+ = reserved for future categorisation
+EXIT_SUCCESS = 0
+EXIT_USER_ERROR = 1
+EXIT_ENV_ERROR = 2
+EXIT_INTERNAL = 3
+
+
+@dataclass
+class SeerError(Exception):
+    """Structured error raised within seer.
+
+    Fields:
+      code:        exit code (see constants above)
+      message:     one-sentence plain-English description of what went wrong
+      remediation: optional concrete next step for the user/agent
+      reason:      optional root-cause sentence (what was tried, why it failed)
+      kind:        optional short tag — "user_error" | "env_error" | "bug"
+
+    Renderers (:func:`seer.cli._output.emit_error`) skip empty optional
+    fields so older call sites that only set code+message+remediation keep
+    producing the same output.
+    """
+
+    code: int
+    message: str
+    remediation: str = ""
+    reason: str = ""
+    kind: str = ""
+
+    def __post_init__(self) -> None:
+        super().__init__(self.message)
+
+    def to_dict(self) -> dict[str, object]:
+        """Serialise to a plain dict suitable for JSON output."""
+        out: dict[str, object] = {"code": self.code, "message": self.message}
+        if self.kind:
+            out["kind"] = self.kind
+        if self.reason:
+            out["reason"] = self.reason
+        if self.remediation:
+            out["remediation"] = self.remediation
+        return out

seer/cli/_output.py

@@ -0,0 +1,47 @@
+"""stdout / stderr helpers with a strict split.
+
+Rule: **results go to stdout, diagnostics and errors go to stderr.** Agents
+parsing seer output can rely on this invariant. JSON mode routes structured
+payloads to the same streams — it never mixes them.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, TextIO
+
+from seer.cli._errors import SeerError
+
+
+def emit_result(data: Any, *, json_mode: bool, stream: TextIO | None = None) -> None:
+    """Write a command result to stdout (text or JSON), newline-terminated."""
+    s = stream if stream is not None else sys.stdout
+    if json_mode:
+        json.dump(data, s, ensure_ascii=False)
+        s.write("\n")
+        return
+    text = data if isinstance(data, str) else str(data)
+    s.write(text)
+    if not text.endswith("\n"):
+        s.write("\n")
+
+
+def emit_error(err: SeerError, *, json_mode: bool, stream: TextIO | None = None) -> None:
+    """Write a :class:`SeerError` to stderr (text or JSON)."""
+    s = stream if stream is not None else sys.stderr
+    if json_mode:
+        json.dump(err.to_dict(), s, ensure_ascii=False)
+        s.write("\n")
+        return
+    s.write(f"error: {err.message}\n")
+    if err.reason:
+        s.write(f"reason: {err.reason}\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 (progress, summary) to stderr."""
+    s = stream if stream is not None else sys.stderr
+    s.write(message if message.endswith("\n") else message + "\n")