motoko-mops-package-maintenance

Mops パッケージのメンテナンス

概要

MOPS で公開されている Motoko パッケージを、AI エージェントが完全にメンテナンスするためのステップバイステップの手順です。依存関係のアップグレード、パッケージの検証、ドキュメントの改善、コードのフォーマット、CI の確認、バージョン付きリリースブランチの準備を、すべて一度の自動処理で行います。

使用する場面

• 定期的な依存関係更新のメンテナンス実行時。
• 新しいリリースを作成する前。
• ユーザーから「依存関係を更新して」「パッケージをメンテナンスして」「リリースを準備して」と依頼されたとき。

主な規約（全手順で適用）

以下の規則は各手順から参照されています。一度目を通してください。

• ベンチマークのランタイムは pocket-ic のみです。moc と同様にバージョンを固定してください。 mops CLI v3.0.0 では dfx-replica のサポートが完全に削除されました（mops test／mops bench の --replica フラグもなくなりました）。パッケージにベンチマークまたはレプリカテストがある場合、あるいは --check-deploy を使用する場合は、[toolchain] pocket-ic を必ず固定しないと mops bench が失敗します。files フィールドとは異なり、これは自動で扱われません。設定がない場合は、mops toolchain use pocket-ic <version> を使って追加してください（mops 自身のエラーに具体的なバージョンが示されます。例：15.0.0）。[toolchain] moc を積極的に管理するのと同様です。
• ベンチマークでは最適化済み Wasm を計測してください。[optimize] を設定し、wasm-opt のバージョンを固定してください。 mops bench（および mops build）は、mops.toml に [optimize] セクションがある場合にのみ Binaryen の wasm-opt を実行します。空の [optimize] でも有効になり、デフォルトで level = "O3"／keep-names = true が適用されます。これがないと最適化は一切実行されず、ベンチマークの数値は本番のカナスタークで実際に出荷されるものではなく、生のコンパイラー出力を反映します。pocket-ic と同様に、[optimize] を使うには [toolchain] wasm-opt の明示的なバージョン固定が必要です。設定しないと、コンパイル前にビルドが失敗します。**パッケージにベンチマークがあり、[optimize] がない場合は、**メンテナンス中に両方を追加してください（手順 5 を参照）。ユーザーが気づくまで放置しないでください。
• mops.toml で自動編集しないフィールド： [package] files は自動編集せず、[toolchain] に項目を自動追加しないでください。代わりに報告して警告してください。例外：[toolchain] pocket-ic と [optimize]／[toolchain] wasm-opt。上記 2 つの箇条書きを参照してください。ベンチマークで必要な場合は、moc と同様に追加してください。
• CHANGELOG には利用者に見える変更のみを記載します。 [dependencies] と [requirements] が対象です。[toolchain] や [dev-dependencies] は記載しないでください。
• ドキュメントの基準： MOPS が Documentation = 100% と報告した場合（手順 1）、手順 7 と 8 は完全にスキップしてください。それ以外の場合は 100% を目指し、最低限、公開宣言にある未記入の /// ドキュメント文字列をすべて補完してください。
• CI では moc --check を実行しないでください。 これはメンテナンス中にエージェントが実行するローカル限定のチェックです。CI で異なるコンパイラーバージョンを使うと、利用者に対する誤った失敗の原因になる可能性があります。
• mops add は mops.toml を書き換え、[requirements] moc を "1.0.0" に黙ってリセットする場合があります。 mops add を実行するたびに差分を確認し、意図した値に戻してください。

前提条件

