feat: platform-prefixed dispatcher architecture (soc + soc-gh-*)

PLAN_ROZWOJU.md

@@ -0,0 +1,106 @@
+# Plan rozwoju `soc-cli`
+
+## Cel
+Rozwinąć `soc-cli` jako stabilne, wieloplatformowe CLI do zarządzania kursami SoC, z naciskiem na jakość UX, bezpieczeństwo operacji administracyjnych i łatwość utrzymania.
+
+## Założenia strategiczne
+- Zachować architekturę komend prefiksowanych platformą (`soc-<platform>-<cmd>`).
+- Utrzymać kompatybilność z obecnym przepływem `gh soc ...`.
+- Priorytetyzować bezpieczeństwo operacji destrukcyjnych (`delete`, `unsync`, `close`).
+- Ułatwić adopcję narzędzia przez lepszą dokumentację i diagnostykę.
+
+## Etap 1 — Stabilizacja fundamentów (najwyższy priorytet)
+
+### 1.1 Walidacja i precheck
+- [ ] Rozszerzyć `precheck` o pełną walidację konfiguracji (`user_config.sh`, `source_config.sh`, `system_config.sh`).
+- [ ] Dodać czytelne komunikaty błędów z podpowiedzią naprawy.
+- [ ] Dodać tryb `--verbose` oraz kod wyjścia per klasa błędu.
+
+### 1.2 Bezpieczeństwo operacji
+- [ ] Wymusić dodatkowe potwierdzenia dla `delete`, `unsync`, `close`.
+- [ ] Dodać tryb `--dry-run` dla komend modyfikujących stan organizacji/repo.
+- [ ] Wprowadzić centralną obsługę rollbacku/częściowego niepowodzenia.
+
+### 1.3 Spójność CLI
+- [ ] Ujednolicić format helpa i przykładów dla wszystkich komend.
+- [ ] Ustandaryzować kody wyjścia i prefiksy logów (`INFO/WARN/ERROR`).
+- [ ] Dodać walidację argumentów wejściowych na poziomie wrapperów komend.
+
+## Etap 2 — Utrzymanie i jakość kodu
+
+### 2.1 Testy i walidacja techniczna
+- [ ] Dodać testy jednostkowe kluczowych funkcji bibliotek (`soc-lib.sh`, `soc-lib-gh.sh`).
+- [ ] Dodać testy smoke dla głównych komend (`init`, `precheck`, `sync`, `open`, `assign`).
+- [ ] Dodać automatyczne uruchamianie walidacji shellowej (np. lint + test) w CI.
+
+### 2.2 Refaktoryzacja i porządki
+- [ ] Rozdzielić funkcje o wysokiej złożoności na mniejsze moduły.
+- [ ] Ujednolicić nazewnictwo funkcji i stałych konfiguracyjnych.
+- [ ] Zmniejszyć duplikację logiki pomiędzy komendami administracyjnymi.
+
+## Etap 3 — Użyteczność dla prowadzących kurs
+
+### 3.1 Lepsza obserwowalność
+- [ ] Rozszerzyć `status` o podsumowanie: liczba repo, przypisań, zaproszeń i niezgodności.
+- [ ] Rozszerzyć `log` o metadane uruchomienia (czas, użytkownik, wersja CLI).
+- [ ] Dodać prosty eksport raportów do CSV/JSON z jednym formatem schematu.
+
+### 3.2 Ergonomia pracy
+- [ ] Dodać interaktywne potwierdzenia z możliwością pominięcia (`--yes`) dla automatyzacji.
+- [ ] Dodać czytelne komunikaty postępu dla dłuższych operacji (`sync`, `open`).
+- [ ] Dodać szybkie komendy diagnostyczne (`soc doctor` / rozszerzony `precheck`).
+
+## Etap 4 — Rozszerzalność platformowa
+
+### 4.1 Interfejs platform
+- [ ] Zdefiniować kontrakt dla nowych platform (`soc-<platform>-*` + wspólne API funkcji).
+- [ ] Przygotować szablon startowy nowej platformy (minimalny zestaw komend + dokumentacja).
+- [ ] Dodać test kompatybilności międzyplatformowej dla dispatcher-a `soc`.
+
+### 4.2 Wersjonowanie i release
+- [ ] Wprowadzić semantyczne wersjonowanie i changelog wydania.
+- [ ] Dodać proces release z checklistą kompatybilności i migracji.
+
+## Etap 5 — Dokumentacja i adopcja
+
+### 5.1 Dokumentacja użytkownika
+- [ ] Przebudować README pod scenariusz „quick start do pierwszego kursu”.
+- [ ] Dodać sekcję „najczęstsze problemy i rozwiązania”.
+- [ ] Dodać pełną tabelę komend z parametrami i przykładami.
+
+### 5.2 Dokumentacja techniczna
+- [ ] Rozszerzyć ADR o standard tworzenia nowych komend i modułów.
+- [ ] Dodać przewodnik contributorski: lokalny workflow, testy, standard zmian.
+
+## Proponowany backlog Issue (do utworzenia i przypisania)
+
+### Epic A — Stabilność i bezpieczeństwo
+- [ ] ISSUE: Rozszerzony precheck walidujący wszystkie pliki konfiguracyjne.
+- [ ] ISSUE: `--dry-run` dla komend modyfikujących stan zasobów GitHub.
+- [ ] ISSUE: Dodatkowe potwierdzenia i mechanizm bezpiecznika dla `delete/unsync`.
+- [ ] ISSUE: Standaryzacja kodów wyjścia i formatu błędów.
+
+### Epic B — Jakość i utrzymanie
+- [ ] ISSUE: Testy jednostkowe dla `soc-lib.sh`.
+- [ ] ISSUE: Testy jednostkowe dla `soc-lib-gh.sh`.
+- [ ] ISSUE: Testy smoke dla ścieżki `init -> precheck -> sync`.
+- [ ] ISSUE: Integracja lint/test w CI.
+
+### Epic C — UX i operacyjność
+- [ ] ISSUE: Rozbudowany `status` z metrykami kursu.
+- [ ] ISSUE: Ujednolicony, czytelny output logów i tryb verbose.
+- [ ] ISSUE: Raport eksportu CSV/JSON.
+- [ ] ISSUE: Quick diagnostics (`doctor`) dla prowadzących.
+
+### Epic D — Rozszerzalność i release
+- [ ] ISSUE: Kontrakt interfejsu platformowego dla `soc-<platform>-*`.
+- [ ] ISSUE: Szablon implementacji nowej platformy.
+- [ ] ISSUE: SemVer + changelog + proces release.
+
+## Kryteria gotowości (Definition of Done)
+- [ ] Każde zadanie ma kryteria akceptacji i właściciela.
+- [ ] Zmiany są pokryte testami adekwatnymi do ryzyka.
+- [ ] Dokumentacja użytkowa i techniczna jest zaktualizowana.
+- [ ] Operacje wysokiego ryzyka mają zabezpieczenia i czytelny rollback.
+- [ ] Brak regresji dla podstawowych komend (`init`, `sync`, `open`, `assign`, `status`).
+

