@cspeach/cli 0.9.0 → 1.1.0

package/dist/tools/fiori/tools.js

@@ -0,0 +1,681 @@
+/**
+ * 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
+ * ------------------
+ * Every fiori_* tool here is 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';
+import { feExtend, FE_EXTEND_OPS, NotV4FeAppError } from './fe-extend.js';
+import { runSmoke } from './smoke/run-smoke.js';
+import { deriveFreestyleSmokeSpec, FreestyleSmokeDerivationError } from './smoke/freestyle-spec.js';
+import { loadConfig, resolveRenderSmoke } from '../../config/loader.js';
+import { searchSamples } from './samples/search.js';
+import { loadSampleSource, SampleFetchError, UnsafeSampleNameError } from './samples/loader.js';
+// The grounding corpus ships as an imported JSON module + the bundled
+// SAMPLE_SOURCES map (read inside loadSampleSource). NEVER readFileSync the
+// corpus — the import is the only shipping-safe read (rule A-C1).
+import sampleIndexJson from './samples/data/index.json' with { type: 'json' };
+const SAMPLE_INDEX = sampleIndexJson;
+// Short provenance line, always attached to a fiori_sample_get payload so the
+// model can cite the source (licensing constraint A-M1). Derived from the
+// corpus NOTICE: OpenUI5 sources, adapted, under Apache-2.0.
+const SAMPLE_ATTRIBUTION = 'Adapted from OpenUI5 (github.com/SAP/openui5) sample sources, licensed under Apache-2.0.';
+/** 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 };
+    if (args.localAnnotations && (!args.localAnnotations.technicalName || !args.localAnnotations.xml)) {
+        return { content: 'error: localAnnotations requires both technicalName and xml', 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,
+            localAnnotations: args.localAnnotations,
+        });
+    }
+    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')}`,
+    };
+}
+// ───────────────────────────── fiori_fe_extend ────────────────────────────
+export async function feExtendHandler(args, ctx) {
+    if (!args.basePath)
+        return { content: 'error: basePath is required', is_error: true };
+    if (!args.op)
+        return { content: 'error: op is required', is_error: true };
+    if (!FE_EXTEND_OPS.includes(args.op)) {
+        return { content: `error: unknown op "${args.op}" — expected one of ${FE_EXTEND_OPS.join(', ')}`, is_error: true };
+    }
+    const resolved = safeDir(ctx, args.basePath);
+    if ('error' in resolved)
+        return { content: `error: ${resolved.error}`, is_error: true };
+    const before = new Set(await listFilesUnder(ctx, resolved.abs));
+    try {
+        await feExtend({ basePath: resolved.abs, op: args.op, params: args.params ?? {} });
+    }
+    catch (err) {
+        // V4-only scope limit: fe-fpm-writer refuses non-V4-FE apps (no
+        // sap.fe.templates) — surfaced as a clean typed line, not the writer's
+        // internal wording.
+        if (err instanceof NotV4FeAppError)
+            return { content: `error: ${err.message}`, is_error: true };
+        return { content: `error: fe extend failed — ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    // Report only the newly-written files (the generator also touches manifest.json).
+    const after = await listFilesUnder(ctx, resolved.abs);
+    const created = after.filter((f) => !before.has(f));
+    const appDir = rel(ctx, resolved.abs);
+    return {
+        content: `Added FE extension "${args.op}" to ${appDir}/ (manifest.json updated).\n` +
+            (created.length
+                ? `New files:\n${created.map((f) => `  ${f}`).join('\n')}`
+                : `No new files (manifest-only change).`),
+    };
+}
+/**
+ * FREESTYLE MODE (appDir given): derive a SmokeSpec from the app's own webapp/
+ * tree via deriveFreestyleSmokeSpec, then let explicit spec args override the
+ * derived fields FIELD-BY-FIELD (explicit wins). `appUrl` always comes from the
+ * arg — derivation produces no URL. Returns the merged spec + derivation warnings,
+ * or a clean `error` string (bad appDir, or a typed derivation failure — named).
+ *
+ * Kept as a pure, exported helper so the derive+merge contract is unit-testable
+ * without launching a browser; the handler only orchestrates.
+ */
+export function resolveFreestyleSmokeSpec(args, ctx) {
+    const resolved = safeDir(ctx, args.appDir);
+    if ('error' in resolved)
+        return { error: resolved.error };
+    let derived;
+    try {
+        derived = deriveFreestyleSmokeSpec(resolved.abs);
+    }
+    catch (err) {
+        // Name the typed derivation failure (no stack trace) so the model sees WHY.
+        if (err instanceof FreestyleSmokeDerivationError) {
+            return { error: `${err.name}: ${err.message}` };
+        }
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+    const { warnings } = derived;
+    // Field-by-field merge (explicit wins). `??` keeps an explicitly-provided empty
+    // array/false as an override, and omits fields that are neither explicit nor derived.
+    const controlKind = args.controlKind ?? derived.controlKind;
+    const expectedColumns = args.expectedColumns ?? derived.expectedColumns;
+    const exercises = args.exercises ?? derived.exercises;
+    const spec = {
+        appUrl: args.appUrl, // always the arg — derivation carries no real preview URL
+        ...(controlKind !== undefined ? { controlKind } : {}),
+        ...(expectedColumns !== undefined ? { expectedColumns } : {}),
+        ...(args.allowEmptyRows !== undefined ? { allowEmptyRows: args.allowEmptyRows } : {}),
+        ...(exercises !== undefined ? { exercises } : {}),
+    };
+    return { spec, warnings };
+}
+export async function fioriRenderSmokeHandler(args, ctx, 
+// Test seam: injected runSmoke deps (browser/openApp/renderSmokeEnabled). In
+// production this is undefined and the real config-driven deps are used.
+deps) {
+    if (!args.appUrl) {
+        return {
+            content: 'error: appUrl is required — the LOCAL AUTHENTICATED PREVIEW URL (the `npm run start` / ' +
+                '`fiori run` URL, e.g. http://localhost:8080/index.html), NOT the deployed BSP URL.',
+            is_error: true,
+        };
+    }
+    // FE mode (no appDir): byte-identical to Track 2 — `args` is the spec, no warnings.
+    // Freestyle mode (appDir): derive + merge, and surface the derivation warnings.
+    let spec = args;
+    let warnings;
+    if (args.appDir) {
+        const derived = resolveFreestyleSmokeSpec(args, ctx);
+        if ('error' in derived) {
+            return {
+                content: `error: could not derive a freestyle smoke spec from appDir "${args.appDir}" — ${derived.error}`,
+                is_error: true,
+            };
+        }
+        spec = derived.spec;
+        warnings = derived.warnings;
+    }
+    // The render_smoke config toggle (plain default true) gates whether a browser
+    // is actually launched; when off, runSmoke returns a skipped manual result.
+    const cfg = await loadConfig();
+    const runDeps = { renderSmokeEnabled: resolveRenderSmoke(cfg), ...deps };
+    const result = await runSmoke(spec, runDeps);
+    // A skip is NOT a tool error — it's a valid `verification:'manual'` outcome the
+    // caller must see and act on (bring the preview up, etc.). Return the full
+    // SmokeResult as JSON either way. In freestyle mode attach the derivation
+    // warnings (always present — even []) so the model sees skipped presses/routes.
+    const payload = warnings !== undefined ? { ...result, warnings } : result;
+    return { content: JSON.stringify(payload, null, 2) };
+}
+// ─────────────────────────────── fiori_sample_search ──────────────────────
+export async function fioriSampleSearchHandler(args, _ctx) {
+    if (!args.text || !args.text.trim()) {
+        return { content: 'error: text is required — free-text keywords to match against the sample corpus', is_error: true };
+    }
+    // searchSamples is pure (Task 2): score the imported index, keep only real
+    // matches, ordered by descending score. Shape each hit as a compact,
+    // CatalogIndexItem-style summary + its score for the model to pick from.
+    // Clamp at the tool boundary: a model-supplied 0, negative, or fractional max
+    // would otherwise reach searchSamples' slice as-is (0 → no hits at all, a
+    // negative → silently drops from the tail). Undefined still means "default".
+    const max = args.max === undefined ? undefined : Math.max(1, Math.floor(args.max) || 1);
+    const hits = searchSamples(SAMPLE_INDEX, { text: args.text, control: args.control, max });
+    const summaries = hits.map(({ entry, score }) => ({
+        name: entry.name,
+        control: entry.control,
+        library: entry.library,
+        description: entry.description,
+        keywords: entry.keywords,
+        vendored: entry.sourceRef.vendored,
+        score,
+    }));
+    return { content: JSON.stringify(summaries, null, 2) };
+}
+// ─────────────────────────────── fiori_sample_get ─────────────────────────
+export async function fioriSampleGetHandler(args, _ctx) {
+    if (!args.name || !args.name.trim()) {
+        return { content: 'error: name is required — the sample name from fiori_sample_search (e.g. "sap.m/Wizard")', is_error: true };
+    }
+    const entry = SAMPLE_INDEX.find((e) => e.name === args.name);
+    if (!entry) {
+        return {
+            content: `error: sample "${args.name}" is not found in the sample index — call fiori_sample_search first to get a valid name.`,
+            is_error: true,
+        };
+    }
+    // loadSampleSource (Task 3): vendored → bundled SAMPLE_SOURCES; un-vendored →
+    // lazy fetch + cache. Its typed errors carry actionable, model-facing messages
+    // (fall back to recipes + sap-docs) — surface them verbatim, don't mask them.
+    try {
+        const loaded = await loadSampleSource(entry, {});
+        return {
+            content: JSON.stringify({ name: entry.name, files: loaded.files, license: 'Apache-2.0', attribution: SAMPLE_ATTRIBUTION }, null, 2),
+        };
+    }
+    catch (err) {
+        if (err instanceof SampleFetchError || err instanceof UnsafeSampleNameError) {
+            return { content: `error: ${err.message}`, is_error: true };
+        }
+        return { content: `error: could not load sample "${args.name}" — ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+}
+// ─────────────────────────────── 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, Overview Page, or Analytical List 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', 'alp'], description: 'FE template: lrop (List Report), worklist, ovp (Overview Page), or alp (Analytical List Page). Default "lrop". All four 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.' },
+            localAnnotations: {
+                type: 'object',
+                description: 'OPTIONAL local annotations.xml for a FOREIGN OData service you do NOT own (cannot add backend @UI). ' +
+                    'Wires the given EDMX as a LOCAL ODataAnnotation dataSource (annotations/<technicalName>.xml) that ' +
+                    'resolves at runtime — no catalog fetch. Omit for services whose backend already carries @UI annotations.',
+                properties: {
+                    technicalName: { type: 'string', description: 'Local annotation name; also the dataSource key and file name (annotations/<technicalName>.xml).' },
+                    xml: { type: 'string', description: 'The annotations EDMX (UI.LineItem/HeaderInfo/SelectionFields/Facets in EDMX form).' },
+                },
+                required: ['technicalName', 'xml'],
+            },
+        },
+        required: ['basePath', 'appId', 'serviceUrl', 'servicePath', 'mainEntity'],
+    },
+    handler: fioriScaffoldFeHandler,
+});
+registerTool({
+    name: 'fiori_fe_extend',
+    description: 'Add a Fiori Elements extension point to an EXISTING V4 FE app on disk via @sap-ux/fe-fpm-writer: ' +
+        'a custom-column (table column + fragment), custom-action (toolbar/table action), custom-section ' +
+        '(object-page section + fragment), or controller-extension (a .controller.js/.ts + manifest wiring). ' +
+        'V4 Fiori Elements ONLY (LROP/Worklist/ALP/FEOP) — OVP and all OData V2 apps are refused with a typed ' +
+        'error. params map 1:1 to fe-fpm-writer\'s CustomTableColumn / CustomAction / CustomSection / ' +
+        'ControllerExtension config and are passed verbatim. basePath is sandboxed to the project root.',
+    isMutating: true,
+    category: 'fiori',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            basePath: { type: 'string', description: 'App root of the existing V4 FE app (the folder containing webapp/manifest.json), relative to the project root.' },
+            op: {
+                type: 'string',
+                enum: [...FE_EXTEND_OPS],
+                description: 'Extension point to add: custom-column, custom-action, custom-section, or controller-extension.',
+            },
+            params: {
+                type: 'object',
+                description: 'Extension config, passed VERBATIM to the matching fe-fpm-writer generator. Required fields per op: ' +
+                    'custom-column → { name, target (routing target, e.g. "<Entity>List"), targetEntity, position { placement: "After"|"Before"|"End", anchor? }, header }; ' +
+                    'custom-action → { name, target { page (routing target), control ("@com.sap.vocabularies.UI.v1.LineItem" for a table action) }, settings { text } }; ' +
+                    'custom-section → { name, target (object-page routing target, e.g. "<Entity>ObjectPage"), title }; ' +
+                    'controller-extension → { name, extension ("ListReport"|"ObjectPage" or a page-target object) }. ' +
+                    'eventHandler is optional on column/action/section.',
+            },
+        },
+        required: ['basePath', 'op', 'params'],
+    },
+    handler: feExtendHandler,
+});
+registerTool({
+    name: 'fiori_render_smoke',
+    description: 'Content-asserting render smoke (Track 2 D-4): launch a headless Edge/Chrome against the LOCAL ' +
+        'AUTHENTICATED PREVIEW (the `npm run start` URL — NEVER the deployed BSP URL) and assert the app ' +
+        'actually rendered — booted with no console errors, no failed OData ($metadata/$batch/entity) calls, ' +
+        'expected columns present, and (for a list) rows returned. TWO MODES: FIORI-ELEMENTS mode — pass the ' +
+        'spec fields (expectedColumns/controlKind/…) yourself. FREESTYLE mode — pass `appDir` (the scaffolded ' +
+        'app root) plus `appUrl` and the spec is DERIVED from the app\'s own webapp/ views + i18n + manifest ' +
+        '(controlKind, expected columns, press/route exercises); any spec field you ALSO pass overrides the ' +
+        'derived one. Derivation notes surface as a `warnings` array in the result. SKIPPABLE BUT NEVER ' +
+        'SILENTLY GREEN: when the render_smoke config is off, no browser is found, the preview is unreachable, ' +
+        'or the page is a SAP logon form, it returns verification:"manual" + passed:false with a "skipped" ' +
+        'check explaining why — it can never report a passing smoke without a real render. Flag-gated (enabled ' +
+        'with local_build), read-only.',
+    isMutating: false,
+    category: 'fiori',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            appUrl: {
+                type: 'string',
+                description: 'The LOCAL AUTHENTICATED PREVIEW URL (the `npm run start` / `fiori run` URL that proxies to the ' +
+                    'real backend with your auth), e.g. "http://localhost:8080/index.html". NOT the deployed BSP URL.',
+            },
+            appDir: {
+                type: 'string',
+                description: 'FREESTYLE mode only: the scaffolded app root (relative to the project root, sandboxed). When ' +
+                    'given, the SmokeSpec is DERIVED from that app\'s webapp/ views + i18n + manifest, and any spec ' +
+                    'field you also pass overrides the derived one. Omit for Fiori Elements mode (pass the spec fields directly).',
+            },
+            expectedColumns: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Column headers that MUST be present (checked case-insensitively). Omit for non-list controls.',
+            },
+            controlKind: {
+                type: 'string',
+                enum: ['table', 'cards', 'chart', 'form', 'custom'],
+                description: 'The app\'s primary control. Only "table" gets a row-count assertion.',
+            },
+            allowEmptyRows: {
+                type: 'boolean',
+                description: 'When true, a table that renders 0 rows still passes (empty list acknowledged). Default false.',
+            },
+            exercises: {
+                type: 'array',
+                description: 'Post-boot interactions to exercise (press/route). Declared for Track 3; unused in Track 2.',
+                items: { type: 'object' },
+            },
+        },
+        required: ['appUrl'],
+    },
+    handler: fioriRenderSmokeHandler,
+});
+registerTool({
+    name: 'fiori_sample_search',
+    description: 'Search the vendored UI5 Demo Kit sample corpus (grounding for the freestyle composer): free-text ' +
+        'keywords + an optional exact control name return the best-matching samples as scored summaries ' +
+        '(name, control, library, description, keywords, vendored flag, score), highest score first. Use this ' +
+        'to FIND a real UI5 sample to ground a control against, then fiori_sample_get to read its source. ' +
+        'Read-only; flag-gated (enabled with local_build).',
+    isMutating: false,
+    category: 'fiori',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            text: { type: 'string', description: 'Free-text keywords, e.g. "wizard step" or "value help dialog".' },
+            control: { type: 'string', description: 'OPTIONAL exact UI5 control name (e.g. "Wizard") — an exact match dominates the ranking.' },
+            max: { type: 'number', description: 'Max results to return. Default 5.' },
+        },
+        required: ['text'],
+    },
+    handler: fioriSampleSearchHandler,
+});
+registerTool({
+    name: 'fiori_sample_get',
+    description: 'Fetch one UI5 sample\'s source files by name (the grounding payload the composer reads). Returns ' +
+        '{ files: [{ path, content }], license: "Apache-2.0", attribution }. Vendored samples are served from ' +
+        'the bundled corpus; un-vendored ones are lazily fetched and cached. The Apache-2.0 attribution line ' +
+        'is ALWAYS included. Call fiori_sample_search first to get a valid name. An unknown name, or a sample ' +
+        'that cannot be retrieved, returns a clean error steering you to the recipes catalog + sap-docs. ' +
+        'Read-only; flag-gated (enabled with local_build).',
+    isMutating: false,
+    category: 'fiori',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'The sample name from fiori_sample_search, e.g. "sap.m/Wizard".' },
+        },
+        required: ['name'],
+    },
+    handler: fioriSampleGetHandler,
+});