create-quiver 0.14.0 → 0.14.1

package/src/create-quiver/lib/cli/theme.js

@@ -0,0 +1,100 @@
+const QUIVER_COLORS = Object.freeze({
+  sky: '#86C8F2',
+  blue: '#6BADEB',
+  periwinkle: '#7F9EE8',
+  violet: '#9B82E6',
+  magenta: '#D56AB0',
+});
+
+const STATUS_COLORS = Object.freeze({
+  info: 'sky',
+  command: 'blue',
+  planner: 'violet',
+  review: 'magenta',
+  risk: 'magenta',
+  muted: 'periwinkle',
+});
+
+function isTruthy(value) {
+  return /^(1|true|yes|on)$/i.test(String(value || '').trim());
+}
+
+function isAsciiLocale(env = process.env) {
+  const locale = `${env.LC_ALL || ''} ${env.LC_CTYPE || ''} ${env.LANG || ''}`;
+  return /\bC\b|ASCII/i.test(locale);
+}
+
+function isDumbTerminal(env = process.env) {
+  return String(env.TERM || '').toLowerCase() === 'dumb';
+}
+
+function shouldUseColor(options = {}, env = process.env, tty = {}) {
+  if (options.json || options.noColor) return false;
+  if (env.NO_COLOR || env.FORCE_COLOR === '0') return false;
+  if (isDumbTerminal(env)) return false;
+  if (isTruthy(env.CI)) return false;
+  if (tty.stdout === false) return false;
+  if (options.color === true) return true;
+  return Boolean(tty.stdout);
+}
+
+function shouldUseUnicode(options = {}, env = process.env, tty = {}) {
+  if (options.ascii || options.json) return false;
+  if (isDumbTerminal(env) || isAsciiLocale(env)) return false;
+  if (tty.stdout === false) return false;
+  if (options.unicode === true) return true;
+  return Boolean(tty.stdout);
+}
+
+function hexToRgb(hex) {
+  const normalized = String(hex || '').replace(/^#/, '');
+  if (!/^[0-9a-f]{6}$/i.test(normalized)) {
+    return null;
+  }
+  return [
+    Number.parseInt(normalized.slice(0, 2), 16),
+    Number.parseInt(normalized.slice(2, 4), 16),
+    Number.parseInt(normalized.slice(4, 6), 16),
+  ];
+}
+
+function colorize(value, colorName, theme) {
+  const text = String(value ?? '');
+  if (!theme?.useColor) return text;
+  const rgb = hexToRgb(theme.colors[colorName] || colorName);
+  if (!rgb) return text;
+  return `\u001b[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m${text}\u001b[0m`;
+}
+
+function resolveTheme(options = {}, env = process.env, tty = {}) {
+  const useColor = shouldUseColor(options, env, tty);
+  const useUnicode = shouldUseUnicode(options, env, tty);
+  const symbols = useUnicode
+    ? { start: '◇', success: '✓', warning: '!', error: '✖', bullet: '•' }
+    : { start: '*', success: 'OK', warning: 'WARN', error: 'ERR', bullet: '-' };
+  const theme = {
+    colors: QUIVER_COLORS,
+    statusColors: STATUS_COLORS,
+    symbols,
+    useColor,
+    useUnicode,
+  };
+
+  return {
+    ...theme,
+    colorize: (value, colorName) => colorize(value, colorName, theme),
+    status: (status, value) => colorize(value, STATUS_COLORS[status] || 'sky', theme),
+  };
+}
+
+module.exports = {
+  QUIVER_COLORS,
+  STATUS_COLORS,
+  colorize,
+  isAsciiLocale,
+  isDumbTerminal,
+  isTruthy,
+  resolveTheme,
+  shouldUseColor,
+  shouldUseUnicode,
+};

package/src/create-quiver/lib/cli/ux-flags.js

@@ -0,0 +1,151 @@
+const UX_FLAG_OPTIONS = Object.freeze({
+  withPlanner: '--with-planner',
+  interactive: '--interactive',
+  review: '--review',
+});
+
+const UX_FLAG_MATRIX = Object.freeze({
+  'ai prepare-context': Object.freeze({
+    withPlanner: true,
+    interactive: true,
+    review: true,
+    note: 'planner-assisted docs-only context preparation',
+  }),
+  'ai plan': Object.freeze({
+    withPlanner: true,
+    interactive: true,
+    review: true,
+    note: 'planner draft generation and human approval workflow',
+  }),
+  'spec create': Object.freeze({
+    withPlanner: true,
+    interactive: true,
+    review: true,
+    note: 'spec generation from approved planner output',
+  }),
+  'ai pr': Object.freeze({
+    withPlanner: false,
+    interactive: true,
+    review: true,
+    note: 'PR body review and interactive PR inputs',
+  }),
+});
+
+function formatError(message) {
+  return `create-quiver: ${message}`;
+}
+
+function normalizeCommandKey(value) {
+  return String(value || '').trim().replace(/\s+/g, ' ');
+}
+
+function resolveUxCommandKey(args = {}) {
+  if (args.mode === 'ai') {
+    const command = args.aiCommand || '';
+    if (command === 'specs' || command === 'slices' || command === 'trace' || command === 'active-slice') {
+      return normalizeCommandKey(`ai ${command} ${args.aiSecondaryCommand || ''}`);
+    }
+    if (command === 'agent') {
+      return normalizeCommandKey(`ai ${command} ${args.aiAgentCommand || ''}`);
+    }
+    if (command === 'run') {
+      return normalizeCommandKey(`ai ${command} ${args.aiRunCommand || ''}`);
+    }
+    return normalizeCommandKey(`ai ${command}`);
+  }
+
+  if (args.mode === 'spec') {
+    return normalizeCommandKey(`spec ${args.specCommand || ''}`);
+  }
+
+  if (args.mode === 'demo') {
+    return normalizeCommandKey(`demo ${args.demoCommand || ''} ${args.demoName || ''}`);
+  }
+
+  if (args.mode === 'evidence') {
+    return normalizeCommandKey(`evidence ${args.evidenceCommand || ''}`);
+  }
+
+  return normalizeCommandKey(args.mode);
+}
+
+function getUxFlagSupport(commandKey) {
+  return UX_FLAG_MATRIX[normalizeCommandKey(commandKey)] || Object.freeze({
+    withPlanner: false,
+    interactive: false,
+    review: false,
+    note: 'no UX flag support',
+  });
+}
+
+function getRequestedUxFlags(args = {}) {
+  return Object.keys(UX_FLAG_OPTIONS).filter((key) => args[key] === true);
+}
+
+function supportedFlagList(support) {
+  return Object.entries(UX_FLAG_OPTIONS)
+    .filter(([key]) => support[key] === true)
+    .map(([, flag]) => flag);
+}
+
+function explainAlternative(flag) {
+  if (flag === 'withPlanner') {
+    return 'Use a planner-capable command such as: npx create-quiver ai prepare-context --with-planner --dry-run';
+  }
+  if (flag === 'interactive') {
+    return 'Use explicit non-interactive flags for automation, or run a command that documents --interactive support.';
+  }
+  if (flag === 'review') {
+    return 'Use a command with persistent AI-generated output, then rerun with --review after inspecting the dry-run.';
+  }
+  return 'Run: npx create-quiver --help';
+}
+
+function buildUnsupportedFlagError(commandKey, flag, support) {
+  const flagName = UX_FLAG_OPTIONS[flag];
+  const supported = supportedFlagList(support);
+  const supportedText = supported.length > 0 ? supported.join(', ') : 'none';
+
+  return new Error(formatError([
+    `UX flag ${flagName} is not supported by '${commandKey}'.`,
+    `Supported UX flags for '${commandKey}': ${supportedText}.`,
+    explainAlternative(flag),
+  ].join('\n')));
+}
+
+function validateUxFlagCombinations(args = {}, commandKey = resolveUxCommandKey(args)) {
+  if (args.json && args.interactive) {
+    throw new Error(formatError(`incompatible UX flags for '${commandKey}': --json cannot be combined with --interactive because JSON output must stay machine-readable.`));
+  }
+  if (args.json && args.review) {
+    throw new Error(formatError(`incompatible UX flags for '${commandKey}': --json cannot be combined with --review because editor review is a human-only flow.`));
+  }
+}
+
+function validateUxFlags(args = {}) {
+  const commandKey = resolveUxCommandKey(args);
+  validateUxFlagCombinations(args, commandKey);
+
+  const support = getUxFlagSupport(commandKey);
+  for (const flag of getRequestedUxFlags(args)) {
+    if (support[flag] !== true) {
+      throw buildUnsupportedFlagError(commandKey, flag, support);
+    }
+  }
+
+  return {
+    commandKey,
+    requested: getRequestedUxFlags(args).map((flag) => UX_FLAG_OPTIONS[flag]),
+    supported: supportedFlagList(support),
+  };
+}
+
+module.exports = {
+  UX_FLAG_MATRIX,
+  UX_FLAG_OPTIONS,
+  getRequestedUxFlags,
+  getUxFlagSupport,
+  resolveUxCommandKey,
+  validateUxFlagCombinations,
+  validateUxFlags,
+};

package/src/create-quiver/lib/cli/ux.js

@@ -0,0 +1,130 @@
+const { resolveTheme, isTruthy } = require('./theme');
+
+function resolveUxMode(options = {}, env = process.env, io = {}) {
+  const isTTY = {
+    stdin: options.stdinIsTTY ?? Boolean((io.input || process.stdin).isTTY),
+    stdout: options.stdoutIsTTY ?? Boolean((io.output || process.stdout).isTTY),
+    stderr: options.stderrIsTTY ?? Boolean((io.error || process.stderr).isTTY),
+  };
+  const json = options.json === true;
+  const ci = isTruthy(env.CI);
+  const noColor = options.noColor === true || Boolean(env.NO_COLOR);
+  const interactive = options.interactive === true;
+  const decoration = !json && !ci && isTTY.stdout;
+  const usePrompts = decoration && interactive && isTTY.stdin;
+  const useSpinners = decoration && options.spinner !== false;
+  const theme = resolveTheme({ ...options, json, noColor }, env, {
+    stdout: isTTY.stdout,
+  });
+
+  return {
+    ci,
+    decoration,
+    interactive,
+    isTTY,
+    json,
+    noColor,
+    theme,
+    usePrompts,
+    useSpinners,
+  };
+}
+
+async function loadClack(injected) {
+  if (injected) return injected;
+  return import('@clack/prompts');
+}
+
+function createUx(options = {}) {
+  const env = options.env || process.env;
+  const io = {
+    input: options.input || process.stdin,
+    output: options.output || process.stdout,
+    error: options.error || process.stderr,
+  };
+  const mode = resolveUxMode(options, env, io);
+  const write = options.write || ((text) => io.output.write(text));
+
+  function line(text = '') {
+    write(`${text}\n`);
+  }
+
+  function heading(text) {
+    if (mode.json) return;
+    if (!mode.decoration) {
+      line(text);
+      return;
+    }
+    const prefix = mode.theme.symbols.start;
+    line(mode.theme.status('planner', `${prefix} ${text}`));
+  }
+
+  function writeStatus(status, text) {
+    if (mode.json) return;
+    if (!mode.decoration) {
+      line(text);
+      return;
+    }
+    const symbol = mode.theme.symbols[status] || mode.theme.symbols.bullet;
+    const body = mode.theme.status(status, `${symbol} ${text}`);
+    line(body);
+  }
+
+  async function withSpinner(message, task, spinnerOptions = {}) {
+    if (!mode.useSpinners) {
+      if (!mode.json && spinnerOptions.echo !== false) {
+        if (mode.decoration) {
+          writeStatus('info', message);
+        } else {
+          line(message);
+        }
+      }
+      return task();
+    }
+
+    const clack = await loadClack(options.prompts);
+    const spinner = clack.spinner();
+    spinner.start(message);
+    try {
+      const result = await task();
+      spinner.stop(spinnerOptions.successMessage || message);
+      return result;
+    } catch (error) {
+      spinner.stop(spinnerOptions.failureMessage || `Failed: ${message}`, 1);
+      throw error;
+    }
+  }
+
+  async function promptConfirm(message, promptOptions = {}) {
+    if (!mode.usePrompts) {
+      throw new Error('create-quiver: interactive confirmation requires an interactive TTY. Pass the equivalent flags or rerun with --interactive.');
+    }
+    if (options.promptConfirm) {
+      return options.promptConfirm(message, promptOptions);
+    }
+    const clack = await loadClack(options.prompts);
+    const result = await clack.confirm({
+      message,
+      initialValue: promptOptions.initialValue === true,
+    });
+    if (clack.isCancel && clack.isCancel(result)) {
+      throw new Error('create-quiver: interactive confirmation canceled.');
+    }
+    return result === true;
+  }
+
+  return {
+    heading,
+    line,
+    mode,
+    promptConfirm,
+    theme: mode.theme,
+    withSpinner,
+    writeStatus,
+  };
+}
+
+module.exports = {
+  createUx,
+  resolveUxMode,
+};