@crystalplatforms/adm 0.2.3 → 0.3.0

package/scripts/completion/adm.zsh

@@ -1,27 +1,17 @@
 #compdef adm
+# v0.3 CLI surface — src/commands.js is the source of truth
 
 _adm() {
-  local -a commands subcommands opts
+  local -a commands
 
   commands=(
-    'help:Show command reference'
-    'exit:Exit ADM'
-    'clear:Clear message history'
-    'theme:List or switch themes'
-    'config:Show current configuration'
-    'status:Show git status'
-    'ai:Toggle AI mode or ask a question'
-    'model:Show or switch AI provider'
-    'setup:Launch extension setup wizard'
-    'connect:Connect to GitHub or GitLab'
-    'pr:Pull request operations'
-    'mr:Merge request operations (GitLab)'
-    'issue:List issues from connected platform'
-    'commit:Commit subcommands'
-    'clock:Show ASCII clock'
-    'dotfiles:Sync dotfiles from repo'
-    'uninstall:Remove ADM CLI config'
-    'plugins:List loaded plugins'
+    'help:Show available commands'
+    '-v:Print ADM version'
+    'feedback:Show how to report bugs and ideas'
+    'config:Show ADM config and detected environment'
+    'uninstall:Remove ADM data (~/.adm) and shell PATH entries'
+    'upgrade:Self-update ADM (alias: update)'
+    'dotfiles:Sync dotfiles from a git repo'
   )
 
   _arguments -C \
@@ -34,53 +24,26 @@ _adm() {
       ;;
     args)
       case $words[1] in
-        setup)
-          _arguments '--dry-run[Preview planned actions without executing]'
+        config)
+          _arguments '--json[Machine-readable output]'
           ;;
-        connect)
-          local -a connect_subs
-          connect_subs=('github:Connect GitHub account' 'gitlab:Connect GitLab account' 'list:List connected services' 'disconnect:Disconnect a service')
-          if (( CURRENT == 2 )); then
-            _describe 'subcommand' connect_subs
-          else
-            case $words[2] in
-              github|gitlab) _arguments '--token[Access token]:token:' ;;
-            esac
-          fi
-          ;;
-        pr)
-          local -a pr_subs
-          pr_subs=('list:List open pull requests' 'draft:Create a draft PR' 'comment:Comment on a pull request')
-          if (( CURRENT == 2 )); then
-            _describe 'subcommand' pr_subs
-          fi
-          ;;
-        mr)
-          local -a mr_subs
-          mr_subs=('list:List open merge requests' 'draft:Create a draft MR' 'comment:Comment on a merge request')
-          if (( CURRENT == 2 )); then
-            _describe 'subcommand' mr_subs
-          fi
-          ;;
-        issue)
-          _arguments '1:subcommand:(list)'
-          ;;
-        commit)
-          _arguments '1:subcommand:(suggest)'
+        upgrade|update)
+          _arguments \
+            '--check[Only check whether a newer version exists]' \
+            '--dry-run[Print the upgrade plan without changing anything]'
           ;;
         dotfiles)
           local -a dotfiles_subs
-          dotfiles_subs=('sync:Clone/pull dotfiles repo and symlink files')
+          dotfiles_subs=('sync:Sync dotfiles from a git repo into your home dir')
           if (( CURRENT == 2 )); then
             _describe 'subcommand' dotfiles_subs
+          else
+            _arguments \
+              '--repo[Dotfiles git repo URL]:url:' \
+              '--copy[Copy files instead of symlinking]' \
+              '--only[Comma-separated file list]:names:'
           fi
           ;;
-        theme)
-          _arguments '1:theme:(dark light cyberpunk nord forest monokai)'
-          ;;
-        model)
-          _arguments '1:provider:(glm-free glm-pro openai anthropic ollama list)'
-          ;;
       esac
       ;;
   esac

package/scripts/install.js

