Catalogue a library from its bibliography

Write one folio-dublin-core/v1 record and one folio-catalogue-node/v1 item per library entry that the source ledger joins to a CSL-JSON reference, into the folio’s declared catalogue directory, so gen-library-jsonld reads the title from the catalogue’s dc.title instead of falling to the PDF or the slug. The join is exact: a ledger row naming the entry’s structure.json source file, one reference id, and the same sha256 where both record one. Unjoined entries are reported and left alone. Never touches a node it did not write.

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.

filing-dublin-core

Cataloguing a source as it arrives — which facts are dcterms, which are this project’s own, and why the line is drawn by the vocabulary rather than by convenience. The bibliographic layer only; the derived layer belongs to ingestion.

Source: folio-assistant-core/skills/library/cataloguing/filing-dublin-core.md.

The skill declares no I/O contract (schemas/skills/filing-dublin-core/{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
ininstanceRepoPathyesThe folio instance’s root. It must declare a catalogue and a library directory.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inapplyFlagWrite the records and nodes, and remove this tool’s stale ones. Without it the run is a dry run.boolean · A boolean switch — projects to a bare flag, with no value word
incheckFlagWrite nothing. Exit 1 if any record or node on disk differs from what the bibliography gives.boolean · A boolean switch — projects to a bare flag, with no value word
injsonFlagPrint the plan as JSON.boolean · A boolean switch — projects to a bare flag, with no value word
inbaseUrlUrlWhere the bibliography is published. With --apply, writes catalogue.json when the catalogue directory has none; without it such a run is refused.string · format uri · An absolute http(s) URL
outcatalogueRepoPath<catalogue>/records/<slug>.dc.json and <catalogue>/nodes/item-<slug>.json per joined entry; catalogue.json when absent and --base-url is given. A summary of joined and left-alone entries goes to stdout.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.

Processes and tasks

No process step names a skill this Tool satisfies.

How it is deployed and reached

  • Command line. From the repository root: bun run folio-assistant-core/scripts/catalogue-from-references.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
networkno
when to choose it
whenA folio keeps its bibliography as CSL-JSON and a source ledger, has no catalogue, and its library titles fall to slug or the PDF.
limitsBibliographic layer only. Every publication gate is written unknown: it records what the bibliography says and decides no licence. Entries the ledger does not join to exactly one reference are left alone, never guessed.
costMilliseconds per entry. Reads the bibliography, the ledger and each entry’s structure.json; no network.

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/folio-assistant-core/tools/catalogue-from-references.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/folio-assistant-core/folio-assistant-core.context.jsonld",
  "@id": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/catalogue-from-references.jsonld",
  "@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
  "partOf": "https://litlfred.github.io/folio-assistant/folio-assistant-core/folio-assistant-core.jsonld",
  "name": "catalogue-from-references",
  "title": "Catalogue a library from its bibliography",
  "description": "Write one `folio-dublin-core/v1` record and one `folio-catalogue-node/v1` item per library entry that the source ledger joins to a CSL-JSON reference, into the folio's declared `catalogue` directory, so `gen-library-jsonld` reads the title from the catalogue's `dc.title` instead of falling to the PDF or the slug. The join is exact: a ledger row naming the entry's `structure.json` source file, one reference id, and the same sha256 where both record one. Unjoined entries are reported and left alone. Never touches a node it did not write.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run folio-assistant-core/scripts/catalogue-from-references.ts"
  },
  "io": {
    "inputs": [
      {
        "name": "instance",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The folio instance's root. It must declare a `catalogue` and a `library` directory.",
        "required": true,
        "arg": {
          "positional": 0
        }
      },
      {
        "name": "apply",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
        "description": "Write the records and nodes, and remove this tool's stale ones. Without it the run is a dry run.",
        "required": false,
        "arg": {
          "flag": "--apply"
        }
      },
      {
        "name": "check",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
        "description": "Write nothing. Exit 1 if any record or node on disk differs from what the bibliography gives.",
        "required": false,
        "arg": {
          "flag": "--check"
        }
      },
      {
        "name": "json",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
        "description": "Print the plan as JSON.",
        "required": false,
        "arg": {
          "flag": "--json"
        }
      },
      {
        "name": "baseUrl",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Url",
        "description": "Where the bibliography is published. With `--apply`, writes `catalogue.json` when the catalogue directory has none; without it such a run is refused.",
        "required": false,
        "arg": {
          "flag": "--base-url"
        }
      }
    ],
    "outputs": [
      {
        "name": "catalogue",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "`<catalogue>/records/<slug>.dc.json` and `<catalogue>/nodes/item-<slug>.json` per joined entry; `catalogue.json` when absent and `--base-url` is given. A summary of joined and left-alone entries goes to stdout."
      }
    ]
  },
  "satisfies": [
    "filing-dublin-core"
  ],
  "requirements": {
    "runtime": [
      "bun"
    ],
    "network": false
  },
  "selection": {
    "when": "A folio keeps its bibliography as CSL-JSON and a source ledger, has no catalogue, and its library titles fall to `slug` or the PDF.",
    "limits": "Bibliographic layer only. Every publication gate is written `unknown`: it records what the bibliography says and decides no licence. Entries the ledger does not join to exactly one reference are left alone, never guessed.",
    "cost": "Milliseconds per entry. Reads the bibliography, the ledger and each entry's structure.json; no network."
  }
}

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