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
6 changes: 6 additions & 0 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,13 @@ jobs:
# --workspace-concurrency: given it, pnpm stopped on the unknown option before publishing
# anything (the first run). Without git checks: prepack writes files into the tree (types/,
# the licence, the skill), and the environment already holds the run to main.
# Each package's checks that what it depends on is on npm wait up to H5P_PUBLISH_WAIT
# minutes, one wait per script, for npm to serve a version published earlier in this run:
# npm processes a new one first, 1 to 4 minutes for most packages and 14 for the 31 MB
# library pack in release 1.7.0 (#253). A dry run publishes nothing, so there it fails at
# once, as by hand.
- run: pnpm -r publish --access public --no-git-checks $DRY_RUN
env:
NPM_CONFIG_PROVENANCE: true
DRY_RUN: ${{ inputs.dry-run && '--dry-run' || '' }}
H5P_PUBLISH_WAIT: ${{ inputs.dry-run && '0' || '30' }}
24 changes: 22 additions & 2 deletions design/build.md
Original file line number Diff line number Diff line change
Expand Up @@ -147,8 +147,28 @@ the commit its tarball came from. Each package's trusted publisher on npmjs.com
the environment, and ticks `npm publish` under Allowed actions: one created after 2026-09-03
allows only `npm stage publish` until it is ticked, and the registry refuses a publish with "403
OIDC permission denied for this action" after the token exchange has worked (the second run, on
2026-11-19). A new one expires unless a publish through it succeeds within 2 days. pnpm publishes through npm, which takes that token from 11.5.1, so the job runs
Node 24. A publish by hand, with a one-time password, still works and records no provenance.
2026-11-19). A new one expires unless a publish through it succeeds within 2 days. pnpm publishes
through npm, which takes that token from 11.5.1, so the job runs Node 24. A publish by hand, with a
one-time password, still works and records no provenance.

