@cspeach/cli 0.8.0 → 1.0.0

package/dist/tools/fiori/manifest.js

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

package/dist/tools/fiori/render.js

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

package/dist/tools/fiori/scaffold.js

@@ -0,0 +1,39 @@
+// cspeach-cli/src/tools/fiori/scaffold.ts
+import { generate, TemplateType } from '@sap-ux/fiori-freestyle-writer';
+import { create } from 'mem-fs';
+import { create as createEditor } from 'mem-fs-editor';
+// Without an explicit ui5 config the writer falls back to minUI5Version 1.60,
+// which fiori-tools-proxy resolves to the 1.71 LTS — whose bootstrap does NOT
+// understand the hyphenated `data-sap-ui-on-init` attribute the writer itself
+// emits in index.html. Result: silent blank page (ComponentSupport never runs).
+// 1.120 is the S/4HANA 2023-era LTS and parses the modern attribute.
+const DEFAULT_UI5_VERSION = '1.120.0';
+const TEMPLATE = {
+    basic: TemplateType.Basic, worklist: TemplateType.Worklist, listdetail: TemplateType.ListDetail,
+};
+/** Scaffold a freestyle UI5 app and FULLY flush it to disk (awaits commit). */
+export async function scaffoldFreestyle(opts) {
+    const fs = createEditor(create());
+    // NOTE (Phase-0 spike finding): the real freestyle-writer@3 API REQUIRES
+    // `app.projectType` and a `package` object — without them ui5-application-writer
+    // throws `Cannot read properties of undefined (reading 'version')`.
+    // 'EDMXBackend' = standalone (non-CAP) freestyle app.
+    const ui5Version = opts.ui5Version ?? DEFAULT_UI5_VERSION;
+    const data = {
+        app: { id: opts.appId, title: opts.appTitle, projectType: 'EDMXBackend' },
+        package: { name: opts.appId },
+        template: { type: TEMPLATE[opts.template], settings: opts.template === 'basic' ? { viewName: 'Main' } : {} },
+        appOptions: { typescript: opts.typescript ?? false },
+        ui5: { minUI5Version: ui5Version, version: ui5Version },
+    };
+    if (opts.service) {
+        // The writer's OdataVersion enum is '2' | '4' — NOT '2.0'/'4.0'. Passing
+        // '4.0' matches neither, and the writer silently skips the version-specific
+        // manifest wiring (settings.odataVersion, V4 model defaults), leaving the
+        // default model to instantiate as a V2 ODataModel against a V4 service.
+        const writerVersion = opts.service.version === '4.0' ? '4' : '2';
+        data.service = { url: opts.service.url, path: opts.service.path, version: writerVersion };
+    }
+    await generate(opts.basePath, data, fs);
+    await new Promise((res, rej) => fs.commit((err) => (err ? rej(err) : res())));
+}

package/dist/tools/fiori/tools.js

