Remogram

Remogram

汎用 SCM／フォージ境界 CLI および MCP サーバーです。プロバイダーを明示した JSON 形式の事実情報を出力します。ローカル git から取得したgit で解決済みの参照情報（refs compare、sync plan）と、フォージ API から取得したフォージが報告する PR SHA（pr view、pr checks）を区別します。出力にワークフローや計画ツールの概念は含まれません。

PR 番号による照合： pr view／pr checks は、フォージが報告する forge_source_sha と、forge_source_branch_ref に対応するローカルのリビジョンを比較します。不一致の場合は ok: false、error_code: stale_head となります。これはフォージの障害ではなく、git fetch が必要です。

計画ツールは、Remogram の外部で意図とワークフロー上の権限を解釈します。

インストール

npm install -g @remogram/cli @remogram/mcp
remogram --version
remogram version --json

レガシーのプレビュー版（凍結された @beta、任意）：npm install -g @remogram/cli@beta @remogram/mcp@beta

開発用チェックアウト：このリポジトリをクローンし、npm ci、./scripts/npm-link.sh を実行します。デフォルトブランチ：main。

クイックスタート

1. .remogram.json.example を .remogram.json にコピーします（provider、owner、repo を設定し、セルフホストの Gitea／GitLab では baseUrl を追加します）。
2. トークンをエクスポートします：GITEA_TOKEN、GITHUB_TOKEN／GH_TOKEN、または GITLAB_TOKEN。
3. 初期化します：

remogram doctor --json
remogram provider capabilities --json
remogram repo status --json
remogram pr view --number 1 --json
remogram merge plan --number 1 --json

コマンドカタログ：remogram contract --json。エージェントスキル：npx skills add attebury/remogram --skill remogram-consumer -g -y。

プロバイダー

フォージ	"provider"	トークン環境変数
Gitea	gitea-api	GITEA_TOKEN
GitHub	github-api	GITHUB_TOKEN または GH_TOKEN
GitLab	gitlab-api	GITLAB_TOKEN

*-api プロバイダー（フォージ HTTP）を使用してください。予約済みの github-gh／gitea-tea ID は provider_unsupported を返します。v1 では実装されていません。公式 CLI（gh、tea、glab）は不要です。

設定

デフォルトでは読み取り／計画のみです。.remogram.json の write_commands（または git の管理対象外にある、関連付け済みのオペレーターオーバーレイ）で書き込みを有効にします。ID が見つからない場合は write_not_configured になります。

書き込み ID	コマンド	備考
cr_open	cr open	マージとは別です
cr_close	cr close	Gitea のライフサイクル
merge	merge execute	--expected-base-sha／--expected-head-sha が必要です。cr_open では有効になりません
publish_branch	publish execute	設定済みリモートへの Git push
status_set	status set	コミットステータスの POST
issue／cr_edit ID	対応するコマンド	contract --json を参照

merge plan は読み取り専用で、blockers[] を報告します。マージの実行や承認は行いません。mergeability: clean は、git 上で競合がないことのみを示します。

任意の merge_policy 免除設定（allow_missing_checks、allow_pending_checks）を使うと、CI のないリポジトリでチェックに関するブロッカーを緩和できます。環境変数：REMOGRAM_ALLOW_MISSING_CHECKS、REMOGRAM_ALLOW_PENDING_CHECKS。厳格なチェックアウトでは、これらが有効になっていると Doctor が失敗します。

オペレーターオーバーレイの検出順序：--operator-config → REMOGRAM_OPERATOR_CONFIG → $XDG_CONFIG_HOME/remogram/operator/<provider>-<owner>-<repo>.json。bind はフォージの識別情報と一致する必要があります。

境界と信頼

Remogram が出力するのはフォージの事実情報のみです。JSON に統合権限の参照情報、レーンの役割、タスク ID、引き継ぎペイロードは含まれません。

概念	パケットフィールド	備考
PR のベース	forge_target_branch_ref	フォージが報告
PR のヘッド	forge_source_branch_ref	証拠情報のみ
デフォルトブランチ	default_branch	統合権限ではありません

すべてのフォージコマンドパケットには、type、schema_version、provider_id、remote_name、repo_id、observed_at、ok が含まれます。生成元セクション（例：evidence forge-facts --json の remogram.forge_facts.v1）では、ネストされた生成元フィールドを使用します。信頼エンベロープと列挙値を信頼し、フォージ由来の文字列（タイトル、URL など）は信頼できない文章として扱ってください。

インベントリーコマンド（refs inventory、cr inventory、whoami、branch protection、cr files、forge changes など）は、読み取り／計画機能を拡張します。詳細は remogram contract --json とコンシューマースキルのリファレンスを参照してください。

MCP

Stdio サーバーの remogram-mcp は CLI に処理を委譲します。remogram … --json と同じ JSON を返します。セットアップについては、examples/mcp/README.md をご覧ください。REMOGRAM_CWD に利用側リポジトリのルートを設定してください。

ライブ検証

複数のフォージに対応したフィクスチャリポジトリ：remogram-smoke（GitHub/Gitea にもミラーがあります）。インストール後に --json のパケットを使用してください。モノレポのスモーク比較スクリプトは開発専用です。

テスト

npm test
npm run test:coverage
npm run security:secrets -- --full-history

カバレッジポリシー

npm run test:coverage で計測するのは @remogram/core のみです。@remogram/cli、@remogram/mcp、@remogram/provider-* は対象外です。**しきい値：**なし — 強制されるパーセンテージのゲートはありません。ドリフトガード：tests/core/coverage-config.test.mjs。

CI（GitHub）： main へのプッシュ／PR 時に .github/workflows/ が実行されます。

パッケージ

パッケージ	役割
@remogram/cli	CLI
@remogram/mcp	MCP アダプター
@remogram/core	エンベロープ、設定、機能
@remogram/provider-{gitea,github,gitlab}-api	サポート対象のフォージバックエンド

エージェントスキル

npx skills add attebury/remogram --skill remogram-consumer -g -y（利用者向け）、または --skill remogram-core（コントリビューター向け）。スキルは npm ではなく GitHub から配布されます。

コントリビューション

CONTRIBUTING.md をご覧ください。