@@ -1,8 +1,8 @@
-#!/usr/bin/env node
-const chalk = require('chalk');
-console.log('');
-console.log(chalk.green('  ADM CLI installed successfully!'));
-console.log('');
-console.log('  Run ' + chalk.bold('adm') + ' to launch the TUI.');
-console.log('  Type ' + chalk.bold('/download') + ' inside ADM to set up your dev environment.');
-console.log('');
+#!/usr/bin/env node
+const chalk = require('chalk');
+console.log('');
+console.log(chalk.green('  ADM CLI installed successfully!'));
+console.log('');
+console.log('  Run ' + chalk.bold('adm') + ' to launch the TUI.');
+console.log('  Type ' + chalk.bold('/download') + ' inside ADM to set up your dev environment.');
+console.log('');

package/src/commands/config.js

@@ -0,0 +1,66 @@
+const { detectEnvironment, formatEnvironment } = require('../platform');
+const { configDir, readConfig } = require('../config');
+const { getVersion } = require('./version');
+
+// `adm config` — human-readable view.
+// `adm config --json` — machine-readable view with a frozen key set:
+//   version, configDir, configFile, os, distro, distroVersion,
+//   manager, arch, isWSL, shell, rcFile
+async function runConfig({ json, log, err } = {}) {
+  log = log || (s => process.stdout.write(s + '\n'));
+  err = err || (s => process.stderr.write(s + '\n'));
+
+  let saved = {};
+  try {
+    saved = await readConfig();
+  } catch {
+    saved = {};
+  }
+
+  const dir = configDir();
+  const file = require('path').join(dir, 'config.json');
+  const env = detectEnvironment();
+
+  if (json) {
+    log(JSON.stringify({
+      version: getVersion(),
+      configDir: dir,
+      configFile: file,
+      os: env.os,
+      distro: env.distro,
+      distroVersion: env.distroVersion,
+      manager: env.manager,
+      arch: env.arch,
+      isWSL: env.isWSL,
+      shell: env.shell,
+      rcFile: env.rcFile,
+    }, null, 2));
+    return 0;
+  }
+
+  const lines = [
+    `ADM v${getVersion()}`,
+    '',
+    'Paths:',
+    `  Config dir:   ${dir}`,
+    `  Config file:  ${file}`,
+    '',
+    'Environment:',
+    formatEnvironment(env),
+    '',
+    'Saved config:',
+  ];
+  const keys = Object.keys(saved);
+  if (keys.length === 0) {
+    lines.push('  (empty)');
+  } else {
+    for (const key of keys) {
+      const value = JSON.stringify(saved[key]);
+      lines.push(`  ${key}: ${value.length > 80 ? value.slice(0, 77) + '...' : value}`);
+    }
+  }
+  log(lines.join('\n'));
+  return 0;
+}
+
+module.exports = { runConfig };

package/src/commands/dotfiles.js

@@ -2,71 +2,88 @@ const fs = require('fs');
 const path = require('path');
 const chalk = require('chalk');
 const ora = require('ora');
-const child_process = require('child_process');
-const { readConfig, ensureConfigDir } = require('../config');
+const { readConfig } = require('../config');
 const { syncDotfiles } = require('../utils/dotfiles-sync');
 
