@laitszkin/apollo-toolkit 3.13.2 → 3.14.1

package/AGENTS.md

@@ -3,13 +3,13 @@
 ## Common Development Commands
 
 - `npm test` - 執行 Node 測試套件（`node --test`）。
-- `node bin/apollo-toolkit.js [mode...]` - 直接從倉庫啟動 CLI，將技能安裝至指定目標（codex/openclaw/trae/agents/claude-code/all）。
-- `node bin/apollo-toolkit.js uninstall [mode...]` - 從指定目標移除已安裝的 Apollo Toolkit 技能。
-- `node bin/apollo-toolkit.js tools` - 列出所有內建 CLI 工具及其分類。
-- `node bin/apollo-toolkit.js <tool> [args...]` - 執行內建工具（如 `filter-logs`、`search-logs`、`architecture`、`create-specs` 等）。
-- `node bin/apollo-toolkit.js architecture [diff]` - 開啟專案 HTML 架構圖，或搭配 `diff` 產生分頁式 before/after 檢視器。
-- `python3 scripts/validate_skill_frontmatter.py` - 驗證所有頂層技能 `SKILL.md` 的 frontmatter 格式與命名規範。
-- `python3 scripts/validate_openai_agent_config.py` - 驗證所有技能 `agents/openai.yaml` 的設定完整性。
+- `node dist/bin/apollo-toolkit.js [mode...]` - 直接從倉庫啟動 CLI，將技能安裝至指定目標（codex/openclaw/trae/agents/claude-code/all）。
+- `node dist/bin/apollo-toolkit.js uninstall [mode...]` - 從指定目標移除已安裝的 Apollo Toolkit 技能。
+- `node dist/bin/apollo-toolkit.js tools` - 列出所有內建 CLI 工具及其分類。
+- `node dist/bin/apollo-toolkit.js <tool> [args...]` - 執行內建工具（如 `filter-logs`、`search-logs`、`architecture`、`create-specs` 等）。
+- `node dist/bin/apollo-toolkit.js architecture [diff]` - 開啟專案 HTML 架構圖，或搭配 `diff` 產生分頁式 before/after 檢視器。
+- `apltk validate-skill-frontmatter` - 驗證所有頂層技能 `SKILL.md` 的 frontmatter 格式與命名規範。
+- `apltk validate-openai-agent-config` - 驗證所有技能 `agents/openai.yaml` 的設定完整性。
 - `./scripts/install_skills.sh [mode...]` - 透過本地 shell 腳本安裝技能（非 npm 安裝方式）。
 
 ## Project Business Goals

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to this repository are documented in this file.
 
+## [v3.14.1] - 2026-05-15
+
+### Fixed
+
+- Replace non-existent `cli.main()` with `cli.dispatch()` in architecture handler, fixing `apltk architecture --help` crash.
+- Correct `repoRoot()` path resolution in `validate-openai-agent-config` tool (3 levels up from `dist/lib/tools/` instead of 2) so CI validation finds skill directories.
+- Add missing `npm run build` step to publish CI workflow so tests importing from `dist/` resolve correctly.
+- Replace removed Python validation scripts (`validate_skill_frontmatter.py`, `validate_openai_agent_config.py`) in CI workflow with their TypeScript CLI equivalents.
+
+## [v3.14.0] - 2026-05-15
+
+### Added
+
+- TypeScript infrastructure (`tsconfig.json`, `lib/types.ts`, `lib/utils/`) for type-safe CLI development.
+- TypeScript handlers for all 19 built-in tools under `lib/tools/`, enabling direct function calls via the CLI without subprocess spawning.
+- `apltk architecture diff` command for paginated before/after architecture viewers.
+- `apltk validate-skill-frontmatter` and `apltk validate-openai-agent-config` CLI commands as TypeScript replacements for the removed Python validation scripts.
+
+### Changed
+
+- Convert CLI core (`lib/cli`, `lib/tool-runner`, `lib/installer`, `lib/updater`, `bin/apollo-toolkit`) from CommonJS JavaScript to TypeScript.
+- Port observability tools (`filter-logs`, `search-logs`), GitHub tools (`open-github-issue`, `find-github-issues`, `read-github-issue`, `review-threads`), media tools (`docs-to-voice`, `render-katex`, `render-error-book`, `generate-storyboard-images`, `enforce-video-aspect-ratio`, `extract-pdf-text`), and spec tools (`create-specs`) from Python/Swift/Shell to TypeScript handlers.
+- Merge two identical `extract_recent_conversations.py` scripts into a single TypeScript handler supporting both `extract-codex-conversations` and `extract-skill-conversations` CLI commands.
+- Replace `init-project-html/scripts/architecture.js` with a TypeScript handler in `lib/tools/architecture.ts`.
+- Update installer to stop copying `scripts/` directories (all tool scripts are now natively handled).
+- Update all SKILL.md files to reference `apltk <tool-name>` instead of legacy script paths.
+- Replace Python validation scripts (`validate_skill_frontmatter.py`, `validate_openai_agent_config.py`) with native TypeScript CLI commands.
+- Archive completed TypeScript migration specs and sync project documentation (architecture docs, testing conventions, AGENTS.md, CLAUDE.md) to reflect current TypeScript-based tooling.
+
+### Removed
+
+- All 14 skill-level `scripts/` directories with 18 Python, 2 Shell, 1 Swift, and 2 JavaScript scripts.
+- `test/python-scripts.test.js` (Python scripts no longer exist).
+- `__pycache__/` and `*.pyc` from `.gitignore` (no more Python assets in the skill tree).
+- Old `docs/plans/2026-05-14/` planning artifacts (archived to `docs/archive/`).
+
 ## [v3.13.2] - 2026-05-14
 
 ### Changed

