Flan246/dsh-latex-guard

LaTeX compile check and BibTeX lint/fill/audit tools for DeepSeek Harness and any agent.

Features

• check — compile a LaTeX project with latexmk and return a structured report of errors, warnings and undefined citations
• bib-lint — dedupe entry keys, check required fields per entry type, canonicalize formatting
• bib-fill — fill missing entry fields from Crossref by DOI or title (never overwrites existing values)
• cite-audit — compare citation keys in .tex files against a .bib file: cited-but-missing and never-cited entries. Recognized commands: \cite, \citep, \citet, \parencite, \textcite, and the biblatex commands \autocite, \footcite, \fullcite, \nocite (a \nocite key counts as cited).

All commands return human-readable output by default and structured JSON with --json. Exit codes: 0 success, 1 business error, 2 usage error. A check that compiles but reports status: "failed" also exits 1; a skipped check (latexmk unavailable) exits 0, since graceful degradation is not an error.

Usage

1. As a dsh plugin

dsh plugin add dsh-latex-guard

Registers four agent tools: latex_check, bib_lint, bib_fill, cite_audit.

2. As a standalone CLI

npx dsh-latex-guard check <dir> <entry.tex> [--engine <name>] [--json]
npx dsh-latex-guard bib-lint <file.bib> [--write]
npx dsh-latex-guard bib-fill <file.bib> [--write]
npx dsh-latex-guard cite-audit <file.bib> <tex...>

--write modifies the bib in place — confirm before using it. As a safety net, both write paths refuse to write when the bib cannot be fully parsed (e.g. an entry missing its closing brace), instead of silently dropping the unparseable tail.

check --engine <name> selects the latexmk engine: auto (default), pdflatex, xelatex or lualatex. In auto mode the engine is detected from the entry tex (and a local \documentclass file): a % !TeX program = ... magic comment, \RequireXeTeX, xeCJK or {ctex select xelatex, \RequireLuaTeX selects lualatex, otherwise pdflatex. The report's engine field records the engine actually used; when a compile fails without any parseable error line, the report also carries a logTail with the last lines of the latexmk log.

Known limitations

• cite-audit counts \cite keys inside commented-out (% ...) lines as real citations.
• A passed check report may still carry citation warnings emitted by latexmk's intermediate passes; only the final pass reflects the true citation state.

3. As an agent skill

The skill/SKILL.md bundled in this package teaches any SKILL.md-compatible agent how to drive the CLI.

latexmk dependency

check requires a TeX installation providing latexmk on PATH (e.g. TeX Live or MiKTeX). When latexmk is not found, check degrades gracefully: it returns a report with skipped: true instead of failing, so the other three commands (pure BibTeX/text processing, no TeX needed) remain fully usable.

bib-fill is the only command that needs network access (Crossref API, 10s timeout, one retry).

License

MIT