@cspeach/cli 1.0.0 → 1.1.1

package/dist/tools/extend-model/tool.js

@@ -13,7 +13,7 @@
  * See docs/superpowers/specs/2026-06-24-revision-aware-cspeach-design.md §5.2.
  */
 import { registerTool } from '../index.js';
-import { insertCdsField, insertDdlxLineItem, promoteCdsFieldToLineItem, addTableField, insertBdefField, buildClauseLine, buildHandlerMethod, insertBdefClause, insertHandlerMethod, createHandlerClassSkeleton, classBlockSpan, resolveBehaviorAlias, insertProjectionUse, insertMdeActionButton, } from './anchored-insert.js';
+import { insertCdsField, insertDdlxLineItem, promoteCdsFieldToLineItem, addTableField, insertBdefField, buildClauseLine, buildHandlerMethod, insertBdefClause, insertHandlerMethod, createHandlerClassSkeleton, classBlockSpan, resolveBehaviorAlias, insertProjectionUse, insertMdeActionButton, insertDdlxHeaderInfo, insertDdlxSelectionField, insertDdlxIdentification, insertDdlxFacet, insertDdlxDataPoint, insertDdlxChart, insertCdsValueHelp, insertBdefSideEffects, } from './anchored-insert.js';
 async function extendModelInsertHandler(args, _ctx) {
     const { kind } = args;
     // bdef-stub is branched BEFORE the source/field guard (which does not apply to this kind).
@@ -47,6 +47,105 @@ async function extendModelInsertHandler(args, _ctx) {
             return { content: `error: mde-action-button failed — ${err instanceof Error ? err.message : String(err)}`, is_error: true };
         }
     }
