tipalti 0.0.1__py3-none-any.whl

tipalti/__init__.py

@@ -0,0 +1,13 @@
+"""tipalti — agent-first CLI package."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("tipalti")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

tipalti/__main__.py

@@ -0,0 +1,10 @@
+"""Entry point for ``python -m tipalti``."""
+
+from __future__ import annotations
+
+import sys
+
+from tipalti.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

tipalti/cli/__init__.py

@@ -0,0 +1,84 @@
+"""Unified CLI entry point for tipalti.
+
+Noun-based command groups and globals are registered here. Top-level globals
+(``learn``, ``explain``) live under :mod:`tipalti.cli._commands`; per-noun
+groups follow the same pattern.
+
+Error-propagation contract: every handler raises
+:class:`tipalti.cli._errors.AfiError` on failure; :func:`main` catches it
+via :func:`_dispatch` and routes through :mod:`tipalti.cli._output`.
+Unknown exceptions are wrapped so no Python traceback leaks.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from tipalti import __version__
+from tipalti.cli._commands import explain as _explain_cmd
+from tipalti.cli._commands import learn as _learn_cmd
+from tipalti.cli._commands import whoami as _whoami_cmd
+from tipalti.cli._errors import EXIT_USER_ERROR, AfiError
+from tipalti.cli._output import emit_error
+
+
+class _ArgumentParser(argparse.ArgumentParser):
+    """ArgumentParser that emits errors via our structured format."""
+
+    def error(self, message: str) -> None:  # type: ignore[override]
+        err = AfiError(
+            code=EXIT_USER_ERROR,
+            message=message,
+            remediation=f"run '{self.prog} --help' to see valid arguments",
+        )
+        emit_error(err, json_mode=False)
+        raise SystemExit(err.code)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = _ArgumentParser(
+        prog="tipalti",
+        description="tipalti — agent-first CLI.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    _learn_cmd.register(sub)
+    _explain_cmd.register(sub)
+    _whoami_cmd.register(sub)
+    # Register noun groups here:
+    #   from tipalti.cli._commands import my_noun as _my_noun_group
+    #   _my_noun_group.register(sub)
+
+    return parser
+
+
+def _dispatch(args: argparse.Namespace) -> int:
+    json_mode = bool(getattr(args, "json", False))
+    try:
+        return args.func(args)
+    except AfiError as err:
+        emit_error(err, json_mode=json_mode)
+        return err.code
+    except Exception as err:  # noqa: BLE001 - last-resort
+        wrapped = AfiError(
+            code=EXIT_USER_ERROR,
+            message=f"unexpected: {err.__class__.__name__}: {err}",
+            remediation="file a bug",
+        )
+        emit_error(wrapped, json_mode=json_mode)
+        return wrapped.code
+
+
+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())

tipalti/cli/_commands/explain.py

