@cspeach/cli 1.0.0 → 1.1.0

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

@@ -0,0 +1,248 @@
+// cspeach-cli/src/tools/fiori/samples/loader.ts
+//
+// Source loader for the fiori freestyle composer's grounding corpus (Track 3).
+//
+// Two paths, one interface:
+//   * VENDORED entries — sources are bundled at build time in the imported
+//     SAMPLE_SOURCES map (data/sources.generated.ts). We read them straight
+//     from memory: no fetch, no cache, no filesystem. NEVER read from a
+//     data/sources/ dir and NEVER readFileSync a shipped source (shipping
+//     rule A-C1 — the map is the only source of truth for vendored sources).
+//   * UN-VENDORED entries — sources are fetched lazily over the network via an
+//     injected `fetchText`, cached under ~/.cspeach/sample-cache/<name>/, and
+//     served from that cache on every subsequent load (zero further fetches).
+//
+// Un-vendored entries carry NO `files` list in index.json (only vendored ones
+// do). The authoritative file list is the sample's own manifest.json, which
+// every UI5 demokit sample publishes at `sap.ui5.config.sample.files`. So the
+// un-vendored path fetches manifest.json first, reads that list, then fetches
+// each declared file. If the sample can't be fetched (offline, 404, malformed
+// manifest), we throw a typed SampleFetchError whose message tells the model to
+// author from the fiori recipes catalog + sap-docs instead — sample grounding
+// is an optional boost and must never block composition.
+import { homedir } from 'node:os';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { SAMPLE_SOURCES } from './data/sources.generated.js';
+/**
+ * Raised when an entry name — or a manifest-declared file path — would escape
+ * the cache directory (a `..` segment or an absolute path). A security
+ * boundary: refused before any fetch or filesystem write.
+ */
+export class UnsafeSampleNameError extends Error {
+    sampleName;
+    constructor(sampleName, reason = `contains a ".." path segment`) {
+        super(`Refusing to load sample path "${sampleName}": ${reason} — ` +
+            `it could escape the sample cache directory.`);
+        this.sampleName = sampleName;
+        this.name = 'UnsafeSampleNameError';
+    }
+}
+/**
+ * Raised when an un-vendored sample cannot be retrieved (offline, HTTP error,
+ * or a manifest without a usable file list). The message is deliberately
+ * actionable for the model: fall back to authoring from recipes + sap-docs.
+ * Sample grounding is optional and must never block composition.
+ */
+export class SampleFetchError extends Error {
+    sampleName;
+    reason;
+    cause;
+    constructor(sampleName, reason, cause) {
+        super(`Could not retrieve UI5 sample "${sampleName}" (${reason}). ` +
+            `Author the UI from the fiori recipes catalog and sap-docs instead — ` +
+            `sample grounding is optional and never blocks composition.`);
+        this.sampleName = sampleName;
+        this.reason = reason;
+        this.cause = cause;
+        this.name = 'SampleFetchError';
+    }
+}
+const CACHE_ROOT_DEFAULT = () => join(homedir(), '.cspeach', 'sample-cache');
+/**
+ * Pinned raw-content root for lazy-fetching un-vendored samples.
+ *
+ * Index `sourceRef.rawBase` values are TARBALL-RELATIVE (e.g.
+ * `src/sap.f/test/sap/f/demokit/sample/AvatarGroup`) — Node `fetch` rejects a
+ * relative URL, so the loader prepends this absolute root before any network
+ * call. The tag (`1.120.14`) MUST match the corpus build tag pinned in
+ * scripts/build-sample-index.ts (`REF`); the sources were extracted from that
+ * exact OpenUI5 tree, so lazy-fetched files must come from the same ref.
+ */
+export const RAW_CONTENT_ROOT = 'https://raw.githubusercontent.com/SAP/openui5/1.120.14/';
+/**
+ * Resolve an index `rawBase` to an absolute fetch base (no trailing slash).
+ * Relative values get the pinned raw-content root prepended; already-absolute
+ * `http(s)://` values (future-proofing) pass through unchanged.
+ */
+export function resolveRawBase(rawBase) {
+    const trimmed = rawBase.replace(/\/+$/, '');
+    if (/^https?:\/\//i.test(trimmed))
+        return trimmed;
+    return RAW_CONTENT_ROOT + trimmed.replace(/^\/+/, '');
+}
+/** 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();
+}
+/** Split a name/relative path into segments on either slash flavour. */
+function segments(p) {
+    return p.split(/[\\/]+/).filter(Boolean);
+}
+/** Reject any name with a `..` (or `.`) traversal segment. */
+function assertSafeName(name) {
+    const segs = segments(name);
+    if (segs.length === 0 || segs.some((s) => s === '..' || s === '.')) {
+        throw new UnsafeSampleNameError(name);
+    }
+}
+/**
+ * Join `rel` under `base`, guaranteeing the result stays inside `base`.
+ * Belt-and-braces against a `..` or an absolute path slipping in via a
+ * manifest-declared file path.
+ */
+function safeJoin(base, rel) {
+    const target = resolve(base, rel);
+    const root = resolve(base);
+    if (target !== root && !target.startsWith(root + sep)) {
+        const reason = /^([a-zA-Z]:[\\/]|[\\/])/.test(rel)
+            ? 'is an absolute path'
+            : `contains a ".." path segment`;
+        throw new UnsafeSampleNameError(rel, reason);
+    }
+    return target;
+}
+/**
+ * The ordered, deduped file list for an un-vendored sample: manifest.json
+ * first, then the paths its manifest declares under sap.ui5.config.sample.files.
+ * Throws SampleFetchError if the manifest is unparseable or lists no files.
+ */
+function fileListFromManifest(manifestText, name) {
+    let parsed;
+    try {
+        parsed = JSON.parse(manifestText);
+    }
+    catch (e) {
+        throw new SampleFetchError(name, 'manifest.json is not valid JSON', e);
+    }
+    const files = parsed?.['sap.ui5']?.config?.sample?.files;
+    if (!Array.isArray(files) || files.length === 0) {
+        throw new SampleFetchError(name, 'manifest.json declares no sap.ui5.config.sample.files list');
+    }
+    const seen = new Set(['manifest.json']);
+    const out = ['manifest.json'];
+    for (const f of files) {
+        if (typeof f !== 'string' || seen.has(f))
+            continue;
+        seen.add(f);
+        out.push(f);
+    }
+    return out;
+}
+/**
+ * Read a fully-cached sample back from disk, or null if not cached.
+ *
+ * ANY failure — missing file, a torn/corrupt cached manifest.json (invalid
+ * JSON or no `files` key), an unreadable file, an unsafe path — is treated as a
+ * cache miss (returns null) so the caller refetches and self-heals. A corrupt
+ * cache must never poison the sample with a permanent, misleading error.
+ */
+function readFromCache(sampleDir, name) {
+    const manifestPath = join(sampleDir, 'manifest.json');
+    if (!existsSync(manifestPath))
+        return null;
+    try {
+        const manifestText = readFileSync(manifestPath, 'utf8');
+        const list = fileListFromManifest(manifestText, name);
+        const files = [];
+        for (const rel of list) {
+            const abs = safeJoin(sampleDir, rel);
+            if (!existsSync(abs))
+                return null; // partial cache → refetch
+            files.push({ path: rel, content: readFileSync(abs, 'utf8') });
+        }
+        return files;
+    }
+    catch {
+        return null; // corrupt/unreadable cache → refetch
+    }
+}
+/**
+ * Load a sample's source files.
+ *
+ * Vendored → from the bundled SAMPLE_SOURCES map (fromCache: false).
+ * Un-vendored → fetch-then-cache; second and later loads come from the on-disk
+ * cache with zero fetches (fromCache: true).
+ *
+ * @throws UnsafeSampleNameError if the entry name has a `..` traversal segment.
+ * @throws SampleFetchError if an un-vendored sample can't be fetched — with a
+ *         message steering the caller to recipes + sap-docs.
+ */
+export async function loadSampleSource(entry, deps) {
+    assertSafeName(entry.name);
+    // Vendored: read straight from the bundled map. No network, no cache.
+    if (entry.sourceRef.vendored) {
+        const bundle = SAMPLE_SOURCES[entry.name];
+        if (!bundle) {
+            throw new SampleFetchError(entry.name, 'marked vendored but absent from the bundled SAMPLE_SOURCES map');
+        }
+        const files = Object.keys(bundle)
+            .sort()
+            .map((path) => ({ path, content: bundle[path] }));
+        return { files, fromCache: false };
+    }
+    // Un-vendored: lazy fetch with an on-disk cache.
+    const cacheRoot = deps.cacheDir ?? CACHE_ROOT_DEFAULT();
+    const sampleDir = safeJoin(cacheRoot, entry.name);
+    const cached = readFromCache(sampleDir, entry.name);
+    if (cached)
+        return { files: cached, fromCache: true };
+    const rawBase = entry.sourceRef.rawBase;
+    if (!rawBase) {
+        throw new SampleFetchError(entry.name, 'un-vendored entry has no rawBase to fetch from');
+    }
+    const fetchText = deps.fetchText ?? defaultFetchText;
+    const base = resolveRawBase(rawBase);
+    let files;
+    try {
+        const manifestText = await fetchText(`${base}/manifest.json`);
+        const list = fileListFromManifest(manifestText, entry.name);
+        // Validate the WHOLE declared file list for containment up front, before
+        // any further fetch or write — an evil later path is refused here, not
+        // mid-persist after the network work is already done.
+        for (const rel of list)
+            safeJoin(sampleDir, rel);
+        files = [{ path: 'manifest.json', content: manifestText }];
+        for (const rel of list) {
+            if (rel === 'manifest.json')
+                continue;
+            const content = await fetchText(`${base}/${rel}`);
+            files.push({ path: rel, content });
+        }
+    }
+    catch (e) {
+        // A containment failure is a security refusal — surface it, don't mask it.
+        if (e instanceof UnsafeSampleNameError)
+            throw e;
+        if (e instanceof SampleFetchError)
+            throw e;
+        throw new SampleFetchError(entry.name, 'network fetch failed', e);
+    }
+    // Persist to cache. The cache is a best-effort optimization: if writing fails
+    // (EACCES, ENOTDIR, disk full) the fetched sources are already in memory, so
+    // we return them anyway rather than throw a raw fs error over a usable result.
+    try {
+        for (const f of files) {
+            const abs = safeJoin(sampleDir, f.path);
+            mkdirSync(dirname(abs), { recursive: true });
+            writeFileSync(abs, f.content, 'utf8');
+        }
+    }
+    catch {
+        /* cache write failed — sources are in memory; grounding proceeds uncached */
+    }
+    return { files, fromCache: false };
+}

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

@@ -0,0 +1,63 @@
+// cspeach-cli/src/tools/fiori/samples/search.ts
+//
+// Pure, deterministic keyword search over the vendored UI5 sample corpus
+// (built in Task 1). No I/O, no globals — the index is passed in. Task 4
+// wires this into the fiori tool; it stays trivially unit-testable here.
+// Scoring weights. Chosen so the three signals never interfere:
+//   exact control match  >>  any number of keyword hits  >>  library boost.
+const CONTROL_EXACT = 1000; // dominates everything
+const KEYWORD_HIT = 10; // per distinct query token that overlaps the entry
+const SAP_M_BOOST = 1; // < KEYWORD_HIT, so it only breaks keyword-count ties
+const DEFAULT_MAX = 5;
+/** Lowercase and split on any non-alphanumeric run; drop empties. */
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/i)
+        .filter(Boolean);
+}
+/**
+ * Search the sample index.
+ *
+ * Scoring: an exact `control` match dominates; then case-insensitive token
+ * overlap between the query text and each entry's keywords + name +
+ * description; then a small library boost for `sap.m`. Entries with no signal
+ * at all are excluded (so an unknown query returns []). Ties break
+ * deterministically by entry name (ascending).
+ */
+export function searchSamples(index, query) {
+    const queryTokens = [...new Set(tokenize(query.text ?? ''))];
+    const wantControl = query.control?.trim().toLowerCase();
+    const max = query.max ?? DEFAULT_MAX;
+    const hits = [];
+    for (const entry of index) {
+        let score = 0;
+        const controlExact = !!wantControl && entry.control.toLowerCase() === wantControl;
+        if (controlExact)
+            score += CONTROL_EXACT;
+        // Token overlap against keywords + name + description.
+        const bag = new Set(tokenize(`${entry.keywords.join(' ')} ${entry.name} ${entry.description}`));
+        let keywordHits = 0;
+        for (const t of queryTokens)
+            if (bag.has(t))
+                keywordHits += 1;
+        score += keywordHits * KEYWORD_HIT;
+        // Only entries with an actual signal are candidates — this is what makes
+        // an unknown query return empty rather than every sap.m entry.
+        if (!controlExact && keywordHits === 0)
+            continue;
+        if (entry.library === 'sap.m')
+            score += SAP_M_BOOST;
+        hits.push({ entry, score });
+    }
+    hits.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        // Locale-independent codepoint compare — a deterministic tie-break that
+        // does not vary with the host ICU locale/collation (CI vs dev machine).
+        const an = a.entry.name;
+        const bn = b.entry.name;
+        return an < bn ? -1 : an > bn ? 1 : 0;
+    });
+    return hits.slice(0, max);
+}

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

