@bloomreach/brxm-upgrade 0.1.1

package/dist/execution/types.d.ts

@@ -0,0 +1,92 @@
+import type { PlanStep, AutomationLevel } from '../planning/types.js';
+import type { CVScanResult } from '../discovery/scanners/cv-scanner.js';
+/**
+ * User decision for a step.
+ */
+export type StepDecision = 'accept' | 'reject' | 'skip' | 'view_diff' | 'edit';
+/**
+ * Result of executing a single step.
+ */
+export interface StepExecutionResult {
+    stepNumber: number;
+    entryId: string;
+    success: boolean;
+    decision: StepDecision;
+    modifiedFiles: string[];
+    modifiedFileCount: number;
+    error?: string;
+    duration: number;
+}
+/**
+ * A file change to be applied.
+ */
+export interface FileChange {
+    filePath: string;
+    originalContent: string;
+    modifiedContent: string;
+    isNew: boolean;
+}
+/**
+ * Prepared changes for a step before execution.
+ */
+export interface PreparedChanges {
+    step: PlanStep;
+    changes: FileChange[];
+    totalFiles: number;
+    aiAnalysis?: string;
+    isValid: boolean;
+    validationErrors?: string[];
+    message?: string;
+    fallbackToManual?: boolean;
+}
+/**
+ * Execution state persisted between runs.
+ */
+export interface ExecutionState {
+    planFile: string;
+    planGeneratedAt: string;
+    currentStep: number;
+    completedSteps: number[];
+    skippedSteps: number[];
+    failedSteps: number[];
+    startedAt: string;
+    updatedAt: string;
+    isComplete: boolean;
+    /** CV pre-check scan result, stored for post-check comparison */
+    cvPreCheckResult?: CVScanResult;
+}
+/**
+ * Options for executing the upgrade plan.
+ */
+export interface ExecuteOptions {
+    planPath?: string;
+    resumeFromStep?: number;
+    nonInteractive?: boolean;
+    dryRun?: boolean;
+    verbose?: boolean;
+    autoAcceptAutomated?: boolean;
+    skipAI?: boolean;
+}
+/**
+ * Progress callback for execution UI.
+ */
+export interface ExecutionProgress {
+    currentStep: number;
+    totalSteps: number;
+    currentDescription: string;
+    phase: 'preparing' | 'executing' | 'confirming' | 'complete';
+    percentComplete: number;
+}
+/**
+ * Callback type for progress updates.
+ */
+export type ProgressCallback = (progress: ExecutionProgress) => void;
+/**
+ * Interface for step executors (strategy pattern).
+ */
+export interface IStepExecutor {
+    readonly automationLevel: AutomationLevel;
+    prepare(step: PlanStep, projectRoot: string): Promise<PreparedChanges>;
+    apply(prepared: PreparedChanges, projectRoot: string): Promise<FileChange[]>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/execution/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/execution/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AAExE;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,YAAY,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;IACpB,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,YAAY,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE,WAAW,GAAG,WAAW,GAAG,YAAY,GAAG,UAAU,CAAC;IAC7D,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACvE,KAAK,CAAC,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;CAC9E"}

package/dist/execution/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/execution/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/execution/types.ts"],"names":[],"mappings":""}

package/dist/guide/GuideRunner.d.ts

@@ -0,0 +1,62 @@
+import type { AIClient } from '../ai/types.js';
+import type { BrxmUpgradeConfig } from '../config/index.js';
+import type { ManifestLoadOptions } from '../planning/types.js';
+import type { GuideSummary } from './types.js';
+import type { DocsClient } from '../docs/docs-client.js';
+/**
+ * Main orchestrator for the guided upgrade experience.
+ *
+ * Creates and runs the three upgrade phases in order (Discovery,
+ * Planning, Execution), with resume detection, error handling
+ * with retry/exit prompts, and optional AI chat breaks between phases.
+ */
+export declare class GuideRunner {
+    private readonly projectRoot;
+    private readonly config;
+    private readonly manifestOptions;
+    private readonly ai?;
+    private readonly docsClient?;
+    constructor(projectRoot: string, config: BrxmUpgradeConfig, manifestOptions: ManifestLoadOptions, ai?: AIClient | undefined, docsClient?: DocsClient | undefined);
+    /**
+     * Run the guided upgrade from start to finish (or from a resumed checkpoint).
+     *
+     * @returns Summary of the upgrade run including completed/skipped step counts
+     */
+    run(): Promise<GuideSummary>;
+    /**
+     * Create the initial shared context for all phases.
+     */
+    private createContext;
+    /**
+     * Check for existing upgrade artifacts on disk to detect a previous session.
+     */
+    private detectResumeState;
+    /**
+     * Show resume banner and prompt the user to resume or start fresh.
+     *
+     * @returns The phase index to start from (0 = fresh start)
+     */
+    private handleResume;
+    /**
+     * Prompt the user to retry a failed phase or exit.
+     *
+     * @returns true if the user chose to retry
+     */
+    private promptRetryOrExit;
+    /**
+     * Pause between phases so the user can review output.
+     * When AI is available, offers a chat option; otherwise a simple continue prompt.
+     * Uses transitionMessage from the phase result when available.
+     */
+    private offerPhasePause;
+    /**
+     * Export the upgrade plan as a markdown file for use by an AI agent.
+     */
+    private exportPlan;
+    /**
+     * Build a fallback GuideSummary when the ExecutionPhase did not provide one
+     * (e.g., early exit due to failure).
+     */
+    private buildFallbackSummary;
+}
+//# sourceMappingURL=GuideRunner.d.ts.map

package/dist/guide/GuideRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuideRunner.d.ts","sourceRoot":"","sources":["../../src/guide/GuideRunner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,KAAK,EAA4B,YAAY,EAA4B,MAAM,YAAY,CAAC;AACnG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAezD;;;;;;GAMG;AACH,qBAAa,WAAW;IAEpB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;gBAJX,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,iBAAiB,EACzB,eAAe,EAAE,mBAAmB,EACpC,EAAE,CAAC,EAAE,QAAQ,YAAA,EACb,UAAU,CAAC,EAAE,UAAU,YAAA;IAG1C;;;;OAIG;IACG,GAAG,IAAI,OAAO,CAAC,YAAY,CAAC;IAmFlC;;OAEG;IACH,OAAO,CAAC,aAAa;IAUrB;;OAEG;YACW,iBAAiB;IA0D/B;;;;OAIG;YACW,YAAY;IA+C1B;;;;OAIG;YACW,iBAAiB;IAiB/B;;;;OAIG;YACW,eAAe;IA4H7B;;OAEG;YACW,UAAU;IAiBxB;;;OAGG;IACH,OAAO,CAAC,oBAAoB;CAiB7B"}

package/dist/guide/GuideRunner.js

@@ -0,0 +1,390 @@
+/* eslint-disable no-console */
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { getAvailableVersions } from '../planning/manifest-loader.js';
+import { DiscoveryPhase } from './phases/DiscoveryPhase.js';
+import { PlanPhase } from './phases/PlanPhase.js';
+import { ExecutionPhase } from './phases/ExecutionPhase.js';
+import { formatWelcomeBanner, formatIntroExplanation, formatResumeBanner, formatTransition, } from './rendering/formatters.js';
+import { ChatContextBuilder } from './chat/ChatContextBuilder.js';
+import { ChatLoop } from './chat/ChatLoop.js';
+import { pathExists, readTextFile, writeTextFile, joinPaths } from '../utils/fs.js';
+import { generateExportMarkdown } from '../commands/export.js';
+/**
+ * Main orchestrator for the guided upgrade experience.
+ *
+ * Creates and runs the three upgrade phases in order (Discovery,
+ * Planning, Execution), with resume detection, error handling
+ * with retry/exit prompts, and optional AI chat breaks between phases.
+ */
+export class GuideRunner {
+    projectRoot;
+    config;
+    manifestOptions;
+    ai;
+    docsClient;
+    constructor(projectRoot, config, manifestOptions, ai, docsClient) {
+        this.projectRoot = projectRoot;
+        this.config = config;
+        this.manifestOptions = manifestOptions;
+        this.ai = ai;
+        this.docsClient = docsClient;
+    }
+    /**
+     * Run the guided upgrade from start to finish (or from a resumed checkpoint).
+     *
+     * @returns Summary of the upgrade run including completed/skipped step counts
+     */
+    async run() {
+        try {
+            const context = this.createContext();
+            const resumeState = await this.detectResumeState();
+            let startPhaseIndex = 0;
+            const hasResumeState = resumeState.hasDiscovery || resumeState.hasPlan || resumeState.hasExecution;
+            if (hasResumeState) {
+                startPhaseIndex = await this.handleResume(resumeState, context);
+            }
+            else {
+                console.log(formatWelcomeBanner());
+                console.log(formatIntroExplanation());
+                // Fail fast if no manifests are available — the tool can't plan or
+                // execute without them, so there's no point starting discovery.
+                const versions = await getAvailableVersions(this.manifestOptions);
+                if (versions.length === 0) {
+                    console.log(chalk.yellow('No upgrade manifests found.'));
+                    console.log('');
+                    console.log('Manifests are distributed separately. To set them up:');
+                    console.log('');
+                    console.log(`  ${chalk.bold('brxm-upgrade setup-manifests')}`);
+                    console.log('');
+                    console.log('Or manually:');
+                    console.log('  mvn dependency:copy \\');
+                    console.log('    -Dartifact=com.bloomreach.xm:brxm-upgrade-manifests:RELEASE:zip \\');
+                    console.log('    -DoutputDirectory=.brxm-upgrade/ \\');
+                    console.log('    -Dtransitive=false -q');
+                    console.log('  unzip .brxm-upgrade/brxm-upgrade-manifests-*.zip \\');
+                    console.log('    -d .brxm-upgrade/manifests/');
+                    console.log('');
+                    console.log('Then add to .brxmrc:');
+                    console.log('  upgrade:');
+                    console.log('    source: local');
+                    console.log('    localPath: .brxm-upgrade/manifests');
+                    console.log('');
+                    process.exit(1);
+                }
+            }
+            const phases = [
+                new DiscoveryPhase(),
+                new PlanPhase(),
+                new ExecutionPhase(),
+            ];
+            const startTime = Date.now();
+            for (let i = startPhaseIndex; i < phases.length; i++) {
+                const phase = phases[i];
+                const result = await phase.run(context);
+                if (!result.success) {
+                    const shouldRetry = await this.promptRetryOrExit(phase.name, result);
+                    if (shouldRetry) {
+                        i--; // will increment back to the same index
+                        continue;
+                    }
+                    // Exit early with partial summary
+                    return this.buildFallbackSummary(context, startTime);
+                }
+                // Extract GuideSummary from ExecutionPhase data if available
+                if (phase.name === 'Execution' && result.data) {
+                    return result.data;
+                }
+                // Pause between phases so the user can review output before continuing
+                if (phase.canChat && i < phases.length - 1) {
+                    const exitRequested = await this.offerPhasePause(phase, result, context);
+                    if (exitRequested) {
+                        return this.buildFallbackSummary(context, startTime);
+                    }
+                }
+            }
+            return this.buildFallbackSummary(context, startTime);
+        }
+        finally {
+            await this.docsClient?.disconnect();
+        }
+    }
+    /**
+     * Create the initial shared context for all phases.
+     */
+    createContext() {
+        return {
+            projectRoot: this.projectRoot,
+            config: this.config,
+            manifestOptions: this.manifestOptions,
+            ai: this.ai,
+            docsClient: this.docsClient,
+        };
+    }
+    /**
+     * Check for existing upgrade artifacts on disk to detect a previous session.
+     */
+    async detectResumeState() {
+        const baseDir = joinPaths(this.projectRoot, '.brxm-upgrade');
+        const state = {
+            hasDiscovery: false,
+            hasPlan: false,
+            hasExecution: false,
+        };
+        // Check for discovery.json
+        const discoveryPath = joinPaths(baseDir, 'discovery.json');
+        if (await pathExists(discoveryPath)) {
+            try {
+                const content = await readTextFile(discoveryPath);
+                state.discovery = JSON.parse(content);
+                state.hasDiscovery = true;
+            }
+            catch {
+                /* ignore corrupt files */
+            }
+        }
+        // Check for plan.json
+        const planPath = joinPaths(baseDir, 'plan.json');
+        if (await pathExists(planPath)) {
+            try {
+                const content = await readTextFile(planPath);
+                state.plan = JSON.parse(content);
+                state.hasPlan = true;
+            }
+            catch {
+                /* ignore corrupt files */
+            }
+        }
+        // Check for execution-state.json
+        const execPath = joinPaths(baseDir, 'execution-state.json');
+        if (await pathExists(execPath)) {
+            try {
+                const content = await readTextFile(execPath);
+                state.executionState = JSON.parse(content);
+                state.hasExecution = true;
+            }
+            catch {
+                /* ignore corrupt files */
+            }
+        }
+        // Check for upgrade-state.json
+        const upgradePath = joinPaths(baseDir, 'upgrade-state.json');
+        if (await pathExists(upgradePath)) {
+            try {
+                const content = await readTextFile(upgradePath);
+                state.upgradeState = JSON.parse(content);
+            }
+            catch {
+                /* ignore corrupt files */
+            }
+        }
+        return state;
+    }
+    /**
+     * Show resume banner and prompt the user to resume or start fresh.
+     *
+     * @returns The phase index to start from (0 = fresh start)
+     */
+    async handleResume(resumeState, context) {
+        console.log(formatResumeBanner(resumeState));
+        const { choice } = (await inquirer.prompt([
+            {
+                type: 'select',
+                name: 'choice',
+                message: 'Would you like to resume or start fresh?',
+                choices: [
+                    { name: 'Resume from where I left off', value: 'resume' },
+                    { name: 'Start fresh (discard previous progress)', value: 'fresh' },
+                ],
+            },
+        ]));
+        if (choice === 'fresh')
+            return 0;
+        // Populate context from resume state and determine start phase
+        if (resumeState.hasExecution && resumeState.executionState && resumeState.plan) {
+            context.discovery = resumeState.discovery;
+            context.plan = resumeState.plan;
+            context.executionState = resumeState.executionState;
+            context.currentVersion = resumeState.plan.fromVersion;
+            context.targetVersion = resumeState.plan.toVersion;
+            return 2; // skip to ExecutionPhase
+        }
+        if (resumeState.hasPlan && resumeState.plan) {
+            context.discovery = resumeState.discovery;
+            context.plan = resumeState.plan;
+            context.currentVersion = resumeState.plan.fromVersion;
+            context.targetVersion = resumeState.plan.toVersion;
+            return 2; // skip to ExecutionPhase
+        }
+        if (resumeState.hasDiscovery && resumeState.discovery) {
+            context.discovery = resumeState.discovery;
+            context.currentVersion = resumeState.upgradeState?.currentVersion
+                ?? resumeState.discovery.build.brxmVersion;
+            if (resumeState.upgradeState?.targetVersion) {
+                context.targetVersion = resumeState.upgradeState.targetVersion;
+                return 1; // skip to PlanPhase
+            }
+            return 0;
+        }
+        return 0;
+    }
+    /**
+     * Prompt the user to retry a failed phase or exit.
+     *
+     * @returns true if the user chose to retry
+     */
+    async promptRetryOrExit(phaseName, result) {
+        const errorDetail = result.error ?? result.summary;
+        const { choice } = (await inquirer.prompt([
+            {
+                type: 'select',
+                name: 'choice',
+                message: `Phase "${phaseName}" failed: ${errorDetail}. What would you like to do?`,
+                choices: [
+                    { name: 'Retry this phase', value: 'retry' },
+                    { name: 'Exit', value: 'exit' },
+                ],
+            },
+        ]));
+        return choice === 'retry';
+    }
+    /**
+     * Pause between phases so the user can review output.
+     * When AI is available, offers a chat option; otherwise a simple continue prompt.
+     * Uses transitionMessage from the phase result when available.
+     */
+    async offerPhasePause(phase, result, context) {
+        console.log('');
+        if (result.transitionMessage) {
+            console.log(formatTransition(result.transitionMessage));
+        }
+        // Use transitionMessage.continuePrompt if available
+        const promptMessage = result.transitionMessage
+            ? result.transitionMessage.continuePrompt
+            : `${phase.name} phase complete. ${result.summary}`;
+        const canExport = phase.name === 'Plan' && context.plan && context.discovery;
+        if (this.ai) {
+            // Loop so user can export or chat and then return to the same menu
+            while (true) {
+                const choices = [
+                    { name: 'Continue to next phase', value: 'continue' },
+                ];
+                if (canExport) {
+                    choices.push({ name: 'Export plan for AI agent', value: 'export' });
+                }
+                choices.push({ name: 'Ask questions about the results first', value: 'chat' });
+                choices.push({ name: 'Exit', value: 'exit' });
+                const { choice } = (await inquirer.prompt([
+                    {
+                        type: 'select',
+                        name: 'choice',
+                        message: promptMessage,
+                        choices,
+                    },
+                ]));
+                if (choice === 'continue') {
+                    break;
+                }
+                if (choice === 'export') {
+                    try {
+                        await this.exportPlan(context);
+                    }
+                    catch (err) {
+                        console.log(chalk.red(`  Export failed: ${err instanceof Error ? err.message : String(err)}`));
+                    }
+                    continue;
+                }
+                if (choice === 'chat') {
+                    const contextBuilder = new ChatContextBuilder();
+                    const chatContext = contextBuilder.buildPhaseContext(phase.name, result.summary, context.discovery, context.plan);
+                    const chatLoop = new ChatLoop(this.ai);
+                    await chatLoop.run(chatContext, contextBuilder.buildSystemPrompt());
+                    continue;
+                }
+                if (choice === 'exit') {
+                    console.log(chalk.dim('  Take your time — re-run when you\'re ready.'));
+                    return true;
+                }
+            }
+            return false;
+        }
+        else if (canExport) {
+            // Without AI but with exportable plan: offer a select menu
+            while (true) {
+                const { choice } = (await inquirer.prompt([
+                    {
+                        type: 'select',
+                        name: 'choice',
+                        message: promptMessage,
+                        choices: [
+                            { name: 'Continue to execution', value: 'continue' },
+                            { name: 'Export plan for AI agent', value: 'export' },
+                            { name: 'Exit', value: 'exit' },
+                        ],
+                    },
+                ]));
+                if (choice === 'continue') {
+                    return false;
+                }
+                if (choice === 'export') {
+                    try {
+                        await this.exportPlan(context);
+                    }
+                    catch (err) {
+                        console.log(chalk.red(`  Export failed: ${err instanceof Error ? err.message : String(err)}`));
+                    }
+                    continue;
+                }
+                if (choice === 'exit') {
+                    console.log(chalk.dim('  Take your time — re-run when you\'re ready.'));
+                    return true;
+                }
+            }
+        }
+        else {
+            const { ready } = (await inquirer.prompt([
+                {
+                    type: 'confirm',
+                    name: 'ready',
+                    message: `${promptMessage} Ready to continue?`,
+                    default: true,
+                },
+            ]));
+            if (!ready) {
+                console.log(chalk.dim('  Take your time — re-run when you\'re ready.'));
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Export the upgrade plan as a markdown file for use by an AI agent.
+     */
+    async exportPlan(context) {
+        if (!context.plan || !context.discovery)
+            return;
+        const outputPath = joinPaths(context.projectRoot, context.config.output.exportPath, 'upgrade-plan.md');
+        const markdown = generateExportMarkdown(context.plan, context.discovery);
+        await writeTextFile(outputPath, markdown);
+        console.log('');
+        console.log(chalk.green('\u2714')
+            + ` Exported upgrade plan to ${context.config.output.exportPath}/upgrade-plan.md (${context.plan.summary.totalSteps} steps)`);
+        console.log('');
+    }
+    /**
+     * Build a fallback GuideSummary when the ExecutionPhase did not provide one
+     * (e.g., early exit due to failure).
+     */
+    buildFallbackSummary(context, startTime) {
+        const results = context.executionResults ?? [];
+        return {
+            fromVersion: context.currentVersion ?? 'unknown',
+            toVersion: context.targetVersion ?? 'unknown',
+            completedSteps: results.filter((r) => r.success && r.decision === 'accept').length,
+            skippedSteps: results.filter((r) => r.decision === 'skip').length,
+            manualStepsRemaining: context.plan?.steps.filter((s) => !results.some((r) => r.stepNumber === s.stepNumber && r.success && r.decision === 'accept') && s.automatable === 'false') ?? [],
+            duration: Date.now() - startTime,
+        };
+    }
+}
+//# sourceMappingURL=GuideRunner.js.map

package/dist/guide/GuideRunner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuideRunner.js","sourceRoot":"","sources":["../../src/guide/GuideRunner.ts"],"names":[],"mappings":"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"}

package/dist/guide/chat/ChatContextBuilder.d.ts

@@ -0,0 +1,44 @@
+import type { ProjectContext } from '../../discovery/types.js';
+import type { PlanStep, UpgradePlan } from '../../planning/types.js';
+interface FileContent {
+    path: string;
+    content: string;
+}
+/**
+ * Builds focused AI context windows for guide interactions.
+ * Each method composes a context string from relevant artifacts,
+ * keeping token usage bounded per interaction type.
+ */
+export declare class ChatContextBuilder {
+    /**
+     * System prompt that defines the AI's role.
+     */
+    buildSystemPrompt(): string;
+    /**
+     * Build context for phase-level chat (between phases).
+     */
+    buildPhaseContext(phaseName: string, phaseSummary: string, discovery?: ProjectContext, plan?: UpgradePlan): string;
+    /**
+     * Build context for step-level coaching (during execution).
+     */
+    buildStepContext(step: PlanStep, discovery?: ProjectContext): string;
+    /**
+     * Build context for AI fix generation.
+     */
+    buildFixContext(step: PlanStep, discovery: ProjectContext | undefined, files: FileContent[]): string;
+    /**
+     * Build a prompt for AI-generated version summary in a customer-friendly format.
+     *
+     * @param manifestDescriptions - List of manifest entry description strings to summarize
+     * @returns A prompt string that instructs the AI to respond with JSON in the form:
+     *   `{ "headline": string, "bullets": string[] }` (up to 4 bullets).
+     *   Callers such as {@link DiscoveryPhase.buildSummary} must `JSON.parse()` the
+     *   response and handle parse failures, as the AI may occasionally deviate from
+     *   the requested format.
+     */
+    buildVersionSummaryPrompt(manifestDescriptions: string[]): string;
+    private condensedDiscovery;
+    private condensedPlan;
+}
+export {};
+//# sourceMappingURL=ChatContextBuilder.d.ts.map

package/dist/guide/chat/ChatContextBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatContextBuilder.d.ts","sourceRoot":"","sources":["../../../src/guide/chat/ChatContextBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAErE,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,qBAAa,kBAAkB;IAC7B;;OAEG;IACH,iBAAiB,IAAI,MAAM;IAU3B;;OAEG;IACH,iBAAiB,CACf,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,SAAS,CAAC,EAAE,cAAc,EAC1B,IAAI,CAAC,EAAE,WAAW,GACjB,MAAM;IAaT;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,cAAc,GAAG,MAAM;IA6BpE;;OAEG;IACH,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,cAAc,GAAG,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,MAAM;IAapG;;;;;;;;;OASG;IACH,yBAAyB,CAAC,oBAAoB,EAAE,MAAM,EAAE,GAAG,MAAM;IAYjE,OAAO,CAAC,kBAAkB;IAa1B,OAAO,CAAC,aAAa;CAOtB"}