@fredlackey/devutils 0.0.19 → 0.1.0

package/src/lib/installer.js

@@ -0,0 +1,225 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Cached registry data. Set on first call to loadRegistry().
+ * The registry doesn't change during a CLI run, so we only read it once.
+ * @type {Array<object>|null}
+ */
+let registryCache = null;
+
+/**
+ * Reads and parses the installer registry (src/installers/registry.json).
+ * Returns the tools array. Results are cached after the first call.
+ *
+ * @returns {Array<object>} The array of tool entries from the registry.
+ */
+function loadRegistry() {
+  if (registryCache) {
+    return registryCache;
+  }
+
+  const registryPath = path.join(__dirname, '..', 'installers', 'registry.json');
+  const raw = fs.readFileSync(registryPath, 'utf8');
+  const data = JSON.parse(raw);
+  registryCache = data.tools || [];
+  return registryCache;
+}
+
+/**
+ * Looks up a tool by name in the registry.
+ * Comparison is case-insensitive.
+ *
+ * @param {string} name - The tool name to look up (e.g. 'git', 'Node').
+ * @returns {object|null} The tool entry, or null if not found.
+ */
+function findTool(name) {
+  if (!name) {
+    return null;
+  }
+
+  const tools = loadRegistry();
+  const lower = name.toLowerCase();
+  return tools.find(t => t.name.toLowerCase() === lower) || null;
+}
+
+/**
+ * Loads the installer module for a given tool entry.
+ * Validates that the file exists and exports the required functions (isInstalled, install).
+ *
+ * @param {object} toolEntry - A tool entry from the registry (must have an `installer` field).
+ * @returns {object} The installer module (with isInstalled, install, etc.).
+ * @throws {Error} If the installer file is missing or doesn't export required functions.
+ */
+function loadInstaller(toolEntry) {
+  if (!toolEntry || !toolEntry.installer) {
+    throw new Error('Invalid tool entry: missing installer field.');
+  }
+
+  const installerPath = path.join(__dirname, '..', 'installers', toolEntry.installer);
+
+  if (!fs.existsSync(installerPath)) {
+    throw new Error(
+      `Installer file not found: ${toolEntry.installer}. ` +
+      `Expected at ${installerPath}`
+    );
+  }
+
+  const mod = require(installerPath);
+
+  if (typeof mod.isInstalled !== 'function') {
+    throw new Error(
+      `Installer "${toolEntry.installer}" does not export an isInstalled() function.`
+    );
+  }
+
+  if (typeof mod.install !== 'function') {
+    throw new Error(
+      `Installer "${toolEntry.installer}" does not export an install() function.`
+    );
+  }
+
+  return mod;
+}
+
+/**
+ * Resolves the full dependency chain for a tool, in installation order.
+ * If tool A depends on B, and B depends on C, returns ['C', 'B', 'A'].
+ * Detects circular dependencies and throws if found.
+ *
+ * @param {string} toolName - The name of the tool to resolve.
+ * @param {Set<string>} [visited] - Already-visited tool names (used internally for recursion).
+ * @param {string[]} [chain] - Current dependency chain (used internally for circular detection).
+ * @returns {string[]} Flat, ordered array of tool names to install.
+ * @throws {Error} If a circular dependency is detected or a tool is unknown.
+ */
+function resolveDependencies(toolName, visited = new Set(), chain = []) {
+  if (chain.includes(toolName)) {
+    throw new Error(
+      `Circular dependency detected: ${chain.join(' -> ')} -> ${toolName}`
+    );
+  }
+
+  if (visited.has(toolName)) {
+    return [];
+  }
+
+  const tool = findTool(toolName);
+  if (!tool) {
+    throw new Error(`Unknown tool: ${toolName}`);
+  }
+
+  chain.push(toolName);
+  visited.add(toolName);
+
+  const result = [];
+  for (const dep of tool.dependencies) {
+    result.push(...resolveDependencies(dep, visited, [...chain]));
+  }
+  result.push(toolName);
+  return result;
+}
+
+/**
+ * Checks if a tool is installed on the current system.
+ * Loads the tool's installer and calls its isInstalled() function.
+ *
+ * @param {string} toolName - The name of the tool to check.
+ * @param {object} context - The CLI context object.
+ * @returns {Promise<boolean>} true if the tool is installed.
+ * @throws {Error} If the tool is unknown or the installer can't be loaded.
+ */
+async function checkInstalled(toolName, context) {
+  const tool = findTool(toolName);
+  if (!tool) {
+    throw new Error(`Unknown tool: ${toolName}`);
+  }
+
+  const mod = loadInstaller(tool);
+  return mod.isInstalled(context);
+}
+
+/**
+ * Installs a tool, including any dependencies, using the platform-appropriate method.
+ *
+ * Steps:
+ * 1. Looks up the tool in the registry. Throws if not found.
+ * 2. Checks if the current platform is supported. Throws if not.
+ * 3. Resolves the dependency chain.
+ * 4. For each tool in the chain, checks if it's already installed.
+ *    If not, loads the installer and calls install(context).
+ * 5. Returns a summary object.
+ *
+ * @param {string} toolName - The name of the tool to install.
+ * @param {object} context - The CLI context object.
+ * @returns {Promise<{ tool: string, alreadyInstalled: boolean, dependenciesInstalled: string[], installed: boolean }>}
+ * @throws {Error} If the tool is unknown, unsupported on the current platform, or installation fails.
+ */
+async function installTool(toolName, context) {
+  const tool = findTool(toolName);
+  if (!tool) {
+    throw new Error(`Tool '${toolName}' not found in registry.`);
+  }
+
+  // Check platform support
+  const platformType = context.platform.detect().type;
+  if (!tool.platforms.includes(platformType)) {
+    throw new Error(
+      `Tool '${toolName}' is not supported on ${platformType}. ` +
+      `Supported platforms: ${tool.platforms.join(', ')}`
+    );
+  }
+
+  // Resolve dependencies
+  const chain = resolveDependencies(toolName);
+  const dependenciesInstalled = [];
+  let alreadyInstalled = false;
+  let installed = false;
+
+  for (const depName of chain) {
+    const depTool = findTool(depName);
+    const depMod = loadInstaller(depTool);
+    const isAlready = await depMod.isInstalled(context);
+
+    if (isAlready) {
+      if (depName === toolName) {
+        alreadyInstalled = true;
+      }
+      continue;
+    }
+
+    // Check platform support for the dependency too
+    if (!depTool.platforms.includes(platformType)) {
+      throw new Error(
+        `Dependency '${depName}' is not supported on ${platformType}. ` +
+        `Cannot install '${toolName}'.`
+      );
+    }
+
+    await depMod.install(context);
+
+    if (depName === toolName) {
+      installed = true;
+    } else {
+      dependenciesInstalled.push(depName);
+    }
+  }
+
+  return {
+    tool: toolName,
+    alreadyInstalled,
+    dependenciesInstalled,
+    installed,
+  };
+}
+
+module.exports = {
+  loadRegistry,
+  findTool,
+  loadInstaller,
+  resolveDependencies,
+  checkInstalled,
+  installTool,
+};

