@cspeach/cli 0.9.0 → 1.0.0

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

@@ -0,0 +1,188 @@
+/**
+ * `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, } 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 };
+        }
+    }
+    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 {
+            return {
+                content: `error: unknown kind "${String(kind)}" — expected "cds-field", "ddlx-lineitem", "cds-lineitem", "table-field", "bdef-field" or "bdef-stub"`,
+                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. 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'],
+                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.',
+            },
+            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.',
+            },
+            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.' },
+            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 for mde-action-button.' },
+            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.' },
+        },
+        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,
+});

package/dist/tools/fiori/apply.js

@@ -0,0 +1,50 @@
+// cspeach-cli/src/tools/fiori/apply.ts
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { getEntry } from './catalog/index.js';
+import { renderEntry } from './render.js';
+import { mergeManifest } from './manifest.js';
+import { appendI18n } from './i18n.js';
+import { resolveSafePath } from '../_filesystem-shared.js';
+/**
+ * Render a catalog entry and apply it into an existing scaffolded app on disk.
+ *
+ * SECURITY — containment is enforced HERE, on every write.
+ * --------------------------------------------------------
+ * Each output path is derived from a catalog EJS template rendered with
+ * CUSTOMER params (e.g. `webapp/ext/fragment/<%- ns %>Chart.fragment.xml`), so a
+ * hostile param could otherwise carry `..` and escape `appDir`. Every path this
+ * function writes — rendered files, manifest.json, and the i18n file (whose
+ * relative location is itself read from on-disk manifest data) — is resolved
+ * through `resolveSafePath(opts.appDir, rel)`, which throws PathOutsideRootError
+ * if the resolved absolute path is not contained under appDir. This is the
+ * authoritative defense; the catalog-side `ns` pattern (render.ts) is the
+ * second, earlier layer.
+ */
+export function applyEntry(opts) {
+    const rendered = renderEntry(getEntry(opts.entryName), opts.params);
+    // 1. write files — re-validate EVERY rendered (param-derived) path against appDir.
+    for (const f of rendered.files) {
+        const abs = resolveSafePath(opts.appDir, f.path);
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, f.content, 'utf8');
+    }
+    // 2. merge manifest — ALWAYS re-read from disk (I2). Fixed relative path, but
+    // routed through resolveSafePath for uniform containment.
+    const manifestPath = resolveSafePath(opts.appDir, 'webapp/manifest.json');
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    let merged = mergeManifest(manifest, rendered.manifestPatch);
+    for (const lib of rendered.libraries) {
+        merged = mergeManifest(merged, { 'sap.ui5': { dependencies: { libs: { [lib]: {} } } } });
+    }
+    writeFileSync(manifestPath, JSON.stringify(merged, null, 2), 'utf8');
+    // 3. append i18n — resolve path from sap.app.i18n (M1). i18nRel is on-disk
+    // data, not a render param, but it still drives a write target, so contain it.
+    const i18nRel = merged['sap.app']?.i18n ?? 'i18n/i18n.properties';
+    const i18nPath = resolveSafePath(opts.appDir, `webapp/${i18nRel}`);
+    const existing = existsSync(i18nPath) ? readFileSync(i18nPath, 'utf8') : '';
+    if (Object.keys(rendered.i18nKeys).length) {
+        mkdirSync(dirname(i18nPath), { recursive: true });
+        writeFileSync(i18nPath, appendI18n(existing, rendered.i18nKeys), 'utf8');
+    }
+}

package/dist/tools/fiori/bin.js

@@ -0,0 +1,3 @@
+// cspeach-cli/src/tools/fiori/bin.ts
+import { runFioriCli } from './cli.js';
+runFioriCli(process.argv.slice(2)).then((code) => process.exit(code));

package/dist/tools/fiori/catalog/index.js

@@ -0,0 +1,27 @@
+// cspeach-cli/src/tools/fiori/catalog/index.ts
+//
+// Catalog index for the Fiori engine.
+// v1 scope: only the two "fiddly" SAPUI5 patterns — viz-chart and value-help.
+// confirm-dialog (4.1), list-table-page (4.2), object-detail-page (4.3),
+// message-toast (4.4) are SKILL.md recipes, not catalog entries.
+import { vizChart } from './viz-chart.js';
+import { valueHelp } from './value-help.js';
+export const CATALOG = [vizChart, valueHelp];
+export function getEntry(name) {
+    const e = CATALOG.find((x) => x.name === name);
+    if (!e)
+        throw new Error(`Unknown catalog entry "${name}". Available: ${CATALOG.map((c) => c.name).join(', ')}`);
+    return e;
+}
+export function listCatalog() {
+    // params included so the agent can construct a correct `apply --params` call
+    // straight from `fiori list` — no trial-and-error against required-param errors.
+    return CATALOG.map(({ name, title, description, categories, libraries, params }) => ({
+        name,
+        title,
+        description,
+        categories,
+        libraries,
+        params,
+    }));
+}