Osx Review

App Store Readiness Code Review

Overview

Systematic code review process for applications targeting Apple App Store, Google Play, or desktop distribution. Identifies crash risks, security vulnerabilities, resource leaks, and compliance issues that cause rejection or poor user experience.

This skill now includes a mandatory cross-repo consistency pass for macOS app websites + README licensing language before release. This skill also enforces MimikaCODE production UX baselines (system logs, queue/history/models/settings/file-path surfaces) for both existing projects and newly created projects.

Repository Layout (Mandatory in This Workspace)

All macOS app projects must follow this structure under artifacts/code:

• artifacts/code/PRJ/CODE - source code repository
• artifacts/code/PRJ/WEB - static website repository (moved from artifacts/all-web)

For licensing and legal checks, always use these surfaces:

• README surface: CODE/README.md
• Flutter app surface: CODE/flutter_app/ (legal screens + bundled app resources)
• Website surface: WEB/ (index.html, license.html, privacy.html, terms.html, privacy-consent.js)

Do not create or update app sites in artifacts/all-web for these macOS apps.

When to Use

• Before App Store/Play Store submission
• Before any production release
• When user says "ship", "release", "production ready", "App Store"
• After major feature completion
• When reviewing cross-platform apps (Flutter, React Native, etc.)

iOS/iPad Baseline (Current)

For iOS/iPad submissions, enforce these before final sign-off:

• [ ] Run bash ./skills/osx-ios/scripts/check_ios_dist.sh --app-root and resolve all FAIL findings
• [ ] Archive/upload baseline matches current App Store Connect tooling requirements
• [ ] TestFlight constraints checked (tester caps, build age, beta review flow)
• [ ] Screenshot coverage satisfies current iPhone + iPad minimum requirements
• [ ] Privacy manifest and required-reason API declarations validated

Review Categories

Review ALL categories systematically. Do not skip any.

digraph review_flow {
    rankdir=TB;
    node [shape=box];

    "Start Review" -> "1. Crash Prevention";
    "1. Crash Prevention" -> "2. Resource Management";
    "2. Resource Management" -> "3. Network & API";
    "3. Network & API" -> "4. Security";
    "4. Security" -> "5. Data Persistence";
    "5. Data Persistence" -> "6. Platform Compliance";
    "6. Platform Compliance" -> "7. Error Handling";
    "7. Error Handling" -> "8. MCP Integration (macOS)";
    "8. MCP Integration (macOS)" -> "9. Performance";
    "9. Performance" -> "10. Product Information";
    "10. Product Information" -> "Generate Report";
}

Severity Classification

| Severity | Definition | Action | |----------|------------|--------| | Critical | Will cause crashes, data loss, or rejection | Must fix before submission | | High | Likely to cause issues under normal use | Should fix before submission | | Medium | Edge cases, degraded experience | Fix in next release | | Low | Code quality, best practices | Nice to have |

1. Crash Prevention Checklist

Flutter/Dart

• [ ] All async callbacks check mounted before setState()
• [ ] StreamSubscription cancelled in dispose()
• [ ] Timer cancelled in dispose()
• [ ] AnimationController disposed
• [ ] TextEditingController disposed
• [ ] ScrollController disposed
• [ ] FocusNode disposed
• [ ] Null safety: no force unwraps (!) without guaranteed non-null
• [ ] List/Map access with bounds checking or .elementAtOrNull()

Flutter UI Patterns (Reference: flutter-python-fullstack)

• [ ] Theme: Uses ColorScheme.fromSeed() with Material 3
• [ ] Dark mode: Supports ThemeMode.system (respects OS preference)
• [ ] Backend check: Health check on startup with loading/disconnected states
• [ ] Bundled backend autostart: If backend is down and app is bundled, UI attempts backend startup automatically (no manual CLI prerequisite for end users)
• [ ] Startup status UX: UI shows backend startup progress/status (for example: starting/waiting/failed)
• [ ] Exit shutdown hook: App intercepts desktop window-close/exit requests and runs graceful backend shutdown before process exit
• [ ] Shutdown UX: During close, app shows a blocking "Stopping server/backend..." progress dialog until shutdown finishes or timeout path is handled
• [ ] Production messaging: Disconnected-state copy does not instruct end users to run terminal commands
• [ ] Stats polling: Uses Future.doWhile() with mounted guard
• [ ] Status chips: Color-coded (green/orange/red) using withValues(alpha:)
• [ ] Deprecated APIs: No withOpacity() (use withValues(alpha:) instead)
• [ ] ApiService: Centralized HTTP client with typed endpoints
• [ ] System log visibility: App exposes a user-visible system log panel (not only startup status text)
• [ ] System log actions: Users can copy logs and export logs directly from UI controls
• [ ] Footer log console: App includes a footer system-log area that is collapsible and resizable
• [ ] Footer parity: Footer log area also provides copy/export actions without navigating to settings
• [ ] Log export surface: Backend provides a plain-text system log export endpoint (separate from full diagnostics bundle)
• [ ] Job Queue surface: App has a visible job queue with live per-job status (queued, processing, paused, cancelling, completed, failed, cancelled), queue position, and controls (pause, resume, cancel, delete)
• [ ] Persistent Job History: Job history persists across app restarts with metadata (created time, model/engine, status, chunk progress, timing metrics, output path/URLs)
• [ ] Jobs History playback: App has a jobs-history UI page that supports audio/video playback plus save/download and open-in-folder actions for generated outputs
• [ ] Queue event sync: Queue/history UI updates live from websocket events (job_created, job_update, job_completed, job_failed, job_cancelled)
• [ ] File path visibility: Generation results and history rows show full output file paths with an Open Folder/Reveal in Finder action

