AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He
fix(cli): harden help handling and argument validation across scripts
hugohe3b4e92b7d0de3
diff --git a/docs/rules/code-style.md b/docs/rules/code-style.mdindex a1f9c0c1..b937a89c 100644--- a/docs/rules/code-style.md+++ b/docs/rules/code-style.md@@ -121,6 +121,14 @@ if __name__ == "__main__":| Internal helpers `--help` | Module-level: `if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]): print(__doc__); raise SystemExit(0)` || Output | Progress / status to **stderr**; the script's primary output (if any) to stdout |+**Help and argument validation requirements**:++- `-h` / `--help` must be handled by `argparse` (preferred) or an explicit early helper guard before any side effect: no directory creation, file writes, network calls, package installs, or long-running servers.+- Help flags must never be accepted as positional values. Examples: `init --help` must not create a project named `--help`; `export --help` must not write a file named `--help`.+- Scripts with subcommands use `argparse` subparsers. Each subcommand must provide its own help (`<script> <subcmd> --help`) and validate its own required arguments before doing work.+- Missing required arguments and unknown flags must print a usage/error message and exit non-zero. Do not silently ignore unknown flags or continue with partial defaults.+- For internal helper modules that are directly executable only for diagnostics, non-help invocation should either run a documented diagnostic command or print a short "use via ..." message and exit non-zero; it must not fail with an import traceback.+---## 5. Type Hintsdiff --git a/skills/ppt-master/scripts/batch_validate.py b/skills/ppt-master/scripts/batch_validate.pyindex f9a85e0e..421a63ef 100644--- a/skills/ppt-master/scripts/batch_validate.py+++ b/skills/ppt-master/scripts/batch_validate.py@@ -11,6 +11,7 @@ Usage:python3 scripts/batch_validate.py examples projects"""+import argparseimport sysfrom collections import defaultdictfrom pathlib import Path@@ -254,37 +255,44 @@ class BatchValidator:print(f"\n[REPORT] Validation report exported: {output_file}")-def print_usage() -> None:- """Print CLI usage information."""- print("PPT Master - Batch Project Validation Tool\n")- print("Usage:")- print(" python3 scripts/batch_validate.py <directory>")- print(" python3 scripts/batch_validate.py <dir1> <dir2> ...")- print(" python3 scripts/batch_validate.py --all")- print("\nExamples:")- print(" python3 scripts/batch_validate.py examples")- print(" python3 scripts/batch_validate.py projects")- print(" python3 scripts/batch_validate.py examples projects")- print(" python3 scripts/batch_validate.py --all")+def build_parser() -> argparse.ArgumentParser:+ """Build the command-line parser."""+ parser = argparse.ArgumentParser(+ description="Validate one or more PPT Master project directories.",+ formatter_class=argparse.RawDescriptionHelpFormatter,+ epilog="""Examples:+ python3 scripts/batch_validate.py examples+ python3 scripts/batch_validate.py projects+ python3 scripts/batch_validate.py examples projects+ python3 scripts/batch_validate.py --all+""",+ )+ parser.add_argument("directories", nargs="*", help="Directories to scan")+ parser.add_argument("--all", action="store_true", help="Validate examples and projects")+ parser.add_argument("--export", action="store_true", help="Write a validation report")+ parser.add_argument(+ "--output",+ default="validation_report.txt",+ help="Report path when --export is used",+ )+ return parser-def main() -> None:+def main(argv: list[str] | None = None) -> int:"""Run the CLI entry point."""- if len(sys.argv) < 2:- print_usage()- sys.exit(0)-- if sys.argv[1] in {"-h", "--help", "help"}:- print_usage()- sys.exit(0)+ parser = build_parser()+ args = parser.parse_args(argv)validator = BatchValidator()- # Process arguments- if '--all' in sys.argv:+ if args.all:directories = ['examples', 'projects']else:- directories = [arg for arg in sys.argv[1:] if not arg.startswith('--')]+ directories = args.directories++ if not directories:+ parser.print_help()+ return 0# Validate each directoryfor directory in directories:@@ -297,22 +305,16 @@ def main() -> None:validator.print_summary()# Export report (if specified)- if '--export' in sys.argv:- output_file = 'validation_report.txt'- if '--output' in sys.argv:- idx = sys.argv.index('--output')- if idx + 1 < len(sys.argv):- output_file = sys.argv[idx + 1]- validator.export_report(output_file)+ if args.export:+ validator.export_report(args.output)# Return exit codeif validator.summary['has_errors'] > 0:- sys.exit(1)+ return 1elif validator.summary['has_warnings'] > 0:- sys.exit(2)- else:- sys.exit(0)+ return 2+ return 0if __name__ == '__main__':- main()+ raise SystemExit(main())diff --git a/skills/ppt-master/scripts/config.py b/skills/ppt-master/scripts/config.pyindex eabee913..73c97608 100644--- a/skills/ppt-master/scripts/config.py+++ b/skills/ppt-master/scripts/config.py@@ -14,10 +14,11 @@ Usage:colors = Config.get_color_scheme('consulting')"""-from pathlib import Path-from typing import Dict, List, Optional, Any+import argparseimport jsonimport os+from pathlib import Path+from typing import Dict, List, Optional, Any# ============================================================@@ -692,65 +693,66 @@ class Config:# Command Line Interface# ============================================================-def print_usage() -> None:- """Print CLI usage information."""- print("PPT Master - Configuration Management Tool\n")- print("Usage:")- print(" python3 scripts/config.py list-formats # List all canvas formats")- print(" python3 scripts/config.py list-colors # List all color schemes")- print(" python3 scripts/config.py list-industries # List all industry colors")- print(" python3 scripts/config.py export # Export configuration to JSON")- print(" python3 scripts/config.py format <key> # View a specific canvas format")---def main() -> None:+def build_parser() -> argparse.ArgumentParser:+ """Build the command-line parser."""+ parser = argparse.ArgumentParser(+ description="PPT Master configuration management tool.",+ )+ subparsers = parser.add_subparsers(dest="command", required=True)+ subparsers.add_parser("list-formats", help="List all canvas formats")+ subparsers.add_parser("list-colors", help="List all color schemes")+ subparsers.add_parser("list-industries", help="List all industry colors")++ export = subparsers.add_parser("export", help="Export configuration to JSON")+ export.add_argument(+ "output_path",+ nargs="?",+ help="Output JSON path (backward-compatible positional form)",+ )+ export.add_argument(+ "-o",+ "--output",+ default=None,+ help="Output JSON path (default: config_export.json)",+ )++ format_parser = subparsers.add_parser("format", help="View a specific canvas format")+ format_parser.add_argument("key", choices=sorted(CANVAS_FORMATS), help="Canvas format key")+ return parser+++def main(argv: list[str] | None = None) -> int:"""Command line entry point."""- import sys-- if len(sys.argv) < 2:- print_usage()- return-- command = sys.argv[1]- if command in {"-h", "--help", "help"}:- print_usage()- return+ parser = build_parser()+ args = parser.parse_args(argv)- if command == 'list-formats':+ if args.command == 'list-formats':print("\nCanvas Format List:\n")for key, info in CANVAS_FORMATS.items():print(f" {key:15} | {info['name']:15} | {info['dimensions']:12} | {info['use_case']}")- elif command == 'list-colors':+ elif args.command == 'list-colors':print("\nColor Scheme List:\n")for key, info in DESIGN_COLORS.items():print(f" {key:12} | {info['name']:15} | Primary: {info['primary']}")- elif command == 'list-industries':+ elif args.command == 'list-industries':print("\nIndustry Color List:\n")for key, info in INDUSTRY_COLORS.items():print(f" {key:15} | {info['name']:15} | Primary: {info['primary']}")- elif command == 'export':- output_file = sys.argv[2] if len(- sys.argv) > 2 else 'config_export.json'- Config.export_config(output_file)+ elif args.command == 'export':+ Config.export_config(args.output or args.output_path or "config_export.json")- elif command == 'format' and len(sys.argv) > 2:- format_key = sys.argv[2]- info = Config.get_canvas_format(format_key)- if info:- print(f"\nCanvas Format: {format_key}\n")- for key, value in info.items():- print(f" {key}: {value}")- else:- print(f"[ERROR] Format not found: {format_key}")- print(f" Available formats: {', '.join(CANVAS_FORMATS.keys())}")+ elif args.command == 'format':+ info = Config.get_canvas_format(args.key)+ print(f"\nCanvas Format: {args.key}\n")+ for key, value in info.items():+ print(f" {key}: {value}")- else:- print(f"[ERROR] Unknown command: {command}")+ return 0if __name__ == '__main__':- main()+ raise SystemExit(main())diff --git a/skills/ppt-master/scripts/error_helper.py b/skills/ppt-master/scripts/error_helper.pyindex 7c65b327..2046b9a4 100644--- a/skills/ppt-master/scripts/error_helper.py+++ b/skills/ppt-master/scripts/error_helper.py@@ -5,6 +5,7 @@ PPT Master - Error Message HelperProvides user-friendly error messages and specific fix suggestions."""+import argparsefrom typing import Dict, List, Optional@@ -419,28 +420,45 @@ class ErrorHelper:print("-" * 80)-def main() -> None:+def build_parser() -> argparse.ArgumentParser:+ """Build the command-line parser."""+ parser = argparse.ArgumentParser(+ description="Look up PPT Master error messages and suggested fixes.",+ )+ parser.add_argument(+ "error_type",+ nargs="?",+ choices=sorted(ErrorHelper.ERROR_SOLUTIONS),+ help="Error type to explain",+ )+ parser.add_argument(+ "context",+ nargs="*",+ metavar="key=value",+ help="Optional context values used by templates",+ )+ return parser+++def main(argv: list[str] | None = None) -> int:"""Run the CLI entry point for error lookup."""- import sys+ parser = build_parser()+ args = parser.parse_args(argv)- if len(sys.argv) > 1:- error_type = sys.argv[1]- if error_type in {'-h', '--help', 'help'}:- ErrorHelper.print_help()- return-- context = {}+ if not args.error_type:+ ErrorHelper.print_help()+ return 0- # Parse context parameters- for arg in sys.argv[2:]:- if '=' in arg:- key, value = arg.split('=', 1)- context[key] = value+ context = {}+ for item in args.context:+ if '=' not in item:+ parser.error(f"context values must use key=value syntax: {item}")+ key, value = item.split('=', 1)+ context[key] = value- print(ErrorHelper.format_error_message(error_type, context))- else:- ErrorHelper.print_help()+ print(ErrorHelper.format_error_message(args.error_type, context))+ return 0if __name__ == '__main__':- main()+ raise SystemExit(main())diff --git a/skills/ppt-master/scripts/image_backends/backend_bfl.py b/skills/ppt-master/scripts/image_backends/backend_bfl.pyindex 77459a72..c07c2864 100644--- a/skills/ppt-master/scripts/image_backends/backend_bfl.py+++ b/skills/ppt-master/scripts/image_backends/backend_bfl.py@@ -10,10 +10,10 @@ Configuration keys:import sys-if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]):+if __name__ == "__main__":print(__doc__)print("Use via: python3 skills/ppt-master/scripts/image_gen.py \"prompt\" --backend bfl")- raise SystemExit(0)+ raise SystemExit(0 if any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]) else 1)import osimport timediff --git a/skills/ppt-master/scripts/image_backends/backend_common.py b/skills/ppt-master/scripts/image_backends/backend_common.pyindex cdba2e7d..ce6392ac 100644--- a/skills/ppt-master/scripts/image_backends/backend_common.py+++ b/skills/ppt-master/scripts/image_backends/backend_common.py@@ -5,10 +5,10 @@ Shared helpers for image generation backends.import sys-if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]):+if __name__ == "__main__":print(__doc__)print("This is an internal helper module used by image_gen.py backends.")- raise SystemExit(0)+ raise SystemExit(0 if any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]) else 1)import ioimport osdiff --git a/skills/ppt-master/scripts/image_backends/backend_fal.py b/skills/ppt-master/scripts/image_backends/backend_fal.pyindex 66ef790b..cde523b2 100644--- a/skills/ppt-master/scripts/image_backends/backend_fal.py+++ b/skills/ppt-master/scripts/image_backends/backend_fal.py@@ -10,10 +10,10 @@ Configuration keys:import sys-if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]):+if __name__ == "__main__":print(__doc__)print("Use via: python3 skills/ppt-master/scripts/image_gen.py \"prompt\" --backend fal")- raise SystemExit(0)+ raise SystemExit(0 if any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]) else 1)import osimport timediff --git a/skills/ppt-master/scripts/image_backends/backend_gemini.py b/skills/ppt-master/scripts/image_backends/backend_gemini.pyindex 2ef90b3c..139087a2 100644--- a/skills/ppt-master/scripts/image_backends/backend_gemini.py+++ b/skills/ppt-master/scripts/image_backends/backend_gemini.py@@ -16,10 +16,10 @@ Dependencies:import sys-if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]):+if __name__ == "__main__":print(__doc__)print("Use via: python3 skills/ppt-master/scripts/image_gen.py \"prompt\" --backend gemini")- raise SystemExit(0)+ raise SystemExit(0 if any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]) else 1)import osimport timediff --git a/skills/ppt-master/scripts/image_backends/backend_ideogram.py b/skills/ppt-master/scripts/image_backends/backend_ideogram.pyindex 45b799b8..09d54883 100644--- a/skills/ppt-master/scripts/image_backends/backend_ideogram.py+++ b/skills/ppt-master/scripts/image_backends/backend_ideogram.py@@ -10,10 +10,10 @@ Configuration keys:import sys-if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]):+if __name__ == "__main__":print(__doc__)print("Use via: python3 skills/ppt-master/scripts/image_gen.py \"prompt\" --backend ideogram")- raise SystemExit(0)+ raise SystemExit(0 if any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]) else 1)import osimport timediff --git a/skills/ppt-master/scripts/image_backends/backend_minimax.py b/skills/ppt-master/scripts/image_backends/backend_minimax.pyindex c6951fff..5b20b31c 100644--- a/skills/ppt-master/scripts/image_backends/backend_minimax.py+++ b/skills/ppt-master/scripts/image_backends/backend_minimax.py@@ -10,10 +10,10 @@ Configuration keys:import sys-if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]):+if __name__ == "__main__":print(__doc__)print("Use via: python3 skills/ppt-master/scripts/image_gen.py \"prompt\" --backend minimax")- raise SystemExit(0)+ raise SystemExit(0 if any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]) else 1)import base64import osdiff --git a/skills/ppt-master/scripts/image_backends/backend_openai.py b/skills/ppt-master/scripts/image_backends/backend_openai.pyindex 752c3684..4a9213ba 100644--- a/skills/ppt-master/scripts/image_backends/backend_openai.py+++ b/skills/ppt-master/scripts/image_backends/backend_openai.py@@ -23,10 +23,10 @@ Dependencies:import sys-if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]):+if __name__ == "__main__":print(__doc__)print("Use via: python3 skills/ppt-master/scripts/image_gen.py \"prompt\" --backend openai")- raise SystemExit(0)+ raise SystemExit(0 if any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]) else 1)import base64import osdiff --git a/skills/ppt-master/scripts/image_backends/backend_openrouter.py b/skills/ppt-master/scripts/image_backends/backend_openrouter.pyindex a12ff190..4e029aef 100644--- a/skills/ppt-master/scripts/image_backends/backend_openrouter.py+++ b/skills/ppt-master/scripts/image_backends/backend_openrouter.py@@ -10,10 +10,10 @@ Configuration keys:import sys-if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]):+if __name__ == "__main__":print(__doc__)print("Use via: python3 skills/ppt-master/scripts/image_gen.py \"prompt\" --backend openrouter")- raise SystemExit(0)+ raise SystemExit(0 if any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]) else 1)import base64import osdiff --git a/skills/ppt-master/scripts/image_backends/backend_qwen.py b/skills/ppt-master/scripts/image_backends/backend_qwen.pyindex 767b69c8..96dd7be5 100644--- a/skills/ppt-master/scripts/image_backends/backend_qwen.py+++ b/skills/ppt-master/scripts/image_backends/backend_qwen.py@@ -10,10 +10,10 @@ Configuration keys:import sys-if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]):+if __name__ == "__main__":print(__doc__)print("Use via: python3 skills/ppt-master/scripts/image_gen.py \"prompt\" --backend qwen")- raise SystemExit(0)+ raise SystemExit(0 if any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]) else 1)import osimport timediff --git a/skills/ppt-master/scripts/image_backends/backend_replicate.py b/skills/ppt-master/scripts/image_backends/backend_replicate.pyindex 27822f3f..c355f6bf 100644--- a/skills/ppt-master/scripts/image_backends/backend_replicate.py+++ b/skills/ppt-master/scripts/image_backends/backend_replicate.py@@ -10,10 +10,10 @@ Configuration keys:import sys-if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]):+if __name__ == "__main__":print(__doc__)print("Use via: python3 skills/ppt-master/scripts/image_gen.py \"prompt\" --backend replicate")- raise SystemExit(0)+ raise SystemExit(0 if any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]) else 1)import osimport timediff --git a/skills/ppt-master/scripts/image_backends/backend_siliconflow.py b/skills/ppt-master/scripts/image_backends/backend_siliconflow.pyindex b9fb2259..96dd8407 100644--- a/skills/ppt-master/scripts/image_backends/backend_siliconflow.py+++ b/skills/ppt-master/scripts/image_backends/backend_siliconflow.py@@ -10,10 +10,10 @@ Configuration keys:import sys-if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]):+if __name__ == "__main__":print(__doc__)print("Use via: python3 skills/ppt-master/scripts/image_gen.py \"prompt\" --backend siliconflow")- raise SystemExit(0)+ raise SystemExit(0 if any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]) else 1)import osimport timediff --git a/skills/ppt-master/scripts/image_backends/backend_stability.py b/skills/ppt-master/scripts/image_backends/backend_stability.pyindex 93bebc0c..64b59242 100644--- a/skills/ppt-master/scripts/image_backends/backend_stability.py+++ b/skills/ppt-master/scripts/image_backends/backend_stability.py@@ -10,10 +10,10 @@ Configuration keys:import sys-if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]):+if __name__ == "__main__":print(__doc__)print("Use via: python3 skills/ppt-master/scripts/image_gen.py \"prompt\" --backend stability")- raise SystemExit(0)+ raise SystemExit(0 if any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]) else 1)import osimport timediff --git a/skills/ppt-master/scripts/image_backends/backend_volcengine.py b/skills/ppt-master/scripts/image_backends/backend_volcengine.pyindex 20af79f9..3b437d96 100644--- a/skills/ppt-master/scripts/image_backends/backend_volcengine.py+++ b/skills/ppt-master/scripts/image_backends/backend_volcengine.py@@ -10,10 +10,10 @@ Configuration keys:import sys-if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]):+if __name__ == "__main__":print(__doc__)print("Use via: python3 skills/ppt-master/scripts/image_gen.py \"prompt\" --backend volcengine")- raise SystemExit(0)+ raise SystemExit(0 if any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]) else 1)import osimport timediff --git a/skills/ppt-master/scripts/image_backends/backend_zhipu.py b/skills/ppt-master/scripts/image_backends/backend_zhipu.pyindex ed9814d3..e0cec539 100644--- a/skills/ppt-master/scripts/image_backends/backend_zhipu.py+++ b/skills/ppt-master/scripts/image_backends/backend_zhipu.py@@ -10,10 +10,10 @@ Configuration keys:import sys-if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]):+if __name__ == "__main__":print(__doc__)print("Use via: python3 skills/ppt-master/scripts/image_gen.py \"prompt\" --backend zhipu")- raise SystemExit(0)+ raise SystemExit(0 if any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]) else 1)import osimport timediff --git a/skills/ppt-master/scripts/image_sources/provider_common.py b/skills/ppt-master/scripts/image_sources/provider_common.pyindex 169b1a4f..c63cef99 100644--- a/skills/ppt-master/scripts/image_sources/provider_common.py+++ b/skills/ppt-master/scripts/image_sources/provider_common.py@@ -18,10 +18,10 @@ from __future__ import annotationsimport sys-if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]):+if __name__ == "__main__":print(__doc__)print("This is an internal helper module used by image_search.py and the four web image providers.")- raise SystemExit(0)+ raise SystemExit(0 if any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]) else 1)import refrom dataclasses import dataclass, fielddiff --git a/skills/ppt-master/scripts/image_sources/provider_openverse.py b/skills/ppt-master/scripts/image_sources/provider_openverse.pyindex 6941d5e8..2e03523b 100644--- a/skills/ppt-master/scripts/image_sources/provider_openverse.py+++ b/skills/ppt-master/scripts/image_sources/provider_openverse.py@@ -10,9 +10,10 @@ from __future__ import annotationsimport sys-if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]):+if __name__ == "__main__":print(__doc__)- raise SystemExit(0)+ print("Use via: python3 skills/ppt-master/scripts/image_search.py ...")+ raise SystemExit(0 if any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]) else 1)import requestsdiff --git a/skills/ppt-master/scripts/image_sources/provider_pexels.py b/skills/ppt-master/scripts/image_sources/provider_pexels.pyindex 11e7a22b..353408b4 100644--- a/skills/ppt-master/scripts/image_sources/provider_pexels.py+++ b/skills/ppt-master/scripts/image_sources/provider_pexels.py@@ -11,9 +11,10 @@ from __future__ import annotationsimport sys-if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]):+if __name__ == "__main__":print(__doc__)- raise SystemExit(0)+ print("Use via: python3 skills/ppt-master/scripts/image_search.py ...")+ raise SystemExit(0 if any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]) else 1)import osdiff --git a/skills/ppt-master/scripts/image_sources/provider_pixabay.py b/skills/ppt-master/scripts/image_sources/provider_pixabay.pyindex 0ec3706a..47c97ba3 100644--- a/skills/ppt-master/scripts/image_sources/provider_pixabay.py+++ b/skills/ppt-master/scripts/image_sources/provider_pixabay.py@@ -11,9 +11,10 @@ from __future__ import annotationsimport sys-if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]):+if __name__ == "__main__":print(__doc__)- raise SystemExit(0)+ print("Use via: python3 skills/ppt-master/scripts/image_search.py ...")+ raise SystemExit(0 if any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]) else 1)import osdiff --git a/skills/ppt-master/scripts/image_sources/provider_wikimedia.py b/skills/ppt-master/scripts/image_sources/provider_wikimedia.pyindex c507a056..03debe8c 100644--- a/skills/ppt-master/scripts/image_sources/provider_wikimedia.py+++ b/skills/ppt-master/scripts/image_sources/provider_wikimedia.py@@ -14,9 +14,10 @@ from __future__ import annotationsimport sys-if __name__ == "__main__" and any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]):+if __name__ == "__main__":print(__doc__)- raise SystemExit(0)+ print("Use via: python3 skills/ppt-master/scripts/image_search.py ...")+ raise SystemExit(0 if any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]) else 1)import htmlimport rediff --git a/skills/ppt-master/scripts/project_manager.py b/skills/ppt-master/scripts/project_manager.pyindex ab5d4fea..0a18140b 100644--- a/skills/ppt-master/scripts/project_manager.py+++ b/skills/ppt-master/scripts/project_manager.py@@ -10,6 +10,7 @@ Usage:from __future__ import annotations+import argparseimport jsonimport reimport shutil@@ -745,89 +746,71 @@ class ProjectManager:}-def print_usage() -> None:- """Print CLI usage information from the module docstring."""- print(__doc__)---def parse_init_args(argv: list[str]) -> tuple[str, str, str | None]:- """Parse arguments for the `init` subcommand."""- if len(argv) < 3:- raise ValueError("Project name is required")-- project_name = argv[2]- canvas_format = "ppt169"- base_dir = None-- i = 3- while i < len(argv):- if argv[i] == "--format" and i + 1 < len(argv):- canvas_format = argv[i + 1]- i += 2- elif argv[i] == "--dir" and i + 1 < len(argv):- base_dir = argv[i + 1]- i += 2- else:- i += 1-- return project_name, canvas_format, base_dir---def parse_import_args(argv: list[str]) -> tuple[str, list[str], bool, bool]:- """Parse arguments for the `import-sources` subcommand."""- if len(argv) < 4:- raise ValueError("Project path and at least one source are required")+def build_parser() -> argparse.ArgumentParser:+ """Build the command-line parser."""+ parser = argparse.ArgumentParser(+ description="PPT Master project management helpers.",+ formatter_class=argparse.RawDescriptionHelpFormatter,+ epilog="""Examples:+ python3 scripts/project_manager.py init demo --format ppt169+ python3 scripts/project_manager.py import-sources projects/demo file.md --move+ python3 scripts/project_manager.py validate projects/demo+ python3 scripts/project_manager.py info projects/demo+""",+ )+ subparsers = parser.add_subparsers(dest="command", required=True)- project_path = argv[2]- move = False- copy = False- sources: list[str] = []+ init = subparsers.add_parser("init", help="Create a project directory")+ init.add_argument("project_name", help="Project name")+ init.add_argument("--format", default="ppt169", help="Canvas format (default: ppt169)")+ init.add_argument("--dir", default=None, help="Base directory for the project")- for arg in argv[3:]:- if arg == "--move":- move = True- elif arg == "--copy":- copy = True- else:- sources.append(arg)+ import_sources = subparsers.add_parser(+ "import-sources",+ help="Import source files or URLs into a project",+ )+ import_sources.add_argument("project_path", help="Project directory")+ import_sources.add_argument("sources", nargs="+", help="Source files or URLs")+ mode = import_sources.add_mutually_exclusive_group()+ mode.add_argument("--move", action="store_true", help="Move local source files")+ mode.add_argument("--copy", action="store_true", help="Copy local source files")- if move and copy:- raise ValueError("--move and --copy are mutually exclusive")+ validate = subparsers.add_parser("validate", help="Validate a project directory")+ validate.add_argument("project_path", help="Project directory")- return project_path, sources, move, copy+ info = subparsers.add_parser("info", help="Print project metadata")+ info.add_argument("project_path", help="Project directory")+ return parser-def main() -> None:+def main(argv: list[str] | None = None) -> int:"""Run the CLI entry point."""- if len(sys.argv) < 2:- print_usage()- sys.exit(1)-- # Help anywhere — top-level or after a subcommand (e.g. `init --help`) —- # prints usage and exits; never treat a help flag as a positional argument.- if any(arg in {"-h", "--help", "help"} for arg in sys.argv[1:]):- print_usage()- sys.exit(0)-- command = sys.argv[1]-+ parser = build_parser()+ args = parser.parse_args(argv)manager = ProjectManager()try:- if command == "init":- project_name, canvas_format, base_dir = parse_init_args(sys.argv)- project_path = manager.init_project(project_name, canvas_format, base_dir=base_dir)+ if args.command == "init":+ project_path = manager.init_project(+ args.project_name,+ args.format,+ base_dir=args.dir,+ )print(f"[OK] Project initialized: {project_path}")print("Next:")print("1. Put source files into sources/ (or use import-sources)")print("2. Save your design spec to the project root")print("3. Generate SVG files into svg_output/")- return-- if command == "import-sources":- project_path, sources, move, copy = parse_import_args(sys.argv)- summary = manager.import_sources(project_path, sources, move=move, copy=copy)- print(f"[OK] Imported sources into: {project_path}")+ return 0++ if args.command == "import-sources":+ summary = manager.import_sources(+ args.project_path,+ args.sources,+ move=args.move,+ copy=args.copy,+ )+ print(f"[OK] Imported sources into: {args.project_path}")if summary["archived"]:print("\nArchived originals / URL records:")for item in summary["archived"]:@@ -848,13 +831,10 @@ def main() -> None:print("\nSkipped:")for item in summary["skipped"]:print(f" - {item}")- return-- if command == "validate":- if len(sys.argv) < 3:- raise ValueError("Project path is required")+ return 0- project_path = sys.argv[2]+ if args.command == "validate":+ project_path = args.project_pathis_valid, errors, warnings = manager.validate_project(project_path)print(f"\nProject validation: {project_path}")@@ -876,14 +856,11 @@ def main() -> None:print("\n[OK] Project structure is valid, with warnings.")else:print("\n[ERROR] Project structure is invalid.")- sys.exit(1)- return+ return 1+ return 0- if command == "info":- if len(sys.argv) < 3:- raise ValueError("Project path is required")-- project_path = sys.argv[2]+ if args.command == "info":+ project_path = args.project_pathinfo = manager.get_project_info(project_path)print(f"\nProject info: {info['name']}")@@ -896,14 +873,13 @@ def main() -> None:print(f"Source count: {info['source_count']}")print(f"Canvas format: {info['canvas_format']}")print(f"Created: {info['create_date']}")- return+ return 0- raise ValueError(f"Unknown command: {command}")+ parser.error(f"Unknown command: {args.command}")except Exception as exc:print(f"[ERROR] {exc}")- print_usage()- sys.exit(1)+ return 1if __name__ == "__main__":- main()+ raise SystemExit(main())diff --git a/skills/ppt-master/scripts/project_utils.py b/skills/ppt-master/scripts/project_utils.pyindex f19b0c21..f85d7472 100644--- a/skills/ppt-master/scripts/project_utils.py+++ b/skills/ppt-master/scripts/project_utils.py@@ -6,6 +6,7 @@ Provides common functions for project information parsing and validation,reusable by other tools."""+import argparseimport refrom pathlib import Pathfrom datetime import datetime@@ -438,45 +439,47 @@ def get_project_stats(project_path: str) -> Dict:return stats+def build_parser() -> argparse.ArgumentParser:+ """Build the command-line parser for the diagnostic entry point."""+ parser = argparse.ArgumentParser(description="Inspect and validate a PPT Master project.")+ parser.add_argument("project_path", help="Project directory")+ return parser+++def main(argv: list[str] | None = None) -> int:+ """Run the diagnostic CLI entry point."""+ parser = build_parser()+ args = parser.parse_args(argv)+ project_path = args.project_path+ info = get_project_info(project_path)++ print(f"\nProject Info: {info['dir_name']}")+ print("=" * 60)+ print(f"Project Name: {info['name']}")+ print(f"Canvas Format: {info['format_name']} ({info['format']})")+ print(f"Created: {info['date_formatted']}")+ print(f"SVG Files: {info['svg_count']}")+ print(f"README: {'Yes' if info['has_readme'] else 'No'}")+ print(f"Design Spec: {'Yes' if info['has_spec'] else 'No'}")++ print("\nValidation Results:")+ print("-" * 60)+ is_valid, errors, warnings = validate_project_structure(project_path)++ if errors:+ print("[ERROR]")+ for error in errors:+ print(f" - {error}")++ if warnings:+ print("[WARN]")+ for warning in warnings:+ print(f" - {warning}")++ if is_valid and not warnings:+ print("[OK] Project structure is complete, no issues found")+ return 0 if is_valid else 1++if __name__ == '__main__':- # Test code- import sys-- def print_usage() -> None:- print("Usage: python3 project_utils.py <project_path>")-- if len(sys.argv) > 1:- if sys.argv[1] in {'-h', '--help', 'help'}:- print_usage()- sys.exit(0)-- project_path = sys.argv[1]- info = get_project_info(project_path)-- print(f"\nProject Info: {info['dir_name']}")- print("=" * 60)- print(f"Project Name: {info['name']}")- print(f"Canvas Format: {info['format_name']} ({info['format']})")- print(f"Created: {info['date_formatted']}")- print(f"SVG Files: {info['svg_count']}")- print(f"README: {'Yes' if info['has_readme'] else 'No'}")- print(f"Design Spec: {'Yes' if info['has_spec'] else 'No'}")-- print("\nValidation Results:")- print("-" * 60)- is_valid, errors, warnings = validate_project_structure(project_path)-- if errors:- print("[ERROR]")- for error in errors:- print(f" - {error}")-- if warnings:- print("[WARN]")- for warning in warnings:- print(f" - {warning}")-- if is_valid and not warnings:- print("[OK] Project structure is complete, no issues found")- else:- print_usage()+ raise SystemExit(main())diff --git a/skills/ppt-master/scripts/rotate_images.py b/skills/ppt-master/scripts/rotate_images.pyindex c5626bd1..20e0cb1f 100644--- a/skills/ppt-master/scripts/rotate_images.py+++ b/skills/ppt-master/scripts/rotate_images.py@@ -12,9 +12,9 @@ Usage:"""-import os-import sys+import argparseimport json+import osimport refrom pathlib import Pathfrom typing import List, Dict, Union, Any, Optional@@ -521,55 +521,59 @@ class ImageRotator:</html>"""-def main() -> None:- """Run the CLI entry point."""- if len(sys.argv) < 2:- print(__doc__)- sys.exit(1)+def build_parser() -> argparse.ArgumentParser:+ """Build the command-line parser."""+ parser = argparse.ArgumentParser(+ description="Manage image orientation and manual rotation fixes.",+ formatter_class=argparse.RawDescriptionHelpFormatter,+ epilog="""Examples:+ python3 scripts/rotate_images.py gen projects/demo/images+ python3 scripts/rotate_images.py fix fixes.json+ python3 scripts/rotate_images.py auto projects/demo/images+""",+ )+ subparsers = parser.add_subparsers(dest="command", required=True)- command = sys.argv[1]- if command in {"-h", "--help", "help"}:- print(__doc__)- sys.exit(0)+ gen = subparsers.add_parser("gen", help="Generate the visual rotation HTML tool")+ gen.add_argument("images_directory", help="Images directory")- rotator = ImageRotator()+ fix = subparsers.add_parser("fix", help="Apply rotations from a fixes JSON file")+ fix.add_argument("fixes_json", help="Path to fixes.json")++ auto = subparsers.add_parser("auto", help="Automatically fix EXIF orientation")+ auto.add_argument("images_directory", help="Images directory")+ return parser- if command == 'gen':- if len(sys.argv) < 3:- print("[ERROR] Error: images directory path is required")- print("Usage: python3 scripts/rotate_images.py gen <images_directory>")- sys.exit(1)- target_dir = sys.argv[2]+def main(argv: list[str] | None = None) -> int:+ """Run the CLI entry point."""+ parser = build_parser()+ args = parser.parse_args(argv)+ rotator = ImageRotator()++ if args.command == 'gen':+ target_dir = args.images_directorytry:output_path = rotator.generate_html_tool(target_dir)print(f"[OK] HTML tool created: {output_path}")print(f"[LINK] Open in browser: file:///{Path(output_path).as_posix()}")except Exception as e:print(f"[ERROR] Generation failed: {e}")- sys.exit(1)+ return 1+ return 0- elif command == 'fix':- if len(sys.argv) < 3:- print("[ERROR] Error: fixes.json path is required")- print("Usage: python3 scripts/rotate_images.py fix <fixes.json>")- sys.exit(1)-- json_file = sys.argv[2]+ if args.command == 'fix':+ json_file = args.fixes_jsontry:stats = rotator.apply_fixes(json_file)print(f"\n[DONE] Processing complete: {stats['success']} succeeded / {stats['total']} total")except Exception as e:print(f"[ERROR] Execution failed: {e}")- sys.exit(1)-- elif command == 'auto':- if len(sys.argv) < 3:- print("[ERROR] Error: images directory path is required")- print("Usage: python3 scripts/rotate_images.py auto <images_directory>")- sys.exit(1)+ return 1+ return 0- target_dir = sys.argv[2]+ if args.command == 'auto':+ target_dir = args.images_directorytry:# Only perform automatic EXIF fixcount = rotator.auto_fix_exif(Path(target_dir))@@ -577,12 +581,10 @@ def main() -> None:print("[INFO] No images requiring automatic fix found")except Exception as e:print(f"[ERROR] Automatic fix failed: {e}")- sys.exit(1)+ return 1+ return 0- else:- print(f"[ERROR] Error: unknown command '{command}'")- print(__doc__)- sys.exit(1)+ parser.error(f"Unknown command: {args.command}")if __name__ == '__main__':- main()+ raise SystemExit(main())diff --git a/skills/ppt-master/scripts/svg_finalize/align_embed_images.py b/skills/ppt-master/scripts/svg_finalize/align_embed_images.pyindex be007abc..d946efbf 100644--- a/skills/ppt-master/scripts/svg_finalize/align_embed_images.py+++ b/skills/ppt-master/scripts/svg_finalize/align_embed_images.py@@ -54,6 +54,14 @@ from typing import TYPE_CHECKINGfrom urllib.parse import unquotefrom xml.etree import ElementTree as ET+if __package__ in {None, ''}:+ import types++ package = types.ModuleType('svg_finalize')+ package.__path__ = [str(Path(__file__).resolve().parent)] # type: ignore[attr-defined]+ sys.modules.setdefault('svg_finalize', package)+ __package__ = 'svg_finalize'+# Reuse helpers from the previous standalone modules.from .crop_images import crop_image_to_size, get_crop_anchor, parse_preserve_aspect_ratiofrom .embed_images import _optimize_image_bytes, get_mime_type@@ -415,7 +423,8 @@ def align_and_embed_images_in_svg(# Standalone CLI (rare; the main entry point is finalize_svg.py)# ----------------------------------------------------------------------------def _cli() -> None:+def build_parser() -> argparse.ArgumentParser:+ """Build the standalone diagnostic parser."""import argparseparser = argparse.ArgumentParser(description='Align (slice/meet) and Base64-embed all <image> refs in an SVG.',@@ -427,11 +436,17 @@ def _cli() -> None:help='Compress images before embedding')parser.add_argument('--max-dimension', type=int, default=None,help='Downscale images larger than this on either axis')- args = parser.parse_args()+ return parser+++def main(argv: list[str] | None = None) -> int:+ """Run the standalone diagnostic CLI."""+ parser = build_parser()+ args = parser.parse_args(argv)if not args.svg.exists():print(f'Error: file not found: {args.svg}', file=sys.stderr)- sys.exit(1)+ return 1proc, err = align_and_embed_images_in_svg(args.svg,@@ -441,7 +456,8 @@ def _cli() -> None:max_dimension=args.max_dimension,)print(f'Processed {proc} image(s), {err} error(s)')+ return 1 if err else 0if __name__ == '__main__':- _cli()+ raise SystemExit(main())diff --git a/skills/ppt-master/scripts/svg_position_calculator.py b/skills/ppt-master/scripts/svg_position_calculator.pyindex 4903fe26..391ca51b 100644--- a/skills/ppt-master/scripts/svg_position_calculator.py+++ b/skills/ppt-master/scripts/svg_position_calculator.py@@ -1300,7 +1300,7 @@ def from_json_config(config_file: str) -> None:print(" ".join(points_list))-def main() -> None:+def main(argv: list[str] | None = None) -> int:"""Run the CLI entry point."""parser = argparse.ArgumentParser(description='SVG Position Calculation and Validation Tool',@@ -1323,11 +1323,11 @@ Common commands:""")- subparsers = parser.add_subparsers(dest='command', help='Command')+ subparsers = parser.add_subparsers(dest='command', help='Command', required=True)# calc subcommandcalc_parser = subparsers.add_parser('calc', help='Calculate coordinates')- calc_subparsers = calc_parser.add_subparsers(dest='chart_type', help='Chart type')+ calc_subparsers = calc_parser.add_subparsers(dest='chart_type', help='Chart type', required=True)# Bar chartbar_parser = calc_subparsers.add_parser('bar', help='Bar chart')@@ -1388,7 +1388,7 @@ Common commands:json_parser = subparsers.add_parser('from-json', help='Calculate from JSON config file')json_parser.add_argument('config_file', help='JSON config file path')- args = parser.parse_args()+ args = parser.parse_args(argv)if args.command == 'calc':# Parse chart area@@ -1475,6 +1475,7 @@ Common commands:else:parser.print_help()+ return 1elif args.command == 'validate':validator = SVGPositionValidator(tolerance=args.tolerance)@@ -1499,13 +1500,14 @@ Common commands:expected_path = Path(args.expected)if not expected_path.exists():print(f"[Error] Expected coordinates file does not exist: {args.expected}")- return+ return 1with open(expected_path, 'r', encoding='utf-8') as f:expected_coords = json.load(f)results = validator.validate_from_file(args.svg_file, expected_coords)print(validator.format_results(results))else:print("Validation mode requires --expected <json_file>; use --extract to extract coordinates first")+ return 1elif args.command == 'analyze':analyze_svg_file(args.svg_file)@@ -1518,7 +1520,10 @@ Common commands:else:parser.print_help()+ return 1++ return 0if __name__ == '__main__':- main()+ raise SystemExit(main())diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.pyindex cb6497a9..c08a7768 100644--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py@@ -9,6 +9,14 @@ import argparsefrom datetime import datetimefrom pathlib import Path+if __package__ in {None, ''}:+ import types++ package = types.ModuleType('svg_to_pptx')+ package.__path__ = [str(Path(__file__).resolve().parent)] # type: ignore[attr-defined]+ sys.modules.setdefault('svg_to_pptx', package)+ __package__ = 'svg_to_pptx'+from .pptx_dimensions import CANVAS_FORMATS, get_project_infofrom .pptx_discovery import find_svg_files, find_notes_filesfrom .pptx_builder import create_pptx_with_native_svg@@ -55,7 +63,7 @@ def _recorded_narration_on_click_slides(return blocked-def main() -> None:+def main(argv: list[str] | None = None) -> int:"""CLI entry point for the SVG to PPTX conversion tool."""transition_choices = (['none'] + (list(TRANSITIONS.keys()) if TRANSITIONS@@ -239,12 +247,12 @@ Recorded narration:help='Parallel workers for SVG→PNG pre-rendering. ''Default: min(cpu, pages, 8). Set 1 for sequential.')- args = parser.parse_args()+ args = parser.parse_args(argv)project_path = Path(args.project_path)if not project_path.exists():print(f"Error: Path does not exist: {project_path}")- sys.exit(1)+ return 1try:project_info = get_project_info(str(project_path))@@ -296,7 +304,7 @@ Recorded narration:ref_files = native_files or legacy_filesif not ref_files:print("Error: No SVG files found")- sys.exit(1)+ return 1timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")@@ -343,7 +351,7 @@ Recorded narration:f"Error: Recorded narration directory does not exist: {narration_audio_dir}",file=sys.stderr,)- sys.exit(1)+ return 1narration_audio = find_narration_files(narration_audio_dir, ref_files)if verbose:print(f" Narration audio directory: {narration_audio_dir}")@@ -361,7 +369,7 @@ Recorded narration:print(f" Missing audio for: {stem}", file=sys.stderr)if len(missing) > 20:print(f" ... and {len(missing) - 20} more", file=sys.stderr)- sys.exit(1)+ return 1unreadable = [f"{stem}: {audio_path}"for stem, audio_path in sorted(narration_audio.items())@@ -377,7 +385,7 @@ Recorded narration:print(f" {item}", file=sys.stderr)if len(unreadable) > 20:print(f" ... and {len(unreadable) - 20} more", file=sys.stderr)- sys.exit(1)+ return 1elif narration_audio_dir_arg and verbose:missing = [path.stem for path in ref_files if path.stem not in narration_audio]if missing:@@ -392,13 +400,13 @@ Recorded narration:config_path = project_path / config_pathif not config_path.exists():print(f"Error: Animation config does not exist: {config_path}")- sys.exit(1)+ return 1try:animation_config = load_animation_config(project_path, args.animation_config)except Exception as exc:print(f"Error: Failed to load animation config: {exc}")- sys.exit(1)+ return 1if animation_config and verbose:config_label = args.animation_config or str(project_path / 'animations.json')print(f" Animation config: {config_label}")@@ -473,7 +481,7 @@ Recorded narration:print(f" on-click trigger: {slide}", file=sys.stderr)if len(on_click_slides) > 20:print(f" ... and {len(on_click_slides) - 20} more", file=sys.stderr)- sys.exit(1)+ return 1if args.no_cache:cache_dir: Path | None = None@@ -600,4 +608,8 @@ Recorded narration:if verbose:print(f" [warn] cache cleanup skipped: {exc}")- sys.exit(0 if success else 1)+ return 0 if success else 1+++if __name__ == '__main__':+ raise SystemExit(main())diff --git a/skills/ppt-master/scripts/template_fill_pptx/cli.py b/skills/ppt-master/scripts/template_fill_pptx/cli.pyindex 7b143ccf..5bcbf161 100644--- a/skills/ppt-master/scripts/template_fill_pptx/cli.py+++ b/skills/ppt-master/scripts/template_fill_pptx/cli.py@@ -8,6 +8,20 @@ import sysfrom datetime import datetimefrom pathlib import Path+if __package__ in {None, ''}:+ import types++ package_dir = Path(__file__).resolve().parent+ while str(package_dir) in sys.path:+ sys.path.remove(str(package_dir))+ scripts_dir = Path(__file__).resolve().parents[1]+ if str(scripts_dir) not in sys.path:+ sys.path.insert(0, str(scripts_dir))+ package = types.ModuleType("template_fill_pptx")+ package.__path__ = [str(package_dir)] # type: ignore[attr-defined]+ sys.modules.setdefault("template_fill_pptx", package)+ __package__ = "template_fill_pptx"+from .analyzer import analyze_pptxfrom .applier import apply_planfrom .checker import check_plan, print_check_report@@ -162,3 +176,7 @@ def main(argv: list[str] | None = None) -> int:parser.print_help()return 1+++if __name__ == "__main__":+ raise SystemExit(main())