@openmixer/plugin-qualify 0.14.1 → 0.16.0

package/src/whole-file.ts

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * A file written whole or not at all: the bytes go to `<path>.new` beside it, are flushed to the disk, and the name is
+ * moved over the old file, then the directory is flushed so the rename itself survives a power cut. A reader of
+ * `path`, plugin-hostd at start among them, sees the old file or the whole new one, never a half.
+ */
+import { closeSync, fsyncSync, mkdirSync, openSync, renameSync, writeSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** The bytes one write call takes; a large file goes out in pieces of this size. */
+const PIECE_BYTES = 1 << 16;
+
+/** The name the new bytes are written under before the rename. */
+export const pendingPath = (path: string): string => `${path}.new`;
+
+export function writeFileWhole(path: string, content: string | Uint8Array): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const bytes = typeof content === "string" ? Buffer.from(content, "utf8") : content;
+  const pending = pendingPath(path);
+  const fd = openSync(pending, "w", 0o644);
+  try {
+    for (let at = 0; at < bytes.length; at += PIECE_BYTES) writeSync(fd, bytes, at, Math.min(PIECE_BYTES, bytes.length - at));
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(pending, path);
+  const dir = openSync(dirname(path), "r");
+  try {
+    fsyncSync(dir);
+  } finally {
+    closeSync(dir);
+  }
+}

package/tools/_declarations.py

@@ -25,8 +25,10 @@ DESCRIPTOR_DIR_SYSTEM = "/var/lib/omx/descriptors"
 DESCRIPTOR_HASH_PREFIX = 12
 DESCRIPTOR_SCHEMA_ENV = "OMX_CONTRACT_SCHEMA"
 DESCRIPTOR_SCHEMA_INSTALLED = "/usr/share/omx-contract/omx-contract.schema.json"
-DESCRIPTOR_SCHEMA_FLOOR = ">= 3.0.0"
+DESCRIPTOR_SCHEMA_FLOOR = ">= 3.4.0"
+DESCRIPTOR_ID_HASH_PREFIX = 8
 DESCRIPTOR_CODE_SCHEMA = "contract.file.invalid"
 DESCRIPTOR_CODE_SCHEMA_MISSING = "qualify.descriptor.schema-missing"
+DESCRIPTOR_CODE_SCHEMA_FLOOR = "qualify.descriptor.schema-floor"
 DESCRIPTOR_CODE_BINARY_UNHASHED = "qualify.descriptor.binary-unhashed"
 DESCRIPTOR_CODE_DIR_UNWRITABLE = "qualify.descriptor.dir-unwritable"

package/tools/ai-trace-commit-check.sh

@@ -1,17 +1,17 @@
 #!/bin/bash
 # SPDX-License-Identifier: GPL-3.0-or-later
-# Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
-#
 # ai-trace-commit-check.sh: fail when a commit message carries an AI-attribution line.
 #
 #   ai-trace-commit-check.sh <range>          every commit in the range (e.g. origin/main..HEAD)
 #   ai-trace-commit-check.sh --msg-file FILE  one message (the commit-msg hook; # lines are git comments, skipped)
-#   ai-trace-commit-check.sh --text-file FILE any text, every line judged (pull request titles and bodies)
+#   ai-trace-commit-check.sh --text-file FILE any text, every line judged (PR titles and bodies)
 #   ai-trace-commit-check.sh --selftest       fixtures plus a sabotage run
 #
 # Exit 0 clean, 1 a hit (each commit and offending line is named), 2 a range, file or pattern list that cannot be read
-# (any crash is 2). A caller refuses on 2: a checker that cannot judge is never a pass.
-# The patterns are ai-trace-patterns.json beside this script; AI_TRACE_PATTERNS names another JSON (self-tests).
+# (any crash is 2). Callers refuse on 2: a checker that cannot judge is never a pass.
+# The patterns are ai-trace-patterns.json beside this script, the same list ai-trace-sweep.sh strips
+# issue and PR text with, and the one list every door reads: merge-pr.sh, integrate-check.sh, pr-from-devel.sh
+# (ops/tools/tests/ai-trace-one-list.t.sh refuses a second list). AI_TRACE_PATTERNS names another JSON (self-tests). Repos that cannot see the ops tree carry a copy of both files.
 set -euo pipefail
 export AI_TRACE_SELF="${BASH_SOURCE[0]}"
 exec python3 -I - "$@" <<'PY'
@@ -51,16 +51,22 @@ def git(*a):
 
 
 def selftest():
-    # built from fragments: this file must not itself carry an attribution line
-    co, by, ai = "Co-Authored-", "By: ", "Cl" + "aude"
-    sess = "Cl" + "aude-Session: https://cl" + "aude.ai/code/session_01"
     fx = {
-        "co-authored-by": f"Fix x\n\n{co}{by}{ai} Opus <noreply@anthro" + "pic.com>\n",
-        "claude-session": f"Fix x\n\n{sess}\n",
-        "generated-footer": f"Fix x\n\n\U0001F916 Generated with [{ai} Code](https://{ai.lower()}.com/{ai.lower()}-code)\n",
-        "claude.ai/code": f"Fix x\n\nsee https://{ai.lower()}.ai/code/session_9\n",
+        "co-authored-by": "Fix x\n\nCo-Authored-By: Claude Opus <noreply@anthropic.com>\n",
+        "claude-session": "Fix x\n\nClaude-Session: https://claude.ai/code/session_01\n",
+        "generated-footer": "Fix x\n\n\U0001F916 Generated with [Claude Code](https://claude.com/claude-code)\n",
+        "claude.ai/code": "Fix x\n\nsee https://claude.ai/code/session_9\n",
+        # the shapes the omx-dsp#155 review saw pass
+        "assisted-by": "Fix x\n\nAssisted-by: Claude\n",
+        "made-with": "Fix x\n\nMade with Claude Code\n",
+        "generated-with-claude": "Fix x\n\nGenerated with Claude\n",
+        "generated-by-trailer": "Fix x\n\nGenerated-by: Claude\n",
+        "co-author-model": "Fix x\n\nCo-authored-by: Opus 5.5 <x@example.invalid>\n",
+        "co-author-github-copilot": "Fix x\n\nCo-authored-by: GitHub Copilot <copilot@github.com>\n",
     }
-    clean = f"Fix x\n\nGenerated by the build; mentions a hidden directory and a {co}{by}Pau line.\n"
+    clean = ("Fix x\n\nGenerated by the build; mentions .claude/ and a Co-Authored-By: Pau line.\n"
+             "Assisted-by: Pau Aliagas\nMade with care; generated with tools/rules-index-gen.sh\n"
+             "A review quoted 'Assisted-by: Claude' and 'Co-authored-by: Opus 5.5 <x>' as shapes that passed.\n")
     def run(markers):
         bad = [k for k, v in fx.items() if not hits(v, markers)]
         if hits(clean, markers):
@@ -71,7 +77,13 @@ def selftest():
     print("selftest:", "GREEN" if not first else f"RED {first}")
     sab = run([x for x in m if x[0] not in ("co-authored-by", "ai-co-author", "anthropic-noreply", "claude-session")])
     print("sabotage (the co-author, email and session patterns removed):", "RED as expected" if sab else "still GREEN: blind")
-    return 0 if not first and sab else 1
+    # each #152 shape is seen by a pattern of its own family, not by luck
+    new = ["assisted-by", "made-with", "generated-with-claude", "generated-by-trailer", "co-author-model", "co-author-github-copilot"]
+    sab2 = run([x for x in m if x[0] not in ("ai-assisted-by", "generated-footer", "ai-co-author-model")])
+    blind = [k for k in new if k not in sab2]
+    print("sabotage (the assisted-by, generated and model co-author patterns removed):",
+          "RED as expected" if not blind else f"still GREEN for {blind}: blind")
+    return 0 if not first and sab and not blind else 1
 
 
 def main(a):

package/tools/ai-trace-patterns.json

@@ -1,5 +1,5 @@
 {
- "$comment": "SPDX-License-Identifier: GPL-3.0-or-later. The AI-attribution patterns (Python re, flags IGNORECASE|MULTILINE) read by ai-trace-commit-check.sh. Edit here only.",
+ "$comment": "Single source of the AI-trace patterns (Python re, flags IGNORECASE|MULTILINE). Read by ai-trace-sweep.sh and ai-trace-commit-check.sh. Edit here only. A trailer-shaped pattern that eats the rest of its line is anchored at the line start, so prose quoting a trailer keeps its text.",
  "markers": [
   {
    "name": "robot-footer",
@@ -7,7 +7,7 @@
   },
   {
    "name": "generated-footer",
-   "pattern": "(?:🤖[^\\S\\r\\n]*)?Generated[^\\S\\r\\n]+(?:with|by)[^\\S\\r\\n]+\\[?Claude[^\\S\\r\\n]+Code\\]?(?:\\([^)\\s]*\\))?"
+   "pattern": "(?:🤖[^\\S\\r\\n]*)?(?:Generated|Made)[^\\S\\r\\n]+(?:with|by)[^\\S\\r\\n]+\\[?Claude(?:[^\\S\\r\\n]+Code)?\\]?(?:\\([^)\\s]*\\))?"
   },
   {
    "name": "co-authored-by",
@@ -17,6 +17,14 @@
    "name": "ai-co-author",
    "pattern": "Co-Authored-By:[^\\S\\r\\n]*(?:Anthropic|OpenAI|ChatGPT|Copilot|Gemini|Codex|Cursor|Aider|Devin)\\b[^\\r\\n<`]*(?:<[^>\\r\\n]*>)?"
   },
+  {
+   "name": "ai-co-author-model",
+   "pattern": "^[^\\S\\r\\n]*Co-Authored-By:[^\\S\\r\\n]*(?:GitHub[^\\S\\r\\n]+Copilot|Opus|Sonnet|Haiku|Fable|GPT)\\b[^\\r\\n<`]*(?:<[^>\\r\\n]*>)?"
+  },
+  {
+   "name": "ai-assisted-by",
+   "pattern": "^[^\\S\\r\\n]*(?:Assisted|Generated)-By:[^\\S\\r\\n]*(?:Claude|Anthropic|OpenAI|ChatGPT|(?:GitHub[^\\S\\r\\n]+)?Copilot|Gemini|Codex|Cursor|Aider|Devin|Opus|Sonnet|Haiku|Fable|GPT)\\b[^\\r\\n<`]*(?:<[^>\\r\\n]*>)?"
+  },
   {
    "name": "anthropic-noreply",
    "pattern": "noreply@anthropic\\.com"

package/tools/gen-hosting-codes.mjs

@@ -51,7 +51,7 @@ export async function hostingCodesFileFrom(dir) {
 function absent() {
   return (
     `omx-clap-core's TypeScript modules were not found in any of: ${clapCoreTsDirCandidates().join(', ')}. ` +
-    'Install omx-clap-core-devel (pkg-config omx-clap-core), set OMX_CLAP_CORE_TSDIR to its tsdir, or run make -C native deps.'
+    'Install omx-clap-core (its modules in /usr/share/omx-clap-core/ts), set OMX_CLAP_CORE_TSDIR to its tsdir, or run make -C native deps.'
   );
 }
 

package/tools/gen-python-declarations.mjs

@@ -42,8 +42,10 @@ const PY_NAMES = [
   'DESCRIPTOR_SCHEMA_ENV',
   'DESCRIPTOR_SCHEMA_INSTALLED',
   'DESCRIPTOR_SCHEMA_FLOOR',
+  'DESCRIPTOR_ID_HASH_PREFIX',
   'DESCRIPTOR_CODE_SCHEMA',
   'DESCRIPTOR_CODE_SCHEMA_MISSING',
+  'DESCRIPTOR_CODE_SCHEMA_FLOOR',
   'DESCRIPTOR_CODE_BINARY_UNHASHED',
   'DESCRIPTOR_CODE_DIR_UNWRITABLE',
 ];

package/tools/install-roundtrip.sh

@@ -0,0 +1,173 @@
+#!/bin/bash
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+#
+# The after-install scan, end to end on a clean image (#168): build this checkout's package, install it, install a
+# plugin package, and see the plugin's qualification record, descriptor and pin appear with no manual step; upgrade
+# the plugin package with a changed bundle and see them change; remove it and see them go.
+#
+#   podman run --rm -v "$PWD":/src:ro,Z docker.io/library/debian:trixie bash /src/tools/install-roundtrip.sh /src
+#   podman run --rm -v "$PWD":/src:ro,Z docker.io/library/fedora:44     bash /src/tools/install-roundtrip.sh /src
+#
+# Runs as root inside a throwaway container; rootless podman has no systemd, which is the "direct run" branch of
+# packaging/trigger-scan.sh (the image-build and chroot case). The scan is never started by hand: every record, descriptor and
+# pin below is what the package manager's trigger left. The units under a running systemd (the service start branch)
+# are not exercised here. Network is needed: the OpenMixer channel (OPENMIXER_URL) and npm.
+#
+# Exit 0 when every check holds; each failed check is printed, the run goes on, and the exit is 1.
+set -uo pipefail
+
+src=$(readlink -f "${1:?usage: install-roundtrip.sh <checkout>}")
+url=${OPENMIXER_URL:-https://www.openmixer.org}
+state=/var/lib/omx
+uri_a=urn:plugin-qualify:fixture:lv2-rt-safe
+uri_b=urn:plugin-qualify:fixture:lv2-rt-safe-lib64
+fails=0
+work=$(mktemp -d /tmp/roundtrip.XXXXXX)
+
+say() { printf '\n== %s\n' "$*"; }
+check() { # check <what> <command...>
+  local what=$1; shift
+  if "$@" >/dev/null 2>&1; then echo "ok    $what"; else echo "FAIL  $what"; fails=$((fails + 1)); fi
+}
+absent() { ! "$@"; }
+has_file_with() { grep -rqF -- "$2" "$1" 2>/dev/null; } # has_file_with <dir> <text>
+pins() { cat "$state/qualified.pins" 2>/dev/null; }
+pin_of() { pins | grep -F -- "$1" | head -1; }
+show() {
+  echo "-- records:";     ls "$state/qualification" 2>/dev/null | sed 's/^/   /'
+  echo "-- descriptors:"; (cd "$state/descriptors" 2>/dev/null && find . -type f | sort | sed 's/^/   /')
+  echo "-- pins:";        pins | sed 's/^/   /'
+}
+
+if command -v dnf >/dev/null; then fmt=rpm; else fmt=deb; fi
+
+# --- the clean image: the channel, the build tools ------------------------------------------------------------------
+say "prepare ($fmt)"
+if [ $fmt = rpm ]; then
+  grep -qx 'retries=10' /etc/dnf/dnf.conf || echo 'retries=10' >> /etc/dnf/dnf.conf
+  dnf install -y --setopt=install_weak_deps=False "$url/rpm/openmixer-release.noarch.rpm" >/dev/null &&
+    dnf install -y --setopt=install_weak_deps=False rpm-build dnf-plugins-core gcc make lv2-devel clap-devel tar gzip >/dev/null || exit 2
+else
+  export DEBIAN_FRONTEND=noninteractive
+  apt-get update -qq && apt-get install -y --no-install-recommends ca-certificates curl >/dev/null || exit 2
+  curl -fsSL --retry 5 -o "$work/release.deb" "$url/deb/openmixer-release.deb" && chmod 755 "$work" &&
+    apt-get install -y --no-install-recommends "$work/release.deb" >/dev/null && apt-get update -qq || exit 2
+  apt-get install -y --no-install-recommends devscripts equivs fakeroot build-essential lv2-dev clap-headers >/dev/null || exit 2
+fi
+
+# --- this checkout's package ------------------------------------------------------------------------------------------
+say "build plugin-qualify"
+tree=$work/tree
+mkdir -p "$tree" && (cd "$src" && tar --exclude=./node_modules --exclude=./.git --exclude=./native/build --exclude=./native/deps --exclude=./dist -cf - .) | tar -xf - -C "$tree"
+if [ $fmt = rpm ]; then
+  ver=$(rpmspec -q --qf '%{version}\n' "$tree/packaging/plugin-qualify.spec" | head -1)
+  dnf builddep -y "$tree/packaging/plugin-qualify.spec" >/dev/null || exit 2
+  mkdir -p "$work/rpmbuild/SOURCES" && cp -r "$tree" "$work/plugin-qualify-$ver" &&
+    tar -czf "$work/rpmbuild/SOURCES/plugin-qualify-$ver.tar.gz" -C "$work" "plugin-qualify-$ver"
+  rpmbuild -bb --define "_topdir $work/rpmbuild" "$tree/packaging/plugin-qualify.spec" >"$work/build.log" 2>&1 || { tail -30 "$work/build.log"; exit 2; }
+  pkg=$(ls "$work"/rpmbuild/RPMS/*/plugin-qualify-[0-9]*.rpm)
+else
+  (cd "$tree" && mk-build-deps -i -r -t 'apt-get -y --no-install-recommends' debian/control >/dev/null 2>&1 &&
+    dpkg-buildpackage -us -uc -b >"$work/build.log" 2>&1) || { tail -30 "$work/build.log"; exit 2; }
+  pkg=$(ls "$work"/plugin-qualify_*.deb)
+fi
+echo "built $pkg"
+
+say "install plugin-qualify"
+# the package manager's defaults, recommends included: the descriptor writer needs python3-lilv, which the deb recommends
+if [ $fmt = rpm ]; then dnf install -y "$pkg" >/dev/null || exit 2; else apt-get install -y "$pkg" >/dev/null || exit 2; fi
+echo "-- after the install, with no plugin: state file $( [ -e $state/qualify-sync.json ] && echo present || echo absent )"
+check "the trigger script ships" test -x "$( (dpkg -L plugin-qualify 2>/dev/null || rpm -ql plugin-qualify) | grep '/trigger-scan$')"
+check "installing with no plugin leaves no record" absent test -e "$state/qualification/$uri_a"
+
+# --- a plugin package: the repo's own LV2 fixture, packed as a distribution package would ------------------------------
+say "build the plugin package"
+fx=$work/fx
+make -C "$src/native" BUILD="$fx" "$fx/fixtures/lv2/rt-safe.lv2/gain.so" >/dev/null 2>&1 || { echo "the fixture bundle does not build"; exit 2; }
+bundle() { # bundle <root> <libdir> <version-marker>: the bundles of one plugin package version
+  local root=$1 lib=$2 mark=$3 b=$root$2/rt-safe.lv2
+  mkdir -p "$b" && cp "$fx"/fixtures/lv2/rt-safe.lv2/* "$b/"
+  [ -z "$mark" ] || echo "# $mark" >> "$b/gain.ttl" # a changed bundle: the plugin's file set hashes differently
+  if [ $fmt = rpm ]; then # the second plugin of the Fedora package lives in /usr/lib64/lv2, under a uri of its own
+    local b2=$root/usr/lib64/lv2/rt-safe-lib64.lv2
+    mkdir -p "$b2" && cp "$fx"/fixtures/lv2/rt-safe.lv2/* "$b2/" && sed -i "s/lv2-rt-safe/lv2-rt-safe-lib64/g" "$b2"/*.ttl
+    [ -z "$mark" ] || echo "# $mark" >> "$b2/gain.ttl"
+  fi
+}
+mkplugin() { # mkplugin <version> <marker>: ./fakeplug-<version>.<fmt>
+  local v=$1 m=$2 root=$work/pkg-$1
+  rm -rf "$root"; bundle "$root" /usr/lib/lv2 "$m"
+  if [ $fmt = deb ]; then
+    mkdir -p "$root/DEBIAN"
+    printf 'Package: fakeplug\nVersion: %s\nArchitecture: %s\nMaintainer: nobody <nobody@example.org>\nDescription: a fake LV2 plugin package\n' "$v" "$(dpkg --print-architecture)" > "$root/DEBIAN/control"
+    dpkg-deb --root-owner-group --build "$root" "$work/fakeplug-$v.deb" >/dev/null
+  else
+    cat > "$work/fake-$v.spec" <<SPEC
+Name: fakeplug
+Version: $v
+Release: 1
+Summary: a fake LV2 plugin package
+License: GPL-3.0-or-later
+AutoReqProv: no
+%global debug_package %{nil}
+%description
+a fake LV2 plugin package
+%install
+cp -a $root/. %{buildroot}/
+%files
+/usr/lib/lv2/rt-safe.lv2
+/usr/lib64/lv2/rt-safe-lib64.lv2
+SPEC
+    rpmbuild -bb --define "_topdir $work/rpmbuild" "$work/fake-$v.spec" >"$work/fake.log" 2>&1 && cp "$work"/rpmbuild/RPMS/*/fakeplug-$v-1.*.rpm "$work/fakeplug-$v.rpm"
+  fi
+  [ -f "$work/fakeplug-$v.$fmt" ] || { echo "no fake package $v"; tail -20 "$work/fake.log" 2>/dev/null; exit 2; }
+}
+mkplugin 1.0 ""
+mkplugin 2.0 "version 2"
+# what the package manager's own trigger printed is the scan's log: the lines that say what it did are shown
+scan_log() { sed 's/^>>> //' "$work/out" | grep -E '^(qualified |urn:|clap:|LV2 descriptors|plugin-qualify|.*: gone|.*: removed)' | sed 's/^/   scan: /'; }
+install_pkg() { if [ $fmt = rpm ]; then dnf install -y "$1" >"$work/out" 2>"$work/err"; else apt-get install -y "$1" >"$work/out" 2>"$work/err"; fi; local rc=$?; scan_log; return $rc; }
+remove_pkg() { if [ $fmt = rpm ]; then dnf remove -y "$1" >"$work/out" 2>"$work/err"; else apt-get remove -y "$1" >"$work/out" 2>"$work/err"; fi; local rc=$?; scan_log; return $rc; }
+
+# --- install --------------------------------------------------------------------------------------------------------------
+say "install the plugin package: nothing is run by hand"
+install_pkg "$work/fakeplug-1.0.$fmt" || { cat "$work/err"; exit 2; }
+show
+check "a qualification record names the plugin" has_file_with "$state/qualification" "$uri_a"
+check "a descriptor names the plugin" has_file_with "$state/descriptors" "$uri_a"
+check "the pin file pins the plugin" grep -qF "$uri_a" "$state/qualified.pins"
+if [ $fmt = rpm ]; then
+  check "the /usr/lib64/lv2 plugin has a record" has_file_with "$state/qualification" "$uri_b"
+  check "the /usr/lib64/lv2 plugin has a descriptor" has_file_with "$state/descriptors" "$uri_b"
+  check "the /usr/lib64/lv2 plugin is pinned" grep -qF "$uri_b" "$state/qualified.pins"
+fi
+pin1=$(pin_of "$uri_a")
+rec1=$(cat "$state/qualification"/* 2>/dev/null | sha256sum)
+
+# --- upgrade --------------------------------------------------------------------------------------------------------------
+say "upgrade the plugin package with a changed bundle"
+install_pkg "$work/fakeplug-2.0.$fmt" || { cat "$work/err"; exit 2; }
+show
+pin2=$(pin_of "$uri_a")
+check "the pin changed with the bundle" test -n "$pin2" -a "$pin1" != "$pin2"
+check "the record changed with the bundle" test "$rec1" != "$(cat "$state/qualification"/* 2>/dev/null | sha256sum)"
+check "the descriptor is still there" has_file_with "$state/descriptors" "$uri_a"
+
+# --- removal --------------------------------------------------------------------------------------------------------------
+say "remove the plugin package"
+remove_pkg fakeplug || { cat "$work/err"; exit 2; }
+show
+check "the pin is gone" absent grep -qF "$uri_a" "$state/qualified.pins"
+check "the record is gone" absent has_file_with "$state/qualification" "$uri_a"
+check "the descriptor is gone" absent has_file_with "$state/descriptors" "$uri_a"
+if [ $fmt = rpm ]; then
+  check "the /usr/lib64/lv2 plugin's pin is gone" absent grep -qF "$uri_b" "$state/qualified.pins"
+  check "the /usr/lib64/lv2 plugin's record is gone" absent has_file_with "$state/qualification" "$uri_b"
+  check "the /usr/lib64/lv2 plugin's descriptor is gone" absent has_file_with "$state/descriptors" "$uri_b"
+fi
+
+echo
+[ "$fails" -eq 0 ] && echo "install-roundtrip: every check holds ($fmt)" || echo "install-roundtrip: $fails check(s) failed ($fmt)"
+rm -rf "$work"
+[ "$fails" -eq 0 ]

package/tools/mod-host-admit.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+// One mod-host admission: a fresh `mod-host -n` on its own port, then `add` and `remove` of one plugin on its
+// socket. Prints one JSON line, {installed, steps:[{cmd, resp | died}]}, for src/host-admission.ts to classify. The host
+// is always killed at the end, so the next plugin gets a fresh one.
+import { spawn } from "node:child_process";
+import { createConnection } from "node:net";
+
+const uri = process.argv[2];
+const port = 20000 + (process.pid % 20000);
+const STEP_MS = 10000;
+const INSTANCE = 0;
+const COMMANDS = [
+  ["add", `add ${uri} ${INSTANCE}`],
+  ["remove", `remove ${INSTANCE}`],
+];
+
+const host = spawn("mod-host", ["-n", "-p", String(port)], { stdio: "ignore" });
+let hostEnd; // how the host went, once it has
+host.on("exit", (code, signal) => (hostEnd = signal ?? "exit"));
+const spawnFailed = new Promise((resolve) => host.on("error", (e) => resolve(e.code)));
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function connect() {
+  for (let i = 0; i < 50; i++) {
+    if (hostEnd !== undefined) return undefined;
+    const s = await new Promise((resolve) => {
+      const c = createConnection({ port, host: "127.0.0.1" }, () => resolve(c));
+      c.on("error", () => resolve(undefined));
+    });
+    if (s !== undefined) return s;
+    await sleep(100);
+  }
+  return undefined;
+}
+
+async function main() {
+  if ((await Promise.race([spawnFailed, sleep(200).then(() => undefined)])) === "ENOENT") return { installed: false, steps: [] };
+  const sock = await connect();
+  if (sock === undefined) return { installed: true, steps: [{ cmd: "add", died: hostEnd ?? "closed" }] };
+  let buffer = "";
+  let closed = false;
+  sock.on("data", (d) => (buffer += d.toString()));
+  sock.on("close", () => (closed = true));
+  sock.on("error", () => (closed = true));
+  const steps = [];
+  for (const [cmd, line] of COMMANDS) {
+    buffer = "";
+    sock.write(`${line}\0`);
+    const until = Date.now() + STEP_MS;
+    let resp;
+    while (Date.now() < until && resp === undefined && !closed && hostEnd === undefined) {
+      const m = /resp (-?\d+)/.exec(buffer);
+      if (m !== null) resp = Number(m[1]);
+      else await sleep(20);
+    }
+    if (resp === undefined) {
+      await sleep(100); // a host that dies on the command closes the socket a moment before it is reaped
+      steps.push({ cmd, died: hostEnd ?? (closed ? "closed" : "timeout") });
+      if (hostEnd === undefined && !closed) steps[steps.length - 1] = { cmd };
+      break;
+    }
+    steps.push({ cmd, resp });
+    if (resp < 0) break;
+  }
+  sock.destroy();
+  return { installed: true, steps };
+}
+
+const result = await main();
+host.kill("SIGKILL");
+process.stdout.write(`${JSON.stringify(result)}\n`);
+process.exit(0);