Skip to content
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions skills/office-docx/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
---
name: office-docx
description: "PREVIEW / dark-launched. Native .docx generation with Python python-docx (real Heading styles, explicit fonts/sizes, tables, page structure), plus reading/parsing existing documents. NOT the default Word path — for a normal Word doc / report / letter / memo request keep using officecli-docx. Only use office-docx when the user (or an experiment) explicitly asks for the python-docx / native-Python preview route by name."
---

# office-docx — native DOCX with python-docx (preview)

You build editable `.docx` documents with Python `python-docx`: real Heading styles that drive the navigation pane and table of contents, explicit fonts and sizes, native tables, and clean paragraph structure. You can also read and parse existing documents. No officecli, no LibreOffice.

This is a **dark-launched preview**. It does not replace the default Word path. Only run it when explicitly routed here.

## Runtime contract

- `uv` must be on `PATH`. All Python runs through `uv run`; the runtime injects the package-mirror environment variables so `uv` resolves `python-docx` from the internal mirror. You do not configure the mirror.
- **If `uv` is missing**, stop and report exactly: `office-docx requires 'uv' on PATH, but 'uv --version' failed. This is an environment problem — uv should be provisioned by the PawWork runtime. Do not fall back to system pip or officecli; report the missing uv instead.` Do not attempt `pip install` or any other fallback.
- The skill directory ships read-only inside the app bundle. **Never write into it.** Work in a fresh directory.

`SKILL_DIR` below means the base directory printed when this skill loaded.

```bash
SKILL_DIR="<the base directory shown when this skill loaded>"
uv --version || { echo "office-docx requires 'uv' on PATH (see Runtime contract)"; exit 1; }
mkdir -p work && cp "$SKILL_DIR/pyproject.toml" work/pyproject.toml # pins python-docx==1.1.2
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
```

Run every `uv run` command from `work/`.

## Authoring rules (hard floor — do not relax)

- **Real Heading styles, not bold body text.** Use `doc.add_heading("...", level=1)` (or `paragraph.style = "Heading 2"`) for every section title. This is what drives the navigation pane, outline, and any table of contents. Never fake a heading with large bold body text — the delivery gate fails a document that needs headings but has none.
- **Explicit fonts and sizes.** Set body and heading fonts deliberately (`run.font.name`, `run.font.size = Pt(11)`, `run.font.bold`). Do not leave the whole document on the theme default when the task specifies a look.
- **Native tables.** When presenting structured data, use `doc.add_table(rows, cols)` with an explicit table style and a bold header row — a real Word table, not tab-aligned text.
- **Document structure.** Use a title, then Heading 1 / Heading 2 sections, real bullet / numbered lists (`style="List Bullet"` / `"List Number"`), and page breaks where the layout needs them.

Minimal shape:

```python
from docx import Document
from docx.shared import Pt
doc = Document()
doc.add_heading("Quarterly Review", level=0) # title
doc.add_heading("Summary", level=1) # real Heading 1
p = doc.add_paragraph()
run = p.add_run("Revenue grew 40% quarter over quarter.")
run.font.size = Pt(11)
t = doc.add_table(rows=1, cols=2); t.style = "Light Grid Accent 1"
hdr = t.rows[0].cells
hdr[0].text = "Quarter"; hdr[1].text = "Revenue"
doc.save("out.docx")
```

## Reading / parsing

`Document(path)` opens an existing file: iterate `doc.paragraphs` (each `p.text`, `p.style.name`) and `doc.tables` (each `table.rows[i].cells[j].text`) to extract or edit content.

## Gate — structure check (before delivering)

Run the structure gate and fix every reported gap by rebuilding from your generator — **never hand-edit the zip** — until it prints `OK`:

```bash
uv run python "$SKILL_DIR/scripts/check_docx.py" out.docx --min-paragraphs 1 [--require-heading] [--require-table]
```

Pass `--require-heading` for any structured report / multi-section document and `--require-table` when the task calls for a table. The gate confirms the document opens, has real body paragraphs, and (when required) uses real Heading styles and contains tables.

**The document is not done until this gate prints `OK`.** The machine check decides completion, not your own judgement.
7 changes: 7 additions & 0 deletions skills/office-docx/pyproject.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
[project]
name = "pawwork-office-docx"
version = "0.0.0"
requires-python = ">=3.9"
dependencies = [
"python-docx==1.1.2",
]
68 changes: 68 additions & 0 deletions skills/office-docx/scripts/check_docx.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
#!/usr/bin/env python3
"""Pre-delivery gate for the office-docx route: open the finished .docx with
python-docx and verify it really has the structure the task demands (real
heading styles, tables, non-empty body) before the run claims success. A
clean OK means the document opens and the required structural elements exist.

Run through uv so python-docx resolves from the mirror:
uv run python <skill>/scripts/check_docx.py <doc.docx> [--require-heading] [--require-table] [--min-paragraphs N]
"""

