# Osx Compliance

> Use when auditing Apple-platform app projects for release infrastructure and distribution compliance. Covers macOS DMG readiness and iOS/iPad App Store Connect release gates via companion checks.

- **Type:** Skill
- **Install:** `agentstack add skill-boltzmannentropy-osxskills-osx-compliance`
- **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-compliance
- **Website:** https://qneura.ai/apps.html

## Install

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

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

## About

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

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

### Step 2: Audit Each Project

For each project, check:

```bash
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:

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

```dart
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

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

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