@zigrivers/scaffold 3.6.0 → 3.8.0

package/content/knowledge/library/library-versioning.md

@@ -0,0 +1,300 @@
+---
+name: library-versioning
+description: Semver discipline, breaking change detection, release automation, and changelog management for published libraries
+topics: [library, versioning, semver, breaking-changes, release-automation, changelog, changesets]
+---
+
+Library versioning is a communication protocol with consumers. Semver (Semantic Versioning) is not merely a numbering scheme — it is a contract about backward compatibility. Breaking that contract without a major version bump is one of the most damaging things a library can do. Consumers set version ranges expecting that minor updates are safe to take automatically. Violating that expectation causes production incidents for real applications. Versioning discipline must be enforced by tooling, not willpower.
+
+## Summary
+
+Enforce semver through tooling: use changesets or semantic-release to automate versioning based on change metadata. Use automated breaking change detection (API Extractor or type-coverage checks) to catch accidental breaking changes before publish. Every release requires a CHANGELOG entry with migration guidance for breaking changes. Pre-releases (`alpha`, `beta`, `rc`) allow consumers to opt into early testing without affecting stable installs. Tag releases in git to enable diff-based changelog generation.
+
+Versioning workflow:
+1. Author creates changeset file describing the change type (patch/minor/major)
+2. CI aggregates changesets and proposes a version bump PR
+3. Version bump PR merges, triggering publish to npm
+4. Git tag pushed matching the published version
+5. GitHub Release created from changelog content
+
+## Deep Guidance
+
+### Changesets Workflow
+
+Changesets is the recommended tool for managing versioning in library projects. It decouples the decision of "what version bump does this change require" from "when do we publish."
+
+**Setup:**
+```bash
+npm install --save-dev @changesets/cli
+npx changeset init
+```
+
+This creates a `.changeset/` directory at the project root.
+
+**Creating a changeset (run for every PR that changes behavior):**
+```bash
+npx changeset add
+# Interactive prompt:
+# ? Which packages would you like to include? my-library
+# ? What type of change is this for my-library?
+#   major (Breaking change)
+#   minor (New feature)
+# > patch (Bug fix)
+# ? Please enter a summary for this change:
+# Fix parseConfig() incorrectly ignoring the encoding option
+```
+
+This creates a markdown file in `.changeset/`:
+```markdown
+<!-- .changeset/silver-wolves-grin.md -->
+---
+"my-library": patch
+---
+
+Fix parseConfig() incorrectly ignoring the encoding option when parsing file input.
+```
+
+**Version bump and publish:**
+```bash
+# Update package.json version and CHANGELOG.md
+npx changeset version
+
+# Publish to npm
+npx changeset publish
+```
+
+In CI, automate this with the Changesets GitHub Action:
+```yaml
+# .github/workflows/release.yml
+# name: Release — CI publishes on push to main
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - uses: changesets/action@v1
+        with:
+          publish: npm run release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+The action opens a "Version Packages" PR when changesets are present and publishes when that PR merges.
+
+### Breaking Change Detection with API Extractor
+
+Microsoft's API Extractor catches breaking changes by comparing the current API surface against a committed baseline:
+
+**Setup:**
+```bash
+npm install --save-dev @microsoft/api-extractor
+npx api-extractor init
+```
+
+```json
+// api-extractor.json (key settings)
+{
+  "mainEntryPointFilePath": "<projectFolder>/dist/types/index.d.ts",
+  "apiReport": {
+    "enabled": true,
+    "reportFolder": "<projectFolder>/etc/"
+  },
+  "docModel": {
+    "enabled": true
+  }
+}
+```
+
+```bash
+# Generate initial API report (commit this file)
+npx api-extractor run --local
+
+# In CI: compare against committed report
+npx api-extractor run
+# Fails if the API surface changed in ways not reflected in the committed report
+```
+
+The generated `etc/my-library.api.md` file shows the complete public API surface in a reviewable format. When a PR changes it, reviewers can see exactly what changed. If the change is intentional, update the committed report; if not, fix the breaking change.
+
+**API report excerpt:**
+```markdown
+// @public
+export function parseConfig(input: string, options?: ParseOptions): Config;
+
+// @public
+export interface ParseOptions {
+  encoding?: BufferEncoding;
+  strict?: boolean;
+}
+
+// @public
+export class ParseError extends Error {
+  constructor(message: string, line: number, column: number);
+  readonly column: number;
+  readonly line: number;
+}
+```
+
+This format makes breaking changes immediately visible in code review.
+
+### Pre-Release Channels
+
+Pre-releases allow consumers to test upcoming changes without affecting stable installs:
+
+**With changesets:**
+```bash
+# Enter pre-release mode
+npx changeset pre enter alpha
+# Or: beta, rc
+
+# Create changesets and version as normal
+npx changeset add
+npx changeset version
+# Produces: 2.0.0-alpha.1
+
+# Exit pre-release mode
+npx changeset pre exit
+```
+
+**Manual pre-release versioning:**
+```json
+// package.json
+"version": "2.0.0-alpha.1"
+```
+
+```bash
+npm publish --tag alpha
+# Consumers opt-in: npm install my-library@alpha
+# Stable consumers (npm install my-library) are unaffected
+```
+
+**Pre-release channel strategy:**
+- `alpha` — internal testing only, may change drastically, no API stability
+- `beta` — public testing, API reasonably stable, looking for feedback
+- `rc` (release candidate) — API frozen, looking for final integration issues
+- Stable — semver protected, change policy enforced
+
+### Release Automation with GitHub Actions
+
+Full release workflow with provenance and attestation:
+
+```yaml
+# .github/workflows/release.yml
+# name: Release — CI publishes on tag push
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+  id-token: write  # For npm provenance
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+
+      - name: Publish to npm
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          draft: false
+```
+
+The `--provenance` flag publishes npm provenance attestation — a cryptographic link between the published package and the GitHub Actions run that built it. This allows consumers to verify the package was built from the expected source.
+
+### CHANGELOG Generation
+
+Keep a Changelog format, managed automatically:
+
+```bash
+# With conventional commits, generate changelog automatically:
+npx conventional-changelog-cli -p angular -i CHANGELOG.md -s
+
+# Or with changesets:
+npx changeset version  # Updates CHANGELOG.md automatically
+```
+
+**Manual CHANGELOG structure:**
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+
+## [Unreleased]
+
+## [2.1.0] - 2024-03-15
+
+### Added
+- `parseConfigFile(path)` for file-based parsing
+- `ParseOptions.maxSize` to limit input size
+
+### Fixed
+- `parseConfig()` no longer ignores `encoding` option for buffer inputs
+
+## [2.0.0] - 2024-01-10
+
+### Breaking Changes
+- Removed `parse()` (deprecated in 1.5.0). Replacement: `parseConfig()`.
+- `Config.timeout` is now milliseconds (was seconds). Multiply existing values × 1000.
+- Dropped Node 16 support. Minimum: Node 18.
+
+### Migration Guide
+See: https://my-library.dev/guides/migration-v2
+
+[Unreleased]: https://github.com/org/my-library/compare/v2.1.0...HEAD
+[2.1.0]: https://github.com/org/my-library/compare/v2.0.0...v2.1.0
+[2.0.0]: https://github.com/org/my-library/releases/tag/v2.0.0
+```
+
+### Git Tag Strategy
+
+Tag every release:
+```bash
+# After publishing to npm
+git tag v2.1.0
+git push origin v2.1.0
+
+# Or use npm version (updates package.json, commits, and tags)
+npm version minor -m "chore(release): v%s"
+git push && git push --tags
+```
+
+Tags are the source of truth for "what was published when." They enable:
+- Reproducible builds from any historical version
+- `git diff v2.0.0 v2.1.0` to review what changed between releases
+- Automated changelog generation tools
+- GitHub Release creation linked to the exact commit

