Repository navigation
Read a package back into its source: h5p-author read, and h5p_read in the MCP server (#236) - #237
alekswebnet wants to merge 2 commits into
Conversation
) 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.
There was a problem hiding this comment.
13 issues found across 18 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="packages/mcp/lib/server.mjs">
<violation number="1" location="packages/mcp/lib/server.mjs:81">
P2: `located` only rewrites media that was written. Any other `path` keeps the archive's raw string, which `h5p_build` then resolves against the first allowed folder. Consider refusing or dropping those paths from the returned source rather than passing them back unchanged.</violation>
<violation number="2" location="packages/mcp/lib/server.mjs:269">
P3: A failed read can leave the newly reserved folder behind. Clean up the folder created for this read when `readPackage` fails, while preserving any pre-existing or concurrently-created files.</violation>
</file>
<file name="packages/mcp/tests/server.test.ts">
<violation number="1" location="packages/mcp/tests/server.test.ts:168">
P2: The test does not verify that `h5p_read` actually writes the source file it reports. Access or read `join(beside, 'one-pixel.source.json')` before rebuilding from the returned source.</violation>
<violation number="2" location="packages/mcp/tests/server.test.ts:173">
P2: This assertion fails on Windows because `join` produces backslashes but the expected prefix hardcodes `/`. Compare against `join(beside, 'pixel.png')` instead.</violation>
</file>
<file name="packages/author/README.md">
<violation number="1" location="packages/author/README.md:162">
P3: The phrase 'to change it and build it again' appears twice in this sentence, and the sentence reads as a fragment. Drop the repetition, for example: 'The source a build would take to make the package again is the content type and the metadata from its `h5p.json`, ...'.</violation>
<violation number="2" location="packages/author/README.md:168">
P3: This sentence is hard to parse: 'and saved again on a site that has the pack's versions, it reads'. Reword it so the subject comes before the verb, for example: 'H5P moves content to a newer version as it plays it, so content saved again on a site that has the pack's versions reads here.'</violation>
</file>
<file name="packages/author/tests/read.test.ts">
<violation number="1" location="packages/author/tests/read.test.ts:110">
P2: This assertion does not verify that `readPackage` preserved the referenced media bytes; it only verifies the destination name exists. Compare each output file with the fixture bytes so a reader that copies the wrong archive entry cannot pass the round-trip suite.</violation>
</file>
<file name="packages/author/lib/media.mjs">
<violation number="1" location="packages/author/lib/media.mjs:101">
P2: `writtenCopyright` keeps a file's copyright licence as stored, but `copyright()` only accepts `COPYRIGHT_LICENSES`, which omits `CC0 1.0`, `CC PDM` and `ODC PDDL`. A package with one of those file licences reads back into a source that the build rejects. Either accept the full H5P licence list for copyright, or have the reader write `U` for licences the build cannot take.</violation>
</file>
<file name="packages/author/lib/text.mjs">
<violation number="1" location="packages/author/lib/text.mjs:191">
P2: `wrapText` does not split paragraphs on a blank line written as CRLF, so `"Line1\r\n\r\nLine2"` becomes one paragraph with two `<br>`s instead of two paragraphs. Accept `\r?\n` in the paragraph split so both line-ending styles match.</violation>
</file>
<file name="packages/author/lib/node.mjs">
<violation number="1" location="packages/author/lib/node.mjs:525">
P1: `readPackage` can write archive media through a symlinked destination component: `mkdir` follows the link before confinement is checked, and normal reads perform no confinement check at all. Resolve and validate the real destination before creating parent directories, and create the path without following symlinks.</violation>
</file>
<file name="packages/author/lib/read.mjs">
<violation number="1" location="packages/author/lib/read.mjs:187">
P2: An unsupported or malformed `licenseVersion` is silently dropped from the returned source. Emit a note whenever the manifest supplies a version that cannot be represented, so rebuilding does not change license metadata without warning.</violation>
<violation number="2" location="packages/author/lib/read.mjs:190">
P2: `ownFields` silently discards invalid author records and changes invalid roles to `Author` when other authors remain. Preserve the valid records but add notes for each dropped or normalized author value so the read reports this metadata loss.</violation>
<violation number="3" location="packages/author/lib/read.mjs:246">
P2: Malformed part metadata can crash `readContent`: `ownMetadata` calls `.map` on `metadata.authors` without verifying it is an array. Guard the value with `Array.isArray` and report or ignore malformed metadata consistently with the other package validation.</violation>
</file>
Reply with feedback, questions, or to request a fix.
View guided diff | Turn on auto-fix | Re-trigger cubic
| const made = [] | ||
| /** @param {string} to @param {(file: import('node:fs/promises').FileHandle) => Promise<void>} write */ | ||
| const create = async (to, write) => { | ||
| await mkdir(dirname(to), { recursive: true }) |
There was a problem hiding this comment.
P1: readPackage can write archive media through a symlinked destination component: mkdir follows the link before confinement is checked, and normal reads perform no confinement check at all. Resolve and validate the real destination before creating parent directories, and create the path without following symlinks.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/author/lib/node.mjs, line 525:
<comment>`readPackage` can write archive media through a symlinked destination component: `mkdir` follows the link before confinement is checked, and normal reads perform no confinement check at all. Resolve and validate the real destination before creating parent directories, and create the path without following symlinks.</comment>
<file context>
@@ -425,6 +432,130 @@ export async function buildPackage(input, output, options = {}) {
+ const made = []
+ /** @param {string} to @param {(file: import('node:fs/promises').FileHandle) => Promise<void>} write */
+ const create = async (to, write) => {
+ await mkdir(dirname(to), { recursive: true })
+ // A folder on the way may be a link out, which a confined read does not write through.
+ if (within && !(await inside(to, within))) throw new Error(`${to} is outside the folders this read may write in`)
</file context>
| function located(value, folder, files) { | ||
| if (Array.isArray(value)) return value.map((each) => located(each, folder, files)) | ||
| if (!value || typeof value !== 'object') return value | ||
| const entries = Object.entries(value).map(([key, each]) => [key, key === 'path' && typeof each === 'string' && files.has(each) ? join(folder, ...each.split('/')) : located(each, folder, files)]) |
There was a problem hiding this comment.
P2: located only rewrites media that was written. Any other path keeps the archive's raw string, which h5p_build then resolves against the first allowed folder. Consider refusing or dropping those paths from the returned source rather than passing them back unchanged.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/mcp/lib/server.mjs, line 81:
<comment>`located` only rewrites media that was written. Any other `path` keeps the archive's raw string, which `h5p_build` then resolves against the first allowed folder. Consider refusing or dropping those paths from the returned source rather than passing them back unchanged.</comment>
<file context>
@@ -65,8 +68,23 @@ const OUTLINE_LINES = 80
+function located(value, folder, files) {
+ if (Array.isArray(value)) return value.map((each) => located(each, folder, files))
+ if (!value || typeof value !== 'object') return value
+ const entries = Object.entries(value).map(([key, each]) => [key, key === 'path' && typeof each === 'string' && files.has(each) ? join(folder, ...each.split('/')) : located(each, folder, files)])
+ return Object.fromEntries(entries)
+}
</file context>
| const text = textOf(answer) | ||
| expect(answer.isError).toBeFalsy() | ||
| const beside = join(folder, 'one-pixel') | ||
| expect(text).toContain(`Read ${built}: H5P.Column. Its source is in ${join(beside, 'one-pixel.source.json')}, with its 1 media file beside it.`) |
There was a problem hiding this comment.
P2: The test does not verify that h5p_read actually writes the source file it reports. Access or read join(beside, 'one-pixel.source.json') before rebuilding from the returned source.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/mcp/tests/server.test.ts, line 168:
<comment>The test does not verify that `h5p_read` actually writes the source file it reports. Access or read `join(beside, 'one-pixel.source.json')` before rebuilding from the returned source.</comment>
<file context>
@@ -151,6 +151,45 @@ describe('h5p_build', () => {
+ const text = textOf(answer)
+ expect(answer.isError).toBeFalsy()
+ const beside = join(folder, 'one-pixel')
+ expect(text).toContain(`Read ${built}: H5P.Column. Its source is in ${join(beside, 'one-pixel.source.json')}, with its 1 media file beside it.`)
+ const read = JSON.parse(text.split('\n').at(-1)!)
+ expect(read).toMatchObject({ type: 'H5P.Column', title: 'One pixel', params: { content: [{ content: { library: 'H5P.Image', params: { alt: 'A pixel' } } }] } })
</file context>
| expect(text).toContain(`Read ${built}: H5P.Column. Its source is in ${join(beside, 'one-pixel.source.json')}, with its 1 media file beside it.`) | |
| expect(text).toContain(`Read ${built}: H5P.Column. Its source is in ${join(beside, 'one-pixel.source.json')}, with its 1 media file beside it.`) | |
| await access(join(beside, 'one-pixel.source.json')) |
| expect(read).toMatchObject({ type: 'H5P.Column', title: 'One pixel', params: { content: [{ content: { library: 'H5P.Image', params: { alt: 'A pixel' } } }] } }) | ||
| // Where it was written, read by a build wherever its package goes. | ||
| const path = read.params.content[0].content.params.file.path | ||
| expect(path.startsWith(`${beside}/`)).toBe(true) |
There was a problem hiding this comment.
P2: This assertion fails on Windows because join produces backslashes but the expected prefix hardcodes /. Compare against join(beside, 'pixel.png') instead.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/mcp/tests/server.test.ts, line 173:
<comment>This assertion fails on Windows because `join` produces backslashes but the expected prefix hardcodes `/`. Compare against `join(beside, 'pixel.png')` instead.</comment>
<file context>
@@ -151,6 +151,45 @@ describe('h5p_build', () => {
+ expect(read).toMatchObject({ type: 'H5P.Column', title: 'One pixel', params: { content: [{ content: { library: 'H5P.Image', params: { alt: 'A pixel' } } }] } })
+ // Where it was written, read by a build wherever its package goes.
+ const path = read.params.content[0].content.params.file.path
+ expect(path.startsWith(`${beside}/`)).toBe(true)
+ await access(path)
+ const again = builtOf(await call('h5p_build', { source: { ...read, title: 'One pixel, again' }, verify: false }))
</file context>
| expect(path.startsWith(`${beside}/`)).toBe(true) | |
| expect(path).toBe(join(beside, 'pixel.png')) |
| expect(JSON.parse(await readFile(read.output, 'utf8'))).toEqual(read.source) | ||
| const { type, title, language, license, authors } = read.source | ||
| expect({ type, title, language, license, authors }).toEqual({ type: first.manifest.mainLibrary, ...META }) | ||
| for (const path of read.files) expect(await exists(join(at, 'read', path)), path).toBe(true) |
There was a problem hiding this comment.
P2: This assertion does not verify that readPackage preserved the referenced media bytes; it only verifies the destination name exists. Compare each output file with the fixture bytes so a reader that copies the wrong archive entry cannot pass the round-trip suite.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/author/tests/read.test.ts, line 110:
<comment>This assertion does not verify that `readPackage` preserved the referenced media bytes; it only verifies the destination name exists. Compare each output file with the fixture bytes so a reader that copies the wrong archive entry cannot pass the round-trip suite.</comment>
<file context>
@@ -0,0 +1,231 @@
+ expect(JSON.parse(await readFile(read.output, 'utf8'))).toEqual(read.source)
+ const { type, title, language, license, authors } = read.source
+ expect({ type, title, language, license, authors }).toEqual({ type: first.manifest.mainLibrary, ...META })
+ for (const path of read.files) expect(await exists(join(at, 'read', path)), path).toBe(true)
+ const again = await buildPackage(read.source, undefined, { base: join(at, 'read'), check: true })
+ expect(withoutIds(again.content)).toEqual(withoutIds(first.content))
</file context>
| if (title === 'Untitled' && manifest.title !== 'Untitled') note('title', 'is not in h5p.json: written as "Untitled"') | ||
| const license = LICENSES.includes(manifest.license) ? manifest.license : 'U' | ||
| if (says(manifest.license) && license !== manifest.license) note('license', `${JSON.stringify(manifest.license)} is no licence H5P names: written as "U"`) | ||
| const versioned = license.startsWith('CC BY') && CC_VERSIONS.includes(manifest.licenseVersion) |
There was a problem hiding this comment.
P2: An unsupported or malformed licenseVersion is silently dropped from the returned source. Emit a note whenever the manifest supplies a version that cannot be represented, so rebuilding does not change license metadata without warning.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/author/lib/read.mjs, line 187:
<comment>An unsupported or malformed `licenseVersion` is silently dropped from the returned source. Emit a note whenever the manifest supplies a version that cannot be represented, so rebuilding does not change license metadata without warning.</comment>
<file context>
@@ -0,0 +1,316 @@
+ if (title === 'Untitled' && manifest.title !== 'Untitled') note('title', 'is not in h5p.json: written as "Untitled"')
+ const license = LICENSES.includes(manifest.license) ? manifest.license : 'U'
+ if (says(manifest.license) && license !== manifest.license) note('license', `${JSON.stringify(manifest.license)} is no licence H5P names: written as "U"`)
+ const versioned = license.startsWith('CC BY') && CC_VERSIONS.includes(manifest.licenseVersion)
+ /** @type {{ name: string, role: string }[]} */
+ const authors = (Array.isArray(manifest.authors) ? manifest.authors : [])
</file context>
| if (!says(value)) return false | ||
| if (key === 'license') return value !== 'U' && value !== source.license | ||
| if (key === 'licenseVersion') return value !== source.licenseVersion | ||
| if (key === 'authors') return JSON.stringify(value.map((/** @type {any} */ author) => [author?.name, author?.role])) !== JSON.stringify(source.authors.map((author) => [author.name, author.role])) |
There was a problem hiding this comment.
P2: Malformed part metadata can crash readContent: ownMetadata calls .map on metadata.authors without verifying it is an array. Guard the value with Array.isArray and report or ignore malformed metadata consistently with the other package validation.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/author/lib/read.mjs, line 246:
<comment>Malformed part metadata can crash `readContent`: `ownMetadata` calls `.map` on `metadata.authors` without verifying it is an array. Guard the value with `Array.isArray` and report or ignore malformed metadata consistently with the other package validation.</comment>
<file context>
@@ -0,0 +1,316 @@
+ if (!says(value)) return false
+ if (key === 'license') return value !== 'U' && value !== source.license
+ if (key === 'licenseVersion') return value !== source.licenseVersion
+ if (key === 'authors') return JSON.stringify(value.map((/** @type {any} */ author) => [author?.name, author?.role])) !== JSON.stringify(source.authors.map((author) => [author.name, author.role]))
+ return true
+ })
</file context>
| Change it, then build it again: h5p-author build rivers/rivers.source.json <output.h5p> | ||
| ``` | ||
|
|
||
| The source a build would take to make the package again, to change it and build it again: the |
There was a problem hiding this comment.
P3: The phrase 'to change it and build it again' appears twice in this sentence, and the sentence reads as a fragment. Drop the repetition, for example: 'The source a build would take to make the package again is the content type and the metadata from its h5p.json, ...'.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/author/README.md, line 162:
<comment>The phrase 'to change it and build it again' appears twice in this sentence, and the sentence reads as a fragment. Drop the repetition, for example: 'The source a build would take to make the package again is the content type and the metadata from its `h5p.json`, ...'.</comment>
<file context>
@@ -147,6 +148,32 @@ packs them as the zips chat apps install, and lists the build tool and each bund
+Change it, then build it again: h5p-author build rivers/rivers.source.json <output.h5p>
+```
+
+The source a build would take to make the package again, to change it and build it again: the
+content type and the metadata from its `h5p.json`, and of its content only what differs from the
+defaults, interface texts in the content's language included. Its pictures, videos and other files
</file context>
| The source a build would take to make the package again, to change it and build it again: the | |
| The source a build would take to make the package again is the content type and the metadata from its |
| It reads content made for the pack's versions of its libraries, and refuses any other, naming both | ||
| versions: H5P moves content to a newer version as it plays it, and saved again on a site that has | ||
| the pack's versions, it reads. What a source has no field for is said and left out: the author's comments, |
There was a problem hiding this comment.
P3: This sentence is hard to parse: 'and saved again on a site that has the pack's versions, it reads'. Reword it so the subject comes before the verb, for example: 'H5P moves content to a newer version as it plays it, so content saved again on a site that has the pack's versions reads here.'
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/author/README.md, line 168:
<comment>This sentence is hard to parse: 'and saved again on a site that has the pack's versions, it reads'. Reword it so the subject comes before the verb, for example: 'H5P moves content to a newer version as it plays it, so content saved again on a site that has the pack's versions reads here.'</comment>
<file context>
@@ -147,6 +148,32 @@ packs them as the zips chat apps install, and lists the build tool and each bund
+go beside the source, at the paths it names them by. Positions and sizes are kept, so a slide or a
+video keeps its layout. Each part gets a new id when it is built again.
+
+It reads content made for the pack's versions of its libraries, and refuses any other, naming both
+versions: H5P moves content to a newer version as it plays it, and saved again on a site that has
+the pack's versions, it reads. What a source has no field for is said and left out: the author's comments,
</file context>
| It reads content made for the pack's versions of its libraries, and refuses any other, naming both | |
| versions: H5P moves content to a newer version as it plays it, and saved again on a site that has | |
| the pack's versions, it reads. What a source has no field for is said and left out: the author's comments, | |
| It reads content made for the pack's versions of its libraries, and refuses any other, naming both | |
| versions. H5P moves content to a newer version as it plays it, so content saved again on a site that | |
| has the pack's versions reads here. What a source has no field for is said and left out: the author's comments, |
| const folder = await freeFolder(dirname(path), fileStem(basename(path).replace(/\.h5p$/i, ''))) | ||
| let result | ||
| try { | ||
| result = await readPackage(path, folder, { within: allowed, libraries: options.libraries }) |
There was a problem hiding this comment.
P3: A failed read can leave the newly reserved folder behind. Clean up the folder created for this read when readPackage fails, while preserving any pre-existing or concurrently-created files.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/mcp/lib/server.mjs, line 269:
<comment>A failed read can leave the newly reserved folder behind. Clean up the folder created for this read when `readPackage` fails, while preserving any pre-existing or concurrently-created files.</comment>
<file context>
@@ -219,6 +253,33 @@ export async function createServer(options = {}) {
+ const folder = await freeFolder(dirname(path), fileStem(basename(path).replace(/\.h5p$/i, '')))
+ let result
+ try {
+ result = await readPackage(path, folder, { within: allowed, libraries: options.libraries })
+ } catch (error) {
+ return refusal(error instanceof Error ? error.message : String(error))
</file context>
Closes #236. Step 3 of #219.
What changes
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.readhook beside the layouts'beforeandafter.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.wrapTextandunwrapTextin text.mjs (the plain branch ofmarkupText), andCOPYRIGHT_FIELDSandwrittenCopyrightin media.mjs.Tested
h5p_readwrites beside the package and names files where it wrote them, the read source builds again, and refusals say why.pnpm typecheck.Found, not done here
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(andreadPackage) to turn a.h5ppackage 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 theh5p_readtool for the same flow.The read
Versions and safety
h5p-author0.13.0 releases first;h5p-mcp0.2.0 depends on itsreadPackage.Written for commit ad811c5. Summary will update on new commits.