GEMINI.md

1# Gemini Guidelines for `mas`
2 
3You are an expert Swift & Zsh developer assisting with the maintenance &
4development of `mas`, a command-line interface for the Mac App Store.
5 
6## Project Overview
7 
8- **Name:** `mas`
9- **Description:** A CLI for the Mac App Store, designed for scripting &
10  automation.
11- **Language:** Swift 6.3 (using Swift Argument Parser)
12- **Target OS:** macOS 13+
13- **Project Type:** SwiftPM project
14 
15## Technical Stack
16 
17- **Swift:** 6.3+ (Check [.swift-version](.swift-version))
18- **Xcode:** 26.4+ (Check [.xcode-version](.xcode-version))
19- **macOS:** 13+ (Check [Package.swift](Package.swift))
20- **Private Frameworks:** Uses `CommerceKit` & `StoreFoundation` for App Store
21  integration only where public APIs are insufficient.
22 
23## Development Workflows
24 
25### Bootstrap
26 
27```shell
28Scripts/bootstrap
29```
30 
31### Build
32 
33- Debug: `Scripts/build`
34- Release: `Scripts/build '' -c release`
35 
36### Lint & Format
37 
38- Quick Lint: `Scripts/lint -AP`
39- Full Lint: `Scripts/lint`
40- Format: `Scripts/format` (Run repeatedly until no changes occur)
41 
42### Test
43 
44```shell
45Scripts/test
46```
47 
48## Engineering Standards
49 
50Refer to [AGENTS.md](AGENTS.md) for comprehensive guidelines. Key highlights:
51 
52### Content Guidelines
53 
54- **Newlines:** UNIX (LF)
55- **Indentation:** Tabs (width: 2) for Swift/Zsh; Spaces (2) for YAML; Spaces
56  (1) for Markdown.
57- **Max line length:** 120 characters (80 for Markdown).
58- **Preservation:** Do not reformat, rename, or reorder code unless necessary
59  for functionality.
60 
61### Markdown Guidelines
62 
63- **Style:** GitHub-Flavored Markdown (GFM), ATX headings, backtick-fenced code
64  blocks with language identifier, underscore emphasis, asterisk strong & hyphen
65  bullets.
66- **HTML:** Limited to elements supported by GFM that don't have an equivalent
67  in GFM for the use case.
68 
69### YAML Guidelines
70 
71- **Style:** 2-space indentation, unix newlines, quoted strings only when
72  necessary, single quotes for strings.
73- **Rules:** Forbid non-empty braces, require document start (`---`).
74 
75### Zsh Scripting
76 
77- **Shebang:** `#!/bin/zsh -Ndefgku`
78- **Setup:** Start scripts with `. "${0:A:h}/_setup_script"`
79- **Preference:** Use zsh builtins over external commands.
80- **Commands:** Use `cp -c` & `trash` (not `rm`).
81 
82### Swift Development
83 
84- **Structure:** Organized by `Commands/`, `Models/`, `Utilities/`.
85- **Force Unwrapping:** Avoid in `Sources/mas/`.
86- **Naming:** Capitalize acronyms consistently (e.g., `ADAM`, `API`, `JSON`).
87- **Organization:** Group computed properties below stored properties.
88- **Error Handling:** Prefer typed throws (`throws(ErrorType)`),
89  then `rethrows`, then untyped `throws`.
90 
91### Git Workflow
92 
93- **Trunk:** `main`
94- **Commits:** Follow [conventional commit style](
95    https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
96  ).
97- **Pre-commit:** Always run `Scripts/format` & `Scripts/lint` before
98  committing.
99 
100## Testing Requirements
101 
102- **Framework:** [Swift Testing](https://github.com/swiftlang/swift-testing).
103- **Location:** `Tests/MASTests/`
104- **Naming Convention:** `Sources/mas/Path/To/File.swift` ->
105  `Tests/MASTests/Path/To/MASTests+File.swift`.
106- **Assertions:** Use force unwrapping (`!`) in tests if appropriate.
107