aw-spec-cli 0.1.21 → 0.1.23

package/assets/foundations/java/Hexagonal/unpack-foundation.sh

@@ -0,0 +1,399 @@
+#!/usr/bin/env bash
+#
+# unpack-foundation.sh — Java foundation unpacker for AW-Spec
+#
+# Unpacks an AW-Spec Java foundation pack into a target application,
+# replacing the Java package sentinel with the target application package.
+#
+# Java foundation contract:
+#   Sentinel: io.appweaver
+#
+# Example:
+#   ./unpack-foundation.sh \
+#       --pack-file ./Hexagonal.pack.txt \
+#       --target-app-name FlightBooking \
+#       --out-dir backend
+#
+
+set -euo pipefail
+
+# ----------------------------------------------------------- defaults --------------
+
+PACK_FILE=''
+TARGET_APP_NAME=''
+OUT_DIR='src'
+SENTINEL=''
+FORCE=0
+DRYRUN=0
+
+# ----------------------------------------------------------- usage ----------------
+
+usage() {
+  cat <<'EOF'
+Usage:
+  unpack-foundation.sh \
+    --pack-file <pack-file> \
+    --target-app-name <app-name> \
+    --out-dir <output-dir> \
+    [--sentinel <sentinel>] \
+    [--force] \
+    [--dry-run]
+
+Options:
+  --pack-file        Foundation pack file.
+  --target-app-name  Target application name.
+  --out-dir          Output directory.
+  --sentinel         Optional sentinel override.
+  --force             Allow existing destination files to be overwritten.
+  --dry-run           Show what would be written without changing files.
+  -h, --help          Show this help.
+EOF
+}
+
+# ----------------------------------------------------------- error -----------------
+
+error() {
+  echo "Error: $*" >&2
+  exit 1
+}
+
+# ----------------------------------------------------------- arguments ------------
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --pack-file)
+      [ "$#" -ge 2 ] || error "--pack-file requires a value"
+      PACK_FILE="$2"
+      shift 2
+      ;;
+
+    --target-app-name)
+      [ "$#" -ge 2 ] || error "--target-app-name requires a value"
+      TARGET_APP_NAME="$2"
+      shift 2
+      ;;
+
+    --out-dir)
+      [ "$#" -ge 2 ] || error "--out-dir requires a value"
+      OUT_DIR="$2"
+      shift 2
+      ;;
+
+    --sentinel)
+      [ "$#" -ge 2 ] || error "--sentinel requires a value"
+      SENTINEL="$2"
+      shift 2
+      ;;
+
+    --force)
+      FORCE=1
+      shift
+      ;;
+
+    --dry-run)
+      DRYRUN=1
+      shift
+      ;;
+
+    -h|--help)
+      usage
+      exit 0
+      ;;
+
+    *)
+      error "Unknown argument: $1"
+      ;;
+  esac
+done
+
+# ----------------------------------------------------------- validate args ----------
+
+[ -n "$PACK_FILE" ] || error "--pack-file is required"
+[ -n "$TARGET_APP_NAME" ] || error "--target-app-name is required"
+
+[ -f "$PACK_FILE" ] || error "Pack file not found: $PACK_FILE"
+
+case "$TARGET_APP_NAME" in
+  *[!A-Za-z0-9._-]*)
+    error "Invalid application name '$TARGET_APP_NAME'. Allowed characters: A-Z a-z 0-9 . _ -"
+    ;;
+esac
+
+# ----------------------------------------------------------- read pack metadata ----
+
+PACK_SENTINEL=''
+
+while IFS= read -r line || [ -n "$line" ]; do
+  line="${line%$'\r'}"
+
+  case "$line" in
+    '# sentinel: '*)
+      PACK_SENTINEL="${line#'# sentinel: '}"
+      break
+      ;;
+  esac
+done < "$PACK_FILE"
+
+if [ -n "$SENTINEL" ]; then
+  :
+elif [ -n "$PACK_SENTINEL" ]; then
+  SENTINEL="$PACK_SENTINEL"
+else
+  error "Could not determine sentinel from pack. Use --sentinel."
+fi
+
+[ -n "$SENTINEL" ] || error "Sentinel cannot be empty"
+
+# ----------------------------------------------------------- Java replacement -------
+
+#
+# Java package rules:
+#
+#   io.appweaver
+#       ->
+#   <lowercase application name>
+#
+#   io/appweaver
+#       ->
+#   <lowercase application name>
+#
+# The application directory itself keeps the original user-provided
+# application name/casing.
+#
+
+TARGET_PACKAGE="$(printf '%s' "$TARGET_APP_NAME" | tr '[:upper:]' '[:lower:]')"
+
+S_DOT="$SENTINEL"
+T_DOT="$TARGET_PACKAGE"
+
+S_PATH="$(printf '%s' "$SENTINEL" | tr '.' '/')"
+T_PATH="$TARGET_PACKAGE"
+
+FROM=()
+TO=()
+
+add_form() {
+  FROM+=("$1")
+  TO+=("$2")
+}
+
+add_form "$S_DOT" "$T_DOT"
+add_form "$S_PATH" "$T_PATH"
+
+# ----------------------------------------------------------- replacement ------------
+
+#
+# Apply replacements from longest source string to shortest.
+# This avoids partial replacement problems when one replacement
+# string is a prefix of another.
+#
+
+apply_repl() {
+  local input="$1"
+  local i
+  local from
+  local to
+
+  REPL_OUT="$input"
+
+  for i in "${!FROM[@]}"; do
+    from="${FROM[$i]}"
+    to="${TO[$i]}"
+
+    REPL_OUT="${REPL_OUT//$from/$to}"
+  done
+}
+
+# ----------------------------------------------------------- output root ------------
+
+if [ "$OUT_DIR" = "." ]; then
+  OUT_ROOT="$TARGET_APP_NAME"
+else
+  OUT_ROOT="$OUT_DIR/$TARGET_APP_NAME"
+fi
+
+# ----------------------------------------------------------- parse pack blocks -------
+
+rels=()
+encs=()
+contents=()
+dir_rels=()
+
+in_block=0
+cur_rel=''
+cur_enc=''
+cur_content=''
+first_line=1
+
+file_re='^<<<FILE path="([^"]+)"( encoding="([^"]+)")?>>>[[:space:]]*$'
+dir_re='^<<<DIR path="([^"]+)">>>[[: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=''
+
+    elif [[ "$line" =~ $dir_re ]]; then
+      dir_rels+=("${BASH_REMATCH[1]}")
+    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 directories ----
+
+is_empty_java_package_parent() {
+  local rel="$1"
+
+  case "$rel" in
+    src/main/java/io|src/test/java/io)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+dir_dests=()
+
+for rel in "${dir_rels[@]}"; do
+  if is_empty_java_package_parent "$rel"; then
+    continue
+  fi
+
+  apply_repl "$rel"
+  dir_dests+=("$OUT_ROOT/$REPL_OUT")
+done
+
+# ----------------------------------------------------------- resolve files ----------
+
+dests=()
+
+for rel in "${rels[@]}"; do
+  apply_repl "$rel"
+  dests+=("$OUT_ROOT/$REPL_OUT")
+done
+
+# ----------------------------------------------------------- conflict guard ----------
+
+if [ "$FORCE" -eq 0 ] && [ "$DRYRUN" -eq 0 ]; then
+
+  for dest in "${dests[@]}"; do
+    if [ -e "$dest" ]; then
+      error "Destination already exists: $dest (use --force to overwrite)"
+    fi
+  done
+
+fi
+
+# ----------------------------------------------------------- base64 decoder ----------
+
+decode_base64() {
+  if base64 --help 2>&1 | grep -q -- '--decode'; then
+    base64 --decode
+  else
+    base64 -D
+  fi
+}
+
+# ----------------------------------------------------------- create directories -------
+
+directories_created=0
+
+if [ "$DRYRUN" -eq 1 ]; then
+
+  for dest in "${dir_dests[@]}"; do
+    echo "WOULD CREATE DIRECTORY  $dest"
+  done
+
+else
+
+  for dest in "${dir_dests[@]}"; do
+    mkdir -p "$dest"
+    directories_created=$((directories_created + 1))
+  done
+
+fi
+
+# ----------------------------------------------------------- write files -------------
+
+written=0
+
+if [ "$DRYRUN" -eq 1 ]; then
+
+  for i in "${!rels[@]}"; do
+    echo "WOULD WRITE  ${dests[$i]}"
+  done
+
+else
+
+  for i in "${!rels[@]}"; do
+
+    dest="${dests[$i]}"
+    enc="${encs[$i]}"
+    content="${contents[$i]}"
+
+    mkdir -p "$(dirname "$dest")"
+
+    if [ "$enc" = "base64" ]; then
+      printf '%s' "$content" | decode_base64 > "$dest"
+    else
+      apply_repl "$content"
+      printf '%s\n' "$REPL_OUT" > "$dest"
+    fi
+
+    written=$((written + 1))
+
+  done
+
+fi
+
+# ----------------------------------------------------------- summary -----------------
+
+echo
+
+if [ "$DRYRUN" -eq 1 ]; then
+
+  echo "DryRun: ${#rels[@]} file(s) and ${#dir_rels[@]} directorie(s) would be written to:"
+  echo "  $OUT_ROOT"
+
+else
+
+  echo "Unpacked $written file(s) and $directories_created directorie(s) to:"
+  echo "  $OUT_ROOT"
+
+fi
+
+echo "  Sentinel: $SENTINEL"
+echo "  Package:  $TARGET_PACKAGE"

