feat: unified CLI with profile-based authentication

.config/dotnet-tools.json

@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {}
+}

.github/workflows/build.yml

@@ -35,8 +35,9 @@ jobs:
       uses: actions/setup-dotnet@v5
       with:
         dotnet-version: |
-          6.0.x
           8.0.x
+          9.0.x
+          10.0.x
 
     - name: Restore dependencies
       run: dotnet restore

.github/workflows/publish-nuget.yml

@@ -6,6 +6,8 @@ on:
       - 'Plugins-v*'
       - 'Dataverse-v*'
       - 'Migration-v*'
+      - 'Auth-v*'
+      - 'Cli-v*'
 
 jobs:
   publish:
@@ -21,6 +23,7 @@ jobs:
       with:
         dotnet-version: |
           8.0.x
+          9.0.x
           10.0.x
 
     - name: Determine package to publish
@@ -38,7 +41,13 @@ jobs:
           echo "projects=src/PPDS.Dataverse/PPDS.Dataverse.csproj" >> $GITHUB_OUTPUT
         elif [[ $TAG == Migration-v* ]]; then
           echo "package=PPDS.Migration" >> $GITHUB_OUTPUT
-          echo "projects=src/PPDS.Migration/PPDS.Migration.csproj src/PPDS.Migration.Cli/PPDS.Migration.Cli.csproj" >> $GITHUB_OUTPUT
+          echo "projects=src/PPDS.Migration/PPDS.Migration.csproj" >> $GITHUB_OUTPUT
+        elif [[ $TAG == Auth-v* ]]; then
+          echo "package=PPDS.Auth" >> $GITHUB_OUTPUT
+          echo "projects=src/PPDS.Auth/PPDS.Auth.csproj" >> $GITHUB_OUTPUT
+        elif [[ $TAG == Cli-v* ]]; then
+          echo "package=PPDS.Cli" >> $GITHUB_OUTPUT
+          echo "projects=src/PPDS.Cli/PPDS.Cli.csproj" >> $GITHUB_OUTPUT
         else
           echo "Unknown tag format: $TAG"
           exit 1

.github/workflows/test.yml

@@ -19,8 +19,9 @@ jobs:
       uses: actions/setup-dotnet@v5
       with:
         dotnet-version: |
-          6.0.x
           8.0.x
+          9.0.x
+          10.0.x
 
     - name: Restore dependencies
       run: dotnet restore

.gitignore

@@ -51,3 +51,7 @@ Thumbs.db
 
 # Temporary artifacts (testing, exports, logs)
 tmp/
+nul
+data.zip
+data/
+schema.xml

CLAUDE.md

@@ -30,23 +30,23 @@
 |------|-----|
 | Strong name all assemblies | Required for Dataverse plugin sandbox |
 | XML documentation for public APIs | IntelliSense support for consumers |
-| Multi-target appropriately | PPDS.Plugins: 4.6.2, 8.0, 10.0; PPDS.Dataverse: 8.0, 10.0 |
+| Multi-target appropriately | PPDS.Plugins: 4.6.2 only; libraries: 8.0, 9.0, 10.0 |
 | Run `dotnet test` before PR | Ensures no regressions |
 | Update `CHANGELOG.md` with changes | Release notes for consumers |
 | Follow SemVer versioning | Clear compatibility expectations |
 | Use connection pool for multi-request scenarios | Reuses connections, applies performance settings automatically |
 | Dispose pooled clients with `await using` | Returns connections to pool; prevents leaks |
 | Use bulk APIs (`CreateMultiple`, `UpdateMultiple`, `UpsertMultiple`) | 5x faster than `ExecuteMultiple` (~10M vs ~2M records/hour) |
 | Reference Microsoft Learn docs in ADRs | Authoritative source for Dataverse best practices |
-| Use `Conservative` preset for production bulk operations | Prevents throttle cascades; slightly lower throughput but zero throttles |
+| Scale throughput by adding Application Users | Each user has independent API quota; DOP × connections = total parallelism |
 
 ---
 
 ## 💻 Tech Stack
 
 | Technology | Version | Purpose |
 |------------|---------|---------|
