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 

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

Project Discovery

All macOS app projects follow this structure:

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

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

Compliance Checklist

1. Required Files

| File | Purpose | Required | |------|---------|----------| | scripts/build_dmg.sh or scripts/build-dmg.sh | DMG creation script | YES | | RELEASE_NOTES.md | Release documentation | YES | | LICENSE | Source code license (BSL 1.1) | YES | | BINARY-LICENSE.txt | Binary distribution license | YES | | LICENSE.md | License overview document | YES | | README.md | Project documentation | YES | | install.sh | Installation script | YES | | issues.sh | Diagnostic script | YES | | scripts/release.sh | End-to-end release automation | YES |

2. Build Script Features

The build_dmg.sh script MUST include:

| Feature | Description | Check Pattern | |---------|-------------|---------------| | SHA256 Generation | Checksum for DMG file | shasum -a 256 | | Auto Version Extraction | Read version from pubspec.yaml | read_version.*pubspec\|VERSION.*grep.*pubspec | | create-dmg Support | Pretty DMG with window layout | create-dmg | | hdiutil Fallback | Basic DMG creation fallback | hdiutil create | | License Embedding | Copy LICENSE files to app bundle | LICENSE\|BINARY-LICENSE in script | | Release Notes Copy | Copy RELEASE_NOTES.md to dist/ | RELEASE_NOTES in script | | dist/ Directory | Output directory for artifacts | DIST_DIR\|dist/ |

3. Version Sources

Projects MUST have at least one version source:

| Location | Format | |----------|--------| | flutter_app/pubspec.yaml | version: X.Y.Z+N | | pubspec.yaml (root) | version: X.Y.Z+N | | flutter_app/lib/version.dart | const String appVersion = "X.Y.Z"; | | backend/version.py | VERSION = "X.Y.Z" |

4. Control Scripts (bin/)

| Script | Purpose | |--------|---------| | bin/appctl or bin/ctl | Service control (up/down/status/logs) | | bin/_mcp_server.py | MCP server for Claude integration |

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.

| Requirement | Description | Check Pattern | |-------------|-------------|---------------| | Exit interception | App intercepts window close / app-exit request before terminating | onExitRequested\|didRequestAppExit\|WindowListener | | Shutdown call | Exit path calls backend stop logic | stopBackend\|stop_server\|shutdown_backend | | Stopping dialog/UI | Close path displays visible "Stopping server/backend" progress UI | Stopping Server\|Stopping backend\|stop.*before exit | | No orphan backend | Post-close check confirms backend port/process is gone | lsof -iTCP / process check in smoke test docs |

6. GitHub Release + Website Sync (Release Blocker)

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

| Requirement | Description | Check Pattern | |-------------|-------------|---------------| | Release automation | scripts/release.sh creates/updates GitHub release and uploads assets | gh release create\|gh release upload | | No empty releases | Release page must contain assets (not tag-only) | gh release view --json assets | | Required assets | Release includes DMG, DMG SHA256, source ZIP, source ZIP SHA256, release notes, release notes SHA256 | -arm64.dmg\|source.zip\|RELEASE_NOTES | | Direct DMG links | Website download buttons/nav resolve directly to current DMG asset URL | /releases/download/v.*/.*\\.dmg | | Version alignment | Version badge/text, release tag, and artifact filenames match | v[0-9]+\\.[0-9]+\\.[0-9]+ or project format | | Gatekeeper instructions | If unsigned/not notarized, release notes include explicit launch steps and security path | Unsigned DMG.*Gatekeeper\|Open Anyway |

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

| Requirement | Description | Check Pattern | |-------------|-------------|---------------| | README model table complete | README lists all app-shipped/supported model variants (including quantized aliases/namespaces where applicable) | ## Supported Models | | Website model table complete | Website "Supported Models" mirrors README/app capability set | Supported Models in WEB | | Pregenerated samples indexed | README includes pregenerated example index for shipped demos | pregenerated | | Capability accuracy | Marketing/docs do not claim unsupported capabilities (for example, cloning on non-cloning models) | manual diff vs runtime engines | | First-run guidance present | README/website include first-launch backend warm-up and model-download guidance | startup log\|Download |

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

| Requirement | Description | Check Pattern | |-------------|-------------|---------------| | No stale app collision | Old copies in /Applications removed before smoke testing new DMG | manual check | | No stale model cache assumption | Validate first run with empty app-scoped cache/models | app-specific cache path check | | Backend port conflict handling | App surfaces clear "restart/stop conflicting process" path if port is in use | port in use\|Restart Server | | Bundled PDF serving check | /api/pdf/list and /pdf/ work from bundled build | health smoke test | | Relative resource pathing | Bundled backend uses app-relative/runtime paths, never source checkout paths | no hardcoded repo paths |

9. MimikaCODE Production UX Baseline (Release Blocker)

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

| Requirement | Description | Check Pattern | |-------------|-------------|---------------| | Job Queue UI | Background queue with live status transitions (queued, processing, paused, cancelling, completed, failed, cancelled), queue position, and control actions (pause, resume, cancel, delete) | Job Queue\|queued\|processing\|paused\|cancelling\|completed\|failed\|cancelled\|queue_position\|pause\|resume\|cancel\|delete | | Persistent Job History | Durable history of all jobs with core metadata (timestamps, engine/model, status, chunk progress, timing metrics, output paths/URLs) | Job History\|generation history\|created_at\|status\|processed_chunks\|total_chunks\|timing_metrics\|output_path\|audio_url\|video_url | | Models Page | Dedicated models page shows model path/location, download status, and disk usage | Models\|model path\|download status\|disk usage | | Settings Screen: System Folders + Output Folder | Settings must display system/runtime folders and allow configuring output folder | System Folders\|Application Support\|Logs\|Output Folder | | Jobs History Page + Playback | Dedicated jobs-history page lists previous jobs and supports audio/video playback plus save/download for generated media | Jobs History\|History\|Playback\|Play\|VideoPlayer\|video_url\|audio_url\|Save\|Download | | WebSocket Queue Updates | Queue/history reflects live job events over websocket (job_created, job_update, job_completed, job_failed, job_cancelled) | job_created\|job_update\|job_completed\|job_failed\|job_cancelled\|WebSocket | | Full File Path Display | UI surfaces full output paths and provides open/reveal-folder affordance | Output Path\|Full Path\|Reveal in Finder\|Open Folder |

Audit Procedure

Step 1: Discover Projects

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

Step 2: Audit Each Project

For each project, check:

PROJECT_DIR=""

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

**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 _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: -sTCP:LISTEN)

RELEASE_NOTES.md Template

#  v1.0.0 Release Notes

**Release Date:**  

## Overview

 v1.0.0 is the initial release of .

## Features

### 
- **Feature**: Description

### 
- **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 `-1.0.0-macos.dmg`
2. Open the DMG and drag  to Applications
3. On first launch, right-click and select "Open" (Gatekeeper bypass)

## Unsigned DMG (Apple Gatekeeper)

As of , the  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 .app to Applications.
2. In Applications, right-click .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 ), then confirm with password/Touch ID.
5. On first launch, wait for the bundled backend to start. A startup-log screen for a

…

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