@cspeach/cli 1.1.18 → 1.1.19

package/dist/tools/fiori/tools.js

@@ -49,14 +49,26 @@ import * as path from 'node:path';
 import { registerTool } from '../index.js';
 import { resolveSafePath, PathOutsideRootError } from '../_filesystem-shared.js';
 import { scaffoldFreestyle } from './scaffold.js';
+import { decodeHtmlEscapes } from './html-escapes.js';
 import { applyEntry } from './apply.js';
 import { listCatalog } from './catalog/index.js';
 import { writeDeployConfig } from './deploy-config.js';
 import { scaffoldFioriElements } from './fe-scaffold.js';
+import { deriveExpectedColumns } from './smoke/audit-columns.js';
+import { PINNED_UI5_VERSION } from './ui5-version.js';
 import { feExtend, FE_EXTEND_OPS, NotV4FeAppError } from './fe-extend.js';
 import { runSmoke } from './smoke/run-smoke.js';
+import { runDraftSmoke, draftSmokePreconditions } from './smoke/draft-smoke.js';
+import { customerService, isLoopbackAppUrl, capService, isCapDevIndex } from './smoke/draft-safety.js';
+import { verifyAndSpendApprovalId } from '../../approvals/jwt.js';
 import { deriveFreestyleSmokeSpec, FreestyleSmokeDerivationError } from './smoke/freestyle-spec.js';
 import { loadConfig, resolveRenderSmoke } from '../../config/loader.js';
+import { startPreview } from './preview/start.js';
+import { loginNeed, readStartScript } from './preview/app-guard.js';
+import { isCredentialHandoverApproved } from '../../repl/credential-handover-gate.js';
+import { listPreviews, stopPreview, findPreviewById, installPreviewExitHandler, } from './preview/registry.js';
+import { auditMetadata } from './metadata/audit.js';
+import { readValueListReferences, resolveReferenceUrl } from './metadata/references.js';
 import { searchSamples } from './samples/search.js';
 import { loadSampleSource, SampleFetchError, UnsafeSampleNameError } from './samples/loader.js';
 // The grounding corpus ships as an imported JSON module + the bundled
@@ -105,6 +117,10 @@ async function listFilesUnder(ctx, dir) {
     await walk(dir);
     return out.sort();
 }
