dart-monorepo-workspace

name: dart-monorepo-workspace description: > Workspace layout, fvm usage, correct working directories for commands, and inter-package dependency relationships for the Flutter-AdaptiveCards monorepo. Use this whenever running flutter/dart commands or navigating the project structure.

Dart Monorepo Workspace Skill

Repository Layout

Flutter-AdaptiveCards/           ← workspace root (pubspec.yaml declares workspace)
├── pubspec.yaml                 ← workspace manifest ONLY — no real package here
├── .fvmrc                       ← pins Flutter SDK version (fvm)
├── packages/
│   ├── flutter_adaptive_cards_fs/    ← MAIN LIBRARY (published to pub.dev)
│   ├── flutter_adaptive_charts_fs/        ← charting extension package
│   ├── flutter_adaptive_template_fs/      ← AdaptiveCard template merging package
│   └── flutter_adaptive_cards_host_fs/    ← backend invoke bridge (published to pub.dev)
├── adaptive_explorer/           ← desktop editor/preview app (not published)
└── widgetbook/                  ← widgetbook demo app (not published)

pubspec.yaml Workspace Declaration

name: _
publish_to: none
environment:
  sdk: ^3.10.4
workspace:
  - packages/flutter_adaptive_cards_fs
  - packages/flutter_adaptive_charts_fs
  - packages/flutter_adaptive_template_fs
  - packages/flutter_adaptive_cards_host_fs
  - widgetbook
  - adaptive_explorer

The root pubspec.yaml is not a real package. It exists solely to declare the workspace and lock shared transitive dependencies in pubspec.lock.

Flutter Version Management (fvm)

This project pins its Flutter SDK version with fvm.

# Use the pinned Flutter version for any command:
fvm flutter ...    # instead of plain `flutter`
fvm dart ...       # instead of plain `dart`

# Check which version is pinned:
cat .fvmrc

# Install the pinned version if it's missing:
fvm install

Important: Always use fvm flutter / fvm dart to ensure the correct SDK version. Antigravity MCP tools (mcp_dart-mcp-server_*) use the system Flutter, so prefer shell commands via fvm when SDK version matters.

Running Commands in the Correct Directory

Each package is an independent Flutter/Dart project. Run commands from the specific package directory, not the workspace root.

✅ Correct — from package directory:

cd packages/flutter_adaptive_cards_fs
fvm flutter test test/basic_test.dart

❌ Wrong — from repo root:

fvm flutter test packages/flutter_adaptive_cards_fs/test/basic_test.dart
# This may fail because asset resolution and test config depend on CWD

Inter-Package Dependencies

The sample apps depend on the library packages using path dependencies (resolved automatically by the workspace):

# adaptive_explorer/pubspec.yaml excerpt
dependencies:
  flutter_adaptive_cards_fs:
    path: ../packages/flutter_adaptive_cards_fs
  flutter_adaptive_template_fs:
    path: ../packages/flutter_adaptive_template_fs

# widgetbook/pubspec.yaml excerpt
dependencies:
  flutter_adaptive_cards_fs:
    path: ../packages/flutter_adaptive_cards_fs
  flutter_adaptive_charts_fs:
    path: ../packages/flutter_adaptive_charts_fs

Changes to a library package are immediately reflected in the apps without requiring a publish step — just hot reload or restart.

Dependency Graph

adaptive_explorer  ──► flutter_adaptive_cards_fs
                   ──► flutter_adaptive_template_fs
widgetbook         ──► flutter_adaptive_cards_fs
                   ──► flutter_adaptive_charts_fs
flutter_adaptive_charts_fs   ──► flutter_adaptive_cards_fs
flutter_adaptive_cards_host_fs ──► flutter_adaptive_cards_fs, http

Package Purposes

packages/flutter_adaptive_cards_fs — Core Library

• Published to pub.dev
• Parses and renders Adaptive Cards JSON as Flutter widgets.
• Entry points:
  • lib/flutter_adaptive_cards_fs.dart — public API (import this in consuming apps)
  • lib/flutter_adaptive_cards_extend.dart — extension API (import when creating custom elements)
• Contains: element widgets, containers, inputs, actions, HostConfig, registry.

packages/flutter_adaptive_charts_fs — Charts Extension

• Published to pub.dev
• Adds charting element types (isolates heavy chart dependencies).
• Registered via the extension API into a CardTypeRegistry.

packages/flutter_adaptive_template_fs — Template Package

• Published to pub.dev
• Implements AdaptiveCards template spec.
• Merges JSON data into an Adaptive Card template before rendering.

packages/flutter_adaptive_cards_host_fs — Backend Invoke Bridge

• Published to pub.dev (entry: lib/flutter_adaptive_cards_host_fs.dart)
• Optional serialize → POST → parse → apply pipeline for Submit/Execute/Refresh/onChange.
• Depends on flutter_adaptive_cards_fs and http.
• Docs: backend-host-integration.md.

adaptive_explorer — Desktop Editor/Preview App

• Not published
• macOS/Linux/Windows desktop app for editing and previewing Adaptive Card JSON.
• Uses file_watcher_service.dart to watch the JSON file on disk and live-reload the preview pane automatically.

widgetbook — Sample demonstration app

• Not published — example / sample program only; not described as package architecture in docs/ (see documentation-scope.md).
• Uses widgetbook.io to catalog card element types and host-callback demos.
• Overlay knob demos: docs/widgetbook-overlay-demos.md.
• Use cases defined in lib/adaptive_cards_use_cases.dart.
• Sample JSON lives under lib/samples/; AdaptiveCardsCanvas.asset loads paths from the Flutter asset bundle.
• New sample directories: add a line under flutter: assets: in widgetbook/pubspec.yaml for every new folder under lib/samples/ (for example lib/samples/v1.4/). Without this registration, asset loads fail at runtime even when the JSON file exists on disk.
• Generated file: lib/main.directories.g.dart — re-generate with:

  cd widgetbook
  fvm dart run build_runner build
  

Analysis and Linting

Each package has its own analysis_options.yaml. The project uses very_good_analysis as the base linting ruleset:

include: package:very_good_analysis/analysis_options.yaml

Run analysis from the root to cover all packages at once:

fvm flutter analyze

Changelog Updates

Whenever you make changes to a package or app:

1. Always document changes under the current top ## [<version>] section in that package's CHANGELOG.md (and in adaptive_explorer / widgetbook changelogs when those apps change).
2. During a development cycle, edit the existing top section; do not add a second heading for the same version.

After a release is published to pub.dev, follow the release-engineer skill §6: minor version bump across all pubspec.yaml files, new ## [<version>] sections in all six changelogs, and flutter_adaptive_cards_fs: ^<version> in flutter_adaptive_charts_fs and flutter_adaptive_cards_host_fs.

Pub Commands Reference

# Add a runtime dependency to main library
cd packages/flutter_adaptive_cards_fs
fvm flutter pub add some_package

# Add a dev dependency
fvm flutter pub add dev:some_dev_package

# Remove a dependency
fvm dart pub remove some_package

# Check outdated dependencies across all packages
# (run from each package directory)
fvm flutter pub outdated