setup-abap-mirror

ABAP Mirror のセットアップ

SAP パッケージまたはオブジェクトセットのローカルな abapGit 形式のミラーを作成します。読み取り元は常に SAP システムです。ローカルファイルを使うと、IDE でのコンテキスト確認、git diff、毎回 SAP にアクセスしなくても素早く検索することができます。

このスキルは現在、ARC-1 に既存の SAPRead と DEVC のプリミティブを使用します。専用の abapGit エクスポートツールが ARC-1 に追加されたら、このスキルを簡素化できます。どちらの場合も、このスキルが生成するファイル構成が目標の形式です。

スマートなデフォルト設定（黙って適用し、質問しないでください）

設定	デフォルト	理由
ミラールート	./mirror/<SID>/src/<package>/	複数システムでの作業をサポートできるよう、システムごとにまとめます
ファイル名	abapGit の規則	標準的で、将来にも対応できます
サブパッケージを再帰的に処理	はい	abapGit の動作に合わせます
テストクラスを含める	はい	テストはクラスと一緒に管理します
メタデータ XML を含める	現時点ではスキップ	ARC-1 はまだ abapGit 形式の XML を出力しません。ソースのみでも有用で安全です

入力

次のいずれかのスコープを指定します。

• 単一オブジェクト — name + type（例：ZCL_TRAVEL_HANDLER、CLAS）
• オブジェクトリスト — { type, name } のペアの配列
• パッケージ — package 名。パッケージ内のすべてを取得します

任意で指定できます。

• ミラールート（デフォルト：./mirror/<SID>/src/<package>/）
• テストクラスをスキップ（デフォルト：含める）

前提条件

実行前に、system-info.md が存在することを確認してください。存在しない場合：

→ Run the bootstrap-system-context skill first

ミラーのヘッダーは、system-info.md に記載された SID、システムタイプ、リリースを参照します。

ステップ 1：スコープをオブジェクトリストに解決する

1a. パッケージスコープの場合

SAPRead(type="DEVC", name="<PACKAGE>")

type がスラッシュ形式（CLAS/OC、DDLS/DF、PROG/P、DEVC/K など）の [{ type, name, description, uri }, ...] を返します。

DEVC/K エントリ（サブパッケージ）ごとに再帰的に処理します。SAPRead(type="DEVC", name=<sub>) を呼び出し、その内容を追加します。

スラッシュ形式のタイプを ARC-1 の SAPRead 短縮コードに正規化します。

スラッシュ形式	SAPRead タイプ	abapGit 拡張子
CLAS/OC	CLAS	.clas.abap（+ .clas.testclasses.abap）
INTF/OI	INTF	.intf.abap
PROG/P	PROG	.prog.abap
FUGR/F	FUGR	.fugr.abap（インクルードを展開）
FUNC/FF	FUNC	.func.abap
DDLS/DF	DDLS	.ddls.asddls
DCLS/DL	DCLS	.dcls.asdcls
DDLX/EX	DDLX	.ddlx.asddlxs
BDEF/BO	BDEF	.bdef.asbdef
SRVD/SRV	SRVD	.srvd.asrvd
SRVB/SVB	SRVB	.srvb.xml
TABL/DT	TABL	.tabl.xml
STRU/DS	STRU	.stru.xml
DOMA/DD	DOMA	.doma.xml
DTEL/DE	DTEL	.dtel.xml
MSAG/N	MSAG	.msag.xml
ENHO/EO	ENHO	.enho.xml

この表にないタイプはスキップし、ミラールートの skipped.md に記録します。

1b. 単一オブジェクトまたはオブジェクトリストの場合

列挙をスキップし、指定されたリストをそのまま使って続行します。

ステップ 2：各オブジェクトを読み取る

解決済みの { type, name } ごとに：

SAPRead(type="<type>", name="<name>")

クラスの場合は、（スキップするよう指定されていない限り）テストクラスも取得します。

SAPRead(type="CLAS", name="<name>", include="testclasses")

関数グループの場合は、（オンプレミスのみ）インクルードを展開します。

SAPRead(type="FUGR", name="<name>", expand_includes=true)

DDLS、CLAS（構造化形式）、DCLS、DDLX では、ミラーにはプレーンなソース形式で十分です。より詳細な構造化形式は読み取り用であり、保存には使用しません。

オブジェクトごとのエラーは捕捉して処理を続けます。失敗はエラークラス（not-found / forbidden / not-released / connectivity）とともに skipped.md に記録し、次に進みます。

ステップ 3：abapGit のレイアウトでファイルを書き込む

ディレクトリ構成：

mirror/<SID>/
  README.md               ← written in Step 4
  system-info.md          ← copied or symlinked from bootstrap-system-context
  src/
    <package_lower>/
      zcl_foo.clas.abap
      zcl_foo.clas.testclasses.abap
      zif_foo.intf.abap
      z_report.prog.abap
      zi_view.ddls.asddls
      zi_view_dcl.dcls.asdcls
      zc_view.ddlx.asddlxs
      zi_travel.bdef.asbdef
      ztable.tabl.xml
      zdomain.doma.xml
      zdtel.dtel.xml
    <subpackage_lower>/
      ...
  skipped.md              ← per-object errors and unsupported types

