Skip to content

Read a package back into its source: h5p-author read, and h5p_read in the MCP server (#236) - #237

Merged
alekswebnet merged 5 commits into
mainfrom
feat/author-read
Nov 19, 2026
Merged

alekswebnet merged 5 commits into
mainfrom
feat/author-read

Conversation

@alekswebnet

@alekswebnet alekswebnet commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Closes #236. Step 3 of #219.

What changes

  • h5p-author: readPackage and h5p-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.
    • params are the content as checkContent returns it, less what a build fills in. ContentGenerator.written walks 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 read hook beside the layouts' before and after.
    • 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. So is what it holds in no form a source takes, which is left out: a file's licence H5P does not list, a licence version, an author without a name, a role, a year.
    • The archive is untrusted:
      • only media the content names are written, and only under the folder;
      • every path is checked before anything is made, so a link in the folder that leads out of it stops the read;
      • a file named by a path that could lead out is left out of the source, which so names no file outside its folder;
      • an archive with an entry leading out of its folders is refused;
      • it never writes over a file, and a read that fails takes away what it made.
  • 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 in that folder, ready for h5p_build, which looks for a file the package lacks there and nowhere else. The instructions gain one line.
  • Shared rather than copied: wrapText and unwrapText in text.mjs (the plain branch of markupText, which now also splits paragraphs at a blank line in Windows line endings), and COPYRIGHT_FIELDS and writtenCopyright in 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, and each media file written is the package's bytes.
  • 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 left out of the source; a link in the folder that leads out stops the read before anything is made; a read that fails partway takes away the folders it made; metadata in no form a source takes is noted; the CLI works.
  • The server: h5p_read writes beside the package and names files where it wrote them, the read source builds again, a file the package lacks is looked for in the read's folder only, and refusals say why.
  • Suites:
    • the author package: 261 tests, in Node and Chromium;
    • the server: 21 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.md does not offer read yet.

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, a part's own license or authors, an empty author list, and copyright parts a build refuses.

Versions and safety

  • Refuses content made for another library version than the pack's, naming both versions.
  • Treats the archive as untrusted: every path is checked against the folder before anything is made, so a link out of it stops the read; only media the content names is written, under the folder, never over an existing file; a failed read removes the folders it made.
  • h5p_read names files by the folder it read into, so a package missing media still builds from what was written.

h5p-author 0.13.0 releases first; h5p-mcp 0.2.0 depends on its readPackage.

Written for commit f47a2c5. Summary will update on new commits.

View guided diff Turn on auto-fix

)

readPackage and h5p-author read write the source a build would take to make a
package again, its media beside it: its own fields from h5p.json, its content
less what a build fills in, by the generator's own rules walked back
(ContentGenerator.written). The source is built again in memory and held to the
content as checked. Content for other versions of its libraries than the pack's
is refused, with both named.
…ld again (#236)

Reads a package in the server's folders into a new folder beside it, and
answers with the source, each file named where it was written, for h5p_build.
The instructions gain one line for changing a package the person has.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 18 files

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread packages/author/lib/node.mjs Resolved
Comment thread packages/mcp/lib/server.mjs Resolved
Comment thread packages/mcp/tests/server.test.ts Resolved
Comment thread packages/mcp/tests/server.test.ts Resolved
Comment thread packages/author/tests/read.test.ts Resolved
Comment thread packages/author/lib/read.mjs Resolved
Comment thread packages/author/lib/read.mjs Resolved
Comment thread packages/author/README.md Resolved
Comment thread packages/author/README.md Resolved
Comment thread packages/mcp/lib/server.mjs Resolved
- Every path is checked against the folder before anything is made, with
  or without `within`, so a link in the folder that leads out of it stops
  the read; `inside` resolves a folder not there yet as it does a path.
- A file named by a path a read cannot write is left out of the source,
  which so names no file outside its folder.
- A read that fails takes away the folders it made, where they are empty.
- A file's licence H5P does not list, or a copyright source that is no web
  address, is left out with a note; copyrights compare in one order.
- Authors left out or given the role "Author", a licence version a source
  cannot take, and a year that is none are noted; a part's authors that
  are no list no longer stop the read.
- wrapText splits paragraphs at a blank line in Windows line endings.
- The round trip compares the media written with the package's bytes.
- The README's two unclear sentences, and the refusal's, reworded.
A file the package lacks was passed back by its path in the package,
which h5p_build looked for in the first folder. Every local path is now
named in the read's folder, so a build looks for it there and nowhere
else. The tests check the source file written, compare paths portably,
and read a package that lacks its picture.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 12 files (changes from recent commits).

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread packages/author/lib/read.mjs Resolved
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Read a package back into a source: h5p-author read, and h5p_read in the MCP server (step 3 of #219)

1 participant