@@ -0,0 +1,2 @@
+// cspeach-cli/src/tools/fiori/samples/types.ts
+export {};

package/dist/tools/fiori/smoke/assertions.js

@@ -0,0 +1,74 @@
+// A failed HTTP response is only smoke-relevant when it is an OData call:
+// $metadata (model load), $batch (V4 read/write), or an entity-set request
+// under the gateway/odata4 path. An incidental non-OData 404 (favicon, a
+// analytics beacon) must NOT false-fail an otherwise healthy render.
+const ODATA_URL = /\$metadata|\$batch|\/sap\/opu\/odata|\/odata4?\//i;
+/** Boot check: the app loaded without throwing anything to the console. */
+export function checkBoot(consoleErrors) {
+    const ok = consoleErrors.length === 0;
+    return {
+        name: 'boot',
+        ok,
+        detail: ok
+            ? 'app booted with no console errors'
+            : `${consoleErrors.length} console error(s) during boot: ${consoleErrors.slice(0, 3).join(' | ')}`,
+    };
+}
+/** OData check: no 4xx/5xx on any $metadata / $batch / entity-set request. */
+export function checkOData(failedRequests) {
+    const bad = failedRequests.filter((r) => ODATA_URL.test(r.url));
+    const ok = bad.length === 0;
+    return {
+        name: 'odata',
+        ok,
+        detail: ok
+            ? 'no failed OData requests'
+            : `${bad.length} failed OData request(s): ${bad.map((r) => `${r.status} ${r.url}`).join(' | ')}`,
+    };
+}
+/** Columns check: every expected column is present in the header texts (case-insensitive). */
+export function checkColumns(headerTexts, expectedColumns) {
+    const present = new Set(headerTexts.map((h) => h.trim().toLowerCase()));
+    const missing = expectedColumns.filter((c) => !present.has(c.trim().toLowerCase()));
+    const ok = missing.length === 0;
+    return {
+        name: 'columns',
+        ok,
+        detail: ok
+            ? `all ${expectedColumns.length} expected column(s) present`
+            : `missing column(s): ${missing.join(', ')} (rendered: ${headerTexts.join(', ') || 'none'})`,
+    };
+}
+/** Rows check: 0 rows passes ONLY when the caller acknowledged an empty list. */
+export function checkRows(rowCount, allowEmptyRows) {
+    if (rowCount > 0) {
+        return { name: 'rows', ok: true, detail: `${rowCount} row(s) rendered` };
+    }
+    if (allowEmptyRows) {
+        return { name: 'rows', ok: true, detail: 'empty list acknowledged' };
+    }
+    return { name: 'rows', ok: false, detail: '0 rows rendered and allowEmptyRows was not set' };
+}
+/**
+ * Exercise check: every exercise ran without throwing and without emitting a new
+ * console error. A single throwing handler or a single new console error fails the
+ * whole smoke (dynamic A4). Vacuously passes on an empty result set.
+ */
+export function checkExercise(results) {
+    const failures = results.filter((r) => r.threw !== undefined || r.newConsoleErrors.length > 0);
+    const ok = failures.length === 0;
+    return {
+        name: 'exercises',
+        ok,
+        detail: ok
+            ? `all ${results.length} exercise(s) ran without new console errors`
+            : failures
+                .map((f) => {
+                const reason = f.threw !== undefined
+                    ? `threw: ${f.threw}`
+                    : `${f.newConsoleErrors.length} new console error(s): ${f.newConsoleErrors.slice(0, 2).join(' | ')}`;
+                return `${f.kind} ${f.label} — ${reason}`;
+            })
+                .join('; '),
+    };
+}

