@crystalplatforms/adm 0.2.3 → 0.3.0

package/src/reports.js

@@ -0,0 +1,37 @@
+// Report persistence (owner decision, 0.3.x): every report ADM generates
+// (wizard install, ADM_TOOLS install, upgrade, uninstall) is written to the
+// global cache <configDir>/reports/ — one file per run.
+//
+// Owner requirement: if the config dir itself does not exist the save FAILS
+// LOUDLY (the caller shows a ⚠ line) — ADM must not silently skip
+// persistence and must not resurrect ~/.adm just to store a report. The
+// reports/ subfolder IS auto-created when the config dir exists.
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// <configDir>/reports — same resolution rules as the registry/config dir.
+function reportsDir(opts = {}) {
+  const dir = opts.configDir || process.env.ADM_CONFIG_DIR || path.join(opts.home || os.homedir(), '.adm');
+  return path.join(dir, 'reports');
+}
+
+// saveReport(kind, body, opts) → { file } on success, { error } when the
+// config dir is missing (nothing is written, nothing auto-created).
+function saveReport(kind, body, opts = {}) {
+  const fsMod = opts.fs || fs;
+  const dir = reportsDir(opts);
+  const configDirPath = path.dirname(dir);
+  if (!fsMod.existsSync(configDirPath)) {
+    return { error: `cannot save report: ${configDirPath} does not exist` };
+  }
+  fsMod.mkdirSync(dir, { recursive: true });
+  const stamp = (opts.now || new Date()).toISOString()
+    .replace(/[:.]/g, '-')
+    .slice(0, 19); // 2026-11-11T15-42-08
+  const file = path.join(dir, `report-${stamp}.txt`);
+  fsMod.writeFileSync(file, String(body), 'utf8');
+  return { file };
+}
+
+module.exports = { saveReport, reportsDir };

package/src/router.js

