@laitszkin/apollo-toolkit 3.13.2 → 3.14.0

package/resources/project-architecture/assets/viewer.client.js

@@ -0,0 +1,144 @@
+/* viewer.client.js — pan/zoom for every atlas SVG on the page.
+ *
+ * Each `[data-pan-zoom-viewport]` element gets its own state and
+ * handlers, so a single page can host the macro atlas SVG AND
+ * sub-module-internal dataflow SVGs simultaneously. Toolbar buttons
+ * (`[data-pan-zoom="zoom-in|zoom-out|fit"]`) are scoped to the
+ * containing `[data-pan-zoom-container]` (falls back to the viewport's
+ * direct parent), so multiple toolbars on one page do not collide.
+ * Keyboard shortcuts (`←` / `→` / `↑` / `↓` / `+` / `−` / `0`) drive
+ * the page's first viewport — the "primary" diagram of that page
+ * (macro SVG on `index.html`; sub-dataflow SVG on a sub-module page).
+ */
+
+(function () {
+  'use strict';
+
+  const viewports = Array.from(document.querySelectorAll('[data-pan-zoom-viewport]'));
+  const controllers = viewports.map(setupViewport).filter(Boolean);
+  if (controllers.length === 0) return;
+
+  const primary = controllers[0];
+  document.addEventListener('keydown', function (evt) {
+    if (evt.target && (evt.target.tagName === 'INPUT' || evt.target.tagName === 'TEXTAREA')) return;
+    if (evt.key === 'ArrowLeft') { primary.pan(-1, 0); }
+    else if (evt.key === 'ArrowRight') { primary.pan(1, 0); }
+    else if (evt.key === 'ArrowUp') { primary.pan(0, -1); }
+    else if (evt.key === 'ArrowDown') { primary.pan(0, 1); }
+    else if (evt.key === '+' || evt.key === '=') { primary.zoom(1 / 1.2); }
+    else if (evt.key === '-' || evt.key === '_') { primary.zoom(1.2); }
+    else if (evt.key === '0') { primary.fit(); }
+  });
+
+  function setupViewport(viewport) {
+    const svg = viewport.querySelector('[data-atlas-svg]');
+    if (!svg) return null;
+    const initial = svg.getAttribute('viewBox');
+    if (!initial) return null;
+    const [ix, iy, iw, ih] = initial.split(/\s+/).map(Number);
+    const state = { x: ix, y: iy, w: iw, h: ih };
+
+    function apply() {
+      svg.setAttribute('viewBox', `${state.x} ${state.y} ${state.w} ${state.h}`);
+    }
+    function fit() {
+      state.x = ix; state.y = iy; state.w = iw; state.h = ih;
+      apply();
+    }
+    function zoom(factor, cx, cy) {
+      const newW = Math.max(40, Math.min(state.w * factor, iw * 8));
+      const newH = newW * (state.h / state.w);
+      if (cx == null) { cx = state.x + state.w / 2; cy = state.y + state.h / 2; }
+      state.x = cx - (cx - state.x) * (newW / state.w);
+      state.y = cy - (cy - state.y) * (newH / state.h);
+      state.w = newW;
+      state.h = newH;
+      apply();
+    }
+    function pan(dirX, dirY) {
+      const stepX = state.w * 0.08;
+      const stepY = state.h * 0.08;
+      state.x += dirX * stepX;
+      state.y += dirY * stepY;
+      apply();
+    }
+    function clientToSvg(evt) {
+      const rect = svg.getBoundingClientRect();
+      const xRatio = (evt.clientX - rect.left) / rect.width;
+      const yRatio = (evt.clientY - rect.top) / rect.height;
+      return { x: state.x + xRatio * state.w, y: state.y + yRatio * state.h };
+    }
+
+    // The diagram viewport owns the wheel gesture entirely: ANY wheel
+    // event that lands inside the viewport is consumed so the host page
+    // never scrolls underneath the user. The wheel zooms the SVG around
+    // the cursor; trackpad pinch-zoom (which arrives as ctrlKey wheel
+    // on macOS) is treated the same way for a single predictable model.
+    viewport.addEventListener('wheel', function (evt) {
+      evt.preventDefault();
+      evt.stopPropagation();
+      const absX = Math.abs(evt.deltaX);
+      const absY = Math.abs(evt.deltaY);
+      if (absX < 0.5 && absY < 0.5) return;
+      const factor = evt.deltaY > 0 ? 1.08 : 1 / 1.08;
+      const pt = clientToSvg(evt);
+      zoom(factor, pt.x, pt.y);
+    }, { passive: false });
+
+    // Drag-pan: defer the pointer capture (and the "is-grabbing" class)
+    // until the pointer actually moves past a small threshold. Without
+    // this, a single click on an SVG <a> (sub-module link) would be
+    // captured by the viewport and never reach the link.
+    const DRAG_THRESHOLD_PX = 4;
+    let pending = null;
+    let dragging = null;
+    viewport.addEventListener('pointerdown', function (evt) {
+      if (evt.button !== 0) return;
+      pending = { x: evt.clientX, y: evt.clientY, pointerId: evt.pointerId };
+    });
+    viewport.addEventListener('pointermove', function (evt) {
+      if (!dragging && pending && pending.pointerId === evt.pointerId) {
+        const dx = evt.clientX - pending.x;
+        const dy = evt.clientY - pending.y;
+        if (Math.hypot(dx, dy) < DRAG_THRESHOLD_PX) return;
+        dragging = { x: pending.x, y: pending.y, pointerId: pending.pointerId };
+        pending = null;
+        viewport.classList.add('is-grabbing');
+        try { viewport.setPointerCapture(dragging.pointerId); } catch (e) { /* ignore */ }
+      }
+      if (!dragging || dragging.pointerId !== evt.pointerId) return;
+      evt.preventDefault();
+      const rect = svg.getBoundingClientRect();
+      const dx = ((evt.clientX - dragging.x) / rect.width) * state.w;
+      const dy = ((evt.clientY - dragging.y) / rect.height) * state.h;
+      state.x -= dx;
+      state.y -= dy;
+      dragging.x = evt.clientX;
+      dragging.y = evt.clientY;
+      apply();
+    });
+    function endDrag(evt) {
+      pending = null;
+      if (!dragging) return;
+      const draggedId = dragging.pointerId;
+      dragging = null;
+      viewport.classList.remove('is-grabbing');
+      try { viewport.releasePointerCapture(draggedId); } catch (e) { /* ignore */ }
+      // Suppress the synthetic click that would follow a drag-release
+      // on top of a sub-module <a>; only the no-movement case should
+      // navigate.
+      const swallow = (e) => { e.preventDefault(); e.stopPropagation(); };
+      viewport.addEventListener('click', swallow, { capture: true, once: true });
+    }
+    viewport.addEventListener('pointerup', endDrag);
+    viewport.addEventListener('pointercancel', endDrag);
+    viewport.addEventListener('pointerleave', endDrag);
+
+    const container = viewport.closest('[data-pan-zoom-container]') || viewport.parentElement || document;
+    container.querySelectorAll('[data-pan-zoom="zoom-in"]').forEach((btn) => btn.addEventListener('click', () => zoom(1 / 1.2)));
+    container.querySelectorAll('[data-pan-zoom="zoom-out"]').forEach((btn) => btn.addEventListener('click', () => zoom(1.2)));
+    container.querySelectorAll('[data-pan-zoom="fit"]').forEach((btn) => btn.addEventListener('click', fit));
+
+    return { zoom, fit, pan };
+  }
+})();

