Improve documentation, improve security, improve Scripts/mas & cleanup code

.github/workflows/build-test.yaml

@@ -39,7 +39,7 @@ jobs:
         GIT_CONFIG_COUNT: 1
         GIT_CONFIG_KEY_0: init.defaultBranch
         GIT_CONFIG_VALUE_0: ${{github.event.repository.default_branch}}
-      uses: actions/checkout@v6
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       with:
         # Include all history & tags for Scripts/version
         fetch-depth: 0

.github/workflows/codeql.yaml

@@ -11,6 +11,7 @@ on:
   schedule:
   - cron: 44 14 * * 4
   workflow_dispatch: {}
+permissions: {}
 jobs:
   analyze:
     name: Analyze ${{matrix.language}}
@@ -31,7 +32,7 @@ jobs:
         GIT_CONFIG_COUNT: 1
         GIT_CONFIG_KEY_0: init.defaultBranch
         GIT_CONFIG_VALUE_0: ${{github.event.repository.default_branch}}
-      uses: actions/checkout@v6
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       with:
         # Include all history & tags for Scripts/version
         fetch-depth: 0
@@ -40,7 +41,7 @@ jobs:
       run: Scripts/setup_workflow_repo
 
     - name: 🔩 Initialize CodeQL
-      uses: github/codeql-action/init@v4
+      uses: github/codeql-action/init@95e58e9a2cdfd71adc6e0353d5c52f41a045d225 # v4.35.2
       with:
         languages: ${{matrix.language}}
         build-mode: ${{matrix.build-mode}}
@@ -54,6 +55,6 @@ jobs:
         Scripts/build codeql -c release
 
     - name: 🔍 Perform CodeQL analysis
-      uses: github/codeql-action/analyze@v4
+      uses: github/codeql-action/analyze@95e58e9a2cdfd71adc6e0353d5c52f41a045d225 # v4.35.2
       with:
         category: /language:${{matrix.language}}

.github/workflows/release-published.yaml

@@ -8,8 +8,6 @@ on:
     types: [published]
 permissions:
   actions: read
-  contents: write
-  pull-requests: write
 defaults:
   run:
     # Force all run commands to not use Rosetta 2
@@ -18,13 +16,16 @@ jobs:
   release-published:
     if: ${{!github.event.repository.fork}}
     runs-on: macos-26
+    permissions:
+      contents: write
+      pull-requests: write
     steps:
     - name: 🛒 Checkout repo
       env:
         GIT_CONFIG_COUNT: 1
         GIT_CONFIG_KEY_0: init.defaultBranch
         GIT_CONFIG_VALUE_0: ${{github.event.repository.default_branch}}
-      uses: actions/checkout@v6
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       with:
         # Include all history & tags for Scripts/version
         fetch-depth: 0

.github/workflows/tag-pushed.yaml

@@ -6,8 +6,7 @@ name: tag-pushed
 on:
   push:
     tags: ['**']
-permissions:
-  contents: write
+permissions: {}
 defaults:
   run:
     # Force all run commands to not use Rosetta 2
@@ -16,13 +15,15 @@ jobs:
   tag-pushed:
     if: ${{!github.event.repository.fork}}
     runs-on: macos-26
+    permissions:
+      contents: write
     steps:
     - name: 🛒 Checkout repo
       env:
         GIT_CONFIG_COUNT: 1
         GIT_CONFIG_KEY_0: init.defaultBranch
         GIT_CONFIG_VALUE_0: ${{github.event.repository.default_branch}}
-      uses: actions/checkout@v6
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       with:
         # Include all history & tags for Scripts/version
         fetch-depth: 0

AGENTS.md

@@ -67,9 +67,9 @@ Do NOT refactor code if doing so makes the caller interface worse. Specifically:
 
 ## Minimum Versions
 
-- **Swift**: [6.2](.swift-version)
-- **Xcode**: [26](.xcode-version)
-- **macOS**: [13](Package.swift)
+- **Swift:** [6.2](.swift-version)
+- **Xcode:** [26](.xcode-version)
+- **macOS:** [13](Package.swift)
 
 ## Distributions
 