@@ -0,0 +1,38 @@
+"""``tipalti explain <path>...`` — global markdown catalog lookup (stable-contract).
+
+``explain`` is global (not nested under a noun). It takes zero or more path
+tokens and resolves them via the catalog in :mod:`tipalti.explain`.
+Unknown paths raise :class:`AfiError` with a remediation hint.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from tipalti.cli._output import emit_result
+from tipalti.explain import resolve
+
+
+def cmd_explain(args: argparse.Namespace) -> int:
+    path = tuple(args.path) if args.path else ()
+    markdown = resolve(path)
+    json_mode = bool(getattr(args, "json", False))
+    if json_mode:
+        emit_result({"path": list(path), "markdown": markdown}, json_mode=True)
+    else:
+        emit_result(markdown, json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "explain",
+        help="Print markdown docs for a noun/verb path (e.g. 'tipalti explain cli foo').",
+    )
+    p.add_argument(
+        "path",
+        nargs="*",
+        help="Command path tokens; empty = root (same as 'tipalti').",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_explain)

tipalti/cli/_commands/learn.py

@@ -0,0 +1,82 @@
+"""``tipalti learn`` — the learnability affordance (shape-adapt)."""
+
+from __future__ import annotations
+
+import argparse
+
+from tipalti import __version__
+from tipalti.cli._output import emit_result
+
+_TEXT = """\
+tipalti — CLI for Tipalti Solutions.
+
+Purpose
+-------
+tipalti is a command-line interface for working with Tipalti Solutions.
+The v0.0.1 surface ships only the agent-first affordances (`learn`,
+`explain`) and an auth-probe stub (`whoami`); domain verbs that talk to
+the Tipalti API land in subsequent releases.
+
+Commands
+--------
+  tipalti learn              Print this self-teaching prompt. Supports --json.
+  tipalti explain <path>...  Print markdown docs for any noun/verb path.
+                              Supports --json.
+  tipalti whoami             Print the active Tipalti principal. Stub for
+                              now (always reports "unauthenticated") until
+                              real Tipalti API auth is wired. Supports --json.
+
+Machine-readable output
+-----------------------
+Every command that produces a listing or report supports --json. Errors in
+JSON mode emit {"code", "message", "remediation"} to stderr. Stdout and
+stderr are never mixed.
+
+Exit-code policy
+----------------
+  0 success
+  1 user-input error (bad flag, bad path, missing arg)
+  2 environment / setup error
+  3+ reserved
+
+More detail
+-----------
+  tipalti explain tipalti
+"""
+
+
+def _as_json_payload() -> dict[str, object]:
+    return {
+        "tool": "tipalti",
+        "version": __version__,
+        "purpose": "CLI for Tipalti Solutions.",
+        "commands": [
+            {"path": ["learn"], "summary": "Self-teaching prompt."},
+            {"path": ["explain"], "summary": "Markdown docs by path."},
+            {"path": ["whoami"], "summary": "Auth probe (stub in v0.0.1)."},
+        ],
+        "exit_codes": {
+            "0": "success",
+            "1": "user-input error",
+            "2": "environment/setup error",
+        },
+        "json_support": True,
+        "explain_pointer": "tipalti explain <path>",
+    }
+
+
+def cmd_learn(args: argparse.Namespace) -> int:
+    if getattr(args, "json", False):
+        emit_result(_as_json_payload(), json_mode=True)
+    else:
+        emit_result(_TEXT, json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "learn",
+        help="Print a structured self-teaching prompt for agent consumers.",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_learn)

tipalti/cli/_commands/whoami.py

@@ -0,0 +1,29 @@
+"""``tipalti whoami`` — auth probe stub (Tipalti-specific).
+
+Returns ``unauthenticated`` until real Tipalti API auth lands. Supports
+``--json``. Exit code is always ``0`` (probe, not gate).
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from tipalti.cli._output import emit_result
+
+
+def cmd_whoami(args: argparse.Namespace) -> int:
+    payload: dict[str, object] = {"status": "unauthenticated", "principal": None}
+    if getattr(args, "json", False):
+        emit_result(payload, json_mode=True)
+    else:
+        emit_result("unauthenticated", json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "whoami",
+        help="Print the active Tipalti principal (stub in v0.0.1).",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_whoami)

tipalti/cli/_errors.py

@@ -0,0 +1,41 @@
+"""AfiError and exit-code policy (stable-contract — copy verbatim).
+
+Every failure inside tipalti raises :class:`AfiError`. The CLI entry
+point catches it and exits with :attr:`AfiError.code`. Guarantees:
+
+* no Python traceback leaks to stderr;
+* every error has shape ``{code, message, remediation}``;
+* the exit-code policy is centralised.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Exit-code policy (documented in ``tipalti learn`` output).
+# 0  = success
+# 1  = user-input error (bad flag, bad path, missing arg)
+# 2  = environment / setup error
+# 3+ = reserved
+EXIT_SUCCESS = 0
+EXIT_USER_ERROR = 1
+EXIT_ENV_ERROR = 2
+
+
+@dataclass
+class AfiError(Exception):
+    """Structured error with a remediation hint for agents."""
+
+    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,
+        }

tipalti/cli/_output.py

@@ -0,0 +1,53 @@
+"""stdout / stderr helpers with a strict split (stable-contract).
+
+Rule: **results go to stdout, diagnostics and errors go to stderr.** Agents
+parsing output can rely on this invariant. JSON mode routes structured
+payloads to the same streams — never mixes them.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, TextIO
+
+from tipalti.cli._errors import AfiError
+
+
+def emit_result(data: Any, *, json_mode: bool, stream: TextIO | None = None) -> None:
+    """Write a command result to stdout (or ``stream``)."""
+    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: AfiError, *, json_mode: bool, stream: TextIO | None = None) -> None:
+    """Write an :class:`AfiError` to stderr.
+
+    Text mode renders as two lines when a remediation is present::
+
+        error: <message>
+        hint: <remediation>
+
+    The ``hint:`` prefix is required by the agent-first error rubric.
+    """
+    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.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")

