@cspeach/cli 1.1.22 → 1.1.23

package/dist/tools/cap/service-catalog.js

@@ -0,0 +1,248 @@
+// cspeach-cli/src/tools/cap/service-catalog.ts
+//
+// CAP phase 2, Task 9 — `sap_service_catalog`: list the OData services ACTIVE on
+// the connected SAP system, from the Gateway V2 and V4 catalogs. The design
+// step uses it to map a spec's S/4 data to a service that really exists.
+//
+// Read-only: the only requests are GETs to V2_CATALOG_BASE and V4_CATALOG_URL.
+// Field names follow the real S4H captures (probe note P3, fixtures/catalog-*.json):
+// - V2: on that box `TechnicalServiceName` is Z-prefixed (ZAPI_…) while
+//   `ServiceUrl` (absolute) ends in the real name, so the name comes from the
+//   last ServiceUrl segment (matrix `;v=..` ignored), then Title, then
+//   TechnicalServiceName.
+// - V4: `ServiceUrl` is RELATIVE and carries `?sap-client=…`; the query is dropped.
+import { registerTool } from '../index.js';
+import { loadConfig } from '../../config/loader.js';
+import { PlainFetchError, plainSapFetchError } from './_fetch-errors.js';
+const V2_CATALOG_BASE = '/sap/opu/odata/IWFND/CATALOGSERVICE;v=2/ServiceCollection?$format=json' +
+    '&$select=ID,TechnicalServiceName,TechnicalServiceVersion,Title,ServiceUrl';
+export const V4_CATALOG_URL = '/sap/opu/odata4/iwfnd/config/default/iwfnd/catalog/0002/ServiceGroups?$expand=DefaultSystem($expand=Services)';
+/** V2 page size and the safety cap on pages (321 `API_` services on S4H → 4 pages). */
+export const V2_PAGE_SIZE = 100;
+export const V2_MAX_PAGES = 20;
+const DEFAULT_MAX = 50;
+const MAX_MAX = 500;
+const SEARCH_MAX_LEN = 60;
+const SEARCH_RE = /^[A-Za-z0-9_ /-]*$/;
+/** Pathname of an absolute or relative URL: no scheme, host, port, query or fragment; no trailing slash. */
+function pathOf(u) {
+    try {
+        return new URL(u, 'http://catalog.invalid').pathname.replace(/\/+$/, '');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Last path segment, matrix parameters (`;v=0002`) removed. */
+function lastSegment(p) {
+    const seg = p.split('/').pop() ?? '';
+    return seg.split(';')[0] ?? '';
+}
+/** One row, one line: SAP-supplied text loses control characters (tabs, newlines, ESC). */
+// eslint-disable-next-line no-control-regex
+const oneLine = (s) => String(s ?? '').replace(/[\u0000-\u001F\u007F]+/g, ' ').replace(/\s+/g, ' ').trim();
+const str = (v) => (typeof v === 'string' ? v : '');
+/**
+ * The V2 catalog URL for one page. `search` is escaped for an OData string
+ * literal (single quotes doubled) and percent-encoded; `$` stays literal the way
+ * sap_odata_test does. The handler validates the term before it gets here.
+ */
+export function v2CatalogUrl(search, skip = 0) {
+    let url = `${V2_CATALOG_BASE}&$top=${V2_PAGE_SIZE}&$skip=${Math.max(0, Math.floor(skip))}`;
+    if (search) {
+        const filter = `substringof('${search.replace(/'/g, "''")}',TechnicalServiceName)`;
+        url += `&$filter=${encodeURIComponent(filter)}`;
+    }
+    return url;
+}
+export function parseV2Catalog(json) {
+    return parseV2Page(json).rows;
+}
+/** Rows plus the raw result count; paging decides on the raw count, not the kept rows. */
+function parseV2Page(json) {
+    const d = JSON.parse(json);
+    const results = Array.isArray(d?.d?.results) ? d.d.results : [];
+    const out = [];
+    for (const r of results) {
+        if (!r || typeof r !== 'object')
+            continue;
+        const servicePath = pathOf(str(r.ServiceUrl));
+        if (!servicePath || !servicePath.startsWith('/sap/opu/odata/'))
+            continue;
+        const name = lastSegment(servicePath) || str(r.Title) || str(r.TechnicalServiceName);
+        if (!name)
+            continue;
+        const v = r.TechnicalServiceVersion;
+        out.push({
+            name: oneLine(name),
+            version: v === undefined || v === null || v === '' ? '' : oneLine(v).padStart(4, '0'),
+            title: oneLine(r.Title),
+            servicePath,
+            odata: 'v2',
+        });
+    }
+    return { rows: out, raw: results.length };
+}
+export function parseV4Catalog(json) {
+    const d = JSON.parse(json);
+    const groups = Array.isArray(d?.value) ? d.value : [];
+    const out = [];
+    for (const g of groups) {
+        const sys = g?.DefaultSystem;
+        const services = Array.isArray(sys?.Services) ? sys.Services : [];
+        for (const s of services) {
+            if (!s || typeof s !== 'object')
+                continue;
+            const servicePath = pathOf(str(s.ServiceUrl));
+            if (!servicePath || !servicePath.startsWith('/sap/opu/odata4/'))
+                continue;
+            const name = str(s.ServiceId);
+            if (!name)
+                continue;
+            out.push({
+                name: oneLine(name),
+                version: oneLine(s.ServiceVersion),
+                title: oneLine(str(s.Description) || str(g.GroupId)),
+                servicePath,
+                odata: 'v4',
+            });
+        }
+    }
+    return out;
+}
+export async function sapServiceCatalogHandler(args, ctx, deps = {}) {
+    const rawSearch = typeof args.search === 'string' ? args.search.trim() : '';
+    if (rawSearch.length > SEARCH_MAX_LEN) {
+        return { content: `The search term is too long. Use at most ${SEARCH_MAX_LEN} characters.`, is_error: true };
+    }
+    if (!SEARCH_RE.test(rawSearch)) {
+        return {
+            content: 'The search term may only use letters, digits, underscore, space, slash and hyphen.',
+            is_error: true,
+        };
+    }
+    const want = args.version ?? 'both';
+    if (want !== 'v2' && want !== 'v4' && want !== 'both') {
+        return { content: 'version must be "v2", "v4" or "both".', is_error: true };
+    }
+    const n = Number(args.max);
+    const max = Number.isFinite(n) && n >= 1 ? Math.min(Math.floor(n), MAX_MAX) : DEFAULT_MAX;
+    const term = rawSearch.toLowerCase();
+    const get = deps.get ?? (async (p) => {
+        const { getConnection } = await import('../../sap/connection-manager.js');
+        const cfg = await loadConfig();
+        const sys = cfg.sap[ctx.sapAlias];
+        if (!sys)
+            throw new PlainFetchError(`No SAP system "${ctx.sapAlias}" is configured.`);
+        try {
+            const conn = await getConnection(ctx.sapAlias, sys);
+            const r = await conn.get(p, 'application/json');
+            return { status: r.status, body: r.body };
+        }
+        catch (err) {
+            // Never the raw message: connection errors can carry headers, cookies or the user name.
+            // An empty fallback lets fetchRows use its own per-catalog sentence.
+            throw new PlainFetchError(plainSapFetchError(err, ctx.sapAlias, sys.host, sys.port, ''));
+        }
+    });
+    const matches = (x) => !term || x.name.toLowerCase().includes(term) || x.title.toLowerCase().includes(term);
+    /** One GET → rows, or a plain one-line error. Never echoes the answer body or a stack. */
+    const fetchRows = async (label, url, parse) => {
+        let r;
+        try {
+            r = await get(url);
+        }
+        catch (err) {
+            // Only a PlainFetchError's own fixed line is shown; anything else gets a fixed sentence.
+            if (err instanceof PlainFetchError && err.message)
+                return err.message;
+            return `${label} catalog could not be read from ${ctx.sapAlias}. Check the SAP login for this system and try again.`;
+        }
+        if (r.status !== 200)
+            return `${label} catalog answered HTTP ${r.status}.`;
+        try {
+            return parse(r.body);
+        }
+        catch {
+            return `${label} catalog answer was not JSON.`;
+        }
+    };
+    const out = [];
+    const notes = [];
+    const errors = [];
+    const emit = (rows) => {
+        for (const x of rows)
+            out.push(`${x.servicePath}\t${x.name}\t${x.odata}\t${x.version}\t${x.title}`);
+    };
+    if (want !== 'v4') {
+        // The server filter matches TechnicalServiceName, which is upper case (and
+        // Z-prefixed on some boxes, e.g. ZAPI_…); substringof still finds the name.
+        const serverTerm = rawSearch ? rawSearch.toUpperCase() : undefined;
+        const rows = [];
+        let page = 0;
+        let failed = false;
+        let lastFull = false;
+        while (page < V2_MAX_PAGES && rows.length < max) {
+            const res = await fetchRows('V2', v2CatalogUrl(serverTerm, page * V2_PAGE_SIZE), parseV2Page);
+            page++;
+            if (typeof res === 'string') {
+                errors.push(res);
+                failed = true;
+                break;
+            }
+            rows.push(...res.rows.filter(matches));
+            lastFull = res.raw >= V2_PAGE_SIZE;
+            if (!lastFull)
+                break;
+        }
+        if (!failed && page >= V2_MAX_PAGES && lastFull && rows.length < max) {
+            notes.push(`Stopped after ${V2_MAX_PAGES} pages of the V2 catalog. The V2 list may be incomplete; narrow the search.`);
+        }
+        if (rows.length > max)
+            notes.push(`V2: showing the first ${max}. Narrow the search or raise max.`);
+        emit(rows.slice(0, max));
+    }
+    if (want !== 'v2') {
+        const res = await fetchRows('V4', V4_CATALOG_URL, parseV4Catalog);
+        if (typeof res === 'string')
+            errors.push(res);
+        else {
+            const rows = res.filter(matches);
+            if (rows.length > max)
+                notes.push(`V4: showing the first ${max} of ${rows.length}. Narrow the search or raise max.`);
+            emit(rows.slice(0, max));
+        }
+    }
+    const content = [
+        'PATH\tNAME\tODATA\tVERSION\tTITLE',
+        ...out,
+        `(${out.length} active services${rawSearch ? ` matching "${rawSearch}"` : ''}. Active means registered in the ` +
+            'Gateway catalog. Release state is separate; check it before you use a service.)',
+        ...notes,
+        ...[...new Set(errors)], // one reach line, not one per catalog
+    ].join('\n');
+    return { content, ...(out.length === 0 && errors.length ? { is_error: true } : {}) };
+}
+registerTool({
+    name: 'sap_service_catalog',
+    description: 'List OData services ACTIVE on the connected SAP system (Gateway catalog, V2 and V4): path, service name, ' +
+        'OData version, service version, title. Use it in design to map a spec\'s S/4 data to a service that really ' +
+        'exists on this system. Active is not the same as released: check release state separately. Read-only.',
+    isMutating: false,
+    requiresSap: true,
+    // R25: visible only with local_build on (the CAP lane already needs it), so
+    // the tool list of non-CAP users stays unchanged.
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            search: {
+                type: 'string',
+                description: 'Part of the service name or title, e.g. "BUSINESS_PARTNER". Letters, digits, _ space / - only; max 60.',
+            },
+            version: { type: 'string', enum: ['v2', 'v4', 'both'], description: 'Which catalog to read. Default both.' },
+            max: { type: 'number', description: 'Rows per catalog, default 50, max 500.' },
+        },
+    },
+    handler: (args, ctx) => sapServiceCatalogHandler(args, ctx),
+});

