<!-- SPDX-FileCopyrightText: 2026 FocusFlow contributors -->
<!-- SPDX-License-Identifier: AGPL-3.0-only -->

# ADHD Scheduler Workspace

SQLite-first Dart workspace for the ADHD scheduler backend, persistence
adapters, notifications, exports, backups, integration tests, and CI scripts.

## Local Workflow

Set up the workspace and local SQLite path:

```sh
scripts/bootstrap_dev.sh
```

Run the local app during development:

```sh
scripts/dev.sh
```

Run the full local quality gate:

```sh
scripts/test.sh
```

The test gate runs analyzer, tests with coverage, combines LCOV output, and
fails below 80% package `lib/` coverage.

Package a local desktop release with the host toolchain:

```sh
scripts/package_release.sh --platform current --output build/releases
```

Equivalent Dart entry points:

```sh
dart run scripts/dev.dart
dart run scripts/build.dart --platform current --output build/releases
```

The dev script prints the SQLite path, starts `dart run build_runner watch`, and
launches Flutter desktop with `SCHEDULER_SQLITE_PATH` passed as a dart define.
Normal Flutter startup uses that SQLite file for scheduler state rather than
inserting seeded demo tasks.

Prerequisites:

- Dart stable SDK
- Flutter stable SDK with desktop support enabled
- platform desktop toolchain: Xcode for macOS, Visual Studio Build Tools for
  Windows, and Linux desktop build dependencies for Linux

Optional flags:

```sh
dart run scripts/dev.dart --device linux --sqlite /tmp/scheduler.sqlite
```

## Earthly Workflow

Earthly is the supported containerized build path going forward. It builds a
Linux desktop Flutter bundle and exports a runnable application under `builds/`.

Install prerequisites on the host:

- Earthly
- Docker or another Earthly-compatible container runtime

Set up the Earthly build image:

```sh
earthly +setup
```

Copy code and resolve Dart/Flutter dependencies inside Earthly:

```sh
earthly +code
```

Run all style and metadata checks:

```sh
earthly +lint
```

Build and package the runnable Linux desktop app:

```sh
earthly +build
```

Run lint, build, and package in one command:

```sh
earthly +all
```

Smoke-run the Earthly-built Linux desktop app under a virtual display:

```sh
earthly +run
```

Earthly outputs:

```sh
builds/focus_flow_linux_x64/
builds/focus_flow_linux_x64.zip
```

Useful focused lint targets:

```sh
earthly +format
earthly +dart-analyze
earthly +flutter-analyze
earthly +reuse
earthly +docs
earthly +pre-commit
```

## Flutter UI

The provisional UI app lives outside the root Dart workspace at
`apps/focus_flow_flutter` so backend package gates can stay Dart-only while the
Flutter foundation settles.

```sh
cd apps/focus_flow_flutter
flutter analyze
flutter test
```

## Packaging

```sh
scripts/package_release.sh --platform current --output build/releases
```

```sh
dart run scripts/build.dart --platform current --output build/releases
```

Packaging prerequisites:

- macOS: Flutter desktop support and Xcode; produces a `.app`
- Windows: Flutter desktop support, Visual Studio Build Tools, and `msix`
  package configuration available to `dart run msix:create`
- Linux: Flutter desktop support plus `appimage-builder` and
  `AppImageBuilder.yml`; produces an AppImage

Tagged CI runs upload release artifacts from `build/releases/`.