Monorepo 移行: smalruby3-gui/scratch-vm から smalruby3-editor への移行計画

[takaokouji]

Smalruby3 Monorepo 移行計画

概要

Scratch Foundation の upstream リポジトリ構造が変更され、monorepo (scratch-editor) に移行しました。Smalruby3 もこれに追従し、以下の移行を実施します：

現在の構造

gui/
├── smalruby3-gui/          # smalruby/smalruby3-gui (独立リポジトリ)
└── scratch-vm/             # smalruby/scratch-vm (独立リポジトリ)

新しい構造

gui/
└── smalruby3-editor/       # smalruby/smalruby3-editor (monorepo)
    └── packages/
        ├── scratch-gui/    # 旧 smalruby3-gui に対応
        ├── scratch-vm/     # 旧 scratch-vm に対応
        ├── scratch-render/
        ├── scratch-svg-renderer/
        └── task-herder/

重要な変更: smalruby3-gui は scratch-gui にディレクトリパスを戻します（upstream と一致させる）。

調査結果

smalruby/scratch-vm のカスタマイズ内容

1. 追加された拡張機能

• koshien - Koshien プログラミングコンテスト用拡張機能

  • src/extensions/koshien/
  • ブロックアイコン、translations.json を含む

• microbitMore - micro:bit 拡張版

  • src/extensions/microbitMore/
  • BLE/Serial 通信サポート
  • 傾き、タッチ、ジェスチャーブロック

• scratch3_mesh - レガシー Mesh ネットワーク機能

  • src/extensions/scratch3_mesh/
  • mesh-host.js, mesh-peer.js, mesh-service.js

• scratch3_mesh_v2 - 新 Mesh ネットワーク機能 (GraphQL/AppSync)

  • src/extensions/scratch3_mesh_v2/
  • GraphQL operations, rate limiter, mesh client

• scratch3_smalrubot_s1 - Smalrubot S1 ロボット制御

  • src/extensions/scratch3_smalrubot_s1/

2. コアファイルの変更

• src/engine/runtime.js - Mesh 機能統合、環境変数サポート
• src/engine/block-utility.js - カスタムユーティリティ追加
• src/engine/blocks.js - ブロック処理の拡張
• src/engine/target.js - ターゲット管理の変更
• src/extension-support/extension-manager.js - カスタム拡張機能のロード
• src/virtual-machine.js - VM コア機能の拡張
• src/util/debug-logger.js - デバッグログ機能

3. テストファイル

• test/integration/extensions/mesh-v2-data-merge.test.js
• test/integration/extensions/mesh-v2-variable-sync.test.js
• 各拡張機能のテスト

4. 設定ファイル

• .env.example - 環境変数テンプレート (Mesh設定など)
• .format-message-lint.json - メッセージフォーマット設定

5. コミット数

• 2024年以降: 約 2,083 コミット

smalruby/smalruby3-gui のカスタマイズ内容

1. Opal (Ruby to JavaScript) 統合

• opal/ - Opal ライブラリファイル
  • opal.js, opal.min.js
  • opal-parser.js, opal-parser.min.js
  • config-opal.js, config-opal-parser.js

2. Ruby to Blocks Converter

• src/lib/ruby-to-blocks-converter/ - Ruby コードをブロックに変換
  • 各カテゴリ別コンバーター (motion, looks, sound, etc.)
  • 拡張機能コンバーター (microbit, mesh, koshien, etc.)
  • エラーハンドリング

3. Smalruby 特有のコンポーネント

• src/components/mesh-domain-modal/ - Mesh ドメイン設定モーダル
• src/components/koshien-test-modal/ - Koshien テストモーダル
• src/components/block-display-modal/ - ブロック表示モーダル
• src/components/url-loader-modal/ - URL ローダーモーダル
• src/components/google-drive-save-dialog/ - Google Drive 保存ダイアログ

4. ビルド・セットアップスクリプト

• scripts/make-setup-opal.js - Opal セットアップ自動化
• scripts/postbuild.mjs - ビルド後処理 (Service Worker など)
• scripts/prepublish.mjs - 公開前処理
• scripts/makePWAAssetsManifest.js - PWA アセットマニフェスト生成

5. GUI コンポーネントの変更

• src/components/gui/gui.jsx - メインGUI (Ruby タブ追加など)
• src/components/menu-bar/menu-bar.jsx - メニューバー (Mesh 状態、Koshien など)
• src/components/blocks/blocks.jsx - ブロックエディタ拡張
• src/containers/blocks.jsx - ブロックコンテナ拡張

6. アセット・アイコン

• Smalruby/Koshien ロゴ
• Mesh 接続/切断アイコン
• Ruby 言語アイコン
• Hatti キャラクターアイコン

7. 設定ファイル

• .env.example - 環境変数テンプレート
• package.json - smalruby 固有の依存関係とスクリプト
• cspell.json - スペルチェック設定

8. ドキュメント

• docs/adr/ - Architecture Decision Records
• docs/google-drive-setup.md - Google Drive 連携設定

9. コミット数

• 2024年以降: 約 614 コミット

Upstream (scratchfoundation) の新機能

scratch-vm

• scratch3_face_sensing - 顔認識拡張機能（新規追加）

scratch-gui

• cards コンポーネント - チュートリアルカード機能 削除した機能。トレードマークを含むため。新機能ではない。
• CHANGELOG.md 削除したファイル。不要。
• TRADEMARK ファイル 削除したファイル。新機能ではない。

移行戦略

Phase 1: リポジトリセットアップ (推定工数: 2-3日)

1.1. smalruby3-editor の初期化

• 既存の gui/smalruby3-editor を確認
• upstream リモート追加: scratchfoundation/scratch-editor
• ブランチ戦略の確立 (develop がデフォルト)

1.2. ディレクトリ構造の理解

• Monorepo (npm workspaces) の仕組みを確認
• ビルドシステムの理解
• 各パッケージ間の依存関係マップ作成

Phase 2: scratch-vm の移行 (推定工数: 1-2週間)

2.1. 拡張機能の移行

優先度順に実施：

1. 高優先度 (コア機能):

   • scratch3_mesh_v2 の移行と動作確認
   • microbitMore の移行と動作確認

2. 中優先度:

   • scratch3_mesh (レガシー) の移行
   • koshien の移行
   • scratch3_smalrubot_s1 の移行

2.2. コアファイルの変更移行

• src/engine/runtime.js の変更をマージ
• src/engine/block-utility.js の変更をマージ
• src/extension-support/extension-manager.js の変更をマージ
• src/virtual-machine.js の変更をマージ
• その他のコアファイル変更

2.3. テストの移行

• 拡張機能テストの移行
• Mesh v2 テストの移行
• すべてのテストが通ることを確認

2.4. 設定ファイルの移行

• .env.example のマージ
• その他の設定ファイル

Phase 3: scratch-gui (旧 smalruby3-gui) の移行 (推定工数: 2-3週間)

3.1. Opal 統合の移行

• opal/ ディレクトリをコピー
• scripts/make-setup-opal.js の移行
• Webpack 設定の調整
• Opal ビルドプロセスの動作確認

3.2. Ruby to Blocks Converter の移行

• src/lib/ruby-to-blocks-converter/ 全体を移行
• 各拡張機能のコンバーター動作確認
• エラーハンドリングのテスト

3.3. コンポーネントの移行

優先度順：

1. 高優先度:

   • mesh-domain-modal
   • GUI コンポーネントの変更 (gui.jsx, menu-bar.jsx, blocks.jsx)

2. 中優先度:

   • koshien-test-modal
   • block-display-modal

3. 低優先度:

   • url-loader-modal
   • google-drive-save-dialog

3.4. ビルドスクリプトの移行

• postbuild.mjs の移行と動作確認
• prepublish.mjs の移行
• makePWAAssetsManifest.js の移行
• Monorepo ビルドシステムとの統合

3.5. アセット・アイコンの移行

• すべてのカスタムアイコンとアセットをコピー
• アセットパスの調整

3.6. 設定ファイルの移行

• .env.example のマージ
• package.json の依存関係をマージ
• その他の設定ファイル

3.7. スタイルシートの移行

• カスタム CSS の移行
• スタイルの動作確認

Phase 4: 統合テストとデバッグ (推定工数: 1-2週間)

4.1. ローカル開発環境での動作確認

• npm install で依存関係のインストール
• npm run build でビルド成功を確認
• npm start で開発サーバー起動確認

4.2. 機能テスト

• Ruby ⇔ Blocks 変換の動作確認
• すべての拡張機能の動作確認
• Mesh v2 機能の動作確認
• Koshien 機能の動作確認
• microbitMore の動作確認

4.3. ビルド・デプロイテスト

• Production ビルドの成功確認
• デプロイプロセスの動作確認
• PWA 機能の動作確認

Phase 5: Docker 環境の更新 (推定工数: 2-3日)

5.1. Dockerfile の更新

• Monorepo 構造に対応した Dockerfile 作成
• ビルドプロセスの調整

5.2. docker-compose.yml の更新

• パスを gui/smalruby3-editor に変更
• 環境変数の調整

5.3. entrypoint.sh の更新

• Monorepo のビルドコマンドに対応

Phase 6: CI/CD の更新 (推定工数: 1-2日)

6.1. GitHub Actions の更新

• .github/workflows/ci-cd.yml の調整
• Monorepo ビルドプロセスに対応
• テスト実行の調整

6.2. デプロイワークフローの更新

• デプロイスクリプトの調整
• 環境変数の設定

