antoine-cli 0.9.1__py3-none-any.whl

antoine/__init__.py

@@ -0,0 +1,35 @@
+"""antoine — 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 ``antoine`` package.
+
+    The same source ships under multiple PyPI distribution names
+    (``antoine-cli``, ``kata-cli``, ``code-lens-cli``) per the lean
+    dual-publish slice of issue #17. Look up which distribution provides
+    the ``antoine`` 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("antoine") or []:
+        try:
+            return _v(dist)
+        except PackageNotFoundError:
+            continue
+    for fallback in ("antoine-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__"]

antoine/__main__.py

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

antoine/cli/__init__.py

@@ -0,0 +1,117 @@
+"""Unified CLI entry point for antoine.
+
+Error-propagation contract: every handler raises
+:class:`antoine.cli._errors.AntoineError` on failure; ``main()`` catches it via
+:func:`_dispatch` and routes through :mod:`antoine.cli._output`. Unknown
+exceptions are wrapped into a ``AntoineError`` so no Python traceback leaks.
+
+Argparse errors (unknown verb, missing required arg) also route through the
+structured format — :class:`_AntoineArgumentParser` overrides ``.error()``.
+Whether errors render as text or JSON depends on whether ``--json`` appears in
+the raw argv (:func:`main` sets ``_AntoineArgumentParser._json_hint`` before
+``parse_args``).
+"""
+
+# pylint: disable=duplicate-code  # _dispatch mirrors antoine.repo.__main__ by design
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from antoine import __version__
+from antoine.cli._errors import EXIT_USER_ERROR, AntoineError
+from antoine.cli._output import emit_error
+
+
+class _AntoineArgumentParser(argparse.ArgumentParser):
+    """ArgumentParser that routes errors through :func:`emit_error`."""
+
+    _json_hint: bool = False
+
+    def error(self, message: str) -> None:  # type: ignore[override]
+        err = AntoineError(
+            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 = _AntoineArgumentParser(
+        prog="antoine",
+        description="antoine — 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=_AntoineArgumentParser)
+
+    # pylint: disable=import-outside-toplevel
+    from antoine.cli._commands import classify as _classify_cmd
+    from antoine.cli._commands import explain as _explain_cmd
+    from antoine.cli._commands import grep as _grep_cmd
+    from antoine.cli._commands import learn as _learn_cmd
+    from antoine.cli._commands import recent as _recent_cmd
+    from antoine.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:`AntoineError`;
+    any other exception is wrapped so no Python traceback leaks.
+    """
+    json_mode = bool(getattr(args, "json", False))
+    try:
+        rc = args.func(args)
+    except AntoineError as err:
+        emit_error(err, json_mode=json_mode)
+        return err.code
+    except Exception as err:  # noqa: BLE001  # pylint: disable=broad-exception-caught
+        wrapped = AntoineError(
+            code=EXIT_USER_ERROR,
+            message=f"unexpected: {err.__class__.__name__}: {err}",
+            remediation="file a bug at https://github.com/agentculture/antoine/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."""
+    _AntoineArgumentParser._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())

antoine/cli/_commands/__init__.py

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

antoine/cli/_commands/classify.py

@@ -0,0 +1,40 @@
+"""``antoine 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 antoine.cli._output import emit_result
+from antoine.lookup.classify import classify
+from antoine.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)

antoine/cli/_commands/explain.py

@@ -0,0 +1,44 @@
+"""``antoine explain`` — placeholder verb.
+
+See :mod:`antoine.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 antoine import __version__
+from antoine.cli._output import emit_result
+
+_TEXT = "antoine explain — not yet implemented; antoine is greenfield. See CLAUDE.md."
+
+
+def _json_payload() -> dict[str, object]:
+    return {
+        "tool": "antoine",
+        "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 antoine topic or command (stub).")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_explain)

antoine/cli/_commands/grep.py

@@ -0,0 +1,44 @@
+"""``antoine 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 antoine.cli._output import emit_result
+from antoine.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)

antoine/cli/_commands/learn.py

@@ -0,0 +1,49 @@
+"""``antoine learn`` — placeholder verb.
+
+antoine 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 antoine import __version__
+from antoine.cli._output import emit_result
+
+_TEXT = (
+    "antoine — codebase lookup and indexing for agent skills. Not yet implemented; "
+    "antoine is a greenfield AgentCulture sibling. See CLAUDE.md."
+)
+
+
+def _json_payload() -> dict[str, object]:
+    return {
+        "tool": "antoine",
+        "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 antoine's self-teaching status line.")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_learn)

antoine/cli/_commands/recent.py

@@ -0,0 +1,52 @@
+"""``antoine 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 antoine.cli._output import emit_result
+from antoine.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)

antoine/cli/_commands/whoami.py

@@ -0,0 +1,42 @@
+"""``antoine whoami`` — placeholder verb.
+
+See :mod:`antoine.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 antoine import __version__
+from antoine.cli._output import emit_result
+
+_TEXT = "antoine — not yet implemented; antoine is greenfield. See CLAUDE.md."
+
+
+def _json_payload() -> dict[str, object]:
+    return {
+        "tool": "antoine",
+        "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 antoine's identity probe (stub).")
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_whoami)

