@plainconceptsplatform/workflows 1.10.1 → 1.12.0

package/loops/templates/quality-gates/.jscpd.json

@@ -0,0 +1,36 @@
+{
+  "path": [
+    "apps/api/src",
+    "apps/web/src"
+  ],
+  "format": [
+    "csharp",
+    "typescript",
+    "tsx"
+  ],
+  "minLines": 10,
+  "minTokens": 70,
+  "maxLines": 100000,
+  "maxSize": "5mb",
+  "mode": "mild",
+  "reporters": [
+    "json"
+  ],
+  "output": "jscpd-report",
+  "absolute": true,
+  "gitignore": false,
+  "silent": true,
+  "noTips": true,
+  "ignore": [
+    "**/obj/**",
+    "**/bin/**",
+    "**/node_modules/**",
+    "**/*.g.cs",
+    "**/*.designer.cs",
+    "**/*.Designer.cs",
+    "**/Migrations/**",
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "**/__tests__/**"
+  ]
+}

package/loops/templates/quality-gates/.jscpd.json.md

@@ -0,0 +1,7 @@
+# Ownership: .jscpd.json
+
+Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/.jscpd.json. Update with `workflows update --force`; consumer edits may be overwritten.
+
+JSON (RFC 8259) does not permit comments, so the ownership header of `.jscpd.json` is documented here. The file is the duplication scope every app of the platform family shares: the jscpd report, the duplication gate (`scripts/check-duplication.mjs`) and the hygiene facet all read it, so they measure one file set.
+
+An app that needs a different scope takes the file over by removing the header paragraph above; `workflows update` then leaves both files alone. Its per-file backlog stays in the app's own `scripts/duplication-baseline.json`, which the package never installs.

package/loops/templates/quality-gates/.semgrep/platform-hygiene.yml

@@ -0,0 +1,88 @@
+# Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/.semgrep/platform-hygiene.yml. Update with `workflows update --force`; consumer edits may be overwritten.
+# Hygiene rules (practice 11, code hygiene) shared by the platform family, run by the blocking
+# Semgrep scan in .github/workflows/app-ci.yml via `--config .semgrep/`. Their findings also feed
+# the `engineering-excellence-hygiene` facet (swallowed-exception counts). Shape from
+# PlainConceptsPlatform/Atlas .semgrep/atlas-hygiene.yml, rule ids neutral so every app shares them.
+#
+# A `catch` with an empty body turns a failure into silence. These rules flag an
+# empty body whatever it catches: a bare `catch`, `catch (Exception)`, or a narrow
+# type. A comment inside the braces is not handling and does not exempt it.
+#
+# One shape is exempt by design: `catch (OperationCanceledException) when
+# (<token>.IsCancellationRequested) { }`, the hosted-service shutdown idiom. It
+# swallows exactly the cancellation its own caller requested, and nothing else; an
+# unfiltered cancellation catch also hides an HttpClient timeout, so it is flagged.
+#
+# Where swallowing is genuinely correct, say why where a reviewer reads it, on the
+# line the finding starts (the `try`) or the line above it:
+#
+#   // nosemgrep: platform-hygiene-csharp-empty-catch — <why swallowing is correct here>
+#
+# The facet counts these justifications, so the backlog of swallowed exceptions stays
+# visible even while the gate is green. Test code is out of scope: a test that
+# expects a throw has its own idioms.
+# See Foundations ai/ENGINEERING.md.
+rules:
+  - id: platform-hygiene-csharp-empty-catch
+    languages: [csharp]
+    severity: ERROR
+    message: >-
+      Empty catch block: the exception is swallowed without logging, rethrowing or a
+      fallback. Handle it, or justify it on the `try` line with
+      `// nosemgrep: platform-hygiene-csharp-empty-catch — <reason>`.
+    metadata:
+      category: hygiene
+    paths:
+      # Product code only: .opencode/plugins and the managed .github actions belong to the
+      # agent-harness and agentic-workflows packages.
+      include:
+        - "/apps/"
+      exclude:
+        - "**/tests/**"
+        - "**/obj/**"
+        - "**/Migrations/**"
+    pattern-either:
+      # Catch-all: never exempt, even next to a filtered cancellation catch.
+      - pattern: try { ... } catch { }
+      - pattern: try { ... } catch { } finally { ... }
+      - pattern: try { ... } catch (Exception) { }
+      - pattern: try { ... } catch (Exception $E) { }
+      - pattern: try { ... } catch (System.Exception) { }
+      - pattern: try { ... } catch (System.Exception $E) { }
+      - pattern: try { ... } catch (Exception) { } finally { ... }
+      - pattern: try { ... } catch (Exception $E) { } finally { ... }
+      - patterns:
+          - pattern-either:
+              - pattern: try { ... } catch ($T) { }
+              - pattern: try { ... } catch ($T $E) { }
+              - pattern: try { ... } catch ($T) { } finally { ... }
+              - pattern: try { ... } catch ($T $E) { } finally { ... }
+          # Semgrep's C# grammar drops the `when` filter, so the exemption is textual.
+          - pattern-not-regex: catch\s*\(\s*OperationCanceledException(\s+\w+)?\s*\)\s*when\s*\(\s*[\w.]*IsCancellationRequested\s*\)\s*\{[^}]*\}
+
+  - id: platform-hygiene-ts-empty-catch
+    languages: [typescript, javascript]
+    severity: ERROR
+    message: >-
+      Empty catch block: the error is swallowed without logging, rethrowing or a
+      fallback. Handle it, or justify it on the `try` line with
+      `// nosemgrep: platform-hygiene-ts-empty-catch — <reason>`.
+    metadata:
+      category: hygiene
+    paths:
+      include:
+        - "/apps/"
+      exclude:
+        - "**/*.test.ts"
+        - "**/*.test.tsx"
+        - "**/*.test.mjs"
+        - "**/*.spec.ts"
+        - "**/__tests__/**"
+        - "**/e2e/**"
+        - "**/node_modules/**"
+        - "**/dist/**"
+    pattern-either:
+      - pattern: try { ... } catch { }
+      - pattern: try { ... } catch ($E) { }
+      - pattern: try { ... } catch { } finally { ... }
+      - pattern: try { ... } catch ($E) { } finally { ... }

