braeburn 1.4.2 → 1.5.0

package/README.md

@@ -32,20 +32,20 @@ braeburn homebrew npm # run specific steps only
 
 ## Steps
 
-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.
+Steps are grouped by system capability. For new setups, braeburn uses a conservative default profile: only package-manager-driven CLI/tooling updates are enabled by default.
 
-| Step | Stage | Default | Requires |
+| Step | Category | Default (new setup) | 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` |
+| `pyenv` | Runtimes | off | `pyenv` or Homebrew |
+| `nvm` | Runtimes | off | `~/.nvm` |
+| `homebrew` | Apps & Packages | on | `brew` (required) |
+| `mas` | Apps & Packages | off | `mas` |
+| `macos` | Apps & Packages | off | — |
+| `npm` | CLI Tools | on | `npm` |
+| `pip` | CLI Tools | on | `pip3` |
+| `dotnet` | CLI Tools | on | `dotnet` |
+| `ohmyzsh` | Shell | off | `~/.oh-my-zsh` |
+| `cleanup` (`homebrew cleanup`) | Maintenance | off | `brew` |
 
 ## Requirements
 

package/dist/commands/config.d.ts

@@ -1,5 +1,5 @@
 import { type BraeburnConfig } from "../config.js";
-import type { Step } from "../steps/index.js";
+import { type Step } from "../steps/index.js";
 type RunConfigCommandOptions = {
     allSteps: Step[];
     outputMode: "interactive" | "non-interactive";

package/dist/commands/config.js

@@ -1,6 +1,7 @@
 import readline from "node:readline";
 import chalk from "chalk";
-import { readConfig, writeConfig, resolveConfigPath, isSettingEnabled, isStepEnabled, isLogoEnabled, applySettingToConfig, PROTECTED_STEP_IDS, DEFAULT_OFF_STEP_IDS, } from "../config.js";
+import { readConfig, writeConfig, resolveConfigPath, isSettingEnabled, isStepEnabled, isLogoEnabled, applySettingToConfig, cleanConfigForWrite, PROTECTED_STEP_IDS, } from "../config.js";
+import { buildCategorySectionsInOrder, getStepCategoryLabel, } from "../steps/index.js";
 import { createScreenRenderer } from "../ui/screen.js";
 import { hideCursorDuringExecution } from "../ui/terminal.js";
 export async function runConfigCommand(options) {
@@ -50,7 +51,7 @@ export async function runConfigUpdateCommand(options) {
     }
     const config = await readConfig();
     const { updatedConfig, changes } = applyConfigUpdates(config, settingUpdates);
-    await writeCleanConfig(updatedConfig);
+    await writeConfig(cleanConfigForWrite(updatedConfig));
     if (changes.length === 0) {
         process.stdout.write("No changes — already set as requested.\n");
         return;
@@ -66,52 +67,61 @@ export async function runConfigUpdateCommand(options) {
 export function buildConfigTableOutput(options) {
     const { config, configPath, allSteps } = options;
     const lines = [];
-    const stepColumnWidth = 12;
-    const divider = "─".repeat(stepColumnWidth + 16);
+    const settingColumnWidth = 24;
     lines.push(`Config: ${chalk.dim(configPath)}`);
     lines.push("");
-    lines.push(`${"Step".padEnd(stepColumnWidth)}Status`);
-    lines.push(divider);
-    const logoEnabled = isLogoEnabled(config);
-    lines.push(`${"logo".padEnd(stepColumnWidth)}${logoEnabled ? chalk.green("enabled") : chalk.red("disabled")}`);
-    lines.push(divider);
-    for (const step of allSteps) {
-        const isProtected = PROTECTED_STEP_IDS.has(step.id);
-        const enabled = isStepEnabled(config, step.id);
-        let statusText;
-        if (isProtected) {
-            statusText = chalk.dim("always enabled");
-        }
-        else if (enabled) {
-            statusText = chalk.green("enabled");
-        }
-        else {
-            statusText = chalk.red("disabled");
+    lines.push(chalk.bold("System"));
+    lines.push(`${"Setting".padEnd(settingColumnWidth)}Status`);
+    lines.push("─".repeat(settingColumnWidth + 16));
+    for (const section of buildCategorySectionsInOrder(allSteps)) {
+        lines.push(chalk.dim(`  ${getStepCategoryLabel(section.categoryId)}`));
+        for (const step of section.items) {
+            const isProtected = PROTECTED_STEP_IDS.has(step.id);
+            const enabled = isStepEnabled(config, step.id);
+            let statusText;
+            if (isProtected) {
+                statusText = chalk.dim("always enabled");
+            }
+            else if (enabled) {
+                statusText = chalk.green("enabled");
+            }
+            else {
+                statusText = chalk.red("disabled");
+            }
+            lines.push(`${step.name.padEnd(settingColumnWidth)}${statusText}`);
         }
-        lines.push(`${step.id.padEnd(stepColumnWidth)}${statusText}`);
+        lines.push("");
     }
+    lines.push(chalk.bold("Interface"));
+    lines.push(`${"Setting".padEnd(settingColumnWidth)}Status`);
+    lines.push("─".repeat(settingColumnWidth + 16));
+    const logoEnabled = isLogoEnabled(config);
+    lines.push(`${"logo".padEnd(settingColumnWidth)}${logoEnabled ? chalk.green("enabled") : chalk.red("disabled")}`);
     lines.push("");
     return lines.join("\n") + "\n";
 }
 function buildConfigViewItems(config, allSteps) {
-    const viewItems = [
-        {
-            id: "logo",
-            label: "logo",
-            description: "Show the braeburn logo in command output",
-            protection: "configurable",
-            selection: isLogoEnabled(config) ? "enabled" : "disabled",
-        },
-    ];
-    for (const step of allSteps) {
-        viewItems.push({
-            id: step.id,
-            label: step.id,
-            description: step.description,
-            protection: PROTECTED_STEP_IDS.has(step.id) ? "protected" : "configurable",
-            selection: isStepEnabled(config, step.id) ? "enabled" : "disabled",
-        });
+    const viewItems = [];
+    for (const section of buildCategorySectionsInOrder(allSteps)) {
+        for (const step of section.items) {
+            viewItems.push({
+                id: step.id,
+                label: step.name,
+                description: step.description,
+                sectionLabel: `System / ${getStepCategoryLabel(step.categoryId)}`,
+                protection: PROTECTED_STEP_IDS.has(step.id) ? "protected" : "configurable",
+                selection: isStepEnabled(config, step.id) ? "enabled" : "disabled",
+            });
+        }
     }
+    viewItems.push({
+        id: "logo",
+        label: "logo",
+        description: "Show the braeburn logo in command output",
+        sectionLabel: "Interface",
+        protection: "configurable",
+        selection: isLogoEnabled(config) ? "enabled" : "disabled",
+    });
     return viewItems;
 }
 function buildInteractiveConfigScreen(options) {
@@ -124,9 +134,13 @@ function buildInteractiveConfigScreen(options) {
     for (let itemIndex = 0; itemIndex < items.length; itemIndex++) {
         const item = items[itemIndex];
         const isCursor = itemIndex === cursorIndex;
+        const previousItem = items[itemIndex - 1];
+        if (!previousItem || previousItem.sectionLabel !== item.sectionLabel) {
+            lines.push(`  ${chalk.dim(`── ${item.sectionLabel} ──────────────────────────────────────────────`)}`);
+        }
         const cursor = isCursor ? chalk.cyan("›") : " ";
         const marker = item.selection === "enabled" ? chalk.green("●") : chalk.dim("○");
-        const label = isCursor ? chalk.bold.white(item.label.padEnd(12)) : chalk.white(item.label.padEnd(12));
+        const label = isCursor ? chalk.bold.white(item.label.padEnd(24)) : chalk.white(item.label.padEnd(24));
         let status;
         if (item.protection === "protected") {
             status = chalk.dim("always enabled");
@@ -170,7 +184,7 @@ async function runInteractiveConfigView(options) {
                 process.stdin.pause();
                 resolve(result);
             };
-            const onKeypress = (_char, key) => {
+            const onKeypress = (_typedCharacter, key) => {
                 if (key.ctrl && key.name === "c") {
                     process.exit(130);
                 }
@@ -219,7 +233,7 @@ async function runInteractiveConfigView(options) {
                 completionOutput = "No changes — already set as requested.\n";
             }
             else {
-                await writeCleanConfig(updatedConfig);
+                await writeConfig(cleanConfigForWrite(updatedConfig));
                 const outputLines = [];
                 for (const { label, from, to } of changes) {
                     const fromLabel = from === "enable" ? chalk.green("enabled") : chalk.red("disabled");
@@ -237,18 +251,3 @@ async function runInteractiveConfigView(options) {
     }
     process.stdout.write(completionOutput);
 }
-async function writeCleanConfig(config) {
-    const cleaned = { steps: {} };
-    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;
-    }
-    await writeConfig(cleaned);
-}

package/dist/commands/setup.d.ts

@@ -1,5 +1,4 @@
-import type { Step } from "../steps/index.js";
-import type { StepStage } from "../update/state.js";
+import { type Step, type StepCategoryId } from "../steps/index.js";
 export type SelectionState = "selected" | "deselected";
 export type ProtectionStatus = "protected" | "configurable";
 export type AvailabilityStatus = "available" | "unavailable";
@@ -7,7 +6,7 @@ export type SetupStepView = {
     id: string;
     name: string;
     description: string;
-    stage: StepStage;
+    categoryId: StepCategoryId;
     brewPackageToInstall?: string;
 };
 export type SelectableStep = {

package/dist/commands/setup.js

@@ -1,9 +1,10 @@
 import readline from "node:readline";
 import chalk from "chalk";
-import { writeConfig, PROTECTED_STEP_IDS } from "../config.js";
+import { writeConfig, PROTECTED_STEP_IDS, CONSERVATIVE_DEFAULT_ON_STEP_IDS, cleanConfigForWrite, } from "../config.js";
 import { LOGO_ART } from "../logo.js";
 import { createScreenRenderer } from "../ui/screen.js";
 import { hideCursorDuringExecution } from "../ui/terminal.js";
+import { getStepCategoryLabel, } from "../steps/index.js";
 export function buildLoadingScreen() {
     const lines = [
         chalk.yellow(LOGO_ART),
@@ -27,21 +28,13 @@ export function buildSetupScreen(items, cursorIndex) {
         `  ${chalk.dim("\u2191\u2193  navigate    Space  toggle    Return  confirm")}`,
         "",
     ];
-    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 previousItem = items[itemIndex - 1];
+        if (!previousItem || previousItem.step.categoryId !== item.step.categoryId) {
+            const categoryLabel = getStepCategoryLabel(item.step.categoryId);
+            lines.push(`  ${chalk.dim(`── System / ${categoryLabel} ──────────────────────────────────────────`)}`);
         }
         const cursor = isCursor ? chalk.cyan("\u203a") : " ";
         const checkbox = item.selection === "selected" ? chalk.green("\u25cf") : chalk.dim("\u25cb");
@@ -82,10 +75,12 @@ export async function runSetupCommand(allSteps) {
                 id: step.id,
                 name: step.name,
                 description: step.description,
-                stage: step.stage,
+                categoryId: step.categoryId,
                 brewPackageToInstall: step.brewPackageToInstall,
             },
-            selection: PROTECTED_STEP_IDS.has(step.id) || step.stage === "tools" ? "selected" : "deselected",
+            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",
         }));
@@ -95,7 +90,7 @@ export async function runSetupCommand(allSteps) {
             readline.emitKeypressEvents(process.stdin);
             if (process.stdin.isTTY)
                 process.stdin.setRawMode(true);
-            const handleKeypress = (_char, key) => {
+            const handleKeypress = (_typedCharacter, key) => {
                 if (key?.ctrl && key?.name === "c") {
                     process.exit(130);
                 }
@@ -125,13 +120,17 @@ export async function runSetupCommand(allSteps) {
             process.stdin.on("keypress", handleKeypress);
             process.stdin.resume();
         });
-        const stepsConfig = {};
+        const draftConfig = {
+            defaultsProfile: "conservative-v2",
+            steps: {},
+        };
         for (const item of items) {
-            if (item.protection === "configurable" && item.selection === "deselected") {
-                stepsConfig[item.step.id] = false;
+            if (item.protection === "protected") {
+                continue;
             }
+            draftConfig.steps[item.step.id] = item.selection === "selected";
         }
-        await writeConfig({ steps: stepsConfig });
+        await writeConfig(cleanConfigForWrite(draftConfig));
         const confirmationLines = [
             chalk.yellow(LOGO_ART),
             "",

package/dist/commands/update.js

@@ -1,12 +1,27 @@
 import { collectVersions } from "../update/versionCollector.js";
 import { captureYesNo } from "../ui/prompt.js";
-import { buildScreen, createScreenRenderer } from "../ui/screen.js";
+import { buildScreen, buildScreenWithAnimationFrame, createScreenRenderer } from "../ui/screen.js";
 import { hideCursorDuringExecution } from "../ui/terminal.js";
 import { runUpdateEngine } from "../update/engine.js";
 export async function runUpdateCommand(options) {
     const renderScreen = createScreenRenderer();
     const restoreCursor = hideCursorDuringExecution({ screenBuffer: "alternate" });
     let finalScreen = "";
+    let latestState = undefined;
+    let animationFrameIndex = 0;
+    const animationTimer = setInterval(() => {
+        if (!latestState) {
+            return;
+        }
+        if (latestState.runCompletion === "finished") {
+            return;
+        }
+        if (latestState.currentPhase !== "running" && latestState.currentPhase !== "installing") {
+            return;
+        }
+        animationFrameIndex += 1;
+        renderScreen(buildScreenWithAnimationFrame(latestState, animationFrameIndex));
+    }, 100);
     try {
         const finalState = await runUpdateEngine({
             steps: options.steps,
@@ -16,12 +31,14 @@ export async function runUpdateCommand(options) {
             askForConfirmation: captureYesNo,
             collectVersions,
             onStateChanged: (state) => {
-                renderScreen(buildScreen(state));
+                latestState = state;
+                renderScreen(buildScreenWithAnimationFrame(state, animationFrameIndex));
             },
         });
         finalScreen = buildScreen(finalState);
     }
     finally {
+        clearInterval(animationTimer);
         restoreCursor();
     }
     if (finalScreen) {

package/dist/config.d.ts

@@ -1,8 +1,11 @@
 export declare const PROTECTED_STEP_IDS: Set<string>;
-export declare const DEFAULT_OFF_STEP_IDS: Set<string>;
+export type ConfigDefaultsProfile = "legacy" | "conservative-v2";
+export declare const LEGACY_DEFAULT_OFF_STEP_IDS: Set<string>;
+export declare const CONSERVATIVE_DEFAULT_ON_STEP_IDS: Set<string>;
 export type BraeburnConfig = {
     steps: Record<string, boolean>;
     logo?: boolean;
+    defaultsProfile?: ConfigDefaultsProfile;
 };
 export declare function resolveConfigPath(): Promise<string>;
 export declare function configFileExists(): Promise<boolean>;
@@ -12,3 +15,4 @@ export declare function isSettingEnabled(config: BraeburnConfig, settingId: stri
 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;
+export declare function cleanConfigForWrite(config: BraeburnConfig): BraeburnConfig;

package/dist/config.js

@@ -3,9 +3,30 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { parse, stringify } from "smol-toml";
 export const PROTECTED_STEP_IDS = new Set(["homebrew"]);
-export const DEFAULT_OFF_STEP_IDS = new Set(["nvm", "pyenv"]);
+export const LEGACY_DEFAULT_OFF_STEP_IDS = new Set(["nvm", "pyenv"]);
+export const CONSERVATIVE_DEFAULT_ON_STEP_IDS = new Set(["homebrew", "npm", "pip", "dotnet"]);
 const EMPTY_CONFIG = { steps: {} };
 const LOGO_SETTING_ID = "logo";
+const DEFAULTS_PROFILE_SETTING_ID = "defaultsProfile";
+const LEGACY_PROFILE = "legacy";
+function resolveDefaultsProfile(config) {
+    return config.defaultsProfile ?? LEGACY_PROFILE;
+}
+function parseDefaultsProfile(rawValue) {
+    if (rawValue === "legacy" || rawValue === "conservative-v2") {
+        return rawValue;
+    }
+    return undefined;
+}
+function isStepEnabledByDefault(profile, stepId) {
+    if (profile === "conservative-v2") {
+        return CONSERVATIVE_DEFAULT_ON_STEP_IDS.has(stepId);
+    }
+    return !LEGACY_DEFAULT_OFF_STEP_IDS.has(stepId);
+}
+function shouldPersistStepOverride(profile, stepId, desiredState) {
+    return isStepEnabledByDefault(profile, stepId) !== (desiredState === "enable");
+}
 async function pathExists(targetPath) {
     try {
         await access(targetPath);
@@ -31,7 +52,9 @@ export async function readConfig() {
     try {
         const raw = await readFile(configPath, "utf-8");
         const parsed = parse(raw);
-        return { steps: parsed.steps ?? {}, logo: parsed.logo };
+        const parsedSteps = parsed.steps;
+        const defaultsProfile = parseDefaultsProfile(parsed[DEFAULTS_PROFILE_SETTING_ID]);
+        return { steps: parsedSteps ?? {}, logo: parsed.logo, defaultsProfile };
     }
     catch {
         return structuredClone(EMPTY_CONFIG);
@@ -47,9 +70,12 @@ export function isSettingEnabled(config, settingId) {
         return true;
     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;
+    const defaultsProfile = resolveDefaultsProfile(config);
+    const explicitStepOverride = config.steps[settingId];
+    if (explicitStepOverride === undefined) {
+        return isStepEnabledByDefault(defaultsProfile, settingId);
+    }
+    return explicitStepOverride === true;
 }
 export function isStepEnabled(config, stepId) {
     return isSettingEnabled(config, stepId);
@@ -68,20 +94,33 @@ export function applySettingToConfig(config, settingId, desiredState) {
         }
         return updatedConfig;
     }
-    if (DEFAULT_OFF_STEP_IDS.has(settingId)) {
-        if (desiredState === "enable") {
-            updatedConfig.steps[settingId] = true;
+    const defaultsProfile = resolveDefaultsProfile(updatedConfig);
+    const shouldPersistOverride = shouldPersistStepOverride(defaultsProfile, settingId, desiredState);
+    if (!shouldPersistOverride) {
+        delete updatedConfig.steps[settingId];
+        return updatedConfig;
+    }
+    updatedConfig.steps[settingId] = desiredState === "enable";
+    return updatedConfig;
+}
+export function cleanConfigForWrite(config) {
+    const defaultsProfile = resolveDefaultsProfile(config);
+    const cleaned = { steps: {} };
+    for (const [stepId, explicitState] of Object.entries(config.steps)) {
+        if (PROTECTED_STEP_IDS.has(stepId)) {
+            continue;
         }
-        else {
-            delete updatedConfig.steps[settingId];
+        const desiredState = explicitState === true ? "enable" : "disable";
+        if (!shouldPersistStepOverride(defaultsProfile, stepId, desiredState)) {
+            continue;
         }
-        return updatedConfig;
+        cleaned.steps[stepId] = explicitState;
     }
-    if (desiredState === "enable") {
-        delete updatedConfig.steps[settingId];
+    if (config.logo === false) {
+        cleaned.logo = false;
     }
-    else {
-        updatedConfig.steps[settingId] = false;
+    if (config.defaultsProfile && config.defaultsProfile !== LEGACY_PROFILE) {
+        cleaned.defaultsProfile = config.defaultsProfile;
     }
-    return updatedConfig;
+    return cleaned;
 }

package/dist/index.js

@@ -28,19 +28,25 @@ program
     .option("--no-logo", "Hide the logo")
     .addHelpText("after", `
 Step descriptions:
-  Runtime stage (default: off — update the version managers and runtimes themselves):
+  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)
 
-  Tools stage (default: on — update packages installed via the managers above):
+  System / Apps & Packages:
   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)
+  macos      Check for macOS updates, prompt to install
+
+  System / CLI Tools:
   npm        Update global npm packages  (requires: npm)
   pip        Update global pip3 packages (requires: pip3) ⚠ may be fragile
   dotnet     Update .NET global tools    (requires: dotnet)
-  macos      Check for macOS updates, prompt to install
-  cleanup    Clean up Homebrew cache and old downloads
+
+  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
@@ -48,7 +54,7 @@ Examples:
   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
+  braeburn nvm pyenv        Run only the runtime steps
   `)
     .action(async (stepArguments, options) => {
     const autoYes = options.yes === true || options.force === true;
@@ -83,7 +89,7 @@ program
     .option("--nvm", "Show latest nvm log")
     .option("--dotnet", "Show latest .NET log")
     .option("--macos", "Show latest macOS update log")
-    .option("--cleanup", "Show latest cleanup log")
+    .option("--cleanup", "Show latest homebrew cleanup log")
     .addHelpText("after", `
 Examples:
   braeburn log              List all available step logs

package/dist/steps/catalog.js

@@ -1,13 +1,26 @@
 import { pyenvStep, nvmStep, homebrewStep, masStep, ohmyzshStep, npmStep, pipStep, dotnetStep, macosStep, cleanupStep, } from "./index.js";
