braeburn 1.2.1 → 1.2.3

package/dist/commands/config.d.ts

@@ -1,12 +1,23 @@
+import { type BraeburnConfig } from "../config.js";
 import type { Step } from "../steps/index.js";
 type RunConfigCommandOptions = {
     allSteps: Step[];
 };
+type DesiredState = "enable" | "disable";
 type RunConfigUpdateCommandOptions = {
-    stepUpdates: Record<string, boolean>;
-    logoUpdate: boolean | undefined;
+    settingUpdates: Record<string, DesiredState>;
     allSteps: Step[];
 };
 export declare function runConfigCommand(options: RunConfigCommandOptions): Promise<void>;
+type ConfigChange = {
+    label: string;
+    from: DesiredState;
+    to: DesiredState;
+};
+type ConfigUpdateResult = {
+    updatedConfig: BraeburnConfig;
+    changes: ConfigChange[];
+};
+export declare function applyConfigUpdates(config: BraeburnConfig, settingUpdates: Record<string, DesiredState>): ConfigUpdateResult;
 export declare function runConfigUpdateCommand(options: RunConfigUpdateCommandOptions): Promise<void>;
 export {};

package/dist/commands/config.js

@@ -1,5 +1,5 @@
 import chalk from "chalk";
-import { readConfig, writeConfig, resolveConfigPath, isStepEnabled, isLogoEnabled, PROTECTED_STEP_IDS, } from "../config.js";
+import { readConfig, writeConfig, resolveConfigPath, isSettingEnabled, isStepEnabled, isLogoEnabled, applySettingToConfig, PROTECTED_STEP_IDS, } from "../config.js";
 export async function runConfigCommand(options) {
     const { allSteps } = options;
     const config = await readConfig();
@@ -29,10 +29,22 @@ export async function runConfigCommand(options) {
     }
     process.stdout.write(`\n`);
 }
