pptx-cli 1.0.0__py3-none-any.whl

pptx_cli/__init__.py

@@ -0,0 +1,5 @@
+"""pptx_cli package."""
+
+__all__ = ["__version__"]
+
+__version__ = "1.0.0"

pptx_cli/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

pptx_cli/cli.py

@@ -0,0 +1,372 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+import yaml
+
+from pptx_cli.commands.compose import deck_build, slide_create
+from pptx_cli.commands.guide import build_guide_document
+from pptx_cli.commands.init import run_init
+from pptx_cli.commands.inspect import (
+    doctor,
+    list_assets,
+    list_layouts,
+    list_placeholders,
+    show_layout,
+    show_theme,
+)
+from pptx_cli.commands.manifest_ops import manifest_diff, manifest_schema
+from pptx_cli.commands.validate import validate_command
+from pptx_cli.commands.wrapper import wrapper_generate
+from pptx_cli.core.composition import CompositionError
+from pptx_cli.core.runtime import build_runtime_context, stdout_is_tty
+from pptx_cli.core.validation import ValidationError
+from pptx_cli.models.envelope import CliMessage, Envelope, Metrics
+
+app = typer.Typer(help="Template-bound PowerPoint generation for enterprise decks.")
+layouts_app = typer.Typer(help="Inspect approved layouts from a manifest package.")
+placeholders_app = typer.Typer(help="Inspect placeholders for a layout contract.")
+theme_app = typer.Typer(help="Inspect extracted theme metadata.")
+assets_app = typer.Typer(help="Inspect extracted asset references.")
+slide_app = typer.Typer(help="Create slides from approved layouts.")
+deck_app = typer.Typer(help="Build full decks from structured specs.")
+manifest_app = typer.Typer(help="Work with manifest packages and schemas.")
+wrapper_app = typer.Typer(help="Generate thin template-specific wrapper CLIs.")
+
+app.add_typer(layouts_app, name="layouts")
+app.add_typer(placeholders_app, name="placeholders")
+app.add_typer(theme_app, name="theme")
+app.add_typer(assets_app, name="assets")
+app.add_typer(slide_app, name="slide")
+app.add_typer(deck_app, name="deck")
+app.add_typer(manifest_app, name="manifest")
+app.add_typer(wrapper_app, name="wrapper")
+
+FormatOption = Annotated[
+    str | None,
+    typer.Option("--format", help="Output format: json or text."),
+]
+DryRunOption = Annotated[
+    bool,
+    typer.Option("--dry-run", help="Preview changes without writing files."),
+]
+ManifestOption = Annotated[
+    Path,
+    typer.Option("--manifest", help="Path to the manifest package directory."),
+]
+
+_EXIT_CODE_MAP = {
+    "validation": 10,
+    "policy": 20,
+    "conflict": 40,
+    "io": 50,
+    "internal": 90,
+}
+
+
+def resolve_output_format(runtime: Any, explicit_format: str | None) -> str:
+    if explicit_format is not None:
+        return explicit_format
+    if runtime.llm_mode or not stdout_is_tty():
+        return "json"
+    return "text"
+
+
+def emit_json(envelope: Envelope) -> None:
+    typer.echo(json.dumps(envelope.model_dump(mode="json", exclude_none=True), indent=2))
+
+
+def emit_result(result: Any, envelope: Envelope, format: str) -> None:
+    if format == "json":
+        emit_json(envelope)
+        return
+    if format == "text":
+        typer.echo(yaml.safe_dump(result, sort_keys=False, allow_unicode=True).rstrip())
+        return
+    raise typer.BadParameter("format must be 'json' or 'text'")
+
+
+def _exit_code_for_error(error_code: str) -> int:
+    if error_code.startswith("ERR_VALIDATION"):
+        return _EXIT_CODE_MAP["validation"]
+    if error_code.startswith("ERR_POLICY"):
+        return _EXIT_CODE_MAP["policy"]
+    if error_code.startswith("ERR_CONFLICT"):
+        return _EXIT_CODE_MAP["conflict"]
+    if error_code.startswith("ERR_IO"):
+        return _EXIT_CODE_MAP["io"]
+    return _EXIT_CODE_MAP["internal"]
+
+
+def _message_for_error(
+    error_code: str,
+    message: str,
+    details: dict[str, Any] | None = None,
+) -> CliMessage:
+    if error_code.startswith("ERR_VALIDATION"):
+        suggested_action = "fix_input"
+    elif error_code.startswith("ERR_IO"):
+        suggested_action = "retry"
+    else:
+        suggested_action = "escalate"
+    retryable = error_code.startswith("ERR_IO")
+    return CliMessage(
+        code=error_code,
+        message=message,
+        retryable=retryable,
+        suggested_action=suggested_action,
+        details=details or {},
+    )
+
+
+def fail(
+    command: str,
+    runtime: Any,
+    format: str,
+    error_code: str,
+    message: str,
+    details: dict[str, Any] | None = None,
+) -> None:
+    error = _message_for_error(error_code, message, details)
+    envelope = Envelope(
+        request_id=runtime.request_id,
+        ok=False,
+        command=command,
+        result=None,
+        warnings=[],
+        errors=[error],
+        metrics=Metrics(duration_ms=runtime.duration_ms),
+    )
+    emit_result(None, envelope, format)
+    raise typer.Exit(code=_exit_code_for_error(error_code))
+
+
+def success(
+    command: str,
+    runtime: Any,
+    format: str,
+    result: Any,
+    *,
+    warnings: list[CliMessage] | None = None,
+) -> None:
+    envelope = Envelope(
+        request_id=runtime.request_id,
+        ok=True,
+        command=command,
+        result=result,
+        warnings=warnings or [],
+        errors=[],
+        metrics=Metrics(duration_ms=runtime.duration_ms),
+    )
+    emit_result(result, envelope, format)
+
+
+def execute(command: str, format: str | None, func: Any) -> None:
+    runtime = build_runtime_context()
+    resolved_format = resolve_output_format(runtime, format)
+    try:
+        result = func()
+    except CompositionError as exc:
+        fail(command, runtime, resolved_format, exc.code, str(exc))
+    except ValidationError as exc:
+        fail(command, runtime, resolved_format, exc.code, str(exc))
+    except ValueError as exc:
+        fail(command, runtime, resolved_format, "ERR_VALIDATION_INPUT", str(exc))
+    success(command, runtime, resolved_format, result)
+
+
+@app.command("guide")
+def guide(format: FormatOption = None) -> None:
+    """Show the machine-readable CLI guide."""
+
+    execute("guide.show", format, lambda: build_guide_document().model_dump(mode="json"))
+
+
+@app.command("init")
+def init_command(
+    template: Annotated[Path, typer.Argument(help="Path to the source .pptx template")],
+    out: Annotated[Path, typer.Option("--out", help="Output directory for the manifest package")],
+    dry_run: DryRunOption = False,
+    format: FormatOption = None,
+) -> None:
+    """Initialize a manifest package from a source template."""
+
+    runtime = build_runtime_context()
+    resolved_format = resolve_output_format(runtime, format)
+    if not template.exists():
+        fail(
+            "template.init",
+            runtime,
+            resolved_format,
+            "ERR_IO_NOT_FOUND",
+            f"Template not found: {template}",
+            {"template": str(template)},
+        )
+    if template.suffix.lower() != ".pptx":
+        fail(
+            "template.init",
+            runtime,
+            resolved_format,
+            "ERR_VALIDATION_TEMPLATE_TYPE",
+            "Template input must be a .pptx file",
+            {"template": str(template)},
+        )
+    try:
+        result = run_init(template, out, dry_run=dry_run)
+    except OSError as exc:
+        fail("template.init", runtime, resolved_format, "ERR_IO_WRITE", str(exc))
+    success("template.init", runtime, resolved_format, result)
+
+
+@app.command("doctor")
+def doctor_command(manifest: ManifestOption, format: FormatOption = None) -> None:
+    """Show compatibility findings for a manifest package."""
+
+    execute("doctor.show", format, lambda: doctor(manifest))
+
+
+@layouts_app.command("list")
+def layouts_list(manifest: ManifestOption, format: FormatOption = None) -> None:
+    """List available layouts from a manifest package."""
+
+    execute("layouts.list", format, lambda: list_layouts(manifest))
+
+
+@layouts_app.command("show")
+def layouts_show(
+    layout_id: Annotated[str, typer.Argument(help="Layout ID or source layout name")],
+    manifest: ManifestOption,
+    format: FormatOption = None,
+) -> None:
+    """Show a single layout contract."""
+
+    execute("layouts.show", format, lambda: show_layout(manifest, layout_id))
+
+
+@placeholders_app.command("list")
+def placeholders_list_command(
+    layout_id: Annotated[str, typer.Argument(help="Layout ID or source layout name")],
+    manifest: ManifestOption,
+    format: FormatOption = None,
+) -> None:
+    """List placeholders for a layout."""
+
+    execute("placeholders.list", format, lambda: list_placeholders(manifest, layout_id))
+
+
+@theme_app.command("show")
+def theme_show(manifest: ManifestOption, format: FormatOption = None) -> None:
+    """Show extracted theme metadata."""
+
+    execute("theme.show", format, lambda: show_theme(manifest))
+
+
+@assets_app.command("list")
+def assets_list_command(manifest: ManifestOption, format: FormatOption = None) -> None:
+    """List extracted assets."""
+
+    execute("assets.list", format, lambda: list_assets(manifest))
+
+
+@slide_app.command("create")
+def slide_create_command(
+    manifest: ManifestOption,
+    layout: Annotated[str, typer.Option("--layout", help="Layout ID from the manifest")],
+    out: Annotated[Path, typer.Option("--out", help="Output .pptx file")],
+    set_values: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--set",
+            help="Placeholder assignment like key=value or key=@file",
+        ),
+    ] = None,
+    dry_run: DryRunOption = False,
+    format: FormatOption = None,
+) -> None:
+    """Create a deck containing a single slide from an approved layout."""
+
+    execute(
+        "slide.create",
+        format,
+        lambda: slide_create(
+            manifest,
+            layout,
+            list(set_values or []),
+            out,
+            dry_run=dry_run,
+        ),
+    )
+
+
+@deck_app.command("build")
+def deck_build_command(
+    manifest: ManifestOption,
+    spec: Annotated[Path, typer.Option("--spec", help="Path to the YAML or JSON deck spec")],
+    out: Annotated[Path, typer.Option("--out", help="Output .pptx file")],
+    dry_run: DryRunOption = False,
+    format: FormatOption = None,
+) -> None:
+    """Build a deck from a structured spec."""
+
+    execute("deck.build", format, lambda: deck_build(manifest, spec, out, dry_run=dry_run))
+
+
+@app.command("validate")
+def validate_deck_command(
+    manifest: ManifestOption,
+    deck: Annotated[Path, typer.Option("--deck", help="Path to the generated .pptx deck")],
+    strict: Annotated[
+        bool,
+        typer.Option(
+            "--strict",
+            help="Escalate warnings into validation failures where applicable.",
+        ),
+    ] = False,
+    format: FormatOption = None,
+) -> None:
+    """Validate a generated deck against the manifest contract."""
+
+    execute("validate.run", format, lambda: validate_command(manifest, deck, strict=strict))
+
+
+@manifest_app.command("diff")
+def manifest_diff_command(
+    left: Annotated[Path, typer.Argument(help="Left-hand manifest directory")],
+    right: Annotated[Path, typer.Argument(help="Right-hand manifest directory")],
+    format: FormatOption = None,
+) -> None:
+    """Compare two manifest packages."""
+
+    execute("manifest.diff", format, lambda: manifest_diff(left, right))
+
+
+@manifest_app.command("schema")
+def manifest_schema_command(format: FormatOption = None) -> None:
+    """Emit the JSON schema for manifest.yaml."""
+
+    execute("manifest.schema", format, manifest_schema)
+
+
+@wrapper_app.command("generate")
+def wrapper_generate_command(
+    manifest: ManifestOption,
+    out: Annotated[
+        Path,
+        typer.Option(
+            "--out",
+            help="Output directory for the generated wrapper package",
+        ),
+    ],
+    dry_run: DryRunOption = False,
+    format: FormatOption = None,
+) -> None:
+    """Generate a thin template-specific wrapper scaffold."""
+
+    execute("wrapper.generate", format, lambda: wrapper_generate(manifest, out, dry_run=dry_run))
+
+
+def main() -> None:
+    app()