tipalti/explain/__init__.py

@@ -0,0 +1,24 @@
+"""Explain catalog — markdown keyed by command-path tuples (stable-contract).
+
+Every noun/verb registered in the CLI should have a catalog entry.
+"""
+
+from __future__ import annotations
+
+from tipalti.cli._errors import EXIT_USER_ERROR, AfiError
+from tipalti.explain.catalog import ENTRIES
+
+
+def resolve(path: tuple[str, ...]) -> str:
+    if path in ENTRIES:
+        return ENTRIES[path]
+    display = " ".join(path) if path else "<root>"
+    raise AfiError(
+        code=EXIT_USER_ERROR,
+        message=f"no explain entry for: {display}",
+        remediation="list known entries with: tipalti explain tipalti",
+    )
+
+
+def known_paths() -> list[tuple[str, ...]]:
+    return list(ENTRIES.keys())

tipalti/explain/catalog.py

@@ -0,0 +1,88 @@
+"""Markdown catalog for ``tipalti explain <path>``.
+
+Each entry is verbatim markdown. Keys are command-path tuples. The empty
+tuple and ``("tipalti",)`` both resolve to the root entry.
+
+Keep bodies self-contained: an agent reading one entry should get enough
+context without chaining reads.
+"""
+
+from __future__ import annotations
+
+_ROOT = """\
+# tipalti
+
+`tipalti` is the command-line interface for Tipalti Solutions. v0.0.1
+ships the agent-first affordances (`learn`, `explain`) and an auth-probe
+stub (`whoami`); domain verbs that exercise the Tipalti API land in later
+releases. The CLI is scaffolded from the AgentCulture sibling pattern.
+
+## Verbs
+
+- `tipalti learn` — structured self-teaching prompt.
+- `tipalti explain <path>` — markdown docs for any noun/verb.
+- `tipalti whoami` — auth probe stub (returns `unauthenticated` for now).
+
+## Exit-code policy
+
+- `0` success
+- `1` user-input error
+- `2` environment / setup error
+- `3+` reserved
+
+## See also
+
+- `tipalti explain learn`
+- `tipalti explain explain`
+- `tipalti explain whoami`
+"""
+
+_LEARN = """\
+# tipalti learn
+
+Prints a structured self-teaching prompt covering tipalti's purpose,
+command map, exit-code policy, `--json` support, and `explain` pointer.
+
+## Usage
+
+    tipalti learn
+    tipalti learn --json
+"""
+
+_EXPLAIN = """\
+# tipalti explain <path>
+
+Prints markdown documentation for any noun/verb path. Unlike `--help`
+(terse, positional), `explain` is global and addressable by path.
+
+## Usage
+
+    tipalti explain tipalti
+    tipalti explain learn
+    tipalti explain --json <path>
+"""
+
+_WHOAMI = """\
+# tipalti whoami
+
+Auth probe. Reports the active Tipalti principal — or
+`unauthenticated` when no credentials are configured.
+
+In v0.0.1 this is a stub: it always reports `unauthenticated` until real
+Tipalti API authentication lands. Exit code is always `0` (probe, not
+gate).
+
+## Usage
+
+    tipalti whoami
+    tipalti whoami --json
+"""
+
+
+ENTRIES: dict[tuple[str, ...], str] = {
+    (): _ROOT,
+    ("tipalti",): _ROOT,
+    ("learn",): _LEARN,
+    ("explain",): _EXPLAIN,
+    ("whoami",): _WHOAMI,
+}

