@cspeach/cli 0.6.0

package/dist/tools/project/project_context_get.js

@@ -0,0 +1,101 @@
+/**
+ * project_context_get — Phase 3 / Chunk 3D.
+ *
+ * On-demand refresh of the rendered <project_context> block. Wraps
+ * Phase 2's getProjectContext + Phase 2.5's resetProjectContextCache.
+ *
+ * Returns the rendered XML-flavored block (the same shape Phase 2
+ * splices into the first user message of a flag-on session). When
+ * force_refresh: true, the per-process cache is cleared first; the
+ * next render reflects whatever the project looks like NOW (post-file_write,
+ * post-checkout, post-SAP-state-change).
+ *
+ * Flag-gated: invisible to listTools() unless
+ * CSPEACH_TOOL_PROJECT_CONTEXT_GET=on. isMutating: false — reads only.
+ *
+ * Note on caching: this tool does NOT consult the
+ * CSPEACH_PROJECT_CONTEXT env flag — it always renders, regardless of
+ * whether the flag-gated Phase 2 enrichment is on. The flag gates
+ * AUTOMATIC injection; this tool is for EXPLICIT model-driven reads.
+ */
+import { registerTool } from '../index.js';
+import { getProjectContext, renderProjectContext, } from '../../project-context/index.js';
+import { resetProjectContextCache } from '../../agent/maybe-build-project-context.js';
+// Tool-local one-shot cache so default (force_refresh: false) calls
+// return the same render as the previous call in the same process.
+// Cleared on force_refresh: true OR via __resetToolCacheForTests().
+// Independent from the Phase 2 cachedBlock — that one is gated on
+// the env flag; this one is always live for explicit tool calls.
+let cachedRender = null;
+/** Test-only: reset the tool-local cache between cases. */
+export function __resetToolCacheForTests() {
+    cachedRender = null;
+}
+export async function projectContextGetHandler(args, ctx) {
+    if (args.force_refresh !== undefined && typeof args.force_refresh !== 'boolean') {
+        return {
+            content: `error: force_refresh must be a boolean (got ${typeof args.force_refresh}).`,
+            is_error: true,
+        };
+    }
+    if (!ctx.cwd || typeof ctx.cwd !== 'string') {
+        return {
+            content: 'error: project_context_get requires a working directory (ctx.cwd).',
+            is_error: true,
+        };
+    }
+    if (args.force_refresh === true) {
+        // Phase 2.5 public API. Also clears the one-shot warning latch.
+        resetProjectContextCache();
+        cachedRender = null;
+    }
+    else if (cachedRender !== null) {
+        return { content: cachedRender };
+    }
+    let pc;
+    try {
+        pc = await getProjectContext(ctx.cwd);
+    }
+    catch (err) {
+        return {
+            content: `error: project context computation failed — ${err instanceof Error ? err.message : String(err)}`,
+            is_error: true,
+        };
+    }
+    if (pc === null) {
+        const empty = '<project_context>(no project detected for this working directory)</project_context>';
+        cachedRender = empty;
+        return { content: empty };
+    }
+    let rendered;
+    try {
+        rendered = renderProjectContext(pc);
+    }
+    catch (err) {
+        return {
+            content: `error: project context render failed — ${err instanceof Error ? err.message : String(err)}`,
+            is_error: true,
+        };
+    }
+    cachedRender = rendered;
+    return { content: rendered };
+}
+registerTool({
+    name: 'project_context_get',
+    description: "Return the rendered <project_context> block for the current working directory. " +
+        "Useful when the model needs a fresh view of the project after a write, a checkout, or a SAP state change. " +
+        "Pass force_refresh: true to invalidate the per-process cache first; default false returns the cached render.",
+    isMutating: false,
+    category: 'project',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            force_refresh: {
+                type: 'boolean',
+                description: "If true, clear the per-process project-context cache before rendering. Default false.",
+            },
+        },
+    },
+    handler: (args, ctx) => projectContextGetHandler(args, ctx),
+});

package/dist/tools/sap-read.js

