baldart 3.6.2

package/src/utils/state.js

@@ -0,0 +1,143 @@
+/**
+ * Consumer-side state tracking — `.baldart/state.json`.
+ *
+ * Centralised view of "what version is installed, when was it installed,
+ * when did we last update, when did we last push". Read by `baldart version`
+ * and the `/baldart-push` skill so the user always knows which framework
+ * version they are working against.
+ *
+ * The file is committed to the consumer's repo. It is never overwritten by
+ * `baldart update` — only mutated by the CLI commands that need to record
+ * an event.
+ *
+ * Schema (v1):
+ *   {
+ *     "state_version": 1,
+ *     "installed_version": "3.1.0",
+ *     "install_date": "2026-05-21T15:30:00.000Z",
+ *     "last_update_date": "2026-05-21T16:00:00.000Z",
+ *     "last_pushed_version": "3.0.0",
+ *     "last_push_date": "2026-05-21T17:00:00.000Z",
+ *     "framework_repo": "antbald/BALDART",
+ *     "history": [
+ *       { "ts": "...", "event": "install"|"update"|"push", "from": "x", "to": "y", "note": "..." }
+ *     ]
+ *   }
+ *
+ * History keeps the last 20 entries (rolling). Older entries are dropped.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const STATE_DIR = '.baldart';
+const STATE_FILE = path.join(STATE_DIR, 'state.json');
+const STATE_VERSION = 1;
+const HISTORY_LIMIT = 20;
+
+function defaultState() {
+  return {
+    state_version: STATE_VERSION,
+    installed_version: null,
+    install_date: null,
+    last_update_date: null,
+    last_pushed_version: null,
+    last_push_date: null,
+    framework_repo: null,
+    history: [],
+  };
+}
+
+function fullPath(cwd = process.cwd()) {
+  return path.join(cwd, STATE_FILE);
+}
+
+function load(cwd = process.cwd()) {
+  const full = fullPath(cwd);
+  if (!fs.existsSync(full)) return defaultState();
+  try {
+    const raw = JSON.parse(fs.readFileSync(full, 'utf8'));
+    // Merge with defaults so missing keys get sane values without crashing.
+    return { ...defaultState(), ...raw };
+  } catch (err) {
+    // Corrupt state file — log and fall back to defaults. Do not throw;
+    // versioning is auxiliary, never block the user's CLI flow.
+    return defaultState();
+  }
+}
+
+function save(state, cwd = process.cwd()) {
+  const dir = path.join(cwd, STATE_DIR);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const full = fullPath(cwd);
+  fs.writeFileSync(full, JSON.stringify(state, null, 2) + '\n', 'utf8');
+}
+
+function appendHistory(state, entry) {
+  const next = [...(state.history || []), { ts: new Date().toISOString(), ...entry }];
+  return next.slice(-HISTORY_LIMIT);
+}
+
+/**
+ * Record an install event. Idempotent: calling twice for the same version is a no-op
+ * other than the history entry.
+ */
+function recordInstall({ version, repo }, cwd = process.cwd()) {
+  const state = load(cwd);
+  const now = new Date().toISOString();
+  const wasFirstInstall = !state.installed_version;
+  state.installed_version = version;
+  state.framework_repo = repo || state.framework_repo || 'antbald/BALDART';
+  if (wasFirstInstall) state.install_date = now;
+  state.history = appendHistory(state, {
+    event: wasFirstInstall ? 'install' : 'reinstall',
+    to: version,
+  });
+  save(state, cwd);
+  return state;
+}
+
+function recordUpdate({ from, to }, cwd = process.cwd()) {
+  const state = load(cwd);
+  state.installed_version = to;
+  state.last_update_date = new Date().toISOString();
+  state.history = appendHistory(state, { event: 'update', from, to });
+  save(state, cwd);
+  return state;
+}
+
+function recordPush({ from, to, description }, cwd = process.cwd()) {
+  const state = load(cwd);
+  state.last_pushed_version = to;
+  state.last_push_date = new Date().toISOString();
+  state.installed_version = to; // a push bumps the local version too
+  state.history = appendHistory(state, { event: 'push', from, to, note: description });
+  save(state, cwd);
+  return state;
+}
+
+/**
+ * Read the framework's VERSION file from .framework/VERSION. Used by version /
+ * status commands to cross-check what the symlinked framework reports vs what
+ * the state file remembers.
+ */
+function readFrameworkVersion(cwd = process.cwd()) {
+  const versionPath = path.join(cwd, '.framework', 'VERSION');
+  if (!fs.existsSync(versionPath)) return null;
+  try {
+    return fs.readFileSync(versionPath, 'utf8').trim();
+  } catch (_) {
+    return null;
+  }
+}
+
+module.exports = {
+  load,
+  save,
+  recordInstall,
+  recordUpdate,
+  recordPush,
+  readFrameworkVersion,
+  STATE_FILE,
+  STATE_VERSION,
+};

