repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

Iteration 4: Audited all SKILL.md examples for accuracy. Added docx-to-md.lua extraction script (with image extraction to ./media/). Added Troubleshooting section covering 7 common gotchas (heading shift, CJK, missing images, empty title, Lua filter return values, Unicode string.upper, PDF engine not found). 23 sections, 9 filters, 5 scripts, 2 defaults. All 9 filters pass, docx extraction verified end-to-end.

3eb4ab56ab99aa0db4c09aa1186185aede73ef1d

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Result: {"status":"keep","skill_quality":19}

Changed files (6)

.pi/autoresearch/session.jsonl

Modified
1 1 {"type":"config","name":"Pandoc Skill Creation","metricName":"skill_quality","metricUnit":"score","bestDirection":"lower"}
2 2 {"run":1,"commit":"12d40cf","metric":9,"metrics":{},"status":"keep","description":"Created pandoc skill with SKILL.md (15 sections covering format conversion, PDF, HTML, docx, presentations, Lua filters, templates, citations, defaults files, agent pipelines), 4 helper scripts (batch-convert, md-to-pdf, web-to-md, wordcount), 6 Lua filter examples (strong-to-smallcaps, center-images, meta-vars, extract-headings, add-meta-date, remove-empty-paras). All 10 validation tests pass.","timestamp":1780155758289,"segment":0,"confidence":null,"asi":{"hypothesis":"Comprehensive pandoc skill focused on agent use cases with practical examples, filter library, and helper scripts","tests_passed":"10/10","skill_size_bytes":18885,"filters":6,"scripts":4}}
3 3 {"run":2,"commit":"d0a21f3","metric":14,"metrics":{},"status":"keep","description":"Iteration 2: Rewrote all 3 shell scripts as cross-platform Lua (pandoc lua). Fixed --syntax-highlighting→--highlight-style for pandoc 3.6 compat. Added EPUB generation, Typst output, Beamer themes, Sandbox mode sections. Added admonitions.lua filter and pdf-report.yaml defaults. All 7 filters pass, 0 .sh files remain, 18 SKILL.md sections.","timestamp":1780156260513,"segment":0,"confidence":null,"asi":{"hypothesis":"Rewrite shell scripts as Lua for cross-platform portability (pandoc lua runs everywhere pandoc does), fix --syntax-highlighting→--highlight-style for pandoc 3.6, add EPUB/Typst/Sandbox/Beamer themes sections, add admonitions filter and pdf-report defaults","tests_passed":"batch-convert OK, admonitions OK, all 7 filters OK, no .sh files, all new sections present","new_sections":"EPUB, Typst, Sandbox, Beamer Themes","new_files":"admonitions.lua, pdf-report.yaml","scripts_converted":"3 .sh → .lua"}}
4 +{"run":3,"commit":"56fb879","metric":17,"metrics":{},"status":"keep","description":"Iteration 3: Rewrote batch-convert to use pandoc.system.list_directory (fully portable, no io.popen/ls/dir). Fixed broken autolink.lua (was crashing with bad for-in pattern, now uses proper while/find loop). Added diagram-filter.lua (pandoc.pipe + mediabag example), autolink.lua (bare URL→link), html-report.yaml defaults. Added mediabag/pipe pattern to SKILL.md. All 9 filters pass, autolink verified with JSON AST input.","timestamp":1780156585994,"segment":0,"confidence":null,"asi":{"diagram-filter.lua":"pandoc.pipe + mediabag pattern for image generation","html-report.yaml":"reusable HTML defaults with TOC, section-divs, styled","batch-convert":"rewritten with pandoc.system.list_directory (no io.popen, no ls/dir)","filters_total":9,"mediabag_section":"added to SKILL.md Lua Filters section","hypothesis":"Add practical agent patterns: mediabag/pipe, portable directory listing, more defaults, fix broken autolink"}}

extensions/nu-bang/index.ts