• mops CLI（npm i -g ic-mops）
• moc（Motoko コンパイラー。mops.toml の [toolchain] moc でバージョンを固定し、mops toolchain bin moc で取得します。mops CLI v3.0.0 以降、dfx に同梱されたフォールバックはなく、バージョン固定が必須です）
• pocket-ic（ベンチマークのランタイム。パッケージにベンチマークがある場合は、[toolchain] pocket-ic でバージョンを固定します。主な規約を参照）
• wasm-opt（Binaryen。mops.toml で [optimize] を設定した場合にのみ実行され、その場合に限り [toolchain] wasm-opt のバージョン固定が必要です。主な規約を参照）
• dfx（DFINITY SDK。任意。カナスタークまたはサンプルのビルドにのみ必要で、mops bench には不要です）
• node >= 22／npm。node --version で確認してください。
• git
• prettier と prettier-plugin-motoko。prettier の実行前にローカルにインストールしてください。クリーンなチェックアウトでは、npx -y だけではプラグインは自動解決されません。

ワークフロー

各手順を順番どおりに進めてください。手順が失敗した場合は、次に進む前に修正してください。

ステップ 0 — メンテナンスブランチを作成する

git checkout -b chore/dependency-bump-$(date +%Y-%m-%d)

また、ステップ 11 でスクラッチファイルと自分が追加したファイルを区別できるように、未追跡ファイルの一覧も今のうちに保存しておきます。

git status --short > /tmp/baseline.txt

ステップ 1 — MOPS でパッケージの品質を確認する

1. mops.toml を開きます。[package] セクションがない場合（[canister] のみ、またはどちらもない場合）、公開済みパッケージではありません。ステップ 2 に進んでください。
2. それ以外の場合は、https://mops.one/<package-name> にアクセスし、Package Quality セクション（ドキュメント、ライセンス、リポジトリ、テスト、ベンチマーク）を確認します。
   • mops.one は SPA です。curl／WebFetch では空のシェルしか表示されません。ページをレンダリングできない場合は、ローカルでシグナルを確認します。mo-doc を実行して (no description) を検索し、mops.toml の [package] license と [package] repository を確認し、mops test と mops bench が成功することを確認します。プログラムで確認できない項目は、ユーザーに確認してください。
3. 指標が 「yes」／「100%」 でない場合は、次のように対応します。
   • ドキュメントが 100% 未満の場合：ステップ 7～8 で motoko-doc-strings スキルを実行します。すでに 100% の場合は、ステップ 7～8 をスキップします。
   • ライセンス／リポジトリが未設定の場合：mops.toml の [package] に設定します。
   • テスト／ベンチマーク：ステップ 4～5 で対応し、ステップ 9c で CI を確実に設定します。
4. 自動修正できない項目があれば、ユーザーに警告します。

ステップ 2 — 古い依存関係を調べる

mops outdated
# Fallback: mops search <package-name>

アップグレードが必要なパッケージを記録します。

moc の方針： [toolchain] moc を最新バージョンにアップグレードします。[requirements] moc は、動作する絶対最小バージョン（ステップ 3 で反復して決定）に設定します。ツールチェーンや依存関係が宣言しているバージョンに、無条件に合わせてはいけません。

ステップ 3 — mops.toml の依存関係をアップグレードする

[dependencies] と [dev-dependencies] にある、古いエントリすべてのバージョンを更新します。

[requirements] moc の決定：

1. 初期バージョン — 通常の [dependencies] が要求する moc の最大バージョンです。core は除外します。
   1. ルートの mops.toml から [dependencies] を一覧にします（core は除外）。
   2. 各依存関係について .mops/<name>@<version>/mops.toml を読み、[requirements] moc を抽出します（ない場合はスキップ）。
   3. 最大値を採用します。現在の [requirements] moc より低い場合は、現在の値を維持します。