pptx_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules."""

pptx_cli/commands/compose.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pptx_cli.core.composition import (
+    build_presentation,
+    create_single_slide_spec,
+    parse_set_arguments,
+    save_presentation,
+)
+from pptx_cli.core.manifest_store import load_deck_spec, load_manifest
+
+
+def slide_create(
+    manifest_dir: Path,
+    layout_id: str,
+    set_values: list[str],
+    output_path: Path,
+    *,
+    dry_run: bool,
+) -> dict[str, Any]:
+    manifest = load_manifest(manifest_dir)
+    content = parse_set_arguments(set_values)
+    spec = create_single_slide_spec(layout_id, content)
+    planned_changes = [
+        {
+            "target": str(output_path),
+            "operation": "replace" if output_path.exists() else "create",
+            "artifact_type": "pptx",
+        }
+    ]
+    if not dry_run:
+        prs = build_presentation(manifest_dir, manifest, spec)
+        save_presentation(prs, output_path)
+    return {
+        "dry_run": dry_run,
+        "manifest": str(manifest_dir),
+        "layout": layout_id,
+        "out": str(output_path),
+        "changes": planned_changes,
+        "summary": {"slides": 1, "artifacts": 1},
+    }
+
+
+def deck_build(
+    manifest_dir: Path,
+    spec_path: Path,
+    output_path: Path,
+    *,
+    dry_run: bool,
+) -> dict[str, Any]:
+    manifest = load_manifest(manifest_dir)
+    spec = load_deck_spec(spec_path)
+    planned_changes = [
+        {
+            "target": str(output_path),
+            "operation": "replace" if output_path.exists() else "create",
+            "artifact_type": "pptx",
+        }
+    ]
+    if not dry_run:
+        prs = build_presentation(manifest_dir, manifest, spec)
+        save_presentation(prs, output_path)
+    return {
+        "dry_run": dry_run,
+        "manifest": str(manifest_dir),
+        "spec": str(spec_path),
+        "out": str(output_path),
+        "changes": planned_changes,
+        "summary": {"slides": len(spec.slides), "artifacts": 1},
+        "metadata": spec.metadata,
+    }

pptx_cli/commands/guide.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from pptx_cli.models.envelope import GuideCommand, GuideDocument
+from pptx_cli.models.manifest import DeckSpec, ManifestDocument, ValidationResult
+
+
+def build_guide_document() -> GuideDocument:
+    return GuideDocument(
+        compatibility={
+            "additive_changes": "minor",
+            "breaking_changes": "major",
+        },
+        commands=[
+            GuideCommand(
+                id="guide.show",
+                summary="Show the machine-readable CLI guide",
+                mutates=False,
+                examples=["pptx guide --format json"],
+            ),
+            GuideCommand(
+                id="template.init",
+                summary="Initialize a manifest package from a source template",
+                mutates=True,
+                output_schema={"$ref": "#/definitions/Envelope"},
+                examples=["pptx init Template.pptx --out ./corp-template --dry-run"],
+            ),
+            GuideCommand(
+                id="doctor.show",
+                summary="Show manifest compatibility findings",
+                mutates=False,
+                examples=["pptx doctor --manifest ./corp-template --format json"],
+            ),
+            GuideCommand(
+                id="layouts.list",
+                summary="List available layouts from a manifest package",
+                mutates=False,
+                examples=["pptx layouts list --manifest ./corp-template --format json"],
+            ),
+            GuideCommand(
+                id="layouts.show",
+                summary="Show a single layout contract",
+                mutates=False,
+                examples=["pptx layouts show title-only --manifest ./corp-template --format json"],
+            ),
+            GuideCommand(
+                id="placeholders.list",
+                summary="List placeholders for a layout",
+                mutates=False,
+                examples=[
+                    "pptx placeholders list title-only --manifest ./corp-template --format json"
+                ],
+            ),
+            GuideCommand(
+                id="theme.show",
+                summary="Show theme metadata extracted into the manifest",
+                mutates=False,
+                examples=["pptx theme show --manifest ./corp-template --format json"],
+            ),
+            GuideCommand(
+                id="assets.list",
+                summary="List extracted assets from the manifest package",
+                mutates=False,
+                examples=["pptx assets list --manifest ./corp-template --format json"],
+            ),
+            GuideCommand(
+                id="slide.create",
+                summary="Create a slide from an approved layout",
+                mutates=True,
+                input_schema=DeckSpec.model_json_schema(),
+                examples=[
+                    "pptx slide create --manifest ./corp-template --layout title-only "
+                    "--set title=Hello --out ./out/slide.pptx --dry-run"
+                ],
+            ),
+            GuideCommand(
+                id="deck.build",
+                summary="Build a deck from a structured spec",
+                mutates=True,
+                input_schema=DeckSpec.model_json_schema(),
+                examples=[
+                    "pptx deck build --manifest ./corp-template --spec deck.yaml "
+                    "--out ./out/deck.pptx --dry-run"
+                ],
+            ),
+            GuideCommand(
+                id="validate.run",
+                summary="Validate a deck against a manifest package",
+                mutates=False,
+                output_schema=ValidationResult.model_json_schema(),
+                examples=[
+                    "pptx validate --manifest ./corp-template --deck ./out/deck.pptx "
+                    "--strict --format json"
+                ],
+            ),
+            GuideCommand(
+                id="manifest.diff",
+                summary="Compare two manifest packages and report additive vs. breaking changes",
+                mutates=False,
+                examples=["pptx manifest diff ./corp-template-v1 ./corp-template-v2 --format json"],
+            ),
+            GuideCommand(
+                id="manifest.schema",
+                summary="Emit the JSON schema for manifest.yaml",
+                mutates=False,
+                output_schema=ManifestDocument.model_json_schema(),
+                examples=["pptx manifest schema --format json"],
+            ),
+            GuideCommand(
+                id="wrapper.generate",
+                summary="Generate a thin template-specific wrapper scaffold",
+                mutates=True,
+                examples=[
+                    "pptx wrapper generate --manifest ./corp-template --out ./wrappers/acme "
+                    "--dry-run"
+                ],
+            ),
+        ],
+        exit_codes={
+            "success": 0,
+            "validation_error": 10,
+            "policy_error": 20,
+            "conflict": 40,
+            "io_error": 50,
+            "internal_error": 90,
+        },
+        error_codes={
+            "ERR_VALIDATION_LAYOUT_UNKNOWN": {"exit_code": 10, "retryable": False},
+            "ERR_VALIDATION_PLACEHOLDER_UNKNOWN": {"exit_code": 10, "retryable": False},
+            "ERR_VALIDATION_PLACEHOLDER_REQUIRED": {"exit_code": 10, "retryable": False},
+            "ERR_VALIDATION_CONTENT_TYPE": {"exit_code": 10, "retryable": False},
+            "ERR_IO_NOT_FOUND": {"exit_code": 50, "retryable": False},
+            "ERR_CONFLICT_OUTPUT_EXISTS": {"exit_code": 40, "retryable": False},
+            "ERR_INTERNAL_PLACEHOLDER_MISSING": {"exit_code": 90, "retryable": False},
+        },
+        identifier_conventions={
+            "command_ids": (
+                "canonical dotted identifiers like guide.show, layouts.list, or deck.build"
+            ),
+            "layout_ids": (
+                "slugified manifest layout identifiers derived from template layout names"
+            ),
+            "placeholder_keys": (
+                "logical placeholder keys such as title, subtitle, content_1, or picture"
+            ),
+            "manifest_path": "path to a manifest package directory containing manifest.yaml",
+        },
+        concurrency={
+            "rule": (
+                "Read commands can run in parallel; mutating commands writing the same "
+                "output path must run sequentially."
+            ),
+            "safe_patterns": [
+                "Run guide, layouts, theme, assets, and doctor commands in parallel",
+                "Run deck.build and validate sequentially against the same output file",
+            ],
+        },
+    )

pptx_cli/commands/init.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pptx_cli.core.manifest_store import write_manifest_package
+from pptx_cli.core.template import (
+    build_manifest_package,
+    ensure_manifest_directories,
+    plan_manifest_writes,
+    write_fingerprints,
+)
+
+
+def plan_init(template: Path, output_dir: Path) -> dict[str, Any]:
+    changes = plan_manifest_writes(template, output_dir)
+    return {
+        "template": str(template),
+        "output_dir": str(output_dir),
+        "changes": changes,
+        "artifacts": [item["target"] for item in changes],
+    }
+
+
+def run_init(template: Path, output_dir: Path, *, dry_run: bool) -> dict[str, Any]:
+    plan = plan_init(template, output_dir)
+    if dry_run:
+        return {
+            "dry_run": True,
+            "summary": {"total_outputs": len(plan["artifacts"])},
+            "plan": plan,
+        }
+
+    ensure_manifest_directories(output_dir)
+    manifest, annotations, init_report = build_manifest_package(template, output_dir)
+    write_manifest_package(
+        output_dir,
+        manifest,
+        annotations,
+        init_report.model_dump(mode="json"),
+    )
+    write_fingerprints(output_dir, manifest)
+    return {
+        "dry_run": False,
+        "summary": {
+            "total_outputs": len(plan["artifacts"]),
+            "layout_count": len(manifest.layouts),
+            "asset_count": len(manifest.assets),
+        },
+        "plan": plan,
+        "manifest": str(output_dir),
+    }