-| .NET | 4.6.2, 8.0, 10.0 | Multi-targeting (Plugins: 4.6.2+, Dataverse: 8.0+) |
+| .NET | 4.6.2, 8.0, 9.0, 10.0 | Plugins: 4.6.2 only; libraries/CLI: 8.0, 9.0, 10.0 |
 | C# | Latest (LangVersion) | Primary language |
 | NuGet | - | Package distribution |
 | Strong Naming | .snk file | Required for Dataverse plugin assemblies |
@@ -70,10 +70,12 @@ ppds-sdk/
 │   │   ├── Resilience/          # Throttle tracking, retry logic
 │   │   └── PPDS.Dataverse.csproj
 │   ├── PPDS.Migration/          # Migration engine library
-│   └── PPDS.Migration.Cli/      # CLI tool (ppds-migrate)
+│   ├── PPDS.Auth/               # Authentication profiles and credentials
+│   └── PPDS.Cli/                # Unified CLI tool (ppds command)
 ├── tests/
 │   ├── PPDS.Plugins.Tests/
-│   └── PPDS.Dataverse.Tests/
+│   ├── PPDS.Dataverse.Tests/
+│   └── PPDS.Cli.Tests/
 ├── docs/
 │   ├── adr/                     # Architecture Decision Records
 │   └── architecture/            # Pattern documentation
@@ -140,6 +142,29 @@ public class PluginStepAttribute : Attribute { }
 public class PluginStepAttribute : Attribute { }
 ```
 
+### Code Comments
+
+Comments explain WHY, not WHAT. The code documents what it does.
+
+```csharp
+// ❌ Bad - explains what (the code already shows this)
+// Loop through all options and check if required
+foreach (var option in command.Options)
+
+// ❌ Bad - references external tool as justification
+// Use [Required] prefix like Azure CLI does
+option.Description = $"[Required] {desc}";
+
+// ✅ Good - explains why (non-obvious side effect)
+// Required=false hides the default suffix; we show [Required] in description instead
+option.Required = false;
+
+// ✅ Good - explains why (workaround for framework limitation)
+// Option validators only run when the option is present on command line,
+// so we need command-level validation to catch missing required options
+command.Validators.Add(result => { ... });
+```
+
 ### Namespaces
 
 ```csharp
@@ -152,11 +177,23 @@ namespace PPDS.Plugins.Enums;        // Enums
 namespace PPDS.Dataverse.Pooling;        // Connection pool, IConnectionSource
 namespace PPDS.Dataverse.BulkOperations; // Bulk API wrappers
 namespace PPDS.Dataverse.Configuration;  // Options, connection config
-namespace PPDS.Dataverse.Resilience;     // Throttle tracking, rate control
+namespace PPDS.Dataverse.Resilience;     // Throttle tracking, service protection
 
 // PPDS.Migration
 namespace PPDS.Migration.Export;     // IExporter
 namespace PPDS.Migration.Import;     // IImporter