package/dist/tools/fiori/smoke/browser.js

@@ -0,0 +1,52 @@
+// cspeach-cli/src/tools/fiori/smoke/browser.ts
+//
+// Render-smoke, part A — browser resolution.
+//
+// puppeteer-core does NOT download a browser; it drives a Chromium-based binary
+// already installed on the machine (Edge on every Windows 11 box, or Chrome).
+// This module finds that binary. It is a PURE function over an injectable
+// existsSync + env so it unit-tests without touching the real filesystem — the
+// production caller invokes it with no arguments (real fs.existsSync + real
+// process.env).
+//
+// Task 9 consumes { path, kind }: `path` feeds puppeteer.launch({ executablePath }),
+// `kind` is surfaced in the smoke report so the developer knows which engine ran.
+import { existsSync as realExistsSync } from 'node:fs';
+/** Classify an explicit override path by its filename — chrome vs edge. */
+function classify(path) {
+    return /chrome/i.test(path) ? 'chrome' : 'edge';
+}
+/**
+ * Windows-first probe for a Chromium-based browser executable.
+ *
+ * Resolution order:
+ *   1. CSPEACH_BROWSER env override — explicit developer intent, returned as-is
+ *      (not gated on existsSync; a bad path surfaces later at launch).
+ *   2. Microsoft Edge (ProgramFiles(x86) then ProgramFiles).
+ *   3. Google Chrome (ProgramFiles(x86) then ProgramFiles).
+ *   4. undefined when nothing is found.
+ *
+ * Pure over the injected deps; safe to call with none in production.
+ */
+export function resolveBrowserExecutable(deps = {}) {
+    const existsSync = deps.existsSync ?? realExistsSync;
+    const env = deps.env ?? process.env;
+    const override = env.CSPEACH_BROWSER;
+    if (override) {
+        return { path: override, kind: classify(override) };
+    }
+    const programFiles = env.ProgramFiles;
+    const programFilesX86 = env['ProgramFiles(x86)'];
+    const candidates = [];
+    const push = (root, suffix, kind) => {
+        if (root)
+            candidates.push({ path: `${root}\\${suffix}`, kind });
+    };
+    // Edge before Chrome: Edge ships on every Windows 11 box, so it is the most
+    // reliable default; Chrome is the fallback.
+    push(programFilesX86, 'Microsoft\\Edge\\Application\\msedge.exe', 'edge');
+    push(programFiles, 'Microsoft\\Edge\\Application\\msedge.exe', 'edge');
+    push(programFilesX86, 'Google\\Chrome\\Application\\chrome.exe', 'chrome');
+    push(programFiles, 'Google\\Chrome\\Application\\chrome.exe', 'chrome');
+    return candidates.find((c) => existsSync(c.path));
+}

