braeburn 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,39 @@
+# braeburn
+
+[![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.
+
+## Install
+
+```sh
+npm install -g braeburn
+```
+
+## Usage
+
+```sh
+braeburn              # run all enabled steps interactively
+braeburn -y           # run all steps, auto-accept everything
+braeburn homebrew npm # run specific steps only
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `braeburn [steps...] [-y]` | Run update steps (default) |
+| `braeburn log [step]` | View the latest output log for a step |
+| `braeburn config` | View current configuration |
+| `braeburn config update --no-<step>` | Disable a step |
+| `braeburn config update --<step>` | Re-enable a step |
+
+## Steps
+
+`homebrew` `mas` `ohmyzsh` `npm` `pip` `pyenv` `nvm` `dotnet` `macos` `cleanup`
+
+## Requirements
+
+- macOS
+- Node.js ≥ 24
+- [Homebrew](https://brew.sh) (required)

package/dist/commands/setup.d.ts

@@ -0,0 +1,2 @@
+import type { Step } from "../steps/index.js";
+export declare function runSetupCommand(allSteps: Step[]): Promise<void>;

package/dist/commands/setup.js

@@ -0,0 +1,144 @@
+import readline from "node:readline";
+import chalk from "chalk";
+import { writeConfig, PROTECTED_STEP_IDS } from "../config.js";
+import { LOGO_ART } from "../logo.js";
+// Module-level render state (scoped to this screen, separate from update screen)
+let prevLines = 0;
+function render(content) {
+    if (prevLines > 0) {
+        process.stdout.write(`\x1b[${prevLines}A\x1b[J`);
+    }
+    process.stdout.write(content);
+    prevLines = (content.match(/\n/g) ?? []).length;
+}
+function buildLoadingScreen() {
+    const lines = [
+        chalk.yellow(LOGO_ART),
+        "",
+        `  ${chalk.bold.white("Welcome to braeburn!")}`,
+        "",
+        `  ${chalk.dim("Checking which tools are installed\u2026")}`,
+        "",
+    ];
+    return lines.join("\n") + "\n";
+}
+function buildSetupScreen(items, cursorIndex) {
+    const lines = [
+        chalk.yellow(LOGO_ART),
+        "",
+        `  ${chalk.bold.white("Welcome to braeburn!")}`,
+        "",
+        `  Select the update tools you\u2019d like to enable. For anything that isn\u2019t`,
+        `  installed yet, braeburn will offer to set it up via Homebrew when you run it.`,
+        "",
+        `  ${chalk.dim("\u2191\u2193  navigate    Space  toggle    Return  confirm")}`,
+        "",
+    ];
+    for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        const isCursor = i === cursorIndex;
+        const cursor = isCursor ? chalk.cyan("\u203a") : " ";
+        const checkbox = item.selected ? chalk.green("\u25cf") : chalk.dim("\u25cb");
+        const namePadded = item.step.name.padEnd(18);
+        const name = isCursor ? chalk.bold.white(namePadded) : chalk.white(namePadded);
+        let status;
+        if (item.isProtected) {
+            status = chalk.dim("required");
+        }
+        else if (item.isAvailable) {
+            status = chalk.green("installed");
+        }
+        else if (item.step.brewPackageToInstall) {
+            status = chalk.yellow(`not installed`) + chalk.dim(`  \u2192 will offer to install via Homebrew`);
+        }
+        else {
+            status = chalk.dim("not installed");
+        }
+        lines.push(`  ${cursor} ${checkbox}  ${name}  ${status}`);
+        if (isCursor) {
+            lines.push(`           ${chalk.dim(item.step.description)}`);
+        }
+    }
+    const enabledCount = items.filter((i) => i.selected).length;
+    lines.push("");
+    lines.push(`  ${chalk.dim(`${enabledCount} of ${items.length} tools selected`)}`);
+    lines.push("");
+    return lines.join("\n") + "\n";
+}
+export async function runSetupCommand(allSteps) {
+    // Hide cursor; restore on exit
+    process.stdout.write("\x1b[?25l");
+    process.on("exit", () => process.stdout.write("\x1b[?25h"));
+    process.on("SIGINT", () => {
+        process.stdout.write("\x1b[?25h\n");
+        process.exit(130);
+    });
+    // Show loading screen while we check availability in parallel
+    render(buildLoadingScreen());
+    const availabilityResults = await Promise.all(allSteps.map((step) => step.checkIsAvailable()));
+    const items = allSteps.map((step, i) => ({
+        step,
+        selected: true, // all enabled by default — user opts out
+        isProtected: PROTECTED_STEP_IDS.has(step.id),
+        isAvailable: availabilityResults[i],
+    }));
+    let cursorIndex = 0;
+    render(buildSetupScreen(items, cursorIndex));
+    // Interactive selection loop
+    await new Promise((resolve) => {
+        readline.emitKeypressEvents(process.stdin);
+        if (process.stdin.isTTY)
+            process.stdin.setRawMode(true);
+        const handleKeypress = (_char, key) => {
+            if (key?.ctrl && key?.name === "c") {
+                process.stdout.write("\x1b[?25h\n");
+                process.exit(130);
+            }
+            if (key?.name === "up" || key?.name === "k") {
+                cursorIndex = Math.max(0, cursorIndex - 1);
+                render(buildSetupScreen(items, cursorIndex));
+            }
+            else if (key?.name === "down" || key?.name === "j") {
+                cursorIndex = Math.min(items.length - 1, cursorIndex + 1);
+                render(buildSetupScreen(items, cursorIndex));
+            }
+            else if (key?.name === "space") {
+                const item = items[cursorIndex];
+                if (!item.isProtected) {
+                    item.selected = !item.selected;
+                    render(buildSetupScreen(items, cursorIndex));
+                }
+            }
+            else if (key?.name === "return") {
+                process.stdin.removeListener("keypress", handleKeypress);
+                if (process.stdin.isTTY)
+                    process.stdin.setRawMode(false);
+                process.stdin.pause();
+                resolve();
+            }
+        };
+        process.stdin.on("keypress", handleKeypress);
+        process.stdin.resume();
+    });
+    // Restore cursor
+    process.stdout.write("\x1b[?25h");
+    // Persist choices — only write explicit false entries (keeps file minimal, matches
+    // the opt-out convention used everywhere else in the codebase)
+    const stepsConfig = {};
+    for (const item of items) {
+        if (!item.isProtected && !item.selected) {
+            stepsConfig[item.step.id] = false;
+        }
+    }
+    await writeConfig({ steps: stepsConfig });
+    // Clear the setup screen and print a brief confirmation before the update starts
+    if (prevLines > 0) {
+        process.stdout.write(`\x1b[${prevLines}A\x1b[J`);
+    }
+    process.stdout.write(chalk.yellow(LOGO_ART) + "\n");
+    process.stdout.write("\n");
+    process.stdout.write(`  ${chalk.green("\u2713")}  Setup complete! Starting your first update\u2026\n`);
+    process.stdout.write("\n");
+    // Small pause so the confirmation is readable before the update screen takes over
+    await new Promise((res) => setTimeout(res, 800));
+}

package/dist/config.d.ts

@@ -4,6 +4,7 @@ export type BraeburnConfig = {
     steps: Record<string, boolean>;
 };
 export declare function resolveConfigPath(): Promise<string>;
+export declare function configFileExists(): Promise<boolean>;
 export declare function readConfig(): Promise<BraeburnConfig>;
 export declare function writeConfig(config: BraeburnConfig): Promise<void>;
 export declare function isStepEnabled(config: BraeburnConfig, stepId: string): boolean;

package/dist/config.js

@@ -21,6 +21,10 @@ export async function resolveConfigPath() {
     }
     return join(homedir(), ".braeburn", "config");
 }
+export async function configFileExists() {
+    const configPath = await resolveConfigPath();
+    return pathExists(configPath);
+}
 export async function readConfig() {
     const configPath = await resolveConfigPath();
     try {

package/dist/index.js

@@ -7,7 +7,8 @@ import { homebrewStep, masStep, ohmyzshStep, npmStep, pipStep, pyenvStep, nvmSte
 import { runUpdateCommand } from "./commands/update.js";
 import { runLogCommand, runLogListCommand } from "./commands/log.js";
 import { runConfigCommand, runConfigUpdateCommand } from "./commands/config.js";
-import { readConfig, isStepEnabled, PROTECTED_STEP_IDS } from "./config.js";
+import { runSetupCommand } from "./commands/setup.js";
+import { readConfig, isStepEnabled, PROTECTED_STEP_IDS, configFileExists } from "./config.js";
 const ALL_STEPS = [
     homebrewStep,
     masStep,
@@ -58,6 +59,10 @@ Examples:
   `)
     .action(async (stepArguments, options) => {
     const autoYes = options.yes === true || options.force === true;
+    // First-run: if no config file exists yet, show the setup wizard.
+    if (!(await configFileExists())) {
+        await runSetupCommand(ALL_STEPS);
+    }
     let stepsToRun = stepArguments.length === 0
         ? ALL_STEPS
         : resolveStepsByIds(stepArguments);

package/package.json

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