@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/scripts/directory-lock.mjs

@@ -0,0 +1,193 @@
+// Dependency-free process exclusion for bootstrap journals. A prepared,
+// nonempty owner directory is published atomically, so another owner can
+// never mistake a newly acquired lease for the empty directory it reclaimed.
+import { randomUUID } from "node:crypto";
+import {
+  closeSync,
+  constants,
+  fdatasyncSync,
+  fstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmdirSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+const OWNER = "owner.json";
+/** @typedef {{ok:true,release:()=>void}|{ok:false,detail:string}} DirectoryLease */
+
+function processStart(pid) {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    return (
+      stat
+        .slice(stat.lastIndexOf(")") + 2)
+        .trim()
+        .split(/\s+/)[19] ?? null
+    );
+  } catch {
+    return null;
+  }
+}
+
+function pinnedDirectory(fd) {
+  const held = fstatSync(fd);
+  for (const prefix of ["/proc/self/fd", "/dev/fd"]) {
+    const path = `${prefix}/${fd}`;
+    try {
+      const actual = statSync(path);
+      if (actual.isDirectory() && actual.dev === held.dev && actual.ino === held.ino) return path;
+    } catch {
+      /* Try the other descriptor filesystem; never fall back to a mutable pathname. */
+    }
+  }
+  throw new Error("this host cannot pin a lock directory by its descriptor");
+}
+
+function ownerAlive(owner) {
+  if (
+    !owner ||
+    !Number.isSafeInteger(owner.pid) ||
+    owner.pid <= 0 ||
+    typeof owner.token !== "string" ||
+    !owner.token
+  )
+    throw new Error("lock owner record is unreadable");
+  const actualStart = processStart(owner.pid);
+  if (typeof owner.start === "string" && actualStart !== null && owner.start !== actualStart)
+    return false;
+  try {
+    process.kill(owner.pid, 0);
+    return true;
+  } catch (err) {
+    if (err?.code === "ESRCH") return false;
+    // Permission errors and unavailable process identity are not proof of death.
+    return true;
+  }
+}
+
+function removeEmpty(path) {
+  try {
+    rmdirSync(path);
+  } catch (err) {
+    if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(err?.code)) throw err;
+  }
+}
+
+function reclaimDead(path) {
+  let fd;
+  try {
+    fd = openSync(
+      path,
+      constants.O_RDONLY | (constants.O_DIRECTORY ?? 0) | (constants.O_NOFOLLOW ?? 0),
+    );
+    const pinned = pinnedDirectory(fd);
+    const ownerPath = join(pinned, OWNER);
+    let owner;
+    try {
+      if (statSync(ownerPath).size > 4096) throw new Error("lock owner record is oversized");
+      owner = JSON.parse(readFileSync(ownerPath, "utf8"));
+    } catch (err) {
+      if (err?.code === "ENOENT" && readdirSync(pinned).length === 0) return true;
+      throw err;
+    }
+    if (ownerAlive(owner)) return false;
+    // The FD names the OLD inode even if another reclaimer replaced the
+    // canonical pathname. Never unlink an owner through that mutable name.
+    try {
+      unlinkSync(ownerPath);
+    } catch (err) {
+      if (err?.code !== "ENOENT") throw err;
+    }
+    // A replacement is nonempty from the moment it becomes visible, so this
+    // either removes the old empty directory or refuses the new live one.
+    removeEmpty(path);
+    return true;
+  } catch (err) {
+    if (err?.code === "ENOENT") return true;
+    throw err;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+/** Immediate refusal under contention; no sleeps, stale timeouts or blind
+ * stale-owner unlink. Release belongs in finally, including async callers.
+ * @returns {DirectoryLease}
+ */
+export function tryDirectoryLock(home, name = "reembed") {
+  if (!/^[a-z0-9-]+$/.test(name)) return { ok: false, detail: "lock busy: invalid lock name" };
+  const path = join(home, `.qcr-${name}.lock`);
+  const prepared = `${path}-${process.pid}-${randomUUID()}.ready`;
+  let fd;
+  let published = false;
+  try {
+    mkdirSync(home, { recursive: true, mode: 0o700 });
+    mkdirSync(prepared, { mode: 0o700 });
+    const ownerFd = openSync(join(prepared, OWNER), "wx", 0o600);
+    try {
+      writeFileSync(
+        ownerFd,
+        JSON.stringify({ pid: process.pid, start: processStart(process.pid), token: randomUUID() }),
+      );
+      fdatasyncSync(ownerFd);
+    } finally {
+      closeSync(ownerFd);
+    }
+    fd = openSync(prepared, constants.O_RDONLY | (constants.O_DIRECTORY ?? 0));
+    const pinned = pinnedDirectory(fd);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        renameSync(prepared, path);
+        published = true;
+      } catch (err) {
+        if (!["ENOTEMPTY", "EEXIST"].includes(err?.code)) throw err;
+        if (!reclaimDead(path))
+          return { ok: false, detail: "lock busy: another process owns this journal" };
+        continue;
+      }
+      let released = false;
+      const heldFd = fd;
+      return {
+        ok: true,
+        release() {
+          if (released) return;
+          released = true;
+          try {
+            try {
+              unlinkSync(join(pinned, OWNER));
+            } catch (err) {
+              if (err?.code !== "ENOENT") throw err;
+            }
+            removeEmpty(path);
+          } finally {
+            closeSync(heldFd);
+          }
+        },
+      };
+    }
+    return { ok: false, detail: "lock busy: another process won the journal lease" };
+  } catch (err) {
+    return { ok: false, detail: `lock busy: ${err instanceof Error ? err.message : String(err)}` };
+  } finally {
+    if (!published) {
+      if (fd !== undefined) closeSync(fd);
+      try {
+        unlinkSync(join(prepared, OWNER));
+      } catch {
+        /* Only our unpublished unique candidate. */
+      }
+      try {
+        rmdirSync(prepared);
+      } catch {
+        /* A refused lease never removes the canonical lock. */
+      }
+    }
+  }
+}

