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
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,10 @@ packages/normalize/LICENSE
packages/verify/LICENSE
packages/author/LICENSE
packages/mcp/LICENSE
# The h5p-author skill's text and build routes, which the author's `prepack` copies beside its type files (#178, #204).
# The h5p-author skill's text and build routes, which the author's `prepack` copies beside its type files (#178, #204, #242).
packages/author/SKILL.md
packages/author/references/authoring.md
packages/author/references/change.md
packages/author/references/build/
packages/cmi5/LICENSE
packages/embed/LICENSE
Expand Down
9 changes: 8 additions & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,12 @@ model may have written:
app's roots, as they are given. Given none, it uses Desktop, Documents and
Downloads, and never the home folder whole. It never writes over a file, and
its preview serves one package on `127.0.0.1` until its tab is closed.
- A read (`readPackage`, `h5p-author read`, the MCP server's `h5p_read`) takes
the archive as untrusted. It writes only the files the content names, only in
its folder, with every path checked before anything is made, so a link in the
folder that leads out of it stops the read; never over a file; and it leaves
out of the source a file named by a path that could lead out of the folder.
An archive with an entry leading out of its folders is not read.

Reports are particularly helpful for issues such as:

Expand All @@ -100,7 +106,8 @@ Reports are particularly helpful for issues such as:
lifecycle safeguards;
- a build confined by `within` that reads or writes outside its folders or
writes over a file, `publicFetch` reaching a local network by an address it
should refuse, or the MCP server reaching a file outside its folders;
should refuse, a read that writes outside its folder or over a file, or the
MCP server reaching a file outside its folders;
- vulnerabilities in the published player, runtime, library bundle, normalizer,
verifier, author package, MCP server, cmi5 package, embed site writer, demo,
or installable app.
Expand Down
36 changes: 36 additions & 0 deletions apps/skills/tests/front-matter.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
import { readdir, readFile } from 'node:fs/promises'
import { resolve } from 'node:path'
import { describe, expect, it } from 'vitest'

/*
* Each skill's front matter as a YAML parser reads it: skills.sh, a chat that takes the skill as a
* zip and an agent's skill loader parse it, and one that does not parse is a skill they do not list
* (#242's description broke it with a colon). No YAML parser is in the workspace, so each line is
* held to the form the skills write, `key: value` with a plain value, which YAML ends at a colon
* followed by a space and cuts at a space followed by `#`; and the name and description to the
* Agent Skills specification's limits.
*/
const skills = resolve(import.meta.dirname, '../../../skills')
const names = (await readdir(skills, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name)

describe("the skills' front matter", () => {
it.each(names)('%s parses, its name its folder and its description under 1024 characters', async (name) => {
const text = await readFile(resolve(skills, name, 'SKILL.md'), 'utf8')
const front = /^---\n([\s\S]*?)\n---\n/.exec(text)?.[1]
expect(front, 'front matter between two --- lines').toBeDefined()
const fields = new Map<string, string>()
for (const line of front!.split('\n')) {
const [, key, value] = /^([a-z-]+): (.+)$/.exec(line) ?? []
expect(key, `"${line.slice(0, 40)}" is a key and a value`).toBeDefined()
expect(value, `${key}: a colon followed by a space or the line's end ends a plain value`).not.toMatch(/:(?: |$)/)
expect(value, `${key}: a space followed by # starts a comment`).not.toMatch(/ #/)
expect(value, `${key}: a plain value cannot start with an indicator`).not.toMatch(/^[-?:,[\]{}#&*!|>'"%@`]/)
fields.set(key, value)
}
expect(fields.get('name')).toBe(name)
expect(name).toMatch(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
Comment thread
alekswebnet marked this conversation as resolved.
Resolved
expect(name.length).toBeLessThanOrEqual(64)
expect(fields.get('description')?.length).toBeGreaterThan(0)
expect(fields.get('description')!.length).toBeLessThanOrEqual(1024)
})
})
20 changes: 16 additions & 4 deletions design/author.md
Original file line number Diff line number Diff line change
Expand Up @@ -197,9 +197,9 @@ text to the content check's rules, and `apps/skills` plays every example untrust
- Only content for the pack's major.minor of every library it names is read; any other is
refused with both versions named, since moving it is the library's own upgrade, the runtime's
(GPL). Of the owner's 88 real packages, 58 were refused so, mostly Interactive Video 1.27 and
Course Presentation 1.25 and 1.26. Of the other 30, 26 build as read; 4 need what their notes
name: pictures missing from the package, styles pasted from Word, a question with one answer,
and H5P.Row's column widths with decimals, which its editor sets and the number rule refuses.
Course Presentation 1.25 and 1.26. Of the other 30, 27 build as read; 3 need what their notes
name: pictures missing from the package, styles pasted from Word, and a question with one
answer.
- What a source has no field for is said and left out: the author's comments, the change log,
the licence's extra terms, and a part's own licence or authors, a build giving every part the
source's.
Expand Down Expand Up @@ -253,7 +253,10 @@ text to the content check's rules, and `apps/skills` plays every example untrust
each rule's script. To move to a newer editor: diff those scripts between the pinned version and
the new one, port what changed, move the commits named in the two files, and run the author's
tests and `apps/skills`'. One departure (#162): a multiple of a fractional step is taken within a
rounding error, where the editor's `%` refuses 0.3 in steps of 0.1.
rounding error, where the editor's `%` refuses 0.3 in steps of 0.1. Two more (#242), for what
H5P.com's own editor writes, H5P's content check keeps and the library plays: H5P.Row's column
widths take two decimals, and a row's column may be left empty, a spacer (a layout's `decimals`
and `optional`); the owner's package from H5P.com builds again after a read.
- **A package installs on an H5P site** (#146). H5P core's upload check wants every library a
package carries to have its preloaded, dynamic and editor dependencies with it at the exact
major.minor, or installed on the site; a fresh Moodle refused 28 of 32 examples without them (see
Expand Down Expand Up @@ -423,6 +426,15 @@ text to the content check's rules, and `apps/skills` plays every example untrust
the build archive attached (route 1, `references/build/archive.md`), npm (route 2, `npm.md`),
Node (route 3, `two-files.md`), anything else (route 4, `browser.md`). Routes 1 to 3 hand over
by `built-here.md`: the build's problems, the verifier where npm answered, and the hand-over.
- A package the user has is changed by `references/change.md` (#242), in place of steps 1 and 2,
asking nothing: read by the tool of the first route that holds (route 3 fetches the bundle of
the type the package's `h5p.json` names; route 4 cannot read one), the source changed as asked,
built by the same route from the read folder, and handed over as any build. The description
Comment thread
alekswebnet marked this conversation as resolved.
Resolved
names it in its first sentence. Given a quiz.h5p and the build archive and asked for two
harder questions, Haiku in Claude Code opened the skill in 1 of 3 runs with "or change an
.h5p" at the description's end, and in the other 2 edited `content.json` and zipped it by
hand; with it in the first sentence, and "never edit or zip one by hand", in 3 of 3, each
reading, changing and building with the tool, at about $0.014 a run.

A chat reads `SKILL.md` and its route's file, where every chat read all four routes, 18.9 KB,
before.
Expand Down
4 changes: 3 additions & 1 deletion design/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,9 @@ agent to write builds and plays. For h5p-to-scorm that is its commands, run as i
their zips, played as a learner under a stand-in LMS with real content. h5p-author's own code is
the author package's, tested with it. The playback test plays the quiz in the verifier's preview,
the page the skill hands a person to review it in, in Chromium only; the player's own suite covers
the engines.
the engines. Each skill's front matter is held to what a YAML parser reads, and its name and
description to the Agent Skills limits (`front-matter.test.ts`): one that does not parse is a
skill that skills.sh and a chat's upload do not list.

The app's tests follow the same variable (`apps/demo/tests/engine.ts`; `tests/harness.ts`
starts the dev server and the second-origin package host and waits on the element for all of
Expand Down
7 changes: 4 additions & 3 deletions packages/author/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,10 @@ type, and only the fields that differ from its defaults. The rest comes from the
`semantics.json` and their translations for the content's language; the libraries come from
[@missing-elements/h5p-libraries](https://www.npmjs.com/package/@missing-elements/h5p-libraries),
the pack this release pins, each checked against the pack's SHA-256 index. No H5P server, no
editor, no network but for media named by web address. `read` turns a package back into its
source, to change it and build it again. Needs Node 22 or later; write `@latest`, since without it
npm on an older Node quietly installs an older release.
editor, no network but for media named by web address, and no telemetry: a build reads the
source, the files it names and the pack, and writes the package. `read` turns a package
back into its source, to change it and build it again. Needs Node 22 or later; write `@latest`,
since without it npm on an older Node quietly installs an older release.

```bash
npx @missing-elements/h5p-author@latest build rivers.json rivers.h5p
Expand Down
2 changes: 1 addition & 1 deletion packages/author/lib/node.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ export async function openPack(folder) {
// A content type's bundle holds what the type can hold, and no addon: a source whose text
// calls for one, or another type's library, needs its part added.
if (folder && /** @type {{ code?: unknown }} */ (error)?.code === 'ENOENT') {
throw new Error(`The parts folder ${directory} has no ${entry.folder}.h5p, which this build needs: add it from the library pack's parts/`)
throw new Error(`The parts folder ${directory} has no ${entry.folder}.h5p, which this package needs: add it from the library pack's parts/`)
}
throw new Error(`Cannot read the library part ${entry.folder} from ${origin}`, { cause: error })
}
Expand Down
45 changes: 38 additions & 7 deletions packages/author/lib/types.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,13 @@ import { stripTags } from './text.mjs'
* - `read` turns what the two wrote back into what a source writes, for a package read back
* into a source (#236), run on that source's parameters;
* - `sets` names the hidden fields the layout sets, which the schema leaves out;
* - `optional` names fields the semantics call required that the content plays without, and the
* editor never asks for.
* - `optional` names fields the semantics call required that the content plays without, which the
* editor never asks for or an editor other than the pinned one leaves out;
* - `decimals` names number fields that take decimals their semantics do not give, and how many,
* where an editor other than the pinned one writes them and the content plays them.
*
* Paths in `sets` and `optional` are dotted, `[]` for a list's item, relative to the type's own
* parameters.
* Paths in `sets`, `optional` and `decimals` are dotted, `[]` for a list's item, relative to the
* type's own parameters.
*
* The widgets followed are the newest release of the minor each content type in the pack names in
* its `editorDependencies`: H5PEditor.InteractiveVideo 1.26.3 (h5p/h5p-editor-interactive-video at
Expand All @@ -42,7 +44,8 @@ import { stripTags } from './text.mjs'
* after?: (params: any, path: string, context: LayoutContext) => void,
* read?: (written: any, path: string, context: LayoutContext) => void,
* sets?: string[],
* optional?: string[]
* optional?: string[],
* decimals?: Record<string, number>
* }} Layout
*/

Expand Down Expand Up @@ -821,6 +824,27 @@ const dragText = {
/** @type {Layout} */
const video = { optional: ['visuals.poster'] }

/* ---------------------------------------------------------------- Row */

/**
* A row's columns, each a share of its width in percent. The standard form refuses a decimal typed
* into one, the field giving no `decimals`, and no editor in the pack sets them; but H5P.com's own
* editor writes them in hundredths, as the owner's package from there holds (24.76, 62.56), H5P's
* content check keeps them, and the library plays one as a CSS width. So a share takes two
* decimals, and such a package builds again after a read (#242).
* @type {Layout}
*/
const row = { decimals: { 'columns[].width': 2 } }
Comment thread
alekswebnet marked this conversation as resolved.
Resolved

/**
* A row's column with nothing in it, which H5P.com's editor leaves as a spacer, as the owner's
* package from there holds (two of three columns empty, the third between them). H5P's content
* check takes the empty list out, and the library plays a column with no content as an empty one
* (`params.content === undefined` becomes `[]`), so a source may leave it out (#242).
* @type {Layout}
*/
const rowColumn = { optional: ['content'] }

/** @type {Record<string, Layout>} */
export const LAYOUTS = {
'H5P.QuestionSet': questionSet,
Expand All @@ -832,11 +856,14 @@ export const LAYOUTS = {
'H5P.BranchingScenario': branchingScenario,
'H5P.GameMap': gameMap,
'H5P.ImageHotspotQuestion': imageHotspotQuestion,
'H5P.Video': video
'H5P.Video': video,
'H5P.Row': row,
'H5P.RowColumn': rowColumn
}

/**
* Semantics with the fields a layout makes optional marked so, for a copy the generator reads.
* Semantics with the fields a layout makes optional marked so, and those it gives decimals given
* them, for a copy the generator reads.
* @param {string} machineName
* @param {any[]} semantics
*/
Expand All @@ -846,6 +873,10 @@ export function patchSemantics(machineName, semantics) {
const field = fieldAt(semantics, path.replace(/\[\]/g, '').split('.'))
if (field) field.optional = true
}
for (const [path, decimals] of Object.entries(layout?.decimals ?? {})) {
const field = fieldAt(semantics, path.replace(/\[\]/g, '').split('.'))
if (field) field.decimals = decimals
}
return semantics
}

Expand Down
1 change: 1 addition & 0 deletions packages/author/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
"./references/types/*.md": "./references/types/*.md",
"./references/build/*.md": "./references/build/*.md",
"./references/authoring.md": "./references/authoring.md",
"./references/change.md": "./references/change.md",
Comment thread
alekswebnet marked this conversation as resolved.
Resolved
"./SKILL.md": "./SKILL.md",
"./package.json": "./package.json"
},
Expand Down
7 changes: 4 additions & 3 deletions packages/author/scripts/copy-skill.mjs
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
// The h5p-author skill's text, copied into the package as `prepack` runs: `SKILL.md`, its brief,
// `references/authoring.md`, its build routes, `references/build/`, one file a way to build, and
// its type files, each content type's notes, an example and its fields, as the release has them.
// `references/authoring.md`, how to change a package, `references/change.md`, its build routes,
// `references/build/`, one file a way to build, and its type files, each content type's notes,
// an example and its fields, as the release has them.
// A page that builds, with no skill beside it, hands the type files to a chat whose source had
// problems (#172), and a site builds the skill's zips from the package it pins. They are the
// skill's, at the repository's root, where `npx skills add` looks; the copy is not in git.
Expand All @@ -21,4 +22,4 @@ await rm(fileURLToPath(new URL('../references/', import.meta.url)), { recursive:
await rm(fileURLToPath(new URL('../SKILL.md', import.meta.url)), { force: true })
await cp(references, fileURLToPath(new URL('../references/', import.meta.url)), { recursive: true })
await cp(fileURLToPath(new URL('SKILL.md', skill)), fileURLToPath(new URL('../SKILL.md', import.meta.url)))
console.log(`Copied SKILL.md, references/authoring.md, ${build} build files to references/build/ and ${types} type files to references/types/`)
console.log(`Copied SKILL.md, references/authoring.md, references/change.md, ${build} build files to references/build/ and ${types} type files to references/types/`)
Loading