runspec-windows 0.1.0__py3-none-any.whl

runspec_windows/__init__.py

@@ -0,0 +1,14 @@
+"""runspec-windows — Windows system admin + Microsoft 365 runnables for runspec.
+
+Public API (parallels runspec-linux's ``nc_send``): ``graph_get`` and
+``get_token`` let other wrapper runnables reuse the authenticated Microsoft
+Graph client without re-implementing the device-code flow.
+
+Importing this package never requires the optional ``[graph]`` dependencies —
+``msal``/``httpx`` are imported lazily and only when a Graph call is made.
+"""
+
+from runspec_windows.graph.auth import get_token
+from runspec_windows.graph.client import graph_get
+
+__all__ = ["graph_get", "get_token"]

runspec_windows/_platform.py

@@ -0,0 +1,65 @@
+"""_platform.py — Windows execution helpers shared by the system runnables.
+
+The OS-specific work (shelling out to ``powershell``/``sc``/``netstat`` etc.)
+lives behind these thin helpers so the pure parsers in each module stay
+import-clean and unit-testable on any platform. Every Windows-only runnable
+calls :func:`ensure_windows` first, so running one on a non-Windows host returns
+a structured JSON error instead of a traceback.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+
+IS_WINDOWS = sys.platform == "win32"
+
+
+def ensure_windows() -> None:
+    """Emit a JSON error and exit if not running on Windows.
+
+    Keeps non-Windows behaviour predictable (clean error, exit 1) rather than
+    crashing on a missing ``ipconfig``/``sc``/Win32 API.
+    """
+    if not IS_WINDOWS:
+        print(json.dumps({"error": "This runnable requires Windows", "platform": sys.platform}))
+        sys.exit(1)
+
+
+def fail(message: str, **extra: object) -> None:
+    """Print ``{"error": message, **extra}`` as JSON and exit non-zero."""
+    print(json.dumps({"error": message, **extra}))
+    sys.exit(1)
+
+
+def run_powershell(script: str, timeout: int = 30) -> str:
+    """Run a PowerShell snippet non-interactively and return its stdout.
+
+    Raises ``RuntimeError`` with stderr on a non-zero exit so callers can turn
+    it into a JSON error.
+    """
+    result = subprocess.run(
+        ["powershell", "-NoProfile", "-NonInteractive", "-Command", script],
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or f"powershell exited {result.returncode}")
+    return result.stdout
+
+
+def run_cmd(args: list[str], timeout: int = 30, check: bool = False) -> subprocess.CompletedProcess[str]:
+    """Run a console command and return the completed process (text mode)."""
+    return subprocess.run(
+        args,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        check=check,
+        encoding="utf-8",
+        errors="replace",
+    )

runspec_windows/eventlog.py

@@ -0,0 +1,87 @@
+"""Event log runnables: query-eventlog, recent-errors."""
+
+from __future__ import annotations
+
+import json
+
+import runspec as rs
+
+from runspec_windows import _platform
+
+# Get-WinEvent numeric levels.
+_LEVELS = {"critical": 1, "error": 2, "warning": 3, "information": 4}
+
+
+def normalize_events(data: object) -> list[dict]:
+    """Reshape parsed ``Get-WinEvent | ConvertTo-Json`` output into rows."""
+    if isinstance(data, dict):
+        items = [data]
+    elif isinstance(data, list):
+        items = [d for d in data if isinstance(d, dict)]
+    else:
+        items = []
+    rows = []
+    for item in items:
+        message = item.get("message") or ""
+        if isinstance(message, str) and len(message) > 500:
+            message = message[:500] + "…"
+        rows.append(
+            {
+                "time": item.get("time"),
+                "level": item.get("level"),
+                "id": item.get("Id"),
+                "provider": item.get("ProviderName"),
+                "message": message,
+            }
+        )
+    return rows
+
+
+def _select() -> str:
+    return "Select-Object @{N='time';E={$_.TimeCreated.ToString('s')}},@{N='level';E={$_.LevelDisplayName}},Id,ProviderName,@{N='message';E={$_.Message}}"
+
+
+def _query(log: str, count: int, level: str | None) -> list[dict]:
+    filt = f"LogName='{log}'"
+    if level and level != "all":
+        filt += f"; Level={_LEVELS[level]}"
+    script = f"Get-WinEvent -FilterHashtable @{{{filt}}} -MaxEvents {count} -ErrorAction Stop | {_select()} | ConvertTo-Json -Compress"
+    out = _platform.run_powershell(script).strip()
+    return normalize_events(json.loads(out)) if out else []
+
+
+def main_query_eventlog() -> None:
+    spec = rs.parse("query-eventlog")
+    _platform.ensure_windows()
+    log = str(spec.log)
+    level = str(spec.level)
+    count = int(spec.count)
+    try:
+        print(json.dumps({"log": log, "level": level, "events": _query(log, count, level)}))
+    except RuntimeError as e:
+        # Get-WinEvent raises "No events were found" when the filter matches nothing.
+        if "No events were found" in str(e):
+            print(json.dumps({"log": log, "level": level, "events": []}))
+        else:
+            _platform.fail(str(e), log=log)
+    except Exception as e:
+        _platform.fail(str(e), log=log)
+
+
+def main_recent_errors() -> None:
+    spec = rs.parse("recent-errors")
+    _platform.ensure_windows()
+    count = int(spec.count)
+    result: dict[str, list[dict]] = {}
+    try:
+        for log in ("System", "Application"):
+            try:
+                result[log] = _query(log, count, "error")
+            except RuntimeError as e:
+                if "No events were found" in str(e):
+                    result[log] = []
+                else:
+                    raise
+        print(json.dumps(result))
+    except Exception as e:
+        _platform.fail(str(e))

runspec_windows/graph/__init__.py

@@ -0,0 +1,24 @@
+"""Microsoft Graph integration for runspec-windows (Outlook + Teams).
+
+Pure HTTP via ``httpx`` + delegated auth via ``msal`` device-code flow — no
+pywin32 and no client secret. The optional dependencies live behind the
+``[graph]`` extra; importing this package never requires them.
+"""
+
+from __future__ import annotations
+
+
+class GraphError(Exception):
+    """Base error for Graph runnables (rendered as a JSON ``error`` payload)."""
+
+
+class GraphDepError(GraphError):
+    """The optional ``[graph]`` dependencies (msal/httpx) are not installed."""
+
+
+class GraphConfigError(GraphError):
+    """No Azure client id configured (RUNSPEC_GRAPH_CLIENT_ID / graph.toml)."""
+
+
+class GraphAuthError(GraphError):
+    """No cached credentials — the user must run ``graph-login`` first."""

runspec_windows/graph/_emit.py

@@ -0,0 +1,20 @@
+"""_emit.py — shared JSON output + error handling for Graph runnables."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from typing import Any
+
+from runspec_windows import _platform
+from runspec_windows.graph import GraphError
+
+
+def run_graph(produce: Callable[[], Any]) -> None:
+    """Print ``produce()`` as JSON, turning Graph errors into a JSON error payload."""
+    try:
+        print(json.dumps(produce()))
+    except GraphError as e:
+        _platform.fail(str(e), kind=type(e).__name__)
+    except Exception as e:  # network/JSON/etc.
+        _platform.fail(str(e))

