runspec-windows 0.1.0__tar.gz

runspec_windows-0.1.0/.gitignore

@@ -0,0 +1,58 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+env/
+.env
+pip-wheel-metadata/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.cover
+
+# Node
+node_modules/
+dist/
+*.js.map
+.npm
+
+# Go
+*.exe
+*.test
+*.out
+vendor/
+
+# IDE
+.idea/
+.vscode/
+*.iml
+*.iws
+*.ipr
+.DS_Store
+Thumbs.db
+
+# Docs
+site/
+
+# Misc
+*.log
+*.tmp
+
+# External reference repos (cloned locally, not committed)
+chainlit-docs/
+.chainlit/
+
+# Claude Code local config (machine-specific)
+.claude/launch.json

runspec_windows-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# runspec-windows Changelog
+
+## [0.1.0] — 2026-06-03
+
+Initial release.
+
+35 runnables covering Windows system administration and Microsoft 365:
+
+**System monitoring** — `system-info`, `disk-usage`, `check-memory`, `uptime`
+
+**Processes** — `list-processes`, `process-info`, `kill-process`
+
+**Services** — `list-services`, `check-service`, `restart-service`, `stop-service`
+
+**Network** — `ping-host`, `check-port`, `show-connections`, `list-adapters`, `flush-dns`
+
+**Event log** — `query-eventlog`, `recent-errors`
+
+**Scheduled tasks** — `list-scheduled-tasks`
+
+**Installed software** — `installed-software`
+
+**Sessions** — `who`, `current-user`
+
+**Microsoft Graph (Outlook + Teams + Calendar + OneDrive)** — `graph-login`, `graph-whoami`, `outlook-unread`, `outlook-search`, `outlook-folders`, `teams-list-chats`, `teams-read-chat`, `calendar-upcoming`, `calendar-today`, `next-meeting`, `onedrive-recent`, `onedrive-search`, `onedrive-list`
+
+Read-only runnables are `autonomy = "autonomous"`; state-changing ones
+(`kill-process`, `restart-service`, `stop-service`, `flush-dns`, `graph-login`)
+are `autonomy = "confirm"`. Windows-only runnables return a structured JSON
+error (not a traceback) when run on a non-Windows host.
+
+Microsoft Graph runnables use delegated **device-code** auth via MSAL — no
+client secret. The optional `msal`/`httpx` dependencies live behind the
+`[graph]` extra. The package also exports `graph_get()` and `get_token()` as a
+public Python API for building further Graph-backed wrapper runnables.

runspec_windows-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: runspec-windows
+Version: 0.1.0
+Summary: Windows system admin + Microsoft 365 (Outlook, Teams) runnables for runspec
+Requires-Python: >=3.10
+Requires-Dist: runspec>=0.23.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: msal>=1.28; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: graph
+Requires-Dist: httpx>=0.27; extra == 'graph'
+Requires-Dist: msal>=1.28; extra == 'graph'

runspec_windows-0.1.0/README.md