2. core を確認する — mops install の後、.mops/core@<version>/mops.toml の [requirements] moc を読みます。
3. 反復検証（core の要件が初期バージョンより高い場合のみ）： 中間にある moc のバージョンをすべて順番にテストする必要があります。飛ばしてはいけません（例：1.0.0 → 1.4.0 の場合、1.1.0、1.2.0、1.3.0…をテストします）。 候補バージョン X ごとに、次の手順を実行します。
   1. [toolchain] moc = "X" に設定します。
   2. mops test を実行します（テストがある場合）。
   3. mops bench を実行します（ベンチマークがある場合）。
   4. サンプルをビルドします（Motoko の canister のみ。アセット／Rust は対象外です）。

      EXAMPLES_DIR=""
      if [ -d "examples" ]; then EXAMPLES_DIR="examples"
      elif [ -d "example" ]; then EXAMPLES_DIR="example"; fi
      if [ -n "$EXAMPLES_DIR" ]; then
        cd "$EXAMPLES_DIR"
        mops install
        if [ -f "icp.yaml" ] && command -v icp >/dev/null; then icp build --all
        elif [ -f "dfx.json" ]; then dfx build; fi
        cd ..
      fi
      

   5. すべて成功したら、[requirements] moc = "X" に設定して終了します。
4. 失敗した場合： core が要求するバージョンでも失敗する場合は、[requirements] moc を初期値に戻し、ユーザーに警告します。
5. 最終同期： [toolchain] moc を最新バージョンに戻します。

次に、インストールします。

mops install

mops install が解決エラーなしで成功し、mops.lock が更新されたことを確認します。ロックファイルを手動で編集してはいけません。

Step 3a — ネストされた mops.toml ファイルを同期する

ネストされたマニフェストをすべて確認します（例、サブキャニスターなど）。

find . -name mops.toml -not -path "./node_modules/*" -not -path "./.mops/*"

ネストされた mops.toml ごとに、次のことを行います。

• サードパーティの [dependencies] のバージョンは、通常、ルートのバージョンに合わせます（例では依存関係を追加できますが、共通の依存関係は一致させます）。
• [toolchain] moc はルートと一致させ、CI の setup-mops アクションで使用するフォークに存在することを確認します。
• 保守対象のパッケージは、相対ローカルパスを使って、実際のパッケージ名で自身を参照する必要があります（例：self-package-name = "../"）。また、利用者が手動で簡単に切り替えられるように、最新の公開バージョンをコメントに記載します。
• 例の .mo ファイル内にある相対パスのソースインポートを置き換えます。 import "../../src/Main" → import "mo:self-package-name/Main" これにより、例をそのままコピー＆ペーストして使えるようになります。

examples/mops.toml の例：

[dependencies]
core = "2.5.0"
self-package-name = "../"
# Replace with:
# self-package-name = "0.0.3"

[toolchain]
moc = "1.6.0"

Step 3b — リポジトリの衛生管理ファイルを監査する

• .gitignore — 存在しない場合は作成し、次の内容が含まれていることを確認します。

  .mops/
  .icp/
  mops.lock        # for libraries only — mops install reminds you
  node_modules/
  package.json
  package-lock.json
  .dfx/
  build/
  skills-lock.json
  .agents
  

  個人用／エディター用のファイル（.idea、.vscode、.claude、.junie、 .copilot、.tmp、*.swp、.DS_Store）は、ここではなく開発者のグローバルな ignore に追加します。
• package-lock.json — 存在しない場合は追加しません。
• package.json — 存在する場合は、その license が mops.toml と一致することを確認します。存在しない場合は追加しません （npm が作成する可能性のあるファイルもコミットしないでください）。
• mops.toml の [package] files — 変更しないでください（「主要な規約」を参照）。 内容をユーザーに伝え、問題がありそうな場合は警告します （例：examples/ が存在するのに一覧にない）。mops publish がサポートするのは .mo、.did、.md、.toml のみです。それ以外の拡張子があれば警告します。

Step 3c — コンパイラーの警告を修正する

fix-compiler-warnings スキルを実行します。コンパイラーが実際に出力した警告／エラーだけに対応し、 「改善」を勝手に作り出さないでください。

Motoko キャニスターのみの警告を取得します（アセット／Rust は無視します）。

# DFX projects:
dfx build --check 2>&1 | tee /tmp/dfx_build_output.txt

# MOPS packages:
find src -type f -name "*.mo" -print0 | xargs -0 -n1 $(mops toolchain bin moc) --check $(mops sources) 2>&1 | tee /tmp/moc_check_output.txt

