@cspeach/cli 1.1.22 → 1.1.23

package/dist/tools/cap/link-smoke.js

@@ -0,0 +1,703 @@
+// cspeach-cli/src/tools/cap/link-smoke.ts
+/**
+ * CAP phase 2 — S/4 link smoke (spec §8.2, Task 11).
+ *
+ * READ leg: the app's S/4 entity shows rows, and a DIRECT S/4 read of the same
+ * keys (through the alias's own SapConnection, independent of the link) returns
+ * the same compareFields values — proof the app is not on mocks. Mode `mock`
+ * only checks that the app serves rows and says it proves nothing live.
+ *
+ * WRITE leg (live only, optional, a SAP write): THROUGH THE SAP LINK, change one
+ * harmless field on one test record, re-read, restore it, re-read again.
+ *
+ * Safety rules held here:
+ *   - Every input is validated before any request (identifiers, key, Gateway
+ *     servicePath, testValue).
+ *   - Write gates run before anything is sent to the link, in this order: loopback
+ *     app URL (checked first of all), role exactly 'dev', the approval verified for
+ *     EXACTLY approvalObjectFor(alias, s4, key) with op 'modify', the nonce spent
+ *     once, the link running. Mode `mock` never writes and never calls SAP.
+ *   - V2 writes use MERGE, V4 writes use PATCH. If-Match is sent only when the read
+ *     returned an ETag (V2 __metadata.etag, V4 @odata.etag, or an ETag header).
+ *   - Everything after a successful test update runs inside one try: a drop at
+ *     the re-read, the restore or the final read is RED and names the alias, the
+ *     record key, the field, the test value and the original value.
+ *   - Response bodies from the app, the link or SAP are never echoed. Only status
+ *     codes and field values, each scrubbed to one line of at most 200 characters.
+ *   - Fix round 1: the approval object is canonicalization-proof (R23, see
+ *     approvalObjectFor) and the verify result must be an exact-record modify; a
+ *     test update answered with anything but 2xx or a definite refusal is outcome
+ *     unknown (re-read, restore if needed, always red); redirects are never
+ *     followed (redirect: 'manual', 3xx is red); the link must be on the same
+ *     alias; bodies are capped at 8 MB; before/restored compare raw JSON values.
+ *   - R28 (live S4H defect): S/4 can show a write late. After any update that was
+ *     not a definite refusal the tool polls for the test value, ALWAYS sends the
+ *     restore, and polls for the original. Green needs both seen; "restored" is
+ *     only said after a read made after the restore confirmed it.
+ *   - Evidence (~/.cspeach/smoke/cap-link-<runId>/evidence.json) holds no headers,
+ *     no bodies and no password.
+ */
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { registerTool } from '../index.js';
+import { resolveSafePath, assertRealPathContained } from '../_filesystem-shared.js';
+import { loadConfig } from '../../config/loader.js';
+import { verifyAndSpendApprovalId } from '../../approvals/jwt.js';
+import { canonicalApprovalObject } from '../../approvals/canonical.js';
+import { writeEvidence } from '../fiori/smoke/evidence.js';
+import { isLoopbackAppUrl } from '../fiori/smoke/draft-safety.js';
+import { findSapLink, writeLogFileFor } from '../../sap-link/registry.js';
+import { writesBlockedMessage } from '../../sap-link/policy.js';
+import { readWriteRows } from '../../sap-link/write-log.js';
+import { unreachableCode } from '../../sap/unreachable.js';
+// ── Input rules ─────────────────────────────────────────────────────────────
+const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+/** Printable ASCII; no `/`, `\`, `?`, `#` (path/query breakers), no `%` or `;` (the link refuses them in a path). */
+const KEY_RE = /^[\x20-\x7E]{1,120}$/;
+const KEY_FORBIDDEN_RE = /[/\\?#%;]/;
+const TEST_VALUE_RE = /^[\x20-\x7E]{1,60}$/;
+const SEG = '[A-Za-z0-9_]+';
+const V2_PATH_RE = new RegExp(`^/sap/opu/odata/${SEG}/${SEG}(?:;v=\\d+)?/?$`);
+const V4_PATH_RE = new RegExp(`^/sap/opu/odata4(?:/${SEG}){6}/?$`);
+/** A local CAP service path: /odata/v4/review/ — plain segments only. */
+const APP_PATH_RE = /^(?:\/[A-Za-z0-9_-]+)+\/?$/;
+const CAP_USER_RE = /^[A-Za-z0-9_.@-]{1,64}$/;
+const MAX_COMPARE_FIELDS = 20;
+const MAX_KEYS = 3;
+const TIMEOUT_MS = 30_000;
+/** R28: how often and how long to re-read after a write until it shows (S/4 commits through the update task). */
+const POLL_INTERVAL_MS = 500;
+const POLL_TIMEOUT_MS = 15_000;
+/** Largest response body read from the app, the link or SAP. */
+export const MAX_BODY_BYTES = 8 * 1024 * 1024;
+/** Answers to the test update that mean SAP refused it: nothing was changed. Any other non-2xx is outcome unknown. */
+const DEFINITE_REFUSALS = new Set([400, 403, 404, 405, 412, 428]);
+const PATH_SHAPE = 's4.servicePath must be a Gateway OData path: /sap/opu/odata/<namespace>/<SERVICE> (optionally ending ;v=<number>) ' +
+    'or /sap/opu/odata4/ followed by 6 segments. No host, query, "..", "%", "\\", "?" or "#".';
+function validKey(k) {
+    return typeof k === 'string' && KEY_RE.test(k) && !KEY_FORBIDDEN_RE.test(k);
+}
+function validGatewayPath(p) {
+    if (typeof p !== 'string' || !/^[\x20-\x7E]+$/.test(p))
+        return undefined;
+    if (p.includes('..') || /[%\\?#]/.test(p))
+        return undefined;
+    if (!V2_PATH_RE.test(p) && !V4_PATH_RE.test(p))
+        return undefined;
+    return p.replace(/\/+$/, '');
+}
+/** The first problem with the args, or undefined when they are usable. Pure: no request is made. */
+function inputProblem(args) {
+    if (!args || typeof args !== 'object')
+        return 'arguments are missing.';
+    if (args.mode !== 'live' && args.mode !== 'mock')
+        return 'mode must be live or mock.';
+    const app = args.app;
+    if (!app || typeof app !== 'object')
+        return 'app is missing.';
+    if (typeof app.url !== 'string' || !isLoopbackAppUrl(app.url)) {
+        return 'app.url must be the local CAP server (localhost, 127.x or [::1]).';
+    }
+    const u = new URL(app.url);
+    if ((u.pathname !== '/' && u.pathname !== '') || u.search || u.hash)
+        return 'app.url must be the server root, such as http://localhost:4004.';
+    if (typeof app.servicePath !== 'string' || !APP_PATH_RE.test(app.servicePath)) {
+        return 'app.servicePath must be a plain path such as /odata/v4/review/.';
+    }
+    if (typeof app.entitySet !== 'string' || !IDENT_RE.test(app.entitySet))
+        return 'app.entitySet must be a plain OData name.';
+    if (typeof app.keyField !== 'string' || !IDENT_RE.test(app.keyField))
+        return 'app.keyField must be a plain OData name.';
+    if (app.capUser !== undefined && (typeof app.capUser !== 'string' || !CAP_USER_RE.test(app.capUser))) {
+        return 'app.capUser must be a plain user name such as alice.';
+    }
+    const s4 = args.s4;
+    if (!s4 || typeof s4 !== 'object')
+        return 's4 is missing.';
+    const svc = validGatewayPath(s4.servicePath);
+    if (!svc)
+        return PATH_SHAPE;
+    if (s4.odata !== undefined && s4.odata !== 'v2' && s4.odata !== 'v4')
+        return 's4.odata must be v2 or v4.';
+    const isV4Path = svc.startsWith('/sap/opu/odata4/');
+    if (isV4Path !== (s4.odata === 'v4')) {
+        return isV4Path ? 'This is an OData V4 path. Set s4.odata to v4.' : 'This is an OData V2 path. Leave s4.odata unset or set it to v2.';
+    }
+    if (typeof s4.entitySet !== 'string' || !IDENT_RE.test(s4.entitySet))
+        return 's4.entitySet must be a plain OData name.';
+    if (typeof s4.keyField !== 'string' || !IDENT_RE.test(s4.keyField))
+        return 's4.keyField must be a plain OData name.';
+    if (!Array.isArray(s4.compareFields) || s4.compareFields.length === 0 || s4.compareFields.length > MAX_COMPARE_FIELDS ||
+        !s4.compareFields.every((f) => typeof f === 'string' && IDENT_RE.test(f))) {
+        return `s4.compareFields must list 1 to ${MAX_COMPARE_FIELDS} plain OData field names.`;
+    }
+    if (args.write !== undefined) {
+        const w = args.write;
+        if (!w || typeof w !== 'object')
+            return 'write must be {key, field, testValue}.';
+        if (!validKey(w.key)) {
+            return 'write.key must be printable ASCII, at most 120 characters, with no "/", "\\", "?", "#", "%" or ";".';
+        }
+        if (typeof w.field !== 'string' || !IDENT_RE.test(w.field))
+            return 'write.field must be a plain OData field name.';
+        if (typeof w.testValue !== 'string' || !TEST_VALUE_RE.test(w.testValue)) {
+            return 'write.testValue must be 1 to 60 printable characters.';
+        }
+    }
+    if (args.approval_id !== undefined && typeof args.approval_id !== 'string')
+        return 'approval_id must be a string.';
+    if (args.projectDir !== undefined && typeof args.projectDir !== 'string')
+        return 'projectDir must be a string.';
+    return undefined;
+}
+// ── URLs ────────────────────────────────────────────────────────────────────
+/** An OData string key literal: single quotes doubled. */
+const literal = (k) => `'${k.replace(/'/g, "''")}'`;
+const svcPath = (s4) => s4.servicePath.replace(/\/+$/, '');
+/** Entity path as sent: the key literal percent-encoded (quotes, parentheses stay as they are). */
+const entityUrlPath = (s4, key) => `${svcPath(s4)}/${s4.entitySet}(${encodeURIComponent(literal(key))})`;
+/**
+ * The approval object for one record (ruling R23):
+ *   `<ALIAS>:<servicePath>/<EntitySet> record <key> [<HEX>]`
+ * HEX = upper-case hex of the UTF-8 bytes of `<ALIAS>\n<servicePath>\n<EntitySet>\n<key>`.
+ *
+ * canonicalApprovalObject (shared by every SAP write) trims, strips a leading
+ * "TR:"-style label, strips TRAILING PARENTHETICALS, collapses whitespace and
+ * upper-cases. The old form ended in `('<key>')`, so the key was stripped and one
+ * approval covered every record. This form ends in `]` (no parenthetical to strip),
+ * has spaces (never a comma list of object names), and the hex part is unchanged
+ * by upper-casing and holds alias, service, entity set and key exactly, so no fold
+ * can merge two records, two key cases, or two aliases. The readable part keeps
+ * the approval card naming the record.
+ */
+export function approvalObjectFor(alias, s4, key) {
+    const hex = Buffer.from(`${alias}\n${svcPath(s4)}\n${s4.entitySet}\n${key}`, 'utf8').toString('hex').toUpperCase();
+    return `${alias}:${svcPath(s4)}/${s4.entitySet} record ${key} [${hex}]`;
+}
+// ── Values ──────────────────────────────────────────────────────────────────
+/** A field value for a message or the evidence: one line, at most 200 characters. */
+function scrub(v) {
+    const s = v === null || v === undefined ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v);
+    // eslint-disable-next-line no-control-regex
+    const one = s.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]+/g, ' ');
+    return one.length > 200 ? `${one.slice(0, 197)}...` : one;
+}
+/** V2 `{d:{…}}` / V4 `{…}` → the record plus its ETag (body first, then the header). */
+function record(body, etagHeader) {
+    const j = JSON.parse(body);
+    if (!j || typeof j !== 'object' || Array.isArray(j))
+        throw new Error('not an OData record');
+    const d = j.d;
+    const rec = (d && typeof d === 'object' && !Array.isArray(d) ? d : j);
+    const md = rec.__metadata;
+    const fromBody = typeof md?.etag === 'string' ? md.etag : typeof rec['@odata.etag'] === 'string' ? rec['@odata.etag'] : undefined;
+    const etag = fromBody ?? (etagHeader || undefined);
+    return { rec, ...(etag ? { etag } : {}) };
+}
+const ok2xx = (s) => s >= 200 && s < 300;
+/** Raw JSON equality: number 5 and string "5" differ. scrub() is for display only. */
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/** A body over MAX_BODY_BYTES. */
+class TooLarge extends Error {
+}
+/** Read a response body as text, refusing more than MAX_BODY_BYTES (content-length first, then while streaming). */
+async function readCapped(r) {
+    const declared = Number(r.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+        try {
+            await r.body?.cancel();
+        }
+        catch { /* best effort */ }
+        throw new TooLarge();
+    }
+    if (!r.body)
+        return '';
+    const reader = r.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > MAX_BODY_BYTES) {
+            try {
+                await reader.cancel();
+            }
+            catch { /* best effort */ }
+            throw new TooLarge();
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+/** Drop a body we do not read (write answers), so the socket is freed. */
+async function discard(r) {
+    try {
+        await r.body?.cancel();
+    }
+    catch { /* best effort */ }
+}
+function evidenceRows(rows) {
+    return rows.flatMap((r) => {
+        if (!r || typeof r !== 'object')
+            return [];
+        const o = r;
+        return [{ at: o.at, method: o.method, path: o.path, status: o.status }];
+    });
+}
+// ── Handler ─────────────────────────────────────────────────────────────────
+/** Nonces of approvals that already ran one smoke (this process). verifyAndSpend also spends them. */
+const usedNonces = new Set();
+export async function capLinkSmokeHandler(args, ctx, partial = {}) {
+    const runId = randomUUID().slice(0, 8);
+    const startedAt = new Date().toISOString();
+    const deps = {
+        fetch: globalThis.fetch,
+        sapGet: async (p) => {
+            const cfg = await loadConfig();
+            const sys = cfg.sap?.[ctx.sapAlias];
+            if (!sys)
+                throw new PlainError(`No SAP system named ${ctx.sapAlias}. Live mode needs one; mock mode does not.`);
+            try {
+                const { getConnection } = await import('../../sap/connection-manager.js');
+                const conn = await getConnection(ctx.sapAlias, sys);
+                const r = await conn.get(p, 'application/json');
+                return { status: r.status, body: r.body };
+            }
+            catch (err) {
+                throw new PlainError(unreachableCode(err)
+                    ? `Can't reach ${ctx.sapAlias} (${sys.host}:${sys.port}) from this machine. Check network access to the SAP system.`
+                    : `Could not read from ${ctx.sapAlias}. Check the SAP login for this system and try again.`);
+            }
+        },
+        role: async () => (await loadConfig()).sap?.[ctx.sapAlias]?.role,
+        alias: ctx.sapAlias,
+        link: (dir) => {
+            const h = findSapLink(dir);
+            return h ? { url: h.url, alias: h.alias } : undefined;
+        },
+        verify: verifyAndSpendApprovalId,
+        evidenceDir: path.join(os.homedir(), '.cspeach', 'smoke', `cap-link-${runId}`),
+        writeLogRows: (dir, since) => readWriteRows(writeLogFileFor(dir), since),
+        pollIntervalMs: POLL_INTERVAL_MS,
+        pollTimeoutMs: POLL_TIMEOUT_MS,
+        ...partial,
+    };
+    const problem = inputProblem(args);
+    if (problem)
+        return { content: `cap_link_smoke: refused (nothing was sent) — ${problem}`, is_error: true };
+    const ev = { tool: 'cap_link_smoke', runId, mode: args.mode, startedAt };
+    const finish = (ok, extra = {}) => writeEvidence(deps.evidenceDir, { ...ev, ok, ...extra });
+    const red = (m, extra = {}) => {
+        const file = finish(false, { ...extra, error: m });
+        return { content: `cap_link_smoke: red — ${m}${file ? `\nEvidence: ${file}` : ''}`, is_error: true };
+    };
+    const timeout = () => (typeof AbortSignal?.timeout === 'function' ? { signal: AbortSignal.timeout(TIMEOUT_MS) } : {});
+    // ── READ leg: the app. ──
+    const auth = args.app.capUser ? { authorization: 'Basic ' + Buffer.from(`${args.app.capUser}:`).toString('base64') } : undefined;
+    const origin = new URL(args.app.url).origin;
+    const appPath = args.app.servicePath.endsWith('/') ? args.app.servicePath : `${args.app.servicePath}/`;
+    const appUrl = `${origin}${appPath}${args.app.entitySet}?$top=5`;
+    let rows;
+    try {
+        // redirect: 'manual' — a redirect is never followed; a 3xx is not 200, so it is red.
+        const ar = await deps.fetch(appUrl, { headers: { accept: 'application/json', ...auth }, redirect: 'manual', ...timeout() });
+        if (ar.status !== 200) {
+            await discard(ar);
+            return red(`the app answered HTTP ${ar.status} on ${args.app.entitySet}.`);
+        }
+        let j;
+        try {
+            j = JSON.parse(await readCapped(ar));
+        }
+        catch (e) {
+            if (e instanceof TooLarge)
+                return red(`the app's answer on ${args.app.entitySet} is too large (over 8 MB).`);
+            return red(`the app did not answer OData JSON on ${args.app.entitySet}.`);
+        }
+        if (!Array.isArray(j?.value))
+            return red(`the app did not answer OData JSON on ${args.app.entitySet}.`);
+        rows = j.value.filter((r) => !!r && typeof r === 'object' && !Array.isArray(r));
+    }
+    catch {
+        return red(`could not read ${args.app.entitySet} from the app at ${origin}. Is the CAP server running?`);
+    }
+    if (rows.length === 0)
+        return red(`the app returned no ${args.app.entitySet} rows.`);
+    const readEv = { rows: rows.length, mismatches: [] };
+    ev.read = readEv;
+    if (args.mode === 'mock') {
+        const file = finish(true, { note: 'mock only, not proven against S/4' });
+        return {
+            content: `cap_link_smoke: read: green (${rows.length} rows) — mock only, not proven against S/4.` +
+                `${args.write ? ' Mock mode never writes; the write args were ignored.' : ' No write was attempted.'}` +
+                `${file ? `\nEvidence: ${file}` : ''}`,
+        };
+    }
+    // ── READ leg: compare with a DIRECT S/4 read of the same keys (one GET per key, at most 3). ──
+    const v4 = args.s4.odata === 'v4';
+    for (const row of rows.slice(0, MAX_KEYS)) {
+        const raw = row[args.app.keyField];
+        const key = typeof raw === 'string' || typeof raw === 'number' ? String(raw) : '';
+        if (!validKey(key))
+            return red(`an app row has a ${args.app.keyField} that cannot be used as an S/4 key.`);
+        const directPath = v4 ? entityUrlPath(args.s4, key) : `${entityUrlPath(args.s4, key)}?$format=json`;
+        let sr;
+        try {
+            sr = await deps.sapGet(directPath);
+        }
+        catch (err) {
+            return red(err instanceof PlainError ? err.message : `could not read ${scrub(key)} directly from ${deps.alias}.`);
+        }
+        if (sr.status !== 200)
+            return red(`direct S/4 read of ${scrub(key)} answered HTTP ${sr.status}.`);
+        if (Buffer.byteLength(String(sr.body ?? ''), 'utf8') > MAX_BODY_BYTES)
+            return red(`direct S/4 read of ${scrub(key)} is too large (over 8 MB).`);
+        let rec;
+        try {
+            rec = record(sr.body).rec;
+        }
+        catch {
+            return red(`direct S/4 read of ${scrub(key)} did not answer OData JSON.`);
+        }
+        if (Object.prototype.hasOwnProperty.call(rec, args.s4.keyField) && scrub(rec[args.s4.keyField]) !== scrub(key)) {
+            readEv.mismatches.push(`${scrub(key)}: S/4 answered a record with ${args.s4.keyField} "${scrub(rec[args.s4.keyField])}"`);
+        }
+        for (const f of args.s4.compareFields) {
+            if (scrub(rec[f]) !== scrub(row[f]))
+                readEv.mismatches.push(`${scrub(key)}.${f}: app "${scrub(row[f])}" vs S/4 "${scrub(rec[f])}"`);
+        }
+    }
+    if (readEv.mismatches.length) {
+        return red(`app values differ from a direct S/4 read (is the app on mocks?): ${readEv.mismatches.join('; ')}`);
+    }
+    const lines = [`cap_link_smoke: read: green (${rows.length} rows; ${args.s4.compareFields.join(', ')} match a direct S/4 read)`];
+    if (!args.write) {
+        const file = finish(true);
+        if (file)
+            lines.push(`Evidence: ${file}`);
+        return { content: lines.join('\n') };
+    }
+    // ── WRITE leg: gates, before anything is sent to the link. ──
+    const w = args.write;
+    const role = await deps.role();
+    if (role !== 'dev')
+        return red(`${writesBlockedMessage(deps.alias, role)} Nothing was written.`);
+    const object = approvalObjectFor(deps.alias, args.s4, w.key);
+    const howToApprove = `Call request_approval with change {op:"modify", object:"${object}", type:"DATA"} and pass its id as approval_id.`;
+    if (!args.approval_id)
+        return red(`the write leg needs an approval. ${howToApprove}`);
+    const v = await deps.verify(args.approval_id, object, 'modify');
+    if (!v.ok)
+        return red(`APPROVAL_INVALID: ${v.reason}. ${howToApprove}`);
+    // R23b: the approval must be for EXACTLY this record and op, never a batch-list member.
+    if (v.matchKind === 'list_member' || v.payload.object !== canonicalApprovalObject(object) || v.payload.op !== 'modify') {
+        return red(`APPROVAL_INVALID: the approval is not a modify approval for exactly this record. ${howToApprove}`);
+    }
+    // R24: an S/4 data write needs an approval a human saw on screen; auto-approvals never count.
+    if (v.payload.auto) {
+        return red(`The write leg needs an approval you confirmed on screen, not an auto-approval. ${howToApprove}`);
+    }
+    if (usedNonces.has(v.payload.nonce))
+        return red(`that approval was already used. One approval runs one smoke. ${howToApprove}`);
+    usedNonces.add(v.payload.nonce);
+    const spentNote = 'That approval is now used; request a new approval for the next run.';
+    let dir;
+    try {
+        dir = await assertRealPathContained(resolveSafePath(ctx.cwd, args.projectDir ?? '.'), ctx.cwd);
+    }
+    catch {
+        return red(`projectDir must be an existing folder inside the workspace. ${spentNote}`);
+    }
+    const link = deps.link(dir);
+    if (!link)
+        return red(`no SAP link is running for this project. Run sap_link start first. ${spentNote}`);
+    if (link.alias !== deps.alias) {
+        return red(`The SAP link for this project is on ${link.alias}, not ${deps.alias}. Start it on ${deps.alias}. ${spentNote}`);
+    }
+    const logRows = () => {
+        try {
+            return evidenceRows(deps.writeLogRows(dir, startedAt));
+        }
+        catch {
+            return [];
+        }
+    };
+    const viaLink = `${link.url.replace(/\/+$/, '')}${entityUrlPath(args.s4, w.key)}`;
+    const verb = v4 ? 'PATCH' : 'MERGE';
+    /** HTTP status of the latest read through the link (null when no answer came). For evidence. */
+    let lastReadStatus = null;
+    const read = async () => {
+        const r = await deps.fetch(v4 ? viaLink : `${viaLink}?$format=json`, { headers: { accept: 'application/json' }, redirect: 'manual', ...timeout() });
+        lastReadStatus = r.status;
+        if (r.status !== 200) {
+            await discard(r);
+            throw new StepError(`read through the SAP link answered HTTP ${r.status}`);
+        }
+        let text;
+        try {
+            text = await readCapped(r);
+        }
+        catch (e) {
+            if (e instanceof TooLarge)
+                throw new StepError('read through the SAP link is too large (over 8 MB)');
+            throw e;
+        }
+        try {
+            return record(text, r.headers.get('etag'));
+        }
+        catch {
+            throw new StepError('read through the SAP link did not answer OData JSON');
+        }
+    };
+    const update = async (value, etag) => {
+        const r = await deps.fetch(viaLink, {
+            method: verb,
+            headers: { 'content-type': 'application/json', accept: 'application/json', ...(etag ? { 'if-match': etag } : {}) },
+            body: JSON.stringify({ [w.field]: value }),
+            redirect: 'manual',
+            ...timeout(),
+        });
+        await discard(r);
+        return r.status;
+    };
+    const statuses = { read: null, update: null, reread: null, restore: null, final: null };
+    const writeEv = (extra) => ({ key: w.key, field: w.field, testValue: w.testValue, ...extra, statuses });
+    // Before: read the record. Nothing is changed yet.
+    let b;
+    try {
+        b = await read();
+        statuses.read = 200;
+    }
+    catch (e) {
+        return red(`${e instanceof StepError ? e.message : 'could not read the record through the SAP link'}. Nothing was changed.`, { write: writeEv({}), writeLog: logRows() });
+    }
+    if (!Object.prototype.hasOwnProperty.call(b.rec, w.field)) {
+        return red(`record ${scrub(w.key)} has no field ${w.field}. Nothing was changed.`, { write: writeEv({}), writeLog: logRows() });
+    }
+    const beforeRaw = b.rec[w.field];
+    if (beforeRaw !== null && typeof beforeRaw === 'object') {
+        return red(`${w.field} is not a simple field. Pick a harmless text field. Nothing was changed.`, { write: writeEv({}), writeLog: logRows() });
+    }
+    const before = scrub(beforeRaw);
+    if (same(beforeRaw, w.testValue)) {
+        return red(`${w.field} already holds "${w.testValue}". Pick another testValue. Nothing was changed.`, { write: writeEv({ before }), writeLog: logRows() });
+    }
+    const who = `${deps.alias} record ${scrub(w.key)}`;
+    // The test update. 2xx = applied. A definite refusal = nothing changed.
+    // Anything else (no answer, 3xx, 5xx, 409, …) = outcome unknown.
+    let unknownCause = '';
+    try {
+        const s1 = await update(w.testValue, b.etag);
+        statuses.update = s1;
+        if (!ok2xx(s1)) {
+            if (DEFINITE_REFUSALS.has(s1)) {
+                return red(`the test update of ${scrub(w.key)}.${w.field} answered HTTP ${s1}. Nothing was changed.`, { write: writeEv({ before }), writeLog: logRows() });
+            }
+            unknownCause = `answered HTTP ${s1}`;
+        }
+    }
+    catch {
+        unknownCause = 'got no answer';
+    }
+    // R28 (live S4H finding): S/4 commits through the update task, so a read straight
+    // after a write can be stale. From here on:
+    //   (a) poll the re-read until the test value shows (up to the poll window);
+    //   (b) ALWAYS send the restore (beforeRaw), seen or not — unconditionally, outside any try;
+    //   (c) poll until a read shows the original value. When the test value was NEVER
+    //       seen, watch the whole window instead: if the test value lands late, send ONE
+    //       more restore and poll again (bounded);
+    //   (d) "restored" only when a read AFTER the restore confirmed it;
+    //   (e) green only when the test value was seen, every restore answered 2xx, and
+    //       the original was confirmed.
+    // Polls never throw; any failure names alias, record, field, test value and original value.
+    const timing = pollTimings(deps.pollIntervalMs, deps.pollTimeoutMs);
+    let etag = b.etag;
+    let lastCause = '';
+    const sleep = (ms) => new Promise((ok) => setTimeout(ok, ms));
+    /**
+     * Re-read until the field equals `want` (or, with `watchFor`, until that value shows),
+     * or the window ends. `fullWindow` keeps reading after `want` matched.
+     */
+    const poll = async (want, o = {}) => {
+        const deadline = Date.now() + timing.timeoutMs;
+        const res = { hit: false, reads: 0, lastStatus: null, sawTest: false };
+        for (;;) {
+            res.reads++;
+            lastReadStatus = null;
+            try {
+                const r = await read();
+                if (r.etag)
+                    etag = r.etag;
+                res.last = { raw: r.rec[w.field] };
+                res.hit = same(res.last.raw, want);
+                if (o.watchFor !== undefined && same(res.last.raw, o.watchFor)) {
+                    res.sawTest = true;
+                    res.lastStatus = lastReadStatus;
+                    return res;
+                }
+                if (res.hit && !o.fullWindow) {
+                    res.lastStatus = lastReadStatus;
+                    return res;
+                }
+            }
+            catch (e) {
+                res.hit = false;
+                lastCause = e instanceof StepError ? `The last ${e.message}.` : 'The connection to the SAP link dropped.';
+            }
+            res.lastStatus = lastReadStatus;
+            if (Date.now() >= deadline)
+                return res;
+            await sleep(timing.intervalMs);
+        }
+    };
+    const restoreCauses = [];
+    const sendRestore = async () => {
+        try {
+            const s = await update(beforeRaw, etag);
+            if (!ok2xx(s))
+                restoreCauses.push(`The restore answered HTTP ${s}.`);
+            return s;
+        }
+        catch {
+            restoreCauses.push('The restore got no answer.');
+            return null;
+        }
+    };
+    const seen = await poll(w.testValue);
+    statuses.reread = seen.lastStatus;
+    statuses.restore = await sendRestore();
+    let back;
+    let testValueSeen = seen.hit;
+    let secondRestore = false;
+    if (seen.hit) {
+        back = await poll(beforeRaw);
+    }
+    else {
+        // Never seen: the test write may still be pending. Watch the whole window.
+        back = await poll(beforeRaw, { fullWindow: true, watchFor: w.testValue });
+        if (back.sawTest) {
+            testValueSeen = true;
+            secondRestore = true;
+            statuses.restore2 = await sendRestore();
+            // Watch the whole window again; if the test value shows once more, stop: no third restore.
+            back = await poll(beforeRaw, { fullWindow: true, watchFor: w.testValue });
+        }
+    }
+    statuses.final = back.lastStatus;
+    const secs = `${Math.round(timing.timeoutMs / 100) / 10} s`;
+    const evWrite = writeEv({
+        before,
+        after: seen.last ? scrub(seen.last.raw) : null,
+        restored: back.last ? scrub(back.last.raw) : null,
+        testValueSeen,
+        originalConfirmed: back.hit,
+        secondRestore,
+        reads: { afterUpdate: seen.reads, afterRestore: back.reads },
+        ...(unknownCause ? { updateOutcome: 'unknown' } : {}),
+    });
+    const unknownPrefix = unknownCause ? `the test update of ${w.field} ${unknownCause}: outcome unknown. ` : '';
+    const restoreRefused = restoreCauses.length > 0;
+    const causes = [...restoreCauses, back.hit ? '' : lastCause].filter(Boolean).join(' ');
+    const tail = `(Test value: "${w.testValue}".)${causes ? ` ${causes}` : ''}`;
+    if (!back.hit) {
+        const state = back.last
+            ? `The last read says ${w.field} is still "${scrub(back.last.raw)}"; its original value was "${before}".`
+            : `No read succeeded after the restore. If ${w.field} is still "${w.testValue}", its original value was "${before}".`;
+        return red(`${who}: ${unknownPrefix}outcome unknown. The restore of ${w.field} to its original value "${before}" was not confirmed within ${secs}. ` +
+            `${state} Check the record in SAP and put it back if needed. ${tail}`, { write: evWrite, writeLog: logRows() });
+    }
+    if (restoreRefused) {
+        // A read shows the original, but a restore was refused or unanswered: the test
+        // write may still be pending (e.g. the update task holds the lock) and land later.
+        return red(`${who}: ${unknownPrefix}outcome unknown. A read shows ${w.field} = "${before}", but a restore did not answer 2xx, ` +
+            `so the test value "${w.testValue}" may still land. Check the record in SAP: its original value was "${before}". ${tail}`, { write: evWrite, writeLog: logRows() });
+    }
+    if (secondRestore) {
+        return red(`${who}: ${unknownPrefix}the test value "${w.testValue}" showed only after the first restore, so a second restore was sent ` +
+            `and a read confirmed ${w.field} = "${before}". Check the record in SAP: its original value was "${before}". ${tail}`, { write: evWrite, writeLog: logRows() });
+    }
+    if (!seen.hit) {
+        return red(`${who}: ${unknownPrefix}the test write could not be confirmed within ${secs}: no read showed ${w.field} = "${w.testValue}". ` +
+            `The restore to the original value "${before}" answered OK, and reads for another ${secs} showed ${w.field} = "${before}". ` +
+            `SAP may apply updates late, so check the record in SAP: its original value was "${before}".`, { write: evWrite, writeLog: logRows() });
+    }
+    if (unknownCause) {
+        return red(`${who}: ${unknownPrefix}A later read showed ${w.field} = "${w.testValue}", and after the restore a read confirmed ` +
+            `${w.field} = "${before}", its original value. ${tail} Check the record in SAP.`, { write: evWrite, writeLog: logRows() });
+    }
+    const file = finish(true, { write: evWrite, writeLog: logRows() });
+    lines.push(`write: green — ${scrub(w.key)}.${w.field} "${before}" → "${w.testValue}" → restored "${before}", confirmed by a read (through the SAP link)`);
+    if (file)
+        lines.push(`Evidence: ${file}`);
+    return { content: lines.join('\n') };
+}
+/** Poll timings, never infinite: anything not a finite number >= 0 falls back to the default. */
+export function pollTimings(intervalMs, timeoutMs) {
+    const ok = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0;
+    return { intervalMs: ok(intervalMs) ? intervalMs : POLL_INTERVAL_MS, timeoutMs: ok(timeoutMs) ? timeoutMs : POLL_TIMEOUT_MS };
+}
+/** An error whose message is already plain and safe to show. */
+class PlainError extends Error {
+}
+/** A write-leg step failure; the message holds a status code only. */
+class StepError extends Error {
+}
+registerTool({
+    name: 'cap_link_smoke',
+    description: 'S/4 link check for a local CAP app (CAP phase 2). READ: the app\'s S/4 entity shows rows and a direct S/4 read of ' +
+        'the same keys matches compareFields (mode live), or the app serves rows (mode mock — reported as "mock only, ' +
+        'not proven against S/4"). WRITE (live only, optional): through the SAP link, change one harmless field on one test ' +
+        'record, re-read, restore it, re-read — only when the alias role is exactly dev. NEEDS APPROVAL for the write: ' +
+        'request_approval with change {op:"modify", object:"<ALIAS>:<servicePath>/<EntitySet> record <key> [<HEX>]", type:"DATA"}, ' +
+        'where HEX is computed by the tool: call it once without approval_id and it answers with the exact object string. ' +
+        'One approval runs one smoke, for that one record; an auto-approval does not count. Needs the sap_link tool started ' +
+        'in this session for the project on the same SAP system.',
+    isMutating: true,
+    requiresSap: false,
+    category: 'fiori',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            projectDir: { type: 'string', description: 'CAP project root, relative to the workspace. Default ".".' },
+            mode: { type: 'string', enum: ['live', 'mock'] },
+            app: {
+                type: 'object',
+                properties: {
+                    url: { type: 'string', description: 'Local CAP server root, e.g. http://localhost:4004' },
+                    servicePath: { type: 'string', description: 'e.g. /odata/v4/review/' },
+                    entitySet: { type: 'string' },
+                    keyField: { type: 'string' },
+                    capUser: { type: 'string', description: 'CAP mock user, e.g. alice' },
+                },
+                required: ['url', 'servicePath', 'entitySet', 'keyField'],
+            },
+            s4: {
+                type: 'object',
+                properties: {
+                    servicePath: { type: 'string', description: 'Gateway path, e.g. /sap/opu/odata/sap/API_BUSINESS_PARTNER' },
+                    entitySet: { type: 'string' },
+                    keyField: { type: 'string' },
+                    compareFields: { type: 'array', items: { type: 'string' } },
+                    odata: { type: 'string', enum: ['v2', 'v4'] },
+                },
+                required: ['servicePath', 'entitySet', 'keyField', 'compareFields'],
+            },
+            write: {
+                type: 'object',
+                properties: {
+                    key: { type: 'string' },
+                    field: { type: 'string' },
+                    testValue: { type: 'string', description: 'At most 60 printable characters.' },
+                },
+                required: ['key', 'field', 'testValue'],
+            },
+            approval_id: { type: 'string' },
+        },
+        required: ['mode', 'app', 's4'],
+    },
+    handler: (args, ctx) => capLinkSmokeHandler(args, ctx),
+});