conductor

commit 49de32bf1c57fab8607ba4ed765b5a928f1e7029
parent 185f40fdb7bd042ca3fb4a0829c06d62bac31e69
Author: finwo <finwo@pm.me>
Date:   Sun, 27 Sep 2026 00:56:50 +0200

Publish the hub short description from package.json and link every doc

Diffstat:
M
deploy/hub/conductor-worker.md
 | 
18
+++++++++++++++---
M
deploy/hub/conductor.md
 | 
20
+++++++++++++++-----
M
deploy/publish.sh
 | 
37
++++++++++++++++++++++++++-----------

3 files changed, 56 insertions(+), 19 deletions(-)
diff --git a/deploy/hub/conductor-worker.md b/deploy/hub/conductor-worker.md
@@ -114,6 +114,18 @@ simply how you say this worker's tasks may use the socket mounted above.
 
 ## Documentation
 
-- [Workers](https://github.com/finwo/conductor/blob/main/docs/worker.md)
-- [Pipelines](https://github.com/finwo/conductor/blob/main/docs/pipeline.md)
-- [Deployment](https://github.com/finwo/conductor/blob/main/docs/deployment.md)
+- [Workers](https://github.com/finwo/conductor/blob/main/docs/worker.md):
+  running a worker
+- [Pipelines](https://github.com/finwo/conductor/blob/main/docs/pipeline.md):
+  the `.conductor.yml` reference
+- [Deployment](https://github.com/finwo/conductor/blob/main/docs/deployment.md):
+  images, state, production settings
+- [Authentication](https://github.com/finwo/conductor/blob/main/docs/auth.md):
+  accounts, OIDC, who may see what
+- [HTTP API](https://github.com/finwo/conductor/blob/main/docs/api.md):
+  the JSON API and its credentials
+- [Contributing](https://github.com/finwo/conductor/blob/main/docs/contributing.md):
+  layout, testing, building
+
+Overview and quick start:
+[README](https://github.com/finwo/conductor/blob/main/README.md).
diff --git a/deploy/hub/conductor.md b/deploy/hub/conductor.md
@@ -146,8 +146,18 @@ Zero means keep forever.
 
 ## Documentation
 
-- [Deployment](https://github.com/finwo/conductor/blob/main/docs/deployment.md)
-- [Authentication](https://github.com/finwo/conductor/blob/main/docs/auth.md)
-- [Pipelines](https://github.com/finwo/conductor/blob/main/docs/pipeline.md)
-- [Workers](https://github.com/finwo/conductor/blob/main/docs/worker.md)
-- [HTTP API](https://github.com/finwo/conductor/blob/main/docs/api.md)
+- [Deployment](https://github.com/finwo/conductor/blob/main/docs/deployment.md):
+  images, state, production settings
+- [Authentication](https://github.com/finwo/conductor/blob/main/docs/auth.md):
+  accounts, OIDC, who may see what
+- [Pipelines](https://github.com/finwo/conductor/blob/main/docs/pipeline.md):
+  the `.conductor.yml` reference
+- [Workers](https://github.com/finwo/conductor/blob/main/docs/worker.md):
+  running a worker
+- [HTTP API](https://github.com/finwo/conductor/blob/main/docs/api.md):
+  the JSON API and its credentials
+- [Contributing](https://github.com/finwo/conductor/blob/main/docs/contributing.md):
+  layout, testing, building
+
+Overview and quick start:
+[README](https://github.com/finwo/conductor/blob/main/README.md).
diff --git a/deploy/publish.sh b/deploy/publish.sh
@@ -224,6 +224,7 @@ docker buildx build \
 sync_readme() {
     image=$1
     file=$2
+    summary=$3
     repo=${image#*/}
     namespace=${image%%/*}
 
@@ -247,16 +248,23 @@ sync_readme() {
     [ -n "${api}" ] || { log "could not get a hub api token, leaving the readme alone"; return 0; }
 
     # The body is json, so the markdown has to be escaped rather than
-    # pasted: it is full of quotes, backslashes and newlines.
-    payload=$(FILE="${file}" awk '
-        BEGIN { printf "{\"full_description\":\"" }
-        {
-            line = $0
-            gsub(/\\/, "\\\\", line)
-            gsub(/"/, "\\\"", line)
-            gsub(/\t/, "\\t", line)
-            printf "%s\\n", line
+    # pasted: it is full of quotes, backslashes and newlines. The summary
+    # comes through the environment so awk does the escaping, not the shell.
+    payload=$(SUMMARY="${summary}" awk '
+        function esc(s) {
+            gsub(/\\/, "\\\\", s)
+            gsub(/"/, "\\\"", s)
+            gsub(/\t/, "\\t", s)
+            return s
         }
+        BEGIN {
+            printf "{"
+            # Sending an empty one would clear what is already there.
+            summary = esc(ENVIRON["SUMMARY"])
+            if (summary != "") printf "\"description\":\"%s\",", summary
+            printf "\"full_description\":\""
+        }
+        { printf "%s\\n", esc($0) }
         END { printf "\"}" }
     ' "${file}")
 
@@ -273,8 +281,15 @@ sync_readme() {
 }
 
 log "updating the repository pages"
-sync_readme "${CONDUCTOR_IMAGE}" "${ROOT}/deploy/hub/conductor.md"
-sync_readme "${WORKER_IMAGE}" "${ROOT}/deploy/hub/conductor-worker.md"
+
+# The short description under the image name. Taken from package.json so it
+# is not maintained in a web form as well as here. Left alone if it cannot
+# be read, rather than failing a release that has already been pushed.
+PKG_SUMMARY=$(sed -n 's/.*"description"[[:space:]]*:[[:space:]]*"\(.*\)".*/\1/p' "${ROOT}/package.json" | head -n 1)
+[ -n "${PKG_SUMMARY}" ] || log "no description in package.json, leaving the short descriptions alone"
+
+sync_readme "${CONDUCTOR_IMAGE}" "${ROOT}/deploy/hub/conductor.md" "${PKG_SUMMARY}"
+sync_readme "${WORKER_IMAGE}" "${ROOT}/deploy/hub/conductor-worker.md" "Worker for conductor: pulls tasks and runs each in its own container"
 
 log "verifying the manifests"
 for image in "${CONDUCTOR_IMAGE}" "${WORKER_IMAGE}"; do