@kubohiroya/sb3-toolchain 0.8.0 → 0.10.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/CHANGELOG.md ADDED
@@ -0,0 +1,16 @@
1
+ # Changelog
2
+
3
+ ## 0.10.0 - 2026-08-27
4
+
5
+ - Add generic deterministic SB3 release snapshot helpers.
6
+ - Add release source identity, candidate write, freeze, publication, and published artifact verification utilities.
7
+
8
+ Rollback: pin `@kubohiroya/sb3-toolchain@0.9.0` and keep app-specific release workflows local to each app package.
9
+
10
+ ## 0.9.0 - 2026-08-25
11
+
12
+ - Add a TurboWarp TM extension ID migration fixture workflow for `kubohiroyatm`.
13
+ - Add repository policy metadata and `repo:check` validation.
14
+ - Update README metadata, package archive checks, and release dry-run tooling.
15
+
16
+ Rollback: pin `@kubohiroya/sb3-toolchain@0.8.0` and revert project migration commits generated with this release.
package/README.ja.md CHANGED
@@ -31,7 +31,7 @@ Scratch 3およびTurboWarpの`.sb3`プロジェクトを、Gitで差分を確
31
31
  再現可能なインストールのため、検証済みのnpmバージョンを固定します。
32
32
 
33
33
  ```bash
34
- pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.8.0
34
+ pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.10.0
35
35
  ```
36
36
 
37
37
  ## クイックスタート
