@metasession.co/devaudit-cli 0.3.8 → 0.3.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metasession.co/devaudit-cli",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "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.8",
+    "@metasession.co/devaudit-plugin-sdk": "^0.3.10",
     "ajv": "^8.20.0",
     "commander": "^12.1.0",
     "consola": "^3.2.3",

package/scripts/upload-evidence.sh

@@ -54,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/
@@ -345,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))
@@ -355,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
 

package/sdlc/files/_common/joining-an-existing-project.md

@@ -152,9 +152,10 @@ Two distinct credentials exist; conflating them is what causes the silent-CI-tok
 |---|---|---|---|---|
 | **Personal PAT** | `mctok_…` | `~/.config/devaudit/auth.json` (per developer) | You (the user) | Your local CLI commands |
 | **Project API key** | `dak_…` | Repo secret `DEVAUDIT_API_KEY` | The project | CI's `devaudit push` calls |
-| **Operator's PAT** | `mctok_…` | Repo secret `DEVAUDIT_USER_TOKEN` | The operator (singular) | CI's mutation calls (release register, approval submit) |
+| **Operator's PAT** | `mctok_…` | Repo secret `DEVAUDIT_USER_TOKEN` | The operator (singular) | CI's DevAudit portal calls that need human attribution (release submit / approval flows) |
+| **GitHub workflow token** | `${{ github.token }}` | Issued automatically per workflow run | The GitHub Actions workflow | CI's GitHub repo mutations (checkout, branch push, PR, issue, comment, label, check-run updates) |
 
-**Never paste your personal PAT into a repo secret.** Repo `DEVAUDIT_USER_TOKEN` is operator-owned. CI portal mutations are attributed to whoever's PAT is there — if it's yours, your name shows up against every release the team ships, and the moment your PAT expires CI breaks. Rotation belongs to the operator: `devaudit install --force-team-config` on their machine.
+**Never paste your personal PAT into a repo secret.** Repo `DEVAUDIT_USER_TOKEN` is operator-owned and is not the default GitHub auth path for workflow repo mutations. CI portal mutations are attributed to whoever's PAT is there — if it's yours, your name shows up against every release the team ships, and the moment your PAT expires CI portal actions break. Rotation belongs to the operator: `devaudit install --force-team-config` on their machine.
 
 If `devaudit auth status` shows the wrong user, run `devaudit auth logout && devaudit auth login` and paste the right PAT.
 
@@ -181,10 +182,10 @@ The synced CI gates expect a specific environment. Here's what you need locally
 
 | Surface | CI | Local (your machine) |
 |---|---|---|