+    // ddlx-headerinfo uses `source` + typeName/typeNamePlural/titleField (NOT `field`) — branch BEFORE the field guard.
+    if (kind === 'ddlx-headerinfo') {
+        if (typeof args.source !== 'string'
+            || typeof args.typeName !== 'string' || args.typeName.trim() === ''
+            || typeof args.typeNamePlural !== 'string' || args.typeNamePlural.trim() === ''
+            || typeof args.titleField !== 'string' || args.titleField.trim() === '') {
+            return { content: 'error: ddlx-headerinfo requires source, typeName, typeNamePlural and titleField', is_error: true };
+        }
+        try {
+            const modified = insertDdlxHeaderInfo(args.source, {
+                typeName: args.typeName, typeNamePlural: args.typeNamePlural,
+                titleField: args.titleField, descriptionField: args.descriptionField,
+            });
+            return { content: JSON.stringify({ modified, summary: `Added a @UI.headerInfo block (typeName '${args.typeName}', title ${args.titleField}) above the annotate view.` }) };
+        }
+        catch (err) {
+            return { content: `error: ddlx-headerinfo failed — ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+        }
+    }
+    // ddlx-identification uses `source`; `field` is optional (FOR_ACTION button needs none) — branch BEFORE the field guard.
+    if (kind === 'ddlx-identification') {
+        if (typeof args.source !== 'string') {
+            return { content: 'error: ddlx-identification requires source', is_error: true };
+        }
+        const forAction = (typeof args.action === 'string' && args.action.trim() !== '')
+            ? { dataAction: args.action, label: args.label ?? args.action }
+            : undefined;
+        if (!forAction && (typeof args.field !== 'string' || args.field.trim() === '')) {
+            return { content: 'error: ddlx-identification requires either field (plain identification) or action (FOR_ACTION button)', is_error: true };
+        }
+        const position = typeof args.position === 'number' ? args.position : 10;
+        try {
+            const modified = insertDdlxIdentification(args.source, { field: args.field, position, forAction });
+            const summary = forAction
+                ? `Added a FOR_ACTION @UI.identification button for '${forAction.dataAction}' (Object Page).`
+                : `Added @UI.identification (position ${position}) on ${args.field}.`;
+            return { content: JSON.stringify({ modified, summary }) };
+        }
+        catch (err) {
+            return { content: `error: ddlx-identification failed — ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+        }
+    }
+    // ddlx-facet uses `source` + facetId/label/fieldGroupQualifier/fields (NOT a single `field`) — branch BEFORE the field guard.
+    if (kind === 'ddlx-facet') {
+        if (typeof args.source !== 'string'
+            || typeof args.facetId !== 'string' || args.facetId.trim() === ''
+            || typeof args.label !== 'string' || args.label.trim() === ''
+            || typeof args.fieldGroupQualifier !== 'string' || args.fieldGroupQualifier.trim() === ''
+            || !Array.isArray(args.fields)) {
+            return { content: 'error: ddlx-facet requires source, facetId, label, fieldGroupQualifier and a fields array', is_error: true };
+        }
+        const position = typeof args.position === 'number' ? args.position : 10;
+        try {
+            const modified = insertDdlxFacet(args.source, {
+                facetId: args.facetId, label: args.label, fieldGroupQualifier: args.fieldGroupQualifier,
+                position, fields: args.fields,
+            });
+            return { content: JSON.stringify({ modified, summary: `Added facet '${args.facetId}' (field group '${args.fieldGroupQualifier}') + @UI.fieldGroup on ${args.fields.length} field(s).` }) };
+        }
+        catch (err) {
+            return { content: `error: ddlx-facet failed — ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+        }
+    }
+    // ddlx-chart uses `source` + chartType/dimensions/measures (NOT a single `field`) — branch BEFORE the field guard.
+    if (kind === 'ddlx-chart') {
+        if (typeof args.source !== 'string'
+            || typeof args.chartType !== 'string'
+            || !Array.isArray(args.dimensions) || args.dimensions.length === 0
+            || !Array.isArray(args.measures) || args.measures.length === 0) {
+            return { content: 'error: ddlx-chart requires source, chartType and non-empty dimensions and measures arrays', is_error: true };
+        }
+        try {
+            const modified = insertDdlxChart(args.source, {
+                qualifier: args.qualifier, chartType: args.chartType,
+                dimensions: args.dimensions, measures: args.measures,
+            });
+            return { content: JSON.stringify({ modified, summary: `Added a #${args.chartType} @UI.chart + paired @UI.presentationVariant (#AS_CHART)${args.qualifier ? ` (qualifier ${args.qualifier})` : ''} above the annotate view.` }) };
+        }
+        catch (err) {
+            return { content: `error: ddlx-chart failed — ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+        }
+    }
+    // bdef-sideeffects uses `source` + sourceFields/targetFields (NOT `field`) — branch BEFORE the field guard.
+    if (kind === 'bdef-sideeffects') {
+        if (typeof args.source !== 'string'
+            || !Array.isArray(args.sourceFields) || args.sourceFields.length === 0
+            || !Array.isArray(args.targetFields) || args.targetFields.length === 0) {
+            return { content: 'error: bdef-sideeffects requires source and non-empty sourceFields and targetFields arrays', is_error: true };
+        }
+        try {
+            const modified = insertBdefSideEffects(args.source, {
+                entityAlias: args.entityAlias, sourceFields: args.sourceFields, targetFields: args.targetFields,
+            });
+            return { content: JSON.stringify({ modified, summary: `Added a side effects clause (field ${args.sourceFields.join(', ')} affects field ${args.targetFields.join(', ')}) to the managed BDEF${args.entityAlias ? ` (alias ${args.entityAlias})` : ''}.` }) };
+        }
+        catch (err) {
+            return { content: `error: bdef-sideeffects failed — ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+        }
+    }
     const { source, field } = args;
     if (typeof source !== 'string' || typeof field !== 'string' || field.trim() === '') {
         return { content: 'error: source (string) and field (non-empty string) are required', is_error: true };
@@ -77,9 +176,30 @@ async function extendModelInsertHandler(args, _ctx) {
             modified = insertBdefField(source, { alias: args.alias, target, clause: field });
             summary = `Added ${target} '${field}' to BDEF${args.alias ? ` (alias ${args.alias})` : ''}.`;
         }
+        else if (kind === 'ddlx-selectionfield') {
+            const position = typeof args.position === 'number' ? args.position : 10;
+            modified = insertDdlxSelectionField(source, { field, position });
+            summary = `Added "${field}" as an @UI.selectionField filter at position ${position} in the DDLX metadata extension.`;
+        }
+        else if (kind === 'ddlx-datapoint') {
+            if (typeof args.title !== 'string' || args.title.trim() === '') {
+                return { content: 'error: ddlx-datapoint requires a non-empty title', is_error: true };
+            }
+            modified = insertDdlxDataPoint(source, { field, title: args.title, criticalityField: args.criticalityField });
+            summary = `Added a @UI.dataPoint (title '${args.title}'${args.criticalityField ? `, criticality ${args.criticalityField}` : ''}) on ${field}.`;
+        }
+        else if (kind === 'cds-valuehelp') {
+            if (typeof args.entity !== 'string' || args.entity.trim() === '' || typeof args.element !== 'string' || args.element.trim() === '') {
+                return { content: 'error: cds-valuehelp requires a non-empty entity and element', is_error: true };
+            }
+            modified = insertCdsValueHelp(source, {
+                field, entity: args.entity, element: args.element, additionalBinding: args.additionalBinding,
+            });
+            summary = `Added a @Consumption.valueHelpDefinition (entity '${args.entity}', element ${args.element}) above ${field} in the CDS view.`;
+        }
         else {
             return {
-                content: `error: unknown kind "${String(kind)}" — expected "cds-field", "ddlx-lineitem", "cds-lineitem", "table-field", "bdef-field" or "bdef-stub"`,
+                content: `error: unknown kind "${String(kind)}" — expected "cds-field", "ddlx-lineitem", "cds-lineitem", "table-field", "bdef-field", "bdef-stub", "projection-use", "mde-action-button", "ddlx-headerinfo", "ddlx-selectionfield", "ddlx-identification", "ddlx-facet", "ddlx-datapoint", "ddlx-chart", "cds-valuehelp" or "bdef-sideeffects"`,
                 is_error: true,
             };
         }
@@ -107,8 +227,21 @@ registerTool({
         + 'MANAGED BDEF and the corresponding handler method skeleton to the CCIMP include; '
         + 'kind="projection-use" exposes a `use action/function/association` line inside a PROJECTION BDEF '
         + 'entity body (non-projection BDEFs refused); kind="mde-action-button" inserts a @UI.lineItem '
-        + 'FOR_ACTION button annotation above an anchor field in a metadata extension. Pure transform — '
-        + 'does not touch SAP.',
+        + 'FOR_ACTION button annotation above an anchor field in a metadata extension; '
+        + 'kind="ddlx-headerinfo" inserts a view-level @UI.headerInfo block above the `annotate view` line '
+        + '(Object Page header — idempotent, refuses a second block); kind="ddlx-selectionfield" adds an '
+        + '@UI.selectionField filter to a DDLX metadata extension (in place above an exposed field, or '
+        + 'appends the field + annotation when absent); kind="ddlx-identification" adds a @UI.identification '
+        + 'annotation on a field, or a #FOR_ACTION Object-Page action button (via `action`) — refuses a '
+        + 'duplicate dataAction; kind="ddlx-facet" adds a view-level @UI.facet (#FIELDGROUP_REFERENCE) above '
+        + 'the `annotate view` line (merged into an existing @UI.facet array, idempotent on facetId) plus a '
+        + 'per-field @UI.fieldGroup on each named field; kind="ddlx-datapoint" adds a @UI.dataPoint (title, '
+        + 'optional criticality field) above an existing field; kind="ddlx-chart" adds a view-level @UI.chart '
+        + 'and its paired @UI.presentationVariant (#AS_CHART) above the `annotate view` line, qualifier-'
+        + 'idempotent as a unit; kind="cds-valuehelp" inserts a @Consumption.valueHelpDefinition above an '
+        + 'EXISTING exposed CDS-view field (DDLS source; refuses multi-line/computed elements, idempotent); '
+        + 'kind="bdef-sideeffects" inserts a `side effects { field … affects field …; }` block into a MANAGED '
+        + 'BDEF entity body (refuses unmanaged). Pure transform — does not touch SAP.',
     isMutating: false,
     category: 'fiori',
     flagGated: true,
@@ -117,15 +250,15 @@ registerTool({
         properties: {
             kind: {
                 type: 'string',
-                enum: ['cds-field', 'ddlx-lineitem', 'cds-lineitem', 'table-field', 'bdef-field', 'bdef-stub', 'projection-use', 'mde-action-button'],
-                description: 'cds-field: add an element to a CDS view body. ddlx-lineitem: add an @UI.lineItem column to a DDLX metadata extension. cds-lineitem: promote an existing exposed CDS-view field to a list column (insert @UI.lineItem above its declaration). table-field: append a NON-KEY field to a CDS `define table` body (key fields refused). bdef-field: add a field/mapping line to a MANAGED BDEF entity (unmanaged refused). bdef-stub: add a validation/determination/action clause to a MANAGED BDEF and its handler skeleton to the CCIMP include. projection-use: expose a `use action/function/association` line inside a PROJECTION BDEF entity body (non-projection BDEFs refused). mde-action-button: insert a @UI.lineItem FOR_ACTION button annotation above an anchor field in a metadata extension.',
+                enum: ['cds-field', 'ddlx-lineitem', 'cds-lineitem', 'table-field', 'bdef-field', 'bdef-stub', 'projection-use', 'mde-action-button', 'ddlx-headerinfo', 'ddlx-selectionfield', 'ddlx-identification', 'ddlx-facet', 'ddlx-datapoint', 'ddlx-chart', 'cds-valuehelp', 'bdef-sideeffects'],
+                description: 'cds-field: add an element to a CDS view body. ddlx-lineitem: add an @UI.lineItem column to a DDLX metadata extension. cds-lineitem: promote an existing exposed CDS-view field to a list column (insert @UI.lineItem above its declaration). table-field: append a NON-KEY field to a CDS `define table` body (key fields refused). bdef-field: add a field/mapping line to a MANAGED BDEF entity (unmanaged refused). bdef-stub: add a validation/determination/action clause to a MANAGED BDEF and its handler skeleton to the CCIMP include. projection-use: expose a `use action/function/association` line inside a PROJECTION BDEF entity body (non-projection BDEFs refused). mde-action-button: insert a @UI.lineItem FOR_ACTION button annotation above an anchor field in a metadata extension. ddlx-headerinfo: insert a view-level @UI.headerInfo block above the `annotate view` line (Object Page header; idempotent). ddlx-selectionfield: add an @UI.selectionField filter to a DDLX metadata extension (in place above an exposed field, or append the field + annotation when absent). ddlx-identification: add an @UI.identification annotation on a field, or a #FOR_ACTION Object-Page action button (set `action`); refuses a duplicate dataAction. ddlx-facet: add a view-level @UI.facet (#FIELDGROUP_REFERENCE) above the `annotate view` line (merged into an existing @UI.facet array, idempotent on facetId) plus a per-field @UI.fieldGroup on each named field. ddlx-datapoint: add a @UI.dataPoint (title, optional criticality field) above an existing field. ddlx-chart: add a view-level @UI.chart and its paired @UI.presentationVariant (#AS_CHART) above the `annotate view` line (qualifier-idempotent as a unit). cds-valuehelp: insert a @Consumption.valueHelpDefinition above an existing exposed CDS-view field (DDLS source; refuses multi-line/computed elements, idempotent). bdef-sideeffects: insert a `side effects { field … affects field …; }` block into a MANAGED BDEF entity body (unmanaged refused).',
             },
             source: { type: 'string', description: 'Full current source of the CDS view, DDLX metadata extension, CDS table, or managed BDEF (from sap_get_source). Required for all kinds except bdef-stub.' },
             field: {
                 type: 'string',
-                description: 'cds-field: the element to add, e.g. "Priority" or "priority as Priority". ddlx-lineitem / cds-lineitem: the field name to expose as a column. table-field: the field clause WITHOUT trailing ";", e.g. "reference : zde_reference". bdef-field: target="field" → a full field declaration "field ( readonly ) Reference"; target="mapping" → an assignment "Reference = reference" (no trailing ";"). Required for all kinds except bdef-stub.',
+                description: 'cds-field: the element to add, e.g. "Priority" or "priority as Priority". ddlx-lineitem / cds-lineitem: the field name to expose as a column. table-field: the field clause WITHOUT trailing ";", e.g. "reference : zde_reference". bdef-field: target="field" → a full field declaration "field ( readonly ) Reference"; target="mapping" → an assignment "Reference = reference" (no trailing ";"). ddlx-selectionfield: the field to expose as a filter. ddlx-identification: the field to annotate (required for a plain identification; optional anchor for a #FOR_ACTION button). Required for all kinds except bdef-stub, ddlx-headerinfo, and a FOR_ACTION ddlx-identification.',
             },
-            position: { type: 'number', description: 'kind=ddlx-lineitem and kind=cds-lineitem: the @UI.lineItem column position (default 10). kind=mde-action-button: optional column order for the inserted #FOR_ACTION entry. Ignored for other kinds.' },
+            position: { type: 'number', description: 'kind=ddlx-lineitem and kind=cds-lineitem: the @UI.lineItem column position (default 10). kind=ddlx-selectionfield: the @UI.selectionField filter order (default 10). kind=ddlx-identification: the @UI.identification position (default 10). kind=mde-action-button: optional column order for the inserted #FOR_ACTION entry. Ignored for other kinds.' },
             alias: { type: 'string', description: 'kind=bdef-field: the behavior entity alias to extend (`alias <ALIAS>`). Optional only when the BDEF defines exactly one behavior; required when several exist. kind=bdef-stub: optional when the BDEF defines exactly one behavior; required when several exist (mirrors bdef-field behavior). kind=projection-use: the projection behavior entity alias; required when the projection BDEF defines more than one behavior.' },
             target: { type: 'string', enum: ['field', 'mapping'], description: 'kind=bdef-field: "field" (default) adds a `field ( … )` line to the entity body; "mapping" adds an assignment line to the entity\'s mapping block.' },
             bdefSource: { type: 'string', description: 'kind=bdef-stub: full managed BDEF source (from sap_get_source).' },
@@ -140,9 +273,28 @@ registerTool({
             static: { type: 'boolean', description: 'kind=bdef-stub static (factory) action.' },
             features: { type: 'boolean', description: 'kind=bdef-stub feature-controlled action (features : instance).' },
             useClause: { type: 'string', description: 'kind=projection-use: the use clause to expose, e.g. "action Approve" or "association _Customer". Do NOT include a leading "use " or trailing ";". Required for projection-use.' },
-            action: { type: 'string', description: 'kind=mde-action-button: the action name to wire, e.g. "Approve". Required for mde-action-button.' },
+            action: { type: 'string', description: 'kind=mde-action-button: the action name to wire, e.g. "Approve" (required). kind=ddlx-identification: set this to emit a #FOR_ACTION Object-Page button for the named dataAction (omit for a plain field identification).' },
             anchorField: { type: 'string', description: 'kind=mde-action-button: the field name above which to insert the action button annotation. Required for mde-action-button.' },
-            label: { type: 'string', description: 'kind=mde-action-button: optional button label text. Defaults to the action name.' },
+            label: { type: 'string', description: 'kind=mde-action-button / kind=ddlx-identification (#FOR_ACTION): optional button label text. Defaults to the action name.' },
+            typeName: { type: 'string', description: 'kind=ddlx-headerinfo: singular Object-Page type name, e.g. "Maintenance Request". Required for ddlx-headerinfo.' },
+            typeNamePlural: { type: 'string', description: 'kind=ddlx-headerinfo: plural Object-Page type name, e.g. "Maintenance Requests". Required for ddlx-headerinfo.' },
+            titleField: { type: 'string', description: 'kind=ddlx-headerinfo: the field whose value renders as the header title. Required for ddlx-headerinfo.' },
+            descriptionField: { type: 'string', description: 'kind=ddlx-headerinfo: optional field for the header description line.' },
+            facetId: { type: 'string', description: 'kind=ddlx-facet: the facet id (idempotency key). Required for ddlx-facet.' },
+            fieldGroupQualifier: { type: 'string', description: 'kind=ddlx-facet: the field-group qualifier the facet targets and each per-field @UI.fieldGroup binds to. Required for ddlx-facet.' },
+            fields: { type: 'array', description: 'kind=ddlx-facet: the fields to place in the field group, each { field, position } — a @UI.fieldGroup annotation is added on each. Required for ddlx-facet.', items: { type: 'object', properties: { field: { type: 'string' }, position: { type: 'number' } }, required: ['field', 'position'] } },
+            title: { type: 'string', description: 'kind=ddlx-datapoint: the @UI.dataPoint title text. Required for ddlx-datapoint.' },
+            criticalityField: { type: 'string', description: 'kind=ddlx-datapoint: optional field name driving the data point criticality colour (the transform does NOT create this field).' },
+            entity: { type: 'string', description: 'kind=cds-valuehelp: the value-help provider CDS entity, e.g. "ZI_Customer". Required for cds-valuehelp.' },
+            element: { type: 'string', description: 'kind=cds-valuehelp: the provider element to bind to, e.g. "CustomerID". Required for cds-valuehelp.' },
+            additionalBinding: { type: 'object', description: 'kind=cds-valuehelp: optional extra value-help binding { localElement, element }.', properties: { localElement: { type: 'string' }, element: { type: 'string' } }, required: ['localElement', 'element'] },
+            entityAlias: { type: 'string', description: 'kind=bdef-sideeffects: the behavior entity alias to extend. Optional only when the BDEF defines exactly one behavior; required when several exist.' },
+            sourceFields: { type: 'array', description: 'kind=bdef-sideeffects: the trigger fields (`field <…>`), non-empty. Required for bdef-sideeffects.', items: { type: 'string' } },
+            targetFields: { type: 'array', description: 'kind=bdef-sideeffects: the affected fields (`affects field <…>`), non-empty. Required for bdef-sideeffects.', items: { type: 'string' } },
+            qualifier: { type: 'string', description: 'kind=ddlx-chart: optional qualifier binding the @UI.chart to its @UI.presentationVariant (idempotency key). Omit for an anonymous chart.' },
+            chartType: { type: 'string', enum: ['COLUMN', 'BAR', 'LINE', 'DONUT'], description: 'kind=ddlx-chart: the chart type, mapped to the CDS enum #COLUMN/#BAR/#LINE/#DONUT. Required for ddlx-chart.' },
+            dimensions: { type: 'array', description: 'kind=ddlx-chart: the chart dimension field names (non-empty). Required for ddlx-chart.', items: { type: 'string' } },
+            measures: { type: 'array', description: 'kind=ddlx-chart: the chart measure field names (non-empty). Required for ddlx-chart.', items: { type: 'string' } },
         },
         required: ['kind'],
     },

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

@@ -2,14 +2,18 @@
 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 use entityConfig.mainEntityName;
-    // OVP uses filterEntitySet (the modern replacement for the deprecated filterEntityType).
+    // 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 } } };
@@ -17,9 +21,19 @@ export async function scaffoldFioriElements(opts) {
     else if (opts.template === 'worklist') {
         template = { type: TemplateType.Worklist, settings: { entityConfig: { mainEntityName: opts.mainEntity } } };
     }
-    else {
+    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 };
@@ -31,6 +45,13 @@ export async function scaffoldFioriElements(opts) {
         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' },
@@ -41,5 +62,10 @@ export async function scaffoldFioriElements(opts) {
         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',
+};