@fredlackey/devutils 0.0.18 → 0.1.0

package/src/lib/prompt.js

@@ -0,0 +1,161 @@
+'use strict';
+
+const readline = require('readline');
+const { detectOutputMode } = require('./detect');
+
+/**
+ * Checks if the current environment is interactive (human at a terminal).
+ * Only 'tty' callers are interactive. AI tools, CI systems, and piped output
+ * are all non-interactive.
+ *
+ * @returns {boolean}
+ */
+function isInteractive() {
+  const { caller } = detectOutputMode();
+  return caller === 'tty';
+}
+
+/**
+ * Opens a readline interface, asks one question, and closes it.
+ * Writes prompt text to stderr (not stdout) so piped output stays clean.
+ *
+ * @param {string} question - The question text to display.
+ * @returns {Promise<string>} The user's answer.
+ */
+function askReadline(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stderr,
+    });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+/**
+ * Asks a free-text question. Returns the user's answer, or the default value
+ * in non-interactive mode or when the user presses Enter without typing.
+ *
+ * @param {string} question - The question to ask.
+ * @param {string} [defaultValue=''] - The default value if no input is given.
+ * @returns {Promise<string>}
+ */
+async function ask(question, defaultValue = '') {
+  if (!isInteractive()) {
+    return defaultValue;
+  }
+
+  const suffix = defaultValue ? ` (${defaultValue})` : '';
+  const answer = await askReadline(`${question}${suffix}: `);
+  return answer.trim() || defaultValue;
+}
+
+/**
+ * Asks a yes/no question. Returns true or false.
+ * The hint shows which option is default: (Y/n) means yes, (y/N) means no.
+ *
+ * @param {string} question - The question to ask.
+ * @param {boolean} [defaultValue=false] - The default value.
+ * @returns {Promise<boolean>}
+ */
+async function confirm(question, defaultValue = false) {
+  if (!isInteractive()) {
+    return defaultValue;
+  }
+
+  const hint = defaultValue ? '(Y/n)' : '(y/N)';
+  const answer = await askReadline(`${question} ${hint}: `);
+  const trimmed = answer.trim().toLowerCase();
+
+  if (trimmed === '') return defaultValue;
+  return trimmed === 'y' || trimmed === 'yes';
+}
+
+/**
+ * Presents a numbered list of choices and asks the user to pick one.
+ * Returns the selected choice string.
+ * Invalid input falls back to the default with a message.
+ *
+ * @param {string} question - The question to display above the choices.
+ * @param {string[]} choices - The list of choices.
+ * @param {number} [defaultIndex=0] - The index of the default choice.
+ * @returns {Promise<string>}
+ */
+async function choose(question, choices, defaultIndex = 0) {
+  if (!isInteractive()) {
+    return choices[defaultIndex] || choices[0];
+  }
+
+  // Display the choices on stderr
+  process.stderr.write(`${question}\n`);
+  for (let i = 0; i < choices.length; i++) {
+    const marker = i === defaultIndex ? '>' : ' ';
+    process.stderr.write(`  ${marker} ${i + 1}. ${choices[i]}\n`);
+  }
+
+  const answer = await askReadline(`Choice (1-${choices.length}) [${defaultIndex + 1}]: `);
+  const trimmed = answer.trim();
+
+  if (trimmed === '') return choices[defaultIndex];
+
+  const index = parseInt(trimmed, 10) - 1;
+  if (isNaN(index) || index < 0 || index >= choices.length) {
+    process.stderr.write(`Invalid choice. Using default: ${choices[defaultIndex]}\n`);
+    return choices[defaultIndex];
+  }
+
+  return choices[index];
+}
+
+/**
+ * Asks for sensitive input (passwords, API keys). The input is not echoed.
+ * Returns an empty string in non-interactive mode.
+ *
+ * @param {string} question - The prompt text.
+ * @returns {Promise<string>}
+ */
+async function password(question) {
+  if (!isInteractive()) {
+    return '';
+  }
+
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stderr,
+      terminal: true,
+    });
+
+    const origWrite = rl.output.write.bind(rl.output);
+    let muted = false;
+
+    rl.output.write = function(chunk) {
+      if (muted) return;
+      return origWrite(chunk);
+    };
+
+    rl.question(`${question}: `, (answer) => {
+      muted = false;
+      rl.output.write('\n');
+      rl.close();
+      resolve(answer);
+    });
+
+    muted = true;
+  });
+}
+
+/**
+ * Alias for ask(). Command stories may use context.prompt.input().
+ */
+const input = ask;
+
+/**
+ * Alias for choose(). Command stories may use context.prompt.select().
+ */
+const select = choose;
+
+module.exports = { ask, input, confirm, choose, select, password, isInteractive };

