pushmetrics-cli 0.1.0__py3-none-any.whl

pm/commands/reports.py

@@ -0,0 +1,364 @@
+"""Report commands."""
+from __future__ import annotations
+
+import sys
+from typing import Optional
+
+import click
+
+from pm._alias import AliasedGroup
+from pm.client import PMClient
+from pm.client.base import PMApiError
+from pm.commands._helpers import (
+    confirm_delete,
+    info,
+    json_option,
+    merge_fields,
+    parse_data,
+    peek_name,
+    report_deleted,
+    yes_option,
+    limit_option,
+    name_filter_option,
+    select_rows,
+)
+from pm.output import emit
+
+
+@click.group(name="reports", cls=AliasedGroup, aliases={"ls": "list"})
+def reports() -> None:
+    """Reports and their runs."""
+
+
+@reports.command(name="list")
+@name_filter_option
+@limit_option
+@json_option
+@click.pass_context
+def ls(ctx: click.Context, name_filter: Optional[str], limit: Optional[int]) -> None:
+    """List reports in the current workspace."""
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    client = PMClient.from_profile(profile)
+    # list_all (not list): FAB caps a single page at ~100 rows, so a plain
+    # list() lets the agent undercount a large workspace and present the
+    # capped page as the total (support session GYmXdRekqy, 2026-07-19).
+    # --limit without --name only needs the first N rows, so stop paging
+    # there; a plain `report list` (what the agent calls) still walks every
+    # page so the count is the workspace total.
+    fetch_limit = limit if name_filter is None else None
+    items = select_rows(client.reports.list_all(limit=fetch_limit), name=name_filter, limit=limit)
+    client.persist()
+
+    emit(
+        items,
+        json_output=json_output,
+        columns=[
+            ("UID", "uid"),
+            ("NAME", "name"),
+            ("CREATED", "created_on"),
+            ("WORKFLOW", lambda r: "y" if r.get("workflow_enabled") else ""),
+        ],
+    )
+
+
+@reports.command(name="get")
+@click.argument("uid")
+@json_option
+@click.pass_context
+def get(ctx: click.Context, uid: str) -> None:
+    """Show one report (use --json for the full record)."""
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    client = PMClient.from_profile(profile)
+    report = client.reports.get(uid)
+    client.persist()
+
+    if json_output:
+        emit(report, json_output=True)
+    else:
+        emit(
+            {
+                "uid": report.uid,
+                "name": report.name,
+                "workflow_enabled": report.workflow_enabled,
+            },
+            json_output=False,
+        )
+
+
+@reports.command(name="run")
+@click.argument("uid")
+@click.option(
+    "--send-to-me",
+    is_flag=True,
+    help=(
+        "Redirect email destination blocks to the calling user (or "
+        "--email) and suppress all other destination blocks "
+        "(slack/webhook/sftp/cloud-storage). Useful for preview runs "
+        "that shouldn't fire real notifications."
+    ),
+)
+@click.option(
+    "--email",
+    default=None,
+    help=(
+        "Address that receives the email blocks when --send-to-me is set. "
+        "Defaults to your own address; pass a saved recipient's address to "
+        "preview as them. Requires --send-to-me."
+    ),
+)
+@json_option
+@click.pass_context
+def run(ctx: click.Context, uid: str, send_to_me: bool, email: Optional[str]) -> None:
+    """Run a report now.
+
+    Prints the new run's uid immediately; the run itself happens in the
+    background. Check on it with pm run get <uid> or pm run logs <uid>.
+    """
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    if email and not send_to_me:
+        raise click.UsageError("--email requires --send-to-me")
+
+    client = PMClient.from_profile(profile)
+
+    # Auto-detect: without an email, the backend suppresses email blocks
+    # instead of redirecting them.
+    if send_to_me and not email:
+        try:
+            email = client.users.current().email
+        except PMApiError as exc:
+            raise click.ClickException(
+                f"--send-to-me needs an email; current user lookup failed: {exc}"
+            )
+
+    result = client.reports.run(uid, send_to_me=send_to_me, email=email)
+    client.persist()
+
+    payload = result.get("result") if isinstance(result, dict) and isinstance(result.get("result"), dict) else result
+    run_uid = payload.get("noteflow_run_uid") if isinstance(payload, dict) else None
+    if json_output or not run_uid:
+        emit(result, json_output=json_output)
+        return
+    # stdout is data: the uid alone, so RUN=$(pm report run X) works.
+    click.echo(run_uid)
+    info(ctx, f"Started run {run_uid}. Follow it with: pm run get {run_uid}")
+
+
+@reports.command(name="yaml")
+@click.argument("uid")
+@json_option
+@click.pass_context
+def yaml_(ctx: click.Context, uid: str) -> None:
+    """Export a report as YAML to stdout.
+
+    --json is ignored here: the output is the YAML document itself, ready
+    for pm report apply.
+    """
+    profile = ctx.obj["profile"]
+    client = PMClient.from_profile(profile)
+    yaml_text = client.reports.yaml(uid)
+    client.persist()
+    # Write directly to avoid emit's trailing newline (YAML already has one).
+    sys.stdout.write(yaml_text)
+    if not yaml_text.endswith("\n"):
+        sys.stdout.write("\n")
+
+
+@reports.command(name="delete")
+@click.argument("uid")
+@yes_option
+@json_option
+@click.pass_context
+def delete(ctx: click.Context, uid: str, yes: bool) -> None:
+    """Delete a report.
+
+    The report's blocks stay in the workspace; its run history is removed
+    with it. This cannot be undone.
+    """
+    profile = ctx.obj["profile"]
+
+    if not yes:
+        name = peek_name(lambda: PMClient.from_profile(profile).reports.get(uid), "name")
+        confirm_delete("report", uid, name)
+
+    client = PMClient.from_profile(profile)
+    client.reports.delete(uid)
+    client.persist()
+    report_deleted(ctx, "report", uid)
+
+
+@reports.command(name="apply")
+@click.argument("file", type=click.File("r", encoding="utf-8"))
+@click.option(
+    "--uid",
+    default=None,
+    help=(
+        "Update this existing report instead of creating a new one. "
+        "Pass - as FILE to read the YAML from stdin."
+    ),
+)
+@click.option(
+    "--allow-create-folder",
+    is_flag=True,
+    help=(
+        "Create the folder named in the YAML if it does not exist. By "
+        "default an unknown folder path is rejected."
+    ),
+)
+@click.option(
+    "--no-prune",
+    is_flag=True,
+    help=(
+        "With --uid: keep blocks that are in the report but missing from "
+        "the YAML. By default they are removed."
+    ),
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help=(
+        "With --uid: show what would change (a summary and a YAML diff) "
+        "without saving anything."
+    ),
+)
+@json_option
+@click.pass_context
+def apply(
+    ctx: click.Context,
+    file,
+    uid: Optional[str],
+    allow_create_folder: bool,
+    no_prune: bool,
+    dry_run: bool,
+) -> None:
+    """Create or update a report from YAML.
+
+    \b
+    To round-trip an existing report:
+      pm report yaml <uid> > report.yaml
+      pm report apply report.yaml --uid <uid>             full replace
+      pm report apply report.yaml --uid <uid> --no-prune  keep extra blocks
+      pm report apply report.yaml --uid <uid> --dry-run   preview the diff
+    """
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    yaml_text = file.read()
+    if not yaml_text.strip():
+        raise click.ClickException("YAML body is empty.")
+
+    if (no_prune or dry_run) and not uid:
+        raise click.UsageError("--no-prune and --dry-run need --uid.")
+
+    client = PMClient.from_profile(profile)
+    if uid:
+        result = client.reports.update_yaml(
+            uid,
+            yaml_text,
+            prune=not no_prune,
+            dry_run=dry_run,
+            allow_create_folder=allow_create_folder,
+        )
+        action = "dry-run" if dry_run else "updated"
+    else:
+        result = client.reports.apply_yaml(
+            yaml_text,
+            allow_create_folder=allow_create_folder,
+        )
+        action = "created"
+    client.persist()
+
+    if json_output:
+        emit(result, json_output=True)
+        return
+
+    if dry_run:
+        # Human-mode dry-run summary
+        click.echo(f"dry-run for {uid}:")
+        if not result.get("would_change"):
+            click.echo("  no changes")
+            return
+        summary = result.get("summary") or {}
+        for k, v in summary.items():
+            click.echo(f"  {k}: {v}")
+        diff = result.get("yaml_diff", "")
+        if diff:
+            click.echo("")
+            click.echo(diff)
+        return
+
+    res_uid = result.get("uid", "")
+    res_name = result.get("name", "")
+    click.echo(f"{action}: {res_uid}  {res_name}")
+    warn = result.get("warning_duplicate_uids")
+    if warn:
+        click.echo(
+            f"  warning: {len(warn)} existing report(s) with the same name in this workspace: "
+            + ", ".join(warn)
+            + "  -- use `pm report apply ... --uid <one>` to update instead."
+        )
+
+
+@reports.command(name="update")
+@click.argument("uid")
+@click.option("--folder-id", type=int, default=None,
+              help="Move the report into the folder with this numeric id.")
+@click.option("--name", default=None, help="Rename the report.")
+@click.option("--data", default=None,
+              help="Extra fields as a JSON object (merged with --folder-id / --name).")
+@json_option
+@click.pass_context
+def update(
+    ctx: click.Context,
+    uid: str,
+    folder_id: Optional[int],
+    name: Optional[str],
+    data: Optional[str],
+) -> None:
+    """Update a report's name, folder or other fields.
+
+    Use --data for fields without a flag of their own, e.g.
+    --data '{"options": {...}}'. Unknown fields are ignored.
+    """
+    payload = merge_fields(parse_data(data), {
+        "folder_id": folder_id,
+        "name": name,
+    })
+    if not payload:
+        raise click.UsageError("Nothing to update; pass --folder-id, --name, or --data.")
+    profile = ctx.obj["profile"]
+    client = PMClient.from_profile(profile)
+    report = client.reports.update(uid, payload)
+    client.persist()
+    emit(report, json_output=ctx.obj["json"])
+
+
+@reports.command(name="runs")
+@click.argument("uid")
+@json_option
+@click.pass_context
+def runs(ctx: click.Context, uid: str) -> None:
+    """List the runs of a report."""
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    client = PMClient.from_profile(profile)
+    items = client.reports.runs(uid)
+    client.persist()
+
+    emit(
+        items,
+        json_output=json_output,
+        columns=[
+            ("UID", "uid"),
+            ("NAME", "name"),
+            ("STATUS", "status"),
+            ("START", "start_time"),
+            ("END", "end_time"),
+        ],
+    )

