braeburn 1.2.3 → 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.js

@@ -1,5 +1,5 @@
 import chalk from "chalk";
-import { readConfig, writeConfig, resolveConfigPath, isSettingEnabled, isStepEnabled, isLogoEnabled, applySettingToConfig, 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();
@@ -76,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.js

@@ -27,9 +27,22 @@ 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 cursor = isCursor ? chalk.cyan("\u203a") : " ";
         const checkbox = item.selection === "selected" ? chalk.green("\u25cf") : chalk.dim("\u25cb");
         const namePadded = item.step.name.padEnd(18);
@@ -65,7 +78,7 @@ export async function runSetupCommand(allSteps) {
     const availabilityResults = await Promise.all(allSteps.map((step) => step.checkIsAvailable()));
     const items = allSteps.map((step, stepIndex) => ({
         step,
-        selection: "selected",
+        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",
     }));

package/dist/config.d.ts

@@ -1,4 +1,5 @@
 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;

package/dist/config.js

@@ -3,6 +3,7 @@ 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"]);
 const EMPTY_CONFIG = { steps: {} };
 const LOGO_SETTING_ID = "logo";
 async function pathExists(targetPath) {
@@ -46,6 +47,8 @@ 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;
 }
 export function isStepEnabled(config, stepId) {
@@ -65,6 +68,15 @@ export function applySettingToConfig(config, settingId, desiredState) {
         }
         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];
     }

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,
@@ -40,23 +40,27 @@ program
     .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;

package/dist/steps/cleanup.js

@@ -2,6 +2,7 @@ import { checkCommandExists } from "./index.js";
 const cleanupStep = {
     id: "cleanup",
     name: "Cleanup",
+    stage: "tools",
     description: "Remove outdated Homebrew downloads and cached versions",
     async checkIsAvailable() {
         return checkCommandExists("brew");

package/dist/steps/dotnet.js

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

package/dist/steps/homebrew.js

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

package/dist/steps/index.d.ts

@@ -8,10 +8,12 @@ export type StepRunContext = {
         shellCommand: string;
     }) => Promise<string>;
 };
+export type StepStage = "runtime" | "tools";
 export type Step = {
     id: string;
     name: string;
     description: string;
+    stage: StepStage;
     warning?: string;
     brewPackageToInstall?: string;
     checkIsAvailable: () => Promise<boolean>;

package/dist/steps/macos.js

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

package/dist/steps/mas.js

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

package/dist/steps/npm.js

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

package/dist/steps/nvm.js

@@ -8,6 +8,7 @@ const NVM_SOURCE_PREFIX = `export NVM_DIR="${NVM_DIRECTORY}" && source "$NVM_DIR
 const nvmStep = {
     id: "nvm",
     name: "Node.js (nvm)",
+    stage: "runtime",
     description: "Install the latest Node.js via nvm, migrating packages from the current version",
     async checkIsAvailable() {
         return checkPathExists(NVM_DIRECTORY);

package/dist/steps/ohmyzsh.js

@@ -5,6 +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",
     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,6 +3,7 @@ const PIP_UPDATE_ALL_OUTDATED_SHELL_COMMAND = "pip3 list --outdated --format=col
 const pipStep = {
     id: "pip",
     name: "pip3",
+    stage: "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,6 +3,7 @@ const FIND_LATEST_STABLE_PYTHON_SHELL_COMMAND = "pyenv install -l | grep -E '^\\
 const pyenvStep = {
     id: "pyenv",
     name: "pyenv",
+    stage: "runtime",
     description: "Upgrade pyenv via Homebrew and install the latest Python 3.x",
     brewPackageToInstall: "pyenv",
     async checkIsAvailable() {

package/dist/ui/header.js

@@ -48,15 +48,31 @@ export function deriveAllStepPhases(steps, currentStepIndex, currentPhase, compl
 export function buildHeaderLines(options) {
     const { steps, version, logoVisibility, currentStepIndex, currentPhase, completedStepRecords } = options;
     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 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)}`,
         chalk.dim("macOS system updater"),
         "",
-        ...steps.map((step, index) => {
-            const icon = stepTrackerIcon(phases[index]);
-            const name = isActivePhase(phases[index]) ? chalk.white(step.name) : chalk.dim(step.name);
-            return `${icon}${name}`;
-        }),
+        ...stepLines,
     ];
     if (logoVisibility === "hidden") {
         return rightColumnLines;

package/package.json

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