pushmetrics-cli 0.1.0__py3-none-any.whl

pm/commands/saved_blocks.py

@@ -0,0 +1,97 @@
+"""Saved block (template) commands.
+
+Backend only allows updating `parameters_schema`. The `create` flow on the FE
+is composite (create block, then create saved_block wrapper) — out of scope
+for Phase 6.1. Use `ls`, `update --schema`, or `delete`.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+import click
+
+from pm._alias import AliasedGroup
+from pm.client import PMClient
+from pm.commands._helpers import (
+    confirm_delete,
+    json_option,
+    parse_data,
+    report_deleted,
+    yes_option,
+    limit_option,
+    name_filter_option,
+    select_rows,
+)
+from pm.output import emit
+
+
+@click.group(name="saved-blocks", cls=AliasedGroup, aliases={"ls": "list"})
+def saved_blocks() -> None:
+    """Saved blocks (reusable block templates)."""
+
+
+@saved_blocks.command(name="list")
+@name_filter_option(matches="the saved block's name")
+@limit_option
+@json_option
+@click.pass_context
+def ls(ctx: click.Context, name_filter: Optional[str], limit: Optional[int]) -> None:
+    """List saved blocks in the current workspace."""
+    client = PMClient.from_profile(ctx.obj["profile"])
+    items = select_rows(
+        client.saved_blocks.list(),
+        name=name_filter,
+        fields=(lambda r: (r.get("block") or {}).get("name") if isinstance(r.get("block"), dict) else None,),
+        limit=limit,
+    )
+    client.persist()
+    emit(
+        items,
+        json_output=ctx.obj["json"],
+        columns=[
+            ("UID", "uid"),
+            ("BLOCK_ID", "block_id"),
+            ("NAME", lambda r: (r.get("block") or {}).get("name", "") if isinstance(r.get("block"), dict) else ""),
+            ("TYPE", lambda r: (r.get("block") or {}).get("type", "") if isinstance(r.get("block"), dict) else ""),
+        ],
+    )
+
+
+@saved_blocks.command(name="update")
+@click.argument("uid")
+@click.option(
+    "--schema",
+    "schema_str",
+    default=None,
+    help="The new parameters schema, as a JSON object.",
+)
+@json_option
+@click.pass_context
+def update(ctx: click.Context, uid: str, schema_str: Optional[str]) -> None:
+    """Replace a saved block's parameters schema.
+
+    The parameters schema is the only field of a saved block that can be
+    changed.
+    """
+    if not schema_str:
+        raise click.UsageError("Pass --schema '<json>'.")
+    parameters_schema = parse_data(schema_str)
+    client = PMClient.from_profile(ctx.obj["profile"])
+    sb = client.saved_blocks.update(uid, {"parameters_schema": parameters_schema})
+    client.persist()
+    emit(sb, json_output=ctx.obj["json"])
+
+
+@saved_blocks.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 saved block."""
+    if not yes:
+        confirm_delete("saved block", uid)
+    client = PMClient.from_profile(ctx.obj["profile"])
+    client.saved_blocks.delete(uid)
+    client.persist()
+    report_deleted(ctx, "saved block", uid)

pm/commands/sftp.py

@@ -0,0 +1,19 @@
+"""`pm sftp` — create + send SFTP upload blocks.
+
+pm-tool introduces SFTP as a NEW agent capability (no direct LLM tool
+exists today). Per codex R3 #5 the agent-side mode should still suppress
+this from `single_tool` help/dispatch until the email/slack soak proves
+out — but the human-facing CLI exposes it fully here.
+"""
+from __future__ import annotations
+
+from pm.commands._block_factory import make_block_group
+
+
+sftp = make_block_group(
+    "sftp",
+    "sftp",
+    help_text="SFTP upload blocks.\n\nBlock type: sftp.",
+    crud_verbs=("create", "list", "get"),
+    execute_verb="send",
+)

pm/commands/slack.py

@@ -0,0 +1,13 @@
+"""`pm slack` — create + send Slack message blocks."""
+from __future__ import annotations
+
+from pm.commands._block_factory import make_block_group
+
+
+slack = make_block_group(
+    "slack",
+    "slack",
+    help_text="Slack message blocks.\n\nBlock type: slack.",
+    crud_verbs=("create", "list", "get"),
+    execute_verb="send",
+)

pm/commands/slides.py

