vacancies-parser-kit 0.1.0__tar.gz

vacancies_parser_kit-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+*.egg
+.ruff_cache/
+.pytest_cache/

vacancies_parser_kit-0.1.0/CLAUDE.md

@@ -0,0 +1,88 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Multi-source vacancy/job-listing parser. Collects vacancies from heterogeneous sources (Telegram channels, HeadHunter API, LinkedIn, and other job platforms), normalises them into a unified schema, and writes them to pluggable storage backends.
+
+CLI tool: **`vpr`** (vacancy parser). Design follows dbt/detectkit patterns — YAML-based source definitions, profiles, tag-based selection.
+
+## Key Design Decisions
+
+- **Source-agnostic ingestion**: each source is a plugin that yields raw vacancy data. Sources may return unstructured or incomplete data — that's expected and must be handled gracefully (missing fields are nullable, never silently dropped).
+- **Source instances in YAML**: each source is defined as a `.yml` file in `sources/`. Same source type (e.g. `headhunter`) can have multiple instances with different params.
+- **Unified vacancy model**: all sources map to one canonical `Vacancy` record (`vpr/core/models.py`). Composite identity: `(source, source_id)`. Records support CRUD lifecycle states.
+- **Per-source dictionaries**: sources may ship lookup/mapping dictionaries (e.g. HeadHunter area codes → city names) used during normalisation.
+- **Pluggable storage**: writers are independent of sources. Targets defined in `profiles.yml`. Primary: ClickHouse, PostgreSQL.
+- **No built-in scheduler**: execution via bash/cron/Prefect. CLI supports `--select` and tags for orchestration.
+
+## Architecture
+
+```
+vpr/
+├── cli/              – Click CLI: vpr init / run / list
+│   └── commands/     – one module per command
+├── config/           – YAML config loaders (project, profile, source)
+├── core/
+│   ├── models.py     – canonical Vacancy schema
+│   ├── selector.py   – --select / --exclude resolution (name, glob, tag:)
+│   └── pipeline.py   – fetch → transform → write orchestration
+├── sources/
+│   ├── base.py       – BaseSource ABC (async fetch → Vacancy iterator)
+│   └── registry.py   – @register_source decorator + lookup
+├── transforms/
+│   └── normalize.py  – raw → canonical normalisation
+├── writers/
+│   ├── base.py       – BaseWriter ABC (async write)
+│   └── registry.py   – @register_writer decorator + lookup
+└── templates/        – scaffold for `vpr init`
+```
+
+## Development
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"       # editable install with dev deps
+pip install -e ".[all]"       # all source/writer extras
+```
+
+```bash
+pytest                        # run all tests
+pytest tests/test_selector.py # single test file
+pytest -k "test_tag"          # by test name pattern
+ruff check vpr/               # lint
+ruff format vpr/              # format
+```
+
+## CLI Usage
+
+```bash
+vpr init <project-name>                    # scaffold a new project
+vpr run --select <name|glob|tag:X>         # run pipeline
+vpr run --select tag:hh --exclude hh_test  # with exclusion
+vpr run --select "tg_*" --steps fetch      # only fetch step
+vpr list                                   # table of all sources
+vpr list --tags                            # grouped by tag
+```
+
+## Adding a New Source
+
+1. Create `vpr/sources/<type>.py`, subclass `BaseSource`, set `source_type = "<type>"`
+2. Decorate with `@register_source`
+3. Implement `async def fetch(self) -> AsyncIterator[Vacancy]`
+4. Import the module in `vpr/sources/__init__.py` so the decorator fires
+
+## Adding a New Writer
+
+1. Create `vpr/writers/<type>.py`, subclass `BaseWriter`, set `writer_type = "<type>"`
+2. Decorate with `@register_writer`
+3. Implement `async def write(self, vacancies: list[Vacancy]) -> int`
+4. Import the module in `vpr/writers/__init__.py`
+
+## Conventions
+
+- All user-facing text and code comments in Russian are acceptable; code identifiers in English.
+- Configuration via environment variables / `.env` files (never committed). Use `{{ env_var('NAME') }}` in profiles.yml.
+- Each source and writer must be independently testable with a fixture/mock for the external service.
+- Pipeline steps: `fetch`, `transform`, `write` — each can run independently via `--steps`.

vacancies_parser_kit-0.1.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: vacancies-parser-kit
+Version: 0.1.0
+Summary: Multi-source vacancy parser with pluggable storage backends
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: jinja2>=3.1
+Requires-Dist: rich>=13.0
+Provides-Extra: hh
+Requires-Dist: httpx>=0.27; extra == "hh"
+Provides-Extra: telegram
+Requires-Dist: telethon>=1.36; extra == "telegram"
+Provides-Extra: linkedin
+Requires-Dist: httpx>=0.27; extra == "linkedin"
+Provides-Extra: clickhouse
+Requires-Dist: clickhouse-connect>=0.7; extra == "clickhouse"
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == "postgres"
+Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
+Provides-Extra: all
+Requires-Dist: vpr[clickhouse,hh,linkedin,postgres,telegram]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"

vacancies_parser_kit-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68.0", "setuptools-scm>=8.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vacancies-parser-kit"
+version = "0.1.0"
+description = "Multi-source vacancy parser with pluggable storage backends"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+dependencies = [
+    "click>=8.1",
+    "pyyaml>=6.0",
+    "pydantic>=2.0",
+    "jinja2>=3.1",
+    "rich>=13.0",
+]
+
+[project.optional-dependencies]
+hh = ["httpx>=0.27"]
+telegram = ["telethon>=1.36"]
+linkedin = ["httpx>=0.27"]
+clickhouse = ["clickhouse-connect>=0.7"]
+postgres = ["asyncpg>=0.29", "psycopg[binary]>=3.1"]
+all = ["vpr[hh,telegram,linkedin,clickhouse,postgres]"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "ruff>=0.4"]
+
+[project.scripts]
+vpr = "vpr.cli.main:cli"
+
+[tool.setuptools.packages.find]
+include = ["vpr*"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

vacancies_parser_kit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vacancies_parser_kit-0.1.0/tests/test_headhunter.py

@@ -0,0 +1,121 @@
+"""Tests for HeadHunter source (mocked HTTP)."""
+
+import json
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from vpr.config.source_config import SourceConfig
+from vpr.sources.headhunter import HeadHunterSource
+
+
+def _make_config(**params) -> SourceConfig:
+    return SourceConfig(name="test_hh", type="headhunter", params=params)
+
+
+def _vacancy_json(vid: str, name: str = "Python Dev") -> dict:
+    return {
+        "id": vid,
+        "name": name,
+        "employer": {"name": "TestCorp"},
+        "area": {"id": "1", "name": "Москва"},
+        "salary": {"from": 100000, "to": 200000, "currency": "RUR", "gross": False},
+        "experience": {"id": "between1And3", "name": "1–3 года"},
+        "employment": {"id": "full", "name": "Полная занятость"},
+        "schedule": {"id": "remote", "name": "Удалённая работа"},
+        "published_at": "2026-04-05T10:00:00+0300",
+        "alternate_url": "https://hh.ru/vacancy/12345",
+    }
+
+
+def _full_vacancy_json(vid: str) -> dict:
+    base = _vacancy_json(vid)
+    base["description"] = "<p>We need a Python developer</p>"
+    base["key_skills"] = [{"name": "Python"}, {"name": "FastAPI"}]
+    return base
+
+
+def _search_response(items: list[dict], found: int | None = None) -> dict:
+    return {
+        "found": found or len(items),
+        "pages": 1,
+        "per_page": 100,
+        "page": 0,
+        "items": items,
+    }
+
+
+class FakeResponse:
+    def __init__(self, data: dict, status_code: int = 200):
+        self._data = data
+        self.status_code = status_code
+        self.text = json.dumps(data)
+        self.content = self.text.encode()
+
+    def json(self):
+        return self._data
+
+
+@pytest.mark.asyncio
+async def test_fetch_with_enrich():
+    """Two-pass: search + enrich each vacancy."""
+    config = _make_config(search_text="python", enrich=True, request_delay=0)
+    source = HeadHunterSource(config)
+
+    search_resp = FakeResponse(_search_response([_vacancy_json("1"), _vacancy_json("2")]))
+    full_1 = FakeResponse(_full_vacancy_json("1"))
+    full_2 = FakeResponse(_full_vacancy_json("2"))
+
+    mock_client = AsyncMock()
+    mock_client.get = AsyncMock(side_effect=[search_resp, full_1, full_2])
+    mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+    mock_client.__aexit__ = AsyncMock(return_value=False)
+
+    with patch.object(source, "_make_client", return_value=mock_client):
+        vacancies = [v async for v in source.fetch()]
+
+    assert len(vacancies) == 2
+    assert vacancies[0].source == "headhunter"
+    assert vacancies[0].source_id == "1"
+    assert vacancies[0].description == "<p>We need a Python developer</p>"
+    assert vacancies[0].skills == ["Python", "FastAPI"]
+    assert vacancies[0].salary.min == 100000
+    assert vacancies[0].salary.currency == "RUR"
+    assert vacancies[0].city == "Москва"
+
+
+@pytest.mark.asyncio
+async def test_fetch_without_enrich():
+    """Single pass: search only, no description/skills."""
+    config = _make_config(search_text="python", enrich=False, request_delay=0)
+    source = HeadHunterSource(config)
+
+    search_resp = FakeResponse(_search_response([_vacancy_json("1")]))
+
+    mock_client = AsyncMock()
+    mock_client.get = AsyncMock(return_value=search_resp)
+    mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+    mock_client.__aexit__ = AsyncMock(return_value=False)
+
+    with patch.object(source, "_make_client", return_value=mock_client):
+        vacancies = [v async for v in source.fetch()]
+
+    assert len(vacancies) == 1
+    assert vacancies[0].description is None
+    assert vacancies[0].skills == []
+
+
+@pytest.mark.asyncio
+async def test_vacancy_mapping():
+    """Check all canonical fields are correctly mapped."""
+    v = HeadHunterSource._to_vacancy(_full_vacancy_json("42"))
+    assert v.source == "headhunter"
+    assert v.source_id == "42"
+    assert v.title == "Python Dev"
+    assert v.company == "TestCorp"
+    assert v.experience == "1–3 года"
+    assert v.employment_type == "Полная занятость"
+    assert v.schedule == "Удалённая работа"
+    assert v.url == "https://hh.ru/vacancy/12345"
+    assert "Python" in v.skills
+    assert v.raw["id"] == "42"

vacancies_parser_kit-0.1.0/tests/test_selector.py

@@ -0,0 +1,52 @@
+"""Tests for source selector logic."""
+
+from vpr.config.source_config import SourceConfig
+from vpr.core.selector import select_sources
+
+
+def _make(name: str, tags: list[str] | None = None) -> SourceConfig:
+    return SourceConfig(name=name, type="test", tags=tags or [])
+
+
+SOURCES = [
+    _make("hh_backend", ["hh", "backend"]),
+    _make("hh_frontend", ["hh", "frontend"]),
+    _make("tg_python_jobs", ["telegram", "python"]),
+    _make("tg_devops_jobs", ["telegram", "devops"]),
+    _make("linkedin_eu", ["linkedin"]),
+]
+
+
+def test_select_by_exact_name():
+    result = select_sources(SOURCES, "hh_backend")
+    assert [s.name for s in result] == ["hh_backend"]
+
+
+def test_select_by_glob():
+    result = select_sources(SOURCES, "hh_*")
+    assert sorted(s.name for s in result) == ["hh_backend", "hh_frontend"]
+
+
+def test_select_by_tag():
+    result = select_sources(SOURCES, "tag:telegram")
+    assert sorted(s.name for s in result) == ["tg_devops_jobs", "tg_python_jobs"]
+
+
+def test_select_all_glob():
+    result = select_sources(SOURCES, "*")
+    assert len(result) == 5
+
+
+def test_exclude():
+    result = select_sources(SOURCES, "tag:hh", excludes={"hh_frontend"})
+    assert [s.name for s in result] == ["hh_backend"]
+
+
+def test_no_match():
+    result = select_sources(SOURCES, "nonexistent")
+    assert result == []
+
+
+def test_exclude_all():
+    result = select_sources(SOURCES, "tag:hh", excludes={"hh_backend", "hh_frontend"})
+    assert result == []

vacancies_parser_kit-0.1.0/vacancies_parser_kit.egg-info/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: vacancies-parser-kit
+Version: 0.1.0
+Summary: Multi-source vacancy parser with pluggable storage backends
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: jinja2>=3.1
+Requires-Dist: rich>=13.0
+Provides-Extra: hh
+Requires-Dist: httpx>=0.27; extra == "hh"
+Provides-Extra: telegram
+Requires-Dist: telethon>=1.36; extra == "telegram"
+Provides-Extra: linkedin
+Requires-Dist: httpx>=0.27; extra == "linkedin"
+Provides-Extra: clickhouse
+Requires-Dist: clickhouse-connect>=0.7; extra == "clickhouse"
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == "postgres"
+Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
+Provides-Extra: all
+Requires-Dist: vpr[clickhouse,hh,linkedin,postgres,telegram]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"

vacancies_parser_kit-0.1.0/vacancies_parser_kit.egg-info/SOURCES.txt

@@ -0,0 +1,43 @@
+.gitignore
+CLAUDE.md
+pyproject.toml
+tests/__init__.py
+tests/test_headhunter.py
+tests/test_selector.py
+vacancies_parser_kit.egg-info/PKG-INFO
+vacancies_parser_kit.egg-info/SOURCES.txt
+vacancies_parser_kit.egg-info/dependency_links.txt
+vacancies_parser_kit.egg-info/entry_points.txt
+vacancies_parser_kit.egg-info/requires.txt
+vacancies_parser_kit.egg-info/top_level.txt
+vpr/__init__.py
+vpr/cli/__init__.py
+vpr/cli/main.py
+vpr/cli/commands/__init__.py
+vpr/cli/commands/init.py
+vpr/cli/commands/list.py
+vpr/cli/commands/run.py
+vpr/config/__init__.py
+vpr/config/profile.py
+vpr/config/project.py
+vpr/config/source_config.py
+vpr/core/__init__.py
+vpr/core/models.py
+vpr/core/pipeline.py
+vpr/core/selector.py
+vpr/sources/__init__.py
+vpr/sources/base.py
+vpr/sources/headhunter.py
+vpr/sources/hh_dictionaries.py
+vpr/sources/registry.py
+vpr/templates/__init__.py
+vpr/templates/scaffold.py
+vpr/transforms/__init__.py
+vpr/transforms/normalize.py
+vpr/writers/__init__.py
+vpr/writers/base.py
+vpr/writers/clickhouse.py
+vpr/writers/jsonl.py
+vpr/writers/postgres.py
+vpr/writers/registry.py
+vpr/writers/sqlite.py

vacancies_parser_kit-0.1.0/vacancies_parser_kit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vacancies_parser_kit-0.1.0/vacancies_parser_kit.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vpr = vpr.cli.main:cli

vacancies_parser_kit-0.1.0/vacancies_parser_kit.egg-info/requires.txt

@@ -0,0 +1,29 @@
+click>=8.1
+pyyaml>=6.0
+pydantic>=2.0
+jinja2>=3.1
+rich>=13.0
+
+[all]
+vpr[clickhouse,hh,linkedin,postgres,telegram]
+
+[clickhouse]
+clickhouse-connect>=0.7
+
+[dev]
+pytest>=8.0
+pytest-asyncio>=0.23
+ruff>=0.4
+
+[hh]
+httpx>=0.27
+
+[linkedin]
+httpx>=0.27
+
+[postgres]
+asyncpg>=0.29
+psycopg[binary]>=3.1
+
+[telegram]
+telethon>=1.36

vacancies_parser_kit-0.1.0/vacancies_parser_kit.egg-info/top_level.txt

@@ -0,0 +1 @@
+vpr

vacancies_parser_kit-0.1.0/vpr/__init__.py

@@ -0,0 +1,3 @@
+"""vpr — multi-source vacancy parser."""
+
+__version__ = "0.1.0"

vacancies_parser_kit-0.1.0/vpr/cli/commands/init.py

@@ -0,0 +1,29 @@
+"""vpr init — scaffold a new project."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from vpr.templates import render_project_scaffold
+
+console = Console()
+
+
+@click.command("init")
+@click.argument("project_name")
+def init_cmd(project_name: str) -> None:
+    """Create a new vpr project."""
+    target = Path.cwd() / project_name
+    if target.exists():
+        raise click.ClickException(f"Directory '{project_name}' already exists")
+
+    render_project_scaffold(target, project_name)
+    console.print(f"[green]Project '{project_name}' created at {target}[/green]")
+    console.print("Next steps:")
+    console.print(f"  cd {project_name}")
+    console.print("  # edit profiles.yml with your database credentials")
+    console.print("  # add source definitions to sources/")
+    console.print("  vpr run --select <source_name>")

vacancies_parser_kit-0.1.0/vpr/cli/commands/list.py

@@ -0,0 +1,59 @@
+"""vpr list — show all configured sources."""
+
+from __future__ import annotations
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from vpr.config.project import find_project_root, load_project_config
+from vpr.config.source_config import load_source_configs
+
+console = Console()
+
+
+@click.command("list")
+@click.option("--tags", is_flag=True, help="Group sources by tag")
+def list_cmd(tags: bool) -> None:
+    """List all configured sources."""
+    project_root = find_project_root()
+    project_cfg = load_project_config(project_root)
+    sources = load_source_configs(project_root / project_cfg.paths.sources)
+
+    if not sources:
+        console.print("[yellow]No sources found.[/yellow]")
+        return
+
+    if tags:
+        _print_by_tags(sources)
+    else:
+        _print_table(sources)
+
+
+def _print_table(sources) -> None:
+    table = Table(title="Sources")
+    table.add_column("Name", style="cyan")
+    table.add_column("Type", style="green")
+    table.add_column("Tags")
+    table.add_column("Targets")
+
+    for src in sorted(sources, key=lambda s: s.name):
+        table.add_row(
+            src.name,
+            src.type,
+            ", ".join(src.tags),
+            ", ".join(src.targets) if src.targets else "—",
+        )
+    console.print(table)
+
+
+def _print_by_tags(sources) -> None:
+    tag_map: dict[str, list[str]] = {}
+    for src in sources:
+        for tag in src.tags:
+            tag_map.setdefault(tag, []).append(src.name)
+
+    for tag in sorted(tag_map):
+        console.print(f"[bold]tag:{tag}[/bold]")
+        for name in sorted(tag_map[tag]):
+            console.print(f"  - {name}")

vacancies_parser_kit-0.1.0/vpr/cli/commands/run.py

@@ -0,0 +1,92 @@
+"""vpr run — fetch, transform, and write vacancies."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+import click
+from rich.console import Console
+
+from vpr.config.project import find_project_root, load_project_config
+from vpr.config.profile import load_profiles
+from vpr.config.source_config import load_source_configs
+from vpr.core.selector import select_sources
+
+if TYPE_CHECKING:
+    pass
+
+console = Console()
+
+VALID_STEPS = ("fetch", "transform", "write")
+
+
+@click.command("run")
+@click.option("--select", "selector", required=True, help="Source selector: name, glob pattern, or tag:<tag>")
+@click.option("--exclude", "excludes", multiple=True, help="Exclude sources by name")
+@click.option("--steps", default=None, help=f"Comma-separated pipeline steps: {', '.join(VALID_STEPS)}")
+@click.option("--profile", default=None, help="Override default profile from vpr_project.yml")
+@click.option("--full-refresh", is_flag=True, help="Drop existing data and re-fetch from scratch")
+def run_cmd(
+    selector: str,
+    excludes: tuple[str, ...],
+    steps: str | None,
+    profile: str | None,
+    full_refresh: bool,
+) -> None:
+    """Run the vacancy pipeline for selected sources."""
+    active_steps = _parse_steps(steps)
+
+    project_root = find_project_root()
+    project_cfg = load_project_config(project_root)
+    profiles_cfg = load_profiles(project_root)
+    all_sources = load_source_configs(project_root / project_cfg.paths.sources)
+
+    if not all_sources:
+        raise click.ClickException(f"No source configs found in {project_cfg.paths.sources}/")
+
+    matched = select_sources(all_sources, selector, excludes=set(excludes))
+    if not matched:
+        raise click.ClickException(f"No sources matched selector '{selector}'")
+
+    profile_name = profile or project_cfg.default_profile
+    if profile_name not in profiles_cfg.profiles:
+        raise click.ClickException(f"Profile '{profile_name}' not found in profiles.yml")
+
+    console.print(f"[bold]Profile:[/bold] {profile_name}")
+    console.print(f"[bold]Steps:[/bold]  {', '.join(active_steps)}")
+    console.print(f"[bold]Sources ({len(matched)}):[/bold]")
+    for src in matched:
+        console.print(f"  - {src.name} [dim]({src.type})[/dim]")
+    console.print()
+
+    asyncio.run(_run_pipeline(matched, profiles_cfg, profile_name, active_steps, full_refresh))
+
+
+async def _run_pipeline(sources, profiles_cfg, profile_name, steps, full_refresh):
+    """Execute the pipeline for each matched source."""
+    from vpr.core.pipeline import run_source_pipeline
+
+    profile = profiles_cfg.profiles[profile_name]
+    for src_cfg in sources:
+        console.print(f"[bold cyan]>>> {src_cfg.name}[/bold cyan]")
+        try:
+            await run_source_pipeline(
+                source_config=src_cfg,
+                profile=profile,
+                steps=steps,
+                full_refresh=full_refresh,
+            )
+            console.print(f"[green]  ✓ {src_cfg.name} done[/green]")
+        except Exception as exc:
+            console.print(f"[red]  ✗ {src_cfg.name} failed: {exc}[/red]")
+
+
+def _parse_steps(raw: str | None) -> list[str]:
+    if raw is None:
+        return list(VALID_STEPS)
+    parts = [s.strip() for s in raw.split(",")]
+    for s in parts:
+        if s not in VALID_STEPS:
+            raise click.ClickException(f"Unknown step '{s}'. Valid: {', '.join(VALID_STEPS)}")
+    return parts