@@ -0,0 +1,356 @@
+/**
+ * Fiori engine tools — built-in, flag-gated wrappers around the existing
+ * CSPeach Fiori engine (scaffold.ts, apply.ts, catalog/, deploy-config.ts).
+ *
+ * WHY THESE EXIST
+ * ---------------
+ * The engine has always been OUR code (cspeach-cli/src/tools/fiori/), but it
+ * was only reachable through `pnpm fiori <cmd>` (bin.ts → cli.ts), a pnpm
+ * script that only works INSIDE the repo. Customers on the shipped npm
+ * `@cspeach/cli` binary could not run it, so the /abap-fiori-build skill had to
+ * improvise file writes by hand — non-deterministic output per customer.
+ *
+ * These tools register the same engine functions as first-class tools so every
+ * customer gets the SAME deterministic scaffold/apply/deploy-config behavior,
+ * no pnpm and no repo required. They DO NOT reimplement the engine — each
+ * handler calls the existing scaffoldFreestyle()/applyEntry()/listCatalog()/
+ * writeDeployConfig() exports.
+ *
+ * SANDBOX (defense in depth)
+ * --------------------------
+ * These tools write file trees (basePath / appDir). Sandboxing is enforced at
+ * TWO layers, because the appDir boundary alone is not sufficient:
+ *
+ *   1. Tool boundary: the customer-supplied basePath/appDir is run through
+ *      resolveSafePath(ctx.cwd, …) so the app ROOT cannot escape the project.
+ *
+ *   2. Engine boundary (the real fix): applyEntry() re-validates EVERY file it
+ *      writes against appDir via resolveSafePath(appDir, renderedPath). This is
+ *      required because catalog templates render OUTPUT PATHS from customer
+ *      params (e.g. `webapp/ext/fragment/<%- ns %>Chart.fragment.xml`) — a
+ *      hostile `ns` could otherwise carry `..` and write CONTENT outside the
+ *      app root even though appDir itself was contained. A matching catalog-side
+ *      `ns` pattern (render.ts) rejects such values even earlier.
+ *
+ * So: a `..`-traversal cannot escape via the appDir arg NOR via a param that
+ * lands in a rendered path.
+ *
+ * FLAG / LOCAL_BUILD
+ * ------------------
+ * All four are flagGated:true (category 'fiori') and listed in
+ * LOCAL_BUILD_TOOLS, so `cspeach config set local_build on` enables them
+ * alongside file_write/shell_exec — they are part of "build apps locally".
+ *
+ * `pnpm fiori` (bin.ts/cli.ts) is UNTOUCHED and still works for repo dev; these
+ * tools are an additional surface, not a replacement.
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { registerTool } from '../index.js';
+import { resolveSafePath, PathOutsideRootError } from '../_filesystem-shared.js';
+import { scaffoldFreestyle } from './scaffold.js';
+import { applyEntry } from './apply.js';
+import { listCatalog } from './catalog/index.js';
+import { writeDeployConfig } from './deploy-config.js';
+import { scaffoldFioriElements } from './fe-scaffold.js';
+/** Resolve a user-supplied dir inside the project root, mapping the escape error. */
+function safeDir(ctx, userPath) {
+    try {
+        return { abs: resolveSafePath(ctx.cwd, userPath) };
+    }
+    catch (err) {
+        if (err instanceof PathOutsideRootError)
+            return { error: err.message };
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Relative-to-cwd, forward-slash path for stable, readable result strings. */
+function rel(ctx, abs) {
+    return path.relative(path.resolve(ctx.cwd), abs).replace(/\\/g, '/') || '.';
+}
+/** Recursively list files under `dir` as cwd-relative paths (sorted). */
+async function listFilesUnder(ctx, dir) {
+    const out = [];
+    async function walk(d) {
+        let entries;
+        try {
+            entries = await fs.readdir(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const full = path.join(d, e.name);
+            if (e.isDirectory())
+                await walk(full);
+            else
+                out.push(rel(ctx, full));
+        }
+    }
+    await walk(dir);
+    return out.sort();
+}
+// ───────────────────────────── fiori_scaffold ─────────────────────────────
+export async function fioriScaffoldHandler(args, ctx) {
+    if (!args.basePath)
+        return { content: 'error: basePath is required', is_error: true };
+    if (!args.appId)
+        return { content: 'error: appId is required', is_error: true };
+    const resolved = safeDir(ctx, args.basePath);
+    if ('error' in resolved)
+        return { content: `error: ${resolved.error}`, is_error: true };
+    try {
+        await scaffoldFreestyle({
+            basePath: resolved.abs,
+            appId: args.appId,
+            appTitle: args.appTitle ?? args.appId,
+            template: args.template ?? 'basic',
+            service: args.serviceUrl
+                ? { url: args.serviceUrl, path: args.servicePath ?? '', version: args.serviceVersion ?? '4.0' }
+                : undefined,
+            typescript: args.typescript ?? false,
+            ui5Version: args.ui5Version,
+        });
+    }
+    catch (err) {
+        return { content: `error: scaffold failed — ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    const files = await listFilesUnder(ctx, resolved.abs);
+    const appDir = rel(ctx, resolved.abs);
+    return {
+        content: `Scaffolded freestyle app "${args.appId}" into ${appDir}/ (${files.length} files).\n` +
+            `App dir: ${appDir}\n` +
+            `Files:\n${files.map((f) => `  ${f}`).join('\n')}`,
+    };
+}
+// ─────────────────────────────── fiori_apply ──────────────────────────────
+export async function fioriApplyHandler(args, ctx) {
+    if (!args.appDir)
+        return { content: 'error: appDir is required', is_error: true };
+    if (!args.entry)
+        return { content: 'error: entry is required', is_error: true };
+    const resolved = safeDir(ctx, args.appDir);
+    if ('error' in resolved)
+        return { content: `error: ${resolved.error}`, is_error: true };
+    // Params may arrive as a parsed object (preferred) or a JSON string (mirrors
+    // the `--params '<json>'` CLI flag). Tolerate both.
+    let params;
+    if (typeof args.params === 'string') {
+        try {
+            params = args.params.trim() ? JSON.parse(args.params) : {};
+        }
+        catch (err) {
+            return { content: `error: params is not valid JSON — ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+        }
+    }
+    else {
+        params = args.params ?? {};
+    }
+    try {
+        // applyEntry preserves the engine's loud-on-conflict manifest merge — a
+        // conflicting manifest patch throws here and surfaces as is_error, never a
+        // silent last-wins overwrite.
+        applyEntry({ appDir: resolved.abs, entryName: args.entry, params });
+    }
+    catch (err) {
+        return { content: `error: apply failed — ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    return {
+        content: `Applied catalog entry "${args.entry}" into ${rel(ctx, resolved.abs)}.\n` +
+            `Entry files written, manifest.json deep-merged (loud on conflict), i18n keys appended.`,
+    };
+}
+// ─────────────────────────────── fiori_list ───────────────────────────────
+export async function fioriListHandler(_args, _ctx) {
+    // listCatalog() returns each entry's param specs so the model can build a
+    // correct fiori_apply params object in one shot (no required-param iteration).
+    const entries = listCatalog();
+    return { content: JSON.stringify(entries, null, 2) };
+}
+// ──────────────────────────── fiori_deploy_config ─────────────────────────
+export async function fioriDeployConfigHandler(args, ctx) {
+    if (!args.appDir)
+        return { content: 'error: appDir is required', is_error: true };
+    if (!args.url)
+        return { content: 'error: url is required', is_error: true };
+    if (!args.client)
+        return { content: 'error: client is required', is_error: true };
+    if (!args.name)
+        return { content: 'error: name (BSP app name) is required', is_error: true };
+    if (!args.package)
+        return { content: 'error: package is required', is_error: true };
+    const resolved = safeDir(ctx, args.appDir);
+    if ('error' in resolved)
+        return { content: `error: ${resolved.error}`, is_error: true };
+    try {
+        writeDeployConfig(resolved.abs, {
+            url: args.url,
+            client: args.client,
+            appName: args.name,
+            description: args.description,
+            package: args.package,
+            transport: args.transport ?? '',
+            ignoreCertErrors: args.ignoreCertErrors === true,
+        });
+    }
+    catch (err) {
+        // writeDeployConfig validates app-name length/case, package namespace, and
+        // transport format — those validation errors surface here as is_error.
+        return { content: `error: deploy-config failed — ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    const appDir = rel(ctx, resolved.abs);
+    return {
+        content: `Deploy config written: ${appDir}/ui5-deploy.yaml (BSP app ${args.name} → package ${args.package}` +
+            `${args.transport ? `, transport ${args.transport}` : ''}).\n` +
+            `package.json gained "deploy" and "deploy-test" scripts. Run "npm run deploy-test" to validate without deploying.`,
+    };
+}
+// ──────────────────────────── fiori_scaffold_fe ───────────────────────────
+export async function fioriScaffoldFeHandler(args, ctx) {
+    if (!args.basePath)
+        return { content: 'error: basePath is required', is_error: true };
+    if (!args.appId)
+        return { content: 'error: appId is required', is_error: true };
+    if (!args.mainEntity)
+        return { content: 'error: mainEntity is required', is_error: true };
+    // metadata is OPTIONAL (the FE writer does not need it — spike §4); no $metadata fetch.
+    const resolved = safeDir(ctx, args.basePath);
+    if ('error' in resolved)
+        return { content: `error: ${resolved.error}`, is_error: true };
+    try {
+        await scaffoldFioriElements({
+            basePath: resolved.abs,
+            appId: args.appId,
+            appTitle: args.appTitle ?? args.appId,
+            template: args.template ?? 'lrop',
+            service: { url: args.serviceUrl, path: args.servicePath, version: args.serviceVersion ?? '4.0', metadata: args.metadata, client: args.client },
+            mainEntity: args.mainEntity,
+            ui5Version: args.ui5Version,
+        });
+    }
+    catch (err) {
+        return { content: `error: FE scaffold failed — ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    const files = await listFilesUnder(ctx, resolved.abs);
+    const appDir = rel(ctx, resolved.abs);
+    return {
+        content: `Scaffolded Fiori Elements ${args.template ?? 'lrop'} app "${args.appId}" into ${appDir}/ (${files.length} files).\n` +
+            `Driven by the service's backend @UI annotations (no local annotation.xml). App dir: ${appDir}\n` +
+            `Files:\n${files.map((f) => `  ${f}`).join('\n')}`,
+    };
+}
+// ─────────────────────────────── registration ─────────────────────────────
+registerTool({
+    name: 'fiori_scaffold',
+    description: 'Scaffold a complete freestyle SAPUI5 app (webapp/ tree: manifest.json, index.html, ' +
+        'Component.js, a Main view+controller, i18n, ui5.yaml, package.json) into a project ' +
+        'directory. Built-in CSPeach Fiori engine — no pnpm or repo needed. Optionally wires a ' +
+        'primary OData V2/V4 service. basePath is sandboxed to the project root.',
+    isMutating: true,
+    category: 'fiori',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            basePath: { type: 'string', description: 'Directory to scaffold into (relative to project root, created if missing).' },
+            appId: { type: 'string', description: 'App namespace in reverse-domain form, e.g. "zso.orderlist".' },
+            appTitle: { type: 'string', description: 'Human-readable app title. Defaults to appId.' },
+            template: { type: 'string', enum: ['basic', 'worklist', 'listdetail'], description: 'Base template. Default "basic".' },
+            serviceUrl: { type: 'string', description: 'Backend host for the primary OData service, e.g. "https://host:44300".' },
+            servicePath: { type: 'string', description: 'Relative OData service path, e.g. "/sap/opu/odata4/zso/srv/".' },
+            serviceVersion: { type: 'string', enum: ['2.0', '4.0'], description: 'OData version of the primary service. Default "4.0".' },
+            typescript: { type: 'boolean', description: 'Generate a TypeScript app. Default false.' },
+            ui5Version: { type: 'string', description: 'UI5 version for manifest minUI5Version + preview. Default 1.120.0. Do not go below 1.84.' },
+        },
+        required: ['basePath', 'appId'],
+    },
+    handler: fioriScaffoldHandler,
+});
+registerTool({
+    name: 'fiori_apply',
+    description: 'Apply a catalog pattern (viz-chart or value-help) into an already-scaffolded app. ' +
+        'Renders the entry, writes its files, deep-merges manifest.json (errors loudly on ' +
+        'conflict — never silent last-wins), and appends i18n keys. Call fiori_list first to ' +
+        'read each entry\'s param specs. appDir is sandboxed to the project root.',
+    isMutating: true,
+    category: 'fiori',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            appDir: { type: 'string', description: 'Root directory of the already-scaffolded app (relative to project root).' },
+            entry: { type: 'string', description: 'Catalog entry name. Use fiori_list to see available entries (e.g. "viz-chart", "value-help").' },
+            params: {
+                type: 'object',
+                description: 'Entry parameters as an object. The required params per entry are returned by fiori_list.',
+            },
+        },
+        required: ['appDir', 'entry'],
+    },
+    handler: fioriApplyHandler,
+});
+registerTool({
+    name: 'fiori_list',
+    description: 'List the Fiori engine catalog entries (the patterns that need a frozen template: ' +
+        'viz-chart, value-help) with each entry\'s title, description, libraries, and full ' +
+        'param spec. Read this before fiori_apply to build a correct params object in one shot.',
+    isMutating: false,
+    category: 'fiori',
+    flagGated: true,
+    input_schema: { type: 'object', properties: {} },
+    handler: fioriListHandler,
+});
+registerTool({
+    name: 'fiori_deploy_config',
+    description: 'Write the ABAP-repository (BSP) deploy configuration for a scaffolded app: ui5-deploy.yaml ' +
+        'plus "deploy" / "deploy-test" package.json scripts. Validates BSP app name (≤15 chars, ' +
+        'uppercase), package namespace, and transport format. Credentials are NEVER written — ' +
+        'fiori deploy takes env-var NAMES at deploy time. appDir is sandboxed to the project root.',
+    isMutating: true,
+    category: 'fiori',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            appDir: { type: 'string', description: 'Root directory of the scaffolded app (relative to project root).' },
+            url: { type: 'string', description: 'ABAP system base URL, e.g. "https://host:44300".' },
+            client: { type: 'string', description: 'SAP client, e.g. "100".' },
+            name: { type: 'string', description: 'BSP application name — max 15 chars, UPPERCASE, Z/Y prefix.' },
+            package: { type: 'string', description: 'ABAP package: Z-/Y-prefixed, $TMP, or a registered /namespace/pkg.' },
+            transport: { type: 'string', description: 'Workbench transport (e.g. "S4HK903359"). Required unless package is $TMP.' },
+            description: { type: 'string', description: 'BSP application description.' },
+            ignoreCertErrors: { type: 'boolean', description: 'Accept self-signed certificates (dev systems only). Default false.' },
+        },
+        required: ['appDir', 'url', 'client', 'name', 'package'],
+    },
+    handler: fioriDeployConfigHandler,
+});
+registerTool({
+    name: 'fiori_scaffold_fe',
+    description: 'Scaffold a trivial Fiori Elements app shell (List Report Object Page, Worklist, or Overview Page) ' +
+        'against an ALREADY-PUBLISHED OData service. Driven entirely by the backend @UI annotations on the ' +
+        'CDS projection/DDLX — authors NO local annotation.xml (not an FE generator). metadata is OPTIONAL ' +
+        '(the running app reads it from the live service); pass it only if you already have it. basePath ' +
+        'sandboxed to the project root.',
+    isMutating: true,
+    category: 'fiori',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            basePath: { type: 'string', description: 'Directory to scaffold into (relative to project root).' },
+            appId: { type: 'string', description: 'App namespace, e.g. "z.tcrs.courses".' },
+            appTitle: { type: 'string', description: 'Human-readable title. Defaults to appId.' },
+            template: { type: 'string', enum: ['lrop', 'worklist', 'ovp'], description: 'FE template. Default "lrop". All three ship.' },
+            serviceUrl: { type: 'string', description: 'Backend host, e.g. "https://host:44300".' },
+            servicePath: { type: 'string', description: 'OData service path, e.g. "/sap/opu/odata4/sap/zc_x/srvd/sap/zc_x/0001/".' },
+            serviceVersion: { type: 'string', enum: ['2.0', '4.0'], description: 'OData version. Default "4.0".' },
+            metadata: { type: 'string', description: 'OPTIONAL service $metadata (EDMX XML). The writer does not need it; pass only if you already have it.' },
+            client: { type: 'string', description: 'OPTIONAL SAP client (e.g. "100"), written to the manifest for the proxy layer.' },
+            mainEntity: { type: 'string', description: 'The entity set to bind, e.g. "Course".' },
+            ui5Version: { type: 'string', description: 'UI5 version. Default 1.120.0.' },
+        },
+        required: ['basePath', 'appId', 'serviceUrl', 'servicePath', 'mainEntity'],
+    },
+    handler: fioriScaffoldFeHandler,
+});

