@cleocode/caamp 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -930,6 +930,267 @@ interface ValidationResult {
  */
 declare function validateSkill(filePath: string): Promise<ValidationResult>;
 
+/**
+ * Marketplace types shared between adapters
+ */
+interface MarketplaceAdapter {
+    name: string;
+    search(query: string, limit?: number): Promise<MarketplaceResult[]>;
+    getSkill(scopedName: string): Promise<MarketplaceResult | null>;
+}
+interface MarketplaceResult {
+    name: string;
+    scopedName: string;
+    description: string;
+    author: string;
+    stars: number;
+    githubUrl: string;
+    repoFullName: string;
+    path: string;
+    source: string;
+}
+
+declare const RECOMMENDATION_ERROR_CODES: {
+    readonly QUERY_INVALID: "E_SKILLS_QUERY_INVALID";
+    readonly NO_MATCHES: "E_SKILLS_NO_MATCHES";
+    readonly SOURCE_UNAVAILABLE: "E_SKILLS_SOURCE_UNAVAILABLE";
+    readonly CRITERIA_CONFLICT: "E_SKILLS_CRITERIA_CONFLICT";
+};
+type RecommendationErrorCode = (typeof RECOMMENDATION_ERROR_CODES)[keyof typeof RECOMMENDATION_ERROR_CODES];
+interface RecommendationValidationIssue {
+    code: RecommendationErrorCode;
+    field: "query" | "mustHave" | "prefer" | "exclude";
+    message: string;
+}
+interface RecommendationValidationResult {
+    valid: boolean;
+    issues: RecommendationValidationIssue[];
+}
+interface RecommendationCriteriaInput {
+    query?: string;
+    mustHave?: string | string[];
+    prefer?: string | string[];
+    exclude?: string | string[];
+}
+interface NormalizedRecommendationCriteria {
+    query: string;
+    queryTokens: string[];
+    mustHave: string[];
+    prefer: string[];
+    exclude: string[];
+}
+type RecommendationReasonCode = "MATCH_TOPIC_GITBOOK" | "HAS_GIT_SYNC" | "HAS_API_WORKFLOW" | "PENALTY_LEGACY_CLI" | "MUST_HAVE_MATCH" | "MISSING_MUST_HAVE" | "PREFER_MATCH" | "QUERY_MATCH" | "STAR_SIGNAL" | "METADATA_SIGNAL" | "MODERN_MARKER" | "LEGACY_MARKER" | "EXCLUDE_MATCH";
+interface RecommendationReason {
+    code: RecommendationReasonCode;
+    detail?: string;
+}
+interface RecommendationScoreBreakdown {
+    mustHave: number;
+    prefer: number;
+    query: number;
+    stars: number;
+    metadata: number;
+    modernity: number;
+    exclusionPenalty: number;
+    total: number;
+}
+interface RankedSkillRecommendation {
+    skill: MarketplaceResult;
+    score: number;
+    reasons: RecommendationReason[];
+    tradeoffs: string[];
+    excluded: boolean;
+    breakdown?: RecommendationScoreBreakdown;
+}
+interface RecommendationOptions {
+    top?: number;
+    includeDetails?: boolean;
+    weights?: Partial<RecommendationWeights>;
+    modernMarkers?: string[];
+    legacyMarkers?: string[];
+}
+interface RecommendationWeights {
+    mustHaveMatch: number;
+    preferMatch: number;
+    queryTokenMatch: number;
+    starsFactor: number;
+    metadataBoost: number;
+    modernMarkerBoost: number;
+    legacyMarkerPenalty: number;
+    excludePenalty: number;
+    missingMustHavePenalty: number;
+}
+interface RecommendSkillsResult {
+    criteria: NormalizedRecommendationCriteria;
+    ranking: RankedSkillRecommendation[];
+}
+declare function tokenizeCriteriaValue(value: string): string[];
+declare function validateRecommendationCriteria(input: RecommendationCriteriaInput): RecommendationValidationResult;
+declare function normalizeRecommendationCriteria(input: RecommendationCriteriaInput): NormalizedRecommendationCriteria;
+declare function scoreSkillRecommendation(skill: MarketplaceResult, criteria: NormalizedRecommendationCriteria, options?: RecommendationOptions): RankedSkillRecommendation;
+declare function recommendSkills$1(skills: MarketplaceResult[], criteriaInput: RecommendationCriteriaInput, options?: RecommendationOptions): RecommendSkillsResult;
+declare const rankSkills: typeof recommendSkills$1;
+
+/**
+ * Advanced orchestration helpers for multi-provider operations.
+ *
+ * These helpers compose CAAMP's lower-level APIs into production patterns:
+ * tier-based targeting, conflict-aware installs, and rollback-capable batches.
+ */
+
+type Scope = "project" | "global";
+/**
+ * Filter providers by minimum priority and return them in deterministic tier order.
+ *
+ * `minimumPriority = "medium"` returns `high` + `medium`.
+ */
+declare function selectProvidersByMinimumPriority(providers: Provider[], minimumPriority?: ProviderPriority): Provider[];
+/**
+ * Single MCP operation entry used by batch orchestration.
+ */
+interface McpBatchOperation {
+    serverName: string;
+    config: McpServerConfig;
+    scope?: Scope;
+}
+/**
+ * Single skill operation entry used by batch orchestration.
+ */
+interface SkillBatchOperation {
+    sourcePath: string;
+    skillName: string;
+    isGlobal?: boolean;
+}
+/**
+ * Options for rollback-capable batch installation.
+ */
+interface BatchInstallOptions {
+    providers?: Provider[];
+    minimumPriority?: ProviderPriority;
+    mcp?: McpBatchOperation[];
+    skills?: SkillBatchOperation[];
+    projectDir?: string;
+}
+/**
+ * Result of rollback-capable batch installation.
+ */
+interface BatchInstallResult {
+    success: boolean;
+    providerIds: string[];
+    mcpApplied: number;
+    skillsApplied: number;
+    rollbackPerformed: boolean;
+    rollbackErrors: string[];
+    error?: string;
+}
+/**
+ * Install multiple MCP servers and skills across filtered providers with rollback.
+ *
+ * Rollback behavior:
+ * - MCP config files are restored exactly from snapshots.
+ * - Skill state is restored for canonical skill dirs and targeted provider link paths.
+ */
+declare function installBatchWithRollback(options: BatchInstallOptions): Promise<BatchInstallResult>;
+/**
+ * Conflict policy when applying MCP install plans.
+ */
+type ConflictPolicy = "fail" | "skip" | "overwrite";
+/**
+ * MCP conflict code.
+ */
+type McpConflictCode = "unsupported-transport" | "unsupported-headers" | "existing-mismatch";
+/**
+ * Conflict detected during preflight.
+ */
+interface McpConflict {
+    providerId: string;
+    serverName: string;
+    scope: Scope;
+    code: McpConflictCode;
+    message: string;
+}
+/**
+ * Result from applying install plan with conflict policy.
+ */
+interface McpPlanApplyResult {
+    conflicts: McpConflict[];
+    applied: InstallResult[];
+    skipped: Array<{
+        providerId: string;
+        serverName: string;
+        scope: Scope;
+        reason: McpConflictCode;
+    }>;
+}
+/**
+ * Preflight conflict detection for MCP install plans across providers.
+ */
+declare function detectMcpConfigConflicts(providers: Provider[], operations: McpBatchOperation[], projectDir?: string): Promise<McpConflict[]>;
+/**
+ * Apply MCP install plan with a conflict policy.
+ */
+declare function applyMcpInstallWithPolicy(providers: Provider[], operations: McpBatchOperation[], policy?: ConflictPolicy, projectDir?: string): Promise<McpPlanApplyResult>;
+/**
+ * Result of a single-operation instruction update across providers.
+ */
+interface InstructionUpdateSummary {
+    scope: Scope;
+    updatedFiles: number;
+    actions: Array<{
+        file: string;
+        action: "created" | "added" | "updated";
+        providers: string[];
+        configFormats: ConfigFormat[];
+    }>;
+}
+/**
+ * Update instruction files across providers as a single operation.
+ *
+ * Works the same regardless of provider config format (JSON/YAML/TOML/JSONC)
+ * because instruction files are handled through CAAMP markers.
+ */
+declare function updateInstructionsSingleOperation(providers: Provider[], content: string, scope?: Scope, projectDir?: string): Promise<InstructionUpdateSummary>;
+/**
+ * Request payload for dual-scope provider configuration.
+ */
+interface DualScopeConfigureOptions {
+    globalMcp?: Array<{
+        serverName: string;
+        config: McpServerConfig;
+    }>;
+    projectMcp?: Array<{
+        serverName: string;
+        config: McpServerConfig;
+    }>;
+    instructionContent?: string | {
+        global?: string;
+        project?: string;
+    };
+    projectDir?: string;
+}
+/**
+ * Result of dual-scope provider configuration.
+ */
+interface DualScopeConfigureResult {
+    providerId: string;
+    configPaths: {
+        global: string | null;
+        project: string | null;
+    };
+    mcp: {
+        global: InstallResult[];
+        project: InstallResult[];
+    };
+    instructions: {
+        global?: Map<string, "created" | "added" | "updated">;
+        project?: Map<string, "created" | "added" | "updated">;
+    };
+}
+/**
+ * Configure both global and project-level settings for one provider in one call.
+ */
+declare function configureProviderGlobalAndProject(provider: Provider, options: DualScopeConfigureOptions): Promise<DualScopeConfigureResult>;
+
 /**
  * Provider registry loader
  *
@@ -1158,6 +1419,19 @@ declare function discoverSkill(skillDir: string): Promise<SkillEntry | null>;
  */
 declare function discoverSkills(rootDir: string): Promise<SkillEntry[]>;
 
+interface SearchSkillsOptions {
+    limit?: number;
+}
+interface RecommendSkillsQueryOptions extends RecommendationOptions {
+    limit?: number;
+}
+declare function formatSkillRecommendations(result: RecommendSkillsResult, opts: {
+    mode: "human" | "json";
+    details?: boolean;
+}): string | Record<string, unknown>;
+declare function searchSkills(query: string, options?: SearchSkillsOptions): Promise<MarketplaceResult[]>;
+declare function recommendSkills(query: string, criteria: Omit<RecommendationCriteriaInput, "query">, options?: RecommendSkillsQueryOptions): Promise<RecommendSkillsResult>;
+
 /**
  * Security scanning engine for SKILL.md files
  *
@@ -1490,26 +1764,6 @@ declare function checkSkillUpdate(skillName: string): Promise<{
     status: "up-to-date" | "update-available" | "unknown";
 }>;
 
-/**
- * Marketplace types shared between adapters
- */
-interface MarketplaceAdapter {
-    name: string;
-    search(query: string, limit?: number): Promise<MarketplaceResult[]>;
-    getSkill(scopedName: string): Promise<MarketplaceResult | null>;
-}
-interface MarketplaceResult {
-    name: string;
-    scopedName: string;
-    description: string;
-    author: string;
-    stars: number;
-    githubUrl: string;
-    repoFullName: string;
-    path: string;
-    source: string;
-}
-
 /**
  * Unified marketplace client
  *
@@ -1893,4 +2147,4 @@ declare function isVerbose(): boolean;
  */
 declare function isQuiet(): boolean;
 
-export { type AuditFinding, type AuditResult, type AuditRule, type AuditSeverity, type CaampLockFile, type ConfigFormat, type DetectionResult, type GlobalOptions, type InjectionCheckResult, type InjectionStatus, type InstallResult, type LockEntry, MarketplaceClient, type MarketplaceResult, type MarketplaceSearchResult, type MarketplaceSkill, type McpServerConfig, type McpServerEntry, type ParsedSource, type Provider, type ProviderPriority, type ProviderStatus, type SkillEntry, type SkillInstallResult, type SkillMetadata, type SourceType, type TransportType, type ValidationIssue, type ValidationResult, buildServerConfig, checkAllInjections, checkInjection, checkSkillUpdate, deepMerge, detectAllProviders, detectProjectProviders, detectProvider, discoverSkill, discoverSkills, ensureDir, generateInjectionContent, getAllProviders, getInstalledProviders, getInstructionFiles, getLastSelectedAgents, getNestedValue, getProvider, getProviderCount, getProvidersByInstructFile, getProvidersByPriority, getProvidersByStatus, getRegistryVersion, getTrackedMcpServers, getTrackedSkills, getTransform, groupByInstructFile, inject, injectAll, installMcpServer, installMcpServerToAll, installSkill, isMarketplaceScoped, isQuiet, isVerbose, listAllMcpServers, listCanonicalSkills, listMcpServers, parseSkillFile, parseSource, readConfig, readLockFile, recordMcpInstall, recordSkillInstall, removeConfig, removeInjection, removeMcpFromLock, removeMcpServer, removeSkill, removeSkillFromLock, resolveAlias, resolveConfigPath, saveLastSelectedAgents, scanDirectory, scanFile, setQuiet, setVerbose, toSarif, validateSkill, writeConfig };
+export { type AuditFinding, type AuditResult, type AuditRule, type AuditSeverity, type BatchInstallOptions, type BatchInstallResult, type CaampLockFile, type ConfigFormat, type ConflictPolicy, type DetectionResult, type DualScopeConfigureOptions, type DualScopeConfigureResult, type GlobalOptions, type InjectionCheckResult, type InjectionStatus, type InstallResult, type InstructionUpdateSummary, type LockEntry, MarketplaceClient, type MarketplaceResult, type MarketplaceSearchResult, type MarketplaceSkill, type McpBatchOperation, type McpConflict, type McpConflictCode, type McpPlanApplyResult, type McpServerConfig, type McpServerEntry, type NormalizedRecommendationCriteria, type ParsedSource, type Provider, type ProviderPriority, type ProviderStatus, RECOMMENDATION_ERROR_CODES, type RankedSkillRecommendation, type RecommendSkillsResult, type RecommendationCriteriaInput, type RecommendationErrorCode, type RecommendationOptions, type RecommendationReason, type RecommendationReasonCode, type RecommendationScoreBreakdown, type RecommendationValidationIssue, type RecommendationValidationResult, type RecommendationWeights, type SkillBatchOperation, type SkillEntry, type SkillInstallResult, type SkillMetadata, type SourceType, type TransportType, type ValidationIssue, type ValidationResult, applyMcpInstallWithPolicy, buildServerConfig, checkAllInjections, checkInjection, checkSkillUpdate, configureProviderGlobalAndProject, deepMerge, detectAllProviders, detectMcpConfigConflicts, detectProjectProviders, detectProvider, discoverSkill, discoverSkills, ensureDir, formatSkillRecommendations, generateInjectionContent, getAllProviders, getInstalledProviders, getInstructionFiles, getLastSelectedAgents, getNestedValue, getProvider, getProviderCount, getProvidersByInstructFile, getProvidersByPriority, getProvidersByStatus, getRegistryVersion, getTrackedMcpServers, getTrackedSkills, getTransform, groupByInstructFile, inject, injectAll, installBatchWithRollback, installMcpServer, installMcpServerToAll, installSkill, isMarketplaceScoped, isQuiet, isVerbose, listAllMcpServers, listCanonicalSkills, listMcpServers, normalizeRecommendationCriteria, parseSkillFile, parseSource, rankSkills, readConfig, readLockFile, recommendSkills, recordMcpInstall, recordSkillInstall, removeConfig, removeInjection, removeMcpFromLock, removeMcpServer, removeSkill, removeSkillFromLock, resolveAlias, resolveConfigPath, saveLastSelectedAgents, scanDirectory, scanFile, scoreSkillRecommendation, searchSkills, selectProvidersByMinimumPriority, setQuiet, setVerbose, toSarif, tokenizeCriteriaValue, updateInstructionsSingleOperation, validateRecommendationCriteria, validateSkill, writeConfig };

package/dist/index.js

@@ -1,16 +1,21 @@
 import {
   MarketplaceClient,
+  RECOMMENDATION_ERROR_CODES,
+  applyMcpInstallWithPolicy,
   buildServerConfig,
   checkAllInjections,
   checkInjection,
   checkSkillUpdate,
+  configureProviderGlobalAndProject,
   deepMerge,
   detectAllProviders,
+  detectMcpConfigConflicts,
   detectProjectProviders,
   detectProvider,
   discoverSkill,
   discoverSkills,
   ensureDir,
+  formatSkillRecommendations,
   generateInjectionContent,
   getAllProviders,
   getInstalledProviders,
@@ -29,6 +34,7 @@ import {
   groupByInstructFile,
   inject,
   injectAll,
+  installBatchWithRollback,
   installMcpServer,
   installMcpServerToAll,
   installSkill,
@@ -38,10 +44,13 @@ import {
   listAllMcpServers,
   listCanonicalSkills,
   listMcpServers,
+  normalizeRecommendationCriteria,
   parseSkillFile,
   parseSource,
+  rankSkills,
   readConfig,
   readLockFile,
+  recommendSkills,
   recordMcpInstall,
   recordSkillInstall,
   removeConfig,
@@ -55,25 +64,36 @@ import {
   saveLastSelectedAgents,
   scanDirectory,
   scanFile,
+  scoreSkillRecommendation,
+  searchSkills,
+  selectProvidersByMinimumPriority,
   setQuiet,
   setVerbose,
   toSarif,
+  tokenizeCriteriaValue,
+  updateInstructionsSingleOperation,
+  validateRecommendationCriteria,
   validateSkill,
   writeConfig
-} from "./chunk-PCWTRJV2.js";
+} from "./chunk-ZYINKJDE.js";
 export {
   MarketplaceClient,
+  RECOMMENDATION_ERROR_CODES,
+  applyMcpInstallWithPolicy,
   buildServerConfig,
   checkAllInjections,
   checkInjection,
   checkSkillUpdate,
+  configureProviderGlobalAndProject,
   deepMerge,
   detectAllProviders,
+  detectMcpConfigConflicts,
   detectProjectProviders,
   detectProvider,
   discoverSkill,
   discoverSkills,
   ensureDir,
+  formatSkillRecommendations,
   generateInjectionContent,
   getAllProviders,
   getInstalledProviders,
@@ -92,6 +112,7 @@ export {
   groupByInstructFile,
   inject,
   injectAll,
+  installBatchWithRollback,
   installMcpServer,
   installMcpServerToAll,
   installSkill,
@@ -101,10 +122,13 @@ export {
   listAllMcpServers,
   listCanonicalSkills,
   listMcpServers,
+  normalizeRecommendationCriteria,
   parseSkillFile,
   parseSource,
+  rankSkills,
   readConfig,
   readLockFile,
+  recommendSkills,
   recordMcpInstall,
   recordSkillInstall,
   removeConfig,
@@ -118,9 +142,15 @@ export {
   saveLastSelectedAgents,
   scanDirectory,
   scanFile,
+  scoreSkillRecommendation,
+  searchSkills,
+  selectProvidersByMinimumPriority,
   setQuiet,
   setVerbose,
   toSarif,
+  tokenizeCriteriaValue,
+  updateInstructionsSingleOperation,
+  validateRecommendationCriteria,
   validateSkill,
   writeConfig
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/caamp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Central AI Agent Managed Packages - unified provider registry and package manager for AI coding agents",
   "type": "module",
   "bin": {
@@ -47,6 +47,7 @@
   "license": "MIT",
   "dependencies": {
     "@clack/prompts": "^1.0.0",
+    "@cleocode/lafs-protocol": "^0.1.1",
     "@iarna/toml": "^2.2.5",
     "commander": "^14.0.0",
     "gray-matter": "^4.0.3",