braeburn 1.3.0 → 1.4.0

package/dist/commands/setup.d.ts

@@ -1,9 +1,17 @@
 import type { Step } from "../steps/index.js";
+import type { StepStage } from "../update/state.js";
 export type SelectionState = "selected" | "deselected";
 export type ProtectionStatus = "protected" | "configurable";
 export type AvailabilityStatus = "available" | "unavailable";
+export type SetupStepView = {
+    id: string;
+    name: string;
+    description: string;
+    stage: StepStage;
+    brewPackageToInstall?: string;
+};
 export type SelectableStep = {
-    step: Step;
+    step: SetupStepView;
     selection: SelectionState;
     protection: ProtectionStatus;
     availability: AvailabilityStatus;

package/dist/commands/setup.js

@@ -73,64 +73,75 @@ export function buildSetupScreen(items, cursorIndex) {
 }
 export async function runSetupCommand(allSteps) {
     const render = createScreenRenderer();
-    hideCursorDuringExecution();
-    render(buildLoadingScreen());
-    const availabilityResults = await Promise.all(allSteps.map((step) => step.checkIsAvailable()));
-    const items = allSteps.map((step, stepIndex) => ({
-        step,
-        selection: PROTECTED_STEP_IDS.has(step.id) || step.stage === "tools" ? "selected" : "deselected",
-        protection: PROTECTED_STEP_IDS.has(step.id) ? "protected" : "configurable",
-        availability: availabilityResults[stepIndex] ? "available" : "unavailable",
-    }));
-    let cursorIndex = 0;
-    render(buildSetupScreen(items, cursorIndex));
-    await new Promise((resolve) => {
-        readline.emitKeypressEvents(process.stdin);
-        if (process.stdin.isTTY)
-            process.stdin.setRawMode(true);
-        const handleKeypress = (_char, key) => {
-            if (key?.ctrl && key?.name === "c") {
-                process.exit(130);
-            }
-            if (key?.name === "up" || key?.name === "k") {
-                cursorIndex = Math.max(0, cursorIndex - 1);
-                render(buildSetupScreen(items, cursorIndex));
-            }
-            else if (key?.name === "down" || key?.name === "j") {
-                cursorIndex = Math.min(items.length - 1, cursorIndex + 1);
-                render(buildSetupScreen(items, cursorIndex));
-            }
-            else if (key?.name === "space") {
-                const item = items[cursorIndex];
-                if (item.protection === "configurable") {
-                    item.selection = item.selection === "selected" ? "deselected" : "selected";
+    const restoreCursor = hideCursorDuringExecution({ screenBuffer: "alternate" });
+    try {
+        render(buildLoadingScreen());
+        const availabilityResults = await Promise.all(allSteps.map((step) => step.checkIsAvailable()));
+        const items = allSteps.map((step, stepIndex) => ({
+            step: {
+                id: step.id,
+                name: step.name,
+                description: step.description,
+                stage: step.stage,
+                brewPackageToInstall: step.brewPackageToInstall,
+            },
+            selection: PROTECTED_STEP_IDS.has(step.id) || step.stage === "tools" ? "selected" : "deselected",
+            protection: PROTECTED_STEP_IDS.has(step.id) ? "protected" : "configurable",
+            availability: availabilityResults[stepIndex] ? "available" : "unavailable",
+        }));
+        let cursorIndex = 0;
+        render(buildSetupScreen(items, cursorIndex));
+        await new Promise((resolve) => {
+            readline.emitKeypressEvents(process.stdin);
+            if (process.stdin.isTTY)
+                process.stdin.setRawMode(true);
+            const handleKeypress = (_char, key) => {
+                if (key?.ctrl && key?.name === "c") {
+                    process.exit(130);
+                }
+                if (key?.name === "up" || key?.name === "k") {
+                    cursorIndex = Math.max(0, cursorIndex - 1);
                     render(buildSetupScreen(items, cursorIndex));
                 }
+                else if (key?.name === "down" || key?.name === "j") {
+                    cursorIndex = Math.min(items.length - 1, cursorIndex + 1);
+                    render(buildSetupScreen(items, cursorIndex));
+                }
+                else if (key?.name === "space") {
+                    const item = items[cursorIndex];
+                    if (item.protection === "configurable") {
+                        item.selection = item.selection === "selected" ? "deselected" : "selected";
+                        render(buildSetupScreen(items, cursorIndex));
+                    }
+                }
+                else if (key?.name === "return") {
+                    process.stdin.removeListener("keypress", handleKeypress);
+                    if (process.stdin.isTTY)
+                        process.stdin.setRawMode(false);
+                    process.stdin.pause();
+                    resolve();
+                }
+            };
+            process.stdin.on("keypress", handleKeypress);
+            process.stdin.resume();
+        });
+        const stepsConfig = {};
+        for (const item of items) {
+            if (item.protection === "configurable" && item.selection === "deselected") {
+                stepsConfig[item.step.id] = false;
             }
-            else if (key?.name === "return") {
-                process.stdin.removeListener("keypress", handleKeypress);
-                if (process.stdin.isTTY)
-                    process.stdin.setRawMode(false);
-                process.stdin.pause();
-                resolve();
-            }
-        };
-        process.stdin.on("keypress", handleKeypress);
-        process.stdin.resume();
-    });
-    const stepsConfig = {};
-    for (const item of items) {
-        if (item.protection === "configurable" && item.selection === "deselected") {
-            stepsConfig[item.step.id] = false;
         }
+        await writeConfig({ steps: stepsConfig });
+        const confirmationLines = [
+            chalk.yellow(LOGO_ART),
+            "",
+            `  ${chalk.green("\u2713")}  Setup complete! Starting your first update\u2026`,
+            "",
+        ];
+        render(confirmationLines.join("\n") + "\n");
+        await new Promise((resolve) => setTimeout(resolve, 800));
+    }
+    finally {
+        restoreCursor();
     }
-    await writeConfig({ steps: stepsConfig });
-    const confirmationLines = [
-        chalk.yellow(LOGO_ART),
-        "",
-        `  ${chalk.green("\u2713")}  Setup complete! Starting your first update\u2026`,
-        "",
-    ];
-    render(confirmationLines.join("\n") + "\n");
-    await new Promise((resolve) => setTimeout(resolve, 800));
 }

package/dist/commands/update.d.ts

@@ -1,6 +1,6 @@
+import { type PromptMode } from "../update/engine.js";
+import type { LogoVisibility } from "../update/state.js";
 import type { Step } from "../steps/index.js";
-type PromptMode = "interactive" | "auto-accept";
-type LogoVisibility = "visible" | "hidden";
 type RunUpdateCommandOptions = {
     steps: Step[];
     promptMode: PromptMode;

package/dist/commands/update.js

@@ -1,109 +1,30 @@
-import { runShellCommand } from "../runner.js";
-import { createLogWriterForStep } from "../logger.js";
-import { collectVersions } from "../ui/versionReport.js";
+import { collectVersions } from "../update/versionCollector.js";
 import { captureYesNo } from "../ui/prompt.js";
-import { createInitialAppState } from "../ui/state.js";
 import { buildScreen, createScreenRenderer } from "../ui/screen.js";
 import { hideCursorDuringExecution } from "../ui/terminal.js";
-import { createDefaultStepRunContext } from "../steps/index.js";
+import { runUpdateEngine } from "../update/engine.js";
 export async function runUpdateCommand(options) {
-    const { steps, version } = options;
-    let autoAccept = options.promptMode === "auto-accept";
-    const state = createInitialAppState(steps, version, options.logoVisibility);
     const renderScreen = createScreenRenderer();
-    hideCursorDuringExecution();
-    renderScreen(buildScreen(state));
-    for (let stepIndex = 0; stepIndex < steps.length; stepIndex++) {
-        const step = steps[stepIndex];
-        state.currentStepIndex = stepIndex;
-        state.currentPhase = "checking-availability";
-        state.currentOutputLines = [];
-        state.currentPrompt = undefined;
-        renderScreen(buildScreen(state));
-        const isAvailable = await step.checkIsAvailable();
-        if (!isAvailable && !step.brewPackageToInstall) {
-            state.currentPhase = "not-available";
-            renderScreen(buildScreen(state));
-            state.completedStepRecords.push({ phase: "not-available", summaryNote: "not installed" });
-            continue;
-        }
-        if (!isAvailable && step.brewPackageToInstall) {
-            state.currentPhase = "prompting-to-install";
-            state.currentPrompt = {
-                question: `Install ${step.name} via Homebrew? (brew install ${step.brewPackageToInstall})`,
-            };
-            renderScreen(buildScreen(state));
-            const installAnswer = autoAccept ? "yes" : await captureYesNo();
-            if (installAnswer === "force")
-                autoAccept = true;
-            const shouldInstall = installAnswer !== "no";
-            state.currentPrompt = undefined;
-            if (!shouldInstall) {
-                state.currentPhase = "skipped";
+    const restoreCursor = hideCursorDuringExecution({ screenBuffer: "alternate" });
+    let finalScreen = "";
+    try {
+        const finalState = await runUpdateEngine({
+            steps: options.steps,
+            promptMode: options.promptMode,
+            version: options.version,
+            logoVisibility: options.logoVisibility,
+            askForConfirmation: captureYesNo,
+            collectVersions,
+            onStateChanged: (state) => {
                 renderScreen(buildScreen(state));
-                state.completedStepRecords.push({ phase: "skipped" });
-                continue;
-            }
-            state.currentPhase = "installing";
-            renderScreen(buildScreen(state));
-            try {
-                const installLogWriter = await createLogWriterForStep(`${step.id}-install`);
-                await runShellCommand({
-                    shellCommand: `brew install ${step.brewPackageToInstall}`,
-                    onOutputLine: (line) => {
-                        state.currentOutputLines.push(line);
-                        renderScreen(buildScreen(state));
-                    },
-                    logWriter: installLogWriter,
-                });
-            }
-            catch {
-                state.currentPhase = "failed";
-                renderScreen(buildScreen(state));
-                state.completedStepRecords.push({ phase: "failed", summaryNote: "install failed" });
-                continue;
-            }
-        }
-        state.currentPhase = "prompting-to-run";
-        state.currentPrompt = { question: `Run ${step.name} update?`, warning: step.warning };
-        renderScreen(buildScreen(state));
-        const runAnswer = autoAccept ? "yes" : await captureYesNo();
-        if (runAnswer === "force")
-            autoAccept = true;
-        const shouldRun = runAnswer !== "no";
-        state.currentPrompt = undefined;
-        if (!shouldRun) {
-            state.currentPhase = "skipped";
-            renderScreen(buildScreen(state));
-            state.completedStepRecords.push({ phase: "skipped" });
-            continue;
-        }
-        state.currentPhase = "running";
-        state.currentOutputLines = [];
-        renderScreen(buildScreen(state));
-        const stepLogWriter = await createLogWriterForStep(step.id);
-        try {
-            await step.run(createDefaultStepRunContext((line) => {
-                state.currentOutputLines.push(line);
-                renderScreen(buildScreen(state));
-            }, stepLogWriter));
-            state.currentPhase = "complete";
-            state.currentOutputLines = [];
-            renderScreen(buildScreen(state));
-            state.completedStepRecords.push({ phase: "complete", summaryNote: "updated" });
-        }
-        catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            state.currentPhase = "failed";
-            state.currentOutputLines = [];
-            renderScreen(buildScreen(state));
-            state.completedStepRecords.push({ phase: "failed", summaryNote: errorMessage });
-        }
+            },
+        });
+        finalScreen = buildScreen(finalState);
+    }
+    finally {
+        restoreCursor();
+    }
+    if (finalScreen) {
+        process.stdout.write(finalScreen);
     }
-    state.runCompletion = "finished";
-    state.currentOutputLines = [];
-    state.currentPrompt = undefined;
-    renderScreen(buildScreen(state));
-    state.versionReport = await collectVersions();
-    renderScreen(buildScreen(state));
 }

package/dist/index.js

@@ -3,24 +3,12 @@ import { Command } from "commander";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
-import { homebrewStep, masStep, ohmyzshStep, npmStep, pipStep, pyenvStep, nvmStep, dotnetStep, macosStep, cleanupStep, } from "./steps/index.js";
+import { ALL_STEPS } from "./steps/catalog.js";
 import { runUpdateCommand } from "./commands/update.js";
 import { runLogCommand, runLogListCommand } from "./commands/log.js";
 import { runConfigCommand, runConfigUpdateCommand } from "./commands/config.js";
 import { runSetupCommand } from "./commands/setup.js";
 import { readConfig, isStepEnabled, isLogoEnabled, PROTECTED_STEP_IDS, configFileExists } from "./config.js";
-const ALL_STEPS = [
-    pyenvStep,
-    nvmStep,
-    homebrewStep,
-    masStep,
-    ohmyzshStep,
-    npmStep,
-    pipStep,
-    dotnetStep,
-    macosStep,
-    cleanupStep,
-];
 const STEP_IDS_BY_NAME = new Map(ALL_STEPS.map((step) => [step.id, step]));
 const requireFromThis = createRequire(import.meta.url);
 const packageJson = requireFromThis(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"));

package/dist/runner.js

@@ -5,14 +5,14 @@ export async function runShellCommand(options) {
         reject: true,
     });
     subprocess.stdout?.on("data", (chunk) => {
-        const lines = String(chunk).split("\n").filter(Boolean);
+        const lines = String(chunk).split(/\r?\n|\r/).filter(Boolean);
         for (const line of lines) {
             options.onOutputLine({ text: line, source: "stdout" });
             options.logWriter(line);
         }
     });
     subprocess.stderr?.on("data", (chunk) => {
-        const lines = String(chunk).split("\n").filter(Boolean);
+        const lines = String(chunk).split(/\r?\n|\r/).filter(Boolean);
         for (const line of lines) {
             options.onOutputLine({ text: line, source: "stderr" });
             options.logWriter(line);

package/dist/steps/catalog.d.ts

@@ -0,0 +1,2 @@
+import { type Step } from "./index.js";
+export declare const ALL_STEPS: Step[];

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,14 @@ import { buildOutputBoxLines } from "./outputBox.js";
 import { buildPromptLines } from "./prompt.js";
 import { buildVersionReportLines } from "./versionReport.js";
 export function createScreenRenderer(output = process.stdout) {
-    let previousLineCount = 0;
+    let hasAnchor = false;
     return (content) => {
-        if (previousLineCount > 0) {
-            output.write(`\x1b[${previousLineCount}A\x1b[J`);
+        if (!hasAnchor) {
+            output.write("\x1b7");
+            hasAnchor = true;
         }
+        output.write("\x1b8\x1b[J");
         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;

package/dist/update/state.js

@@ -0,0 +1,15 @@
+export function createInitialUpdateState(steps, version, logoVisibility) {
+    return {
+        steps,
+        version,
+        logoVisibility,
+        currentStepIndex: 0,
+        currentPhase: "checking-availability",
+        completedStepRecords: [],
+        currentOutputLines: [],
+        currentPrompt: undefined,
+        runCompletion: "in-progress",
+        versionReport: undefined,
+    };
+}
+export const createInitialAppState = createInitialUpdateState;

package/dist/update/versionCollector.d.ts

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

package/dist/update/versionCollector.js

@@ -0,0 +1,16 @@
+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" };
+    }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "braeburn",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "macOS system updater CLI",
   "type": "module",
   "bin": {