@cspeach/cli 0.9.0 → 1.1.0

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

@@ -0,0 +1,340 @@
+/**
+ * `extend_model_insert` — the deterministic anchored-insertion tool behind the
+ * `abap-extend-model` skill (B1). The skill reads the live source with
+ * `sap_get_source`, calls THIS tool to produce the modified source via anchored
+ * insertion (never blind LLM string-editing), shows the preview, then drives the
+ * safe write chain (snapshot → sap_set_source → sap_syntax_check → sap_activate
+ * → republish-if-needed → rollback) with the existing sap_* tools.
+ *
+ * This tool is a PURE transform: it does not touch the SAP system, so it is
+ * non-mutating. It is flag-gated with the other local-build tools (rides the
+ * `local_build` switch via LOCAL_BUILD_TOOLS in tools/local-build.ts).
+ *
+ * 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, 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).
+    if (kind === 'bdef-stub') {
+        return handleBdefStub(args);
+    }
+    // projection-use and mde-action-button use `source` but NOT `field` — branch BEFORE the field guard.
+    if (kind === 'projection-use') {
+        if (typeof args.source !== 'string' || typeof args.useClause !== 'string' || args.useClause.trim() === '') {
+            return { content: 'error: projection-use requires source and a non-empty useClause (e.g. "action Approve")', is_error: true };
+        }
+        try {
+            const modified = insertProjectionUse(args.source, { alias: args.alias, useClause: args.useClause });
+            return { content: JSON.stringify({ modified, summary: `Exposed "use ${args.useClause}" in the projection BDEF${args.alias ? ` (alias ${args.alias})` : ''}.` }) };
+        }
+        catch (err) {
+            return { content: `error: projection-use failed — ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+        }
+    }
+    if (kind === 'mde-action-button') {
+        if (typeof args.source !== 'string' || typeof args.action !== 'string' || args.action.trim() === '' || typeof args.anchorField !== 'string' || args.anchorField.trim() === '') {
+            return { content: 'error: mde-action-button requires source and non-empty action and anchorField', is_error: true };
+        }
+        try {
+            const modified = insertMdeActionButton(args.source, {
+                action: args.action, label: args.label, position: args.position, anchorField: args.anchorField,
+            });
+            return { content: JSON.stringify({ modified, summary: `Added FE action button for '${args.action}' above ${args.anchorField} in the metadata extension.` }) };
+        }
+        catch (err) {
+            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 };
+    }
+    try {
+        let modified;
+        let summary;
+        if (kind === 'cds-field') {
+            modified = insertCdsField(source, field);
+            summary = `Inserted element "${field}" into the CDS view's element list (prior last element gained a trailing comma).`;
+        }
+        else if (kind === 'ddlx-lineitem') {
+            const position = typeof args.position === 'number' ? args.position : 10;
+            modified = insertDdlxLineItem(source, field, position);
+            summary = `Added "${field}" as an @UI.lineItem column at position ${position} in the DDLX metadata extension.`;
+        }
+        else if (kind === 'cds-lineitem') {
+            const position = typeof args.position === 'number' ? args.position : 10;
+            modified = promoteCdsFieldToLineItem(source, field, position);
+            summary = `Promoted field '${field}' to a list column (@UI.lineItem position ${position}) in the CDS view.`;
+        }
+        else if (kind === 'table-field') {
+            modified = addTableField(source, field);
+            summary = `Added field '${field}' to the table.`;
+        }
+        else if (kind === 'bdef-field') {
+            const target = args.target === 'mapping' ? 'mapping' : 'field';
+            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", "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,
+            };
+        }
+        return { content: JSON.stringify({ modified, summary }) };
+    }
+    catch (err) {
+        return {
+            content: `error: anchored insertion failed — ${err instanceof Error ? err.message : String(err)}`,
+            is_error: true,
+        };
+    }
+}
+registerTool({
+    name: 'extend_model_insert',
+    description: 'Deterministically insert a field or @UI.lineItem column into existing CDS/DDLX source via '
+        + 'anchored insertion (no DSL parser, no blind string-editing). Returns the modified source for '
+        + 'the caller to snapshot, write (sap_set_source), syntax-check, and activate. kind="cds-field" '
+        + 'adds an element to a CDS view body; kind="ddlx-lineitem" adds an @UI.lineItem-annotated field '
+        + 'to a DDLX metadata extension (the Fiori Elements column-add); kind="cds-lineitem" promotes an '
+        + 'EXISTING exposed CDS-view field to a list column by inserting @UI.lineItem above its declaration '
+        + '(fail-safe: refuses multi-line/computed elements, idempotent); kind="table-field" appends a '
+        + 'NON-KEY field to a CDS `define table` body (refuses key fields — destructive); kind="bdef-field" '
+        + 'adds a `field ( … )` or mapping line to a MANAGED BDEF entity (target="field"|"mapping", optional '
+        + 'alias; refuses unmanaged); kind="bdef-stub" adds a validation/determination/action clause to a '
+        + '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; '
+        + '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,
+    input_schema: {
+        type: 'object',
+        properties: {
+            kind: {
+                type: 'string',
+                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 ";"). 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=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).' },
+            ccimpSource: { type: 'string', description: 'kind=bdef-stub: full CCIMP ("Local Types") include source of the behavior pool class (may be empty).' },
+            stubKind: { type: 'string', enum: ['validation', 'determination', 'action'], description: 'kind=bdef-stub: which clause to add.' },
+            name: { type: 'string', description: 'kind=bdef-stub: the validation/determination/action name (e.g. ValidateInstructorName).' },
+            trigger: { type: 'string', enum: ['modify', 'save'], description: 'kind=bdef-stub determination trigger point (default modify).' },
+            ops: { type: 'string', description: 'kind=bdef-stub validation/determination operations, e.g. "create; update;".' },
+            parameter: { type: 'string', description: 'kind=bdef-stub action input parameter type (CDS abstract entity).' },
+            result: { type: 'boolean', description: 'kind=bdef-stub action declares a result.' },
+            resultType: { type: 'string', description: 'kind=bdef-stub action result type (default $self; required-typed for static actions).' },
+            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). 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 / 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'],
+    },
+    handler: extendModelInsertHandler,
+});
+function handleBdefStub(args) {
+    const { bdefSource, ccimpSource, stubKind, name, alias } = args;
+    if (typeof bdefSource !== 'string' || typeof ccimpSource !== 'string') {
+        return { content: 'error: bdef-stub requires bdefSource and ccimpSource (strings)', is_error: true };
+    }
+    if (!stubKind || !['validation', 'determination', 'action'].includes(stubKind)) {
+        return { content: 'error: bdef-stub requires stubKind = validation|determination|action', is_error: true };
+    }
+    if (typeof name !== 'string' || name.trim() === '') {
+        return { content: 'error: bdef-stub requires a non-empty name', is_error: true };
+    }
+    try {
+        // Resolve alias: auto-picks the single behavior when no alias is given;
+        // throws (→ is_error) on ambiguity or missing behavior — same policy as bdef-field.
+        const entityAlias = alias ?? resolveBehaviorAlias(bdefSource);
+        const clauseLine = buildClauseLine(stubKind, {
+            name, ops: args.ops, trigger: args.trigger, parameter: args.parameter,
+            result: args.result, resultType: args.resultType, static: args.static, features: args.features,
+        });
+        const method = buildHandlerMethod(stubKind, {
+            name, entity: entityAlias, trigger: args.trigger, parameter: args.parameter,
+            result: args.result, features: args.features,
+        });
+        const modifiedBdef = insertBdefClause(bdefSource, { alias: entityAlias, clauseLine });
+        const className = `lhc_${entityAlias.toLowerCase()}`;
+        const exists = classBlockSpan(ccimpSource.split('\n'), className) !== null;
+        const modifiedCcimp = exists
+            ? insertHandlerMethod(ccimpSource, { entity: entityAlias, method })
+            : createHandlerClassSkeleton(ccimpSource, { entity: entityAlias, method });
+        const summary = `Added ${stubKind} '${name}' to BDEF (alias ${entityAlias}) and ${exists ? 'inserted the handler method into' : 'created'} ${className}.`;
+        return { content: JSON.stringify({ modifiedBdef, modifiedCcimp, createdHandlerClass: !exists, summary }) };
+    }
+    catch (err) {
+        return { content: `error: bdef-stub failed — ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+}
+// Exported for unit tests.
+export const __extendModelInsertHandler = extendModelInsertHandler;

package/dist/tools/filesystem/extract-document.js

@@ -0,0 +1,57 @@
+// Pure document text extraction. No filesystem, no network — buffer in, text
+// out. Unit-tested directly; the read_document tool wraps it with containment.
+import { extractText, getDocumentProxy } from 'unpdf';
+import mammoth from 'mammoth';
+import TurndownService from 'turndown';
+/** Thrown when a PDF exceeds the caller's page ceiling — checked before full extraction. */
+export class DocumentTooLargeError extends Error {
+    pages;
+    limit;
+    constructor(pages, limit) {
+        super(`document has ${pages} pages, exceeding the ${limit}-page limit`);
+        this.pages = pages;
+        this.limit = limit;
+        this.name = 'DocumentTooLargeError';
+    }
+}
+const NO_TEXT_WARNING = 'no extractable text — likely a scanned PDF; OCR is not supported';
+export async function extractDocument(buffer, ext, opts) {
+    if (ext === '.pdf')
+        return extractPdf(buffer, opts?.maxPages);
+    if (ext === '.docx')
+        return extractDocx(buffer);
+    throw new Error(`extractDocument: unsupported extension "${ext}"`);
+}
+async function extractPdf(buffer, maxPages) {
+    // unpdf's bundled pdfjs rejects Buffer instances even though Buffer extends Uint8Array
+    // (it does an explicit constructor check). Wrapping is required.
+    const pdf = await getDocumentProxy(new Uint8Array(buffer));
+    // Check limit before full extraction to avoid unnecessary work
+    const total = pdf.numPages;
+    if (maxPages !== undefined && total > maxPages) {
+        throw new DocumentTooLargeError(total, maxPages);
+    }
+    // Fix 3: unpdf with mergePages:false always returns string[]; use it directly.
+    const { text } = await extractText(pdf, { mergePages: false });
+    // Fix 1: per-page emptiness detection — correctly handles mixed-content PDFs
+    // and avoids false-positives from literal "[page N]" text in the document.
+    let hasText = false;
+    const body = text.map((t, i) => {
+        const trimmed = (t ?? '').trim();
+        if (trimmed.length > 0)
+            hasText = true;
+        return `[page ${i + 1}]\n${trimmed}`;
+    }).join('\n\n');
+    return { text: body, pages: total, warnings: hasText ? [] : [NO_TEXT_WARNING] };
+}
+async function extractDocx(buffer) {
+    // Fix 2: esModuleInterop:true makes the default import correct — no interop guard needed.
+    const { value: html } = await mammoth.convertToHtml({ buffer });
+    const td = new TurndownService({ headingStyle: 'atx', bulletListMarker: '-' });
+    const raw = td.turndown(html).trim();
+    // Turndown emits "-   text" (3 spaces) for bullet items; collapse to "- text".
+    // The regex anchors on a line-leading "-" so mid-line double spaces (e.g. "Col A  Col B")
+    // and indented nested bullets (leading whitespace is captured in $1) are both preserved.
+    const md = raw.replace(/^([ \t]*)-[ \t]{2,}/gm, '$1- ');
+    return { text: md, warnings: md.length === 0 ? ['no extractable text in document'] : [] };
+}

