@cleocode/caamp 1.7.1 → 1.8.0

package/dist/index.d.ts

@@ -1446,7 +1446,7 @@ interface InstructionUpdateSummary {
     updatedFiles: number;
     actions: Array<{
         file: string;
-        action: "created" | "added" | "updated";
+        action: "created" | "added" | "updated" | "intact";
         providers: string[];
         configFormats: ConfigFormat[];
     }>;
@@ -1490,8 +1490,8 @@ interface DualScopeConfigureResult {
         project: InstallResult[];
     };
     instructions: {
-        global?: Map<string, "created" | "added" | "updated">;
-        project?: Map<string, "created" | "added" | "updated">;
+        global?: Map<string, "created" | "added" | "updated" | "intact">;
+        project?: Map<string, "created" | "added" | "updated" | "intact">;
     };
 }
 /**
@@ -2606,6 +2606,104 @@ declare function checkAllSkillUpdates(): Promise<Record<string, {
     status: "up-to-date" | "update-available" | "unknown";
 }>>;
 
+/**
+ * Skill integrity checking
+ *
+ * Validates that installed skills have intact symlinks, correct canonical paths,
+ * and enforces ct-* prefix priority for CAAMP-shipped skills.
+ */
+
+/**
+ * Status of a single skill's integrity check.
+ */
+type SkillIntegrityStatus = "intact" | "broken-symlink" | "missing-canonical" | "missing-link" | "not-tracked" | "tampered";
+/**
+ * Result of checking a single skill's integrity.
+ */
+interface SkillIntegrityResult {
+    /** Skill name. */
+    name: string;
+    /** Overall integrity status. */
+    status: SkillIntegrityStatus;
+    /** Whether the canonical directory exists. */
+    canonicalExists: boolean;
+    /** Expected canonical path from lock file. */
+    canonicalPath: string | null;
+    /** Provider link statuses — which agents have valid symlinks. */
+    linkStatuses: Array<{
+        providerId: string;
+        linkPath: string;
+        exists: boolean;
+        isSymlink: boolean;
+        pointsToCanonical: boolean;
+    }>;
+    /** Whether this is a CAAMP-reserved (ct-*) skill. */
+    isCaampOwned: boolean;
+    /** Human-readable issue description, if any. */
+    issue?: string;
+}
+/**
+ * Check whether a skill name is reserved by CAAMP (ct-* prefix).
+ *
+ * @param skillName - Skill name to check
+ * @returns `true` if the skill name starts with `ct-`
+ */
+declare function isCaampOwnedSkill(skillName: string): boolean;
+/**
+ * Check the integrity of a single installed skill.
+ *
+ * Validates:
+ * - Canonical directory exists on disk
+ * - Lock file entry matches actual state
+ * - Symlinks from provider skill directories point to the canonical path
+ *
+ * @param skillName - Name of the skill to check
+ * @param providers - Providers to check symlinks for
+ * @param scope - Whether to check global or project links
+ * @param projectDir - Project directory (for project scope)
+ * @returns Integrity check result
+ */
+declare function checkSkillIntegrity(skillName: string, providers: Provider[], scope?: "global" | "project", projectDir?: string): Promise<SkillIntegrityResult>;
+/**
+ * Check integrity of all tracked skills.
+ *
+ * @param providers - Providers to check symlinks for
+ * @param scope - Whether to check global or project links
+ * @param projectDir - Project directory (for project scope)
+ * @returns Map of skill name to integrity result
+ */
+declare function checkAllSkillIntegrity(providers: Provider[], scope?: "global" | "project", projectDir?: string): Promise<Map<string, SkillIntegrityResult>>;
+/**
+ * Resolve a skill name conflict where a user-installed skill collides
+ * with a CAAMP-owned (ct-*) skill.
+ *
+ * CAAMP-owned skills always win. Returns `true` if the incoming skill
+ * should take precedence over the existing installation.
+ *
+ * @param skillName - Skill name to check
+ * @param incomingSource - Source of the incoming skill installation
+ * @param existingEntry - Existing lock entry, if any
+ * @returns `true` if the incoming installation should proceed
+ */
+declare function shouldOverrideSkill(skillName: string, incomingSource: string, existingEntry: LockEntry | undefined): boolean;
+/**
+ * Validate instruction file injection status across all providers.
+ *
+ * Checks that CAAMP blocks exist and are current in all relevant
+ * instruction files.
+ *
+ * @param providers - Providers to check
+ * @param projectDir - Project directory
+ * @param scope - Whether to check global or project files
+ * @param expectedContent - Expected CAAMP block content
+ * @returns Array of file paths with issues
+ */
+declare function validateInstructionIntegrity(providers: Provider[], projectDir: string, scope: "project" | "global", expectedContent?: string): Promise<Array<{
+    file: string;
+    providerId: string;
+    issue: string;
+}>>;
+
 /**
  * Unified marketplace client
  *
@@ -2711,21 +2809,25 @@ declare function checkInjection(filePath: string, expectedContent?: string): Pro
  * Inject content into an instruction file between CAAMP markers.
  *
  * Behavior depends on the file state:
- * - File does not exist: creates the file with the injection block
- * - File exists without markers: prepends the injection block
- * - File exists with markers: replaces the existing injection block
+ * - File does not exist: creates the file with the injection block → `"created"`
+ * - File exists without markers: prepends the injection block → `"added"`
+ * - File exists with markers, content differs: replaces the block → `"updated"`
+ * - File exists with markers, content matches: no-op → `"intact"`
+ *
+ * This function is **idempotent** — calling it multiple times with the same
+ * content will not modify the file after the first write.
  *
  * @param filePath - Absolute path to the instruction file
  * @param content - Content to inject between CAAMP markers
- * @returns Action taken: `"created"`, `"added"`, or `"updated"`
+ * @returns Action taken: `"created"`, `"added"`, `"updated"`, or `"intact"`
  *
  * @example
  * ```typescript
  * const action = await inject("/project/CLAUDE.md", "## My Config\nSome content");
- * console.log(`File ${action}`);
+ * console.log(`File ${action}`); // "created" on first call, "intact" on subsequent
  * ```
  */