package/scripts/heartbeat-fresh.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Is the daemon's heartbeat from the container that is running NOW?
+//
+// Any status.json on disk may be the previous daemon's last write (made while
+// ansible was still rsyncing, so even "written after the deploy started" does
+// not prove it). The only reference that cannot be fooled that way is the
+// container's own start: a heartbeat written after it came from this boot,
+// and one that is also recent says the daemon is still alive.
+//
+// stdin, all from ONE ssh call so every timestamp is the VM's own clock:
+//   line 1  the container's .State.StartedAt (docker inspect)
+//   line 2  the VM's current time (date -u +%Y-%m-%dT%H:%M:%SZ)
+//   rest    status.json
+// Exit 0 fresh, 1 stale (one line on stdout says why), 2 unreadable.
+
+const MAX_AGE_S = Number(process.env.QC_HEARTBEAT_MAX_AGE_S ?? 90);
+
+let input = "";
+for await (const chunk of process.stdin) input += chunk;
+const [startedLine = "", nowLine = "", ...rest] = input.split("\n");
+
+const started = Date.parse(startedLine.trim());
+const now = Date.parse(nowLine.trim());
+let written = NaN;
+try {
+  written = Date.parse(JSON.parse(rest.join("\n")).written_at);
+} catch {
+  // falls through as unreadable
+}
+
+if (Number.isNaN(started) || Number.isNaN(now)) {
+  console.log("unreadable: no container start time or VM clock reading");
+  process.exit(2);
+}
+if (Number.isNaN(written)) {
+  console.log("unreadable: status.json is missing, not JSON, or has no written_at");
+  process.exit(2);
+}
+if (written < started) {
+  console.log(
+    `stale: last heartbeat ${new Date(written).toISOString()} predates the container start ` +
+      `${new Date(started).toISOString()} — the daemon has not written one since this boot`,
+  );
+  process.exit(1);
+}
+const age = Math.round((now - written) / 1000);
+if (age > MAX_AGE_S) {
+  console.log(
+    `stale: last heartbeat is ${age}s old (limit ${MAX_AGE_S}s) — the daemon stopped writing it`,
+  );
+  process.exit(1);
+}
+console.log(`fresh: written ${age}s ago, after the container started`);
+process.exit(0);

