Seed the FHIR package cache from trusted sources (exact versions)
Fill ~/.fhir/packages (or --cache) for an environment that cannot reach packages.fhir.org, from trust anchors only: npm account grahamegrieve, publishers’ own published-site repositories (the seeder’s list, each fetch verified against the tarball’s own package.json), template repos found through FHIR/ig-registry’s templates.json read live each run, and a --mirror. Exact versions only (a patch wildcard resolves as the Publisher resolves it, recorded); every tarball verified; nothing computed once and kept; provenance recorded; missing versions listed, never substituted.
Skills it satisfies
A skill states the capability; this Tool is one way to exercise it. Each skill’s declared input and output contract follows, where it has one.
ig-publisher-fork
Requirements for an agent working a local experimental fork of the IG Publisher — which repositories, what the AST must carry, what must not change, and the acceptance criteria. Read before forking, and before reporting a fork’s work complete.
Source: fhir-harness/skills/fhir-ig-base/ig-publisher-fork.md.
Also satisfied by: fhir-package-mirror, ig-ast-export, ig-ast-incremental-build, ig-ast-measure-real-igs, ig-ast-plan, smart-fhir-cache-seed.
The skill declares no I/O contract (schemas/skills/ig-publisher-fork/{input,output}.schema.json).
Inputs and outputs
Each port names a shared type by IRI, so two Tools for one skill can be checked for interchangeability.
| port | type | required | description | constraint | |
|---|---|---|---|---|---|
| in | sushi-config | FilesystemPath | Seed what this IG pins: its dependencies: and the core package for its fhirVersion. | string · A filesystem path, possibly outside the repository. Not admissible as a command-line argument. | |
| in | lock | FilesystemPath | An IG’s fhir-packages.lock.json (packages: name, version, tarball https URL, integrity sha512-/sha256- and/or hex sha256). Each package it pins is installed from that URL only, after every pinned hash matches; a mismatch is refused. Its dependencies are not followed: the lock lists them. | string · A filesystem path, possibly outside the repository. Not admissible as a command-line argument. | |
| in | cache | FilesystemPath | Default ~/.fhir/packages, which SUSHI and the IG Publisher read. | string · A filesystem path, possibly outside the repository. Not admissible as a command-line argument. | |
| in | dry-run | Flag | Resolve and report; download nothing. | boolean · A boolean switch — projects to a bare flag, with no value word | |
| in | mirror | FilesystemPath | A directory or git repository of <name>#<version>.tgz filled by fhir-package-mirror. | string · A filesystem path, possibly outside the repository. Not admissible as a command-line argument. | |
| in | missing-out | FilesystemPath | Write the missing list, one name#version per line: the input fhir-package-mirror takes. | string · A filesystem path, possibly outside the repository. Not admissible as a command-line argument. | |
| out | installed | Count | integer · A non-negative count — how many of something, or how many to show. Zero is a real answer. | ||
| out | missing | Count | Exit 1 when any is missing. Each is listed with why: not on npm, a different version only, an untrusted maintainer, or not an exact version. | integer · A non-negative count — how many of something, or how many to show. Zero is a real answer. |
Processes and tasks
Steps this Tool can carry out, because each names a skill it satisfies:
| process | step | lane | via skill |
|---|---|---|---|
| An IG site, built from the AST on its cache branch | Build the IG with the AST exporter | AST refresh (GitHub runner: IG Publisher with the AST exporter) | ig-publisher-fork |
How it is deployed and reached
- Command line. From the repository root:
bun run fhir-harness/scripts/fhir-cache-seed-npm.ts [--cache <dir>] [--sushi-config <file>] [--mirror <dir|git-url>] [--template-repo <name=owner/repo>] [--site-repo <prefix=owner/repo[@branch]>] [--lock <file>] [--missing-out <file>] [--dry-run] [name#version ...]. - GitHub Actions. 1 workflow line(s) run its command:
| workflow | line | |
|---|---|---|
fhir-harness/.github/workflows/ig-ast-refresh.yml | 317 | bun run fhir-harness/scripts/fhir-cache-seed-npm.ts --cache "$HOME/.fhir/packages" --lock "$PACKAGE_LOCK" \\ |
As an API: its operation in the OpenAPI document and the MCP tool list of its layer.
| install | none |
| runtime | bun, npm, git |
| network | yes |
When a host it reaches is refused:
| host / error | remedy |
|---|---|
registry.npmjs.org | none: npm is a trust anchor this Tool reads. The other route is an owner mirror (--mirror), filled by fhir-package-mirror on a machine that reaches packages.fhir.org. |
github.com | none: Publishers’ site and template repositories are read from GitHub; with it refused, only npm and --mirror remain. |
| when to choose it | |
|---|---|
| when | packages.fhir.org is unreachable and registry.npmjs.org is not. |
| limits | Pinned HL7 versions are often not on npm and need --mirror. A template FHIR/ig-registry does not list is named with --template-repo. A partly seeded cache does not make a faithful build of an IG whose pins it misses. |
| cost | One download per package; the core packages are tens of megabytes. |
What it is made of
| role | file | |
|---|---|---|
| definition | fhir-harness/tools/fhir-cache-seed-npm/fhir-cache-seed-npm.ts | |
| script | fhir-harness/scripts/fhir-cache-seed-npm.ts |
Linked data
The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/fhir-harness/tools/fhir-cache-seed-npm.jsonld, partOf its layer’s document. The node below is the definition this page was drawn from, and is embedded in the page as application/ld+json.
{
"@context": "https://litlfred.github.io/folio-assistant/fhir-harness/fhir-harness.context.jsonld",
"@id": "https://litlfred.github.io/folio-assistant/fhir-harness/tools/fhir-cache-seed-npm.jsonld",
"@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
"partOf": "https://litlfred.github.io/folio-assistant/fhir-harness/fhir-harness.jsonld",
"name": "fhir-cache-seed-npm",
"title": "Seed the FHIR package cache from trusted sources (exact versions)",
"description": "Fill `~/.fhir/packages` (or `--cache`) for an environment that cannot reach packages.fhir.org, from trust anchors only: npm account `grahamegrieve`, publishers' own published-site repositories (the seeder's list, each fetch verified against the tarball's own package.json), template repos found through FHIR/ig-registry's templates.json read live each run, and a `--mirror`. Exact versions only (a patch wildcard resolves as the Publisher resolves it, recorded); every tarball verified; nothing computed once and kept; provenance recorded; missing versions listed, never substituted.",
"install": {
"none": true
},
"invoke": {
"shell": "bun run fhir-harness/scripts/fhir-cache-seed-npm.ts [--cache <dir>] [--sushi-config <file>] [--mirror <dir|git-url>] [--template-repo <name=owner/repo>] [--site-repo <prefix=owner/repo[@branch]>] [--lock <file>] [--missing-out <file>] [--dry-run] [name#version ...]"
},
"io": {
"inputs": [
{
"name": "sushi-config",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
"description": "Seed what this IG pins: its `dependencies:` and the core package for its `fhirVersion`.",
"required": false
},
{
"name": "lock",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
"description": "An IG's `fhir-packages.lock.json` (`packages`: name, version, `tarball` https URL, `integrity` sha512-/sha256- and/or hex `sha256`). Each package it pins is installed from that URL only, after every pinned hash matches; a mismatch is refused. Its dependencies are not followed: the lock lists them.",
"required": false
},
{
"name": "cache",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
"description": "Default `~/.fhir/packages`, which SUSHI and the IG Publisher read.",
"required": false
},
{
"name": "dry-run",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
"description": "Resolve and report; download nothing.",
"required": false
},
{
"name": "mirror",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
"description": "A directory or git repository of `<name>#<version>.tgz` filled by `fhir-package-mirror`.",
"required": false
},
{
"name": "missing-out",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
"description": "Write the missing list, one `name#version` per line: the input `fhir-package-mirror` takes.",
"required": false
}
],
"outputs": [
{
"name": "installed",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Count"
},
{
"name": "missing",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Count",
"description": "Exit 1 when any is missing. Each is listed with why: not on npm, a different version only, an untrusted maintainer, or not an exact version."
}
]
},
"satisfies": [
"ig-publisher-fork"
],
"requirements": {
"runtime": [
"bun",
"npm",
"git"
],
"network": true
},
"remedies": [
{
"host": "registry.npmjs.org",
"none": "npm is a trust anchor this Tool reads. The other route is an owner mirror (`--mirror`), filled by `fhir-package-mirror` on a machine that reaches packages.fhir.org."
},
{
"host": "github.com",
"none": "Publishers' site and template repositories are read from GitHub; with it refused, only npm and `--mirror` remain."
}
],
"selection": {
"when": "packages.fhir.org is unreachable and registry.npmjs.org is not.",
"limits": "Pinned HL7 versions are often not on npm and need `--mirror`. A template FHIR/ig-registry does not list is named with `--template-repo`. A partly seeded cache does not make a faithful build of an IG whose pins it misses.",
"cost": "One download per package; the core packages are tens of megabytes."
}
}