@cspeach/cli 0.9.0 → 1.1.0

package/dist/tools/transport.js

@@ -17,6 +17,28 @@ import { ERR } from '../errors/codes.js';
 import { presentSafetyConfirmation } from '../repl/safety-confirm.js';
 import { isSafetyConfirmEnabled } from '../repl/safety-mode-state.js';
 import { setCurrentTransport } from '../repl/current-transport.js';
+// ── Session ledger: transports CREATED by sap_transport_create this session ──
+//
+// Orphan-hint support (third junk transport this month, 2026-06-12 — D15/D20
+// pattern: /abap-refactor created a fresh TR while ZTTT_GAME was already
+// locked in S4HK903328, leaving the new TR an empty orphan).
+// resolveWriteTransport (transport-resolution.ts) consults this set: when a
+// write is forced into the owning transport, the session current-transport
+// differs, AND the current one came from a create THIS session, it warns that
+// the created TR may be an empty orphan. Deliberately NOT persisted — a TR
+// created in an earlier session may have collected objects since.
+const createdThisSession = new Set();
+export function markTransportCreatedThisSession(trkorr) {
+    createdThisSession.add(trkorr);
+}
+export function wasTransportCreatedThisSession(trkorr) {
+    return createdThisSession.has(trkorr);
+}
+/** Test hook — the set is a module-scope singleton and would otherwise leak
+ *  across Vitest tests (same pattern as clearCurrentTransport). */
+export function clearTransportsCreatedThisSession() {
+    createdThisSession.clear();
+}
 // ── sap_transport_create ─────────────────────────────────────────────────────
 //
 // Creates a new CTS workbench transport request.