runspec_windows/graph/account.py

@@ -0,0 +1,48 @@
+"""Account runnables (Microsoft Graph): graph-login, graph-whoami."""
+
+from __future__ import annotations
+
+import json
+
+import runspec as rs
+
+from runspec_windows import _platform
+from runspec_windows.graph import GraphError
+from runspec_windows.graph._emit import run_graph
+from runspec_windows.graph.auth import device_login
+from runspec_windows.graph.client import graph_get
+
+
+def main_graph_login() -> None:
+    rs.parse("graph-login")
+    try:
+        result = device_login()
+        claims = result.get("id_token_claims", {})
+        print(
+            json.dumps(
+                {
+                    "signed_in": True,
+                    "user": claims.get("preferred_username") or claims.get("name"),
+                    "scopes": result.get("scope"),
+                }
+            )
+        )
+    except GraphError as e:
+        _platform.fail(str(e), kind=type(e).__name__)
+    except Exception as e:
+        _platform.fail(str(e))
+
+
+def main_graph_whoami() -> None:
+    rs.parse("graph-whoami")
+    run_graph(lambda: _whoami(graph_get("/me", params={"$select": "displayName,userPrincipalName,mail,jobTitle,id"})))
+
+
+def _whoami(me: dict) -> dict:
+    return {
+        "display_name": me.get("displayName"),
+        "user_principal_name": me.get("userPrincipalName"),
+        "mail": me.get("mail"),
+        "job_title": me.get("jobTitle"),
+        "id": me.get("id"),
+    }

runspec_windows/graph/auth.py