-declare function inject(filePath: string, content: string): Promise<"created" | "added" | "updated">;
+declare function inject(filePath: string, content: string): Promise<"created" | "added" | "updated" | "intact">;
 /**
  * Remove the CAAMP injection block from an instruction file.
  *
@@ -2768,7 +2870,7 @@ declare function checkAllInjections(providers: Provider[], projectDir: string, s
  * @param projectDir - Absolute path to the project directory
  * @param scope - Whether to target project or global instruction files
  * @param content - Content to inject between CAAMP markers
- * @returns Map of file path to action taken (`"created"`, `"added"`, or `"updated"`)
+ * @returns Map of file path to action taken (`"created"`, `"added"`, `"updated"`, or `"intact"`)
  *
  * @example
  * ```typescript
@@ -2778,7 +2880,87 @@ declare function checkAllInjections(providers: Provider[], projectDir: string, s
  * }
  * ```
  */
-declare function injectAll(providers: Provider[], projectDir: string, scope: "project" | "global", content: string): Promise<Map<string, "created" | "added" | "updated">>;
+declare function injectAll(providers: Provider[], projectDir: string, scope: "project" | "global", content: string): Promise<Map<string, "created" | "added" | "updated" | "intact">>;
+/**
+ * Options for ensuring a provider instruction file.
+ */
+interface EnsureProviderInstructionFileOptions {
+    /** `@` references to inject (e.g. `["@AGENTS.md"]`). */
+    references: string[];
+    /** Optional inline content blocks. */
+    content?: string[];
+    /** Whether this is a global or project-level file. Defaults to `"project"`. */
+    scope?: "project" | "global";
+}
+/**
+ * Result of ensuring a provider instruction file.
+ */
+interface EnsureProviderInstructionFileResult {
+    /** Absolute path to the instruction file. */
+    filePath: string;
+    /** Instruction file name from the provider registry. */
+    instructFile: string;
+    /** Action taken. */
+    action: "created" | "added" | "updated" | "intact";
+    /** Provider ID. */
+    providerId: string;
+}
+/**
+ * Ensure a provider's instruction file exists with the correct CAAMP block.
+ *
+ * This is the canonical API for adapters and external packages to manage
+ * provider instruction files. Instead of directly creating/modifying
+ * CLAUDE.md, GEMINI.md, etc., callers should use this function to
+ * delegate instruction file management to CAAMP.
+ *
+ * The instruction file name is resolved from CAAMP's provider registry
+ * (single source of truth), not hardcoded by the caller.
+ *
+ * @param providerId - Provider ID from the registry (e.g. `"claude-code"`, `"gemini-cli"`)
+ * @param projectDir - Absolute path to the project directory
+ * @param options - References, content, and scope configuration
+ * @returns Result with file path, action taken, and provider metadata
+ * @throws {Error} If the provider ID is not found in the registry
+ *
+ * @example
+ * ```typescript
+ * // Adapter delegates instruction file creation to CAAMP:
+ * const result = await ensureProviderInstructionFile("claude-code", "/project", {
+ *   references: ["@AGENTS.md"],
+ * });
+ * // result.filePath → "/project/CLAUDE.md"
+ * // result.action → "created" | "added" | "updated" | "intact"
+ *
+ * // Global scope:
+ * const globalResult = await ensureProviderInstructionFile("claude-code", homedir(), {
+ *   references: ["@~/.agents/AGENTS.md"],
+ *   scope: "global",
+ * });
+ * ```
+ */
+declare function ensureProviderInstructionFile(providerId: string, projectDir: string, options: EnsureProviderInstructionFileOptions): Promise<EnsureProviderInstructionFileResult>;
+/**
+ * Ensure instruction files for multiple providers at once.
+ *
+ * Deduplicates by file path — providers sharing the same instruction file
+ * (e.g. many providers use AGENTS.md) are only written once.
+ *
+ * @param providerIds - Array of provider IDs from the registry
+ * @param projectDir - Absolute path to the project directory
+ * @param options - References, content, and scope configuration
+ * @returns Array of results, one per unique instruction file
+ * @throws {Error} If any provider ID is not found in the registry
+ *
+ * @example
+ * ```typescript
+ * const results = await ensureAllProviderInstructionFiles(
+ *   ["claude-code", "cursor", "gemini-cli"],
+ *   "/project",
+ *   { references: ["@AGENTS.md"] },
+ * );
+ * ```
+ */
+declare function ensureAllProviderInstructionFiles(providerIds: string[], projectDir: string, options: EnsureProviderInstructionFileOptions): Promise<EnsureProviderInstructionFileResult[]>;
 
 /**
  * Instruction template management
@@ -3043,4 +3225,4 @@ declare function isVerbose(): boolean;
  */
 declare function isQuiet(): boolean;
 
