@kubohiroya/sb3-toolchain 0.19.0 → 0.20.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.
@@ -0,0 +1,176 @@
1
+ import { assert } from "./assert.js";
2
+ import { validateArchiveEntryName } from "./archive.js";
3
+ import { extensionHeaderId } from "./extension-dependencies.js";
4
+ import { fixedZipTimestamp } from "./source.js";
5
+ import { writeSb3Archive } from "./build.js";
6
+ import { decodeExtensionDataUrl } from "./import.js";
7
+ import path from "node:path";
8
+ import { createHash } from "node:crypto";
9
+ import { lstat, readFile, realpath } from "node:fs/promises";
10
+ import { strFromU8, strToU8, unzipSync, zipSync } from "fflate";
11
+ import { lt, valid } from "semver";
12
+ //#region src/extension-sb3-replacement.ts
13
+ var defaultKamishibaiManifestUrl = "https://kubohiroya.github.io/turbowarp-kamishibai-samples/stories/tutorial/public-surfaces.json";
14
+ var kamishibaiReplacementIds = Object.freeze(["kubohiroyakamishibai4", "kubohiroyakamishibaiauthoring4"]);
15
+ var archiveSizeLimit = 67108864;
16
+ var expandedSizeLimit = 268435456;
17
+ function isObject(value) {
18
+ return typeof value === "object" && value !== null && !Array.isArray(value);
19
+ }
20
+ function sha256(contents) {
21
+ return createHash("sha256").update(contents).digest("hex");
22
+ }
23
+ async function readArchive(filePath) {
24
+ assert(path.extname(filePath).toLowerCase() === ".sb3", `Expected an .sb3 file: ${filePath}`);
25
+ const stats = await lstat(filePath);
26
+ assert(stats.isFile() && !stats.isSymbolicLink(), `Expected a regular SB3 file: ${filePath}`);
27
+ assert(stats.size <= archiveSizeLimit, `SB3 exceeds the 64 MiB limit: ${filePath}`);
28
+ return readFile(filePath);
29
+ }
30
+ function parseArchive(contents) {
31
+ const names = /* @__PURE__ */ new Set();
32
+ let expandedSize = 0;
33
+ const entries = unzipSync(contents, { filter: (entry) => {
34
+ validateArchiveEntryName(entry.name);
35
+ assert(!names.has(entry.name), `Duplicate SB3 archive entry: ${entry.name}`);
36
+ assert(!/^(?:0|[1-9][0-9]*)$/u.test(entry.name), "Integer ZIP entry names are unsupported.");
37
+ names.add(entry.name);
38
+ expandedSize += entry.originalSize;
39
+ assert(names.size <= 4096 && expandedSize <= expandedSizeLimit, "SB3 expansion limit exceeded.");
40
+ return true;
41
+ } });
42
+ assert(Object.hasOwn(entries, "project.json"), "SB3 archive does not contain project.json.");
43
+ const project = JSON.parse(strFromU8(entries["project.json"]));
44
+ assert(isObject(project) && isObject(project.extensionURLs), "SB3 requires an extensionURLs object.");
45
+ return {
46
+ entries,
47
+ project,
48
+ urls: project.extensionURLs
49
+ };
50
+ }
51
+ function embeddedSource(urls, id) {
52
+ const dataUrl = urls[id];
53
+ assert(typeof dataUrl === "string" && dataUrl.startsWith("data:"), `Missing embedded extension: ${id}`);
54
+ const decoded = decodeExtensionDataUrl(dataUrl);
55
+ assert(decoded.mediaType === "text/javascript" || decoded.mediaType === "application/javascript", `Embedded extension must contain JavaScript: ${id}`);
56
+ const source = Buffer.from(decoded.source);
57
+ const literalId = source.toString("utf8").match(/getInfo\s*\(\)\s*\{\s*return\s*\{\s*"id"\s*:\s*"([a-z0-9]+)"/u)?.[1];
58
+ const actualId = extensionHeaderId(source) ?? literalId;
59
+ assert(actualId === id, `Embedded extension ID mismatch: expected ${id}, got ${actualId ?? "(missing)"}.`);
60
+ return source;
61
+ }
62
+ function runtimeVersion(source) {
63
+ const value = source.toString("utf8").match(/^\/\/ Version: (.+)\r?$/mu)?.[1]?.trim();
64
+ return value && valid(value) ? value : null;
65
+ }
66
+ async function download(url, limit, fetchImplementation) {
67
+ const response = await fetchImplementation(url, {
68
+ redirect: "error",
69
+ signal: AbortSignal.timeout(3e4),
70
+ cache: "no-store"
71
+ });
72
+ assert(response.ok, `Download failed (${response.status}): ${url}`);
73
+ assert(response.body, `Empty download: ${url}`);
74
+ const reader = response.body.getReader();
75
+ const chunks = [];
76
+ let size = 0;
77
+ try {
78
+ for (;;) {
79
+ const { done, value } = await reader.read();
80
+ if (done) break;
81
+ size += value.byteLength;
82
+ assert(size <= limit, `Download exceeds the size limit: ${url}`);
83
+ chunks.push(value);
84
+ }
85
+ } catch (error) {
86
+ await reader.cancel().catch(() => void 0);
87
+ throw error;
88
+ } finally {
89
+ reader.releaseLock();
90
+ }
91
+ return Buffer.concat(chunks, size);
92
+ }
93
+ async function publishedDonor(fetchImplementation) {
94
+ const manifest = JSON.parse((await download(defaultKamishibaiManifestUrl, 1048576, fetchImplementation)).toString("utf8"));
95
+ assert(isObject(manifest), "Invalid Kamishibai public surfaces manifest.");
96
+ assert(manifest.formatVersion === 1 && manifest.status === "published" && manifest.published === true, "Kamishibai donor must be a published format 1 release.");
97
+ assert(typeof manifest.version === "string" && valid(manifest.version), "Invalid published version.");
98
+ assert(isObject(manifest.runtime) && manifest.runtime.version === manifest.version, "Published runtime version mismatch.");
99
+ assert(isObject(manifest.surfaces) && typeof manifest.surfaces.sb3BlocksUrl === "string", "Missing published block SB3 URL.");
100
+ assert(isObject(manifest.artifacts) && isObject(manifest.artifacts.sb3Blocks), "Missing block SB3 artifact.");
101
+ const artifact = manifest.artifacts.sb3Blocks;
102
+ assert(typeof artifact.size === "number" && Number.isSafeInteger(artifact.size) && artifact.size > 0 && artifact.size <= archiveSizeLimit, "Invalid block SB3 size.");
103
+ assert(typeof artifact.sha256 === "string" && /^[a-f0-9]{64}$/u.test(artifact.sha256), "Invalid block SB3 SHA-256.");
104
+ const url = new URL(manifest.surfaces.sb3BlocksUrl);
105
+ const manifestUrl = new URL(defaultKamishibaiManifestUrl);
106
+ assert(url.origin === manifestUrl.origin && !url.username && !url.password && url.pathname.startsWith("/turbowarp-kamishibai-samples/"), "Block SB3 URL must remain on the official samples site.");
107
+ const archive = await download(url.href, archiveSizeLimit, fetchImplementation);
108
+ assert(archive.byteLength === artifact.size, "Downloaded block SB3 size mismatch.");
109
+ assert(sha256(archive) === artifact.sha256, "Downloaded block SB3 SHA-256 mismatch.");
110
+ return {
111
+ archive,
112
+ source: url.href,
113
+ version: manifest.version
114
+ };
115
+ }
116
+ async function assertDistinctOutput(outputPath, protectedPaths) {
117
+ for (const protectedPath of protectedPaths) {
118
+ assert(path.resolve(outputPath) !== path.resolve(protectedPath), "Output must differ from input and donor SB3 paths.");
119
+ try {
120
+ assert(await realpath(outputPath) !== await realpath(protectedPath), "Output must differ from input and donor SB3 paths.");
121
+ } catch (error) {
122
+ if (!isObject(error) || error.code !== "ENOENT") throw error;
123
+ }
124
+ }
125
+ }
126
+ /** Replaces the Kamishibai runtime bundle and Block Script without executing donor code. */
127
+ async function replaceSb3Extensions({ confirmReplace, fetch: fetchImplementation = globalThis.fetch, fromPath, inputPath, outputPath, yes = false }) {
128
+ const protectedPaths = fromPath ? [inputPath, fromPath] : [inputPath];
129
+ await assertDistinctOutput(outputPath, protectedPaths);
130
+ const input = parseArchive(await readArchive(inputPath));
131
+ const extensionIds = kamishibaiReplacementIds.filter((id) => Object.hasOwn(input.urls, id));
132
+ assert(extensionIds.length > 0, "Input contains no supported Kamishibai embedded extensions.");
133
+ const inputSources = new Map(extensionIds.map((id) => [id, embeddedSource(input.urls, id)]));
134
+ const donor = fromPath ? {
135
+ archive: await readArchive(fromPath),
136
+ source: path.resolve(fromPath),
137
+ version: null
138
+ } : await publishedDonor(fetchImplementation);
139
+ const replacement = parseArchive(donor.archive);
140
+ for (const id of extensionIds) embeddedSource(replacement.urls, id);
141
+ const runtimeId = kamishibaiReplacementIds[0];
142
+ const donorRuntime = Object.hasOwn(replacement.urls, runtimeId) ? embeddedSource(replacement.urls, runtimeId) : null;
143
+ const donorVersion = donor.version ?? (donorRuntime ? runtimeVersion(donorRuntime) : null);
144
+ if (!fromPath && donorVersion) {
145
+ const inputRuntime = inputSources.get(runtimeId);
146
+ const inputVersion = inputRuntime ? runtimeVersion(inputRuntime) : null;
147
+ assert(!inputVersion || !lt(donorVersion, inputVersion), `Published donor ${donorVersion} is older than input ${inputVersion}. Wait for publication or select an intentional donor with --from.`);
148
+ const declaredVersion = donorRuntime ? runtimeVersion(donorRuntime) : null;
149
+ assert(!declaredVersion || declaredVersion === donorVersion, "Donor runtime header does not match the published version.");
150
+ }
151
+ for (const id of extensionIds) input.urls[id] = replacement.urls[id];
152
+ input.entries["project.json"] = strToU8(`${JSON.stringify(input.project)}\n`);
153
+ const archive = zipSync(input.entries, {
154
+ level: 6,
155
+ mtime: fixedZipTimestamp
156
+ });
157
+ await assertDistinctOutput(outputPath, protectedPaths);
158
+ return {
159
+ ...await writeSb3Archive({
160
+ archive,
161
+ confirmReplace,
162
+ outputPath,
163
+ yes
164
+ }),
165
+ extensionIds,
166
+ donor: {
167
+ source: donor.source,
168
+ sha256: sha256(donor.archive),
169
+ version: donorVersion
170
+ }
171
+ };
172
+ }
173
+ //#endregion
174
+ export { defaultKamishibaiManifestUrl, kamishibaiReplacementIds, replaceSb3Extensions };
175
+
176
+ //# sourceMappingURL=extension-sb3-replacement.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"extension-sb3-replacement.js","names":[],"sources":["../src/extension-sb3-replacement.ts"],"sourcesContent":["// SPDX-License-Identifier: MPL-2.0\n\nimport {createHash} from 'node:crypto';\nimport {lstat, readFile, realpath} from 'node:fs/promises';\nimport path from 'node:path';\n\nimport {strFromU8, strToU8, unzipSync, zipSync} from 'fflate';\nimport {lt, valid} from 'semver';\n\nimport {validateArchiveEntryName} from './archive';\nimport {assert} from './assert';\nimport {writeSb3Archive} from './build';\nimport type {WriteSb3ArchiveOptions, WriteSb3ArchiveResult} from './build';\nimport {extensionHeaderId} from './extension-dependencies';\nimport type {FetchImplementation} from './extension-sync';\nimport {decodeExtensionDataUrl} from './import';\nimport {fixedZipTimestamp} from './source';\nimport type {UnknownRecord} from './types';\n\nexport const defaultKamishibaiManifestUrl =\n 'https://kubohiroya.github.io/turbowarp-kamishibai-samples/stories/tutorial/public-surfaces.json';\n\nexport const kamishibaiReplacementIds: readonly string[] = Object.freeze([\n 'kubohiroyakamishibai4',\n 'kubohiroyakamishibaiauthoring4',\n]);\n\nconst archiveSizeLimit = 64 * 1024 * 1024;\nconst expandedSizeLimit = 256 * 1024 * 1024;\n\nexport interface ReplaceSb3ExtensionsOptions {\n confirmReplace?: WriteSb3ArchiveOptions['confirmReplace'];\n fetch?: FetchImplementation;\n fromPath?: string;\n inputPath: string;\n outputPath: string;\n yes?: boolean;\n}\n\nexport interface ReplaceSb3ExtensionsResult extends WriteSb3ArchiveResult {\n extensionIds: string[];\n donor: {source: string; sha256: string; version: string | null};\n}\n\nfunction isObject(value: unknown): value is UnknownRecord {\n return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction sha256(contents: Uint8Array): string {\n return createHash('sha256').update(contents).digest('hex');\n}\n\nasync function readArchive(filePath: string): Promise<Buffer> {\n assert(path.extname(filePath).toLowerCase() === '.sb3', `Expected an .sb3 file: ${filePath}`);\n const stats = await lstat(filePath);\n assert(stats.isFile() && !stats.isSymbolicLink(), `Expected a regular SB3 file: ${filePath}`);\n assert(stats.size <= archiveSizeLimit, `SB3 exceeds the 64 MiB limit: ${filePath}`);\n return readFile(filePath);\n}\n\nfunction parseArchive(contents: Uint8Array) {\n const names = new Set<string>();\n let expandedSize = 0;\n const entries = unzipSync(contents, {\n filter: (entry) => {\n validateArchiveEntryName(entry.name);\n assert(!names.has(entry.name), `Duplicate SB3 archive entry: ${entry.name}`);\n assert(!/^(?:0|[1-9][0-9]*)$/u.test(entry.name), 'Integer ZIP entry names are unsupported.');\n names.add(entry.name);\n expandedSize += entry.originalSize;\n assert(\n names.size <= 4096 && expandedSize <= expandedSizeLimit,\n 'SB3 expansion limit exceeded.',\n );\n return true;\n },\n });\n assert(Object.hasOwn(entries, 'project.json'), 'SB3 archive does not contain project.json.');\n const project: unknown = JSON.parse(strFromU8(entries['project.json']));\n assert(\n isObject(project) && isObject(project.extensionURLs),\n 'SB3 requires an extensionURLs object.',\n );\n return {entries, project, urls: project.extensionURLs};\n}\n\nfunction embeddedSource(urls: UnknownRecord, id: string): Buffer {\n const dataUrl = urls[id];\n assert(\n typeof dataUrl === 'string' && dataUrl.startsWith('data:'),\n `Missing embedded extension: ${id}`,\n );\n const decoded = decodeExtensionDataUrl(dataUrl);\n assert(\n decoded.mediaType === 'text/javascript' || decoded.mediaType === 'application/javascript',\n `Embedded extension must contain JavaScript: ${id}`,\n );\n const source = Buffer.from(decoded.source);\n // Generated Block Script declares its ID in a literal getInfo() result, without a header.\n const literalId = source\n .toString('utf8')\n .match(/getInfo\\s*\\(\\)\\s*\\{\\s*return\\s*\\{\\s*\"id\"\\s*:\\s*\"([a-z0-9]+)\"/u)?.[1];\n const actualId = extensionHeaderId(source) ?? literalId;\n assert(\n actualId === id,\n `Embedded extension ID mismatch: expected ${id}, got ${actualId ?? '(missing)'}.`,\n );\n return source;\n}\n\nfunction runtimeVersion(source: Buffer): string | null {\n const value = source\n .toString('utf8')\n .match(/^\\/\\/ Version: (.+)\\r?$/mu)?.[1]\n ?.trim();\n return value && valid(value) ? value : null;\n}\n\nasync function download(\n url: string,\n limit: number,\n fetchImplementation: FetchImplementation,\n): Promise<Buffer> {\n const response = await fetchImplementation(url, {\n redirect: 'error',\n signal: AbortSignal.timeout(30_000),\n cache: 'no-store',\n });\n assert(response.ok, `Download failed (${response.status}): ${url}`);\n assert(response.body, `Empty download: ${url}`);\n const reader = response.body.getReader();\n const chunks: Uint8Array[] = [];\n let size = 0;\n try {\n for (;;) {\n const {done, value} = await reader.read();\n if (done) break;\n size += value.byteLength;\n assert(size <= limit, `Download exceeds the size limit: ${url}`);\n chunks.push(value);\n }\n } catch (error) {\n await reader.cancel().catch(() => undefined);\n throw error;\n } finally {\n reader.releaseLock();\n }\n return Buffer.concat(chunks, size);\n}\n\nasync function publishedDonor(fetchImplementation: FetchImplementation) {\n const manifest: unknown = JSON.parse(\n (await download(defaultKamishibaiManifestUrl, 1024 * 1024, fetchImplementation)).toString(\n 'utf8',\n ),\n );\n assert(isObject(manifest), 'Invalid Kamishibai public surfaces manifest.');\n assert(\n manifest.formatVersion === 1 && manifest.status === 'published' && manifest.published === true,\n 'Kamishibai donor must be a published format 1 release.',\n );\n assert(\n typeof manifest.version === 'string' && valid(manifest.version),\n 'Invalid published version.',\n );\n assert(\n isObject(manifest.runtime) && manifest.runtime.version === manifest.version,\n 'Published runtime version mismatch.',\n );\n assert(\n isObject(manifest.surfaces) && typeof manifest.surfaces.sb3BlocksUrl === 'string',\n 'Missing published block SB3 URL.',\n );\n assert(\n isObject(manifest.artifacts) && isObject(manifest.artifacts.sb3Blocks),\n 'Missing block SB3 artifact.',\n );\n const artifact = manifest.artifacts.sb3Blocks;\n assert(\n typeof artifact.size === 'number' &&\n Number.isSafeInteger(artifact.size) &&\n artifact.size > 0 &&\n artifact.size <= archiveSizeLimit,\n 'Invalid block SB3 size.',\n );\n assert(\n typeof artifact.sha256 === 'string' && /^[a-f0-9]{64}$/u.test(artifact.sha256),\n 'Invalid block SB3 SHA-256.',\n );\n const url = new URL(manifest.surfaces.sb3BlocksUrl);\n const manifestUrl = new URL(defaultKamishibaiManifestUrl);\n assert(\n url.origin === manifestUrl.origin &&\n !url.username &&\n !url.password &&\n url.pathname.startsWith('/turbowarp-kamishibai-samples/'),\n 'Block SB3 URL must remain on the official samples site.',\n );\n const archive = await download(url.href, archiveSizeLimit, fetchImplementation);\n assert(archive.byteLength === artifact.size, 'Downloaded block SB3 size mismatch.');\n assert(sha256(archive) === artifact.sha256, 'Downloaded block SB3 SHA-256 mismatch.');\n return {archive, source: url.href, version: manifest.version};\n}\n\nasync function assertDistinctOutput(outputPath: string, protectedPaths: string[]): Promise<void> {\n for (const protectedPath of protectedPaths) {\n assert(\n path.resolve(outputPath) !== path.resolve(protectedPath),\n 'Output must differ from input and donor SB3 paths.',\n );\n try {\n assert(\n (await realpath(outputPath)) !== (await realpath(protectedPath)),\n 'Output must differ from input and donor SB3 paths.',\n );\n } catch (error) {\n if (!isObject(error) || error.code !== 'ENOENT') throw error;\n }\n }\n}\n\n/** Replaces the Kamishibai runtime bundle and Block Script without executing donor code. */\nexport async function replaceSb3Extensions({\n confirmReplace,\n fetch: fetchImplementation = globalThis.fetch,\n fromPath,\n inputPath,\n outputPath,\n yes = false,\n}: ReplaceSb3ExtensionsOptions): Promise<ReplaceSb3ExtensionsResult> {\n const protectedPaths = fromPath ? [inputPath, fromPath] : [inputPath];\n await assertDistinctOutput(outputPath, protectedPaths);\n const input = parseArchive(await readArchive(inputPath));\n const extensionIds = kamishibaiReplacementIds.filter((id) => Object.hasOwn(input.urls, id));\n assert(extensionIds.length > 0, 'Input contains no supported Kamishibai embedded extensions.');\n const inputSources = new Map(extensionIds.map((id) => [id, embeddedSource(input.urls, id)]));\n const donor = fromPath\n ? {archive: await readArchive(fromPath), source: path.resolve(fromPath), version: null}\n : await publishedDonor(fetchImplementation);\n const replacement = parseArchive(donor.archive);\n for (const id of extensionIds) embeddedSource(replacement.urls, id);\n const runtimeId = kamishibaiReplacementIds[0];\n const donorRuntime = Object.hasOwn(replacement.urls, runtimeId)\n ? embeddedSource(replacement.urls, runtimeId)\n : null;\n const donorVersion = donor.version ?? (donorRuntime ? runtimeVersion(donorRuntime) : null);\n if (!fromPath && donorVersion) {\n const inputRuntime = inputSources.get(runtimeId);\n const inputVersion = inputRuntime ? runtimeVersion(inputRuntime) : null;\n assert(\n !inputVersion || !lt(donorVersion, inputVersion),\n `Published donor ${donorVersion} is older than input ${inputVersion}. Wait for publication or select an intentional donor with --from.`,\n );\n const declaredVersion = donorRuntime ? runtimeVersion(donorRuntime) : null;\n assert(\n !declaredVersion || declaredVersion === donorVersion,\n 'Donor runtime header does not match the published version.',\n );\n }\n for (const id of extensionIds) input.urls[id] = replacement.urls[id];\n input.entries['project.json'] = strToU8(`${JSON.stringify(input.project)}\\n`);\n const archive = zipSync(input.entries, {level: 6, mtime: fixedZipTimestamp});\n await assertDistinctOutput(outputPath, protectedPaths);\n const written = await writeSb3Archive({archive, confirmReplace, outputPath, yes});\n return {\n ...written,\n extensionIds,\n donor: {source: donor.source, sha256: sha256(donor.archive), version: donorVersion},\n };\n}\n"],"mappings":"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"}
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- export type { EmbeddedExtension, EmbeddedExtensionManifest, ExtensionApiManifestSource, ExtensionBundleConfiguration, ExtensionEncoding, ExtensionModuleSource, ExtensionSource, GitHubExtensionSource, NpmExtensionSource, ProjectAssetReference, ProjectJson, ProjectTarget, Sb3SourceManifest, } from './types';
1
+ export type { EmbeddedExtension, EmbeddedExtensionManifest, ExtensionApiManifestSource, ExtensionBundleConfiguration, ExtensionBundleMetadata, ExtensionEncoding, ExtensionModuleSource, ExtensionSource, GitHubExtensionSource, NpmExtensionSource, ProjectAssetReference, ProjectJson, ProjectTarget, Sb3SourceManifest, } from './types';
2
2
  export { assert } from './assert';
3
3
  export { validateArchiveEntryName } from './archive';
4
4
  export { buildSb3 } from './build';
@@ -32,3 +32,5 @@ export type { ProjectAssetAdditionsSummary } from './project-asset-additions';
32
32
  export type { Sb3ReleaseSnapshotMetadata } from './release-snapshot';
33
33
  export type { DeterministicSb3, InspectedSb3Source } from './source';
34
34
  export type { TurboWarpCleanUpResult } from './turbowarp-clean-up';
35
+ export { defaultKamishibaiManifestUrl, kamishibaiReplacementIds, replaceSb3Extensions, } from './extension-sb3-replacement';
36
+ export type { ReplaceSb3ExtensionsOptions, ReplaceSb3ExtensionsResult, } from './extension-sb3-replacement';
package/dist/index.js CHANGED
@@ -14,6 +14,7 @@ import { decodeExtensionDataUrl, importSb3 } from "./import.js";
14
14
  import { planBundledSb3Unbundle, unbundleSb3 } from "./extension-bundle-archive.js";
15
15
  import { bundleExtensions, planExtensionBundle, planExtensionUnbundle, unbundleExtensions } from "./extension-bundle-configuration.js";
16
16
  import { migrateExtensionId, planExtensionIdMigration, validateNewExtensionId } from "./extension-id-migration.js";
17
+ import { defaultKamishibaiManifestUrl, kamishibaiReplacementIds, replaceSb3Extensions } from "./extension-sb3-replacement.js";
17
18
  import { defaultExtensionArtifactSizeLimit, extensionStatus, syncExtensions, updateExtensions } from "./extension-sync.js";
18
19
  import { assertSb3ReleaseSnapshotMetadata, computeReleaseSourceIdentity, createSb3ReleaseSnapshot, createSb3ReleaseSnapshotMetadata, freezeSb3ReleaseSnapshot, readSb3ReleaseSnapshotMetadata, recordPublishedSb3ReleaseSnapshot, verifySb3ReleaseSnapshot, writeSb3ReleaseCandidate } from "./release-snapshot.js";
19
- export { applyProjectAssetAdditions, assert, assertSb3ReleaseSnapshotMetadata, buildExtensionBundles, buildExtensionBundlesWithModules, buildSb3, bundleExtensions, bundleUnsandboxedRequirement, cleanUpTurboWarpBlocks, compareDirectories, compareExtensionApiManifests, computeReleaseSourceIdentity, createDeterministicSb3, createSb3ReleaseSnapshot, createSb3ReleaseSnapshotMetadata, createStaticExtensionBundle, decodeExtensionDataUrl, defaultExtensionApiManifestSizeLimit, defaultExtensionArtifactSizeLimit, defaultSandboxedNotices, extensionApiManifestEffects, extensionApiManifestFormatVersion, extensionApiManifestFormatVersions, extensionApiManifestIntegrity, extensionApiManifestLocalPath, extensionApiManifestResultTypes, extensionBundleRecoveryMarker, extensionHeaderId, extensionHeaderMetadata, extensionIntegrity, extensionStatus, fixedZipTimestamp, formatExtensionApiCompatibilityChanges, freezeSb3ReleaseSnapshot, importSb3, inspectGitOutputState, migrateExtensionId, packageName, packageVersion, parseExtensionApiManifest, planBundledSb3Unbundle, planExtensionBundle, planExtensionIdMigration, planExtensionUnbundle, projectAssetAdditionsFormatVersion, readSb3ReleaseSnapshotMetadata, recordPublishedSb3ReleaseSnapshot, sourceFormatVersion, syncExtensions, tryParseExtensionApiManifest, turboWarpCleanUpLayout, unbundleExtensions, unbundleSb3, unsandboxedRequirement, unsandboxedRequirements, updateExtensions, validateArchiveEntryName, validateExtensionApiManifestSourceMetadata, validateExtensionBundleConfigurations, validateExtensionSourceMetadata, validateManagedExtensionApiManifest, validateManagedExtensionContents, validateNewExtensionId, validateOutputDirectoryPath, validateSb3Source, verifySb3ReleaseSnapshot, writeSb3ReleaseCandidate };
20
+ export { applyProjectAssetAdditions, assert, assertSb3ReleaseSnapshotMetadata, buildExtensionBundles, buildExtensionBundlesWithModules, buildSb3, bundleExtensions, bundleUnsandboxedRequirement, cleanUpTurboWarpBlocks, compareDirectories, compareExtensionApiManifests, computeReleaseSourceIdentity, createDeterministicSb3, createSb3ReleaseSnapshot, createSb3ReleaseSnapshotMetadata, createStaticExtensionBundle, decodeExtensionDataUrl, defaultExtensionApiManifestSizeLimit, defaultExtensionArtifactSizeLimit, defaultKamishibaiManifestUrl, defaultSandboxedNotices, extensionApiManifestEffects, extensionApiManifestFormatVersion, extensionApiManifestFormatVersions, extensionApiManifestIntegrity, extensionApiManifestLocalPath, extensionApiManifestResultTypes, extensionBundleRecoveryMarker, extensionHeaderId, extensionHeaderMetadata, extensionIntegrity, extensionStatus, fixedZipTimestamp, formatExtensionApiCompatibilityChanges, freezeSb3ReleaseSnapshot, importSb3, inspectGitOutputState, kamishibaiReplacementIds, migrateExtensionId, packageName, packageVersion, parseExtensionApiManifest, planBundledSb3Unbundle, planExtensionBundle, planExtensionIdMigration, planExtensionUnbundle, projectAssetAdditionsFormatVersion, readSb3ReleaseSnapshotMetadata, recordPublishedSb3ReleaseSnapshot, replaceSb3Extensions, sourceFormatVersion, syncExtensions, tryParseExtensionApiManifest, turboWarpCleanUpLayout, unbundleExtensions, unbundleSb3, unsandboxedRequirement, unsandboxedRequirements, updateExtensions, validateArchiveEntryName, validateExtensionApiManifestSourceMetadata, validateExtensionBundleConfigurations, validateExtensionSourceMetadata, validateManagedExtensionApiManifest, validateManagedExtensionContents, validateNewExtensionId, validateOutputDirectoryPath, validateSb3Source, verifySb3ReleaseSnapshot, writeSb3ReleaseCandidate };
package/dist/types.d.ts CHANGED
@@ -39,10 +39,24 @@ export interface EmbeddedExtension {
39
39
  encoding: ExtensionEncoding;
40
40
  source?: ExtensionSource;
41
41
  }
42
+ /** Explicit presentation of the bundle itself, independent of its member packages. */
43
+ export interface ExtensionBundleMetadata {
44
+ description?: string;
45
+ descriptions?: Record<string, string>;
46
+ author?: string;
47
+ authorURL?: string;
48
+ version?: string;
49
+ updatedAt?: string;
50
+ repository?: string;
51
+ docsURL?: string;
52
+ banner?: string;
53
+ package?: string;
54
+ }
42
55
  export interface ExtensionBundleConfiguration {
43
56
  id: string;
44
57
  name: string;
45
58
  members: string[];
59
+ metadata?: ExtensionBundleMetadata;
46
60
  recoveryCapsule?: boolean;
47
61
  sandboxedNotice?: Record<string, string>;
48
62
  blockEditorRegistrations?: boolean;
@@ -68,6 +68,36 @@ sb3-toolchain build app --output dist/project.sb3
68
68
  `bundleExtensions` and `planExtensionBundle` also accept `buildMode` and `sharedDependencies`.
69
69
  Repeat `--share` for additional packages. GUI editor adaptation remains an explicit manifest option.
70
70
 
71
+ The bundle's optional `metadata` describes the complete bundle, rather than its first member:
72
+
73
+ ```json
74
+ {
75
+ "description": "The complete application extension.",
76
+ "descriptions": {"ja": "アプリ全体の機能拡張。"},
77
+ "author": "Application Author",
78
+ "authorURL": "https://example.com/author",
79
+ "version": "1.2.3",
80
+ "repository": "https://github.com/example/application",
81
+ "docsURL": "https://example.com/docs/",
82
+ "banner": "https://example.com/banner.png",
83
+ "package": "@example/application"
84
+ }
85
+ ```
86
+
87
+ Put this object in `extensionBundles[].metadata`, pass `metadata` to `bundleExtensions` or
88
+ `planExtensionBundle`, or use `--metadata-json '{"version":"1.2.3"}'` with the bundle command.
89
+ The exported `ExtensionBundleMetadata` type also accepts `updatedAt`. Fields are single lines of at
90
+ most 1000 characters. Locale keys are lowercase language tags. Repository and documentation URLs
91
+ use HTTPS; author URLs allow HTTP or HTTPS and require an explicit author in the same object.
92
+ Banners allow HTTPS or image data URLs for PNG, JPEG, GIF, WebP, or SVG; the data URL prefix is
93
+ normalized to lowercase. Invalid values, credentials, and unknown fields are rejected.
94
+
95
+ These fields become comment headers in both classic and module bundles, without executing members
96
+ to obtain display information. Name and ID remain bundle settings; licenses and sandbox requirements
97
+ remain derived from members. No package or author URL is inferred from a member. Omitting `metadata`
98
+ retains the existing generated bytes; removing it restores that output for future builds. Previously
99
+ frozen release artifacts must retain their original bytes.
100
+
71
101
  The resolver checks the selected version against each importer's declared range and uses one real
72
102
  package under browser conditions. yaml must use its browser entry; duplicate copies or mixed Node
73
103
  and browser graphs fail. Missing entries, mismatched package versions, classic artifacts, module
package/docs/index.html CHANGED
@@ -69,7 +69,7 @@
69
69
  <body>
70
70
  <header>
71
71
  <h1>SB3 Toolchain</h1>
72
- <p><code>@kubohiroya/sb3-toolchain@0.19.0</code></p>
72
+ <p><code>@kubohiroya/sb3-toolchain@0.20.0</code></p>
73
73
  <nav aria-label="Documentation">
74
74
  <a href="#scope">責務</a><a href="#usage">使い方</a><a href="#api">API</a
75
75
  ><a href="#schemas">Schema</a><a href="#guides">関連文書</a>
@@ -90,7 +90,7 @@
90
90
  <section id="usage">
91
91
  <h2>使い方</h2>
92
92
  <p>公開済みの完全固定versionを使います。</p>
93
- <pre><code>npm install --save-exact @kubohiroya/sb3-toolchain@0.19.0</code></pre>
93
+ <pre><code>npm install --save-exact @kubohiroya/sb3-toolchain@0.20.0</code></pre>
94
94
  <pre><code>sb3-toolchain import tmp/project.sb3 --output app
95
95
  sb3-toolchain check app
96
96
  sb3-toolchain build app --output dist/project.sb3</code></pre>
@@ -64,6 +64,36 @@ sb3-toolchain build app --output dist/project.sb3
64
64
  APIは`bundleExtensions` / `planExtensionBundle`の`buildMode`と`sharedDependencies`でも指定できます。
65
65
  `--share`は複数指定でき、完全な版番号を要求します。GUIの編集登録変換は従来どおりmanifestで明示選択します。
66
66
 
67
+ 任意の`metadata`は、先頭メンバーではなくbundle全体の表示情報を明示します。
68
+
69
+ ```json
70
+ {
71
+ "description": "The complete application extension.",
72
+ "descriptions": {"ja": "アプリ全体の機能拡張。"},
73
+ "author": "Application Author",
74
+ "authorURL": "https://example.com/author",
75
+ "version": "1.2.3",
76
+ "repository": "https://github.com/example/application",
77
+ "docsURL": "https://example.com/docs/",
78
+ "banner": "https://example.com/banner.png",
79
+ "package": "@example/application"
80
+ }
81
+ ```
82
+
83
+ このobjectを`extensionBundles[].metadata`へ保存するか、APIの`bundleExtensions`/
84
+ `planExtensionBundle`へ`metadata`として渡します。CLIではbundleコマンドに
85
+ `--metadata-json '{"version":"1.2.3"}'`を指定します。公開型`ExtensionBundleMetadata`は
86
+ `updatedAt`も受け付けます。各値は1000文字以内の単行で、localeは小文字の言語タグです。
87
+ repository/docsURLはHTTPS、authorURLはHTTPまたはHTTPSとし、同じobjectにauthorも明示します。
88
+ bannerはHTTPSまたはPNG/JPEG/GIF/WebP/SVGの画像data URIを受け付け、data URIのprefixを
89
+ 小文字に正規化します。不正な値・認証情報付きURL・未定義fieldは拒否します。
90
+
91
+ classic/moduleの両方でコメントheaderへ出力し、表示情報を得るためにメンバーを実行しません。
92
+ 名前とIDは従来のbundle設定、ライセンスと実行要件は従来のメンバー集約を維持します。
93
+ メンバーのpackageやauthorURLをbundle全体へ推測適用しません。metadataを省略した場合の
94
+ 生成bytesは従来どおりです。metadataを外すと以後のbuildは従来出力に戻せますが、凍結済みの
95
+ リリース成果物は元のbytesを保持してください。
96
+
67
97
  共有packageの要求範囲と選択版を照合し、browser条件で同じ実体へ解決します。yamlはbrowser入口に限定し、
68
98
  別コピーやNode向け実装が混ざるgraphを拒否します。版・classicとの一致・module integrity・対応入口不足も診断します。
69
99
  必要なunsandboxed権限を得られなければ、ライブラリ評価やfactory生成より前に従来の案内拡張だけを登録します。
@@ -0,0 +1,41 @@
1
+ # Kamishibai作品SB3の埋め込み機能拡張を一括更新する
2
+
3
+ ```sh
4
+ sb3-toolchain extensions replace-sb3 ari-kirigirisu-20161029.sb3 --output ari-kirigirisu-updated.sb3
5
+ ```
6
+
7
+ `--from`を省略すると、[公式サンプルサイトの公開マニフェスト](https://kubohiroya.github.io/turbowarp-kamishibai-samples/stories/tutorial/public-surfaces.json)から
8
+ ブロック台本SB3のURLを解決し、自動取得します。公開済み状態・バージョンの整合性・ダウンロードしたSB3のサイズとSHA-256を検証してから、入力作品にある次の実装を差し替えます。
9
+
10
+ - `kubohiroyakamishibai4`: Kamishibai DSL 4.0 Runtimeを含むバンドル全体
11
+ - `kubohiroyakamishibaiauthoring4`: Kamishibai Block Script
12
+
13
+ 入力に両方あれば、同じ提供元SB3から両方を更新します。片方だけなら、その機能拡張だけを更新します。提供元に必要なIDがない場合は停止します。取得したコードは実行しません。
14
+
15
+ 取得するのはサンプルサイトで現在公開されているブロック台本です。開発中の候補版は使いません。アプリ本体だけが先に公開され、サンプルサイトの更新がまだの場合は、その本体版を取得できません。公開版が入力のRuntimeヘッダーに記載された版より古い場合は、自動ダウングレードを防ぐため停止します。入力にバージョンヘッダーがない場合は、新旧の比較を省略します。
16
+
17
+ 提供元を手元のファイルに固定する場合は、`--from`を指定します。この場合、ネットワーク通信は不要です。明示的に古い提供元を選ぶこともできます。
18
+
19
+ ```sh
20
+ sb3-toolchain extensions replace-sb3 input.sb3 --from 新版のブロック台本.sb3 --output updated.sb3
21
+ ```
22
+
23
+ 元ファイルを保護するため、入力と提供元は出力先に指定できません。既存の出力内容が異なる場合は、対話確認または`--yes`が必要です。検証失敗時には出力を変更しません。元の作品を開けば更新前の状態に戻れます。
24
+
25
+ 変更するのは`project.json`内の対象IDの`extensionURLs`の値です。その他の機能拡張、ブロック、座標、変数、リスト、`extensionStorage`、素材、および追加のZIPエントリーは保持します。ZIPの圧縮とタイムスタンプ、`project.json`の文字列表現は再生成します。出力には提供元・公開版・SHA-256・更新対象IDを表示します。ローカル提供元にバージョンヘッダーがない場合は`unknown`と表示します。
26
+
27
+ このコマンドはDSLや保存データの移行を行いません。例えば`/assets/SafetyPose`の参照が作品の保存データに残っている場合、そのデータは保持されます。コードの置換だけでは、旧版とのDSL互換性や再生の成功を保証できません。更新後の作品をエディターで再生して確認してください。
28
+
29
+ 入力・提供元の圧縮サイズは64 MiB、展開サイズは256 MiB、ZIPエントリー数は4096までです。ネットワーク取得には各30秒のタイムアウトを設け、マニフェストは1 MiBまで受け付けます。
30
+
31
+ JavaScript APIでも同じ処理を利用できます。
32
+
33
+ ```js
34
+ import {replaceSb3Extensions} from '@kubohiroya/sb3-toolchain';
35
+
36
+ const result = await replaceSb3Extensions({
37
+ inputPath: 'input.sb3',
38
+ outputPath: 'updated.sb3',
39
+ });
40
+ console.log(result.donor, result.extensionIds);
41
+ ```
@@ -1,5 +1,7 @@
1
1
  # SB3ソース管理ワークフロー
2
2
 
3
+ Kamishibai作品SB3に埋め込まれた実装を一括更新する場合は、[SB3の機能拡張更新](sb3-extension-replacement.md)を参照してください。
4
+
3
5
  [English](../workflows.md)
4
6
 
5
7
  この文書では、Scratch 3またはTurboWarpのSB3をGit内の展開ソースとして管理し、検証済みSB3を再ビルドする
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kubohiroya/sb3-toolchain",
3
- "version": "0.19.0",
3
+ "version": "0.20.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",
@@ -85,9 +85,9 @@
85
85
  "source-control",
86
86
  "reproducible-builds"
87
87
  ],
88
- "gitHead": "b69f3f7e088d8b055aacc5aea3af3f44f0f09d1f",
88
+ "gitHead": "80bdc3d0bf282234223257aca23c6a79fe31e9c6",
89
89
  "x-turbowarp-source": {
90
- "revision": "b69f3f7e088d8b055aacc5aea3af3f44f0f09d1f",
90
+ "revision": "80bdc3d0bf282234223257aca23c6a79fe31e9c6",
91
91
  "revisionRole": "base-commit",
92
92
  "sourceState": "local-release-overlay"
93
93
  }