braeburn 1.3.1 → 1.4.1

package/dist/steps/catalog.js

@@ -0,0 +1,13 @@
+import { pyenvStep, nvmStep, homebrewStep, masStep, ohmyzshStep, npmStep, pipStep, dotnetStep, macosStep, cleanupStep, } from "./index.js";
+export const ALL_STEPS = [
+    pyenvStep,
+    nvmStep,
+    homebrewStep,
+    masStep,
+    ohmyzshStep,
+    npmStep,
+    pipStep,
+    dotnetStep,
+    macosStep,
+    cleanupStep,
+];

package/dist/steps/cleanup.d.ts

@@ -1,3 +1,3 @@
-import { type Step } from "./index.js";
+import type { Step } from "./types.js";
 declare const cleanupStep: Step;
 export default cleanupStep;

package/dist/steps/cleanup.js

@@ -1,4 +1,4 @@
-import { checkCommandExists } from "./index.js";
+import { checkCommandExists } from "./runtime.js";
 const cleanupStep = {
     id: "cleanup",
     name: "Cleanup",

package/dist/steps/dotnet.d.ts

@@ -1,3 +1,3 @@
-import { type Step } from "./index.js";
+import type { Step } from "./types.js";
 declare const dotnetStep: Step;
 export default dotnetStep;

package/dist/steps/dotnet.js

@@ -1,4 +1,4 @@
-import { checkCommandExists } from "./index.js";
+import { checkCommandExists } from "./runtime.js";
 const dotnetStep = {
     id: "dotnet",
     name: ".NET",

package/dist/steps/homebrew.d.ts

@@ -1,3 +1,3 @@
-import { type Step } from "./index.js";
+import type { Step } from "./types.js";
 declare const homebrewStep: Step;
 export default homebrewStep;

package/dist/steps/homebrew.js

@@ -1,4 +1,4 @@
-import { checkCommandExists } from "./index.js";
+import { checkCommandExists } from "./runtime.js";
 const homebrewStep = {
     id: "homebrew",
     name: "Homebrew",

package/dist/steps/index.d.ts

@@ -1,24 +1,5 @@
-import { type OutputLineCallback } from "../runner.js";
-import type { StepLogWriter } from "../logger.js";
-export type StepRunContext = {
-    onOutputLine: OutputLineCallback;
-    logWriter: StepLogWriter;
-    runStep: (shellCommand: string) => Promise<void>;
-    captureOutput: (options: {
-        shellCommand: string;
-    }) => Promise<string>;
-};
-export type StepStage = "runtime" | "tools";
-export type Step = {
-    id: string;
-    name: string;
-    description: string;
-    stage: StepStage;
-    warning?: string;
-    brewPackageToInstall?: string;
-    checkIsAvailable: () => Promise<boolean>;
-    run: (context: StepRunContext) => Promise<void>;
-};
+export type { StepRunContext, StepStage, Step, } from "./types.js";
+export { checkCommandExists, checkPathExists, runStep, createDefaultStepRunContext, } from "./runtime.js";
 export { default as homebrewStep } from "./homebrew.js";
 export { default as masStep } from "./mas.js";
 export { default as ohmyzshStep } from "./ohmyzsh.js";
@@ -29,7 +10,3 @@ export { default as nvmStep } from "./nvm.js";
 export { default as dotnetStep } from "./dotnet.js";
 export { default as macosStep } from "./macos.js";
 export { default as cleanupStep } from "./cleanup.js";
-export declare function checkCommandExists(command: string): Promise<boolean>;
-export declare function checkPathExists(filePath: string): Promise<boolean>;
-export declare function runStep(shellCommand: string, context: StepRunContext): Promise<void>;
-export declare function createDefaultStepRunContext(onOutputLine: OutputLineCallback, logWriter: StepLogWriter): StepRunContext;

package/dist/steps/index.js

@@ -1,4 +1,4 @@
-import { doesShellCommandSucceed, runShellCommand, captureShellCommandOutput, } from "../runner.js";
+export { checkCommandExists, checkPathExists, runStep, createDefaultStepRunContext, } from "./runtime.js";
 export { default as homebrewStep } from "./homebrew.js";
 export { default as masStep } from "./mas.js";
 export { default as ohmyzshStep } from "./ohmyzsh.js";
@@ -9,25 +9,3 @@ export { default as nvmStep } from "./nvm.js";
 export { default as dotnetStep } from "./dotnet.js";
 export { default as macosStep } from "./macos.js";
 export { default as cleanupStep } from "./cleanup.js";
-export async function checkCommandExists(command) {
-    return doesShellCommandSucceed({ shellCommand: `command -v ${command}` });
-}
-export async function checkPathExists(filePath) {
-    return doesShellCommandSucceed({ shellCommand: `test -e "${filePath}"` });
-}
-export async function runStep(shellCommand, context) {
-    await runShellCommand({
-        shellCommand,
-        onOutputLine: context.onOutputLine,
-        logWriter: context.logWriter,
-    });
-}
-export function createDefaultStepRunContext(onOutputLine, logWriter) {
-    const context = {
-        onOutputLine,
-        logWriter,
-        runStep: (shellCommand) => runStep(shellCommand, context),
-        captureOutput: captureShellCommandOutput,
-    };
-    return context;
-}

package/dist/steps/macos.d.ts

@@ -1,3 +1,3 @@
-import { type Step } from "./index.js";
+import { type Step } from "./types.js";
 declare const macosStep: Step;
 export default macosStep;

package/dist/steps/mas.d.ts

@@ -1,3 +1,3 @@
-import { type Step } from "./index.js";
+import type { Step } from "./types.js";
 declare const masStep: Step;
 export default masStep;

package/dist/steps/mas.js

@@ -1,4 +1,4 @@
-import { checkCommandExists } from "./index.js";
+import { checkCommandExists } from "./runtime.js";
 const masStep = {
     id: "mas",
     name: "Mac App Store",

package/dist/steps/npm.d.ts

@@ -1,3 +1,3 @@
-import { type Step } from "./index.js";
+import type { Step } from "./types.js";
 declare const npmStep: Step;
 export default npmStep;

package/dist/steps/npm.js

@@ -1,4 +1,4 @@
-import { checkCommandExists } from "./index.js";
+import { checkCommandExists } from "./runtime.js";
 const npmStep = {
     id: "npm",
     name: "npm",

package/dist/steps/nvm.d.ts

@@ -1,3 +1,3 @@
-import { type Step } from "./index.js";
+import type { Step } from "./types.js";
 declare const nvmStep: Step;
 export default nvmStep;

package/dist/steps/nvm.js

@@ -1,6 +1,6 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { checkPathExists } from "./index.js";
+import { checkPathExists } from "./runtime.js";
 const NVM_DIRECTORY = join(homedir(), ".nvm");
 // nvm is a shell function sourced from nvm.sh — it cannot be invoked as a
 // standalone binary, so we source it explicitly inside each bash invocation.

package/dist/steps/ohmyzsh.d.ts

@@ -1,3 +1,3 @@
-import { type Step } from "./index.js";
+import type { Step } from "./types.js";
 declare const ohmyzshStep: Step;
 export default ohmyzshStep;

package/dist/steps/ohmyzsh.js

@@ -1,6 +1,6 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { checkPathExists } from "./index.js";
+import { checkPathExists } from "./runtime.js";
 const OH_MY_ZSH_UPGRADE_SCRIPT_PATH = join(homedir(), ".oh-my-zsh", "tools", "upgrade.sh");
 const ohmyzshStep = {
     id: "ohmyzsh",

package/dist/steps/pip.d.ts

@@ -1,3 +1,3 @@
-import { type Step } from "./index.js";
+import type { Step } from "./types.js";
 declare const pipStep: Step;
 export default pipStep;

package/dist/steps/pip.js

@@ -1,4 +1,4 @@
-import { checkCommandExists } from "./index.js";
+import { checkCommandExists } from "./runtime.js";
 const PIP_UPDATE_ALL_OUTDATED_SHELL_COMMAND = "pip3 list --outdated --format=columns | tail -n +3 | awk '{print $1}' | xargs -n1 pip3 install -U";
 const pipStep = {
     id: "pip",

package/dist/steps/pyenv.d.ts

@@ -1,3 +1,3 @@
-import { type Step } from "./index.js";
+import type { Step } from "./types.js";
 declare const pyenvStep: Step;
 export default pyenvStep;

package/dist/steps/pyenv.js

@@ -1,4 +1,4 @@
-import { checkCommandExists, } from "./index.js";
+import { checkCommandExists, } from "./runtime.js";
 const FIND_LATEST_STABLE_PYTHON_SHELL_COMMAND = "pyenv install -l | grep -E '^\\s+3\\.[0-9]+\\.[0-9]+$' | grep -vE 'dev|a[0-9]|b[0-9]|rc[0-9]' | tail -1 | tr -d ' '";
 const pyenvStep = {
     id: "pyenv",

package/dist/steps/runtime.d.ts

@@ -0,0 +1,7 @@
+import { type OutputLineCallback } from "../runner.js";
+import type { StepLogWriter } from "../logger.js";
+import type { StepRunContext } from "./types.js";
+export declare function checkCommandExists(command: string): Promise<boolean>;
+export declare function checkPathExists(filePath: string): Promise<boolean>;
+export declare function runStep(shellCommand: string, context: StepRunContext): Promise<void>;
+export declare function createDefaultStepRunContext(onOutputLine: OutputLineCallback, logWriter: StepLogWriter): StepRunContext;

package/dist/steps/runtime.js

@@ -0,0 +1,23 @@
+import { doesShellCommandSucceed, runShellCommand, captureShellCommandOutput, } from "../runner.js";
+export async function checkCommandExists(command) {
+    return doesShellCommandSucceed({ shellCommand: `command -v ${command}` });
+}
+export async function checkPathExists(filePath) {
+    return doesShellCommandSucceed({ shellCommand: `test -e "${filePath}"` });
+}
+export async function runStep(shellCommand, context) {
+    await runShellCommand({
+        shellCommand,
+        onOutputLine: context.onOutputLine,
+        logWriter: context.logWriter,
+    });
+}
+export function createDefaultStepRunContext(onOutputLine, logWriter) {
+    const context = {
+        onOutputLine,
+        logWriter,
+        runStep: (shellCommand) => runStep(shellCommand, context),
+        captureOutput: captureShellCommandOutput,
+    };
+    return context;
+}

package/dist/steps/types.d.ts

@@ -0,0 +1,21 @@
+import type { OutputLineCallback } from "../runner.js";
+import type { StepLogWriter } from "../logger.js";
+export type StepRunContext = {
+    onOutputLine: OutputLineCallback;
+    logWriter: StepLogWriter;
+    runStep: (shellCommand: string) => Promise<void>;
+    captureOutput: (options: {
+        shellCommand: string;
+    }) => Promise<string>;
+};
+export type StepStage = "runtime" | "tools";
+export type Step = {
+    id: string;
+    name: string;
+    description: string;
+    stage: StepStage;
+    warning?: string;
+    brewPackageToInstall?: string;
+    checkIsAvailable: () => Promise<boolean>;
+    run: (context: StepRunContext) => Promise<void>;
+};

package/dist/steps/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ui/currentStep.d.ts

@@ -1,7 +1,6 @@
-import type { Step } from "../steps/index.js";
-import type { StepPhase } from "./state.js";
+import type { DisplayStep, StepPhase } from "./state.js";
 type ActiveStepOptions = {
-    step: Step;
+    step: DisplayStep;
     stepNumber: number;
     totalSteps: number;
     phase: StepPhase;

package/dist/ui/header.d.ts

@@ -1,13 +1,12 @@
-import type { Step } from "../steps/index.js";
-import type { StepPhase, CompletedStepRecord, LogoVisibility } from "./state.js";
+import type { DisplayStep, StepPhase, CompletedStepRecord, LogoVisibility } from "./state.js";
 import type { TerminalDimensions } from "./outputBox.js";
 type LogoLayout = "side-by-side" | "stacked" | "none";
 export declare function determineLogoLayout(logoLines: string[], dimensions?: TerminalDimensions): LogoLayout;
 export declare function stepTrackerIcon(phase: StepPhase): string;
 export declare function isActivePhase(phase: StepPhase): boolean;
-export declare function deriveAllStepPhases(steps: Step[], currentStepIndex: number, currentPhase: StepPhase, completedStepRecords: CompletedStepRecord[]): StepPhase[];
+export declare function deriveAllStepPhases(steps: DisplayStep[], currentStepIndex: number, currentPhase: StepPhase, completedStepRecords: CompletedStepRecord[]): StepPhase[];
 type BuildHeaderOptions = {
-    steps: Step[];
+    steps: DisplayStep[];
     version: string;
     logoVisibility: LogoVisibility;
     currentStepIndex: number;

package/dist/ui/screen.js

@@ -4,13 +4,9 @@ import { buildOutputBoxLines } from "./outputBox.js";
 import { buildPromptLines } from "./prompt.js";
 import { buildVersionReportLines } from "./versionReport.js";
 export function createScreenRenderer(output = process.stdout) {
-    let previousLineCount = 0;
     return (content) => {
-        if (previousLineCount > 0) {
-            output.write(`\x1b[${previousLineCount}A\x1b[J`);
-        }
+        output.write("\x1b[H\x1b[2J");
         output.write(content);
-        previousLineCount = (content.match(/\n/g) ?? []).length;
     };
 }
 export function buildScreen(state, terminalDimensions) {

package/dist/ui/state.d.ts

@@ -1,30 +1 @@
-import type { Step } from "../steps/index.js";
-import type { CommandOutputLine } from "../runner.js";
-export type StepPhase = "pending" | "checking-availability" | "prompting-to-install" | "installing" | "prompting-to-run" | "running" | "complete" | "failed" | "skipped" | "not-available";
-export type CompletedStepRecord = {
-    phase: StepPhase;
-    summaryNote?: string;
-};
-export type CurrentPrompt = {
-    question: string;
-    warning?: string;
-};
-export type ResolvedVersion = {
-    label: string;
-    value: string;
-};
-export type LogoVisibility = "visible" | "hidden";
-export type RunCompletion = "in-progress" | "finished";
-export type AppState = {
-    steps: Step[];
-    version: string;
-    logoVisibility: LogoVisibility;
-    currentStepIndex: number;
-    currentPhase: StepPhase;
-    completedStepRecords: CompletedStepRecord[];
-    currentOutputLines: CommandOutputLine[];
-    currentPrompt: CurrentPrompt | undefined;
-    runCompletion: RunCompletion;
-    versionReport: ResolvedVersion[] | undefined;
-};
-export declare function createInitialAppState(steps: Step[], version: string, logoVisibility: LogoVisibility): AppState;
+export { type StepStage, type DisplayStep, type StepPhase, type CompletedStepRecord, type CurrentPrompt, type ResolvedVersion, type LogoVisibility, type RunCompletion, type UpdateState, type AppState, createInitialUpdateState, createInitialAppState, } from "../update/state.js";

package/dist/ui/state.js

@@ -1,14 +1 @@
-export function createInitialAppState(steps, version, logoVisibility) {
-    return {
-        steps,
-        version,
-        logoVisibility,
-        currentStepIndex: 0,
-        currentPhase: "checking-availability",
-        completedStepRecords: [],
-        currentOutputLines: [],
-        currentPrompt: undefined,
-        runCompletion: "in-progress",
-        versionReport: undefined,
-    };
-}
+export { createInitialUpdateState, createInitialAppState, } from "../update/state.js";

package/dist/ui/terminal.d.ts

@@ -1,5 +1,6 @@
 type TerminalOptions = {
     output?: NodeJS.WritableStream;
+    screenBuffer?: "main" | "alternate";
 };
 type CursorCleanup = () => void;
 export declare function hideCursorDuringExecution(options?: TerminalOptions): CursorCleanup;

package/dist/ui/terminal.js

@@ -1,9 +1,20 @@
 export function hideCursorDuringExecution(options = {}) {
     const output = options.output ?? process.stdout;
+    const screenBuffer = options.screenBuffer ?? "main";
+    if (screenBuffer === "alternate") {
+        output.write("\x1b[?1049h");
+    }
     output.write("\x1b[?25l");
-    const restoreOnExit = () => output.write("\x1b[?25h");
+    const restoreTerminal = () => {
+        output.write("\x1b[?25h");
+        if (screenBuffer === "alternate") {
+            output.write("\x1b[?1049l");
+        }
+    };
+    const restoreOnExit = () => restoreTerminal();
     const restoreAndExitOnInterrupt = () => {
-        output.write("\x1b[?25h\n");
+        restoreTerminal();
+        output.write("\n");
         process.exit(130);
     };
     process.on("exit", restoreOnExit);
@@ -11,6 +22,6 @@ export function hideCursorDuringExecution(options = {}) {
     return () => {
         process.removeListener("exit", restoreOnExit);
         process.removeListener("SIGINT", restoreAndExitOnInterrupt);
-        output.write("\x1b[?25h");
+        restoreTerminal();
     };
 }

package/dist/ui/versionReport.d.ts

@@ -1,3 +1,2 @@
 import type { ResolvedVersion } from "./state.js";
-export declare function collectVersions(): Promise<ResolvedVersion[]>;
 export declare function buildVersionReportLines(versions: ResolvedVersion[]): string[];

package/dist/ui/versionReport.js

@@ -1,20 +1,4 @@
 import chalk from "chalk";
-import { captureShellCommandOutput } from "../runner.js";
-const VERSION_ENTRIES = [
-    { label: "macOS", shellCommand: "sw_vers -productVersion" },
-    { label: "Homebrew", shellCommand: "brew --version | head -n1" },
-    { label: "Node", shellCommand: "node -v 2>/dev/null" },
-    { label: "NPM", shellCommand: "npm -v 2>/dev/null" },
-    { label: "Python", shellCommand: "python3 --version 2>/dev/null" },
-    { label: "pip3", shellCommand: "pip3 --version 2>/dev/null | cut -d' ' -f1-2" },
-    { label: "Zsh", shellCommand: "zsh --version 2>/dev/null" },
-];
-export async function collectVersions() {
-    return Promise.all(VERSION_ENTRIES.map(async ({ label, shellCommand }) => {
-        const value = await captureShellCommandOutput({ shellCommand }).catch(() => "");
-        return { label, value: value || "not installed" };
-    }));
-}
 export function buildVersionReportLines(versions) {
     return [
         chalk.dim("  ─── Versions ─────────────────────────"),

package/dist/update/displayStep.d.ts

@@ -0,0 +1,4 @@
+import type { Step } from "../steps/index.js";
+import type { DisplayStep } from "./state.js";
+export declare function toDisplayStep(step: Step): DisplayStep;
+export declare function toDisplaySteps(steps: Step[]): DisplayStep[];

package/dist/update/displayStep.js

@@ -0,0 +1,11 @@
+export function toDisplayStep(step) {
+    return {
+        id: step.id,
+        name: step.name,
+        description: step.description,
+        stage: step.stage,
+    };
+}
+export function toDisplaySteps(steps) {
+    return steps.map(toDisplayStep);
+}

package/dist/update/engine.d.ts

@@ -0,0 +1,23 @@
+import { type StepLogWriter } from "../logger.js";
+import { runShellCommand } from "../runner.js";
+import { createDefaultStepRunContext, type Step } from "../steps/index.js";
+import { type LogoVisibility, type ResolvedVersion, type UpdateState } from "./state.js";
+export type PromptMode = "interactive" | "auto-accept";
+export type ConfirmationAnswer = "yes" | "no" | "force";
+type UpdateEngineDependencies = {
+    createLogWriter: (stepId: string) => Promise<StepLogWriter>;
+    runCommand: typeof runShellCommand;
+    createStepRunContext: typeof createDefaultStepRunContext;
+};
+type RunUpdateEngineOptions = {
+    steps: Step[];
+    promptMode: PromptMode;
+    version: string;
+    logoVisibility: LogoVisibility;
+    askForConfirmation: () => Promise<ConfirmationAnswer>;
+    collectVersions: () => Promise<ResolvedVersion[]>;
+    onStateChanged: (state: UpdateState) => void;
+    dependencies?: Partial<UpdateEngineDependencies>;
+};
+export declare function runUpdateEngine(options: RunUpdateEngineOptions): Promise<UpdateState>;
+export {};

package/dist/update/engine.js

@@ -0,0 +1,126 @@
+import { createLogWriterForStep } from "../logger.js";
+import { runShellCommand } from "../runner.js";
+import { createDefaultStepRunContext } from "../steps/index.js";
+import { toDisplaySteps } from "./displayStep.js";
+import { createInitialUpdateState, } from "./state.js";
+function resolveDependencies(dependencyOverrides) {
+    return {
+        createLogWriter: dependencyOverrides?.createLogWriter ?? createLogWriterForStep,
+        runCommand: dependencyOverrides?.runCommand ?? runShellCommand,
+        createStepRunContext: dependencyOverrides?.createStepRunContext ?? createDefaultStepRunContext,
+    };
+}
+async function resolvePrompt(promptMode, askForConfirmation) {
+    if (promptMode === "auto-accept") {
+        return { promptMode: "auto-accept", decision: "run" };
+    }
+    const answer = await askForConfirmation();
+    if (answer === "no") {
+        return { promptMode: "interactive", decision: "skip" };
+    }
+    if (answer === "force") {
+        return { promptMode: "auto-accept", decision: "run" };
+    }
+    return { promptMode: "interactive", decision: "run" };
+}
+function reportState(state, onStateChanged) {
+    onStateChanged(state);
+}
+export async function runUpdateEngine(options) {
+    const dependencies = resolveDependencies(options.dependencies);
+    const state = createInitialUpdateState(toDisplaySteps(options.steps), options.version, options.logoVisibility);
+    let promptMode = options.promptMode;
+    reportState(state, options.onStateChanged);
+    for (let stepIndex = 0; stepIndex < options.steps.length; stepIndex++) {
+        const step = options.steps[stepIndex];
+        state.currentStepIndex = stepIndex;
+        state.currentPhase = "checking-availability";
+        state.currentOutputLines = [];
+        state.currentPrompt = undefined;
+        reportState(state, options.onStateChanged);
+        const availabilityStatus = (await step.checkIsAvailable())
+            ? "available"
+            : "unavailable";
+        if (availabilityStatus === "unavailable" && !step.brewPackageToInstall) {
+            state.currentPhase = "not-available";
+            reportState(state, options.onStateChanged);
+            state.completedStepRecords.push({ phase: "not-available", summaryNote: "not installed" });
+            continue;
+        }
+        if (availabilityStatus === "unavailable" && step.brewPackageToInstall) {
+            state.currentPhase = "prompting-to-install";
+            state.currentPrompt = {
+                question: `Install ${step.name} via Homebrew? (brew install ${step.brewPackageToInstall})`,
+            };
+            reportState(state, options.onStateChanged);
+            const installPrompt = await resolvePrompt(promptMode, options.askForConfirmation);
+            promptMode = installPrompt.promptMode;
+            state.currentPrompt = undefined;
+            if (installPrompt.decision === "skip") {
+                state.currentPhase = "skipped";
+                reportState(state, options.onStateChanged);
+                state.completedStepRecords.push({ phase: "skipped" });
+                continue;
+            }
+            state.currentPhase = "installing";
+            reportState(state, options.onStateChanged);
+            try {
+                const installLogWriter = await dependencies.createLogWriter(`${step.id}-install`);
+                await dependencies.runCommand({
+                    shellCommand: `brew install ${step.brewPackageToInstall}`,
+                    onOutputLine: (line) => {
+                        state.currentOutputLines.push(line);
+                        reportState(state, options.onStateChanged);
+                    },
+                    logWriter: installLogWriter,
+                });
+            }
+            catch {
+                state.currentPhase = "failed";
+                reportState(state, options.onStateChanged);
+                state.completedStepRecords.push({ phase: "failed", summaryNote: "install failed" });
+                continue;
+            }
+        }
+        state.currentPhase = "prompting-to-run";
+        state.currentPrompt = { question: `Run ${step.name} update?`, warning: step.warning };
+        reportState(state, options.onStateChanged);
+        const runPrompt = await resolvePrompt(promptMode, options.askForConfirmation);
+        promptMode = runPrompt.promptMode;
+        state.currentPrompt = undefined;
+        if (runPrompt.decision === "skip") {
+            state.currentPhase = "skipped";
+            reportState(state, options.onStateChanged);
+            state.completedStepRecords.push({ phase: "skipped" });
+            continue;
+        }
+        state.currentPhase = "running";
+        state.currentOutputLines = [];
+        reportState(state, options.onStateChanged);
+        const stepLogWriter = await dependencies.createLogWriter(step.id);
+        try {
+            await step.run(dependencies.createStepRunContext((line) => {
+                state.currentOutputLines.push(line);
+                reportState(state, options.onStateChanged);
+            }, stepLogWriter));
+            state.currentPhase = "complete";
+            state.currentOutputLines = [];
+            reportState(state, options.onStateChanged);
+            state.completedStepRecords.push({ phase: "complete", summaryNote: "updated" });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            state.currentPhase = "failed";
+            state.currentOutputLines = [];
+            reportState(state, options.onStateChanged);
+            state.completedStepRecords.push({ phase: "failed", summaryNote: errorMessage });
+        }
+    }
+    state.runCompletion = "finished";
+    state.currentOutputLines = [];
+    state.currentPrompt = undefined;
+    reportState(state, options.onStateChanged);
+    state.versionReport = await options.collectVersions();
+    reportState(state, options.onStateChanged);
+    return state;
+}

package/dist/update/state.d.ts

@@ -0,0 +1,38 @@
+import type { CommandOutputLine } from "../runner.js";
+export type StepStage = "runtime" | "tools";
+export type DisplayStep = {
+    id: string;
+    name: string;
+    description: string;
+    stage: StepStage;
+};
+export type StepPhase = "pending" | "checking-availability" | "prompting-to-install" | "installing" | "prompting-to-run" | "running" | "complete" | "failed" | "skipped" | "not-available";
+export type CompletedStepRecord = {
+    phase: StepPhase;
+    summaryNote?: string;
+};
+export type CurrentPrompt = {
+    question: string;
+    warning?: string;
+};
+export type ResolvedVersion = {
+    label: string;
+    value: string;
+};
+export type LogoVisibility = "visible" | "hidden";
+export type RunCompletion = "in-progress" | "finished";
+export type UpdateState = {
+    steps: DisplayStep[];
+    version: string;
+    logoVisibility: LogoVisibility;
+    currentStepIndex: number;
+    currentPhase: StepPhase;
+    completedStepRecords: CompletedStepRecord[];
+    currentOutputLines: CommandOutputLine[];
+    currentPrompt: CurrentPrompt | undefined;
+    runCompletion: RunCompletion;
+    versionReport: ResolvedVersion[] | undefined;
+};
+export type AppState = UpdateState;
+export declare function createInitialUpdateState(steps: DisplayStep[], version: string, logoVisibility: LogoVisibility): UpdateState;
+export declare const createInitialAppState: typeof createInitialUpdateState;