halkyon-days/halkyon
Watch
1
0
Fork
You've already forked halkyon
 0
Code Issues Pull requests Projects Releases 37 Packages Wiki Activity Actions
halkyon/AGENTS.md
Tizian 「ティツィアーン」 e17d99fa51
 chore: scaffold the Serverpod 4 build 
Deviations from a stock `serverpod create`:
- Dropped Flutter web support, for two reasons:
  - Appflowy editor had issues in the past, potentially related to the
    Flutter-Web IME bridge. Upstream has also open bugs in relation to
that:
    - AppFlowy-IO/appflowy-editor#1029 [Bug][Web] Unwanted space on click
       and overall space bugs (open)
    - AppFlowy-IO/appflowy-editor#782 [Bug] Editor auto-scrolling when
       pressing space too quickly if placed inside a scrollable (open)
  - Offline-first is a required feature. serverpod_offline_sync's SQLite
    support in browsers, maybe via sqlite3.wasm + OPFS, is not
documented.
- SDK constraints raised to ^3.13.0, instead of ^3.12.2, so enjoy the
  newest language features.
- Pinned to Flutter 3.47.4 via FVM.

Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>
2026-09-24 15:32:29 +02:00

4.2 KiB
Raw Blame History

Flutter & Serverpod project

This project is a Flutter app (frontend) backed by a Serverpod server (backend). Always build the app's backend with Serverpod. Build for multiple users, use Serverpod's built-in authentication, which is already set up in lib/server.dart.

The user starts the server and Flutter app with serverpod start. There is no need to check if the server is running: make the changes and call the serverpod MCP tools as needed. If the server is not running, an informative error message will be received from the MCP server. Then STOP and ask the user to start it. NEVER start the server yourself. The Flutter app is started along with it, or can be launched from the MCP tool spawn_flutter_app.

While running, serverpod start watches for file changes to run incremental code generation and hot reload both the server and the Flutter app.

Calling serverpod generate directly is not needed, but might be useful to troubleshoot when an incremental generation fails.

ALWAYS use the MCP server instead of the command line. Use the MCP server to:

  • create_migration and apply_migrations for database (after you change data models).
  • create_repair_migration if the database has drifted out of sync with the migrations.
  • tail_server_logs to read logs from the server.
  • tail_flutter_logs to read the raw stdout/stderr of the Flutter app.
  • hot_reload / hot_restart to reload or restart the server and the Flutter app. ALWAYS call hot_restart after doing changes in the Flutter app that may not work with normal hot reload (which is automatically applied).
  • spawn_flutter_app to start a Flutter app declared under serverpod: flutter_apps: in the server pubspec.yaml.
  • get_flutter_app_dtd (Dart tooling daemon) for connecting to the app through the dart MCP.

NEVER edit generated code. The server's lib/src/generated/ directory and the whole halkyon_learn_client package are rewritten by the code generator. Change the .spy.yaml models, the endpoints, or lib/server.dart instead.

Migrations are a narrow exception: the migration.sql of a generated migration MAY be edited by hand when the generated SQL would lose data — to add a data transformation, or to reach a destructive change through non-destructive steps. Never touch the other files in the migration directory, and keep the schema the SQL ends up with identical to definition.sql — new databases are created from that file and never run migration.sql.

Only when the server cannot be started at all, fall back to the CLI in the server package:

  • serverpod generate to regenerate the client and the generated server code.
  • serverpod create-migration after changing a model with a table (add --force for destructive changes). It only writes the migration; serverpod start applies pending migrations when it boots the server.

Tests need no Docker. config/test.yaml sets database.dataPath, so Serverpod starts and manages the test database (an embedded PostgreSQL) itself, and the project's docker-compose.yaml is not used for it. Just run dart test in the server package.

Checklist after doing changes, in this order:

  • dart analyze (CLI)
  • dart format (CLI)
  • create_migration and apply_migrations (MCP - only if necessary)
  • Do serverpod MCP hot_restart if required (hot reload is done automatically). Will also hot restart Flutter app
  • Run tests, if applicable (dart test in the server package)
  • Check serverpod MCP tail_server_logs and tail_flutter_logs for any issues.

If the user asks you to test the app:

  1. Use get_flutter_app_dtd (serverpod MCP) to get the Flutter app's DTD
  2. Pass the DTD to connect_dart_tooling_daemon (dart MCP) to connect to the app
  3. Use flutter_driver (dart MCP) to navigate through the app

The app is launched from halkyon_learn_flutter/lib/driver.dart, which starts the Flutter driver extension with text entry emulation turned off so the app stays usable by hand. To let the driver type, set enableTextEntryEmulation: true there and hot_restart the app.

IMPORTANT: After building the first version of the app, update this AGENTS.md file with information about the app we're building. KEEP the info about the MCP server and the checklist. Remove this paragraph.