okf-catalog 0.1.0

package/recipes/publish/pack.sh

@@ -0,0 +1,60 @@
+#!/bin/sh
+# Checks the source bundle with the OKF checkers, packs it with okf-catalog, checks the result, and prints the
+# commit it recorded. Nothing is pushed here: push.sh does that, in a job that holds the write token (D46).
+#
+# usage: pack.sh --config <path> --source <bundle folder> --out <folder> [--commit <sha>]
+# needs: sh, git, okf-catalog (or OKF_CATALOG_BIN, such as "node dist/cli.js"), and the checkers you enable on PATH.
+# settings: OKFLINT_MANIFEST (okflint's manifest file; unset leaves okflint out), OKF_SCHEMA (1, strict, or unset).
+set -eu
+
+usage() {
+  echo "usage: pack.sh --config <path> --source <bundle folder> --out <folder> [--commit <sha>]" >&2
+  exit 2
+}
+
+COMMIT=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --config) CONFIG=$2; shift 2 ;;
+    --source) SOURCE=$2; shift 2 ;;
+    --out) OUT=$2; shift 2 ;;
+    --commit) COMMIT=$2; shift 2 ;;
+    *) usage ;;
+  esac
+done
+[ -n "${CONFIG:-}" ] && [ -n "${SOURCE:-}" ] && [ -n "${OUT:-}" ] || usage
+
+OKF_CATALOG_BIN="${OKF_CATALOG_BIN:-okf-catalog}"
+if [ -z "$COMMIT" ]; then
+  COMMIT=$(git -C "$SOURCE" rev-parse HEAD)
+fi
+
+# The checkers are the company's gates, run when their setting is given: OKFLINT_MANIFEST names okflint's own
+# manifest file (okflint 0.5.0 exits 2 without one); OKF_SCHEMA is 1, or strict to fail on warnings (okf-schema
+# 0.12.0 fails the specification's own example on its log.md, so a company decides). They run on the source,
+# then the pack, then on what will be published.
+case "${OKF_SCHEMA:-}" in
+  ""|1|strict) ;;
+  *) echo "OKF_SCHEMA must be unset, 1 or strict" >&2; exit 2 ;;
+esac
+if [ -n "${OKFLINT_MANIFEST:-}" ]; then
+  okflint validate --manifest "$OKFLINT_MANIFEST" "$SOURCE" >&2
+fi
+if [ "${OKF_SCHEMA:-}" = 1 ]; then
+  okf-schema validate --path "$SOURCE" >&2
+elif [ "${OKF_SCHEMA:-}" = strict ]; then
+  okf-schema validate --path "$SOURCE" --strict >&2
+fi
+# OKF_CATALOG_BIN may carry arguments ("node dist/cli.js"), so it is split on purpose.
+# shellcheck disable=SC2086
+$OKF_CATALOG_BIN pack --config "$CONFIG" --from "$SOURCE" --out "$OUT" --commit "$COMMIT" >&2
+if [ -n "${OKFLINT_MANIFEST:-}" ]; then
+  okflint validate --manifest "$OKFLINT_MANIFEST" "$OUT" >&2
+fi
+if [ "${OKF_SCHEMA:-}" = 1 ]; then
+  okf-schema validate --path "$OUT" >&2
+elif [ "${OKF_SCHEMA:-}" = strict ]; then
+  okf-schema validate --path "$OUT" --strict >&2
+fi
+
+echo "$COMMIT"

package/recipes/publish/publish.yml

