@aiwg/cli 2026.9.6 → 2026.9.9

package/dist/src/cli/handlers/refresh.js

@@ -13,7 +13,10 @@
  * @issue #173, #174, #482, #557, #694
  */
 import { promises as fs } from 'fs';
+import { execFile } from 'node:child_process';
 import path from 'path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
 import { createScriptRunner } from './script-runner.js';
 import { createUseHandler } from './use.js';
 import { getFrameworkRoot } from '../../channel/manager.mjs';
@@ -21,6 +24,7 @@ import { refreshAllPackages } from '../../packages/registry.js';
 import { resolveActiveProvider } from '../provider-resolution.js';
 import { readAiwgConfig, writeAiwgConfig, hashManifest, getProviderParallelismDefaults, } from '../../config/aiwg-config.js';
 import { discoverProjectLocalBundles } from '../../extensions/project-local-discovery.js';
+import { getProviderArtifactPathStrings } from '../../providers/provider-definitions.js';
 import { collectPackagedAgentInventory, normalizeAgentArtifactName, parseManagedArtifactMarker, } from '../../agents/packaged-agent-inventory.js';
 import * as ui from '../ui.js';
 const PROVIDER_AGENT_DIRS = {
@@ -36,6 +40,48 @@ const PROVIDER_AGENT_DIRS = {
 export async function currentBundledAgentBasenames(frameworkRoot) {
     return new Set((await collectPackagedAgentInventory(frameworkRoot)).keys());
 }
+/**
+ * Basenames of every rule the current package can deploy.
+ *
+ * Symmetric to {@link currentBundledAgentBasenames}. A rule absent from this set
+ * is residue from a deploy model that no longer writes it (#2540).
+ *
+ * Every group that can ship a `rules/` directory must be listed here: the set is
+ * the prune's definition of "still shipped", so a missed group makes live rules
+ * look orphaned and deletes them. `extensions` ships 22 rules and was the group
+ * this nearly lost.
+ */
+export const BUNDLED_RULE_SOURCE_GROUPS = ['frameworks', 'addons', 'plugins', 'extensions'];
+export async function currentBundledRuleBasenames(frameworkRoot) {
+    const names = new Set();
+    const codeRoot = path.join(frameworkRoot, 'agentic', 'code');
+    for (const group of BUNDLED_RULE_SOURCE_GROUPS) {
+        let units;
+        try {
+            units = await fs.readdir(path.join(codeRoot, group), { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const unit of units) {
+            if (!unit.isDirectory())
+                continue;
+            const rulesDir = path.join(codeRoot, group, unit.name, 'rules');
+            let entries;
+            try {
+                entries = await fs.readdir(rulesDir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (entry.isFile() && entry.name.endsWith('.md'))
+                    names.add(entry.name);
+            }
+        }
+    }
+    return names;
+}
 async function readFrameworkVersion(frameworkRoot) {
     try {
         const pkg = JSON.parse(await fs.readFile(path.join(frameworkRoot, 'package.json'), 'utf8'));
@@ -69,12 +115,33 @@ function isOlderManagedVersion(deployedVersion, currentVersion) {
         return true;
     return deployed.prerelease.localeCompare(current.prerelease, undefined, { numeric: true }) < 0;
 }
-export async function pruneStaleManagedAgentFiles(options) {
-    const desired = await currentBundledAgentBasenames(options.frameworkRoot);
-    const currentVersion = options.currentVersion ?? await readFrameworkVersion(options.frameworkRoot);
-    const removals = [];
-    for (const [provider, relDir] of Object.entries(PROVIDER_AGENT_DIRS)) {
-        const dir = path.join(options.projectRoot, relDir);
+const PRUNABLE_ARTIFACT_KINDS = ['agents', 'commands', 'rules'];
+/**
+ * Resolve the on-disk artifact directories for a provider.
+ *
+ * `PROVIDER_AGENT_DIRS` remains the enumeration of providers AIWG can prune;
+ * the command/rule directories come from the provider definitions so the
+ * unit-prune path never drifts from what `aiwg use` actually wrote.
+ */
+function providerArtifactDirs(provider) {
+    const agents = PROVIDER_AGENT_DIRS[provider] ?? null;
+    const declared = getProviderArtifactPathStrings(provider);
+    const usable = (value) => typeof value === 'string' && value.length > 0 && !path.isAbsolute(value) ? value : null;
+    return {
+        agents,
+        commands: usable(declared?.commands),
+        rules: usable(declared?.rules),
+    };
+}
+/** Collect every AIWG-managed (`source: bundled`) artifact in one provider tree. */
+async function collectManagedProviderArtifacts(projectRoot, provider, kinds) {
+    const dirs = providerArtifactDirs(provider);
+    const hits = [];
+    for (const kind of kinds) {
+        const relDir = dirs[kind];
+        if (!relDir)
+            continue;
+        const dir = path.join(projectRoot, relDir);
         let entries;
         try {
             entries = await fs.readdir(dir, { withFileTypes: true });
@@ -85,6 +152,9 @@ export async function pruneStaleManagedAgentFiles(options) {
         for (const entry of entries) {
             if (!entry.isFile() || !entry.name.endsWith('.md'))
                 continue;
+            // Generated indexes are rewritten on every deploy, never orphaned.
+            if (entry.name === 'RULES-INDEX.md' || entry.name === 'RULES-ONDEMAND.md')
+                continue;
             const file = path.join(dir, entry.name);
             let content;
             try {
@@ -96,32 +166,198 @@ export async function pruneStaleManagedAgentFiles(options) {
             const marker = parseManagedArtifactMarker(content);
             if (marker?.source !== 'bundled')
                 continue;
-            const artifactName = normalizeAgentArtifactName(entry.name);
-            const missingFromCurrentPackage = !desired.has(artifactName);
-            // Addons have independent manifest versions. Comparing their managed
-            // marker to the top-level package version makes a successful refresh
-            // delete freshly restored addon agents. Version-based cleanup remains
-            // valid for other provider trees that were not refreshed, while the
-            // active provider removes only artifacts absent from current sources.
-            const fromOlderPackage = provider !== options.provider
-                && currentVersion !== null
-                && isOlderManagedVersion(marker.version, currentVersion);
-            if (!missingFromCurrentPackage && !fromOlderPackage)
+            hits.push({
+                kind,
+                absolutePath: file,
+                relativePath: path.relative(projectRoot, file),
+                version: marker.version,
+                artifactName: normalizeAgentArtifactName(entry.name),
+            });
+        }
+    }
+    return hits;
+}
+export async function detectStaleProviderTrees(options) {
+    const currentVersion = options.currentVersion ?? await readFrameworkVersion(options.frameworkRoot);
+    if (currentVersion === null)
+        return [];
+    const trees = [];
+    for (const provider of Object.keys(PROVIDER_AGENT_DIRS)) {
+        if (provider === options.provider)
+            continue;
+        const hits = (await collectManagedProviderArtifacts(options.projectRoot, provider, PRUNABLE_ARTIFACT_KINDS))
+            .filter((hit) => isOlderManagedVersion(hit.version, currentVersion));
+        if (hits.length === 0)
+            continue;
+        const counts = { agents: 0, commands: 0, rules: 0 };
+        for (const hit of hits)
+            counts[hit.kind] += 1;
+        const oldest = hits
+            .map((hit) => hit.version)
+            .reduce((a, b) => (isOlderManagedVersion(a, b) ? a : b));
+        trees.push({ provider, version: oldest, counts, total: hits.length });
+    }
+    trees.sort((a, b) => a.provider.localeCompare(b.provider));
+    return trees;
+}
+/**
+ * Split project-relative paths into the ones git tracks and the ones it does not (#2509).
+ *
+ * Deleting an ignored, regenerable artifact and deleting a committed file are
+ * not the same act. A project that is not a git repo — or a machine without
+ * git — reports everything as untracked, so the caller behaves as before.
+ */
+export async function partitionTrackedPaths(projectRoot, relativePaths) {
+    if (relativePaths.length === 0)
+        return { tracked: [], untracked: [] };
+    let trackedSet;
+    try {
+        const { stdout } = await execFileAsync('git', ['ls-files', '-z', '--', ...relativePaths], { cwd: projectRoot, maxBuffer: 32 * 1024 * 1024 });
+        trackedSet = new Set(stdout.split('\0').filter(Boolean));
+    }
+    catch {
+        return { tracked: [], untracked: [...relativePaths] };
+    }
+    const tracked = [];
+    const untracked = [];
+    for (const relativePath of relativePaths) {
+        // git reports POSIX separators regardless of platform.
+        (trackedSet.has(relativePath.split(path.sep).join('/')) ? tracked : untracked).push(relativePath);
+    }
+    return { tracked, untracked };
+}
+export async function pruneStaleManagedAgentFiles(options) {
+    const desired = await currentBundledAgentBasenames(options.frameworkRoot);
+    const desiredRules = await currentBundledRuleBasenames(options.frameworkRoot);
+    const currentVersion = options.currentVersion ?? await readFrameworkVersion(options.frameworkRoot);
+    const crossProvider = options.crossProvider ?? 'skip';
+    const removals = [];
+    const trackedSkipped = [];
+    const record = (list, provider, relativePath) => {
+        let entry = list.find((item) => item.provider === provider);
+        if (!entry) {
+            entry = { provider, paths: [] };
+            list.push(entry);
+        }
+        entry.paths.push(relativePath);
+    };
+    for (const provider of Object.keys(PROVIDER_AGENT_DIRS)) {
+        const isTargetProvider = provider === options.provider;
+        // Non-target trees are pruned as a unit or not at all; the refreshed
+        // provider only drops agents whose source no longer ships them.
+        if (!isTargetProvider && crossProvider === 'skip')
+            continue;
+        // Rules were excluded from the target-provider pass, so a project carried
+        // every rule any past version ever deployed. On long-lived projects that is
+        // the bulk of the startup-context budget (#2540).
+        const kinds = isTargetProvider ? ['agents', 'rules'] : PRUNABLE_ARTIFACT_KINDS;
+        const hits = await collectManagedProviderArtifacts(options.projectRoot, provider, kinds);
+        const eligible = hits.filter((hit) => {
+            if (isTargetProvider) {
+                // Addons have independent manifest versions. Comparing their managed
+                // marker to the top-level package version makes a successful refresh
+                // delete freshly restored addon agents, so the active provider removes
+                // only artifacts absent from current sources.
+                if (hit.kind === 'rules')
+                    return !desiredRules.has(path.basename(hit.relativePath));
+                return !desired.has(hit.artifactName);
+            }
+            return currentVersion !== null && isOlderManagedVersion(hit.version, currentVersion);
+        });
+        if (eligible.length === 0)
+            continue;
+        // Only the cross-provider unit prune defers to VCS state.
+        let protectedPaths = new Set();
+        if (!isTargetProvider && !options.allowTrackedDeletes) {
+            const { tracked } = await partitionTrackedPaths(options.projectRoot, eligible.map((hit) => hit.relativePath));
+            protectedPaths = new Set(tracked);
+        }
+        for (const hit of eligible) {
+            if (protectedPaths.has(hit.relativePath)) {
+                record(trackedSkipped, provider, hit.relativePath);
                 continue;
-            const relFile = path.relative(options.projectRoot, file);
+            }
             if (!options.dryRun)
-                await fs.rm(file, { force: true });
-            let providerRemoval = removals.find((item) => item.provider === provider);
-            if (!providerRemoval) {
-                providerRemoval = { provider, paths: [] };
-                removals.push(providerRemoval);
+                await fs.rm(hit.absolutePath, { force: true });
+            record(removals, provider, hit.relativePath);
+        }
+    }
+    for (const list of [removals, trackedSkipped]) {
+        for (const entry of list)
+            entry.paths.sort((a, b) => a.localeCompare(b));
+    }
+    return { removals, trackedSkipped };
+}
+/**
+ * Reconcile `installed.deployedTo` with the artifacts a prune pass left behind (#2506).
+ *
+ * Recorded counts are written by `aiwg use` before the prune runs, so a run
+ * that deletes artifacts otherwise leaves the config permanently claiming
+ * files that are gone. Two cases:
+ *
+ *  - **Unit-pruned provider tree** (a non-refreshed provider removed wholesale):
+ *    every managed agent/command/rule for that provider is gone, so those
+ *    counts drop to zero across all installed bundles. Skills are not part of
+ *    the prune pass and keep their recorded values.
+ *  - **Refreshed provider** (agent orphans only): subtract the removed count
+ *    from the recorded agent totals, largest contributor first, clamped at 0.
+ */
+async function reconcileDeployedToAfterPrune(projectRoot, removals, refreshedProvider) {
+    if (removals.length === 0)
+        return;
+    const config = await readAiwgConfig(projectRoot);
+    if (!config)
+        return;
+    let changed = false;
+    for (const removal of removals) {
+        const unitPruned = removal.provider !== refreshedProvider;
+        const entries = Object.values(config.installed)
+            .filter((entry) => entry.deployedTo?.[removal.provider]);
+        if (entries.length === 0)
+            continue;
+        if (unitPruned) {
+            for (const entry of entries) {
+                const counts = entry.deployedTo[removal.provider];
+                if (counts.agents === 0 && counts.commands === 0 && counts.rules === 0)
+                    continue;
+                counts.agents = 0;
+                counts.commands = 0;
+                counts.rules = 0;
+                changed = true;
             }
-            providerRemoval.paths.push(relFile);
+            continue;
+        }
+        let outstanding = removal.paths.length;
+        const byAgentsDesc = entries
+            .slice()
+            .sort((a, b) => b.deployedTo[removal.provider].agents - a.deployedTo[removal.provider].agents);
+        for (const entry of byAgentsDesc) {
+            if (outstanding <= 0)
+                break;
+            const counts = entry.deployedTo[removal.provider];
+            const deduct = Math.min(counts.agents, outstanding);
+            if (deduct <= 0)
+                continue;
+            counts.agents -= deduct;
+            outstanding -= deduct;
+            changed = true;
         }
     }
-    for (const removal of removals)
-        removal.paths.sort((a, b) => a.localeCompare(b));
-    return removals;
+    if (changed)
+        await writeAiwgConfig(projectRoot, config);
+}
+/**
+ * Whether this run may delete git-tracked artifacts during a cross-provider
+ * prune (#2514).
+ *
+ * Deliberately not derived from `--force`. `--force` governs what gets
+ * *written* — it replaces artifacts AIWG does not currently manage. Deleting
+ * files someone committed, in a provider tree this run was not asked to touch,
+ * is a different decision and gets its own switch, so habitual `--force` use
+ * can never authorise it.
+ */
+export function allowsTrackedDeletes(args) {
+    return args.includes('--prune-tracked');
 }
 /**
  * Parse --flag value pairs from args
@@ -161,6 +397,17 @@ Options:
   --skip-update             Skip the installation update
   --packages-only           Refresh remote packages only
   --provider <name>         Override provider auto-detection
+  --prune-other-providers   Remove stale AIWG-managed trees belonging to
+                            providers this run did not refresh. Off by default:
+                            a provider-scoped refresh never mutates another
+                            provider's deployed surface. Git-tracked files are
+                            always left in place unless --prune-tracked is given.
+  --prune-tracked           Allow --prune-other-providers to delete git-tracked
+                            files. Deleting committed files is a separate
+                            decision from --force, which only governs writes.
+  --force                   Re-write every deployed artifact, replacing files
+                            AIWG does not currently manage. Never authorises
+                            deleting tracked files.
   --channel <name>          Select the update channel (stable or main)
   --frameworks <list>       Re-deploy a comma-separated installed subset
   --model <name>            Override all deployed agent model tiers
@@ -192,6 +439,14 @@ export const refreshHandler = {
         const quiet = hasFlag(ctx.args, '--quiet');
         const skipUpdate = hasFlag(ctx.args, '--skip-update');
         const packagesOnly = hasFlag(ctx.args, '--packages-only');
+        // #2506: cross-provider pruning is opt-in. A provider-scoped refresh must
+        // not silently delete another provider's deployed surface.
+        const pruneOtherProviders = hasFlag(ctx.args, '--prune-other-providers');
+        const forceDeploy = hasFlag(ctx.args, '--force');
+        // #2514: deleting committed files in a tree this run was not asked to touch
+        // is its own decision, not a consequence of asking for a forceful re-write.
+        // `--force` governs what gets written; this governs what gets destroyed.
+        const pruneTracked = allowsTrackedDeletes(ctx.args);
         const provider = parseFlag(ctx.args, '--provider');
         const channel = parseFlag(ctx.args, '--channel');
         const frameworksArg = parseFlag(ctx.args, '--frameworks');
@@ -313,6 +568,9 @@ export const refreshHandler = {
                         '--target', ctx.cwd,
                         '--yes',
                         '--json',
+                        // #2507: give operators a reclaim path for artifacts an older
+                        // AIWG left behind without a managed marker.
+                        ...(forceDeploy ? ['--force'] : []),
                         ...modelDeployArgs,
                     ],
                     rawArgs: ['use', fw],
@@ -364,32 +622,93 @@ export const refreshHandler = {
         catch {
             // Non-fatal — refresh continues
         }
-        // Step 4.5: Stale deployment check (#621, #1460, #1799)
+        // Step 4.5: Stale deployment check (#621, #1460, #1799, #2506)
         if (!quiet)
             ui.info('Checking for stale deployments...');
+        // A modifier with nothing to modify is almost always a mistyped intent.
+        if (pruneTracked && !pruneOtherProviders && !quiet) {
+            ui.warn('--prune-tracked has no effect without --prune-other-providers; nothing was removed.');
+        }
         let staleAgentRemovals = [];
-        if (!dryRun && deploymentFailures.length === 0) {
+        let trackedSkipped = [];
+        // A dry run still reports what a real run would remove. Skipping the pass
+        // entirely meant `refresh --dry-run` printed "Checking for stale deployments..."
+        // and nothing else, so orphaned artifacts were invisible until they had
+        // pushed the project over its context budget (#2540).
+        if (deploymentFailures.length === 0) {
             try {
-                staleAgentRemovals = await pruneStaleManagedAgentFiles({
+                const pruneResult = await pruneStaleManagedAgentFiles({
                     projectRoot: ctx.cwd,
                     frameworkRoot,
                     provider: detectedProvider,
+                    crossProvider: pruneOtherProviders ? 'prune' : 'skip',
+                    allowTrackedDeletes: pruneTracked,
+                    dryRun,
                 });
+                staleAgentRemovals = pruneResult.removals;
+                trackedSkipped = pruneResult.trackedSkipped;
+                if (trackedSkipped.length > 0 && !quiet) {
+                    const total = trackedSkipped.reduce((sum, item) => sum + item.paths.length, 0);
+                    ui.warn(`Left ${total} git-tracked AIWG-managed file${total === 1 ? '' : 's'} in place ` +
+                        `across ${trackedSkipped.length} provider${trackedSkipped.length === 1 ? '' : 's'}`);
+                    for (const skipped of trackedSkipped) {
+                        const shown = skipped.paths.slice(0, 3).join(', ');
+                        const remainder = skipped.paths.length - 3;
+                        ui.dim(`    ${skipped.provider}: ${skipped.paths.length} (${shown}${remainder > 0 ? `, ...and ${remainder} more` : ''})`);
+                    }
+                    ui.dim("    These are committed files. Add --prune-tracked to remove them as well.");
+                }
                 if (staleAgentRemovals.length > 0 && !quiet) {
                     const total = staleAgentRemovals.reduce((sum, item) => sum + item.paths.length, 0);
-                    ui.success(`Removed ${total} stale AIWG-managed agent file${total === 1 ? '' : 's'} ` +
+                    ui.warn(`${dryRun ? 'Would remove' : 'Removed'} ${total} stale AIWG-managed file${total === 1 ? '' : 's'} ` +
                         `across ${staleAgentRemovals.length} provider${staleAgentRemovals.length === 1 ? '' : 's'}`);
                     for (const removal of staleAgentRemovals) {
                         const shown = removal.paths.slice(0, 3).join(', ');
                         const remainder = removal.paths.length - 3;
                         ui.dim(`    ${removal.provider}: ${removal.paths.length} (${shown}${remainder > 0 ? `, ...and ${remainder} more` : ''})`);
                     }
+                    ui.dim(dryRun
+                        ? '    Re-run without --dry-run to remove them.'
+                        : '    Review `git status` before committing — deployed artifacts may be tracked.');
+                }
+                // #2506: keep the recorded deployment state consistent with what the
+                // prune actually left on disk, so a later run does not trust counts
+                // for artifacts that no longer exist. A dry run deleted nothing, so the
+                // recorded state is already accurate.
+                if (!dryRun) {
+                    await reconcileDeployedToAfterPrune(ctx.cwd, staleAgentRemovals, pruneOtherProviders ? detectedProvider : null);
                 }
             }
             catch {
                 if (!quiet)
                     ui.dim('  Agent orphan cleanup skipped (non-critical)');
             }
+            // #2506: a provider-scoped refresh reports other providers' stale trees
+            // instead of mutating them. Silent cross-provider deletion destroyed
+            // git-tracked artifacts and left half-deployed surfaces behind.
+            if (!pruneOtherProviders) {
+                try {
+                    const staleTrees = await detectStaleProviderTrees({
+                        projectRoot: ctx.cwd,
+                        frameworkRoot,
+                        provider: detectedProvider,
+                    });
+                    for (const tree of staleTrees) {
+                        const breakdown = ['agents', 'commands', 'rules']
+                            .filter((kind) => tree.counts[kind] > 0)
+                            .map((kind) => `${tree.counts[kind]} ${kind}`)
+                            .join(', ');
+                        ui.warn(`Stale ${tree.provider} deployment: ${tree.total} AIWG-managed file(s) from v${tree.version} ` +
+                            `(${breakdown}) — this run refreshed ${detectedProvider ?? 'the active provider'} only`);
+                        ui.dim(`    Refresh it with 'aiwg refresh --provider ${tree.provider}', ` +
+                            `or remove it with 'aiwg refresh --prune-other-providers'`);
+                    }
+                }
+                catch {
+                    if (!quiet)
+                        ui.dim('  Stale provider tree check skipped (non-critical)');
+                }
+            }
             try {
                 const { getFrameworkRoot } = await import('../../channel/manager.mjs');
                 const { join } = await import('path');
@@ -420,6 +739,15 @@ export const refreshHandler = {
                             ui.warn(`Stale deployment: ${name} — run 'aiwg use ${name}' to redeploy`);
                         }
                     }
+                    else if (staleAgentRemovals.length > 0) {
+                        // #2506: a run that deleted artifacts is not an "up to date" run.
+                        const removed = staleAgentRemovals.reduce((sum, item) => sum + item.paths.length, 0);
+                        if (!quiet) {
+                            ui.warn(dryRun
+                                ? `Deployments current, but ${removed} stale artifact(s) would be removed — review the list above`
+                                : `Deployments current, but ${removed} stale artifact(s) were removed this run — review the list above`);
+                        }
+                    }
                     else {
                         if (!quiet)
                             ui.success('All deployments up to date');