@cleocode/caamp 2026.9.18 → 2026.9.20

package/dist/{chunk-G3CEXEW2.js → chunk-JELNPPLN.js}

@@ -6,15 +6,17 @@ import {
 } from "./chunk-HDZYZTR2.js";
 
 // src/core/instructions/injector.ts
-import { existsSync } from "fs";
+import { existsSync as existsSync2 } from "fs";
 import { readFile as readFile3, stat as stat3 } from "fs/promises";
 import { homedir as homedir2 } from "os";
-import { dirname as dirname4, join as join2 } from "path";
-import { writeFileAtomic } from "@cleocode/core/tools/fs.js";
+import { dirname as dirname4, isAbsolute, join as join2 } from "path";
+import { writeFileAtomic as writeFileAtomic2 } from "@cleocode/core/tools/fs.js";
 
 // src/core/fs/atomic.ts
+import { existsSync } from "fs";
 import { mkdir, open, readFile, rm, stat, writeFile } from "fs/promises";
 import { dirname } from "path";
+import { writeFileAtomic } from "@cleocode/core/tools/fs.js";
 var DEFAULT_STALE_LOCK_MS = 3e4;
 var DEFAULT_LOCK_RETRIES = 400;
 var DEFAULT_LOCK_DELAY_MS = 25;
@@ -77,6 +79,50 @@ function assertNotTornRead(filePath, content, sizeOnDisk) {
     );
   }
 }
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var JsonConfigParseError = class extends Error {
+  /** Path of the file that failed to parse. */
+  filePath;
+  /**
+   * @param filePath - Path of the file that failed to parse
+   * @param reason - Parser message
+   */
+  constructor(filePath, reason) {
+    super(`Refusing to rewrite ${filePath}: it is not a valid JSON object (${reason}).`);
+    this.name = "JsonConfigParseError";
+    this.filePath = filePath;
+  }
+};
+async function updateJsonConfigFile(filePath, mutate) {
+  return withFileLock(filePath, async () => {
+    let config = {};
+    if (existsSync(filePath)) {
+      const raw = await readFile(filePath, "utf-8");
+      if (raw.length === 0) assertNotTornRead(filePath, raw, (await stat(filePath)).size);
+      if (raw.trim().length > 0) {
+        let parsed;
+        try {
+          parsed = JSON.parse(raw);
+        } catch (err) {
+          throw new JsonConfigParseError(
+            filePath,
+            err instanceof Error ? err.message : String(err)
+          );
+        }
+        if (!isJsonObject(parsed)) {
+          throw new JsonConfigParseError(filePath, "top-level value is not an object");
+        }
+        config = parsed;
+      }
+    }
+    if (!mutate(config)) return false;
+    await writeFileAtomic({ path: filePath, content: `${JSON.stringify(config, null, 2)}
+` });
+    return true;
+  });
+}
 
 // src/core/registry/providers.ts
 import { readFileSync } from "fs";
