@laitszkin/apollo-toolkit 4.1.4 → 5.0.1

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 All notable changes to this repository are documented in this file.
 
+## [v5.0.1] - 2026-06-06
+
+### Fixed
+
+- **Publish CI**: Build now passes in fresh CI checkout. Added missing tsconfig `references` for `tui` and `tool-registry` to fix `tsc --build` dependency ordering. Broke circular type dependency between `tool-utils` and `tool-registry` by moving `ToolContext` into `tool-utils`.
+- **Stale tests**: `ToolNotFoundError` formatting tests updated to match `formatAppError` behavior (bare message, no "Error:" prefix). Architecture `REGTEST-15/17` tests updated to handle error-throwing handlers.
+- **Lockfile sync**: `package-lock.json` regenerated to match workspace `package.json` files after version bump.
+
+## [v5.0.0] - 2026-06-06
+
+### Added
+
+- **Schema-based tool argument parsing**: New `createToolRunner()` function in `@laitszkin/tool-utils` that wraps `node:util.parseArgs`. Tools declare options, help text, and validation logic in a single `ToolSchema` declaration — no more hand-rolled `parseArgs()` loops. 18 of 21 in-scope tools migrated.
+- **`PlatformAdapter` cross-platform abstraction**: New `PlatformAdapter` interface in `@laitszkin/tool-utils` with `WindowsAdapter`/`PosixAdapter` implementations. Encapsulates `symlinkType()` (junction on Windows), `resolveCommand()` (`.cmd` resolution), `homeDir()` (multi-env fallback), and `EOL`.
+- **`AppError` hierarchy**: Typed error classes (`UserInputError`, `ToolNotFoundError`, `SystemError`) with `formatAppError()` boundary function. Business logic throws typed errors → CLI boundary catches + consistent stderr formatting.
+- **Command parser classes**: `InstallArgsParser`, `UninstallArgsParser`, `ToolArgsParser` implementing `CommandParser<T>` interface. Independently testable, map-based dispatch table replaces the monolithic `parseArguments()` if-else chain.
+- **`HelpTextBuilder`**: Unified help text generator replaces 4 nearly-identical help builders. Command types provide section content declaratively.
+- **Per-group test coverage thresholds**: Two-tier enforcement — Group 1 (`test/`) at 75/60/65 lines/branches/functions; Group 2 (`packages/`) at 65/60/65. Combined file-weighted ≥80% enforced in `scripts/test.sh`.
+- **CI matrix (ubuntu + windows)**: `.github/workflows/test.yml` runs `npm test` on both `ubuntu-latest` and `windows-latest` with `fail-fast: false`.
+
+### Changed
+
+- **Internal package versions unified to 5.0.0**: All 24 `@laitszkin/*` packages bumped from 4.0.8 to 5.0.0 to match the root package version.
+- **Global install dependency chain fixed**: Root `package.json` now lists `@laitszkin/cli` as a direct dependency; `@laitszkin/cli` now lists `@laitszkin/tool-codegraph` and `@laitszkin/tool-eval` so all registered tools are resolvable when installed via `npm install -g @laitszkin/apollo-toolkit`.
+- **Coverage enforcement**: `scripts/test.sh` enforces combined file-weighted ≥80% line coverage across Groups 1 and 2, with per-group minimums. Group 3 (mock.module tests, codegraph) excluded due to Node.js flag incompatibility.
+- **Design doc accuracy**: Six inaccuracies in DESIGN.md corrected — branch thresholds, split-process description, `--check-coverage` references aligned with actual implementation.
+- **Windows CI comment updated**: `.github/workflows/test.yml` comment now accurately describes coverage enforcement mechanism.
+
+### Fixed
+
+- **`docs-to-voice` syntax corruption**: Three structural defects from ToolSchema migration (fdf8628b) repaired — duplicated code block, missing `if (mode === "say")` wrapper, missing `textChunks` definition. These caused `tsc --build` to emit garbled JS, blocking `registerAllTools()` from loading any tool.
+- **Error cause chain preservation**: Original error causes are now passed via `{ cause: err }` in filter-logs, codegraph, and open-github-issue error re-wraps. Regression tests added.
+- **EPERM symlink fallback**: `installer.ts` degrades to copy mode with a warning when `fs.symlink` fails with EPERM on Windows.
+- **All `\n` hardcodes replaced**: Manifest writes, schema output, error formatting, and EPERM warnings now use `os.EOL` or `adapter.EOL`.
+- **Carryover tools `--help` support**: Three carryover tools (open-github-issue, find-github-issues, review-threads) received `--help` output handling.
+- **Storyboard failure return code**: `generate-storyboard-images` now returns non-zero exit code when API failures occur.
+- **TypeScript build config**: Narrowed `tui` and `tool-registry` tsconfig `include` from `"**/*.ts"` to `"*.ts"` to prevent TS5055 dist/ overwrite errors in TypeScript 5.5+.
+
+### Removed
+
+- **Monolithic `parseArguments()` if-else chain**: Replaced with Map-based dispatch table and per-command parser classes.
+- **Individual tool `parseArgs()` implementations**: 18 tools' ad-hoc argument parsing removed in favor of `createToolRunner` schema.
+- **Dead code in enforce-video-aspect-ratio**: ~75 lines of unreachable `parseArgs`/`AspectArgs`/`help` field removed after `createToolRunner` migration.
+- **Unused stderr bindings in architecture tool**: Both `handleApply` and `handleTemplate` cleaned.
+
 ## [v4.1.4] - 2026-06-04
 
 ### Fixed