import argparse
import sys

try:
from docx import Document
except ImportError:
print(
"FAIL: python-docx is not importable. Run this through 'uv run python ...' from the "
"directory that holds the office-docx pyproject.toml (uv must be on PATH).",
file=sys.stderr,
)
sys.exit(2)


def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("docx", help="path to the built .docx")
parser.add_argument("--min-paragraphs", type=int, default=1, help="minimum non-empty paragraph count")
parser.add_argument("--require-heading", action="store_true", help="need at least one real Heading-styled paragraph")
parser.add_argument("--require-table", action="store_true", help="need at least one table")
args = parser.parse_args()

try:
doc = Document(args.docx)
except Exception as error: # noqa: BLE001 - report any open failure as a gate failure
print(f"FAIL: cannot open {args.docx}: {error}")
return 1

non_empty = [p for p in doc.paragraphs if p.text.strip()]
headings = [
p
for p in doc.paragraphs
if (p.style is not None and p.style.name is not None and p.style.name.startswith("Heading"))
]
tables = doc.tables

problems: list[str] = []
if len(non_empty) < args.min_paragraphs:
problems.append(f"expected at least {args.min_paragraphs} non-empty paragraph(s), found {len(non_empty)}")
if args.require_heading and len(headings) < 1:
problems.append("task needs headings but no paragraph uses a real Heading style (do not fake headings with bold body text)")
if args.require_table and len(tables) < 1:
problems.append("task needs a table but no table was found")
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

for problem in problems:
print(f"FAIL: {problem}")
if problems:
print(f"FAIL: {len(problems)} structure gap(s). Fix the generator and rebuild; do not hand-edit the zip.")
return 1
print(
f"OK: {len(non_empty)} non-empty paragraph(s), {len(headings)} heading(s), "
f"{len(tables)} table(s) — document matches the brief."
)
return 0


if __name__ == "__main__":
sys.exit(main())
56 changes: 56 additions & 0 deletions skills/office-pdf/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
name: office-pdf
description: "PREVIEW / dark-launched. PDF generation (author HTML, then print to PDF with PawWork's bundled Chromium) and PDF parsing (uv + pdfplumber / pypdf). NOT a default route — only use office-pdf when the user (or an experiment) explicitly asks for the preview PDF route by name. Hard rule: never use PyMuPDF / fitz (AGPL)."
---

# office-pdf — generate and parse PDF (preview)

Two independent paths: **generate** a PDF from HTML using PawWork's bundled Chromium, and **parse** an existing PDF with permissively-licensed Python libraries.

This is a **dark-launched preview**. It does not replace any default route. Only run it when explicitly routed here.

## License hard rule (non-negotiable)

**Never use PyMuPDF / `fitz` / `pymupdf` — it is AGPL and must not enter the product.** Also avoid any tool that shells out to it. Allowed parsers are `pdfplumber` (MIT) and `pypdf` (BSD) only. For rendering, use the bundled Chromium — not `wkhtmltopdf`, not LibreOffice, not a system-installed browser.

## Runtime contract

- `uv` must be on `PATH` for the **parse** path. Parsing runs through `uv run`; the runtime injects the package-mirror environment variables so `uv` resolves `pdfplumber` / `pypdf` from the internal mirror. You do not configure the mirror.
- **If `uv` is missing** (parse path), stop and report exactly: `office-pdf parsing requires 'uv' on PATH, but 'uv --version' failed. This is an environment problem — uv should be provisioned by the PawWork runtime. Do not fall back to system pip; report the missing uv instead.`
- The skill directory ships read-only inside the app bundle. **Never write into it.** Work in a fresh directory.

## Path 1 — Generate (HTML → Chromium printToPDF)

PawWork bundles its own Chromium; the PDF is produced by that engine's `Page.printToPDF` (Chrome DevTools Protocol) driving your HTML. No external browser install, no wkhtmltopdf, no LibreOffice.

Author a **self-contained HTML file** built for print:

- Set page geometry with `@page { size: A4; margin: 18mm; }` (or `Letter`, or an explicit `size: 210mm 297mm`).
- Inline all CSS and, where practical, images (as `data:` URIs) so the page renders without network fetches.
- Use `page-break-before/after` / `break-inside: avoid` to control pagination; design against print CSS, not screen scroll.
- Prefer real text and CSS/SVG vector graphics over rasterized screenshots so the PDF stays selectable and crisp.

Then render it to PDF through the runtime's bundled-Chromium print entry point (`Page.printToPDF` over the browser bridge). **If the current build exposes no PDF/print tool, report that the generation path is not available in this runtime rather than shelling out to an unbundled browser or an AGPL library** — this is expected while the route is dark-launched.

## Path 2 — Parse (uv + pdfplumber / pypdf)

```bash
SKILL_DIR="<the base directory shown when this skill loaded>"
uv --version || { echo "office-pdf parsing requires 'uv' on PATH (see Runtime contract)"; exit 1; }
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
mkdir -p work && cp "$SKILL_DIR/pyproject.toml" work/pyproject.toml # pdfplumber (MIT) + pypdf (BSD)
```

Choose by need, both run from `work/`:

- **`pdfplumber`** — layout-aware text and **table** extraction; use when you need columns, tables, or word positions.
```bash
uv run python -c "import pdfplumber,sys; \
[print(p.extract_text() or '') for p in pdfplumber.open(sys.argv[1]).pages]" input.pdf
```
- **`pypdf`** — fast plain-text, metadata, page count, and split/merge; use for quick text or manipulation.
```bash
uv run python -c "from pypdf import PdfReader; import sys; r=PdfReader(sys.argv[1]); \
print(len(r.pages), 'pages'); print(r.pages[0].extract_text())" input.pdf
```

If text extraction returns empty, the PDF is likely scanned images — say so and stop; do not reach for PyMuPDF or any AGPL OCR-render path.
13 changes: 13 additions & 0 deletions skills/office-pdf/pyproject.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
[project]
name = "pawwork-office-pdf"
version = "0.0.0"
requires-python = ">=3.9"
# Parsing/extraction only. Both are permissive-licensed:
# pdfplumber -> MIT (layout-aware text + tables)
# pypdf -> BSD (fast text, metadata, split/merge)
# PDF GENERATION does not use these — it goes through the bundled Chromium
# printToPDF (see SKILL.md). Never add PyMuPDF / fitz here (AGPL).
dependencies = [
"pdfplumber==0.11.4",
"pypdf==5.1.0",
]
21 changes: 21 additions & 0 deletions skills/office-pptx/LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2025-2026 Hugo He

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
85 changes: 85 additions & 0 deletions skills/office-pptx/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
---
name: office-pptx
description: "PREVIEW / dark-launched. Native .pptx generation by authoring one SVG per slide and converting with a bundled offline svg_to_pptx tool (no officecli, no LibreOffice, no LLM render). NOT the default deck path — for a normal presentation, pitch deck, or .pptx request keep using officecli-pptx / officecli-pitch-deck. Only use office-pptx when the user (or an experiment) explicitly asks for the SVG-to-native-PPTX / svg-pptx preview route by name."
---

# office-pptx — native PPTX from SVG (preview)

You build an editable native `.pptx` by hand-authoring one SVG per slide and converting the deck with the bundled, offline `svg_to_pptx` converter. No officecli, no LibreOffice, no LLM-rendered image slides — every shape stays natively editable in PowerPoint / Keynote / WPS.

This is a **dark-launched preview**. It does not replace the default office path. Only run it when explicitly routed here.

## Runtime contract

- `uv` must be on `PATH`. This skill runs all Python through `uv run`; the runtime injects the package-mirror environment variables so `uv` resolves `python-pptx` from the internal mirror. You do not configure the mirror yourself.
- **If `uv` is missing**, stop and report exactly: `office-pptx requires 'uv' on PATH, but 'uv --version' failed. This is an environment problem — uv should be provisioned by the PawWork runtime. Do not fall back to system pip or officecli; report the missing uv instead.` Do not attempt `pip install`, `brew install`, or any other fallback.
- The skill directory ships read-only inside the app bundle. **Never write into it.** Do all work in a fresh working directory (e.g. `./office-pptx-work/`).

Below, `SKILL_DIR` means the base directory printed when this skill loaded (shown as "Base directory for this skill"). Set it once:

```bash
SKILL_DIR="<the base directory shown when this skill loaded>"
uv --version || { echo "office-pptx requires 'uv' on PATH (see Runtime contract)"; exit 1; }
```