# ICP-CLI projects:
icp build 2>&1 | tee /tmp/icp_build_output.txt

警告の種類ごとに一つずつ修正し、チェックを再実行します。必要に応じて mops test／mops bench も実行し、リグレッションを検出します。

Step 4 — テストを実行する

mops test

テストが失敗した場合は、依存関係のアップグレードによって API が変更されたかどうかを確認し、 ソースを調整して再実行します。重要な変更（名前変更、シグネチャ変更）があれば、 CHANGELOG に記録します。

ステップ 5 — ベンチマークを実行する

パッケージにベンチマークがある場合（bench/ ディレクトリに *.bench.mo ファイルがある場合）は、mops bench を実行する 前に、ベンチマーク用ツールチェーンが完全に設定されていることを 確認してください。mops CLI v3.0.0 では、以下の両方を明示的に 固定する必要があります。そうしないと、mops bench は失敗します （「主な規約」を参照）。

1. [toolchain] pocket-ic — 設定されていない場合は追加します：

   mops toolchain use pocket-ic <version>   # mops's own error names one, e.g. 15.0.0
   

2. [optimize] + [toolchain] wasm-opt — mops.toml に [optimize] がない場合は、指摘するだけでなく、今すぐ追加して ください。空のセクションで十分です（デフォルトは level = "O3"、 keep-names = true です）：

   [optimize]
   
   [toolchain]
   wasm-opt = "<version>"
   

   バージョンは pocket-ic と同じ方法で固定します：

   mops toolchain use wasm-opt <version>   # or: mops toolchain info wasm-opt
   

   [optimize] がないと、mops bench は最適化されていない Wasm を 通知なく計測します。これは CHANGELOG に記載すべきベンチマークの 数値を表すものではありません。 以前は [optimize] がなかったパッケージに追加した場合は、 CHANGELOG（ステップ 6）にその旨を記載してください。ベンチマーク 数値の変化は、コードの回帰や改善ではなく、計測方法の変更によるものです。

次を実行します：

mops install   # picks up any new [toolchain] pins
mops bench

コンパイルまたは実行に失敗した場合は、ステップ 4 と同様に修正します。

環境に起因する失敗とコードの失敗。 mops bench が Deploying canisters... の行より後にエラーになる場合、典型的な例は次のとおりです：

• TrustError: Certificate verification error: "Invalid signature"
• UND_ERR_SOCKET / fetch failed
• Could not find the PocketIC binary

この場合、ベンチマークのコンパイルは問題なく完了しています。これは pocket-ic／mops エージェントの互換性の問題であり、バージョン更新が 原因ではありません。次の順に対処してください。古い pocket-ic プロセスを終了します。[toolchain] pocket-ic が固定されていることを 確認し、バイナリを再取得します（mops toolchain bin pocket-ic）。 古い、または見つからないようであれば、mops toolchain use pocket-ic <version> を使って新しいバージョンに固定し直します（「主な規約」を参照してください。 mops CLI v3.0.0 では、以前のバージョンに戻すための dfx-replica フォールバックはありません）。最終手段として、CI から bench ジョブを削除し、ユーザーに知らせてください。この問題の解決のために リリースを遅らせないでください。

重大な回帰は CHANGELOG に記載しますが、ユーザーから求められない限り リリースを止めないでください。

ステップ 6 — CHANGELOG を更新する

CHANGELOG.md を開くか新規作成し、次のバージョン（番号は ステップ 10 で確定）のセクションを先頭に追加します。

次の項目を含めます（「主な規約」を参照し、[dependencies] と [requirements] のみを対象とします）。

• 依存関係の更新 — アップグレードした [dependencies] の各項目を、 更新前 → 更新後の形式で列挙します。
• 破壊的変更／特筆すべき変更 — ソースコードの適応内容。
• バグ修正 — 作業中に見つけて修正したもの。

CHANGELOG がない場合は、新規作成します：

# Changelog

## Unreleased

### Changed

