pptx-cli 1.0.0__tar.gz → 1.2.0__tar.gz

pptx_cli-1.2.0/.github/skills/pptx-deck-builder/SKILL.md

@@ -0,0 +1,353 @@
+---
+name: pptx-deck-builder
+description: >
+  Build enterprise PowerPoint decks using the `pptx` and `excal` CLI tools.
+  Use this skill whenever the user wants to create a PowerPoint presentation,
+  generate slides from a template, build a deck with diagrams, or produce
+  consulting-style slide content. Also triggers for requests involving
+  .pptx files, slide decks, presentation generation, Excalidraw diagrams
+  for slides, or McKinsey/consulting-style deliverables. If the user mentions
+  "pptx", "excal", "slides", "deck", "presentation", or "PowerPoint" in the
+  context of creating output, use this skill.
+---
+
+# pptx + excal Deck Builder
+
+Build template-bound, validated PowerPoint decks with professional diagrams.
+This skill combines two CLI tools (`pptx` for slide generation, `excal` for
+diagrams) with consulting-grade presentation principles.
+
+## When to read the reference files
+
+- **`references/pptx-workflow.md`** — Read when you need the full `pptx` CLI
+  command reference, manifest structure, placeholder details, deck spec format,
+  error codes, or image-handling workarounds.
+- **`references/excal-diagrams.md`** — Read when you need to create Excalidraw
+  diagrams, render them to PNG, or understand the scene JSON format.
+- **`references/mckinsey-style.md`** — Read when the user asks for
+  consulting-style, executive, strategy, or McKinsey-style presentations. Also
+  read when you need guidance on action titles, storyline structure, slide
+  archetypes, or the Pyramid Principle.
+
+---
+
+## Core workflow
+
+Every deck project follows this sequence. Do not skip steps.
+
+### Step 0 — Think before building
+
+Before touching any tool, resolve the presentation's purpose:
+
+1. What decision or outcome is this deck driving?
+2. What is the single governing thought or recommendation?
+3. What are the 3-5 supporting arguments?
+4. What evidence proves each argument?
+
+If the user's request is vague, ask clarifying questions. A deck without a
+clear purpose becomes a collection of slides instead of an argument.
+
+For consulting-style decks, write a **ghost deck** first — a title-only
+outline where each slide title states the takeaway (not the topic). The titles
+alone should tell a coherent story. See `references/mckinsey-style.md`.
+
+### Step 1 — Initialize the manifest (one-time setup)
+
+Check if a manifest package already exists. If not, initialize from the
+template:
+
+```bash
+pptx init Template.pptx --out ./corp-template --format json
+```
+
+Then run the doctor to verify compatibility:
+
+```bash
+pptx doctor --manifest ./corp-template --format json
+```
+
+### Step 2 — Discover layouts and placeholders
+
+List available layouts, then inspect placeholders for the ones you plan to use:
+
+```bash
+pptx layouts list --manifest ./corp-template --format json
+pptx placeholders list <layout-id> --manifest ./corp-template --format json
+```
+
+Read-only commands can run in parallel for speed. Key information per
+placeholder:
+
+- `logical_name` — The key to use in your spec (e.g., `title`, `content_1`)
+- `placeholder_type` — `title`, `body`, `object`, or `picture`
+- `supported_content_types` — What it accepts (`text`, `markdown-text`,
+  `image`, `table`, `chart`)
+- `required` — Whether it must be filled
+- `estimated_text_capacity` — Preferred normalized guidance for text-capable
+  placeholders. Read `max_lines` first, then check `confidence`, `source`,
+  and `font_size_pt`.
+- `text_defaults` — Raw extracted placeholder hints such as suggested font
+  size or explicit `max_lines` from the template text
+- `left_emu`, `top_emu`, `width_emu`, `height_emu` — The actual geometry.
+  Treat `width_emu` and `height_emu` as hard constraints for how much content
+  the placeholder can realistically hold.
+
+For slide drafting, prefer `estimated_text_capacity.max_lines` over parsing
+`text_defaults.max_lines` directly. Treat it as guidance, not a hard rule:
+stay at or below the line estimate when possible, and be more conservative
+when `confidence` is `low`.
+
+Respect placeholder size in every content decision:
+
+- Text: do not write beyond the likely line budget for the box. If the message
+  does not fit, tighten the wording or choose a layout with a larger text area.
+- Images and diagrams: match the placeholder aspect ratio and expected visual
+  density to the available width and height.
+- Tables and charts: reduce rows, columns, labels, or series when the
+  placeholder is small. Prefer a larger layout over forcing dense content into
+  a small box.
+
+Also inspect theme colors and assets if you need to match the visual identity:
+
+```bash
+pptx theme show --manifest ./corp-template --format json
+pptx assets list --manifest ./corp-template --format json
+```
+
+### Step 3 — Create diagrams with excal (if needed)
+
+When the deck needs diagrams, flowcharts, or visual explanations, create them
+as Excalidraw scenes and render to PNG.
+
+**Critical: match the placeholder aspect ratio.** Before designing a diagram,
+check the target placeholder's dimensions in EMUs (from the placeholders
+command). Calculate the aspect ratio and design the diagram to match.
+
+For a picture placeholder that is 6642100 x 5514313 EMU (~1.2:1), design a
+diagram roughly 540px wide x 450px tall. A mismatch causes cropping or
+letterboxing.
+
+```bash
+# Create the .excalidraw file, then:
+excal validate diagrams/my-diagram.excalidraw
+excal render diagrams/my-diagram.excalidraw --outDir ./out/diagrams --png --scale 4 --no-background
+```
+
+Use `--no-background` for transparent backgrounds that blend with slide
+backgrounds. Use `--scale 4` for crisp output — scale 2 looks blurry on
+large slide placeholders because the pixel density is too low for the
+physical size. Scale 4 ensures diagrams stay sharp even on high-DPI
+displays and when projected.
+
+**Match the template's visual identity.** Diagrams should feel like they belong
+on the slide, not like foreign objects pasted in. Two things matter most:
+
+1. **Use `fontFamily: 1`** (Excalidraw's hand-drawn style) for diagram text.
+   This gives a clean whiteboard aesthetic that contrasts well with formal slide
+   typography and looks intentional rather than mismatched.
+
+2. **Pull colors from the template theme.** Run `pptx theme show --manifest
+   ./corp-template --format json` and use the accent colors for fills and
+   strokes. Common mapping:
+   - Primary elements → accent1 (e.g., `#003778`)
+   - Secondary elements → accent2 (e.g., `#4673C3`)
+   - Tertiary/subtle → accent3 (e.g., `#87AAE1`)
+   - Success/positive → `#087f5b` (green)
+   - Labels/muted → `#868e96` (gray)
+
+   Avoid arbitrary colors — diagrams that use theme colors integrate seamlessly
+   with the slide's color palette.
+
+See `references/excal-diagrams.md` for the full Excalidraw scene format and
+element types.
+
+### Step 4 — Write the deck spec
+
+Create a YAML file mapping layouts to content:
+
+```yaml
+manifest: ./corp-template
+metadata:
+  title: "Presentation Title"
+  author: "Author Name"
+slides:
+  - layout: layout-id
+    content:
+      title: "Action title stating the takeaway"
+      subtitle: "Optional context"
+      content_1: |
+        - Bullet point one
+        - Bullet point two
+      source: "Source: Data attribution"
+
+  - layout: picture-layout-id
+    content:
+      title: "Slide title"
+      picture:
+        kind: image
+        path: out/diagrams/my-diagram.png
+      content_1: |
+        Supporting text alongside the image
+```
+
+**Content value formats:**
+- Plain string → treated as `text`
+- Multi-line YAML block scalar → treated as `text` with line breaks
+- `{ kind: "image", path: "path/to/file.png" }` → image insertion
+- `{ kind: "table", columns: [...], rows: [[...], ...] }` → table
+- `{ kind: "chart", chart_type: "column_clustered", categories: [...], series: [{name: "...", values: [...]}] }` → chart
+
+### Step 5 — Build and validate
+
+```bash
+pptx deck build --manifest ./corp-template --spec deck.yaml --out ./out/deck.pptx --format json
+pptx validate --manifest ./corp-template --deck ./out/deck.pptx --strict --format json
+```
+
+Always validate with `--strict`. Fix any issues and rebuild. If the output
+file is locked (open in PowerPoint), write to a new filename.
+
+Use `--dry-run` on build to preview without writing files.
+
+---
+
+## Image handling
+
+### Image scaling — fit vs crop
+
+Picture placeholders should already advertise `image` in
+`supported_content_types`. Do not patch `manifest.yaml` unless inspection
+output proves the template contract is actually wrong.
+
+The current build behavior defaults to `image_fit: fit`, which preserves the
+full image inside the placeholder. Use `image_fit: cover` when you explicitly
+want crop-to-fill behavior.
+
+```yaml
+slides:
+  - layout: picture-layout-id
+    content:
+      title: Workflow
+      picture:
+        kind: image
+        path: out/diagrams/workflow.png
+        image_fit: fit
+```
+
+---
+
+## Slide writing principles
+
+These apply to every deck, not just consulting-style ones.
+
+### Action titles, not topic labels
+
+Every slide title should state the takeaway — what the audience should
+conclude — not just name the topic.
+
+- Bad: "Market Overview"
+- Good: "Nordic retail margins will remain under pressure through 2027"
+
+### One slide, one message
+
+If a slide has two insights, split it into two slides. The body must prove
+the headline.
+
+### Respect placeholder geometry
+
+Never treat placeholder size as flexible. The template geometry is part of the
+contract.
+
+- If text exceeds the placeholder's likely capacity, shorten it or split it.
+- If a table or chart needs more room, switch to a layout with a larger object
+  placeholder.
+- If a diagram becomes unreadable at the placeholder's size, simplify the
+  diagram rather than shrinking text and shapes until they are illegible.
+
+### Source attribution
+
+Data-driven slides need source lines. Use the `source` placeholder when
+available.
+
+### Storyline coherence
+
+A reader should be able to read only the slide titles, in order, and
+understand the full argument.
+
+For full consulting-style guidance including the Pyramid Principle, MECE
+structuring, ghost decks, slide archetypes, and executive summary
+construction, read `references/mckinsey-style.md`.
+
+---
+
+## Layout selection guide
+
+Match content to the right layout:
+
+| Content type | Suggested layout patterns |
+|---|---|
+| Opening / title | front-page layouts (with pattern or picture) |
+| Agenda / TOC | agenda layouts (use plain text items without numbered prefixes — the layout often auto-numbers) |
+| Section divider | breaker layouts |
+| Single topic with bullets | title-and-content |
+| Side-by-side comparison | two-contents |
+| Topic with description header | title-description-and-content |
+| Image with explanation | picture-right-text-and-box (or similar) |
+| Minimal / custom | title-only or blank-with-logo |
+| Closing | end-slide layouts |
+
+When a template has numbered variants (e.g., `1-title-and-content`,
+`2-title-description-and-content`), inspect the placeholders of each to
+understand the differences. Numbered variants often differ in placeholder
+arrangement, background color, or description fields.
+
+---
+
+## Quick reference — common commands
+
+```bash
+# One-time setup
+pptx init Template.pptx --out ./manifest-dir --format json
+pptx doctor --manifest ./manifest-dir --format json
+
+# Inspection (safe to parallelize)
+pptx layouts list --manifest ./manifest-dir --format json
+pptx placeholders list <layout-id> --manifest ./manifest-dir --format json
+pptx theme show --manifest ./manifest-dir --format json
+pptx assets list --manifest ./manifest-dir --format json
+
+# Single slide (quick test)
+pptx slide create --manifest ./manifest-dir --layout <id> --set title="Hello" --out slide.pptx
+
+# Full deck
+pptx deck build --manifest ./manifest-dir --spec deck.yaml --out deck.pptx --format json
+pptx validate --manifest ./manifest-dir --deck deck.pptx --strict --format json
+
+# Diagrams
+excal validate diagram.excalidraw
+excal render diagram.excalidraw --outDir ./out --png --scale 4 --no-background
+
+# Template versioning
+pptx manifest diff ./v1-manifest ./v2-manifest --format json
+```
+
+---
+
+## Error handling
+
+All `pptx` commands return JSON envelopes with `ok`, `errors`, and exit codes:
+
+| Exit code | Meaning |
+|---|---|
+| 0 | Success |
+| 10 | Validation error (bad layout, missing placeholder, wrong content type) |
+| 20 | Policy error |
+| 40 | Conflict (output file exists / locked) |
+| 50 | I/O error (file not found) |
+| 90 | Internal error |
+
+If output file is locked (exit code 40 or PermissionError), write to a
+different filename — do not retry.
+
+All `excal` errors also return JSON envelopes. Key codes: exit 10 for
+invalid scene JSON, exit 20 for render failures, exit 50 for I/O errors.

pptx_cli-1.2.0/.github/skills/pptx-deck-builder/references/excal-diagrams.md

@@ -0,0 +1,161 @@
+# excal CLI — Diagram Reference
+
+## Commands
+
+### excal inspect <file|->
+Inspect scene structure: element counts, bounds, metadata.
+```bash
+excal inspect diagram.excalidraw
+```
+
+### excal validate <file|->
+Validate scene: frame refs, bound text, arrow bindings, assets.
+```bash
+excal validate diagram.excalidraw
+excal validate diagram.excalidraw --check-assets
+```
+
+### excal render <file|->
+Render to SVG, PNG, or PDF. PNG/PDF require Playwright.
+```bash
+excal render diagram.excalidraw --outDir ./out --png --scale 4 --no-background
+excal render diagram.excalidraw --outDir ./out --svg
+excal render diagram.excalidraw --outDir ./out --png --dark-mode
+excal render diagram.excalidraw --outDir ./out --png --frame "Frame Name"
+```
+
+Flags:
+- `--outDir <dir>` — Output directory (default: .)
+- `--svg` — Export SVG (default format)
+- `--png` — Export PNG (requires Playwright)
+- `--pdf` — Export PDF (requires Playwright)
+- `--dark-mode` — Dark theme
+- `--no-background` — Transparent background
+- `--scale <n>` — Scale factor for PNG (default: 2, use 4 for slide-quality output)
+- `--padding <n>` — Padding in pixels (default: 20)
+- `--frame <id|name>` — Export specific frame only
+- `--element <id>` — Export specific element only
+- `--dry-run` — Validate pipeline without writing
+
+### excal guide
+Output CLI guide as Markdown.
+
+### excal skill
+Return Excalidraw domain knowledge.
+
+---
+
+## Excalidraw scene format
+
+```json
+{
+  "type": "excalidraw",
+  "version": 2,
+  "source": "manual",
+  "elements": [ ... ],
+  "appState": { "viewBackgroundColor": "#ffffff" },
+  "files": {}
+}
+```
+
+## Element types
+
+| Type | Description |
+|---|---|
+| rectangle | Box shape |
+| diamond | Diamond/rhombus |
+| ellipse | Circle/ellipse |
+| arrow | Arrow connector |
+| line | Line/polyline |
+| text | Text label |
+| image | Embedded image |
+| frame | Grouping frame |
+
+## Key element properties
+
+Every element has: `id`, `type`, `x`, `y`, `width`, `height`, `isDeleted`,
+`opacity`, `groupIds`, `frameId`, `angle`, `seed`.
+
+Shape-specific:
+- `strokeColor` — Border color (hex)
+- `backgroundColor` — Fill color (hex)
+- `fillStyle` — "solid", "hachure", "cross-hatch"
+- `strokeWidth` — Border width (1-4 typical)
+- `roundness` — `{ "type": 3 }` for rounded corners
+- `boundElements` — Array of `{ id, type }` for bound text/arrows
+
+Text-specific:
+- `text` — The text content (use \n for line breaks)
+- `fontSize` — Font size in px
+- `fontFamily` — 1 (hand-drawn), 2 (normal), 3 (monospace)
+- `textAlign` — "left", "center", "right"
+- `verticalAlign` — "top", "middle", "bottom"
+- `containerId` — ID of container shape (for bound text)
+
+Arrow-specific:
+- `points` — Array of [x, y] relative to element position
+- `startBinding` — `{ elementId, focus, gap }`
+- `endBinding` — `{ elementId, focus, gap }`
+
+## Bound text pattern
+
+Text bound to a container:
+1. Container has `boundElements: [{ id: "text-id", type: "text" }]`
+2. Text has `containerId: "container-id"`
+3. Text position is relative but overridden by container
+
+## Styling for professional presentations
+
+When creating diagrams for slide decks, use `fontFamily: 1` (the hand-drawn
+Excalidraw style) for a distinctive, approachable look. This gives diagrams
+a clean whiteboard aesthetic that contrasts well with formal slide typography.
+
+Use the template's theme colors for visual consistency. Extract colors from
+`pptx theme show`:
+
+```bash
+pptx theme show --manifest ./corp-template --format json
+```
+
+Use the theme's accent colors for fills and strokes. Common pattern:
+- Primary elements: accent1 (e.g., `#003778`)
+- Secondary elements: accent2 (e.g., `#4673C3`)
+- Tertiary/subtle: accent3 (e.g., `#87AAE1`)
+- Contrast/alternative: accent5/accent6 for a different hue
+- Success/positive: `#087f5b` (green)
+- Labels/muted: `#868e96` (gray)
+
+### Aspect ratio matching
+
+**This is critical.** Before designing a diagram, check the target
+placeholder's EMU dimensions and calculate its aspect ratio:
+
+```
+aspect = width_emu / height_emu
+```
+
+Design the diagram's bounding box to match. For a 1.2:1 placeholder, aim for
+~540x450 px. For a 2:1 placeholder, aim for ~600x300 px.
+
+Vertical/stacked layouts (top-to-bottom flow) work well for nearly-square
+placeholders. Horizontal layouts work for wide placeholders.
+
+---
+
+## Error codes
+
+| Code | Exit | Description |
+|---|---|---|
+| ERR_VALIDATION_INVALID_JSON | 10 | Input is not valid JSON |
+| ERR_VALIDATION_INVALID_SCENE | 10 | Scene structure validation failed |
+| ERR_RENDER_BROWSER_UNAVAILABLE | 20 | Playwright not installed |
+| ERR_RENDER_EXPORT_FAILED | 20 | Export failed in browser |
+| ERR_IO_READ_FAILED | 50 | Failed to read input |
+| ERR_IO_WRITE_FAILED | 50 | Failed to write output |
+
+---
+
+## Concurrency
+
+Reads (inspect, validate) and renders are all safe to run concurrently.
+Each render launches its own browser instance.