@laitszkin/apollo-toolkit 2.14.23 → 3.0.1

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.1",
   "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/scheduled-runtime-health-check/SKILL.md

@@ -52,6 +52,7 @@ This skill is an orchestration layer. It owns the background terminal session, o
 - Do not call a module healthy unless there is at least one positive signal for it.
 - Separate scheduler failures, boot failures, runtime failures, and shutdown failures.
 - For complex pipelines, identify the last successful stage before attributing the failure to application logic.
+- When the user asks to compare a bounded run with a previous run, compare only runs with the same command or preset, duration, runtime mode, and complete structured artifacts. If the previous run lacks canonical reports, databases, or startup artifacts, mark the runs incomparable and explain the artifact completeness gap instead of inventing performance deltas.
 - If logs cannot support a health judgment, mark the module as `unknown` instead of guessing.
 
 ## Required workflow
@@ -93,6 +94,8 @@ This skill is an orchestration layer. It owns the background terminal session, o
    - Invoke `analyse-app-logs` on only the captured runtime window.
    - Pass the service or module names, environment, timezone, canonical run folder, relevant log files, and the exact start/end boundaries.
    - When the command produced reports, databases, or other structured artifacts, compare them against the same run's logs before making a health judgment.
+   - For follow-up questions about why most business events did not happen, build a stage-by-stage funnel from the canonical artifacts before reading isolated logs: candidate counts, admission/precheck decisions, queue or governor outcomes, skipped/blocked reasons, executed counts, retry/remediation outcomes, and persistence records.
+   - For follow-up questions about runtime speed, report latency from structured timestamps when available, separating startup/readiness, queue wait, precheck/final-prepare, submission, confirmation, and end-to-end timings rather than collapsing them into one vague duration.
    - Reuse its confirmed issues, hypotheses, and monitoring improvements instead of rewriting a separate incident workflow.
 8. Produce the final report
    - Always summarize the actual command executed, actual start/end timestamps, execution status, and log locations.

package/systematic-debug/SKILL.md

@@ -25,6 +25,7 @@ description: "Systematic debugging workflow for program issues: understand obser
 - Cover all plausible causes with reproducible tests instead of guessing a single cause.
 - Keep fixes minimal, focused, and validated by passing tests.
 - When logs or runtime artifacts exist, treat one run as canonical and compare every conclusion against that same run's generated artifacts, not against ad hoc console recollection.
+- When comparing runtime runs, first verify the baseline run is complete enough for the requested comparison: same command or scenario, same runtime mode, same bounded duration, and matching structured artifacts. If the baseline is incomplete, report that the only proven change is artifact/run completeness and avoid drawing strategy or performance conclusions from missing data.
 - When a repository has both scenario or harness runs and a production-like runtime, do not treat the lower-fidelity mode as proof about the higher-fidelity mode unless you explicitly state that limitation and the user agrees.
 - When the failing flow crosses multiple layers, identify the last confirmed successful stage before assigning blame.
 - When tests fail, separate stale assertions and fixture drift from real implementation regressions before changing product code.
@@ -58,6 +59,8 @@ Also auto-invoke this skill when mismatch evidence appears during normal executi
 - If a hypothesized cause cannot be reproduced, document why and deprioritize it explicitly.
 - For long-running or generated-artifact workflows, record the exact command, timestamps, and artifact paths before inspecting outputs so later comparisons stay on the same evidence set.
 - Do not mix baseline data and rerun data casually; compare the same scenario or command across runs and call out when a conclusion comes from a rerun rather than the original failure.
+- For post-run "why did most events not happen" questions, derive the answer from a funnel over structured artifacts first, then corroborate with logs: discovered or eligible candidates, admission blocks, stale or skipped decisions, queue/governor outcomes, execution attempts, confirmations, retries, and persisted event rows.
+- For speed questions, compute per-stage timings from available event timestamps and state which stages are measured versus unavailable; avoid treating wall-clock bounded duration as pipeline latency.
 - When test fixtures or assertions no longer match the implemented contract, update the tests instead of weakening the product behavior to satisfy stale expectations.
 - When tests shell out to shared local infrastructure, add deterministic isolation such as mutexes, unique temp roots, or serialized sections before accepting flakes as inevitable.
 

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.