laporan-generator 2.6.1

package/.agents/skills/laporan-generator/references/troubleshooting.md

@@ -0,0 +1,105 @@
+# Panduan Penanganan Masalah (Troubleshooting)
+
+Dokumen ini berisi daftar masalah umum, kode kesalahan, dan solusi langkah-demi-langkah saat menjalankan **Laporan Generator**.
+
+---
+
+## 1. ImageMagick Security Policy Error
+
+### Gejala Error:
+```text
+convert-im6.q16: attempt to perform an operation not allowed by the security policy 'PDF'
+```
+
+### Penyebab:
+Kebijakan keamanan default ImageMagick pada beberapa distribusi Linux (seperti Ubuntu/Debian) membatasi pemrosesan berkas PDF/PNG untuk mencegah kerentanan keamanan.
+
+### Solusi:
+1. Buka file kebijakan ImageMagick dengan hak akses sudo:
+   ```bash
+   sudo nano /etc/ImageMagick-6/policy.xml
+   # atau untuk ImageMagick 7:
+   sudo nano /etc/ImageMagick-7/policy.xml
+   ```
+2. Cari baris berikut:
+   ```xml
+   <policy domain="coder" rights="none" pattern="PDF" />
+   ```
+3. Ubah `rights="none"` menjadi `rights="read|write"`:
+   ```xml
+   <policy domain="coder" rights="read|write" pattern="PDF" />
+   ```
+4. Simpan file (`Ctrl+O`, `Enter`) lalu keluar (`Ctrl+X`).
+
+---
+
+## 2. Font Tidak Ditemukan (Missing Font)
+
+### Gejala Error:
+```text
+warning: font 'Nimbus Serif' not found, falling back to default
+warning: failed to resolve font 'Times New Roman'
+```
+
+### Penyebab:
+Font yang disebutkan di dalam `template.typ` tidak tersedia. Typst hanya memakai font yang dibundel di binary-nya (termasuk Libertinus Serif dan DejaVu Sans Mono) plus font yang terinstall di sistem.
+
+### Solusi:
+1. Gunakan font bawaan Typst: `Libertinus Serif`, `DejaVu Sans Mono`, atau `New Computer Modern`.
+2. Jika ingin font sistem lain, pastikan font tersebut sudah terinstall di OS/container.
+3. Cek daftar font yang tersedia:
+   ```bash
+   typst fonts
+   ```
+
+---
+
+## 3. Syntax Error Raw Typst di cover.md
+
+### Gejala Error:
+```text
+error: expected `)`, found `]`
+  ┌─ cover.md:5:1
+```
+
+### Penyebab:
+Blok raw Typst di dalam `cover.md` (diapit ``` ```typst ```) memiliki kesalahan sintaks. Contoh yang sering terjadi: `block(align: center)` (tidak valid di Typst, gunakan `align(center)[block(...)]`) atau `ns.first()` (dihapus sejak Typst 0.13, gunakan `ns.at(0)`).
+
+### Solusi:
+Periksa pesan error Typst yang menyebutkan posisi baris, lalu perbaiki blok raw di `cover.md` atau konstruksi template di `template.typ`.
+
+---
+
+## 4. Citasi "Undefined Reference"
+
+### Gejala Error:
+```text
+[WARNING] Citeproc: citation 'he2016deep' not found
+```
+
+### Penyebab:
+Di dalam Markdown, sintaks sitasi tidak dikenali atau citekey tidak ada di `references.bib`.
+
+### Solusi:
+Gunakan sintaks sitasi Pandoc `[@citekey]` atau `@citekey` di file Markdown:
+- **Salah**: `Menurut \cite{he2016deep}...`
+- **Benar**: `Menurut [@he2016deep]...`
+
+---
+
+## 5. Permission Denied pada Laporan.pdf (Docker Volume)
+
+### Gejala Error:
+```text
+cannot create Laporan.pdf: Permission denied
+```
+
+### Penyebab:
+Container Docker dijalankan sebagai user `root` sehingga menghalangi user lokal untuk mengubah atau menghapus file output.
+
+### Solusi:
+Gunakan perintah `docker compose` yang sudah dikonfigurasi dengan variabel `UID/GID` lokal:
+```bash
+docker compose run --rm laporan-generator
+```
+*(File `docker-compose.yml` pada project ini secara otomatis memetakan `user: "${UID:-1000}:${GID:-1000}"`)*.

package/.agents/skills/laporan-generator/resources/Makefile

@@ -0,0 +1,90 @@
+.PHONY: build clean lint-deps watch docx html crossref test docker-build init view reference-docx
+
+build:
+	./build.sh
+
+init:
+	@git config core.hooksPath .githooks
+	@echo "[OK] Git pre-commit hook berhasil diaktifkan!"
+
+view:
+	@if [ -f Laporan.pdf ]; then \
+		command -v xdg-open >/dev/null 2>&1 && xdg-open Laporan.pdf || open Laporan.pdf || echo "Laporan.pdf ada di: $(shell pwd)/Laporan.pdf"; \
+	else \
+		echo "ERROR: Laporan.pdf belum dibuat. Jalankan 'make build' terlebih dahulu."; \
+		exit 1; \
+	fi
+
+clean:
+	rm -f Laporan.pdf Laporan.docx Laporan.html
+	rm -rf tmp/
+
+lint-deps:
+	@echo "Checking dependencies..."
+	@command -v pandoc >/dev/null 2>&1 || { echo "ERROR: pandoc not found"; exit 1; }
+	@command -v typst >/dev/null 2>&1 || { echo "ERROR: typst not found"; exit 1; }
+	@command -v magick >/dev/null 2>&1 || command -v convert >/dev/null 2>&1 || { echo "ERROR: ImageMagick (magick/convert) not found"; exit 1; }
+	@echo "All dependencies OK."
+
+watch:
+	@command -v inotifywait >/dev/null 2>&1 || { echo "ERROR: inotifywait not found. Install inotify-tools."; exit 1; }
+	@echo "Watching for changes... (Ctrl+C to stop)"
+	@while true; do \
+		inotifywait -r -e modify -e create -e delete . \
+			--exclude '(Laporan\.pdf|tmp/|\.git/|\.pdf)' 2>/dev/null; \
+		./build.sh; \
+	done
+
+docx:
+	./build-docx.sh
+
+
+reference-docx:
+	@command -v pandoc >/dev/null 2>&1 || { echo "ERROR: pandoc not found"; exit 1; }
+	@command -v python3 >/dev/null 2>&1 || { echo "ERROR: python3 not found"; exit 1; }
+	@mkdir -p tmp
+	pandoc --print-default-data-file reference.docx > tmp/ref-default.docx
+	python3 scripts/make-reference-docx.py tmp/ref-default.docx reference.docx
+	@rm -f tmp/ref-default.docx
+
+html:
+	@if [ ! -d chapters ]; then \
+		echo "ERROR: Direktori chapters/ tidak ditemukan."; \
+		exit 1; \
+	fi; \
+	PRESET=$$(grep -E '^[[:space:]]*(preset|margin_preset):' metadata.yml 2>/dev/null | head -n 1 | cut -d: -f2- | tr -d '\"'\''\r\n '); \
+	PRESET_FILE=""; \
+	if [ -n "$$PRESET" ] && [ -f "presets/$${PRESET}.yml" ]; then \
+		PRESET_FILE="--metadata-file=presets/$${PRESET}.yml"; \
+	elif [ -f "presets/standard.yml" ]; then \
+		PRESET_FILE="--metadata-file=presets/standard.yml"; \
+	fi; \
+	pandoc chapters/bab*.md \
+		$$PRESET_FILE \
+		--metadata-file=metadata.yml \
+		--citeproc --bibliography=references.bib \
+		--csl=apa.csl \
+		--metadata=reference-section-title="DAFTAR PUSTAKA" \
+		--top-level-division=chapter \
+		--standalone --toc \
+		-o Laporan.html 2>&1
+
+crossref:
+	@command -v pandoc-crossref >/dev/null 2>&1 || { \
+		echo "ERROR: pandoc-crossref not found."; \
+		echo "Install: https://github.com/lierdakil/pandoc-crossref"; \
+		exit 1; \
+	}
+	CITEPROC_OPTS="--filter pandoc-crossref" ./build.sh
+
+test:
+	./test.sh
+
+docker-build:
+	docker compose build
+
+docker-run:
+	docker compose run --rm laporan-generator
+
+docker-watch:
+	docker compose run --rm watch