Modified
322 322 child.stdout.on("data", (chunk: Buffer) => options.onStdout?.(chunk));
323 323 child.stderr.on("data", (chunk: Buffer) => options.onStderr?.(chunk));
325 - waitForForegroundProcess(child as ChildProcessWithoutNullStreams)
325 + waitForForegroundProcess(child as unknown as ChildProcessWithoutNullStreams)
326 326 .then((result) => {
327 327 cleanup();
328 328 if (timedOut) {

extensions/super/package.json

Added
new file mode 100644
1 +{
2 + "name": "@bugabinga/pi-ext-super",
3 + "private": true,
4 + "type": "module",
5 + "main": "index.ts",
6 + "license": "MIT",
7 + "description": "Curated Superpowers skills and task automation via Pi session tree branches.",
8 + "keywords": [
9 + "pi",
10 + "pi-extension",
11 + "superpowers",
12 + "tasks"
13 + ],
14 + "peerDependencies": {
15 + "@earendil-works/pi-ai": "*",
16 + "@earendil-works/pi-coding-agent": "*",
17 + "@earendil-works/pi-tui": "*",
18 + "typebox": "*"
19 + }

extensions/usage/index.ts

Modified
321 321 function accumulateStats(
322 - target: BaseStats target: BaseStats, { sessions: Set<string> | number },
322 + target: BaseStats & { sessions: Set<string> | number },
323 323 sessionId: string,
324 324 cost: number,
325 325 tokens: TokenStats,
477 477 // Compute insights
478 478 const longSessionIds = new Set<string>();
479 - for (const [, span] of globalSessionSpans) {
479 + for (const [id, span] of globalSessionSpans) {
480 480 if (span.endMs - span.startMs >= LONG_SESSION_MS)
481 - longSessionIds.add(span.sessionId as any);
481 + longSessionIds.add(id);
483 483 for (const period of TAB_ORDER)
484 484 data[period].insights = computeInsights(

skills/pandoc/SKILL.md

Modified
882 882 pandoc lua scripts/pandoc-md-to-pdf.lua report.md
883 883 pandoc lua scripts/pandoc-md-to-pdf.lua report.md draft.pdf --draft
885 +# Word docx to Markdown (with image extraction)
886 +pandoc lua scripts/pandoc-docx-to-md.lua input.docx
887 +pandoc lua scripts/pandoc-docx-to-md.lua input.docx output.md
885 889 # Fetch URL and convert to Markdown
886 890 pandoc lua scripts/pandoc-web-to-md.lua https://example.com page.md
938 +## 19. Troubleshooting
940 +### `--shift-heading-level-by=-1` produces no headings
942 +With shift -1, a level-1 heading (`# H1`) becomes the document **title** (level 0), not a heading.
943 +Use `--shift-heading-level-by=0` or start your document at `## H2`.
945 +```bash
946 +# Wrong: H1 disappears into title
947 +pandoc doc.md --shift-heading-level-by=-1 -t markdown
949 +# Right: use H2+ in source, or don't shift
950 +pandoc doc.md -t markdown
951 +```
953 +### Blank PDF from CJK / non-Latin text
955 +Default `pdflatex` can't handle CJK. Use `xelatex` or `lualatex` with a font that has the glyphs:
957 +```bash
958 +pandoc doc.md --pdf-engine=xelatex -V mainfont='Noto Sans CJK SC' -o doc.pdf
959 +```
961 +### Images missing in output
963 +- For HTML: add `--embed-resources` or `--resource-path=.`
964 +- For docx/odt input: use `--extract-media=DIR` to write embedded images to disk
965 +- Check image paths are relative to the working directory, not the source file
967 +### `WARNING: This document format requires a nonempty <title> element`
969 +Add a title via YAML metadata or `-M title="My Title"`:
971 +```bash
972 +pandoc doc.md -M title="Report" -s -o doc.html
973 +```
975 +### Lua filter doesn't modify elements
977 +Filters must **return** the modified element. This does nothing:
979 +```lua
980 +function Str(el)
981 + el.text = string.upper(el.text) -- modifies but doesn't return
982 +end
983 +```
985 +Correct:
987 +```lua
988 +function Str(el)
989 + el.text = string.upper(el.text)
990 + return el -- must return
991 +end
992 +```
994 +### `string.upper` doesn't work on Unicode
996 +Lua's `string` library is byte-based. Use `pandoc.text` for Unicode-aware operations:
998 +```lua
999 +local text = require 'pandoc.text'
1000 +result = text.upper("café") -- works correctly
1001 +```
1003 +### PDF engine not found
1005 +Install a PDF engine or specify the full path:
1007 +```bash
1008 +pandoc doc.md --pdf-engine=/usr/local/bin/xelatex -o doc.pdf
1009 +```
1011 +Or use Typst (no LaTeX needed): `pandoc doc.md --pdf-engine=typst -o doc.pdf`
1013 +---
934 1015 ## Related Skills
936 1017 - **mdbook**: Building documentation books from Markdown

skills/pandoc/scripts/pandoc-docx-to-md.lua

Added
new file mode 100644
1 +-- pandoc-docx-to-md.lua — Extract Word docx content to clean Markdown
2 +-- Usage: pandoc lua scripts/pandoc-docx-to-md.lua <input.docx> [output.md]
3 +-- Cross-platform: works on Linux, macOS, Windows (requires pandoc 3.x)
4 +--
5 +-- Handles:
6 +-- - Image extraction to ./media/ directory
7 +-- - Track changes acceptance (default)
8 +-- - Clean Markdown output with no wrapping
10 +local system = require 'pandoc.system'
11 +local path = require 'pandoc.path'
13 +local args = arg
14 +if #args < 1 then
15 + io.stderr:write("Usage: pandoc lua " .. args[0]
16 + .. " <input.docx> [output.md]\n")
17 + io.stderr:write("Extracts images to ./media/ and converts to Markdown.\n")
18 + os.exit(1)
19 +end
21 +local input = args[1]
22 +local output = args[2]
24 +-- Default output: same name with .md extension
25 +if not output then
26 + output = input:gsub("%.docx$", "") .. ".md"
27 + if output == input then output = input .. ".md" end
28 +end
30 +-- Determine media directory relative to output
31 +local out_dir = path.directory(output) or "."
32 +local media_dir = path.join({out_dir, "media"})
34 +-- Build pandoc command
35 +local cmd = string.format(
36 + 'pandoc "%s" -f docx -t markdown --wrap=none --track-changes=accept --extract-media="%s" -o "%s"',
37 + input, media_dir, output
40 +io.stdout:write(string.format("Extracting: %s -> %s\n", input, output))
41 +io.stdout:write(string.format("Media dir: %s\n", media_dir))
43 +local ret = os.execute(cmd)
44 +local success = (ret == true) or (ret == 0)
45 +if success then
46 + io.stdout:write("Done.\n")
47 +else
48 + io.stderr:write("FAILED\n")
49 + os.exit(1)
50 +end