@fredlackey/devutils 0.0.19 → 0.1.0

package/src/commands/update.js

@@ -0,0 +1,113 @@
+'use strict';
+
+const shell = require('../lib/shell');
+
+const meta = {
+  description: 'Self-update to the latest published version.',
+  arguments: [],
+  flags: [
+    { name: 'check', description: 'Check for updates without installing' },
+  ],
+};
+
+/**
+ * Get the current installed version from package.json.
+ * @returns {string}
+ */
+function getCurrentVersion() {
+  const pkg = require('../../package.json');
+  return pkg.version;
+}
+
+/**
+ * Get the latest version from the npm registry.
+ * @returns {Promise<string|null>}
+ */
+async function getLatestVersion() {
+  const result = await shell.exec('npm view @fredlackey/devutils version');
+  if (result.exitCode !== 0) return null;
+  return result.stdout.trim() || null;
+}
+
+/**
+ * Compare two semver strings. Returns true if latest is newer than current.
+ * @param {string} latest
+ * @param {string} current
+ * @returns {boolean}
+ */
+function isNewer(latest, current) {
+  const l = latest.split('.').map(Number);
+  const c = current.split('.').map(Number);
+  for (let i = 0; i < Math.max(l.length, c.length); i++) {
+    const lv = l[i] || 0;
+    const cv = c[i] || 0;
+    if (lv > cv) return true;
+    if (lv < cv) return false;
+  }
+  return false;
+}
+
+async function run(args, context) {
+  if (!shell.commandExists('npm')) {
+    context.errors.throwError(500, 'npm is not available on this system. Install Node.js and npm first.', 'update');
+    return;
+  }
+
+  const current = getCurrentVersion();
+  context.output.info(`Current version: ${current}`);
+  context.output.info('Checking for updates...');
+
+  const latest = await getLatestVersion();
+  if (!latest) {
+    context.errors.throwError(500, 'Could not reach the npm registry. Check your network connection.', 'update');
+    return;
+  }
+
+  if (!isNewer(latest, current)) {
+    const result = {
+      current,
+      latest,
+      updateAvailable: false,
+      message: `Already on the latest version (${current}).`,
+    };
+    context.output.out(result);
+    return;
+  }
+
+  // Update available
+  if (args.flags.check) {
+    const result = {
+      current,
+      latest,
+      updateAvailable: true,
+      message: `Update available: ${current} -> ${latest}. Run "dev update" to install.`,
+    };
+    context.output.out(result);
+    return;
+  }
+
+  // Perform the update
+  context.output.info(`Updating from ${current} to ${latest}...`);
+
+  const installResult = await shell.exec('npm install -g @fredlackey/devutils@latest');
+
+  if (installResult.exitCode !== 0) {
+    const msg = installResult.stderr || '';
+    if (msg.includes('EACCES') || msg.includes('permission')) {
+      context.errors.throwError(403, 'Permission denied. Try running with sudo: sudo dev update', 'update');
+      return;
+    }
+    context.errors.throwError(500, `Update failed: ${msg}`, 'update');
+    return;
+  }
+
+  const result = {
+    previous: current,
+    current: latest,
+    updateAvailable: false,
+    message: `Updated to ${latest}. Restart your terminal to use the new version.`,
+  };
+  context.output.out(result);
+}
+
+module.exports = { meta, run };

package/src/commands/util/add.js

