# Osx Review

> Use when preparing mobile/desktop apps for App Store submission, before final release, or when user mentions App Store, production readiness, shipping, or needs comprehensive quality review for distribution

- **Type:** Skill
- **Install:** `agentstack add skill-boltzmannentropy-osxskills-osx-review`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [BoltzmannEntropy](https://agentstack.voostack.com/s/boltzmannentropy)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [BoltzmannEntropy](https://github.com/BoltzmannEntropy)
- **Source:** https://github.com/BoltzmannEntropy/OSXSkills/tree/main/skills/osx-review
- **Website:** https://qneura.ai/apps.html

## Install

```sh
agentstack add skill-boltzmannentropy-osxskills-osx-review
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.

```dot
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](https://github.com/BoltzmannEntropy)
- **Source:** [BoltzmannEntropy/OSXSkills](https://github.com/BoltzmannEntropy/OSXSkills)
- **License:** MIT
- **Homepage:** https://qneura.ai/apps.html

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-boltzmannentropy-osxskills-osx-review
- Seller: https://agentstack.voostack.com/s/boltzmannentropy
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.