pptx-cli 1.0.0__tar.gz

pptx_cli-1.0.0/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.py]
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false

pptx_cli-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,21 @@
+---
+name: Bug report
+about: Report a defect in CLI behavior, manifest extraction, generation, or validation
+labels: bug
+---
+
+## What happened
+
+## Expected behavior
+
+## Reproduction
+
+## Environment
+
+- OS:
+- Python version:
+- `pptx` version/commit:
+
+## Artifacts
+
+If possible, attach a sanitized manifest, spec, or template description.

pptx_cli-1.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security issue
+    url: https://github.com/ThomasRohde/pptx-cli/security/policy
+    about: Please report suspected vulnerabilities privately.

pptx_cli-1.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,13 @@
+---
+name: Feature request
+about: Propose a new capability, content type, validation rule, or CLI contract improvement
+labels: enhancement
+---
+
+## Problem to solve
+
+## Proposed change
+
+## Why it belongs in scope
+
+## Examples or references

pptx_cli-1.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,25 @@
+## Summary
+
+Describe the change and why it matters.
+
+## What changed
+
+- 
+
+## Verification
+
+- [ ] `uv run pytest`
+- [ ] `uv run ruff check .`
+- [ ] `uv run ruff format --check .`
+- [ ] `uv run pyright`
+- [ ] Docs updated if needed
+
+## Contract impact
+
+- [ ] No CLI contract change
+- [ ] Guide / envelope / error-code change documented
+- [ ] Manifest/schema change documented
+
+## TODOs / follow-ups
+
+- 

pptx_cli-1.0.0/.github/copilot-instructions.md

@@ -0,0 +1,36 @@
+# Copilot instructions
+
+Use `AGENTS.md` as the canonical workspace guide. This file should only contain Copilot-specific reminders that supplement, rather than duplicate, the project-wide instructions.
+
+## Copilot-specific reminders
+
+- Follow existing patterns before introducing new abstractions
+- Prefer updating `AGENTS.md` when the project-wide guidance changes
+- Keep terminal and JSON output terse, deterministic, and easy for agents to parse
+
+## Preferred patterns
+
+- use typed models for shared contracts
+- keep Typer command handlers thin
+- put reusable logic in `src/pptx_cli/core/`
+- keep machine-readable output stable and explicit
+- prefer additive evolution over silent breaking changes
+
+## Naming conventions
+
+- CLI executable: `pptx`
+- Python package: `pptx_cli`
+- command IDs in machine-readable envelopes: dotted form like `guide.show`, `template.init`, or similar stable canonical names
+- tests: `test_*.py`
+
+## Testing expectations
+
+- add or update tests with code changes
+- validate command behavior and structured output for CLI changes
+- preserve dry-run and safe-write semantics in tests for mutating commands
+
+## Documentation expectations
+
+- update docs in the same PR when commands, examples, or contracts change
+- keep examples aligned with the current scaffold and command names
+- leave guided `TODO:` blocks instead of guessing product decisions

pptx_cli-1.0.0/.github/instructions/backend.instructions.md

@@ -0,0 +1,12 @@
+---
+applyTo: "src/pptx_cli/**/*.py"
+---
+
+# Backend instructions
+
+- Keep command handlers thin and move reusable logic into `core/` or `models/`
+- Preserve deterministic machine-readable output
+- Do not introduce a Python package named `pptx`
+- Prefer explicit types and small, composable functions
+- When a command mutates outputs, maintain dry-run compatibility and safe file-write semantics
+- Do not silently change stable error codes or exit-code categories

pptx_cli-1.0.0/.github/instructions/testing.instructions.md

@@ -0,0 +1,11 @@
+---
+applyTo: "tests/**/*.py"
+---
+
+# Testing instructions
+
+- Test machine-readable output contracts, not just happy-path text
+- Cover at least one failure case for every new command behavior
+- Prefer deterministic fixtures and golden outputs for schemas/envelopes
+- Keep tests small and focused unless they are explicit integration tests
+- When changing command names, flags, or envelope fields, update the tests in the same change

