odoo-agent-cli 0.2.0__py3-none-any.whl

odoocli/cli/app.py

@@ -0,0 +1,337 @@
+"""Typer application: global options, session, run/emit helpers, exit code mapping."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+import os
+import sys
+from collections.abc import Awaitable, Callable, Iterator, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, TypeVar
+
+import typer
+from typer.core import TyperGroup
+
+from odoocli._version import __version__
+from odoocli.cli.output import FORMATS, detect_format, render
+from odoocli.client import AsyncOdooClient
+from odoocli.config import ENV_ASSUME_YES, Profile, config_path, env_flag, resolve_profile
+from odoocli.errors import OdooError, OdooRefusedError
+from odoocli.security import is_sensitive_model, redact
+
+T = TypeVar("T")
+
+# Root options that may appear anywhere on the command line. Agents naturally
+# write ``odoo search res.partner --format jsonl``; click only accepts group
+# options before the subcommand, so we hoist them.
+_GLOBAL_WITH_VALUE = {
+    "--profile",
+    "-p",
+    "--format",
+    "-f",
+    "--timeout",
+    "--context",
+    "--company",
+    "--lang",
+}
+_GLOBAL_FLAGS = {
+    "--no-redact",
+    "--include-sensitive",
+    "--include-archived",
+    "--insecure",
+    "--verbose",
+    "--debug",
+    "--version",
+}
+
+
+def hoist_global_options(args: list[str]) -> list[str]:
+    """Move root options found after the subcommand to the front, keeping order."""
+    hoisted: list[str] = []
+    rest: list[str] = []
+    i = 0
+    while i < len(args):
+        tok = args[i]
+        if tok == "--":
+            rest.extend(args[i:])
+            break
+        name, eq, _value = tok.partition("=")
+        if tok in _GLOBAL_FLAGS:
+            hoisted.append(tok)
+        elif tok in _GLOBAL_WITH_VALUE and i + 1 < len(args):
+            hoisted.extend(args[i : i + 2])
+            i += 1
+        elif eq and name in _GLOBAL_WITH_VALUE:
+            hoisted.append(tok)
+        else:
+            rest.append(tok)
+        i += 1
+    return hoisted + rest
+
+
+class _RootGroup(TyperGroup):
+    def parse_args(self, ctx: Any, args: list[str]) -> list[str]:
+        return super().parse_args(ctx, hoist_global_options(args))
+
+
+app = typer.Typer(
+    name="odoo",
+    cls=_RootGroup,
+    help=(
+        "Odoo JSON-RPC CLI for AI agents and scripts.\n\n"
+        "stdout carries only data: raw Odoo JSON when piped, a table on a terminal. "
+        "Errors, warnings and write logs are single JSON lines on stderr. "
+        "Exit codes: 0 ok, 1 Odoo error, 2 usage, 3 connection/auth, 4 refused by a guard.\n\n"
+        "New here? Run: odoo agent-guide"
+    ),
+    no_args_is_help=True,
+    add_completion=False,
+    rich_markup_mode=None,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+@dataclass
+class Session:
+    profile_name: str | None
+    fmt: str | None
+    redact: bool
+    include_sensitive: bool
+    timeout: float
+    verbose: bool
+    assume_yes: bool
+    context: dict[str, Any] = field(default_factory=dict)
+    verify_ssl: bool = True
+    debug: bool = False
+    env: Mapping[str, str] = field(default_factory=lambda: dict(os.environ))
+    config: Path = field(default_factory=lambda: config_path(os.environ))
+
+    def profile(self) -> Profile:
+        return resolve_profile(self.profile_name, self.env, self.config)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"odoo {__version__} (odoo-agent-cli)")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    ctx: typer.Context,
+    profile: str | None = typer.Option(
+        None,
+        "--profile",
+        "-p",
+        help="Profile name (see 'odoo profile'). Beats ODOO_PROFILE and ODOO_* env.",
+    ),
+    fmt: str | None = typer.Option(
+        None,
+        "--format",
+        "-f",
+        help="json | jsonl | table | csv. Default: table on a TTY, json otherwise.",
+    ),
+    no_redact: bool = typer.Option(
+        False, "--no-redact", help="Do not mask password/api_key/secret field values."
+    ),
+    include_sensitive: bool = typer.Option(
+        False,
+        "--include-sensitive",
+        help="Allow sensitive models (ir.config_parameter, ir.mail_server, ir.cron, ...).",
+    ),
+    timeout: float = typer.Option(30.0, "--timeout", help="Seconds per RPC call."),
+    verbose: bool = typer.Option(
+        False, "--verbose", help="Include the Odoo debug payload in errors."
+    ),
+    context: str | None = typer.Option(
+        None,
+        "--context",
+        help='Odoo context as JSON, e.g. \'{"lang": "fr_BE"}\'. Merged into every call.',
+    ),
+    include_archived: bool = typer.Option(
+        False, "--include-archived", help="Also match archived records (context active_test=false)."
+    ),
+    company: int | None = typer.Option(
+        None, "--company", help="Company id to operate in (context allowed_company_ids)."
+    ),
+    lang: str | None = typer.Option(None, "--lang", help="Language code for labels, e.g. fr_BE."),
+    insecure: bool = typer.Option(
+        False, "--insecure", help="Skip TLS certificate verification (self-signed on-prem)."
+    ),
+    debug: bool = typer.Option(
+        False,
+        "--debug",
+        help="Log every RPC call (method, id, duration, retries) as JSON on stderr.",
+    ),
+    _version: bool = typer.Option(
+        False, "--version", callback=_version_callback, is_eager=True, help="Print version."
+    ),
+) -> None:
+    if fmt is not None and fmt not in FORMATS:
+        raise typer.BadParameter(f"--format must be one of {', '.join(FORMATS)}")
+    ctx.obj = Session(
+        profile_name=profile,
+        fmt=fmt,
+        redact=not no_redact,
+        include_sensitive=include_sensitive,
+        timeout=timeout,
+        verbose=verbose,
+        assume_yes=env_flag(os.environ, ENV_ASSUME_YES),
+        context=build_context(context, include_archived, company, lang),
+        verify_ssl=not insecure,
+        debug=debug,
+    )
+
+
+def build_context(
+    context_json: str | None, include_archived: bool, company: int | None, lang: str | None
+) -> dict[str, Any]:
+    """Compose the Odoo context from the convenience flags; explicit JSON keys come first."""
+    ctx: dict[str, Any] = {}
+    if context_json:
+        try:
+            parsed = json.loads(context_json)
+        except ValueError as e:
+            raise typer.BadParameter(f"--context must be a JSON object: {e}") from e
+        if not isinstance(parsed, dict):
+            raise typer.BadParameter("--context must be a JSON object")
+        ctx.update(parsed)
+    if lang:
+        ctx["lang"] = lang
+    if company is not None:
+        ctx["allowed_company_ids"] = [company]
+    if include_archived:
+        ctx["active_test"] = False
+    return ctx
+
+
+class _JsonLineFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        return json.dumps(
+            {
+                "log": {
+                    "level": record.levelname,
+                    "logger": record.name,
+                    "message": record.getMessage(),
+                }
+            },
+            ensure_ascii=False,
+        )
+
+
+@contextlib.contextmanager
+def debug_logging(enabled: bool) -> Iterator[None]:
+    """Attach a JSON-lines stderr handler to the ``odoocli`` logger for one command."""
+    if not enabled:
+        yield
+        return
+    root = logging.getLogger("odoocli")
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(_JsonLineFormatter())
+    previous_level = root.level
+    root.addHandler(handler)
+    root.setLevel(logging.DEBUG)
+    try:
+        yield
+    finally:
+        root.removeHandler(handler)
+        root.setLevel(previous_level)
+        handler.flush()
+
+
+def session(ctx: typer.Context) -> Session:
+    obj = ctx.obj
+    assert isinstance(obj, Session)
+    return obj
+
+
+def warn(payload: dict[str, Any]) -> None:
+    """One JSON line on stderr (warnings, write logs)."""
+    sys.stderr.write(json.dumps(payload, ensure_ascii=False) + "\n")
+    sys.stderr.flush()
+
+
+def fail(err: OdooError, verbose: bool) -> None:
+    body = err.to_dict()
+    if verbose and err.data:
+        body["debug"] = err.data.get("debug")
+    warn({"error": body})
+    raise typer.Exit(err.exit_code)
+
+
+def check_model(sess: Session, profile: Profile, model: str) -> None:
+    if is_sensitive_model(model) and not (sess.include_sensitive or profile.allow_sensitive):
+        raise OdooRefusedError(
+            f"Model {model!r} is sensitive (secrets or code execution). "
+            "Pass --include-sensitive or set allow_sensitive = true on the profile.",
+            code="sensitive_model",
+        )
+
+
+def require_writes(profile: Profile) -> None:
+    if not profile.allow_writes:
+        raise OdooRefusedError(
+            f"Writes are disabled for {profile.source}. Set allow_writes = true on the profile "
+            "or ODOO_ALLOW_WRITES=1 in the environment.",
+            code="writes_disabled",
+        )
+
+
+def require_yes(sess: Session, yes: bool, what: str) -> None:
+    if not (yes or sess.assume_yes):
+        raise OdooRefusedError(
+            f"{what} needs explicit confirmation: pass --yes (or ODOO_ASSUME_YES=1).",
+            code="confirmation_required",
+        )
+
+
+def run(ctx: typer.Context, fn: Callable[[AsyncOdooClient, Profile], Awaitable[T]]) -> T:
+    """Resolve the profile, open a client, run ``fn``, map errors to exit codes.
+
+    Argument parsing that can raise ``OdooUsageError`` belongs inside ``fn`` so
+    it is mapped to exit code 2 like every other ``OdooError``.
+    """
+    sess = session(ctx)
+
+    async def _go() -> T:
+        profile = sess.profile()
+        async with AsyncOdooClient(
+            profile.url,
+            profile.database,
+            profile.login,
+            profile.api_key,
+            timeout=sess.timeout,
+            verify_ssl=sess.verify_ssl and profile.verify_ssl,
+            context=sess.context,
+        ) as client:
+            return await fn(client, profile)
+
+    try:
+        with debug_logging(sess.debug):
+            return asyncio.run(_go())
+    except OdooError as e:
+        fail(e, sess.verbose)
+        raise AssertionError("unreachable") from e
+
+
+def emit(ctx: typer.Context, data: Any, *, table_rows: list[dict[str, Any]] | None = None) -> None:
+    sess = session(ctx)
+    if sess.redact:
+        data = redact(data)
+        table_rows = redact(table_rows) if table_rows is not None else None
+    fmt = detect_format(sess.fmt, sys.stdout.isatty())
+    text = render(data, fmt, table_rows=table_rows)
+    if text:
+        typer.echo(text)
+
+
+def main() -> None:
+    app()
+
+
+# Command modules register themselves on ``app``; imported last to avoid cycles.
+from odoocli.cli import guide_cmd, profile_cmds, read_cmds, write_cmds  # noqa: E402,F401

odoocli/cli/guide_cmd.py

@@ -0,0 +1,19 @@
+"""odoo agent-guide: print the packaged guide written for AI agents."""
+
+from __future__ import annotations
+
+from importlib import resources
+
+import typer
+
+from odoocli.cli.app import app
+
+
+def guide_text() -> str:
+    return resources.files("odoocli").joinpath("AGENT_GUIDE.md").read_text(encoding="utf-8")
+
+
+@app.command("agent-guide")
+def agent_guide() -> None:
+    """Print the usage guide written for AI agents (conventions, pitfalls, recipes)."""
+    typer.echo(guide_text())

odoocli/cli/output.py

@@ -0,0 +1,105 @@
+"""Render data for stdout. json is the source of truth; table and csv are for humans."""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+from typing import Any
+
+from rich.console import Console
+from rich.table import Table
+
+FORMATS = ("json", "jsonl", "table", "csv")
+_MAX_CELL = 60
+
+
+def detect_format(explicit: str | None, isatty: bool) -> str:
+    if explicit:
+        return explicit
+    return "table" if isatty else "json"
+
+
+def _is_m2o(value: Any) -> bool:
+    return (
+        isinstance(value, list)
+        and len(value) == 2
+        and isinstance(value[0], int)
+        and isinstance(value[1], str)
+    )
+
+
+def _cell(value: Any) -> str:
+    if value is False or value is None:
+        return ""
+    if _is_m2o(value):
+        return f"{value[1]} (#{value[0]})"
+    text = json.dumps(value, ensure_ascii=False) if isinstance(value, list | dict) else str(value)
+    return text if len(text) <= _MAX_CELL else text[: _MAX_CELL - 3] + "..."
+
+
+def _columns(rows: list[dict[str, Any]]) -> list[str]:
+    cols: list[str] = []
+    for row in rows:
+        for key in row:
+            if key not in cols:
+                cols.append(key)
+    if "id" in cols:
+        cols.remove("id")
+        cols.insert(0, "id")
+    return cols
+
+
+def _as_rows(data: Any, table_rows: list[dict[str, Any]] | None) -> list[dict[str, Any]] | None:
+    if table_rows is not None:
+        return table_rows
+    if isinstance(data, list) and all(isinstance(r, dict) for r in data):
+        return data
+    if isinstance(data, dict):
+        return [data]
+    return None
+
+
+def _table(rows: list[dict[str, Any]]) -> str:
+    cols = _columns(rows)
+    table = Table(show_lines=False, header_style="bold")
+    for col in cols:
+        table.add_column(col)
+    for row in rows:
+        table.add_row(*(_cell(row.get(c)) for c in cols))
+    buf = io.StringIO()
+    console = Console(file=buf, width=200, force_terminal=False, color_system=None)
+    console.print(table)
+    return buf.getvalue().rstrip("\n")
+
+
+def _csv(rows: list[dict[str, Any]]) -> str:
+    cols = _columns(rows)
+    buf = io.StringIO()
+    writer = csv.DictWriter(buf, fieldnames=cols, lineterminator="\n")
+    writer.writeheader()
+    for row in rows:
+        writer.writerow(
+            {
+                c: (json.dumps(v, ensure_ascii=False) if isinstance(v, list | dict) else v)
+                for c, v in row.items()
+                if c in cols
+            }
+        )
+    return buf.getvalue().rstrip("\n")
+
+
+def render(data: Any, fmt: str, *, table_rows: list[dict[str, Any]] | None = None) -> str:
+    """Return the text to print for ``data`` in ``fmt``. Empty string means print nothing."""
+    if fmt == "json":
+        return json.dumps(data, ensure_ascii=False, indent=2)
+    if fmt == "jsonl":
+        items = data if isinstance(data, list) else [data]
+        return "\n".join(json.dumps(i, ensure_ascii=False) for i in items)
+    rows = _as_rows(data, table_rows)
+    if rows is None:
+        # Scalars and unknown shapes: fall back to compact JSON.
+        return json.dumps(data, ensure_ascii=False)
+    if not rows:
+        return ""
+    return _table(rows) if fmt == "table" else _csv(rows)

odoocli/cli/profile_cmds.py

@@ -0,0 +1,116 @@
+"""odoo profile add | list | test | remove | path"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+
+from odoocli.cli.app import app, emit, fail, session
+from odoocli.cli.read_cmds import info
+from odoocli.config import load_profiles, remove_profile, save_profile
+from odoocli.errors import OdooConnectionError
+
+profile_app = typer.Typer(
+    help="Manage named connections stored in the config file (mode 0600).",
+    no_args_is_help=True,
+    rich_markup_mode=None,
+)
+app.add_typer(profile_app, name="profile")
+
+
+@profile_app.command("add")
+def profile_add(
+    ctx: typer.Context,
+    name: str = typer.Argument(...),
+    url: str = typer.Option(..., "--url", help="https://your-odoo.example.com"),
+    db: str = typer.Option(..., "--db", help="Database name"),
+    login: str = typer.Option(..., "--login", help="User login (email)"),
+    api_key: str | None = typer.Option(
+        None, "--api-key", help="API key or password, stored in the file."
+    ),
+    api_key_env: str | None = typer.Option(
+        None, "--api-key-env", help="Name of an env var holding the key (nothing stored)."
+    ),
+    allow_writes: bool = typer.Option(
+        False, "--allow-writes", help="Enable create/write/unlink/call on this profile."
+    ),
+    allow_sensitive: bool = typer.Option(
+        False, "--allow-sensitive", help="Allow sensitive models on this profile."
+    ),
+    no_verify_ssl: bool = typer.Option(
+        False, "--no-verify-ssl", help="Skip TLS verification (self-signed on-prem)."
+    ),
+    test: bool = typer.Option(False, "--test", help="Run 'odoo info' with the new profile."),
+) -> None:
+    """Add or replace a profile."""
+    if bool(api_key) == bool(api_key_env):
+        raise typer.BadParameter("Give exactly one of --api-key or --api-key-env")
+    sess = session(ctx)
+    save_profile(
+        sess.config,
+        name,
+        {
+            "url": url.rstrip("/"),
+            "database": db,
+            "login": login,
+            "api_key": api_key,
+            "api_key_env": api_key_env,
+            "allow_writes": allow_writes,
+            "allow_sensitive": allow_sensitive,
+            "verify_ssl": False if no_verify_ssl else None,
+        },
+    )
+    if test:
+        sess.profile_name = name
+        info(ctx, modules=False)
+
+
+@profile_app.command("list")
+def profile_list(ctx: typer.Context) -> None:
+    """List profiles. Keys are never printed."""
+    sess = session(ctx)
+    rows: list[dict[str, Any]] = []
+    for name, data in load_profiles(sess.config).items():
+        key = "***" if data.get("api_key") else f"${data.get('api_key_env', '')}"
+        rows.append(
+            {
+                "name": name,
+                "url": data.get("url"),
+                "database": data.get("database"),
+                "login": data.get("login"),
+                "key": key,
+                "allow_writes": bool(data.get("allow_writes", False)),
+                "allow_sensitive": bool(data.get("allow_sensitive", False)),
+                "verify_ssl": bool(data.get("verify_ssl", True)),
+            }
+        )
+    emit(ctx, rows)
+
+
+@profile_app.command("test")
+def profile_test(ctx: typer.Context, name: str | None = typer.Argument(None)) -> None:
+    """Authenticate with a profile (default: the one that would be used) and print server info."""
+    sess = session(ctx)
+    if name:
+        sess.profile_name = name
+    info(ctx, modules=False)
+
+
+@profile_app.command("remove")
+def profile_remove(ctx: typer.Context, name: str = typer.Argument(...)) -> None:
+    """Delete a profile."""
+    sess = session(ctx)
+    if not remove_profile(sess.config, name):
+        fail(
+            OdooConnectionError(
+                f"Profile {name!r} not found in {sess.config}", code="no_connection"
+            ),
+            False,
+        )
+
+
+@profile_app.command("path")
+def profile_path(ctx: typer.Context) -> None:
+    """Print the config file path."""
+    typer.echo(str(session(ctx).config))