@fredlackey/devutils 0.0.18 → 0.1.0

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 };

package/src/lib/platforms/raspbian.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const { execFileSync } = require('child_process');
+
+/**
+ * Platform name identifier.
+ * @type {string}
+ */
+const name = 'raspbian';
+
+/**
+ * Default package manager for Raspberry Pi OS (Raspbian).
+ * Raspbian is Debian-based, so it uses apt just like Ubuntu.
+ * @type {string}
+ */
+const packageManager = 'apt';
+
+/**
+ * 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 Raspberry Pi OS.
+ * Same as Ubuntu since Raspbian is Debian-based.
+ * @returns {string[]} Array of directory paths where applications are typically installed.
+ */
+function getAppPaths() {
+  return ['/usr/bin', '/usr/local/bin', '/snap/bin'];
+}
+
+module.exports = { name, packageManager, isInstalled, getAppPaths };

package/src/lib/platforms/ubuntu.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const { execFileSync } = require('child_process');
+
+/**
+ * Platform name identifier.
+ * @type {string}
+ */
+const name = 'ubuntu';
+
+/**
+ * Default package manager for Ubuntu.
+ * @type {string}
+ */
+const packageManager = 'apt';
+
+/**
+ * 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 Ubuntu.
+ * @returns {string[]} Array of directory paths where applications are typically installed.
+ */
+function getAppPaths() {
+  return ['/usr/bin', '/usr/local/bin', '/snap/bin'];
+}
+
+module.exports = { name, packageManager, isInstalled, getAppPaths };

package/src/lib/platforms/windows.js

@@ -0,0 +1,45 @@
+'use strict';
+
+const { execFileSync } = require('child_process');
+
+/**
+ * Platform name identifier.
+ * @type {string}
+ */
+const name = 'windows';
+
+/**
+ * Default package manager for Windows.
+ * @type {string}
+ */
+const packageManager = 'choco';
+
+/**
+ * Checks if a binary is available on the system PATH.
+ * Windows uses "where" instead of "which" for binary lookup.
+ * @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('where', [binary], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Returns common application directories for Windows.
+ * Filters out undefined entries in case environment variables aren't set.
+ * @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 };