tipalti-0.0.1.dist-info/METADATA

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: tipalti
+Version: 0.0.1
+Summary: Tipalti — CLI for Tipalti Solutions.
+Project-URL: Homepage, https://github.com/agentculture/tipalti
+Project-URL: Issues, https://github.com/agentculture/tipalti/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
+
+# tipalti
+
+CLI for Tipalti Solutions — scaffolded from the AgentCulture sibling pattern.
+
+## Install
+
+```bash
+uv tool install tipalti
+# or
+pipx install tipalti
+```
+
+## Quickstart
+
+```bash
+tipalti --version           # 0.0.1
+tipalti learn               # structured self-teaching prompt for agents
+tipalti learn --json        # machine-readable form
+tipalti explain tipalti     # root markdown doc
+tipalti explain whoami      # docs for the whoami verb
+tipalti whoami              # auth probe (v0.0.1: always "unauthenticated")
+```
+
+## Status
+
+Pre-1.0. v0.0.1 ships only the agent-first affordances (`learn`, `explain`)
+and an auth-probe stub (`whoami`). Domain verbs that exercise the Tipalti
+API land in later releases.
+
+## Development
+
+```bash
+uv sync
+uv run pytest -n auto -v
+uv run tipalti --version
+```
+
+See [`CLAUDE.md`](CLAUDE.md) for the full project shape, conventions, and
+publish flow. The repo follows the AgentCulture sibling pattern — see
+[`agentculture/steward`](https://github.com/agentculture/steward) and
+[`agentculture/afi-cli`](https://github.com/agentculture/afi-cli) for the
+canonical templates.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

tipalti-0.0.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+tipalti/__init__.py,sha256=-H-5b8b8V2Rn7I1E3ZlJze5KLw2yr-Nf8r1F7S2h5Ok,337
+tipalti/__main__.py,sha256=Bl8Q62cwGXpU4pEJiFj06w0B6c0hwsFFxxZLP0eYsqE,172
+tipalti/cli/__init__.py,sha256=CEJpNAtRxtgGL1tDHOmE6yzQ4X2ZTeskX5n4mNVhixk,2653
+tipalti/cli/_errors.py,sha256=q7hKpKRQOFJz7fT-gb6xUQFZJvtHfT7kmZoA7tP15zI,1082
+tipalti/cli/_output.py,sha256=k0qJSqklpjLkyaxQUxnIcengu6zV9pkHlkDMHxl9JEw,1707
+tipalti/cli/_commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tipalti/cli/_commands/explain.py,sha256=9SyHgKlg4mxplWBHFKxVnAP41nT8h4MPKh0-qzoiHJ8,1228
+tipalti/cli/_commands/learn.py,sha256=j3JEi1ZnuhT98ik0Jpk6Z70gZR8piZIhM7gMHpSTCjc,2553
+tipalti/cli/_commands/whoami.py,sha256=yhScSykttCUkJkHOI5-d0EhR_cuin0R3ZPfP--TQJCI,878
+tipalti/explain/__init__.py,sha256=fKs4EXaxOjSxXcu5W5IJWvDj-DGVuY9LPjh3wek_zSU,698
+tipalti/explain/catalog.py,sha256=szniTmRNqGqJBdXMF3-VfYzaVsCEKplTjtKjrRS3BMI,2086
+tipalti-0.0.1.dist-info/METADATA,sha256=m2HKSLYwrJZJr8Trtyzykwfv1PTUpbLYg-o-oX8h0b8,1764
+tipalti-0.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+tipalti-0.0.1.dist-info/entry_points.txt,sha256=0m3thyJ9MSyzfW-42hHKXEO6s4etTBgyf4NmSSM5vyg,45
+tipalti-0.0.1.dist-info/licenses/LICENSE,sha256=d-o3g1Varo3ruZBbZUlkdoDVJBoIhutjarID0c0OIyU,1069
+tipalti-0.0.1.dist-info/RECORD,,

tipalti-0.0.1.dist-info/WHEEL

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

tipalti-0.0.1.dist-info/entry_points.txt

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

tipalti-0.0.1.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.