aw-spec-cli 0.1.0 → 0.1.2

package/assets/docs/VerticalSlice/pack-foundation.ps1

@@ -0,0 +1,145 @@
+#requires -Version 5.1
+<#
+.SYNOPSIS
+    Pack a verified foundation solution into a single AW-Spec text pack file.
+
+.DESCRIPTION
+    Walks -SourceDir, excludes build/IDE artifacts, and writes every remaining file
+    into one pack file using <<<FILE>>> / <<<ENDFILE>>> markers. Text files are stored
+    verbatim (UTF-8, LF); binary files are base64-encoded. The resulting pack file is
+    the single bundled artifact consumed by /aw-spec-foundation (see PACKAGING.md).
+
+.EXAMPLE
+    ./pack-foundation.ps1 -SourceDir ../../.foundation-build -OutFile ./VerticalSlice.pack.txt
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)] [string] $SourceDir,
+    [string] $OutFile,
+    [string] $Sentinel    = 'AppWeaver.Foundation',
+    [string] $Foundation  = 'VerticalSlice',
+    [switch] $AllowSecrets
+)
+
+$ErrorActionPreference = 'Stop'
+
+$src = (Resolve-Path -LiteralPath $SourceDir).Path
+if (-not (Test-Path -LiteralPath $src -PathType Container)) {
+    throw "SourceDir is not a folder: $SourceDir"
+}
+if (-not $OutFile) { $OutFile = Join-Path (Get-Location).Path "$Foundation.pack.txt" }
+
+# Entire subtree excluded if any path segment matches one of these
+$excludeDirs  = @('bin','obj','.vs','.git','.idea','.vscode','TestResults','node_modules','packages','App_Data','artifacts','.next','logs')
+# Files excluded by name glob (build noise, local dbs, and secret-bearing files)
+# NOTE: the root '.env' is intentionally NOT excluded — it carries required sample config
+# and is bundled on purpose. Per-environment overrides ('.env.local', '.env.production', ...)
+# stay excluded via the '.env.*' glob. Real credentials are still caught by the content scan.
+$excludeFiles = @(
+    '*.user','*.suo','*.DotSettings.user','*.db','*.db-shm','*.db-wal','*.sqlite','*.log',
+    '.env.*','*.pfx','*.pem','*.key','*.snk','id_rsa','id_rsa.pub','secrets.json'
+)
+
+# Content patterns that indicate a real secret; packing aborts on a hit unless -AllowSecrets.
+$secretPatterns = @(
+    @{ Name = 'NuGet ClearTextPassword'; Rx = 'ClearTextPassword' }
+    @{ Name = 'Private key block';       Rx = 'BEGIN (RSA |OPENSSH |EC |DSA )?PRIVATE KEY' }
+    @{ Name = 'AWS access key id';       Rx = 'AKIA[0-9A-Z]{16}' }
+    @{ Name = 'Azure DevOps PAT-ish';    Rx = '[A-Za-z0-9]{52}AZDO[A-Za-z0-9]' }
+)
+
+function Test-Excluded([string] $relPath) {
+    foreach ($seg in ($relPath -split '[\\/]')) {
+        if ($excludeDirs -contains $seg) { return $true }
+    }
+    $leaf = Split-Path $relPath -Leaf
+    foreach ($g in $excludeFiles) { if ($leaf -like $g) { return $true } }
+    return $false
+}
+
+function Test-Binary([byte[]] $bytes) {
+    $n = [Math]::Min(8000, $bytes.Length)
+    for ($i = 0; $i -lt $n; $i++) { if ($bytes[$i] -eq 0) { return $true } }
+    return $false
+}
+
+# Collect + filter
+$picked = New-Object System.Collections.Generic.List[object]
+foreach ($f in (Get-ChildItem -LiteralPath $src -Recurse -File -Force)) {
+    $rel = ($f.FullName.Substring($src.Length).TrimStart('\','/')) -replace '\\','/'
+    if (Test-Excluded $rel) { continue }
+    $picked.Add([pscustomobject]@{ Rel = $rel; Full = $f.FullName })
+}
+$picked = @($picked | Sort-Object Rel)
+if ($picked.Count -eq 0) { throw "No files to pack under: $src" }
+
+# Secret scan — fail closed so credentials never get baked into the committed bundle
+$findings = New-Object System.Collections.Generic.List[string]
+foreach ($p in $picked) {
+    try {
+        $t = [System.IO.File]::ReadAllText($p.Full)
+    } catch { continue }
+    foreach ($pat in $secretPatterns) {
+        if ($t -match $pat.Rx) { $findings.Add("  $($p.Rel)  ->  $($pat.Name)") }
+    }
+}
+if ($findings.Count -gt 0) {
+    $msg = "Potential secret(s) detected — refusing to pack (rotate + remove them, or pass -AllowSecrets):`n" + ($findings -join "`n")
+    if ($AllowSecrets) { Write-Warning $msg } else { throw $msg }
+}
+
+# Sentinel sanity check
+$hits = 0
+foreach ($p in $picked) {
+    try {
+        $t = [System.IO.File]::ReadAllText($p.Full)
+        if ($t.Contains($Sentinel)) { $hits++ }
+    } catch { }
+}
+if ($hits -eq 0) {
+    Write-Warning "Sentinel '$Sentinel' not found in any file. Did you build the sample under that exact name?"
+} else {
+    Write-Host "Sentinel '$Sentinel' found in $hits file(s)."
+}
+
+# Build the pack (explicit LF newlines throughout)
+$sb = [System.Text.StringBuilder]::new()
+function AddLine([string] $s) { [void]$sb.Append($s); [void]$sb.Append("`n") }
+
+AddLine '# AW-SPEC FOUNDATION PACK'
+AddLine "# foundation: $Foundation"
+AddLine "# sentinel: $Sentinel"
+AddLine "# generated: $([DateTime]::UtcNow.ToString('o'))"
+AddLine "# files: $($picked.Count)"
+AddLine '# format: aw-spec-pack/v1'
+AddLine '# --- replacement contract (ordinal, case-sensitive, longest-first) ---'
+AddLine '#   <Sentinel>           -> <AppName>            (dotted:       namespaces, csproj/sln, refs)'
+AddLine '#   <Sentinel _-form>    -> <AppName _-form>     (underscored:  Aspire project class names)'
+AddLine '#   <sentinel --form>    -> <appname --form>     (lower-hyphen: UserSecretsId, db/containers)'
+AddLine '#   <sentinel .-form>    -> <appname lower-dot>  (lower-dot:    lowercased identifiers)'
+AddLine '# Applied to file CONTENTS and file/dir PATHS. Never touch other AppWeaver.* tokens.'
+AddLine '# ============================================================'
+AddLine ''
+
+foreach ($p in $picked) {
+    $bytes = [System.IO.File]::ReadAllBytes($p.Full)
+    if (Test-Binary $bytes) {
+        AddLine "<<<FILE path=`"$($p.Rel)`" encoding=`"base64`">>>"
+        AddLine ([Convert]::ToBase64String($bytes))
+        AddLine '<<<ENDFILE>>>'
+    } else {
+        $text = ([System.IO.File]::ReadAllText($p.Full)) -replace "`r`n", "`n"
+        AddLine "<<<FILE path=`"$($p.Rel)`">>>"
+        [void]$sb.Append($text)
+        if (-not $text.EndsWith("`n")) { [void]$sb.Append("`n") }
+        AddLine '<<<ENDFILE>>>'
+    }
+}
+
+$outDir = Split-Path -Parent $OutFile
+if ($outDir -and -not (Test-Path -LiteralPath $outDir)) {
+    New-Item -ItemType Directory -Force -Path $outDir | Out-Null
+}
+[System.IO.File]::WriteAllText($OutFile, $sb.ToString(), [System.Text.UTF8Encoding]::new($false))
+
+Write-Host "Packed $($picked.Count) file(s) -> $OutFile"

package/assets/docs/VerticalSlice/pack-foundation.sh

@@ -0,0 +1,196 @@
+#!/usr/bin/env bash
+#
+# pack-foundation.sh — bash/macOS+Unix port of pack-foundation.ps1
+#
+# SYNOPSIS
+#   Pack a verified foundation solution into a single AW-Spec text pack file.
+#
+# DESCRIPTION
+#   Walks --source-dir, excludes build/IDE artifacts and secret-bearing files, and
+#   writes every remaining file into one pack file using <<<FILE>>> / <<<ENDFILE>>>
+#   markers. Text files are stored verbatim (UTF-8, LF); binary files are
+#   base64-encoded. The resulting pack file is the single bundled artifact consumed
+#   by /aw-spec-foundation (see PACKAGING.md). This is byte-for-byte format-compatible
+#   with pack-foundation.ps1 / unpack-foundation.ps1.
+#
+# EXAMPLE
+#   ./pack-foundation.sh --source-dir ../../.foundation-build --out-file ./VerticalSlice.pack.txt --allow-secrets
+#
+set -euo pipefail
+
+# ------------------------------------------------------------------ defaults ---
+SENTINEL='AppWeaver.Foundation'
+FOUNDATION='VerticalSlice'
+SOURCE_DIR=''
+OUT_FILE=''
+ALLOW_SECRETS=0
+
+usage() {
+  cat >&2 <<'EOF'
+Usage: pack-foundation.sh --source-dir <dir> [--out-file <file>] [--sentinel <name>]
+                          [--foundation <name>] [--allow-secrets]
+
+  -s, --source-dir <dir>   Folder holding the foundation solution        (required)
+  -o, --out-file <file>    Output pack file  (default: ./<foundation>.pack.txt)
+      --sentinel <name>    Sentinel app name        (default: AppWeaver.Foundation)
+      --foundation <name>  Foundation name                 (default: VerticalSlice)
+      --allow-secrets      Pack even if credential markers are detected
+  -h, --help               Show this help
+
+Positional fallback: pack-foundation.sh <source-dir> [out-file]
+EOF
+}
+
+# -------------------------------------------------------------- arg parsing ---
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -s|--source-dir)  SOURCE_DIR="${2:?--source-dir needs a value}"; shift 2 ;;
+    -o|--out-file)    OUT_FILE="${2:?--out-file needs a value}";     shift 2 ;;
+    --sentinel)       SENTINEL="${2:?--sentinel needs a value}";     shift 2 ;;
+    --foundation)     FOUNDATION="${2:?--foundation needs a value}"; shift 2 ;;
+    --allow-secrets)  ALLOW_SECRETS=1; shift ;;
+    -h|--help)        usage; exit 0 ;;
+    --)               shift; break ;;
+    -*)               echo "Error: unknown option: $1" >&2; usage; exit 2 ;;
+    *)
+      if   [ -z "$SOURCE_DIR" ]; then SOURCE_DIR="$1"
+      elif [ -z "$OUT_FILE"   ]; then OUT_FILE="$1"
+      else echo "Error: unexpected argument: $1" >&2; usage; exit 2
+      fi
+      shift ;;
+  esac
+done
+
+[ -n "$SOURCE_DIR" ] || { echo "Error: --source-dir is required." >&2; usage; exit 2; }
+[ -d "$SOURCE_DIR" ] || { echo "Error: SourceDir is not a folder: $SOURCE_DIR" >&2; exit 1; }
+
+SRC="$(cd "$SOURCE_DIR" && pwd -P)"
+[ -n "$OUT_FILE" ] || OUT_FILE="$(pwd)/$FOUNDATION.pack.txt"
+
+# -------------------------------------------------------------- exclusions ---
+# Entire subtree excluded if any path segment matches one of these.
+EXCLUDE_DIRS=(bin obj .vs .git .idea .vscode TestResults node_modules packages App_Data artifacts .next logs)
+# Files excluded by leaf-name glob (build noise, local dbs, and secret-bearing files).
+# NOTE: the root `.env` is intentionally NOT excluded — it carries required sample config
+# and is bundled on purpose. Per-environment overrides (`.env.local`, `.env.production`, ...)
+# stay excluded via the `.env.*` glob. Real credentials are still caught by the content scan.
+EXCLUDE_FILES=('*.user' '*.suo' '*.DotSettings.user' '*.db' '*.db-shm' '*.db-wal' '*.sqlite' '*.log' \
+               '.env.*' '*.pfx' '*.pem' '*.key' '*.snk' 'id_rsa' 'id_rsa.pub' 'secrets.json')
+
+# Content patterns that indicate a real secret; packing aborts on a hit unless --allow-secrets.
+SECRET_NAMES=('NuGet ClearTextPassword' 'Private key block' 'AWS access key id' 'Azure DevOps PAT-ish')
+SECRET_RX=('ClearTextPassword' \
+           'BEGIN (RSA |OPENSSH |EC |DSA )?PRIVATE KEY' \
+           'AKIA[0-9A-Z]{16}' \
+           '[A-Za-z0-9]{52}AZDO[A-Za-z0-9]')
+
+is_excluded() {  # $1 = repo-relative path with '/' separators
+  local rel="$1" seg leaf g
+  local -a segs
+  IFS='/' read -ra segs <<< "$rel"
+  for seg in "${segs[@]}"; do
+    for g in "${EXCLUDE_DIRS[@]}"; do
+      [ "$seg" = "$g" ] && return 0
+    done
+  done
+  leaf="${rel##*/}"
+  for g in "${EXCLUDE_FILES[@]}"; do
+    # shellcheck disable=SC2254  # intentional glob match
+    case "$leaf" in $g) return 0 ;; esac
+  done
+  return 1
+}
+
+is_binary() {  # $1 = file path; true if a NUL byte appears in the first 8000 bytes
+  local f="$1" n1 n2
+  n1="$(head -c 8000 "$f" | wc -c | tr -d '[:space:]')"
+  n2="$(head -c 8000 "$f" | LC_ALL=C tr -d '\000' | wc -c | tr -d '[:space:]')"
+  [ "$n1" != "$n2" ]
+}
+
+# ----------------------------------------------------------- collect + sort ---
+picked=()
+while IFS= read -r full; do
+  rel="${full#"$SRC"/}"
+  is_excluded "$rel" && continue
+  picked+=("$rel")
+done < <(find "$SRC" -type f | LC_ALL=C sort)
+
+[ "${#picked[@]}" -gt 0 ] || { echo "Error: No files to pack under: $SRC" >&2; exit 1; }
+
+# ----------------------------------------------------------- secret scan -----
+# Fail closed so credentials never get baked into the committed bundle.
+findings=()
+for rel in "${picked[@]}"; do
+  f="$SRC/$rel"
+  for i in "${!SECRET_RX[@]}"; do
+    if LC_ALL=C grep -aEq -- "${SECRET_RX[$i]}" "$f" 2>/dev/null; then
+      findings+=("  $rel  ->  ${SECRET_NAMES[$i]}")
+    fi
+  done
+done
+if [ "${#findings[@]}" -gt 0 ]; then
+  if [ "$ALLOW_SECRETS" -eq 1 ]; then
+    echo "WARNING: Potential secret(s) detected — packing anyway (--allow-secrets):" >&2
+    printf '%s\n' "${findings[@]}" >&2
+  else
+    echo "Error: Potential secret(s) detected — refusing to pack (rotate + remove them, or pass --allow-secrets):" >&2
+    printf '%s\n' "${findings[@]}" >&2
+    exit 1
+  fi
+fi
+
+# ----------------------------------------------------------- sentinel check --
+hits=0
+for rel in "${picked[@]}"; do
+  if LC_ALL=C grep -aFq -- "$SENTINEL" "$SRC/$rel" 2>/dev/null; then
+    hits=$((hits + 1))
+  fi
+done
+if [ "$hits" -eq 0 ]; then
+  echo "WARNING: Sentinel '$SENTINEL' not found in any file. Did you build the sample under that exact name?" >&2
+else
+  echo "Sentinel '$SENTINEL' found in $hits file(s)."
+fi
+
+# ----------------------------------------------------------- write the pack --
+outdir="$(dirname "$OUT_FILE")"
+[ -d "$outdir" ] || mkdir -p "$outdir"
+
+{
+  printf '%s\n' '# AW-SPEC FOUNDATION PACK'
+  printf '# foundation: %s\n' "$FOUNDATION"
+  printf '# sentinel: %s\n'   "$SENTINEL"
+  printf '# generated: %s\n'  "$(date -u +%Y-%m-%dT%H:%M:%S.0000000Z)"
+  printf '# files: %s\n'      "${#picked[@]}"
+  printf '%s\n' '# format: aw-spec-pack/v1'
+  printf '%s\n' '# --- replacement contract (ordinal, case-sensitive, longest-first) ---'
+  printf '%s\n' '#   <Sentinel>           -> <AppName>            (dotted:       namespaces, csproj/sln, refs)'
+  printf '%s\n' '#   <Sentinel _-form>    -> <AppName _-form>     (underscored:  Aspire project class names)'
+  printf '%s\n' '#   <sentinel --form>    -> <appname --form>     (lower-hyphen: UserSecretsId, db/containers)'
+  printf '%s\n' '#   <sentinel .-form>    -> <appname lower-dot>  (lower-dot:    lowercased identifiers)'
+  printf '%s\n' '# Applied to file CONTENTS and file/dir PATHS. Never touch other AppWeaver.* tokens.'
+  printf '%s\n' '# ============================================================'
+  printf '\n'
+} > "$OUT_FILE"
+
+for rel in "${picked[@]}"; do
+  f="$SRC/$rel"
+  if is_binary "$f"; then
+    {
+      printf '<<<FILE path="%s" encoding="base64">>>\n' "$rel"
+      base64 < "$f" | tr -d '\n'
+      printf '\n'
+      printf '%s\n' '<<<ENDFILE>>>'
+    } >> "$OUT_FILE"
+  else
+    {
+      printf '<<<FILE path="%s">>>\n' "$rel"
+      # CRLF -> LF, and guarantee the content ends with exactly one trailing newline.
+      awk '{ sub(/\r$/, ""); print }' "$f"
+      printf '%s\n' '<<<ENDFILE>>>'
+    } >> "$OUT_FILE"
+  fi
+done
+
+echo "Packed ${#picked[@]} file(s) -> $OUT_FILE"

package/assets/docs/VerticalSlice/unpack-foundation.ps1

@@ -0,0 +1,126 @@
+#requires -Version 5.1
+<#
+.SYNOPSIS
+    Unpack an AW-Spec foundation pack file into a target application, renaming the
+    sentinel app name to the caller's app name.
+
+.DESCRIPTION
+    Reads -PackFile, takes the sentinel from its header (override with -Sentinel),
+    derives four case forms of the target app name, and writes every file block to
+    -OutDir 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-foundation.ps1 -PackFile ./VerticalSlice.pack.txt -TargetAppName AppWeaver.Health -OutDir ../../
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)] [string] $PackFile,
+    [Parameter(Mandatory)] [string] $TargetAppName,
+    [string] $OutDir = '.',
+    [string] $Sentinel,
+    [switch] $Force,
+    [switch] $DryRun
+)
+
+$ErrorActionPreference = 'Stop'
+
+$pack  = (Resolve-Path -LiteralPath $PackFile).Path
+$lines = ([System.IO.File]::ReadAllText($pack)) -split "`r?`n"
+
+# --- sentinel from header unless overridden ---
+if (-not $Sentinel) {
+    foreach ($l in $lines) {
+        if ($l -match '^#\s*sentinel:\s*(.+?)\s*$') { $Sentinel = $Matches[1]; break }
+    }
+}
+if (-not $Sentinel) { throw "Sentinel not found in pack header; supply it with -Sentinel." }
+
+# --- derive case forms ---
+function Conv-Underscore  ([string] $s) { $s -replace '\.','_' }
+function Conv-LowerHyphen ([string] $s) { ($s.ToLowerInvariant()) -replace '\.','-' }
+function Conv-LowerDot    ([string] $s) { $s.ToLowerInvariant() }
+
+# NOTE: do NOT use a hashtable here — PowerShell hashtable keys are case-INSENSITIVE,
+# which would collapse the dotted ("AppWeaver.Foundation") and lower-dot
+# ("appweaver.foundation") forms into one entry and drop the namespace rename.
+$forms = @(
+    @{ From = $Sentinel;                     To = $TargetAppName }
+    @{ From = (Conv-Underscore  $Sentinel);  To = (Conv-Underscore  $TargetAppName) }
+    @{ From = (Conv-LowerHyphen $Sentinel);  To = (Conv-LowerHyphen $TargetAppName) }
+    @{ From = (Conv-LowerDot    $Sentinel);  To = (Conv-LowerDot    $TargetAppName) }
+)
+$replacements = @()
+$seen = New-Object 'System.Collections.Generic.HashSet[string]' ([System.StringComparer]::Ordinal)
+foreach ($pair in $forms) {
+    $from = [string]$pair.From
+    $to   = [string]$pair.To
+    if ([string]::IsNullOrEmpty($from)) { continue }
+    if ($from -ceq $to) { continue }          # -ceq: case-sensitive no-op check
+    if (-not $seen.Add($from)) { continue }    # ordinal dedupe of identical From tokens
+    $replacements += [pscustomobject]@{ From = $from; To = $to }
+}
+# longest token first so overlaps resolve correctly
+$replacements = @($replacements | Sort-Object { $_.From.Length } -Descending)
+
+function Apply-Repl([string] $text) {
+    foreach ($r in $replacements) { $text = $text.Replace($r.From, $r.To) }
+    return $text
+}
+
+# --- output root ---
+if (-not (Test-Path -LiteralPath $OutDir)) { New-Item -ItemType Directory -Force -Path $OutDir | Out-Null }
+$outRoot = (Resolve-Path -LiteralPath $OutDir).Path
+$sep     = [System.IO.Path]::DirectorySeparatorChar
+
+# --- parse file blocks ---
+$files = @()
+$i = 0
+while ($i -lt $lines.Count) {
+    if ($lines[$i] -match '^<<<FILE path="(.+?)"(?:\s+encoding="(\w+)")?>>>\s*$') {
+        $rel = $Matches[1]; $enc = $Matches[2]
+        $i++
+        $buf = New-Object System.Collections.Generic.List[string]
+        while ($i -lt $lines.Count -and $lines[$i] -ne '<<<ENDFILE>>>') {
+            $buf.Add($lines[$i]); $i++
+        }
+        $files += [pscustomobject]@{ Rel = $rel; Enc = $enc; Content = ($buf -join "`n") }
+    }
+    $i++
+}
+if ($files.Count -eq 0) { throw "No <<<FILE>>> blocks found in pack: $pack" }
+
+function Resolve-Dest([string] $rel) {
+    $renamed = (Apply-Repl $rel).Replace('/', $sep)
+    return (Join-Path $outRoot $renamed)
+}
+
+# --- conflict guard ---
+$conflicts = foreach ($f in $files) { $d = Resolve-Dest $f.Rel; if (Test-Path -LiteralPath $d) { $d } }
+if ($conflicts -and -not $Force) {
+    throw ("Refusing to overwrite existing files (re-run with -Force):`n  " + ($conflicts -join "`n  "))
+}
+
+# --- write ---
+$written = 0
+foreach ($f in $files) {
+    $dest    = Resolve-Dest $f.Rel
+    $destDir = Split-Path -Parent $dest
+    if ($DryRun) { Write-Host "WOULD WRITE  $($f.Rel)  ->  $dest"; continue }
+    if ($destDir -and -not (Test-Path -LiteralPath $destDir)) {
+        New-Item -ItemType Directory -Force -Path $destDir | Out-Null
+    }
+    if ($f.Enc -eq 'base64') {
+        [System.IO.File]::WriteAllBytes($dest, [Convert]::FromBase64String(($f.Content -replace '\s','')))
+    } else {
+        [System.IO.File]::WriteAllText($dest, (Apply-Repl $f.Content), [System.Text.UTF8Encoding]::new($false))
+    }
+    $written++
+}
+
+if ($DryRun) {
+    Write-Host "DryRun: $($files.Count) file(s) would be written to $outRoot (sentinel '$Sentinel' -> '$TargetAppName')."
+} else {
+    Write-Host "Unpacked $written file(s) to $outRoot (sentinel '$Sentinel' -> '$TargetAppName')."
+}

package/assets/docs/VerticalSlice/unpack-foundation.sh

@@ -0,0 +1,217 @@
+#!/usr/bin/env bash
+#
+# unpack-foundation.sh — bash/macOS+Unix port of unpack-foundation.ps1
+#
+# SYNOPSIS
+#   Unpack an AW-Spec foundation pack file into a target application, renaming the
+#   sentinel app name to the caller's app name.
+#
+# DESCRIPTION
+#   Reads --pack-file, 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. Reads packs produced by either
+#   pack-foundation.sh or pack-foundation.ps1.
+#
+# EXAMPLE
+#   ./unpack-foundation.sh --pack-file ./VerticalSlice.pack.txt --target-app-name AppWeaver.Health --out-dir ../../
+#
+set -euo pipefail
+
+# ------------------------------------------------------------------ defaults ---
+PACK_FILE=''
+TARGET_APP_NAME=''
+OUT_DIR='.'
+SENTINEL=''
+FORCE=0
+DRYRUN=0
+
+usage() {
+  cat >&2 <<'EOF'
+Usage: unpack-foundation.sh --pack-file <file> --target-app-name <name>
+                            [--out-dir <dir>] [--sentinel <name>] [--force] [--dry-run]
+
+  -p, --pack-file <file>        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: . / repo root by skill)
+      --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-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; }
+
+# Keep replacement tokens safe for bash literal substitution / path joins.
+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"                       # dotted
+S_UND="${SENTINEL//./_}";       T_UND="${TARGET_APP_NAME//./_}"               # underscored
+s_low="$(to_lower "$SENTINEL")"; t_low="$(to_lower "$TARGET_APP_NAME")"
+S_HYP="${s_low//./-}";          T_HYP="${t_low//./-}"                         # lower-hyphen
+S_LDOT="$s_low";                T_LDOT="$t_low"                               # lower-dot
+
+# Build replacement list: dedupe by From (ordinal), drop no-ops, sort longest-first.
+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"
+
+# Order indices by FROM length descending (stable for equal lengths).
+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() {  # literal, ordinal, longest-first; result in $REPL_OUT (no subshell trim)
+  local text="$1" idx from to
+  if [ "${#ORDER[@]}" -gt 0 ]; then   # empty when target == sentinel (no-op rename)
+    for idx in "${ORDER[@]}"; do
+      from="${FROM[$idx]}"; to="${TO[$idx]}"
+      text="${text//"$from"/$to}"   # quoted pattern => literal (non-glob) match
+    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'}"   # tolerate CRLF packs (e.g. git autocrlf on Windows checkout)
+  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