package/scripts/install-locator.sh

@@ -0,0 +1,328 @@
+# shellcheck shell=bash
+# install-locator.sh — the install locator's shell mirror.
+#
+# `src/install.ts` is the reference; this is the same rule for the scripts that
+# cannot import it (the posting route, mint-token, deploy.sh, the bench). The
+# two are run over the same cases by `tests/install-shell.test.ts`, so they
+# cannot drift apart silently.
+#
+# SOURCE it, never run it:
+#
+#   . "$ROOT/scripts/install-locator.sh"
+#   CONFIG="$(qcr_locate_config "$ROOT")" || exit 1
+#
+# The rule, in order:
+#   1. $QCR_CONFIG, taken as given (a missing file is the caller's error)
+#   2. the install's config home: ${XDG_CONFIG_HOME:-$HOME/.config}/qcr/<install>/config.toml,
+#      whether or not it exists (a missing file is the caller's error too)
+#      ($QCR_CONFIG_HOME, when set and absolute, is the config home)
+# `<install>` is $QCR_INSTALL, default `default`, a plain name only. The
+# checkout's own config.toml is never read — `qcr install migrate`
+# moves it. The <checkout-root> argument is kept for the profile lookup.
+#
+# Repo profiles: `qcr_profile_dirs <root>` prints the directories a
+# profile is looked up in, highest priority first — the config home's
+# profiles/, then profiles/ beside $QCR_CONFIG when it is set, then the
+# checkout's, which serves only the generic examples (`QCR_EXAMPLE_PROFILES`,
+# pinned to src/install.ts EXAMPLE_PROFILES): `qcr_profile_dir` applies that.
+
+qcr_install_name() {
+  local name="${QCR_INSTALL:-}"
+  name="${name#"${name%%[![:space:]]*}"}"
+  name="${name%"${name##*[![:space:]]}"}"
+  if [[ -z "$name" ]]; then
+    printf '%s\n' default
+    return 0
+  fi
+  if [[ ! "$name" =~ ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$ || "$name" == *..* ]]; then
+    echo "install-locator: QCR_INSTALL \"$name\" is not a plain name — letters, digits, '.', '_' and '-' only, no path separators or '..'" >&2
+    return 1
+  fi
+  printf '%s\n' "$name"
+}
+
+# Leading and trailing whitespace dropped, as the reference's .trim() does.
+_qcr_trim() { # _qcr_trim <value>
+  local v="$1"
+  v="${v#"${v%%[![:space:]]*}"}"
+  v="${v%"${v##*[![:space:]]}"}"
+  printf '%s\n' "$v"
+}
+
+# An XDG base dir: the variable (trimmed) when set AND absolute, else
+# $HOME/<fallback> ($HOME trimmed too).
+_qcr_xdg_base() { # _qcr_xdg_base <value> <fallback-under-home>
+  local value fallback="$2" home
+  value="$(_qcr_trim "$1")"
+  if [[ -n "$value" && "$value" == /* ]]; then
+    printf '%s\n' "$value"
+  else
+    home="$(_qcr_trim "${HOME:-}")"
+    printf '%s\n' "${home:-$(cd ~ && pwd)}/$fallback"
+  fi
+}
+
+# A whole-home override ($QCR_CONFIG_HOME / $QCR_STATE_HOME — the
+# companion container points them at its mounts): taken only when set AND
+# absolute, trailing slashes dropped. Prints nothing when it does not apply.
+_qcr_home_override() { # _qcr_home_override <value>
+  local v
+  v="$(_qcr_trim "$1")"
+  [[ -n "$v" && "$v" == /* ]] || return 0
+  while [[ "$v" == */ && "$v" != / ]]; do v="${v%/}"; done
+  printf '%s\n' "$v"
+}
+
+qcr_config_home() {
+  local name over
+  over="$(_qcr_home_override "${QCR_CONFIG_HOME:-}")"
+  if [[ -n "$over" ]]; then
+    printf '%s\n' "$over"
+    return 0
+  fi
+  name="$(qcr_install_name)" || return 1
+  printf '%s\n' "$(_qcr_xdg_base "${XDG_CONFIG_HOME:-}" .config)/qcr/$name"
+}
+
+qcr_state_home() {
+  local name over
+  over="$(_qcr_home_override "${QCR_STATE_HOME:-}")"
+  if [[ -n "$over" ]]; then
+    printf '%s\n' "$over"
+    return 0
+  fi
+  name="$(qcr_install_name)" || return 1
+  printf '%s\n' "$(_qcr_xdg_base "${XDG_STATE_HOME:-}" .local/state)/qcr/$name"
+}
+
+# Where scripts/vm-ghcr-login.sh records when the VM's registry pull token
+# expires (one ISO UTC line, no secret in it) and where `deploy.sh verify` reads
+# it back: the install's state home on the controller, never the config home
+# (which ships to the VM). $QCR_GHCR_EXPIRY_FILE overrides it (tests).
+qcr_ghcr_expiry_file() {
+  local override home
+  override="$(_qcr_trim "${QCR_GHCR_EXPIRY_FILE:-}")"
+  if [[ -n "$override" ]]; then
+    printf '%s\n' "$override"
+    return 0
+  fi
+  home="$(qcr_state_home)" || return 1
+  printf '%s\n' "$home/ghcr-token-expiry"
+}
+
+qcr_locate_config() { # qcr_locate_config [checkout-root]
+  local override="${QCR_CONFIG:-}" home
+  override="${override#"${override%%[![:space:]]*}"}"
+  override="${override%"${override##*[![:space:]]}"}"
+  if [[ -n "$override" ]]; then
+    [[ "$override" == /* ]] || override="$PWD/$override"
+    printf '%s\n' "$override"
+    return 0
+  fi
+  home="$(qcr_config_home)" || return 1
+  printf '%s\n' "$home/config.toml"
+}
+
+# The generic profiles the checkout ships — the only ones read from there.
+QCR_EXAMPLE_PROFILES=(default example-django minimal snappy fast)
+
+qcr_is_example_profile() { # qcr_is_example_profile <name>
+  local p
+  for p in "${QCR_EXAMPLE_PROFILES[@]}"; do [[ "$p" == "$1" ]] && return 0; done
+  return 1
+}
+
+qcr_profile_dirs() { # qcr_profile_dirs <checkout-root>
+  local root="$1" override="${QCR_CONFIG:-}" home dir seen=""
+  override="${override#"${override%%[![:space:]]*}"}"
+  override="${override%"${override##*[![:space:]]}"}"
+  home="$(qcr_config_home)" || return 1
+  local -a dirs=("$home/profiles")
+  if [[ -n "$override" ]]; then
+    [[ "$override" == /* ]] || override="$PWD/$override"
+    dirs+=("$(dirname "$override")/profiles")
+  fi
+  dirs+=("$root/profiles")
+  for dir in "${dirs[@]}"; do
+    [[ "$seen" == *$'\n'"$dir"$'\n'* ]] && continue
+    seen+=$'\n'"$dir"$'\n'
+    printf '%s\n' "$dir"
+  done
+}
+
+# The directory holding profile <name> — src/install.ts `locateProfile`: the
+# first of qcr_profile_dirs that has it, the checkout's only for an example
+# (a directory reached first as "beside $QCR_CONFIG" is not the checkout's,
+# even when it is the same path). Prints nothing when none does.
+qcr_profile_dir() { # qcr_profile_dir <checkout-root> <name>
+  local root="$1" name="$2" dir override="${QCR_CONFIG:-}" beside=""
+  override="$(_qcr_trim "$override")"
+  if [[ -n "$override" ]]; then
+    [[ "$override" == /* ]] || override="$PWD/$override"
+    beside="$(dirname "$override")/profiles"
+  fi
+  while IFS= read -r dir; do
+    if [[ "$dir" == "$root/profiles" && "$dir" != "$beside" ]] && ! qcr_is_example_profile "$name"; then
+      continue
+    fi
+    if [[ -d "$dir/$name" ]]; then
+      printf '%s\n' "$dir/$name"
+      return 0
+    fi
+  done < <(qcr_profile_dirs "$root")
+  return 0
+}
+
+# Copy the profiles the locator would resolve into <dest>, one directory per
+# name taken from the first qcr_profile_dirs place that holds it (the home's,
+# then beside $QCR_CONFIG). The checkout's own profiles/ is left out unless
+# $QCR_CONFIG sits beside it: a snapshot of the checkout carries those.
+qcr_profiles_merged() { # qcr_profiles_merged <checkout-root> <dest>
+  local root="$1" dest="$2" override="${QCR_CONFIG:-}" beside="" dir entry name
+  override="$(_qcr_trim "$override")"
+  if [[ -n "$override" ]]; then
+    [[ "$override" == /* ]] || override="$PWD/$override"
+    beside="$(dirname "$override")/profiles"
+  fi
+  mkdir -p "$dest"
+  while IFS= read -r dir; do
+    [[ "$dir" == "$root/profiles" && "$dir" != "$beside" ]] && continue
+    [[ -d "$dir" ]] || continue
+    for entry in "$dir"/* "$dir"/.[!.]*; do
+      [[ -e "$entry" ]] || continue
+      name="$(basename "$entry")"
+      [[ -e "$dest/$name" ]] || cp -RL "$entry" "$dest/$name"
+    done
+  done < <(qcr_profile_dirs "$root")
+}
+
+# ---- secrets -----------------------------------------------------------------
+#
+#   SECRETS_DIR="$(qcr_locate_secrets "$configured" "${QC_SECRETS_DIR:-}")" || exit 1
+#
+# The rule, in order (src/install.ts `locateSecrets`):
+#   0. inside a daemon container, $QCR_SECRETS_MOUNT (absolute; both
+#      entrypoints export it) — the shared config names a HOST path
+#   1. the configured [github] secrets_dir, unless empty or the old default
+#      spelling (~/.config/quickreview-bot) — taken as given, ~ expanded
+#   2. the caller's override (the wizards' $QC_SECRETS_DIR), ~ expanded
+#   3. <config home>/secrets, whether or not it exists
+# The old ~/.config/quickreview-bot dir itself is never read.
+
+qcr_secrets_home() {
+  local home
+  home="$(qcr_config_home)" || return 1
+  printf '%s\n' "$home/secrets"
+}
+
+_qcr_home_dir() {
+  local h
+  h="$(_qcr_trim "${HOME:-}")"
+  printf '%s\n' "${h:-$(cd ~ && pwd)}"
+}
+
+_qcr_expand_home() { # _qcr_expand_home <path>
+  local p="$1"
+  if [[ "$p" == "~" ]]; then
+    _qcr_home_dir
+  elif [[ "$p" == "~/"* ]]; then
+    printf '%s\n' "$(_qcr_home_dir)/${p#\~/}"
+  else
+    printf '%s\n' "$p"
+  fi
+}
+
+# The old default's spelling, only to recognise it in a configured value.
+_qcr_old_secrets_dir() { printf '%s\n' "$(_qcr_home_dir)/.config/quickreview-bot"; }
+
+qcr_locate_secrets() { # qcr_locate_secrets [configured] [override]
+  local configured override home stripped mount
+  mount="$(_qcr_trim "${QCR_SECRETS_MOUNT:-}")"
+  if [[ "$mount" == /* ]]; then
+    printf '%s\n' "$mount"
+    return 0
+  fi
+  configured="$(_qcr_trim "${1:-}")"
+  override="$(_qcr_trim "${2:-}")"
+  if [[ -n "$configured" ]]; then
+    stripped="$configured"
+    while [[ "$stripped" == */ ]]; do stripped="${stripped%/}"; done
+    if [[ "$stripped" != "~/.config/quickreview-bot" && "$(_qcr_expand_home "$stripped")" != "$(_qcr_old_secrets_dir)" ]]; then
+      _qcr_expand_home "$configured"
+      return 0
+    fi
+  fi
+  if [[ -n "$override" ]]; then
+    _qcr_expand_home "$override"
+    return 0
+  fi
+  home="$(qcr_secrets_home)" || return 1
+  printf '%s\n' "$home"
+}
+
+# The companion's OpenViking key file (src/install.ts `locateKeysFile`):
+# $QCR_OPENVIKING_KEYS, else $XDG_CONFIG_HOME/qcr-operator/<install>/ — whether
+# or not it exists. Deliberately outside the config home, which a container
+# mounts.
+qcr_locate_keys_file() {
+  local override name
+  override="$(_qcr_trim "${QCR_OPENVIKING_KEYS:-}")"
+  if [[ -n "$override" ]]; then
+    printf '%s\n' "$override"
+    return 0
+  fi
+  name="$(qcr_install_name)" || return 1
+  printf '%s\n' "$(_qcr_xdg_base "${XDG_CONFIG_HOME:-}" .config)/qcr-operator/$name/openviking-keys.env"
+}
+
+# ---- the shipped config home -------------------------------------------------
+#
+#   SHIPPED="$(qcr_shipped_config "$ROOT")" || exit 1
+#
+# The located config when it is one `deploy.sh release` can ship (it sends the
+# config home as a tar): the file exists and its directory — the config home, with the profiles/ beside it —
+# lies outside the checkout. Prints nothing (status 0) when there is none: no
+# config at all, or a $QCR_CONFIG naming a file inside the checkout, which
+# deploy never ships (the tar carries the config home only, and the VM reads
+# the shipped home).
+# Status 1 only on a locator error.
+qcr_shipped_config() { # qcr_shipped_config <checkout-root>
+  local root="$1" config dir rootp
+  config="$(qcr_locate_config "$root")" || return 1
+  [[ -f "$config" ]] || return 0
+  dir="$(cd "$(dirname "$config")" 2>/dev/null && pwd -P)" || return 0
+  rootp="$(cd "$root" 2>/dev/null && pwd -P)" || return 1
+  [[ "$dir" == "$rootp" || "$dir" == "$rootp"/* ]] && return 0
+  printf '%s/%s\n' "$dir" "$(basename "$config")"
+}
+
+_qcr_sha256() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum | cut -d' ' -f1
+  else
+    shasum -a 256 | cut -d' ' -f1
+  fi
+}
+
+# What a config home ships, as two hashes: `config=<sha256> profiles=<sha256>`.
+# The config file's bytes; and every file under profiles/ beside it (symlinks
+# followed, as the ship copies them), listed `<sha256>  <relative path>` in
+# byte order and hashed again — so a renamed, added or removed file changes it
+# as surely as an edited one. The same function runs on the PC over the home it
+# would ship and in the container over the home it was shipped; the deploy
+# tab's "profile changed, not deployed" is those two answers disagreeing.
+qcr_config_fingerprint() { # qcr_config_fingerprint <config-file>
+  local config="$1" dir cfg_h prof_h
+  dir="$(dirname "$config")"
+  cfg_h="$(_qcr_sha256 <"$config")" || return 1
+  prof_h="$(
+    cd "$dir" || exit 1
+    if [[ -d profiles ]]; then
+      find -L profiles -type f -print0 | LC_ALL=C sort -z |
+        while IFS= read -r -d '' f; do
+          printf '%s  %s\n' "$(_qcr_sha256 <"$f")" "$f"
+        done
+    fi | _qcr_sha256
+  )" || return 1
+  printf 'config=%s profiles=%s\n' "$cfg_h" "$prof_h"
+}

package/scripts/install-wrapper.sh

@@ -0,0 +1,76 @@
+#!/bin/sh
+# The image's `install` mode (docker/entrypoint.sh): the host wrapper, pinned.
+#
+#   docker run --rm --user "$(id -u):$(id -g)" -v ~/.local/bin:/out IMAGE install
+#       writes /out/qcr (the -v ~/.local/bin:/out shape);
+#   docker run --rm IMAGE install | sh
+#       with no /out mounted, prints a script that writes ~/.local/bin/qcr.
+#
+# The wrapper (scripts/qcr-host.sh) is the image's own copy with the image
+# pinned into it: QCR_IMAGE if the caller named one (`qcr update` does), else
+# ghcr.io/<owner>/<name>:<this image's version>, owner and name from
+# package.json's repository URL. The image cannot see its own tag or digest
+# from inside, so a local or retagged image is installed with
+# -e QCR_IMAGE=<its tag>.
+#
+# Nothing but the wrapper (or the printed installer) goes to stdout.
+set -eu
+
+APP="${QCR_APP_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
+OUT="${QCR_INSTALL_OUT:-/out}"
+
+die() {
+  echo "qcr-install: $*" >&2
+  exit 1
+}
+
+template="$APP/scripts/qcr-host.sh"
+[ -f "$template" ] || die "the wrapper template is missing: $template"
+
+image="${QCR_IMAGE:-}"
+if [ -z "$image" ]; then
+  image="$(node -e '
+    const pkg = require(process.argv[1]);
+    const m = /github\.com[/:]([^/]+)\/([^/]+?)(?:\.git)?$/.exec(pkg.repository?.url ?? "");
+    if (!m || !pkg.version) process.exit(1);
+    console.log("ghcr.io/" + m[1].toLowerCase() + "/" + m[2].toLowerCase() + ":" + pkg.version);
+  ' "$APP/package.json" 2>/dev/null)" ||
+    die "cannot tell the image from $APP/package.json (repository url, version): name it with -e QCR_IMAGE=<ref>"
+fi
+# One option-safe token, and nothing the substitution below could misread.
+case "$image" in
+  '' | -* | *[!A-Za-z0-9._/:@-]*) die "QCR_IMAGE \"$image\" is not an image reference" ;;
+esac
+
+grep -q '@@QCR_IMAGE@@' "$template" || die "the wrapper template has no image placeholder"
+wrapper="$(sed "s|@@QCR_IMAGE@@|$image|" "$template")"
+case "$wrapper" in *QCR_WRAPPER_EOF*) die "the wrapper template holds the installer's terminator" ;; esac
+
+if [ -d "$OUT" ]; then
+  [ -w "$OUT" ] ||
+    die "$OUT is not writable by uid $(id -u) — run with --user \"\$(id -u):\$(id -g)\" so the file is yours"
+  tmp="$(mktemp "$OUT/.qcr.XXXXXX")"
+  printf '%s\n' "$wrapper" >"$tmp"
+  chmod 0755 "$tmp"
+  mv -f "$tmp" "$OUT/qcr"
+  echo "qcr-install: wrote $OUT/qcr, pinned to $image" >&2
+  exit 0
+fi
+
+# No /out: the installer for `| sh`. It writes the same file, atomically.
+cat <<INSTALLER
+set -eu
+dest="\$HOME/.local/bin"
+mkdir -p "\$dest"
+tmp="\$(mktemp "\$dest/.qcr.XXXXXX")"
+cat >"\$tmp" <<'QCR_WRAPPER_EOF'
+$wrapper
+QCR_WRAPPER_EOF
+chmod 0755 "\$tmp"
+mv -f "\$tmp" "\$dest/qcr"
+echo "qcr: installed \$dest/qcr, pinned to $image" >&2
+case ":\$PATH:" in
+  *":\$dest:"*) ;;
+  *) echo "qcr: add \$dest to your PATH" >&2 ;;
+esac
+INSTALLER