typeclaw 0.31.1 → 0.32.1

package/src/skills/typeclaw-markdown-pdf/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: typeclaw-markdown-pdf
-description: "Turn any Markdown into a polished, professional PDF and (optionally) attach it to a channel. Load this whenever you need to deliver a document as a PDF rather than raw markdown — reports, summaries, briefs, meeting notes, docs, anything a human would want to download, print, or forward. Triggers: 'make a PDF', 'export to PDF', 'markdown to PDF', 'PDF report', 'attach the report', 'send me a PDF', 'as a PDF', 'turn this into a document', a researcher/subagent result you want to ship as a file, 'PDF로', 'PDF로 만들어', 'PDF로 변환', 'PDF 첨부'. Also load before saying you cannot produce PDFs — you can: this skill installs a tiny Typst toolchain into workspace/ on first use, then renders. Covers the one-time setup, the styled wrapper, the render command, and how to attach the PDF to Slack/Discord/Telegram/KakaoTalk. For operating on EXISTING PDFs (merge, split, extract text, fill forms), this is not the skill — use pypdf/qpdf instead."
+description: "The ONLY supported way to turn Markdown into a polished, professional PDF (and optionally attach it to a channel). Load this whenever you need to deliver a document as a PDF rather than raw markdown — reports, summaries, briefs, meeting notes, docs, render report, export document, anything a human would want to download, print, or forward, including a researcher's report file shipped as a Slack/Discord attachment. Triggers: 'make a PDF', 'export to PDF', 'markdown to PDF', 'PDF report', 'render report', 'export document', 'the report', 'attach the report', 'send me a PDF', 'as a PDF', 'turn this into a document', a researcher/subagent result you want to ship as a file, 'PDF로', 'PDF로 만들어', 'PDF로 변환', 'PDF 첨부', '리포트', '보고서'. Handles CJK/Korean/Japanese/Chinese: CJK fonts are opt-in, so before rendering it checks whether a CJK font is present and, if not, asks the user to enable `docker.file.cjkFonts` and regenerate rather than shipping a tofu PDF — it never auto-downloads a font. Also load before saying you cannot produce PDFs — you can: this skill installs a tiny Typst toolchain into workspace/ on first use, then renders. NEVER build a PDF with jsPDF, pdfkit, a canvas text dump, or a headless-browser raw-text print — those produce unrendered markdown and broken CJK; this skill is the only correct path. Covers the one-time setup, the styled wrapper, the render command, and how to attach the PDF to Slack/Discord/Telegram/KakaoTalk. For operating on EXISTING PDFs (merge, split, extract text, fill forms), this is not the skill — use pypdf/qpdf instead."
 ---
 
 # typeclaw-markdown-pdf
@@ -22,6 +22,15 @@ You do **not** need to learn Typst markup. `cmarker` renders your CommonMark
 wrapper only sets _styling_ — fonts, margins, headings, page numbers — so the
 output looks deliberate, not like a default-template export.
 
+> **This is the only supported way to make a PDF from Markdown in TypeClaw.**
+> Do **not** reach for `jsPDF`, `pdfkit`, a `<canvas>` text dump, or a
+> headless-browser "print raw text" path. Those skip Markdown rendering (you get
+> literal `##` and `**` in the output) and ship no CJK font, so Korean/Japanese/
+> Chinese come out as mojibake. The Typst path below renders the Markdown properly;
+> for CJK it relies on the opt-in `cjkFonts` font and gates on its presence (see
+> "## Handling CJK content") rather than shipping tofu. If you catch yourself about
+> to `bun add` a PDF library, stop and use this skill instead.
+
 ## When to use this
 
 - A research report, brief, or summary the user wants as a downloadable file.
@@ -108,7 +117,7 @@ fonts/margins only if the user asks.
     #counter(page).display("1 / 1", both: true)
   ]),
 )
-#set text(font: ("Libertinus Serif", "New Computer Modern"), size: 11pt, lang: "en")
+#set text(font: ("Libertinus Serif", "New Computer Modern", "Noto Serif CJK KR"), size: 11pt, lang: "en")
 #set par(justify: true, leading: 0.68em, spacing: 1.1em)
 
 #show heading: set text(weight: "semibold")
