"""Lesson 0: Getting Started with ONA."""

from __future__ import annotations

from cde_onboard.lessons.base import BaseLesson
from cde_onboard.models import CodeBlock, LessonMeta, LessonStep, ScaffoldFile


class GettingStartedLesson(BaseLesson):
    """Introduction to ONA and the onboarding journey."""

    @classmethod
    def meta(cls) -> LessonMeta:
        return LessonMeta(
            id="getting-started",
            number=0,
            title="Getting Started",
            description="Introduction to ONA and how this onboarding works.",
            overview="Learn what ONA is, how cloud developer environments work, the workflow "
            "you'll follow, and what you'll build through these lessons.",
        )

    def steps(self) -> list[LessonStep]:
        return [
            LessonStep(
                title="Welcome to ONA",
                explanation=(
                    "**ONA (Open Nimbus Architecture)** provides cloud-based developer environments "
                    "that run in your browser. Instead of setting up tools and dependencies on your "
                    "local machine, you get a pre-configured environment that's:\n\n"
                    "- **Consistent** — Every team member gets the same environment\n"
                    "- **Fast to start** — No more 'download and install' on day one\n"
                    "- **Accessible anywhere** — Work from any device with a browser\n"
                    "- **Reproducible** — Defined as code in your repository"
                ),
                why=(
                    "Traditional local development has problems: 'works on my machine,' long "
                    "onboarding, version conflicts, and expensive local hardware. ONA eliminates "
                    "these by moving development to the cloud while keeping the familiar workflow."
                ),
            ),
            LessonStep(
                title="How ONA Works",
                explanation=(
                    "ONA environments are built from **configuration files** in your repository:\n\n"
                    "1. **Dev Container** (`.devcontainer/devcontainer.json`) — Defines the base "
                    "image, features, and lifecycle commands\n"
                    "2. **Automations** (`.ona/automations.yaml`) — Defines tasks and services that "
                    "run automatically\n"
                    "3. **Dotfiles** (separate GitLab repo) — Your personal shell and tool configs\n\n"
                    "When you create an ONA environment from a GitLab repository, ONA:\n"
                    "- Clones your repository\n"
                    "- Builds a dev container from your configuration\n"
                    "- Runs your tasks and services\n"
                    "- Applies your dotfiles\n"
                    "- Opens VS Code Browser for you to start coding"
                ),
            ),
            LessonStep(
                title="The Configuration Workflow",
                explanation=(
                    "This onboarding teaches you to configure ONA environments. Here's the "
                    "workflow you'll follow:\n\n"
                    "**1. Learn** — Each lesson explains a configuration concept\n\n"
                    "**2. Scaffold** — Click 'Scaffold & Complete' to generate sample files\n\n"
                    "**3. Copy** — Copy files from `./cde-onboard-practice/` to your repository\n\n"
                    "**4. Customize** — Edit the configs to match your project's needs\n\n"
                    "**5. Commit & Push** — Push changes to GitLab\n\n"
                    "**6. Test** — Create or rebuild your ONA environment to see the changes"
                ),
                code=CodeBlock(
                    language="bash",
                    source=(
                        "# Example: After completing Lesson 1\n"
                        "cp -R cde-onboard-practice/lesson-01-devcontainer-basics/.devcontainer ./\n"
                        "git add .devcontainer/\n"
                        "git commit -m \"Add devcontainer configuration\"\n"
                        "git push\n"
                        "\n"
                        "# Then in ONA dashboard: Create new environment from your repo"
                    ),
                ),
            ),
            LessonStep(
                title="Your Onboarding Journey",
                explanation=(
                    "You'll complete **6 hands-on lessons** that build on each other:\n\n"
                    "**Lesson 1: Dev Container Basics**\n"
                    "Learn to configure `.devcontainer/devcontainer.json` with base images, "
                    "features, and lifecycle commands.\n\n"
                    "**Lesson 2: Setting Up Your First Environment**\n"
                    "Create your first ONA environment from GitLab and connect via VS Code Browser.\n\n"
                    "**Lesson 3: Tasks**\n"
                    "Define one-off commands like installing dependencies and running migrations.\n\n"
                    "**Lesson 4: Services**\n"
                    "Configure long-running services like databases with health checks.\n\n"
                    "**Lesson 5: Dotfiles**\n"
                    "Personalize your environment with shell configs and tool preferences.\n\n"
                    "**Lesson 6: Managing Multiple Repos**\n"
                    "Work with multiple repositories in a single ONA environment."
                ),
            ),
            LessonStep(
                title="Prerequisites Checklist",
                explanation=(
                    "Before starting the lessons, make sure you have:\n\n"
                    "✓ **GitLab account** — You need access to `https://gitlab.example.com`\n\n"
                    "✓ **Practice repository** — Create a new repo or use an existing one\n\n"
                    "✓ **Local clone** — Clone your repository locally:\n"
                    "  ```bash\n"
                    "  git clone https://gitlab.example.com/your-user/your-repo.git\n"
                    "  cd your-repo\n"
                    "  ```\n\n"
                    "✓ **Run from repo root** — Launch `cde-onboard` from your repository root "
                    "for easiest file copying\n\n"
                    "If you don't have a practice repo yet, create one now on GitLab before "
                    "continuing."
                ),
            ),
            LessonStep(
                title="Key Concepts",
                explanation=(
                    "Understanding these concepts will help as you work through the lessons:\n\n"
                    "**Dev Container** — A Docker container configured for development, not "
                    "production. Contains your tools, runtimes, and IDE settings.\n\n"
                    "**Lifecycle Commands** — Commands that run at different stages:\n"
                    "- `onCreateCommand` — Runs once when container is first created\n"
                    "- `postCreateCommand` — Runs after creation and rebuilds\n"
                    "- `postStartCommand` — Runs every time the container starts\n\n"
                    "**Tasks vs Services** — Tasks run once and complete (e.g., migrations). "
                    "Services run continuously (e.g., databases).\n\n"
                    "**Prebuild** — ONA can pre-build your environment image when your repo changes, "
                    "making new environments start instantly.\n\n"
                    "**Workspace** — Your code lives in `/workspaces/<repo-name>/` inside the "
                    "environment."
                ),
            ),
            LessonStep(
                title="Tips for Success",
                explanation=(
                    "**Start Simple** — Don't try to configure everything at once. Complete each "
                    "lesson, test it, then move to the next.\n\n"
                    "**Test Frequently** — After each lesson, push your configs and rebuild your "
                    "ONA environment to verify they work.\n\n"
                    "**Customize Later** — The scaffolded files are templates. Get them working "
                    "first, then customize for your project.\n\n"
                    "**Read the 'Why'** — Each lesson includes 'Why' sections explaining the "
                    "reasoning behind choices. Understanding the 'why' helps you adapt configs "
                    "to your needs.\n\n"
                    "**Use Your Real Repo** — While you can practice in a throwaway repo, using "
                    "your actual project repo means you'll finish onboarding with a working setup.\n\n"
                    "Ready to start? Click **Next Lesson** or **Choose a Lesson** to begin!"
                ),
            ),
        ]

    def scaffold_files(self) -> list[ScaffoldFile]:
        # This lesson doesn't scaffold any files—it's purely educational
        return []
