@kubohiroya/sb3-toolchain 0.3.0 → 0.5.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 +151 -0
- package/README.md +9 -6
- package/docs/extension-bundles.md +45 -6
- package/docs/extension-id-migration.md +2 -0
- package/docs/ja/extension-bundles.md +465 -0
- package/docs/ja/extension-id-migration.md +69 -0
- package/docs/ja/source-format-v1.md +205 -0
- package/docs/ja/workflows.md +265 -0
- package/docs/source-format-v1.md +28 -9
- package/docs/workflows.md +33 -13
- package/package.json +4 -3
- package/src/build.js +8 -2
- package/src/cli.js +31 -4
- package/src/constants.js +1 -1
- package/src/extension-bundle.js +32 -1
- package/src/extension-dependencies.js +32 -19
- package/src/extension-sync.js +109 -20
- package/src/index.js +1 -0
- package/src/npm-extension-source.js +111 -0
- package/src/source.js +16 -2
- package/src/turbowarp-clean-up.js +295 -0
|
@@ -0,0 +1,205 @@
|
|
|
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
|
+
npmパッケージから管理する機能拡張には、任意の`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
|
+
完全固定したnpm依存では、GitHub固有のフィールドをパッケージ情報へ置き換えます。
|
|
78
|
+
|
|
79
|
+
```json
|
|
80
|
+
{
|
|
81
|
+
"provider": "npm",
|
|
82
|
+
"package": "@owner/example-extension",
|
|
83
|
+
"version": "1.2.3",
|
|
84
|
+
"artifact": "dist/example.js",
|
|
85
|
+
"integrity": "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
- `provider`: `github`または`npm`
|
|
90
|
+
- `repository`: `<owner>/<repository>`形式のGitHubリポジトリ
|
|
91
|
+
- `ref`: 更新候補として追跡するブランチ、タグ、またはコミット
|
|
92
|
+
- `resolvedCommit`: 現在のファイルの取得に使用した、小文字40文字のコミットSHA
|
|
93
|
+
- `package`: スコープを含む完全なnpmパッケージ名
|
|
94
|
+
- `version`: インストール済み`package.json`に記録された完全固定のsemantic version。範囲指定は不可
|
|
95
|
+
- `artifact`: リポジトリまたはnpmパッケージのルートを基準にしたJavaScript成果物のパス
|
|
96
|
+
- `integrity`: 現在のファイルのSRI形式SHA-256
|
|
97
|
+
- `apiManifest`: 任意で使用するAPI互換性メタデータ
|
|
98
|
+
- `artifact`: 同じGitHubリポジトリを基準にしたAPIマニフェストのパス
|
|
99
|
+
- `path`: 必須のローカルパス`extensions/<extensionId>.manifest.json`
|
|
100
|
+
- `formatVersion`: 対応するマニフェスト形式。現在は`1`
|
|
101
|
+
- `integrity`: インストール済みマニフェストのSRI形式SHA-256
|
|
102
|
+
|
|
103
|
+
検証とビルドでは、ネットワークへ接続せずに管理対象機能拡張を検証します。
|
|
104
|
+
|
|
105
|
+
- 実ファイルのSHA-256が`integrity`と一致する
|
|
106
|
+
- ファイルの`// ID: <extensionId>`ヘッダーが`id`と一致する
|
|
107
|
+
- GitHubリポジトリ、ref、コミット、npmパッケージ、完全固定バージョン、成果物パスが安全な形式である
|
|
108
|
+
- `apiManifest`が存在する場合、そのJSONスキーマ、ID、形式バージョン、パス、SHA-256が有効である
|
|
109
|
+
|
|
110
|
+
既存の展開ソースディレクトリへSB3を再importすると、同じIDとパスの`source`メタデータが保持されます。
|
|
111
|
+
importしたファイルが記録済みのハッシュまたはIDと一致しない場合、既存の出力を変更せずにimportを拒否します。
|
|
112
|
+
新規importでは来歴を推測できないため、`source`は自動作成されません。
|
|
113
|
+
|
|
114
|
+
GitHub sourceの`extensions sync`は変更不能な`resolvedCommit`からJavaScriptと任意のAPIマニフェストを
|
|
115
|
+
ダウンロードします。npm sourceでは、最寄りの親`node_modules`にインストールされた完全固定パッケージから、
|
|
116
|
+
ネットワークを使わずに読み込みます。どちらもIDとハッシュが既存メタデータに一致する場合だけ復元します。
|
|
117
|
+
パッケージマネージャーで新しい完全固定npmバージョンを導入した後に`extensions update`を実行すると、成果物を
|
|
118
|
+
コピーして`version`とintegrityを更新します。GitHub更新では`ref`を解決して`resolvedCommit`を更新します。
|
|
119
|
+
どちらも候補APIマニフェストを事前に比較し、選択した全項目の検証が終わるまで展開ソースを変更しません。
|
|
120
|
+
|
|
121
|
+
機能拡張IDの移行では、マニフェストの`id`と`path`、`project.source.json`内の既知の参照、
|
|
122
|
+
`extensions/<id>.js`を1回のトランザクションで変更します。`extensions update`の一部として管理対象機能拡張を
|
|
123
|
+
移行する場合は、明示的に指定した`artifact`、`resolvedCommit`、`integrity`も新しい成果物に合わせて更新します。
|
|
124
|
+
任意のAPIマニフェストは、明示した旧IDと新IDのトップレベルIDを正規化してから比較し、新しいIDで保存して、
|
|
125
|
+
同じトランザクションで更新します。リモートファイル名も変わる場合は、`--api-manifest-artifact`で
|
|
126
|
+
`source.apiManifest.artifact`を明示的に更新します。
|
|
127
|
+
|
|
128
|
+
APIマニフェストファイルは展開ソースの検証入力であり、SB3アーカイブのエントリではありません。決定的なSB3の
|
|
129
|
+
バイト列は変わりません。マニフェストv1、互換性分類、破壊的変更の明示的な許可、ロールバックについては、
|
|
130
|
+
[`extension-api-compatibility.md`](extension-api-compatibility.md)を参照してください。
|
|
131
|
+
|
|
132
|
+
### `extensionBundles`
|
|
133
|
+
|
|
134
|
+
任意の`extensionBundles`配列を追加すると、複数の個別機能拡張を、生成SB3内だけで1つの権限単位にできます。
|
|
135
|
+
|
|
136
|
+
```json
|
|
137
|
+
{
|
|
138
|
+
"formatVersion": 1,
|
|
139
|
+
"extensions": [
|
|
140
|
+
{
|
|
141
|
+
"id": "extensionone",
|
|
142
|
+
"path": "extensions/extensionone.js",
|
|
143
|
+
"mediaType": "text/javascript",
|
|
144
|
+
"parameters": [],
|
|
145
|
+
"encoding": "base64"
|
|
146
|
+
},
|
|
147
|
+
{
|
|
148
|
+
"id": "extensiontwo",
|
|
149
|
+
"path": "extensions/extensiontwo.js",
|
|
150
|
+
"mediaType": "text/javascript",
|
|
151
|
+
"parameters": [],
|
|
152
|
+
"encoding": "base64"
|
|
153
|
+
}
|
|
154
|
+
],
|
|
155
|
+
"extensionBundles": [
|
|
156
|
+
{
|
|
157
|
+
"id": "projectbundle",
|
|
158
|
+
"name": "Project Extension Bundle",
|
|
159
|
+
"members": ["extensionone", "extensiontwo"]
|
|
160
|
+
}
|
|
161
|
+
]
|
|
162
|
+
}
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
- `id`: TurboWarpの`[a-z0-9]+`形式で、個別機能拡張と衝突しない複合機能拡張ID
|
|
166
|
+
- `name`: 権限確認と機能拡張カテゴリに表示される単一行の名前
|
|
167
|
+
- `members`: 2つ以上の個別機能拡張ID。順序によってブロックとメニューの合成順が決まる。パレットでは、
|
|
168
|
+
メタデータを持つ装飾済みbundle LABEL見出しとグループ間の二重separatorが追加される一方、元の機能拡張の
|
|
169
|
+
LABELエントリとseparatorは変更されない
|
|
170
|
+
|
|
171
|
+
1つのメンバーを複数のbundleに所属させることはできません。個別エントリ、個別JavaScript、`source`、
|
|
172
|
+
`project.source.json`が引き続き信頼できる情報源です。`build`は各元opcodeに`memberId + "__"`を加え、
|
|
173
|
+
出力側の`project.json`のopcode、`extensions`、`extensionURLs`、機能拡張ストレージだけをbundle IDに変更します。
|
|
174
|
+
埋め込まれるbundle JavaScriptのdata URLは1つです。
|
|
175
|
+
|
|
176
|
+
bundle JavaScriptの末尾には、元の個別data URLと機能拡張の順序を格納した形式1の復元カプセルが含まれます。
|
|
177
|
+
設定を削除するか、そのカプセルを含む生成SB3に対して`extensions unbundle`を実行すると、通常の出力へ
|
|
178
|
+
復元できます。互換性契約と復元手順については、[`extension-bundles.md`](extension-bundles.md)を参照してください。
|
|
179
|
+
|
|
180
|
+
## アセット
|
|
181
|
+
|
|
182
|
+
`assets/`には、`project.source.json`から参照されるコスチュームと音声が含まれます。各ファイル名は
|
|
183
|
+
`<assetId>.<dataFormat>`であり、`assetId`は内容のMD5と一致しなければなりません。未参照、欠落、余分な
|
|
184
|
+
ファイルはいずれも検証エラーです。
|
|
185
|
+
|
|
186
|
+
## 決定的出力
|
|
187
|
+
|
|
188
|
+
- ZIPエントリは`archiveEntries`に従う
|
|
189
|
+
- ZIPタイムスタンプは1980-01-01 00:00:00に固定
|
|
190
|
+
- 圧縮レベルは6に固定
|
|
191
|
+
- `project.json`は末尾に改行を持つ最小JSONとして格納
|
|
192
|
+
- ソース形式のバージョン、入力ファイル、ツールのバージョンが同じなら、同じバイト列を生成
|
|
193
|
+
|
|
194
|
+
## 安全性
|
|
195
|
+
|
|
196
|
+
- 絶対パス、`\`、空の構成要素、`.`、`..`を含むZIPエントリを拒否
|
|
197
|
+
- ソース入力としてシンボリックリンクと特殊ファイルを拒否
|
|
198
|
+
- ファイルシステムルート、Gitリポジトリルート、その祖先、`.git/`をimport先として拒否
|
|
199
|
+
- 認識できない既存ディレクトリを上書きしない
|
|
200
|
+
- 2段階の明示的な許可なしにGit管理対象の変更を破棄しない
|
|
201
|
+
- 中断された置換のロールバック領域が存在するときは、自動的に上書きしない
|
|
202
|
+
- 管理対象機能拡張のコミット、SHA-256、機能拡張IDをオフラインで検証
|
|
203
|
+
- bundle時に個別JavaScriptと来歴を保持し、互換性を確立できない契約を拒否
|
|
204
|
+
- GitHubからはHTTPSだけで取得し、リダイレクトを拒否してサイズを制限し、ダウンロードしたJavaScriptは
|
|
205
|
+
決して実行しない
|
|
@@ -0,0 +1,265 @@
|
|
|
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へ書き込む前に、全ターゲットのトップレベルスクリプトを整理するには、明示的にオプションを指定します。
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
sb3-toolchain build app --output dist/project.sb3 --clean-up-blocks
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
`--clean-up-blocks`は、TurboWarpの「きれいにする」配置と同じ開始座標、列の判定範囲、余白を使用します。
|
|
94
|
+
ブロック、変数、リスト、コメントは削除せず、ブロックに付いたコメントはスクリプトと一緒に移動します。変換する
|
|
95
|
+
のは生成物内の`project.json`だけであり、展開ソースは変更しません。生成SB3をTurboWarpで開いた後は座標変更を
|
|
96
|
+
元に戻せない場合があります。ソース座標へ戻すにはこのオプションを外して再ビルドしてください。
|
|
97
|
+
|
|
98
|
+
プロジェクト固有のテストに加えて、生成SB3をTurboWarpで開き、起動、主要な操作、画像、音声、埋め込み
|
|
99
|
+
機能拡張の動作を確認してください。
|
|
100
|
+
|
|
101
|
+
## 管理対象の埋め込み機能拡張
|
|
102
|
+
|
|
103
|
+
`embedded-extensions.json`の`source`オブジェクトには、GitHubコミットの来歴またはインストール済みnpm
|
|
104
|
+
パッケージの完全固定バージョンと、成果物パス、SHA-256を記録できます。更新時の静的互換性検査に使用する
|
|
105
|
+
バージョン付きAPIマニフェストも任意で設定できます。完全なスキーマは
|
|
106
|
+
[`source-format-v1.md`](source-format-v1.md)を参照してください。
|
|
107
|
+
|
|
108
|
+
機能拡張コマンドの役割は次のとおりです。
|
|
109
|
+
|
|
110
|
+
| コマンド | ネットワーク | refの解決 | メタデータ更新 | 目的 |
|
|
111
|
+
| ----------------------- | ------------ | ---------- | -------------- | -------------------------------------- |
|
|
112
|
+
| `extensions status` | GitHubのみ | GitHubのみ | なし | 上流または導入済みパッケージを確認 |
|
|
113
|
+
| `extensions sync` | GitHubのみ | なし | なし | 宣言したsourceからファイルを復元 |
|
|
114
|
+
| `extensions update` | GitHubのみ | GitHubのみ | あり | 上流または導入済みパッケージを採用 |
|
|
115
|
+
| `extensions migrate-id` | なし | なし | ID/参照 | プロジェクトで使用中の機能拡張IDを移行 |
|
|
116
|
+
| `extensions bundle` | なし | なし | bundle設定 | 機能拡張を1つの権限単位へ統合 |
|
|
117
|
+
| `extensions unbundle` | なし | なし | 設定またはSB3 | 個別機能拡張を使用する出力へ復元 |
|
|
118
|
+
|
|
119
|
+
### 更新の確認
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
sb3-toolchain extensions status app
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
`status`はローカルファイルを変更しません。GitHub sourceでは追跡対象refと`resolvedCommit`を比較します。
|
|
126
|
+
npm sourceでは、宣言した完全固定バージョンとインストール済みパッケージをネットワークなしで比較します。
|
|
127
|
+
|
|
128
|
+
### 固定したコミットからの復元
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
sb3-toolchain extensions sync app
|
|
132
|
+
sb3-toolchain check app
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
`sync`は変更可能なブランチやタグを解決しません。GitHub sourceは`resolvedCommit`からダウンロードし、
|
|
136
|
+
npm sourceは最寄りの親`node_modules`へ導入済みの完全固定パッケージから読み込みます。JavaScriptと任意の
|
|
137
|
+
APIマニフェストが記録済みIDおよびSHA-256値に一致する場合に限り、ローカルファイルを置き換えます。
|
|
138
|
+
|
|
139
|
+
### 追跡対象refの更新
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
sb3-toolchain extensions update app
|
|
143
|
+
sb3-toolchain extensions update app EXTENSION_ID
|
|
144
|
+
sb3-toolchain check app
|
|
145
|
+
git diff -- app
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
IDを省略すると、管理対象の全機能拡張を1回のトランザクションで更新します。ダウンロードまたは検証が1つでも
|
|
149
|
+
失敗した場合、ファイルもメタデータも変更しません。
|
|
150
|
+
|
|
151
|
+
npm sourceでは、最初にプロジェクトのパッケージマネージャーで新しい完全固定バージョンを導入し、続けて
|
|
152
|
+
`extensions status`と`extensions update`を実行します。updateは導入済み成果物をコピーし、パッケージの
|
|
153
|
+
`version`とintegrityを記録します。sb3-toolchain自身はnpm registryへ問い合わせません。
|
|
154
|
+
|
|
155
|
+
`source.apiManifest`が存在する場合、同じ解決済みコミットからJavaScriptとAPIマニフェストをダウンロードします。
|
|
156
|
+
互換性のある追加は報告されます。ブロックの削除、ブロック種別の変更、引数契約の変更、参照中メニューの削除、
|
|
157
|
+
`acceptReporters`の変更は、インストール前に拒否されます。未参照メニューの削除には互換性があります。
|
|
158
|
+
報告されたすべてのパスを確認した後、意図的な破壊的更新には両方のフラグが必要です。
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
sb3-toolchain extensions update app EXTENSION_ID --allow-breaking-api --yes
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
バージョン付きマニフェスト契約、分類表、既定OFFの動作、ロールバックについては、
|
|
165
|
+
[`extension-api-compatibility.md`](extension-api-compatibility.md)を参照してください。
|
|
166
|
+
|
|
167
|
+
更新PRでは、`resolvedCommit`またはnpmの`version`、JavaScriptとマニフェストのintegrity、互換性パス、
|
|
168
|
+
両成果物をまとめて確認し、生成SB3で機能拡張の主要機能をテストします。
|
|
169
|
+
|
|
170
|
+
## 機能拡張IDの移行
|
|
171
|
+
|
|
172
|
+
機能拡張IDはopcodeとmonitorに保存されるため、ファイル名やマニフェストだけを手作業で変更しないでください。
|
|
173
|
+
dry runから始め、分類済み参照と未分類参照の両方を確認します。
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
sb3-toolchain extensions migrate-id app --from OLD_ID --to NEW_ID
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
新しいIDを宣言するJavaScriptを用意して結果を確認し、適用します。
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
sb3-toolchain extensions migrate-id app --from OLD_ID --to NEW_ID --yes
|
|
183
|
+
sb3-toolchain check app
|
|
184
|
+
git diff -- app
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
GitHub管理対象機能拡張では、上流成果物の更新とID移行を1回のトランザクションにできます。
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
sb3-toolchain extensions update app OLD_ID \
|
|
191
|
+
--migrate-id NEW_ID \
|
|
192
|
+
--artifact dist/NEW_ID.js
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
上流の成果物パスも変わった場合に限り`--artifact`を指定します。影響するスキーマ、衝突検査、未分類参照、
|
|
196
|
+
ロールバックについては、[`extension-id-migration.md`](extension-id-migration.md)を参照してください。
|
|
197
|
+
|
|
198
|
+
## unsandboxed権限を1回の確認に統合
|
|
199
|
+
|
|
200
|
+
複数の埋め込み機能拡張を含むプロジェクトでは、静的bundleを任意で使用できます。元のJavaScript、ID、opcode、
|
|
201
|
+
来歴は変更されず、ビルド出力だけが1つの複合機能拡張へ変換されます。
|
|
202
|
+
|
|
203
|
+
```bash
|
|
204
|
+
sb3-toolchain extensions bundle app \
|
|
205
|
+
--id projectbundle \
|
|
206
|
+
--name "Project Extension Bundle" \
|
|
207
|
+
extensionone extensiontwo
|
|
208
|
+
sb3-toolchain extensions bundle app \
|
|
209
|
+
--id projectbundle \
|
|
210
|
+
--name "Project Extension Bundle" \
|
|
211
|
+
extensionone extensiontwo \
|
|
212
|
+
--yes
|
|
213
|
+
sb3-toolchain check app
|
|
214
|
+
sb3-toolchain build app --output dist/project.sb3 --yes
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
プロジェクトレベルの自動テストと実際のTurboWarpでのスモークテストを使用し、bundle前後での同等な動作、
|
|
218
|
+
1回だけの権限確認、保存後の再読み込み成功を検証します。問題がある場合は、保持されている個別機能拡張へ
|
|
219
|
+
復元します。
|
|
220
|
+
|
|
221
|
+
```bash
|
|
222
|
+
sb3-toolchain extensions unbundle app projectbundle
|
|
223
|
+
sb3-toolchain extensions unbundle app projectbundle --yes
|
|
224
|
+
sb3-toolchain check app
|
|
225
|
+
sb3-toolchain build app --output dist/project.sb3 --yes
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
展開ソースが利用できない場合でも、このバージョンのツールチェーンで生成したSB3は直接unbundleできます。
|
|
229
|
+
最初のコマンドはdry runで、`--yes`を指定した場合に限り出力を書き込みます。
|
|
230
|
+
|
|
231
|
+
```bash
|
|
232
|
+
sb3-toolchain extensions unbundle \
|
|
233
|
+
dist/project.sb3 projectbundle \
|
|
234
|
+
--output dist/project.unbundled.sb3
|
|
235
|
+
sb3-toolchain extensions unbundle \
|
|
236
|
+
dist/project.sb3 projectbundle \
|
|
237
|
+
--output dist/project.unbundled.sb3 \
|
|
238
|
+
--yes
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
互換性契約、ソースコメント、opcodeとストレージの変換、直接unbundleの制限、再import時の注意事項については、
|
|
242
|
+
[`extension-bundles.md`](extension-bundles.md)を参照してください。
|
|
243
|
+
|
|
244
|
+
## CIと配布
|
|
245
|
+
|
|
246
|
+
依存関係のバージョンを固定し、CIで少なくとも次のコマンドを実行します。
|
|
247
|
+
|
|
248
|
+
```bash
|
|
249
|
+
sb3-toolchain check app
|
|
250
|
+
sb3-toolchain build app --output dist/project.sb3 --yes
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
プロジェクトレベルの自動テストと手動検証に合格したSB3だけを配布してください。ネットワーク状態が入力になって
|
|
254
|
+
しまうため、リリースビルドの一部として`sync`や`update`を暗黙的に実行しないでください。更新は独立した
|
|
255
|
+
レビュー可能な変更として行い、固定した展開ソースを先にコミットします。
|
|
256
|
+
|
|
257
|
+
## 失敗時の対応
|
|
258
|
+
|
|
259
|
+
- コマンドが置換を拒否した場合は、再試行する前に`git status`と該当する差分を確認する
|
|
260
|
+
- `.<output-name>.rollback-*`が残っている場合は、復元または削除を決める前に現在の出力と比較する
|
|
261
|
+
- 機能拡張更新が途中で失敗した場合は、再試行する前に`git diff`を確認する
|
|
262
|
+
- merge済み変更はプロジェクトコミットをrevertし、ソース、成果物、来歴をまとめて元に戻す
|
|
263
|
+
- 公開済みSB3を置き換える場合は、プロジェクトのリリースポリシーに従い、履歴を保持する
|
|
264
|
+
|
|
265
|
+
復旧の近道として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
|
|
@@ -42,7 +44,7 @@ reconstruct the data URL.
|
|
|
42
44
|
## `embedded-extensions.json`
|
|
43
45
|
|
|
44
46
|
This file records embedded extension data URL information and extraction paths. Optional `source`
|
|
45
|
-
metadata can be added for an extension managed from GitHub.
|
|
47
|
+
metadata can be added for an extension managed from GitHub or an installed npm package.
|
|
46
48
|
|
|
47
49
|
```json
|
|
48
50
|
{
|
|
@@ -73,10 +75,25 @@ metadata can be added for an extension managed from GitHub.
|
|
|
73
75
|
}
|
|
74
76
|
```
|
|
75
77
|
|
|
78
|
+
For an exact npm dependency, replace the GitHub-specific fields with the package identity:
|
|
79
|
+
|
|
80
|
+
```json
|
|
81
|
+
{
|
|
82
|
+
"provider": "npm",
|
|
83
|
+
"package": "@owner/example-extension",
|
|
84
|
+
"version": "1.2.3",
|
|
85
|
+
"artifact": "dist/example.js",
|
|
86
|
+
"integrity": "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
- `provider`: `github` or `npm`
|
|
76
91
|
- `repository`: GitHub repository in `<owner>/<repository>` form
|
|
77
92
|
- `ref`: branch, tag, or commit to track for update candidates
|
|
78
93
|
- `resolvedCommit`: lowercase 40-character commit SHA used to obtain the current file
|
|
79
|
-
- `
|
|
94
|
+
- `package`: exact npm package name, including its scope when applicable
|
|
95
|
+
- `version`: exact semantic version recorded in the installed package's `package.json`; ranges are not accepted
|
|
96
|
+
- `artifact`: JavaScript artifact path relative to the repository or npm package root
|
|
80
97
|
- `integrity`: SRI-form SHA-256 of the current file
|
|
81
98
|
- `apiManifest`: optional, opt-in API compatibility metadata
|
|
82
99
|
- `artifact`: API manifest path relative to the same GitHub repository
|
|
@@ -88,7 +105,7 @@ Validation and builds verify managed extensions without accessing the network:
|
|
|
88
105
|
|
|
89
106
|
- The actual file SHA-256 matches `integrity`
|
|
90
107
|
- The file's `// ID: <extensionId>` header matches `id`
|
|
91
|
-
- The repository, ref, commit, and artifact path use safe forms
|
|
108
|
+
- The GitHub repository, ref, commit, npm package, exact version, and artifact path use safe forms
|
|
92
109
|
- When `apiManifest` exists, its JSON schema, ID, format version, path, and SHA-256 are valid
|
|
93
110
|
|
|
94
111
|
Re-importing an SB3 into an existing expanded source directory preserves `source` metadata for the
|
|
@@ -96,12 +113,14 @@ same ID and path. If the imported file does not match the recorded hash or ID, t
|
|
|
96
113
|
without changing the existing output. A new import cannot infer provenance, so it does not create
|
|
97
114
|
`source` automatically.
|
|
98
115
|
|
|
99
|
-
`extensions sync` downloads the JavaScript and optional API manifest using the
|
|
100
|
-
`resolvedCommit
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
`
|
|
104
|
-
|
|
116
|
+
For GitHub sources, `extensions sync` downloads the JavaScript and optional API manifest using the
|
|
117
|
+
immutable `resolvedCommit`. For npm sources, it reads them from the exact package installed in the
|
|
118
|
+
nearest ancestor `node_modules` directory without network access. Both paths restore local files only
|
|
119
|
+
when IDs and hashes match existing metadata. After the package manager installs a newer exact npm
|
|
120
|
+
version, `extensions update` copies its artifacts and updates `version` and integrity metadata.
|
|
121
|
+
GitHub updates instead resolve `ref` and update `resolvedCommit`. Candidate API manifests are compared
|
|
122
|
+
before either type is installed. The expanded source remains unchanged until every selected entry has
|
|
123
|
+
been validated.
|
|
105
124
|
|
|
106
125
|
An extension ID migration changes the manifest `id` and `path`, known references in
|
|
107
126
|
`project.source.json`, and `extensions/<id>.js` in one transaction. When a managed extension is
|
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.
|
|
@@ -81,22 +83,35 @@ expanded format, embedded extension IDs, and SHA-256 hashes using only local inp
|
|
|
81
83
|
and expanded source produce a bit-for-bit identical SB3. An identical existing output is left
|
|
82
84
|
untouched. A differing output requires replacement confirmation or `--yes`.
|
|
83
85
|
|
|
86
|
+
To arrange the top-level scripts in every target before writing the generated SB3, opt in explicitly:
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
sb3-toolchain build app --output dist/project.sb3 --clean-up-blocks
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
`--clean-up-blocks` uses TurboWarp's cleaned-layout starting coordinates, column grouping tolerance,
|
|
93
|
+
and spacing. It preserves blocks, variables, lists, and comments; attached comments move with their
|
|
94
|
+
scripts. Only the generated `project.json` is transformed, so the expanded source remains unchanged.
|
|
95
|
+
TurboWarp might not be able to undo these coordinate changes after opening the generated SB3. Omit
|
|
96
|
+
the option and rebuild to roll back to the source coordinates.
|
|
97
|
+
|
|
84
98
|
In addition to project-specific tests, open the generated SB3 in TurboWarp and verify startup, primary
|
|
85
99
|
operations, images, sounds, and embedded extension behavior.
|
|
86
100
|
|
|
87
101
|
## Managed embedded extensions
|
|
88
102
|
|
|
89
|
-
The `source` object in `embedded-extensions.json` can record
|
|
90
|
-
|
|
91
|
-
|
|
103
|
+
The `source` object in `embedded-extensions.json` can record either GitHub commit provenance or an
|
|
104
|
+
exact installed npm package version, together with its artifact path and SHA-256. It can also opt in
|
|
105
|
+
to a versioned API manifest for static update compatibility checks. See
|
|
106
|
+
[`source-format-v1.md`](source-format-v1.md) for the complete schema.
|
|
92
107
|
|
|
93
108
|
The extension commands have the following roles:
|
|
94
109
|
|
|
95
110
|
| Command | Network | Resolve ref | Metadata update | Purpose |
|
|
96
111
|
| ----------------------- | ------- | ----------- | --------------- | ------------------------------------------- |
|
|
97
|
-
| `extensions status` |
|
|
98
|
-
| `extensions sync` |
|
|
99
|
-
| `extensions update` |
|
|
112
|
+
| `extensions status` | GitHub | GitHub | No | Check the upstream or installed package |
|
|
113
|
+
| `extensions sync` | GitHub | No | No | Restore files from the declared source |
|
|
114
|
+
| `extensions update` | GitHub | GitHub | Yes | Adopt the upstream or installed package |
|
|
100
115
|
| `extensions migrate-id` | No | No | IDs/references | Migrate an extension ID used by the project |
|
|
101
116
|
| `extensions bundle` | No | No | Bundle config | Combine extensions into one permission unit |
|
|
102
117
|
| `extensions unbundle` | No | No | Config or SB3 | Restore output with individual extensions |
|
|
@@ -107,8 +122,8 @@ The extension commands have the following roles:
|
|
|
107
122
|
sb3-toolchain extensions status app
|
|
108
123
|
```
|
|
109
124
|
|
|
110
|
-
`status` does not change local files.
|
|
111
|
-
|
|
125
|
+
`status` does not change local files. GitHub sources compare the tracked ref with `resolvedCommit`.
|
|
126
|
+
npm sources compare the declared exact version with the installed package without network access.
|
|
112
127
|
|
|
113
128
|
### Restore from a pinned commit
|
|
114
129
|
|
|
@@ -117,9 +132,9 @@ sb3-toolchain extensions sync app
|
|
|
117
132
|
sb3-toolchain check app
|
|
118
133
|
```
|
|
119
134
|
|
|
120
|
-
`sync` does not resolve a mutable branch or tag.
|
|
121
|
-
|
|
122
|
-
SHA-256 values.
|
|
135
|
+
`sync` does not resolve a mutable branch or tag. GitHub sources download from `resolvedCommit`; npm
|
|
136
|
+
sources read from the exact package installed in the nearest ancestor `node_modules`. It replaces
|
|
137
|
+
local files only when JavaScript and an optional API manifest match recorded IDs and SHA-256 values.
|
|
123
138
|
|
|
124
139
|
### Update a tracked ref
|
|
125
140
|
|
|
@@ -133,6 +148,10 @@ git diff -- app
|
|
|
133
148
|
Omitting the ID updates all managed extensions as one transaction. If any download or validation
|
|
134
149
|
fails, neither files nor metadata are changed.
|
|
135
150
|
|
|
151
|
+
For an npm source, first use the project package manager to install a new exact dependency version,
|
|
152
|
+
then run `extensions status` and `extensions update`. The update copies the installed artifacts and
|
|
153
|
+
records their package `version` and integrity. It never queries the npm registry itself.
|
|
154
|
+
|
|
136
155
|
When `source.apiManifest` is present, the update downloads JavaScript and the API manifest from the
|
|
137
156
|
same resolved commit. Compatible additions are reported. A removed block, changed block type,
|
|
138
157
|
argument-contract change, removed referenced menu, or `acceptReporters` change is rejected before
|
|
@@ -146,8 +165,9 @@ sb3-toolchain extensions update app EXTENSION_ID --allow-breaking-api --yes
|
|
|
146
165
|
See [`extension-api-compatibility.md`](extension-api-compatibility.md) for the versioned manifest
|
|
147
166
|
contract, classification table, default-off behavior, and rollback.
|
|
148
167
|
|
|
149
|
-
In an update PR, review `resolvedCommit`, JavaScript and manifest integrity,
|
|
150
|
-
both artifacts together, then test the extension's primary features in the
|
|
168
|
+
In an update PR, review `resolvedCommit` or npm `version`, JavaScript and manifest integrity,
|
|
169
|
+
compatibility paths, and both artifacts together, then test the extension's primary features in the
|
|
170
|
+
generated SB3.
|
|
151
171
|
|
|
152
172
|
## Migrate an extension ID
|
|
153
173
|
|