@@ -0,0 +1,151 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const meta = {
+  description: 'Register a custom utility by name and source path. Copies the script into ~/.devutils/utils/.',
+  arguments: [
+    { name: 'name', required: true, description: 'Name for the utility (used in dev util run <name>)' },
+    { name: 'path', required: true, description: 'Path to the script file or directory to register' },
+  ],
+  flags: [
+    { name: 'link', description: 'Create a symlink instead of copying (for active development)' },
+  ],
+};
+
+/**
+ * Recursively copy a directory.
+ * @param {string} src - Source directory path.
+ * @param {string} dest - Destination directory path.
+ */
+function copyDirectorySync(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirectorySync(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+async function run(args, context) {
+  const name = args.positional[0];
+  const sourcePath = args.positional[1];
+
+  if (!name || !sourcePath) {
+    context.errors.throwError(400, 'Usage: dev util add <name> <path>', 'util');
+    return;
+  }
+
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) {
+    context.output.error('Utility names must be lowercase letters, numbers, and hyphens only.');
+    context.output.info('Example: my-script, git-helper, deploy-2');
+    return;
+  }
+
+  // Check for name conflicts with built-in utilities
+  const builtInRegistry = require('../../utils/registry.json');
+  const isBuiltIn = (builtInRegistry.utilities || []).some(u => u.name === name);
+  if (isBuiltIn) {
+    context.output.error(`"${name}" is a built-in utility and cannot be overridden.`);
+    return;
+  }
+
+  const customDir = path.join(os.homedir(), '.devutils', 'utils');
+  const existingFolder = path.join(customDir, name);
+  const existingFile = path.join(customDir, name + '.js');
+  if (fs.existsSync(existingFolder) || fs.existsSync(existingFile)) {
+    context.output.error(`A custom utility named "${name}" already exists.`);
+    context.output.info('Remove it first with: dev util remove ' + name);
+    return;
+  }
+
+  // Validate the source path
+  const resolvedSource = path.resolve(sourcePath);
+  if (!fs.existsSync(resolvedSource)) {
+    context.output.error(`Source path not found: ${resolvedSource}`);
+    return;
+  }
+
+  const stat = fs.statSync(resolvedSource);
+  let entryPoint;
+
+  if (stat.isDirectory()) {
+    entryPoint = path.join(resolvedSource, 'index.js');
+    if (!fs.existsSync(entryPoint)) {
+      context.output.error('Directory does not contain an index.js file.');
+      return;
+    }
+  } else if (stat.isFile() && resolvedSource.endsWith('.js')) {
+    entryPoint = resolvedSource;
+  } else {
+    context.output.error('Source must be a .js file or a directory containing index.js.');
+    return;
+  }
+
+  // Verify it exports a run function
+  try {
+    const mod = require(entryPoint);
+    if (typeof mod.run !== 'function') {
+      context.output.error('The source file must export a run() function.');
+      return;
+    }
+  } catch (err) {
+    context.output.error(`Failed to load source file: ${err.message}`);
+    return;
+  }
+
+  // Copy or link the utility
+  fs.mkdirSync(customDir, { recursive: true });
+
+  if (args.flags.link) {
+    const linkTarget = stat.isDirectory()
+      ? path.join(customDir, name)
+      : path.join(customDir, name + '.js');
+    fs.symlinkSync(resolvedSource, linkTarget);
+  } else {
+    if (stat.isDirectory()) {
+      copyDirectorySync(resolvedSource, path.join(customDir, name));
+    } else {
+      fs.copyFileSync(resolvedSource, path.join(customDir, name + '.js'));
+    }
+  }
+
+  // Update the custom registry
+  const registryPath = path.join(customDir, 'registry.json');
+  let registry = { utilities: [] };
+  if (fs.existsSync(registryPath)) {
+    try {
+      registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+    } catch {
+      registry = { utilities: [] };
+    }
+  }
+
+  const mod = require(entryPoint);
+  const utilMeta = mod.meta || {};
+
+  registry.utilities.push({
+    name: name,
+    description: utilMeta.description || '',
+    type: 'custom',
+    platforms: utilMeta.platforms || [],
+    arguments: utilMeta.arguments || [],
+    flags: utilMeta.flags || [],
+    source: resolvedSource,
+    linked: !!args.flags.link,
+  });
+
+  fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2) + '\n');
+
+  context.output.info(`Utility "${name}" registered successfully.`);
+  context.output.info(`Run it with: dev util run ${name}`);
+}
+
+module.exports = { meta, run };

package/src/commands/util/index.js

@@ -0,0 +1,15 @@
+/**
+ * Util service registration.
+ * Complex utility functions (platform-aware).
+ */
+module.exports = {
+  name: 'util',
+  description: 'Complex utility functions (platform-aware)',
+  commands: {
+    run:    () => require('./run'),
+    list:   () => require('./list'),
+    show:   () => require('./show'),
+    add:    () => require('./add'),
+    remove: () => require('./remove'),
+  }
+};

package/src/commands/util/list.js

