@laitszkin/apollo-toolkit 3.13.2 → 3.14.1

package/lib/types.ts

@@ -0,0 +1,90 @@
+export interface ToolHelp {
+  purpose: string;
+  useWhen: string[];
+  insteadOf?: string[];
+  examples?: ToolExample[];
+}
+
+export interface ToolExample {
+  command: string;
+  result: string;
+}
+
+export type RunnerKind = 'node' | 'python3' | 'swift';
+
+export interface ToolDefinition {
+  name: string;
+  category: string;
+  skill?: string;
+  script?: string;
+  runner?: RunnerKind;
+  description: string;
+  aliases?: string[];
+  help?: ToolHelp;
+  /** Direct function reference for the tool handler (replaces spawn-based execution). */
+  handler?: (args: string[], context: ToolContext) => Promise<number>;
+  canonicalName?: string;
+}
+
+export interface ToolContext {
+  sourceRoot?: string;
+  stdout?: NodeJS.WriteStream;
+  stderr?: NodeJS.WriteStream;
+  env?: NodeJS.ProcessEnv;
+  spawnCommand?: Function;
+  cwd?: string;
+  stdio?: any;
+}
+
+export type InstallMode = 'codex' | 'openclaw' | 'trae' | 'agents' | 'claude-code';
+
+export interface InstallTarget {
+  id: InstallMode;
+  label: string;
+  description?: string;
+  root?: string;
+}
+
+export interface InstallResult {
+  skillNames: string[];
+  linkMode: 'symlink' | 'copy';
+  targets: { label: string; root: string }[];
+}
+
+export interface ManifestData {
+  version: string;
+  installedAt: string;
+  linkMode: string;
+  skills: string[];
+  historicalSkills: string[];
+}
+
+export interface SyncResult {
+  previousSkillNames: string[];
+}
+
+export interface ParsedArguments {
+  command: 'install' | 'uninstall' | 'tool' | 'tools-help';
+  modes: InstallMode[];
+  showHelp: boolean;
+  showToolsHelp: boolean;
+  toolkitHome: string | null;
+  toolName: string | null;
+  toolArgs: string[];
+  linkMode: 'copy' | 'symlink' | null;
+  assumeYes: boolean;
+  explicitInstallCommand: boolean;
+  helpTopic: string;
+}
+
+export interface CliContext {
+  sourceRoot?: string;
+  stdout?: NodeJS.WriteStream;
+  stderr?: NodeJS.WriteStream;
+  stdin?: NodeJS.ReadStream;
+  env?: NodeJS.ProcessEnv;
+  execCommand?: Function;
+  confirmUpdate?: Function;
+  runTool?: Function;
+  spawnCommand?: Function;
+}

package/lib/updater.ts

