Build an IG repository’s own site from its cached AST, with no instance declaration
The three checkout scripts the platform’s site build runs for a repository that holds an IG and only mounts layers (index.config.json): ig-site:ast restores the AST from the IG’s cache branch (ig-cache.sh restore) and judges it, refusing a stale, cannot-tell or absent one (a stale one is accepted for a preview by default, refused with SITE_ACCEPT_STALE_AST=0, and never accepted for the root); ig-site:compose derives the artefact index from the AST (binding any IG API sidecars a layer above left in $SITE_WORK/ig-api/), writes the thin artefact pages, stages the IG’s input/ and sushi-config.yaml (menu read at build time, palette from the webpage theme of the top layer the repository mounts, edit links from its origin) and composes it at the ROOT of the host site source; ig-site:publisher-pages serves each of the AST’s resources once, as <Type>-<id>.json at the root (no ast-data/ mirror) — reduced (minified, no narrative, no ELM data, the ELM attachment pointing at the full copy) when the pages read the full resources by raw URL from the AST cache commit, and off with SITE_ROOT_RESOURCES=0 — the artefact index (or fhir-artifact-index/index.ref.json, pointing at the cache’s copy) and the sidecars (or none, read from the cache), refuses a page wearing the IG Publisher’s chrome, repairs repeated element ids and stamps folio-build.json. Never runs the Publisher and never reads its output. Compose lists the pages it puts in the site in FOLIO_SITE_UPSTREAM_PAGES, so the site build reports the IG’s own dead links rather than refusing the publish over them.
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-build-pipeline
The bare FHIR IG pipeline — FSH to SUSHI to the IG Publisher to a pages branch, with no pre-processing and no post-processing. What this layer runs, what it emits, and the list of things it deliberately refuses to know about. Owns the AST cache lifecycle: an IG site is built from the AST on its cache branch, the publish refuses a stale one, and the reusable ig-ast-refresh.yml is the one writer. Owns what an IG reader may read: contentTypes.ig.include in the repository’s index.config.json, and the legacy warning for a repository that declares none. Read before adding anything to fhir-harness, before onboarding, converting or changing the workflows of an IG repository, and before publishing an IG site.
Source: fhir-harness/skills/fhir-ig-base/ig-build-pipeline.md.
Also satisfied by: build-ig-site, fhir-core, ig-artifact-jsonld, ig-ast-refresh, ig-index-build, ig-page-render-qa, ig-pages, ig-publisher-i18n, ig-site-data, ingest-ig-menu, jsonld-vocabularies, logical-model-schemas, stage-ig-sites, strip-library-binaries, strip-library-content, terminology-index, valueset-schemas.
The skill declares no I/O contract (schemas/skills/ig-build-pipeline/{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 | ig | RepoPath | The IG checkout; the current directory by default. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | baseurl | RepoPath | compose: the site’s base path; FOLIO_SITE_BASEURL from the site build when absent. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | plantuml-jar | RepoPath | compose: render input/images-source/*.plantuml as the Publisher does. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | work | RepoPath | The site build’s work directory (SITE_WORK when absent): where ast writes its verdict, a layer above leaves the IG API sidecars, and compose the index publisher-pages serves. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| out | pages | Count | Pages composed, or AST files served. | 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 | Restore and judge the cached AST | Site build (agent, stage-local) | ig-build-pipeline |
| An IG site, built from the AST on its cache branch | Build and publish the site from the AST | Site build (agent, stage-local) | ig-build-pipeline |
| An IG site, built from the AST on its cache branch | Dispatch AST refresh | Publication manager (owner, or the agent the owner delegates to) | ig-build-pipeline |
| Each IG, composed into a host docs site and rendered with just-the-docs | Build each IG’s artefact index | Host docs site build (CI runner) | ig-build-pipeline |
| Each IG, composed into a host docs site and rendered with just-the-docs | Generate each IG instance’s artefact pages | Host docs site build (CI runner) | ig-build-pipeline |
| Each IG, composed into a host docs site and rendered with just-the-docs | Clone each IG at its recorded commit and stage it | Host docs site build (CI runner) | ig-build-pipeline |
How it is deployed and reached
- Command line. From the repository root:
bun run fhir-harness/scripts/ig-repo-site.ts. - GitHub Actions. No workflow in this checkout runs its command.
As an API: its operation in the OpenAPI document and the MCP tool list of its layer.
| install | none |
| runtime | bun, git |
| network | yes |
When a host it reaches is refused:
| host / error | remedy |
|---|---|
github.com | none: The AST IS a fetch of the IG’s cache branch; offline, an AST already restored into output-ast/ is judged and used as it is. |
| when to choose it | |
|---|---|
| when | Publishing an IG repository’s own site, as stage-local.ts does for a harnessed IG repository. |
| limits | Needs the IG’s AST cache branch (ig-ast-refresh.yml writes it) and the network to fetch it; asks the IG’s origin for its default branch for edit links (absent, pages carry none). Never runs the Publisher. |
| cost | Seconds to restore and compose; serving the AST is proportional to its size. |
What it is made of
| role | file | |
|---|---|---|
| definition | fhir-harness/tools/ig-repo-site/ig-repo-site.ts | |
| script | fhir-harness/scripts/ig-repo-site.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/ig-repo-site.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/ig-repo-site.jsonld",
"@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
"partOf": "https://litlfred.github.io/folio-assistant/fhir-harness/fhir-harness.jsonld",
"name": "ig-repo-site",
"title": "Build an IG repository's own site from its cached AST, with no instance declaration",
"description": "The three checkout scripts the platform's site build runs for a repository that holds an IG and only mounts layers (`index.config.json`): `ig-site:ast` restores the AST from the IG's cache branch (`ig-cache.sh restore`) and judges it, refusing a stale, cannot-tell or absent one (a stale one is accepted for a preview by default, refused with `SITE_ACCEPT_STALE_AST=0`, and never accepted for the root); `ig-site:compose` derives the artefact index from the AST (binding any IG API sidecars a layer above left in `$SITE_WORK/ig-api/`), writes the thin artefact pages, stages the IG's `input/` and `sushi-config.yaml` (menu read at build time, palette from the webpage theme of the top layer the repository mounts, edit links from its origin) and composes it at the ROOT of the host site source; `ig-site:publisher-pages` serves each of the AST's resources once, as `<Type>-<id>.json` at the root (no `ast-data/` mirror) — reduced (minified, no narrative, no ELM data, the ELM attachment pointing at the full copy) when the pages read the full resources by raw URL from the AST cache commit, and off with `SITE_ROOT_RESOURCES=0` — the artefact index (or `fhir-artifact-index/index.ref.json`, pointing at the cache's copy) and the sidecars (or none, read from the cache), refuses a page wearing the IG Publisher's chrome, repairs repeated element ids and stamps `folio-build.json`. Never runs the Publisher and never reads its output. Compose lists the pages it puts in the site in `FOLIO_SITE_UPSTREAM_PAGES`, so the site build reports the IG's own dead links rather than refusing the publish over them.",
"install": {
"none": true
},
"invoke": {
"shell": "bun run fhir-harness/scripts/ig-repo-site.ts"
},
"io": {
"inputs": [
{
"name": "ig",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The IG checkout; the current directory by default.",
"required": false
},
{
"name": "baseurl",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "`compose`: the site's base path; `FOLIO_SITE_BASEURL` from the site build when absent.",
"required": false
},
{
"name": "plantuml-jar",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "`compose`: render `input/images-source/*.plantuml` as the Publisher does.",
"required": false
},
{
"name": "work",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The site build's work directory (`SITE_WORK` when absent): where `ast` writes its verdict, a layer above leaves the IG API sidecars, and `compose` the index `publisher-pages` serves.",
"required": false
}
],
"outputs": [
{
"name": "pages",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Count",
"description": "Pages composed, or AST files served."
}
]
},
"satisfies": [
"ig-build-pipeline"
],
"requirements": {
"runtime": [
"bun",
"git"
],
"network": true
},
"remedies": [
{
"host": "github.com",
"none": "The AST IS a fetch of the IG's cache branch; offline, an AST already restored into `output-ast/` is judged and used as it is."
}
],
"selection": {
"when": "Publishing an IG repository's own site, as `stage-local.ts` does for a harnessed IG repository.",
"limits": "Needs the IG's AST cache branch (`ig-ast-refresh.yml` writes it) and the network to fetch it; asks the IG's origin for its default branch for edit links (absent, pages carry none). Never runs the Publisher.",
"cost": "Seconds to restore and compose; serving the AST is proportional to its size."
}
}