package/src/utils/symlinks.js

@@ -0,0 +1,425 @@
+const fs = require('fs');
+const path = require('path');
+const UI = require('./ui');
+
+const FRAMEWORK_DIR = '.framework';
+// The Git subtree pulls the ENTIRE BALDART repo into `.framework/`, and the
+// repo itself nests its shippable content under a top-level `framework/`
+// directory. So everything we symlink or copy lives at
+// `.framework/framework/<path>`, never directly at `.framework/<path>`.
+// Use FRAMEWORK_PAYLOAD for any source path you want to reach inside the
+// installed framework — never bare FRAMEWORK_DIR.
+const FRAMEWORK_PAYLOAD = path.join(FRAMEWORK_DIR, 'framework');
+const CONFLICT_LOG = path.join('.baldart', 'skill-conflicts.json');
+
+/**
+ * Symlink management for BALDART.
+ *
+ * Design notes (v2.1.1+):
+ *
+ * - `AGENTS.md`, `agents/`, `.claude/agents/`, `.claude/commands/` are
+ *   **bulk symlinks**. They've worked this way since v1.0.0 and replacing
+ *   them is safe for users on canonical installations. If a user has
+ *   replaced one of these with a real file/dir (customisation), we WARN
+ *   and ask before overwriting — we no longer silently rename to `.backup`.
+ *
+ * - `.claude/skills/` is a **real directory the user owns**. Each framework
+ *   skill is symlinked **per-item** inside it. User-authored skills coexist
+ *   in the same dir. Name collisions are recorded in
+ *   `.baldart/skill-conflicts.json` and never overwritten.
+ */
+class SymlinkUtils {
+  constructor(cwd = process.cwd()) {
+    this.cwd = cwd;
+  }
+
+  // -----------------------------------------------------------------------
+  // Low-level helpers
+  // -----------------------------------------------------------------------
+
+  /**
+   * Create a single symlink at linkPath pointing at target.
+   * Modes:
+   *   safe: refuse to overwrite a non-symlink at linkPath (returns false).
+   *   prompt: ask the user before backing up a non-symlink (default).
+   *   force: legacy v2.0.x behaviour — backup non-symlink to .backup and replace.
+   */
+  async createSymlink(target, linkPath, opts = {}) {
+    const mode = opts.mode || 'prompt';
+    const relative = !!opts.relative;
+    const fullLinkPath = path.join(this.cwd, linkPath);
+    const fullTarget = relative
+      ? path.relative(path.dirname(fullLinkPath), path.join(this.cwd, target))
+      : path.join(this.cwd, target);
+
+    // Use lstat (not exists, which follows symlinks) so we detect broken
+    // symlinks — they fail fs.existsSync but still occupy the path and
+    // would make fs.symlinkSync below throw EEXIST.
+    let lstat = null;
+    try { lstat = fs.lstatSync(fullLinkPath); } catch (_) { /* path not present */ }
+
+    if (lstat) {
+      const stat = lstat;
+      if (stat.isSymbolicLink()) {
+        const current = fs.readlinkSync(fullLinkPath);
+        if (current === fullTarget) {
+          // Already correct — no-op.
+          return true;
+        }
+        // Existing symlink pointing elsewhere — replace silently
+        fs.unlinkSync(fullLinkPath);
+      } else {
+        // Real file or directory — user customisation
+        if (mode === 'safe') {
+          UI.warning(`Keeping existing (not a symlink): ${linkPath} — framework will not overwrite.`);
+          return false;
+        }
+        if (mode === 'prompt') {
+          UI.warning(`${linkPath} exists and is not a symlink (likely customised).`);
+          const ok = await UI.confirm(`Move it to ${linkPath}.backup and install the framework symlink?`, false);
+          if (!ok) {
+            UI.info(`Skipped ${linkPath}. Your customisation is preserved.`);
+            return false;
+          }
+        }
+        const backupPath = `${fullLinkPath}.backup`;
+        UI.warning(`Backing up existing: ${linkPath} → ${linkPath}.backup`);
+        fs.renameSync(fullLinkPath, backupPath);
+      }
+    }
+
+    fs.symlinkSync(fullTarget, fullLinkPath);
+    UI.success(`Symlink: ${linkPath} → ${target}`);
+    return true;
+  }
+
+  ensureDirectory(dir) {
+    const fullPath = path.join(this.cwd, dir);
+    if (!fs.existsSync(fullPath)) {
+      fs.mkdirSync(fullPath, { recursive: true });
+    }
+  }
+
+  copyFile(source, dest) {
+    const fullSource = path.join(this.cwd, source);
+    const fullDest = path.join(this.cwd, dest);
+
+    const destDir = path.dirname(fullDest);
+    if (!fs.existsSync(destDir)) {
+      fs.mkdirSync(destDir, { recursive: true });
+    }
+
+    if (fs.existsSync(fullDest)) {
+      UI.warning(`Skipped (already exists): ${dest}`);
+      return false;
+    }
+
+    fs.copyFileSync(fullSource, fullDest);
+    UI.success(`Copied: ${dest}`);
+    return true;
+  }
+
+  // -----------------------------------------------------------------------
+  // Bulk symlinks (AGENTS.md, agents/, .claude/agents/, .claude/commands/)
+  // -----------------------------------------------------------------------
+
+  async createBulkSymlinks(opts = {}) {
+    const mode = opts.mode || 'prompt';
+
+    await this.createSymlink(
+      path.join(FRAMEWORK_PAYLOAD, 'AGENTS.md'),
+      'AGENTS.md',
+      { mode }
+    );
+
+    await this.createSymlink(
+      path.join(FRAMEWORK_PAYLOAD, 'agents'),
+      'agents',
+      { mode }
+    );
+
+    this.ensureDirectory('.claude');
+
+    // target is relative to cwd; createSymlink converts it to a path relative
+    // to the link's parent directory when `relative: true`.
+    await this.createSymlink(
+      path.join(FRAMEWORK_PAYLOAD, '.claude', 'agents'),
+      path.join('.claude', 'agents'),
+      { relative: true, mode }
+    );
+
+    await this.createSymlink(
+      path.join(FRAMEWORK_PAYLOAD, '.claude', 'commands'),
+      path.join('.claude', 'commands'),
+      { relative: true, mode }
+    );
+  }
+
+  // -----------------------------------------------------------------------
+  // Per-item merge for .claude/skills/
+  // -----------------------------------------------------------------------
+
+  /**
+   * Merge framework skills into the user's .claude/skills/ directory
+   * without ever touching user-authored skills.
+   *
+   * Returns { linked: [...], skipped: [...], conflicts: [...] }
+   */
+  mergeSkills() {
+    const result = { linked: [], skipped: [], conflicts: [] };
+
+    const frameworkSkillsDir = path.join(this.cwd, FRAMEWORK_DIR, 'framework', '.claude', 'skills');
+    if (!fs.existsSync(frameworkSkillsDir)) {
+      UI.warning(`No framework skills found at ${path.relative(this.cwd, frameworkSkillsDir)}. Skipping skill merge.`);
+      return result;
+    }
+
+    const userSkillsDir = path.join(this.cwd, '.claude', 'skills');
+
+    // Handle the v2.0.x legacy case: .claude/skills is a single symlink to
+    // .framework/.../skills. Convert it back to a real directory so we can
+    // host per-item symlinks alongside user skills.
+    if (fs.existsSync(userSkillsDir) && fs.lstatSync(userSkillsDir).isSymbolicLink()) {
+      UI.warning('Detected legacy v2.0.x bulk skills symlink. Converting to per-item layout…');
+      fs.unlinkSync(userSkillsDir);
+    }
+
+    this.ensureDirectory('.claude/skills');
+
+    const frameworkSkills = fs.readdirSync(frameworkSkillsDir).filter(name => {
+      // Skip hidden files (.DS_Store, etc.) and any non-skill entries
+      if (name.startsWith('.')) return false;
+      const full = path.join(frameworkSkillsDir, name);
+      return fs.lstatSync(full).isDirectory();
+    });
+
+    frameworkSkills.forEach(name => {
+      const linkPath = path.join(userSkillsDir, name);
+      const target = path.join('..', '..', FRAMEWORK_DIR, 'framework', '.claude', 'skills', name);
+      const targetAbsolute = path.join(this.cwd, FRAMEWORK_DIR, 'framework', '.claude', 'skills', name);
+
+      if (!fs.existsSync(linkPath)) {
+        fs.symlinkSync(target, linkPath);
+        UI.success(`Skill linked: .claude/skills/${name}`);
+        result.linked.push(name);
+        return;
+      }
+
+      const stat = fs.lstatSync(linkPath);
+      if (stat.isSymbolicLink()) {
+        const current = fs.readlinkSync(linkPath);
+        if (current === target || path.resolve(path.dirname(linkPath), current) === targetAbsolute) {
+          // Already linked correctly — silent OK
+          result.skipped.push({ name, reason: 'already-linked' });
+          return;
+        }
+        // Symlink pointing elsewhere — user override, leave alone
+        UI.info(`Skill kept (user override symlink): .claude/skills/${name} → ${current}`);
+        result.skipped.push({ name, reason: 'user-symlink-override', target: current });
+        return;
+      }
+
+      // Real file or directory under same name — NAME COLLISION
+      UI.warning(`Skill name conflict: .claude/skills/${name} already exists locally. Framework version NOT installed.`);
+      result.conflicts.push({
+        name,
+        local_kind: stat.isDirectory() ? 'directory' : 'file',
+        local_path: path.join('.claude', 'skills', name),
+        framework_path: path.relative(this.cwd, path.join(frameworkSkillsDir, name)),
+        detected_at: new Date().toISOString()
+      });
+    });
+
+    // Persist conflicts (only when there's something to record)
+    if (result.conflicts.length > 0) {
+      this.ensureDirectory('.baldart');
+      const conflictPath = path.join(this.cwd, CONFLICT_LOG);
+      let existing = { conflicts: [] };
+      if (fs.existsSync(conflictPath)) {
+        try { existing = JSON.parse(fs.readFileSync(conflictPath, 'utf8')); }
+        catch (_) { /* ignore parse errors, overwrite */ }
+      }
+      // Replace conflicts for this run (most recent wins)
+      existing.conflicts = result.conflicts;
+      existing.last_merge = new Date().toISOString();
+      fs.writeFileSync(conflictPath, JSON.stringify(existing, null, 2) + '\n');
+      UI.warning(`Recorded ${result.conflicts.length} skill conflict(s) in ${CONFLICT_LOG}`);
+      UI.info('Resolve each by renaming your local skill OR confirming the framework version is the one you want, then re-run `npx baldart update`.');
+    }
+
+    return result;
+  }
+
+  // -----------------------------------------------------------------------
+  // Public composite operations
+  // -----------------------------------------------------------------------
+
+  async createAllSymlinks(opts = {}) {
+    UI.section('Creating Symlinks');
+    await this.createBulkSymlinks(opts);
+
+    UI.newline();
+    UI.section('Merging Framework Skills');
+    this.mergeSkills();
+
+    UI.newline();
+  }
+
+  verifySymlinks() {
+    const bulkSymlinks = [
+      'AGENTS.md',
+      'agents',
+      '.claude/agents',
+      '.claude/commands'
+    ];
+
+    let allValid = true;
+
+    bulkSymlinks.forEach(link => {
+      const fullPath = path.join(this.cwd, link);
+
+      // lstat (doesn't follow symlinks) so we can distinguish "absent" from
+      // "broken symlink" — the latter fails fs.existsSync but still occupies
+      // the path and must be removed before recreating the link.
+      let lstat = null;
+      try { lstat = fs.lstatSync(fullPath); } catch (_) { /* absent */ }
+
+      if (!lstat) {
+        UI.warning(`Missing: ${link}`);
+        allValid = false;
+      } else if (!lstat.isSymbolicLink()) {
+        UI.warning(`Not a symlink (user customisation?): ${link}`);
+        allValid = false;
+      } else if (!fs.existsSync(fullPath)) {
+        UI.warning(`Broken symlink: ${link} → ${fs.readlinkSync(fullPath)}`);
+        allValid = false;
+      } else {
+        UI.success(`Valid: ${link}`);
+      }
+    });
+
+    // .claude/skills/ should be a real directory in v2.1.1+ (or absent).
+    const skillsDir = path.join(this.cwd, '.claude', 'skills');
+    if (fs.existsSync(skillsDir)) {
+      const stat = fs.lstatSync(skillsDir);
+      if (stat.isSymbolicLink()) {
+        UI.warning('Legacy v2.0.x layout: .claude/skills is a bulk symlink. Run `npx baldart update` (or `npx baldart migrate`) to convert to the per-item layout.');
+        allValid = false;
+      } else {
+        // Spot-check a couple of well-known framework skills
+        const sample = ['skill-creator', 'frontend-design', 'bug', 'prd', 'capture'];
+        let frameworkLinks = 0;
+        sample.forEach(name => {
+          const p = path.join(skillsDir, name);
+          if (fs.existsSync(p) && fs.lstatSync(p).isSymbolicLink()) frameworkLinks++;
+        });
+        if (frameworkLinks === 0) {
+          UI.warning('.claude/skills/ has no framework-linked skills. Run `npx baldart update` to merge them.');
+          allValid = false;
+        } else {
+          UI.success(`Valid: .claude/skills/ (per-item merge, ${frameworkLinks}/${sample.length} sampled framework skills linked)`);
+        }
+      }
+    } else {
+      UI.warning('Missing: .claude/skills/ (the framework would merge skills here)');
+      allValid = false;
+    }
+
+    // Project configuration (v3.0.0+)
+    const configPath = path.join(this.cwd, 'baldart.config.yml');
+    if (!fs.existsSync(configPath)) {
+      UI.warning('Missing: baldart.config.yml — skills will prompt for paths on every invocation. Run `npx baldart configure`.');
+      allValid = false;
+    } else {
+      // Check it parses + has a version field — full schema validation is the
+      // configure command's job, this is a smoke test.
+      try {
+        const yaml = require('js-yaml');
+        const cfg = yaml.load(fs.readFileSync(configPath, 'utf8'));
+        if (!cfg || typeof cfg !== 'object') throw new Error('not an object');
+        if (typeof cfg.version !== 'number') throw new Error('missing version');
+        UI.success(`Valid: baldart.config.yml (schema v${cfg.version})`);
+      } catch (err) {
+        UI.warning(`baldart.config.yml is malformed (${err.message}). Re-run \`npx baldart configure\`.`);
+        allValid = false;
+      }
+    }
+
+    // Overlays dir (v3.0.0+)
+    const overlaysDir = path.join(this.cwd, '.baldart', 'overlays');
+    if (!fs.existsSync(overlaysDir)) {
+      UI.warning('Missing: .baldart/overlays/ — run `npx baldart configure` to create it.');
+      allValid = false;
+    } else {
+      UI.success('Valid: .baldart/overlays/');
+    }
+
+    return allValid;
+  }
+
+  copyCustomizableFiles() {
+    UI.section('Copying Customizable Templates');
+
+    // Hooks
+    this.ensureDirectory('.claude/hooks');
+    this.copyFile(
+      path.join(FRAMEWORK_PAYLOAD, '.claude', 'hooks', 'lint-before-commit.sh.template'),
+      path.join('.claude', 'hooks', 'lint-before-commit.sh.template')
+    );
+
+    // UI guidelines
+    this.ensureDirectory('docs/references');
+    this.copyFile(
+      path.join(FRAMEWORK_PAYLOAD, 'docs', 'references', 'ui-guidelines.template.md'),
+      path.join('docs', 'references', 'ui-guidelines.template.md')
+    );
+
+    this.copyFile(
+      path.join(FRAMEWORK_PAYLOAD, 'docs', 'references', 'brand-guidelines.md'),
+      path.join('docs', 'references', 'brand-guidelines.md')
+    );
+
+    // Templates — only user-edit backlog/spec templates.
+    // Skip BALDART-internal templates (config schema, snippet, overlay examples)
+    // which live in `.framework/templates/` and are consumed by CLI commands,
+    // not by humans.
+    const FRAMEWORK_INTERNAL = new Set([
+      'baldart.config.template.yml',
+      'skill-project-context.snippet.md',
+      'overlays', // example overlays directory — consumers reference, don't copy wholesale
+    ]);
+
+    this.ensureDirectory('templates');
+    const templatesDir = path.join(this.cwd, FRAMEWORK_PAYLOAD, 'templates');
+    if (fs.existsSync(templatesDir)) {
+      const templateFiles = fs.readdirSync(templatesDir);
+      templateFiles.forEach(file => {
+        if (FRAMEWORK_INTERNAL.has(file)) return;
+        const src = path.join(this.cwd, FRAMEWORK_PAYLOAD, 'templates', file);
+        if (fs.lstatSync(src).isDirectory()) return;
+        this.copyFile(
+          path.join(FRAMEWORK_PAYLOAD, 'templates', file),
+          path.join('templates', file)
+        );
+      });
+    }
+
+    // Ensure consumer-owned overlay directory exists (real dir, never a symlink).
+    // The configure command also creates this; this branch covers installs that
+    // skip configure.
+    const overlaysDir = path.join(this.cwd, '.baldart', 'overlays');
+    if (!fs.existsSync(overlaysDir)) {
+      fs.mkdirSync(overlaysDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(overlaysDir, '.gitkeep'),
+        '# Skill overlays — see framework/agents/project-context.md § 5\n',
+        'utf8'
+      );
+      UI.success('Created .baldart/overlays/');
+    }
+
+    UI.newline();
+  }
+}
+
+module.exports = SymlinkUtils;

