@crystalplatforms/adm 0.2.3

package/src/tui/components/SetupScreen.js

@@ -0,0 +1,292 @@
+const React = require('react');
+const { loadCatalog, getToolsByCategories } = require('../../setup/catalog');
+const { installTools, installToolAsync, getInstallCommand, isToolInstalled } = require('../../setup/installer');
+
+const PAGE_SIZE = 10;
+
+function createSetupState(opts = {}) {
+  const categories = loadCatalog();
+  const onExit = opts.onExit || (() => {});
+  const dryRun = opts.dryRun || false;
+  const execSync = opts.execSync;
+
+  const state = {
+    categories,
+    step: 'categories',
+    selectedCategories: [],
+    selectedTools: [],
+    summary: null,
+    cursor: 0,
+    page: 0,
+    installProgress: null,
+
+    toggleCategory(id) {
+      const idx = state.selectedCategories.indexOf(id);
+      if (idx === -1) state.selectedCategories.push(id);
+      else state.selectedCategories.splice(idx, 1);
+    },
+
+    toggleTool(id) {
+      const idx = state.selectedTools.indexOf(id);
+      if (idx === -1) state.selectedTools.push(id);
+      else state.selectedTools.splice(idx, 1);
+    },
+
+    getToolsForSelectedCategories() {
+      return getToolsByCategories(state.selectedCategories);
+    },
+
+    goToTools() {
+      state.step = 'tools';
+      state.cursor = 0;
+      state.page = 0;
+    },
+
+    goToInstall() {
+      state.step = 'install';
+      state.cursor = 0;
+      state.page = 0;
+    },
+
+    goToSummary(summary, results) {
+      state.summary = summary;
+      state.installResults = results || [];
+      state.step = 'summary';
+      state.page = 0;
+    },
+
+    getVisibleItems() {
+      if (state.step === 'categories') return state.categories;
+      if (state.step === 'tools') return state.getToolsForSelectedCategories();
+      if (state.step === 'summary') return state.installResults || [];
+      return [];
+    },
+
+    handleArrow(direction) {
+      const totalPages = state.getTotalPages();
+      if (direction === 'right' && state.page < totalPages - 1) {
+        state.page++;
+      } else if (direction === 'left' && state.page > 0) {
+        state.page--;
+      }
+    },
+
+    getTotalPages() {
+      return Math.max(1, Math.ceil(state.getVisibleItems().length / PAGE_SIZE));
+    },
+
+    cancel() {
+      onExit();
+    },
+
+    async runInstall(platform, onProgress) {
+      if (dryRun) {
+        const allTools = state.getToolsForSelectedCategories();
+        const selected = allTools.filter(t => state.selectedTools.includes(t.id));
+        const plan = selected.map(t => ({
+          id: t.id,
+          name: t.name,
+          command: getInstallCommand(t, platform),
+        }));
+        return { dryRun: true, plan };
+      }
+
+      const allTools = state.getToolsForSelectedCategories();
+      const selected = allTools.filter(t => state.selectedTools.includes(t.id));
+      const results = [];
+
+      for (const tool of selected) {
+        state.installProgress = { current: tool.name, done: results.length, total: selected.length };
+        if (onProgress) onProgress();
+
+        const result = await installToolAsync(tool, platform);
+        results.push(result);
+        if (onProgress) onProgress();
+      }
+
+      state.installProgress = null;
+
+      const summary = {
+        installed: results.filter(r => r.status === 'installed').length,
+        skipped: results.filter(r => r.status === 'skipped').length,
+        failed: results.filter(r => r.status === 'failed').length,
+      };
+
+      return { results, summary };
+    },
+  };
+
+  return state;
+}
+
+function createSetupScreen(ink) {
+  const { Box, Text, useInput, useApp } = ink;
+
+  return function SetupScreen({ onExit, dryRun, platform }) {
+    const stateRef = React.useRef(createSetupState({ onExit, dryRun }));
+    const [renderKey, setRenderKey] = React.useState(0);
+    const s = stateRef.current;
+
+    const triggerRender = () => setRenderKey(k => k + 1);
+
+    const allItems = s.getVisibleItems();
+
+    const totalPages = s.getTotalPages();
+    const pageStart = s.page * PAGE_SIZE;
+    const pageItems = allItems.slice(pageStart, pageStart + PAGE_SIZE);
+
+    // Clamp cursor to current page
+    if (s.cursor < pageStart || s.cursor >= pageStart + pageItems.length) {
+      s.cursor = pageStart;
+    }
+
+    useInput((ch, key) => {
+      if (key.escape) {
+        s.cancel();
+        return;
+      }
+
+      // Navigate up/down within current page
+      if (key.upArrow) {
+        s.cursor = Math.max(pageStart, s.cursor - 1);
+        triggerRender();
+        return;
+      }
+      if (key.downArrow) {
+        s.cursor = Math.min(pageStart + pageItems.length - 1, s.cursor + 1);
+        triggerRender();
+        return;
+      }
+
+      // Page left/right
+      if (key.leftArrow) {
+        s.handleArrow('left');
+        s.cursor = s.page * PAGE_SIZE;
+        triggerRender();
+        return;
+      }
+      if (key.rightArrow) {
+        s.handleArrow('right');
+        s.cursor = s.page * PAGE_SIZE;
+        triggerRender();
+        return;
+      }
+
+      // Space — toggle selection
+      if (ch === ' ') {
+        const item = allItems[s.cursor];
+        if (!item) return;
+        if (s.step === 'categories') {
+          s.toggleCategory(item.id);
+        } else if (s.step === 'tools') {
+          s.toggleTool(item.id);
+        }
+        triggerRender();
+        return;
+      }
+
+      // Enter — confirm step
+      if (key.return) {
+        if (s.step === 'categories' && s.selectedCategories.length > 0) {
+          s.goToTools();
+          triggerRender();
+        } else if (s.step === 'tools' && s.selectedTools.length > 0) {
+          s.goToInstall();
+          triggerRender();
+          s.runInstall(platform || 'darwin', triggerRender).then(result => {
+            if (result.summary) {
+              s.goToSummary(result.summary, result.results || []);
+            }
+            triggerRender();
+          });
+        }
+      }
+    });
+
+    const lines = [];
+    const selCount = s.step === 'categories' ? s.selectedCategories.length : s.selectedTools.length;
+    const pagerText = totalPages > 1 ? `  [${s.page + 1}/${totalPages}]  ←→ = change page` : '';
+
+    if (s.step === 'categories') {
+      lines.push({ text: `Select categories (${selCount} selected) Space=toggle  Enter=confirm  Esc=cancel`, highlight: false });
+      lines.push({ text: pagerText, highlight: false });
+
+      for (let i = 0; i < pageItems.length; i++) {
+        const cat = pageItems[i];
+        const globalIdx = pageStart + i;
+        const marker = s.selectedCategories.includes(cat.id) ? '[x]' : '[ ]';
+        const active = globalIdx === s.cursor ? ' > ' : '   ';
+        lines.push({ text: `${active}${marker} ${cat.icon} ${cat.name}`, highlight: globalIdx === s.cursor });
+      }
+    } else if (s.step === 'tools') {
+      lines.push({ text: `Select tools (${selCount} selected) Space=toggle  Enter=confirm  Esc=cancel`, highlight: false });
+      lines.push({ text: pagerText, highlight: false });
+
+      for (let i = 0; i < pageItems.length; i++) {
+        const tool = pageItems[i];
+        const globalIdx = pageStart + i;
+        const marker = s.selectedTools.includes(tool.id) ? '[x]' : '[ ]';
+        const active = globalIdx === s.cursor ? ' > ' : '   ';
+        lines.push({ text: `${active}${marker} ${tool.name} (${tool.installMethod})`, highlight: globalIdx === s.cursor });
+      }
+    } else if (s.step === 'install') {
+      const p = s.installProgress;
+      if (p) {
+        lines.push({ text: `Installing (${p.done + 1}/${p.total}): ${p.current}...`, highlight: false });
+      } else {
+        lines.push({ text: 'Installing selected tools...', highlight: false });
+      }
+    } else if (s.step === 'summary') {
+      const sum = s.summary || {};
+      const results = s.installResults || [];
+
+      lines.push({ text: ' Setup complete!', highlight: false });
+      lines.push({ text: ` Installed: ${sum.installed || 0}  Skipped: ${sum.skipped || 0}  Failed: ${sum.failed || 0}`, highlight: false });
+      lines.push({ text: '', highlight: false });
+
+      // Show per-tool results (paginated)
+      const resPageStart = s.page * PAGE_SIZE;
+      const resPage = results.slice(resPageStart, resPageStart + PAGE_SIZE);
+      const resTotalPages = Math.max(1, Math.ceil(results.length / PAGE_SIZE));
+
+      for (const r of resPage) {
+        const icon = r.status === 'installed' ? '+' : r.status === 'skipped' ? '-' : 'x';
+        const color = r.status === 'installed' ? 'green' : r.status === 'skipped' ? 'yellow' : 'red';
+        const detail = r.status === 'failed' ? ` — ${r.error || 'unknown error'}` : '';
+        lines.push({ text: `  [${icon}] ${r.name} ${r.status}${detail}`, color, highlight: false });
+        if (r.hint) {
+          lines.push({ text: `       ${r.hint}`, color: 'gray', highlight: false });
+        }
+      }
+
+      if (resTotalPages > 1) {
+        lines.push({ text: `  [${s.page + 1}/${resTotalPages}] ←→ = more results`, highlight: false });
+      }
+
+      lines.push({ text: '\n Press Esc to return to ADM.', highlight: false });
+
+      if (sum.installed > 0) {
+        lines.push({ text: ' Tip: restart terminal (or run: source ~/.zshrc) for new tools', color: 'yellow', highlight: false });
+      }
+
+      if (dryRun) {
+        lines.push({ text: ' (dry-run mode — no tools were actually installed)', highlight: false });
+      }
+    }
+
+    return React.createElement(
+      Box,
+      { flexDirection: 'column', flexGrow: 1, paddingX: 1 },
+      ...lines.map((line, i) =>
+        React.createElement(Text, {
+          key: i,
+          wrap: 'wrap',
+          color: line.color || (line.highlight ? 'cyan' : undefined),
+          bold: line.highlight,
+        }, line.text)
+      ),
+    );
+  };
+}
+
+module.exports = { createSetupScreen, createSetupState };