@@ -0,0 +1,216 @@
+"""`pm slides` — create + run Google Slides blocks + advanced verbs.
+
+A Slides block points at a Google Slides template via integration_id +
+template_id; running it renders the template with placeholder data and
+produces a new presentation.
+
+NOTE: the backend stores these as ``block.type = "google_slides"`` — see
+`prefect/queryme/noteflow/template_block/google_slides.py`. The CLI group
+name is the short `slides`; the bound block_type is the full backend
+name so create/run dispatch correctly.
+
+Three custom verbs ship here:
+
+- ``parse-template <uid>`` — hits the dedicated
+  ``POST /api/v1/block/<uid>/parse_slides_template`` endpoint. Parses a
+  master deck into template partials + sample composition_json,
+  persists them onto the block, returns them. Run this once after
+  creating a slides block from a master deck.
+
+- ``export <uid> [--filename name.pdf]`` — convenience wrapper over
+  ``pm slides run``. Sets ``action="export_pdf"`` in the block's
+  content_json (temporarily, for this run only) so the executor renders
+  the existing presentation to PDF and uploads to S3.
+
+- ``batch-update <uid> --stdin`` — convenience wrapper over
+  ``pm slides run``. Reads a JSON array of Google Slides batchUpdate
+  request objects from stdin and dispatches via
+  ``action="batch_update"``. Advanced escape hatch for arbitrary slide
+  mutations.
+
+The ``export`` and ``batch-update`` verbs use a content-json-override
+helper because the backend's run endpoint shallow-merges request.json
+into block fields; partial overrides into content_json have to
+fetch+merge+serialize CLI-side.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, Dict, Optional
+
+import click
+
+from pm.client import PMClient
+from pm.commands._block_factory import make_block_group
+from pm.commands._helpers import json_option
+from pm.output import emit
+
+
+# ── Helper: run with content_json overrides ──────────────────────────
+
+
+def _run_with_content_overrides(
+    client: PMClient,
+    uid: str,
+    *,
+    overrides: Dict[str, Any],
+) -> Dict[str, Any]:
+    """Fetch the block, merge ``overrides`` into its content_json, and run.
+
+    The backend's `/run` handler shallow-merges request.json into block
+    fields (FAB's ``_merge_update_item``). For partial overrides INTO
+    content_json (not full content_json replacement), the CLI has to do
+    the merge itself: fetch → parse content_json → update → re-serialize
+    → send the merged content_json as a top-level field.
+
+    The merge is in-memory on the backend (the run handler reverts
+    block.content_json after dispatch), so the override is per-run only.
+    """
+    block = client.blocks.get(uid)
+    raw = block.content_json or "{}"
+    if isinstance(raw, str):
+        try:
+            current = json.loads(raw) if raw else {}
+        except json.JSONDecodeError as exc:
+            raise click.ClickException(
+                f"Block {uid} has invalid content_json — cannot merge "
+                f"overrides ({exc.msg})",
+            )
+    elif isinstance(raw, dict):
+        current = dict(raw)
+    else:
+        current = {}
+    current.update(overrides)
+    return client.blocks.execute_existing(
+        uid,
+        verb="run",
+        block_properties={
+            "content_json": json.dumps(current),
+        },
+    )
+
+
+# ── parse-template ───────────────────────────────────────────────────
+
+
+@click.command(name="parse-template")
+@click.argument("uid")
+@json_option
+@click.pass_context
+def parse_template(ctx: click.Context, uid: str) -> None:
+    """Read a master deck into reusable slide templates.
+
+    The block must name its source_file_id and integration_id. Run this
+    once after pm slides create; it returns the template definition and
+    a sample composition to start from.
+    """
+    client = PMClient.from_profile(ctx.obj["profile"])
+    result = client.blocks.parse_slides_template(uid)
+    client.persist()
+    emit(result, json_output=ctx.obj["json"])
+
+
+# ── export ───────────────────────────────────────────────────────────
+
+
+@click.command(name="export")
+@click.argument("uid")
+@click.option(
+    "--filename",
+    default=None,
+    help="Name of the PDF, e.g. q4-report.pdf (default: the presentation's name).",
+)
+@json_option
+@click.pass_context
+def export(
+    ctx: click.Context,
+    uid: str,
+    filename: Optional[str],
+) -> None:
+    """Export the block's presentation as a PDF.
+
+    Returns the download URL. The block must have been run at least once
+    so that it has a presentation.
+    """
+    overrides: Dict[str, Any] = {
+        "action": "export_pdf",
+    }
+    if filename:
+        overrides["export_options"] = {
+            "pdf_filename": filename,
+        }
+    client = PMClient.from_profile(ctx.obj["profile"])
+    result = _run_with_content_overrides(client, uid, overrides=overrides)
+    client.persist()
+    emit(result, json_output=ctx.obj["json"])
+
+
+# ── batch-update ─────────────────────────────────────────────────────
+
+
+@click.command(name="batch-update")
+@click.argument("uid")
+@click.option(
+    "--stdin",
+    "use_stdin",
+    is_flag=True,
+    required=True,
+    help=(
+        "Read the JSON body from stdin: an array of Google Slides "
+        "batchUpdate request objects."
+    ),
+)
+@json_option
+@click.pass_context
+def batch_update(
+    ctx: click.Context,
+    uid: str,
+    use_stdin: bool,
+) -> None:
+    """Apply Google Slides batchUpdate requests to the deck.
+
+    For edits the template flow does not cover. Requests are forwarded to
+    the Google Slides API; destructive request types are refused.
+    """
+    raw = sys.stdin.read()
+    if not raw.strip():
+        raise click.UsageError("--stdin was given but stdin was empty.")
+    try:
+        requests_list = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise click.ClickException(f"--stdin: invalid JSON ({exc.msg})")
+    if not isinstance(requests_list, list):
+        raise click.ClickException(
+            f"--stdin must be a JSON array of batchUpdate request objects, "
+            f"got {type(requests_list).__name__}",
+        )
+
+    overrides: Dict[str, Any] = {
+        "action": "batch_update",
+        # The backend reads this list from `content.get("requests", [])`
+        # (google_slides.py:149). Previously sent under `requests_list`
+        # which silently dropped every batch update — codex catch.
+        "requests": requests_list,
+    }
+    client = PMClient.from_profile(ctx.obj["profile"])
+    result = _run_with_content_overrides(client, uid, overrides=overrides)
+    client.persist()
+    emit(result, json_output=ctx.obj["json"])
+
+
+# ── Group ────────────────────────────────────────────────────────────
+
+
+slides = make_block_group(
+    "slides",
+    "google_slides",
+    crud_verbs=("create", "list", "get"),
+    execute_verb="run",
+    help_text="Google Slides blocks.\n\nBlock type: google_slides.",
+    custom_verbs={
+        "parse-template": parse_template,
+        "export": export,
+        "batch-update": batch_update,
+    },
+)

pm/commands/sql.py

@@ -0,0 +1,17 @@
+"""`pm sql` — create + run SQL blocks.
+
+Per pm-tool plan §3.8. Domain group with the standard CRUD discovery
+(``list`` / ``get``) plus the typed ``create`` and ``run`` verbs.
+"""
+from __future__ import annotations
+
+from pm.commands._block_factory import make_block_group
+
+
+sql = make_block_group(
+    "sql",
+    "sql",
+    help_text="SQL query blocks.\n\nBlock type: sql.",
+    crud_verbs=("create", "list", "get"),
+    execute_verb="run",
+)

pm/commands/tableau.py

@@ -0,0 +1,148 @@
+"""`pm tableau` — create + run Tableau view blocks + discovery verbs.
+
+A Tableau block points at a Tableau view via an integration_id + view_id;
+running it exports/downloads the rendered view as PNG/PDF (or returns an
+embed URL).
+
+Standard create + run + results come from the factory. Two custom verbs
+hit the Tableau integration API directly (no block needed) for discovery
+before creating a block:
+
+- ``pm tableau search`` — list views (default) or workbooks (``--workbooks``)
+  available through a Tableau integration, with optional ``--keyword`` and
+  ``--workbook-id`` filters.
+- ``pm tableau view`` — fetch one view's metadata by ``--view-id`` (the
+  natural follow-up to search: drill into details before creating a block).
+
+``run`` help is overridden per codex R3 #6 so agents don't mistake it for
+report execution.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+import click
+
+from pm.client import PMClient
+from pm.commands._block_factory import make_block_group
+from pm.commands._helpers import json_option
+from pm.output import emit
+
+
+# ── search ────────────────────────────────────────────────────────────
+
+
+@click.command(name="search")
+@click.option(
+    "--integration",
+    "integration_uid",
+    required=True,
+    help="Tableau integration uid (from pm integration list).",
+)
+@click.option(
+    "--keyword",
+    default=None,
+    help="Only views (or workbooks) whose name contains this text.",
+)
+@click.option(
+    "--workbook-id",
+    default=None,
+    help="Only views in this Tableau workbook id. Ignored with --workbooks.",
+)
+@click.option(
+    "--workbooks",
+    is_flag=True,
+    help="Search workbooks instead of views.",
+)
+@json_option
+@click.pass_context
+def search(
+    ctx: click.Context,
+    integration_uid: str,
+    keyword: Optional[str],
+    workbook_id: Optional[str],
+    workbooks: bool,
+) -> None:
+    """Search the views or workbooks of a Tableau site.
+
+    Each result has an id, name and content URL; views also carry their
+    workbook id.
+    """
+    client = PMClient.from_profile(ctx.obj["profile"])
+    if workbooks:
+        results = client.tableau.list_workbooks(
+            integration_uid,
+            keyword=keyword,
+        )
+    else:
+        results = client.tableau.list_views(
+            integration_uid,
+            keyword=keyword,
+            workbook_id=workbook_id,
+        )
+    client.persist()
+    emit(
+        results,
+        json_output=ctx.obj["json"],
+        columns=[
+            ("ID", lambda r: r.get("id", "")),
+            ("NAME", lambda r: r.get("name", "")),
+            ("WORKBOOK", lambda r: r.get("workbook_id") or r.get("contentUrl") or ""),
+        ],
+    )
+
+
+# ── view ──────────────────────────────────────────────────────────────
+
+
+@click.command(name="view")
+@click.option(
+    "--integration",
+    "integration_uid",
+    required=True,
+    help="Tableau integration uid (from pm integration list).",
+)
+@click.option(
+    "--view-id",
+    required=True,
+    help="Tableau view id (from pm tableau search).",
+)
+@json_option
+@click.pass_context
+def view(
+    ctx: click.Context,
+    integration_uid: str,
+    view_id: str,
+) -> None:
+    """Show one Tableau view.
+
+    The follow-up to tableau search before creating a Tableau block.
+    """
+    client = PMClient.from_profile(ctx.obj["profile"])
+    result = client.tableau.get_view(integration_uid, view_id)
+    client.persist()
+    emit(result, json_output=ctx.obj["json"])
+
+
+# ── Group ────────────────────────────────────────────────────────────
+
+
+tableau = make_block_group(
+    "tableau",
+    "tableau",
+    crud_verbs=("create", "list", "get"),
+    execute_verb="run",
+    help_text="Tableau view blocks.\n\nBlock type: tableau.",
+    verb_help={
+        "run": (
+            "Export a Tableau view as PNG, PDF or an embed URL.\n\n"
+            "Pass UID to render a saved Tableau block, or --stdin with a "
+            "body holding integration_id and view_id to render once "
+            "without saving."
+        ),
+    },
+    custom_verbs={
+        "search": search,
+        "view": view,
+    },
+)

