From 36283d43636cce96931b386a55f2dd5dff2c2546 Mon Sep 17 00:00:00 2001 From: Aleksandr Shevchuk Date: Fri, 20 Nov 2026 11:15:06 +0200 Subject: [PATCH 1/2] feat(author): a source names the version of its type it was built with, and the build writes it (#219) --- design/author.md | 22 ++++++ packages/author/README.md | 17 ++++- packages/author/bin/h5p-author.mjs | 47 +++++++++++- packages/author/lib/browser.mjs | 8 +- packages/author/lib/build.mjs | 31 +++++++- packages/author/lib/node.mjs | 10 ++- packages/author/lib/source-schema.mjs | 9 ++- packages/author/tests/build.test.ts | 74 ++++++++++++++++++- packages/mcp/lib/server.mjs | 3 +- packages/mcp/tests/server.test.ts | 5 +- .../h5p-author/references/build/built-here.md | 6 +- 11 files changed, 210 insertions(+), 22 deletions(-) diff --git a/design/author.md b/design/author.md index 3f8632f8..687493ac 100644 --- a/design/author.md +++ b/design/author.md @@ -417,6 +417,28 @@ text to the content check's rules, and `apps/skills` plays every example untrust packages, the 79 checked against their own libraries give 36 notes of a picture with no alt text in 8 packages, and 4 of answers alike in one, a test whose answers all read "Test"; no question with no answer marked correct, and no text with no gap. +- **A source names the version of its type it was built with, and the build writes that** (#219, + the owner's calls). A source handed over beside a package is built again later, on the build + page or by a newer release, with a newer pack. So a build hands back the source with + `builtWith`, the content type and the pack's major.minor of it (`H5P.Blanks 1.14`), beside its + `type` (`result.source`, `result.builtWith`), and a build of a source that names another + version of the same type says so: a note where it builds, and one more line with the problems + where it does not, since a field that changed since may have made them. Alone it is never a + problem, and another type's is the type changed by hand, named anew with nothing said. + - **The type's version, not the pack's.** Every route knows it, a build from a `parts/` folder + too, whose index names no pack; and it says what moved, where two pack versions say only + that something did. + - **The build writes it, since a model writes the source before there is a build.** The + command line writes `.source.json` beside the package, as the MCP server does, both + from `result.source`; `buildPackage` itself writes the package alone. The skill's hand-over + gives that file, not the one the chat wrote. It is never written over: a name that is taken + stops the build before a package is made. The one exception is the file being built, the + usual name of a source that was handed over, which is rewritten by a rename, and only where + what it names has changed. A quiz in the quiz format has no field for it and stays as written. + - `builtWith` is a field of `sourceSchema`, described as a build's to write, and left out of + the fields a problem lists as a source's; one that is not a name and a version is a problem + saying to leave it out. A read leaves it out: the next build writes it. + - The build page shows it once the organisation's site pins a release with it (not done yet). - **The hand-over carries the source and one web address, the build page's plain one** (#190, #215, the owner's calls). Beside the package, the hand-over gives the source as a file named after the package with `.source.json`, and one fixed line saying to open that file on the build diff --git a/packages/author/README.md b/packages/author/README.md index 9070c973..45f8e6a3 100644 --- a/packages/author/README.md +++ b/packages/author/README.md @@ -30,6 +30,7 @@ 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. +Its source, naming H5P.Blanks 1.14 as what it was built with, is /work/rivers.source.json: hand it over with the package. 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. ``` @@ -42,6 +43,13 @@ the same package exported from Moodle has, because their editors bring every typ 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. +Beside the package the command writes the source again, as `rivers.source.json`, with one field +more: `builtWith`, the content type and the pack's version of it. A source is built again later, +often with a newer pack, and a build of one that names another version of its type says so: as a +note where it builds, and with the problems where it does not, since a field may have changed +since. That file is never written over either, but where it is the file being built, which is +kept up to date. + 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 [h5p-author skill](https://github.com/missing-elements/h5p-toolkit/tree/main/skills/h5p-author) @@ -58,6 +66,7 @@ an example and the fields, then the check and the preview. | `license` | An H5P licence code: `U` (undisclosed), `CC BY`, `CC BY-SA`, `CC BY-ND`, `CC BY-NC`, `CC BY-NC-SA`, `CC BY-NC-ND`, `CC0 1.0`, `CC PDM`, `GNU GPL`, `PD`, `ODC PDDL`, `C`; `licenseVersion` for a CC BY one | | `authors` | `[{ "name": "…", "role": "Author" }]`, the role one of Author, Editor, Licensee, Originator | | `params` | The content type's fields that differ from their defaults | +| `builtWith` | Written by a build, never by hand: the content type and its version when the source was last built, `H5P.Blanks 1.14` | What `params` takes is what H5P's editor would let an author save in the same form: @@ -214,7 +223,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, coreApi, translations, notes, media, outline } = +const { output, source: built, builtWith, manifest, content, libraries, install, coreApi, translations, notes, media, outline } = await buildPackage(source, 'rivers.h5p', { base: process.cwd() }) ``` @@ -253,7 +262,9 @@ source, the media written beside it by the paths it names them by, and what was not come back as it is, each `{ path, message }`. With `within`, the package and the folder must be inside those folders, on their real paths. -A result's `libraries` are the folders the package +A result's `builtWith` is the content type and the pack's version of it, `H5P.Blanks 1.14`, and +its `source` the source as built, naming it: what to keep with the package, as the command line +writes it beside one. `buildPackage` writes the package alone. Its `libraries` are the folders the package 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)` @@ -359,7 +370,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, coreApi, translations, notes, media }`, as in Node. Its options: + `{ blob, source, builtWith, 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 748089ad..acbab335 100755 --- a/packages/author/bin/h5p-author.mjs +++ b/packages/author/bin/h5p-author.mjs @@ -1,5 +1,5 @@ #!/usr/bin/env node -import { readFile } from 'node:fs/promises' +import { lstat, readFile, realpath, rename, rm, writeFile } from 'node:fs/promises' import { dirname, relative, resolve } from 'node:path' import { parseArgs } from 'node:util' import { buildPackage, coreApiLine, readPackage, schemaOf, SourceError, writeBundle, writeBundles } from '../lib/author.mjs' @@ -16,7 +16,8 @@ const USAGE = `Usage: build Makes a playable .h5p from a source: { "type", "title", "language", "license", "authors", "params" }, or a quiz in the h5p-author skill's quiz format. Writes only when the whole source is right, and never over an existing file; --check lists the - problems and notes and writes no package. + problems and notes and writes no package. Beside the package it writes the source + as .source.json, naming the content type's version it was built with. read Writes the source a build would take to make a package again into a folder, with the package's media beside it: to change it and build it again. Reads content made for the pack's versions of its libraries; never writes over a file. @@ -77,6 +78,16 @@ function parse(argv) { return { positional: positionals, flags } } +/** + * Whether two paths are one file, a link followed; false where either is not there. + * @param {string} one + * @param {string} other + */ +async function sameFile(one, other) { + const [first, second] = await Promise.all([one, other].map((path) => realpath(path).catch(() => null))) + return first !== null && first === second +} + try { const { positional, flags } = parse(process.argv.slice(2)) const [command, ...rest] = positional @@ -100,11 +111,43 @@ try { } catch (error) { throw new Error(`${rest[0]} is not a readable JSON file: ${error instanceof Error ? error.message : error}`) } + // The source a build keeps beside its package, naming what it was built with (#219): the + // package's name with `.source.json`. Looked at before any work, as the package's own name + // is: never written over, but where it is the file being built, which is kept up to date. + const beside = check ? '' : resolve(rest[1]).replace(/\.h5p$/i, '') + '.source.json' + const same = !check && await sameFile(beside, sourcePath) + const there = (/** @type {string} */ path) => lstat(path).then(() => true, () => false) + // A package that is there already is the build's to refuse, in its own words. + if (!check && !same && await there(beside) && !(await there(resolve(rest[1])))) { + throw new Error(`${beside} exists, and a build writes its source there and never over a file: name a new package`) + } const result = await buildPackage(source, check ? undefined : rest[1], { base: dirname(sourcePath), libraries: /** @type {string | undefined} */ (flags.libraries), check }) + /** @type {string} */ + let kept = '' + if (!check) { + const text = `${JSON.stringify(result.source, null, 2)}\n` + if (!same) await writeFile(beside, text, { flag: 'wx' }).then(() => { kept = beside }, (error) => console.warn(`Its source was not written beside it: ${error instanceof Error ? error.message : error}`)) + else { + // The file being built, given what it was built with: all of it or none, by a rename. + // A quiz in the quiz format stays one: it has no field for it. + kept = 'kind' in source ? '' : beside + if (kept && source.builtWith !== result.builtWith) { + // By its real path, so that a link to it stays a link. + const real = await realpath(beside) + const next = `${real}.${process.pid}.tmp` + await writeFile(next, text, { flag: 'wx' }).then(() => rename(next, real)).catch(async (error) => { + await rm(next, { force: true }) + kept = '' + console.warn(`${beside} was not given what it was built with: ${error instanceof Error ? error.message : error}`) + }) + } + } + } 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)) + if (kept) console.log(`Its source, naming ${result.builtWith} as what it was built with, is ${kept}: hand it over with the package.`) 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 6f44b86b..4b2eddac 100644 --- a/packages/author/lib/browser.mjs +++ b/packages/author/lib/browser.mjs @@ -26,12 +26,14 @@ export * from './core.mjs' * the `pack` export of `@missing-elements/h5p-libraries` as a bundler emits it: the index, each * library with its part's URL * @typedef {{ - * blob: Blob, manifest: Record, content: Record, libraries: string[], install: string[], + * blob: Blob, source: import('./build.mjs').Source, builtWith: string, manifest: Record, content: Record, libraries: string[], install: 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; `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`) + * content as text for a review (`outlineOf`); `builtWith`, the content type and the pack's version + * of it, "H5P.Blanks 1.14", and `source`, the source as built, naming it: what to keep with the + * package, so that a build with a later pack can say the type has moved * @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 @@ -174,6 +176,8 @@ export async function buildPackage(input, options) { }) return { blob: await writer.close(), + source: built.source, + builtWith: built.builtWith, manifest: built.manifest, content: built.content, libraries: [...built.selected.keys()], diff --git a/packages/author/lib/build.mjs b/packages/author/lib/build.mjs index 70f43358..ab63f160 100644 --- a/packages/author/lib/build.mjs +++ b/packages/author/lib/build.mjs @@ -38,7 +38,7 @@ const isObject = (value) => value !== null && typeof value === 'object' && !Arra /** A source's fields, as `sourceSchema` declares them. */ const FIELDS = Object.keys(sourceSchema.shape) /** Those a source says of itself, which H5P keeps in an object of their own, `metadata`. */ -const OWN = FIELDS.filter((name) => name !== 'type' && name !== 'params') +const OWN = FIELDS.filter((name) => name !== 'type' && name !== 'params' && name !== 'builtWith') /** * The machine names a source's `type` may be: the pack's libraries but those carried only for an @@ -169,7 +169,7 @@ export function sourceOf(input, names) { // The authors that hold are kept, so the content is checked with them. const authorsHold = holds(field.authors, given.authors, at.authors, report) if (Array.isArray(given.authors)) source.authors = authorsHold ? given.authors : given.authors.filter(authorHolds) - for (const key of /** @type {const} */ (['source', 'yearFrom', 'yearTo', 'params'])) { + for (const key of /** @type {const} */ (['source', 'yearFrom', 'yearTo', 'params', 'builtWith'])) { if (given[key] !== undefined && holds(field[key], given[key], at[key], report)) source[key] = given[key] } return { source: /** @type {Source} */ (source), problems, typed } @@ -234,6 +234,19 @@ async function closure(pack, main, content) { return { selected, addons } } +/** + * A source naming what it was built with, the content type and the pack's version of it, beside + * its `type`: what a build hands back to be kept with the package (#219), so that a build of it + * with a later pack can say the type has moved. + * @param {Source} source + * @param {string} builtWith as `libraryString` writes it, "H5P.Blanks 1.14" + * @returns {Source} + */ +function stamped(source, builtWith) { + const { type, builtWith: _before, ...rest } = source + return { type, builtWith, ...rest } +} + /** * A source made what a package holds, its media resolved through `media`: the manifest, the content, * the libraries' parts in the order the package lists them, and what is worth telling. Nothing is @@ -244,10 +257,11 @@ 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, coreApi: import('./install.mjs').CoreApi, translations: TranslationReport[], notes: Problem[], outline: string }>} + * @returns {Promise<{ source: Source, builtWith: string, 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 + * content as text for a review (`outlineOf`), made when it is first read; `builtWith`, the + * content type and the version the pack has of it, and `source`, the source naming it (`stamped`) * @internal */ export async function composePackage(source, pack, media, said = []) { @@ -323,7 +337,15 @@ export async function composePackage(source, pack, media, said = []) { for (const place of placesOf(main, checked.params)) { if (place.library === 'H5P.InteractiveVideo') videoTimes(place.params, inSource(place.path), (file) => media.lengthOf(file), timed) } + // What the source was last built with, where this pack has another version of the type: said + // with the problems, which a field that changed since may have made, and a note where it builds. + const builtWith = libraryString(mainLibrary.library) + const before = source.builtWith !== undefined && source.builtWith !== builtWith && source.builtWith.split(' ')[0] === main ? source.builtWith : '' + if (before && (said.length || problems.length)) { + report('builtWith', `this source was last built with ${before} and this pack has ${builtWith}: a field named here may have changed since, and the type's fields as they are now say what to write`) + } if (said.length || problems.length) throw new SourceError([...said, ...problems]) + if (before) note('builtWith', `was ${before} and this pack has ${builtWith}: its fields may have changed since, so play it through before handing it over`) const content = checked.params const { selected, addons } = await closure(pack, mainLibrary.library, content) @@ -352,6 +374,7 @@ export async function composePackage(source, pack, media, said = []) { /** @type {string | undefined} */ let outline return { + source: stamped(source, builtWith), builtWith, 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 diff --git a/packages/author/lib/node.mjs b/packages/author/lib/node.mjs index b94f0eea..2d3f4d7a 100644 --- a/packages/author/lib/node.mjs +++ b/packages/author/lib/node.mjs @@ -26,12 +26,14 @@ import { SourceError } from './source-error.mjs' * @typedef {import('./build.mjs').Problem} Problem * @typedef {import('./translate.mjs').TranslationReport} TranslationReport * @typedef {{ - * output: string, manifest: Record, content: Record, + * output: string, source: import('./build.mjs').Source, builtWith: string, manifest: Record, content: Record, * 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; `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`) + * `outline`, the content as text for a review (`outlineOf`); `builtWith`, the content type and + * the pack's version of it, "H5P.Blanks 1.14", and `source`, the source as built, naming it: what + * to keep with the package, so that a build with a later pack can say the type has moved * @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 @@ -390,6 +392,8 @@ export async function buildPackage(input, output, options = {}) { if (check) { return { output: '', + source: built.source, + builtWith: built.builtWith, manifest: built.manifest, content: built.content, libraries: [...built.selected.keys()], @@ -428,6 +432,8 @@ export async function buildPackage(input, output, options = {}) { }) return { output: target, + source: built.source, + builtWith: built.builtWith, manifest: built.manifest, content: built.content, libraries: [...built.selected.keys()], diff --git a/packages/author/lib/source-schema.mjs b/packages/author/lib/source-schema.mjs index 8cd7406a..6a28416c 100644 --- a/packages/author/lib/source-schema.mjs +++ b/packages/author/lib/source-schema.mjs @@ -17,6 +17,7 @@ const NAME = 'expected the author\'s name' const AUTHORS = 'name at least one author: [{ "name": "…", "role": "Author" }]' const ADDRESS = 'expected the address the content comes from' const YEAR = 'expected a year' +const BUILT_WITH = 'is written by a build, the content type and its version then, as "H5P.Blanks 1.14": leave it out' /** @param {string} text */ const written = (text) => text.trim() !== '' @@ -56,11 +57,13 @@ const fields = { yearFrom: z.optional(z.int({ error: YEAR })), yearTo: z.optional(z.int({ error: YEAR })), params: z.optional(z.record(z.string(), z.unknown(), { error: 'expected an object of the content type\'s fields' }) - .check(z.describe('The content type\'s fields that differ from their defaults'))) + .check(z.describe('The content type\'s fields that differ from their defaults'))), + builtWith: z.optional(z.string({ error: BUILT_WITH }).check(z.regex(/^\S+ \d+\.\d+$/, { error: BUILT_WITH }), + z.describe('Written by a build, never by hand: the content type and its version when the source was last built'))) } -/** @internal What is said of a key that is no field of a source. */ -export const NO_FIELD = `is not a field of a source; the fields are ${Object.keys(fields).join(', ')}` +/** @internal What is said of a key that is no field of a source: those one writes, so not what a build writes in it. */ +export const NO_FIELD = `is not a field of a source; the fields are ${Object.keys(fields).filter((name) => name !== 'builtWith').join(', ')}` /** @internal What is said of a source that is no object. */ export const NO_SOURCE = 'expected an object: { "type", "title", "language", "license", "authors", "params" }' diff --git a/packages/author/tests/build.test.ts b/packages/author/tests/build.test.ts index ce5ad4d6..195d3dcd 100644 --- a/packages/author/tests/build.test.ts +++ b/packages/author/tests/build.test.ts @@ -1,5 +1,5 @@ import { execFile } from 'node:child_process' -import { cp, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises' +import { cp, mkdtemp, readFile, readdir, realpath, rm, writeFile } from 'node:fs/promises' import { createServer, type Server } from 'node:http' import { createRequire } from 'node:module' import type { AddressInfo } from 'node:net' @@ -1015,6 +1015,78 @@ describe('the build', () => { }) }) +describe('what a source was built with (#219)', () => { + const entry = pack.libraries.find(library => library.machineName === 'H5P.TrueFalse')! + const now = `H5P.TrueFalse ${entry.majorVersion}.${entry.minorVersion}` + const before = `H5P.TrueFalse ${entry.majorVersion}.${entry.minorVersion - 1}` + const source = { ...META, type: 'H5P.TrueFalse', params: { question: 'Is the Nile a river?', correct: 'true' } } + + it('hands back the source naming the content type and the pack\'s version of it, beside its type', async () => { + const result = await build(source) + expect(result.builtWith).toBe(now) + expect(result.source).toEqual({ ...source, builtWith: now }) + expect(Object.keys(result.source).slice(0, 2)).toEqual(['type', 'builtWith']) + // Built again as handed back: the same content, and nothing said. + const again = await build(result.source) + expect(again.content).toEqual(result.content) + expect(again.notes).toEqual([]) + expect((await buildPackage(source, undefined, { check: true })).builtWith).toBe(now) + }) + + it('says so where the pack has another version of the type: a note where it builds, beside the problems where it does not', async () => { + const { notes, source: kept } = await build({ ...source, builtWith: before }) + expect(notes).toEqual([{ path: 'builtWith', message: `was ${before} and this pack has ${now}: its fields may have changed since, so play it through before handing it over` }]) + expect(kept.builtWith).toBe(now) + expect(await problems({ ...source, builtWith: before, params: { ...source.params, corect: 'true' } })).toEqual([ + expect.stringMatching(/^params\.corect: is not a field here/), + `builtWith: this source was last built with ${before} and this pack has ${now}: a field named here may have changed since, and the type's fields as they are now say what to write` + ]) + // Alone it is no problem, and another type's is the type changed by hand: named anew, nothing said. + expect((await build({ ...source, builtWith: 'H5P.Blanks 1.14' })).notes).toEqual([]) + }) + + it('refuses one that is not a type and a version, saying to leave it out', async () => { + for (const builtWith of ['yes', 'H5P.TrueFalse', 1.8, 'H5P.TrueFalse 1.8.2']) { + expect(await problems({ ...source, builtWith })).toEqual(['builtWith: is written by a build, the content type and its version then, as "H5P.Blanks 1.14": leave it out']) + } + }) + + it('as a command writes it beside the package, never over a file but the one it builds from', async () => { + const project = await realpath(await mkdtemp(join(dir, 'built-with-'))) + const run = (...args: string[]) => exec(process.execPath, [bin, 'build', ...args], { cwd: project }) + const read = async (name: string) => JSON.parse(await readFile(join(project, name), 'utf8')) + await writeFile(join(project, 'source.json'), JSON.stringify(source)) + const { stdout } = await run('source.json', 'rivers.h5p') + expect(stdout).toContain(`Its source, naming ${now} as what it was built with, is ${join(project, 'rivers.source.json')}: hand it over with the package.`) + expect(await read('rivers.source.json')).toEqual({ ...source, builtWith: now }) + + // A name that is taken stops the build before it writes a package; a check writes neither. + await writeFile(join(project, 'taken.source.json'), 'mine') + await expect(run('source.json', 'taken.h5p')).rejects.toMatchObject({ stderr: expect.stringContaining('taken.source.json exists, and a build writes its source there and never over a file: name a new package') }) + await run('--check', 'source.json') + expect((await readdir(project)).sort()).toEqual(['rivers.h5p', 'rivers.source.json', 'source.json', 'taken.source.json']) + expect(await readFile(join(project, 'taken.source.json'), 'utf8')).toBe('mine') + + // The file it builds from is kept up to date, and left as it is where it says so already. + await writeFile(join(project, 'old.source.json'), JSON.stringify({ ...source, builtWith: before })) + const old = await run('old.source.json', 'old.h5p') + expect(old.stderr).toContain(`Note: builtWith was ${before} and this pack has ${now}`) + expect(await read('old.source.json')).toEqual({ ...source, builtWith: now }) + const written = `${JSON.stringify({ ...source, builtWith: now })}\n\n` + await writeFile(join(project, 'same.source.json'), written) + await run('same.source.json', 'same.h5p') + expect(await readFile(join(project, 'same.source.json'), 'utf8')).toBe(written) + + // A quiz in the quiz format has no field for it, and stays as written. + const quiz = JSON.stringify(example) + await writeFile(join(project, 'quiz.source.json'), quiz) + const { stdout: said } = await run('quiz.source.json', 'quiz.h5p') + expect(said).not.toContain('Its source') + expect(await readFile(join(project, 'quiz.source.json'), 'utf8')).toBe(quiz) + expect((await readdir(project)).filter(name => name.endsWith('.tmp'))).toEqual([]) + }) +}) + describe('the package', () => { it('carries the skill\'s text, build routes and type files, copied as it is packed, for a page to hand to a chat (#172, #178)', async () => { const skill = resolve(import.meta.dirname, '../../../skills/h5p-author') diff --git a/packages/mcp/lib/server.mjs b/packages/mcp/lib/server.mjs index be05d3d2..a97e1b0b 100644 --- a/packages/mcp/lib/server.mjs +++ b/packages/mcp/lib/server.mjs @@ -217,7 +217,8 @@ export async function createServer(options = {}) { try { result = await buildPackage(source, target, { base: dirname(target), within: allowed, fetch: publicFetch, libraries: options.libraries }) // Made new: a file or a link put at its name since the name was found free is not written through. - unwritten = await writeFile(sourceFile, `${JSON.stringify(source, null, 2)}\n`, { flag: 'wx' }).then(() => undefined, (error) => error) + // As the build took it, naming the content type's version it was built with (author's #219). + unwritten = await writeFile(sourceFile, `${JSON.stringify(result.source, null, 2)}\n`, { flag: 'wx' }).then(() => undefined, (error) => error) } catch (error) { if (error instanceof SourceError) return refusal(`${error.message}\nFix each at its path and build again.${/outside the folders/.test(error.message) ? ` ${whereFiles(allowed)}` : ''}`) return refusal(error instanceof Error ? error.message : String(error)) diff --git a/packages/mcp/tests/server.test.ts b/packages/mcp/tests/server.test.ts index 3fd3f3fe..79bdc1a3 100644 --- a/packages/mcp/tests/server.test.ts +++ b/packages/mcp/tests/server.test.ts @@ -106,7 +106,10 @@ describe('h5p_build', () => { expect(text).toMatch(/^pass {2}boiling-point\.h5p/m) expect(text).not.toMatch(/screenshot:/) expect(answer.content.some((part) => part.type === 'image' && part.mimeType === 'image/png')).toBe(true) - expect(JSON.parse(await readFile(join(folder, 'boiling-point.source.json'), 'utf8'))).toEqual(SOURCE) + // As the build took it, naming the content type's version it was built with, beside its type. + const kept = JSON.parse(await readFile(join(folder, 'boiling-point.source.json'), 'utf8')) + expect(kept).toEqual({ ...SOURCE, builtWith: expect.stringMatching(/^H5P\.TrueFalse \d+\.\d+$/) }) + expect(Object.keys(kept).slice(0, 2)).toEqual(['type', 'builtWith']) }) it('takes the next number rather than write over a file', async () => { diff --git a/skills/h5p-author/references/build/built-here.md b/skills/h5p-author/references/build/built-here.md index da7a1fc5..9130611b 100644 --- a/skills/h5p-author/references/build/built-here.md +++ b/skills/h5p-author/references/build/built-here.md @@ -44,9 +44,9 @@ do it: the person's own play is the check, and a script of your own costs more t Deliver: -- the `.h5p`, and its source beside it, under the package's name with `.source.json` - (`course.source.json`), copied as the package was. Name the files it names, if any: a build - reads them beside it; +- the `.h5p`, and its source, which the build wrote beside it under the package's name with + `.source.json` (`course.source.json`): hand over that file, not the one you wrote, copied as + the package was. Name the files it names, if any: a build reads them beside it; - this line, as it is but for the source file's name, the only web address you give: ```text From 3f88473554d3a94d8494e5200483622345adffe2 Mon Sep 17 00:00:00 2001 From: Aleksandr Shevchuk Date: Fri, 20 Nov 2026 11:21:33 +0200 Subject: [PATCH 2/2] docs(author): what is kept of a quiz in the quiz format, and whose libraries the README means (#219) --- design/author.md | 5 ++++- packages/author/README.md | 8 +++++--- packages/mcp/lib/server.mjs | 3 ++- 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/design/author.md b/design/author.md index 687493ac..a6b0f4d8 100644 --- a/design/author.md +++ b/design/author.md @@ -434,7 +434,10 @@ text to the content check's rules, and `apps/skills` plays every example untrust gives that file, not the one the chat wrote. It is never written over: a name that is taken stops the build before a package is made. The one exception is the file being built, the usual name of a source that was handed over, which is rewritten by a rename, and only where - what it names has changed. A quiz in the quiz format has no field for it and stays as written. + what it names has changed. A quiz in the quiz format has no field for it: what is kept + beside its package, by the command line and the MCP server alike, is the source it was + built as (`quizSource`), which builds the same package and takes the field; a quiz that is + itself the file being built stays as written. - `builtWith` is a field of `sourceSchema`, described as a build's to write, and left out of the fields a problem lists as a source's; one that is not a name and a version is a problem saying to leave it out. A read leaves it out: the next build writes it. diff --git a/packages/author/README.md b/packages/author/README.md index 45f8e6a3..c763b2b0 100644 --- a/packages/author/README.md +++ b/packages/author/README.md @@ -48,7 +48,9 @@ more: `builtWith`, the content type and the pack's version of it. A source is bu often with a newer pack, and a build of one that names another version of its type says so: as a note where it builds, and with the problems where it does not, since a field may have changed since. That file is never written over either, but where it is the file being built, which is -kept up to date. +kept up to date. A quiz in the quiz format has no such field: built to a new name, it is kept +beside the package as the source it was built as, and built from that file itself, the file +stays as written. 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 @@ -264,8 +266,8 @@ inside those folders, on their real paths. A result's `builtWith` is the content type and the pack's version of it, `H5P.Blanks 1.14`, and its `source` the source as built, naming it: what to keep with the package, as the command line -writes it beside one. `buildPackage` writes the package alone. Its `libraries` are the folders the package -plays with, `install` those carried for an H5P site's upload check, and `coreApi` the newest H5P +writes it beside one; `buildPackage` writes the package alone. A result's `libraries` are the +folders the package 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 diff --git a/packages/mcp/lib/server.mjs b/packages/mcp/lib/server.mjs index a97e1b0b..0295dd9d 100644 --- a/packages/mcp/lib/server.mjs +++ b/packages/mcp/lib/server.mjs @@ -217,7 +217,8 @@ export async function createServer(options = {}) { try { result = await buildPackage(source, target, { base: dirname(target), within: allowed, fetch: publicFetch, libraries: options.libraries }) // Made new: a file or a link put at its name since the name was found free is not written through. - // As the build took it, naming the content type's version it was built with (author's #219). + // As the build took it, naming the content type's version it was built with (author's #219): + // for a quiz in the quiz format, the source it was built as, which has the field for it. unwritten = await writeFile(sourceFile, `${JSON.stringify(result.source, null, 2)}\n`, { flag: 'wx' }).then(() => undefined, (error) => error) } catch (error) { if (error instanceof SourceError) return refusal(`${error.message}\nFix each at its path and build again.${/outside the folders/.test(error.message) ? ` ${whereFiles(allowed)}` : ''}`)