procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/procesio/handlers/schedules.py

@@ -0,0 +1,320 @@
+"""Curated scheduler actions (run a process on a cron / recurrence).
+
+Wraps the `/api/Schedules*` surface so a user or agent can list / get / create /
+update / delete a schedule, enable or disable one, manage its notifications, and
+list a project's schedules — without dropping to the untyped generic `request`.
+
+Verified routes + methods (Web-API, tag Schedules; perms in parens):
+  list           GET    /api/Schedules                              (Schedule.Read)
+  get            GET    /api/Schedules/{scheduleId}                 (Schedule.Read)
+  create         POST   /api/Schedules                              (Schedule.Write)
+  update         PUT    /api/Schedules                              (Schedule.Update)
+  delete         DELETE /api/Schedules/{scheduleId}                 (Schedule.Delete)
+  set status     PATCH  /api/Schedules/{scheduleId}/status          (Schedule.Update)
+  get notifs     GET    /api/Schedules/notifications/{scheduleId}    (Schedule.Read)
+  set notifs     POST   /api/Schedules/notifications                 (Schedule.Update)
+  project list   GET    /api/Projects/{id}/restricted/schedules      (Schedule.Read)
+
+The create/update body shape is captured in PROCESIO-API-NOTES.md (Hard rule 6).
+Security: literal ``processInputs`` are persisted and returned by schedule reads.
+The curated handler preserves the raw DTO by default for backward-compatible
+round-tripping and offers ``get-schedule --redact-process-inputs`` for evidence and
+diagnostics. Read SCHEDULE-INPUT-SECURITY-NOTES.md before storing authentication
+material there or capturing a raw schedule result.
+"""
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from tools.procesio import errors
+from tools.procesio.actiondef import ActionDef
+from tools.procesio.client import parse_json_arg
+from tools.procesio.handlers.common import add_paging_args, add_profile_arg
+
+
+_REDACTED = "[REDACTED]"
+
+
+# -- list / get -------------------------------------------------------------
+
+def _list_args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    add_paging_args(p)
+    p.add_argument("--search", help="filter by schedule name (searchName)")
+
+
+def list_schedules(client, args) -> dict:
+    q = {"pageNumber": args.page, "pageItemCount": args.page_size,
+         "searchName": args.search}
+    return {"result": client.get("/api/Schedules", q)}
+
+
+def _id_args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    p.add_argument("--id", required=True, help="schedule id (scheduleId)")
+
+
+def _get_args(p: argparse.ArgumentParser) -> None:
+    _id_args(p)
+    p.add_argument(
+        "--redact-process-inputs",
+        action="store_true",
+        help="replace every returned processInputs[].value with [REDACTED]",
+    )
+
+
+def _redact_process_inputs(value: Any) -> Any:
+    """Copy a schedule DTO while masking literal process-input values.
+
+    Both camelCase live DTOs and PascalCase export-like shapes are handled. Other
+    fields stay byte-for-byte equivalent at the JSON-value level so the result is
+    useful for structural diagnostics without exposing a stored secret.
+    """
+    if isinstance(value, list):
+        return [_redact_process_inputs(item) for item in value]
+    if not isinstance(value, dict):
+        return value
+
+    result: dict[str, Any] = {}
+    for key, item in value.items():
+        if key.casefold() != "processinputs" or not isinstance(item, list):
+            result[key] = _redact_process_inputs(item)
+            continue
+
+        rows: list[Any] = []
+        for row in item:
+            if not isinstance(row, dict):
+                rows.append(_REDACTED if row is not None else None)
+                continue
+            clean: dict[str, Any] = {}
+            for row_key, row_value in row.items():
+                if row_key.casefold() == "value" and row_value is not None:
+                    clean[row_key] = _REDACTED
+                else:
+                    clean[row_key] = _redact_process_inputs(row_value)
+            rows.append(clean)
+        result[key] = rows
+    return result
+
+
+def get_schedule(client, args) -> dict:
+    result = client.get(f"/api/Schedules/{args.id}")
+    if args.redact_process_inputs:
+        result = _redact_process_inputs(result)
+    return {"result": result}
+
+
+# -- create / update / delete ----------------------------------------------
+
+# RecurrenceTypes enum (Domain/Enums/Scheduler/RecurrenceTypes.cs): NONE=0, ONCE=1,
+# MINUTES=2, HOURS=3, DAILY=4, WEEKLY=5, MONTHLY=6, YEARLY=7, CRON=8. The crontab
+# feature (PRC-3282) is recurrence type 8 with a RecurrenceCron block.
+_RECURRENCE_CRON = 8
+
+
+def _apply_cron(body: dict, args) -> dict:
+    """When --cron is given, REPLACE the recurrence block with the crontab shape.
+
+    Replace, not overlay. A cron recurrence carries only `recurrence: 8`,
+    `cronExpression`, `timeZone`, `info`, `startDate` and `isEndDate` (plus `endDate` when
+    the window really ends). Leaving the calendar-recurrence fields in place —
+    `every` / `onDay` / `onThe` / `isOnThe` / `isWeekendExcluded` — is what earns the
+    generic HTTP 400 `[{"statusCode":502,"value":"Invalid request due to missing or
+    incorrect resource parameters.","target":"schedules"}]`. Captured from the designer's
+    own PUT, which sends exactly the keys below and nothing else; the same body that fails
+    with them present succeeds with them stripped, so this drops them rather than
+    trusting a caller's --payload to be cron-shaped already.
+    """
+    if not getattr(args, "cron", None):
+        return body
+    src_rec = dict(body.get("recurrence") or {})
+    rec = {"recurrence": _RECURRENCE_CRON,
+           "cronExpression": args.cron,
+           "info": (getattr(args, "recurrence_info", None)
+                    or src_rec.get("info") or f"cron: {args.cron}"),
+           "isEndDate": bool(src_rec.get("isEndDate"))}
+    tz = getattr(args, "timezone", None) or src_rec.get("timeZone")
+    if tz:
+        rec["timeZone"] = tz
+    # Only these two calendar fields survive: the activation window a cron may still carry.
+    if src_rec.get("startDate"):
+        rec["startDate"] = src_rec["startDate"]
+    if rec["isEndDate"] and src_rec.get("endDate"):
+        rec["endDate"] = src_rec["endDate"]
+    body["recurrence"] = rec
+    return body
+
+
+# Recurrences that read `recurrence.timeZone`: DAILY..YEARLY evaluate their weekday /
+# day-of-month / time-of-day rules on that zone's local clock, CRON evaluates its
+# expression there. ONCE / MINUTES / HOURS never read it. An absent zone means UTC; an id
+# the server cannot resolve fails the whole recurrence.
+_ZONED_RECURRENCES = {4, 5, 6, 7, _RECURRENCE_CRON}
+
+
+def _apply_timezone(body: dict, args) -> dict:
+    """Set --timezone on a calendar recurrence (the cron path already carries it).
+
+    Refuses it on a recurrence type that ignores the zone, rather than writing a key the
+    server silently drops."""
+    tz = getattr(args, "timezone", None)
+    if not tz or getattr(args, "cron", None):
+        return body
+    rec = body.get("recurrence")
+    kind = rec.get("recurrence") if isinstance(rec, dict) else None
+    if kind not in _ZONED_RECURRENCES:
+        raise errors.UsageError(
+            f"--timezone has no effect on recurrence type {kind!r}: only daily (4), weekly (5), "
+            f"monthly (6), yearly (7) and cron (8) schedules are evaluated in a time zone")
+    rec["timeZone"] = tz
+    return body
+
+
+def _payload_args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    p.add_argument("--payload", required=True,
+                   help="schedule as a JSON object (see PROCESIO-API-NOTES.md for the shape)")
+    p.add_argument("--cron",
+                   help="5-field crontab expression (min hour day month weekday); sets "
+                        "the recurrence to CRON (type 8) over the --payload. Preview it "
+                        "first with validate-crontab. BE rule (PRC-5406): 5 fields only "
+                        "(no seconds), @-macros like @daily are REJECTED, max 100 chars. "
+                        "The expression runs on --timezone's clock (UTC when omitted); "
+                        "startDate / endDate are always UTC.")
+    p.add_argument("--timezone",
+                   help="IANA timezone id (e.g. Europe/Bucharest) the recurrence runs in. "
+                        "Applies to cron and to daily / weekly / monthly / yearly "
+                        "recurrences, whose day and time rules follow that zone's local "
+                        "clock, DST included; absent means UTC")
+    p.add_argument("--recurrence-info", dest="recurrence_info",
+                   help="human-readable recurrence label (optional)")
+
+
+def create_schedule(client, args) -> dict:
+    body = _apply_timezone(_apply_cron(parse_json_arg(args.payload, "payload"), args), args)
+    return {"result": client.post("/api/Schedules", body)}
+
+
+def update_schedule(client, args) -> dict:
+    body = _apply_timezone(_apply_cron(parse_json_arg(args.payload, "payload"), args), args)
+    return {"result": client.put("/api/Schedules", body)}
+
+
+# -- crontab preview --------------------------------------------------------
+
+def _validate_crontab_args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    p.add_argument("--cron", required=True,
+                   help="5-field crontab expression to validate (min hour day month weekday)")
+    p.add_argument("--timezone", help="IANA timezone id (default server/UTC)")
+    p.add_argument("--count", type=int,
+                   help="how many upcoming occurrences to return (default 5, max 20)")
+    p.add_argument("--start-date", dest="start_date", help="ISO-8601 activation start (optional)")
+    p.add_argument("--end-date", dest="end_date", help="ISO-8601 activation end (optional)")
+
+
+def validate_crontab(client, args) -> dict:
+    body = {"cronExpression": args.cron, "timeZone": args.timezone,
+            "count": args.count, "startDate": args.start_date, "endDate": args.end_date}
+    body = {k: v for k, v in body.items() if v is not None}
+    return {"result": client.post("/api/Schedules/validate-crontab", body)}
+
+
+def delete_schedule(client, args) -> dict:
+    return {"result": client.delete(f"/api/Schedules/{args.id}")}
+
+
+# -- enable / disable -------------------------------------------------------
+
+def _status_args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    p.add_argument("--id", required=True, help="schedule id (scheduleId)")
+    p.add_argument("--active", required=True, choices=["true", "false"],
+                   help="true to enable the schedule, false to disable it")
+
+
+def set_schedule_status(client, args) -> dict:
+    # The API names the query flag `enable`; we expose it as --active per spec.
+    q = {"enable": args.active}
+    return {"result": client.patch(f"/api/Schedules/{args.id}/status", None, q)}
+
+
+# -- notifications ----------------------------------------------------------
+
+def _notif_id_args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    p.add_argument("--id", required=True, help="schedule id (scheduleId)")
+
+
+def get_schedule_notifications(client, args) -> dict:
+    return {"result": client.get(f"/api/Schedules/notifications/{args.id}")}
+
+
+def _notif_payload_args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    p.add_argument("--payload", required=True,
+                   help="notifications config as a JSON object")
+
+
+def set_schedule_notifications(client, args) -> dict:
+    body = parse_json_arg(args.payload, "payload")
+    return {"result": client.post("/api/Schedules/notifications", body)}
+
+
+# -- project schedules ------------------------------------------------------
+
+def _project_args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    p.add_argument("--id", required=True, help="project (process) id")
+
+
+def list_project_schedules(client, args) -> dict:
+    return {"result": client.get(f"/api/Projects/{args.id}/restricted/schedules")}
+
+
+ACTIONS = {
+    "list-schedules": ActionDef(
+        func=list_schedules, add_args=_list_args, needs_client=True,
+        description="List schedules (GET /api/Schedules).",
+    ),
+    "get-schedule": ActionDef(
+        func=get_schedule, add_args=_get_args, needs_client=True,
+        description="Get one schedule by id; use --redact-process-inputs for safe evidence.",
+    ),
+    "create-schedule": ActionDef(
+        func=create_schedule, add_args=_payload_args, needs_client=True,
+        description="Create a schedule (POST /api/Schedules) from a JSON --payload; "
+                    "--cron/--timezone sets a crontab recurrence.",
+    ),
+    "update-schedule": ActionDef(
+        func=update_schedule, add_args=_payload_args, needs_client=True,
+        description="Update a schedule (PUT /api/Schedules) from a JSON --payload; "
+                    "--cron/--timezone sets a crontab recurrence.",
+    ),
+    "validate-crontab": ActionDef(
+        func=validate_crontab, add_args=_validate_crontab_args, needs_client=True,
+        description="Preview a crontab expression's next occurrences "
+                    "(POST /api/Schedules/validate-crontab).",
+    ),
+    "delete-schedule": ActionDef(
+        func=delete_schedule, add_args=_id_args, needs_client=True,
+        description="Delete a schedule (DELETE /api/Schedules/{id}).",
+    ),
+    "set-schedule-status": ActionDef(
+        func=set_schedule_status, add_args=_status_args, needs_client=True,
+        description="Enable/disable a schedule (PATCH /api/Schedules/{id}/status --active true|false).",
+    ),
+    "get-schedule-notifications": ActionDef(
+        func=get_schedule_notifications, add_args=_notif_id_args, needs_client=True,
+        description="Get a schedule's notifications (GET /api/Schedules/notifications/{id}).",
+    ),
+    "set-schedule-notifications": ActionDef(
+        func=set_schedule_notifications, add_args=_notif_payload_args, needs_client=True,
+        description="Set a schedule's notifications (POST /api/Schedules/notifications) from a JSON --payload.",
+    ),
+    "list-project-schedules": ActionDef(
+        func=list_project_schedules, add_args=_project_args, needs_client=True,
+        description="List a project's schedules (GET /api/Projects/{id}/restricted/schedules).",
+    ),
+}

