@cspeach/cli 1.1.18 → 1.1.19

package/dist/tools/fiori/metadata/references.js

@@ -0,0 +1,104 @@
+/**
+ * L1-1 — `Common.ValueListReferences`: read them out of a main `$metadata`,
+ * and resolve each (relative) reference against the service path.
+ *
+ * Why this exists: a RAP V4 service does NOT carry `Common.ValueList` inline
+ * for a `@Consumption.valueHelpDefinition`. Its main document names a separate
+ * value-help service per field, as a relative URL with matrix parameters:
+ *
+ *   ../../../../srvd_f4/sap/<vh>/0001;ps='srvd-<srvd>-0001';va='…'/$metadata
+ *
+ * and the mapping itself lives in THAT document (see audit.ts). Both functions
+ * here are pure: no network, no filesystem.
+ */
+import { parse } from '@sap-ux/edmx-parser';
+const VALUE_LIST_REFERENCES = 'com.sap.vocabularies.Common.v1.ValueListReferences';
+/**
+ * Pure: scan a main $metadata for ValueListReferences, in document order.
+ *
+ * Uses the EDMX parser, not a text match: the parser resolves whatever alias
+ * the document declares (`SAP__common.ValueListReferences` on a real system,
+ * the full namespace elsewhere) to the vocabulary namespace. The URL strings
+ * come back exactly as written — raw apostrophes and all — which is also the
+ * key shape of the captured refs maps.
+ */
+export function readValueListReferences(mainXml) {
+    const raw = parse(mainXml);
+    const out = [];
+    for (const list of Object.values(raw.schema.annotations)) {
+        for (const target of list) {
+            for (const ann of target.annotations) {
+                if (ann.term !== VALUE_LIST_REFERENCES)
+                    continue;
+                const urls = stringsOf(ann.collection);
+                if (urls.length === 0)
+                    continue;
+                const property = target.target.slice(target.target.lastIndexOf('/') + 1);
+                const existing = out.find((r) => r.property === property);
+                if (existing) {
+                    for (const u of urls)
+                        if (!existing.urls.includes(u))
+                            existing.urls.push(u);
+                }
+                else {
+                    out.push({ property, urls });
+                }
+            }
+        }
+    }
+    return out;
+}
+function stringsOf(collection) {
+    if (!Array.isArray(collection))
+        return [];
+    const out = [];
+    for (const item of collection) {
+        if (typeof item === 'string')
+            out.push(item);
+        else if (item && typeof item === 'object' && typeof item.String === 'string') {
+            out.push(item.String);
+        }
+    }
+    return out;
+}
+/**
+ * Pure: resolve a relative reference URL against the service path.
+ *
+ *   '/sap/opu/odata4/sap/zx/srvd/sap/zc_x/0001/$metadata' + '../../../../srvd_f4/sap/i_vh/0001/$metadata'
+ *   → '/sap/opu/odata4/sap/zx/srvd_f4/sap/i_vh/0001/$metadata'
+ *
+ * The base is the DIRECTORY of the service path: everything up to its last
+ * `/`, so `…/0001/$metadata` and `…/0001/` resolve alike. Segments are
+ * processed by hand rather than through `URL`, so the matrix parameters and
+ * their raw apostrophes come out byte for byte as SAP wrote them — no
+ * percent-encoding, no normalisation. An absolute reference (leading `/`) is
+ * returned untouched.
+ */
+export function resolveReferenceUrl(servicePath, referenceUrl) {
+    if (referenceUrl.startsWith('/'))
+        return referenceUrl;
+    const pathOnly = servicePath.split('?')[0];
+    const baseDir = pathOnly.slice(0, pathOnly.lastIndexOf('/') + 1);
+    const segments = baseDir.split('/').filter((s, i, all) => !(s === '' && i === all.length - 1));
+    // segments[0] is '' (leading slash); keep it as the root marker.
+    const refSegments = referenceUrl.split('/');
+    for (let i = 0; i < refSegments.length; i++) {
+        const seg = refSegments[i];
+        const last = i === refSegments.length - 1;
+        if (seg === '..') {
+            if (segments.length > 1)
+                segments.pop();
+            if (last)
+                segments.push('');
+        }
+        else if (seg === '.') {
+            if (last)
+                segments.push('');
+        }
+        else {
+            segments.push(seg);
+        }
+    }
+    const joined = segments.join('/');
+    return joined.startsWith('/') ? joined : `/${joined}`;
+}

