refactor(main): organize main structure

Signed-off-by: Adam Setch <adam.setch@outlook.com>

Author: setchy

src/main/handlers/app.ts

@@ -20,6 +20,7 @@ export function registerAppHandlers(mb: Menubar): void {
 
   onMainEvent(EVENTS.QUIT, () => mb.app.quit());
 
+  // Path handlers for renderer queries about resource locations
   handleMainEvent(EVENTS.NOTIFICATION_SOUND_PATH, () => {
     return Paths.notificationSound;
   });

src/main/lifecycle/first-run.ts

@@ -7,6 +7,10 @@ import { APPLICATION } from '../../shared/constants';
 import { logError } from '../../shared/logger';
 import { isMacOS } from '../../shared/platform';
 
+/**
+ * On first launch, write the first-run marker file and prompt macOS users
+ * to move the app to the Applications folder. No-ops on subsequent launches.
+ */
 export async function onFirstRunMaybe() {
   if (isFirstRun()) {
     await promptMoveToApplicationsFolder();
@@ -38,6 +42,9 @@ async function promptMoveToApplicationsFolder() {
   }
 }
 
+/**
+ * Returns the absolute path to the first-run marker file in the user data directory.
+ */
 const getConfigPath = () => {
   const userDataPath = app.getPath('userData');
   return path.join(userDataPath, 'FirstRun', APPLICATION.FIRST_RUN_FOLDER);

src/main/utils.ts

@@ -9,10 +9,18 @@ import type { Menubar } from 'menubar';
 import { APPLICATION } from '../shared/constants';
 import { logError, logInfo } from '../shared/logger';
 
-export function isDevMode() {
+/**
+ * Returns true when the app is running in development mode (i.e. not packaged).
+ */
+export function isDevMode(): boolean {
   return !app.isPackaged;
 }
 
+/**
+ * Capture the current window contents and save a PNG file to the user's home directory.
+ * The filename includes an ISO timestamp and the application name.
+ * @param mb - The menubar instance whose window is captured.
+ */
 export function takeScreenshot(mb: Menubar) {
   const date = new Date();
   const dateStr = date.toISOString().replaceAll(':', '-');
@@ -28,6 +36,10 @@ export function takeScreenshot(mb: Menubar) {
   });
 }
 
+/**
+ * Open the directory containing the application log file in the OS file manager.
+ * Logs an error if the log file path cannot be resolved.
+ */
 export function openLogsDirectory() {
   const logFilePath = log.transports.file?.getFile()?.path;