Build each IG instance’s artefact index from the IG’s cached AST

Write each IG instance’s fhir-artifact-index/ at publish, so no IG instance commits one. Indexes each instance that needs this layer and whose repository has an AST cache branch; others are skipped and named. Per instance: index.json from the AST ig-cache.sh restore lays down from the IG repository’s cache branch (authority: "cache"), menu.json from the IG’s sushi-config.yaml at the commit cloned (recording the source.of and source.ref that stage-ig-sites clones from), releases.json from the repository’s GitHub releases (a failed read writes nothing, never an empty list), package.tgz from the AST’s resources, and the JSON-LD contexts the IG publishes. The first step of process ig-docs-site-compose.

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-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).

Inputs and outputs

Each port names a shared type by IRI, so two Tools for one skill can be checked for interchangeability.

porttyperequireddescriptionconstraint
inrootRepoPathThe checkout whose IG instances are indexed. Default: the current directory’s checkout.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inonlySlugIndex one IG instance.string · pattern ^[a-z0-9][a-z0-9-]*$ · A folio slug, e.g. quantum-observable-universe
inworkRepoPathScratch directory for each IG’s clone and restored AST. Default: a fresh temporary directory.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inplanFlagWrite nothing; say which instances would be indexed, and why any is skipped.boolean · A boolean switch — projects to a bare flag, with no value word
outindexesCountIG instances indexed; each skipped instance is named with its reason, never silently absent.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:

processsteplanevia skill
An IG site, built from the AST on its cache branchRestore and judge the cached ASTSite build (agent, stage-local)ig-build-pipeline
An IG site, built from the AST on its cache branchBuild and publish the site from the ASTSite build (agent, stage-local)ig-build-pipeline
An IG site, built from the AST on its cache branchDispatch AST refreshPublication 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-docsBuild each IG’s artefact indexHost docs site build (CI runner)ig-build-pipeline
Each IG, composed into a host docs site and rendered with just-the-docsGenerate each IG instance’s artefact pagesHost docs site build (CI runner)ig-build-pipeline
Each IG, composed into a host docs site and rendered with just-the-docsClone each IG at its recorded commit and stage itHost 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/build-ig-indexes.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.

installnone
runtimebun, git
networkyes

When a host it reaches is refused:

host / errorremedy
github.comnone: It clones each IG’s repository and reads its AST cache branch and releases from GitHub; no declared Tool builds an IG’s index without it.
when to choose it
whenBuilding the docs site or a staging preview, before any page step reads an IG instance’s artefact index.
limitsNeeds the IG repository’s AST cache branch: an IG with none is skipped, and the index is only as current as that cache (ig-ast-cache).
costA shallow clone and an AST restore per IG, then seconds of indexing.

What it is made of

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-index-build.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-index-build.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-index-build",
  "title": "Build each IG instance's artefact index from the IG's cached AST",
  "description": "Write each IG instance's `fhir-artifact-index/` at publish, so no IG instance commits one. Indexes each instance that needs this layer and whose `repository` has an AST cache branch; others are skipped and named. Per instance: `index.json` from the AST `ig-cache.sh restore` lays down from the IG repository's cache branch (`authority: \"cache\"`), `menu.json` from the IG's `sushi-config.yaml` at the commit cloned (recording the `source.of` and `source.ref` that `stage-ig-sites` clones from), `releases.json` from the repository's GitHub releases (a failed read writes nothing, never an empty list), `package.tgz` from the AST's resources, and the JSON-LD contexts the IG publishes. The first step of process `ig-docs-site-compose`.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run fhir-harness/scripts/build-ig-indexes.ts"
  },
  "io": {
    "inputs": [
      {
        "name": "root",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The checkout whose IG instances are indexed. Default: the current directory's checkout.",
        "required": false
      },
      {
        "name": "only",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Slug",
        "description": "Index one IG instance.",
        "required": false
      },
      {
        "name": "work",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "Scratch directory for each IG's clone and restored AST. Default: a fresh temporary directory.",
        "required": false
      },
      {
        "name": "plan",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
        "description": "Write nothing; say which instances would be indexed, and why any is skipped.",
        "required": false,
        "arg": {
          "flag": "--plan"
        }
      }
    ],
    "outputs": [
      {
        "name": "indexes",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Count",
        "description": "IG instances indexed; each skipped instance is named with its reason, never silently absent."
      }
    ]
  },
  "satisfies": [
    "ig-build-pipeline"
  ],
  "requirements": {
    "runtime": [
      "bun",
      "git"
    ],
    "network": true
  },
  "remedies": [
    {
      "host": "github.com",
      "none": "It clones each IG's repository and reads its AST cache branch and releases from GitHub; no declared Tool builds an IG's index without it."
    }
  ],
  "selection": {
    "when": "Building the docs site or a staging preview, before any page step reads an IG instance's artefact index.",
    "limits": "Needs the IG repository's AST cache branch: an IG with none is skipped, and the index is only as current as that cache (`ig-ast-cache`).",
    "cost": "A shallow clone and an AST restore per IG, then seconds of indexing."
  }
}

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev