feat: Menu Bar Foundation - Phase 1 Task 1

[jsonify]

Summary

Implements Phase 1 Task 1 of the Menu Bar Foundation spec: App Group and Shared State Infrastructure.

This establishes the foundation for state sharing between the main Pearcleaner app and the menu bar component that will be built in subsequent tasks.

Changes Made

1. App Group Configuration

• Verified existing group.com.alienator88.Pearcleaner entitlement in Pearcleaner.entitlements
• Ready for shared UserDefaults communication between app components

2. MenuBarUpdatePublisher Class

Location: Pearcleaner/Logic/MenuBar/MenuBarUpdatePublisher.swift

• Singleton pattern for centralized shared state publishing
• Methods:
  • publishUpdateCount(_:) - Writes update count to shared storage
  • publishLastCheckDate(_:) - Writes last check timestamp to shared storage
  • publishUpdate(count:lastCheck:) - Atomic write of both values
  • readUpdateCount() / readLastCheckDate() - Read methods for testing
• Error handling with graceful degradation when App Group unavailable
• Debug logging via printOS() for troubleshooting
• Returns Bool to indicate success/failure

3. AppState Extension

Location: Pearcleaner/Logic/AppState.swift

• Added @Published var showMenuBar: Bool property
• Persists to UserDefaults key: "settings.interface.showMenuBar"
• Auto-saves on change via didSet observer
• Defaults to false (menu bar hidden initially)
• Reactive property for SwiftUI binding in Settings UI (Task 8)

4. Shared Storage Keys

• menubar.updateCount - Total pending updates
• menubar.lastCheck - Last update check Date
• App Group: group.com.alienator88.Pearcleaner

Testing

Manual test verification document created at:
.agent-os/specs/2025-11-26-menubar-foundation/test-verification/task-1-verification.md

Test Checklist:

• App Group entitlement configured
• MenuBarUpdatePublisher class created with all methods
• Error handling for nil shared storage
• AppState.showMenuBar property with persistence
• Manual runtime testing (pending Xcode build)

Product Documentation

This PR also includes initial Agent OS product documentation:

• Product mission and vision
• Technical architecture decisions
• 5-phase development roadmap
• Decision log with rationale
• CLAUDE.md for future AI agents working on this codebase

Next Steps

Task 2 will build MenuBarManager to read from this shared state and manage menu bar UI state.

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello @jsonify, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request lays the groundwork for integrating a persistent menu bar component into Pearcleaner. It focuses on establishing the necessary infrastructure for shared state management between the main application and the upcoming menu bar feature, ensuring seamless data synchronization and user preference persistence. The changes are part of Phase 1 Task 1 of the Menu Bar Foundation, setting up the core communication channels and initial configuration without yet implementing the menu bar UI itself.

Highlights

• App Group and Shared State Infrastructure: This PR establishes the foundation for state sharing between the main Pearcleaner app and a future menu bar component. It includes verifying the existing App Group entitlement group.com.alienator88.Pearcleaner for shared UserDefaults communication.
• MenuBarUpdatePublisher Class: A new singleton class, MenuBarUpdatePublisher, has been added to Pearcleaner/Logic/MenuBar/MenuBarUpdatePublisher.swift. This class is responsible for publishing update counts and last check timestamps to the shared App Group storage, featuring error handling for unavailable App Groups and debug logging.
• AppState Extension for Menu Bar Visibility: The AppState.swift file has been extended with a new @Published var showMenuBar: Bool property. This property manages the visibility of the menu bar, persists its state to UserDefaults under the key settings.interface.showMenuBar, and defaults to false.
• Comprehensive Documentation Added: Extensive new documentation has been added, including product mission, decisions, roadmap, technical stack, and detailed specifications (spec, technical-spec, tests, tasks) for the Menu Bar Foundation feature. A CLAUDE.md file was also added to guide AI agents.
• Initial Test Verification: An initial manual test verification document (.agent-os/specs/2025-11-26-menubar-foundation/test-verification/task-1-verification.md) has been created, outlining steps and expected behaviors for verifying the App Group and shared state infrastructure, with several checks already marked as complete.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request lays a solid foundation for the new menu bar feature by setting up the App Group and shared state infrastructure. The code is well-structured and accompanied by thorough documentation, which is great to see. I've provided a couple of suggestions to improve maintainability and align with modern Swift practices, mainly concerning the use of UserDefaults.

[gemini-code-assist]

The UserDefaults key "settings.interface.showMenuBar" is hardcoded and duplicated. It's a good practice to define it as a constant to avoid typos and improve maintainability. This also makes it easier to find all usages of this key.