procesio_cli/tools/procesio/handlers/sqlactions.py

@@ -0,0 +1,232 @@
+"""SQL Server action hardening: convert inline `N'<%N%>'` string-substitution in Execute Query /
+Execute Command nodes (SQL-injection-prone, and the wrong action config) into the safe form —
+named `@params` bound via the `Parameters config tab`. See tools/procesio/PROCESIO-SQL-ACTIONS-NOTES.md.
+
+  sql-scan          list a process's SQL nodes with inline-vs-parameterized status (read-only)
+  sql-parameterize  convert one node (--node) or every inline node (--all) -> validate -> PUT
+                    (--dry-run converts + validates but does not PUT; an invalid flow is never PUT)
+  sql-convert       move one node between the Execute Command and Execute Query families, and
+                    optionally rebind its Output -> validate + flow-lint -> PUT. Needed whenever a
+                    procedure that ends in SELECT sits on a Command node: Command returns
+                    rows-affected, so the result set is discarded with no error to show for it.
+
+JSON in / JSON out; impure (live client). Thin, validated wrappers over GET/validate/PUT /api/Projects.
+"""
+from __future__ import annotations
+
+import argparse
+
+from tools.procesio.actiondef import ActionDef
+from tools.procesio.client import VARIABLES_ONLY
+from tools.procesio.errors import ProcesioAPIError, UsageError
+from tools.procesio.flowmodel import sqlparam
+from tools.procesio.handlers.common import add_profile_arg
+from tools.procesio.handlers.fevalidate import run_fe_validation, save_flow
+
+
+def _enabled(node: dict) -> bool:
+    """False if the node is disabled in the designer (so --all never touches a disabled node)."""
+    cd = node.get("customData") or {}
+    return not (node.get("isDisabled") or node.get("disabled") or cd.get("isDisabled"))
+
+
+def _fetch_flow(client, pid: str) -> dict:
+    flow = client.get(f"/api/Projects/{pid}")
+    return flow.get("flow") if isinstance(flow, dict) and "flow" in flow else flow
+
+
+def _validate(client, flow: dict):
+    """(is_valid, errors). Empty 200 == valid (mirrors process-validate)."""
+    try:
+        res = client.post("/api/Projects/validate", flow)
+    except ProcesioAPIError as e:
+        det = e.details if isinstance(e.details, dict) else {"body": e.details}
+        return False, det.get("body", det)
+    empty = (not res) or (isinstance(res, dict) and list(res.keys()) == ["raw_text"] and not res["raw_text"])
+    return (True, None) if empty else (False, res)
+
+
+def _lint(client, flow: dict) -> list[dict]:
+    """Designer-layer save-blockers the BE validator does not report (same oracle as flow-lint)."""
+    from tools.procesio.handlers.flowlint import _template_sidepanel_ids, lint_flow_dto
+
+    try:
+        tmpl_sp = _template_sidepanel_ids(client)
+    except Exception:  # noqa: BLE001 - catalog unreachable -> lint what does not need it
+        tmpl_sp = {}
+
+    def target_vars_of(fid: str) -> dict:
+        try:
+            r = client.get(f"/api/Projects/{fid}", VARIABLES_ONLY)
+            f = r.get("flow", r) if isinstance(r, dict) else r
+            return {v["id"]: v for v in f.get("variables") or []}
+        except Exception:  # noqa: BLE001 - unreadable target -> can't assert its contract
+            return {}
+    return lint_flow_dto(flow, tmpl_sp, target_vars_of)
+
+
+def sql_scan(client, args) -> dict:
+    flow = _fetch_flow(client, args.id)
+    return {"id": args.id, "title": flow.get("title"), "sql_nodes": sqlparam.scan(flow)}
+
+
+def sql_parameterize(client, args) -> dict:
+    if not args.node and not args.all:
+        raise UsageError("pass --node <label|id> to convert one node, or --all for every inline SQL node")
+    flow = _fetch_flow(client, args.id)
+    if args.all:
+        targets = [a for a in flow.get("actions") or []
+                   if sqlparam.is_sql_node(a) and sqlparam.is_inline(a) and _enabled(a)]
+    else:
+        n = sqlparam.find_node(flow, args.node)
+        if not n:
+            raise UsageError(f"node not found in process {args.id}: {args.node}")
+        targets = [n]
+
+    changes = []
+    for n in targets:
+        ok, msg = sqlparam.parameterize_node(n)
+        changes.append({"node": n.get("actionName"), "id": n.get("id"), "converted": ok, "msg": msg})
+    converted = [c for c in changes if c["converted"]]
+    result = {"id": args.id, "converted": len(converted), "changes": changes}
+    if not converted:
+        result["note"] = "nothing to convert (already parameterized or no inline SQL)"
+        return result
+
+    valid, errors = _validate(client, flow)
+    result["isValid"] = valid
+    if not valid:                      # never PUT an invalid flow
+        result["errors"] = errors
+        result["put"] = False
+        return result
+    fe = run_fe_validation(client, flow)
+    result["fe"] = fe
+    if args.dry_run:
+        result["isValid"] = bool(valid and fe["clean"])
+        result["put"] = False
+        result["dry_run"] = True
+        return result
+    # The mark is stamped from the FE+BE verdict and then re-read: the platform stores
+    # whatever the body carries and never computes this field, so passing the fetched
+    # value through would leave a corrected process marked broken.
+    saved = save_flow(client, flow, flow_id=args.id, valid=valid and fe["clean"])
+    result["isValid"] = saved["isValid"]
+    result["stamped"] = saved["stamped"]
+    if "readback_error" in saved:
+        result["readback_error"] = saved["readback_error"]
+    result["put"] = True
+    return result
+
+
+def _resolve_variable(flow: dict, key: str) -> str:
+    """A flow variable's id, from its id or its name. Ambiguity is an error, never a guess."""
+    variables = flow.get("variables") or []
+    if any(v.get("id") == key for v in variables):
+        return key
+    matches = [v for v in variables if v.get("name") == key]
+    if not matches:
+        known = ", ".join(sorted(str(v.get("name")) for v in variables))
+        raise UsageError(f"variable not found: {key} (process has: {known})")
+    if len(matches) > 1:
+        raise UsageError(f"variable name {key!r} is ambiguous - pass its id instead")
+    return matches[0]["id"]
+
+
+def sql_convert(client, args) -> dict:
+    target = sqlparam.EQ_TEMPLATE if args.to == "query" else sqlparam.EC_TEMPLATE
+    flow = _fetch_flow(client, args.id)
+    node = sqlparam.find_node(flow, args.node)
+    if not node:
+        raise UsageError(f"node not found in process {args.id}: {args.node}")
+
+    changed, msg = sqlparam.convert_family(node, target)
+    result = {"id": args.id, "node": node.get("actionName"), "node_id": node.get("id"),
+              "to": target, "converted": changed, "msg": msg}
+
+    if args.output_variable:
+        var_id = _resolve_variable(flow, args.output_variable)
+        rebound, rmsg = sqlparam.rebind_output(node, var_id)
+        result["output_rebound"] = rebound
+        result["output_msg"] = rmsg
+        changed = changed or rebound
+
+    if not changed:
+        result["note"] = "nothing to change"
+        result["put"] = False
+        return result
+
+    valid, errors = _validate(client, flow)
+    result["isValid"] = valid
+    if not valid:                      # never PUT an invalid flow
+        result["errors"] = errors
+        result["put"] = False
+        return result
+
+    # The BE validator does not see designer save-blockers, and "Execute Query with a null Output"
+    # is exactly one of them — the case this conversion is most likely to create.
+    problems = _lint(client, flow)
+    result["lint_clean"] = not problems
+    if problems:
+        result["lint_problems"] = problems
+        result["put"] = False
+        return result
+
+    fe = run_fe_validation(client, flow)
+    result["fe"] = fe
+    if args.dry_run:
+        result["isValid"] = bool(valid and fe["clean"])
+        result["put"] = False
+        result["dry_run"] = True
+        return result
+    # The mark is stamped from the FE+BE verdict and then re-read: the platform stores
+    # whatever the body carries and never computes this field, so passing the fetched
+    # value through would leave a corrected process marked broken.
+    saved = save_flow(client, flow, flow_id=args.id, valid=valid and fe["clean"])
+    result["isValid"] = saved["isValid"]
+    result["stamped"] = saved["stamped"]
+    if "readback_error" in saved:
+        result["readback_error"] = saved["readback_error"]
+    result["put"] = True
+    return result
+
+
+def _scan_args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    p.add_argument("--id", required=True, help="process (project) id")
+
+
+def _param_args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    p.add_argument("--id", required=True, help="process (project) id")
+    p.add_argument("--node", help="node actionName or id to convert")
+    p.add_argument("--all", action="store_true", help="convert every inline SQL node in the process")
+    p.add_argument("--dry-run", dest="dry_run", action="store_true",
+                   help="convert + validate but do not PUT")
+
+
+def _convert_args(p: argparse.ArgumentParser) -> None:
+    add_profile_arg(p)
+    p.add_argument("--id", required=True, help="process (project) id")
+    p.add_argument("--node", required=True, help="node actionName or id to convert")
+    p.add_argument("--to", required=True, choices=("query", "command"),
+                   help="target family: query (returns a result set) or command (returns rows affected)")
+    p.add_argument("--output-variable", dest="output_variable",
+                   help="flow variable name or id to bind the node's Output to")
+    p.add_argument("--dry-run", dest="dry_run", action="store_true",
+                   help="convert + validate + lint but do not PUT")
+
+
+ACTIONS = {
+    "sql-convert": ActionDef(
+        func=sql_convert, add_args=_convert_args, needs_client=True,
+        description=("Move one SQL node between the Execute Command and Execute Query families "
+                     "(--to) and optionally rebind its Output (--output-variable); validate + "
+                     "flow-lint then PUT (--dry-run to preview). A SELECT-ing procedure on a Command "
+                     "node discards its result set silently - this is the fix.")),
+    "sql-scan": ActionDef(
+        func=sql_scan, add_args=_scan_args, needs_client=True,
+        description="List a process's SQL Server actions (Execute Query/Command) with inline-vs-parameterized status."),
+    "sql-parameterize": ActionDef(
+        func=sql_parameterize, add_args=_param_args, needs_client=True,
+        description="Convert inline N'<%N%>' SQL nodes to safe named-@param binding (--node or --all); validate then PUT (--dry-run to preview)."),
+}