package/dist/tools/fiori/smoke/driver.js

@@ -0,0 +1,89 @@
+// cspeach-cli/src/tools/fiori/smoke/driver.ts
+//
+// Render-smoke, part A — the page driver.
+//
+// This is a NEUTRAL url-driver. It launches a headless Chromium-based browser
+// via puppeteer-core, navigates to whatever URL it is handed, and COLLECTS
+// signals (failed HTTP responses, console errors) so the caller can reason
+// about them. It makes NO assertions and bakes in NO assumption about what the
+// URL is.
+//
+// F-1 (Critical, realized in Task 9): the smoke must target the LOCAL
+// AUTHENTICATED PREVIEW (`npm run start` / `fiori run` → fiori-tools-proxy →
+// real backend with the dev's auth), NOT the deployed BSP URL (which serves a
+// SAP logon page and 401s every OData call — the "green tests, dead at the live
+// leg" trap). This driver deliberately stays neutral: it exposes failedRequests()
+// + consoleErrors() precisely so Task 9 can detect the logon-page / unreachable
+// cases from the collected signals. Do not add any deployed-URL assumption here.
+import puppeteer from 'puppeteer-core';
+/**
+ * Launch a headless browser at `executablePath`, navigate to `url`, and return a
+ * SmokePage that has already begun collecting failed requests + console errors.
+ *
+ * `timeoutMs` bounds both the initial navigation and subsequent waitForSelector
+ * calls. Never called from unit tests (no real browser in CI) — exercised only
+ * on the live leg (VPN, local authenticated preview up).
+ */
+export async function openApp(executablePath, url, timeoutMs) {
+    const browser = await puppeteer.launch({ executablePath, headless: true });
+    const failed = [];
+    const consoleErrs = [];
+    try {
+        const page = await browser.newPage();
+        // Collect BEFORE navigating so the initial document + its OData calls are seen.
+        page.on('response', (resp) => {
+            const status = resp.status();
+            if (status >= 400)
+                failed.push({ url: resp.url(), status });
+        });
+        page.on('console', (msg) => {
+            if (msg.type() === 'error')
+                consoleErrs.push(msg.text());
+        });
+        await page.goto(url, { waitUntil: 'networkidle2', timeout: timeoutMs });
+        return {
+            currentUrl: () => page.url(),
+            waitForSelector: (selector) => page.waitForSelector(selector, { timeout: timeoutMs }),
+            queryTexts: (selector) => page.$$eval(selector, (els) => els.map((el) => (el.textContent ?? '').trim())),
+            failedRequests: () => [...failed],
+            consoleErrors: () => [...consoleErrs],
+            // Track 3 exercises (live leg only — never unit-tested; the suite injects
+            // fakes). `selectorHint` is a REAL DOM selector derived from the control id
+            // (`[id$="--<id>"]`), so a plain click drives the press handler.
+            press: async (selectorHint) => {
+                await page.click(selectorHint, { delay: 0 });
+                await page.waitForNetworkIdle({ idleTime: 200, timeout: timeoutMs }).catch(() => { });
+            },
+            // Navigate by route NAME via the UI5 router (navTo) — UI5 maps the name to
+            // its pattern, so this works even when the pattern is '' (root). Setting the
+            // hash by name would match nothing when name !== pattern.
+            gotoRoute: async (name) => {
+                await page.evaluate((route) => {
+                    const w = window;
+                    const Component = w.sap?.ui?.core?.Component;
+                    const registry = Component?.registry?.all?.() ?? {};
+                    for (const key of Object.keys(registry)) {
+                        const comp = registry[key];
+                        const router = typeof comp?.getRouter === 'function' ? comp.getRouter() : undefined;
+                        if (router && typeof router.navTo === 'function') {
+                            router.navTo(route);
+                            return;
+                        }
+                    }
+                    throw new Error(`no UI5 router found to navigate route "${route}"`);
+                }, name);
+                await page.waitForNetworkIdle({ idleTime: 200, timeout: timeoutMs }).catch(() => { });
+            },
+            close: async () => {
+                await browser.close();
+            },
+        };
+    }
+    catch (err) {
+        // Navigation failed (preview server down, timeout, ...). Don't leak the
+        // browser process — Task 9's precondition check turns this into a clean
+        // verification:'manual' with the caught reason.
+        await browser.close();
+        throw err;
+    }
+}