hiringcafe-cli 0.1.4__py3-none-any.whl

hiringcafe_cli/__init__.py

@@ -0,0 +1,152 @@
+"""HiringCafe CLI package interface."""
+
+import argparse
+import sys
+
+from hiringcafe_cli import (
+    auth,
+    count,
+    job,
+    probe,
+    saved_jobs_list,
+    saved_jobs_remove,
+    saved_jobs_save,
+    saved_jobs_stage,
+    search,
+)
+from hiringcafe_cli.cache import CacheStore, active_cache_root
+from hiringcafe_cli.firebase import FirebaseAuthError, FirebaseTransportError
+from hiringcafe_cli.http_client import HireCafeHTTPError, HireCafeTransportError
+from hiringcafe_cli.saved_jobs import VALID_STAGES
+from hiringcafe_cli.saved_jobs_list import FirestoreError
+from hiringcafe_cli.search_state import InvalidSearchState
+
+__version__ = "0.1.0"
+
+EXIT_CONTRACT = """\
+Exit codes:
+  0 success
+  1 transport, HTTP, parsing, or API error
+  2 invalid arguments or search state
+  3 rate limited
+  4 no stored credential
+  5 stored credential rejected
+  6 write conflict or prerequisite missing
+"""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the root CLI parser.
+
+    Returns:
+        An argparse parser implementing the PR 0.1 bootstrap contract.
+    """
+    parser = argparse.ArgumentParser(
+        prog="hiringcafe",
+        description="Hiring Cafe command-line interface",
+        epilog=EXIT_CONTRACT,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    cache_options = argparse.ArgumentParser(add_help=False)
+    cache_options.add_argument("--no-cache", action="store_true")
+    cache_options.add_argument("--cache-ttl", type=int)
+    subparsers = parser.add_subparsers(dest="command")
+    probe_parser = subparsers.add_parser("probe", help="run the opt-in live endpoint probe")
+    probe_parser.set_defaults(handler=probe.main)
+    search_parser = subparsers.add_parser("search", help="search jobs", parents=[cache_options])
+    search_parser.add_argument("query", nargs="?", default="")
+    search_parser.add_argument("--page", type=int, default=0)
+    search_parser.add_argument("--pages", type=int, default=1)
+    search_parser.add_argument("--raw-search-state")
+    search_parser.add_argument("--json", action="store_true")
+    search_parser.add_argument("--jsonl", action="store_true")
+    search_parser.set_defaults(handler=search.run)
+    count_parser = subparsers.add_parser("count", help="print total result count", parents=[cache_options])
+    count_parser.add_argument("query", nargs="?", default="")
+    count_parser.add_argument("--raw-search-state")
+    count_parser.add_argument("--json", action="store_true")
+    count_parser.set_defaults(handler=count.run)
+    job_parser = subparsers.add_parser("job", help="inspect job details")
+    job_subparsers = job_parser.add_subparsers(dest="job_command", required=True)
+    job_show_parser = job_subparsers.add_parser("show", help="show a job description", parents=[cache_options])
+    job_show_parser.add_argument("object_id")
+    job_show_parser.add_argument("--json", action="store_true")
+    job_show_parser.set_defaults(handler=job.run)
+    auth_parser = subparsers.add_parser("auth", help="manage Firebase authentication")
+    auth_subparsers = auth_parser.add_subparsers(dest="auth_command", required=True)
+    auth_login_parser = auth_subparsers.add_parser("login", help="log in to Firebase")
+    auth_login_parser.add_argument("--email", required=True)
+    auth_login_parser.set_defaults(handler=auth.login_email)
+    auth_import_parser = auth_subparsers.add_parser("import", help="import a refresh token")
+    auth_import_parser.set_defaults(handler=auth.import_token)
+    auth_status_parser = auth_subparsers.add_parser("status", help="show credential status")
+    auth_status_parser.add_argument("--json", action="store_true")
+    auth_status_parser.set_defaults(handler=auth.status)
+    auth_logout_parser = auth_subparsers.add_parser("logout", help="remove the local session")
+    auth_logout_parser.set_defaults(handler=auth.logout)
+    saved_parser = subparsers.add_parser("saved-jobs", help="manage saved jobs")
+    saved_subparsers = saved_parser.add_subparsers(dest="saved_command", required=True)
+    saved_list_parser = saved_subparsers.add_parser("list", help="list saved jobs")
+    saved_list_parser.add_argument("--stage", choices=sorted(VALID_STAGES))
+    saved_list_parser.add_argument("--json", action="store_true")
+    saved_list_parser.set_defaults(handler=saved_jobs_list.run)
+    saved_save_parser = saved_subparsers.add_parser("save", help="save a job")
+    saved_save_parser.add_argument("object_id")
+    saved_save_parser.add_argument("--stage", default="saved")
+    saved_save_parser.set_defaults(handler=saved_jobs_save.run)
+    saved_stage_parser = saved_subparsers.add_parser("stage", help="update a job stage")
+    saved_stage_parser.add_argument("object_id")
+    saved_stage_parser.add_argument("--stage", required=True)
+    saved_stage_parser.set_defaults(handler=saved_jobs_stage.run)
+    saved_remove_parser = saved_subparsers.add_parser("remove", help="remove a saved job")
+    saved_remove_parser.add_argument("object_id")
+    saved_remove_parser.add_argument("--yes", action="store_true")
+    saved_remove_parser.set_defaults(handler=saved_jobs_remove.run)
+    cache_parser = subparsers.add_parser("cache", help="manage anonymous read cache")
+    cache_subparsers = cache_parser.add_subparsers(dest="cache_command", required=True)
+    cache_purge_parser = cache_subparsers.add_parser("purge", help="remove cached anonymous reads")
+    cache_purge_parser.set_defaults(handler=cache_purge)
+    return parser
+
+
+def cache_purge(argv=None, json_output: bool = False) -> int:
+    """Purge all anonymous cache files."""
+    CacheStore(active_cache_root()).purge()
+    print("Cache purged")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Run the command-line interface.
+
+    Args:
+        argv: Optional argv list; defaults to ``sys.argv[1:]``.
+    """
+    arguments = build_parser().parse_args(argv)
+    handler = getattr(arguments, "handler", None)
+    if handler is not None:
+        json_output = getattr(arguments, "json", False)
+        try:
+            raise SystemExit(handler(arguments, json_output))
+        except InvalidSearchState as error:
+            print(f"hiringcafe: {error}", file=sys.stderr)
+            raise SystemExit(2) from error
+        except ValueError as error:
+            print(f"hiringcafe: {error}", file=sys.stderr)
+            raise SystemExit(1) from error
+        except FirebaseAuthError as error:
+            print(f"hiringcafe: {error}", file=sys.stderr)
+            raise SystemExit(5) from error
+        except FirebaseTransportError as error:
+            print(f"hiringcafe: {error}", file=sys.stderr)
+            raise SystemExit(1) from error
+        except FirestoreError as error:
+            print(f"hiringcafe: {error}", file=sys.stderr)
+            raise SystemExit(1) from error
+        except HireCafeHTTPError as error:
+            print(f"hiringcafe: {error}", file=sys.stderr)
+            raise SystemExit(3 if error.status == 429 else 1) from error
+        except HireCafeTransportError as error:
+            print(f"hiringcafe: {error}", file=sys.stderr)
+            raise SystemExit(1) from error

