ai-profile-switch 2.2.0 → 2.2.2

package/src/lib/i18n.mjs

@@ -0,0 +1,65 @@
+// Chooses the screen language and looks up messages. English fills any gap.
+import { LANGUAGES, LANGUAGE_ENV, META_FILE } from './constants.mjs';
+import { readJsonFile } from './json-fs.mjs';
+import en from '../locales/en.mjs';
+import ko from '../locales/ko.mjs';
+
+const MESSAGES = { en, ko };
+export const LANGUAGE_NAMES = { en: 'English', ko: '한국어' };
+
+function languageCode(value) {
+  const code = String(value ?? '').trim().split(/[-_.@]/)[0].toLowerCase();
+  return code || null;
+}
+
+// Terminal locale first (LC_ALL → LC_MESSAGES → LANG), then the OS locale.
+// A set but unknown locale such as C means English rather than a fallthrough.
+export function systemLanguage(env = process.env, intlLocale) {
+  const code = languageCode(env.LC_ALL || env.LC_MESSAGES || env.LANG)
+    ?? languageCode(intlLocale ?? Intl.DateTimeFormat().resolvedOptions().locale);
+  return LANGUAGES.includes(code) ? code : 'en';
+}
+
+export function savedLanguage() {
+  try {
+    const { language } = readJsonFile(META_FILE, {}) ?? {};
+    return LANGUAGES.includes(language) ? language : null;
+  } catch {
+    return null;
+  }
+}
+
+export function detectLanguage({ saved = savedLanguage(), env = process.env, intlLocale } = {}) {
+  if (saved) return saved;
+  const forced = languageCode(env[LANGUAGE_ENV]);
+  if (LANGUAGES.includes(forced)) return forced;
+  return systemLanguage(env, intlLocale);
+}
+
+let current;
+
+export function language() {
+  current ??= detectLanguage();
+  return current;
+}
+
+export function setLanguage(code) {
+  current = code;
+}
+
+export function t(key, vars = {}) {
+  const message = MESSAGES[language()][key] ?? en[key];
+  if (message === undefined) throw new Error(`Missing message: ${key}`);
+  return message.replace(/\{(\w+)\}/g, (match, name) => (Object.hasOwn(vars, name) ? String(vars[name]) : match));
+}
+
+const TIME_UNITS = [['year', 31536000], ['month', 2592000], ['week', 604800], ['day', 86400], ['hour', 3600], ['minute', 60]];
+
+export function relativeTime(ms, now = Date.now()) {
+  const seconds = Math.round((ms - now) / 1000);
+  const format = new Intl.RelativeTimeFormat(language(), { numeric: 'auto' });
+  for (const [unit, size] of TIME_UNITS) {
+    if (Math.abs(seconds) >= size) return format.format(Math.round(seconds / size), unit);
+  }
+  return t('time.justNow');
+}

package/src/lib/profile.mjs

@@ -11,7 +11,8 @@ import {
 } from './constants.mjs';
 import { createHash } from 'node:crypto';
 import { addProfileToMeta, removeProfileFromMeta, readMeta, writeMeta } from './config.mjs';
