@cspeach/cli 1.1.24 → 1.1.26

package/dist/tools/fiori/deploy/run.js

@@ -0,0 +1,608 @@
+// cspeach-cli/src/tools/fiori/deploy/run.ts
+/**
+ * fiori_deploy — deploy a built UI5 app to the ABAP repository (a BSP) with
+ * SAP's own `fiori deploy` (@sap/ux-ui5-tooling), using the SAP logon CSPeach
+ * already holds for the alias. The developer never types a password and no
+ * environment variable has to be set before CSPeach starts.
+ *
+ * HOW THE LOGON TRAVELS
+ * ---------------------
+ * `fiori deploy --username X --password Y` takes the NAMES of environment
+ * variables (verified against @sap/ux-ui5-tooling 1.25.0: handleConfigCredentials
+ * turns them into `env:X` and the deploy tooling resolves process.env[X]).
+ * This module reads the password from the same keychain entry every ADT call
+ * uses (connection-manager resolveSapPassword, headless — never a prompt) and
+ * puts user + password into the deploy child's environment ONLY, under
+ * random per-run names (CSP_DEPLOY_U_<hex> / CSP_DEPLOY_P_<hex>).
+ *
+ * Why explicit names and not FIORI_TOOLS_USER / FIORI_TOOLS_PASSWORD (which
+ * the tooling also reads): those are consulted only AFTER the Fiori tools'
+ * own secure store, so a login saved there for the same URL would silently
+ * win over CSPeach's. Explicit --username/--password win over both.
+ *
+ *  - Never on argv (argv holds the variable names), never in the build child,
+ *    never in a file, never in a log line or result: every captured byte is
+ *    scrubbed (preview/env.ts scrubSecrets — every encoding of the secret).
+ *  - The child inherits the environment normally, minus CSPeach / Anthropic
+ *    secrets and minus NODE_TLS_REJECT_UNAUTHORIZED / NODE_EXTRA_CA_CERTS;
+ *    the CA is set ONLY from sap.<alias>.ca_cert_path.
+ *
+ * WHERE THE LOGON MAY GO (host rule)
+ * ----------------------------------
+ * The yaml's target must be the alias's system: same scheme (https when the
+ * alias uses SSL), same port, same client, and a host that is EITHER the
+ * alias host itself (case-insensitive) OR resolves only to addresses the alias
+ * host resolves to (this is what lets a yaml that names the box by IP pass
+ * for an alias that names it by hostname — and refuses an IP or host that is
+ * anything else). Then the deploy is sent to the ALIAS url and client
+ * (`--url` / `--client` override the yaml), so the logon only ever reaches the
+ * exact host ADT already talks to, and a yaml edited after the check changes
+ * nothing.
+ *
+ * GATES
+ * -----
+ *  - role prd: refused in both modes (CSPeach is a development agent).
+ *  - mode 'deploy' is a SAP write: refused when the effective write mode is
+ *    advisory-only; otherwise it needs an approval_id from request_approval
+ *    for the BSP name (op create or modify), one approval per deploy.
+ *  - mode 'test' writes nothing (the backend validates and rolls back), so it
+ *    needs no write approval — but it still hands the logon to a child, so the
+ *    tool's credentialHandover prompt (once per session per alias) applies.
+ */
+import crossSpawn from 'cross-spawn';
+import { promises as fs } from 'node:fs';
+import { lookup as dnsLookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+import * as path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { resolveSapTls } from '../../../config/loader.js';
+import { scrubSecrets } from '../preview/env.js';
+import { readDeployYaml } from './yaml-read.js';
+import { readExistingBsp, overwriteApprovalObject, bspFilePath } from './existing-bsp.js';
+import { validateDeployTarget } from '../deploy-config.js';
+import { killProcessTree } from '../preview/registry.js';
+const KEYCHAIN_SERVICE = 'cspeach-sap';
+/** Nonces of approvals that already ran one deploy (this process only). */
+const deployApprovalsUsed = new Set();
+export function __resetDeployApprovalsForTests() {
+    deployApprovalsUsed.clear();
+}
+/* ── host rule ─────────────────────────────────────────────────────────── */
+function bareHost(host) {
+    return host.trim().replace(/^[a-z][a-z0-9+.-]*:\/\//i, '').replace(/[/?#].*$/, '').replace(/:\d+$/, '')
+        .replace(/^\[|\]$/g, '').toLowerCase();
+}
+async function addressesOf(host, lookup) {
+    if (isIP(host))
+        return [host];
+    try {
+        return (await lookup(host)).map((a) => a.toLowerCase());
+    }
+    catch {
+        return [];
+    }
+}
+export async function matchDeployTarget(yamlUrl, yamlClient, system, lookup) {
+    const aliasHost = bareHost(system.host);
+    const aliasScheme = system.useSsl === false ? 'http:' : 'https:';
+    const aliasUrl = `${aliasScheme}//${aliasHost.includes(':') ? `[${aliasHost}]` : aliasHost}:${system.port}`;
+    let u;
+    try {
+        u = new URL(yamlUrl);
+    }
+    catch {
+        return { ok: false, error: `target.url "${yamlUrl}" is not a URL` };
+    }
+    if (u.username || u.password)
+        return { ok: false, error: 'target.url must not carry a user or password' };
+    if (u.protocol !== aliasScheme) {
+        return { ok: false, error: `target.url uses ${u.protocol.replace(':', '')}, but alias ${aliasUrl} uses ${aliasScheme.replace(':', '')} — refusing to send the SAP logon` };
+    }
+    const yamlPort = u.port !== '' ? Number(u.port) : u.protocol === 'https:' ? 443 : 80;
+    if (yamlPort !== Number(system.port)) {
+        return { ok: false, error: `target.url port ${yamlPort} is not the alias port ${system.port} — refusing to send the SAP logon` };
+    }
+    if (String(yamlClient).trim() !== String(system.client).trim()) {
+        return { ok: false, error: `target client ${yamlClient} is not the alias client ${system.client} — deploy with the alias for that client, or fix the yaml` };
+    }
+    const yamlHost = bareHost(u.hostname);
+    if (yamlHost === aliasHost)
+        return { ok: true, aliasUrl };
+    const aliasAddrs = new Set(await addressesOf(aliasHost, lookup));
+    const yamlAddrs = await addressesOf(yamlHost, lookup);
+    if (aliasAddrs.size > 0 && yamlAddrs.length > 0 && yamlAddrs.every((a) => aliasAddrs.has(a))) {
+        return {
+            ok: true,
+            aliasUrl,
+            note: `ui5-deploy.yaml names ${yamlHost}; it resolves to the alias host ${aliasHost}, so the deploy goes to ${aliasUrl}`,
+        };
+    }
+    return {
+        ok: false,
+        error: `ui5-deploy.yaml targets ${yamlHost}:${yamlPort}, which is not the system of this SAP alias (${aliasUrl}` +
+            `${aliasAddrs.size > 0 ? `, ${[...aliasAddrs].join(', ')}` : ''}). Refusing to send the SAP logon there. ` +
+            'Deploy with the alias for that system, or rewrite the deploy config with fiori_deploy_config for this one.',
+    };
+}
+/* ── helpers ───────────────────────────────────────────────────────────── */
+/** Variables the app's .env could set that would redirect or weaken the connection. dotenv runs inside fiori deploy. */
+const DOTENV_DANGER = /^\s*(?:export\s+)?(HTTPS?_PROXY|ALL_PROXY|NO_PROXY|NODE_TLS_REJECT_UNAUTHORIZED|NODE_EXTRA_CA_CERTS|NODE_OPTIONS|NODE_USE_ENV_PROXY|NO_RETRY|H2O_URL|WS_BASE_URL|FIORI_TOOLS_\w+|SAP_UX_\w+|SERVICE_\w+)(?:\s*=|:\s)/im;
+/**
+ * The child environment is an ALLOWLIST (the fiori_preview stance, preview/env.ts):
+ * what Node, npm and the Windows shell need to run, the locale, and the
+ * proxy settings a corporate network needs to reach SAP — nothing else. A
+ * parent GITHUB_TOKEN, AWS key, ANTHROPIC_API_KEY, CSPEACH_* token or
+ * NODE_OPTIONS never reaches project code. Names are compared upper-cased:
+ * Windows spells `Path` or `PATH` depending on the shell, and POSIX tools use
+ * both `http_proxy` and `HTTP_PROXY`.
+ */
+const ENV_ALLOW = new Set([
+    'PATH', 'PATHEXT', 'SYSTEMROOT', 'SYSTEMDRIVE', 'WINDIR', 'COMSPEC',
+    'TEMP', 'TMP', 'TMPDIR', 'HOME', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'HOMEDRIVE', 'HOMEPATH',
+    'PROGRAMDATA', 'PROGRAMFILES', 'PROGRAMFILES(X86)', 'NUMBER_OF_PROCESSORS', 'PROCESSOR_ARCHITECTURE', 'OS',
+    'LANG', 'LANGUAGE', 'TZ',
+    'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'ALL_PROXY', 'NODE_USE_ENV_PROXY',
+    // npm settings needed to resolve and cache — never npm auth (npm_config__auth*, //registry:_authToken).
+    'NPM_CONFIG_CACHE', 'NPM_CONFIG_PREFIX', 'NPM_CONFIG_USERCONFIG', 'NPM_CONFIG_GLOBALCONFIG',
+]);
+function allowedEnvKey(name) {
+    const n = name.toUpperCase();
+    return ENV_ALLOW.has(n) || /^LC_[A-Z]+$/.test(n);
+}
+/** Case-insensitive lookup (Windows env names are case-insensitive; POSIX tools use both cases for proxies). */
+function lookupEnv(env, name) {
+    const exact = env[name];
+    if (exact !== undefined)
+        return exact;
+    const hit = Object.keys(env).find((k) => k.toUpperCase() === name);
+    return hit === undefined ? undefined : env[hit];
+}
+/**
+ * Set `name` to `value`, removing any other spelling first. On POSIX the
+ * lower-case form is set too for the proxy variables (axios reads the
+ * lower-case one first there; on Windows the names are one variable).
+ */
+function pinEnv(env, name, value, bothCases = false) {
+    for (const k of Object.keys(env))
+        if (k.toUpperCase() === name)
+            delete env[k];
+    env[name] = value;
+    if (bothCases && process.platform !== 'win32')
+        env[name.toLowerCase()] = value;
+}
+const PROXY_VARS = ['HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'ALL_PROXY'];
+/**
+ * Review 2026-10-03 — the tooling runs dotenv on the app's .env, and dotenv
+ * never overrides a variable that is already SET. So every variable that
+ * could redirect or weaken the connection carrying the logon is set here
+ * explicitly — to the parent's value (proxies) or a safe fixed value — and a
+ * .env line for it can no longer take effect.
+ */
+const PINNED = [
+    ['NODE_TLS_REJECT_UNAUTHORIZED', '1'], // any value but '0' keeps Node's verification on
+    ['NODE_OPTIONS', ''],
+    ['H2O_URL', ''], // the tooling's App Studio switches (destination / BAS paths)
+    ['WS_BASE_URL', ''],
+    ['FIORI_TOOLS_USER', ''], // the explicit --username/--password win; never a stray login
+    ['FIORI_TOOLS_PASSWORD', ''],
+    ['FIORI_TOOLS_DISABLE_SECURE_STORE', 'true'], // never read or write the Fiori tools' own credential store
+    ['SAP_UX_FIORI_TOOLS_DISABLE_TELEMETRY', 'true'],
+    ['NO_RETRY', '1'], // no 401 re-prompt, no auto-confirmed 412 overwrite (with --failfast)
+];
+function childEnv(base, caCertPath) {
+    const env = {};
+    for (const [k, v] of Object.entries(base))
+        if (allowedEnvKey(k))
+            env[k] = v;
+    for (const name of PROXY_VARS)
+        pinEnv(env, name, lookupEnv(base, name) ?? '', true);
+    pinEnv(env, 'NODE_USE_ENV_PROXY', lookupEnv(base, 'NODE_USE_ENV_PROXY') ?? '');
+    for (const [name, value] of PINNED)
+        pinEnv(env, name, value);
+    for (const k of Object.keys(env))
+        if (k.toUpperCase() === 'NODE_EXTRA_CA_CERTS')
+            delete env[k];
+    if (caCertPath)
+        env.NODE_EXTRA_CA_CERTS = caCertPath;
+    return env;
+}
+async function readGuardedInputs(appDir) {
+    let yamlText;
+    try {
+        const real = await fs.realpath(path.join(appDir, 'ui5-deploy.yaml'));
+        const realApp = await fs.realpath(appDir);
+        const rel = path.relative(realApp, real);
+        if (rel.startsWith('..') || path.isAbsolute(rel))
+            return { ok: false, error: 'ui5-deploy.yaml links outside the app directory' };
+        yamlText = await fs.readFile(real, 'utf8');
+    }
+    catch {
+        return { ok: false, error: `no ui5-deploy.yaml in ${appDir} — write it first with fiori_deploy_config (BSP name, package, transport)` };
+    }
+    let dotenvText = null;
+    try {
+        dotenvText = await fs.readFile(path.join(appDir, '.env'), 'utf8');
+    }
+    catch { /* no .env */ }
+    if (dotenvText !== null) {
+        const m = DOTENV_DANGER.exec(dotenvText);
+        if (m) {
+            return {
+                ok: false,
+                error: `the app's .env sets ${m[1]}, which fiori deploy would load and which can redirect or weaken the connection that carries the SAP logon — remove that line from ${path.join(appDir, '.env')}`,
+            };
+        }
+    }
+    return { ok: true, yamlText, dotenvText };
+}
+async function findTooling(appDir, projectRoot) {
+    const stop = path.resolve(projectRoot);
+    let dir = path.resolve(appDir);
+    for (;;) {
+        const pkgDir = path.join(dir, 'node_modules', '@sap', 'ux-ui5-tooling');
+        try {
+            const pkg = JSON.parse(await fs.readFile(path.join(pkgDir, 'package.json'), 'utf8'));
+            const bin = path.join(pkgDir, 'bin', 'fiori.cjs');
+            if (pkg.name === '@sap/ux-ui5-tooling') {
+                await fs.access(bin);
+                return bin;
+            }
+        }
+        catch { /* not here */ }
+        if (dir === stop)
+            return null;
+        const parent = path.dirname(dir);
+        const rel = path.relative(stop, parent);
+        if (parent === dir || rel.startsWith('..') || path.isAbsolute(rel))
+            return null;
+        dir = parent;
+    }
+}
+const HEAD_CAP = 20_000;
+const TAIL_CAP = 180_000;
+/**
+ * The child's output, bounded: the first ~20k characters and a rolling last
+ * ~180k, both cut at line ends (so a secret on one line is never split by the
+ * cut and stays scrubbable), so the tooling's final success/failure line is
+ * never lost however chatty the run was.
+ */
+class CappedOutput {
+    head = '';
+    tail = '';
+    headFull = false;
+    truncated = false;
+    push(chunk) {
+        if (!this.headFull) {
+            this.head += chunk;
+            if (this.head.length > HEAD_CAP) {
+                const cut = this.head.lastIndexOf('\n', HEAD_CAP);
+                const at = cut >= 0 ? cut + 1 : HEAD_CAP;
+                this.tail = this.head.slice(at);
+                this.head = this.head.slice(0, at);
+                this.headFull = true;
+                this.trim();
+            }
+            return;
+        }
+        this.tail += chunk;
+        this.trim();
+    }
+    trim() {
+        if (this.tail.length <= TAIL_CAP)
+            return;
+        const excess = this.tail.length - TAIL_CAP;
+        const nlAt = this.tail.indexOf('\n', excess);
+        this.tail = nlAt >= 0 ? this.tail.slice(nlAt + 1) : this.tail.slice(excess);
+        this.truncated = true;
+    }
+    text() {
+        return this.truncated ? `${this.head}\n…(output truncated)…\n${this.tail}` : this.head + this.tail;
+    }
+}
+function runChild(spawn, cmd, args, opts, timeoutMs, kill) {
+    return new Promise((resolve) => {
+        const out = new CappedOutput();
+        let child;
+        try {
+            // detached on POSIX so the timeout can signal the whole process group (npm → node → workers).
+            child = spawn(cmd, args, {
+                ...opts, windowsHide: true, shell: false, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        }
+        catch (e) {
+            resolve({ code: null, signal: null, out: '', timedOut: false, spawnError: e instanceof Error ? e.message : String(e) });
+            return;
+        }
+        let done = false;
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            // The whole tree: taskkill /T /F on Windows, the process group on POSIX.
+            void kill(child.pid, child).catch(() => { try {
+                child.kill('SIGKILL');
+            }
+            catch { /* gone */ } });
+        }, timeoutMs);
+        // Decode as UTF-8 per stream, so a multibyte character (or password) split
+        // across two chunks is reassembled before anything is scrubbed.
+        child.stdout?.setEncoding?.('utf8');
+        child.stderr?.setEncoding?.('utf8');
+        child.stdout?.on('data', (c) => out.push(String(c)));
+        child.stderr?.on('data', (c) => out.push(String(c)));
+        const finish = (r) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            resolve({ ...r, out: out.text() });
+        };
+        child.on('error', (e) => finish({ code: null, signal: null, timedOut, spawnError: e.message }));
+        child.on('close', (code, signal) => finish({ code, signal: signal ?? null, timedOut }));
+    });
+}
+function tail(text, lines = 30) {
+    return text.split(/\r?\n/).filter((l) => l.trim().length > 0).slice(-lines).join('\n');
+}
+/** The tooling's own success lines (@sap-ux/deploy-tooling, 1.25.0). */
+/** The tooling's 412 warning; seen after all the checks above it is a failure, never a prompt to confirm. */
+const DIFFERENT_APP_412 = /different sap app id/i;
+const SUCCESS = {
+    deploy: /Deployment Successful\./,
+    test: /Deployment in TestMode completed\./,
+};
+/* ── the run ───────────────────────────────────────────────────────────── */
+export async function runFioriDeploy(input, deps = {}) {
+    const refuse = (error) => ({ ok: false, stage: 'refused', error });
+    const log = deps.log ?? (() => { });
+    const notes = [];
+    // ── 1. The alias ───────────────────────────────────────────────────────
+    let cfg;
+    try {
+        cfg = await (deps.loadConfig ?? (async () => (await import('../../../config/loader.js')).loadConfig()))();
+    }
+    catch (e) {
+        return refuse(`could not read the CSPeach config — ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const system = cfg.sap?.[input.alias];
+    if (!system)
+        return refuse(`unknown SAP alias "${input.alias}" — configure it first`);
+    if (system.authType !== 'basic')
+        return refuse(`alias ${input.alias} does not use a user + password logon — fiori_deploy supports basic logon only`);
+    if (system.role === 'prd') {
+        return refuse(`alias ${input.alias} is tagged as a production system (role prd) — CSPeach does not deploy there. Deploy in development and move the app with the transport.`);
+    }
+    // ── 2. The deploy config (untrusted file) ──────────────────────────────
+    const before = await readGuardedInputs(input.appDir);
+    if (!before.ok)
+        return refuse(before.error);
+    const read = readDeployYaml(before.yamlText);
+    if (!read.ok)
+        return refuse(read.error);
+    const y = read.config;
+    let pkg;
+    let isTmp;
+    try {
+        ({ package: pkg, isTmp } = validateDeployTarget({ appName: y.name, package: y.package, transport: y.transport }));
+    }
+    catch (e) {
+        return refuse(`ui5-deploy.yaml is not valid — ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!/^([ZY][A-Z0-9_]*|\/[A-Z0-9_]+\/[A-Z0-9_]+)$/.test(y.name)) {
+        return refuse(`BSP app name "${y.name}" must be in the customer namespace (Z…/Y… or /NAMESPACE/NAME)`);
+    }
+    const bsp = y.name;
+    // ── 3. Host rule ───────────────────────────────────────────────────────
+    const lookup = deps.lookupHost ?? (async (h) => (await dnsLookup(h, { all: true })).map((a) => a.address));
+    const match = await matchDeployTarget(y.url, y.client, system, lookup);
+    if (!match.ok)
+        return refuse(match.error);
+    if (match.note)
+        notes.push(match.note);
+    // ── 3b. TLS: the yaml cannot switch certificate checking off when the alias verifies.
+    // The tooling turns ignoreCertErrors: true into --no-strict-ssl; --strict-ssl true is read first.
+    const tls = resolveSapTls(system);
+    const strictSsl = tls.mode !== 'insecure';
+    if (strictSsl && y.ignoreCertErrors) {
+        notes.push('ignoreCertErrors: true in ui5-deploy.yaml was overridden — certificate verification stays ON for this deploy ' +
+            `(alias ${input.alias} verifies certificates${tls.caCertPath ? ` with ${tls.caCertPath}` : ''}); set it to false in the yaml`);
+    }
+    if (!strictSsl) {
+        notes.push(y.ignoreCertErrors
+            ? `certificate verification is OFF for this deploy (alias ${input.alias} is in insecure mode and the yaml sets ignoreCertErrors: true) — set sap.${input.alias}.ca_cert_path to a PEM root CA instead`
+            : `alias ${input.alias} is in insecure mode; this deploy still verifies the certificate against the system trust store (ignoreCertErrors: false in the yaml)`);
+    }
+    // ── 4. Write gate (deploy mode) ────────────────────────────────────────
+    const howToApprove = (object) => `call request_approval with a change {op:"create", object:"${object}", type:"WAPA", package:"${pkg}"` +
+        `${isTmp ? '' : `, transport "${y.transport}"`}} and pass the returned id as approval_id`;
+    if (input.mode === 'deploy') {
+        const effective = (deps.effectiveWriteMode ?? (await import('../../../repl/mode-cycle.js')).getEffectiveWriteMode)(cfg.write_mode ?? 'approval-gated', system.role);
+        if (effective === 'advisory-only') {
+            return refuse(`write mode is advisory-only for alias ${input.alias} — the deploy is a SAP write, so CSPeach will not run it. Run mode "test", or deploy by hand with the plan above.`);
+        }
+        if (!input.approvalId || input.approvalId.trim() === '')
+            return refuse(`approval_id is required for the real deploy — ${howToApprove(bsp)}.`);
+    }
+    // ── 5. Tooling + build (no logon involved yet) ─────────────────────────
+    const fioriBin = await findTooling(input.appDir, input.projectRoot);
+    if (!fioriBin) {
+        return refuse('@sap/ux-ui5-tooling is not installed in this app (node_modules/@sap/ux-ui5-tooling) — run "npm install" in the app directory first');
+    }
+    const spawn = deps.spawn ?? crossSpawn;
+    const kill = deps.kill ?? killProcessTree;
+    const baseEnv = childEnv(deps.baseEnv ?? process.env, tls.mode === 'ca-trusted' ? tls.caCertPath : undefined);
+    // ── 6. The logon — keychain only, never a prompt (read before the build, so a missing one fails fast)
+    let password;
+    try {
+        const { resolveSapPassword } = await import('../../../sap/connection-manager.js');
+        password = await resolveSapPassword(input.alias, system, {
+            headless: () => true,
+            ...(deps.getPassword ? { getPassword: deps.getPassword } : {}),
+        });
+    }
+    catch {
+        return refuse(`no stored password for SAP alias '${input.alias}' — the deploy uses the logon CSPeach keeps in the OS credential store and cannot prompt. ` +
+            'Store it once (run cspeach interactively and connect, or use cspeach config) and try again.');
+    }
+    const username = system.username;
+    const scrub = (t) => scrubSecrets(t, password, username);
+    const fetchSap = deps.fetchSap ?? (async (alias, p) => {
+        const { getConnection } = await import('../../../sap/connection-manager.js');
+        const conn = await getConnection(alias, system);
+        const r = await conn.get(p, 'application/json, text/html, */*');
+        return { status: r.status, body: r.body };
+    });
+    // ── 6b. Existing BSP pre-check (read-only): never overwrite another app silently
+    const existing = await readExistingBsp(bsp, (p) => fetchSap(input.alias, p));
+    if (existing.kind === 'unknown') {
+        return refuse(`could not check whether BSP ${bsp} already exists — ${scrub(existing.reason)}. CSPeach does not deploy without that check (it would risk overwriting another app).`);
+    }
+    let approvalObject = bsp;
+    if (existing.kind === 'existing') {
+        let localId = null;
+        try {
+            const id = JSON.parse(await fs.readFile(path.join(input.appDir, 'webapp', 'manifest.json'), 'utf8'))['sap.app']?.id;
+            if (typeof id === 'string' && id.trim() !== '')
+                localId = id.trim();
+        }
+        catch { /* unreadable — handled below */ }
+        if (!localId) {
+            return refuse(`BSP ${bsp} already exists on the system, and this app's webapp/manifest.json has no readable sap.app.id to compare it with — fix the manifest first.`);
+        }
+        const sameApp = existing.appId !== null && existing.appId === localId;
+        if (!sameApp) {
+            approvalObject = overwriteApprovalObject(bsp, existing.appId);
+            const held = existing.appId
+                ? `holds a different app (app id ${existing.appId})`
+                : 'holds an app whose app id could not be read (no readable manifest.json)';
+            const where = existing.package ? ` in package ${existing.package}` : '';
+            const desc = existing.description ? ` — "${existing.description}"` : '';
+            const why = `BSP ${bsp} already exists${where} and ${held}${desc}; this app is ${localId}. Deploying would overwrite it — it may belong to another team. ` +
+                `Choose another BSP name with fiori_deploy_config, or, if replacing it is intended, run mode "deploy" with an approval that names the overwrite: ${howToApprove(approvalObject)}.`;
+            if (input.mode === 'test')
+                return refuse(why);
+            notes.push(`overwrites the existing BSP ${bsp} (app id ${existing.appId ?? 'unknown'}) — approved explicitly`);
+            if (input.approvalId === undefined)
+                return refuse(why);
+        }
+    }
+    if (input.mode === 'deploy') {
+        const verify = deps.verifyApproval ?? (await import('../../../approvals/jwt.js')).verifyAndSpendApprovalId;
+        const v = await verify(input.approvalId ?? '', approvalObject, 'modify');
+        if (!v.ok)
+            return refuse(`APPROVAL_INVALID: ${v.reason} — ${howToApprove(approvalObject)}.`);
+        if (String(v.payload.type ?? '').trim().toUpperCase() !== 'WAPA') {
+            return refuse(`APPROVAL_INVALID: the approval is for type ${v.payload.type}, not a BSP application (WAPA) — ${howToApprove(approvalObject)}.`);
+        }
+        if (v.matchKind === 'list_member') {
+            return refuse(`APPROVAL_INVALID: the approval lists several objects; a deploy needs an approval for exactly this BSP — ${howToApprove(approvalObject)}.`);
+        }
+        // A real deploy writes to SAP: it needs an approval a human saw on screen,
+        // never one minted by auto_approve (as cap_link_smoke's write leg).
+        if (v.payload.auto) {
+            return refuse(`the real deploy needs an approval you confirmed on screen, not an auto-approval — ${howToApprove(approvalObject)}.`);
+        }
+        if (deployApprovalsUsed.has(v.payload.nonce)) {
+            return refuse(`this approval_id already ran one deploy — each deploy needs its own approval; ${howToApprove(approvalObject)}.`);
+        }
+        // Spent at verify: a build failure below does not free it.
+        deployApprovalsUsed.add(v.payload.nonce);
+    }
+    let scripts = {};
+    try {
+        scripts = JSON.parse(await fs.readFile(path.join(input.appDir, 'package.json'), 'utf8')).scripts ?? {};
+    }
+    catch {
+        return refuse(`could not read ${path.join(input.appDir, 'package.json')}`);
+    }
+    if (typeof scripts.build === 'string') {
+        const npm = await (deps.resolveNpm ?? (async () => (await import('../../_command-shared.js')).resolveExecutable('npm')))();
+        if (!npm)
+            return refuse('npm is not on PATH — needed to run the app\'s "build" script before the deploy');
+        log(`fiori_deploy: building ${input.appDir} (npm run build)`);
+        const b = await runChild(spawn, npm, ['run', 'build', '--ignore-scripts'], { cwd: input.appDir, env: baseEnv }, deps.buildTimeoutMs ?? 300_000, kill);
+        if (b.spawnError || b.timedOut || b.code !== 0) {
+            const why = b.spawnError ? `could not start npm — ${b.spawnError}` : b.timedOut ? 'timed out' : `exit code ${b.code}`;
+            return { ok: false, stage: 'build', error: `npm run build failed (${why}); nothing was sent to SAP.\n${tail(b.out)}` };
+        }
+    }
+    else {
+        try {
+            await fs.access(path.join(input.appDir, 'dist'));
+        }
+        catch {
+            return refuse('the app has no "build" script and no dist/ folder — build the app first');
+        }
+    }
+    // ── 6c. TOCTOU: the build ran project code in the app folder. Re-read what
+    // fiori deploy will read, right before it starts; any change is refused.
+    const after = await readGuardedInputs(input.appDir);
+    if (!after.ok)
+        return refuse(after.error);
+    if (after.yamlText !== before.yamlText) {
+        return refuse('ui5-deploy.yaml changed while the app was being built — nothing was sent. Check it, then run fiori_deploy again.');
+    }
+    if (after.dotenvText !== before.dotenvText) {
+        return refuse("the app's .env changed while the app was being built — nothing was sent. Check it, then run fiori_deploy again.");
+    }
+    // ── 7. Deploy child ────────────────────────────────────────────────────
+    const suffix = (deps.varSuffix ?? (() => randomBytes(8).toString('hex').toUpperCase()))();
+    const userVar = `CSP_DEPLOY_U_${suffix}`;
+    const passVar = `CSP_DEPLOY_P_${suffix}`;
+    // NO_RETRY (pinned in childEnv) + --failfast switch the tooling's retry handler off: no 401 re-prompt,
+    // and no auto-confirmed HTTP 412 "different sap app id" overwrite (with --yes it would overwrite silently).
+    const env = { ...baseEnv, [userVar]: username, [passVar]: password };
+    const args = [
+        fioriBin, 'deploy',
+        '--config', 'ui5-deploy.yaml',
+        '--url', match.aliasUrl,
+        '--client', String(system.client),
+        '--name', bsp,
+        '--package', pkg,
+        ...(isTmp ? [] : ['--transport', y.transport]),
+        ...(input.mode === 'test' ? ['--testMode'] : []),
+        ...(strictSsl ? ['--strict-ssl', 'true'] : []),
+        '--yes',
+        '--failfast',
+        '--username', userVar,
+        '--password', passVar,
+    ];
+    log(`fiori_deploy: ${input.mode === 'test' ? 'test-mode deploy (nothing is written)' : 'deploying'} ${bsp} to ${match.aliasUrl} client ${system.client}`);
+    const d = await runChild(spawn, deps.nodePath ?? process.execPath, args, { cwd: input.appDir, env }, deps.deployTimeoutMs ?? 600_000, kill);
+    const output = scrub(d.out);
+    const okLine = SUCCESS[input.mode].test(output) && !/Deployment has failed/i.test(output) && !DIFFERENT_APP_412.test(output);
+    if (d.spawnError || d.timedOut || d.code !== 0 || !okLine) {
+        const why = d.spawnError ? `could not start fiori deploy — ${scrub(d.spawnError)}` : d.timedOut ? 'timed out' : d.code !== 0 ? `exit code ${d.code}` : 'no success line in the output';
+        return {
+            ok: false,
+            stage: 'deploy',
+            error: `fiori deploy ${input.mode === 'test' ? '(test mode) ' : ''}failed for ${bsp} (${why}). Backend output:\n${tail(output) || '(no output)'}`,
+        };
+    }
+    if (input.mode === 'test') {
+        return {
+            ok: true, mode: 'test', bsp, output, notes,
+            summary: `Test mode passed for ${bsp} → package ${pkg}${isTmp ? '' : `, transport ${y.transport}`} on ${match.aliasUrl} client ${system.client}. The backend validated the upload; nothing was deployed.`,
+        };
+    }
+    // ── 8. Verify (Forge Rule 10) ──────────────────────────────────────────
+    const sapPath = bspFilePath(bsp, 'index.html');
+    const url = `${match.aliasUrl}${sapPath}?sap-client=${system.client}`;
+    let status;
+    try {
+        status = (await fetchSap(input.alias, sapPath)).status;
+    }
+    catch (e) {
+        return { ok: false, stage: 'verify', error: `deployed ${bsp}, but the check GET ${url} failed — ${scrub(e instanceof Error ? e.message : String(e))}` };
+    }
+    if (status !== 200) {
+        return {
+            ok: false,
+            stage: 'verify',
+            error: `deployed ${bsp}, but GET ${url} answered HTTP ${status} (expected 200). A 403/404 usually means the SICF node /sap/bc/ui5_ui5 needs activating or the upload was rejected — deploy output:\n${tail(output, 15)}`,
+        };
+    }
+    return {
+        ok: true, mode: 'deploy', bsp, url, output, notes,
+        summary: `Deployed ${bsp} → package ${pkg}${isTmp ? '' : `, transport ${y.transport}`} on ${match.aliasUrl} client ${system.client}. Verified: GET ${url} → 200.`,
+    };
+}

package/dist/tools/fiori/deploy/scope.js

@@ -0,0 +1,8 @@
+// cspeach-cli/src/tools/fiori/deploy/scope.ts
+/**
+ * The credential-handover scope of fiori_deploy. Its own module so the plan
+ * chain's deploy card (commands/deploy-card.ts) can record the approval
+ * without importing the tool registry. With a scope, an earlier fiori_preview
+ * approval for the same alias does not cover a deploy (and vice versa).
+ */
+export const FIORI_DEPLOY_HANDOVER_SCOPE = 'fiori_deploy';