iowap-node 2.3.20__py3-none-any.whl

nodes/common/cli/cli_task.py

@@ -0,0 +1,191 @@
+"""CLI task subcommands — submit / result / note / wait (T-117 split).
+
+Handler signatures are plain ``(client, args) -> int``; the
+``node_cli.with_client`` decorator is applied at parser-registration time
+in the facade, so this module never imports ``node_cli`` (avoids a
+circular import and keeps the ``cli.RelayClient`` monkeypatch working).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from typing import Any
+
+import httpx
+
+from nodes.common.relay_client import RelayClient
+
+
+def _parse_stage_arg(stage: str) -> tuple[str, dict[str, Any]]:
+    """Parse ``<cap>:<json_payload>`` into (capability, payload)."""
+    if ":" not in stage:
+        raise SystemExit(f"invalid --stage value {stage!r}; expected <capability>:<json-payload>")
+    cap, _, payload_str = stage.partition(":")
+    cap = cap.strip()
+    if not cap:
+        raise SystemExit(f"invalid --stage value {stage!r}; empty capability")
+    try:
+        payload = json.loads(payload_str) if payload_str.strip() else {}
+    except json.JSONDecodeError as exc:
+        raise SystemExit(f"invalid --stage payload JSON: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise SystemExit("--stage payload must be a JSON object")
+    return cap, payload
+
+
+def _cmd_task_submit(client: RelayClient, args) -> int:
+    cap, payload = _parse_stage_arg(args.stage)
+    resp = client.submit_simple_task(
+        cap,
+        payload,
+        name=args.name or "",
+        priority=args.priority,
+        owner_node_id=args.owner,
+    )
+    if args.json:
+        print(json.dumps(resp, default=str))
+        return 0
+    print(json.dumps(resp, indent=2, default=str))
+    return 0
+
+
+def _cmd_task_result(client: RelayClient, args) -> int:
+    data = client.get_task(args.task_id)
+    if "error" in data:
+        print(f"Task {args.task_id}: {data['error']}", file=sys.stderr)
+        return 1
+    if args.json:
+        print(json.dumps(data, default=str))
+        return 0
+    _print_task_result(data)
+    return 0
+
+
+def _cmd_task_note(client: RelayClient, args) -> int:
+    """node-cli task note <task_id> <message> — append a note to a task.
+
+    T-179 Task 4: ``task_id`` falls back to ``RELAY_TASK_ID`` (set by
+    handler_runner for every handler) — handler scripts can post notes
+    without repeating their task ID. Explicit argument wins over env.
+    Without any ID → stderr message + exit 1.
+    """
+    task_id = args.task_id or os.environ.get("RELAY_TASK_ID")
+    if not task_id:
+        print(
+            "note: no task_id and no RELAY_TASK_ID in env",
+            file=sys.stderr,
+        )
+        return 1
+    try:
+        data = client.add_task_note(task_id, args.message)
+    except httpx.HTTPStatusError as exc:
+        if exc.response.status_code == 404:
+            print(f"Task {task_id} not found", file=sys.stderr)
+            return 1
+        print(f"Error: {exc.response.status_code} {exc.response.text}", file=sys.stderr)
+        return 1
+    if args.json:
+        print(json.dumps(data, default=str))
+        return 0
+    print(f"✅ Note added to task {data.get('task_id', task_id)}")
+    print(f"   {data.get('message', '')} ({data.get('created_at', '')})")
+    return 0
+
+
+def _cmd_task_wait(client: RelayClient, args) -> int:
+    task_id = args.task_id
+    interval = max(1, args.interval)
+
+    last_note_count = 0
+    while True:
+        data = client.get_task(task_id)
+        if "error" in data:
+            print(f"Task {task_id}: {data['error']}", file=sys.stderr)
+            return 1
+
+        task = data.get("task", {})
+        status = task.get("status", "unknown")
+
+        # T-052: surface any new notes that arrived since the last poll.
+        notes = data.get("notes", [])
+        if len(notes) > last_note_count:
+            for n in notes[last_note_count:]:
+                print(f"\n💬 [{n.get('node_id', '?')}] {n.get('message', '')} ({n.get('created_at', '?')})")
+            last_note_count = len(notes)
+
+        if status in ("completed", "failed", "timed_out"):
+            if args.json:
+                print(json.dumps(data, default=str))
+                return 0 if status == "completed" else 1
+            print(f"\n✅ Task {task_id} — {status}\n")
+            _print_task_result(data)
+            return 0 if status == "completed" else 1
+
+        # Show spinner / progress
+        stages = data.get("stages", [])
+        done = sum(1 for s in stages if s.get("status") == "completed")
+        total = len(stages)
+        print(f"\r⏳ {status} — {done}/{total} stages completed...", end="", flush=True)
+        time.sleep(interval)
+
+
+def _print_task_result(data: dict[str, Any]) -> None:
+    task = data.get("task", {})
+    stages = data.get("stages", [])
+    artifacts = data.get("artifacts", [])
+    notes = data.get("notes", [])
+
+    print(f"  Task:    {task.get('task_name', '?')} ({task.get('task_id', '?')})")
+    print(f"  Status:  {task.get('status', '?')}")
+    print(f"  Created: {task.get('created_at', '?')}")
+    print(f"  Updated: {task.get('updated_at', '?')}")
+    print()
+
+    if stages:
+        print("  Stages:")
+        for s in stages:
+            status_icon = "✅" if s.get("status") == "completed" else "⏳" if s.get("status") == "claimed" else "⬜"
+            result_str = ""
+            if s.get("result"):
+                result_str = f"  result={json.dumps(s['result'])}"
+            print(f"    {status_icon} {s.get('stage_name','?')} [{s.get('capability','?')}] — {s.get('status','?')}{result_str}")
+            # T-053: show resolved capability metadata when present.
+            cd = s.get("capability_details")
+            if cd:
+                if cd.get("description"):
+                    print(f"       description: {cd['description']}")
+                if cd.get("type"):
+                    print(f"       type:        {cd['type']}")
+                if cd.get("input_schema"):
+                    print(f"       input_schema: {json.dumps(cd['input_schema'])}")
+            # Surface handler diagnostics (exit code, stdout size,
+            # stderr snippet) so callers can debug empty responses
+            # without downloading artifacts. Populated by
+            # handler_runner.run_handler() on success (exit 0).
+            handler_info = (s.get("result") or {}).get("_handler")
+            if handler_info:
+                stderr_snippet = (handler_info.get("stderr") or "")[:200]
+                print(
+                    f"      [handler] exit={handler_info.get('exit_code')} "
+                    f"stdout={handler_info.get('stdout_length','?')}B "
+                    f"stderr={stderr_snippet!r}"
+                )
+        print()
+
+    if artifacts:
+        print("  Artifacts:")
+        for a in artifacts:
+            size = a.get("size_bytes", 0)
+            size_str = f"{size/1024:.0f} KB" if size < 1024*1024 else f"{size/1024/1024:.1f} MB"
+            print(f"    📄 {a.get('name','?')} ({a.get('artifact_id','?')}) — {size_str}")
+    else:
+        print("  (no artifacts linked to this task)")
+
+    if notes:
+        print()
+        print(f"  Notes ({len(notes)}):")
+        for n in notes:
+            print(f"    💬 [{n.get('node_id', '?')}] {n.get('message', '')} ({n.get('created_at', '?')})")

nodes/common/cli/cli_update.py

@@ -0,0 +1,48 @@
+"""CLI update subcommands — check / apply (wheel-based, successor of T-062).
+
+The git-based update path was removed: wheel-deployed nodes have no git
+checkout, and a pull would never touch the package running from
+site-packages. The source of truth is now the newest ``wheel-vX.Y.Z``
+release on GitHub (iowap-org/iowap-node); the installed distribution
+version (importlib.metadata) is compared against it.
+"""
+
+from __future__ import annotations
+
+import json
+
+from nodes.common.node_utils import apply_wheel_update, check_wheel_updates
+from nodes.common.relay_client import _setup_logging
+
+
+def _cmd_update_check(args) -> int:
+    """node-cli update check — compare installed version vs. newest release."""
+    _setup_logging("ERROR" if args.json else args.log_level)
+    info = check_wheel_updates()
+    if args.json:
+        print(json.dumps(info, default=str))
+        return 0
+    print(f"Local version:  {info.get('local_version') or '-'}")
+    print(f"Latest release: {info.get('latest_version') or '-'} ({info.get('tag') or 'no wheel release'})")
+    if info.get("error"):
+        print(f"Error:          {info['error']}")
+        return 1
+    if info.get("update_available"):
+        print("Status:         update available")
+        return 0
+    print("Status:         up to date")
+    return 0
+
+
+def _cmd_update_apply(args) -> int:
+    """node-cli update apply — download wheel, pip reinstall, restart unit."""
+    _setup_logging("ERROR" if args.json else args.log_level)
+    result = apply_wheel_update(service_unit=args.service_unit, restart_command=args.restart_command)
+    if args.json:
+        print(json.dumps(result, default=str))
+        return 0 if result.get("success") else 1
+    print(f"Before: {result.get('before_version') or '-'}")
+    print(f"After:  {result.get('after_version') or '-'}")
+    print(f"Restarted: {'yes' if result.get('restarted') else 'no'}")
+    print(f"Result:  {result.get('message')}")
+    return 0 if result.get("success") else 1

nodes/common/envelope.py

@@ -0,0 +1,168 @@
+"""T-179: Envelope format v1 for handler primitives (put/get).
+
+Contract: the sending node-cli replaces a payload field with the
+envelope; the receiving node-cli recognizes ``__iowap_ref__`` and
+resolves it. Scripts see only a path in / a path out.
+
+FROZEN (Phase 1, T-179) — every signature in this module is immutable
+for Phase 2 (scaffold) and Phase 3 (integrate). Field semantics v1:
+
+* ``v``           — version, must be exactly 1 (anything else: hard
+                    error; forward-compat never silently breaks old
+                    receivers).
+* ``src``         — ``inline`` | ``artifact`` | ``bridge``; unknown → error.
+* ``filename``    — display name inside the envelope (not trustworthy
+                    as a path — receivers sanitize).
+* ``size_bytes``  — inline: exact byte length; otherwise 0 (placeholder,
+                    the size only becomes fixed after resolution).
+* ``sha256``      — inline: always set (computed); otherwise optional; the
+                    sender may know it when it saw the bytes.
+* ``data_base64`` — only for src=inline.
+* ``artifact_id`` — only for src=artifact.
+* ``storage_ref`` — only for src=bridge (``{type, id, ...}``).
+
+The envelope replaces the payload field completely (no wrapper object).
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from typing import Any
+
+ENVELOPE_KEY = "__iowap_ref__"
+SUPPORTED_VERSION = 1
+SUPPORTED_SOURCES = ("inline", "artifact", "bridge")
+
+
+class EnvelopeError(ValueError):
+    """Envelope missing, foreign, or carrying an unsupported format."""
+
+
+def make_envelope(
+    *,
+    src: str,
+    filename: str,
+    data: bytes | None = None,
+    artifact_id: str | None = None,
+    storage_ref: dict | None = None,
+    sha256: str | None = None,
+    size_bytes: int | None = None,
+) -> dict[str, Any]:
+    """Build a v1 envelope. ``data`` only for src=inline (base64-encoded).
+
+    Raise: EnvelopeError on unknown ``src`` or a contradicting field
+    combination (inline+artifact_id, inline without data, bridge+data …).
+    Fail fast at the producer — an invalid envelope should never leave
+    the repo, so the receiver only sees transport-related errors.
+
+    ``size_bytes``: actual file size for artifact/bridge (there the
+    ``data`` is not inside the envelope). Default ``0`` — the original
+    T-166 delivery erroneously always had ``0`` for non-inline
+    (bugfix after the live E2E). Negative or smaller than a set
+    ``data`` length → EnvelopeError.
+    """
+    if not isinstance(size_bytes, int) or isinstance(size_bytes, bool):
+        if size_bytes is not None:
+            raise EnvelopeError("size_bytes must be an int")
+        size_bytes = None
+    if size_bytes is not None and size_bytes < 0:
+        raise EnvelopeError("size_bytes must be >= 0")
+    if src not in SUPPORTED_SOURCES:
+        raise EnvelopeError(f"unsupported src {src!r}")
+    if not filename:
+        raise EnvelopeError("envelope requires a filename")
+    is_inline = src == "inline"
+    if is_inline and data is None:
+        raise EnvelopeError("inline envelope requires data")
+    if not is_inline and data is not None:
+        raise EnvelopeError(f"{src!r} envelope must not carry data")
+    if src == "artifact" and not artifact_id:
+        raise EnvelopeError("artifact envelope requires artifact_id")
+    if src == "bridge" and storage_ref is None:
+        raise EnvelopeError("bridge envelope requires storage_ref")
+    if is_inline and artifact_id is not None:
+        raise EnvelopeError("inline envelope must not carry artifact_id")
+    if src == "bridge" and artifact_id is not None:
+        raise EnvelopeError("bridge envelope must not carry artifact_id")
+
+    ref: dict[str, Any] = {
+        "v": SUPPORTED_VERSION,
+        "src": src,
+        "filename": filename,
+        # inline: always derived from data; artifact/bridge: explicit
+        # size (the file is not inside the envelope), default 0.
+        "size_bytes": len(data) if data is not None else (
+            size_bytes if size_bytes is not None else 0
+        ),
+    }
+    if data is not None:
+        ref["data_base64"] = base64.b64encode(data).decode("ascii")
+    # T-166 (F8): sha256 in the envelope — inline computes it from the
+    # data, bridge/artifact carry the sender hash explicitly (F8
+    # verification at the receiver even without inline payload).
+    if sha256 is not None:
+        ref["sha256"] = sha256
+    elif data is not None:
+        ref["sha256"] = hashlib.sha256(data).hexdigest()
+    if artifact_id is not None:
+        ref["artifact_id"] = artifact_id
+    if storage_ref is not None:
+        ref["storage_ref"] = storage_ref
+    return {ENVELOPE_KEY: ref}
+
+
+def parse_envelope(envelope: dict[str, Any]) -> tuple[str, Any]:
+    """Validate an envelope, return ``(src, raw reference)``.
+
+    inline   → second value is the decoded bytes (``bytes``)
+    artifact → second value is the artifact_id (``str``)
+    bridge   → second value is the storage_ref dict
+
+    Raise: EnvelopeError on a missing/contradicting envelope —
+    unknown ``v`` or unknown ``src`` breaks the receiver loudly
+    (forward-compat: new modes never break old receivers silently).
+    """
+    if not isinstance(envelope, dict) or ENVELOPE_KEY not in envelope:
+        raise EnvelopeError(f"no {ENVELOPE_KEY} key — not an envelope")
+    ref = envelope[ENVELOPE_KEY]
+    if not isinstance(ref, dict):
+        raise EnvelopeError("envelope payload must be an object")
+    version = ref.get("v")
+    if version != SUPPORTED_VERSION:
+        raise EnvelopeError(f"unsupported envelope version {version!r}")
+    src = ref.get("src")
+    if src not in SUPPORTED_SOURCES:
+        raise EnvelopeError(f"unsupported envelope src {src!r}")
+    if src == "inline":
+        raw = ref.get("data_base64")
+        if not raw:
+            raise EnvelopeError("inline envelope without data_base64")
+        try:
+            return src, base64.b64decode(raw)
+        except (ValueError, TypeError) as exc:
+            # binascii.Error is a ValueError subclass.
+            raise EnvelopeError(f"invalid base64 in inline envelope: {exc}") from exc
+    if src == "artifact":
+        artifact_id = ref.get("artifact_id")
+        if not artifact_id:
+            raise EnvelopeError("artifact envelope without artifact_id")
+        return src, artifact_id
+    storage_ref = ref.get("storage_ref")
+    if not isinstance(storage_ref, dict):
+        raise EnvelopeError("bridge envelope without storage_ref")
+    return src, storage_ref
+
+
+def is_envelope(value: Any) -> bool:
+    """True if ``value`` is a dict with the ``__iowap_ref__`` key.
+
+    Pure shape check without validation — for "is this payload field an
+    envelope?" decisions on the receiver side.
+    """
+    return isinstance(value, dict) and ENVELOPE_KEY in value
+
+
+def dump(envelope: dict[str, Any]) -> str:
+    """Serialize an envelope as compact JSON (no separator lines)."""
+    return json.dumps(envelope, separators=(",", ":"))