@@ -0,0 +1,454 @@
+/**
+ * 18 read-only SAP tools wired to @cspeach/sap-client AdtClient.
+ *
+ * All method names verified against sap-client/src/adt-client.ts:
+ *   getSource(type, name)
+ *   objectStructure(type, name)
+ *   searchObject(query, objType?, maxResults?)
+ *   changeLog(type, name)
+ *   sqlQuery(query, maxRows?, extraBlocked?)
+ *   shortDump(dumpId?, user?)
+ *   atcRun(type, name, variant?)
+ *   usageReferences(objectType, objectName)
+ *   apiState(objects)
+ *   abapDocu(keyword)
+ *   classIncludes(className, includeType?)
+ *   inactiveObjects()
+ *   syntaxCheck(type, name)
+ *   diff(type, name, version1?, version2?)
+ *   previewChange(type, name, newSource)
+ *   runUnitTest(type, name)
+ *   odataTest(servicePath, entity?, method?)
+ *   badiList(query, enhancementSpot?, maxResults?)
+ */
+import { registerTool } from './index.js';
+// -----------------------------------------------------------------------
+// 1. sap_get_source
+// -----------------------------------------------------------------------
+registerTool({
+    name: 'sap_get_source',
+    description: 'Read the source code of an ABAP object by name and type.',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'Object name, e.g. ZCL_ORDER_HANDLER' },
+            type: { type: 'string', description: 'Object type token, e.g. CLAS, PROG, INTF, DDLS' },
+        },
+        required: ['name', 'type'],
+    },
+    handler: async (args, ctx) => {
+        // AdtClient.getSource takes (type, name) — type first
+        const source = await ctx.adt.getSource(args.type, args.name);
+        return { content: source };
+    },
+});
+// -----------------------------------------------------------------------
+// 2. sap_object_structure
+// -----------------------------------------------------------------------
+registerTool({
+    name: 'sap_object_structure',
+    description: 'Retrieve metadata and structural information for an ABAP repository object (package, description, lock state, etc.).',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'Object name, e.g. ZCL_ORDER_HANDLER' },
+            type: { type: 'string', description: 'Object type token, e.g. CLAS, PROG, INTF, DDLS' },
+        },
+        required: ['name', 'type'],
+    },
+    handler: async (args, ctx) => {
+        const result = await ctx.adt.objectStructure(args.type, args.name);
+        return { content: JSON.stringify(result, null, 2) };
+    },
+});
+// -----------------------------------------------------------------------
+// 3. sap_search_object
+// -----------------------------------------------------------------------
+registerTool({
+    name: 'sap_search_object',
+    description: 'Search the SAP repository by object name pattern. Supports wildcard * (e.g. ZCL_ORDER*).',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: 'Name pattern, e.g. ZCL_ORDER* or ZHELLO*' },
+            type: {
+                type: 'string',
+                description: 'Optional object type filter, e.g. PROG, CLAS, INTF, DDLS',
+            },
+            maxResults: {
+                type: 'number',
+                description: 'Maximum number of results (default 100)',
+            },
+        },
+        required: ['query'],
+    },
+    handler: async (args, ctx) => {
+        const results = await ctx.adt.searchObject(args.query, args.type, args.maxResults ?? 100);
+        return { content: JSON.stringify(results, null, 2) };
+    },
+});
+// -----------------------------------------------------------------------
+// 4. sap_change_log
+// -----------------------------------------------------------------------
+registerTool({
+    name: 'sap_change_log',
+    description: 'Retrieve the version history (change log) of an ABAP object — date, author, description per revision.',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'Object name, e.g. ZCL_ORDER_HANDLER' },
+            type: { type: 'string', description: 'Object type token, e.g. CLAS, PROG, INTF, DDLS' },
+        },
+        required: ['name', 'type'],
+    },
+    handler: async (args, ctx) => {
+        const entries = await ctx.adt.changeLog(args.type, args.name);
+        return { content: JSON.stringify(entries, null, 2) };
+    },
+});
+// -----------------------------------------------------------------------
+// 5. sap_sql_query
+// -----------------------------------------------------------------------
+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.',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: 'SQL SELECT statement, e.g. SELECT * FROM mara WHERE matnr = \'MAT001\'' },
+            maxRows: { type: 'number', description: 'Maximum rows to return (default 100)' },
+        },
+        required: ['query'],
+    },
+    handler: async (args, ctx) => {
+        const result = await ctx.adt.sqlQuery(args.query, args.maxRows ?? 100);
+        return { content: JSON.stringify(result, null, 2) };
+    },
+});
+// -----------------------------------------------------------------------
+// 6. sap_short_dump
+// -----------------------------------------------------------------------
+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.',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            dumpId: {
+                type: 'string',
+                description: 'Specific dump ID for detailed view (from a previous list call)',
+            },
+            user: {
+                type: 'string',
+                description: 'Filter dumps by SAP username (list mode only)',
+            },
+        },
+        required: [],
+    },
+    handler: async (args, ctx) => {
+        const result = await ctx.adt.shortDump(args.dumpId, args.user);
+        return { content: JSON.stringify(result, null, 2) };
+    },
+});
+// -----------------------------------------------------------------------
+// 7. sap_atc_run
+// -----------------------------------------------------------------------
+registerTool({
+    name: 'sap_atc_run',
+    description: 'Run ABAP Test Cockpit (ATC) checks on a specific object and return all findings.',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'Object name, e.g. ZCL_ORDER_HANDLER' },
+            type: { type: 'string', description: 'Object type token, e.g. CLAS, PROG, INTF' },
+            variant: {
+                type: 'string',
+                description: 'ATC check variant (default: DEFAULT)',
+            },
+        },
+        required: ['name', 'type'],
+    },
+    handler: async (args, ctx) => {
+        // atcRun(type, name, variant?) — type first
+        const result = await ctx.adt.atcRun(args.type, args.name, args.variant ?? 'DEFAULT');
+        return { content: JSON.stringify(result, null, 2) };
+    },
+});
+// -----------------------------------------------------------------------
+// 8. sap_usage_references
+// -----------------------------------------------------------------------
+registerTool({
+    name: 'sap_usage_references',
+    description: 'Find all places where a given ABAP object is referenced (where-used list).',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'Object name, e.g. ZCL_ORDER_HANDLER' },
+            type: { type: 'string', description: 'Object type token, e.g. CLAS, PROG, INTF, DDLS' },
+        },
+        required: ['name', 'type'],
+    },
+    handler: async (args, ctx) => {
+        // usageReferences(objectType, objectName) — type first
+        const refs = await ctx.adt.usageReferences(args.type, args.name);
+        return { content: JSON.stringify(refs, null, 2) };
+    },
+});
+// -----------------------------------------------------------------------
+// 9. sap_api_state
+// -----------------------------------------------------------------------
+registerTool({
+    name: 'sap_api_state',
+    description: 'Check the ABAP Cloud / clean-core release state of SAP objects. Pass comma-separated TYPE:NAME pairs, e.g. "CLAS:CL_GUI_ALV_GRID,FUNC:BAPI_SALESORDER_GETLIST".',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            objects: {
+                type: 'string',
+                description: 'Comma-separated TYPE:NAME pairs, e.g. "CLAS:CL_GUI_ALV_GRID,FUNC:BAPI_SALESORDER_GETLIST"',
+            },
+        },
+        required: ['objects'],
+    },
+    handler: async (args, ctx) => {
+        // apiState(objects) — single comma-separated string
+        const result = await ctx.adt.apiState(args.objects);
+        return { content: JSON.stringify(result, null, 2) };
+    },
+});
+// -----------------------------------------------------------------------
+// 10. sap_abap_docu
+// -----------------------------------------------------------------------
+registerTool({
+    name: 'sap_abap_docu',
+    description: 'Retrieve official ABAP language documentation from the SAP system for a keyword, class, or function module.',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            keyword: {
+                type: 'string',
+                description: 'ABAP keyword, class name, or function module, e.g. SELECT, CL_ABAP_UNIT_ASSERT',
+            },
+        },
+        required: ['keyword'],
+    },
+    handler: async (args, ctx) => {
+        const docu = await ctx.adt.abapDocu(args.keyword);
+        return { content: docu };
+    },
+});
+// -----------------------------------------------------------------------
+// 11. sap_class_includes
+// -----------------------------------------------------------------------
+registerTool({
+    name: 'sap_class_includes',
+    description: 'List the includes of an ABAP class, or read one specific include source (testclasses, locals_def, locals_imp, macros).',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            className: {
+                type: 'string',
+                description: 'Class name, e.g. ZCL_ORDER_HANDLER',
+            },
+            includeType: {
+                type: 'string',
+                enum: ['testclasses', 'locals_def', 'locals_imp', 'macros'],
+                description: 'Specific include to read; omit to list all includes',
+            },
+        },
+        required: ['className'],
+    },
+    handler: async (args, ctx) => {
+        const result = await ctx.adt.classIncludes(args.className, args.includeType);
+        // classIncludes returns string (source) when includeType is given, array otherwise
+        if (typeof result === 'string') {
+            return { content: result };
+        }
+        return { content: JSON.stringify(result, null, 2) };
+    },
+});
+// -----------------------------------------------------------------------
+// 12. sap_inactive_objects
+// -----------------------------------------------------------------------
+registerTool({
+    name: 'sap_inactive_objects',
+    description: 'List all ABAP objects that are currently inactive (not yet activated) in the system.',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {},
+        required: [],
+    },
+    handler: async (_args, ctx) => {
+        const result = await ctx.adt.inactiveObjects();
+        return { content: JSON.stringify(result, null, 2) };
+    },
+});
+// -----------------------------------------------------------------------
+// 13. sap_syntax_check
+// -----------------------------------------------------------------------
+registerTool({
+    name: 'sap_syntax_check',
+    description: 'Run a syntax check on an ABAP object and return any errors or warnings without activating it.',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'Object name, e.g. ZCL_ORDER_HANDLER' },
+            type: { type: 'string', description: 'Object type token, e.g. CLAS, PROG, INTF, DDLS' },
+        },
+        required: ['name', 'type'],
+    },
+    handler: async (args, ctx) => {
+        // syntaxCheck(type, name) — type first
+        const result = await ctx.adt.syntaxCheck(args.type, args.name);
+        return { content: JSON.stringify(result, null, 2) };
+    },
+});
+// -----------------------------------------------------------------------
+// 14. sap_diff
+// -----------------------------------------------------------------------
+registerTool({
+    name: 'sap_diff',
+    description: 'Compute a unified diff for an ABAP object between two optional source strings; if omitted, diffs the current version against the previous from the change log.',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'Object name, e.g. ZCL_ORDER_HANDLER' },
+            type: { type: 'string', description: 'Object type token, e.g. CLAS, PROG, INTF, DDLS' },
+            version1: {
+                type: 'string',
+                description: 'Optional "before" source text; omit to use the previous saved version',
+            },
+            version2: {
+                type: 'string',
+                description: 'Optional "after" source text; omit to use the current saved version',
+            },
+        },
+        required: ['name', 'type'],
+    },
+    handler: async (args, ctx) => {
+        // diff(type, name, version1?, version2?) — type first
+        const result = await ctx.adt.diff(args.type, args.name, args.version1, args.version2);
+        return { content: JSON.stringify(result, null, 2) };
+    },
+});
+// -----------------------------------------------------------------------
+// 15. sap_preview_change
+// -----------------------------------------------------------------------
+registerTool({
+    name: 'sap_preview_change',
+    description: 'Preview a proposed source change for an ABAP object as a unified diff without writing anything to the system.',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'Object name, e.g. ZCL_ORDER_HANDLER' },
+            type: { type: 'string', description: 'Object type token, e.g. CLAS, PROG, INTF, DDLS' },
+            newSource: {
+                type: 'string',
+                description: 'The full proposed source code to compare against the current version',
+            },
+        },
+        required: ['name', 'type', 'newSource'],
+    },
+    handler: async (args, ctx) => {
+        // previewChange(type, name, newSource) — type first
+        const result = await ctx.adt.previewChange(args.type, args.name, args.newSource);
+        return { content: JSON.stringify(result, null, 2) };
+    },
+});
+// -----------------------------------------------------------------------
+// 16. sap_run_unit_test
+// -----------------------------------------------------------------------
+registerTool({
+    name: 'sap_run_unit_test',
+    description: 'Execute ABAP Unit tests for an object and return a structured pass/fail report with method-level results.',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'Object name, e.g. ZCL_ORDER_HANDLER' },
+            type: { type: 'string', description: 'Object type token, e.g. CLAS, PROG' },
+        },
+        required: ['name', 'type'],
+    },
+    handler: async (args, ctx) => {
+        // runUnitTest(type, name) — type first
+        const result = await ctx.adt.runUnitTest(args.type, args.name);
+        return { content: JSON.stringify(result, null, 2) };
+    },
+});
+// -----------------------------------------------------------------------
+// 17. sap_odata_test
+// -----------------------------------------------------------------------
+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.',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            servicePath: {
+                type: 'string',
+                description: 'Full service path, e.g. /sap/opu/odata/sap/ZSALESORDER_SD_SRV',
+            },
+            entity: {
+                type: 'string',
+                description: 'Optional entity set name to append, e.g. SalesOrder',
+            },
+            method: {
+                type: 'string',
+                enum: ['GET', 'HEAD'],
+                description: 'HTTP method to use (default: GET)',
+            },
+        },
+        required: ['servicePath'],
+    },
+    handler: async (args, ctx) => {
+        const result = await ctx.adt.odataTest(args.servicePath, args.entity, args.method ?? 'GET');
+        return { content: JSON.stringify(result, null, 2) };
+    },
+});
+// -----------------------------------------------------------------------
+// 18. sap_badi_list
+// -----------------------------------------------------------------------
+registerTool({
+    name: 'sap_badi_list',
+    description: 'Search for BAdI definitions and enhancement spots by name pattern (supports * wildcard), with optional enhancement-spot drill-down.',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'BAdI name pattern with optional * wildcard, e.g. MD_PURCH* or BADI_SD*',
+            },
+            enhancementSpot: {
+                type: 'string',
+                description: 'Optional enhancement spot name to drill into for its BAdI definitions',
+            },
+            maxResults: {
+                type: 'number',
+                description: 'Maximum search results (default 50)',
+            },
+        },
+        required: ['query'],
+    },
+    handler: async (args, ctx) => {
+        const result = await ctx.adt.badiList(args.query, args.enhancementSpot, args.maxResults ?? 50);
+        return { content: JSON.stringify(result, null, 2) };
+    },
+});