aw-spec-cli 0.1.0 → 0.1.2

package/assets/docs/components/Email/README.md

@@ -0,0 +1,112 @@
+# Email Component (`AppWeaver.Messaging.Email`)
+
+> Pure technology (domain-agnostic). Reference sheet for the Email messaging component.
+> To wire it into a project, follow the agent runbook in [integration.md](./integration.md).
+> Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## What it is
+
+A provider-agnostic email-sending component. Application code depends on a single abstraction,
+`IEmailService`; the transport (Microsoft Graph, SMTP, SendGrid, OAuth2-SMTP, or a local File
+sink) is chosen once during DI registration via `AddEmailMessaging(...)`.
+
+**Use when:** a feature must send transactional or notification email (user-created alerts,
+confirmations, admin notices, password flows, attachments).
+
+## Public contract (`AppWeaver.Messaging.Email`)
+
+```csharp
+namespace AppWeaver.Messaging.Email;
+
+public interface IEmailService
+{
+    // Convenience overload — single recipient.
+    Task SendAsync(string from, string to, string subject, string body,
+                   bool isHtml = true, CancellationToken cancellationToken = default);
+
+    // Full message — multi-recipient, Cc/Bcc, attachments.
+    Task SendAsync(EmailMessage message, CancellationToken cancellationToken = default);
+}
+```
+
+```csharp
+namespace AppWeaver.Messaging.Email.Entities;
+
+public class EmailMessage
+{
+    public string From { get; set; }                 // falls back to provider DefaultFrom if empty
+    public List<string> To { get; set; }  = new();
+    public List<string> Cc { get; set; }  = new();
+    public List<string> Bcc { get; set; } = new();
+    public string Subject { get; set; }
+    public string Body { get; set; }
+    public bool IsHtml { get; set; } = true;
+    public List<EmailAttachment> Attachments { get; set; } = new();
+}
+
+public class EmailAttachment
+{
+    public string FileName { get; set; }
+    public byte[] Content { get; set; }
+    public string ContentType { get; set; } = "application/octet-stream";
+}
+```
+
+## Packages
+
+| Package | Version | Role | Builder method | Provider key |
+|---|---|---|---|---|
+| `AppWeaver.Messaging.Email` | `0.1.3` | **Required.** Abstraction + `AddEmailMessaging` + facade. | — | — |
+| `AppWeaver.Messaging.Email.MsGraph` | `0.1.2` | Microsoft 365 / Graph API (recommended for prod). | `UseMsGraph` | `MsGraph` |
+| `AppWeaver.Messaging.Email.Smtp` | `0.1.3` | Classic SMTP (host/port/user/password). | `UseSmtp` | `Smtp` |
+| `AppWeaver.Messaging.Email.SendGrid` | `0.1.2` | SendGrid API key. | `UseSendGrid` | `SendGrid` |
+| `AppWeaver.Messaging.Email.OAuth2` | `0.1.3` | OAuth2-authenticated SMTP (O365). | `UseOAuth2` | `OAuth2` |
+| `AppWeaver.Messaging.Email.File` | `0.1.2` | Writes email to a local `.txt` file — local dev / tests. | `UseFile` | `File` |
+
+Install the abstraction **plus exactly one provider** for the environment you are wiring.
+
+## Provider option shapes
+
+| Provider | Options type | Key fields | Bound config section |
+|---|---|---|---|
+| MsGraph | `MsGraphEmailOptions` | `TenantId`, `ClientId`, `ClientSecret`, `DefaultFrom`, `Scopes` | `Messaging.Email.MsGraph` |
+| Smtp | `SmtpEmailOptions` | `Host`, `Port`, `Username`, `Password`, `EnableSsl`, `DefaultFrom` | `Messaging.Email.Smtp` |
+| SendGrid | `SendGridEmailOptions` | `ApiKey` *(required)*, `DefaultFrom` | `Messaging.Email.SendGrid` |
+| OAuth2 | `OAuth2EmailOptions` | `TenantId`, `ClientId`, `ClientSecret`, `Host`, `Port`, `Scopes`, `DefaultFrom` | `Messaging.Email.OAuth2` |
+| File | `FileEmailOptions` | `DefaultFrom` | `Messaging.Email.Smtp` *(quirk — pass options inline)* |
+
+## Registration entry point
+
+```csharp
+// In AppWeaver.Messaging.Email.Extensions
+IComponentBuilder<IEmailService> AddEmailMessaging(
+    this IServiceCollection services,
+    Action<IComponentBuilder<IEmailService>> configureBuilder,   // required
+    Action<MessagingEmailConfiguration>? configureOptions = null,// set Provider here
+    IConfiguration? configuration = null);                       // OR bind from config
+```
+
+`MessagingEmailConfiguration` exposes a single `[Required] string Provider`. The facade
+(`DefaultImplementation`) resolves the keyed provider whose key equals `Provider`.
+
+## Source map (framework)
+
+```
+framework/Messaging.Email/
+  Integration.md                         ← original MsGraph tutorial (reference)
+  src/
+    AppWeaver.Messaging.Email/           ← IEmailService, EmailMessage, AddEmailMessaging, facade
+    AppWeaver.Messaging.Email.MsGraph/   ← UseMsGraph + MsGraphEmailService
+    AppWeaver.Messaging.Email.Smtp/      ← UseSmtp + SmtpEmailService
+    AppWeaver.Messaging.Email.SendGrid/  ← UseSendGrid + SendGridEmailService
+    AppWeaver.Messaging.Email.OAuth2/    ← UseOAuth2 + OAuth2EmailService
+    AppWeaver.Messaging.Email.File/      ← UseFile  + FileEmailService
+  test/
+    MsGraphTest/Program.cs               ← MsGraph end-to-end sample
+    TestApp/Program.cs                   ← OAuth2 + File multi-provider sample
+```
+
+## Related
+
+- [integration.md](./integration.md) · [[components-readme]] · [[cqrs]] ·
+  [[clean-architecture]] · [[dependency-policy]]

