arc-1 0.9.6 → 0.9.7

package/dist/handlers/intent.js

@@ -11,8 +11,9 @@
  */
 import { checkRepo as abapGitCheckRepo, createBranch as abapGitCreateBranch, createRepo as abapGitCreateRepo, getExternalInfo as abapGitGetExternalInfo, listRepos as abapGitListRepos, pullRepo as abapGitPullRepo, pushRepo as abapGitPushRepo, stageRepo as abapGitStageRepo, switchBranch as abapGitSwitchBranch, unlinkRepo as abapGitUnlinkRepo, } from '../adt/abapgit.js';
 import { buildSiblingExtensionFinding, classifyCdsImpact, deriveSiblingStem, isSiblingNameMatch, } from '../adt/cds-impact.js';
+import { diffMethodSets, extractMethodNameFromClause, findSectionAnchor, insertMethodPair, moveMethodDefinition, removeMethodPair, spliceClassDefinition, spliceMethodSignature, } from '../adt/class-structure.js';
 import { findDefinition, findInterfaceImplementersViaSeoMetaRel, findReferences, findWhereUsed, getCompletion, getWhereUsedScope, } from '../adt/codeintel.js';
-import { createObject, deleteObject, lockObject, safeUpdateObject, safeUpdateSource, unlockObject, updateObject, updateSource, } from '../adt/crud.js';
+import { createObject, deleteObject, lockObject, safeUpdateClassInclude, safeUpdateObject, safeUpdateSource, unlockObject, updateObject, updateSource, } from '../adt/crud.js';
 import { buildDataElementXml, buildDomainXml, buildMessageClassXml, buildPackageXml, buildServiceBindingXml, decodeKtdText, rewriteKtdText, } from '../adt/ddic-xml.js';
 import { activate, activateBatch, applyFixProposal, getFixProposals, getPrettyPrinterSettings, prettyPrint, publishServiceBinding, runAtcCheck, runUnitTests, setPrettyPrinterSettings, syntaxCheck, unpublishServiceBinding, } from '../adt/devtools.js';
 import { getDump, getGatewayErrorDetail, getObjectState, getTraceDbAccesses, getTraceHitlist, getTraceStatements, listDumps, listGatewayErrors, listSystemMessages, listTraces, } from '../adt/diagnostics.js';
@@ -31,6 +32,7 @@ import { getAppInfo } from '../adt/ui5-repository.js';
 import { validateAffHeader } from '../aff/validator.js';
 import { extractCdsDependencies, extractCdsElements } from '../context/cds-deps.js';
 import { compressCdsContext, compressContext } from '../context/compressor.js';
+import { grepSource } from '../context/grep.js';
 import { extractMethod, formatMethodListing, listMethods, spliceMethod } from '../context/method-surgery.js';
 import { buildLintConfig, listRulesFromConfig, } from '../lint/config-builder.js';
 import { detectFilename, lintAbapSource, lintAndFix, validateBeforeWrite } from '../lint/lint.js';
@@ -227,7 +229,11 @@ function buildBaseErrorMessage(err, message, tool, args, config) {
         // Append additional SAP messages (line numbers, secondary errors) if available
         const enriched = enrichWithSapDetails(err, message);
         const argType = canonicalTablType(String(args.type ?? '').toUpperCase());
-        const classification = classifySapDomainError(err.statusCode, err.responseBody, err.path);
+        // Pass the detected SAP_BASIS release so the 423 lock-handle hint can specialize
+        // (< 7.51 → point at abapfs_extensions; see issue #293). cachedFeatures is set by the
+        // startup probe; config.abapRelease is the manual SAP_ABAP_RELEASE override fallback.
+        const abapRelease = cachedFeatures?.abapRelease ?? config.abapRelease;
+        const classification = classifySapDomainError(err.statusCode, err.responseBody, err.path, abapRelease);
         if (classification) {
             const transactionLine = classification.transaction ? `\nSAP Transaction: ${classification.transaction}` : '';
             return `${enriched}\n\nHint: ${classification.hint}${transactionLine}`;
@@ -263,6 +269,14 @@ function buildBaseErrorMessage(err, message, tool, args, config) {
                     `sqlFilter="MANDT = '100'" or sqlFilter="MATNR LIKE 'Z%'".`);
             }
         }
