crewly 1.20.131 → 1.20.133

package/dist/cli/backend/src/services/marketplace/marketplace.service.js

@@ -0,0 +1,392 @@
+/**
+ * Marketplace Service
+ *
+ * Handles fetching the marketplace registry from the Crewly webapp API,
+ * managing the local installed-items manifest, and enriching items
+ * with install status information.
+ *
+ * @module services/marketplace/marketplace.service
+ */
+import { homedir } from 'os';
+import path from 'path';
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { MARKETPLACE_CONSTANTS } from '../../constants.js';
+const CREWLY_HOME = path.join(homedir(), '.crewly');
+const MARKETPLACE_DIR = path.join(CREWLY_HOME, MARKETPLACE_CONSTANTS.DIR_NAME);
+const MANIFEST_PATH = path.join(MARKETPLACE_DIR, MARKETPLACE_CONSTANTS.MANIFEST_FILE);
+const LOCAL_REGISTRY_PATH = path.join(MARKETPLACE_DIR, MARKETPLACE_CONSTANTS.LOCAL_REGISTRY_FILE);
+/** Pattern for valid marketplace item IDs: lowercase alphanumeric with hyphens */
+const VALID_ITEM_ID_PATTERN = /^[a-z0-9][a-z0-9\-]*$/;
+let cachedRegistry = null;
+let cacheTimestamp = 0;
+let fetchInFlight = null;
+/**
+ * Validates that a marketplace item ID is safe (no path traversal).
+ *
+ * @param id - The item ID to validate
+ * @returns True if the ID matches the allowed pattern
+ */
+function isValidItemId(id) {
+    return VALID_ITEM_ID_PATTERN.test(id);
+}
+/**
+ * Fetches the marketplace registry from the Crewly webapp API.
+ * Uses in-memory caching with a 1-hour TTL. Concurrent callers share
+ * the same in-flight request to avoid duplicate network fetches.
+ *
+ * On network failure, falls back to the previously cached registry
+ * if one is available. Throws only when no cached data exists.
+ *
+ * @param forceRefresh - If true, bypasses the cache and fetches fresh data
+ * @returns The marketplace registry containing all available items
+ * @throws Error if the fetch fails and no cached registry is available
+ */
+export async function fetchRegistry(forceRefresh = false) {
+    const now = Date.now();
+    if (!forceRefresh && cachedRegistry && now - cacheTimestamp < MARKETPLACE_CONSTANTS.CACHE_TTL) {
+        return cachedRegistry;
+    }
+    // When forceRefresh is true, wait for any in-flight request to complete
+    // before starting a new fetch to avoid returning stale data
+    if (forceRefresh && fetchInFlight) {
+        await fetchInFlight.catch(() => { });
+        // Fall through to start a new fetch
+    }
+    // Deduplicate concurrent requests
+    if (fetchInFlight) {
+        return fetchInFlight;
+    }
+    fetchInFlight = doFetchRegistry(now).finally(() => {
+        fetchInFlight = null;
+    });
+    return fetchInFlight;
+}
+/**
+ * Internal fetch implementation. Separated to enable in-flight deduplication.
+ *
+ * Fetches from two sources in parallel:
+ * 1. Public registry -- GitHub raw content (config/skills/registry.json in crewly repo)
+ * 2. Premium registry -- crewlyai.com/api/registry/skills (private/paid skills)
+ *
+ * Results are merged with local registry items (locally published skills).
+ *
+ * When both remote sources fail and no local items exist, the empty registry
+ * is returned but NOT cached so the next call will retry immediately.
+ */
+async function doFetchRegistry(now) {
+    // Fetch public and premium registries in parallel
+    const [publicResult, premiumResult] = await Promise.allSettled([
+        fetchPublicRegistry(),
+        fetchPremiumRegistry(),
+    ]);
+    const publicItems = publicResult.status === 'fulfilled' ? publicResult.value : [];
+    const premiumItems = premiumResult.status === 'fulfilled' ? premiumResult.value : [];
+    // If both failed and we have a cache, return cache
+    if (publicItems.length === 0 && premiumItems.length === 0 && cachedRegistry) {
+        return cachedRegistry;
+    }
+    // Merge: public + premium (premium overwrites by ID if conflict)
+    const mergedMap = new Map();
+    for (const item of publicItems) {
+        mergedMap.set(item.id, { ...item, registrySource: 'public' });
+    }
+    for (const item of premiumItems) {
+        // Keep the public entry a premium one replaces: premium archives can be
+        // missing from the CDN while the public copy of the same skill installs.
+        const replaced = mergedMap.get(item.id);
+        const sameSource = replaced && (replaced.assets.archive ?? replaced.assets.model) === (item.assets.archive ?? item.assets.model);
+        mergedMap.set(item.id, {
+            ...item,
+            registrySource: 'premium',
+            ...(replaced && !sameSource ? { fallback: replaced } : {}),
+        });
+    }
+    // Merge locally published skills
+    const localItems = await loadLocalRegistry();
+    for (const item of localItems) {
+        if (!mergedMap.has(item.id)) {
+            mergedMap.set(item.id, { ...item, registrySource: 'local' });
+        }
+    }
+    const registry = {
+        schemaVersion: MARKETPLACE_CONSTANTS.SCHEMA_VERSION,
+        lastUpdated: new Date().toISOString(),
+        cdnBaseUrl: MARKETPLACE_CONSTANTS.PUBLIC_CDN_BASE,
+        items: Array.from(mergedMap.values()),
+    };
+    // Only cache non-empty registries so that next call retries on total failure
+    if (mergedMap.size > 0) {
+        cachedRegistry = registry;
+        cacheTimestamp = now;
+    }
+    return registry;
+}
+/**
+ * Fetches items from the public registry (GitHub raw content).
+ *
+ * @returns Array of public marketplace items, empty on failure
+ */
+async function fetchPublicRegistry() {
+    try {
+        const res = await fetch(MARKETPLACE_CONSTANTS.PUBLIC_REGISTRY_URL, {
+            signal: AbortSignal.timeout(MARKETPLACE_CONSTANTS.REGISTRY_FETCH_TIMEOUT),
+        });
+        if (res.ok) {
+            const data = (await res.json());
+            return data.items || [];
+        }
+    }
+    catch {
+        // Public registry unavailable -- continue with empty
+    }
+    return [];
+}
+/**
+ * Fetches items from the premium registry (crewlyai.com).
+ *
+ * @returns Array of premium marketplace items with premium flag, empty on failure
+ */
+async function fetchPremiumRegistry() {
+    try {
+        const url = `${MARKETPLACE_CONSTANTS.PREMIUM_BASE_URL}${MARKETPLACE_CONSTANTS.PREMIUM_REGISTRY_ENDPOINT}`;
+        const res = await fetch(url, {
+            signal: AbortSignal.timeout(MARKETPLACE_CONSTANTS.REGISTRY_FETCH_TIMEOUT),
+        });
+        if (res.ok) {
+            const data = (await res.json());
+            return (data.items || []).map((item) => ({
+                ...item,
+                metadata: { ...item.metadata, premium: true },
+            }));
+        }
+    }
+    catch {
+        // Premium registry unavailable -- continue without premium skills
+    }
+    return [];
+}
+/**
+ * Loads locally published marketplace items from the local registry file.
+ *
+ * These are skills that were submitted and approved through the local
+ * submission workflow.
+ *
+ * @returns Array of locally published marketplace items
+ */
+async function loadLocalRegistry() {
+    try {
+        const data = await readFile(LOCAL_REGISTRY_PATH, 'utf-8');
+        const registry = JSON.parse(data);
+        if (!Array.isArray(registry.items)) {
+            return [];
+        }
+        return registry.items;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Loads the locally installed items manifest from disk.
+ *
+ * Returns an empty manifest (schemaVersion 1, no items) if the
+ * manifest file does not exist or cannot be parsed.
+ *
+ * @returns The installed items manifest
+ */
+export async function loadManifest() {
+    try {
+        const data = await readFile(MANIFEST_PATH, 'utf-8');
+        return JSON.parse(data);
+    }
+    catch {
+        return { schemaVersion: 1, items: [] };
+    }
+}
+/**
+ * Saves the installed items manifest to disk.
+ *
+ * Creates the marketplace directory if it does not exist.
+ *
+ * @param manifest - The manifest to persist
+ */
+export async function saveManifest(manifest) {
+    await mkdir(MARKETPLACE_DIR, { recursive: true });
+    await writeFile(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + '\n');
+}
+/**
+ * Returns a single marketplace item by ID, enriched with install status.
+ *
+ * @param id - The marketplace item ID to look up
+ * @returns The item with install status, or null if not found in the registry
+ */
+export async function getItem(id) {
+    const registry = await fetchRegistry();
+    const item = registry.items.find((i) => i.id === id);
+    if (!item)
+        return null;
+    const manifest = await loadManifest();
+    const installedMap = new Map(manifest.items.map((r) => [r.id, r]));
+    return enrichWithStatusFromMap(item, installedMap);
+}
+/**
+ * Lists marketplace items with optional filtering, enriched with install status.
+ *
+ * Supports filtering by type, category, and free-text search (matches name,
+ * description, and tags). Results are sorted by the specified sort option,
+ * defaulting to most popular (highest downloads).
+ *
+ * @param filter - Optional filter and sort criteria
+ * @returns Filtered and sorted list of items with install status
+ */
+export async function listItems(filter) {
+    const registry = await fetchRegistry();
+    // Shallow copy to avoid mutating the cached registry's items array via .sort()
+    let items = [...registry.items];
+    if (filter?.type) {
+        items = items.filter((i) => i.type === filter.type);
+    }
+    if (filter?.category) {
+        items = items.filter((i) => i.category === filter.category);
+    }
+    if (filter?.search) {
+        const q = filter.search.toLowerCase();
+        items = items.filter((i) => i.name.toLowerCase().includes(q) ||
+            i.description.toLowerCase().includes(q) ||
+            i.tags.some((t) => t.toLowerCase().includes(q)));
+    }
+    switch (filter?.sortBy) {
+        case 'popular':
+            items.sort((a, b) => b.downloads - a.downloads);
+            break;
+        case 'rating':
+            items.sort((a, b) => b.rating - a.rating);
+            break;
+        case 'newest':
+            items.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+            break;
+        default:
+            items.sort((a, b) => b.downloads - a.downloads);
+    }
+    const manifest = await loadManifest();
+    // Use Map for O(n+m) enrichment instead of O(n*m) linear scan per item
+    const installedMap = new Map(manifest.items.map((r) => [r.id, r]));
+    return items.map((i) => enrichWithStatusFromMap(i, installedMap));
+}
+/**
+ * Returns marketplace items that have updates available.
+ *
+ * An item has an update available when the installed version differs
+ * from the latest version in the registry.
+ *
+ * @returns Items with installStatus 'update_available'
+ */
+export async function getUpdatableItems() {
+    const all = await listItems();
+    return all.filter((i) => i.installStatus === 'update_available');
+}
+/**
+ * Returns locally installed items from the manifest.
+ *
+ * @returns Array of installed item records
+ */
+export async function getInstalledItems() {
+    const manifest = await loadManifest();
+    return manifest.items;
+}
+/**
+ * Searches marketplace items by query string.
+ *
+ * Convenience wrapper around listItems with a search filter.
+ *
+ * @param query - Free-text search query
+ * @returns Matching items with install status
+ */
+export async function searchItems(query) {
+    return listItems({ search: query });
+}
+/**
+ * Enriches a marketplace item with its local install status using a pre-built Map.
+ *
+ * @param item - The marketplace item from the registry
+ * @param installedMap - Map of installed item ID to record for O(1) lookup
+ * @returns The item enriched with installStatus and optional installedVersion
+ */
+function enrichWithStatusFromMap(item, installedMap) {
+    const installed = installedMap.get(item.id);
+    if (!installed) {
+        return { ...item, installStatus: 'not_installed' };
+    }
+    if (installed.version !== item.version) {
+        return { ...item, installStatus: 'update_available', installedVersion: installed.version };
+    }
+    return { ...item, installStatus: 'installed', installedVersion: installed.version };
+}
+/**
+ * Returns the local install path for a marketplace item.
+ *
+ * Maps item types to directory names:
+ * - 'skill' -> 'skills'
+ * - 'model' -> 'models'
+ * - 'role'  -> 'roles'
+ *
+ * @param type - The marketplace item type
+ * @param id - The marketplace item ID
+ * @returns Absolute path to the item's install directory
+ * @throws Error if the id contains path traversal characters
+ */
+const TYPE_DIR_MAP = {
+    skill: 'skills',
+    model: 'models',
+    role: 'roles',
+    mcp_tool: 'mcp-tools',
+};
+export function getInstallPath(type, id) {
+    if (!isValidItemId(id)) {
+        throw new Error(`Invalid marketplace item ID "${id}": must match ${VALID_ITEM_ID_PATTERN}`);
+    }
+    const typeDir = TYPE_DIR_MAP[type];
+    return path.join(MARKETPLACE_DIR, typeDir, id);
+}
+/**
+ * Retrieves the README.md content for a marketplace item.
+ *
+ * Looks for a README.md file in the item's install directory. Tries multiple
+ * filenames (README.md, readme.md, SKILL.md) for flexibility.
+ *
+ * @param id - The marketplace item ID
+ * @returns The README content as a string, or null if not found
+ * @throws Error if the item ID is invalid (path traversal protection)
+ */
+export async function getItemReadme(id) {
+    if (!isValidItemId(id)) {
+        throw new Error(`Invalid marketplace item ID "${id}": must match ${VALID_ITEM_ID_PATTERN}`);
+    }
+    // Try skill type first (most common), then other types
+    const types = ['skill', 'role', 'mcp_tool', 'model'];
+    const readmeNames = ['README.md', 'readme.md', 'SKILL.md'];
+    for (const type of types) {
+        const installDir = getInstallPath(type, id);
+        for (const name of readmeNames) {
+            try {
+                const content = await readFile(path.join(installDir, name), 'utf-8');
+                return content;
+            }
+            catch {
+                // File doesn't exist for this type/name combo — try next
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Resets the in-memory registry cache.
+ *
+ * Used primarily for testing to ensure a clean state between test runs.
+ */
+export function resetRegistryCache() {
+    cachedRegistry = null;
+    cacheTimestamp = 0;
+    fetchInFlight = null;
+}
+//# sourceMappingURL=marketplace.service.js.map

package/dist/cli/backend/src/services/marketplace/marketplace.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"marketplace.service.js","sourceRoot":"","sources":["../../../../../../backend/src/services/marketplace/marketplace.service.ts"],"names":[],"mappings":"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"}

package/dist/cli/backend/src/services/skill-setup/skill-discovery.service.d.ts

@@ -0,0 +1,281 @@
+/**
+ * Skill discovery — find a skill for a capability, locally or in the marketplace.
+ *
+ * Backs `find-skill` and `install-skill` (specs/skill-auto-install.md). It
+ * merges three sources into one candidate list:
+ *
+ * 1. **Bundled** skills shipped in the npm package (`config/skills/agent/**`).
+ *    They are present on every install, so `find-skill` works for them even
+ *    when the registry has no entry or the network is down.
+ * 2. **Installed** marketplace skills (`~/.crewly/marketplace/skills/<id>`).
+ * 3. **Registry** entries (public GitHub registry + crewlyai.com), fetched
+ *    with the existing marketplace service (cached, deduplicated).
+ *
+ * ## What "official" means
+ *
+ * A skill is official — and may be installed by an agent without asking — when
+ * it is **bundled with Crewly**, or it is listed in an **official registry**
+ * (the public GitHub registry or crewlyai.com, both curated by Crewly
+ * maintainers) with `author` "Crewly Team" / "crewly" or `metadata.verified:
+ * true`. Entries from the machine-local registry (`local-registry.json`,
+ * written by local publishing) are never official, whatever author they claim.
+ * A marketplace skill installed earlier counts as official only when the
+ * registry still lists it as official.
+ *
+ * @module services/skill-setup/skill-discovery.service
+ */
+import type { MarketplaceItem, MarketplaceRegistry, InstalledItemsManifest } from '../../types/marketplace.types.js';
+import { type SkillSetupManifest } from './skill-setup-manifest.js';
+import { type SkillSetupRunner } from './skill-setup-runner.service.js';
+/** Where a candidate was found. */
+export type SkillSource = 'bundled' | 'installed' | 'registry';
+/** Setup state reported for a candidate. */
+export interface CandidateSetup {
+    /** The skill declares a setup block */
+    declared: boolean;
+    /** Minutes a first-time setup takes (quoted to the user) */
+    estimatedMinutes?: number;
+    /** Result of a check-only probe (undefined when not probed) */
+    satisfied?: boolean;
+    /** Steps that are missing (check-only probe) */
+    missing?: string[];
+}
+/** One skill that could provide a capability. */
+export interface SkillCandidate {
+    /** The id `install-skill --id` takes */
+    id: string;
+    name: string;
+    description: string;
+    tags: string[];
+    triggers: string[];
+    source: SkillSource;
+    official: boolean;
+    /** Why it is (or is not) official, in words */
+    officialReason: string;
+    author?: string;
+    version?: string;
+    /** The skill's files are on this machine */
+    installed: boolean;
+    /** Installed and its setup (if any) is satisfied — usable right now */
+    ready?: boolean;
+    /** Local skill directory */
+    skillDir?: string;
+    /** Local entry point (`<skillDir>/execute.sh`) */
+    executePath?: string;
+    /** Registry id when it differs from `id` */
+    registryId?: string;
+    setup: CandidateSetup;
+    /** Ranking score (higher is better) */
+    score: number;
+}
+/** A candidate plus the internals install-skill needs. */
+export interface ResolvedSkill extends SkillCandidate {
+    /** Parsed, validated setup manifest (local copy preferred, registry fallback) */
+    manifest?: SkillSetupManifest;
+    /** Setup block that failed validation (message) */
+    manifestError?: string;
+    /** The registry entry, when there is one */
+    registryItem?: MarketplaceItem;
+}
+/** Injectable dependencies. */
+export interface SkillDiscoveryDeps {
+    /** Root of bundled agent skills (default: `<package>/config/skills/agent`) */
+    bundledRoot?: string;
+    /** Directory of marketplace-installed skills */
+    installedRoot?: string;
+    fetchRegistry?: () => Promise<MarketplaceRegistry>;
+    loadManifest?: () => Promise<InstalledItemsManifest>;
+    runner?: SkillSetupRunner;
+}
+/**
+ * Split a query into lower-case tokens, dropping stopwords.
+ *
+ * @param text - Free text
+ * @returns Tokens (CJK runs stay whole)
+ */
+export declare function tokenize(text: string): string[];
+/**
+ * Expand tokens with synonyms (QUERY_SYNONYMS). CJK tokens also match a
+ * synonym key they contain ("语音消息" contains "语音").
+ *
+ * @param tokens - Query tokens
+ * @returns Original tokens (weight 1) and synonyms (weight 0.6), deduplicated
+ */
+export declare function expandTokens(tokens: string[]): Array<{
+    token: string;
+    weight: number;
+}>;
+/** The text fields a candidate is scored on. */
+export interface ScoredDoc {
+    id: string;
+    name: string;
+    tags: string[];
+    triggers: string[];
+    description: string;
+}
+/**
+ * Score how well a skill matches a query.
+ *
+ * Each query token (and synonym, at reduced weight) takes its best match:
+ * exact id/name 10, exact tag 6, id/name contains 5, trigger contains 3,
+ * tag overlap 3, description contains 1.5. The whole query appearing in a
+ * trigger or the description adds 4.
+ *
+ * @param query - Free-text need ("transcribe a voice message")
+ * @param doc - Candidate fields
+ * @returns Score (0 = no match)
+ */
+export declare function scoreSkill(query: string, doc: ScoredDoc): number;
+/**
+ * Whether a registry entry is official (see module docs).
+ *
+ * @param item - Registry entry (with registrySource set by fetchRegistry)
+ * @returns `{ official, reason }`
+ */
+export declare function registryOfficial(item: MarketplaceItem): {
+    official: boolean;
+    reason: string;
+};
+/** Finds and describes skills. */
+export declare class SkillDiscoveryService {
+    private readonly bundledRoot;
+    private readonly installedRoot;
+    private readonly fetchRegistryFn;
+    private readonly loadManifestFn;
+    private readonly runner;
+    /**
+     * @param deps - Injectable dependencies (all optional)
+     */
+    constructor(deps?: SkillDiscoveryDeps);
+    /**
+     * `<package root>/config/skills/agent`, or null when the package root cannot be found.
+     *
+     * @returns Absolute path or null
+     */
+    static defaultBundledRoot(): string | null;
+    /**
+     * Where to start looking for the package root.
+     *
+     * The compiled backend and CLI are ES modules, where `__dirname` does not
+     * exist (a bare reference throws); under ts-jest it does. The entry script
+     * (`process.argv[1]`, realpath'd through the global `bin` symlink) is
+     * always inside the package at runtime, so it is the anchor that works
+     * for `crewly` and the backend alike; cwd is the last resort.
+     *
+     * @returns Candidate start directories, most reliable first
+     */
+    static packageSearchStarts(): string[];
+    /**
+     * Find skills for a need, best first.
+     *
+     * @param query - What the agent needs ("transcribe voice message", "read pdf")
+     * @param options - `limit` (default FIND_MAX_RESULTS); `probe` runs check-only setup on the top few (default true)
+     * @returns Ranked candidates (score > 0) and whether the registry was reachable
+     *
+     * @example
+     * ```ts
+     * const { candidates } = await discovery.find('transcribe a voice message');
+     * candidates[0].id; // 'transcribe-audio'
+     * ```
+     */
+    find(query: string, options?: {
+        limit?: number;
+        probe?: boolean;
+    }): Promise<{
+        candidates: SkillCandidate[];
+        registryAvailable: boolean;
+    }>;
+    /**
+     * Resolve one skill by id (local id, directory name or registry id).
+     *
+     * @param id - Skill id
+     * @returns The skill, or null when neither bundled, installed nor in the registry
+     */
+    resolve(id: string): Promise<ResolvedSkill | null>;
+    /**
+     * Resolve a skill that is on this machine (bundled or installed) without
+     * touching the network — for `crewly skills setup` offline.
+     *
+     * Official status of an installed marketplace skill needs the registry, so
+     * here it is reported as not official; bundled skills are official.
+     *
+     * @param id - Skill id or directory name
+     * @returns The skill, or null when it is not on this machine
+     */
+    resolveLocal(id: string): Promise<ResolvedSkill | null>;
+    /**
+     * Pick a candidate by id, registry id or directory name.
+     *
+     * @param id - Wanted id
+     * @param all - Candidates
+     * @returns The match or null
+     */
+    private pick;
+    /**
+     * Run a check-only setup probe and record the result on the candidate.
+     *
+     * @param c - Candidate (mutated)
+     * @returns The same candidate
+     */
+    probe(c: ResolvedSkill): Promise<ResolvedSkill>;
+    /**
+     * Strip internals for API output.
+     *
+     * @param c - Resolved candidate
+     * @returns Public candidate
+     */
+    publicView(c: ResolvedSkill): SkillCandidate;
+    /**
+     * Build every candidate from all sources.
+     *
+     * @param options - `registry: false` skips the registry fetch
+     * @returns Candidates and registry reachability
+     */
+    private collect;
+    /**
+     * Candidate for a local (bundled or installed) skill.
+     *
+     * @param local - Local skill
+     * @param item - Matching registry entry, if any
+     * @returns Candidate
+     */
+    private fromLocal;
+    /**
+     * Candidate for a registry-only skill.
+     *
+     * @param item - Registry entry
+     * @param installed - The marketplace manifest lists it (files may still be missing)
+     * @returns Candidate
+     */
+    private fromRegistry;
+    /**
+     * Validate a raw setup block and record it on the candidate.
+     *
+     * @param c - Candidate (mutated)
+     * @param raw - Raw `setup` value
+     */
+    private attachSetup;
+    /**
+     * Scan a skills root: direct skill dirs, and one level of category dirs.
+     *
+     * @param root - Directory
+     * @param source - Label for what is found
+     * @returns Local skills
+     */
+    private scanRoot;
+    /**
+     * Read one skill directory (SKILL.md frontmatter wins over skill.json, as in the registry builder).
+     *
+     * @param dir - Skill directory
+     * @param source - Label
+     * @returns The skill, or null when the directory has no manifest
+     */
+    private readLocal;
+}
+/**
+ * The process-wide discovery service.
+ *
+ * @returns The service
+ */
+export declare function getSkillDiscoveryService(): SkillDiscoveryService;
+//# sourceMappingURL=skill-discovery.service.d.ts.map