braeburn 1.0.0

package/dist/steps/homebrew.js

@@ -0,0 +1,13 @@
+import { checkCommandExists, runStep } from "./index.js";
+const homebrewStep = {
+    id: "homebrew",
+    name: "Homebrew",
+    description: "Update Homebrew itself and upgrade all installed formulae",
+    async checkIsAvailable() {
+        return checkCommandExists("brew");
+    },
+    async run(context) {
+        await runStep("brew update && brew upgrade", context);
+    },
+};
+export default homebrewStep;

package/dist/steps/index.d.ts

@@ -0,0 +1,27 @@
+import { type OutputLineCallback } from "../runner.js";
+import type { StepLogWriter } from "../logger.js";
+export type StepRunContext = {
+    onOutputLine: OutputLineCallback;
+    logWriter: StepLogWriter;
+};
+export type Step = {
+    id: string;
+    name: string;
+    description: string;
+    brewPackageToInstall?: string;
+    checkIsAvailable: () => Promise<boolean>;
+    run: (context: StepRunContext) => Promise<void>;
+};
+export { default as homebrewStep } from "./homebrew.js";
+export { default as masStep } from "./mas.js";
+export { default as ohmyzshStep } from "./ohmyzsh.js";
+export { default as npmStep } from "./npm.js";
+export { default as pipStep } from "./pip.js";
+export { default as pyenvStep } from "./pyenv.js";
+export { default as nvmStep } from "./nvm.js";
+export { default as dotnetStep } from "./dotnet.js";
+export { default as macosStep } from "./macos.js";
+export { default as cleanupStep } from "./cleanup.js";
+export declare function checkCommandExists(command: string): Promise<boolean>;
+export declare function checkPathExists(filePath: string): Promise<boolean>;
+export declare function runStep(shellCommand: string, context: StepRunContext): Promise<void>;

package/dist/steps/index.js

@@ -0,0 +1,24 @@
+import { doesShellCommandSucceed, runShellCommand, } from "../runner.js";
+export { default as homebrewStep } from "./homebrew.js";
+export { default as masStep } from "./mas.js";
+export { default as ohmyzshStep } from "./ohmyzsh.js";
+export { default as npmStep } from "./npm.js";
+export { default as pipStep } from "./pip.js";
+export { default as pyenvStep } from "./pyenv.js";
+export { default as nvmStep } from "./nvm.js";
+export { default as dotnetStep } from "./dotnet.js";
+export { default as macosStep } from "./macos.js";
+export { default as cleanupStep } from "./cleanup.js";
+export async function checkCommandExists(command) {
+    return doesShellCommandSucceed({ shellCommand: `command -v ${command}` });
+}
+export async function checkPathExists(filePath) {
+    return doesShellCommandSucceed({ shellCommand: `test -e "${filePath}"` });
+}
+export async function runStep(shellCommand, context) {
+    await runShellCommand({
+        shellCommand,
+        onOutputLine: context.onOutputLine,
+        logWriter: context.logWriter,
+    });
+}

package/dist/steps/macos.d.ts

@@ -0,0 +1,3 @@
+import { type Step } from "./index.js";
+declare const macosStep: Step;
+export default macosStep;

package/dist/steps/macos.js

@@ -0,0 +1,32 @@
+import { runStep, } from "./index.js";
+import { captureShellCommandOutput } from "../runner.js";
+// softwareupdate always exists on macOS — no availability check needed
+const macosStep = {
+    id: "macos",
+    name: "macOS",
+    description: "Check for and optionally install macOS system software updates",
+    async checkIsAvailable() {
+        return true;
+    },
+    async run(context) {
+        const updateListOutput = await captureShellCommandOutput({
+            shellCommand: "softwareupdate -l 2>&1",
+        });
+        context.logWriter(updateListOutput);
+        const noUpdatesAvailable = updateListOutput.includes("No new software available");
+        if (noUpdatesAvailable) {
+            context.onOutputLine({
+                text: "macOS is already up to date.",
+                isError: false,
+            });
+            return;
+        }
+        context.onOutputLine({ text: updateListOutput, isError: false });
+        context.onOutputLine({
+            text: "Updates found — installing now...",
+            isError: false,
+        });
+        await runStep("softwareupdate -ia --verbose", context);
+    },
+};
+export default macosStep;