iOS/Swift

• [ ] No force unwraps (!) on optionals from external data
• [ ] weak self in closures to prevent retain cycles
• [ ] deinit called (add print to verify during testing)
• [ ] No unhandled fatalError() or preconditionFailure()

Android/Kotlin

• [ ] Null checks on Intent extras
• [ ] Activity lifecycle handled (no operations on destroyed activity)
• [ ] Fragment lifecycle handled
• [ ] No !! on nullable external data

Backend/Python

• [ ] All exceptions caught at API boundary
• [ ] No bare except: clauses (catch specific exceptions)
• [ ] Thread safety for shared resources
• [ ] Connection pool limits configured

2. Resource Management Checklist

Memory Leaks

• [ ] Large objects released when not needed
• [ ] Image/media caching bounded
• [ ] Listeners/observers removed
• [ ] Background tasks cancelled on screen exit
• [ ] File handles closed in finally blocks
• [ ] Voice-clone pipelines profiled with Instruments (Allocations + Leaks) for full clone lifecycle (load model -> clone -> teardown)
• [ ] Add standalone clone regression tests using Natasha and Suzan voices to detect runaway memory growth or unreleased buffers

File System

• [ ] Temp files cleaned up
• [ ] File existence checked before read
• [ ] File permissions checked
• [ ] Path sanitization (no ../ injection)
• [ ] Disk space checked before large writes
• [ ] Runtime writes never target .app/Contents/... or mounted .dmg paths
• [ ] Mutable runtime storage uses user-writable locations (~/Library/Application Support/, ~/Library/Caches/, ~/Library/Logs/)

Audio/Video

• [ ] Players disposed when done
• [ ] Audio session properly configured
• [ ] Background audio handled correctly
• [ ] Interruption handling (phone calls)

3. Network & API Checklist

Timeouts

• [ ] All HTTP requests have timeout configured
• [ ] Reasonable timeout values (10-30s for normal, 60-120s for uploads)
• [ ] Timeout errors handled gracefully

Error Handling

• [ ] Network unavailable handled
• [ ] Server errors (5xx) handled
• [ ] Client errors (4xx) handled with user feedback
• [ ] Malformed response handled
• [ ] Empty response handled

Resilience

• [ ] Retry logic with exponential backoff
• [ ] Circuit breaker for failing services
• [ ] Offline mode / cached data fallback
• [ ] Request cancellation on screen exit

Configuration

• [ ] Base URL configurable (not hardcoded localhost)
• [ ] API version handling
• [ ] Certificate pinning (if required)
• [ ] Bundled desktop apps can fully start backend without any external shell command
• [ ] Port-conflict path handled (if port already bound, user gets clear action instead of silent failure)

4. Security Checklist

Input Validation

• [ ] All user input validated
• [ ] Path traversal prevention (../)
• [ ] SQL injection prevention (parameterized queries)
• [ ] XSS prevention (output encoding)
• [ ] File type validation for uploads

Authentication

• [ ] Tokens stored securely (Keychain/Keystore)
• [ ] Token refresh logic
• [ ] Session expiration handling
• [ ] Logout clears all sensitive data

Network Security

• [ ] HTTPS only (no HTTP except localhost)
• [ ] CORS configured properly (not * in production)
• [ ] Sensitive data not logged
• [ ] API keys not in source code

Data Protection

• [ ] Sensitive data encrypted at rest
• [ ] No sensitive data in logs
• [ ] No sensitive data in crash reports
• [ ] Clipboard cleared after paste of sensitive data

5. Data Persistence Checklist

Database

• [ ] Schema migrations for updates
• [ ] Database connection pooling
• [ ] Thread-safe access (locking or connection per thread)
• [ ] Backup/restore capability
• [ ] Corruption recovery
• [ ] Database path resolves to user-writable runtime directory (not app bundle path)

Preferences/Settings

• [ ] Default values for all settings
• [ ] Settings validation on load
• [ ] Settings migration for app updates

Cache

• [ ] Cache size limits
• [ ] Cache expiration
• [ ] Cache invalidation logic
• [ ] Graceful handling of corrupted cache
• [ ] ML/model cache path is app-scoped for bundled builds (avoid accidental reuse of developer/global cache unless explicitly intended)
• [ ] Model-download detection logic honors runtime cache environment variables (HUGGINGFACE_HUB_CACHE / HF_HOME / XDG_CACHE_HOME)

6. Platform Compliance Checklist

Apple App Store