package/resources/project-architecture/index.html

@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html lang="en" data-atlas-page="macro">
+<head>
+  <meta charset="utf-8">
+  <title>Project architecture</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="color-scheme" content="dark">
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,300..600;1,9..144,300..500&family=Geist:wght@300..700&family=JetBrains+Mono:wght@400..600&display=swap">
+  <link rel="stylesheet" href="assets/architecture.css">
+</head>
+<body>
+  <header class="atlas-header">
+    <h1>Project architecture</h1>
+    
+  </header>
+  <main class="atlas-main">
+    <section class="atlas-canvas" aria-label="Macro architecture diagram">
+      <div class="atlas-canvas__toolbar" role="toolbar" aria-label="Diagram controls">
+        <button type="button" data-pan-zoom="zoom-in" aria-label="Zoom in">+</button>
+        <button type="button" data-pan-zoom="zoom-out" aria-label="Zoom out">−</button>
+        <button type="button" data-pan-zoom="fit" aria-label="Reset view">Fit</button>
+      </div>
+      <div class="atlas-canvas__viewport" data-pan-zoom-viewport>
+<svg class="atlas-svg" viewBox="0 0 320 160" preserveAspectRatio="xMidYMid meet" role="img" aria-label="Atlas is empty"><text x="160" y="80" text-anchor="middle" fill="currentColor">Atlas has no features yet</text></svg>
+      </div>
+      <ol class="atlas-legend" aria-label="Edge legend">
+        <li><span class="legend-swatch legend-swatch--call"></span>call</li>
+        <li><span class="legend-swatch legend-swatch--return"></span>return</li>
+        <li><span class="legend-swatch legend-swatch--data-row"></span>data-row</li>
+        <li><span class="legend-swatch legend-swatch--failure"></span>failure</li>
+      </ol>
+    </section>
+    <section class="atlas-index" aria-label="Submodule index">
+      <h2>Submodule index</h2>
+
+    </section>
+  </main>
+  <script src="assets/viewer.client.js" defer></script>
+</body>
+</html>

