@cspeach/cli 1.1.18 → 1.1.19

package/test-harness/fe-draft/routes.ts

@@ -0,0 +1,224 @@
+// cspeach-cli/test-harness/fe-draft/routes.ts
+//
+// L1-2b — the PURE half of the offline Fiori Elements harness.
+//
+// The harness serves a scaffolded app the way `fiori run` serves it for a real
+// preview (see the scaffold's ui5.yaml): `/resources` + `/test-resources` come
+// from the UI5 CDN, `/sap/...` goes to "the backend", everything else is a file
+// under `webapp/`. Here "the backend" is @sap-ux/fe-mockserver reading the
+// CAPTURED $metadata in place. No socket, no network, no mockserver import in
+// this file — it is unit-tested in `pnpm test` (test/unit/fe-harness-routes.test.ts).
+import * as path from 'node:path';
+import { PINNED_UI5_VERSION } from '../../src/tools/fiori/ui5-version.js';
+
+/** The origin fiori-tools-proxy's `ui5:` block points at in every scaffolded ui5.yaml. */
+export const UI5_CDN_ORIGIN = 'https://ui5.sap.com';
+
+export type HarnessRoute =
+  | { kind: 'ui5'; upstream: string }
+  | { kind: 'mock' }
+  /** The UI5 flexibility (LREP) service a real ABAP backend answers; the mockserver does not. */
+  | { kind: 'flex'; what: 'settings' | 'data' }
+  | { kind: 'static'; file: string }
+  | { kind: 'reject'; status: 400 | 404; reason: string };
+
+export interface RouteOptions {
+  /** Absolute path of the app's `webapp/` folder. */
+  webappDir: string;
+  /** UI5 version the app was scaffolded for (manifest minUI5Version). */
+  ui5Version: string;
+}
+
+const VERSION = /^\d+\.\d+\.\d+$/;
+
+/** Decide where one browser request goes. Pure. */
+export function routeRequest(rawUrl: string, opts: RouteOptions): HarnessRoute {
+  if (!VERSION.test(opts.ui5Version)) {
+    throw new Error(`UI5 version must be a plain x.y.z, got "${opts.ui5Version}"`);
+  }
+  const q = rawUrl.indexOf('?');
+  const rawPath = q === -1 ? rawUrl : rawUrl.slice(0, q);
+  const query = q === -1 ? '' : rawUrl.slice(q);
+
+  if (rawPath.startsWith('/resources/') || rawPath.startsWith('/test-resources/')) {
+    return { kind: 'ui5', upstream: `${UI5_CDN_ORIGIN}/${opts.ui5Version}${rawPath}${query}` };
+  }
+  if (rawPath === '/sap/bc/lrep/flex/settings') return { kind: 'flex', what: 'settings' };
+  if (rawPath.startsWith('/sap/bc/lrep/flex/data/')) return { kind: 'flex', what: 'data' };
+  if (rawPath.startsWith('/sap/')) return { kind: 'mock' };
+
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(rawPath);
+  } catch {
+    return { kind: 'reject', status: 400, reason: 'malformed percent-encoding' };
+  }
+  const rel = decoded === '/' ? 'index.html' : decoded.replace(/^\/+/, '');
+  const root = path.resolve(opts.webappDir);
+  const file = path.resolve(root, rel);
+  if (file !== root && !file.startsWith(root + path.sep)) {
+    return { kind: 'reject', status: 400, reason: 'path leaves webapp/' };
+  }
+  return { kind: 'static', file };
+}
+
+export interface MockServiceInput {
+  /** Service URL path as the manifest names it, WITHOUT the trailing slash. */
+  urlPath: string;
+  /** Absolute path of a captured `$metadata` document — read in place, never copied. */
+  metadataPath: string;
+  /** Where the mockserver may look for / keep mock data. Never the fixture folder. */
+  mockdataPath: string;
+}
+
+/**
+ * The fe-mockserver configuration for one captured service. `mockdataPath`
+ * must not be the folder that holds the captured metadata: the mockserver
+ * defaults to that folder, and the fixture scrub guard fails on any file there
+ * it does not know.
+ */
+export function mockServerConfig(input: MockServiceInput): {
+  services: Array<MockServiceInput & { generateMockData: true }>;
+  annotations: never[];
+} {
+  if (input.urlPath.endsWith('/')) {
+    throw new Error(`urlPath must not end with a trailing slash: ${input.urlPath}`);
+  }
+  if (path.resolve(input.mockdataPath) === path.resolve(path.dirname(input.metadataPath))) {
+    throw new Error('mockdataPath must not be the fixture folder that holds the captured metadata');
+  }
+  return {
+    services: [
+      {
+        urlPath: input.urlPath,
+        metadataPath: input.metadataPath,
+        mockdataPath: input.mockdataPath,
+        generateMockData: true,
+      },
+    ],
+    annotations: [],
+  };
+}
+
+export interface AppFacts {
+  appId: string;
+  /** mainService uri without its trailing slash. */
+  servicePath: string;
+  ui5Version: string;
+}
+
+/** Read what the harness needs from a scaffolded manifest.json. */
+export function appFactsFromManifest(manifest: unknown): AppFacts {
+  const m = manifest as {
+    'sap.app'?: { id?: string; dataSources?: Record<string, { uri?: string }> };
+    'sap.ui5'?: { dependencies?: { minUI5Version?: string } };
+  };
+  const uri = m['sap.app']?.dataSources?.mainService?.uri;
+  if (!uri) throw new Error('manifest.json has no sap.app.dataSources.mainService.uri');
+  const ui5Version = m['sap.ui5']?.dependencies?.minUI5Version;
+  if (!ui5Version) throw new Error('manifest.json has no sap.ui5.dependencies.minUI5Version');
+  return {
+    appId: m['sap.app']?.id ?? '',
+    servicePath: uri.replace(/\/+$/, ''),
+    ui5Version,
+  };
+}
+
+/** The part of https://ui5.sap.com/neo-app.json the harness reads: one route per hosted version. */
+export interface NeoApp {
+  routes?: Array<{ path?: string }>;
+}
+
+function hostedVersions(neoApp: NeoApp): string[] {
+  return (neoApp.routes ?? [])
+    .map((r) => (r.path ?? '').replace(/^\//, ''))
+    .filter((v) => VERSION.test(v));
+}
+
+/** Is this exact x.y.z on the CDN? (SAP retires old patches; only some stay hosted.) */
+export function isHosted(version: string, neoApp: NeoApp): boolean {
+  return hostedVersions(neoApp).includes(version);
+}
+
+/** The highest hosted patch of `minor` ("1.120" → "1.120.51"), or undefined. */
+export function latestHostedPatch(minor: string, neoApp: NeoApp): string | undefined {
+  const patches = hostedVersions(neoApp)
+    .filter((v) => v.startsWith(`${minor}.`) && v.split('.').length === 3)
+    .map((v) => ({ v, p: Number(v.split('.')[2]) }))
+    .sort((a, b) => b.p - a.p);
+  return patches[0]?.v;
+}
+
+/**
+ * The page the scaffold's `npm start` opens (`fiori run --open "<url>"`) — the
+ * FLP sandbox entry a developer sees. The harness serves the same page.
+ */
+export function openUrlFromStartScript(script: string): string {
+  const m = /--open\s+"([^"]+)"/.exec(script) ?? /--open\s+(\S+)/.exec(script);
+  if (!m) throw new Error(`start script has no --open "<url>": ${script}`);
+  return m[1]!;
+}
+
+/**
+ * THE one place the harness's UI5 versions are pinned. Never "latest": a
+ * deployed app runs on the customer system's own UI5, and Fiori Elements DOM
+ * changes between versions, so a run must say which version it proved.
+ *
+ * - newest: PINNED_UI5_VERSION — the SAME constant the scaffolds write as their
+ *   default (src/tools/fiori/ui5-version.ts; 1.120 ≈ S/4HANA 2023).
+ * - oldest: the newest hosted patch of 1.84 (≈ S/4HANA 2020), the oldest FE V4
+ *   release the owner named. Which release is "oldest supported" is his call.
+ *
+ * SAP retires old patches from the CDN; when a pin disappears the e2e run fails
+ * with a message pointing here. Bump the patch, never the policy.
+ */
+export const HARNESS_UI5_VERSIONS = { newest: PINNED_UI5_VERSION, oldest: '1.84.61' } as const;
+
+/**
+ * The long-term UI5 line of every S/4HANA release we support (2020 → 1.84,
+ * 2021 → 1.96, 2022 → 1.108, 2023 → 1.120, 2025 → 1.136). Customers run their system's own
+ * UI5, so the generated apps and the smoke checks must work on each of them.
+ */
+export const SUPPORTED_UI5_LINES = ['1.84', '1.96', '1.108', '1.120', '1.136'] as const;
+
+/** One pinned, hosted patch per supported line (CSP_HARNESS_UI5=all). Bump patches, never the policy. */
+const PINNED_LINE_PATCHES: Record<(typeof SUPPORTED_UI5_LINES)[number], string> = {
+  '1.84': HARNESS_UI5_VERSIONS.oldest,
+  '1.96': '1.96.50',
+  '1.108': '1.108.56',
+  '1.120': HARNESS_UI5_VERSIONS.newest,
+  '1.136': '1.136.22',
+};
+
+/**
+ * The newest HOSTED patch of each line (CSP_HARNESS_UI5=latest — the weekly
+ * run). Throws when a supported line is no longer on the CDN, so a retired line
+ * is a loud decision, not a silently shorter matrix.
+ */
+export function latestPatches(lines: readonly string[], neoApp: NeoApp): string[] {
+  return lines.map((line) => {
+    const v = latestHostedPatch(line, neoApp);
+    if (!v) throw new Error(`UI5 line ${line} is no longer hosted on the CDN — update SUPPORTED_UI5_LINES (test-harness/fe-draft/routes.ts)`);
+    return v;
+  });
+}
+
+/**
+ * Which pinned version(s) a smoke-e2e run uses, from `CSP_HARNESS_UI5`:
+ * unset/empty → newest; `newest` | `oldest` | `both`; or a comma list of x.y.z.
+ */
+export function selectUi5Versions(envValue: string | undefined): string[] {
+  const raw = (envValue ?? '').trim();
+  if (raw === '' || raw === 'newest') return [HARNESS_UI5_VERSIONS.newest];
+  if (raw === 'oldest') return [HARNESS_UI5_VERSIONS.oldest];
+  if (raw === 'both') return [HARNESS_UI5_VERSIONS.newest, HARNESS_UI5_VERSIONS.oldest];
+  if (raw === 'all') return SUPPORTED_UI5_LINES.map((line) => PINNED_LINE_PATCHES[line]);
+  const list = raw.split(',').map((v) => v.trim());
+  const bad = list.filter((v) => !VERSION.test(v));
+  if (bad.length > 0) {
+    throw new Error(
+      `CSP_HARNESS_UI5 takes newest | oldest | both | all | latest | a comma list of x.y.z — not: ${bad.join(', ')}`,
+    );
+  }
+  return list;
+}

