owa-tools 0.1.0__tar.gz

owa_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carl Joakim Damsleth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

owa_tools-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: owa-tools
+Version: 0.1.0
+Summary: Monorepo workspace for owa-piggy consumer CLIs
+Author: Carl Joakim Damsleth
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# owa-tools
+
+Monorepo for the seven `owa-piggy` consumer CLIs: `owa-cal`, `owa-mail`, `owa-graph`, `owa-doctor`, `owa-people`, `owa-sched`, `owa-drive`. Plus the umbrella `owa` discovery binary.
+
+The auth broker `owa-piggy` lives in its own repository. It is the only persistent-secret holder in the suite.
+
+## Status
+
+`owa-tools` is currently unreleased and uses one suite version for all console scripts.
+
+| CLI | Status |
+|---|---|
+| `owa-cal` | beta |
+| `owa-mail` | beta |
+| `owa-graph` | beta |
+| `owa-doctor` | alpha |
+| `owa-people` | alpha |
+| `owa-sched` | alpha |
+| `owa-drive` | alpha |
+| `owa` | umbrella discovery binary |
+
+## Layout
+
+```
+owa-tools/
+├── owa_cal/         calendar CRUD over Outlook REST
+├── owa_mail/        mail CRUD over Outlook REST
+├── owa_graph/       Microsoft Graph CLI (verb-first + 14 resource shortcut groups)
+├── owa_doctor/      health check across the suite
+├── owa_people/      people, directory, contacts (Graph)
+├── owa_sched/       free/busy and slot finding (Graph)
+├── owa_drive/       OneDrive CRUD (Graph)
+├── owa/             umbrella `owa` binary (list, schema, doctor, version)
+├── tools/           CI helpers (stdlib check)
+├── tests/           per-tool test suites
+├── completions/     bash, zsh, fish
+└── docs/            per-tool docs
+```
+
+## Running
+
+Local dev install:
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e .[dev]
+.venv/bin/owa list
+```
+
+Wheel build:
+
+```bash
+.venv/bin/python -m build --wheel
+```
+
+The wheel contains all eight console scripts (`owa`, `owa-cal`, `owa-mail`, `owa-graph`, `owa-doctor`, `owa-people`, `owa-sched`, `owa-drive`) and they all report the same `owa-tools` suite version.
+
+Test suite:
+
+```bash
+.venv/bin/python -m pytest
+.venv/bin/coverage run --source=owa_core -m pytest -q
+.venv/bin/coverage report --fail-under=95
+.venv/bin/python -m pytest --cov --cov-fail-under=90
+.venv/bin/python tools/check_stdlib_only.py
+.venv/bin/python tools/check_no_secrets.py
+.venv/bin/python tools/check_docs_sync.py
+.venv/bin/python tools/check_artifacts.py dist/*   # after build
+.venv/bin/python tools/check_console_smoke.py      # after build
+```
+
+See `RELEASING.md` for the suite tag-and-publish flow.
+
+## More Docs
+
+- `docs/security.md` defines the token, config, redaction, and live-test
+  boundaries.
+- `docs/agent-integration.md` documents schema discovery, `--agent`, and
+  `--err-json`.
+- `docs/profile-model.md` explains how `owa-tools` profile aliases map to
+  `owa-piggy` profiles.
+- `docs/migrating-from-individual-installs.md` walks existing users from
+  the legacy per-tool installs to the `owa-tools` suite.
+
+## Conventions
+
+- Stdlib only at runtime, except for the local suite packages and `owa-piggy`.
+- JSON on stdout, logs on stderr, `--pretty` for humans.
+- `--agent` wraps JSON-compatible output for automation; `--err-json` emits
+  structured stderr.
+- Auth via `owa-piggy` (subprocess, JSON contract).
+- For agents and contributors, start with `AGENTS.md`, then read the nearest
+  local `AGENTS.md` for the package or directory being edited.
+
+## License
+
+MIT.

owa_tools-0.1.0/README.md

@@ -0,0 +1,97 @@
+# owa-tools
+
+Monorepo for the seven `owa-piggy` consumer CLIs: `owa-cal`, `owa-mail`, `owa-graph`, `owa-doctor`, `owa-people`, `owa-sched`, `owa-drive`. Plus the umbrella `owa` discovery binary.
+
+The auth broker `owa-piggy` lives in its own repository. It is the only persistent-secret holder in the suite.
+
+## Status
+
+`owa-tools` is currently unreleased and uses one suite version for all console scripts.
+
+| CLI | Status |
+|---|---|
+| `owa-cal` | beta |
+| `owa-mail` | beta |
+| `owa-graph` | beta |
+| `owa-doctor` | alpha |
+| `owa-people` | alpha |
+| `owa-sched` | alpha |
+| `owa-drive` | alpha |
+| `owa` | umbrella discovery binary |
+
+## Layout
+
+```
+owa-tools/
+├── owa_cal/         calendar CRUD over Outlook REST
+├── owa_mail/        mail CRUD over Outlook REST
+├── owa_graph/       Microsoft Graph CLI (verb-first + 14 resource shortcut groups)
+├── owa_doctor/      health check across the suite
+├── owa_people/      people, directory, contacts (Graph)
+├── owa_sched/       free/busy and slot finding (Graph)
+├── owa_drive/       OneDrive CRUD (Graph)
+├── owa/             umbrella `owa` binary (list, schema, doctor, version)
+├── tools/           CI helpers (stdlib check)
+├── tests/           per-tool test suites
+├── completions/     bash, zsh, fish
+└── docs/            per-tool docs
+```
+
+## Running
+
+Local dev install:
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e .[dev]
+.venv/bin/owa list
+```
+
+Wheel build:
+
+```bash
+.venv/bin/python -m build --wheel
+```
+
+The wheel contains all eight console scripts (`owa`, `owa-cal`, `owa-mail`, `owa-graph`, `owa-doctor`, `owa-people`, `owa-sched`, `owa-drive`) and they all report the same `owa-tools` suite version.
+
+Test suite:
+
+```bash
+.venv/bin/python -m pytest
+.venv/bin/coverage run --source=owa_core -m pytest -q
+.venv/bin/coverage report --fail-under=95
+.venv/bin/python -m pytest --cov --cov-fail-under=90
+.venv/bin/python tools/check_stdlib_only.py
+.venv/bin/python tools/check_no_secrets.py
+.venv/bin/python tools/check_docs_sync.py
+.venv/bin/python tools/check_artifacts.py dist/*   # after build
+.venv/bin/python tools/check_console_smoke.py      # after build
+```
+
+See `RELEASING.md` for the suite tag-and-publish flow.
+
+## More Docs
+
+- `docs/security.md` defines the token, config, redaction, and live-test
+  boundaries.
+- `docs/agent-integration.md` documents schema discovery, `--agent`, and
+  `--err-json`.
+- `docs/profile-model.md` explains how `owa-tools` profile aliases map to
+  `owa-piggy` profiles.
+- `docs/migrating-from-individual-installs.md` walks existing users from
+  the legacy per-tool installs to the `owa-tools` suite.
+
+## Conventions
+
+- Stdlib only at runtime, except for the local suite packages and `owa-piggy`.
+- JSON on stdout, logs on stderr, `--pretty` for humans.
+- `--agent` wraps JSON-compatible output for automation; `--err-json` emits
+  structured stderr.
+- Auth via `owa-piggy` (subprocess, JSON contract).
+- For agents and contributors, start with `AGENTS.md`, then read the nearest
+  local `AGENTS.md` for the package or directory being edited.
+
+## License
+
+MIT.

owa_tools-0.1.0/owa/__init__.py

@@ -0,0 +1,3 @@
+from owa_core.version import suite_version
+
+__version__ = suite_version()

owa_tools-0.1.0/owa/__main__.py

@@ -0,0 +1,7 @@
+"""Allow `python -m owa` for contract tests and local smoke checks."""
+import sys
+
+from .cli import main
+
+if __name__ == '__main__':
+    sys.exit(main())

owa_tools-0.1.0/owa/cli.py

@@ -0,0 +1,193 @@
+"""Umbrella `owa` binary. Discovery only; not a full dispatcher.
+
+Subcommands:
+  owa list         List installed consumer CLIs and their versions.
+  owa schema       Aggregate schemas from each consumer CLI.
+  owa doctor       Forward to `owa-doctor probe`.
+  owa version      Print the umbrella version.
+
+Real work lives in the consumer CLIs (owa-cal, owa-mail, ...).
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from . import __version__
+
+CONSUMERS = (
+    "owa-cal",
+    "owa-mail",
+    "owa-graph",
+    "owa-doctor",
+    "owa-people",
+    "owa-sched",
+    "owa-drive",
+)
+
+
+def _which(name: str) -> str | None:
+    for base in (
+        Path(sys.argv[0]).parent,
+        Path(sys.argv[0]).resolve().parent,
+        Path(sys.executable).parent,
+        Path(sys.executable).resolve().parent,
+    ):
+        candidate = base / name
+        if candidate.exists():
+            return str(candidate)
+    found = shutil.which(name)
+    if found:
+        return found
+    return None
+
+
+def _version_of(binary: str) -> str | None:
+    """Best-effort version lookup. Tries `--version`, falls back to the
+    first line of `--help`. Returns None on failure.
+
+    Several owa-* CLIs do not implement --version yet; that's tracked as
+    Phase 6 work in the implementation plan. This function works against
+    today's state."""
+    path = _which(binary)
+    if path is None:
+        return None
+
+    def _run(args: list[str]) -> str | None:
+        try:
+            out = subprocess.run(
+                [path, *args],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+        except (subprocess.TimeoutExpired, OSError):
+            return None
+        return (out.stdout or out.stderr or "").strip() or None
+
+    text = _run(["--version"])
+    if text and not _looks_like_error(text):
+        return text.splitlines()[0]
+    text = _run(["--help"])
+    if text:
+        return text.splitlines()[0]
+    return None
+
+
+def _looks_like_error(text: str) -> bool:
+    head = text.lower()
+    return head.startswith(("error", "usage:", "unknown")) or "unknown command" in head
+
+
+def cmd_list(argv: list[str]) -> int:
+    del argv
+    rows = []
+    for name in CONSUMERS:
+        path = _which(name)
+        rows.append({
+            "tool": name,
+            "installed": path is not None,
+            "path": path,
+            "version": _version_of(name) if path else None,
+        })
+    json.dump(rows, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+def cmd_version(argv: list[str]) -> int:
+    del argv
+    sys.stdout.write(f"owa {__version__}\n")
+    return 0
+
+
+def cmd_doctor(argv: list[str]) -> int:
+    path = _which("owa-doctor")
+    if path is None:
+        sys.stderr.write("owa-doctor not on PATH\n")
+        return 13
+    return subprocess.call([path, "probe", *argv])
+
+
+def cmd_schema(argv: list[str]) -> int:
+    """Aggregate `<tool> schema` output across installed consumers.
+
+    Each consumer either ships a JSON schema (Phase 3+) or doesn't.
+    Tools that don't yet support `schema` get a stub entry with
+    ``"schema_supported": false``. With ``--tool <name>``, fetches a
+    single tool only.
+    """
+    only = None
+    if argv and argv[0] in ("--tool", "-t"):
+        if len(argv) < 2:
+            sys.stderr.write("--tool requires a value\n")
+            return 2
+        only = argv[1]
+    aggregate = []
+    for name in CONSUMERS:
+        if only and name != only:
+            continue
+        path = _which(name)
+        if path is None:
+            aggregate.append({"tool": name, "installed": False})
+            continue
+        entry: dict[str, object] = {"tool": name, "installed": True, "path": path}
+        try:
+            proc = subprocess.run(
+                [path, "schema"], capture_output=True, text=True, timeout=5,
+            )
+        except (subprocess.TimeoutExpired, OSError) as e:
+            entry["schema_supported"] = False
+            entry["error"] = str(e)
+            aggregate.append(entry)
+            continue
+        if proc.returncode == 0 and proc.stdout.strip():
+            try:
+                entry["schema"] = json.loads(proc.stdout)
+                entry["schema_supported"] = True
+            except json.JSONDecodeError:
+                entry["schema_supported"] = False
+                entry["error"] = "non-JSON output from `schema`"
+        else:
+            entry["schema_supported"] = False
+        aggregate.append(entry)
+    json.dump(aggregate, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+def cmd_help(argv: list[str]) -> int:
+    del argv
+    sys.stdout.write(__doc__ or "")
+    return 0
+
+
+COMMANDS = {
+    "list": cmd_list,
+    "version": cmd_version,
+    "doctor": cmd_doctor,
+    "schema": cmd_schema,
+    "help": cmd_help,
+    "--help": cmd_help,
+    "-h": cmd_help,
+    "--version": cmd_version,
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv:
+        return cmd_help([])
+    cmd = argv[0]
+    handler = COMMANDS.get(cmd)
+    if handler is None:
+        sys.stderr.write(f"unknown command: {cmd}\n")
+        return 2
+    return handler(argv[1:])
+
+
+if __name__ == "__main__":
+    sys.exit(main())

owa_tools-0.1.0/owa_cal/__init__.py

@@ -0,0 +1,10 @@
+"""owa-cal - calendar CLI for Outlook / Microsoft 365."""
+
+from owa_core.version import suite_version
+
+__version__ = suite_version()
+
+# Defined after __version__ so cli.py can safely `from . import __version__`.
+from .cli import main  # noqa: E402
+
+__all__ = ["main", "__version__"]

owa_tools-0.1.0/owa_cal/__main__.py

@@ -0,0 +1,6 @@
+"""`python -m owa_cal` entrypoint."""
+import sys
+
+from .cli import main
+
+sys.exit(main())

owa_tools-0.1.0/owa_cal/api.py

@@ -0,0 +1,55 @@
+"""Outlook REST HTTP helper.
+
+One function: api_request. Returns parsed JSON or None (for
+return-to-caller failures). For auth/permission failures we exit the
+process with a clear message - owa-cal is a CLI, not a library, and
+there is no recovery path for a 401 except telling the user to re-run.
+"""
+import urllib.parse
+
+from owa_core import http
+from owa_core.errors import (
+    AuthExpiredError,
+    ConflictError,
+    InternalError,
+    NetworkError,
+    NotFoundError,
+    OwaError,
+    RateLimitedError,
+    ScopeInsufficientError,
+    emit_error,
+)
+
+
+def api_request(method, base, endpoint, access_token, body=None, debug=False):
+    """Issue a request against Outlook REST.
+
+    - `base` and `endpoint` are joined with a single slash.
+    - `body` is dict-serialised to JSON when non-None.
+    - Returns parsed JSON on 2xx, None on 404/429 (caller decides),
+      and exits on 401/403 (unrecoverable without reconfig).
+    """
+    url = f'{base}/{endpoint}'
+    try:
+        return http.request(method, url, token=access_token, body=body, debug=debug).json
+    except (AuthExpiredError, ScopeInsufficientError) as error:
+        raise error
+    except (ConflictError, InternalError, NetworkError, NotFoundError, RateLimitedError) as error:
+        emit_error(error)
+        return None
+    except OwaError as error:
+        emit_error(error)
+        return None
+
+
+def api_get(base, endpoint, access_token, debug=False):
+    return api_request('GET', base, endpoint, access_token, debug=debug)
+
+
+def build_query(params):
+    """Build an OData query string. Values are URL-encoded, keys are
+    not (they are $-prefixed OData system params)."""
+    parts = []
+    for k, v in params.items():
+        parts.append(f'{k}={urllib.parse.quote(str(v), safe="")}')
+    return '&'.join(parts)

owa_tools-0.1.0/owa_cal/auth.py

@@ -0,0 +1,40 @@
+"""Token acquisition. Audience: outlook (Outlook REST endpoint).
+
+owa-cal targets `outlook.office.com`, not Microsoft Graph: the OWA SPA
+client owa-piggy borrows does NOT carry Calendars.ReadWrite on the
+Graph audience - OWA itself calls Outlook REST for calendar.
+
+Thin wrapper over owa_core.auth - see owa_drive/auth.py for the
+"""
+
+from owa_core import auth as _core
+from owa_core.errors import OwaError, emit_error
+
+TOOL_NAME = 'owa-cal'
+AUDIENCE = 'outlook'
+API_BASE = 'https://outlook.office.com/api/v2.0'
+
+def _log_token_remaining(access, debug):
+    _core.log_token_remaining(access, debug)
+
+
+def _refresh_via_owa_piggy(config, debug=False):
+    try:
+        token = _core.get_token_for_config(
+            config, tool_name=TOOL_NAME, audience=AUDIENCE, debug=debug,
+        )
+    except OwaError as error:
+        emit_error(error)
+        return None
+    return token.access_token
+
+
+def do_token_refresh(config, debug=False):
+    return _refresh_via_owa_piggy(config, debug=debug)
+
+
+def setup_auth(config, debug=False):
+    token = _core.get_token_for_config(
+        config, tool_name=TOOL_NAME, audience=AUDIENCE, debug=debug,
+    )
+    return token.access_token, API_BASE