AGENTS.md

1# Project Guidelines
2 
3## Purpose & Scope
4 
5This file is the canonical source of project conventions for humans & agents.
6Read it before making repository changes.
7 
8## Minimum Versions
9 
10- **Swift:** 6.3
11- **Xcode:** 26.4
12- **macOS:** 13
13 
14## Quick Entry Points
15 
16- `Scripts/bootstrap`
17- `Scripts/format`
18- `Scripts/lint -AP` (quick) / `Scripts/lint` (includes unused code checks)
19- `Scripts/build` (debug) / `Scripts/build '' -c release` (release)
20- `Scripts/test`
21- `Scripts/package`
22 
23## Git Workflow
24 
25- `main` is the trunk
26- Branch topics from `main`
27- Before committing (to preserve tokens, agents should skip steps 2 & 3):
28  1. Add or edit tests for non-trivial changes
29  2. Repeatedly run `Scripts/format` until no modifications are made
30  3. Repeatedly run `Scripts/lint` & fix all violations until no violations are
31     reported
32- **Commit messages:** Follow [commit message conventions](
33    https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
34  )
35- Tag releases as `vX.Y.Z`
36 
37## Content Formatting
38 
39- **Newlines:** UNIX (i.e. `\n`)
40- **Indentation:** Tabs (width: 2)
41- **Max line length:** 120 characters (tabs count as 2 characters)
42- **Unnecessary trailing whitespace:** Remove
43- **File ends:** Single newline
44 
45## Refactoring Rules
46 
47Unless absolutely necessary for functionality or fixes, or unless violations of
48standards are discovered, do not:
49 
50- reformat
51- rename
52- reorder
53- respace
54- reword
55- remove comments
56- refactor if it worsens the caller interface
57 
58Refactoring should:
59 
60- Keep clean abstractions
61- Inline a utility iff it is single-use
62- Replace a utility iff the new version is more correct, performant, and/or
63  simpler than the existing version, in descending order of priority
64 
65## Scripting
66 
67- Use zsh for scripts (except for shell-specific completion scripts)
68- Zsh scripts must be compatible with all zsh versions starting with the version
69  ([currently 5.9](https://opensource.apple.com/releases/)) bundled with the
70  newest version ([currently 13.5.x](https://opensource.apple.com/releases/))
71  of the oldest macOS major version supported by mas
72  ([currently 13](Package.swift))
73- Use `#!/bin/zsh` shebang (with `-Ndefgku` options, unless any changes to the
74  options are absolutely necessary)
75- Run `. "${0:A:h}/_setup_script"` at the start of all development scripts
76- Prefer concision over verbosity
77- If performance is at least almost equivalent or better, prefer in descending
78  order:
79  - zsh expansions
80  - zsh globs
81  - zsh builtins
82  - zsh loops
83  - external commands
84- Make variables local & readonly when possible
85- Use:
86  - `cp -c` instead of `cp`
87  - `trash` instead of `rm`
88 
89## Swift
90 
91mas is a SwiftPM project that uses Swift Argument Parser to interact with the
92command-line.
93 
94### Apple Private Frameworks
95 
96The `PrivateFrameworks` SwiftPM target exposes the following Apple private
97frameworks (via Objective-C headers extracted from the DSC) to deploy App Store
98apps:
99 
100- **CommerceKit:** Controllers
101- **StoreFoundation:** Models
102 
103Use private frameworks only when public APIs are insufficient.
104 
105Newer Apple private frameworks (e.g., AppStoreDaemon & AppleMediaServices) seem
106to supersede the currently used ones, but the newer ones seem usable only by
107code with Apple-exclusive entitlements.
108 
109### Swift Source Folder Hierarchy
110 
111Swift source is organized in subfolders of `Sources/mas`:
112 
113- **Commands:** CLI implementation
114- **Models:** Data types & suppliers
115- **Utilities:** Utilities
116 
117### Command Implementation Patterns
118 
119Commands follow a consistent structure:
120 
121- Commands are nested structs within the `MAS` main command
122- Use `@OptionGroup` to compose reusable argument sets from dedicated types
123  that conform to `ParsableArguments`
124- Implement `func run() async { … }` as the main command entry point
125- Use the static `MAS.printer` for all output to ensure consistent formatting
126- Call methods on `AppStoreAction` enum cases (accessible via the `AppStore`
127  typealias) to execute business logic, e.g., `await AppStore.install.apps(…)`
128 
129### Style Essentials
130 
131- Name most function parameters
132- Capitalize acronym & initialism characters consistently (e.g., `HTTPRequest`,
133  not `HttpRequest`)
134- Shadow variables if the respective original will no longer be used
135- Strongify weak references instead of evaluating them multiple times
136 
137### Code Preference Hierarchies
138 
139Each subsection contains code preferences in descending order.
140 
141Within this section & all subsections, `X` is a placeholder for any type name.
142 
143#### Naming
144 
1451. Standardized name
1462. Concise name
1473. Verbose name
148 
149#### Concision/Verbosity
150 
1511. Concise code, e.g.:
152   - Optional binding shorthand (e.g., `if let x { … }`, not
153     `if let x = x{ … }`)
1542. Verbose code
155 
156#### Architecture
157 
1581. Composition
1592. Protocol conformance
1603. Class inheritance
161 
162#### Typing
163 
1641. Inferred type, e.g.:
165   - `var a = [X]()`
166   - `var o = X?.none`
167   - `var c: X { .init() }`
168   - `f(array: .init())`
169   - `f(dictionary: .init())`
1702. Cast type, e.g.:
171   - `var a = [] as [X]`
172   - `var o = nil as X?`
1733. Explicit type, e.g.:
174   - `var a: [X] = .init()`
175   - `var o: X? = nil`
176   - `var c: X { X() }`
177   - `f(array: [])`
178   - `f(dictionary: [:])`
179 
180#### Functional
181 
1821. Functional
1832. Non-functional
184 
185#### Value Inlining/Binding
186 
1871. Inlined single-use value
1882. `let` multiple-use value
1893. `var` multiple-use value
190 
191#### Code Inlining/Reuse
192 
1931. Inlined single-use code (unless inlined code is much more complex)
1942. Computed property
1953. Function
196 
197#### Optional Handling
198 
1991. Nil-coalescing operator (`??`)
2002. Ternary operator
2013. `Optional.map(_:)` / `Optional.flatMap(_:)`
2024. Single `guard`
2035. `if` / `else` (no `else if`)
2046. `switch`
2057. Multiple `guard`
2068. `if` / `else if`… / `else`
2079. `preconditionFailure(_:file:line:)`
20810. Forced unwrapping (`!` suffix)
20911. `fatalError(_:file:line:)`
210 
211#### Throwing
212 
2131. Typed throws (`throws(ErrorType)`)
2142. Untyped rethrows (`rethrows`)
2153. Untyped throws (`throws`)
216 
217#### Code Reuse
218 
2191. Framework/library call
2202. Custom code
221 
222#### Constants
223 
2241. Global `let`
2252. `enum` `static let`
2263. `struct` `static let`
2274. `class` `static let`
228 
229#### Preferred Types
230 
2311. Unaliased infrequent tuple/closure
2322. Type-aliased frequent tuple/closure
2333. `enum`
2344. `struct`
2355. `actor`
2366. `final class`
2377. `class`
238 
239#### Type Syntax
240 
2411. Concision:
242   - Generics: `<T: X>`
243   - Optional: `X?`
244   - Collection: `[X]`
245   - Dictionary: `[X:X]`
2462. Verbosity:
247   - Generics: `where T: X`
248   - Optional: `Optional<X>`
249   - Collection: `Array<X>`
250   - Dictionary: `Dictionary<X, X>`
251 
252#### Void Types
253 
2541. `()` for void parameter type
2552. `Void` for void return type
256 
257#### Closure Syntax
258 
2591. Trailing closure
2602. Inline closure
261 
262#### Closure Arguments
263 
2641. Shorthand argument names (e.g., `$0`) iff one-line closure
2652. Explicit argument names for multi-line closure
266 
267#### Functional Arguments
268 
2691. KeyPath
2702. Function reference
2713. Closure
272 
273#### Strict Memory Safety
274 
2751. Memory-safe code (i.e. not `unsafe`)
2762. `unsafe` code iff a memory-safe alternative:
277   - Is not available from frameworks/libraries
278   - Is too difficult to implement properly & performantly
279 
280### Testing Requirements
281 
282- Add tests for all non-trivial changes
283- Implement in [Swift Testing](https://github.com/swiftlang/swift-testing)
284- Derive test file paths from source file paths:
285  - replace the `Sources/mas` source path folder prefix with `Tests/MASTests`
286  - prepend `MASTests+` to the source file name
287  - e.g., `Sources/mas/Commands/X.swift` →
288    `Tests/MASTests/Commands/MASTests+X.swift`
289- Use force unwrapping in tests where appropriate
290