@@ -0,0 +1,119 @@
+# runspec-windows
+
+Windows system-administration and Microsoft 365 (Outlook + Teams) runnables for
+[runspec](https://pypi.org/project/runspec/). The Windows counterpart to
+[`runspec-linux`](../runspec-linux): `pip install` it into a venv and the
+runnables are discoverable by `runspec local`, `runspec serve` (MCP), and
+runspec-console.
+
+All runnables emit JSON on stdout. Read-only runnables are `autonomy =
+"autonomous"`; state-changing ones (`kill-process`, `restart-service`,
+`stop-service`, `flush-dns`, `graph-login`) are `autonomy = "confirm"`.
+
+## Install
+
+```
+pip install runspec-windows          # system utilities only
+pip install "runspec-windows[graph]" # + Microsoft 365 (Outlook/Teams) runnables
+```
+
+## Runnables
+
+| Group | Runnables |
+|---|---|
+| System | `system-info`, `disk-usage`, `check-memory`, `uptime` |
+| Processes | `list-processes`, `process-info`, `kill-process` |
+| Services | `list-services`, `check-service`, `restart-service`, `stop-service` |
+| Network | `ping-host`, `check-port`, `show-connections`, `list-adapters`, `flush-dns` |
+| Event log | `query-eventlog`, `recent-errors` |
+| Scheduled tasks | `list-scheduled-tasks` |
+| Installed software | `installed-software` |
+| Sessions | `who`, `current-user` |
+| Microsoft 365 | `graph-login`, `graph-whoami`, `outlook-unread`, `outlook-search`, `outlook-folders`, `teams-list-chats`, `teams-read-chat`, `calendar-upcoming`, `calendar-today`, `next-meeting`, `onedrive-recent`, `onedrive-search`, `onedrive-list` |
+
+The system runnables are Windows-only; run one on macOS/Linux and it returns a
+clean JSON error rather than a traceback. The Microsoft Graph runnables are pure
+HTTP and run anywhere — they only need a token.
+
+```
+system-info
+list-processes --filter chrome --limit 10
+query-eventlog --log System --level error --count 20
+installed-software --filter "Microsoft"
+```
+
+## Microsoft 365 (Outlook + Teams) — one-time setup
+
+The Graph runnables authenticate as the signed-in user via the OAuth
+**device-code** flow (no client secret, no admin app password). You need a
+public-client **app registration** in your Entra ID (Azure AD) tenant:
+
+1. **Entra admin center → App registrations → New registration.** Give it a
+   name; under *Supported account types* pick whatever matches your tenant.
+2. **Authentication → Advanced settings → Allow public client flows → Yes.**
+   (Device-code flow requires this.)
+3. **API permissions → Add → Microsoft Graph → Delegated**, add
+   `User.Read`, `Mail.Read`, `Chat.Read`, `Calendars.Read`, `Files.Read.All`,
+   then *Grant admin consent* if your tenant requires it.
+4. Copy the **Application (client) ID**.
+
+Then point the package at it (the client id is **not** a secret):
+
+```
+set RUNSPEC_GRAPH_CLIENT_ID=<application-client-id>
+set RUNSPEC_GRAPH_TENANT=<tenant-id-or-domain>   # optional; default "organizations"
+```
+
+…or create `%APPDATA%\runspec-windows\graph.toml`:
+
+```toml
+client_id = "00000000-0000-0000-0000-000000000000"
+tenant    = "contoso.onmicrosoft.com"
+```
+
+Sign in once (prints a code + URL to visit; the token is cached under
+`%APPDATA%\runspec-windows\msal_cache.bin`):
+
+```
+graph-login
+graph-whoami
+outlook-unread --count 10
+outlook-search --query "invoice"
+teams-list-chats
+teams-read-chat --chat-id 19:abc...@thread.v2
+calendar-upcoming --days 7
+calendar-today
+next-meeting
+onedrive-recent
+onedrive-search --query "budget"
+onedrive-list --path "/Documents"
+```
+
+Tokens are cached and refreshed silently; rerun `graph-login` if the cache is
+cleared or consent changes.
+
+## Public Python API
+
+Mirroring `runspec-linux`'s `nc_send`, this package exports the authenticated
+Graph client so you can build your own wrapper runnables:
+
+```python
+from runspec_windows import graph_get, get_token
+
+me = graph_get("/me")
+events = graph_get("/me/events", params={"$top": 5})
+```
+
+## Development
+
+```
+python -m venv .venv && . .venv/bin/activate   # or .venv\Scripts\activate
+pip install -e ".[dev,graph]"
+ruff check . && ruff format --check .
+pytest
+```
+
+The OS-specific work sits behind thin helpers in `_platform.py`; the pure output
+parsers (`tasklist`/`netstat`/`ipconfig`/`schtasks`/`query user`) and the Graph
+formatters are unit-tested on any platform. Real end-to-end runs of the
+Windows-only runnables happen on a Windows host / the `windows-latest` CI job.

runspec_windows-0.1.0/pyproject.toml

@@ -0,0 +1,93 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runspec-windows"
+version = "0.1.0"
+requires-python = ">=3.10"
+description = "Windows system admin + Microsoft 365 (Outlook, Teams) runnables for runspec"
+dependencies = [
+    "runspec>=0.23.0",
+]
+
+[project.optional-dependencies]
+# Microsoft Graph runnables (Outlook + Teams). Pure HTTP — no pywin32 needed.
+graph = [
+    "msal>=1.28",
+    "httpx>=0.27",
+]
+dev = [
+    "ruff",
+    "mypy",
+    "pytest>=8.0",
+    "msal>=1.28",
+    "httpx>=0.27",
+]
+
+[project.scripts]
+# System monitoring
+system-info          = "runspec_windows.system_info:main_system_info"
+disk-usage           = "runspec_windows.system_info:main_disk_usage"
+check-memory         = "runspec_windows.system_info:main_check_memory"
+uptime               = "runspec_windows.system_info:main_uptime"
+# Processes
+list-processes       = "runspec_windows.processes:main_list_processes"
+process-info         = "runspec_windows.processes:main_process_info"
+kill-process         = "runspec_windows.processes:main_kill_process"
+# Services
+list-services        = "runspec_windows.services:main_list_services"
+check-service        = "runspec_windows.services:main_check_service"
+restart-service      = "runspec_windows.services:main_restart_service"
+stop-service         = "runspec_windows.services:main_stop_service"
+# Network
+ping-host            = "runspec_windows.network:main_ping_host"
+check-port           = "runspec_windows.network:main_check_port"
+show-connections     = "runspec_windows.network:main_show_connections"
+list-adapters        = "runspec_windows.network:main_list_adapters"
+flush-dns            = "runspec_windows.network:main_flush_dns"
+# Event log
+query-eventlog       = "runspec_windows.eventlog:main_query_eventlog"
+recent-errors        = "runspec_windows.eventlog:main_recent_errors"
+# Scheduled tasks
+list-scheduled-tasks = "runspec_windows.tasks:main_list_scheduled_tasks"
+# Installed software
+installed-software   = "runspec_windows.software:main_installed_software"
+# Sessions
+who                  = "runspec_windows.sessions:main_who"
+current-user         = "runspec_windows.sessions:main_current_user"
+# Microsoft Graph — account
+graph-login          = "runspec_windows.graph.account:main_graph_login"
+graph-whoami         = "runspec_windows.graph.account:main_graph_whoami"
+# Microsoft Graph — Outlook
+outlook-unread       = "runspec_windows.graph.outlook:main_outlook_unread"
+outlook-search       = "runspec_windows.graph.outlook:main_outlook_search"
+outlook-folders      = "runspec_windows.graph.outlook:main_outlook_folders"
+# Microsoft Graph — Calendar
+calendar-upcoming    = "runspec_windows.graph.calendar:main_calendar_upcoming"
+calendar-today       = "runspec_windows.graph.calendar:main_calendar_today"
+next-meeting         = "runspec_windows.graph.calendar:main_next_meeting"
+# Microsoft Graph — OneDrive / Files
+onedrive-recent      = "runspec_windows.graph.files:main_onedrive_recent"
+onedrive-search      = "runspec_windows.graph.files:main_onedrive_search"
+onedrive-list        = "runspec_windows.graph.files:main_onedrive_list"
+# Microsoft Graph — Teams
+teams-list-chats     = "runspec_windows.graph.teams:main_teams_list_chats"
+teams-read-chat      = "runspec_windows.graph.teams:main_teams_read_chat"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+
+[[tool.mypy.overrides]]
+module = ["msal.*"]
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 200
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

runspec_windows-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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"),
+    }