@cleocode/caamp 0.4.0 → 0.4.1

package/dist/index.d.ts

@@ -34,7 +34,7 @@ type TransportType = "stdio" | "sse" | "http";
  *
  * - `"binary"` - Check if a CLI binary exists on PATH
  * - `"directory"` - Check if known config/data directories exist
- * - `"appBundle"` - Check for macOS .app bundle in /Applications
+ * - `"appBundle"` - Check for macOS .app bundle in standard app directories
  * - `"flatpak"` - Check for Flatpak installation on Linux
  */
 type DetectionMethod = "binary" | "directory" | "appBundle" | "flatpak";
@@ -245,10 +245,13 @@ interface SkillMetadata {
  *
  * @example
  * ```typescript
+ * import { getCanonicalSkillsDir } from "./core/paths/standard.js";
+ * import { join } from "node:path";
+ *
  * const entry: SkillEntry = {
  *   name: "my-skill",
  *   scopedName: "my-skill",
- *   path: "/home/user/.agents/skills/my-skill",
+ *   path: join(getCanonicalSkillsDir(), "my-skill"),
  *   metadata: { name: "my-skill", description: "A skill" },
  * };
  * ```
@@ -270,6 +273,9 @@ interface SkillEntry {
  *
  * @example
  * ```typescript
+ * import { getCanonicalSkillsDir } from "./core/paths/standard.js";
+ * import { join } from "node:path";
+ *
  * const entry: LockEntry = {
  *   name: "my-skill",
  *   scopedName: "my-skill",
@@ -277,7 +283,7 @@ interface SkillEntry {
  *   sourceType: "github",
  *   installedAt: "2025-01-15T10:30:00.000Z",
  *   agents: ["claude-code", "cursor"],
- *   canonicalPath: "/home/user/.agents/skills/my-skill",
+ *   canonicalPath: join(getCanonicalSkillsDir(), "my-skill"),
  *   isGlobal: true,
  * };
  * ```
@@ -307,7 +313,7 @@ interface LockEntry {
     projectDir?: string;
 }
 /**
- * The CAAMP lock file structure, stored at `~/.agents/.caamp-lock.json`.
+ * The CAAMP lock file structure, stored at the resolved canonical lock path.
  *
  * Tracks all installed skills and MCP servers along with their sources,
  * versions, and linked agents.
@@ -532,7 +538,7 @@ interface InjectionCheckResult {
  *   providerId: "claude-code",
  *   providerName: "Claude Code",
  *   scope: "project",
- *   configPath: "/project/.claude/settings.json",
+ *   configPath: "/project/<provider-project-config>",
  *   config: { command: "npx", args: ["-y", "@mcp/server-filesystem"] },
  * };
  * ```
@@ -610,6 +616,10 @@ interface DetectionResult {
     /** Whether the provider has project-level config in the current directory. */
     projectDetected: boolean;
 }
+interface DetectionCacheOptions {
+    forceRefresh?: boolean;
+    ttlMs?: number;
+}
 /**
  * Detect if a single provider is installed on the system.
  *
@@ -643,7 +653,7 @@ declare function detectProvider(provider: Provider): DetectionResult;
  * console.log(`${installed.length} agents detected`);
  * ```
  */
-declare function detectAllProviders(): DetectionResult[];
+declare function detectAllProviders(options?: DetectionCacheOptions): DetectionResult[];
 /**
  * Get only providers that are currently installed on the system.
  *
@@ -658,7 +668,7 @@ declare function detectAllProviders(): DetectionResult[];
  * console.log(installed.map(p => p.toolName).join(", "));
  * ```
  */
-declare function getInstalledProviders(): Provider[];
+declare function getInstalledProviders(options?: DetectionCacheOptions): Provider[];
 /**
  * Detect all providers and enrich results with project-level presence.
  *
@@ -678,7 +688,8 @@ declare function getInstalledProviders(): Provider[];
  * }
  * ```
  */
-declare function detectProjectProviders(projectDir: string): DetectionResult[];
+declare function detectProjectProviders(projectDir: string, options?: DetectionCacheOptions): DetectionResult[];
+declare function resetDetectionCache(): void;
 
 /**
  * MCP config installer
@@ -814,7 +825,7 @@ interface SkillInstallResult {
 /**
  * Install a skill from a local path to the canonical location and link to agents.
  *
- * Copies the skill directory to `~/.agents/skills/<name>/` and creates symlinks
+ * Copies the skill directory to the canonical skills directory and creates symlinks
  * (or copies on Windows) from each provider's skills directory to the canonical path.
  *
  * @param sourcePath - Local path to the skill directory to install
@@ -834,7 +845,7 @@ declare function installSkill(sourcePath: string, skillName: string, providers:
  * Remove a skill from the canonical location and all agent symlinks.
  *
  * Removes symlinks from each provider's skills directory and then removes the
- * canonical copy from `~/.agents/skills/<name>/`.
+ * canonical copy from the centralized canonical skills directory.
  *
  * @param skillName - Name of the skill to remove
  * @param providers - Providers to unlink the skill from
@@ -852,7 +863,7 @@ declare function removeSkill(skillName: string, providers: Provider[], isGlobal:
     errors: string[];
 }>;
 /**
- * List all skills installed in the canonical directory (`~/.agents/skills/`).
+ * List all skills installed in the canonical skills directory.
  *
  * Returns the directory names of all skills, which correspond to skill names.
  *
@@ -1315,6 +1326,21 @@ declare function getProviderCount(): number;
  */
 declare function getRegistryVersion(): string;
 
+interface PlatformLocations {
+    home: string;
+    config: string;
+    vscodeConfig: string;
+    zedConfig: string;
+    claudeDesktopConfig: string;
+    applications: string[];
+}
+declare function getPlatformLocations(): PlatformLocations;
+declare function getAgentsHome(): string;
+declare function getProjectAgentsDir(projectRoot?: string): string;
+declare function getCanonicalSkillsDir(): string;
+declare function getLockFilePath(): string;
+declare function resolveRegistryTemplatePath(template: string): string;
+
 /**
  * Source URL/path classifier
  *
@@ -1395,7 +1421,10 @@ declare function parseSkillFile(filePath: string): Promise<SkillMetadata | null>
  *
  * @example
  * ```typescript
- * const skill = await discoverSkill("/home/user/.agents/skills/my-skill");
+ * import { getCanonicalSkillsDir } from "../paths/standard.js";
+ * import { join } from "node:path";
+ *
+ * const skill = await discoverSkill(join(getCanonicalSkillsDir(), "my-skill"));
  * if (skill) {
  *   console.log(`Found: ${skill.name}`);
  * }
@@ -1413,7 +1442,9 @@ declare function discoverSkill(skillDir: string): Promise<SkillEntry | null>;
  *
  * @example
  * ```typescript
- * const skills = await discoverSkills("/home/user/.agents/skills");
+ * import { getCanonicalSkillsDir } from "../paths/standard.js";
+ *
+ * const skills = await discoverSkills(getCanonicalSkillsDir());
  * console.log(`Found ${skills.length} skills`);
  * ```
  */
@@ -1467,7 +1498,9 @@ declare function scanFile(filePath: string, rules?: AuditRule[]): Promise<AuditR
  *
  * @example
  * ```typescript
- * const results = await scanDirectory("/home/user/.agents/skills");
+ * import { getCanonicalSkillsDir } from "../../paths/standard.js";
+ *
+ * const results = await scanDirectory(getCanonicalSkillsDir());
  * const failing = results.filter(r => !r.passed);
  * ```
  */
@@ -1538,7 +1571,7 @@ declare function getTransform(providerId: string): ((name: string, config: McpSe
  * @example
  * ```typescript
  * const path = resolveConfigPath(provider, "project", "/home/user/my-project");
- * // "/home/user/my-project/.claude/settings.json"
+ * // Returns provider-specific project config path
  * ```
  */
 declare function resolveConfigPath(provider: Provider, scope: "project" | "global", projectDir?: string): string | null;
@@ -1598,7 +1631,7 @@ declare function removeMcpServer(provider: Provider, serverName: string, scope:
 /**
  * Shared lock file utilities
  *
- * Single source of truth for reading/writing ~/.agents/.caamp-lock.json.
+ * Single source of truth for reading/writing the canonical CAAMP lock file path.
  * Both MCP and skills lock modules import from here.
  */
 
@@ -1609,7 +1642,7 @@ declare function readLockFile(): Promise<CaampLockFile>;
  * MCP lock file management
  *
  * Tracks installed MCP servers with source and agent metadata.
- * Stored at ~/.agents/.caamp-lock.json (shared with skills lock).
+ * Stored in the canonical CAAMP lock file (shared with skills lock).
  */
 
 /**
@@ -1685,7 +1718,7 @@ declare function getLastSelectedAgents(): Promise<string[] | undefined>;
 /**
  * Skills lock file management
  *
- * Shares the same lock file as MCP (~/.agents/.caamp-lock.json).
+ * Shares the same canonical lock file as MCP.
  */
 
 /**
@@ -1706,9 +1739,12 @@ declare function getLastSelectedAgents(): Promise<string[] | undefined>;
  *
  * @example
  * ```typescript
+ * import { getCanonicalSkillsDir } from "../paths/standard.js";
+ * import { join } from "node:path";
+ *
  * await recordSkillInstall(
  *   "my-skill", "my-skill", "owner/repo", "github",
- *   ["claude-code"], "/home/user/.agents/skills/my-skill", true,
+ *   ["claude-code"], join(getCanonicalSkillsDir(), "my-skill"), true,
  * );
  * ```
  */
@@ -2147,4 +2183,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 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 };
+export { type AuditFinding, type AuditResult, type AuditRule, type AuditSeverity, type BatchInstallOptions, type BatchInstallResult, type CaampLockFile, type ConfigFormat, type ConflictPolicy, type DetectionCacheOptions, 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, getAgentsHome, getAllProviders, getCanonicalSkillsDir, getInstalledProviders, getInstructionFiles, getLastSelectedAgents, getLockFilePath, getNestedValue, getPlatformLocations, getProjectAgentsDir, 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, resetDetectionCache, resolveAlias, resolveConfigPath, resolveRegistryTemplatePath, saveLastSelectedAgents, scanDirectory, scanFile, scoreSkillRecommendation, searchSkills, selectProvidersByMinimumPriority, setQuiet, setVerbose, toSarif, tokenizeCriteriaValue, updateInstructionsSingleOperation, validateRecommendationCriteria, validateSkill, writeConfig };

package/dist/index.js

@@ -17,11 +17,16 @@ import {
   ensureDir,
   formatSkillRecommendations,
   generateInjectionContent,
+  getAgentsHome,
   getAllProviders,
+  getCanonicalSkillsDir,
   getInstalledProviders,
   getInstructionFiles,
   getLastSelectedAgents,
+  getLockFilePath,
   getNestedValue,
+  getPlatformLocations,
+  getProjectAgentsDir,
   getProvider,
   getProviderCount,
   getProvidersByInstructFile,
@@ -59,8 +64,10 @@ import {
   removeMcpServer,
   removeSkill,
   removeSkillFromLock,
+  resetDetectionCache,
   resolveAlias,
   resolveConfigPath,
+  resolveRegistryTemplatePath,
   saveLastSelectedAgents,
   scanDirectory,
   scanFile,
@@ -75,7 +82,7 @@ import {
   validateRecommendationCriteria,
   validateSkill,
   writeConfig
-} from "./chunk-ZYINKJDE.js";
+} from "./chunk-6HQDRJLS.js";
 export {
   MarketplaceClient,
   RECOMMENDATION_ERROR_CODES,
@@ -95,11 +102,16 @@ export {
   ensureDir,
   formatSkillRecommendations,
   generateInjectionContent,
+  getAgentsHome,
   getAllProviders,
+  getCanonicalSkillsDir,
   getInstalledProviders,
   getInstructionFiles,
   getLastSelectedAgents,
+  getLockFilePath,
   getNestedValue,
+  getPlatformLocations,
+  getProjectAgentsDir,
   getProvider,
   getProviderCount,
   getProvidersByInstructFile,
@@ -137,8 +149,10 @@ export {
   removeMcpServer,
   removeSkill,
   removeSkillFromLock,
+  resetDetectionCache,
   resolveAlias,
   resolveConfigPath,
+  resolveRegistryTemplatePath,
   saveLastSelectedAgents,
   scanDirectory,
   scanFile,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/caamp",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Central AI Agent Managed Packages - unified provider registry and package manager for AI coding agents",
   "type": "module",
   "bin": {
@@ -24,9 +24,11 @@
     "build": "tsup",
     "dev": "tsx src/cli.ts",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "lint": "tsc --noEmit",
+    "lint": "biome lint src tests",
+    "lint:fix": "biome lint --write src tests",
     "docs:api": "typedoc",
     "docs:api:check": "typedoc --emit none",
     "prepublishOnly": "npm run build"
@@ -46,7 +48,6 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@clack/prompts": "^1.0.0",
     "@cleocode/lafs-protocol": "^0.1.1",
     "@iarna/toml": "^2.2.5",
     "commander": "^14.0.0",
@@ -57,8 +58,10 @@
     "simple-git": "^3.30.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.3.14",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
     "tsup": "^8.5.0",
     "tsx": "^4.21.0",
     "typedoc": "^0.28.16",