{"owner":"mas-cli","repo":"mas","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Project Guidelines\n\n## Purpose & Scope\n\nThis file is the canonical source of project conventions for humans & agents.\nRead it before making repository changes.\n\n## Minimum Versions\n\n- **Swift:** 6.3\n- **Xcode:** 26.4\n- **macOS:** 13\n\n## Quick Entry Points\n\n- `Scripts/bootstrap`\n- `Scripts/format`\n- `Scripts/lint -AP` (quick) / `Scripts/lint` (includes unused code checks)\n- `Scripts/build` (debug) / `Scripts/build '' -c release` (release)\n- `Scripts/test`\n- `Scripts/package`\n\n## Git Workflow\n\n- `main` is the trunk\n- Branch topics from `main`\n- Before committing (to preserve tokens, agents should skip all of the following\n  steps unless explicitly directed to perform them):\n  1. Add or edit tests for non-trivial changes\n  2. Repeatedly run `Scripts/format` until no modifications are made\n  3. Repeatedly run `Scripts/lint` & fix all violations until no violations are\n     reported\n- **Commit messages:** Follow [commit message conventions](\n    https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html\n  )\n- Tag releases as `vX.Y.Z`\n\n## Content Formatting\n\n- **Newlines:** Unix (i.e. `\\n`)\n- **Indentation:** Tabs (2 characters wide) for all files unless otherwise\n  specified; 2 spaces for YAML; 1 space for Markdown\n- **Max line length:** 120 characters for all files unless otherwise specified\n  (tabs count as 2 characters); 80 for Markdown; unlimited for header, JSON &\n  swiftformat\n- **Unnecessary trailing whitespace:** Remove\n- **File ends:** Single newline\n- **Quoting:** Quote strings only when necessary, preferring the most literal\n  format that works over more interpreted formats; if multiple quote syntaxes\n  are functionally equivalent, prefer the visually lightest, e.g., prefer single\n  quotes over double quotes if they are functionally equivalent\n- **Text**: In documentation, comments, strings, etc.:\n  - **Commas:** Use Oxford commas for lists\n  - **Ampersands:** Prefer `&` to `and` (omit Oxford comma before `&`)\n  - **Exceptions:** `and` should be used in `and/or` & after a comma that\n    separates distinct clauses (but not in a list)\n  - **Quotes**: The enclosing quotations marks of a quote at the end of a\n    sentence (iff the whole sentence isn't a quote) should not enclose the\n    terminal punctuation mark of the encompassing sentence\n  - **Iff**: Use `iff` as `if & only if`\n\n### Markdown Guidelines\n\n- **Style:** GitHub-Flavored Markdown (GFM), ATX headings, backtick-fenced code\n  blocks with language identifier, underscore emphasis, asterisk strong & hyphen\n  bullets\n- **HTML:** Limit to HTML supported by GFM that doesn't have a native GFM\n  equivalent\n\n## Refactoring Rules\n\nUnless absolutely necessary for functionality or fixes, or unless violations of\nstandards are discovered, do not:\n\n- reformat\n- rename\n- reorder\n- respace\n- reword\n- remove comments\n- refactor if it worsens the caller interface\n\nRefactoring should:\n\n- Keep clean abstractions\n- Inline a utility iff it is single-use\n- Replace a utility iff the new version is more correct, performant, and/or\n  simpler than the existing version, in descending order of priority\n\n## Scripting\n\n- Use zsh for scripts (except for shell-specific completion scripts)\n- Zsh scripts must be compatible with all zsh versions starting with the version\n  ([currently 5.9](https://opensource.apple.com/releases/)) bundled with the\n  newest version ([currently 13.5.x](https://opensource.apple.com/releases/))\n  of the oldest macOS major version supported by mas\n  ([currently 13](Package.swift))\n- Use `#!/bin/zsh` shebang (with `-Ndefgku` options, unless any changes to the\n  options are absolutely necessary)\n- Run `. \"${0:A:h}/_setup_script\"` at the start of all development scripts\n- Prefer concision over verbosity\n- If performance is at least almost equivalent or better, prefer in descending\n  order:\n  - zsh expansions\n  - zsh globs\n  - zsh builtins\n  - zsh loops\n  - external commands\n- Make variables local & readonly when possible\n- Use:\n  - `cp -c` instead of `cp`\n  - `trash` instead of `rm`\n\n## Swift\n\nmas is a SwiftPM project that uses Swift Argument Parser to interact with the\ncommand-line.\n\n### Apple Private Frameworks\n\nThe `PrivateFrameworks` SwiftPM target exposes the following Apple private\nframeworks (via Objective-C headers extracted from the DSC) to deploy App Store\napps:\n\n- **CommerceKit:** Controllers\n- **StoreFoundation:** Models\n\nUse private frameworks only when public APIs are insufficient.\n\nNewer Apple private frameworks (e.g., AppStoreDaemon & AppleMediaServices) seem\nto supersede the currently used ones, but the newer ones seem usable only by\ncode with Apple-exclusive entitlements.\n\n### Swift Source Folder Hierarchy\n\nSwift source is organized in subfolders of `Sources/mas`:\n\n- **Commands:** CLI implementation\n- **Models:** Data types & suppliers\n- **Utilities:** Utilities\n\n### Command Implementation Patterns\n\nCommands follow a consistent structure:\n\n- Commands are nested structs within the `MAS` main command\n- Use `@OptionGroup` to compose reusable argument sets from dedicated types\n  that conform to `ParsableArguments`\n- Implement `func run() async { … }` as the main command entry point\n- Use the static `MAS.printer` for all output to ensure consistent formatting\n- Call methods on `AppStoreAction` enum cases (accessible via the `AppStore`\n  typealias) to execute business logic, e.g., `await AppStore.install.apps(…)`\n\n### Style Essentials\n\n- Name most function parameters\n- Capitalize acronym & initialism characters consistently (e.g., `ADAM`, `API`,\n  `HTTPRequest`, `JSON`)\n- Shadow variables if the respective original will no longer be used\n- Strongify weak references instead of evaluating them multiple times\n- Group computed properties below stored properties\n\n### Code Preference Hierarchies\n\nEach subsection contains code preferences in descending order.\n\nWithin this section & all subsections, `X` is a placeholder for any type name.\n\n#### Naming\n\n1. Standardized name\n2. Concise name\n3. Verbose name\n\n#### Concision/Verbosity\n\n1. Concise code, e.g.:\n   - Optional binding shorthand (e.g., `if let x { … }`, not\n     `if let x = x{ … }`)\n2. Verbose code\n\n#### Architecture\n\n1. Composition\n2. Protocol conformance\n3. Class inheritance\n\n#### Typing\n\n1. Inferred type, e.g.:\n   - `var a = [X]()`\n   - `var o = X?.none`\n   - `var c: X { .init() }`\n   - `f(array: .init())`\n   - `f(dictionary: .init())`\n2. Cast type, e.g.:\n   - `var a = [] as [X]`\n   - `var o = nil as X?`\n3. Explicit type, e.g.:\n   - `var a: [X] = .init()`\n   - `var o: X? = nil`\n   - `var c: X { X() }`\n   - `f(array: [])`\n   - `f(dictionary: [:])`\n\n#### Functional\n\n1. Functional\n2. Non-functional\n\n#### Value Inlining/Binding\n\n1. Inlined single-use value\n2. `let` multiple-use value\n3. `var` multiple-use value\n\n#### Code Inlining/Reuse\n\n1. Inlined single-use code (unless inlined code is much more complex)\n2. Computed property\n3. Function\n\n#### Optional Handling\n\n1. Nil-coalescing operator (`??`)\n2. Ternary operator\n3. `Optional.map(_:)` / `Optional.flatMap(_:)`\n4. Single `guard`\n5. `if` / `else` (no `else if`)\n6. `switch`\n7. Multiple `guard`\n8. `if` / `else if`… / `else`\n9. `preconditionFailure(_:file:line:)`\n10. Forced unwrapping (`!` suffix)\n11. `fatalError(_:file:line:)`\n\n#### Throwing\n\n1. Typed throws (`throws(ErrorType)`)\n2. Untyped rethrows (`rethrows`)\n3. Untyped throws (`throws`)\n\n#### Code Reuse\n\n1. Framework/library call\n2. Custom code\n\n#### Constants\n\n1. Global `let`\n2. `enum` `static let`\n3. `struct` `static let`\n4. `class` `static let`\n\n#### Preferred Types\n\n1. Unaliased infrequent tuple/closure\n2. Type-aliased frequent tuple/closure\n3. `enum`\n4. `struct`\n5. `actor`\n6. `final class`\n7. `class`\n\n#### Type Syntax\n\n1. Concision:\n   - Generics: `<T: X>`\n   - Optional: `X?`\n   - Collection: `[X]`\n   - Dictionary: `[X:X]`\n2. Verbosity:\n   - Generics: `where T: X`\n   - Optional: `Optional<X>`\n   - Collection: `Array<X>`\n   - Dictionary: `Dictionary<X, X>`\n\n#### Void Types\n\n1. `()` for void parameter type\n2. `Void` for void return type\n\n#### Closure Syntax\n\n1. Trailing closure\n2. Inline closure\n\n#### Closure Arguments\n\n1. Shorthand argument names (e.g., `$0`) iff one-line closure\n2. Explicit argument names for multi-line closure\n\n#### Functional Arguments\n\n1. KeyPath\n2. Function reference\n3. Closure\n\n#### Strict Memory Safety\n\n1. Memory-safe code (i.e. not `unsafe`)\n2. `unsafe` code iff a memory-safe alternative:\n   - Is not available from frameworks/libraries\n   - Is too difficult to implement properly & performantly\n\n### Testing Requirements\n\n- Add tests for all non-trivial changes (to preserve tokens, agents should not\n  add tests unless explicitly directed to do so)\n- Implement in [Swift Testing](https://github.com/swiftlang/swift-testing)\n- Derive test file paths from source file paths:\n  - replace the `Sources/mas` source path folder prefix with `Tests/MASTests`\n  - prepend `MASTests+` to the source file name\n  - e.g., `Sources/mas/Commands/X.swift` →\n    `Tests/MASTests/Commands/MASTests+X.swift`\n- Use force unwrapping in tests where appropriate\n"},"files":{"AGENTS.md":"# Project Guidelines\n\n## Purpose & Scope\n\nThis file is the canonical source of project conventions for humans & agents.\nRead it before making repository changes.\n\n## Minimum Versions\n\n- **Swift:** 6.3\n- **Xcode:** 26.4\n- **macOS:** 13\n\n## Quick Entry Points\n\n- `Scripts/bootstrap`\n- `Scripts/format`\n- `Scripts/lint -AP` (quick) / `Scripts/lint` (includes unused code checks)\n- `Scripts/build` (debug) / `Scripts/build '' -c release` (release)\n- `Scripts/test`\n- `Scripts/package`\n\n## Git Workflow\n\n- `main` is the trunk\n- Branch topics from `main`\n- Before committing (to preserve tokens, agents should skip all of the following\n  steps unless explicitly directed to perform them):\n  1. Add or edit tests for non-trivial changes\n  2. Repeatedly run `Scripts/format` until no modifications are made\n  3. Repeatedly run `Scripts/lint` & fix all violations until no violations are\n     reported\n- **Commit messages:** Follow [commit message conventions](\n    https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html\n  )\n- Tag releases as `vX.Y.Z`\n\n## Content Formatting\n\n- **Newlines:** Unix (i.e. `\\n`)\n- **Indentation:** Tabs (2 characters wide) for all files unless otherwise\n  specified; 2 spaces for YAML; 1 space for Markdown\n- **Max line length:** 120 characters for all files unless otherwise specified\n  (tabs count as 2 characters); 80 for Markdown; unlimited for header, JSON &\n  swiftformat\n- **Unnecessary trailing whitespace:** Remove\n- **File ends:** Single newline\n- **Quoting:** Quote strings only when necessary, preferring the most literal\n  format that works over more interpreted formats; if multiple quote syntaxes\n  are functionally equivalent, prefer the visually lightest, e.g., prefer single\n  quotes over double quotes if they are functionally equivalent\n- **Text**: In documentation, comments, strings, etc.:\n  - **Commas:** Use Oxford commas for lists\n  - **Ampersands:** Prefer `&` to `and` (omit Oxford comma before `&`)\n  - **Exceptions:** `and` should be used in `and/or` & after a comma that\n    separates distinct clauses (but not in a list)\n  - **Quotes**: The enclosing quotations marks of a quote at the end of a\n    sentence (iff the whole sentence isn't a quote) should not enclose the\n    terminal punctuation mark of the encompassing sentence\n  - **Iff**: Use `iff` as `if & only if`\n\n### Markdown Guidelines\n\n- **Style:** GitHub-Flavored Markdown (GFM), ATX headings, backtick-fenced code\n  blocks with language identifier, underscore emphasis, asterisk strong & hyphen\n  bullets\n- **HTML:** Limit to HTML supported by GFM that doesn't have a native GFM\n  equivalent\n\n## Refactoring Rules\n\nUnless absolutely necessary for functionality or fixes, or unless violations of\nstandards are discovered, do not:\n\n- reformat\n- rename\n- reorder\n- respace\n- reword\n- remove comments\n- refactor if it worsens the caller interface\n\nRefactoring should:\n\n- Keep clean abstractions\n- Inline a utility iff it is single-use\n- Replace a utility iff the new version is more correct, performant, and/or\n  simpler than the existing version, in descending order of priority\n\n## Scripting\n\n- Use zsh for scripts (except for shell-specific completion scripts)\n- Zsh scripts must be compatible with all zsh versions starting with the version\n  ([currently 5.9](https://opensource.apple.com/releases/)) bundled with the\n  newest version ([currently 13.5.x](https://opensource.apple.com/releases/))\n  of the oldest macOS major version supported by mas\n  ([currently 13](Package.swift))\n- Use `#!/bin/zsh` shebang (with `-Ndefgku` options, unless any changes to the\n  options are absolutely necessary)\n- Run `. \"${0:A:h}/_setup_script\"` at the start of all development scripts\n- Prefer concision over verbosity\n- If performance is at least almost equivalent or better, prefer in descending\n  order:\n  - zsh expansions\n  - zsh globs\n  - zsh builtins\n  - zsh loops\n  - external commands\n- Make variables local & readonly when possible\n- Use:\n  - `cp -c` instead of `cp`\n  - `trash` instead of `rm`\n\n## Swift\n\nmas is a SwiftPM project that uses Swift Argument Parser to interact with the\ncommand-line.\n\n### Apple Private Frameworks\n\nThe `PrivateFrameworks` SwiftPM target exposes the following Apple private\nframeworks (via Objective-C headers extracted from the DSC) to deploy App Store\napps:\n\n- **CommerceKit:** Controllers\n- **StoreFoundation:** Models\n\nUse private frameworks only when public APIs are insufficient.\n\nNewer Apple private frameworks (e.g., AppStoreDaemon & AppleMediaServices) seem\nto supersede the currently used ones, but the newer ones seem usable only by\ncode with Apple-exclusive entitlements.\n\n### Swift Source Folder Hierarchy\n\nSwift source is organized in subfolders of `Sources/mas`:\n\n- **Commands:** CLI implementation\n- **Models:** Data types & suppliers\n- **Utilities:** Utilities\n\n### Command Implementation Patterns\n\nCommands follow a consistent structure:\n\n- Commands are nested structs within the `MAS` main command\n- Use `@OptionGroup` to compose reusable argument sets from dedicated types\n  that conform to `ParsableArguments`\n- Implement `func run() async { … }` as the main command entry point\n- Use the static `MAS.printer` for all output to ensure consistent formatting\n- Call methods on `AppStoreAction` enum cases (accessible via the `AppStore`\n  typealias) to execute business logic, e.g., `await AppStore.install.apps(…)`\n\n### Style Essentials\n\n- Name most function parameters\n- Capitalize acronym & initialism characters consistently (e.g., `ADAM`, `API`,\n  `HTTPRequest`, `JSON`)\n- Shadow variables if the respective original will no longer be used\n- Strongify weak references instead of evaluating them multiple times\n- Group computed properties below stored properties\n\n### Code Preference Hierarchies\n\nEach subsection contains code preferences in descending order.\n\nWithin this section & all subsections, `X` is a placeholder for any type name.\n\n#### Naming\n\n1. Standardized name\n2. Concise name\n3. Verbose name\n\n#### Concision/Verbosity\n\n1. Concise code, e.g.:\n   - Optional binding shorthand (e.g., `if let x { … }`, not\n     `if let x = x{ … }`)\n2. Verbose code\n\n#### Architecture\n\n1. Composition\n2. Protocol conformance\n3. Class inheritance\n\n#### Typing\n\n1. Inferred type, e.g.:\n   - `var a = [X]()`\n   - `var o = X?.none`\n   - `var c: X { .init() }`\n   - `f(array: .init())`\n   - `f(dictionary: .init())`\n2. Cast type, e.g.:\n   - `var a = [] as [X]`\n   - `var o = nil as X?`\n3. Explicit type, e.g.:\n   - `var a: [X] = .init()`\n   - `var o: X? = nil`\n   - `var c: X { X() }`\n   - `f(array: [])`\n   - `f(dictionary: [:])`\n\n#### Functional\n\n1. Functional\n2. Non-functional\n\n#### Value Inlining/Binding\n\n1. Inlined single-use value\n2. `let` multiple-use value\n3. `var` multiple-use value\n\n#### Code Inlining/Reuse\n\n1. Inlined single-use code (unless inlined code is much more complex)\n2. Computed property\n3. Function\n\n#### Optional Handling\n\n1. Nil-coalescing operator (`??`)\n2. Ternary operator\n3. `Optional.map(_:)` / `Optional.flatMap(_:)`\n4. Single `guard`\n5. `if` / `else` (no `else if`)\n6. `switch`\n7. Multiple `guard`\n8. `if` / `else if`… / `else`\n9. `preconditionFailure(_:file:line:)`\n10. Forced unwrapping (`!` suffix)\n11. `fatalError(_:file:line:)`\n\n#### Throwing\n\n1. Typed throws (`throws(ErrorType)`)\n2. Untyped rethrows (`rethrows`)\n3. Untyped throws (`throws`)\n\n#### Code Reuse\n\n1. Framework/library call\n2. Custom code\n\n#### Constants\n\n1. Global `let`\n2. `enum` `static let`\n3. `struct` `static let`\n4. `class` `static let`\n\n#### Preferred Types\n\n1. Unaliased infrequent tuple/closure\n2. Type-aliased frequent tuple/closure\n3. `enum`\n4. `struct`\n5. `actor`\n6. `final class`\n7. `class`\n\n#### Type Syntax\n\n1. Concision:\n   - Generics: `<T: X>`\n   - Optional: `X?`\n   - Collection: `[X]`\n   - Dictionary: `[X:X]`\n2. Verbosity:\n   - Generics: `where T: X`\n   - Optional: `Optional<X>`\n   - Collection: `Array<X>`\n   - Dictionary: `Dictionary<X, X>`\n\n#### Void Types\n\n1. `()` for void parameter type\n2. `Void` for void return type\n\n#### Closure Syntax\n\n1. Trailing closure\n2. Inline closure\n\n#### Closure Arguments\n\n1. Shorthand argument names (e.g., `$0`) iff one-line closure\n2. Explicit argument names for multi-line closure\n\n#### Functional Arguments\n\n1. KeyPath\n2. Function reference\n3. Closure\n\n#### Strict Memory Safety\n\n1. Memory-safe code (i.e. not `unsafe`)\n2. `unsafe` code iff a memory-safe alternative:\n   - Is not available from frameworks/libraries\n   - Is too difficult to implement properly & performantly\n\n### Testing Requirements\n\n- Add tests for all non-trivial changes (to preserve tokens, agents should not\n  add tests unless explicitly directed to do so)\n- Implement in [Swift Testing](https://github.com/swiftlang/swift-testing)\n- Derive test file paths from source file paths:\n  - replace the `Sources/mas` source path folder prefix with `Tests/MASTests`\n  - prepend `MASTests+` to the source file name\n  - e.g., `Sources/mas/Commands/X.swift` →\n    `Tests/MASTests/Commands/MASTests+X.swift`\n- Use force unwrapping in tests where appropriate\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Project Guidelines\n\n## Purpose & Scope\n\nThis file is the canonical source of project conventions for humans & agents.\nRead it before making repository changes.\n\n## Minimum Versions\n\n- **Swift:** 6.3\n- **Xcode:** 26.4\n- **macOS:** 13\n\n## Quick Entry Points\n\n- `Scripts/bootstrap`\n- `Scripts/format`\n- `Scripts/lint -AP` (quick) / `Scripts/lint` (includes unused code checks)\n- `Scripts/build` (debug) / `Scripts/build '' -c release` (release)\n- `Scripts/test`\n- `Scripts/package`\n\n## Git Workflow\n\n- `main` is the trunk\n- Branch topics from `main`\n- Before committing (to preserve tokens, agents should skip all of the following\n  steps unless explicitly directed to perform them):\n  1. Add or edit tests for non-trivial changes\n  2. Repeatedly run `Scripts/format` until no modifications are made\n  3. Repeatedly run `Scripts/lint` & fix all violations until no violations are\n     reported\n- **Commit messages:** Follow [commit message conventions](\n    https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html\n  )\n- Tag releases as `vX.Y.Z`\n\n## Content Formatting\n\n- **Newlines:** Unix (i.e. `\\n`)\n- **Indentation:** Tabs (2 characters wide) for all files unless otherwise\n  specified; 2 spaces for YAML; 1 space for Markdown\n- **Max line length:** 120 characters for all files unless otherwise specified\n  (tabs count as 2 characters); 80 for Markdown; unlimited for header, JSON &\n  swiftformat\n- **Unnecessary trailing whitespace:** Remove\n- **File ends:** Single newline\n- **Quoting:** Quote strings only when necessary, preferring the most literal\n  format that works over more interpreted formats; if multiple quote syntaxes\n  are functionally equivalent, prefer the visually lightest, e.g., prefer single\n  quotes over double quotes if they are functionally equivalent\n- **Text**: In documentation, comments, strings, etc.:\n  - **Commas:** Use Oxford commas for lists\n  - **Ampersands:** Prefer `&` to `and` (omit Oxford comma before `&`)\n  - **Exceptions:** `and` should be used in `and/or` & after a comma that\n    separates distinct clauses (but not in a list)\n  - **Quotes**: The enclosing quotations marks of a quote at the end of a\n    sentence (iff the whole sentence isn't a quote) should not enclose the\n    terminal punctuation mark of the encompassing sentence\n  - **Iff**: Use `iff` as `if & only if`\n\n### Markdown Guidelines\n\n- **Style:** GitHub-Flavored Markdown (GFM), ATX headings, backtick-fenced code\n  blocks with language identifier, underscore emphasis, asterisk strong & hyphen\n  bullets\n- **HTML:** Limit to HTML supported by GFM that doesn't have a native GFM\n  equivalent\n\n## Refactoring Rules\n\nUnless absolutely necessary for functionality or fixes, or unless violations of\nstandards are discovered, do not:\n\n- reformat\n- rename\n- reorder\n- respace\n- reword\n- remove comments\n- refactor if it worsens the caller interface\n\nRefactoring should:\n\n- Keep clean abstractions\n- Inline a utility iff it is single-use\n- Replace a utility iff the new version is more correct, performant, and/or\n  simpler than the existing version, in descending order of priority\n\n## Scripting\n\n- Use zsh for scripts (except for shell-specific completion scripts)\n- Zsh scripts must be compatible with all zsh versions starting with the version\n  ([currently 5.9](https://opensource.apple.com/releases/)) bundled with the\n  newest version ([currently 13.5.x](https://opensource.apple.com/releases/))\n  of the oldest macOS major version supported by mas\n  ([currently 13](Package.swift))\n- Use `#!/bin/zsh` shebang (with `-Ndefgku` options, unless any changes to the\n  options are absolutely necessary)\n- Run `. \"${0:A:h}/_setup_script\"` at the start of all development scripts\n- Prefer concision over verbosity\n- If performance is at least almost equivalent or better, prefer in descending\n  order:\n  - zsh expansions\n  - zsh globs\n  - zsh builtins\n  - zsh loops\n  - external commands\n- Make variables local & readonly when possible\n- Use:\n  - `cp -c` instead of `cp`\n  - `trash` instead of `rm`\n\n## Swift\n\nmas is a SwiftPM project that uses Swift Argument Parser to interact with the\ncommand-line.\n\n### Apple Private Frameworks\n\nThe `PrivateFrameworks` SwiftPM target exposes the following Apple private\nframeworks (via Objective-C headers extracted from the DSC) to deploy App Store\napps:\n\n- **CommerceKit:** Controllers\n- **StoreFoundation:** Models\n\nUse private frameworks only when public APIs are insufficient.\n\nNewer Apple private frameworks (e.g., AppStoreDaemon & AppleMediaServices) seem\nto supersede the currently used ones, but the newer ones seem usable only by\ncode with Apple-exclusive entitlements.\n\n### Swift Source Folder Hierarchy\n\nSwift source is organized in subfolders of `Sources/mas`:\n\n- **Commands:** CLI implementation\n- **Models:** Data types & suppliers\n- **Utilities:** Utilities\n\n### Command Implementation Patterns\n\nCommands follow a consistent structure:\n\n- Commands are nested structs within the `MAS` main command\n- Use `@OptionGroup` to compose reusable argument sets from dedicated types\n  that conform to `ParsableArguments`\n- Implement `func run() async { … }` as the main command entry point\n- Use the static `MAS.printer` for all output to ensure consistent formatting\n- Call methods on `AppStoreAction` enum cases (accessible via the `AppStore`\n  typealias) to execute business logic, e.g., `await AppStore.install.apps(…)`\n\n### Style Essentials\n\n- Name most function parameters\n- Capitalize acronym & initialism characters consistently (e.g., `ADAM`, `API`,\n  `HTTPRequest`, `JSON`)\n- Shadow variables if the respective original will no longer be used\n- Strongify weak references instead of evaluating them multiple times\n- Group computed properties below stored properties\n\n### Code Preference Hierarchies\n\nEach subsection contains code preferences in descending order.\n\nWithin this section & all subsections, `X` is a placeholder for any type name.\n\n#### Naming\n\n1. Standardized name\n2. Concise name\n3. Verbose name\n\n#### Concision/Verbosity\n\n1. Concise code, e.g.:\n   - Optional binding shorthand (e.g., `if let x { … }`, not\n     `if let x = x{ … }`)\n2. Verbose code\n\n#### Architecture\n\n1. Composition\n2. Protocol conformance\n3. Class inheritance\n\n#### Typing\n\n1. Inferred type, e.g.:\n   - `var a = [X]()`\n   - `var o = X?.none`\n   - `var c: X { .init() }`\n   - `f(array: .init())`\n   - `f(dictionary: .init())`\n2. Cast type, e.g.:\n   - `var a = [] as [X]`\n   - `var o = nil as X?`\n3. Explicit type, e.g.:\n   - `var a: [X] = .init()`\n   - `var o: X? = nil`\n   - `var c: X { X() }`\n   - `f(array: [])`\n   - `f(dictionary: [:])`\n\n#### Functional\n\n1. Functional\n2. Non-functional\n\n#### Value Inlining/Binding\n\n1. Inlined single-use value\n2. `let` multiple-use value\n3. `var` multiple-use value\n\n#### Code Inlining/Reuse\n\n1. Inlined single-use code (unless inlined code is much more complex)\n2. Computed property\n3. Function\n\n#### Optional Handling\n\n1. Nil-coalescing operator (`??`)\n2. Ternary operator\n3. `Optional.map(_:)` / `Optional.flatMap(_:)`\n4. Single `guard`\n5. `if` / `else` (no `else if`)\n6. `switch`\n7. Multiple `guard`\n8. `if` / `else if`… / `else`\n9. `preconditionFailure(_:file:line:)`\n10. Forced unwrapping (`!` suffix)\n11. `fatalError(_:file:line:)`\n\n#### Throwing\n\n1. Typed throws (`throws(ErrorType)`)\n2. Untyped rethrows (`rethrows`)\n3. Untyped throws (`throws`)\n\n#### Code Reuse\n\n1. Framework/library call\n2. Custom code\n\n#### Constants\n\n1. Global `let`\n2. `enum` `static let`\n3. `struct` `static let`\n4. `class` `static let`\n\n#### Preferred Types\n\n1. Unaliased infrequent tuple/closure\n2. Type-aliased frequent tuple/closure\n3. `enum`\n4. `struct`\n5. `actor`\n6. `final class`\n7. `class`\n\n#### Type Syntax\n\n1. Concision:\n   - Generics: `<T: X>`\n   - Optional: `X?`\n   - Collection: `[X]`\n   - Dictionary: `[X:X]`\n2. Verbosity:\n   - Generics: `where T: X`\n   - Optional: `Optional<X>`\n   - Collection: `Array<X>`\n   - Dictionary: `Dictionary<X, X>`\n\n#### Void Types\n\n1. `()` for void parameter type\n2. `Void` for void return type\n\n#### Closure Syntax\n\n1. Trailing closure\n2. Inline closure\n\n#### Closure Arguments\n\n1. Shorthand argument names (e.g., `$0`) iff one-line closure\n2. Explicit argument names for multi-line closure\n\n#### Functional Arguments\n\n1. KeyPath\n2. Function reference\n3. Closure\n\n#### Strict Memory Safety\n\n1. Memory-safe code (i.e. not `unsafe`)\n2. `unsafe` code iff a memory-safe alternative:\n   - Is not available from frameworks/libraries\n   - Is too difficult to implement properly & performantly\n\n### Testing Requirements\n\n- Add tests for all non-trivial changes (to preserve tokens, agents should not\n  add tests unless explicitly directed to do so)\n- Implement in [Swift Testing](https://github.com/swiftlang/swift-testing)\n- Derive test file paths from source file paths:\n  - replace the `Sources/mas` source path folder prefix with `Tests/MASTests`\n  - prepend `MASTests+` to the source file name\n  - e.g., `Sources/mas/Commands/X.swift` →\n    `Tests/MASTests/Commands/MASTests+X.swift`\n- Use force unwrapping in tests where appropriate\n","category":"root","tokens":2264}]}