pm/commands/roles.py

@@ -0,0 +1,102 @@
+"""Role / group commands."""
+from __future__ import annotations
+
+from typing import Optional
+
+import click
+
+from pm._alias import AliasedGroup
+from pm.client import PMClient
+from pm.client.roles import MAIN_ROLE_NAMES
+from pm.commands._helpers import json_option, limit_option, name_filter_option, select_rows
+from pm.output import emit
+
+
+@click.group(name="roles", cls=AliasedGroup, aliases={"ls": "list"})
+def roles() -> None:
+    """Roles and groups in the current workspace."""
+
+
+def _kind(name: str) -> str:
+    return "main" if name in MAIN_ROLE_NAMES else "group"
+
+
+@roles.command(name="list")
+@name_filter_option
+@limit_option
+@json_option
+@click.pass_context
+def ls(ctx: click.Context, name_filter: Optional[str], limit: Optional[int]) -> None:
+    """List roles and groups in the current workspace.
+
+    KIND is "main" for Admin, User and Guest, and "group" for everything
+    else.
+    """
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    client = PMClient.from_profile(profile)
+    items = select_rows(client.roles.list(), name=name_filter, limit=limit)
+    client.persist()
+
+    emit(
+        items,
+        json_output=json_output,
+        columns=[
+            ("UID", "uid"),
+            ("ID", "id"),
+            ("NAME", "name"),
+            ("KIND", lambda r: _kind(r.get("name") or "")),
+        ],
+    )
+
+
+@roles.command(name="assign")
+@click.argument("role_ref")
+@click.argument("user_uids", nargs=-1, required=True)
+@json_option
+@click.pass_context
+def assign(ctx: click.Context, role_ref: str, user_uids: tuple) -> None:
+    """Add users to a role or group.
+
+    ROLE_REF is the role uid or name (case-insensitive). Users already in
+    the role are left as they are.
+    """
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    client = PMClient.from_profile(profile)
+    result = client.roles.assign_users(role_ref, list(user_uids))
+    client.persist()
+
+    if json_output:
+        emit(result, json_output=True)
+        return
+    role_info = result.get("role") if isinstance(result, dict) else None
+    role_name = (role_info or {}).get("name", role_ref)
+    click.echo(f"Assigned {len(user_uids)} user(s) to role {role_name!r}.", err=True)
+
+
+@roles.command(name="revoke")
+@click.argument("role_ref")
+@click.argument("user_uids", nargs=-1, required=True)
+@json_option
+@click.pass_context
+def revoke(ctx: click.Context, role_ref: str, user_uids: tuple) -> None:
+    """Remove users from a role or group.
+
+    ROLE_REF is the role uid or name (case-insensitive).
+    """
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    client = PMClient.from_profile(profile)
+    result = client.roles.revoke_users(role_ref, list(user_uids))
+    client.persist()
+
+    if json_output:
+        emit(result, json_output=True)
+        return
+    role_info = result.get("role") if isinstance(result, dict) else None
+    role_name = (role_info or {}).get("name", role_ref)
+    click.echo(f"Removed {len(user_uids)} user(s) from role {role_name!r}.", err=True)

