If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/mas-cli/mas shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 2d ago
• 2 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 98% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live mas-cli/mas repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mas-cli/mas.

What it runs against: a local clone of mas-cli/mas — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in mas-cli/mas | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mas-cli/mas. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mas-cli/mas.git
#   cd mas
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of mas-cli/mas and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mas-cli/mas(\\.git)?\\b" \\
  && ok "origin remote is mas-cli/mas" \\
  || miss "origin remote is not mas-cli/mas (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Sources/mas/Commands/MAS.swift" \\
  && ok "Sources/mas/Commands/MAS.swift" \\
  || miss "missing critical file: Sources/mas/Commands/MAS.swift"
test -f "Sources/mas/AppStore/AppStoreAction.swift" \\
  && ok "Sources/mas/AppStore/AppStoreAction.swift" \\
  || miss "missing critical file: Sources/mas/AppStore/AppStoreAction.swift"
test -f "Sources/mas/Models/MASError.swift" \\
  && ok "Sources/mas/Models/MASError.swift" \\
  || miss "missing critical file: Sources/mas/Models/MASError.swift"
test -f "Package.swift" \\
  && ok "Package.swift" \\
  || miss "missing critical file: Package.swift"
test -f "Sources/PrivateFrameworks/include/CommerceKit/CommerceKit.h" \\
  && ok "Sources/PrivateFrameworks/include/CommerceKit/CommerceKit.h" \\
  || miss "missing critical file: Sources/PrivateFrameworks/include/CommerceKit/CommerceKit.h"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/mas-cli/mas"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

mas is a command-line interface for the macOS App Store that enables scripting and automation of app installations, purchases, and management. It wraps the private macOS App Store frameworks (CommerceKit) to programmatically control what would normally require the GUI App Store app, written primarily in Swift 6.2 and supporting macOS 13+. Single Swift Package structure (Package.swift) with Sources/PrivateFrameworks containing C bindings to Apple's private frameworks. The codebase is a monolithic CLI tool using command-pattern routing; Scripts/ directory contains shell orchestration for build, test, lint, and release workflows. Plugins/MASBuildToolPlugin provides Xcode integration via Swift Package Plugins.

DevOps engineers, system administrators, and Mac automation specialists who need to automate App Store app deployments across fleets of Macs, often as part of MDM (Mobile Device Management) workflows or CI/CD pipelines that manage software distribution.

Production-ready and actively maintained. The project has proper CI/CD (GitHub Actions workflows in .github/workflows/), uses Swift 6.2 with enforced linting (.swiftlint.yml, .swiftformat), and maintains a comprehensive build/test/release pipeline. Regular dependency updates via Dependabot and consistent release cadence indicate active stewardship.

Low-to-moderate risk: the codebase depends on private Apple frameworks (PrivateFrameworks/) which are undocumented and can break between macOS versions—this is the primary fragility. The project is relatively small (208KB Swift code) with a focused maintainer group listed in CODEOWNERS, reducing truck-factor risk. Monitor .swift-version (5.9+) and .xcode-version constraints closely when updating dependencies.

The project actively tracks Swift version compatibility and maintains CI health via workflows in .github/workflows/ (build-test.yaml, tag-pushed.yaml, release-published.yaml). Dependabot automation handles dependency updates. The repository has standardized on Swift 6.2 and enforces modern tooling via .swiftlint.yml and .swiftformat configuration.

git clone https://github.com/mas-cli/mas.git && cd mas && ./Scripts/bootstrap && ./Scripts/build. Requires Xcode and Homebrew (see Brewfile for pinned dependencies). Use ./Scripts/test to run the test suite and ./Scripts/lint to validate code style.

Daily commands: For development: ./Scripts/build produces a binary at .build/release/mas. For testing: ./Scripts/test. For formatting: ./Scripts/format. For linting: ./Scripts/lint. The Scripts/mas wrapper script handles local invocation during development.

• Sources/mas/Commands/MAS.swift — Main entry point defining all CLI commands using Swift Package Manager's Argument Parser; every contributor must understand the command structure
• Sources/mas/AppStore/AppStoreAction.swift — Core business logic for App Store interactions (search, install, update); orchestrates private framework calls
• Sources/mas/Models/MASError.swift — Error handling strategy for the entire CLI; defines error types and user-facing messages
• Package.swift — Project manifest defining Swift version (6.2), dependencies, and build configuration for macOS 13+
• Sources/PrivateFrameworks/include/CommerceKit/CommerceKit.h — Private Apple framework headers for purchase and download operations; critical bridging layer to macOS App Store
• Sources/mas/Commands/MAS.Install.swift — Install command implementation showing pattern for async operation handling and download orchestration
• .github/workflows/build-test.yaml — CI/CD pipeline for build, test, and lint; defines minimum macOS version and Swift version requirements