**A package is published only once npm serves what it depends on** (#253). npm takes a version in,
then processes it before it serves it. In release 1.7.0 that took 1 to 4 minutes for most packages
and 14 for the 31 MB library pack. The release took four runs, since each check that a dependency
is on npm failed on one published moments before. Two kinds of check now wait while npm processes:
- `scripts/published.mjs`, in the `prepublishOnly` of every published package that names another
by `workspace:` outside `devDependencies` (verify, embed, author and mcp), checks each at the
version the workspace has;
- the three checks of what a package pins, the player's pack and embed's and the author's, use its
`served()`.

Both ask again every 30 s after a 404, a server error, or a request that failed, timed out or
could not be read. The checks in one script share one wait of `H5P_PUBLISH_WAIT` minutes, which
`publish.yml` sets to 30, twice the longest seen. By hand and in a dry run it is 0, and the check
says at once what a 404 means. From npm, it does not serve the version: not published, or still
being processed. From jsDelivr, the pack there has no `parts/index.json`. After any other failure
the check stops and prints that the version could not be checked, which says nothing about whether
it is there, and to run the publish again. Each request, its body included, is cut at 30 s: one to
npm hung for over 5 minutes.

A publish of the player runs its `prepublishOnly` (a check that the pack it names is on npm,
typecheck, the unit suite and the build) so a broken tree cannot ship; the browser suite is left out because it needs an installed
Expand Down
2 changes: 2 additions & 0 deletions design/layout.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,8 @@ apps/skills/ the skills' test project: author-verify, author-playback,
front-matter
skills/ the agent skills, at the root, where `npx skills add` looks
docs/ the README's longer sections, for integrators
scripts/ published.mjs, the check before a package is published that npm serves the
workspace packages it names outside devDependencies (design/build.md)
api/, vercel.json the hosted demo's Vercel function and deployment; at the root because that
is the Vercel project's root, which only the dashboard can move
```
Expand Down
2 changes: 1 addition & 1 deletion packages/author/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@
"build:tool": "pnpm --filter @missing-elements/h5p-offline-player build:plan && node scripts/build-tool.mjs",
"sync:skill": "pnpm --filter @missing-elements/h5p-offline-player build:plan && node scripts/sync-skill.mjs",
"prepack": "node -e \"require('node:fs').copyFileSync('../../LICENSE', 'LICENSE')\" && node scripts/copy-skill.mjs && pnpm types && pnpm build:tool",
"prepublishOnly": "node -e \"if (!/^pnpm\\//.test(process.env.npm_config_user_agent || '')) { console.error('Publish with pnpm publish: npm would ship the workspace: dependency ranges as they are, and the package would not install.'); process.exit(1) }\" && node scripts/check-pack-published.mjs && pnpm typecheck && pnpm test",
"prepublishOnly": "node -e \"if (!/^pnpm\\//.test(process.env.npm_config_user_agent || '')) { console.error('Publish with pnpm publish: npm would ship the workspace: dependency ranges as they are, and the package would not install.'); process.exit(1) }\" && node ../../scripts/published.mjs && node scripts/check-pack-published.mjs && pnpm typecheck && pnpm test",
"types": "pnpm --filter @missing-elements/h5p-offline-player exec tsc -b && node -e \"require('node:fs').rmSync('types', { recursive: true, force: true })\" && tsc -p tsconfig.types.json"
},
"dependencies": {
Expand Down
21 changes: 16 additions & 5 deletions packages/author/scripts/check-pack-published.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -11,28 +11,38 @@
*/
import { readFile } from 'node:fs/promises'
import { resolve } from 'node:path'
import { served, stopUnlessAnswered, waitUntil } from '../../../scripts/published.mjs'

const packages = resolve(import.meta.dirname, '..', '..')
/** @param {string} directory */
const versionOf = async (directory) => JSON.parse(await readFile(resolve(packages, directory, 'package.json'), 'utf8')).version

// One wait for all four, in CI, where each was published moments before in the same run (#253).
const until = waitUntil()

const version = await versionOf('libraries')
const response = await fetch(`https://registry.npmjs.org/@missing-elements%2fh5p-libraries/${version}`)
const response = await served(`https://registry.npmjs.org/@missing-elements%2fh5p-libraries/${version}`, `@missing-elements/h5p-libraries@${version}`, { until })
stopUnlessAnswered(response, `@missing-elements/h5p-libraries@${version} on npm`)
if (!response.ok) {
console.error(`[library-pack] @missing-elements/h5p-libraries@${version} is not on npm (${response.status}). Publish it from packages/libraries first: the author package pins it.`)
process.exit(1)
}
const index = await fetch(`https://cdn.jsdelivr.net/npm/@missing-elements/h5p-libraries@${version}/parts/index.json`)
const index = await served(`https://cdn.jsdelivr.net/npm/@missing-elements/h5p-libraries@${version}/parts/index.json`, `h5p-libraries@${version}/parts/index.json on jsDelivr`, { until })
stopUnlessAnswered(index, `h5p-libraries@${version}/parts/index.json on jsDelivr`)
const local = await readFile(resolve(packages, 'libraries', 'parts', 'index.json'), 'utf8')
const same = index.ok && JSON.stringify((await index.json()).libraries) === JSON.stringify(JSON.parse(local).libraries)
if (!same) {
console.error(`[library-pack] @missing-elements/h5p-libraries@${version} on npm has another parts/index.json than this checkout: publish the pack from this checkout, under a new version.`)
console.error(
`[library-pack] @missing-elements/h5p-libraries@${version} on jsDelivr ${index.ok ? 'has another parts/index.json than' : 'has no parts/index.json, unlike'} this checkout: ` +
'publish the pack from this checkout, under a new version.'
)
process.exit(1)
}
console.log(`[library-pack] @missing-elements/h5p-libraries@${version} is published, with this checkout's index`)

const player = await versionOf('player')
const published = await fetch(`https://registry.npmjs.org/@missing-elements%2fh5p-offline-player/${player}`)
const published = await served(`https://registry.npmjs.org/@missing-elements%2fh5p-offline-player/${player}`, `@missing-elements/h5p-offline-player@${player}`, { until })
stopUnlessAnswered(published, `@missing-elements/h5p-offline-player@${player} on npm`)
if (!published.ok) {
console.error(`[player] @missing-elements/h5p-offline-player@${player} is not on npm (${published.status}). Publish it from packages/player first: the author package pins it, for its ./plan.`)
process.exit(1)
Expand All @@ -44,7 +54,8 @@ if (!(await published.json()).exports?.['./plan']) {
console.log(`[player] @missing-elements/h5p-offline-player@${player} is published, and exports ./plan`)

const normalize = await versionOf('normalize')
const normalizer = await fetch(`https://registry.npmjs.org/@missing-elements%2fh5p-normalize/${normalize}`)
const normalizer = await served(`https://registry.npmjs.org/@missing-elements%2fh5p-normalize/${normalize}`, `@missing-elements/h5p-normalize@${normalize}`, { until })
stopUnlessAnswered(normalizer, `@missing-elements/h5p-normalize@${normalize} on npm`)
if (!normalizer.ok) {
console.error(`[normalize] @missing-elements/h5p-normalize@${normalize} is not on npm (${normalizer.status}). Publish it from packages/normalize first: the author package depends on it, for its ./crc32.`)
process.exit(1)
Expand Down
174 changes: 174 additions & 0 deletions packages/author/tests/published.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,174 @@
import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join, resolve } from 'node:path'
import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
import { dependenciesServed, served, stopUnlessAnswered } from '../../../scripts/published.mjs'

/*
* The check, before a package is published, that npm serves what it depends on (#253): in CI it
* waits for a version published moments before in the same run, which npm processes first.
*/

let dir: string
beforeAll(async () => {
dir = await mkdtemp(join(tmpdir(), 'h5p-published-'))
vi.spyOn(console, 'log').mockImplementation(() => {})
})
afterAll(async () => {
vi.restoreAllMocks()
vi.unstubAllEnvs()
await rm(dir, { recursive: true, force: true })
})

/** A fetch that answers with the statuses given, in turn, and with the last one after them. */
function answers(...statuses: Array<number | Error>) {
const asked: string[] = []
const fetch = async (url: string) => {
asked.push(url)
const next = statuses.length > 1 ? statuses.shift()! : statuses[0]
if (next instanceof Error) throw next
return { ok: next >= 200 && next < 300, status: next, json: async () => ({}) }
}
return { fetch, asked }
}

const version = async (folder: string) => JSON.parse(await readFile(resolve(import.meta.dirname, '../..', folder, 'package.json'), 'utf8')).version as string

describe('waiting for npm to serve a version', () => {
it('asks again after a 404, a server error or a failed request, until it is served', async () => {
const { fetch, asked } = answers(404, 503, new TypeError('fetch failed'), 200)
const response = await served('https://registry.npmjs.org/x/1.0.0', 'x@1.0.0', { minutes: 1, poll: 1, fetch })
expect(response.ok).toBe(true)
expect(asked).toHaveLength(4)
})

it('asks once with no wait, as by hand and in a dry run, and takes any other refusal as the answer', async () => {
const once = answers(404, 200)
expect((await served('u', 'x', { minutes: 0, poll: 1, fetch: once.fetch })).status).toBe(404)
expect(once.asked).toHaveLength(1)
const refused = answers(403, 200)
expect((await served('u', 'x', { minutes: 1, poll: 1, fetch: refused.fetch })).status).toBe(403)
expect(refused.asked).toHaveLength(1)
})

it('cuts a request that gets no answer, and asks again within the wait', async () => {
let calls = 0
const stalling = (_url: string, init: { signal: AbortSignal }) => {
calls++
if (calls > 1) return Promise.resolve({ ok: true, status: 200, json: async () => ({}) })
return new Promise<never>((_, reject) => init.signal.addEventListener('abort', () => reject(init.signal.reason)))
}
expect((await served('u', 'x', { minutes: 0, poll: 1, timeout: 10, fetch: stalling })).status).toBe('no answer in time')
calls = 0
expect((await served('u', 'x', { minutes: 1, poll: 1, timeout: 10, fetch: stalling })).ok).toBe(true)
expect(calls).toBe(2)
})

it('reads the body of a success, and asks again when it cannot be read', async () => {
let calls = 0
const cut = async () => {
calls++
const body = calls > 1 ? { exports: { './plan': './plan.js' } } : undefined
return { ok: true, status: 200, json: async () => body ?? Promise.reject(new TypeError('terminated')) }
}
expect(await served('u', 'x', { minutes: 0, poll: 1, fetch: cut })).toMatchObject({ ok: false, status: 'terminated' })
calls = 0
const response = await served('u', 'x', { minutes: 1, poll: 1, fetch: cut })
expect(await response.json()).toEqual({ exports: { './plan': './plan.js' } })
expect(calls).toBe(2)
})

it('waits as long as H5P_PUBLISH_WAIT says, and no longer', async () => {
vi.stubEnv('H5P_PUBLISH_WAIT', '1')
const late = answers(404, 404, 200)
expect((await served('u', 'x', { poll: 1, fetch: late.fetch })).ok).toBe(true)
// The last answer once the wait has run out: the poll is longer than the minute left.
const never = answers(404)
expect((await served('u', 'x', { poll: 61_000, fetch: never.fetch })).status).toBe(404)
expect(never.asked).toHaveLength(1)
vi.unstubAllEnvs()
})
})

describe('a check whose request failed', () => {
it('goes on after a success or a 404, and stops on anything else, which says nothing about the version', () => {
const exit = vi.spyOn(process, 'exit').mockImplementation(((code?: number) => {
throw new Error(`exit ${code}`)
}) as never)
const error = vi.spyOn(console, 'error').mockImplementation(() => {})
const response = (ok: boolean, status: number | string) => ({ ok, status, json: async () => undefined })
stopUnlessAnswered(response(true, 200), 'x@1.0.0 on npm')
stopUnlessAnswered(response(false, 404), 'x@1.0.0 on npm')
for (const status of [403, 503, 'ENOTFOUND', 'no answer in time']) {
expect(() => stopUnlessAnswered(response(false, status), 'x@1.0.0 on npm')).toThrow('exit 1')
}
expect(error.mock.calls.map(([line]) => line)).toEqual([
expect.stringContaining('x@1.0.0 on npm could not be checked (403)'),
expect.stringContaining('(503)'),
expect.stringContaining('(ENOTFOUND)'),
expect.stringContaining('(no answer in time)')
])
expect(error.mock.calls[0][0]).not.toMatch(/publish it/i)
exit.mockRestore()
error.mockRestore()
})
})

describe('the dependencies a package names by workspace:', () => {
let packages: string
beforeAll(async () => {
packages = join(dir, 'packages')
const write = async (folder: string, manifest: object) => {
await mkdir(join(packages, folder), { recursive: true })
await writeFile(join(packages, folder, 'package.json'), JSON.stringify(manifest))
}
await write('a', {
name: '@scope/a',
version: '1.0.0',
dependencies: { '@scope/b': 'workspace:^', zod: '^4.0.0' },
peerDependencies: { '@scope/c': 'workspace:*' },
devDependencies: { '@scope/d': 'workspace:*' }
})
await write('b', { name: '@scope/b', version: '2.3.4' })
await write('c', { name: '@scope/c', version: '0.5.0' })
await write('d', { name: '@scope/d', version: '9.9.9' })
})

it('are each asked for at the version the workspace has, and only those', async () => {
const { fetch, asked } = answers(200, 404)
expect(await dependenciesServed(join(packages, 'a'), { minutes: 0, fetch })).toEqual([
{ name: '@scope/c', version: '0.5.0', status: 200, ok: true },
{ name: '@scope/b', version: '2.3.4', status: 404, ok: false }
])
expect(asked).toEqual(['https://registry.npmjs.org/@scope%2fc/0.5.0', 'https://registry.npmjs.org/@scope%2fb/2.3.4'])
})

it('share one wait: one that is missing leaves the next none of its own', async () => {
// A clock the requests move, 10 ms each, so the wait runs out at the fourth however busy the machine is.
let now = 1_000
const clock = vi.spyOn(Date, 'now').mockImplementation(() => now)
const asked: string[] = []
const fetch = async (url: string) => {
asked.push(url)
now += 10
return { ok: false, status: 404, json: async () => ({}) }
}
try {
const results = await dependenciesServed(join(packages, 'a'), { until: 1_035, poll: 1, fetch })
expect(results.map(({ ok }) => ok)).toEqual([false, false])
} finally {
clock.mockRestore()
}
expect(asked.filter((url) => url.includes('%2fc/'))).toHaveLength(4)
expect(asked.filter((url) => url.includes('%2fb/'))).toHaveLength(1)
})

it('for the MCP server, are the author and the verifier at their versions here', async () => {
const { fetch, asked } = answers(200)
await dependenciesServed(resolve(import.meta.dirname, '../../mcp'), { minutes: 0, fetch })
expect(asked).toEqual([
`https://registry.npmjs.org/@missing-elements%2fh5p-author/${await version('author')}`,
`https://registry.npmjs.org/@missing-elements%2fh5p-verify/${await version('verify')}`
])
})
})
2 changes: 1 addition & 1 deletion packages/embed/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@
"test": "pnpm --filter @missing-elements/h5p-offline-player build && pnpm build && vitest run",
"typecheck": "pnpm types && tsc -p tsconfig.json",
"prepack": "node -e \"require('node:fs').copyFileSync('../../LICENSE', 'LICENSE')\" && pnpm types && pnpm build",
"prepublishOnly": "node -e \"if (!/^pnpm\\//.test(process.env.npm_config_user_agent || '')) { console.error('Publish with pnpm publish: npm would ship the workspace: dependency ranges as they are, and the package would not install.'); process.exit(1) }\" && node scripts/check-published.mjs && pnpm typecheck && pnpm test",
"prepublishOnly": "node -e \"if (!/^pnpm\\//.test(process.env.npm_config_user_agent || '')) { console.error('Publish with pnpm publish: npm would ship the workspace: dependency ranges as they are, and the package would not install.'); process.exit(1) }\" && node ../../scripts/published.mjs && node scripts/check-published.mjs && pnpm typecheck && pnpm test",
"types": "pnpm --filter @missing-elements/h5p-offline-player exec tsc -b && node -e \"require('node:fs').rmSync('types', { recursive: true, force: true })\" && tsc -p tsconfig.types.json"
},
"dependencies": {
Expand Down
7 changes: 6 additions & 1 deletion packages/embed/scripts/check-published.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,10 @@
*/
import { readFile } from 'node:fs/promises'
import { resolve } from 'node:path'
import { served, stopUnlessAnswered, waitUntil } from '../../../scripts/published.mjs'

// One wait for both, in CI, where each was published moments before in the same run (#253).
const until = waitUntil()

/**
* @param {string} folder the package's folder under packages/
Expand All @@ -18,7 +22,8 @@ import { resolve } from 'node:path'
*/
async function published(folder, name, subpath, why) {
const { version } = JSON.parse(await readFile(resolve(import.meta.dirname, '..', '..', folder, 'package.json'), 'utf8'))
const response = await fetch(`https://registry.npmjs.org/${name.replaceAll('/', '%2f')}/${version}`)
const response = await served(`https://registry.npmjs.org/${name.replaceAll('/', '%2f')}/${version}`, `${name}@${version}`, { until })
stopUnlessAnswered(response, `${name}@${version} on npm`)
if (!response.ok) {
console.error(`[${folder}] ${name}@${version} is not on npm (${response.status}). Publish it from packages/${folder} first: the embed package depends on it, for its ${subpath}.`)
process.exit(1)
Expand Down
Loading