@@ -24,16 +46,43 @@ import { setCurrentTransport } from '../repl/current-transport.js';
 registerTool({
     name: 'sap_transport_create',
     description: 'Create a new CTS transport request (Rule 9 — one dedicated transport per session). '
-        + 'BEFORE calling this tool, you MUST ask the user for the transport description '
-        + 'using `ask_question` — DO NOT generate a marketing-style description yourself. '
-        + 'Use the user\'s exact answer as the `description` argument AND in your '
-        + '`request_approval` reason. Identical strings prevent the approval mismatch '
-        + 'failure mode observed live 2026-05-07. '
+        + 'RESOLVE FIRST: pass for_object_type/for_object_name ONLY for an EXISTING object you '
+        + 'are about to MODIFY/WRITE — the tool then reuses that object owning transport. Do NOT '
+        + 'pass an object you are only READING and not changing (e.g. the legacy source in a '
+        + 'modernization; the NEW objects go to a fresh transport and the read-only source lock '
+        + 'is irrelevant). Creating brand-new objects from scratch? OMIT for_object and a fresh '
+        + 'transport is created. '
+        + 'Flow: resolve → object locked in an open transport? this tool then does NOT '
+        + 'create anything and returns the owning transport — use it → only create when '
+        + 'the object is free. '
+        + 'Ask the user for the transport description using `ask_question` — DO NOT '
+        + 'generate a marketing-style description yourself. When asking, SUGGEST the '
+        + 'Rule 9 session format "ABAPForge <YYYY-MM-DD>: <work summary>" as the default; '
+        + 'the user may override. Use the user\'s exact answer as the `description` '
+        + 'argument AND in your `request_approval` reason (identical strings prevent the '
+        + 'approval mismatch failure mode observed live 2026-05-07). '
         + 'Requires approval_id. Returns the transport number to use in subsequent writes.',
     isMutating: true,
     input_schema: {
         type: 'object',
         properties: {
+            for_object_type: {
+                type: 'string',
+                description: 'ABAP object type (PROG, CLAS, …) of the object motivating this transport. '
+                    + 'Pass it together with for_object_name whenever the transport is for work '
+                    + 'on a known existing object.',
+            },
+            for_object_name: {
+                type: 'string',
+                description: 'Name of the object you are about to WRITE/modify (NOT a read-only source object '
+                    + 'you only read — e.g. the legacy program in a modernization, whose new objects '
+                    + 'go to a fresh transport).',
+            },
+            force: {
+                type: 'boolean',
+                description: 'Set true to create a new transport even though for_object is already '
+                    + 'locked elsewhere (rare — deliberate parallel transport). Default false.',
+            },
             description: {
                 type: 'string',
                 description: 'Transport description AS PROVIDED BY THE USER (ask via ask_question first). '
@@ -60,6 +109,79 @@ registerTool({
         required: ['description', 'approval_id'],
     },
     handler: async (args, ctx) => {
+        // ── Gate 0: owning-transport guard (runs BEFORE the approval gate) ──────
+        //
+        // Ordering decision (2026-06-12, documented on purpose): the E071 lookup
+        // runs BEFORE verifyAndSpendApprovalId. When the motivating object is
+        // already locked, the early `already_locked` return performs NO mutation
+        // (read-only lookup + session current-transport pointer), so no
+        // authorization needs to be — or should be — consumed for it. Concretely:
+        // verifyAndSpendApprovalId only burns a nonce for one-shot ops
+        // (delete/release; 'create' approvals are reusable within TTL), so the
+        // user's approval JWT survives either ordering — but lookup-first means
+        // the model gets the useful answer ("use S4HK903328") even when the
+        // approval is stale/mismatched, instead of an APPROVAL_INVALID round-trip
+        // for a create that should never happen. The approval is verified only on
+        // the path that actually creates.
+        //
+        // Best-effort: a failed lookup must NEVER block the create (VPN flake is
+        // normal here) — same contract as resolveWriteTransport.
+        let guardNote;
+        if (args.for_object_name && !args.force) {
+            try {
+                const owning = await ctx.adt.transportForObject(args.for_object_type ?? '', args.for_object_name);
+                if (owning.transport) {
+                    // Mirror the create success path: the owning TR becomes the session
+                    // current-transport so subsequent writes pick it up via the 3-tier
+                    // fallback. It is NOT marked created-this-session — it wasn't.
+                    setCurrentTransport(owning.transport);
+                    // Ownership-aware guidance (I1): "use it" is only honest advice when
+                    // the connected user owns the lock — SAP rejects a foreign user's
+                    // writes under someone else's request unless the owner adds a task.
+                    const me = (ctx.adt.username ?? '').toUpperCase();
+                    const foreignOwner = owning.owner && owning.owner.toUpperCase() !== me ? owning.owner : undefined;
+                    const note = foreignOwner
+                        ? `${args.for_object_name} is locked in ${owning.transport} (owned by ${foreignOwner}) `
+                            + '— SAP only accepts changes under that request; ask the owner to add you as a '
+                            + 'task user. Do NOT create a new transport either way.'
+                        : `${args.for_object_name} is already locked in ${owning.transport} — use it; `
+                            + 'no new transport created. Set as session current transport for subsequent writes.';
+                    ctx.chunkEmitter?.emit('info', note);
+                    return {
+                        content: JSON.stringify({
+                            created: false,
+                            already_locked: true,
+                            transport: owning.transport,
+                            ...(owning.owner ? { owner: owning.owner } : {}),
+                            note,
+                        }),
+                    };
+                }
+                if (owning.candidates.length > 1) {
+                    // Ambiguous ownership — never pick silently (same stance as
+                    // resolveWriteTransport). The create proceeds, but the model is
+                    // told the candidates so it can surface them to the user.
+                    guardNote =
+                        `${args.for_object_name} pieces are locked in ${owning.candidates.length} open `
+                            + `transports (${owning.candidates.join(', ')}) — writes to those pieces will be `
+                            + 'forced into their owning requests; the new transport may stay empty.';
+                }
+                else if (owning.capped) {
+                    // M1: a capped lookup means the E071 row set was truncated — the
+                    // object COULD be locked in rows we never saw. The create proceeds
+                    // (best-effort contract), but never silently.
+                    guardNote =
+                        'owning-transport pre-check unreliable (row cap) — proceeding to create; '
+                            + 'verify in SE03 if unsure.';
+                }
+                // free → normal create flow.
+            }
+            catch (err) {
+                ctx.chunkEmitter?.emit('info', `owning-transport pre-check failed for ${args.for_object_type ?? ''} `
+                    + `${args.for_object_name} — proceeding with create `
+                    + `(${err instanceof Error ? err.message : String(err)})`);
+            }
+        }
         // ── Gate 1: Approval ────────────────────────────────────────────────────
         const verify = await verifyAndSpendApprovalId(args.approval_id, args.description, 'create');
         if (!verify.ok) {
@@ -84,11 +206,34 @@ registerTool({
             // subsequent write calls pick it up via the 3-tier fallback without the LLM
             // needing to pass it explicitly every time.
             setCurrentTransport(result.transportNumber);
+            // Orphan-hint ledger: resolveWriteTransport warns later if this freshly
+            // created TR ends up bypassed by an owning-transport force.
+            markTransportCreatedThisSession(result.transportNumber);
+            // Legacy-caller nudge: the object-context args are how the create guard
+            // learns what the transport is FOR. Surfaced in the RESULT payload (not
+            // just the human stream) so the model learns the contract.
+            const forObjectHint = args.for_object_name
+                ? undefined
+                : 'Tip: pass for_object_type/for_object_name when the transport is for a known '
+                    + 'existing object — the tool then reuses the owning transport instead of '
+                    + 'creating an empty orphan (or check first via sap_transport_for_object).';
+            // Rule 9 description format (D20: "Magic fix" accepted verbatim) —
+            // non-blocking note when the description doesn't follow the session
+            // format. The transport IS created; the user's wording always wins.
+            const rule9Format = /^ABAPForge \d{4}-\d{2}-\d{2}: .+/;
+            const today = new Date().toISOString().slice(0, 10);
+            const rule9Suggestion = rule9Format.test(args.description)
+                ? undefined
+                : `Description does not follow the Rule 9 session format. Suggested: "ABAPForge ${today}: <work summary>". `
+                    + 'Non-blocking — keep the user\'s wording if they chose it deliberately.';
             return {
                 content: JSON.stringify({
                     created: true,
                     transport_number: result.transportNumber,
                     description: result.description,
+                    ...(rule9Suggestion ? { rule9_suggestion: rule9Suggestion } : {}),
+                    ...(guardNote ? { guard_note: guardNote } : {}),
+                    ...(forObjectHint ? { for_object_hint: forObjectHint } : {}),
                     note: 'Use this transport_number in all subsequent sap_set_source / sap_create_object calls this session.',
                 }),
             };
@@ -102,6 +247,80 @@ registerTool({
         }
     },
 });
+// ── sap_transport_for_object ─────────────────────────────────────────────────
+//
+// Read-only E071/E070 owning-transport lookup (AdtClient.transportForObject).
+// First-class way for skills/models to resolve the transport question BEFORE
+// asking the user anything or creating a request.
+registerTool({
+    name: 'sap_transport_for_object',
+    description: 'Check whether an ABAP object (or any of its LIMU pieces) is already locked '
+        + 'in an OPEN transport request (E071/E070 lookup). Read-only, no approval. '
+        + 'Call this BEFORE asking the user about transports or creating one: '
+        + 'locked → use the returned owning transport; not locked → a new or '
+        + 'existing transport may be used.',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            object_type: {
+                type: 'string',
+                description: 'ABAP object type (PROG, CLAS, TABL, …)',
+            },
+            object_name: {
+                type: 'string',
+                description: 'ABAP object name (e.g. ZTTT_GAME)',
+            },
+        },
+        required: ['object_type', 'object_name'],
+    },
+    handler: async (args, ctx) => {
+        try {
+            const r = await ctx.adt.transportForObject(args.object_type, args.object_name);
+            let note;
+            if (r.transport) {
+                // Ownership-aware guidance (I1) — mirrors the create guard wording.
+                const me = (ctx.adt.username ?? '').toUpperCase();
+                const foreignOwner = r.owner && r.owner.toUpperCase() !== me ? r.owner : undefined;
+                note = foreignOwner
+                    ? `${args.object_name} is locked in ${r.transport} (owned by ${foreignOwner}) — SAP `
+                        + 'only accepts changes under that request; ask the owner to add you as a task '
+                        + 'user. Do NOT create a new transport either way.'
+                    : `${args.object_name} is already locked in ${r.transport} — use this `
+                        + 'transport for writes to it; do NOT create a new one.';
+            }
+            else if (r.capped) {
+                note = 'Lookup hit its row cap — the result is unreliable; ownership could not '
+                    + 'be determined. Treat as unknown (write tools will still auto-resolve).';
+            }
+            else if (r.candidates.length > 1) {
+                note = `${args.object_name} pieces are locked in ${r.candidates.length} open `
+                    + `transports (${r.candidates.join(', ')}) — ambiguous; ask the user which to use.`;
+            }
+            else {
+                note = `${args.object_name} is not locked in any open transport — a new or `
+                    + 'existing transport may be used.';
+            }
+            return {
+                content: JSON.stringify({
+                    object_type: args.object_type,
+                    object_name: args.object_name,
+                    transport: r.transport,
+                    owner: r.owner ?? null,
+                    candidates: r.candidates,
+                    capped: r.capped ?? false,
+                    note,
+                }),
+            };
+        }
+        catch (err) {
+            return {
+                content: JSON.stringify({ error: 'transport_for_object_failed', detail: String(err) }),
+                is_error: true,
+            };
+        }
+    },
+});
 // ── sap_transport_list ───────────────────────────────────────────────────────
 //
 // Lists transport requests, optionally filtered by owner and/or status.

package/dist/tools/write-mode.js

@@ -9,12 +9,16 @@
  */
 export const WRITE_TOOLS = new Set([
     'sap_create_object',
+    'sap_create_domain',
+    'sap_create_data_element',
     'sap_set_source',
+    'sap_set_class_include',
     'sap_update_method',
     'sap_delete_object',
     'sap_activate',
     'sap_message_maintain',
     'sap_service_binding_publish',
+    'sap_service_binding_unpublish',
     'sap_transport_release',
 ]);
 export function isWriteTool(name) {