Osx Compliance

Apple Platform Compliance Check

Overview

This skill audits Apple-platform app projects in the workspace for release infrastructure, versioning, publication hygiene, website/download integrity, model/documentation parity, and distribution blockers.

Primary focus:

• macOS desktop distribution (.dmg) infrastructure
• iOS/iPad distribution (.ipa + App Store Connect/TestFlight) preflight delegation

When this skill is applied, enforce the same baseline on both existing projects and new projects. The baseline includes system-log UX plus the MimikaCODE production surfaces defined in this file.

Related Skills:

• For in-depth code review before App Store submission, see osx-review/SKILL.md.
• For iOS/iPad upload/submission checks, see osx-ios/SKILL.md.

When to Use

• Before releasing a new version of any macOS, iOS, or iPad app
• When setting up a new macOS app project
• Periodic compliance audits across all projects
• After major infrastructure changes to verify consistency

iOS/iPad Companion Gate

If a project contains an iOS target, this skill MUST require a passed osx-ios preflight:

bash ./skills/osx-ios/scripts/check_ios_dist.sh --app-root <APP_ROOT>

Treat any FAIL result as release-blocking before TestFlight/App Store actions.

Project Discovery

All macOS app projects follow this structure:

<workspace>/
├── <AppName>PRJ/
│   ├── <AppName>CODE/           # Primary source location
│   │   ├── flutter_app/         # Flutter app (if nested)
│   │   ├── backend/             # Backend code
│   │   ├── scripts/             # Build scripts
│   │   └── ...
│   └── <AppName>WEB/            # Website repository

The skill automatically discovers all *PRJ directories in the workspace.

Compliance Checklist

1. Required Files

2. Build Script Features

The build_dmg.sh script MUST include:

3. Version Sources

Projects MUST have at least one version source:

4. Control Scripts (bin/)

5. Window-Close Backend Shutdown UX (Release Blocker)

Desktop apps with bundled local backends MUST shut down the backend when the user closes the app window.

6. GitHub Release + Website Sync (Release Blocker)

Every DMG release must produce a real, populated GitHub release and matching website links.

7. Documentation and Model-Catalog Parity (Release Blocker)

8. Clean-Machine First-Run Validation (Release Blocker)

9. MimikaCODE Production UX Baseline (Release Blocker)

Apply these checks to both existing apps and newly created apps.

Audit Procedure

Step 1: Discover Projects

