@laitszkin/apollo-toolkit 2.14.23 → 3.0.0

package/openai-text-to-image-storyboard/tests/test_generate_storyboard_images.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import json
+import random
+import string
+import tempfile
+import types
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+PIL_AVAILABLE = importlib.util.find_spec("PIL") is not None
+
+if PIL_AVAILABLE:
+    from PIL import Image
+    SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "generate_storyboard_images.py"
+    SPEC = importlib.util.spec_from_file_location("generate_storyboard_images", SCRIPT_PATH)
+    MODULE = importlib.util.module_from_spec(SPEC)
+    SPEC.loader.exec_module(MODULE)
+else:
+    Image = None
+    MODULE = None
+
+
+def png_bytes(width: int, height: int, color: tuple[int, int, int] = (64, 128, 255)) -> bytes:
+    buffer = io.BytesIO()
+    Image.new("RGB", (width, height), color).save(buffer, format="PNG")
+    return buffer.getvalue()
+
+
+@unittest.skipUnless(PIL_AVAILABLE, "Pillow is required for storyboard image tests")
+class GenerateStoryboardImagesTests(unittest.TestCase):
+    def test_sanitize_component_property_removes_invalid_path_characters(self) -> None:
+        generator = random.Random(20260418)
+        alphabet = string.ascii_letters + string.digits + string.punctuation + " \t中文"
+
+        for _ in range(200):
+            raw = "".join(generator.choice(alphabet) for _ in range(generator.randint(0, 30)))
+            sanitized = MODULE.sanitize_component(raw, "fallback")
+            with self.subTest(raw=raw, sanitized=sanitized):
+                self.assertTrue(sanitized)
+                self.assertNotRegex(sanitized, MODULE.INVALID_PATH_CHARS)
+                self.assertNotIn(" ", sanitized)
+
+    def test_parse_image_dimensions_supports_png_and_jpeg(self) -> None:
+        png = png_bytes(320, 180)
+        self.assertEqual(MODULE.parse_image_dimensions(png), (320, 180))
+
+        buffer = io.BytesIO()
+        Image.new("RGB", (160, 90), (0, 0, 0)).save(buffer, format="JPEG")
+        self.assertEqual(MODULE.parse_image_dimensions(buffer.getvalue()), (160, 90))
+
+    def test_parse_prompts_file_supports_structured_scene_mode(self) -> None:
+        payload = {
+            "characters": [
+                {
+                    "id": "hero",
+                    "name": "Kai",
+                    "appearance": "short black hair",
+                    "outfit": "blue jacket",
+                    "description": "determined teenage inventor",
+                }
+            ],
+            "scenes": [
+                {
+                    "title": "Workshop",
+                    "description": "Kai repairs a flickering lantern inside a cramped workshop.",
+                    "character_ids": ["hero"],
+                    "character_descriptions": {"hero": "focused and covered with grease"},
+                    "camera": "medium shot",
+                }
+            ],
+        }
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            prompts_file = Path(temp_dir) / "prompts.json"
+            prompts_file.write_text(json.dumps(payload, ensure_ascii=False), encoding="utf-8")
+            items = MODULE.parse_prompts_file(prompts_file)
+
+        self.assertEqual(len(items), 1)
+        self.assertEqual(items[0]["title"], "Workshop")
+        prompt_payload = json.loads(items[0]["prompt"])
+        self.assertEqual(prompt_payload["characters"][0]["description"], "focused and covered with grease")
+        self.assertEqual(prompt_payload["camera"], "medium shot")
+
+    def test_build_scene_json_prompt_rejects_unknown_override_character(self) -> None:
+        scene = {
+            "title": "Workshop",
+            "description": "Lantern repair",
+            "character_ids": ["hero"],
+            "character_descriptions": {"ghost": "not listed"},
+        }
+
+        with self.assertRaises(SystemExit) as context:
+            MODULE.build_scene_json_prompt(
+                scene=scene,
+                scene_index=1,
+                prompts_file=Path("prompts.json"),
+                character_profiles={
+                    "hero": {
+                        "id": "hero",
+                        "name": "Kai",
+                        "appearance": "short black hair",
+                        "outfit": "blue jacket",
+                        "description": "determined teenage inventor",
+                    }
+                },
+            )
+
+        self.assertIn("ids not listed in character_ids", str(context.exception))
+
+    def test_generate_image_supports_b64_payload(self) -> None:
+        raw = png_bytes(100, 60)
+
+        with patch.object(
+            MODULE,
+            "post_json",
+            return_value={"data": [{"b64_json": MODULE.base64.b64encode(raw).decode("ascii"), "revised_prompt": "ok"}]},
+        ):
+            image_bytes, revised_prompt = MODULE.generate_image(
+                base_url="https://example.com",
+                api_key="token",
+                image_model="gpt-image-1",
+                prompt="scene",
+                aspect_ratio=None,
+                image_size=None,
+                quality=None,
+                style=None,
+            )
+
+        self.assertEqual(image_bytes, raw)
+        self.assertEqual(revised_prompt, "ok")
+
+    def test_main_generates_cropped_images_and_summary(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            project_dir = Path(temp_dir)
+            args = types.SimpleNamespace(
+                content_name="Lantern / Story",
+                project_dir=str(project_dir),
+                env_file=str(project_dir / ".env"),
+                api_url="https://example.com",
+                api_key="token",
+                prompts_file=None,
+                prompt=["Lantern workshop at dusk"],
+                image_model="gpt-image-1",
+                aspect_ratio="1:1",
+                image_size=None,
+                quality=None,
+                style=None,
+            )
+
+            with patch.object(MODULE, "parse_args", return_value=args), patch.object(
+                MODULE, "load_dotenv_file", return_value=False
+            ), patch.object(
+                MODULE,
+                "generate_image",
+                return_value=(png_bytes(200, 100), "Lantern workshop at dusk, improved"),
+            ):
+                exit_code = MODULE.main()
+
+            self.assertEqual(exit_code, 0)
+            output_dir = project_dir / "pictures" / "Lantern_Story"
+            summary = json.loads((output_dir / "storyboard.json").read_text(encoding="utf-8"))
+            self.assertEqual(summary["aspect_ratio"], "1:1")
+            self.assertEqual(summary["images"][0]["width"], 100)
+            self.assertEqual(summary["images"][0]["height"], 100)
+            self.assertEqual(summary["images"][0]["source_width"], 200)
+            self.assertEqual(summary["images"][0]["source_height"], 100)
+            self.assertEqual(summary["images"][0]["revised_prompt"], "Lantern workshop at dusk, improved")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "2.14.23",
+  "version": "3.0.0",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",

package/read-github-issue/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: read-github-issue
-description: Read and search remote GitHub issues via GitHub CLI (`gh`). Use when users ask to list issues, filter issue candidates, inspect a specific issue with comments, or gather issue context before planning follow-up work. Prefer the bundled scripts when they are present and working, but fall back to direct `gh issue list` / `gh issue view` commands when the scripts are missing or fail for repository-specific reasons.
+description: Read and search remote GitHub issues via GitHub CLI (`gh`). Use when users ask to list issues, filter issue candidates, inspect a specific issue with comments, or gather issue context before planning follow-up work. Prefer the bundled CLI tools when they are present and working, but fall back to direct `gh issue list` / `gh issue view` commands when the tools are missing or fail for repository-specific reasons.
 ---
 
 # Read GitHub Issue
@@ -10,12 +10,12 @@ description: Read and search remote GitHub issues via GitHub CLI (`gh`). Use whe
 - Required: none.
 - Conditional: none.
 - Optional: none.
-- Fallback: If the bundled scripts are missing or fail but `gh` is available, continue with raw `gh issue list` / `gh issue view`; only stop when `gh` itself is unavailable or unauthenticated.
+- Fallback: If the bundled CLI tools are missing or fail but `gh` is available, continue with raw `gh issue list` / `gh issue view`; only stop when `gh` itself is unavailable or unauthenticated.
 
 ## Standards
 
 - Evidence: Verify repository context first, then read remote issue data directly from `gh issue list` / `gh issue view` instead of paraphrasing from memory.
-- Execution: Confirm the target repo, prefer the bundled scripts for deterministic output, then fall back to raw `gh` commands whenever the scripts are unavailable or broken in the target repository.
+- Execution: Confirm the target repo, prefer the bundled CLI tools for deterministic output, then fall back to raw `gh` commands whenever the tools are unavailable or broken in the target repository.
 - Quality: Keep the skill focused on issue discovery and retrieval only; do not embed any hardcoded fixing, branching, PR, or push workflow.
 - Output: Return candidate issues, selected issue details, comments summary, and any missing information needed before follow-up work.
 
@@ -35,12 +35,12 @@ Use this skill to gather trustworthy GitHub issue context with `gh`: discover op
 - Run `gh repo view --json nameWithOwner,isPrivate,defaultBranchRef` to confirm target repo.
 - If the user specifies another repository, always use `--repo <owner>/<repo>` in issue commands.
 
-### 2) Find candidate issues with the bundled script
+### 2) Find candidate issues with the bundled CLI
 
 - Preferred command:
 
 ```bash
-python3 scripts/find_issues.py --limit 50 --state open
+apltk find-github-issues --limit 50 --state open
 ```
 
 - Optional filters:
@@ -61,7 +61,7 @@ gh issue list --limit 50 --state open
 - Preferred command:
 
 ```bash
-python3 scripts/read_issue.py 123 --comments
+apltk read-github-issue 123 --comments
 ```
 
 - Optional flags:
@@ -82,16 +82,16 @@ gh issue view 123 --comments
 - Identify missing acceptance criteria, repro details, affected components, or environment context.
 - If issue text and comments are insufficient, state exactly what is missing instead of inventing a fix plan.
 
-## Included Script
+## Included CLI
 
-### `scripts/find_issues.py`
+### `apltk find-github-issues`
 
 - Purpose: consistent remote issue listing via `gh issue list`.
 - Outputs a readable table by default, or JSON with `--output json`.
 - Uses only GitHub CLI so it reflects remote GitHub state.
 - Treat it as a convenience wrapper, not a hard dependency.
 
-### `scripts/read_issue.py`
+### `apltk read-github-issue`
 
 - Purpose: deterministic issue detail retrieval via `gh issue view`.
 - Outputs either a human-readable summary or full JSON for downstream automation.

package/resolve-review-comments/SKILL.md

@@ -46,8 +46,8 @@ Use this skill to run an end-to-end GitHub PR review loop: collect review thread
 - If user does not provide PR number, infer from current branch context.
 
 ```bash
-python3 scripts/review_threads.py list --repo <owner>/<repo> --pr <number>
-python3 scripts/review_threads.py list
+apltk review-threads list --repo <owner>/<repo> --pr <number>
+apltk review-threads list
 ```
 
 ## 2) Read unresolved review threads
@@ -55,8 +55,8 @@ python3 scripts/review_threads.py list
 Use table view for quick scan, then JSON when you need full details.
 
 ```bash
-python3 scripts/review_threads.py list --pr <number> --state unresolved --output table
-python3 scripts/review_threads.py list --pr <number> --state unresolved --output json > /tmp/pr_threads.json
+apltk review-threads list --pr <number> --state unresolved --output table
+apltk review-threads list --pr <number> --state unresolved --output json > /tmp/pr_threads.json
 ```
 
 The JSON output contains `thread_id`, `path`, `line`, and comment bodies for decision and resolution.
@@ -98,13 +98,13 @@ Track adopted thread IDs in a JSON file:
 Resolve only threads you actually addressed in code.
 
 ```bash
-python3 scripts/review_threads.py resolve --pr <number> --thread-id-file adopted_threads.json
+apltk review-threads resolve --pr <number> --thread-id-file adopted_threads.json
 ```
 
 Optional preview without mutating GitHub state:
 
 ```bash
-python3 scripts/review_threads.py resolve --pr <number> --thread-id-file adopted_threads.json --dry-run
+apltk review-threads resolve --pr <number> --thread-id-file adopted_threads.json --dry-run
 ```
 
 ## 8) Handle non-adopted comments
@@ -113,9 +113,9 @@ python3 scripts/review_threads.py resolve --pr <number> --thread-id-file adopted
 - Reply with a concise technical reason and, if needed, a proposed follow-up.
 - Never resolve rejected or unhandled feedback threads.
 
-## Scripts
+## CLI
 
-### `scripts/review_threads.py`
+### `apltk review-threads`
 
 - `list`: fetch PR review threads via GitHub GraphQL (`gh api graphql`), supports repo/PR inference.
 - `resolve`: resolve selected review threads by thread IDs.

package/review-codebases/README.md

@@ -50,6 +50,8 @@ For each confirmed finding, delegate publication to `$open-github-issue` with:
 - file references and causal reasoning in `suspected-cause`
 - reproduction conditions when known
 
+When invoking the publisher CLI directly, use `apltk open-github-issue --payload-file <json>` or `@file` inputs for Markdown-rich fields so shell parsing cannot consume backticks or code snippets.
+
 If issue publication is unavailable, return draft issue content instead of switching to an ad-hoc publishing path.
 
 ## Output expectations

package/review-codebases/SKILL.md

@@ -74,6 +74,7 @@ Only continue to the next level when the current level has no confirmed findings
      - `suspected-cause`: file references, causal chain, and confidence
      - `reproduction`: concrete trigger or conditions when known; otherwise leave empty
      - `repo`: target repository in `owner/repo` format when known
+   - If invoking the publisher CLI directly, pass finding details through `apltk open-github-issue --payload-file <json>` or `@file` inputs rather than inline shell arguments so code snippets and backticks survive unchanged.
 
 ## Evidence standard
 

package/text-to-short-video/README.md

@@ -56,7 +56,7 @@ cp ~/.codex/skills/text-to-short-video/.env.example \
 If API-generated video ratio/size does not match the target, run:
 
 ```bash
-python ~/.codex/skills/text-to-short-video/scripts/enforce_video_aspect_ratio.py \
+apltk enforce-video-aspect-ratio \
   --input-video "<downloaded_video_path>" \
   --output-video "<final_output_video_path>" \
   --env-file ~/.codex/skills/text-to-short-video/.env \

package/text-to-short-video/SKILL.md

@@ -173,7 +173,7 @@ If provider returns multiple outputs, keep the best one that matches requested s
 When output ratio or resolution differs from target, run:
 
 ```bash
-python ~/.codex/skills/text-to-short-video/scripts/enforce_video_aspect_ratio.py \
+apltk enforce-video-aspect-ratio \
   --input-video "<downloaded_video_path>" \
   --output-video "<final_output_video_path>" \
   --env-file ~/.codex/skills/text-to-short-video/.env \

package/text-to-short-video/tests/test_enforce_video_aspect_ratio.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import json
+import os
+import random
+import re
+import tempfile
+import types
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+
+SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "enforce_video_aspect_ratio.py"
+SPEC = importlib.util.spec_from_file_location("enforce_video_aspect_ratio", SCRIPT_PATH)
+MODULE = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(MODULE)
+
+
+def parse_crop(expression: str) -> tuple[int, int, int, int] | None:
+    match = re.search(r"crop=(\d+):(\d+):(\d+):(\d+)", expression)
+    if not match:
+        return None
+    return tuple(int(value) for value in match.groups())
+
+
+class EnforceVideoAspectRatioTests(unittest.TestCase):
+    def test_parse_size_property_round_trips_positive_dimensions(self) -> None:
+        generator = random.Random(20260418)
+        for _ in range(150):
+            width = generator.randint(1, 9999)
+            height = generator.randint(1, 9999)
+            raw = f"{width}x{height}"
+            with self.subTest(raw=raw):
+                self.assertEqual(MODULE.parse_size(raw), (width, height))
+
+    def test_load_dotenv_file_parses_quotes_and_respects_override(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            env_file = Path(temp_dir) / ".env"
+            env_file.write_text(
+                'TEXT_TO_SHORT_VIDEO_WIDTH="720"\n'
+                "TEXT_TO_SHORT_VIDEO_HEIGHT=1280 # comment\n",
+                encoding="utf-8",
+            )
+            original = os.environ.get("TEXT_TO_SHORT_VIDEO_WIDTH")
+            os.environ["TEXT_TO_SHORT_VIDEO_WIDTH"] = "999"
+            try:
+                loaded = MODULE.load_dotenv_file(env_file, override=False)
+                self.assertTrue(loaded)
+                self.assertEqual(os.environ["TEXT_TO_SHORT_VIDEO_WIDTH"], "999")
+                self.assertEqual(os.environ["TEXT_TO_SHORT_VIDEO_HEIGHT"], "1280")
+                MODULE.load_dotenv_file(env_file, override=True)
+                self.assertEqual(os.environ["TEXT_TO_SHORT_VIDEO_WIDTH"], "720")
+            finally:
+                if original is None:
+                    os.environ.pop("TEXT_TO_SHORT_VIDEO_WIDTH", None)
+                else:
+                    os.environ["TEXT_TO_SHORT_VIDEO_WIDTH"] = original
+                os.environ.pop("TEXT_TO_SHORT_VIDEO_HEIGHT", None)
+
+    def test_build_video_filter_property_keeps_crop_within_bounds(self) -> None:
+        generator = random.Random(20260418)
+        for _ in range(200):
+            input_width = generator.randint(32, 4096)
+            input_height = generator.randint(32, 4096)
+            target_width = generator.randint(32, 2160)
+            target_height = generator.randint(32, 3840)
+
+            expression, crop_applied = MODULE.build_video_filter(
+                input_width=input_width,
+                input_height=input_height,
+                target_width=target_width,
+                target_height=target_height,
+            )
+
+            with self.subTest(
+                input_width=input_width,
+                input_height=input_height,
+                target_width=target_width,
+                target_height=target_height,
+                expression=expression,
+            ):
+                if expression is None:
+                    self.assertFalse(crop_applied)
+                    self.assertEqual((input_width, input_height), (target_width, target_height))
+                    continue
+
+                self.assertIn(f"scale={target_width}:{target_height}", expression)
+                crop = parse_crop(expression)
+                if crop is None:
+                    self.assertFalse(crop_applied)
+                    self.assertEqual(input_width * target_height, input_height * target_width)
+                    continue
+
+                crop_width, crop_height, offset_x, offset_y = crop
+                self.assertTrue(crop_applied)
+                self.assertEqual(crop_width % 2, 0)
+                self.assertEqual(crop_height % 2, 0)
+                self.assertGreaterEqual(crop_width, 2)
+                self.assertGreaterEqual(crop_height, 2)
+                self.assertLessEqual(crop_width, input_width)
+                self.assertLessEqual(crop_height, input_height)
+                self.assertGreaterEqual(offset_x, 0)
+                self.assertGreaterEqual(offset_y, 0)
+                self.assertLessEqual(offset_x + crop_width, input_width)
+                self.assertLessEqual(offset_y + crop_height, input_height)
+
+    def test_resolve_output_path_enforces_in_place_rules(self) -> None:
+        input_video = Path("/tmp/input.mp4")
+        args = types.SimpleNamespace(in_place=False, output_video=None)
+        self.assertEqual(MODULE.resolve_output_path(args, input_video), Path("/tmp/input_aspect_fixed.mp4"))
+
+        args = types.SimpleNamespace(in_place=True, output_video=None)
+        self.assertEqual(MODULE.resolve_output_path(args, input_video), input_video)
+
+        args = types.SimpleNamespace(in_place=True, output_video="/tmp/out.mp4")
+        with self.assertRaises(SystemExit):
+            MODULE.resolve_output_path(args, input_video)
+
+    def test_main_copies_file_when_video_already_matches_target(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            input_video = Path(temp_dir) / "input.mp4"
+            input_video.write_bytes(b"video")
+            output_video = Path(temp_dir) / "copy.mp4"
+            args = types.SimpleNamespace(
+                input_video=str(input_video),
+                output_video=str(output_video),
+                in_place=False,
+                target_size="640x360",
+                target_width=None,
+                target_height=None,
+                env_file=str(Path(temp_dir) / ".env"),
+                force=False,
+                ffmpeg_bin="ffmpeg",
+                ffprobe_bin="ffprobe",
+            )
+
+            with patch.object(MODULE, "parse_args", return_value=args), patch.object(
+                MODULE, "load_dotenv_file", return_value=False
+            ), patch.object(MODULE, "required_command"), patch.object(
+                MODULE, "probe_video_size", return_value=(640, 360)
+            ), patch("sys.stdout", new_callable=io.StringIO) as stdout:
+                exit_code = MODULE.main()
+
+            self.assertEqual(exit_code, 0)
+            self.assertEqual(output_video.read_bytes(), b"video")
+            self.assertIn("already matches target size", stdout.getvalue())
+
+    def test_main_runs_ffmpeg_and_reports_output_dimensions(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            input_video = Path(temp_dir) / "input.mp4"
+            output_video = Path(temp_dir) / "output.mp4"
+            input_video.write_bytes(b"video")
+            args = types.SimpleNamespace(
+                input_video=str(input_video),
+                output_video=str(output_video),
+                in_place=False,
+                target_size="1080x1920",
+                target_width=None,
+                target_height=None,
+                env_file=str(Path(temp_dir) / ".env"),
+                force=True,
+                ffmpeg_bin="ffmpeg",
+                ffprobe_bin="ffprobe",
+            )
+
+            def fake_run(command, check):
+                self.assertIn("-vf", command)
+                Path(command[-1]).write_bytes(b"processed")
+                return types.SimpleNamespace(returncode=0)
+
+            with patch.object(MODULE, "parse_args", return_value=args), patch.object(
+                MODULE, "load_dotenv_file", return_value=False
+            ), patch.object(MODULE, "required_command"), patch.object(
+                MODULE,
+                "probe_video_size",
+                side_effect=[(1920, 1080), (1080, 1920)],
+            ), patch.object(MODULE.subprocess, "run", side_effect=fake_run), patch(
+                "sys.stdout", new_callable=io.StringIO
+            ) as stdout:
+                exit_code = MODULE.main()
+
+            self.assertEqual(exit_code, 0)
+            self.assertTrue(output_video.is_file())
+            self.assertIn("Center crop applied: yes", stdout.getvalue())
+            self.assertIn("Output size: 1080x1920", stdout.getvalue())
+
+
+if __name__ == "__main__":
+    unittest.main()

package/weekly-financial-event-report/SKILL.md

@@ -10,7 +10,7 @@ description: Read a user-specified PDF that marks the week's key financial event
 - Required: `pdf` to render the final report.
 - Conditional: `document-vision-reader` when the source PDF's highlighted markers are visible in layout but not recoverable from machine-readable text alone.
 - Optional: none.
-- Fallback: If source-PDF extraction through `pdf` is unavailable or fails on macOS, use the bundled `scripts/extract_pdf_text_pdfkit.swift` helper before giving up; only stop when neither `pdf` nor the local PDFKit fallback can recover the marked events, or when final PDF rendering itself cannot be completed.
+- Fallback: If source-PDF extraction through `pdf` is unavailable or fails on macOS, use the bundled `apltk extract-pdf-text-pdfkit` helper before giving up; only stop when neither `pdf` nor the local PDFKit fallback can recover the marked events, or when final PDF rendering itself cannot be completed.
 
 ## Standards
 
@@ -72,7 +72,7 @@ Do not guess any input that materially changes the research window or report sco
 - If `pdf` extraction is unavailable or fails because the current machine lacks local PDF tooling, and the host is macOS, run:
 
 ```bash
-swift scripts/extract_pdf_text_pdfkit.swift /absolute/path/to/source.pdf
+apltk extract-pdf-text-pdfkit /absolute/path/to/source.pdf
 ```
 
 - The bundled extractor prints page-delimited text directly from PDFKit so the agent can still build the source-event table without adding Python PDF packages ad hoc.

package/weekly-financial-event-report/tests/test_extract_pdf_text_pdfkit.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import importlib.util
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+REPORTLAB_AVAILABLE = importlib.util.find_spec("reportlab") is not None
+
+if REPORTLAB_AVAILABLE:
+    from reportlab.pdfgen import canvas
+
+
+SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "extract_pdf_text_pdfkit.swift"
+
+
+@unittest.skipUnless(shutil.which("swift"), "swift is required for PDFKit script tests")
+@unittest.skipUnless(sys.platform == "darwin", "PDFKit script tests only work on macOS")
+class ExtractPdfTextPdfkitTests(unittest.TestCase):
+    def run_script(self, *args: str) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            ["swift", str(SCRIPT_PATH), *args],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+
+    def test_missing_path_prints_usage(self) -> None:
+        result = self.run_script()
+        self.assertEqual(result.returncode, 1)
+        self.assertIn("Usage: swift scripts/extract_pdf_text_pdfkit.swift", result.stderr)
+
+    def test_unreadable_pdf_reports_missing_file(self) -> None:
+        result = self.run_script("/tmp/does-not-exist.pdf")
+        self.assertEqual(result.returncode, 1)
+        self.assertIn("Unable to open PDF", result.stderr)
+
+    @unittest.skipUnless(REPORTLAB_AVAILABLE, "reportlab is required to generate fixture PDFs")
+    def test_extracts_text_from_generated_pdf(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            pdf_path = Path(temp_dir) / "sample.pdf"
+            pdf = canvas.Canvas(str(pdf_path))
+            pdf.drawString(72, 720, "Weekly event headline")
+            pdf.showPage()
+            pdf.drawString(72, 720, "Second page details")
+            pdf.save()
+
+            result = self.run_script(str(pdf_path))
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertIn(f"PDF_PATH={pdf_path}", result.stdout)
+        self.assertIn("PAGE_COUNT=2", result.stdout)
+        self.assertIn("=== PAGE 1 ===", result.stdout)
+        self.assertIn("Weekly event headline", result.stdout)
+        self.assertIn("Second page details", result.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main()