package/bin/apollo-toolkit.ts

@@ -8,4 +8,8 @@ const sourceRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '.
 
 run(process.argv.slice(2), { sourceRoot }).then((code: number) => {
   process.exitCode = code;
+}).catch((err: unknown) => {
+  const message = err instanceof Error ? err.message : String(err);
+  process.stderr.write(message + '\n');
+  process.exitCode = 1;
 });

package/dist/bin/apollo-toolkit.js

@@ -5,4 +5,8 @@ import { fileURLToPath } from 'node:url';
 const sourceRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 run(process.argv.slice(2), { sourceRoot }).then((code) => {
     process.exitCode = code;
+}).catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(message + '\n');
+    process.exitCode = 1;
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "4.1.4",
+  "version": "5.0.1",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",
@@ -28,6 +28,7 @@
     "prepublishOnly": "npm run build",
     "watch": "tsc --build --watch",
     "test": "scripts/test.sh",
+    "test:coverage": "COVERAGE=true npm test",
     "test:ts": "node --test dist/test/"
   },
   "engines": {
@@ -58,4 +59,4 @@
     "@types/node": "^25.9.1",
     "typescript": "^6.0.3"
   }
-}
+}

package/packages/cli/dist/help-text-builder.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Produces the four help text sections previously generated by standalone
+ * functions.  Each method returns text identical to the original builder so
+ * that observable CLI output is unchanged.
+ */
+export declare class HelpTextBuilder {
+    private version;
+    private colorEnabled;
+    constructor({ version, colorEnabled }: {
+        version: string;
+        colorEnabled: boolean;
+    });
+    private modeUsagePattern;
+    private joinLines;
+    /** Replaces  buildHelpText  –  top-level overview help. */
+    overview(): string;
+    /** Replaces  buildInstallHelpText  –  install-specific help. */
+    install(): string;
+    /** Replaces  buildUninstallHelpText  –  uninstall-specific help. */
+    uninstall(): string;
+    /** Replaces  buildToolsHelp  –  tools listing help screen. */
+    toolsHelp(): string;
+}

package/packages/cli/dist/help-text-builder.js