package/dist/tools/fiori/metadata/types.js

@@ -0,0 +1,8 @@
+/**
+ * L1-1 — the contract `fiori_metadata_audit` returns: machine truth about ONE
+ * entity set of a published V4 service, read from its `$metadata` and from
+ * every value-help document it references. Everything downstream (the build
+ * phases, the smoke checks, lane 2) reads this instead of trusting a
+ * model-supplied string.
+ */
+export {};

package/dist/tools/fiori/preview/app-guard.js

@@ -0,0 +1,215 @@
+// cspeach-cli/src/tools/fiori/preview/app-guard.ts
+/**
+ * L1-6 fix round 2 — the checks that run BEFORE the SAP password is read from
+ * the keychain. Each one closes a way for the app directory (which the model
+ * can write) to receive, or to redirect, the login that `fiori_preview` hands
+ * to `npm run start`.
+ *
+ *  - R1-2: npm runs `prestart` / `poststart` around `start`, and a project
+ *    `.npmrc` can swap the script shell or preload code with `node-options`.
+ *    `--ignore-scripts` is passed as well; these refusals make the reason
+ *    visible instead of silently skipping a hook the app may rely on.
+ *  - R1-4: the preview proxy presents the login to whatever `backend[].url`
+ *    the app's ui5.yaml names. A copied app folder previewed with another
+ *    alias would send that alias's password to the first system's host — no
+ *    attacker needed. Every backend url must name the alias's host and port.
+ *
+ * No YAML library: the CLI ships none as a direct dependency and the ruling
+ * forbids adding one. The reader below only extracts `url:` values under a
+ * `backend:` key and FAILS CLOSED on anything it cannot read with certainty
+ * (flow style, anchors/aliases, block scalars, escapes).
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+const WHY = "the SAP login would be in that script's environment";
+/** R1-2 — npm lifecycle hooks and project .npmrc settings that run code. */
+export async function lifecycleProblem(appDir, scripts) {
+    for (const hook of ['prestart', 'poststart']) {
+        if (scripts && Object.prototype.hasOwnProperty.call(scripts, hook)) {
+            return (`refusing to start: package.json has a "${hook}" script (${JSON.stringify(scripts[hook])}), and npm ` +
+                `runs it around "start" — ${WHY}. Remove it (the preview only needs "start").`);
+        }
+    }
+    let npmrc;
+    try {
+        npmrc = await fs.readFile(path.join(appDir, '.npmrc'), 'utf8');
+    }
+    catch {
+        return null; // no project .npmrc — nothing to check
+    }
+    const m = /^\s*(script[-_]shell|node[-_]options)\s*=.*$/im.exec(npmrc);
+    if (m) {
+        return (`refusing to start: ${path.join(appDir, '.npmrc')} sets ${m[1]} (${JSON.stringify(m[0].trim())}), which ` +
+            `makes npm run other code for "start" — ${WHY}. Remove that line from the app's .npmrc.`);
+    }
+    return null;
+}
+/** The ui5 config files the start script will read: every --config/-c value, else ui5.yaml. */
+export function configFilesFor(startScript) {
+    const tokens = startScript.trim().split(/\s+/).map((t) => t.replace(/^["']|["']$/g, ''));
+    const out = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (t === '--config' || t === '-c') {
+            out.push(tokens[i + 1] ?? '');
+            i++;
+        }
+        else if (t.startsWith('--config=')) {
+            out.push(t.slice('--config='.length));
+        }
+    }
+    return out.length > 0 ? out : ['ui5.yaml'];
+}
+function inside(root, candidate) {
+    const rel = path.relative(root, candidate);
+    return rel.length > 0 && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+async function realOr(p) {
+    try {
+        return await fs.realpath(p);
+    }
+    catch {
+        return p;
+    }
+}
+/** Parse one YAML plain / single- / double-quoted scalar, or null when unsure. */
+function scalar(raw) {
+    const v = raw.trim();
+    if (v.startsWith('"')) {
+        const end = v.indexOf('"', 1);
+        if (end < 0)
+            return null;
+        const body = v.slice(1, end);
+        return body.includes('\\') ? null : body; // escapes could spell another host
+    }
+    if (v.startsWith("'")) {
+        const end = v.indexOf("'", 1);
+        if (end < 0)
+            return null;
+        return v.slice(1, end);
+    }
+    const plain = v.replace(/\s+#.*$/, '').trim();
+    if (plain.length === 0 || /^[|>*&!{[\]]/.test(plain))
+        return null;
+    return plain;
+}
+/** Every `url:` under a `backend:` key, block style only. */
+export function backendUrlsFromUi5Yaml(text) {
+    const urls = [];
+    let keyCol = null;
+    for (const raw of text.split(/\r?\n/)) {
+        if (/^\s*(#.*)?$/.test(raw))
+            continue;
+        const indent = raw.length - raw.trimStart().length;
+        const body = raw.slice(indent);
+        if (keyCol !== null) {
+            const inBlock = indent > keyCol || (indent === keyCol && body.startsWith('-'));
+            if (!inBlock)
+                keyCol = null;
+        }
+        const key = /^(-\s+)?backend\s*:(.*)$/.exec(body);
+        if (key) {
+            const rest = key[2].replace(/\s+#.*$/, '').trim();
+            if (rest.length > 0)
+                return { error: `the backend list is written inline (${JSON.stringify(body.trim())})` };
+            keyCol = raw.indexOf('backend');
+            continue;
+        }
+        if (keyCol !== null) {
+            if (/(^|\s)<<\s*:|:\s*[*&]|^-\s+[*&]/.test(body)) {
+                return { error: `the backend list uses a YAML anchor or alias (${JSON.stringify(body.trim())})` };
+            }
+            const u = /^(-\s+)?url\s*:(.*)$/.exec(body);
+            if (u) {
+                const value = scalar(u[2]);
+                if (value === null)
+                    return { error: `a backend url is not a plain value (${JSON.stringify(body.trim())})` };
+                urls.push(value);
+            }
+        }
+    }
+    return { urls };
+}
+function hostPort(u) {
+    const port = u.port !== '' ? u.port : u.protocol === 'https:' ? '443' : u.protocol === 'http:' ? '80' : null;
+    return port === null ? null : `${u.hostname.toLowerCase()}:${port}`;
+}
+function aliasHostPort(host, port) {
+    const bare = host.trim().replace(/^[a-z][a-z0-9+.-]*:\/\//i, '').replace(/[/?#].*$/, '').replace(/:\d+$/, '');
+    return `${bare.toLowerCase()}:${port}`;
+}
+/**
+ * THE decision (round 2b, owner ruling 2026-09-21) — the one source of truth
+ * for both the approval hook and the start path:
+ *   - no backend url in any ui5 config the start script reads → 'none': the
+ *     preview starts WITHOUT the SAP login (no keychain read, no prompt);
+ *   - backend urls present and all on the alias's host:port → 'login';
+ *   - a config outside appDir, an unreadable or uncertain one, a mismatch,
+ *     a non-http(s) url → refuse (fail closed).
+ * `system` may be omitted by a caller that only needs to know whether a login
+ * WOULD be passed (the approval hook): urls present then means 'login'
+ * without the host comparison — the start path always passes `system`.
+ */
+export async function loginNeed(appDir, startScript, alias, system) {
+    const expected = system ? aliasHostPort(system.host, system.port) : null;
+    const realApp = await realOr(appDir);
+    let total = 0;
+    for (const name of configFilesFor(startScript)) {
+        const file = path.resolve(appDir, name);
+        if (name.length === 0 || !inside(appDir, file) || !inside(realApp, await realOr(file))) {
+            return {
+                refuse: `refusing to start: the start script reads ui5 config ${JSON.stringify(name)}, which is not a file ` +
+                    `inside the app directory — the SAP login for alias ${alias} would go wherever that file says.`,
+            };
+        }
+        let text;
+        try {
+            text = await fs.readFile(file, 'utf8');
+        }
+        catch {
+            return {
+                refuse: `refusing to start: cannot read ${file} — without it there is no way to confirm which host the ` +
+                    `preview proxy would send the SAP login for alias ${alias} to.`,
+            };
+        }
+        const read = backendUrlsFromUi5Yaml(text);
+        if ('error' in read) {
+            return {
+                refuse: `refusing to start: ${file} could not be read with certainty — ${read.error}. Write the backend ` +
+                    `entries in plain block style ("- path: /sap" / "url: https://host:port").`,
+            };
+        }
+        total += read.urls.length;
+        for (const raw of read.urls) {
+            let actual = null;
+            try {
+                actual = hostPort(new URL(raw));
+            }
+            catch {
+                actual = null;
+            }
+            if (actual === null) {
+                return { refuse: `refusing to start: backend url ${JSON.stringify(raw)} in ${file} is not an http(s) URL.` };
+            }
+            if (expected !== null && actual !== expected) {
+                return {
+                    refuse: `refusing to start: this app was scaffolded for ${actual}; alias ${alias} points at ${expected}. ` +
+                        `The preview proxy would send the SAP login for ${alias} to ${actual} (${file}). Preview it with ` +
+                        'the alias for that system, or re-scaffold the app for this one.',
+                };
+            }
+        }
+    }
+    return total === 0 ? { need: 'none' } : { need: 'login' };
+}
+/** The app's `scripts.start`, or null when package.json or the script is missing/unreadable. */
+export async function readStartScript(appDir) {
+    try {
+        const pkg = JSON.parse(await fs.readFile(path.join(appDir, 'package.json'), 'utf8'));
+        const v = pkg.scripts?.start;
+        return typeof v === 'string' ? v : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/tools/fiori/preview/env.js

@@ -0,0 +1,193 @@
+// cspeach-cli/src/tools/fiori/preview/env.ts
+/**
+ * L1-6 — the preview child's ENVIRONMENT CONTRACT.
+ *
+ * WHY THIS IS NOT buildSafeEnv()
+ * ------------------------------
+ * `buildSafeEnv()` (`../../_command-shared.ts`) whitelists ENV_PASSTHROUGH and
+ * DROPS everything else — including the two things a Fiori preview needs:
+ *   - NODE_EXTRA_CA_CERTS, so the proxy's Node process trusts the SAP box's CA
+ *     while certificate verification stays ON;
+ *   - FIORI_TOOLS_USER / FIORI_TOOLS_PASSWORD, which `fiori run`'s proxy
+ *     answers the backend's basic-auth challenge with.
+ * Loosening ENV_PASSTHROUGH would loosen it for shell_exec and background_run
+ * too (no-regression), so the preview builds its OWN environment instead:
+ * the SAME passthrough set plus EXACTLY three keys.
+ *
+ * WHAT NEVER HAPPENS HERE
+ * -----------------------
+ *  - No file is written. The credentials and the CA path travel only in the
+ *    child's process environment — never `.env`, never `ui5.yaml`, never a
+ *    temp file (constraints.md: "No credential reaches a file").
+ *  - Certificate checking is NEVER turned off. There is no code path that sets
+ *    NODE_TLS_REJECT_UNAUTHORIZED, and `insecure` mode is REPORTED (loudly),
+ *    not implemented. An alias in insecure mode still gets a preview — its
+ *    ui5.yaml proxy posture is the alias owner's business — but the tool says
+ *    so in its result and points at `sap.<alias>.ca_cert_path`.
+ *  - The parent's own NODE_EXTRA_CA_CERTS is never inherited. A stale value
+ *    pointing at a cert for a different system would silently change which
+ *    roots the child trusts, so the key is set from the alias config or not at
+ *    all.
+ */
+import { inspect } from 'node:util';
+import { ENV_PASSTHROUGH } from '../../_command-shared.js';
+/** Lower-cased copy of the shared allowlist, for the Windows lookup. */
+const ENV_PASSTHROUGH_LOWER = new Set([...ENV_PASSTHROUGH].map((n) => n.toLowerCase()));
+function isPassthrough(name) {
+    if (ENV_PASSTHROUGH.has(name))
+        return true;
+    return process.platform === 'win32' && ENV_PASSTHROUGH_LOWER.has(name.toLowerCase());
+}
+/**
+ * Pure. Builds the child environment: the shell passthrough set PLUS
+ * NODE_EXTRA_CA_CERTS, FIORI_TOOLS_USER, FIORI_TOOLS_PASSWORD. Nothing else
+ * from the parent leaks; nothing is written to disk.
+ */
+export function buildPreviewEnv(input) {
+    const env = {};
+    // 1. The same passthrough set the other spawning tools use — and ONLY that.
+    //    CSPEACH_*, ANTHROPIC_*, SAP_*, *_TOKEN and every other parent variable
+    //    are dropped because they are not on the list.
+    //
+    //    On Windows the match is case-INSENSITIVE (F-12): environment names there
+    //    are case-insensitive, and the real parent process spells them `Path` and
+    //    `ComSpec` under PowerShell but `PATH` and `COMSPEC` under Git Bash — so a
+    //    case-sensitive match silently gave the child a different environment
+    //    depending on which shell started the CLI. The shared ENV_PASSTHROUGH set
+    //    is NOT modified; only this lookup is relaxed.
+    for (const k of Object.keys(input.baseEnv)) {
+        if (isPassthrough(k))
+            env[k] = input.baseEnv[k];
+    }
+    // 2. The CA. Set ONLY from the alias config, never inherited. Verification
+    //    stays on in every branch.
+    if (input.tls.mode === 'ca-trusted' && input.tls.caCertPath) {
+        env.NODE_EXTRA_CA_CERTS = input.tls.caCertPath;
+    }
+    // 3. The credentials, by environment only.
+    //    Round 2b: an app whose ui5 config names no backend url gets NEITHER.
+    if (input.password !== undefined) {
+        env.FIORI_TOOLS_USER = input.username;
+        env.FIORI_TOOLS_PASSWORD = input.password;
+    }
+    const insecureFallback = input.tls.mode === 'insecure';
+    return { env, insecureFallback, tlsNote: tlsNoteFor(input.tls) };
+}
+/**
+ * The one-line TLS posture, shared by `buildPreviewEnv` and the reuse path in
+ * `start.ts` (it needs the note without building an environment). One copy —
+ * the two used to be the same 13 lines twice (F-13).
+ */
+export function tlsNoteFor(tls) {
+    switch (tls.mode) {
+        case 'ca-trusted':
+            return `CA trusted: ${tls.caCertPath} (certificate verification ON)`;
+        case 'insecure':
+            return ('certificate verification is OFF for this alias (insecure_skip_tls_verify) — ' +
+                'set sap.<alias>.ca_cert_path to a PEM root CA instead');
+        default:
+            return 'certificate verification ON (system trust store; no extra CA configured)';
+    }
+}
+export const REDACTED = '***';
+/**
+ * Literal replacement is skipped for a secret this short. Replacing a one- or
+ * two-character password shreds the output into unreadable `***`-confetti
+ * (`npm ERR! *** f***t***l`), and the shredding pattern itself tells a reader
+ * exactly how long the password is. The generic header / env-dump / userinfo
+ * patterns below still apply to short secrets — they are what actually catch
+ * the dangerous shapes.
+ */
+export const MIN_LITERAL_SECRET_LENGTH = 4;
+/**
+ * Every ENCODING of the credential that a crashing HTTP client, an env dump or
+ * a JSON error body can print. Review F-2 measured five of these leaking.
+ * Built as LITERALS and removed with split/join — never a RegExp compiled from
+ * the secret, which would have to be escaped correctly for every input and
+ * whose replacement string could re-inject `$&`.
+ */
+function literalForms(password, username) {
+    if (password.length < MIN_LITERAL_SECRET_LENGTH)
+        return [];
+    const forms = new Set();
+    const add = (s) => { if (s && s.length > 0)
+        forms.add(s); };
+    add(password);
+    // `Authorization: Basic base64(user:password)` — what an uncaught request
+    // error prints from `request._header` / `config.headers`. This leaks for
+    // EVERY password, not just exotic ones.
+    // R1-7: per base64 form also the unpadded one, the base64url one and the
+    // latin1 one (a client that encodes the header as latin1, not utf8).
+    const addBase64 = (raw) => {
+        for (const enc of ['utf8', 'latin1']) {
+            const buf = Buffer.from(raw, enc);
+            const std = buf.toString('base64');
+            add(std);
+            add(std.replace(/=+$/, ''));
+            add(buf.toString('base64url'));
+        }
+    };
+    if (username)
+        addBase64(`${username}:${password}`);
+    addBase64(password);
+    // `https://user:pass@host` in a proxy error, and query-string echoes — plus
+    // the form-encoded `+` for space and the lower-case-hex spellings (R1-7).
+    const uri = encodeURIComponent(password);
+    const lowerHex = (x) => x.replace(/%[0-9A-F]{2}/g, (m) => m.toLowerCase());
+    for (const f of [uri, uri.replace(/%20/g, '+')]) {
+        add(f);
+        add(lowerHex(f));
+    }
+    // A string printed inside quotes of the same kind: `\'` and `\"` (R1-7).
+    add(password.replace(/'/g, "\\'"));
+    add(password.replace(/"/g, '\\"'));
+    // A JSON error body: `{"FIORI_TOOLS_PASSWORD":"Pa\"ss\r"}`.
+    add(JSON.stringify(password).slice(1, -1));
+    // `util.inspect` of an options object: quotes chosen at runtime, so strip
+    // whatever quote characters it picked rather than assuming one.
+    const inspected = inspect(password);
+    if (inspected.length >= 2)
+        add(inspected.slice(1, -1));
+    // Longest first: a shorter form that is a substring of a longer one must not
+    // break the longer match up before it is replaced.
+    return [...forms].sort((a, b) => b.length - a.length);
+}
+/**
+ * Shapes that are secrets whatever their value is. These run for EVERY call,
+ * including when the password is unknown or too short to replace literally.
+ */
+const GENERIC_PATTERNS = [
+    // Authorization: Basic <base64> / Bearer <token>, header or log line.
+    [/\b(Basic|Bearer)\s+[A-Za-z0-9+/=._~-]{8,}/gi, `$1 ${REDACTED}`],
+    // Any authorization / proxy-authorization header value, quoted or not.
+    [/(authorization["']?\s*[:=]\s*)(["']?)[^"'\r\n]+/gi, `$1$2${REDACTED}`],
+    // FIORI_TOOLS_PASSWORD in KEY=value, JSON, or quoted-with-spaces shape.
+    // R1-7: quoted values may contain escaped quotes; unquoted ones may contain
+    // spaces (up to the end of the line, a comma or a closing brace).
+    [/(FIORI_TOOLS_PASSWORD["']?\s*[:=]\s*)("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|[^\r\n,}]+)/gi, `$1${REDACTED}`],
+    // URL userinfo: https://user:pass@host.
+    [/(\/\/[^/\s:@]+:)[^@\s/]+@/g, `$1${REDACTED}@`],
+];
+/**
+ * Redact credentials from any child output we are about to SURFACE (a stderr
+ * tail in an error, a log line, a tool result). The child may print its own
+ * environment, its request headers or a JSON error body on a crash — and the
+ * most likely crash is exactly the one this tool exists to surface, an
+ * unverifiable certificate on first boot.
+ *
+ * Two passes: every literal ENCODING of the credential (§literalForms), then
+ * the generic shapes that are secrets regardless of value (§GENERIC_PATTERNS).
+ *
+ * `username` is needed to compute `base64(user:password)` — without it the
+ * Basic-auth form can only be caught by the generic pattern.
+ */
+export function scrubSecrets(text, password, username) {
+    let out = text;
+    if (password && password.length > 0) {
+        for (const form of literalForms(password, username))
+            out = out.split(form).join(REDACTED);
+    }
+    for (const [pattern, replacement] of GENERIC_PATTERNS)
+        out = out.replace(pattern, replacement);
+    return out;
+}

package/dist/tools/fiori/preview/readiness.js

@@ -0,0 +1,127 @@
+// cspeach-cli/src/tools/fiori/preview/readiness.ts
+/**
+ * L1-6 — the bounded readiness probe.
+ *
+ * A preview is READY only when BOTH legs answer:
+ *   1. the app URL itself (the UI5 server is serving index.html), and
+ *   2. `<origin><servicePath>$metadata` (the proxy leg actually reaches the
+ *      backend with the credentials and the CA we handed the child).
+ *
+ * Leg 2 is the whole point. A UI5 server comes up in a second and serves
+ * index.html happily while the proxy is still 401-ing, 502-ing or dying on a
+ * certificate — which is exactly how July's run looked green until a browser
+ * opened it. So "the port answered" is never enough.
+ *
+ * The outcome is CLASSIFIED, because the three failures need three different
+ * fixes:
+ *   - `refused`              — nothing is listening: the child died or never bound.
+ *   - `metadata-not-served`  — the app is up, the backend leg is not.
+ *   - `timeout`              — the socket answers but the app never arrives.
+ * When a later round regresses (the app stops answering after the service leg
+ * already failed) we keep the FURTHEST stage reached, because that is the
+ * informative one.
+ *
+ * Everything time-ish and network-ish is injected (ReadinessDeps) so the unit
+ * suite drives every path offline.
+ */
+/** Gap between polls. Small enough to feel instant, large enough not to spin. */
+export const POLL_INTERVAL_MS = 500;
+/**
+ * Furthest-stage ranking — a later round never downgrades the classification.
+ *
+ * `refused` is the LOWEST rank, not a high one (review F-8): every real start
+ * begins with a few refusals while the server binds, so if a refusal outranked
+ * an HTTP answer, every "server is up but the page 404s" failure would be
+ * reported as "nothing is listening" — the opposite of actionable. An answer,
+ * any answer, is further along than a refusal.
+ */
+const RANK = { refused: 0, timeout: 1, 'app-not-served': 2, 'metadata-not-served': 3 };
+/** A 2xx is served. A 3xx is a redirect (typically to a logon page) — not ready. */
+function served(status) {
+    return status >= 200 && status < 300;
+}
+/**
+ * `<origin><servicePath>$metadata`, or undefined when no service path is known
+ * (a freestyle app with no backend service still has a valid preview — it just
+ * has no second leg to probe).
+ */
+export function metadataUrlFor(appUrl, servicePath) {
+    const trimmed = (servicePath ?? '').trim();
+    if (trimmed.length === 0)
+        return undefined;
+    let origin;
+    try {
+        origin = new URL(appUrl).origin;
+    }
+    catch {
+        return undefined;
+    }
+    const withLead = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+    const withTrail = withLead.endsWith('/') ? withLead : `${withLead}/`;
+    return `${origin}${withTrail}$metadata`;
+}
+/**
+ * Polls until BOTH the app URL and <appUrl-origin><servicePath>$metadata answer
+ * 2xx through the proxy, or the budget runs out.
+ */
+export async function waitForPreview(appUrl, servicePath, budgetMs, deps) {
+    const metadataUrl = metadataUrlFor(appUrl, servicePath);
+    const started = deps.now();
+    // The starting point is "nothing answered at all"; the first refusal or HTTP
+    // status replaces it with something more informative.
+    let reason = 'timeout';
+    let detail = `no response from ${appUrl} within ${budgetMs}ms`;
+    let seenAnything = false;
+    const note = (r, d) => {
+        if (!seenAnything || RANK[r] >= RANK[reason]) {
+            reason = r;
+            detail = d;
+            seenAnything = true;
+        }
+    };
+    while (deps.now() - started < budgetMs) {
+        let appStatus;
+        try {
+            appStatus = (await deps.probe(appUrl)).status;
+        }
+        catch (err) {
+            const code = err?.code;
+            // R1-10: ETIMEDOUT = the port is open but the server stays silent.
+            if (code === 'ETIMEDOUT')
+                note('timeout', `${appUrl} accepted the connection but did not answer (ETIMEDOUT)`);
+            else
+                note('refused', `${appUrl} refused the connection (${code ?? err?.message ?? 'unknown'})`);
+            await deps.sleep(POLL_INTERVAL_MS);
+            continue;
+        }
+        if (!served(appStatus)) {
+            // The server IS up — it answered. The app page is the problem, and the
+            // usual cause is the wrong entry file. Say both things.
+            const entry = appUrl.split('/').pop() || appUrl;
+            note('app-not-served', `the preview server is up but ${appUrl} answered HTTP ${appStatus} — check that "${entry}" is the ` +
+                'app\'s entry page (a redirect is not a served app either)');
+            await deps.sleep(POLL_INTERVAL_MS);
+            continue;
+        }
+        if (metadataUrl === undefined) {
+            return { ready: true, ms: deps.now() - started };
+        }
+        let metaStatus;
+        try {
+            metaStatus = (await deps.probe(metadataUrl)).status;
+        }
+        catch (err) {
+            const code = err?.code;
+            note('metadata-not-served', `${metadataUrl} could not be reached through the preview proxy (${code ?? err?.message ?? 'unknown'})`);
+            await deps.sleep(POLL_INTERVAL_MS);
+            continue;
+        }
+        if (served(metaStatus)) {
+            return { ready: true, ms: deps.now() - started };
+        }
+        note('metadata-not-served', `the app is served but ${metadataUrl} answered HTTP ${metaStatus} through the preview proxy ` +
+            '(check the service path, the backend credentials and the CA)');
+        await deps.sleep(POLL_INTERVAL_MS);
+    }
+    return { ready: false, reason, detail };
+}