till/mana-swift-core
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
mana-swift-core/CLAUDE.md
Till JS df6f67ee45 v1.0.0 — initiale Extraktion aus memoro-native 
ManaCore + ManaTokens als Swift-Package für alle nativen
mana-e.V.-Apps. Phase α aus mana/docs/MANA_SWIFT.md durch.

ManaCore:
- AuthClient gegen mana-auth (Login, Refresh, Status-Maschine)
- AuthenticatedTransport (URLSession + 401-Retry)
- ManaAppConfig-Protocol für App-injizierbare Konfig
- KeychainStore mit optionaler Shared-Access-Group
- JWT-Parser für lokale Expiry-Prüfung
- AuthError, CoreLog (interne OSLog-Logger)

ManaTokens:
- 12 Vereins-Tokens als dynamic Light/Dark Colors
- 5 Brand-Literale (mana-yellow, spectrum-orange, ...)
- Spacing, Radius, Typography aus mana/docs/THEMING.md

Tests: 12 Unit-Tests grün via swift test.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 19:13:31 +02:00

4.4 KiB
Raw Permalink Blame History

CLAUDE.md — mana-swift-core

Guidance für Claude Code in diesem Repo.

Übergeordneter Plan: ../mana/docs/MANA_SWIFT.md ist die SOT für die ganze native-App-Plattform. Dieses CLAUDE.md ist die Repo-lokale Konventionen-Doku.

Was dieses Repo ist

Swift-Package-Plattform für alle nativen mana-e.V.-Apps. Enthält genau zwei Library-Products:

  • ManaCore — Auth (mana-auth-Login, JWT-Refresh, Keychain), Transport (URLSession-Wrapper mit 401-Retry).
  • ManaTokens — Verein-Designwerte. Spiegelt mana/docs/THEMING.md.

Wird konsumiert von memoro-native, geplant cards-native, nutriphi-native und weiteren.

Status

v1.0.0 — initiale Extraktion aus memoro-native (2026-05-12).

Phase α aus mana/docs/MANA_SWIFT.md — wortwörtliche Verschiebung von Core/Auth, Core/API/Transport, plus ManaTokens neu aus mana/docs/THEMING.md. Keine spekulativen Verallgemeinerungen.

Architektonische Invarianten

Nicht ohne explizite Diskussion antasten:

  1. Genau zwei Library-Products. ManaCore + ManaTokens. Ein ManaUI-Komponenten-Package entsteht später in einem eigenen Repo, nicht hier (mana/docs/MANA_SWIFT.md Phase ε).
  2. Keine externen Dependencies. ManaCore darf nur Foundation, Security, OSLog, Combine importieren. Kein Alamofire, kein Sentry, kein nichts. Compliance (mana/docs/COMPLIANCE.md) + Build-Stabilität.
  3. Public API ist Sendable. Jeder Cross-Actor-Type. Swift-6- Concurrency-Korrektheit.
  4. Keine app-spezifischen Annahmen. ManaCore weiß nichts über Memos, Decks, Meals. PRs, die "irgendwas für Memoro" hinzufügen wollen, gehören in memoro-native, nicht hier.
  5. mana-auth-Wissen ist erlaubt. Endpoint-Pfade /api/v1/auth/login, /api/v1/auth/refresh, Wire-Format mit accessToken/refreshToken. Das ist Verein-Plattform-Konstante, nicht App-Detail.
  6. OSLog statt print/Sentry. ManaCore loggt intern unter Subsystem ev.mana.core. Apps haben ihr eigenes Subsystem.
  7. App injiziert ihre Config. ManaCore hardcoded nichts (außer die mana-auth-Endpoint-Pfade als Konstante). authBaseURL, keychainService, keychainAccessGroup kommen vom App-Caller.
  8. Tests gegen reine Logik. JWT-Decode, Token-Expiry, Keychain- Key-Mapping. URLSession-Calls werden über Protokoll-Injection getestet, nicht über echtes Netzwerk.

Versionierung

  • Semver strikt. Patch = Bugfix ohne API-Änderung. Minor = neue API additiv. Major = breaking.
  • Git-Tag nach jedem Sinn-Abschnitt auf main. Nicht jeden Commit.
  • CHANGELOG.md pflicht. Was hat sich geändert, müssen Apps was anpassen.
  • Pflege-Politik: Letzte zwei Major-Versionen werden mit Patches bedient. Ältere nicht.

Konventionen

  • Swift 6.0, Strict Concurrency komplett
  • iOS 18 / macOS 15 Minimum (gleiche Targets wie memoro-native)
  • SwiftFormat mit .swiftformat (4-space, 120-col, sorted imports)
  • SwiftLint mit .swiftlint.yml
  • Doc-Comments pflicht auf jedem public-Symbol (///)
  • Lokalisierung: Public-API-Strings auf Deutsch (Verein-Konvention), Code-Identifier auf Englisch

Lokal entwickeln

swift build                          # baut beide Targets
swift test                           # Unit-Tests
swift package generate-xcodeproj     # optional, für Xcode

Für die Integration in eine App (memoro-native, cards-native):

  • Dev-Cycle: in project.yml der App path: ../mana-swift-core setzen
  • Release: from: 1.0.0 mit Git-Tag

Wenn eine neue Funktion dazukommt

  1. Frage: gehört das wirklich in ManaCore/ManaTokens, oder ist es App-spezifisch? Wenn unsicher: in die App, später extrahieren.
  2. Public API mit Doc-Comments.
  3. Unit-Tests gegen die State-Machine, nicht gegen echtes Netzwerk.
  4. CHANGELOG.md ergänzen.
  5. Bei Breaking-Change: Major-Bump-Plan in mana/docs/MANA_SWIFT.md notieren, alle aktiven Apps informieren.

Wichtige Cross-Repo-Doks

  • mana/docs/MANA_SWIFT.md — Plattform-SOT für native Apps
  • mana/docs/MANA_AUTH_FEDERATION.md — Auth-Protokoll
  • mana/docs/THEMING.md — Token-SOT, spiegelt sich in ManaTokens
  • mana/docs/COMPLIANCE.md — Telemetrie/Crash-Reporter-Regeln
  • mana/services/mana-auth/CLAUDE.md — Server-Konventionen, § "Native-App-Koordination" beschreibt die Refresh-Token-Invariante
  • memoro-native/CLAUDE.md — erste Konsumenten-App, Konventionen hier sind aus deren PLAN.md gewachsen