@@ -141,13 +141,14 @@ await unbundleSb3({
141
141
  ## 開発
142
142
 
143
143
  ```bash
144
- pnpm install
145
- pnpm check
144
+ corepack enable
145
+ pnpm install --frozen-lockfile
146
+ pnpm run check
146
147
  ```
147
148
 
148
149
  ## ライセンス
149
150
 
150
- [Mozilla Public License 2.0](LICENSE)
151
+ SPDX-License-Identifier: MPL-2.0
151
152
 
152
- この実装は、[`kubohiroya/tmpose-kamishibai`](https://github.com/kubohiroya/tmpose-kamishibai)
153
- 向けに開発された一般的なSB3ソース管理機構を、プロジェクト固有およびTMPose固有の処理から分離したものです。
153
+ この実装は、[`kubohiroya/tm-kamishibai`](https://github.com/kubohiroya/tm-kamishibai)
154
+ 向けに開発された一般的なSB3ソース管理機構を、TurboWarp TMのアプリケーション層から分離したものです。
package/README.md CHANGED
@@ -32,7 +32,7 @@ expanded sources and rebuilding bit-for-bit identical SB3 files from the same in
32
32
  Pin the verified npm version for reproducible installation.
33
33
 
34
34
  ```bash
35
- pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.8.0
35
+ pnpm add --save-dev --save-exact @kubohiroya/sb3-toolchain@0.10.0
36
36
  ```
37
37
 
38
38
  ## Quick start
@@ -142,14 +142,15 @@ await unbundleSb3({
142
142
  ## Development
143
143
 
144
144
  ```bash
145
- pnpm install
146
- pnpm check
145
+ corepack enable
146
+ pnpm install --frozen-lockfile
147
+ pnpm run check
147
148
  ```
148
149
 
149
150
  ## License
150
151
 
151
- [Mozilla Public License 2.0](LICENSE)
152
+ SPDX-License-Identifier: MPL-2.0
152
153
 
153
154
  This implementation extracts the general SB3 source-management mechanism developed for
154
- [`kubohiroya/tmpose-kamishibai`](https://github.com/kubohiroya/tmpose-kamishibai) from its
155
- project- and TMPose-specific processing.
155
+ [`kubohiroya/tm-kamishibai`](https://github.com/kubohiroya/tm-kamishibai) from the
156
+ TurboWarp TM application layer.
@@ -64,6 +64,38 @@ compatibility policy to every remaining field. JavaScript, the renamed local man
64
64
  both remote artifact paths when supplied, and both integrity values change in one transaction. See
65
65
  [`extension-api-compatibility.md`](extension-api-compatibility.md).
66
66
 
67
+ ## TurboWarp TM workflow
68
+
69
+ TurboWarp TM uses `kubohiroyatm` as the migrated extension ID. Plan first and review every
70
+ classified count, conflict, manifest path, and unclassified reference before applying the migration.
71
+
72
+ ```bash
73
+ sb3-toolchain extensions migrate-id app --from LEGACY_TM_ID --to kubohiroyatm
74
+ ```
75
+
76
+ After placing or updating the extension artifact so it declares `// ID: kubohiroyatm`, apply the
77
+ same generic migration. No TurboWarp TM-specific hard-code is required.
78
+
79
+ ```bash
80
+ sb3-toolchain extensions migrate-id app --from LEGACY_TM_ID --to kubohiroyatm --yes
81
+ sb3-toolchain check app
82
+ sb3-toolchain build app --output dist/project.sb3 --yes
83
+ ```
84
+
85
+ When the extension is managed from an upstream artifact, update provenance and migrate the ID in one
86
+ transaction:
87
+
88
+ ```bash
89
+ sb3-toolchain extensions update app LEGACY_TM_ID \
90
+ --migrate-id kubohiroyatm \
91
+ --artifact dist/kubohiroyatm.js \
92
+ --api-manifest-artifact dist/kubohiroyatm.manifest.json \
93
+ --yes
94
+ ```
95
+
96
+ The repository fixture for this workflow generates the legacy source state during tests so checked-in
97
+ metadata and documentation remain aligned with TurboWarp TM naming.
98
+
67
99
  ## Validation and rollback
68
100
 
69
101
  The tool completes normal source validation and a deterministic candidate SB3 build before replacing
@@ -62,6 +62,37 @@ sb3-toolchain extensions update app twOld \
62
62
  両方のintegrity値を、1回のトランザクションで変更します。詳しくは、
63
63
  [`extension-api-compatibility.md`](extension-api-compatibility.md)を参照してください。
64
64
 
65
+ ## TurboWarp TM ワークフロー
66
+
67
+ TurboWarp TMでは、移行後の機能拡張IDとして`kubohiroyatm`を使用します。まずplanを実行し、
68
+ 分類済み件数、衝突、manifest path、未分類参照を確認してから移行を適用します。
69
+
70
+ ```bash
71
+ sb3-toolchain extensions migrate-id app --from LEGACY_TM_ID --to kubohiroyatm
72
+ ```
73
+
74
+ `// ID: kubohiroyatm`を宣言する機能拡張成果物を配置または更新した後、同じgeneric migrationを適用します。
75
+ TurboWarp TM固有のhard-codeは不要です。
76
+
77
+ ```bash
78
+ sb3-toolchain extensions migrate-id app --from LEGACY_TM_ID --to kubohiroyatm --yes
79
+ sb3-toolchain check app
80
+ sb3-toolchain build app --output dist/project.sb3 --yes
81
+ ```
82
+
83
+ 上流成果物で管理している機能拡張では、来歴更新とID移行を1回のトランザクションで行います。
84
+
85
+ ```bash
86
+ sb3-toolchain extensions update app LEGACY_TM_ID \
87
+ --migrate-id kubohiroyatm \
88
+ --artifact dist/kubohiroyatm.js \
89
+ --api-manifest-artifact dist/kubohiroyatm.manifest.json \
90
+ --yes
91
+ ```
92
+
93
+ このワークフローのリポジトリfixtureはテスト中に旧source状態を生成するため、チェックイン済みmetadataと
94
+ ドキュメントはTurboWarp TM命名に揃ったままです。
95
+
65
96
  ## 検証とロールバック
66
97
 
67
98
  ツールは展開ソースディレクトリをトランザクションで置き換える前に、通常のソース検証と候補SB3の決定的ビルドを
package/package.json CHANGED
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "@kubohiroya/sb3-toolchain",
3
- "version": "0.8.0",
3
+ "version": "0.10.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",
7
7
  "author": "Hiroya Kubo",
8
- "homepage": "https://github.com/kubohiroya/sb3-toolchain#readme",
8
+ "homepage": "https://kubohiroya.github.io/sb3-toolchain/",
9
9
  "repository": {
10
10
  "type": "git",
11
11
  "url": "git+https://github.com/kubohiroya/sb3-toolchain.git"
@@ -23,6 +23,8 @@
23
23
  "files": [
24
24
  "bin/",
25
25
  "docs/",
26
+ "repo-policy.json",
27
+ "CHANGELOG.md",
26
28
  "src/",
27
29
  "README.md",
28
30
  "README.ja.md",
@@ -34,15 +36,16 @@
34
36
  },
35
37
  "packageManager": "pnpm@11.11.0",
36
38
  "scripts": {
37
- "lint": "eslint src bin test",
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
+ "lint": "eslint src bin scripts test",
40
+ "format": "prettier --check .github bin docs scripts src test CHANGELOG.md package.json README.md README.ja.md repo-policy.json tsconfig.json",
41
+ "format:write": "prettier --write .github bin docs scripts src test CHANGELOG.md package.json README.md README.ja.md repo-policy.json tsconfig.json",
40
42
  "typecheck": "tsc --project tsconfig.json",
41
43
  "test": "node --test test/*.test.mjs",
42
44
  "pack:check": "npm pack --dry-run --ignore-scripts",
43
45
  "release:check": "npm publish --dry-run --access public",
44
- "check": "pnpm lint && pnpm format && pnpm typecheck && pnpm test && pnpm pack:check",
45
- "prepack": "pnpm check"
46
+ "repo:check": "node scripts/check-repo.mjs",
47
+ "check": "pnpm run lint && pnpm run format && pnpm run typecheck && pnpm run test && pnpm run repo:check && pnpm run pack:check",
48
+ "prepack": "pnpm run check"
46
49
  },
47
50
  "dependencies": {
48
51
  "fflate": "0.8.3",
@@ -0,0 +1,29 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "profile": "cli-js-api-package",
4
+ "packageName": "@kubohiroya/sb3-toolchain",
5
+ "humanName": "sb3-toolchain",
6
+ "license": "MPL-2.0",
7
+ "homepage": "https://kubohiroya.github.io/sb3-toolchain/",
8
+ "repository": "kubohiroya/sb3-toolchain",
9
+ "authorPolicy": {
10
+ "name": "Hiroya Kubo",
11
+ "email": false
12
+ },
13
+ "publicSurface": {
14
+ "cli": "sb3-toolchain",
15
+ "javascriptApi": true,
16
+ "preserveExistingBehavior": true
17
+ },
18
+ "integration": {
19
+ "upstreamMigrationIssue": "kubohiroya/turbowarp-tm#79",
20
+ "targetExtensionId": "kubohiroyatm",
21
+ "downstreamApplication": "TurboWarp TM",
22
+ "downstreamRepository": "kubohiroya/tm-kamishibai"
23
+ },
24
+ "release": {
25
+ "packDryRun": "pnpm run pack:check",
26
+ "releaseDryRun": "pnpm run release:check",
27
+ "publish": "manual-approval-required"
28
+ }
29
+ }
package/src/constants.js CHANGED
@@ -1,4 +1,4 @@
1
1
  // SPDX-License-Identifier: MPL-2.0
2
2
 
3
3
  export const packageName = '@kubohiroya/sb3-toolchain';
4
- export const packageVersion = '0.8.0';
4
+ export const packageVersion = '0.10.0';
package/src/index.js CHANGED
@@ -61,4 +61,15 @@ export {
61
61
  applyProjectAssetAdditions,
62
62
  projectAssetAdditionsFormatVersion,
63
63
  } from './project-asset-additions.js';
64
+ export {
65
+ assertSb3ReleaseSnapshotMetadata,
66
+ computeReleaseSourceIdentity,
67
+ createSb3ReleaseSnapshot,
68
+ createSb3ReleaseSnapshotMetadata,
69
+ freezeSb3ReleaseSnapshot,
70
+ readSb3ReleaseSnapshotMetadata,
71
+ recordPublishedSb3ReleaseSnapshot,
72
+ verifySb3ReleaseSnapshot,
73
+ writeSb3ReleaseCandidate,
74
+ } from './release-snapshot.js';
64
75
  export {cleanUpTurboWarpBlocks, turboWarpCleanUpLayout} from './turbowarp-clean-up.js';
@@ -0,0 +1,247 @@
1
+ // SPDX-License-Identifier: MPL-2.0
2
+
3
+ import {createHash} from 'node:crypto';
4
+ import {mkdir, readFile, rename, rm, writeFile} from 'node:fs/promises';
5
+ import path from 'node:path';
6
+ import process from 'node:process';
7
+
8
+ const releaseSnapshotFormatVersion = 1;
9
+ const releaseSnapshotStates = new Set(['candidate', 'frozen', 'published']);
10
+
11
+ function assert(condition, message) {
12
+ if (!condition) {
13
+ throw new Error(message);
14
+ }
15
+ }
16
+
17
+ function sha256(contents) {
18
+ return createHash('sha256').update(contents).digest('hex');
19
+ }
20
+
21
+ function asBuffer(contents, description) {
22
+ if (Buffer.isBuffer(contents)) return contents;
23
+ if (contents instanceof Uint8Array) return Buffer.from(contents);
24
+ if (typeof contents === 'string') return Buffer.from(contents);
25
+ throw new TypeError(`${description} must be a string, Buffer, or Uint8Array.`);
26
+ }
27
+
28
+ function normalizedSourceEntries(sourceFiles) {
29
+ assert(sourceFiles instanceof Map, 'Release source files must be provided as a Map.');
30
+ const entries = [...sourceFiles.entries()].map(([relativePath, contents]) => {
31
+ assert(
32
+ typeof relativePath === 'string' &&
33
+ relativePath.length > 0 &&
34
+ !path.isAbsolute(relativePath) &&
35
+ !relativePath.split(/[\\/]+/u).includes('..'),
36
+ `Release source path must be a safe relative path: ${relativePath}`,
37
+ );
38
+ return [relativePath.split(path.sep).join('/'), asBuffer(contents, relativePath)];
39
+ });
40
+ entries.sort(([left], [right]) => left.localeCompare(right, 'en'));
41
+ return entries;
42
+ }
43
+
44
+ export function computeReleaseSourceIdentity(sourceFiles) {
45
+ const hash = createHash('sha256');
46
+ for (const [relativePath, contents] of normalizedSourceEntries(sourceFiles)) {
47
+ const pathBytes = Buffer.from(relativePath);
48
+ hash.update(Buffer.from(`${pathBytes.byteLength}:`));
49
+ hash.update(pathBytes);
50
+ hash.update(Buffer.from(`:${contents.byteLength}:`));
51
+ hash.update(contents);
52
+ }
53
+ return `sha256:${hash.digest('hex')}`;
54
+ }
55
+
56
+ export function createSb3ReleaseSnapshotMetadata({
57
+ artifact,
58
+ metadata = {},
59
+ publication = {},
60
+ sourceFiles,
61
+ state = 'candidate',
62
+ }) {
63
+ assert(releaseSnapshotStates.has(state), `Unsupported SB3 release snapshot state: ${state}`);
64
+ const archive = asBuffer(artifact.archive, 'SB3 release artifact archive');
65
+ const filename = artifact.filename;
66
+ assert(
67
+ typeof filename === 'string' && filename.endsWith('.sb3'),
68
+ 'Artifact filename is required.',
69
+ );
70
+ const normalizedArtifact = {
71
+ filename,
72
+ sha256: sha256(archive),
73
+ size: archive.byteLength,
74
+ };
75
+ if (artifact.url !== undefined) {
76
+ const url = new URL(artifact.url);
77
+ assert(url.protocol === 'https:', 'Artifact URL must use HTTPS.');
78
+ normalizedArtifact.url = url.href;
79
+ }
80
+ return {
81
+ formatVersion: releaseSnapshotFormatVersion,
82
+ ...metadata,
83
+ state,
84
+ sourceIdentity: computeReleaseSourceIdentity(sourceFiles),
85
+ artifact: normalizedArtifact,
86
+ publication: {...publication},
87
+ };
88
+ }
89
+
90
+ export function assertSb3ReleaseSnapshotMetadata(metadata) {
91
+ assert(
92
+ metadata?.formatVersion === releaseSnapshotFormatVersion,
93
+ 'SB3 release snapshot metadata format is invalid.',
94
+ );
95
+ assert(releaseSnapshotStates.has(metadata.state), 'SB3 release snapshot state is invalid.');
96
+ assert(
97
+ typeof metadata.sourceIdentity === 'string' &&
98
+ /^sha256:[0-9a-f]{64}$/u.test(metadata.sourceIdentity),
99
+ 'SB3 release snapshot source identity is invalid.',
100
+ );
101
+ assert(
102
+ typeof metadata.artifact?.filename === 'string' && metadata.artifact.filename.endsWith('.sb3'),
103
+ 'SB3 release snapshot artifact filename is invalid.',
104
+ );
105
+ assert(
106
+ typeof metadata.artifact?.sha256 === 'string' &&
107
+ /^[0-9a-f]{64}$/u.test(metadata.artifact.sha256),
108
+ 'SB3 release snapshot artifact SHA-256 is invalid.',
109
+ );
110
+ assert(
111
+ Number.isSafeInteger(metadata.artifact?.size) && metadata.artifact.size > 0,
112
+ 'SB3 release snapshot artifact size is invalid.',
113
+ );
114
+ if (metadata.artifact.url !== undefined) {
115
+ const url = new URL(metadata.artifact.url);
116
+ assert(url.protocol === 'https:', 'SB3 release snapshot artifact URL must use HTTPS.');
117
+ }
118
+ if (metadata.publication?.urls !== undefined) {
119
+ for (const [name, value] of Object.entries(metadata.publication.urls)) {
120
+ const url = new URL(value);
121
+ assert(
122
+ url.protocol === 'https:',
123
+ `SB3 release snapshot publication URL must use HTTPS: ${name}`,
124
+ );
125
+ }
126
+ }
127
+ return metadata;
128
+ }
129
+
130
+ export async function createSb3ReleaseSnapshot({
131
+ artifact,
132
+ createSb3,
133
+ metadata,
134
+ publication,
135
+ sourceFiles,
136
+ state,
137
+ }) {
138
+ assert(typeof createSb3 === 'function', 'A createSb3 function is required.');
139
+ const built = await createSb3();
140
+ const archive = asBuffer(built.archive, 'SB3 release artifact archive');
141
+ const snapshot = createSb3ReleaseSnapshotMetadata({
142
+ artifact: {...artifact, archive},
143
+ metadata,
144
+ publication,
145
+ sourceFiles,
146
+ state,
147
+ });
148
+ return {archive, metadata: assertSb3ReleaseSnapshotMetadata(snapshot), sourceFiles};
149
+ }
150
+
151
+ export async function verifySb3ReleaseSnapshot(options) {
152
+ const {createSb3, fetchPublishedArtifact, metadata, sourceFiles} = options;
153
+ const snapshot = assertSb3ReleaseSnapshotMetadata(metadata);
154
+ if (snapshot.state === 'published') {
155
+ assert(
156
+ typeof fetchPublishedArtifact === 'function',
157
+ 'A published artifact fetcher is required.',
158
+ );
159
+ const archive = asBuffer(
160
+ await fetchPublishedArtifact(snapshot),
161
+ 'Published SB3 release artifact',
162
+ );
163
+ assert(
164
+ archive.byteLength === snapshot.artifact.size,
165
+ 'Published SB3 release artifact size is invalid.',
166
+ );
167
+ assert(
168
+ sha256(archive) === snapshot.artifact.sha256,
169
+ 'Published SB3 release artifact SHA-256 is invalid.',
170
+ );
171
+ return snapshot;
172
+ }
173
+
174
+ assert(
175
+ computeReleaseSourceIdentity(sourceFiles) === snapshot.sourceIdentity,
176
+ 'SB3 release source changed. Update the release snapshot.',
177
+ );
178
+ assert(typeof createSb3 === 'function', 'A createSb3 function is required.');
179
+ const [first, second] = await Promise.all([createSb3(), createSb3()]);
180
+ const firstArchive = asBuffer(first.archive, 'First SB3 release artifact archive');
181
+ const secondArchive = asBuffer(second.archive, 'Second SB3 release artifact archive');
182
+ assert(
183
+ firstArchive.equals(secondArchive),
184
+ 'SB3 release artifact generation is not deterministic.',
185
+ );
186
+ assert(
187
+ sha256(firstArchive) === snapshot.artifact.sha256,
188
+ 'SB3 release artifact SHA-256 is stale.',
189
+ );
190
+ assert(firstArchive.byteLength === snapshot.artifact.size, 'SB3 release artifact size is stale.');
191
+ return snapshot;
192
+ }
193
+
194
+ async function writeAtomically(filename, contents) {
195
+ await mkdir(path.dirname(filename), {recursive: true});
196
+ const temporaryPath = `${filename}.tmp-${process.pid}`;
197
+ try {
198
+ await writeFile(temporaryPath, contents);
199
+ await rename(temporaryPath, filename);
200
+ } catch (error) {
201
+ await rm(temporaryPath, {force: true});
202
+ throw error;
203
+ }
204
+ }
205
+
206
+ export async function writeSb3ReleaseCandidate({artifactPath, archive, metadata, metadataPath}) {
207
+ assertSb3ReleaseSnapshotMetadata(metadata);
208
+ const artifactArchive = asBuffer(archive, 'SB3 release candidate archive');
209
+ assert(
210
+ sha256(artifactArchive) === metadata.artifact.sha256 &&
211
+ artifactArchive.byteLength === metadata.artifact.size,
212
+ 'SB3 release candidate archive does not match metadata.',
213
+ );
214
+ await writeAtomically(artifactPath, artifactArchive);
215
+ await writeAtomically(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`);
216
+ return {artifactPath, metadataPath};
217
+ }
218
+
219
+ export function freezeSb3ReleaseSnapshot(metadata) {
220
+ const snapshot = assertSb3ReleaseSnapshotMetadata(metadata);
221
+ if (snapshot.state === 'frozen') return snapshot;
222
+ assert(snapshot.state === 'candidate', 'Only candidate SB3 release snapshots can be frozen.');
223
+ return assertSb3ReleaseSnapshotMetadata({...snapshot, state: 'frozen'});
224
+ }
225
+
226
+ export async function readSb3ReleaseSnapshotMetadata(metadataPath) {
227
+ return assertSb3ReleaseSnapshotMetadata(JSON.parse(await readFile(metadataPath, 'utf8')));
228
+ }
229
+
230
+ export async function recordPublishedSb3ReleaseSnapshot(metadata, urls, options = {}) {
231
+ const {fetchPublishedArtifact} = options;
232
+ const snapshot = assertSb3ReleaseSnapshotMetadata(metadata);
233
+ assert(snapshot.state === 'frozen', 'Only frozen SB3 release snapshots can be published.');
234
+ const published = assertSb3ReleaseSnapshotMetadata({
235
+ ...snapshot,
236
+ state: 'published',
237
+ publication: {
238
+ ...snapshot.publication,
239
+ urls,
240
+ },
241
+ });
242
+ await verifySb3ReleaseSnapshot({
243
+ fetchPublishedArtifact,
244
+ metadata: published,
245
+ });
246
+ return published;
247
+ }