@vibelord/lanes 1.2.0 → 1.5.0

package/payload/lanes/holders.lock

@@ -16,3 +16,8 @@ glow 3.0.0 13e05e4b2acc18d2aee44291aefe6325b077ec321b631a0cfa780e8e3bc33f78 http
 # a locally built binary with `lanes studio-host install --from PATH [--sha256 HEX]` (also sha256-verified).
 # Template (fill from the release's two .sha256 sidecars, then uncomment):
 # throttle-rc node-<sha12> <tarball-sha256> https://github.com/bwllaming/bw-tools/releases/download/node/<sha12>/throttle-rc-x86_64-unknown-linux-gnu.tar.gz opt-in throttle-rc-x86_64-unknown-linux-gnu/throttle-rc <binary-sha256>
+# mermaid 11.17.2 (the docs page's diagrams, plan W10 W6, LNS-107): the npm tarball, 17,796,365 B, whose sha512 is the
+# registry's dist.integrity; the member is the classic-script (IIFE) build, 3,572,661 B, that web/docs.js loads with
+# this digest as its SRI. Both sha256s measured 2026-10-08. install/enable-docs.sh installs it into
+# ~/.local/share/lanes/vendor/; to bump it see docs/RUNBOOK.md "Mermaid pin".
+mermaid 11.17.2 6ad2f42c3fc26bbf9e45cbb6d11898972573ea52b33a5f4ff51952899f950ffd https://registry.npmjs.org/mermaid/-/mermaid-11.17.2.tgz opt-in package/dist/mermaid.min.js 581ed7d74bd9048d0e3a91363927d72ef22942d7722546b27f7cc29e35390eb8

package/payload/lanes/install/enable-docs.sh

@@ -0,0 +1,78 @@
+#!/bin/sh
+# The docs page's pinned Mermaid (plan W10 W6, LNS-107; docs/RUNBOOK.md "Mermaid pin"). Every server install runs it
+# right after lanes-docsd's restart and every update (--update-only) as the post-commit step `enable-docs` (W8, LNS-109:
+# host-install.sh, libexec/update.py DOCS_STEP), never fatally; it runs by hand as well. As the workspace account, never
+# root. Reads holders.lock's `mermaid` opt-in pin, downloads its npm tarball into a temporary
+# directory, checks the tarball's sha256, extracts ONLY the pinned member (never a link), checks the member's sha256,
+# and installs it as $LANES_SHARE/vendor/mermaid-<version>.min.js (0644, by rename) with the relative link
+# mermaid.min.js -> that file. Caddy serves the directory at /lanes-assets/vendor/ (web/Caddyfile); web/docs.js
+# loads the versioned name with the member digest as its SRI. Idempotent: an installed file whose digest is the pin's
+# is kept and nothing is downloaded; one that differs is replaced from a verified download. Older versions stay.
+# Exit status: 0 installed, or already present; 1 a prerequisite is missing or the download failed; 2 usage;
+# 3 refused — holders.lock has no valid mermaid pin, a digest differs, or the member is missing or not a regular file.
+# A refusal or failure installs nothing.
+set -eu
+repo=$(cd "$(dirname "$0")/.." && pwd)
+usage='usage: enable-docs.sh [--help]'
+case "$#:${1:-}" in
+    0:) ;;
+    1:-h|1:--help)
+        echo "$usage"
+        echo 'Installs the Mermaid that holders.lock pins (opt-in line `mermaid`) into ~/.local/share/lanes/vendor/'
+        echo '($LANES_SHARE/vendor), after checking the sha256 of the npm tarball and of its member.'
+        echo 'Exit status: 0 installed or already present; 1 a prerequisite is missing or the download failed;'
+        echo '2 usage; 3 refused (no valid pin, a sha256 mismatch, the member missing or not a regular file).'
+        exit 0 ;;
+    *) echo "$usage" >&2; exit 2 ;;
+esac
+[ "$(id -u)" != 0 ] || { echo 'Run as the workspace account, not root.' >&2; exit 1; }
+for command in curl tar sha256sum install mktemp; do
+    command -v "$command" >/dev/null 2>&1 || { echo "Missing prerequisite: $command (see docs/INSTALL.md)" >&2; exit 1; }
+done
+share=${LANES_SHARE:-$HOME/.local/share/lanes}
+lock=$repo/holders.lock
+refuse() { echo "enable-docs: refused, nothing was installed: $*" >&2; exit 3; }
+hex64() { [ "${#1}" -eq 64 ] && case $1 in *[!0-9a-f]*) false ;; esac; }
+
+# The pin: exactly one `mermaid` line of the 7-field opt-in grammar (holders.lock's header; studio_host.parse_lock).
+pins=$(grep -v '^[[:space:]]*#' "$lock" | awk '$1 == "mermaid"') || :
+[ -n "$pins" ] || refuse "$lock has no mermaid line"
+[ "$(printf '%s\n' "$pins" | wc -l)" -eq 1 ] || refuse "$lock pins mermaid more than once"
+# shellcheck disable=SC2086 # the line's words are the fields; no pathname expansion of them
+set -f
+set -- $pins
+set +f
+[ "$#" -eq 7 ] && [ "$5" = opt-in ] || refuse "$lock: the mermaid line is not 'name version sha256 url opt-in member sha256'"
+version=$2 sha=$3 url=$4 member=$6 member_sha=$7
+case $version in ''|*[!A-Za-z0-9._-]*) refuse "$lock: mermaid version '$version' is not a plain word" ;; esac
+hex64 "$sha" || refuse "$lock: the mermaid tarball digest is not 64 lowercase hex"
+hex64 "$member_sha" || refuse "$lock: the mermaid member digest is not 64 lowercase hex"
+case $url in https://*) ;; *) refuse "$lock: the mermaid url is not https" ;; esac
+case /$member/ in //*|*/../*|*/./*|*//*) refuse "$lock: member '$member' is not a plain relative path" ;; esac
+
+vendor=$share/vendor
+target=$vendor/mermaid-$version.min.js
+if [ -f "$target" ] && [ ! -L "$target" ] && [ "$(sha256sum "$target" | cut -d' ' -f1)" = "$member_sha" ]; then
+    ln -sfn "mermaid-$version.min.js" "$vendor/mermaid.min.js"
+    echo "ok  mermaid $version ($target)"
+    exit 0
+fi
+
+temporary=$(mktemp -d)
+trap 'rm -rf "$temporary"' EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM HUP
+curl -fsSL --retry 3 -o "$temporary/mermaid.tgz" "$url" || { echo "enable-docs: download failed: $url" >&2; exit 1; }
+actual=$(sha256sum "$temporary/mermaid.tgz" | cut -d' ' -f1)
+[ "$actual" = "$sha" ] || refuse "sha256 mismatch for the mermaid $version tarball: $actual, pinned $sha"
+mkdir "$temporary/x"
+tar -xzf "$temporary/mermaid.tgz" -C "$temporary/x" "$member" 2>/dev/null || refuse "the tarball has no $member"
+file=$temporary/x/$member
+[ -f "$file" ] && [ ! -L "$file" ] || refuse "$member in the tarball is not a regular file"
+actual=$(sha256sum "$file" | cut -d' ' -f1)
+[ "$actual" = "$member_sha" ] || refuse "sha256 mismatch for $member: $actual, pinned $member_sha"
+mkdir -p "$vendor"
+install -m 0644 "$file" "$vendor/.mermaid-$version.min.js.$$"
+mv -f "$vendor/.mermaid-$version.min.js.$$" "$target"
+ln -sfn "mermaid-$version.min.js" "$vendor/mermaid.min.js"
+echo "installed $target (sha256 $member_sha)"