+
+// PPDS.Auth
+namespace PPDS.Auth.Profiles;        // AuthProfile, ProfileStore, ProfileCollection
+namespace PPDS.Auth.Credentials;     // ICredentialProvider, credential implementations
+namespace PPDS.Auth.Discovery;       // GlobalDiscoveryService, EnvironmentResolver
+namespace PPDS.Auth.Cloud;           // CloudEnvironment, CloudEndpoints
+
+// PPDS.Cli
+namespace PPDS.Cli.Commands.Auth;    // Auth command group
+namespace PPDS.Cli.Commands.Env;     // Environment command group
+namespace PPDS.Cli.Commands.Data;    // Data command group (export, import, copy)
+namespace PPDS.Cli.Infrastructure;   // ServiceFactory, ProfileServiceFactory
 ```
 
 ---
@@ -169,7 +206,9 @@ Each package has independent versioning using [MinVer](https://github.com/adamra
 |---------|------------|---------|
 | PPDS.Plugins | `Plugins-v{version}` | `Plugins-v1.2.0` |
 | PPDS.Dataverse | `Dataverse-v{version}` | `Dataverse-v1.0.0` |
-| PPDS.Migration + CLI | `Migration-v{version}` | `Migration-v1.0.0` |
+| PPDS.Migration | `Migration-v{version}` | `Migration-v1.0.0` |
+| PPDS.Auth | `Auth-v{version}` | `Auth-v1.0.0` |
+| PPDS.Cli | `Cli-v{version}` | `Cli-v1.0.0` |
 
 - Follow SemVer: `MAJOR.MINOR.PATCH`
 - Pre-release: `-alpha.N`, `-beta.N`, `-rc.N` suffix
@@ -201,6 +240,8 @@ See per-package changelogs:
 - [PPDS.Plugins](src/PPDS.Plugins/CHANGELOG.md)
 - [PPDS.Dataverse](src/PPDS.Dataverse/CHANGELOG.md)
 - [PPDS.Migration](src/PPDS.Migration/CHANGELOG.md)
+- [PPDS.Auth](src/PPDS.Auth/CHANGELOG.md)
+- [PPDS.Cli](src/PPDS.Cli/CHANGELOG.md)
 
 ---
 
@@ -213,14 +254,15 @@ See per-package changelogs:
 | PPDS.Plugins | NuGet |
 | PPDS.Dataverse | NuGet |
 | PPDS.Migration | NuGet |
-| PPDS.Migration.Cli | .NET Tool |
+| PPDS.Auth | NuGet |
+| PPDS.Cli | .NET Tool |
 
 ### Consumed By
 
 | Consumer | How | Breaking Change Impact |
 |----------|-----|------------------------|
 | ppds-tools | Reflects on attributes | Must update reflection code |
-| ppds-tools | Shells to `ppds-migrate` CLI | Must update CLI calls |
+| ppds-tools | Shells to `ppds` CLI | Must update CLI calls |
 | ppds-demo | NuGet reference | Must update package reference |
 
 ### Version Sync Rules
@@ -235,7 +277,7 @@ See per-package changelogs:
 
 - Adding required properties to `PluginStepAttribute` or `PluginImageAttribute`
 - Changing attribute property types or names
-- Changing `ppds-migrate` CLI arguments or output format
+- Changing `ppds` CLI arguments or output format
 
 ---
 
@@ -288,30 +330,26 @@ ServicePointManager.UseNagleAlgorithm = false;
 - [Service protection API limits](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/api-limits)
 - [Use bulk operation messages](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/bulk-operations)
 
-### Adaptive Rate Control
+### DOP-Based Parallelism
 
-The pool implements AIMD-based (Additive Increase, Multiplicative Decrease) rate control that:
-- Starts at server-recommended parallelism
-- Increases gradually after sustained success
-- Backs off aggressively on throttle (50% reduction)
-- Applies execution time-aware ceiling for slow operations
+The pool uses Microsoft's `RecommendedDegreesOfParallelism` (from `x-ms-dop-hint` header) as the parallelism limit:
 
-### Rate Control Presets
+```
+Total Parallelism = sum(DOP per connection)
+```
 
-| Preset | Use Case | Behavior |
-|--------|----------|----------|
-| `Conservative` | Production bulk jobs, migrations | Lower ceiling, avoids all throttles |
-| `Balanced` | General purpose (default) | Balanced throughput vs safety |
-| `Aggressive` | Dev/test with monitoring | Higher ceiling, accepts some throttles |
+- **DOP varies by environment**: Trial environments report ~4, production can report up to 50
+- **Hard cap of 52 per user**: Microsoft's enforced limit per Application User
+- **Scale by adding connections**: 2 users at DOP=4 = 8 parallel requests
 
-**Configuration:**
-```json
-{"Dataverse": {"AdaptiveRate": {"Preset": "Conservative"}}}
+**Scaling Strategy:**
+```
+1 Application User  @ DOP=4  →  4 parallel requests
+2 Application Users @ DOP=4  →  8 parallel requests
+4 Application Users @ DOP=4  → 16 parallel requests
 ```
 
