pptx-cli 1.3.3__tar.gz → 1.3.5__tar.gz

{pptx_cli-1.3.3 → pptx_cli-1.3.5}/.github/skills/pptx-deck-builder/SKILL.md

@@ -51,6 +51,34 @@ 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`.
 
+### Working from a YAML input file
+
+When the user provides a YAML (or similar structured) file that already
+contains slide content, treat it as the authoritative source. The file
+typically defines `slides:` with per-slide fields such as `title`, `body`,
+`notes`, `table`, `chart`, and `image`.
+
+**Carry over every field.** Walk through each slide in the input and map
+every field into the deck spec. The most common mistake is silently dropping
+fields that do not map to a placeholder — especially `notes`. Always include:
+
+- `title` and `body` → map to the layout's `title` and `content_1`
+- `notes` → map to the slide-level `notes:` key in the deck spec
+- `table` → map to a `{ kind: table, ... }` content block
+- `chart` → map to a `{ kind: chart, ... }` content block
+- `image` → map to a `{ kind: image, ... }` content block
+
+**Do not summarize, rewrite, or omit content** unless the user explicitly
+asks for editing. The goal is faithful conversion from the input format to
+a template-bound deck spec, not reinterpretation.
+
+**Checklist before building:** after writing the deck spec, verify that:
+
+1. The number of slides matches the input.
+2. Every `notes:` block from the input appears in the spec.
+3. Every table, chart, and image from the input is present.
+4. Source attributions are preserved.
+
 ### Step 1 — Initialize the manifest (one-time setup)
 
 Check if a manifest package already exists. If not, initialize from the

{pptx_cli-1.3.3 → pptx_cli-1.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pptx-cli
-Version: 1.3.3
+Version: 1.3.5
 Summary: Template-bound PowerPoint generation for enterprise decks
 Author: Thomas Rohde
 License: MIT License

{pptx_cli-1.3.3 → pptx_cli-1.3.5}/src/pptx_cli/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "1.3.3"
+__version__ = "1.3.5"

{pptx_cli-1.3.3 → pptx_cli-1.3.5}/src/pptx_cli/cli.py

@@ -245,13 +245,44 @@ def schema_command(
         Path | None,
         typer.Option("--template", help="Path to a manifest package directory."),
     ] = None,
+    no_template: Annotated[
+        bool,
+        typer.Option("--no-template", help="Emit generic schema without template layouts."),
+    ] = False,
     no_copy: Annotated[
         bool,
         typer.Option("--no-copy", help="Skip copying output to the clipboard."),
     ] = False,
 ) -> None:
     """Print the deck-spec YAML reference (for pasting into LLM prompts)."""
-    text = build_schema_document(template)
+    if template is not None and no_template:
+        typer.echo("Error: --template and --no-template are mutually exclusive.", err=True)
+        raise typer.Exit(code=1)
+
+    effective_template = template
+    if not no_template and effective_template is None:
+        # Auto-discover manifest in cwd
+        for candidate in [Path("manifest.yaml"), Path("manifest/manifest.yaml")]:
+            if candidate.exists():
+                effective_template = candidate.parent
+                break
+        if effective_template is None:
+            # Fall back to generic schema with a hint
+            typer.echo(
+                "Hint: use --template <dir> for a layout-aware schema, "
+                "or --no-template for the generic version.",
+                err=True,
+            )
+
+    if effective_template is not None and not (effective_template / "manifest.yaml").exists():
+        typer.echo(
+            f"Error: manifest not found at '{effective_template / 'manifest.yaml'}'.\n"
+            f"Run 'pptx init <template.pptx> --out {effective_template}' first.",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    text = build_schema_document(effective_template)
     typer.echo(text)
     if not no_copy:
         if copy_to_clipboard(text):

{pptx_cli-1.3.3 → pptx_cli-1.3.5}/src/pptx_cli/commands/schema.py

@@ -42,10 +42,10 @@ def copy_to_clipboard(text: str) -> bool:
 
 
 # ---------------------------------------------------------------------------
-# Generic (template-free) schema
+# Shared constants
 # ---------------------------------------------------------------------------
 
-_GENERIC_SCHEMA = """\
+_OUTPUT_FORMAT = """\
 <output-format>
 IMPORTANT: Your output MUST be a YAML deck spec, not a binary .pptx file.
 Do NOT attempt to generate PowerPoint XML, base64 data, or any format
@@ -56,8 +56,54 @@ Preferred: offer the YAML as a downloadable file (e.g. a download link or
 file attachment named "deck.yaml") so the user can save it directly.
 Fallback: emit a single ```yaml code block the user can copy-paste into
 a .yaml file and then run `pptx deck build -f deck.yaml`.