package/CLAUDE.md

@@ -3,13 +3,13 @@
 ## Common Development Commands
 
 - `npm test` - 執行 Node 測試套件（`node --test`）。
-- `node bin/apollo-toolkit.js [mode...]` - 直接從倉庫啟動 CLI，將技能安裝至指定目標（codex/openclaw/trae/agents/claude-code/all）。
-- `node bin/apollo-toolkit.js uninstall [mode...]` - 從指定目標移除已安裝的 Apollo Toolkit 技能。
-- `node bin/apollo-toolkit.js tools` - 列出所有內建 CLI 工具及其分類。
-- `node bin/apollo-toolkit.js <tool> [args...]` - 執行內建工具（如 `filter-logs`、`search-logs`、`architecture`、`create-specs` 等）。
-- `node bin/apollo-toolkit.js architecture [diff]` - 開啟專案 HTML 架構圖，或搭配 `diff` 產生分頁式 before/after 檢視器。
-- `python3 scripts/validate_skill_frontmatter.py` - 驗證所有頂層技能 `SKILL.md` 的 frontmatter 格式與命名規範。
-- `python3 scripts/validate_openai_agent_config.py` - 驗證所有技能 `agents/openai.yaml` 的設定完整性。
+- `node dist/bin/apollo-toolkit.js [mode...]` - 直接從倉庫啟動 CLI，將技能安裝至指定目標（codex/openclaw/trae/agents/claude-code/all）。
+- `node dist/bin/apollo-toolkit.js uninstall [mode...]` - 從指定目標移除已安裝的 Apollo Toolkit 技能。
+- `node dist/bin/apollo-toolkit.js tools` - 列出所有內建 CLI 工具及其分類。
+- `node dist/bin/apollo-toolkit.js <tool> [args...]` - 執行內建工具（如 `filter-logs`、`search-logs`、`architecture`、`create-specs` 等）。
+- `node dist/bin/apollo-toolkit.js architecture [diff]` - 開啟專案 HTML 架構圖，或搭配 `diff` 產生分頁式 before/after 檢視器。
+- `apltk validate-skill-frontmatter` - 驗證所有頂層技能 `SKILL.md` 的 frontmatter 格式與命名規範。
+- `apltk validate-openai-agent-config` - 驗證所有技能 `agents/openai.yaml` 的設定完整性。
 - `./scripts/install_skills.sh [mode...]` - 透過本地 shell 腳本安裝技能（非 npm 安裝方式）。
 
 ## Project Business Goals
@@ -32,7 +32,7 @@
 - `docs/architecture/skill-structure.md` - 技能目錄佈局、frontmatter 規範、選擇性擴充
 - `docs/principles/naming-conventions.md` - 命名慣例：kebab-case、文件命名、工具命名
 - `docs/principles/skill-development.md` - 技能開發慣例：frontmatter、主體結構、依賴宣告
-- `docs/principles/testing-conventions.md` - 測試慣例：node:test、隔離、Python 測試發現
+- `docs/principles/testing-conventions.md` - 測試慣例：node:test、隔離、輸出捕捉
 - `README.md` - 公開安裝指南與技能目錄
 - `CHANGELOG.md` - 版本發佈歷史
 - `LICENSE` - MIT 授權條款

package/analyse-app-logs/SKILL.md

@@ -118,7 +118,7 @@ Use this structure in responses:
 
 - `references/investigation-checklist.md`: Step-by-step checklist for evidence-driven log investigations.
 - `references/log-signal-patterns.md`: Common log signatures, likely causes, validation hints, and false-positive guards.
-- `scripts/filter_logs_by_time.py`: Filter raw logs to a bounded incident window from files or stdin; exposed as `apltk filter-logs`.
-- `scripts/search_logs.py`: Search logs by keyword or regex with optional time-window filtering and context lines; exposed as `apltk search-logs`.
-- `scripts/log_cli_utils.py`: Shared timestamp parsing and stdin/file iteration utilities for the bundled log scripts.
+- `apltk filter-logs`: Filter raw logs to a bounded incident window from files or stdin (TypeScript handler in `lib/tools/filter-logs.ts`).
+- `apltk search-logs`: Search logs by keyword or regex with optional time-window filtering and context lines (TypeScript handler in `lib/tools/search-logs.ts`).
+- Shared timestamp parsing and stdin/file iteration utilities built into `lib/tools/log-cli-utils.ts`.
 - Dependency skill: `open-github-issue` for deterministic issue publishing with auth fallback and README language detection.