package/dist/tools/fiori/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/local-build.js

@@ -0,0 +1,76 @@
+// cspeach-cli/src/tools/local-build.ts
+/**
+ * Startup wiring for the persisted `local_build` config toggle (2026-06-13,
+ * renamed + broadened from `local_files`).
+ *
+ * When the effective toggle is on (see config/loader.ts resolveLocalBuild —
+ * `local_build ?? local_files` for backward compat), the otherwise flag-gated
+ * LOCAL BUILD tools are force-enabled via the in-memory override in `_flag.ts`,
+ * BEFORE the first listTools()/turn. The enable set is now:
+ *
+ *   filesystem: file_read, file_write, file_edit, glob, grep
+ *   shell:      shell_exec
+ *   fiori:      fiori_scaffold, fiori_apply, fiori_list, fiori_deploy_config
+ *   extend:     extend_model_insert (anchored CDS/DDLX edit — abap-extend-model)
+ *
+ * This is what makes /abap-fiori-build runnable end to end — it writes local
+ * app files (FS tools), runs safelisted build CLIs (shell), AND scaffolds /
+ * composes the app via the built-in Fiori engine (fiori_* tools). The fiori_*
+ * tools replace the old repo-only `pnpm fiori scaffold` path so shipped-binary
+ * customers get the same deterministic engine output without pnpm or the repo.
+ *
+ * The toggle is PERSISTED (config.toml), not re-consented each session, so
+ * `applyLocalBuildConfig` returns an announce line the entry point prints
+ * whenever the tools are live — the user must always see that local file access
+ * AND command execution are on this session (trust-visibility requirement).
+ *
+ * The blast radius is honestly named: the announce line surfaces the cwd (where
+ * read/write/edit operate) AND the shell safelist (which commands shell_exec may
+ * run). The FS tools' own cwd-sandbox (writes confined to the project root;
+ * .cspeach/.env/.git denylisted) and shell_exec's argv-only safelist enforcement
+ * still apply regardless of this toggle — enabling shell_exec only makes it
+ * visible, it does NOT make it unrestricted.
+ */
+import { enableToolFlags } from './_flag.js';
+// Source-of-truth for the shell safelist names surfaced in the announce line.
+// Imported (not hand-copied) so the announce can never drift from the actual
+// commands shell_exec permits. If shell_exec's DEFAULT_SAFELIST changes, this
+// announce string follows automatically.
+import { DEFAULT_SAFELIST } from './_command-shared.js';
+/**
+ * The exact tool NAMEs the flag uses (file_read → CSPEACH_TOOL_FILE_READ,
+ * shell_exec → CSPEACH_TOOL_SHELL_EXEC). `shell_exec` matches the tool's
+ * registered name in tools/shell/shell_exec.ts, so isToolFlagOn('shell_exec')
+ * checks the same override key enableToolFlags(['shell_exec']) sets.
+ */
+export const LOCAL_BUILD_TOOLS = [
+    'file_read',
+    'read_document',
+    'file_write',
+    'file_edit',
+    'glob',
+    'grep',
+    'shell_exec',
+    'fiori_scaffold',
+    'fiori_apply',
+    'fiori_list',
+    'fiori_deploy_config',
+    'fiori_scaffold_fe',
+    'extend_model_insert',
+    'system_capability',
+];
+/**
+ * Apply the persisted `local_build` toggle. When on, force-enables the FS +
+ * shell build tools and returns a one-line announce string (undefined when off,
+ * so the caller prints nothing). `cwd` is surfaced so the user sees exactly
+ * which directory tree read/write/edit operate under; the shell safelist is
+ * surfaced so the user sees which commands shell_exec may run.
+ */
+export function applyLocalBuildConfig(localBuild, cwd) {
+    if (localBuild !== true)
+        return undefined;
+    enableToolFlags([...LOCAL_BUILD_TOOLS]);
+    const safelist = [...DEFAULT_SAFELIST].join(', ');
+    return (`local build tools enabled — file read/write/edit under ${cwd} ` +
+        `+ safelisted commands (${safelist}) — cspeach config set local_build off to disable`);
+}