package/assets/docs/components/Email/integration.md

@@ -0,0 +1,260 @@
+# Email Component — Integration Workflow (agent playbook)
+
+> Pure technology (domain-agnostic). This file is an **agent runbook**: read it top-to-bottom and
+> execute the workflow in order. It drives an interactive integration of `IEmailService` into a
+> project, asking the user which transport implementation(s) to wire. Read [README.md](./README.md)
+> first for the contract. Replace `<SampleProjectName>` with the project name.
+> Commands: `/aw-spec-implement`.
+
+---
+
+## Agent workflow — execute in order
+
+1. **Load context.** Read [README.md](./README.md) (contract + provider matrix) and this file.
+2. **Locate target projects** in the solution (see [[folder-structure]]):
+   `…Application` (injects `IEmailService`), `…Infrastructure` (does the registration),
+   `…Service` (holds `appsettings.json`). If the layout differs, map these roles before continuing.
+3. **Present the implementation catalog (below) as a selection list and ASK the user which
+   implementation(s) to integrate.** Use an interactive multi-select prompt (`AskUserQuestion`,
+   `multiSelect: true`). The list options are the rows of the *Implementation catalog*.
+   - The user MAY select **more than one** (e.g., `MsGraph` for production + `File` for local dev).
+   - If more than one is selected, **ask a follow-up single-select**: *which one is the default
+     (active) provider?* — this becomes `options.Provider`.
+   - If the user selects exactly one, that one is the default.
+4. **Apply “Common steps” once** (§Common steps) — abstraction package + registration scaffold.
+5. **For each selected implementation, apply its block** under §Implementation blocks — add its
+   package, its `Use…` call inside the `AddEmailMessaging` builder, and its config section.
+6. **Set the default provider:** `configureOptions: options => options.Provider = "<default key>"`.
+   All selected implementations stay registered; the active one is switchable later via config.
+7. **(Optional) Wire a usage example** in the relevant feature handler (§Usage).
+8. **Verify** (§Verification) and report what was added.
+
+> **Guardrail — always set `options.Provider`.** When `Provider` is null the facade falls back to a
+> **hardcoded `"SendGrid"`** key; if SendGrid is not registered, resolution throws at runtime. Never
+> rely on the implicit fallback.
+
+---
+
+## Implementation catalog (selection list)
+
+Present these as the multi-select options. `Key` is the provider key and the `Use…` method suffix.
+
+| Key | Implementation | Best for | Package (v) | Required settings |
+|---|---|---|---|---|
+| `MsGraph` | Microsoft 365 / Graph API | Production on an O365 tenant | `AppWeaver.Messaging.Email.MsGraph` (0.1.2) | `TenantId`, `ClientId`, `ClientSecret`, `DefaultFrom` |
+| `Smtp` | Classic SMTP | Any SMTP server | `AppWeaver.Messaging.Email.Smtp` (0.1.3) | `Host`, `Port`, `Username`, `Password`, `EnableSsl` |
+| `SendGrid` | SendGrid API | SendGrid accounts | `AppWeaver.Messaging.Email.SendGrid` (0.1.2) | `ApiKey` *(required)*, `DefaultFrom` |
+| `OAuth2` | OAuth2-authenticated SMTP | O365 SMTP with OAuth2 | `AppWeaver.Messaging.Email.OAuth2` (0.1.3) | `TenantId`, `ClientId`, `ClientSecret`, `Host`, `Port` |
+| `File` | Writes email to a local `.txt` | Local dev / tests (no real send) | `AppWeaver.Messaging.Email.File` (0.1.2) | `DefaultFrom` |
+
+> Recommended pairing: **`MsGraph` (default) + `File`** so developers can run locally without
+> sending real mail, while production uses Graph.
+
+---
+
+## Common steps (apply once, regardless of selection)
+
+### C1 — Abstraction package version
+
+**File:** `Directory.Packages.props` (versions live here only — see [[dependency-policy]])
+
+```xml
+<ItemGroup>
+  <!-- AppWeaver — Email (abstraction) -->
+  <PackageVersion Include="AppWeaver.Messaging.Email" Version="0.1.3" />
+  <!-- + one <PackageVersion> per selected implementation — see each block below -->
+</ItemGroup>
+```
+
+### C2 — Project references
+
+**File:** `src/<SampleProjectName>.Application/<SampleProjectName>.Application.csproj`
+
+```xml
+<ItemGroup>
+  <PackageReference Include="AppWeaver.Messaging.Email" />   <!-- no Version= -->
+</ItemGroup>
+```
+
+**File:** `src/<SampleProjectName>.Infrastructure/<SampleProjectName>.Infrastructure.csproj`
+(add the abstraction here too, plus each selected implementation’s package — see its block).
+
+```xml
+<ItemGroup>
+  <PackageReference Include="AppWeaver.Messaging.Email" />
+</ItemGroup>
+```
+
+### C3 — Registration scaffold
+
+**File:** `src/<SampleProjectName>.Infrastructure/Extensions/InfrastructureServiceRegistration.cs`
+
+Add the base call; each selected implementation contributes one `builder.Use…(…)` line (C4).
+
+```csharp
+using AppWeaver.Messaging.Email.Extensions;
+// + one using per selected implementation (see its block)
+
+services.AddEmailMessaging(
+    configureBuilder: builder =>
+    {
+        // ⬇ one Use…() call per selected implementation is inserted here
+    },
+    configureOptions: options => options.Provider = "<default key>");   // step 6
+```
+
+### C4 — Base appsettings block
+
+**File:** `src/<SampleProjectName>.Service/appsettings.json`
+
+```jsonc
+{
+  "Messaging": {
+    "Email": {
+      "DefaultFrom": "no-reply@your-domain.com",
+      "AdminEmail":  "admin@your-domain.com"
+    }
+  }
+}
+```
+
+---
+
+## Implementation blocks
+
+For each implementation the user selected, do all three sub-steps: **package**, **registration
+line**, **config**. Secrets MUST be supplied via user-secrets / env / key vault — never committed.
+
+### MsGraph
+```xml
+<!-- Directory.Packages.props --> <PackageVersion Include="AppWeaver.Messaging.Email.MsGraph" Version="0.1.2" />
+<!-- Infrastructure.csproj   --> <PackageReference Include="AppWeaver.Messaging.Email.MsGraph" />
+```
+```csharp
+using AppWeaver.Messaging.Email.MsGraph.Extensions;
+// inside AddEmailMessaging builder:
+builder.UseMsGraph(o =>
+{
+    o.TenantId     = configuration["Messaging.Email.MsGraph:TenantId"];
+    o.ClientId     = configuration["Messaging.Email.MsGraph:ClientId"];
+    o.ClientSecret = configuration["Messaging.Email.MsGraph:ClientSecret"]; // user-secrets
+    o.DefaultFrom  = configuration["Messaging:Email:DefaultFrom"];
+});
+```
+```jsonc
+// appsettings.json — secret set out-of-band:
+//   dotnet user-secrets set "Messaging.Email.MsGraph:ClientSecret" "<secret>"
+"Messaging.Email.MsGraph": { "TenantId": "<guid>", "ClientId": "<guid>", "DefaultFrom": "no-reply@your-domain.com" }
+```
+
+### Smtp
+```xml
+<PackageVersion Include="AppWeaver.Messaging.Email.Smtp" Version="0.1.3" />
+<PackageReference Include="AppWeaver.Messaging.Email.Smtp" />
+```
+```csharp
+using AppWeaver.Messaging.Email.Smtp.Extensions;
+builder.UseSmtp(o =>
+{
+    o.Host = configuration["Messaging.Email.Smtp:Host"]!;
+    o.Port = int.Parse(configuration["Messaging.Email.Smtp:Port"] ?? "587");
+    o.Username = configuration["Messaging.Email.Smtp:Username"]!;
+    o.Password = configuration["Messaging.Email.Smtp:Password"]!;   // user-secrets
+    o.EnableSsl = true;
+    o.DefaultFrom = configuration["Messaging:Email:DefaultFrom"];
+});
+```
+```jsonc
+"Messaging.Email.Smtp": { "Host": "smtp.example.com", "Port": 587, "Username": "<user>", "EnableSsl": true }
+```
+> Note: the `SendAsync(from,to,…)` convenience overload of the SMTP service writes to a file; the
+> `EmailMessage` overload performs the real SMTP send. Use `SendAsync(EmailMessage, ct)` for delivery.
+
+### SendGrid
+```xml
+<PackageVersion Include="AppWeaver.Messaging.Email.SendGrid" Version="0.1.2" />
+<PackageReference Include="AppWeaver.Messaging.Email.SendGrid" />
+```
+```csharp
+using AppWeaver.Messaging.Email.SendGrid.Extensions;
+builder.UseSendGrid(o =>
+{
+    o.ApiKey = configuration["Messaging.Email.SendGrid:ApiKey"]!;   // [Required] — user-secrets
+    o.DefaultFrom = configuration["Messaging:Email:DefaultFrom"];
+});
+```
+> `ApiKey` is `[Required]` and validates on startup — a missing key fails app boot, not the first send.
+
+### OAuth2
+```xml
+<PackageVersion Include="AppWeaver.Messaging.Email.OAuth2" Version="0.1.3" />
+<PackageReference Include="AppWeaver.Messaging.Email.OAuth2" />
+```
+```csharp
+using AppWeaver.Messaging.Email.OAuth2.Extensions;
+builder.UseOAuth2(o =>
+{
+    o.TenantId = configuration["Messaging.Email.OAuth2:TenantId"];
+    o.ClientId = configuration["Messaging.Email.OAuth2:ClientId"];
+    o.ClientSecret = configuration["Messaging.Email.OAuth2:ClientSecret"]; // user-secrets
+    o.Host = "smtp.office365.com"; o.Port = 587;
+    o.DefaultFrom = configuration["Messaging:Email:DefaultFrom"];
+});
+```
+
+### File
+```xml
+<PackageVersion Include="AppWeaver.Messaging.Email.File" Version="0.1.2" />
+<PackageReference Include="AppWeaver.Messaging.Email.File" />
+```
+```csharp
+using AppWeaver.Messaging.Email.File.Extensions;
+builder.UseFile(o => o.DefaultFrom = configuration["Messaging:Email:DefaultFrom"]);
+```
+> Pass `DefaultFrom` **inline** as shown. The File provider’s config binder reads the
+> `Messaging.Email.Smtp` section (a known quirk), so do not rely on a `Messaging.Email.File` config
+> section. Output is written to `Emails_<yyyy-MM-dd>.txt` in `AppContext.BaseDirectory`.
+
+---
+
+## Usage (inject the abstraction in a feature handler)
+
+Email is a side effect of a business operation — call it from the Application command handler that
+owns the operation (see [[cqrs]], [[vertical-slices]]). Inject **`IEmailService`**, never a provider.
+
+```csharp
+using AppWeaver.Messaging.Email;
+
+public class CreateUserCommandHandler(IEmailService _email, IConfiguration _config /* … */)
+    : ICommandHandler<CreateUserCommand, Result<UserDto>>
+{
+    public async ValueTask<Result<UserDto>> Handle(CreateUserCommand req, CancellationToken ct)
+    {
+        // … persist aggregate …
+        var from = _config["Messaging:Email:DefaultFrom"]!;
+        var to   = _config["Messaging:Email:AdminEmail"]!;
+        await _email.SendAsync(from, to, $"New user: {req.Name}", "<p>Created.</p>", ct: ct);
+        return Result<UserDto>.Ok(/* dto */);
+    }
+}
+```
+
+Multi-recipient / attachments — use the `EmailMessage` overload (To/Cc/Bcc + `EmailAttachment`,
+see [README.md](./README.md)).
+
+---
+
+## Verification
+
+1. **Builds** — `dotnet build` succeeds; no `Version=` on package references.
+2. **Startup validates** — app boots; options `ValidateOnStart()` passes; `options.Provider` equals
+   one of the selected keys.
+3. **Resolves** — `IEmailService` resolves from DI.
+4. **Sends** — a send succeeds; for `File`, confirm `Emails_<yyyy-MM-dd>.txt` appears in the app
+   base directory.
+5. **No secrets in diff** — `git diff` shows no secret / API key / password literals.
+
+## Related
+
+- [README.md](./README.md) · [[components-readme]] · [[cqrs]] · [[clean-architecture]] ·
+  [[vertical-slices]] · [[dependency-policy]] · [[ai-rules]]