- Updated `core` from `2.0.0` to `2.5.0`.
- Bumped `bench` from `1.0.0` to `2.0.1`.
- Updated `[requirements] moc` from `1.2.0` to `1.3.0` (only if changed).

### Fixed

- Adapted `<function>` to new `<dep>` API (renamed `old` → `new`).

新しいバージョンを上に記載します。既存の CHANGELOG があれば、その スタイルに合わせます。

ステップ 7 — ドキュメント文字列を確認・改善する

MOPS Documentation が 100% の場合はスキップします（「主な規約」を 参照してください）。それ以外の場合は 100% を目指します。

src/ 以下のすべての .mo ファイルを調べ、公開宣言 （type、func、actor、actor class、let、module）を確認します。 各宣言について、次のことを行います。

1. 直前に /// ドキュメント文字列があることを確認します。
2. 初めて使うユーザーの視点で、目的が明確かどうかを確認します。 引数の型、単位、制約が説明されているか。トラップやエラーの動作が 説明されているか。複雑な関数に例があるか。
3. 必要に応じて改善または追加します。

motoko-doc-strings スキルがインストールされている場合は、そのチェックリストに従います。

ステップ 8 — README とその他の Markdown を確認する

MOPS Documentation が 100% の場合はスキップします。

README.md とその他すべての .md ファイルについて、次のことを行います。

1. 事実関係の正確さ（バージョン、API 名、例）を確認します。
2. 古い情報を修正し、明確さ、文法、完全性を改善します。
3. アップグレードした依存関係で新たに追加された API を説明するセクションを追加します。
4. README.md に、たとえば npx -y prettier --plugin prettier-plugin-motoko --write '**/*.{mo,json,md}' のようなフォーマッターコマンドが記載されていることを確認します （「Development」または「Formatting」セクションがなければ追加します）。

ステップ 9 — フォーマット

9a — Prettier の設定

.prettierrc がない場合、または存在していても設定が簡素すぎる場合（たとえば tabWidth のみの場合）は、次を記述します：

{
  "plugins": ["prettier-plugin-motoko"],
  "bracketSpacing": true,
  "printWidth": 80,
  "semi": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "useTabs": false
}

9b — コードをフォーマットする

prettier の --plugin フラグはパッケージを自動解決しません。まずプラグインをローカルにインストールしてください（クリーンなチェックアウトで npx -y prettier --plugin prettier-plugin-motoko ... を実行すると、Cannot find package 'prettier-plugin-motoko' というエラーで失敗します）。

npm install --no-save prettier prettier-plugin-motoko
npx prettier --plugin prettier-plugin-motoko --write '**/*.{mo,json,md}'

9c — CI ワークフローを確認または追加する

motoko-github-ci-workflow スキルがインストールされている場合は、このセクションではなく、その指示に従ってください。

それ以外の場合は、テストとフォーマットを含む .github/workflows/ci.yml を作成または更新してください。パッケージにベンチマークがある場合は、[toolchain] pocket-ic をピン留めし（Key Conventions に従う）、mops bench の前に mops toolchain bin pocket-ic で CI にインストールする必要があります。mops CLI v3.0.0 の時点では、PocketIC が唯一のベンチマーク実行環境です。mops bench は独自の PocketIC インスタンスを起動・停止するため、手動の dfx start --background ステップは追加しないでください。見つけた場合は削除してください。mops.toml に [optimize] セクションがある場合（Key Conventions に従い、ない場合は Step 5 で追加されているはずです）、mops bench の前に mops toolchain bin wasm-opt で wasm-opt も CI にインストールしてください。

name: CI

on:
  push:
    branches: [main, master]
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