+// Dry run 2026-09-25: the model sent appTitle "Suppliers & Quality
+// Certificates" and the app header showed "&". A title is plain text — the
+// writers escape it where HTML needs it — so escapes arriving in it are decoded.
+const decodeTitle = decodeHtmlEscapes;
 // ───────────────────────────── fiori_scaffold ─────────────────────────────
 export async function fioriScaffoldHandler(args, ctx) {
     if (!args.basePath)
@@ -118,7 +134,7 @@ export async function fioriScaffoldHandler(args, ctx) {
         await scaffoldFreestyle({
             basePath: resolved.abs,
             appId: args.appId,
-            appTitle: args.appTitle ?? args.appId,
+            appTitle: decodeTitle(args.appTitle ?? args.appId),
             template: args.template ?? 'basic',
             service: args.serviceUrl
                 ? { url: args.serviceUrl, path: args.servicePath ?? '', version: args.serviceVersion ?? '4.0' }
@@ -239,12 +255,13 @@ export async function fioriScaffoldFeHandler(args, ctx) {
         await scaffoldFioriElements({
             basePath: resolved.abs,
             appId: args.appId,
-            appTitle: args.appTitle ?? args.appId,
+            appTitle: decodeTitle(args.appTitle ?? args.appId),
             template: args.template ?? 'lrop',
             service: { url: args.serviceUrl, path: args.servicePath, version: args.serviceVersion ?? '4.0', metadata: args.metadata, client: args.client },
             mainEntity: args.mainEntity,
             ui5Version: args.ui5Version,
             localAnnotations: args.localAnnotations,
+            ...(args.backend === 'cap' ? { backend: 'cap' } : {}),
         });
     }
     catch (err) {
@@ -293,6 +310,127 @@ export async function feExtendHandler(args, ctx) {
                 : `No new files (manifest-only change).`),
     };
 }
+// ─────────────────────────────── fiori_preview ────────────────────────────
+/**
+ * Preview lifecycle (L1-6). `start` brings a local preview server up for an
+ * already-scaffolded app with TLS verification ON and the SAP login supplied
+ * through the child's process environment; `stop` kills its whole process tree;
+ * `list` shows what this CLI process is running.
+ *
+ * `deps` is the test seam (spawn / port picker / readiness / config / keychain);
+ * in production it is undefined and the real ones are used. No npm process ever
+ * starts in the unit suite.
+ */
+export async function fioriPreviewHandler(args, ctx, deps) {
+    // Whatever the action, a preview must never outlive this CLI process.
+    installPreviewExitHandler();
+    const action = args.action ?? 'start';
+    if (action === 'list') {
+        const rows = listPreviews().map((e) => ({
+            previewId: e.previewId,
+            url: e.url,
+            port: e.port,
+            pid: e.pid,
+            entry: e.entry,
+            alias: e.alias,
+            appDir: rel(ctx, e.appDir),
+            startedAt: new Date(e.startedAt).toISOString(),
+        }));
+        return { content: JSON.stringify(rows, null, 2) };
+    }
+    if (action === 'stop') {
+        if (!args.previewId)
+            return { content: 'error: previewId is required for action "stop"', is_error: true };
+        const res = await stopPreview(args.previewId);
+        if (!res.stopped) {
+            return {
+                content: `error: no running preview with previewId "${args.previewId}" — call fiori_preview with action "list".`,
+                is_error: true,
+            };
+        }
+        // F-7: claim only what the evidence shows. The port is polled closed on
+        // both loopback families; a kill that was issued but left the port open is
+        // an error, not a success line.
+        if (res.portClosed) {
+            return {
+                content: `Preview ${args.previewId} stopped — port ${res.port} is closed.` +
+                    (res.issued ? '' : `\n(No process was killed: ${res.reason ?? 'no live handle in this session'}.)`),
+            };
+        }
+        return {
+            content: `error: preview ${args.previewId} was removed from the registry but port ${res.port} still answers` +
+                (res.issued ? ` (kill issued, exit code ${String(res.exitCode)})` : ` — nothing was killed: ${res.reason ?? 'no live handle in this session'}`) +
+                '. Close it by hand before starting another preview for this app.',
+            is_error: true,
+        };
+    }
+    if (action !== 'start') {
+        return { content: `error: unknown action "${String(args.action)}" — expected start, stop or list`, is_error: true };
+    }
+    if (!args.appDir)
+        return { content: 'error: appDir is required for action "start"', is_error: true };
+    const resolved = safeDir(ctx, args.appDir);
+    if ('error' in resolved)
+        return { content: `error: ${resolved.error}`, is_error: true };
+    const result = await startPreview({
+        appDir: resolved.abs,
+        alias: args.alias ?? ctx.sapAlias,
+        servicePath: args.servicePath ?? '',
+        ...(args.budgetMs !== undefined ? { budgetMs: args.budgetMs } : {}),
+        ...(args.entryFile !== undefined ? { entryFile: args.entryFile } : {}),
+    }, {
+        ...deps,
+        // Round 2b TOCTOU guard: ALWAYS the real approval gate — a caller's deps
+        // can never claim an approval the human did not give.
+        isLoginApproved: (alias) => isCredentialHandoverApproved(ctx.session?.id, alias),
+    });
+    if (!result.ok)
+        return { content: `error: ${result.error}`, is_error: true };
+    const e = result.entry;
+    // The TLS posture is ALWAYS stated, and an insecure alias gets its own line.
+    // Every non-fatal note (a replaced preview for another alias, the insecure
+    // warning) is surfaced too — a silent replacement is how ':8080 beside :8081'
+    // happened in the first place.
+    const lines = [
+        `Preview ${result.reused ? 'already running (reused)' : 'started'}: ${e.url}`,
+        `previewId: ${e.previewId}`,
+        `port: ${e.port}  pid: ${e.pid ?? 'unknown'}  entry: ${e.entry}  alias: ${e.alias}`,
+        `appDir: ${rel(ctx, e.appDir)}`,
+        `TLS: ${result.tlsNote}`,
+    ];
+    for (const w of result.warnings)
+        lines.push(`WARNING: ${w}`);
+    lines.push(result.loginPassed
+        ? 'Credentials reached the preview through the process environment only — no file on disk holds them.'
+        : 'no backend url in ui5.yaml — started without the SAP login', `Pass previewId "${e.previewId}" to fiori_render_smoke instead of appUrl.`);
+    return { content: lines.join('\n') };
+}
+/**
+ * Resolve the preview URL a smoke should drive. `previewId` wins over `appUrl`
+ * when both are given (and the caller is told), because the registry knows the
+ * port that is actually live — that is the whole point of L1-6. Callers that
+ * pass only `appUrl` are untouched: `undefined` comes back and the existing
+ * error/behaviour stands byte-identical.
+ *
+ * Exported so `fiori_draft_smoke` (L1-5b) resolves it the same way.
+ */
+export function resolvePreviewAppUrl(args) {
+    if (!args.previewId)
+        return {};
+    const entry = findPreviewById(args.previewId);
+    if (!entry) {
+        return {
+            error: `no running preview with previewId "${args.previewId}" — call fiori_preview with action "list", ` +
+                'or start one with action "start".',
+        };
+    }
+    return {
+        appUrl: entry.url,
+        ...(args.appUrl && args.appUrl !== entry.url
+            ? { note: `previewId "${args.previewId}" wins over the supplied appUrl — using ${entry.url}` }
+            : {}),
+    };
+}
 /**
  * FREESTYLE MODE (appDir given): derive a SmokeSpec from the app's own webapp/
  * tree via deriveFreestyleSmokeSpec, then let explicit spec args override the
@@ -337,6 +475,14 @@ export async function fioriRenderSmokeHandler(args, ctx,
 // Test seam: injected runSmoke deps (browser/openApp/renderSmokeEnabled). In
 // production this is undefined and the real config-driven deps are used.
 deps) {
+    // L1-6: a registered previewId resolves to the URL the preview is ACTUALLY
+    // serving. Callers that pass only appUrl take `{}` back here and fall through
+    // to exactly the code (and the error) that existed before.
+    const resolvedPreview = resolvePreviewAppUrl(args);
+    if ('error' in resolvedPreview)
+        return { content: `error: ${resolvedPreview.error}`, is_error: true };
+    if (resolvedPreview.appUrl)
+        args = { ...args, appUrl: resolvedPreview.appUrl };
     if (!args.appUrl) {
         return {
             content: 'error: appUrl is required — the LOCAL AUTHENTICATED PREVIEW URL (the `npm run start` / ' +
@@ -348,6 +494,8 @@ deps) {
     // Freestyle mode (appDir): derive + merge, and surface the derivation warnings.
     let spec = args;
     let warnings;
+    if (resolvedPreview.note)
+        warnings = [resolvedPreview.note];
     if (args.appDir) {
         const derived = resolveFreestyleSmokeSpec(args, ctx);
         if ('error' in derived) {
@@ -357,7 +505,24 @@ deps) {
             };
         }
         spec = derived.spec;
-        warnings = derived.warnings;
+        // Keep the previewId note (if any) in front of the derivation warnings.
+        warnings = [...(warnings ?? []), ...derived.warnings];
+    }
+    else if (args.metadataAudit) {
+        // L1-2 — FE mode with the audit: the expected columns are the audit's
+        // UI.LineItem labels (machine truth), and a model-supplied list does not
+        // override them. Without the audit nothing here runs (byte-identical).
+        const derivedColumns = deriveExpectedColumns(args.metadataAudit)
+            .map((c) => c.label)
+            .filter((l) => typeof l === 'string' && l.length > 0);
+        if (args.expectedColumns !== undefined) {
+            warnings = [
+                ...(warnings ?? []),
+                'expectedColumns ignored: in Fiori Elements mode the expected columns are derived from metadataAudit ' +
+                    `(${derivedColumns.join(', ') || 'none'})`,
+            ];
+        }
+        spec = { ...args, expectedColumns: derivedColumns };
     }
     // The render_smoke config toggle (plain default true) gates whether a browser
     // is actually launched; when off, runSmoke returns a skipped manual result.
@@ -371,6 +536,149 @@ deps) {
     const payload = warnings !== undefined ? { ...result, warnings } : result;
     return { content: JSON.stringify(payload, null, 2) };
 }
+/** One draft smoke per approval: nonces of approvals that already ran one (this process only). */
+const draftSmokeApprovalsUsed = new Set();
+/**
+ * L1-5b — fiori_draft_smoke. A SAP WRITE: it creates, edits and deletes one
+ * CSP-SMOKE-<runId> test row through the app's own service. Order matters:
+ *   1. refusals that need no network: a passed-in audit, the customer service
+ *      (Z*|Y*) on servicePath, a non-loopback app URL, no approval_id, render_smoke off;
+ *   2. the tool's OWN audit — fetchMetadataAudit, the same fetch + reference
+ *      resolution fiori_metadata_audit uses. Nothing model-supplied chooses the
+ *      service root, the activation action or the mandatory fields;
+ *   3. the audit-based refusals (draft root + activation action, marker field,
+ *      edit field) — still before any write;
+ *   4. the approval, verified through the SAME verifyAndSpendApprovalId every SAP
+ *      write tool uses (object = the binding of the servicePath the tool fetched),
+ *      one run per approval;
+ *   5. the browser.
+ */
+export async function fioriDraftSmokeHandler(args, ctx, deps) {
+    const refuse = (why) => ({
+        content: `error: fiori_draft_smoke refused (nothing was sent): ${why}`,
+        is_error: true,
+    });
+    if (args && Object.prototype.hasOwnProperty.call(args, 'metadataAudit')) {
+        return refuse('metadataAudit is not an input — pass servicePath; the smoke fetches and audits the service itself ' +
+            '(the activation action and the mandatory fields must come from the system, not from the call)');
+    }
+    const resolvedPreview = resolvePreviewAppUrl(args);
+    if ('error' in resolvedPreview)
+        return { content: `error: ${resolvedPreview.error}`, is_error: true };
+    const appUrl = resolvedPreview.appUrl ?? args.appUrl;
+    if (!appUrl) {
+        return {
+            content: 'error: appUrl (the local preview URL) or previewId (from fiori_preview "start") is required.',
+            is_error: true,
+        };
+    }
+    const isCap = args.backend === 'cap';
+    const rawPath = typeof args.servicePath === 'string' ? args.servicePath.trim() : '';
+    let serviceRoot;
+    let approvalObject;
+    let capOrigin;
+    if (isCap) {
+        // CAP rule (owner-approved 2026-09-25) — separate from the SAP rule below.
+        const cs = capService(rawPath);
+        if (!cs.ok)
+            return refuse(cs.reason);
+        serviceRoot = cs.serviceRoot;
+        approvalObject = cs.service;
+    }
+    else {
+        const svc = customerService(rawPath);
+        if (!svc.ok)
+            return refuse(svc.reason);
+        serviceRoot = svc.serviceRoot;
+        approvalObject = svc.binding;
+    }
+    if (!isLoopbackAppUrl(appUrl)) {
+        return refuse(`appUrl "${appUrl}" is not a local preview (http(s) on localhost / 127.x / [::1]) — ` +
+            'fiori_draft_smoke runs only against the preview it is given, never a deployed app');
+    }
+    if (isCap) {
+        // The loopback origin must PROVE it is the CAP development server: its root
+        // serves CAP's development index (development only) listing this service.
+        // A UI5 preview forwarding to a remote CAP app serves its own page instead.
+        capOrigin = new URL(appUrl).origin;
+        const fetchText = deps?.fetchText ?? defaultCapFetchText;
+        let index;
+        try {
+            index = await fetchText(`${capOrigin}/`);
+        }
+        catch (err) {
+            return refuse(`could not reach ${capOrigin}/ — ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (index.status < 200 || index.status >= 300 || !isCapDevIndex(index.body, serviceRoot)) {
+            return refuse(`${capOrigin} is not the CAP development server for ${serviceRoot} — its root does not serve CAP's ` +
+                'development index listing this service. On the CAP path fiori_draft_smoke writes only to the local ' +
+                'CAP dev server itself (cds watch), never through a proxy and never to a deployed app');
+        }
+    }
+    const howToApprove = `call request_approval with a change {op:"modify", object:"${approvalObject}", type:"DATA"} — it creates, ` +
+        'edits and deletes one CSP-SMOKE test row — and pass the returned id';
+    if (typeof args.approval_id !== 'string' || args.approval_id.trim() === '') {
+        return { content: `error: approval_id is required — ${howToApprove}.`, is_error: true };
+    }
+    const renderSmokeEnabled = deps?.renderSmokeEnabled ?? resolveRenderSmoke(await loadConfig());
+    if (!renderSmokeEnabled) {
+        return {
+            content: JSON.stringify({
+                verification: 'manual',
+                passed: false,
+                checks: [
+                    { name: 'skipped', ok: false, detail: 'render smoke disabled (render_smoke config is off); nothing was written' },
+                ],
+            }, null, 2),
+        };
+    }
+    // The tool's own audit — read-only GETs of $metadata and its value-help documents.
+    const capAuth = args.capUser ? { Authorization: `Basic ${Buffer.from(`${args.capUser}:`).toString('base64')}` } : undefined;
+    const fetched = await fetchMetadataAudit({
+        servicePath: serviceRoot,
+        ...(isCap ? { capPath: true } : {}),
+        ...(args.entitySet ? { entitySet: args.entitySet } : {}),
+        ...(args.localAnnotationsXml ? { localAnnotationsXml: args.localAnnotationsXml } : {}),
+    }, ctx, deps?.fetchDoc
+        ? { fetchDoc: deps.fetchDoc }
+        : isCap
+            ? { fetchDoc: (p) => defaultCapFetchText(`${capOrigin}${p}`, capAuth) }
+            : undefined);
+    if ('error' in fetched) {
+        return {
+            content: `error: fiori_draft_smoke stopped before any write — could not read the service's $metadata: ${fetched.error}`,
+            is_error: true,
+        };
+    }
+    const spec = {
+        appUrl,
+        metadataAudit: fetched.audit,
+        markerField: args.markerField,
+        ...(args.editField ? { editField: args.editField } : {}),
+        ...(typeof args.slowMo === 'number' ? { slowMo: args.slowMo } : {}),
+        ...(typeof args.headless === 'boolean' ? { headless: args.headless } : {}),
+        ...(isCap ? { backend: 'cap' } : {}),
+        ...(isCap && args.capUser ? { capUser: args.capUser } : {}),
+    };
+    const refused = draftSmokePreconditions(spec);
+    if (refused)
+        return refuse(refused);
+    const verify = await verifyAndSpendApprovalId(args.approval_id, approvalObject, 'modify');
+    if (!verify.ok) {
+        return { content: `error: APPROVAL_INVALID: ${verify.reason} — ${howToApprove}.`, is_error: true };
+    }
+    if (draftSmokeApprovalsUsed.has(verify.payload.nonce)) {
+        return {
+            content: `error: this approval_id already ran one draft smoke — each run needs its own approval; ${howToApprove}.`,
+            is_error: true,
+        };
+    }
+    draftSmokeApprovalsUsed.add(verify.payload.nonce);
+    const { renderSmokeEnabled: _enabled, fetchDoc: _fetch, fetchText: _text, ...runDeps } = deps ?? {};
+    const result = await runDraftSmoke(spec, runDeps);
+    const payload = resolvedPreview.note ? { ...result, warnings: [resolvedPreview.note] } : result;
+    return { content: JSON.stringify(payload, null, 2) };
+}
 // ─────────────────────────────── fiori_sample_search ──────────────────────
 export async function fioriSampleSearchHandler(args, _ctx) {
     if (!args.text || !args.text.trim()) {
@@ -423,6 +731,118 @@ export async function fioriSampleGetHandler(args, _ctx) {
         return { content: `error: could not load sample "${args.name}" — ${err instanceof Error ? err.message : String(err)}`, is_error: true };
     }
 }
+/** `/sap/…/0001/` or `/sap/…/0001/$metadata` → the `$metadata` path. Query strings dropped. */
+function metadataPathOf(servicePath) {
+    const p = servicePath.split('?')[0];
+    if (p.endsWith('$metadata'))
+        return p;
+    return `${p.endsWith('/') ? p : `${p}/`}$metadata`;
+}
+/**
+ * The ONE fetch + audit path (fiori_metadata_audit, and fiori_draft_smoke which
+ * must not trust a model-supplied audit): GET the `$metadata` over the alias's
+ * connection, resolve every ValueListReferences document, run auditMetadata.
+ * Errors come back as data (the message the audit tool prints after "error: ").
+ */
+/** CAP path: a plain loopback GET with a timeout (the CAP dev server, never SAP). */
+async function defaultCapFetchText(url, headers) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 10_000);
+    try {
+        const r = await fetch(url, { signal: ctrl.signal, ...(headers ? { headers } : {}) });
+        return { status: r.status, body: await r.text() };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function fetchMetadataAudit(args, ctx, deps) {
+    const servicePath = typeof args.servicePath === 'string' ? args.servicePath.trim() : '';
+    // A path on the alias's own host only — never a URL, never a relative path.
+    // CAP path: the caller proved the local CAP dev server and supplies fetchDoc.
+    if (args.capPath ? !capService(servicePath).ok : !servicePath.startsWith('/sap/')) {
+        return {
+            error: 'servicePath must start with /sap/ — the OData V4 service path on the configured system, e.g. ' +
+                '"/sap/opu/odata4/sap/zui_x_o4/srvd/sap/zui_x/0001/" (a host or scheme is never accepted).',
+        };
+    }
+    const metadataPath = metadataPathOf(servicePath);
+    const fetchDoc = deps?.fetchDoc ??
+        (async (p) => {
+            const { getConnection } = await import('../../sap/connection-manager.js');
+            const cfg = await loadConfig();
+            const sys = cfg.sap[ctx.sapAlias];
+            if (!sys)
+                throw new Error(`no SAP alias "${ctx.sapAlias}" is configured`);
+            const conn = await getConnection(ctx.sapAlias, sys);
+            const resp = await conn.get(p, 'application/xml');
+            return { status: resp.status, body: resp.body };
+        });
+    let main;
+    try {
+        main = await fetchDoc(metadataPath);
+    }
+    catch (err) {
+        return {
+            error: `could not fetch ${metadataPath} — ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (main.status < 200 || main.status >= 300) {
+        return {
+            error: `${metadataPath} → HTTP ${main.status}. Is the service binding published, and is the path the ` +
+                'binding\'s service URL?',
+        };
+    }
+    if (!/<edmx:Edmx[\s>]/.test(main.body) || !main.body.includes('</edmx:Edmx>')) {
+        return {
+            error: `${metadataPath} answered HTTP ${main.status} but the body is not an OData $metadata document (no complete <edmx:Edmx>).`,
+        };
+    }
+    // Every referenced value-help document, once each, in document order. A
+    // failure is DATA (the value-help-unreachable flag), never a thrown error.
+    const referenceDocs = new Map();
+    const referenceFailures = new Map();
+    try {
+        const urls = [...new Set(readValueListReferences(main.body).flatMap((r) => r.urls))];
+        for (const url of urls) {
+            try {
+                const resp = await fetchDoc(resolveReferenceUrl(metadataPath, url));
+                if (resp.status >= 200 && resp.status < 300)
+                    referenceDocs.set(url, resp.body);
+                else
+                    referenceFailures.set(url, resp.status);
+            }
+            catch {
+                referenceFailures.set(url, 0); // no HTTP answer at all
+            }
+        }
+    }
+    catch (err) {
+        return {
+            error: `${metadataPath} could not be parsed — ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    try {
+        const audit = auditMetadata({
+            servicePath: metadataPath,
+            mainXml: main.body,
+            referenceDocs,
+            referenceFailures,
+            ...(args.localAnnotationsXml ? { localAnnotationsXml: args.localAnnotationsXml } : {}),
+            ...(args.entitySet ? { entitySet: args.entitySet } : {}),
+        });
+        return { audit };
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+}
+export async function fioriMetadataAuditHandler(args, ctx, deps) {
+    const r = await fetchMetadataAudit(args, ctx, deps);
+    if ('error' in r)
+        return { content: `error: ${r.error}`, is_error: true };
+    return { content: JSON.stringify(r.audit, null, 2) };
+}
 // ─────────────────────────────── registration ─────────────────────────────
 registerTool({
     name: 'fiori_scaffold',
@@ -444,7 +864,7 @@ registerTool({
             servicePath: { type: 'string', description: 'Relative OData service path, e.g. "/sap/opu/odata4/zso/srv/".' },
             serviceVersion: { type: 'string', enum: ['2.0', '4.0'], description: 'OData version of the primary service. Default "4.0".' },
             typescript: { type: 'boolean', description: 'Generate a TypeScript app. Default false.' },
-            ui5Version: { type: 'string', description: 'UI5 version for manifest minUI5Version + preview. Default 1.120.0. Do not go below 1.84.' },
+            ui5Version: { type: 'string', description: `UI5 version for manifest minUI5Version + preview. Default ${PINNED_UI5_VERSION} (an exact hosted patch — SAP removes old patches from the UI5 CDN). Do not go below 1.84.` },
         },
         required: ['basePath', 'appId'],
     },
@@ -532,7 +952,12 @@ registerTool({
             metadata: { type: 'string', description: 'OPTIONAL service $metadata (EDMX XML). The writer does not need it; pass only if you already have it.' },
             client: { type: 'string', description: 'OPTIONAL SAP client (e.g. "100"), written to the manifest for the proxy layer.' },
             mainEntity: { type: 'string', description: 'The entity set to bind, e.g. "Course".' },
-            ui5Version: { type: 'string', description: 'UI5 version. Default 1.120.0.' },
+            ui5Version: { type: 'string', description: `UI5 version. Default ${PINNED_UI5_VERSION} (an exact hosted patch — SAP removes old patches from the UI5 CDN).` },
+            backend: {
+                type: 'string',
+                enum: ['cap'],
+                description: 'CAP apps only: "cap" for an app served inside the CAP server by cds-plugin-ui5 (leaves out the fiori-tools-preview middleware, which loads a second CAP copy into the server and crashes draft saves). Omit for ABAP backends.',
+            },
             localAnnotations: {
                 type: 'object',
                 description: 'OPTIONAL local annotations.xml for a FOREIGN OData service you do NOT own (cannot add backend @UI). ' +
@@ -605,10 +1030,21 @@ registerTool({
     input_schema: {
         type: 'object',
         properties: {
+            capUser: {
+                type: 'string',
+                description: "CAP apps only: the mock user for CAP's development login when the service needs one (e.g. \"alice\").",
+            },
             appUrl: {
                 type: 'string',
                 description: 'The LOCAL AUTHENTICATED PREVIEW URL (the `npm run start` / `fiori run` URL that proxies to the ' +
-                    'real backend with your auth), e.g. "http://localhost:8080/index.html". NOT the deployed BSP URL.',
+                    'real backend with your auth), e.g. "http://localhost:8080/index.html". NOT the deployed BSP URL. ' +
+                    'Not needed when previewId is given.',
+            },
+            previewId: {
+                type: 'string',
+                description: 'PREFERRED: the id returned by fiori_preview action "start". Resolves to the URL that preview is ' +
+                    'actually serving, so there is no guessing between :8080 and :8081. When both previewId and appUrl ' +
+                    'are given, previewId wins and the result says so in its warnings.',
             },
             appDir: {
                 type: 'string',
@@ -635,11 +1071,183 @@ registerTool({
                 description: 'Post-boot interactions to exercise (press/route). Declared for Track 3; unused in Track 2.',
                 items: { type: 'object' },
             },
+            metadataAudit: {
+                type: 'object',
+                description: 'OPTIONAL: the result of fiori_metadata_audit for the list’s entity set, passed through as-is. When ' +
+                    'given, Fiori Elements mode DERIVES expectedColumns from its UI.LineItem labels (a model-supplied ' +
+                    'expectedColumns is ignored, with a warning) and adds two checks: "labels" (every column rendered under ' +
+                    'its label; no bare technical name as a header) and "no-raw-codes" (every coded column shows its text, ' +
+                    'not the raw code — compared row by row, first 20 rows, against the backend read from inside the page).',
+            },
         },
-        required: ['appUrl'],
+        // L1-6: `previewId` is an equal alternative to `appUrl`, so neither is
+        // schema-required. The handler still returns the SAME "appUrl is required"
+        // error when neither is given — unchanged for every existing caller.
+        required: [],
     },
     handler: fioriRenderSmokeHandler,
 });
+registerTool({
+    name: 'fiori_draft_smoke',
+    description: 'Draft round trip through a Fiori Elements V4 app on its LOCAL preview — a SAP WRITE. It creates one test row ' +
+        "through the app's own OData service, marked CSP-SMOKE-<runId> in markerField, drives the app like a user " +
+        '(open the row, Edit, change one field THROUGH ITS VALUE HELP, Save; then Edit, change, Discard) and deletes the ' +
+        "row and any draft of it at the end, even when a step fails. At the start it also removes other runs' leftover " +
+        "CSP-SMOKE- rows and drafts (by the prefix, not only this run's id — fine on a development system) and nothing " +
+        "else. It fetches and audits the service's $metadata itself — it never takes an audit from the call. Checks: " +
+        'sweep, setup, rows, value-help (the value ' +
+        'help opens and lists at least one entry — dropdown or dialog), draft-save (the backend has the new value, the ' +
+        'list shows its text), draft-discard (the saved value is back, no draft left), no-error-dialogs, odata (the ' +
+        'INNER $batch statuses) and cleanup. The activation action is the one Common.DraftRoot names in the fetched $metadata — ' +
+        'never a guessed name. REFUSED before anything is sent unless the service binding AND definition are in the ' +
+        'customer namespace (Z*/Y*) and the app URL is a local preview (localhost / 127.x). NEEDS APPROVAL: call ' +
+        'request_approval with a change {op:"modify", object:"<SERVICE BINDING NAME>", type:"DATA"} first and pass the ' +
+        'id as approval_id — one approval runs one smoke. Flag-gated (enabled with local_build); needs a configured SAP ' +
+        'alias and a running preview (fiori_preview).',
+    isMutating: true,
+    // CAP path (2026-09-25): usable without an SAP connection (standalone CAP work);
+    // the SAP path still needs one and fails cleanly without it (no alias configured).
+    requiresSap: false,
+    category: 'fiori',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            previewId: { type: 'string', description: 'PREFERRED: the id from fiori_preview "start". Wins over appUrl.' },
+            appUrl: {
+                type: 'string',
+                description: 'The LOCAL preview URL (localhost / 127.x only), e.g. the fiori_preview url. Never a deployed app.',
+            },
+            servicePath: {
+                type: 'string',
+                description: 'The OData V4 service path of the app, e.g. "/sap/opu/odata4/sap/zui_x_o4/srvd/sap/zui_x/0001/". The smoke ' +
+                    'fetches and audits its $metadata itself (keys, mandatory fields, value helps, the Common.DraftRoot actions).',
+            },
+            entitySet: { type: 'string', description: 'The draft root entity set. Default: as fiori_metadata_audit picks it.' },
+            localAnnotationsXml: {
+                type: 'string',
+                description: "Optional: the app's local annotations EDMX content, merged over the service (as in fiori_metadata_audit).",
+            },
+            markerField: {
+                type: 'string',
+                description: 'A writable text property of the entity (e.g. "Note") that holds the CSP-SMOKE-<runId> marker (29 characters).',
+            },
+            editField: {
+                type: 'string',
+                description: 'The property changed through its value help. Default: the first rendered coded field that has one.',
+            },
+            backend: {
+                type: 'string',
+                enum: ['sap', 'cap'],
+                description: 'Optional: "cap" for a local CAP app served by cds watch (servicePath like /odata/v4/<service>/, appUrl on that ' +
+                    'same CAP server; the tool refuses unless the server proves it is the CAP development server). Default: an SAP ' +
+                    'OData V4 service (Z*/Y*).',
+            },
+            capUser: {
+                type: 'string',
+                description: 'CAP only: the mock user for the CAP development login when the service needs one (e.g. "alice").',
+            },
+            slowMo: {
+                type: 'number',
+                description: 'Optional: slow each browser step by this many milliseconds, to record the run on camera. Default 0.',
+            },
+            headless: {
+                type: 'boolean',
+                description: 'Optional: false shows the browser window, to record the run on camera. Default true.',
+            },
+            approval_id: {
+                type: 'string',
+                description: 'From request_approval: change {op:"modify", object:"<SERVICE BINDING NAME>", type:"DATA"}.',
+            },
+        },
+        required: ['servicePath', 'markerField', 'approval_id'],
+    },
+    handler: fioriDraftSmokeHandler,
+});
+registerTool({
+    name: 'fiori_preview',
+    description: 'Preview lifecycle for a scaffolded Fiori app — the thing every browser check depends on. ' +
+        'action "start" starts a local preview server for the given app directory. The SAP login for the ' +
+        'alias is passed to that process through its environment when the app\'s ui5 config names a backend ' +
+        '(an app with no backend url starts without it) — never on the command line and never in a file. ' +
+        'It picks a free port, runs the app\'s own "npm run start" in its directory, and waits until ' +
+        'BOTH the app AND its OData $metadata answer THROUGH the preview proxy before reporting ready (a ' +
+        'port that merely opened is never called ready). The certificate and the login travel as ' +
+        'NODE_EXTRA_CA_CERTS / FIORI_TOOLS_USER / FIORI_TOOLS_PASSWORD, read from the OS keychain. The ' +
+        'start script itself must be a plain "fiori run" or "ui5 serve" — anything else is refused rather ' +
+        'than handed the login; so is an app with a "prestart"/"poststart" script, an .npmrc that sets ' +
+        'script-shell or node-options, or a ui5.yaml whose backend url is not the alias\'s own host and port. ' +
+        'Certificate verification is never turned off: an alias with checking off ' +
+        'still starts, and the result says so on its own line. ONE preview per app directory: a second ' +
+        'start for the same directory and alias REUSES the live one instead of leaving a second server on ' +
+        'another port; a start for a DIFFERENT alias or entry page stops the old one first and says so. A ' +
+        'start that never becomes ready kills the whole process tree and returns the child\'s last output ' +
+        'with a classified reason (refused / app-not-served / metadata-not-served / timeout). action "stop" ' +
+        'kills the tree and reports whether the port actually closed; action "list" shows what is running. ' +
+        'Pass the returned previewId to fiori_render_smoke instead of a hand-typed appUrl. The app\'s own ' +
+        'start script may open a browser window. A proxy configured in the environment is NOT inherited by ' +
+        'the preview, so a machine that can only reach the UI5 CDN through one may need it in the app\'s own ' +
+        'configuration. Flag-gated (enabled with local_build); needs a configured SAP alias, and a stored ' +
+        'password for it when the app names a backend url.',
+    isMutating: true,
+    requiresSap: true,
+    category: 'fiori',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: ['start', 'stop', 'list'],
+                description: 'start a preview for an app dir, stop one by previewId, or list the running ones. Default "start".',
+            },
+            appDir: { type: 'string', description: 'action "start": the scaffolded app root (relative to the project root, sandboxed).' },
+            alias: { type: 'string', description: 'SAP alias whose CA + credentials the preview proxy uses. Defaults to the session alias.' },
+            servicePath: {
+                type: 'string',
+                description: 'OData service path, e.g. "/sap/opu/odata4/sap/zc_x/srvd/sap/zc_x/0001/". Used for the $metadata readiness ' +
+                    'leg — the one that proves the proxy really reached the backend. Omit only for an app with no backend service; ' +
+                    'such an app (no backend url in its ui5.yaml) starts WITHOUT the SAP login and without the approval prompt.',
+            },
+            previewId: { type: 'string', description: 'action "stop": which preview to stop.' },
+            entryFile: { type: 'string', description: 'Preview entry page. Default: the page the app’s own npm start opens (the FLP sandbox for scaffolded apps — Fiori Elements V4 needs the shell), else "index.html".' },
+            budgetMs: { type: 'number', description: 'How long to wait for readiness. Default 120000 (a cold UI5 CDN load is slow).' },
+        },
+        required: [],
+    },
+    // R1-6 (owner decision 2026-09-21): a start hands the stored SAP login to
+    // the preview process — dispatchTool asks a human once per session per alias.
+    // Round 2b (owner ruling): NO prompt only when app-guard's loginNeed says
+    // 'none' (no backend url). Any doubt — no appDir, an escaping appDir, no
+    // package.json, an unreadable/uncertain/outside config, anything thrown —
+    // returns the handover, i.e. PROMPTS. The handler re-runs the decision.
+    credentialHandover: async (args, ctx) => {
+        if ((args.action ?? 'start') !== 'start')
+            return null;
+        const alias = args.alias ?? ctx.sapAlias;
+        const handover = {
+            alias,
+            summary: `The SAP login for alias ${alias} is passed to the preview process through its environment ` +
+                `("npm run start" in ${args.appDir ?? '(no appDir given)'}). Asked once per session for each alias.`,
+        };
+        try {
+            if (!args.appDir)
+                return handover;
+            const resolved = safeDir(ctx, args.appDir);
+            if ('error' in resolved)
+                return handover;
+            const startScript = await readStartScript(resolved.abs);
+            if (startScript === null)
+                return handover;
+            const need = await loginNeed(resolved.abs, startScript, alias);
+            return 'need' in need && need.need === 'none' ? null : handover;
+        }
+        catch {
+            return handover;
+        }
+    },
+    handler: fioriPreviewHandler,
+});
 registerTool({
     name: 'fiori_sample_search',
     description: 'Search the vendored UI5 Demo Kit sample corpus (grounding for the freestyle composer): free-text ' +
@@ -681,3 +1289,39 @@ registerTool({
     },
     handler: fioriSampleGetHandler,
 });
+registerTool({
+    name: 'fiori_metadata_audit',
+    description: 'Machine truth about a published OData V4 service, read from the system itself. Fetches the service\'s ' +
+        '$metadata and every value-help document it references (Common.ValueListReferences — a RAP V4 service ' +
+        'keeps its value helps in separate documents, not inline), and returns JSON for one entity set: per ' +
+        'property the label and where it comes from, the text path and text arrangement, the value help ' +
+        '(inline / references / fixed-values dropdown, its collection, key and text), whether the field is a ' +
+        'coded value; plus the fully-qualified draft action names, the line item, selection fields, field ' +
+        'groups, header info and create/update/delete capabilities. It also returns flags, each with a ' +
+        'one-sentence fix: no-label, coded-without-text, coded-without-value-help, value-help-unreachable. ' +
+        'Use it so no downstream check has to trust a model-supplied string — never hardcode a draft action ' +
+        'name or assume a label. servicePath is the binding\'s service URL on the configured system, starting ' +
+        'with /sap/ (with or without the trailing $metadata). entitySet defaults to the first set with a line ' +
+        'item, else the draft root. localAnnotationsXml (optional) is the app\'s local annotation file content, ' +
+        'merged over the service. Read-only; flag-gated (enabled with local_build); needs a configured SAP alias.',
+    isMutating: false,
+    requiresSap: true,
+    category: 'fiori',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            servicePath: {
+                type: 'string',
+                description: 'OData V4 service path, e.g. "/sap/opu/odata4/sap/zui_x_o4/srvd/sap/zui_x/0001/" — "$metadata" is appended when missing.',
+            },
+            entitySet: { type: 'string', description: 'Entity set to audit. Default: the first with UI.LineItem, else the draft root.' },
+            localAnnotationsXml: {
+                type: 'string',
+                description: 'Optional: the content of the app\'s local annotations EDMX (webapp/annotations/*.xml), merged over the service.',
+            },
+        },
+        required: ['servicePath'],
+    },
+    handler: fioriMetadataAuditHandler,
+});