arcle 3.0.0

arcle: ^3.0.0 copied to clipboard

Network Ecosystem (Dio & Http) #

• Interactive Network Selection: During project creation (arcle create / arcle init), developers are prompted to select their preferred network ecosystem across all state management choices (BLoC, GetX, Riverpod):
  • 1. Dio (recommended)
  • 2. Http (powered by http: ^1.6.0)
• Added --network / -n flag (dio or http) to arcle create and arcle init for non-interactive / CI automation.
• Full package:http 1.6.0 client integration (ApiHttpClient):
  • GET, POST, PUT, PATCH, DELETE operations.
  • Native request cancellation via AbortableRequest and AbortableMultipartRequest.
  • Multipart file upload support.
  • File download with real-time download progress tracking.
  • Unified ApiResponse wrapper matching status code and response payloads.
• State-aware dependency injection configuration for both DioClient and ApiHttpClient (BLoC get_it, GetX bindings, Riverpod providers).

Unified Error & Response Handling #

• Actively wired BaseResponse and ResponseHandler into project generation for both Dio and Http networking pipelines.
• Error messages are surfaced through AppDialogs (lib/core/utils/dialogs.dart) directly from AppFailure:
  • Error messages and retry prompts display clean dialogs (AppDialogs.showError and AppDialogs.showRetry).
  • Success actions display a 2-second snackbar notification (AppDialogs.showSuccess).
  • Technical error messages and raw traces are intercepted and mapped into user-friendly messages via AppFailure.

Application Branding & Versioning #

• ARCLE version banner: The CLI intro banner now displays ARCLE Version : 3.0.0 instead of ARCLE-FLUTTER CLEAN ARCHITECTURE.
• Project naming in constants: Generated lib/core/utils/constants.dart now includes static const String appName = '<project_name>'; in AppConstants.
• MaterialApp widget now consumes title: AppConstants.appName with import 'package:<project_name>/core/utils/constants.dart'; across BLoC, GetX, and Riverpod templates.

Breaking Changes — Clean Architecture & Core Restructure #

This release replaces the unpublished 2.4.0 line entirely because it changes generated project structure and import paths; anyone who already generated a project against the unpublished 2.4.0 templates needs to regenerate or manually migrate.

