# Instructure Agent

A macOS status bar application built with Electron that runs as a background agent with no dock icon.

## Features

- **Status Bar Integration**: Lives in the macOS menu bar with a clean, native interface
- **Background Agent**: Runs in the background without appearing in the dock
- **Global Shortcuts**: Access functionality from anywhere with keyboard shortcuts
  - `Option+Space` - Open action (configurable)
- **Settings UI**: React-based settings window for configuration
- **Auto-Updates**: Built-in update mechanism using Squirrel.Mac
- **Persistent Settings**: Settings stored locally using electron-store
- **Reactive Architecture**: Uses RxJS for reactive state management

## Technology Stack

- **Electron** v28+ - Cross-platform desktop framework
- **TypeScript** - Type-safe development
- **React** - Settings UI
- **RxJS** - Reactive programming
- **Vite** - Fast bundling and dev server
- **electron-store** - Persistent settings storage
- **electron-updater** - Auto-update functionality

## Project Structure

```
instructure-agent/
├── src/
│   ├── main/              # Main process (Electron backend)
│   │   ├── index.ts       # App entry point
│   │   ├── tray.ts        # Status bar management
│   │   ├── menu.ts        # Menu with shortcuts
│   │   ├── settings-window.ts  # Settings window
│   │   ├── shortcuts.ts   # Global shortcuts
│   │   ├── updater.ts     # Auto-update logic
│   │   └── store.ts       # Settings storage
│   ├── renderer/          # Renderer process (React UI)
│   │   ├── settings/      # Settings window
│   │   └── types.ts       # Shared types
│   ├── preload/           # Preload scripts (IPC bridge)
│   └── assets/            # Icons and resources
├── build/                 # Build resources
└── dist/                  # Compiled output
```

## Getting Started

### Prerequisites

- Node.js 18+ and npm
- macOS (for development and testing)

### Installation

1. Install dependencies:
```bash
npm install
```

2. Start development mode:
```bash
npm run dev
```

This will:
- Compile the main process and watch for changes
- Start Vite dev server for the renderer process
- You'll need to run `npm start` in another terminal to launch Electron

3. Start the application:
```bash
npm start
```

### Development Workflow

1. **Main Process Development**:
   - Edit files in `src/main/`
   - Run `npm run dev:main` to watch and recompile
   - Restart Electron to see changes

2. **Renderer Process Development**:
   - Edit files in `src/renderer/`
   - Run `npm run dev:renderer` to start Vite dev server
   - Changes will hot-reload automatically

3. **Concurrent Development**:
   ```bash
   npm run dev  # Runs both main and renderer in watch mode
   ```

## Building

### Build for production:
```bash
npm run build
```

### Package for macOS:
```bash
npm run package:mac
```

This creates distributable packages in the `release/` directory:
- `.dmg` - Disk image installer
- `.zip` - Compressed app bundle

### Package specific formats:
```bash
npm run package:mac:dmg  # DMG only
npm run package:mac:zip  # ZIP only
```

## Configuration

### Settings

Settings are stored in:
```
~/Library/Application Support/instructure-agent/settings.json
```

Available settings:
- `openShortcut` - Global shortcut for open action (default: "Alt+Space")
- `autoUpdate` - Enable automatic updates (default: true)

### Icons

Replace placeholder icons in `src/assets/icons/`:
- `tray-icon.png` - 22x22px for menu bar
- `tray-icon@2x.png` - 44x44px for Retina displays

Create app icon at `build/icon.icns` for the packaged application.

See `src/assets/icons/README.md` and `build/README.md` for details.

## Architecture

### Main Process
- `index.ts` - Orchestrates app lifecycle and component initialization
- `tray.ts` - Manages status bar icon and menu
- `menu.ts` - Defines menu structure with shortcuts
- `settings-window.ts` - Manages settings window lifecycle
- `shortcuts.ts` - Registers and manages global keyboard shortcuts
- `updater.ts` - Handles auto-update checks and notifications
- `store.ts` - Manages persistent settings with RxJS observables

### Renderer Process
- React-based UI for the settings window
- Three tabs: General, Shortcuts, About
- Communicates with main process via IPC through preload script

### IPC Communication
The preload script (`settings-preload.ts`) exposes a safe API:
- `window.settingsAPI.getSettings()` - Get all settings
- `window.settingsAPI.setSetting(key, value)` - Update a setting
- `window.settingsAPI.getVersion()` - Get app version

## Security

- Context isolation enabled
- Node integration disabled in renderer
- IPC communication through secure contextBridge API
- Hardened runtime enabled for macOS builds

## Logs

Logs are written to:
- **macOS**: `~/Library/Logs/instructure-agent/main.log`

Log levels:
- Console: debug
- File: info

## Updating

The app checks for updates:
- On startup
- Every 6 hours

Updates can be disabled in Settings. Update server URL is configured in `package.json` under `build.publish.url`.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

## Troubleshooting

### App doesn't appear in menu bar
- Check console logs for tray creation errors
- Ensure icon files exist in `src/assets/icons/`

### Global shortcuts not working
- Check if shortcuts are already registered by another app
- View logs for registration errors
- Try different key combinations in settings

### Settings window doesn't open
- Check if Vite dev server is running (in development)
- Check console logs for errors
- Ensure preload script compiled correctly

### Build fails
- Ensure all dependencies are installed
- Check that TypeScript compilation succeeds
- Verify icon files exist (or remove icon references temporarily)

## License

MIT
