@metasession.co/devaudit-cli 0.3.7 → 0.3.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "DevAudit CLI — installs, syncs, and operates the Metasession SDLC across consumer projects.",
   "type": "module",
   "bin": {
@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.8.2",
-    "@metasession.co/devaudit-plugin-sdk": "^0.3.7",
+    "@metasession.co/devaudit-plugin-sdk": "^0.3.9",
     "ajv": "^8.20.0",
     "commander": "^12.1.0",
     "consola": "^3.2.3",

package/scripts/upload-evidence.sh

@@ -21,6 +21,11 @@
 #                               release-ticket H1). Forwarded as
 #                               `releaseTitle`; the portal no-clobbers
 #                               existing non-null values.
+#   --release-summary <text>    Reviewer-facing short description of what
+#                               the release covers. Forwarded as
+#                               `releaseSummary`; the portal no-clobbers
+#                               existing non-null values.
+#                               DevAudit-Installer#285.
 #   --change-type <type>        Conventional-commit prefix (feat / fix /
 #                               refactor / perf / chore / docs / ci /
 #                               build / test / compliance / revert) for
@@ -49,6 +54,14 @@
 #                         Issue from: Project Settings → API Keys in
 #                         META-COMPLY's web UI.
 #
+# Large-file uploads (>=25MB):
+#   Files above 25MB use a presigned R2 upload flow (3-step: request URL →
+#   PUT to R2 → notify portal) instead of multipart POST. This requires
+#   the Portal to be configured with R2 evidence storage
+#   (R2_EVIDENCE_BUCKET and related env vars). If R2 is not configured,
+#   the Portal returns a clear error which is surfaced to the operator.
+#   #298 — the Portal response body is included in the error output.
+#
 # Examples:
 #   ./scripts/upload-evidence.sh meta-ats REQ-001 screenshot \
 #       compliance/evidence/REQ-001/screenshots/
@@ -80,6 +93,7 @@ CREATE_RELEASE_IF_MISSING=false
 ENVIRONMENT=""
 EVIDENCE_CATEGORY=""
 RELEASE_TITLE=""
+RELEASE_SUMMARY=""
 CHANGE_TYPE=""
 GATE_STATUS=""
 SDLC_STAGE=""
@@ -103,6 +117,7 @@ while [ "$#" -gt 0 ]; do
     # the portal's findOrCreateRelease no-clobber backfill. Both optional;
     # unknown change-type values are dropped server-side, not 400'd.
     --release-title) RELEASE_TITLE="$2"; shift 2 ;;
+    --release-summary) RELEASE_SUMMARY="$2"; shift 2 ;;
     --change-type) CHANGE_TYPE="$2"; shift 2 ;;
     # passed/failed/skipped — surfaces failed gates on the portal so
     # ran-and-failed != never-ran. Unknown values dropped server-side.
@@ -320,6 +335,8 @@ upload_presigned() {
         \"releaseBranch\": \"${BRANCH}\",
         \"environment\": \"${ENVIRONMENT}\",
         \"evidenceCategory\": \"${EVIDENCE_CATEGORY}\",
+        \"releaseTitle\": \"${RELEASE_TITLE}\",
+        \"releaseSummary\": \"${RELEASE_SUMMARY}\",
         \"sdlcStage\": \"${SDLC_STAGE}\",
         \"testCycleId\": \"${TEST_CYCLE}\"
       }") || curl_exit=$?