package/dist/steps/mas.d.ts

@@ -0,0 +1,3 @@
+import { type Step } from "./index.js";
+declare const masStep: Step;
+export default masStep;

package/dist/steps/mas.js

@@ -0,0 +1,14 @@
+import { checkCommandExists, runStep } from "./index.js";
+const masStep = {
+    id: "mas",
+    name: "Mac App Store",
+    description: "Upgrade all Mac App Store apps via the mas CLI tool",
+    brewPackageToInstall: "mas",
+    async checkIsAvailable() {
+        return checkCommandExists("mas");
+    },
+    async run(context) {
+        await runStep("mas upgrade", context);
+    },
+};
+export default masStep;

package/dist/steps/npm.d.ts

@@ -0,0 +1,3 @@
+import { type Step } from "./index.js";
+declare const npmStep: Step;
+export default npmStep;

package/dist/steps/npm.js

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

package/dist/steps/nvm.d.ts

@@ -0,0 +1,3 @@
+import { type Step } from "./index.js";
+declare const nvmStep: Step;
+export default nvmStep;

package/dist/steps/nvm.js

@@ -0,0 +1,20 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { checkPathExists, runStep } from "./index.js";
+const NVM_DIRECTORY = join(homedir(), ".nvm");
+// nvm is a shell function sourced from nvm.sh — it cannot be invoked as a
+// standalone binary, so we source it explicitly inside each bash invocation.
+const NVM_SOURCE_PREFIX = `export NVM_DIR="${NVM_DIRECTORY}" && source "$NVM_DIR/nvm.sh"`;
+const nvmStep = {
+    id: "nvm",
+    name: "Node.js (nvm)",
+    description: "Install the latest Node.js via nvm, migrating packages from the current version",
+    // No brewPackageToInstall — nvm is installed via a curl script, not Homebrew
+    async checkIsAvailable() {
+        return checkPathExists(NVM_DIRECTORY);
+    },
+    async run(context) {
+        await runStep(`${NVM_SOURCE_PREFIX} && nvm install node --reinstall-packages-from=node`, context);
+    },
+};
+export default nvmStep;

package/dist/steps/ohmyzsh.d.ts

@@ -0,0 +1,3 @@
+import { type Step } from "./index.js";
+declare const ohmyzshStep: Step;
+export default ohmyzshStep;

package/dist/steps/ohmyzsh.js

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

package/dist/steps/pip.d.ts

@@ -0,0 +1,3 @@
+import { type Step } from "./index.js";
+declare const pipStep: Step;
+export default pipStep;

package/dist/steps/pip.js

@@ -0,0 +1,17 @@
+import { checkCommandExists, runStep } from "./index.js";
+// Updating all global pip3 packages can occasionally break tools that depend
+// on specific versions. The warning is surfaced in the UI before running.
+const PIP_UPDATE_ALL_OUTDATED_SHELL_COMMAND = "pip3 list --outdated --format=columns | tail -n +3 | awk '{print $1}' | xargs -n1 pip3 install -U";
+const pipStep = {
+    id: "pip",
+    name: "pip3",
+    description: "Update all globally installed pip3 packages",
+    // No brewPackageToInstall — pip3 comes with Python
+    async checkIsAvailable() {
+        return checkCommandExists("pip3");
+    },
+    async run(context) {
+        await runStep(PIP_UPDATE_ALL_OUTDATED_SHELL_COMMAND, context);
+    },
+};
+export default pipStep;

package/dist/steps/pyenv.d.ts

@@ -0,0 +1,3 @@
+import { type Step } from "./index.js";
+declare const pyenvStep: Step;
+export default pyenvStep;

package/dist/steps/pyenv.js