## Setup the working project

```bash
mkdir -p work/deck/svg_output work/deck/notes work/artifacts
cp "$SKILL_DIR/pyproject.toml" work/pyproject.toml # pins python-pptx==1.0.2, Python >=3.10
```

Run every `uv run` command from `work/` (the directory that holds `pyproject.toml`).

## Authoring rules (hard floor — do not relax)

- **Canvas**: every SVG must use `viewBox="0 0 1280 720"` (16:9). Keep all shapes inside that box.
- **One SVG per slide** in `deck/svg_output/`, named with zero-padded order prefixes (`01_title.svg`, `02_chart.svg`, ...); files convert in filename order.
- **Font sizes are SVG px, exported at 0.75pt per px.** Set an explicit `font-size` on every `<text>`: titles at least `60` px (= 45pt), body at least `24` px (= 18pt), and titles at least 2× the body px. Write one `<text>` per visual line, not positional `<tspan>`.
- **SVG `<text>` does not wrap** — a long line renders straight off the slide edge. Budget characters before writing: a Latin line takes about `0.55 × font-size` px per character (CJK about `1.0 × font-size`). Keep `chars × 0.55 × font-size ≤ 1220 − x` for every line. Example: a 60px title starting at `x=80` fits at most ~34 Latin characters. Split or shorten longer lines. (The text-budget gate below enforces this.)
- **Conclusion titles, not topic labels.** Every slide needs a real visual object (native chart, image, or a structured system of 3+ shapes). Vary layout across the deck.
- **Speaker notes**: for each content slide add `deck/notes/<same-stem>.md` (e.g. `02_chart.md` for `02_chart.svg`); its Markdown becomes that slide's notes. Cover at least slides 2..N.
- **Native editable chart** (required whenever the slide presents data): wrap the chart region in
`<g data-pptx-native="chart" data-pptx-x="80" data-pptx-y="210" data-pptx-width="1120" data-pptx-height="450">` and put the data in a child
`<metadata type="application/json">{"type":"column","categories":["Q1","Q2"],"series":[{"name":"2025","values":[10,20]}]}</metadata>`.
Each series `values` length must equal `categories` length. `type` may be `column`, `bar`, `line`, `pie`, `doughnut`, or `area`. Keep a plain fallback shape inside the group. This becomes a real `ppt/charts/chart*.xml` (editable chart), not a picture.
- **Image**: use `<image x=".." y=".." width=".." height=".." xlink:href="pic.png"/>` and place `pic.png` next to the SVGs in `deck/svg_output/`. Base64 `data:` hrefs also work. Images are embedded into `ppt/media/`.

## Gate 1 — text budget (before converting)

Run the budget check and fix every reported line (shorten the copy or split it into more `<text>` lines) until it prints `OK`:

```bash
uv run python "$SKILL_DIR/scripts/check_text_budget.py" deck/svg_output
```

Do not convert while this reports `FAIL`.

## Convert

Run from `work/` (holds `pyproject.toml`):

```bash
uv run python "$SKILL_DIR/scripts/svg_to_pptx.py" deck --only native --no-compat --native-objects -o artifacts/<name>.pptx
```

`--only native` skips the legacy image-based pptx; `--no-compat` skips the PNG fallback (no cairosvg needed); `--native-objects` turns the `data-pptx-native` chart markers into real `ppt/charts/chart*.xml`.

## Gate 2 — package assets (before delivering)

Finish in this order:

1. Write `artifacts/artifact-summary.json` describing renderer, slide titles, layout names, visual rules applied, and limitations.
2. Run the package gate as the **last** step and fix every reported gap by rebuilding the deck source — **never hand-edit the zip** — until it prints `OK`:

```bash
python3 "$SKILL_DIR/scripts/check_pptx_assets.py" artifacts/<name>.pptx --slides <N> [--require-chart] [--require-media]
```

Pass `--require-chart` for data-backed decks and `--require-media` when the deck must embed an image. The gate also requires `artifact-summary.json` to already exist next to the artifact, and checks the slide count and speaker-note coverage.

**The deck is not done until Gate 1 and Gate 2 both print `OK`.** Machine checks decide completion, not your own judgement.

## Provenance

The `svg_to_pptx` converter under `scripts/` is vendored from an upstream MIT project. See `VENDORED.md` for the exact source (repo, tag, commit) and the omitted/optional-dependency notes, and `LICENSE` for the upstream MIT license. Both must ship with this skill; do not remove them.
Loading
Loading