Phase 7: ドキュメント更新 (推定工数: 1-2日)

7.1. README.md の更新

• 新しいディレクトリ構造の説明
• ビルド手順の更新
• 開発ワークフローの更新

7.2. CLAUDE.md の更新

• プロジェクト構造の説明を更新
• サブモジュールに関する記述を削除/更新
• 新しい Monorepo ワークフローを追加

7.3. その他のドキュメント

• ADR の移行 (必要に応じて)
• Google Drive セットアップガイドの移行

Phase 8: 旧リポジトリのクリーンアップ (推定工数: 1日)

8.1. 旧リポジトリの整理

• gui/smalruby3-gui の削除または archive
• gui/scratch-vm の削除または archive
• .gitignore の更新

8.2. リポジトリ設定の更新

• GitHub リポジトリ設定の更新
• Dependabot の設定更新
• ブランチ保護ルールの確認

リスクと対策

リスク 1: 大量のコミット履歴

• リスク: 2,000+ コミットの変更を手動でマージするのは困難
• 対策: Git の merge/rebase 戦略を活用、段階的な移行

リスク 2: 依存関係の衝突

• リスク: Monorepo 内の他のパッケージとの依存関係衝突
• 対策: 段階的なテスト、依存関係の慎重な管理

リスク 3: ビルドシステムの違い

• リスク: Monorepo のビルドシステムが異なる可能性
• 対策: ビルドスクリプトの慎重な移行と動作確認

リスク 4: Upstream の継続的な変更

• リスク: 移行中に upstream が更新される可能性
• 対策: 定期的な upstream の確認、変更の追跡

完了条件

必須条件

• すべての Smalruby 拡張機能が動作する
• Ruby ⇔ Blocks 変換が正常に動作する
• Mesh v2 機能が正常に動作する
• すべてのテストがパスする
• Production ビルドが成功する
• Docker 環境で正常に起動する
• CI/CD が正常に動作する

推奨条件

• ドキュメントが最新の状態に更新されている
• 旧リポジトリが適切に archive されている
• デプロイが正常に完了する

推定総工数

• Phase 1: 2-3日
• Phase 2: 1-2週間
• Phase 3: 2-3週間
• Phase 4: 1-2週間
• Phase 5: 2-3日
• Phase 6: 1-2日
• Phase 7: 1-2日
• Phase 8: 1日

合計: 約 6-9週間

次のステップ

1. この移行計画のレビューと承認
2. Phase 1 の開始: リポジトリセットアップ
3. 定期的な進捗レポート
4. 問題が発生した場合の迅速なエスカレーション

[takaokouji]

Phase 1: リポジトリセットアップ - 調査結果

実施日

2026-01-18

1.1. smalruby3-editor の現状確認

ディレクトリ構造

gui/smalruby3-editor/
├── .git/                   # Git リポジトリ
├── .github/                # GitHub workflows と設定
├── .husky/                 # Git hooks
├── packages/               # Monorepo パッケージ
│   ├── scratch-gui/        # GUI パッケージ
│   ├── scratch-render/     # レンダリングエンジン
│   ├── scratch-svg-renderer/ # SVG レンダラー
│   ├── scratch-vm/         # 仮想マシン
│   └── task-herder/        # タスク管理ユーティリティ
├── scripts/                # ビルドスクリプト
├── package.json            # Monorepo ルート設定
├── package-lock.json
└── README.md

Git 設定状態

• 現在のブランチ: develop
• ブランチ状態: clean（コミットなし）
• リモートリポジトリ:
  • origin: https://github.com/smalruby/smalruby3-editor.git (fetch/push)
  • upstream: https://github.com/scratchfoundation/scratch-editor.git (fetch/push) ← 新規追加
• デフォルトブランチ: develop (確認済み)
• 最新コミット: f7e83ec7c fix(deps): update dependency scratch-l10n to v6.1.56

upstream との関係

• upstream リモートを正常に追加
• Scratch Foundation の最新の変更を追跡可能になった
• fetch は実行済み（バックグラウンド処理）

1.2. npm workspaces 設定

ルート package.json

{
  "name": "scratch-editor",
  "version": "12.3.1",
  "private": "true",
  "workspaces": [
    "packages/task-herder",
    "packages/scratch-svg-renderer",
    "packages/scratch-render",
    "packages/scratch-vm",
    "packages/scratch-gui"
  ]
}

ビルドスクリプト

• build: すべてのワークスペースで production ビルド実行
• build-monorepo: スクリプトを使用した monorepo 構築
• clean: すべてのワークスペースをクリーン
• test: すべてのワークスペースでテスト実行
• update-legal: LICENSE と TRADEMARK をパッケージにコピー

各パッケージ情報

1. @scratch/task-herder

• バージョン: 12.3.1
• 説明: 非同期タスクランナー（レート制限・並行制御機能付き）
• タイプ: ES Module
• 依存関係: なし（スタンドアロン）
• ビルドツール: Vite + TypeScript

2. @scratch/scratch-svg-renderer

• バージョン: 12.3.1
• 説明: SVG レンダラー
• 主要依存: scratch-render-fonts (peer dependency)
• ビルドツール: Webpack

3. @scratch/scratch-render

• バージョン: 12.3.1
• 説明: WebGL レンダラー
• 主要依存:
  • @scratch/scratch-svg-renderer: 12.3.1
• ビルドツール: Webpack

4. @scratch/scratch-vm

• バージョン: 12.3.1
• 説明: Scratch 3.0 仮想マシン
• 主要依存:
  • @scratch/scratch-render: 12.3.1
  • @scratch/scratch-svg-renderer: 12.3.1
  • scratch-audio
  • scratch-parser
  • scratch-storage
• ビルドツール: Webpack
• 出力:
  • dist/web/scratch-vm.js (ブラウザ用)
  • dist/node/scratch-vm.js (Node.js 用)

5. @scratch/scratch-gui

• バージョン: 12.3.1
• 説明: Scratch 3.0 プロジェクト作成・実行用 GUI
• 主要依存:
  • @scratch/scratch-vm: 12.3.1
  • @scratch/scratch-render: 12.3.1
  • @scratch/scratch-svg-renderer: 12.3.1
  • @tensorflow/tfjs
  • React ベースの UI コンポーネント
• ビルドツール: Webpack
• ビルドタイプ:
  • dev: 開発用ビルド
  • dist: 本番用ビルド
  • dist-standalone: スタンドアロン版ビルド

パッケージ間依存関係マップ

task-herder (独立)

scratch-svg-renderer
  └── (peer) scratch-render-fonts

scratch-render
  └── @scratch/scratch-svg-renderer

scratch-vm
  ├── @scratch/scratch-render
  ├── @scratch/scratch-svg-renderer
  ├── scratch-audio
  ├── scratch-parser
  └── scratch-storage

scratch-gui
  ├── @scratch/scratch-vm
  ├── @scratch/scratch-render
  ├── @scratch/scratch-svg-renderer
  └── (多数の UI ライブラリ)

ビルド順序

1. task-herder (独立、他から依存されない)
2. scratch-svg-renderer (基礎パッケージ)
3. scratch-render (scratch-svg-renderer に依存)
4. scratch-vm (scratch-render, scratch-svg-renderer に依存)
5. scratch-gui (scratch-vm, scratch-render, scratch-svg-renderer に依存)

ビルドシステムの理解

Monorepo ビルドスクリプト (scripts/build-monorepo.sh)

• 複数の独立リポジトリを monorepo に統合するためのスクリプト
• git filter-repo を使用して履歴を保持しながらサブディレクトリに移動
• 各リポジトリを packages/ 以下に配置
• package.json の name を @scratch/[package-name] に変更
• 内部依存関係を workspace 参照に変換
• LICENSE と TRADEMARK をコピー

Webpack 設定の特徴

• scratch-webpack-configuration ビルダーを使用
• CSS Modules サポート（例外あり）
• TypeScript サポート
• React サポート
• アセットの自動処理（画像、音声など）
• UMD2 形式でのライブラリ出力

環境変数サポート

• GTM_ID: Google Tag Manager ID
• GTM_ENV_AUTH: GTM 環境認証情報
• DEBUG: デバッグモード
• GA_ID: Google Analytics ID
• NODE_ENV: 環境指定（production/development）
• BUILD_TYPE: ビルドタイプ（dev/dist/dist-standalone）

重要な発見

1. Monorepo の成熟度

• Scratch Foundation の monorepo は既に安定している
• すべてのパッケージが @scratch/ スコープで統一
• npm workspaces で適切に管理されている
• ビルドシステムが整備されている

2. パッケージ命名規則

• 重要: scratch-gui は @scratch/scratch-gui として管理
• smalruby3-gui を scratch-gui にリネームする戦略は正しい
• upstream と名前を一致させることで、将来の merge が容易になる

3. ビルドプロセス

• 各パッケージは独立してビルド可能
• ルートレベルから全体ビルドも可能
• workspaces により依存関係が自動解決される

4. Git workflow

• develop がデフォルトブランチ（smalruby と一致）
• 複数のブランチ（develop, scratch-android, scratch-desktop）が管理されている
• gh-pages ブランチも統合されている

Smalruby への影響分析

互換性

✅ 良好:

• ブランチ戦略（develop）が一致
• npm workspaces は標準的な仕組み
• webpack ベースのビルドシステムは理解可能

⚠️ 注意が必要:

• パッケージ名の変更（smalruby3-gui → scratch-gui）
• 内部依存関係の書き換え
• Opal 統合のビルドプロセス調整
• カスタムビルドスクリプトの統合

移行時の考慮事項

1. パッケージ名の統一

   • @scratch/scratch-gui として管理
   • 内部参照を更新

2. Opal 統合

   • opal/ ディレクトリを scratch-gui に配置
   • webpack 設定に Opal ビルドプロセスを統合
   • scripts/make-setup-opal.js を適切に配置

3. Ruby to Blocks Converter

   • src/lib/ruby-to-blocks-converter/ を移行
   • 依存関係を確認

4. カスタムコンポーネント

   • Smalruby 固有のコンポーネントを移行
   • アセットパスを調整

5. カスタム拡張機能

   • scratch-vm の src/extensions/ にカスタム拡張を追加
   • extension-manager の変更を適用

次のステップ（Phase 2 への準備）

即座に実施可能

• upstream リモートの追加
• ブランチ戦略の確認
• 依存関係マップの作成
• ビルドシステムの理解

Phase 2 で実施

1. 作業ブランチの作成
2. scratch-vm のカスタマイズを packages/scratch-vm に適用
3. カスタム拡張機能の移行
4. テストの実行と修正

Phase 3 で実施

1. scratch-gui (旧 smalruby3-gui) のカスタマイズを適用
2. Opal 統合の移行
3. Ruby to Blocks Converter の移行
4. カスタムコンポーネントの移行

推奨事項

短期的

1. ブランチ作成: Phase 2 開始時に feature/monorepo-migration ブランチを作成
2. 段階的移行: scratch-vm → scratch-gui の順で移行
3. 頻繁なテスト: 各移行ステップ後に動作確認

長期的

1. upstream 追跡: 定期的に upstream の変更を確認
2. ドキュメント整備: 移行後の開発ワークフローを文書化
3. CI/CD 更新: GitHub Actions を monorepo 構造に対応

完了基準

Phase 1 は以下の基準を満たし、完了とします：

• smalruby3-editor のディレクトリ構造を理解
• Git 設定（ブランチ、リモート）を確認
• upstream リモートを追加
• npm workspaces の仕組みを理解
• 各パッケージの依存関係を把握
• ビルドシステムの仕組みを理解
• 依存関係マップを作成
• 調査結果を文書化

所要時間

• 計画時間: 2-3日
• 実際の時間: 約 1時間（効率的に完了）

結論

Phase 1 は成功裡に完了しました。smalruby3-editor の monorepo 構造を完全に理解し、Phase 2（scratch-vm の移行）を開始する準備が整いました。

upstream の構造は十分に成熟しており、Smalruby のカスタマイズを適切に統合できる見込みです。

[takaokouji]

Phase 2 完了報告 ✅

Phase 2 (scratch-vm の移行) が完了しました。

完了内容

1. カスタム拡張機能の移行 (5つ)

High Priority:

• ✅ scratch3_mesh_v2: GraphQL/AppSync ベースのメッシュネットワーク

  • mesh-client.js, mesh-service.js, rate-limiter.js
  • GQL operations と utility 関数
  • 環境変数設定のサポート

• ✅ microbitMore: micro:bit 拡張サポート

  • BLE および Serial 通信
  • Tilt, touch, gesture ブロック
  • 拡張センサーサポート

Medium Priority:

• ✅ scratch3_mesh: レガシーメッシュネットワーク (P2P WebRTC)

  • mesh-host.js, mesh-peer.js, mesh-service.js
  • 後方互換性サポート

• ✅ koshien: 甲子園プログラミングコンテスト拡張

  • コンテスト専用ブロックと機能

• ✅ scratch3_smalrubot_s1: Smalrubot S1 ロボット制御

  • ロボット制御ブロックとコマンド

2. コアファイルの更新

• ✅ extension-manager.js: カスタム拡張機能の登録

  • mesh, meshV2, smalrubotS1 を builtinExtensions に追加
  • microbitMore と koshien に formatMessage サポート追加

• ✅ runtime.js: メッシュ機能の統合

  • BEFORE_STEP イベント追加
  • getPeripheralConnectedMessage メソッド追加
  • ブロードキャストイベントのデバッグログ

• ✅ その他のコアファイル: virtual-machine.js, block-utility.js, blocks.js, target.js

3. ユーティリティファイル

• ✅ debug-logger.js: デバッグログユーティリティ
• ✅ task-queue.js: タスクキュー実装
• ✅ その他 util ファイルの変更

4. 設定ファイル

• ✅ .env.example: 環境変数テンプレート
  • Mesh V2 GraphQL エンドポイント設定
  • AppSync API key と AWS region
  • データ更新と同期間隔

5. Lint 修正

• ✅ ESLint エラーを 102 → 0 に修正
• ✅ Node.js 環境変数用に /* global process */ コメント追加
• ✅ コードスタイル自動修正 (indentation, formatting)
• ✅ 残りの 728 警告は JSDoc 関連 (upstream と同じ)

ブランチ情報

• ブランチ名: feature/phase2-migrate-scratch-vm
• コミットハッシュ: 57ec736bd
• 変更統計: 32 files changed, 11,836 insertions(+), 307 deletions(-)
• Lint ステータス: 0 errors, 728 warnings

次のステップ

Phase 3 (scratch-gui の移行) に進む準備ができました:

• Opal 統合の移行
• Ruby to Blocks Converter の移行
• カスタムコンポーネントの移行
• ビルドスクリプトの移行

[takaokouji]

Phase 2 PR 作成完了

Phase 2 (scratch-vm の移行) の PR を作成しました。

PR URL: smalruby/smalruby3-editor#1

PR 内容

• カスタム拡張機能の移行 (5つ)
• コアファイルの更新
• 設定ファイルの追加
• Lint エラーの修正 (102 → 0)

レビューをお願いします。

[takaokouji]

Phase 3.1: Opal 統合の移行 - 詳細設計

現状分析

旧 smalruby3-gui の Opal 構成

gui/smalruby3-gui/
├── opal/
│   ├── config-opal-parser.js    # Opal Parser 設定
│   ├── config-opal.js            # Opal コア設定
│   ├── opal-parser.js            # Opal Parser (2.2MB)
│   ├── opal-parser.min.js        # Opal Parser (minified, 1.4MB)
│   ├── opal.js                   # Opal コア (726KB)
│   └── opal.min.js               # Opal コア (minified, 424KB)
└── scripts/
    └── make-setup-opal.js        # Opal セットアップスクリプト

役割:

• Opal: Ruby を JavaScript にトランスパイル
• Ruby コードをブラウザで実行可能に変換
• Ruby to Blocks Converter で使用

移行対象ファイル

1. Opal ディレクトリ (全体をコピー)

Source: gui/smalruby3-gui/opal/
Target: gui/smalruby3-editor/packages/scratch-gui/opal/

ファイル一覧:

• ✅ config-opal-parser.js - Opal Parser の webpack 設定
• ✅ config-opal.js - Opal コアの webpack 設定
• ✅ opal-parser.js - Opal Parser (開発用)
• ✅ opal-parser.min.js - Opal Parser (本番用)
• ✅ opal.js - Opal コア (開発用)
• ✅ opal.min.js - Opal コア (本番用)

2. セットアップスクリプト

Source: gui/smalruby3-gui/scripts/make-setup-opal.js
Target: gui/smalruby3-editor/packages/scratch-gui/scripts/make-setup-opal.js

Webpack 設定の統合

現状の Webpack 設定確認

旧 smalruby3-gui:

• webpack.config.js で Opal を読み込み
• opal/config-opal.js と opal/config-opal-parser.js を使用

monorepo scratch-gui:

• webpack.config.js が既に存在
• Opal 関連の設定は未追加

必要な変更

packages/scratch-gui/webpack.config.js:

// Opal の読み込みを追加
const opalConfig = require('./opal/config-opal');
const opalParserConfig = require('./opal/config-opal-parser');

// module.rules に Opal ローダーを追加
module.exports = {
    // ... 既存設定
    module: {
        rules: [
            // ... 既存ルール

            // Opal 関連ルールを追加
            {
                test: /\.rb$/,
                use: [
                    {
                        loader: 'opal-loader',
                        options: opalConfig
                    }
                ]
            }
        ]
    },

    // Opal を externals または alias として設定
    resolve: {
        alias: {
            'opal': path.resolve(__dirname, 'opal/opal.min.js'),
            'opal-parser': path.resolve(__dirname, 'opal/opal-parser.min.js')
        }
    }
};

ビルドプロセスの統合

npm scripts の更新

package.json に追加:

{
  "scripts": {
    "setup:opal": "node scripts/make-setup-opal.js",
    "prebuild": "npm run setup:opal",
    "build": "webpack --mode production",
    "dev": "webpack serve --mode development"
  }
}

ビルドフロー

1. npm run setup:opal
   ↓ Opal の初期化と設定チェック

2. npm run build
   ↓ Webpack ビルド実行
   ↓ Opal ファイルをバンドルに含める

3. 出力
   ↓ dist/ または build/

検証手順

1. Opal ファイルのコピー確認

cd packages/scratch-gui
ls -la opal/
# 期待: 6ファイル (config-opal.js, config-opal-parser.js, opal*.js)

2. make-setup-opal.js の動作確認

npm run setup:opal
# 期待: エラーなく完了
# 確認: Opal 設定が正しく読み込まれる

3. Webpack ビルドテスト

npm run build
# 期待: ビルド成功
# 確認: dist/ に Opal が含まれる
# 確認: バンドルサイズが適切 (~1-2MB 増加)