Suggested change

	// Menu bar visibility (persisted to UserDefaults)
	@Published var showMenuBar: Bool = UserDefaults.standard.bool(forKey: "settings.interface.showMenuBar") {
	didSet {
	UserDefaults.standard.set(showMenuBar, forKey: "settings.interface.showMenuBar")
	}
	}
	// Menu bar visibility (persisted to UserDefaults)
	private static let showMenuBarKey = "settings.interface.showMenuBar"
	@Published var showMenuBar: Bool = UserDefaults.standard.bool(forKey: AppState.showMenuBarKey) {
	didSet {
	UserDefaults.standard.set(showMenuBar, forKey: AppState.showMenuBarKey)
	}
	}

[gemini-code-assist]

This is a solid implementation for publishing state. I have a couple of suggestions to improve it further:

1. Use Static Constants for Keys: The UserDefaults keys and app group identifier are defined as private instance properties. Making them static constants is more idiomatic and allows other components (like the future menu bar reader) to safely access them (e.g., MenuBarUpdatePublisher.appGroupIdentifier), preventing stringly-typed errors.
2. Remove synchronize() Calls: The calls to defaults.synchronize() are no longer necessary. UserDefaults automatically saves data at appropriate times, and explicitly calling synchronize() can be inefficient. Removing these calls is the modern best practice.

I've combined these changes into a single suggestion for the whole class.

class MenuBarUpdatePublisher {
    static let shared = MenuBarUpdatePublisher()

    // MARK: - Shared UserDefaults Keys
    static let updateCountKey = "menubar.updateCount"
    static let lastCheckKey = "menubar.lastCheck"
    static let appGroupIdentifier = "group.com.alienator88.Pearcleaner"

    // MARK: - Shared Storage Access

    /// Shared UserDefaults container for App Group communication
    /// Returns nil if App Group is not configured
    private var sharedDefaults: UserDefaults? {
        return UserDefaults(suiteName: Self.appGroupIdentifier)
    }

    // MARK: - Public Methods

    /// Publishes update count to shared storage
    /// - Parameter count: Total number of pending updates
    /// - Returns: Boolean indicating success or failure
    @discardableResult
    func publishUpdateCount(_ count: Int) -> Bool {
        guard let defaults = sharedDefaults else {
            printOS("MenuBarUpdatePublisher: App Group not available, cannot publish update count")
            return false
        }

        defaults.set(count, forKey: Self.updateCountKey)

        printOS("MenuBarUpdatePublisher: Published update count: \(count)")
        return true
    }

    /// Publishes last check timestamp to shared storage
    /// - Parameter date: Date when update check completed
    /// - Returns: Boolean indicating success or failure
    @discardableResult
    func publishLastCheckDate(_ date: Date) -> Bool {
        guard let defaults = sharedDefaults else {
            printOS("MenuBarUpdatePublisher: App Group not available, cannot publish last check date")
            return false
        }

        defaults.set(date, forKey: Self.lastCheckKey)

        printOS("MenuBarUpdatePublisher: Published last check date: \(date)")
        return true
    }

    /// Publishes both update count and timestamp atomically
    /// - Parameters:
    ///   - count: Total number of pending updates
    ///   - date: Date when update check completed
    /// - Returns: Boolean indicating success or failure
    @discardableResult
    func publishUpdate(count: Int, lastCheck date: Date) -> Bool {
        guard let defaults = sharedDefaults else {
            printOS("MenuBarUpdatePublisher: App Group not available, cannot publish update")
            return false
        }

        defaults.set(count, forKey: Self.updateCountKey)
        defaults.set(date, forKey: Self.lastCheckKey)

        printOS("MenuBarUpdatePublisher: Published count: \(count), date: \(date)")
        return true
    }

    // MARK: - Read Methods (for testing/debugging)

    /// Reads current update count from shared storage
    /// Returns nil if App Group not available or key doesn't exist
    func readUpdateCount() -> Int? {
        guard let defaults = sharedDefaults else {
            return nil
        }

        guard defaults.object(forKey: Self.updateCountKey) != nil else {
            return nil
        }

        return defaults.integer(forKey: Self.updateCountKey)
    }

    /// Reads last check date from shared storage
    /// Returns nil if App Group not available or key doesn't exist
    func readLastCheckDate() -> Date? {
        guard let defaults = sharedDefaults else {
            return nil
        }

        return defaults.object(forKey: Self.lastCheckKey) as? Date
    }
}