package/loops/templates/quality-gates/.zap/rules.tsv

@@ -0,0 +1,26 @@
+# Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/.zap/rules.tsv. Update with `workflows update --force`; consumer edits may be overwritten.
+# ZAP baseline triage for .github/workflows/security-dast.yml.
+#
+# Format, tab-separated:	<rule-id>	<WARN|IGNORE|FAIL>	<justification>
+#
+# Each entry is a reviewed decision about one rule, and the justification column is mandatory.
+# An IGNORE that a fix would remove names the issue tracking that fix. Never add an IGNORE just
+# to turn the job green: fix the finding, or record here why the rule does not apply to the app.
+# An app that needs a triage line of its own takes this file over: remove the header line above.
+#
+# Shared by the platform family. 10020, 10021, 10035, 10038, 10063, 90004 and 10015 are fixed at
+# source by the platform security headers (Api/Security/SecurityHeaders.cs), and 90003 by
+# self-hosting Geist Mono, so none of them appears here. See Foundations ai/ENGINEERING.md.
+#
+# OUTOFSCOPE lines take a URL regex as the third column instead of a justification, so the
+# justification sits in the comment above each one.
+#
+# An anonymous / answers only with a 302 to the Entra sign-in. ZAP follows it and files
+# login.microsoftonline.com's page, headers and cookies (esctx, fpc, x-ms-gateway-slice) under
+# the app's /, so the header and cookie rules fire on a page the app does not serve. The app's own
+# headers on that redirect come from the same middleware as /login, which stays in scope.
+*	OUTOFSCOPE	^https://[^/]+/$
+10049	IGNORE	Non-Storable / Storable Content: informational, describes caching semantics, not a defect. The shell and API are no-store on purpose; hashed _next/static assets are immutable on purpose.
+10109	IGNORE	Modern Web Application: informational, ZAP noting the target is a JavaScript SPA, which is why the scan uses the AJAX spider.
+10112	IGNORE	Session Management Response Identified: informational, ZAP recognising the App Service ARRAffinity cookie as a session token. Not a finding.
+10055	IGNORE	CSP analysis: style-src carries 'unsafe-inline' because Radix UI and React inline style attributes need it; script-src does not use unsafe-inline: the build emits per-script SHA-256 hashes (scripts/extract-csp-hashes.mjs). The rest of the policy is pinned by SecurityHeadersTests.

