@laitszkin/apollo-toolkit 2.14.22 → 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.22",
+  "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/scheduled-runtime-health-check/SKILL.md

@@ -15,7 +15,7 @@ description: Use a background terminal to run a user-specified command immediate
 ## Standards
 
 - Evidence: Anchor every conclusion to the requested command, execution window, startup/shutdown timestamps, one canonical run folder or artifact root, captured logs, and concrete runtime signals.
-- Execution: Collect the run contract, verify the real stop mechanism before launch, use a background terminal, optionally update the code only when the user asks, execute the requested command immediately or in the requested window, record the canonical run folder once the process materializes it, capture logs, stop cleanly when bounded, then delegate log review to `analyse-app-logs` only when findings are requested or needed.
+- Execution: Collect the run contract, verify the real stop mechanism before launch, choose the highest-fidelity execution mode that matches the user's intent, use a background terminal, optionally update the code only when the user asks, execute the requested command immediately or in the requested window, record the canonical run folder once the process materializes it, capture logs, stop cleanly when bounded, then delegate log review to `analyse-app-logs` only when findings are requested or needed.
 - Quality: Keep scheduling, execution, and shutdown deterministic; separate confirmed findings from hypotheses; and mark each assessed module healthy/degraded/failed/unknown with reasons.
 - Output: Return the run configuration, execution status, log locations, optional code-update result, optional module health by area, confirmed issues, potential issues, observability gaps, and scheduler status when applicable.
 
@@ -46,6 +46,7 @@ This skill is an orchestration layer. It owns the background terminal session, o
 - Prefer one bounded observation window over open-ended monitoring.
 - Use one dedicated background terminal session per requested run so execution and logs stay correlated.
 - Record the canonical run directory, artifact root, or other generated output location as soon as it exists, and use that as the source of truth for later analysis.
+- When a repository exposes both synthetic harnesses and production-like runtime entrypoints, prefer the production-like path for claims about real runtime, market, or operator behavior; use the lower-fidelity harness only when the user explicitly asked for it or when it is the only safe reproduction surface.
 - Treat code update as optional and only perform it when the user explicitly requests it.
 - Treat startup, steady-state, and shutdown as part of the same investigation.
 - Do not call a module healthy unless there is at least one positive signal for it.
@@ -58,6 +59,7 @@ This skill is an orchestration layer. It owns the background terminal session, o
 1. Define the run contract
    - Confirm or derive the workspace, execution command, optional code-update step, optional schedule, optional duration, readiness signal, log locations, and whether post-run findings are required.
    - Derive commands from trustworthy sources first: `package.json`, `Makefile`, `docker-compose.yml`, `Procfile`, scripts, or project docs.
+   - If multiple commands exist for the same workflow, rank them by fidelity and state explicitly which mode you are choosing: production-like runtime, bounded integration harness, or synthetic scenario replay.
    - If no trustworthy execution command or stop method can be found, stop and ask only for the missing command rather than guessing.
 2. Prepare the background terminal run
    - Use a dedicated background terminal session for the whole workflow.
@@ -77,6 +79,7 @@ This skill is an orchestration layer. It owns the background terminal session, o
 5. Run and capture readiness
    - Execute the requested command in the same background terminal.
    - As soon as the command emits or creates its canonical run directory, artifact root, or equivalent output location, record that path and reuse it for every later check.
+   - Report the exact runtime mode used in the evidence record so later analysis does not accidentally treat synthetic-harness results as proof about production behavior.
    - Wait for a concrete readiness signal when the command is expected to stay up, such as a health endpoint, listening-port log, worker boot line, or queue-consumer ready message.
    - If readiness never arrives, stop the run, preserve logs, and treat it as a failed startup window.
 6. Observe and stop when bounded

package/systematic-debug/SKILL.md

@@ -15,7 +15,7 @@ description: "Systematic debugging workflow for program issues: understand obser
 ## Standards
 
 - Evidence: Gather expected versus observed behavior from code and runtime facts before deciding on a cause, and when the issue involves a runtime pipeline or bounded run, anchor the investigation to one canonical artifact root or run directory instead of mixed terminal snippets from multiple runs.
-- Execution: Inspect the relevant paths, reproduce every plausible cause with tests or bounded reruns, map each observed failure to a concrete pipeline stage, distinguish toolchain/platform faults from application-logic faults, classify failing tests as stale test contract vs test-harness interference vs real product bug, then apply the minimal fix at the true owner.
+- Execution: Inspect the relevant paths, reproduce every plausible cause with tests or bounded reruns, choose a reproduction mode whose fidelity matches the user's claim, map each observed failure to a concrete pipeline stage, distinguish toolchain/platform faults from application-logic faults, classify failing tests as stale test contract vs test-harness interference vs real product bug, then apply the minimal fix at the true owner.
 - Quality: Keep scope focused on the bug, prefer existing test patterns, explicitly rule out hypotheses that could not be reproduced, and when failures disappear in isolated reruns treat shared-state or parallel-test interference as a first-class hypothesis instead of silently dismissing the original failure.
 - Output: Deliver the plausible-cause list, the canonical evidence source, reproduction tests or reruns, the final failure classification for each investigated symptom, validated fix summary, and passing-test confirmation.
 
@@ -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 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.
 - If failures only appear under parallel execution or shared shell-out paths, investigate test isolation, shared locks, temp directories, run-name collisions, and environment leakage before blaming the product.
@@ -45,7 +46,7 @@ Also auto-invoke this skill when mismatch evidence appears during normal executi
 
 1. **Understand and inspect**: Parse expected vs observed behavior, explore relevant code paths, record the canonical failing run or artifact root when runtime output is involved, and build a list of plausible root causes.
 2. **Map the failure boundary**: Break the flow into concrete stages such as setup, startup, readiness, steady-state execution, persistence, and shutdown, then identify the last stage that is confirmed to have succeeded.
-3. **Reproduce with tests or bounded reruns**: Write or extend tests that reproduce every plausible cause, and when the bug depends on runtime orchestration rerun the same bounded command or scenario instead of switching contexts mid-investigation. When a failing test passes in isolation, rerun it under the original suite shape to determine whether the real cause is stale expectations, fixture drift, or shared-state interference.
+3. **Reproduce with tests or bounded reruns**: Write or extend tests that reproduce every plausible cause, and when the bug depends on runtime orchestration rerun the same bounded command or the same runtime mode instead of switching contexts mid-investigation. If the user is asking about real runtime or market behavior, prefer the production-like bounded run over a synthetic scenario replay unless safety or tooling constraints make that impossible. When a failing test passes in isolation, rerun it under the original suite shape to determine whether the real cause is stale expectations, fixture drift, or shared-state interference.
 4. **Diagnose and confirm**: Use reproduction evidence to confirm the true root cause, explicitly rule out non-causes, and classify whether each investigated failure belongs to the toolchain/platform layer, test contract drift, test-harness interference, orchestration, or application logic.
 5. **Fix and validate**: Implement focused fixes and iterate until all reproduction tests or bounded reruns pass.
 

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.