@@ -0,0 +1,166 @@
+import { buildBanner, buildSupportedTargetLines } from '../../tui/dist/index.js';
+import { formatToolList, buildToolDiscoveryHelp, formatExamples } from '../../tool-registry/dist/index.js';
+import { TARGET_DEFINITIONS, VALID_MODES } from './installer.js';
+/**
+ * Produces the four help text sections previously generated by standalone
+ * functions.  Each method returns text identical to the original builder so
+ * that observable CLI output is unchanged.
+ */
+export class HelpTextBuilder {
+    version;
+    colorEnabled;
+    constructor({ version, colorEnabled }) {
+        this.version = version;
+        this.colorEnabled = colorEnabled;
+    }
+    // ---- shared helpers -------------------------------------------------------
+    modeUsagePattern() {
+        return `${VALID_MODES.join('|')}|all`;
+    }
+    joinLines(lines) {
+        return lines.filter(Boolean).join('\n');
+    }
+    // ---- public methods -------------------------------------------------------
+    /** Replaces  buildHelpText  –  top-level overview help. */
+    overview() {
+        const examples = [
+            { command: 'apltk --help', result: 'Shows the top-level Apollo Toolkit guide, including install modes and bundled task-tool discovery.' },
+            { command: 'apltk tools --help', result: 'Lists bundled tools by task so you can decide which CLI helper to inspect next.' },
+            { command: 'apltk architecture --help', result: 'Shows the architecture atlas command tree, task guidance, and action-specific follow-up help paths.' },
+            { command: 'apltk tools architecture --help', result: 'Shows what the architecture atlas tool is for, then prints its native command tree and examples.' },
+            { command: 'apltk filter-logs app.log --start 2026-03-24T10:00:00Z', result: 'Prints only the log lines whose timestamps fall within the requested time window.' },
+        ];
+        return this.joinLines([
+            buildBanner({ version: this.version, colorEnabled: this.colorEnabled }),
+            '',
+            'Usage:',
+            `  apltk [install] [${this.modeUsagePattern()}]...`,
+            `  apollo-toolkit [install] [${this.modeUsagePattern()}]...`,
+            `  apltk uninstall [${this.modeUsagePattern()}]... [--yes]`,
+            '  apltk tools',
+            '  apltk <tool> [...args]',
+            '  apltk tools <tool> [...args]',
+            '  apltk --help',
+            '  apollo-toolkit --help',
+            '',
+            'Common goals:',
+            '  - Install or refresh skills in one or more agent targets: `apltk install --help`',
+            '  - Remove manifest-tracked installs from selected targets: `apltk uninstall --help`',
+            '  - Discover which bundled helper tool matches a task: `apltk tools --help`',
+            '  - Inspect one tool deeply before running it: `apltk tools <tool> --help`',
+            '',
+            'Bundled tools:',
+            formatToolList(),
+            '',
+            buildToolDiscoveryHelp(),
+            '',
+            'Options:',
+            '  --home <path>  Override Apollo Toolkit home directory',
+            '  --symlink      Install skills as symlinks instead of copied directories',
+            '  --copy         Install skills as copied directories instead of symlinks',
+            '  --yes, -y      Skip uninstall confirmation',
+            '  --help         Show this help text',
+            '',
+            'Examples:',
+            formatExamples(examples),
+        ]);
+    }
+    /** Replaces  buildInstallHelpText  –  install-specific help. */
+    install() {
+        const examples = [
+            { command: 'apltk', result: 'Launches the interactive installer, opens the target selector, and then walks through link-mode confirmation.' },
+            { command: 'apltk codex openclaw --symlink', result: 'Performs a non-interactive install into `codex` and `openclaw` targets using symlinks.' },
+            { command: 'npx @laitszkin/apollo-toolkit all --copy', result: 'Installs a copied snapshot into every supported target instead of symlinking.' },
+        ];
+        return this.joinLines([
+            buildBanner({ version: this.version, colorEnabled: this.colorEnabled }),
+            '',
+            'Usage:',
+            `  apltk [install] [${this.modeUsagePattern()}]...`,
+            `  apollo-toolkit [install] [${this.modeUsagePattern()}]...`,
+            '',
+            'Use this when:',
+            '  - You want to install or refresh Apollo Toolkit skills in one or more agent targets.',
+            '  - You need to choose between symlink mode (auto-updating) and copy mode (stable snapshot).',
+            '',
+            'Supported targets:',
+            buildSupportedTargetLines({ targets: [...TARGET_DEFINITIONS], colorEnabled: this.colorEnabled }),
+            '',
+            'Behavior notes:',
+            '  - Running `apltk` with no targets opens the interactive installer and target selector.',
+            '  - `--symlink` keeps installed skills connected to the managed toolkit checkout in `~/.apollo-toolkit`.',
+            '  - `--copy` installs a snapshot that only changes when you run the installer again.',
+            '  - The installer can optionally include codex-exclusive skills in non-codex targets after prompting.',
+            '',
+            'Options:',
+            '  --home <path>  Override Apollo Toolkit home directory',
+            '  --symlink      Install skills as symlinks (recommended)',
+            '  --copy         Install skills as copied directories',
+            '  --help         Show this install help',
+            '',
+            'Examples:',
+            formatExamples(examples),
+        ]);
+    }
+    /** Replaces  buildUninstallHelpText  –  uninstall-specific help. */
+    uninstall() {
+        const examples = [
+            { command: 'apltk uninstall', result: 'Opens the interactive uninstall selector when running in a TTY and then asks for confirmation before removal.' },
+            { command: 'apltk uninstall codex agents --yes', result: 'Removes Apollo Toolkit-managed installs from `codex` and `agents` without another confirmation prompt.' },
+            { command: 'apltk uninstall codex --home /tmp/custom-home', result: 'Uses the custom managed toolkit home while removing manifest-tracked installs from the selected target.' },
+        ];
+        return this.joinLines([
+            buildBanner({ version: this.version, colorEnabled: this.colorEnabled }),
+            '',
+            'Usage:',
+            `  apltk uninstall [${this.modeUsagePattern()}]... [--yes]`,
+            '',
+            'Use this when:',
+            '  - You want to remove Apollo Toolkit-managed skills from one or more agent targets.',
+            '  - You need to clean up manifest-tracked historical installs as well as the current installed skills.',
+            '',
+            'Supported targets:',
+            buildSupportedTargetLines({ targets: [...TARGET_DEFINITIONS], colorEnabled: this.colorEnabled }),
+            '',
+            'Behavior notes:',
+            '  - With no explicit targets, uninstall opens the interactive selector in a TTY and otherwise falls back to all targets.',
+            '  - Uninstall removes manifest-tracked current and historical Apollo Toolkit skill directories.',
+            '  - `--yes` skips the confirmation prompt after the target list is resolved.',
+            '',
+            'Options:',
+            '  --home <path>  Override Apollo Toolkit home directory',
+            '  --yes, -y      Skip uninstall confirmation',
+            '  --help         Show this uninstall help',
+            '',
+            'Examples:',
+            formatExamples(examples),
+        ]);
+    }
+    /** Replaces  buildToolsHelp  –  tools listing help screen. */
+    toolsHelp() {
+        const examples = [
+            { command: 'apltk tools', result: 'Lists all bundled tools plus the task-oriented discovery guide.' },
+            { command: 'apltk tools open-github-issue --help', result: 'Shows when to use the GitHub issue publisher, then prints its exact script flags and examples.' },
+            { command: 'apltk tools architecture --help', result: 'Shows when to use the architecture atlas CLI, then prints its native command tree.' },
+        ];
+        return this.joinLines([
+            buildBanner({ version: this.version, colorEnabled: this.colorEnabled }),
+            '',
+            'Usage:',
+            '  apltk tools',
+            '  apltk <tool> [...args]',
+            '  apltk tools <tool> [...args]',
+            '',
+            buildToolDiscoveryHelp(),
+            '',
+            'Bundled tools:',
+            formatToolList(),
+            '',
+            'Tip:',
+            '  Pass `--help` after a tool name to view task guidance, native script flags, and concrete examples.',
+            '',
+            'Examples:',
+            formatExamples(examples),
+        ]);
+    }
+}

