# schmeeve-toolz — Agent Guide

Personal macOS automation toolkit deployed to `~/Dropbox/bin/`. Mostly shell scripts for power management, network, and system automation, triggered by Keyboard Maestro and cron.

## Commands

No build/test/deploy infrastructure exists. Scripts run directly:

```sh
./scriptname          # run any script directly
chmod +x scriptname   # scripts should already be executable
```

Scripts are deployed by copying (or symlinking) to `~/Dropbox/bin/`. There is no install step.

Check shebang (`#!/bin/sh` or `#!/bin/bash`) before running — some use bashisms like `[[ ]]` and arrays.

## Language & Style

| Aspect | Convention |
|---|---|
| **Shell** | `#!/bin/bash` for complex scripts, `#!/bin/sh` for simple one-liners. Mix of both. |
| **Python** | `#!/usr/bin/python3` for mail helpers. Hardcoded SMTP config block at top. |
| **AppleScript** | Compiled `.scpt` files (binary — cannot view as text). Shell scripts invoke via `/usr/bin/osascript`. |
| **Indentation** | Inconsistent across codebase. 2-space dominant but no enforced standard. |
| **Naming** | `lowercase-with-hyphens` for scripts. `UPPER_CASE` for config constants, `lower_case` for locals. |
| **Functions** | `name() {` syntax (rarely used). |
| **Quoting** | Inconsistent. Many older scripts use bare `$var`. Newer scripts use `"${var}"`. Assume unquoted vars will break on spaces. |

## Architecture

### What it is

A flat collection of ~60+ standalone scripts organized by function, NOT a structured project. No packages, no modules, no dependencies file.

### How scripts relate

```
presleep ──→ presleep_quitapps ──→ send_quitbrowsers_mail3.py
    │                                        │
    └──── send_sleep_mail3.py                (sends email)
    
idlecheck ──→ idlecheck_tasks ──→ idlecheck_quitvideowake
                  │              ──→ idlecheck_quitaudioprevent
                  └──── idlecheck_caffeinatestuck
    
wakenotify ──→ wakelogstart / wakelogend
    
sleep ──→ idlecheck_caffeinatestuck
    
pull-all ──→ iterates repos in ~/git/ matching *schmeeve* remote
checkin-all ──→ iterates repos in ~/git/ matching *schmeeve* remote
```

Sub-scripts are invoked via `/bin/bash` or `/bin/sh`, never sourced.

### Trigger chain

1. **Keyboard Maestro** (macros) — most common trigger. Evidence: `$KMINFO_MacroName` env var used in email subjects, `dactoggle` bound to hotkey.
2. **cron/launchd** — likely for `checkin-all`, `pull-all`, maintenance scripts.
3. **pmset schedule** — `wakenotify` and `maintwakes` are scheduled via `pmset repeat`.

### Power management flow

```
[Keyboard Maestro / cron / pmset schedule]
    │
    ▼
presleep / sleep / idlecheck / shutdown_safe / wakenotify
    │
    ├── pmset (sleep, assertions, schedule)
    ├── osascript (quit apps, shutdown)
    ├── HomeKit URL scheme (smart home)
    └── Python mailer (status email via SMTP)
```

## Gotchas & Non-Obvious

### Hardcoded paths

- `/Users/shughey/Dropbox/bin/` is hardcoded in many scripts (`sleep`, `presleep`, `wakenotify`, `idlecheck_tasks`, `maintwakes`). Will break on a different user's machine. Use `$HOME` when adding references.
- `/Users/shughey/git/` is hardcoded in `checkin-all` and `pull-all`.
- `/Usres/shughey/` (typo) exists in `Angus/tdarr-bounce` — affects the `Angus` machine only.

### Machine-specific branching

Several scripts branch on `scutil --get ComputerName` output:
- `dactoggle` — branches on `Angus` vs `Petula` vs `Callum` for HomeKit tokens.
- `presleep_quitapps` — same pattern.

Add new branches when adding machine-specific behavior.

### Authentication tokens in scripts

HomeKit x-callback-url tokens are **hardcoded** in `dactoggle` and `presleep_quitapps`. These are auth tokens for homecontrol.d27n.com. Do not commit to public repos.

### Email pipeline

All mail scripts:
1. Read `$ESUBJ` env var for subject (set by Keyboard Maestro)
2. Compute `CNAME` from `platform.node()` (Python) or `scutil --get ComputerName` (shell)
3. Send via `emailz.d27n.com:587` with hardcoded credentials

### Deprecated patterns to avoid

- `` `backtick command substitution` `` — use `$( )` instead
- `$[ arithmetic ]` — use `$(( ))` instead
- Bare `$var` without quotes — use `"${var}"`
- `export PATH=$PATH:/usr/bin/local` — `/usr/bin/local` doesn't exist on standard macOS (typo for `/usr/local/bin`)

### Risk zones (pmset)

These commands are **destructive** if run unintentionally:
- `pmset schedule cancelall` — wipes all scheduled sleep/wake events
- `pmset repeat cancel` — wipes recurring schedule
- `osascript -e 'tell application "System Events" to shut down'` — immediate shutdown
- `pmset sleepnow` / `pmset displaysleepnow` — immediate sleep

### Cloud sync artifacts

Conflicted copies from iCloud/Google Drive exist throughout the repo (`displaycount (Callum.local's conflicted copy YYYY-MM-DD).scpt`, `main (host's conflicted copy).scpt` inside `.app` bundles). These are stale and can be cleaned up.

### sudo requirements

Some scripts reference `sudo pmset ...` which requires `NOPASSWD` in sudoers (e.g., `/etc/sudoers.d/shughey`). Not portable.

### macOS-specific commands

All scripts depend on macOS-only commands:
- `pmset` — power management
- `scutil` — system config (ComputerName)
- `sw_vers` — macOS version
- `osascript` — AppleScript bridge
- `log show --style syslog` — unified logging
- `diskutil` — disk management
- `networksetup` — network config
- `sips` / `iconutil` — image processing (makeicns)
- `hdiutil` — disk images (bootableBigSur)

### arc-export subproject

`arc-export/` is a vendored third-party tool (from [ivnvxd/arc-export](https://github.com/ivnvxd/arc-export)) — converts Arc Browser pinned tabs to HTML bookmarks. Has its own MIT license. Don't modify unless fixing bugs.

### Test data files

- `wakemaints.txt` — maintenance window config (read by `maintwakes`)
- `test-caffeinate.txt` — test data for caffeinate detection
- `test.sh` — sanity check/test script
- `.nova/Configuration.json` — Nova editor config (sets default syntax to shell)

## .app Bundles

Two AppleScript `.app` bundles follow this structure:

```
*.app/
  Contents/
    Info.plist         # CFBundleExecutable=applet, CFBundlePackageType=APPL
    PkgInfo            # "APPLaplt"
    MacOS/applet       # Compiled runtime binary
    Resources/
      applet.icns      # Icon
      applet.rsrc      # Resource fork
      Scripts/main.scpt # The actual AppleScript (compiled binary)
    _CodeSignature/    # (unmount-cli only)
```

## What NOT to do

- Don't add comments to scripts unless the user asks. Many scripts have minimal or no comments.
- Don't fix inconsistent quoting/indentation across the codebase — it's a personal toolkit, not a shared project.
- Don't assume `set -euo pipefail` exists — only `checkin-all` and `pull-all` use it.
- Don't run `pmset schedule cancelall` or `pmset repeat cancel` unless explicitly asked.
- Don't commit changes without user confirmation (per agent rules).