package/src/lib/output.js

@@ -0,0 +1,239 @@
+'use strict';
+
+/**
+ * Renders data as JSON. Pretty-prints for TTY callers, compact for machines.
+ * @param {*} data - The data to render.
+ * @param {string} caller - The caller context ('ai', 'ci', 'tty', 'pipe').
+ * @returns {string}
+ */
+function renderJson(data, caller) {
+  if (caller === 'tty') {
+    return JSON.stringify(data, null, 2);
+  }
+  return JSON.stringify(data);
+}
+
+/**
+ * Renders an array of objects as an aligned text table.
+ * @param {Array<object>|object} data - The data to render. Single objects are wrapped in an array.
+ * @returns {string}
+ */
+function renderTable(data) {
+  if (!Array.isArray(data)) data = [data];
+  if (data.length === 0) return '(no data)';
+
+  const keys = Object.keys(data[0]);
+
+  // Calculate column widths
+  const widths = {};
+  for (const key of keys) {
+    widths[key] = key.length;
+  }
+  for (const row of data) {
+    for (const key of keys) {
+      const val = String(row[key] === undefined ? '' : row[key]);
+      widths[key] = Math.max(widths[key], val.length);
+    }
+  }
+
+  // Build header
+  const header = keys.map(k => k.padEnd(widths[k])).join('  ');
+  const separator = keys.map(k => '-'.repeat(widths[k])).join('  ');
+
+  // Build rows
+  const rows = data.map(row => {
+    return keys.map(k => {
+      const val = String(row[k] === undefined ? '' : row[k]);
+      return val.padEnd(widths[k]);
+    }).join('  ');
+  });
+
+  return [header, separator, ...rows].join('\n');
+}
+
+/**
+ * Formats a value for YAML output.
+ * Quotes strings that could be misinterpreted by YAML parsers.
+ * @param {*} value - The value to format.
+ * @returns {string}
+ */
+function formatYamlValue(value) {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  if (typeof value === 'number') return String(value);
+  if (typeof value === 'string') {
+    if (/[:#\[\]{}&*!|>'"%@`]/.test(value) || value === '' || value === 'true' || value === 'false' || value === 'null') {
+      return `"${value.replace(/"/g, '\\"')}"`;
+    }
+    return value;
+  }
+  return String(value);
+}
+
+/**
+ * Renders data as simple YAML.
+ * Handles nested objects, arrays, strings, numbers, booleans, and null.
+ * @param {*} data - The data to render.
+ * @param {number} [indent=0] - Current indentation level.
+ * @returns {string}
+ */
+function renderYaml(data, indent = 0) {
+  const prefix = '  '.repeat(indent);
+
+  if (Array.isArray(data)) {
+    if (data.length === 0) return `${prefix}[]`;
+    return data.map(item => {
+      if (typeof item === 'object' && item !== null) {
+        const inner = renderYaml(item, indent + 1);
+        return `${prefix}-\n${inner}`;
+      }
+      return `${prefix}- ${formatYamlValue(item)}`;
+    }).join('\n');
+  }
+
+  if (typeof data === 'object' && data !== null) {
+    const entries = Object.entries(data);
+    if (entries.length === 0) return `${prefix}{}`;
+    return entries.map(([key, value]) => {
+      if (typeof value === 'object' && value !== null) {
+        return `${prefix}${key}:\n${renderYaml(value, indent + 1)}`;
+      }
+      return `${prefix}${key}: ${formatYamlValue(value)}`;
+    }).join('\n');
+  }
+
+  return `${prefix}${formatYamlValue(data)}`;
+}
+
+/**
+ * Renders an array of objects as CSV with proper escaping.
+ * @param {Array<object>|object} data - The data to render.
+ * @returns {string}
+ */
+function renderCsv(data) {
+  if (!Array.isArray(data)) data = [data];
+  if (data.length === 0) return '';
+
+  const keys = Object.keys(data[0]);
+
+  function escapeCsvField(value) {
+    const str = String(value === undefined || value === null ? '' : value);
+    if (str.includes(',') || str.includes('"') || str.includes('\n')) {
+      return `"${str.replace(/"/g, '""')}"`;
+    }
+    return str;
+  }
+
+  const header = keys.map(escapeCsvField).join(',');
+  const rows = data.map(row => {
+    return keys.map(k => escapeCsvField(row[k])).join(',');
+  });
+
+  return [header, ...rows].join('\n');
+}
+
+/**
+ * Renders data in the specified format.
+ * Falls back to JSON for unknown formats.
+ *
+ * @param {*} data - The data to render.
+ * @param {string} format - The output format ('json', 'table', 'yaml', 'csv').
+ * @param {string} [caller] - The caller context (affects JSON pretty-printing).
+ * @returns {string}
+ */
+function render(data, format, caller) {
+  switch (format) {
+    case 'json':
+      return renderJson(data, caller);
+    case 'table':
+      return renderTable(data);
+    case 'yaml':
+      return renderYaml(data);
+    case 'csv':
+      return renderCsv(data);
+    default:
+      return renderJson(data, caller);
+  }
+}
+
+/**
+ * Alias for render(). Some command stories use context.output.print(data).
+ */
+const print = render;
+
+/**
+ * Writes a plain text informational message to stdout.
+ * Does not go through the format rendering pipeline.
+ * @param {string} message - The message to write.
+ */
+function info(message) {
+  process.stdout.write(message + '\n');
+}
+
+/**
+ * Writes a plain text error message to stderr.
+ * Does not go through the format rendering pipeline.
+ * @param {string} message - The message to write.
+ */
+function error(message) {
+  process.stderr.write(message + '\n');
+}
+
+/**
+ * Renders an error object for output.
+ * Shows a human-readable message for table format, JSON for everything else.
+ *
+ * @param {object} errorObj - The error object (typically { error: { code, message, service } }).
+ * @param {string} format - The output format.
+ * @returns {string}
+ */
+function renderError(errorObj, format) {
+  if (format === 'table') {
+    const msg = errorObj.error ? errorObj.error.message : JSON.stringify(errorObj);
+    return `Error: ${msg}`;
+  }
+  return JSON.stringify(errorObj);
+}
+
+/**
+ * Creates a pre-configured formatter bound to a specific format and caller.
+ * Commands use this so they don't have to pass format/caller on every call.
+ *
+ * @param {{ format: string, caller: string }} context - The format and caller context.
+ * @returns {object} An object with out(), err(), render(), print(), info(), error(), renderError() methods.
+ */
+function createFormatter(context) {
+  const { format, caller } = context;
+
+  function _render(data) {
+    return render(data, format, caller);
+  }
+
+  function _info(message) {
+    process.stdout.write(message + '\n');
+  }
+
+  function _error(message) {
+    process.stderr.write(message + '\n');
+  }
+
+  return {
+    out(data) {
+      const output = render(data, format, caller);
+      process.stdout.write(output + '\n');
+    },
+    err(errorObj) {
+      const output = renderError(errorObj, format);
+      process.stderr.write(output + '\n');
+    },
+    render: _render,
+    print: _render,
+    info: _info,
+    error: _error,
+    renderError(errorObj) {
+      return renderError(errorObj, format);
+    },
+  };
+}
+
+module.exports = { render, print, renderError, createFormatter, info, error };

package/src/lib/platform.js

@@ -0,0 +1,112 @@
+'use strict';
+
+const fs = require('fs');
+
+/**
+ * Cached detection result. Set on first call to detect().
+ * The OS doesn't change while the process is running, so we only detect once.
+ * @type {{ type: string, arch: string, packageManager: string|null }|null}
+ */
+let cached = null;
+
+/**
+ * Lazy-loading lookup for platform helper modules.
+ * Each entry is a function that requires the platform file only when called.
+ * Other modules should never import platform files directly -- always go
+ * through platform.js using getHelper().
+ */
+const helpers = {
+  'macos': () => require('./platforms/macos'),
+  'ubuntu': () => require('./platforms/ubuntu'),
+  'raspbian': () => require('./platforms/raspbian'),
+  'amazon-linux': () => require('./platforms/amazon-linux'),
+  'windows': () => require('./platforms/windows'),
+  'gitbash': () => require('./platforms/gitbash'),
+};
+
+/**
+ * Reads /etc/os-release and returns the value of the ID= line.
+ * This tells us which Linux distro is running (e.g. 'ubuntu', 'raspbian', 'amzn').
+ * @returns {string|null} The distro ID in lowercase, or null if it can't be determined.
+ */
+function getLinuxDistroId() {
+  try {
+    const content = fs.readFileSync('/etc/os-release', 'utf8');
+    const match = content.match(/^ID=["']?([^"'\n]+)["']?/m);
+    return match ? match[1].toLowerCase() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Detects the current platform and returns an object describing the OS type,
+ * CPU architecture, and default package manager.
+ *
+ * Results are cached after the first call. Calling detect() multiple times
+ * returns the same object reference.
+ *
+ * @returns {{ type: string, arch: string, packageManager: string|null }}
+ *   - type: 'macos', 'ubuntu', 'raspbian', 'amazon-linux', 'windows', 'gitbash', or 'linux' (unknown)
+ *   - arch: CPU architecture string from process.arch (e.g. 'x64', 'arm64')
+ *   - packageManager: 'brew', 'apt', 'dnf', 'yum', 'choco', 'manual', or null
+ */
+function detect() {
+  if (cached) {
+    return cached;
+  }
+
+  const arch = process.arch;
+  let type = 'linux';
+  let packageManager = null;
+
+  if (process.platform === 'darwin') {
+    type = 'macos';
+    packageManager = 'brew';
+  } else if (process.platform === 'win32') {
+    // Git Bash sets the MSYSTEM environment variable (e.g. 'MINGW64').
+    // If it's set, we're running inside Git Bash. Otherwise, native Windows.
+    if (process.env.MSYSTEM) {
+      type = 'gitbash';
+      packageManager = 'manual';
+    } else {
+      type = 'windows';
+      packageManager = 'choco';
+    }
+  } else if (process.platform === 'linux') {
+    const distroId = getLinuxDistroId();
+
+    if (distroId === 'ubuntu') {
+      type = 'ubuntu';
+      packageManager = 'apt';
+    } else if (distroId === 'raspbian') {
+      type = 'raspbian';
+      packageManager = 'apt';
+    } else if (distroId === 'amzn') {
+      type = 'amazon-linux';
+      // Use dnf if available (AL2023+), otherwise fall back to yum
+      packageManager = fs.existsSync('/usr/bin/dnf') ? 'dnf' : 'yum';
+    } else {
+      // Unknown Linux distro -- don't crash, just report what we know
+      type = 'linux';
+      packageManager = null;
+    }
+  }
+
+  cached = { type, arch, packageManager };
+  return cached;
+}
+
+/**
+ * Returns the platform-specific helper module for the detected platform.
+ * The helper module exports functions like isInstalled(), getAppPaths(), etc.
+ *
+ * @returns {object|null} The helper module, or null if the platform has no helper.
+ */
+function getHelper() {
+  const { type } = detect();
+  const loader = helpers[type];
+  return loader ? loader() : null;
+}
+
+module.exports = { detect, getHelper };

package/src/lib/platforms/amazon-linux.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const fs = require('fs');
+const { execFileSync } = require('child_process');
+
+/**
+ * Platform name identifier.
+ * @type {string}
+ */
+const name = 'amazon-linux';
+
+/**
+ * Default package manager for Amazon Linux.
+ * Uses dnf on newer versions (AL2023+), falls back to yum on older versions.
+ * @type {string}
+ */
+const packageManager = fs.existsSync('/usr/bin/dnf') ? 'dnf' : 'yum';
+
+/**
+ * Checks if a binary is available on the system PATH.
+ * @param {string} binary - The name of the binary to look for (e.g. 'node', 'git').
+ * @returns {boolean} True if the binary exists on the PATH, false otherwise.
+ */
+function isInstalled(binary) {
+  try {
+    execFileSync('which', [binary], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Returns common application directories for Amazon Linux.
+ * @returns {string[]} Array of directory paths where applications are typically installed.
+ */
+function getAppPaths() {
+  return ['/usr/bin', '/usr/local/bin'];
+}
+
+module.exports = { name, packageManager, isInstalled, getAppPaths };

package/src/lib/platforms/gitbash.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const { execFileSync } = require('child_process');
+
+/**
+ * Platform name identifier.
+ * @type {string}
+ */
+const name = 'gitbash';
+
+/**
+ * Package manager for Git Bash.
+ * Git Bash doesn't have its own package manager, so this is 'manual'.
+ * @type {string}
+ */
+const packageManager = 'manual';
+
+/**
+ * Checks if a binary is available on the system PATH.
+ * Git Bash provides a "which" command, so we use that instead of "where".
+ * @param {string} binary - The name of the binary to look for (e.g. 'node', 'git').
+ * @returns {boolean} True if the binary exists on the PATH, false otherwise.
+ */
+function isInstalled(binary) {
+  try {
+    execFileSync('which', [binary], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Returns common application directories for Git Bash.
+ * Git Bash runs on top of Windows, so the paths are the same as Windows.
+ * @returns {string[]} Array of directory paths where applications are typically installed.
+ */
+function getAppPaths() {
+  return [
+    process.env.ProgramFiles,
+    process.env['ProgramFiles(x86)'],
+    process.env.LOCALAPPDATA,
+  ].filter(Boolean);
+}
+
+module.exports = { name, packageManager, isInstalled, getAppPaths };

package/src/lib/platforms/macos.js

@@ -0,0 +1,45 @@
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+/**
+ * Platform name identifier.
+ * @type {string}
+ */
+const name = 'macos';
+
+/**
+ * Default package manager for macOS.
+ * @type {string}
+ */
+const packageManager = 'brew';
+
+/**
+ * Checks if a binary is available on the system PATH.
+ * @param {string} binary - The name of the binary to look for (e.g. 'node', 'git').
+ * @returns {boolean} True if the binary exists on the PATH, false otherwise.
+ */
+function isInstalled(binary) {
+  try {
+    execFileSync('which', [binary], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Returns common application directories for macOS.
+ * @returns {string[]} Array of directory paths where applications are typically installed.
+ */
+function getAppPaths() {
+  return [
+    '/Applications',
+    '/usr/local/bin',
+    path.join(os.homedir(), 'Applications'),
+  ];
+}
+
+module.exports = { name, packageManager, isInstalled, getAppPaths };