@fredlackey/devutils 0.0.18 → 0.1.0

package/src/installers/homebrew.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Installer: homebrew
+ *
+ * Installs Homebrew on macOS. This is a macOS-only installer.
+ * All other platforms get a clear error explaining what package manager to use instead.
+ * See registry.json for platform support and dependencies.
+ */
+
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+
+/**
+ * Returns the path to the user's shell profile file.
+ * Checks the SHELL environment variable to pick between .zshrc and .bashrc.
+ * @returns {string} Absolute path to the shell profile.
+ */
+function getShellProfile() {
+  const shell = process.env.SHELL || '';
+  if (shell.includes('zsh')) {
+    return path.join(os.homedir(), '.zshrc');
+  }
+  return path.join(os.homedir(), '.bashrc');
+}
+
+/**
+ * Check if Homebrew is already installed.
+ * @param {object} context - The CLI context object (has platform, shell, output, etc.)
+ * @returns {Promise<boolean>} true if brew is available on the system
+ */
+async function isInstalled(context) {
+  return context.shell.commandExists('brew');
+}
+
+/**
+ * Get the installed Homebrew version.
+ * @param {object} context - The CLI context object
+ * @returns {Promise<string|null>} Version string like '4.2.5', or null if unavailable.
+ */
+async function getVersion(context) {
+  try {
+    const result = await context.shell.exec('brew --version');
+    // Output looks like: "Homebrew 4.2.5"
+    const match = result.stdout.trim().match(/Homebrew\s+(\d+\.\d+\.\d+)/);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Install Homebrew on macOS.
+ * Uses the official install script with NONINTERACTIVE=1 to avoid prompts.
+ * Handles Apple Silicon PATH setup automatically.
+ * @param {object} context - The CLI context object
+ */
+async function install_macos(context) {
+  context.output.info('Installing Homebrew...');
+  context.output.info('This may prompt for your password and take a few minutes.');
+
+  // The official Homebrew install script.
+  // NONINTERACTIVE=1 suppresses the "Press RETURN to continue" prompt.
+  await context.shell.exec(
+    'NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"'
+  );
+
+  // On Apple Silicon Macs, brew installs to /opt/homebrew and the install script
+  // tells the user to add it to their PATH. We do that here if needed.
+  const platform = context.platform.detect();
+  if (platform.arch === 'arm64') {
+    if (!context.shell.commandExists('brew')) {
+      context.output.info('Adding Homebrew to PATH for Apple Silicon...');
+      const profilePath = getShellProfile();
+      const brewInitLine = 'eval "$(/opt/homebrew/bin/brew shellenv)"';
+
+      const existing = fs.existsSync(profilePath) ? fs.readFileSync(profilePath, 'utf8') : '';
+      if (!existing.includes(brewInitLine)) {
+        fs.appendFileSync(profilePath, `\n# Homebrew\n${brewInitLine}\n`);
+        context.output.info(`Added Homebrew PATH to ${profilePath}`);
+      }
+    }
+  }
+
+  // Verify it worked
+  if (!context.shell.commandExists('brew')) {
+    // Try the known paths directly
+    if (fs.existsSync('/opt/homebrew/bin/brew') || fs.existsSync('/usr/local/bin/brew')) {
+      context.output.info(
+        'Homebrew installed, but "brew" is not on your PATH yet. Open a new terminal or run: eval "$(/opt/homebrew/bin/brew shellenv)"'
+      );
+      return;
+    }
+    throw new Error('Homebrew installation failed. Check the output above for errors.');
+  }
+
+  context.output.info('Homebrew installed successfully.');
+}
+
+/**
+ * Install on Ubuntu -- not supported. Throws a helpful error.
+ * @param {object} context - The CLI context object
+ */
+async function install_ubuntu(context) {
+  throw new Error(
+    'Homebrew is only available on macOS. On Ubuntu, packages are managed with apt. ' +
+    'DevUtils uses apt automatically for Ubuntu installations.'
+  );
+}
+
+/**
+ * Install on Raspberry Pi OS -- not supported. Throws a helpful error.
+ * @param {object} context - The CLI context object
+ */
+async function install_raspbian(context) {
+  throw new Error(
+    'Homebrew is only available on macOS. On Raspberry Pi OS, packages are managed with apt. ' +
+    'DevUtils uses apt automatically for Raspberry Pi installations.'
+  );
+}
+
+/**
+ * Install on Amazon Linux -- not supported. Throws a helpful error.
+ * @param {object} context - The CLI context object
+ */
+async function install_amazon_linux(context) {
+  throw new Error(
+    'Homebrew is only available on macOS. On Amazon Linux, packages are managed with dnf/yum. ' +
+    'DevUtils uses dnf/yum automatically for Amazon Linux installations.'
+  );
+}
+
+/**
+ * Install on Windows -- not supported. Throws a helpful error.
+ * @param {object} context - The CLI context object
+ */
+async function install_windows(context) {
+  throw new Error(
+    'Homebrew is only available on macOS. On Windows, packages are managed with Chocolatey or winget. ' +
+    'DevUtils uses those automatically for Windows installations.'
+  );
+}
+
+/**
+ * Install in Git Bash -- not supported. Throws a helpful error.
+ * @param {object} context - The CLI context object
+ */
+async function install_gitbash(context) {
+  throw new Error(
+    'Homebrew is only available on macOS. In Git Bash, use the Windows package managers (Chocolatey or winget) instead.'
+  );
+}
+
+/**
+ * Main install dispatcher. Detects the platform and calls the right function.
+ * The framework calls this -- you don't need to call it directly.
+ * @param {object} context - The CLI context object
+ */
+async function install(context) {
+  const platformType = context.platform.detect().type;
+  const installers = {
+    'macos': install_macos,
+    'ubuntu': install_ubuntu,
+    'raspbian': install_raspbian,
+    'amazon-linux': install_amazon_linux,
+    'windows': install_windows,
+    'gitbash': install_gitbash,
+  };
+
+  const fn = installers[platformType];
+  if (!fn) {
+    throw new Error(`No installer for platform: ${platformType}`);
+  }
+
+  await fn(context);
+}
+
+module.exports = {
+  isInstalled,
+  install,
+  getVersion,
+  install_macos,
+  install_ubuntu,
+  install_raspbian,
+  install_amazon_linux,
+  install_windows,
+  install_gitbash,
+};

package/src/installers/node.js

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Installer: node
+ *
+ * Installs Node.js on all supported platforms.
+ * On Unix-like systems, installs via nvm (Node Version Manager).
+ * On Windows, installs directly via Chocolatey or winget.
+ * See registry.json for platform support and dependencies.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+/**
+ * Returns the nvm directory path.
+ * Checks the NVM_DIR environment variable first, falls back to ~/.nvm.
+ * @returns {string} The nvm directory path.
+ */
+function getNvmDir() {
+  return process.env.NVM_DIR || path.join(os.homedir(), '.nvm');
+}
+
+/**
+ * Checks if nvm is installed by looking for the nvm.sh script.
+ * nvm is a shell function, not a binary, so `which nvm` won't find it.
+ * @returns {boolean} true if nvm is installed.
+ */
+function isNvmInstalled() {
+  const nvmDir = getNvmDir();
+  return fs.existsSync(path.join(nvmDir, 'nvm.sh'));
+}
+
+/**
+ * Installs nvm using the official install script.
+ * The script clones the nvm repo (which is why git is a dependency).
+ * @param {object} context - The CLI context object
+ */
+async function installNvm(context) {
+  await context.shell.exec(
+    'curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash'
+  );
+}
+
+/**
+ * Wraps a command so that nvm is sourced in the subshell before it runs.
+ * Since nvm is a shell function (not a binary), we need to source it
+ * in the same subshell that will call nvm commands.
+ * @param {string} command - The nvm command to run (e.g. 'nvm install --lts').
+ * @returns {string} A bash command string that sources nvm first.
+ */
+function buildNvmCommand(command) {
+  const nvmDir = getNvmDir();
+  return `export NVM_DIR="${nvmDir}" && [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" && ${command}`;
+}
+
+/**
+ * Shared Unix install logic: installs nvm (if missing) then Node LTS via nvm.
+ * Used by macOS, Ubuntu, Raspbian, and Amazon Linux installers.
+ * @param {object} context - The CLI context object
+ */
+async function installViaUnixNvm(context) {
+  if (!isNvmInstalled()) {
+    context.output.info('Installing nvm...');
+    await installNvm(context);
+  }
+
+  context.output.info('Installing Node.js LTS via nvm...');
+  await context.shell.exec(buildNvmCommand('nvm install --lts'));
+  await context.shell.exec(buildNvmCommand('nvm alias default lts/*'));
+}
+
+/**
+ * Check if Node.js is already installed.
+ * @param {object} context - The CLI context object (has platform, shell, output, etc.)
+ * @returns {Promise<boolean>} true if node is available on the system
+ */
+async function isInstalled(context) {
+  return context.shell.commandExists('node');
+}
+
+/**
+ * Get the installed Node.js version.
+ * @param {object} context - The CLI context object
+ * @returns {Promise<string|null>} Version string like '20.11.0', or null if unavailable.
+ */
+async function getVersion(context) {
+  try {
+    const result = await context.shell.exec('node --version');
+    // Output looks like: "v20.11.0"
+    const match = result.stdout.trim().match(/v?(\d+\.\d+\.\d+)/);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Install Node.js on macOS via nvm.
+ * @param {object} context - The CLI context object
+ */
+async function install_macos(context) {
+  await installViaUnixNvm(context);
+}
+
+/**
+ * Install Node.js on Ubuntu via nvm.
+ * Ensures curl is available first (needed to download the nvm install script).
+ * @param {object} context - The CLI context object
+ */
+async function install_ubuntu(context) {
+  if (!context.shell.commandExists('curl')) {
+    context.output.info('Installing curl...');
+    await context.shell.exec('sudo apt-get update && sudo apt-get install -y curl');
+  }
+  await installViaUnixNvm(context);
+}
+
+/**
+ * Install Node.js on Raspberry Pi OS via nvm.
+ * Ensures curl is available first.
+ * @param {object} context - The CLI context object
+ */
+async function install_raspbian(context) {
+  if (!context.shell.commandExists('curl')) {
+    context.output.info('Installing curl...');
+    await context.shell.exec('sudo apt-get update && sudo apt-get install -y curl');
+  }
+  await installViaUnixNvm(context);
+}
+
+/**
+ * Install Node.js on Amazon Linux via nvm.
+ * Ensures curl is available first, using dnf or yum.
+ * @param {object} context - The CLI context object
+ */
+async function install_amazon_linux(context) {
+  if (!context.shell.commandExists('curl')) {
+    const hasDnf = context.shell.commandExists('dnf');
+    if (hasDnf) {
+      await context.shell.exec('sudo dnf install -y curl');
+    } else {
+      await context.shell.exec('sudo yum install -y curl');
+    }
+  }
+  await installViaUnixNvm(context);
+}
+
+/**
+ * Install Node.js on Windows using Chocolatey or winget.
+ * Installs Node directly (not via nvm-windows) for simplicity.
+ * @param {object} context - The CLI context object
+ */
+async function install_windows(context) {
+  const hasChoco = context.shell.commandExists('choco');
+  const hasWinget = context.shell.commandExists('winget');
+
+  if (hasChoco) {
+    await context.shell.exec('choco install nodejs-lts -y');
+  } else if (hasWinget) {
+    await context.shell.exec(
+      'winget install --id OpenJS.NodeJS.LTS --accept-package-agreements --accept-source-agreements'
+    );
+  } else {
+    throw new Error(
+      'Neither Chocolatey nor winget is available. Install one of them first, or download Node.js from https://nodejs.org'
+    );
+  }
+}
+
+/**
+ * Install Node.js in Git Bash.
+ * Git Bash runs on Windows, so Node must be installed on the Windows host.
+ * @param {object} context - The CLI context object
+ */
+async function install_gitbash(context) {
+  if (await isInstalled(context)) {
+    context.output.info('Node.js is already available in Git Bash.');
+    return;
+  }
+
+  throw new Error(
+    'Node.js must be installed on the Windows host. Download from https://nodejs.org or run the installer from a Windows shell.'
+  );
+}
+
+/**
+ * Main install dispatcher. Detects the platform and calls the right function.
+ * The framework calls this -- you don't need to call it directly.
+ * @param {object} context - The CLI context object
+ */
+async function install(context) {
+  const platformType = context.platform.detect().type;
+  const installers = {
+    'macos': install_macos,
+    'ubuntu': install_ubuntu,
+    'raspbian': install_raspbian,
+    'amazon-linux': install_amazon_linux,
+    'windows': install_windows,
+    'gitbash': install_gitbash,
+  };
+
+  const fn = installers[platformType];
+  if (!fn) {
+    throw new Error(`No installer for platform: ${platformType}`);
+  }
+
+  await fn(context);
+}
+
+module.exports = {
+  isInstalled,
+  install,
+  getVersion,
+  install_macos,
+  install_ubuntu,
+  install_raspbian,
+  install_amazon_linux,
+  install_windows,
+  install_gitbash,
+};

package/src/installers/registry.json

@@ -0,0 +1,29 @@
+{
+  "_comment": "Tool installer metadata. Dependencies, platforms, desktop flag, and status for each tool.",
+  "tools": [
+    {
+      "name": "git",
+      "description": "Distributed version control system",
+      "platforms": ["macos", "ubuntu", "raspbian", "amazon-linux", "windows", "gitbash"],
+      "dependencies": [],
+      "desktop": false,
+      "installer": "git.js"
+    },
+    {
+      "name": "node",
+      "description": "JavaScript runtime (installed via nvm on Unix)",
+      "platforms": ["macos", "ubuntu", "raspbian", "amazon-linux", "windows", "gitbash"],
+      "dependencies": ["git"],
+      "desktop": false,
+      "installer": "node.js"
+    },
+    {
+      "name": "homebrew",
+      "description": "Package manager for macOS",
+      "platforms": ["macos"],
+      "dependencies": [],
+      "desktop": false,
+      "installer": "homebrew.js"
+    }
+  ]
+}

package/src/lib/config.js

@@ -0,0 +1,125 @@
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * The path to the DevUtils configuration directory.
+ * All user data, preferences, and plugin data live here.
+ * @type {string}
+ */
+const CONFIG_DIR = path.join(os.homedir(), '.devutils');
+
+/**
+ * Creates the ~/.devutils/ directory if it doesn't exist.
+ * Idempotent: calling it multiple times has the same effect as calling it once.
+ *
+ * @returns {string} The config directory path.
+ */
+function ensureDir() {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+  return CONFIG_DIR;
+}
+
+/**
+ * Returns the full path to a file inside ~/.devutils/.
+ * Does not check if the file exists.
+ *
+ * @param {string} filename - The filename (e.g. 'config.json').
+ * @returns {string} The full file path.
+ */
+function getPath(filename) {
+  return path.join(CONFIG_DIR, filename);
+}
+
+/**
+ * Checks if a file exists in ~/.devutils/.
+ *
+ * @param {string} filename - The filename to check.
+ * @returns {boolean}
+ */
+function exists(filename) {
+  return fs.existsSync(getPath(filename));
+}
+
+/**
+ * Reads a JSON file from ~/.devutils/ and returns the parsed object.
+ * Returns null if the file doesn't exist or can't be parsed.
+ *
+ * @param {string} filename - The filename to read.
+ * @returns {object|null} The parsed JSON object, or null.
+ */
+function read(filename) {
+  const filePath = getPath(filename);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Writes a JavaScript object to a JSON file in ~/.devutils/.
+ * Creates the directory if it doesn't exist. Uses 2-space indentation
+ * and a trailing newline for human-readability.
+ *
+ * @param {string} filename - The filename to write.
+ * @param {object} data - The data to write.
+ * @returns {string} The full file path that was written.
+ */
+function write(filename, data) {
+  ensureDir();
+  const filePath = getPath(filename);
+  const content = JSON.stringify(data, null, 2) + '\n';
+  fs.writeFileSync(filePath, content, 'utf8');
+  return filePath;
+}
+
+/**
+ * Deletes a file from ~/.devutils/.
+ * Idempotent: does not throw if the file doesn't exist.
+ *
+ * @param {string} filename - The filename to delete.
+ * @returns {string} The full file path (whether it existed or not).
+ */
+function remove(filename) {
+  const filePath = getPath(filename);
+  if (fs.existsSync(filePath)) {
+    fs.unlinkSync(filePath);
+  }
+  return filePath;
+}
+
+/**
+ * Lists all files (not directories) in ~/.devutils/.
+ * Returns an empty array if the directory doesn't exist.
+ *
+ * @returns {string[]} Array of filenames.
+ */
+function list() {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    return [];
+  }
+  return fs.readdirSync(CONFIG_DIR).filter(entry => {
+    const fullPath = path.join(CONFIG_DIR, entry);
+    return fs.statSync(fullPath).isFile();
+  });
+}
+
+module.exports = {
+  CONFIG_DIR,
+  ensureDir,
+  getPath,
+  exists,
+  read,
+  write,
+  remove,
+  list,
+};

package/src/lib/detect.js

@@ -0,0 +1,74 @@
+'use strict';
+
+/**
+ * Environment variables set by AI coding assistants.
+ * Each entry is [varName, expectedValue].
+ * expectedValue can be null to match any truthy value.
+ */
+const AI_ENV_VARS = [
+  ['CLAUDECODE', '1'],
+  ['GEMINI_CLI', '1'],
+];
+
+/**
+ * Environment variables set by CI/CD systems.
+ * Each entry is [varName, expectedValue].
+ * expectedValue can be null to match any truthy value.
+ */
+const CI_ENV_VARS = [
+  ['CI', 'true'],
+  ['BUILD_NUMBER', null],
+  ['TF_BUILD', 'True'],
+];
+
+/**
+ * Checks if any environment variable in the list is set and matches.
+ * When expectedValue is null, any truthy value counts as a match.
+ *
+ * @param {Array<[string, string|null]>} varList - Array of [varName, expectedValue] pairs.
+ * @returns {boolean}
+ */
+function matchesEnv(varList) {
+  for (const [varName, expectedValue] of varList) {
+    const actual = process.env[varName];
+    if (actual === undefined) continue;
+    if (expectedValue === null) return true;
+    if (actual === expectedValue) return true;
+  }
+  return false;
+}
+
+/**
+ * Detects the output mode based on the calling environment.
+ * Checks three layers in priority order: AI tools, CI/CD, then TTY.
+ *
+ * - AI tools (Claude Code, Gemini CLI) get JSON format.
+ * - CI/CD systems (GitHub Actions, Jenkins, Azure) get JSON format.
+ * - Humans at a terminal get table format.
+ * - Piped or redirected output gets JSON format.
+ *
+ * @returns {{ format: string, caller: string }}
+ *   - format: 'json' or 'table'
+ *   - caller: 'ai', 'ci', 'tty', or 'pipe'
+ */
+function detectOutputMode() {
+  // Layer 1: AI tool environment
+  if (matchesEnv(AI_ENV_VARS)) {
+    return { format: 'json', caller: 'ai' };
+  }
+
+  // Layer 2: CI/CD environment
+  if (matchesEnv(CI_ENV_VARS)) {
+    return { format: 'json', caller: 'ci' };
+  }
+
+  // Layer 3: TTY detection
+  if (process.stdout.isTTY) {
+    return { format: 'table', caller: 'tty' };
+  }
+
+  // Fallback: piped or redirected output
+  return { format: 'json', caller: 'pipe' };
+}
+
+module.exports = { detectOutputMode };