create-quiver 0.14.0 → 0.15.0

package/src/create-quiver/lib/ai/providers.js

@@ -11,6 +11,8 @@ const PROVIDERS = {
     id: 'codex',
     command: 'codex',
     args: ['exec'],
+    supportsModelSelection: true,
+    modelArgBuilder: (model) => ['--model', model],
     timeoutMs: 10 * 60 * 1000,
     installHint: 'Install the Codex CLI and make sure it is available on PATH.',
   },
@@ -18,6 +20,8 @@ const PROVIDERS = {
     id: 'claude',
     command: 'claude',
     args: ['-p'],
+    supportsModelSelection: true,
+    modelArgBuilder: (model) => ['--model', model],
     timeoutMs: 10 * 60 * 1000,
     installHint: 'Install the Claude CLI and make sure it is available on PATH.',
   },
@@ -25,6 +29,8 @@ const PROVIDERS = {
     id: 'gemini',
     command: 'gemini',
     args: ['--prompt', ''],
+    supportsModelSelection: true,
+    modelArgBuilder: (model) => ['--model', model],
     timeoutMs: 10 * 60 * 1000,
     installHint: 'Install the Gemini CLI and make sure it is available on PATH.',
   },
@@ -61,9 +67,68 @@ function getProviderDefinition(providerId) {
   return PROVIDERS[normalized];
 }
 