package/src/lib/schema.js

@@ -0,0 +1,211 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SERVICE_NAMES = [
+  'config', 'machine', 'identity', 'tools',
+  'ignore', 'util', 'alias', 'auth', 'api', 'ai', 'search',
+];
+
+const TOP_LEVEL_COMMANDS = ['status', 'update', 'version', 'schema', 'help'];
+
+let _registry = null;
+
+/**
+ * Build the full schema registry by walking all service index.js files,
+ * top-level commands, and installed API plugins.
+ *
+ * @returns {object} The nested registry object.
+ */
+function buildRegistry() {
+  const registry = {};
+
+  // Load services
+  for (const name of SERVICE_NAMES) {
+    try {
+      const service = require(`../commands/${name}/index`);
+      const entry = {
+        type: 'service',
+        name: service.name || name,
+        description: service.description || '',
+        commands: {},
+      };
+
+      for (const [cmdName, loader] of Object.entries(service.commands || {})) {
+        try {
+          const cmd = typeof loader === 'function' ? loader() : loader;
+          entry.commands[cmdName] = {
+            type: 'command',
+            name: cmdName,
+            description: (cmd.meta && cmd.meta.description) || '',
+            arguments: (cmd.meta && cmd.meta.arguments) || [],
+            flags: (cmd.meta && cmd.meta.flags) || [],
+          };
+        } catch {
+          // Skip commands that fail to load
+        }
+      }
+
+      registry[name] = entry;
+    } catch {
+      // Skip services that fail to load
+    }
+  }
+
+  // Load top-level commands
+  for (const name of TOP_LEVEL_COMMANDS) {
+    try {
+      const cmd = require(`../commands/${name}`);
+      registry[name] = {
+        type: 'command',
+        name,
+        description: (cmd.meta && cmd.meta.description) || '',
+        arguments: (cmd.meta && cmd.meta.arguments) || [],
+        flags: (cmd.meta && cmd.meta.flags) || [],
+      };
+    } catch {
+      // Skip commands that fail to load
+    }
+  }
+
+  // Load API plugins
+  loadPlugins(registry);
+
+  return registry;
+}
+
+/**
+ * Load installed API plugins into the registry under api.plugins.
+ * @param {object} registry - The registry to extend.
+ */
+function loadPlugins(registry) {
+  const pluginsFile = path.join(os.homedir(), '.devutils', 'plugins.json');
+
+  if (!fs.existsSync(pluginsFile)) {
+    return;
+  }
+
+  let plugins;
+  try {
+    plugins = JSON.parse(fs.readFileSync(pluginsFile, 'utf8'));
+  } catch {
+    return;
+  }
+
+  const pluginsDir = path.join(os.homedir(), '.devutils', 'plugins');
+
+  if (!registry.api) {
+    registry.api = { type: 'service', name: 'api', description: 'API plugin system', commands: {} };
+  }
+
+  for (const [serviceName, info] of Object.entries(plugins)) {
+    try {
+      const pluginPath = path.join(pluginsDir, 'node_modules', info.package);
+      const plugin = require(pluginPath);
+
+      const serviceEntry = {
+        type: 'plugin',
+        name: plugin.name || serviceName,
+        description: plugin.description || '',
+        version: plugin.version || '',
+        auth: plugin.auth || null,
+        resources: {},
+      };
+
+      for (const [resName, resource] of Object.entries(plugin.resources || {})) {
+        const resEntry = {
+          type: 'resource',
+          name: resName,
+          description: (resource.description) || '',
+          commands: {},
+        };
+
+        for (const [cmdName, loader] of Object.entries(resource.commands || {})) {
+          try {
+            const cmd = typeof loader === 'function' ? loader() : loader;
+            resEntry.commands[cmdName] = {
+              type: 'command',
+              name: cmdName,
+              description: (cmd.meta && cmd.meta.description) || '',
+              arguments: (cmd.meta && cmd.meta.arguments) || [],
+              flags: (cmd.meta && cmd.meta.flags) || [],
+            };
+          } catch {
+            // Skip commands that fail to load
+          }
+        }
+
+        serviceEntry.resources[resName] = resEntry;
+      }
+
+      if (!registry.api.plugins) {
+        registry.api.plugins = {};
+      }
+      registry.api.plugins[serviceName] = serviceEntry;
+    } catch {
+      // Plugin failed to load, skip it
+    }
+  }
+}
+
+/**
+ * Get the schema registry. Built lazily on first access and cached.
+ * @returns {object} The registry.
+ */
+function getRegistry() {
+  if (!_registry) {
+    _registry = buildRegistry();
+  }
+  return _registry;
+}
+
+/**
+ * Resolve a dot-notation path to a registry entry.
+ * Handles up to 4 levels: api.plugin.resource.command.
+ *
+ * @param {string} dotPath - Dot-notation path (e.g., "config.set", "api.gmail.messages.list").
+ * @returns {object|null} The matching entry, or null if not found.
+ */
+function resolve(dotPath) {
+  const registry = getRegistry();
+  const parts = dotPath.split('.');
+
+  // Single segment: top-level service or command
+  if (parts.length === 1) {
+    return registry[parts[0]] || null;
+  }
+
+  // Two segments: service.command
+  if (parts.length === 2) {
+    const service = registry[parts[0]];
+    if (!service) return null;
+    if (service.type === 'service' && service.commands && service.commands[parts[1]]) {
+      return service.commands[parts[1]];
+    }
+    return null;
+  }
+
+  // Three segments: api.plugin.resource
+  if (parts.length === 3 && parts[0] === 'api') {
+    const plugins = (registry.api && registry.api.plugins) || {};
+    const plugin = plugins[parts[1]];
+    if (!plugin) return null;
+    return (plugin.resources && plugin.resources[parts[2]]) || null;
+  }
+
+  // Four segments: api.plugin.resource.command
+  if (parts.length === 4 && parts[0] === 'api') {
+    const plugins = (registry.api && registry.api.plugins) || {};
+    const plugin = plugins[parts[1]];
+    if (!plugin) return null;
+    const resource = plugin.resources && plugin.resources[parts[2]];
+    if (!resource) return null;
+    return (resource.commands && resource.commands[parts[3]]) || null;
+  }
+
+  return null;
+}
+
+module.exports = { getRegistry, resolve };