pm/commands/token.py

@@ -0,0 +1,107 @@
+"""Personal Access Token commands (`pm token create|list|revoke`).
+
+Tokens authenticate the CLI / any programmatic client via
+``Authorization: Bearer pmpat_...`` (exchanged for a short-lived JWT). Manage
+them here while logged in (cookie or token auth both work); store a created
+token with `pm login --token`.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+import click
+
+from pm._alias import AliasedGroup
+from pm.client import PMClient
+from pm.commands._helpers import info, json_option, limit_option, name_filter_option, select_rows
+from pm.output import emit
+
+
+@click.group(
+    name="token",
+    cls=AliasedGroup,
+    aliases={
+        "ls": "list",
+        "rm": "revoke",
+        "delete": "revoke",
+    },
+)
+def token() -> None:
+    """Personal access tokens for API / CLI authentication."""
+
+
+@token.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 your tokens in the current workspace."""
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    client = PMClient.from_profile(profile)
+    items = select_rows(client.access_tokens.list(), name=name_filter, limit=limit)
+    client.persist()
+
+    emit(
+        items,
+        json_output=json_output,
+        columns=[
+            ("ID", "id"),
+            ("NAME", "name"),
+            ("PREFIX", "token_prefix"),
+            ("CREATED", "created_on"),
+            ("LAST_USED", "last_used_on"),
+            ("EXPIRES", "expires_on"),
+        ],
+    )
+
+
+@token.command(name="create")
+@click.argument("name")
+@click.option(
+    "--expires-on",
+    default=None,
+    help="Expiry date, ISO 8601, e.g. 2026-12-31 or 2026-12-31T23:59:59 (default: none).",
+)
+@json_option
+@click.pass_context
+def create(ctx: click.Context, name: str, expires_on: str) -> None:
+    """Create a token; its value is shown once.
+
+    The token value goes to stdout so it can be captured or piped; the
+    reminder goes to stderr.
+    """
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    client = PMClient.from_profile(profile)
+    raw_token, meta = client.access_tokens.create(name, expires_on=expires_on)
+    client.persist()
+
+    if json_output:
+        payload = meta.model_dump()
+        payload["token"] = raw_token
+        emit(payload, json_output=True)
+        return
+
+    click.echo(raw_token)
+    info(ctx, "Copy your access token now. You won't be able to see this again.")
+    info(ctx, "Use it with: pm login --token (paste it at the hidden prompt). "
+              "In CI, set PM_API_TOKEN from the secret store.")
+
+
+@token.command(name="revoke")
+@click.argument("token_id")
+@json_option
+@click.pass_context
+def revoke(ctx: click.Context, token_id: str) -> None:
+    """Revoke a token by its numeric ID (from pm token list)."""
+    profile = ctx.obj["profile"]
+
+    client = PMClient.from_profile(profile)
+    client.access_tokens.revoke(token_id)
+    client.persist()
+
+    info(ctx, f"Revoked token {token_id}.")