jobs:
  test:
    name: Tests and Benchmarks
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: latest
      - uses: caffeinelabs/setup-mops@v1
      - run: mops install
      - run: mops test   # Omit if no tests
      # Benchmarks: pocket-ic is the only bench runtime (mops CLI
      # v3.0.0 removed dfx-replica support). Requires [toolchain]
      # pocket-ic to be pinned in mops.toml. Omit both steps if there
      # are no benchmarks.
      - name: Make sure pocket-ic is installed
        run: mops toolchain bin pocket-ic
      # Only if mops.toml has an [optimize] section (see Key
      # Conventions / Step 5) — otherwise omit this step too.
      - name: Make sure wasm-opt is installed
        run: mops toolchain bin wasm-opt
      - run: mops bench

  fmt:
    name: Formatting Check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: latest
      - name: Prettier Check
        run: |
          npm install prettier prettier-plugin-motoko --no-save
          npx -y prettier --plugin prettier-plugin-motoko --check '**/*.{mo,json,md}'

Key Conventions に従い、CI に moc --check ステップを追加しないでください。

Step 10 — バージョンを更新する

1. ルートの mops.toml でバージョンをインクリメントします。デフォルトはパッチ（1.2.3 → 1.2.4）です。次のいずれかに該当する場合は、マイナーを上げ（パッチをリセット）ます。

   • [requirements] moc を引き上げた（利用側でより新しいコンパイラーが必要になる）。
   • [dependencies] のパッケージがメジャーバージョンを上げ、このパッケージがその型や関数を再エクスポートしている。
   • 利用側が依存する可能性のあるソースのシグネチャや実行時のセマンティクスを変更した。

   0.x.y の場合は、ルールを右に 1 セグメントずらします。

   [package]
   name = "my-package"
   version = "1.2.4"   # was 1.2.3
   

2. CHANGELOG の Unreleased ヘッダーを新しい番号に更新します。 ## 1.2.4。

3. すべてのネストされた mops.toml（Step 3a で扱ったもの）の自己依存関係に関するコメントを、新しいバージョンに更新します。

   self-package-name = "../"
   # Replace with:
   # self-package-name = "1.2.4"
   

Step 11 — コミットしてプッシュする

まず、追跡されていないファイルを監査します。 git status --short の結果を /tmp/baseline.txt（Step 0）と比較してください。作業を始める前から存在していたファイル（*.debug.bench.mo、roxy.txt、場当たり的な実験ファイルなど）は作業用ファイルです。ステージングせずに残すか、.gitignore に追加するか、削除してください。決して考えずに git add -A を実行しないでください。不明な場合はユーザーに確認してください。

変更をステージングします。作業開始時に package.json / package-lock.json が存在せず、npm install によって作成された場合は、コミットしないでください。

git add -u
git add .gitignore CHANGELOG.md .prettierrc .github/workflows/*.yml 2>/dev/null || true
git status
git commit -m "chore: bump dependencies and prepare v<NEW_VERSION>"

ユーザーに次の内容を伝えてください。

Branch: chore/dependency-bump-YYYY-MM-DD
Ready for review. Run `git push -u origin HEAD` to push.

よくある落とし穴

1. 依存関係のメジャーバージョン更新。 MOPS の依存関係がメジャーバージョンを上げた場合（1.x → 2.x）、その CHANGELOG を確認してください。API が変更されている可能性があります。大がかりな移行が必要な場合はユーザーに伝えてください。
2. [requirements] moc の網羅的な検索。 中間のバージョンをすべてテストしてください（Step 3）。決して飛ばさないでください。すべてのチェックに合格する最も低いバージョンを優先してください。core が宣言するバージョンより低くてもかまいません。これにより、利用側との互換性を最大限に高められます。
3. ロックファイルの不整合。 mops.toml を編集した後は、必ず mops install を実行してください。mops.lock を手動で編集しないでください。
4. CHANGELOG の順序。 新しいものを先頭に置いてください。
5. [optimize] を指定しないベンチマーク。 パッケージにベンチマークがあるのに [optimize] セクションがない場合、mops bench は最適化されていない Wasm を気付かれないまま計測します（Key Conventions / Step 5 を参照）。mops bench がそれなしでも「すでに動作する」というだけで追加を省略しないでください。動作することと、実態を反映した計測であることは別です。

動作を確認する

mops install
mops test
mops bench

すべての項目がエラーなしで成功する必要があります。