• Data sources no longer parse response bodies. Previously, ${Feature}RemoteSource/${Feature}RemoteDataSource classes (in arcle feature <name> output) called Model.fromJson(...) directly on the raw API response, which put domain-shape knowledge in the transport layer and bypassed BaseResponse entirely. Data sources now only call the API and wrap the raw response in BaseResponse (Future<BaseResponse<dynamic>> fetchData()); the repository impl class is the only place that calls Model.fromJson on BaseResponse.data and maps to an entity. This matches the clean-architecture rule that transport and domain-model parsing are separate responsibilities.
• BaseResponse and ResponseHandler merged into one file (lib/core/network/base_response.dart). ResponseHandler previously reimplemented its own ad-hoc envelope detection (checking data/result/payload keys, manual success checks) instead of using BaseResponse.fromJson, so two independent, partially-overlapping response-shape parsers existed in the same project. ResponseHandler now builds a BaseResponse first and derives success/failure/data from it — response-shape normalization lives in exactly one place.
• Removed the unused ErrorHandler class and core/error_handler/ folder. It was generated into every project but never referenced anywhere outside its own definition file; presentation code already calls AppDialogs directly off the AppFailure returned by result.fold(...).
• core/ folder consolidation — new projects now generate:
  • core/network/ — api_service.dart, http_client.dart/dio_client.dart, base_response.dart (incl. merged ResponseHandler), api_failure.dart, result.dart (replaces core/api_client/, core/response_handler/, and core/utils/result.dart)
  • core/services/ — session_manager.dart, pref_manager.dart, notification_service.dart, permission_service.dart (replaces core/session_manager/, core/notifications/, core/permissions/)
  • core/theme_manager/ — app_theme.dart, app_colors.dart, dimensions.dart (renamed from core/theme_handler/, now also owns colors and spacing since they're one "how things look" concern)
  • core/di/, core/env/, core/localization/, core/route_handler/, core/common_widgets/, core/utils/ are unchanged.

Documentation & Work Tracking #

• arcle create, arcle init, and arcle configure-ai now seed a root docs/PLAN.md and docs/HISTORY.md for whole-project planning and a chronological work log.
• arcle feature <name> now generates lib/features/<name>/docs/<name>_plan.md and lib/features/<name>/docs/<name>_history.md — keeping each feature's docs grouped in a docs/ folder while still naming the files after the feature, so it stays obvious which feature a file belongs to.
• Added arcle history add --summary "<text>" [--feature <name>] [--agent claude|codex|gemini|human] to append work-tracking rows to root docs/HISTORY.md and, when --feature is given, to that feature's docs/HISTORY.md too.
• arcle configure-ai now writes the work-tracking rule into CLAUDE.md, .codex/instructions.md, and GEMINI.md, instructing agents to run arcle history add after finishing a unit of work, and allow-lists arcle history add in the generated Claude Code settings.json.
• Generating a feature now automatically logs a "Feature scaffolded" entry to root docs/HISTORY.md so project history stays accurate even without AI involvement.

Theme System Improvements #

• Generated AppTheme now covers checkboxTheme, radioTheme, switchTheme, textButtonTheme, dialogTheme, bottomSheetTheme, floatingActionButtonTheme, progressIndicatorTheme, tabBarTheme, tooltipTheme, and textSelectionTheme for both light and dark modes, all driven from AppColors.
• Button styles now define disabledBackgroundColor/disabledForegroundColor so disabled states are theme-driven instead of hardcoded per widget.
• CommonButton, CommonTextField, CommonDropdown, CommonCheckbox, CommonSnackbar, CommonAppBar, and CommonBottomSheet no longer hardcode fallback colors (Colors.blue/grey/white/red/green) — they now inherit from AppTheme/AppColors by default while still accepting optional per-call overrides.
• CommonDropdown is now built on DropdownButtonFormField, so it automatically shares the same inputDecorationTheme styling as CommonTextField instead of rendering unstyled.
• Result: editing lib/core/utils/app_colors.dart now cascades consistently through every common widget, in both light and dark mode, without further per-widget edits.

CLI Cleanup #

• Removed a large block of dead, unreferenced template code from core_templates.dart, including a duplicate/outdated AppTheme implementation that used deprecated MaterialStatePropertyAll APIs and was never wired into project generation.

Improvements #

• Feature generation now creates only <feature>_plan.md and <feature>_history.md inside each feature module.
• arcle build apk now supports debug/staging, release/production, or both builds with interactive version selection and environment-aware APK names.
• Added arcle organize imports to convert project-relative imports to full package: imports, remove duplicates, and sort imports. Use --check to preview changes.
• arcle review now runs the complete review workflow by default: analyze, format, missing-test scan, tests with coverage, and AI review when configured.
• arcle verify now runs all verification checks by default, including feature structure, assets, localization, code generation, and 16 KB APK validation.
• Added automatic command reports at docs/report.md; the docs directory is created when necessary, with separate review and verify report content.
• API logging now prints one focused request record containing only the full URL, endpoint, request body, and response body with highlighted labels.
• Updated generated Dio API signatures to use explicit generic types such as Response<dynamic>, preventing strict-raw-types warnings.

CLI Cleanup #

• Removed the arcle br and arcle bd APK shortcut commands in favor of the interactive arcle build apk workflow.
• Simplified README and CLI help examples so the main review and verification commands are easier to remember.

New Features #

• New arcle ci command — generate CI/CD pipelines for GitHub Actions (arcle ci add github) or GitLab CI (arcle ci add gitlab). Runs dart analyze + dart format on every push, with opt-in flutter test / --coverage, and optional --build apk|appbundle artifact upload. Also supports arcle ci list and arcle ci remove <provider>.

Fixes #

• Wired up arcle add locale and arcle delete locale — these commands existed in the codebase and were documented in the README but were never registered with the CLI's argument parser, so running them returned "Unknown command." They now work as documented, including the arcle del locale alias.

Release #

• Formal release consolidating the 2.1.5 changeset — CardThemeData theme fix and updated Codex/Gemini AI templates — with a full README and toolchain documentation pass.

Fixes #

• Updated generated theme templates for current Flutter APIs — replaced CardTheme with CardThemeData in the light and dark AppTheme templates so newly generated projects use the correct material theme type.
• Refreshed AI agent config templates — updated Codex and Gemini settings templates to use the newer model object shape; Codex now defaults to gpt-5.6 and Gemini to gemini-3.5-flash.

Improvements #

• Expanded AppColors — replaced the minimal 5-constant class with a full design-system palette: brand (light + dark), accent (light + dark), backgrounds, surfaces, borders, text (primary/secondary for each mode), semantic (error, success, warning, info), and neutral utilities (divider, disabled, overlay). AppColors._() private constructor prevents instantiation.
• Reworked AppTheme — AppTheme._() private constructor; light() / dark() renamed to lightTheme / darkTheme getters; all hardcoded Color(...) values replaced with AppColors.* references; added full component theme coverage: cardTheme, elevatedButtonTheme, outlinedButtonTheme, inputDecorationTheme, bottomNavigationBarTheme, navigationBarTheme, drawerTheme, dividerTheme, chipTheme, snackBarTheme; imports app_colors.dart.
• New PaginatedListView<T> widget — generated to lib/core/common_widgets/paginated_list_view.dart; pure stateless widget that handles scroll-threshold triggering, separated/normal list modes, loading indicator, empty state, and end-of-list widget. All state (items, isLoading, hasReachedMax) is owned by the caller's state management layer.

Changes #

• Removed arrow-key TUI menu — state management selection reverts to the simple numbered prompt (1. BLoC / 2. GetX / 3. Riverpod). The ANSI raw-mode approach caused StdinException on Windows terminals and added unnecessary complexity. The --state flag continues to work as before for non-interactive use.
• interactive_menu.dart removed. configure-ai agent selection also uses a numbered prompt.

Documentation #

• Updated README to reflect v2.1.x commands — removed unreachable commands, added arcle configure-ai and arcle review sections, updated "What's New" from 2.0.0 to 2.1.x.

Bug Fixes #

• Fixed crash on Windows when launching the arrow-key state selection menu — StdinException: Error setting terminal echo mode was thrown on certain Windows terminals (cmd.exe, some PowerShell hosts) that report stdin.hasTerminal = true but do not support raw mode. Raw-mode setup now happens before any rendering; StdinException is caught in select() and silently falls back to the numbered list (1. BLoC / 2. Riverpod / 3. GetX).

Improvements #

• Decoupled AI scaffolding from arcle create — default project creation now generates only the Flutter Clean Architecture structure. AI agent config (.ai/, .claude/, .codex/, .gemini/, scripts/) is no longer generated automatically.
• New command: arcle configure-ai (alias: arcle agent-init) — interactive one-question wizard to scaffold AI agent context files for an existing project. Detects state management from arcle.yaml; prompts if not found. Supports Claude Code, OpenAI Codex, Google Gemini, or all three.
• Arrow-key TUI menu for state management selection — replaced the text-based prompt (typing bloc/getx/riverpod) with an ANSI arrow-key navigable menu. Falls back to a numbered list automatically in CI/CD and non-TTY environments. The --state flag still bypasses the menu for scripted use.
• New command: arcle review (aliases: arcle audit, arcle -r) — pre-commit quality gate that runs:
  • dart analyze — static analysis
  • dart format --output=none --set-exit-if-changed — format check
  • Missing-tests scan — checks only files changed in the current git diff; warns on any lib/ file with no test/ counterpart
  • flutter test (opt-in via --test)
  • flutter test --coverage with percentage report (opt-in via --coverage)
  • AI-assisted diff review via configured agent binary (opt-in via --ai)

ARCLE Agentic Flutter Development Platform

New Commands #

• arcle agent add <claude|codex|gemini|custom> — scaffold agent-specific config files (.claude/, .codex/, .gemini/, .custom-agent/)
• arcle agent remove <agent> — remove an agent configuration directory
• arcle agent switch <agent> — set active_agent in .ai/settings.yaml
• arcle agent list — list all configured AI agents in the project
• arcle agent validate — validate that all required .ai/ files exist
• arcle ai init [--state] — generate .ai/ project context & rules directory
• arcle ai sync — sync .ai/settings.yaml state from arcle.yaml
• arcle ai validate — check all required .ai/ config files
• arcle ai doctor — diagnose AI configuration health
• arcle upgrade [--force] — upgrade an existing ARCLE project to v2.0.0 (SDK, analysis, dimensions, .ai/, scripts)

Project Scaffolding #

• New projects now include .ai/ directory with 6 AI agent context files: settings.yaml, project-context.md, architecture-rules.md, coding-rules.md, security-rules.md, permissions.yaml
• New projects now include Claude Code integration (.claude/CLAUDE.md, .claude/settings.json)
• New projects now include OpenAI Codex integration (.codex/instructions.md, .codex/settings.json)
• New projects now include Gemini integration (.gemini/GEMINI.md, .gemini/settings.json)
• New projects now include scripts/setup.sh, scripts/setup.ps1, scripts/doctor.sh, scripts/doctor.ps1

Breaking Changes #

• Replaced DimensionsTemplates.dimensions(state) with universal DimensionsTemplates.dimensions() — new implementation uses dart:ui PlatformDispatcher directly (works for all state management, no GetX dependency)
• Updated analysis_options.yaml template: replaced prefer_relative_imports with always_use_package_imports, added avoid_unnecessary_containers, prefer_single_quotes, unnecessary_const, unnecessary_new
• Minimum Dart SDK raised from ^3.5.4 to >=3.7.0 <4.0.0

Improvements #

• Generated project pubspec.yaml SDK constraint is now automatically set to >=3.7.0 <4.0.0
• buildCommonProjectFiles now accepts projectName parameter for proper AI context generation

• Reworked localization management around dedicated top-level commands:
  • arcle add locale <code> adds a single locale to the project; on first use it creates the localization infrastructure, and on later calls it appends the locale to the existing setup.
  • arcle delete locale <code> removes a single locale's JSON file, updates supportedLocales / isSupported in app_strings.dart, removes the GetX locale section when applicable, and cleans the assets/langs/ pubspec entry when the last locale is removed.
• Added localization command aliases: arcle add loc <code>, arcle delete loc <code>, arcle del locale <code>, and arcle del loc --<code>.
• Added --<code> flag shorthand for locale commands such as arcle add loc --my and arcle del loc --my.
• add locale now supports any ISO 639-1 locale code, with built-in country-code mappings for 60+ languages; unknown locales receive English-value placeholder JSON so the app stays runnable while translations are filled in.
• Updated localization injection so feature keys are added to every JSON file under assets/langs/ and every // arcle:keys_* marker in getx_localization.dart.
• Added arcle verify --check-features to scan every module under lib/features/ and report missing data, domain, or presentation layer files for the project's state management.
• Added arcle verify --check-assets to verify that every asset path declared in pubspec.yaml exists on disk.
• Added arcle verify --check-l10n to verify that each feature has its {feature}_title translation key present in assets/langs/en.json (BLoC/Riverpod) or lib/core/localization/getx_localization.dart (GetX).
• Added arcle verify --full to run --check-features, --check-assets, and --check-l10n in a single pass.

Platform Configuration Improvements:

• [CRITICAL FIX] Added automatic iOS Podfile configuration with minimum deployment target of iOS 13.0.
• [CRITICAL FIX] Added automatic iOS Info.plist generation with essential permission descriptions (camera, photos, microphone, location, contacts, calendar).
• [CRITICAL FIX] Added post-install hooks to Podfile to ensure consistent iOS build settings across all targets.
• [CRITICAL FIX] Fixed iOS builds that would previously fail due to missing Info.plist permission descriptions.
• Added automatic iOS deployment target enforcement to prevent compatibility issues.
• Updated iOS configuration to match Android's rigorous platform setup standard.
• Both Android and iOS are now configured equally during project creation for production-ready apps.
• Created comprehensive PLATFORM_CONFIGURATION_GUIDE.md with setup details, checklists, and troubleshooting.

Build & DI Improvements:

• Added persistent build version updates in arcle build apk with --version-name and --version-code, which rewrite the target project's pubspec.yaml.
• Added persistent environment updates in arcle build apk --env prod|stag|local, which rewrite the target project's lib/core/env/env_factory.dart.
• Added static 16 KB Android APK compatibility checks with arcle verify --check-16kb.
• Added separated gen-di and auto-gen-di commands with clear documentation on when/why to use each.
• Added comprehensive DI_COMMANDS_GUIDE.md explaining command differences and use cases.

Developer Experience:

• Added optional short command aliases such as new, feat, health, autodi, di, docs, ver, b, br, and bd while keeping all existing commands unchanged.
• Platform configuration status now shown during project creation (Android & iOS setup feedback).

• Added doctor command for ARCLE project health checks.
• Added doctor --fix for safe ARCLE-owned repairs.
• Added verify command to run analyze, test, and BLoC codegen verification.
• Added generated core/utils/date_formatter.dart with UTC/local conversion and UX-friendly date helpers.
• Added automatic intl dependency injection to generated projects.
• Updated generated notification service to be platform-safe across Android, iOS, macOS, and unsupported platforms.
• Updated generated permission service to use platform-aware permission handling and safe fallbacks.
• Updated README with platform notes for Android, iOS, macOS, and web behavior.
• Removed generated lib/features/README.md from new projects across all state management options.

• Fixed pubspec description length.
• Added usage example.