From 4114d32c0e5c98bdf5fbe071adcd8ed59963a9cf Mon Sep 17 00:00:00 2001 From: Aleksandr Shevchuk Date: Thu, 19 Nov 2026 13:13:04 +0200 Subject: [PATCH 1/2] feat(author): build the one-file tool in the package, not on the organisation's site (#247) prepack runs scripts/build-tool.mjs: Vite bundles the command line and everything it imports into dist/h5p-author.mjs, with dist/h5p-author-LICENSES.txt, as the site's own build did, and checks its --version. The npm package then covers the bytes route 3 runs, with its provenance once publishing moves to CI, and the site serves them as shipped. --- design/author.md | 10 +++++- design/layout.md | 3 +- packages/author/README.md | 5 ++- packages/author/bin/h5p-author.mjs | 5 +-- packages/author/lib/node.mjs | 6 ++-- packages/author/package.json | 5 ++- packages/author/scripts/build-tool.mjs | 49 ++++++++++++++++++++++++++ packages/author/tests/bundle.test.ts | 19 ++++++++++ pnpm-lock.yaml | 3 ++ 9 files changed, 96 insertions(+), 9 deletions(-) create mode 100644 packages/author/scripts/build-tool.mjs diff --git a/design/author.md b/design/author.md index 9be9c862..cc842561 100644 --- a/design/author.md +++ b/design/author.md @@ -294,11 +294,19 @@ text to the content check's rules, and `apps/skills` plays every example untrust in a bundle: H5P.MathDisplay, 2.8 MB, is fetched where text holds math. With pack 1.1.0 a question type's bundle is 0.6 to 1.5 MB, a Question Set's 2.6, a container's 4.3 to 8.4, and the 55 types' 99 MB in all, more than jsDelivr's 50 MB cap, so the organisation's site serves - them at `/h5p/bundles/`. The build tool beside them is the command line as one file, 575 kB, + them at `/h5p/bundles/`. The build tool beside them is the command line as one file, 756 kB, which builds from an unzipped bundle with nothing installed. Its version is an import the bundler writes into the file; where the packages are installed their `package.json` files are read first, since Node before 22.12 warns on a JSON import, and a `package.json` above the one file that is not this package's is passed over. +- **This package builds the one-file tool, and the site serves it as shipped** (#247). `prepack` + runs `scripts/build-tool.mjs`. It bundles the command line and everything it imports with Vite + into `dist/h5p-author.mjs`, writes `dist/h5p-author-LICENSES.txt` beside it, and checks that its + `--version` names this package's and its pack's. Up to author 0.13.0 the site's own Vite built + it, so the site's build tools and their updates were in the path of every byte route 3 runs, and + nothing published covered them. Now the npm package does, with its provenance once publishing + moves to CI (#246). The skill names no hash of the file: checking one would add a command to + every run of route 3, and copies of the skill installed earlier would stop at each release. - **A preview inside Claude is the desktop app's browser panel, not a card.** A connector's card in Claude is an iframe under Claude's policy: it can register no worker, and Claude drops `frameDomains`, so neither the player's page nor a YouTube frame opens in it. The desktop app's diff --git a/design/layout.md b/design/layout.md index 810842e5..782cf047 100644 --- a/design/layout.md +++ b/design/layout.md @@ -32,7 +32,8 @@ packages/author/ a playable .h5p from a short source: lib/build.mjs both b Node's, generator.mjs content from semantics, check.mjs, outline.mjs, types.mjs the editor widgets' rules, mistakes.mjs the notes of what is almost surely a mistake, read.mjs a package back to a source; - scripts/ the skill's sync and copy + scripts/ the skill's sync and copy, and build-tool.mjs the command line + as one file (dist/) packages/mcp/ the local MCP server: bin/h5p-mcp.mjs the command, lib/server.mjs its four tools, lib/folders.mjs the folders it may use packages/cmi5/ the element as a cmi5 AU: src/index.ts startCmi5, src/client.ts the protocol diff --git a/packages/author/README.md b/packages/author/README.md index 5f0c7044..a04f6d9e 100644 --- a/packages/author/README.md +++ b/packages/author/README.md @@ -147,7 +147,10 @@ serve the skill from the release it pins: [missing-elements.github.io](https://missing-elements.github.io/h5p/create-with-ai/#install) packs them as the zips chat apps install, and lists the build tool and each bundle that the skill's route 3, from two files, fetches at -[missing-elements.github.io/h5p/skill/](https://missing-elements.github.io/h5p/skill/). +[missing-elements.github.io/h5p/skill/](https://missing-elements.github.io/h5p/skill/). The build +tool is in the package too: `dist/h5p-author.mjs` is the command line as one file, everything it +imports bundled in, and `dist/h5p-author-LICENSES.txt` lists those packages' licences. The site +serves both as the release has them. ## A package back to its source diff --git a/packages/author/bin/h5p-author.mjs b/packages/author/bin/h5p-author.mjs index e0fd4989..d5dcfd8b 100755 --- a/packages/author/bin/h5p-author.mjs +++ b/packages/author/bin/h5p-author.mjs @@ -38,8 +38,9 @@ const sized = (bytes) => (bytes < 1_000_000 ? `${Math.max(1, Math.round(bytes / /** * This package's version, from its package.json where the package is installed. The command line - * as one file, which the organisation's site bundles, has no package.json of its own beside it, and - * the one above it may be another's: there it is the copy its bundler wrote in from the import. + * as one file (`scripts/build-tool.mjs`), copied out of the package, has no package.json of its own + * beside it, and the one above it may be another's: there it is the copy its bundler wrote in from + * the import. * The file comes first, since Node before 22.12 warns on a JSON import. */ async function ownVersion() { diff --git a/packages/author/lib/node.mjs b/packages/author/lib/node.mjs index 21a76bcd..0f5b710b 100644 --- a/packages/author/lib/node.mjs +++ b/packages/author/lib/node.mjs @@ -94,9 +94,9 @@ export async function openPack(folder) { /** * The pinned pack's version, for messages and reports, from the libraries package's package.json - * where it is installed beside this one. The command line as one file, which the organisation's - * site bundles, has no package beside it: there it is the copy its bundler wrote in from the - * import. The file comes first, since Node before 22.12 warns on a JSON import. + * where it is installed beside this one. The command line as one file (`scripts/build-tool.mjs`), + * copied out of the package, has no package beside it: there it is the copy its bundler wrote in + * from the import. The file comes first, since Node before 22.12 warns on a JSON import. */ export async function packVersion() { try { diff --git a/packages/author/package.json b/packages/author/package.json index f4c254ff..7798726c 100644 --- a/packages/author/package.json +++ b/packages/author/package.json @@ -41,6 +41,7 @@ }, "files": [ "bin", + "dist", "lib", "references", "types", @@ -60,8 +61,9 @@ "test": "pnpm --filter @missing-elements/h5p-offline-player build && vitest run", "test:unit": "pnpm --filter @missing-elements/h5p-offline-player build:plan && vitest run --project node", "typecheck": "pnpm types && tsc -p tsconfig.json", + "build:tool": "pnpm --filter @missing-elements/h5p-offline-player build:plan && node scripts/build-tool.mjs", "sync:skill": "pnpm --filter @missing-elements/h5p-offline-player build:plan && node scripts/sync-skill.mjs", - "prepack": "node -e \"require('node:fs').copyFileSync('../../LICENSE', 'LICENSE')\" && node scripts/copy-skill.mjs && pnpm types", + "prepack": "node -e \"require('node:fs').copyFileSync('../../LICENSE', 'LICENSE')\" && node scripts/copy-skill.mjs && pnpm types && pnpm build:tool", "prepublishOnly": "node -e \"if (!/^pnpm\\//.test(process.env.npm_config_user_agent || '')) { console.error('Publish with pnpm publish: npm would ship the workspace: dependency ranges as they are, and the package would not install.'); process.exit(1) }\" && node scripts/check-pack-published.mjs && pnpm typecheck && pnpm test", "types": "pnpm --filter @missing-elements/h5p-offline-player exec tsc -b && node -e \"require('node:fs').rmSync('types', { recursive: true, force: true })\" && tsc -p tsconfig.types.json" }, @@ -79,6 +81,7 @@ "@vitest/browser-playwright": "^5.1.0", "playwright": "^1.65.1", "typescript": "^7.0.2", + "vite": "^8.3.8", "vitest": "^5.1.0" }, "engines": { diff --git a/packages/author/scripts/build-tool.mjs b/packages/author/scripts/build-tool.mjs new file mode 100644 index 00000000..22d555de --- /dev/null +++ b/packages/author/scripts/build-tool.mjs @@ -0,0 +1,49 @@ +import { execFileSync } from 'node:child_process' +import { readFile, rm } from 'node:fs/promises' +import { join, resolve } from 'node:path' +import { fileURLToPath } from 'node:url' +import { build } from 'vite' + +/** + * The command line as one file, `h5p-author.mjs`, and `h5p-author-LICENSES.txt`, every package + * bundled into it with its licence, since MIT and BSD-3-Clause ask their notices to travel with + * copies (#247). Route 3 of the skill runs the file with nothing installed, from an unzipped bundle, + * and the organisation's site serves it as this package ships it, so the npm package, and its + * provenance, cover the bytes a chat runs. Everything it imports is bundled in by Vite, with copies + * of the two package.json files it reads its versions from where neither is beside it + * (h5p-toolkit#198). It takes `--libraries`: the pinned pack is not with it. + * + * `pnpm build:tool` builds the player's plan, which it imports, first; `prepack` runs that. + * `node scripts/build-tool.mjs [folder]` writes the two files in `folder`, by default `dist/`. + */ +const root = resolve(import.meta.dirname, '..') +const folder = resolve(process.argv[2] ?? join(root, 'dist')) +const TOOL = 'h5p-author.mjs' +const LICENSES = 'h5p-author-LICENSES.txt' + +for (const file of [TOOL, LICENSES]) await rm(join(folder, file), { force: true }) +await build({ + configFile: false, + root, + logLevel: 'warn', + publicDir: false, + build: { + ssr: join(root, 'bin', TOOL), + outDir: folder, + emptyOutDir: false, + copyPublicDir: false, + minify: false, + license: { fileName: LICENSES }, + reportCompressedSize: false, + rolldownOptions: { output: { entryFileNames: TOOL, format: 'es', codeSplitting: false } } + }, + ssr: { noExternal: true, target: 'node' } +}) + +// The tool says its own versions, as a model checking it first asks: this package's and its pack's. +const version = async (/** @type {string} */ path) => JSON.parse(await readFile(path, 'utf8')).version +const pack = fileURLToPath(import.meta.resolve('@missing-elements/h5p-libraries/package.json')) +const expected = `@missing-elements/h5p-author ${await version(join(root, 'package.json'))}, library pack ${await version(pack)}` +const printed = execFileSync(process.execPath, [join(folder, TOOL), '--version'], { encoding: 'utf8' }).trim() +if (printed !== expected) throw new Error(`${TOOL} --version printed "${printed}", not "${expected}"`) +console.log(`Built ${join(folder, TOOL)}: ${printed}`) diff --git a/packages/author/tests/bundle.test.ts b/packages/author/tests/bundle.test.ts index 97b4c626..d05264ca 100644 --- a/packages/author/tests/bundle.test.ts +++ b/packages/author/tests/bundle.test.ts @@ -226,3 +226,22 @@ describe('the bundle command', () => { // Every content type's bundle, written twice: 2.2 s here, past vitest's 5 s once on a slow runner (#242). }, 20_000) }) + +describe('the command line as one file', () => { + // Route 3's two files (#247): the tool as the package ships it, and a bundle, unzipped in a + // folder with no package.json above it and nothing installed, as a chat's sandbox has them. + it('builds from a bundle where nothing is installed, and says its versions', async () => { + const built = join(dir, 'tool') + await exec(process.execPath, [resolve(import.meta.dirname, '../scripts/build-tool.mjs'), built]) + expect(await readFile(join(built, 'h5p-author-LICENSES.txt'), 'utf8')).toMatch(/^## @zip\.js\/zip\.js - [\d.]+ \(BSD-3-Clause\)$/m) + const sandbox = await unzip((await writeBundle('H5P.QuestionSet', join(dir, 'route3.zip'))).output, 'route3') + await copyFile(join(built, 'h5p-author.mjs'), join(sandbox, 'h5p-author.mjs')) + const version = async (path: string) => JSON.parse(await readFile(path, 'utf8')).version + const { stdout: versions } = await exec(process.execPath, ['h5p-author.mjs', '--version'], { cwd: sandbox }) + expect(versions).toBe(`@missing-elements/h5p-author ${await version(resolve(import.meta.dirname, '../package.json'))}, library pack ${await version(join(parts, '../package.json'))}\n`) + await writeFile(join(sandbox, 'quiz.json'), JSON.stringify(QUIZ)) + const { stdout } = await exec(process.execPath, ['h5p-author.mjs', 'build', 'quiz.json', 'quiz.h5p', '--libraries', 'parts'], { cwd: sandbox }) + expect(stdout).toMatch(/^Built \S+quiz\.h5p: H5P\.QuestionSet, \d+ libraries from the pack in parts, \d+ more for installing on an H5P site\.\n/) + expect((await stat(join(sandbox, 'quiz.h5p'))).size).toBeGreaterThan(0) + }, 60_000) +}) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index a99106fd..a5aef166 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -124,6 +124,9 @@ importers: typescript: specifier: ^7.0.2 version: 7.0.2 + vite: + specifier: ^8.3.8 + version: 8.3.8(@types/node@26.6.6)(esbuild@0.28.2) vitest: specifier: ^5.1.0 version: 5.1.0(@types/node@26.6.6)(@vitest/browser-playwright@5.1.0)(@vitest/ui@5.1.0)(vite@8.3.8(@types/node@26.6.6)(esbuild@0.28.2)) From 4c36491968c27cf0c790f37e15004fbfef821cb8 Mon Sep 17 00:00:00 2001 From: Aleksandr Shevchuk Date: Thu, 19 Nov 2026 13:25:44 +0200 Subject: [PATCH 2/2] fix(author): export the tool, say the Node packing needs, and what the site serves when (#247) The two dist files are exported by their paths, and a test resolves them by the package's name. Packing on Node before 22.12 stops with a message before Vite fails to load; engines stays >=22, since installing runs none of it. The design, the README and the comments no longer say the site serves the shipped file already: its pin copies it from the first release that ships it. --- design/author.md | 11 +++++++---- packages/author/README.md | 4 ++-- packages/author/bin/h5p-author.mjs | 2 +- packages/author/lib/node.mjs | 2 +- packages/author/package.json | 2 ++ packages/author/scripts/build-tool.mjs | 17 +++++++++++++---- packages/author/tests/bundle.test.ts | 14 +++++++++++++- 7 files changed, 39 insertions(+), 13 deletions(-) diff --git a/design/author.md b/design/author.md index cc842561..d5445a90 100644 --- a/design/author.md +++ b/design/author.md @@ -302,10 +302,13 @@ text to the content check's rules, and `apps/skills` plays every example untrust - **This package builds the one-file tool, and the site serves it as shipped** (#247). `prepack` runs `scripts/build-tool.mjs`. It bundles the command line and everything it imports with Vite into `dist/h5p-author.mjs`, writes `dist/h5p-author-LICENSES.txt` beside it, and checks that its - `--version` names this package's and its pack's. Up to author 0.13.0 the site's own Vite built - it, so the site's build tools and their updates were in the path of every byte route 3 runs, and - nothing published covered them. Now the npm package does, with its provenance once publishing - moves to CI (#246). The skill names no hash of the file: checking one would add a command to + `--version` names this package's and its pack's. Both are exported by those paths. The site's + own Vite has built the file so far, so the site's build tools and their updates are in the path + of every byte route 3 runs, and nothing published covers them. From the first release that ships + the two files, the site's pin copies them instead, and the npm package covers them, with its + provenance once publishing moves to CI (#246). Packing runs Vite 8 and needs the workspace's + Node, 22.12 or later, and says so on an older one; the package's `engines` stays `>=22`, since + installing it runs none of this. The skill names no hash of the file: checking one would add a command to every run of route 3, and copies of the skill installed earlier would stop at each release. - **A preview inside Claude is the desktop app's browser panel, not a card.** A connector's card in Claude is an iframe under Claude's policy: it can register no worker, and Claude drops diff --git a/packages/author/README.md b/packages/author/README.md index a04f6d9e..716e3cb4 100644 --- a/packages/author/README.md +++ b/packages/author/README.md @@ -149,8 +149,8 @@ packs them as the zips chat apps install, and lists the build tool and each bund skill's route 3, from two files, fetches at [missing-elements.github.io/h5p/skill/](https://missing-elements.github.io/h5p/skill/). The build tool is in the package too: `dist/h5p-author.mjs` is the command line as one file, everything it -imports bundled in, and `dist/h5p-author-LICENSES.txt` lists those packages' licences. The site -serves both as the release has them. +imports bundled in, and `dist/h5p-author-LICENSES.txt` lists those packages' licences. Both are +exported by those paths. ## A package back to its source diff --git a/packages/author/bin/h5p-author.mjs b/packages/author/bin/h5p-author.mjs index d5dcfd8b..db179f72 100755 --- a/packages/author/bin/h5p-author.mjs +++ b/packages/author/bin/h5p-author.mjs @@ -38,7 +38,7 @@ const sized = (bytes) => (bytes < 1_000_000 ? `${Math.max(1, Math.round(bytes / /** * This package's version, from its package.json where the package is installed. The command line - * as one file (`scripts/build-tool.mjs`), copied out of the package, has no package.json of its own + * as one file, `dist/h5p-author.mjs`, copied out of the package, has no package.json of its own * beside it, and the one above it may be another's: there it is the copy its bundler wrote in from * the import. * The file comes first, since Node before 22.12 warns on a JSON import. diff --git a/packages/author/lib/node.mjs b/packages/author/lib/node.mjs index 0f5b710b..d3132668 100644 --- a/packages/author/lib/node.mjs +++ b/packages/author/lib/node.mjs @@ -94,7 +94,7 @@ export async function openPack(folder) { /** * The pinned pack's version, for messages and reports, from the libraries package's package.json - * where it is installed beside this one. The command line as one file (`scripts/build-tool.mjs`), + * where it is installed beside this one. The command line as one file, `dist/h5p-author.mjs`, * copied out of the package, has no package beside it: there it is the copy its bundler wrote in * from the import. The file comes first, since Node before 22.12 warns on a JSON import. */ diff --git a/packages/author/package.json b/packages/author/package.json index 7798726c..adb702a5 100644 --- a/packages/author/package.json +++ b/packages/author/package.json @@ -32,6 +32,8 @@ "types": "./types/browser.d.mts", "default": "./lib/browser.mjs" }, + "./dist/h5p-author.mjs": "./dist/h5p-author.mjs", + "./dist/h5p-author-LICENSES.txt": "./dist/h5p-author-LICENSES.txt", "./references/types/*.md": "./references/types/*.md", "./references/build/*.md": "./references/build/*.md", "./references/authoring.md": "./references/authoring.md", diff --git a/packages/author/scripts/build-tool.mjs b/packages/author/scripts/build-tool.mjs index 22d555de..cb550cbb 100644 --- a/packages/author/scripts/build-tool.mjs +++ b/packages/author/scripts/build-tool.mjs @@ -2,20 +2,29 @@ import { execFileSync } from 'node:child_process' import { readFile, rm } from 'node:fs/promises' import { join, resolve } from 'node:path' import { fileURLToPath } from 'node:url' -import { build } from 'vite' /** * The command line as one file, `h5p-author.mjs`, and `h5p-author-LICENSES.txt`, every package * bundled into it with its licence, since MIT and BSD-3-Clause ask their notices to travel with - * copies (#247). Route 3 of the skill runs the file with nothing installed, from an unzipped bundle, - * and the organisation's site serves it as this package ships it, so the npm package, and its - * provenance, cover the bytes a chat runs. Everything it imports is bundled in by Vite, with copies + * copies (#247). Route 3 of the skill runs the file with nothing installed, from an unzipped bundle. + * The organisation's site serves it, copied from this package from the first release that ships + * it, so that the npm package, and its provenance, cover the bytes a chat runs. Everything it + * imports is bundled in by Vite, with copies * of the two package.json files it reads its versions from where neither is beside it * (h5p-toolkit#198). It takes `--libraries`: the pinned pack is not with it. * * `pnpm build:tool` builds the player's plan, which it imports, first; `prepack` runs that. * `node scripts/build-tool.mjs [folder]` writes the two files in `folder`, by default `dist/`. */ +// Packing runs Vite 8, which needs Node 20.19, or 22.12 and later, on the workspace's floor, 22.12: +// said here before Vite fails to load. The package's own `engines` stays `>=22`, since installing +// it runs none of this. +const [major, minor] = process.versions.node.split('.').map(Number) +if (major < 22 || (major === 22 && minor < 12)) { + throw new Error(`Packing builds the one-file tool with Vite 8, and the workspace needs Node 22.12 or later for it; this is Node ${process.versions.node}`) +} +const { build } = await import('vite') + const root = resolve(import.meta.dirname, '..') const folder = resolve(process.argv[2] ?? join(root, 'dist')) const TOOL = 'h5p-author.mjs' diff --git a/packages/author/tests/bundle.test.ts b/packages/author/tests/bundle.test.ts index d05264ca..1f04a47d 100644 --- a/packages/author/tests/bundle.test.ts +++ b/packages/author/tests/bundle.test.ts @@ -1,7 +1,8 @@ import { execFile } from 'node:child_process' -import { copyFile, cp, lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises' +import { copyFile, cp, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, stat, writeFile } from 'node:fs/promises' import { tmpdir } from 'node:os' import { dirname, join, resolve } from 'node:path' +import { pathToFileURL } from 'node:url' import { promisify } from 'node:util' import { BlobReader, Uint8ArrayWriter, ZipReader } from '@zip.js/zip.js' import { afterAll, beforeAll, describe, expect, it } from 'vitest' @@ -243,5 +244,16 @@ describe('the command line as one file', () => { const { stdout } = await exec(process.execPath, ['h5p-author.mjs', 'build', 'quiz.json', 'quiz.h5p', '--libraries', 'parts'], { cwd: sandbox }) expect(stdout).toMatch(/^Built \S+quiz\.h5p: H5P\.QuestionSet, \d+ libraries from the pack in parts, \d+ more for installing on an H5P site\.\n/) expect((await stat(join(sandbox, 'quiz.h5p'))).size).toBeGreaterThan(0) + + // Both files resolve by the package's name, through its exports, as a site that pins it reaches them. + const scope = join(dir, 'scope') + await mkdir(join(scope, 'dist'), { recursive: true }) + await copyFile(resolve(import.meta.dirname, '../package.json'), join(scope, 'package.json')) + const files = ['h5p-author.mjs', 'h5p-author-LICENSES.txt'] + for (const file of files) await copyFile(join(built, file), join(scope, 'dist', file)) + const script = `for (const file of ${JSON.stringify(files)}) console.log(import.meta.resolve('@missing-elements/h5p-author/dist/' + file))` + const { stdout: resolved } = await exec(process.execPath, ['--input-type=module', '-e', script], { cwd: scope }) + const real = await realpath(scope) + expect(resolved).toBe(files.map((file) => `${pathToFileURL(join(real, 'dist', file)).href}\n`).join('')) }, 60_000) })