create-quiver 0.15.0 → 0.15.1

package/src/create-quiver/lib/ai/model-catalog.js

@@ -0,0 +1,333 @@
+const { assertSupportedProvider } = require('./providers');
+
+const MODEL_CATALOG_VERSION = 1;
+const MODEL_CATALOG_LAST_UPDATED = '2026-05-27';
+
+const MODEL_CATALOG = Object.freeze({
+  catalogVersion: MODEL_CATALOG_VERSION,
+  lastUpdated: MODEL_CATALOG_LAST_UPDATED,
+  providers: Object.freeze({
+    codex: Object.freeze({
+      id: 'codex',
+      displayName: 'Codex',
+      models: Object.freeze([
+        knownModel('gpt-5.5', 'GPT 5.5', {
+          aliases: ['GPT 5.5', 'gpt 5.5', 'Gpt-5.5'],
+          recommendedFor: ['planner', 'reviewer'],
+          costTier: 'high',
+          qualityTier: 'premium',
+          stability: 'stable',
+          notes: 'Recommended for planning, specs, architecture, and high-risk reviews.',
+        }),
+        knownModel('gpt-5.4', 'GPT 5.4', {
+          aliases: ['GPT 5.4', 'gpt 5.4'],
+          recommendedFor: ['planner', 'reviewer'],
+          costTier: 'medium',
+          qualityTier: 'high',
+          stability: 'stable',
+          notes: 'Balanced planner or reviewer model.',
+        }),
+        knownModel('gpt-5.4-mini', 'GPT 5.4 mini', {
+          aliases: ['GPT 5.4 mini', 'gpt 5.4 mini', 'gpt-5.4 mini'],
+          recommendedFor: ['executor', 'doctor'],
+          costTier: 'low',
+          qualityTier: 'standard',
+          stability: 'stable',
+          notes: 'Recommended for lower-cost execution, diagnostics, and sub-agent work.',
+        }),
+        knownModel('gpt-5.3-codex', 'GPT 5.3 Codex', {
+          aliases: ['GPT 5.3 Codex', 'gpt 5.3 codex'],
+          recommendedFor: ['executor'],
+          costTier: 'medium',
+          qualityTier: 'high',
+          stability: 'stable',
+          notes: 'Recommended for more complex coding slices.',
+        }),
+        knownModel('gpt-5.3-codex-spark', 'GPT 5.3 Codex Spark', {
+          aliases: ['GPT 5.3 Codex Spark', 'gpt 5.3 codex spark'],
+          recommendedFor: ['executor'],
+          costTier: 'medium',
+          qualityTier: 'high',
+          stability: 'preview',
+          notes: 'Preview or limited model for quick code iteration.',
+        }),
+      ]),
+    }),
+    claude: Object.freeze({
+      id: 'claude',
+      displayName: 'Claude',
+      models: Object.freeze([
+        knownModel('opus', 'Claude Opus', {
+          aliases: ['Claude Opus', 'opus'],
+          recommendedFor: ['planner', 'reviewer'],
+          costTier: 'high',
+          qualityTier: 'premium',
+          stability: 'stable',
+          notes: 'Recommended for complex planning and architectural decisions.',
+        }),
+        knownModel('sonnet', 'Claude Sonnet', {
+          aliases: ['Claude Sonnet', 'sonnet'],
+          recommendedFor: ['executor', 'reviewer'],
+          costTier: 'medium',
+          qualityTier: 'high',
+          stability: 'stable',
+          notes: 'Balanced execution and review model.',
+        }),
+        knownModel('haiku', 'Claude Haiku', {
+          aliases: ['Claude Haiku', 'haiku'],
+          recommendedFor: ['doctor'],
+          costTier: 'low',
+          qualityTier: 'standard',
+          stability: 'stable',
+          notes: 'Recommended for diagnostics and simple tasks.',
+        }),
+        knownModel('claude-opus-4-7', 'Claude Opus 4.7', {
+          aliases: ['OPUS 4.7', 'Claude Opus 4.7', 'opus 4.7'],
+          recommendedFor: ['planner', 'reviewer'],
+          costTier: 'high',
+          qualityTier: 'premium',
+          stability: 'known',
+          notes: 'Version-pinned known catalog choice for planning.',
+        }),
+        knownModel('claude-sonnet-4-6', 'Claude Sonnet 4.6', {
+          aliases: ['Claude Sonnet 4.6', 'sonnet 4.6'],
+          recommendedFor: ['executor', 'reviewer'],
+          costTier: 'medium',
+          qualityTier: 'high',
+          stability: 'known',
+          notes: 'Version-pinned known catalog choice for execution and review.',
+        }),
+        knownModel('claude-haiku-4-5', 'Claude Haiku 4.5', {
+          aliases: ['Claude Haiku 4.5', 'haiku 4.5'],
+          recommendedFor: ['doctor'],
+          costTier: 'low',
+          qualityTier: 'standard',
+          stability: 'known',
+          notes: 'Version-pinned known catalog choice for low-cost diagnostics.',
+        }),
+      ]),
+    }),
+    gemini: Object.freeze({
+      id: 'gemini',
+      displayName: 'Gemini',
+      models: Object.freeze([
+        knownModel('gemini-3.1-pro-preview', 'Gemini 3.1 Pro Preview', {
+          aliases: ['Gemini 3.1 Pro Preview', 'gemini 3.1 pro preview'],
+          recommendedFor: ['planner', 'reviewer'],
+          costTier: 'high',
+          qualityTier: 'premium',
+          stability: 'preview',
+          notes: 'Known catalog choice for complex planning and review.',
+        }),
+        knownModel('gemini-3.5-flash', 'Gemini 3.5 Flash', {
+          aliases: ['Gemini 3.5 Flash', 'gemini 3.5 flash'],
+          recommendedFor: ['executor'],
+          costTier: 'medium',
+          qualityTier: 'high',
+          stability: 'stable',
+          notes: 'Known catalog choice for balanced execution.',
+        }),
+        knownModel('gemini-3.1-flash-lite', 'Gemini 3.1 Flash-Lite', {
+          aliases: ['Gemini 3.1 Flash Lite', 'Gemini 3.1 Flash-Lite', 'gemini 3.1 flash lite'],
+          recommendedFor: ['doctor'],
+          costTier: 'low',
+          qualityTier: 'standard',
+          stability: 'stable',
+          notes: 'Known catalog choice for low-cost diagnostics and mechanical tasks.',
+        }),
+        knownModel('gemini-3.1-pro-preview-customtools', 'Gemini 3.1 Pro Custom Tools', {
+          aliases: ['Gemini 3.1 Pro Custom Tools', 'gemini 3.1 pro preview custom tools'],
+          recommendedFor: ['planner', 'reviewer'],
+          costTier: 'high',
+          qualityTier: 'premium',
+          stability: 'preview',
+          notes: 'Known catalog choice for advanced tool-oriented workflows.',
+        }),
+      ]),
+    }),
+  }),
+});
+
+function knownModel(id, displayName, options = {}) {
+  return Object.freeze({
+    id,
+    displayName,
+    aliases: Object.freeze(Array.from(new Set([id, displayName].concat(options.aliases || [])))),
+    recommendedFor: Object.freeze((options.recommendedFor || []).slice()),
+    costTier: options.costTier || 'unknown',
+    qualityTier: options.qualityTier || 'unknown',
+    stability: options.stability || 'known',
+    notes: options.notes || '',
+    modelSource: 'catalog',
+  });
+}
+
+function customModel(providerId, modelId = '') {
+  const id = String(modelId || '').trim();
+  return {
+    id: id || 'custom',
+    displayName: id || 'Custom',
+    aliases: id ? [id] : ['custom'],
+    recommendedFor: [],
+    costTier: 'unknown',
+    qualityTier: 'unknown',
+    stability: 'custom',
+    notes: 'Custom model id. Quiver cannot guarantee account availability without a live validation.',
+    modelSource: 'custom',
+    custom: true,
+    provider: providerId ? assertSupportedProvider(providerId) : '',
+  };
+}
+
+function getModelCatalog() {
+  return MODEL_CATALOG;
+}
+
+function listCatalogProviders() {
+  return Object.values(MODEL_CATALOG.providers).map((provider) => ({
+    id: provider.id,
+    displayName: provider.displayName,
+    modelCount: provider.models.length,
+  }));
+}
+
+function getProviderModelCatalog(providerId) {
+  const provider = assertSupportedProvider(providerId);
+  return MODEL_CATALOG.providers[provider];
+}
+
+function getKnownModelsForProvider(providerId, options = {}) {
+  const provider = getProviderModelCatalog(providerId);
+  const role = String(options.role || '').trim().toLowerCase();
+  const includeCustom = options.includeCustom !== false;
+  const models = provider.models.slice();
+  const sorted = role
+    ? models.sort((left, right) => roleScore(right, role) - roleScore(left, role))
+    : models;
+
+  if (!includeCustom) {
+    return sorted;
+  }
+
+  return sorted.concat(customModel(provider.id));
+}
+
+function roleScore(model, role) {
+  const roles = Array.isArray(model.recommendedFor) ? model.recommendedFor : [];
+  const index = roles.indexOf(role);
+  if (index === -1) return 0;
+  return 100 - index;
+}
+
+function normalizeModelAliasKey(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '');
+}
+
+function resolveModelFromEntries(providerId, modelValue, entries) {
+  const provider = assertSupportedProvider(providerId);
+  const input = String(modelValue || '').trim();
+  const inputKey = normalizeModelAliasKey(input);
+  if (!inputKey) {
+    return {
+      provider,
+      input,
+      matched: false,
+      ambiguous: false,
+      model: null,
+      matches: [],
+      reason: 'empty model',
+    };
+  }
+
+  const matches = [];
+  for (const model of entries || []) {
+    const aliases = Array.isArray(model.aliases) ? model.aliases : [model.id, model.displayName];
+    if (aliases.some((alias) => normalizeModelAliasKey(alias) === inputKey)) {
+      matches.push(model);
+    }
+  }
+
+  if (matches.length === 1) {
+    const model = matches[0];
+    return {
+      provider,
+      input,
+      matched: true,
+      ambiguous: false,
+      model,
+      matches,
+      technicalModel: model.id,
+      displayName: model.displayName,
+      modelSource: model.modelSource || 'catalog',
+      reason: 'known model alias matched',
+    };
+  }
+
+  if (matches.length > 1) {
+    return {
+      provider,
+      input,
+      matched: false,
+      ambiguous: true,
+      model: null,
+      matches,
+      reason: 'ambiguous model alias',
+    };
+  }
+
+  return {
+    provider,
+    input,
+    matched: false,
+    ambiguous: false,
+    model: customModel(provider, input),
+    matches: [],
+    technicalModel: input,
+    displayName: input,
+    modelSource: 'custom',
+    reason: 'custom model',
+  };
+}
+
+function resolveKnownModel(providerId, modelValue) {
+  const provider = getProviderModelCatalog(providerId);
+  return resolveModelFromEntries(provider.id, modelValue, provider.models);
+}
+
+function normalizeModelSelection(providerId, modelValue, options = {}) {
+  const resolution = resolveKnownModel(providerId, modelValue);
+  const fallbackDisplayName = String(options.displayName || '').trim();
+
+  if (resolution.ambiguous) {
+    return {
+      ...resolution,
+      model: String(modelValue || '').trim(),
+      displayName: fallbackDisplayName || String(modelValue || '').trim(),
+      validationStatus: options.validationStatus || 'not-tested',
+    };
+  }
+
+  return {
+    ...resolution,
+    model: resolution.technicalModel || String(modelValue || '').trim(),
+    displayName: fallbackDisplayName || resolution.displayName || String(modelValue || '').trim(),
+    validationStatus: options.validationStatus || 'not-tested',
+  };
+}
+
+module.exports = {
+  MODEL_CATALOG_LAST_UPDATED,
+  MODEL_CATALOG_VERSION,
+  customModel,
+  getKnownModelsForProvider,
+  getModelCatalog,
+  getProviderModelCatalog,
+  listCatalogProviders,
+  normalizeModelAliasKey,
+  normalizeModelSelection,
+  resolveKnownModel,
+  resolveModelFromEntries,
+};

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