@@ -279,6 +325,11 @@ function getSpawnCapableProviders() {
 function getProvidersBySpawnCapability(flag) {
   return getAllProviders().filter((p) => p.capabilities.spawn[flag] === true);
 }
+function resetRegistry() {
+  _registry = null;
+  _providers = null;
+  _aliasMap = null;
+}
 function getProviderInstructionReferences(idOrAlias) {
   const provider = getProvider(idOrAlias);
   return provider?.instructionReferences ? [...provider.instructionReferences] : [];
@@ -355,8 +406,25 @@ import {
   CAAMP_DAMAGED_END_PATTERN_SOURCE,
   CAAMP_DAMAGED_START_PATTERN_SOURCE,
   CAAMP_MARKER_END,
-  CAAMP_MARKER_START
+  CAAMP_MARKER_START,
+  CAAMP_SOURCE_STAMP_PATTERN_SOURCE
 } from "@cleocode/contracts/caamp-markers";
+var EmbeddedDeliveryDowngradeError = class extends Error {
+  /** Stable error code for envelopes and tests. */
+  code = "E_CAAMP_EMBEDDED_DOWNGRADE";
+  /**
+   * @param detail - Which file or block the refused write targeted.
+   */
+  constructor(detail) {
+    super(
+      `Refusing to replace an embedded CAAMP delivery with reference-only content (${detail}). Regenerate it from its sources: cleo install-global (global) or cleo upgrade (project).`
+    );
+    this.name = "EmbeddedDeliveryDowngradeError";
+  }
+};
+function isEmbeddedDelivery(body) {
+  return new RegExp(CAAMP_SOURCE_STAMP_PATTERN_SOURCE, "m").test(body);
+}
 function blockPattern() {
   return new RegExp(CAAMP_BLOCK_PATTERN_SOURCE, "g");
 }
@@ -417,6 +485,9 @@ function reconcile(existing, desiredContent, insert = "prepend") {
   const blocks = parseBlocks(healed);
   const desiredBlock = buildBlock(desiredContent.trim());
   assertBalancedMarkers(desiredBlock);
+  if (!isEmbeddedDelivery(desiredContent) && blocks.some((b) => isEmbeddedDelivery(b.content))) {
+    throw new EmbeddedDeliveryDowngradeError("existing block carries CAAMP:SOURCE stamps");
+  }
   if (blocks.length === 0) {
     if (healed.length === 0) return { content: `${desiredBlock}
 `, blocksBefore: 0, repaired };
@@ -650,7 +721,7 @@ function parseCaampBlocks(fileContent) {
   return parseBlocks(fileContent);
 }
 async function dedupeFile(filePath) {
-  if (!existsSync(filePath)) {
+  if (!existsSync2(filePath)) {
     return { filePath, removed: 0, kept: 0, modified: false, repaired: 0 };
   }
   return withFileLock(filePath, async () => {
@@ -660,7 +731,7 @@ async function dedupeFile(filePath) {
     const blocks = parseBlocks(healed);
     if (blocks.length === 0) {
       if (repaired > 0 && healed !== original) {
-        await writeFileAtomic({ path: filePath, content: healed });
+        await writeFileAtomic2({ path: filePath, content: healed });
         return { filePath, removed: 0, kept: 0, modified: true, repaired };
       }
       return { filePath, removed: 0, kept: 0, modified: false, repaired };
@@ -687,7 +758,7 @@ async function dedupeFile(filePath) {
     if (result === original) {
       return { filePath, removed: 0, kept: blocks.length, modified: false, repaired };
     }
-    await writeFileAtomic({ path: filePath, content: result });
+    await writeFileAtomic2({ path: filePath, content: result });
     return { filePath, removed, kept: keepSet.size, modified: true, repaired };
   });
 }
@@ -706,12 +777,20 @@ function instructionFileCascade(projectDir, providers) {
     join2(projectDir, "GEMINI.md")
   ];
   for (const provider of providers) {
-    paths.push(join2(provider.pathGlobal, provider.instructFile));
+    const globalPath = resolveGlobalInstructionPath(provider);
+    if (globalPath !== null) paths.push(globalPath);
   }
   return [...new Set(paths)];
 }
+function resolveGlobalInstructionPath(provider) {
+  if (!provider.pathGlobal || !isAbsolute(provider.pathGlobal)) return null;
+  return join2(provider.pathGlobal, provider.instructFile);
+}
+function scopedInstructionPath(provider, projectDir, scope) {
+  return scope === "global" ? resolveGlobalInstructionPath(provider) : join2(projectDir, provider.instructFile);
+}
 async function repairInstructionFiles(projectDir, providers) {
-  const paths = instructionFileCascade(projectDir, providers).filter((p) => existsSync(p));
+  const paths = instructionFileCascade(projectDir, providers).filter((p) => existsSync2(p));
   const files = [];
   for (const filePath of paths) {
     files.push(
@@ -725,7 +804,7 @@ async function repairInstructionFiles(projectDir, providers) {
         if (content === original) {
           return { filePath, removed: 0, kept: blocksBefore, modified: false, repaired };
         }
-        await writeFileAtomic({ path: filePath, content });
+        await writeFileAtomic2({ path: filePath, content });
         return {
           filePath,
           removed,
@@ -744,7 +823,7 @@ async function repairInstructionFiles(projectDir, providers) {
   };
 }
 async function checkInjection(filePath, expectedContent) {
-  if (!existsSync(filePath)) return "missing";
+  if (!existsSync2(filePath)) return "missing";
   const raw = await readFile3(filePath, "utf-8");
   const { content, repaired } = normalizeMarkers(raw);
   const blocks = parseBlocks(content);
@@ -759,8 +838,8 @@ async function inject(filePath, content) {
   const body = content.trim();
   assertBalancedMarkers(buildBlock(body));
   return withFileLock(filePath, async () => {
-    if (!existsSync(filePath)) {
-      await writeFileAtomic({ path: filePath, content: `${buildBlock(body)}
+    if (!existsSync2(filePath)) {
+      await writeFileAtomic2({ path: filePath, content: `${buildBlock(body)}
 ` });
       return "created";
     }
@@ -770,7 +849,7 @@ async function inject(filePath, content) {
     }
     const { content: next, blocksBefore, repaired } = reconcile(existing, body);
     if (next === existing) return "intact";
-    await writeFileAtomic({ path: filePath, content: next });
+    await writeFileAtomic2({ path: filePath, content: next });
     if (blocksBefore === 0) return "added";
     if (repaired > 0) return "repaired";
     if (blocksBefore > 1) return "consolidated";
@@ -778,7 +857,7 @@ async function inject(filePath, content) {
   });
 }
 async function removeInjection(filePath) {
-  if (!existsSync(filePath)) return false;
+  if (!existsSync2(filePath)) return false;
   return withFileLock(filePath, async () => {
     const original = await readFile3(filePath, "utf-8");
     const { content } = normalizeMarkers(original);
@@ -789,7 +868,7 @@ async function removeInjection(filePath) {
       const { rm: rm2 } = await import("fs/promises");
       await rm2(filePath);
     } else {
-      await writeFileAtomic({ path: filePath, content: cleaned });
+      await writeFileAtomic2({ path: filePath, content: cleaned });
     }
     return true;
   });
@@ -798,7 +877,8 @@ async function checkAllInjections(providers, projectDir, scope, expectedContent)
   const results = [];
   const checked = /* @__PURE__ */ new Set();
   for (const provider of providers) {
-    const filePath = scope === "global" ? join2(provider.pathGlobal, provider.instructFile) : join2(projectDir, provider.instructFile);
+    const filePath = scopedInstructionPath(provider, projectDir, scope);
+    if (filePath === null) continue;
     if (checked.has(filePath)) continue;
     checked.add(filePath);
     let status = await checkInjection(filePath, expectedContent);
@@ -810,7 +890,7 @@ async function checkAllInjections(providers, projectDir, scope, expectedContent)
         reason: "Managed content differs from the expected version."
       });
     }
-    if (existsSync(filePath) && parseBlocks(await readFile3(filePath, "utf8")).length > 1) {
+    if (existsSync2(filePath) && parseBlocks(await readFile3(filePath, "utf8")).length > 1) {
       delivery.findings.push({
         kind: "duplicate",
         path: filePath,
@@ -824,7 +904,7 @@ async function checkAllInjections(providers, projectDir, scope, expectedContent)
       file: filePath,
       provider: provider.id,
       status,
-      fileExists: existsSync(filePath)
+      fileExists: existsSync2(filePath)
     });
   }
   return results;
@@ -833,7 +913,8 @@ 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" ? join2(provider.pathGlobal, provider.instructFile) : join2(projectDir, provider.instructFile);
+    const filePath = scopedInstructionPath(provider, projectDir, scope);
+    if (filePath === null) continue;
     if (injected.has(filePath)) continue;
     injected.add(filePath);
     const action = await inject(filePath, content);
@@ -847,10 +928,13 @@ async function ensureProviderInstructionFile(providerId, projectDir, options) {
     throw new Error(`Unknown provider: "${providerId}". Check CAAMP provider registry.`);
   }
   const scope = options.scope ?? "project";
-  const filePath = scope === "global" ? join2(provider.pathGlobal, provider.instructFile) : join2(projectDir, provider.instructFile);
+  const filePath = scopedInstructionPath(provider, projectDir, scope);
+  if (filePath === null) {
+    throw new Error(`Provider "${providerId}" has no global instruction file (T12379).`);
+  }
   let references = options.references ?? getProviderInstructionReferences(providerId);
   let content = options.content;
-  if (options.delivery !== "verified-references" && references.includes("@.cleo/memory-bridge.md") && !existsSync(join2(dirname4(filePath), ".cleo", "memory-bridge.md"))) {
+  if (options.delivery !== "verified-references" && references.includes("@.cleo/memory-bridge.md") && !existsSync2(join2(dirname4(filePath), ".cleo", "memory-bridge.md"))) {
     references = references.filter((reference) => reference !== "@.cleo/memory-bridge.md");
     content = [
       ...content ?? [],
@@ -880,6 +964,57 @@ async function ensureProviderInstructionFile(providerId, projectDir, options) {
     providerId: provider.id
   };
 }
+function stripBareReferenceLines(content, references) {
+  const refs = new Set(references);
+  const kept = content.split("\n").filter((line) => !refs.has(line.trim()));
+  return kept.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+async function ensureProviderRuleFile(providerId, projectDir, options) {
+  const provider = getProvider(providerId);
+  if (!provider) {
+    throw new Error(`Unknown provider: "${providerId}". Check CAAMP provider registry.`);
+  }
+  const filePath = join2(projectDir, options.relativePath);
+  if (options.onlyIfExists === true && !existsSync2(filePath)) return null;
+  const references = options.references ?? getProviderInstructionReferences(providerId);
+  const body = buildInjectionContent({ references }).trim();
+  const block = buildBlock(body);
+  assertBalancedMarkers(block);
+  const owned = options.preamble !== void 0 ? `${options.preamble}
+${block}
+` : null;
+  return withFileLock(filePath, async () => {
+    const result = (action) => ({
+      filePath,
+      action,
+      providerId: provider.id
+    });
+    if (!existsSync2(filePath)) {
+      if (options.onlyIfExists === true) return null;
+      await writeFileAtomic2({ path: filePath, content: owned ?? `${block}
+` });
+      return result("created");
+    }
+    const existing = await readFile3(filePath, "utf-8");
+    if (existing.length === 0) {
+      assertNotTornRead(filePath, existing, (await stat3(filePath)).size);
+    }
+    if (owned !== null) {
+      if (existing === owned) return result("intact");
+      await writeFileAtomic2({ path: filePath, content: owned });
+      return result("updated");
+    }
+    const hasBlock = parseBlocks(normalizeMarkers(existing).content).length > 0;
+    const base = hasBlock ? existing : stripBareReferenceLines(existing, references).trimEnd();
+    const { content: next, blocksBefore, repaired } = reconcile(base, body, "append");
+    if (next === existing) return result("intact");
+    await writeFileAtomic2({ path: filePath, content: next });
+    if (blocksBefore === 0) return result("added");
+    if (repaired > 0) return result("repaired");
+    if (blocksBefore > 1) return result("consolidated");
+    return result("updated");
+  });
+}
 async function ensureAllProviderInstructionFiles(providerIds, projectDir, options) {
   const results = [];
   const processed = /* @__PURE__ */ new Set();
@@ -889,7 +1024,8 @@ async function ensureAllProviderInstructionFiles(providerIds, projectDir, option
       throw new Error(`Unknown provider: "${providerId}". Check CAAMP provider registry.`);
     }
     const scope = options.scope ?? "project";
-    const filePath = scope === "global" ? join2(provider.pathGlobal, provider.instructFile) : join2(projectDir, provider.instructFile);
+    const filePath = scopedInstructionPath(provider, projectDir, scope);
+    if (filePath === null) continue;
     if (processed.has(filePath)) continue;
     processed.add(filePath);
     const references = options.references ?? getProviderInstructionReferences(providerId);
@@ -949,7 +1085,7 @@ async function writeAgentFileToAllProviders(providerIds, options) {
       continue;
     }
     processed.add(filePath);
-    if (options.skipMissingFolders === true && !existsSync(folder)) {
+    if (options.skipMissingFolders === true && !existsSync2(folder)) {
       continue;
     }
     const action = await inject(filePath, options.content);
@@ -961,6 +1097,8 @@ async function writeAgentFileToAllProviders(providerIds, options) {
 export {
   withFileLock,
   assertNotTornRead,
+  JsonConfigParseError,
+  updateJsonConfigFile,
   getAllProviders,
   getProvider,
   resolveAlias,
@@ -976,12 +1114,15 @@ export {
   providerSupports,
   getSpawnCapableProviders,
   getProvidersBySpawnCapability,
+  resetRegistry,
   getProviderInstructionReferences,
   getProvidersBySkillsPrecedence,
   getEffectiveSkillsPaths,
   buildSkillsMap,
   getProviderCapabilities,
   providerSupportsById,
+  EmbeddedDeliveryDowngradeError,
+  isEmbeddedDelivery,
   blockPattern,
   normalizeMarkers,
   parseBlocks,
@@ -999,6 +1140,7 @@ export {
   dedupeFile,
   dedupeFiles,
   instructionFileCascade,
+  resolveGlobalInstructionPath,
   repairInstructionFiles,
   checkInjection,
   inject,
@@ -1006,8 +1148,9 @@ export {
   checkAllInjections,
   injectAll,
   ensureProviderInstructionFile,
+  ensureProviderRuleFile,
   ensureAllProviderInstructionFiles,
   getProviderAgentFolder,
   writeAgentFileToAllProviders
 };
-//# sourceMappingURL=chunk-G3CEXEW2.js.map
+//# sourceMappingURL=chunk-JELNPPLN.js.map