braeburn 2.0.0 → 2.1.0

package/dist/cli.d.ts

@@ -0,0 +1,39 @@
+import { Command } from "commander";
+import type { Step } from "./steps/index.js";
+import { applyUpdateCommandResult, 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 { configFileExists, readConfig } from "./config.js";
+type CliProcess = Pick<NodeJS.Process, "stderr"> & {
+    exitCode: string | number | null | undefined;
+};
+type CliCommandDependencies = {
+    applyUpdateCommandResult: typeof applyUpdateCommandResult;
+    configFileExists: typeof configFileExists;
+    readConfig: typeof readConfig;
+    runConfigCommand: typeof runConfigCommand;
+    runConfigUpdateCommand: typeof runConfigUpdateCommand;
+    runLogCommand: typeof runLogCommand;
+    runLogListCommand: typeof runLogListCommand;
+    runSetupCommand: typeof runSetupCommand;
+    runUpdateCommand: typeof runUpdateCommand;
+};
+type CreateBraeburnProgramOptions = {
+    allSteps?: Step[];
+    dependencies?: Partial<CliCommandDependencies>;
+    processLike?: CliProcess;
+    version?: string;
+};
+export type StepResolution = {
+    status: "resolved";
+    steps: Step[];
+} | {
+    status: "unknown-step";
+    stepId: string;
+};
+export declare function resolveStepsByIds(stepIds: string[], allSteps: Step[]): StepResolution;
+export declare function reportCliError(error: unknown, processLike?: CliProcess): void;
+export declare function createBraeburnProgram(options?: CreateBraeburnProgramOptions): Command;
+export declare function runBraeburnCli(argv?: string[]): Promise<void>;
+export {};

package/dist/cli.js

@@ -0,0 +1,226 @@
+import { Command } from "commander";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { ALL_STEPS } from "./steps/catalog.js";
+import { applyUpdateCommandResult, 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 { ConfigReadError, PROTECTED_STEP_IDS, configFileExists, isLogoEnabled, isStepEnabled, readConfig, } from "./config.js";
+const requireFromThis = createRequire(import.meta.url);
+function resolveBraeburnVersion() {
+    const packageJson = requireFromThis(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"));
+    return packageJson.version;
+}
+function resolveDependencies(overrides) {
+    return {
+        applyUpdateCommandResult: overrides?.applyUpdateCommandResult ?? applyUpdateCommandResult,
+        configFileExists: overrides?.configFileExists ?? configFileExists,
+        readConfig: overrides?.readConfig ?? readConfig,
+        runConfigCommand: overrides?.runConfigCommand ?? runConfigCommand,
+        runConfigUpdateCommand: overrides?.runConfigUpdateCommand ?? runConfigUpdateCommand,
+        runLogCommand: overrides?.runLogCommand ?? runLogCommand,
+        runLogListCommand: overrides?.runLogListCommand ?? runLogListCommand,
+        runSetupCommand: overrides?.runSetupCommand ?? runSetupCommand,
+        runUpdateCommand: overrides?.runUpdateCommand ?? runUpdateCommand,
+    };
+}
+export function resolveStepsByIds(stepIds, allSteps) {
+    const stepsById = new Map(allSteps.map((step) => [step.id, step]));
+    const resolvedSteps = [];
+    for (const stepId of stepIds) {
+        const step = stepsById.get(stepId);
+        if (!step) {
+            return { status: "unknown-step", stepId };
+        }
+        resolvedSteps.push(step);
+    }
+    return { status: "resolved", steps: resolvedSteps };
+}
+export function reportCliError(error, processLike = process) {
+    if (error instanceof ConfigReadError) {
+        processLike.stderr.write(`${error.message}\n`);
+        processLike.exitCode = 1;
+        return;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    processLike.stderr.write(`${message}\n`);
+    processLike.exitCode = 1;
+}
+export function createBraeburnProgram(options = {}) {
+    const allSteps = options.allSteps ?? ALL_STEPS;
+    const dependencies = resolveDependencies(options.dependencies);
+    const processLike = options.processLike ?? process;
+    const braeburnVersion = options.version ?? resolveBraeburnVersion();
+    const program = new Command();
+    program
+        .name("braeburn")
+        .description("macOS system updater")
+        .version(braeburnVersion)
+        .helpCommand(false);
+    program
+        .command("update", { isDefault: true })
+        .description("Run system update steps (default command)")
+        .argument("[steps...]", `Steps to run — omit to run all.\nAvailable: ${allSteps.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:
+  System / Runtimes (default: off — larger changes, enabled intentionally):
+  pyenv      Upgrade pyenv, install latest Python 3.x  (requires: pyenv or brew)
+  nvm        Install latest Node.js via nvm             (requires: ~/.nvm)
+
+  System / Apps & Packages:
+  homebrew   Update Homebrew itself and all installed formulae
+  mas        Upgrade Mac App Store apps  (requires: mas)
+  macos      Check for macOS updates, prompt to install
+
+  System / CLI Tools:
+  npm        Update global npm packages  (requires: npm)
+  braeburn   Update braeburn CLI itself  (requires: npm)
+  pip        Update global pip3 packages (requires: pip3) ⚠ may be fragile
+  dotnet     Update .NET global tools    (requires: dotnet)
+
+  System / Shell:
+  ohmyzsh    Update Oh My Zsh            (requires: ~/.oh-my-zsh)
+
+  System / Maintenance:
+  cleanup    homebrew cleanup (remove outdated Homebrew cache/downloads)
+
+Examples:
+  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 steps
+  `)
+        .action(async (stepArguments, updateOptions) => {
+        const autoYes = updateOptions.yes === true || updateOptions.force === true;
+        if (!(await dependencies.configFileExists())) {
+            await dependencies.runSetupCommand(allSteps);
+        }
+        const config = await dependencies.readConfig();
+        let stepsToRun = allSteps;
+        if (stepArguments.length > 0) {
+            const stepResolution = resolveStepsByIds(stepArguments, allSteps);
+            if (stepResolution.status === "unknown-step") {
+                processLike.stderr.write(`Unknown step: "${stepResolution.stepId}". Run braeburn --help to see available steps.\n`);
+                processLike.exitCode = 1;
+                return;
+            }
+            stepsToRun = stepResolution.steps;
+        }
+        if (stepArguments.length === 0) {
+            stepsToRun = stepsToRun.filter((step) => isStepEnabled(config, step.id));
+        }
+        const logoIsEnabled = updateOptions.logo !== false && isLogoEnabled(config);
+        const updateCommandResult = await dependencies.runUpdateCommand({
+            steps: stepsToRun,
+            promptMode: autoYes ? "auto-accept" : "interactive",
+            logoVisibility: logoIsEnabled ? "visible" : "hidden",
+            version: braeburnVersion,
+        });
+        dependencies.applyUpdateCommandResult(updateCommandResult, processLike);
+    });
+    program
+        .command("log")
+        .description("View the most recent output log for a given step")
+        .argument("[step]", "Step ID to view logs for (e.g. homebrew, npm, pip)")
+        .option("--homebrew", "Show latest Homebrew log")
+        .option("--brew", "Alias for --homebrew")
+        .option("--mas", "Show latest Mac App Store log")
+        .option("--ohmyzsh", "Show latest Oh My Zsh log")
+        .option("--npm", "Show latest npm log")
+        .option("--braeburn", "Show latest braeburn log")
+        .option("--pip", "Show latest pip3 log")
+        .option("--pyenv", "Show latest pyenv log")
+        .option("--nvm", "Show latest nvm log")
+        .option("--dotnet", "Show latest .NET log")
+        .option("--macos", "Show latest macOS update log")
+        .option("--cleanup", "Show latest homebrew cleanup log")
+        .addHelpText("after", `
+Examples:
+  braeburn log              List all available step logs
+  braeburn log homebrew     Show the latest Homebrew run log
+  braeburn log --brew       Same as above
+  braeburn log npm | less   Pipe log output through less
+  `)
+        .action(async (stepArgument, logOptions) => {
+        const stepIdFromFlag = logOptions.brew === true
+            ? "homebrew"
+            : allSteps.map((step) => step.id).find((stepId) => logOptions[stepId] === true);
+        const resolvedStepId = stepArgument ?? stepIdFromFlag;
+        if (!resolvedStepId) {
+            dependencies.runLogListCommand();
+            return;
+        }
+        await dependencies.runLogCommand({ stepId: resolvedStepId });
+    });
+    const configCommand = program
+        .command("config")
+        .description("View or edit braeburn configuration")
+        .action(() => {
+        configCommand.outputHelp();
+    });
+    configCommand
+        .command("list")
+        .description("Print current configuration")
+        .action(async () => {
+        await dependencies.runConfigCommand({
+            allSteps,
+            outputMode: "non-interactive",
+        });
+    });
+    const configurableSteps = allSteps.filter((step) => !PROTECTED_STEP_IDS.has(step.id));
+    const configUpdateCommand = configCommand
+        .command("update")
+        .description("Edit configuration (interactive by default, flags for direct updates)")
+        .addHelpText("after", `
+Examples:
+  braeburn config update                     Open interactive config editor
+  braeburn config update --no-logo           Hide the logo
+  braeburn config update --no-ohmyzsh        Disable Oh My Zsh updates
+  braeburn config update --no-pip --no-nvm   Disable pip and nvm updates
+  braeburn config update --ohmyzsh           Re-enable Oh My Zsh updates
+    `);
+    configUpdateCommand.option("--no-logo", "Hide the logo");
+    configUpdateCommand.option("--logo", "Show the logo");
+    for (const step of configurableSteps) {
+        configUpdateCommand.option(`--no-${step.id}`, `Disable ${step.name} updates`);
+        configUpdateCommand.option(`--${step.id}`, `Enable ${step.name} updates`);
+    }
+    configUpdateCommand.action(async function () {
+        // 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") {
+                settingUpdates[step.id] = configUpdateCommand.opts()[step.id] ? "enable" : "disable";
+            }
+        }
+        const logoSource = configUpdateCommand.getOptionValueSource("logo");
+        if (logoSource === "cli") {
+            settingUpdates.logo = configUpdateCommand.opts().logo ? "enable" : "disable";
+        }
+        if (Object.keys(settingUpdates).length === 0) {
+            await dependencies.runConfigCommand({
+                allSteps,
+                outputMode: "interactive",
+            });
+            return;
+        }
+        await dependencies.runConfigUpdateCommand({ settingUpdates, allSteps });
+    });
+    return program;
+}
+export async function runBraeburnCli(argv = process.argv) {
+    try {
+        await createBraeburnProgram().parseAsync(argv);
+    }
+    catch (error) {
+        reportCliError(error);
+    }
+}

package/dist/commands/setup.d.ts

@@ -1,3 +1,4 @@
+import { type BraeburnConfig } from "../config.js";
 import { type Step, type StepCategoryId } from "../steps/index.js";
 export type SelectionState = "selected" | "deselected";
 export type ProtectionStatus = "protected" | "configurable";
@@ -17,4 +18,6 @@ export type SelectableStep = {
 };
 export declare function buildLoadingScreen(): string;
 export declare function buildSetupScreen(items: SelectableStep[], cursorIndex: number): string;
+export declare function buildSetupItems(allSteps: Step[], availabilityResults: boolean[]): SelectableStep[];
+export declare function buildConfigFromSetupItems(items: SelectableStep[]): BraeburnConfig;
 export declare function runSetupCommand(allSteps: Step[]): Promise<void>;

package/dist/commands/setup.js

@@ -64,26 +64,42 @@ export function buildSetupScreen(items, cursorIndex) {
     lines.push("");
     return lines.join("\n") + "\n";
 }
+export function buildSetupItems(allSteps, availabilityResults) {
+    return allSteps.map((step, stepIndex) => ({
+        step: {
+            id: step.id,
+            name: step.name,
+            description: step.description,
+            categoryId: step.categoryId,
+            brewPackageToInstall: step.brewPackageToInstall,
+        },
+        selection: PROTECTED_STEP_IDS.has(step.id) || CONSERVATIVE_DEFAULT_ON_STEP_IDS.has(step.id)
+            ? "selected"
+            : "deselected",
+        protection: PROTECTED_STEP_IDS.has(step.id) ? "protected" : "configurable",
+        availability: availabilityResults[stepIndex] ? "available" : "unavailable",
+    }));
+}
+export function buildConfigFromSetupItems(items) {
+    const draftConfig = {
+        defaultsProfile: "conservative-v2",
+        steps: {},
+    };
+    for (const item of items) {
+        if (item.protection === "protected") {
+            continue;
+        }
+        draftConfig.steps[item.step.id] = item.selection === "selected";
+    }
+    return cleanConfigForWrite(draftConfig);
+}
 export async function runSetupCommand(allSteps) {
     const render = createScreenRenderer();
     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,
-                categoryId: step.categoryId,
-                brewPackageToInstall: step.brewPackageToInstall,
-            },
-            selection: PROTECTED_STEP_IDS.has(step.id) || CONSERVATIVE_DEFAULT_ON_STEP_IDS.has(step.id)
-                ? "selected"
-                : "deselected",
-            protection: PROTECTED_STEP_IDS.has(step.id) ? "protected" : "configurable",
-            availability: availabilityResults[stepIndex] ? "available" : "unavailable",
-        }));
+        const items = buildSetupItems(allSteps, availabilityResults);
         let cursorIndex = 0;
         render(buildSetupScreen(items, cursorIndex));
         await new Promise((resolve) => {
@@ -120,17 +136,7 @@ export async function runSetupCommand(allSteps) {
             process.stdin.on("keypress", handleKeypress);
             process.stdin.resume();
         });
-        const draftConfig = {
-            defaultsProfile: "conservative-v2",
-            steps: {},
-        };
-        for (const item of items) {
-            if (item.protection === "protected") {
-                continue;
-            }
-            draftConfig.steps[item.step.id] = item.selection === "selected";
-        }
-        await writeConfig(cleanConfigForWrite(draftConfig));
+        await writeConfig(buildConfigFromSetupItems(items));
         const confirmationLines = [
             chalk.yellow(LOGO_ART),
             "",

package/dist/commands/update.d.ts

@@ -1,5 +1,5 @@
 import { type PromptMode } from "../update/engine.js";
-import { type LogoVisibility } from "../update/state.js";
+import { type LogoVisibility, type UpdateState } from "../update/state.js";
 import type { Step } from "../steps/index.js";
 type RunUpdateCommandOptions = {
     steps: Step[];
@@ -13,6 +13,7 @@ export type UpdateCommandResult = {
 type ExitCodeWritable = {
     exitCode: string | number | null | undefined;
 };
+export declare function shouldRenderRuntimeStateImmediately(state: UpdateState, lastRuntimeRenderTime: number, currentTime: number): boolean;
 export declare function applyUpdateCommandResult(updateCommandResult: UpdateCommandResult, processWithExitCode: ExitCodeWritable): void;
 export declare function runUpdateCommand(options: RunUpdateCommandOptions): Promise<UpdateCommandResult>;
 export {};

package/dist/commands/update.js

@@ -6,9 +6,19 @@ import { hideCursorDuringExecution } from "../ui/terminal.js";
 import { runUpdateEngine } from "../update/engine.js";
 import { countFailedSteps } from "../update/state.js";
 import { cancelActiveShellCommand } from "../runner.js";
+const RUNTIME_RENDER_INTERVAL_MS = 100;
 function shouldCaptureRuntimeAbortKey(state) {
     return state?.currentPhase === "running" || state?.currentPhase === "installing";
 }
+function shouldThrottleRuntimeRender(state) {
+    return state.runCompletion !== "finished" && shouldCaptureRuntimeAbortKey(state);
+}
+export function shouldRenderRuntimeStateImmediately(state, lastRuntimeRenderTime, currentTime) {
+    if (!shouldThrottleRuntimeRender(state)) {
+        return true;
+    }
+    return currentTime - lastRuntimeRenderTime >= RUNTIME_RENDER_INTERVAL_MS;
+}
 export function applyUpdateCommandResult(updateCommandResult, processWithExitCode) {
     if (updateCommandResult.failedStepCount > 0) {
         processWithExitCode.exitCode = 1;
@@ -22,6 +32,25 @@ export async function runUpdateCommand(options) {
     let runtimeAbortKeyCaptureEnabled = false;
     let animationFrameIndex = 0;
     let updateCommandResult = { failedStepCount: 0 };
+    let lastRuntimeRenderTime = 0;
+    const renderState = (state) => {
+        renderScreen(buildScreenWithAnimationFrame(state, animationFrameIndex));
+        if (shouldThrottleRuntimeRender(state)) {
+            lastRuntimeRenderTime = Date.now();
+        }
+    };
+    const renderStateWithRuntimeThrottle = (state) => {
+        if (!shouldThrottleRuntimeRender(state)) {
+            renderState(state);
+            return;
+        }
+        const currentTime = Date.now();
+        if (shouldRenderRuntimeStateImmediately(state, lastRuntimeRenderTime, currentTime)) {
+            renderState(state);
+            return;
+        }
+        // The animation timer renders the latest runtime state at the next frame.
+    };
     const handleRuntimeKeypress = (typedCharacter, key) => {
         if (key?.ctrl && key?.name === "c") {
             process.stdout.write("\x1b[?25h\n");
@@ -67,8 +96,8 @@ export async function runUpdateCommand(options) {
             return;
         }
         animationFrameIndex += 1;
-        renderScreen(buildScreenWithAnimationFrame(latestState, animationFrameIndex));
-    }, 100);
+        renderState(latestState);
+    }, RUNTIME_RENDER_INTERVAL_MS);
     try {
         const finalState = await runUpdateEngine({
             steps: options.steps,
@@ -85,7 +114,7 @@ export async function runUpdateCommand(options) {
                 else {
                     disableRuntimeAbortKeyCapture();
                 }
-                renderScreen(buildScreenWithAnimationFrame(state, animationFrameIndex));
+                renderStateWithRuntimeThrottle(state);
             },
         });
         finalScreen = buildScreen(finalState);

package/dist/config.d.ts

@@ -7,10 +7,18 @@ export type BraeburnConfig = {
     logo?: boolean;
     defaultsProfile?: ConfigDefaultsProfile;
 };
+export declare class ConfigReadError extends Error {
+    readonly configPath: string;
+    readonly originalError: unknown;
+    constructor(configPath: string, originalError: unknown);
+}
+export declare function parseConfig(rawConfig: string): BraeburnConfig;
 export declare function resolveConfigPath(): Promise<string>;
 export declare function configFileExists(): Promise<boolean>;
 export declare function readConfig(): Promise<BraeburnConfig>;
+export declare function readConfigFromPath(configPath: string): Promise<BraeburnConfig>;
 export declare function writeConfig(config: BraeburnConfig): Promise<void>;
+export declare function writeConfigToPath(configPath: string, 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;

package/dist/config.js

@@ -1,5 +1,5 @@
 import { readFile, writeFile, mkdir, access } from "node:fs/promises";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { parse, stringify } from "smol-toml";
 export const PROTECTED_STEP_IDS = new Set(["homebrew"]);
@@ -9,14 +9,67 @@ const EMPTY_CONFIG = { steps: {} };
 const LOGO_SETTING_ID = "logo";
 const DEFAULTS_PROFILE_SETTING_ID = "defaultsProfile";
 const LEGACY_PROFILE = "legacy";
+export class ConfigReadError extends Error {
+    configPath;
+    originalError;
+    constructor(configPath, originalError) {
+        const reason = originalError instanceof Error ? originalError.message : String(originalError);
+        super(`Could not read braeburn config at ${configPath}: ${reason}`);
+        this.name = "ConfigReadError";
+        this.configPath = configPath;
+        this.originalError = originalError;
+    }
+}
 function resolveDefaultsProfile(config) {
     return config.defaultsProfile ?? LEGACY_PROFILE;
 }
 function parseDefaultsProfile(rawValue) {
+    if (rawValue === undefined) {
+        return undefined;
+    }
     if (rawValue === "legacy" || rawValue === "conservative-v2") {
         return rawValue;
     }
-    return undefined;
+    throw new Error(`"${DEFAULTS_PROFILE_SETTING_ID}" must be "legacy" or "conservative-v2".`);
+}
+function parseSteps(rawValue) {
+    if (rawValue === undefined) {
+        return {};
+    }
+    if (typeof rawValue !== "object" || rawValue === null || Array.isArray(rawValue)) {
+        throw new Error('"steps" must be a table of step IDs to boolean values.');
+    }
+    const steps = {};
+    for (const [stepId, enabled] of Object.entries(rawValue)) {
+        if (typeof enabled !== "boolean") {
+            throw new Error(`"steps.${stepId}" must be true or false.`);
+        }
+        steps[stepId] = enabled;
+    }
+    return steps;
+}
+function parseLogo(rawValue) {
+    if (rawValue === undefined || typeof rawValue === "boolean") {
+        return rawValue;
+    }
+    throw new Error('"logo" must be true or false.');
+}
+function isMissingFileError(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+export function parseConfig(rawConfig) {
+    const parsed = parse(rawConfig);
+    const steps = parseSteps(parsed.steps);
+    const logo = parseLogo(parsed.logo);
+    const defaultsProfile = parseDefaultsProfile(parsed[DEFAULTS_PROFILE_SETTING_ID]);
+    const config = { steps };
+    if (logo !== undefined) {
+        config.logo = logo;
+    }
+    if (defaultsProfile !== undefined) {
+        config.defaultsProfile = defaultsProfile;
+    }
+    return config;
 }
 function isStepEnabledByDefault(profile, stepId) {
     if (profile === "conservative-v2") {
@@ -49,20 +102,26 @@ export async function configFileExists() {
 }
 export async function readConfig() {
     const configPath = await resolveConfigPath();
+    return readConfigFromPath(configPath);
+}
+export async function readConfigFromPath(configPath) {
     try {
         const raw = await readFile(configPath, "utf-8");
-        const parsed = parse(raw);
-        const parsedSteps = parsed.steps;
-        const defaultsProfile = parseDefaultsProfile(parsed[DEFAULTS_PROFILE_SETTING_ID]);
-        return { steps: parsedSteps ?? {}, logo: parsed.logo, defaultsProfile };
+        return parseConfig(raw);
     }
-    catch {
-        return structuredClone(EMPTY_CONFIG);
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return structuredClone(EMPTY_CONFIG);
+        }
+        throw new ConfigReadError(configPath, error);
     }
 }
 export async function writeConfig(config) {
     const configPath = await resolveConfigPath();
-    await mkdir(join(configPath, ".."), { recursive: true });
+    await writeConfigToPath(configPath, config);
+}
+export async function writeConfigToPath(configPath, config) {
+    await mkdir(dirname(configPath), { recursive: true });
     await writeFile(configPath, stringify(config), "utf-8");
 }
 export function isSettingEnabled(config, settingId) {

package/dist/index.js

@@ -1,179 +1,3 @@
 #!/usr/bin/env node
-import { Command } from "commander";
-import { createRequire } from "node:module";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-import { ALL_STEPS } from "./steps/catalog.js";
-import { applyUpdateCommandResult, 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 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"));
-const BRAEBURN_VERSION = packageJson.version;
-const program = new Command();
-program
-    .name("braeburn")
-    .description("macOS system updater")
-    .version(BRAEBURN_VERSION)
-    .helpCommand(false);
-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((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:
-  System / Runtimes (default: off — larger changes, enabled intentionally):
-  pyenv      Upgrade pyenv, install latest Python 3.x  (requires: pyenv or brew)
-  nvm        Install latest Node.js via nvm             (requires: ~/.nvm)
-
-  System / Apps & Packages:
-  homebrew   Update Homebrew itself and all installed formulae
-  mas        Upgrade Mac App Store apps  (requires: mas)
-  macos      Check for macOS updates, prompt to install
-
-  System / CLI Tools:
-  npm        Update global npm packages  (requires: npm)
-  braeburn   Update braeburn CLI itself  (requires: npm)
-  pip        Update global pip3 packages (requires: pip3) ⚠ may be fragile
-  dotnet     Update .NET global tools    (requires: dotnet)
-
-  System / Shell:
-  ohmyzsh    Update Oh My Zsh            (requires: ~/.oh-my-zsh)
-
-  System / Maintenance:
-  cleanup    homebrew cleanup (remove outdated Homebrew cache/downloads)
-
-Examples:
-  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 steps
-  `)
-    .action(async (stepArguments, options) => {
-    const autoYes = options.yes === true || options.force === true;
-    if (!(await configFileExists())) {
-        await runSetupCommand(ALL_STEPS);
-    }
-    const config = await readConfig();
-    let stepsToRun = stepArguments.length === 0
-        ? ALL_STEPS
-        : resolveStepsByIds(stepArguments);
-    if (stepArguments.length === 0) {
-        stepsToRun = stepsToRun.filter((step) => isStepEnabled(config, step.id));
-    }
-    const logoIsEnabled = options.logo !== false && isLogoEnabled(config);
-    const updateCommandResult = await runUpdateCommand({
-        steps: stepsToRun,
-        promptMode: autoYes ? "auto-accept" : "interactive",
-        logoVisibility: logoIsEnabled ? "visible" : "hidden",
-        version: BRAEBURN_VERSION,
-    });
-    applyUpdateCommandResult(updateCommandResult, process);
-});
-program
-    .command("log")
-    .description("View the most recent output log for a given step")
-    .argument("[step]", "Step ID to view logs for (e.g. homebrew, npm, pip)")
-    .option("--homebrew", "Show latest Homebrew log")
-    .option("--mas", "Show latest Mac App Store log")
-    .option("--ohmyzsh", "Show latest Oh My Zsh log")
-    .option("--npm", "Show latest npm log")
-    .option("--braeburn", "Show latest braeburn log")
-    .option("--pip", "Show latest pip3 log")
-    .option("--pyenv", "Show latest pyenv log")
-    .option("--nvm", "Show latest nvm log")
-    .option("--dotnet", "Show latest .NET log")
-    .option("--macos", "Show latest macOS update log")
-    .option("--cleanup", "Show latest homebrew cleanup log")
-    .addHelpText("after", `
-Examples:
-  braeburn log              List all available step logs
-  braeburn log homebrew     Show the latest Homebrew run log
-  braeburn log --brew       Same as above
-  braeburn log npm | less   Pipe log output through less
-  `)
-    .action((stepArgument, options) => {
-    const stepIdFromFlag = ALL_STEPS.map((step) => step.id).find((stepId) => options[stepId] === true);
-    const resolvedStepId = stepArgument ?? stepIdFromFlag;
-    if (!resolvedStepId) {
-        runLogListCommand();
-        return;
-    }
-    runLogCommand({ stepId: resolvedStepId });
-});
-const configCommand = program
-    .command("config")
-    .description("View or edit braeburn configuration")
-    .action(() => {
-    configCommand.outputHelp();
-});
-configCommand
-    .command("list")
-    .description("Print current configuration")
-    .action(async () => {
-    await runConfigCommand({
-        allSteps: ALL_STEPS,
-        outputMode: "non-interactive",
-    });
-});
-const configurableSteps = ALL_STEPS.filter((step) => !PROTECTED_STEP_IDS.has(step.id));
-const configUpdateCommand = configCommand
-    .command("update")
-    .description("Edit configuration (interactive by default, flags for direct updates)")
-    .addHelpText("after", `
-Examples:
-  braeburn config update                     Open interactive config editor
-  braeburn config update --no-logo           Hide the logo
-  braeburn config update --no-ohmyzsh        Disable Oh My Zsh updates
-  braeburn config update --no-pip --no-nvm   Disable pip and nvm updates
-  braeburn config update --ohmyzsh           Re-enable Oh My Zsh updates
-    `);
-configUpdateCommand.option(`--no-logo`, `Hide the logo`);
-configUpdateCommand.option(`--logo`, `Show the logo`);
-for (const step of configurableSteps) {
-    configUpdateCommand.option(`--no-${step.id}`, `Disable ${step.name} updates`);
-    configUpdateCommand.option(`--${step.id}`, `Enable ${step.name} updates`);
-}
-configUpdateCommand.action(async function () {
-    // 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") {
-            settingUpdates[step.id] = configUpdateCommand.opts()[step.id] ? "enable" : "disable";
-        }
-    }
-    const logoSource = configUpdateCommand.getOptionValueSource("logo");
-    if (logoSource === "cli") {
-        settingUpdates["logo"] = configUpdateCommand.opts().logo ? "enable" : "disable";
-    }
-    if (Object.keys(settingUpdates).length === 0) {
-        await runConfigCommand({
-            allSteps: ALL_STEPS,
-            outputMode: "interactive",
-        });
-        return;
-    }
-    await runConfigUpdateCommand({ settingUpdates, allSteps: ALL_STEPS });
-});
-function resolveStepsByIds(stepIds) {
-    const resolvedSteps = [];
-    for (const stepId of stepIds) {
-        const step = STEP_IDS_BY_NAME.get(stepId);
-        if (!step) {
-            process.stderr.write(`Unknown step: "${stepId}". Run braeburn --help to see available steps.\n`);
-            process.exit(1);
-        }
-        resolvedSteps.push(step);
-    }
-    return resolvedSteps;
-}
-program.parse();
+import { runBraeburnCli } from "./cli.js";
+await runBraeburnCli();

package/dist/runner.d.ts

@@ -10,11 +10,17 @@ type RunCommandOptions = {
     onOutputLine: OutputLineCallback;
     logWriter: StepLogWriter;
 };
+export type ShellCommandRunner = {
+    cancelActiveShellCommand: () => boolean;
+    runShellCommand: (options: RunCommandOptions) => Promise<void>;
+    runShellCommandAndCaptureOutput: (options: RunCommandOptions) => Promise<string>;
+};
 export declare class ShellCommandCanceledError extends Error {
     readonly shellCommand: string;
     readonly originalError: unknown;
     constructor(shellCommand: string, originalError: unknown);
 }
+export declare function createShellCommandRunner(): ShellCommandRunner;
 export declare function cancelActiveShellCommand(): boolean;
 export declare function runShellCommand(options: RunCommandOptions): Promise<void>;
 export declare function runShellCommandAndCaptureOutput(options: RunCommandOptions): Promise<string>;

package/dist/runner.js

@@ -1,7 +1,7 @@
 import { execa } from "execa";
 const FAILURE_OUTPUT_TAIL_LINE_LIMIT = 20;
-let activeShellCommandSubprocess;
-const userCanceledSubprocesses = new WeakSet();
+const DEFAULT_CAPTURE_MODE = "disabled";
+const MAX_BUFFERED_OUTPUT_LINE_LENGTH = 16_384;
 export class ShellCommandCanceledError extends Error {
     shellCommand;
     originalError;
@@ -12,21 +12,30 @@ export class ShellCommandCanceledError extends Error {
         this.originalError = originalError;
     }
 }
-export function cancelActiveShellCommand() {
-    if (!activeShellCommandSubprocess) {
+function createLimitedLineBuffer(lineLimit) {
+    const lines = [];
+    return {
+        add(line) {
+            lines.push(line);
+            if (lines.length > lineLimit) {
+                lines.shift();
+            }
+        },
+        lines() {
+            return [...lines];
+        },
+    };
+}
+function cancelActiveShellCommandForState(state) {
+    if (!state.activeShellCommandSubprocess) {
         return false;
     }
-    userCanceledSubprocesses.add(activeShellCommandSubprocess);
-    activeShellCommandSubprocess.kill("SIGTERM");
+    state.userCanceledSubprocesses.add(state.activeShellCommandSubprocess);
+    state.activeShellCommandSubprocess.kill("SIGTERM");
     return true;
 }
-function splitNonEmptyLines(text) {
-    if (!text) {
-        return [];
-    }
-    return text.split(/\r?\n|\r/).filter(Boolean);
-}
-function buildFailureSummaryLines(shellCommand, error) {
+function buildFailureSummaryLines(details) {
+    const { shellCommand, error, stdoutTailLines, stderrTailLines } = details;
     const defaultMessage = error instanceof Error ? error.message : String(error);
     if (typeof error !== "object" || error === null) {
         return [
@@ -48,12 +57,10 @@ function buildFailureSummaryLines(shellCommand, error) {
     else {
         summaryLines.push(`[braeburn] Error: ${defaultMessage}`);
     }
-    const stderrTailLines = splitNonEmptyLines(errorDetails.stderr).slice(-FAILURE_OUTPUT_TAIL_LINE_LIMIT);
     if (stderrTailLines.length > 0) {
         summaryLines.push(`[braeburn] stderr tail (${stderrTailLines.length}):`);
         summaryLines.push(...stderrTailLines.map((line) => `  ${line}`));
     }
-    const stdoutTailLines = splitNonEmptyLines(errorDetails.stdout).slice(-FAILURE_OUTPUT_TAIL_LINE_LIMIT);
     if (stdoutTailLines.length > 0) {
         summaryLines.push(`[braeburn] stdout tail (${stdoutTailLines.length}):`);
         summaryLines.push(...stdoutTailLines.map((line) => `  ${line}`));
@@ -73,6 +80,10 @@ function createBufferedLineEmitter(emitLine) {
                 }
                 emitLine(linePart);
             }
+            while (pendingText.length > MAX_BUFFERED_OUTPUT_LINE_LENGTH) {
+                emitLine(pendingText.slice(0, MAX_BUFFERED_OUTPUT_LINE_LENGTH));
+                pendingText = pendingText.slice(MAX_BUFFERED_OUTPUT_LINE_LENGTH);
+            }
         },
         flushPendingLine() {
             if (pendingText.length === 0) {
@@ -83,17 +94,46 @@ function createBufferedLineEmitter(emitLine) {
         },
     };
 }
-async function executeShellCommand(options) {
-    const capturedOutputLines = [];
+async function executeShellCommand(state, options, captureMode = DEFAULT_CAPTURE_MODE) {
+    const capturedOutputLines = captureMode === "enabled" ? [] : undefined;
+    const stdoutTailLines = createLimitedLineBuffer(FAILURE_OUTPUT_TAIL_LINE_LIMIT);
+    const stderrTailLines = createLimitedLineBuffer(FAILURE_OUTPUT_TAIL_LINE_LIMIT);
+    let logWriteQueue = Promise.resolve();
+    let logWriteFailure;
     const subprocess = execa("bash", ["-c", options.shellCommand], {
-        all: true,
+        buffer: false,
         reject: true,
     });
-    activeShellCommandSubprocess = subprocess;
+    state.activeShellCommandSubprocess = subprocess;
+    const queueLogWrite = (line) => {
+        logWriteQueue = logWriteQueue.then(async () => {
+            if (logWriteFailure) {
+                return;
+            }
+            try {
+                await options.logWriter(line);
+            }
+            catch (error) {
+                logWriteFailure = error;
+            }
+        });
+    };
+    const waitForQueuedLogWrites = async () => {
+        await logWriteQueue;
+        if (logWriteFailure) {
+            throw logWriteFailure;
+        }
+    };
     const emitOutputLine = (line) => {
-        capturedOutputLines.push(line.text);
+        if (line.source === "stdout") {
+            stdoutTailLines.add(line.text);
+        }
+        else {
+            stderrTailLines.add(line.text);
+        }
+        capturedOutputLines?.push(line.text);
         options.onOutputLine(line);
-        options.logWriter(line.text);
+        queueLogWrite(line.text);
     };
     const stdoutEmitter = createBufferedLineEmitter((line) => {
         emitOutputLine({ text: line, source: "stdout" });
@@ -111,36 +151,64 @@ async function executeShellCommand(options) {
         await subprocess;
         stdoutEmitter.flushPendingLine();
         stderrEmitter.flushPendingLine();
-        return { capturedOutput: capturedOutputLines.join("\n") };
+        await waitForQueuedLogWrites();
+        return { capturedOutput: capturedOutputLines?.join("\n") };
     }
     catch (error) {
         stdoutEmitter.flushPendingLine();
         stderrEmitter.flushPendingLine();
-        const commandWasCanceledByUser = userCanceledSubprocesses.has(subprocess);
-        const failureSummaryLines = buildFailureSummaryLines(options.shellCommand, error);
+        const commandWasCanceledByUser = state.userCanceledSubprocesses.has(subprocess);
+        const failureSummaryLines = buildFailureSummaryLines({
+            shellCommand: options.shellCommand,
+            error,
+            stdoutTailLines: stdoutTailLines.lines(),
+            stderrTailLines: stderrTailLines.lines(),
+        });
         if (commandWasCanceledByUser) {
             failureSummaryLines.push("[braeburn] Command canceled by user input (q).");
         }
         for (const line of failureSummaryLines) {
-            await options.logWriter(line);
+            queueLogWrite(line);
         }
+        await waitForQueuedLogWrites();
         if (commandWasCanceledByUser) {
             throw new ShellCommandCanceledError(options.shellCommand, error);
         }
         throw error;
     }
     finally {
-        if (activeShellCommandSubprocess === subprocess) {
-            activeShellCommandSubprocess = undefined;
+        if (state.activeShellCommandSubprocess === subprocess) {
+            state.activeShellCommandSubprocess = undefined;
         }
     }
 }
+export function createShellCommandRunner() {
+    const state = {
+        activeShellCommandSubprocess: undefined,
+        userCanceledSubprocesses: new WeakSet(),
+    };
+    return {
+        cancelActiveShellCommand() {
+            return cancelActiveShellCommandForState(state);
+        },
+        async runShellCommand(options) {
+            await executeShellCommand(state, options);
+        },
+        async runShellCommandAndCaptureOutput(options) {
+            const result = await executeShellCommand(state, options, "enabled");
+            return result.capturedOutput ?? "";
+        },
+    };
+}
+const defaultShellCommandRunner = createShellCommandRunner();
+export function cancelActiveShellCommand() {
+    return defaultShellCommandRunner.cancelActiveShellCommand();
+}
 export async function runShellCommand(options) {
-    await executeShellCommand(options);
+    await defaultShellCommandRunner.runShellCommand(options);
 }
 export async function runShellCommandAndCaptureOutput(options) {
-    const result = await executeShellCommand(options);
-    return result.capturedOutput;
+    return defaultShellCommandRunner.runShellCommandAndCaptureOutput(options);
 }
 export async function doesShellCommandSucceed(options) {
     const result = await execa("bash", ["-c", options.shellCommand], {

package/dist/update/engine.d.ts

@@ -9,6 +9,7 @@ type UpdateEngineDependencies = {
     runCommand: typeof runShellCommand;
     createStepRunContext: typeof createDefaultStepRunContext;
 };
+export declare const CURRENT_OUTPUT_LINE_LIMIT = 200;
 type RunUpdateEngineOptions = {
     steps: Step[];
     promptMode: PromptMode;

package/dist/update/engine.js

@@ -3,6 +3,7 @@ import { runShellCommand, ShellCommandCanceledError, } from "../runner.js";
 import { createDefaultStepRunContext } from "../steps/index.js";
 import { toDisplaySteps } from "./displayStep.js";
 import { createInitialUpdateState, } from "./state.js";
+export const CURRENT_OUTPUT_LINE_LIMIT = 200;
 function resolveDependencies(dependencyOverrides) {
     return {
         createLogWriter: dependencyOverrides?.createLogWriter ?? createLogWriterForStep,
@@ -26,6 +27,12 @@ async function resolvePrompt(promptMode, askForConfirmation) {
 function reportState(state, onStateChanged) {
     onStateChanged(state);
 }
+function appendCurrentOutputLine(state, line) {
+    state.currentOutputLines.push(line);
+    if (state.currentOutputLines.length > CURRENT_OUTPUT_LINE_LIMIT) {
+        state.currentOutputLines.splice(0, state.currentOutputLines.length - CURRENT_OUTPUT_LINE_LIMIT);
+    }
+}
 function wasStepCanceledByUser(error) {
     return error instanceof ShellCommandCanceledError;
 }
@@ -90,7 +97,7 @@ export async function runUpdateEngine(options) {
                 await dependencies.runCommand({
                     shellCommand: `brew install ${step.brewPackageToInstall}`,
                     onOutputLine: (line) => {
-                        state.currentOutputLines.push(line);
+                        appendCurrentOutputLine(state, line);
                         reportState(state, options.onStateChanged);
                     },
                     logWriter: installLogWriter,
@@ -130,7 +137,7 @@ export async function runUpdateEngine(options) {
         const stepLogWriter = await dependencies.createLogWriter(step.id);
         try {
             await step.run(dependencies.createStepRunContext((line) => {
-                state.currentOutputLines.push(line);
+                appendCurrentOutputLine(state, line);
                 reportState(state, options.onStateChanged);
             }, stepLogWriter));
             state.currentPhase = "complete";

package/package.json

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