package/src/ui/animations.js

@@ -0,0 +1,24 @@
+function createAnimation(renderFn, options = {}) {
+  const interval = options.interval || 5000;
+  let timer = null;
+
+  return {
+    start() {
+      if (timer) return this;
+      timer = setInterval(renderFn, interval);
+      return this;
+    },
+    stop() {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+      return this;
+    },
+    isRunning() {
+      return timer !== null;
+    },
+  };
+}
+
+module.exports = { createAnimation };

package/src/ui/spinner.js

@@ -0,0 +1,34 @@
+const ora = require('ora');
+const { resolveTheme } = require('./theme');
+
+const NAMED_COLORS = ['black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white', 'gray'];
+
+function toOraColor(color) {
+  if (NAMED_COLORS.includes(color)) return color;
+  return 'cyan';
+}
+
+function createSpinner(text, options = {}) {
+  const theme = resolveTheme({});
+  const rawColor = options.noColor ? 'white' : (options.color || theme.colors.primary);
+  const spinnerColor = toOraColor(rawColor);
+  const spinnerOpts = {
+    text,
+    color: spinnerColor,
+    isEnabled: options.isEnabled !== undefined ? options.isEnabled : true,
+  };
+
+  const spinner = ora(spinnerOpts);
+
+  return {
+    get text() { return spinner.text; },
+    set text(val) { spinner.text = val; },
+    start() { spinner.start(); return spinner; },
+    stop() { spinner.stop(); return spinner; },
+    succeed(msg) { spinner.succeed(msg || text); return spinner; },
+    fail(msg) { spinner.fail(msg || text); return spinner; },
+    _ora: spinner,
+  };
+}
+
+module.exports = { createSpinner };