package/dist/tools/local-files.js

@@ -0,0 +1,31 @@
+// cspeach-cli/src/tools/local-files.ts
+/**
+ * Startup wiring for the persisted `local_files` config toggle.
+ *
+ * When `cfg.local_files === true`, the otherwise flag-gated filesystem tools
+ * (file_read/file_write/file_edit/glob/grep) are force-enabled via the
+ * in-memory override in `_flag.ts`, BEFORE the first listTools()/turn. This is
+ * what makes /abap-fiori-build runnable — it writes local app files.
+ *
+ * The toggle is PERSISTED (config.toml), not re-consented each session, so
+ * `applyLocalFilesConfig` returns an announce line the entry point prints
+ * whenever the tools are live — the user must always see that local file
+ * access is on this session (trust-visibility requirement). The FS tools'
+ * own cwd-sandbox (writes confined to the project root; .cspeach/.env/.git
+ * denylisted) still applies regardless of this toggle.
+ */
+import { enableToolFlags } from './_flag.js';
+/** The exact tool NAMEs the flag uses (file_read → CSPEACH_TOOL_FILE_READ). */
+export const LOCAL_FILE_TOOLS = ['file_read', 'file_write', 'file_edit', 'glob', 'grep'];
+/**
+ * Apply the persisted `local_files` toggle. When on, force-enables the FS
+ * tools and returns a one-line announce string (undefined when off, so the
+ * caller prints nothing). `cwd` is surfaced so the user sees exactly which
+ * directory tree read/write/edit operate under.
+ */
+export function applyLocalFilesConfig(localFiles, cwd) {
+    if (localFiles !== true)
+        return undefined;
+    enableToolFlags([...LOCAL_FILE_TOOLS]);
+    return `local file tools enabled (read/write/edit under ${cwd}) — cspeach config set local_files off to disable`;
+}