-export const ALL_STEPS = [
-    pyenvStep,
-    nvmStep,
-    homebrewStep,
-    masStep,
-    ohmyzshStep,
-    npmStep,
-    pipStep,
-    dotnetStep,
-    macosStep,
-    cleanupStep,
+const STEP_BY_ID = {
+    pyenv: pyenvStep,
+    nvm: nvmStep,
+    homebrew: homebrewStep,
+    mas: masStep,
+    macos: macosStep,
+    npm: npmStep,
+    pip: pipStep,
+    dotnet: dotnetStep,
+    ohmyzsh: ohmyzshStep,
+    cleanup: cleanupStep,
+};
+const STEP_EXECUTION_ORDER = [
+    "pyenv",
+    "nvm",
+    "homebrew",
+    "mas",
+    "macos",
+    "npm",
+    "pip",
+    "dotnet",
+    "ohmyzsh",
+    "cleanup",
 ];
+export const ALL_STEPS = STEP_EXECUTION_ORDER.map((stepId) => STEP_BY_ID[stepId]);

package/dist/steps/categories.d.ts

@@ -0,0 +1,7 @@
+export type StepCategoryId = "apps-packages" | "cli-tools" | "runtimes" | "shell" | "maintenance";
+export type StepCategoryDefinition = {
+    id: StepCategoryId;
+    label: string;
+};
+export declare function listStepCategoryDefinitions(): StepCategoryDefinition[];
+export declare function getStepCategoryLabel(categoryId: StepCategoryId): string;

package/dist/steps/categories.js

@@ -0,0 +1,18 @@
+const STEP_CATEGORY_DEFINITIONS = [
+    { id: "runtimes", label: "Runtimes" },
+    { id: "apps-packages", label: "Apps & Packages" },
+    { id: "cli-tools", label: "CLI Tools" },
+    { id: "shell", label: "Shell" },
+    { id: "maintenance", label: "Maintenance" },
+];
+const STEP_CATEGORY_DEFINITION_BY_ID = new Map(STEP_CATEGORY_DEFINITIONS.map((categoryDefinition) => [categoryDefinition.id, categoryDefinition]));
+export function listStepCategoryDefinitions() {
+    return [...STEP_CATEGORY_DEFINITIONS];
+}
+export function getStepCategoryLabel(categoryId) {
+    const categoryDefinition = STEP_CATEGORY_DEFINITION_BY_ID.get(categoryId);
+    if (!categoryDefinition) {
+        return categoryId;
+    }
+    return categoryDefinition.label;
+}

package/dist/steps/cleanup.js

@@ -1,8 +1,8 @@
 import { checkCommandExists } from "./runtime.js";
 const cleanupStep = {
     id: "cleanup",
-    name: "Cleanup",
-    stage: "tools",
+    name: "homebrew cleanup",
+    categoryId: "maintenance",
     description: "Remove outdated Homebrew downloads and cached versions",
     async checkIsAvailable() {
         return checkCommandExists("brew");

package/dist/steps/dotnet.js

@@ -2,7 +2,7 @@ import { checkCommandExists } from "./runtime.js";
 const dotnetStep = {
     id: "dotnet",
     name: ".NET",
-    stage: "tools",
+    categoryId: "cli-tools",
     description: "Update all globally installed .NET tools",
     async checkIsAvailable() {
         return checkCommandExists("dotnet");

package/dist/steps/grouping.d.ts

@@ -0,0 +1,10 @@
+import type { StepCategoryId } from "./categories.js";
+type CategorizedItem = {
+    categoryId: StepCategoryId;
+};
+export type CategorySection<TItem> = {
+    categoryId: StepCategoryId;
+    items: TItem[];
+};
+export declare function buildCategorySectionsInOrder<TItem extends CategorizedItem>(orderedItems: TItem[]): CategorySection<TItem>[];
+export {};

package/dist/steps/grouping.js

@@ -0,0 +1,15 @@
+export function buildCategorySectionsInOrder(orderedItems) {
+    const sections = [];
+    for (const item of orderedItems) {
+        const lastSection = sections[sections.length - 1];
+        if (!lastSection || lastSection.categoryId !== item.categoryId) {
+            sections.push({
+                categoryId: item.categoryId,
+                items: [item],
+            });
+            continue;
+        }
+        lastSection.items.push(item);
+    }
+    return sections;
+}

package/dist/steps/homebrew.js

@@ -2,7 +2,7 @@ import { checkCommandExists } from "./runtime.js";
 const homebrewStep = {
     id: "homebrew",
     name: "Homebrew",
-    stage: "tools",
+    categoryId: "apps-packages",
     description: "Update Homebrew itself and upgrade all installed formulae",
     async checkIsAvailable() {
         return checkCommandExists("brew");

package/dist/steps/index.d.ts

@@ -1,4 +1,8 @@
-export type { StepRunContext, StepStage, Step, } from "./types.js";
+export type { StepRunContext, Step, } from "./types.js";
+export type { StepCategoryId, StepCategoryDefinition, } from "./categories.js";
+export { listStepCategoryDefinitions, getStepCategoryLabel, } from "./categories.js";
+export type { CategorySection, } from "./grouping.js";
+export { buildCategorySectionsInOrder, } from "./grouping.js";
 export { checkCommandExists, checkPathExists, runStep, createDefaultStepRunContext, } from "./runtime.js";
 export { default as homebrewStep } from "./homebrew.js";
 export { default as masStep } from "./mas.js";

package/dist/steps/index.js

@@ -1,3 +1,5 @@
+export { listStepCategoryDefinitions, getStepCategoryLabel, } from "./categories.js";
+export { buildCategorySectionsInOrder, } from "./grouping.js";
 export { checkCommandExists, checkPathExists, runStep, createDefaultStepRunContext, } from "./runtime.js";
 export { default as homebrewStep } from "./homebrew.js";
 export { default as masStep } from "./mas.js";

package/dist/steps/macos.js

@@ -1,7 +1,7 @@
 const macosStep = {
     id: "macos",
     name: "macOS",
-    stage: "tools",
+    categoryId: "apps-packages",
     description: "Check for and optionally install macOS system software updates",
     async checkIsAvailable() {
         return true;

package/dist/steps/mas.js

@@ -2,7 +2,7 @@ import { checkCommandExists } from "./runtime.js";
 const masStep = {
     id: "mas",
     name: "Mac App Store",
-    stage: "tools",
+    categoryId: "apps-packages",
     description: "Upgrade all Mac App Store apps via the mas CLI tool",
     brewPackageToInstall: "mas",
     async checkIsAvailable() {

package/dist/steps/npm.js

@@ -2,7 +2,7 @@ import { checkCommandExists } from "./runtime.js";
 const npmStep = {
     id: "npm",
     name: "npm",
-    stage: "tools",
+    categoryId: "cli-tools",
     description: "Update all globally installed npm packages",
     async checkIsAvailable() {
         return checkCommandExists("npm");

package/dist/steps/nvm.js

@@ -16,7 +16,7 @@ const NVM_INSTALL_COMMAND = `${NVM_SOURCE_PREFIX} && ` +
 const nvmStep = {
     id: "nvm",
     name: "Node.js (nvm)",
-    stage: "runtime",
+    categoryId: "runtimes",
     description: "Install the latest Node.js via nvm, migrating packages from the current version",
     async checkIsAvailable() {
         return checkPathExists(NVM_SCRIPT_PATH);

package/dist/steps/ohmyzsh.js

@@ -5,7 +5,7 @@ const OH_MY_ZSH_UPGRADE_SCRIPT_PATH = join(homedir(), ".oh-my-zsh", "tools", "up
 const ohmyzshStep = {
     id: "ohmyzsh",
     name: "Oh My Zsh",
-    stage: "tools",
+    categoryId: "shell",
     description: "Update Oh My Zsh to the latest version",
     async checkIsAvailable() {
         return checkPathExists(OH_MY_ZSH_UPGRADE_SCRIPT_PATH);

package/dist/steps/pip.js

@@ -3,7 +3,7 @@ const PIP_UPDATE_ALL_OUTDATED_SHELL_COMMAND = "pip3 list --outdated --format=col
 const pipStep = {
     id: "pip",
     name: "pip3",
-    stage: "tools",
+    categoryId: "cli-tools",
     description: "Update all globally installed pip3 packages",
     warning: "This updates all global pip3 packages, which can occasionally break tools.",
     async checkIsAvailable() {

package/dist/steps/pyenv.js

@@ -3,7 +3,7 @@ const FIND_LATEST_STABLE_PYTHON_SHELL_COMMAND = "pyenv install -l | grep -E '^\\
 const pyenvStep = {
     id: "pyenv",
     name: "pyenv",
-    stage: "runtime",
+    categoryId: "runtimes",
     description: "Upgrade pyenv via Homebrew and install the latest Python 3.x",
     brewPackageToInstall: "pyenv",
     async checkIsAvailable() {

package/dist/steps/types.d.ts

@@ -1,5 +1,6 @@
 import type { OutputLineCallback } from "../runner.js";
 import type { StepLogWriter } from "../logger.js";
+import type { StepCategoryId } from "./categories.js";
 export type StepRunContext = {
     onOutputLine: OutputLineCallback;
     logWriter: StepLogWriter;
@@ -8,12 +9,11 @@ export type StepRunContext = {
         shellCommand: string;
     }) => Promise<string>;
 };
-export type StepStage = "runtime" | "tools";
 export type Step = {
     id: string;
     name: string;
     description: string;
-    stage: StepStage;
+    categoryId: StepCategoryId;
     warning?: string;
     brewPackageToInstall?: string;
     checkIsAvailable: () => Promise<boolean>;

package/dist/ui/activityIndicator.d.ts

@@ -0,0 +1 @@
+export declare function getActivityIndicatorFrame(frameIndex: number): string;

package/dist/ui/activityIndicator.js

@@ -0,0 +1,5 @@
+const ACTIVITY_FRAMES = ["◐", "◓", "◑", "◒"];
+export function getActivityIndicatorFrame(frameIndex) {
+    const normalizedFrameIndex = Math.abs(Math.trunc(frameIndex));
+    return ACTIVITY_FRAMES[normalizedFrameIndex % ACTIVITY_FRAMES.length];
+}

package/dist/ui/currentStep.d.ts

@@ -4,6 +4,7 @@ type ActiveStepOptions = {
     stepNumber: number;
     totalSteps: number;
     phase: StepPhase;
+    activityFrameIndex?: number;
 };
 export declare function buildActiveStepLines(options: ActiveStepOptions): string[];
 export {};

package/dist/ui/currentStep.js

@@ -1,6 +1,8 @@
 import chalk from "chalk";
+import { getActivityIndicatorFrame } from "./activityIndicator.js";
 export function buildActiveStepLines(options) {
     const { step, stepNumber, totalSteps, phase } = options;
+    const activityFrameIndex = options.activityFrameIndex ?? 0;
     const isRunning = phase === "running" || phase === "installing";
     const lines = [
         chalk.dim(`  ${"─".repeat(3)} Step ${stepNumber}/${totalSteps}  `) +
@@ -10,7 +12,7 @@ export function buildActiveStepLines(options) {
     ];
     if (isRunning) {
         const label = phase === "installing" ? "Installing..." : "Running...";
-        lines.push(`  ${chalk.blue("▶")} ${label}`);
+        lines.push(`  ${chalk.blue(getActivityIndicatorFrame(activityFrameIndex))} ${label}`);
     }
     return lines;
 }

package/dist/ui/header.d.ts

@@ -2,7 +2,7 @@ import type { DisplayStep, StepPhase, CompletedStepRecord, LogoVisibility } from
 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 stepTrackerIcon(phase: StepPhase, activityFrameIndex?: number): string;
 export declare function isActivePhase(phase: StepPhase): boolean;
 export declare function deriveAllStepPhases(steps: DisplayStep[], currentStepIndex: number, currentPhase: StepPhase, completedStepRecords: CompletedStepRecord[]): StepPhase[];
 type BuildHeaderOptions = {
@@ -12,6 +12,7 @@ type BuildHeaderOptions = {
     currentStepIndex: number;
     currentPhase: StepPhase;
     completedStepRecords: CompletedStepRecord[];
+    activityFrameIndex?: number;
     terminalDimensions?: TerminalDimensions;
 };
 export declare function buildHeaderLines(options: BuildHeaderOptions): string[];

package/dist/ui/header.js

@@ -1,5 +1,7 @@
 import chalk from "chalk";
 import { LOGO_ART } from "../logo.js";
+import { buildCategorySectionsInOrder, getStepCategoryLabel } from "../steps/index.js";
+import { getActivityIndicatorFrame } from "./activityIndicator.js";
 const LOGO_COLUMN_WIDTH = 32;
 const LOGO_SEPARATOR = "    ";
 const MIN_SIDE_BY_SIDE_COLS = LOGO_COLUMN_WIDTH + LOGO_SEPARATOR.length + 20; // 56
@@ -14,16 +16,16 @@ export function determineLogoLayout(logoLines, dimensions) {
     }
     return "none";
 }
-export function stepTrackerIcon(phase) {
+export function stepTrackerIcon(phase, activityFrameIndex = 0) {
     if (phase === "complete")
         return chalk.green("✓ ");
     if (phase === "failed")
         return chalk.red("✗ ");
     if (phase === "skipped" || phase === "not-available")
         return chalk.dim("– ");
-    if (phase === "running" ||
-        phase === "installing" ||
-        phase === "prompting-to-run" ||
+    if (phase === "running" || phase === "installing")
+        return chalk.cyan(`${getActivityIndicatorFrame(activityFrameIndex)} `);
+    if (phase === "prompting-to-run" ||
         phase === "prompting-to-install" ||
         phase === "checking-availability")
         return chalk.cyan("→ ");
@@ -47,26 +49,17 @@ export function deriveAllStepPhases(steps, currentStepIndex, currentPhase, compl
 }
 export function buildHeaderLines(options) {
     const { steps, version, logoVisibility, currentStepIndex, currentPhase, completedStepRecords } = options;
+    const activityFrameIndex = options.activityFrameIndex ?? 0;
     const phases = deriveAllStepPhases(steps, currentStepIndex, currentPhase, completedStepRecords);
-    const hasRuntimeSteps = steps.some((step) => step.stage === "runtime");
-    const hasToolsSteps = steps.some((step) => step.stage === "tools");
-    const showStageLabels = hasRuntimeSteps && hasToolsSteps;
     const stepLines = [];
-    for (let stepIndex = 0; stepIndex < steps.length; stepIndex++) {
-        const step = steps[stepIndex];
-        if (showStageLabels) {
-            const isFirstRuntime = step.stage === "runtime" && (stepIndex === 0 || steps[stepIndex - 1].stage !== "runtime");
-            const isFirstTools = step.stage === "tools" && (stepIndex === 0 || steps[stepIndex - 1].stage !== "tools");
-            if (isFirstRuntime) {
-                stepLines.push(chalk.dim("Runtimes"));
-            }
-            else if (isFirstTools) {
-                stepLines.push(chalk.dim("Tools"));
-            }
+    const indexedSteps = steps.map((step, stepIndex) => ({ step, stepIndex, categoryId: step.categoryId }));
+    for (const section of buildCategorySectionsInOrder(indexedSteps)) {
+        stepLines.push(chalk.dim(`System / ${getStepCategoryLabel(section.categoryId)}`));
+        for (const indexedStep of section.items) {
+            const icon = stepTrackerIcon(phases[indexedStep.stepIndex], activityFrameIndex);
+            const name = isActivePhase(phases[indexedStep.stepIndex]) ? chalk.white(indexedStep.step.name) : chalk.dim(indexedStep.step.name);
+            stepLines.push(`${icon}${name}`);
         }
-        const icon = stepTrackerIcon(phases[stepIndex]);
-        const name = isActivePhase(phases[stepIndex]) ? chalk.white(step.name) : chalk.dim(step.name);
-        stepLines.push(`${icon}${name}`);
     }
     const rightColumnLines = [
         `${chalk.bold.white("braeburn")} ${chalk.dim("v" + version)}`,

package/dist/ui/screen.d.ts

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

package/dist/ui/screen.js

@@ -10,6 +10,9 @@ export function createScreenRenderer(output = process.stdout) {
     };
 }
 export function buildScreen(state, terminalDimensions) {
+    return buildScreenWithAnimationFrame(state, 0, terminalDimensions);
+}
+export function buildScreenWithAnimationFrame(state, activityFrameIndex, terminalDimensions) {
     const lines = [];
     const failedStepIds = state.completedStepRecords.flatMap((record, stepIndex) => {
         if (record.phase !== "failed") {
@@ -28,6 +31,7 @@ export function buildScreen(state, terminalDimensions) {
         currentStepIndex: state.currentStepIndex,
         currentPhase: state.currentPhase,
         completedStepRecords: state.completedStepRecords,
+        activityFrameIndex,
         terminalDimensions,
     }));
     lines.push("");
@@ -50,6 +54,7 @@ export function buildScreen(state, terminalDimensions) {
                 stepNumber: state.currentStepIndex + 1,
                 totalSteps: state.steps.length,
                 phase: state.currentPhase,
+                activityFrameIndex,
             }));
             const isShowingOutput = (state.currentPhase === "running" || state.currentPhase === "installing") &&
                 state.currentOutputLines.length > 0;

package/dist/ui/state.d.ts

@@ -1 +1 @@
-export { type StepStage, type DisplayStep, type StepPhase, type CompletedStepRecord, type CurrentPrompt, type ResolvedVersion, type LogoVisibility, type RunCompletion, type UpdateState, type AppState, createInitialUpdateState, createInitialAppState, } from "../update/state.js";
+export { type DisplayStep, type StepPhase, type CompletedStepRecord, type CurrentPrompt, type ResolvedVersion, type LogoVisibility, type RunCompletion, type UpdateState, type AppState, createInitialUpdateState, createInitialAppState, } from "../update/state.js";

package/dist/update/displayStep.js

@@ -3,7 +3,7 @@ export function toDisplayStep(step) {
         id: step.id,
         name: step.name,
         description: step.description,
-        stage: step.stage,
+        categoryId: step.categoryId,
     };
 }
 export function toDisplaySteps(steps) {

package/dist/update/state.d.ts

@@ -1,10 +1,10 @@
 import type { CommandOutputLine } from "../runner.js";
-export type StepStage = "runtime" | "tools";
+import type { StepCategoryId } from "../steps/categories.js";
 export type DisplayStep = {
     id: string;
     name: string;
     description: string;
-    stage: StepStage;
+    categoryId: StepCategoryId;
 };
 export type StepPhase = "pending" | "checking-availability" | "prompting-to-install" | "installing" | "prompting-to-run" | "running" | "complete" | "failed" | "skipped" | "not-available";
 export type CompletedStepRecord = {

package/package.json

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