linkml-scaffold.sh

Overview

scripts/linkml-scaffold.sh is the driver and scripts/linkml-scaffold.py its Python half. Nothing in it is a judgement: the facts come in as environment variables that the skill’s Step 0 resolved from real sources.

The driver runs the Python half through uv run first, which reads the half’s own # /// script header and so passes over a python3 older than 3.8, such as RHEL 8’s 3.6. Without uv, it uses python3, and python as the last resort, each only when it is 3.8 or later. The half needs only the standard library, so its header names no package for a mirror to refuse. With none of these, the driver exits 2.

linkml-scaffold.sh [--dry-run] [--host DIR] [--mode plain|lokf|auto]
                   [--gitignored] [--adopt SCHEMA | --dummy]
                   [--pointers-only] [--repair PATH]

The facts are PROJ_NAME, PROJ_SLUG, PROJ_DESC, GITHUB_ORG, REPO_URL, FULL_NAME, EMAIL, LICENSE_ID, SCHEMA_ID and DOCS_URL, with BASE_IRI read from .lokf/knowledge/index.md when it is absent. With --adopt, PROJ_SLUG and SCHEMA_ID come from the schema file itself.

What it does, in order

1. Refuses a sidecar in .linkml/, a schema project at the root or one directory down, and a .linkml/ holding project files without answers. It refuses a schema the host already holds unless --adopt or --dummy says what to do. It installs around configuration files alone in .linkml/.
2. Checks the facts against the template’s own rules. An adopted schema’s id is exempt, since it was chosen before.
3. In KTL mode, pins .lokf/lokf.yaml out of the installed toolkit.
4. Verifies the pin: the tag must name the commit the driver records before the template runs with --trust.
5. Pre-seeds the files the skill owns into a staging directory beside .linkml/, substituting facts as literal text through Python’s str.replace, never sed.
6. Runs copier for everything else, into the same staging directory.
7. Neutralises the root assumptions that remain. With --adopt, it points config.public.mk’s LINKML_SCHEMA_SOURCE_DIR at the schema’s folder, relative to .linkml/. It renames config.yaml to generators.yaml and names it in config.public.mk, unless the host already keeps a .linkml/generators.yaml.
8. Moves the staged files into .linkml/, around whatever is already there. A name both hold is a clash: nothing moves, and the run ends with exit 3.
9. In KTL mode, edits .lokf/justfile to name the schema.
10. Adds the root pointers, then prints the hand-off facts.

Every line it prints starts with scaffold:, handoff: or next:. It never removes anything but its own staging directory, so a failed run leaves .linkml/ as it was.

--repair generators.yaml moves a finished project’s config.yaml to .linkml/generators.yaml: the sidecar’s, or a root project’s into .linkml/. It changes the one line of config.public.mk that names the file, and moves nothing when it cannot finish. After the move, copier update leaves the file alone, so the template’s later changes to its settings no longer arrive.

Exit codes

• 0: done.
• 2: a usage error, a bad fact or a missing tool.
• 3: refused, because a project, a schema or a file already there stands in the way.
• 4: copier failed.
• 5: an overlay or a pointer failed.

The driver holds the one template pin, LINKML_TEMPLATE_REF and LINKML_TEMPLATE_SHA.