braeburn 1.2.2 → 1.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/braeburn)](https://www.npmjs.com/package/braeburn)
 
-A macOS system updater CLI. Runs update steps for Homebrew, Mac App Store, Oh My Zsh, npm, pip, pyenv, nvm, .NET, and macOS itself.
+A macOS system updater CLI. Keeps tools installed via Homebrew, npm, pip, .NET, and others up to date.
 
 ## Install
 
@@ -30,7 +30,20 @@ braeburn homebrew npm # run specific steps only
 
 ## Steps
 
-`homebrew` `mas` `ohmyzsh` `npm` `pip` `pyenv` `nvm` `dotnet` `macos` `cleanup`
+Steps run in two stages. The runtime stage runs first and is **off by default** — upgrading a runtime is a larger change than upgrading a tool, and is best done intentionally.
+
+| Step | Stage | Default | Requires |
+|---|---|---|---|
+| `pyenv` | runtime | off | `pyenv` or Homebrew |
+| `nvm` | runtime | off | `~/.nvm` |
+| `homebrew` | tools | on | `brew` (required) |
+| `mas` | tools | on | `mas` |
+| `ohmyzsh` | tools | on | `~/.oh-my-zsh` |
+| `npm` | tools | on | `npm` |
+| `pip` | tools | on | `pip3` |
+| `dotnet` | tools | on | `dotnet` |
+| `macos` | tools | on | — |
+| `cleanup` | tools | on | `brew` |
 
 ## Requirements
 

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, DEFAULT_OFF_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();
@@ -90,10 +76,13 @@ export async function runConfigUpdateCommand(options) {
 }
 async function writeCleanConfig(config) {
     const cleaned = { steps: {} };
-    for (const [stepId, enabled] of Object.entries(config.steps)) {
-        if (enabled === false) {
+    for (const [stepId, value] of Object.entries(config.steps)) {
+        if (value === false && !DEFAULT_OFF_STEP_IDS.has(stepId)) {
             cleaned.steps[stepId] = false;
         }
+        else if (value === true && DEFAULT_OFF_STEP_IDS.has(stepId)) {
+            cleaned.steps[stepId] = true;
+        }
     }
     if (config.logo === false) {
         cleaned.logo = false;

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,31 @@ 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;
+    const hasRuntimeItems = items.some((item) => item.step.stage === "runtime");
+    const hasToolsItems = items.some((item) => item.step.stage === "tools");
+    const showStageLabels = hasRuntimeItems && hasToolsItems;
+    for (let itemIndex = 0; itemIndex < items.length; itemIndex++) {
+        const item = items[itemIndex];
+        const isCursor = itemIndex === cursorIndex;
+        if (showStageLabels) {
+            const isFirstRuntime = item.step.stage === "runtime" && (itemIndex === 0 || items[itemIndex - 1].step.stage !== "runtime");
+            const isFirstTools = item.step.stage === "tools" && (itemIndex === 0 || items[itemIndex - 1].step.stage !== "tools");
+            if (isFirstRuntime) {
+                lines.push(`  ${chalk.dim("── Runtimes ─────────────────────────────────────────────────────────")}`);
+            }
+            else if (isFirstTools) {
+                lines.push(`  ${chalk.dim("── Tools ────────────────────────────────────────────────────────────")}`);
+            }
+        }
         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 +65,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: 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));
-    // 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 +102,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 +118,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,5 +1,5 @@
-/** Steps that cannot be disabled — brew is a hard runtime dependency. */
 export declare const PROTECTED_STEP_IDS: Set<string>;
+export declare const DEFAULT_OFF_STEP_IDS: Set<string>;
 export type BraeburnConfig = {
     steps: Record<string, boolean>;
     logo?: boolean;
@@ -8,5 +8,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,13 @@ 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"]);
+export const DEFAULT_OFF_STEP_IDS = new Set(["nvm", "pyenv"]);
 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 +42,46 @@ 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;
+    if (DEFAULT_OFF_STEP_IDS.has(settingId))
+        return config.steps[settingId] === true;
+    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 (DEFAULT_OFF_STEP_IDS.has(settingId)) {
+        if (desiredState === "enable") {
+            updatedConfig.steps[settingId] = true;
+        }
+        else {
+            delete updatedConfig.steps[settingId];
+        }
+        return updatedConfig;
+    }
+    if (desiredState === "enable") {
+        delete updatedConfig.steps[settingId];
+    }
+    else {
+        updatedConfig.steps[settingId] = false;
+    }
+    return updatedConfig;
 }

package/dist/index.js

@@ -10,13 +10,13 @@ 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,
-    pyenvStep,
-    nvmStep,
     dotnetStep,
     macosStep,
     cleanupStep,
@@ -34,33 +34,36 @@ 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")
     .addHelpText("after", `
 Step descriptions:
+  Runtime stage (default: off — update the version managers and runtimes themselves):
+  pyenv      Upgrade pyenv, install latest Python 3.x  (requires: pyenv or brew)
+  nvm        Install latest Node.js via nvm             (requires: ~/.nvm)
+
+  Tools stage (default: on — update packages installed via the managers above):
   homebrew   Update Homebrew itself and all installed formulae
   mas        Upgrade Mac App Store apps  (requires: mas)
   ohmyzsh    Update Oh My Zsh            (requires: ~/.oh-my-zsh)
   npm        Update global npm packages  (requires: npm)
   pip        Update global pip3 packages (requires: pip3) ⚠ may be fragile
-  pyenv      Upgrade pyenv, install latest Python 3.x (requires: pyenv or brew)
-  nvm        Update Node.js via nvm      (requires: ~/.nvm)
   dotnet     Update .NET global tools    (requires: dotnet)
   macos      Check for macOS updates, prompt to install
   cleanup    Clean up Homebrew cache and old downloads
 
 Examples:
-  braeburn                  Run all steps interactively
-  braeburn -y               Run all steps, auto-accept everything
+  braeburn                  Run all enabled steps interactively
+  braeburn -y               Run all enabled steps, auto-accept everything
   braeburn -fy              Same as above
   braeburn homebrew npm     Run only the homebrew and npm steps
   braeburn homebrew -y      Run only homebrew, auto-accept
+  braeburn nvm pyenv        Run only the runtime-stage steps
   `)
     .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 +71,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 +118,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 +136,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[];