package/review-spec-related-changes/SKILL.md

@@ -34,6 +34,6 @@ description: 當你需要審查規格文檔相關變更時，調用此技能
 ### 3. 生成 code review report
 
 將上一步發現的所有問題代碼總結，並按照問題嚴重程度排序，生成code review report。report需要包含以下元素：
-- 問題描述、嚴重度及影響
+- 問題描述、嚴重度（分為P0-P3）及影響
 - 涉及的代碼檔案、行數
 - 建議修正方案

package/solve-issues-found-during-review/SKILL.md

@@ -20,4 +20,5 @@ description: 當你需要修復 code review report 之中發現的問題時，
 
 ### 2. 修復發現的問題
 
-按照 code review report 之中的嚴重度排序，從最高嚴重度的問題開始建議方案修復。
+按照 code review report 之中的嚴重度排序，使用 `systematic-debug` 這個技能，從最高嚴重度的問題開始建議方案修復。
+如果外部環境允許使用 subagents，建議將修復任務拆分並分配給多個 subagents 並行完成。

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "outDir": "dist",
+    "rootDir": ".",
+    "declaration": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node",
+    "ignoreDeprecations": "6.0",
+    "types": ["node"]
+  },
+  "include": [
+    "bin/**/*.ts",
+    "lib/**/*.ts",
+    "test/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    ".claude",
+    "resources"
+  ]
+}

package/analyse-app-logs/scripts/filter_logs_by_time.py

@@ -1,64 +0,0 @@
-#!/usr/bin/env python3
-
-from __future__ import annotations
-
-import argparse
-import sys
-
-from log_cli_utils import ensure_timezone, extract_timestamp, in_window, iter_input_lines, parse_cli_timestamp
-
-
-def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(
-        description="Filter log lines by timestamp window from files or stdin."
-    )
-    parser.add_argument("paths", nargs="*", help="Log file paths. Reads stdin when omitted.")
-    parser.add_argument("--start", help="Inclusive start timestamp.")
-    parser.add_argument("--end", help="Inclusive end timestamp.")
-    parser.add_argument(
-        "--assume-timezone",
-        default="UTC",
-        help="Timezone for naive timestamps and --start/--end values. Default: UTC.",
-    )
-    parser.add_argument(
-        "--keep-undated",
-        action="store_true",
-        help="Keep lines without a parseable timestamp.",
-    )
-    parser.add_argument(
-        "--count-only",
-        action="store_true",
-        help="Print only the count of matching lines.",
-    )
-    return parser.parse_args()
-
-
-def main() -> int:
-    args = parse_args()
-    assume_timezone = ensure_timezone(args.assume_timezone)
-    start = parse_cli_timestamp(args.start, assume_timezone) if args.start else None
-    end = parse_cli_timestamp(args.end, assume_timezone) if args.end else None
-
-    if start and end and start > end:
-        print("Error: --start must be earlier than or equal to --end.", file=sys.stderr)
-        return 1
-
-    matches = 0
-    for line in iter_input_lines(args.paths):
-        timestamp = extract_timestamp(line, assume_timezone)
-        if timestamp is None and not args.keep_undated:
-            continue
-        if timestamp is not None and not in_window(timestamp, start, end):
-            continue
-
-        matches += 1
-        if not args.count_only:
-            print(line)
-
-    if args.count_only:
-        print(matches)
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/analyse-app-logs/scripts/log_cli_utils.py