+export function applyConfigUpdates(config, settingUpdates) {
+    let updatedConfig = config;
+    const changes = [];
+    for (const [settingId, desiredState] of Object.entries(settingUpdates)) {
+        const currentState = isSettingEnabled(config, settingId) ? "enable" : "disable";
+        if (currentState !== desiredState) {
+            changes.push({ label: settingId, from: currentState, to: desiredState });
+        }
+        updatedConfig = applySettingToConfig(updatedConfig, settingId, desiredState);
+    }
+    return { updatedConfig, changes };
+}
 export async function runConfigUpdateCommand(options) {
-    const { stepUpdates, logoUpdate, allSteps } = options;
-    if (Object.keys(stepUpdates).length === 0 && logoUpdate === undefined) {
-        const configurableSteps = allSteps.filter((s) => !PROTECTED_STEP_IDS.has(s.id));
+    const { settingUpdates, allSteps } = options;
+    if (Object.keys(settingUpdates).length === 0) {
+        const configurableSteps = allSteps.filter((step) => !PROTECTED_STEP_IDS.has(step.id));
         process.stdout.write("No changes — pass flags to enable or disable steps:\n\n");
         process.stdout.write(`  ${"--no-logo".padEnd(18)} hide the logo\n`);
         process.stdout.write(`  ${"--logo".padEnd(18)} show the logo\n`);
@@ -48,41 +60,15 @@ export async function runConfigUpdateCommand(options) {
         return;
     }
     const config = await readConfig();
-    const changes = [];
-    if (logoUpdate !== undefined) {
-        const currentlyEnabled = isLogoEnabled(config);
-        if (currentlyEnabled !== logoUpdate) {
-            changes.push({ label: "logo", from: currentlyEnabled, to: logoUpdate });
-        }
-        if (logoUpdate) {
-            delete config.logo;
-        }
-        else {
-            config.logo = false;
-        }
-    }
-    for (const [stepId, newEnabled] of Object.entries(stepUpdates)) {
-        const currentlyEnabled = isStepEnabled(config, stepId);
-        if (currentlyEnabled !== newEnabled) {
-            changes.push({ label: stepId, from: currentlyEnabled, to: newEnabled });
-        }
-        if (newEnabled) {
-            // Re-enabling: remove from config so absent = enabled (keeps file minimal)
-            delete config.steps[stepId];
-        }
-        else {
-            config.steps[stepId] = false;
-        }
-    }
-    // Write even if no visible changes, in case the user is re-confirming state
-    await writeCleanConfig(config);
+    const { updatedConfig, changes } = applyConfigUpdates(config, settingUpdates);
+    await writeCleanConfig(updatedConfig);
     if (changes.length === 0) {
         process.stdout.write("No changes — already set as requested.\n");
         return;
     }
     for (const { label, from, to } of changes) {
-        const fromLabel = from ? chalk.green("enabled") : chalk.red("disabled");
-        const toLabel = to ? chalk.green("enabled") : chalk.red("disabled");
+        const fromLabel = from === "enable" ? chalk.green("enabled") : chalk.red("disabled");
+        const toLabel = to === "enable" ? chalk.green("enabled") : chalk.red("disabled");
         process.stdout.write(`  ${label.padEnd(12)} ${fromLabel} → ${toLabel}\n`);
     }
     const configPath = await resolveConfigPath();

package/dist/commands/setup.d.ts

@@ -1,2 +1,13 @@
 import type { Step } from "../steps/index.js";
+export type SelectionState = "selected" | "deselected";
+export type ProtectionStatus = "protected" | "configurable";
+export type AvailabilityStatus = "available" | "unavailable";
+export type SelectableStep = {
+    step: Step;
+    selection: SelectionState;
+    protection: ProtectionStatus;
+    availability: AvailabilityStatus;
+};
+export declare function buildLoadingScreen(): string;
+export declare function buildSetupScreen(items: SelectableStep[], cursorIndex: number): string;
 export declare function runSetupCommand(allSteps: Step[]): Promise<void>;

package/dist/commands/setup.js

@@ -2,16 +2,9 @@ import readline from "node:readline";
 import chalk from "chalk";
 import { writeConfig, PROTECTED_STEP_IDS } from "../config.js";
 import { LOGO_ART } from "../logo.js";
-// Module-level render state (scoped to this screen, separate from update screen)
-let prevLines = 0;
-function render(content) {
-    if (prevLines > 0) {
-        process.stdout.write(`\x1b[${prevLines}A\x1b[J`);
-    }
-    process.stdout.write(content);
-    prevLines = (content.match(/\n/g) ?? []).length;
-}
-function buildLoadingScreen() {
+import { createScreenRenderer } from "../ui/screen.js";
+import { hideCursorDuringExecution } from "../ui/terminal.js";
+export function buildLoadingScreen() {
     const lines = [
         chalk.yellow(LOGO_ART),
         "",
@@ -22,7 +15,7 @@ function buildLoadingScreen() {
     ];
     return lines.join("\n") + "\n";
 }
-function buildSetupScreen(items, cursorIndex) {
+export function buildSetupScreen(items, cursorIndex) {
     const lines = [
         chalk.yellow(LOGO_ART),
         "",
@@ -34,18 +27,18 @@ function buildSetupScreen(items, cursorIndex) {
         `  ${chalk.dim("\u2191\u2193  navigate    Space  toggle    Return  confirm")}`,
         "",
     ];
-    for (let i = 0; i < items.length; i++) {
-        const item = items[i];
-        const isCursor = i === cursorIndex;
+    for (let itemIndex = 0; itemIndex < items.length; itemIndex++) {
+        const item = items[itemIndex];
+        const isCursor = itemIndex === cursorIndex;
         const cursor = isCursor ? chalk.cyan("\u203a") : " ";
-        const checkbox = item.selected ? chalk.green("\u25cf") : chalk.dim("\u25cb");
+        const checkbox = item.selection === "selected" ? chalk.green("\u25cf") : chalk.dim("\u25cb");
         const namePadded = item.step.name.padEnd(18);
         const name = isCursor ? chalk.bold.white(namePadded) : chalk.white(namePadded);
         let status;
-        if (item.isProtected) {
+        if (item.protection === "protected") {
             status = chalk.dim("required");
         }
-        else if (item.isAvailable) {
+        else if (item.availability === "available") {
             status = chalk.green("installed");
         }
         else if (item.step.brewPackageToInstall) {
@@ -59,39 +52,31 @@ function buildSetupScreen(items, cursorIndex) {
             lines.push(`           ${chalk.dim(item.step.description)}`);
         }
     }
-    const enabledCount = items.filter((i) => i.selected).length;
+    const enabledCount = items.filter((item) => item.selection === "selected").length;
     lines.push("");
     lines.push(`  ${chalk.dim(`${enabledCount} of ${items.length} tools selected`)}`);
     lines.push("");
     return lines.join("\n") + "\n";
 }
 export async function runSetupCommand(allSteps) {
-    // Hide cursor; restore on exit
-    process.stdout.write("\x1b[?25l");
-    process.on("exit", () => process.stdout.write("\x1b[?25h"));
-    process.on("SIGINT", () => {
-        process.stdout.write("\x1b[?25h\n");
-        process.exit(130);
-    });
-    // Show loading screen while we check availability in parallel
+    const render = createScreenRenderer();
+    hideCursorDuringExecution();
     render(buildLoadingScreen());
     const availabilityResults = await Promise.all(allSteps.map((step) => step.checkIsAvailable()));
-    const items = allSteps.map((step, i) => ({
+    const items = allSteps.map((step, stepIndex) => ({
         step,
-        selected: true, // all enabled by default — user opts out
-        isProtected: PROTECTED_STEP_IDS.has(step.id),
-        isAvailable: availabilityResults[i],
+        selection: "selected",
+        protection: PROTECTED_STEP_IDS.has(step.id) ? "protected" : "configurable",
+        availability: availabilityResults[stepIndex] ? "available" : "unavailable",
     }));
     let cursorIndex = 0;
     render(buildSetupScreen(items, cursorIndex));
-    // Interactive selection loop
     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.stdout.write("\x1b[?25h\n");
                 process.exit(130);
             }
             if (key?.name === "up" || key?.name === "k") {
@@ -104,8 +89,8 @@ export async function runSetupCommand(allSteps) {
             }
             else if (key?.name === "space") {
                 const item = items[cursorIndex];
-                if (!item.isProtected) {
-                    item.selected = !item.selected;
+                if (item.protection === "configurable") {
+                    item.selection = item.selection === "selected" ? "deselected" : "selected";
                     render(buildSetupScreen(items, cursorIndex));
                 }
             }
@@ -120,25 +105,19 @@ export async function runSetupCommand(allSteps) {
         process.stdin.on("keypress", handleKeypress);
         process.stdin.resume();
     });
-    // Restore cursor
-    process.stdout.write("\x1b[?25h");
-    // Persist choices — only write explicit false entries (keeps file minimal, matches
-    // the opt-out convention used everywhere else in the codebase)
     const stepsConfig = {};
     for (const item of items) {
-        if (!item.isProtected && !item.selected) {
+        if (item.protection === "configurable" && item.selection === "deselected") {
             stepsConfig[item.step.id] = false;
         }
     }
     await writeConfig({ steps: stepsConfig });
-    // Clear the setup screen and print a brief confirmation before the update starts
-    if (prevLines > 0) {
-        process.stdout.write(`\x1b[${prevLines}A\x1b[J`);
-    }
-    process.stdout.write(chalk.yellow(LOGO_ART) + "\n");
-    process.stdout.write("\n");
-    process.stdout.write(`  ${chalk.green("\u2713")}  Setup complete! Starting your first update\u2026\n`);
-    process.stdout.write("\n");
-    // Small pause so the confirmation is readable before the update screen takes over
-    await new Promise((res) => setTimeout(res, 800));
+    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,8 +1,10 @@
 import type { Step } from "../steps/index.js";
+type PromptMode = "interactive" | "auto-accept";
+type LogoVisibility = "visible" | "hidden";
 type RunUpdateCommandOptions = {
     steps: Step[];
-    autoYes: boolean;
-    showLogo: boolean;
+    promptMode: PromptMode;
+    logoVisibility: LogoVisibility;
     version: string;
 };
 export declare function runUpdateCommand(options: RunUpdateCommandOptions): Promise<void>;

package/dist/commands/update.js

@@ -3,21 +3,19 @@ import { createLogWriterForStep } from "../logger.js";
 import { collectVersions } from "../ui/versionReport.js";
 import { captureYesNo } from "../ui/prompt.js";
 import { createInitialAppState } from "../ui/state.js";
-import { buildScreen, renderScreen } from "../ui/screen.js";
+import { buildScreen, createScreenRenderer } from "../ui/screen.js";
+import { hideCursorDuringExecution } from "../ui/terminal.js";
+import { createDefaultStepRunContext } from "../steps/index.js";
 export async function runUpdateCommand(options) {
     const { steps, version } = options;
-    let autoYes = options.autoYes;
-    const state = createInitialAppState(steps, version, options.showLogo);
-    process.stdout.write("\x1b[?25l");
-    process.on("exit", () => process.stdout.write("\x1b[?25h"));
-    process.on("SIGINT", () => {
-        process.stdout.write("\x1b[?25h\n");
-        process.exit(130);
-    });
+    let autoAccept = options.promptMode === "auto-accept";
+    const state = createInitialAppState(steps, version, options.logoVisibility);
+    const renderScreen = createScreenRenderer();
+    hideCursorDuringExecution();
     renderScreen(buildScreen(state));
-    for (let i = 0; i < steps.length; i++) {
-        const step = steps[i];
-        state.currentStepIndex = i;
+    for (let stepIndex = 0; stepIndex < steps.length; stepIndex++) {
+        const step = steps[stepIndex];
+        state.currentStepIndex = stepIndex;
         state.currentPhase = "checking-availability";
         state.currentOutputLines = [];
         state.currentPrompt = undefined;
@@ -35,9 +33,9 @@ export async function runUpdateCommand(options) {
                 question: `Install ${step.name} via Homebrew? (brew install ${step.brewPackageToInstall})`,
             };
             renderScreen(buildScreen(state));
-            const installAnswer = autoYes ? "yes" : await captureYesNo();
+            const installAnswer = autoAccept ? "yes" : await captureYesNo();
             if (installAnswer === "force")
-                autoYes = true;
+                autoAccept = true;
             const shouldInstall = installAnswer !== "no";
             state.currentPrompt = undefined;
             if (!shouldInstall) {
@@ -66,15 +64,12 @@ export async function runUpdateCommand(options) {
                 continue;
             }
         }
-        const pipWarning = step.id === "pip"
-            ? "This updates all global pip3 packages, which can occasionally break tools."
-            : undefined;
         state.currentPhase = "prompting-to-run";
-        state.currentPrompt = { question: `Run ${step.name} update?`, warning: pipWarning };
+        state.currentPrompt = { question: `Run ${step.name} update?`, warning: step.warning };
         renderScreen(buildScreen(state));
-        const runAnswer = autoYes ? "yes" : await captureYesNo();
+        const runAnswer = autoAccept ? "yes" : await captureYesNo();
         if (runAnswer === "force")
-            autoYes = true;
+            autoAccept = true;
         const shouldRun = runAnswer !== "no";
         state.currentPrompt = undefined;
         if (!shouldRun) {
@@ -88,13 +83,10 @@ export async function runUpdateCommand(options) {
         renderScreen(buildScreen(state));
         const stepLogWriter = await createLogWriterForStep(step.id);
         try {
-            await step.run({
-                onOutputLine: (line) => {
-                    state.currentOutputLines.push(line);
-                    renderScreen(buildScreen(state));
-                },
-                logWriter: stepLogWriter,
-            });
+            await step.run(createDefaultStepRunContext((line) => {
+                state.currentOutputLines.push(line);
+                renderScreen(buildScreen(state));
+            }, stepLogWriter));
             state.currentPhase = "complete";
             state.currentOutputLines = [];
             renderScreen(buildScreen(state));
@@ -108,7 +100,7 @@ export async function runUpdateCommand(options) {
             state.completedStepRecords.push({ phase: "failed", summaryNote: errorMessage });
         }
     }
-    state.isFinished = true;
+    state.runCompletion = "finished";
     state.currentOutputLines = [];
     state.currentPrompt = undefined;
     renderScreen(buildScreen(state));

package/dist/config.d.ts

@@ -1,4 +1,3 @@
-/** Steps that cannot be disabled — brew is a hard runtime dependency. */
 export declare const PROTECTED_STEP_IDS: Set<string>;
 export type BraeburnConfig = {
     steps: Record<string, boolean>;
@@ -8,5 +7,7 @@ export declare function resolveConfigPath(): Promise<string>;
 export declare function configFileExists(): Promise<boolean>;
 export declare function readConfig(): Promise<BraeburnConfig>;
 export declare function writeConfig(config: BraeburnConfig): Promise<void>;
+export declare function isSettingEnabled(config: BraeburnConfig, settingId: string): boolean;
 export declare function isStepEnabled(config: BraeburnConfig, stepId: string): boolean;
 export declare function isLogoEnabled(config: BraeburnConfig): boolean;
+export declare function applySettingToConfig(config: BraeburnConfig, settingId: string, desiredState: "enable" | "disable"): BraeburnConfig;

package/dist/config.js

@@ -2,12 +2,12 @@ import { readFile, writeFile, mkdir, access } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { parse, stringify } from "smol-toml";
-/** Steps that cannot be disabled — brew is a hard runtime dependency. */
 export const PROTECTED_STEP_IDS = new Set(["homebrew"]);
 const EMPTY_CONFIG = { steps: {} };
-async function pathExists(p) {
+const LOGO_SETTING_ID = "logo";
+async function pathExists(targetPath) {
     try {
-        await access(p);
+        await access(targetPath);
         return true;
     }
     catch {
@@ -41,13 +41,35 @@ export async function writeConfig(config) {
     await mkdir(join(configPath, ".."), { recursive: true });
     await writeFile(configPath, stringify(config), "utf-8");
 }
-export function isStepEnabled(config, stepId) {
-    if (PROTECTED_STEP_IDS.has(stepId))
+export function isSettingEnabled(config, settingId) {
+    if (PROTECTED_STEP_IDS.has(settingId))
         return true;
-    // Absent from config means enabled (opt-out model)
-    return config.steps[stepId] !== false;
+    if (settingId === LOGO_SETTING_ID)
+        return config.logo !== false;
+    return config.steps[settingId] !== false;
+}
+export function isStepEnabled(config, stepId) {
+    return isSettingEnabled(config, stepId);
 }
 export function isLogoEnabled(config) {
-    // Absent from config means enabled (opt-out model)
-    return config.logo !== false;
+    return isSettingEnabled(config, LOGO_SETTING_ID);
+}
+export function applySettingToConfig(config, settingId, desiredState) {
+    const updatedConfig = structuredClone(config);
+    if (settingId === LOGO_SETTING_ID) {
+        if (desiredState === "enable") {
+            delete updatedConfig.logo;
+        }
+        else {
+            updatedConfig.logo = false;
+        }
+        return updatedConfig;
+    }
+    if (desiredState === "enable") {
+        delete updatedConfig.steps[settingId];
+    }
+    else {
+        updatedConfig.steps[settingId] = false;
+    }
+    return updatedConfig;
 }

package/dist/index.js

@@ -34,7 +34,7 @@ program
 program
     .command("update", { isDefault: true })
     .description("Run system update steps (default command)")
-    .argument("[steps...]", `Steps to run — omit to run all.\nAvailable: ${ALL_STEPS.map((s) => s.id).join(", ")}`)
+    .argument("[steps...]", `Steps to run — omit to run all.\nAvailable: ${ALL_STEPS.map((step) => step.id).join(", ")}`)
     .option("-y, --yes", "Auto-accept all prompts (default yes to everything)")
     .option("-f, --force", "Alias for --yes")
     .option("--no-logo", "Hide the logo")
@@ -60,7 +60,6 @@ Examples:
   `)
     .action(async (stepArguments, options) => {
     const autoYes = options.yes === true || options.force === true;
-    // First-run: if no config file exists yet, show the setup wizard.
     if (!(await configFileExists())) {
         await runSetupCommand(ALL_STEPS);
     }
@@ -68,17 +67,14 @@ Examples:
     let stepsToRun = stepArguments.length === 0
         ? ALL_STEPS
         : resolveStepsByIds(stepArguments);
-    // When no explicit steps are requested, filter out steps disabled in config.
-    // Explicit step arguments always bypass config (user knows what they want).
     if (stepArguments.length === 0) {
         stepsToRun = stepsToRun.filter((step) => isStepEnabled(config, step.id));
     }
-    // CLI --no-logo overrides config; otherwise defer to config preference.
-    const showLogo = options.logo !== false && isLogoEnabled(config);
+    const logoIsEnabled = options.logo !== false && isLogoEnabled(config);
     await runUpdateCommand({
         steps: stepsToRun,
-        autoYes,
-        showLogo,
+        promptMode: autoYes ? "auto-accept" : "interactive",
+        logoVisibility: logoIsEnabled ? "visible" : "hidden",
         version: BRAEBURN_VERSION,
     });
 });
@@ -118,7 +114,7 @@ const configCommand = program
     .action(async () => {
     await runConfigCommand({ allSteps: ALL_STEPS });
 });
-const configurableSteps = ALL_STEPS.filter((s) => !PROTECTED_STEP_IDS.has(s.id));
+const configurableSteps = ALL_STEPS.filter((step) => !PROTECTED_STEP_IDS.has(step.id));
 const configUpdateCommand = configCommand
     .command("update")
     .description("Enable or disable individual update steps")
@@ -136,20 +132,19 @@ for (const step of configurableSteps) {
     configUpdateCommand.option(`--${step.id}`, `Enable ${step.name} updates`);
 }
 configUpdateCommand.action(function () {
-    // Use getOptionValueSource to detect only flags explicitly passed on the CLI.
-    // Commander defaults --no-* to true, so we can't rely on option values alone.
-    const stepUpdates = {};
+    // Commander defaults --no-* to true, so we use getOptionValueSource to detect explicit CLI flags.
+    const settingUpdates = {};
     for (const step of configurableSteps) {
         const source = configUpdateCommand.getOptionValueSource(step.id);
         if (source === "cli") {
-            stepUpdates[step.id] = configUpdateCommand.opts()[step.id];
+            settingUpdates[step.id] = configUpdateCommand.opts()[step.id] ? "enable" : "disable";
         }
     }
     const logoSource = configUpdateCommand.getOptionValueSource("logo");
-    const logoUpdate = logoSource === "cli"
-        ? configUpdateCommand.opts().logo
-        : undefined;
-    runConfigUpdateCommand({ stepUpdates, logoUpdate, allSteps: ALL_STEPS });
+    if (logoSource === "cli") {
+        settingUpdates["logo"] = configUpdateCommand.opts().logo ? "enable" : "disable";
+    }
+    runConfigUpdateCommand({ settingUpdates, allSteps: ALL_STEPS });
 });
 function resolveStepsByIds(stepIds) {
     const resolvedSteps = [];

package/dist/logger.d.ts

@@ -1,4 +1,4 @@
 export type StepLogWriter = (line: string) => Promise<void>;
-export declare function createLogWriterForStep(stepId: string): Promise<StepLogWriter>;
-export declare function findLatestLogFileForStep(stepId: string): string | null;
-export declare function listAllStepIdsWithLogs(): string[];
+export declare function createLogWriterForStep(stepId: string, logDirectory?: string): Promise<StepLogWriter>;
+export declare function findLatestLogFileForStep(stepId: string, logDirectory?: string): string | null;
+export declare function listAllStepIdsWithLogs(logDirectory?: string): string[];

package/dist/logger.js

@@ -2,41 +2,41 @@ import { mkdir, appendFile } from "node:fs/promises";
 import { existsSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-const BRAEBURN_LOG_DIRECTORY = join(homedir(), ".braeburn", "logs");
-async function ensureLogDirectoryExists() {
-    if (existsSync(BRAEBURN_LOG_DIRECTORY)) {
+const DEFAULT_LOG_DIRECTORY = join(homedir(), ".braeburn", "logs");
+async function ensureDirectoryExists(directoryPath) {
+    if (existsSync(directoryPath)) {
         return;
     }
-    await mkdir(BRAEBURN_LOG_DIRECTORY, { recursive: true });
+    await mkdir(directoryPath, { recursive: true });
 }
-export async function createLogWriterForStep(stepId) {
-    await ensureLogDirectoryExists();
+export async function createLogWriterForStep(stepId, logDirectory = DEFAULT_LOG_DIRECTORY) {
+    await ensureDirectoryExists(logDirectory);
     const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-    const logFilePath = join(BRAEBURN_LOG_DIRECTORY, `${stepId}-${timestamp}.log`);
+    const logFilePath = join(logDirectory, `${stepId}-${timestamp}.log`);
     const writeLineToLog = async (line) => {
         await appendFile(logFilePath, line + "\n", "utf-8");
     };
     return writeLineToLog;
 }
-export function findLatestLogFileForStep(stepId) {
-    if (!existsSync(BRAEBURN_LOG_DIRECTORY)) {
+export function findLatestLogFileForStep(stepId, logDirectory = DEFAULT_LOG_DIRECTORY) {
+    if (!existsSync(logDirectory)) {
         return null;
     }
-    const allFiles = readdirSync(BRAEBURN_LOG_DIRECTORY);
+    const allFiles = readdirSync(logDirectory);
     const filesForThisStep = allFiles
         .filter((fileName) => fileName.startsWith(`${stepId}-`))
         .sort()
-        .reverse(); // most recent first
+        .reverse();
     if (filesForThisStep.length === 0) {
         return null;
     }
-    return join(BRAEBURN_LOG_DIRECTORY, filesForThisStep[0]);
+    return join(logDirectory, filesForThisStep[0]);
 }
-export function listAllStepIdsWithLogs() {
-    if (!existsSync(BRAEBURN_LOG_DIRECTORY)) {
+export function listAllStepIdsWithLogs(logDirectory = DEFAULT_LOG_DIRECTORY) {
+    if (!existsSync(logDirectory)) {
         return [];
     }
-    const allFiles = readdirSync(BRAEBURN_LOG_DIRECTORY);
+    const allFiles = readdirSync(logDirectory);
     const stepIds = new Set(allFiles
         .map((fileName) => fileName.split("-")[0])
         .filter((maybeStepId) => Boolean(maybeStepId)));

package/dist/logo.js

@@ -1,5 +1,3 @@
-// The ASCII art is intentionally left-aligned with spaces as part of the design.
-// Keep the template literal formatting exactly as-is.
 export const LOGO_ART = `                ;
                :x :           
               .x\$+x           

package/dist/runner.d.ts

@@ -1,7 +1,8 @@
 import type { StepLogWriter } from "./logger.js";
+export type OutputSource = "stdout" | "stderr";
 export type CommandOutputLine = {
     text: string;
-    isError: boolean;
+    source: OutputSource;
 };
 export type OutputLineCallback = (line: CommandOutputLine) => void;
 type RunCommandOptions = {

package/dist/runner.js

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

package/dist/steps/cleanup.js

@@ -1,4 +1,4 @@
-import { checkCommandExists, runStep } from "./index.js";
+import { checkCommandExists } from "./index.js";
 const cleanupStep = {
     id: "cleanup",
     name: "Cleanup",
@@ -7,7 +7,7 @@ const cleanupStep = {
         return checkCommandExists("brew");
     },
     async run(context) {
-        await runStep("brew cleanup", context);
+        await context.runStep("brew cleanup");
     },
 };
 export default cleanupStep;

package/dist/steps/dotnet.js

@@ -1,14 +1,13 @@
-import { checkCommandExists, runStep } from "./index.js";
+import { checkCommandExists } from "./index.js";
 const dotnetStep = {
     id: "dotnet",
     name: ".NET",
     description: "Update all globally installed .NET tools",
-    // No brewPackageToInstall — .NET has its own installer
     async checkIsAvailable() {
         return checkCommandExists("dotnet");
     },
     async run(context) {
-        await runStep("dotnet tool update --global --all", context);
+        await context.runStep("dotnet tool update --global --all");
     },
 };
 export default dotnetStep;

package/dist/steps/homebrew.js

@@ -1,4 +1,4 @@
-import { checkCommandExists, runStep } from "./index.js";
+import { checkCommandExists } from "./index.js";
 const homebrewStep = {
     id: "homebrew",
     name: "Homebrew",
@@ -7,7 +7,7 @@ const homebrewStep = {
         return checkCommandExists("brew");
     },
     async run(context) {
-        await runStep("brew update && brew upgrade", context);
+        await context.runStep("brew update && brew upgrade");
     },
 };
 export default homebrewStep;

package/dist/steps/index.d.ts

@@ -3,11 +3,16 @@ 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 Step = {
     id: string;
     name: string;
     description: string;
+    warning?: string;
     brewPackageToInstall?: string;
     checkIsAvailable: () => Promise<boolean>;
     run: (context: StepRunContext) => Promise<void>;
@@ -25,3 +30,4 @@ 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, } from "../runner.js";
+import { doesShellCommandSucceed, runShellCommand, captureShellCommandOutput, } from "../runner.js";
 export { default as homebrewStep } from "./homebrew.js";
 export { default as masStep } from "./mas.js";
 export { default as ohmyzshStep } from "./ohmyzsh.js";
@@ -22,3 +22,12 @@ export async function runStep(shellCommand, context) {
         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.js

@@ -1,6 +1,3 @@
-import { runStep, } from "./index.js";
-import { captureShellCommandOutput } from "../runner.js";
-// softwareupdate always exists on macOS — no availability check needed
 const macosStep = {
     id: "macos",
     name: "macOS",
@@ -9,7 +6,7 @@ const macosStep = {
         return true;
     },
     async run(context) {
-        const updateListOutput = await captureShellCommandOutput({
+        const updateListOutput = await context.captureOutput({
             shellCommand: "softwareupdate -l 2>&1",
         });
         context.logWriter(updateListOutput);
@@ -17,16 +14,16 @@ const macosStep = {
         if (noUpdatesAvailable) {
             context.onOutputLine({
                 text: "macOS is already up to date.",
-                isError: false,
+                source: "stdout",
             });
             return;
         }
-        context.onOutputLine({ text: updateListOutput, isError: false });
+        context.onOutputLine({ text: updateListOutput, source: "stdout" });
         context.onOutputLine({
             text: "Updates found — installing now...",
-            isError: false,
+            source: "stdout",
         });
-        await runStep("softwareupdate -ia --verbose", context);
+        await context.runStep("softwareupdate -ia --verbose");
     },
 };
 export default macosStep;

package/dist/steps/mas.js

@@ -1,4 +1,4 @@
-import { checkCommandExists, runStep } from "./index.js";
+import { checkCommandExists } from "./index.js";
 const masStep = {
     id: "mas",
     name: "Mac App Store",
@@ -8,7 +8,7 @@ const masStep = {
         return checkCommandExists("mas");
     },
     async run(context) {
-        await runStep("mas upgrade", context);
+        await context.runStep("mas upgrade");
     },
 };
 export default masStep;

package/dist/steps/npm.js

@@ -1,14 +1,13 @@
-import { checkCommandExists, runStep } from "./index.js";
+import { checkCommandExists } from "./index.js";
 const npmStep = {
     id: "npm",
     name: "npm",
     description: "Update all globally installed npm packages",
-    // No brewPackageToInstall — npm comes bundled with Node.js
     async checkIsAvailable() {
         return checkCommandExists("npm");
     },
     async run(context) {
-        await runStep("npm update -g", context);
+        await context.runStep("npm update -g");
     },
 };
 export default npmStep;

package/dist/steps/nvm.js

@@ -1,6 +1,6 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { checkPathExists, runStep } from "./index.js";
+import { checkPathExists } from "./index.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.
@@ -9,12 +9,11 @@ const nvmStep = {
     id: "nvm",
     name: "Node.js (nvm)",
     description: "Install the latest Node.js via nvm, migrating packages from the current version",
-    // No brewPackageToInstall — nvm is installed via a curl script, not Homebrew
     async checkIsAvailable() {
         return checkPathExists(NVM_DIRECTORY);
     },
     async run(context) {
-        await runStep(`${NVM_SOURCE_PREFIX} && nvm install node --reinstall-packages-from=node`, context);
+        await context.runStep(`${NVM_SOURCE_PREFIX} && nvm install node --reinstall-packages-from=node`);
     },
 };
 export default nvmStep;

package/dist/steps/ohmyzsh.js

@@ -1,17 +1,16 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { checkPathExists, runStep } from "./index.js";
+import { checkPathExists } from "./index.js";
 const OH_MY_ZSH_UPGRADE_SCRIPT_PATH = join(homedir(), ".oh-my-zsh", "tools", "upgrade.sh");
 const ohmyzshStep = {
     id: "ohmyzsh",
     name: "Oh My Zsh",
     description: "Update Oh My Zsh to the latest version",
-    // No brewPackageToInstall — Oh My Zsh is installed via a curl script, not Homebrew
     async checkIsAvailable() {
         return checkPathExists(OH_MY_ZSH_UPGRADE_SCRIPT_PATH);
     },
     async run(context) {
-        await runStep(`zsh "${OH_MY_ZSH_UPGRADE_SCRIPT_PATH}"`, context);
+        await context.runStep(`zsh "${OH_MY_ZSH_UPGRADE_SCRIPT_PATH}"`);
     },
 };
 export default ohmyzshStep;

package/dist/steps/pip.js

@@ -1,17 +1,15 @@
-import { checkCommandExists, runStep } from "./index.js";
-// Updating all global pip3 packages can occasionally break tools that depend
-// on specific versions. The warning is surfaced in the UI before running.
+import { checkCommandExists } from "./index.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",
     name: "pip3",
     description: "Update all globally installed pip3 packages",
-    // No brewPackageToInstall — pip3 comes with Python
+    warning: "This updates all global pip3 packages, which can occasionally break tools.",
     async checkIsAvailable() {
         return checkCommandExists("pip3");
     },
     async run(context) {
-        await runStep(PIP_UPDATE_ALL_OUTDATED_SHELL_COMMAND, context);
+        await context.runStep(PIP_UPDATE_ALL_OUTDATED_SHELL_COMMAND);
     },
 };
 export default pipStep;

package/dist/steps/pyenv.js

@@ -1,7 +1,4 @@
-import { checkCommandExists, runStep, } from "./index.js";
-import { captureShellCommandOutput } from "../runner.js";
-// Dynamically finds the latest stable Python 3.x.y release known to pyenv,
-// excluding pre-releases (alpha, beta, release candidates, dev builds).
+import { checkCommandExists, } from "./index.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",
@@ -12,18 +9,18 @@ const pyenvStep = {
         return checkCommandExists("pyenv");
     },
     async run(context) {
-        await runStep("brew upgrade pyenv", context);
-        const latestPythonVersion = await captureShellCommandOutput({
+        await context.runStep("brew upgrade pyenv");
+        const latestPythonVersion = await context.captureOutput({
             shellCommand: FIND_LATEST_STABLE_PYTHON_SHELL_COMMAND,
         });
         if (!latestPythonVersion) {
             context.onOutputLine({
                 text: "Could not determine latest Python version — skipping pyenv install.",
-                isError: true,
+                source: "stderr",
             });
             return;
         }
-        await runStep(`pyenv install --skip-existing ${latestPythonVersion}`, context);
+        await context.runStep(`pyenv install --skip-existing ${latestPythonVersion}`);
     },
 };
 export default pyenvStep;

package/dist/ui/header.d.ts

@@ -1,12 +1,19 @@
 import type { Step } from "../steps/index.js";
-import type { StepPhase, CompletedStepRecord } from "./state.js";
+import type { 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[];
 type BuildHeaderOptions = {
     steps: Step[];
     version: string;
-    showLogo: boolean;
+    logoVisibility: LogoVisibility;
     currentStepIndex: number;
     currentPhase: StepPhase;
     completedStepRecords: CompletedStepRecord[];
+    terminalDimensions?: TerminalDimensions;
 };
 export declare function buildHeaderLines(options: BuildHeaderOptions): string[];
 export {};

package/dist/ui/header.js

@@ -2,7 +2,19 @@ import chalk from "chalk";
 import { LOGO_ART } from "../logo.js";
 const LOGO_COLUMN_WIDTH = 32;
 const LOGO_SEPARATOR = "    ";
-function stepTrackerIcon(phase) {
+const MIN_SIDE_BY_SIDE_COLS = LOGO_COLUMN_WIDTH + LOGO_SEPARATOR.length + 20; // 56
+export function determineLogoLayout(logoLines, dimensions) {
+    const cols = dimensions?.columns ?? process.stdout.columns ?? 80;
+    const rows = dimensions?.rows ?? process.stdout.rows ?? 24;
+    if (cols >= MIN_SIDE_BY_SIDE_COLS) {
+        return "side-by-side";
+    }
+    if (rows >= logoLines.length + 6) {
+        return "stacked";
+    }
+    return "none";
+}
+export function stepTrackerIcon(phase) {
     if (phase === "complete")
         return chalk.green("✓ ");
     if (phase === "failed")
@@ -17,15 +29,15 @@ function stepTrackerIcon(phase) {
         return chalk.cyan("→ ");
     return chalk.dim("· ");
 }
-function isActivePhase(phase) {
+export function isActivePhase(phase) {
     return (phase === "running" ||
         phase === "installing" ||
         phase === "prompting-to-run" ||
         phase === "prompting-to-install" ||
         phase === "checking-availability");
 }
-function deriveAllStepPhases(steps, currentStepIndex, currentPhase, completedStepRecords) {
-    return steps.map((_, index) => {
+export function deriveAllStepPhases(steps, currentStepIndex, currentPhase, completedStepRecords) {
+    return steps.map((_step, index) => {
         if (index < completedStepRecords.length)
             return completedStepRecords[index].phase;
         if (index === currentStepIndex)
@@ -34,7 +46,7 @@ function deriveAllStepPhases(steps, currentStepIndex, currentPhase, completedSte
     });
 }
 export function buildHeaderLines(options) {
-    const { steps, version, showLogo, currentStepIndex, currentPhase, completedStepRecords } = options;
+    const { steps, version, logoVisibility, currentStepIndex, currentPhase, completedStepRecords } = options;
     const phases = deriveAllStepPhases(steps, currentStepIndex, currentPhase, completedStepRecords);
     const rightColumnLines = [
         `${chalk.bold.white("braeburn")} ${chalk.dim("v" + version)}`,
@@ -46,18 +58,28 @@ export function buildHeaderLines(options) {
             return `${icon}${name}`;
         }),
     ];
-    if (!showLogo) {
+    if (logoVisibility === "hidden") {
         return rightColumnLines;
     }
     const logoLines = LOGO_ART.split("\n");
+    const layout = determineLogoLayout(logoLines, options.terminalDimensions);
+    if (layout === "none") {
+        return rightColumnLines;
+    }
+    if (layout === "stacked") {
+        return [
+            ...logoLines.map((line) => chalk.yellow(line)),
+            "",
+            ...rightColumnLines,
+        ];
+    }
     const totalLines = Math.max(logoLines.length, rightColumnLines.length);
     const result = [];
-    for (let i = 0; i < totalLines; i++) {
-        // Pad the raw logo line to a fixed width before applying colour, so the
-        // ANSI escape codes don't affect visual alignment.
-        const rawLogoLine = (logoLines[i] ?? "").padEnd(LOGO_COLUMN_WIDTH);
+    for (let lineIndex = 0; lineIndex < totalLines; lineIndex++) {
+        // Padding must happen before chalk; ANSI escape codes break .padEnd() alignment.
+        const rawLogoLine = (logoLines[lineIndex] ?? "").padEnd(LOGO_COLUMN_WIDTH);
         const logoColumn = chalk.yellow(rawLogoLine);
-        const rightColumn = rightColumnLines[i] ?? "";
+        const rightColumn = rightColumnLines[lineIndex] ?? "";
         result.push(`${logoColumn}${LOGO_SEPARATOR}${rightColumn}`);
     }
     return result;

package/dist/ui/outputBox.d.ts

@@ -1,2 +1,6 @@
 import type { CommandOutputLine } from "../runner.js";
-export declare function buildOutputBoxLines(lines: CommandOutputLine[], stepName: string): string[];
+export type TerminalDimensions = {
+    columns: number;
+    rows: number;
+};
+export declare function buildOutputBoxLines(lines: CommandOutputLine[], stepName: string, dimensions?: TerminalDimensions): string[];

package/dist/ui/outputBox.js

@@ -3,17 +3,23 @@ const INDENT = "  ";
 const HEADER_LINES_APPROXIMATE = 18;
 const OUTPUT_BOX_CHROME_LINES = 3;
 const MINIMUM_VISIBLE_LINES = 5;
-function maxVisibleLines() {
-    const rows = process.stdout.rows ?? 40;
+function maxVisibleLines(rows) {
     const available = rows - HEADER_LINES_APPROXIMATE - OUTPUT_BOX_CHROME_LINES;
     return Math.max(MINIMUM_VISIBLE_LINES, available);
 }
-function boxWidth() {
-    return Math.min(process.stdout.columns ?? 80, 120) - INDENT.length * 2;
+function boxWidth(columns) {
+    return Math.min(columns, 120) - INDENT.length * 2;
 }
-export function buildOutputBoxLines(lines, stepName) {
-    const visibleLines = lines.slice(-maxVisibleLines());
-    const width = boxWidth();
+function resolveTerminalDimensions(dimensions) {
+    return dimensions ?? {
+        columns: process.stdout.columns ?? 80,
+        rows: process.stdout.rows ?? 40,
+    };
+}
+export function buildOutputBoxLines(lines, stepName, dimensions) {
+    const resolved = resolveTerminalDimensions(dimensions);
+    const visibleLines = lines.slice(-maxVisibleLines(resolved.rows));
+    const width = boxWidth(resolved.columns);
     const headerLabel = `─ ${stepName} output `;
     const topDashes = "─".repeat(Math.max(0, width - headerLabel.length - 2));
     const topBorder = chalk.dim(`${INDENT}┌${headerLabel}${topDashes}┐`);
@@ -21,7 +27,7 @@ export function buildOutputBoxLines(lines, stepName) {
     const result = [topBorder];
     for (const line of visibleLines) {
         const truncated = line.text.slice(0, width - 4);
-        const colored = line.isError ? chalk.yellow(truncated) : chalk.dim(truncated);
+        const colored = line.source === "stderr" ? chalk.yellow(truncated) : chalk.dim(truncated);
         result.push(`${INDENT}${chalk.dim("│")} ${colored}`);
     }
     result.push(bottomBorder);

package/dist/ui/screen.d.ts

@@ -1,3 +1,5 @@
+import { type TerminalDimensions } from "./outputBox.js";
 import type { AppState } from "./state.js";
-export declare function renderScreen(content: string): void;
-export declare function buildScreen(state: AppState): string;
+export type ScreenRenderer = (content: string) => void;
+export declare function createScreenRenderer(output?: NodeJS.WritableStream): ScreenRenderer;
+export declare function buildScreen(state: AppState, terminalDimensions?: TerminalDimensions): string;

package/dist/ui/screen.js

@@ -3,26 +3,29 @@ import { buildActiveStepLines } from "./currentStep.js";
 import { buildOutputBoxLines } from "./outputBox.js";
 import { buildPromptLines } from "./prompt.js";
 import { buildVersionReportLines } from "./versionReport.js";
-let previousLineCount = 0;
-export function renderScreen(content) {
-    if (previousLineCount > 0) {
-        process.stdout.write(`\x1b[${previousLineCount}A\x1b[J`);
-    }
-    process.stdout.write(content);
-    previousLineCount = (content.match(/\n/g) ?? []).length;
+export function createScreenRenderer(output = process.stdout) {
+    let previousLineCount = 0;
+    return (content) => {
+        if (previousLineCount > 0) {
+            output.write(`\x1b[${previousLineCount}A\x1b[J`);
+        }
+        output.write(content);
+        previousLineCount = (content.match(/\n/g) ?? []).length;
+    };
 }
-export function buildScreen(state) {
+export function buildScreen(state, terminalDimensions) {
     const lines = [];
     lines.push(...buildHeaderLines({
         steps: state.steps,
         version: state.version,
-        showLogo: state.showLogo,
+        logoVisibility: state.logoVisibility,
         currentStepIndex: state.currentStepIndex,
         currentPhase: state.currentPhase,
         completedStepRecords: state.completedStepRecords,
+        terminalDimensions,
     }));
     lines.push("");
-    if (state.isFinished) {
+    if (state.runCompletion === "finished") {
         if (state.versionReport) {
             lines.push("");
             lines.push(...buildVersionReportLines(state.versionReport));
@@ -42,7 +45,7 @@ export function buildScreen(state) {
                 state.currentOutputLines.length > 0;
             if (isShowingOutput) {
                 lines.push("");
-                lines.push(...buildOutputBoxLines(state.currentOutputLines, currentStep.name));
+                lines.push(...buildOutputBoxLines(state.currentOutputLines, currentStep.name, terminalDimensions));
             }
             if (state.currentPrompt) {
                 lines.push("");

package/dist/ui/state.d.ts

@@ -13,16 +13,18 @@ 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;
-    showLogo: boolean;
+    logoVisibility: LogoVisibility;
     currentStepIndex: number;
     currentPhase: StepPhase;
     completedStepRecords: CompletedStepRecord[];
     currentOutputLines: CommandOutputLine[];
     currentPrompt: CurrentPrompt | undefined;
-    isFinished: boolean;
+    runCompletion: RunCompletion;
     versionReport: ResolvedVersion[] | undefined;
 };
-export declare function createInitialAppState(steps: Step[], version: string, showLogo: boolean): AppState;
+export declare function createInitialAppState(steps: Step[], version: string, logoVisibility: LogoVisibility): AppState;

package/dist/ui/state.js

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

package/dist/ui/terminal.d.ts

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

package/dist/ui/terminal.js

@@ -0,0 +1,16 @@
+export function hideCursorDuringExecution(options = {}) {
+    const output = options.output ?? process.stdout;
+    output.write("\x1b[?25l");
+    const restoreOnExit = () => output.write("\x1b[?25h");
+    const restoreAndExitOnInterrupt = () => {
+        output.write("\x1b[?25h\n");
+        process.exit(130);
+    };
+    process.on("exit", restoreOnExit);
+    process.on("SIGINT", restoreAndExitOnInterrupt);
+    return () => {
+        process.removeListener("exit", restoreOnExit);
+        process.removeListener("SIGINT", restoreAndExitOnInterrupt);
+        output.write("\x1b[?25h");
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "braeburn",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "macOS system updater CLI",
   "type": "module",
   "bin": {
@@ -17,6 +17,8 @@
     "postbuild": "chmod +x dist/index.js",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
@@ -28,6 +30,7 @@
   "devDependencies": {
     "@types/node": "^24.0.0",
     "tsx": "^4.7.0",
-    "typescript": "^5.5.0"
+    "typescript": "^5.5.0",
+    "vitest": "^4.0.18"
   }
 }