-</output-format>
+</output-format>"""
 
+_STYLE_GUIDE = """\
+<style-guide>
+Follow these principles to produce decision-grade slides.
+
+Structure
+- Lead with the answer.  Do not build up to the conclusion.
+- Pyramid Principle: governing thought -> supporting arguments -> evidence.
+- Arguments must be MECE (mutually exclusive, collectively exhaustive).
+- One slide = one message.  Two insights -> two slides.
+
+Titles
+- Use action titles, not topic labels.  The title states the takeaway.
+  Bad:  "Market overview"
+  Good: "Nordic retail banking margins will remain under pressure through 2027"
+- Title storyline reads on its own - skim only titles and understand the
+  full argument.
+- Formulas:
+    Insight:        "[What happened] because [driver]"
+    Comparison:     "[A] outperforms [B] on [criterion]"
+    Implication:    "[Fact] puts [objective] at risk"
+    Recommendation: "[Org] should [action] to achieve [outcome]"
+
+Executive summary slide
+- Situation: what context everyone agrees on.
+- Complication: what changed or created urgency.
+- Answer: the recommended response.
+- Support: 2-3 reasons the answer is correct.
+
+Deck sequence (typical)
+1. Title page
+2. Executive summary (situation -> complication -> resolution)
+3. Context / problem framing (only enough to orient)
+4. Analysis body (current state -> root causes -> options -> recommendation)
+5. Recommendation (explicit, decision-ready)
+6. Implementation / roadmap
+7. Risks and mitigations
+8. Appendix (source data, benchmarks, methodology)
+
+Body content
+- Every claim backed by evidence.  The body proves the headline.
+- Quantify.  Replace vague adjectives with measured claims.
+- Keep text tight: verbs, short bullets, no filler.
+- Move backup detail to appendix - main story stays focused.
+</style-guide>"""
+
+_GENERIC_SLIDE_SCHEMA = """\
 <slide-schema>
 Use this schema to draft presentation content.  Layout assignment and
 template binding happen later, so focus on the slides themselves.
@@ -101,8 +147,9 @@ slides:
       kind: image
       path: path/to/image.png
       image_fit: fit
-</slide-schema>
+</slide-schema>"""
 
+_GENERIC_CONTENT_RULES = """\
 <content-rules>
 - Each slide MUST have a "title".
 - Use "body" for the main text area.  Markdown is auto-detected
@@ -113,56 +160,42 @@ slides:
 - "notes" is optional speaker-notes text (markdown ok).
 - Do NOT include a "layout" key - layout is assigned later when
   binding to a corporate template.