package/src/lib/shell.js

@@ -0,0 +1,75 @@
+'use strict';
+
+const { exec: cpExec, execSync: cpExecSync } = require('child_process');
+
+/**
+ * Runs a shell command asynchronously.
+ * Always resolves (never rejects). The caller checks exitCode to determine success.
+ *
+ * @param {string} cmd - The command to run.
+ * @param {object} [opts] - Options passed through to child_process.exec (cwd, env, timeout, etc.).
+ * @returns {Promise<{ stdout: string, stderr: string, exitCode: number }>}
+ */
+async function exec(cmd, opts = {}) {
+  return new Promise((resolve) => {
+    cpExec(cmd, opts, (error, stdout, stderr) => {
+      resolve({
+        stdout: stdout ? stdout.toString().trim() : '',
+        stderr: stderr ? stderr.toString().trim() : '',
+        exitCode: error ? error.code || 1 : 0,
+      });
+    });
+  });
+}
+
+/**
+ * Runs a shell command synchronously.
+ * Returns the trimmed stdout string on success, or null on failure.
+ *
+ * An empty string means "command ran but produced no output."
+ * Null means "command failed."
+ *
+ * @param {string} cmd - The command to run.
+ * @param {object} [opts] - Options passed through to child_process.execSync.
+ * @returns {string|null}
+ */
+function execSync(cmd, opts = {}) {
+  try {
+    const result = cpExecSync(cmd, { ...opts, encoding: 'utf8' });
+    return result ? result.trim() : '';
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Finds the full path to a binary on the system PATH.
+ * Uses "which" on unix-like systems and "where" on native Windows.
+ * Git Bash provides its own "which", so it uses the unix path.
+ *
+ * @param {string} binary - The name of the binary to find (e.g. 'node', 'git').
+ * @returns {string|null} The full path to the binary, or null if not found.
+ */
+function which(binary) {
+  const platform = require('./platform').detect();
+  const cmd = platform.type === 'windows' ? `where ${binary}` : `which ${binary}`;
+  const result = execSync(cmd);
+  if (result === null) {
+    return null;
+  }
+  // 'where' on Windows can return multiple lines; take the first one
+  return result.split('\n')[0].trim();
+}
+
+/**
+ * Checks if a binary exists on the system PATH.
+ * A boolean wrapper around which().
+ *
+ * @param {string} binary - The name of the binary to check.
+ * @returns {boolean} True if the binary exists, false otherwise.
+ */
+function commandExists(binary) {
+  return which(binary) !== null;
+}
+
+module.exports = { exec, execSync, which, commandExists };

package/src/patterns/gitignore/claude-code.txt

@@ -0,0 +1,25 @@
+# Claude Code
+# Patterns for Claude Code, Sidecar, and other AI coding tool artifacts.
+
+# Claude Code local state
+.claude/
+
+# Sidecar local state (TUI task runner)
+.sidecar/
+
+# Sidecar todo tracking
+.todos/
+
+# AI session artifacts
+.ai-sessions/
+
+# Cursor AI
+.cursorignore
+.cursorindexingignore
+.cursor/
+
+# Aider
+.aider*
+
+# Codeium
+.codeium/

package/src/patterns/gitignore/docker.txt

@@ -0,0 +1,15 @@
+# Docker
+# Patterns for Docker projects. These are files that should not be
+# included in a Docker build context or committed to version control.
+
+# Docker Compose override (local dev customization)
+docker-compose.override.yml
+docker-compose.override.yaml
+
+# Docker environment files
+.docker/
+.dockerenv
+
+# Local data volumes (often mounted for development)
+data/
+volumes/

package/src/patterns/gitignore/go.txt

@@ -0,0 +1,24 @@
+# Go
+# Patterns for Go projects.
+
+# Compiled binaries
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary (created by go test -c)
+*.test
+
+# Output of go coverage tool
+*.out
+
+# Go workspace file
+go.work
+
+# Vendor directory (if not committing dependencies)
+# vendor/
+
+# Build output directory
+bin/

package/src/patterns/gitignore/java.txt

@@ -0,0 +1,38 @@
+# Java
+# Patterns for Java and JVM-based projects.
+
+# Compiled class files
+*.class
+
+# Package files
+*.jar
+*.war
+*.nar
+*.ear
+*.zip
+*.tar.gz
+*.rar
+
+# Build output
+target/
+build/
+out/
+
+# Gradle
+.gradle/
+gradle-app.setting
+!gradle-wrapper.jar
+
+# Maven
+pom.xml.tag
+pom.xml.releaseBackup
+pom.xml.versionsBackup
+pom.xml.next
+release.properties
+
+# Log files
+*.log
+
+# Virtual machine crash logs
+hs_err_pid*
+replay_pid*

package/src/patterns/gitignore/jetbrains.txt

@@ -0,0 +1,26 @@
+# JetBrains
+# Patterns for JetBrains IDEs (IntelliJ, WebStorm, PyCharm, etc.).
+
+# IDE project settings
+.idea/
+
+# File-based project format
+*.iws
+*.iml
+*.ipr
+
+# CMake build output
+cmake-build-*/
+
+# Crashlytics plugin (for Android projects)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based HTTP client requests
+httpRequests/
+
+# DataSources local storage
+dataSources/
+dataSources.local.xml

package/src/patterns/gitignore/linux.txt

@@ -0,0 +1,18 @@
+# Linux
+# Patterns for Linux system files and editor artifacts.
+
+# Backup files
+*~
+
+# NFS temp files
+.nfs*
+
+# KDE directory preferences
+.directory
+
+# Swap files
+*.swp
+*.swo
+
+# Trash directories
+.Trash-*

package/src/patterns/gitignore/macos.txt

@@ -0,0 +1,27 @@
+# macOS
+# Patterns for macOS system and Finder metadata files.
+
+# Finder metadata
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Thumbnail cache
+._*
+
+# Spotlight indexing
+.Spotlight-V100
+
+# Trash folder state
+.Trashes
+
+# Volume metadata
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Finder directory metadata
+.fseventsd
+.apdisk
+
+# macOS resource forks
+Icon?

package/src/patterns/gitignore/node.txt

@@ -0,0 +1,51 @@
+# Node.js
+# Patterns for Node.js and JavaScript/TypeScript projects.
+
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+build/
+out/
+.next/
+.nuxt/
+
+# Environment and secrets
+.env
+.env.*
+!.env.example
+
+# Package manager files
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+.yarn/
+.pnp.*
+
+# Debug and logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+*.log
+
+# Coverage and test output
+coverage/
+.nyc_output/
+*.lcov
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Cache directories
+.cache/
+.parcel-cache/
+.eslintcache
+
+# Runtime data
+pids/
+*.pid
+*.seed
+*.pid.lock