@@ -0,0 +1,88 @@
+# Copy this file into the repository that holds the company's bundle, as .github/workflows/publish.yml, and set the
+# four values under `env`. It runs on a push to the source branch, never on the published branch; a read-only job
+# checks and packs, and a second job with the write token runs git alone. See README.md beside this file.
+name: publish knowledge bundle
+
+on:
+  push:
+    branches:
+      - main # the source branch; never the published branch
+
+permissions: {}
+
+concurrency:
+  group: okf-catalog-publish
+  cancel-in-progress: false
+
+env:
+  BUNDLE_PATH: kb
+  CONFIG_PATH: okf-catalog.yaml
+  PUBLISHED_BRANCH: published
+  # The checkers are your gates: okflint needs its own manifest file (unset leaves it out); OKF_SCHEMA is 1, or
+  # strict to fail on warnings, or empty to leave okf-schema out.
+  OKFLINT_MANIFEST: okf-base.yaml
+  OKF_SCHEMA: "1"
+  # The server package from a pinned commit of its repository, never a bare package name (the npm name is unclaimed).
+  OKF_CATALOG_SOURCE: "github:drathm/okf-catalog#0000000000000000000000000000000000000000"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      commit: ${{ steps.pack.outputs.commit }}
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        with:
+          node-version: "22"
+      - uses: astral-sh/setup-uv@0c5e2b8115b80b4c7c5ddf6ffdd634974642d182 # v5.4.1
+        with:
+          version: "0.11.19"
+      - name: install the server package from its pinned source, then the checkers from its lock
+        run: |
+          # The server package carries the recipe's scripts and the hash-pinned checker lock; this file is the
+          # only thing a company copies. The package builds itself on install (its `prepare` script).
+          NODE_LLAMA_CPP_SKIP_DOWNLOAD=1 npm install --global "$OKF_CATALOG_SOURCE"
+          RECIPE="$(npm root -g)/okf-catalog/recipes/publish"
+          echo "RECIPE=$RECIPE" >> "$GITHUB_ENV"
+          uv venv --python 3.12 "$RUNNER_TEMP/checkers"
+          uv pip install --python "$RUNNER_TEMP/checkers/bin/python" --require-hashes -r "$RECIPE/checkers.lock"
+          echo "$RUNNER_TEMP/checkers/bin" >> "$GITHUB_PATH"
+      - name: check, pack, check
+        id: pack
+        run: |
+          commit=$(sh "$RECIPE/pack.sh" --config "$CONFIG_PATH" --source "$BUNDLE_PATH" --out "$RUNNER_TEMP/bundle" --commit "$GITHUB_SHA")
+          echo "commit=$commit" >> "$GITHUB_OUTPUT"
+          # One archive, so file names the artifact store would refuse (quotes, colons, stars) travel untouched;
+          # push.sh rides along, so the publish job installs nothing and runs git alone.
+          cp "$RECIPE/push.sh" "$RUNNER_TEMP/push.sh"
+          tar -C "$RUNNER_TEMP" -cf "$RUNNER_TEMP/bundle.tar" bundle push.sh
+      - uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # v4.4.3
+        with:
+          name: bundle
+          path: ${{ runner.temp }}/bundle.tar
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 1
+      - uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        with:
+          name: bundle
+          path: ${{ runner.temp }}
+      - name: commit the bundle onto the published branch and push
+        env:
+          SOURCE_COMMIT: ${{ needs.build.outputs.commit }}
+        run: |
+          tar -C "$RUNNER_TEMP" -xf "$RUNNER_TEMP/bundle.tar"
+          sh "$RUNNER_TEMP/push.sh" --repo "$GITHUB_WORKSPACE" --bundle "$RUNNER_TEMP/bundle" --commit "$SOURCE_COMMIT" --branch "$PUBLISHED_BRANCH"

package/recipes/publish/push.sh

@@ -0,0 +1,63 @@
+#!/bin/sh
+# Commits a packed bundle onto the published branch, on top of its current tip, and pushes it without force. It
+# works through a checkout whose remote already carries the credentials (in GitHub Actions, the checkout step's),
+# so no credential ever appears in a URL here, and it never touches that checkout's index or working tree: the
+# bundle is staged into an index of its own and written as a tree with git's plumbing.
+#
+# usage: push.sh --repo <checkout> --bundle <packed folder> --commit <sha> [--remote origin] [--branch published]
+set -eu
+
+usage() {
+  echo "usage: push.sh --repo <checkout> --bundle <packed folder> --commit <sha> [--remote origin] [--branch published]" >&2
+  exit 2
+}
+
+REMOTE=origin
+BRANCH=published
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --repo) REPO=$2; shift 2 ;;
+    --bundle) BUNDLE=$2; shift 2 ;;
+    --commit) COMMIT=$2; shift 2 ;;
+    --remote) REMOTE=$2; shift 2 ;;
+    --branch) BRANCH=$2; shift 2 ;;
+    *) usage ;;
+  esac
+done
+[ -n "${REPO:-}" ] && [ -n "${BUNDLE:-}" ] && [ -n "${COMMIT:-}" ] || usage
+BUNDLE=$(cd "$BUNDLE" && pwd)
+
+GIT_DIR=$(git -C "$REPO" rev-parse --absolute-git-dir)
+export GIT_DIR
+export GIT_AUTHOR_NAME="okf-catalog publish" GIT_AUTHOR_EMAIL="okf-catalog-publish@invalid"
+export GIT_COMMITTER_NAME="okf-catalog publish" GIT_COMMITTER_EMAIL="okf-catalog-publish@invalid"
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+GIT_INDEX_FILE="$TMP/index"
+export GIT_INDEX_FILE
+
+# The new commit's parent is the branch's current tip, so a race is rejected by the remote and the next run follows.
+PARENT=""
+if git fetch -q "$REMOTE" "refs/heads/$BRANCH" 2>/dev/null; then
+  PARENT=$(git rev-parse --verify -q "FETCH_HEAD^{commit}")
+fi
+
+# Stage every file of the packed folder into the private index as a plain blob, with no filter, no line-ending
+# rule and no ignore rule (git add would apply the person's configuration and change the bytes pack hashed).
+(cd "$BUNDLE" && find . -type f | sed 's|^\./||' | LC_ALL=C sort) > "$TMP/files"
+while IFS= read -r file; do
+  blob=$(git hash-object -w --no-filters -- "$BUNDLE/$file")
+  git update-index --add --cacheinfo "100644,$blob,$file"
+done < "$TMP/files"
+TREE=$(git write-tree)
+
+# The message carries the source commit through a variable, never text from an event.
+MESSAGE="publish $COMMIT"
+if [ -n "$PARENT" ]; then
+  NEW=$(printf '%s\n' "$MESSAGE" | git commit-tree "$TREE" -p "$PARENT")
+else
+  NEW=$(printf '%s\n' "$MESSAGE" | git commit-tree "$TREE")
+fi
+git push -q "$REMOTE" "$NEW:refs/heads/$BRANCH"
+echo "published $COMMIT to $BRANCH as $NEW"