diff --git a/design/author.md b/design/author.md index 9be9c862..56b2b5c9 100644 --- a/design/author.md +++ b/design/author.md @@ -273,6 +273,14 @@ text to the content check's rules, and `apps/skills` plays every example untrust `installOnly` parts the `pack` export leaves out; a page gives `@missing-elements/h5p-libraries/install`'s, and a build from a pack without them is refused, naming the first library and where the full pack is. +- **A build says the H5P core a site needs** (#245). The upload check also refuses a package if + a library in it asks for a newer `coreApi` than the site's core, and its message names that + library. With pack 1.1.0, 50 of the 57 runnable libraries need 1.28: 31 ask for it themselves, + and the rest carry a library that does, such as H5P.JoubelUI 1.3 or H5P.Question 1.5. As checked + on 2026-11-19, Moodle has 1.28 from 4.5.11, 5.0.7 and 5.1.4 (2026-04-16), and the WordPress + plugin from 1.17. `coreApiOf` takes the newest over the parts a package carries. A build from + the command line (not `build --check`, which writes no package) and `h5p_build` print + `coreApiLine`, which names those releases for 1.28 and only the version for any other. - **Where `npx` cannot install, a page builds.** ChatGPT's sandbox reaches npm only through OpenAI's mirror, which refuses or hangs, and nothing in the skill can fix that. So the skill hands over the source for the build page, `https://missing-elements.github.io/h5p/build/`, diff --git a/design/mcp.md b/design/mcp.md index b444b5e5..8f6fafce 100644 --- a/design/mcp.md +++ b/design/mcp.md @@ -46,7 +46,8 @@ server, for ChatGPT or Claude on the web, is #210 and not this. so builds at once take names of their own. The answer names the path written. Beside the package goes its source, `.source.json`, which the build page opens to change and build again; it is made new, never written over or through a link, and where it cannot be, the answer says so. -- **A build answers with the content, the check and a picture.** The build's line, its notes, the +- **A build answers with the content, the check and a picture.** The build's line, the H5P core a + site needs (`coreApiLine`), its notes, the outline (80 lines at most) and, with `verify`, the default, the verifier's summary of a check run in a temporary folder, with its screenshot as an image. Where neither Chrome, Edge nor Playwright's Chromium is found, the answer says "Not verified" and why. A source with problems diff --git a/packages/author/README.md b/packages/author/README.md index 5f0c7044..743d6b02 100644 --- a/packages/author/README.md +++ b/packages/author/README.md @@ -29,15 +29,18 @@ npx @missing-elements/h5p-author@latest build rivers.json rivers.h5p ``` Built /work/rivers.h5p: H5P.Blanks, 9 libraries from the library pack 1.1.0, 3 more for installing on an H5P site. +Needs H5P core 1.28 or newer on a site it is uploaded to: Moodle 4.5.11, 5.0.7 or 5.1.4 and later, or the WordPress H5P plugin 1.17 and later. An older site refuses it. H5P.Blanks 1.14: interface texts from its translation language/de.json. Not verified: run npx @missing-elements/h5p-verify@latest on it and look at its screenshot before handing it over. ``` The package plays in the player and carries the editor libraries an H5P site's upload check asks -for, which the player never reads: a Moodle 4.5 with no library installed accepts +for, which the player never reads: a Moodle 4.5.15 with no library installed accepts every type's example (Moodle was the one site tried; WordPress and Drupal run the same check). A Question Set gains 120 kB by them; a Course Presentation or a Branching Scenario several MB, as the same package exported from Moodle has, because their editors bring every type they can hold. +A site also refuses a package if a library in it asks for a newer H5P core than the site has. The +build's second line says which core that is: with pack 1.1.0, 1.28 for nearly every type. It is written for an AI agent and its tokens: the agent writes what only an author can know, and code writes everything that can be derived. The @@ -208,7 +211,7 @@ Set's 2.6 MB, a container's up to 8.4 MB. `--all ` writes one per conten ```js import { buildPackage, schemaOf, SourceError } from '@missing-elements/h5p-author' -const { output, manifest, content, libraries, install, translations, notes, media, outline } = +const { output, manifest, content, libraries, install, coreApi, translations, notes, media, outline } = await buildPackage(source, 'rivers.h5p', { base: process.cwd() }) ``` @@ -248,7 +251,9 @@ not come back as it is, each `{ path, message }`. With `within`, the package and inside those folders, on their real paths. A result's `libraries` are the folders the package -plays with, `install` those carried for an H5P site's upload check. `missingForInstall(libraries)` +plays with, `install` those carried for an H5P site's upload check, and `coreApi` the newest H5P +core they ask for, `{ majorVersion, minorVersion }`, which a site needs to take the package; +`coreApiLine(coreApi)` says it as the command line does. `missingForInstall(libraries)` is that check, over a package's `library.json` files: what a site with no library installed would refuse it for, empty for a build. `schemaOf(machineName, { markdown, all, libraries })` returns the field list. `writeBundle(type, output, { libraries })` and @@ -351,7 +356,7 @@ const { blob, notes } = await buildPackage(source, { libraries, files: { 'volga. Each part is fetched whole when a build first needs it, and checked against the index's SHA-256, as in Node. `close()` the pack when the page is done with it. - `buildPackage(source, { libraries, files, fetch })` throws a `SourceError` as in Node, and returns - `{ blob, manifest, content, libraries, install, translations, notes, media }`, as in Node. Its options: + `{ blob, manifest, content, libraries, install, coreApi, translations, notes, media }`, as in Node. Its options: - `libraries`: a pack `openPack` opened, or what to open one from for this build alone. - `files`: an object or a `Map` of the files a source names, by the names it gives them: `{ "path": "volga.png" }` takes `files['volga.png']`. diff --git a/packages/author/bin/h5p-author.mjs b/packages/author/bin/h5p-author.mjs index e0fd4989..403d54f3 100755 --- a/packages/author/bin/h5p-author.mjs +++ b/packages/author/bin/h5p-author.mjs @@ -2,7 +2,7 @@ import { readFile } from 'node:fs/promises' import { dirname, relative, resolve } from 'node:path' import { parseArgs } from 'node:util' -import { buildPackage, readPackage, schemaOf, SourceError, writeBundle, writeBundles } from '../lib/author.mjs' +import { buildPackage, coreApiLine, readPackage, schemaOf, SourceError, writeBundle, writeBundles } from '../lib/author.mjs' import { packVersion } from '../lib/node.mjs' const USAGE = `Usage: @@ -103,6 +103,7 @@ try { const from = flags.libraries ? `the pack in ${flags.libraries}` : `the library pack ${await packVersion()}` const install = result.install.length ? `, ${result.install.length} more for installing on an H5P site` : '' console.log(`${check ? 'Checked, no package written' : `Built ${result.output}`}: ${result.manifest.mainLibrary}, ${result.libraries.length} libraries from ${from}${install}${result.media.length ? `, ${result.media.length} media file${result.media.length === 1 ? '' : 's'}` : ''}.`) + if (!check) console.log(coreApiLine(result.coreApi)) const language = String(result.manifest.language) if (!/^en(?:-|$)/i.test(language)) { for (const { library, translation, strings, english } of result.translations) { diff --git a/packages/author/lib/browser.mjs b/packages/author/lib/browser.mjs index bf14f9a1..6f44b86b 100644 --- a/packages/author/lib/browser.mjs +++ b/packages/author/lib/browser.mjs @@ -27,10 +27,11 @@ export * from './core.mjs' * library with its part's URL * @typedef {{ * blob: Blob, manifest: Record, content: Record, libraries: string[], install: string[], - * translations: import('./translate.mjs').TranslationReport[], notes: import('./build.mjs').Problem[], media: string[], outline: string + * coreApi: import('./install.mjs').CoreApi, translations: import('./translate.mjs').TranslationReport[], notes: import('./build.mjs').Problem[], media: string[], outline: string * }} BuildResult the package, and what is worth telling about it: `libraries`, the folders it plays - * with; `install`, those it carries for an H5P site's upload check; `outline`, the content as text - * for a review (`outlineOf`) + * with; `install`, those it carries for an H5P site's upload check; `coreApi`, the newest H5P core + * they ask for, which a site needs to take the package (`coreApiLine` says it); `outline`, the + * content as text for a review (`outlineOf`) * @typedef {{ libraries: Pack | PackIndex | string | URL, files?: Map | Record, fetch?: typeof fetch }} BuildOptions * `libraries`, a pack `openPack` opened, which a page keeps for its builds, or what to open one * from; `files`, the files a source names, by the names it gives them; `fetch`, for media named by @@ -177,6 +178,7 @@ export async function buildPackage(input, options) { content: built.content, libraries: [...built.selected.keys()], install: [...built.install.keys()], + coreApi: built.coreApi, translations: built.translations, notes: built.notes, media: media.files.map((item) => item.name), diff --git a/packages/author/lib/build.mjs b/packages/author/lib/build.mjs index dc341a4e..70f43358 100644 --- a/packages/author/lib/build.mjs +++ b/packages/author/lib/build.mjs @@ -2,7 +2,7 @@ import { TextReader } from '@zip.js/zip.js' import { librariesNamedIn, planPack } from '@missing-elements/h5p-offline-player/plan' import { checkContent, layoutContext, valueAt } from './check.mjs' import { ContentGenerator, libraryString } from './generator.mjs' -import { installClosure } from './install.mjs' +import { coreApiOf, installClosure } from './install.mjs' import { loadLibraries } from './libraries.mjs' import { CC_VERSIONS } from './metadata.mjs' import { machineNameOf, NAMING_KEYS, namingKey, nearestNames } from './names.mjs' @@ -244,8 +244,9 @@ async function closure(pack, main, content) { * @param {import('./media.mjs').MediaStore} media * @param {Problem[]} [said] the problems `sourceOf` found in the source's own fields, which come * first among the content's: all of them in one round (#174) - * @returns {Promise<{ manifest: Record, content: Record, selected: Map, install: Map, translations: TranslationReport[], notes: Problem[], outline: string }>} - * `selected`, the libraries the package plays with; `install`, those an H5P site's upload check wants with them; `outline`, the + * @returns {Promise<{ manifest: Record, content: Record, selected: Map, install: Map, coreApi: import('./install.mjs').CoreApi, translations: TranslationReport[], notes: Problem[], outline: string }>} + * `selected`, the libraries the package plays with; `install`, those an H5P site's upload check wants with them; `coreApi`, the + * newest H5P core any of them asks for (`coreApiOf`); `outline`, the * content as text for a review (`outlineOf`), made when it is first read * @internal */ @@ -352,6 +353,7 @@ export async function composePackage(source, pack, media, said = []) { let outline return { manifest, content, selected, install, translations, notes, + coreApi: coreApiOf([...selected.values(), ...install.values()].map((part) => part.library)), // Made when it is first read: it is for a review, which only some callers make, and a build // that never reads it never runs it. get outline() { return (outline ??= outlineOf({ entries, main: mainLibrary }, { params: content })) } diff --git a/packages/author/lib/core.mjs b/packages/author/lib/core.mjs index 04fb3864..ccbfe394 100644 --- a/packages/author/lib/core.mjs +++ b/packages/author/lib/core.mjs @@ -11,7 +11,7 @@ export { bundleLibraries, contentTypes } from './bundle.mjs' export { checkContent } from './check.mjs' export { outlineOf } from './outline.mjs' export { ContentGenerator, librariesIn, libraryString } from './generator.mjs' -export { missingForInstall } from './install.mjs' +export { coreApiLine, coreApiOf, missingForInstall } from './install.mjs' export { loadLibraries, packageLibraries } from './libraries.mjs' export { sourceType } from './names.mjs' export { GENERATED_END, GENERATED_START } from './schema.mjs' @@ -22,6 +22,7 @@ export { allowedTags, editorWidget, markupText, plainText, takesMarkup } from '. /** * @typedef {import('./build.mjs').Source} Source * @typedef {import('./check.mjs').CheckedContent} CheckedContent + * @typedef {import('./install.mjs').CoreApi} CoreApi * @typedef {import('./generator.mjs').GeneratorOptions} GeneratorOptions * @typedef {import('./generator.mjs').PackEntry} PackEntry * @typedef {import('./libraries.mjs').LibraryRecord} LibraryRecord diff --git a/packages/author/lib/install.mjs b/packages/author/lib/install.mjs index a7a17343..0d742bb5 100644 --- a/packages/author/lib/install.mjs +++ b/packages/author/lib/install.mjs @@ -70,3 +70,44 @@ export function missingForInstall(libraries) { } return missing } + +/** + * The newest H5P core API that `libraries`, each given as its `library.json`, ask for in + * `coreApi`; one that asks for none asks for 1.0, as H5P reads it. H5P core's upload check + * (`H5PValidator::isValidH5pData`) refuses a package that carries a library asking for a newer core + * than the site has, and its message names that library, not the package. + * @param {Iterable} libraries + * @returns {CoreApi} + */ +export function coreApiOf(libraries) { + let newest = { majorVersion: 1, minorVersion: 0 } + for (const library of libraries) { + const asked = library?.coreApi + if (!asked) continue + // A minor left out is 0; a version that is not two whole numbers is none. + const major = Number(asked.majorVersion) + const minor = Number(asked.minorVersion ?? 0) + if (!Number.isInteger(major) || !Number.isInteger(minor)) continue + if (major > newest.majorVersion || (major === newest.majorVersion && minor > newest.minorVersion)) newest = { majorVersion: major, minorVersion: minor } + } + return newest +} + +/** + * The platforms' first releases with a core, by its version, as checked on 2026-11-19 (#245): + * Moodle's `h5plib_v128` (MDL-88092) and the WordPress plugin's bundled core. A version not here + * is said without them. + */ +const CORE_RELEASES = new Map([['1.28', 'Moodle 4.5.11, 5.0.7 or 5.1.4 and later, or the WordPress H5P plugin 1.17 and later']]) + +/** + * The line a build says of the core a site needs to take its package (`coreApiOf`). + * @param {CoreApi} core + */ +export function coreApiLine(core) { + const version = `${core.majorVersion}.${core.minorVersion}` + const releases = CORE_RELEASES.get(version) + return `Needs H5P core ${version} or newer on a site it is uploaded to${releases ? `: ${releases}` : ''}. An older site refuses it.` +} + +/** @typedef {{ majorVersion: number, minorVersion: number }} CoreApi a core API version, as a `library.json` names one */ diff --git a/packages/author/lib/node.mjs b/packages/author/lib/node.mjs index 21a76bcd..a8dfcb07 100644 --- a/packages/author/lib/node.mjs +++ b/packages/author/lib/node.mjs @@ -27,10 +27,11 @@ import { SourceError } from './source-error.mjs' * @typedef {import('./translate.mjs').TranslationReport} TranslationReport * @typedef {{ * output: string, manifest: Record, content: Record, - * libraries: string[], install: string[], translations: TranslationReport[], notes: Problem[], media: string[], outline: string + * libraries: string[], install: string[], coreApi: import('./install.mjs').CoreApi, translations: TranslationReport[], notes: Problem[], media: string[], outline: string * }} BuildResult what was written, and what is worth telling about it: `libraries`, the folders the - * package plays with; `install`, those carried for an H5P site's upload check; `outline`, the - * content as text for a review (`outlineOf`) + * package plays with; `install`, those carried for an H5P site's upload check; `coreApi`, the + * newest H5P core they ask for, which a site needs to take the package (`coreApiLine` says it); + * `outline`, the content as text for a review (`outlineOf`) * @typedef {{ libraries?: string, base?: string, fetch?: typeof fetch, within?: string[], check?: boolean }} BuildOptions * `libraries`, a library pack's parts folder in place of the pinned pack; `base`, the folder a * source's file paths are read from; `fetch`, for media named by web address; `within`, the @@ -393,6 +394,7 @@ export async function buildPackage(input, output, options = {}) { content: built.content, libraries: [...built.selected.keys()], install: [...built.install.keys()], + coreApi: built.coreApi, translations: built.translations, notes: built.notes, media: media.files.map((item) => item.name), @@ -430,6 +432,7 @@ export async function buildPackage(input, output, options = {}) { content: built.content, libraries: [...built.selected.keys()], install: [...built.install.keys()], + coreApi: built.coreApi, translations: built.translations, notes: built.notes, media: media.files.map((item) => item.name), diff --git a/packages/author/tests/build.test.ts b/packages/author/tests/build.test.ts index a4f0a7f1..bea486d1 100644 --- a/packages/author/tests/build.test.ts +++ b/packages/author/tests/build.test.ts @@ -10,7 +10,7 @@ import { BlobReader, TextWriter, Uint8ArrayWriter, ZipReader } from '@zip.js/zip import { pack } from '@missing-elements/h5p-libraries' import { afterAll, beforeAll, describe, expect, it } from 'vitest' import { toJSONSchema } from 'zod/mini' -import { buildPackage, librariesIn, missingForInstall, SourceError, sourceSchema } from '../lib/author.mjs' +import { buildPackage, coreApiLine, coreApiOf, librariesIn, missingForInstall, SourceError, sourceSchema } from '../lib/author.mjs' import { readSource } from '../lib/build.mjs' import { LICENSES } from '../lib/metadata.mjs' import { MediaStore } from '../lib/media.mjs' @@ -177,6 +177,21 @@ describe('the quiz format', () => { } }) + it('says the newest H5P core a library it carries asks for, which a site needs to take it (#245)', async () => { + const built = await build(example) + const asked = [...built.files].filter(([name]) => /^[^/]+\/library\.json$/.test(name)).map(([, text]) => JSON.parse(text).coreApi) + const [newest] = asked.filter(Boolean).map(({ majorVersion, minorVersion }) => [Number(majorVersion), Number(minorVersion)]).sort((a, b) => b[0] - a[0] || b[1] - a[1]) + expect(built.coreApi).toEqual({ majorVersion: newest[0], minorVersion: newest[1] }) + // H5P reads a library that names none as asking for 1.0; library.json may write the numbers as strings. + expect(coreApiOf([])).toEqual({ majorVersion: 1, minorVersion: 0 }) + expect(coreApiOf([{ coreApi: { majorVersion: '1', minorVersion: '27' } }, { coreApi: { majorVersion: 1, minorVersion: 9 } }, {}])).toEqual({ majorVersion: 1, minorVersion: 27 }) + // A minor left out is 0, and what is not two whole numbers is passed over: never "2.NaN". + expect(coreApiOf([{ coreApi: { majorVersion: 2 } }])).toEqual({ majorVersion: 2, minorVersion: 0 }) + expect(coreApiOf([{ coreApi: { majorVersion: 2, minorVersion: 'x' } }, { coreApi: { majorVersion: 1.5, minorVersion: 1 } }])).toEqual({ majorVersion: 1, minorVersion: 0 }) + expect(coreApiLine({ majorVersion: 1, minorVersion: 28 })).toBe('Needs H5P core 1.28 or newer on a site it is uploaded to: Moodle 4.5.11, 5.0.7 or 5.1.4 and later, or the WordPress H5P plugin 1.17 and later. An older site refuses it.') + expect(coreApiLine({ majorVersion: 1, minorVersion: 29 })).toBe('Needs H5P core 1.29 or newer on a site it is uploaded to. An older site refuses it.') + }) + it('builds standalone Multiple Choice, escapes markup, and preserves false and zero values', async () => { const source = { ...example, kind: 'multiple-choice', passPercentage: 0, passedFeedback: 'Done & dusted', @@ -979,7 +994,7 @@ describe('the build', () => { const project = await mkdtemp(join(dir, 'project-')) await writeFile(join(project, 'german.json'), JSON.stringify({ ...example, language: 'de' })) const german = await exec(process.execPath, [bin, 'build', 'german.json', 'german.h5p'], { cwd: project }) - expect(german.stdout).toMatch(/^Built .*german\.h5p: H5P\.QuestionSet, \d+ libraries from the library pack \d+\.\d+\.\d+, \d+ more for installing on an H5P site\./) + expect(german.stdout).toMatch(/^Built .*german\.h5p: H5P\.QuestionSet, \d+ libraries from the library pack \d+\.\d+\.\d+, \d+ more for installing on an H5P site\.\nNeeds H5P core \d+\.\d+ or newer on a site it is uploaded to\b/) expect(german.stdout).toMatch(/H5P\.MultiChoice 1\.\d+: interface texts from its translation language\/de\.json\./) expect(german.stdout + german.stderr).toMatch(/H5P\.QuestionSet 1\.\d+: interface texts from its translation language\/de\.json/) expect(german.stdout).toContain('Not verified') diff --git a/packages/mcp/README.md b/packages/mcp/README.md index 20ea2039..5c481fdc 100644 --- a/packages/mcp/README.md +++ b/packages/mcp/README.md @@ -44,7 +44,8 @@ gets a number, and it says which. - `h5p_types`: the content types, and how to write a source for one. - `h5p_build`: a package from a source, its source beside it as `.source.json`. A source with - problems is refused, each problem named. It checks the package and says what it holds. + problems is refused, each problem named. It checks the package, says what it holds, and which + H5P core a site needs to take it. - `h5p_preview`: opens a package in your browser, in the real player, served from your computer until its tab is closed. - `h5p_read`: a package back into its source, with its pictures and other files, in a new folder diff --git a/packages/mcp/lib/server.mjs b/packages/mcp/lib/server.mjs index d25c0c19..be05d3d2 100644 --- a/packages/mcp/lib/server.mjs +++ b/packages/mcp/lib/server.mjs @@ -4,7 +4,7 @@ import { basename, dirname, join, resolve } from 'node:path' import { fileURLToPath } from 'node:url' import { McpServer } from '@modelcontextprotocol/server' import { z } from 'zod' -import { SourceError, buildPackage, contentTypes, inside, openPack, publicFetch, readPackage, schemaOf, sourceSchema, sourceType } from '@missing-elements/h5p-author' +import { SourceError, buildPackage, contentTypes, coreApiLine, inside, openPack, publicFetch, readPackage, schemaOf, sourceSchema, sourceType } from '@missing-elements/h5p-author' import { VerifyError, openBrowser, previewPackage, summarize, verifyPackage } from '@missing-elements/h5p-verify' import { defaultFolders, fileStem, rootFolders } from './folders.mjs' @@ -228,6 +228,7 @@ export async function createServer(options = {}) { const media = result.media.length ? `, ${result.media.length} media file${result.media.length === 1 ? '' : 's'}` : '' const lines = [ `Built ${target} (${sized((await stat(target)).size)}): ${result.manifest.mainLibrary}, ${result.libraries.length} libraries${install}${media}.`, + coreApiLine(result.coreApi), unwritten ? `Its source was not written beside it: ${unwritten.message}` : `Its source is beside it, ${basename(sourceFile)}: https://missing-elements.github.io/h5p/build/ opens it under "Or open a file", to change and build again.` diff --git a/packages/mcp/tests/server.test.ts b/packages/mcp/tests/server.test.ts index 0f7f546d..3fd3f3fe 100644 --- a/packages/mcp/tests/server.test.ts +++ b/packages/mcp/tests/server.test.ts @@ -101,6 +101,7 @@ describe('h5p_build', () => { const text = textOf(answer) expect(answer.isError).toBeFalsy() expect(text).toContain(`Built ${join(folder, 'boiling-point.h5p')}`) + expect(text).toMatch(/^Needs H5P core \d+\.\d+ or newer on a site it is uploaded to\b/m) expect(text).toContain('Water boils at 100 °C at sea level.') expect(text).toMatch(/^pass {2}boiling-point\.h5p/m) expect(text).not.toMatch(/screenshot:/)