@kubohiroya/sb3-toolchain 0.2.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.ja.md +147 -0
- package/README.md +8 -4
- package/docs/extension-api-compatibility.md +169 -0
- package/docs/extension-bundles.md +27 -5
- package/docs/extension-id-migration.md +15 -4
- package/docs/ja/extension-api-compatibility.md +167 -0
- package/docs/ja/extension-bundles.md +449 -0
- package/docs/ja/extension-id-migration.md +69 -0
- package/docs/ja/source-format-v1.md +190 -0
- package/docs/ja/workflows.md +249 -0
- package/docs/source-format-v1.md +30 -7
- package/docs/workflows.md +21 -5
- package/package.json +4 -3
- package/src/cli.js +27 -1
- package/src/constants.js +1 -1
- package/src/extension-api-manifest.js +336 -0
- package/src/extension-bundle.js +21 -1
- package/src/extension-dependencies.js +2 -0
- package/src/extension-id-migration.js +74 -3
- package/src/extension-sync.js +189 -20
- package/src/import.js +28 -12
- package/src/index.js +11 -0
- package/src/source.js +15 -0
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
# SB3展開ソース形式v1
|
|
2
|
+
|
|
3
|
+
[English](../source-format-v1.md)
|
|
4
|
+
|
|
5
|
+
## レイアウト
|
|
6
|
+
|
|
7
|
+
```text
|
|
8
|
+
SOURCE_DIR/
|
|
9
|
+
├── sb3-source.json
|
|
10
|
+
├── project.source.json
|
|
11
|
+
├── embedded-extensions.json
|
|
12
|
+
├── assets/
|
|
13
|
+
│ └── <assetId>.<dataFormat>
|
|
14
|
+
└── extensions/
|
|
15
|
+
└── <extensionId>.js
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
`sb3-source.json`は、形式のバージョン、各構成要素へのパス、元のSB3におけるZIPエントリ順を記録します。
|
|
19
|
+
|
|
20
|
+
```json
|
|
21
|
+
{
|
|
22
|
+
"formatVersion": 1,
|
|
23
|
+
"project": "project.source.json",
|
|
24
|
+
"embeddedExtensions": "embedded-extensions.json",
|
|
25
|
+
"assetsDirectory": "assets",
|
|
26
|
+
"archiveEntries": ["project.json", "<assetId>.svg"]
|
|
27
|
+
}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## `project.source.json`
|
|
31
|
+
|
|
32
|
+
このファイルは、元のSB3の`project.json`を2スペースインデントで整形したJSONです。配列とオブジェクトの
|
|
33
|
+
順序は意味のある入力として保持されます。data URLとして埋め込まれていたTurboWarp機能拡張は、次の参照に
|
|
34
|
+
置き換えられます。
|
|
35
|
+
|
|
36
|
+
```text
|
|
37
|
+
embedded-extension:extensions/<extensionId>.js
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
ビルド時には、`embedded-extensions.json`のメディアタイプ、パラメータ、エンコーディングを使用してdata URLを
|
|
41
|
+
再構築します。
|
|
42
|
+
|
|
43
|
+
## `embedded-extensions.json`
|
|
44
|
+
|
|
45
|
+
このファイルは、埋め込み機能拡張のdata URL情報と展開先パスを記録します。GitHubから管理する機能拡張には、
|
|
46
|
+
任意の`source`メタデータを追加できます。
|
|
47
|
+
|
|
48
|
+
```json
|
|
49
|
+
{
|
|
50
|
+
"formatVersion": 1,
|
|
51
|
+
"extensions": [
|
|
52
|
+
{
|
|
53
|
+
"id": "example",
|
|
54
|
+
"path": "extensions/example.js",
|
|
55
|
+
"mediaType": "text/javascript",
|
|
56
|
+
"parameters": [],
|
|
57
|
+
"encoding": "base64",
|
|
58
|
+
"source": {
|
|
59
|
+
"provider": "github",
|
|
60
|
+
"repository": "owner/example-extension",
|
|
61
|
+
"ref": "main",
|
|
62
|
+
"resolvedCommit": "0123456789abcdef0123456789abcdef01234567",
|
|
63
|
+
"artifact": "dist/example.js",
|
|
64
|
+
"integrity": "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
|
|
65
|
+
"apiManifest": {
|
|
66
|
+
"artifact": "dist/extension-manifest.json",
|
|
67
|
+
"path": "extensions/example.manifest.json",
|
|
68
|
+
"formatVersion": 1,
|
|
69
|
+
"integrity": "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB="
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
]
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
- `repository`: `<owner>/<repository>`形式のGitHubリポジトリ
|
|
78
|
+
- `ref`: 更新候補として追跡するブランチ、タグ、またはコミット
|
|
79
|
+
- `resolvedCommit`: 現在のファイルの取得に使用した、小文字40文字のコミットSHA
|
|
80
|
+
- `artifact`: リポジトリルートを基準にしたJavaScript成果物のパス
|
|
81
|
+
- `integrity`: 現在のファイルのSRI形式SHA-256
|
|
82
|
+
- `apiManifest`: 任意で使用するAPI互換性メタデータ
|
|
83
|
+
- `artifact`: 同じGitHubリポジトリを基準にしたAPIマニフェストのパス
|
|
84
|
+
- `path`: 必須のローカルパス`extensions/<extensionId>.manifest.json`
|
|
85
|
+
- `formatVersion`: 対応するマニフェスト形式。現在は`1`
|
|
86
|
+
- `integrity`: インストール済みマニフェストのSRI形式SHA-256
|
|
87
|
+
|
|
88
|
+
検証とビルドでは、ネットワークへ接続せずに管理対象機能拡張を検証します。
|
|
89
|
+
|
|
90
|
+
- 実ファイルのSHA-256が`integrity`と一致する
|
|
91
|
+
- ファイルの`// ID: <extensionId>`ヘッダーが`id`と一致する
|
|
92
|
+
- リポジトリ、ref、コミット、成果物パスが安全な形式である
|
|
93
|
+
- `apiManifest`が存在する場合、そのJSONスキーマ、ID、形式バージョン、パス、SHA-256が有効である
|
|
94
|
+
|
|
95
|
+
既存の展開ソースディレクトリへSB3を再importすると、同じIDとパスの`source`メタデータが保持されます。
|
|
96
|
+
importしたファイルが記録済みのハッシュまたはIDと一致しない場合、既存の出力を変更せずにimportを拒否します。
|
|
97
|
+
新規importでは来歴を推測できないため、`source`は自動作成されません。
|
|
98
|
+
|
|
99
|
+
`extensions sync`は、変更不能な`resolvedCommit`を使用してJavaScriptと任意のAPIマニフェストを
|
|
100
|
+
ダウンロードし、そのIDとハッシュが既存メタデータに一致する場合に限りローカルファイルを復元します。
|
|
101
|
+
`extensions update`はGitHub APIを通じて`ref`を解決し、同じコミットから両方の成果物をダウンロードして、
|
|
102
|
+
候補APIマニフェストをインストール済み契約と比較します。互換性検査と内容検証が成功した後に限り、
|
|
103
|
+
`resolvedCommit`と両方のintegrity値を更新します。選択したすべてのエントリのダウンロードと検証が完了するまで、
|
|
104
|
+
展開ソースは変更されません。
|
|
105
|
+
|
|
106
|
+
機能拡張IDの移行では、マニフェストの`id`と`path`、`project.source.json`内の既知の参照、
|
|
107
|
+
`extensions/<id>.js`を1回のトランザクションで変更します。`extensions update`の一部として管理対象機能拡張を
|
|
108
|
+
移行する場合は、明示的に指定した`artifact`、`resolvedCommit`、`integrity`も新しい成果物に合わせて更新します。
|
|
109
|
+
任意のAPIマニフェストは、明示した旧IDと新IDのトップレベルIDを正規化してから比較し、新しいIDで保存して、
|
|
110
|
+
同じトランザクションで更新します。リモートファイル名も変わる場合は、`--api-manifest-artifact`で
|
|
111
|
+
`source.apiManifest.artifact`を明示的に更新します。
|
|
112
|
+
|
|
113
|
+
APIマニフェストファイルは展開ソースの検証入力であり、SB3アーカイブのエントリではありません。決定的なSB3の
|
|
114
|
+
バイト列は変わりません。マニフェストv1、互換性分類、破壊的変更の明示的な許可、ロールバックについては、
|
|
115
|
+
[`extension-api-compatibility.md`](extension-api-compatibility.md)を参照してください。
|
|
116
|
+
|
|
117
|
+
### `extensionBundles`
|
|
118
|
+
|
|
119
|
+
任意の`extensionBundles`配列を追加すると、複数の個別機能拡張を、生成SB3内だけで1つの権限単位にできます。
|
|
120
|
+
|
|
121
|
+
```json
|
|
122
|
+
{
|
|
123
|
+
"formatVersion": 1,
|
|
124
|
+
"extensions": [
|
|
125
|
+
{
|
|
126
|
+
"id": "extensionone",
|
|
127
|
+
"path": "extensions/extensionone.js",
|
|
128
|
+
"mediaType": "text/javascript",
|
|
129
|
+
"parameters": [],
|
|
130
|
+
"encoding": "base64"
|
|
131
|
+
},
|
|
132
|
+
{
|
|
133
|
+
"id": "extensiontwo",
|
|
134
|
+
"path": "extensions/extensiontwo.js",
|
|
135
|
+
"mediaType": "text/javascript",
|
|
136
|
+
"parameters": [],
|
|
137
|
+
"encoding": "base64"
|
|
138
|
+
}
|
|
139
|
+
],
|
|
140
|
+
"extensionBundles": [
|
|
141
|
+
{
|
|
142
|
+
"id": "projectbundle",
|
|
143
|
+
"name": "Project Extension Bundle",
|
|
144
|
+
"members": ["extensionone", "extensiontwo"]
|
|
145
|
+
}
|
|
146
|
+
]
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
- `id`: TurboWarpの`[a-z0-9]+`形式で、個別機能拡張と衝突しない複合機能拡張ID
|
|
151
|
+
- `name`: 権限確認と機能拡張カテゴリに表示される単一行の名前
|
|
152
|
+
- `members`: 2つ以上の個別機能拡張ID。順序によってブロックとメニューの合成順が決まる。パレットでは、
|
|
153
|
+
メタデータを持つ装飾済みbundle LABEL見出しとグループ間の二重separatorが追加される一方、元の機能拡張の
|
|
154
|
+
LABELエントリとseparatorは変更されない
|
|
155
|
+
|
|
156
|
+
1つのメンバーを複数のbundleに所属させることはできません。個別エントリ、個別JavaScript、`source`、
|
|
157
|
+
`project.source.json`が引き続き信頼できる情報源です。`build`は各元opcodeに`memberId + "__"`を加え、
|
|
158
|
+
出力側の`project.json`のopcode、`extensions`、`extensionURLs`、機能拡張ストレージだけをbundle IDに変更します。
|
|
159
|
+
埋め込まれるbundle JavaScriptのdata URLは1つです。
|
|
160
|
+
|
|
161
|
+
bundle JavaScriptの末尾には、元の個別data URLと機能拡張の順序を格納した形式1の復元カプセルが含まれます。
|
|
162
|
+
設定を削除するか、そのカプセルを含む生成SB3に対して`extensions unbundle`を実行すると、通常の出力へ
|
|
163
|
+
復元できます。互換性契約と復元手順については、[`extension-bundles.md`](extension-bundles.md)を参照してください。
|
|
164
|
+
|
|
165
|
+
## アセット
|
|
166
|
+
|
|
167
|
+
`assets/`には、`project.source.json`から参照されるコスチュームと音声が含まれます。各ファイル名は
|
|
168
|
+
`<assetId>.<dataFormat>`であり、`assetId`は内容のMD5と一致しなければなりません。未参照、欠落、余分な
|
|
169
|
+
ファイルはいずれも検証エラーです。
|
|
170
|
+
|
|
171
|
+
## 決定的出力
|
|
172
|
+
|
|
173
|
+
- ZIPエントリは`archiveEntries`に従う
|
|
174
|
+
- ZIPタイムスタンプは1980-01-01 00:00:00に固定
|
|
175
|
+
- 圧縮レベルは6に固定
|
|
176
|
+
- `project.json`は末尾に改行を持つ最小JSONとして格納
|
|
177
|
+
- ソース形式のバージョン、入力ファイル、ツールのバージョンが同じなら、同じバイト列を生成
|
|
178
|
+
|
|
179
|
+
## 安全性
|
|
180
|
+
|
|
181
|
+
- 絶対パス、`\`、空の構成要素、`.`、`..`を含むZIPエントリを拒否
|
|
182
|
+
- ソース入力としてシンボリックリンクと特殊ファイルを拒否
|
|
183
|
+
- ファイルシステムルート、Gitリポジトリルート、その祖先、`.git/`をimport先として拒否
|
|
184
|
+
- 認識できない既存ディレクトリを上書きしない
|
|
185
|
+
- 2段階の明示的な許可なしにGit管理対象の変更を破棄しない
|
|
186
|
+
- 中断された置換のロールバック領域が存在するときは、自動的に上書きしない
|
|
187
|
+
- 管理対象機能拡張のコミット、SHA-256、機能拡張IDをオフラインで検証
|
|
188
|
+
- bundle時に個別JavaScriptと来歴を保持し、互換性を確立できない契約を拒否
|
|
189
|
+
- GitHubからはHTTPSだけで取得し、リダイレクトを拒否してサイズを制限し、ダウンロードしたJavaScriptは
|
|
190
|
+
決して実行しない
|
|
@@ -0,0 +1,249 @@
|
|
|
1
|
+
# SB3ソース管理ワークフロー
|
|
2
|
+
|
|
3
|
+
[English](../workflows.md)
|
|
4
|
+
|
|
5
|
+
この文書では、Scratch 3またはTurboWarpのSB3をGit内の展開ソースとして管理し、検証済みSB3を再ビルドする
|
|
6
|
+
一般的なワークフローを説明します。各プロジェクトリポジトリでは、編集、テスト、配布の手順を個別に定義して
|
|
7
|
+
ください。
|
|
8
|
+
|
|
9
|
+
展開ディレクトリのレイアウトとファイル形式については、
|
|
10
|
+
[`source-format-v1.md`](source-format-v1.md)を参照してください。
|
|
11
|
+
|
|
12
|
+
## 原則
|
|
13
|
+
|
|
14
|
+
- Git内の展開ディレクトリを信頼できる情報源として扱い、生成SB3ファイルはビルド成果物として扱う
|
|
15
|
+
- TurboWarp Editorで編集したSB3は、差分を確認した後に限りimportする
|
|
16
|
+
- コミット前と配布前に`check`を実行する
|
|
17
|
+
- CIとリリースワークフローでは、固定したツールチェーンバージョンとコミット済み展開ソースからビルドする
|
|
18
|
+
- 管理対象の埋め込み機能拡張は、固定したソースコミットとSHA-256から再現する
|
|
19
|
+
|
|
20
|
+
以下の例では、展開ソースに`app/`、エディタで保存したSB3に`tmp/edited.sb3`、生成出力に
|
|
21
|
+
`dist/project.sb3`を使用します。必要に応じてプロジェクト固有のパスを選択してください。
|
|
22
|
+
|
|
23
|
+
## 初回import
|
|
24
|
+
|
|
25
|
+
TurboWarpで保存したSB3を、Gitでの管理に適したファイルへ展開します。
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
sb3-toolchain import tmp/edited.sb3 --output app
|
|
29
|
+
sb3-toolchain check app
|
|
30
|
+
git status --short
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
import後、少なくとも次の項目を確認します。
|
|
34
|
+
|
|
35
|
+
- `project.source.json`の変更がエディタで行った操作に対応している
|
|
36
|
+
- `assets/`へのアセット追加または削除が意図したものだけである
|
|
37
|
+
- `extensions/`と`embedded-extensions.json`に予期しない変更がない
|
|
38
|
+
- `sb3-toolchain check app`が成功する
|
|
39
|
+
|
|
40
|
+
新規importでは、埋め込みJavaScriptの取得元は推測されません。GitHubでホストされる機能拡張を管理対象にする
|
|
41
|
+
場合は、後述の来歴メタデータを追加してください。
|
|
42
|
+
|
|
43
|
+
## 既存ソースへの再import
|
|
44
|
+
|
|
45
|
+
プロジェクトを編集した後、保存したSB3を既存の展開ソースディレクトリへimportします。
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
git status --short
|
|
49
|
+
sb3-toolchain import tmp/edited.sb3 --output app
|
|
50
|
+
sb3-toolchain check app
|
|
51
|
+
git diff -- app
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
既存の展開ソースと内容が異なる場合、ツールは置換の確認を求めます。非対話環境では`--yes`によって確認を
|
|
55
|
+
省略できますが、Git管理対象の未コミット変更は破棄されません。破棄される変更を確認した後に限り、両方の
|
|
56
|
+
オプションを指定してください。
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
sb3-toolchain import tmp/edited.sb3 --output app \
|
|
60
|
+
--yes \
|
|
61
|
+
--discard-local-changes
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
`--discard-local-changes`は復旧手段ではありません。使用する前に、必要な変更をコミットするなどして保存して
|
|
65
|
+
ください。`--force`オプションはありません。
|
|
66
|
+
|
|
67
|
+
同じIDとパスを持つ管理対象機能拡張の来歴メタデータは、再import時も保持されます。SB3内のJavaScriptが
|
|
68
|
+
記録済みのIDまたはSHA-256と異なる場合、実ファイルと来歴の不整合を防ぐため、既存出力を変更せずにimportを
|
|
69
|
+
拒否します。
|
|
70
|
+
|
|
71
|
+
## 検証とビルド
|
|
72
|
+
|
|
73
|
+
展開ソースだけを検証するには`check`、SB3を生成するには`build`を使用します。
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
sb3-toolchain check app
|
|
77
|
+
sb3-toolchain build app --output dist/project.sb3
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
`check`と`build`はネットワークへ接続しません。ローカル入力だけを使用して、アセット参照、MD5ハッシュ、
|
|
81
|
+
展開形式、埋め込み機能拡張ID、SHA-256ハッシュを検証します。
|
|
82
|
+
|
|
83
|
+
`build`はZIPエントリ順、タイムスタンプ、圧縮設定を固定します。同じツールチェーンバージョンと展開ソースから、
|
|
84
|
+
バイト単位で同一のSB3が生成されます。既存出力が同一なら変更しません。異なる場合は、置換の確認または
|
|
85
|
+
`--yes`が必要です。
|
|
86
|
+
|
|
87
|
+
プロジェクト固有のテストに加えて、生成SB3をTurboWarpで開き、起動、主要な操作、画像、音声、埋め込み
|
|
88
|
+
機能拡張の動作を確認してください。
|
|
89
|
+
|
|
90
|
+
## 管理対象の埋め込み機能拡張
|
|
91
|
+
|
|
92
|
+
`embedded-extensions.json`の`source`オブジェクトには、GitHubリポジトリ、追跡対象ref、解決済みコミット、
|
|
93
|
+
成果物パス、SHA-256を記録できます。更新時の静的互換性検査に使用するバージョン付きAPIマニフェストも任意で
|
|
94
|
+
設定できます。完全なスキーマは[`source-format-v1.md`](source-format-v1.md)を参照してください。
|
|
95
|
+
|
|
96
|
+
機能拡張コマンドの役割は次のとおりです。
|
|
97
|
+
|
|
98
|
+
| コマンド | ネットワーク | refの解決 | メタデータ更新 | 目的 |
|
|
99
|
+
| ----------------------- | ------------ | --------- | -------------- | -------------------------------------- |
|
|
100
|
+
| `extensions status` | あり | あり | なし | 追跡対象refに更新があるか確認 |
|
|
101
|
+
| `extensions sync` | あり | なし | なし | 固定したコミットからファイルを復元 |
|
|
102
|
+
| `extensions update` | あり | あり | あり | 最新のrefコミットへ明示的に更新 |
|
|
103
|
+
| `extensions migrate-id` | なし | なし | ID/参照 | プロジェクトで使用中の機能拡張IDを移行 |
|
|
104
|
+
| `extensions bundle` | なし | なし | bundle設定 | 機能拡張を1つの権限単位へ統合 |
|
|
105
|
+
| `extensions unbundle` | なし | なし | 設定またはSB3 | 個別機能拡張を使用する出力へ復元 |
|
|
106
|
+
|
|
107
|
+
### 更新の確認
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
sb3-toolchain extensions status app
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
`status`はローカルファイルを変更しません。追跡対象refが`resolvedCommit`と異なる機能拡張について上流の
|
|
114
|
+
変更を確認し、更新するかどうかを判断します。
|
|
115
|
+
|
|
116
|
+
### 固定したコミットからの復元
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
sb3-toolchain extensions sync app
|
|
120
|
+
sb3-toolchain check app
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
`sync`は変更可能なブランチやタグを解決しません。記録済みの`resolvedCommit`からダウンロードし、
|
|
124
|
+
JavaScriptと任意のAPIマニフェストが記録済みIDおよびSHA-256値に一致する場合に限り、ローカルファイルを
|
|
125
|
+
置き換えます。
|
|
126
|
+
|
|
127
|
+
### 追跡対象refの更新
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
sb3-toolchain extensions update app
|
|
131
|
+
sb3-toolchain extensions update app EXTENSION_ID
|
|
132
|
+
sb3-toolchain check app
|
|
133
|
+
git diff -- app
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
IDを省略すると、管理対象の全機能拡張を1回のトランザクションで更新します。ダウンロードまたは検証が1つでも
|
|
137
|
+
失敗した場合、ファイルもメタデータも変更しません。
|
|
138
|
+
|
|
139
|
+
`source.apiManifest`が存在する場合、同じ解決済みコミットからJavaScriptとAPIマニフェストをダウンロードします。
|
|
140
|
+
互換性のある追加は報告されます。ブロックの削除、ブロック種別の変更、引数契約の変更、参照中メニューの削除、
|
|
141
|
+
`acceptReporters`の変更は、インストール前に拒否されます。未参照メニューの削除には互換性があります。
|
|
142
|
+
報告されたすべてのパスを確認した後、意図的な破壊的更新には両方のフラグが必要です。
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
sb3-toolchain extensions update app EXTENSION_ID --allow-breaking-api --yes
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
バージョン付きマニフェスト契約、分類表、既定OFFの動作、ロールバックについては、
|
|
149
|
+
[`extension-api-compatibility.md`](extension-api-compatibility.md)を参照してください。
|
|
150
|
+
|
|
151
|
+
更新PRでは、`resolvedCommit`、JavaScriptとマニフェストのintegrity、互換性パス、両成果物をまとめて確認し、
|
|
152
|
+
生成SB3で機能拡張の主要機能をテストします。
|
|
153
|
+
|
|
154
|
+
## 機能拡張IDの移行
|
|
155
|
+
|
|
156
|
+
機能拡張IDはopcodeとmonitorに保存されるため、ファイル名やマニフェストだけを手作業で変更しないでください。
|
|
157
|
+
dry runから始め、分類済み参照と未分類参照の両方を確認します。
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
sb3-toolchain extensions migrate-id app --from OLD_ID --to NEW_ID
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
新しいIDを宣言するJavaScriptを用意して結果を確認し、適用します。
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
sb3-toolchain extensions migrate-id app --from OLD_ID --to NEW_ID --yes
|
|
167
|
+
sb3-toolchain check app
|
|
168
|
+
git diff -- app
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
GitHub管理対象機能拡張では、上流成果物の更新とID移行を1回のトランザクションにできます。
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
sb3-toolchain extensions update app OLD_ID \
|
|
175
|
+
--migrate-id NEW_ID \
|
|
176
|
+
--artifact dist/NEW_ID.js
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
上流の成果物パスも変わった場合に限り`--artifact`を指定します。影響するスキーマ、衝突検査、未分類参照、
|
|
180
|
+
ロールバックについては、[`extension-id-migration.md`](extension-id-migration.md)を参照してください。
|
|
181
|
+
|
|
182
|
+
## unsandboxed権限を1回の確認に統合
|
|
183
|
+
|
|
184
|
+
複数の埋め込み機能拡張を含むプロジェクトでは、静的bundleを任意で使用できます。元のJavaScript、ID、opcode、
|
|
185
|
+
来歴は変更されず、ビルド出力だけが1つの複合機能拡張へ変換されます。
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
sb3-toolchain extensions bundle app \
|
|
189
|
+
--id projectbundle \
|
|
190
|
+
--name "Project Extension Bundle" \
|
|
191
|
+
extensionone extensiontwo
|
|
192
|
+
sb3-toolchain extensions bundle app \
|
|
193
|
+
--id projectbundle \
|
|
194
|
+
--name "Project Extension Bundle" \
|
|
195
|
+
extensionone extensiontwo \
|
|
196
|
+
--yes
|
|
197
|
+
sb3-toolchain check app
|
|
198
|
+
sb3-toolchain build app --output dist/project.sb3 --yes
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
プロジェクトレベルの自動テストと実際のTurboWarpでのスモークテストを使用し、bundle前後での同等な動作、
|
|
202
|
+
1回だけの権限確認、保存後の再読み込み成功を検証します。問題がある場合は、保持されている個別機能拡張へ
|
|
203
|
+
復元します。
|
|
204
|
+
|
|
205
|
+
```bash
|
|
206
|
+
sb3-toolchain extensions unbundle app projectbundle
|
|
207
|
+
sb3-toolchain extensions unbundle app projectbundle --yes
|
|
208
|
+
sb3-toolchain check app
|
|
209
|
+
sb3-toolchain build app --output dist/project.sb3 --yes
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
展開ソースが利用できない場合でも、このバージョンのツールチェーンで生成したSB3は直接unbundleできます。
|
|
213
|
+
最初のコマンドはdry runで、`--yes`を指定した場合に限り出力を書き込みます。
|
|
214
|
+
|
|
215
|
+
```bash
|
|
216
|
+
sb3-toolchain extensions unbundle \
|
|
217
|
+
dist/project.sb3 projectbundle \
|
|
218
|
+
--output dist/project.unbundled.sb3
|
|
219
|
+
sb3-toolchain extensions unbundle \
|
|
220
|
+
dist/project.sb3 projectbundle \
|
|
221
|
+
--output dist/project.unbundled.sb3 \
|
|
222
|
+
--yes
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
互換性契約、ソースコメント、opcodeとストレージの変換、直接unbundleの制限、再import時の注意事項については、
|
|
226
|
+
[`extension-bundles.md`](extension-bundles.md)を参照してください。
|
|
227
|
+
|
|
228
|
+
## CIと配布
|
|
229
|
+
|
|
230
|
+
依存関係のバージョンを固定し、CIで少なくとも次のコマンドを実行します。
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
sb3-toolchain check app
|
|
234
|
+
sb3-toolchain build app --output dist/project.sb3 --yes
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
プロジェクトレベルの自動テストと手動検証に合格したSB3だけを配布してください。ネットワーク状態が入力になって
|
|
238
|
+
しまうため、リリースビルドの一部として`sync`や`update`を暗黙的に実行しないでください。更新は独立した
|
|
239
|
+
レビュー可能な変更として行い、固定した展開ソースを先にコミットします。
|
|
240
|
+
|
|
241
|
+
## 失敗時の対応
|
|
242
|
+
|
|
243
|
+
- コマンドが置換を拒否した場合は、再試行する前に`git status`と該当する差分を確認する
|
|
244
|
+
- `.<output-name>.rollback-*`が残っている場合は、復元または削除を決める前に現在の出力と比較する
|
|
245
|
+
- 機能拡張更新が途中で失敗した場合は、再試行する前に`git diff`を確認する
|
|
246
|
+
- merge済み変更はプロジェクトコミットをrevertし、ソース、成果物、来歴をまとめて元に戻す
|
|
247
|
+
- 公開済みSB3を置き換える場合は、プロジェクトのリリースポリシーに従い、履歴を保持する
|
|
248
|
+
|
|
249
|
+
復旧の近道としてGit履歴を破壊しないでください。原因と影響範囲を調査可能な状態に保ちます。
|
package/docs/source-format-v1.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# SB3 expanded source format v1
|
|
2
2
|
|
|
3
|
+
[日本語版](ja/source-format-v1.md)
|
|
4
|
+
|
|
3
5
|
## Layout
|
|
4
6
|
|
|
5
7
|
```text
|
|
@@ -60,7 +62,13 @@ metadata can be added for an extension managed from GitHub.
|
|
|
60
62
|
"ref": "main",
|
|
61
63
|
"resolvedCommit": "0123456789abcdef0123456789abcdef01234567",
|
|
62
64
|
"artifact": "dist/example.js",
|
|
63
|
-
"integrity": "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
|
|
65
|
+
"integrity": "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
|
|
66
|
+
"apiManifest": {
|
|
67
|
+
"artifact": "dist/extension-manifest.json",
|
|
68
|
+
"path": "extensions/example.manifest.json",
|
|
69
|
+
"formatVersion": 1,
|
|
70
|
+
"integrity": "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB="
|
|
71
|
+
}
|
|
64
72
|
}
|
|
65
73
|
}
|
|
66
74
|
]
|
|
@@ -72,28 +80,43 @@ metadata can be added for an extension managed from GitHub.
|
|
|
72
80
|
- `resolvedCommit`: lowercase 40-character commit SHA used to obtain the current file
|
|
73
81
|
- `artifact`: JavaScript artifact path relative to the repository root
|
|
74
82
|
- `integrity`: SRI-form SHA-256 of the current file
|
|
83
|
+
- `apiManifest`: optional, opt-in API compatibility metadata
|
|
84
|
+
- `artifact`: API manifest path relative to the same GitHub repository
|
|
85
|
+
- `path`: required local path `extensions/<extensionId>.manifest.json`
|
|
86
|
+
- `formatVersion`: supported manifest format, currently `1`
|
|
87
|
+
- `integrity`: SRI-form SHA-256 of the installed manifest
|
|
75
88
|
|
|
76
89
|
Validation and builds verify managed extensions without accessing the network:
|
|
77
90
|
|
|
78
91
|
- The actual file SHA-256 matches `integrity`
|
|
79
92
|
- The file's `// ID: <extensionId>` header matches `id`
|
|
80
93
|
- The repository, ref, commit, and artifact path use safe forms
|
|
94
|
+
- When `apiManifest` exists, its JSON schema, ID, format version, path, and SHA-256 are valid
|
|
81
95
|
|
|
82
96
|
Re-importing an SB3 into an existing expanded source directory preserves `source` metadata for the
|
|
83
97
|
same ID and path. If the imported file does not match the recorded hash or ID, the import is rejected
|
|
84
98
|
without changing the existing output. A new import cannot infer provenance, so it does not create
|
|
85
99
|
`source` automatically.
|
|
86
100
|
|
|
87
|
-
`extensions sync` downloads
|
|
88
|
-
|
|
89
|
-
`ref` through the GitHub API
|
|
90
|
-
|
|
91
|
-
|
|
101
|
+
`extensions sync` downloads the JavaScript and optional API manifest using the immutable
|
|
102
|
+
`resolvedCommit` and restores local files only when their IDs and hashes match the existing metadata.
|
|
103
|
+
`extensions update` resolves `ref` through the GitHub API, downloads both artifacts from that same
|
|
104
|
+
commit, and compares a candidate API manifest with the installed contract. It updates
|
|
105
|
+
`resolvedCommit` and both integrity values only after compatibility and content validation succeed.
|
|
106
|
+
The expanded source is not changed until every selected entry has been downloaded and validated.
|
|
92
107
|
|
|
93
108
|
An extension ID migration changes the manifest `id` and `path`, known references in
|
|
94
109
|
`project.source.json`, and `extensions/<id>.js` in one transaction. When a managed extension is
|
|
95
110
|
migrated as part of `extensions update`, `artifact` when explicitly supplied, `resolvedCommit`, and
|
|
96
|
-
`integrity` are also updated for the new artifact.
|
|
111
|
+
`integrity` are also updated for the new artifact. An opt-in API manifest is compared after
|
|
112
|
+
normalizing the explicit old and new top-level IDs, saved under the new ID, and updated in the same
|
|
113
|
+
transaction. If its remote filename also changes, `--api-manifest-artifact` updates
|
|
114
|
+
`source.apiManifest.artifact` explicitly.
|
|
115
|
+
|
|
116
|
+
API manifest files are expanded-source validation inputs, not SB3 archive entries. They do not
|
|
117
|
+
change deterministic SB3 bytes. See
|
|
118
|
+
[`extension-api-compatibility.md`](extension-api-compatibility.md) for manifest v1, compatibility
|
|
119
|
+
classification, the explicit breaking-change override, and rollback.
|
|
97
120
|
|
|
98
121
|
### `extensionBundles`
|
|
99
122
|
|
package/docs/workflows.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# SB3 source-management workflows
|
|
2
2
|
|
|
3
|
+
[日本語版](ja/workflows.md)
|
|
4
|
+
|
|
3
5
|
This document describes the common workflow for managing a Scratch 3 or TurboWarp SB3 as expanded
|
|
4
6
|
source in Git and rebuilding a validated SB3. Each project repository should define its own editing,
|
|
5
7
|
testing, and distribution procedures.
|
|
@@ -87,8 +89,8 @@ operations, images, sounds, and embedded extension behavior.
|
|
|
87
89
|
## Managed embedded extensions
|
|
88
90
|
|
|
89
91
|
The `source` object in `embedded-extensions.json` can record the GitHub repository, tracked ref,
|
|
90
|
-
resolved commit, artifact path, and SHA-256.
|
|
91
|
-
complete schema.
|
|
92
|
+
resolved commit, artifact path, and SHA-256. It can also opt in to a versioned API manifest for static
|
|
93
|
+
update compatibility checks. See [`source-format-v1.md`](source-format-v1.md) for the complete schema.
|
|
92
94
|
|
|
93
95
|
The extension commands have the following roles:
|
|
94
96
|
|
|
@@ -118,7 +120,8 @@ sb3-toolchain check app
|
|
|
118
120
|
```
|
|
119
121
|
|
|
120
122
|
`sync` does not resolve a mutable branch or tag. It downloads from the recorded `resolvedCommit` and
|
|
121
|
-
replaces
|
|
123
|
+
replaces local files only when JavaScript and an optional API manifest match their recorded IDs and
|
|
124
|
+
SHA-256 values.
|
|
122
125
|
|
|
123
126
|
### Update a tracked ref
|
|
124
127
|
|
|
@@ -132,8 +135,21 @@ git diff -- app
|
|
|
132
135
|
Omitting the ID updates all managed extensions as one transaction. If any download or validation
|
|
133
136
|
fails, neither files nor metadata are changed.
|
|
134
137
|
|
|
135
|
-
|
|
136
|
-
|
|
138
|
+
When `source.apiManifest` is present, the update downloads JavaScript and the API manifest from the
|
|
139
|
+
same resolved commit. Compatible additions are reported. A removed block, changed block type,
|
|
140
|
+
argument-contract change, removed referenced menu, or `acceptReporters` change is rejected before
|
|
141
|
+
installation. Removing an unreferenced menu is compatible. After reviewing every reported path, an
|
|
142
|
+
intentionally breaking update requires both flags:
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
sb3-toolchain extensions update app EXTENSION_ID --allow-breaking-api --yes
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
See [`extension-api-compatibility.md`](extension-api-compatibility.md) for the versioned manifest
|
|
149
|
+
contract, classification table, default-off behavior, and rollback.
|
|
150
|
+
|
|
151
|
+
In an update PR, review `resolvedCommit`, JavaScript and manifest integrity, compatibility paths, and
|
|
152
|
+
both artifacts together, then test the extension's primary features in the generated SB3.
|
|
137
153
|
|
|
138
154
|
## Migrate an extension ID
|
|
139
155
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kubohiroya/sb3-toolchain",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "Git-friendly source management and deterministic builds for Scratch 3 and TurboWarp SB3 projects",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MPL-2.0",
|
|
@@ -25,6 +25,7 @@
|
|
|
25
25
|
"docs/",
|
|
26
26
|
"src/",
|
|
27
27
|
"README.md",
|
|
28
|
+
"README.ja.md",
|
|
28
29
|
"LICENSE"
|
|
29
30
|
],
|
|
30
31
|
"publishConfig": {
|
|
@@ -34,8 +35,8 @@
|
|
|
34
35
|
"packageManager": "pnpm@11.11.0",
|
|
35
36
|
"scripts": {
|
|
36
37
|
"lint": "eslint src bin test",
|
|
37
|
-
"format": "prettier --check .github bin docs src test package.json README.md tsconfig.json",
|
|
38
|
-
"format:write": "prettier --write .github bin docs src test package.json README.md tsconfig.json",
|
|
38
|
+
"format": "prettier --check .github bin docs src test package.json README.md README.ja.md tsconfig.json",
|
|
39
|
+
"format:write": "prettier --write .github bin docs src test package.json README.md README.ja.md tsconfig.json",
|
|
39
40
|
"typecheck": "tsc --project tsconfig.json",
|
|
40
41
|
"test": "node --test test/*.test.mjs",
|
|
41
42
|
"pack:check": "npm pack --dry-run --ignore-scripts",
|
package/src/cli.js
CHANGED
|
@@ -26,7 +26,7 @@ export function usage() {
|
|
|
26
26
|
sb3-toolchain build SOURCE_DIR --output OUTPUT.sb3 [--yes]
|
|
27
27
|
sb3-toolchain extensions status SOURCE_DIR
|
|
28
28
|
sb3-toolchain extensions sync SOURCE_DIR [--yes]
|
|
29
|
-
sb3-toolchain extensions update SOURCE_DIR [EXTENSION_ID] [--migrate-id NEW_ID] [--artifact PATH] [--yes]
|
|
29
|
+
sb3-toolchain extensions update SOURCE_DIR [EXTENSION_ID] [--migrate-id NEW_ID] [--artifact PATH] [--api-manifest-artifact PATH] [--allow-breaking-api --yes]
|
|
30
30
|
sb3-toolchain extensions migrate-id SOURCE_DIR --from OLD_ID --to NEW_ID [--yes]
|
|
31
31
|
sb3-toolchain extensions bundle SOURCE_DIR --id BUNDLE_ID --name NAME [EXTENSION_ID ...] [--yes]
|
|
32
32
|
sb3-toolchain extensions unbundle SOURCE_DIR BUNDLE_ID [--yes]
|
|
@@ -115,6 +115,8 @@ function parseBuildArguments(arguments_) {
|
|
|
115
115
|
}
|
|
116
116
|
|
|
117
117
|
function parseExtensionMutationArguments(action, arguments_) {
|
|
118
|
+
let allowBreakingApi = false;
|
|
119
|
+
let apiManifestArtifact;
|
|
118
120
|
let sourceDirectory;
|
|
119
121
|
let extensionId;
|
|
120
122
|
let migrateToId;
|
|
@@ -125,6 +127,9 @@ function parseExtensionMutationArguments(action, arguments_) {
|
|
|
125
127
|
const argument = arguments_[index];
|
|
126
128
|
if (argument === '--yes') {
|
|
127
129
|
yes = true;
|
|
130
|
+
} else if (argument === '--allow-breaking-api') {
|
|
131
|
+
assert(action === 'update', '--allow-breaking-api is only valid for extensions update.');
|
|
132
|
+
allowBreakingApi = true;
|
|
128
133
|
} else if (argument === '--migrate-id') {
|
|
129
134
|
assert(action === 'update', '--migrate-id is only valid for extensions update.');
|
|
130
135
|
migrateToId = takeValue(arguments_, index, '--migrate-id');
|
|
@@ -133,6 +138,10 @@ function parseExtensionMutationArguments(action, arguments_) {
|
|
|
133
138
|
assert(action === 'update', '--artifact is only valid for extensions update.');
|
|
134
139
|
sourceArtifact = takeValue(arguments_, index, '--artifact');
|
|
135
140
|
index += 1;
|
|
141
|
+
} else if (argument === '--api-manifest-artifact') {
|
|
142
|
+
assert(action === 'update', '--api-manifest-artifact is only valid for extensions update.');
|
|
143
|
+
apiManifestArtifact = takeValue(arguments_, index, '--api-manifest-artifact');
|
|
144
|
+
index += 1;
|
|
136
145
|
} else {
|
|
137
146
|
assert(!argument.startsWith('-'), `Unknown option: ${argument}`);
|
|
138
147
|
if (!sourceDirectory) {
|
|
@@ -158,8 +167,15 @@ function parseExtensionMutationArguments(action, arguments_) {
|
|
|
158
167
|
sourceArtifact === undefined || migrateToId !== undefined,
|
|
159
168
|
'--artifact requires --migrate-id.',
|
|
160
169
|
);
|
|
170
|
+
assert(
|
|
171
|
+
apiManifestArtifact === undefined || migrateToId !== undefined,
|
|
172
|
+
'--api-manifest-artifact requires --migrate-id.',
|
|
173
|
+
);
|
|
174
|
+
assert(!allowBreakingApi || yes, '--allow-breaking-api requires --yes.');
|
|
161
175
|
return {
|
|
162
176
|
action,
|
|
177
|
+
...(allowBreakingApi ? {allowBreakingApi} : {}),
|
|
178
|
+
...(apiManifestArtifact ? {apiManifestArtifact} : {}),
|
|
163
179
|
command: 'extensions',
|
|
164
180
|
extensionId,
|
|
165
181
|
migrateToId,
|
|
@@ -561,6 +577,8 @@ export async function runCli(
|
|
|
561
577
|
? await syncExtensions(operationOptions)
|
|
562
578
|
: await updateExtensions({
|
|
563
579
|
...operationOptions,
|
|
580
|
+
allowBreakingApi: options.allowBreakingApi,
|
|
581
|
+
apiManifestArtifact: options.apiManifestArtifact,
|
|
564
582
|
extensionId: options.extensionId,
|
|
565
583
|
migrateToId: options.migrateToId,
|
|
566
584
|
sourceArtifact: options.sourceArtifact,
|
|
@@ -580,6 +598,14 @@ export async function runCli(
|
|
|
580
598
|
log,
|
|
581
599
|
);
|
|
582
600
|
}
|
|
601
|
+
for (const compatibility of result.apiCompatibility) {
|
|
602
|
+
for (const change of compatibility.changes) {
|
|
603
|
+
log(
|
|
604
|
+
`API ${compatibility.id}: ${change.breaking ? 'breaking' : 'compatible'} ` +
|
|
605
|
+
`${change.kind} ${change.path}`,
|
|
606
|
+
);
|
|
607
|
+
}
|
|
608
|
+
}
|
|
583
609
|
if (result.rollbackCleanupWarning) log(result.rollbackCleanupWarning);
|
|
584
610
|
return;
|
|
585
611
|
}
|