@fredlackey/devutils 0.0.19 → 0.1.0

package/src/commands/auth/services.js

@@ -0,0 +1,169 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const AUTH_DIR = path.join(os.homedir(), '.devutils', 'auth');
+const CLIENTS_DIR = path.join(AUTH_DIR, 'clients');
+
+/**
+ * Registry of all supported authentication services.
+ * Each entry describes how the service authenticates and what credentials it needs.
+ *
+ * - OAuth services use a browser-based consent flow (e.g., Google).
+ * - API key services prompt the user for static credentials (e.g., AWS, Cloudflare).
+ *
+ * This object is the single source of truth for all auth commands (login, logout,
+ * list, status, refresh). Add new services here -- all commands will pick them up.
+ */
+const AUTH_SERVICES = {
+  google: {
+    type: 'oauth',
+    authUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+    tokenUrl: 'https://oauth2.googleapis.com/token',
+    revokeUrl: 'https://oauth2.googleapis.com/revoke',
+    defaultScopes: ['openid', 'email', 'profile'],
+    clientFile: 'google.json'
+  },
+  aws: {
+    type: 'api-key',
+    fields: ['accessKeyId', 'secretAccessKey', 'region'],
+    fieldLabels: ['AWS Access Key ID', 'AWS Secret Access Key', 'Default Region']
+  },
+  cloudflare: {
+    type: 'api-key',
+    fields: ['apiToken'],
+    fieldLabels: ['Cloudflare API Token']
+  },
+  dokploy: {
+    type: 'api-key',
+    fields: ['apiUrl', 'apiToken'],
+    fieldLabels: ['Dokploy API URL', 'Dokploy API Token']
+  },
+  namecheap: {
+    type: 'api-key',
+    fields: ['apiUser', 'apiKey', 'clientIp'],
+    fieldLabels: ['Namecheap API User', 'API Key', 'Whitelisted Client IP']
+  },
+  flowroute: {
+    type: 'api-key',
+    fields: ['accessKey', 'secretKey'],
+    fieldLabels: ['Flowroute Access Key', 'Secret Key']
+  },
+  mailu: {
+    type: 'api-key',
+    fields: ['apiUrl', 'apiKey'],
+    fieldLabels: ['Mailu API URL', 'API Key']
+  }
+};
+
+/**
+ * Read a credential file from ~/.devutils/auth/<service>.json.
+ * Returns the parsed JSON content, or null if the file is missing or invalid.
+ *
+ * @param {string} service - The service name (e.g., 'google', 'aws').
+ * @returns {object|null} The parsed credential data, or null.
+ */
+function readCredential(service) {
+  const filePath = path.join(AUTH_DIR, `${service}.json`);
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Determine the status of a credential.
+ * - 'missing' means no credential file exists.
+ * - 'valid' means the credential exists and (for OAuth) is not expired.
+ * - 'expired' means the OAuth token's expiresAt is in the past.
+ * - 'unknown' means the credential exists but can't be evaluated.
+ *
+ * @param {object|null} credential - The parsed credential data from readCredential().
+ * @returns {string} One of 'missing', 'valid', 'expired', 'unknown'.
+ */
+function getTokenStatus(credential) {
+  if (!credential) return 'missing';
+  if (credential.type === 'api-key') return 'valid';
+  if (credential.type === 'oauth') {
+    if (!credential.expiresAt) return 'unknown';
+    return new Date(credential.expiresAt) > new Date() ? 'valid' : 'expired';
+  }
+  return 'unknown';
+}
+
+/**
+ * Check if a field name looks like it holds sensitive data.
+ * Fields with "secret", "key", "token", or "password" in the name
+ * should be masked in output and use password-style input.
+ *
+ * @param {string} fieldName - The field name to check.
+ * @returns {boolean} True if the field is sensitive.
+ */
+function isSensitiveField(fieldName) {
+  const lower = fieldName.toLowerCase();
+  return lower.includes('secret') ||
+    lower.includes('key') ||
+    lower.includes('token') ||
+    lower.includes('password');
+}
+
+/**
+ * Mask a sensitive value for display.
+ * Shows the first 4 and last 3 characters for partially-sensitive values,
+ * or '****' for fully-sensitive ones.
+ *
+ * @param {string} value - The value to mask.
+ * @param {boolean} fullMask - If true, mask the entire value with '****'.
+ * @returns {string} The masked value.
+ */
+function maskValue(value, fullMask) {
+  if (!value || typeof value !== 'string') return '****';
+  if (fullMask) return '****';
+  if (value.length <= 8) return '****';
+  return value.substring(0, 4) + '...' + value.substring(value.length - 3);
+}
+
+/**
+ * Format a time difference as a human-readable string.
+ * Handles both future ("47 minutes") and past ("expired 12 minutes ago") times.
+ *
+ * @param {Date} target - The target time (e.g., expiresAt).
+ * @param {Date} now - The current time.
+ * @returns {string} Human-readable duration string.
+ */
+function formatTimeDiff(target, now) {
+  const diffMs = target.getTime() - now.getTime();
+  const absDiffMs = Math.abs(diffMs);
+  const isPast = diffMs < 0;
+
+  let value;
+  if (absDiffMs < 60000) {
+    value = 'less than a minute';
+  } else if (absDiffMs < 3600000) {
+    const mins = Math.floor(absDiffMs / 60000);
+    value = `${mins} minute${mins === 1 ? '' : 's'}`;
+  } else if (absDiffMs < 86400000) {
+    const hours = Math.floor(absDiffMs / 3600000);
+    value = `${hours} hour${hours === 1 ? '' : 's'}`;
+  } else {
+    const days = Math.floor(absDiffMs / 86400000);
+    value = `${days} day${days === 1 ? '' : 's'}`;
+  }
+
+  return isPast ? `expired ${value} ago` : value;
+}
+
+module.exports = {
+  AUTH_SERVICES,
+  AUTH_DIR,
+  CLIENTS_DIR,
+  readCredential,
+  getTokenStatus,
+  isSensitiveField,
+  maskValue,
+  formatTimeDiff
+};

package/src/commands/auth/status.js

@@ -0,0 +1,104 @@
+'use strict';
+
+const {
+  AUTH_SERVICES,
+  readCredential,
+  getTokenStatus,
+  isSensitiveField,
+  maskValue,
+  formatTimeDiff
+} = require('./services');
+
+const meta = {
+  description: 'Show detailed auth state for one service',
+  arguments: [
+    { name: 'service', description: 'Service name to check', required: true }
+  ],
+  flags: []
+};
+
+/**
+ * Run the auth status command.
+ * Shows detailed credential information for a single service, including
+ * scopes and expiry for OAuth, or masked field values for API key services.
+ *
+ * @param {object} args - Parsed CLI arguments (positional, flags).
+ * @param {object} context - CLI context (output, prompt, errors).
+ */
+async function run(args, context) {
+  const service = args.positional[0];
+
+  if (!service) {
+    context.errors.throwError(400, 'Missing required argument: <service>. Example: dev auth status google', 'auth');
+    return;
+  }
+
+  const serviceConfig = AUTH_SERVICES[service];
+  if (!serviceConfig) {
+    const supported = Object.keys(AUTH_SERVICES).join(', ');
+    context.errors.throwError(400, `Unknown service '${service}'. Supported services: ${supported}`, 'auth');
+    return;
+  }
+
+  const credential = readCredential(service);
+  if (!credential) {
+    context.output.info(`Not authenticated with ${service}. Run "dev auth login ${service}" to connect.`);
+    return;
+  }
+
+  const status = getTokenStatus(credential);
+
+  if (credential.type === 'oauth') {
+    // Build detailed OAuth status
+    const now = new Date();
+    let expiresIn = null;
+
+    if (credential.expiresAt) {
+      expiresIn = formatTimeDiff(new Date(credential.expiresAt), now);
+    }
+
+    const result = {
+      service: service,
+      type: 'oauth',
+      status: status,
+      scopes: credential.scopes || [],
+      expiresAt: credential.expiresAt || '-',
+      expiresIn: expiresIn || '-',
+      authenticatedAt: credential.authenticatedAt || '-',
+      hasRefreshToken: !!credential.refreshToken
+    };
+
+    context.output.out(result);
+  } else if (credential.type === 'api-key') {
+    // Build detailed API key status with masked values
+    const fields = credential.credentials ? Object.keys(credential.credentials) : [];
+    const maskedValues = {};
+
+    for (const field of fields) {
+      const val = credential.credentials[field];
+      if (isSensitiveField(field)) {
+        // Fully mask sensitive fields
+        maskedValues[field] = maskValue(val, true);
+      } else {
+        // Show non-sensitive values in full (like region)
+        maskedValues[field] = val;
+      }
+    }
+
+    const result = {
+      service: service,
+      type: 'api-key',
+      status: status,
+      fields: fields,
+      maskedValues: maskedValues,
+      authenticatedAt: credential.authenticatedAt || '-'
+    };
+
+    context.output.out(result);
+  } else {
+    // Unknown credential type
+    context.output.info(`Credential file exists for ${service} but has an unrecognized type: ${credential.type}`);
+  }
+}
+
+module.exports = { meta, run };

package/src/commands/config/export.js

@@ -0,0 +1,224 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const DEVUTILS_DIR = path.join(os.homedir(), '.devutils');
+const CONFIG_FILE = path.join(DEVUTILS_DIR, 'config.json');
+
+const meta = {
+  description: 'Push the current config profile to the remote backup (repo or gist), or export to a local file.',
+  arguments: [],
+  flags: [
+    { name: 'file', type: 'string', description: 'Export to a local file instead of remote backup' },
+    { name: 'profile', type: 'string', description: 'Export a specific profile (defaults to the active profile)' }
+  ]
+};
+
+/**
+ * The list of config files that are included in an export.
+ * Auth tokens are NOT included -- they are sensitive and should be
+ * re-created on new machines via "dev auth login".
+ */
+const FILES_TO_EXPORT = ['config.json', 'aliases.json', 'ai.json', 'plugins.json'];
+
+/**
+ * Read a config file from ~/.devutils/ if it exists.
+ * Returns the parsed content, or null if the file is missing or invalid JSON.
+ *
+ * @param {string} filename - The filename to read (e.g., 'config.json').
+ * @returns {object|null} The parsed JSON content, or null.
+ */
+function readConfigFile(filename) {
+  const filePath = path.join(DEVUTILS_DIR, filename);
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the sync timestamp after a successful export.
+ * This is used by future sync-check features to know when the last
+ * export or import happened.
+ *
+ * @param {string} profileName - The profile that was exported.
+ */
+function writeSyncTimestamp(profileName) {
+  const syncPath = path.join(DEVUTILS_DIR, 'sync.json');
+  const syncData = {
+    lastSync: new Date().toISOString(),
+    direction: 'export',
+    profile: profileName
+  };
+  fs.writeFileSync(syncPath, JSON.stringify(syncData, null, 2) + '\n');
+}
+
+/**
+ * Run the config export command.
+ * Supports two modes:
+ * - File mode (--file): Bundles all config files into a single JSON file on disk.
+ * - Remote mode (default): Pushes config to a GitHub repo or gist based on backup settings.
+ *
+ * @param {object} args - Parsed CLI arguments (positional, flags).
+ * @param {object} context - CLI context (output, prompt, errors).
+ */
+async function run(args, context) {
+  const github = require('../../lib/github');
+
+  // Read current config to get profile and backup settings
+  const config = readConfigFile('config.json');
+  const profileName = args.flags.profile || (config && config.profile) || 'default';
+
+  // --- File export mode ---
+  if (args.flags.file) {
+    const bundle = {
+      exportedAt: new Date().toISOString(),
+      profile: profileName,
+      config: readConfigFile('config.json'),
+      aliases: readConfigFile('aliases.json'),
+      ai: readConfigFile('ai.json'),
+      plugins: readConfigFile('plugins.json')
+    };
+
+    const outputPath = path.resolve(args.flags.file);
+    fs.writeFileSync(outputPath, JSON.stringify(bundle, null, 2) + '\n');
+    context.output.info(`Config exported to ${outputPath}`);
+
+    writeSyncTimestamp(profileName);
+    return;
+  }
+
+  // --- Remote export mode ---
+  if (!config || !config.backup) {
+    context.output.info('No backup storage configured.');
+    context.output.info('Run "dev config init" to set up backup storage.');
+    return;
+  }
+
+  const backend = config.backup.backend;
+  const location = config.backup.location;
+
+  if (backend === 'repo') {
+    // Check gh authentication
+    const isAuth = await github.isAuthenticated();
+    if (!isAuth) {
+      context.output.info('Not authenticated with GitHub. Run: gh auth login');
+      return;
+    }
+
+    const cacheDir = path.join(DEVUTILS_DIR, 'cache');
+    const repoDir = path.join(cacheDir, 'config-backup');
+    fs.mkdirSync(cacheDir, { recursive: true });
+
+    // Clone or pull the repo
+    if (fs.existsSync(path.join(repoDir, '.git'))) {
+      // Already cloned -- pull latest
+      const pullResult = await github.pullRepo(repoDir);
+      if (!pullResult.success) {
+        context.output.error('Failed to pull latest config: ' + pullResult.error);
+        return;
+      }
+    } else {
+      // First time -- need repo location
+      if (!location) {
+        context.output.info('No backup repository configured.');
+        context.output.info('Run "dev config init --force" to set up a backup repository.');
+        return;
+      }
+
+      const cloneResult = await github.cloneRepo(location, repoDir);
+      if (!cloneResult.success) {
+        context.output.error('Failed to clone backup repo: ' + cloneResult.error);
+        return;
+      }
+    }
+
+    // Copy config files into the profile directory
+    const profileDir = path.join(repoDir, 'profiles', profileName);
+    fs.mkdirSync(profileDir, { recursive: true });
+
+    for (const filename of FILES_TO_EXPORT) {
+      const sourcePath = path.join(DEVUTILS_DIR, filename);
+      if (fs.existsSync(sourcePath)) {
+        fs.copyFileSync(sourcePath, path.join(profileDir, filename));
+      }
+    }
+
+    // Push
+    const pushResult = await github.pushRepo(
+      repoDir,
+      `Update profile "${profileName}" - ${new Date().toISOString()}`
+    );
+
+    if (!pushResult.success) {
+      context.output.error('Failed to push config: ' + pushResult.error);
+      return;
+    }
+
+    context.output.info(`Config exported to repo (profile: ${profileName}).`);
+    writeSyncTimestamp(profileName);
+
+  } else if (backend === 'gist') {
+    // Check gh authentication
+    const isAuth = await github.isAuthenticated();
+    if (!isAuth) {
+      context.output.info('Not authenticated with GitHub. Run: gh auth login');
+      return;
+    }
+
+    // Bundle config files into a single JSON for the gist
+    const bundle = {
+      config: readConfigFile('config.json'),
+      aliases: readConfigFile('aliases.json'),
+      ai: readConfigFile('ai.json'),
+      plugins: readConfigFile('plugins.json')
+    };
+
+    const filename = `${profileName}.json`;
+    const content = JSON.stringify(bundle, null, 2);
+
+    if (location) {
+      // Update existing gist
+      const result = await github.updateGist(location, { [filename]: content });
+      if (!result.success) {
+        context.output.error('Failed to update gist: ' + result.error);
+        return;
+      }
+      context.output.info(`Config exported to gist (profile: ${profileName}).`);
+    } else {
+      // Create new gist
+      const result = await github.createGist(
+        { [filename]: content },
+        'DevUtils CLI configuration backup',
+        true
+      );
+
+      if (!result.success) {
+        context.output.error('Failed to create gist: ' + result.error);
+        return;
+      }
+
+      // Save the gist ID back to config so future exports update the same gist
+      config.backup.location = result.id;
+      fs.writeFileSync(
+        CONFIG_FILE,
+        JSON.stringify(config, null, 2) + '\n'
+      );
+
+      context.output.info(`Config exported to new gist (profile: ${profileName}).`);
+      context.output.info(`Gist URL: ${result.url}`);
+    }
+
+    writeSyncTimestamp(profileName);
+
+  } else {
+    context.output.info(`Unknown backup backend: ${backend}`);
+    context.output.info('Run "dev config init --force" to reconfigure backup storage.');
+  }
+}
+
+module.exports = { meta, run };

package/src/commands/config/get.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CONFIG_FILE = path.join(os.homedir(), '.devutils', 'config.json');
+
+const meta = {
+  description: 'Read a specific config value by dot-notation key.',
+  arguments: [
+    { name: 'key', required: true, description: 'Dot-notation path to the config value (e.g., user.email, defaults.license)' },
+  ],
+  flags: [],
+};
+
+async function run(args, context) {
+  const key = args.positional[0];
+
+  if (!key) {
+    context.errors.throwError(400, 'Missing required argument: <key>. Example: dev config get user.email', 'config');
+    return;
+  }
+
+  if (!fs.existsSync(CONFIG_FILE)) {
+    context.errors.throwError(404, 'Config not found. Run "dev config init" first.', 'config');
+    return;
+  }
+
+  const raw = fs.readFileSync(CONFIG_FILE, 'utf8');
+  const config = JSON.parse(raw);
+
+  // Resolve dot-notation key
+  const parts = key.split('.');
+  let value = config;
+
+  for (const part of parts) {
+    if (value === null || value === undefined || typeof value !== 'object') {
+      context.errors.throwError(404, `Key "${key}" not found in config.`, 'config');
+      return;
+    }
+    if (!(part in value)) {
+      context.errors.throwError(404, `Key "${key}" not found in config.`, 'config');
+      return;
+    }
+    value = value[part];
+  }
+
+  context.output.out(value);
+}
+
+module.exports = { meta, run };