@fredlackey/devutils 0.0.18 → 0.1.0

package/src/lib/errors.js

@@ -0,0 +1,114 @@
+'use strict';
+
+/**
+ * Creates a structured error object in the DevUtils standard format.
+ * Does not write anything or exit the process.
+ *
+ * @param {number} code - Numeric error code (400=bad input, 401=unauthorized, 404=not found, 500=internal).
+ * @param {string} message - Human-readable description of what went wrong.
+ * @param {string} [service='devutils'] - The service that generated the error.
+ * @returns {{ error: { code: number, message: string, service: string } }}
+ */
+function createError(code, message, service) {
+  return {
+    error: {
+      code: code,
+      message: message,
+      service: service || 'devutils',
+    },
+  };
+}
+
+/**
+ * Creates a structured error, writes it to stderr, and exits with code 1.
+ * Uses detect.js to determine the output format and output.js to render.
+ *
+ * Uses lazy require() to avoid circular dependency issues.
+ *
+ * @param {number} code - Numeric error code.
+ * @param {string} message - Human-readable error message.
+ * @param {string} [service] - The service that generated the error.
+ */
+function throwError(code, message, service) {
+  const err = createError(code, message, service);
+  const output = require('./output');
+  const detect = require('./detect');
+
+  const { format } = detect.detectOutputMode();
+  const formatted = output.renderError(err, format);
+  process.stderr.write(formatted + '\n');
+  process.exit(1);
+}
+
+/**
+ * Alias for throwError. Some command stories use context.errors.exit().
+ */
+const exit = throwError;
+
+/**
+ * Checks if an object matches the DevUtils error shape.
+ * Uses duck-typing: if it has error.code (number) and error.message (string), it's valid.
+ *
+ * @param {*} obj - The object to check.
+ * @returns {boolean}
+ */
+function isDevUtilsError(obj) {
+  if (obj === null || obj === undefined) return false;
+  if (typeof obj !== 'object') return false;
+  if (!obj.error) return false;
+  if (typeof obj.error !== 'object') return false;
+  if (typeof obj.error.code !== 'number') return false;
+  if (typeof obj.error.message !== 'string') return false;
+  return true;
+}
+
+/**
+ * Creates a 404 Not Found error.
+ * @param {string} message - What was not found.
+ * @param {string} [service] - The service that generated the error.
+ * @returns {{ error: { code: number, message: string, service: string } }}
+ */
+function notFound(message, service) {
+  return createError(404, message, service);
+}
+
+/**
+ * Creates a 400 Bad Input error.
+ * @param {string} message - What was wrong with the input.
+ * @param {string} [service] - The service that generated the error.
+ * @returns {{ error: { code: number, message: string, service: string } }}
+ */
+function badInput(message, service) {
+  return createError(400, message, service);
+}
+
+/**
+ * Creates a 500 Internal Error.
+ * @param {string} message - What went wrong internally.
+ * @param {string} [service] - The service that generated the error.
+ * @returns {{ error: { code: number, message: string, service: string } }}
+ */
+function internal(message, service) {
+  return createError(500, message, service);
+}
+
+/**
+ * Creates a 401 Unauthorized error.
+ * @param {string} message - Why access was denied.
+ * @param {string} [service] - The service that generated the error.
+ * @returns {{ error: { code: number, message: string, service: string } }}
+ */
+function unauthorized(message, service) {
+  return createError(401, message, service);
+}
+
+module.exports = {
+  createError,
+  throwError,
+  exit,
+  isDevUtilsError,
+  notFound,
+  badInput,
+  internal,
+  unauthorized,
+};

package/src/lib/github.js

