Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions design/author.md
Original file line number Diff line number Diff line change
Expand Up @@ -417,6 +417,31 @@ 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 `<package>.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: 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.
- 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
Expand Down
21 changes: 17 additions & 4 deletions packages/author/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
```
Expand All @@ -42,6 +43,15 @@ 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
Comment thread
alekswebnet marked this conversation as resolved.
Resolved
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
[h5p-author skill](https://github.com/missing-elements/h5p-toolkit/tree/main/skills/h5p-author)
Expand All @@ -58,6 +68,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:

Expand Down Expand Up @@ -214,7 +225,7 @@ Set's 2.6 MB, a container's up to 8.4 MB. `--all <folder>` 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() })
```

Expand Down Expand Up @@ -253,8 +264,10 @@ 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
plays with, `install` those carried for an H5P site's upload check, and `coreApi` the newest H5P
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. 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
Expand Down Expand Up @@ -359,7 +372,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']`.
Expand Down
47 changes: 45 additions & 2 deletions packages/author/bin/h5p-author.mjs
Original file line number Diff line number Diff line change
@@ -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'
Expand All @@ -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 <output>.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.
Expand Down Expand Up @@ -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
Expand All @@ -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) {
Expand Down
8 changes: 6 additions & 2 deletions packages/author/lib/browser.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, unknown>, content: Record<string, unknown>, libraries: string[], install: string[],
* blob: Blob, source: import('./build.mjs').Source, builtWith: string, manifest: Record<string, unknown>, content: Record<string, unknown>, 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<string, Blob> | Record<string, Blob>, 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
Expand Down Expand Up @@ -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()],
Expand Down
31 changes: 27 additions & 4 deletions packages/author/lib/build.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 }
Expand Down Expand Up @@ -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
Expand All @@ -244,10 +257,11 @@ async function closure(pack, main, content) {
* @param {import('./media.mjs').MediaStore<F>} 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<string, unknown>, content: Record<string, unknown>, selected: Map<string, import('./pack.mjs').PartLibrary>, install: Map<string, import('./pack.mjs').PartLibrary>, coreApi: import('./install.mjs').CoreApi, translations: TranslationReport[], notes: Problem[], outline: string }>}
* @returns {Promise<{ source: Source, builtWith: string, manifest: Record<string, unknown>, content: Record<string, unknown>, selected: Map<string, import('./pack.mjs').PartLibrary>, install: Map<string, import('./pack.mjs').PartLibrary>, 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 = []) {
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down
Loading