@@ -0,0 +1,97 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const meta = {
+  description: 'List available utilities. Use flags to filter by source.',
+  arguments: [],
+  flags: [
+    { name: 'built-in', description: 'Show only built-in utilities' },
+    { name: 'custom', description: 'Show only user-added utilities' },
+  ],
+};
+
+/**
+ * Load custom utilities from ~/.devutils/utils/.
+ * Checks for a registry.json first; falls back to scanning directories.
+ *
+ * @returns {Array<object>} Array of utility metadata objects.
+ */
+function loadCustomUtilities() {
+  const customDir = path.join(os.homedir(), '.devutils', 'utils');
+  if (!fs.existsSync(customDir)) {
+    return [];
+  }
+
+  const registryPath = path.join(customDir, 'registry.json');
+  if (fs.existsSync(registryPath)) {
+    try {
+      const data = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+      return (data.utilities || []).map(u => ({ ...u, type: 'custom' }));
+    } catch {
+      // Fall through to directory scan
+    }
+  }
+
+  // Fallback: scan directories for index.js with meta exports
+  const entries = fs.readdirSync(customDir, { withFileTypes: true });
+  const utilities = [];
+
+  for (const entry of entries) {
+    if (entry.name === 'registry.json') continue;
+
+    let indexPath;
+    if (entry.isDirectory()) {
+      indexPath = path.join(customDir, entry.name, 'index.js');
+    } else if (entry.isFile() && entry.name.endsWith('.js')) {
+      indexPath = path.join(customDir, entry.name);
+    }
+
+    if (indexPath && fs.existsSync(indexPath)) {
+      try {
+        const mod = require(indexPath);
+        if (mod.meta) {
+          utilities.push({
+            name: mod.meta.name || entry.name.replace(/\.js$/, ''),
+            description: mod.meta.description || '',
+            type: 'custom',
+          });
+        }
+      } catch {
+        // Skip utilities that fail to load
+      }
+    }
+  }
+
+  return utilities;
+}
+
+async function run(args, context) {
+  const builtInRegistry = require('../../utils/registry.json');
+  const results = [];
+
+  if (!args.flags.custom) {
+    for (const util of builtInRegistry.utilities || []) {
+      results.push({ Name: util.name, Description: util.description, Type: 'built-in' });
+    }
+  }
+
+  if (!args.flags['built-in']) {
+    const custom = loadCustomUtilities();
+    for (const util of custom) {
+      results.push({ Name: util.name, Description: util.description || '', Type: 'custom' });
+    }
+  }
+
+  if (results.length === 0) {
+    context.output.info('No utilities found.');
+    return;
+  }
+
+  context.output.out(results);
+  context.output.info(`\n${results.length} ${results.length === 1 ? 'utility' : 'utilities'} available.`);
+}
+
+module.exports = { meta, run };

package/src/commands/util/remove.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const meta = {
+  description: 'Unregister a custom utility. Built-in utilities cannot be removed.',
+  arguments: [
+    { name: 'name', required: true, description: 'Name of the custom utility to remove' },
+  ],
+  flags: [
+    { name: 'confirm', description: 'Skip the confirmation prompt' },
+  ],
+};
+
+async function run(args, context) {
+  const name = args.positional[0];
+  if (!name) {
+    context.errors.throwError(400, 'Usage: dev util remove <name>', 'util');
+    return;
+  }
+
+  // Reject removal of built-in utilities
+  const builtInRegistry = require('../../utils/registry.json');
+  const isBuiltIn = (builtInRegistry.utilities || []).some(u => u.name === name);
+  if (isBuiltIn) {
+    context.output.error(`"${name}" is a built-in utility and cannot be removed.`);
+    return;
+  }
+
+  const customDir = path.join(os.homedir(), '.devutils', 'utils');
+  const folderPath = path.join(customDir, name);
+  const filePath = path.join(customDir, name + '.js');
+
+  const exists = fs.existsSync(folderPath) || fs.existsSync(filePath);
+  if (!exists) {
+    context.output.error(`Custom utility "${name}" not found.`);
+    return;
+  }
+
+  // Ask for confirmation unless --confirm is set
+  if (!args.flags.confirm) {
+    const ok = await context.prompt.confirm(
+      `Remove custom utility "${name}"? This will delete the files.`,
+      false
+    );
+    if (!ok) {
+      context.output.info('Cancelled.');
+      return;
+    }
+  }
+
+  // Delete the files
+  if (fs.existsSync(folderPath)) {
+    fs.rmSync(folderPath, { recursive: true, force: true });
+  } else if (fs.existsSync(filePath)) {
+    fs.unlinkSync(filePath);
+  }
+
+  // Update the custom registry
+  const registryPath = path.join(customDir, 'registry.json');
+  if (fs.existsSync(registryPath)) {
+    try {
+      const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+      registry.utilities = (registry.utilities || []).filter(u => u.name !== name);
+      fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2) + '\n');
+    } catch {
+      // Registry corrupted, skip update
+    }
+  }
+
+  context.output.info(`Utility "${name}" removed.`);
+}
+
+module.exports = { meta, run };