@@ -0,0 +1,157 @@
+const { COMMANDS, AUTOMATION_HINTS } = require('./commands');
+const { getVersion } = require('./commands/version');
+const { showHelp, renderCommandLines } = require('./commands/help');
+const { runFeedback } = require('./commands/feedback');
+const { runConfig } = require('./commands/config');
+const { runUninstall } = require('./commands/uninstall');
+const { runUpgrade } = require('./upgrade');
+const { runDotfilesSync } = require('./commands/dotfiles');
+const { runPlan } = require('./install/plan');
+const { runInstall } = require('./install/run');
+const { runWizard } = require('./setup/wizard');
+const { legacyCleanup } = require('./legacy-cleanup');
+const { closestMatches } = require('./utils/closest-match');
+
+function knownTokens() {
+  const tokens = [];
+  for (const cmd of COMMANDS) {
+    tokens.push(cmd.name);
+    for (const alias of cmd.aliases || []) tokens.push(alias);
+  }
+  return tokens;
+}
+
+function usageError(message, err) {
+  const lines = [
+    message,
+    '',
+    'Valid commands:',
+    ...renderCommandLines(),
+  ];
+  err(lines.join('\n'));
+  return 1;
+}
+
+function route(argv, deps = {}) {
+  const log = deps.log || (s => process.stdout.write(s + '\n'));
+  const err = deps.err || (s => process.stderr.write(s + '\n'));
+  const tty = deps.tty !== undefined ? deps.tty : Boolean(process.stdin.isTTY);
+
+  // ── adm (no args) ────────────────────────────────────────────
+  if (argv.length === 0) {
+    // Non-interactive tool planning / real install: ADM_TOOLS=<id,id>
+    if (process.env.ADM_TOOLS) {
+      if (process.env.ADM_DRY_RUN === '1') {
+        return runPlan(process.env.ADM_TOOLS, { log, err });
+      }
+      return runInstall(process.env.ADM_TOOLS, { log, err });
+    }
+    if (!tty) {
+      // Never hang: stdin is not a terminal — the wizard needs a TTY (#26 guard).
+      const lines = [
+        'adm needs a terminal for interactive mode.',
+        '',
+        ...AUTOMATION_HINTS,
+        '',
+        'Valid commands:',
+        ...renderCommandLines(),
+      ];
+      err(lines.join('\n'));
+      return 1;
+    }
+    // Interactive setup wizard (#30): categories → tools → install → git step.
+    return (deps.wizard || runWizard)({ log, err, tty });
+  }
+
+  const head = argv[0];
+  const rest = argv.slice(1);
+
+  // ── help ─────────────────────────────────────────────────────
+  if (head === 'help' || head === '--help' || head === '-h') {
+    log(showHelp());
+    return 0;
+  }
+
+  // ── -v / --version ───────────────────────────────────────────
+  if (head === '-v' || head === '--version') {
+    log(getVersion());
+    return 0;
+  }
+
+  // ── feedback ─────────────────────────────────────────────────
+  if (head === 'feedback') {
+    return runFeedback({ log });
+  }
+
+  // ── config [--json] ──────────────────────────────────────────
+  if (head === 'config') {
+    const json = rest.includes('--json');
+    const badFlags = rest.filter(f => f !== '--json');
+    if (badFlags.length > 0) return usageError(`Unknown flag for "config": ${badFlags.join(', ')}`, err);
+    return runConfig({ json, log, err });
+  }
+
+  // ── uninstall ────────────────────────────────────────────────
+  if (head === 'uninstall') {
+    if (rest.length > 0) return usageError(`"uninstall" takes no arguments, got: ${rest.join(' ')}`, err);
+    return runUninstall({ log, err });
+  }
+
+  // ── upgrade / update (#32) ───────────────────────────────────
+  if (head === 'upgrade' || head === 'update') {
+    return runUpgrade(rest, { log, err });
+  }
+
+  // ── dotfiles sync ────────────────────────────────────────────
+  if (head === 'dotfiles') {
+    if (rest[0] !== 'sync') {
+      return usageError(`Unknown subcommand for "dotfiles": ${rest[0] || '(none)'}\nValid: adm dotfiles sync`, err);
+    }
+    return runDotfilesSync(rest.slice(1), { log, err });
+  }
+
+  // ── unknown command ──────────────────────────────────────────
+  const suggestions = closestMatches(head, knownTokens());
+  const lines = [`Unknown command: ${head}`];
+  if (suggestions.length > 0) lines.push(`Did you mean: ${suggestions.join(', ')}?`);
+  lines.push('');
+  lines.push('Valid commands:');
+  lines.push(...renderCommandLines());
+  err(lines.join('\n'));
+  return 1;
+}
+
+// Run one ADM invocation end-to-end and return the process exit code.
+// Legacy cleanup runs on first start of every command except "-v" (kept
+// machine-parsable) and the no-args notices.
+async function main(argv, deps = {}) {
+  const log = deps.log || (s => process.stdout.write(s + '\n'));
+  const err = deps.err || (s => process.stderr.write(s + '\n'));
+  const tty = deps.tty !== undefined ? deps.tty : Boolean(process.stdin.isTTY);
+
+  const first = argv[0];
+  // Cleanup runs on every start except "-v" (machine-parsable output) and
+  // "uninstall" (it removes the whole config dir anyway; writing the cleanedAt
+  // marker would resurrect the dir before the removal).
+  const skipCleanup = first === '-v' || first === '--version' || first === 'uninstall';
+
+  if (!skipCleanup) {
+    // Keep machine-parsable output clean: the cleanup notice goes to stderr
+    // when the invoked command prints JSON.
+    const machineOutput = first === 'config' && argv.includes('--json');
+    try {
+      await legacyCleanup({ log: machineOutput ? err : log });
+    } catch {
+      // Cleanup must never block a command from running.
+    }
+  }
+
+  try {
+    return (deps.route || route)(argv, { log, err, tty });
+  } catch (e) {
+    err(`ADM failed: ${e && e.message ? e.message : e}`);
+    return 2;
+  }
+}
+
+module.exports = { route, main };

package/src/setup/catalog.js

@@ -1,13 +1,13 @@
-const data = require('../data/extensions.json');
-
-function loadCatalog() {
-  return data.categories;
-}
-
-function getToolsByCategories(categoryIds) {
-  const categories = loadCatalog();
-  const selected = categories.filter(cat => categoryIds.includes(cat.id));
-  return selected.flatMap(cat => cat.tools);
-}
-
-module.exports = { loadCatalog, getToolsByCategories };
+const data = require('../data/extensions.json');
+
+function loadCatalog() {
+  return data.categories;
+}
+
+function getToolsByCategories(categoryIds) {
+  const categories = loadCatalog();
+  const selected = categories.filter(cat => categoryIds.includes(cat.id));
+  return selected.flatMap(cat => cat.tools);
+}
+
+module.exports = { loadCatalog, getToolsByCategories };

package/src/setup/git-step.js