@@ -0,0 +1,127 @@
+"""auth.py — Microsoft Graph delegated auth via MSAL device-code flow.
+
+Token cache persists to ``%APPDATA%/runspec-windows/msal_cache.bin``. The Azure
+``client_id`` (a public client — no secret) and ``tenant`` come from the
+environment or ``%APPDATA%/runspec-windows/graph.toml``.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from runspec_windows.graph import GraphAuthError, GraphConfigError, GraphDepError
+
+try:
+    import msal
+except ImportError:  # optional [graph] dependency
+    msal = None  # type: ignore[assignment]
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover
+    try:
+        import tomli as tomllib  # type: ignore[no-redef]
+    except ImportError:  # tomllib is the only consumer; degrade gracefully
+        tomllib = None  # type: ignore[assignment]
+
+DEFAULT_SCOPES = ["User.Read", "Mail.Read", "Chat.Read", "Calendars.Read", "Files.Read.All"]
+_AUTHORITY_BASE = "https://login.microsoftonline.com"
+
+
+def _require_msal() -> Any:
+    if msal is None:
+        raise GraphDepError("The 'msal' package is required for Microsoft Graph runnables. Install with: pip install 'runspec-windows[graph]'")
+    return msal
+
+
+def config_dir() -> Path:
+    base = os.environ.get("APPDATA") or str(Path.home() / ".config")
+    d = Path(base) / "runspec-windows"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _cache_path() -> Path:
+    return config_dir() / "msal_cache.bin"
+
+
+def _read_graph_toml() -> dict:
+    path = config_dir() / "graph.toml"
+    if not path.exists() or tomllib is None:
+        return {}
+    try:
+        with open(path, "rb") as f:
+            return dict(tomllib.load(f))
+    except Exception:
+        return {}
+
+
+def client_id() -> str:
+    cid = os.environ.get("RUNSPEC_GRAPH_CLIENT_ID") or _read_graph_toml().get("client_id")
+    if not cid:
+        raise GraphConfigError("No Azure client id. Set RUNSPEC_GRAPH_CLIENT_ID or add client_id to %APPDATA%/runspec-windows/graph.toml. See the README for app-registration steps.")
+    return str(cid)
+
+
+def tenant() -> str:
+    return str(os.environ.get("RUNSPEC_GRAPH_TENANT") or _read_graph_toml().get("tenant") or "organizations")
+
+
+def _load_cache() -> Any:
+    m = _require_msal()
+    cache = m.SerializableTokenCache()
+    path = _cache_path()
+    if path.exists():
+        cache.deserialize(path.read_text(encoding="utf-8"))
+    return cache
+
+
+def _save_cache(cache: Any) -> None:
+    if cache.has_state_changed:
+        _cache_path().write_text(cache.serialize(), encoding="utf-8")
+
+
+def _build_app(cache: Any) -> Any:
+    m = _require_msal()
+    return m.PublicClientApplication(client_id(), authority=f"{_AUTHORITY_BASE}/{tenant()}", token_cache=cache)
+
+
+def get_token(scopes: list[str] | None = None) -> str:
+    """Return a cached access token (silent refresh), or raise ``GraphAuthError``.
+
+    Does not start an interactive flow — call ``device_login`` (the ``graph-login``
+    runnable) once to populate the cache.
+    """
+    scopes = scopes or DEFAULT_SCOPES
+    cache = _load_cache()
+    app = _build_app(cache)
+    accounts = app.get_accounts()
+    result = app.acquire_token_silent(scopes, account=accounts[0]) if accounts else None
+    _save_cache(cache)
+    if not result or "access_token" not in result:
+        raise GraphAuthError("Not signed in to Microsoft 365 — run 'graph-login' first.")
+    return str(result["access_token"])
+
+
+def device_login(scopes: list[str] | None = None, on_prompt: Callable[[str], None] | None = None) -> dict:
+    """Run the device-code flow interactively and cache the resulting token.
+
+    ``on_prompt`` receives the human-readable instructions (verification URL +
+    code); defaults to printing them to stderr so stdout stays clean JSON.
+    """
+    scopes = scopes or DEFAULT_SCOPES
+    cache = _load_cache()
+    app = _build_app(cache)
+    flow = app.initiate_device_flow(scopes=scopes)
+    if "user_code" not in flow:
+        raise GraphAuthError(f"Failed to start device-code flow: {flow.get('error_description', flow)}")
+    (on_prompt or (lambda m: print(m, file=sys.stderr)))(flow["message"])
+    result = app.acquire_token_by_device_flow(flow)
+    _save_cache(cache)
+    if "access_token" not in result:
+        raise GraphAuthError(result.get("error_description", "Device-code login failed"))
+    return result

runspec_windows/graph/calendar.py

@@ -0,0 +1,77 @@
+"""Calendar runnables (Microsoft Graph): calendar-upcoming, calendar-today, next-meeting."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+import runspec as rs
+
+from runspec_windows.graph._emit import run_graph
+from runspec_windows.graph.client import graph_get
+
+_EVENT_SELECT = "subject,start,end,organizer,location,onlineMeeting,isOnlineMeeting,webLink"
+
+
+def format_events(data: dict) -> list[dict]:
+    """Reshape a Graph calendarView response (``{"value": [...]}``) into rows."""
+    rows = []
+    for ev in data.get("value", []):
+        organizer = ((ev.get("organizer") or {}).get("emailAddress") or {}).get("name")
+        online = ev.get("onlineMeeting") or {}
+        rows.append(
+            {
+                "subject": ev.get("subject"),
+                "start": (ev.get("start") or {}).get("dateTime"),
+                "end": (ev.get("end") or {}).get("dateTime"),
+                "organizer": organizer,
+                "location": (ev.get("location") or {}).get("displayName"),
+                "is_online": ev.get("isOnlineMeeting"),
+                "join_url": online.get("joinUrl"),
+                "web_link": ev.get("webLink"),
+            }
+        )
+    return rows
+
+
+def _iso(dt: datetime) -> str:
+    return dt.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _calendar_view(start: datetime, end: datetime, count: int) -> list[dict]:
+    return format_events(
+        graph_get(
+            "/me/calendarView",
+            params={
+                "startDateTime": _iso(start),
+                "endDateTime": _iso(end),
+                "$select": _EVENT_SELECT,
+                "$orderby": "start/dateTime",
+                "$top": count,
+            },
+        )
+    )
+
+
+def main_calendar_upcoming() -> None:
+    spec = rs.parse("calendar-upcoming")
+    days = int(spec.days)
+    count = int(spec.count)
+    now = datetime.now(timezone.utc)
+    run_graph(lambda: _calendar_view(now, now + timedelta(days=days), count))
+
+
+def main_calendar_today() -> None:
+    rs.parse("calendar-today")
+    start = datetime.now(timezone.utc).replace(hour=0, minute=0, second=0, microsecond=0)
+    run_graph(lambda: _calendar_view(start, start + timedelta(days=1), 50))
+
+
+def main_next_meeting() -> None:
+    rs.parse("next-meeting")
+    now = datetime.now(timezone.utc)
+
+    def produce() -> dict:
+        events = _calendar_view(now, now + timedelta(days=30), 1)
+        return events[0] if events else {"message": "No upcoming meetings in the next 30 days"}
+
+    run_graph(produce)