hiringcafe_cli/auth.py

@@ -0,0 +1,95 @@
+"""Firebase authentication commands."""
+
+import getpass
+import json
+import os
+import sys
+from pathlib import Path
+
+from hiringcafe_cli.firebase import FirebaseClient
+from hiringcafe_cli.session import SessionStore
+
+
+def default_session_path() -> Path:
+    """Return the platform user config session path."""
+    config_home = os.environ.get("HIRINGCAFE_CONFIG_HOME")
+    if config_home:
+        return Path(config_home) / "session.json"
+    return Path.home() / ".config" / "hiringcafe-cli" / "session.json"
+
+
+def store() -> SessionStore:
+    """Create the session store using the selected configuration root."""
+    return SessionStore(default_session_path())
+
+
+def import_token(argv: object, json_output: bool = False) -> int:
+    """Import a refresh token through stdin or the nonprinting environment."""
+    token = sys.stdin.readline().strip() or os.environ.get("HIRINGCAFE_REFRESH_TOKEN", "")
+    if not token:
+        print("hiringcafe: no refresh token provided on stdin or HIRINGCAFE_REFRESH_TOKEN", file=sys.stderr)
+        return 2
+    credentials = FirebaseClient().refresh(token)
+    store().save(credentials["refreshToken"])
+    print("Authenticated Firebase session saved")
+    return 0
+
+
+def login_email(argv: object, json_output: bool = False) -> int:
+    """Exchange Firebase email/password credentials once and save only the refresh token."""
+    password = os.environ.get("HIRINGCAFE_PASSWORD") or getpass.getpass("Firebase password: ")
+    credentials = FirebaseClient().login_with_password(argv.email, password)
+    del password
+    store().save(credentials["refreshToken"])
+    print("Authenticated Firebase session saved")
+    return 0
+
+
+def status(argv: object, json_output: bool = False) -> int:
+    """Report whether the stored Firebase credential can obtain an ID token.
+
+    Args:
+        argv: Unused CLI namespace.
+        json_output: Whether stdout must be machine-readable.
+
+    Returns:
+        Exit code 0 when usable, 4 when no session exists.
+    """
+    session = store().load()
+    if session is None:
+        if json_output:
+            print(json.dumps({"version": 1, "authenticated": False}, separators=(",", ":")))
+        else:
+            print("No stored credential", file=sys.stderr)
+        return 4
+    FirebaseClient().refresh(session.refresh_token)
+    if json_output:
+        payload = json.dumps(
+            {"version": 1, "authenticated": True},
+            separators=(",", ":"),
+        )
+        print(payload)
+    else:
+        print("Authenticated")
+    return 0
+
+
+def logout(argv: object, json_output: bool = False) -> int:
+    """Delete the local Firebase session.
+
+    Args:
+        argv: Unused CLI namespace.
+        json_output: Unused; logout output remains intentionally human-only.
+
+    Returns:
+        Exit code 0 after local credential removal.
+    """
+    session_store = store()
+    had_session = session_store.load() is not None
+    try:
+        session_store.delete()
+    except OSError as error:
+        print(f"hiringcafe: cannot remove session: {error}", file=sys.stderr)
+        return 1
+    print("Local Firebase session removed" if had_session else "No local Firebase session")
+    return 0

