Merge pull request #26 from peopleworks/feat/byo-ai-key

Let any model answer, and a key be enough

Author: peopleworks

CHANGELOG.md

@@ -39,9 +39,26 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   an appearance rule does. Probed at the time: an application went from two declared rules to
   three and the diff reported zero changes.
 
+### Changed
+
+- **Any model will do, and a key is enough** ([#24]). Every AI feature reached PeopleWorks Copilot
+  for its credentials — not for a key the user had configured, but for the *model's* key, fetched
+  from an account. On a public MIT project that meant no outside user could run any of them:
+  `--enrich` refused without an API URL and token and told the reader to configure credentials for
+  a service they had never heard of, and the Description Annotator asked for `COPILOT_API_TOKEN`.
+  There is now one resolver shared by both, taking the first route that is configured: `--api-key`
+  on the command line, then `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` in the environment, then a
+  PeopleWorks Copilot account — which still works untouched, as one option among several rather
+  than the gate. `--ai-base-url` reaches any OpenAI-compatible endpoint, including a local one, and
+  `--ai-model` names the model. Someone with none of them configured is now told all four.
+  A key is never read from or written to the configuration file: the endpoint and the model name
+  are settings, a key is a secret, and that file lives in a home directory that gets copied around.
+
 ### Internal
 
-- First tests over `ProjectDiffEngine`, which is why the key above survived. 337 tests.
+- First tests over `ProjectDiffEngine`, which is why the key above survived. 345 tests.
+
+[#24]: https://github.com/peopleworks/XAFLogicExplainer/issues/24
 
 [#21]: https://github.com/peopleworks/XAFLogicExplainer/pull/21
 [@MBrekhof]: https://github.com/MBrekhof

README.md

@@ -295,6 +295,19 @@ Documentation is generated in **English or Spanish** (`--lang en|es`).
 Useful flags: `--orm auto\|xpo\|efcore`, `--lang en\|es`, `--enrich` (AI-generated business-logic
 summaries per controller and action), `--force`, `--all`.
 
+`--enrich` needs a model, and **any of these is enough** — a key on the command line wins, then the
+environment, then a PeopleWorks Copilot account if you happen to have one:
+
+```bash
+xaflogic extract --enrich --api-key sk-...              # or any OpenAI-compatible endpoint:
+xaflogic extract --enrich --api-key ... --ai-base-url http://localhost:11434/v1 --ai-model qwen2.5-coder
+
+export OPENAI_API_KEY=sk-...        # picked up with no configuration at all
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+Everything else in this tool runs with no key, no account and no network.
+
 Extraction is **incremental** — a SHA-256 over your `.cs` and `.xafml` files means an unchanged
 project is a no-op. There is an MSBuild `.targets` file if you want it to run on build.
 
@@ -317,7 +330,7 @@ applications. The agent-facing surface is what is landing now, in the open.
 | ✅ | Pluggable publishing targets (`IDocumentationSink`) |
 | ✅ | **MCP server** — 10 tools, live against your source |
 | ✅ | **Installable Claude Code plugin** with skill and MCP server |
-| ✅ | **337 tests** over synthetic XPO and EF Core fixtures — no DevExpress needed |
+| ✅ | **345 tests** over synthetic XPO and EF Core fixtures — no DevExpress needed |
 | ✅ | **DevExpress ground-truth catalog**, generated locally by licensees |
 
 PeopleWorks Copilot, where this tool grew up, is now one sink among several rather than the

src/XafLogicExplainer.Cli/Program.cs

@@ -4,6 +4,7 @@
 using Spectre.Console;
 using XafLogicExplainer.Cli.Helpers;
 using XafLogicExplainer.Cli.Models;
+using XafLogicExplainer.CopilotSync.Ai;
 using XafLogicExplainer.CopilotSync.Models;
 using XafLogicExplainer.CopilotSync.Services;
 using XafLogicExplainer.Core.Analyzers;
@@ -46,12 +47,34 @@
 allOption.AddAlias("-a");
 var enrichOption = new Option<bool>("--enrich", "Enrich controllers with AI-generated business logic summaries");
 
+// Global, because every command that can enrich needs them and none of them owns the choice of
+// model. Declared as options rather than read out of the environment alone so they appear in
+// --help: the reason nobody outside this shop could use --enrich was that nothing said how.
+var apiKeyOption = new Option<string?>("--api-key", "API key for the AI provider (or set OPENAI_API_KEY / ANTHROPIC_API_KEY)");
+var aiBaseUrlOption = new Option<string?>("--ai-base-url", "Any OpenAI-compatible endpoint, including a local one");
+var aiModelOption = new Option<string?>("--ai-model", "Model name, when not the provider's default");
+
 // ============================================================
 // ROOT COMMAND
 // ============================================================
 
 var rootCommand = new RootCommand("XAF Logic Explainer CLI - Extract and sync XAF project documentation");
 
+rootCommand.AddGlobalOption(apiKeyOption);
+rootCommand.AddGlobalOption(aiBaseUrlOption);
+rootCommand.AddGlobalOption(aiModelOption);
+
+// Read once, here, rather than threaded through each handler: SetHandler takes at most eight
+// parameters and extract already spends six, so adding three would have forced four commands onto
+// the InvocationContext pattern to carry a setting none of them decides.
+var aiParse = rootCommand.Parse(args);
+var aiOverrides = new AiClientRequest
+{
+    ApiKey = aiParse.GetValueForOption(apiKeyOption),
+    BaseUrl = aiParse.GetValueForOption(aiBaseUrlOption),
+    Model = aiParse.GetValueForOption(aiModelOption),
+};
+
 // ============================================================
 // COMMAND: config
 // ============================================================
@@ -380,7 +403,7 @@ await AnsiConsole.Status().Spinner(Spinner.Known.Dots).StartAsync("Extracting pr
 
     if (enrich)
     {
-        await EnrichWithAi(project, config, language!);
+        await EnrichWithAi(project, config, language!, aiOverrides);
     }
 
     // Summary table
@@ -631,7 +654,7 @@ await AnsiConsole.Status().Spinner(Spinner.Known.Dots).StartAsync("Syncing to Pe
         {
             enrichHook = async (extractedProject) =>
             {
-                await EnrichWithAi(extractedProject, config, language!);
+                await EnrichWithAi(extractedProject, config, language!, aiOverrides);
             };
         }
         singleResult = await syncService.SyncAsync(singleSyncConfig, BuildExtractionOptions(language, orm), msg =>
@@ -1433,7 +1456,8 @@ await GenerateAgentFiles(
                 agentsForce,
                 agentsEnrich,
                 agentsOptions,
-                agentsConfig);
+                agentsConfig,
+                aiOverrides);
         }
 
         return;
@@ -1454,7 +1478,8 @@ await GenerateAgentFiles(
         agentsForce,
         agentsEnrich,
         agentsOptions,
-        agentsConfig);
+        agentsConfig,
+        aiOverrides);
 });
 
 rootCommand.AddCommand(agentsCommand);
@@ -1503,7 +1528,7 @@ await AnsiConsole.Status().Spinner(Spinner.Known.Dots).StartAsync("Reading the a
 
     if (explainEnrich)
     {
-        await EnrichWithAi(explained, explainConfig, explainLang);
+        await EnrichWithAi(explained, explainConfig, explainLang, aiOverrides);
     }
 
     var html = new HtmlExplainerGenerator(ThisAssemblyVersion()).Generate(explained);
@@ -1759,7 +1784,8 @@ static async Task GenerateAgentFiles(
     bool force,
     bool enrich,
     AgentFilesOptions options,
-    CliConfig config)
+    CliConfig config,
+    AiClientRequest aiOverrides)
 {
     if (!Directory.Exists(projectPath))
     {
@@ -1784,7 +1810,7 @@ await AnsiConsole.Status().Spinner(Spinner.Known.Dots).StartAsync("Reading the a
 
     if (enrich)
     {
-        await EnrichWithAi(agentProject, config, language);
+        await EnrichWithAi(agentProject, config, language, aiOverrides);
     }
 
     var agentGenerator = new MarkdownDocumentationGenerator(language);
@@ -1967,49 +1993,46 @@ static void DisplayDiffSummary(ProjectDiffReport report)
 // HELPER: AI Business Logic Enrichment
 // ============================================================
 
-static async Task EnrichWithAi(ExtractedProject project, CliConfig config, string language)
+static async Task EnrichWithAi(
+    ExtractedProject project, CliConfig config, string language, AiClientRequest aiOverrides)
 {
     if (project.Controllers.Count == 0)
     {
         AnsiConsole.MarkupLine("[grey]  No controllers to enrich.[/]");
         return;
     }
 
-    var apiUrl = config.ApiUrl;
-    var token = config.Token;
-    var userName = config.UserName ?? "xaf-logic-explainer";
-    var resourceName = config.ResourceName ?? "";
-
-    if (string.IsNullOrEmpty(apiUrl) || string.IsNullOrEmpty(token))
+    // A PeopleWorks Copilot account is now the last of several routes rather than the only one, so
+    // it is offered rather than required: an empty URL or token simply means this route is not
+    // configured, and the resolver moves on to the next.
+    var request = aiOverrides with
     {
-        AnsiConsole.MarkupLine("[yellow]  --enrich requires API credentials. Configure with: xaflogic config[/]");
-        return;
-    }
+        Copilot = new SyncConfiguration
+        {
+            CopilotApiBaseUrl = config.ApiUrl ?? "",
+            CopilotApiToken = config.Token ?? "",
+            UserName = config.UserName ?? "xaf-logic-explainer",
+            ResourceName = config.ResourceName ?? "",
+        },
+    };
 
-    AnsiConsole.MarkupLine("[grey]  Fetching AI provider credentials...[/]");
-    AiProviderInfo? aiProvider = null;
-    using (var apiClient = new CopilotApiClient(apiUrl, token, userName, resourceName))
-    {
-        aiProvider = await apiClient.GetAiProviderAsync();
-    }
+    var resolved = await AiClientResolver.ResolveAsync(request);
 
-    if (aiProvider == null || string.IsNullOrEmpty(aiProvider.ApiKey))
+    if (!resolved.Succeeded)
     {
-        AnsiConsole.MarkupLine("[yellow]  Could not retrieve AI provider. Skipping enrichment.[/]");
+        var problem = resolved.Problem ?? AiClientResolver.NothingConfigured;
+
+        foreach (var line in problem.Split('\n'))
+            AnsiConsole.MarkupLine($"[yellow]  {Markup.Escape(line)}[/]");
+
         return;
     }
 
-    var model = aiProvider.Parameters?.GetValueOrDefault("model")?.ToString() ?? "gpt-4o-mini";
-    var baseUrl = aiProvider.AiProviderBaseUrl ?? "https://api.openai.com/v1";
+    var chatClient = resolved.Client!;
 
-    AnsiConsole.MarkupLine($"[blue]AI:[/] {Markup.Escape(aiProvider.ProviderName ?? "OpenAI")} / {Markup.Escape(model)}");
+    AnsiConsole.MarkupLine($"[blue]AI:[/] {Markup.Escape(resolved.ProviderName)} / {Markup.Escape(resolved.Model)}");
     AnsiConsole.MarkupLine($"[blue]  Enriching {project.Controllers.Count} controllers...[/]");
 
-    var openAiClient = new OpenAIClient(
-        new System.ClientModel.ApiKeyCredential(aiProvider.ApiKey),
-        new OpenAIClientOptions { Endpoint = new Uri(baseUrl) });
-    var chatClient = openAiClient.GetChatClient(model).AsIChatClient();
-
     var enricher = new BusinessLogicEnricher(chatClient);
     await enricher.EnrichAsync(project, language, msg =>
     {