@aiwg/cli 2026.8.8 → 2026.8.10

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

@@ -36,16 +36,22 @@ import { installAiwgHooks } from '../../extensions/claude-hooks-installer.js';
 import { detectScope, mirrorToUserScope, rejectOpenClawProjectScope, USER_SCOPE_PATHS, } from '../scope-resolver.js';
 import { maybeWarnProjectIsolation } from '../project-isolation/index.js';
 import { formatWorkspaceSignalPlan, includedBundleIds, resolveWorkspaceSignalPlan, writeWorkspaceSignalPlan, } from '../workspace-signals.js';
-import { getProviderArtifactPathStrings, getProviderKernelSkillPath, normalizeProviderDefinitionId, } from '../../providers/provider-definitions.js';
+import { getProviderArtifactPathStrings, getProviderDefinition, getProviderKernelSkillPath, normalizeProviderDefinitionId, } from '../../providers/provider-definitions.js';
 // Module-level guard so the iteration loops further down (which re-enter
 // execute() per framework/provider) don't re-emit the warning each pass.
 // Reset is not needed: a single CLI process is one user invocation.
 let projectIsolationChecked = false;
+// Non-zero only while the outer `aiwg use --json` orchestration wrapper is
+// collecting child-process output. The CLI is single-command-per-process;
+// recursive provider expansion shares this guard intentionally.
+let machineReadableUseDepth = 0;
 // Context-pipeline: emits WORKSPACE.md + AIWG.md + provider adapters last.
 // for non-Claude providers per ADR-1 (.aiwg/architecture/adr-agents-md-aggregation.md).
 // Distinct from agentsmith (which creates subagent personas).
 import { generate as generateContextFiles, discoverDeployedArtifacts, } from '../../smiths/context-pipeline/index.js';
 import { verifyModelWrapperDeployment } from '../../models/wrapper-deployment.js';
+import { loadGraphIndexFile } from '../../artifacts/index-reader.js';
+import { aggregateUseDeploymentResult, buildDryRunUseResult, renderUseDeploymentResult, verifyProviderDeployment, } from '../services/deployment-verification.js';
 /**
  * Valid framework identifiers
  */
@@ -517,11 +523,13 @@ async function runPreDeployCollisionCheck(opts) {
         sourceSkillsDir,
     });
     const report = formatCollisionReport(results, { verbose });
