@cspeach/cli 0.9.0 → 1.1.0

package/dist/tools/fiori/fe-extend.js

@@ -0,0 +1,76 @@
+// cspeach-cli/src/tools/fiori/fe-extend.ts
+/**
+ * Add a Fiori Elements extension point (custom column / action / section /
+ * controller-extension) to an EXISTING V4 FE app on disk, via
+ * @sap-ux/fe-fpm-writer. Mirrors scaffold.ts's generate()+commit() pattern:
+ * run the matching generator into a mem-fs editor, then flush with commit().
+ *
+ * SCOPE LIMIT (V4 FE only)
+ * ------------------------
+ * fe-fpm-writer's validateBasePath requires a `sap.fe.templates` dependency in
+ * the manifest — it works ONLY on V4 Fiori Elements apps (LROP / Worklist /
+ * ALP / FEOP) and REFUSES OVP (sap.ovp) and every OData V2 app with a
+ * "Dependency sap.fe.templates is missing …" library error. We catch that and
+ * rethrow the clean typed message so callers get a single, actionable line
+ * instead of the writer's internal wording.
+ */
+import { create } from 'mem-fs';
+import { create as createEditor } from 'mem-fs-editor';
+/** The four supported extension operations. Closed union → schema enum. */
+export const FE_EXTEND_OPS = ['custom-column', 'custom-action', 'custom-section', 'controller-extension'];
+/** Thrown when the target app is not a V4 Fiori Elements app (no sap.fe.templates). */
+export class NotV4FeAppError extends Error {
+    constructor() {
+        super('fiori_fe_extend requires a V4 Fiori Elements app');
+        this.name = 'NotV4FeAppError';
+    }
+}
+// fe-fpm-writer's validateBasePath library error — both the single-dependency
+// and (defensively) the shared trailing sentence are matched so a wording
+// tweak on either side still maps to the typed V4-only error.
+function isMissingFeLibError(msg) {
+    return /sap\.fe\.templates is missing/i.test(msg) || /Fiori elements FPM requires the SAP FE libraries/i.test(msg);
+}
+/**
+ * Run the requested FE extension generator against an existing V4 FE app and
+ * flush the result to disk. Throws NotV4FeAppError when the target is not a V4
+ * FE app; rethrows any other writer error unchanged.
+ */
+export async function feExtend(opts) {
+    // Dynamic import: keep the heavy writer out of the cold-start path (mirrors
+    // the engine's lazy-load convention; only paid when the tool actually runs).
+    const fpm = await import('@sap-ux/fe-fpm-writer');
+    const editor = createEditor(create());
+    let result;
+    try {
+        // params is passed through verbatim (1:1 with the writer's Custom*/Controller
+        // config types) — the tool is a thin, deterministic pass-through.
+        switch (opts.op) {
+            case 'custom-column':
+                result = await fpm.generateCustomColumn(opts.basePath, opts.params, editor);
+                break;
+            case 'custom-action':
+                result = await fpm.generateCustomAction(opts.basePath, opts.params, editor);
+                break;
+            case 'custom-section':
+                result = await fpm.generateCustomSection(opts.basePath, opts.params, editor);
+                break;
+            case 'controller-extension':
+                result = await fpm.generateControllerExtension(opts.basePath, opts.params, editor);
+                break;
+            default: {
+                // Exhaustiveness guard: the union is closed. A future op added without a
+                // branch here fails loudly instead of silently no-op'ing.
+                const never = opts.op;
+                throw new Error(`unsupported fe_extend op: ${String(never)}`);
+            }
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (isMissingFeLibError(msg))
+            throw new NotV4FeAppError();
+        throw err;
+    }
+    await new Promise((res, rej) => result.commit((e) => (e ? rej(e) : res())));
+}

package/dist/tools/fiori/fe-scaffold.js

@@ -0,0 +1,71 @@
+// cspeach-cli/src/tools/fiori/fe-scaffold.ts
+import { generate, TemplateType, OdataVersion } from '@sap-ux/fiori-elements-writer';
+import { create } from 'mem-fs';
+import { create as createEditor } from 'mem-fs-editor';
+import { join } from 'node:path';
+const DEFAULT_UI5_VERSION = '1.120.0'; // same rationale as scaffold.ts (avoids the 1.71 blank-page trap)
+/** Scaffold a Fiori Elements shell and FULLY flush it to disk. Relies on the
+ *  service's backend @UI annotations — authors no local annotation.xml. */
+export async function scaffoldFioriElements(opts) {
+    const ui5Version = opts.ui5Version ?? DEFAULT_UI5_VERSION;
+    const version = opts.service.version === '2.0' ? OdataVersion.v2 : OdataVersion.v4;
+    // Per-template settings (spike §3): LROP/Worklist/ALP use
+    // entityConfig.mainEntityName (ALP is a LROP-based analytical variant — same
+    // settings shape); OVP uses filterEntitySet (the modern replacement for the
+    // deprecated filterEntityType). Each arm is explicit so adding a branch never
+    // silently changes another floorplan's behaviour.
+    let template;
+    if (opts.template === 'lrop') {
+        template = { type: TemplateType.ListReportObjectPage, settings: { entityConfig: { mainEntityName: opts.mainEntity } } };
+    }
+    else if (opts.template === 'worklist') {
+        template = { type: TemplateType.Worklist, settings: { entityConfig: { mainEntityName: opts.mainEntity } } };
+    }
+    else if (opts.template === 'ovp') {
+        template = { type: TemplateType.OverviewPage, settings: { filterEntitySet: opts.mainEntity } };
+    }
+    else if (opts.template === 'alp') {
+        template = { type: TemplateType.AnalyticalListPage, settings: { entityConfig: { mainEntityName: opts.mainEntity } } };
+    }
+    else {
+        // Exhaustiveness guard: the union is closed, so this is unreachable — but a
+        // future template added to the union without a branch here fails loudly
+        // instead of silently misrouting to another floorplan.
+        const never = opts.template;
+        throw new Error(`unsupported FE template: ${String(never)}`);
+    }
+    // Build the service object: version is required; url/path/metadata/client only
+    // when provided (metadata is optional — spike §4).
+    const service = { version };
+    if (opts.service.url)
+        service.url = opts.service.url;
+    if (opts.service.path)
+        service.path = opts.service.path;
+    if (opts.service.metadata)
+        service.metadata = opts.service.metadata;
+    if (opts.service.client)
+        service.client = opts.service.client;
+    // Foreign-service local annotations: thread ONLY localAnnotationsName so the
+    // writer produces a LOCAL ODataAnnotation dataSource (uri === localUri ===
+    // annotations/<name>.xml). The real EDMX is written over the skeleton below,
+    // after generate() and before commit. When absent, the writer's own default
+    // ('annotation') is left untouched — zero regression.
+    if (opts.localAnnotations)
+        service.localAnnotationsName = opts.localAnnotations.technicalName;
+    const fs = createEditor(create());
+    const config = {
+        app: { id: opts.appId, title: opts.appTitle, projectType: 'EDMXBackend' },
+        package: { name: opts.appId },
+        template,
+        service,
+        appOptions: { typescript: false },
+        ui5: { minUI5Version: ui5Version, version: ui5Version },
+    };
+    await generate(opts.basePath, config, fs);
+    // Overwrite the writer's empty EDMX skeleton with the caller's real annotations
+    // EDMX, in the mem-fs editor, BEFORE commit so the flushed file is the caller's.
+    if (opts.localAnnotations) {
+        fs.write(join(opts.basePath, 'webapp', 'annotations', `${opts.localAnnotations.technicalName}.xml`), opts.localAnnotations.xml);
+    }
+    await new Promise((res, rej) => fs.commit((err) => (err ? rej(err) : res())));
+}

package/dist/tools/fiori/floorplan-map.js

@@ -0,0 +1,19 @@
+// cspeach-cli/src/tools/fiori/floorplan-map.ts
+//
+// Single source of truth for the plan-name ↔ tool-template spelling
+// divergence: the plan schema (PlanPhaseUi.floorplan) names the List Report
+// floorplan 'listReport', but the FE writer / fiori_scaffold_fe tool names
+// the same template 'lrop'. Every other floorplan spells identically.
+//
+// Deliberate leaf module (cycle-1 M7): it imports NOTHING from the writer, so
+// plan-resume.ts can consume the map without pulling
+// @sap-ux/fiori-elements-writer into plan-resume's test graph. Both
+// fe-scaffold's consumers and plan-resume import FLOORPLAN_TO_TEMPLATE here.
+/** Deterministic plan-floorplan → tool-template mapping. Only 'listReport'
+ *  diverges ('lrop'); the rest map to their identical spelling. */
+export const FLOORPLAN_TO_TEMPLATE = {
+    listReport: 'lrop',
+    worklist: 'worklist',
+    ovp: 'ovp',
+    alp: 'alp',
+};

package/dist/tools/fiori/i18n.js

@@ -0,0 +1,39 @@
+// cspeach-cli/src/tools/fiori/i18n.ts
+export class I18nConflictError extends Error {
+    constructor(key, a, b) {
+        super(`i18n key "${key}" already set to "${a}", refusing to overwrite with "${b}"`);
+        this.name = 'I18nConflictError';
+    }
+}
+/** Parse a .properties body into a key→value map (ignores comments/blanks). */
+function parse(text) {
+    const map = new Map();
+    for (const line of text.split(/\r?\n/)) {
+        const t = line.trim();
+        if (!t || t.startsWith('#'))
+            continue;
+        const eq = t.indexOf('=');
+        if (eq === -1)
+            continue;
+        map.set(t.slice(0, eq).trim(), t.slice(eq + 1));
+    }
+    return map;
+}
+/** Returns the properties text with `keys` appended; dedupes, errors on conflict. */
+export function appendI18n(existing, keys) {
+    const map = parse(existing);
+    const additions = [];
+    for (const [k, v] of Object.entries(keys)) {
+        const cur = map.get(k);
+        if (cur === undefined) {
+            additions.push(`${k}=${v}`);
+            map.set(k, v);
+        }
+        else if (cur !== v)
+            throw new I18nConflictError(k, cur, v);
+    }
+    if (additions.length === 0)
+        return existing;
+    const sep = existing.endsWith('\n') || existing === '' ? '' : '\n';
+    return `${existing}${sep}${additions.join('\n')}\n`;
+}

package/dist/tools/fiori/manifest.js

@@ -0,0 +1,70 @@
+// cspeach-cli/src/tools/fiori/manifest.ts
+/** Deep-merges manifest.json fragments. Unions object maps by key and arrays
+ * of named objects (routes) by `name`; identical value = no-op, differing
+ * value for the same key = hard error. Never silent last-wins. */
+export class ManifestMergeError extends Error {
+    path;
+    a;
+    b;
+    constructor(path, a, b) {
+        super(`Manifest merge conflict at "${path}": ${JSON.stringify(a)} vs ${JSON.stringify(b)}`);
+        this.path = path;
+        this.a = a;
+        this.b = b;
+        this.name = 'ManifestMergeError';
+    }
+}
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** Arrays whose elements are merged by a key field instead of concatenated. */
+const ARRAY_KEY_BY = { routes: 'name' };
+function mergeNode(a, b, path) {
+    if (b === undefined)
+        return a;
+    if (a === undefined)
+        return b;
+    if (isObj(a) && isObj(b)) {
+        const out = { ...a };
+        for (const k of Object.keys(b))
+            out[k] = mergeNode(a[k], b[k], `${path}.${k}`);
+        return out;
+    }
+    if (Array.isArray(a) && Array.isArray(b)) {
+        const keyField = ARRAY_KEY_BY[path.split('.').pop() ?? ''];
+        if (keyField) {
+            const out = [...a];
+            for (const item of b) {
+                const idx = out.findIndex((x) => x?.[keyField] === item?.[keyField]);
+                if (idx === -1)
+                    out.push(item);
+                else if (JSON.stringify(out[idx]) !== JSON.stringify(item))
+                    throw new ManifestMergeError(`${path}[${keyField}=${item[keyField]}]`, out[idx], item);
+            }
+            return out;
+        }
+        return [...a, ...b];
+    }
+    if (JSON.stringify(a) === JSON.stringify(b))
+        return a;
+    throw new ManifestMergeError(path, a, b);
+}
+export function mergeManifest(base, patch) {
+    return mergeNode(base ?? {}, patch ?? {}, 'manifest');
+}
+export function addDataSource(m, name, uri, type = 'OData', odataVersion) {
+    const ds = { uri, type };
+    if (odataVersion)
+        ds.settings = { odataVersion };
+    return mergeManifest(m, { 'sap.app': { dataSources: { [name]: ds } } });
+}
+export function addModel(m, name, def) {
+    return mergeManifest(m, { 'sap.ui5': { models: { [name]: def } } });
+}
+export function addTarget(m, name, viewName, viewLevel = 1) {
+    return mergeManifest(m, { 'sap.ui5': { routing: { targets: { [name]: { viewName, viewLevel, viewType: 'XML' } } } } });
+}
+export function addRoute(m, name, pattern, target) {
+    return mergeManifest(m, { 'sap.ui5': { routing: { routes: [{ name, pattern, target: [target] }] } } });
+}
+export function addLib(m, lib) {
+    return mergeManifest(m, { 'sap.ui5': { dependencies: { libs: { [lib]: {} } } } });
+}

package/dist/tools/fiori/render.js

@@ -0,0 +1,77 @@
+// cspeach-cli/src/tools/fiori/render.ts
+import { render as ejsRender } from 'ejs';
+export class MissingParamError extends Error {
+    param;
+    constructor(param, entry) {
+        super(`Catalog entry "${entry}" requires param "${param}"`);
+        this.param = param;
+        this.name = 'MissingParamError';
+    }
+}
+/**
+ * Raised when a param value fails its declared `pattern`. This is a SECURITY
+ * boundary for any param that reaches a file path (e.g. `ns`): a value like
+ * `../../../x` must fail here, loudly, before render — never silently produce a
+ * traversal path. Keep the message human-actionable.
+ */
+export class InvalidParamError extends Error {
+    param;
+    constructor(param, entry, value, hint) {
+        super(`Catalog entry "${entry}" param "${param}" is invalid: ${hint} ` +
+            `(got ${JSON.stringify(String(value))}).`);
+        this.param = param;
+        this.name = 'InvalidParamError';
+    }
+}
+const ejs = (tpl, data) => ejsRender(tpl, data, { rmWhitespace: false });
+/**
+ * Render manifestPatch with JSON-safe per-placeholder substitution.
+ *
+ * Works by serialising the patch to JSON and replacing each `<%- name %>`
+ * placeholder with a JSON-escaped string value (the surrounding quotes from
+ * JSON.stringify are stripped because the placeholder already sits inside a
+ * JSON string literal).  Only simple `<%- name %>` (raw output) substitutions
+ * are supported; any remaining `<%` tag after substitution triggers a clear
+ * error so callers are not silently given a partially-rendered patch.
+ */
+function renderManifestPatch(patch, params, entryName) {
+    const json = JSON.stringify(patch).replace(/<%-\s*(\w+)\s*%>/g, (_m, name) => {
+        const val = params[name];
+        // JSON.stringify yields a quoted, fully-escaped string literal; strip the
+        // surrounding quotes because the placeholder already sits inside a JSON string.
+        return JSON.stringify(val === undefined ? '' : String(val)).slice(1, -1);
+    });
+    if (json.includes('<%')) {
+        throw new Error(`Catalog entry "${entryName}" manifestPatch uses an unsupported EJS expression; ` +
+            `only simple "<%- name %>" substitutions are allowed in manifestPatch.`);
+    }
+    return JSON.parse(json);
+}
+/** Render a catalog entry's EJS files/i18n/manifest with resolved params. */
+export function renderEntry(entry, params) {
+    for (const [name, def] of Object.entries(entry.params)) {
+        const value = params[name];
+        if (def.required && (value === undefined || value === null))
+            throw new MissingParamError(name, entry.name);
+        // Enforce declared pattern on any provided value. This is the early,
+        // catalog-driven half of the defense-in-depth: a path-bearing param (ns)
+        // declares a strict identifier pattern so a `../`-traversal is rejected
+        // here, before it can ever reach `join(appDir, renderedPath)`.
+        if (def.pattern !== undefined && value !== undefined && value !== null) {
+            const re = new RegExp(`^(?:${def.pattern})$`);
+            if (typeof value !== 'string' || !re.test(value)) {
+                throw new InvalidParamError(name, entry.name, value, `must be a simple identifier matching /${def.pattern}/ ` +
+                    `(no dots, slashes, or path separators)`);
+            }
+        }
+    }
+    const files = entry.files.map((f) => ({
+        path: ejs(f.path, params),
+        content: ejs(f.content, params),
+    }));
+    const i18nKeys = {};
+    for (const [k, v] of Object.entries(entry.i18nKeys))
+        i18nKeys[ejs(k, params)] = ejs(v, params);
+    const manifestPatch = renderManifestPatch(entry.manifestPatch, params, entry.name);
+    return { files, manifestPatch, i18nKeys, libraries: entry.libraries };
+}