package/src/commands/util/run.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const builtInDir = path.join(__dirname, '..', '..', 'utils');
+const customDir = path.join(os.homedir(), '.devutils', 'utils');
+
+const meta = {
+  description: 'Execute a utility by name. Extra arguments are passed through to the utility.',
+  arguments: [
+    { name: 'name', required: true, description: 'Name of the utility to run' },
+  ],
+  flags: [],
+};
+
+/**
+ * Find a utility by name, checking built-in first, then custom.
+ * Supports both folder-based (name/index.js) and single-file (name.js) utilities.
+ *
+ * @param {string} name - The utility name.
+ * @returns {{ path: string, type: string }|null} The utility location, or null if not found.
+ */
+function findUtility(name) {
+  // Check built-in: folder with index.js
+  const builtInFolder = path.join(builtInDir, name, 'index.js');
+  if (fs.existsSync(builtInFolder)) {
+    return { path: builtInFolder, type: 'built-in' };
+  }
+
+  // Check built-in: single file
+  const builtInFile = path.join(builtInDir, name + '.js');
+  if (fs.existsSync(builtInFile)) {
+    return { path: builtInFile, type: 'built-in' };
+  }
+
+  // Check custom: folder with index.js
+  const customFolder = path.join(customDir, name, 'index.js');
+  if (fs.existsSync(customFolder)) {
+    return { path: customFolder, type: 'custom' };
+  }
+
+  // Check custom: single file
+  const customFile = path.join(customDir, name + '.js');
+  if (fs.existsSync(customFile)) {
+    return { path: customFile, type: 'custom' };
+  }
+
+  return null;
+}
+
+async function run(args, context) {
+  const name = args.positional[0];
+  if (!name) {
+    context.errors.throwError(400, 'Usage: dev util run <name> [args...]', 'util');
+    return;
+  }
+
+  const utilArgs = args.positional.slice(1);
+
+  const util = findUtility(name);
+  if (!util) {
+    context.output.error(`Utility "${name}" not found.`);
+    context.output.info('Run "dev util list" to see available utilities.');
+    return;
+  }
+
+  const utilModule = require(util.path);
+
+  if (typeof utilModule.run !== 'function') {
+    context.output.error(`Utility "${name}" does not export a run() function.`);
+    return;
+  }
+
+  await utilModule.run(utilArgs, context);
+}
+
+module.exports = { meta, run, findUtility };

package/src/commands/util/show.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const meta = {
+  description: 'Show details, supported platforms, and accepted arguments for a utility.',
+  arguments: [
+    { name: 'name', required: true, description: 'Name of the utility to inspect' },
+  ],
+  flags: [],
+};
+
+async function run(args, context) {
+  const name = args.positional[0];
+  if (!name) {
+    context.errors.throwError(400, 'Usage: dev util show <name>', 'util');
+    return;
+  }
+
+  const { findUtility } = require('./run');
+  const util = findUtility(name);
+
+  if (!util) {
+    context.errors.throwError(404, `Utility "${name}" not found. Run "dev util list" to see available utilities.`, 'util');
+    return;
+  }
+
+  const utilModule = require(util.path);
+  const utilMeta = utilModule.meta || {};
+
+  const info = {
+    name: utilMeta.name || name,
+    description: utilMeta.description || '(no description)',
+    type: util.type,
+    platforms: utilMeta.platforms || [],
+    arguments: utilMeta.arguments || [],
+    flags: utilMeta.flags || [],
+  };
+
+  if (context.flags.format === 'json') {
+    context.output.out(info);
+    return;
+  }
+
+  context.output.info(`Utility: ${info.name}`);
+  context.output.info('');
+  context.output.info(`  Description: ${info.description}`);
+  context.output.info(`  Type:        ${info.type}`);
+  context.output.info(`  Platforms:   ${info.platforms.length > 0 ? info.platforms.join(', ') : '(all)'}`);
+
+  if (info.arguments.length > 0) {
+    context.output.info('');
+    context.output.info('  Arguments:');
+    for (const arg of info.arguments) {
+      const req = arg.required ? '(required)' : '(optional)';
+      context.output.info(`    ${arg.name} ${req} - ${arg.description || ''}`);
+    }
+  }
+
+  if (info.flags.length > 0) {
+    context.output.info('');
+    context.output.info('  Flags:');
+    for (const flag of info.flags) {
+      context.output.info(`    --${flag.name} - ${flag.description || ''}`);
+    }
+  }
+}
+
+module.exports = { meta, run };

package/src/commands/version.js

@@ -0,0 +1,33 @@
+'use strict';
+
+/**
+ * version command.
+ * Reads the version string from package.json and prints it.
+ * When format is json, outputs { version: "x.y.z" }.
+ * When table/tty, outputs just the version string.
+ */
+
+const meta = {
+  description: 'Show the current installed version',
+  arguments: [],
+  flags: []
+};
+
+/**
+ * Prints the current DevUtils CLI version.
+ *
+ * @param {object} args - Parsed command arguments (none expected).
+ * @param {object} context - The CLI context object with output, flags, etc.
+ */
+async function run(args, context) {
+  const pkg = require('../../package.json');
+  const version = pkg.version;
+
+  if (context.flags.format === 'json') {
+    context.output.out({ version });
+  } else {
+    context.output.info(version);
+  }
+}
+
+module.exports = { meta, run };