package/bin/apollo-toolkit.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+import { run } from '../lib/cli';
+
+run(process.argv.slice(2)).then((code: number) => {
+  process.exitCode = code;
+});

package/codex/codex-memory-manager/SKILL.md

@@ -25,8 +25,8 @@ Keep a durable, categorized memory of user preferences so future agents can quic
 
 ## Required Resources
 
-- `scripts/extract_recent_conversations.py` to read the last 24 hours of Codex sessions, including archived sessions, exposed as `apltk extract-codex-conversations`.
-- `scripts/sync_memory_index.py` to maintain a normalized memory index section at the end of `~/.codex/AGENTS.md`, exposed as `apltk sync-codex-memory-index`.
+- `apltk extract-codex-conversations`: Read the last N hours of Codex sessions, including archived sessions (TypeScript handler in `lib/tools/extract-conversations.ts`).
+- `apltk sync-codex-memory-index`: Maintain a normalized memory index section at the end of `~/.codex/AGENTS.md` (TypeScript handler in `lib/tools/sync-memory-index.ts`).
 
 ## Workflow
 

package/codex/learn-skill-from-conversations/SKILL.md

@@ -21,7 +21,7 @@ description: Learn and evolve the local skill library from recent Codex conversa
 
 ## Required Resources
 
-- `scripts/extract_recent_conversations.py` for deterministic session extraction, exposed as `apltk extract-skill-conversations`.
+- `apltk extract-skill-conversations`: Deterministic session extraction (TypeScript handler in `lib/tools/extract-conversations.ts`, shared with `codex-memory-manager`).
 - `$skill-creator` for all skill creation/update work.
 
 ## Workflow
@@ -79,7 +79,7 @@ apltk extract-skill-conversations --lookback-minutes 1440
 ### 4) Apply changes through skill-creator
 
 - Explicitly follow `$skill-creator` workflow before editing skills.
-- For new shared skills, initialize with `~/.codex/skills/.system/skill-creator/scripts/init_skill.py`, then complete `SKILL.md` and required resources.
+- For new shared skills, use the Codex system `skill-creator` initialization script (located at `~/.codex/skills/.system/skill-creator/scripts/init_skill.py` -- an external Codex system tool outside the scope of this project), then complete `SKILL.md` and required resources.
 - For new project-specific skills, create or update them under the relevant project's `~/.codex/skills/` directory instead of the shared catalog.
 - For existing skills, make minimal focused edits and keep behavior consistent.
 
@@ -88,7 +88,7 @@ apltk extract-skill-conversations --lookback-minutes 1440
 - Run:
 
 ```bash
-python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py <skill-path>
+python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py <skill-path>  # Codex system validation tool (external, outside the scope of this project)
 ```
 
 - Resolve validation failures before finishing.

package/dist/bin/apollo-toolkit.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/apollo-toolkit.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const cli_1 = require("../lib/cli");
+(0, cli_1.run)(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+});

package/dist/lib/cli.d.ts

@@ -0,0 +1,41 @@
+import type { CliContext, ParsedArguments } from './types';
+declare function buildBanner({ version, colorEnabled }: {
+    version: string;
+    colorEnabled: boolean;
+}): string;
+declare function buildWelcomeScreen({ version, colorEnabled, stage }: {
+    version: string;
+    colorEnabled: boolean;
+    stage?: number;
+}): string;
+declare function buildHelpText({ version, colorEnabled }: {
+    version: string;
+    colorEnabled: boolean;
+}): string;
+declare function buildToolsHelp({ version, colorEnabled }: {
+    version: string;
+    colorEnabled: boolean;
+}): string;
+declare function buildInstallHelpText({ version, colorEnabled }: {
+    version: string;
+    colorEnabled: boolean;
+}): string;
+declare function buildUninstallHelpText({ version, colorEnabled }: {
+    version: string;
+    colorEnabled: boolean;
+}): string;
+declare function parseArguments(argv: string[]): ParsedArguments;
+declare function promptForModes({ stdin, stdout, version, env }: {
+    stdin: NodeJS.ReadStream;
+    stdout: NodeJS.WriteStream;
+    version: string;
+    env: NodeJS.ProcessEnv;
+}): Promise<string[]>;
+declare function promptForUninstallModes({ stdin, stdout, version, env }: {
+    stdin: NodeJS.ReadStream;
+    stdout: NodeJS.WriteStream;
+    version: string;
+    env: NodeJS.ProcessEnv;
+}): Promise<string[]>;
+export { parseArguments, buildHelpText, buildInstallHelpText, buildUninstallHelpText, buildToolsHelp, buildBanner, buildWelcomeScreen, promptForModes, promptForUninstallModes };
+export declare function run(argv: string[], context?: CliContext): Promise<number>;