-export { type AuditFinding, type AuditResult, type AuditRule, type AuditSeverity, type BatchInstallOptions, type BatchInstallResult, type CaampLockFile, type CleoChannel, type CleoProfileBuildResult, type ConfigFormat, type ConflictPolicy, type CtDispatchMatrix, type CtManifest, type CtManifestSkill, type CtProfileDefinition, type CtSkillEntry, type CtValidationIssue, type CtValidationResult, type DetectionCacheOptions, type DetectionResult, type DualScopeConfigureOptions, type DualScopeConfigureResult, type GlobalOptions, type HookEvent, type InferredLockData, type InjectionCheckResult, type InjectionStatus, type InjectionTemplate, 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 PlatformPaths, type Provider, type ProviderCapabilities, type ProviderHooksCapability, type ProviderPriority, type ProviderSkillsCapability, type ProviderSpawnCapability, 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 ReconcileOptions, type ReconcileResult, type SkillBatchOperation, type SkillEntry, type SkillInstallResult, type SkillLibrary, type SkillLibraryDispatchMatrix, type SkillLibraryEntry, type SkillLibraryManifest, type SkillLibraryManifestSkill, type SkillLibraryProfile, type SkillLibraryValidationIssue, type SkillLibraryValidationResult, type SkillMetadata, type SkillsPrecedence, type SourceType, type SpawnAdapter, type SpawnMechanism, type SpawnOptions, type SpawnResult, type SystemInfo, type TransportType, type ValidationIssue, type ValidationResult, _resetPlatformPathsCache, applyMcpInstallWithPolicy, buildCleoProfile, buildInjectionContent, buildLibraryFromFiles, buildServerConfig, buildSkillsMap, catalog, checkAllInjections, checkAllSkillUpdates, checkCommandReachability, checkInjection, checkSkillUpdate, clearRegisteredLibrary, configureProviderGlobalAndProject, deepMerge, detectAllProviders, detectMcpConfigConflicts, detectProjectProviders, detectProvider, discoverSkill, discoverSkills, ensureDir, extractVersionTag, formatSkillRecommendations, generateInjectionContent, generateSkillsSection, getAgentsConfigPath, getAgentsHome, getAgentsInstructFile, getAgentsLinksDir, getAgentsMcpDir, getAgentsMcpServersPath, getAgentsSpecDir, getAgentsWikiDir, getAllProviders, getCanonicalSkillsDir, getCommonHookEvents, getEffectiveSkillsPaths, getInstalledProviders, getInstructionFiles, getLastSelectedAgents, getLockFilePath, getNestedValue, getPlatformLocations, getPlatformPaths, getProjectAgentsDir, getProvider, getProviderCapabilities, getProviderCount, getProvidersByHookEvent, getProvidersByInstructFile, getProvidersByPriority, getProvidersBySkillsPrecedence, getProvidersBySpawnCapability, getProvidersByStatus, getRegistryVersion, getSpawnCapableProviders, getSystemInfo, getTrackedMcpServers, getTrackedSkills, getTransform, groupByInstructFile, inferCleoLockData, inject, injectAll, installBatchWithRollback, installMcpServer, installMcpServerToAll, installSkill, isCleoSource, isMarketplaceScoped, isQuiet, isVerbose, listAgentsMcpServers, listAllMcpServers, listCanonicalSkills, listMcpServers, loadLibraryFromModule, normalizeCleoChannel, normalizeRecommendationCriteria, parseEnvAssignments, parseInjectionContent, parseSkillFile, parseSource, providerSupports, providerSupportsById, rankSkills, readConfig, readLockFile, recommendSkills, reconcileCleoLock, recordMcpInstall, recordSkillInstall, registerSkillLibrary, registerSkillLibraryFromPath, removeConfig, removeInjection, removeMcpFromLock, removeMcpServer, removeSkill, removeSkillFromLock, resetDetectionCache, resolveAlias, resolveChannelFromServerName, resolveCleoServerName, resolveConfigPath, resolveProviderSkillsDirs, resolveRegistryTemplatePath, saveLastSelectedAgents, scanDirectory, scanFile, scoreSkillRecommendation, searchSkills, selectProvidersByMinimumPriority, setQuiet, setVerbose, toSarif, tokenizeCriteriaValue, updateInstructionsSingleOperation, validateRecommendationCriteria, validateSkill, writeConfig };
+export { type AuditFinding, type AuditResult, type AuditRule, type AuditSeverity, type BatchInstallOptions, type BatchInstallResult, type CaampLockFile, type CleoChannel, type CleoProfileBuildResult, type ConfigFormat, type ConflictPolicy, type CtDispatchMatrix, type CtManifest, type CtManifestSkill, type CtProfileDefinition, type CtSkillEntry, type CtValidationIssue, type CtValidationResult, type DetectionCacheOptions, type DetectionResult, type DualScopeConfigureOptions, type DualScopeConfigureResult, type EnsureProviderInstructionFileOptions, type EnsureProviderInstructionFileResult, type GlobalOptions, type HookEvent, type InferredLockData, type InjectionCheckResult, type InjectionStatus, type InjectionTemplate, 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 PlatformPaths, type Provider, type ProviderCapabilities, type ProviderHooksCapability, type ProviderPriority, type ProviderSkillsCapability, type ProviderSpawnCapability, 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 ReconcileOptions, type ReconcileResult, type SkillBatchOperation, type SkillEntry, type SkillInstallResult, type SkillIntegrityResult, type SkillIntegrityStatus, type SkillLibrary, type SkillLibraryDispatchMatrix, type SkillLibraryEntry, type SkillLibraryManifest, type SkillLibraryManifestSkill, type SkillLibraryProfile, type SkillLibraryValidationIssue, type SkillLibraryValidationResult, type SkillMetadata, type SkillsPrecedence, type SourceType, type SpawnAdapter, type SpawnMechanism, type SpawnOptions, type SpawnResult, type SystemInfo, type TransportType, type ValidationIssue, type ValidationResult, _resetPlatformPathsCache, applyMcpInstallWithPolicy, buildCleoProfile, buildInjectionContent, buildLibraryFromFiles, buildServerConfig, buildSkillsMap, catalog, checkAllInjections, checkAllSkillIntegrity, checkAllSkillUpdates, checkCommandReachability, checkInjection, checkSkillIntegrity, checkSkillUpdate, clearRegisteredLibrary, configureProviderGlobalAndProject, deepMerge, detectAllProviders, detectMcpConfigConflicts, detectProjectProviders, detectProvider, discoverSkill, discoverSkills, ensureAllProviderInstructionFiles, ensureDir, ensureProviderInstructionFile, extractVersionTag, formatSkillRecommendations, generateInjectionContent, generateSkillsSection, getAgentsConfigPath, getAgentsHome, getAgentsInstructFile, getAgentsLinksDir, getAgentsMcpDir, getAgentsMcpServersPath, getAgentsSpecDir, getAgentsWikiDir, getAllProviders, getCanonicalSkillsDir, getCommonHookEvents, getEffectiveSkillsPaths, getInstalledProviders, getInstructionFiles, getLastSelectedAgents, getLockFilePath, getNestedValue, getPlatformLocations, getPlatformPaths, getProjectAgentsDir, getProvider, getProviderCapabilities, getProviderCount, getProvidersByHookEvent, getProvidersByInstructFile, getProvidersByPriority, getProvidersBySkillsPrecedence, getProvidersBySpawnCapability, getProvidersByStatus, getRegistryVersion, getSpawnCapableProviders, getSystemInfo, getTrackedMcpServers, getTrackedSkills, getTransform, groupByInstructFile, inferCleoLockData, inject, injectAll, installBatchWithRollback, installMcpServer, installMcpServerToAll, installSkill, isCaampOwnedSkill, isCleoSource, isMarketplaceScoped, isQuiet, isVerbose, listAgentsMcpServers, listAllMcpServers, listCanonicalSkills, listMcpServers, loadLibraryFromModule, normalizeCleoChannel, normalizeRecommendationCriteria, parseEnvAssignments, parseInjectionContent, parseSkillFile, parseSource, providerSupports, providerSupportsById, rankSkills, readConfig, readLockFile, recommendSkills, reconcileCleoLock, recordMcpInstall, recordSkillInstall, registerSkillLibrary, registerSkillLibraryFromPath, removeConfig, removeInjection, removeMcpFromLock, removeMcpServer, removeSkill, removeSkillFromLock, resetDetectionCache, resolveAlias, resolveChannelFromServerName, resolveCleoServerName, resolveConfigPath, resolveProviderSkillsDirs, resolveRegistryTemplatePath, saveLastSelectedAgents, scanDirectory, scanFile, scoreSkillRecommendation, searchSkills, selectProvidersByMinimumPriority, setQuiet, setVerbose, shouldOverrideSkill, toSarif, tokenizeCriteriaValue, updateInstructionsSingleOperation, validateInstructionIntegrity, validateRecommendationCriteria, validateSkill, writeConfig };

