aw-spec-cli 0.1.4 → 0.1.6

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

@@ -1,205 +0,0 @@
-#!/usr/bin/env bash
-#
-# pack-reference-foundation.sh — bash/macOS port of pack-reference-foundation.ps1
-#
-# SYNOPSIS
-#   Pack a verified UI feature reference template into a single AW-Spec text pack file.
-#
-# DESCRIPTION
-#   Walks --source-dir (a templates/features/<Name>.SimpleSample folder for UI features),
-#   excludes build/IDE artifacts, JS output, template meta-files, and secret-bearing files,
-#   and writes every remaining file into one pack file using <<<FILE>>> / <<<ENDFILE>>>
-#   markers. Format-compatible with unpack-reference-foundation.
-#
-# EXAMPLE
-#   ./pack-reference-foundation.sh \
-#       --source-dir ../../../../templates/features/UIVisualization.SimpleSample \
-#       --out-file   ./UI.Visualization.Reference.pack.txt \
-#       --sentinel   UI.Visualization \
-#       --foundation UI.Visualization.Reference
-#
-set -euo pipefail
-
-# ------------------------------------------------------------------ defaults ---
-SENTINEL='AppWeaver.UI.Visualization'
-FOUNDATION='AppWeaver.UI.Visualization.Reference'
-SOURCE_DIR=''
-OUT_FILE=''
-ALLOW_SECRETS=0
-
-usage() {
-  cat >&2 <<'EOF'
-Usage: pack-reference-foundation.sh --source-dir <dir> [--out-file <file>]
-                                    [--sentinel <name>] [--foundation <name>]
-                                    [--allow-secrets]
-
-  -s, --source-dir <dir>   templates/features/<Name>.SimpleSample folder  (required)
-  -o, --out-file <file>    Output pack file  (default: ./<foundation>.pack.txt)
-      --sentinel <name>    Sentinel app name  (default: UI.Visualization)
-      --foundation <name>  Foundation name    (default: UI.Visualization.Reference)
-      --allow-secrets      Pack even if credential markers are detected
-  -h, --help               Show this help
-
-Positional fallback: pack-reference-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 ---
-EXCLUDE_DIRS=(
-  bin obj .vs .git .idea .vscode TestResults
-  node_modules packages App_Data artifacts
-  .next .turbo dist out coverage .cache logs
-)
-
-EXCLUDE_FILES=(
-  '*.user' '*.suo' '*.DotSettings.user' '*.db' '*.db-shm' '*.db-wal' '*.sqlite' '*.log'
-  '.env' '*.env.*' '.env.*' '*.pfx' '*.pem' '*.key' '*.snk' 'id_rsa' 'id_rsa.pub' 'secrets.json'
-  '.DS_Store'
-  '*.my-ref.*'
-  '*TemplateConfig.config'
-  '*.tsbuildinfo'
-  'next-env.d.ts'
-)
-
-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() {
-  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
-    case "$leaf" in $g) return 0 ;; esac
-  done
-  return 1
-}
-
-is_binary() {
-  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 -----
-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:" >&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 author 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 REFERENCE 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:       package.json name as dotted)'
-  printf '%s\n' '#   <Sentinel _-form>    -> <AppName _-form>     (underscored:  identifiers)'
-  printf '%s\n' '#   <sentinel --form>    -> <appname --form>     (lower-hyphen: npm package name, docker image)'
-  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"
-      awk '{ sub(/\r$/, ""); print }' "$f"
-      printf '%s\n' '<<<ENDFILE>>>'
-    } >> "$OUT_FILE"
-  fi
-done
-
-echo "Packed ${#picked[@]} file(s) -> $OUT_FILE"

package/assets/docs/UI.Visualization/unpack-foundation.ps1

@@ -1,126 +0,0 @@
-#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 ./UI.Visualization.pack.txt -TargetAppName MyApp -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/UI.Visualization/unpack-foundation.sh

@@ -1,217 +0,0 @@
-#!/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 ./UI.Visualization.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-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

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

@@ -1,129 +0,0 @@
-#requires -Version 5.1
-<#
-.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 -PackFile (produced by pack-reference-foundation.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 -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-reference-foundation.ps1 `
-        -PackFile ./UI.Visualization.Reference.pack.txt `
-        -TargetAppName MyApp `
-        -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.VerticalSlice") and lower-dot
-# ("appweaver.verticalslice") 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 }
-    if (-not $seen.Add($from)) { continue }
-    $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')."
-}