+        if (tool === 'SAPRead' && argType === 'TABLE_QUERY' && err.statusCode === 400) {
+            const combined = `${err.message}\n${err.responseBody ?? ''}`;
+            if (/is invalid here|due to grammar/i.test(combined)) {
+                return (`${enriched}\n\nHint: TABLE_QUERY parser error — check field names match the actual column names ` +
+                    'exposed by the table/CDS view (use SAPRead(type="DDLS", include="elements") to inspect CDS view fields). ' +
+                    'Also verify value formats (e.g. FiscalPeriod is C(2,0) so use "01" not "001").');
+            }
+        }
         const behaviorPoolHint = getBehaviorPoolSaveFailureHint(err, args);
         if (behaviorPoolHint) {
             return `${enriched}\n\nHint: ${behaviorPoolHint}`;
@@ -1105,6 +1119,11 @@ async function handleSAPRead(client, args, cachingLayer) {
         const indicator = cacheHit && revalidated ? '[cached:revalidated]\n' : '';
         return textResult(`${note}${indicator}${source}`);
     };
+    /** When args.grep is set, return only matching source lines (+context) instead of full source. */
+    const grepText = (source) => {
+        const g = grepSource(source, String(args.grep));
+        return g.invalidPattern ? errorResult(g.output) : textResult(g.output);
+    };
     // Structured format is only supported for CLAS type
     if (args.format === 'structured' && type !== 'CLAS') {
         return errorResult('The "structured" format is only supported for CLAS type. Other types return text format.');
@@ -1112,9 +1131,45 @@ async function handleSAPRead(client, args, cachingLayer) {
     switch (type) {
         case 'PROG': {
             const { source, cacheHit, revalidated } = await cachedGet('PROG', name, effectiveVersion, (ifNoneMatch) => client.getProgram(name, { ifNoneMatch, version: effectiveVersion }));
+            if (args.grep)
+                return grepText(source);
             return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'CLAS': {
+            // grep: return only matching source lines (+context), annotated with the owning class/method.
+            if (args.grep) {
+                if (args.method) {
+                    return errorResult('Do not combine grep with method. Use grep to find code, then method="<name>" to read the full method.');
+                }
+                const rawSection = args.include;
+                // 'main' (and the default) live at /source/main, not /includes/main — read via the
+                // cached main path; only real sub-includes go through the raw getClassInclude endpoint.
+                const section = rawSection && rawSection.toLowerCase() !== 'main' ? rawSection : undefined;
+                let clasSource;
+                if (section) {
+                    try {
+                        clasSource = (await client.getClassInclude(name, section, { version: effectiveVersion })).source;
+                    }
+                    catch (err) {
+                        if (isNotFoundError(err)) {
+                            return textResult(`Include "${section}" is not available for class ${name}. Run grep without include= to search the full class source.`);
+                        }
+                        throw err;
+                    }
+                }
+                else {
+                    clasSource = (await cachedGet('CLAS', name, effectiveVersion, (ifNoneMatch) => client.getClass(name, undefined, { ifNoneMatch, version: effectiveVersion }))).source;
+                }
+                const abaplintVer = cachedFeatures?.abapRelease
+                    ? mapSapReleaseToAbaplintVersion(cachedFeatures.abapRelease)
+                    : undefined;
+                // MethodInfo is a structural superset of grepSource's MethodRange — pass through directly.
+                const listing = listMethods(clasSource, name, abaplintVer);
+                const g = grepSource(clasSource, String(args.grep), listing.success ? { methods: listing.methods } : undefined);
+                return g.invalidPattern
+                    ? errorResult(g.output)
+                    : textResult(`[${name} section=${rawSection ?? 'main'}]\n${g.output}`);
+            }
             // Structured format: return JSON with metadata + decomposed source
             if (args.format === 'structured') {
                 const structured = await client.getClassStructured(name);
@@ -1149,6 +1204,8 @@ async function handleSAPRead(client, args, cachingLayer) {
         }
         case 'INTF': {
             const { source, cacheHit, revalidated } = await cachedGet('INTF', name, effectiveVersion, (ifNoneMatch) => client.getInterface(name, { ifNoneMatch, version: effectiveVersion }));
+            if (args.grep)
+                return grepText(source);
             return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'FUNC': {
@@ -1184,6 +1241,8 @@ async function handleSAPRead(client, args, cachingLayer) {
                 };
                 return textResult(JSON.stringify(payload, null, 2));
             }
+            if (args.grep)
+                return grepText(source);
             return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'FUGR': {
@@ -1211,6 +1270,8 @@ async function handleSAPRead(client, args, cachingLayer) {
         }
         case 'INCL': {
             const { source, cacheHit, revalidated } = await cachedGet('INCL', name, effectiveVersion, (ifNoneMatch) => client.getInclude(name, { ifNoneMatch, version: effectiveVersion }));
+            if (args.grep)
+                return grepText(source);
             return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'DDLS': {
@@ -1223,23 +1284,33 @@ async function handleSAPRead(client, args, cachingLayer) {
                 // Elements extraction is derived from source — no cache indicator
                 return cachedTextResult(extractCdsElements(ddlSource, name), false, false, versionWarning);
             }
+            if (args.grep)
+                return grepText(ddlSource);
             return cachedTextResult(ddlSource, cacheHit, revalidated, versionWarning);
         }
         case 'DCLS': {
             const { source, cacheHit, revalidated } = await cachedGet('DCLS', name, effectiveVersion, (ifNoneMatch) => client.getDcl(name, { ifNoneMatch, version: effectiveVersion }));
+            if (args.grep)
+                return grepText(source);
             return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'BDEF': {
             const { source, cacheHit, revalidated } = await cachedGet('BDEF', name, effectiveVersion, (ifNoneMatch) => client.getBdef(name, { ifNoneMatch, version: effectiveVersion }));
+            if (args.grep)
+                return grepText(source);
             return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'SRVD': {
             const { source, cacheHit, revalidated } = await cachedGet('SRVD', name, effectiveVersion, (ifNoneMatch) => client.getSrvd(name, { ifNoneMatch, version: effectiveVersion }));
+            if (args.grep)
+                return grepText(source);
             return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'DDLX': {
             try {
                 const { source, cacheHit, revalidated } = await cachedGet('DDLX', name, effectiveVersion, (ifNoneMatch) => client.getDdlx(name, { ifNoneMatch, version: effectiveVersion }));
+                if (args.grep)
+                    return grepText(source);
                 return cachedTextResult(source, cacheHit, revalidated, versionWarning);
             }
             catch (err) {
@@ -1273,10 +1344,14 @@ async function handleSAPRead(client, args, cachingLayer) {
             // client.getTabl() handles the /tables/ → /structures/ fallback internally
             // and caches the resolved URL for subsequent write/activate paths.
             const { source, cacheHit, revalidated } = await cachedGet('TABL', name, effectiveVersion, (ifNoneMatch) => client.getTabl(name, { ifNoneMatch, version: effectiveVersion }));
+            if (args.grep)
+                return grepText(source);
             return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'VIEW': {
             const { source, cacheHit, revalidated } = await cachedGet('VIEW', name, effectiveVersion, (ifNoneMatch) => client.getView(name, { ifNoneMatch, version: effectiveVersion }));
+            if (args.grep)
+                return grepText(source);
             return cachedTextResult(source, cacheHit, revalidated, versionWarning);
         }
         case 'DOMA': {
@@ -1383,6 +1458,15 @@ async function handleSAPRead(client, args, cachingLayer) {
             const data = await client.getTableContents(name, maxRows, args.sqlFilter);
             return textResult(JSON.stringify(data, null, 2));
         }
+        case 'TABLE_QUERY': {
+            const maxRows = Number(args.maxRows ?? 100);
+            const columns = Array.isArray(args.columns) ? args.columns : undefined;
+            const where = Array.isArray(args.where)
+                ? args.where
+                : undefined;
+            const data = await client.runTableQuery(name, { columns, where, maxRows });
+            return textResult(JSON.stringify(data, null, 2));
+        }
         case 'SOBJ': {
             const method = String(args.method ?? '');
             // Sanitize inputs to prevent SQL injection — BOR names are alphanumeric + underscore only
@@ -1542,7 +1626,7 @@ async function handleSAPSearch(client, args) {
                 // keeps the same logical object from appearing twice in the merged matches.
                 // Preserve the more-specific slash form when both originate from ADT+DB.
                 const seen = new Map();
-                const baseKey = (m) => `${(m.objectType.split('/')[0] || m.objectType).toUpperCase()}${m.objectName.toUpperCase()}`;
+                const baseKey = (m) => `${(m.objectType.split('/')[0] || m.objectType).toUpperCase()}\x00${m.objectName.toUpperCase()}`;
                 for (const m of adtMatches)
                     seen.set(baseKey(m), m);
                 for (const m of dbMatches) {
@@ -2924,6 +3008,12 @@ function stripIncludeHeader(source) {
     return source.replace(/^=== \w+ ===\n/, '');
 }
 // ─── SAPWrite Handler ────────────────────────────────────────────────
+/**
+ * Single-object actions whose top-level `name` is an SAP object name and must be
+ * uppercase (TADIR convention). `batch_create` is excluded — its names live in
+ * the `objects[]` items and are validated per item in the batch_create branch.
+ */
+const NAME_CASE_GUARD_ACTIONS = new Set(['create', 'update', 'edit_method', 'delete']);
 async function handleSAPWrite(client, args, config, cachingLayer) {
     const action = String(args.action ?? '');
     const type = normalizeWriteObjectType(String(args.type ?? ''));
@@ -2931,6 +3021,10 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
     const source = String(args.source ?? '');
     const hasSource = typeof args.source === 'string';
     const include = normalizeClassWriteInclude(args.include);
+    // Whether a non-empty include was actually requested. Some MCP clients serialize
+    // an omitted optional string as "" — treat empty/whitespace as "not provided" so
+    // those clients aren't rejected with a bogus "Invalid CLAS include" on the MAIN path.
+    const includeProvided = typeof args.include === 'string' && args.include.trim() !== '';
     const transport = args.transport;
     const lintOverride = args.lintBeforeWrite;
     const preflightOverride = args.preflightBeforeWrite;
@@ -2940,12 +3034,16 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
         return errorResult('"type" and "name" are required for this action.');
     }
     // SAP TADIR stores object names uppercase. Mixed-case names cause silent corruption
-    // (e.g. DDLS created as "Zc_MyView" registers as "ZC_MYVIEW" in TADIR but the source body
-    // still contains "Zc_MyView", confusing every downstream tool). Reject pre-flight on create —
-    // applies on every SAP release; this is universal SAP convention, not a 7.50 quirk.
+    // on create (e.g. DDLS "Zc_MyView" registers as "ZC_MYVIEW" in TADIR but the source body
+    // still contains "Zc_MyView", confusing every downstream tool) and broken URL lookups on
+    // mutate/delete — the lock is held against the canonical uppercase name while the request
+    // URL carries the mixed-case one, which surfaces on ECC as 423 "... is not locked" (issue
+    // #293, original report used name "Z_HELLO_world"). Reject pre-flight for every name-bearing
+    // single-object action — universal SAP convention, not a 7.50 quirk. (batch_create validates
+    // each item separately below.)
     // Note: source code INSIDE the object can use mixed case (e.g. for DDLS: name="ZC_MYVIEW"
     // but `define view entity Zc_MyView` is fine inside the source body).
-    if (action === 'create' && name && name !== name.toUpperCase()) {
+    if (NAME_CASE_GUARD_ACTIONS.has(action) && name && name !== name.toUpperCase()) {
         return errorResult(`Object name "${name}" contains lowercase characters. SAP object names must be uppercase (e.g. "${name.toUpperCase()}").\n\n` +
             `Note: the object NAME in TADIR must be uppercase, but the source code inside the object can use mixed case ` +
             `(e.g. for DDLS: name="${name.toUpperCase()}" but source can contain "define view entity ${name}").`);
@@ -3023,14 +3121,35 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
     };
     // Helper: enforce allowedPackages for existing objects (update/delete/edit_method/scaffold_rap_handlers).
     // Only fetches metadata when package restrictions are configured — no extra HTTP call otherwise.
+    // Fail-closed: if the package cannot be determined from ADT metadata, refuse the write
+    // rather than silently passing through the allowlist gate.
     async function enforcePackageForExistingObject() {
         if (client.safety.allowedPackages.length === 0)
             return undefined;
         const pkg = await client.resolveObjectPackage(objectUrl);
-        if (pkg)
-            checkPackage(client.safety, pkg);
+        if (!pkg) {
+            throw new AdtSafetyError(`Operations on ${type} '${name}' blocked: ARC-1 could not determine the object's package ` +
+                `from ADT metadata (no adtcore:packageRef in response). Fail-closed because allowedPackages is restricted.`);
+        }
+        await checkPackage(client.safety, pkg, client.getPackageHierarchyResolver());
         return pkg;
     }
+    // Helper for class-section surgery (issue #303): fetch the class structure AND
+    // /source/main at the SAME effective version, so the spliced line ranges line
+    // up with the bytes being edited. resolveVersionAndDraftInfo picks 'inactive'
+    // when an unactivated draft exists. We pass that version to BOTH getClassStructure
+    // (the /objectstructure?version= read) and the source read, AND to the cache opts
+    // (so inactive bytes aren't cached under the 'active' key). Without this, a chained
+    // surgery call on a draft would splice active-version line ranges into inactive
+    // source and silently corrupt the draft.
+    async function fetchClassStructureAndMain(clsName) {
+        const { effectiveVersion } = await resolveVersionAndDraftInfo(client, cachingLayer, 'CLAS', clsName, 'auto');
+        const structure = await client.getClassStructure(clsName, effectiveVersion);
+        const main = cachingLayer
+            ? (await cachingLayer.getSource('CLAS', clsName, (ifNoneMatch) => client.getClass(clsName, undefined, { ifNoneMatch, version: effectiveVersion }), { version: effectiveVersion })).source
+            : (await client.getClass(clsName, undefined, { version: effectiveVersion })).source;
+        return { structure, main, effectiveVersion };
+    }
     switch (action) {
         case 'update': {
             const existingPackage = await enforcePackageForExistingObject();
@@ -3047,9 +3166,14 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                 if (!hasSource) {
                     return errorResult('"source" is required when updating a CLAS include.');
                 }
-                await safeUpdateSource(client.http, client.safety, objectUrl, classIncludeUrl(name, include), source, transport, cachedFeatures?.abapRelease);
+                // Auto-initialise the include if it doesn't exist yet. On a fresh class
+                // the testclasses (CCAU) include is absent — a content PUT alone fails
+                // with HTTP 500 "…CCAU does not have any inactive version". safeUpdateClassInclude
+                // probes the include and POST-creates it (under the same lock) before the PUT.
+                const { initialized } = await safeUpdateClassInclude(client.http, client.safety, objectUrl, classIncludeUrl(name, include), source, transport, cachedFeatures?.abapRelease);
                 invalidateWrittenObject(type, name);
-                return textResult(`Successfully updated ${type} ${name} include ${include}. Active version remains unchanged until activation; read with SAPRead(version="inactive") to verify the draft.`);
+                const initNote = initialized ? ` (initialised the ${include} include first)` : '';
+                return textResult(`Successfully updated ${type} ${name} include ${include}${initNote}. Active version remains unchanged until activation; read with SAPRead(version="inactive") to verify the draft.`);
             }
             if (type === 'SKTD') {
                 // KTD update requires the full <sktd:docu> XML envelope with the Markdown
@@ -3150,7 +3274,7 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
         }
         case 'create': {
             const pkg = String(args.package ?? '$TMP');
-            checkPackage(client.safety, pkg);
+            await checkPackage(client.safety, pkg, client.getPackageHierarchyResolver());
             const description = String(args.description ?? name);
             // Pre-flight: check transport requirements for non-$TMP packages when no transport provided.
             // SAP requires a transport number for objects in transportable packages.
@@ -3466,6 +3590,261 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
             const extras = [lintWarnings.warnings, checkNotes].filter(Boolean).join('\n\n');
             return extras ? textResult(`${msg}\n\n${extras}`) : textResult(msg);
         }
+        // ─── Class-section surgery actions (issue #303) ─────────────────────
+        //
+        // Four actions share a common shape: fetch objectstructure → optional
+        // diff/refuse → splice into /source/main (or /includes/<inc> when
+        // include= is set) → PUT under lock → no auto-activate.
+        //
+        // Pre-write lint runs on the SPLICED FULL source (not the partial input
+        // fragment) because a raw DEFINITION block alone fails abaplint with
+        // "Expected CLASSIMPLEMENTATION" — verified live on a4h. Lint is skipped
+        // for include= writes (same precedent as `update include=` path).
+        case 'edit_class_definition': {
+            if (type !== 'CLAS')
+                return errorResult('edit_class_definition is only supported for type=CLAS.');
+            if (!hasSource)
+                return errorResult('"source" (new CLASS DEFINITION block) is required for edit_class_definition.');
+            if (includeProvided && !include) {
+                return errorResult(`Invalid CLAS include "${String(args.include)}". Valid values: ${CLASS_WRITE_INCLUDES.join(', ')}.`);
+            }
+            await enforcePackageForExistingObject();
+            const writeUrl = include ? classIncludeUrl(name, include) : srcUrl;
+            let spliced;
+            if (include) {
+                // include= path: whole-replace the local include (CCDEF/CCIMP/macros/
+                // testclasses). The structure-based diff/refuse doesn't apply — the
+                // /objectstructure endpoint reports the GLOBAL class, not the local
+                // include's split DEFINITION/IMPLEMENTATION halves. SAP activation is the
+                // validator here (same precedent as `update include=`). No structure or
+                // source fetch is needed: the caller's `source` IS the new include body.
+                spliced = source.endsWith('\n') ? source : `${source}\n`;
+            }
+            else {
+                // MAIN path: fetch structure + source at the same effective version so
+                // the spliced line ranges align with the bytes being edited.
+                const { structure, main } = await fetchClassStructureAndMain(name);
+                // Refuse-policy: compute the method-set diff against the NEW DEFINITION.
+                const diff = diffMethodSets(structure, source);
+                const missingImpls = [];
+                const orphanImpls = [];
+                for (const add of diff.added) {
+                    // Exempt declarations that never have a METHOD…ENDMETHOD body.
+                    if (add.isAbstract || add.isEvent || add.isInterface || add.isAlias)
+                        continue;
+                    // Does IMPLEMENTATION already have a METHOD <name> header? Match the
+                    // method name followed by a word-boundary so AMDP / event-handler /
+                    // multi-line headers (`METHOD x BY DATABASE PROCEDURE…`, `METHOD x FOR
+                    // EVENT…`, `METHOD x\n  IMPORTING…`) are recognized — NOT only the bare
+                    // `METHOD x.` form. \b after the name prevents matching a longer name
+                    // with the same prefix (METHOD x_helper for added X).
+                    const re = new RegExp(`^\\s*METHOD\\s+${add.name}\\b`, 'im');
+                    if (!re.test(main))
+                        missingImpls.push(add.name);
+                }
+                for (const rem of diff.removed) {
+                    if (rem.implementation) {
+                        // Was concrete, still has impl range — caller didn't remove the body.
+                        orphanImpls.push(rem.name);
+                    }
+                }
+                if (missingImpls.length > 0 || orphanImpls.length > 0) {
+                    const parts = [];
+                    if (missingImpls.length > 0) {
+                        parts.push(`Cannot apply edit_class_definition: the new DEFINITION declares method(s) ${missingImpls.join(', ')} but the existing IMPLEMENTATION block has no matching METHOD…ENDMETHOD body. Either include a METHOD <name>. ENDMETHOD. block per added method in your new source, or use SAPWrite(action="add_method", name="${name}", method="<METHODS clause>") to insert each one atomically.`);
+                    }
+                    if (orphanImpls.length > 0) {
+                        parts.push(`Cannot apply edit_class_definition: the new DEFINITION removes method(s) ${orphanImpls.join(', ')} but the existing IMPLEMENTATION block still has METHOD…ENDMETHOD bodies for them (orphan implementation). Either remove those METHOD blocks in your edit, or use SAPWrite(action="delete_method", name="${name}", method="<name>") to drop each one atomically.`);
+                    }
+                    return errorResult(parts.join('\n\n'));
+                }
+                spliced = spliceClassDefinition(main, structure, source);
+            }
+            // Pre-write lint on the spliced full source (MAIN path only — include=
+            // fragments can't be lint-parsed standalone).
+            if (!include) {
+                const lintWarnings = runPreWriteLint(spliced, type, name, config, lintOverride);
+                if (lintWarnings.blocked)
+                    return lintWarnings.result;
+            }
+            await safeUpdateSource(client.http, client.safety, objectUrl, writeUrl, spliced, transport, cachedFeatures?.abapRelease);
+            invalidateWrittenObject(type, name);
+            const whereLabel = include ? ` (include: ${include})` : '';
+            return textResult(`Successfully updated DEFINITION of ${type} ${name}${whereLabel}. Active version unchanged until activation; read with SAPRead(version="inactive") to verify, then SAPActivate.`);
+        }
+        case 'edit_method_signature': {
+            if (type !== 'CLAS')
+                return errorResult('edit_method_signature is only supported for type=CLAS.');
+            const methodSpecifier = String(args.method ?? '').trim();
+            if (!methodSpecifier) {
+                return errorResult('"method" (the method NAME to re-sign) is required for edit_method_signature.');
+            }
+            if (!hasSource) {
+                return errorResult('"source" (the new METHODS clause) is required for edit_method_signature.');
+            }
+            // MAIN-only action: include= is rejected at the schema layer (this action is
+            // not in SAPWRITE_INCLUDE_AWARE_ACTIONS). Defensive guard for direct CLI calls
+            // that bypass Zod.
+            if (includeProvided) {
+                return errorResult('edit_method_signature targets the global class DEFINITION (/source/main). For local-class (CCDEF) signatures, use edit_class_definition with include=definitions.');
+            }
+            await enforcePackageForExistingObject();
+            const { structure, main } = await fetchClassStructureAndMain(name);
+            const upperName = methodSpecifier.toUpperCase();
+            const method = structure.methods.find((m) => m.name === upperName);
+            if (!method) {
+                const available = structure.methods.map((m) => m.name).join(', ');
+                const hint = methodSpecifier.includes('~')
+                    ? ' Interface-qualified names (e.g. "zif_x~m") are not addressable here — objectstructure lists the implementing method under its bare name; for interface/local-handler bodies use edit_method.'
+                    : '';
+                return errorResult(`Method "${methodSpecifier}" not found in CLAS ${name}. Available methods: ${available || '(none)'}.${hint}`);
+            }
+            const spliced = spliceMethodSignature(main, method, source);
+            // No pre-write lint: edit_method_signature changes ONLY the declaration; the
+            // method body still references the old signature until the caller follows up
+            // with edit_method. Linting the spliced full source here would flag legitimate
+            // in-progress renames (e.g. "param `name` not declared"). SAP activation is the
+            // authoritative check — same rationale as the include= lint skip on edit_method.
+            await safeUpdateSource(client.http, client.safety, objectUrl, srcUrl, spliced, transport, cachedFeatures?.abapRelease);
+            invalidateWrittenObject(type, name);
+            return textResult(`Successfully updated signature of method "${method.name}" in ${type} ${name}. Active version unchanged until activation; if the body still references the old signature, follow up with edit_method, then SAPActivate.`);
+        }
+        case 'add_method': {
+            if (type !== 'CLAS')
+                return errorResult('add_method is only supported for type=CLAS.');
+            const clause = String(args.method ?? '');
+            if (!clause.trim()) {
+                return errorResult('"method" (the full METHODS clause, e.g. "METHODS greet IMPORTING who TYPE string.") is required for add_method.');
+            }
+            const methodName = extractMethodNameFromClause(clause);
+            if (!methodName) {
+                return errorResult('Could not extract method name from the METHODS clause. Provide a clause starting with "METHODS <name>" or "CLASS-METHODS <name>".');
+            }
+            // Interface-qualified names (lhc_x~y, zif_x~m) can't be added to a global
+            // class's DEFINITION/IMPLEMENTATION — `~` is interface-method scope and would
+            // produce invalid ABAP in the METHOD stub. Reject with a clear pointer.
+            if (methodName.includes('~')) {
+                return errorResult(`add_method cannot add the interface-qualified method "${methodName}" to a global class. Implement the interface via "INTERFACES <name>." in the DEFINITION (use edit_class_definition), then provide the body with edit_method.`);
+            }
+            const visibility = args.visibility ?? 'public';
+            const isAbstract = args.abstract === true;
+            // MAIN-only action: include= is rejected at the schema layer (not in
+            // SAPWRITE_INCLUDE_AWARE_ACTIONS). Defensive guard for direct CLI calls.
+            if (includeProvided) {
+                return errorResult('add_method targets the global class DEFINITION (/source/main). For local-class (CCDEF) method additions, use edit_class_definition with include=definitions.');
+            }
+            await enforcePackageForExistingObject();
+            const { structure, main } = await fetchClassStructureAndMain(name);
+            // Refuse if method already exists (would silently duplicate).
+            if (structure.methods.some((m) => m.name === methodName)) {
+                return errorResult(`Method "${methodName}" already exists in CLAS ${name}. Use SAPWrite(action="edit_method_signature", method="${methodName}", source="<new METHODS clause>") to change its signature.`);
+            }
+            // A concrete (non-abstract) method needs an IMPLEMENTATION block to receive
+            // its METHOD…ENDMETHOD stub. A purely-abstract class has no IMPLEMENTATION
+            // half, so inserting a concrete declaration there would leave it unimplemented.
+            if (!isAbstract && !structure.classImplementationBlock) {
+                return errorResult(`CLAS ${name} has no IMPLEMENTATION block (purely abstract class). Pass abstract=true to add an abstract method, or add the IMPLEMENTATION half first via edit_class_definition.`);
+            }
+            // Refuse with hint if the target visibility section header is missing.
+            const anchor = findSectionAnchor(main, structure, visibility);
+            if (!anchor) {
+                return errorResult(`No ${visibility.toUpperCase()} SECTION exists in CLAS ${name}. Use SAPWrite(action="edit_class_definition") to add the section header first, then re-run add_method.`);
+            }
+            const spliced = insertMethodPair(main, structure, {
+                decl: clause,
+                visibility,
+                methodName,
+                isAbstract,
+            });
+            const lintWarnings = runPreWriteLint(spliced, type, name, config, lintOverride);
+            if (lintWarnings.blocked)
+                return lintWarnings.result;
+            await safeUpdateSource(client.http, client.safety, objectUrl, srcUrl, spliced, transport, cachedFeatures?.abapRelease);
+            invalidateWrittenObject(type, name);
+            const stubNote = isAbstract ? ' (abstract — no IMPL stub inserted)' : '';
+            return textResult(`Successfully added method "${methodName}" (${visibility}) to ${type} ${name}${stubNote}. Active version unchanged until activation; SAPActivate next.`);
+        }
+        case 'delete_method': {
+            if (type !== 'CLAS')
+                return errorResult('delete_method is only supported for type=CLAS.');
+            const methodSpecifier = String(args.method ?? '').trim();
+            if (!methodSpecifier) {
+                return errorResult('"method" (the method NAME to delete) is required for delete_method.');
+            }
+            // MAIN-only action: include= is rejected at the schema layer (not in
+            // SAPWRITE_INCLUDE_AWARE_ACTIONS). Defensive guard for direct CLI calls.
+            if (includeProvided) {
+                return errorResult('delete_method targets the global class DEFINITION (/source/main). For local-class (CCDEF/CCIMP) method removal, use edit_class_definition with include=...');
+            }
+            await enforcePackageForExistingObject();
+            const { structure, main } = await fetchClassStructureAndMain(name);
+            const upperName = methodSpecifier.toUpperCase();
+            const method = structure.methods.find((m) => m.name === upperName);
+            if (!method) {
+                const available = structure.methods.map((m) => m.name).join(', ');
+                const hint = methodSpecifier.includes('~')
+                    ? ' Interface-qualified names (e.g. "zif_x~m") are not addressable here; objectstructure lists methods under their bare names.'
+                    : '';
+                return errorResult(`Method "${methodSpecifier}" not found in CLAS ${name}. Available methods: ${available || '(none)'}.${hint}`);
+            }
+            const spliced = removeMethodPair(main, method);
+            const lintWarnings = runPreWriteLint(spliced, type, name, config, lintOverride);
+            if (lintWarnings.blocked)
+                return lintWarnings.result;
+            await safeUpdateSource(client.http, client.safety, objectUrl, srcUrl, spliced, transport, cachedFeatures?.abapRelease);
+            invalidateWrittenObject(type, name);
+            const where = method.implementation ? ' (DEFINITION + IMPLEMENTATION)' : ' (DEFINITION only — was ABSTRACT)';
+            return textResult(`Successfully deleted method "${method.name}" from ${type} ${name}${where}. Active version unchanged until activation; SAPActivate next.`);
+        }
+        case 'change_method_visibility': {
+            // Body-preserving visibility move (issue #303 follow-up). Moves the METHODS
+            // clause from its current section to the target section; the IMPLEMENTATION
+            // block is never touched, so the method body survives. This is the safe
+            // alternative to delete_method + add_method (which discards the body).
+            if (type !== 'CLAS')
+                return errorResult('change_method_visibility is only supported for type=CLAS.');
+            const methodSpecifier = String(args.method ?? '').trim();
+            if (!methodSpecifier) {
+                return errorResult('"method" (the method NAME to move) is required for change_method_visibility.');
+            }
+            const target = args.visibility;
+            if (!target) {
+                return errorResult('"visibility" (target section: public, protected, or private) is required for change_method_visibility.');
+            }
+            // MAIN-only action: include= is rejected at the schema layer (not in
+            // SAPWRITE_INCLUDE_AWARE_ACTIONS). Defensive guard for direct CLI calls.
+            if (includeProvided) {
+                return errorResult('change_method_visibility targets the global class DEFINITION (/source/main). For local-class (CCDEF) methods, use edit_class_definition with include=definitions.');
+            }
+            await enforcePackageForExistingObject();
+            const { structure, main } = await fetchClassStructureAndMain(name);
+            const upperName = methodSpecifier.toUpperCase();
+            const method = structure.methods.find((m) => m.name === upperName);
+            if (!method) {
+                const available = structure.methods.map((m) => m.name).join(', ');
+                const hint = methodSpecifier.includes('~')
+                    ? ' Interface-qualified names (e.g. "zif_x~m") are not addressable here; objectstructure lists methods under their bare names.'
+                    : '';
+                return errorResult(`Method "${methodSpecifier}" not found in CLAS ${name}. Available methods: ${available || '(none)'}.${hint}`);
+            }
+            // Idempotent: already in the requested section → no write.
+            if (method.visibility === target) {
+                return textResult(`Method "${method.name}" is already in the ${target.toUpperCase()} SECTION of ${type} ${name}. No change made.`);
+            }
+            // The target section header must already exist (same constraint as add_method).
+            const anchor = findSectionAnchor(main, structure, target);
+            if (!anchor) {
+                return errorResult(`No ${target.toUpperCase()} SECTION exists in CLAS ${name}. Use SAPWrite(action="edit_class_definition") to add the section header first, then re-run change_method_visibility.`);
+            }
+            // DEFINITION-only move — IMPLEMENTATION (the method body) is preserved verbatim.
+            const spliced = moveMethodDefinition(main, method, anchor.afterLine);
+            const lintWarnings = runPreWriteLint(spliced, type, name, config, lintOverride);
+            if (lintWarnings.blocked)
+                return lintWarnings.result;
+            await safeUpdateSource(client.http, client.safety, objectUrl, srcUrl, spliced, transport, cachedFeatures?.abapRelease);
+            invalidateWrittenObject(type, name);
+            return textResult(`Successfully moved method "${method.name}" from ${method.visibility.toUpperCase()} to ${target.toUpperCase()} SECTION of ${type} ${name} (IMPLEMENTATION preserved). Active version unchanged until activation; SAPActivate next.`);
+        }
         case 'scaffold_rap_handlers': {
             // What this action does:
             //   Given a behavior-pool class (ZBP_*) and its interface BDEF, inspect
@@ -3745,8 +4124,13 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                 return { obj, type: objType, name: objName, packageName: objPackage, explicitTransport };
             });
             // Check every target package before starting any creates.
-            for (const pkg of new Set(batchPlan.map((item) => item.packageName))) {
-                checkPackage(client.safety, pkg);
+            // Resolver is shared across the loop so subtree BFS happens once even when
+            // many objects target descendants of the same `ZFOO/**` root.
+            {
+                const resolver = client.getPackageHierarchyResolver();
+                for (const pkg of new Set(batchPlan.map((item) => item.packageName))) {
+                    await checkPackage(client.safety, pkg, resolver);
+                }
             }
             // Pre-flight transport check for batch_create (same logic as single create),
             // but keyed by each effective package because objects can override package.
@@ -4020,11 +4404,11 @@ async function handleSAPWrite(client, args, config, cachingLayer) {
                     const batchStatuses = buildBatchActivationStatuses(writtenObjects, activationOutcome);
                     const statusDetails = formatBatchActivationStatuses(batchStatuses);
                     terminalActivationFailure = statusDetails;
-                    const statusByName = new Map(batchStatuses.map((s) => [`${s.type}${s.name}`, s]));
+                    const statusByName = new Map(batchStatuses.map((s) => [`${s.type}\x00${s.name}`, s]));
                     for (const result of results) {
                         if (result.status !== 'success')
                             continue;
-                        const key = `${result.type}${result.name}`;
+                        const key = `${result.type}\x00${result.name}`;
                         const matched = statusByName.get(key);
                         if (!matched)
                             continue;
@@ -5064,7 +5448,7 @@ async function handleSAPGit(client, args, _authInfo) {
                     password,
                     token,
                 };
-                result = await gctsCloneRepo(client.http, client.safety, params);
+                result = await gctsCloneRepo(client.http, client.safety, params, client.getPackageHierarchyResolver());
             }
             else {
                 if (!packageName)
@@ -5076,7 +5460,7 @@ async function handleSAPGit(client, args, _authInfo) {
                     transportRequest: String(args.transport ?? '').trim() || undefined,
                     user,
                     password,
-                });
+                }, client.getPackageHierarchyResolver());
             }
             break;
         case 'pull':
@@ -5134,7 +5518,7 @@ async function handleSAPGit(client, args, _authInfo) {
                 result = await gctsCreateBranch(client.http, client.safety, repoId, {
                     branch,
                     ...(packageName ? { package: packageName } : {}),
-                });
+                }, client.getPackageHierarchyResolver());
             }
             else {
                 await abapGitCreateBranch(client.http, client.safety, repoId, branch);
@@ -5635,10 +6019,19 @@ async function handleSAPManage(client, config, args, cachingLayer, isPerUserClie
             if (!description)
                 return errorResult('"description" is required for create_package action.');
             checkOperation(client.safety, OperationType.Create, 'CreatePackage');
-            // Package allowlist is enforced on the parent package, not the new package name.
-            // This enables creating children in allowed parents like $TMP.
+            // Package allowlist gate:
+            // - When `superPackage` is set, gate the parent. This enables creating
+            //   children in allowed parents like $TMP. With subtree (`X/**`) rules,
+            //   the new child will automatically be inside its parent's subtree.
+            // - When `superPackage` is omitted, the new package is created at the
+            //   root and IS the gateable name itself — otherwise an admin's
+            //   allowedPackages restriction would be bypassed by simply omitting
+            //   the parent. Gate the new name in that case.
             if (superPackage) {
-                checkPackage(client.safety, superPackage);
+                await checkPackage(client.safety, superPackage, client.getPackageHierarchyResolver());
+            }
+            else {
+                await checkPackage(client.safety, name, client.getPackageHierarchyResolver());
             }
             let effectiveTransport = transport || undefined;
             const packageUrl = `/sap/bc/adt/packages/${encodeURIComponent(name)}`;
@@ -5681,6 +6074,9 @@ async function handleSAPManage(client, config, args, cachingLayer, isPerUserClie
                 packageType,
             });
             await createObject(client.http, client.safety, '/sap/bc/adt/packages', xml, 'application/*', effectiveTransport, undefined, cachedFeatures?.abapRelease);
+            // Hierarchy changed: invalidate any cached subtree that could contain
+            // the new package. Conservative: clear all (cheap; per-call cost is one BFS).
+            client.invalidatePackageHierarchy();
             return textResult(`Created package ${name}.`);
         }
         case 'delete_package': {
@@ -5689,6 +6085,9 @@ async function handleSAPManage(client, config, args, cachingLayer, isPerUserClie
             if (!name)
                 return errorResult('"name" is required for delete_package action.');
             checkOperation(client.safety, OperationType.Delete, 'DeletePackage');
+            // Gate by allowedPackages: deletion targets the package itself, so the
+            // package name must be in the allowed set (or in an allowed subtree).
+            await checkPackage(client.safety, name, client.getPackageHierarchyResolver());
             const packageUrl = `/sap/bc/adt/packages/${encodeURIComponent(name)}`;
             await client.http.withStatefulSession(async (session) => {
                 const lock = await lockObject(session, client.safety, packageUrl, 'MODIFY', cachedFeatures?.abapRelease);
@@ -5705,6 +6104,8 @@ async function handleSAPManage(client, config, args, cachingLayer, isPerUserClie
                     }
                 }
             });
+            // Hierarchy changed: invalidate cached subtrees.
+            client.invalidatePackageHierarchy();
             return textResult(`Deleted package ${name}.`);
         }
         case 'change_package': {
@@ -5723,8 +6124,11 @@ async function handleSAPManage(client, config, args, cachingLayer, isPerUserClie
             if (!newPackage)
                 return errorResult('"newPackage" is required for change_package action.');
             checkOperation(client.safety, OperationType.Update, 'ChangePackage');
-            checkPackage(client.safety, oldPackage);
-            checkPackage(client.safety, newPackage);
+            {
+                const resolver = client.getPackageHierarchyResolver();
+                await checkPackage(client.safety, oldPackage, resolver);
+                await checkPackage(client.safety, newPackage, resolver);
+            }
             // Resolve object URI via search if not provided
             if (!objectUri) {
                 const searchResp = await client.http.get(`/sap/bc/adt/repository/informationsystem/search?operation=quickSearch&query=${encodeURIComponent(objectName)}&maxResults=10`);
@@ -5770,6 +6174,8 @@ async function handleSAPManage(client, config, args, cachingLayer, isPerUserClie
                 newPackage,
                 transport: effectiveTransport,
             });
+            // Hierarchy may have shifted (object moved between packages); invalidate cache.
+            client.invalidatePackageHierarchy();
             const transportNote = result.transport ? ` (transport: ${result.transport})` : '';
             return textResult(`Moved ${objectName} from package ${oldPackage} to ${newPackage}${transportNote}.`);
         }