@@ -1,112 +0,0 @@
-#!/usr/bin/env python3
-
-from __future__ import annotations
-
-import argparse
-import re
-from datetime import datetime, timedelta, timezone
-from pathlib import Path
-from typing import Iterator, Sequence
-
-
-TIMESTAMP_PATTERN = re.compile(
-    r"(?P<timestamp>"
-    r"\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:[.,]\d+)?(?:Z|[+-]\d{2}:\d{2})?"
-    r")"
-)
-
-TIMESTAMP_FORMATS = (
-    "%Y-%m-%dT%H:%M:%S.%f%z",
-    "%Y-%m-%dT%H:%M:%S%z",
-    "%Y-%m-%d %H:%M:%S.%f%z",
-    "%Y-%m-%d %H:%M:%S%z",
-    "%Y-%m-%dT%H:%M:%S.%f",
-    "%Y-%m-%dT%H:%M:%S",
-    "%Y-%m-%d %H:%M:%S.%f",
-    "%Y-%m-%d %H:%M:%S",
-)
-
-
-def normalize_timestamp(raw: str) -> str:
-    value = raw.strip().replace(",", ".")
-    if value.endswith("Z"):
-        return value[:-1] + "+00:00"
-    return value
-
-
-def parse_cli_timestamp(raw: str, assume_timezone: timezone) -> datetime:
-    normalized = normalize_timestamp(raw)
-    for fmt in TIMESTAMP_FORMATS:
-        try:
-            parsed = datetime.strptime(normalized, fmt)
-        except ValueError:
-            continue
-        if parsed.tzinfo is None:
-            return parsed.replace(tzinfo=assume_timezone)
-        return parsed
-    raise argparse.ArgumentTypeError(f"invalid timestamp: {raw}")
-
-
-def extract_timestamp(line: str, assume_timezone: timezone) -> datetime | None:
-    match = TIMESTAMP_PATTERN.search(line)
-    if not match:
-        return None
-    try:
-        return parse_cli_timestamp(match.group("timestamp"), assume_timezone)
-    except argparse.ArgumentTypeError:
-        return None
-
-
-def build_timezone(raw: str) -> timezone:
-    if raw.upper() == "UTC":
-        return timezone.utc
-
-    match = re.fullmatch(r"([+-])(\d{2}):(\d{2})", raw)
-    if not match:
-        raise argparse.ArgumentTypeError("timezone must be UTC or ±HH:MM")
-
-    sign, hours, minutes = match.groups()
-    total_minutes = int(hours) * 60 + int(minutes)
-    if sign == "-":
-        total_minutes *= -1
-    return timezone.utc if total_minutes == 0 else timezone(timedelta(minutes=total_minutes))
-
-
-def iter_input_lines(paths: Sequence[str]) -> Iterator[str]:
-    if not paths:
-        import sys
-
-        for line in sys.stdin:
-            yield line.rstrip("\n")
-        return
-
-    for raw_path in paths:
-        if raw_path == "-":
-            import sys
-
-            for line in sys.stdin:
-                yield line.rstrip("\n")
-            continue
-
-        path = Path(raw_path)
-        with path.open("r", encoding="utf-8") as handle:
-            for line in handle:
-                yield line.rstrip("\n")
-
-
-def in_window(
-    timestamp: datetime | None,
-    start: datetime | None,
-    end: datetime | None,
-) -> bool:
-    if timestamp is None:
-        return False
-    if start and timestamp < start:
-        return False
-    if end and timestamp > end:
-        return False
-    return True
-
-
-def ensure_timezone(value: str) -> timezone:
-    return build_timezone(value)