runspec_windows/graph/client.py

@@ -0,0 +1,43 @@
+"""client.py — thin authenticated Microsoft Graph GET helper."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runspec_windows.graph import GraphDepError, GraphError
+from runspec_windows.graph.auth import get_token
+
+try:
+    import httpx
+except ImportError:  # optional [graph] dependency
+    httpx = None  # type: ignore[assignment]
+
+GRAPH_BASE = "https://graph.microsoft.com/v1.0"
+
+
+def graph_get(path: str, params: dict | None = None, scopes: list[str] | None = None, timeout: int = 30) -> dict:
+    """GET ``GRAPH_BASE + path`` with a bearer token and return parsed JSON.
+
+    Raises ``GraphError`` on a non-2xx response, surfacing the Graph error
+    message. ``path`` should start with ``/`` (e.g. ``/me/messages``).
+    """
+    if httpx is None:
+        raise GraphDepError("The 'httpx' package is required for Microsoft Graph runnables. Install with: pip install 'runspec-windows[graph]'")
+    token = get_token(scopes)
+    headers = {"Authorization": f"Bearer {token}", "Accept": "application/json"}
+    if params and "$search" in params:
+        # Graph requires ConsistencyLevel: eventual for $search on messages.
+        headers["ConsistencyLevel"] = "eventual"
+    resp = httpx.get(GRAPH_BASE + path, headers=headers, params=params, timeout=timeout)
+    if resp.status_code >= 400:
+        raise GraphError(_error_message(resp))
+    return resp.json()  # type: ignore[no-any-return]
+
+
+def _error_message(resp: Any) -> str:
+    try:
+        body = resp.json()
+        msg = body.get("error", {}).get("message") or str(body)
+    except Exception:
+        msg = resp.text[:500]
+    return f"Graph {resp.status_code}: {msg}"

runspec_windows/graph/files.py

@@ -0,0 +1,51 @@
+"""OneDrive/SharePoint file runnables (Microsoft Graph): onedrive-recent, onedrive-search, onedrive-list."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+import runspec as rs
+
+from runspec_windows.graph._emit import run_graph
+from runspec_windows.graph.client import graph_get
+
+_ITEM_SELECT = "name,size,lastModifiedDateTime,webUrl,id,folder,file,parentReference"
+
+
+def format_items(data: dict) -> list[dict]:
+    """Reshape a Graph driveItem collection (``{"value": [...]}``) into rows."""
+    rows = []
+    for it in data.get("value", []):
+        rows.append(
+            {
+                "name": it.get("name"),
+                "is_folder": "folder" in it,
+                "size": it.get("size"),
+                "last_modified": it.get("lastModifiedDateTime"),
+                "web_url": it.get("webUrl"),
+                "item_id": it.get("id"),
+                "path": (it.get("parentReference") or {}).get("path"),
+            }
+        )
+    return rows
+
+
+def main_onedrive_recent() -> None:
+    spec = rs.parse("onedrive-recent")
+    count = int(spec.count)
+    run_graph(lambda: format_items(graph_get("/me/drive/recent", params={"$top": count})))
+
+
+def main_onedrive_search() -> None:
+    spec = rs.parse("onedrive-search")
+    query = str(spec.query)
+    count = int(spec.count)
+    path = f"/me/drive/root/search(q='{quote(query)}')"
+    run_graph(lambda: format_items(graph_get(path, params={"$top": count, "$select": _ITEM_SELECT})))
+
+
+def main_onedrive_list() -> None:
+    spec = rs.parse("onedrive-list")
+    folder = str(spec.path).strip("/")
+    path = f"/me/drive/root:/{quote(folder)}:/children" if folder else "/me/drive/root/children"
+    run_graph(lambda: format_items(graph_get(path, params={"$select": _ITEM_SELECT})))

