@cleocode/caamp 0.3.0 → 0.4.0

package/dist/cli.js

@@ -1,12 +1,18 @@
 #!/usr/bin/env node
 import {
   MarketplaceClient,
+  RECOMMENDATION_ERROR_CODES,
+  applyMcpInstallWithPolicy,
   buildServerConfig,
   checkAllInjections,
   checkSkillUpdate,
+  configureProviderGlobalAndProject,
   detectAllProviders,
+  detectMcpConfigConflicts,
   detectProjectProviders,
   discoverSkillsMulti,
+  formatNetworkError,
+  formatSkillRecommendations,
   generateInjectionContent,
   getAllProviders,
   getInstalledProviders,
@@ -17,6 +23,7 @@ import {
   getTrackedSkills,
   groupByInstructFile,
   injectAll,
+  installBatchWithRollback,
   installMcpServerToAll,
   installSkill,
   isMarketplaceScoped,
@@ -25,6 +32,7 @@ import {
   parseSource,
   readConfig,
   readLockFile,
+  recommendSkills,
   recordMcpInstall,
   recordSkillInstall,
   removeMcpFromLock,
@@ -34,11 +42,14 @@ import {
   resolveConfigPath,
   scanDirectory,
   scanFile,
+  selectProvidersByMinimumPriority,
   setQuiet,
   setVerbose,
   toSarif,
+  tokenizeCriteriaValue,
+  updateInstructionsSingleOperation,
   validateSkill
-} from "./chunk-PCWTRJV2.js";
+} from "./chunk-ZYINKJDE.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -137,6 +148,7 @@ ${provider.toolName}`));
 }
 
 // src/commands/skills/install.ts
+import { existsSync } from "fs";
 import pc2 from "picocolors";
 
 // src/core/sources/github.ts
@@ -192,6 +204,28 @@ async function cloneGitLabRepo(owner, repo, ref, subPath) {
 }
 
 // src/commands/skills/install.ts
+function normalizeSkillSubPath(path) {
+  if (!path) return void 0;
+  const normalized = path.replace(/\\/g, "/").replace(/^\/+/, "").replace(/\/SKILL\.md$/i, "").trim();
+  return normalized.length > 0 ? normalized : void 0;
+}
+function marketplacePathCandidates(skillPath, parsedPath) {
+  const candidates = [];
+  const base = normalizeSkillSubPath(skillPath);
+  const parsed = normalizeSkillSubPath(parsedPath);
+  if (base) candidates.push(base);
+  if (parsed) candidates.push(parsed);
+  if (base && base.startsWith("skills/") && !base.startsWith(".claude/")) {
+    candidates.push(`.claude/${base}`);
+  }
+  if (parsed && parsed.startsWith("skills/") && !parsed.startsWith(".claude/")) {
+    candidates.push(`.claude/${parsed}`);
+  }
+  if (candidates.length === 0) {
+    candidates.push(void 0);
+  }
+  return Array.from(new Set(candidates));
+}
 function registerSkillsInstall(parent) {
   parent.command("install").description("Install a skill from GitHub, URL, or marketplace").argument("<source>", "Skill source (GitHub URL, owner/repo, @author/name)").option("-a, --agent <name>", "Target specific agent(s)", (v, prev) => [...prev, v], []).option("-g, --global", "Install globally").option("-y, --yes", "Skip confirmation").option("--all", "Install to all detected agents").action(async (source, opts) => {
     let providers;
@@ -215,7 +249,13 @@ function registerSkillsInstall(parent) {
     if (isMarketplaceScoped(source)) {
       console.log(pc2.dim(`Searching marketplace for ${source}...`));
       const client = new MarketplaceClient();
-      const skill = await client.getSkill(source);
+      let skill;
+      try {
+        skill = await client.getSkill(source);
+      } catch (error) {
+        console.error(pc2.red(`Marketplace lookup failed: ${formatNetworkError(error)}`));
+        process.exit(1);
+      }
       if (!skill) {
         console.error(pc2.red(`Skill not found: ${source}`));
         process.exit(1);
@@ -226,25 +266,58 @@ function registerSkillsInstall(parent) {
         console.error(pc2.red("Could not resolve GitHub source"));
         process.exit(1);
       }
-      const result = await cloneRepo(parsed.owner, parsed.repo, parsed.ref, skill.path ? skill.path.replace(/\/SKILL\.md$/, "") : void 0);
-      localPath = result.localPath;
-      cleanup = result.cleanup;
-      skillName = skill.name;
-      sourceValue = skill.githubUrl;
-      sourceType = parsed.type;
+      try {
+        const subPathCandidates = marketplacePathCandidates(skill.path, parsed.path);
+        let cloneError;
+        let cloned = false;
+        for (const subPath of subPathCandidates) {
+          try {
+            const result = await cloneRepo(parsed.owner, parsed.repo, parsed.ref, subPath);
+            if (subPath && !existsSync(result.localPath)) {
+              await result.cleanup();
+              continue;
+            }
+            localPath = result.localPath;
+            cleanup = result.cleanup;
+            cloned = true;
+            break;
+          } catch (error) {
+            cloneError = error;
+          }
+        }
+        if (!cloned) {
+          throw cloneError ?? new Error("Unable to resolve skill path from marketplace metadata");
+        }
+        skillName = skill.name;
+        sourceValue = skill.githubUrl;
+        sourceType = parsed.type;
+      } catch (error) {
+        console.error(pc2.red(`Failed to fetch source repository: ${formatNetworkError(error)}`));
+        process.exit(1);
+      }
     } else {
       const parsed = parseSource(source);
       skillName = parsed.inferredName;
       sourceValue = parsed.value;
       sourceType = parsed.type;
       if (parsed.type === "github" && parsed.owner && parsed.repo) {
-        const result = await cloneRepo(parsed.owner, parsed.repo, parsed.ref, parsed.path);
-        localPath = result.localPath;
-        cleanup = result.cleanup;
+        try {
+          const result = await cloneRepo(parsed.owner, parsed.repo, parsed.ref, parsed.path);
+          localPath = result.localPath;
+          cleanup = result.cleanup;
+        } catch (error) {
+          console.error(pc2.red(`Failed to clone GitHub repository: ${formatNetworkError(error)}`));
+          process.exit(1);
+        }
       } else if (parsed.type === "gitlab" && parsed.owner && parsed.repo) {
-        const result = await cloneGitLabRepo(parsed.owner, parsed.repo, parsed.ref, parsed.path);
-        localPath = result.localPath;
-        cleanup = result.cleanup;
+        try {
+          const result = await cloneGitLabRepo(parsed.owner, parsed.repo, parsed.ref, parsed.path);
+          localPath = result.localPath;
+          cleanup = result.cleanup;
+        } catch (error) {
+          console.error(pc2.red(`Failed to clone GitLab repository: ${formatNetworkError(error)}`));
+          process.exit(1);
+        }
       } else if (parsed.type === "local") {
         localPath = parsed.value;
       } else {
@@ -253,6 +326,9 @@ function registerSkillsInstall(parent) {
       }
     }
     try {
+      if (!localPath) {
+        throw new Error("No local skill path resolved for installation");
+      }
       const result = await installSkill(
         localPath,
         skillName,
@@ -359,19 +435,125 @@ ${skills.length} skill(s) found:
 }
 
 // src/commands/skills/find.ts
+import { randomUUID } from "crypto";
+import {
+  resolveOutputFormat
+} from "@cleocode/lafs-protocol";
 import pc5 from "picocolors";
+var SkillsFindValidationError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "SkillsFindValidationError";
+  }
+};
 function registerSkillsFind(parent) {
-  parent.command("find").description("Search marketplace for skills").argument("[query]", "Search query").option("--json", "Output as JSON").option("-l, --limit <n>", "Max results", "20").action(async (query, opts) => {
+  parent.command("find").description("Search marketplace for skills").argument("[query]", "Search query").option("--recommend", "Recommend skills from constraints").option("--top <n>", "Number of recommendation candidates", "3").option("--must-have <term>", "Required criteria term", (value, previous) => [...previous, value], []).option("--prefer <term>", "Preferred criteria term", (value, previous) => [...previous, value], []).option("--exclude <term>", "Excluded criteria term", (value, previous) => [...previous, value], []).option("--details", "Include expanded machine output").option("--human", "Force human-readable output").option("--json", "Output as JSON").option("--select <indexes>", "Pre-select recommendation ranks (comma-separated)").option("-l, --limit <n>", "Max results", "20").action(async (query, opts) => {
+    const operation = opts.recommend ? "skills.find.recommend" : "skills.find.search";
+    const details = Boolean(opts.details);
+    const mvi = !details;
+    let format;
+    try {
+      format = resolveOutputFormat({
+        jsonFlag: opts.json ?? false,
+        humanFlag: opts.human ?? false,
+        projectDefault: opts.recommend ? "json" : "human"
+      }).format;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (opts.json) {
+        emitJsonError(operation, mvi, "E_FORMAT_CONFLICT", message, "VALIDATION");
+      } else {
+        console.error(pc5.red(message));
+      }
+      process.exit(1);
+    }
+    if (opts.recommend) {
+      try {
+        const top = parseTop(opts.top);
+        const mustHave = parseConstraintList(opts.mustHave);
+        const prefer = parseConstraintList(opts.prefer);
+        const exclude = parseConstraintList(opts.exclude);
+        validateCriteriaConflicts(mustHave, prefer, exclude);
+        const selectedRanks = parseSelectList(opts.select);
+        const seedQuery = buildSeedQuery(query, mustHave, prefer, exclude);
+        const recommendation = await recommendSkills(
+          seedQuery,
+          {
+            mustHave,
+            prefer,
+            exclude
+          },
+          {
+            top,
+            includeDetails: details
+          }
+        );
+        const options = normalizeRecommendationOptions(recommendation.ranking, details);
+        validateSelectedRanks(selectedRanks, options.length);
+        const selected = selectedRanks.length > 0 ? options.filter((option) => selectedRanks.includes(option.rank)) : [];
+        if (format === "json") {
+          const result = formatSkillRecommendations(recommendation, { mode: "json", details });
+          const resultOptions = Array.isArray(result.options) ? result.options : [];
+          const selectedObjects = resultOptions.filter(
+            (option) => selectedRanks.includes(Number(option.rank ?? 0))
+          );
+          const envelope = buildEnvelope(
+            operation,
+            mvi,
+            {
+              ...result,
+              selected: selectedObjects
+            },
+            null
+          );
+          console.log(JSON.stringify(envelope, null, 2));
+          return;
+        }
+        const human = formatSkillRecommendations(recommendation, { mode: "human", details });
+        console.log(human);
+        if (selected.length > 0) {
+          console.log(`Selected: ${selected.map((option) => option.scopedName).join(", ")}`);
+        }
+        return;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const errorCode = error instanceof SkillsFindValidationError ? error.code : error.code ?? RECOMMENDATION_ERROR_CODES.SOURCE_UNAVAILABLE;
+        const category = errorCode === RECOMMENDATION_ERROR_CODES.CRITERIA_CONFLICT ? "CONFLICT" : errorCode === RECOMMENDATION_ERROR_CODES.NO_MATCHES ? "NOT_FOUND" : errorCode === RECOMMENDATION_ERROR_CODES.QUERY_INVALID ? "VALIDATION" : "INTERNAL";
+        if (format === "json") {
+          emitJsonError(operation, mvi, errorCode, message, category, {
+            query: query ?? null
+          });
+        } else {
+          console.error(pc5.red(`Recommendation failed: ${message}`));
+        }
+        process.exit(1);
+      }
+    }
     if (!query) {
       console.log(pc5.dim("Usage: caamp skills find <query>"));
       return;
     }
     const limit = parseInt(opts.limit, 10);
     const client = new MarketplaceClient();
-    console.log(pc5.dim(`Searching marketplaces for "${query}"...
+    if (format === "human") {
+      console.log(pc5.dim(`Searching marketplaces for "${query}"...
 `));
-    const results = await client.search(query, limit);
-    if (opts.json) {
+    }
+    let results;
+    try {
+      results = await client.search(query, limit);
+    } catch (error) {
+      const message = formatNetworkError(error);
+      if (format === "json") {
+        console.log(JSON.stringify({ error: message }));
+      } else {
+        console.error(pc5.red(`Marketplace search failed: ${message}`));
+      }
+      process.exit(1);
+    }
+    if (format === "json") {
       console.log(JSON.stringify(results, null, 2));
       return;
     }
@@ -386,13 +568,118 @@ function registerSkillsFind(parent) {
       console.log(`  ${pc5.dim(`from ${skill.source}`)}`);
       console.log();
     }
-    console.log(pc5.dim(`Install with: caamp skills install <scopedName>`));
+    console.log(pc5.dim("Install with: caamp skills install <scopedName>"));
   });
 }
 function formatStars(n) {
   if (n >= 1e3) return `${(n / 1e3).toFixed(1)}k`;
   return String(n);
 }
+function parseConstraintList(values) {
+  const normalized = values.flatMap((value) => tokenizeCriteriaValue(value));
+  return Array.from(new Set(normalized));
+}
+function parseTop(value) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > 20) {
+    throw new SkillsFindValidationError(RECOMMENDATION_ERROR_CODES.QUERY_INVALID, "--top must be an integer between 1 and 20");
+  }
+  return parsed;
+}
+function parseSelectList(value) {
+  if (!value) return [];
+  const parsed = value.split(",").map((entry) => Number.parseInt(entry.trim(), 10)).filter((entry) => Number.isInteger(entry) && entry > 0);
+  return Array.from(new Set(parsed));
+}
+function buildSeedQuery(query, mustHave, prefer, exclude) {
+  if (query && query.trim().length > 0) {
+    return query;
+  }
+  const seedTerms = [...mustHave, ...prefer, ...exclude].filter((term) => term.length > 0);
+  if (seedTerms.length > 0) {
+    return seedTerms.join(" ");
+  }
+  throw new SkillsFindValidationError(
+    RECOMMENDATION_ERROR_CODES.QUERY_INVALID,
+    "Recommendation mode requires a query or at least one criteria flag."
+  );
+}
+function normalizeRecommendationOptions(ranking, details) {
+  return ranking.map((entry, index) => {
+    const whyCodes = entry.reasons.map((reason) => reason.code);
+    return {
+      rank: index + 1,
+      scopedName: entry.skill.scopedName,
+      description: entry.skill.description,
+      score: entry.score,
+      why: whyCodes.length > 0 ? whyCodes.join(", ") : "score-based match",
+      source: entry.skill.source,
+      ...details ? {
+        evidence: {
+          reasons: entry.reasons,
+          breakdown: entry.breakdown
+        }
+      } : {}
+    };
+  });
+}
+function validateCriteriaConflicts(mustHave, prefer, exclude) {
+  const overlap = mustHave.filter((term) => exclude.includes(term));
+  if (overlap.length > 0) {
+    throw new SkillsFindValidationError(
+      RECOMMENDATION_ERROR_CODES.CRITERIA_CONFLICT,
+      "A criteria term cannot be both required and excluded."
+    );
+  }
+  const preferOverlap = prefer.filter((term) => exclude.includes(term));
+  if (preferOverlap.length > 0) {
+    throw new SkillsFindValidationError(
+      RECOMMENDATION_ERROR_CODES.CRITERIA_CONFLICT,
+      "A criteria term cannot be both preferred and excluded."
+    );
+  }
+}
+function validateSelectedRanks(selectedRanks, total) {
+  for (const rank of selectedRanks) {
+    if (rank < 1 || rank > total) {
+      throw new SkillsFindValidationError(
+        RECOMMENDATION_ERROR_CODES.QUERY_INVALID,
+        `--select rank ${rank} is out of range (1-${total}).`
+      );
+    }
+  }
+}
+function buildEnvelope(operation, mvi, result, error) {
+  return {
+    $schema: "https://lafs.dev/schemas/v1/envelope.schema.json",
+    _meta: {
+      specVersion: "1.0.0",
+      schemaVersion: "1.0.0",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      operation,
+      requestId: randomUUID(),
+      transport: "cli",
+      strict: true,
+      mvi,
+      contextVersion: 0
+    },
+    success: error === null,
+    result,
+    error,
+    page: null
+  };
+}
+function emitJsonError(operation, mvi, code, message, category, details = {}) {
+  const envelope = buildEnvelope(operation, mvi, null, {
+    code,
+    message,
+    category,
+    retryable: false,
+    retryAfterMs: null,
+    details
+  });
+  console.error(JSON.stringify(envelope, null, 2));
+}
 
 // src/commands/skills/check.ts
 import pc6 from "picocolors";
@@ -576,13 +863,13 @@ ${outdated.length} skill(s) have updates available:
 // src/commands/skills/init.ts
 import pc8 from "picocolors";
 import { writeFile, mkdir } from "fs/promises";
-import { existsSync } from "fs";
+import { existsSync as existsSync2 } from "fs";
 import { join as join4 } from "path";
 function registerSkillsInit(parent) {
   parent.command("init").description("Create a new SKILL.md template").argument("[name]", "Skill name").option("-d, --dir <path>", "Output directory", ".").action(async (name, opts) => {
     const skillName = name ?? "my-skill";
     const skillDir = join4(opts.dir, skillName);
-    if (existsSync(skillDir)) {
+    if (existsSync2(skillDir)) {
       console.error(pc8.red(`Directory already exists: ${skillDir}`));
       process.exit(1);
     }
@@ -621,10 +908,10 @@ Show example inputs and expected outputs.
 
 // src/commands/skills/audit.ts
 import pc9 from "picocolors";
-import { existsSync as existsSync2, statSync } from "fs";
+import { existsSync as existsSync3, statSync } from "fs";
 function registerSkillsAudit(parent) {
   parent.command("audit").description("Security scan skill files (46+ rules, SARIF output)").argument("[path]", "Path to SKILL.md or directory", ".").option("--sarif", "Output in SARIF format").option("--json", "Output as JSON").action(async (path, opts) => {
-    if (!existsSync2(path)) {
+    if (!existsSync3(path)) {
       console.error(pc9.red(`Path not found: ${path}`));
       process.exit(1);
     }
@@ -842,7 +1129,7 @@ ${allEntries.length} MCP server(s) configured:
 
 // src/commands/mcp/detect.ts
 import pc14 from "picocolors";
-import { existsSync as existsSync3 } from "fs";
+import { existsSync as existsSync4 } from "fs";
 function registerMcpDetect(parent) {
   parent.command("detect").description("Auto-detect installed MCP tools and their configurations").option("--json", "Output as JSON").action(async (opts) => {
     const providers = getInstalledProviders();
@@ -854,8 +1141,8 @@ function registerMcpDetect(parent) {
       const projectEntries = await listMcpServers(provider, "project");
       detected.push({
         provider: provider.id,
-        hasGlobalConfig: globalPath !== null && existsSync3(globalPath),
-        hasProjectConfig: projectPath !== null && existsSync3(projectPath),
+        hasGlobalConfig: globalPath !== null && existsSync4(globalPath),
+        hasProjectConfig: projectPath !== null && existsSync4(projectPath),
         globalServers: globalEntries.map((e) => e.name),
         projectServers: projectEntries.map((e) => e.name)
       });
@@ -1016,7 +1303,7 @@ function registerInstructionsCommands(program2) {
 // src/commands/config.ts
 import pc18 from "picocolors";
 import { join as join5 } from "path";
-import { existsSync as existsSync4 } from "fs";
+import { existsSync as existsSync5 } from "fs";
 function registerConfigCommand(program2) {
   const config = program2.command("config").description("View provider configuration");
   config.command("show").description("Show provider configuration").argument("<provider>", "Provider ID or alias").option("-g, --global", "Show global config").option("--json", "Output as JSON").action(async (providerId, opts) => {
@@ -1026,7 +1313,7 @@ function registerConfigCommand(program2) {
       process.exit(1);
     }
     const configPath = opts.global ? provider.configPathGlobal : provider.configPathProject ? join5(process.cwd(), provider.configPathProject) : provider.configPathGlobal;
-    if (!existsSync4(configPath)) {
+    if (!existsSync5(configPath)) {
       console.log(pc18.dim(`No config file at: ${configPath}`));
       return;
     }
@@ -1067,7 +1354,7 @@ ${provider.toolName} config (${configPath}):
 // src/commands/doctor.ts
 import pc19 from "picocolors";
 import { execFileSync } from "child_process";
-import { existsSync as existsSync5, readdirSync, lstatSync } from "fs";
+import { existsSync as existsSync6, readdirSync, lstatSync } from "fs";
 import { homedir } from "os";
 import { join as join6 } from "path";
 var CAAMP_VERSION = "0.2.0";
@@ -1146,7 +1433,7 @@ function checkInstalledProviders() {
 function checkSkillSymlinks() {
   const checks = [];
   const canonicalDir = join6(homedir(), ".agents", "skills");
-  if (!existsSync5(canonicalDir)) {
+  if (!existsSync6(canonicalDir)) {
     checks.push({ label: "0 canonical skills", status: "pass" });
     checks.push({ label: "No broken symlinks", status: "pass" });
     return { name: "Skills", checks };
@@ -1164,7 +1451,7 @@ function checkSkillSymlinks() {
   const providers = getAllProviders();
   for (const provider of providers) {
     const skillDir = provider.pathSkills;
-    if (!existsSync5(skillDir)) continue;
+    if (!existsSync6(skillDir)) continue;
     try {
       const entries = readdirSync(skillDir);
       for (const entry of entries) {
@@ -1172,7 +1459,7 @@ function checkSkillSymlinks() {
         try {
           const stat = lstatSync(fullPath);
           if (stat.isSymbolicLink()) {
-            if (!existsSync5(fullPath)) {
+            if (!existsSync6(fullPath)) {
               broken.push(`${provider.id}/${entry}`);
             }
           }
@@ -1200,7 +1487,7 @@ async function checkLockFile() {
     checks.push({ label: "Lock file valid", status: "pass" });
     let orphaned = 0;
     for (const [name, entry] of Object.entries(lock.skills)) {
-      if (entry.canonicalPath && !existsSync5(entry.canonicalPath)) {
+      if (entry.canonicalPath && !existsSync6(entry.canonicalPath)) {
         orphaned++;
       }
     }
@@ -1229,7 +1516,7 @@ async function checkConfigFiles() {
   for (const r of installed) {
     const provider = r.provider;
     const configPath = provider.configPathGlobal;
-    if (!existsSync5(configPath)) {
+    if (!existsSync6(configPath)) {
       checks.push({
         label: `${provider.id}: no config file found`,
         status: "warn",
@@ -1317,6 +1604,650 @@ function registerDoctorCommand(program2) {
   });
 }
 
+// src/commands/advanced/common.ts
+import { readFile } from "fs/promises";
+
+// src/commands/advanced/lafs.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import {
+  isRegisteredErrorCode
+} from "@cleocode/lafs-protocol";
+var LAFSCommandError = class extends Error {
+  code;
+  category;
+  recoverable;
+  suggestion;
+  retryAfterMs;
+  details;
+  constructor(code, message, suggestion, recoverable = true, details) {
+    super(message);
+    this.name = "LAFSCommandError";
+    this.code = code;
+    this.category = inferErrorCategory(code);
+    this.recoverable = recoverable;
+    this.suggestion = suggestion;
+    this.retryAfterMs = null;
+    this.details = details;
+  }
+};
+function inferErrorCategory(code) {
+  if (code.includes("VALIDATION")) return "VALIDATION";
+  if (code.includes("NOT_FOUND")) return "NOT_FOUND";
+  if (code.includes("CONFLICT")) return "CONFLICT";
+  if (code.includes("AUTH")) return "AUTH";
+  if (code.includes("PERMISSION")) return "PERMISSION";
+  if (code.includes("RATE_LIMIT")) return "RATE_LIMIT";
+  if (code.includes("MIGRATION")) return "MIGRATION";
+  if (code.includes("CONTRACT")) return "CONTRACT";
+  return "INTERNAL";
+}
+function baseMeta(operation, mvi) {
+  return {
+    specVersion: "1.0.0",
+    schemaVersion: "1.0.0",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    operation,
+    requestId: randomUUID2(),
+    transport: "cli",
+    strict: true,
+    mvi,
+    contextVersion: 0
+  };
+}
+function emitSuccess(operation, result, mvi = true) {
+  const envelope = {
+    $schema: "https://lafs.dev/schemas/v1/envelope.schema.json",
+    _meta: {
+      ...baseMeta(operation, mvi)
+    },
+    success: true,
+    result,
+    error: null,
+    page: null
+  };
+  console.log(JSON.stringify(envelope, null, 2));
+}
+function emitError(operation, error, mvi = true) {
+  let envelope;
+  if (error instanceof LAFSCommandError) {
+    envelope = {
+      $schema: "https://lafs.dev/schemas/v1/envelope.schema.json",
+      _meta: {
+        ...baseMeta(operation, mvi)
+      },
+      success: false,
+      result: null,
+      error: {
+        code: isRegisteredErrorCode(error.code) ? error.code : "E_INTERNAL_UNEXPECTED",
+        message: error.message,
+        category: error.category,
+        retryable: error.recoverable,
+        retryAfterMs: error.retryAfterMs,
+        details: {
+          hint: error.suggestion,
+          ...error.details !== void 0 ? { payload: error.details } : {}
+        }
+      },
+      page: null
+    };
+  } else {
+    envelope = {
+      $schema: "https://lafs.dev/schemas/v1/envelope.schema.json",
+      _meta: {
+        ...baseMeta(operation, mvi)
+      },
+      success: false,
+      result: null,
+      error: {
+        code: "E_INTERNAL_UNEXPECTED",
+        message: error instanceof Error ? error.message : String(error),
+        category: "INTERNAL",
+        retryable: false,
+        retryAfterMs: null,
+        details: {
+          hint: "Rerun with --verbose and validate your inputs."
+        }
+      },
+      page: null
+    };
+  }
+  console.error(JSON.stringify(envelope, null, 2));
+}
+async function runLafsCommand(command, mvi, action) {
+  try {
+    const result = await action();
+    emitSuccess(command, result, mvi);
+  } catch (error) {
+    emitError(command, error, mvi);
+    process.exit(1);
+  }
+}
+
+// src/commands/advanced/common.ts
+var VALID_PRIORITIES = /* @__PURE__ */ new Set(["high", "medium", "low"]);
+function parsePriority(value) {
+  if (!VALID_PRIORITIES.has(value)) {
+    throw new LAFSCommandError(
+      "E_ADVANCED_VALIDATION_PRIORITY",
+      `Invalid tier: ${value}`,
+      "Use one of: high, medium, low."
+    );
+  }
+  return value;
+}
+function resolveProviders(options) {
+  if (options.all) {
+    return getAllProviders();
+  }
+  const targetAgents = options.agent ?? [];
+  if (targetAgents.length === 0) {
+    return getInstalledProviders();
+  }
+  const providers = targetAgents.map((id) => getProvider(id)).filter((provider) => provider !== void 0);
+  if (providers.length !== targetAgents.length) {
+    const found = new Set(providers.map((provider) => provider.id));
+    const missing = targetAgents.filter((id) => !found.has(id));
+    throw new LAFSCommandError(
+      "E_ADVANCED_PROVIDER_NOT_FOUND",
+      `Unknown provider(s): ${missing.join(", ")}`,
+      "Check `caamp providers list` for valid provider IDs/aliases."
+    );
+  }
+  return providers;
+}
+async function readJsonFile(path) {
+  try {
+    const raw = await readFile(path, "utf-8");
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new LAFSCommandError(
+      "E_ADVANCED_INPUT_JSON",
+      `Failed to read JSON file: ${path}`,
+      "Confirm the path exists and contains valid JSON.",
+      true,
+      { reason: error instanceof Error ? error.message : String(error) }
+    );
+  }
+}
+async function readMcpOperations(path) {
+  const value = await readJsonFile(path);
+  if (!Array.isArray(value)) {
+    throw new LAFSCommandError(
+      "E_ADVANCED_VALIDATION_MCP_ARRAY",
+      `MCP operations file must be a JSON array: ${path}`,
+      "Provide an array of objects with serverName and config fields."
+    );
+  }
+  const operations = [];
+  for (const [index, item] of value.entries()) {
+    if (!item || typeof item !== "object") {
+      throw new LAFSCommandError(
+        "E_ADVANCED_VALIDATION_MCP_ITEM",
+        `Invalid MCP operation at index ${index}`,
+        "Each operation must be an object with serverName and config."
+      );
+    }
+    const obj = item;
+    const serverName = obj["serverName"];
+    const config = obj["config"];
+    const scope = obj["scope"];
+    if (typeof serverName !== "string" || serverName.length === 0) {
+      throw new LAFSCommandError(
+        "E_ADVANCED_VALIDATION_MCP_NAME",
+        `Invalid serverName at index ${index}`,
+        "Set serverName to a non-empty string."
+      );
+    }
+    if (!config || typeof config !== "object" || Array.isArray(config)) {
+      throw new LAFSCommandError(
+        "E_ADVANCED_VALIDATION_MCP_CONFIG",
+        `Invalid config at index ${index}`,
+        "Set config to an object matching McpServerConfig."
+      );
+    }
+    if (scope !== void 0 && scope !== "project" && scope !== "global") {
+      throw new LAFSCommandError(
+        "E_ADVANCED_VALIDATION_SCOPE",
+        `Invalid scope at index ${index}: ${String(scope)}`,
+        "Use scope value 'project' or 'global'."
+      );
+    }
+    operations.push({
+      serverName,
+      config,
+      ...scope ? { scope } : {}
+    });
+  }
+  return operations;
+}
+async function readSkillOperations(path) {
+  const value = await readJsonFile(path);
+  if (!Array.isArray(value)) {
+    throw new LAFSCommandError(
+      "E_ADVANCED_VALIDATION_SKILL_ARRAY",
+      `Skill operations file must be a JSON array: ${path}`,
+      "Provide an array of objects with sourcePath and skillName fields."
+    );
+  }
+  const operations = [];
+  for (const [index, item] of value.entries()) {
+    if (!item || typeof item !== "object") {
+      throw new LAFSCommandError(
+        "E_ADVANCED_VALIDATION_SKILL_ITEM",
+        `Invalid skill operation at index ${index}`,
+        "Each operation must be an object with sourcePath and skillName."
+      );
+    }
+    const obj = item;
+    const sourcePath = obj["sourcePath"];
+    const skillName = obj["skillName"];
+    const isGlobal = obj["isGlobal"];
+    if (typeof sourcePath !== "string" || sourcePath.length === 0) {
+      throw new LAFSCommandError(
+        "E_ADVANCED_VALIDATION_SKILL_SOURCE",
+        `Invalid sourcePath at index ${index}`,
+        "Set sourcePath to a non-empty string."
+      );
+    }
+    if (typeof skillName !== "string" || skillName.length === 0) {
+      throw new LAFSCommandError(
+        "E_ADVANCED_VALIDATION_SKILL_NAME",
+        `Invalid skillName at index ${index}`,
+        "Set skillName to a non-empty string."
+      );
+    }
+    if (isGlobal !== void 0 && typeof isGlobal !== "boolean") {
+      throw new LAFSCommandError(
+        "E_ADVANCED_VALIDATION_SKILL_SCOPE",
+        `Invalid isGlobal value at index ${index}`,
+        "Set isGlobal to true or false when provided."
+      );
+    }
+    operations.push({
+      sourcePath,
+      skillName,
+      ...isGlobal !== void 0 ? { isGlobal } : {}
+    });
+  }
+  return operations;
+}
+async function readTextInput(inlineContent, filePath) {
+  if (inlineContent && filePath) {
+    throw new LAFSCommandError(
+      "E_ADVANCED_VALIDATION_INPUT_MODE",
+      "Provide either inline content or a content file, not both.",
+      "Use --content OR --content-file."
+    );
+  }
+  if (inlineContent) return inlineContent;
+  if (!filePath) return void 0;
+  try {
+    return await readFile(filePath, "utf-8");
+  } catch (error) {
+    throw new LAFSCommandError(
+      "E_ADVANCED_INPUT_TEXT",
+      `Failed to read content file: ${filePath}`,
+      "Confirm the file exists and is readable.",
+      true,
+      { reason: error instanceof Error ? error.message : String(error) }
+    );
+  }
+}
+
+// src/commands/advanced/providers.ts
+function registerAdvancedProviders(parent) {
+  parent.command("providers").description("Select providers by priority using advanced wrapper logic").option("-a, --agent <name>", "Target specific provider(s)", (v, prev) => [...prev, v], []).option("--all", "Use all registry providers (not only detected)").option("--min-tier <tier>", "Minimum priority tier: high|medium|low", "low").option("--details", "Include full provider objects").action(async (opts) => runLafsCommand("advanced.providers", !opts.details, async () => {
+    const providers = resolveProviders({ all: opts.all, agent: opts.agent });
+    const minTier = parsePriority(opts.minTier);
+    const selected = selectProvidersByMinimumPriority(providers, minTier);
+    return {
+      objective: "Filter providers by minimum priority tier",
+      constraints: {
+        minTier,
+        selectionMode: opts.all ? "registry" : "detected-or-explicit"
+      },
+      acceptanceCriteria: {
+        selectedCount: selected.length,
+        orderedByPriority: true
+      },
+      data: opts.details ? selected : selected.map((provider) => ({
+        id: provider.id,
+        priority: provider.priority,
+        status: provider.status,
+        configFormat: provider.configFormat
+      }))
+    };
+  }));
+}
+
+// src/commands/advanced/batch.ts
+function registerAdvancedBatch(parent) {
+  parent.command("batch").description("Run rollback-capable batch install for MCP + skills").option("-a, --agent <name>", "Target specific provider(s)", (v, prev) => [...prev, v], []).option("--all", "Use all registry providers (not only detected)").option("--min-tier <tier>", "Minimum priority tier: high|medium|low", "low").option("--mcp-file <path>", "JSON file containing McpBatchOperation[]").option("--skills-file <path>", "JSON file containing SkillBatchOperation[]").option("--project-dir <path>", "Project directory to resolve project-scope paths").option("--details", "Include detailed operation result").action(async (opts) => runLafsCommand("advanced.batch", !opts.details, async () => {
+    const baseProviders = resolveProviders({ all: opts.all, agent: opts.agent });
+    const minimumPriority = parsePriority(opts.minTier);
+    const providers = selectProvidersByMinimumPriority(baseProviders, minimumPriority);
+    const mcp = opts.mcpFile ? await readMcpOperations(opts.mcpFile) : [];
+    const skills = opts.skillsFile ? await readSkillOperations(opts.skillsFile) : [];
+    if (mcp.length === 0 && skills.length === 0) {
+      throw new LAFSCommandError(
+        "E_ADVANCED_VALIDATION_NO_OPS",
+        "No operations provided.",
+        "Provide --mcp-file and/or --skills-file."
+      );
+    }
+    if (providers.length === 0) {
+      throw new LAFSCommandError(
+        "E_ADVANCED_NO_TARGET_PROVIDERS",
+        "No target providers resolved for this batch operation.",
+        "Use --all or pass provider IDs with --agent."
+      );
+    }
+    const result = await installBatchWithRollback({
+      providers,
+      minimumPriority,
+      mcp,
+      skills,
+      projectDir: opts.projectDir
+    });
+    if (!result.success) {
+      throw new LAFSCommandError(
+        "E_ADVANCED_BATCH_FAILED",
+        result.error ?? "Batch operation failed.",
+        "Check rollbackErrors and input configs, then retry.",
+        true,
+        result
+      );
+    }
+    return {
+      objective: "Install MCP and skills with rollback safety",
+      constraints: {
+        minimumPriority,
+        providerCount: providers.length,
+        mcpOps: mcp.length,
+        skillOps: skills.length
+      },
+      acceptanceCriteria: {
+        success: result.success,
+        rollbackPerformed: result.rollbackPerformed
+      },
+      data: opts.details ? result : {
+        providerCount: result.providerIds.length,
+        mcpApplied: result.mcpApplied,
+        skillsApplied: result.skillsApplied,
+        rollbackPerformed: result.rollbackPerformed
+      }
+    };
+  }));
+}
+
+// src/commands/advanced/conflicts.ts
+function registerAdvancedConflicts(parent) {
+  parent.command("conflicts").description("Preflight MCP conflict detection across providers").requiredOption("--mcp-file <path>", "JSON file containing McpBatchOperation[]").option("-a, --agent <name>", "Target specific provider(s)", (v, prev) => [...prev, v], []).option("--all", "Use all registry providers (not only detected)").option("--min-tier <tier>", "Minimum priority tier: high|medium|low", "low").option("--project-dir <path>", "Project directory to resolve project-scope paths").option("--details", "Include full conflict list").action(async (opts) => runLafsCommand("advanced.conflicts", !opts.details, async () => {
+    const baseProviders = resolveProviders({ all: opts.all, agent: opts.agent });
+    const minimumPriority = parsePriority(opts.minTier);
+    const providers = selectProvidersByMinimumPriority(baseProviders, minimumPriority);
+    const operations = await readMcpOperations(opts.mcpFile);
+    if (providers.length === 0) {
+      throw new LAFSCommandError(
+        "E_ADVANCED_NO_TARGET_PROVIDERS",
+        "No target providers resolved for conflict detection.",
+        "Use --all or pass provider IDs with --agent."
+      );
+    }
+    const conflicts = await detectMcpConfigConflicts(
+      providers,
+      operations,
+      opts.projectDir
+    );
+    const countByCode = conflicts.reduce((acc, conflict) => {
+      acc[conflict.code] = (acc[conflict.code] ?? 0) + 1;
+      return acc;
+    }, {});
+    return {
+      objective: "Detect MCP configuration conflicts before mutation",
+      constraints: {
+        minimumPriority,
+        providerCount: providers.length,
+        operationCount: operations.length
+      },
+      acceptanceCriteria: {
+        conflictCount: conflicts.length
+      },
+      data: opts.details ? conflicts : {
+        conflictCount: conflicts.length,
+        countByCode,
+        sample: conflicts.slice(0, 5)
+      }
+    };
+  }));
+}
+
+// src/commands/advanced/apply.ts
+var VALID_POLICIES = /* @__PURE__ */ new Set(["fail", "skip", "overwrite"]);
+function parsePolicy(value) {
+  if (!VALID_POLICIES.has(value)) {
+    throw new LAFSCommandError(
+      "E_ADVANCED_VALIDATION_POLICY",
+      `Invalid policy: ${value}`,
+      "Use one of: fail, skip, overwrite."
+    );
+  }
+  return value;
+}
+function registerAdvancedApply(parent) {
+  parent.command("apply").description("Apply MCP operations with configurable conflict policy").requiredOption("--mcp-file <path>", "JSON file containing McpBatchOperation[]").option("--policy <policy>", "Conflict policy: fail|skip|overwrite", "fail").option("-a, --agent <name>", "Target specific provider(s)", (v, prev) => [...prev, v], []).option("--all", "Use all registry providers (not only detected)").option("--min-tier <tier>", "Minimum priority tier: high|medium|low", "low").option("--project-dir <path>", "Project directory to resolve project-scope paths").option("--details", "Include detailed apply result").action(async (opts) => runLafsCommand("advanced.apply", !opts.details, async () => {
+    const baseProviders = resolveProviders({ all: opts.all, agent: opts.agent });
+    const minimumPriority = parsePriority(opts.minTier);
+    const providers = selectProvidersByMinimumPriority(baseProviders, minimumPriority);
+    const operations = await readMcpOperations(opts.mcpFile);
+    const policy = parsePolicy(opts.policy);
+    if (providers.length === 0) {
+      throw new LAFSCommandError(
+        "E_ADVANCED_NO_TARGET_PROVIDERS",
+        "No target providers resolved for apply operation.",
+        "Use --all or pass provider IDs with --agent."
+      );
+    }
+    const result = await applyMcpInstallWithPolicy(
+      providers,
+      operations,
+      policy,
+      opts.projectDir
+    );
+    if (policy === "fail" && result.conflicts.length > 0) {
+      throw new LAFSCommandError(
+        "E_ADVANCED_CONFLICTS_BLOCKING",
+        "Conflicts detected and policy is set to fail.",
+        "Run `caamp advanced conflicts` to inspect, or rerun with --policy skip/overwrite.",
+        true,
+        result
+      );
+    }
+    const failedWrites = result.applied.filter((entry) => !entry.success);
+    if (failedWrites.length > 0) {
+      throw new LAFSCommandError(
+        "E_ADVANCED_APPLY_WRITE_FAILED",
+        "One or more MCP writes failed.",
+        "Check result details, fix provider config issues, and retry.",
+        true,
+        result
+      );
+    }
+    return {
+      objective: "Apply MCP operations with policy-driven conflict handling",
+      constraints: {
+        policy,
+        minimumPriority,
+        providerCount: providers.length,
+        operationCount: operations.length
+      },
+      acceptanceCriteria: {
+        conflicts: result.conflicts.length,
+        writesSucceeded: result.applied.length
+      },
+      data: opts.details ? result : {
+        conflicts: result.conflicts.length,
+        applied: result.applied.length,
+        skipped: result.skipped.length
+      }
+    };
+  }));
+}
+
+// src/commands/advanced/instructions.ts
+function registerAdvancedInstructions(parent) {
+  parent.command("instructions").description("Single-operation instruction update across providers").option("-a, --agent <name>", "Target specific provider(s)", (v, prev) => [...prev, v], []).option("--all", "Use all registry providers (not only detected)").option("--min-tier <tier>", "Minimum priority tier: high|medium|low", "low").option("--scope <scope>", "Instruction scope: project|global", "project").option("--content <text>", "Inline content to inject").option("--content-file <path>", "File containing content to inject").option("--project-dir <path>", "Project directory to resolve project-scope paths").option("--details", "Include detailed per-file actions").action(async (opts) => runLafsCommand("advanced.instructions", !opts.details, async () => {
+    const minimumPriority = parsePriority(opts.minTier);
+    const baseProviders = resolveProviders({ all: opts.all, agent: opts.agent });
+    const providers = selectProvidersByMinimumPriority(baseProviders, minimumPriority);
+    const scope = opts.scope === "global" ? "global" : opts.scope === "project" ? "project" : null;
+    if (!scope) {
+      throw new LAFSCommandError(
+        "E_ADVANCED_VALIDATION_SCOPE",
+        `Invalid scope: ${opts.scope}`,
+        "Use --scope project or --scope global."
+      );
+    }
+    const content = await readTextInput(opts.content, opts.contentFile);
+    if (!content || content.trim().length === 0) {
+      throw new LAFSCommandError(
+        "E_ADVANCED_VALIDATION_CONTENT",
+        "Instruction content is required.",
+        "Provide --content or --content-file with non-empty text."
+      );
+    }
+    if (providers.length === 0) {
+      throw new LAFSCommandError(
+        "E_ADVANCED_NO_TARGET_PROVIDERS",
+        "No target providers resolved for instruction update.",
+        "Use --all or pass provider IDs with --agent."
+      );
+    }
+    const summary = await updateInstructionsSingleOperation(
+      providers,
+      content,
+      scope,
+      opts.projectDir
+    );
+    return {
+      objective: "Update instruction files across providers in one operation",
+      constraints: {
+        scope,
+        minimumPriority,
+        providerCount: providers.length
+      },
+      acceptanceCriteria: {
+        updatedFiles: summary.updatedFiles
+      },
+      data: opts.details ? summary : {
+        updatedFiles: summary.updatedFiles,
+        files: summary.actions.map((entry) => ({
+          file: entry.file,
+          action: entry.action
+        }))
+      }
+    };
+  }));
+}
+
+// src/commands/advanced/configure.ts
+function registerAdvancedConfigure(parent) {
+  parent.command("configure").description("Configure global + project scope for one provider in one operation").requiredOption("-a, --agent <name>", "Target provider ID or alias").option("--global-mcp-file <path>", "JSON file for global MCP operations").option("--project-mcp-file <path>", "JSON file for project MCP operations").option("--instruction <text>", "Instruction content for both scopes").option("--instruction-file <path>", "Instruction content file for both scopes").option("--instruction-global <text>", "Instruction content for global scope").option("--instruction-global-file <path>", "Instruction content file for global scope").option("--instruction-project <text>", "Instruction content for project scope").option("--instruction-project-file <path>", "Instruction content file for project scope").option("--project-dir <path>", "Project directory to resolve project-scope paths").option("--details", "Include detailed write results").action(async (opts) => runLafsCommand("advanced.configure", !opts.details, async () => {
+    const provider = getProvider(opts.agent);
+    if (!provider) {
+      throw new LAFSCommandError(
+        "E_ADVANCED_PROVIDER_NOT_FOUND",
+        `Unknown provider: ${opts.agent}`,
+        "Check `caamp providers list` for valid provider IDs/aliases."
+      );
+    }
+    const globalMcp = opts.globalMcpFile ? await readMcpOperations(opts.globalMcpFile) : [];
+    const projectMcp = opts.projectMcpFile ? await readMcpOperations(opts.projectMcpFile) : [];
+    const sharedInstruction = await readTextInput(opts.instruction, opts.instructionFile);
+    const globalInstruction = await readTextInput(
+      opts.instructionGlobal,
+      opts.instructionGlobalFile
+    );
+    const projectInstruction = await readTextInput(
+      opts.instructionProject,
+      opts.instructionProjectFile
+    );
+    let instructionContent;
+    if (globalInstruction || projectInstruction) {
+      instructionContent = {
+        ...globalInstruction ? { global: globalInstruction } : {},
+        ...projectInstruction ? { project: projectInstruction } : {}
+      };
+    } else if (sharedInstruction) {
+      instructionContent = sharedInstruction;
+    }
+    if (globalMcp.length === 0 && projectMcp.length === 0 && !instructionContent) {
+      throw new LAFSCommandError(
+        "E_ADVANCED_VALIDATION_NO_OPS",
+        "No configuration operations were provided.",
+        "Provide MCP files and/or instruction content."
+      );
+    }
+    const result = await configureProviderGlobalAndProject(provider, {
+      globalMcp: globalMcp.map((entry) => ({
+        serverName: entry.serverName,
+        config: entry.config
+      })),
+      projectMcp: projectMcp.map((entry) => ({
+        serverName: entry.serverName,
+        config: entry.config
+      })),
+      instructionContent,
+      projectDir: opts.projectDir
+    });
+    const globalFailures = result.mcp.global.filter((entry) => !entry.success);
+    const projectFailures = result.mcp.project.filter((entry) => !entry.success);
+    if (globalFailures.length > 0 || projectFailures.length > 0) {
+      throw new LAFSCommandError(
+        "E_ADVANCED_CONFIGURE_FAILED",
+        "One or more MCP writes failed during configure operation.",
+        "Inspect the failed write entries and provider config paths, then retry.",
+        true,
+        result
+      );
+    }
+    return {
+      objective: "Configure global and project settings in one operation",
+      constraints: {
+        provider: provider.id,
+        globalMcpOps: globalMcp.length,
+        projectMcpOps: projectMcp.length,
+        instructionMode: instructionContent ? typeof instructionContent === "string" ? "shared" : "scoped" : "none"
+      },
+      acceptanceCriteria: {
+        globalWrites: result.mcp.global.length,
+        projectWrites: result.mcp.project.length
+      },
+      data: opts.details ? result : {
+        providerId: result.providerId,
+        configPaths: result.configPaths,
+        globalWrites: result.mcp.global.length,
+        projectWrites: result.mcp.project.length,
+        instructionUpdates: {
+          global: result.instructions.global?.size ?? 0,
+          project: result.instructions.project?.size ?? 0
+        }
+      }
+    };
+  }));
+}
+
+// src/commands/advanced/index.ts
+function registerAdvancedCommands(program2) {
+  const advanced = program2.command("advanced").description("LAFS-compliant wrappers for advanced orchestration APIs");
+  registerAdvancedProviders(advanced);
+  registerAdvancedBatch(advanced);
+  registerAdvancedConflicts(advanced);
+  registerAdvancedApply(advanced);
+  registerAdvancedInstructions(advanced);
+  registerAdvancedConfigure(advanced);
+}
+
 // src/cli.ts
 var program = new Command();
 program.name("caamp").description("Central AI Agent Managed Packages - unified provider registry and package manager").version("0.3.0").option("-v, --verbose", "Show debug output").option("-q, --quiet", "Suppress non-error output");
@@ -1331,5 +2262,6 @@ registerMcpCommands(program);
 registerInstructionsCommands(program);
 registerConfigCommand(program);
 registerDoctorCommand(program);
+registerAdvancedCommands(program);
 program.parse();
 //# sourceMappingURL=cli.js.map