hiringcafe_cli/cache.py

@@ -0,0 +1,98 @@
+"""Owner-only anonymous-read TTL cache."""
+
+import hashlib
+import json
+import os
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+VERSION = 1
+
+
+def default_cache_root(base: Path) -> Path:
+    """Return the versioned cache root under a configuration base."""
+    return base / "cache" / "v1"
+
+
+def active_cache_root() -> Path:
+    """Return the configured or user-default cache root."""
+    configured = os.environ.get("HIRINGCAFE_CACHE_HOME")
+    if configured:
+        return default_cache_root(Path(configured))
+    return default_cache_root(Path.home() / ".cache" / "hiringcafe-cli")
+
+
+class CacheStore:
+    def __init__(self, root: Path) -> None:
+        self.root = root
+
+    def path(self, key: tuple) -> Path:
+        raw = json.dumps(key, separators=(",", ":"), sort_keys=True)
+        name = hashlib.sha256(raw.encode()).hexdigest()
+        return self.root / f"{name}.json"
+
+    def read(self, key: tuple, ttl: int) -> dict | None:
+        path = self.path(key)
+        if not path.exists():
+            print("cache miss", file=sys.stderr)
+            return None
+        payload = None
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            payload = None
+        if not (
+            isinstance(payload, dict)
+            and payload.get("version") == VERSION
+            and isinstance(payload.get("expiresAt"), int)
+            and isinstance(payload.get("value"), dict)
+        ):
+            path.unlink(missing_ok=True)
+            print("cache miss", file=sys.stderr)
+            return None
+        if time.time() >= payload["expiresAt"]:
+            path.unlink(missing_ok=True)
+            print("cache miss", file=sys.stderr)
+            return None
+        print("cache hit", file=sys.stderr)
+        return payload["value"]
+
+    def write(self, key: tuple, value: dict, ttl: int) -> None:
+        """Atomically write an owner-only cache entry."""
+        self.root.mkdir(parents=True, exist_ok=True, mode=0o700)
+        if self.root.exists():
+            os.chmod(self.root, 0o700)
+        destination = self.path(key)
+        descriptor, temporary_name = tempfile.mkstemp(prefix=f"{destination.name}.", suffix=".tmp", dir=self.root)
+        try:
+            with os.fdopen(descriptor, "w", encoding="utf-8") as output:
+                os.chmod(temporary_name, 0o600)
+                json.dump(
+                    {"version": VERSION, "expiresAt": int(time.time() + ttl), "value": value},
+                    output,
+                    separators=(",", ":"),
+                )
+                output.flush()
+                os.fsync(output.fileno())
+            os.replace(temporary_name, destination)
+        except BaseException:
+            Path(temporary_name).unlink(missing_ok=True)
+            raise
+
+    def purge(self) -> None:
+        if not self.root.exists():
+            return
+        for entry in self.root.iterdir():
+            if entry.is_file():
+                entry.unlink()
+
+
+def cache_read(key: tuple, ttl: int, root: Path, enabled: bool = True) -> dict | None:
+    return CacheStore(root).read(key, ttl) if enabled else None
+
+
+def cache_write(key: tuple, value: dict, ttl: int, root: Path, enabled: bool = True) -> None:
+    if enabled:
+        CacheStore(root).write(key, value, ttl)

hiringcafe_cli/count.py

