relayctl 0.1.0__py3-none-any.whl

relayctl/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

relayctl/_remote_runner.py

@@ -0,0 +1,254 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import TypedDict
+
+
+class ShellEnvEntryPayload(TypedDict):
+    name: str
+    value: str
+
+
+class StagedPathPayload(TypedDict):
+    slot: int
+    path: str
+
+
+class _RemoteRunnerManifestOptionalPayload(TypedDict, total=False):
+    mode: str
+    shell_text: str
+    shell_env: list[ShellEnvEntryPayload]
+    pullback_report_path: str
+    staged_paths: list[StagedPathPayload]
+
+
+class RemoteRunnerManifestPayload(_RemoteRunnerManifestOptionalPayload):
+    argv: list[str]
+    cwd: str
+
+
+class PullbackStatePayload(TypedDict):
+    slot: int
+    changed: bool
+    exists: bool
+    is_dir: bool
+
+
+class PullbackReportPayload(TypedDict):
+    staged: list[PullbackStatePayload]
+
+
+REMOTE_RUNNER_TIMEOUT_SECONDS = 3600.0
+
+
+def _expand_home(value: str) -> str:
+    if value.startswith("~/"):
+        return os.path.expanduser(value)
+    return value
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    if len(args) != 1:
+        raise SystemExit("Usage: remote-runner.py <manifest-path>")
+
+    manifest_path = Path(args[0]).expanduser()
+    try:
+        manifest = _parse_remote_runner_manifest(
+            json.loads(manifest_path.read_text(encoding="utf-8"))
+        )
+    except ValueError as exc:
+        raise SystemExit(str(exc)) from exc
+
+    manifest_cwd = _expand_home(manifest["cwd"])
+    mode = manifest.get("mode", "argv")
+    shell_text = manifest.get("shell_text")
+
+    report_path_raw = manifest.get("pullback_report_path")
+    report_path = (
+        Path(_expand_home(report_path_raw)) if report_path_raw is not None else None
+    )
+
+    staged_paths = [
+        (entry["slot"], Path(_expand_home(entry["path"])))
+        for entry in manifest.get("staged_paths", [])
+    ]
+
+    shell_env = [
+        (entry["name"], _expand_home(entry["value"]))
+        for entry in manifest.get("shell_env", [])
+    ]
+
+    staged_before = {slot: _snapshot_any(path) for slot, path in staged_paths}
+
+    completed = _run_manifest_command(
+        mode=mode,
+        manifest_cwd=manifest_cwd,
+        shell_text=shell_text,
+        shell_env=shell_env,
+        argv=tuple(manifest["argv"]),
+    )
+
+    if report_path is not None:
+        staged_entries: list[PullbackStatePayload] = []
+        for slot, stage_path in staged_paths:
+            after_snapshot = _snapshot_any(stage_path)
+            before_snapshot = staged_before.get(slot, {"kind": "missing"})
+            staged_entries.append(
+                PullbackStatePayload(
+                    slot=slot,
+                    changed=before_snapshot != after_snapshot,
+                    exists=after_snapshot.get("kind") != "missing",
+                    is_dir=after_snapshot.get("kind") == "dir",
+                )
+            )
+        report_payload = PullbackReportPayload(staged=staged_entries)
+        report_path.parent.mkdir(parents=True, exist_ok=True)
+        report_path.write_text(
+            json.dumps(report_payload, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+
+    return completed.returncode
+
+
+def _parse_remote_runner_manifest(payload: object) -> RemoteRunnerManifestPayload:
+    if not isinstance(payload, dict):
+        raise ValueError("remote runner manifest payload must be an object")
+    cwd = payload.get("cwd")
+    if not isinstance(cwd, str):
+        raise ValueError("Invalid manifest cwd payload")
+
+    mode = payload.get("mode", "argv")
+    if not isinstance(mode, str):
+        raise ValueError("Invalid manifest mode payload")
+
+    shell_text = payload.get("shell_text")
+    if shell_text is not None and not isinstance(shell_text, str):
+        raise ValueError("Invalid shell manifest payload")
+
+    argv = payload.get("argv", [])
+    if not isinstance(argv, list) or not all(isinstance(token, str) for token in argv):
+        raise ValueError("Invalid argv manifest payload")
+
+    shell_env_raw = payload.get("shell_env", [])
+    if not isinstance(shell_env_raw, list):
+        raise ValueError("Invalid shell environment payload")
+    shell_env: list[ShellEnvEntryPayload] = []
+    for entry in shell_env_raw:
+        if not isinstance(entry, dict):
+            raise ValueError("Invalid shell environment payload")
+        name = entry.get("name")
+        value = entry.get("value")
+        if not isinstance(name, str) or not isinstance(value, str):
+            raise ValueError("Invalid shell environment payload")
+        shell_env.append(ShellEnvEntryPayload(name=name, value=value))
+
+    pullback_report_path = payload.get("pullback_report_path")
+    if pullback_report_path is not None and not isinstance(pullback_report_path, str):
+        raise ValueError("Invalid pullback report payload")
+
+    staged_paths_raw = payload.get("staged_paths", [])
+    if not isinstance(staged_paths_raw, list):
+        raise ValueError("Invalid staged paths payload")
+    staged_paths: list[StagedPathPayload] = []
+    for entry in staged_paths_raw:
+        if not isinstance(entry, dict):
+            raise ValueError("Invalid staged paths payload")
+        slot = entry.get("slot")
+        path = entry.get("path")
+        if type(slot) is not int or not isinstance(path, str):
+            raise ValueError("Invalid staged paths payload")
+        staged_paths.append(StagedPathPayload(slot=slot, path=path))
+
+    manifest = RemoteRunnerManifestPayload(argv=list(argv), cwd=cwd)
+    if mode != "argv":
+        manifest["mode"] = mode
+    if shell_text is not None:
+        manifest["shell_text"] = shell_text
+    if shell_env:
+        manifest["shell_env"] = shell_env
+    if pullback_report_path is not None:
+        manifest["pullback_report_path"] = pullback_report_path
+    if staged_paths:
+        manifest["staged_paths"] = staged_paths
+    return manifest
+
+
+def _run_manifest_command(
+    *,
+    mode: object,
+    manifest_cwd: str,
+    shell_text: object,
+    shell_env: list[tuple[str, str]],
+    argv: tuple[str, ...],
+) -> subprocess.CompletedProcess[bytes] | subprocess.CompletedProcess[str]:
+    env = os.environ.copy()
+    for name, value in shell_env:
+        env[name] = value
+
+    if mode == "shell":
+        if not isinstance(shell_text, str):
+            raise SystemExit("Invalid shell manifest payload")
+        return subprocess.run(
+            ["/bin/sh", "-c", shell_text],
+            cwd=manifest_cwd,
+            env=env,
+            check=False,
+            timeout=REMOTE_RUNNER_TIMEOUT_SECONDS,
+        )
+
+    manifest_argv = [_expand_home(token) for token in argv]
+    return subprocess.run(
+        manifest_argv,
+        cwd=manifest_cwd,
+        env=env,
+        check=False,
+        timeout=REMOTE_RUNNER_TIMEOUT_SECONDS,
+    )
+
+
+def _snapshot_any(path: Path) -> dict[str, object]:
+    if not path.exists():
+        return {"kind": "missing"}
+    if path.is_file():
+        return {"kind": "file", "digest": _hash_file(path)}
+    if path.is_dir():
+        return {"kind": "dir", "entries": _snapshot_tree(path)}
+    return {"kind": "other"}
+
+
+def _snapshot_tree(path: Path | None) -> dict[str, str]:
+    if path is None or not path.exists() or not path.is_dir():
+        return {}
+
+    snapshot: dict[str, str] = {}
+    for child in sorted(path.rglob("*"), key=lambda value: value.as_posix()):
+        rel = child.relative_to(path).as_posix()
+        if child.is_file():
+            snapshot[rel] = f"file:{_hash_file(child)}"
+        elif child.is_dir():
+            snapshot[rel] = "dir"
+        else:
+            snapshot[rel] = "other"
+    return snapshot
+
+
+def _hash_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        while True:
+            chunk = handle.read(8192)
+            if not chunk:
+                break
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

relayctl/argv_paths.py

@@ -0,0 +1,300 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from pathlib import Path, PurePosixPath
+import re
+
+from relayctl.root import logical_absolute_path, logical_current_directory
+from relayctl.workspace import RemoteLayout
+
+
+class PathRewriteError(ValueError):
+    pass
+
+
+class SymlinkEscapeError(PathRewriteError):
+    pass
+
+
+class ExplicitStagePathError(PathRewriteError):
+    pass
+
+
+@dataclass(frozen=True)
+class ClassifiedPathToken:
+    original: str
+    kind: str
+    local_path: Path | None = None
+    relative_path: PurePosixPath | None = None
+    rewritten_token: str | None = None
+
+
+@dataclass(frozen=True)
+class ExternalStagePath:
+    slot: int
+    local_path: Path
+    remote_path: PurePosixPath
+
+
+@dataclass(frozen=True)
+class RewrittenArgv:
+    argv: tuple[str, ...]
+    staged_paths: tuple[ExternalStagePath, ...]
+
+
+def _plan_stage_path(
+    local_path: Path,
+    *,
+    layout: RemoteLayout,
+    planned: list[ExternalStagePath],
+    stage_slots: dict[Path, ExternalStagePath],
+) -> ExternalStagePath:
+    stage_path = stage_slots.get(local_path)
+    if stage_path is not None:
+        return stage_path
+
+    slot = len(planned) + 1
+    stage_path = ExternalStagePath(
+        slot=slot,
+        local_path=local_path,
+        remote_path=layout.run_stage_dir / str(slot) / _stage_basename(local_path),
+    )
+    stage_slots[local_path] = stage_path
+    planned.append(stage_path)
+    return stage_path
+
+
+def classify_path_token(
+    token: str,
+    *,
+    local_root: Path,
+    cwd: Path | None = None,
+) -> ClassifiedPathToken:
+    if _is_attached_or_value_form(token):
+        return ClassifiedPathToken(original=token, kind="unchanged")
+
+    label, labeled_path = _split_path_label(token)
+    if label not in {None, "local", "remote"}:
+        raise PathRewriteError(
+            f"Unsupported path label '{label}:' in token: {token}. "
+            "Use local:PATH or remote:PATH"
+        )
+
+    if label == "remote":
+        return ClassifiedPathToken(
+            original=token,
+            kind="remote_literal",
+            rewritten_token=labeled_path,
+        )
+
+    local_token = labeled_path if label == "local" else token
+
+    base_cwd = (
+        logical_current_directory() if cwd is None else logical_absolute_path(cwd)
+    )
+    candidate = Path(local_token).expanduser()
+    if not candidate.is_absolute():
+        candidate = base_cwd / candidate
+
+    absolute_candidate = _lexical_normalize(
+        logical_absolute_path(candidate, base=base_cwd)
+    )
+    logical_root = _lexical_normalize(logical_absolute_path(local_root, base=base_cwd))
+
+    if not absolute_candidate.exists():
+        logical_relative = _relative_to(absolute_candidate, logical_root)
+        if logical_relative is None:
+            raise PathRewriteError(
+                f"Absolute local path does not exist: {local_token}. "
+                f"If this path already exists on the remote host, use remote:{local_token}"
+            )
+        return ClassifiedPathToken(
+            original=token,
+            kind="in_root",
+            local_path=absolute_candidate,
+            relative_path=PurePosixPath(*logical_relative.parts),
+        )
+
+    resolved_root = logical_root.resolve(strict=True)
+    resolved_candidate = absolute_candidate.resolve(strict=True)
+
+    logical_relative = _relative_to(absolute_candidate, logical_root)
+    if logical_relative is not None:
+        resolved_relative = _relative_to(resolved_candidate, resolved_root)
+        if resolved_relative is None:
+            raise SymlinkEscapeError(
+                f"Path escapes the project root through a symlink: {absolute_candidate}"
+            )
+        return ClassifiedPathToken(
+            original=token,
+            kind="in_root",
+            local_path=absolute_candidate,
+            relative_path=PurePosixPath(*resolved_relative.parts),
+        )
+
+    resolved_relative = _relative_to(resolved_candidate, resolved_root)
+    if resolved_relative is not None:
+        return ClassifiedPathToken(
+            original=token,
+            kind="in_root",
+            local_path=absolute_candidate,
+            relative_path=PurePosixPath(*resolved_relative.parts),
+        )
+
+    return ClassifiedPathToken(
+        original=token,
+        kind="external",
+        local_path=absolute_candidate,
+    )
+
+
+def rewrite_argv_path_tokens(
+    argv: tuple[str, ...] | list[str],
+    *,
+    local_root: Path,
+    layout: RemoteLayout,
+    cwd: Path | None = None,
+) -> RewrittenArgv:
+    rewritten: list[str] = []
+    staged_paths: list[ExternalStagePath] = []
+    stage_slots: dict[Path, ExternalStagePath] = {}
+
+    for token in argv:
+        if not _looks_like_explicit_path_token(token):
+            rewritten.append(token)
+            continue
+
+        classification = classify_path_token(token, local_root=local_root, cwd=cwd)
+        if classification.kind == "in_root":
+            if classification.relative_path is None:
+                raise PathRewriteError(
+                    f"Internal path classification bug for in-root token: {token}"
+                )
+            rewritten.append(str(layout.mirror_dir / classification.relative_path))
+            continue
+
+        if classification.kind == "external":
+            if classification.local_path is None:
+                raise PathRewriteError(
+                    f"Internal path classification bug for external token: {token}"
+                )
+            stage_path = _plan_stage_path(
+                classification.local_path,
+                layout=layout,
+                planned=staged_paths,
+                stage_slots=stage_slots,
+            )
+            rewritten.append(str(stage_path.remote_path))
+            continue
+
+        if classification.kind == "remote_literal":
+            if classification.rewritten_token is None:
+                raise PathRewriteError(
+                    f"Internal path classification bug for remote literal token: {token}"
+                )
+            rewritten.append(classification.rewritten_token)
+            continue
+
+        rewritten.append(token)
+
+    return RewrittenArgv(argv=tuple(rewritten), staged_paths=tuple(staged_paths))
+
+
+def plan_explicit_stage_paths(
+    stage_paths: tuple[str, ...] | list[str],
+    *,
+    local_root: Path,
+    layout: RemoteLayout,
+    cwd: Path | None = None,
+) -> tuple[ExternalStagePath, ...]:
+    base_cwd = (
+        logical_current_directory() if cwd is None else logical_absolute_path(cwd)
+    )
+    logical_root = logical_absolute_path(local_root, base=base_cwd)
+    resolved_root = logical_root.resolve(strict=True)
+
+    planned: list[ExternalStagePath] = []
+    stage_slots: dict[Path, ExternalStagePath] = {}
+
+    for raw_path in stage_paths:
+        local_path = logical_absolute_path(raw_path, base=base_cwd)
+        if not local_path.exists():
+            raise ExplicitStagePathError(
+                f"Explicit stage path does not exist: {raw_path}"
+            )
+        if not local_path.is_file() and not local_path.is_dir():
+            raise ExplicitStagePathError(
+                f"Explicit stage path must be a file or directory: {raw_path}"
+            )
+
+        resolved_local = local_path.resolve(strict=True)
+        if _relative_to(resolved_local, resolved_root) is not None:
+            raise ExplicitStagePathError(
+                f"Explicit stage path is already inside the mirrored project root: {raw_path}"
+            )
+
+        _plan_stage_path(
+            local_path,
+            layout=layout,
+            planned=planned,
+            stage_slots=stage_slots,
+        )
+
+    return tuple(planned)
+
+
+def _is_attached_or_value_form(token: str) -> bool:
+    if token.startswith("-"):
+        return True
+
+    if "=" not in token:
+        return False
+
+    return not Path(token).expanduser().is_absolute()
+
+
+_LABELLED_PATH_RE = re.compile(r"^(?P<label>[A-Za-z][A-Za-z0-9_-]*):(?P<path>.+)$")
+_PLAIN_FILENAME_RE = re.compile(
+    r"^(?=.*[A-Za-z])[A-Za-z0-9][A-Za-z0-9._-]*\.[A-Za-z0-9._-]+$"
+)
+
+
+def _split_path_label(token: str) -> tuple[str | None, str]:
+    match = _LABELLED_PATH_RE.match(token)
+    if match is None:
+        return None, token
+    return match.group("label"), match.group("path")
+
+
+def _looks_like_explicit_path_token(token: str) -> bool:
+    label, _ = _split_path_label(token)
+    if label is not None:
+        return True
+
+    candidate = Path(token).expanduser()
+    return (
+        candidate.is_absolute()
+        or token.startswith((".", "~"))
+        or "/" in token
+        or _PLAIN_FILENAME_RE.match(token) is not None
+    )
+
+
+def _lexical_normalize(path: Path) -> Path:
+    return Path(os.path.normpath(str(path)))
+
+
+def _relative_to(path: Path, root: Path) -> Path | None:
+    try:
+        return path.relative_to(root)
+    except ValueError:
+        return None
+
+
+def _stage_basename(path: Path) -> str:
+    if path.name:
+        return path.name
+
+    anchor = path.anchor.replace("/", "").replace("\\", "")
+    return anchor or "root"