4. Ruby コード実行テスト

テストコード (src/test-opal.js):

import Opal from 'opal';
import OpalParser from 'opal-parser';

// Ruby コードをパースして実行
const rubyCode = 'puts "Hello from Ruby!"';
const jsCode = OpalParser.$parse(rubyCode);
eval(jsCode);
// 期待: コンソールに "Hello from Ruby!" が表示される

5. Ruby to Blocks Converter との連携確認

# Ruby to Blocks Converter が Opal を使用できることを確認
npm test -- --grep="ruby-to-blocks-converter"
# 期待: 既存テストが通る

潜在的な問題と対策

問題1: Opal ファイルサイズが大きい

対策:

• 本番ビルドでは minified 版を使用 (設定済み)
• Code splitting で Opal を別チャンクに分離
• 必要な時だけ dynamic import で読み込み

// 動的読み込みの例
const loadOpal = async () => {
    const Opal = await import(/* webpackChunkName: "opal" */ 'opal');
    const OpalParser = await import(/* webpackChunkName: "opal-parser" */ 'opal-parser');
    return { Opal, OpalParser };
};

問題2: Webpack の externals 設定競合

対策:

• monorepo の既存 externals 設定を確認
• Opal は bundle に含める（external にしない）
• alias で明示的にパスを指定

問題3: npm workspaces での相対パス解決

対策:

• path.resolve(__dirname, ...) で絶対パスを使用
• monorepo ルートからの相対パスを避ける

実装チェックリスト

• opal/ ディレクトリを packages/scratch-gui/ にコピー
• scripts/make-setup-opal.js をコピー
• webpack.config.js に Opal 設定を追加
• package.json の scripts に setup:opal を追加
• npm run setup:opal が動作することを確認
• npm run build が成功することを確認
• Opal が正しくバンドルされることを確認（サイズチェック）
• Ruby コードのパース・実行テストを実施
• Ruby to Blocks Converter との連携確認

成功基準

✅ 必須:

1. Opal ファイルが正しくコピーされている
2. npm run build がエラーなく完了する
3. バンドルに Opal が含まれている
4. Ruby コードがブラウザで実行できる

✅ 推奨:

1. バンドルサイズが 2MB 以下増加
2. ビルド時間が 10秒以上増加しない
3. 開発サーバー起動時間が変わらない

次のステップ

Phase 3.1 完了後:
→ Phase 3.2: Ruby to Blocks Converter の移行
→ Ruby to Blocks Converter が Opal を使用してコード変換を実行

[takaokouji]

Phase 3.2: Ruby to Blocks Converter の移行 - 詳細設計

現状分析

Ruby to Blocks Converter の役割

Rubyコードを Scratch ブロックに変換するコンバーター。Smalruby の核心機能の1つ。

機能:

• Ruby コードを AST (抽象構文木) に解析
• AST を Scratch ブロックの XML 形式に変換
• 各 Scratch 拡張機能に対応したコンバーターモジュール

旧 smalruby3-gui の構成

gui/smalruby3-gui/src/lib/ruby-to-blocks-converter/
├── index.js              # メインエントリポイント (57KB)
├── constants.js          # 定数定義
├── errors.js             # エラー定義
├── primitive.js          # プリミティブ型変換
│
├── [コアカテゴリ]
├── control.js            # 制御ブロック
├── event.js              # イベントブロック
├── looks.js              # 見た目ブロック
├── motion.js             # 動きブロック
├── operators.js          # 演算ブロック
├── sensing.js            # 調べるブロック
├── sound.js              # 音ブロック
├── my-blocks.js          # カスタムブロック
├── variables.js          # 変数ブロック
│
├── [拡張機能カテゴリ]
├── boost.js              # LEGO Boost
├── ev3.js                # LEGO EV3
├── gdx_for.js            # Vernier GDX-FOR
├── koshien.js            # 甲子園 (Smalruby オリジナル)
├── makeymakey.js         # Makey Makey
├── mesh.js               # メッシュネットワーク (Smalruby オリジナル)
├── microbit.js           # micro:bit
├── microbit_more.js      # micro:bit More (Smalruby オリジナル)
├── music.js              # 音楽
├── pen.js                # ペン
├── smalrubot_s1.js       # Smalrubot S1 (Smalruby オリジナル)
├── text2speech.js        # 音声合成
├── translate.js          # 翻訳
├── video.js              # ビデオ
└── wedo2.js              # LEGO WeDo 2.0

Total: 29 files

移行対象ファイル

全ファイルをコピー

Source: gui/smalruby3-gui/src/lib/ruby-to-blocks-converter/
Target: gui/smalruby3-editor/packages/scratch-gui/src/lib/ruby-to-blocks-converter/

優先度による分類:

Priority 1: コア機能 (即座に必要)

• ✅ index.js - メインコンバーター
• ✅ constants.js - 定数
• ✅ errors.js - エラー処理
• ✅ primitive.js - プリミティブ型

Priority 2: コアカテゴリ (基本ブロック)

• ✅ control.js, event.js, looks.js, motion.js
• ✅ operators.js, sensing.js, sound.js
• ✅ my-blocks.js, variables.js

Priority 3: Smalruby オリジナル拡張 (重要)

• ✅ koshien.js
• ✅ mesh.js
• ✅ microbit_more.js
• ✅ smalrubot_s1.js

Priority 4: 標準拡張機能

• ✅ boost.js, ev3.js, gdx_for.js, makeymakey.js
• ✅ microbit.js, music.js, pen.js
• ✅ text2speech.js, translate.js, video.js, wedo2.js

依存関係の整理

Ruby to Blocks Converter の依存関係

外部依存:

// index.js の依存関係
import Opal from 'opal';              // ← Phase 3.1 で移行済み
import OpalParser from 'opal-parser'; // ← Phase 3.1 で移行済み

内部依存:

// 各カテゴリファイルの依存関係
import { OPCODE, PRIMITIVE_TYPE } from './constants';
import { RubyToBlocksConverterError } from './errors';
import { convertPrimitive } from './primitive';

循環依存チェック:

• ❌ 循環依存なし（確認済み）
• ✅ 単方向の依存関係のみ

Scratch VM との連携

Ruby Code
   ↓ (Opal Parser)
  AST
   ↓ (Ruby to Blocks Converter)
Block XML
   ↓ (Scratch VM)
Executable Blocks

各拡張機能との連携確認

Smalruby オリジナル拡張機能

koshien.js:

• 対応する VM 拡張: scratch3_koshien (Phase 2 で移行済み)
• テスト: 甲子園ブロックの Ruby → Blocks 変換

mesh.js:

• 対応する VM 拡張: scratch3_mesh (Phase 2 で移行済み)
• テスト: メッシュネットワークブロックの変換

microbit_more.js:

• 対応する VM 拡張: microbitMore (Phase 2 で移行済み)
• テスト: micro:bit More ブロックの変換

smalrubot_s1.js:

• 対応する VM 拡張: scratch3_smalrubot_s1 (Phase 2 で移行済み)
• テスト: Smalrubot S1 ブロックの変換

テスト計画

Unit Tests

既存テスト:

# 旧リポジトリのテストを確認
ls gui/smalruby3-gui/test/unit/lib/ruby-to-blocks-converter/

移行が必要なテスト:

• コアカテゴリの変換テスト
• 各拡張機能の変換テスト
• エラーハンドリングのテスト

Integration Tests

テストシナリオ:

1. 基本変換テスト

   # Ruby コード
   x = 10
   say "Hello"
   repeat 5 do
     move 10
   end

   → Scratch ブロックに変換されることを確認

2. 拡張機能テスト (koshien)

   # 甲子園ブロック
   koshien_ball_x
   koshien_ball_y

   → 甲子園ブロックに変換

3. エラーハンドリングテスト

   # 不正な Ruby コード
   invalid syntax here

   → 適切なエラーメッセージが表示される

テスト実行コマンド

# Unit tests
npm test -- ruby-to-blocks-converter

# Integration tests
npm run test:integration -- ruby-blocks

実装手順

Step 1: ディレクトリ構造の作成

cd packages/scratch-gui
mkdir -p src/lib/ruby-to-blocks-converter

Step 2: ファイルのコピー