package/dist/tools/fiori/preview/registry.js

@@ -56,6 +56,7 @@ import * as net from 'node:net';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { KILL_GRACE_MS } from '../../_command-shared.js';
+import { registerShutdownHook } from '../../../lib/shutdown-hooks.js';
 /** appDirKey → tracked preview. At most one per directory, by construction. */
 const registry = new Map();
 /**
@@ -108,7 +109,7 @@ export function childIsLive(child) {
     return !!child && child.exitCode === null && child.signalCode === null;
 }
 /** A pid we are allowed to signal. 0 = own group / idle process, 1 = everything. */
-function killablePid(pid) {
+export function killablePid(pid) {
     return typeof pid === 'number' && Number.isInteger(pid) && pid > 1;
 }
 export function registerPreview(e, child) {
@@ -340,15 +341,30 @@ export async function stopPreview(previewId) {
     const portClosed = await waitForPortClosed(port);
     return { stopped: true, portClosed, port, ...outcome };
 }
+/**
+ * Windows only: kill `pid` and every descendant SYNCHRONOUSLY with the absolute
+ * taskkill (`/T /F`), minimal env, cwd = tmpdir. Safe inside `process.on('exit')`.
+ * The CALLER owns the identity rule — call it only for a live child handle this
+ * process holds, and with `killablePid(pid)` true. Shared with the background
+ * registry (subagent/_background-shared.ts).
+ *
+ * Returns true when taskkill ran and reported success — exit 0, or 128 ("no such
+ * process": already gone). spawnSync never throws; a spawn failure or timeout
+ * shows up as `error`, and the caller decides on a fallback.
+ */
+export function taskkillTreeSync(pid) {
+    const r = spawnSync(TASKKILL, ['/PID', String(pid), '/T', '/F'], {
+        windowsHide: true,
+        stdio: 'ignore',
+        cwd: os.tmpdir(),
+        env: TASKKILL_ENV,
+        timeout: TASKKILL_TIMEOUT_MS,
+    });
+    return !r.error && (r.status === 0 || r.status === 128);
+}
 function realSyncKill(pid) {
     if (process.platform === 'win32') {
-        spawnSync(TASKKILL, ['/PID', String(pid), '/T', '/F'], {
-            windowsHide: true,
-            stdio: 'ignore',
-            cwd: os.tmpdir(),
-            env: TASKKILL_ENV,
-            timeout: TASKKILL_TIMEOUT_MS,
-        });
+        taskkillTreeSync(pid);
     }
     else {
         process.kill(-pid, 'SIGTERM');
@@ -381,22 +397,12 @@ export function installPreviewExitHandler() {
     if (exitHandlerInstalled)
         return;
     exitHandlerInstalled = true;
-    process.on('exit', killAllPreviewsSync);
-    for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
-        // PREPEND: ui/alt-screen.ts re-raises with process.kill(process.pid, sig),
-        // which on Windows is an immediate TerminateProcess — a listener appended
-        // after it would never run, and 'exit' would never fire either.
-        process.prependListener(sig, () => {
-            killAllPreviewsSync();
-            // In one-shot/classic mode ours may be the ONLY listener, and merely
-            // having one removes Node's default exit-on-signal. Re-raise so Ctrl+C
-            // still stops the CLI.
-            if (process.listenerCount(sig) === 1) {
-                process.removeAllListeners(sig);
-                process.kill(process.pid, sig);
-            }
-        });
-    }
+    // One shared exit/signal handler for every managed resource (Task 8 fix
+    // round 1, I-1): it runs on 'exit' and on SIGINT/SIGTERM/SIGHUP (prepended,
+    // so ui/alt-screen.ts's re-raise cannot pre-empt it), and re-raises when every
+    // remaining listener is its own. Two registries with their own prepended
+    // listeners each saw a count of 2 and nobody re-raised — Ctrl+C hung.
+    registerShutdownHook(killAllPreviewsSync);
 }
 export function __resetPreviewRegistryForTests() {
     registry.clear();

package/dist/tools/local-build.js

@@ -16,6 +16,9 @@
  *               depends on), fiori_metadata_audit, fiori_draft_smoke
  *               (L1-5b — a SAP write, approval-gated like every write),
  *               fiori_sample_search, fiori_sample_get
+ *   cap:        cap_metadata_import (CAP phase 2 — writes srv/external/<API>.edmx),
+ *               sap_service_catalog (read-only Gateway catalog, used in design),
+ *               sap_link, cap_link_smoke (S/4 link check; its write leg is approval-gated)
  *   extend:     extend_model_insert (anchored CDS/DDLX edit — abap-extend-model)
  *   subagent:   agent_run (Task 7, 2026-07-03 — customers get subagent
  *               dispatch when local_build is on; plan phases force its
@@ -71,6 +74,14 @@ export const LOCAL_BUILD_TOOLS = [
     'fiori_draft_smoke',
     'fiori_sample_search',
     'fiori_sample_get',
+    // CAP phase 2 (Task 10) — writes srv/external/<API>.edmx from a SAP $metadata.
+    'cap_metadata_import',
+    // R25 (final wave) — Gateway catalog read for design; gated so non-CAP users' tool list is unchanged.
+    'sap_service_catalog',
+    // CAP phase 2 (Task 8) — the SAP link: a local CAP app's [s4] profile reaches S/4 through it.
+    'sap_link',
+    // CAP phase 2 (Task 11) — S/4 link check: live read vs direct S/4, dev-only update-then-restore.
+    'cap_link_smoke',
     'extend_model_insert',
     'system_capability',
     'agent_run',

package/dist/tools/subagent/_background-shared.js

@@ -15,11 +15,27 @@
  * spawned in.
  *
  * Exit handler installed exactly once via installExitHandler(). When
- * Node exits (normal or signal), every tracked child is SIGTERMd, then
- * SIGKILLd after KILL_GRACE_MS ms. Both timers .unref() so they don't
- * keep Node alive past the legitimate shutdown.
+ * Node exits (normal or signal), every tracked LIVE child is stopped:
+ *   - Windows: the whole tree, synchronously, with the absolute taskkill
+ *     `/T /F` shared with the Fiori preview registry. `child.kill()` there is
+ *     TerminateProcess on the direct child only — and cross-spawn runs a
+ *     `.cmd` shim (`cds.cmd`, `npm.cmd`) through cmd.exe, which creates no job
+ *     object, so the real server (e.g. `cds watch`'s `watched` grandchild)
+ *     kept the port (task 14c finding 3).
+ *     If taskkill cannot run or fails (not exit 0 / 128), fall back to the
+ *     direct kill below.
+ *   - POSIX: SIGTERM to the direct child, then SIGKILL after KILL_GRACE_MS
+ *     (timer .unref()d).
+ * Identity rule (same as preview): only a child handle this process still
+ * holds live, and only a pid > 1.
+ *
+ * The handler is a hook on lib/shutdown-hooks.ts, NOT its own process
+ * listeners: our own appended SIGINT/SIGTERM listeners used to stop Node's
+ * default "exit on signal", so SIGTERM no longer ended the CLI.
  */
 import { KILL_GRACE_MS } from '../_command-shared.js';
+import { registerShutdownHook } from '../../lib/shutdown-hooks.js';
+import { childIsLive, killablePid, taskkillTreeSync } from '../fiori/preview/registry.js';
 export const MAX_EVENTS_PER_BG = 10_000;
 const registry = new Map();
 let exitHandlerInstalled = false;
@@ -83,46 +99,52 @@ export function consumeEvents(bg_id, max) {
         signal: entry.signal,
     };
 }
+let treeKillImpl = taskkillTreeSync;
+/** Stop one entry's process tree, synchronously where it matters (Windows). */
+function stopEntrySync(entry) {
+    const child = entry.child;
+    if (entry.closed || !childIsLive(child))
+        return;
+    if (process.platform === 'win32' && killablePid(child.pid)) {
+        // taskkill failed to run, timed out, or exited with an error → fall back
+        // to the direct kill so at least the child itself goes.
+        if (treeKillImpl(child.pid))
+            return;
+    }
+    try {
+        child.kill('SIGTERM');
+    }
+    catch { /* ignore */ }
+    const t = setTimeout(() => {
+        try {
+            if (childIsLive(child))
+                child.kill('SIGKILL');
+        }
+        catch { /* ignore */ }
+    }, KILL_GRACE_MS);
+    t.unref();
+}
+/** Stop every live background child (and, on Windows, its descendants). */
+export function killAllBackgroundSync() {
+    for (const entry of registry.values()) {
+        try {
+            stopEntrySync(entry);
+        }
+        catch { /* best effort: one failure never blocks the rest */ }
+    }
+}
 /** Idempotent. Subsequent calls are silent no-ops. */
 export function installExitHandler() {
     if (exitHandlerInstalled)
         return;
     exitHandlerInstalled = true;
-    // 'exit' fires synchronously during Node shutdown. Best-effort SIGTERM
-    // each tracked child; the SIGKILL escalation timer cannot fire from
-    // inside an 'exit' handler (event-loop is shutting down) so we
-    // additionally hook SIGINT/SIGTERM/SIGHUP below for graceful paths
-    // where the loop is still alive.
-    process.on('exit', () => {
-        for (const entry of registry.values()) {
-            if (!entry.closed) {
-                try {
-                    entry.child.kill('SIGTERM');
-                }
-                catch { /* ignore */ }
-            }
-        }
-    });
-    for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
-        process.on(sig, () => {
-            for (const entry of registry.values()) {
-                if (!entry.closed) {
-                    try {
-                        entry.child.kill('SIGTERM');
-                    }
-                    catch { /* ignore */ }
-                    const t = setTimeout(() => {
-                        try {
-                            entry.child.kill('SIGKILL');
-                        }
-                        catch { /* ignore */ }
-                    }, KILL_GRACE_MS);
-                    t.unref();
-                }
-            }
-        });
-    }
+    // One shared exit/signal handler for every managed resource (runs on 'exit'
+    // and on SIGINT/SIGTERM/SIGHUP, and re-raises so the CLI still exits).
+    registerShutdownHook(killAllBackgroundSync);
 }
+/** Test-only — replace / restore the Windows tree kill. */
+export function __setTreeKillForTests(fn) { treeKillImpl = fn; }
+export function __resetTreeKillForTests() { treeKillImpl = taskkillTreeSync; }
 /** Test-only — clears registry between cases. Does NOT uninstall the exit handler (handler is process-lifetime-scoped). */
 export function __resetRegistryForTests() {
     registry.clear();

package/dist/tools/subagent/background_run.js

@@ -8,9 +8,11 @@
  * Child stdout/stderr lines stream into the registry as BgEvents;
  * monitor_emit drains them.
  *
- * Child does NOT outlive the CLI process — the registry's exit
- * handler SIGTERMs every live child on Node exit and SIGKILLs after
- * KILL_GRACE_MS.
+ * Child does NOT outlive the CLI process. There is no per-job stop: when
+ * the CLI exits or gets SIGINT/SIGTERM/SIGHUP, the registry's shutdown hook
+ * stops every live child — on Windows the whole process tree (absolute
+ * taskkill /T /F, falling back to a direct kill), on POSIX SIGTERM to the
+ * direct child, then SIGKILL after KILL_GRACE_MS.
  *
  * Flag-gated: invisible to listTools() unless
  * CSPEACH_TOOL_BACKGROUND_RUN=on. isMutating: true — hooks the existing
@@ -135,14 +137,16 @@ export async function backgroundRunHandler(args, ctx) {
             `pid: ${child.pid ?? 'unknown'}\n` +
             `cwd: ${cwd}\n` +
             `note: child is running — call monitor_emit with this bg_id to drain stdout/stderr/exit events. ` +
-            `child will be SIGTERMd on CLI exit (then SIGKILLd after grace).`,
+            `there is no per-job stop: the child runs until the CLI exits, which stops it ` +
+            `(on Windows the whole process tree; on POSIX SIGTERM to the child, SIGKILL after grace).`,
     };
 }
 registerTool({
     name: 'background_run',
     description: 'Spawn a safelisted command as a non-blocking background process. Returns a bg_id immediately; ' +
         'caller polls events via monitor_emit. Same safelist + argv-only + env scrub as shell_exec. ' +
-        'Child does NOT outlive the CLI process — SIGTERM on exit, SIGKILL after grace.',
+        'No per-job stop: the child runs until the CLI exits or gets a signal, which stops it — ' +
+        'the whole process tree on Windows; SIGTERM to the child (SIGKILL after grace) on POSIX.',
     isMutating: true,
     category: 'subagent',
     flagGated: true,