hexaqueue-cli 0.3.0__tar.gz → 0.5.0__tar.gz

{hexaqueue_cli-0.3.0 → hexaqueue_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexaqueue-cli
-Version: 0.3.0
+Version: 0.5.0
 Summary: Hexaqueue CLI - Modern developer and operator terminal interface
 Author: Richard West
 Author-email: Richard West <dopplereffect.us@gmail.com>
@@ -9,10 +9,10 @@ Requires-Dist: hexaqueue-core
 Requires-Dist: hexaqueue-server
 Requires-Dist: hexaqueue-worker
 Requires-Dist: hexaqueue-workflow
-Requires-Dist: hexastack-cli>=0.6.0
-Requires-Dist: hexastack-core>=0.6.0
-Requires-Dist: hexastack-cqrs>=0.6.0
-Requires-Dist: hexastack-grpc>=0.6.0
+Requires-Dist: hexastack-cli>=0.8.0
+Requires-Dist: hexastack-core>=0.8.0
+Requires-Dist: hexastack-cqrs>=0.8.0
+Requires-Dist: hexastack-grpc>=0.8.0
 Requires-Dist: pyyaml>=6.0.2
 Requires-Dist: rich>=13.8.0
 Requires-Dist: typer>=0.15.0
@@ -26,8 +26,13 @@ Description-Content-Type: text/markdown
 [![PyPI: hexaqueue-cli](https://img.shields.io/pypi/v/hexaqueue-cli.svg)](https://pypi.org/project/hexaqueue-cli/)
 [![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
 [![Coverage](https://codecov.io/github/TheTrueSCU/hexaqueue/graph/badge.svg?component=hexaqueue_cli)](https://codecov.io/github/TheTrueSCU/hexaqueue)
+[![Part of Hexaqueue](https://img.shields.io/badge/part%20of-hexaqueue-blue.svg)](https://dopplereffect.us/hexaqueue/)
+[![Built with Hexastack](https://img.shields.io/badge/built%20with-hexastack-blueviolet.svg)](https://dopplereffect.us/hexastack/)
+[![Governed by Hexaqual](https://img.shields.io/badge/governed%20by-hexaqual-10b981.svg)](https://dopplereffect.us/hexaqual/)
 [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../../LICENSE)
 
+> Part of the [**Hexaqueue Scheduler**](https://dopplereffect.us/hexaqueue/) · Built on [**Hexastack**](https://dopplereffect.us/hexastack/) · Governed by [**Hexaqual**](https://dopplereffect.us/hexaqual/).
+
 ---
 
 ## 🏗️ Architecture & Dependencies

{hexaqueue_cli-0.3.0 → hexaqueue_cli-0.5.0}/README.md

@@ -5,8 +5,13 @@
 [![PyPI: hexaqueue-cli](https://img.shields.io/pypi/v/hexaqueue-cli.svg)](https://pypi.org/project/hexaqueue-cli/)
 [![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
 [![Coverage](https://codecov.io/github/TheTrueSCU/hexaqueue/graph/badge.svg?component=hexaqueue_cli)](https://codecov.io/github/TheTrueSCU/hexaqueue)
+[![Part of Hexaqueue](https://img.shields.io/badge/part%20of-hexaqueue-blue.svg)](https://dopplereffect.us/hexaqueue/)
+[![Built with Hexastack](https://img.shields.io/badge/built%20with-hexastack-blueviolet.svg)](https://dopplereffect.us/hexastack/)
+[![Governed by Hexaqual](https://img.shields.io/badge/governed%20by-hexaqual-10b981.svg)](https://dopplereffect.us/hexaqual/)
 [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../../LICENSE)
 
+> Part of the [**Hexaqueue Scheduler**](https://dopplereffect.us/hexaqueue/) · Built on [**Hexastack**](https://dopplereffect.us/hexastack/) · Governed by [**Hexaqual**](https://dopplereffect.us/hexaqual/).
+
 ---
 
 ## 🏗️ Architecture & Dependencies

{hexaqueue_cli-0.3.0 → hexaqueue_cli-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hexaqueue-cli"
-version = "0.3.0"
+version = "0.5.0"
 description = "Hexaqueue CLI - Modern developer and operator terminal interface"
 readme = "README.md"
 license = "Apache-2.0"
@@ -10,10 +10,10 @@ dependencies = [
     "hexaqueue-server",
     "hexaqueue-worker",
     "hexaqueue-workflow",
-    "hexastack-cli>=0.6.0",
-    "hexastack-core>=0.6.0",
-    "hexastack-cqrs>=0.6.0",
-    "hexastack-grpc>=0.6.0",
+    "hexastack-cli>=0.8.0",
+    "hexastack-core>=0.8.0",
+    "hexastack-cqrs>=0.8.0",
+    "hexastack-grpc>=0.8.0",
     "pyyaml>=6.0.2",
     "rich>=13.8.0",
     "typer>=0.15.0",

{hexaqueue_cli-0.3.0 → hexaqueue_cli-0.5.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "hexaqueue-cli"
-version = "0.3.0"
+version = "0.5.0"
 description = "Hexaqueue CLI - Modern developer and operator terminal interface"
 readme = "README.md"
 license = "Apache-2.0"
@@ -13,10 +13,10 @@ dependencies = [
     "hexaqueue-server",
     "hexaqueue-worker",
     "hexaqueue-workflow",
-    "hexastack-cli>=0.6.0",
-    "hexastack-core>=0.6.0",
-    "hexastack-cqrs>=0.6.0",
-    "hexastack-grpc>=0.6.0",
+    "hexastack-cli>=0.8.0",
+    "hexastack-core>=0.8.0",
+    "hexastack-cqrs>=0.8.0",
+    "hexastack-grpc>=0.8.0",
     "pyyaml>=6.0.2",
     "rich>=13.8.0",
     "typer>=0.15.0",

hexaqueue_cli-0.5.0/src/hexaqueue_cli/adapters/local.py

@@ -0,0 +1,320 @@
+"""In-process local client adapter for hq CLI.
+
+Notes/Architectural Intent:
+    Implements ClientPort by routing directly to in-process session controller
+    and log stream port without network transport overhead.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from pathlib import Path
+from uuid import uuid4
+
+from hexaqueue_cli.domain.models import ClusterStatsReport
+from hexaqueue_cli.domain.session import LocalCliSession, get_default_session
+from hexaqueue_cli.ports.client import ClientPort
+from hexaqueue_core.domain.collateral import (
+    CollateralBundle,
+    CollateralKind,
+    CollateralState,
+    CollateralTier,
+)
+from hexaqueue_core.domain.exceptions import PermissionDeniedError
+from hexaqueue_core.domain.explainability import (
+    FairShareTreeReport,
+    SchedulingDecisionReport,
+)
+from hexaqueue_core.domain.job import JobSpec
+from hexaqueue_core.domain.run import RunSpec
+from hexaqueue_core.domain.suite import SuiteCompiler, SuiteSpec
+from hexaqueue_core.ports.logging import LogChunk
+from hexaqueue_server.domain.models import RunStatusReport, RunSubmission
+from hexaqueue_worker.domain.pty import PtySessionInfo, PtySessionRequest
+from hexaqueue_worker.domain.telemetry import NodeTelemetryPulse
+
+
+def _extract_job_owner(job: JobSpec) -> str:
+    """Extract owner tag or env from job specification."""
+    for tag in job.tags:
+        if tag.startswith("owner:"):
+            return tag.split(":", 1)[1]
+    return job.env.get("HEXAQUEUE_OWNER", "default")
+
+
+def _check_job_mutation_permission(
+    job: JobSpec, user_id: str, elevate: bool, action_name: str
+) -> None:
+    """Verify that caller has permission to mutate the job."""
+    owner = _extract_job_owner(job)
+    if owner != user_id and not elevate:
+        msg = (
+            f"Permission denied: You are not the owner of job '{job.id}' (owned by '{owner}'). "
+            f"To {action_name} this job, explicit administrative elevation (--admin / elevate=true) is required."
+        )
+        raise PermissionDeniedError(msg)
+
+
+class LocalClientAdapter(ClientPort):
+    """In-process local client adapter."""
+
+    def __init__(self, session: LocalCliSession | None = None) -> None:
+        self._session = session or get_default_session()
+
+    async def submit_run(self, submission: RunSubmission) -> RunStatusReport:
+        """Submit a pipeline run to local in-process controller."""
+        return await self._session.controller.submit_run(submission)
+
+    async def submit_suite(
+        self,
+        suite: SuiteSpec,
+        user_id: str = "default",
+        elevate: bool = False,
+    ) -> RunStatusReport:
+        """Submit a hierarchical suite pipeline run to local controller."""
+        compiler = SuiteCompiler()
+        result = compiler.compile(suite, run_id=suite.id)
+        run_spec = RunSpec(
+            id=suite.id,
+            name=suite.name or suite.id,
+            tags=[f"owner:{user_id}"],
+        )
+        dependencies = {
+            child_id: [dep.parent_job_id for dep in deps]
+            for child_id, deps in result.dependencies.items()
+        }
+        submission = RunSubmission(
+            run_spec=run_spec,
+            jobs=result.jobs,
+            dependencies=dependencies,
+        )
+        return await self._session.controller.submit_run(submission)
+
+    async def get_run_status(self, run_id: str) -> RunStatusReport:
+        """Get run status report from local in-process controller."""
+        return await self._session.controller.get_run_status(run_id)
+
+    async def get_job(self, job_id: str) -> JobSpec:
+        """Get job metadata from local in-process controller."""
+        return await self._session.controller.get_job(job_id)
+
+    async def list_jobs(self) -> list[JobSpec]:
+        """List all registered jobs across runs."""
+        return await self._session.controller.list_jobs()
+
+    async def cancel_run(
+        self, run_id: str, user_id: str = "default", elevate: bool = False
+    ) -> RunStatusReport:
+        """Cancel run in local in-process controller."""
+        if not elevate:
+            jobs = await self._session.controller.list_jobs()
+            run_jobs = [j for j in jobs if j.run_id == run_id]
+            for j in run_jobs:
+                _check_job_mutation_permission(j, user_id, elevate, "cancel run")
+        return await self._session.controller.cancel_run(run_id)
+
+    async def cancel_job(
+        self, job_id: str, user_id: str = "default", elevate: bool = False
+    ) -> JobSpec:
+        """Cancel an individual job."""
+        job = await self._session.controller.get_job(job_id)
+        _check_job_mutation_permission(job, user_id, elevate, "cancel")
+        return await self._session.controller.cancel_job(job_id)
+
+    async def hold_job(
+        self, job_id: str, user_id: str = "default", elevate: bool = False
+    ) -> JobSpec:
+        """Place an administrative hold on a job."""
+        job = await self._session.controller.get_job(job_id)
+        _check_job_mutation_permission(job, user_id, elevate, "hold")
+        return await self._session.controller.hold_job(job_id)
+
+    async def release_job(
+        self, job_id: str, user_id: str = "default", elevate: bool = False
+    ) -> JobSpec:
+        """Release an administrative hold on a job."""
+        job = await self._session.controller.get_job(job_id)
+        _check_job_mutation_permission(job, user_id, elevate, "release")
+        return await self._session.controller.release_job(job_id)
+
+    async def get_logs(self, job_id: str) -> list[LogChunk]:
+        """Fetch captured logs from in-memory stream adapter."""
+        return [
+            c async for c in self._session.log_stream.stream_logs(job_id, follow=False)
+        ]
+
+    async def stream_logs(
+        self, job_id: str, follow: bool = False, tail: int | None = None
+    ) -> AsyncIterator[LogChunk]:
+        """Stream logs for a job with optional real-time tail follow."""
+        async for chunk in self._session.log_stream.stream_logs(
+            job_id, follow=follow, tail=tail
+        ):
+            yield chunk
+
+    async def get_cluster_stats(self) -> ClusterStatsReport:
+        """Retrieve high-level cluster state and backlog statistics."""
+        from hexaqueue_core.domain.lifecycle import JobState
+
+        all_jobs = await self._session.controller.list_jobs()
+        running_cnt = sum(1 for j in all_jobs if j.state == JobState.RUNNING)
+        pending_cnt = sum(1 for j in all_jobs if j.state == JobState.PENDING)
+        blocked_cnt = sum(1 for j in all_jobs if j.state == JobState.BLOCKED)
+        completed_cnt = sum(
+            1
+            for j in all_jobs
+            if j.state == JobState.DONE and str(j.outcome) == "COMPLETED"
+        )
+        failed_cnt = sum(
+            1
+            for j in all_jobs
+            if j.state == JobState.DONE and str(j.outcome) != "COMPLETED"
+        )
+
+        total_runs = len(getattr(self._session.controller, "_runs", {}))
+        active_workers = 1 if getattr(self._session.worker, "_running", False) else 0
+
+        return ClusterStatsReport(
+            total_runs=total_runs,
+            total_jobs=len(all_jobs),
+            running_jobs=running_cnt,
+            pending_jobs=pending_cnt,
+            blocked_jobs=blocked_cnt,
+            completed_jobs=completed_cnt,
+            failed_jobs=failed_cnt,
+            active_workers=active_workers,
+        )
+
+    async def get_nodes(self) -> list[NodeTelemetryPulse]:
+        """Retrieve telemetry pulses for registered compute worker nodes."""
+        worker = self._session.worker
+        active_jobs = len(getattr(worker, "_active_jobs", set()))
+        worker_id = getattr(worker._config, "worker_id", "local-worker")
+        pulse = self._session.telemetry.collect_pulse(
+            worker_id=worker_id, active_jobs=active_jobs
+        )
+        return [pulse]
+
+    async def create_pty_session(
+        self, request: PtySessionRequest, job_owner: str = "default"
+    ) -> PtySessionInfo:
+        """Create an interactive terminal PTY session inside a running job."""
+        return await self._session.pty.create_session(request, job_owner=job_owner)
+
+    async def explain_job(
+        self,
+        job_id: str,
+        requesting_user: str = "default",
+        is_admin: bool = False,
+    ) -> SchedulingDecisionReport:
+        """Generate explainability report for a job in the local session."""
+        from datetime import UTC, datetime
+
+        from hexaqueue_core.domain.explainability import SchedulerExplainabilityEngine
+        from hexaqueue_core.domain.redaction import MultiTenantRedactionFilter
+        from hexaqueue_core.domain.scheduling import ResourceSlotPool
+
+        engine = SchedulerExplainabilityEngine()
+        redaction = MultiTenantRedactionFilter()
+        all_jobs = await self._session.controller.list_jobs()
+        pool = ResourceSlotPool(total_slots=4)
+        report = engine.explain_job(
+            job_id=job_id,
+            all_jobs=all_jobs,
+            pool=pool,
+            current_timestamp=datetime.now(UTC).timestamp(),
+        )
+        return redaction.redact_decision_report(
+            report, requesting_user=requesting_user, is_admin=is_admin
+        )
+
+    async def get_fairshare_tree(
+        self,
+        requesting_user: str = "default",
+        is_admin: bool = False,
+    ) -> FairShareTreeReport:
+        """Generate fair-share tree report for the local session."""
+        from datetime import UTC, datetime
+
+        from hexaqueue_core.domain.explainability import (
+            SchedulerExplainabilityEngine,
+        )
+        from hexaqueue_core.domain.redaction import MultiTenantRedactionFilter
+
+        engine = SchedulerExplainabilityEngine()
+        redaction = MultiTenantRedactionFilter()
+        report = engine.explain_fairshare(datetime.now(UTC).timestamp())
+        return redaction.redact_fairshare_tree(
+            report, requesting_user=requesting_user, is_admin=is_admin
+        )
+
+    async def register_collateral(
+        self,
+        name: str,
+        size_bytes: int,
+        checksum_sha256: str,
+        tier: CollateralTier = CollateralTier.TEMPORARY,
+        kind: CollateralKind = CollateralKind.BUNDLE,
+        target_path: str = "",
+        user_id: str = "default",
+        elevate: bool = False,
+    ) -> CollateralBundle:
+        """Register and stage a collateral bundle."""
+        checksum = (
+            checksum_sha256 if len(checksum_sha256) == 64 else checksum_sha256.zfill(64)
+        )
+        staging_uri = f"memory://staging/collateral/{name}"
+        if target_path and Path(target_path).is_file():
+            if ".." in name or "/" in name or "\\" in name or Path(name).is_absolute():
+                raise ValueError(
+                    f"Collateral name '{name}' contains illegal path components."
+                )
+            content = Path(target_path).read_bytes()
+            alloc = await self._session.storage.allocate_scratch(
+                job_id="collateral", size_mb=max(1, len(content) // (1024 * 1024))
+            )
+            mount_path = Path(alloc.mount_path).resolve()
+            dest = (mount_path / name).resolve()
+            if not dest.is_relative_to(mount_path):
+                raise ValueError("Path traversal detected in collateral destination.")
+            dest.write_bytes(content)
+            staging_uri = f"file://{dest}"
+        return CollateralBundle(
+            id=f"col-{uuid4().hex[:8]}",
+            job_id="global",
+            filename=name,
+            size_bytes=size_bytes,
+            sha256_checksum=checksum,
+            tier=tier,
+            kind=kind,
+            state=CollateralState.REGISTERED,
+            staging_uri=staging_uri,
+        )
+
+    async def create_bastion_session(
+        self,
+        node_id: str,
+        session_id: str = "",
+        user_id: str = "default",
+        elevate: bool = False,
+    ) -> PtySessionInfo:
+        """Create administrative bastion session (requires elevation)."""
+        if not elevate:
+            msg = (
+                f"Permission denied: Bastion shell access on node '{node_id}' "
+                "requires explicit administrative elevation (--admin)."
+            )
+            raise PermissionDeniedError(msg)
+        req = PtySessionRequest(
+            session_id=session_id or f"bastion-{uuid4().hex[:8]}",
+            job_id=f"bastion-{node_id}",
+            user_id=user_id,
+            roles=["admin", "operator"],
+            command=["/bin/sh"],
+        )
+        return await self._session.pty.create_session(req, job_owner=user_id)
+
+
+__all__ = [
+    "LocalClientAdapter",
+]