@@ -136,9 +145,65 @@ Notes:
 - `read("report.md")` is **relative to the workspace** (the compiler's `workspace`
   is set to `workspace/` — see Step 3). Keep the `.typ` and `.md` in `workspace/`.
 - Fonts `Libertinus Serif` / `New Computer Modern` are bundled with Typst (no font
-  install). For Korean/CJK body text, add `"Noto Serif CJK KR"` to the `font:` list
-  and pass that font dir to `fontPaths` in Step 3 (the container's `cjkFonts` toggle
-  installs `fonts-noto-cjk` under `/usr/share/fonts`).
+  install) and carry the Latin text. `"Noto Serif CJK KR"` is appended as the
+  fallback so Korean/CJK glyphs resolve per-glyph — Typst falls through to it
+  wherever the Latin fonts have no glyph, leaving Latin runs untouched. It comes
+  from `fonts-noto-cjk`, which Step 3's renderer loads from `/usr/share/fonts` via
+  `fontPaths`. **The package is only present when the container's `cjkFonts` toggle
+  resolves to `true`** (default `"auto"` installs it only on a CJK host locale), so
+  on a non-CJK host CJK text renders as tofu — see "## Handling CJK content" below
+  for the pre-render check that catches this and asks the user before shipping a
+  broken PDF. If your CJK font lives elsewhere, add its dir to the `fontPaths` list.
+
+## Handling CJK content
+
+CJK fonts are **opt-in** (the `docker.file.cjkFonts` toggle). When they are off,
+Typst still renders — it just substitutes `.notdef` tofu boxes for every
+Korean/Japanese/Chinese glyph, so the render "succeeds" and you can ship a broken
+PDF without noticing. **Do not** download, vendor, or `curl` a font into the
+workspace to work around this, and **do not** silently deliver a tofu PDF. Instead,
+run this gate **before** Step 3 whenever the markdown might contain CJK:
+
+```sh
+# Run from workspace/. MD is the markdown you are about to render.
+MD="report.md"
+
+# Hangul, Kana, CJK ideographs + the common extensions. grep -P on Debian; perl
+# slurp as the fallback (BusyBox/macOS grep lack -P).
+CJK_RE='[\x{1100}-\x{11FF}\x{3130}-\x{318F}\x{AC00}-\x{D7A3}\x{3040}-\x{30FF}\x{31F0}-\x{31FF}\x{3400}-\x{4DBF}\x{4E00}-\x{9FFF}\x{F900}-\x{FAFF}\x{20000}-\x{2A6DF}\x{2A700}-\x{2B73F}\x{2B740}-\x{2B81F}\x{2B820}-\x{2CEAF}\x{2CEB0}-\x{2EBEF}\x{30000}-\x{3134F}]'
+if command -v grep >/dev/null && echo | grep -qP '' 2>/dev/null; then
+  LC_ALL=C.UTF-8 grep -qP "$CJK_RE" -- "$MD" && HAS_CJK=1 || HAS_CJK=0
+else
+  perl -CSDA -0777 -ne "exit(/$CJK_RE/ ? 0 : 1)" "$MD" && HAS_CJK=1 || HAS_CJK=0
+fi
+
+# A CJK font Typst can load. dpkg is the authoritative signal for the opt-in
+# fonts-noto-cjk package; the file scan covers a preinstalled or mounted font.
+# fontconfig/fc-list is NOT consulted — Typst reads fontPaths directly, not fc.
+has_cjk_font() {
+  dpkg-query -W -f='${Status}' fonts-noto-cjk 2>/dev/null | grep -q 'install ok installed' && return 0
+  find /usr/share/fonts /usr/local/share/fonts -type f \( -iname '*.otf' -o -iname '*.ttf' -o -iname '*.ttc' \) 2>/dev/null |
+    grep -Eiq '(Noto(Sans|Serif)CJK|Noto (Sans|Serif) CJK|SourceHan|Source Han|WenQuanYi|Nanum|Unifont|DroidSansFallback|AR PL)'
+}
+
+if [ "$HAS_CJK" = 1 ] && ! has_cjk_font; then
+  echo "CJK_FONT_MISSING"
+fi
+```
+
+If the gate prints `CJK_FONT_MISSING`, **stop — do not render or attach a PDF.**
+Tell the user, honestly, that this is a restart-required boot setting, e.g.:
+
+> This report has Korean/Japanese/Chinese text, but the container has no CJK font
+> — they're opt-in, so the PDF would come out as tofu boxes. Want me to set
+> `docker.file.cjkFonts: true` in `typeclaw.json`? It's a boot setting, so after I
+> edit it you'll need to run `typeclaw restart` from the host project directory,
+> and then I'll regenerate the PDF.
+
+Only after the user agrees: edit `typeclaw.json` to set `docker.file.cjkFonts:
+true` (use the `typeclaw-config` skill), ask them to `typeclaw restart`, and
+regenerate the PDF **after** the restarted container reports `has_cjk_font` true.
+If the markdown has no CJK, or a CJK font is present, skip straight to Step 3.
 
 ## Step 3 — render
 
@@ -149,15 +214,23 @@ writes the PDF. Pass the wrapper and output paths as arguments.
 ```ts
 // workspace/.tools/render.ts
 import { NodeCompiler } from '@myriaddreamin/typst-ts-node-compiler'
-import { writeFileSync } from 'node:fs'
+import { existsSync, writeFileSync } from 'node:fs'
 
 const [, , mainFile, outFile] = process.argv
 if (!mainFile || !outFile) throw new Error('usage: render.ts <main.typ> <out.pdf>')
 
+// Load system fonts so CJK glyphs resolve. The compiler does NOT auto-discover
+// system font dirs the way the Typst CLI does — without explicit fontPaths,
+// "Noto Serif CJK KR" (from fonts-noto-cjk under /usr/share/fonts) is invisible
+// and Korean/Japanese/Chinese text renders as .notdef tofu boxes. Filtered with
+// existsSync so a missing dir (e.g. on a dev/host run) is skipped, not fatal.
+const fontPaths = ['/usr/share/fonts', '/usr/local/share/fonts', '/Library/Fonts', '/System/Library/Fonts'].filter(
+  existsSync,
+)
+
 const compiler = NodeCompiler.create({
   workspace: '.', // run from workspace/, so read("report.md") resolves
-  // Add CJK / extra font dirs here if needed:
-  // fontArgs: [{ fontPaths: ["/usr/share/fonts"] }],
+  ...(fontPaths.length > 0 ? { fontArgs: [{ fontPaths }] } : {}),
 })
 const pdf = compiler.pdf({ mainFilePath: mainFile })
 writeFileSync(outFile, Buffer.from(pdf))