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/player/LICENSE
packages/normalize/LICENSE
packages/verify/LICENSE
packages/author/LICENSE
# The h5p-author skill's text, which the author's `prepack` copies beside its type files (#178).
# The h5p-author skill's text and build routes, which the author's `prepack` copies beside its type files (#178, #204).
packages/author/SKILL.md
packages/author/references/authoring.md
packages/author/references/build/
packages/cmi5/LICENSE
packages/embed/LICENSE

Expand Down
177 changes: 174 additions & 3 deletions design/author.md

Large diffs are not rendered by default.

12 changes: 7 additions & 5 deletions design/layout.md
Original file line number Diff line number Diff line change
Expand Up @@ -207,9 +207,9 @@ packages/author/ @missing-elements/h5p-author — a playable .h5p of an
pack (`pnpm --filter @missing-elements/h5p-author sync:skill`);
check-pack-published.mjs, the publish guard for the pinned pack and player,
and the normalizer's `./crc32`; copy-skill.mjs, `prepack`'s copy of
the skill's text and type files, `SKILL.md`, `references/authoring.md`
and `references/types/`, which the package carries and git does not
(#172, #178)
the skill's text, build routes and type files, `SKILL.md` and all of
`references/` (`authoring.md`, `build/`, `types/`), which the package
carries and git does not (#172, #178)
tests/ node tests: the generator, text and translations, layouts and schema, the
loader, builds with media from disk and a local server, the command, the
quiz format, the check of saved content, the demo's packages among it, and
Expand Down Expand Up @@ -419,8 +419,10 @@ skills/ agent skills, one directory per skill, at the root bec
type chosen with the user first, a source of only what differs from the
defaults, written from references/types/<Type>.md — notes, a tested
example and the fields, their section generated from the pack — built
with `npx @missing-elements/h5p-author`, then the verifier's check, its
screenshot and its preview for the user; tested from apps/skills)
by the first of four routes whose check holds, each a file of
references/build/ (the archive, npm, two files, the user's browser), then
the verifier's check, its screenshot and its preview for the user; tested
from apps/skills)

api/no-range.js the Vercel function that stands in for a host without Range on the demo
vercel.json the deployment: build command, the /no-range rewrite, caching and security headers
Expand Down
7 changes: 4 additions & 3 deletions packages/author/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -136,11 +136,12 @@ The package carries those type files too, as the release has them:
`@missing-elements/h5p-author/references/types/H5P.TrueFalse.md` is the type's notes, an example and
these fields. A page that builds for a chat with no skill beside it hands them over with a source's
problems, as the [build page](https://missing-elements.github.io/h5p/build/) does. The skill's text
travels with them, `@missing-elements/h5p-author/SKILL.md` and its brief,
`references/authoring.md`, so a site can serve the skill from the release it pins:
travels with them, `@missing-elements/h5p-author/SKILL.md`, its brief,
`references/authoring.md`, and its build routes, `references/build/<route>.md`, so a site can
serve the skill from the release it pins:
[missing-elements.github.io](https://missing-elements.github.io/h5p/create-with-ai/#install)
packs them as the zips chat apps install, and lists the build tool and each bundle that the
skill's step 3 fetches at
skill's route 3, from two files, fetches at
[missing-elements.github.io/h5p/skill/](https://missing-elements.github.io/h5p/skill/).

## A content type's bundle
Expand Down
2 changes: 1 addition & 1 deletion packages/author/lib/schema.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -229,7 +229,7 @@ export function withSection(text, section, name) {
* for a licence they skip `U`, each on its own: what they gave stays. A part other content
* holds has none: it is sub-content.
*/
export const SOURCE_FIELDS = 'The example is `type` and `params` alone, and `params` holds the fields below. A source also names its own `title`, `language`, `license` and `authors`, all four required: the build refuses a source that leaves out any of them. The author\'s name and the licence are the user\'s: ask for what they have not given. For a name they skip, write the one you know them by, or "Unknown"; for a licence they skip, `U`.'
export const SOURCE_FIELDS = 'The example is `type` and `params` alone, and `params` holds the fields below. A source also names its own `title`, `language`, `license` and `authors`, all four required: the build refuses a source that leaves out any of them. Write the author and the licence the user gave, as given, and ask for neither: an author not given is the name you know the user by, or "Unknown"; a licence not given, or one no code below stands for, is `U`; never make up a name. A licence is one of these H5P codes: `U`, `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`. Only the six CC BY codes take a version, written apart, one of 4.0, 3.0, 2.5, 2.0 or 1.0: "CC BY 4.0" is `"license": "CC BY", "licenseVersion": "4.0"`. `CC0 1.0` is one code, as it stands.'

/**
* The generated section of a type file: the fields, under a heading, between markers that a
Expand Down
1 change: 1 addition & 0 deletions packages/author/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@
"default": "./lib/browser.mjs"
},
"./references/types/*.md": "./references/types/*.md",
"./references/build/*.md": "./references/build/*.md",
"./references/authoring.md": "./references/authoring.md",
"./SKILL.md": "./SKILL.md",
"./package.json": "./package.json"
Expand Down
30 changes: 16 additions & 14 deletions packages/author/scripts/copy-skill.mjs
Original file line number Diff line number Diff line change
@@ -1,22 +1,24 @@
// The h5p-author skill's text, copied into the package as `prepack` runs: `SKILL.md`, its brief,
// `references/authoring.md`, 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 serves the skill to a chat given a link to
// it rather than GitHub's, which limits the requests of addresses many users share (#178). They are
// the skill's, at the repository's root, where `npx skills add` looks; the copy is not in git.
import { cp, mkdir, readdir, rm } from 'node:fs/promises'
// `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.
// 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.
import { cp, readdir, rm } from 'node:fs/promises'
import { fileURLToPath } from 'node:url'

const skill = new URL('../../../skills/h5p-author/', import.meta.url)
const from = fileURLToPath(new URL('references/types/', skill))
const to = fileURLToPath(new URL('../references/types/', import.meta.url))
const references = fileURLToPath(new URL('references/', skill))
/** The `.md` files of one folder of the skill's `references/`, which may not be empty. @param {string} folder */
const count = async (folder) => {
const names = (await readdir(`${references}${folder}/`)).filter((name) => name.endsWith('.md'))
if (!names.length) throw new Error(`No ${folder} files in ${references}${folder}/`)
return names.length
}
const [types, build] = [await count('types'), await count('build')]

await rm(fileURLToPath(new URL('../references/', import.meta.url)), { recursive: true, force: true })
await rm(fileURLToPath(new URL('../SKILL.md', import.meta.url)), { force: true })
await mkdir(to, { recursive: true })
const files = (await readdir(from)).filter((name) => name.endsWith('.md'))
if (!files.length) throw new Error(`No type files in ${from}`)
for (const name of files) await cp(`${from}${name}`, `${to}${name}`)
await cp(fileURLToPath(new URL('references/authoring.md', skill)), fileURLToPath(new URL('../references/authoring.md', import.meta.url)))
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 and ${files.length} type files to references/types/`)
console.log(`Copied SKILL.md, references/authoring.md, ${build} build files to references/build/ and ${types} type files to references/types/`)
9 changes: 6 additions & 3 deletions packages/author/tests/build.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -802,17 +802,19 @@ describe('the build', () => {
})

describe('the package', () => {
it('carries the skill\'s text and type files, copied as it is packed, for a page to hand to a chat (#172, #178)', async () => {
it('carries the skill\'s text, build routes and type files, copied as it is packed, for a page to hand to a chat (#172, #178)', async () => {
const skill = resolve(import.meta.dirname, '../../../skills/h5p-author')
const copied = resolve(import.meta.dirname, '../references/types')
const { stdout } = await exec(process.execPath, [resolve(import.meta.dirname, '../scripts/copy-skill.mjs')])
const names = (await readdir(join(skill, 'references/types'))).filter(name => name.endsWith('.md')).sort()
expect(names).toContain('H5P.InteractiveBook.md')
expect(stdout).toContain(`Copied SKILL.md, references/authoring.md and ${names.length} type files`)
const routes = (await readdir(join(skill, 'references/build'))).filter(name => name.endsWith('.md')).sort()
expect(routes).toContain('browser.md')
expect(stdout).toContain(`Copied SKILL.md, references/authoring.md, ${routes.length} build files to references/build/ and ${names.length} type files`)
expect((await readdir(copied)).sort()).toEqual(names)
for (const name of names) expect(await readFile(join(copied, name), 'utf8'), name).toBe(await readFile(join(skill, 'references/types', name), 'utf8'))
// The skill's text beside them, as it is, for a site to serve to a chat given a link.
for (const name of ['SKILL.md', 'references/authoring.md']) {
for (const name of ['SKILL.md', 'references/authoring.md', ...routes.map(route => `references/build/${route}`)]) {
expect(await readFile(resolve(import.meta.dirname, '..', name), 'utf8'), name).toBe(await readFile(join(skill, name), 'utf8'))
}
// Packed and found: in `files`, copied by `prepack`, and each one an export of its own.
Expand All @@ -823,6 +825,7 @@ describe('the package', () => {
expect(require.resolve('@missing-elements/h5p-author/references/types/H5P.InteractiveBook.md')).toBe(join(copied, 'H5P.InteractiveBook.md'))
expect(require.resolve('@missing-elements/h5p-author/SKILL.md')).toBe(resolve(import.meta.dirname, '../SKILL.md'))
expect(require.resolve('@missing-elements/h5p-author/references/authoring.md')).toBe(resolve(import.meta.dirname, '../references/authoring.md'))
expect(require.resolve('@missing-elements/h5p-author/references/build/browser.md')).toBe(resolve(import.meta.dirname, '../references/build/browser.md'))
})
})

Expand Down
11 changes: 7 additions & 4 deletions packages/author/tests/layout.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -321,15 +321,18 @@ describe('the schema a source is written from', () => {
expect(markdown.endsWith(`\`h5p-author schema H5P.Test --all\` lists them, for a source to set one.\n\n${GENERATED_END}`)).toBe(true)
})

it('says what a content type\'s source names beside its fields, the author asked of the user, and not for a part (#182)', () => {
it('says what a content type\'s source names beside its fields, the author and licence taken as given, and not for a part (#182)', () => {
const type = schemaMarkdown({ machineName: 'H5P.Test', majorVersion: 1, minorVersion: 2, runnable: 1 }, semantics)
expect(type.startsWith(`${GENERATED_START}\n\n## Fields of H5P.Test 1.2\n\n${SOURCE_FIELDS}\n\n- `)).toBe(true)
for (const field of ['`title`', '`language`', '`license`', '`authors`']) expect(SOURCE_FIELDS).toContain(field)
expect(SOURCE_FIELDS).toContain('all four required')
expect(SOURCE_FIELDS).toContain('The example is `type` and `params` alone')
expect(SOURCE_FIELDS).toContain('ask for what they have not given')
expect(SOURCE_FIELDS).toContain('For a name they skip, write the one you know them by, or "Unknown"')
expect(SOURCE_FIELDS).toContain('for a licence they skip, `U`')
expect(SOURCE_FIELDS).toContain('ask for neither')
expect(SOURCE_FIELDS).toContain('an author not given is the name you know the user by, or "Unknown"')
expect(SOURCE_FIELDS).toContain('a licence not given, or one no code below stands for, is `U`')
expect(SOURCE_FIELDS).toContain('Only the six CC BY codes take a version')
expect(SOURCE_FIELDS).toContain('`CC0 1.0` is one code, as it stands')
expect(SOURCE_FIELDS).toContain('"license": "CC BY", "licenseVersion": "4.0"')
expect(schemaMarkdown({ machineName: 'H5P.Test', majorVersion: 1, minorVersion: 2, runnable: 0 }, semantics)).not.toContain(SOURCE_FIELDS)
})
})
Expand Down
Loading
Loading