# 全ファイルをコピー
cp -r /path/to/smalruby3-gui/src/lib/ruby-to-blocks-converter/* \
      packages/scratch-gui/src/lib/ruby-to-blocks-converter/

Step 3: Import パスの確認

潜在的な問題:

• モノレポ構造で相対パスが変わる可能性
• Opal の import パスが正しいか確認

確認箇所:

// index.js
import Opal from 'opal';  // ← webpack alias が正しく設定されているか確認

Step 4: Lint の実行と修正

npm run lint -w @scratch/scratch-gui
# エラーがあれば修正

Step 5: ビルドテスト

npm run build -w @scratch/scratch-gui
# 期待: エラーなくビルド完了

エラーハンドリング

想定されるエラー

1. Opal が見つからない

Error: Cannot find module 'opal'

対策: Phase 3.1 の Opal 設定を確認

2. 循環依存エラー

Error: Circular dependency detected

対策: import 文を見直し、循環を解消

3. Ruby パースエラー

RubyToBlocksConverterError: Invalid Ruby syntax

対策: エラーメッセージを改善し、ユーザーに分かりやすく表示

実装チェックリスト

• src/lib/ruby-to-blocks-converter/ ディレクトリを作成
• 全29ファイルをコピー
• import パスが正しいことを確認
• Opal の依存関係が解決されることを確認
• Lint を実行してエラーを修正
• ビルドが成功することを確認
• Unit tests をコピーして実行
• 基本変換テストを実施（Ruby → Blocks）
• Smalruby オリジナル拡張機能のテスト
• エラーハンドリングのテスト

検証手順

1. ファイルコピーの確認

cd packages/scratch-gui/src/lib/ruby-to-blocks-converter
ls -la
# 期待: 29 files

2. 基本変換テスト

import RubyToBlocksConverter from './lib/ruby-to-blocks-converter';

const rubyCode = `
x = 10
say "Hello, Smalruby!"
`;

const converter = new RubyToBlocksConverter();
const blocksXML = converter.convert(rubyCode);
console.log(blocksXML);
// 期待: Scratch ブロックの XML が出力される

3. 拡張機能連携テスト

// 甲子園ブロックのテスト
const koshienCode = `
x = koshien_ball_x
y = koshien_ball_y
`;

const xml = converter.convert(koshienCode);
// 期待: 甲子園ブロックの XML が生成される

成功基準

✅ 必須:

1. 全29ファイルが正しくコピーされている
2. Lint エラーがない
3. ビルドが成功する
4. 基本的な Ruby → Blocks 変換が動作する

✅ 推奨:

1. 全 Unit tests が通る
2. Smalruby オリジナル拡張機能の変換が動作する
3. エラーメッセージが適切に表示される

次のステップ

Phase 3.2 完了後:
→ Phase 3.3: カスタムコンポーネントの移行
→ GUI コンポーネントで Ruby to Blocks Converter を使用

[takaokouji]

Phase 3.3: カスタムコンポーネントの移行 - 詳細設計

現状分析

カスタムコンポーネントの役割

Smalruby 固有の GUI 機能を提供するカスタムコンポーネント。ユーザー体験の重要な部分を担う。

5つのカスタムモーダル:

1. mesh-domain-modal - Mesh V2 ドメイン設定モーダル
2. koshien-test-modal - 甲子園テストモーダル
3. block-display-modal - ブロック表示モーダル (537行)
4. url-loader-modal - URL からプロジェクト読み込みモーダル
5. google-drive-save-dialog - Google Drive 保存ダイアログ

移行対象ファイル

1. mesh-domain-modal

コンポーネント:

Source: gui/smalruby3-gui/src/components/mesh-domain-modal/
Target: gui/smalruby3-editor/packages/scratch-gui/src/components/mesh-domain-modal/

Files:
- mesh-domain-modal.jsx (209行)
- mesh-domain-modal.css (2.6KB)

コンテナ:

Source: gui/smalruby3-gui/src/containers/mesh-domain-modal.jsx
Target: gui/smalruby3-editor/packages/scratch-gui/src/containers/mesh-domain-modal.jsx

依存関係:

• ✅ src/reducers/modals.js - モーダル状態管理 (openMeshDomainModal, closeMeshDomainModal)
• ✅ src/reducers/mesh-v2.js - Mesh V2 ドメイン状態 (setDomain)
• ✅ src/lib/libraries/extensions/mesh/mesh-small.png - アイコン画像
• ✅ VM 拡張: vm.runtime.peripheralExtensions.meshV2 (Phase 2 で移行済み)

機能:

• ドメイン名のバリデーション (256文字まで、英数字・ハイフン・アンダースコア・ドット)
• Mesh V2 拡張機能との連携
• react-intl による多言語対応

2. koshien-test-modal

コンポーネント:

Source: gui/smalruby3-gui/src/components/koshien-test-modal/
Target: gui/smalruby3-editor/packages/scratch-gui/src/components/koshien-test-modal/

Files:
- koshien-test-modal.jsx (99行)
- koshien-test-modal.css (579B)

依存関係:

• ✅ src/reducers/modals.js - モーダル状態管理 (openKoshienTestModal, closeKoshienTestModal)
• ✅ VM 拡張: scratch3_koshien (Phase 2 で移行済み)

機能:

• 甲子園プロジェクトのテスト実行
• シンプルな確認ダイアログ

3. block-display-modal

コンポーネント:

Source: gui/smalruby3-gui/src/components/block-display-modal/
Target: gui/smalruby3-editor/packages/scratch-gui/src/components/block-display-modal/

Files:
- block-display-modal.jsx (537行) ← 最大サイズ
- block-display-modal.css (10.8KB)
- icon--clipboard-copy.svg

コンテナ:

Source: gui/smalruby3-gui/src/containers/block-display-modal.jsx
Target: gui/smalruby3-editor/packages/scratch-gui/src/containers/block-display-modal.jsx

Reducer:

Source: gui/smalruby3-gui/src/reducers/block-display.js
Target: gui/smalruby3-editor/packages/scratch-gui/src/reducers/block-display.js

依存関係:

• ✅ src/reducers/block-display.js - ブロック表示状態管理 (openBlockDisplayModal, closeBlockDisplayModal)
• ✅ Scratch VM - ブロック情報の取得
• ✅ クリップボード API

機能:

• 全ブロックのビジュアル表示
• カテゴリ別フィルタリング
• クリップボードへのコピー
• 検索機能

4. url-loader-modal

コンポーネント:

Source: gui/smalruby3-gui/src/components/url-loader-modal/
Target: gui/smalruby3-editor/packages/scratch-gui/src/components/url-loader-modal/

Files:
- url-loader-modal.jsx (183行)
- url-loader-modal.css (2.6KB)
- url-loader-icon.svg

HOC:

Source: gui/smalruby3-gui/src/lib/url-loader-hoc.jsx
Target: gui/smalruby3-editor/packages/scratch-gui/src/lib/url-loader-hoc.jsx

依存関係:

• ✅ src/lib/url-loader-hoc.jsx - URL からのプロジェクト読み込みロジック
• ✅ プロジェクト読み込み API

機能:

• URL 入力によるプロジェクト読み込み
• URL バリデーション
• エラーハンドリング

5. google-drive-save-dialog

コンポーネント:

Source: gui/smalruby3-gui/src/components/google-drive-save-dialog/
Target: gui/smalruby3-editor/packages/scratch-gui/src/components/google-drive-save-dialog/

Files:
- google-drive-save-dialog.jsx (288行)
- google-drive-save-dialog.css (2.1KB)

HOC:

Source: gui/smalruby3-gui/src/containers/google-drive-loader-hoc.jsx
Target: gui/smalruby3-editor/packages/scratch-gui/src/containers/google-drive-loader-hoc.jsx

Source: gui/smalruby3-gui/src/containers/google-drive-saver-hoc.jsx
Target: gui/smalruby3-editor/packages/scratch-gui/src/containers/google-drive-saver-hoc.jsx

API:

Source: gui/smalruby3-gui/src/lib/google-drive-api.js
Target: gui/smalruby3-editor/packages/scratch-gui/src/lib/google-drive-api.js

Reducer:

Source: gui/smalruby3-gui/src/reducers/google-drive-file.js
Target: gui/smalruby3-editor/packages/scratch-gui/src/reducers/google-drive-file.js

Source: gui/smalruby3-gui/src/reducers/koshien-file.js (関連)
Target: gui/smalruby3-editor/packages/scratch-gui/src/reducers/koshien-file.js

依存関係:

• ✅ src/lib/google-drive-api.js - Google Drive API クライアント
• ✅ src/reducers/google-drive-file.js - Google Drive ファイル状態管理
• ✅ Google OAuth 認証

機能:

• Google Drive への保存
• Google Drive からの読み込み
• OAuth 認証フロー
• ファイル名の入力と検証

GUI への統合

gui.jsx への追加

Source: gui/smalruby3-gui/src/components/gui/gui.jsx

必要な変更:

// Imports
import BlockDisplayModal from '../../containers/block-display-modal.jsx';
import MeshDomainModal from '../../containers/mesh-domain-modal.jsx';
import URLLoaderModal from '../url-loader-modal/url-loader-modal.jsx';
import KoshienTestModal from '../koshien-test-modal/koshien-test-modal.jsx';

// Render 内で使用
<BlockDisplayModal />
<MeshDomainModal />
<URLLoaderModal />
<KoshienTestModal />

menu-bar.jsx への統合

Source: gui/smalruby3-gui/src/components/menu-bar/menu-bar.jsx

必要な変更:

// Imports
import GoogleDriveLoaderHOC from '../../containers/google-drive-loader-hoc.jsx';
import GoogleDriveSaverHOC from '../../containers/google-drive-saver-hoc.jsx';
import GoogleDriveSaveDialog from '../google-drive-save-dialog/google-drive-save-dialog.jsx';
import {openBlockDisplayModal} from '../../reducers/block-display';
import {clearGoogleDriveFile} from '../../reducers/google-drive-file';

// Event handlers
handleClickMesh () {
    this.props.onOpenMeshDomainModal();
}

handleClickKoshienTest () {
    this.props.onOpenKoshienTestModal();
}

// Props
onOpenBlockDisplayModal: PropTypes.func,
onOpenMeshDomainModal: PropTypes.func,
onOpenKoshienTestModal: PropTypes.func,

// mapDispatchToProps
onOpenMeshDomainModal: () => dispatch(openMeshDomainModal()),
onOpenBlockDisplayModal: () => dispatch(openBlockDisplayModal()),
onOpenKoshienTestModal: () => dispatch(openKoshienTestModal()),

アイコン:

Source: gui/smalruby3-gui/src/components/menu-bar/block-display-icon.svg
Target: gui/smalruby3-editor/packages/scratch-gui/src/components/menu-bar/block-display-icon.svg

Reducer の統合

modals.js への追加

Source: gui/smalruby3-gui/src/reducers/modals.js

必要な変更:

const MODAL_MESH_DOMAIN = 'meshDomainModal';
const MODAL_KOSHIEN_TEST = 'koshienTestModal';

const initialState = {
    // ... existing modals
    [MODAL_MESH_DOMAIN]: false,
    [MODAL_KOSHIEN_TEST]: false
};

const openMeshDomainModal = function () {
    return openModal(MODAL_MESH_DOMAIN);
};

const openKoshienTestModal = function () {
    return openModal(MODAL_KOSHIEN_TEST);
};

const closeMeshDomainModal = function () {
    return closeModal(MODAL_MESH_DOMAIN);
};

const closeKoshienTestModal = function () {
    return closeModal(MODAL_KOSHIEN_TEST);
};

export {
    // ... existing exports
    openMeshDomainModal,
    openKoshienTestModal,
    closeMeshDomainModal,
    closeKoshienTestModal
};

新規 Reducer

block-display.js:

• ブロック表示モーダルの状態管理
• 表示するブロックの選択状態

google-drive-file.js:

• Google Drive ファイルの状態管理
• 現在のファイル ID とメタデータ

koshien-file.js (関連):

• 甲子園ファイルの状態管理

依存パッケージ

必要な npm パッケージ

Google Drive 関連:

{
  "dependencies": {
    "cross-fetch": "^3.x.x"  // Google Drive API 用
  }
}

その他:

• すでに存在: classnames, lodash.bindall, prop-types, react, react-intl, react-redux

実装優先度

Priority 1: コア機能モーダル (即座に必要)

block-display-modal:

• ✅ 最大 537 行、最も複雑
• ✅ ブロック一覧表示機能（Smalruby の重要機能）
• ✅ 設定メニューから使用

mesh-domain-modal:

• ✅ Mesh V2 拡張の設定に必要
• ✅ ファイルメニューから使用

Priority 2: Smalruby オリジナル機能 (重要)

koshien-test-modal:

• ✅ 甲子園拡張のテスト機能
• ✅ シンプル (99行)

url-loader-modal:

• ✅ URL からのプロジェクト読み込み
• ✅ 183 行

Priority 3: Google Drive 連携 (オプション)

google-drive-save-dialog:

• ✅ Google Drive 保存機能
• ✅ OAuth 認証が必要
• ✅ 複雑な依存関係 (google-drive-api.js, HOC)

テスト計画

Unit Tests

既存テスト:

# 旧リポジトリのテストを確認
ls gui/smalruby3-gui/test/unit/components/

移行が必要なテスト:

• 各コンポーネントのレンダリングテスト
• Reducer のアクションテスト
• Google Drive API のモックテスト

Integration Tests

テストシナリオ:

1. mesh-domain-modal:

   • ドメイン入力 → バリデーション → 保存 → モーダル閉じる
   • エラー表示の確認 (256文字超過、不正文字)

2. block-display-modal:

   • モーダル表示 → カテゴリ選択 → ブロック表示
   • クリップボードコピー機能

3. koshien-test-modal:

   • モーダル表示 → テスト実行 → 結果確認

4. url-loader-modal:

   • URL 入力 → プロジェクト読み込み
   • 不正 URL のエラーハンドリング

5. google-drive-save-dialog:

   • OAuth 認証 → ファイル名入力 → 保存
   • 既存ファイルの上書き確認

テスト実行コマンド

# Unit tests
npm test -- components

# Integration tests
npm run test:integration -- modals

実装手順

Step 1: ディレクトリ構造の作成

cd packages/scratch-gui

# Components
mkdir -p src/components/mesh-domain-modal
mkdir -p src/components/koshien-test-modal
mkdir -p src/components/block-display-modal
mkdir -p src/components/url-loader-modal
mkdir -p src/components/google-drive-save-dialog

# Containers (block-display-modal, mesh-domain-modal は container あり)
# Lib (url-loader-hoc.jsx, google-drive-api.js)
mkdir -p src/lib

# Reducers
# (既存の reducers ディレクトリに追加)

Step 2: ファイルのコピー

Priority 1: コア機能:

# block-display-modal
cp -r /path/to/smalruby3-gui/src/components/block-display-modal/* \
      packages/scratch-gui/src/components/block-display-modal/
cp /path/to/smalruby3-gui/src/containers/block-display-modal.jsx \
   packages/scratch-gui/src/containers/
cp /path/to/smalruby3-gui/src/reducers/block-display.js \
   packages/scratch-gui/src/reducers/

# mesh-domain-modal
cp -r /path/to/smalruby3-gui/src/components/mesh-domain-modal/* \
      packages/scratch-gui/src/components/mesh-domain-modal/
cp /path/to/smalruby3-gui/src/containers/mesh-domain-modal.jsx \
   packages/scratch-gui/src/containers/

Priority 2: Smalruby オリジナル:

# koshien-test-modal
cp -r /path/to/smalruby3-gui/src/components/koshien-test-modal/* \
      packages/scratch-gui/src/components/koshien-test-modal/

# url-loader-modal
cp -r /path/to/smalruby3-gui/src/components/url-loader-modal/* \
      packages/scratch-gui/src/components/url-loader-modal/
cp /path/to/smalruby3-gui/src/lib/url-loader-hoc.jsx \
   packages/scratch-gui/src/lib/

Priority 3: Google Drive:

# google-drive-save-dialog
cp -r /path/to/smalruby3-gui/src/components/google-drive-save-dialog/* \
      packages/scratch-gui/src/components/google-drive-save-dialog/
cp /path/to/smalruby3-gui/src/containers/google-drive-*-hoc.jsx \
   packages/scratch-gui/src/containers/
cp /path/to/smalruby3-gui/src/lib/google-drive-api.js \
   packages/scratch-gui/src/lib/
cp /path/to/smalruby3-gui/src/reducers/google-drive-file.js \
   packages/scratch-gui/src/reducers/
cp /path/to/smalruby3-gui/src/reducers/koshien-file.js \
   packages/scratch-gui/src/reducers/

Step 3: modals.js Reducer の更新

Target: packages/scratch-gui/src/reducers/modals.js

# 既存の modals.js に Smalruby カスタムモーダルを追加
# - MODAL_MESH_DOMAIN
# - MODAL_KOSHIEN_TEST
# - open/close 関数

Step 4: GUI への統合

gui.jsx:

# Import 追加
# コンポーネントの配置

menu-bar.jsx:

# Import 追加
# Event handler 追加
# Props 追加
# mapDispatchToProps 追加

Step 5: Import パスの確認

潜在的な問題:

• モノレポ構造で相対パスが変わる可能性
• Mesh アイコン画像のパス確認

確認箇所:

// mesh-domain-modal.jsx
import meshIcon from '../../lib/libraries/extensions/mesh/mesh-small.png';
// ← パスが正しいか確認

Step 6: Lint の実行と修正

npm run lint -w @scratch/scratch-gui
# エラーがあれば修正

Step 7: ビルドテスト

npm run build -w @scratch/scratch-gui
# 期待: エラーなくビルド完了

エラーハンドリング

想定されるエラー

1. モーダルが表示されない

Error: Cannot find reducer 'modals'

対策: modals.js reducer が正しく統合されているか確認

2. 画像が見つからない

Error: Cannot find module 'mesh-small.png'

対策: 画像ファイルのパスを確認、必要に応じてコピー

3. Redux 接続エラー

Error: mapStateToProps is not defined

対策: Container の Redux 接続を確認

4. Google Drive API エラー

Error: OAuth client ID not configured

対策: 環境変数または設定ファイルで OAuth 設定を追加

セキュリティ考慮事項

URL Loader

URL インジェクション対策:

• URL のホワイトリスト検証
• プロトコルの制限 (https のみ)
• CORS ポリシー確認

Google Drive

OAuth トークン管理:

• トークンをローカルストレージに保存する場合の暗号化
• トークン更新フローの実装
• 認証エラー時の適切なハンドリング

XSS 対策:

• ファイル名の入力検証
• サニタイゼーション

実装チェックリスト

Priority 1

• src/components/block-display-modal/ をコピー
• src/containers/block-display-modal.jsx をコピー
• src/reducers/block-display.js をコピー
• src/components/mesh-domain-modal/ をコピー
• src/containers/mesh-domain-modal.jsx をコピー
• src/reducers/modals.js に mesh/koshien モーダル追加

Priority 2

• src/components/koshien-test-modal/ をコピー
• src/components/url-loader-modal/ をコピー
• src/lib/url-loader-hoc.jsx をコピー

Priority 3

• src/components/google-drive-save-dialog/ をコピー
• src/containers/google-drive-*-hoc.jsx をコピー
• src/lib/google-drive-api.js をコピー
• src/reducers/google-drive-file.js をコピー
• src/reducers/koshien-file.js をコピー

統合

• gui.jsx にカスタムモーダルを追加
• menu-bar.jsx にイベントハンドラを追加
• Import パスが正しいことを確認
• 画像ファイルのパス確認
• Lint を実行してエラーを修正
• ビルドが成功することを確認

テスト

• Unit tests をコピーして実行
• 各モーダルの表示テスト
• Reducer のアクションテスト
• Google Drive OAuth フローのテスト

検証手順

1. ファイルコピーの確認

cd packages/scratch-gui/src/components
ls -la mesh-domain-modal/ koshien-test-modal/ block-display-modal/ \
       url-loader-modal/ google-drive-save-dialog/
# 期待: すべてのディレクトリが存在

2. モーダル表示テスト

# 開発サーバー起動
npm run dev -w @scratch/scratch-gui

# ブラウザで確認:
# 1. メニューバー → ファイル → Mesh V2 設定 → mesh-domain-modal 表示
# 2. メニューバー → 設定 → ブロック表示 → block-display-modal 表示
# 3. メニューバー → 甲子園 → テスト → koshien-test-modal 表示

3. Redux DevTools で状態確認

// modals.js の状態
{
  meshDomainModal: false,
  koshienTestModal: false
}

// block-display.js の状態
{
  visible: false
}

// google-drive-file.js の状態
{
  fileId: null
}

成功基準

✅ 必須:

1. 全カスタムコンポーネントが正しくコピーされている
2. Lint エラーがない
3. ビルドが成功する
4. mesh-domain-modal と block-display-modal が表示される

✅ 推奨:

1. 全 Unit tests が通る
2. 全 5 つのモーダルが正しく表示される
3. Reducer のアクションが正しく動作する
4. Google Drive OAuth が動作する (オプション)

次のステップ

Phase 3.3 完了後:
→ Phase 3.4: ビルドスクリプトの移行
→ postbuild.mjs, prepublish.mjs の統合
→ webpack 設定の最終調整

[takaokouji]

Phase 3.4: ビルドスクリプトの移行 - 詳細設計

現状分析

ビルドスクリプトの役割

Smalruby 固有のビルドプロセスを実装するスクリプト群。開発・デプロイワークフローの重要な部分。

スクリプト一覧:

1. postbuild.mjs - ビルド後の fetch-worker パス修正
2. prepublish.mjs - micro:bit/micro:bit More の hex ファイルダウンロード
3. makePWAAssetsManifest.js - PWA マニフェスト生成
4. make-setup-opal.js - Opal 初期化 (Phase 3.1 で移行)

移行対象ファイル

1. postbuild.mjs

Source: gui/smalruby3-gui/scripts/postbuild.mjs
Target: gui/smalruby3-editor/packages/scratch-gui/scripts/postbuild.mjs

役割:

• GitHub Pages サブディレクトリデプロイ用の fetch-worker パス修正
• PUBLIC_PATH 環境変数に基づいてパスを書き換え
• build/gui.js と build/player.js を修正

処理内容:

// 修正対象パターン
return "chunks/" + "fetch-worker"
↓
return "/smalruby3-gui/chunks/" + "fetch-worker"

// 修正対象パターン 2
=>"chunks/fetch-worker.
↓
=>"/smalruby3-gui/chunks/fetch-worker.

依存関係:

• ✅ Node.js 標準モジュール: fs, path
• ✅ ES Modules (import/export)
• ✅ 環境変数: PUBLIC_PATH

使用タイミング:

{
  "scripts": {
    "build": "npm run clean && ... && webpack && node ./scripts/postbuild.mjs"
  }
}

2. prepublish.mjs

Source: gui/smalruby3-gui/scripts/prepublish.mjs
Target: gui/smalruby3-editor/packages/scratch-gui/scripts/prepublish.mjs

役割:

• micro:bit 用 hex ファイルのダウンロード
• micro:bit More 用 hex ファイルのダウンロード
• 生成ファイルの作成 (src/generated/*.cjs)

処理内容:

micro:bit:

// ダウンロード元
URL: https://downloads.scratch.mit.edu/microbit/scratch-microbit.hex.zip

// 保存先
static/microbit/scratch-microbit.hex

// 生成ファイル
src/generated/microbit-hex-url.cjs

micro:bit More:

// ダウンロード元
URL: https://github.com/microbit-more/pxt-mbit-more-v2/releases/download/0.2.5/microbit-mbit-more-v2-0_2_5.hex

// 保存先
static/microbitMore/microbit-mbit-more-v2-0_2_5.hex

// 生成ファイル
src/generated/microbit-more-hex-url.cjs

生成ファイルの形式:

// src/generated/microbit-hex-url.cjs
// This file is generated by scripts/prepublish.mjs
// Do not edit this file directly
// This file relies on a loader to turn this `require` into a URL
module.exports = require('../../static/microbit/scratch-microbit.hex');

依存関係:

• ✅ npm パッケージ:
  • cross-fetch - HTTP リクエスト
  • yauzl - ZIP ファイル展開
• ✅ Node.js 標準モジュール: fs, path
• ✅ ES Modules (import/export)

使用タイミング:

{
  "scripts": {
    "prepublish": "node scripts/prepublish.mjs"
  }
}

重要: npm install 時や最初のビルド前に実行される。

3. makePWAAssetsManifest.js

Source: gui/smalruby3-gui/scripts/makePWAAssetsManifest.js
Target: gui/smalruby3-editor/packages/scratch-gui/scripts/makePWAAssetsManifest.js

役割:

• PWA (Progressive Web App) のアセットマニフェスト生成
• Service Worker 用のファイルリスト作成

依存関係:

• ✅ プロジェクト固有のアセット構造
• ✅ Node.js 標準モジュール: fs, path

使用タイミング:

{
  "scripts": {
    "build": "npm run clean && node ./scripts/makePWAAssetsManifest.js && webpack && ..."
  }
}

4. make-setup-opal.js (Phase 3.1 で移行済み)

Source: gui/smalruby3-gui/scripts/make-setup-opal.js
Target: gui/smalruby3-editor/packages/scratch-gui/scripts/make-setup-opal.js

Status: ✅ Phase 3.1 で移行済み

package.json への統合

現在の smalruby3-gui の scripts

{
  "scripts": {
    "setup-opal": "node ./scripts/make-setup-opal.js",
    "build": "npm run clean && node ./scripts/makePWAAssetsManifest.js && webpack && node ./scripts/postbuild.mjs",
    "clean": "rimraf ./build && mkdirp build && rimraf ./dist && mkdirp dist",
    "prepublish": "node scripts/prepublish.mjs",
    "deploy": "touch build/.nojekyll && gh-pages -t -d build -m \"[skip ci] Build for $(git log --pretty=format:%H -n1)\"",
    "deploy:smalruby.app": "rimraf node_modules/gh-pages/.cache && echo \"smalruby.app\" > build/CNAME && touch build/.nojekyll && gh-pages -t -d build -m \"build: build for $(git log --pretty=format:%H -n1) [skip ci] \""
  }
}

monorepo での統合

packages/scratch-gui/package.json:

{
  "scripts": {
    "setup-opal": "node ./scripts/make-setup-opal.js",
    "prebuild": "npm run setup-opal",
    "build": "npm run clean && node ./scripts/makePWAAssetsManifest.js && webpack && node ./scripts/postbuild.mjs",
    "clean": "rimraf ./build && mkdirp build && rimraf ./dist && mkdirp dist",
    "prepublish": "node scripts/prepublish.mjs",
    "deploy": "touch build/.nojekyll && gh-pages -t -d build -m \"[skip ci] Build for $(git log --pretty=format:%H -n1)\"",
    "deploy:smalruby.app": "rimraf node_modules/gh-pages/.cache && echo \"smalruby.app\" > build/CNAME && touch build/.nojekyll && gh-pages -t -d build -m \"build: build for $(git log --pretty=format:%H -n1) [skip ci] \""
  }
}

ルートの package.json:

{
  "scripts": {
    "build:gui": "npm run build -w @scratch/scratch-gui",
    "deploy:gui": "npm run deploy -w @scratch/scratch-gui",
    "deploy:smalruby.app": "npm run deploy:smalruby.app -w @scratch/scratch-gui"
  }
}

依存パッケージの追加

prepublish.mjs に必要

packages/scratch-gui/package.json:

{
  "dependencies": {
    "cross-fetch": "^3.1.5",
    "yauzl": "^2.10.0"
  }
}

postbuild.mjs に必要

• ✅ Node.js 標準モジュールのみ (追加不要)

makePWAAssetsManifest.js に必要

• ✅ プロジェクト固有 (追加不要)

ビルドフロー

開発ビルド

1. npm run prepublish
   ↓ micro:bit hex ファイルをダウンロード
   ↓ src/generated/*.cjs を生成

2. npm run prebuild
   ↓ Opal 初期化 (make-setup-opal.js)

3. npm run build
   ↓ npm run clean
   ↓ rimraf ./build && mkdirp build
   ↓ rimraf ./dist && mkdirp dist
   ↓
   ↓ node ./scripts/makePWAAssetsManifest.js
   ↓ PWA マニフェスト生成
   ↓
   ↓ webpack
   ↓ バンドル生成
   ↓
   ↓ node ./scripts/postbuild.mjs
   ↓ fetch-worker パス修正 (PUBLIC_PATH 設定時のみ)

4. 出力
   ↓ build/ ディレクトリにファイル生成

デプロイビルド (GitHub Pages)

1. PUBLIC_PATH=/smalruby3-gui/ npm run build
   ↓ 上記ビルドフロー + PUBLIC_PATH によるパス修正

2. npm run deploy
   ↓ touch build/.nojekyll
   ↓ gh-pages でデプロイ

デプロイビルド (smalruby.app)

1. PUBLIC_PATH=/ npm run build
   ↓ ルートパスでビルド

2. npm run deploy:smalruby.app
   ↓ rimraf node_modules/gh-pages/.cache
   ↓ echo "smalruby.app" > build/CNAME
   ↓ touch build/.nojekyll
   ↓ gh-pages でデプロイ

環境変数

PUBLIC_PATH

用途: サブディレクトリデプロイ用のパス設定

例:

# GitHub Pages サブディレクトリ
PUBLIC_PATH=/smalruby3-gui/ npm run build

# ルートパス
PUBLIC_PATH=/ npm run build

# 未設定 (デフォルト)
npm run build

影響:

• postbuild.mjs で fetch-worker パスを書き換え
• webpack の publicPath 設定

実装手順

Step 1: スクリプトファイルのコピー

cd packages/scratch-gui

# scripts ディレクトリが存在しない場合は作成
mkdir -p scripts

# postbuild.mjs をコピー
cp /path/to/smalruby3-gui/scripts/postbuild.mjs \
   packages/scratch-gui/scripts/

# prepublish.mjs をコピー
cp /path/to/smalruby3-gui/scripts/prepublish.mjs \
   packages/scratch-gui/scripts/

# makePWAAssetsManifest.js をコピー
cp /path/to/smalruby3-gui/scripts/makePWAAssetsManifest.js \
   packages/scratch-gui/scripts/

# make-setup-opal.js は Phase 3.1 で移行済み (確認のみ)
ls -la packages/scratch-gui/scripts/make-setup-opal.js

Step 2: package.json の更新

packages/scratch-gui/package.json:

# scripts セクションに追加
# - prepublish
# - build (postbuild.mjs を含む)
# - clean
# - deploy
# - deploy:smalruby.app

# dependencies に追加
# - cross-fetch
# - yauzl

Step 3: 依存パッケージのインストール

npm install -w @scratch/scratch-gui cross-fetch yauzl

Step 4: prepublish の実行テスト

npm run prepublish -w @scratch/scratch-gui

# 期待:
# - static/microbit/scratch-microbit.hex が生成される
# - static/microbitMore/microbit-mbit-more-v2-0_2_5.hex が生成される
# - src/generated/microbit-hex-url.cjs が生成される
# - src/generated/microbit-more-hex-url.cjs が生成される

Step 5: ビルドテスト (PUBLIC_PATH なし)

npm run build -w @scratch/scratch-gui

# 期待:
# - エラーなくビルド完了
# - build/gui.js が生成される
# - build/player.js が生成される
# - postbuild.mjs が "PUBLIC_PATH not set" メッセージを表示

Step 6: ビルドテスト (PUBLIC_PATH あり)

PUBLIC_PATH=/smalruby3-gui/ npm run build -w @scratch/scratch-gui

# 期待:
# - エラーなくビルド完了
# - build/gui.js に "/smalruby3-gui/chunks/fetch-worker" が含まれる
# - build/player.js に "/smalruby3-gui/chunks/fetch-worker" が含まれる
# - postbuild.mjs が "Fixed fetch-worker paths" メッセージを表示

Step 7: 生成ファイルの確認

# micro:bit hex ファイル
ls -lh packages/scratch-gui/static/microbit/
ls -lh packages/scratch-gui/static/microbitMore/

# 生成ファイル
cat packages/scratch-gui/src/generated/microbit-hex-url.cjs
cat packages/scratch-gui/src/generated/microbit-more-hex-url.cjs

エラーハンドリング

想定されるエラー

1. prepublish ダウンロードエラー

Error: Failed to fetch https://downloads.scratch.mit.edu/microbit/scratch-microbit.hex.zip

対策:

• ネットワーク接続を確認
• URL が正しいか確認
• プロキシ設定が必要な場合は設定

2. yauzl エラー

Error: invalid signature: 0x...

対策:

• ダウンロードしたファイルが壊れていないか確認
• キャッシュをクリアして再ダウンロード

3. postbuild パス書き換えエラー

File not found: build/gui.js

対策:

• webpack ビルドが成功しているか確認
• build/ ディレクトリが存在するか確認

4. PUBLIC_PATH 設定ミス

Warning: PUBLIC_PATH must start and end with /

対策:

• PUBLIC_PATH の形式を確認 (例: /smalruby3-gui/)

.gitignore の更新

生成ファイルを無視

packages/scratch-gui/.gitignore:

# Generated files
src/generated/

# Downloaded hex files
static/microbit/
static/microbitMore/

# Build output
build/
dist/

CI/CD への影響

GitHub Actions

ビルドワークフロー:

- name: Install dependencies
  run: npm ci

- name: Run prepublish
  run: npm run prepublish -w @scratch/scratch-gui

- name: Build GUI
  run: npm run build -w @scratch/scratch-gui
  env:
    PUBLIC_PATH: /smalruby3-gui/

- name: Deploy to GitHub Pages
  run: npm run deploy -w @scratch/scratch-gui

注意点:

• prepublish は npm ci の後に明示的に実行
• PUBLIC_PATH は環境変数で設定

実装チェックリスト

ファイルコピー

• scripts/postbuild.mjs をコピー
• scripts/prepublish.mjs をコピー
• scripts/makePWAAssetsManifest.js をコピー
• scripts/make-setup-opal.js を確認 (Phase 3.1 で移行済み)

package.json 更新

• scripts セクションに prepublish 追加
• scripts セクションに build 追加 (postbuild.mjs を含む)
• scripts セクションに clean 追加
• scripts セクションに deploy 追加
• scripts セクションに deploy:smalruby.app 追加
• dependencies に cross-fetch 追加
• dependencies に yauzl 追加

依存パッケージ

• npm install -w @scratch/scratch-gui cross-fetch yauzl を実行
• package-lock.json が更新されることを確認

テスト

• npm run prepublish が成功することを確認
• static/microbit/ に hex ファイルが生成される
• static/microbitMore/ に hex ファイルが生成される
• src/generated/*.cjs が生成される
• npm run build が成功することを確認 (PUBLIC_PATH なし)
• PUBLIC_PATH=/smalruby3-gui/ npm run build が成功することを確認
• build/gui.js に正しいパスが含まれる

.gitignore

• src/generated/ を .gitignore に追加
• static/microbit/ を .gitignore に追加
• static/microbitMore/ を .gitignore に追加

検証手順

1. prepublish の動作確認

# prepublish 実行
npm run prepublish -w @scratch/scratch-gui

# ファイル生成確認
ls -lh packages/scratch-gui/static/microbit/scratch-microbit.hex
ls -lh packages/scratch-gui/static/microbitMore/microbit-mbit-more-v2-0_2_5.hex

# 生成ファイル確認
cat packages/scratch-gui/src/generated/microbit-hex-url.cjs
cat packages/scratch-gui/src/generated/microbit-more-hex-url.cjs

2. postbuild の動作確認 (PUBLIC_PATH あり)

# PUBLIC_PATH 付きでビルド
PUBLIC_PATH=/smalruby3-gui/ npm run build -w @scratch/scratch-gui

# パス書き換え確認
grep "/smalruby3-gui/chunks/fetch-worker" packages/scratch-gui/build/gui.js
# 期待: マッチする行がある

grep "/smalruby3-gui/chunks/fetch-worker" packages/scratch-gui/build/player.js
# 期待: マッチする行がある

3. postbuild の動作確認 (PUBLIC_PATH なし)

# PUBLIC_PATH なしでビルド
npm run build -w @scratch/scratch-gui

# デフォルトパス確認
grep "\"chunks/fetch-worker\"" packages/scratch-gui/build/gui.js
# 期待: マッチする行がある (書き換えなし)

4. deploy スクリプトの動作確認

# deploy:smalruby.app の dry-run
# (実際のデプロイはしない)
echo "smalruby.app" > packages/scratch-gui/build/CNAME
cat packages/scratch-gui/build/CNAME
# 期待: smalruby.app

成功基準

✅ 必須:

1. 全スクリプトファイルが正しくコピーされている
2. package.json の scripts が正しく設定されている
3. 依存パッケージがインストールされている
4. npm run prepublish が成功し、hex ファイルがダウンロードされる
5. npm run build が成功する
6. PUBLIC_PATH=/smalruby3-gui/ npm run build が成功し、パスが書き換えられる

✅ 推奨:

1. .gitignore が正しく設定されている
2. CI/CD ワークフローが更新されている
3. ドキュメントが更新されている

次のステップ

Phase 3.4 完了後:
→ Phase 3 全体の統合テスト
→ 全機能が動作することを確認
→ PR 作成と Phase 3 完了

トラブルシューティング

prepublish が失敗する

症状: ダウンロードがタイムアウト

対策:

# プロキシ設定 (必要な場合)
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# または npm config で設定
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080

# 再試行
npm run prepublish -w @scratch/scratch-gui

postbuild でパスが書き換えられない

症状: PUBLIC_PATH を設定してもパスが変わらない

対策:

# postbuild.mjs のログを確認
PUBLIC_PATH=/smalruby3-gui/ npm run build -w @scratch/scratch-gui 2>&1 | grep postbuild

# 期待: "PUBLIC_PATH is set to: /smalruby3-gui/"
# 期待: "Fixed fetch-worker paths in build/gui.js"

# パターンマッチを確認
grep -n "chunks.*fetch-worker" packages/scratch-gui/build/gui.js

ビルドファイルが見つからない

症状: postbuild.mjs で "File not found: build/gui.js"

対策:

# webpack ビルドが成功しているか確認
ls -la packages/scratch-gui/build/

# build/ ディレクトリがない場合
npm run clean -w @scratch/scratch-gui
npm run build -w @scratch/scratch-gui