package/analyse-app-logs/scripts/search_logs.py

@@ -1,137 +0,0 @@
-#!/usr/bin/env python3
-
-from __future__ import annotations
-
-import argparse
-import re
-import sys
-from collections import deque
-from typing import Callable
-
-from log_cli_utils import ensure_timezone, extract_timestamp, in_window, iter_input_lines, parse_cli_timestamp
-
-
-def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(
-        description="Search log lines by keyword or regex, with optional time filtering."
-    )
-    parser.add_argument("paths", nargs="*", help="Log file paths. Reads stdin when omitted.")
-    parser.add_argument(
-        "--keyword",
-        action="append",
-        default=[],
-        help="Keyword to match. Repeat for multiple values.",
-    )
-    parser.add_argument(
-        "--regex",
-        action="append",
-        default=[],
-        help="Regular expression to match. Repeat for multiple values.",
-    )
-    parser.add_argument(
-        "--mode",
-        choices=["any", "all"],
-        default="any",
-        help="Require any or all patterns to match. Default: any.",
-    )
-    parser.add_argument(
-        "--ignore-case",
-        action="store_true",
-        help="Case-insensitive matching for keywords and regex.",
-    )
-    parser.add_argument("--start", help="Inclusive start timestamp.")
-    parser.add_argument("--end", help="Inclusive end timestamp.")
-    parser.add_argument(
-        "--assume-timezone",
-        default="UTC",
-        help="Timezone for naive timestamps and --start/--end values. Default: UTC.",
-    )
-    parser.add_argument(
-        "--before-context",
-        type=int,
-        default=0,
-        help="Print N lines of context before each match.",
-    )
-    parser.add_argument(
-        "--after-context",
-        type=int,
-        default=0,
-        help="Print N lines of context after each match.",
-    )
-    parser.add_argument(
-        "--count-only",
-        action="store_true",
-        help="Print only the number of matching lines.",
-    )
-    return parser.parse_args()
-
-
-def build_matchers(args: argparse.Namespace) -> list[Callable[[str], bool]]:
-    flags = re.IGNORECASE if args.ignore_case else 0
-    matchers: list[Callable[[str], bool]] = []
-
-    for keyword in args.keyword:
-        needle = keyword.lower() if args.ignore_case else keyword
-
-        def match_keyword(line: str, needle: str = needle) -> bool:
-            haystack = line.lower() if args.ignore_case else line
-            return needle in haystack
-
-        matchers.append(match_keyword)
-
-    for pattern in args.regex:
-        compiled = re.compile(pattern, flags)
-        matchers.append(lambda line, compiled=compiled: bool(compiled.search(line)))
-
-    return matchers
-
-
-def line_matches(line: str, matchers: list[Callable[[str], bool]], mode: str) -> bool:
-    if not matchers:
-        return True
-    results = [matcher(line) for matcher in matchers]
-    return any(results) if mode == "any" else all(results)
-
-
-def main() -> int:
-    args = parse_args()
-    assume_timezone = ensure_timezone(args.assume_timezone)
-    start = parse_cli_timestamp(args.start, assume_timezone) if args.start else None
-    end = parse_cli_timestamp(args.end, assume_timezone) if args.end else None
-    if start and end and start > end:
-        print("Error: --start must be earlier than or equal to --end.", file=sys.stderr)
-        return 1
-
-    matchers = build_matchers(args)
-    matches = 0
-    before_buffer: deque[str] = deque(maxlen=args.before_context)
-    after_remaining = 0
-
-    for line in iter_input_lines(args.paths):
-        timestamp = extract_timestamp(line, assume_timezone)
-        if (start or end) and not in_window(timestamp, start, end):
-            before_buffer.append(line)
-            continue
-
-        is_match = line_matches(line, matchers, args.mode)
-
-        if is_match:
-            matches += 1
-            if not args.count_only:
-                while before_buffer:
-                    print(before_buffer.popleft())
-                print(line)
-            after_remaining = args.after_context
-        elif after_remaining > 0 and not args.count_only:
-            print(line)
-            after_remaining -= 1
-
-        before_buffer.append(line)
-
-    if args.count_only:
-        print(matches)
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/analyse-app-logs/tests/test_filter_logs_by_time.py