pptx_cli-1.0.0/.github/skills/pptx/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: pptx
+description: >
+  How to use the `pptx` CLI to create PowerPoint presentations from enterprise templates.
+  Use this skill whenever the user wants to create, build, or generate PowerPoint slides or decks,
+  work with .pptx templates, inspect slide layouts or placeholders, validate presentations,
+  or anything related to PowerPoint generation from the command line. Also trigger when the user
+  mentions deck specs, slide layouts, manifest packages, or template-bound presentation workflows.
+  Even if the user just says "make me a presentation" or "create some slides", this skill applies.
+---
+
+# pptx — Template-Bound PowerPoint Generation
+
+`pptx` is a CLI that turns a real `.pptx` template into a machine-readable manifest, then generates slides and decks **inside the original corporate design contract**. It preserves masters, themes, locked branding, and placeholder rules — instead of approximating them.
+
+## Quick orientation
+
+The workflow has three phases:
+
+1. **Setup** — install the CLI and initialize a manifest from a template
+2. **Discover** — explore layouts, placeholders, and theme to understand what's available
+3. **Build** — create slides or full decks from structured specs, then validate
+
+## Phase 1: Setup
+
+### Install
+
+```bash
+uv tool install pptx-cli
+# or: pip install pptx-cli
+```
+
+Verify with `pptx --version`.
+
+### Initialize a manifest
+
+The manifest package lives at `.pptx/` in the project root. Always check for an existing one first:
+
+```bash
+ls .pptx/manifest.yaml 2>/dev/null
+```
+
+If no manifest exists, you need a `.pptx` template file from the user. **Ask the user** to provide one — do not assume a template exists. Then initialize:
+
+```bash
+pptx init <template.pptx> --out ./.pptx
+```
+
+This extracts layouts, placeholders, assets, themes, and rules into a structured manifest package.
+
+### Bootstrap command: `pptx guide`
+
+Run this once to get the full CLI contract — all commands, schemas, error codes, and examples:
+
+```bash
+pptx guide --format json
+```
+
+This is your single source of truth for the CLI's capabilities. Cache the result mentally and refer to it throughout the session.
+
+## Phase 2: Discover
+
+Before building anything, understand what the template offers. These are all read-only commands and can run in parallel:
+
+```bash
+# List all available layouts
+pptx layouts list --manifest ./.pptx --format json
+
+# Show details for a specific layout
+pptx layouts show <layout-id> --manifest ./.pptx --format json
+
+# List placeholders for a layout (tells you what content keys are available)
+pptx placeholders list <layout-id> --manifest ./.pptx --format json
+
+# Show theme metadata
+pptx theme show --manifest ./.pptx --format json
+
+# List extracted assets
+pptx assets list --manifest ./.pptx --format json
+
+# Check for compatibility warnings
+pptx doctor --manifest ./.pptx --format json
+```
+
+**Layout IDs** are slugified names derived from the template (e.g., `title-only`, `1-title-and-content`, `1-breaker-with-pattern`). Use `layouts list` to discover the exact IDs.
+
+**Placeholder keys** are logical names like `title`, `subtitle`, `content_1`, `picture`. Use `placeholders list <layout-id>` to discover the exact keys and their supported content types for each layout.
+
+## Phase 3: Build
+
+### Single slide
+
+```bash
+pptx slide create \
+  --manifest ./.pptx \
+  --layout <layout-id> \
+  --set title="Your Title" \
+  --set subtitle="Your Subtitle" \
+  --out ./out/slide.pptx
+```
+
+### Full deck from a spec
+
+Create a YAML or JSON spec file, then build. See `references/deck-spec.md` for the full spec format.
+
+```yaml
+# deck.yaml
+manifest: ./.pptx
+metadata:
+  title: My Presentation
+  author: Author Name
+slides:
+  - layout: title-only
+    content:
+      title: Welcome
+      subtitle: March 2026
+  - layout: 1-title-and-content
+    content:
+      title: Key Points
+      content_1: |
+        First point.
+        Second point.
+        Third point.
+```
+
+```bash
+pptx deck build \
+  --manifest ./.pptx \
+  --spec deck.yaml \
+  --out ./out/deck.pptx
+```
+
+### Preview before writing
+
+Always use `--dry-run` first on mutating commands to preview what will happen without writing files:
+
+```bash
+pptx deck build --manifest ./.pptx --spec deck.yaml --out ./out/deck.pptx --dry-run
+```
+
+### Validate the output
+
+After generating a deck, validate it against the manifest:
+
+```bash
+pptx validate --manifest ./.pptx --deck ./out/deck.pptx --strict --format json
+```
+
+## Supported content types
+
+- `text` — plain text
+- `image` — image file reference
+- `table` — structured table data
+- `chart` — chart data
+- `markdown-to-text` — markdown converted to formatted text
+
+## Error handling
+
+All commands return a structured JSON envelope with `ok`, `errors`, and `warnings` fields. Key exit codes:
+
+| Exit | Meaning |
+|------|---------|
+| 0 | Success |
+| 10 | Validation error (bad input, unknown layout/placeholder) |
+| 20 | Policy error |
+| 40 | Conflict (output file exists) |
+| 50 | I/O error |
+| 90 | Internal error |
+
+Check `ok` first, then branch on `errors[0].code` if it's `false`.
+
+## Typical workflow for building a presentation
+
+1. Check for `.pptx/manifest.yaml` — if missing, ask user for a template and run `pptx init`
+2. Run `pptx layouts list` to see available layouts
+3. For each layout you plan to use, run `pptx placeholders list <layout-id>` to discover content keys
+4. Draft a `deck.yaml` spec using only discovered layout IDs and placeholder keys
+5. Preview with `pptx deck build ... --dry-run`
+6. Build with `pptx deck build ... --out ./out/deck.pptx`
+7. Validate with `pptx validate ...`
+
+## Key rules
+
+- **Only use layout IDs that appear in `layouts list`** — unknown layouts cause validation errors
+- **Only use placeholder keys that appear in `placeholders list`** — unknown keys are silently ignored or cause errors
+- **Always use `--manifest ./.pptx`** to point to the manifest package
+- **Use `--dry-run` before writing** to catch issues early
+- **Use `--format json`** on read commands to get structured output you can parse
+
+For detailed deck spec format and advanced options, read `references/deck-spec.md`.