package/payload/lanes/install/host-install.sh

@@ -8,13 +8,15 @@
 #                (sha256), terminfo, the catalog: a failure here leaves the installed release running exactly as it was;
 #   commit       install/services.py --install: every unit, then current.previous, then the flip of `current` (W9 U1);
 #   post-commit  libexec/update.py post-commit, from the tree just installed: daemon-reload, `lanes sync`, restart
-#                lanes-statusd, try-restart each optional service, `lanes install-container` per container,
-#                `lanes reload-views`, `lanes ensure --if-layout-changed` — each step runs whatever the one before it
-#                returned (`lanes sync` exiting 1 — a board with an error — is a warning in the record, which leaves
-#                the result `ok`; never the end of the update).
+#                lanes-statusd, try-restart each optional service (right after lanes-docsd's, install/enable-docs.sh:
+#                the docs page's pinned Mermaid, a warning when it is skipped or refused, W10 W8), `lanes
+#                install-container` per container, `lanes reload-views`, `lanes ensure --if-layout-changed` — each step
+#                runs whatever the one before it returned (`lanes sync` exiting 1 — a board with an error — is a warning
+#                in the record, which leaves the result `ok`; never the end of the update).
 # Every run is recorded in $LANES_STATE/update/last.json (DM-LANES-UPDATE-RECORD: result ok | partial | refused |
 # failed, each phase and step with its exit status) and logged in full to update/last.log; the terminal or the journal
-# gets one line per phase and step. A full install (no --update-only) prints as before and records nothing.
+# gets one line per phase and step. A full install (no --update-only) records nothing; it runs enable-docs.sh right
+# after lanes-docsd's restart, never fatally, and its summary names the Mermaid outcome.
 # One install or update at a time: every run but --check first takes the run lock $LANES_STATE/update/.lock and holds
 # it to its end (fd 9); a run that finds it held writes nothing — no log, no record — and exits 3.
 # A full install enables lanes-update.timer with the other timers (plan W9 U3, LNS-91): `lanes update --timer`, 15 min