• MAS.swift (Command Router) — undefined

Add a new CLI command

1. Create new command file following pattern: Sources/mas/Commands/MAS.YourCommand.swift with struct conforming to ParsableCommand (Sources/mas/Commands/MAS.YourCommand.swift)
2. Add @CommandGroup entry in Sources/mas/Commands/MAS.swift's subcommands array (Sources/mas/Commands/MAS.swift)
3. Implement run() method; use AppStoreAction async functions or direct private framework calls (Sources/mas/AppStore/AppStoreAction.swift)
4. Define output model if needed and add to Sources/mas/Models/ directory (Sources/mas/Models/YourModel.swift)

Add a new App Store operation

1. Add async func to AppStoreAction class in Sources/mas/AppStore/AppStoreAction.swift (Sources/mas/AppStore/AppStoreAction.swift)
2. Use CommerceKit or StoreFoundation private framework APIs via bridging headers (Sources/PrivateFrameworks/include/CommerceKit/CommerceKit.h)
3. Return Codable model (CatalogApp, InstalledApp, etc.) or throw MASError for failures (Sources/mas/Models/MASError.swift)
4. Call new operation from command run() method in Sources/mas/Commands/ (Sources/mas/Commands/MAS.swift)

Add reusable command-line option group

1. Create new struct in Sources/mas/Commands/OptionGroups/ conforming to ParsableArguments (Sources/mas/Commands/OptionGroups/YourOptionGroup.swift)
2. Define @Option and @Flag properties matching desired CLI flags/arguments (Sources/mas/Commands/OptionGroups/YourOptionGroup.swift)
3. Embed OptionGroup as property in command struct (via @OptionGroup wrapper) (Sources/mas/Commands/MAS.YourCommand.swift)

• Swift 6.2 with Argument Parser — Type-safe, native macOS CLI framework; compile-time validation of command structure and flags
• Private CommerceKit & StoreFoundation frameworks — Only documented way to programmatically trigger App Store purchases and downloads on macOS; reverse-engineered headers maintained in repo
• Async/await — Native Swift concurrency for long-running operations (downloads, API calls) without callback hell
• Codable for API models — Type-safe JSON decoding from ITunes Search API; automatic validation at decode time
• Swift Package Manager — Standard macOS Swift build tool; easier dependency management than CocoaPods for CLI

• Use undocumented Apple private frameworks (CommerceKit, StoreFoundation)

  • Why: No public API exists for App Store operations; private frameworks are the only way to achieve the tool's goal
  • Consequence: Brittle to macOS updates; requires maintenance when Apple changes private APIs; potential for app rejection if masquerading as official tool

• Synchronous CLI blocking on async operations

  • Why: Standard CLI UX; user runs mas install X and waits for completion
  • Consequence: Blocks shell; no background daemon mode; tight coupling between command lifetime and download lifecycle

• No local database or cache of App Store catalog

  • Why: Keeps tool simple and stateless; always queries ITunes API for fresh data
  • Consequence: Higher API call latency; potential rate limiting; no offline mode

• macOS 13+ minimum version requirement

  • Why: Aligns with Swift 6.2 availability and modern async/await support
  • Consequence: Excludes older Mac users; simplifies deployment but narrows audience

• Does not provide a GUI (command-line only)
• Does not handle paid app purchases with payment credentials (requires existing Apple ID sign-in via System Preferences)
• Does not work on non-macOS systems (App Store is macOS/iOS only)
• Does not cache App Store metadata persistently
• Does not support real-time app update notifications; requires periodic polling

Private framework imports (PrivateFrameworks/) are undocumented by Apple and subject to breaking changes on every major macOS release—App Store updates may render mas non-functional until the bindings are reverse-engineered and updated. Requires valid Apple ID credentials at runtime for authentication. macOS version must be 13.0+ (enforced in Package.swift). The build system uses both Swift package manager and shell scripts, so missing Xcode CLT or incorrect Swift version will cause silent build failures—always verify ./Scripts/bootstrap completes without errors.