package/test-harness/fe-draft/routes.unit.test.ts

@@ -0,0 +1,45 @@
+/**
+ * The UI5 version matrix the offline FE harness proves (2026-09-24). Each S/4
+ * release ships one long-term UI5 line; generated apps and our smoke checks
+ * must work on every supported line, not just the one we develop on.
+ *   all    → the pinned patch of every supported line (reproducible)
+ *   latest → the newest HOSTED patch of every line (the weekly run: catches a
+ *            UI5 patch that breaks us before a customer hits it)
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  selectUi5Versions,
+  latestPatches,
+  SUPPORTED_UI5_LINES,
+  HARNESS_UI5_VERSIONS,
+} from './routes.js';
+
+const neo = (paths: string[]) => ({ routes: paths.map((p) => ({ path: `/${p}` })) });
+
+describe('UI5 matrix', () => {
+  it('supports the long-term line of every S/4 release from 2020 (2025 = 1.136)', () => {
+    expect(SUPPORTED_UI5_LINES).toEqual(['1.84', '1.96', '1.108', '1.120', '1.136']);
+  });
+
+  it('`all` runs one pinned patch per supported line, oldest and newest included', () => {
+    const v = selectUi5Versions('all');
+    expect(v.map((x) => x.split('.').slice(0, 2).join('.'))).toEqual([...SUPPORTED_UI5_LINES]);
+    expect(v).toContain(HARNESS_UI5_VERSIONS.oldest);
+    expect(v).toContain(HARNESS_UI5_VERSIONS.newest);
+  });
+
+  it('existing selections keep working', () => {
+    expect(selectUi5Versions(undefined)).toEqual([HARNESS_UI5_VERSIONS.newest]);
+    expect(selectUi5Versions('both')).toEqual([HARNESS_UI5_VERSIONS.newest, HARNESS_UI5_VERSIONS.oldest]);
+    expect(selectUi5Versions('1.96.50')).toEqual(['1.96.50']);
+  });
+
+  it('latestPatches picks the highest hosted patch of each line', () => {
+    const n = neo(['1.84.61', '1.84.62', '1.96.49', '1.96.50', '1.108.56', '1.120.51', '1.120.9']);
+    expect(latestPatches(['1.84', '1.96', '1.108', '1.120'], n)).toEqual(['1.84.62', '1.96.50', '1.108.56', '1.120.51']);
+  });
+
+  it('latestPatches fails loudly when a supported line is no longer hosted', () => {
+    expect(() => latestPatches(['1.84', '1.96'], neo(['1.84.62']))).toThrow(/1\.96/);
+  });
+});

package/test-harness/fe-draft/server.ts

@@ -0,0 +1,225 @@
+// cspeach-cli/test-harness/fe-draft/server.ts
+//
+// L1-2b — the offline Fiori Elements harness server.
+//
+// One loopback HTTP server per app, shaped like the scaffold's own ui5.yaml
+// (the `fiori run` preview): `/resources` + `/test-resources` → the UI5 CDN,
+// `/sap/...` → @sap-ux/fe-mockserver (in place of the SAP backend), everything
+// else → a file under `webapp/`. The mockserver reads the CAPTURED `$metadata`
+// where it sits in `src/tools/fiori/__tests__/fixtures/metadata/` — nothing is
+// copied, nothing in that folder is written.
+//
+// Test-only code. It imports a devDependency and lives outside `src/`, so it
+// never reaches `dist/`. The only network it opens is to UI5_CDN_ORIGIN.
+import * as http from 'node:http';
+import * as https from 'node:https';
+import { readFile, writeFile, mkdtemp, mkdir, rm } from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import type { AddressInfo } from 'node:net';
+import FEMiddleware from '@sap-ux/ui5-middleware-fe-mockserver';
+import manifestEnhancer from '@ui5/builder/processors/manifestEnhancer';
+import fsInterface from '@ui5/fs/fsInterface';
+import { createAdapter } from '@ui5/fs/resourceFactory';
+import {
+  routeRequest,
+  mockServerConfig,
+  appFactsFromManifest,
+  UI5_CDN_ORIGIN,
+  type NeoApp,
+} from './routes.js';
+
+export interface HarnessServer {
+  /** e.g. http://127.0.0.1:53211 */
+  origin: string;
+  /** Every `/sap/...` request the mockserver answered: method, url, status. */
+  mockLog: Array<{ method: string; url: string; status: number }>;
+  close(): Promise<void>;
+}
+
+const CONTENT_TYPES: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'application/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.properties': 'text/plain; charset=utf-8',
+  '.xml': 'application/xml; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+};
+
+const EMPTY_FLEX_DATA = {
+  changes: [],
+  compVariants: [],
+  variants: [],
+  variantChanges: [],
+  variantDependentControlChanges: [],
+  variantManagementChanges: [],
+  ui2personalization: {},
+};
+
+/** UI5 CDN answers, kept for the life of the test process (the same files every boot). */
+const cdnCache = new Map<string, { status: number; headers: http.OutgoingHttpHeaders; body: Buffer }>();
+
+function fetchCdn(upstream: string): Promise<{ status: number; headers: http.OutgoingHttpHeaders; body: Buffer }> {
+  const hit = cdnCache.get(upstream);
+  if (hit) return Promise.resolve(hit);
+  return new Promise((resolve, reject) => {
+    const req = https.get(upstream, { timeout: 60_000 }, (res) => {
+      const chunks: Buffer[] = [];
+      res.on('data', (c: Buffer) => chunks.push(c));
+      res.on('end', () => {
+        const headers: http.OutgoingHttpHeaders = {};
+        if (res.headers['content-type']) headers['content-type'] = res.headers['content-type'];
+        const entry = { status: res.statusCode ?? 502, headers, body: Buffer.concat(chunks) };
+        if (entry.status === 200) cdnCache.set(upstream, entry);
+        resolve(entry);
+      });
+      res.on('error', reject);
+    });
+    req.on('timeout', () => req.destroy(new Error(`UI5 CDN timeout: ${upstream}`)));
+    req.on('error', reject);
+  });
+}
+
+/** The CDN's list of hosted versions (https://ui5.sap.com/neo-app.json). */
+export async function fetchNeoApp(): Promise<NeoApp> {
+  const r = await fetchCdn(`${UI5_CDN_ORIGIN}/neo-app.json`);
+  if (r.status !== 200) throw new Error(`UI5 CDN neo-app.json answered HTTP ${r.status}`);
+  return JSON.parse(r.body.toString('utf8')) as NeoApp;
+}
+
+export interface StartHarnessOptions {
+  /** Absolute path of the scaffolded app (the folder holding webapp/). */
+  appDir: string;
+  /** Absolute path of the captured $metadata the mockserver serves. */
+  metadataPath: string;
+  /**
+   * Fixed rows per entity set, written as <EntitySet>.json into the harness's own
+   * temp mock-data folder. Sets not named here get the mockserver's generated data
+   * (random, including HasDraftEntity — not a clean start for draft tests).
+   */
+  mockRows?: Record<string, unknown[]>;
+  /**
+   * L1-3: serve a VARIANT of the captured document — e.g. variants.ts
+   * withCodeTexts / withoutLabels. The transform runs in memory on the capture;
+   * the result is written into the harness's own temp folder, never next to the
+   * capture.
+   */
+  transformMetadata?: (xml: string) => string;
+  /** Receives exactly the document the mock backend serves (for auditMetadata). */
+  onServedMetadata?: (xml: string) => void;
+  /**
+   * L1-5b: fe-mockserver behaviour modules, written as <EntitySet>.js (CommonJS
+   * source) into the harness's temp mock-data folder next to the JSON rows —
+   * e.g. variants.ts inspectionLogHooks.
+   */
+  mockScripts?: Record<string, string>;
+}
+
+/**
+ * manifest.json exactly as `fiori run` serves it (2026-09-25). UI5 tooling 4's
+ * dev server passes every app manifest through the builder's manifestEnhancer,
+ * which adds supportedLocales from the i18n files the app ships. Serving the raw
+ * file hid a boot error every real preview shows ("fallback locale 'en' is not
+ * contained in the list of supported locales").
+ */
+export async function enhancedManifest(webappDir: string): Promise<string> {
+  const reader = createAdapter({ fsBasePath: webappDir, virBasePath: '/' });
+  const resource = await reader.byPath('/manifest.json');
+  if (!resource) throw new Error(`no manifest.json in ${webappDir}`);
+  await manifestEnhancer({ resources: [resource], fs: fsInterface(reader) });
+  return resource.getString();
+}
+
+/** Start the harness for one scaffolded app on 127.0.0.1, a free port. */
+export async function startHarness(opts: StartHarnessOptions): Promise<HarnessServer> {
+  const webappDir = path.join(opts.appDir, 'webapp');
+  const manifest = JSON.parse(await readFile(path.join(webappDir, 'manifest.json'), 'utf8'));
+  const facts = appFactsFromManifest(manifest);
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'csp-fe-harness-mock-'));
+  const mockdataPath = path.join(tempRoot, 'mockdata');
+  await mkdir(mockdataPath, { recursive: true });
+  let metadataPath = opts.metadataPath;
+  const captured = await readFile(opts.metadataPath, 'utf8');
+  const served = opts.transformMetadata ? opts.transformMetadata(captured) : captured;
+  if (opts.transformMetadata) {
+    await mkdir(path.join(tempRoot, 'metadata'), { recursive: true });
+    metadataPath = path.join(tempRoot, 'metadata', 'service.xml');
+    await writeFile(metadataPath, served, 'utf8');
+  }
+  opts.onServedMetadata?.(served);
+  for (const [set, rows] of Object.entries(opts.mockRows ?? {})) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(set)) throw new Error(`not an entity set name: ${set}`);
+    await writeFile(path.join(mockdataPath, `${set}.json`), JSON.stringify(rows));
+  }
+  for (const [set, source] of Object.entries(opts.mockScripts ?? {})) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(set)) throw new Error(`not an entity set name: ${set}`);
+    await writeFile(path.join(mockdataPath, `${set}.js`), source);
+  }
+
+  const configuration = mockServerConfig({
+    urlPath: facts.servicePath,
+    metadataPath,
+    mockdataPath,
+  });
+  // The UI5 tooling calls the middleware with its own project handles; the
+  // mockserver only asks them for a base path, and every path we pass is absolute.
+  const mockRouter = (await FEMiddleware({
+    options: { configuration },
+    resources: {},
+    middlewareUtil: { getProject: () => ({ getSourcePath: () => webappDir }) },
+  } as never)) as unknown as (req: http.IncomingMessage, res: http.ServerResponse, next: (err?: unknown) => void) => void;
+
+  const mockLog: HarnessServer['mockLog'] = [];
+
+  const server = http.createServer((req, res) => {
+    const route = routeRequest(req.url ?? '/', { webappDir, ui5Version: facts.ui5Version });
+    if (route.kind === 'reject') {
+      res.writeHead(route.status, { 'content-type': 'text/plain' }).end(route.reason);
+      return;
+    }
+    if (route.kind === 'flex') {
+      // What an ABAP backend with no key-user changes answers. The mockserver
+      // has no LREP; without this every boot logs two 404s a real preview does not.
+      const body = route.what === 'settings' ? {} : EMPTY_FLEX_DATA;
+      res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify(body));
+      return;
+    }
+    if (route.kind === 'mock') {
+      const url = req.url ?? '';
+      res.on('finish', () => mockLog.push({ method: req.method ?? '', url, status: res.statusCode }));
+      mockRouter(req, res, (err) => {
+        if (res.headersSent) return;
+        res.writeHead(err ? 500 : 404, { 'content-type': 'text/plain' }).end(err ? String(err) : 'not a mock route');
+      });
+      return;
+    }
+    if (route.kind === 'ui5') {
+      fetchCdn(route.upstream).then(
+        (r) => res.writeHead(r.status, r.headers).end(r.body),
+        (err: unknown) => res.writeHead(502, { 'content-type': 'text/plain' }).end(String(err)),
+      );
+      return;
+    }
+    const isManifest = route.file === path.resolve(webappDir, 'manifest.json');
+    (isManifest ? enhancedManifest(webappDir) : readFile(route.file)).then(
+      (body) =>
+        res
+          .writeHead(200, { 'content-type': CONTENT_TYPES[path.extname(route.file)] ?? 'application/octet-stream' })
+          .end(body),
+      () => res.writeHead(404, { 'content-type': 'text/plain' }).end('not found'),
+    );
+  });
+
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const { port } = server.address() as AddressInfo;
+
+  return {
+    origin: `http://127.0.0.1:${port}`,
+    mockLog,
+    close: async () => {
+      server.closeAllConnections();
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await rm(tempRoot, { recursive: true, force: true });
+    },
+  };
+}