Skip to content

Latest commit

 

History

History
73 lines (50 loc) · 3.65 KB

CLAUDE.md

File metadata and controls

73 lines (50 loc) · 3.65 KB

CLAUDE.md / AGENTS.md

This file provides guidance to Claude Code, Codex or other AI agents when working with code in this repository.

What is Alex

alex is a Dart CLI tool for managing Flutter projects, published on pub.dev and installed globally via dart pub global activate alex. It automates release management (gitflow-based), localization (ARB, XML, iOS strings), code generation, feature branch management, and dependency management.

Commands

# Setup
dart pub get
dart pub run build_runner build --delete-conflicting-outputs

# Quality (run both before committing; CI will fail otherwise)
dart analyze       # must show "No issues found!"
dart test          # ~29 tests, ~20-29 seconds — never cancel

# Run the tool locally
dart bin/alex.dart --help
dart bin/alex.dart --version

To run a single test file: dart test test/src/changelog/changelog_test.dart

Architecture

Entry flow: bin/alex.dart → lib/app.dart:run() → AlexCommandRunner → individual AlexCommand subclasses.

Command pattern: Every command extends AlexCommand (in lib/runner/alex_command.dart), which provides:

  • Config access via AlexConfig.instance (singleton loaded from alex.yaml or pubspec.yaml)
  • Git operations via getGit() returning a Git interface (implementations: GitClient, ConsoleGit, DemoGit)
  • Console I/O abstraction
  • Structured error handling via RunException

Command hierarchy:

  • lib/commands/release/ — gitflow-based releases, changelog updates, optional ChatGPT release notes
  • lib/commands/feature/ — feature branch finish (merge to develop, delete remote)
  • lib/commands/l10n/ — 8 subcommands for ARB/XML/iOS strings localization
  • lib/commands/code/ — runs build_runner (supports subprojects)
  • lib/commands/pubspec/ — pub get and dependency updates (supports workspaces)
  • lib/commands/settings/ — global settings (e.g., OpenAI API key stored via Hive)
  • lib/commands/update/ — self-update via pub.dev

Core utilities (lib/src/):

  • config.dart — AlexConfig singleton; searches for alex.yaml or pubspec.yaml recursively for multi-package projects
  • git/ — GitCommands wraps high-level operations; uses Process.runSync() internally
  • changelog/ — parses and mutates CHANGELOG.md
  • l10n/ — encoders/decoders/validators for ARB, XML, iOS strings, JSON, Google Docs export
  • local_store/ — Hive-based persistence (used by local_data.dart and settings.dart)
  • run/ — Cmd and FlutterCmd for executing shell processes
  • pub_spec.dart — pubspec.yaml parsing; supports multi-package workspace discovery

Code generation: lib/src/version.dart is generated by build_version. Always regenerate after version changes.

Testing: Tests are in test/src/ covering changelog parsing and l10n validators. Constructor-based dependency injection on commands enables unit testing without real git/file-system dependencies.

Configuration

Alex reads config from alex.yaml (preferred) or the alex: key in pubspec.yaml. See alex.yaml at the repo root for a documented example of all available options (l10n paths, git branch names, script paths, CI settings).

Lint Rules

Uses innim_lint (configured in analysis_options.yaml). Run dart analyze to check; CI enforces zero issues.

Commit Messages

Keep commit messages short — a single concise subject line is preferred. Add a body only when the reasoning is not obvious from the subject alone.

Changelog

When adding a changelog entry, add it at the very top of CHANGELOG.md as a new unreleased section (e.g. ## Next), not under the latest version header — that version is already released.