package/packages/cli/dist/index.d.ts

@@ -4,22 +4,11 @@ import { checkForPackageUpdate, compareVersions, execCommand } from './updater.j
 import { registerAllTools } from './tool-registration.js';
 export { TARGET_DEFINITIONS, VALID_MODES, installLinks, listAllKnownSkillNames, listCodexSkillNames, normalizeModes, resolveToolkitHome, syncToolkitHome, uninstallSkills, getTargetRoots, getUninstallTargetRoots, expandUserPath, readManifest, writeManifest, resolveHomeDirectory, listSkillNames, checkForPackageUpdate, compareVersions, execCommand, };
 import type { CliContext, ParsedArguments } from './types.js';
-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;
-export { parseArguments, buildHelpText, buildInstallHelpText, buildUninstallHelpText, buildToolsHelp, buildBanner, buildWelcomeScreen, registerAllTools };
+export { InstallArgsParser } from './parsers/install-parser.js';
+export { UninstallArgsParser } from './parsers/uninstall-parser.js';
+export { ToolArgsParser } from './parsers/tool-parser.js';
+export { HelpTextBuilder } from './help-text-builder.js';
+export { normalizeParseError } from './parsers/parser-utils.js';
+export { parseArguments, buildBanner, buildWelcomeScreen, registerAllTools };
 export declare function run(argv: string[], context?: CliContext): Promise<number>;