@almyty/skills 1.0.0

package/dist/__tests__/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/client.test.js

@@ -0,0 +1,145 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { parseRef } from '../client.js';
+import { generateMetaSkill } from '../meta-skill.js';
+import { loadConfig } from '../config.js';
+// ---------------------------------------------------------------------------
+// parseRef()
+// ---------------------------------------------------------------------------
+describe('parseRef', () => {
+    it('parses @org/gateway as a gateway ref', () => {
+        const result = parseRef('@org/gateway');
+        expect(result).toEqual({
+            type: 'gateway',
+            orgSlug: 'org',
+            gatewaySlug: 'gateway',
+            raw: '@org/gateway',
+        });
+    });
+    it('parses @org/gateway/skill as a skill ref', () => {
+        const result = parseRef('@org/gateway/skill');
+        expect(result).toEqual({
+            type: 'skill',
+            orgSlug: 'org',
+            gatewaySlug: 'gateway',
+            skillName: 'skill',
+            raw: '@org/gateway/skill',
+        });
+    });
+    it('parses a UUID string as a uuid ref', () => {
+        const uuid = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
+        const result = parseRef(uuid);
+        expect(result).toEqual({
+            type: 'uuid',
+            uuid,
+            raw: uuid,
+        });
+    });
+    it('parses uppercase UUID correctly', () => {
+        const uuid = 'A1B2C3D4-E5F6-7890-ABCD-EF1234567890';
+        const result = parseRef(uuid);
+        expect(result.type).toBe('uuid');
+        expect(result.uuid).toBe(uuid);
+    });
+    it('returns search for a random string', () => {
+        const result = parseRef('some-random-query');
+        expect(result).toEqual({
+            type: 'search',
+            raw: 'some-random-query',
+        });
+    });
+    it('returns search for an empty string', () => {
+        const result = parseRef('');
+        expect(result).toEqual({
+            type: 'search',
+            raw: '',
+        });
+    });
+    it('returns search for @ with only one segment', () => {
+        const result = parseRef('@org');
+        expect(result).toEqual({
+            type: 'search',
+            raw: '@org',
+        });
+    });
+    it('returns search for @ with more than three segments', () => {
+        const result = parseRef('@org/gw/skill/extra');
+        expect(result).toEqual({
+            type: 'search',
+            raw: '@org/gw/skill/extra',
+        });
+    });
+});
+// ---------------------------------------------------------------------------
+// generateMetaSkill()
+// ---------------------------------------------------------------------------
+describe('generateMetaSkill', () => {
+    it('returns a SkillFile with name "skills" and fileName "almyty-skills"', () => {
+        const skill = generateMetaSkill();
+        expect(skill.name).toBe('skills');
+        expect(skill.fileName).toBe('almyty-skills');
+    });
+    it('content includes npx @almyty/skills commands', () => {
+        const { content } = generateMetaSkill();
+        expect(content).toContain('npx @almyty/skills');
+    });
+    it('content references daemon command', () => {
+        const { content } = generateMetaSkill();
+        expect(content).toContain('daemon');
+    });
+    it('content references search command', () => {
+        const { content } = generateMetaSkill();
+        expect(content).toContain('search');
+    });
+    it('content references install command', () => {
+        const { content } = generateMetaSkill();
+        expect(content).toContain('install');
+    });
+    it('content references run command', () => {
+        const { content } = generateMetaSkill();
+        expect(content).toContain('run');
+    });
+    it('content includes SKILL.md front-matter', () => {
+        const { content } = generateMetaSkill();
+        expect(content).toContain('---');
+        expect(content).toContain('name: almyty-skills');
+        expect(content).toContain('description:');
+    });
+});
+// ---------------------------------------------------------------------------
+// loadConfig()
+// ---------------------------------------------------------------------------
+describe('loadConfig', () => {
+    const originalEnv = process.env;
+    beforeEach(() => {
+        // Reset env between tests
+        process.env = { ...originalEnv };
+        delete process.env.APIFAI_SKILLS_DIR;
+    });
+    afterEach(() => {
+        process.env = originalEnv;
+        vi.restoreAllMocks();
+    });
+    it('returns empty config when no .almytyrc exists and no env var', () => {
+        // Use a temp directory that definitely has no .almytyrc
+        const config = loadConfig('/tmp/nonexistent-dir-' + Date.now());
+        expect(config).toEqual({});
+    });
+    it('uses APIFAI_SKILLS_DIR env var when set', () => {
+        process.env.APIFAI_SKILLS_DIR = '/custom/skills/dir';
+        const config = loadConfig();
+        expect(config).toEqual({ skillsDir: '/custom/skills/dir' });
+    });
+    it('env var takes precedence over .almytyrc files', () => {
+        process.env.APIFAI_SKILLS_DIR = '/env/override';
+        // Even if we pass a projectDir, env should take priority
+        const config = loadConfig('/some/project');
+        expect(config.skillsDir).toBe('/env/override');
+    });
+    it('returns empty config for a directory with no rc file and no home rc', () => {
+        // Use a deeply nested temp path that certainly has no .almytyrc anywhere
+        // and also won't match ~/.almytyrc (already handled by the missing file)
+        const fakePath = `/tmp/almyty-test-${Date.now()}/deeply/nested/project`;
+        const config = loadConfig(fakePath);
+        expect(config).toEqual({});
+    });
+});

