azdoutil: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

azdoutil is a .NET CLI tool distributed as a global tool via NuGet that provides utilities for Azure DevOps automation. The tool helps with tasks like managing work items, build/release definitions, flow metrics calculation, and test data generation.

Solution Structure

The solution uses a three-project architecture:

1. Benday.AzureDevOpsUtil.Api - Core library containing all business logic, commands, and Azure DevOps API integration
2. Benday.AzureDevOpsUtil.ConsoleUi - Minimal console entry point that bootstraps the CLI (packaged as .NET global tool)
3. Benday.AzureDevOpsUtil.UnitTests - Unit tests

Multi-targeted to .NET 8.0, 9.0, and 10.0.

Build and Test Commands

Build

dotnet build

Run Tests

dotnet test

Pack for NuGet

dotnet pack --configuration Release --output ./artifacts

Install Locally for Testing

# From the repository root
./install.sh       # On Linux/macOS
./install.ps1      # On Windows (PowerShell)

Uninstall

./uninstall.sh     # On Linux/macOS
./uninstall.ps1    # On Windows (PowerShell)

Core Architecture

Command Framework Pattern

The entire CLI is built on the Benday.CommandsFramework library (v5 — restored from the LocalNuGet feed until v5 is published) which provides automatic command discovery and execution:

• Commands are decorated with [Command] attributes specifying category, name, and description (IsAsync is gone in v5 — the type system says how a command runs)
• The framework automatically discovers all command classes in the Api assembly
• Program.cs (~30 lines) creates a DefaultProgram instance and delegates everything to the framework; Main returns the exit code from RunAsync — a Main that discards it would silently always exit 0
• Arguments are defined by overriding GetArguments() and returning a fluent-built ArgumentCollection (there is no [Argument] attribute in the framework)
• v5 notes: there is one Command base class (SynchronousCommand is gone; a sequential command returns Task.CompletedTask); OnExecute takes a CancellationToken, which most commands accept but do not yet thread through to their HTTP calls; arguments render and are documented in POSIX form (--name value) while the old /name:value form still parses with a deprecation warning on stderr; CommandRegistryFixture keeps the framework's registry and argument checks in the test suite (duplicate/reserved names like tui fail there rather than silently at run time)