focus-flow/README.md

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:

scripts/bootstrap_dev.sh

Run the local app during development:

scripts/dev.sh

Run the full local quality gate:

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:

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

Equivalent Dart entry points:

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:

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:

earthly +setup

Copy code and resolve Dart/Flutter dependencies inside Earthly:

earthly +code

Run all style and metadata checks:

earthly +lint

Build and package the runnable Linux desktop app:

earthly +build

Run lint, build, and package in one command:

earthly +all

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

earthly +run

Earthly outputs:

builds/focus_flow_linux_x64/
builds/focus_flow_linux_x64.zip

Useful focused lint targets:

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.

From the repository root, start the desktop UI with the default local SQLite database:

scripts/bootstrap_dev.sh
cd apps/focus_flow_flutter
flutter pub get
flutter run -d linux

Replace linux with macos or windows on those hosts. Use flutter devices to list available device IDs. If Flutter reports that the desktop project is not configured for that platform, generate the missing runner from apps/focus_flow_flutter:

flutter create --platforms=linux .

Use --platforms=macos or --platforms=windows for those hosts.

For a disposable dev database, pass an explicit SQLite path:

flutter run -d linux --dart-define=SCHEDULER_SQLITE_PATH=/tmp/focus_flow_dev.sqlite

The default database path is ~/ADHD_Scheduler/scheduler.sqlite. To reset local UI data, close the app and delete the SQLite file you used.

cd apps/focus_flow_flutter
flutter analyze
flutter test

Packaging

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

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/.