@@ -0,0 +1,128 @@
+const { readConfig, writeConfig } = require('../config');
+
+// Wizard's git step (#30, story 10): user.name + user.email, nothing else
+// (SSH/GPG intentionally cut). Defaults come from the current git config;
+// values are written via `git config --global` AND stored in
+// ~/.adm/config.json under { git: { name, email } }.
+
+// Reads one key from global git config ("" when unset). exec injectable.
+function readGitValue(key, { execFunc } = {}) {
+  const exec = execFunc || require('child_process').exec;
+  return new Promise(resolve => {
+    exec(`git config --global ${key}`, { shell: 'sh' }, (err, stdout) => {
+      resolve(err ? '' : String(stdout || '').trim());
+    });
+  });
+}
+
+function gitSetCommand(key, value) {
+  const escaped = String(value).replace(/"/g, '\\"');
+  return `git config --global ${key} "${escaped}"`;
+}
+
+function setGitValue(key, value, { execFunc } = {}) {
+  const exec = execFunc || require('child_process').exec;
+  return new Promise((resolve, reject) => {
+    exec(gitSetCommand(key, value), { shell: 'sh' }, err => (err ? reject(err) : resolve()));
+  });
+}
+
+async function readSavedGit({ readConfigFn, configDir } = {}) {
+  try {
+    const cfg = await (readConfigFn || readConfig)(configDir);
+    return (cfg && cfg.git) || {};
+  } catch {
+    return {};
+  }
+}
+
+// Runs the git step. Returns:
+//   { status: 'existing', name, email }  both already set — nothing asked
+//   { status: 'declined-before' }        user declined in a previous run
+//   { status: 'skipped' }                user declined now (remembered)
+//   { status: 'configured', name, email } written via git config + config.json
+async function runGitStep(opts = {}) {
+  const {
+    execFunc,
+    prompt = require('inquirer').prompt,
+    log = () => {},
+    readConfigFn,
+    writeConfigFn,
+    configDir,
+  } = opts;
+
+  const fullConfig = await safeReadAll(readConfigFn, configDir);
+  const savedGit = (fullConfig && fullConfig.git) || {};
+
+  const currentName = (await readGitValue('user.name', { execFunc })) || savedGit.name || '';
+  const currentEmail = (await readGitValue('user.email', { execFunc })) || savedGit.email || '';
+
+  if (currentName && currentEmail) {
+    log(`git already configured: ${currentName} <${currentEmail}>`);
+    return { status: 'existing', name: currentName, email: currentEmail };
+  }
+
+  // A previous "no" is final — never ask again (unless git is configured now).
+  if (savedGit.setupDeclined) {
+    return { status: 'declined-before' };
+  }
+
+  const { proceed } = await prompt([{
+    type: 'confirm',
+    name: 'proceed',
+    message: 'Configure git identity (user.name / user.email) now?',
+    default: true,
+  }]);
+  if (!proceed) {
+    // Remember the decline — the wizard must not re-ask on every start.
+    try {
+      const writer = writeConfigFn || ((cfg, dir) => writeConfig(cfg, dir));
+      await writer({ ...fullConfig, git: { ...savedGit, setupDeclined: true } }, configDir);
+    } catch { /* config write must never break the wizard */ }
+    return { status: 'skipped' };
+  }
+
+  const answers = await prompt([
+    {
+      type: 'input',
+      name: 'name',
+      message: 'git user.name:',
+      default: currentName,
+      validate: v => String(v).trim().length > 0 || 'name cannot be empty',
+    },
+    {
+      type: 'input',
+      name: 'email',
+      message: 'git user.email:',
+      default: currentEmail,
+      validate: v => /.+@.+/.test(String(v).trim()) || 'enter a valid email',
+    },
+  ]);
+
+  const name = answers.name.trim();
+  const email = answers.email.trim();
+  await setGitValue('user.name', name, { execFunc });
+  await setGitValue('user.email', email, { execFunc });
+
+  // Persist in ADM config too (config.json), merged with whatever is saved.
+  const writer = writeConfigFn || ((cfg, dir) => writeConfig(cfg, dir));
+  const saved = await readSavedGit({ readConfigFn, configDir });
+  const full = await safeReadAll(readConfigFn, configDir);
+  await writer({
+    ...full,
+    git: { ...saved, name, email },
+  }, configDir);
+
+  return { status: 'configured', name, email };
+}
+
+async function safeReadAll(readConfigFn, configDir) {
+  try {
+    const read = readConfigFn || readConfig;
+    return (await read(configDir)) || {};
+  } catch {
+    return {};
+  }
+}
+
+module.exports = { runGitStep, readGitValue, setGitValue, gitSetCommand };

package/src/setup/loader.js

@@ -0,0 +1,108 @@
+// Loader — the dots_12 braille animation (56 frames), ADM's own spinner.
+// Replaces the ASCII \|/- spinner everywhere ADM "works": startup
+// (Preparing…), tool-status scan (Scanning…), per-tool install lines.
+//
+// Frames: dots_12 from cli-spinners/cli-loaders — MIT license.
+//   https://cliloaders.com/dots_12 · https://github.com/cbmongithub/cli-loaders
+//   (frames also mirrored in the repo root loader.txt)
+//
+// Wrap-aware: install lines carry the FULL command in parentheses, so a
+// frame can span several terminal rows — every repaint erases ALL rows the
+// previous frame occupied (a plain `\r\x1b[2K` would leave leftovers).
+//
+// The terminal cursor is HIDDEN while the loader animates (it would blink
+// on top of the frame) and restored on every finish/stop.
+const chalk = require('chalk');
+
+const FRAMES = [
+  '⢀⠀', '⡀⠀', '⠄⠀', '⢂⠀', '⡂⠀', '⠅⠀', '⢃⠀', '⡃⠀', '⠍⠀', '⢋⠀', '⡋⠀',
+  '⠍⠁', '⢋⠁', '⡋⠁', '⠍⠉', '⠋⠉', '⠋⠉', '⠉⠙', '⠉⠙', '⠉⠩', '⠈⢙', '⠈⡙',
+  '⢈⠩', '⡀⢙', '⠄⡙', '⢂⠩', '⡂⢘', '⠅⡘', '⢃⠨', '⡃⢐', '⠍⡐', '⢋⠠', '⡋⢀',
+  '⠍⡁', '⢋⠁', '⡋⠁', '⠍⠉', '⠋⠉', '⠋⠉', '⠉⠙', '⠉⠙', '⠉⠩', '⠈⢙', '⠈⡙',
+  '⠈⠩', '⠀⢙', '⠀⡙', '⠀⠩', '⠀⢘', '⠀⡘', '⠀⠨', '⠀⢐', '⠀⡐', '⠀⠠', '⠀⢀',
+  '⠀⡀',
+];
+
+function stripAnsi(s) {
+  return String(s).replace(/\x1b\[[0-9;]*[A-Za-z]/g, '');
+}
+
+// Same method contract as miniSpinner (start/text/succeed/fail/info/stop),
+// so the wizard's spinnerFactory injection works with either.
+// Owner decision: the frame + text render in the terminal's default color
+// (white) — no cyan/blue tint.
+function loader(text, opts = {}) {
+  const stdout = opts.stdout || process.stdout;
+  const interval = opts.interval || 80;
+  const frames = opts.frames || FRAMES;
+  let current = text;
+  let frame = 0;
+  let timer = null;
+  let active = false;
+  let rows = 0; // visual rows the currently painted frame occupies
+  let startedAt = 0;
+
+  const cols = () => Math.max(20, (stdout.columns || 80) - 1);
+
+  // erase-string for the currently painted frame
+  const eraseStr = () => {
+    if (rows <= 0) return '';
+    return (rows > 1 ? `\x1b[${rows - 1}A` : '') + '\r\x1b[J';
+  };
+
+  // ONE atomic write per repaint (erase + content together) — separate
+  // writes flicker on consoles without double buffering.
+  const paint = () => {
+    if (!active) return;
+    const elapsed = Date.now() - startedAt;
+    // long installs show the elapsed time — same contract as before
+    const time = elapsed >= 3000 ? chalk.dim(` [${Math.floor(elapsed / 1000)}s]`) : '';
+    const line = `${frames[frame % frames.length]} ${current}${time}`;
+    stdout.write(eraseStr() + line);
+    rows = Math.max(1, Math.ceil(stripAnsi(line).length / cols()));
+    frame++;
+  };
+
+  const stopPaint = () => {
+    if (timer) { clearInterval(timer); timer = null; }
+  };
+
+  const finish = (mark, msg) => {
+    stopPaint();
+    active = false;
+    // cursor back + erase + status line in ONE write — no flicker
+    stdout.write('\x1b[?25h' + eraseStr() + `${mark} ${msg || current}\n`);
+    rows = 0;
+  };
+
+  return {
+    start(t) {
+      if (t) current = t;
+      active = true;
+      frame = 0;
+      startedAt = Date.now();
+      const line = `${frames[frame % frames.length]} ${current}`;
+      stdout.write('\x1b[?25l' + (rows > 0 ? eraseStr() : '') + line);
+      rows = Math.max(1, Math.ceil(stripAnsi(line).length / cols()));
+      frame++;
+      timer = setInterval(paint, interval);
+      if (timer.unref) timer.unref();
+      return this;
+    },
+    text(t) { current = t; paint(); return this; },
+    succeed(msg) { finish(chalk.green('✓'), msg); return this; },
+    fail(msg) { finish(chalk.red('✗'), msg); return this; },
+    info(msg) { finish(chalk.yellow('i'), msg); return this; },
+    stop() {
+      stopPaint();
+      if (active) {
+        active = false;
+        stdout.write('\x1b[?25h' + eraseStr());
+        rows = 0;
+      }
+      return this;
+    },
+  };
+}
+
+module.exports = { loader, FRAMES };