package/src/ui/theme/cyberpunk.js

@@ -0,0 +1,14 @@
+module.exports = {
+  name: 'cyberpunk',
+  colors: {
+    primary: '#f706cf',
+    secondary: '#ff2a6d',
+    accent: '#05d9e8',
+    text: '#d1f7ff',
+    bg: '#01012b',
+    muted: '#7b2d8e',
+    error: '#ff2a6d',
+    success: '#01ff89',
+    warning: '#ff6c11',
+  },
+};

package/src/ui/theme/dark.js

@@ -0,0 +1,14 @@
+module.exports = {
+  name: 'dark',
+  colors: {
+    primary: '#61dafb',
+    secondary: '#4fc3f7',
+    accent: '#ff6b6b',
+    text: '#e0e0e0',
+    bg: '#1a1a2e',
+    muted: '#6c757d',
+    error: '#ff4757',
+    success: '#2ed573',
+    warning: '#ffa502',
+  },
+};

package/src/ui/theme/forest.js

@@ -0,0 +1,14 @@
+module.exports = {
+  name: 'forest',
+  colors: {
+    primary: '#a7c957',
+    secondary: '#6a994e',
+    accent: '#f2e8cf',
+    text: '#dda15e',
+    bg: '#1b2a1b',
+    muted: '#606c38',
+    error: '#bc4749',
+    success: '#a7c957',
+    warning: '#dda15e',
+  },
+};

