aw-spec-cli 0.1.2 → 0.1.4

package/assets/docs/ModularMonolith/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 ./VerticalSlice.Reference.pack.txt \
+#       --target-app-name AppWeaver.Pharma \
+#       --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/UI.Visualization/PACKAGING.md

@@ -0,0 +1,191 @@
+# UI.Visualization — Foundation Packaging Rules
+
+> **Why this exists.** This packaging model replaces reconstruction with a
+> **byte-for-byte bundle of the real, verified Next.js template**.
+>
+> You author the UI foundation **once** (a Next.js app that actually builds and runs),
+> pack it into a single text file, and the scaffolder **unpacks + renames** it.
+> No regeneration, no drift — the same guarantee that `VerticalSlice` provides for the backend.
+
+---
+
+## The single artifact
+
+```
+docs/UI.Visualization/
+├── UI.Visualization.pack.txt      ← THE BUNDLE: every source file in one text file
+├── PACKAGING.md                             ← this file
+├── pack-foundation.ps1                      ← produces the pack from the template folder (Windows)
+├── pack-foundation.sh                       ← produces the pack from the template folder (macOS/Linux)
+├── pack-reference-foundation.ps1            ← produces a reference/sample pack
+├── pack-reference-foundation.sh
+├── unpack-foundation.ps1                    ← extracts + renames into a target app (used by skill)
+├── unpack-foundation.sh
+├── unpack-reference-foundation.ps1
+└── unpack-reference-foundation.sh
+```
+
+The source template lives at:
+
+```
+templates/UI.Visualization/
+```
+
+---
+
+## The sentinel convention
+
+The template is authored under the sentinel app name:
+
+```
+UI.Visualization
+```
+
+The scaffolder rewrites the sentinel in **four case forms** (ordinal, case-sensitive, longest-first),
+applied to **file contents and to file/folder paths**:
+
+| Form         | Sentinel                       | Example target (`PharmaViz`)    | Where it appears                          |
+|--------------|--------------------------------|---------------------------------|-------------------------------------------|
+| dotted       | `UI.Visualization`   | `PharmaViz`                     | `package.json` name (dotted form), README |
+| underscored  | `UI_Visualization`   | `PharmaViz`                     | any underscored identifiers               |
+| lower-hyphen | `ui-visualization`   | `pharmaviz`                     | npm package name, Docker image tag        |
+| lower-dot    | `ui.visualization`   | `pharmaviz`                     | any lowercased identifiers                |
+
+### What does NOT get renamed
+
+- `AppWeaver.*` framework package references in `package.json` (there are none in this UI template — all deps are third-party).
+- The generic sample pages (`/heatmap`, `/bubble`, etc.) — these are example content the caller replaces with their own pages.
+
+---
+
+## How to author the template (do this once per change)
+
+1. Work in `templates/UI.Visualization/`.
+
+2. Use `UI.Visualization` as the sentinel wherever the app name belongs:
+   - `package.json` → `"name": "ui-visualization"` (lower-hyphen form)
+   - `README.md` → title
+   - `src/app/layout.tsx` → `<title>UI.Visualization</title>` and metadata
+   - Any other branding strings
+
+3. Verify the template builds and runs clean:
+   ```bash
+   cd templates/UI.Visualization
+   npm install
+   npm run build    # must exit 0, no TypeScript errors
+   npm run dev      # browse to http://localhost:3000, all 10 chart pages render
+   ```
+
+4. Fix every error here, in the real template, where the compiler tells you exactly what's wrong.
+
+---
+
+## How to build the bundle
+
+From `docs/UI.Visualization/`:
+
+**macOS / Linux:**
+```bash
+./pack-foundation.sh \
+    --source-dir ../../../../templates/UI.Visualization \
+    --out-file   ./UI.Visualization.pack.txt
+```
+
+**Windows (PowerShell):**
+```powershell
+./pack-foundation.ps1 `
+    -SourceDir ../../../../templates/UI.Visualization `
+    -OutFile   ./UI.Visualization.pack.txt
+```
+
+The packer:
+- Walks the template, **excluding** build/IDE and JS output artifacts:
+  - dirs: `node_modules .next .turbo dist out coverage .cache bin obj .vs .git logs`
+  - files: `*.tsbuildinfo  next-env.d.ts  *.log  .env.*  *.pem  *.key  secrets.json`
+- **Fails closed on detected secrets** — scans file contents for credential markers and refuses to pack unless `--allow-secrets` / `-AllowSecrets` is passed.
+- Stores text files **verbatim** and binary files (e.g. `.xlsx`) **base64-encoded**.
+- Writes a header containing `foundation`, `sentinel`, file count, format version, and the replacement contract.
+- **Warns** if the sentinel token appears in zero files.
+
+Re-run it whenever the template changes; commit the regenerated `UI.Visualization.pack.txt`.
+
+---
+
+## How to build the reference pack
+
+The reference pack is used by `/aw-spec-addcomponent` and `/aw-spec-implement` unpack workflows
+when a feature reference example exists under `templates/features/`.
+
+```bash
+./pack-reference-foundation.sh \
+    --source-dir ../../../../templates/features/UIVisualization.SimpleSample \
+    --out-file   ./UI.Visualization.Reference.pack.txt
+```
+
+*(Create the `SimpleSample` folder when you have a working feature example to bundle.)*
+
+---
+
+## Pack file format (`aw-spec-pack/v1`)
+
+Same format as `VerticalSlice.pack.txt`:
+
+```
+# AW-SPEC FOUNDATION PACK
+# foundation: UI.Visualization
+# sentinel: UI.Visualization
+# generated: 2026-06-26T10:00:00.0000000Z
+# files: 32
+# format: aw-spec-pack/v1
+# --- replacement contract ... ---
+# ============================================================
+
+<<<FILE path="package.json">>>
+...verbatim file content...
+<<<ENDFILE>>>
+<<<FILE path="src/app/layout.tsx">>>
+...
+<<<ENDFILE>>>
+<<<FILE path="public/sample-data.xlsx" encoding="base64">>>
+AAABAAE...
+<<<ENDFILE>>>
+```
+
+---
+
+## How scaffolding consumes the bundle
+
+`/aw-spec-foundation UI.Visualization <AppName> [OutputDir]`
+runs `unpack-foundation.sh` (or `.ps1`), which reads the sentinel from the pack header,
+derives the four target case forms, and writes the renamed files to the output directory.
+
+```bash
+# macOS / Linux
+./unpack-foundation.sh \
+    --pack-file   ./UI.Visualization.pack.txt \
+    --target-app-name PharmaViz \
+    --out-dir     ~/projects/
+
+# Windows
+./unpack-foundation.ps1 `
+    -PackFile        ./UI.Visualization.pack.txt `
+    -TargetAppName   PharmaViz `
+    -OutDir          ~/projects/
+```
+
+After unpacking:
+```bash
+cd ~/projects/PharmaViz     # or wherever OutDir puts it
+npm install
+npm run dev                  # → http://localhost:3000
+```
+
+---
+
+## Maintenance checklist
+
+- [ ] Template builds clean (`npm run build`, no TypeScript errors).
+- [ ] Sentinel `UI.Visualization` appears in `package.json`, `README.md`, `layout.tsx`.
+- [ ] No `node_modules/`, `.next/`, or generated files committed into the pack.
+- [ ] `pack-foundation.sh` reported a non-zero sentinel hit count.
+- [ ] `UI.Visualization.pack.txt` regenerated and committed after any change.