-import { warn } from './ui.mjs';
+import { userError, warn } from './ui.mjs';
+import { t } from './i18n.mjs';
 
 export function pathExists(path) {
   try { lstatSync(path); return true; } catch (err) {
@@ -31,23 +32,21 @@ export function createLink(target, link, isDir, copySource = resolve(dirname(lin
   } catch (err) {
     if (!IS_WINDOWS || isDir || !['EPERM', 'ENOTSUP'].includes(err.code)) throw err;
     copyFileSync(copySource, link);
-    warn(`Symlink unavailable: copied shared file instead (${link}).`);
-    warn('Enable Windows Developer Mode for full shared-settings sync.');
+    warn(t('profile.copiedInstead', { link }));
+    warn(t('profile.devMode'));
   }
 }
 
 export function validateProfileName(name) {
-  if (!name) return 'Profile name cannot be empty';
+  if (!name) return t('profile.empty');
   if (name.length > PROFILE_NAME_MAX_LENGTH) {
-    return `Profile name must be ${PROFILE_NAME_MAX_LENGTH} characters or fewer`;
+    return t('profile.tooLong', { max: PROFILE_NAME_MAX_LENGTH });
   }
-  if (RESERVED_NAMES.includes(name)) return `"${name}" is a reserved name`;
+  if (RESERVED_NAMES.includes(name)) return t('profile.reserved', { name });
   if (IS_WINDOWS && /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i.test(name)) {
-    return `"${name}" is a reserved Windows device name`;
-  }
-  if (!PROFILE_NAME_REGEX.test(name)) {
-    return 'Only lowercase letters, numbers, and hyphens allowed (must start/end with letter or number)';
+    return t('profile.reservedWindows', { name });
   }
+  if (!PROFILE_NAME_REGEX.test(name)) return t('profile.invalidName');
   return null;
 }
 
@@ -87,13 +86,16 @@ export function assertRegisteredProfile(name) {
   const error = validateProfileName(name);
   if (error) throw new Error(error);
   const meta = readMeta();
-  if (!meta.profiles.includes(name)) throw new Error(`Profile "${name}" is not registered`);
+  if (!meta.profiles.includes(name)) {
+    throw userError(t('profile.notFound', { name }), [
+      ...(meta.profiles.length ? [{ label: t('hint.profiles'), text: meta.profiles.join(', ') }] : []),
+      { label: t('hint.create'), command: `cpf add ${name}` },
+    ]);
+  }
   const dir = profileDir(name);
-  if (!pathExists(dir)) throw new Error(`Profile "${name}" directory is missing`);
+  if (!pathExists(dir)) throw new Error(t('profile.missingDir', { name }));
   const entry = lstatSync(dir);
-  if (entry.isSymbolicLink() || !entry.isDirectory()) {
-    throw new Error(`Profile "${name}" must be a directory, not a symbolic link or file`);
-  }
+  if (entry.isSymbolicLink() || !entry.isDirectory()) throw new Error(t('profile.notDirectory', { name }));
   return meta;
 }
 
@@ -103,16 +105,25 @@ export function removeProfile(name) {
   removeProfileFromMeta(name);
 }
 
-export function renameProfile(oldName, newName) {
+// Checks a rename without changing anything, so callers can warn only when it can go ahead.
+export function checkRename(oldName, newName) {
   const meta = assertRegisteredProfile(oldName);
   const error = validateProfileName(newName);
   if (error) throw new Error(error);
+  if (oldName !== newName && (meta.profiles.includes(newName) || pathExists(profileDir(newName)))) {
+    throw userError(t('profile.exists', { name: newName }), [
+      { label: t('hint.profiles'), text: meta.profiles.join(', ') },
+      { label: t('hint.otherName'), command: `cpf rename ${oldName} ${newName}-2` },
+    ]);
+  }
+  return meta;
+}
+
+export function renameProfile(oldName, newName) {
+  const meta = checkRename(oldName, newName);
   if (oldName === newName) return false;
   const oldDir = profileDir(oldName);
   const newDir = profileDir(newName);
-  if (meta.profiles.includes(newName) || pathExists(newDir)) {
-    throw new Error(`Profile "${newName}" already exists`);
-  }
 
   renameSync(oldDir, newDir);
   try {
@@ -220,6 +231,37 @@ function validateJson(source) {
   }
 }
 
+// Claude Code saves absolute paths in its plugin indexes. Copied as they are, a profile would keep
+// loading plugins from the source folder and break once that folder is removed.
+const PLUGIN_INDEXES = ['installed_plugins.json', 'known_marketplaces.json'];
+
+function repointPlugins(plugins, sourceDir, targetDir) {
+  if (!pathExists(plugins) || !lstatSync(plugins).isDirectory()) return;
+  const to = join(targetDir, 'plugins');
+  const prefixes = [...new Set([join(sourceDir, 'plugins'), join(canonicalPath(sourceDir), 'plugins')])];
+  const move = value => {
+    if (typeof value === 'string') {
+      const from = prefixes.find(prefix => value === prefix
+        || value.startsWith(prefix + sep) || value.startsWith(prefix + '/'));
+      return from ? to + value.slice(from.length) : value;
+    }
+    if (Array.isArray(value)) return value.map(move);
+    if (value && typeof value === 'object') {
+      return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, move(item)]));
+    }
+    return value;
+  };
+  for (const name of PLUGIN_INDEXES) {
+    const path = join(plugins, name);
+    if (!pathExists(path) || !lstatSync(path).isFile()) continue;
+    const text = readFileSync(path, 'utf8');
+    let index;
+    try { index = JSON.parse(text); } catch { continue; }
+    const moved = JSON.stringify(move(index), null, 2);
+    if (moved !== JSON.stringify(index, null, 2)) writeFileSync(path, moved + '\n');
+  }
+}
+
 function stageEntry(source, destination) {
   if (!pathExists(source)) return;
   if (pathExists(destination)) {
@@ -282,6 +324,7 @@ function prepareMigration(source, profileName, shareSettings, stage) {
     stageEntry(join(source.directory, entry), join(stagedProfile, entry));
     if (!pathExists(join(stagedProfile, entry))) mkdirSync(join(stagedProfile, entry));
   }
+  repointPlugins(join(stagedProfile, 'plugins'), source.directory, target);
   for (const entry of [...SHARED_FILES, ...SHARED_DIRS]) {
     const shared = shareSettings ? stagedShared : stagedProfile;
     const from = join(source.directory, entry);

package/src/lib/prompt.mjs

@@ -1,6 +1,7 @@
 import { createInterface, emitKeypressEvents } from 'node:readline';
 import { PassThrough } from 'node:stream';
-import { color, cursorControl, sym } from './ui.mjs';
+import { color, cursorControl, displayWidth, sym } from './ui.mjs';
+import { t } from './i18n.mjs';
 
 function rl() {
   return createInterface({ input: process.stdin, output: process.stdout });
@@ -29,17 +30,18 @@ function readKeys(onKey) {
   };
 }
 
-export async function text(message, defaultVal) {
-  const suffix = defaultVal !== undefined ? color.dim(` (${defaultVal})`) : '';
+// hint is shown only while asking, such as "now: side · empty to cancel".
+export async function text(message, defaultVal, hint) {
+  const suffix = hint ? `  ${color.dim(hint)}` : defaultVal !== undefined ? color.dim(` (${defaultVal})`) : '';
   const r = rl();
   const cursor = cursorControl();
   return new Promise((resolve) => {
-    r.question(`${color.cyan('?')} ${message}${suffix}\n  ${color.dim(sym.arrow)} `, (answer) => {
+    r.question(`${color.cyan(sym.step)}  ${message}${suffix}\n${color.dim(sym.rail)}  ${color.dim(sym.arrow)} `, (answer) => {
       r.close();
       const result = answer.trim() || defaultVal || '';
-      // Replace 2-line prompt with single completed line: ✓ message … answer
+      // Replace 2-line prompt with single completed line: ◇ message … answer
       if (cursor.enabled) {
-        process.stdout.write(`${cursor.up(2)}\r${cursor.clearLine}${color.green(sym.check)} ${message} ${color.dim(sym.dots)} ${color.cyan(result)}\n${cursor.clearDown}`);
+        process.stdout.write(`${cursor.up(2)}\r${cursor.clearLine}${color.green(sym.stepDone)}  ${message} ${color.dim(sym.dots)} ${result ? color.cyan(result) : color.dim(t('prompt.cancelled'))}\n${cursor.clearDown}`);
       }
       resolve(result);
     });
@@ -63,11 +65,12 @@ export async function confirm(message, defaultVal = true) {
     const cursor = cursorControl();
 
     const render = (final = false) => {
-      const prefix = final ? color.green(sym.check) : color.cyan('?');
+      const prefix = final ? color.green(sym.stepDone) : color.cyan(sym.step);
       const sep = final ? color.dim(` ${sym.dots} `) : color.dim(` ${sym.arrow} `);
-      const no  = !selected ? color.cyan('No')  : color.dim('No');
-      const yes =  selected ? color.cyan('Yes') : color.dim('Yes');
-      process.stdout.write(`\r${cursor.clearLine}${prefix} ${message}${sep}${no} ${color.dim('/')} ${yes}`);
+      const no  = !selected ? color.cyan(t('prompt.no'))  : color.dim(t('prompt.no'));
+      const yes =  selected ? color.cyan(t('prompt.yes')) : color.dim(t('prompt.yes'));
+      const answer = final ? (selected ? yes : no) : `${no} ${color.dim('/')} ${yes}`;
+      process.stdout.write(`\r${cursor.clearLine}${prefix}  ${message}${sep}${answer}`);
     };
 
     render();
@@ -82,7 +85,8 @@ export async function confirm(message, defaultVal = true) {
       } else if (character === 'n' || character === 'N') {
         selected = false;
         render();
-      } else if (key.name === 'return' || key.name === 'enter') {
+      } else if (key.name === 'return' || key.name === 'enter' || key.name === 'escape') {
+        if (key.name === 'escape') selected = false;
         stop();
         render(true);
         process.stdout.write('\n');
@@ -96,52 +100,115 @@ export async function confirm(message, defaultVal = true) {
   });
 }
 
-export async function select(message, choices, { output = process.stdout, initial = 0 } = {}) {
+// Choices are strings or { label, value, hint, details }. hint sits after the label,
+// details are extra dim lines under it. numbered adds 1-9 keys that pick at once.
+// body lines sit between the question and the choices; back says Esc goes back.
+export async function select(message, choices, {
+  output = process.stdout, initial = 0, numbered = false, done, body = [], back = false,
+} = {}) {
+  const items = choices.map(choice => (typeof choice === 'string' ? { label: choice, value: choice } : choice));
   return new Promise((resolve) => {
-    let selected = Math.max(0, Math.min(initial, choices.length - 1));
-    let rendered = false;
+    let selected = Math.max(0, Math.min(initial, items.length - 1));
+    let height = 0;
+    let top = 0;
     const cursor = cursorControl(output);
+    const rail = color.dim(sym.rail);
+    const indent = ' '.repeat(numbered ? 5 : 2);
+    const keys = numbered && items.length > 1 && items.length <= 9
+      ? t(back ? 'prompt.keysNumberedBack' : 'prompt.keysNumbered', { arrows: sym.arrows, max: items.length })
+      : t(back ? 'prompt.keysBack' : 'prompt.keys', { arrows: sym.arrows });
+
+    // The choices from index from up to to, with details under the ones detailed(i) picks.
+    const rows = (detailed = () => true, from = 0, to = items.length) => {
+      const lines = [];
+      if (from > 0) lines.push(`${rail}  ${color.dim(t('prompt.moreAbove', { count: from }))}`);
+      items.slice(from, to).forEach((item, offset) => {
+        const i = from + offset;
+        const number = numbered ? `${i + 1}  ` : '';
+        const head = i === selected
+          ? color.cyan(`${sym.cursor} ${number}${item.label}`)
+          : `  ${numbered ? `${color.dim(String(i + 1))}  ` : ''}${item.label}`;
+        lines.push(`${rail}  ${head}${item.hint ? `  ${item.hint}` : ''}`);
+        if (!detailed(i) || !item.details?.length) return;
+        for (const detail of item.details) lines.push(`${rail}  ${indent}${detail}`);
+        lines.push(rail);
+      });
+      if (to < items.length) lines.push(`${rail}  ${color.dim(t('prompt.moreBelow', { count: items.length - to }))}`);
+      lines.push(`${rail}  ${color.dim(keys)}`, color.dim(sym.railEnd));
+      return lines;
+    };
+
+    // A line wider than the window wraps, so count the screen rows it really takes.
+    const screenRows = lines => lines.reduce((sum, line) => sum
+      + Math.max(1, Math.ceil(displayWidth(line) / (output.columns || Infinity))), 0);
+    const header = [`${color.cyan(sym.step)}  ${message}`, ...body.map(line => `${rail}  ${line}`)];
+
+    // The cursor can't move up past the top of the window, so a menu taller than the window
+    // can't be redrawn in place: every redraw would push another copy of its first rows into
+    // the scrollback. It shrinks to fit instead: details only under the selected choice, then
+    // only the choices around it. The row under the menu is where the cursor waits.
+    const fits = lines => screenRows(header) + screenRows(lines) < (output.rows || Infinity);
+    const layout = () => {
+      const full = rows();
+      if (fits(full)) return full;
+      const shown = (from, to) => rows(i => i === selected, from, to);
+      if (fits(shown(0, items.length))) return shown(0, items.length);
+      const end = from => {
+        let to = Math.max(from, selected) + 1;
+        while (to < items.length && fits(shown(from, to + 1))) to++;
+        return to;
+      };
+      top = Math.min(top, selected);
+      while (top < selected && !fits(shown(top, end(top)))) top++;
+      return shown(top, end(top));
+    };
 
     const render = () => {
-      if (rendered) {
-        output.write(cursor.up(choices.length));
+      if (height) output.write(cursor.up(height));
+      const lines = layout();
+      for (const line of lines) output.write(`${cursor.clearLine}${line}\n`);
+      // A shorter menu than last time leaves old rows below it.
+      output.write(cursor.clearDown);
+      height = screenRows(lines);
+    };
+
+    const finish = (value, summary) => {
+      stop();
+      if (cursor.enabled) {
+        output.write(`${cursor.up(height + screenRows(header))}\r${cursor.clearLine}${summary}\n${cursor.clearDown}`);
       }
-      choices.forEach((choice, i) => {
-        const label = typeof choice === 'string' ? choice : choice.label;
-        const prefix = i === selected ? color.cyan(`  ${sym.cursor} `) : '    ';
-        output.write(`${cursor.clearLine}${prefix}${label}\n`);
-      });
-      rendered = true;
+      resolve(value);
+    };
+
+    const pick = () => {
+      const item = items[selected];
+      const summary = done ? done(item.value) : `${message} ${color.dim(sym.dots)} ${color.cyan(item.label.trim())}`;
+      finish(item.value, `${color.green(sym.stepDone)}  ${summary}`);
     };
 
     if (!process.stdin.isTTY) {
-      // Non-interactive: pick first choice without rendering menu
-      resolve(typeof choices[selected] === 'string' ? choices[selected] : choices[selected].value);
+      // Non-interactive: pick the initial choice without rendering the menu
+      resolve(items[selected].value);
       return;
     }
 
-    output.write(`${color.cyan('?')} ${message}\n`);
+    for (const line of header) output.write(`${line}\n`);
     render();
 
     const stop = readKeys((character, key) => {
       if (key.name === 'up') {
-        selected = (selected - 1 + choices.length) % choices.length;
+        selected = (selected - 1 + items.length) % items.length;
         render();
       } else if (key.name === 'down') {
-        selected = (selected + 1) % choices.length;
+        selected = (selected + 1) % items.length;
         render();
+      } else if (numbered && /^[1-9]$/.test(character ?? '') && Number(character) <= items.length) {
+        selected = Number(character) - 1;
+        pick();
       } else if (key.name === 'return' || key.name === 'enter') {
-        stop();
-        const choice = choices[selected];
-        const value = typeof choice === 'string' ? choice : choice.value;
-        if (cursor.enabled) {
-          output.write(`${cursor.up(choices.length + 1)}\r${cursor.clearLine}${color.green(sym.check)} ${message} ${color.dim(sym.dots)} ${color.cyan(value)}\n${cursor.clearDown}`);
-        }
-        resolve(value);
-      } else if (key.ctrl && key.name === 'c') {
-        stop();
-        output.write('\n');
-        resolve(null);
+        pick();
+      } else if (key.name === 'escape' || (key.ctrl && key.name === 'c')) {
+        finish(null, `${color.dim(sym.stepDone)}  ${message} ${color.dim(t('prompt.cancelled'))}`);
       }
     });
   });

package/src/lib/shared.mjs

@@ -6,6 +6,7 @@ import {
   SHARED_DIR, SHAREABLE_ENTRIES, SHAREABLE_FILES, ACCOUNT_SKILL_ENTRIES,
 } from './constants.mjs';
 import { readMeta, getActiveProfile, getSharedEntries, setSharedEntries } from './config.mjs';
+import { t } from './i18n.mjs';
 import {
   pathExists, createLink, copyEntry, identicalEntries, emptyEntry, linkTarget, canonicalPath,
   profileDir, listProfiles,
@@ -93,7 +94,7 @@ export function syncShared(names = listProfiles(), options) {
 
 function validateEntry(entry) {
   if (!SHAREABLE_ENTRIES.includes(entry)) {
-    throw new Error(`"${entry}" cannot be shared. Choose one of: ${SHAREABLE_ENTRIES.join(', ')}`);
+    throw new Error(t('share.cannot', { entry, list: SHAREABLE_ENTRIES.join(', ') }));
   }
 }
 
@@ -120,9 +121,9 @@ function seedShared(entry, from) {
 export function shareEntry(entry, from = getActiveProfile()) {
   validateEntry(entry);
   const meta = readMeta();
-  if (!meta.shareSettings) throw new Error('Sharing needs shared settings. This setup keeps each profile separate.');
+  if (!meta.shareSettings) throw new Error(t('share.needsSettings'));
   const entries = meta.shared ?? [];
-  if (entries.includes(entry)) throw new Error(`"${entry}" is already shared`);
+  if (entries.includes(entry)) throw new Error(t('share.already', { entry }));
   mkdirSync(SHARED_DIR, { recursive: true });
   if (!pathExists(join(SHARED_DIR, entry))) seedShared(entry, from);
   setSharedEntries([...entries, entry]);
@@ -133,7 +134,7 @@ export function shareEntry(entry, from = getActiveProfile()) {
 export function unshareEntry(entry) {
   validateEntry(entry);
   const entries = getSharedEntries();
-  if (!entries.includes(entry)) throw new Error(`"${entry}" is not shared`);
+  if (!entries.includes(entry)) throw new Error(t('share.notShared', { entry }));
   const sharedPath = join(SHARED_DIR, entry);
   for (const name of listProfiles()) {
     if (entry === 'skills') {

package/src/lib/ui.mjs

@@ -1,9 +1,13 @@
-// ANSI colors, terminal capability detection, and box-drawing helpers.
+// ANSI colors, terminal capability detection, and the left-rail layout helpers.
 // Single source for any module that writes to stdout/stderr.
 
-export const hasColor = Boolean(process.stdout.isTTY || process.env.FORCE_COLOR)
-  && !process.env.NO_COLOR
-  && process.env.TERM !== 'dumb';
+const colorAllowed = !process.env.NO_COLOR && process.env.TERM !== 'dumb';
+export let hasColor = Boolean(process.stdout.isTTY || process.env.FORCE_COLOR) && colorAllowed;
+
+// The claude picker draws on stderr while its stdout is captured by the shell.
+export function colorFor(stream) {
+  hasColor = Boolean(stream.isTTY || process.env.FORCE_COLOR) && colorAllowed;
+}
 
 // On legacy Windows consoles (cmd.exe without UTF-8 codepage), Unicode box
 // characters may not render.  Detect via the WT_SESSION env var (set by
@@ -15,17 +19,16 @@ export const supportsUnicode = Boolean(
 );
 
 const ESC = '\x1b[';
-const RESET = hasColor ? `${ESC}0m` : '';
 const c = (code) => hasColor ? `${ESC}${code}m` : '';
 
 export const color = {
-  bold:    (s) => `${c('1')}${s}${RESET}`,
-  dim:     (s) => `${c('2')}${s}${RESET}`,
-  green:   (s) => `${c('32')}${s}${RESET}`,
-  yellow:  (s) => `${c('33')}${s}${RESET}`,
-  blue:    (s) => `${c('34')}${s}${RESET}`,
-  cyan:    (s) => `${c('36')}${s}${RESET}`,
-  red:     (s) => `${c('31')}${s}${RESET}`,
+  bold:    (s) => `${c('1')}${s}${c('0')}`,
+  dim:     (s) => `${c('2')}${s}${c('0')}`,
+  green:   (s) => `${c('32')}${s}${c('0')}`,
+  yellow:  (s) => `${c('33')}${s}${c('0')}`,
+  blue:    (s) => `${c('34')}${s}${c('0')}`,
+  cyan:    (s) => `${c('36')}${s}${c('0')}`,
+  red:     (s) => `${c('31')}${s}${c('0')}`,
 };
 
 export function cursorControl(output = process.stdout) {
@@ -50,24 +53,17 @@ export const sym = {
   bulletOn:  supportsUnicode ? '●' : '*',
   bulletOff: supportsUnicode ? '○' : 'o',
   dash:      supportsUnicode ? '──' : '--',
+  arrows:    supportsUnicode ? '↑↓' : 'Up/Down',
+  // Left rail that groups one flow: ┌ start, │ body, ◆ question, ◇ answered, └ end.
+  railTop:   supportsUnicode ? '┌' : '+',
+  rail:      supportsUnicode ? '│' : '|',
+  railEnd:   supportsUnicode ? '└' : '`',
+  step:      supportsUnicode ? '◆' : '*',
+  stepDone:  supportsUnicode ? '◇' : 'o',
+  barOn:     supportsUnicode ? '▰' : '#',
+  barOff:    supportsUnicode ? '▱' : '-',
 };
 
-const BOX_TL = supportsUnicode ? '╭' : '+';
-const BOX_TR = supportsUnicode ? '╮' : '+';
-const BOX_BL = supportsUnicode ? '╰' : '+';
-const BOX_BR = supportsUnicode ? '╯' : '+';
-const BOX_H  = supportsUnicode ? '─' : '-';
-const BOX_V  = supportsUnicode ? '│' : '|';
-
-export function box(lines) {
-  const maxLen = Math.max(...lines.map(stripAnsi).map(l => l.length));
-  const pad = (s) => s + ' '.repeat(maxLen - stripAnsi(s).length);
-  const top    = `  ${BOX_TL}${BOX_H.repeat(maxLen + 2)}${BOX_TR}`;
-  const bottom = `  ${BOX_BL}${BOX_H.repeat(maxLen + 2)}${BOX_BR}`;
-  const body = lines.map(l => `  ${BOX_V} ${pad(l)} ${BOX_V}`).join('\n');
-  return `${top}\n${body}\n${bottom}`;
-}
-
 export function success(msg) {
   process.stdout.write(`  ${color.green(sym.check)} ${msg}\n`);
 }
@@ -76,8 +72,31 @@ export function warn(msg) {
   process.stdout.write(`  ${color.yellow(sym.warn)} ${msg}\n`);
 }
 
-export function error(msg) {
+// Hints are { label, text } or { label, command } lines telling what to do next.
+export function error(msg, hints = []) {
   process.stderr.write(`  ${color.red(sym.cross)} ${msg}\n`);
+  for (const hint of hints) {
+    process.stderr.write(`    ${color.dim(hint.label)} ${hint.command ? color.cyan(hint.command) : hint.text}\n`);
+  }
+}
+
+export function userError(message, hints = []) {
+  return Object.assign(new Error(message), { hints });
+}
+
+export function intro(title, note = '', output = process.stdout) {
+  output.write(`${color.dim(sym.railTop)}  ${color.bold(title)}${note ? `  ${color.dim(note)}` : ''}\n${color.dim(sym.rail)}\n`);
+}
+
+export function outro(message, output = process.stdout) {
+  output.write(`${color.dim(sym.railEnd)}  ${message}\n`);
+}
+
+// The number is always printed so the bar never relies on color alone.
+export function meter(percent, width = 10) {
+  const filled = Math.round(percent / 100 * width);
+  const paint = percent >= 80 ? color.red : percent >= 50 ? color.yellow : color.green;
+  return `${paint(sym.barOn.repeat(filled))}${color.dim(sym.barOff.repeat(width - filled))} ${String(percent).padStart(3)}%`;
 }
 
 export function info(msg) {
@@ -87,3 +106,9 @@ export function info(msg) {
 export function stripAnsi(s) {
   return s.replace(/\x1b\[[0-9;]*m/g, '');
 }
+
+// Hangul and other wide characters take two terminal columns.
+export function displayWidth(text) {
+  return [...stripAnsi(text)].reduce((width, char) => width
+    + (/[\u1100-\u115f\u2e80-\ua4cf\uac00-\ud7a3\uf900-\ufaff\uff00-\uff60]/.test(char) ? 2 : 1), 0);
+}