• Private Framework Reverse Engineering — mas relies entirely on undocumented Apple private frameworks (CommerceKit) exposed via C bindings, requiring developers to understand how to safely call private APIs and adapt when Apple changes internal interfaces.
• Swift Package Manager (SPM) — The build system uses SPM (Package.swift) for dependency management and project organization, making understanding SPM plugins and target configuration essential for extending mas.
• macOS Version Compatibility & Soft Deprecation — mas must support macOS 13+ while handling breaking changes in private frameworks across major OS releases; contributors need to understand how to conditionally compile and test across multiple macOS versions.
• CLI Argument Parsing & Command Routing — The tool implements a command-based interface (install, uninstall, search, etc.) requiring understanding of argument parsing patterns and subcommand dispatch in Swift CLIs.
• C-to-Swift FFI (Foreign Function Interface) — The PrivateFrameworks bindings use C to interface with Objective-C runtime and private frameworks; understanding Swift/C interop is critical for debugging or extending API access.
• GitHub Actions CI/CD Pipelines — The project relies on GitHub Actions for multi-stage builds (build, test, lint, release); understanding workflow syntax and Xcode runner configuration is needed for improving the pipeline.
• macOS App Notarization & Code Signing — Released binaries must be notarized by Apple and code-signed; the release workflow (release-published.yaml) likely handles this, requiring understanding of notary tools and signing certificates for distribution.

• mas-cli/homebrew-tap — Official Homebrew tap distribution channel for mas, ensures installation via brew install mas-cli/tap/mas for macOS 13+ users
• Homebrew/homebrew-core — Primary package distribution for mas via brew install mas; the repo is packaged here for broader macOS compatibility (14+)
• apple-oss-distributions/BOM — Apple's Bill of Materials tools source—understanding Xcode's internal frameworks helps reverse-engineer private API bindings used by mas
• Homebrew/homebrew-cask — Parallel ecosystem for distributing binary macOS applications; context for understanding how mas fits into Mac software distribution workflows
• mas-cli/mas-cli.github.io — Documentation and landing page site for the mas project; companion repo for user-facing materials and guides

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for CommerceKit and StoreFoundation private framework bindings

The repo heavily depends on private Apple frameworks (CommerceKit, StoreFoundation) with C bindings in Sources/PrivateFrameworks/, but there are no visible integration tests validating these bindings work correctly. This is critical since the entire app functionality depends on these private APIs. New contributors can create tests that verify the framework headers are correctly bridged and callable from Swift.

• [ ] Create Tests/PrivateFrameworksTests/ directory structure
• [ ] Add test cases in Tests/PrivateFrameworksTests/CommerceKitBindingTests.swift to verify CKDownloadQueue, CKPurchaseController initialization
• [ ] Add test cases in Tests/PrivateFrameworksTests/StoreFoundationBindingTests.swift to verify ISStoreAccount, SSDownload struct accessibility
• [ ] Update .github/workflows/build-test.yaml to ensure these tests run in CI (if not already included)
• [ ] Document expected behavior in CONTRIBUTING.md for private framework testing

Create Swift Package plugin documentation and examples for MASBuildToolPlugin

The repo contains Plugins/MASBuildToolPlugin/MASBuildToolPlugin.swift but there's no documentation explaining what this build plugin does, why it exists, or how contributors should modify it. This is a barrier to new contributors understanding the build system. Adding documentation will help maintainers review plugin-related PRs more efficiently.

• [ ] Create PLUGINS.md documenting the purpose of MASBuildToolPlugin
• [ ] Document what the plugin does in the build lifecycle (prebuild steps, code generation, etc.)
• [ ] Add inline code comments to Plugins/MASBuildToolPlugin/MASBuildToolPlugin.swift explaining the implementation
• [ ] Reference PLUGINS.md from CONTRIBUTING.md
• [ ] Add example usage or output to README.md if the plugin affects user-facing behavior

Add macOS version compatibility tests for supported versions (macOS 13+)

The README specifies 'Supported OS: macOS 13+' but there's no visible CI workflow testing against multiple macOS versions (13, 14, 15, etc.). Since the app uses private frameworks that may change across macOS releases, testing across supported versions is critical. This PR would add a GitHub Actions matrix workflow to catch regressions.

• [ ] Create or update .github/workflows/build-test.yaml to include macOS version matrix (13, 14, 15)
• [ ] Test build and unit tests against each macOS version using macos-13-latest, macos-14-latest, macos-15-latest runners
• [ ] Document in CONTRIBUTING.md which macOS versions are tested in CI
• [ ] Ensure .swift-version and .xcode-version are pinned versions that work across all supported macOS versions
• [ ] Add badge to README.md showing tested macOS versions (similar to language/license badges)