-    if (report) {
+    if (report && machineReadableUseDepth === 0) {
         process.stderr.write(report + '\n');
     }
     if (hasBlockingCollisions(results) && !force) {
-        process.stderr.write('\nDeployment blocked. Use --force to override.\n');
+        if (machineReadableUseDepth === 0) {
+            process.stderr.write('\nDeployment blocked. Use --force to override.\n');
+        }
         return false;
     }
     return true;
@@ -559,7 +567,7 @@ const NEXT_STEPS = {
     'warp/sdlc': agenticNextSteps('Open Warp:         Start a Warp session in this project root.'),
     'copilot/sdlc': agenticNextSteps('Open VS Code:      Open this workspace and use Copilot Chat.'),
     'codex/sdlc': agenticNextSteps('Open Codex:        Restart Codex in this project root.'),
-    'windsurf/sdlc': agenticNextSteps('Open Windsurf:     Open this project in Windsurf and ask Cascade for AIWG status.'),
+    'windsurf/sdlc': agenticNextSteps('Open Devin Desktop: Open this project in Devin Desktop and ask Devin for AIWG status.'),
     'openclaw/sdlc': agenticNextSteps('Start OpenClaw:    Open OpenClaw with this project workspace.'),
     'openclaw/marketing': agenticNextSteps('Start OpenClaw:    Open OpenClaw with this project workspace.'),
     'openclaw/all': agenticNextSteps('Start OpenClaw:    Open OpenClaw with this project workspace.'),
@@ -575,9 +583,6 @@ export function nextStepsFor(framework, provider = 'claude') {
     const steps = NEXT_STEPS[providerKey] ?? NEXT_STEPS[framework] ?? NEXT_STEPS.sdlc;
     return steps.map((step) => step.replace('{{aiwg-regenerate}}', regenerateInvocation));
 }
-function printNextSteps(framework, provider = 'claude') {
-    ui.section('Next steps:', nextStepsFor(framework, provider));
-}
 /**
  * Per-provider session-reload requirement after `aiwg use`.
  *
@@ -613,8 +618,8 @@ const SESSION_RELOAD_NOTICE = {
         rationale: 'Warp aggregates context from WARP.md when a new tab spawns; existing tabs keep the prior version.',
     },
     windsurf: {
-        action: 'Restart Windsurf or reload the workspace so the aggregated AGENTS.md is re-parsed.',
-        rationale: 'Windsurf reads AGENTS.md once per workspace session.',
+        action: 'Restart Devin Desktop or reload the workspace so the aggregated AGENTS.md is re-parsed.',
+        rationale: 'Devin Desktop reads the Windsurf-compatible AGENTS.md once per workspace session.',
     },
     factory: {
         action: 'Restart your Factory droid runtime to pick up new entries in .factory/droids/.',
@@ -723,18 +728,6 @@ async function countDeployedArtifacts(target, paths, provider) {
         behaviors: await countDirs(paths.behaviors),
     };
 }
-async function countDiscoverableSkills(aiwgRoot) {
-    try {
-        const { loadGraphIndexFile } = await import('../../artifacts/index-reader.js');
-        const index = loadGraphIndexFile(aiwgRoot, 'metadata.json', 'framework');
-        if (!index?.entries)
-            return null;
-        return Object.values(index.entries).filter(entry => entry.type === 'skill').length;
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * Detect forge targets from .git/config remote URLs.
  * Returns a list of forge types found: 'github' | 'gitea'
@@ -1106,7 +1099,7 @@ async function deployProjectLocalBundles(opts) {
     const upstream = await buildUpstreamRegistry({ frameworkRoot });
     const shadowResult = await resolveShadows(targetBundles, upstream);
     const report = formatShadowReport(shadowResult);
-    if (report) {
+    if (report && machineReadableUseDepth === 0) {
         process.stderr.write(report + '\n');
     }
     // #1037/#1049 — Activity log per shadow resolution
@@ -1237,15 +1230,12 @@ function resolveBuiltInProviderForUse(provider) {
 }
 function unsupportedProviderMessage(provider) {
     const normalized = provider.trim().toLowerCase();
-    if (normalized === 'devin' || normalized === 'devin-cli') {
+    if (normalized === 'devin-cli') {
         return [
             `Unsupported provider: ${provider}`,
             '',
-            'Devin Desktop is supported through the Windsurf compatibility adapter:',
-            '  aiwg use sdlc --provider windsurf',
-            '  aiwg use sdlc --provider devin-desktop',
-            '',
-            'Devin CLI has distinct rules/skills surfaces and is recorded as future-provider metadata; AIWG does not emit .devin/ provider output yet.',
+            'Devin CLI has distinct rules/skills surfaces and is not a deployable AIWG provider yet.',
+            'Use --provider devin for Devin Desktop deployments.',
         ].join('\n');
     }
     return null;
@@ -1670,6 +1660,46 @@ async function generateGlobalProjectContext(opts) {
         },
     });
 }
+async function ensurePostDeployPhases(opts) {
+    const currentIndex = loadGraphIndexFile(opts.frameworkRoot, 'metadata.json', 'framework');
+    const builtAt = currentIndex ? Date.parse(currentIndex.builtAt) : Number.NaN;
+    const startedAt = Date.parse(opts.invocationStartedAt);
+    if (!Number.isFinite(builtAt) || builtAt + 2_000 < startedAt) {
+        try {
+            const { buildIndex } = await import('../../artifacts/index-builder.js');
+            await buildIndex(opts.frameworkRoot, { graph: 'framework', explicit: false });
+        }
+        catch {
+            // The shared verifier reports the index failure with stable remediation.
+        }
+    }
+    if (opts.args.includes('--no-context-files'))
+        return;
+    const paths = getProviderPaths(opts.provider);
+    const sections = await discoverDeployedArtifacts(opts.projectPath, {
+        agents: paths.agents,
+        rules: paths.rules,
+        skills: paths.skills,
+        behaviors: paths.behaviors,
+    });
+    try {
+        await generateContextFiles({
+            provider: opts.provider,
+            projectPath: opts.projectPath,
+            sections,
+            detectExistingFiles: true,
+            force: opts.args.includes('--force-context-files'),
+            skip: {
+                workspaceMd: opts.args.includes('--no-workspace-md'),
+                aiwgMd: opts.args.includes('--no-aiwg-md'),
+                agentsMd: opts.args.includes('--no-agents-md'),
+            },
+        });
+    }
+    catch {
+        // The shared verifier reports context or provider-wiring failures.
+    }
+}
 async function deploySourceDirectory(opts) {
     const args = [
         '--source', opts.source,
@@ -1820,7 +1850,158 @@ export class UseHandler {
     description = 'Deploy AIWG framework to project or user scope';
     category = 'framework';
     aliases = [];
+    orchestrationDepth = 0;
     async execute(ctx) {
+        const requestedBundle = firstUsePositional(ctx.args)
+            ?? (ctx.args[0] === '--profile' ? 'all' : undefined);
+        const bypassOrchestration = this.orchestrationDepth > 0
+            || !requestedBundle
+            || requestedBundle === 'cockpit'
+            || ctx.args.includes('--workspace-signals');
+        if (bypassOrchestration)
+            return this.executeCore(ctx);
+        this.orchestrationDepth += 1;
+        try {
+            return await this.executeOrchestrated(ctx, requestedBundle);
+        }
+        finally {
+            this.orchestrationDepth -= 1;
+        }
+    }
+    async executeOrchestrated(ctx, requestedBundle) {
+        const startedAt = new Date().toISOString();
+        const json = ctx.args.includes('--json');
+        const coreArgs = ctx.args.filter((arg) => arg !== '--json');
+        const remainingArgs = removeFirstPositional(coreArgs);
+        const projectDir = getProjectDir(ctx, remainingArgs);
+        const frameworkRoot = ctx.frameworkRoot || await getFrameworkRoot();
+        const config = await readAiwgConfig(projectDir);
+        const requestedProviders = configuredGlobalProviders(remainingArgs, config);
+        const providers = [];
+        for (const requestedProvider of requestedProviders) {
+            const local = await resolveProjectLocalProviderAdapter(projectDir, requestedProvider);
+            const builtIn = local.requestedProvider
+                ? local.provider
+                : resolveBuiltInProviderForUse(local.provider).provider;
+            if (!providers.includes(builtIn))
+                providers.push(builtIn);
+        }
+        const dryRun = remainingArgs.includes('--dry-run');
+        const requestedScope = remainingArgs.includes('--global')
+            ? 'user'
+            : detectScope(remainingArgs);
+        const contextOptOut = [
+            '--no-context-files',
+            '--no-workspace-md',
+            '--no-aiwg-md',
+            '--no-agents-md',
+        ].some((flag) => remainingArgs.includes(flag));
+        const originalConsole = {
+            log: console.log,
+            info: console.info,
+            warn: console.warn,
+            error: console.error,
+        };
+        if (json) {
+            machineReadableUseDepth += 1;
+            console.log = () => { };
+            console.info = () => { };
+            console.warn = () => { };
+            console.error = () => { };
+        }
+        let coreResult;
+        try {
+            coreResult = await this.executeCore({ ...ctx, args: coreArgs });
+        }
+        finally {
+            if (json) {
+                machineReadableUseDepth -= 1;
+                console.log = originalConsole.log;
+                console.info = originalConsole.info;
+                console.warn = originalConsole.warn;
+                console.error = originalConsole.error;
+            }
+        }
+        let result;
+        if (dryRun && coreResult.exitCode === 0) {
+            result = buildDryRunUseResult({
+                projectRoot: projectDir,
+                frameworkRoot,
+                providers,
+                scope: requestedScope,
+                requestedBundles: [requestedBundle],
+                contextOptOut,
+            });
+        }
+        else {
+            if (coreResult.exitCode === 0 && !dryRun && !VALID_FRAMEWORKS.includes(requestedBundle)) {
+                for (const provider of providers) {
+                    await ensurePostDeployPhases({
+                        frameworkRoot,
+                        projectPath: projectDir,
+                        provider,
+                        args: remainingArgs,
+                        invocationStartedAt: startedAt,
+                    });
+                }
+            }
+            const providerResults = [];
+            for (const provider of providers) {
+                const effectiveScope = provider === 'openclaw' || provider === 'openhuman'
+                    ? 'user'
+                    : requestedScope;
+                providerResults.push(await verifyProviderDeployment({
+                    projectRoot: projectDir,
+                    frameworkRoot,
+                    provider,
+                    scope: effectiveScope,
+                    requestedBundles: [requestedBundle],
+                    contextOptOut,
+                    invocationStartedAt: dryRun ? undefined : startedAt,
+                    deploymentExitCode: coreResult.exitCode,
+                    deploymentMessage: coreResult.message,
+                }));
+            }
+            result = aggregateUseDeploymentResult({
+                projectRoot: projectDir,
+                frameworkRoot,
+                scope: requestedScope,
+                requestedBundles: [requestedBundle],
+                providers: providerResults,
+            });
+            if (dryRun) {
+                result.dryRun = true;
+                result.exitClassification = 'failure';
+            }
+        }
+        if (json) {
+            return { exitCode: result.exitCode, message: JSON.stringify(result, null, 2), rawOutput: true };
+        }
+        const verbose = coreArgs.includes('--verbose') || coreArgs.includes('-v');
+        const versionInfo = await getVersionInfo().catch(() => null);
+        const widthFromEnvironment = Number(process.env.COLUMNS);
+        const width = Number.isFinite(process.stdout.columns) && process.stdout.columns > 0
+            ? process.stdout.columns
+            : Number.isFinite(widthFromEnvironment) && widthFromEnvironment > 0
+                ? widthFromEnvironment
+                : 100;
+        const canonicalProvider = result.providers[0]?.provider ?? 'claude';
+        const rendered = renderUseDeploymentResult(result, {
+            verbose,
+            width,
+            version: versionInfo
+                ? { version: versionInfo.version, repository: versionInfo.repoUrl || 'aiwg.io' }
+                : undefined,
+            nextSteps: verbose && result.outcome !== 'failed' && VALID_FRAMEWORKS.includes(requestedBundle)
+                ? nextStepsFor(requestedBundle, canonicalProvider)
+                : undefined,
+        });
+        return {
+            exitCode: result.exitCode,
+            message: [coreResult.message, rendered].filter(Boolean).join('\n'),
+        };
+    }
+    async executeCore(ctx) {
         const explicitTarget = firstUsePositional(ctx.args);
         if (ctx.args.includes('--workspace-signals')) {
             const signalArgs = ctx.args.filter((a) => a !== '--workspace-signals');
@@ -2062,7 +2243,7 @@ export class UseHandler {
             const verbose = remainingArgs.includes('--verbose') || remainingArgs.includes('-v');
             const force = remainingArgs.includes('--force');
             const copyAll = remainingArgs.includes('--copy-all') || remainingArgs.includes('--copy-standard-skills');
-            const quiet = !verbose && !dryRun;
+            const quiet = machineReadableUseDepth > 0 || (!verbose && !dryRun);
             ui.blank();
             ui.header(`  Workspace-aware deployment (${plan.profile})`);
             ui.dim(`  Included frameworks: ${selectedFrameworks.join(', ') || '(none)'}`);
@@ -2135,7 +2316,7 @@ export class UseHandler {
                         target,
                         dryRun,
                         verbose,
-                        quiet: !verbose && !dryRun,
+                        quiet: machineReadableUseDepth > 0 || (!verbose && !dryRun),
                         modelArgs: modelDeployArgs,
                     });
                     if (plResult.failed > 0) {
@@ -2326,13 +2507,19 @@ export class UseHandler {
             const dryRunAddon = remainingArgs.includes('--dry-run');
             const runner = createScriptRunner(frameworkRoot);
             const addonBaseArgs = ['--deploy-commands', '--deploy-skills', '--deploy-rules'];
+            // An explicitly selected upstream addon must be self-contained in the
+            // project. Unlike a full framework deploy, its standard skills cannot be
+            // left index-only: the user asked to install this specific bundle and
+            // its supporting scripts must travel with the skill directory.
+            addonBaseArgs.push('--copy-all');
             addonBaseArgs.push(...modelDeployArgs);
             if (provider)
                 addonBaseArgs.push('--provider', provider);
             if (target)
                 addonBaseArgs.push('--target', target);
             // Forward --copy-all (#1219) so addon-only deploys also honor it.
-            if (remainingArgs.includes('--copy-all') || remainingArgs.includes('--copy-standard-skills')) {
+            if ((remainingArgs.includes('--copy-all') || remainingArgs.includes('--copy-standard-skills'))
+                && !addonBaseArgs.includes('--copy-all')) {
                 addonBaseArgs.push('--copy-all');
             }
             if (dryRunAddon)
@@ -2424,6 +2611,30 @@ export class UseHandler {
                     message: `Failed to register CLI commands: ${error instanceof Error ? error.message : String(error)}`,
                 };
             }
+            // Persist the same lifecycle record frameworks and project-local bundles
+            // receive so status, refresh, doctor, and remove can account for this
+            // upstream addon and every provider artifact it actually deployed.
+            if (!dryRunAddon && config) {
+                try {
+                    const manifestPath = path.join(addonSource, 'manifest.json');
+                    const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+                    // Provider rule aggregation may rename many source rules into one
+                    // managed index. Record this addon's contributed artifact counts,
+                    // matching framework registry semantics, rather than trying to
+                    // attribute shared aggregate filenames after deployment.
+                    const counts = await countBundleSourceArtifacts(addonSource);
+                    const updated = updateInstalled(config, framework, provider, counts, {
+                        version: manifest.version ?? (await getVersionInfo()).version,
+                        source: 'bundled',
+                        manifestHash: await hashManifest(manifestPath),
+                    });
+                    await writeAiwgConfig(projectDir, updated);
+                    config = updated;
+                }
+                catch (error) {
+                    ui.warn(`Addon registry update failed for '${framework}': ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
             // Profile picker for addons with memory topology and multiple templates
             try {
                 const profileManifestPath = path.join(addonSource, 'manifest.json');
@@ -2542,8 +2753,9 @@ export class UseHandler {
         const filteredArgs = deployArgs.filter(a => a !== '--no-utils' && a !== '--no-project-local' && a !== '--ci-hooks-enabled' && a !== '--force' && a !== '--skip-conflicts' && a !== '--no-harness-agents');
         const deployFilteredArgs = removeFlagWithOptionalValue(filteredArgs, '--harness-agents');
         // Pass --quiet to suppress deploy-agents.mjs header/footer in default mode (#460)
-        // Dry-run must not capture output — its purpose is to show what would happen
-        if (!verbose && !dryRun)
+        // Human dry-run remains verbose; machine-readable dry-run captures the
+        // preview so stdout stays a single JSON document.
+        if (machineReadableUseDepth > 0 || (!verbose && !dryRun))
             deployFilteredArgs.push('--quiet');
         // Extract provider and target from remainingArgs to pass to addon deployments
         // Config-first resolution (#621): explicit --provider overrides config, config overrides default 'claude'
@@ -2583,6 +2795,9 @@ export class UseHandler {
         if (unsupportedMessage) {
             return { exitCode: 1, message: unsupportedMessage };
         }
+        if (requestedProvider.trim().toLowerCase() === 'windsurf') {
+            ui.warn("Provider id 'windsurf' is deprecated; use '--provider devin' for Devin Desktop. Existing .windsurf/ output paths remain supported.");
+        }
         const provider = builtInProviderResolution.provider;
         const providerDeployArgs = builtInProviderResolution.requestedProvider
             ? withProviderOverride(deployFilteredArgs, provider)
@@ -2645,14 +2860,15 @@ export class UseHandler {
             }
         }
         // Deploy main framework
-        const quiet = !verbose && !dryRun;
+        const quiet = machineReadableUseDepth > 0 || (!verbose && !dryRun);
         const captureOpts = quiet ? { capture: true } : {};
         if (quiet) {
             const installLabel = framework === 'all'
                 ? 'Installing complete AIWG surface'
                 : `Installing ${framework} framework`;
+            const providerLabel = getProviderDefinition(provider)?.displayName ?? provider;
             ui.blank();
-            console.log(`  ${ui.brandMark()} ${ui.bold(installLabel)}  ${ui.dimText(`for ${provider === 'claude' ? 'Claude Code' : provider}`)}`);
+            console.log(`  ${ui.brandMark()} ${ui.bold(installLabel)}  ${ui.dimText(`for ${providerLabel}`)}`);
             ui.blank();
         }
         const runner = createScriptRunner(ctx.frameworkRoot);
@@ -2886,6 +3102,7 @@ export class UseHandler {
                 behaviorsPath: paths.behaviors,
                 provider,
                 cwd: target,
+                quiet: !verbose,
             });
             if (verbose)
                 console.log('Extension registration complete');
@@ -2905,7 +3122,6 @@ export class UseHandler {
         // (e.g., test fixtures, deploy from npm install rather than the
         // source repo). buildIndex() calls `process.exit(1)` on missing
         // scan dirs which would short-circuit our catch.
-        let discoverableSkillCount = null;
         if (!dryRun) {
             // Build the framework graph against $AIWG_ROOT, not the project's
             // target dir (#1217). The framework source is user-global at
@@ -2937,9 +3153,8 @@ export class UseHandler {
                     // regardless of build cwd.
                     await buildIndex(aiwgRootForIndex, { graph: 'framework', explicit: false });
                     console.log = origLog;
-                    discoverableSkillCount = await countDiscoverableSkills(aiwgRootForIndex);
                     const indexElapsedSec = ((Date.now() - indexStart) / 1000).toFixed(1);
-                    ui.success(`Capability index ready (${indexElapsedSec}s) — agents can search the installed capability set.`);
+                    ui.success(`Capability index ready (${indexElapsedSec}s).`);
                 }
                 catch (error) {
                     console.log = origLog;
@@ -2951,42 +3166,13 @@ export class UseHandler {
                 console.log('Framework source not found; skipping capability index rebuild');
             }
         }
-        // Show completion summary and next steps (default mode only)
+        // Collect deployment counts for registry persistence and the final
+        // orchestrated report. Presentation happens once, after verification, so
+        // users do not see a second competing summary.
         let counts = { agents: 0, commands: 0, skills: 0, rules: 0, behaviors: 0 };
         if (quiet) {
-            // Count deployed artifacts
             const paths = getProviderPaths(provider);
             counts = await countDeployedArtifacts(target, paths, provider);
-            if (counts.agents > 0)
-                ui.deployCount('Agents', counts.agents);
-            if (counts.commands > 0)
-                ui.deployCount('Commands', counts.commands);
-            if (counts.skills > 0)
-                ui.deployCount('Skills', counts.skills);
-            if (discoverableSkillCount !== null)
-                ui.deployCount('Discoverable skills', discoverableSkillCount);
-            if (counts.rules > 0)
-                ui.deployCount('Rules', counts.rules);
-            if (counts.behaviors > 0)
-                ui.deployCount('Behaviors', counts.behaviors);
-            ui.blank();
-            printNextSteps(framework, provider);
-            // #1240: warn the operator that the running session can't see the newly
-            // deployed agents until reloaded. Skipping this notice is what produced
-            // the "Agent type 'software-implementer' not found" symptom on a stale
-            // Claude Code session.
-            ui.blank();
-            printSessionReloadNotice(provider);
-            // Append version confirmation line (#719)
-            try {
-                const versionInfo = await getVersionInfo();
-                ui.blank();
-                const repoStamp = versionInfo.repoUrl || 'aiwg.io';
-                ui.dim(`  AIWG v${versionInfo.version} — ${repoStamp}`);
-            }
-            catch {
-                // Graceful fallback: omit version line if versionInfo unavailable
-            }
         }
         // Deploy CI workflow files when --ci-hooks-enabled is set (#661)
         if (ciHooksEnabled) {