@@ -0,0 +1,37 @@
+"""Anonymous result-count command."""
+
+import json
+
+from hiringcafe_cli.search import search
+
+
+def count(
+    query: str, raw_search_state: str | None = None, no_cache: bool = False, cache_ttl: int | None = None
+) -> dict:
+    """Count results by requesting page zero.
+
+    Args:
+        query: Query-text mode.
+        raw_search_state: Raw JSON object mode.
+
+    Returns:
+        Stable count envelope.
+    """
+    envelope = search(query, 0, raw_search_state, no_cache=no_cache, cache_ttl=cache_ttl)
+    total_count = envelope["result"]["totalCount"]
+    return {"version": 1, "query": envelope["query"], "count": total_count}
+
+
+def run(argv: object, json_output: bool) -> int:
+    """Execute count with CLI arguments."""
+    envelope = count(
+        argv.query,
+        argv.raw_search_state,
+        no_cache=getattr(argv, "no_cache", False),
+        cache_ttl=getattr(argv, "cache_ttl", None),
+    )
+    if json_output:
+        print(json.dumps(envelope, separators=(",", ":")))
+    else:
+        print(envelope["count"])
+    return 0

hiringcafe_cli/firebase.py

@@ -0,0 +1,93 @@
+"""Firebase Identity Toolkit REST adapter."""
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from urllib.request import urlopen
+
+from hiringcafe_cli.io_limits import read_limited
+
+FIREBASE_WEB_API_KEY = "AIzaSyBggiJ0ZSnwXoh1JILiairK8I3_BzI1V1E"
+PROJECT_ID = "hiringcafe-ec4d6"
+
+
+class FirebaseAuthError(RuntimeError):
+    """Firebase rejected the credential."""
+
+
+class FirebaseTransportError(RuntimeError):
+    """Firebase could not be reached."""
+
+
+class FirebaseClient:
+    """Client for the public Firebase Identity Toolkit endpoints."""
+
+    post = staticmethod(urlopen)
+
+    def refresh(self, refresh_token: str) -> dict:
+        """Exchange a refresh token for fresh credentials.
+
+        Args:
+            refresh_token: Stored Firebase refresh token.
+
+        Returns:
+            Firebase token response containing an ephemeral ID token.
+        """
+        query = urllib.parse.urlencode({"key": FIREBASE_WEB_API_KEY})
+        body = urllib.parse.urlencode({"grant_type": "refresh_token", "refresh_token": refresh_token}).encode()
+        payload = self._post(
+            f"https://securetoken.googleapis.com/v1/token?{query}",
+            body,
+        )
+        if "id_token" not in payload or "refresh_token" not in payload:
+            raise ValueError("Firebase token response is missing required fields")
+        return {
+            "idToken": payload["id_token"],
+            "refreshToken": payload["refresh_token"],
+            "userId": payload.get("user_id"),
+        }
+
+    def login_with_password(self, email: str, password: str) -> dict:
+        """Exchange Firebase email/password credentials once.
+
+        Args:
+            email: User's Firebase account email.
+            password: Password used in memory for exactly this request.
+
+        Returns:
+            Firebase sign-in response containing the durable refresh token.
+        """
+        query = urllib.parse.urlencode({"key": FIREBASE_WEB_API_KEY})
+        body = json.dumps({"email": email, "password": password, "returnSecureToken": True}).encode()
+        payload = self._post(
+            f"https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?{query}",
+            body,
+            {"Content-Type": "application/json"},
+        )
+        if "refreshToken" not in payload:
+            raise ValueError("Firebase sign-in response has no refresh token")
+        return payload
+
+    def _post(self, url: str, body: bytes, extra_headers: dict | None = None, timeout: float = 30) -> dict:
+        """POST JSON or form data and parse a JSON object response."""
+        headers = {"Accept": "application/json"}
+        if extra_headers:
+            headers.update(extra_headers)
+        request = urllib.request.Request(url, data=body, headers=headers, method="POST")
+        try:
+            with self.post(request, timeout=timeout) as response:
+                text = read_limited(response, "Firebase").decode("utf-8")
+        except urllib.error.HTTPError as error:
+            if error.code == 400:
+                raise FirebaseAuthError("Firebase rejected the credential") from error
+            raise FirebaseTransportError(f"Firebase returned HTTP {error.code}") from error
+        except (urllib.error.URLError, TimeoutError, OSError) as error:
+            raise FirebaseTransportError("Firebase transport failed") from error
+        try:
+            value = json.loads(text)
+        except json.JSONDecodeError as error:
+            raise ValueError("invalid Firebase JSON response") from error
+        if not isinstance(value, dict):
+            raise ValueError("Firebase response is not an object")
+        return value