Refresh an IG’s AST cache on a runner
Dispatch an IG repository’s ig-ast-refresh.yml, which calls fhir-harness’s reusable .github/workflows/ig-ast-refresh.yml: mount the layers the IG’s index.lock.json pins, restore and judge the cache for ref, and when it is not valid (or force) run the caller’s optional pre-export overlay command and build the IG with the pinned Publisher AST exporter (the AST is recorded against the clean commit’s inputs, the overlay’s changes put back), check the new AST is valid for its commit, and seed cat/fhir-harness/fhir-ast/<package id> with ig-cache seed --push — only from a commit on the default branch with the tip’s inputs. Builds no site, writes no gh-pages, dispatches nothing.
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-index-build, ig-page-render-qa, ig-pages, ig-publisher-i18n, ig-repo-site, 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).
compiled-artefact-cache
The general pattern for caching expensive compiled artefacts (Lean .oleans, FHIR ASTs) across builds. Defines branch-based storage, validity checking, exit code protocol, safety guards, and the restore→build→contribute loop.
Source: cat-harness/skills/process/process-core/compiled-artefact-cache.md.
Also satisfied by: ig-cache.
The skill declares no I/O contract (schemas/skills/compiled-artefact-cache/{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 | repository | RepoFullName | yes | The IG repository that carries the caller (owner/repo). | string · pattern ^[A-Za-z0-9][A-Za-z0-9._-]*\\/[A-Za-z0-9][A-Za-z0-9._-]*$ · A forge repository’s full name, owner/name |
| in | ref | Branch | What to build; default main. Only a commit on the default branch with the tip’s inputs is seeded. | string · pattern ^[A-Za-z0-9][A-Za-z0-9._/-]*$ · A git branch name | |
| in | force | Flag | Rebuild even when the cache is valid. | boolean · A boolean switch — projects to a bare flag, with no value word | |
| out | result | Text | The run’s verdict before (valid, stale, cannot-tell, missing) and whether it seeded; the AST as a run artifact when it did not. | string · A short single-line human string. Not admissible as a command-line argument. |
Processes and tasks
Steps this Tool can carry out, because each names a skill it satisfies:
| process | step | lane | via skill |
|---|---|---|---|
| The cache process: restore and save every cache a run can use | Lean .oleans: restore / save | Build pipeline | compiled-artefact-cache |
| 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 |
| An IG site, built from the AST on its cache branch | Seed the cache branch | AST refresh (GitHub runner: IG Publisher with the AST exporter) | compiled-artefact-cache |
| 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:
gh workflow run ig-ast-refresh.yml --repo <owner/repo> --ref main -f ref=main [-f force=true]. - 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 | gh |
| network | yes |
When a host it reaches is refused:
| host / error | remedy |
|---|---|
github.com | none: The Tool IS a workflow dispatch on GitHub, and the build it starts runs on a GitHub runner; offline there is no arm. ig-cache restores an AST already seeded. |
| when to choose it | |
|---|---|
| when | An IG site publish refused a stale or missing AST, or the IG’s source changed on its default branch. Dispatched by a person, or by an agent the owner named for that run — never by an agent on its own. |
| limits | Needs the IG repository to carry the caller and an index.lock.json that mounts fhir-harness. A merge that changes an input during the build leaves the cache unseeded (the run says so). A pre-export command is the caller’s, in its own workflow file, never a dispatch input; a failing one exports nothing. The no-shrink gate refuses a candidate under 90% of the incumbent. |
| cost | One GitHub runner for the Publisher build: about 25 minutes cold for a ~700-resource IG, less with the restored txcache. |
What it is made of
| role | file | |
|---|---|---|
| definition | fhir-harness/tools/ig-ast-refresh/ig-ast-refresh.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-ast-refresh.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-ast-refresh.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-ast-refresh",
"title": "Refresh an IG's AST cache on a runner",
"description": "Dispatch an IG repository's `ig-ast-refresh.yml`, which calls fhir-harness's reusable `.github/workflows/ig-ast-refresh.yml`: mount the layers the IG's index.lock.json pins, restore and judge the cache for `ref`, and when it is not valid (or `force`) run the caller's optional `pre-export` overlay command and build the IG with the pinned Publisher AST exporter (the AST is recorded against the clean commit's inputs, the overlay's changes put back), check the new AST is valid for its commit, and seed `cat/fhir-harness/fhir-ast/<package id>` with `ig-cache seed --push` — only from a commit on the default branch with the tip's inputs. Builds no site, writes no gh-pages, dispatches nothing.",
"install": {
"none": true
},
"invoke": {
"shell": "gh workflow run ig-ast-refresh.yml --repo <owner/repo> --ref main -f ref=main [-f force=true]"
},
"io": {
"inputs": [
{
"name": "repository",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoFullName",
"description": "The IG repository that carries the caller (`owner/repo`).",
"required": true
},
{
"name": "ref",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Branch",
"description": "What to build; default `main`. Only a commit on the default branch with the tip's inputs is seeded.",
"required": false
},
{
"name": "force",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
"description": "Rebuild even when the cache is valid.",
"required": false
}
],
"outputs": [
{
"name": "result",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Text",
"description": "The run's verdict before (`valid`, `stale`, `cannot-tell`, `missing`) and whether it seeded; the AST as a run artifact when it did not."
}
]
},
"satisfies": [
"ig-build-pipeline",
"compiled-artefact-cache"
],
"requirements": {
"runtime": [
"gh"
],
"network": true
},
"remedies": [
{
"host": "github.com",
"none": "The Tool IS a workflow dispatch on GitHub, and the build it starts runs on a GitHub runner; offline there is no arm. `ig-cache` restores an AST already seeded."
}
],
"selection": {
"when": "An IG site publish refused a stale or missing AST, or the IG's source changed on its default branch. Dispatched by a person, or by an agent the owner named for that run — never by an agent on its own.",
"limits": "Needs the IG repository to carry the caller and an index.lock.json that mounts fhir-harness. A merge that changes an input during the build leaves the cache unseeded (the run says so). A `pre-export` command is the caller's, in its own workflow file, never a dispatch input; a failing one exports nothing. The no-shrink gate refuses a candidate under 90% of the incumbent.",
"cost": "One GitHub runner for the Publisher build: about 25 minutes cold for a ~700-resource IG, less with the restored txcache."
}
}