runspec_windows/graph/outlook.py

@@ -0,0 +1,79 @@
+"""Outlook runnables (Microsoft Graph): outlook-unread, outlook-search, outlook-folders."""
+
+from __future__ import annotations
+
+import runspec as rs
+
+from runspec_windows.graph._emit import run_graph
+from runspec_windows.graph.client import graph_get
+
+_MESSAGE_SELECT = "subject,from,receivedDateTime,isRead,bodyPreview,webLink"
+
+
+def format_messages(data: dict) -> list[dict]:
+    """Reshape a Graph messages response (``{"value": [...]}``) into rows."""
+    rows = []
+    for msg in data.get("value", []):
+        sender = (msg.get("from") or {}).get("emailAddress") or {}
+        rows.append(
+            {
+                "subject": msg.get("subject"),
+                "from": sender.get("name"),
+                "from_address": sender.get("address"),
+                "received": msg.get("receivedDateTime"),
+                "is_read": msg.get("isRead"),
+                "preview": msg.get("bodyPreview"),
+                "web_link": msg.get("webLink"),
+            }
+        )
+    return rows
+
+
+def format_folders(data: dict) -> list[dict]:
+    """Reshape a Graph mailFolders response into rows with unread/total counts."""
+    return [
+        {
+            "name": f.get("displayName"),
+            "unread": f.get("unreadItemCount"),
+            "total": f.get("totalItemCount"),
+            "id": f.get("id"),
+        }
+        for f in data.get("value", [])
+    ]
+
+
+def main_outlook_unread() -> None:
+    spec = rs.parse("outlook-unread")
+    count = int(spec.count)
+    run_graph(
+        lambda: format_messages(
+            graph_get(
+                "/me/mailFolders/inbox/messages",
+                params={
+                    "$filter": "isRead eq false",
+                    "$top": count,
+                    "$select": _MESSAGE_SELECT,
+                    "$orderby": "receivedDateTime desc",
+                },
+            )
+        )
+    )
+
+
+def main_outlook_search() -> None:
+    spec = rs.parse("outlook-search")
+    query = str(spec.query)
+    count = int(spec.count)
+    run_graph(
+        lambda: format_messages(
+            graph_get(
+                "/me/messages",
+                params={"$search": f'"{query}"', "$top": count, "$select": _MESSAGE_SELECT},
+            )
+        )
+    )
+
+
+def main_outlook_folders() -> None:
+    rs.parse("outlook-folders")
+    run_graph(lambda: format_folders(graph_get("/me/mailFolders", params={"$top": 100})))