aw-spec-cli 0.1.4 → 0.1.6

package/assets/docs/UI.Visualization/unpack-reference-foundation.sh

@@ -1,218 +0,0 @@
-#!/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 ./UI.Visualization.Reference.pack.txt \
-#       --target-app-name MyApp \
-#       --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/docs/VerticalSlice/PACKAGING.md

@@ -1,185 +0,0 @@
-# VerticalSlice — Foundation Packaging Rules
-
-> **Why this exists.** The old `/aw-spec-foundation` skill *reconstructed* every project
-> file from prose rule docs. Any omission or namespace drift produced a broken,
-> non-compiling skeleton. This packaging model replaces reconstruction with a
-> **byte-for-byte bundle of a real, verified solution**.
->
-> You build the foundation **once** (a solution that actually compiles and runs),
-> pack it into a single text file, and the scaffolder just **unpacks + renames** it.
-> No regeneration, no drift.
-
----
-
-## The single artifact
-
-```
-docs/VerticalSlice/
-├── VerticalSlice.pack.txt      ← THE BUNDLE: every source file, in one text file
-├── PACKAGING.md                ← this file (how to build the bundle)
-├── pack-foundation.ps1         ← produces VerticalSlice.pack.txt from a solution
-└── unpack-foundation.ps1       ← extracts + renames into a target app (used by the skill)
-```
-
-The bundle is the single source of truth for scaffolding. The engineering standards
-the foundation solution must satisfy (vertical slices, DDD, CQRS, persistence, etc.)
-live in the project constitution and the domain-specs rule files, not in this folder.
-
----
-
-## The sentinel convention
-
-You author the foundation solution under one fixed **sentinel app name**:
-
-```
-AppWeaver.Foundation
-```
-
-This is the placeholder that the scaffolder rewrites into the caller's app name.
-It must be a **distinctive two-segment token** that is **not a prefix of any
-`AppWeaver.*` NuGet package** (it isn't — there is no `AppWeaver.Foundation` package),
-so a full-token replacement can never clobber a framework reference.
-
-The scaffolder rewrites the sentinel in **four case forms** (ordinal, case-sensitive),
-applied to **file contents and to file/folder paths**:
-
-| Form        | Sentinel               | Example target (`AppWeaver.Health`) | Where it appears                                  |
-|-------------|------------------------|-------------------------------------|---------------------------------------------------|
-| dotted      | `AppWeaver.Foundation` | `AppWeaver.Health`                  | namespaces, `.csproj`/`.sln` names, project refs  |
-| underscored | `AppWeaver_Foundation` | `AppWeaver_Health`                  | Aspire project class names (`Projects.X_Service`) |
-| lower-hyphen| `appweaver-foundation` | `appweaver-health`                  | `UserSecretsId`, db/container names               |
-| lower-dot   | `appweaver.foundation` | `appweaver.health`                  | any lowercased identifiers                         |
-
-**Never** rename the bare `AppWeaver` company segment on its own — only the full
-sentinel token in the forms above. The framework packages (`AppWeaver.Mediator`,
-`AppWeaver.Repository`, …) stay exactly as written.
-
-### What does NOT get renamed
-
-- `AppWeaver.*` framework package references (`Directory.Packages.props`, every `.csproj`).
-- The sample domain folder **`Projects`** (aggregate `Project`, `CreateProject`, etc.).
-  This is intentional sample content the caller renames to their own bounded context later.
-- `<Company>` / `<Authors>` metadata in `Directory.Build.props` (display-only; edit manually if desired).
-
----
-
-## How to author the foundation solution (do this once)
-
-1. **Pick a scratch folder** outside `docs/`, e.g.
-   `E:\Work\Bytestrone\AppWeaver\Testing\AppWeaver.Spec\.foundation-build\`.
-2. **Create the solution under the sentinel name** `AppWeaver.Foundation`, following the
-   engineering standards in the project constitution and domain-specs rule files:
-   ```
-   AppWeaver.Foundation.sln
-   global.json
-   Directory.Build.props
-   Directory.Packages.props
-   src/
-     AppWeaver.Foundation.AppHost/
-     AppWeaver.Foundation.ServiceDefaults/
-     AppWeaver.Foundation.Service/        (includes the sample 'Projects' domain)
-     AppWeaver.Foundation.Web/
-   ```
-3. **Make it actually work.** This is the whole point — the bundle is only as good as
-   the solution you pack. Verify before packing:
-   ```powershell
-   dotnet restore .foundation-build/AppWeaver.Foundation.sln
-   dotnet build   .foundation-build/AppWeaver.Foundation.sln -c Debug
-   # optional end-to-end:
-   dotnet run --project .foundation-build/src/AppWeaver.Foundation.AppHost
-   ```
-   Fix every error and warning-as-error here, in the real project, where the compiler
-   tells you exactly what's wrong. The packed bundle inherits this correctness.
-4. **Use the sentinel everywhere** the app name belongs: namespaces, project/folder
-   names, `UserSecretsId`, the Aspire db resource name, container names. Use the correct
-   case form for each (see table above).
-
----
-
-## How to build the bundle
-
-From `docs/VerticalSlice/`:
-
-```powershell
-# This foundation intentionally ships the org-internal Azure Artifacts PAT in NuGet.config,
-# so the secret guard must be overridden with -AllowSecrets (org-internal use only — rotate periodically).
-./pack-foundation.ps1 -SourceDir ../../.foundation-build -OutFile ./VerticalSlice.pack.txt -AllowSecrets
-```
-
-The packer:
-
-- walks the solution, **excluding** build/IDE artifacts and secret-bearing files:
-  - dirs: `bin obj .vs .git .idea .vscode TestResults node_modules packages App_Data artifacts .next logs`
-  - files: `*.user *.suo *.DotSettings.user *.db *.db-shm *.db-wal *.sqlite *.log`
-    and **secrets**: `.env.* *.pfx *.pem *.key *.snk id_rsa id_rsa.pub secrets.json`;
-    > The root **`.env` is bundled on purpose** (required sample config); only per-environment
-    > overrides (`.env.local`, `.env.production`, …) are excluded. Keep the bundle org-internal
-    > and rotate any real values — the content scan still blocks PATs/keys regardless of filename.
-- **fails closed on detected secrets** — it scans file *contents* for credential markers
-  (`ClearTextPassword`, private-key blocks, AWS keys, Azure DevOps PAT patterns) and
-  **refuses to pack** if any are found, unless you pass `-AllowSecrets`. This is what stops
-  a `NuGet.config` PAT from being baked into the committed bundle. **Fix the source** (rotate
-  the secret, switch the feed to env/CLI auth) rather than overriding the guard;
-- stores text files **verbatim** and binary files (e.g. a `.png`) **base64-encoded**;
-- writes a header (foundation, sentinel, file count, format version, replacement contract);
-- **warns** if the sentinel token appears in zero files (a sign you used the wrong name).
-
-> **Credentials in a scaffold.** The bundled `NuGet.config` should contain only feed
-> *definitions* and `packageSourceMapping` — never `<packageSourceCredentials>`. Developers
-> authenticate to private feeds with `dotnet nuget` / the Azure Artifacts credential provider
-> / environment variables, not a checked-in PAT.
-
-Re-run it whenever the foundation changes; commit the regenerated `VerticalSlice.pack.txt`.
-
----
-
-## Pack file format (`aw-spec-pack/v1`)
-
-```
-# AW-SPEC FOUNDATION PACK
-# foundation: VerticalSlice
-# sentinel: AppWeaver.Foundation
-# generated: 2026-06-14T10:00:00.0000000Z
-# files: 47
-# format: aw-spec-pack/v1
-# --- replacement contract ... ---
-# ============================================================
-
-<<<FILE path="Directory.Build.props">>>
-...verbatim file content...
-<<<ENDFILE>>>
-<<<FILE path="src/AppWeaver.Foundation.AppHost/Program.cs">>>
-...verbatim file content...
-<<<ENDFILE>>>
-<<<FILE path="src/AppWeaver.Foundation.Web/wwwroot/favicon.ico" encoding="base64">>>
-AAABAAE...
-<<<ENDFILE>>>
-```
-
-- Paths are repo-root-relative with `/` separators.
-- The marker lines `<<<FILE …>>>` and `<<<ENDFILE>>>` are **reserved** — they must never
-  occur as a literal line inside a source file (they can't in C#/XML/JSON/Razor).
-- `encoding="base64"` marks a binary file; everything else is UTF-8 text.
-
----
-
-## How scaffolding consumes the bundle
-
-`/aw-spec-foundation VerticalSlice <AppName> [OutputDir]` runs `unpack-foundation.ps1`,
-which reads the sentinel from the pack header, derives the four target case forms, and
-writes the renamed files to the output directory (**repo root by default**). See
-`.claude/skills/aw-spec-foundation/SKILL.md`.
-
-```powershell
-./unpack-foundation.ps1 -PackFile ./VerticalSlice.pack.txt -TargetAppName AppWeaver.Health -OutDir ../../ 
-```
-
----
-
-## Maintenance checklist
-
-- [ ] Foundation solution builds clean (`dotnet build`, warnings-as-errors satisfied).
-- [ ] Sentinel `AppWeaver.Foundation` used consistently in all four case forms.
-- [ ] No `bin/obj/.vs` or local `.db` files committed into the pack.
-- [ ] `pack-foundation.ps1` reported a non-zero sentinel hit count.
-- [ ] `VerticalSlice.pack.txt` regenerated and committed after any change.