# Find all PRJ directories in workspace
ls -d <workspace>/*PRJ 2>/dev/null

Step 2: Audit Each Project

For each project, check:

PROJECT_DIR="<path_to_CODE_directory>"

# Required files
[ -f "$PROJECT_DIR/scripts/build_dmg.sh" ] || [ -f "$PROJECT_DIR/scripts/build-dmg.sh" ]
[ -f "$PROJECT_DIR/RELEASE_NOTES.md" ]
[ -f "$PROJECT_DIR/LICENSE" ]
[ -f "$PROJECT_DIR/BINARY-LICENSE.txt" ]
[ -f "$PROJECT_DIR/LICENSE.md" ]
[ -f "$PROJECT_DIR/README.md" ]
[ -f "$PROJECT_DIR/install.sh" ]
[ -f "$PROJECT_DIR/issues.sh" ]
[ -f "$PROJECT_DIR/scripts/release.sh" ]

# Build script features (if script exists)
BUILD_SCRIPT="$PROJECT_DIR/scripts/build_dmg.sh"
grep -q 'shasum' "$BUILD_SCRIPT"           # SHA256
grep -qE 'read_version|VERSION.*pubspec' "$BUILD_SCRIPT"  # Auto version
grep -q 'create-dmg' "$BUILD_SCRIPT"       # create-dmg
grep -q 'hdiutil' "$BUILD_SCRIPT"          # hdiutil fallback
grep -qE 'LICENSE|BINARY-LICENSE' "$BUILD_SCRIPT"  # License embedding
grep -q 'RELEASE_NOTES' "$BUILD_SCRIPT"    # Release notes copy

# Release script checks
RELEASE_SCRIPT="$PROJECT_DIR/scripts/release.sh"
grep -q 'gh release create' "$RELEASE_SCRIPT"
grep -q 'gh release upload' "$RELEASE_SCRIPT"
grep -qE 'source\\.zip|RELEASE_NOTES' "$RELEASE_SCRIPT"

# Window-close backend shutdown UX (Flutter desktop apps with local backend)
MAIN_DART="$PROJECT_DIR/flutter_app/lib/main.dart"
if [ -f "$MAIN_DART" ] && [ -d "$PROJECT_DIR/backend" ]; then
  grep -qE 'onExitRequested|didRequestAppExit|WindowListener' "$MAIN_DART"
  grep -qE 'stopBackend|stop_server|shutdown_backend' "$MAIN_DART"
  grep -qE 'Stopping Server|Stopping backend' "$MAIN_DART"
fi

# MimikaCODE production UX baseline checks
UI_DIR="$PROJECT_DIR/flutter_app/lib"
if [ -d "$UI_DIR" ]; then
  rg -n 'Job Queue|queued|processing|paused|cancelling|completed|failed|cancelled|queue_position|pause|resume|cancel|delete' "$UI_DIR"
  rg -n 'Job History|generation history|created_at|status|processed_chunks|total_chunks|timing_metrics|output_path|audio_url|video_url' "$UI_DIR"
  rg -n 'Models|model path|download status|disk usage' "$UI_DIR"
  rg -n 'Settings|System Folders|Application Support|Logs|Output Folder' "$UI_DIR"
  rg -n 'Jobs History|History|Playback|Play|VideoPlayer|video_url|audio_url|Save|Download' "$UI_DIR"
  rg -n 'job_created|job_update|job_completed|job_failed|job_cancelled|WebSocket' "$UI_DIR"
  rg -n 'Output Path|Full Path|Reveal in Finder|Open Folder' "$UI_DIR"
fi

# Website direct-download link checks (if website repo exists)
PROJECT_PARENT="$(dirname "$PROJECT_DIR")"
PRJ_NAME="$(basename "$PROJECT_PARENT")"
APP_PREFIX="${PRJ_NAME%PRJ}"
WEBSITE_DIR="$PROJECT_PARENT/${APP_PREFIX}WEB"
if [ -d "$WEBSITE_DIR" ]; then
  rg -n '/releases/download/.+\\.dmg' "$WEBSITE_DIR"/*.html
fi

Step 3: Generate Report

Output format:

# macOS App Compliance Report

**Generated:** YYYY-MM-DD HH:MM:SS
**Projects Audited:** N

## Summary

| Project | Status | Issues |
|---------|--------|--------|
| AppName | PASS/FAIL | N issues |
| ... | ... | ... |

## Detailed Results

### Project: <AppName>

**Path:** `<path>`
**Status:** PASS/FAIL

#### Required Files
- [x] scripts/build_dmg.sh
- [ ] RELEASE_NOTES.md (MISSING)
- ...

#### Build Script Features
- [x] SHA256 generation
- [ ] Auto version extraction (MISSING)
- ...

#### Window-Close Backend Shutdown UX
- [x] Exit interception implemented
- [x] Backend stop invoked during close
- [x] Stopping dialog shown during close
- [ ] No orphan backend validation documented (MISSING)

#### GitHub Release + Website Sync
- [x] release.sh automates release upload
- [ ] Release assets incomplete (MISSING SOURCE ZIP SHA)
- [ ] Website download button points to non-DMG URL (MISSING)

#### Documentation and Model-Catalog Parity
- [x] README has Supported Models section
- [ ] Website model table missing variants (MISSING)
- [ ] Pregenerated sample index incomplete (MISSING)

#### MimikaCODE Production UX Baseline
- [x] Job Queue implemented with live status tracking
- [ ] Job queue controls incomplete (MISSING PAUSE/RESUME/CANCEL/DELETE OR CANCELLING/CANCELLED STATE)
- [ ] Job history metadata persistence incomplete (MISSING CHUNK/TIMING/OUTPUT URL FIELDS)
- [ ] Models page missing disk-usage view (MISSING)
- [ ] Settings missing system-folders display (MISSING)
- [ ] Jobs history page missing audio/video playback or save/download actions (MISSING)
- [ ] WebSocket live queue updates missing (MISSING JOB_CREATED/JOB_UPDATE/JOB_COMPLETED/JOB_FAILED/JOB_CANCELLED)
- [ ] Full output path not shown in result cards (MISSING)

#### Issues Found
1. Missing RELEASE_NOTES.md
2. Build script lacks auto version extraction

#### Recommended Fixes
- Create RELEASE_NOTES.md using template
- Add version extraction to build script

Fix Templates

Flutter Window-Close Backend Shutdown Pattern

For Flutter desktop apps with a bundled backend, add an exit-request hook that blocks immediate app termination, shows a stopping dialog, stops backend, then exits:

AppLifecycleListener? _appLifecycleListener;
bool _allowImmediateExit = false;
bool _isShuttingDown = false;

@override
void initState() {
  super.initState();
  _appLifecycleListener = AppLifecycleListener(
    onExitRequested: _handleExitRequested,
  );
}

Future<AppExitResponse> _handleExitRequested() async {
  if (_allowImmediateExit) return AppExitResponse.exit;
  if (_isShuttingDown) return AppExitResponse.cancel;
  _isShuttingDown = true;
  _showStoppingDialog();
  await backendService.stopBackend();
  _allowImmediateExit = true;
  await SystemNavigator.pop();
  return AppExitResponse.cancel;
}

Also add a smoke test step:

• Launch app from /Applications
• Close window
• Confirm stopping dialog appears
• Confirm backend process/port is gone (lsof -iTCP:<port> -sTCP:LISTEN)

RELEASE_NOTES.md Template

# <AppName> v1.0.0 Release Notes

**Release Date:** <Month> <Year>

## Overview

<AppName> v1.0.0 is the initial release of <brief description>.

## Features

### <Category 1>
- **Feature**: Description

### <Category 2>
- **Feature**: Description

## Technical Details

- **Version**: 1.0.0 (build 1)
- **Platform**: macOS (Apple Silicon and Intel)
- **Framework**: Flutter 3.x
- **Minimum macOS**: 12.0 (Monterey)

## Installation

1. Download `<AppName>-1.0.0-macos.dmg`
2. Open the DMG and drag <AppName> to Applications
3. On first launch, right-click and select "Open" (Gatekeeper bypass)

## Unsigned DMG (Apple Gatekeeper)

As of <Month DD, YYYY>, the <AppName> DMG is not yet signed/notarized by Apple.
macOS may block first launch until you explicitly allow it in security settings.

1. Open the DMG and drag <AppName>.app to Applications.
2. In Applications, right-click <AppName>.app and select Open.
3. Click Open in the warning dialog.
4. If macOS still blocks launch, go to: System Settings -> Privacy & Security -> Open Anyway (for <AppName>), then confirm with password/Touch ID.
5. On first launch, wait for the bundled backend to start. A startup-log screen for a few seconds is expected.
6. On first use, click Download for any required model in the in-app model card.

## Checksums

SHA256 checksums are provided in `<AppName>-1.0.0-macos.dmg.sha256`

## Known Issues

- First launch requires Gatekeeper bypass

## License

- Source code: Business Source License 1.1 (`LICENSE`)
- Binary distribution: Binary Distribution License (`BINARY-LICENSE.txt`)

---

For bug reports: <contact_email>

LICENSE.md Template

# <AppName> Licensing Overview

Last updated: <Month> <Year>

## Summary

<AppName> is source-available under a BSL-style license. Source code use is allowed, while the official binary distribution has stricter terms.

## Source Code License (BSL 1.1)

- **License:** Business Source License 1.1
- **Scope:** Source code only
- **File:** `LICENSE`

## Binary Distribution License

- **License:** Binary Distribution License (EULA)
- **Scope:** DMG/app bundles and compiled binaries
- **File:** `BINARY-LICENSE.txt`
- **Key restriction:** No commercial use or redistribution

## What You Can Do

- Clone and modify the source code
- Build binaries for personal or internal use
- Use the source code as permitted by BSL parameters

## What You Cannot Do

- Sell or redistribute the official binary distribution
- Use the official binary for commercial purposes without license

## Need Commercial Rights?

Contact <contact_email> for commercial licensing.

Build Script Version Extraction

Add to build script after APP_NAME definition:

# Auto-extract version from pubspec.yaml if not provided
read_version_from_pubspec() {
    local pubspec="$ROOT_DIR/flutter_app/pubspec.yaml"
    [ -f "$pubspec" ] || pubspec="$ROOT_DIR/pubspec.yaml"
    if [ -f "$pubspec" ]; then
        grep '^version:' "$pubspec" | head -1 | cut -d'+' -f1 | cut -d':' -f2 | xargs
    fi
}

VERSION="${1:-$(read_version_from_pubspec)}"
if [ -z "$VERSION" ]; then
    VERSION="1.0.0"
fi

Build Script SHA256 Generation

Add after DMG creation:

# Generate SHA256 checksum
info "Generating SHA256 checksum..."
cd "$DIST_DIR"
shasum -a 256 "$DMG_NAME" > "$DMG_NAME.sha256"
SHA256=$(awk '{print $1}' "$DMG_NAME.sha256")
ok "SHA256: $SHA256"

Build Script Release Notes Copy

Add after SHA256 generation:

# Copy release notes if present
RELEASE_NOTES_SRC="$ROOT_DIR/RELEASE_NOTES.md"
RELEASE_NOTES_NAME="${APP_NAME}-${VERSION}-RELEASE_NOTES.md"
if [ -f "$RELEASE_NOTES_SRC" ]; then
    cp "$RELEASE_NOTES_SRC" "$DIST_DIR/$RELEASE_NOTES_NAME"
    shasum -a 256 "$RELEASE_NOTES_NAME" > "$RELEASE_NOTES_NAME.sha256"
    ok "Release notes copied"
fi

Release Script GitHub Publish Pattern

scripts/release.sh should create or update the release and upload all required assets every time:

TAG="v$VERSION"
TITLE="$APP_NAME $VERSION"
NOTES_FILE="$ROOT_DIR/RELEASE_NOTES.md"

DMG_PATH="$DIST_DIR/${APP_NAME}-${VERSION}-arm64.dmg"
DMG_SHA_PATH="$DMG_PATH.sha256"
SRC_ZIP_PATH="$DIST_DIR/${APP_NAME}-${VERSION}-source.zip"
SRC_SHA_PATH="$SRC_ZIP_PATH.sha256"
RN_PATH="$DIST_DIR/${APP_NAME}-${VERSION}-RELEASE_NOTES.md"
RN_SHA_PATH="$RN_PATH.sha256"

if ! gh release view "$TAG" >/dev/null 2>&1; then
  gh release create "$TAG" --title "$TITLE" --notes-file "$NOTES_FILE" --latest
else
  gh release edit "$TAG" --title "$TITLE" --notes-file "$NOTES_FILE"
fi

gh release upload "$TAG" \
  "$DMG_PATH" "$DMG_SHA_PATH" \
  "$SRC_ZIP_PATH" "$SRC_SHA_PATH" \
  "$RN_PATH" "$RN_SHA_PATH" \
  --clobber

Minimum publish rule: release is FAIL if the tag exists but assets are empty.

Build Script License Embedding

Add before DMG staging:

# Embed license files in app bundle
RESOURCES_DIR="$APP_PATH/Contents/Resources"
[ -f "$ROOT_DIR/LICENSE" ] && cp "$ROOT_DIR/LICENSE" "$RESOURCES_DIR/"
[ -f "$ROOT_DIR/BINARY-LICENSE.txt" ] && cp "$ROOT_DIR/BINARY-LICENSE.txt" "$RESOURCES_DIR/"

# Copy to DMG root
[ -f "$ROOT_DIR/LICENSE" ] && cp "$ROOT_DIR/LICENSE" "$DMG_STAGE/"
[ -f "$ROOT_DIR/BINARY-LICENSE.txt" ] && cp "$ROOT_DIR/BINARY-LICENSE.txt" "$DMG_STAGE/"

Workflow

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

    "User invokes skill" -> "Discover all PRJ projects";
    "Discover all PRJ projects" -> "Audit each project";
    "Audit each project" -> "Check required files";
    "Check required files" -> "Check build script features";
    "Check build script features" -> "Check version sources";
    "Check version sources" -> "Generate compliance report";
    "Generate compliance report" -> "Ask: Fix issues?";
    "Ask: Fix issues?" -> "Apply fixes" [label="Yes"];
    "Ask: Fix issues?" -> "Done" [label="No"];
    "Apply fixes" -> "Re-audit to verify";
    "Re-audit to verify" -> "Done";
}

User Interaction

After generating the report, ask the user:

1. View detailed report? - Show full compliance details
2. Fix all issues automatically? - Apply all fixes using templates
3. Fix specific projects? - Select which projects to fix
4. Skip fixes? - Just report, no changes

Reference Implementation Pattern

A comprehensive build_dmg.sh for Python-bundled macOS apps should include:

• ~500+ lines of production-tested bash
• Mach-O binary patching for portable Python bundling
• Multi-pass dependency vendoring for transitive dylib dependencies
• MLX/PyTorch pruning options for smaller Apple Silicon bundles
• Backend launcher with proper environment setup
• Fallback from create-dmg to hdiutil
• SHA256 hash generation for all artifacts
• Source archive via git

See the DMG Creation section in the main README for complete implementation details.

Cross-Reference

After running this compliance check, consider running osx-review skill for:

• Crash prevention analysis
• Resource management review
• Security audit
• Platform compliance (App Store specific)
• MCP integration verification
• Product information completeness

The compliance check ensures infrastructure is in place; the code review ensures code quality meets App Store standards.