@cspeach/cli 0.9.0 → 1.1.0

package/dist/tools/sap-read.js

@@ -7,7 +7,7 @@
  *   searchObject(query, objType?, maxResults?)
  *   changeLog(type, name)
  *   sqlQuery(query, maxRows?, extraBlocked?)
- *   shortDump(dumpId?, user?)
+ *   shortDump(dumpId?, user?, fromDate?, toDate?)
  *   atcRun(type, name, variant?)
  *   usageReferences(objectType, objectName)
  *   apiState(objects)
@@ -32,7 +32,9 @@ registerTool({
         + 'omitting it lets SAP choose (usually active). When the object has '
         + 'pending inactive changes and the caller did not pass `version`, '
         + 'the response is the active source AND a warning is emitted so the '
-        + 'caller knows the inactive edits are not visible.',
+        + 'caller knows the inactive edits are not visible. For a freshly '
+        + 'created object with NO active version yet, the inactive (working) '
+        + 'source is returned with version="inactive" and an honest note.',
     isMutating: false,
     input_schema: {
         type: 'object',
@@ -68,15 +70,41 @@ registerTool({
                 const conflict = inactive.find((o) => o.name.toUpperCase() === upperName &&
                     (o.type === '' || o.type.toUpperCase().startsWith(upperType)));
                 if (conflict) {
-                    // SAP defaults to the active version when version is unspecified,
-                    // but the caller should know an inactive copy exists so they don't
-                    // base dependent edits on stale committed source.
-                    resolvedVersion = 'active';
-                    splitStateWarning =
-                        `${args.type} ${args.name} has a pending inactive version. `
-                            + `This response is the ACTIVE source; pending edits are NOT included. `
-                            + `Pass version="inactive" to read the in-flight version, or have the user `
-                            + `activate (or discard) the inactive version before basing dependent code on this read.`;
+                    // Fable review 2026-07-06 (clas-create-hygiene I1): a FRESH shell
+                    // (created, never activated) ALSO appears in inactiveObjects(), but
+                    // it has NO active version at all — sap-client's inactive-read
+                    // fallback just served the INACTIVE (working) source. Claiming
+                    // "this is the ACTIVE source" here would be false. Cross-check
+                    // objectStructure's adtcore:version (honest for fresh shells now
+                    // that objectStructure carries the same inactive fallback):
+                    // 'inactive' ⇒ inactive-only shell.
+                    let inactiveOnly = false;
+                    try {
+                        const struct = await ctx.adt.objectStructure(args.type, args.name);
+                        const m = /\badtcore:version="([^"]*)"/.exec(struct.rawXml ?? '');
+                        inactiveOnly = m?.[1] === 'inactive';
+                    }
+                    catch {
+                        // Cross-check failed — fall through to the conservative
+                        // split-state warning (never claim inactive-only without proof).
+                    }
+                    if (inactiveOnly) {
+                        resolvedVersion = 'inactive';
+                        splitStateWarning =
+                            `${args.type} ${args.name} has no active version yet — this is the `
+                                + `inactive (working) source. Activate it via sap_activate when ready.`;
+                    }
+                    else {
+                        // SAP defaults to the active version when version is unspecified,
+                        // but the caller should know an inactive copy exists so they don't
+                        // base dependent edits on stale committed source.
+                        resolvedVersion = 'active';
+                        splitStateWarning =
+                            `${args.type} ${args.name} has a pending inactive version. `
+                                + `This response is the ACTIVE source; pending edits are NOT included. `
+                                + `Pass version="inactive" to read the in-flight version, or have the user `
+                                + `activate (or discard) the inactive version before basing dependent code on this read.`;
+                    }
                 }
                 else {
                     resolvedVersion = 'active';
@@ -112,7 +140,22 @@ registerTool({
     },
     handler: async (args, ctx) => {
         const result = await ctx.adt.objectStructure(args.type, args.name);
-        return { content: JSON.stringify(result, null, 2) };
+        // Fable review 2026-07-05 (audit-reverify item 2) — surface the object's
+        // adtcore:version EARLY in the JSON. The sap-client ObjectStructure has
+        // no parsed version field; adtcore:version lives deep inside rawXml,
+        // beyond the audit evidence's 200-char result excerpt — so the audit
+        // contract's "sap_object_structure reporting an active version" proof
+        // path for verify-only re-runs was unreachable in production, and a
+        // re-run that skipped sap_inactive_objects would false-FAIL an active
+        // object. Parsing here (CLI-side, no sap-client bump) and placing
+        // `version` right after name/type puts it inside the excerpt window.
+        const versionMatch = /\badtcore:version="([^"]*)"/.exec(result.rawXml ?? '');
+        const version = versionMatch?.[1] || 'unknown';
+        // name/type/version lead the serialized JSON (rawXml stays last via the
+        // rest spread), so `version` sits inside the excerpt window while every
+        // ObjectStructure field is preserved.
+        const { name, type, ...rest } = result;
+        return { content: JSON.stringify({ name, type, version, ...rest }, null, 2) };
     },
 });
 // -----------------------------------------------------------------------
@@ -167,7 +210,9 @@ registerTool({
 // -----------------------------------------------------------------------
 registerTool({
     name: 'sap_sql_query',
-    description: 'Execute a read-only SQL SELECT against the SAP database via ADT Data Preview. Security-sensitive tables are blocked automatically.',
+    description: 'Execute a read-only SQL SELECT against the SAP database via ADT Data Preview. Security-sensitive tables are blocked automatically. '
+        + 'Dialect limits (violations return an opaque "SAP HTTP 400: sqlQuery"): no IN-lists and at most one LIKE per WHERE clause '
+        + '(multi-OR LIKE chains are rejected) — use a single LIKE or split into separate queries.',
     isMutating: false,
     input_schema: {
         type: 'object',
@@ -187,7 +232,10 @@ registerTool({
 // -----------------------------------------------------------------------
 registerTool({
     name: 'sap_short_dump',
-    description: 'Read ABAP runtime errors (short dumps / ST22). Without dumpId returns a list of recent dumps; with dumpId returns the full diagnostic detail.',
+    description: 'Read ABAP runtime errors (short dumps / ST22). Without dumpId returns dumps from a '
+        + 'time window (default: the last 24h of SAP SYSTEM time), paginated server-side; the '
+        + 'result includes a `coverage` line stating exactly which window was fetched — trust it '
+        + 'over assumptions. With dumpId returns the full diagnostic detail.',
     isMutating: false,
     input_schema: {
         type: 'object',
@@ -198,13 +246,43 @@ registerTool({
             },
             user: {
                 type: 'string',
-                description: 'Filter dumps by SAP username (list mode only)',
+                description: 'Filter dumps by SAP username (list mode only, applied after the windowed fetch)',
+            },
+            fromDate: {
+                type: 'string',
+                description: 'Window start (list mode). Zone-less values are SAP SYSTEM time: "YYYYMMDDHHMMSS", '
+                    + '"YYYY-MM-DD" (day start) or "2026-06-11T06:00:00". ISO-8601 with timezone '
+                    + '("2026-06-11T06:00:00Z") is an absolute instant, auto-translated to system time. '
+                    + 'Default: now − 24h (or 24h before an explicit toDate).',
+            },
+            toDate: {
+                type: 'string',
+                description: 'Window end (list mode). Same formats as fromDate ("YYYY-MM-DD" = day end). '
+                    + 'Default: now (SAP system time).',
             },
         },
         required: [],
     },
     handler: async (args, ctx) => {
-        const result = await ctx.adt.shortDump(args.dumpId, args.user);
+        const result = await ctx.adt.shortDump(args.dumpId, args.user, args.fromDate, args.toDate);
+        // List mode: lead with a coverage line so the model KNOWS what slice of
+        // time it is looking at (battery D18 — the old list was the feed's
+        // arbitrary first page and the newest dumps were routinely missing).
+        if (result.operation === 'list' && result.window) {
+            const w = result.window;
+            let coverage = `showing ${result.count} dump(s) from window ${w.windowFromSap}–${w.windowToSap} `
+                + `(SAP system time${w.windowFromUtc ? `; UTC ${w.windowFromUtc}–${w.windowToUtc}` : ''}); `
+                + `${w.totalFetched} in window before filters; ${w.pagesFetched} page(s) fetched`;
+            if (w.clockProbe === 'failed') {
+                coverage +=
+                    '; WARNING: system clock probe failed — window widened by ±1 day, timestamps are approximate';
+            }
+            if (w.capped) {
+                coverage +=
+                    '; WARNING: page cap hit — window NOT fully covered, narrow fromDate/toDate to see the rest';
+            }
+            return { content: JSON.stringify({ coverage, ...result }, null, 2) };
+        }
         return { content: JSON.stringify(result, null, 2) };
     },
 });
@@ -440,6 +518,31 @@ registerTool({
     handler: async (args, ctx) => {
         // runUnitTest(type, name) — type first
         const result = await ctx.adt.runUnitTest(args.type, args.name);
+        // B2 false-green guard (project_aunit_run_gap): the ADT AUnit-run endpoint
+        // returns HTTP 200 with an EMPTY runResult (total:0, no programs) even for a
+        // class that is active + syntax-clean with a valid FOR TESTING local class —
+        // a known environmental gap, exhaustively probed (sap-client buildUnitTestXml
+        // comment). The raw {total:0} shape reads to a caller like "0 tests, nothing
+        // failed → green", so an unguarded pass-through risks a false-green test gate.
+        // When we detect that empty signature, wrap the (still-carried) raw result in
+        // an explicit UNVERIFIED envelope that names Eclipse "Run As → ABAP Unit" as
+        // the authoritative check. A genuine run (total > 0) passes through unchanged.
+        const summary = result?.summary;
+        const programs = result?.programs;
+        const noTestsRun = summary?.total === 0 && (!Array.isArray(programs) || programs.length === 0);
+        if (noTestsRun) {
+            return {
+                content: JSON.stringify({
+                    verification: 'UNVERIFIED',
+                    warning: 'ABAP Unit run enumerated 0 tests (empty runResult). This does NOT mean the tests ' +
+                        'passed — it means none executed. A FOR TESTING class that is active + syntax-clean ' +
+                        'still returning 0 is a known ADT AUnit-run gap (project_aunit_run_gap): the ' +
+                        'authoritative check is Eclipse "Run As → ABAP Unit" (Ctrl+Shift+F10). Do NOT treat ' +
+                        'this as a green test gate.',
+                    result,
+                }, null, 2),
+            };
+        }
         return { content: JSON.stringify(result, null, 2) };
     },
 });
@@ -448,18 +551,27 @@ registerTool({
 // -----------------------------------------------------------------------
 registerTool({
     name: 'sap_odata_test',
-    description: 'Test an OData service endpoint by issuing a GET or HEAD request and returning the HTTP status and response body.',
+    description: 'Test an OData service endpoint (V2 or V4). Fetches $metadata or reads an entity set and returns the real HTTP status, the request URL/Accept actually used, and the response body. Works on draft-enabled OData V4 RAP services: V4 is auto-detected from /odata4/ paths, $metadata gets an XML Accept, and data reads use a JSON Accept without the V2-only $format option. System query options ($metadata, $top, $filter, $select, $expand, $count) are preserved literally.',
     isMutating: false,
     input_schema: {
         type: 'object',
         properties: {
             servicePath: {
                 type: 'string',
-                description: 'Full service path, e.g. /sap/opu/odata/sap/ZSALESORDER_SD_SRV',
+                description: 'Full service path. V2 e.g. /sap/opu/odata/sap/ZSALESORDER_SD_SRV; V4 e.g. /sap/opu/odata4/sap/zui_x_o4/srvd/sap/zui_x/0001',
             },
             entity: {
                 type: 'string',
-                description: 'Optional entity set name to append, e.g. SalesOrder',
+                description: 'Optional entity set name to append and read, e.g. SalesOrder',
+            },
+            query: {
+                type: 'string',
+                description: 'Optional raw OData query/resource. Pass "$metadata" to fetch the metadata document, or query options like "$top=5&$filter=Status eq \'OPEN\'". $ signs are preserved as-is. Overrides the default $top=5 when an entity is given.',
+            },
+            version: {
+                type: 'string',
+                enum: ['v2', 'v4'],
+                description: 'OData version override. Normally auto-detected (/odata4/ ⇒ v4, else v2). Set this only when the path does not reveal the version.',
             },
             method: {
                 type: 'string',
@@ -470,7 +582,7 @@ registerTool({
         required: ['servicePath'],
     },
     handler: async (args, ctx) => {
-        const result = await ctx.adt.odataTest(args.servicePath, args.entity, args.method ?? 'GET');
+        const result = await ctx.adt.odataTest(args.servicePath, args.entity, args.method ?? 'GET', { query: args.query, version: args.version });
         return { content: JSON.stringify(result, null, 2) };
     },
 });