@@ -0,0 +1,29 @@
+import { checkCommandExists, runStep, } from "./index.js";
+import { captureShellCommandOutput } from "../runner.js";
+// Dynamically finds the latest stable Python 3.x.y release known to pyenv,
+// excluding pre-releases (alpha, beta, release candidates, dev builds).
+const FIND_LATEST_STABLE_PYTHON_SHELL_COMMAND = "pyenv install -l | grep -E '^\\s+3\\.[0-9]+\\.[0-9]+$' | grep -vE 'dev|a[0-9]|b[0-9]|rc[0-9]' | tail -1 | tr -d ' '";
+const pyenvStep = {
+    id: "pyenv",
+    name: "pyenv",
+    description: "Upgrade pyenv via Homebrew and install the latest Python 3.x",
+    brewPackageToInstall: "pyenv",
+    async checkIsAvailable() {
+        return checkCommandExists("pyenv");
+    },
+    async run(context) {
+        await runStep("brew upgrade pyenv", context);
+        const latestPythonVersion = await captureShellCommandOutput({
+            shellCommand: FIND_LATEST_STABLE_PYTHON_SHELL_COMMAND,
+        });
+        if (!latestPythonVersion) {
+            context.onOutputLine({
+                text: "Could not determine latest Python version — skipping pyenv install.",
+                isError: true,
+            });
+            return;
+        }
+        await runStep(`pyenv install --skip-existing ${latestPythonVersion}`, context);
+    },
+};
+export default pyenvStep;

package/dist/ui/currentStep.d.ts

@@ -0,0 +1,10 @@
+import type { Step } from "../steps/index.js";
+import type { StepPhase } from "./state.js";
+type ActiveStepOptions = {
+    step: Step;
+    stepNumber: number;
+    totalSteps: number;
+    phase: StepPhase;
+};
+export declare function buildActiveStepLines(options: ActiveStepOptions): string[];
+export {};

package/dist/ui/currentStep.js

@@ -0,0 +1,16 @@
+import chalk from "chalk";
+export function buildActiveStepLines(options) {
+    const { step, stepNumber, totalSteps, phase } = options;
+    const isRunning = phase === "running" || phase === "installing";
+    const lines = [
+        chalk.dim(`  ${"─".repeat(3)} Step ${stepNumber}/${totalSteps}  `) +
+            chalk.bold.white(step.name) +
+            chalk.dim(`  ${"─".repeat(20)}`),
+        `  ${chalk.dim("·")} ${chalk.dim.italic(step.description)}`,
+    ];
+    if (isRunning) {
+        const label = phase === "installing" ? "Installing..." : "Running...";
+        lines.push(`  ${chalk.blue("▶")} ${label}`);
+    }
+    return lines;
+}

package/dist/ui/header.d.ts

@@ -0,0 +1,11 @@
+import type { Step } from "../steps/index.js";
+import type { StepPhase, CompletedStepRecord } from "./state.js";
+type BuildHeaderOptions = {
+    steps: Step[];
+    version: string;
+    currentStepIndex: number;
+    currentPhase: StepPhase;
+    completedStepRecords: CompletedStepRecord[];
+};
+export declare function buildHeaderLines(options: BuildHeaderOptions): string[];
+export {};

package/dist/ui/header.js