@@ -1,95 +0,0 @@
-#!/usr/bin/env python3
-
-from __future__ import annotations
-
-import importlib.util
-import io
-import tempfile
-import unittest
-from argparse import Namespace
-from pathlib import Path
-from unittest.mock import patch
-
-
-SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "filter_logs_by_time.py"
-SCRIPT_DIR = SCRIPT_PATH.parent
-if str(SCRIPT_DIR) not in __import__("sys").path:
-    __import__("sys").path.insert(0, str(SCRIPT_DIR))
-SPEC = importlib.util.spec_from_file_location("filter_logs_by_time", SCRIPT_PATH)
-MODULE = importlib.util.module_from_spec(SPEC)
-SPEC.loader.exec_module(MODULE)
-
-
-class FilterLogsByTimeTests(unittest.TestCase):
-    def test_filters_lines_inside_window(self) -> None:
-        with tempfile.NamedTemporaryFile("w+", encoding="utf-8", delete=False) as handle:
-            handle.write(
-                "2026-03-24T10:00:00Z INFO boot\n"
-                "2026-03-24T10:05:00Z ERROR failed\n"
-                "2026-03-24T10:10:00Z INFO recovered\n"
-            )
-            path = handle.name
-
-        args = Namespace(
-            paths=[path],
-            start="2026-03-24T10:01:00Z",
-            end="2026-03-24T10:06:00Z",
-            assume_timezone="UTC",
-            keep_undated=False,
-            count_only=False,
-        )
-
-        with patch.object(MODULE, "parse_args", return_value=args), patch(
-            "sys.stdout", new_callable=io.StringIO
-        ) as stdout:
-            code = MODULE.main()
-
-        self.assertEqual(code, 0)
-        self.assertEqual(stdout.getvalue().strip(), "2026-03-24T10:05:00Z ERROR failed")
-
-    def test_keep_undated_lines_when_requested(self) -> None:
-        with tempfile.NamedTemporaryFile("w+", encoding="utf-8", delete=False) as handle:
-            handle.write(
-                "2026-03-24T10:00:00Z INFO boot\n"
-                "plain undated line\n"
-            )
-            path = handle.name
-
-        args = Namespace(
-            paths=[path],
-            start=None,
-            end=None,
-            assume_timezone="UTC",
-            keep_undated=True,
-            count_only=False,
-        )
-
-        with patch.object(MODULE, "parse_args", return_value=args), patch(
-            "sys.stdout", new_callable=io.StringIO
-        ) as stdout:
-            code = MODULE.main()
-
-        self.assertEqual(code, 0)
-        self.assertIn("plain undated line", stdout.getvalue())
-
-    def test_rejects_inverted_window(self) -> None:
-        args = Namespace(
-            paths=[],
-            start="2026-03-24T10:10:00Z",
-            end="2026-03-24T10:00:00Z",
-            assume_timezone="UTC",
-            keep_undated=False,
-            count_only=False,
-        )
-
-        with patch.object(MODULE, "parse_args", return_value=args), patch(
-            "sys.stderr", new_callable=io.StringIO
-        ) as stderr:
-            code = MODULE.main()
-
-        self.assertEqual(code, 1)
-        self.assertIn("--start", stderr.getvalue())
-
-
-if __name__ == "__main__":
-    unittest.main()