+function normalizeProviderModel(model) {
+  const value = String(model || '').trim();
+  return value || '';
+}
+
+function buildProviderModelArgs(providerId, model, options = {}) {
+  const provider = getProviderDefinition(providerId);
+  const normalizedModel = normalizeProviderModel(model);
+  const enforce = options.enforce === true;
+
+  if (!normalizedModel) {
+    return {
+      model: '',
+      supported: Boolean(provider.supportsModelSelection),
+      enforced: enforce,
+      args: [],
+      reason: 'no model selected',
+    };
+  }
+
+  if (provider.supportsModelSelection !== true || typeof provider.modelArgBuilder !== 'function') {
+    if (enforce) {
+      throw new ProviderRunnerError(
+        'UNSUPPORTED_PROVIDER_MODEL_SELECTION',
+        `Provider '${provider.id}' cannot receive model '${normalizedModel}' through its Quiver adapter. Remove the model selection or update the provider adapter before live execution.`,
+        {
+          provider: provider.id,
+          model: normalizedModel,
+          nextSteps: [
+            `Run without a model override for provider '${provider.id}'.`,
+            `Update the '${provider.id}' provider adapter with model argument support.`,
+            'Use --dry-run to inspect the invocation before live execution.',
+          ],
+        },
+      );
+    }
+
+    return {
+      model: normalizedModel,
+      supported: false,
+      enforced: false,
+      args: [],
+      reason: 'provider adapter does not support model arguments',
+    };
+  }
+
+  const args = provider.modelArgBuilder(normalizedModel);
+  return {
+    model: normalizedModel,
+    supported: true,
+    enforced: enforce,
+    args: Array.isArray(args) ? args.map((arg) => String(arg)) : [],
+    reason: 'model argument supported',
+  };
+}
+
 function buildProviderInvocation(providerId, options = {}) {
   const provider = getProviderDefinition(providerId);
   const extraArgs = Array.isArray(options.args) ? options.args.map((arg) => String(arg)) : [];
+  const modelSelection = buildProviderModelArgs(provider.id, options.model, {
+    enforce: options.enforceModelSelection === true,
+  });
   const prompt = String(options.prompt ?? '');
   const timeoutMs = Number.isFinite(options.timeoutMs) ? Number(options.timeoutMs) : provider.timeoutMs;
   const cwd = options.cwd ? String(options.cwd) : process.cwd();
@@ -72,10 +137,11 @@ function buildProviderInvocation(providerId, options = {}) {
   return {
     provider: provider.id,
     command: provider.command,
-    args: provider.args.concat(extraArgs),
+    args: provider.args.concat(modelSelection.args, extraArgs),
     cwd,
     timeoutMs,
     promptLength: Buffer.byteLength(prompt, 'utf8'),
+    modelSelection,
     promptTransport: {
       mode: transportMode,
       promptLength: Buffer.byteLength(prompt, 'utf8'),
@@ -93,6 +159,7 @@ function createDryRunResult(invocation) {
     args: invocation.args.slice(),
     cwd: invocation.cwd,
     timeoutMs: invocation.timeoutMs,
+    modelSelection: invocation.modelSelection,
     promptTransport: invocation.promptTransport,
     exitCode: 0,
     stdout: '',
@@ -256,6 +323,7 @@ async function runProvider(providerId, options = {}) {
       args: invocation.args.slice(),
       cwd: invocation.cwd,
       timeoutMs: invocation.timeoutMs,
+      modelSelection: invocation.modelSelection,
       promptTransport: invocation.promptTransport,
       exitCode: null,
       stdout: '',
@@ -292,6 +360,7 @@ async function runProvider(providerId, options = {}) {
       args: invocation.args.slice(),
       cwd: invocation.cwd,
       timeoutMs: invocation.timeoutMs,
+      modelSelection: invocation.modelSelection,
       promptTransport: describePromptTransport(transport),
       exitCode: execution.exitCode,
       signal: execution.signal,
@@ -309,6 +378,7 @@ module.exports = {
   SUPPORTED_PROVIDERS,
   ProviderRunnerError,
   assertSupportedProvider,
+  buildProviderModelArgs,
   buildProviderInvocation,
   formatProviderList,
   getProviderDefinition,

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

@@ -0,0 +1,118 @@
+const os = require('os');
+const { spawnSync } = require('child_process');
+
+function splitEditorCommand(value) {
+  const input = String(value || '').trim();
+  if (!input) return null;
+  const parts = [];
+  let current = '';
+  let quote = null;
+  let escaping = false;
+
+  for (const char of input) {
+    if (escaping) {
+      current += char;
+      escaping = false;
+      continue;
+    }
+    if (char === '\\') {
+      escaping = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) {
+        quote = null;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (/\s/.test(char)) {
+      if (current) {
+        parts.push(current);
+        current = '';
+      }
+      continue;
+    }
+    current += char;
+  }
+
+  if (current) parts.push(current);
+  return parts.length > 0 ? { command: parts[0], args: parts.slice(1) } : null;
+}
+
+function defaultEditorForPlatform(platform = os.platform()) {
+  return platform === 'win32' ? 'notepad' : 'vi';
+}
+
+function resolveEditor(env = process.env, options = {}) {
+  const candidates = [
+    { source: 'VISUAL', value: env.VISUAL },
+    { source: 'EDITOR', value: env.EDITOR },
+    ...((options.fallbacks || [defaultEditorForPlatform(options.platform)]).map((value) => ({
+      source: 'fallback',
+      value,
+    }))),
+  ];
+
+  for (const candidate of candidates) {
+    const parsed = splitEditorCommand(candidate.value);
+    if (parsed) {
+      return { ...parsed, source: candidate.source };
+    }
+  }
+
+  return null;
+}
+
+function openEditor(filePath, options = {}) {
+  const editor = options.editor || resolveEditor(options.env || process.env, options);
+  if (!editor) {
+    return {
+      ok: false,
+      canceled: true,
+      filePath,
+      reason: 'No editor configured. Set VISUAL or EDITOR, then rerun the command.',
+    };
+  }
+
+  const runner = options.spawnSync || spawnSync;
+  const result = runner(editor.command, [...editor.args, filePath], {
+    cwd: options.cwd || process.cwd(),
+    env: options.env || process.env,
+    shell: false,
+    stdio: options.stdio || 'inherit',
+  });
+
+  if (result.error) {
+    return {
+      ok: false,
+      canceled: true,
+      command: editor.command,
+      filePath,
+      reason: result.error.message,
+      source: editor.source,
+    };
+  }
+
+  const status = result.status ?? 0;
+  return {
+    ok: status === 0,
+    canceled: status !== 0,
+    command: editor.command,
+    exitCode: status,
+    filePath,
+    source: editor.source,
+  };
+}
+
+module.exports = {
+  defaultEditorForPlatform,
+  openEditor,
+  resolveEditor,
+  splitEditorCommand,
+};

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

@@ -0,0 +1,107 @@
+const { resolveUxMode } = require('./ux');
+
+function formatError(message) {
+  return `create-quiver: ${message}`;
+}
+
+function normalizeSelectorOptions(options = []) {
+  return options.map((option) => {
+    if (typeof option === 'string') {
+      return {
+        label: option,
+        value: option,
+        hint: '',
+        default: false,
+      };
+    }
+    return {
+      label: String(option.label || option.name || option.id || option.value || ''),
+      value: String(option.value || option.id || option.path || option.label || ''),
+      hint: option.hint || option.description || '',
+      default: option.default === true || option.recommended === true,
+      raw: option.raw || option,
+    };
+  }).filter((option) => option.label && option.value);
+}
+
+function findOption(options, value) {
+  const normalized = String(value || '').trim();
+  if (!normalized) return null;
+  return options.find((option) => option.value === normalized || option.label === normalized) || null;
+}
+
+function resolveDefaultOption(options, defaultValue) {
+  return findOption(options, defaultValue) || options.find((option) => option.default) || (options.length === 1 ? options[0] : null);
+}
+
+async function loadClack(injected) {
+  if (injected) return injected;
+  return import('@clack/prompts');
+}
+
+async function selectOption(message, rawOptions, options = {}) {
+  const normalizedOptions = normalizeSelectorOptions(rawOptions);
+  if (normalizedOptions.length === 0) {
+    throw new Error(formatError(`${options.name || 'selection'} has no available options.`));
+  }
+
+  const explicit = findOption(normalizedOptions, options.value);
+  if (explicit) return explicit;
+  if (options.value) {
+    throw new Error(formatError(`${options.name || 'selection'} option '${options.value}' was not found.`));
+  }
+
+  const mode = resolveUxMode({
+    interactive: options.interactive === true,
+    json: options.json,
+    noColor: options.noColor,
+    stdinIsTTY: options.stdinIsTTY,
+    stdoutIsTTY: options.stdoutIsTTY,
+    stderrIsTTY: options.stderrIsTTY,
+  }, options.env || process.env, {
+    input: options.input || process.stdin,
+    output: options.output || process.stdout,
+    error: options.error || process.stderr,
+  });
+
+  if (mode.usePrompts) {
+    if (typeof options.promptSelect === 'function') {
+      const selected = await options.promptSelect(message, normalizedOptions);
+      const match = findOption(normalizedOptions, selected);
+      if (!match) {
+        throw new Error(formatError(`${options.name || 'selection'} prompt returned unknown option '${selected}'.`));
+      }
+      return match;
+    }
+    const clack = await loadClack(options.prompts);
+    const selected = await clack.select({
+      message,
+      options: normalizedOptions.map((option) => ({
+        label: option.label,
+        value: option.value,
+        hint: option.hint || undefined,
+      })),
+      initialValue: resolveDefaultOption(normalizedOptions, options.defaultValue)?.value,
+    });
+    if (clack.isCancel && clack.isCancel(selected)) {
+      throw new Error(formatError(`${options.name || 'selection'} was canceled.`));
+    }
+    return findOption(normalizedOptions, selected);
+  }
+
+  const fallback = resolveDefaultOption(normalizedOptions, options.defaultValue);
+  if (fallback) return fallback;
+
+  const flag = options.flag || '--value';
+  const available = normalizedOptions.map((option) => option.value).join(', ');
+  throw new Error(formatError([
+    `${options.name || 'selection'} requires an explicit choice.`,
+    `Available options: ${available}.`,
+    `Use ${flag} <value> or rerun with --interactive.`,
+  ].join('\n')));
+}
+
+module.exports = {
+  normalizeSelectorOptions,
+  selectOption,
+};

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

@@ -0,0 +1,103 @@
+const QUIVER_COLORS = Object.freeze({
+  sky: '#86C8F2',
+  blue: '#6BADEB',
+  periwinkle: '#7F9EE8',
+  violet: '#9B82E6',
+  magenta: '#D56AB0',
+});
+
+const STATUS_COLORS = Object.freeze({
+  info: 'sky',
+  command: 'blue',
+  success: 'blue',
+  planner: 'violet',
+  review: 'magenta',
+  warning: 'magenta',
+  error: '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: '◇', section: '◆', success: '✓', warning: '!', error: '✖', bullet: '•' }
+    : { start: '*', section: '*', 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,169 @@
+const UX_FLAG_OPTIONS = Object.freeze({
+  withPlanner: '--with-planner',
+  interactive: '--interactive',
+  review: '--review',
+});
+
+const UX_FLAG_MATRIX = Object.freeze({
+  init: Object.freeze({
+    withPlanner: false,
+    interactive: true,
+    review: false,
+    note: 'guided project onboarding choices',
+  }),
+  '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',
+  }),
+  'ai execute-slice': Object.freeze({
+    withPlanner: false,
+    interactive: true,
+    review: false,
+    note: 'executor profile and ready-slice selection',
+  }),
+  'ai execute-plan': Object.freeze({
+    withPlanner: false,
+    interactive: true,
+    review: false,
+    note: 'execution strategy confirmation and future selectors',
+  }),
+});
+
+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,
+};