package/src/ui/theme/light.js

@@ -0,0 +1,14 @@
+module.exports = {
+  name: 'light',
+  colors: {
+    primary: '#0066cc',
+    secondary: '#0099e6',
+    accent: '#cc3300',
+    text: '#1a1a1a',
+    bg: '#f5f5f5',
+    muted: '#999999',
+    error: '#cc0000',
+    success: '#008800',
+    warning: '#cc8800',
+  },
+};

package/src/ui/theme/monokai.js

@@ -0,0 +1,14 @@
+module.exports = {
+  name: 'monokai',
+  colors: {
+    primary: '#a6e22e',
+    secondary: '#66d9ef',
+    accent: '#f92672',
+    text: '#f8f8f2',
+    bg: '#272822',
+    muted: '#75715e',
+    error: '#f92672',
+    success: '#a6e22e',
+    warning: '#e6db74',
+  },
+};

package/src/ui/theme/nord.js

@@ -0,0 +1,14 @@
+module.exports = {
+  name: 'nord',
+  colors: {
+    primary: '#88c0d0',
+    secondary: '#81a1c1',
+    accent: '#bf616a',
+    text: '#eceff4',
+    bg: '#2e3440',
+    muted: '#636f88',
+    error: '#bf616a',
+    success: '#a3be8c',
+    warning: '#ebcb8b',
+  },
+};

package/src/ui/theme.js

@@ -0,0 +1,49 @@
+const darkTheme = require('./theme/dark');
+const lightTheme = require('./theme/light');
+const cyberpunkTheme = require('./theme/cyberpunk');
+const nordTheme = require('./theme/nord');
+const forestTheme = require('./theme/forest');
+const monokaiTheme = require('./theme/monokai');
+const { isDarkMode } = require('../utils/terminal-detection');
+
+const presets = {
+  dark: darkTheme,
+  light: lightTheme,
+  cyberpunk: cyberpunkTheme,
+  nord: nordTheme,
+  forest: forestTheme,
+  monokai: monokaiTheme,
+};
+
+function getTheme(name) {
+  const theme = presets[name];
+  if (!theme) throw new Error(`Unknown theme: "${name}". Available: ${Object.keys(presets).join(', ')}`);
+  return theme;
+}
+
+function listThemes() {
+  return Object.values(presets);
+}
+
+function resolveTheme(config = {}) {
+  const { theme } = config;
+
+  if (!theme || theme === 'auto') {
+    return isDarkMode() ? darkTheme : lightTheme;
+  }
+
+  if (typeof theme === 'string') {
+    return getTheme(theme);
+  }
+
+  if (typeof theme === 'object') {
+    return {
+      name: 'custom',
+      colors: { ...darkTheme.colors, ...theme },
+    };
+  }
+
+  return darkTheme;
+}
+
+module.exports = { resolveTheme, getTheme, listThemes };