• [ ] Privacy manifest (PrivacyInfo.xcprivacy) present
• [ ] Required-reason API declarations and third-party SDK manifests validated
• [ ] Required device capabilities declared
• [ ] App Transport Security configured
• [ ] No private API usage
• [ ] Proper entitlements configured
• [ ] App icons all sizes present
• [ ] Launch screen configured
• [ ] Build uploaded with current supported Xcode/SDK baseline
• [ ] TestFlight readiness verified (internal/external path + beta review expectations)
• [ ] iPhone and iPad screenshot requirements satisfied for enabled device families

Google Play

• [ ] Target SDK meets requirements
• [ ] Permissions declared and justified
• [ ] Data safety form ready
• [ ] 64-bit support
• [ ] App bundle (not APK)

macOS App Store

• [ ] Sandboxing configured
• [ ] Hardened runtime enabled
• [ ] Notarization ready
• [ ] Entitlements minimal and justified

macOS Distribution

• [ ] DMG builder script present (scripts/build_dmg.sh)
• [ ] DMG includes app bundle, Applications symlink, and background image
• [ ] hdiutil fallback packages the DMG staging directory (not only the .app) so Applications symlink survives fallback builds
• [ ] Code signing for DMG distribution
• [ ] Notarization of DMG for Gatekeeper
• [ ] If DMG is unsigned, release notes + README + website include explicit Gatekeeper bypass steps with concrete date and Open Anyway path
• [ ] Volume name and window layout configured
• [ ] SHA256 hash generated alongside DMG (.dmg.sha256)
• [ ] Version extracted from centralized version file
• [ ] DMG root includes LICENSE (source) and BINARY-LICENSE.txt (binary/EULA)
• [ ] App bundle embeds Contents/Resources/LICENSE and Contents/Resources/BINARY-LICENSE.txt
• [ ] DMG license agreement configured (when supported by the DMG toolchain)
• [ ] Bundled-app smoke test validates GET /api/health, GET /api/pdf/list, and direct GET /pdf/ after launch from /Applications
• [ ] Bundled PDF/runtime assets resolve via app-relative paths (no hardcoded source checkout paths)

Bundled Python Backend (Mandatory for macOS Desktop Distribution)

• [ ] Backend process is launched by the app itself on first run (no terminal dependency for end users)
• [ ] Launch uses bundled Python runtime, not system Python
• [ ] Backend startup path works when app is run from /Applications and does not rely on source checkout paths
• [ ] Backend runtime env config sets app-specific writable paths for logs/data/outputs/cache
• [ ] Backend does not require writing launcher logs into app bundle directories
• [ ] Backend model/cache env vars are set for app-scoped storage (HF_HOME, HUGGINGFACE_HUB_CACHE, TRANSFORMERS_CACHE)
• [ ] Backend health check retries include clear startup status and failure state
• [ ] First-launch UI includes explicit startup/waiting log state while bundled backend warms up
• [ ] Disconnected-state primary action is a user-safe restart flow (for example Restart Server) and avoids shell-command instructions
• [ ] Backend port-conflict path is handled explicitly (detect in-use port, prompt/confirm stop conflicting process, then retry)
• [ ] First-run behavior tested with no existing localhost backend process running
• [ ] Closing the app window must terminate bundled backend child processes (no orphan backend after UI exit)

Project Scripts (Reference: flutter-python-fullstack pattern)

• [ ] Control script (bin/appctl):
• appctl up - Start all services
• appctl down - Stop all services
• appctl status - Show running/stopped with colors
• appctl logs - Tail log files
• appctl clean - Clean logs and temp files
• [ ] Install script (install.sh):
• Check/install dependencies (Homebrew, Flutter, etc.)
• Create virtual environments
• Download required models
• Colored output with status indicators
• [ ] Diagnostic script (issues.sh):
• System info (OS, architecture, disk space)
• Tool versions (Flutter, Python, git)
• Port status checks
• Network/health checks
• Last 50 lines of runtime logs
• Timestamped output file

Release Scripts (Mandatory for All macOS Apps)

Every macOS app MUST have a scripts/release.sh that automates the full release workflow. Manual releases are error-prone and forbidden.

Release Script Requirements

• [ ] Release script (scripts/release.sh) exists and is executable
• [ ] Script extracts version from pubspec.yaml automatically (no hardcoded versions)
• [ ] Script supports --upload flag for GitHub release upload
• [ ] Script supports --sync-website flag for website download link updates
• [ ] Script generates SHA256 checksum alongside DMG
• [ ] Script creates or updates GitHub release for the current tag (never leave tag-only/empty release pages)
• [ ] Script uploads full asset set: DMG + DMG SHA256 + source ZIP + source ZIP SHA256 + release notes + release notes SHA256
• [ ] Script updates website download URLs with new version
• [ ] Script updates website download URLs to direct DMG asset links (not generic release listing pages)
• [ ] Script commits and pushes website changes automatically
• [ ] Script provides clear success/failure output with colored status

Version Advancement Protocol

• [ ] Version follows sema

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: BoltzmannEntropy
• Source: BoltzmannEntropy/OSXSkills
• License: MIT
• Homepage: https://qneura.ai/apps.html

Install and usage instructions live in the source repository linked above.