### Bootstrap TestFlight Setup Source: https://github.com/dnakov/litter/blob/main/docs/DEVELOPMENT.md Initializes TestFlight setup by providing the application bundle ID to the setup script. ```bash APP_BUNDLE_ID= ./apps/ios/scripts/testflight-setup.sh ``` -------------------------------- ### Install and Launch App on Android Emulator Source: https://github.com/dnakov/litter/blob/main/CLAUDE.md Build the Android app for emulator, install it using adb, and then launch the main activity. ```bash make android-emulator-fast ``` ```bash adb -e install -r apps/android/app/build/outputs/apk/debug/app-debug.apk ``` ```bash adb -e shell am start -n com.sigkitten.litter.android/com.litter.android.MainActivity ``` -------------------------------- ### Install and Launch App on iOS Simulator Source: https://github.com/dnakov/litter/blob/main/CLAUDE.md Install the latest built app directly from DerivedData onto the iOS simulator and then launch it. ```bash xcrun simctl install booted <.../Build/Products/Debug-iphonesimulator/Litter.app> ``` ```bash xcrun simctl launch booted com.sigkitten.litter ``` -------------------------------- ### Install Meson and Ninja Source: https://github.com/dnakov/litter/blob/main/docs/DEVELOPMENT.md Installs Meson and Ninja build systems, which are dependencies for webrtc-audio-processing-sys. ```bash brew install meson ``` -------------------------------- ### Install xcodegen Source: https://github.com/dnakov/litter/blob/main/docs/DEVELOPMENT.md Installs xcodegen, a tool used for regenerating the Litter.xcodeproj file. ```bash brew install xcodegen ``` -------------------------------- ### Install Xcode Command Line Tools Source: https://github.com/dnakov/litter/blob/main/apps/ios/fastlane/README.md Ensure the latest version of the Xcode command line tools are installed before proceeding with Fastlane installation. ```sh xcode-select --install ``` -------------------------------- ### Basic SVG Setup Source: https://github.com/dnakov/litter/blob/main/shared/rust-bridge/codex-mobile-client/src/widget_guidelines/svg_setup.md Sets up a responsive SVG with a fixed width of 360px and a flexible height that fits content tightly. The viewBox width is critical for 1:1 rendering with CSS pixels. ```html ``` -------------------------------- ### CMake Minimum Version and Project Setup Source: https://github.com/dnakov/litter/blob/main/apps/android/core/bridge/src/main/cpp/CMakeLists.txt Sets the minimum required CMake version and defines the project name and languages. ```cmake cmake_minimum_required(VERSION 3.22.1) project(litter_ghostty_jni LANGUAGES CXX) ``` -------------------------------- ### Install Rust and iOS Targets Source: https://github.com/dnakov/litter/blob/main/docs/DEVELOPMENT.md Installs Rust via rustup and adds necessary iOS targets for cross-compilation. Avoid Homebrew's Rust formula to prevent conflicts. ```bash curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh rustup target add aarch64-apple-ios aarch64-apple-ios-sim x86_64-apple-ios ``` -------------------------------- ### Run Codex App Server Locally Source: https://github.com/dnakov/litter/blob/main/docs/DEVELOPMENT.md Starts the Codex app server listening on a specific local WebSocket address. Avoid binding to 0.0.0.0 unless fully understood. ```bash codex app-server --listen ws://127.0.0.1:8390 ``` -------------------------------- ### Download ios_system Frameworks Source: https://github.com/dnakov/litter/blob/main/docs/ios/quickstart.md Fetches the necessary `ios_system` frameworks for the project. ```bash ./apps/ios/scripts/download-ios-system.sh ``` -------------------------------- ### Build iOS App with Make Source: https://github.com/dnakov/litter/blob/main/docs/ios/quickstart.md Use these Make commands for a comprehensive iOS build process, including device and simulator targets. The recommended approach handles all necessary steps like submodule synchronization, UniFFI bindings, and Xcode project generation. ```bash # Full iOS build (device + simulator) make ios # Simulator only (faster) make ios-sim # Device only make ios-device # Build + open Xcode make ios-run ``` -------------------------------- ### Fast Build Commands Source: https://github.com/dnakov/litter/blob/main/README.md Use these commands for quick builds of the iOS and Android applications. ```bash make ios-device-fast # fast device build make ios-sim-fast # fast simulator build make android-emulator-fast # fast Android emulator build ``` -------------------------------- ### Open Xcode Project Source: https://github.com/dnakov/litter/blob/main/docs/DEVELOPMENT.md Opens the Litter Xcode project in the Xcode application. ```bash open apps/ios/Litter.xcodeproj ``` -------------------------------- ### Android Debug Build Command Source: https://github.com/dnakov/litter/blob/main/docs/architecture/ios-android-monorepo-migration-plan.md The command to execute a debug build for the Android application, used to verify the native Android setup. ```bash ./gradlew :app:assembleDebug ``` -------------------------------- ### Get Saved App Details Source: https://github.com/dnakov/litter/blob/main/apps/android/docs/qa-matrix.md Retrieves details for a specific saved app using its UUID. This is called upon entering the SavedAppScreen. ```kotlin savedAppGet(dir, uuid) ``` -------------------------------- ### Build Android App with Gradle Source: https://github.com/dnakov/litter/blob/main/docs/android/quickstart.md Use this command to assemble the debug version of the Android application. ```bash gradle -p apps/android :app:assembleDebug ``` -------------------------------- ### Set Saved Apps Directory Source: https://github.com/dnakov/litter/blob/main/apps/android/docs/qa-matrix.md Initializes the directory for saved applications. This must be called once before any threads start to ensure the Rust finalize hook functions correctly. ```kotlin AppClient.setSavedAppsDirectory(MobilePreferencesDirectory.path(context)) ``` -------------------------------- ### Run Fastlane iOS Screenshots Action Source: https://github.com/dnakov/litter/blob/main/apps/ios/fastlane/README.md Execute the Fastlane action to capture screenshots for your iOS application. Use 'bundle exec' if Fastlane is installed via Bundler. ```sh [bundle exec] fastlane ios screenshots ``` -------------------------------- ### Importing a Pre-built Shared Library Source: https://github.com/dnakov/litter/blob/main/apps/android/core/bridge/src/main/cpp/CMakeLists.txt Imports an existing shared library (libghostty.so) and sets its properties, including the import location and interface include directories. ```cmake add_library(ghostty SHARED IMPORTED) set_target_properties( ghostty PROPERTIES IMPORTED_LOCATION "${CMAKE_CURRENT_SOURCE_DIR}/../jniLibs/${ANDROID_ABI}/libghostty.so" INTERFACE_INCLUDE_DIRECTORIES "${CMAKE_CURRENT_SOURCE_DIR}/include" ) ``` -------------------------------- ### Build Rust Bridge Source: https://github.com/dnakov/litter/blob/main/docs/DEVELOPMENT.md Builds the Rust bridge for iOS. Use --fast-device for raw device staticlib only. ```bash ./apps/ios/scripts/build-rust.sh ./apps/ios/scripts/build-rust.sh --fast-device ``` -------------------------------- ### SVG Arrow Marker Definition Source: https://github.com/dnakov/litter/blob/main/shared/rust-bridge/codex-mobile-client/src/widget_guidelines/svg_setup.md Include this `` block at the start of every SVG to define a reusable arrow marker. The marker uses `context-stroke` to inherit the line's color, ensuring consistency. ```html ``` -------------------------------- ### Direct Fetch for Store Artifacts Source: https://github.com/dnakov/litter/blob/main/CLAUDE.md Use this script directly for one-off raw iOS/Android store snapshots or deeper API debugging. ```bash fetch-mobile-store-artifacts.py ``` -------------------------------- ### Structural Container Example in SVG Source: https://github.com/dnakov/litter/blob/main/shared/rust-bridge/codex-mobile-client/src/widget_guidelines/diagram_types.md This SVG code demonstrates a structural diagram for a library branch, illustrating nested containers and regions with specific styling for different modes. It includes definitions for markers and uses CSS classes for color theming. ```svg Library branch Main floor Circulation desk Checkouts, returns Books Reading room Seating, reference ``` -------------------------------- ### Control Codex Desktop Controller Instance Source: https://github.com/dnakov/litter/blob/main/tools/scripts/README.md Attaches to a running Codex desktop application instance or controls an existing one. Use --port to specify the debugging port. The --launch flag can be used to start a new instance if needed. ```bash # Attach to an already-running automation instance and inspect the active thread. node tools/scripts/codex-desktop-controller.mjs thread-state --port 9333 ``` ```bash # Send one turn into the current thread, wait for the assistant to finish, and print JSON. node tools/scripts/codex-desktop-controller.mjs run-turn \ --port 9333 \ --message 'Reply with exactly: OK' ``` ```bash # Start a fresh thread in a sidebar project, run the first turn, and print the final transcript. node tools/scripts/codex-desktop-controller.mjs run-turn \ --port 9333 \ --project codex-test \ --message 'Reply with exactly: OK' ``` -------------------------------- ### Run Android Play Upload Script Source: https://github.com/dnakov/litter/blob/main/docs/releases/android-play-internal-checklist.md Execute the main script for uploading Android builds to the Play Console. ```bash ./apps/android/scripts/play-upload.sh ``` -------------------------------- ### Open Android Project in Android Studio Source: https://github.com/dnakov/litter/blob/main/apps/android/README.md Command to open the Android project directory in Android Studio on macOS. ```bash open -a "Android Studio" apps/android ``` -------------------------------- ### Authenticate with App Store Connect Source: https://github.com/dnakov/litter/blob/main/docs/DEVELOPMENT.md Logs into App Store Connect using API credentials. Ensure the private key path is correct. ```bash asc auth login \ --name "Litter ASC" \ --key-id "" \ --issuer-id "" \ --private-key "$HOME/AppStore.p8" \ --network ``` -------------------------------- ### Build Only (No Upload) Source: https://github.com/dnakov/litter/blob/main/docs/releases/android-play-internal-checklist.md Set UPLOAD=0 to perform a build without uploading the artifact to the Play Console. ```bash UPLOAD=0 ./apps/android/scripts/play-upload.sh ``` -------------------------------- ### Building a Custom Shared Library Source: https://github.com/dnakov/litter/blob/main/apps/android/core/bridge/src/main/cpp/CMakeLists.txt Creates a new shared library (litter_ghostty_jni) from source files and links it with the imported ghostty library and other system libraries. ```cmake add_library(litter_ghostty_jni SHARED ghostty_jni.cpp) target_compile_features(litter_ghostty_jni PRIVATE cxx_std_17) target_include_directories(litter_ghostty_jni PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/include") target_link_libraries(litter_ghostty_jni PRIVATE ghostty EGL GLESv3 android log) ``` -------------------------------- ### Capture Baseline Build Commands Source: https://github.com/dnakov/litter/blob/main/docs/architecture/ios-android-monorepo-migration-plan.md Essential commands to ensure the iOS project remains buildable before migration steps begin. These must pass to satisfy exit criteria. ```bash xcodegen generate xcodebuild -project Litter.xcodeproj -scheme Litter -configuration Debug -destination 'platform=iOS Simulator,name=iPhone 17 Pro' build ``` -------------------------------- ### Run iOS App Store Release Script Source: https://github.com/dnakov/litter/blob/main/docs/DEVELOPMENT.md Execute the app store release script for iOS. Ensure all required environment variables are set, including bundle ID, App Store Connect IDs, Apple Team ID, API keys, and the path to the private key. Metadata is sourced from the specified directory. ```bash APP_BUNDLE_ID= \ APP_STORE_APP_ID= \ TEAM_ID= \ ASC_KEY_ID= \ ASC_ISSUER_ID= \ ASC_PRIVATE_KEY_PATH="$HOME/AppStore.p8" \ ./apps/ios/scripts/app-store-release.sh ``` -------------------------------- ### Fast Lane Commands for Local Iteration Source: https://github.com/dnakov/litter/blob/main/CLAUDE.md Use these commands for faster local iteration on iOS and Android. ```bash make ios-sim-fast ``` ```bash make ios-device-fast ``` ```bash make android-emulator-fast ``` -------------------------------- ### Local Mac Direct Distribution Pipeline Source: https://github.com/dnakov/litter/blob/main/docs/releases/mac-distribution-checklist.md Execute the full Mac direct distribution pipeline, including notarization. Requires ASC API key environment variables to be set. Alternatively, skip notarization for testing the build script itself. ```bash ASC_PRIVATE_KEY_PATH=/path/to/AuthKey.p8 \ ASC_KEY_ID=ABC123 \ ASC_ISSUER_ID=00000000-0000-0000-0000-000000000000 \ make mac-direct-dist ``` ```bash SKIP_NOTARIZATION=1 make mac-direct-dist ``` ```bash DMG_SKIP_FINDER_LAYOUT=1 SKIP_NOTARIZATION=1 make mac-direct-dist ``` -------------------------------- ### Build and Upload to TestFlight Source: https://github.com/dnakov/litter/blob/main/docs/DEVELOPMENT.md Builds the iOS application and uploads it to TestFlight. Automatically bumps patch version if live, and increments build number from App Store Connect. ```bash APP_BUNDLE_ID= \ APP_STORE_APP_ID= \ TEAM_ID= \ ASC_KEY_ID= \ ASC_ISSUER_ID= \ ASC_PRIVATE_KEY_PATH="$HOME/AppStore.p8" \ ./apps/ios/scripts/testflight-upload.sh ``` -------------------------------- ### Launch Codex Desktop Controller Source: https://github.com/dnakov/litter/blob/main/tools/scripts/README.md Launches a new instance of the Codex desktop application with remote debugging enabled. Specify the app path, debugging port, and a user data directory. Use --fresh-launch to ensure a new instance even if one already exists on the specified port and profile. ```bash # Launch a separate Codex instance with Electron remote debugging enabled. node tools/scripts/codex-desktop-controller.mjs launch \ --app "/Applications/Codex copy.app" \ --port 9333 \ --user-data-dir /tmp/codex-desktop-controller-profile ``` ```bash # Reuse that same instance on later commands. Add --fresh-launch only if you # intentionally want a brand new app instance on the same port/profile setup. node tools/scripts/codex-desktop-controller.mjs thread-state --port 9333 --launch ``` -------------------------------- ### Assemble Android App Variants Source: https://github.com/dnakov/litter/blob/main/apps/android/README.md Use these Gradle commands to assemble different build variants of the Android application. Specify the target for on-device or remote-only debugging. ```bash ./gradlew :app:assembleOnDeviceDebug ``` ```bash ./gradlew :app:assembleRemoteOnlyDebug ``` -------------------------------- ### Load Initial App State Source: https://github.com/dnakov/litter/blob/main/apps/android/docs/qa-matrix.md Loads the initial application state from the seeded state JSON, enabling cold-launch persistence. ```kotlin loadAppState() ``` -------------------------------- ### Run Unit Tests for Android Runtime Flavors Source: https://github.com/dnakov/litter/blob/main/apps/android/docs/qa-matrix.md Execute unit tests for both the on-device and remote-only runtime flavors of the Android application. ```bash ./gradlew :app:testOnDeviceDebugUnitTest ./gradlew :app:testRemoteOnlyDebugUnitTest ``` -------------------------------- ### Validate App with Wait Option Source: https://github.com/dnakov/litter/blob/main/docs/releases/export-compliance/README.md Once the encryption documentation review is complete in App Store Connect, run this command to validate your app. The --wait flag ensures the command only returns after validation is finished. ```bash asc validate com.sigkitten.litter --wait ``` -------------------------------- ### Build iOS Project with Xcodebuild Source: https://github.com/dnakov/litter/blob/main/docs/DEVELOPMENT.md Builds the Litter project for an iOS Simulator using xcodebuild. ```bash xcodebuild -project apps/ios/Litter.xcodeproj -scheme Litter -configuration Debug -destination 'platform=iOS Simulator,name=iPhone 17 Pro' build ``` -------------------------------- ### Build App with Xcodebuild Source: https://github.com/dnakov/litter/blob/main/docs/ios/quickstart.md Builds the application using `xcodebuild` for a specific configuration and destination. This command is typically used after project generation. ```bash xcodebuild -project apps/ios/Litter.xcodeproj -scheme Litter -configuration Debug -destination 'generic/platform=iOS Simulator' build ```