adt-plugin-gcts-cli — AI Agent Guide

Package purpose

CLI command plugin adding adt gcts ... subcommands for SAP gCTS (git-enabled CTS). This is the command side of gCTS; the serialization side lives in @abapify/adt-plugin-gcts (E06).

Architecture

User runs `adt gcts ...`
   ↓
adt-cli resolves plugin via CliContext.getAdtClient() factory
   ↓
src/lib/commands/gcts.ts — CliCommandPlugin tree (repo/branch/...)
   ↓
client.adt.gcts.{repository,branches,commits,config}.*  (typed contracts)
   ↓
HTTP → /sap/bc/cts_abapvcs/*   (separate REST surface — NOT /sap/bc/adt/*)

What this plugin does NOT do

• ❌ Talk to /sap/bc/adt/ — gCTS has its own /sap/bc/cts_abapvcs/ surface. For ADT transport operations use adt cts tr * instead.
• ❌ Serialize objects to files — that's @abapify/adt-plugin-gcts.
• ❌ Read user credentials / manage sessions — adt-cli handles auth and injects an authenticated client via ctx.getAdtClient().

Key invariants

1. Contracts only — no direct HTTP

All network traffic MUST go through client.adt.gcts.*. Do not call client.fetch('/sap/bc/cts_abapvcs/…') or construct URLs by hand. If an endpoint is missing, add a contract to packages/adt-contracts/src/adt/gcts/ first.

2. JSON-only

gCTS is JSON-native. There are no XSDs. Request/response schemas live in packages/adt-contracts/src/adt/gcts/schema.ts as hand-built Serializable<T> values (same pattern as datapreview/schema.ts).

3. Commands are thin wrappers

Each subcommand:

1. Resolves the client via getGctsClient(ctx).
2. Calls a single contract method (occasionally two — e.g. checkout calls repository.get first to learn the current branch).
3. Prints either JSON (--json) or a human-readable summary.

No business logic lives in the CLI. Multi-step orchestration (e.g. sapcli's clone_with_task polling loop) is deliberately deferred — add a service under client.services.gcts first, then call it from here.

4. Config key casing

sapcli upper-cases config keys (VCS_TARGET_DIR etc.). We keep the user's casing verbatim — gCTS accepts both. If a downstream consumer reports case mismatches, add a .toUpperCase() in configCmd and document it here.

Adding a new subcommand

1. Add / extend the contract in packages/adt-contracts/src/adt/gcts/ (schema + endpoint + contract test). Re-run bunx nx test adt-contracts.
2. Add the subcommand to src/lib/commands/gcts.ts using the existing CliCommandPlugin objects as templates. Keep it under ~60 LOC.
3. Register it in the appropriate group's subcommands array.
4. Add a mock route in packages/adt-fixtures/src/mock-server/routes.ts so the e2e harness can exercise the new command.
5. Extend the parity test (packages/adt-cli/tests/e2e/parity.gcts.test.ts) with at least one case.

Typing the client

CliContext.getAdtClient() returns Promise<unknown>. We declare a narrow GctsClient interface in src/lib/client/gcts-client.ts so the plugin stays self-contained. The shape is copied from client.adt.gcts.* in @abapify/adt-contracts — when contracts change, update this interface first, then the subcommands.

Build / test

bunx nx build adt-plugin-gcts-cli
bunx nx test adt-plugin-gcts-cli      # unit tests (zero network)
# integration lives in adt-cli parity tests:
bunx nx test adt-cli -- parity.gcts

Open questions

• Auth surface. The epic asked whether gCTS requires a different auth (basic vs OAuth) than ADT. Empirically the same AdtClient session (basic auth + CSRF cookie) works for both surfaces on on-premise and BTP-trial systems. Revisit if users report 401s.
• Overlap with adt cts tr. adt cts tr * targets /sap/bc/adt/cts/ (Eclipse ADT transport surface) while adt gcts commit --corrnr <TR> targets /sap/bc/cts_abapvcs/ (gCTS). They are complementary — document in user-facing docs that gcts commit --corrnr only works on systems where gCTS is configured.