@cleocode/caamp 0.2.0 → 0.3.0

package/README.md

@@ -184,6 +184,7 @@ Each provider uses a different key name for MCP server configuration:
 | Document | Description |
 |----------|-------------|
 | [API Reference](docs/API-REFERENCE.md) | Full library API (82 exports with signatures and examples) |
+| [Generated API Docs](docs/api/) | Auto-generated from TSDoc (run `npm run docs:api`) |
 | [Vision & Architecture](claudedocs/VISION.md) | Project vision, design philosophy, and architecture |
 | [Product Requirements](claudedocs/PRD.md) | Full PRD with user stories and feature requirements |
 | [Technical Specification](claudedocs/specs/CAAMP-SPEC.md) | RFC 2119 spec covering all subsystems |

package/dist/{chunk-RW745KDU.js → chunk-PCWTRJV2.js}

@@ -140,13 +140,33 @@ function getRegistryVersion() {
   return loadRegistry().version;
 }
 
+// src/core/logger.ts
+var verboseMode = false;
+var quietMode = false;
+function setVerbose(v) {
+  verboseMode = v;
+}
+function setQuiet(q) {
+  quietMode = q;
+}
+function debug(...args) {
+  if (verboseMode) console.error("[debug]", ...args);
+}
+function isVerbose() {
+  return verboseMode;
+}
+function isQuiet() {
+  return quietMode;
+}
+
 // src/core/registry/detection.ts
 import { existsSync as existsSync2 } from "fs";
 import { execFileSync } from "child_process";
 import { join as join2 } from "path";
 function checkBinary(binary) {
   try {
-    execFileSync("which", [binary], { stdio: "pipe" });
+    const cmd = process.platform === "win32" ? "where" : "which";
+    execFileSync(cmd, [binary], { stdio: "pipe" });
     return true;
   } catch {
     return false;
@@ -171,10 +191,12 @@ function checkFlatpak(flatpakId) {
 function detectProvider(provider) {
   const matchedMethods = [];
   const detection = provider.detection;
+  debug(`detecting provider ${provider.id} via methods: ${detection.methods.join(", ")}`);
   for (const method of detection.methods) {
     switch (method) {
       case "binary":
         if (detection.binary && checkBinary(detection.binary)) {
+          debug(`  ${provider.id}: binary "${detection.binary}" found`);
           matchedMethods.push("binary");
         }
         break;
@@ -444,7 +466,7 @@ async function listCanonicalSkills() {
   return entries.filter((e) => e.isDirectory() || e.isSymbolicLink()).map((e) => e.name);
 }
 
-// src/core/mcp/lock.ts
+// src/core/lock-utils.ts
 import { readFile as readFile2, writeFile as writeFile2, mkdir as mkdir2 } from "fs/promises";
 import { existsSync as existsSync4 } from "fs";
 import { homedir as homedir3 } from "os";
@@ -466,55 +488,9 @@ async function writeLockFile(lock) {
   await mkdir2(LOCK_DIR, { recursive: true });
   await writeFile2(LOCK_FILE, JSON.stringify(lock, null, 2) + "\n", "utf-8");
 }
-async function recordMcpInstall(serverName, source, sourceType, agents, isGlobal) {
-  const lock = await readLockFile();
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  const existing = lock.mcpServers[serverName];
-  lock.mcpServers[serverName] = {
-    name: serverName,
-    scopedName: serverName,
-    source,
-    sourceType,
-    installedAt: existing?.installedAt ?? now,
-    updatedAt: now,
-    agents: [.../* @__PURE__ */ new Set([...existing?.agents ?? [], ...agents])],
-    canonicalPath: "",
-    isGlobal
-  };
-  await writeLockFile(lock);
-}
-async function removeMcpFromLock(serverName) {
-  const lock = await readLockFile();
-  if (!(serverName in lock.mcpServers)) return false;
-  delete lock.mcpServers[serverName];
-  await writeLockFile(lock);
-  return true;
-}
-async function getTrackedMcpServers() {
-  const lock = await readLockFile();
-  return lock.mcpServers;
-}
-async function saveLastSelectedAgents(agents) {
-  const lock = await readLockFile();
-  lock.lastSelectedAgents = agents;
-  await writeLockFile(lock);
-}
-async function getLastSelectedAgents() {
-  const lock = await readLockFile();
-  return lock.lastSelectedAgents;
-}
 
 // src/core/skills/lock.ts
 import { simpleGit } from "simple-git";
-import { writeFile as writeFile3, mkdir as mkdir3 } from "fs/promises";
-import { homedir as homedir4 } from "os";
-import { join as join5 } from "path";
-var LOCK_DIR2 = join5(homedir4(), ".agents");
-var LOCK_FILE2 = join5(LOCK_DIR2, ".caamp-lock.json");
-async function writeLockFile2(lock) {
-  await mkdir3(LOCK_DIR2, { recursive: true });
-  await writeFile3(LOCK_FILE2, JSON.stringify(lock, null, 2) + "\n", "utf-8");
-}
 async function recordSkillInstall(skillName, scopedName, source, sourceType, agents, canonicalPath, isGlobal, projectDir, version) {
   const lock = await readLockFile();
   const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -532,13 +508,13 @@ async function recordSkillInstall(skillName, scopedName, source, sourceType, age
     isGlobal,
     projectDir
   };
-  await writeLockFile2(lock);
+  await writeLockFile(lock);
 }
 async function removeSkillFromLock(skillName) {
   const lock = await readLockFile();
   if (!(skillName in lock.skills)) return false;
   delete lock.skills[skillName];
-  await writeLockFile2(lock);
+  await writeLockFile(lock);
   return true;
 }
 async function getTrackedSkills() {
@@ -691,13 +667,42 @@ var SkillsShAdapter = class {
 // src/core/marketplace/client.ts
 var MarketplaceClient = class {
   adapters;
+  /**
+   * Create a new marketplace client.
+   *
+   * @param adapters - Custom marketplace adapters (defaults to agentskills.in and skills.sh)
+   *
+   * @example
+   * ```typescript
+   * // Use default adapters
+   * const client = new MarketplaceClient();
+   *
+   * // Use custom adapters
+   * const client = new MarketplaceClient([myAdapter]);
+   * ```
+   */
   constructor(adapters) {
     this.adapters = adapters ?? [
       new SkillsMPAdapter(),
       new SkillsShAdapter()
     ];
   }
-  /** Search all marketplaces and deduplicate results */
+  /**
+   * Search all marketplaces and return deduplicated, sorted results.
+   *
+   * Queries all adapters in parallel and deduplicates by `scopedName`,
+   * keeping the entry with the highest star count. Results are sorted by
+   * stars descending.
+   *
+   * @param query - Search query string
+   * @param limit - Maximum number of results to return (default: 20)
+   * @returns Deduplicated and sorted marketplace results
+   *
+   * @example
+   * ```typescript
+   * const results = await client.search("code review", 10);
+   * ```
+   */
   async search(query, limit = 20) {
     const promises = this.adapters.map(
       (adapter) => adapter.search(query, limit).catch(() => [])
@@ -715,7 +720,19 @@ var MarketplaceClient = class {
     deduplicated.sort((a, b) => b.stars - a.stars);
     return deduplicated.slice(0, limit);
   }
-  /** Get a specific skill by scoped name */
+  /**
+   * Get a specific skill by its scoped name from any marketplace.
+   *
+   * Tries each adapter in order and returns the first match.
+   *
+   * @param scopedName - Scoped skill name (e.g. `"@author/my-skill"`)
+   * @returns The marketplace result, or `null` if not found in any marketplace
+   *
+   * @example
+   * ```typescript
+   * const skill = await client.getSkill("@anthropic/memory");
+   * ```
+   */
   async getSkill(scopedName) {
     for (const adapter of this.adapters) {
       const result = await adapter.getSkill(scopedName).catch(() => null);
@@ -728,7 +745,7 @@ var MarketplaceClient = class {
 // src/core/skills/discovery.ts
 import { readFile as readFile3, readdir } from "fs/promises";
 import { existsSync as existsSync5 } from "fs";
-import { join as join6 } from "path";
+import { join as join5 } from "path";
 import matter from "gray-matter";
 async function parseSkillFile(filePath) {
   try {
@@ -752,7 +769,7 @@ async function parseSkillFile(filePath) {
   }
 }
 async function discoverSkill(skillDir) {
-  const skillFile = join6(skillDir, "SKILL.md");
+  const skillFile = join5(skillDir, "SKILL.md");
   if (!existsSync5(skillFile)) return null;
   const metadata = await parseSkillFile(skillFile);
   if (!metadata) return null;
@@ -769,7 +786,7 @@ async function discoverSkills(rootDir) {
   const skills = [];
   for (const entry of entries) {
     if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
-    const skillDir = join6(rootDir, entry.name);
+    const skillDir = join5(rootDir, entry.name);
     const skill = await discoverSkill(skillDir);
     if (skill) {
       skills.push(skill);
@@ -1205,13 +1222,13 @@ async function scanFile(filePath, rules) {
 }
 async function scanDirectory(dirPath) {
   const { readdir: readdir2 } = await import("fs/promises");
-  const { join: join9 } = await import("path");
+  const { join: join8 } = await import("path");
   if (!existsSync6(dirPath)) return [];
   const entries = await readdir2(dirPath, { withFileTypes: true });
   const results = [];
   for (const entry of entries) {
     if (entry.isDirectory() || entry.isSymbolicLink()) {
-      const skillFile = join9(dirPath, entry.name, "SKILL.md");
+      const skillFile = join8(dirPath, entry.name, "SKILL.md");
       if (existsSync6(skillFile)) {
         results.push(await scanFile(skillFile));
       }
@@ -1425,13 +1442,13 @@ function getNestedValue(obj, keyPath) {
   return current;
 }
 async function ensureDir(filePath) {
-  const { mkdir: mkdir5 } = await import("fs/promises");
-  const { dirname: dirname5 } = await import("path");
-  await mkdir5(dirname5(filePath), { recursive: true });
+  const { mkdir: mkdir4 } = await import("fs/promises");
+  const { dirname: dirname4 } = await import("path");
+  await mkdir4(dirname4(filePath), { recursive: true });
 }
 
 // src/core/formats/json.ts
-import { readFile as readFile6, writeFile as writeFile4 } from "fs/promises";
+import { readFile as readFile6, writeFile as writeFile3 } from "fs/promises";
 import { existsSync as existsSync8 } from "fs";
 import * as jsonc from "jsonc-parser";
 async function readJsonConfig(filePath) {
@@ -1485,7 +1502,7 @@ async function writeJsonConfig(filePath, configKey, serverName, serverConfig) {
   if (!content.endsWith("\n")) {
     content += "\n";
   }
-  await writeFile4(filePath, content, "utf-8");
+  await writeFile3(filePath, content, "utf-8");
 }
 async function removeJsonConfig(filePath, configKey, serverName) {
   if (!existsSync8(filePath)) return false;
@@ -1505,12 +1522,12 @@ async function removeJsonConfig(filePath, configKey, serverName) {
   if (!content.endsWith("\n")) {
     content += "\n";
   }
-  await writeFile4(filePath, content, "utf-8");
+  await writeFile3(filePath, content, "utf-8");
   return true;
 }
 
 // src/core/formats/yaml.ts
-import { readFile as readFile7, writeFile as writeFile5 } from "fs/promises";
+import { readFile as readFile7, writeFile as writeFile4 } from "fs/promises";
 import { existsSync as existsSync9 } from "fs";
 import yaml from "js-yaml";
 async function readYamlConfig(filePath) {
@@ -1535,7 +1552,7 @@ async function writeYamlConfig(filePath, configKey, serverName, serverConfig) {
     noRefs: true,
     sortKeys: false
   });
-  await writeFile5(filePath, content, "utf-8");
+  await writeFile4(filePath, content, "utf-8");
 }
 async function removeYamlConfig(filePath, configKey, serverName) {
   if (!existsSync9(filePath)) return false;
@@ -1555,12 +1572,12 @@ async function removeYamlConfig(filePath, configKey, serverName) {
     noRefs: true,
     sortKeys: false
   });
-  await writeFile5(filePath, content, "utf-8");
+  await writeFile4(filePath, content, "utf-8");
   return true;
 }
 
 // src/core/formats/toml.ts
-import { readFile as readFile8, writeFile as writeFile6 } from "fs/promises";
+import { readFile as readFile8, writeFile as writeFile5 } from "fs/promises";
 import { existsSync as existsSync10 } from "fs";
 import TOML from "@iarna/toml";
 async function readTomlConfig(filePath) {
@@ -1580,7 +1597,7 @@ async function writeTomlConfig(filePath, configKey, serverName, serverConfig) {
   }
   const merged = deepMerge(existing, newEntry);
   const content = TOML.stringify(merged);
-  await writeFile6(filePath, content, "utf-8");
+  await writeFile5(filePath, content, "utf-8");
 }
 async function removeTomlConfig(filePath, configKey, serverName) {
   if (!existsSync10(filePath)) return false;
@@ -1595,12 +1612,13 @@ async function removeTomlConfig(filePath, configKey, serverName) {
   if (!(serverName in current)) return false;
   delete current[serverName];
   const content = TOML.stringify(existing);
-  await writeFile6(filePath, content, "utf-8");
+  await writeFile5(filePath, content, "utf-8");
   return true;
 }
 
 // src/core/formats/index.ts
 async function readConfig(filePath, format) {
+  debug(`reading config: ${filePath} (format: ${format})`);
   switch (format) {
     case "json":
     case "jsonc":
@@ -1614,6 +1632,7 @@ async function readConfig(filePath, format) {
   }
 }
 async function writeConfig(filePath, format, key, serverName, serverConfig) {
+  debug(`writing config: ${filePath} (format: ${format}, key: ${key}, server: ${serverName})`);
   switch (format) {
     case "json":
     case "jsonc":
@@ -1737,17 +1756,18 @@ function getTransform(providerId) {
 }
 
 // src/core/mcp/reader.ts
-import { join as join7 } from "path";
+import { join as join6 } from "path";
 import { existsSync as existsSync11 } from "fs";
 function resolveConfigPath(provider, scope, projectDir) {
   if (scope === "project") {
     if (!provider.configPathProject) return null;
-    return join7(projectDir ?? process.cwd(), provider.configPathProject);
+    return join6(projectDir ?? process.cwd(), provider.configPathProject);
   }
   return provider.configPathGlobal;
 }
 async function listMcpServers(provider, scope, projectDir) {
   const configPath = resolveConfigPath(provider, scope, projectDir);
+  debug(`listing MCP servers for ${provider.id} (${scope}) at ${configPath ?? "(none)"}`);
   if (!configPath || !existsSync11(configPath)) return [];
   try {
     const config = await readConfig(configPath, provider.configFormat);
@@ -1797,6 +1817,8 @@ function buildConfig(provider, serverName, config) {
 }
 async function installMcpServer(provider, serverName, config, scope = "project", projectDir) {
   const configPath = resolveConfigPath(provider, scope, projectDir);
+  debug(`installing MCP server "${serverName}" for ${provider.id} (${scope})`);
+  debug(`  config path: ${configPath ?? "(none)"}`);
   if (!configPath) {
     return {
       provider,
@@ -1808,6 +1830,8 @@ async function installMcpServer(provider, serverName, config, scope = "project",
   }
   try {
     const transformedConfig = buildConfig(provider, serverName, config);
+    const transform = getTransform(provider.id);
+    debug(`  transform applied: ${transform ? "yes" : "no"}`);
     await writeConfig(
       configPath,
       provider.configFormat,
@@ -1860,11 +1884,50 @@ function buildServerConfig(source, transport, headers) {
   };
 }
 
+// src/core/mcp/lock.ts
+async function recordMcpInstall(serverName, source, sourceType, agents, isGlobal) {
+  const lock = await readLockFile();
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const existing = lock.mcpServers[serverName];
+  lock.mcpServers[serverName] = {
+    name: serverName,
+    scopedName: serverName,
+    source,
+    sourceType,
+    installedAt: existing?.installedAt ?? now,
+    updatedAt: now,
+    agents: [.../* @__PURE__ */ new Set([...existing?.agents ?? [], ...agents])],
+    canonicalPath: "",
+    isGlobal
+  };
+  await writeLockFile(lock);
+}
+async function removeMcpFromLock(serverName) {
+  const lock = await readLockFile();
+  if (!(serverName in lock.mcpServers)) return false;
+  delete lock.mcpServers[serverName];
+  await writeLockFile(lock);
+  return true;
+}
+async function getTrackedMcpServers() {
+  const lock = await readLockFile();
+  return lock.mcpServers;
+}
+async function saveLastSelectedAgents(agents) {
+  const lock = await readLockFile();
+  lock.lastSelectedAgents = agents;
+  await writeLockFile(lock);
+}
+async function getLastSelectedAgents() {
+  const lock = await readLockFile();
+  return lock.lastSelectedAgents;
+}
+
 // src/core/instructions/injector.ts
-import { readFile as readFile9, writeFile as writeFile7 } from "fs/promises";
+import { readFile as readFile9, writeFile as writeFile6 } from "fs/promises";
 import { existsSync as existsSync12 } from "fs";
-import { join as join8, dirname as dirname4 } from "path";
-import { mkdir as mkdir4 } from "fs/promises";
+import { join as join7, dirname as dirname3 } from "path";
+import { mkdir as mkdir3 } from "fs/promises";
 var MARKER_START = "<!-- CAAMP:START -->";
 var MARKER_END = "<!-- CAAMP:END -->";
 var MARKER_PATTERN = /<!-- CAAMP:START -->[\s\S]*?<!-- CAAMP:END -->/;
@@ -1893,19 +1956,19 @@ ${MARKER_END}`;
 }
 async function inject(filePath, content) {
   const block = buildBlock(content);
-  await mkdir4(dirname4(filePath), { recursive: true });
+  await mkdir3(dirname3(filePath), { recursive: true });
   if (!existsSync12(filePath)) {
-    await writeFile7(filePath, block + "\n", "utf-8");
+    await writeFile6(filePath, block + "\n", "utf-8");
     return "created";
   }
   const existing = await readFile9(filePath, "utf-8");
   if (MARKER_PATTERN.test(existing)) {
     const updated2 = existing.replace(MARKER_PATTERN, block);
-    await writeFile7(filePath, updated2, "utf-8");
+    await writeFile6(filePath, updated2, "utf-8");
     return "updated";
   }
   const updated = block + "\n\n" + existing;
-  await writeFile7(filePath, updated, "utf-8");
+  await writeFile6(filePath, updated, "utf-8");
   return "added";
 }
 async function removeInjection(filePath) {
@@ -1917,7 +1980,7 @@ async function removeInjection(filePath) {
     const { rm: rm2 } = await import("fs/promises");
     await rm2(filePath);
   } else {
-    await writeFile7(filePath, cleaned + "\n", "utf-8");
+    await writeFile6(filePath, cleaned + "\n", "utf-8");
   }
   return true;
 }
@@ -1925,7 +1988,7 @@ async function checkAllInjections(providers, projectDir, scope, expectedContent)
   const results = [];
   const checked = /* @__PURE__ */ new Set();
   for (const provider of providers) {
-    const filePath = scope === "global" ? join8(provider.pathGlobal, provider.instructFile) : join8(projectDir, provider.instructFile);
+    const filePath = scope === "global" ? join7(provider.pathGlobal, provider.instructFile) : join7(projectDir, provider.instructFile);
     if (checked.has(filePath)) continue;
     checked.add(filePath);
     const status = await checkInjection(filePath, expectedContent);
@@ -1942,7 +2005,7 @@ async function injectAll(providers, projectDir, scope, content) {
   const results = /* @__PURE__ */ new Map();
   const injected = /* @__PURE__ */ new Set();
   for (const provider of providers) {
-    const filePath = scope === "global" ? join8(provider.pathGlobal, provider.instructFile) : join8(projectDir, provider.instructFile);
+    const filePath = scope === "global" ? join7(provider.pathGlobal, provider.instructFile) : join7(projectDir, provider.instructFile);
     if (injected.has(filePath)) continue;
     injected.add(filePath);
     const action = await inject(filePath, content);
@@ -1989,6 +2052,10 @@ export {
   getInstructionFiles,
   getProviderCount,
   getRegistryVersion,
+  setVerbose,
+  setQuiet,
+  isVerbose,
+  isQuiet,
   detectProvider,
   detectAllProviders,
   getInstalledProviders,
@@ -1999,11 +2066,6 @@ export {
   removeSkill,
   listCanonicalSkills,
   readLockFile,
-  recordMcpInstall,
-  removeMcpFromLock,
-  getTrackedMcpServers,
-  saveLastSelectedAgents,
-  getLastSelectedAgents,
   recordSkillInstall,
   removeSkillFromLock,
   getTrackedSkills,
@@ -2031,6 +2093,11 @@ export {
   installMcpServer,
   installMcpServerToAll,
   buildServerConfig,
+  recordMcpInstall,
+  removeMcpFromLock,
+  getTrackedMcpServers,
+  saveLastSelectedAgents,
+  getLastSelectedAgents,
   checkInjection,
   inject,
   removeInjection,
@@ -2039,4 +2106,4 @@ export {
   generateInjectionContent,
   groupByInstructFile
 };
-//# sourceMappingURL=chunk-RW745KDU.js.map
+//# sourceMappingURL=chunk-PCWTRJV2.js.map