pm/commands/runs.py

@@ -0,0 +1,214 @@
+"""Noteflow run commands."""
+from __future__ import annotations
+
+import re
+
+import click
+
+from pm._alias import AliasedGroup
+from pm.client import PMClient
+from pm.commands._helpers import info, json_option
+from pm.output import emit
+
+# A prefect ``flow_run_id`` is always a UUID (8-4-4-4-12 hex); a run ``uid``
+# is a short hashid with no hyphens. Lets ``pm run logs`` accept either.
+_UUID_RE = re.compile(
+    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-"
+    r"[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+)
+
+
+@click.group(name="runs", cls=AliasedGroup, aliases={"ls": "list"})
+def runs() -> None:
+    """Report runs: status, results and logs."""
+
+
+@runs.command(name="list")
+@click.option(
+    "--limit",
+    type=int,
+    default=None,
+    help="Maximum number of runs to return (default 25, max 5000).",
+)
+@click.option(
+    "--report",
+    "report_uid",
+    default=None,
+    help="Only runs of this report (report uid).",
+)
+@click.option(
+    "--last-days",
+    type=click.IntRange(min=1),
+    default=None,
+    help="Only runs started in the last N days.",
+)
+@click.option(
+    "--status",
+    default=None,
+    help="Only runs with this status (failed, success, running, pending).",
+)
+@json_option
+@click.pass_context
+def ls(ctx: click.Context, limit, report_uid, last_days, status) -> None:
+    """List recent runs, newest first.
+
+    \b
+    Filters combine, so "why did report X fail recently?" is:
+      pm run list --report <report_uid> --last-days 2 --status failed
+      pm run logs <run_uid>
+    """
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    client = PMClient.from_profile(profile)
+    items = client.runs.list(
+        limit=limit,
+        report_uid=report_uid,
+        last_days=last_days,
+        status=status,
+    )
+    client.persist()
+
+    emit(
+        items,
+        json_output=json_output,
+        columns=[
+            ("UID", "uid"),
+            ("NAME", "name"),
+            ("STATUS", "status"),
+            ("START", "start_time"),
+            ("END", "end_time"),
+            ("RE_RUNS", "re_run_count"),
+        ],
+    )
+
+
+@runs.command(name="get")
+@click.argument("run_uid")
+@json_option
+@click.pass_context
+def get(ctx: click.Context, run_uid: str) -> None:
+    """Show one run's status and timing."""
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    client = PMClient.from_profile(profile)
+    run = client.runs.get(run_uid)
+    client.persist()
+
+    if json_output:
+        emit(run, json_output=True)
+    else:
+        emit(
+            {
+                "uid": run.uid,
+                "name": run.name,
+                "status": run.status,
+                "flow_run_id": run.flow_run_id,
+                "start_time": run.start_time,
+                "end_time": run.end_time,
+                "re_run_count": run.re_run_count,
+            },
+            json_output=False,
+        )
+
+
+@runs.command(name="results")
+@click.argument("run_uid")
+@json_option
+@click.pass_context
+def results(ctx: click.Context, run_uid: str) -> None:
+    """Show the per-block results of a run."""
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    client = PMClient.from_profile(profile)
+    items = client.runs.results(run_uid)
+    client.persist()
+
+    # Backend ``task_to_result`` returns ``block_uid``, ``status``,
+    # ``results_key``, ``uid`` (the run uid) — no block_type or
+    # timestamps. Render the columns that actually exist.
+    emit(
+        items,
+        json_output=json_output,
+        columns=[
+            ("BLOCK_UID", "block_uid"),
+            ("STATUS", "status"),
+            ("RESULTS_KEY", "results_key"),
+            ("RUN_UID", "uid"),
+        ],
+    )
+
+
+@runs.command(name="logs")
+@click.argument("run_ref")
+@click.option(
+    "--limit",
+    type=int,
+    default=None,
+    help="Maximum number of log lines to return (default 1000, max 5000).",
+)
+@click.option(
+    "--level",
+    default=None,
+    help="Only lines at this level (ERROR, WARNING, INFO).",
+)
+@json_option
+@click.pass_context
+def logs(ctx: click.Context, run_ref: str, limit, level) -> None:
+    """Show a run's log lines, oldest first.
+
+    RUN_REF is the run uid or its flow run id (UUID). To answer "why did
+    this run fail?", add --level ERROR.
+    """
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    client = PMClient.from_profile(profile)
+
+    if _UUID_RE.match(run_ref):
+        # Already a flow_run_id — no run lookup needed.
+        log_filter = {"flow_run_id": run_ref}
+    else:
+        run = client.runs.get(run_ref)
+
+        # Prefer the stable numeric run id (noteflow_run_id) — populated on
+        # every current log row and unchanged across in-flow retries. Fall
+        # back to flow_run_id only if the run somehow lacks a numeric id.
+        if run.id is not None:
+            log_filter = {"noteflow_run_id": run.id}
+        elif run.flow_run_id:
+            log_filter = {"flow_run_id": run.flow_run_id}
+        else:
+            client.persist()
+            status = f" (status: {run.status})" if run.status else ""
+            raise click.ClickException(
+                f"Run {run_ref} has no id or flow_run_id yet{status}. "
+                "Logs appear once the run starts executing."
+            )
+
+    items = client.runs.logs(limit=limit, **log_filter)
+    client.persist()
+
+    if level:
+        wanted = level.upper()
+        items = [
+            i for i in items
+            if (i.effective_level or "").upper() == wanted
+        ]
+
+    if not items and not json_output:
+        at_level = f" at level {level.upper()}" if level else ""
+        info(ctx, f"No log lines{at_level} for run {run_ref}.")
+        return
+
+    emit(
+        items,
+        json_output=json_output,
+        columns=[
+            ("CREATED", "created_on"),
+            ("LEVEL", "effective_level"),
+            ("MESSAGE", "message"),
+        ],
+    )