aw-spec-cli 0.1.2 → 0.1.4

package/assets/docs/UI.Visualization/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 ./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