package/assets/docs/components/Jobs/README.md

@@ -0,0 +1,113 @@
+# Jobs Component (`AppWeaver.Jobs`)
+
+> Pure technology (domain-agnostic). Reference sheet for the background-job component.
+> To wire it into a project, follow the agent runbook in [integration.md](./integration.md).
+> Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
+
+## What it is
+
+A plug-and-play background-job framework. Application code depends only on the `IJobScheduler`
+and `IJobProgress` abstractions; the engine (Quartz.NET, optionally with EF Core status
+persistence) is a single registration decision. Supports **fire-and-forget**, **delayed**, and
+**recurring (CRON)** jobs with progress tracking, status polling, and cooperative cancellation.
+
+**Use when:** work must run outside the request thread — exports, batch processing, archival,
+report generation, scheduled maintenance, sending bulk notifications.
+
+## Public contract (`AppWeaver.Jobs.Abstractions`)
+
+```csharp
+public interface IJob { }   // marker — implement on every job class
+
+public interface IJobScheduler
+{
+    Task<string> EnqueueAsync<TJob>(Expression<Func<TJob, Task>> jobMethod,
+        string? description = null, string? userId = null) where TJob : class, IJob;
+
+    Task<string> ScheduleAsync<TJob>(Expression<Func<TJob, Task>> jobMethod, TimeSpan delay,
+        string? description = null, string? userId = null) where TJob : class, IJob;
+
+    Task AddOrUpdateRecurringAsync<TJob>(string jobId,
+        Expression<Func<TJob, Task>> jobMethod, string cronExpression) where TJob : class, IJob;
+
+    Task RemoveRecurringAsync(string jobId);
+    Task<JobStatus?> GetStatusAsync(string jobId);
+    Task<IEnumerable<JobStatus>> GetStatusesAsync(string userId, DateTime? from = null, DateTime? to = null);
+    Task CancelAsync(string jobId);
+}
+
+public interface IJobProgress
+{
+    Task ReportProgressAsync(int percent, string? message = null, object? progressDetails = null);
+    Task ReportResultUrlAsync(string url);
+    CancellationToken CancellationToken { get; }   // check inside loops for cooperative cancel
+}
+```
+
+`JobStatus` carries: `JobId`, `State`, `CreatedAt`, `StartedAt`, `CompletedAt`, `ProgressPercent`,
+`ProgressMessage`, `ResultUrl`, `ErrorMessage`, `Description`, `UserId`, `ProgressDetails`.
+`JobState` = `Pending → Running → Completed | Failed | Cancelled`.
+
+## Packages
+
+| Package | Version | Role | Builder method |
+|---|---|---|---|
+| `AppWeaver.Jobs` | `0.1.1` | **Required.** Abstractions + `AddAppWeaverJobs` + facade. | — |
+| `AppWeaver.Jobs.Quartz` | `0.1.0` | **Recommended engine.** Quartz.NET scheduler; in-memory or persistent store. | `UseQuartzJobScheduler` |
+| `AppWeaver.Jobs.Persistence.EfCore` | `0.1.0` | EF Core persistence of `JobStatus`. | `UseEfCoreJobs` + `UseJobDatabase` / `UseAppWeaverDataStore` |
+| `AppWeaver.Jobs.InMemory` | `0.1.0` | ⚠️ **Work in progress — not functional. Do not use.** | — |
+
+**Recommended stack:** `AppWeaver.Jobs` + `AppWeaver.Jobs.Quartz` + `AppWeaver.Jobs.Persistence.EfCore`.
+
+## Registration shapes
+
+```csharp
+// In AppWeaver.Jobs.Extensions
+IComponentBuilder<IJobScheduler> AddAppWeaverJobs(
+    this IServiceCollection services,
+    Action<IComponentBuilder<IJobScheduler>> configureBuilder,  // required
+    Action<JobsConfiguration>? configureOptions = null,         // set Provider = "Quartz"
+    IConfiguration? configuration = null);                      // OR bind "AppWeaver:Jobs"
+
+// In AppWeaver.Jobs.Quartz.Extensions
+builder.UseQuartzJobScheduler(opts => { opts.MaxConcurrency = 10; opts.ConfigureQuartz = q => { … }; });
+
+// In AppWeaver.Jobs.Persistence.EfCore.Extensions  (choose ONE store wiring)
+builder.UseEfCoreJobs().UseJobDatabase(opts => opts.UseSqlite("Data Source=jobs.db")); // standalone
+builder.UseEfCoreJobs().UseAppWeaverDataStore();                                       // shared DataStore
+```
+
+`JobsConfiguration.Provider` (config section `AppWeaver:Jobs`) selects the engine key; for Quartz
+it is `"Quartz"`. `UseQuartzJobScheduler` registers `IJobProgress` (`QuartzJobProgress`) and a
+Quartz hosted service automatically.
+
+## Persistence modes (EF Core)
+
+| Mode | Wiring | DbContext | Migration |
+|---|---|---|---|
+| **Standalone** | `.UseJobDatabase(opts => opts.UseXxx(conn))` | dedicated `JobStatusDbContext` | own migration / `EnsureCreated` |
+| **Shared DataStore** | `.UseAppWeaverDataStore()` (after `AddDataStore().UseEfCoreDataStore()`) | shares DataStore connection | Shared: in `SharedComponentDbContext` migration; Isolated: own migration |
+
+The Quartz **persistent store** (for distributed/durable scheduling) is configured separately via
+`opts.ConfigureQuartz = q => q.UsePersistentStore(...)` and needs the Quartz DDL applied to the DB.
+With no `ConfigureQuartz`, Quartz uses an in-memory store (single instance, lost on restart).
+
+## Source map (framework)
+
+```
+framework/Jobs/
+  README.md                              ← full component manual (authoritative deep-dive)
+  src/
+    AppWeaver.Jobs/                      ← IJob, IJobScheduler, IJobProgress, JobStatus, AddAppWeaverJobs
+    AppWeaver.Jobs.Quartz/               ← UseQuartzJobScheduler + QuartzJobScheduler/Wrapper/Progress
+    AppWeaver.Jobs.Persistence.EfCore/   ← UseEfCoreJobs/UseJobDatabase/UseAppWeaverDataStore
+    AppWeaver.Jobs.InMemory/             ← ⚠️ WIP, not functional
+  tests/
+    AppWeaver.Jobs.Tests/                ← DefaultJobSchedulerTests
+    TestApp/                             ← Quartz + EF Core end-to-end scenarios (A–O)
+```
+
+## Related
+
+- [integration.md](./integration.md) · [[components-readme]] · [[cqrs]] ·
+  [[persistence]] · [[clean-architecture]] · [[dependency-policy]]