@aiwg/cli 2026.9.6 → 2026.9.9

package/tools/agents/providers/base.mjs

@@ -199,7 +199,7 @@ export function addManagedMarker(content, version, source, style = 'markdown') {
 /**
  * Compute SHA-256 hash of content (hex string).
  */
-function contentHash(content) {
+export function contentHash(content) {
   return createHash('sha256').update(content).digest('hex');
 }
 
@@ -240,9 +240,12 @@ export function updateSidecarManifest(dir, deployedEntries, opts) {
   const existing = readSidecarManifest(dir) || { managed: {} };
 
   for (const entry of deployedEntries) {
-    const { filename, hash, frameworkSlug } = entry;
+    const { filename, hash, frameworkSlug, kind } = entry;
     const sidecarEntry = { hash: `sha256:${hash}`, source, version };
     if (frameworkSlug) sidecarEntry.frameworkSlug = frameworkSlug;
+    // `kind` marks artifacts whose lifecycle is governed elsewhere — currently
+    // only `skill-command` wrappers, which follow their source skill (#2507).
+    if (kind) sidecarEntry.kind = kind;
     existing.managed[filename] = sidecarEntry;
   }
 
@@ -473,6 +476,41 @@ export function injectPlatformInContent(content, targetPlatform) {
  * copies destined for such providers must drop the field entirely. An
  * absent field is the documented "compatible with all platforms" default.
  */
+/**
+ * Remove the `triggers:` field from a deployed rule's frontmatter.
+ *
+ * Rules declare trigger phrases so `aiwg discover` can reach them by the
+ * question an agent asks rather than by their policy name (#2544). That is
+ * index-time metadata: no provider matches a *rule* by trigger, and the agent
+ * reading the deployed rule gains nothing from the list. Shipping it spends
+ * startup context on noise, which is exactly the budget #2540 is defending —
+ * ~2KB across the 16 rules covered today, and ~16KB if every rule adopts.
+ *
+ * Skills are untouched: several providers do match skills by trigger.
+ */
+export function stripTriggersFromContent(content) {
+  const fmMatch = content.match(/^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))([\s\S]*)$/);
+  if (!fmMatch) return content;
+
+  const [, open, fm, close, body] = fmMatch;
+  // Block list form:
+  //   triggers:
+  //     - "am I allowed to do this"
+  let updated = fm.replace(
+    /^triggers:[ \t]*\r?\n(?:[ \t]+-[ \t]+\S[^\r\n]*(?:\r?\n|$))*/m,
+    '',
+  );
+  // Inline form: triggers: ["a", "b"]
+  if (updated === fm) updated = fm.replace(/^triggers:[^\r\n]*(?:\r?\n|$)/m, '');
+
+  if (updated === fm) return content;
+  // An otherwise-empty frontmatter block is dropped rather than left as `---\n---`.
+  if (updated.trim().length === 0) return body.replace(/^\r?\n/, '');
+  // Removing a block mid-frontmatter can leave a trailing blank line before the
+  // closing fence; the deployed file should not carry it.
+  return open + updated.replace(/\s+$/, '') + close + body;
+}
+
 export function stripPlatformsFromContent(content) {
   const fmMatch = content.match(/^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))([\s\S]*)$/);
   if (!fmMatch) return content;
@@ -704,6 +742,13 @@ export function deployFiles(files, destDir, opts, transformFn) {
     const srcContent = fs.readFileSync(f, 'utf8');
     let transformedContent = transformFn ? transformFn(f, srcContent, opts) : srcContent;
 
+    // Rule triggers are index metadata, not something the reading agent needs.
+    // Keyed on the source path so every provider's rule deploy gets it without
+    // eight call sites opting in, and so skill triggers are never touched (#2544).
+    if (/(?:^|[\\/])rules[\\/][^\\/]+$/.test(f)) {
+      transformedContent = stripTriggersFromContent(transformedContent);
+    }
+
     // Inject target platform into agent .md files that use platforms: [all]
     if (injectPlatform && provider && /platforms:\s*\[all\]/.test(transformedContent)) {
       const platformName = PROVIDER_TO_PLATFORM[provider] || provider;
@@ -1342,6 +1387,39 @@ export function resolveAiwgRoot(srcRoot) {
   return null;
 }
 
+/**
+ * Names of every skill AIWG ships, kernel and standard alike (#2511).
+ *
+ * `computeAllKernelNames` filters to kernel skills, but skill-command wrappers
+ * are generated from both tiers, so retiring an orphaned wrapper needs the full
+ * set. Anchored to the AIWG root rather than `srcRoot` for the same reason
+ * `computeAllArtifactBasenames` is: a bundle-scoped deploy must not produce an
+ * empty desired set and retire everything.
+ *
+ * @param {string} srcRoot AIWG repo / install root (or a subdir of it)
+ * @returns {Set<string>|null} skill directory names, or null when no AIWG tree
+ *   is found — callers MUST then skip pruning.
+ */
+export function computeAllSkillNames(srcRoot) {
+  const aiwgRoot = resolveAiwgRoot(srcRoot);
+  if (!aiwgRoot) return null;
+
+  const names = new Set();
+  for (const group of ['frameworks', 'addons']) {
+    const root = path.join(aiwgRoot, 'agentic', 'code', group);
+    if (!fs.existsSync(root)) continue;
+    for (const component of fs.readdirSync(root, { withFileTypes: true })) {
+      if (!component.isDirectory()) continue;
+      const skillsDir = path.join(root, component.name, 'skills');
+      if (!fs.existsSync(skillsDir)) continue;
+      for (const skill of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+        if (skill.isDirectory()) names.add(skill.name);
+      }
+    }
+  }
+  return names;
+}
+
 /**
  * Holistic post-deploy prune of stale AIWG-managed flat artifacts
  * (agents / commands / rules). The flat-file analogue of
@@ -1371,6 +1449,15 @@ export function resolveAiwgRoot(srcRoot) {
 export function pruneStaleAiwgFiles(destDir, desiredStems, opts = {}) {
   const { dryRun = false, verbose = false } = opts;
   const artifactExtensions = opts.artifactExtensions || ['.md', '.mdc'];
+  // When supplied, skill-command wrappers are retired against the set of skills
+  // that still exist rather than exempted outright (#2511). `null`/absent keeps
+  // the blanket exemption, so callers without a skill inventory cannot retire a
+  // wrapper by accident.
+  const skillCommandStems = opts.skillCommandStems instanceof Set
+    ? opts.skillCommandStems
+    : Array.isArray(opts.skillCommandStems)
+      ? new Set(opts.skillCommandStems)
+      : null;
   const removed = [];
   if (!destDir || !fs.existsSync(destDir)) return removed;
 
@@ -1397,6 +1484,15 @@ export function pruneStaleAiwgFiles(destDir, desiredStems, opts = {}) {
 
     if (desired.has(artifactStem(name))) continue;
 
+    // Skill-command wrappers are named after skills, not command sources, so
+    // they are absent from the command desired set by construction — pruning
+    // them against it would delete wrappers the same deploy just wrote (#2507).
+    // They are retired against the skill inventory instead, when one is given
+    // (#2511); without one they stay exempt.
+    if (managed[name]?.kind === 'skill-command') {
+      if (!skillCommandStems || skillCommandStems.has(artifactStem(name))) continue;
+    }
+
     // Ownership gate — never delete a file AIWG didn't deploy.
     let owned = Object.prototype.hasOwnProperty.call(managed, name);
     if (!owned) {
@@ -2878,8 +2974,47 @@ export function cleanupOldRuleFiles(rulesDir, opts = {}) {
  * @param {boolean} opts.skipCommandsMigration - User opted out; warn about duplicates instead
  * @returns {boolean} true if any AIWG command file was removed (or would be in dry-run)
  */
+/**
+ * Commands directories already warned about this process. The stale-command
+ * condition belongs to the directory, not to each deployed framework/addon, so
+ * `aiwg use all` must not repeat it once per unit (#2541).
+ */
+const warnedCommandsDirs = new Set();
+
+/**
+ * AIWG-managed command filenames in a directory — sidecar entries or files
+ * carrying the managed marker. Operator-authored commands and current
+ * skill-command wrappers are excluded.
+ */
+function listManagedCommandFiles(commandsDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(commandsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const sidecar = readSidecarManifest(commandsDir) || { managed: {} };
+  const managed = sidecar.managed || {};
+  const names = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (!entry.name.toLowerCase().endsWith('.md')) continue;
+    if (managed[entry.name]?.kind === 'skill-command') continue;
+    let owned = Object.prototype.hasOwnProperty.call(managed, entry.name);
+    if (!owned) {
+      try {
+        owned = MANAGED_MARKER_RE.test(fs.readFileSync(path.join(commandsDir, entry.name), 'utf8'));
+      } catch {
+        owned = false;
+      }
+    }
+    if (owned) names.push(entry.name);
+  }
+  return names;
+}
+
 export function migrateCommandsDirectory(commandsDir, opts = {}) {
-  const { dryRun = false, skipCommandsMigration = false, verbose = false } = opts;
+  const { dryRun = false, skipCommandsMigration = false, verbose = false, warnOnSkip = true } = opts;
 
   if (!fs.existsSync(commandsDir)) return false;
 
@@ -2887,11 +3022,27 @@ export function migrateCommandsDirectory(commandsDir, opts = {}) {
   if (entries.length === 0) return false;
 
   if (skipCommandsMigration) {
+    // Structural opt-outs (project-local addon bundles) skip the migration because
+    // it does not apply to them, not because the operator declined it. Warning
+    // there is noise, and it fired once per bundle (#2541).
+    if (!warnOnSkip) return false;
+
     const rel = path.relative(process.cwd(), commandsDir);
+    // The condition is a property of the directory, not of each deployed unit;
+    // emit it once per run no matter how many units pass through.
+    if (warnedCommandsDirs.has(commandsDir)) return false;
+    warnedCommandsDirs.add(commandsDir);
+
+    const stale = listManagedCommandFiles(commandsDir);
+    if (stale.length === 0) return false;
+
     console.warn(`\nWarning: commands migration skipped for ${rel}`);
-    console.warn('  Duplicate entries may appear in the command palette because old command');
-    console.warn('  files overlap with newly deployed skills. Remove AIWG command files manually');
-    console.warn(`  to fix: rm ${rel}/<command>.md`);
+    console.warn('  Duplicate entries may appear in the command palette because these old');
+    console.warn('  AIWG command files overlap with newly deployed skills:');
+    for (const name of stale) console.warn(`    ${path.join(rel, name)}`);
+    console.warn('  Resolve automatically by re-running without --skip-commands-migration,');
+    console.warn('  or remove them directly:');
+    console.warn(`    rm ${stale.map((name) => path.join(rel, name)).join(' ')}`);
     return false;
   }
 
@@ -2907,6 +3058,11 @@ export function migrateCommandsDirectory(commandsDir, opts = {}) {
     const lower = entry.name.toLowerCase();
     if (!lower.endsWith('.md')) continue; // only command markdown files
     const filePath = path.join(commandsDir, entry.name);
+    // Skill-command wrappers ARE the current skill surface, not legacy command
+    // files superseded by it. Migrating them away deletes what the same deploy
+    // just wrote — and on a kernel-only run, which does not re-translate, they
+    // are never restored (#2507).
+    if (managed[entry.name]?.kind === 'skill-command') continue;
     let owned = Object.prototype.hasOwnProperty.call(managed, entry.name);
     if (!owned) {
       try {