keboola-cli 0.63.4__py3-none-any.whl

keboola_agent_cli/commands/repl.py

@@ -0,0 +1,243 @@
+"""Interactive REPL mode for kbagent.
+
+Provides a prompt-toolkit based interactive shell where users and agents
+can run kbagent commands without restarting the process. Supports tab
+completion, persistent history, and colored output.
+"""
+
+import contextlib
+import os
+import shlex
+import sys
+from pathlib import Path
+from typing import TypeGuard
+
+import click
+import platformdirs
+import typer
+from prompt_toolkit import PromptSession
+from prompt_toolkit.completion import Completer, Completion
+from prompt_toolkit.formatted_text import HTML
+from prompt_toolkit.history import FileHistory
+
+from .. import __version__
+from ._helpers import get_formatter
+
+
+def _is_group(cmd: object) -> TypeGuard[click.Group]:
+    """True if ``cmd`` is a command group (duck-typed; Typer >=0.25 vendors Click)."""
+    return callable(getattr(cmd, "list_commands", None))
+
+
+def _build_command_tree(click_group: click.Group, prefix: str = "") -> dict:
+    """Walk Typer/Click command tree and return a dict of command paths to help strings."""
+    tree: dict[str, str] = {}
+    try:
+        with click.Context(click_group) as ctx:
+            for name in click_group.list_commands(ctx):
+                cmd = click_group.get_command(ctx, name)
+                if cmd is None:
+                    continue
+                full_name = f"{prefix}{name}"
+                help_text = cmd.get_short_help_str(limit=80)
+                tree[full_name] = help_text
+                if _is_group(cmd):
+                    tree.update(_build_command_tree(cmd, f"{full_name} "))
+    except Exception as exc:
+        # Report rather than degrade silently to an empty tree.
+        sys.stderr.write(f"kbagent: failed to build REPL command tree: {exc!r}\n")
+    return tree
+
+
+class KbagentCompleter(Completer):
+    """Tab-completion for kbagent commands inside the REPL."""
+
+    def __init__(self, command_tree: dict[str, str]) -> None:
+        self._commands = command_tree
+
+    def get_completions(self, document, complete_event):
+        text = document.text_before_cursor.strip()
+        for cmd, help_text in sorted(self._commands.items()):
+            if cmd.startswith(text):
+                # Yield the remaining part after what's already typed
+                suffix = cmd[len(text) :]
+                yield Completion(
+                    suffix,
+                    start_position=0,
+                    display=cmd,
+                    display_meta=help_text,
+                )
+
+
+def _get_history_path() -> Path:
+    """Return path for persistent REPL history file.
+
+    Ensures the file exists with 0600 permissions before returning so
+    ``prompt_toolkit.FileHistory`` does not create it world-readable
+    under a permissive umask. REPL command lines may include
+    ``project add --token TOKEN``, so the history must not leak to
+    group/other (issue #269 sec-04).
+    """
+    config_dir = Path(platformdirs.user_config_dir("keboola-agent-cli"))
+    config_dir.mkdir(parents=True, exist_ok=True)
+    history_path = config_dir / "repl_history"
+    if not history_path.exists():
+        # Atomic create with 0600 so FileHistory.append never widens perms.
+        fd = os.open(str(history_path), os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        os.close(fd)
+    else:
+        # Pre-existing file might have been created by an older kbagent
+        # under a permissive umask -- tighten perms in place. Filesystems
+        # that do not support chmod (e.g. some network mounts) silently no-op.
+        with contextlib.suppress(OSError):
+            history_path.chmod(0o600)
+    return history_path
+
+
+def _run_repl(
+    json_mode: bool,
+    verbose: bool,
+    no_color: bool,
+    config_dir: str | None,
+    deny_writes: bool = False,
+    deny_destructive: bool = False,
+    allow_env_manage_token: bool = False,
+) -> None:
+    """Main REPL loop.
+
+    Global flags from the outer invocation are re-applied on every command
+    executed inside the REPL. This includes the session-only firewall flags
+    ``--deny-writes`` / ``--deny-destructive`` -- dropping them here would
+    silently elevate the REPL above the policy the user started it with --
+    and ``--allow-env-manage-token``, which would otherwise force re-prompts
+    on every nested ``org setup`` / ``project refresh`` / ``data-app
+    password`` even after the user opted in at the outer invocation.
+    """
+    from ..cli import app as typer_app
+
+    # Build command tree for completion
+    click_app = typer.main.get_command(typer_app)
+    command_tree = _build_command_tree(click_app) if _is_group(click_app) else {}
+
+    # Add REPL-specific commands
+    command_tree["help"] = "Show available commands"
+    command_tree["exit"] = "Exit the REPL"
+    command_tree["quit"] = "Exit the REPL"
+
+    completer = KbagentCompleter(command_tree)
+    history = FileHistory(str(_get_history_path()))
+
+    session: PromptSession = PromptSession(
+        history=history,
+        completer=completer,
+        complete_while_typing=False,
+    )
+
+    prompt_text = HTML("<ansiblue><b>kbagent</b></ansiblue><ansigray> &gt; </ansigray>")
+
+    # Show banner
+    sys.stderr.write(f"\nkbagent v{__version__} -- interactive mode\n")
+    sys.stderr.write("Type 'help' for commands, 'exit' to quit.\n")
+    sys.stderr.write(f"Global flags: --json={json_mode}, --verbose={verbose}\n")
+    if deny_writes or deny_destructive:
+        active = []
+        if deny_writes:
+            active.append("--deny-writes")
+        if deny_destructive:
+            active.append("--deny-destructive")
+        sys.stderr.write(f"Session firewall: {' '.join(active)} (active for all commands)\n")
+    sys.stderr.write("\n")
+
+    while True:
+        try:
+            line = session.prompt(prompt_text).strip()
+        except (EOFError, KeyboardInterrupt):
+            sys.stderr.write("\n")
+            break
+
+        if not line:
+            continue
+
+        if line in ("exit", "quit", "q"):
+            break
+
+        if line == "help":
+            # Print command tree
+            sys.stderr.write("\nAvailable commands:\n")
+            # Show only top-level and second-level commands
+            shown = set()
+            for cmd, help_text in sorted(command_tree.items()):
+                parts = cmd.split()
+                if len(parts) <= 2 and cmd not in ("help", "exit", "quit"):
+                    sys.stderr.write(f"  {cmd:<35} {help_text}\n")
+                    shown.add(cmd)
+            sys.stderr.write(f"\n  {'help':<35} Show this help\n")
+            sys.stderr.write(f"  {'exit':<35} Exit the REPL\n")
+            sys.stderr.write("\n")
+            continue
+
+        # Parse the input line into argv
+        try:
+            argv = shlex.split(line)
+        except ValueError as exc:
+            sys.stderr.write(f"Parse error: {exc}\n")
+            continue
+
+        # Build full argv with global flags
+        full_argv = []
+        if json_mode and "--json" not in argv and "-j" not in argv:
+            full_argv.append("--json")
+        if verbose and "--verbose" not in argv and "-v" not in argv:
+            full_argv.append("--verbose")
+        if no_color and "--no-color" not in argv:
+            full_argv.append("--no-color")
+        if config_dir and "--config-dir" not in argv:
+            full_argv.extend(["--config-dir", config_dir])
+        # Session firewall flags: re-applied on every REPL invocation so the
+        # user's opt-in policy survives across prompts. Forgetting to forward
+        # these would silently restore write/destructive access inside the REPL.
+        if deny_writes and "--deny-writes" not in argv:
+            full_argv.append("--deny-writes")
+        if deny_destructive and "--deny-destructive" not in argv:
+            full_argv.append("--deny-destructive")
+        if allow_env_manage_token and "--allow-env-manage-token" not in argv:
+            full_argv.append("--allow-env-manage-token")
+        full_argv.extend(argv)
+
+        # Prevent recursive REPL
+        if full_argv and full_argv[-1] == "repl":
+            sys.stderr.write("Already in REPL mode.\n")
+            continue
+
+        # Execute the command via Typer
+        try:
+            click_app = typer.main.get_command(typer_app)
+            click_app(full_argv, standalone_mode=False)
+        except SystemExit:
+            pass  # Typer/Click raises SystemExit on --help or errors
+        except Exception as exc:
+            sys.stderr.write(f"Error: {exc}\n")
+
+
+def repl_command(ctx: typer.Context) -> None:
+    """Start interactive REPL mode for kbagent."""
+    formatter = get_formatter(ctx)
+
+    if formatter.json_mode:
+        # In JSON mode, REPL doesn't make sense -- output instructions
+        formatter.output(
+            {
+                "message": "REPL mode is for interactive use. Run 'kbagent repl' without --json.",
+            }
+        )
+        return
+
+    _run_repl(
+        json_mode=ctx.obj.get("json_output", False),
+        verbose=ctx.obj.get("verbose", False),
+        no_color=ctx.obj.get("no_color", False),
+        config_dir=None,  # Already resolved in ctx
+        deny_writes=ctx.obj.get("deny_writes", False),
+        deny_destructive=ctx.obj.get("deny_destructive", False),
+        allow_env_manage_token=ctx.obj.get("allow_env_manage_token", False),
+    )

keboola_agent_cli/commands/schedule.py

@@ -0,0 +1,340 @@
+"""Schedule discovery and audit commands.
+
+Thin CLI layer over :class:`ScheduleService`. Three subcommands:
+
+- ``schedule list`` — fleet-wide listing of ``keboola.scheduler`` configs.
+- ``schedule detail`` — single-schedule detail plus parent metadata.
+- ``schedule find`` — audit filters (cron-window, not-run-since).
+
+All three are read-only and safe under ``--deny-writes``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import typer
+from rich.markup import escape
+from rich.table import Table
+
+from ..errors import ConfigError, ErrorCode, KeboolaApiError
+from ._helpers import (
+    check_cli_permission,
+    get_formatter,
+    get_service,
+    map_error_to_exit_code,
+    resolve_branch,
+)
+
+logger = logging.getLogger(__name__)
+
+schedule_app = typer.Typer(
+    help="Discover and audit cron schedules across projects (keboola.scheduler)"
+)
+
+
+@schedule_app.callback(invoke_without_command=True)
+def _schedule_permission_check(ctx: typer.Context) -> None:
+    check_cli_permission(ctx, "schedule")
+
+
+# ---------------------------------------------------------------------------
+# Shared helpers
+# ---------------------------------------------------------------------------
+
+
+def _enabled_badge(enabled: bool) -> str:
+    return "[green]yes[/green]" if enabled else "[yellow]no[/yellow]"
+
+
+def _format_schedule_table(
+    formatter: Any,
+    schedules: list[dict[str, Any]],
+    *,
+    extra_columns: list[str] | None = None,
+) -> None:
+    """Render a schedule list as a Rich table.
+
+    ``extra_columns`` optionally appends columns like ``last_run_at`` that
+    only exist on the ``find`` output, keeping the base list view compact.
+    """
+    extra_columns = extra_columns or []
+
+    columns = [
+        "Project",
+        "Schedule",
+        "Parent",
+        "Component",
+        "Cron",
+        "TZ",
+        "Enabled",
+    ]
+    columns.extend(extra_columns)
+
+    tbl = Table(*columns, show_header=True, header_style="bold cyan")
+    for s in schedules:
+        row = [
+            escape(s.get("project_alias", "")),
+            escape(s.get("schedule_name", "") or s.get("schedule_id", "")),
+            escape(s.get("parent_name", "") or s.get("parent_config_id", "")),
+            escape(s.get("parent_component_id", "")),
+            escape(s.get("cron", "")),
+            escape(s.get("timezone", "")),
+            _enabled_badge(bool(s.get("enabled", False))),
+        ]
+        for col in extra_columns:
+            if col == "Last run":
+                row.append(escape(s.get("last_run_at") or "never"))
+            elif col == "In window":
+                match = s.get("matches_cron_window")
+                # ``None`` means the filter was never evaluated -- render
+                # as a neutral dash instead of a green "yes" to avoid
+                # visually implying an affirmative match.
+                if match is None:
+                    row.append("[dim]—[/dim]")
+                else:
+                    row.append(_enabled_badge(bool(match)))
+            else:
+                row.append("")
+        tbl.add_row(*row)
+    formatter.console.print(tbl)
+
+
+def _emit_errors(formatter: Any, errors: list[dict[str, Any]]) -> None:
+    for err in errors:
+        formatter.warning(
+            f"Project '{err.get('project_alias', '?')}': {err.get('message', 'error')}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# schedule list
+# ---------------------------------------------------------------------------
+
+
+@schedule_app.command("list")
+def schedule_list(
+    ctx: typer.Context,
+    project: list[str] | None = typer.Option(
+        None,
+        "--project",
+        help="Project alias (repeatable; omit for all registered projects)",
+    ),
+    enabled_only: bool = typer.Option(
+        False,
+        "--enabled-only",
+        help="Only show schedules whose state is 'enabled'",
+    ),
+    branch: int | None = typer.Option(
+        None, "--branch", help="Dev branch ID (requires single --project)"
+    ),
+) -> None:
+    """List cron schedules (keboola.scheduler configs) across projects.
+
+    Each row shows: project alias, schedule ID + name, parent component ID
+    and config name, cron expression, timezone, and enabled state.
+    """
+    formatter = get_formatter(ctx)
+    service = get_service(ctx, "schedule_service")
+    config_store = ctx.obj["config_store"]
+
+    if branch is not None and (not project or len(project) != 1):
+        formatter.error(
+            message="--branch requires exactly one --project",
+            error_code=ErrorCode.INVALID_ARGUMENT,
+        )
+        raise typer.Exit(code=2) from None
+
+    effective_branch: int | None = branch
+    if branch is None and project and len(project) == 1:
+        _, effective_branch = resolve_branch(config_store, formatter, project[0], None)
+
+    try:
+        result = service.list_schedules(
+            aliases=project,
+            enabled_only=enabled_only,
+            branch_id=effective_branch,
+        )
+    except ConfigError as exc:
+        formatter.error(message=exc.message, error_code=ErrorCode.CONFIG_ERROR)
+        raise typer.Exit(code=5) from None
+
+    if formatter.json_mode:
+        formatter.output(result)
+        return
+
+    schedules = result.get("schedules", [])
+    if not schedules:
+        formatter.console.print("[dim]No schedules found.[/dim]")
+    else:
+        _format_schedule_table(formatter, schedules)
+    _emit_errors(formatter, result.get("errors", []))
+
+
+# ---------------------------------------------------------------------------
+# schedule detail
+# ---------------------------------------------------------------------------
+
+
+@schedule_app.command("detail")
+def schedule_detail(
+    ctx: typer.Context,
+    project: str = typer.Option(..., "--project", help="Project alias"),
+    schedule_id: str = typer.Option(
+        ..., "--schedule-id", help="keboola.scheduler configuration ID"
+    ),
+    branch: int | None = typer.Option(None, "--branch", help="Dev branch ID"),
+) -> None:
+    """Show full detail for a single cron schedule.
+
+    Returns the cron expression, timezone, enabled state, and the parent
+    configuration the schedule targets (component_id + config_id + name).
+    """
+    formatter = get_formatter(ctx)
+    service = get_service(ctx, "schedule_service")
+    config_store = ctx.obj["config_store"]
+    _, effective_branch = resolve_branch(config_store, formatter, project, branch)
+
+    try:
+        result = service.get_schedule_detail(
+            alias=project,
+            schedule_id=schedule_id,
+            branch_id=effective_branch,
+        )
+    except ConfigError as exc:
+        formatter.error(message=exc.message, error_code=ErrorCode.CONFIG_ERROR)
+        raise typer.Exit(code=5) from None
+    except KeboolaApiError as exc:
+        formatter.error(message=exc.message, error_code=exc.error_code, retryable=exc.retryable)
+        raise typer.Exit(code=map_error_to_exit_code(exc)) from None
+
+    if formatter.json_mode:
+        formatter.output(result)
+        return
+
+    formatter.console.print(
+        f"\n[bold]{escape(result.get('schedule_name', ''))}[/bold] "
+        f"[dim](ID: {escape(result.get('schedule_id', ''))})[/dim]"
+    )
+    formatter.console.print(f"  Project:     {escape(result.get('project_alias', ''))}")
+    if result.get("branch_id") is not None:
+        formatter.console.print(f"  Branch:      {result['branch_id']}")
+    formatter.console.print(
+        f"  Parent:      {escape(result.get('parent_name', '') or '(unknown)')} "
+        f"[dim]{escape(result.get('parent_component_id', ''))}/"
+        f"{escape(result.get('parent_config_id', ''))}[/dim]"
+    )
+    formatter.console.print(f"  Cron:        {escape(result.get('cron', ''))}")
+    formatter.console.print(f"  Timezone:    {escape(result.get('timezone', ''))}")
+    formatter.console.print(f"  Enabled:     {_enabled_badge(bool(result.get('enabled', False)))}")
+    if result.get("created"):
+        formatter.console.print(f"  Created:     {escape(result['created'])}")
+
+
+# ---------------------------------------------------------------------------
+# schedule find
+# ---------------------------------------------------------------------------
+
+
+@schedule_app.command("find")
+def schedule_find(
+    ctx: typer.Context,
+    project: list[str] | None = typer.Option(
+        None,
+        "--project",
+        help="Project alias (repeatable; omit for all projects)",
+    ),
+    cron_window: str | None = typer.Option(
+        None,
+        "--cron-window",
+        help="Only include schedules firing entirely inside an hour window, "
+        "e.g. '02:00-04:00'. Hour-field approximation -- see gotchas.md.",
+    ),
+    not_run_since: int | None = typer.Option(
+        None,
+        "--not-run-since",
+        help="Only include schedules whose parent config has not produced "
+        "a job in the last N days (or never ran). Pass 0 to force the "
+        "last_run_at lookup for every row without applying a staleness "
+        "filter. NOTE: Queue API is not branch-aware -- combining with "
+        "--branch still compares against production jobs.",
+    ),
+    branch: int | None = typer.Option(
+        None, "--branch", help="Dev branch ID (requires single --project)"
+    ),
+) -> None:
+    """Audit schedules by cron window or job-freshness.
+
+    The ``last_run_at`` and ``matches_cron_window`` columns are always
+    present in the output but populated only when the corresponding
+    filter is active. Without filters both stay ``None`` -- this avoids
+    N extra Queue API calls per project purely to populate columns the
+    caller did not ask for. Pass ``--not-run-since 0`` to force the
+    ``last_run_at`` lookup for every row (N extra API calls per
+    project).
+
+    ``--not-run-since`` resolves jobs via the Queue API, which has no
+    branch-awareness: ``schedule find --branch <DEV> --not-run-since N``
+    still compares against production jobs. Expect false-positive
+    "stale" matches for dev branches with freshly-deployed configs.
+
+    \b
+    Examples:
+      # Schedules that fire between 02:00 and 04:00 across every project
+      kbagent --json schedule find --cron-window "02:00-04:00"
+
+      # Schedules whose parent hasn't run in the last 90 days
+      kbagent --json schedule find --not-run-since 90
+
+      # Both filters combined (AND)
+      kbagent --json schedule find --cron-window "00:00-05:00" --not-run-since 30
+
+      # No filters -> same rows as 'schedule list' plus empty last_run_at +
+      # empty matches_cron_window columns (populated only when filters active)
+      kbagent --json schedule find
+
+      # Force last_run_at population on every row (no staleness filter)
+      kbagent --json schedule find --not-run-since 0
+    """
+    formatter = get_formatter(ctx)
+    service = get_service(ctx, "schedule_service")
+    config_store = ctx.obj["config_store"]
+
+    if branch is not None and (not project or len(project) != 1):
+        formatter.error(
+            message="--branch requires exactly one --project",
+            error_code=ErrorCode.INVALID_ARGUMENT,
+        )
+        raise typer.Exit(code=2) from None
+
+    effective_branch: int | None = branch
+    if branch is None and project and len(project) == 1:
+        _, effective_branch = resolve_branch(config_store, formatter, project[0], None)
+
+    try:
+        result = service.find_schedules(
+            aliases=project,
+            cron_window=cron_window,
+            not_run_since_days=not_run_since,
+            branch_id=effective_branch,
+        )
+    except ConfigError as exc:
+        formatter.error(message=exc.message, error_code=ErrorCode.CONFIG_ERROR)
+        raise typer.Exit(code=5) from None
+
+    if formatter.json_mode:
+        formatter.output(result)
+        return
+
+    schedules = result.get("schedules", [])
+    if not schedules:
+        formatter.console.print("[dim]No schedules match the filters.[/dim]")
+    else:
+        extras: list[str] = []
+        if cron_window is not None:
+            extras.append("In window")
+        if not_run_since is not None:
+            extras.append("Last run")
+        _format_schedule_table(formatter, schedules, extra_columns=extras)
+    _emit_errors(formatter, result.get("errors", []))