-</content-rules>
-
-<style-guide>
-Follow these principles to produce decision-grade slides.
+</content-rules>"""
 
-Structure
-- Lead with the answer.  Do not build up to the conclusion.
-- Pyramid Principle: governing thought -> supporting arguments -> evidence.
-- Arguments must be MECE (mutually exclusive, collectively exhaustive).
-- One slide = one message.  Two insights -> two slides.
-
-Titles
-- Use action titles, not topic labels.  The title states the takeaway.
-  Bad:  "Market overview"
-  Good: "Nordic retail banking margins will remain under pressure through 2027"
-- Title storyline reads on its own - skim only titles and understand the
-  full argument.
-- Formulas:
-    Insight:        "[What happened] because [driver]"
-    Comparison:     "[A] outperforms [B] on [criterion]"
-    Implication:    "[Fact] puts [objective] at risk"
-    Recommendation: "[Org] should [action] to achieve [outcome]"
-
-Executive summary slide
-- Situation: what context everyone agrees on.
-- Complication: what changed or created urgency.
-- Answer: the recommended response.
-- Support: 2-3 reasons the answer is correct.
-
-Deck sequence (typical)
-1. Title page
-2. Executive summary (situation -> complication -> resolution)
-3. Context / problem framing (only enough to orient)
-4. Analysis body (current state -> root causes -> options -> recommendation)
-5. Recommendation (explicit, decision-ready)
-6. Implementation / roadmap
-7. Risks and mitigations
-8. Appendix (source data, benchmarks, methodology)
-
-Body content
-- Every claim backed by evidence.  The body proves the headline.
-- Quantify.  Replace vague adjectives with measured claims.
-- Keep text tight: verbs, short bullets, no filler.
-- Move backup detail to appendix - main story stays focused.
-</style-guide>
-"""
+_TEMPLATE_CONTENT_RULES = """\
+<content-rules>
+- Each slide MUST have a "layout" key matching one of the layout IDs
+  listed in the <layouts> section.
+- Each slide MUST have a "content" dict that maps placeholder names
+  (from the layout's placeholders) to values.
+- Content type dispatch:
+  - Plain text or markdown: provide a string value directly.
+    Markdown is auto-detected (headings, bullets, **bold**, *italic*).
+  - Image: { kind: image, path: path/to/image.png, image_fit: fit }
+    image_fit accepts: "fit" (default) or "cover".
+  - Table: { kind: table, columns: [...], rows: [[...], ...] }
+  - Chart: { kind: chart, chart_type: column_clustered, categories: [...],
+    series: [{ name: ..., values: [...] }] }
+    chart_type accepts: column_clustered, bar_clustered, line, pie.
+- Respect "required" and "max_lines" guidance from the layout definitions.
+- "notes" is optional speaker-notes text (markdown ok) at the slide level.
+</content-rules>"""
+
+# Recompose generic schema from shared pieces
+_GENERIC_SCHEMA = (
+    _OUTPUT_FORMAT
+    + "\n\n"
+    + _GENERIC_SLIDE_SCHEMA
+    + "\n\n"
+    + _GENERIC_CONTENT_RULES
+    + "\n\n"
+    + _STYLE_GUIDE
+    + "\n"
+)
 
 
 # ---------------------------------------------------------------------------
-# Template-enriched schema
+# Template-enriched schema helpers
 # ---------------------------------------------------------------------------
 
 
@@ -207,21 +240,54 @@ def _example_slide(layout: LayoutContract) -> dict[str, Any]:
     return slide
 
 
-def _build_template_section(manifest: ManifestDocument) -> str:
-    """Return the template-specific portion of the reference doc."""
+def _build_layouts_section(manifest: ManifestDocument) -> str:
+    """Return the <layouts> XML section with all layout definitions."""
     layouts_ref: dict[str, Any] = {}
-    examples: list[dict[str, Any]] = []
-
     for layout in manifest.layouts:
         layouts_ref[layout.id] = _layout_section(layout)
+    layouts_yaml = yaml.safe_dump(layouts_ref, sort_keys=False, allow_unicode=True, width=120)
+    return f"<layouts>\n{layouts_yaml}</layouts>"
+
+
+def _build_deck_schema_section(manifest: ManifestDocument) -> str:
+    """Return the <deck-schema> XML section with DeckSpec example."""
+    examples: list[dict[str, Any]] = []
+    # Use up to 4 representative layouts for examples
+    for layout in manifest.layouts[:4]:
         examples.append(_example_slide(layout))
 