@@ -0,0 +1,165 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+
+interface Version {
+  parts: number[];
+  prerelease: string;
+}
+
+interface ExecResult {
+  stdout: string;
+  stderr: string;
+}
+
+interface UpdateCheckResult {
+  checked: boolean;
+  updated: boolean;
+  latestVersion?: string;
+  error?: Error;
+}
+
+function normalizeVersion(version: string): string {
+  return String(version || '')
+    .trim()
+    .replace(/^v/i, '');
+}
+
+function parseVersion(version: string): Version {
+  const normalized = normalizeVersion(version);
+  const [core, prerelease = ''] = normalized.split('-', 2);
+  const parts = core.split('.').map((part) => Number.parseInt(part, 10) || 0);
+  return { parts, prerelease };
+}
+
+export function compareVersions(left: string, right: string): number {
+  const leftVersion = parseVersion(left);
+  const rightVersion = parseVersion(right);
+  const leftParts = leftVersion.parts;
+  const rightParts = rightVersion.parts;
+  const length = Math.max(leftParts.length, rightParts.length);
+
+  for (let index = 0; index < length; index += 1) {
+    const delta = (leftParts[index] || 0) - (rightParts[index] || 0);
+    if (delta !== 0) return delta;
+  }
+
+  if (leftVersion.prerelease && !rightVersion.prerelease) return -1;
+  if (!leftVersion.prerelease && rightVersion.prerelease) return 1;
+  if (leftVersion.prerelease !== rightVersion.prerelease) {
+    return leftVersion.prerelease.localeCompare(rightVersion.prerelease);
+  }
+  return 0;
+}
+
+function shouldSkipUpdateCheck({ env = process.env, stdin = process.stdin, stdout = process.stdout }: {
+  env?: NodeJS.ProcessEnv;
+  stdin?: NodeJS.ReadStream;
+  stdout?: NodeJS.WriteStream;
+}): boolean {
+  return env.APOLLO_TOOLKIT_SKIP_UPDATE_CHECK === '1' || !stdin.isTTY || !stdout.isTTY;
+}
+
+export function execCommand(command: string, args: string[], { env = process.env, stdout, stderr }: {
+  env?: NodeJS.ProcessEnv;
+  stdout?: NodeJS.WriteStream;
+  stderr?: NodeJS.WriteStream;
+} = {}): Promise<ExecResult> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let capturedStdout = '';
+    let capturedStderr = '';
+
+    child.stdout.on('data', (chunk: Buffer) => {
+      capturedStdout += chunk.toString('utf8');
+      if (stdout) stdout.write(chunk);
+    });
+
+    child.stderr.on('data', (chunk: Buffer) => {
+      capturedStderr += chunk.toString('utf8');
+      if (stderr) stderr.write(chunk);
+    });
+
+    child.on('error', reject);
+    child.on('close', (code: number | null) => {
+      if (code !== 0) {
+        reject(new Error(capturedStderr.trim() || `${command} exited with code ${code}`));
+        return;
+      }
+      resolve({ stdout: capturedStdout, stderr: capturedStderr });
+    });
+  });
+}
+
+async function defaultConfirmUpdate({ stdin, stdout, currentVersion, latestVersion, packageName }: {
+  stdin: NodeJS.ReadStream;
+  stdout: NodeJS.WriteStream;
+  currentVersion: string;
+  latestVersion: string;
+  packageName: string;
+}): Promise<boolean> {
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = await rl.question(
+      `A newer ${packageName} release is available (${currentVersion} -> ${latestVersion}). Update now? [Y/n] `,
+    );
+    const normalized = answer.trim().toLowerCase();
+    return normalized === '' || normalized === 'y';
+  } finally {
+    rl.close();
+  }
+}
+
+async function getLatestPublishedVersion({ packageName, env = process.env, exec = execCommand }: {
+  packageName: string;
+  env?: NodeJS.ProcessEnv;
+  exec?: typeof execCommand;
+}): Promise<string> {
+  const result = await exec('npm', ['view', packageName, 'version', '--json'], { env });
+  const parsed = JSON.parse(result.stdout.trim());
+  if (Array.isArray(parsed)) {
+    return String(parsed[parsed.length - 1] || '').trim();
+  }
+  return String(parsed || '').trim();
+}
+
+export async function checkForPackageUpdate({ packageName, currentVersion, env = process.env, stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, exec = execCommand, confirmUpdate = defaultConfirmUpdate }: {
+  packageName: string;
+  currentVersion: string;
+  env?: NodeJS.ProcessEnv;
+  stdin?: NodeJS.ReadStream;
+  stdout?: NodeJS.WriteStream;
+  stderr?: NodeJS.WriteStream;
+  exec?: typeof execCommand;
+  confirmUpdate?: typeof defaultConfirmUpdate;
+}): Promise<UpdateCheckResult> {
+  if (shouldSkipUpdateCheck({ env, stdin, stdout })) {
+    return { checked: false, updated: false };
+  }
+
+  try {
+    const latestVersion = await getLatestPublishedVersion({ packageName, env, exec });
+    if (!latestVersion || compareVersions(latestVersion, currentVersion) <= 0) {
+      return { checked: true, updated: false, latestVersion };
+    }
+
+    const approved = await confirmUpdate({ stdin, stdout, currentVersion, latestVersion, packageName });
+
+    if (!approved) {
+      stdout.write(`Continuing with ${packageName} ${currentVersion}.\n`);
+      return { checked: true, updated: false, latestVersion };
+    }
+
+    stdout.write(`Updating ${packageName} to ${latestVersion}...\n`);
+    await exec('npm', ['install', '-g', `${packageName}@latest`], { env, stdout, stderr });
+    stdout.write(`Update complete. Continuing with ${packageName} ${latestVersion}.\n`);
+
+    return { checked: true, updated: true, latestVersion };
+  } catch (error) {
+    stderr.write(`Warning: unable to check or install package updates: ${(error as Error).message}\n`);
+    return { checked: false, updated: false, error: error as Error };
+  }
+}