pptx_cli-1.0.0/.github/skills/pptx/references/deck-spec.md

@@ -0,0 +1,160 @@
+# Deck Spec Format
+
+The deck spec is a YAML or JSON file that describes a full presentation. It is the input to `pptx deck build`.
+
+## Schema
+
+```yaml
+# Required
+slides:
+  - layout: <layout-id>        # Must match an ID from `pptx layouts list`
+    content:                    # Optional — keys must match placeholder logical_names
+      <placeholder-key>: <value>
+
+# Optional
+manifest: <path>                # Path to manifest package (can also be passed via --manifest flag)
+metadata:                       # Presentation-level metadata
+  title: <string>
+  author: <string>
+  template_version: <string>
+  # Additional arbitrary key-value pairs are allowed
+```
+
+## Slide content values
+
+Content values depend on the placeholder's `supported_content_types` (discoverable via `pptx placeholders list <layout-id>`).
+
+### Text content
+
+Plain strings or multi-line YAML strings:
+
+```yaml
+- layout: 1-title-and-content
+  content:
+    title: My Title
+    content_1: |
+      Bullet point one.
+      Bullet point two.
+      Bullet point three.
+    subtitle: Supporting context here.
+```
+
+### Image content
+
+Reference an image file path:
+
+```yaml
+- layout: picture-layout
+  content:
+    picture: ./images/diagram.png
+```
+
+### Table content
+
+Structured table data:
+
+```yaml
+- layout: table-layout
+  content:
+    table:
+      headers: [Name, Role, Status]
+      rows:
+        - [Alice, Engineer, Active]
+        - [Bob, Designer, Active]
+```
+
+### Chart content
+
+Structured chart data:
+
+```yaml
+- layout: chart-layout
+  content:
+    chart:
+      type: bar
+      categories: [Q1, Q2, Q3, Q4]
+      series:
+        - name: Revenue
+          values: [100, 150, 130, 170]
+```
+
+## Full example
+
+```yaml
+manifest: ./.pptx
+metadata:
+  title: Quarterly Business Review
+  author: Jane Smith
+  template_version: 1.0.0
+slides:
+  - layout: title-only
+    content:
+      title: Q1 2026 Business Review
+      subtitle: Prepared by Jane Smith
+
+  - layout: 1-breaker-with-pattern
+    content:
+      title: Financial Overview
+
+  - layout: 1-title-and-content
+    content:
+      title: Revenue Summary
+      content_1: |
+        Total revenue: $4.2M (up 12% YoY).
+        New customer acquisition: 47 accounts.
+        Renewal rate: 94%.
+      subtitle: All figures as of March 31, 2026.
+
+  - layout: 1-title-and-content
+    content:
+      title: Key Initiatives
+      content_1: |
+        Platform migration: 80% complete.
+        New product launch: on track for Q2.
+        Hiring: 12 of 15 positions filled.
+
+  - layout: 1-breaker-with-pattern
+    content:
+      title: Next Steps
+
+  - layout: 1-title-and-content
+    content:
+      title: Action Items
+      content_1: |
+        Complete platform migration by April 30.
+        Finalize Q2 product launch plan.
+        Fill remaining 3 open positions.
+      subtitle: Review again at May steering committee.
+```
+
+## Discovering valid layout IDs and placeholder keys
+
+Before writing a spec, always discover what's available:
+
+```bash
+# Get all layout IDs
+pptx layouts list --manifest ./.pptx --format json
+
+# Get placeholder keys for a specific layout
+pptx placeholders list <layout-id> --manifest ./.pptx --format json
+```
+
+The `placeholders list` output includes:
+- `logical_name` — the key to use in your spec's `content` block
+- `placeholder_type` — what kind of placeholder it is (TITLE, SUBTITLE, BODY, etc.)
+- `supported_content_types` — what content formats are accepted
+- `required` — whether this placeholder must be filled
+- `guidance_text` — hint text from the template about intended use
+
+## Building from the spec
+
+```bash
+# Preview first
+pptx deck build --manifest ./.pptx --spec deck.yaml --out ./out/deck.pptx --dry-run
+
+# Build
+pptx deck build --manifest ./.pptx --spec deck.yaml --out ./out/deck.pptx
+
+# Validate
+pptx validate --manifest ./.pptx --deck ./out/deck.pptx --strict --format json
+```

pptx_cli-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: '3.12'
+          enable-cache: true
+
+      - name: Sync dependencies
+        run: uv sync --group dev
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Pyright
+        run: uv run pyright
+
+      - name: Pytest
+        run: uv run pytest

pptx_cli-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: write
+    environment:
+      name: pypi
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: '3.12'
+          enable-cache: true
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        if: startsWith(github.ref, 'refs/tags/v')
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "${{ github.ref_name }}" dist/* --generate-notes

pptx_cli-1.0.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+.Python
+.venv/
+venv/
+env/
+.pytest_cache/
+.mypy_cache/
+.pyright/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Local outputs
+out/
+.tmp/
+logs/
+*.log
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+
+# Generated template/manifests during local development
+*.pptx
+*.zip
+
+

pptx_cli-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12