• Add comprehensive test coverage for PrivateFrameworks C bindings—currently there are likely no unit tests for the lower-level App Store API wrapping code, which is high-risk for regressions.
• Improve documentation in Sources/ with inline examples of how to call each CLI command programmatically; junior contributors can infer command structure from actual usage and add doc comments.
• Create shell completion generators (bash/zsh/_mas) and document installation—many CLI tools lack this quality-of-life feature that would benefit power users.

The mas-cli project demonstrates a reasonable security posture with established security policies and vulnerability reporting mechanisms. However, the direct dependency on Apple's private frameworks presents a significant architectural risk that should be addressed. The inability to fully assess dependency vulnerabilities due to missing Package.resolved details prevents a complete security evaluation. Key recommendations include: (1) auditing and minimizing private API usage, (2) implementing comprehensive input validation and security documentation, (3) auditing shell scripts for credential exposure, and (4) enhancing supply chain transparency through SBOM generation and automated dependency scanning. The project would benefit from more explicit security hardening documentation and expanded automated security testing in CI/CD pipelines.

• High · Use of Private/Undocumented Apple Frameworks — Sources/PrivateFrameworks/include/CommerceKit, Sources/PrivateFrameworks/include/StoreFoundation. The codebase directly interfaces with Apple's private frameworks (CommerceKit, StoreFoundation) via header files and Objective-C bridging. These frameworks are not part of the public API and are subject to change without notice. This creates maintenance risks and potential security issues if Apple modifies internal implementations. Additionally, Apple's App Store guidelines may prohibit or restrict the use of private APIs. Fix: Audit the use of private frameworks and migrate to public APIs where possible. If private API usage is necessary, document the dependency and establish a process to monitor for Apple framework changes. Consider implementing fallback mechanisms for API changes.
• Medium · Incomplete Package.resolved Analysis — Package.resolved. The Package.resolved file (Swift Package Manager dependencies) was not provided in the analysis context. This prevents verification of dependency versions, known vulnerabilities in transitive dependencies, and validation of dependency integrity. Without this information, potential supply chain vulnerabilities cannot be assessed. Fix: Provide the complete Package.resolved file for dependency vulnerability scanning. Implement automated dependency checking in CI/CD pipeline using tools like 'swift package describe' and OWASP Dependency-Check adapted for Swift packages.
• Medium · Missing Content Security and Input Validation Documentation — Sources/mas/AppStore/, Sources/mas/Commands/. While the codebase structure suggests command-line interface functionality with app store interactions, there is no visible evidence of explicit input validation, sanitization, or security documentation for handling user inputs and API responses. Given the interaction with AppStore APIs and download functionality, improper handling could lead to injection attacks or unexpected behavior. Fix: Implement and document comprehensive input validation for all user-supplied data. Validate and sanitize API responses before use. Add security documentation detailing how inputs are handled and any constraints applied.
• Medium · Credential Handling in Scripts — Scripts/generate_token, Scripts/release_start, Scripts/setup_workflow_repo. Multiple scripts in the Scripts directory (including 'generate_token', 'release_start', 'setup_workflow_repo') may handle credentials or sensitive tokens. Without reviewing their content, there's risk of hardcoded secrets, insecure credential storage, or improper token handling. Fix: Audit all scripts for hardcoded credentials, API keys, or tokens. Use environment variables or secure credential stores (e.g., GitHub Secrets, Keychain) for sensitive data. Never commit credentials to version control. Implement pre-commit hooks to detect secrets.
• Low · Missing SBOM and Supply Chain Transparency — Repository root. No Software Bill of Materials (SBOM) or comprehensive dependency documentation is visible in the provided file structure. While the project uses Swift Package Manager, explicit SBOM generation and publication would improve supply chain transparency and security vulnerability tracking. Fix: Generate and publish an SBOM (e.g., in SPDX or CycloneDX format) as part of the release process. Integrate SBOM generation into CI/CD pipeline. Document all direct and transitive dependencies with their versions and known vulnerabilities.
• Low · Limited Security Testing Documentation — .github/workflows/codeql.yaml. While GitHub Actions workflows are present (CodeQL, build-test), the specific security testing coverage is not evident. No visible documentation of security testing strategies, threat modeling, or penetration testing procedures. Fix: Document security testing strategy including static analysis coverage, dynamic testing approach, and frequency of security audits. Ensure CodeQL is properly configured with appropriate query suites. Consider adding dependency vulnerability scanning to CI/CD.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.