PROPOZYCJE_ISSUES_DLA_SOC_CLI.md

@@ -0,0 +1,24 @@
+# Propozycje Issues dla soc-cli
+
+## Epic A — Stabilność i bezpieczeństwo
+- [ ] ISSUE: Rozszerzony precheck walidujący wszystkie pliki konfiguracyjne.
+- [ ] ISSUE: `--dry-run` dla komend modyfikujących stan zasobów GitHub.
+- [ ] ISSUE: Dodatkowe potwierdzenia i mechanizm bezpiecznika dla `delete/unsync`.
+- [ ] ISSUE: Standaryzacja kodów wyjścia i formatu błędów.
+
+## Epic B — Jakość i utrzymanie
+- [ ] ISSUE: Testy jednostkowe dla `soc-lib.sh`.
+- [ ] ISSUE: Testy jednostkowe dla `soc-lib-gh.sh`.
+- [ ] ISSUE: Testy smoke dla ścieżki `init -> precheck -> sync`.
+- [ ] ISSUE: Integracja lint/test w CI.
+
+## Epic C — UX i operacyjność
+- [ ] ISSUE: Rozbudowany `status` z metrykami kursu.
+- [ ] ISSUE: Ujednolicony, czytelny output logów i tryb verbose.
+- [ ] ISSUE: Raport eksportu CSV/JSON.
+- [ ] ISSUE: Quick diagnostics (`doctor`) dla prowadzących.
+
+## Epic D — Rozszerzalność i release
+- [ ] ISSUE: Kontrakt interfejsu platformowego dla `soc-<platform>-*`.
+- [ ] ISSUE: Szablon implementacji nowej platformy.
+- [ ] ISSUE: SemVer + changelog + proces release.

docs/adr/001-platform-prefixed-commands.md