antoine/cli/_errors.py

@@ -0,0 +1,59 @@
+"""AntoineError and exit-code policy.
+
+Every failure inside antoine raises :class:`AntoineError`. The top-level
+``main()`` catches it, formats via :mod:`antoine.cli._output`, and exits with
+:attr:`AntoineError.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 AntoineError(Exception):
+    """Structured error raised within antoine.
+
+    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:`antoine.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

antoine/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 antoine 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 antoine.cli._errors import AntoineError
+
+
+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: AntoineError, *, json_mode: bool, stream: TextIO | None = None) -> None:
+    """Write a :class:`AntoineError` 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")

antoine/lookup/__init__.py

@@ -0,0 +1,25 @@
+"""antoine.lookup — codebase classification + lookup verbs.
+
+This package is the sibling of `antoine.repo`: it answers "what kind of project
+is this?" / "where is X?" rather than "tell me about this repo."
+"""
+
+from __future__ import annotations
+
+from antoine.lookup.ast_scope import Scope, find_enclosing, list_symbols
+from antoine.lookup.classify import classify
+from antoine.lookup.grep_context import grep_with_context, render_grep_markdown
+from antoine.lookup.recent_outline import recent_with_outline, render_recent_markdown
+from antoine.lookup.render import render_classify_markdown
+
+__all__ = [
+    "classify",
+    "find_enclosing",
+    "grep_with_context",
+    "list_symbols",
+    "recent_with_outline",
+    "render_classify_markdown",
+    "render_grep_markdown",
+    "render_recent_markdown",
+    "Scope",
+]

antoine/lookup/ast_scope.py

@@ -0,0 +1,74 @@
+"""antoine.lookup.ast_scope — AST-based scope resolver (stdlib ast only).
+
+Provides:
+  Scope          — frozen dataclass describing a named code scope.
+  list_symbols   — collect all module-level + class-method scopes.
+  find_enclosing — smallest scope whose line range contains a given line.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+
+__all__ = ["Scope", "list_symbols", "find_enclosing"]
+
+
+@dataclass(frozen=True)
+class Scope:
+    kind: str  # "function" | "async_function" | "class"
+    name: str  # qualified, e.g. "Foo.method_a"
+    start_line: int
+    end_line: int
+
+
+def _scope_kind(node: ast.AST) -> str | None:
+    """Return the scope kind string for *node*, or ``None`` if not a named scope."""
+    if isinstance(node, ast.AsyncFunctionDef):
+        return "async_function"
+    if isinstance(node, ast.ClassDef):
+        return "class"
+    if isinstance(node, ast.FunctionDef):
+        return "function"
+    return None
+
+
+def list_symbols(tree: ast.AST) -> list[Scope]:
+    """Walk *tree* and return one :class:`Scope` per named scope.
+
+    Covers:
+    - Module-level functions, async functions, and classes.
+    - Methods defined directly inside a class (one level of nesting per
+      class, but classes inside classes recurse so ``Outer.Inner.method``
+      is emitted correctly).
+
+    Does **not** recurse into function bodies.
+    """
+    out: list[Scope] = []
+
+    def visit(node: ast.AST, prefix: str = "") -> None:
+        for child in ast.iter_child_nodes(node):
+            kind = _scope_kind(child)
+            if kind is None:
+                continue
+            name = f"{prefix}{child.name}"  # type: ignore[attr-defined]
+            end = child.end_lineno or child.lineno  # type: ignore[attr-defined]
+            start = child.lineno  # type: ignore[attr-defined]
+            out.append(Scope(kind=kind, name=name, start_line=start, end_line=end))
+            if isinstance(child, ast.ClassDef):
+                visit(child, prefix=f"{name}.")
+
+    visit(tree)
+    return out
+
+
+def find_enclosing(tree: ast.AST, line: int) -> Scope | None:
+    """Return the smallest :class:`Scope` whose ``[start_line, end_line]``
+    contains *line*, or ``None`` for module-level lines.
+    """
+    best: Scope | None = None
+    for s in list_symbols(tree):
+        if s.start_line <= line <= s.end_line:
+            if best is None or (s.end_line - s.start_line) < (best.end_line - best.start_line):
+                best = s
+    return best