@@ -336,9 +353,9 @@ upload_presigned() {
       echo -n "(portal did not return presigned URL, falling back to multipart) "
       return 255
     fi
-    rm -f "$resp_body"
     if [ "$curl_exit" -ne 0 ] || [ "$http_code" = "429" ] || { [ "$http_code" -ge 500 ] && [ "$http_code" -lt 600 ]; }; then
       if [ "$attempt" -lt "$PRESIGNED_MAX_ATTEMPTS" ]; then
+        rm -f "$resp_body"
         echo -n "(step 1: HTTP ${http_code}, retry in ${backoff}s) "
         sleep "$backoff"
         attempt=$((attempt + 1))
@@ -346,8 +363,20 @@ upload_presigned() {
         continue
       fi
     fi
-    # Non-retriable error (4xx other than 429).
-    echo -n "(step 1 failed: HTTP ${http_code}) "
+    # Non-retriable error (4xx other than 429) or exhausted retries.
+    # #298 — Surface the Portal response body so operators see WHY it
+    # failed (e.g. "Presigned uploads require R2 storage configuration")
+    # instead of just "HTTP 501". Include up to 500 chars of the body.
+    local err_excerpt=""
+    if [ -s "$resp_body" ]; then
+      err_excerpt=$(head -c 500 "$resp_body")
+    fi
+    rm -f "$resp_body"
+    echo -n "(step 1 failed: HTTP ${http_code}"
+    if [ -n "$err_excerpt" ]; then
+      echo -n " — ${err_excerpt}"
+    fi
+    echo ") "
     return 1
   done
 
@@ -469,6 +498,7 @@ for FILE in "${FILES[@]}"; do
   [ -n "$ENVIRONMENT" ] && CURL_ARGS+=(-F "environment=${ENVIRONMENT}")
   [ -n "$EVIDENCE_CATEGORY" ] && CURL_ARGS+=(-F "evidenceCategory=${EVIDENCE_CATEGORY}")
   [ -n "$RELEASE_TITLE" ] && CURL_ARGS+=(-F "releaseTitle=${RELEASE_TITLE}")
+  [ -n "$RELEASE_SUMMARY" ] && CURL_ARGS+=(-F "releaseSummary=${RELEASE_SUMMARY}")
   [ -n "$CHANGE_TYPE" ] && CURL_ARGS+=(-F "changeType=${CHANGE_TYPE}")
   [ -n "$GATE_STATUS" ] && CURL_ARGS+=(-F "gateStatus=${GATE_STATUS}")
   [ -n "$SDLC_STAGE" ] && CURL_ARGS+=(-F "sdlcStage=${SDLC_STAGE}")

package/sdlc/files/_common/scripts/close-out-contract.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# close-out-contract.sh — Shared constants for release close-out automation.
+#
+# Sourced by close-out-release.yml.template and any CI logic that needs to
+# recognise or suppress reconciliation pushes (devaudit#281, devaudit#284).
+#
+# Usage: source scripts/close-out-contract.sh
+#   CLOSEOUT_BRANCH_PREFIX  — reserved automation branch prefix
+#   CLOSEOUT_MARKER         — structured marker for PR/commit bodies
+#   CLOSEOUT_MARKER_REGEX   — grep pattern to detect the marker
+
+# Reserved branch prefix for automation. Humans should not use this for
+# unrelated housekeeping work.
+CLOSEOUT_BRANCH_PREFIX="chore/close-out-"
+
+# Structured close-out marker emitted in the PR body / merge commit body.
+# Format: Release-Closeout: REQ-XXX
+CLOSEOUT_MARKER_PREFIX="Release-Closeout:"
+CLOSEOUT_MARKER_REGEX='^Release-Closeout:[[:space:]]*REQ-[0-9]{3,}'
+
+# Emit the marker for a given REQ-ID.
+closeout_marker() {
+  printf '%s %s\n' "$CLOSEOUT_MARKER_PREFIX" "$1"
+}
+
+# Check if a string (e.g. commit body, PR body) contains the close-out marker.
+is_closeout_marker() {
+  grep -qE "$CLOSEOUT_MARKER_REGEX" <<< "$1"
+}
+
+# Extract the REQ-ID from a close-out marker string.
+closeout_marker_req() {
+  grep -oE "$CLOSEOUT_MARKER_REGEX" <<< "$1" | grep -oE 'REQ-[0-9]{3,}' | head -1
+}

package/sdlc/files/_common/scripts/derive-release-version.sh

@@ -16,6 +16,12 @@
 #   4-bis. RTM.md IN PROGRESS row:    exactly one tracked REQ marked
 #                                      IN PROGRESS in compliance/RTM.md
 #                                                                    -> REQ-XXX
+#   4-ter. Close-out marker:           commit body contains
+#                                      "Release-Closeout: REQ-XXX"
+#                                      (devaudit#284 — suppresses false
+#                                      housekeeping stubs from release
+#                                      reconciliation merges)
+#                                                                    -> empty/skip
 #   5. Fallback:                      bare date                      -> v2026.05.17
 #
 # Step 4 (DevAudit-Installer#92) handles `chore:` / `docs:` / `ci:`
@@ -127,5 +133,17 @@ if [ -f "$RTM_PATH" ]; then
   fi
 fi
 
+# 4-ter. Close-out marker suppression (devaudit#284).
+# A push that is solely the result of completing a tracked release's
+# reconciliation/close-out path must not derive a bare-date housekeeping
+# release. The close-out workflow (devaudit#281) emits a structured
+# `Release-Closeout: REQ-XXX` marker in the merge commit body. When
+# present, emit no version. Workflow callers translate the empty result
+# to an explicit `skip` sentinel so reconciliation pushes neither create
+# housekeeping releases nor attach new evidence to an already released REQ.
+if echo "$BODY" | grep -qE '^Release-Closeout:[[:space:]]*REQ-[0-9]{3,}'; then
+  exit 0
+fi
+
 # 5. Fallback: bare date in UTC
 echo "v$(date -u +%Y.%m.%d)"

package/sdlc/files/_common/scripts/derive-release-version.test.sh

@@ -266,6 +266,63 @@ cat > compliance/RTM.md <<'RTM'
 RTM
 assert_eq "RTM two IN PROGRESS w/ escaped pipes -> bare date $TODAY" "$TODAY" "$(run_helper)"
 
+# Case 21: close-out reconciliation marker suppresses release registration.
+# The workflow caller translates this empty stdout to version=skip so the
+# reconciliation push neither creates housekeeping stubs nor attaches evidence
+# to an already released REQ.
+make_fixture "$WORK/c21" "chore(release): reconcile REQ-089 close-out
+
+Release-Closeout: REQ-089"
+assert_eq "close-out marker -> empty version" "" "$(run_helper)"
+
+# Case 22 (#571 Gap 3): close-out marker with no REQ digits — must NOT
+# suppress the bare-date fallback. The regex requires REQ-[0-9]{3,} so
+# a malformed marker like "Release-Closeout: REQ-AB" should fall through
+# to the bare date.
+make_fixture "$WORK/c22" "chore(release): reconcile close-out
+
+Release-Closeout: REQ-AB"
+assert_eq "malformed close-out marker -> bare date $TODAY" "$TODAY" "$(run_helper)"
+
+# Case 23 (#571 Gap 3): close-out marker with extra whitespace — must
+# still suppress (regex allows leading whitespace after the colon).
+make_fixture "$WORK/c23" "chore(release): reconcile REQ-100 close-out
+
+Release-Closeout:    REQ-100"
+assert_eq "close-out marker with extra whitespace -> empty" "" "$(run_helper)"
+
+# Case 24 (#571 Gap 3): no ticket file, no RTM, no git tags, no close-out
+# marker — the ultimate fallback chain reaches the bare date. This tests
+# that every prior step's `exit 0` guard correctly falls through when
+# its condition is not met.
+make_fixture "$WORK/c24" "chore: misc cleanup with no compliance state"
+assert_eq "no compliance state at all -> bare date $TODAY" "$TODAY" "$(run_helper)"
+
+# Case 25 (#571 Gap 3): pending-releases dir exists but is empty — step 4
+# must not crash and must fall through to step 4-bis / bare date.
+make_fixture "$WORK/c25" "chore: devaudit update to 0.1.30"
+mkdir -p compliance/pending-releases
+assert_eq "empty pending-releases dir -> bare date $TODAY" "$TODAY" "$(run_helper)"
+
+# Case 26 (#571 Gap 3): RTM.md exists but has no IN PROGRESS rows —
+# step 4-bis must fall through to the bare date.
+make_fixture "$WORK/c26" "chore: devaudit update to 0.1.30"
+mkdir -p compliance
+cat > compliance/RTM.md <<'RTM'
+| REQ-ID  | Status        |
+| ------- | ------------- |
+| REQ-001 | RELEASED      |
+| REQ-002 | DRAFT         |
+RTM
+assert_eq "RTM with no IN PROGRESS -> bare date $TODAY" "$TODAY" "$(run_helper)"
+
+# Case 27 (#571 Gap 3): RTM.md exists but is empty (no rows at all) —
+# step 4-bis must not crash and must fall through.
+make_fixture "$WORK/c27" "chore: devaudit update to 0.1.30"
+mkdir -p compliance
+echo "# Requirements Traceability Matrix" > compliance/RTM.md
+assert_eq "empty RTM.md -> bare date $TODAY" "$TODAY" "$(run_helper)"
+
 echo ""
 echo "=== Summary: $PASS pass / $FAIL fail ==="
 

package/sdlc/files/_common/scripts/extract-release-metadata.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# extract-release-metadata.sh — Extract canonical tracked-release metadata.
+#
+# DevAudit-Installer#285 — Provides one shared extraction source of truth for
+# tracked-release title and summary, usable from both CI workflow paths
+# (ci.yml.template and compliance-evidence.yml.template).
+#
+# Usage:
+#   source scripts/extract-release-metadata.sh
+#   extract_release_metadata "REQ-089"
+#
+# Sets the following shell variables:
+#   RELEASE_TITLE      — canonical human title (empty if none found)
+#   RELEASE_SUMMARY    — reviewer-facing summary from ## Summary section (empty if none)
+#
+# Title fallback chain (normative per #285):
+#   1. **Requirement:** line in RELEASE-TICKET-REQ-XXX.md → human part after "REQ-XXX —"
+#   2. GitHub issue title from RTM row (best-effort, requires gh CLI)
+#   3. Normalised ticket H1 only if no better source exists
+#   4. Empty rather than garbage
+#
+# Summary rules:
+#   - Capture content between ## Summary and the next ## heading
+#   - Trim boilerplate / empty placeholders
+#   - Empty if section absent or still a stub
+
+set -euo pipefail
+
+extract_release_metadata() {
+  local req_id="$1"
+  RELEASE_TITLE=""
+  RELEASE_SUMMARY=""
+
+  local ticket_file=""
+  for FILE in \
+    "compliance/pending-releases/RELEASE-TICKET-${req_id}.md" \
+    "compliance/approved-releases/RELEASE-TICKET-${req_id}.md"; do
+    if [ -f "$FILE" ]; then
+      ticket_file="$FILE"
+      break
+    fi
+  done
+
+  # --- Title extraction ---
+  # 1. Try **Requirement:** REQ-XXX — <human title>
+  if [ -n "$ticket_file" ]; then
+    local req_line
+    req_line=$(grep -m1 '^\*\*Requirement:\*\*' "$ticket_file" 2>/dev/null || true)
+    if [ -n "$req_line" ]; then
+      # Extract the human part after "REQ-XXX —"
+      # Format: **Requirement:** REQ-089 — Some human title here
+      RELEASE_TITLE=$(printf '%s' "$req_line" \
+        | sed -E 's/^\*\*Requirement:\*\*[[:space:]]*//' \
+        | sed -E 's/^REQ-[0-9]+[[:space:]]*[—–:-][[:space:]]*//' \
+        | sed -E 's/[[:space:]]*$//')
+    fi
+  fi
+
+  # 2. Fallback: GitHub issue title from RTM row
+  if [ -z "$RELEASE_TITLE" ]; then
+    local rtm_row
+    rtm_row=$(grep -m1 "| ${req_id} " compliance/RTM.md 2>/dev/null || true)
+    if [ -n "$rtm_row" ] && command -v gh >/dev/null 2>&1; then
+      # Try to extract issue number from RTM row if present
+      local issue_num
+      issue_num=$(printf '%s' "$rtm_row" | grep -oE '#[0-9]+' | head -1 | tr -d '#' || true)
+      if [ -n "$issue_num" ]; then
+        RELEASE_TITLE=$(gh issue view "$issue_num" --json title --jq '.title' 2>/dev/null || true)
+      fi
+    fi
+  fi
+
+  # 3. Fallback: normalised ticket H1 (least preferred)
+  if [ -z "$RELEASE_TITLE" ] && [ -n "$ticket_file" ]; then
+    local h1_line
+    h1_line=$(grep -m1 '^# ' "$ticket_file" 2>/dev/null || true)
+    if [ -n "$h1_line" ]; then
+      # Strip the leading "# " and any "Release Ticket — REQ-XXX" prefix
+      RELEASE_TITLE=$(printf '%s' "$h1_line" \
+        | sed -E 's/^# *//' \
+        | sed -E 's/^Release Ticket[[:space:]]*[—:-][[:space:]]*//' \
+        | sed -E 's/^REQ-[0-9]+[[:space:]]*[—:-][[:space:]]*//' \
+        | sed -E 's/[[:space:]]*$//')
+    fi
+  fi
+
+  # 4. If still empty, leave empty rather than inventing garbage
+
+  # --- Summary extraction ---
+  # Capture content between ## Summary and the next ## heading
+  local summary_raw
+  summary_raw=""
+  if [ -n "$ticket_file" ]; then
+    summary_raw=$(awk '
+      /^## Summary/ { found=1; next }
+      /^## / { if (found) exit }
+      found { print }
+    ' "$ticket_file" 2>/dev/null || true)
+  fi
+
+  if [ -n "$summary_raw" ]; then
+    # Trim leading/trailing blank lines and trailing whitespace per line
+    RELEASE_SUMMARY=$(printf '%s' "$summary_raw" \
+      | sed -E 's/[[:space:]]+$//' \
+      | awk 'NF { p=1 } p { print }' \
+      | awk '{ lines[NR]=$0 } END { for (i=NR; i>=1; i--) { if (lines[i] ~ /[^[:space:]]/) { last=i; break } } for (i=1; i<=last; i++) print lines[i] }')
+  fi
+
+  # If summary is just placeholder/stub text, clear it
+  if [ -n "$RELEASE_SUMMARY" ]; then
+    local summary_lower
+    summary_lower=$(printf '%s' "$RELEASE_SUMMARY" | tr '[:upper:]' '[:lower:]')
+    case "$summary_lower" in
+      *"placeholder"*|*"todo"*|*"tbd"*|*"to be completed"*|*"stub"*)
+        RELEASE_SUMMARY=""
+        ;;
+    esac
+  fi
+}