@@ -0,0 +1,136 @@
+# ADR 001 – Platform-Prefixed Command Scripts
+
+**Status:** Accepted  
+**Date:** 2026-05-14
+
+---
+
+## Context
+
+SoC CLI automates GitHub organization management tasks (creating repos, teams,
+projects, invitations, …).  Initially the entire tool was a single monolithic
+script (`gh-soc`) that could only target the GitHub platform via the GitHub CLI
+(`gh`).
+
+The project was renamed **soc-cli** to reflect a broader vision: the same
+workflow should be usable on other Git hosting platforms (e.g. Gitea via the
+`tea` CLI, GitLab via `glab`).  This required an architecture that cleanly
+separates platform-specific logic from common glue code and from the entry
+point.
+
+---
+
+## Decision
+
+We adopt a **platform-prefixed command-script** model inspired by `git`.
+
+### 1. `soc` – dispatcher
+
+A thin `soc` script acts as the entry point for all commands.  It reads
+`SOC_PLATFORM_CLI` from `system_config.sh` (default: `gh`) and resolves the
+concrete executable to run:
+
+```
+soc open
+  → reads SOC_PLATFORM_CLI='gh'
+  → exec soc-gh-open "$@"
+
+soc open
+  → reads SOC_PLATFORM_CLI='tea'
+  → exec soc-tea-open "$@"
+```
+
+Resolution order:
+
+1. `soc-<platform>-<cmd>` – platform-specific variant (preferred).
+2. `soc-<cmd>` – platform-agnostic fallback (for commands that do not depend
+   on any external CLI).
+
+### 2. `soc-lib.sh` – common library
+
+Contains utilities that are independent of any particular platform:
+
+- Error handling, visual indicators (`OK`, `YUP`, `WRN`, `ERR`).
+- `source_config_files()` – sources the three configuration files.
+- Tool-presence checks for `git`, `sed`, `grep`, `jq`, `date`, `touch`.
+- All `validate_*` functions.
+
+### 3. `soc-lib-gh.sh` – GitHub platform library
+
+Contains everything specific to the GitHub CLI (`gh`):
+
+- `check_if_gh_installed()`, `check_if_gh_has_required_token_scopes()`.
+- All GitHub API / GraphQL helper functions.
+- All main command implementations: `init`, `precheck`, `open`, `close`,
+  `sync`, `unsync`, `log`, `status`, `assign`, `unassign`, `invite`,
+  `disinvite`, `delete`.
+
+### 4. `soc-gh-*` – platform-specific command scripts
+
+One executable file per command, named `soc-gh-<cmd>`.  Each file:
+
+1. Sources `soc-lib.sh` and `soc-lib-gh.sh`.
+2. Sources configuration files (except `soc-gh-init`).
+3. Calls `precheck 0` and `check_if_gh_has_required_token_scopes` (except
+   `soc-gh-init` and `soc-gh-precheck`).
+4. Delegates to the corresponding command function.
+
+Current set:
+
+| Script             | Command       |
+|--------------------|---------------|
+| `soc-gh-init`      | `soc init`    |
+| `soc-gh-precheck`  | `soc precheck`|
+| `soc-gh-sync`      | `soc sync`    |
+| `soc-gh-unsync`    | `soc unsync`  |
+| `soc-gh-open`      | `soc open`    |
+| `soc-gh-close`     | `soc close`   |
+| `soc-gh-invite`    | `soc invite`  |
+| `soc-gh-disinvite` | `soc disinvite`|
+| `soc-gh-assign`    | `soc assign`  |
+| `soc-gh-unassign`  | `soc unassign`|
+| `soc-gh-log`       | `soc log`     |
+| `soc-gh-status`    | `soc status`  |
+| `soc-gh-delete`    | `soc delete`  |
+
+### 5. `gh-soc` – GitHub CLI extension entry point
+
+The file `gh-soc` is kept so that users can continue to invoke the tool as
+`gh soc <command>` through the GitHub CLI extension mechanism.  It is now a
+one-line thin wrapper that delegates to the `soc` dispatcher:
+
+```bash
+exec "$(dirname "${BASH_SOURCE[0]}")/soc" "$@"
+```
+
+### 6. `SOC_PLATFORM_CLI` in `system_config.sh`
+
+The `init` command generates a `system_config.sh` file that now includes:
+
+```bash
+readonly SOC_PLATFORM_CLI='gh'
+```
+
+This variable is the single source of truth for which platform a given working
+directory targets.  Changing its value (e.g. to `'tea'`) switches all `soc`
+commands to the corresponding `soc-tea-*` scripts.
+
+---
+
+## Consequences
+
+### Positive
+
+- Adding support for a new platform (e.g. Gitea) requires only:
+  - A new `soc-lib-tea.sh` with Gitea-specific helper functions.
+  - New `soc-tea-<cmd>` scripts.
+  - Setting `SOC_PLATFORM_CLI='tea'` in `system_config.sh`.
+- The common library (`soc-lib.sh`) and the dispatcher (`soc`) never need to
+  change when a new platform is added.
+- Each command script is small and easy to read in isolation.
+
+### Negative / Trade-offs
+
+- More files to install compared to the original monolith.
+- `soc-lib-gh.sh` is still large; further decomposition may be needed as
+  new platforms are added (to identify which utilities are truly common).