# LOKF knowledge-bundle recipes for KTL Curator.
#
# The `lokf` toolkit is a Python sidecar (see pyproject.toml); these recipes
# drive it against the knowledge/ bundle. Run `just --list` to see them.

bundle := "knowledge"

# This line names the domain vocabulary: a LinkML file that imports the
# pinned lokf.yaml and adds the host's classes
# (ktl-librarian/references/domain-vocabulary.md). Give its path from this
# folder, as "schema/<slug>.yaml", beside lokf.yaml and each file it imports.
# Copy a LinkML project's schema there first, through `lokf adapt` where it
# must be. Leave it empty for the core vocabulary alone.
#
# The validate, convert and serve recipes pass it as --schema (lokf 0.9.0 or
# later), and the workflows, the release and the website read only this line.
# A lokf command given no --schema reads `[tool.lokf] schema` in
# pyproject.toml instead: set that to the same path or leave it out. The
# preflight warns when the two differ.
schema := ""
_schema := if schema == "" { "" } else { "--schema " + quote(schema) }

# List available recipes
default:
    @just --list

# Install the lokf sidecar toolkit into a local .venv
lokf-install:
    uv sync

# Assemble and validate the knowledge bundle against the LOKF schema (and the domain vocabulary `schema` names)
lokf-validate:
    uv run lokf validate {{ _schema }} {{ bundle }}

# Project the bundle (or a concept file) to RDF (Turtle) on stdout
lokf-convert FILE=bundle:
    uv run lokf convert {{ _schema }} --format ttl {{ FILE }}

# Serve the bundle locally: SPARQL endpoint + live graph explorer
lokf-serve:
    uv run lokf serve {{ _schema }} {{ bundle }}

# Schema validation alone reads a fabricated or stale IRI as a valid string.
# --check-refs takes the relation slots from the schema, so it covers reified
# `relations` entries and a domain vocabulary's slots too. It leaves a target
# outside base_iri alone, since `source` and `definedBy` take an external
# resource. --check-excerpts (lokf 0.9.0 or later) finds each
# `sources[].excerpt` in its local file, and counts an excerpt on a URL
# without fetching it.
#
# Audit: every typed-relation target must resolve to a concept, and every local excerpt must match its file
lokf-check-refs:
    uv run lokf validate {{ _schema }} --check-refs --check-excerpts {{ bundle }}

# The knowledge_bundle doorway shows the bundle under a visible name at the
# host root, for tools that hide dot-folders: folder pickers, file managers
# and the "Open folder as vault" of Obsidian. Git carries the link and a sync
# service such as OneDrive does not, so a machine may need it recreated. This
# recipe is POSIX only. On Windows, run mklink /J knowledge_bundle .lokf\knowledge

# Create (or recreate) the knowledge_bundle -> .lokf/knowledge doorway link at the host root
lokf-link:
    #!/usr/bin/env bash
    set -euo pipefail
    if [ -L knowledge ]; then echo "knowledge is itself a link onto $(readlink knowledge) - that folder is already the visible name; nothing to do"; exit 0; fi
    if [ ! -d knowledge ]; then echo "no knowledge/ folder here to link to" >&2; exit 1; fi
    if [ -L ../knowledge_bundle ]; then
      if [ "$(readlink ../knowledge_bundle)" = ".lokf/knowledge" ]; then echo "knowledge_bundle already present - nothing to link"; exit 0; fi
      echo "../knowledge_bundle is a link elsewhere ($(readlink ../knowledge_bundle)) - remove it and re-run" >&2; exit 1
    fi
    if [ -e ../knowledge_bundle ]; then echo "../knowledge_bundle exists and is not a link - leaving it alone" >&2; exit 1; fi
    ln -s .lokf/knowledge ../knowledge_bundle && echo "linked knowledge_bundle -> .lokf/knowledge"