ルール：

• ファイル名のオブジェクト名は小文字にします。
• パスの各セグメントのパッケージ名は小文字にします。
• ソースファイルは SAP から取得した内容をそのまま書き込みます。形式を変更してはいけません。
• 既存ファイルは確認を求めずに上書きします（SAP が信頼できる情報源です）。

ステップ 4：mirror//README.md を書き込む

# Mirror: <SID>

_Generated: <ISO timestamp>_ · _Source: ARC-1_

This directory is a **read-only mirror** of selected ABAP objects from **<SID>**. The SAP system is the source of truth — edits here will NOT be pushed back automatically. To deploy local changes, use `SAPWrite` or a dedicated abapGit export/deploy tool.

See [system-info.md](./system-info.md) for system identity and feature availability.

## Scope

- Mode: <single / list / package>
- <If package: **Package**: ZPKG — recursed into N sub-packages>
- <If list: **Objects**: M explicit>
- Objects mirrored: <count by type>
- Objects skipped: see [skipped.md](./skipped.md)

## Layout

- `src/<package>/` — abapGit-style object files
- `skipped.md` — objects that failed to read or aren't supported yet

## Refreshing

Re-run the `setup-abap-mirror` skill with the same scope. Files are overwritten.

ステップ 5：ユーザーに要約する

4～6 行で報告します。

• ミラー対象の SID とスコープ（単一／リスト／パッケージ）
• タイプごとのオブジェクト数（例：5 CLAS, 12 DDLS, 3 BDEF）
• スキップ／失敗した数と skipped.md への参照
• ミラールートのパス

エラー処理

エラー	原因	対処方法
DEVC の読み取りで 404 が返る	パッケージが存在しない	SAPSearch でパッケージ名を確認するようユーザーに依頼します
オブジェクト単位の読み取りに失敗する	認証／未リリース／見つからない	skipped.md に記録し、残りの処理を続けます
サブパッケージの再帰でループする	循環参照（まれ）	既に確認したパッケージ名を追跡し、重複をスキップします
FUGR の expand_includes に失敗する	オンプレミス環境の機能であり、エンドポイントを利用できない	expand_includes=false に切り替え、部分的な結果として記録します
ソース本文が空である	生成されたプロキシ、または非アクティブなオブジェクト	コメントヘッダー付きの空ファイルを作成し、skipped.md に記録します
system-info.md が見つからない	スキルの依存関係	まず bootstrap-system-context を実行してから、再試行します

注意事項

このスキルで行わないこと

• デプロイは行いません — ローカルでの編集内容は反映されません。SAPWrite または将来の abapGit デプロイアクションを使用してください。
• abapGit 形式のメタデータ XML は扱いません — ARC-1 が現在返すのはソーステキストです。XML ベースのオブジェクトメタデータ（TABL 定義、DOMA 固定値、クラス属性）は、abapGit の object.xml 規約ではなく、SAP のネイティブ形式で JSON または XML として出力されます。読み取りや git diff には十分ですが、abapGit による完全なプル・プッシュの往復には不十分です。
• 並行処理は行いません — SAP のワークプロセスの負荷上限を守るため、オブジェクトの読み取りは逐次実行します。

このスキルを使用する場面

• 既存のコードベースに新しいチームメンバーを迎えるとき
• 多数のオブジェクトをローカルで grep する必要がある移行の準備をするとき
• サポートパッケージのアップグレード前にシステムのスナップショットを作成するとき
• 読み取りのたびに MCP ツールを呼び出せない AI アシスタントに、ローカルのコンテキストを渡すとき

このスキルを使用しない場面

• 単発の読み取りを行うとき — SAPRead を直接呼び出してください
• abapGit による完全な往復（ミラーリングとデプロイ）を必要とするとき — ネイティブの abapGit サポートをお待ちください
• SAP の読み取り負荷が懸念される本番システムで使用するとき — 大規模なパッケージのミラーリングでは、数百件のリクエストが発生します

BTP とオンプレミスの違い

• BTP：DEVC の一覧に表示されるオブジェクトタイプは少なくなります（PROG、INCL、FUGR はありません）。上記の正規化テーブルがこの違いに対応しているため、サポートされていないタイプは単に表示されません。
• オンプレミス：すべてのタイプが対象です。テーブルにないレガシータイプは skipped.md に記録され、時間をかけて ARC-1 に追加できます。

将来への対応

このスキルは、既存のプリミティブを使用して、現在 abapGit 互換のレイアウトを生成します。ARC-1 に専用の abapGit エクスポートアクションが追加されると、内部の実装は変わりますが、出力ディレクトリは abapGit 対応ツールで引き続き認識できます。