@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
package/README.ja.md
ADDED
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
# sb3-toolchain
|
|
2
|
+
|
|
3
|
+
[English](README.md)
|
|
4
|
+
|
|
5
|
+
Scratch 3およびTurboWarpの`.sb3`プロジェクトを、Gitで差分を確認できる展開ソースとして管理し、
|
|
6
|
+
同じ入力からバイト単位で同一のSB3ファイルを再ビルドするためのNode.jsツールチェーンです。
|
|
7
|
+
|
|
8
|
+
## 特長
|
|
9
|
+
|
|
10
|
+
- SB3を、整形済みの`project.source.json`、アセット、埋め込み機能拡張へ安全に展開
|
|
11
|
+
- アセット参照、MD5ハッシュ、ZIPエントリ、埋め込み機能拡張の対応関係を検証
|
|
12
|
+
- GitHubでホストされる埋め込み機能拡張のコミットとSHA-256ハッシュを記録し、オフラインで検証
|
|
13
|
+
- 埋め込みJavaScriptを置き換える前に、バージョン付き機能拡張APIマニフェストを任意で比較
|
|
14
|
+
- 元のJavaScriptを削除せず、複数の機能拡張を1つの権限単位へ静的にbundleし、展開ソースまたは
|
|
15
|
+
bundle済みSB3から復元
|
|
16
|
+
- ZIPエントリ順、タイムスタンプ、圧縮設定を固定した決定的ビルド
|
|
17
|
+
- import時に未コミットのGit変更を保護
|
|
18
|
+
- トランザクションによる置換とロールバックで既存出力を保護
|
|
19
|
+
- CLIとJavaScript APIの両方を提供
|
|
20
|
+
|
|
21
|
+
## 必要環境
|
|
22
|
+
|
|
23
|
+
- Node.js 22.12.0以降
|
|
24
|
+
- pnpm 11
|
|
25
|
+
|
|
26
|
+
## インストール
|
|
27
|
+
|
|
28
|
+
再現可能なインストールのため、検証済みのnpmバージョンを固定します。
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.4.0
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## クイックスタート
|
|
35
|
+
|
|
36
|
+
TurboWarpで保存したSB3を展開して検証し、再ビルドします。
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
sb3-toolchain import tmp/project.sb3 --output app
|
|
40
|
+
sb3-toolchain check app
|
|
41
|
+
sb3-toolchain build app --output dist/project.sb3
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
プロジェクトリポジトリに推奨する信頼できる唯一の情報源、再import、置換保護、機能拡張更新、CIの
|
|
45
|
+
ワークフローについては、[`docs/ja/workflows.md`](docs/ja/workflows.md)を参照してください。
|
|
46
|
+
|
|
47
|
+
## JavaScript API
|
|
48
|
+
|
|
49
|
+
```js
|
|
50
|
+
import {readFile} from 'node:fs/promises';
|
|
51
|
+
|
|
52
|
+
import {
|
|
53
|
+
buildSb3,
|
|
54
|
+
bundleExtensions,
|
|
55
|
+
createDeterministicSb3,
|
|
56
|
+
extensionIntegrity,
|
|
57
|
+
extensionStatus,
|
|
58
|
+
importSb3,
|
|
59
|
+
migrateExtensionId,
|
|
60
|
+
planExtensionIdMigration,
|
|
61
|
+
syncExtensions,
|
|
62
|
+
unbundleSb3,
|
|
63
|
+
unbundleExtensions,
|
|
64
|
+
updateExtensions,
|
|
65
|
+
validateSb3Source,
|
|
66
|
+
} from '@kubohiroya/sb3-toolchain';
|
|
67
|
+
|
|
68
|
+
await importSb3({
|
|
69
|
+
inputPath: 'tmp/project.sb3',
|
|
70
|
+
outputDirectory: 'app',
|
|
71
|
+
});
|
|
72
|
+
|
|
73
|
+
await validateSb3Source('app');
|
|
74
|
+
|
|
75
|
+
await buildSb3({
|
|
76
|
+
sourceDirectory: 'app',
|
|
77
|
+
outputPath: 'dist/project.sb3',
|
|
78
|
+
});
|
|
79
|
+
|
|
80
|
+
const {archive} = await createDeterministicSb3('app');
|
|
81
|
+
|
|
82
|
+
const integrity = extensionIntegrity(await readFile('app/extensions/example.js'));
|
|
83
|
+
|
|
84
|
+
const statuses = await extensionStatus('app');
|
|
85
|
+
const migration = await planExtensionIdMigration({
|
|
86
|
+
sourceDirectory: 'app',
|
|
87
|
+
fromId: 'oldId',
|
|
88
|
+
toId: 'newid',
|
|
89
|
+
});
|
|
90
|
+
await migrateExtensionId({
|
|
91
|
+
sourceDirectory: 'app',
|
|
92
|
+
fromId: 'oldId',
|
|
93
|
+
toId: 'newid',
|
|
94
|
+
yes: true,
|
|
95
|
+
});
|
|
96
|
+
await syncExtensions({sourceDirectory: 'app', yes: true});
|
|
97
|
+
await updateExtensions({
|
|
98
|
+
sourceDirectory: 'app',
|
|
99
|
+
extensionId: 'oldId',
|
|
100
|
+
migrateToId: 'newid',
|
|
101
|
+
sourceArtifact: 'dist/newid.js',
|
|
102
|
+
apiManifestArtifact: 'dist/newid.manifest.json',
|
|
103
|
+
yes: true,
|
|
104
|
+
});
|
|
105
|
+
// After reviewing a reported breaking API change, opt in explicitly:
|
|
106
|
+
await updateExtensions({sourceDirectory: 'app', allowBreakingApi: true, yes: true});
|
|
107
|
+
await bundleExtensions({
|
|
108
|
+
sourceDirectory: 'app',
|
|
109
|
+
bundleId: 'projectbundle',
|
|
110
|
+
bundleName: 'Project Extension Bundle',
|
|
111
|
+
extensionIds: ['extensionone', 'extensiontwo'],
|
|
112
|
+
yes: true,
|
|
113
|
+
});
|
|
114
|
+
await unbundleExtensions({
|
|
115
|
+
sourceDirectory: 'app',
|
|
116
|
+
bundleId: 'projectbundle',
|
|
117
|
+
yes: true,
|
|
118
|
+
});
|
|
119
|
+
await unbundleSb3({
|
|
120
|
+
inputPath: 'dist/project.sb3',
|
|
121
|
+
outputPath: 'dist/project.unbundled.sb3',
|
|
122
|
+
bundleId: 'projectbundle',
|
|
123
|
+
yes: true,
|
|
124
|
+
});
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## ドキュメント
|
|
128
|
+
|
|
129
|
+
- [`docs/ja/workflows.md`](docs/ja/workflows.md): SB3ソースと機能拡張を管理するワークフロー
|
|
130
|
+
- [`docs/ja/source-format-v1.md`](docs/ja/source-format-v1.md): 展開ソース形式と決定的出力
|
|
131
|
+
- [`docs/ja/extension-id-migration.md`](docs/ja/extension-id-migration.md): プロジェクトで使用中の機能拡張IDの移行
|
|
132
|
+
- [`docs/ja/extension-api-compatibility.md`](docs/ja/extension-api-compatibility.md): 機能拡張更新時の任意の静的API互換性検査
|
|
133
|
+
- [`docs/ja/extension-bundles.md`](docs/ja/extension-bundles.md): 1つの権限単位への静的bundleと可逆的なunbundle
|
|
134
|
+
|
|
135
|
+
## 開発
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
pnpm install
|
|
139
|
+
pnpm check
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## ライセンス
|
|
143
|
+
|
|
144
|
+
[Mozilla Public License 2.0](LICENSE)
|
|
145
|
+
|
|
146
|
+
この実装は、[`kubohiroya/tmpose-kamishibai`](https://github.com/kubohiroya/tmpose-kamishibai)
|
|
147
|
+
向けに開発された一般的なSB3ソース管理機構を、プロジェクト固有およびTMPose固有の処理から分離したものです。
|
package/README.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# sb3-toolchain
|
|
2
2
|
|
|
3
|
+
[日本語](README.ja.md)
|
|
4
|
+
|
|
3
5
|
A Node.js toolchain for managing Scratch 3 and TurboWarp `.sb3` projects as Git-diffable
|
|
4
6
|
expanded sources and rebuilding bit-for-bit identical SB3 files from the same input.
|
|
5
7
|
|
|
@@ -8,6 +10,7 @@ expanded sources and rebuilding bit-for-bit identical SB3 files from the same in
|
|
|
8
10
|
- Safely expand an SB3 into formatted `project.source.json`, assets, and embedded extensions
|
|
9
11
|
- Validate asset references, MD5 hashes, ZIP entries, and embedded extension mappings
|
|
10
12
|
- Record commits and SHA-256 hashes for GitHub-hosted embedded extensions and verify them offline
|
|
13
|
+
- Optionally compare versioned extension API manifests before replacing embedded JavaScript
|
|
11
14
|
- Statically bundle multiple extensions into one permission unit without deleting their original
|
|
12
15
|
JavaScript, then restore them from either the expanded source or the bundled SB3
|
|
13
16
|
- Produce deterministic builds with fixed ZIP entry order, timestamps, and compression settings
|
|
@@ -15,9 +18,6 @@ expanded sources and rebuilding bit-for-bit identical SB3 files from the same in
|
|
|
15
18
|
- Protect existing output through transactional replacement and rollback
|
|
16
19
|
- Provide both a CLI and a JavaScript API
|
|
17
20
|
|
|
18
|
-
TMPose kamishibai script conversion, project-specific data, and web application generation with
|
|
19
|
-
TurboWarp Packager are outside the scope of this package.
|
|
20
|
-
|
|
21
21
|
## Requirements
|
|
22
22
|
|
|
23
23
|
- Node.js 22.12.0 or later
|
|
@@ -28,7 +28,7 @@ TurboWarp Packager are outside the scope of this package.
|
|
|
28
28
|
Pin the verified npm version for reproducible installation.
|
|
29
29
|
|
|
30
30
|
```bash
|
|
31
|
-
pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.
|
|
31
|
+
pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.4.0
|
|
32
32
|
```
|
|
33
33
|
|
|
34
34
|
## Quick start
|
|
@@ -99,8 +99,11 @@ await updateExtensions({
|
|
|
99
99
|
extensionId: 'oldId',
|
|
100
100
|
migrateToId: 'newid',
|
|
101
101
|
sourceArtifact: 'dist/newid.js',
|
|
102
|
+
apiManifestArtifact: 'dist/newid.manifest.json',
|
|
102
103
|
yes: true,
|
|
103
104
|
});
|
|
105
|
+
// After reviewing a reported breaking API change, opt in explicitly:
|
|
106
|
+
await updateExtensions({sourceDirectory: 'app', allowBreakingApi: true, yes: true});
|
|
104
107
|
await bundleExtensions({
|
|
105
108
|
sourceDirectory: 'app',
|
|
106
109
|
bundleId: 'projectbundle',
|
|
@@ -126,6 +129,7 @@ await unbundleSb3({
|
|
|
126
129
|
- [`docs/workflows.md`](docs/workflows.md): SB3 source and extension management workflows
|
|
127
130
|
- [`docs/source-format-v1.md`](docs/source-format-v1.md): expanded source format and deterministic output
|
|
128
131
|
- [`docs/extension-id-migration.md`](docs/extension-id-migration.md): migration of extension IDs already used by a project
|
|
132
|
+
- [`docs/extension-api-compatibility.md`](docs/extension-api-compatibility.md) ([日本語](docs/ja/extension-api-compatibility.md)): opt-in static API compatibility checks for extension updates
|
|
129
133
|
- [`docs/extension-bundles.md`](docs/extension-bundles.md): static bundling into one permission unit and reversible unbundling
|
|
130
134
|
|
|
131
135
|
## Development
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
# Extension API compatibility manifests
|
|
2
|
+
|
|
3
|
+
[日本語版](ja/extension-api-compatibility.md)
|
|
4
|
+
|
|
5
|
+
An embedded extension can opt in to a versioned API manifest so that `sb3-toolchain` checks the
|
|
6
|
+
saved-project contract before replacing its JavaScript. The manifest is validation metadata: it is
|
|
7
|
+
kept in expanded source, fetched from the same immutable commit as the JavaScript, and never embedded
|
|
8
|
+
in the generated SB3.
|
|
9
|
+
|
|
10
|
+
This feature is optional. Existing unmanaged extensions and managed extensions without
|
|
11
|
+
`source.apiManifest` keep their previous behavior and deterministic SB3 output.
|
|
12
|
+
|
|
13
|
+
## Why a second artifact is necessary
|
|
14
|
+
|
|
15
|
+
Commit pinning and SHA-256 answer whether a JavaScript artifact is authentic and reproducible. They
|
|
16
|
+
do not answer whether an update still provides the opcodes and argument shapes already stored in a
|
|
17
|
+
project.
|
|
18
|
+
|
|
19
|
+
```mermaid
|
|
20
|
+
flowchart LR
|
|
21
|
+
Ref["Tracked Git ref"] --> Commit["Resolved commit"]
|
|
22
|
+
Commit --> JS["Extension JavaScript"]
|
|
23
|
+
Commit --> API["API manifest v1"]
|
|
24
|
+
JS --> Identity["Header ID + SHA-256"]
|
|
25
|
+
API --> Contract["Opcode / argument / menu comparison"]
|
|
26
|
+
Identity --> Candidate["Validated candidate"]
|
|
27
|
+
Contract --> Candidate
|
|
28
|
+
Candidate --> Transaction["One transactional source update"]
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
The manifest is parsed as JSON and is never executed. `sb3-toolchain` validates manifest v1 locally
|
|
32
|
+
instead of downloading a schema during a check or build.
|
|
33
|
+
|
|
34
|
+
## Expanded-source metadata
|
|
35
|
+
|
|
36
|
+
Add `apiManifest` below an existing GitHub `source` object:
|
|
37
|
+
|
|
38
|
+
```json
|
|
39
|
+
{
|
|
40
|
+
"id": "example",
|
|
41
|
+
"path": "extensions/example.js",
|
|
42
|
+
"mediaType": "text/javascript",
|
|
43
|
+
"parameters": [],
|
|
44
|
+
"encoding": "base64",
|
|
45
|
+
"source": {
|
|
46
|
+
"provider": "github",
|
|
47
|
+
"repository": "owner/example-extension",
|
|
48
|
+
"ref": "main",
|
|
49
|
+
"resolvedCommit": "0123456789abcdef0123456789abcdef01234567",
|
|
50
|
+
"artifact": "dist/example.js",
|
|
51
|
+
"integrity": "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
|
|
52
|
+
"apiManifest": {
|
|
53
|
+
"artifact": "dist/extension-manifest.json",
|
|
54
|
+
"path": "extensions/example.manifest.json",
|
|
55
|
+
"formatVersion": 1,
|
|
56
|
+
"integrity": "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB="
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
- `artifact` is the manifest path in the GitHub repository.
|
|
63
|
+
- `path` must be `extensions/<extensionId>.manifest.json` in expanded source.
|
|
64
|
+
- `formatVersion` must be `1`.
|
|
65
|
+
- `integrity` is the SHA-256 SRI value of the installed manifest file.
|
|
66
|
+
|
|
67
|
+
The JavaScript and manifest artifacts use the same repository and `resolvedCommit`. Separate
|
|
68
|
+
repositories or commits are intentionally unsupported because they would make the recorded API
|
|
69
|
+
contract ambiguous.
|
|
70
|
+
|
|
71
|
+
## Manifest v1 contract
|
|
72
|
+
|
|
73
|
+
Manifest v1 contains:
|
|
74
|
+
|
|
75
|
+
- the extension ID;
|
|
76
|
+
- block opcode and block type;
|
|
77
|
+
- argument ID, type, and optional menu reference;
|
|
78
|
+
- menu ID and `acceptReporters`.
|
|
79
|
+
|
|
80
|
+
Unknown properties, duplicate identifiers, unknown menu references, unsupported versions, and ID
|
|
81
|
+
mismatches are rejected. Array order is normalized before comparison.
|
|
82
|
+
|
|
83
|
+
Display text, descriptions, default values, static menu items, labels, separators, and palette order
|
|
84
|
+
are outside manifest v1. They do not identify saved-project API references. Extension bundling
|
|
85
|
+
therefore continues to use `extensionBundles[].members` and runtime `getInfo().blocks` order; it does
|
|
86
|
+
not use manifest order to build the palette.
|
|
87
|
+
|
|
88
|
+
## Compatibility policy
|
|
89
|
+
|
|
90
|
+
| Candidate change | Classification | Reason |
|
|
91
|
+
| ---------------------------- | -------------- | ---------------------------------------------------- |
|
|
92
|
+
| Add a block | Compatible | Existing saved blocks keep their handler |
|
|
93
|
+
| Add an unreferenced menu | Compatible | No existing argument contract changes |
|
|
94
|
+
| Remove an unreferenced menu | Compatible | No saved argument refers to the menu |
|
|
95
|
+
| Remove a block | Breaking | Saved opcodes lose their handler |
|
|
96
|
+
| Change a block type | Breaking | Saved block shape or evaluation changes |
|
|
97
|
+
| Add or remove an argument | Breaking | Manifest v1 cannot prove a safe default or migration |
|
|
98
|
+
| Change argument type or menu | Breaking | Saved input interpretation changes |
|
|
99
|
+
| Remove a referenced menu | Breaking | Existing menu references can no longer resolve |
|
|
100
|
+
| Change `acceptReporters` | Breaking | Accepted saved input shapes change |
|
|
101
|
+
|
|
102
|
+
Compatibility reports use stable paths such as:
|
|
103
|
+
|
|
104
|
+
```text
|
|
105
|
+
/blocks/speak/blockType
|
|
106
|
+
/blocks/speak/arguments/VOICE/menu
|
|
107
|
+
/menus/voices/acceptReporters
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
An ID migration explicitly normalizes the old and new top-level IDs before comparing the remaining
|
|
111
|
+
contract. Any other API difference follows the same policy.
|
|
112
|
+
|
|
113
|
+
If the remote manifest filename changes with the extension ID, supply the new path explicitly:
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
sb3-toolchain extensions update app OLD_ID --migrate-id NEW_ID \
|
|
117
|
+
--artifact dist/newid.js \
|
|
118
|
+
--api-manifest-artifact dist/newid.manifest.json
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Both artifact paths and their integrity values are updated in the same transaction.
|
|
122
|
+
|
|
123
|
+
## Status, sync, and update
|
|
124
|
+
|
|
125
|
+
`extensions status` validates both installed files offline when reporting `local=valid` or
|
|
126
|
+
`local=modified`. It resolves only the tracked Git ref and does not download a candidate manifest.
|
|
127
|
+
|
|
128
|
+
`extensions sync` downloads both artifacts from the recorded `resolvedCommit`. Both must match their
|
|
129
|
+
recorded integrity and IDs before either local file is replaced.
|
|
130
|
+
|
|
131
|
+
`extensions update` resolves `ref`, downloads both artifacts from the new commit, validates them, and
|
|
132
|
+
compares the candidate API with the installed manifest. New blocks are reported as compatible.
|
|
133
|
+
Breaking changes are rejected before a candidate directory is installed.
|
|
134
|
+
|
|
135
|
+
To apply an intentionally breaking update, review every reported path and use both explicit flags:
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
sb3-toolchain extensions update app EXTENSION_ID --allow-breaking-api --yes
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
`--allow-breaking-api` without `--yes` is rejected. This prevents an ordinary replacement
|
|
142
|
+
confirmation from also authorizing an API break.
|
|
143
|
+
|
|
144
|
+
The JavaScript, API manifest, `resolvedCommit`, and both integrity values are written in one
|
|
145
|
+
transaction. If one download or validation fails, expanded source is unchanged.
|
|
146
|
+
|
|
147
|
+
## Check, build, and import
|
|
148
|
+
|
|
149
|
+
`check` and `build` verify the installed API manifest without network access. The manifest does not
|
|
150
|
+
enter `project.json` or the SB3 ZIP, so opting in does not change the generated SB3 bytes.
|
|
151
|
+
|
|
152
|
+
Re-importing an unchanged SB3 into an existing managed expanded source preserves both
|
|
153
|
+
`source.apiManifest` and its installed manifest file. A new import cannot infer GitHub provenance or
|
|
154
|
+
manifest metadata, so it does not enable the feature automatically. Existing manifest metadata is
|
|
155
|
+
read only for an extension with the same imported ID and path, and its local path is validated before
|
|
156
|
+
the manifest file is opened.
|
|
157
|
+
|
|
158
|
+
## Rollback
|
|
159
|
+
|
|
160
|
+
For a project update, revert the project commit so that JavaScript, API manifest,
|
|
161
|
+
`resolvedCommit`, and both integrity values return together.
|
|
162
|
+
|
|
163
|
+
To stop API compatibility tracking without changing the embedded JavaScript:
|
|
164
|
+
|
|
165
|
+
1. Remove `source.apiManifest` from the extension entry.
|
|
166
|
+
2. Remove `extensions/<extensionId>.manifest.json`.
|
|
167
|
+
3. Run `sb3-toolchain check` and rebuild the SB3.
|
|
168
|
+
|
|
169
|
+
The extension then follows the previous JavaScript provenance and integrity workflow.
|
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# Static bundles for embedded extensions
|
|
2
2
|
|
|
3
|
+
[日本語版](ja/extension-bundles.md)
|
|
4
|
+
|
|
3
5
|
When a newly opened SB3 contains several unsandboxed extensions, TurboWarp asks for permission to
|
|
4
6
|
run each extension. A static bundle keeps the individual extensions in the expanded source but
|
|
5
7
|
transforms only the generated SB3 into one composite extension, reducing the permission unit to
|
|
@@ -227,11 +229,12 @@ each member's `getInfo().blocks`. In the TurboWarp Editor palette, each group be
|
|
|
227
229
|
LABEL heading in this form:
|
|
228
230
|
|
|
229
231
|
```text
|
|
230
|
-
◆
|
|
232
|
+
◆ <name> [<memberId>] ◆
|
|
231
233
|
```
|
|
232
234
|
|
|
233
|
-
|
|
234
|
-
machine-readable
|
|
235
|
+
Putting the member name first keeps it visible in TurboWarp's narrow palette. Two consecutive `---`
|
|
236
|
+
separators divide member groups. A generated LABEL also carries the following machine-readable
|
|
237
|
+
metadata:
|
|
235
238
|
|
|
236
239
|
```js
|
|
237
240
|
{
|
|
@@ -242,6 +245,24 @@ machine-readable metadata:
|
|
|
242
245
|
}
|
|
243
246
|
```
|
|
244
247
|
|
|
248
|
+
When a member's `getInfo()` returns a non-empty string [`docsURI`](https://docs.turbowarp.org/development/extensions/assorted-apis#docsuri),
|
|
249
|
+
the bundle inserts an `Open Documentation` button immediately after that member's heading. It uses TurboWarp's native
|
|
250
|
+
`OPEN_EXTENSION_DOCS` callback, so it preserves the normal `docsURI` behavior instead of delegating
|
|
251
|
+
to extension code. The generated button carries separate metadata and safely XML-escapes the URI:
|
|
252
|
+
|
|
253
|
+
```js
|
|
254
|
+
{
|
|
255
|
+
sb3Toolchain: {
|
|
256
|
+
docsURI,
|
|
257
|
+
kind: 'bundle-member-docs',
|
|
258
|
+
memberId,
|
|
259
|
+
},
|
|
260
|
+
}
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
No button is inserted for a member without `docsURI`. Member-provided XML blocks remain unsupported;
|
|
264
|
+
the tool generates only this narrowly defined documentation button XML.
|
|
265
|
+
|
|
245
266
|
LABEL entries and separators originally defined by a member are preserved unchanged and in their
|
|
246
267
|
original positions. The decorated bundle heading and wider double separator therefore remain
|
|
247
268
|
visually distinct from an original heading or ordinary separator. A tool can identify the generated
|
|
@@ -252,14 +273,15 @@ The resulting palette has this visual hierarchy:
|
|
|
252
273
|
|
|
253
274
|
```text
|
|
254
275
|
┌─ Project Extension Bundle ─────────────────────────────┐
|
|
255
|
-
│ ◆
|
|
276
|
+
│ ◆ Alpha Tools [alpha] ◆ │ ← generated heading
|
|
277
|
+
│ Open Documentation │ ← generated docsURI button
|
|
256
278
|
│ alpha block 1 │
|
|
257
279
|
│ Alpha original heading │ ← original LABEL
|
|
258
280
|
│ │ ← original separator
|
|
259
281
|
│ alpha block 2 │
|
|
260
282
|
│ │
|
|
261
283
|
│ │ ← generated double separator
|
|
262
|
-
│ ◆
|
|
284
|
+
│ ◆ Beta Tools [beta] ◆ │ ← generated heading
|
|
263
285
|
│ beta block 1 │
|
|
264
286
|
└────────────────────────────────────────────────────────┘
|
|
265
287
|
```
|
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# Migrating embedded extension IDs
|
|
2
2
|
|
|
3
|
+
[日本語版](ja/extension-id-migration.md)
|
|
4
|
+
|
|
3
5
|
TurboWarp stores the IDs of loaded extensions in project opcodes and monitors. `extensions migrate-id`
|
|
4
6
|
does not perform a global string replacement. It changes only references whose meaning is defined by
|
|
5
7
|
SB3 source format v1.
|
|
@@ -46,12 +48,21 @@ upstream repository publishes an artifact declaring the new ID.
|
|
|
46
48
|
```bash
|
|
47
49
|
sb3-toolchain extensions update app twOld \
|
|
48
50
|
--migrate-id newext \
|
|
49
|
-
--artifact dist/newext.js
|
|
51
|
+
--artifact dist/newext.js \
|
|
52
|
+
--api-manifest-artifact dist/newext.manifest.json
|
|
50
53
|
```
|
|
51
54
|
|
|
52
|
-
Specify `--artifact` only when the upstream artifact path
|
|
53
|
-
|
|
54
|
-
|
|
55
|
+
Specify `--artifact` only when the upstream JavaScript artifact path changed. Specify
|
|
56
|
+
`--api-manifest-artifact` only when an opt-in manifest artifact path also changed. The tool resolves
|
|
57
|
+
the tracked ref to an immutable commit and downloads the new artifacts from that commit. It rejects
|
|
58
|
+
an artifact that does not declare `// ID: newext`, a collision, or an invalid new ID before changing
|
|
59
|
+
local files.
|
|
60
|
+
|
|
61
|
+
If the managed extension has `source.apiManifest`, the tool downloads the candidate manifest from
|
|
62
|
+
the same commit, normalizes only the explicit old and new top-level IDs, and applies the ordinary API
|
|
63
|
+
compatibility policy to every remaining field. JavaScript, the renamed local manifest, provenance,
|
|
64
|
+
both remote artifact paths when supplied, and both integrity values change in one transaction. See
|
|
65
|
+
[`extension-api-compatibility.md`](extension-api-compatibility.md).
|
|
55
66
|
|
|
56
67
|
## Validation and rollback
|
|
57
68
|
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
# Extension API互換性マニフェスト
|
|
2
|
+
|
|
3
|
+
[English](../extension-api-compatibility.md)
|
|
4
|
+
|
|
5
|
+
埋め込み機能拡張は、バージョン付きAPIマニフェストを任意で使用できます。これにより、
|
|
6
|
+
`sb3-toolchain`はJavaScriptを置き換える前に、保存済みプロジェクトとの契約を検査します。
|
|
7
|
+
マニフェストは検証用メタデータです。展開ソース内に保存され、JavaScriptと同じ変更不能なコミットから
|
|
8
|
+
取得されますが、生成するSB3には埋め込まれません。
|
|
9
|
+
|
|
10
|
+
この機能は任意です。管理対象外の既存機能拡張と、`source.apiManifest`を持たない管理対象機能拡張は、
|
|
11
|
+
従来の動作と決定的なSB3出力を維持します。
|
|
12
|
+
|
|
13
|
+
## 2つ目の成果物が必要な理由
|
|
14
|
+
|
|
15
|
+
コミット固定とSHA-256によって、JavaScript成果物が真正かつ再現可能かを確認できます。しかし、更新後も、
|
|
16
|
+
既存プロジェクトに保存されているopcodeや引数の形が提供されるかどうかは確認できません。
|
|
17
|
+
|
|
18
|
+
```mermaid
|
|
19
|
+
flowchart LR
|
|
20
|
+
Ref["追跡対象のGit ref"] --> Commit["解決済みコミット"]
|
|
21
|
+
Commit --> JS["機能拡張JavaScript"]
|
|
22
|
+
Commit --> API["APIマニフェストv1"]
|
|
23
|
+
JS --> Identity["header ID + SHA-256"]
|
|
24
|
+
API --> Contract["opcode / 引数 / メニューの比較"]
|
|
25
|
+
Identity --> Candidate["検証済み候補"]
|
|
26
|
+
Contract --> Candidate
|
|
27
|
+
Candidate --> Transaction["1回のトランザクションによるソース更新"]
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
マニフェストはJSONとして解析され、実行されることはありません。`sb3-toolchain`はcheckまたはbuildの
|
|
31
|
+
実行時にスキーマを取得せず、マニフェストv1をローカルで検証します。
|
|
32
|
+
|
|
33
|
+
## 展開ソースのメタデータ
|
|
34
|
+
|
|
35
|
+
既存のGitHub `source`オブジェクトの下に`apiManifest`を追加します。
|
|
36
|
+
|
|
37
|
+
```json
|
|
38
|
+
{
|
|
39
|
+
"id": "example",
|
|
40
|
+
"path": "extensions/example.js",
|
|
41
|
+
"mediaType": "text/javascript",
|
|
42
|
+
"parameters": [],
|
|
43
|
+
"encoding": "base64",
|
|
44
|
+
"source": {
|
|
45
|
+
"provider": "github",
|
|
46
|
+
"repository": "owner/example-extension",
|
|
47
|
+
"ref": "main",
|
|
48
|
+
"resolvedCommit": "0123456789abcdef0123456789abcdef01234567",
|
|
49
|
+
"artifact": "dist/example.js",
|
|
50
|
+
"integrity": "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
|
|
51
|
+
"apiManifest": {
|
|
52
|
+
"artifact": "dist/extension-manifest.json",
|
|
53
|
+
"path": "extensions/example.manifest.json",
|
|
54
|
+
"formatVersion": 1,
|
|
55
|
+
"integrity": "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB="
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
- `artifact`はGitHubリポジトリ内のマニフェストのパスです。
|
|
62
|
+
- `path`は展開ソース内の`extensions/<extensionId>.manifest.json`でなければなりません。
|
|
63
|
+
- `formatVersion`は`1`でなければなりません。
|
|
64
|
+
- `integrity`はインストール済みマニフェストファイルのSHA-256 SRI値です。
|
|
65
|
+
|
|
66
|
+
JavaScript成果物とマニフェスト成果物は、同じリポジトリと`resolvedCommit`を使用します。別のリポジトリや
|
|
67
|
+
コミットは、記録されたAPI契約を曖昧にするため、意図的にサポートしていません。
|
|
68
|
+
|
|
69
|
+
## マニフェストv1の契約
|
|
70
|
+
|
|
71
|
+
マニフェストv1には次の情報が含まれます。
|
|
72
|
+
|
|
73
|
+
- 機能拡張ID
|
|
74
|
+
- ブロックのopcodeとブロック種別
|
|
75
|
+
- 引数のID、型、任意のメニュー参照
|
|
76
|
+
- メニューのIDと`acceptReporters`
|
|
77
|
+
|
|
78
|
+
未知のプロパティ、識別子の重複、未知のメニュー参照、未対応バージョン、ID不一致は拒否されます。配列の順序は、
|
|
79
|
+
比較前に正規化されます。
|
|
80
|
+
|
|
81
|
+
表示テキスト、説明、デフォルト値、静的メニュー項目、`label`、`separator`、パレット順序はマニフェストv1の
|
|
82
|
+
対象外です。これらは保存済みプロジェクトのAPI参照を識別するものではありません。そのため、機能拡張の
|
|
83
|
+
bundleでは、引き続き`extensionBundles[].members`と実行時の`getInfo().blocks`の順序を使用します。
|
|
84
|
+
パレット構築にマニフェストの順序は使用しません。
|
|
85
|
+
|
|
86
|
+
## 互換性ポリシー
|
|
87
|
+
|
|
88
|
+
| 候補の変更 | 分類 | 理由 |
|
|
89
|
+
| ------------------------ | ---------- | ------------------------------------------------------ |
|
|
90
|
+
| ブロックを追加 | Compatible | 既存の保存済みブロックは処理を維持する |
|
|
91
|
+
| 未参照メニューを追加 | Compatible | 既存の引数契約は変わらない |
|
|
92
|
+
| 未参照メニューを削除 | Compatible | 保存済み引数から参照されていない |
|
|
93
|
+
| ブロックを削除 | Breaking | 保存済みopcodeの処理が失われる |
|
|
94
|
+
| ブロック種別を変更 | Breaking | 保存済みブロックの形または評価方法が変わる |
|
|
95
|
+
| 引数を追加または削除 | Breaking | マニフェストv1では安全なデフォルトや移行を証明できない |
|
|
96
|
+
| 引数の型やメニューを変更 | Breaking | 保存済み入力の解釈が変わる |
|
|
97
|
+
| 参照中メニューを削除 | Breaking | 既存のメニュー参照を解決できなくなる |
|
|
98
|
+
| `acceptReporters`を変更 | Breaking | 受け入れ可能な保存済み入力の形が変わる |
|
|
99
|
+
|
|
100
|
+
互換性レポートでは、次のような安定したパスを使用します。
|
|
101
|
+
|
|
102
|
+
```text
|
|
103
|
+
/blocks/speak/blockType
|
|
104
|
+
/blocks/speak/arguments/VOICE/menu
|
|
105
|
+
/menus/voices/acceptReporters
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
ID移行では、明示された旧IDと新IDのトップレベルIDだけを正規化してから、残りの契約を比較します。それ以外の
|
|
109
|
+
API差分には、同じ互換性ポリシーを適用します。
|
|
110
|
+
|
|
111
|
+
リモートのマニフェストファイル名も機能拡張IDとともに変わる場合は、新しいパスを明示します。
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
sb3-toolchain extensions update app OLD_ID --migrate-id NEW_ID \
|
|
115
|
+
--artifact dist/newid.js \
|
|
116
|
+
--api-manifest-artifact dist/newid.manifest.json
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
2つの成果物パスとintegrity値は、同じトランザクションで更新されます。
|
|
120
|
+
|
|
121
|
+
## Status、sync、update
|
|
122
|
+
|
|
123
|
+
`extensions status`は、`local=valid`または`local=modified`を報告するとき、インストール済みの2つの
|
|
124
|
+
ファイルをオフラインで検証します。追跡対象のGit refだけを解決し、候補マニフェストはダウンロードしません。
|
|
125
|
+
|
|
126
|
+
`extensions sync`は、記録済みの`resolvedCommit`から2つの成果物をダウンロードします。ローカルファイルを
|
|
127
|
+
置き換える前に、両方のIDと記録済みintegrityが一致しなければなりません。
|
|
128
|
+
|
|
129
|
+
`extensions update`は`ref`を解決し、新しいコミットから両方の成果物をダウンロードして検証した後、候補APIと
|
|
130
|
+
インストール済みマニフェストを比較します。新しいブロックはCompatibleとして報告されます。Breakingに分類される
|
|
131
|
+
変更がある場合、候補ディレクトリをインストールする前に拒否します。
|
|
132
|
+
|
|
133
|
+
意図的に破壊的更新を適用する場合は、報告されたすべてのパスを確認し、次の2つの明示的なフラグを使用します。
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
sb3-toolchain extensions update app EXTENSION_ID --allow-breaking-api --yes
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
`--yes`を伴わない`--allow-breaking-api`は拒否されます。これにより、通常の置換確認がAPI破壊の許可を
|
|
140
|
+
兼ねてしまうことを防ぎます。
|
|
141
|
+
|
|
142
|
+
JavaScript、APIマニフェスト、`resolvedCommit`、2つのintegrity値は、1回のトランザクションで書き込まれます。
|
|
143
|
+
ダウンロードまたは検証のいずれかが失敗した場合、展開ソースは変更されません。
|
|
144
|
+
|
|
145
|
+
## Check、build、import
|
|
146
|
+
|
|
147
|
+
`check`と`build`は、ネットワークへ接続せずにインストール済みAPIマニフェストを検証します。マニフェストは
|
|
148
|
+
`project.json`やSB3 ZIPへ追加されないため、この機能を有効にしても生成されるSB3のバイト列は変わりません。
|
|
149
|
+
|
|
150
|
+
変更されていないSB3を既存の管理対象展開ソースへ再インポートすると、`source.apiManifest`とインストール済み
|
|
151
|
+
マニフェストファイルの両方が保持されます。新規インポートではGitHubの来歴やマニフェストメタデータを
|
|
152
|
+
推測できないため、この機能を自動的に有効にはしません。既存のマニフェストメタデータを読み込むのは、
|
|
153
|
+
インポートしたIDとパスが一致する機能拡張だけです。また、マニフェストファイルを開く前にローカルパスを
|
|
154
|
+
検証します。
|
|
155
|
+
|
|
156
|
+
## ロールバック
|
|
157
|
+
|
|
158
|
+
プロジェクトを更新した場合は、プロジェクトのコミットをrevertし、JavaScript、APIマニフェスト、
|
|
159
|
+
`resolvedCommit`、2つのintegrity値をまとめて元に戻します。
|
|
160
|
+
|
|
161
|
+
埋め込みJavaScriptを変更せずにAPI互換性の追跡を停止するには、次の手順を実行します。
|
|
162
|
+
|
|
163
|
+
1. 機能拡張エントリから`source.apiManifest`を削除します。
|
|
164
|
+
2. `extensions/<extensionId>.manifest.json`を削除します。
|
|
165
|
+
3. `sb3-toolchain check`を実行し、SB3を再ビルドします。
|
|
166
|
+
|
|
167
|
+
その後、機能拡張は従来のJavaScript来歴とintegrityのワークフローに戻ります。
|