gfunk 0.1.0__py3-none-any.whl

gfunk/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("gfunk")

gfunk/__main__.py

@@ -0,0 +1,4 @@
+from gfunk.cli import main
+
+if __name__ == "__main__":
+    main()

gfunk/auth.py

@@ -0,0 +1,119 @@
+from pathlib import Path
+from typing import Literal
+
+from google.auth.transport.requests import Request
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+
+from gfunk.bootstrap import classify, diagnose
+from gfunk.browser import hyperlink
+from gfunk.browser import register as register_browser
+
+SCOPES = [
+    "https://www.googleapis.com/auth/spreadsheets",
+    "https://www.googleapis.com/auth/drive",
+    "https://www.googleapis.com/auth/script.processes",
+    "https://www.googleapis.com/auth/script.projects",
+    "https://www.googleapis.com/auth/gmail.modify",
+]
+
+CALENDAR_SCOPE = "https://www.googleapis.com/auth/calendar.readonly"
+
+DEFAULT_CONFIG_DIR = Path.home() / ".config" / "gfunk"
+DEFAULT_CLIENT_SECRETS = DEFAULT_CONFIG_DIR / "credentials.json"
+DEFAULT_TOKEN_PATH = DEFAULT_CONFIG_DIR / "token.json"
+
+
+def _scopes_changed(token_path: Path, expected: list[str]) -> bool:
+    """True when the cached token was issued for different scopes."""
+    import json
+
+    try:
+        stored = json.loads(token_path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return False
+    saved = stored.get("scopes")
+    if not saved:
+        return False
+    return set(expected) != set(saved)
+
+
+def granted_scopes(token_path: Path = DEFAULT_TOKEN_PATH) -> set[str]:
+    """Scopes the cached token actually carries, for feature-level opt-in checks."""
+    import json
+
+    try:
+        stored = json.loads(token_path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return set()
+    return set(stored.get("scopes") or [])
+
+
+TokenState = Literal["none", "signed-in", "refreshable", "stale"]
+
+
+def token_state(
+    token_path: Path = DEFAULT_TOKEN_PATH, scopes: list[str] | None = None
+) -> TokenState:
+    """What the cached token is still good for, without touching the network."""
+    if not token_path.exists():
+        return "none"
+    expected = scopes if scopes is not None else SCOPES
+    if _scopes_changed(token_path, expected):
+        return "stale"
+    try:
+        creds = Credentials.from_authorized_user_file(str(token_path), expected)
+    except (ValueError, OSError):
+        return "stale"
+
+    if creds.valid:
+        return "signed-in"
+    return "refreshable" if creds.expired and creds.refresh_token else "stale"
+
+
+def authorize_prompt() -> str:
+    """A one-click link; the raw URL only where clicking is impossible anyway."""
+    link = hyperlink("Authorize gfunk in Google", "{url}")
+    return f"\nOpening your browser to sign in.\nIf nothing opens, visit:\n  {link}\n"
+
+
+class MissingClientSecretsError(Exception):
+    """gfunk ships no credentials; the user registers their own GCP OAuth client."""
+
+
+def get_down(
+    client_secrets: Path = DEFAULT_CLIENT_SECRETS,
+    token_path: Path = DEFAULT_TOKEN_PATH,
+    scopes: list[str] | None = None,
+) -> Credentials:
+    """Complete first-run OAuth and cache the resulting token."""
+    scopes = scopes if scopes is not None else SCOPES
+    creds: Credentials | None = None
+
+    if token_path.exists():
+        if _scopes_changed(token_path, scopes):
+            token_path.unlink()
+        else:
+            creds = Credentials.from_authorized_user_file(str(token_path), scopes)
+
+    if creds and creds.valid:
+        return creds
+
+    if creds and creds.expired and creds.refresh_token:
+        creds.refresh(Request())
+    else:
+        kind = classify(client_secrets)
+        if kind != "installed":
+            raise MissingClientSecretsError(diagnose(kind, client_secrets))
+        flow = InstalledAppFlow.from_client_secrets_file(str(client_secrets), scopes)
+        register_browser()
+        creds = flow.run_local_server(
+            port=0,
+            authorization_prompt_message=authorize_prompt(),
+            success_message="gfunk is signed in. Close this tab.",
+        )
+
+    token_path.parent.mkdir(parents=True, exist_ok=True)
+    token_path.write_text(creds.to_json())
+    token_path.chmod(0o600)
+    return creds

gfunk/bootstrap.py

@@ -0,0 +1,183 @@
+"""Guided setup for the one thing gfunk cannot ship: your own OAuth client."""
+
+import json
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+Kind = Literal["installed", "web", "service_account", "unknown", "missing", "malformed"]
+
+PROJECT_PLACEHOLDER = "YOUR_PROJECT_ID"
+
+CONSOLE = "https://console.cloud.google.com"
+_URLS = {
+    "sheets_api": f"{CONSOLE}/apis/library/sheets.googleapis.com",
+    "drive_api": f"{CONSOLE}/apis/library/drive.googleapis.com",
+    "consent": f"{CONSOLE}/auth/overview",
+    "clients": f"{CONSOLE}/auth/clients",
+}
+
+
+@dataclass(frozen=True)
+class Step:
+    number: int
+    title: str
+    lines: list[str] = field(default_factory=list)
+    url: str | None = None
+
+
+def classify(path: Path) -> Kind:
+    """Name the credential family, because every family fails differently."""
+    try:
+        payload = json.loads(path.read_text())
+    except FileNotFoundError:
+        return "missing"
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        return "malformed"
+
+    if not isinstance(payload, dict):
+        return "unknown"
+    for marker in ("installed", "web"):
+        if marker in payload:
+            return marker
+    return "service_account" if payload.get("type") == "service_account" else "unknown"
+
+
+def diagnose(kind: Kind, path: Path) -> str:
+    """Turn a wrong credential file into instructions for getting the right one."""
+    messages = {
+        "missing": (
+            f"No OAuth client secrets at {path}. "
+            "Run `gfunk mount-up` to be walked through creating one."
+        ),
+        "malformed": (
+            f"{path} is not valid JSON. Re-download the client JSON "
+            "from the Google console, or run `gfunk mount-up`."
+        ),
+        "web": (
+            f"{path} is a Web application OAuth client, but gfunk signs in from "
+            "your terminal. Create the client again choosing application type "
+            "'Desktop app', then run `gfunk mount-up`."
+        ),
+        "service_account": (
+            f"{path} is a service account key, not an OAuth client. Service "
+            "accounts have their own identity and see only files explicitly "
+            "shared with them; gfunk signs in as you. Run `gfunk mount-up` to "
+            "create a Desktop app OAuth client instead."
+        ),
+        "unknown": (
+            f"{path} is not an OAuth client JSON — it has no 'installed' "
+            "section. Run `gfunk mount-up` to download the right file."
+        ),
+    }
+    if kind == "installed":
+        message = (
+            "'installed' is the credential gfunk wants; there is nothing to diagnose."
+        )
+        raise ValueError(message)
+    return messages[kind]
+
+
+def project_of(path: Path) -> str | None:
+    """The client JSON names its own project; asking the user for it is redundant."""
+    try:
+        payload = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+        return None
+    if not isinstance(payload, dict):
+        return None
+    section = payload.get("installed") or payload.get("web") or {}
+    project = section.get("project_id") if isinstance(section, dict) else None
+    return str(project) if project else None
+
+
+def console_urls(project: str | None) -> dict[str, str]:
+    suffix = f"?project={project}" if project else ""
+    return {name: url + suffix for name, url in _URLS.items()}
+
+
+def walkthrough(project: str | None) -> list[Step]:
+    urls = console_urls(project)
+    named = project or "your Google Cloud project"
+    return [
+        Step(
+            1,
+            f"Enable the Sheets API in {named}",
+            [
+                "It should read 'API enabled'. If it offers 'Enable', click that.",
+                "Check the project picker up top really says this project.",
+            ],
+            urls["sheets_api"],
+        ),
+        Step(
+            2,
+            "Enable the Drive API — a separate switch, not covered by step 1",
+            [
+                "Every Google API is enabled per project, one at a time.",
+                "gfunk needs both: Sheets to read rows, Drive to find the files.",
+                "Skip this and every `gfunk snoop` fails with 403 accessNotConfigured.",
+            ],
+            urls["drive_api"],
+        ),
+        Step(
+            3,
+            "Configure the OAuth consent screen (first time only)",
+            [
+                "Get started -> App name 'gfunk' -> your email -> Audience: External.",
+                "Then Audience -> Test users -> + Add users -> your account.",
+                "Skipping the test user step causes access_denied later:",
+                "in Testing mode only listed test users may sign in.",
+            ],
+            urls["consent"],
+        ),
+        Step(
+            4,
+            "Create the client",
+            [
+                "+ Create client -> Application type: Desktop app -> Create.",
+                "'Desktop app' matters: a Web client cannot finish this flow.",
+                "Download JSON in the dialog that follows.",
+            ],
+            urls["clients"],
+        ),
+        Step(
+            5,
+            "Install the downloaded JSON",
+            [
+                "Save it as ~/.config/gfunk/credentials.json:",
+                "  mkdir -p ~/.config/gfunk && chmod 700 ~/.config/gfunk",
+                "  mv ~/Downloads/client_secret*.json ~/.config/gfunk/credentials.json",
+                "  chmod 600 ~/.config/gfunk/credentials.json",
+                "Or let gfunk do it:",
+                "  gfunk mount-up --client-secrets <path/to/downloaded.json>",
+                "Then: gfunk mount-up",
+            ],
+        ),
+    ]
+
+
+def default_download_dirs() -> list[Path]:
+    """Downloads, plus the Windows-side one that WSL users actually download into."""
+    dirs = [Path.home() / "Downloads"]
+    dirs.extend(sorted(Path("/mnt/c/Users").glob("*/Downloads")))
+    return dirs
+
+
+def find_candidates(dirs: list[Path]) -> list[Path]:
+    found = [
+        path for directory in dirs for path in directory.glob("client_secret*.json")
+    ]
+    return sorted(found, key=lambda path: path.stat().st_mtime, reverse=True)
+
+
+def install(source: Path, dest: Path) -> Path:
+    kind = classify(source)
+    if kind != "installed":
+        raise ValueError(diagnose(kind, source))
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.parent.chmod(0o700)
+    shutil.copyfile(source, dest)
+    dest.chmod(0o600)
+    return dest

gfunk/browser.py

@@ -0,0 +1,69 @@
+"""Open the OAuth consent page where the human is: a Windows browser, from WSL."""
+
+import subprocess
+import sys
+import webbrowser
+from pathlib import Path
+from typing import Any
+
+PROC_VERSION = Path("/proc/version")
+RUNDLL32 = "/mnt/c/Windows/System32/rundll32.exe"
+POWERSHELL = "/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe"
+
+
+def _powershell_literal(url: str) -> str:
+    """Single-quoted, because -Command re-parses and OAuth URLs are full of '&'."""
+    escaped = url.replace("'", "''")
+    return f"Start-Process '{escaped}'"
+
+
+def under_wsl(proc_version: Path = PROC_VERSION) -> bool:
+    try:
+        return "microsoft" in proc_version.read_text().lower()
+    except OSError:
+        return False
+
+
+class WindowsBrowser(webbrowser.BaseBrowser):
+    """WSL has no browser; Windows does, and Start-Process reaches it."""
+
+    def open(self, url: str, new: int = 0, autoraise: bool = True) -> bool:  # noqa: ARG002, FBT001, FBT002
+        for argv in self.commands(url):
+            try:
+                done = subprocess.run(argv, capture_output=True, check=False)  # noqa: S603
+            except OSError:
+                continue
+            if done.returncode == 0:
+                return True
+        return False
+
+    def commands(self, url: str) -> list[list[str]]:
+        """rundll32 first: it hands the URL to Windows with no shell to re-parse it."""
+        powershell = POWERSHELL if Path(POWERSHELL).exists() else "powershell.exe"
+        return [
+            [RUNDLL32, "url.dll,FileProtocolHandler", url],
+            [powershell, "-NoProfile", "-Command", _powershell_literal(url)],
+        ]
+
+
+def register() -> None:
+    """Make webbrowser.open (and anything built on it) reach the Windows side."""
+    if not under_wsl():
+        return
+    webbrowser.register("gfunk-windows", None, WindowsBrowser(), preferred=True)
+
+
+def hyperlink(text: str, url: str, *, supported: bool | None = None) -> str:
+    """OSC 8: one clickable link, immune to however the terminal wraps the URL."""
+    if supported is None:
+        supported = sys.stdout.isatty()
+    if not supported:
+        return url
+    return f"\x1b]8;;{url}\x1b\\{text}\x1b]8;;\x1b\\"
+
+
+def open_in_browser(item: dict[str, Any]) -> None:
+    link = item.get("webViewLink") or f"https://drive.google.com/open?id={item['id']}"
+    register()
+    if not webbrowser.open(link):
+        print(f"Could not open a browser. The link is:\n  {link}", file=sys.stderr)

gfunk/cache.py

@@ -0,0 +1,123 @@
+"""Local store for bulk Workspace reads.
+
+SQLite rather than Parquet: it is in the stdlib, it is queryable without a
+second engine, and it is one file that can be chmod-ed. The file holds real
+Workspace content, so it is created 0600 and lives outside the repo.
+"""
+
+import json
+import sqlite3
+from collections.abc import Generator, Iterable
+from contextlib import contextmanager
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+DEFAULT_CACHE_PATH = Path.home() / ".local" / "share" / "gfunk" / "cache.db"
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS records (
+    service    TEXT NOT NULL,
+    kind       TEXT NOT NULL,
+    record_id  TEXT NOT NULL,
+    fetched_at TEXT NOT NULL,
+    payload    TEXT NOT NULL,
+    PRIMARY KEY (service, kind, record_id)
+);
+"""
+
+
+class Cache:
+    """Records keyed by (service, kind, record_id), payloads as JSON text."""
+
+    def __init__(self, path: Path = DEFAULT_CACHE_PATH) -> None:
+        self.path = path
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        # Create the file before writing to it so the 0600 is in place first;
+        # sqlite would otherwise create it 0644 and the content would sit
+        # world-readable for the width of the connect.
+        self.path.touch(mode=0o600, exist_ok=True)
+        self.path.chmod(0o600)
+        with self._connect() as conn:
+            conn.executescript(SCHEMA)
+
+    @contextmanager
+    def _connect(self) -> Generator[sqlite3.Connection]:
+        conn = sqlite3.connect(self.path)
+        try:
+            yield conn
+            conn.commit()
+        except BaseException:
+            conn.rollback()
+            raise
+        finally:
+            conn.close()
+
+    def put(self, service: str, kind: str, record_id: str, payload: Any) -> None:
+        self.put_many(service, kind, [(record_id, payload)])
+
+    def put_many(
+        self, service: str, kind: str, records: Iterable[tuple[str, Any]]
+    ) -> None:
+        now = datetime.now(UTC).isoformat()
+        rows = [
+            (service, kind, record_id, now, json.dumps(payload))
+            for record_id, payload in records
+        ]
+        with self._connect() as conn:
+            conn.executemany(
+                """
+                INSERT INTO records (service, kind, record_id, fetched_at, payload)
+                VALUES (?, ?, ?, ?, ?)
+                ON CONFLICT (service, kind, record_id) DO UPDATE SET
+                    fetched_at = excluded.fetched_at,
+                    payload    = excluded.payload
+                """,
+                rows,
+            )
+
+    def get(self, service: str, kind: str, record_id: str) -> Any | None:
+        with self._connect() as conn:
+            row = conn.execute(
+                """
+                SELECT payload FROM records
+                WHERE service = ? AND kind = ? AND record_id = ?
+                """,
+                (service, kind, record_id),
+            ).fetchone()
+        return json.loads(row[0]) if row else None
+
+    def fetched_at(self, service: str, kind: str, record_id: str) -> str | None:
+        with self._connect() as conn:
+            row = conn.execute(
+                """
+                SELECT fetched_at FROM records
+                WHERE service = ? AND kind = ? AND record_id = ?
+                """,
+                (service, kind, record_id),
+            ).fetchone()
+        return str(row[0]) if row else None
+
+    def records(self, service: str, kind: str, limit: int | None = None) -> list[Any]:
+        sql = """
+            SELECT payload FROM records
+            WHERE service = ? AND kind = ?
+            ORDER BY record_id
+        """
+        params: tuple[Any, ...] = (service, kind)
+        if limit is not None:
+            sql += " LIMIT ?"
+            params = (*params, limit)
+        with self._connect() as conn:
+            rows = conn.execute(sql, params).fetchall()
+        return [json.loads(row[0]) for row in rows]
+
+    def clear(self, service: str, kind: str | None = None) -> None:
+        with self._connect() as conn:
+            if kind is None:
+                conn.execute("DELETE FROM records WHERE service = ?", (service,))
+            else:
+                conn.execute(
+                    "DELETE FROM records WHERE service = ? AND kind = ?",
+                    (service, kind),
+                )