-    doc: dict[str, Any] = {
-        "template": manifest.template.name,
-        "layouts": layouts_ref,
-        "example_slides": examples,
+    example_spec: dict[str, Any] = {
+        "metadata": {
+            "title": "<deck title>",
+            "author": "<author name>",
+        },
+        "slides": examples,
     }
-    return yaml.safe_dump(doc, sort_keys=False, allow_unicode=True, width=120)
+    example_yaml = yaml.safe_dump(example_spec, sort_keys=False, allow_unicode=True, width=120)
+
+    prose = (
+        f"Use this schema to draft presentation content for the "
+        f'"{manifest.template.name}" template.\n'
+        f"Each slide must reference a layout from the <layouts> section and "
+        f"provide content for its placeholders.\n\n"
+    )
+    return f"<deck-schema>\n{prose}{example_yaml}</deck-schema>"
+
+
+def _build_template_schema(manifest: ManifestDocument) -> str:
+    """Compose the unified template-bound schema document."""
+    parts = [
+        _OUTPUT_FORMAT,
+        "",
+        _build_deck_schema_section(manifest),
+        "",
+        _build_layouts_section(manifest),
+        "",
+        _TEMPLATE_CONTENT_RULES,
+        "",
+        _STYLE_GUIDE,
+    ]
+    return "\n".join(parts) + "\n"
 
 
 # ---------------------------------------------------------------------------
@@ -231,9 +297,7 @@ def _build_template_section(manifest: ManifestDocument) -> str:
 
 def build_schema_document(template_dir: Path | None = None) -> str:
     """Return the full reference document as a string."""
-    parts = [_GENERIC_SCHEMA]
     if template_dir is not None:
         manifest = load_effective_manifest(template_dir)
-        parts.append("\n# ── Template-specific layouts ──────────────────────────────────\n")
-        parts.append(_build_template_section(manifest))
-    return "\n".join(parts)
+        return _build_template_schema(manifest)
+    return _GENERIC_SCHEMA

pptx_cli-1.3.5/tests/test_schema.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from unittest.mock import patch
+
+from typer.testing import CliRunner
+
+from pptx_cli.cli import app
+from pptx_cli.commands.schema import build_schema_document
+
+runner = CliRunner()
+
+
+def test_generic_schema_contains_deck_structure() -> None:
+    text = build_schema_document()
+    assert "<slide-schema>" in text
+    assert "metadata:" in text
+    assert "slides:" in text
+    assert "title:" in text
+    assert "body:" in text
+    assert "notes:" in text
+
+
+def test_generic_schema_documents_content_types() -> None:
+    text = build_schema_document()
+    assert "kind: image" in text
+    assert "kind: table" in text
+    assert "kind: chart" in text
+
+
+def test_generic_schema_uses_xml_sections() -> None:
+    text = build_schema_document()
+    assert "<slide-schema>" in text
+    assert "</slide-schema>" in text
+    assert "<content-rules>" in text
+    assert "</content-rules>" in text
+    assert "<style-guide>" in text
+    assert "</style-guide>" in text
+
+
+def test_generic_schema_omits_layout() -> None:
+    text = build_schema_document()
+    assert "Do NOT include" in text
+    assert "layout is assigned later" in text
+
+
+def test_schema_command_outputs_text(tmp_path: str) -> None:
+    result = runner.invoke(app, ["schema", "--no-template", "--no-copy"])
+    assert result.exit_code == 0
+    assert "metadata:" in result.stdout
+    assert "slides:" in result.stdout
+
+
+def test_schema_command_copies_to_clipboard() -> None:
+    with patch("pptx_cli.cli.copy_to_clipboard", return_value=True) as mock_copy:
+        result = runner.invoke(app, ["schema", "--no-template"])
+    assert result.exit_code == 0
+    mock_copy.assert_called_once()
+    assert "copied to clipboard" in result.stderr
+
+
+def test_schema_command_no_copy_skips_clipboard() -> None:
+    with patch("pptx_cli.cli.copy_to_clipboard") as mock_copy:
+        result = runner.invoke(app, ["schema", "--no-template", "--no-copy"])
+    assert result.exit_code == 0
+    mock_copy.assert_not_called()
+
+
+def test_schema_with_template(template_path: str, manifest_dir: str) -> None:
+    # First init a manifest so we can point --template at it
+    init_result = runner.invoke(
+        app,
+        ["init", str(template_path), "--out", str(manifest_dir), "--format", "json"],
+    )
+    assert init_result.exit_code == 0
+
+    result = runner.invoke(app, ["schema", "--template", str(manifest_dir), "--no-copy"])
+    assert result.exit_code == 0
+    assert "<layouts>" in result.stdout
+    assert "<deck-schema>" in result.stdout
+    assert "layout:" in result.stdout
+    assert "content:" in result.stdout
+
+
+def test_template_schema_unified_sections(template_path: str, manifest_dir: str) -> None:
+    init_result = runner.invoke(
+        app,
+        ["init", str(template_path), "--out", str(manifest_dir), "--format", "json"],
+    )
+    assert init_result.exit_code == 0
+
+    result = runner.invoke(app, ["schema", "--template", str(manifest_dir), "--no-copy"])
+    assert result.exit_code == 0
+    assert "<deck-schema>" in result.stdout
+    assert "<layouts>" in result.stdout
+    assert "<content-rules>" in result.stdout
+    assert "<style-guide>" in result.stdout
+
+
+def test_template_schema_has_layout_in_examples(template_path: str, manifest_dir: str) -> None:
+    init_result = runner.invoke(
+        app,
+        ["init", str(template_path), "--out", str(manifest_dir), "--format", "json"],
+    )
+    assert init_result.exit_code == 0
+
+    result = runner.invoke(app, ["schema", "--template", str(manifest_dir), "--no-copy"])
+    assert result.exit_code == 0
+    assert "layout:" in result.stdout
+    assert "content:" in result.stdout
+
+
+def test_template_schema_no_generic_layout_warning(template_path: str, manifest_dir: str) -> None:
+    init_result = runner.invoke(
+        app,
+        ["init", str(template_path), "--out", str(manifest_dir), "--format", "json"],
+    )
+    assert init_result.exit_code == 0
+
+    result = runner.invoke(app, ["schema", "--template", str(manifest_dir), "--no-copy"])
+    assert result.exit_code == 0
+    assert "Do NOT include" not in result.stdout
+
+
+def test_no_template_flag_emits_generic() -> None:
+    result = runner.invoke(app, ["schema", "--no-template", "--no-copy"])
+    assert result.exit_code == 0
+    assert "<slide-schema>" in result.stdout
+    assert "Do NOT include" in result.stdout
+
+
+def test_template_and_no_template_conflict() -> None:
+    result = runner.invoke(app, ["schema", "--template", "some/dir", "--no-template", "--no-copy"])
+    assert result.exit_code != 0
+    assert "mutually exclusive" in result.stderr

pptx_cli-1.3.3/tests/test_schema.py

@@ -1,80 +0,0 @@
-from __future__ import annotations
-
-from unittest.mock import patch
-
-from typer.testing import CliRunner
-
-from pptx_cli.cli import app
-from pptx_cli.commands.schema import build_schema_document
-
-runner = CliRunner()
-
-
-def test_generic_schema_contains_deck_structure() -> None:
-    text = build_schema_document()
-    assert "<slide-schema>" in text
-    assert "metadata:" in text
-    assert "slides:" in text
-    assert "title:" in text
-    assert "body:" in text
-    assert "notes:" in text
-
-
-def test_generic_schema_documents_content_types() -> None:
-    text = build_schema_document()
-    assert "kind: image" in text
-    assert "kind: table" in text
-    assert "kind: chart" in text
-
-
-def test_generic_schema_uses_xml_sections() -> None:
-    text = build_schema_document()
-    assert "<slide-schema>" in text
-    assert "</slide-schema>" in text
-    assert "<content-rules>" in text
-    assert "</content-rules>" in text
-    assert "<style-guide>" in text
-    assert "</style-guide>" in text
-
-
-def test_generic_schema_omits_layout() -> None:
-    text = build_schema_document()
-    assert "Do NOT include" in text
-    assert "layout is assigned later" in text
-
-
-def test_schema_command_outputs_text(tmp_path: str) -> None:
-    result = runner.invoke(app, ["schema", "--no-copy"])
-    assert result.exit_code == 0
-    assert "metadata:" in result.stdout
-    assert "slides:" in result.stdout
-
-
-def test_schema_command_copies_to_clipboard() -> None:
-    with patch("pptx_cli.cli.copy_to_clipboard", return_value=True) as mock_copy:
-        result = runner.invoke(app, ["schema"])
-    assert result.exit_code == 0
-    mock_copy.assert_called_once()
-    assert "copied to clipboard" in result.stderr
-
-
-def test_schema_command_no_copy_skips_clipboard() -> None:
-    with patch("pptx_cli.cli.copy_to_clipboard") as mock_copy:
-        result = runner.invoke(app, ["schema", "--no-copy"])
-    assert result.exit_code == 0
-    mock_copy.assert_not_called()
-
-
-def test_schema_with_template(template_path: str, manifest_dir: str) -> None:
-    # First init a manifest so we can point --template at it
-    init_result = runner.invoke(
-        app,
-        ["init", str(template_path), "--out", str(manifest_dir), "--format", "json"],
-    )
-    assert init_result.exit_code == 0
-
-    result = runner.invoke(app, ["schema", "--template", str(manifest_dir), "--no-copy"])
-    assert result.exit_code == 0
-    assert "template:" in result.stdout
-    assert "layouts:" in result.stdout
-    assert "placeholders:" in result.stdout