package/loops/templates/quality-gates/scripts/check-complexity.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/scripts/check-complexity.mjs. Update with `workflows update --force`; consumer edits may be overwritten.
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { CC_MAX, CRAP_MAX, buildBaseline, evaluate, pruneBaseline } from './lib/complexity-gate.mjs';
+import { apiMethods, scoreMethods, webMethods } from './lib/engineering-excellence.mjs';
+
+const DEFAULT_BASELINE = fileURLToPath(new URL('./complexity-baseline.json', import.meta.url));
+const REPO_ROOT = fileURLToPath(new URL('..', import.meta.url));
+
+const args = process.argv.slice(2);
+const opt = (name) => {
+  const i = args.indexOf(`--${name}`);
+  return i === -1 ? undefined : args[i + 1];
+};
+const flag = (name) => args.includes(`--${name}`);
+
+const api = opt('api');
+const webFinal = opt('web-final');
+const eslint = opt('eslint');
+if (!api || !webFinal || !eslint) {
+  console.error('usage: node scripts/check-complexity.mjs --api <Cobertura.xml> --web-final <coverage-final.json> --eslint <eslint.json> [--baseline <file>] [--prune | --write-baseline]');
+  process.exit(2);
+}
+const baselineFile = opt('baseline') ?? DEFAULT_BASELINE;
+
+const methods = scoreMethods([
+  ...apiMethods(readFileSync(api, 'utf8')),
+  ...webMethods(JSON.parse(readFileSync(eslint, 'utf8')), JSON.parse(readFileSync(webFinal, 'utf8'))),
+]);
+
+const writeJson = (file, obj) => writeFileSync(file, `${JSON.stringify(obj, null, 2)}\n`);
+
+if (flag('write-baseline')) {
+  const b = buildBaseline(methods);
+  writeJson(baselineFile, b);
+  console.log(`· wrote ${Object.keys(b).length} baseline entries to ${baselineFile}`);
+  process.exit(0);
+}
+
+const baseline = existsSync(baselineFile) ? JSON.parse(readFileSync(baselineFile, 'utf8')) : {};
+
+if (flag('prune')) {
+  const pruned = pruneBaseline(baseline, methods);
+  writeJson(baselineFile, pruned);
+  console.log(`· baseline ${Object.keys(baseline).length} -> ${Object.keys(pruned).length} entries`);
+  process.exit(0);
+}
+
+const sourceCache = new Map();
+const readSource = (file) => {
+  if (!sourceCache.has(file)) {
+    const path = `${REPO_ROOT}${file}`;
+    sourceCache.set(file, existsSync(path) ? readFileSync(path, 'utf8').split('\n') : null);
+  }
+  return sourceCache.get(file);
+};
+
+const { violations, justified, baselined, fixed } = evaluate(methods, baseline, readSource);
+const pct = (r) => `${(r * 100).toFixed(0)}%`;
+const WHY = {
+  new: 'not in the baseline',
+  'cc-increased': 'complexity rose above its baseline',
+  'crap-increased': 'CRAP rose above its baseline (coverage dropped or complexity rose)',
+};
+
+console.log(`### Complexity gate (CC ≤ ${CC_MAX}, CRAP ≤ ${CRAP_MAX})`);
+console.log('');
+console.log(`${methods.length} methods · ${baselined} baselined backlog · ${justified.length} justified · ${violations.length} violations`);
+if (justified.length) {
+  console.log('', 'Justified (`complexity-justified:`):', '');
+  for (const j of justified) console.log(`- \`${j.file}:${j.line}\` ${j.method} — CC ${j.cc}, CRAP ${j.crap} — ${j.reason} (#${j.issue})`);
+}
+if (fixed.length) {
+  console.log('', `${fixed.length} baseline entries no longer violate — run \`node scripts/check-complexity.mjs ... --prune\` to ratchet the baseline down.`);
+}
+if (violations.length) {
+  console.log('', 'Violations — simplify the method, or test it until CRAP ≤ 30:', '');
+  for (const v of violations.sort((a, b) => b.crap - a.crap)) {
+    const base = v.baseline ? ` (baseline CC ${v.baseline.cc}, CRAP ${v.baseline.crap})` : '';
+    console.log(`- ✗ \`${v.file}:${v.line}\` ${v.method} — CC ${v.cc}, coverage ${pct(v.coverage)}, CRAP ${v.crap}: ${WHY[v.why]}${base}`);
+  }
+  process.exit(1);
+}
+console.log('', '✓ no method above the thresholds outside the baseline');