package/src/utils/command-history.js

@@ -0,0 +1,43 @@
+const fs = require('fs').promises;
+const path = require('path');
+const { configDir } = require('../config/index');
+
+const MAX_ENTRIES = 1000;
+
+function historyFile() {
+  return path.join(configDir(), 'history');
+}
+
+async function loadHistory() {
+  try {
+    const data = await fs.readFile(historyFile(), 'utf8');
+    return data.split('\n').filter(Boolean);
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+}
+
+async function saveCommand(command) {
+  const trimmed = command.trim();
+  if (!trimmed) return;
+
+  const dir = configDir();
+  await fs.mkdir(dir, { recursive: true });
+
+  let history = await loadHistory();
+  history.push(trimmed);
+  if (history.length > MAX_ENTRIES) {
+    history = history.slice(history.length - MAX_ENTRIES);
+  }
+
+  await fs.writeFile(historyFile(), history.join('\n'), 'utf8');
+}
+
+async function searchHistory(query) {
+  const history = await loadHistory();
+  const lower = query.toLowerCase();
+  return history.filter(entry => entry.toLowerCase().includes(lower));
+}
+
+module.exports = { saveCommand, loadHistory, searchHistory };

package/src/utils/dotfiles-sync.js

@@ -0,0 +1,89 @@
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const { handleConflict, createBackup } = require('./file-conflict-handler');
+
+const DEFAULT_FILES = ['.bashrc', '.zshrc', '.gitconfig', '.ssh/config'];
+
+/**
+ * Syncs dotfiles from repo to home directory
+ *
+ * Options:
+ *   repo: string — dotfiles repo path/URL
+ *   homeDir: string — home directory (defaults to os.homedir())
+ *   copy: boolean — copy instead of symlinking
+ *   only: string[] — file filter (without dot, e.g. ['bashrc', 'zshrc'])
+ *   files: string[] — file list (with dot, e.g. ['.bashrc'])
+ *   onConflict: () => 'skip' | 'backup' — conflict strategy
+ */
+async function syncDotfiles(options = {}) {
+  const configDir = process.env.ADM_CONFIG_DIR || path.join(require('os').homedir(), '.adm');
+  const dotfilesDir = path.join(configDir, 'dotfiles');
+  const homeDir = options.homeDir || process.env.ADM_TEST_HOME || require('os').homedir();
+
+  // Determine file list to sync
+  let files = options.files || DEFAULT_FILES;
+
+  // --only filter (user provides without dot: 'bashrc' → '.bashrc')
+  if (options.only && options.only.length > 0) {
+    files = options.only.map(f => f.startsWith('.') ? f : '.' + f);
+  }
+
+  const result = { symlinked: [], copied: [], skipped: [], backedUp: [], errors: [] };
+
+  for (const file of files) {
+    const sourcePath = path.join(dotfilesDir, file);
+    const targetPath = path.join(homeDir, file);
+
+    // Check if source file exists in repo
+    if (!fs.existsSync(sourcePath)) {
+      continue;
+    }
+
+    // Create target directory if needed (e.g. .ssh/)
+    const targetDir = path.dirname(targetPath);
+    if (!fs.existsSync(targetDir)) {
+      fs.mkdirSync(targetDir, { recursive: true });
+    }
+
+    // Check for conflict
+    const conflict = handleConflict({ targetPath, sourcePath });
+    if (conflict === 'conflict') {
+      const strategy = options.onConflict ? options.onConflict(file) : 'skip';
+      if (strategy === 'skip') {
+        result.skipped.push(file);
+        console.log(chalk.yellow(`  ⚠ Skipped ${file} (conflict)`));
+        continue;
+      }
+      if (strategy === 'backup') {
+        createBackup(targetPath);
+        result.backedUp.push(file);
+        fs.unlinkSync(targetPath);
+        console.log(chalk.blue(`  ℹ Backup ${file} → ${file}.backup`));
+      }
+    }
+
+    // Symlink or copy
+    try {
+      if (options.copy) {
+        fs.copyFileSync(sourcePath, targetPath);
+        // Preserve permissions
+        const sourceStat = fs.statSync(sourcePath);
+        fs.chmodSync(targetPath, sourceStat.mode);
+        result.copied.push(file);
+        console.log(chalk.green(`  ✔ Copied ${file}`));
+      } else {
+        fs.symlinkSync(sourcePath, targetPath);
+        result.symlinked.push(file);
+        console.log(chalk.green(`  ✔ Symlink ${file}`));
+      }
+    } catch (err) {
+      result.errors.push({ file, error: err.message });
+      console.error(chalk.red(`  ✖ Error ${file}: ${err.message}`));
+    }
+  }
+
+  return result;
+}
+
+module.exports = { syncDotfiles };

package/src/utils/error-handler.js

@@ -0,0 +1,69 @@
+class AdmError extends Error {
+  constructor(type, message, exitCode = 1, remediation = null) {
+    super(message);
+    this.name = 'AdmError';
+    this.type = type;
+    this.exitCode = exitCode;
+    this.remediation = remediation;
+  }
+}
+
+function stripSensitive(msg) {
+  if (typeof msg !== 'string') return String(msg ?? '');
+  return msg
+    .replace(/ghp_[A-Za-z0-9]{20,}/g, '<TOKEN>')
+    .replace(/glpat-[A-Za-z0-9\-]{20,}/g, '<TOKEN>')
+    .replace(/Bearer\s+\S+/gi, 'Bearer <TOKEN>');
+}
+
+function handleAdmError(err) {
+  // String error
+  if (typeof err === 'string') {
+    return new AdmError('unknown', err, 1, 'Type /help for available commands.');
+  }
+
+  // Network errors
+  if (err.code === 'ENOTFOUND' || err.code === 'ECONNREFUSED' || err.code === 'ETIMEDOUT') {
+    return new AdmError('network', 'Network error. Check your internet connection.', 1, 'Check your internet connection and try again.');
+  }
+
+  // Auth errors (401/403 without rate limit)
+  if (err.status === 401) {
+    return new AdmError('auth', stripSensitive('Authentication failed. Token may be expired or invalid.'), 1, 'Run /connect to reconnect.');
+  }
+
+  if (err.status === 403) {
+    if (err.headers && err.headers['x-ratelimit-remaining'] === '0') {
+      return new AdmError('rate_limit', 'GitHub API rate limit exceeded.', 1, 'Wait a few minutes and try again.');
+    }
+    return new AdmError('auth', stripSensitive('Authentication failed. Token may be expired or invalid.'), 1, 'Run /connect to reconnect.');
+  }
+
+  // Not found
+  if (err.status === 404) {
+    return new AdmError('not_found', 'Resource not found.', 1, 'Check the repository/PR number and your permissions.');
+  }
+
+  // User errors — validation, missing arguments
+  const msg = stripSensitive(err.message || 'An unexpected error occurred.');
+  if (/missing required argument|argument.*required|must provide/i.test(msg)) {
+    return new AdmError('user_error', msg, 2, 'Type /help for available commands.');
+  }
+
+  // Unknown / fallback
+  return new AdmError('unknown', msg, 1, 'If this persists, file an issue at https://github.com/adm-cli/adm/issues.');
+}
+
+function formatError(err) {
+  if (err instanceof AdmError) {
+    let msg = `Error: ${err.message}`;
+    if (err.remediation) {
+      msg += `\n  → ${err.remediation}`;
+    }
+    return msg;
+  }
+  // Plain Error or anything else
+  return `Error: ${err.message || String(err)}`;
+}
+
+module.exports = { AdmError, handleAdmError, formatError };