@@ -154,6 +156,15 @@ for command in python3 curl tar sha256sum infocmp tic install systemctl docker t
     command -v "$command" >/dev/null 2>&1 || { echo "Missing prerequisite: $command (see docs/INSTALL.md)" >&2; exit 1; }
 done
 python3 -c 'import sys; sys.exit(0 if sys.version_info >= (3, 9) else "Python 3.9+ is required")'
+# --- docs store encryption at rest (W10 W5, LNS-106) ------------------------------------------------------------
+# LANES_DOCS_AGE_RECIPIENT in lanes-docsd.service's drop-in encrypts each document's docs-store copy with `age -r`
+# (default off; RUNBOOK "Docs service", encryption at rest). Set where no `age` binary is on PATH, every upload and
+# publish would fail: refused here, before anything is installed, with libexec/docs_store.py's reason.
+check_docs_age() {
+    python3 "$repo/libexec/docs_store.py" check-age || exit 1
+}
+check_docs_age
+# --- end docs store encryption at rest -------------------------------------------------------------------------
 export XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"
 if [ "$start" = 1 ]; then
     systemctl --user show-environment >/dev/null
@@ -224,6 +235,7 @@ if [ "$update_only" = 1 ]; then
         *) printf 'partial: the post-commit ended with exit %s (log %s)\n' "$status" "$log" >&3; exit 4 ;;
     esac
 fi
+mermaid="not installed (--no-start) — sh $repo/install/enable-docs.sh installs it"
 if [ "$start" = 1 ]; then
     systemctl --user daemon-reload
     # A failing sync (a board's container down, a registry it cannot read) is reported; the services still start.
@@ -236,11 +248,33 @@ if [ "$start" = 1 ]; then
     # The enrolment service (libexec/enrold.py) runs the code of THIS install: enable, then (re)start it.
     systemctl --user enable lanes-enrold.service
     systemctl --user restart lanes-enrold.service
+    # The docs service (libexec/docsd.py, W10 W3) likewise; it refuses every request until `lanes enrol mode request`
+    # pins the Serve header check.
+    systemctl --user enable lanes-docsd.service
+    systemctl --user restart lanes-docsd.service
+    # --- the docs page's pinned Mermaid (W10 W8, LNS-109) ---------------------------------------------------------
+    # install/enable-docs.sh (RUNBOOK "Mermaid pin"), never fatal: the install goes on whatever it exits, and the
+    # summary below names the outcome — 0 ok (installed, or already present with the pinned digest: no download),
+    # 1 skipped (a prerequisite or the download), 3 refused (no valid pin, a digest mismatch: nothing installed), any
+    # other status failed. An update (--update-only) runs it as a post-commit step (libexec/update.py DOCS_STEP).
+    mermaid_rc=0
+    mermaid_said=$(sh "$repo/install/enable-docs.sh" 2>&1 9>&-) || mermaid_rc=$?
+    [ -z "$mermaid_said" ] || printf '%s\n' "$mermaid_said"
+    mermaid_reason=$(printf '%s\n' "$mermaid_said" | awk 'NF { line = $0 } END { print line }')
+    [ -n "$mermaid_reason" ] || mermaid_reason="exit $mermaid_rc, no output"
+    case $mermaid_rc in
+        0) mermaid='ok' ;;
+        1) mermaid="skipped ($mermaid_reason) — diagrams show as source until sh $repo/install/enable-docs.sh succeeds" ;;
+        3) mermaid="refused ($mermaid_reason) — nothing was installed; see RUNBOOK \"Mermaid pin\"" ;;
+        *) mermaid="failed (exit $mermaid_rc: $mermaid_reason) — sh $repo/install/enable-docs.sh" ;;
+    esac
+    # --- end the docs page's pinned Mermaid -----------------------------------------------------------------------
     # A running web frontend reads the Caddyfile of the tree it was started from; an npm update stages a new tree,
     # so a reload would keep the old routes (/enrol/ included): restart it, only when it runs. Clients reconnect.
     systemctl --user try-restart lanes-mobile.service
 fi
 printf '\nServer installed from %s\n' "$repo"
+echo "Mermaid for the docs page: $mermaid"
 echo 'Configure boards in ~/.config/lanes/workspaces/; see workspaces.example/README.md.'
 echo 'Next: lanes install-container CONTAINER; lanes sync; lanes doctor'
 echo 'Web access and host cleanup/guard timers remain opt-in; see docs/INSTALL.md.'