@laitszkin/apollo-toolkit 3.13.2 → 3.14.0

package/dist/lib/installer.d.ts

@@ -0,0 +1,59 @@
+import type { InstallMode, InstallTarget, ManifestData, SyncResult } from './types';
+export interface TargetDefinition {
+    id: InstallMode;
+    label: string;
+    description: string;
+}
+export declare const TARGET_DEFINITIONS: readonly TargetDefinition[];
+export declare const VALID_MODES: readonly InstallMode[];
+export declare const MANIFEST_FILENAME = ".apollo-toolkit-manifest.json";
+export declare function resolveHomeDirectory(env?: NodeJS.ProcessEnv): string;
+export declare function expandUserPath(inputPath: string, env?: NodeJS.ProcessEnv): string;
+export declare function resolveToolkitHome(env?: NodeJS.ProcessEnv): string;
+export declare function normalizeModes(inputModes: string[]): InstallMode[];
+export declare function listSkillNames(rootDir: string, modes?: InstallMode[]): Promise<string[]>;
+export declare function listCodexSkillNames(rootDir: string): Promise<string[]>;
+export declare function readManifest(targetRoot: string): Promise<ManifestData | null>;
+export declare function writeManifest(targetRoot: string, { version, linkMode, skills, previousSkills }: {
+    version: string;
+    linkMode: string;
+    skills: string[];
+    previousSkills?: string[];
+}): Promise<void>;
+export declare function listAllKnownSkillNames({ toolkitHome, modes, env }: {
+    toolkitHome: string;
+    modes?: InstallMode[];
+    env?: NodeJS.ProcessEnv;
+}): Promise<string[]>;
+export declare function syncToolkitHome({ sourceRoot, toolkitHome, version, modes }: {
+    sourceRoot: string;
+    toolkitHome: string;
+    version: string;
+    modes?: InstallMode[];
+}): Promise<SyncResult & {
+    toolkitHome: string;
+    skillNames: string[];
+}>;
+export declare function getTargetRoots(modes: string[], env?: NodeJS.ProcessEnv): Promise<InstallTarget[]>;
+export declare function getUninstallTargetRoots(modes?: string[], env?: NodeJS.ProcessEnv): Promise<InstallTarget[]>;
+export declare function installLinks({ toolkitHome, modes, env, previousSkillNames, linkMode, includeExclusiveSkills }: {
+    toolkitHome: string;
+    modes: InstallMode[];
+    env?: NodeJS.ProcessEnv;
+    previousSkillNames?: string[];
+    linkMode?: 'copy' | 'symlink';
+    includeExclusiveSkills?: boolean;
+}): Promise<{
+    skillNames: string[];
+    targets: InstallTarget[];
+    copiedPaths: any[];
+    linkMode: string;
+}>;
+export declare function uninstallSkills({ env, modes }?: {
+    env?: NodeJS.ProcessEnv;
+    modes?: InstallMode[] | null;
+}): Promise<{
+    target: string;
+    root: string;
+    removedSkills: string[];
+}[]>;

package/dist/lib/installer.js

