skilark 0.1.0__tar.gz

skilark-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+*.egg-info/
+dist/
+.env
+.pytest_cache/
+.ruff_cache/
+
+# Go binary
+api/job-pulse-api
+
+# Large data files
+data.dump
+schema.sql
+
+# Generated site
+site/dist/
+
+# Terraform
+terraform/.terraform/
+terraform/*.tfstate
+terraform/*.tfstate.backup
+terraform/*.tfvars
+terraform/.terraform.lock.hcl
+*.old

skilark-0.1.0/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: skilark
+Version: 0.1.0
+Summary: Daily coding challenges from market intelligence
+Project-URL: Homepage, https://skilark.com
+Author-email: Skilark <skilark.feedback@gmail.com>
+License-Expression: MIT
+Keywords: challenges,cli,coding,learning,practice
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: inquirerpy>=0.3
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0

skilark-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "skilark"
+version = "0.1.0"
+description = "Daily coding challenges from market intelligence"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "Skilark", email = "skilark.feedback@gmail.com" },
+]
+keywords = ["coding", "challenges", "practice", "cli", "learning"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Education",
+]
+dependencies = [
+    "httpx>=0.27",
+    "rich>=13.0",
+    "InquirerPy>=0.3",
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+Homepage = "https://skilark.com"
+
+[project.scripts]
+skilark = "skilark_cli.main:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/skilark_cli"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+]

skilark-0.1.0/src/skilark_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

skilark-0.1.0/src/skilark_cli/answer_checker.py

@@ -0,0 +1,30 @@
+import re
+
+
+def normalize(s: str) -> str:
+    """Normalize answer string for comparison.
+
+    Strips whitespace, lowercases, removes bracket/paren wrappers,
+    normalizes commas to spaces, and collapses internal whitespace.
+    This lets users write answers in natural forms like "(1, 2)" or
+    "[1, 2, 3]" and still match the canonical expected value "1 2 3".
+    """
+    s = s.strip().lower()
+    # Remove common wrappers: parentheses, brackets, braces
+    s = re.sub(r'[\[\]\(\)\{\}]', '', s)
+    # Normalize commas to spaces
+    s = s.replace(',', ' ')
+    # Collapse multiple spaces
+    s = re.sub(r'\s+', ' ', s)
+    return s.strip()
+
+
+def check_answer(user_answer: str, expected: str) -> bool:
+    """Check if user's answer matches expected, with normalization.
+
+    Returns False for blank input so callers can distinguish
+    "no answer given" from a wrong answer without special-casing.
+    """
+    if not user_answer.strip():
+        return False
+    return normalize(user_answer) == normalize(expected)

skilark-0.1.0/src/skilark_cli/client.py

@@ -0,0 +1,107 @@
+"""
+SkilarkClient: thin httpx wrapper for the Skilark API.
+
+Every method maps 1-to-1 to a REST endpoint.  The client is synchronous
+because the CLI is a short-lived interactive process — async overhead is
+not warranted here.
+
+The `transport` constructor argument exists solely for testing: pass an
+httpx.MockTransport to intercept calls without hitting the network.
+"""
+
+import httpx
+
+
+class SkilarkClient:
+    """HTTP client for the Skilark API.
+
+    Args:
+        base_url:  Root URL of the API (e.g. "https://api.skilark.com").
+        user_id:   UUID for the authenticated user.  When set, every request
+                   carries an ``X-Skilark-User`` header so the server can
+                   associate actions with the right account.
+        transport: Optional httpx transport override, used in tests.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        user_id: str | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ):
+        kwargs: dict = {"base_url": base_url, "timeout": 15.0}
+        if transport is not None:
+            kwargs["transport"] = transport
+        self._http = httpx.Client(**kwargs)
+        self._user_id = user_id
+
+    def _headers(self) -> dict:
+        """Return request headers that identify the current user, if known."""
+        h: dict = {}
+        if self._user_id:
+            h["X-Skilark-User"] = self._user_id
+        return h
+
+    def create_user(self, topics: list[str]) -> dict:
+        """Register a new CLI user and return the created user object.
+
+        Called once during ``skilark setup``.  The returned dict contains
+        at minimum ``id`` (UUID) and ``topics``.
+        """
+        resp = self._http.post("/cli/users", json={"topics": topics})
+        resp.raise_for_status()
+        return resp.json()
+
+    def get_next_challenge(self, topics: list[str]) -> dict | None:
+        """Fetch the next unseen challenge for the given topics.
+
+        Returns None when the server responds with 404, meaning there are no
+        more challenges available right now (the user has exhausted today's
+        pool or there are simply no challenges for the requested topics).
+        """
+        resp = self._http.get(
+            "/cli/challenges/next",
+            params={"topics": ",".join(topics)},
+            headers=self._headers(),
+        )
+        if resp.status_code == 404:
+            return None
+        resp.raise_for_status()
+        return resp.json()
+
+    def complete_challenge(
+        self,
+        challenge_id: str,
+        answer: str,
+        correct: bool,
+        self_corrected: bool,
+    ) -> None:
+        """Record the user's attempt for a challenge.
+
+        Args:
+            challenge_id:   The challenge UUID returned by get_next_challenge.
+            answer:         The raw text the user typed.
+            correct:        Whether the system judged the answer correct.
+            self_corrected: Whether the user self-assessed after seeing the
+                            expected answer (used for partial-credit scoring).
+        """
+        resp = self._http.post(
+            f"/cli/challenges/{challenge_id}/complete",
+            json={
+                "answer": answer,
+                "correct": correct,
+                "self_corrected": self_corrected,
+            },
+            headers=self._headers(),
+        )
+        resp.raise_for_status()
+
+    def get_stats(self) -> dict:
+        """Return practice statistics for the current user.
+
+        The returned dict contains at minimum ``streak`` and
+        ``total_completed``.
+        """
+        resp = self._http.get("/cli/users/me/stats", headers=self._headers())
+        resp.raise_for_status()
+        return resp.json()

skilark-0.1.0/src/skilark_cli/commands/config.py

@@ -0,0 +1,54 @@
+"""
+`skilark config` command.
+
+Allows the user to interactively update their topic preferences.
+Presents a pre-populated checkbox prompt showing current selections,
+then persists any changes to the config file on disk.
+Exits early with a friendly message if the user has not yet run setup.
+"""
+
+from InquirerPy import inquirer
+from rich.console import Console
+
+from skilark_cli.config_store import ConfigStore
+from skilark_cli.onboarding import TOPIC_CHOICES
+
+console = Console()
+
+
+def run() -> None:
+    """Interactively update the user's topic preferences."""
+    config_store = ConfigStore()
+
+    if config_store.is_first_run():
+        console.print("[dim]Run 'skilark today' first to get started.[/dim]")
+        return
+
+    config = config_store.load()
+    current_topics = set(config.get("topics", []))
+
+    console.print(f"\n[bold]Current topics:[/bold] {', '.join(sorted(current_topics))}\n")
+
+    choices = [
+        {"name": t["name"], "value": t["value"], "enabled": t["value"] in current_topics}
+        for t in TOPIC_CHOICES
+    ]
+
+    selected = inquirer.checkbox(
+        message="Update topics (space to toggle, enter to confirm):",
+        choices=choices,
+        validate=lambda result: len(result) >= 1,
+        invalid_message="Pick at least one topic.",
+    ).execute()
+
+    config_store.update_topics(selected)
+
+    added = set(selected) - current_topics
+    removed = current_topics - set(selected)
+    if added:
+        console.print(f"[green]+ Added:[/green] {', '.join(sorted(added))}")
+    if removed:
+        console.print(f"[red]- Removed:[/red] {', '.join(sorted(removed))}")
+    if not added and not removed:
+        console.print("[dim]No changes.[/dim]")
+    console.print()

skilark-0.1.0/src/skilark_cli/commands/status.py

@@ -0,0 +1,29 @@
+"""
+`skilark status` command.
+
+Fetches and displays the user's learning statistics (streak, weekly
+progress, per-topic breakdown, last session) from the Skilark API.
+Exits early with a friendly message if the user has not yet run setup.
+"""
+
+from rich.console import Console
+
+from skilark_cli.client import SkilarkClient
+from skilark_cli.config_store import ConfigStore
+from skilark_cli.display import render_stats
+
+console = Console()
+
+
+def run() -> None:
+    """Display the current user's learning statistics."""
+    config_store = ConfigStore()
+
+    if config_store.is_first_run():
+        console.print("[dim]Run 'skilark today' first to get started.[/dim]")
+        return
+
+    config = config_store.load()
+    client = SkilarkClient(base_url=config["api_url"], user_id=config["user_id"])
+    stats = client.get_stats()
+    render_stats(console, stats)

skilark-0.1.0/src/skilark_cli/commands/today.py

@@ -0,0 +1,138 @@
+"""
+today command — the core challenge loop.
+
+Entry point: `skilark` or `skilark today`
+
+Fetches the next unseen challenge, prompts for an answer, checks it,
+records the result, and offers another round.  The interactive loop is
+extracted into `run_challenge_loop()` so tests can call it directly
+without touching ConfigStore or performing network I/O.
+"""
+
+import json
+
+from rich.console import Console
+from rich.prompt import Confirm, Prompt
+
+from skilark_cli.answer_checker import check_answer
+from skilark_cli.client import SkilarkClient
+from skilark_cli.config_store import ConfigStore
+from skilark_cli.display import render_challenge, render_hint, render_result
+from skilark_cli.onboarding import run_onboarding
+
+console = Console()
+
+
+def run() -> None:
+    """Entry point called from main.py for `skilark today`."""
+    config_store = ConfigStore()
+
+    if config_store.is_first_run():
+        run_onboarding(config_store, api_url="https://api.skilark.com")
+
+    config = config_store.load()
+    client = SkilarkClient(base_url=config["api_url"], user_id=config["user_id"])
+
+    # Use total_completed to drive the displayed day counter.  If the stats
+    # endpoint is unavailable (e.g. no network), fall back to day 1 silently
+    # so the user can still practice.
+    try:
+        stats = client.get_stats()
+        day = stats.get("total_completed", 0) + 1
+    except Exception:
+        day = 1
+
+    run_challenge_loop(client, topics=config["topics"], day=day)
+
+
+def run_challenge_loop(client: SkilarkClient, topics: list[str], day: int) -> None:
+    """Interactive challenge loop.
+
+    Fetches one challenge at a time, handles the answer/hint/skip/quit
+    interactions, records completions, and asks whether to continue.
+
+    Separated from `run()` so tests can inject a mock client and drive the
+    loop via patched Rich prompts without touching the filesystem or network.
+
+    Args:
+        client: SkilarkClient instance (or mock in tests).
+        topics: Topic filter passed to get_next_challenge.
+        day:    Starting day number displayed in the challenge header.
+    """
+    while True:
+        challenge = client.get_next_challenge(topics=topics)
+        if not challenge:
+            console.print(
+                "\n[dim]No more challenges available for your topics. "
+                "Try adding more![/dim]\n"
+            )
+            return
+
+        render_challenge(console, challenge, day=day)
+
+        # Hints may arrive as a JSON string or as an already-parsed list.
+        # Normalise to a list here so the rest of the loop is clean.
+        hints = challenge.get("hints") or []
+        if isinstance(hints, str):
+            try:
+                hints = json.loads(hints)
+            except (json.JSONDecodeError, TypeError):
+                hints = []
+
+        hint_idx = 0
+
+        while True:
+            answer = Prompt.ask("  Your answer")
+
+            if answer.lower() == "h":
+                if hint_idx < len(hints):
+                    render_hint(console, hints[hint_idx])
+                    hint_idx += 1
+                else:
+                    console.print("[dim]  No more hints.[/dim]\n")
+                continue
+
+            if answer.lower() == "s":
+                console.print("[dim]  Skipped.[/dim]\n")
+                break
+
+            if answer.lower() == "q":
+                return
+
+            correct = check_answer(answer, challenge["expected_answer"])
+            self_corrected = False
+
+            if not correct:
+                render_result(
+                    console,
+                    correct=False,
+                    expected_answer=challenge["expected_answer"],
+                    explanation=challenge["explanation"],
+                    deep_link=challenge["deep_link"],
+                )
+                self_corrected = Confirm.ask(
+                    "  Were you actually right?", default=False
+                )
+                if self_corrected:
+                    correct = True
+            else:
+                render_result(
+                    console,
+                    correct=True,
+                    explanation=challenge["explanation"],
+                    deep_link=challenge["deep_link"],
+                )
+
+            client.complete_challenge(
+                challenge["id"],
+                answer=answer,
+                correct=correct,
+                self_corrected=self_corrected,
+            )
+            break
+
+        day += 1
+
+        if not Confirm.ask("\n  Another?", default=True):
+            console.print("[dim]  See you tomorrow.[/dim]\n")
+            return

skilark-0.1.0/src/skilark_cli/config_store.py

@@ -0,0 +1,62 @@
+"""
+ConfigStore: reads and writes ~/.skilark/config.yaml.
+
+The config file is created on first setup and contains:
+  user_id  - UUID assigned by the API on registration
+  topics   - list of skill topics the user cares about
+  api_url  - base URL for the Skilark API (default: production)
+"""
+
+from pathlib import Path
+
+import yaml
+
+DEFAULT_API_URL = "https://api.skilark.com"
+
+
+class ConfigStore:
+    """Manages the on-disk configuration for the Skilark CLI.
+
+    Uses a configurable config_dir so that tests can point at a tmp_path
+    instead of touching the real ~/.skilark directory.
+    """
+
+    def __init__(self, config_dir: Path | None = None):
+        self.config_dir = config_dir or Path.home() / ".skilark"
+        self.config_file = self.config_dir / "config.yaml"
+
+    def is_first_run(self) -> bool:
+        """Return True if no config file exists yet (i.e. not yet set up)."""
+        return not self.config_file.exists()
+
+    def save(
+        self,
+        user_id: str,
+        topics: list[str],
+        api_url: str = DEFAULT_API_URL,
+    ) -> None:
+        """Write a fresh config file, creating the directory if needed.
+
+        Overwrites any existing config entirely — intended for initial setup
+        or a full reset.
+        """
+        self.config_dir.mkdir(parents=True, exist_ok=True)
+        data = {"user_id": user_id, "topics": topics, "api_url": api_url}
+        self.config_file.write_text(yaml.dump(data, default_flow_style=False))
+
+    def load(self) -> dict:
+        """Load and return the config as a plain dict.
+
+        Raises FileNotFoundError if is_first_run() is True (file not yet
+        created).  Callers should check is_first_run() before calling load().
+        """
+        return yaml.safe_load(self.config_file.read_text())
+
+    def update_topics(self, topics: list[str]) -> None:
+        """Replace the stored topic list without touching other fields.
+
+        Raises FileNotFoundError if config has not been created yet.
+        """
+        config = self.load()
+        config["topics"] = topics
+        self.config_file.write_text(yaml.dump(config, default_flow_style=False))