package/dist/index.js

@@ -1,18 +1,13 @@
 import {
   MarketplaceClient,
   RECOMMENDATION_ERROR_CODES,
-  _resetPlatformPathsCache,
   applyMcpInstallWithPolicy,
   buildCleoProfile,
-  buildInjectionContent,
   buildLibraryFromFiles,
   buildServerConfig,
-  buildSkillsMap,
   catalog_exports,
-  checkAllInjections,
   checkAllSkillUpdates,
   checkCommandReachability,
-  checkInjection,
   checkSkillUpdate,
   clearRegisteredLibrary,
   configureProviderGlobalAndProject,
@@ -26,47 +21,13 @@ import {
   ensureDir,
   extractVersionTag,
   formatSkillRecommendations,
-  generateInjectionContent,
-  generateSkillsSection,
-  getAgentsConfigPath,
-  getAgentsHome,
-  getAgentsInstructFile,
-  getAgentsLinksDir,
-  getAgentsMcpDir,
-  getAgentsMcpServersPath,
-  getAgentsSpecDir,
-  getAgentsWikiDir,
-  getAllProviders,
-  getCanonicalSkillsDir,
-  getCommonHookEvents,
-  getEffectiveSkillsPaths,
   getInstalledProviders,
-  getInstructionFiles,
   getLastSelectedAgents,
-  getLockFilePath,
   getNestedValue,
-  getPlatformLocations,
-  getPlatformPaths,
-  getProjectAgentsDir,
-  getProvider,
-  getProviderCapabilities,
-  getProviderCount,
-  getProvidersByHookEvent,
-  getProvidersByInstructFile,
-  getProvidersByPriority,
-  getProvidersBySkillsPrecedence,
-  getProvidersBySpawnCapability,
-  getProvidersByStatus,
-  getRegistryVersion,
-  getSpawnCapableProviders,
-  getSystemInfo,
   getTrackedMcpServers,
   getTrackedSkills,
   getTransform,
-  groupByInstructFile,
   inferCleoLockData,
-  inject,
-  injectAll,
   installBatchWithRollback,
   installMcpServer,
   installMcpServerToAll,
@@ -83,11 +44,8 @@ import {
   normalizeCleoChannel,
   normalizeRecommendationCriteria,
   parseEnvAssignments,
-  parseInjectionContent,
   parseSkillFile,
   parseSource,
-  providerSupports,
-  providerSupportsById,
   rankSkills,
   readConfig,
   readLockFile,
@@ -98,18 +56,14 @@ import {
   registerSkillLibrary,
   registerSkillLibraryFromPath,
   removeConfig,
-  removeInjection,
   removeMcpFromLock,
   removeMcpServer,
   removeSkill,
   removeSkillFromLock,
   resetDetectionCache,
-  resolveAlias,
   resolveChannelFromServerName,
   resolveCleoServerName,
   resolveConfigPath,
-  resolveProviderSkillsDirs,
-  resolveRegistryTemplatePath,
   saveLastSelectedAgents,
   scanDirectory,
   scanFile,
@@ -124,7 +78,200 @@ import {
   validateRecommendationCriteria,
   validateSkill,
   writeConfig
-} from "./chunk-6T3TJQFF.js";
+} from "./chunk-YWO4I7LI.js";
+import {
+  _resetPlatformPathsCache,
+  buildInjectionContent,
+  buildSkillsMap,
+  checkAllInjections,
+  checkInjection,
+  ensureAllProviderInstructionFiles,
+  ensureProviderInstructionFile,
+  generateInjectionContent,
+  generateSkillsSection,
+  getAgentsConfigPath,
+  getAgentsHome,
+  getAgentsInstructFile,
+  getAgentsLinksDir,
+  getAgentsMcpDir,
+  getAgentsMcpServersPath,
+  getAgentsSpecDir,
+  getAgentsWikiDir,
+  getAllProviders,
+  getCanonicalSkillsDir,
+  getCommonHookEvents,
+  getEffectiveSkillsPaths,
+  getInstructionFiles,
+  getLockFilePath,
+  getPlatformLocations,
+  getPlatformPaths,
+  getProjectAgentsDir,
+  getProvider,
+  getProviderCapabilities,
+  getProviderCount,
+  getProvidersByHookEvent,
+  getProvidersByInstructFile,
+  getProvidersByPriority,
+  getProvidersBySkillsPrecedence,
+  getProvidersBySpawnCapability,
+  getProvidersByStatus,
+  getRegistryVersion,
+  getSpawnCapableProviders,
+  getSystemInfo,
+  groupByInstructFile,
+  inject,
+  injectAll,
+  parseInjectionContent,
+  providerSupports,
+  providerSupportsById,
+  removeInjection,
+  resolveAlias,
+  resolveProviderSkillsDirs,
+  resolveRegistryTemplatePath
+} from "./chunk-ZVRDBY6L.js";
+
+// src/core/skills/integrity.ts
+import { existsSync, lstatSync, readlinkSync } from "fs";
+import { join, resolve } from "path";
+var CAAMP_SKILL_PREFIX = "ct-";
+function isCaampOwnedSkill(skillName) {
+  return skillName.startsWith(CAAMP_SKILL_PREFIX);
+}
+async function checkSkillIntegrity(skillName, providers, scope = "global", projectDir) {
+  const lock = await readLockFile();
+  const entry = lock.skills[skillName];
+  const isCaampOwned = isCaampOwnedSkill(skillName);
+  if (!entry) {
+    const canonicalPath2 = join(getCanonicalSkillsDir(), skillName);
+    return {
+      name: skillName,
+      status: "not-tracked",
+      canonicalExists: existsSync(canonicalPath2),
+      canonicalPath: null,
+      linkStatuses: [],
+      isCaampOwned,
+      issue: "Skill is not tracked in the CAAMP lock file"
+    };
+  }
+  const canonicalPath = entry.canonicalPath;
+  const canonicalExists = existsSync(canonicalPath);
+  const linkStatuses = [];
+  for (const provider of providers) {
+    const targetDirs = resolveProviderSkillsDirs(provider, scope, projectDir);
+    for (const skillsDir of targetDirs) {
+      if (!skillsDir) continue;
+      const linkPath = join(skillsDir, skillName);
+      const exists = existsSync(linkPath);
+      let isSymlink = false;
+      let pointsToCanonical = false;
+      if (exists) {
+        try {
+          const stat = lstatSync(linkPath);
+          isSymlink = stat.isSymbolicLink();
+          if (isSymlink) {
+            const target = resolve(readlinkSync(linkPath));
+            pointsToCanonical = target === resolve(canonicalPath);
+          }
+        } catch {
+        }
+      }
+      linkStatuses.push({
+        providerId: provider.id,
+        linkPath,
+        exists,
+        isSymlink,
+        pointsToCanonical
+      });
+    }
+  }
+  if (!canonicalExists) {
+    return {
+      name: skillName,
+      status: "missing-canonical",
+      canonicalExists,
+      canonicalPath,
+      linkStatuses,
+      isCaampOwned,
+      issue: `Canonical directory missing: ${canonicalPath}`
+    };
+  }
+  const brokenLinks = linkStatuses.filter((l) => !l.exists);
+  const tamperedLinks = linkStatuses.filter((l) => l.exists && !l.pointsToCanonical);
+  if (tamperedLinks.length > 0) {
+    return {
+      name: skillName,
+      status: "tampered",
+      canonicalExists,
+      canonicalPath,
+      linkStatuses,
+      isCaampOwned,
+      issue: `${tamperedLinks.length} link(s) do not point to canonical path`
+    };
+  }
+  if (brokenLinks.length > 0) {
+    return {
+      name: skillName,
+      status: "broken-symlink",
+      canonicalExists,
+      canonicalPath,
+      linkStatuses,
+      isCaampOwned,
+      issue: `${brokenLinks.length} symlink(s) missing`
+    };
+  }
+  return {
+    name: skillName,
+    status: "intact",
+    canonicalExists,
+    canonicalPath,
+    linkStatuses,
+    isCaampOwned
+  };
+}
+async function checkAllSkillIntegrity(providers, scope = "global", projectDir) {
+  const lock = await readLockFile();
+  const results = /* @__PURE__ */ new Map();
+  for (const skillName of Object.keys(lock.skills)) {
+    const result = await checkSkillIntegrity(skillName, providers, scope, projectDir);
+    results.set(skillName, result);
+  }
+  return results;
+}
+function shouldOverrideSkill(skillName, incomingSource, existingEntry) {
+  if (!existingEntry) return true;
+  if (isCaampOwnedSkill(skillName)) {
+    if (existingEntry.sourceType === "library") return true;
+    return true;
+  }
+  return true;
+}
+async function validateInstructionIntegrity(providers, projectDir, scope, expectedContent) {
+  const { checkAllInjections: checkAllInjections2 } = await import("./injector-XGI7NNZA.js");
+  const results = await checkAllInjections2(providers, projectDir, scope, expectedContent);
+  const issues = [];
+  for (const result of results) {
+    if (result.status === "missing") {
+      issues.push({
+        file: result.file,
+        providerId: result.provider,
+        issue: "Instruction file does not exist"
+      });
+    } else if (result.status === "none") {
+      issues.push({
+        file: result.file,
+        providerId: result.provider,
+        issue: "No CAAMP injection block found"
+      });
+    } else if (result.status === "outdated") {
+      issues.push({
+        file: result.file,
+        providerId: result.provider,
+        issue: "CAAMP injection block is outdated"
+      });
+    }
+  }
+  return issues;
+}
 export {
   MarketplaceClient,
   RECOMMENDATION_ERROR_CODES,
@@ -137,9 +284,11 @@ export {
   buildSkillsMap,
   catalog_exports as catalog,
   checkAllInjections,
+  checkAllSkillIntegrity,
   checkAllSkillUpdates,
   checkCommandReachability,
   checkInjection,
+  checkSkillIntegrity,
   checkSkillUpdate,
   clearRegisteredLibrary,
   configureProviderGlobalAndProject,
@@ -150,7 +299,9 @@ export {
   detectProvider,
   discoverSkill,
   discoverSkills,
+  ensureAllProviderInstructionFiles,
   ensureDir,
+  ensureProviderInstructionFile,
   extractVersionTag,
   formatSkillRecommendations,
   generateInjectionContent,
@@ -198,6 +349,7 @@ export {
   installMcpServer,
   installMcpServerToAll,
   installSkill,
+  isCaampOwnedSkill,
   isCleoSource,
   isMarketplaceScoped,
   isQuiet,
@@ -245,9 +397,11 @@ export {
   selectProvidersByMinimumPriority,
   setQuiet,
   setVerbose,
+  shouldOverrideSkill,
   toSarif,
   tokenizeCriteriaValue,
   updateInstructionsSingleOperation,
+  validateInstructionIntegrity,
   validateRecommendationCriteria,
   validateSkill,
   writeConfig

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
+{"version":3,"sources":["../src/core/skills/integrity.ts"],"sourcesContent":["/**\n * Skill integrity checking\n *\n * Validates that installed skills have intact symlinks, correct canonical paths,\n * and enforces ct-* prefix priority for CAAMP-shipped skills.\n */\n\nimport { existsSync, lstatSync, readlinkSync } from \"node:fs\";\nimport { join, resolve } from \"node:path\";\nimport type { LockEntry, Provider } from \"../../types.js\";\nimport { getCanonicalSkillsDir, resolveProviderSkillsDirs } from \"../paths/standard.js\";\nimport { readLockFile, updateLockFile } from \"../lock-utils.js\";\n\n/** CAAMP-reserved skill prefix. Skills with this prefix are owned by CAAMP. */\nconst CAAMP_SKILL_PREFIX = \"ct-\";\n\n/**\n * Status of a single skill's integrity check.\n */\nexport type SkillIntegrityStatus =\n  | \"intact\"\n  | \"broken-symlink\"\n  | \"missing-canonical\"\n  | \"missing-link\"\n  | \"not-tracked\"\n  | \"tampered\";\n\n/**\n * Result of checking a single skill's integrity.\n */\nexport interface SkillIntegrityResult {\n  /** Skill name. */\n  name: string;\n  /** Overall integrity status. */\n  status: SkillIntegrityStatus;\n  /** Whether the canonical directory exists. */\n  canonicalExists: boolean;\n  /** Expected canonical path from lock file. */\n  canonicalPath: string | null;\n  /** Provider link statuses — which agents have valid symlinks. */\n  linkStatuses: Array<{\n    providerId: string;\n    linkPath: string;\n    exists: boolean;\n    isSymlink: boolean;\n    pointsToCanonical: boolean;\n  }>;\n  /** Whether this is a CAAMP-reserved (ct-*) skill. */\n  isCaampOwned: boolean;\n  /** Human-readable issue description, if any. */\n  issue?: string;\n}\n\n/**\n * Check whether a skill name is reserved by CAAMP (ct-* prefix).\n *\n * @param skillName - Skill name to check\n * @returns `true` if the skill name starts with `ct-`\n */\nexport function isCaampOwnedSkill(skillName: string): boolean {\n  return skillName.startsWith(CAAMP_SKILL_PREFIX);\n}\n\n/**\n * Check the integrity of a single installed skill.\n *\n * Validates:\n * - Canonical directory exists on disk\n * - Lock file entry matches actual state\n * - Symlinks from provider skill directories point to the canonical path\n *\n * @param skillName - Name of the skill to check\n * @param providers - Providers to check symlinks for\n * @param scope - Whether to check global or project links\n * @param projectDir - Project directory (for project scope)\n * @returns Integrity check result\n */\nexport async function checkSkillIntegrity(\n  skillName: string,\n  providers: Provider[],\n  scope: \"global\" | \"project\" = \"global\",\n  projectDir?: string,\n): Promise<SkillIntegrityResult> {\n  const lock = await readLockFile();\n  const entry = lock.skills[skillName];\n  const isCaampOwned = isCaampOwnedSkill(skillName);\n\n  // Not tracked in lock file\n  if (!entry) {\n    const canonicalPath = join(getCanonicalSkillsDir(), skillName);\n    return {\n      name: skillName,\n      status: \"not-tracked\",\n      canonicalExists: existsSync(canonicalPath),\n      canonicalPath: null,\n      linkStatuses: [],\n      isCaampOwned,\n      issue: \"Skill is not tracked in the CAAMP lock file\",\n    };\n  }\n\n  const canonicalPath = entry.canonicalPath;\n  const canonicalExists = existsSync(canonicalPath);\n\n  // Check symlinks for each provider\n  const linkStatuses: SkillIntegrityResult[\"linkStatuses\"] = [];\n\n  for (const provider of providers) {\n    const targetDirs = resolveProviderSkillsDirs(provider, scope, projectDir);\n    for (const skillsDir of targetDirs) {\n      if (!skillsDir) continue;\n\n      const linkPath = join(skillsDir, skillName);\n      const exists = existsSync(linkPath);\n      let isSymlink = false;\n      let pointsToCanonical = false;\n\n      if (exists) {\n        try {\n          const stat = lstatSync(linkPath);\n          isSymlink = stat.isSymbolicLink();\n          if (isSymlink) {\n            const target = resolve(readlinkSync(linkPath));\n            pointsToCanonical = target === resolve(canonicalPath);\n          }\n        } catch {\n          // Can't stat — treat as broken\n        }\n      }\n\n      linkStatuses.push({\n        providerId: provider.id,\n        linkPath,\n        exists,\n        isSymlink,\n        pointsToCanonical,\n      });\n    }\n  }\n\n  // Determine overall status\n  if (!canonicalExists) {\n    return {\n      name: skillName,\n      status: \"missing-canonical\",\n      canonicalExists,\n      canonicalPath,\n      linkStatuses,\n      isCaampOwned,\n      issue: `Canonical directory missing: ${canonicalPath}`,\n    };\n  }\n\n  const brokenLinks = linkStatuses.filter((l) => !l.exists);\n  const tamperedLinks = linkStatuses.filter((l) => l.exists && !l.pointsToCanonical);\n\n  if (tamperedLinks.length > 0) {\n    return {\n      name: skillName,\n      status: \"tampered\",\n      canonicalExists,\n      canonicalPath,\n      linkStatuses,\n      isCaampOwned,\n      issue: `${tamperedLinks.length} link(s) do not point to canonical path`,\n    };\n  }\n\n  if (brokenLinks.length > 0) {\n    return {\n      name: skillName,\n      status: \"broken-symlink\",\n      canonicalExists,\n      canonicalPath,\n      linkStatuses,\n      isCaampOwned,\n      issue: `${brokenLinks.length} symlink(s) missing`,\n    };\n  }\n\n  return {\n    name: skillName,\n    status: \"intact\",\n    canonicalExists,\n    canonicalPath,\n    linkStatuses,\n    isCaampOwned,\n  };\n}\n\n/**\n * Check integrity of all tracked skills.\n *\n * @param providers - Providers to check symlinks for\n * @param scope - Whether to check global or project links\n * @param projectDir - Project directory (for project scope)\n * @returns Map of skill name to integrity result\n */\nexport async function checkAllSkillIntegrity(\n  providers: Provider[],\n  scope: \"global\" | \"project\" = \"global\",\n  projectDir?: string,\n): Promise<Map<string, SkillIntegrityResult>> {\n  const lock = await readLockFile();\n  const results = new Map<string, SkillIntegrityResult>();\n\n  for (const skillName of Object.keys(lock.skills)) {\n    const result = await checkSkillIntegrity(skillName, providers, scope, projectDir);\n    results.set(skillName, result);\n  }\n\n  return results;\n}\n\n/**\n * Resolve a skill name conflict where a user-installed skill collides\n * with a CAAMP-owned (ct-*) skill.\n *\n * CAAMP-owned skills always win. Returns `true` if the incoming skill\n * should take precedence over the existing installation.\n *\n * @param skillName - Skill name to check\n * @param incomingSource - Source of the incoming skill installation\n * @param existingEntry - Existing lock entry, if any\n * @returns `true` if the incoming installation should proceed\n */\nexport function shouldOverrideSkill(\n  skillName: string,\n  incomingSource: string,\n  existingEntry: LockEntry | undefined,\n): boolean {\n  // No existing entry — always allow\n  if (!existingEntry) return true;\n\n  // For ct-* skills, CAAMP package source always wins\n  if (isCaampOwnedSkill(skillName)) {\n    // If incoming is from CAAMP package (library source), it always wins\n    if (existingEntry.sourceType === \"library\") return true;\n    // If existing is from CAAMP but incoming is user, CAAMP wins (block user)\n    return true;\n  }\n\n  // Non-ct-* skills: user always wins\n  return true;\n}\n\n/**\n * Validate instruction file injection status across all providers.\n *\n * Checks that CAAMP blocks exist and are current in all relevant\n * instruction files.\n *\n * @param providers - Providers to check\n * @param projectDir - Project directory\n * @param scope - Whether to check global or project files\n * @param expectedContent - Expected CAAMP block content\n * @returns Array of file paths with issues\n */\nexport async function validateInstructionIntegrity(\n  providers: Provider[],\n  projectDir: string,\n  scope: \"project\" | \"global\",\n  expectedContent?: string,\n): Promise<Array<{ file: string; providerId: string; issue: string }>> {\n  const { checkAllInjections } = await import(\"../instructions/injector.js\");\n  const results = await checkAllInjections(providers, projectDir, scope, expectedContent);\n  const issues: Array<{ file: string; providerId: string; issue: string }> = [];\n\n  for (const result of results) {\n    if (result.status === \"missing\") {\n      issues.push({\n        file: result.file,\n        providerId: result.provider,\n        issue: \"Instruction file does not exist\",\n      });\n    } else if (result.status === \"none\") {\n      issues.push({\n        file: result.file,\n        providerId: result.provider,\n        issue: \"No CAAMP injection block found\",\n      });\n    } else if (result.status === \"outdated\") {\n      issues.push({\n        file: result.file,\n        providerId: result.provider,\n        issue: \"CAAMP injection block is outdated\",\n      });\n    }\n  }\n\n  return issues;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAOA,SAAS,YAAY,WAAW,oBAAoB;AACpD,SAAS,MAAM,eAAe;AAM9B,IAAM,qBAAqB;AA6CpB,SAAS,kBAAkB,WAA4B;AAC5D,SAAO,UAAU,WAAW,kBAAkB;AAChD;AAgBA,eAAsB,oBACpB,WACA,WACA,QAA8B,UAC9B,YAC+B;AAC/B,QAAM,OAAO,MAAM,aAAa;AAChC,QAAM,QAAQ,KAAK,OAAO,SAAS;AACnC,QAAM,eAAe,kBAAkB,SAAS;AAGhD,MAAI,CAAC,OAAO;AACV,UAAMA,iBAAgB,KAAK,sBAAsB,GAAG,SAAS;AAC7D,WAAO;AAAA,MACL,MAAM;AAAA,MACN,QAAQ;AAAA,MACR,iBAAiB,WAAWA,cAAa;AAAA,MACzC,eAAe;AAAA,MACf,cAAc,CAAC;AAAA,MACf;AAAA,MACA,OAAO;AAAA,IACT;AAAA,EACF;AAEA,QAAM,gBAAgB,MAAM;AAC5B,QAAM,kBAAkB,WAAW,aAAa;AAGhD,QAAM,eAAqD,CAAC;AAE5D,aAAW,YAAY,WAAW;AAChC,UAAM,aAAa,0BAA0B,UAAU,OAAO,UAAU;AACxE,eAAW,aAAa,YAAY;AAClC,UAAI,CAAC,UAAW;AAEhB,YAAM,WAAW,KAAK,WAAW,SAAS;AAC1C,YAAM,SAAS,WAAW,QAAQ;AAClC,UAAI,YAAY;AAChB,UAAI,oBAAoB;AAExB,UAAI,QAAQ;AACV,YAAI;AACF,gBAAM,OAAO,UAAU,QAAQ;AAC/B,sBAAY,KAAK,eAAe;AAChC,cAAI,WAAW;AACb,kBAAM,SAAS,QAAQ,aAAa,QAAQ,CAAC;AAC7C,gCAAoB,WAAW,QAAQ,aAAa;AAAA,UACtD;AAAA,QACF,QAAQ;AAAA,QAER;AAAA,MACF;AAEA,mBAAa,KAAK;AAAA,QAChB,YAAY,SAAS;AAAA,QACrB;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AAGA,MAAI,CAAC,iBAAiB;AACpB,WAAO;AAAA,MACL,MAAM;AAAA,MACN,QAAQ;AAAA,MACR;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA,OAAO,gCAAgC,aAAa;AAAA,IACtD;AAAA,EACF;AAEA,QAAM,cAAc,aAAa,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM;AACxD,QAAM,gBAAgB,aAAa,OAAO,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,iBAAiB;AAEjF,MAAI,cAAc,SAAS,GAAG;AAC5B,WAAO;AAAA,MACL,MAAM;AAAA,MACN,QAAQ;AAAA,MACR;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA,OAAO,GAAG,cAAc,MAAM;AAAA,IAChC;AAAA,EACF;AAEA,MAAI,YAAY,SAAS,GAAG;AAC1B,WAAO;AAAA,MACL,MAAM;AAAA,MACN,QAAQ;AAAA,MACR;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA,OAAO,GAAG,YAAY,MAAM;AAAA,IAC9B;AAAA,EACF;AAEA,SAAO;AAAA,IACL,MAAM;AAAA,IACN,QAAQ;AAAA,IACR;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAUA,eAAsB,uBACpB,WACA,QAA8B,UAC9B,YAC4C;AAC5C,QAAM,OAAO,MAAM,aAAa;AAChC,QAAM,UAAU,oBAAI,IAAkC;AAEtD,aAAW,aAAa,OAAO,KAAK,KAAK,MAAM,GAAG;AAChD,UAAM,SAAS,MAAM,oBAAoB,WAAW,WAAW,OAAO,UAAU;AAChF,YAAQ,IAAI,WAAW,MAAM;AAAA,EAC/B;AAEA,SAAO;AACT;AAcO,SAAS,oBACd,WACA,gBACA,eACS;AAET,MAAI,CAAC,cAAe,QAAO;AAG3B,MAAI,kBAAkB,SAAS,GAAG;AAEhC,QAAI,cAAc,eAAe,UAAW,QAAO;AAEnD,WAAO;AAAA,EACT;AAGA,SAAO;AACT;AAcA,eAAsB,6BACpB,WACA,YACA,OACA,iBACqE;AACrE,QAAM,EAAE,oBAAAC,oBAAmB,IAAI,MAAM,OAAO,wBAA6B;AACzE,QAAM,UAAU,MAAMA,oBAAmB,WAAW,YAAY,OAAO,eAAe;AACtF,QAAM,SAAqE,CAAC;AAE5E,aAAW,UAAU,SAAS;AAC5B,QAAI,OAAO,WAAW,WAAW;AAC/B,aAAO,KAAK;AAAA,QACV,MAAM,OAAO;AAAA,QACb,YAAY,OAAO;AAAA,QACnB,OAAO;AAAA,MACT,CAAC;AAAA,IACH,WAAW,OAAO,WAAW,QAAQ;AACnC,aAAO,KAAK;AAAA,QACV,MAAM,OAAO;AAAA,QACb,YAAY,OAAO;AAAA,QACnB,OAAO;AAAA,MACT,CAAC;AAAA,IACH,WAAW,OAAO,WAAW,YAAY;AACvC,aAAO,KAAK;AAAA,QACV,MAAM,OAAO;AAAA,QACb,YAAY,OAAO;AAAA,QACnB,OAAO;AAAA,MACT,CAAC;AAAA,IACH;AAAA,EACF;AAEA,SAAO;AACT;","names":["canonicalPath","checkAllInjections"]}

package/dist/injector-XGI7NNZA.js

@@ -0,0 +1,19 @@
+import {
+  checkAllInjections,
+  checkInjection,
+  ensureAllProviderInstructionFiles,
+  ensureProviderInstructionFile,
+  inject,
+  injectAll,
+  removeInjection
+} from "./chunk-ZVRDBY6L.js";
+export {
+  checkAllInjections,
+  checkInjection,
+  ensureAllProviderInstructionFiles,
+  ensureProviderInstructionFile,
+  inject,
+  injectAll,
+  removeInjection
+};
+//# sourceMappingURL=injector-XGI7NNZA.js.map

package/dist/injector-XGI7NNZA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/caamp",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "Central AI Agent Managed Packages - unified provider registry and package manager for AI coding agents",
   "type": "module",
   "bin": {