aicademy 0.1.0__tar.gz

aicademy-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  # Optionally allow manual triggers
+  workflow_dispatch:
+
+jobs:
+  pypi-publish:
+    name: Build and publish Python package
+    runs-on: ubuntu-latest
+    
+    # Specifying a GitHub environment is strongly encouraged for Trusted Publishing
+    environment: pypi
+    
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tool
+        run: python -m pip install --upgrade build
+
+      - name: Build a binary wheel and a source tarball
+        run: python -m build
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

aicademy-0.1.0/.gitignore

@@ -0,0 +1,81 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Secrets & Local Config
+.env
+.env.local
+.env.*
+*.pem
+*.key
+*.db
+*.sqlite
+*.sqlite3
+
+# IDEs / Editors / OS
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Typer / Hatch / uv cache
+.hatch/
+.uv/

aicademy-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: aicademy
+Version: 0.1.0
+Summary: Aicademy Practice CLI — solve Kubernetes exam scenarios locally with KIND
+Project-URL: Homepage, https://aicademy.ac/practice
+Project-URL: Repository, https://github.com/devcrypted/aicademy-cli
+Project-URL: Issues, https://github.com/devcrypted/aicademy-cli/issues
+Author-email: Aicademy <hello@aicademy.ac>
+License: MIT
+Keywords: cka,ckad,cks,cli,devops,kubernetes,practice
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Education
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer[all]>=0.12.0
+Description-Content-Type: text/markdown
+
+# Aicademy CLI
+
+> Practice CKA, CKAD, and CKS exam scenarios locally — powered by KIND + Aicademy API.
+
+[![PyPI](https://img.shields.io/pypi/v/aicademy)](https://pypi.org/project/aicademy/)
+[![Python](https://img.shields.io/pypi/pyversions/aicademy)](https://pypi.org/project/aicademy/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Installation
+
+### Using pip
+
+```bash
+pip install aicademy
+```
+
+### Using uv (recommended)
+
+```bash
+uv tool install aicademy
+```
+
+### Using pipx
+
+```bash
+pipx install aicademy
+```
+
+## Quick Start
+
+```bash
+# 1. Login to Aicademy
+aicademy login
+
+# 2. Check / install prerequisites
+aicademy install-tool all --check
+aicademy install-tool all
+
+# 3. Start a practice question (creates KIND cluster automatically)
+aicademy question start cka-01
+
+# 4. Read the full task instructions in your terminal
+aicademy question instructions
+
+# 5. Solve the scenario using kubectl, helm, etc.
+
+# 6. Verify your solution
+aicademy verify
+
+# 7. Clean up the cluster
+aicademy question clear
+```
+
+## Command Reference
+
+| Command                                     | Description                                       |
+| ------------------------------------------- | ------------------------------------------------- |
+| `aicademy login`                            | Authenticate (browser flow or direct token)       |
+| `aicademy logout`                           | Clear stored credentials                          |
+| `aicademy auth whoami`                      | Verify token validity                             |
+| `aicademy question start <id>`              | Start question environment (creates KIND cluster) |
+| `aicademy question instructions [id]`       | Show full task instructions in terminal           |
+| `aicademy question instructions [id] --web` | Open question page in browser                     |
+| `aicademy question clear [id]`              | Delete KIND cluster and clear session             |
+| `aicademy verify [id]`                      | Run verify.sh and report result                   |
+| `aicademy install-tool <name>`              | Install kubectl / kind / docker / all             |
+| `aicademy install-tool <name> --check`      | Check if tool is installed (no install)           |
+| `aicademy install-tool <name> --dry-run`    | Preview install commands                          |
+
+## Prerequisites
+
+| Tool    | Purpose           | Install                         |
+| ------- | ----------------- | ------------------------------- |
+| Docker  | Runs KIND nodes   | `aicademy install-tool docker`  |
+| kubectl | Kubernetes CLI    | `aicademy install-tool kubectl` |
+| kind    | Local K8s cluster | `aicademy install-tool kind`    |
+
+## OS Support
+
+| OS      | Package Manager        |
+| ---------| ------------------------|
+| Windows | winget                 |
+| macOS   | Homebrew               |
+| Linux   | Official shell scripts |
+
+## Categories
+
+| Exam                                       | Slug   | Questions | Free |
+| --------------------------------------------| --------| -----------| ------|
+| Certified Kubernetes Administrator         | `cka`  | 20        | 10   |
+| Certified Kubernetes Application Developer | `ckad` | 20        | 10   |
+| Certified Kubernetes Security Specialist   | `cks`  | 20        | 10   |
+
+## Development
+
+### Project Structure
+
+The codebase is organized modularly:
+
+- `aicademy_cli/main.py`: The entry point and top-level Typer application.
+- `aicademy_cli/commands/`: All user-facing Typer CLI groups (`auth`, `question`, `tools`, `verify`).
+- `aicademy_cli/api.py`: Centralized HTTP requests and error handling.
+- `aicademy_cli/core/`: Internal logic like cluster management (`kind.py`) and helper methods (`utils.py`).
+
+### Using uv
+
+```bash
+# Clone and install in dev mode
+git clone https://github.com/devcrypted/aicademy-cli
+cd aicademy-cli
+uv sync
+
+# Run against local dev server
+AICADEMY_API_URL=http://localhost:5173 uv run aicademy login
+
+# Run tests
+uv run pytest
+
+# Lint
+uv run ruff check .
+uv run mypy aicademy_cli/
+```
+
+### Building the wheel
+
+```bash
+# Build wheel + sdist
+uv build
+
+# Output will be in dist/
+ls dist/
+# aicademy-0.1.0-py3-none-any.whl
+# aicademy-0.1.0.tar.gz
+```
+
+### Publishing to PyPI
+
+```bash
+# Test on TestPyPI first
+uv publish --index testpypi
+
+# Publish to production PyPI
+uv publish
+```
+
+## Security
+
+- CLI tokens stored in `~/.aicademy/config.json`
+- Tokens expire after 7 days — run `aicademy login` to renew
+- Question tasks and scenarios only delivered when you have an active session (anti-scraping)
+- Revoke all tokens with `aicademy logout`
+
+## License
+
+MIT © [Aicademy](https://www.aicademy.ac)

aicademy-0.1.0/README.md

@@ -0,0 +1,155 @@
+# Aicademy CLI
+
+> Practice CKA, CKAD, and CKS exam scenarios locally — powered by KIND + Aicademy API.
+
+[![PyPI](https://img.shields.io/pypi/v/aicademy)](https://pypi.org/project/aicademy/)
+[![Python](https://img.shields.io/pypi/pyversions/aicademy)](https://pypi.org/project/aicademy/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Installation
+
+### Using pip
+
+```bash
+pip install aicademy
+```
+
+### Using uv (recommended)
+
+```bash
+uv tool install aicademy
+```
+
+### Using pipx
+
+```bash
+pipx install aicademy
+```
+
+## Quick Start
+
+```bash
+# 1. Login to Aicademy
+aicademy login
+
+# 2. Check / install prerequisites
+aicademy install-tool all --check
+aicademy install-tool all
+
+# 3. Start a practice question (creates KIND cluster automatically)
+aicademy question start cka-01
+
+# 4. Read the full task instructions in your terminal
+aicademy question instructions
+
+# 5. Solve the scenario using kubectl, helm, etc.
+
+# 6. Verify your solution
+aicademy verify
+
+# 7. Clean up the cluster
+aicademy question clear
+```
+
+## Command Reference
+
+| Command                                     | Description                                       |
+| ------------------------------------------- | ------------------------------------------------- |
+| `aicademy login`                            | Authenticate (browser flow or direct token)       |
+| `aicademy logout`                           | Clear stored credentials                          |
+| `aicademy auth whoami`                      | Verify token validity                             |
+| `aicademy question start <id>`              | Start question environment (creates KIND cluster) |
+| `aicademy question instructions [id]`       | Show full task instructions in terminal           |
+| `aicademy question instructions [id] --web` | Open question page in browser                     |
+| `aicademy question clear [id]`              | Delete KIND cluster and clear session             |
+| `aicademy verify [id]`                      | Run verify.sh and report result                   |
+| `aicademy install-tool <name>`              | Install kubectl / kind / docker / all             |
+| `aicademy install-tool <name> --check`      | Check if tool is installed (no install)           |
+| `aicademy install-tool <name> --dry-run`    | Preview install commands                          |
+
+## Prerequisites
+
+| Tool    | Purpose           | Install                         |
+| ------- | ----------------- | ------------------------------- |
+| Docker  | Runs KIND nodes   | `aicademy install-tool docker`  |
+| kubectl | Kubernetes CLI    | `aicademy install-tool kubectl` |
+| kind    | Local K8s cluster | `aicademy install-tool kind`    |
+
+## OS Support
+
+| OS      | Package Manager        |
+| ---------| ------------------------|
+| Windows | winget                 |
+| macOS   | Homebrew               |
+| Linux   | Official shell scripts |
+
+## Categories
+
+| Exam                                       | Slug   | Questions | Free |
+| --------------------------------------------| --------| -----------| ------|
+| Certified Kubernetes Administrator         | `cka`  | 20        | 10   |
+| Certified Kubernetes Application Developer | `ckad` | 20        | 10   |
+| Certified Kubernetes Security Specialist   | `cks`  | 20        | 10   |
+
+## Development
+
+### Project Structure
+
+The codebase is organized modularly:
+
+- `aicademy_cli/main.py`: The entry point and top-level Typer application.
+- `aicademy_cli/commands/`: All user-facing Typer CLI groups (`auth`, `question`, `tools`, `verify`).
+- `aicademy_cli/api.py`: Centralized HTTP requests and error handling.
+- `aicademy_cli/core/`: Internal logic like cluster management (`kind.py`) and helper methods (`utils.py`).
+
+### Using uv
+
+```bash
+# Clone and install in dev mode
+git clone https://github.com/devcrypted/aicademy-cli
+cd aicademy-cli
+uv sync
+
+# Run against local dev server
+AICADEMY_API_URL=http://localhost:5173 uv run aicademy login
+
+# Run tests
+uv run pytest
+
+# Lint
+uv run ruff check .
+uv run mypy aicademy_cli/
+```
+
+### Building the wheel
+
+```bash
+# Build wheel + sdist
+uv build
+
+# Output will be in dist/
+ls dist/
+# aicademy-0.1.0-py3-none-any.whl
+# aicademy-0.1.0.tar.gz
+```
+
+### Publishing to PyPI
+
+```bash
+# Test on TestPyPI first
+uv publish --index testpypi
+
+# Publish to production PyPI
+uv publish
+```
+
+## Security
+
+- CLI tokens stored in `~/.aicademy/config.json`
+- Tokens expire after 7 days — run `aicademy login` to renew
+- Question tasks and scenarios only delivered when you have an active session (anti-scraping)
+- Revoke all tokens with `aicademy logout`
+
+## License
+
+MIT © [Aicademy](https://www.aicademy.ac)

aicademy-0.1.0/aicademy_cli/__init__.py

@@ -0,0 +1 @@
+"""Aicademy CLI — Kubernetes exam practice in your terminal"""

aicademy-0.1.0/aicademy_cli/api.py

@@ -0,0 +1,106 @@
+"""API Client for Aicademy CLI"""
+
+import httpx
+from typing import Any
+from . import config
+
+class APIError(Exception):
+    def __init__(self, message: str, status_code: int, response_data: dict | str = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_data = response_data
+
+def _get_headers(token: str | None = None) -> dict[str, str]:
+    t = token or config.get_token()
+    if t:
+        return {"Authorization": f"Bearer {t}"}
+    return {}
+
+def _request(method: str, url: str, **kwargs) -> dict:
+    try:
+        resp = httpx.request(method, url, **kwargs)
+    except httpx.RequestError as exc:
+        raise APIError(f"Network error: {exc}", 0, str(exc))
+    
+    if resp.status_code >= 400:
+        data = resp.text
+        try:
+            data = resp.json()
+        except Exception:
+            pass
+        raise APIError(f"HTTP {resp.status_code}: {resp.reason_phrase}", resp.status_code, data)
+    
+    if resp.status_code == 204:
+        return None
+    try:
+        return resp.json()
+    except Exception:
+        return resp.text
+
+# ─── Auth ───────────────────────────────────────────────────────────────────────
+
+def verify_token(token: str) -> dict:
+    return _request(
+        "POST",
+        f"{config.API_BASE_URL}/api/auth/cli-token",
+        headers=_get_headers(token),
+        timeout=10,
+    )
+
+def logout(token: str) -> None:
+    try:
+        httpx.delete(
+            f"{config.API_BASE_URL}/api/auth/cli-token",
+            headers=_get_headers(token),
+            timeout=5,
+        )
+    except httpx.RequestError:
+        pass
+
+def get_sessions() -> dict:
+    return _request(
+        "GET",
+        f"{config.API_BASE_URL}/api/practice/sessions",
+        headers=_get_headers(),
+        timeout=10,
+    )
+
+# ─── Practice ───────────────────────────────────────────────────────────────────
+
+def start_session(question_id: str, cluster_name: str) -> dict:
+    return _request(
+        "POST",
+        f"{config.API_BASE_URL}/api/practice/sessions",
+        json={"questionId": question_id, "clusterName": cluster_name},
+        headers=_get_headers(),
+        timeout=15,
+    )
+
+def get_question(category: str, question_id: str) -> dict:
+    return _request(
+        "GET",
+        f"{config.API_BASE_URL}/api/practice/questions/{category}/{question_id}",
+        headers=_get_headers(),
+        timeout=10,
+    )
+
+def abandon_session(session_id: str) -> None:
+    try:
+        httpx.patch(
+            f"{config.API_BASE_URL}/api/practice/sessions/{session_id}",
+            headers=_get_headers(),
+            timeout=10,
+        )
+    except httpx.RequestError:
+        pass
+
+def verify_session(session_id: str, result: dict) -> None:
+    try:
+        httpx.post(
+            f"{config.API_BASE_URL}/api/practice/sessions/{session_id}/verify",
+            json=result,
+            headers=_get_headers(),
+            timeout=10,
+        )
+    except httpx.RequestError:
+        pass

aicademy-0.1.0/aicademy_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules for Aicademy."""

aicademy-0.1.0/aicademy_cli/commands/auth.py

@@ -0,0 +1,102 @@
+"""Authentication commands — login & logout"""
+
+import webbrowser
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Prompt
+from .. import config, api
+from ..core import utils
+
+console = Console()
+app = typer.Typer(help="Authenticate with Aicademy")
+
+@app.command()
+def login(
+    token: str = typer.Option(
+        None,
+        "--token",
+        "-t",
+        help="Paste a CLI token directly (skip browser flow)",
+    ),
+) -> None:
+    """Login to Aicademy and store your CLI token."""
+    cfg = config.get_config()
+    if cfg.get("token"):
+        console.print(
+            "[yellow]ℹ Already logged in.[/yellow] Use [bold]aicademy logout[/bold] first to switch accounts."
+        )
+        raise typer.Exit()
+
+    if not token:
+        console.print(
+            Panel(
+                "[bold]Aicademy Login[/bold]\n\n"
+                "Opening your browser to generate a CLI token.\n"
+                "After logging in, copy the token and paste it below.",
+                title="🔐  Authentication",
+                border_style="cyan",
+            )
+        )
+        token_url = f"{config.API_BASE_URL}/auth?cli=1"
+        console.print(f"\n  [dim]→ Opening:[/dim] [cyan]{token_url}[/cyan]\n")
+        webbrowser.open(token_url)
+        token = Prompt.ask("  [bold]Paste your CLI token here[/bold]").strip()
+
+    if not token:
+        console.print("[red]✗ No token provided. Login cancelled.[/red]")
+        raise typer.Exit(1)
+
+    # Verify the token against the API
+    console.print("\n[dim]Verifying token...[/dim]")
+    try:
+        api.verify_token(token)
+    except api.APIError as e:
+        if e.status_code == 401:
+            console.print("[red]✗ Token is invalid or expired. Please try again.[/red]")
+        else:
+            utils.format_access_error(e)
+        raise typer.Exit(1)
+
+    cfg["token"] = token
+    config.save_config(cfg)
+    console.print(
+        Panel(
+            "[bold green]✓ Logged in successfully![/bold green]\n\n"
+            f"Your token is stored in [dim]~/.aicademy/config.json[/dim]\n"
+            "It expires in [bold]7 days[/bold]. Run [bold]aicademy login[/bold] again to renew.",
+            title="✅  Success",
+            border_style="green",
+        )
+    )
+
+@app.command()
+def logout() -> None:
+    """Log out and clear stored credentials."""
+    cfg = config.get_config()
+    if not cfg.get("token"):
+        console.print("[yellow]ℹ You are not logged in.[/yellow]")
+        raise typer.Exit()
+
+    token = cfg.get("token")
+    api.logout(token)
+
+    cfg.pop("token", None)
+    cfg.pop("active_session", None)
+    config.save_config(cfg)
+    console.print("[bold green]✓ Logged out successfully.[/bold green]")
+
+@app.command()
+def whoami() -> None:
+    """Show the currently logged-in user."""
+    token = utils.require_auth()
+
+    try:
+        api.get_sessions()
+        console.print("[green]✓ Logged in[/green] — token is valid.")
+    except api.APIError as e:
+        if e.status_code == 401:
+            console.print("[red]Token expired.[/red] Please run [bold]aicademy login[/bold] again.")
+        else:
+            utils.format_access_error(e)
+        raise typer.Exit(1)