Read a package back into its source: h5p-author read, and h5p_read in the MCP server (#236)
AL
3h ago+1188+1188+0123456789012345678901234567890123456789-51-51-01234567890123456789
What changes
- h5p-author:
readPackageandh5p-author read <package.h5p> <folder>. They write the source a build would take to make the package again,<name>.source.json, with the package's media beside it.paramsare the content ascheckContentreturns it, less what a build fills in.ContentGenerator.writtenwalks the generator back: for each field, what the generator writes when nothing is written, worked out at the field's own level. So defaults, interface texts equal to the content language's translation, part ids and the titles a build gives all drop out. Positions and sizes are kept.- Untouched fields are not written. That is what H5P's editor saves for fields nobody touched: empty texts and choices, a list it started (Interactive Video's text track with no file), and a default nobody opened (its summary task).
- Plain text comes back plain. Markup that is only the blocks a build wraps typing in reads as the typing. Game Map's neighbours go back to numbers, through a
readhook beside the layouts'beforeandafter. - Checked by a second build. The source is built again in memory and compared with the content. A text, number, flag or title that comes back otherwise is written as stored. Anything else is a note, as is whatever a build would refuse.
- Versions: only content for the pack's major.minor is read. Any other is refused, with both versions named.
- What a source cannot hold is a note: the author's comments, the change log, the licence's extra terms, and a part's own licence or authors.
- The archive is untrusted:
- only media the content names are written, and only under the folder;
- an archive with an entry leading out of its folders is refused;
- it never writes over a file.
- h5p-mcp:
h5p_read. It reads a package in the server's folders into a new folder beside it. It answers with the source, each file named by its full path, ready forh5p_build. The instructions gain one line. - Shared rather than copied:
wrapTextandunwrapTextin text.mjs (the plain branch ofmarkupText), andCOPYRIGHT_FIELDSandwrittenCopyrightin media.mjs. - Docs: design/author.md, design/mcp.md, both READMEs, design/layout.md, and the AGENTS.md and README rows.
Tested
- Round trip: every type file's example (32 of them) is built, read and built again. Each gives the same content but for the ids, with no notes.
- A package as another tool exports it reads, says what it drops, and builds. The test package has no libraries and no author; it has comments and a change log, a part with its own metadata, an empty tip, a copyright with every part empty, and a question with no title.
- Edge cases: a package for other versions is refused; nothing is written over a file; the read stays inside its folders; a path leading out is not written; the CLI works.
- The server:
h5p_readwrites beside the package and names files where it wrote them, the read source builds again, and refusals say why. - Suites:
- the author package: 259 tests, in Node and Chromium;
- the server: 20 tests;
pnpm typecheck.
- The owner's 88 real packages, read locally:
- 58 are refused for versions, mostly Interactive Video 1.27, Course Presentation 1.25 and 1.26, and Question Set 1.20.
- Of the other 30, 26 build as read.
- 4 need what their notes name: pictures missing from the package itself, styles pasted from Word, a question with one answer, and H5P.Row column widths with decimals.
- Haiku over MCP: asked to "add two harder questions" to the demo quiz, it read it and built at the first build in 6 of 6 runs. All 6 pass the check, at about $0.006 a run. In the first 3, it first guessed the path from its working folder each time. Once the parameter said "by its file name alone", none did.
Found, not done here
- 58 of 88 refused: reading content for older minors needs the libraries' upgrade steps, which the runtime runs (GPL). The plan has this as "later, if asked for".
- H5P.Row's column widths: its editor sets decimals, which the number rule refuses, in a build too.
- The skill:
SKILL.mddoes not offerreadyet.
Release
h5p-author 0.13.0 first, then h5p-mcp 0.2.0, which needs readPackage.
Summary by cubic
Adds h5p-author read (and readPackage) to turn a .h5p package back into the source a build would take to make it, with the package's media beside it, so a package can be changed and rebuilt. The MCP server gains the h5p_read tool for the same flow.
The read
- Leaves out what a build fills in: defaults, interface texts equal to the content language's translation, part ids, build-given titles, and fields the editor saved but an author never touched.
- Rebuilds the source in memory and holds it against the content; a value that comes back differently is written as stored, anything else is a note, as is whatever a build of it would refuse.
- Notes and drops what a source has no field for: the author's comments, change log, license extras, and a part's own license or authors.
Versions and safety
- Refuses content made for another library version than the pack's, naming both versions.
- Treats the archive as untrusted: only media the content names is written, under the folder, never over an existing file.
h5p-author 0.13.0 releases first; h5p-mcp 0.2.0 depends on its readPackage.