package/content/knowledge/mobile-app/mobile-app-architecture.md

@@ -0,0 +1,283 @@
+---
+name: mobile-app-architecture
+description: MVVM/MVI/TCA patterns, navigation architecture, dependency injection, and state management for iOS and Android mobile apps
+topics: [mobile-app, architecture, mvvm, mvi, tca, navigation, dependency-injection, state-management]
+---
+
+Mobile app architecture determines testability, scalability, and developer velocity. The wrong architecture is expensive to reverse — a monolithic ViewController or God Activity becomes unmaintainable at scale. Both iOS and Android ecosystems have converged on unidirectional data flow patterns: TCA and MVVM+Combine/async for iOS, MVI and MVVM+Flow for Android. Choose the pattern that matches your team's size and complexity requirements, not the most sophisticated available option.
+
+## Summary
+
+iOS architectures: MVVM with SwiftUI/Combine for mid-size apps, TCA (The Composable Architecture) for large apps requiring strict testability and state isolation. Android architectures: MVVM with StateFlow for most apps, MVI for complex state management. Both platforms benefit from clean architecture layers — presentation, domain, data — with dependency injection (Hilt for Android, constructor injection or a container for iOS). Navigation architecture is separate from view architecture: use Coordinator (iOS) or Navigation Component (Android).
+
+## Deep Guidance
+
+### iOS Architecture Patterns
+
+**MVVM with SwiftUI**
+
+The standard pattern for new iOS apps. The ViewModel is an `@Observable` class (iOS 17+) or `ObservableObject` (iOS 13+) that holds and transforms state:
+
+```swift
+@Observable
+final class UserProfileViewModel {
+    var user: User?
+    var isLoading = false
+    var error: Error?
+
+    private let repository: UserRepository
+
+    init(repository: UserRepository) {
+        self.repository = repository
+    }
+
+    func loadUser(id: String) async {
+        isLoading = true
+        defer { isLoading = false }
+        do {
+            user = try await repository.fetchUser(id: id)
+        } catch {
+            self.error = error
+        }
+    }
+}
+
+struct UserProfileView: View {
+    @State private var viewModel = UserProfileViewModel(repository: LiveUserRepository())
+
+    var body: some View {
+        Group {
+            if viewModel.isLoading { ProgressView() }
+            else if let user = viewModel.user { UserDetailView(user: user) }
+            else if viewModel.error != nil { ErrorView() }
+        }
+        .task { await viewModel.loadUser(id: userId) }
+    }
+}
+```
+
+Rules for healthy MVVM:
+- ViewModels must not import UIKit or SwiftUI — they are platform-agnostic
+- One ViewModel per screen/feature, not per view hierarchy level
+- ViewModels receive dependencies via constructor injection — no singletons
+- ViewModels hold only UI state, not business logic — business logic belongs in services/repositories
+- Test ViewModels by injecting fake dependencies and asserting state transitions
+
+**TCA (The Composable Architecture)**
+
+For large apps with complex state, strict testability requirements, or large teams. TCA provides a single-direction state mutation model:
+
+```swift
+@Reducer
+struct UserProfileFeature {
+    @ObservableState
+    struct State: Equatable {
+        var user: User?
+        var isLoading = false
+        var error: String?
+    }
+
+    enum Action {
+        case loadUser(String)
+        case userLoaded(Result<User, Error>)
+    }
+
+    @Dependency(\.userRepository) var userRepository
+
+    var body: some ReducerOf<Self> {
+        Reduce { state, action in
+            switch action {
+            case .loadUser(let id):
+                state.isLoading = true
+                return .run { send in
+                    await send(.userLoaded(Result { try await userRepository.fetchUser(id: id) }))
+                }
+            case .userLoaded(.success(let user)):
+                state.isLoading = false
+                state.user = user
+                return .none
+            case .userLoaded(.failure(let error)):
+                state.isLoading = false
+                state.error = error.localizedDescription
+                return .none
+            }
+        }
+    }
+}
+```
+
+TCA benefits: every state mutation is explicit, side effects are isolated and cancellable, testing is deterministic. TCA costs: steep learning curve, boilerplate-heavy for simple features, requires team-wide adoption to be consistent.
+
+**Clean Architecture layers for iOS**
+```
+Presentation Layer: Views + ViewModels
+    ↓ calls
+Domain Layer: Use Cases + Domain Models + Repository Protocols
+    ↓ calls
+Data Layer: Repository Implementations + Network + Persistence
+```
+
+- Domain layer has zero dependencies on UIKit, SwiftUI, or any specific framework
+- Repository protocols defined in the domain layer, implemented in the data layer
+- Use cases encapsulate single business operations: `FetchUserProfileUseCase`, `SubmitOrderUseCase`
+
+### Android Architecture Patterns
+
+**MVVM with StateFlow**
+
+The Google-recommended pattern, aligning with Android's official architecture guidance:
+
+```kotlin
+data class UserProfileUiState(
+    val user: User? = null,
+    val isLoading: Boolean = false,
+    val error: String? = null
+)
+
+@HiltViewModel
+class UserProfileViewModel @Inject constructor(
+    private val userRepository: UserRepository
+) : ViewModel() {
+
+    private val _uiState = MutableStateFlow(UserProfileUiState())
+    val uiState: StateFlow<UserProfileUiState> = _uiState.asStateFlow()
+
+    fun loadUser(userId: String) {
+        viewModelScope.launch {
+            _uiState.update { it.copy(isLoading = true) }
+            userRepository.fetchUser(userId)
+                .onSuccess { user ->
+                    _uiState.update { it.copy(user = user, isLoading = false) }
+                }
+                .onFailure { error ->
+                    _uiState.update { it.copy(error = error.message, isLoading = false) }
+                }
+        }
+    }
+}
+
+@Composable
+fun UserProfileScreen(viewModel: UserProfileViewModel = hiltViewModel()) {
+    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+    // render based on uiState
+}
+```
+
+**MVI (Model-View-Intent)**
+
+For features with complex state machines where MVVM state updates become hard to reason about:
+
+```kotlin
+sealed class UserProfileIntent {
+    data class LoadUser(val userId: String) : UserProfileIntent()
+    data object Refresh : UserProfileIntent()
+}
+
+sealed class UserProfileEffect {
+    data class ShowError(val message: String) : UserProfileEffect()
+    data object NavigateToLogin : UserProfileEffect()
+}
+```
+
+MVI separates user intentions from state mutations. The `SharedFlow` channel (`_effect`) handles one-shot events (navigation, toasts) that must not survive recomposition — a critical distinction from `StateFlow`.
+
+**One-shot events vs. state**
+- Use `StateFlow` for persistent UI state: loading, data, errors that survive recomposition
+- Use `SharedFlow` or `Channel` (as `Flow`) for one-shot effects: navigation commands, snackbar messages, dialog triggers
+- Never put navigation events in `StateFlow` — they replay on configuration change, causing double navigation
+
+**Clean Architecture layers for Android**
+```
+UI Layer: Composables + ViewModels
+    ↓ calls
+Domain Layer: Use Cases + Domain Models + Repository Interfaces
+    ↓ calls
+Data Layer: Repository Implementations + RemoteDataSource + LocalDataSource
+```
+
+- Domain layer: pure Kotlin module (`core/domain`) with no Android dependencies
+- Use cases: single `operator fun invoke()` or `execute()` function
+- Repository pattern: the domain defines the interface; data layer implements it
+
+### Dependency Injection
+
+**Android: Hilt**
+
+Hilt is the recommended DI framework for Android:
+
+```kotlin
+// Define a module
+@Module
+@InstallIn(SingletonComponent::class)
+object NetworkModule {
+    @Provides
+    @Singleton
+    fun provideOkHttpClient(): OkHttpClient = OkHttpClient.Builder().build()
+
+    @Provides
+    @Singleton
+    fun provideRetrofit(client: OkHttpClient): Retrofit = Retrofit.Builder()
+        .baseUrl(BuildConfig.BASE_URL)
+        .client(client)
+        .addConverterFactory(GsonConverterFactory.create())
+        .build()
+}
+
+// Inject into ViewModel
+@HiltViewModel
+class HomeViewModel @Inject constructor(
+    private val userRepository: UserRepository,
+    private val analyticsService: AnalyticsService
+) : ViewModel()
+```
+
+Hilt scopes: `SingletonComponent` (app lifetime), `ActivityRetainedComponent` (ViewModel lifetime), `ViewModelComponent` (ViewModel scope), `FragmentComponent`, `ActivityComponent`. Match the scope to the dependency's actual lifetime.
+
+**iOS: Constructor injection + container**
+
+Swift does not have a dominant DI framework. Use constructor injection as the default:
+
+```swift
+// Dependency container
+final class AppDependencies {
+    static let shared = AppDependencies()
+
+    lazy var networkClient: NetworkClient = URLSessionNetworkClient()
+    lazy var userRepository: UserRepository = NetworkUserRepository(client: networkClient)
+    lazy var analyticsService: AnalyticsService = FirebaseAnalyticsService()
+}
+
+// Inject at the composition root (app entry point or Coordinator)
+let viewModel = UserProfileViewModel(
+    repository: AppDependencies.shared.userRepository
+)
+```
+
+For testing: define protocols for all dependencies and inject fakes in tests. Never call `AppDependencies.shared` inside a ViewModel — inject via constructor.
+
+### State Management
+
+**iOS state scoping**
+- `@State`: view-local ephemeral state (animation flags, text field values) — does not survive view destruction
+- `@Binding`: two-way binding from parent to child — child can mutate parent's state
+- `@Observable` / `@ObservableObject`: shared mutable state in a ViewModel — survives view re-renders
+- `@Environment`: dependency injection through the view tree (theme, locale, custom services)
+- `@EnvironmentObject`: globally shared state accessed without explicit passing — use sparingly, only for truly app-wide state (user session, theme)
+- Avoid prop-drilling state through 4+ view layers — use `@Environment` or restructure to lift state to a shared ancestor ViewModel
+
+**Android state scoping**
+- `remember { }`: view-local ephemeral state in Compose — survives recomposition, not configuration change
+- `rememberSaveable { }`: survives configuration change by saving to Bundle
+- `StateFlow` in ViewModel: survives configuration change automatically (ViewModel lifecycle)
+- `SavedStateHandle` in ViewModel: persists through process death for critical state (form data, scroll position)
+- Hoist state to the lowest ancestor that needs it — do not hoist everything to the ViewModel
+
+**Handling configuration changes (Android)**
+- ViewModel automatically survives rotation and theme change — the primary benefit of the ViewModel
+- Always collect `StateFlow` with `collectAsStateWithLifecycle()` in Compose — stops collection when UI is not visible, preventing wasted work and crashes in background
+
+**Background state handling (iOS)**
+- ScenePhase: observe `\.scenePhase` in SwiftUI to react to foreground/background transitions
+- Save in-progress work when entering background: `@Environment(\.scenePhase) var scenePhase`
+- `@AppStorage`: lightweight persistence backed by UserDefaults for small values
+- Combine state from multiple sources with `Publishers.CombineLatest` or async/await TaskGroup