@laitszkin/apollo-toolkit 2.14.23 → 3.0.1

package/katex/SKILL.md

@@ -15,7 +15,7 @@ description: Render and embed math formulas with KaTeX using official documentat
 ## Standards
 
 - Evidence: Follow the official KaTeX docs in `references/official-docs.md` before choosing render mode, options, or insertion strategy.
-- Execution: Decide between pre-rendering and client-side auto-render first, then use `scripts/render_katex.py` for deterministic output whenever a static rendered snippet is enough.
+- Execution: Decide between pre-rendering and client-side auto-render first, then use `apltk render-katex` for deterministic output whenever a static rendered snippet is enough.
 - Quality: Default to `htmlAndMathml`, keep `trust` disabled unless the content source is explicitly trusted, and include the KaTeX stylesheet whenever the output will be displayed in HTML.
 - Output: Return insertion-ready content plus the exact CSS or runtime requirements still needed by the target file.
 
@@ -41,7 +41,7 @@ Use KaTeX safely and consistently so mathematical formulas can be inserted into
 Run the bundled renderer for pre-rendered output:
 
 ```bash
-python3 katex/scripts/render_katex.py \
+apltk render-katex \
   --tex '\int_0^1 x^2 \\, dx = \\frac{1}{3}' \
   --display-mode \
   --output-format html-fragment
@@ -88,5 +88,5 @@ See `references/insertion-patterns.md` for concrete insertion guidance.
 
 - `references/official-docs.md`: condensed notes from the official KaTeX docs and direct source links.
 - `references/insertion-patterns.md`: insertion patterns for HTML, Markdown/MDX, and auto-rendered pages.
-- `scripts/render_katex.py`: deterministic wrapper around the official KaTeX CLI for insertion-ready output.
+- `scripts/render_katex.py`: deterministic wrapper around the official KaTeX CLI for insertion-ready output, exposed as `apltk render-katex`.
 - `scripts/render_katex.sh`: shell wrapper for environments that prefer an executable script entrypoint.

package/katex/tests/test_render_katex.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import json
+import os
+import random
+import string
+import subprocess
+import sys
+import tempfile
+import types
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+
+SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "render_katex.py"
+SHELL_SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "render_katex.sh"
+SPEC = importlib.util.spec_from_file_location("render_katex", SCRIPT_PATH)
+MODULE = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(MODULE)
+
+
+class RenderKatexTests(unittest.TestCase):
+    def test_load_macro_pairs_rejects_invalid_values(self) -> None:
+        with self.assertRaises(MODULE.KatexRenderError):
+            MODULE.load_macro_pairs(["\\RR"])
+
+        with self.assertRaises(MODULE.KatexRenderError):
+            MODULE.load_macro_pairs(["\\RR:"])
+
+    def test_normalize_path_property_returns_absolute_resolved_path(self) -> None:
+        generator = random.Random(20260418)
+        alphabet = string.ascii_letters + string.digits
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            with patch("pathlib.Path.cwd", return_value=Path(temp_dir)):
+                for _ in range(120):
+                    depth = generator.randint(1, 4)
+                    pieces = [
+                        "".join(generator.choice(alphabet) for _ in range(generator.randint(1, 8)))
+                        for _ in range(depth)
+                    ]
+                    raw_path = "/".join(pieces)
+                    normalized = MODULE.normalize_path(raw_path)
+                    with self.subTest(raw_path=raw_path):
+                        self.assertTrue(normalized.is_absolute())
+                        self.assertEqual(normalized, (Path(temp_dir) / raw_path).resolve())
+
+    def test_wrap_output_json_includes_metadata(self) -> None:
+        args = types.SimpleNamespace(
+            output_format="json",
+            display_mode=True,
+            katex_format="htmlAndMathml",
+            css_href="https://cdn.example.com/katex.css",
+        )
+
+        payload = json.loads(MODULE.wrap_output("<span>ok</span>", r"x^2", args))
+        self.assertEqual(payload["tex"], r"x^2")
+        self.assertEqual(payload["displayMode"], True)
+        self.assertEqual(payload["content"], "<span>ok</span>")
+
+    def test_run_katex_cli_builds_expected_command(self) -> None:
+        captured = {}
+        with tempfile.TemporaryDirectory() as temp_dir:
+            macro_file = Path(temp_dir) / "macros.json"
+            macro_file.write_text('{"\\\\RR":"\\\\mathbb{R}"}\n', encoding="utf-8")
+            args = types.SimpleNamespace(
+                katex_format="html",
+                display_mode=True,
+                leqno=True,
+                fleqn=False,
+                color_is_text_color=True,
+                no_throw_on_error=True,
+                error_color="#cc0000",
+                strict="warn",
+                trust="true",
+                max_size=12.5,
+                max_expand=500,
+                min_rule_thickness=0.08,
+                macro=[r"\RR:\mathbb{R}"],
+                macro_file=str(macro_file),
+            )
+
+            def fake_run(command, **kwargs):
+                captured["command"] = command
+                captured["kwargs"] = kwargs
+                return types.SimpleNamespace(returncode=0, stdout="<span>rendered</span>", stderr="")
+
+            with patch.object(MODULE.subprocess, "run", side_effect=fake_run):
+                output = MODULE.run_katex_cli(r"\RR + x", args)
+
+        self.assertEqual(output, "<span>rendered</span>")
+        command = captured["command"]
+        self.assertIn("--display-mode", command)
+        self.assertIn("--leqno", command)
+        self.assertIn("--color-is-text-color", command)
+        self.assertIn("--no-throw-on-error", command)
+        self.assertIn("--macro", command)
+        self.assertIn(r"\RR:\mathbb{R}", command)
+        self.assertIn("--macro-file", command)
+        self.assertIn("--input", command)
+
+    def test_main_writes_output_file_when_renderer_succeeds(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            output_path = Path(temp_dir) / "out" / "katex.html"
+            argv = [
+                "--tex",
+                r"\int_0^1 x^2 dx",
+                "--output-format",
+                "html-page",
+                "--output-file",
+                str(output_path),
+                "--title",
+                "Sample Render",
+            ]
+
+            with patch.object(MODULE, "run_katex_cli", return_value="<span>ok</span>"), patch(
+                "sys.stdout", new_callable=io.StringIO
+            ) as stdout:
+                exit_code = MODULE.main(argv)
+
+            self.assertEqual(exit_code, 0)
+            self.assertIn(str(output_path.resolve()), stdout.getvalue())
+            self.assertIn("<span>ok</span>", output_path.read_text(encoding="utf-8"))
+            self.assertIn("Sample Render", output_path.read_text(encoding="utf-8"))
+
+    def test_main_reports_missing_node_tooling(self) -> None:
+        error = FileNotFoundError(2, "No such file or directory", "npx")
+
+        with patch.object(MODULE, "run_katex_cli", side_effect=error), patch(
+            "sys.stderr", new_callable=io.StringIO
+        ) as stderr:
+            exit_code = MODULE.main(["--tex", r"x+1"])
+
+        self.assertEqual(exit_code, 1)
+        self.assertIn("node and npx are required", stderr.getvalue())
+
+    def test_shell_wrapper_invokes_python_script_with_same_arguments(self) -> None:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            capture_path = Path(temp_dir) / "argv.json"
+            fake_python = Path(temp_dir) / "python3"
+            fake_python.write_text(
+                f"#!{sys.executable}\n"
+                "import json, os, sys\n"
+                "with open(os.environ['CAPTURE_PATH'], 'w', encoding='utf-8') as handle:\n"
+                "    json.dump(sys.argv[1:], handle)\n",
+                encoding="utf-8",
+            )
+            fake_python.chmod(0o755)
+
+            env = dict(os.environ)
+            env["PATH"] = f"{temp_dir}:{env['PATH']}"
+            env["CAPTURE_PATH"] = str(capture_path)
+
+            result = subprocess.run(
+                ["bash", str(SHELL_SCRIPT_PATH), "--tex", r"x^2", "--output-format", "json"],
+                capture_output=True,
+                text=True,
+                env=env,
+                check=False,
+            )
+
+            self.assertEqual(result.returncode, 0, result.stderr)
+            argv = json.loads(capture_path.read_text(encoding="utf-8"))
+            self.assertEqual(argv[0], str(SCRIPT_PATH))
+            self.assertEqual(argv[1:], ["--tex", r"x^2", "--output-format", "json"])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/learning-error-book/SKILL.md

@@ -111,8 +111,8 @@ error_book/
 
 5) Render structured data -> PDF (CJK font support)
    - Run:
-     - `python3 learning-error-book/scripts/render_error_book_json_to_pdf.py error_book/references/mc-question-reference.json error_book/mc-question-error-book.pdf`
-     - `python3 learning-error-book/scripts/render_error_book_json_to_pdf.py error_book/references/long-question-reference.json error_book/long-question-error-book.pdf`
+     - `apltk render-error-book error_book/references/mc-question-reference.json error_book/mc-question-error-book.pdf`
+     - `apltk render-error-book error_book/references/long-question-reference.json error_book/long-question-error-book.pdf`
    - If paper size/font needs change: adjust script flags (`--help`)
 
 ## Built-in Template

package/learning-error-book/tests/test_render_error_book_json_to_pdf.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+REPORTLAB_AVAILABLE = importlib.util.find_spec("reportlab") is not None
+
+if REPORTLAB_AVAILABLE:
+    from reportlab.platypus import Paragraph
+    SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "render_error_book_json_to_pdf.py"
+    SPEC = importlib.util.spec_from_file_location("render_error_book_json_to_pdf", SCRIPT_PATH)
+    MODULE = importlib.util.module_from_spec(SPEC)
+    SPEC.loader.exec_module(MODULE)
+else:
+    Paragraph = object
+    MODULE = None
+
+
+def minimal_payload() -> dict:
+    return {
+        "title": "Physics Error Book",
+        "book_type": "mc-question",
+        "last_updated": "2026-04-18",
+        "coverage_scope": [
+            {
+                "source_path": "notes/ch1.pdf",
+                "included_questions": ["Q1", "Q2"],
+                "notes": "Kinematics review",
+            }
+        ],
+        "mistake_overview": [
+            {
+                "type": "Concept mix-up",
+                "summary": "Mixed up displacement and distance.",
+                "representative_questions": ["Q1"],
+            }
+        ],
+        "concept_highlights": [
+            {
+                "name": "Velocity",
+                "definition": "Rate of change of displacement.",
+                "common_misjudgment": "Treating it as always positive speed.",
+                "checklist": ["Track sign", "Check reference direction"],
+            }
+        ],
+        "questions": [
+            {
+                "question_id": "Q1",
+                "source_path": "notes/ch1.pdf",
+                "page_or_locator": "p.3",
+                "user_answer": "B",
+                "correct_answer": "C",
+                "mistake_type": "Concept mix-up",
+                "concepts": ["Velocity", "Displacement"],
+                "stem": "A car turns around after 10 seconds.",
+                "why_wrong": "The answer used total distance instead of signed displacement.",
+                "correct_solution_steps": ["Identify direction", "Compute signed displacement"],
+                "options": [
+                    {"label": "A", "text": "0", "verdict": "wrong", "reason": "Ignores movement"},
+                    {"label": "C", "text": "-2", "verdict": "correct", "reason": "Signed displacement"},
+                ],
+            }
+        ],
+    }
+
+
+@unittest.skipUnless(REPORTLAB_AVAILABLE, "reportlab is required for PDF rendering tests")
+class RenderErrorBookTests(unittest.TestCase):
+    def test_safe_text_handles_lists_numbers_and_defaults(self) -> None:
+        self.assertEqual(MODULE._safe_text([" A ", 2, ""], default="-"), "A, 2")
+        self.assertEqual(MODULE._safe_text(None, default="(none)"), "(none)")
+        self.assertEqual(MODULE._safe_text("   ", default="fallback"), "fallback")
+
+    def test_markup_escapes_html_and_preserves_line_breaks(self) -> None:
+        rendered = MODULE._markup("A < B\nline 2")
+        self.assertIn("A &lt; B", rendered)
+        self.assertIn("<br/>", rendered)
+
+    def test_bullet_lines_returns_default_paragraph_when_empty(self) -> None:
+        styles = MODULE._build_styles("Helvetica", 11)
+        bullets = MODULE._bullet_lines([], styles, empty_text="No data")
+        self.assertEqual(len(bullets), 1)
+        self.assertIsInstance(bullets[0], Paragraph)
+
+    def test_build_story_contains_multiple_sections(self) -> None:
+        font_path, subfont_index = MODULE._detect_cjk_font_path(None)
+        font_name = MODULE._register_font(font_path, subfont_index)
+        styles = MODULE._build_styles(font_name, 11)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            output_pdf = Path(temp_dir) / "preview.pdf"
+            doc = MODULE.SimpleDocTemplate(
+                str(output_pdf),
+                title="Physics Error Book",
+            )
+            story = MODULE._build_story(minimal_payload(), styles, doc)
+
+        self.assertGreater(len(story), 10)
+        self.assertEqual(story[1].text, "Physics Error Book")
+
+    def test_main_renders_pdf_from_minimal_payload(self) -> None:
+        font_path, _ = MODULE._detect_cjk_font_path(None)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            temp_root = Path(temp_dir)
+            input_json = temp_root / "error-book.json"
+            output_pdf = temp_root / "out" / "error-book.pdf"
+            input_json.write_text(json.dumps(minimal_payload(), ensure_ascii=False), encoding="utf-8")
+
+            argv = [
+                str(input_json),
+                str(output_pdf),
+                "--font-path",
+                font_path,
+                "--font-size",
+                "10",
+            ]
+
+            with patch("sys.argv", ["render_error_book_json_to_pdf.py", *argv]):
+                exit_code = MODULE.main()
+
+            self.assertEqual(exit_code, 0)
+            self.assertTrue(output_pdf.is_file())
+            self.assertTrue(output_pdf.read_bytes().startswith(b"%PDF"))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/lib/cli.js

@@ -10,6 +10,7 @@ const {
   syncToolkitHome,
   getTargetRoots,
 } = require('./installer');
+const { formatToolList, getToolCommand, runTool } = require('./tool-runner');
 const { checkForPackageUpdate } = require('./updater');
 
 const TARGET_OPTIONS = [
@@ -124,6 +125,9 @@ function buildHelpText({ version, colorEnabled }) {
     'Usage:',
     '  apltk [install] [codex|openclaw|trae|agents|claude-code|all]...',
     '  apollo-toolkit [install] [codex|openclaw|trae|agents|claude-code|all]...',
+    '  apltk tools',
+    '  apltk <tool> [...args]',
+    '  apltk tools <tool> [...args]',
     '  apltk --help',
     '  apollo-toolkit --help',
     '',
@@ -136,14 +140,37 @@ function buildHelpText({ version, colorEnabled }) {
     '  apltk agents',
     '  apltk claude-code',
     '  apltk all',
+    '  apltk filter-logs app.log --start 2026-03-24T10:00:00Z',
+    '  apltk create-specs "Membership upgrade flow" --change-name membership-upgrade-flow',
+    '  apltk tools',
     '  apollo-toolkit all',
     '',
+    'Bundled tools:',
+    formatToolList(),
+    '',
     'Options:',
     '  --home <path>  Override Apollo Toolkit home directory',
     '  --help         Show this help text',
   ].join('\n');
 }
 
+function buildToolsHelp({ version, colorEnabled }) {
+  return [
+    buildBanner({ version, colorEnabled }),
+    '',
+    'Usage:',
+    '  apltk tools',
+    '  apltk <tool> [...args]',
+    '  apltk tools <tool> [...args]',
+    '',
+    'Bundled tools:',
+    formatToolList(),
+    '',
+    'Tip:',
+    '  Pass `--help` after a tool name to view the original script flags.',
+  ].join('\n');
+}
+
 function readPackageJson(sourceRoot) {
   return JSON.parse(fs.readFileSync(path.join(sourceRoot, 'package.json'), 'utf8'));
 }
@@ -151,11 +178,36 @@ function readPackageJson(sourceRoot) {
 function parseArguments(argv) {
   const args = [...argv];
   const result = {
+    command: 'install',
     modes: [],
     showHelp: false,
+    showToolsHelp: false,
     toolkitHome: null,
+    toolName: null,
+    toolArgs: [],
   };
 
+  if (args[0] === 'tools' || args[0] === 'tool') {
+    args.shift();
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+      result.command = 'tools-help';
+      result.showToolsHelp = true;
+      return result;
+    }
+
+    result.command = 'tool';
+    result.toolName = args.shift();
+    result.toolArgs = args;
+    return result;
+  }
+
+  if (args[0] && getToolCommand(args[0])) {
+    result.command = 'tool';
+    result.toolName = args.shift();
+    result.toolArgs = args;
+    return result;
+  }
+
   while (args.length > 0) {
     const arg = args.shift();
 
@@ -368,6 +420,19 @@ async function run(argv, context = {}) {
       stdout.write(`${buildHelpText({ version: packageJson.version, colorEnabled: supportsColor(stdout, env) })}\n`);
       return 0;
     }
+    if (parsed.showToolsHelp) {
+      stdout.write(`${buildToolsHelp({ version: packageJson.version, colorEnabled: supportsColor(stdout, env) })}\n`);
+      return 0;
+    }
+    if (parsed.command === 'tool') {
+      return (context.runTool || runTool)(parsed.toolName, parsed.toolArgs, {
+        sourceRoot,
+        stdout,
+        stderr,
+        env,
+        spawnCommand: context.spawnCommand,
+      });
+    }
 
     const updateResult = await checkForPackageUpdate({
       packageName: packageJson.name,
@@ -432,6 +497,7 @@ module.exports = {
   buildBanner,
   buildWelcomeScreen,
   buildHelpText,
+  buildToolsHelp,
   parseArguments,
   promptForModes,
   readPackageJson,

package/lib/tool-runner.js

@@ -0,0 +1,214 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const TOOL_COMMANDS = [
+  {
+    name: 'filter-logs',
+    skill: 'analyse-app-logs',
+    script: 'analyse-app-logs/scripts/filter_logs_by_time.py',
+    runner: 'python3',
+    description: 'Filter log lines by timestamp window.',
+    aliases: ['filter-logs-by-time'],
+  },
+  {
+    name: 'search-logs',
+    skill: 'analyse-app-logs',
+    script: 'analyse-app-logs/scripts/search_logs.py',
+    runner: 'python3',
+    description: 'Search logs by keyword or regex.',
+  },
+  {
+    name: 'docs-to-voice',
+    skill: 'docs-to-voice',
+    script: 'docs-to-voice/scripts/docs_to_voice.py',
+    runner: 'python3',
+    description: 'Convert text into audio, timeline JSON, and SRT.',
+  },
+  {
+    name: 'create-specs',
+    skill: 'generate-spec',
+    script: 'generate-spec/scripts/create-specs',
+    runner: 'python3',
+    description: 'Create spec planning documents from templates.',
+  },
+  {
+    name: 'render-katex',
+    skill: 'katex',
+    script: 'katex/scripts/render_katex.py',
+    runner: 'python3',
+    description: 'Render TeX with KaTeX into reusable output.',
+  },
+  {
+    name: 'render-error-book',
+    skill: 'learning-error-book',
+    script: 'learning-error-book/scripts/render_error_book_json_to_pdf.py',
+    runner: 'python3',
+    description: 'Render structured error-book JSON into PDF.',
+  },
+  {
+    name: 'open-github-issue',
+    skill: 'open-github-issue',
+    script: 'open-github-issue/scripts/open_github_issue.py',
+    runner: 'python3',
+    description: 'Publish or draft a structured GitHub issue.',
+  },
+  {
+    name: 'generate-storyboard-images',
+    skill: 'openai-text-to-image-storyboard',
+    script: 'openai-text-to-image-storyboard/scripts/generate_storyboard_images.py',
+    runner: 'python3',
+    description: 'Generate storyboard image sets from text.',
+  },
+  {
+    name: 'find-github-issues',
+    skill: 'read-github-issue',
+    script: 'read-github-issue/scripts/find_issues.py',
+    runner: 'python3',
+    description: 'List GitHub issues through gh.',
+  },
+  {
+    name: 'read-github-issue',
+    skill: 'read-github-issue',
+    script: 'read-github-issue/scripts/read_issue.py',
+    runner: 'python3',
+    description: 'Read GitHub issue details through gh.',
+  },
+  {
+    name: 'review-threads',
+    skill: 'resolve-review-comments',
+    script: 'resolve-review-comments/scripts/review_threads.py',
+    runner: 'python3',
+    description: 'List or resolve GitHub PR review threads.',
+  },
+  {
+    name: 'enforce-video-aspect-ratio',
+    skill: 'text-to-short-video',
+    script: 'text-to-short-video/scripts/enforce_video_aspect_ratio.py',
+    runner: 'python3',
+    description: 'Resize video output to a target aspect ratio.',
+  },
+  {
+    name: 'extract-pdf-text-pdfkit',
+    skill: 'weekly-financial-event-report',
+    script: 'weekly-financial-event-report/scripts/extract_pdf_text_pdfkit.swift',
+    runner: 'swift',
+    description: 'Extract PDF text with macOS PDFKit fallback.',
+  },
+  {
+    name: 'extract-codex-conversations',
+    skill: 'codex-memory-manager',
+    script: 'codex/codex-memory-manager/scripts/extract_recent_conversations.py',
+    runner: 'python3',
+    description: 'Extract recent Codex sessions for memory updates.',
+  },
+  {
+    name: 'sync-codex-memory-index',
+    skill: 'codex-memory-manager',
+    script: 'codex/codex-memory-manager/scripts/sync_memory_index.py',
+    runner: 'python3',
+    description: 'Sync the Codex memory index in AGENTS.md.',
+  },
+  {
+    name: 'extract-skill-conversations',
+    skill: 'learn-skill-from-conversations',
+    script: 'codex/learn-skill-from-conversations/scripts/extract_recent_conversations.py',
+    runner: 'python3',
+    description: 'Extract recent Codex sessions for skill learning.',
+  },
+  {
+    name: 'validate-skill-frontmatter',
+    skill: 'maintain-skill-catalog',
+    script: 'scripts/validate_skill_frontmatter.py',
+    runner: 'python3',
+    description: 'Validate SKILL.md frontmatter across the catalog.',
+  },
+  {
+    name: 'validate-openai-agent-config',
+    skill: 'maintain-skill-catalog',
+    script: 'scripts/validate_openai_agent_config.py',
+    runner: 'python3',
+    description: 'Validate every skill agents/openai.yaml config.',
+  },
+];
+
+const TOOL_BY_NAME = new Map();
+
+for (const tool of TOOL_COMMANDS) {
+  TOOL_BY_NAME.set(tool.name, tool);
+  for (const alias of tool.aliases || []) {
+    TOOL_BY_NAME.set(alias, { ...tool, name: alias, canonicalName: tool.name });
+  }
+}
+
+function getToolCommand(name) {
+  return TOOL_BY_NAME.get(name) || null;
+}
+
+function listToolCommands() {
+  return [...TOOL_COMMANDS].sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function resolveToolCommand(name, sourceRoot) {
+  const tool = getToolCommand(name);
+  if (!tool) {
+    return null;
+  }
+
+  return {
+    ...tool,
+    scriptPath: path.join(sourceRoot, tool.script),
+  };
+}
+
+function formatToolList() {
+  const tools = listToolCommands();
+  const width = tools.reduce((max, tool) => Math.max(max, tool.name.length), 0);
+  return tools.map((tool) => {
+    const name = tool.name.padEnd(width, ' ');
+    return `  ${name}  ${tool.description}`;
+  }).join('\n');
+}
+
+function runTool(toolName, toolArgs, context = {}) {
+  const sourceRoot = context.sourceRoot || path.resolve(__dirname, '..');
+  const stderr = context.stderr || process.stderr;
+  const env = context.env || process.env;
+  const spawnCommand = context.spawnCommand || spawn;
+  const tool = resolveToolCommand(toolName, sourceRoot);
+
+  if (!tool) {
+    stderr.write(`Unknown tool: ${toolName}\n\nAvailable tools:\n${formatToolList()}\n`);
+    return Promise.resolve(1);
+  }
+
+  if (!fs.existsSync(tool.scriptPath)) {
+    stderr.write(`Tool script not found: ${tool.scriptPath}\n`);
+    return Promise.resolve(1);
+  }
+
+  return new Promise((resolve) => {
+    const child = spawnCommand(tool.runner, [tool.scriptPath, ...toolArgs], {
+      cwd: context.cwd || process.cwd(),
+      env,
+      stdio: context.stdio || 'inherit',
+    });
+
+    child.on('error', (error) => {
+      stderr.write(`Failed to start ${tool.runner}: ${error.message}\n`);
+      resolve(1);
+    });
+
+    child.on('close', (code) => {
+      resolve(typeof code === 'number' ? code : 1);
+    });
+  });
+}
+
+module.exports = {
+  formatToolList,
+  getToolCommand,
+  listToolCommands,
+  resolveToolCommand,
+  runTool,
+};