aw-spec-cli 0.1.8 → 0.1.10

package/assets/foundations/dotnet/VerticalSlice/unpack-reference-foundation.sh

@@ -0,0 +1,218 @@
+#!/usr/bin/env bash
+#
+# unpack-reference-foundation.sh — bash/macOS port of unpack-reference-foundation.ps1
+#
+# SYNOPSIS
+#   Unpack an AW-Spec reference pack file into a target project, renaming the
+#   sentinel app name to the caller's app name.
+#
+# DESCRIPTION
+#   Reads --pack-file (produced by pack-reference-foundation.sh/.ps1), takes the sentinel
+#   from its header (override with --sentinel), derives four case forms of the target app
+#   name, and writes every file block to --out-dir with the sentinel rewritten in both file
+#   CONTENTS and file/dir PATHS. Text blocks are rewritten and written as UTF-8; base64
+#   blocks are decoded as-is. Refuses to overwrite existing files unless --force.
+#
+# EXAMPLE
+#   ./unpack-reference-foundation.sh \
+#       --pack-file ./VerticalSlice.Reference.pack.txt \
+#       --target-app-name AppWeaver.Pharma \
+#       --out-dir ../../../
+#
+set -euo pipefail
+
+# ------------------------------------------------------------------ defaults ---
+PACK_FILE=''
+TARGET_APP_NAME=''
+OUT_DIR='.'
+SENTINEL=''
+FORCE=0
+DRYRUN=0
+
+usage() {
+  cat >&2 <<'EOF'
+Usage: unpack-reference-foundation.sh --pack-file <file> --target-app-name <name>
+                                      [--out-dir <dir>] [--sentinel <name>]
+                                      [--force] [--dry-run]
+
+  -p, --pack-file <file>        Reference pack file to unpack               (required)
+  -t, --target-app-name <name>  New app name to rename the sentinel into    (required)
+  -o, --out-dir <dir>           Output root                   (default: .)
+      --sentinel <name>         Override the sentinel from the pack header
+      --force                   Overwrite files that already exist
+      --dry-run                 List what would be written, write nothing
+  -h, --help                    Show this help
+
+Positional fallback: unpack-reference-foundation.sh <pack-file> <target-app-name> [out-dir]
+EOF
+}
+
+# -------------------------------------------------------------- arg parsing ---
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -p|--pack-file)        PACK_FILE="${2:?--pack-file needs a value}";             shift 2 ;;
+    -t|--target-app-name)  TARGET_APP_NAME="${2:?--target-app-name needs a value}"; shift 2 ;;
+    -o|--out-dir)          OUT_DIR="${2:?--out-dir needs a value}";                 shift 2 ;;
+    --sentinel)            SENTINEL="${2:?--sentinel needs a value}";               shift 2 ;;
+    --force)               FORCE=1; shift ;;
+    --dry-run)             DRYRUN=1; shift ;;
+    -h|--help)             usage; exit 0 ;;
+    --)                    shift; break ;;
+    -*)                    echo "Error: unknown option: $1" >&2; usage; exit 2 ;;
+    *)
+      if   [ -z "$PACK_FILE" ];       then PACK_FILE="$1"
+      elif [ -z "$TARGET_APP_NAME" ]; then TARGET_APP_NAME="$1"
+      else OUT_DIR="$1"
+      fi
+      shift ;;
+  esac
+done
+
+[ -n "$PACK_FILE" ]       || { echo "Error: --pack-file is required." >&2; usage; exit 2; }
+[ -n "$TARGET_APP_NAME" ] || { echo "Error: --target-app-name is required." >&2; usage; exit 2; }
+[ -f "$PACK_FILE" ]       || { echo "Error: pack file not found: $PACK_FILE" >&2; exit 1; }
+
+case "$TARGET_APP_NAME" in
+  *[!A-Za-z0-9._-]*)
+    echo "Error: --target-app-name may contain only letters, digits, '.', '_' or '-': $TARGET_APP_NAME" >&2
+    exit 2 ;;
+esac
+
+# ------------------------------------------------ sentinel from header --------
+if [ -z "$SENTINEL" ]; then
+  SENTINEL="$(LC_ALL=C sed -n 's/^#[[:space:]]*sentinel:[[:space:]]*\(.*[^[:space:]]\)[[:space:]]*$/\1/p' "$PACK_FILE" | head -n1)"
+fi
+[ -n "$SENTINEL" ] || { echo "Error: Sentinel not found in pack header; supply it with --sentinel." >&2; exit 1; }
+
+# ------------------------------------------------ derive case forms -----------
+to_lower() { printf '%s' "$1" | LC_ALL=C tr '[:upper:]' '[:lower:]'; }
+
+S_DOT="$SENTINEL";               T_DOT="$TARGET_APP_NAME"
+S_UND="${SENTINEL//./_}";        T_UND="${TARGET_APP_NAME//./_}"
+s_low="$(to_lower "$SENTINEL")"; t_low="$(to_lower "$TARGET_APP_NAME")"
+S_HYP="${s_low//./-}";           T_HYP="${t_low//./-}"
+S_LDOT="$s_low";                 T_LDOT="$t_low"
+
+FROM=(); TO=()
+add_form() {
+  local from="$1" to="$2" e
+  [ -n "$from" ] || return 0
+  [ "$from" = "$to" ] && return 0
+  if [ "${#FROM[@]}" -gt 0 ]; then
+    for e in "${FROM[@]}"; do [ "$e" = "$from" ] && return 0; done
+  fi
+  FROM+=("$from"); TO+=("$to")
+}
+add_form "$S_DOT"  "$T_DOT"
+add_form "$S_UND"  "$T_UND"
+add_form "$S_HYP"  "$T_HYP"
+add_form "$S_LDOT" "$T_LDOT"
+
+# Sort indices by FROM length descending
+ORDER=()
+{
+  local_n="${#FROM[@]}"
+  used=(); for ((k = 0; k < local_n; k++)); do used[$k]=0; done
+  for ((pass = 0; pass < local_n; pass++)); do
+    best=-1; bestlen=-1
+    for ((j = 0; j < local_n; j++)); do
+      if [ "${used[$j]}" -eq 0 ] && [ "${#FROM[$j]}" -gt "$bestlen" ]; then
+        bestlen="${#FROM[$j]}"; best="$j"
+      fi
+    done
+    used[$best]=1; ORDER+=("$best")
+  done
+}
+
+REPL_OUT=''
+apply_repl() {
+  local text="$1" idx from to
+  if [ "${#ORDER[@]}" -gt 0 ]; then
+    for idx in "${ORDER[@]}"; do
+      from="${FROM[$idx]}"; to="${TO[$idx]}"
+      text="${text//"$from"/$to}"
+    done
+  fi
+  REPL_OUT="$text"
+}
+
+# ------------------------------------------------ output root ----------------
+[ -d "$OUT_DIR" ] || mkdir -p "$OUT_DIR"
+OUT_ROOT="$(cd "$OUT_DIR" && pwd -P)"
+
+# ------------------------------------------------ base64 decoder (portable) --
+B64D=()
+if   printf 'aGk=' | base64 -d        >/dev/null 2>&1; then B64D=(base64 -d)
+elif printf 'aGk=' | base64 -D        >/dev/null 2>&1; then B64D=(base64 -D)
+elif printf 'aGk=' | base64 --decode  >/dev/null 2>&1; then B64D=(base64 --decode)
+else                                                        B64D=(openssl base64 -d -A)
+fi
+
+# ------------------------------------------------ parse file blocks ----------
+rels=(); encs=(); contents=()
+in_block=0; cur_rel=''; cur_enc=''; cur_content=''; first_line=1
+file_re='^<<<FILE path="([^"]+)"( encoding="([^"]+)")?>>>[[:space:]]*$'
+
+while IFS= read -r line || [ -n "$line" ]; do
+  line="${line%$'\r'}"
+  if [ "$in_block" -eq 0 ]; then
+    if [[ "$line" =~ $file_re ]]; then
+      cur_rel="${BASH_REMATCH[1]}"
+      cur_enc="${BASH_REMATCH[3]:-}"
+      in_block=1; first_line=1; cur_content=''
+    fi
+  else
+    if [ "$line" = '<<<ENDFILE>>>' ]; then
+      rels+=("$cur_rel"); encs+=("$cur_enc"); contents+=("$cur_content")
+      in_block=0
+    elif [ "$first_line" -eq 1 ]; then
+      cur_content="$line"; first_line=0
+    else
+      cur_content="$cur_content"$'\n'"$line"
+    fi
+  fi
+done < "$PACK_FILE"
+
+[ "${#rels[@]}" -gt 0 ] || { echo "Error: No <<<FILE>>> blocks found in pack: $PACK_FILE" >&2; exit 1; }
+
+# ------------------------------------------------ resolve destinations -------
+dests=()
+for ((i = 0; i < ${#rels[@]}; i++)); do
+  apply_repl "${rels[$i]}"
+  dests+=("$OUT_ROOT/$REPL_OUT")
+done
+
+# ------------------------------------------------ conflict guard -------------
+if [ "$FORCE" -eq 0 ] && [ "$DRYRUN" -eq 0 ]; then
+  conflicts=()
+  for d in "${dests[@]}"; do [ -e "$d" ] && conflicts+=("$d"); done
+  if [ "${#conflicts[@]}" -gt 0 ]; then
+    echo "Error: Refusing to overwrite existing files (re-run with --force):" >&2
+    printf '  %s\n' "${conflicts[@]}" >&2
+    exit 1
+  fi
+fi
+
+# ------------------------------------------------ write ----------------------
+written=0
+for ((i = 0; i < ${#rels[@]}; i++)); do
+  rel="${rels[$i]}"; enc="${encs[$i]}"; dest="${dests[$i]}"
+  if [ "$DRYRUN" -eq 1 ]; then
+    echo "WOULD WRITE  $rel  ->  $dest"
+    continue
+  fi
+  mkdir -p "$(dirname "$dest")"
+  if [ "$enc" = 'base64' ]; then
+    printf '%s' "${contents[$i]}" | tr -d '[:space:]' | "${B64D[@]}" > "$dest"
+  else
+    apply_repl "${contents[$i]}"
+    printf '%s' "$REPL_OUT" > "$dest"
+  fi
+  written=$((written + 1))
+done
+
+if [ "$DRYRUN" -eq 1 ]; then
+  echo "DryRun: ${#rels[@]} file(s) would be written to $OUT_ROOT (sentinel '$SENTINEL' -> '$TARGET_APP_NAME')."
+else
+  echo "Unpacked $written file(s) to $OUT_ROOT (sentinel '$SENTINEL' -> '$TARGET_APP_NAME')."
+fi

package/assets/foundations/dotnet/components/Email/README.md

@@ -0,0 +1,119 @@
+# 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: `/appweaver add-component`.
+
+## 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
+```
+
+## Sample reference endpoint
+
+A ready-to-run FastEndpoint that sends mail inline (no command/handler) is bundled at
+[`ReferenceEndpoints/SendEmailEndpoint.cs`](./ReferenceEndpoints/SendEmailEndpoint.cs). It is offered
+(opt-in) at the end of the [integration.md](./integration.md) runbook and, if accepted, copied into
+the host project's `ReferenceEndpoints/` folder. Endpoint: `POST /reference/email/send`.
+
+## Related
+
+- [integration.md](./integration.md) · [[components-readme]] · [[cqrs]] ·
+  [[clean-architecture]] · [[dependency-policy]]

package/assets/foundations/dotnet/components/Email/ReferenceEndpoints/SendEmailEndpoint.cs

@@ -0,0 +1,84 @@
+using FastEndpoints;
+using Microsoft.Extensions.Configuration;
+using AppWeaver.Messaging.Email;
+
+// NOTE: This is a bundled SAMPLE endpoint for the AppWeaver Email component.
+// It lives under foundations/dotnet/components/ and is NOT compiled here. `/appweaver add-component`
+// copies it into the host project's ReferenceEndpoints/ folder and replaces the __HOSTPROJECT__ token
+// with the host project's root namespace (e.g. AppWeaver.Health.Service).
+namespace __HOSTPROJECT__.ReferenceEndpoints;
+
+/// <summary>
+/// Sample reference endpoint for the AppWeaver Email component.
+///
+/// Demonstrates the full send sequence inline — it injects the <see cref="IEmailService"/>
+/// abstraction directly and calls <c>SendAsync</c> with the provider wired during DI
+/// registration (see the component's integration runbook). There is intentionally no
+/// command / command-handler / mediator: this is a copy-paste sample only.
+///
+/// The active transport is whatever <c>options.Provider</c> was set to when
+/// <c>AddEmailMessaging(...)</c> was registered. With the <c>File</c> provider the message is
+/// written to <c>Emails_&lt;yyyy-MM-dd&gt;.txt</c> in the application base directory.
+/// </summary>
+public class SendEmailEndpoint(IEmailService _email, IConfiguration _config)
+    : Endpoint<SendEmailRequest>
+{
+    public override void Configure()
+    {
+        Post("/reference/email/send");
+        AllowAnonymous();
+        Summary(s =>
+        {
+            s.Summary = "Send a sample email via the configured Email provider";
+            s.Description = "Reference endpoint for the AppWeaver Email component. Injects "
+                          + "IEmailService directly (no command/handler). 'from' falls back to "
+                          + "Messaging:Email:DefaultFrom when omitted.";
+        });
+        Options(o => o.WithTags("Reference - Email"));
+    }
+
+    public override async Task HandleAsync(SendEmailRequest req, CancellationToken ct)
+    {
+        if (string.IsNullOrWhiteSpace(req.To) || string.IsNullOrWhiteSpace(req.Subject))
+        {
+            HttpContext.Response.StatusCode = 400;
+            await HttpContext.Response.WriteAsJsonAsync(
+                new { error = "'to' and 'subject' are required." }, ct);
+            return;
+        }
+
+        // 'from' is optional in the request — fall back to the configured DefaultFrom.
+        var from = string.IsNullOrWhiteSpace(req.From)
+            ? _config["Messaging:Email:DefaultFrom"] ?? "no-reply@your-domain.com"
+            : req.From;
+
+        await _email.SendAsync(from, req.To, req.Subject, req.Body ?? string.Empty, req.IsHtml, ct);
+
+        await HttpContext.Response.WriteAsJsonAsync(new
+        {
+            status = "sent",
+            from,
+            to = req.To,
+            note = "With the File provider, output is written to Emails_<yyyy-MM-dd>.txt "
+                 + "in the app base directory."
+        }, ct);
+    }
+}
+
+public class SendEmailRequest
+{
+    /// <summary>Recipient address (required).</summary>
+    public string To { get; set; } = string.Empty;
+
+    /// <summary>Subject line (required).</summary>
+    public string Subject { get; set; } = string.Empty;
+
+    /// <summary>HTML or plain-text body.</summary>
+    public string Body { get; set; } = string.Empty;
+
+    /// <summary>Treat <see cref="Body"/> as HTML. Defaults to true.</summary>
+    public bool IsHtml { get; set; } = true;
+
+    /// <summary>Optional sender; falls back to Messaging:Email:DefaultFrom when omitted.</summary>
+    public string? From { get; set; }
+}