package/lib/utils/format.ts

@@ -0,0 +1,7 @@
+import type { ToolExample } from '../types';
+
+export function formatExamples(examples: ToolExample[] = []): string {
+  return examples.map(({ command, result }) => (
+    `  ${command}\n    Result: ${result}`
+  )).join('\n');
+}

package/lib/utils/terminal.ts

@@ -0,0 +1,22 @@
+export function supportsColor(stream: { isTTY?: boolean }, env: NodeJS.ProcessEnv = process.env): boolean {
+  return Boolean(stream && stream.isTTY && !env.NO_COLOR);
+}
+
+export function supportsAnimation(stream: { isTTY?: boolean }, env: NodeJS.ProcessEnv = process.env): boolean {
+  return Boolean(stream && stream.isTTY && !env.CI && env.APOLLO_TOOLKIT_NO_ANIMATION !== '1');
+}
+
+export function color(text: string, code: string, enabled: boolean): string {
+  if (!enabled) return text;
+  return `\x1b[${code}m${text}\x1b[0m`;
+}
+
+export function clearScreen(output: { isTTY?: boolean; write: (str: string) => boolean }): void {
+  if (output.isTTY) {
+    output.write('\x1b[2J\x1b[H');
+  }
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/open-github-issue/SKILL.md

@@ -87,5 +87,5 @@ When another skill depends on `open-github-issue`:
 
 ## Resources
 
-- `scripts/open_github_issue.py`: Deterministic issue publishing helper with auth fallback and README language detection, exposed as `apltk open-github-issue`.
-- If the helper path is unavailable or still fails for environment reasons, fall back to direct `gh issue create` or GitHub REST API publishing instead of retrying the same broken relative-path invocation.
+- `apltk open-github-issue`: Deterministic issue publishing helper with auth fallback and README language detection (TypeScript handler in `lib/tools/open-github-issue.ts`).
+- If the CLI tool is unavailable or fails for environment reasons, fall back to direct `gh issue create` or GitHub REST API publishing instead of retrying the same invocation.

package/optimise-skill/SKILL.md

@@ -16,7 +16,7 @@ description: 當你需要優化 agent skills 的 `SKILL.md` 時，調用這個
 
 ### 1. 識別交付物
 
-完整閱讀整個技能的 `SKILL.md` 文檔，以及其引用的所有額檔案，包括但不限於 `references/` , `scripts/` 。基於獲取到的技能上下文資訊，總結出該技能的最終交付產物。
+完整閱讀整個技能的 `SKILL.md` 文檔，以及其引用的所有額外檔案，包括但不限於 `references/`、`lib/tools/` 中的 TypeScript handler。基於獲取到的技能上下文資訊，總結出該技能的最終交付產物。
 
 ### 2. 制定驗收條件
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "3.13.2",
+  "version": "3.14.1",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",
@@ -13,12 +13,16 @@
     "url": "https://github.com/LaiTszKin/apollo-toolkit/issues"
   },
   "type": "commonjs",
+  "main": "dist/lib/cli.js",
   "bin": {
-    "apollo-toolkit": "bin/apollo-toolkit.js",
-    "apltk": "bin/apollo-toolkit.js"
+    "apollo-toolkit": "dist/bin/apollo-toolkit.js",
+    "apltk": "dist/bin/apollo-toolkit.js"
   },
   "scripts": {
-    "test": "node --test"
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "test": "node --test",
+    "test:ts": "node --test dist/test/"
   },
   "engines": {
     "node": ">=18.18"
@@ -37,5 +41,10 @@
   "dependencies": {
     "elkjs": "^0.11.1",
     "js-yaml": "^4.1.1"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.7.0",
+    "typescript": "^6.0.3"
   }
 }