package/dist/agents.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Agent directory detection and mapping.
+ *
+ * Detects which AI coding agents are present in the current project
+ * by looking for their config directories. Skills are installed into
+ * agent-specific skill directories.
+ *
+ * Agent list aligned with https://github.com/vercel-labs/skills
+ */
+export interface AgentTarget {
+    name: string;
+    configDir: string;
+    skillsDir: string;
+}
+/**
+ * Detect which AI agents are configured in the given project directory.
+ */
+export declare function detectAgents(projectDir: string): AgentTarget[];
+/**
+ * If no agents are detected, return defaults:
+ * - .claude/skills/ (Claude Code native)
+ * - .agents/skills/ (cross-client standard per agentskills.io spec)
+ */
+export declare function getDefaultTargets(projectDir: string): AgentTarget[];
+/**
+ * Get ALL detected targets plus cross-client .agents/skills/.
+ * Used by watch/daemon mode to ensure maximum coverage.
+ */
+export declare function getAllTargets(projectDir: string): AgentTarget[];
+/**
+ * Filter agents by name (case-insensitive partial match).
+ */
+export declare function filterAgents(agents: AgentTarget[], filter: string[]): AgentTarget[];
+/**
+ * Ensure a skills directory exists.
+ */
+export declare function ensureSkillsDir(skillsDir: string): void;

package/dist/agents.js