@@ -72,9 +72,54 @@ function normalizeProviderModel(model) {
   return value || '';
 }
 
+function resolveProviderModelSelection(providerId, model, options = {}) {
+  const rawModel = normalizeProviderModel(model);
+  if (!rawModel) {
+    return {
+      input: '',
+      model: '',
+      displayName: '',
+      modelSource: '',
+      aliasNormalized: false,
+    };
+  }
+
+  const { normalizeModelSelection } = require('./model-catalog');
+  const selection = normalizeModelSelection(providerId, rawModel, {
+    displayName: options.displayName,
+  });
+  const aliasNormalized = selection.modelSource === 'catalog' && selection.model !== rawModel;
+  if (aliasNormalized && options.blockModelAlias === true) {
+    throw new ProviderRunnerError(
+      'DISPLAY_MODEL_ALIAS',
+      `Model '${rawModel}' is a display alias for provider '${providerId}', not the technical id. Use '${selection.model}' or run 'npx create-quiver ai agent repair --dry-run'.`,
+      {
+        provider: providerId,
+        inputModel: rawModel,
+        suggestedModel: selection.model,
+        displayName: selection.displayName,
+        nextSteps: [
+          `Use --model ${selection.model}.`,
+          'Run npx create-quiver ai agent repair --dry-run to preview profile normalization.',
+          'Run npx create-quiver ai agent doctor to inspect profile issues.',
+        ],
+      },
+    );
+  }
+
+  return {
+    input: rawModel,
+    model: selection.model,
+    displayName: selection.displayName,
+    modelSource: selection.modelSource,
+    aliasNormalized,
+  };
+}
+
 function buildProviderModelArgs(providerId, model, options = {}) {
   const provider = getProviderDefinition(providerId);
-  const normalizedModel = normalizeProviderModel(model);
+  const modelResolution = resolveProviderModelSelection(provider.id, model, options);
+  const normalizedModel = modelResolution.model;
   const enforce = options.enforce === true;
 
   if (!normalizedModel) {
@@ -114,13 +159,19 @@ function buildProviderModelArgs(providerId, model, options = {}) {
   }
 
   const args = provider.modelArgBuilder(normalizedModel);
-  return {
+  const result = {
     model: normalizedModel,
     supported: true,
     enforced: enforce,
     args: Array.isArray(args) ? args.map((arg) => String(arg)) : [],
-    reason: 'model argument supported',
+    reason: modelResolution.aliasNormalized ? `model alias normalized from ${modelResolution.input}` : 'model argument supported',
   };
+  if (modelResolution.aliasNormalized) {
+    result.input = modelResolution.input;
+    result.displayName = modelResolution.displayName;
+    result.modelSource = modelResolution.modelSource;
+  }
+  return result;
 }
 
 function buildProviderInvocation(providerId, options = {}) {
@@ -128,6 +179,8 @@ function buildProviderInvocation(providerId, options = {}) {
   const extraArgs = Array.isArray(options.args) ? options.args.map((arg) => String(arg)) : [];
   const modelSelection = buildProviderModelArgs(provider.id, options.model, {
     enforce: options.enforceModelSelection === true,
+    blockModelAlias: options.blockModelAlias === true,
+    displayName: options.displayName,
   });
   const prompt = String(options.prompt ?? '');
   const timeoutMs = Number.isFinite(options.timeoutMs) ? Number(options.timeoutMs) : provider.timeoutMs;
@@ -184,6 +237,85 @@ function serializeError(error, provider, invocation) {
   };
 }
 
+function compactProviderText(value) {
+  return redactSecrets(String(value || ''))
+    .replace(/\bsk-[A-Za-z0-9_-]{16,}\b/g, '[REDACTED]')
+    .replace(/\bghp_[A-Za-z0-9_]{16,}\b/g, '[REDACTED]')
+    .replace(/\bgithub_pat_[A-Za-z0-9_]{16,}\b/g, '[REDACTED]')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .slice(0, 6)
+    .join(' ');
+}
+
+function extractProviderErrorCause(result = {}) {
+  const error = result.error || {};
+  const text = compactProviderText([
+    error.message,
+    result.stderr,
+    result.stdout,
+  ].filter(Boolean).join('\n'));
+  const lower = text.toLowerCase();
+
+  if (error.code === 'MISSING_PROVIDER_CLI') {
+    return {
+      code: 'MISSING_PROVIDER_CLI',
+      message: error.message || `Provider CLI '${result.command || result.provider}' is not available.`,
+    };
+  }
+
+  if (error.code === 'PROVIDER_TIMEOUT') {
+    return {
+      code: 'PROVIDER_TIMEOUT',
+      message: error.message || `Provider '${result.provider}' timed out.`,
+    };
+  }
+
+  const quotedUnsupportedModel = text.match(/the ['"`]([^'"`]+)['"`] model is not supported/i);
+  const genericInvalidModel = /invalid model|unknown model|model .*not supported|model .*not available|model .*does not exist|unsupported model/i.test(text);
+  if (quotedUnsupportedModel || genericInvalidModel) {
+    const model = quotedUnsupportedModel ? quotedUnsupportedModel[1] : result.modelSelection?.model;
+    return {
+      code: 'INVALID_PROVIDER_MODEL',
+      message: model
+        ? `Provider '${result.provider}' rejected model '${model}'. ${text}`
+        : `Provider '${result.provider}' rejected the selected model. ${text}`,
+    };
+  }
+
+  if (/unauthorized|forbidden|permission denied|not authenticated|authentication|api key|login required|log in/i.test(text)) {
+    return {
+      code: 'PROVIDER_AUTH_ERROR',
+      message: `Provider '${result.provider}' authentication failed. ${text}`,
+    };
+  }
+
+  if (text) {
+    return {
+      code: 'PROVIDER_RUN_FAILED',
+      message: text,
+    };
+  }
+
+  return {
+    code: 'PROVIDER_RUN_FAILED',
+    message: 'provider run failed',
+  };
+}
+
+function createProviderFailureError(result = {}) {
+  const cause = extractProviderErrorCause(result);
+  return new ProviderRunnerError(cause.code, cause.message, {
+    provider: result.provider,
+    command: result.command,
+    args: Array.isArray(result.args) ? result.args.slice() : [],
+    exitCode: result.exitCode,
+    signal: result.signal,
+    modelSelection: result.modelSelection,
+  });
+}
+
 function runSpawn(command, args, options = {}) {
   const spawnImpl = options.spawn || spawn;
 
@@ -352,7 +484,7 @@ async function runProvider(providerId, options = {}) {
       timeoutMs: invocation.timeoutMs,
     });
 
-    return {
+    const providerResult = {
       ok: execution.ok,
       dryRun: false,
       provider: invocation.provider,
@@ -369,6 +501,10 @@ async function runProvider(providerId, options = {}) {
       error: execution.error,
       preflight: preflightResult,
     };
+    if (!providerResult.ok && !providerResult.error) {
+      providerResult.error = serializeError(createProviderFailureError(providerResult), invocation.provider, invocation);
+    }
+    return providerResult;
   } finally {
     finalizePromptTransport(transport);
   }
@@ -380,7 +516,10 @@ module.exports = {
   assertSupportedProvider,
   buildProviderModelArgs,
   buildProviderInvocation,
+  createProviderFailureError,
+  extractProviderErrorCause,
   formatProviderList,
   getProviderDefinition,
+  resolveProviderModelSelection,
   runProvider,
 };

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

@@ -101,7 +101,60 @@ async function selectOption(message, rawOptions, options = {}) {
   ].join('\n')));
 }
 
+async function promptText(message, options = {}) {
+  const explicit = String(options.value || '').trim();
+  if (explicit) return explicit;
+
+  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.promptText === 'function') {
+      const value = await options.promptText(message, options);
+      const normalized = String(value || '').trim();
+      if (!normalized && options.required !== false) {
+        throw new Error(formatError(`${options.name || 'input'} is required.`));
+      }
+      return normalized;
+    }
+    const clack = await loadClack(options.prompts);
+    const value = await clack.text({
+      message,
+      placeholder: options.placeholder,
+      initialValue: options.initialValue,
+      validate: options.required === false
+        ? undefined
+        : (input) => (String(input || '').trim() ? undefined : 'Required'),
+    });
+    if (clack.isCancel && clack.isCancel(value)) {
+      throw new Error(formatError(`${options.name || 'input'} was canceled.`));
+    }
+    return String(value || '').trim();
+  }
+
+  if (options.defaultValue !== undefined && options.defaultValue !== null) {
+    return String(options.defaultValue).trim();
+  }
+
+  const flag = options.flag || '--value';
+  throw new Error(formatError([
+    `${options.name || 'input'} requires an explicit value.`,
+    `Use ${flag} <value> or rerun with --interactive.`,
+  ].join('\n')));
+}
+
 module.exports = {
   normalizeSelectorOptions,
+  promptText,
   selectOption,
 };