Native Shell Upgrade Guide

View Source

This guide tracks per-template-version changes to the generated iOS and Android shell projects. Versions are listed newest-first. Each entry leads with the RebuildPolicy.classify/2 verdict and the named change-class atoms so you can determine the adopter action before reading the details.

The shell is host-owned after generation. Every upgrade is elective. Even OTA-safe entries document what changed so you can make an informed decision about whether to apply the update.

Use mix crosswake.gen.shell --diff to compare your on-disk shell against the current templates before deciding whether to incorporate changes.

Use mix crosswake.shell.status to check whether your generated shell manifest matches the current template_version.

Template Version 2 (Phase 134 — stamp, manifest, diff)

RebuildPolicy verdict: :ota_safe — change class: :docs_wording (template commentary only)

What changed

  • A 2-line provenance stamp was added to all 15 stamp-eligible templates (Swift, Kotlin, Groovy, Properties, XML, and plist files). The stamp records the crosswake version and integer template_version at generation time.
  • A .crosswake/shell.json manifest is now written to the per-platform generated root on every mix crosswake.gen.shell invocation. The manifest captures crosswake_version, template_version, platform, generated_at, and params (router, local, target).
  • The gradlew.bat and gradlew scripts and project.pbxproj were not stamped (binary-safe exclusions per Phase 134 design).

Should you rebuild?

RebuildPolicy.classify/2 called with :docs_wording returns :ota_safe. The stamp and manifest additions are commentary and metadata only — no native code, entitlements, permissions, or platform configuration changed.

iex> RebuildPolicy.classify(:docs_wording, nil)
# Equivalent outcome: :ota_safe

No rebuild of the host binary is required.

Files changed in this template version

iOS (6 stamped templates):

  • CrosswakeShell/CrosswakeShellApp.swift
  • CrosswakeShell/CrosswakeCoordinator.swift
  • CrosswakeShell/Info.plist
  • CrosswakeShell/CrosswakeShell.entitlements
  • CrosswakeShell/PrivacyInfo.xcprivacy
  • CrosswakeShell.xcodeproj/xcshareddata/xcschemes/CrosswakeShell.xcscheme

Android (9 stamped templates):

  • settings.gradle
  • build.gradle
  • gradle.properties
  • gradle/wrapper/gradle-wrapper.properties
  • app/build.gradle
  • app/src/main/AndroidManifest.xml
  • app/src/main/java/dev/crosswake/shell/MainActivity.kt
  • app/src/main/java/dev/crosswake/shell/CrosswakeViewModel.kt
  • app/src/main/res/values/themes.xml

Template Version 1 (initial)

RebuildPolicy verdict: baseline — no prior version to upgrade from.

What changed

Template Version 1 established the initial generated shell scaffold:

  • iOS Xcode project with CrosswakeShellApp.swift, CrosswakeCoordinator.swift, Info.plist, entitlements, privacy manifest, and xcscheme.
  • Android Studio project with Kotlin MainActivity, CrosswakeViewModel, AndroidManifest.xml, Gradle build files, and themes.
  • Bundled canonical manifest, activation, denial, and pack inventory fixtures under Fixtures/ (iOS) and app/src/main/assets/ (Android).

Should you rebuild?

This is the baseline version. There is no prior shell to upgrade from. Run mix crosswake.gen.shell ios and/or mix crosswake.gen.shell android to generate Template Version 1 output.

RebuildPolicy.classify/2 is not applicable at the initial baseline — there is no prior template version to classify a change against.

Files changed in this template version

All generated shell files — this is the initial scaffold.