@@ -0,0 +1,404 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MANIFEST_FILENAME = exports.VALID_MODES = exports.TARGET_DEFINITIONS = void 0;
+exports.resolveHomeDirectory = resolveHomeDirectory;
+exports.expandUserPath = expandUserPath;
+exports.resolveToolkitHome = resolveToolkitHome;
+exports.normalizeModes = normalizeModes;
+exports.listSkillNames = listSkillNames;
+exports.listCodexSkillNames = listCodexSkillNames;
+exports.readManifest = readManifest;
+exports.writeManifest = writeManifest;
+exports.listAllKnownSkillNames = listAllKnownSkillNames;
+exports.syncToolkitHome = syncToolkitHome;
+exports.getTargetRoots = getTargetRoots;
+exports.getUninstallTargetRoots = getUninstallTargetRoots;
+exports.installLinks = installLinks;
+exports.uninstallSkills = uninstallSkills;
+const node_fs_1 = __importDefault(require("node:fs"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+exports.TARGET_DEFINITIONS = Object.freeze([
+    { id: 'codex', label: 'Codex', description: '~/.codex/skills' },
+    { id: 'openclaw', label: 'OpenClaw', description: '~/.openclaw/workspace*/skills' },
+    { id: 'trae', label: 'Trae', description: '~/.trae/skills' },
+    { id: 'agents', label: 'Agents', description: '~/.agents/skills' },
+    { id: 'claude-code', label: 'Claude Code', description: '~/.claude/skills' },
+]);
+exports.VALID_MODES = exports.TARGET_DEFINITIONS.map(({ id }) => id);
+const COPY_FILES = new Set(['AGENTS.md', 'CHANGELOG.md', 'LICENSE', 'README.md', 'package.json']);
+const COPY_DIRS = new Set();
+exports.MANIFEST_FILENAME = '.apollo-toolkit-manifest.json';
+function resolveHomeDirectory(env = process.env) {
+    return env.HOME || env.USERPROFILE || node_os_1.default.homedir();
+}
+function expandUserPath(inputPath, env = process.env) {
+    if (!inputPath)
+        return inputPath;
+    if (inputPath === '~')
+        return resolveHomeDirectory(env);
+    if (inputPath.startsWith('~/') || inputPath.startsWith('~\\')) {
+        return node_path_1.default.join(resolveHomeDirectory(env), inputPath.slice(2));
+    }
+    return inputPath;
+}
+function resolveToolkitHome(env = process.env) {
+    if (env.APOLLO_TOOLKIT_HOME) {
+        return node_path_1.default.resolve(expandUserPath(env.APOLLO_TOOLKIT_HOME, env));
+    }
+    return node_path_1.default.join(resolveHomeDirectory(env), '.apollo-toolkit');
+}
+function normalizeModes(inputModes) {
+    const modes = [];
+    for (const rawMode of inputModes) {
+        const mode = String(rawMode).toLowerCase();
+        if (mode === 'all') {
+            for (const candidate of exports.VALID_MODES) {
+                if (!modes.includes(candidate)) {
+                    modes.push(candidate);
+                }
+            }
+            continue;
+        }
+        if (!exports.VALID_MODES.includes(mode)) {
+            throw new Error(`Invalid mode: ${rawMode}`);
+        }
+        if (!modes.includes(mode)) {
+            modes.push(mode);
+        }
+    }
+    return modes;
+}
+async function listSkillNames(rootDir, modes = []) {
+    const entries = await promises_1.default.readdir(rootDir, { withFileTypes: true });
+    const skillNames = new Set();
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (node_fs_1.default.existsSync(node_path_1.default.join(rootDir, entry.name, 'SKILL.md'))) {
+            skillNames.add(entry.name);
+        }
+    }
+    if (modes.includes('codex')) {
+        const codexDir = node_path_1.default.join(rootDir, 'codex');
+        if (node_fs_1.default.existsSync(codexDir)) {
+            const codexEntries = await promises_1.default.readdir(codexDir, { withFileTypes: true });
+            for (const entry of codexEntries) {
+                if (entry.isDirectory() && node_fs_1.default.existsSync(node_path_1.default.join(codexDir, entry.name, 'SKILL.md'))) {
+                    skillNames.add(entry.name);
+                }
+            }
+        }
+    }
+    return [...skillNames].sort();
+}
+async function listCodexSkillNames(rootDir) {
+    const codexDir = node_path_1.default.join(rootDir, 'codex');
+    if (!node_fs_1.default.existsSync(codexDir))
+        return [];
+    const entries = await promises_1.default.readdir(codexDir, { withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isDirectory() && node_fs_1.default.existsSync(node_path_1.default.join(codexDir, entry.name, 'SKILL.md')))
+        .map((entry) => entry.name)
+        .sort();
+}
+async function readManifest(targetRoot) {
+    const manifestPath = node_path_1.default.join(targetRoot, exports.MANIFEST_FILENAME);
+    try {
+        const raw = await promises_1.default.readFile(manifestPath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function isSafeSkillName(skillName) {
+    return typeof skillName === 'string'
+        && skillName.length > 0
+        && !skillName.includes('\0')
+        && !skillName.includes('/')
+        && !skillName.includes('\\')
+        && !node_path_1.default.isAbsolute(skillName)
+        && skillName !== '.'
+        && skillName !== '..';
+}
+function getManifestSkillNames(manifest) {
+    return [...new Set([
+            ...(Array.isArray(manifest.historicalSkills) ? manifest.historicalSkills : []),
+            ...(Array.isArray(manifest.skills) ? manifest.skills : []),
+        ])].filter(isSafeSkillName).sort();
+}
+async function writeManifest(targetRoot, { version, linkMode, skills, previousSkills = [] }) {
+    const historicalSkills = [...new Set([...previousSkills, ...skills])].sort();
+    const manifest = {
+        version,
+        installedAt: new Date().toISOString(),
+        linkMode,
+        skills: [...skills].sort(),
+        historicalSkills,
+    };
+    await promises_1.default.mkdir(targetRoot, { recursive: true });
+    await promises_1.default.writeFile(node_path_1.default.join(targetRoot, exports.MANIFEST_FILENAME), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+}
+async function listAllKnownSkillNames({ toolkitHome, modes = [], env = process.env }) {
+    const allNames = new Set();
+    const currentSkills = await listSkillNames(toolkitHome, modes).catch(() => []);
+    for (const name of currentSkills)
+        allNames.add(name);
+    const targets = await getUninstallTargetRoots(modes, env);
+    for (const target of targets) {
+        if (!target.root)
+            continue;
+        const manifest = await readManifest(target.root);
+        if (manifest && manifest.historicalSkills) {
+            for (const name of getManifestSkillNames(manifest)) {
+                allNames.add(name);
+            }
+        }
+    }
+    return [...allNames].sort();
+}
+function getTargetSkillNames({ targetMode, sharedSkillNames, codexSkillNames, includeExclusiveSkills = false }) {
+    const includeCodexSkills = targetMode === 'codex' || includeExclusiveSkills;
+    if (!includeCodexSkills || codexSkillNames.length === 0)
+        return sharedSkillNames;
+    return [...new Set([...sharedSkillNames, ...codexSkillNames])].sort();
+}
+function resolveInstallSourcePath({ toolkitHome, targetMode, skillName, codexSkillNames }) {
+    if (targetMode === 'codex' && codexSkillNames.includes(skillName)) {
+        return node_path_1.default.join(toolkitHome, 'codex', skillName);
+    }
+    return node_path_1.default.join(toolkitHome, skillName);
+}
+function shouldCopyEntry(sourceRoot, entry) {
+    if (entry.isFile())
+        return COPY_FILES.has(entry.name);
+    if (!entry.isDirectory())
+        return false;
+    if (COPY_DIRS.has(entry.name))
+        return true;
+    return node_fs_1.default.existsSync(node_path_1.default.join(sourceRoot, entry.name, 'SKILL.md'));
+}
+function shouldCopyCodexContainer({ sourceRoot, entry, modes = [] }) {
+    if (entry.name !== 'codex' || !entry.isDirectory() || !modes.includes('codex'))
+        return false;
+    const codexDir = node_path_1.default.join(sourceRoot, entry.name);
+    if (!node_fs_1.default.existsSync(codexDir))
+        return false;
+    const childNames = node_fs_1.default.readdirSync(codexDir);
+    return childNames.some((childName) => node_fs_1.default.existsSync(node_path_1.default.join(codexDir, childName, 'SKILL.md')));
+}
+async function stageToolkitContents({ sourceRoot, destinationRoot, version, modes = [] }) {
+    const entries = await promises_1.default.readdir(sourceRoot, { withFileTypes: true });
+    const copiedEntries = [];
+    await promises_1.default.mkdir(destinationRoot, { recursive: true });
+    for (const entry of entries) {
+        if (!shouldCopyEntry(sourceRoot, entry) && !shouldCopyCodexContainer({ sourceRoot, entry, modes }))
+            continue;
+        const sourcePath = node_path_1.default.join(sourceRoot, entry.name);
+        const destinationPath = node_path_1.default.join(destinationRoot, entry.name);
+        await promises_1.default.cp(sourcePath, destinationPath, { recursive: true, force: true });
+        copiedEntries.push(entry.name);
+    }
+    const metadata = { version, installedAt: new Date().toISOString(), source: 'npm-package' };
+    await promises_1.default.writeFile(node_path_1.default.join(destinationRoot, '.apollo-toolkit-install.json'), `${JSON.stringify(metadata, null, 2)}\n`, 'utf8');
+    return copiedEntries.sort();
+}
+async function syncToolkitHome({ sourceRoot, toolkitHome, version, modes = [] }) {
+    const parentDir = node_path_1.default.dirname(toolkitHome);
+    const tempDir = node_path_1.default.join(parentDir, `.apollo-toolkit.tmp-${process.pid}-${Date.now()}`);
+    const previousSkillNames = await listSkillNames(toolkitHome, modes).catch(() => []);
+    await promises_1.default.rm(tempDir, { recursive: true, force: true });
+    await stageToolkitContents({ sourceRoot, destinationRoot: tempDir, version, modes });
+    const stat = await promises_1.default.lstat(toolkitHome).catch(() => null);
+    if (stat && !stat.isDirectory()) {
+        throw new Error(`Apollo Toolkit home exists but is not a directory: ${toolkitHome}`);
+    }
+    await promises_1.default.rm(toolkitHome, { recursive: true, force: true });
+    await promises_1.default.mkdir(parentDir, { recursive: true });
+    await promises_1.default.rename(tempDir, toolkitHome);
+    return {
+        toolkitHome,
+        previousSkillNames,
+        skillNames: await listSkillNames(toolkitHome, modes),
+    };
+}
+async function getTargetRoots(modes, env = process.env) {
+    const homeDir = resolveHomeDirectory(env);
+    const targets = [];
+    for (const mode of normalizeModes(modes)) {
+        if (mode === 'codex') {
+            targets.push({
+                id: mode,
+                label: 'Codex',
+                root: env.CODEX_SKILLS_DIR
+                    ? node_path_1.default.resolve(expandUserPath(env.CODEX_SKILLS_DIR, env))
+                    : node_path_1.default.join(homeDir, '.codex', 'skills'),
+            });
+            continue;
+        }
+        if (mode === 'trae') {
+            targets.push({
+                id: mode,
+                label: 'Trae',
+                root: env.TRAE_SKILLS_DIR
+                    ? node_path_1.default.resolve(expandUserPath(env.TRAE_SKILLS_DIR, env))
+                    : node_path_1.default.join(homeDir, '.trae', 'skills'),
+            });
+            continue;
+        }
+        if (mode === 'agents') {
+            targets.push({
+                id: mode,
+                label: 'Agents',
+                root: env.AGENTS_SKILLS_DIR
+                    ? node_path_1.default.resolve(expandUserPath(env.AGENTS_SKILLS_DIR, env))
+                    : node_path_1.default.join(homeDir, '.agents', 'skills'),
+            });
+            continue;
+        }
+        if (mode === 'openclaw') {
+            const openclawHome = env.OPENCLAW_HOME
+                ? node_path_1.default.resolve(expandUserPath(env.OPENCLAW_HOME, env))
+                : node_path_1.default.join(homeDir, '.openclaw');
+            const entries = await promises_1.default.readdir(openclawHome, { withFileTypes: true }).catch(() => []);
+            const workspaceNames = entries
+                .filter((entry) => entry.isDirectory() && entry.name.startsWith('workspace'))
+                .map((entry) => entry.name)
+                .sort();
+            if (workspaceNames.length === 0) {
+                throw new Error(`No workspace directories found under: ${openclawHome}`);
+            }
+            for (const workspaceName of workspaceNames) {
+                targets.push({
+                    id: mode,
+                    label: `OpenClaw (${workspaceName})`,
+                    root: node_path_1.default.join(openclawHome, workspaceName, 'skills'),
+                });
+            }
+            continue;
+        }
+        if (mode === 'claude-code') {
+            targets.push({
+                id: mode,
+                label: 'Claude Code',
+                root: env.CLAUDE_CODE_SKILLS_DIR
+                    ? node_path_1.default.resolve(expandUserPath(env.CLAUDE_CODE_SKILLS_DIR, env))
+                    : node_path_1.default.join(homeDir, '.claude', 'skills'),
+            });
+            continue;
+        }
+    }
+    return targets;
+}
+async function getUninstallTargetRoots(modes = [...exports.VALID_MODES], env = process.env) {
+    const targets = [];
+    for (const mode of normalizeModes(modes)) {
+        try {
+            targets.push(...await getTargetRoots([mode], env));
+        }
+        catch {
+            // Uninstall is best-effort across agents
+        }
+    }
+    return targets;
+}
+async function ensureDirectory(dirPath) {
+    await promises_1.default.mkdir(dirPath, { recursive: true });
+}
+async function replaceWithCopy(sourcePath, targetPath) {
+    await promises_1.default.rm(targetPath, { recursive: true, force: true });
+    await ensureDirectory(node_path_1.default.dirname(targetPath));
+    await promises_1.default.cp(sourcePath, targetPath, { recursive: true, force: true });
+}
+async function replaceWithSymlink(sourcePath, targetPath) {
+    await promises_1.default.rm(targetPath, { recursive: true, force: true });
+    await ensureDirectory(node_path_1.default.dirname(targetPath));
+    await promises_1.default.symlink(sourcePath, targetPath, process.platform === 'win32' ? 'junction' : 'dir');
+}
+async function installLinks({ toolkitHome, modes, env = process.env, previousSkillNames = [], linkMode = 'copy', includeExclusiveSkills = false }) {
+    const normalizedModes = normalizeModes(modes);
+    const codexSkillNames = (normalizedModes.includes('codex') || includeExclusiveSkills)
+        ? await listCodexSkillNames(toolkitHome)
+        : [];
+    const sharedSkillNames = await listSkillNames(toolkitHome);
+    const skillNames = normalizedModes.includes('codex')
+        ? [...new Set([...sharedSkillNames, ...codexSkillNames])].sort()
+        : sharedSkillNames;
+    const targets = await getTargetRoots(normalizedModes, env);
+    const copiedPaths = [];
+    for (const target of targets) {
+        const targetSkillNames = getTargetSkillNames({
+            targetMode: target.id,
+            sharedSkillNames,
+            codexSkillNames,
+            includeExclusiveSkills,
+        });
+        const existingManifest = await readManifest(target.root);
+        const allPreviousSkills = existingManifest
+            ? [...new Set([...getManifestSkillNames(existingManifest), ...previousSkillNames.filter(isSafeSkillName)])]
+            : previousSkillNames.filter(isSafeSkillName);
+        const staleSkillNames = allPreviousSkills.filter((skillName) => !targetSkillNames.includes(skillName));
+        await ensureDirectory(target.root);
+        for (const staleSkillName of staleSkillNames) {
+            await promises_1.default.rm(node_path_1.default.join(target.root, staleSkillName), { recursive: true, force: true });
+        }
+        for (const skillName of targetSkillNames) {
+            const sourcePath = resolveInstallSourcePath({
+                toolkitHome,
+                targetMode: target.id,
+                skillName,
+                codexSkillNames,
+            });
+            const targetPath = node_path_1.default.join(target.root, skillName);
+            if (linkMode === 'symlink') {
+                await replaceWithSymlink(sourcePath, targetPath);
+            }
+            else {
+                await replaceWithCopy(sourcePath, targetPath);
+            }
+            copiedPaths.push({ target: target.label, path: targetPath, skillName, linkMode });
+        }
+        await writeManifest(target.root, {
+            version: existingManifest?.version || 'unknown',
+            linkMode,
+            skills: targetSkillNames,
+            previousSkills: allPreviousSkills,
+        });
+    }
+    return { skillNames, targets, copiedPaths, linkMode };
+}
+async function uninstallSkills({ env = process.env, modes = null } = {}) {
+    const normalizedModes = modes ? normalizeModes(modes) : [...exports.VALID_MODES];
+    const targets = await getUninstallTargetRoots(normalizedModes, env);
+    const results = [];
+    for (const target of targets) {
+        const manifest = await readManifest(target.root);
+        if (!manifest)
+            continue;
+        const skillNames = getManifestSkillNames(manifest);
+        const removedSkills = [];
+        for (const skillName of skillNames) {
+            const skillPath = node_path_1.default.join(target.root, skillName);
+            try {
+                await promises_1.default.rm(skillPath, { recursive: true, force: true });
+                removedSkills.push(skillName);
+            }
+            catch {
+                // skip
+            }
+        }
+        try {
+            await promises_1.default.rm(node_path_1.default.join(target.root, exports.MANIFEST_FILENAME), { force: true });
+        }
+        catch {
+            // ok
+        }
+        results.push({ target: target.label, root: target.root, removedSkills });
+    }
+    return results;
+}

package/dist/lib/tool-runner.d.ts

@@ -0,0 +1,19 @@
+import { formatExamples } from './utils/format';
+import type { ToolContext, ToolDefinition } from './types';
+export declare function getToolCommand(name: string): ToolDefinition | null;
+export declare function listToolCommands(): ToolDefinition[];
+export declare function resolveToolCommand(name: string, sourceRoot: string): (ToolDefinition & {
+    scriptPath?: string;
+}) | null;
+export declare function formatToolList(): string;
+declare function buildToolOverview(name: string): string | null;
+declare function buildToolExamples(name: string): string;
+export declare function buildToolDiscoveryHelp(): string;
+declare function isTopLevelToolHelpRequest(toolArgs: string[]): boolean;
+declare function captureCommandOutput(tool: ToolDefinition, toolArgs: string[], context?: ToolContext): Promise<{
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}>;
+export declare function runTool(toolName: string, toolArgs: string[], context?: ToolContext): Promise<number>;
+export { formatExamples, buildToolOverview, buildToolExamples, isTopLevelToolHelpRequest, captureCommandOutput };