package/assets/guardrails/technology/dotnet-webapi/framework-api-map.md

@@ -50,6 +50,50 @@ The auditing interfaces are the ones most often reported missing: they are in a
 package from the aggregate types, so a project that references `AppWeaver.DomainAbstraction`
 alone cannot see `IAggregateChild` at all. A rule that requires one requires its package.
 
+## The other direction — framework types that shadow DOMAIN names
+
+The map above is about a framework type the code cannot find. The opposite failure is a
+framework type it finds *too easily*: a domain noun that the ambient scope already defines.
+
+`Microsoft.NET.Sdk.Web` turns on implicit usings, so `System`, `System.Collections.Generic`,
+`System.IO`, `System.Threading.Tasks`, `Microsoft.AspNetCore.Http` and
+`Microsoft.AspNetCore.Routing` are in scope in **every** file without appearing in any
+`using` line. A domain type sharing a name with one of theirs — `Route`, `Task`, `Activity`,
+`Path`, `File`, `Timer`, `Index`, `Range`, `Version`, `Results`, `Endpoint`, `Environment`,
+`Stream`, `Type`, `Queue`, `Stack` — is then an **ambiguous reference, CS0104**:
+
+```csharp
+using Acme.Clinic.Service.Care.Domain;     // brings in the domain Route
+
+public static Route? Route(string? value)  // CS0104: Care.Domain.Route
+                                           //      vs Microsoft.AspNetCore.Routing.Route
+```
+
+The conflict is invisible in the file. Nothing in it names `Microsoft.AspNetCore.Routing`,
+so the bare name reads as correct and fails only at build.
+
+**The domain name is not the problem and never changes.** It is the ubiquitous language,
+the plan spells it, and the code spells it back verbatim. What changes is how it is
+written at the use site:
+
+```csharp
+public static Domain.Route? Route(string? value) =>
+    string.IsNullOrWhiteSpace(value) ? null : Domain.Route.From(value);
+```
+
+- **Qualify with the type's own enclosing namespace segment** — `Domain.Route` — at every
+  site the type is named: declarations, parameters, return types, generic arguments and
+  `<see cref="…"/>` comments.
+- **Not a `using` alias and not the full namespace path.** One convention, so two features
+  never disambiguate the same name two ways.
+- **Never rename the domain type** to avoid the clash, and never drop the domain type in
+  favour of the framework one.
+
+`/aw-spec-implement` is told which of *this* plan's element names are affected before it
+writes anything — the list comes from the lane's stack profile (`reserved_names` in
+`.appweaver/stack-profiles/<id>.json`), so it is the same answer on every run rather than
+something each pass has to notice for itself.
+
 ## Rules
 
 - **Cite a framework type with its namespace** in plans and generated code, and add the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aw-spec-cli",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "AppWeaver Spec-Driven Development CLI - scaffolds projects with vertical slices, DDD, CQRS, and agent skills",
   "type": "module",
   "main": "dist/index.js",