@sdd-method/sdd-cli 0.9.0

package/scripts/sync-method-baseline.sh

@@ -0,0 +1,258 @@
+#!/bin/bash
+#
+# sync-method-baseline.sh
+# Apply a built method baseline bundle to a target repository.
+#
+# Usage:
+#   ./orchestration/scripts/sync-method-baseline.sh --bundle dist/method-baseline/method-baseline-v0.1.0.tar.gz
+#   ./orchestration/scripts/sync-method-baseline.sh --bundle ... --target-repo /path/to/repo --dry-run
+
+set -euo pipefail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+REPO_KIND_FILE=".sdd-repo-kind"
+PROTECTED_PREFIXES=("content/")
+
+log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
+log_fail() { echo -e "${RED}[FAIL]${NC} $1"; }
+log_pass() { echo -e "${GREEN}[PASS]${NC} $1"; }
+log_section() {
+  echo -e "\n${BLUE}═══════════════════════════════════════════════════════════${NC}"
+  echo -e "${BLUE}  $1${NC}"
+  echo -e "${BLUE}═══════════════════════════════════════════════════════════${NC}\n"
+}
+
+usage() {
+  cat <<USAGE
+Usage: $(basename "$0") --bundle <path.tar.gz> [--target-repo <dir>] [--dry-run] [--allow-overwrite] [--no-delete]
+
+Options:
+  --bundle           Required bundle archive generated by build-method-baseline-bundle.sh
+  --target-repo      Target repository root (default: current working directory)
+  --dry-run          Report plan only; do not modify files
+  --allow-overwrite  Overwrite conflicting managed files (default: fail on conflict)
+  --no-delete        Do not delete previously managed files removed from the incoming bundle
+USAGE
+}
+
+BUNDLE=""
+TARGET_REPO="$(pwd)"
+DRY_RUN=0
+ALLOW_OVERWRITE=0
+NO_DELETE=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --bundle)
+      BUNDLE="${2:-}"
+      shift 2
+      ;;
+    --target-repo)
+      TARGET_REPO="${2:-}"
+      shift 2
+      ;;
+    --dry-run)
+      DRY_RUN=1
+      shift
+      ;;
+    --allow-overwrite)
+      ALLOW_OVERWRITE=1
+      shift
+      ;;
+    --no-delete)
+      NO_DELETE=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      log_fail "Unknown argument: $1"
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$BUNDLE" ]]; then
+  log_fail "--bundle is required"
+  usage
+  exit 1
+fi
+
+if [[ ! -f "$BUNDLE" ]]; then
+  log_fail "Bundle not found: $BUNDLE"
+  exit 1
+fi
+
+if [[ ! -d "$TARGET_REPO" ]]; then
+  log_fail "Target repo not found: $TARGET_REPO"
+  exit 1
+fi
+
+log_section "Sync Method Baseline"
+
+TMP_DIR="$(mktemp -d)"
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+tar -xzf "$BUNDLE" -C "$TMP_DIR"
+BUNDLE_ROOT="$(find "$TMP_DIR" -mindepth 1 -maxdepth 1 -type d | head -n 1)"
+if [[ -z "$BUNDLE_ROOT" ]]; then
+  log_fail "Could not find extracted bundle root"
+  exit 1
+fi
+
+MANAGED_PATHS_FILE="$BUNDLE_ROOT/MANAGED_PATHS.txt"
+PAYLOAD_DIR="$BUNDLE_ROOT/payload"
+MANIFEST_FILE="$BUNDLE_ROOT/BUNDLE_MANIFEST.yaml"
+LOCK_FILE="$TARGET_REPO/method-baseline.lock"
+
+if [[ ! -f "$MANAGED_PATHS_FILE" || ! -d "$PAYLOAD_DIR" || ! -f "$MANIFEST_FILE" ]]; then
+  log_fail "Bundle missing required files (MANAGED_PATHS.txt, payload/, or BUNDLE_MANIFEST.yaml)"
+  exit 1
+fi
+
+BUNDLE_VERSION="$(awk -F': ' '/^bundle_version:/{gsub(/"/,"",$2); print $2}' "$MANIFEST_FILE")"
+SOURCE_COMMIT="$(awk -F': ' '/^source_commit:/{gsub(/"/,"",$2); print $2}' "$MANIFEST_FILE")"
+BUNDLE_NAME="$(awk -F': ' '/^bundle_name:/{gsub(/"/,"",$2); print $2}' "$MANIFEST_FILE")"
+
+case "$BUNDLE_NAME" in
+  platform-baseline)
+    REPO_KIND_VALUE="platform-product"
+    ;;
+  app-baseline)
+    REPO_KIND_VALUE="application-product"
+    ;;
+  integration-baseline)
+    REPO_KIND_VALUE="integration-product"
+    ;;
+  *)
+    log_fail "Unknown bundle_name in manifest: $BUNDLE_NAME"
+    exit 1
+    ;;
+esac
+
+mapfile -t INCOMING_PATHS < "$MANAGED_PATHS_FILE"
+
+for p in "${INCOMING_PATHS[@]}"; do
+  if [[ ! -f "$PAYLOAD_DIR/$p" ]]; then
+    log_fail "Missing payload file listed in MANAGED_PATHS.txt: $p"
+    exit 1
+  fi
+  for prefix in "${PROTECTED_PREFIXES[@]}"; do
+    if [[ "$p" == "$prefix"* ]]; then
+      log_fail "Incoming bundle attempts to manage protected product-owned path: $p"
+      log_fail "Method baseline bundles must not manage files under: ${PROTECTED_PREFIXES[*]}"
+      exit 1
+    fi
+  done
+done
+
+# Detect conflicts unless caller explicitly allows overwrite.
+CONFLICTS=()
+for p in "${INCOMING_PATHS[@]}"; do
+  target_file="$TARGET_REPO/$p"
+  incoming_file="$PAYLOAD_DIR/$p"
+  if [[ -f "$target_file" ]] && ! cmp -s "$incoming_file" "$target_file"; then
+    CONFLICTS+=("$p")
+  fi
+done
+
+if [[ ${#CONFLICTS[@]} -gt 0 && "$ALLOW_OVERWRITE" -ne 1 ]]; then
+  log_fail "Found ${#CONFLICTS[@]} conflicting managed file(s). Re-run with --allow-overwrite to apply."
+  printf '%s\n' "${CONFLICTS[@]}" | sed 's/^/  - /'
+  exit 1
+fi
+
+# Load previously managed paths from lock file (if present).
+PREV_PATHS=()
+if [[ -f "$LOCK_FILE" ]]; then
+  while IFS= read -r p; do
+    PREV_PATHS+=("$p")
+  done < <(awk '
+    /^managed_paths:/ {in_list=1; next}
+    in_list && /^  - / {sub(/^  - /, ""); print; next}
+    in_list && !/^  - / {in_list=0}
+  ' "$LOCK_FILE")
+fi
+
+for p in "${PREV_PATHS[@]}"; do
+  for prefix in "${PROTECTED_PREFIXES[@]}"; do
+    if [[ "$p" == "$prefix"* ]]; then
+      log_fail "Existing lock file contains protected product-owned path: $p"
+      log_fail "Resolve this manually before refreshing the method baseline."
+      exit 1
+    fi
+  done
+done
+
+# Compute removal set: paths previously managed but not in incoming list.
+REMOVE_PATHS=()
+if [[ "$NO_DELETE" -ne 1 && ${#PREV_PATHS[@]} -gt 0 ]]; then
+  for prev in "${PREV_PATHS[@]}"; do
+    keep=0
+    for cur in "${INCOMING_PATHS[@]}"; do
+      if [[ "$prev" == "$cur" ]]; then
+        keep=1
+        break
+      fi
+    done
+    if [[ "$keep" -eq 0 ]]; then
+      REMOVE_PATHS+=("$prev")
+    fi
+  done
+fi
+
+log_info "Incoming managed files: ${#INCOMING_PATHS[@]}"
+log_info "Conflicts: ${#CONFLICTS[@]}"
+log_info "Removals from previous baseline: ${#REMOVE_PATHS[@]}"
+log_info "Protected ownership prefixes: ${PROTECTED_PREFIXES[*]}"
+
+if [[ "$DRY_RUN" -eq 1 ]]; then
+  log_info "Dry run enabled. No files modified."
+  if [[ ${#CONFLICTS[@]} -gt 0 ]]; then
+    log_info "Conflicting files:"
+    printf '%s\n' "${CONFLICTS[@]}" | sed 's/^/  - /'
+  fi
+  if [[ ${#REMOVE_PATHS[@]} -gt 0 ]]; then
+    log_info "Files that would be removed:"
+    printf '%s\n' "${REMOVE_PATHS[@]}" | sed 's/^/  - /'
+  fi
+  exit 0
+fi
+
+# Apply incoming managed files.
+for p in "${INCOMING_PATHS[@]}"; do
+  mkdir -p "$TARGET_REPO/$(dirname "$p")"
+  cp "$PAYLOAD_DIR/$p" "$TARGET_REPO/$p"
+done
+
+# Remove files no longer managed by this baseline.
+for p in "${REMOVE_PATHS[@]}"; do
+  rm -f "$TARGET_REPO/$p"
+done
+
+printf '%s\n' "$REPO_KIND_VALUE" > "$TARGET_REPO/$REPO_KIND_FILE"
+
+SYNCED_AT_UTC="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+BUNDLE_SHA="$(sha256sum "$BUNDLE" | awk '{print $1}')"
+
+{
+  echo "method_repo: sdd-method"
+  echo "bundle_version: \"$BUNDLE_VERSION\""
+  echo "source_commit: \"$SOURCE_COMMIT\""
+  echo "bundle_sha256: \"$BUNDLE_SHA\""
+  echo "synced_at_utc: \"$SYNCED_AT_UTC\""
+  echo "managed_paths:"
+  for p in "${INCOMING_PATHS[@]}"; do
+    echo "  - $p"
+  done
+} > "$LOCK_FILE"
+
+log_pass "Method baseline synced to: $TARGET_REPO"
+log_info "Updated lock file: method-baseline.lock"
+log_info "Set repo kind marker: $REPO_KIND_FILE = $REPO_KIND_VALUE"

package/scripts/validate-app-dependencies.sh

@@ -0,0 +1,289 @@
+#!/bin/bash
+#
+# validate-app-dependencies.sh - Validate app platform dependency declarations
+#
+# Usage:
+#   ./validate-app-dependencies.sh --app-root <path> --platform-root <path>
+#
+# Checks (for each entry in app-platform-dependencies.yaml):
+#   1. required_stability is a valid value (provisional | locked)
+#   2. service_id exists in platform service-architecture.md
+#   3. contract_path exists (as a file) when required_stability is "locked"
+#
+# Outputs a dependency status table.
+# Used as the Stage 6 lock-in gate in the App Exploration Workflow.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
+log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+log_fail() { echo -e "${RED}[FAIL]${NC} $1"; }
+log_pass() { echo -e "${GREEN}[PASS]${NC} $1"; }
+log_section() {
+    echo -e "\n${BLUE}═══════════════════════════════════════════════════════════${NC}"
+    echo -e "${BLUE}  $1${NC}"
+    echo -e "${BLUE}═══════════════════════════════════════════════════════════${NC}\n"
+}
+
+APP_ROOT=""
+PLATFORM_ROOT=""
+
+usage() {
+    cat <<USAGE
+Usage: $(basename "$0") --app-root <path> --platform-root <path>
+
+Options:
+  --app-root       Path to the app repository root (must contain app-platform-dependencies.yaml)
+  --platform-root  Path to the platform repository root (must contain docs/service-architecture.md)
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --app-root)
+            APP_ROOT="${2:-}"
+            shift 2
+            ;;
+        --platform-root)
+            PLATFORM_ROOT="${2:-}"
+            shift 2
+            ;;
+        -h|--help)
+            usage
+            exit 0
+            ;;
+        *)
+            log_fail "Unknown argument: $1"
+            usage
+            exit 1
+            ;;
+    esac
+done
+
+if [[ -z "$APP_ROOT" ]]; then
+    log_fail "--app-root is required"
+    usage
+    exit 1
+fi
+
+if [[ -z "$PLATFORM_ROOT" ]]; then
+    log_fail "--platform-root is required"
+    usage
+    exit 1
+fi
+
+if [[ ! -d "$APP_ROOT" ]]; then
+    log_fail "App root not found: $APP_ROOT"
+    exit 1
+fi
+
+if [[ ! -d "$PLATFORM_ROOT" ]]; then
+    log_fail "Platform root not found: $PLATFORM_ROOT"
+    exit 1
+fi
+
+APP_DEPS_FILE="$APP_ROOT/app-platform-dependencies.yaml"
+PLATFORM_SERVICE_ARCH="$PLATFORM_ROOT/docs/platform/service-architecture.md"
+
+VALID_STABILITY_VALUES=("provisional" "locked")
+
+FAILURES=0
+WARNINGS=0
+TOTAL_DEPS=0
+PASSED_DEPS=0
+
+# ──────────────────────────────────────────────────────────────────────────────
+check_prerequisites() {
+    log_section "Prerequisites"
+
+    if [[ ! -f "$APP_DEPS_FILE" ]]; then
+        log_fail "app-platform-dependencies.yaml not found: $APP_DEPS_FILE"
+        exit 1
+    fi
+    log_pass "app-platform-dependencies.yaml found"
+
+    if ! command -v yq &>/dev/null; then
+        log_fail "yq is required but not installed. Install with: brew install yq"
+        exit 1
+    fi
+    log_pass "yq available"
+
+    if [[ ! -f "$PLATFORM_SERVICE_ARCH" ]]; then
+        log_warn "Platform service-architecture.md not found: $PLATFORM_SERVICE_ARCH"
+        log_warn "service_id validation will be skipped"
+        PLATFORM_SERVICE_ARCH=""
+    else
+        log_pass "Platform service-architecture.md found"
+    fi
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+validate_dependency() {
+    local index="$1"
+    local dep_errors=0
+
+    local capability_id service_id contract_type required_stability contract_path
+
+    capability_id="$(yq e ".platform_dependencies[$index].capability_id // \"\"" "$APP_DEPS_FILE")"
+    service_id="$(yq e ".platform_dependencies[$index].service_id // \"\"" "$APP_DEPS_FILE")"
+    contract_type="$(yq e ".platform_dependencies[$index].contract_type // \"\"" "$APP_DEPS_FILE")"
+    required_stability="$(yq e ".platform_dependencies[$index].required_stability // \"\"" "$APP_DEPS_FILE")"
+    contract_path="$(yq e ".platform_dependencies[$index].contract_path // \"\"" "$APP_DEPS_FILE")"
+
+    local dep_label="${service_id:-dep[$index]}"
+    if [[ -n "$capability_id" && "$capability_id" != "null" ]]; then
+        dep_label="$capability_id / $service_id"
+    fi
+
+    # Check 1: required_stability is a valid value
+    local stability_valid=0
+    for v in "${VALID_STABILITY_VALUES[@]}"; do
+        if [[ "$required_stability" == "$v" ]]; then
+            stability_valid=1
+            break
+        fi
+    done
+
+    if [[ "$stability_valid" -eq 0 ]]; then
+        log_fail "$dep_label: invalid required_stability '$required_stability' (allowed: ${VALID_STABILITY_VALUES[*]})"
+        ((dep_errors++))
+    fi
+
+    # Check 2: service_id exists in platform service-architecture.md
+    if [[ -n "$PLATFORM_SERVICE_ARCH" ]]; then
+        if [[ -z "$service_id" || "$service_id" == "null" ]]; then
+            log_fail "$dep_label: service_id is empty or missing"
+            ((dep_errors++))
+        elif ! grep -q "$service_id" "$PLATFORM_SERVICE_ARCH" 2>/dev/null; then
+            log_fail "$dep_label: service_id '$service_id' not found in platform service-architecture.md"
+            ((dep_errors++))
+        fi
+    fi
+
+    # Check 3: contract_path exists when required_stability is locked
+    if [[ "$required_stability" == "locked" ]]; then
+        if [[ -z "$contract_path" || "$contract_path" == "null" ]]; then
+            log_fail "$dep_label: required_stability is 'locked' but contract_path is empty"
+            ((dep_errors++))
+        else
+            local full_contract_path="$PLATFORM_ROOT/$contract_path"
+            if [[ ! -f "$full_contract_path" ]]; then
+                log_fail "$dep_label: locked contract_path '$contract_path' does not exist in platform repo"
+                ((dep_errors++))
+            fi
+        fi
+    elif [[ "$required_stability" == "provisional" ]]; then
+        if [[ -n "$contract_path" && "$contract_path" != "null" ]]; then
+            local full_contract_path="$PLATFORM_ROOT/$contract_path"
+            if [[ ! -f "$full_contract_path" ]]; then
+                log_warn "$dep_label: contract_path '$contract_path' declared but not yet present (provisional — acceptable)"
+                ((WARNINGS++))
+            fi
+        fi
+    fi
+
+    if [[ "$dep_errors" -eq 0 ]]; then
+        log_pass "$dep_label: stability=$required_stability type=$contract_type"
+        ((PASSED_DEPS++))
+        return 0
+    fi
+
+    FAILURES=$((FAILURES + dep_errors))
+    return 1
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+print_status_table() {
+    log_section "Dependency Status Table"
+
+    local app_id
+    app_id="$(yq e ".app_id // \"unknown\"" "$APP_DEPS_FILE")"
+    log_info "App: $app_id"
+
+    printf "\n  %-30s %-15s %-12s %s\n" "Service ID" "Stability" "Contract" "Status"
+    printf "  %-30s %-15s %-12s %s\n" "──────────────────────────────" "───────────────" "────────────" "──────────"
+
+    local count
+    count="$(yq e ".platform_dependencies | length" "$APP_DEPS_FILE")"
+
+    for ((i = 0; i < count; i++)); do
+        local service_id required_stability contract_type contract_path dep_status
+        service_id="$(yq e ".platform_dependencies[$i].service_id // \"(missing)\"" "$APP_DEPS_FILE")"
+        required_stability="$(yq e ".platform_dependencies[$i].required_stability // \"(missing)\"" "$APP_DEPS_FILE")"
+        contract_type="$(yq e ".platform_dependencies[$i].contract_type // \"(missing)\"" "$APP_DEPS_FILE")"
+        contract_path="$(yq e ".platform_dependencies[$i].contract_path // \"\"" "$APP_DEPS_FILE")"
+
+        # Determine display status
+        if [[ "$required_stability" == "locked" ]]; then
+            if [[ -n "$contract_path" && "$contract_path" != "null" && -f "$PLATFORM_ROOT/$contract_path" ]]; then
+                dep_status="${GREEN}LOCKED OK${NC}"
+            else
+                dep_status="${RED}LOCKED UNMET${NC}"
+            fi
+        elif [[ "$required_stability" == "provisional" ]]; then
+            dep_status="${YELLOW}PROVISIONAL${NC}"
+        else
+            dep_status="${RED}INVALID${NC}"
+        fi
+
+        printf "  %-30s %-15s %-12s " "$service_id" "$required_stability" "$contract_type"
+        echo -e "$dep_status"
+    done
+    echo ""
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+main() {
+    log_section "App Dependency Validation"
+    log_info "App root:      $APP_ROOT"
+    log_info "Platform root: $PLATFORM_ROOT"
+
+    check_prerequisites
+
+    log_section "Validating Dependencies"
+
+    local dep_count
+    dep_count="$(yq e ".platform_dependencies | length" "$APP_DEPS_FILE")"
+    TOTAL_DEPS="$dep_count"
+
+    if [[ "$dep_count" -eq 0 ]]; then
+        log_warn "No platform_dependencies entries found in app-platform-dependencies.yaml"
+        log_info "If this app has no platform deps, this is acceptable."
+        exit 0
+    fi
+
+    for ((i = 0; i < dep_count; i++)); do
+        validate_dependency "$i" || true
+    done
+
+    print_status_table
+
+    log_section "Summary"
+    log_info "Total dependencies: $TOTAL_DEPS"
+    log_info "Passed:  $PASSED_DEPS"
+    log_info "Warnings: $WARNINGS"
+    log_info "Failures: $FAILURES"
+
+    if [[ "$FAILURES" -gt 0 ]]; then
+        log_fail "$FAILURES dependency check(s) failed. Stage 6 lock-in gate NOT met."
+        exit 1
+    fi
+
+    if [[ "$WARNINGS" -gt 0 ]]; then
+        log_warn "All required checks passed with $WARNINGS warning(s)."
+    else
+        log_pass "All dependency checks passed. Stage 6 lock-in gate met."
+    fi
+    exit 0
+}
+
+main "$@"