@@ -0,0 +1,315 @@
+'use strict';
+
+const shell = require('./shell');
+
+/**
+ * Check if the GitHub CLI (gh) is installed on the system.
+ * @returns {boolean} True if gh is available on PATH
+ */
+function isInstalled() {
+  return shell.commandExists('gh');
+}
+
+/**
+ * Throw a clear error if gh is not installed.
+ * Call this at the top of any function that needs gh.
+ */
+function requireGh() {
+  if (!isInstalled()) {
+    throw new Error(
+      'GitHub CLI (gh) is not installed.\n' +
+      'Install it from: https://cli.github.com/\n' +
+      'Or with Homebrew: brew install gh'
+    );
+  }
+}
+
+/**
+ * Check if the user is authenticated with GitHub via gh.
+ * @returns {Promise<boolean>} True if authenticated
+ */
+async function isAuthenticated() {
+  requireGh();
+  const result = await shell.exec('gh auth status');
+  return result.exitCode === 0;
+}
+
+/**
+ * Get the authenticated username.
+ * @returns {Promise<string|null>} The GitHub username, or null if not authenticated
+ */
+async function getUsername() {
+  requireGh();
+  const result = await shell.exec('gh api user --jq .login');
+  if (result.exitCode !== 0) return null;
+  return result.stdout.trim() || null;
+}
+
+/**
+ * Create a new GitHub repository.
+ * @param {string} name - Repository name
+ * @param {boolean} isPrivate - Whether the repo should be private
+ * @returns {Promise<{ success: boolean, url: string|null, error: string|null }>}
+ */
+async function createRepo(name, isPrivate = true) {
+  requireGh();
+  const visibility = isPrivate ? '--private' : '--public';
+  const result = await shell.exec(`gh repo create "${name}" ${visibility} --yes`);
+
+  if (result.exitCode !== 0) {
+    return { success: false, url: null, error: result.stderr };
+  }
+
+  // gh repo create outputs the repo URL
+  return { success: true, url: result.stdout.trim(), error: null };
+}
+
+/**
+ * Clone a GitHub repository to a local directory.
+ * @param {string} url - Repository URL or owner/name
+ * @param {string} dest - Local destination directory
+ * @returns {Promise<{ success: boolean, error: string|null }>}
+ */
+async function cloneRepo(url, dest) {
+  requireGh();
+  const result = await shell.exec(`gh repo clone "${url}" "${dest}"`);
+
+  if (result.exitCode !== 0) {
+    return { success: false, error: result.stderr };
+  }
+
+  return { success: true, error: null };
+}
+
+/**
+ * Push local changes to the remote repository.
+ * Runs git add, commit, and push inside the given directory.
+ * If there are no changes, returns success without committing.
+ * @param {string} dest - Local repository directory
+ * @param {string} [message] - Commit message (defaults to 'DevUtils config update')
+ * @returns {Promise<{ success: boolean, error: string|null }>}
+ */
+async function pushRepo(dest, message = 'DevUtils config update') {
+  const escapedMessage = message.replace(/"/g, '\\"');
+
+  // Stage all changes
+  let result = await shell.exec('git add -A', { cwd: dest });
+  if (result.exitCode !== 0) {
+    return { success: false, error: 'git add failed: ' + result.stderr };
+  }
+
+  // Check if there is anything to commit
+  const status = await shell.exec('git status --porcelain', { cwd: dest });
+  if (!status.stdout.trim()) {
+    // Nothing to commit -- still a success, just nothing changed
+    return { success: true, error: null };
+  }
+
+  // Commit
+  result = await shell.exec(`git commit -m "${escapedMessage}"`, { cwd: dest });
+  if (result.exitCode !== 0) {
+    return { success: false, error: 'git commit failed: ' + result.stderr };
+  }
+
+  // Push
+  result = await shell.exec('git push', { cwd: dest });
+  if (result.exitCode !== 0) {
+    return { success: false, error: 'git push failed: ' + result.stderr };
+  }
+
+  return { success: true, error: null };
+}
+
+/**
+ * Pull the latest changes from the remote repository.
+ * @param {string} dest - Local repository directory
+ * @returns {Promise<{ success: boolean, error: string|null }>}
+ */
+async function pullRepo(dest) {
+  const result = await shell.exec('git pull', { cwd: dest });
+
+  if (result.exitCode !== 0) {
+    return { success: false, error: result.stderr };
+  }
+
+  return { success: true, error: null };
+}
+
+/**
+ * List the authenticated user's repositories.
+ * @param {number} [limit] - Maximum number of repos to return (default: 100)
+ * @returns {Promise<Array<{ name: string, url: string, private: boolean }>>}
+ */
+async function listRepos(limit = 100) {
+  requireGh();
+  const result = await shell.exec(
+    `gh repo list --json name,url,isPrivate --limit ${limit}`
+  );
+
+  if (result.exitCode !== 0) return [];
+
+  try {
+    const repos = JSON.parse(result.stdout);
+    return repos.map(r => ({
+      name: r.name,
+      url: r.url,
+      private: r.isPrivate
+    }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Create a new GitHub gist.
+ * Writes temp files to disk because gh gist create expects file paths.
+ * Temp files are cleaned up even if the command fails.
+ * @param {Object<string, string>} files - Object mapping filename to content
+ * @param {string} [description] - Gist description
+ * @param {boolean} [secret] - Whether the gist should be secret (default: true)
+ * @returns {Promise<{ success: boolean, id: string|null, url: string|null, error: string|null }>}
+ */
+async function createGist(files, description = '', secret = true) {
+  requireGh();
+
+  const fs = require('fs');
+  const path = require('path');
+  const nodeOs = require('os');
+
+  const tempDir = fs.mkdtempSync(path.join(nodeOs.tmpdir(), 'devutils-gist-'));
+  const tempFiles = [];
+
+  try {
+    for (const [filename, content] of Object.entries(files)) {
+      const filePath = path.join(tempDir, filename);
+      fs.writeFileSync(filePath, content);
+      tempFiles.push(filePath);
+    }
+
+    const secretFlag = secret ? '' : '--public';
+    const descFlag = description ? `--desc "${description.replace(/"/g, '\\"')}"` : '';
+    const fileArgs = tempFiles.map(f => `"${f}"`).join(' ');
+
+    const result = await shell.exec(
+      `gh gist create ${fileArgs} ${secretFlag} ${descFlag}`
+    );
+
+    if (result.exitCode !== 0) {
+      return { success: false, id: null, url: null, error: result.stderr };
+    }
+
+    // gh gist create outputs the gist URL
+    const url = result.stdout.trim();
+    // Extract the gist ID from the URL (last path segment)
+    const id = url.split('/').pop();
+
+    return { success: true, id, url, error: null };
+  } finally {
+    // Clean up temp files
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Get the contents of a gist by ID.
+ * Uses gh api with a jq filter to extract file contents as structured JSON.
+ * @param {string} id - The gist ID
+ * @returns {Promise<{ success: boolean, files: Object<string, string>|null, error: string|null }>}
+ */
+async function getGist(id) {
+  requireGh();
+  const result = await shell.exec(
+    `gh api gists/${id} --jq '.files | to_entries | map({key: .key, value: .value.content}) | from_entries'`
+  );
+
+  if (result.exitCode !== 0) {
+    return { success: false, files: null, error: result.stderr };
+  }
+
+  try {
+    const files = JSON.parse(result.stdout);
+    return { success: true, files, error: null };
+  } catch {
+    return { success: false, files: null, error: 'Failed to parse gist content' };
+  }
+}
+
+/**
+ * Update an existing gist with new file contents.
+ * Updates each file sequentially using gh gist edit --add.
+ * @param {string} id - The gist ID
+ * @param {Object<string, string>} files - Object mapping filename to new content
+ * @returns {Promise<{ success: boolean, error: string|null }>}
+ */
+async function updateGist(id, files) {
+  requireGh();
+
+  const fs = require('fs');
+  const path = require('path');
+  const nodeOs = require('os');
+
+  const tempDir = fs.mkdtempSync(path.join(nodeOs.tmpdir(), 'devutils-gist-'));
+
+  try {
+    // Write each file to disk and update via gh gist edit
+    for (const [filename, content] of Object.entries(files)) {
+      const filePath = path.join(tempDir, filename);
+      fs.writeFileSync(filePath, content);
+
+      const result = await shell.exec(
+        `gh gist edit ${id} --add "${filePath}"`
+      );
+
+      if (result.exitCode !== 0) {
+        return { success: false, error: `Failed to update ${filename}: ${result.stderr}` };
+      }
+    }
+
+    return { success: true, error: null };
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * List the authenticated user's gists.
+ * Parses tab-separated output from gh gist list.
+ * @param {number} [limit] - Maximum number of gists to return (default: 30)
+ * @returns {Promise<Array<{ id: string, description: string, public: boolean, files: string[] }>>}
+ */
+async function listGists(limit = 30) {
+  requireGh();
+  const result = await shell.exec(
+    `gh gist list --limit ${limit}`
+  );
+
+  if (result.exitCode !== 0) return [];
+
+  // gh gist list outputs a tab-separated table
+  // Columns: ID, Description, Files, Visibility, Updated
+  const lines = result.stdout.split('\n').filter(Boolean);
+  return lines.map(line => {
+    const parts = line.split('\t');
+    return {
+      id: parts[0] || '',
+      description: parts[1] || '',
+      public: (parts[3] || '').trim() === 'public',
+      files: (parts[2] || '').split(',').map(f => f.trim()).filter(Boolean)
+    };
+  });
+}
+
+module.exports = {
+  isInstalled,
+  isAuthenticated,
+  getUsername,
+  createRepo,
+  cloneRepo,
+  pushRepo,
+  pullRepo,
+  listRepos,
+  createGist,
+  getGist,
+  updateGist,
+  listGists
+};

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