-/**
- * /dotfiles sync — clones/pulls dotfiles repo and synchronizes files
- *
- * Options:
- *   repo: string — dotfiles repo URL (overrides config)
- *   copy: boolean — copy instead of symlinking
- *   only: string[] — file filter (e.g. ['bashrc', 'zshrc'])
- */
-async function syncDotfilesCommand(options = {}) {
+// `adm dotfiles sync [--repo <url>] [--copy] [--only <name,name>]`
+// Port of the old logic: clones/pulls the dotfiles repo into ~/.adm/dotfiles,
+// then symlinks (or copies) known files into the home directory.
+async function runDotfilesSync(flags = [], { log, err } = {}) {
+  log = log || (s => process.stdout.write(s + '\n'));
+  err = err || (s => process.stderr.write(s + '\n'));
   const configDir = process.env.ADM_CONFIG_DIR || path.join(require('os').homedir(), '.adm');
   const dotfilesDir = path.join(configDir, 'dotfiles');
 
-  // Get repo URL
+  // ── parse flags ──────────────────────────────────────────────
+  const options = {};
+  const bad = [];
+  for (let i = 0; i < flags.length; i++) {
+    const f = flags[i];
+    if (f === '--help' || f === '-h') {
+      log('Usage: adm dotfiles sync [--repo <url>] [--copy] [--only <name,name>]');
+      log('');
+      log('  --repo <url>      dotfiles git repo (or set dotfiles.repo in the config)');
+      log('  --copy            copy files instead of symlinking');
+      log('  --only <name,name>  sync only these files (e.g. --only bashrc,zshrc)');
+      return 0;
+    }
+    if (f === '--repo') options.repo = flags[++i];
+    else if (f === '--copy') options.copy = true;
+    else if (f === '--only') options.only = String(flags[++i] || '').split(',').map(s => s.trim()).filter(Boolean);
+    else bad.push(f);
+  }
+  if (bad.length > 0) {
+    err(`Unknown flags for "dotfiles sync": ${bad.join(', ')}\nValid flags: --repo <url>, --copy, --only <name,name>`);
+    return 1;
+  }
+
+  // ── resolve repo URL ─────────────────────────────────────────
   let repoUrl = options.repo;
   if (!repoUrl) {
     const config = await readConfig();
     repoUrl = config?.dotfiles?.repo;
   }
   if (!repoUrl) {
-    throw new Error('No dotfiles repo URL. Use --repo or set in config (dotfiles.repo).');
+    err('No dotfiles repo URL. Pass --repo <url> or set it in the config (dotfiles.repo).\nExample: adm dotfiles sync --repo https://github.com/you/dotfiles');
+    return 1;
   }
 
-  // Clone or pull repo
+  // ── clone or pull ────────────────────────────────────────────
+  const { execFileSync } = require('child_process');
   const s = ora('Syncing dotfiles...').start();
   try {
     if (fs.existsSync(path.join(dotfilesDir, '.git'))) {
       s.text = 'Pulling updates...';
-      child_process.execSync(`git pull`, { cwd: dotfilesDir, stdio: 'pipe' });
+      execFileSync('git', ['pull'], { cwd: dotfilesDir, stdio: 'pipe' });
     } else {
-      // Remove empty directory if it exists
       if (fs.existsSync(dotfilesDir)) {
         fs.rmSync(dotfilesDir, { recursive: true, force: true });
       }
       s.text = 'Cloning dotfiles repo...';
-      child_process.execSync(`git clone ${repoUrl} ${dotfilesDir}`, { stdio: 'pipe' });
+      fs.mkdirSync(configDir, { recursive: true });
+      execFileSync('git', ['clone', repoUrl, dotfilesDir], { stdio: 'pipe' });
     }
     s.succeed('Dotfiles repo ready');
-  } catch (err) {
-    s.fail(`Git error: ${err.message}`);
-    throw err;
+  } catch (e) {
+    s.fail(`Git error: ${e.message}`);
+    return 2;
   }
 
-  // Sync files
-  console.log(chalk.bold('\n  Syncing files:'));
+  // ── sync files ───────────────────────────────────────────────
+  log(chalk.bold('\n  Syncing files:'));
   const result = await syncDotfiles({
     repo: repoUrl,
     copy: options.copy,
     only: options.only,
   });
 
-  // Summary
   const total = result.symlinked.length + result.copied.length;
-  console.log(chalk.bold(`\n  Done: ${total} files synced`));
-  if (result.skipped.length > 0) {
-    console.log(chalk.yellow(`  Skipped: ${result.skipped.join(', ')}`));
-  }
-  if (result.errors.length > 0) {
-    console.log(chalk.red(`  Errors: ${result.errors.map(e => e.file).join(', ')}`));
-  }
+  log(chalk.bold(`\n  Done: ${total} file${total === 1 ? '' : 's'} synced`));
+  if (result.skipped.length > 0) log(chalk.yellow(`  Skipped: ${result.skipped.join(', ')}`));
+  if (result.backedUp.length > 0) log(chalk.blue(`  Backed up: ${result.backedUp.join(', ')}`));
+  if (result.errors.length > 0) log(chalk.red(`  Errors: ${result.errors.map(e => e.file).join(', ')}`));
 
-  return result;
+  return result.errors.length > 0 ? 2 : 0;
 }
 
-module.exports = { syncDotfilesCommand };
+module.exports = { runDotfilesSync };

package/src/commands/feedback.js

@@ -0,0 +1,12 @@
+const REPO_ISSUES = 'https://github.com/CrystalPlatforms/ADM-CLI/issues';
+
+function runFeedback({ log } = {}) {
+  log = log || (s => process.stdout.write(s + '\n'));
+  log('Found a bug or an idea? Open an issue:');
+  log(`  ${REPO_ISSUES}`);
+  log('');
+  log('Include: OS + distro, shell, the command you ran, and the full output.');
+  return 0;
+}
+
+module.exports = { runFeedback, REPO_ISSUES };

package/src/commands/help.js

@@ -0,0 +1,33 @@
+const { COMMANDS, AUTOMATION_HINTS } = require('../commands');
+
+// Renders one "  <name>  <summary>" line per COMMANDS table entry.
+// This is the only place help text is produced — the table is the single
+// source of truth (anti-drift).
+function renderCommandLines() {
+  const width = Math.max(...COMMANDS.map(c => c.name.length));
+  const flagsWidth = Math.max(...COMMANDS.map(c => c.flags ? c.flags.join('|').length : 0));
+  const labelWidth = width + (flagsWidth > 0 ? flagsWidth + 3 : 0);
+  return COMMANDS.map(c => {
+    const flags = c.flags ? ` [${c.flags.join('|')}]` : '';
+    return `  ${(c.name + flags).padEnd(labelWidth)}  ${c.summary}`;
+  });
+}
+
+function showHelp() {
+  const lines = [
+    'ADM — lightweight, multi-platform developer environment installer',
+    '',
+    'Usage:',
+    '  adm <command> [flags]',
+    '',
+    'Commands:',
+    ...renderCommandLines(),
+    '',
+    ...AUTOMATION_HINTS,
+    '',
+    'Docs: https://github.com/CrystalPlatforms/ADM-CLI#readme',
+  ];
+  return lines.join('\n');
+}
+
+module.exports = { showHelp, renderCommandLines };

package/src/commands/uninstall.js

@@ -1,72 +1,91 @@
-const fs = require('fs').promises;
+const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { spawn } = require('child_process');
-const chalk = require('chalk');
+const { saveReport } = require('../reports');
+const { getVersion } = require('../commands/version');
 
-async function uninstall() {
-  const configDir = process.env.ADM_CONFIG_DIR || path.join(os.homedir(), '.adm');
+// Removes ADM's footprint:
+//   1. the config dir (~/.adm, or ADM_CONFIG_DIR)
+//   2. PATH entries ADM wrote into shell rc files (marker lines)
+// Idempotent by contract: removing nothing still exits 0 ("already removed").
+const RC_FILES = ['.bashrc', '.bash_profile', '.zprofile', '.zshrc', '.profile'];
+const RC_MARKERS = ['# adm-cli', 'adm completion', 'adm-cli npm path'];
 
-  console.log(chalk.yellow('  Uninstalling ADM CLI...\n'));
-
-  // Remove config directory
+function cleanRcFile(rcPath) {
+  let content;
   try {
-    await fs.rm(configDir, { recursive: true, force: true });
-    console.log(chalk.green(`  Removed config directory: ${configDir}`));
-  } catch (err) {
-    if (err.code !== 'ENOENT') {
-      console.log(chalk.red(`  Failed to remove config: ${err.message}`));
+    content = fs.readFileSync(rcPath, 'utf8');
+  } catch {
+    return { cleaned: false, lines: 0 };
+  }
+  const lines = content.split('\n');
+  const kept = [];
+  let removed = 0;
+  for (let i = 0; i < lines.length; i++) {
+    if (RC_MARKERS.some(m => lines[i].includes(m))) {
+      removed++;
+      // The PATH line ADM appends right after its marker goes too —
+      // leave zero trace (v0.3 installer layout).
+      if (lines[i + 1] && /^\s*export\s+PATH=/.test(lines[i + 1])) {
+        i++;
+        removed++;
+      }
+      continue;
     }
+    kept.push(lines[i]);
   }
+  if (removed === 0) {
+    return { cleaned: false, lines: 0 };
+  }
+  fs.writeFileSync(rcPath, kept.join('\n'), 'utf8');
+  return { cleaned: true, lines: removed };
+}
 
-  // Uninstall npm package
-  await new Promise((resolve) => {
-    const child = spawn('npm', ['uninstall', '-g', '@crystalgames/adm'], { stdio: 'pipe' });
-    child.on('close', (code) => {
-      if (code === 0) {
-        console.log(chalk.green('  Removed npm package: @crystalgames/adm'));
-      } else {
-        console.log(chalk.yellow('  npm uninstall failed — package may have been installed differently'));
-      }
-      resolve();
-    });
-  });
+async function runUninstall({ log, err, configDir: cfgDir, home } = {}) {
+  log = log || (s => process.stdout.write(s + '\n'));
+  err = err || (s => process.stderr.write(s + '\n'));
+  const dir = cfgDir || process.env.ADM_CONFIG_DIR || path.join(home || os.homedir(), '.adm');
+  const homeDir = home || os.homedir();
 
-  // Remove binary (curl-installed)
-  const binaryPath = '/usr/local/bin/adm';
-  try {
-    await fs.rm(binaryPath, { force: true });
-    console.log(chalk.green(`  Removed binary: ${binaryPath}`));
-  } catch (err) {
-    if (err.code !== 'ENOENT') {
-      console.log(chalk.yellow(`  Could not remove binary: ${err.message}`));
+  const dirExisted = fs.existsSync(dir);
+  if (dirExisted) {
+    try {
+      fs.rmSync(dir, { recursive: true, force: true });
+    } catch (e) {
+      err(`ADM uninstall: failed to remove ${dir}: ${e.message}`);
+      return 2;
     }
   }
 
-  // Remove shell completions references
-  const shell = process.env.SHELL || '';
-  const rcFiles = [];
-  if (shell.includes('bash')) {
-    rcFiles.push(path.join(os.homedir(), '.bashrc'), path.join(os.homedir(), '.bash_profile'));
-  } else if (shell.includes('zsh')) {
-    rcFiles.push(path.join(os.homedir(), '.zshrc'));
+  const cleanedRcs = [];
+  for (const rc of RC_FILES) {
+    const result = cleanRcFile(path.join(homeDir, rc));
+    if (result.cleaned) cleanedRcs.push(`${rc} (${result.lines} line${result.lines === 1 ? '' : 's'})`);
   }
 
-  for (const rc of rcFiles) {
-    try {
-      let content = await fs.readFile(rc, 'utf8');
-      const cleaned = content.split('\n').filter(
-        line => !line.includes('adm completion') && !line.includes('source.*adm'),
-      ).join('\n');
-      if (content !== cleaned) {
-        await fs.writeFile(rc, cleaned, 'utf8');
-        console.log(chalk.green(`  Cleaned ADM references from ${rc}`));
-      }
-    } catch { /* skip missing rc files */ }
+  if (dirExisted) {
+    log(`Removed ${dir}`);
+  } else {
+    log(`${dir} already removed`);
+  }
+  if (cleanedRcs.length > 0) {
+    for (const rc of cleanedRcs) log(`Cleaned PATH entries from ~/${rc}`);
   }
 
-  console.log(chalk.green('\n  ADM CLI fully uninstalled.'));
-  return true;
+  log('ADM data removed. To uninstall the program itself, remove the npm package: npm rm -g @crystalplatforms/adm');
+
+  // Persist the uninstall report (owner decision: all reports are saved) —
+  // but the config dir is GONE by design, so the report lands in the OS
+  // temp dir instead of resurrecting ~/.adm.
+  const body = [
+    `ADM uninstall report — ${new Date().toISOString()}`,
+    `ADM ${getVersion()}`,
+    `config dir: ${dirExisted ? `removed (${dir})` : `already removed (${dir})`}`,
+    cleanedRcs.length ? `cleaned rc entries: ${cleanedRcs.join(', ')}` : 'no rc entries cleaned',
+  ].join('\n') + '\n';
+  const saved = saveReport('uninstall', body, { configDir: os.tmpdir() });
+  if (saved.file) log(`Uninstall report saved: ${saved.file}`);
+  return 0;
 }
 
-module.exports = { uninstall };
+module.exports = { runUninstall, RC_FILES, RC_MARKERS };

package/src/commands/version.js

@@ -0,0 +1,7 @@
+const pkg = require('../../package.json');
+
+function getVersion() {
+  return pkg.version;
+}
+
+module.exports = { getVersion };

package/src/commands.js

@@ -0,0 +1,26 @@
+// ── Single source of truth for the CLI surface (frozen contract) ──
+// Exit codes: 0 = success (incl. "nothing to do")
+//             1 = usage error (message enumerates the valid set)
+//             2 = execution failure
+const COMMANDS = [
+  { name: 'help', aliases: ['--help', '-h'], summary: 'Show available commands' },
+  { name: '-v', aliases: ['--version'], summary: 'Print ADM version' },
+  { name: 'feedback', summary: 'Show how to report bugs and ideas' },
+  { name: 'config', summary: 'Show ADM config and detected environment', flags: ['--json'] },
+  { name: 'uninstall', summary: 'Remove ADM data (~/.adm) and shell PATH entries' },
+  { name: 'upgrade', aliases: ['update'], summary: 'Self-update ADM (bundle: atomic swap · npm: prints the npm command)',
+    flags: ['--check', '--dry-run'] },
+  { name: 'dotfiles sync', summary: 'Sync dotfiles from a git repo into your home dir',
+    usage: 'adm dotfiles sync [--repo <url>] [--copy] [--only <name,name>]' },
+];
+
+const AUTOMATION_HINTS = [
+  'Automation:',
+  '  ADM_TOOLS=<id,id> adm               install the given tools (no prompts)',
+  '  ADM_DRY_RUN=1 ADM_TOOLS=<ids> adm   print the install plan only (no changes)',
+  ...(process.platform === 'win32' ? [
+    '  PowerShell:  $env:ADM_TOOLS="typescript,node"; adm   (then: $env:ADM_TOOLS=$null)',
+  ] : []),
+];
+
+module.exports = { COMMANDS, AUTOMATION_HINTS };

package/src/config/index.js

@@ -1,32 +1,32 @@
-const fs = require('fs').promises;
-const path = require('path');
-const os = require('os');
-
-function configDir() {
-  return process.env.ADM_CONFIG_DIR || path.join(os.homedir(), '.adm');
-}
-
-async function ensureConfigDir(dir) {
-  await fs.mkdir(dir, { recursive: true });
-}
-
-async function readConfig() {
-  const dir = configDir();
-  const file = path.join(dir, 'config.json');
-  try {
-    const data = await fs.readFile(file, 'utf8');
-    return JSON.parse(data);
-  } catch (err) {
-    if (err.code === 'ENOENT') return {};
-    throw err;
-  }
-}
-
-async function writeConfig(obj) {
-  const dir = configDir();
-  await ensureConfigDir(dir);
-  const file = path.join(dir, 'config.json');
-  await fs.writeFile(file, JSON.stringify(obj, null, 2), 'utf8');
-}
-
-module.exports = { configDir, readConfig, writeConfig, ensureConfigDir };
+const fs = require('fs').promises;
+const path = require('path');
+const os = require('os');
+
+function configDir() {
+  return process.env.ADM_CONFIG_DIR || path.join(os.homedir(), '.adm');
+}
+
+async function ensureConfigDir(dir) {
+  await fs.mkdir(dir, { recursive: true });
+}
+
+async function readConfig(dirOverride) {
+  const dir = dirOverride || configDir();
+  const file = path.join(dir, 'config.json');
+  try {
+    const data = await fs.readFile(file, 'utf8');
+    return JSON.parse(data);
+  } catch (err) {
+    if (err.code === 'ENOENT') return {};
+    throw err;
+  }
+}
+
+async function writeConfig(obj, dirOverride) {
+  const dir = dirOverride || configDir();
+  await ensureConfigDir(dir);
+  const file = path.join(dir, 'config.json');
+  await fs.writeFile(file, JSON.stringify(obj, null, 2), 'utf8');
+}
+
+module.exports = { configDir, readConfig, writeConfig, ensureConfigDir };