@fredlackey/devutils 0.0.19 → 0.1.0

package/src/lib/config.js

@@ -0,0 +1,125 @@
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * The path to the DevUtils configuration directory.
+ * All user data, preferences, and plugin data live here.
+ * @type {string}
+ */
+const CONFIG_DIR = path.join(os.homedir(), '.devutils');
+
+/**
+ * Creates the ~/.devutils/ directory if it doesn't exist.
+ * Idempotent: calling it multiple times has the same effect as calling it once.
+ *
+ * @returns {string} The config directory path.
+ */
+function ensureDir() {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+  return CONFIG_DIR;
+}
+
+/**
+ * Returns the full path to a file inside ~/.devutils/.
+ * Does not check if the file exists.
+ *
+ * @param {string} filename - The filename (e.g. 'config.json').
+ * @returns {string} The full file path.
+ */
+function getPath(filename) {
+  return path.join(CONFIG_DIR, filename);
+}
+
+/**
+ * Checks if a file exists in ~/.devutils/.
+ *
+ * @param {string} filename - The filename to check.
+ * @returns {boolean}
+ */
+function exists(filename) {
+  return fs.existsSync(getPath(filename));
+}
+
+/**
+ * Reads a JSON file from ~/.devutils/ and returns the parsed object.
+ * Returns null if the file doesn't exist or can't be parsed.
+ *
+ * @param {string} filename - The filename to read.
+ * @returns {object|null} The parsed JSON object, or null.
+ */
+function read(filename) {
+  const filePath = getPath(filename);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Writes a JavaScript object to a JSON file in ~/.devutils/.
+ * Creates the directory if it doesn't exist. Uses 2-space indentation
+ * and a trailing newline for human-readability.
+ *
+ * @param {string} filename - The filename to write.
+ * @param {object} data - The data to write.
+ * @returns {string} The full file path that was written.
+ */
+function write(filename, data) {
+  ensureDir();
+  const filePath = getPath(filename);
+  const content = JSON.stringify(data, null, 2) + '\n';
+  fs.writeFileSync(filePath, content, 'utf8');
+  return filePath;
+}
+
+/**
+ * Deletes a file from ~/.devutils/.
+ * Idempotent: does not throw if the file doesn't exist.
+ *
+ * @param {string} filename - The filename to delete.
+ * @returns {string} The full file path (whether it existed or not).
+ */
+function remove(filename) {
+  const filePath = getPath(filename);
+  if (fs.existsSync(filePath)) {
+    fs.unlinkSync(filePath);
+  }
+  return filePath;
+}
+
+/**
+ * Lists all files (not directories) in ~/.devutils/.
+ * Returns an empty array if the directory doesn't exist.
+ *
+ * @returns {string[]} Array of filenames.
+ */
+function list() {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    return [];
+  }
+  return fs.readdirSync(CONFIG_DIR).filter(entry => {
+    const fullPath = path.join(CONFIG_DIR, entry);
+    return fs.statSync(fullPath).isFile();
+  });
+}
+
+module.exports = {
+  CONFIG_DIR,
+  ensureDir,
+  getPath,
+  exists,
+  read,
+  write,
+  remove,
+  list,
+};

package/src/lib/detect.js

@@ -0,0 +1,74 @@
+'use strict';
+
+/**
+ * Environment variables set by AI coding assistants.
+ * Each entry is [varName, expectedValue].
+ * expectedValue can be null to match any truthy value.
+ */
+const AI_ENV_VARS = [
+  ['CLAUDECODE', '1'],
+  ['GEMINI_CLI', '1'],
+];
+
+/**
+ * Environment variables set by CI/CD systems.
+ * Each entry is [varName, expectedValue].
+ * expectedValue can be null to match any truthy value.
+ */
+const CI_ENV_VARS = [
+  ['CI', 'true'],
+  ['BUILD_NUMBER', null],
+  ['TF_BUILD', 'True'],
+];
+
+/**
+ * Checks if any environment variable in the list is set and matches.
+ * When expectedValue is null, any truthy value counts as a match.
+ *
+ * @param {Array<[string, string|null]>} varList - Array of [varName, expectedValue] pairs.
+ * @returns {boolean}
+ */
+function matchesEnv(varList) {
+  for (const [varName, expectedValue] of varList) {
+    const actual = process.env[varName];
+    if (actual === undefined) continue;
+    if (expectedValue === null) return true;
+    if (actual === expectedValue) return true;
+  }
+  return false;
+}
+
+/**
+ * Detects the output mode based on the calling environment.
+ * Checks three layers in priority order: AI tools, CI/CD, then TTY.
+ *
+ * - AI tools (Claude Code, Gemini CLI) get JSON format.
+ * - CI/CD systems (GitHub Actions, Jenkins, Azure) get JSON format.
+ * - Humans at a terminal get table format.
+ * - Piped or redirected output gets JSON format.
+ *
+ * @returns {{ format: string, caller: string }}
+ *   - format: 'json' or 'table'
+ *   - caller: 'ai', 'ci', 'tty', or 'pipe'
+ */
+function detectOutputMode() {
+  // Layer 1: AI tool environment
+  if (matchesEnv(AI_ENV_VARS)) {
+    return { format: 'json', caller: 'ai' };
+  }
+
+  // Layer 2: CI/CD environment
+  if (matchesEnv(CI_ENV_VARS)) {
+    return { format: 'json', caller: 'ci' };
+  }
+
+  // Layer 3: TTY detection
+  if (process.stdout.isTTY) {
+    return { format: 'table', caller: 'tty' };
+  }
+
+  // Fallback: piped or redirected output
+  return { format: 'json', caller: 'pipe' };
+}
+
+module.exports = { detectOutputMode };

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