package/loops/templates/quality-gates/scripts/check-coverage.mjs

@@ -0,0 +1,89 @@
+// Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/scripts/check-coverage.mjs. Update with `workflows update --force`; consumer edits may be overwritten.
+// Enforces per-assembly line-coverage floors from a Cobertura XML report, and the web floor from
+// the vitest v8 report. Shape vendored from PlainConceptsPlatform/Atlas scripts/check-coverage.mjs.
+//
+// Why a floor map (not one global number): coverage is only honest where the test run actually
+// exercises the assembly. The CI report this runs against is the MERGED unit + acceptance +
+// integration coverage (the Application assembly is mostly exercised by the SQL-backed integration suite).
+//
+// The web floor gates the v8 Cobertura report from `vitest run --coverage`. It reads the report's
+// root line-rate: the web suite is one run, so there is nothing to merge.
+//
+// The floors are the app's, in quality.config.json (`coverage.api`, `coverage.reportOnly`,
+// `coverage.web`). They sit just under the measured baseline and only ever ratchet up; never
+// lower one to go green. The rule is in Foundations, ai/ENGINEERING.md, "Thresholds and ratchets".
+//
+// Usage: node scripts/check-coverage.mjs <coverage.cobertura.xml>
+//        node scripts/check-coverage.mjs --web <cobertura-coverage.xml>
+
+import { readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { coberturaRoot, packageRates } from './lib/engineering-excellence.mjs';
+import { loadQualityConfig } from './lib/quality-config.mjs';
+
+const pct = (r) => `${(r * 100).toFixed(2)}%`;
+
+function checkApi(file, { api: floors, reportOnly }) {
+  const rates = packageRates(readFileSync(file, 'utf8'));
+  let failed = false;
+  if (Object.keys(floors).length === 0) {
+    console.error('✗ quality.config.json sets no coverage.api floors: nothing would be gated');
+    return true;
+  }
+  for (const [pkg, floor] of Object.entries(floors)) {
+    const rate = rates[pkg];
+    if (rate === undefined) {
+      console.error(`✗ ${pkg}: no coverage data in ${file} (assembly not measured)`);
+      failed = true;
+      continue;
+    }
+    if (rate < floor) {
+      console.error(`✗ ${pkg}: ${pct(rate)} < floor ${pct(floor)}`);
+      failed = true;
+    } else {
+      console.log(`✓ ${pkg}: ${pct(rate)} (floor ${pct(floor)})`);
+    }
+  }
+  for (const pkg of reportOnly) {
+    if (rates[pkg] !== undefined) {
+      console.log(`· ${pkg}: ${pct(rates[pkg])} (report-only — not gated yet)`);
+    }
+  }
+  return failed;
+}
+
+function checkWeb(file, { web: floor }) {
+  if (floor === null) {
+    console.error('✗ web: quality.config.json sets no coverage.web floor');
+    return true;
+  }
+  const { lineRate } = coberturaRoot(readFileSync(file, 'utf8'));
+  if (Number.isNaN(lineRate)) {
+    console.error(`✗ web: no line-rate in ${file}`);
+    return true;
+  }
+  if (lineRate < floor) {
+    console.error(`✗ web: ${pct(lineRate)} < floor ${pct(floor)}`);
+    return true;
+  }
+  console.log(`✓ web: ${pct(lineRate)} (floor ${pct(floor)})`);
+  return false;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const args = process.argv.slice(2);
+  const web = args[0] === '--web';
+  const file = web ? args[1] : args[0];
+  if (!file) {
+    console.error('usage: node scripts/check-coverage.mjs [--web] <coverage.cobertura.xml>');
+    process.exit(2);
+  }
+  let coverage;
+  try {
+    ({ coverage } = loadQualityConfig());
+  } catch (err) {
+    console.error(`✗ ${err.message}`);
+    process.exit(2);
+  }
+  process.exit((web ? checkWeb(file, coverage) : checkApi(file, coverage)) ? 1 : 0);
+}

package/loops/templates/quality-gates/scripts/check-duplication.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/scripts/check-duplication.mjs. Update with `workflows update --force`; consumer edits may be overwritten.
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { buildBaseline, evaluate, pruneBaseline } from './lib/duplication-gate.mjs';
+import { duplicatedLinesByFile, lineCount, repoPath } from './lib/engineering-excellence.mjs';
+
+const args = process.argv.slice(2);
+const opt = (name) => {
+  const i = args.indexOf(`--${name}`);
+  return i === -1 ? undefined : args[i + 1];
+};
+const flag = (name) => args.includes(`--${name}`);
+
+const report = opt('report') ?? 'jscpd-report/jscpd-report.json';
+const baselineFile = opt('baseline') ?? fileURLToPath(new URL('./duplication-baseline.json', import.meta.url));
+if (!existsSync(report)) {
+  console.error(`✗ ${report} not found — run \`npx jscpd -c .jscpd.json\` first`);
+  process.exit(2);
+}
+
+const jscpd = JSON.parse(readFileSync(report, 'utf8'));
+const REPO_ROOT = fileURLToPath(new URL('..', import.meta.url));
+const lengthOf = (file) => (existsSync(`${REPO_ROOT}${file}`) ? lineCount(readFileSync(`${REPO_ROOT}${file}`, 'utf8')) : Infinity);
+const duplicated = duplicatedLinesByFile(jscpd, lengthOf);
+const clonesOf = (file) =>
+  (jscpd.duplicates ?? [])
+    .map((d) => [d.firstFile, d.secondFile].map((f) => ({ file: repoPath(f.name), start: f.start, end: f.end })))
+    .filter((pair) => pair.some((f) => f.file === file))
+    .map((pair) => pair.map((f) => `${f.file}:${f.start}-${f.end}`).join(' ↔ '));
+const writeJson = (file, obj) => writeFileSync(file, `${JSON.stringify(obj, null, 2)}\n`);
+const total = (b) => Object.values(b).reduce((n, v) => n + v, 0);
+
+if (flag('write-baseline')) {
+  const b = buildBaseline(duplicated);
+  writeJson(baselineFile, b);
+  console.log(`· wrote ${Object.keys(b).length} files (${total(b)} duplicated lines) to ${baselineFile}`);
+  process.exit(0);
+}
+
+const baseline = existsSync(baselineFile) ? JSON.parse(readFileSync(baselineFile, 'utf8')) : {};
+
+if (flag('prune')) {
+  const pruned = pruneBaseline(baseline, duplicated);
+  writeJson(baselineFile, pruned);
+  console.log(`· baseline ${Object.keys(baseline).length} -> ${Object.keys(pruned).length} files, ${total(baseline)} -> ${total(pruned)} lines`);
+  process.exit(0);
+}
+
+const { violations, baselined, fixed } = evaluate(duplicated, baseline);
+console.log('### Duplication gate (jscpd, no new clones)');
+console.log('');
+console.log(`${Object.keys(duplicated).length} files with clones · ${baselined} within their baseline · ${violations.length} violations`);
+if (fixed.length) {
+  console.log('', `${fixed.length} baseline entries improved — run \`node scripts/check-duplication.mjs --prune\` to ratchet the baseline down.`);
+}
+if (violations.length) {
+  console.log('', 'Violations — reuse the existing code instead of copying it:', '');
+  for (const v of violations) {
+    const why = v.why === 'new' ? 'not in the baseline' : `baseline ${v.baseline}`;
+    console.log(`- ✗ \`${v.file}\` — ${v.lines} duplicated lines (${why})`);
+    for (const c of clonesOf(v.file)) console.log(`  - ${c}`);
+  }
+  process.exit(1);
+}
+console.log('', '✓ no duplicated lines above the baseline');

package/loops/templates/quality-gates/scripts/check-mutation.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/scripts/check-mutation.mjs. Update with `workflows update --force`; consumer edits may be overwritten.
+
+import { readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { mutationScores, tallyMutants } from './lib/engineering-excellence.mjs';
+import { loadQualityConfig } from './lib/quality-config.mjs';
+
+// The covered-code floor per scope is the app's: `mutation` in quality.config.json.
+
+// Mutant states and the score formula live in scripts/lib/engineering-excellence.mjs so the
+// Engineering Excellence facet reports exactly what this gate judged. `Killed`/`Timeout` are
+// detections; `CompileError`/`RuntimeError` are Stryker's problem rather than the
+// suite's, and `Ignored` was filtered deliberately, so all three are excluded.
+
+function main() {
+  const [scope, file] = process.argv.slice(2);
+  if (!scope || !file) {
+    console.error('usage: node scripts/check-mutation.mjs <scope> <mutation-report.json>');
+    process.exit(2);
+  }
+  let floors;
+  try {
+    floors = loadQualityConfig().mutation;
+  } catch (err) {
+    console.error(`✗ ${err.message}`);
+    process.exit(2);
+  }
+  if (!(scope in floors)) {
+    console.error(`✗ unknown scope '${scope}' — quality.config.json sets mutation floors for: ${Object.keys(floors).join(', ') || 'none'}`);
+    process.exit(2);
+  }
+
+  // The gate step runs with if: always(), so a Stryker run that died before writing
+  // its report lands here. Say that plainly instead of throwing an ENOENT stack.
+  let report;
+  try {
+    report = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (err) {
+    console.error(`✗ ${scope}: cannot read ${file} — ${err.message}`);
+    process.exit(1);
+  }
+  const s = mutationScores(tallyMutants(report));
+  const { survived, noCoverage } = s;
+
+  if (s.valid === 0) {
+    console.error(`✗ ${scope}: no valid mutants in ${file} — the run produced nothing to score`);
+    process.exit(1);
+  }
+
+  const pct = (r) => `${(r * 100).toFixed(2)}%`;
+  const floor = floors[scope];
+  const { coveredScore, fullScore } = s;
+
+  // Printed on every run, pass or fail: the NoCoverage population is not a
+  // deficiency to gate on, it is the backlog of logic no unit test reaches.
+  console.log(`· ${scope}: full score ${pct(fullScore)} · ${noCoverage} mutants with no unit coverage · ${survived} survived`);
+
+  if (coveredScore < floor) {
+    console.error(`✗ ${scope}: covered-code ${pct(coveredScore)} < floor ${pct(floor)}`);
+    process.exit(1);
+  }
+
+  console.log(`✓ ${scope}: covered-code ${pct(coveredScore)} (floor ${pct(floor)})`);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) main();

package/loops/templates/quality-gates/scripts/dast-wait-stable.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/scripts/dast-wait-stable.sh. Update with `workflows update --force`; consumer edits may be overwritten.
+# Wait until a deployed instance of the app is the NEW build and stays up, before (or between) DAST
+# scans. Used by .github/workflows/security-dast.yml; shape from
+# PlainConceptsPlatform/Atlas scripts/dast-wait-stable.sh.
+#
+#   dast-wait-stable.sh <host> <streak> [expected-sha]
+#
+# With an expected SHA, first poll /api/v1/health until it reports that commit (the deploy's own
+# build-identity gate). After a deploy the old process can keep answering 200 for about a minute
+# before the new one takes over, with 502s in between, and a streak of 200s from the OLD process
+# would start the scan on platform pages.
+#
+# Then require <streak> consecutive 200s on /login (the SPA shell) 10 s apart, within 6 minutes.
+# Not /: with Entra SSO on, an anonymous GET / is redirected to the sign-in (SignInRedirect).
+# Exits 0 when stable, 1 otherwise.
+set -uo pipefail
+
+host="$1"
+streak_needed="$2"
+sha="${3:-}"
+
+# wait_build <url> <sha> <attempts>: poll every 15 s until the body names the commit.
+wait_build() {
+  local url="$1" expected="$2" attempts="$3" body
+  for _ in $(seq 1 "$attempts"); do
+    body="$(curl -s --max-time 20 "$url" || true)"
+    case "$body" in *"$expected"*) return 0 ;; esac
+    sleep 15
+  done
+  return 1
+}
+
+if [ -n "$sha" ]; then
+  if ! wait_build "https://${host}/api/v1/health" "$sha" 24; then
+    echo "::error::${host} never reported build ${sha} on /api/v1/health in 6 minutes: the deploy did not land, or the old process is still serving"
+    exit 1
+  fi
+  echo "Build ${sha:0:7} is serving /api/v1/health"
+fi
+
+streak=0
+for attempt in $(seq 1 36); do
+  code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 15 "https://${host}/login" || echo 000)
+  if [ "$code" = "200" ]; then streak=$((streak + 1)); else streak=0; fi
+  if [ "$streak" -ge "$streak_needed" ]; then
+    echo "SPA shell stable (${streak_needed} consecutive 200s by attempt ${attempt})"
+    exit 0
+  fi
+  sleep 10
+done
+echo "::error::${host}/login never answered 200 ${streak_needed} times in a row in 6 minutes: the scan would read platform errors, not the app"
+exit 1