-**For production bulk operations, always use `Conservative`** to prevent throttle cascades.
-
-See [ADR-0006](docs/adr/0006_EXECUTION_TIME_CEILING.md) for execution time ceiling details.
+See [ADR-0005](docs/adr/0005_DOP_BASED_PARALLELISM.md) for details.
 
 ### Architecture Decision Records
 
@@ -321,30 +359,53 @@ See [ADR-0006](docs/adr/0006_EXECUTION_TIME_CEILING.md) for execution time ceili
 | [0002](docs/adr/0002_MULTI_CONNECTION_POOLING.md) | Multiple Application Users multiply API quota |
 | [0003](docs/adr/0003_THROTTLE_AWARE_SELECTION.md) | Route away from throttled connections |
 | [0004](docs/adr/0004_THROTTLE_RECOVERY_STRATEGY.md) | Transparent throttle waiting without blocking |
-| [0005](docs/adr/0005_POOL_SIZING_PER_CONNECTION.md) | Per-user pool sizing (52 per Application User) |
-| [0006](docs/adr/0006_EXECUTION_TIME_CEILING.md) | Execution time-aware parallelism ceiling |
-| [0007](docs/adr/0007_CONNECTION_SOURCE_ABSTRACTION.md) | IConnectionSource for custom auth methods |
+| [0005](docs/adr/0005_DOP_BASED_PARALLELISM.md) | DOP-based parallelism (server-recommended limits) |
+| [0006](docs/adr/0006_CONNECTION_SOURCE_ABSTRACTION.md) | IConnectionSource for custom auth methods |
+| [0007](docs/adr/0007_UNIFIED_CLI_AND_AUTH.md) | Unified CLI and shared authentication profiles |
 
 ---
 
-## 🖥️ CLI (PPDS.Migration.Cli)
+## 🖥️ CLI (PPDS.Cli)
+
+The unified CLI (`ppds`) uses stored authentication profiles. Create a profile once, then all commands use it automatically.
+
+### Command Structure
 
-### Authentication Modes
+```
+ppds
+├── auth      Authentication profile management
+├── env       Environment discovery and selection
+├── data      Data operations (export, import, copy, analyze)
+├── schema    Schema generation and entity listing
+└── users     User mapping for cross-environment migrations
+```
 
-| Mode | Flag | Use Case |
-|------|------|----------|
-| Interactive | `--auth interactive` (default) | Development, ad-hoc usage |
-| Environment | `--auth env` | CI/CD pipelines |
-| Managed Identity | `--auth managed` | Azure-hosted workloads |
+### Quick Start
 
-**CI/CD environment variables:**
 ```bash
-DATAVERSE__URL=https://org.crm.dynamics.com
-DATAVERSE__CLIENTID=your-client-id
-DATAVERSE__CLIENTSECRET=your-secret
+# Create profile (opens browser)
+ppds auth create --name dev
+
+# Select environment
+ppds env select --environment "My Environment"
+
+# Run commands
+ppds data export --schema schema.xml --output data.zip
 ```
 
-See [CLI README](src/PPDS.Migration.Cli/README.md) for full documentation.
+### Authentication Methods
+
+| Method | Flags | Use Case |
+|--------|-------|----------|
+| Interactive Browser | (default) | Development |
+| Device Code | `--deviceCode` | Headless/SSH |
+| Client Secret | `--applicationId` + `--clientSecret` + `--tenant` | CI/CD |
+| Certificate | `--applicationId` + `--certificateDiskPath` + `--tenant` | Automated |
+| Managed Identity | `--managedIdentity` | Azure-hosted |
+| GitHub OIDC | `--githubFederated` + `--applicationId` + `--tenant` | GitHub Actions |
+| Azure DevOps OIDC | `--azureDevOpsFederated` + `--applicationId` + `--tenant` | Azure Pipelines |
+
+See [CLI README](src/PPDS.Cli/README.md) for full documentation.
 
 ---
 

