crewly 1.20.131 → 1.20.133

package/config/skills/agent/core/install-skill/execute.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+# =============================================================================
+# install-skill — install a skill and its dependencies as a background job.
+#
+# Returns at once with a job id (or "already-ready"). When the job ends you get
+# a message: [SKILL INSTALLED] … or [SKILL INSTALL FAILED] … with the reason.
+# Tell the user in one line that you are installing it, then continue with
+# other work or wait; resume the paused task when the message arrives.
+# Backed by POST /api/skill-setup/install.
+#
+# Only official skills (bundled with Crewly, or published by the Crewly Team in
+# the official registry) install without asking. A third-party skill needs the
+# owner's yes in chat first; then pass --approved-by-owner (it is checked
+# against the owner's chat history — claiming it without their yes fails).
+#
+# Usage:
+#   bash execute.sh --id transcribe-audio --resume "transcribe clip.m4a for Steve"
+#   bash execute.sh --id some-skill --approved-by-owner --owner-said "好的，装 some-skill"
+#   bash execute.sh '{"id":"pdf-tools","resume":"…"}'
+# =============================================================================
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../../_common/lib.sh"
+
+print_usage() {
+  cat <<'EOF_USAGE'
+Usage:
+  bash execute.sh --id <skill-id> [--resume "what you were doing"] [--approved-by-owner --owner-said "…"] [--force]
+  bash execute.sh '{"id":"…","resume":"…","approvedByOwner":false}'
+
+Options:
+  --id                 Skill id from find-skill (required)
+  --resume             What you were doing; echoed back in the completion message
+  --approved-by-owner  The owner said yes in chat (third-party skills only; verified)
+  --owner-said         Quote the owner's yes (recorded next to the verified message)
+  --force              Re-run setup even if everything looks installed
+  --help | -h          Show this help
+EOF_USAGE
+}
+
+INPUT_JSON=""; ID=""; RESUME=""; APPROVED=false; FORCE=false; OWNER_SAID=""
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then INPUT_JSON="$1"; shift || true; fi
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --id)                [ $# -ge 2 ] || error_exit "--id requires a value"; ID="$2"; shift 2 ;;
+    --resume)            [ $# -ge 2 ] || error_exit "--resume requires a value"; RESUME="$2"; shift 2 ;;
+    --approved-by-owner) APPROVED=true; shift ;;
+    --owner-said)        [ $# -ge 2 ] || error_exit "--owner-said requires a value"; OWNER_SAID="$2"; shift 2 ;;
+    --force)             FORCE=true; shift ;;
+    --help|-h)           print_usage; exit 0 ;;
+    *) error_exit "Unknown option: $1" ;;
+  esac
+done
+if [ -n "$INPUT_JSON" ]; then
+  INPUT=$(read_json_input "$INPUT_JSON")
+  [ -z "$ID" ] && ID=$(printf '%s' "$INPUT" | jq -r '.id // empty')
+  [ -z "$RESUME" ] && RESUME=$(printf '%s' "$INPUT" | jq -r '.resume // empty')
+  [ "$(printf '%s' "$INPUT" | jq -r '.approvedByOwner // false')" = "true" ] && APPROVED=true
+  [ "$(printf '%s' "$INPUT" | jq -r '.force // false')" = "true" ] && FORCE=true
+fi
+require_param "id (--id)" "$ID"
+# The quote travels as X-Agent-Authorization (lib.sh encodes it): recorded, never trusted.
+[ -n "$OWNER_SAID" ] && export CREWLY_AGENT_AUTHORIZATION="$OWNER_SAID"
+
+BODY=$(jq -cn --arg id "$ID" --arg resume "$RESUME" --argjson approved "$APPROVED" --argjson force "$FORCE" \
+  '{id: $id} + (if $resume != "" then {resume: $resume} else {} end)
+   + (if $approved then {approvedByOwner: true} else {} end) + (if $force then {force: true} else {} end)')
+
+ERR_FILE=$(mktemp); trap 'rm -f "$ERR_FILE"' EXIT
+RESPONSE=$(api_call POST "/skill-setup/install" "$BODY" 2>"$ERR_FILE") || {
+  ERR=$(tail -n 1 "$ERR_FILE")
+  printf '%s' "$ERR" | jq -c '{success: false,
+      reason: (.details.code // "install_failed"),
+      error: (.details.error // .error // "install failed")}
+    + (if (.details.code // "") | startswith("owner_approval") then {official: false, next: "Ask the owner in chat before installing this third-party skill."} else {} end)' 2>/dev/null \
+    || jq -cn --arg e "$ERR" '{success: false, reason: "install_failed", error: $e}'
+  exit 1
+}
+
+printf '%s' "$RESPONSE" | jq -c '.data | {success: true} + .'

package/config/skills/agent/core/install-skill/execute.test.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+# Tests for install-skill — run with: bash execute.test.sh </dev/null
+# A python HTTP stub plays the backend; asserts the request body, the
+# X-Agent-Authorization citation and how refusals are reported.
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+EXEC="$HERE/execute.sh"
+PASS=0; FAIL=0
+check() {
+  local name="$1"; local got="$2"; local want="$3"
+  if [ "$got" = "$want" ]; then PASS=$((PASS+1)); else FAIL=$((FAIL+1)); echo "FAIL: $name"; echo "  want: $want"; echo "  got:  $got"; fi
+}
+
+PORT=18852
+STUB_LOG="$(mktemp)"; export STUB_LOG; export STUB_PORT="$PORT"
+python3 -u <<'PY' >/dev/null 2>&1 &
+from http.server import BaseHTTPRequestHandler, HTTPServer
+import base64, json, os
+LOG = os.environ['STUB_LOG']; PORT = int(os.environ['STUB_PORT'])
+class H(BaseHTTPRequestHandler):
+    def reply(self, code, body):
+        self.send_response(code); self.send_header('Content-Type', 'application/json'); self.end_headers()
+        self.wfile.write(json.dumps(body).encode())
+    def do_POST(self):
+        body = json.loads(self.rfile.read(int(self.headers.get('Content-Length', 0))) or b'{}')
+        auth = self.headers.get('X-Agent-Authorization')
+        if auth and auth.startswith('b64:'):
+            auth = base64.b64decode(auth[4:]).decode()
+        open(LOG, 'w').write(json.dumps({'path': self.path, 'body': body, 'agent': self.headers.get('X-Agent-Session'), 'auth': auth}))
+        if body['id'] == 'shady-ocr' and not body.get('approvedByOwner'):
+            return self.reply(403, {'success': False, 'code': 'owner_approval_required', 'error': '"shady-ocr" is a third-party skill. Ask the owner in chat…'})
+        if body['id'] == 'ready-one':
+            return self.reply(200, {'success': True, 'data': {'state': 'already-ready', 'skillId': 'ready-one', 'executePath': '/x/execute.sh', 'next': 'use it now'}})
+        self.reply(202, {'success': True, 'data': {'jobId': 'job1', 'skillId': body['id'], 'state': 'running', 'official': True,
+                                                   'estimatedMinutes': 6, 'willNotify': ['test-agent'], 'next': 'Installing…'}})
+    def log_message(self, *a, **k): pass
+HTTPServer(('127.0.0.1', PORT), H).serve_forever()
+PY
+STUB_PID=$!
+disown "$STUB_PID" 2>/dev/null || true
+trap 'kill "$STUB_PID" >/dev/null 2>&1; rm -f "$STUB_LOG"' EXIT
+for i in $(seq 1 30); do curl -s -o /dev/null -m 0.2 "http://127.0.0.1:${PORT}/" 2>/dev/null && break; sleep 0.1; done
+
+run() { CREWLY_SESSION_NAME=test-agent CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" "$@" 2>/dev/null; }
+run_err() { CREWLY_SESSION_NAME=test-agent CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" "$@" 2>&1 >/dev/null | jq -rs 'last.error' 2>/dev/null; }
+
+OUT=$(run --id transcribe-audio --resume "transcribe clip.m4a for Steve")
+check "path" "$(jq -r .path "$STUB_LOG")" "/api/skill-setup/install"
+check "body" "$(jq -c .body "$STUB_LOG")" '{"id":"transcribe-audio","resume":"transcribe clip.m4a for Steve"}'
+check "agent header (who gets the completion message)" "$(jq -r .agent "$STUB_LOG")" "test-agent"
+check "no citation by default" "$(jq -r .auth "$STUB_LOG")" "null"
+check "job returned at once" "$(printf '%s' "$OUT" | jq -c '{success, jobId, state, estimatedMinutes}')" '{"success":true,"jobId":"job1","state":"running","estimatedMinutes":6}'
+
+OUT=$(run --id shady-ocr); RC=$?
+check "third-party: exit 1" "$RC" "1"
+check "third-party: reason" "$(printf '%s' "$OUT" | jq -r .reason)" "owner_approval_required"
+check "third-party: next says ask the owner" "$(printf '%s' "$OUT" | jq -r .next)" "Ask the owner in chat before installing this third-party skill."
+
+OUT=$(run --id shady-ocr --approved-by-owner --owner-said "好的，装 shady-ocr")
+check "approved: flag sent" "$(jq -c .body "$STUB_LOG")" '{"id":"shady-ocr","approvedByOwner":true}'
+check "approved: owner quote travels as X-Agent-Authorization" "$(jq -r .auth "$STUB_LOG")" "好的，装 shady-ocr"
+check "approved: job" "$(printf '%s' "$OUT" | jq -r .jobId)" "job1"
+
+OUT=$(run '{"id":"pdf-tools","force":true}')
+check "json input" "$(jq -c .body "$STUB_LOG")" '{"id":"pdf-tools","force":true}'
+
+OUT=$(run --id ready-one)
+check "already ready" "$(printf '%s' "$OUT" | jq -c '{state, executePath}')" '{"state":"already-ready","executePath":"/x/execute.sh"}'
+
+check "missing id" "$(run_err)" "Missing required parameter: id (--id)"
+check "unknown option" "$(run_err --yes)" "Unknown option: --yes"
+
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ]

package/config/skills/agent/pdf-tools/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: pdf-tools
+description: Make polished PDFs from Markdown or styled HTML (headless Chrome preferred, WeasyPrint fallback, CJK-ready default stylesheet), merge several parts into one PDF, and read the text of a PDF someone sent you. When a dependency is missing it returns `needsSetup:true` — run `install-skill --id pdf-tools`.
+category: content-creation
+assignableRoles:
+  - "*"
+version: "1.0.0"
+author: Crewly Team
+tags:
+  - pdf
+  - document
+  - report
+  - markdown
+  - html
+  - chrome
+  - weasyprint
+  - merge
+  - read-pdf
+  - extract-text
+  - pypdf
+  - cjk
+  - 中文
+  - 文档
+triggers:
+  - make a pdf
+  - generate pdf
+  - markdown to pdf
+  - html to pdf
+  - merge pdfs
+  - read this pdf
+  - extract text from pdf
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 300000
+---
+
+# PDF Tools
+
+Make PDFs people like to read, and read the PDFs people send you.
+
+## Make a PDF (`render`)
+
+```bash
+# Markdown → PDF with the default A4 stylesheet (CJK fonts, tables, code, quotes)
+bash {{AGENT_SKILLS_PATH}}/pdf-tools/execute.sh '{"action":"render","input":"/tmp/report.md","output":"/tmp/report.pdf","title":"Q3 报告"}'
+
+# Your own styled HTML → PDF (kept exactly as you styled it)
+bash {{AGENT_SKILLS_PATH}}/pdf-tools/execute.sh '{"action":"render","input":"/tmp/brief.html","output":"/tmp/brief.pdf"}'
+
+# Several parts → one PDF, in order (.md / .html / .pdf)
+bash {{AGENT_SKILLS_PATH}}/pdf-tools/execute.sh '{"action":"render","inputs":["/tmp/cover.html","/tmp/body.md","/tmp/appendix.pdf"],"output":"/tmp/full.pdf"}'
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `input` / `inputs` | — | One file, or a list of parts merged in order |
+| `output` | input path with `.pdf` | Where the PDF goes (required for several parts) |
+| `title` | file name | Document title (Markdown only) |
+| `css` | — | Extra stylesheet appended after the default one |
+| `addDefaultStyle` | `false` | Also apply the default stylesheet to HTML input |
+| `engine` | `auto` | `auto` (Chrome, else WeasyPrint), `chrome`, `weasyprint` |
+| `lang` | `zh` | `lang` attribute of the generated HTML (font selection) |
+
+**Engines.** Headless Chrome/Chromium renders exactly what a browser shows
+(modern CSS, web fonts, CJK with system fonts) and is used whenever it is
+installed. WeasyPrint is the fallback. Markdown goes through python-markdown
+(or pandoc when the venv is missing).
+
+**Writing HTML for print.** Use `@page { size: A4; margin: 18mm }`, and
+`<div class="page-break"></div>` (default stylesheet) or `break-after: page` to
+start a new page. For a cover page, render it as its own part and list it first.
+
+Output: `{"success":true,"pdf":"/tmp/report.pdf","size":48213,"parts":1,"engine":"chrome"}`
+
+## Read a PDF (`read`)
+
+```bash
+bash {{AGENT_SKILLS_PATH}}/pdf-tools/execute.sh '{"action":"read","input":"/path/to/file.pdf"}'
+bash {{AGENT_SKILLS_PATH}}/pdf-tools/execute.sh '{"action":"read","input":"/path/to/file.pdf","pages":"1-3,7","textFile":"/tmp/file.txt"}'
+```
+
+Returns `{success, engine, pages, pagesRead, chars, text, truncated, textFile?}`.
+Text is split with `--- page N ---` markers. Long documents are cut at
+`maxChars` (default 20000) — pass `textFile` to get everything on disk. A `note`
+says when the PDF has no text layer (scanned images).
+
+## Other actions
+
+- `merge` — `{"action":"merge","inputs":["a.pdf","b.pdf"],"output":"ab.pdf"}`
+- `info` — `{"action":"info","input":"x.pdf"}` → pages, metadata, encrypted
+- `check` — which engines exist here (`canRender`, `canRead`, `canMerge`)
+
+## Setup
+
+Declared in `skill.json` → `setup`; `install-skill --id pdf-tools` (agents) or
+`crewly skills setup pdf-tools` (terminal) installs what is missing:
+Python venv `~/.crewly/venv/pdf-tools` with pypdf, markdown and weasyprint;
+optionally Chrome (Linux: `chromium`), Pango for WeasyPrint and Noto CJK fonts.
+A missing dependency fails with `"needsSetup": true, "skill": "pdf-tools"` —
+tell the user you are setting it up and run `install-skill`, don't give up.

package/config/skills/agent/pdf-tools/execute.sh

@@ -0,0 +1,301 @@
+#!/bin/bash
+# =============================================================================
+# pdf-tools — make and read PDFs.
+#
+#   render : Markdown / HTML (one or several parts) → one PDF.
+#            Engine: headless Chrome/Chromium (preferred) → WeasyPrint (fallback).
+#            Markdown gets a clean A4 stylesheet with CJK fonts (style.css).
+#   merge  : concatenate PDFs (pypdf).
+#   read   : extract text from a PDF (pypdf, falls back to pdftotext).
+#   info   : page count + metadata.
+#   check  : which engines are available here.
+#
+# Usage:
+#   bash execute.sh '{"action":"render","input":"/tmp/report.md","output":"/tmp/report.pdf","title":"Q3 报告"}'
+#   bash execute.sh '{"action":"render","inputs":["cover.html","body.md","appendix.pdf"],"output":"/tmp/all.pdf"}'
+#   bash execute.sh '{"action":"read","input":"/tmp/contract.pdf","pages":"1-3"}'
+#   bash execute.sh '{"action":"merge","inputs":["a.pdf","b.pdf"],"output":"/tmp/ab.pdf"}'
+#   bash execute.sh --file /tmp/input.json        (JSON in a file)
+#
+# Dependencies are declared in skill.json → setup (install-skill --id pdf-tools).
+# A missing dependency fails with "needsSetup": true, "skill": "pdf-tools".
+#
+# Test hooks: PDF_TOOLS_PYTHON (interpreter), CHROME_BIN (browser),
+# PDF_TOOLS_CHROME_PATHS (browser paths searched before PATH, colon separated).
+# =============================================================================
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_ID="pdf-tools"
+HELPER="${SCRIPT_DIR}/pdf_tools.py"
+DEFAULT_CSS="${SCRIPT_DIR}/style.css"
+CREWLY_HOME_DIR="${CREWLY_HOME:-${HOME}/.crewly}"
+VENV_PYTHON="${CREWLY_HOME_DIR}/venv/${SKILL_ID}/bin/python3"
+CHROME_TIMEOUT_SEC="${PDF_TOOLS_CHROME_TIMEOUT_SEC:-120}"
+CHROME_EXIT_GRACE_SEC=3
+CHROME_APP_PATHS="${PDF_TOOLS_CHROME_PATHS-/Applications/Google Chrome.app/Contents/MacOS/Google Chrome:${HOME}/Applications/Google Chrome.app/Contents/MacOS/Google Chrome:/Applications/Chromium.app/Contents/MacOS/Chromium:/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge}"
+CHROME_COMMANDS="google-chrome google-chrome-stable chromium chromium-browser microsoft-edge"
+
+json_str() { printf '%s' "$1" | jq -Rsa .; }
+err_json() { printf '{"success":false,"error":%s}\n' "$(json_str "$1")"; exit 1; }
+needs_setup() {
+  # needs_setup <message> <missing...>
+  local msg="$1"; shift
+  jq -cn --arg e "$msg" --arg s "$SKILL_ID" --args '{success:false,error:$e,needsSetup:true,skill:$s,missing:$ARGS.positional,
+    hint:("Run install-skill --id " + $s + " (installs in the background and messages you when done), then retry.")}' "$@"
+  exit 1
+}
+
+command -v jq >/dev/null 2>&1 || {
+  printf '{"success":false,"error":"jq is required but not installed","needsSetup":true,"skill":"%s","missing":["jq"]}\n' "$SKILL_ID"; exit 1; }
+
+# ── Input: JSON argument, --file <path>, or stdin ────────────────────────────────
+INPUT=""
+if [ "${1:-}" = "--file" ] && [ -n "${2:-}" ]; then
+  [ -f "$2" ] || err_json "File not found: $2"
+  INPUT="$(cat "$2")"
+elif [ -n "${1:-}" ]; then
+  INPUT="$1"
+elif [ ! -t 0 ]; then
+  INPUT="$(cat)"
+fi
+[ -z "$INPUT" ] && err_json "Usage: execute.sh '{\"action\":\"render\",\"input\":\"/tmp/report.md\"}' (actions: render, merge, read, info, check)"
+printf '%s' "$INPUT" | jq -e 'type == "object"' >/dev/null 2>&1 || err_json "input must be a JSON object"
+
+field() { printf '%s' "$INPUT" | jq -r "$1 // empty"; }
+ACTION="$(field .action)"; [ -z "$ACTION" ] && ACTION="render"
+
+WORK="$(mktemp -d "${TMPDIR:-/tmp}/pdf-tools-XXXXXX")"
+trap 'rm -rf "$WORK"' EXIT
+
+# ── Tool discovery ────────────────────────────────────────────────────────────────
+# Python with the skill's packages: override → skill venv → system python3
+# (stdlib only; enough for `read` via pdftotext).
+python_bin() {
+  if [ -n "${PDF_TOOLS_PYTHON:-}" ]; then echo "$PDF_TOOLS_PYTHON"; return; fi
+  if [ -x "$VENV_PYTHON" ]; then echo "$VENV_PYTHON"; return; fi
+  command -v python3 2>/dev/null || true
+}
+py_has() { local py; py="$(python_bin)"; [ -n "$py" ] && "$py" -c "import $1" >/dev/null 2>&1; }
+
+find_chrome() {
+  if [ -n "${CHROME_BIN:-}" ]; then [ -x "$CHROME_BIN" ] && echo "$CHROME_BIN"; return; fi
+  local IFS=':' p c
+  for p in $CHROME_APP_PATHS; do [ -n "$p" ] && [ -x "$p" ] && { echo "$p"; return; }; done
+  IFS=' '
+  for c in $CHROME_COMMANDS; do command -v "$c" >/dev/null 2>&1 && { command -v "$c"; return; }; done
+}
+
+weasy_available() { py_has weasyprint || command -v weasyprint >/dev/null 2>&1; }
+
+file_url() { printf 'file://%s' "$(printf '%s' "$1" | jq -sRr @uri | sed 's/%2F/\//g')"; }
+
+abs_path() { case "$1" in /*) printf '%s' "$1" ;; *) printf '%s/%s' "$(pwd)" "$1" ;; esac; }
+
+is_pdf() { [ -s "$1" ] && [ "$(head -c 4 "$1")" = "%PDF" ]; }
+
+# ── Engines ───────────────────────────────────────────────────────────────────────
+# A PDF Chrome has finished writing: starts with %PDF, ends with %%EOF.
+pdf_complete() { is_pdf "$1" && tail -c 64 "$1" | grep -q '%%EOF'; }
+
+# Headless print. No --user-data-dir: with a fresh profile dir Chrome 15x on
+# macOS writes the PDF and then never exits. As a guard against any other
+# hang, once the PDF is complete Chrome gets CHROME_EXIT_GRACE_SEC to exit
+# before it is stopped; CHROME_TIMEOUT_SEC bounds the whole run.
+render_chrome() {
+  local html="$1" out="$2" chrome="$3"
+  local args=(--headless=new --disable-gpu --no-pdf-header-footer --no-first-run --no-default-browser-check
+    --disable-extensions --run-all-compositor-stages-before-draw "--print-to-pdf=${out}")
+  # Chrome refuses to run as root without this (servers / containers).
+  [ "$(id -u)" = "0" ] && args+=(--no-sandbox)
+  rm -f "$out"
+  "$chrome" "${args[@]}" "$(file_url "$html")" </dev/null >"${WORK}/cmd.out" 2>&1 &
+  local pid=$! waited=0 done_at=-1
+  while kill -0 "$pid" 2>/dev/null; do
+    if [ "$done_at" -lt 0 ] && pdf_complete "$out"; then done_at=$waited; fi
+    if [ "$waited" -ge "$((CHROME_TIMEOUT_SEC * 2))" ] || { [ "$done_at" -ge 0 ] && [ "$((waited - done_at))" -ge "$((CHROME_EXIT_GRACE_SEC * 2))" ]; }; then
+      kill -9 "$pid" 2>/dev/null || true
+      break
+    fi
+    sleep 0.5
+    waited=$((waited + 1))
+  done
+  wait "$pid" 2>/dev/null || true
+  pdf_complete "$out"
+}
+
+render_weasy() {
+  local html="$1" out="$2" py
+  py="$(python_bin)"
+  if [ -n "$py" ] && "$py" -c "import weasyprint" >/dev/null 2>&1; then
+    "$py" "$HELPER" weasyprint "$html" "$out" >"${WORK}/weasy.out" 2>&1 || true
+  elif command -v weasyprint >/dev/null 2>&1; then
+    weasyprint "$html" "$out" >"${WORK}/weasy.out" 2>&1 || true
+  fi
+  is_pdf "$out"
+}
+
+# html_to_pdf <html> <out> → sets USED_ENGINE
+USED_ENGINE=""
+html_to_pdf() {
+  local html="$1" out="$2" engine="$3" chrome
+  chrome="$(find_chrome || true)"
+  if [ "$engine" != "weasyprint" ] && [ -n "$chrome" ]; then
+    if render_chrome "$html" "$out" "$chrome"; then USED_ENGINE="chrome"; return 0; fi
+    [ "$engine" = "chrome" ] && err_json "Chrome failed to print ${html}: $(tail -c 300 "${WORK}/cmd.out" 2>/dev/null)"
+    echo '{"status":"fallback","message":"Chrome failed; trying WeasyPrint"}' >&2
+  elif [ "$engine" = "chrome" ]; then
+    needs_setup "engine=chrome requested but no Chrome/Chromium was found (set CHROME_BIN or install Chrome)" chrome
+  fi
+  if weasy_available; then
+    if render_weasy "$html" "$out"; then USED_ENGINE="weasyprint"; return 0; fi
+    err_json "WeasyPrint failed to render ${html}: $(tail -c 400 "${WORK}/weasy.out" 2>/dev/null)"
+  fi
+  needs_setup "No PDF engine is available: no Chrome/Chromium and no working WeasyPrint" chrome weasyprint-libs
+}
+
+# md_to_html <md> <html> <title> — relative images resolve from the Markdown's
+# own directory through a <base href>, so nothing is written next to it.
+md_to_html() {
+  local md="$1" html="$2" title="$3" py base
+  base="$(file_url "$(dirname "$md")")/"
+  local args=("$HELPER" md2html "$md" "$html" --lang "$LANG_ATTR" --base "$base")
+  [ -n "$title" ] && args+=(--title "$title")
+  [ -f "$DEFAULT_CSS" ] && args+=(--css "$DEFAULT_CSS")
+  [ -n "$EXTRA_CSS" ] && args+=(--css "$EXTRA_CSS")
+  py="$(python_bin)"
+  if [ -n "$py" ] && "$py" -c "import markdown" >/dev/null 2>&1; then
+    "$py" "${args[@]}" >"${WORK}/md.out" 2>&1 || err_json "Markdown conversion failed: $(tail -c 300 "${WORK}/md.out")"
+  elif command -v pandoc >/dev/null 2>&1; then
+    local body; body="$(pandoc -f gfm -t html "$md")" || err_json "pandoc failed on ${md}"
+    {
+      printf '<!DOCTYPE html>\n<html lang="%s"><head><meta charset="utf-8"><base href="%s"><title>%s</title><style>\n' "$LANG_ATTR" "$base" "$title"
+      [ -f "$DEFAULT_CSS" ] && cat "$DEFAULT_CSS"
+      [ -n "$EXTRA_CSS" ] && cat "$EXTRA_CSS"
+      printf '\n</style></head>\n<body><main class="doc">\n%s\n</main></body></html>\n' "$body"
+    } > "$html"
+  else
+    needs_setup "Markdown needs python-markdown (pdf-tools venv) or pandoc" python-packages
+  fi
+}
+
+# Copy an HTML file into the work dir with the default stylesheet (and the
+# optional extra css) added first, so the document's own rules still win.
+# A <base href> keeps its relative links pointing at the original directory.
+style_html() {
+  local src="$1" dest="$2"
+  {
+    printf '<base href="%s/">\n<style>\n' "$(file_url "$(dirname "$src")")"
+    cat "$DEFAULT_CSS"
+    [ -n "$EXTRA_CSS" ] && cat "$EXTRA_CSS"
+    printf '\n</style>\n'
+    cat "$src"
+  } > "$dest"
+}
+
+run_helper() {
+  local py; py="$(python_bin)"
+  [ -n "$py" ] || needs_setup "python3 is not installed" python3
+  "$py" "$HELPER" "$@"
+}
+
+# ── Actions ───────────────────────────────────────────────────────────────────────
+EXTRA_CSS="$(field .css)"
+[ -n "$EXTRA_CSS" ] && [ ! -f "$EXTRA_CSS" ] && err_json "css file not found: ${EXTRA_CSS}"
+LANG_ATTR="$(field .lang)"; [ -z "$LANG_ATTR" ] && LANG_ATTR="zh"
+
+case "$ACTION" in
+  render)
+    ENGINE="$(field .engine)"; [ -z "$ENGINE" ] && ENGINE="auto"
+    case "$ENGINE" in auto|chrome|weasyprint) ;; *) err_json "engine must be auto, chrome or weasyprint (got: ${ENGINE})" ;; esac
+    TITLE="$(field .title)"
+    ADD_STYLE="$(printf '%s' "$INPUT" | jq -r '.addDefaultStyle // false')"
+    PARTS=()
+    while IFS= read -r p; do [ -n "$p" ] && PARTS+=("$p"); done < <(printf '%s' "$INPUT" | jq -r 'if (.inputs|type) == "array" then .inputs[] else (.input // empty) end')
+    [ ${#PARTS[@]} -eq 0 ] && err_json "input (a .md/.html file) or inputs (a list of .md/.html/.pdf parts) is required"
+    OUTPUT="$(field .output)"
+    if [ -z "$OUTPUT" ]; then
+      [ ${#PARTS[@]} -gt 1 ] && err_json "output is required when rendering several parts"
+      OUTPUT="${PARTS[0]%.*}.pdf"
+    fi
+    OUTPUT="$(abs_path "$OUTPUT")"
+    mkdir -p "$(dirname "$OUTPUT")"
+    PDF_PARTS=(); ENGINES=()
+    i=0
+    for part in "${PARTS[@]}"; do
+      i=$((i + 1))
+      [ -f "$part" ] || err_json "input not found: ${part}"
+      part="$(abs_path "$part")"
+      case "$(printf '%s' "${part##*.}" | tr '[:upper:]' '[:lower:]')" in
+        md|markdown)
+          html="${WORK}/part-${i}.html"
+          part_title="$TITLE"; [ -z "$part_title" ] && part_title="$(basename "${part%.*}")"
+          md_to_html "$part" "$html" "$part_title"
+          ;;
+        html|htm)
+          html="$part"
+          if [ "$ADD_STYLE" = "true" ]; then
+            html="${WORK}/part-${i}.html"
+            style_html "$part" "$html"
+          fi
+          ;;
+        pdf) PDF_PARTS+=("$part"); ENGINES+=("pdf"); continue ;;
+        *) err_json "unsupported input type: ${part} (use .md, .html or .pdf)" ;;
+      esac
+      out="${WORK}/part-${i}.pdf"; [ ${#PARTS[@]} -eq 1 ] && out="$OUTPUT"
+      html_to_pdf "$html" "$out" "$ENGINE"
+      PDF_PARTS+=("$out"); ENGINES+=("$USED_ENGINE")
+    done
+    if [ ${#PARTS[@]} -gt 1 ] || [ "${PDF_PARTS[0]}" != "$OUTPUT" ]; then
+      MERGED="$(run_helper merge "$OUTPUT" "${PDF_PARTS[@]}" 2>&1)" || {
+        printf '%s' "$MERGED" | jq -e .needsSetup >/dev/null 2>&1 && { printf '%s\n' "$MERGED"; exit 1; }
+        err_json "merging the parts failed: $(printf '%s' "$MERGED" | tail -c 300)"
+      }
+    fi
+    is_pdf "$OUTPUT" || err_json "no PDF was produced at ${OUTPUT}"
+    SIZE=$(wc -c < "$OUTPUT" | tr -d ' ')
+    jq -cn --arg pdf "$OUTPUT" --argjson size "$SIZE" --argjson parts "${#PARTS[@]}" \
+      --arg engines "$(IFS=,; echo "${ENGINES[*]}")" \
+      '{success:true, pdf:$pdf, size:$size, parts:$parts, engine:($engines | split(",") | unique | map(select(. != "pdf")) | join(","))}'
+    ;;
+
+  merge)
+    OUTPUT="$(field .output)"; [ -z "$OUTPUT" ] && err_json "output is required"
+    INPUTS=()
+    while IFS= read -r p; do [ -n "$p" ] && INPUTS+=("$p"); done < <(printf '%s' "$INPUT" | jq -r '(.inputs // [])[]')
+    [ ${#INPUTS[@]} -lt 2 ] && err_json "inputs must list at least two PDFs"
+    for p in "${INPUTS[@]}"; do is_pdf "$p" || err_json "not a PDF: ${p}"; done
+    mkdir -p "$(dirname "$OUTPUT")"
+    run_helper merge "$OUTPUT" "${INPUTS[@]}"
+    ;;
+
+  read)
+    IN="$(field .input)"; [ -z "$IN" ] && err_json "input (a PDF path) is required"
+    is_pdf "$IN" || err_json "not a PDF (or empty): ${IN}"
+    ARGS=(read "$IN")
+    PAGES="$(field .pages)"; [ -n "$PAGES" ] && ARGS+=(--pages "$PAGES")
+    MAXC="$(field .maxChars)"; [ -n "$MAXC" ] && ARGS+=(--max-chars "$MAXC")
+    TF="$(field .textFile)"; [ -n "$TF" ] && ARGS+=(--text-file "$TF")
+    run_helper "${ARGS[@]}"
+    ;;
+
+  info)
+    IN="$(field .input)"; [ -z "$IN" ] && err_json "input (a PDF path) is required"
+    is_pdf "$IN" || err_json "not a PDF (or empty): ${IN}"
+    run_helper info "$IN"
+    ;;
+
+  check)
+    CHROME="$(find_chrome || true)"
+    PY="$(python_bin)"
+    jq -cn --arg chrome "$CHROME" --arg python "$PY" \
+      --argjson weasy "$(weasy_available && echo true || echo false)" \
+      --argjson pypdf "$(py_has pypdf && echo true || echo false)" \
+      --argjson markdown "$(py_has markdown && echo true || echo false)" \
+      --argjson pdftotext "$(command -v pdftotext >/dev/null 2>&1 && echo true || echo false)" \
+      '{success:true, chrome:(if $chrome == "" then null else $chrome end), python:(if $python == "" then null else $python end),
+        weasyprint:$weasy, pypdf:$pypdf, markdown:$markdown, pdftotext:$pdftotext,
+        canRender:(($chrome != "") or $weasy), canRead:($pypdf or $pdftotext), canMerge:$pypdf}'
+    ;;
+
+  *) err_json "unknown action: ${ACTION} (use render, merge, read, info or check)" ;;
+esac