@kubohiroya/sb3-toolchain 0.1.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/LICENSE +373 -0
- package/README.md +187 -0
- package/bin/sb3-toolchain.mjs +9 -0
- package/docs/extension-id-migration.md +59 -0
- package/docs/source-format-v1.md +119 -0
- package/package.json +62 -0
- package/src/archive.js +35 -0
- package/src/build.js +151 -0
- package/src/cli.js +465 -0
- package/src/constants.js +4 -0
- package/src/extension-dependencies.js +86 -0
- package/src/extension-id-migration.js +425 -0
- package/src/extension-sync.js +496 -0
- package/src/import.js +381 -0
- package/src/index.js +34 -0
- package/src/output-safety.js +322 -0
- package/src/source.js +386 -0
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# SB3展開ソース形式 v1
|
|
2
|
+
|
|
3
|
+
## 構成
|
|
4
|
+
|
|
5
|
+
```text
|
|
6
|
+
SOURCE_DIR/
|
|
7
|
+
├── sb3-source.json
|
|
8
|
+
├── project.source.json
|
|
9
|
+
├── embedded-extensions.json
|
|
10
|
+
├── assets/
|
|
11
|
+
│ └── <assetId>.<dataFormat>
|
|
12
|
+
└── extensions/
|
|
13
|
+
└── <extensionId>.js
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
`sb3-source.json`は形式バージョン、各構成要素のパス、元SB3のZIPエントリ順を保持します。
|
|
17
|
+
|
|
18
|
+
```json
|
|
19
|
+
{
|
|
20
|
+
"formatVersion": 1,
|
|
21
|
+
"project": "project.source.json",
|
|
22
|
+
"embeddedExtensions": "embedded-extensions.json",
|
|
23
|
+
"assetsDirectory": "assets",
|
|
24
|
+
"archiveEntries": ["project.json", "<assetId>.svg"]
|
|
25
|
+
}
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## `project.source.json`
|
|
29
|
+
|
|
30
|
+
元SB3の`project.json`を2スペースで整形したJSONです。配列とオブジェクトの順序は
|
|
31
|
+
意味のある入力として保持します。data URLで埋め込まれていたTurboWarp拡張は次の参照へ
|
|
32
|
+
置き換えます。
|
|
33
|
+
|
|
34
|
+
```text
|
|
35
|
+
embedded-extension:extensions/<extensionId>.js
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
ビルド時には`embedded-extensions.json`のメディアタイプ、パラメーター、エンコーディングを
|
|
39
|
+
使ってdata URLへ戻します。
|
|
40
|
+
|
|
41
|
+
## `embedded-extensions.json`
|
|
42
|
+
|
|
43
|
+
埋め込み拡張のdata URL情報と展開先を保持します。GitHub上で管理する拡張には、任意の
|
|
44
|
+
`source`メタデータを追加できます。
|
|
45
|
+
|
|
46
|
+
```json
|
|
47
|
+
{
|
|
48
|
+
"formatVersion": 1,
|
|
49
|
+
"extensions": [
|
|
50
|
+
{
|
|
51
|
+
"id": "example",
|
|
52
|
+
"path": "extensions/example.js",
|
|
53
|
+
"mediaType": "text/javascript",
|
|
54
|
+
"parameters": [],
|
|
55
|
+
"encoding": "base64",
|
|
56
|
+
"source": {
|
|
57
|
+
"provider": "github",
|
|
58
|
+
"repository": "owner/example-extension",
|
|
59
|
+
"ref": "main",
|
|
60
|
+
"resolvedCommit": "0123456789abcdef0123456789abcdef01234567",
|
|
61
|
+
"artifact": "dist/example.js",
|
|
62
|
+
"integrity": "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
]
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
- `repository`: `<owner>/<repository>`形式のGitHubリポジトリ
|
|
70
|
+
- `ref`: 更新候補を追跡するbranch、tag、またはcommit
|
|
71
|
+
- `resolvedCommit`: 現在の実ファイルを取得した小文字40桁のcommit SHA
|
|
72
|
+
- `artifact`: リポジトリルートから見たJavaScript成果物の相対パス
|
|
73
|
+
- `integrity`: 現在の実ファイルに対するSRI形式のSHA-256
|
|
74
|
+
|
|
75
|
+
`source`を持つ拡張について、検証とビルドはネットワークへ接続せず、次を確認します。
|
|
76
|
+
|
|
77
|
+
- 実ファイルのSHA-256が`integrity`と一致する
|
|
78
|
+
- 実ファイルの`// ID: <extensionId>`ヘッダーが`id`と一致する
|
|
79
|
+
- リポジトリ、ref、commit、成果物パスが安全な形式である
|
|
80
|
+
|
|
81
|
+
既存の展開ディレクトリへSB3を再importすると、同じIDとパスに対応する`source`を維持します。
|
|
82
|
+
再importされた実ファイルが記録済みハッシュまたはIDと一致しない場合は、既存出力を変更
|
|
83
|
+
しません。新規importは由来を推測できないため、`source`を自動生成しません。
|
|
84
|
+
|
|
85
|
+
`extensions sync`は`resolvedCommit`を固定入力として`artifact`を取得し、既存の
|
|
86
|
+
`integrity`とIDに一致する場合だけローカルファイルを復元します。`extensions update`は
|
|
87
|
+
`ref`をGitHub APIで解決し、そのcommitから取得した成果物に合わせて`resolvedCommit`と
|
|
88
|
+
`integrity`を更新します。複数entryの取得と検証がすべて成功するまで、展開ソースは変更
|
|
89
|
+
されません。
|
|
90
|
+
|
|
91
|
+
拡張IDの変更では、manifestの`id`と`path`、`project.source.json`の既知参照、
|
|
92
|
+
`extensions/<id>.js`を同じtransactionで移行します。管理対象拡張を`extensions update`
|
|
93
|
+
と同時に移行した場合は、`artifact`(明示時)、`resolvedCommit`、`integrity`も新成果物に
|
|
94
|
+
合わせて更新します。
|
|
95
|
+
|
|
96
|
+
## アセット
|
|
97
|
+
|
|
98
|
+
`assets/`には`project.source.json`から参照されるコスチュームと音声を置きます。
|
|
99
|
+
各ファイル名は`<assetId>.<dataFormat>`であり、`assetId`は内容のMD5と一致しなければ
|
|
100
|
+
なりません。未参照、欠損、余分なファイルは検証エラーです。
|
|
101
|
+
|
|
102
|
+
## 決定的出力
|
|
103
|
+
|
|
104
|
+
- ZIPエントリ順は`archiveEntries`に従う
|
|
105
|
+
- ZIPタイムスタンプは1980-01-01 00:00:00に固定
|
|
106
|
+
- 圧縮レベルは6に固定
|
|
107
|
+
- `project.json`は末尾改行付きの最小JSONとして格納
|
|
108
|
+
- 同じソース形式バージョン、入力ファイル、ツールバージョンから同じバイト列を生成
|
|
109
|
+
|
|
110
|
+
## 安全性
|
|
111
|
+
|
|
112
|
+
- 絶対パス、`\`、空要素、`.`、`..`を含むZIPエントリを拒否
|
|
113
|
+
- シンボリックリンクまたは特殊ファイルをソースとして受理しない
|
|
114
|
+
- import先のファイルシステムルート、Gitリポジトリルート、その祖先、`.git/`を拒否
|
|
115
|
+
- 認識できない既存ディレクトリを上書きしない
|
|
116
|
+
- Git管理中の差分は明示的な二段階指定なしに破棄しない
|
|
117
|
+
- 置換中断時のロールバック領域を検出した場合は自動上書きしない
|
|
118
|
+
- 管理対象の拡張は、ネットワークに依存せずcommit、SHA-256、拡張IDの整合性を検証
|
|
119
|
+
- GitHub取得はHTTPS・redirect拒否・サイズ上限付きとし、取得したJavaScriptを実行しない
|
package/package.json
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@kubohiroya/sb3-toolchain",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Git-friendly source management and deterministic builds for Scratch 3 and TurboWarp SB3 projects",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MPL-2.0",
|
|
7
|
+
"author": "Hiroya Kubo",
|
|
8
|
+
"homepage": "https://github.com/kubohiroya/sb3-toolchain#readme",
|
|
9
|
+
"repository": {
|
|
10
|
+
"type": "git",
|
|
11
|
+
"url": "git+https://github.com/kubohiroya/sb3-toolchain.git"
|
|
12
|
+
},
|
|
13
|
+
"bugs": {
|
|
14
|
+
"url": "https://github.com/kubohiroya/sb3-toolchain/issues"
|
|
15
|
+
},
|
|
16
|
+
"exports": {
|
|
17
|
+
".": "./src/index.js",
|
|
18
|
+
"./package.json": "./package.json"
|
|
19
|
+
},
|
|
20
|
+
"bin": {
|
|
21
|
+
"sb3-toolchain": "./bin/sb3-toolchain.mjs"
|
|
22
|
+
},
|
|
23
|
+
"files": [
|
|
24
|
+
"bin/",
|
|
25
|
+
"docs/",
|
|
26
|
+
"src/",
|
|
27
|
+
"README.md",
|
|
28
|
+
"LICENSE"
|
|
29
|
+
],
|
|
30
|
+
"publishConfig": {
|
|
31
|
+
"access": "public"
|
|
32
|
+
},
|
|
33
|
+
"packageManager": "pnpm@11.11.0",
|
|
34
|
+
"scripts": {
|
|
35
|
+
"lint": "eslint src bin test",
|
|
36
|
+
"format": "prettier --check .github bin docs src test package.json README.md tsconfig.json",
|
|
37
|
+
"format:write": "prettier --write .github bin docs src test package.json README.md tsconfig.json",
|
|
38
|
+
"typecheck": "tsc --project tsconfig.json",
|
|
39
|
+
"test": "node --test test/*.test.mjs",
|
|
40
|
+
"check": "pnpm lint && pnpm format && pnpm typecheck && pnpm test",
|
|
41
|
+
"prepack": "pnpm check"
|
|
42
|
+
},
|
|
43
|
+
"dependencies": {
|
|
44
|
+
"fflate": "0.8.3"
|
|
45
|
+
},
|
|
46
|
+
"devDependencies": {
|
|
47
|
+
"@types/node": "^24.0.0",
|
|
48
|
+
"eslint": "^9.0.0",
|
|
49
|
+
"prettier": "^3.0.0",
|
|
50
|
+
"typescript": "^5.9.0"
|
|
51
|
+
},
|
|
52
|
+
"engines": {
|
|
53
|
+
"node": ">=22.12.0"
|
|
54
|
+
},
|
|
55
|
+
"keywords": [
|
|
56
|
+
"sb3",
|
|
57
|
+
"scratch",
|
|
58
|
+
"turbowarp",
|
|
59
|
+
"source-control",
|
|
60
|
+
"reproducible-builds"
|
|
61
|
+
]
|
|
62
|
+
}
|
package/src/archive.js
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
// SPDX-License-Identifier: MPL-2.0
|
|
2
|
+
|
|
3
|
+
import path from 'node:path';
|
|
4
|
+
|
|
5
|
+
function assert(condition, message) {
|
|
6
|
+
if (!condition) {
|
|
7
|
+
throw new Error(message);
|
|
8
|
+
}
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
export function validateArchiveEntryName(entryName) {
|
|
12
|
+
assert(
|
|
13
|
+
typeof entryName === 'string' && entryName.length > 0,
|
|
14
|
+
'SB3 archive contains an empty entry name.',
|
|
15
|
+
);
|
|
16
|
+
assert(
|
|
17
|
+
!entryName.includes('\0'),
|
|
18
|
+
`SB3 archive entry contains a NUL byte: ${JSON.stringify(entryName)}`,
|
|
19
|
+
);
|
|
20
|
+
assert(
|
|
21
|
+
!entryName.includes('\\'),
|
|
22
|
+
`SB3 archive entry uses a backslash: ${JSON.stringify(entryName)}`,
|
|
23
|
+
);
|
|
24
|
+
assert(
|
|
25
|
+
!path.posix.isAbsolute(entryName) && !/^[A-Za-z]:/u.test(entryName),
|
|
26
|
+
`SB3 archive entry is absolute: ${JSON.stringify(entryName)}`,
|
|
27
|
+
);
|
|
28
|
+
|
|
29
|
+
const segments = entryName.replace(/\/$/u, '').split('/');
|
|
30
|
+
assert(
|
|
31
|
+
segments.every((segment) => segment !== '' && segment !== '.' && segment !== '..'),
|
|
32
|
+
`SB3 archive entry contains an unsafe path segment: ${JSON.stringify(entryName)}`,
|
|
33
|
+
);
|
|
34
|
+
return entryName;
|
|
35
|
+
}
|
package/src/build.js
ADDED
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
// SPDX-License-Identifier: MPL-2.0
|
|
2
|
+
|
|
3
|
+
import {randomUUID} from 'node:crypto';
|
|
4
|
+
import {lstat, mkdir, mkdtemp, readdir, readFile, rename, rm, writeFile} from 'node:fs/promises';
|
|
5
|
+
import path from 'node:path';
|
|
6
|
+
|
|
7
|
+
import {pathExists} from './output-safety.js';
|
|
8
|
+
import {createDeterministicSb3} from './source.js';
|
|
9
|
+
|
|
10
|
+
function assert(condition, message) {
|
|
11
|
+
if (!condition) {
|
|
12
|
+
throw new Error(message);
|
|
13
|
+
}
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
async function assertNoInterruptedRollback(outputPath) {
|
|
17
|
+
const parentDirectory = path.dirname(outputPath);
|
|
18
|
+
if (!(await pathExists(parentDirectory))) {
|
|
19
|
+
return;
|
|
20
|
+
}
|
|
21
|
+
const rollbackPrefix = `.${path.basename(outputPath)}.rollback-`;
|
|
22
|
+
const leftovers = (await readdir(parentDirectory))
|
|
23
|
+
.filter((entryName) => entryName.startsWith(rollbackPrefix))
|
|
24
|
+
.map((entryName) => path.join(parentDirectory, entryName));
|
|
25
|
+
assert(
|
|
26
|
+
leftovers.length === 0,
|
|
27
|
+
`Found an interrupted SB3 build rollback file. Inspect or restore it before retrying: ` +
|
|
28
|
+
leftovers.join(', '),
|
|
29
|
+
);
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
async function inspectOutput(outputPath) {
|
|
33
|
+
if (!(await pathExists(outputPath))) {
|
|
34
|
+
return {contents: null, exists: false};
|
|
35
|
+
}
|
|
36
|
+
const stats = await lstat(outputPath);
|
|
37
|
+
assert(
|
|
38
|
+
stats.isFile() && !stats.isSymbolicLink(),
|
|
39
|
+
`Refusing to replace a non-file or symbolic link: ${outputPath}`,
|
|
40
|
+
);
|
|
41
|
+
return {contents: await readFile(outputPath), exists: true};
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
async function assertOutputUnchanged(outputPath, expectedOutput) {
|
|
45
|
+
const currentOutput = await inspectOutput(outputPath);
|
|
46
|
+
assert(
|
|
47
|
+
currentOutput.exists === expectedOutput.exists &&
|
|
48
|
+
(!currentOutput.exists ||
|
|
49
|
+
Buffer.compare(currentOutput.contents, expectedOutput.contents) === 0),
|
|
50
|
+
`SB3 output changed while the build was running; refusing to replace it: ${outputPath}`,
|
|
51
|
+
);
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
async function installArchiveTransactionally(archive, outputPath, expectedOutput) {
|
|
55
|
+
const parentDirectory = path.dirname(outputPath);
|
|
56
|
+
await assertNoInterruptedRollback(outputPath);
|
|
57
|
+
const temporaryDirectory = await mkdtemp(
|
|
58
|
+
path.join(parentDirectory, `.${path.basename(outputPath)}.build-`),
|
|
59
|
+
);
|
|
60
|
+
const temporaryPath = path.join(temporaryDirectory, path.basename(outputPath));
|
|
61
|
+
const rollbackPath = path.join(
|
|
62
|
+
parentDirectory,
|
|
63
|
+
`.${path.basename(outputPath)}.rollback-${randomUUID()}`,
|
|
64
|
+
);
|
|
65
|
+
await writeFile(temporaryPath, archive);
|
|
66
|
+
|
|
67
|
+
try {
|
|
68
|
+
await assertOutputUnchanged(outputPath, expectedOutput);
|
|
69
|
+
if (expectedOutput.exists) {
|
|
70
|
+
await rename(outputPath, rollbackPath);
|
|
71
|
+
}
|
|
72
|
+
try {
|
|
73
|
+
await rename(temporaryPath, outputPath);
|
|
74
|
+
} catch (installError) {
|
|
75
|
+
if (expectedOutput.exists) {
|
|
76
|
+
try {
|
|
77
|
+
await rename(rollbackPath, outputPath);
|
|
78
|
+
} catch (restoreError) {
|
|
79
|
+
throw new AggregateError(
|
|
80
|
+
[installError, restoreError],
|
|
81
|
+
`SB3 build failed and automatic restoration also failed. ` +
|
|
82
|
+
`Original output remains at: ${rollbackPath}`,
|
|
83
|
+
);
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
throw installError;
|
|
87
|
+
}
|
|
88
|
+
} finally {
|
|
89
|
+
await rm(temporaryDirectory, {recursive: true, force: true});
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
if (!expectedOutput.exists) {
|
|
93
|
+
return null;
|
|
94
|
+
}
|
|
95
|
+
try {
|
|
96
|
+
await rm(rollbackPath);
|
|
97
|
+
return null;
|
|
98
|
+
} catch (error) {
|
|
99
|
+
return (
|
|
100
|
+
`Built SB3 was installed, but its temporary rollback file could not be removed: ` +
|
|
101
|
+
`${rollbackPath} (${error.message})`
|
|
102
|
+
);
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
export async function buildSb3({confirmReplace, outputPath, sourceDirectory, yes = false}) {
|
|
107
|
+
assert(typeof sourceDirectory === 'string', 'SB3 source directory is required.');
|
|
108
|
+
assert(typeof outputPath === 'string', 'SB3 output path is required.');
|
|
109
|
+
const resolvedOutputPath = path.resolve(outputPath);
|
|
110
|
+
assert(
|
|
111
|
+
path.extname(resolvedOutputPath).toLowerCase() === '.sb3',
|
|
112
|
+
`SB3 output path must use the .sb3 extension: ${resolvedOutputPath}`,
|
|
113
|
+
);
|
|
114
|
+
await assertNoInterruptedRollback(resolvedOutputPath);
|
|
115
|
+
const built = await createDeterministicSb3(sourceDirectory);
|
|
116
|
+
const existingOutput = await inspectOutput(resolvedOutputPath);
|
|
117
|
+
if (existingOutput.exists) {
|
|
118
|
+
if (Buffer.compare(existingOutput.contents, Buffer.from(built.archive)) === 0) {
|
|
119
|
+
return {
|
|
120
|
+
...built,
|
|
121
|
+
changed: false,
|
|
122
|
+
outputPath: resolvedOutputPath,
|
|
123
|
+
rollbackCleanupWarning: null,
|
|
124
|
+
};
|
|
125
|
+
}
|
|
126
|
+
if (!yes) {
|
|
127
|
+
assert(
|
|
128
|
+
typeof confirmReplace === 'function',
|
|
129
|
+
`Existing SB3 output differs: ${resolvedOutputPath}. ` +
|
|
130
|
+
'Non-interactive replacement requires --yes.',
|
|
131
|
+
);
|
|
132
|
+
assert(
|
|
133
|
+
await confirmReplace(resolvedOutputPath),
|
|
134
|
+
'SB3 build cancelled; the existing output was not changed.',
|
|
135
|
+
);
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
await mkdir(path.dirname(resolvedOutputPath), {recursive: true});
|
|
140
|
+
const rollbackCleanupWarning = await installArchiveTransactionally(
|
|
141
|
+
built.archive,
|
|
142
|
+
resolvedOutputPath,
|
|
143
|
+
existingOutput,
|
|
144
|
+
);
|
|
145
|
+
return {
|
|
146
|
+
...built,
|
|
147
|
+
changed: true,
|
|
148
|
+
outputPath: resolvedOutputPath,
|
|
149
|
+
rollbackCleanupWarning,
|
|
150
|
+
};
|
|
151
|
+
}
|