# WorkMuch

Copyright (c) 2011 Joseph Lisee. All rights reserved.

## License

WorkMuch is available under the MIT License. See [LICENSE](LICENSE) for the
license text and warranty disclaimer.

## About

WorkMuch records the active application, window title, and idle time at a
configurable sample rate. It is a Go application.

- Linux uses a pure-Go X11 backend for Xorg sessions.
- macOS uses native AppKit, Accessibility, and CoreGraphics APIs by default.

## Requirements

- Go 1.26 or later, as declared in `go.mod`. Go downloads the module
  dependencies recorded in `go.mod` and `go.sum` when the scripts run.
- On Linux, an accessible X11/Xorg session with `$DISPLAY` set. The backend
  uses the X11 Screen Saver extension through `github.com/jezek/xgb`; no
  X11 development package is required.
- On macOS, use the normal CGO-enabled Go toolchain so the native backend can
  link the system frameworks. The `macos-subprocess` fallback uses the system
  `osascript` and `ioreg` commands.

### macOS permissions

Accessibility permission lets the native backend obtain focused window titles.
Without it, a focused title can be unavailable. Run `./run.sh doctor` to see
the current permission and backend report.

The packaged macOS app supports Ventura 13 and later. It uses the main app
Login Item API for startup and must be installed at
`/Applications/WorkMuch.app`. See
[macOS installation and local releases](docs/explanations/macos-release.md) for
local signing, Gatekeeper, Accessibility, Login Item, update, and uninstall
instructions.

## Usage

Show the available commands and options:

```bash
./run.sh --help
```

Start the tray collector, which begins logging immediately:

```bash
./run.sh
```

The tray menu provides About, Status, and Quit. Normal tray collection and
`--no-tray` write daily worklogs under `~/.workmuch`.

Run the collector in the foreground without a tray:

```bash
./run.sh --no-tray
```

For manual QA, write CSV rows to standard output without creating a worklog or
error log:

```bash
./run.sh --qa-console
```

Build a local binary at `bin/workmuch`:

```bash
./build.sh
./bin/workmuch --help
```

Show the build version:

```bash
./bin/workmuch --version
```

Ordinary builds report `dev`. Release builds embed the calculated repository
version; published Linux builds use it in the GitHub Release and Debian
package. See
[Versioning](docs/explanations/versioning.md) for how the value is calculated,
validated, and embedded.

### Backends

`--backend auto` is the default. It selects `linux` on Linux and
`macos-native` on macOS. Select a supported backend explicitly when needed:

```bash
./run.sh --backend macos-subprocess --no-tray
```

`macos-subprocess` is a Go implementation and an explicit macOS fallback; it
does not require or invoke a separate collector. `macos-native` requires macOS
with CGO enabled, and `linux` requires Linux with an accessible X11 display.

See [Linux usage](docs/explanations/linux.md) for X11 diagnostics, Wayland
limitations, the CSV format, file locations, and privacy guidance.

## Debian packages

GitHub Releases provide Linux `.deb` packages for amd64 and arm64. Download the
package matching the machine architecture and install it with apt so local
dependencies are resolved:

```bash
sudo apt install ./workmuch_<version>_amd64.deb
```

The package globally enables a systemd user service. Each logged-in graphical
user runs their own unprivileged collector and writes only to their own
`~/.workmuch`. See
[Debian user service](docs/explanations/debian-service.md) for status, journal,
opt-out, and display-support commands. Packages are distributed directly
through GitHub Releases; WorkMuch does not provide an APT repository.

## Releases

Build one versioned Debian package locally for testing with:

```bash
./release.sh --local linux/amd64
```

Use `linux/arm64` for an arm64 package. Local builds use the version calculated
from the current commit and append `.dirty` when the worktree has tracked or
untracked changes. They include those source changes and write the selected
package to `dist/` without fetching, tagging, pushing, or creating a GitHub
Release. The pinned GoReleaser version is downloaded through the Go toolchain
when it is not already cached.

On macOS, build a locally signed universal app and DMG with:

```bash
export WORKMUCH_CODESIGN_IDENTITY="WorkMuch Local Code Signing"
./release.sh --local darwin/universal
```

This writes the DMG and its checksum under `dist/macos/`. The macOS artifact is
not uploaded automatically. It uses a persistent self-signed identity rather
than Developer ID signing or notarization; follow the dedicated macOS guide for
installation and Gatekeeper handling.

Maintainers create a release from a clean checkout with:

```bash
./release.sh
```

The script fetches full origin history and tags, runs tests and lint, calculates
the repository version, creates an annotated reproducibility tag, and pushes
it. The tag-triggered workflow publishes stable GitHub Releases containing the
amd64 and arm64 Debian packages plus checksums and generated release notes.

## Tests and lint

Run the unit tests:

```bash
./test.sh
```

Run formatting checks, `go vet`, and the full test suite:

```bash
./lint.sh
```