@@ -133,22 +133,22 @@ Scripts/package
 
 ## Git Workflow
 
-- **Trunk-based development**: `main` is the trunk
-- **Topic branches**: Branch from `main` (e.g., `git checkout -b feature main`)
-- **Commit messages**: Follow [commit message conventions](
+- **Trunk-based development:** `main` is the trunk
+- **Topic branches:** Branch from `main` (e.g., `git checkout -b feature main`)
+- **Commit messages:** Follow [commit message conventions](
     https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
   )
-- **Release tags**: Format like `v1.2.3`
-- **Before committing**: Run `Scripts/format` repeatedly until it no longer
+- **Release tags:** Format like `v1.2.3`
+- **Before committing:** Run `Scripts/format` repeatedly until it no longer
   modifies any files, then run `Scripts/lint`, then fix all violations
 
 ## Content Formatting
 
-- **Newlines**: UNIX (i.e. `\n`)
-- **Indentation**: Tabs (width: 2)
-- **Max line length**: 120 characters
-- **Unnecessary trailing whitespace**: Remove
-- **File ends**: Single newline
+- **Newlines:** UNIX (i.e. `\n`)
+- **Indentation:** Tabs (width: 2)
+- **Max line length:** 120 characters
+- **Unnecessary trailing whitespace:** Remove
+- **File ends:** Single newline
 
 ## Content Preservation
 
@@ -199,8 +199,8 @@ The `PrivateFrameworks` SwiftPM target allows using the following Apple private
 frameworks (via Objective-C headers extracted from the DSC) to deploy App Store
 apps:
 
-- **CommerceKit**: Controllers
-- **StoreFoundation**: Models
+- **CommerceKit:** Controllers
+- **StoreFoundation:** Models
 
 Use them only where public APIs are insufficient.
 
@@ -210,12 +210,12 @@ Apple-exclusive entitlements.
 
 ### Source Folder Hierarchy
 
-Source is organized by concern:
+Source is organized in folders by concern:
 
-- **AppStore/**: App Store integration
-- **Commands/**: CLI implementation
-- **Models/**: Data types
-- **Utilities/**: Utilities
+- **AppStore:** App Store integration
+- **Commands:** CLI implementation
+- **Models:** Data types
+- **Utilities:** Utilities
 
 ### Style Essentials
 

GEMINI.md

@@ -5,19 +5,19 @@ development of `mas`, a command-line interface for the Mac App Store.
 
 ## Project Overview
 
-- **Name**: `mas`
-- **Description**: A CLI for the Mac App Store, designed for scripting &
+- **Name:** `mas`
+- **Description:** A CLI for the Mac App Store, designed for scripting &
   automation.
-- **Language**: Swift 6.2 (using Swift Argument Parser)
-- **Target OS**: macOS 13+
-- **Project Type**: SwiftPM project
+- **Language:** Swift 6.2 (using Swift Argument Parser)
+- **Target OS:** macOS 13+
+- **Project Type:** SwiftPM project
 
 ## Technical Stack
 
-- **Swift**: 6.2+ (Check [.swift-version](.swift-version))
-- **Xcode**: 26+ (Check [.xcode-version](.xcode-version))
-- **macOS**: 13+ (Check [Package.swift](Package.swift))
-- **Private Frameworks**: Uses `CommerceKit` and `StoreFoundation` for App Store
+- **Swift:** 6.2+ (Check [.swift-version](.swift-version))
+- **Xcode:** 26+ (Check [.xcode-version](.xcode-version))
+- **macOS:** 13+ (Check [Package.swift](Package.swift))
+- **Private Frameworks:** Uses `CommerceKit` and `StoreFoundation` for App Store
   integration only where public APIs are insufficient.
 
 ## Development Workflows
@@ -51,54 +51,54 @@ Refer to [AGENTS.md](AGENTS.md) for comprehensive guidelines. Key highlights:
 
 ### Content Guidelines
 
-- **Newlines**: UNIX (LF)
-- **Indentation**: Tabs (width: 2) for Swift/Zsh; Spaces (2) for YAML; Spaces
+- **Newlines:** UNIX (LF)
+- **Indentation:** Tabs (width: 2) for Swift/Zsh; Spaces (2) for YAML; Spaces
   (1) for Markdown.
-- **Max line length**: 120 characters (80 for Markdown).
-- **Preservation**: Do not reformat, rename, or reorder code unless necessary
+- **Max line length:** 120 characters (80 for Markdown).
+- **Preservation:** Do not reformat, rename, or reorder code unless necessary
   for functionality.
 
 ### Markdown Guidelines
 
-- **Style**: ATX headings, fenced code blocks with backticks, underscore
+- **Style:** ATX headings, fenced code blocks with backticks, underscore
   emphasis, asterisk strong.
-- **Language**: Only `console` and `shell` are allowed in code fences.
-- **HTML**: Limited to `<details>`, `<h1>`, `<summary>`.
+- **Language:** Only `console` and `shell` are allowed in code fences.
+- **HTML:** Limited to `<details>`, `<h1>`, `<summary>`.
 
 ### YAML Guidelines
 
-- **Style**: 2 spaces indentation, single quotes for strings, unix newlines.
-- **Rules**: Forbid non-empty braces, require document start (`---`).
+- **Style:** 2 spaces indentation, single quotes for strings, unix newlines.
+- **Rules:** Forbid non-empty braces, require document start (`---`).
 
 ### Zsh Scripting
 
-- **Shebang**: `#!/bin/zsh -Ndefgku`
-- **Setup**: Start scripts with `. "${0:A:h}/_setup_script"`
-- **Preference**: Use zsh builtins over external commands.
-- **Commands**: Use `cp -c` and `trash` (not `rm`).
+- **Shebang:** `#!/bin/zsh -Ndefgku`
+- **Setup:** Start scripts with `. "${0:A:h}/_setup_script"`
+- **Preference:** Use zsh builtins over external commands.
+- **Commands:** Use `cp -c` and `trash` (not `rm`).
 
 ### Swift Development
 
-- **Structure**: Organized by `AppStore/`, `Commands/`, `Models/`, `Utilities/`.
-- **Force Unwrapping**: Avoid in `Sources/mas/`.
-- **Naming**: Capitalize acronyms consistently (e.g., `ADAM`, `API`, `JSON`).
-- **Organization**: Group computed properties below stored properties.
-- **Error Handling**: Prefer typed throws (`throws(ErrorType)`),
+- **Structure:** Organized by `AppStore/`, `Commands/`, `Models/`, `Utilities/`.
+- **Force Unwrapping:** Avoid in `Sources/mas/`.
+- **Naming:** Capitalize acronyms consistently (e.g., `ADAM`, `API`, `JSON`).
+- **Organization:** Group computed properties below stored properties.
+- **Error Handling:** Prefer typed throws (`throws(ErrorType)`),
   then `rethrows`, then untyped `throws`.
 
 ### Git Workflow
 
-- **Trunk**: `main`
-- **Commits**: Follow [conventional commit style](
+- **Trunk:** `main`
+- **Commits:** Follow [conventional commit style](
     https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
   ).
-- **Pre-commit**: Always run `Scripts/format` and `Scripts/lint` before
+- **Pre-commit:** Always run `Scripts/format` and `Scripts/lint` before
   committing.
 
 ## Testing Requirements
 
-- **Framework**: [Swift Testing](https://github.com/swiftlang/swift-testing).
-- **Location**: `Tests/MASTests/`
-- **Naming Convention**: `Sources/mas/Path/To/File.swift` ->
+- **Framework:** [Swift Testing](https://github.com/swiftlang/swift-testing).
+- **Location:** `Tests/MASTests/`
+- **Naming Convention:** `Sources/mas/Path/To/File.swift` ->
   `Tests/MASTests/Path/To/MASTests+File.swift`.
-- **Assertions**: Use force unwrapping (`!`) in tests if appropriate.
+- **Assertions:** Use force unwrapping (`!`) in tests if appropriate.