dart_minify #

dart_minify is a local, provider-agnostic codec for Dart and Flutter coding agents. It builds a semantic project index, packs only task-relevant context, accepts declaration-level edit operations, applies them atomically, and returns compact verification diagnostics.

It optimizes both directions of an agent exchange:

index -> pack -> agent edits -> apply -> verify -> repair pack

Source files remain ordinary Dart. dart_minify is not an obfuscator, does not call a model, and does not require a provider SDK.

Requirements #

• Dart SDK 3.9 or later
• A Dart or Flutter-shaped project for indexing
• Project tools such as Flutter or custom test commands only when selected by verification

The package itself is developed and tested with the Dart SDK; a Flutter SDK is needed only when a selected target-project verification command invokes it.

Install #

dart pub global activate dart_minify
dart-minify --help

From a checkout:

dart pub get
dart run bin/dart_minify.dart --help

Quickstart #

Start by checking the target project and building its local index:

dart-minify doctor --project-root /path/to/project
dart-minify index --project-root /path/to/project

Create a task-focused pack. Use --format compact for an agent exchange or --format json while inspecting an integration:

dart-minify pack \
  --project-root /path/to/project \
  --file lib/src/session.dart \
  --max-tokens 12000 \
  --format compact > /tmp/session.pack.dmp

Ask the agent to return protocol edit operations rather than rewritten files. Preflight the response before writing anything:

dart-minify apply \
  --project-root /path/to/project \
  --stdin \
  --dry-run < /tmp/session.edits.dmp

Apply the same validated response without --dry-run, then verify the affected closure:

dart-minify apply --project-root /path/to/project --stdin --analyze \
  < /tmp/session.edits.dmp
dart-minify verify --project-root /path/to/project

apply always parses planned Dart sources by default. Add --analyze to resolve the transitive affected closure in memory and reject newly introduced analyzer errors before the atomic commit; unrelated pre-existing errors do not block the edit.

The exact focus, budget, and verification options are listed by each command's --help output.

Commands #

Machine-readable output is written to stdout. Progress and logs are written to stderr, so packs and edit results can be piped safely.

Safety model #

• The Dart analyzer, rather than a handwritten scanner, drives source tokenization and parsing.
• Packs identify files and declarations with stable IDs, content hashes, and structural fingerprints.
• Edit resolution never falls back to line-number guessing.
• Missing, extra, stale, and deleted files are explicit protocol states.
• Every edit and affected path is validated before the first source write.
• apply --dry-run performs preflight without committing source changes.
• apply --analyze resolves planned sources and their indexed dependents in an in-memory overlay before committing.
• A stale or ambiguous edit is a conflict and requires a fresh pack.

Local indexes and session state live under .dart_minify/. Recoverable transaction journals use root-level .dart_minify.transaction.* files, while transaction-owned temporary and backup files are created beside their target files so replacement stays on the same filesystem. These local artifacts are ignored by Git and are not part of an agent pack unless selected data is explicitly encoded.

Protocol formats #

compact is a counted, checksummed, line-oriented envelope designed for model traffic. json is the canonical debugging and storage representation. Both decode to the same validated protocol models and support the same operations.

See Protocol v2 for document fields, edit operations, anchors, validation rules, and framing.

Agent integrations #

Adapters should stay thin: run the local commands, transmit the pack, require a protocol edit response, and pass that response back to apply. They should not translate the wire format into provider-specific edit semantics or write files on the model's behalf.

See Agent integration for a provider-neutral adapter contract and prompt preamble.

Upgrading from 0.1.x #

Version 0.2.0 removes minify, expand, lossy-build, apply-lossy, the build-runner builder, framed whole-file payloads, and .llm.* sidecars. There is no compatibility decoder for 0.1 maps or manifests.

Follow the 0.1.x to 0.2.0 migration guide before upgrading automated workflows.

Development #

dart format --output=none --set-exit-if-changed .
dart analyze
dart test
dart pub publish --dry-run

CI covers the minimum Dart SDK and latest stable Dart. Flutter target-project integration remains a separate fixture lane because this package itself is a pure Dart package.

Documentation #

• Protocol v2
• Agent integration
• Migration from 0.1.x
• Benchmark methodology

Limits #

• The core performs no network calls and chooses no model provider.
• Generated files remain owned by their generator unless an operation explicitly creates or deletes a file.
• Automatic semantic repair is out of scope; repair packs provide focused context for another explicit agent response.
• Compression statistics are estimates, not provider billing counts.