PPDS.Sdk.sln

@@ -15,12 +15,14 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PPDS.Dataverse", "src\PPDS.
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PPDS.Dataverse.Tests", "tests\PPDS.Dataverse.Tests\PPDS.Dataverse.Tests.csproj", "{738F9CC6-9EAC-4EA0-9B8B-DD6A5157A1F1}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PPDS.Migration.Cli", "src\PPDS.Migration.Cli\PPDS.Migration.Cli.csproj", "{10DA306C-4AB2-464D-B090-3DA7B18B1C08}"
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PPDS.Cli", "src\PPDS.Cli\PPDS.Cli.csproj", "{10DA306C-4AB2-464D-B090-3DA7B18B1C08}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PPDS.Migration.Cli.Tests", "tests\PPDS.Migration.Cli.Tests\PPDS.Migration.Cli.Tests.csproj", "{45DB0E17-0355-4342-8218-2FD8FA545157}"
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PPDS.Cli.Tests", "tests\PPDS.Cli.Tests\PPDS.Cli.Tests.csproj", "{45DB0E17-0355-4342-8218-2FD8FA545157}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PPDS.Migration", "src\PPDS.Migration\PPDS.Migration.csproj", "{1642C0BD-0B5B-476D-86EB-73BE3CD9BD67}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PPDS.Auth", "src\PPDS.Auth\PPDS.Auth.csproj", "{5B3662DC-7BC8-4981-8F0F-30FB12CFD3F7}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -115,6 +117,18 @@ Global
 		{1642C0BD-0B5B-476D-86EB-73BE3CD9BD67}.Release|x64.Build.0 = Release|Any CPU
 		{1642C0BD-0B5B-476D-86EB-73BE3CD9BD67}.Release|x86.ActiveCfg = Release|Any CPU
 		{1642C0BD-0B5B-476D-86EB-73BE3CD9BD67}.Release|x86.Build.0 = Release|Any CPU
+		{5B3662DC-7BC8-4981-8F0F-30FB12CFD3F7}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{5B3662DC-7BC8-4981-8F0F-30FB12CFD3F7}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{5B3662DC-7BC8-4981-8F0F-30FB12CFD3F7}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{5B3662DC-7BC8-4981-8F0F-30FB12CFD3F7}.Debug|x64.Build.0 = Debug|Any CPU
+		{5B3662DC-7BC8-4981-8F0F-30FB12CFD3F7}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{5B3662DC-7BC8-4981-8F0F-30FB12CFD3F7}.Debug|x86.Build.0 = Debug|Any CPU
+		{5B3662DC-7BC8-4981-8F0F-30FB12CFD3F7}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{5B3662DC-7BC8-4981-8F0F-30FB12CFD3F7}.Release|Any CPU.Build.0 = Release|Any CPU
+		{5B3662DC-7BC8-4981-8F0F-30FB12CFD3F7}.Release|x64.ActiveCfg = Release|Any CPU
+		{5B3662DC-7BC8-4981-8F0F-30FB12CFD3F7}.Release|x64.Build.0 = Release|Any CPU
+		{5B3662DC-7BC8-4981-8F0F-30FB12CFD3F7}.Release|x86.ActiveCfg = Release|Any CPU
+		{5B3662DC-7BC8-4981-8F0F-30FB12CFD3F7}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -127,5 +141,6 @@ Global
 		{10DA306C-4AB2-464D-B090-3DA7B18B1C08} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
 		{45DB0E17-0355-4342-8218-2FD8FA545157} = {0AB3BF05-4346-4AA6-1389-037BE0695223}
 		{1642C0BD-0B5B-476D-86EB-73BE3CD9BD67} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
+		{5B3662DC-7BC8-4981-8F0F-30FB12CFD3F7} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
 	EndGlobalSection
 EndGlobal