insightfactory-cli 1.0.0.dev1__py3-none-any.whl

if_cli/__init__.py

@@ -0,0 +1 @@
+"""InsightFactory CLI."""

if_cli/__main__.py

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

if_cli/cache.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+import json
+import math
+import os
+import time
+from collections.abc import Callable
+from typing import TypedDict, TypeGuard, TypeVar
+
+from if_cli.config import cache_file, write_private_file
+from if_cli.constants import EXPIRY_SLACK_SECONDS
+from if_cli.runtime import die, is_record
+
+CACHE_LOCK_STALE_MS = 30_000
+
+
+class CacheEntry(TypedDict, total=False):
+    access_token: str
+    refresh_token: str
+    expires_at: float
+    token_endpoint: str
+    client_id: str
+
+
+class TokenCache(TypedDict):
+    version: int
+    tokens: dict[str, CacheEntry]
+
+
+def _positive_integer_env(name: str, fallback: int) -> int:
+    raw = os.environ.get(name)
+    if raw is None:
+        return fallback
+    try:
+        value = float(raw)
+    except (TypeError, ValueError):
+        return fallback
+    if math.isfinite(value) and value == int(value) and value > 0:
+        return int(value)
+    return fallback
+
+
+def _cache_lock_file() -> str:
+    return f"{cache_file()}.lock"
+
+
+def _cache_lock_attempts() -> int:
+    return _positive_integer_env("INSIGHTFACTORY_CACHE_LOCK_ATTEMPTS", 200)
+
+
+def _cache_lock_retry_ms() -> int:
+    return _positive_integer_env("INSIGHTFACTORY_CACHE_LOCK_RETRY_MS", 25)
+
+
+def is_fresh(entry: CacheEntry, now_seconds: float | None = None) -> bool:
+    if now_seconds is None:
+        now_seconds = time.time()
+    return entry["expires_at"] - EXPIRY_SLACK_SECONDS > now_seconds
+
+
+def _is_cache_entry(value: object) -> TypeGuard[CacheEntry]:
+    if not is_record(value):
+        return False
+    access_token = value.get("access_token")
+    expires_at = value.get("expires_at")
+    token_endpoint = value.get("token_endpoint")
+    refresh_token = value.get("refresh_token")
+    client_id = value.get("client_id")
+    return (
+        isinstance(access_token, str)
+        and isinstance(expires_at, (int, float))
+        and not isinstance(expires_at, bool)
+        and math.isfinite(float(expires_at))
+        and isinstance(token_endpoint, str)
+        and ("refresh_token" not in value or isinstance(refresh_token, str))
+        and ("client_id" not in value or isinstance(client_id, str))
+    )
+
+
+def _parse_cache(raw: str) -> TokenCache:
+    value: object = json.loads(raw)
+    if not is_record(value):
+        die(f"token cache {cache_file()} has an invalid structure; move it aside and log in again")
+    tokens_value = value.get("tokens")
+    if value.get("version") != 1 or not is_record(tokens_value):
+        die(f"token cache {cache_file()} has an invalid structure; move it aside and log in again")
+    tokens: dict[str, CacheEntry] = {}
+    for host, entry in tokens_value.items():
+        if not _is_cache_entry(entry):
+            die(f"token cache entry for {host} is invalid; move {cache_file()} aside and log in again")
+        tokens[host] = entry
+    return {"version": 1, "tokens": tokens}
+
+
+def load_cache() -> TokenCache:
+    try:
+        with open(cache_file(), encoding="utf-8") as handle:
+            return _parse_cache(handle.read())
+    except FileNotFoundError:
+        return {"version": 1, "tokens": {}}
+    except json.JSONDecodeError:
+        die(f"token cache {cache_file()} is not valid JSON; move it aside and log in again")
+
+
+def _save_cache(cache: TokenCache) -> None:
+    write_private_file(cache_file(), f"{json.dumps(cache, indent=2)}\n")
+
+
+T = TypeVar("T")
+
+
+def with_cache_lock(operation: Callable[[], T]) -> T:
+    lock_file = _cache_lock_file()
+    os.makedirs(os.path.dirname(lock_file), mode=0o700, exist_ok=True)
+    attempts = _cache_lock_attempts()
+    retry_ms = _cache_lock_retry_ms()
+    for _attempt in range(attempts):
+        try:
+            descriptor = os.open(lock_file, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        except FileExistsError:
+            try:
+                mtime_ms = os.stat(lock_file).st_mtime * 1000
+                if time.time() * 1000 - mtime_ms > CACHE_LOCK_STALE_MS:
+                    os.unlink(lock_file)
+                    continue
+            except OSError:
+                pass
+            time.sleep(retry_ms / 1000)
+            continue
+        try:
+            return operation()
+        finally:
+            os.close(descriptor)
+            try:
+                os.unlink(lock_file)
+            except OSError:
+                pass
+    die(f"timed out waiting for token cache lock {lock_file}")
+
+
+def clear_token(host: str) -> bool:
+    def operation() -> bool:
+        cache = load_cache()
+        if host not in cache["tokens"]:
+            return False
+        del cache["tokens"][host]
+        _save_cache(cache)
+        return True
+
+    return with_cache_lock(operation)
+
+
+def clear_refresh_token_if_matches(host: str, rejected_token: str) -> bool:
+    def operation() -> bool:
+        cache = load_cache()
+        entry = cache["tokens"].get(host)
+        if not entry or entry.get("refresh_token") != rejected_token:
+            return False
+        entry.pop("refresh_token", None)
+        _save_cache(cache)
+        return True
+
+    return with_cache_lock(operation)
+
+
+def store_tokens(
+    host: str,
+    token_response: dict[str, object],
+    token_endpoint: str,
+    client_id: str | None = None,
+    *,
+    replace: bool = False,
+) -> CacheEntry:
+    def operation() -> CacheEntry:
+        cache = load_cache()
+        previous = None if replace else cache["tokens"].get(host)
+        expires_in_raw = token_response.get("expires_in")
+        if (
+            isinstance(expires_in_raw, bool)
+            or not isinstance(expires_in_raw, (int, float))
+            or not math.isfinite(float(expires_in_raw))
+        ):
+            expires_in: int | float = 3600
+        else:
+            expires_in = expires_in_raw
+        entry: CacheEntry = previous.copy() if previous is not None else {}
+        access_token = token_response.get("access_token")
+        if not isinstance(access_token, str):
+            die("token response did not include a valid access token")
+        entry["access_token"] = access_token
+        entry["expires_at"] = int(math.floor(time.time()) + expires_in)
+        entry["token_endpoint"] = token_endpoint
+        if client_id:
+            entry["client_id"] = client_id
+        else:
+            entry.pop("client_id", None)
+        refresh_token = token_response.get("refresh_token")
+        if isinstance(refresh_token, str) and refresh_token:
+            entry["refresh_token"] = refresh_token
+        elif replace:
+            entry.pop("refresh_token", None)
+        cache["tokens"][host] = entry
+        _save_cache(cache)
+        return entry
+
+    return with_cache_lock(operation)

if_cli/cli.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Callable
+from typing import Any, NoReturn
+
+from if_cli.runtime import die, get_exit_code, handle_broken_pipe, install_broken_pipe_handlers
+
+Options = dict[str, dict[str, Any]]
+
+
+class _ArgumentParser(argparse.ArgumentParser):
+    def error(self, message: str) -> NoReturn:
+        # Node util.parseArgs reports "Unknown option '--flag'". argparse says
+        # "unrecognized arguments: --flag"; rewrite the common case so the two
+        # CLIs fail with the same wording.
+        if message.startswith("unrecognized arguments: "):
+            unknown = message.removeprefix("unrecognized arguments: ").split()[0]
+            die(f"Unknown option '{unknown}'")
+        die(message)
+
+
+def parse_args(
+    argv: list[str],
+    *,
+    options: Options,
+    allow_positionals: bool = False,
+) -> tuple[dict[str, Any], list[str]]:
+    """Parse argv with argparse, using the same flags as the TypeScript parseArgs specs."""
+    parser = _ArgumentParser(add_help=False, allow_abbrev=False)
+    for name, spec in options.items():
+        flags = [f"--{name}"]
+        short = spec.get("short")
+        if short:
+            flags.append(f"-{short}")
+        dest = name.replace("-", "_")
+        if spec["type"] == "boolean":
+            parser.add_argument(*flags, dest=dest, action="store_true", default=spec.get("default", False))
+        else:
+            parser.add_argument(*flags, dest=dest, default=spec.get("default"))
+    if allow_positionals:
+        parser.add_argument("positionals", nargs="*")
+    namespace = parser.parse_args(argv)
+    raw = vars(namespace)
+    values = {name: raw.get(name.replace("-", "_")) for name in options}
+    if allow_positionals:
+        return values, list(raw.get("positionals") or [])
+    return values, []
+
+
+def run_with_handlers(run_cli: Callable[[list[str]], None], argv: list[str] | None = None) -> None:
+    install_broken_pipe_handlers()
+    try:
+        run_cli(sys.argv[1:] if argv is None else argv)
+        # Force any buffered EPIPE to raise here. Python 3.14 can keep the
+        # entire command output in the TextIOWrapper until shutdown, where an
+        # unhandled BrokenPipeError becomes exit status 120.
+        sys.stdout.flush()
+    except BrokenPipeError:
+        handle_broken_pipe()
+    except Exception as error:
+        try:
+            sys.stderr.write(f"if-cli: {error}\n")
+        except BrokenPipeError:
+            handle_broken_pipe()
+        raise SystemExit(1) from None
+    raise SystemExit(get_exit_code())

if_cli/colour.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import os
+import sys
+from typing import Literal
+
+Colour = Literal["green", "yellow", "red"]
+CODES: dict[Colour, int] = {"green": 32, "yellow": 33, "red": 31}
+
+
+def colours_enabled() -> bool:
+    no_color = os.environ.get("NO_COLOR")
+    if no_color is not None and no_color != "":
+        return False
+    force_color = os.environ.get("FORCE_COLOR")
+    if force_color is not None and force_color != "0":
+        return True
+    return sys.stdout.isatty() and os.environ.get("TERM") != "dumb"
+
+
+def colourise(value: str, colour: Colour) -> str:
+    if not colours_enabled():
+        return value
+    return f"\033[{CODES[colour]}m{value}\033[0m"

if_cli/commands/api.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import json
+import re
+import sys
+from typing import Any
+from urllib.parse import ParseResult
+
+from if_cli.cli import Options, parse_args
+from if_cli.config import get_profile, load_config, resolve_profile_name
+from if_cli.http import fetch_with_timeout, parse_url, url_href, url_origin
+from if_cli.oauth import get_valid_token
+from if_cli.runtime import die, is_record, set_exit_code
+
+HTTP_METHODS: tuple[str, ...] = ("get", "post", "put", "patch", "delete", "options", "head", "trace")
+REQUEST_METHODS = {"GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"}
+WINDOWS_DRIVE_PATH = re.compile(r"^[A-Za-z]:[\\/]")
+MSYS_PREFIX = re.compile(r"^[A-Za-z]:.*?(?=[\\/]api(?:[\\/]|$))")
+
+API_OPTIONS: Options = {
+    "profile": {"type": "string", "short": "p"},
+    "method": {"type": "string", "short": "X"},
+    "data": {"type": "string", "short": "d"},
+}
+
+API_USAGE = (
+    "usage: if-cli api [-p profile] [-X METHOD] [-d DATA] /api/path\n"
+    "       if-cli api routes [-p profile] [filter]\n"
+    "       if-cli api describe [-p profile] METHOD /api/path"
+)
+
+
+def discover_routes(document: dict[str, Any], filter_text: str | None = None) -> list[str]:
+    normalized_filter = filter_text.lower() if filter_text else None
+    routes: list[str] = []
+    paths = document.get("paths") or {}
+    for path, path_item in paths.items():
+        if not isinstance(path_item, dict):
+            continue
+        for method in HTTP_METHODS:
+            operation = path_item.get(method)
+            if not operation:
+                continue
+            summary = operation.get("summary") if isinstance(operation, dict) else None
+            line = f"{method.upper():<7} {path}"
+            if summary:
+                line += f"  {summary}"
+            if not normalized_filter or normalized_filter in line.lower():
+                routes.append(line)
+    return sorted(routes)
+
+
+def describe_route(document: dict[str, Any], method: str, path: str) -> dict[str, Any] | None:
+    normalized_method = method.lower()
+    if normalized_method not in HTTP_METHODS:
+        return None
+    path_item = (document.get("paths") or {}).get(path)
+    if not isinstance(path_item, dict) or normalized_method not in path_item:
+        return None
+    operation = path_item[normalized_method]
+    return operation if isinstance(operation, dict) else None
+
+
+def _die_on_msys_mangled_path(api_path: str) -> None:
+    if not WINDOWS_DRIVE_PATH.search(api_path):
+        return
+    recovered = MSYS_PREFIX.sub("", api_path).replace("\\", "/")
+    intended = f" The intended path looks like '{recovered}'." if recovered.startswith("/") else ""
+    die(
+        f"the API path '{api_path}' is a Windows filesystem path, not an API path.{intended}\n"
+        "        On Git Bash, MSYS path conversion rewrites leading-slash arguments this way;\n"
+        "        prefix the command with MSYS_NO_PATHCONV=1."
+    )
+
+
+def _is_absolute_http_url(api_path: str) -> bool:
+    parsed = parse_url(api_path)
+    return parsed.scheme in {"http", "https"} and bool(parsed.hostname)
+
+
+def resolve_api_url(host: str, api_path: str) -> ParseResult:
+    if not api_path.startswith("/") and not _is_absolute_http_url(api_path):
+        _die_on_msys_mangled_path(api_path)
+        die("API path must begin with '/' or be an absolute http(s) URL on the selected factory origin")
+    profile_parsed = parse_url(host)
+    url = parse_url(api_path, host)
+    profile_origin = url_origin(profile_parsed)
+    resolved_origin = url_origin(url)
+    if resolved_origin != profile_origin:
+        die(f"refusing to send the profile token to {resolved_origin}; selected factory origin is {profile_origin}")
+    if url.username or url.password:
+        die("API path must not embed credentials; the profile token authenticates the request")
+    return url
+
+
+def _fetch_openapi(host: str) -> dict[str, Any]:
+    url = f"{host}/swagger/v1/swagger.json"
+    response = fetch_with_timeout(url)
+    if not response.ok:
+        die(f"API discovery failed for {host} (HTTP {response.status})")
+    try:
+        body: object = response.json()
+    except json.JSONDecodeError:
+        die(f"API discovery for {host} did not return valid JSON")
+    if not is_record(body):
+        die(f"API discovery for {host} has no paths")
+    if not is_record(body.get("paths")):
+        die(f"API discovery for {host} has no paths")
+    return body
+
+
+def _routes_command(positionals: list[str], profile_name: str | None) -> None:
+    profile = get_profile(load_config(), resolve_profile_name(profile_name))
+    filter_text = positionals[1] if len(positionals) > 1 else None
+    routes = discover_routes(_fetch_openapi(profile["host"]), filter_text)
+    if not routes:
+        die(f"no API routes matched '{filter_text or ''}'")
+    sys.stdout.write(f"{chr(10).join(routes)}\n")
+
+
+def _describe_command(positionals: list[str], profile_name: str | None) -> None:
+    method = positionals[1].upper() if len(positionals) > 1 and positionals[1] else None
+    path = positionals[2] if len(positionals) > 2 else None
+    if not method or not path:
+        die("usage: if-cli api describe [-p profile] METHOD /api/path")
+    if not path.startswith("/"):
+        _die_on_msys_mangled_path(path)
+        die(f"API path must begin with '/'; '{path}' is not a discovery document path")
+    profile = get_profile(load_config(), resolve_profile_name(profile_name))
+    operation = describe_route(_fetch_openapi(profile["host"]), method, path)
+    if not operation:
+        die(f"{method} {path} was not found in the API discovery document")
+    sys.stdout.write(f"{json.dumps({'method': method, 'path': path, **operation}, indent=2)}\n")
+
+
+def api_command(argv: list[str]) -> None:
+    values, positionals = parse_args(argv, options=API_OPTIONS, allow_positionals=True)
+    if positionals and positionals[0] == "routes":
+        _routes_command(positionals, values["profile"])
+        return
+    if positionals and positionals[0] == "describe":
+        _describe_command(positionals, values["profile"])
+        return
+
+    api_path = positionals[0] if positionals else None
+    if not api_path:
+        die(API_USAGE)
+
+    if values["method"] is not None:
+        method = values["method"].upper()
+    else:
+        method = "POST" if values["data"] is not None else "GET"
+    if method not in REQUEST_METHODS:
+        die(f"unsupported request method '{method}'; use GET, POST, PUT, PATCH, DELETE, OPTIONS, or HEAD")
+    if values["data"] is not None and method in {"GET", "HEAD"}:
+        die("-d cannot be used with GET or HEAD")
+    profile = get_profile(load_config(), resolve_profile_name(values["profile"]))
+    resolved = resolve_api_url(profile["host"], api_path)
+    url = url_href(resolved)
+    token = get_valid_token(profile)
+    headers = {"Authorization": f"Bearer {token}"}
+    if values["data"] is not None:
+        headers["Content-Type"] = "application/json"
+    response = fetch_with_timeout(url, method=method, headers=headers, body=values["data"])
+    sys.stderr.write(f"HTTP {response.status}\n")
+    body = response.text()
+    if body:
+        content_type = response.header("content-type") or ""
+        if "json" in content_type:
+            try:
+                sys.stdout.write(f"{json.dumps(json.loads(body), indent=2)}\n")
+            except json.JSONDecodeError:
+                sys.stdout.write(f"{body}\n")
+        else:
+            sys.stdout.write(f"{body}\n")
+    if response.status >= 400:
+        set_exit_code(1)

if_cli/commands/config.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+
+from if_cli.cli import Options, parse_args
+from if_cli.config import Profile, get_profile, load_config, resolve_profile_name
+from if_cli.runtime import die
+
+READABLE_KEYS: dict[str, Callable[[Profile], str | None]] = {
+    "host": lambda profile: profile["host"],
+    "audience": lambda profile: profile["audience"],
+    "callback_port": lambda profile: str(profile["callback_port"]),
+    "client_id": lambda profile: profile.get("client_id"),
+    "organization": lambda profile: profile.get("organization"),
+}
+
+CONFIG_USAGE = f"""usage: if-cli config get <key> [-p profile]
+
+readable keys: {", ".join(READABLE_KEYS)}"""
+
+CONFIG_OPTIONS: Options = {
+    "profile": {"type": "string", "short": "p"},
+}
+
+
+def config_command(argv: list[str]) -> None:
+    values, positionals = parse_args(argv, options=CONFIG_OPTIONS, allow_positionals=True)
+    subcommand = positionals[0] if positionals else None
+    key = positionals[1] if len(positionals) > 1 else None
+    extra = positionals[2:]
+    if subcommand != "get":
+        die(CONFIG_USAGE if subcommand is None else f"unknown config subcommand '{subcommand}'\n\n{CONFIG_USAGE}")
+    if key is None:
+        die(CONFIG_USAGE)
+    if extra:
+        die(f"config get takes a single key\n\n{CONFIG_USAGE}")
+    if key not in READABLE_KEYS:
+        die(f"'{key}' is not a readable config key; readable keys are {', '.join(READABLE_KEYS)}")
+
+    profile: Profile = get_profile(load_config(), resolve_profile_name(values["profile"]))
+    value = READABLE_KEYS[key](profile)
+    if value is None:
+        die(f"profile '{profile['name']}' has no {key} configured")
+    sys.stdout.write(f"{value}\n")

if_cli/commands/login.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import sys
+
+from if_cli.cli import Options, parse_args
+from if_cli.config import (
+    INI_UNSAFE_VALUE,
+    empty_section,
+    get_profile,
+    load_config,
+    parse_callback_port,
+    resolve_profile_name,
+    save_config,
+)
+from if_cli.http import normalize_origin, validate_audience_url
+from if_cli.oauth import login
+from if_cli.runtime import die, format_expiry
+
+LOGIN_OPTIONS: Options = {
+    "profile": {"type": "string", "short": "p"},
+    "host": {"type": "string"},
+    "client-id": {"type": "string"},
+    "organization": {"type": "string"},
+    "audience": {"type": "string"},
+    "callback-port": {"type": "string"},
+    "no-browser": {"type": "boolean", "default": False},
+}
+
+
+def login_command(argv: list[str]) -> None:
+    values, _positionals = parse_args(argv, options=LOGIN_OPTIONS)
+    name = resolve_profile_name(values["profile"])
+    has_overrides = any(
+        values[key] is not None for key in ("host", "client-id", "organization", "audience", "callback-port")
+    )
+
+    def apply_overrides(config: dict[str, dict[str, str]]) -> dict[str, dict[str, str]]:
+        key = "" if name == "DEFAULT" else name
+        section = config.setdefault(key, empty_section())
+        if values["host"] is not None:
+            section["host"] = normalize_origin(values["host"], "host")
+        if values["client-id"] is not None:
+            if not values["client-id"].strip():
+                die("client ID cannot be empty")
+            if INI_UNSAFE_VALUE.search(values["client-id"]):
+                die("--client-id cannot contain newlines or carriage returns")
+            section["client_id"] = values["client-id"]
+        if values["organization"] is not None:
+            if not values["organization"].strip():
+                die("organization cannot be empty")
+            if INI_UNSAFE_VALUE.search(values["organization"]):
+                die("--organization cannot contain newlines or carriage returns")
+            section["organization"] = values["organization"]
+        if values["audience"] is not None:
+            if INI_UNSAFE_VALUE.search(values["audience"]):
+                die("--audience cannot contain newlines or carriage returns")
+            section["audience"] = validate_audience_url(values["audience"].strip(), "audience")
+        if values["callback-port"] is not None:
+            section["callback_port"] = str(parse_callback_port(values["callback-port"]))
+        return config
+
+    profile = get_profile(apply_overrides(load_config()) if has_overrides else load_config(), name)
+    login_options: dict[str, str] = {}
+    if values["client-id"] is not None:
+        login_options["client_id_override"] = values["client-id"]
+    if values["organization"] is not None:
+        login_options["organization_override"] = values["organization"]
+    entry = login(profile, bool(values["no-browser"]), login_options)
+    if has_overrides:
+        save_config(apply_overrides(load_config()))
+    refreshable = "with refresh token" if entry.get("refresh_token") else "NO refresh token"
+    sys.stdout.write(
+        f"✓ logged in to {profile['host']} (profile '{name}', access token valid until "
+        f"{format_expiry(int(entry['expires_at']))}, {refreshable})\n"
+    )

if_cli/commands/logout.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import sys
+
+from if_cli.cache import clear_token
+from if_cli.cli import Options, parse_args
+from if_cli.config import get_profile, load_config, resolve_profile_name
+
+LOGOUT_OPTIONS: Options = {
+    "profile": {"type": "string", "short": "p"},
+}
+
+
+def logout_command(argv: list[str]) -> None:
+    values, _positionals = parse_args(argv, options=LOGOUT_OPTIONS)
+    profile = get_profile(load_config(), resolve_profile_name(values["profile"]))
+    removed = clear_token(profile["host"])
+    sys.stdout.write(
+        f"✓ cleared cached token for {profile['host']}\n" if removed else f"no cached token for {profile['host']}\n"
+    )