package/src/utils/ui.js

@@ -0,0 +1,133 @@
+const chalk = require('chalk');
+const ora = require('ora');
+const inquirer = require('inquirer');
+
+class UI {
+  static header(text) {
+    console.log('');
+    console.log(chalk.cyan('━'.repeat(60)));
+    console.log(chalk.cyan.bold(text));
+    console.log(chalk.cyan('━'.repeat(60)));
+    console.log('');
+  }
+
+  static step(number, text) {
+    console.log(chalk.green(`✓ STEP ${number}:`) + ` ${text}`);
+  }
+
+  static info(text) {
+    console.log(chalk.blue('→') + ` ${text}`);
+  }
+
+  static success(text) {
+    console.log(chalk.green('✓') + ` ${text}`);
+  }
+
+  static warning(text) {
+    console.log(chalk.yellow('⚠') + ` ${text}`);
+  }
+
+  static error(text) {
+    console.log(chalk.red('✗') + ` ${text}`);
+  }
+
+  static spinner(text) {
+    return ora({
+      text,
+      color: 'cyan'
+    });
+  }
+
+  static async confirm(message, defaultValue = true) {
+    const answers = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'confirmed',
+        message,
+        default: defaultValue
+      }
+    ]);
+    return answers.confirmed;
+  }
+
+  static async select(message, choices) {
+    const answers = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'selected',
+        message,
+        choices
+      }
+    ]);
+    return answers.selected;
+  }
+
+  static async input(message, defaultValue = '') {
+    const answers = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'value',
+        message,
+        default: defaultValue
+      }
+    ]);
+    return answers.value;
+  }
+
+  static box(title, lines) {
+    console.log('');
+    console.log(chalk.cyan('╔' + '═'.repeat(58) + '╗'));
+    console.log(chalk.cyan('║') + chalk.bold(` ${title}`.padEnd(58)) + chalk.cyan('║'));
+    console.log(chalk.cyan('╠' + '═'.repeat(58) + '╣'));
+
+    lines.forEach(line => {
+      // Wrap long lines
+      const maxWidth = 56;
+      const chunks = [];
+      let current = '';
+
+      line.split(' ').forEach(word => {
+        if ((current + ' ' + word).length <= maxWidth) {
+          current += (current ? ' ' : '') + word;
+        } else {
+          if (current) chunks.push(current);
+          current = word;
+        }
+      });
+      if (current) chunks.push(current);
+
+      chunks.forEach(chunk => {
+        console.log(chalk.cyan('║') + ` ${chunk}`.padEnd(58) + chalk.cyan('║'));
+      });
+    });
+
+    console.log(chalk.cyan('╚' + '═'.repeat(58) + '╝'));
+    console.log('');
+  }
+
+  static section(title) {
+    console.log('');
+    console.log(chalk.bold.white(title));
+    console.log(chalk.gray('─'.repeat(title.length)));
+  }
+
+  static code(command, description) {
+    console.log('');
+    console.log(chalk.cyan('Command:'), chalk.white(command));
+    if (description) {
+      console.log(chalk.gray(description));
+    }
+  }
+
+  static list(items, color = 'white') {
+    items.forEach(item => {
+      console.log(chalk[color]('  •'), item);
+    });
+  }
+
+  static newline() {
+    console.log('');
+  }
+}
+
+module.exports = UI;