usecase_forge_devtools 0.1.0-dev.5

DevTools extension and protocol models for inspecting UseCase Forge applications.

UseCase Forge DevTools

Russian translation

English is the primary language of the ecosystem. README.ru.md is a supplementary Russian translation.

A read-only DevTools extension for applications built with usecase_forge. It shows active UseCase instances, queue and processing positions, current snapshots, bounded terminal history, lifecycle events, cancellations, command rejections, and error-handler routes.

Pre-release: the protocol and UI may change before 1.0. Pin the version and read the changelog before upgrading.

The inspected application needs no initialization call, and installing the extension does not add Flutter to its runtime dependencies. Core reports through dart:developer in supported non-product Dart VM runs. The extension itself is installed as a development dependency.

Installation

dev_dependencies:
  usecase_forge_devtools: ^0.1.0-dev.5

dart pub add --dev usecase_forge_devtools:^0.1.0-dev.5

Declare usecase_forge as a direct dependency when application code imports core APIs.

Opening the extension

1. Resolve the application's development dependencies.
2. Start the Dart or Flutter application in a non-product mode with a VM service connection available.
3. Open DevTools from the IDE or connect DevTools to that VM service.
4. Select the UseCase Forge extension tab.

A separate initialize() call is not required. DevTools discovers the extension from the application's development dependencies.

Product and release builds do not expose this diagnostic channel. It is a development tool, not a production monitoring service.

What the screen shows

For every live UseCase, the extension can show:

• the runtime type and an optional application-defined label;
• registered exact command types;
• the current State snapshot and lifecycle phase;
• Admission, Pending, Starting, Processing, and Finalizing positions;
• terminal history with completed, failed, cancelled, and terminated results;
• rejected commands and rejection reasons;
• cancellation events;
• whether an error was handled by the command registration or continued to the global UseCase.onError flow.

The extension is read-only. It cannot add a command, cancel an execution, change State, replay work, or modify queue policies.

Privacy by default

Core sends technical metadata automatically, but hides application values by default:

• State contents;
• command fields;
• execution keys;
• cancellation and rejection details;
• error objects;
• stack traces.

This prevents an installed development tool from automatically turning tokens, personal data, or business objects into display text.

To reveal selected safe fields, import the secondary core library:

import 'package:usecase_forge/diagnostics.dart';

Then its UseCase mixes in UseCaseDiagnosticsDataProvider and returns only JSON-safe data that may be shown:

final class CartUseCase extends UseCase<CartState>
    with UseCaseDiagnosticsDataProvider {
  // Normal command registration is omitted.

  @override
  String get useCaseDiagnosticLabel => 'Shopping cart';

  @override
  Object? encodeUseCaseDiagnosticValue(
    UseCaseDiagnosticValueKind kind,
    Object? value,
  ) {
    if (kind == UseCaseDiagnosticValueKind.state && value is CartState) {
      return <String, Object?>{'itemCount': value.itemCount};
    }
    return null;
  }
}

Returning null keeps a value hidden. Core validates and bounds returned data. A formatter failure cannot fail a command, enter terminal history, or call the business UseCase.onError.

Compatibility

Core and DevTools exchange versioned protocol messages. A compatible protocol major version is required; unknown fields may be ignored so compatible minor additions do not break the whole screen.

Keep usecase_forge and usecase_forge_devtools on versions declared compatible by their release notes. Isolates with malformed diagnostic data or an incompatible protocol are omitted from the overview. If the connected screen remains empty, check both the VM build mode and package compatibility.

Troubleshooting

The tab is not visible

• Confirm that usecase_forge_devtools is in dev_dependencies of the application being inspected, not only in another package.
• Resolve dependencies again and restart both the application and DevTools.
• Confirm that the current DevTools build supports extensions.
• Confirm that the packaged directory contains extension/devtools/config.yaml and the compiled build directory.

The tab is visible but not connected

Connect DevTools to the VM service of the running application. Opening the compiled extension's index.html directly with a file:// URL is not a supported launch method: the extension expects the DevTools host and its connection APIs.

The screen is connected but has no UseCases

• Run a debug or other non-product VM build.
• Confirm that the application uses a compatible core version.
• Create at least one UseCase; disposed instances are removed from the live overview.
• Check whether the VM service connection was replaced after an application restart.

State or error details say hidden

That is the expected default. Add a diagnostics formatter only for values that are safe to display. Do not expose credentials, tokens, personal data, complete HTTP payloads, or unrestricted toString() output.

The source changed but the UI did not

The published package contains a compiled web build. Changing the sibling Flutter source does nothing until the extension is rebuilt, validated, and copied into extension/devtools/build.

Development layout

The publishable usecase_forge_devtools package contains:

• the DevTools extension manifest;
• shared protocol models;
• the compiled web extension.

Flutter source lives in the sibling, non-published usecase_forge_devtools_extension package. Its dependencies devtools_extensions and devtools_app_shared therefore do not become runtime dependencies of core or of an inspected production application.

The compiled assets are larger than the protocol library because Flutter web includes rendering and framework code. They increase the development package download, not the production application's runtime dependency graph.

Project and publisher

• Package documentation
• UseCase Forge product site
• GitLab repository
• Issue tracker
• Flutter source workspace

This package is created and maintained by Petr Orlov and published through the verified ArkTelos publisher. For package and ecosystem questions, contact [e-mail] or use the protected ArkTelos contact form.

License and bundled code

UseCase Forge DevTools is licensed under the Apache License, Version 2.0. Copyright 2026 Orlov Petr Petrovich. See LICENSE and NOTICE.

The compiled extension includes third-party Flutter and Dart code under its own licenses. The generated extension/devtools/build/assets/NOTICES must be rebuilt after a dependency or license change and must not be edited manually.

The build also contains fallback_root_certificates under MPL 2.0. A distributed build must preserve the MPL notice and tell recipients where the corresponding source is available. This does not change the Apache 2.0 license of UseCase Forge code.

The current build uses Dart 3.12.2. The corresponding source for fallback_root_certificates is available from the Dart SDK repository. Update this link when rebuilding the extension with a different Dart SDK revision.