@@ -0,0 +1,61 @@
+import chalk from "chalk";
+import { LOGO_ART } from "../logo.js";
+const LOGO_COLUMN_WIDTH = 32;
+const LOGO_SEPARATOR = "    ";
+function stepTrackerIcon(phase) {
+    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" ||
+        phase === "prompting-to-install" ||
+        phase === "checking-availability")
+        return chalk.cyan("→ ");
+    return chalk.dim("· ");
+}
+function isActivePhase(phase) {
+    return (phase === "running" ||
+        phase === "installing" ||
+        phase === "prompting-to-run" ||
+        phase === "prompting-to-install" ||
+        phase === "checking-availability");
+}
+function deriveAllStepPhases(steps, currentStepIndex, currentPhase, completedStepRecords) {
+    return steps.map((_, index) => {
+        if (index < completedStepRecords.length)
+            return completedStepRecords[index].phase;
+        if (index === currentStepIndex)
+            return currentPhase;
+        return "pending";
+    });
+}
+export function buildHeaderLines(options) {
+    const { steps, version, currentStepIndex, currentPhase, completedStepRecords } = options;
+    const phases = deriveAllStepPhases(steps, currentStepIndex, currentPhase, completedStepRecords);
+    const logoLines = LOGO_ART.split("\n");
+    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}`;
+        }),
+    ];
+    const totalLines = Math.max(logoLines.length, rightColumnLines.length);
+    const result = [];
+    for (let i = 0; i < totalLines; i++) {
+        // Pad the raw logo line to a fixed width before applying colour, so the
+        // ANSI escape codes don't affect visual alignment.
+        const rawLogoLine = (logoLines[i] ?? "").padEnd(LOGO_COLUMN_WIDTH);
+        const logoColumn = chalk.yellow(rawLogoLine);
+        const rightColumn = rightColumnLines[i] ?? "";
+        result.push(`${logoColumn}${LOGO_SEPARATOR}${rightColumn}`);
+    }
+    return result;
+}

package/dist/ui/outputBox.d.ts

@@ -0,0 +1,2 @@
+import type { CommandOutputLine } from "../runner.js";
+export declare function buildOutputBoxLines(lines: CommandOutputLine[], stepName: string): string[];

package/dist/ui/outputBox.js

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

package/dist/ui/prompt.d.ts

@@ -0,0 +1,3 @@
+import type { CurrentPrompt } from "./state.js";
+export declare function captureYesNo(): Promise<boolean>;
+export declare function buildPromptLines(prompt: CurrentPrompt): string[];

package/dist/ui/prompt.js

@@ -0,0 +1,37 @@
+import readline from "node:readline";
+import chalk from "chalk";
+export function captureYesNo() {
+    return new Promise((resolve) => {
+        readline.emitKeypressEvents(process.stdin);
+        if (process.stdin.isTTY) {
+            process.stdin.setRawMode(true);
+        }
+        const handleKeypress = (character, key) => {
+            if (key?.ctrl && key?.name === "c") {
+                process.stdout.write("\x1b[?25h\n");
+                process.exit(130);
+            }
+            const isConfirm = character === "y" || character === "Y" || key?.name === "return";
+            const isDecline = character === "n" || character === "N";
+            if (!isConfirm && !isDecline)
+                return;
+            process.stdin.removeListener("keypress", handleKeypress);
+            if (process.stdin.isTTY) {
+                process.stdin.setRawMode(false);
+            }
+            process.stdin.pause();
+            resolve(isConfirm);
+        };
+        process.stdin.on("keypress", handleKeypress);
+        process.stdin.resume();
+    });
+}
+export function buildPromptLines(prompt) {
+    const lines = [];
+    if (prompt.warning) {
+        lines.push(`  ${chalk.yellow("⚠")}  ${chalk.yellow(prompt.warning)}`);
+        lines.push("");
+    }
+    lines.push(`  ${chalk.cyan("?")}  ${prompt.question} ${chalk.dim("[Y/n]")}`);
+    return lines;
+}

package/dist/ui/screen.d.ts

@@ -0,0 +1,3 @@
+import type { AppState } from "./state.js";
+export declare function renderScreen(content: string): void;
+export declare function buildScreen(state: AppState): string;

package/dist/ui/screen.js

@@ -0,0 +1,54 @@
+import { buildHeaderLines } from "./header.js";
+import { buildActiveStepLines } from "./currentStep.js";
+import { buildOutputBoxLines } from "./outputBox.js";
+import { buildPromptLines } from "./prompt.js";
+import { buildVersionReportLines } from "./versionReport.js";
+let previousLineCount = 0;
+export function renderScreen(content) {
+    if (previousLineCount > 0) {
+        process.stdout.write(`\x1b[${previousLineCount}A\x1b[J`);
+    }
+    process.stdout.write(content);
+    previousLineCount = (content.match(/\n/g) ?? []).length;
+}
+export function buildScreen(state) {
+    const lines = [];
+    lines.push(...buildHeaderLines({
+        steps: state.steps,
+        version: state.version,
+        currentStepIndex: state.currentStepIndex,
+        currentPhase: state.currentPhase,
+        completedStepRecords: state.completedStepRecords,
+    }));
+    lines.push("");
+    if (state.isFinished) {
+        if (state.versionReport) {
+            lines.push("");
+            lines.push(...buildVersionReportLines(state.versionReport));
+        }
+    }
+    else {
+        const currentStep = state.steps[state.currentStepIndex];
+        if (currentStep) {
+            lines.push("");
+            lines.push(...buildActiveStepLines({
+                step: currentStep,
+                stepNumber: state.currentStepIndex + 1,
+                totalSteps: state.steps.length,
+                phase: state.currentPhase,
+            }));
+            const isShowingOutput = (state.currentPhase === "running" || state.currentPhase === "installing") &&
+                state.currentOutputLines.length > 0;
+            if (isShowingOutput) {
+                lines.push("");
+                lines.push(...buildOutputBoxLines(state.currentOutputLines, currentStep.name));
+            }
+            if (state.currentPrompt) {
+                lines.push("");
+                lines.push(...buildPromptLines(state.currentPrompt));
+            }
+        }
+    }
+    lines.push("");
+    return lines.join("\n") + "\n";
+}

package/dist/ui/state.d.ts

@@ -0,0 +1,27 @@
+import type { Step } from "../steps/index.js";
+import type { CommandOutputLine } from "../runner.js";
+export type StepPhase = "pending" | "checking-availability" | "prompting-to-install" | "installing" | "prompting-to-run" | "running" | "complete" | "failed" | "skipped" | "not-available";
+export type CompletedStepRecord = {
+    phase: StepPhase;
+    summaryNote?: string;
+};
+export type CurrentPrompt = {
+    question: string;
+    warning?: string;
+};
+export type ResolvedVersion = {
+    label: string;
+    value: string;
+};
+export type AppState = {
+    steps: Step[];
+    version: string;
+    currentStepIndex: number;
+    currentPhase: StepPhase;
+    completedStepRecords: CompletedStepRecord[];
+    currentOutputLines: CommandOutputLine[];
+    currentPrompt: CurrentPrompt | undefined;
+    isFinished: boolean;
+    versionReport: ResolvedVersion[] | undefined;
+};
+export declare function createInitialAppState(steps: Step[], version: string): AppState;

package/dist/ui/state.js

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

package/dist/ui/versionReport.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedVersion } from "./state.js";
+export declare function collectVersions(): Promise<ResolvedVersion[]>;
+export declare function buildVersionReportLines(versions: ResolvedVersion[]): string[];

package/dist/ui/versionReport.js

@@ -0,0 +1,25 @@
+import chalk from "chalk";
+import { captureShellCommandOutput } from "../runner.js";
+const VERSION_ENTRIES = [
+    { label: "macOS", shellCommand: "sw_vers -productVersion" },
+    { label: "Homebrew", shellCommand: "brew --version | head -n1" },
+    { label: "Node", shellCommand: "node -v 2>/dev/null" },
+    { label: "NPM", shellCommand: "npm -v 2>/dev/null" },
+    { label: "Python", shellCommand: "python3 --version 2>/dev/null" },
+    { label: "pip3", shellCommand: "pip3 --version 2>/dev/null | cut -d' ' -f1-2" },
+    { label: "Zsh", shellCommand: "zsh --version 2>/dev/null" },
+];
+export async function collectVersions() {
+    return Promise.all(VERSION_ENTRIES.map(async ({ label, shellCommand }) => {
+        const value = await captureShellCommandOutput({ shellCommand }).catch(() => "");
+        return { label, value: value || "not installed" };
+    }));
+}
+export function buildVersionReportLines(versions) {
+    return [
+        chalk.dim("  ─── Versions ─────────────────────────"),
+        ...versions.map(({ label, value }) => `  ${chalk.dim("·")} ${chalk.bold(label + ":")} ${chalk.dim(value)}`),
+        "",
+        `  ${chalk.green.bold("✓")} ${chalk.bold("All done!")}`,
+    ];
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "braeburn",
+  "version": "1.0.0",
+  "description": "macOS system updater CLI",
+  "type": "module",
+  "bin": {
+    "braeburn": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "execa": "^9.3.0",
+    "smol-toml": "^1.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.5.0"
+  }
+}