-| Personal identity | `secrets.DEVAUDIT_USER_TOKEN` (operator's) | `~/.config/devaudit/auth.json` (yours) — `devaudit auth login` |
+| Personal identity | `secrets.DEVAUDIT_USER_TOKEN` (operator's, portal-only) | `~/.config/devaudit/auth.json` (yours) — `devaudit auth login` |
 | Project API key | `secrets.DEVAUDIT_API_KEY` | Usually unset locally — only needed if you're testing `devaudit push` against the live portal; ask the operator if you need to debug it |
 | Portal URL | `vars.DEVAUDIT_BASE_URL` | `~/.config/devaudit/auth.json` (set by `auth login`) or `$DEVAUDIT_BASE_URL` env |
-| GitHub auth | `${{ github.token }}` (auto) | `gh auth login` |
+| GitHub auth | `${{ github.token }}` (auto, repo mutations) | `gh auth login` |
 | Node | matrix-pinned to project's `node_version` | nvm / volta / whatever — `devaudit doctor` checks ≥ 22 |
 | `jq` / `curl` | always present on GH runners | install via package manager — `devaudit doctor` flags absence |
 

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

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# close-out-contract.test.sh — Tests for the close-out marker helper.
+#
+# Usage:
+#   ./scripts/close-out-contract.test.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/close-out-contract.sh"
+
+PASS=0
+FAIL=0
+
+assert_eq() {
+  local desc="$1" want="$2" got="$3"
+  if [ "$got" = "$want" ]; then
+    echo "  PASS: $desc"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $desc"
+    echo "        want: $want"
+    echo "        got:  $got"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+assert_true() {
+  local desc="$1"
+  shift
+  if "$@"; then
+    echo "  PASS: $desc"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $desc"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+assert_false() {
+  local desc="$1"
+  shift
+  if "$@"; then
+    echo "  FAIL: $desc"
+    FAIL=$((FAIL + 1))
+  else
+    echo "  PASS: $desc"
+    PASS=$((PASS + 1))
+  fi
+}
+
+echo "=== close-out-contract.sh tests ==="
+
+assert_eq "branch prefix constant" "chore/close-out-" "$CLOSEOUT_BRANCH_PREFIX"
+assert_eq "marker prefix constant" "Release-Closeout:" "$CLOSEOUT_MARKER_PREFIX"
+assert_eq "closeout_marker emits structured line" "Release-Closeout: REQ-090" "$(closeout_marker REQ-090)"
+
+assert_true "is_closeout_marker accepts canonical marker" is_closeout_marker "Release-Closeout: REQ-090"
+assert_true "is_closeout_marker accepts extra whitespace" is_closeout_marker "Release-Closeout:    REQ-123"
+assert_false "is_closeout_marker rejects wrong prefix" is_closeout_marker "Closeout: REQ-090"
+assert_false "is_closeout_marker rejects short req ids" is_closeout_marker "Release-Closeout: REQ-9"
+assert_false "is_closeout_marker rejects bare prose mention" is_closeout_marker "This closes REQ-090 after release."
+
+assert_eq "closeout_marker_req extracts req id" "REQ-090" "$(closeout_marker_req "Release-Closeout: REQ-090")"
+assert_eq "closeout_marker_req extracts first req id from mixed text" "REQ-111" "$(closeout_marker_req $'x\nRelease-Closeout: REQ-111\nmore')"
+assert_eq "closeout_marker_req returns empty when marker absent" "" "$(closeout_marker_req "no marker here" || true)"
+
+echo
+echo "Result: $PASS passed, $FAIL failed"
+[ "$FAIL" = "0" ]

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

@@ -275,6 +275,54 @@ 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.test.sh

@@ -273,6 +273,91 @@ assert_eq "RTM issue title fallback without ticket" "Issue title from RTM" "$REL
 assert_empty "Summary empty without ticket" "$RELEASE_SUMMARY"
 echo ""
 
+# --- Test 12 (#571 Gap 3): No ticket, no RTM, no gh CLI — all fallbacks empty ---
+echo "--- Test 12: All fallbacks unreachable ---"
+make_fixture "$WORK/test12"
+source "$HELPER"
+extract_release_metadata "REQ-999"
+assert_empty "Title empty when no ticket, no RTM, no gh" "$RELEASE_TITLE"
+assert_empty "Summary empty when no ticket" "$RELEASE_SUMMARY"
+echo ""
+
+# --- Test 13 (#571 Gap 3): Ticket exists but has no **Requirement:** line,
+# no H1, and no ## Summary — all extraction targets are unreachable ---
+echo "--- Test 13: Ticket with no extractable content ---"
+make_fixture "$WORK/test13"
+cat > "compliance/pending-releases/RELEASE-TICKET-REQ-012.md" <<'TICKET'
+Some prose without any standard headings.
+
+Just a paragraph.
+TICKET
+
+source "$HELPER"
+extract_release_metadata "REQ-012"
+assert_empty "Title empty when no Requirement line or H1" "$RELEASE_TITLE"
+assert_empty "Summary empty when no ## Summary section" "$RELEASE_SUMMARY"
+echo ""
+
+# --- Test 14 (#571 Gap 3): RTM row exists but has no issue number,
+# so the gh CLI fallback is unreachable. Title should be empty. ---
+echo "--- Test 14: RTM row without issue number ---"
+make_fixture "$WORK/test14"
+cat > compliance/RTM.md <<'RTM'
+| REQ-ID  | Issue | Risk | Evidence | Status |
+| ------- | ----- | ---- | -------- | ------ |
+| REQ-013 |       | LOW  | n/a      | DRAFT  |
+RTM
+source "$HELPER"
+extract_release_metadata "REQ-013"
+assert_empty "Title empty when RTM row has no issue number" "$RELEASE_TITLE"
+echo ""
+
+# --- Test 15 (#571 Gap 3): gh CLI exists but issue lookup fails —
+# must fall through to H1 fallback, not error out ---
+echo "--- Test 15: gh CLI fails, falls through to H1 ---"
+make_fixture "$WORK/test15"
+cat > "compliance/pending-releases/RELEASE-TICKET-REQ-014.md" <<'TICKET'
+# Fix critical payment bug
+
+## Summary
+Fixes the payment redirect issue.
+TICKET
+cat > compliance/RTM.md <<'RTM'
+| REQ-ID  | Issue | Risk | Evidence | Status |
+| ------- | ----- | ---- | -------- | ------ |
+| REQ-014 | #999  | LOW  | n/a      | DRAFT  |
+RTM
+mkdir -p bin
+cat > bin/gh <<'GH'
+#!/usr/bin/env bash
+# Simulate gh CLI failing (e.g. rate limited, issue not found)
+exit 1
+GH
+chmod +x bin/gh
+PATH="$PWD/bin:$PATH"
+source "$HELPER"
+extract_release_metadata "REQ-014"
+assert_eq "H1 fallback when gh CLI fails" "Fix critical payment bug" "$RELEASE_TITLE"
+echo ""
+
+# --- Test 16 (#571 Gap 3): Summary section exists but is only whitespace ---
+echo "--- Test 16: Whitespace-only summary is cleared ---"
+make_fixture "$WORK/test16"
+cat > "compliance/pending-releases/RELEASE-TICKET-REQ-015.md" <<'TICKET'
+**Requirement:** REQ-015 — Feature fifteen
+
+## Summary
+
+## Changes
+- Change A
+TICKET
+
+source "$HELPER"
+extract_release_metadata "REQ-015"
+assert_eq "Title extracted" "Feature fifteen" "$RELEASE_TITLE"
+assert_empty "Whitespace-only summary cleared" "$RELEASE_SUMMARY"
+echo ""
+
 echo ""
 echo "=== Results: $PASS passed, $FAIL failed ==="
 exit $FAIL

package/sdlc/files/_common/scripts/prepare-release-pr.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# prepare-release-pr.sh — ensure there is one truthful release PR.
+#
+# Usage:
+#   ./scripts/prepare-release-pr.sh [--apply] [--mode=update|recreate]
+#
+# Default mode is dry-run + update. Dry-run prints the action it would take.
+# With --apply:
+#   - no existing PR: creates one
+#   - current PR: updates title/body only when needed
+#   - stale PR + mode=update: rewrites title/body and comments
+#   - stale PR + mode=recreate: closes old PR and opens a fresh one
+
+set -euo pipefail
+
+APPLY=false
+MODE="update"
+for arg in "$@"; do
+  case "$arg" in
+    --apply) APPLY=true ;;
+    --mode=update) MODE="update" ;;
+    --mode=recreate) MODE="recreate" ;;
+    *) echo "Unknown argument: $arg" >&2; exit 2 ;;
+  esac
+done
+
+INTEGRATION_BRANCH=$(jq -r '.integration_branch // "develop"' sdlc-config.json 2>/dev/null || echo "develop")
+RELEASE_BRANCH=$(jq -r '.release_branch // "main"' sdlc-config.json 2>/dev/null || echo "main")
+
+if [ ! -x scripts/derive-release-version.sh ]; then
+  chmod +x scripts/derive-release-version.sh 2>/dev/null || true
+fi
+CURRENT_RELEASE=$(./scripts/derive-release-version.sh)
+if [ -z "$CURRENT_RELEASE" ]; then
+  echo "No active release version derived; close-out reconciliation appears in progress." >&2
+  exit 1
+fi
+
+TITLE="Release: ${CURRENT_RELEASE}"
+BODY=$(cat <<EOF
+## Release
+
+- Release: ${CURRENT_RELEASE}
+- Base: ${RELEASE_BRANCH}
+- Head: ${INTEGRATION_BRANCH}
+
+## DevAudit
+
+- Release context is derived from the current ${INTEGRATION_BRANCH} head.
+- If this PR replaced an older release PR, the older PR was superseded because it no longer matched the governing release context.
+EOF
+)
+
+OPEN_PRS=$(gh pr list --base "$RELEASE_BRANCH" --head "$INTEGRATION_BRANCH" --state open --json number,title,body,url --limit 10)
+COUNT=$(echo "$OPEN_PRS" | jq 'length')
+
+if [ "$COUNT" -eq 0 ]; then
+  echo "No open ${INTEGRATION_BRANCH}->${RELEASE_BRANCH} PR found."
+  if [ "$APPLY" = "true" ]; then
+    gh pr create --base "$RELEASE_BRANCH" --head "$INTEGRATION_BRANCH" --title "$TITLE" --body "$BODY"
+  else
+    echo "Dry run: would create release PR titled '$TITLE'."
+  fi
+  exit 0
+fi
+
+if [ "$COUNT" -gt 1 ]; then
+  echo "ERROR: ${COUNT} open ${INTEGRATION_BRANCH}->${RELEASE_BRANCH} PRs found. Resolve duplicates manually." >&2
+  echo "$OPEN_PRS" | jq -r '.[] | "  #\(.number) \(.title) \(.url)"' >&2
+  exit 1
+fi
+
+PR_NUMBER=$(echo "$OPEN_PRS" | jq -r '.[0].number')
+PR_TITLE=$(echo "$OPEN_PRS" | jq -r '.[0].title // ""')
+PR_BODY=$(echo "$OPEN_PRS" | jq -r '.[0].body // ""')
+PR_URL=$(echo "$OPEN_PRS" | jq -r '.[0].url')
+
+if printf '%s\n%s\n' "$PR_TITLE" "$PR_BODY" | grep -q "$CURRENT_RELEASE"; then
+  echo "Open release PR #${PR_NUMBER} already matches ${CURRENT_RELEASE}: ${PR_URL}"
+  exit 0
+fi
+
+echo "Open release PR #${PR_NUMBER} is stale for current release ${CURRENT_RELEASE}: ${PR_URL}"
+echo "Current title: ${PR_TITLE}"
+
+if [ "$APPLY" != "true" ]; then
+  echo "Dry run: would ${MODE} stale PR #${PR_NUMBER} for ${CURRENT_RELEASE}."
+  exit 0
+fi
+
+if [ "$MODE" = "recreate" ]; then
+  gh pr comment "$PR_NUMBER" --body "Superseded: current ${INTEGRATION_BRANCH} head now derives ${CURRENT_RELEASE}; this PR no longer matches the governing release context."
+  gh pr close "$PR_NUMBER" --comment "Closed as superseded by ${CURRENT_RELEASE} release context."
+  gh pr create --base "$RELEASE_BRANCH" --head "$INTEGRATION_BRANCH" --title "$TITLE" --body "$BODY"
+else
+  gh pr edit "$PR_NUMBER" --title "$TITLE" --body "$BODY"
+  gh pr comment "$PR_NUMBER" --body "Release PR context refreshed: current ${INTEGRATION_BRANCH} head derives ${CURRENT_RELEASE}."
+  echo "Updated PR #${PR_NUMBER} to ${CURRENT_RELEASE}: ${PR_URL}"
+fi