@@ -0,0 +1,123 @@
+/**
+ * Agent directory detection and mapping.
+ *
+ * Detects which AI coding agents are present in the current project
+ * by looking for their config directories. Skills are installed into
+ * agent-specific skill directories.
+ *
+ * Agent list aligned with https://github.com/vercel-labs/skills
+ */
+import { existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+/**
+ * Known agent configurations (30+ agents).
+ * Aligned with Vercel's skills CLI.
+ * See: https://github.com/vercel-labs/skills/blob/main/src/agents.ts
+ */
+const AGENT_CONFIGS = [
+    // --- Major agents ---
+    { name: 'Claude Code', detectDirs: ['.claude'], skillsDir: '.claude/skills' },
+    { name: 'Cursor', detectDirs: ['.cursor', '.cursorrc'], skillsDir: '.agents/skills' },
+    { name: 'GitHub Copilot', detectDirs: ['.github/copilot'], skillsDir: '.agents/skills' },
+    { name: 'Windsurf', detectDirs: ['.windsurf'], skillsDir: '.windsurf/skills' },
+    { name: 'Codex', detectDirs: ['.codex'], skillsDir: '.agents/skills' },
+    // --- Additional agents ---
+    { name: 'Amp', detectDirs: ['.amp'], skillsDir: '.agents/skills' },
+    { name: 'Augment', detectDirs: ['.augment'], skillsDir: '.augment/skills' },
+    { name: 'Cline', detectDirs: ['.cline'], skillsDir: '.agents/skills' },
+    { name: 'CodeBuddy', detectDirs: ['.codebuddy'], skillsDir: '.codebuddy/skills' },
+    { name: 'Command Code', detectDirs: ['.commandcode'], skillsDir: '.commandcode/skills' },
+    { name: 'Continue', detectDirs: ['.continue'], skillsDir: '.continue/skills' },
+    { name: 'Cortex', detectDirs: ['.cortex'], skillsDir: '.cortex/skills' },
+    { name: 'Droid (Factory)', detectDirs: ['.factory'], skillsDir: '.factory/skills' },
+    { name: 'Gemini CLI', detectDirs: ['.gemini'], skillsDir: '.agents/skills' },
+    { name: 'Goose', detectDirs: ['.goose'], skillsDir: '.goose/skills' },
+    { name: 'Junie', detectDirs: ['.junie'], skillsDir: '.junie/skills' },
+    { name: 'Kilo Code', detectDirs: ['.kilocode'], skillsDir: '.kilocode/skills' },
+    { name: 'Kiro CLI', detectDirs: ['.kiro'], skillsDir: '.kiro/skills' },
+    { name: 'Kode', detectDirs: ['.kode'], skillsDir: '.kode/skills' },
+    { name: 'MCPJam', detectDirs: ['.mcpjam'], skillsDir: '.mcpjam/skills' },
+    { name: 'Mistral Vibe', detectDirs: ['.vibe'], skillsDir: '.vibe/skills' },
+    { name: 'Mux', detectDirs: ['.mux'], skillsDir: '.mux/skills' },
+    { name: 'OpenCode', detectDirs: ['.opencode'], skillsDir: '.agents/skills' },
+    { name: 'OpenHands', detectDirs: ['.openhands'], skillsDir: '.openhands/skills' },
+    { name: 'Pi', detectDirs: ['.pi'], skillsDir: '.pi/skills' },
+    { name: 'Qoder', detectDirs: ['.qoder'], skillsDir: '.qoder/skills' },
+    { name: 'Qwen Code', detectDirs: ['.qwen'], skillsDir: '.qwen/skills' },
+    { name: 'Roo Code', detectDirs: ['.roo'], skillsDir: '.roo/skills' },
+    { name: 'Trae', detectDirs: ['.trae'], skillsDir: '.trae/skills' },
+    { name: 'Zencoder', detectDirs: ['.zencoder'], skillsDir: '.zencoder/skills' },
+];
+/**
+ * Detect which AI agents are configured in the given project directory.
+ */
+export function detectAgents(projectDir) {
+    const agents = [];
+    const seenSkillsDirs = new Set();
+    for (const config of AGENT_CONFIGS) {
+        const detected = config.detectDirs.some(dir => existsSync(join(projectDir, dir)));
+        if (detected) {
+            const fullSkillsDir = join(projectDir, config.skillsDir);
+            // Avoid duplicates when multiple agents share the same skills dir
+            if (!seenSkillsDirs.has(fullSkillsDir)) {
+                seenSkillsDirs.add(fullSkillsDir);
+                agents.push({
+                    name: config.name,
+                    configDir: config.detectDirs[0],
+                    skillsDir: fullSkillsDir,
+                });
+            }
+        }
+    }
+    return agents;
+}
+/**
+ * If no agents are detected, return defaults:
+ * - .claude/skills/ (Claude Code native)
+ * - .agents/skills/ (cross-client standard per agentskills.io spec)
+ */
+export function getDefaultTargets(projectDir) {
+    return [
+        {
+            name: 'Claude Code',
+            configDir: '.claude',
+            skillsDir: join(projectDir, '.claude/skills'),
+        },
+        {
+            name: 'Universal (.agents/skills)',
+            configDir: '.agents',
+            skillsDir: join(projectDir, '.agents/skills'),
+        },
+    ];
+}
+/**
+ * Get ALL detected targets plus cross-client .agents/skills/.
+ * Used by watch/daemon mode to ensure maximum coverage.
+ */
+export function getAllTargets(projectDir) {
+    const detected = detectAgents(projectDir);
+    const seenDirs = new Set(detected.map(a => a.skillsDir));
+    // Always include cross-client .agents/skills/ if not already covered
+    const universalDir = join(projectDir, '.agents/skills');
+    if (!seenDirs.has(universalDir)) {
+        detected.push({
+            name: 'Universal (.agents/skills)',
+            configDir: '.agents',
+            skillsDir: universalDir,
+        });
+    }
+    return detected;
+}
+/**
+ * Filter agents by name (case-insensitive partial match).
+ */
+export function filterAgents(agents, filter) {
+    const normalized = filter.map(f => f.toLowerCase());
+    return agents.filter(a => normalized.some(f => a.name.toLowerCase().includes(f)));
+}
+/**
+ * Ensure a skills directory exists.
+ */
+export function ensureSkillsDir(skillsDir) {
+    mkdirSync(skillsDir, { recursive: true });
+}

package/dist/auth.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Authentication helpers for the almyty skills CLI.
+ *
+ * Shares credentials with @almyty/mcp-server via ~/.almyty/credentials.json.
+ *
+ * Supports:
+ * 1. Environment variable (APIFAI_TOKEN) — for CI/scripts
+ * 2. Stored credentials (~/.almyty/credentials.json) — for interactive use
+ * 3. Interactive login (npx @almyty/skills login) — stores credentials
+ */
+interface StoredCredentials {
+    url: string;
+    token: string;
+    email?: string;
+    expiresAt?: string;
+}
+/**
+ * Load stored credentials from ~/.almyty/credentials.json
+ */
+export declare function loadCredentials(): StoredCredentials | null;
+/**
+ * Save credentials to ~/.almyty/credentials.json
+ */
+export declare function saveCredentials(creds: StoredCredentials): void;
+/**
+ * Remove stored credentials
+ */
+export declare function logout(): void;
+/**
+ * Resolve token: env var > stored credentials
+ */
+export declare function resolveAuth(): {
+    url: string;
+    token: string;
+};
+/**
+ * Interactive login: prompts for email/password, authenticates against
+ * the almyty backend, and stores the JWT token.
+ */
+export declare function login(baseUrl: string): Promise<void>;
+export {};

package/dist/auth.js

@@ -0,0 +1,117 @@
+/**
+ * Authentication helpers for the almyty skills CLI.
+ *
+ * Shares credentials with @almyty/mcp-server via ~/.almyty/credentials.json.
+ *
+ * Supports:
+ * 1. Environment variable (APIFAI_TOKEN) — for CI/scripts
+ * 2. Stored credentials (~/.almyty/credentials.json) — for interactive use
+ * 3. Interactive login (npx @almyty/skills login) — stores credentials
+ */
+import { readFileSync, writeFileSync, mkdirSync, unlinkSync, existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { createInterface } from 'readline';
+const CREDENTIALS_DIR = join(homedir(), '.almyty');
+const CREDENTIALS_FILE = join(CREDENTIALS_DIR, 'credentials.json');
+/**
+ * Load stored credentials from ~/.almyty/credentials.json
+ */
+export function loadCredentials() {
+    try {
+        if (!existsSync(CREDENTIALS_FILE))
+            return null;
+        const data = readFileSync(CREDENTIALS_FILE, 'utf-8');
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Save credentials to ~/.almyty/credentials.json
+ */
+export function saveCredentials(creds) {
+    mkdirSync(CREDENTIALS_DIR, { recursive: true });
+    writeFileSync(CREDENTIALS_FILE, JSON.stringify(creds, null, 2), { mode: 0o600 });
+}
+/**
+ * Remove stored credentials
+ */
+export function logout() {
+    try {
+        if (existsSync(CREDENTIALS_FILE)) {
+            unlinkSync(CREDENTIALS_FILE);
+            console.log('Logged out. Credentials removed.');
+        }
+        else {
+            console.log('No stored credentials found.');
+        }
+    }
+    catch {
+        console.error('Failed to remove credentials.');
+    }
+}
+/**
+ * Resolve token: env var > stored credentials
+ */
+export function resolveAuth() {
+    const envToken = process.env.APIFAI_TOKEN;
+    const envUrl = process.env.APIFAI_URL || 'https://api.almyty.com';
+    if (envToken) {
+        return { url: envUrl, token: envToken };
+    }
+    const creds = loadCredentials();
+    if (creds?.token) {
+        return { url: creds.url, token: creds.token };
+    }
+    console.error('Not authenticated. Run one of:');
+    console.error('  npx @almyty/skills login');
+    console.error('  export APIFAI_TOKEN=<your-token>');
+    process.exit(1);
+}
+/**
+ * Interactive login: prompts for email/password, authenticates against
+ * the almyty backend, and stores the JWT token.
+ */
+export async function login(baseUrl) {
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    const ask = (question) => new Promise((resolve) => rl.question(question, resolve));
+    try {
+        console.error(`Logging in to ${baseUrl}...\n`);
+        const email = await ask('Email: ');
+        const password = await ask('Password: ');
+        console.error('\nAuthenticating...');
+        const response = await fetch(`${baseUrl}/api/auth/login`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ email, password }),
+        });
+        if (!response.ok) {
+            const errBody = await response.json().catch(() => ({ message: 'Authentication failed' }));
+            console.error(`Error: ${errBody.message || 'Authentication failed'}`);
+            process.exit(1);
+        }
+        const data = await response.json();
+        const token = data.accessToken || data.token;
+        if (!token) {
+            console.error('Error: No token received from server');
+            process.exit(1);
+        }
+        saveCredentials({
+            url: baseUrl,
+            token,
+            email,
+        });
+        console.error(`\n✓ Logged in as ${email}`);
+        console.error(`  Credentials saved to ${CREDENTIALS_FILE}`);
+        console.error('\nYou can now install skills:');
+        console.error('  npx @almyty/skills install --gateway <id>');
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,34 @@
+export interface SkillFile {
+    name: string;
+    fileName: string;
+    content: string;
+}
+export interface GatewayInfo {
+    id: string;
+    name: string;
+    type: string;
+}
+export interface ParsedRef {
+    type: 'gateway' | 'skill' | 'search' | 'uuid';
+    orgSlug?: string;
+    gatewaySlug?: string;
+    skillName?: string;
+    uuid?: string;
+    raw: string;
+}
+export declare function parseRef(ref: string): ParsedRef;
+export declare class AlmytyClient {
+    private baseUrl;
+    private token;
+    constructor(baseUrl: string, token: string);
+    private request;
+    private post;
+    resolveGateway(orgSlug: string, gatewaySlug: string): Promise<GatewayInfo>;
+    fetchSkills(gatewayIdOrRef: string): Promise<SkillFile[]>;
+    fetchGateway(gatewayIdOrRef: string): Promise<GatewayInfo>;
+    listGateways(): Promise<GatewayInfo[]>;
+    searchSkills(query: string): Promise<any[]>;
+    fetchAllSkills(): Promise<SkillFile[]>;
+    executeSkill(gatewayId: string, toolId: string, parameters: Record<string, any>): Promise<any>;
+    private resolveRef;
+}

package/dist/client.js

@@ -0,0 +1,128 @@
+export function parseRef(ref) {
+    if (!ref)
+        return { type: 'search', raw: ref };
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    if (uuidRegex.test(ref))
+        return { type: 'uuid', uuid: ref, raw: ref };
+    if (ref.startsWith('@')) {
+        const parts = ref.slice(1).split('/');
+        if (parts.length === 3) {
+            return { type: 'skill', orgSlug: parts[0], gatewaySlug: parts[1], skillName: parts[2], raw: ref };
+        }
+        if (parts.length === 2) {
+            return { type: 'gateway', orgSlug: parts[0], gatewaySlug: parts[1], raw: ref };
+        }
+    }
+    return { type: 'search', raw: ref };
+}
+export class AlmytyClient {
+    baseUrl;
+    token;
+    constructor(baseUrl, token) {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.token = token;
+    }
+    async request(path) {
+        const url = `${this.baseUrl}/api${path}`;
+        const response = await fetch(url, {
+            headers: {
+                'Authorization': `Bearer ${this.token}`,
+                'Content-Type': 'application/json',
+            },
+        });
+        if (!response.ok) {
+            if (response.status === 401) {
+                throw new Error('Authentication failed. Run: npx @almyty/skills login');
+            }
+            const text = await response.text();
+            throw new Error(`API error (${response.status}): ${text}`);
+        }
+        return response.json();
+    }
+    async post(path, body) {
+        const url = `${this.baseUrl}/api${path}`;
+        const resp = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this.token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+        if (!resp.ok) {
+            const text = await resp.text();
+            throw new Error(`API error ${resp.status}: ${text}`);
+        }
+        return resp.json();
+    }
+    async resolveGateway(orgSlug, gatewaySlug) {
+        const data = await this.request(`/gateways/resolve/${orgSlug}/${gatewaySlug}`);
+        const gw = data?.data || data;
+        return {
+            id: gw.id,
+            name: gw.name,
+            type: gw.type,
+        };
+    }
+    async fetchSkills(gatewayIdOrRef) {
+        const gatewayId = await this.resolveRef(gatewayIdOrRef);
+        const data = await this.request(`/gateways/${gatewayId}/skills/individual`);
+        return data?.data?.skills || [];
+    }
+    async fetchGateway(gatewayIdOrRef) {
+        if (gatewayIdOrRef.startsWith('@')) {
+            const parsed = parseRef(gatewayIdOrRef);
+            if (parsed.orgSlug && parsed.gatewaySlug) {
+                return this.resolveGateway(parsed.orgSlug, parsed.gatewaySlug);
+            }
+        }
+        const data = await this.request(`/gateways/${gatewayIdOrRef}`);
+        const gw = data?.data || data;
+        return {
+            id: gw.id,
+            name: gw.name,
+            type: gw.type,
+        };
+    }
+    async listGateways() {
+        const data = await this.request('/gateways');
+        const gateways = data?.data?.data?.gateways || data?.data?.data || data?.data || [];
+        return gateways.map((gw) => ({
+            id: gw.id,
+            name: gw.name,
+            type: gw.type,
+        }));
+    }
+    async searchSkills(query) {
+        const resp = await this.request(`/gateways/skills/search?q=${encodeURIComponent(query)}`);
+        return resp?.data || [];
+    }
+    async fetchAllSkills() {
+        const resp = await this.request('/gateways/all-skills');
+        const gateways = resp?.data || [];
+        const skills = [];
+        for (const gw of gateways) {
+            for (const skill of gw.skills || []) {
+                skill.gateway = gw.gatewayName;
+                skill.gatewayId = gw.gatewayId;
+                skill.orgSlug = gw.orgSlug;
+                skill.gatewaySlug = gw.gatewaySlug;
+                skills.push(skill);
+            }
+        }
+        return skills;
+    }
+    async executeSkill(gatewayId, toolId, parameters) {
+        return this.post(`/gateways/${gatewayId}/skills/${toolId}/execute`, { parameters });
+    }
+    async resolveRef(ref) {
+        if (ref.startsWith('@')) {
+            const parsed = parseRef(ref);
+            if (parsed.orgSlug && parsed.gatewaySlug) {
+                const gw = await this.resolveGateway(parsed.orgSlug, parsed.gatewaySlug);
+                return gw.id;
+            }
+        }
+        return ref;
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+import { type AgentTarget } from './agents.js';
+export interface AlmytyConfig {
+    skillsDir?: string;
+    agents?: string[];
+    url?: string;
+    interval?: number;
+}
+export declare function loadConfig(projectDir?: string): AlmytyConfig;
+export declare function resolveTargets(projectDir: string, config: AlmytyConfig): AgentTarget[];