package/dist/tools/filesystem/file-edit.js

@@ -14,7 +14,7 @@
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { registerTool } from '../index.js';
-import { resolveSafePath, assertRealPathContained, PathOutsideRootError, BLOCKED_PREFIXES, isDenylistedPath, } from '../_filesystem-shared.js';
+import { resolveSafePath, assertRealPathContained, PathOutsideRootError, DENYLIST_DESCRIPTION, isDenylistedPath, blockedExecutableExtension, } from '../_filesystem-shared.js';
 export async function fileEditHandler(args, ctx) {
     // 1. Validate args before any IO
     if (args.old_string === args.new_string) {
@@ -52,7 +52,17 @@ export async function fileEditHandler(args, ctx) {
     const denylist = isDenylistedPath(realAbs, ctx.cwd);
     if (denylist.blocked) {
         return {
-            content: `error: refusing to edit sensitive path "${denylist.relFromRoot}" (denylist: ${BLOCKED_PREFIXES.join(', ')})`,
+            content: `error: refusing to edit sensitive path "${denylist.relFromRoot}" (denylist: ${DENYLIST_DESCRIPTION})`,
+            is_error: true,
+        };
+    }
+    // 4b. Executable-extension denylist: refuse mutating an executable/script
+    //     shim (same threat class as planting one — keeps file_edit from being
+    //     an alternate path to a malicious .cmd/.exe/etc.).
+    const badExt = blockedExecutableExtension(realAbs);
+    if (badExt !== null) {
+        return {
+            content: `error: refusing to write executable file type ${badExt} — not permitted`,
             is_error: true,
         };
     }

package/dist/tools/filesystem/file-read.js

@@ -10,7 +10,7 @@
  */
 import { promises as fs } from 'node:fs';
 import { registerTool } from '../index.js';
-import { resolveSafePath, assertRealPathContained, PathOutsideRootError, BLOCKED_PREFIXES, isDenylistedPath } from '../_filesystem-shared.js';
+import { resolveSafePath, assertRealPathContained, PathOutsideRootError, DENYLIST_DESCRIPTION, isDenylistedPath } from '../_filesystem-shared.js';
 const MAX_LINES = 2000;
 export async function fileReadHandler(args, ctx) {
     // Validate offset and limit BEFORE clamping
@@ -47,7 +47,7 @@ export async function fileReadHandler(args, ctx) {
     const denylist = isDenylistedPath(realAbs, ctx.cwd);
     if (denylist.blocked) {
         return {
-            content: `error: refusing to read sensitive path "${denylist.relFromRoot}" (denylist: ${BLOCKED_PREFIXES.join(', ')})`,
+            content: `error: refusing to read sensitive path "${denylist.relFromRoot}" (denylist: ${DENYLIST_DESCRIPTION})`,
             is_error: true,
         };
     }

package/dist/tools/filesystem/file-write.js

@@ -20,7 +20,7 @@
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { registerTool } from '../index.js';
-import { resolveSafePath, assertRealPathContained, PathOutsideRootError, BLOCKED_PREFIXES, isDenylistedPath, } from '../_filesystem-shared.js';
+import { resolveSafePath, assertRealPathContained, PathOutsideRootError, DENYLIST_DESCRIPTION, isDenylistedPath, blockedExecutableExtension, } from '../_filesystem-shared.js';
 export async function fileWriteHandler(args, ctx) {
     // 1. Path containment — sync phase (pure string math, catches .. traversals)
     let abs;
@@ -77,7 +77,16 @@ export async function fileWriteHandler(args, ctx) {
     const denylist = isDenylistedPath(target, ctx.cwd);
     if (denylist.blocked) {
         return {
-            content: `error: refusing to write sensitive path "${denylist.relFromRoot}" (denylist: ${BLOCKED_PREFIXES.join(', ')})`,
+            content: `error: refusing to write sensitive path "${denylist.relFromRoot}" (denylist: ${DENYLIST_DESCRIPTION})`,
+            is_error: true,
+        };
+    }
+    // 3b. Executable-extension denylist: refuse planting an executable/script
+    //     shim (defense-in-depth against the cross-spawn cwd-first vector).
+    const badExt = blockedExecutableExtension(target);
+    if (badExt !== null) {
+        return {
+            content: `error: refusing to write executable file type ${badExt} — not permitted`,
             is_error: true,
         };
     }

package/dist/tools/filesystem/glob.js

@@ -113,6 +113,17 @@ export async function globHandler(args, ctx) {
             if (budget <= 0 || collected.length >= MAX_RESULTS * 4)
                 return;
             const relPath = relPrefix ? `${relPrefix}/${ent.name}` : ent.name;
+            // Sandbox escape guard: never descend into a symlink. fs.readdir follows
+            // directory symlinks, so a pre-existing in-root symlink (e.g.
+            // `data -> /etc`) would otherwise leak filenames from OUTSIDE root.
+            // The Dirent reflects the link itself (lstat semantics): a symlink to a
+            // directory reports isSymbolicLink()=true and isDirectory()=false, so we
+            // must check the symlink case explicitly and skip it. A scaffolded UI5
+            // project has no legitimate reason to need glob to follow a symlink out
+            // of the sandbox root.
+            if (ent.isSymbolicLink()) {
+                continue;
+            }
             if (ent.isDirectory()) {
                 if (ALWAYS_SKIPPED_DIRS.has(ent.name))
                     continue;

package/dist/tools/filesystem/grep.js

@@ -78,6 +78,16 @@ export async function grepHandler(args, ctx) {
             if (budget <= 0 || matches.length >= MAX_MATCHES)
                 return;
             const relPath = relPrefix ? `${relPrefix}/${ent.name}` : ent.name;
+            // Sandbox escape guard: never descend into a symlink. fs.readdir follows
+            // directory symlinks, so a pre-existing in-root symlink (e.g.
+            // `vendor -> ~/.ssh`) would otherwise let grep read + return content from
+            // OUTSIDE root. The Dirent reflects the link itself (lstat semantics): a
+            // symlink to a directory reports isSymbolicLink()=true and
+            // isDirectory()=false, so we must check the symlink case explicitly and
+            // skip it.
+            if (ent.isSymbolicLink()) {
+                continue;
+            }
             if (ent.isDirectory()) {
                 if (ALWAYS_SKIPPED_DIRS.has(ent.name))
                     continue;

package/dist/tools/filesystem/read-document.js

@@ -0,0 +1,107 @@
+/**
+ * read_document — extract text from a .pdf or .docx and return it with line
+ * numbers, page/heading markers, and a one-line header. Reuses file_read's
+ * path containment + denylist + 2000-line windowing. Flag-gated:
+ * CSPEACH_TOOL_READ_DOCUMENT=on (enabled together with the local_build set).
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { registerTool } from '../index.js';
+import { resolveSafePath, assertRealPathContained, PathOutsideRootError, DENYLIST_DESCRIPTION, isDenylistedPath, } from '../_filesystem-shared.js';
+import { extractDocument, DocumentTooLargeError } from './extract-document.js';
+const MAX_LINES = 2000;
+const MAX_BYTES = 50 * 1024 * 1024; // 50 MB
+const MAX_PAGES = 150;
+const SUPPORTED = new Set(['.pdf', '.docx']);
+export async function readDocumentHandler(args, ctx) {
+    if (args.offset !== undefined && args.offset < 0) {
+        return { content: `error: offset must be non-negative (got ${args.offset})`, is_error: true };
+    }
+    if (args.limit !== undefined && args.limit < 1) {
+        return { content: `error: limit must be a positive integer (got ${args.limit})`, is_error: true };
+    }
+    let abs;
+    try {
+        abs = resolveSafePath(ctx.cwd, args.path);
+    }
+    catch (err) {
+        if (err instanceof PathOutsideRootError)
+            return { content: `error: ${err.message}`, is_error: true };
+        return { content: `error: ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    const ext = path.extname(abs).toLowerCase();
+    if (!SUPPORTED.has(ext)) {
+        return {
+            content: `error: read_document supports .pdf and .docx; convert "${args.path}" first (.doc/.pptx/scanned images are not supported)`,
+            is_error: true,
+        };
+    }
+    let realAbs;
+    try {
+        realAbs = await assertRealPathContained(abs, ctx.cwd);
+    }
+    catch (err) {
+        if (err instanceof PathOutsideRootError)
+            return { content: `error: ${err.message} (after symlink resolution)`, is_error: true };
+        if (err.code === 'ENOENT')
+            return { content: 'error: file not found', is_error: true };
+        return { content: `error: ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    const denylist = isDenylistedPath(realAbs, ctx.cwd);
+    if (denylist.blocked) {
+        return { content: `error: refusing to read sensitive path "${denylist.relFromRoot}" (denylist: ${DENYLIST_DESCRIPTION})`, is_error: true };
+    }
+    let stat;
+    try {
+        stat = await fs.stat(realAbs);
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return { content: 'error: file not found', is_error: true };
+        return { content: `error: ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    if (stat.size > MAX_BYTES) {
+        return { content: `error: "${args.path}" is ${(stat.size / 1048576).toFixed(1)} MB, exceeding the ${MAX_BYTES / 1048576} MB limit`, is_error: true };
+    }
+    let result;
+    try {
+        const buffer = await fs.readFile(realAbs);
+        result = await extractDocument(buffer, ext, { maxPages: MAX_PAGES });
+    }
+    catch (err) {
+        if (err instanceof DocumentTooLargeError) {
+            return { content: `error: "${args.path}" has ${err.pages} pages, exceeding the ${err.limit}-page limit`, is_error: true };
+        }
+        return { content: `error: could not read "${args.path}": ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    // 'document' is the intentional label for .docx: result.pages is PDF-only and undefined for Word files.
+    const header = `${args.path} — ${result.pages !== undefined ? `${result.pages} pages` : 'document'}`;
+    const warnLines = result.warnings.map((w) => `[warning] ${w}`);
+    const allLines = result.text.replace(/\n$/, '').split('\n');
+    const offset = Math.max(0, args.offset ?? 0);
+    const limit = Math.min(args.limit ?? MAX_LINES, MAX_LINES);
+    const window = allLines.slice(offset, offset + limit);
+    const numbered = window.map((line, i) => `${offset + i + 1}\t${line}`).join('\n');
+    const truncated = allLines.length > offset + window.length;
+    const trailer = truncated
+        ? `\n... (truncated, ${allLines.length - (offset + window.length)} more lines — re-read with offset=${offset + window.length})`
+        : '';
+    return { content: [header, ...warnLines, numbered].join('\n') + trailer };
+}
+registerTool({
+    name: 'read_document',
+    description: 'Read a .pdf or .docx and return its extracted text with page/heading markers and line numbers. Optional offset + limit for windowed reads of large documents.',
+    isMutating: false,
+    category: 'filesystem',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'Path to a .pdf or .docx, relative to the project root or absolute inside it.' },
+            offset: { type: 'number', description: 'Optional 0-based line offset into the extracted text.' },
+            limit: { type: 'number', description: 'Optional max lines to return (cap 2000).' },
+        },
+        required: ['path'],
+    },
+    handler: readDocumentHandler,
+});