chati-dev 3.2.4 → 3.3.0

package/src/utils/schema-validator.js

@@ -0,0 +1,226 @@
+/**
+ * @fileoverview Lightweight schema validation for runtime data.
+ *
+ * Validates session.yaml, build-state.json, config.yaml, and handoff
+ * blocks against defined schemas. No external dependencies.
+ *
+ * Constitution Article XIV — Framework Registry Governance.
+ */
+
+// ---------------------------------------------------------------------------
+// Validation Engine
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} SchemaProperty
+ * @property {string} type - Expected type (string|number|boolean|array|object)
+ * @property {boolean} [required] - Whether field is required
+ * @property {*} [default] - Default value if missing
+ * @property {*[]} [enum] - Allowed values
+ * @property {number} [min] - Minimum value (for numbers)
+ * @property {number} [max] - Maximum value (for numbers)
+ * @property {number} [minLength] - Minimum length (for strings/arrays)
+ * @property {number} [maxLength] - Maximum length (for strings/arrays)
+ */
+
+/**
+ * @typedef {object} Schema
+ * @property {string[]} [required] - Required field names
+ * @property {Record<string, SchemaProperty>} properties - Property definitions
+ */
+
+/**
+ * @typedef {object} ValidationResult
+ * @property {boolean} valid - Whether data passes validation
+ * @property {string[]} errors - List of validation errors
+ * @property {string[]} warnings - List of validation warnings
+ */
+
+/**
+ * Validate data against a schema.
+ *
+ * @param {object} data - Data to validate
+ * @param {Schema} schema - Schema definition
+ * @returns {ValidationResult}
+ */
+export function validateSchema(data, schema) {
+  const errors = [];
+  const warnings = [];
+
+  if (!data || typeof data !== 'object') {
+    errors.push('Data must be a non-null object');
+    return { valid: false, errors, warnings };
+  }
+
+  if (!schema || !schema.properties) {
+    return { valid: true, errors, warnings };
+  }
+
+  // Check required fields
+  const requiredFields = schema.required || [];
+  for (const field of requiredFields) {
+    if (data[field] === undefined || data[field] === null) {
+      errors.push(`Missing required field: ${field}`);
+    }
+  }
+
+  // Validate each defined property
+  for (const [key, prop] of Object.entries(schema.properties)) {
+    const value = data[key];
+
+    // Skip undefined/null non-required fields
+    if (value === undefined || (value === null && !requiredFields.includes(key))) {
+      continue;
+    }
+
+    // Type check
+    if (prop.type) {
+      const actual = getType(value);
+      if (actual !== prop.type) {
+        errors.push(`Field "${key}": expected ${prop.type}, got ${actual}`);
+        continue;
+      }
+    }
+
+    // Enum check
+    if (prop.enum && !prop.enum.includes(value)) {
+      errors.push(`Field "${key}": value "${value}" not in allowed values [${prop.enum.join(', ')}]`);
+    }
+
+    // Number range
+    if (prop.type === 'number') {
+      if (prop.min !== undefined && value < prop.min) {
+        errors.push(`Field "${key}": value ${value} below minimum ${prop.min}`);
+      }
+      if (prop.max !== undefined && value > prop.max) {
+        errors.push(`Field "${key}": value ${value} above maximum ${prop.max}`);
+      }
+    }
+
+    // String/Array length
+    if (prop.type === 'string' || prop.type === 'array') {
+      const len = value.length;
+      if (prop.minLength !== undefined && len < prop.minLength) {
+        warnings.push(`Field "${key}": length ${len} below recommended minimum ${prop.minLength}`);
+      }
+      if (prop.maxLength !== undefined && len > prop.maxLength) {
+        warnings.push(`Field "${key}": length ${len} above recommended maximum ${prop.maxLength}`);
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Validate data and apply default values for missing fields.
+ *
+ * @param {object} data - Data to validate (will NOT be mutated)
+ * @param {Schema} schema - Schema definition
+ * @returns {{ valid: boolean, data: object, errors: string[], warnings: string[] }}
+ */
+export function validateAndCoerce(data, schema) {
+  const result = validateSchema(data, schema);
+
+  // Create a copy with defaults applied
+  const coerced = { ...data };
+
+  if (schema.properties) {
+    for (const [key, prop] of Object.entries(schema.properties)) {
+      if (coerced[key] === undefined && prop.default !== undefined) {
+        coerced[key] = prop.default;
+      }
+    }
+  }
+
+  return {
+    valid: result.valid,
+    data: coerced,
+    errors: result.errors,
+    warnings: result.warnings,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the type of a value (matching schema type names).
+ *
+ * @param {*} value
+ * @returns {string}
+ */
+function getType(value) {
+  if (Array.isArray(value)) return 'array';
+  if (value === null) return 'null';
+  return typeof value;
+}
+
+// ---------------------------------------------------------------------------
+// Built-in Schemas
+// ---------------------------------------------------------------------------
+
+/**
+ * Session schema (session.yaml).
+ */
+export const SESSION_SCHEMA = {
+  required: ['project', 'language'],
+  properties: {
+    project: { type: 'string', required: true, minLength: 1 },
+    language: { type: 'string', required: true, default: 'en' },
+    pipeline_phase: { type: 'string', enum: ['discover', 'plan', 'build', 'deploy', 'completed'] },
+    current_agent: { type: 'string' },
+    governance_mode: { type: 'string', enum: ['planning', 'build', 'deploy'] },
+    execution_profile: { type: 'string', enum: ['explore', 'guided', 'autonomous'] },
+    context_bracket: { type: 'string', enum: ['FRESH', 'MODERATE', 'DEPLETED', 'CRITICAL'] },
+  },
+};
+
+/**
+ * Build state schema (build-state.json).
+ */
+export const BUILD_STATE_SCHEMA = {
+  required: ['sessionId', 'status', 'checkpoints'],
+  properties: {
+    sessionId: { type: 'string', required: true },
+    status: { type: 'string', required: true, enum: ['idle', 'running', 'completed', 'failed', 'abandoned'] },
+    checkpoints: { type: 'array', required: true },
+    startedAt: { type: 'string' },
+    totalAttempts: { type: 'number', min: 0 },
+  },
+};
+
+/**
+ * Config schema (config.yaml).
+ */
+export const CONFIG_SCHEMA = {
+  required: ['version'],
+  properties: {
+    version: { type: 'string', required: true },
+    installed_at: { type: 'string' },
+    updated_at: { type: 'string' },
+    installer_version: { type: 'string' },
+    project_type: { type: 'string', enum: ['greenfield', 'brownfield'] },
+    language: { type: 'string', default: 'en' },
+    ides: { type: 'array' },
+    providers: { type: 'object' },
+    agent_overrides: { type: 'object' },
+  },
+};
+
+/**
+ * Handoff schema (parsed handoff block).
+ */
+export const HANDOFF_SCHEMA = {
+  required: ['status'],
+  properties: {
+    status: { type: 'string', required: true, enum: ['APPROVED', 'NEEDS_REVISION', 'BLOCKED', 'unknown'] },
+    score: { type: 'number', min: 0, max: 100 },
+    summary: { type: 'string', maxLength: 2000 },
+    outputs: { type: 'array' },
+    decisions: { type: 'object' },
+    blockers: { type: 'array' },
+    needs_input_question: { type: 'string' },
+  },
+};

package/src/wizard/i18n.js

@@ -26,6 +26,14 @@ const FALLBACK_EN = {
     llm_provider_codex: 'Codex (OpenAI) — Optimized for code generation',
     llm_provider_not_installed: '(CLI not detected)',
     llm_provider_label: 'AI Provider',
+    ide_selection_title: 'Select your IDEs / CLIs (multiple allowed):',
+    provider_selection_title: 'Which AI providers will you use?',
+    editor_selection_title: 'Which editor IDEs should get rules files? (optional)',
+    primary_provider_title: 'Which is your primary CLI provider?',
+    primary_provider_label: 'Primary Provider',
+    providers_label: 'Providers',
+    quick_start_switch_hint: 'Switch CLIs anytime — your session continues from where you left off',
+    created_overlays: 'Created provider overlay directories',
     will_install: 'Will install:',
     agents_count: '13 agent definitions (DISCOVER, PLAN, BUILD, DEPLOY phases)',
     workflows_count: '6 workflow blueprints',
@@ -58,6 +66,9 @@ const FALLBACK_EN = {
     quick_start_1: 'Open your IDE',
     quick_start_2: 'Type: /chati',
     quick_start_3: 'The orchestrator will guide you through the process',
+    telemetry_consent: 'Help improve Chati.dev by sharing anonymous usage data?',
+    telemetry_description: 'Anonymous metrics only (agents used, pipeline duration, gate scores). Zero code, files, or personal data. You can disable anytime with: npx chati-dev telemetry disable',
+    telemetry_privacy: 'Privacy: opt-in only, anonymous UUID, no PII collected.',
   },
   agents: {
     starting: 'Starting agent: {agent}',

package/src/wizard/index.js

@@ -3,23 +3,13 @@ import { readFileSync } from 'fs';
 import { join, dirname, basename } from 'path';
 import { fileURLToPath } from 'url';
 import { logBanner } from '../utils/logger.js';
-import { stepLanguage, stepProjectType, stepLlmProvider, stepConfirmation } from './questions.js';
+import { stepLanguage, stepProjectType, stepIDESelection, stepProviderSelection, stepEditorSelection, stepPrimaryProvider, stepConfirmation, stepTelemetryConsent } from './questions.js';
 import { createSpinner, showStep, showValidation, showQuickStart } from './feedback.js';
 import { installFramework } from '../installer/core.js';
 import { validateInstallation } from '../installer/validator.js';
 import { t } from './i18n.js';
 import { DEFAULT_MCPS } from '../config/mcp-configs.js';
-import { IDE_CONFIGS } from '../config/ide-configs.js';
-
-/**
- * Map LLM provider to its primary IDE.
- * Each provider maps to its own standalone IDE — no cross-contamination.
- */
-const PROVIDER_TO_IDE = {
-  claude: ['claude-code'],
-  gemini: ['gemini-cli'],
-  codex: ['codex-cli'],
-};
+import { IDE_CONFIGS, IDE_TO_PROVIDER } from '../config/ide-configs.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const VERSION = JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf-8')).version;
@@ -46,11 +36,25 @@ export async function runWizard(targetDir, options = {}) {
   // Step 2: Project Type
   const projectType = options.projectType || await stepProjectType(targetDir);
 
-  // Step 3: LLM Provider
-  const llmProvider = options.llmProvider || await stepLlmProvider();
+  // Step 3a: Provider Selection (which AI providers to use)
+  const selectedProviders = options.providers || await stepProviderSelection();
+
+  // Step 3b: Primary provider (only if multiple)
+  const primaryProvider = options.llmProvider || await stepPrimaryProvider(selectedProviders);
+
+  // Step 3c: Editor Selection (which editor IDEs get rules files)
+  const selectedEditors = options.editors || await stepEditorSelection();
+
+  // Combine providers + editors into selectedIDEs for backward compatibility
+  const providerToIDE = { claude: 'claude-code', gemini: 'gemini-cli', codex: 'codex-cli' };
+  const selectedIDEs = options.ides || [
+    ...selectedProviders.map(p => providerToIDE[p]).filter(Boolean),
+    ...selectedEditors,
+  ];
+
+  // CLI providers derived from selected providers
+  const cliProviders = selectedProviders;
 
-  // Map provider to its standalone IDE(s)
-  const selectedIDEs = options.ides || PROVIDER_TO_IDE[llmProvider] || ['claude-code'];
   const selectedMCPs = options.mcps || DEFAULT_MCPS;
 
   // Step 4: Confirmation
@@ -59,7 +63,8 @@ export async function runWizard(targetDir, options = {}) {
     projectName,
     projectType,
     language,
-    llmProvider,
+    llmProvider: primaryProvider,
+    allProviders: cliProviders,
     selectedIDEs,
     selectedMCPs,
     targetDir,
@@ -68,8 +73,12 @@ export async function runWizard(targetDir, options = {}) {
 
   await stepConfirmation(config);
 
+  // Step 5: Telemetry Consent (opt-in)
+  const telemetryEnabled = options.telemetry !== undefined ? options.telemetry : await stepTelemetryConsent();
+  config.telemetryEnabled = telemetryEnabled;
+
   // Step 5: Installation + Validation
-  const primaryIDE = selectedIDEs[selectedIDEs.length - 1];
+  const primaryIDE = selectedIDEs.find(ide => IDE_TO_PROVIDER[ide] === primaryProvider) || selectedIDEs[0];
   const primaryIDEName = IDE_CONFIGS[primaryIDE]?.name || primaryIDE;
 
   console.log();
@@ -97,9 +106,15 @@ export async function runWizard(targetDir, options = {}) {
     if (selectedIDEs.includes('claude-code')) {
       showStep(t('installer.created_claude_md'));
     }
+    if (cliProviders.length > 1) {
+      showStep(t('installer.created_overlays'));
+    }
     showStep(t('installer.created_memories'));
     showStep(t('installer.installed_intelligence'));
     showStep(`${t('installer.configured_mcps')} ${selectedMCPs.join(', ')}`);
+    if (telemetryEnabled) {
+      showStep('Telemetry: enabled (anonymous, opt-in)');
+    }
 
     // Validation
     console.log();
@@ -133,11 +148,18 @@ export async function runWizard(targetDir, options = {}) {
       'codex-cli': '$chati',
     };
     const invokeCmd = invokeCmdMap[primaryIDE] || '/chati';
-    showQuickStart(t('installer.quick_start_title'), [
+    const quickStartSteps = [
       `${t('installer.quick_start_1')} (${primaryIDEName})`,
       `Type: ${invokeCmd}`,
       t('installer.quick_start_3'),
-    ]);
+    ];
+
+    // Add switch hint if multiple CLI providers configured
+    if (cliProviders.length > 1) {
+      quickStartSteps.push(t('installer.quick_start_switch_hint'));
+    }
+
+    showQuickStart(t('installer.quick_start_title'), quickStartSteps);
 
     return { success: true, config, validation };
   } catch (err) {

package/src/wizard/questions.js

@@ -4,7 +4,7 @@ import { detectProjectType } from '../utils/detector.js';
 import { showSummary, showChecklist } from './feedback.js';
 import { brand, dim, success } from '../utils/colors.js';
 import { isProviderAvailable } from '../terminal/cli-registry.js';
-import { IDE_CONFIGS } from '../config/ide-configs.js';
+import { IDE_CONFIGS, IDE_TO_PROVIDER } from '../config/ide-configs.js';
 
 /**
  * Step 1: Language Selection (always in English)
@@ -60,73 +60,212 @@ export async function stepProjectType(targetDir) {
 }
 
 /**
- * Step 3: LLM Provider Selection
+ * Provider display names for confirmation and selection prompts.
  */
-export async function stepLlmProvider() {
-  const providers = [
-    { name: 'claude', label: t('installer.llm_provider_claude') },
-    { name: 'gemini', label: t('installer.llm_provider_gemini') },
-    { name: 'codex', label: t('installer.llm_provider_codex') },
-  ];
-
-  // Check availability of each provider
-  const availability = {};
-  for (const prov of providers) {
+const PROVIDER_DISPLAY_NAMES = {
+  claude: 'Claude (Anthropic)',
+  gemini: 'Gemini (Google)',
+  codex: 'Codex (OpenAI)',
+};
+
+/**
+ * Step 3a: Provider Selection (multi-select)
+ *
+ * Asks the user which AI providers they want to use (Claude, Gemini, Codex).
+ * Returns an array of provider names (e.g. ['claude', 'gemini']).
+ */
+export async function stepProviderSelection() {
+  const cliIDEs = Object.entries(IDE_CONFIGS).filter(([, c]) => c.group === 'cli');
+  const options = [];
+
+  for (const [key, config] of cliIDEs) {
+    const provider = IDE_TO_PROVIDER[key];
+    let installed = false;
     try {
-      availability[prov.name] = await isProviderAvailable(prov.name);
+      installed = provider ? await isProviderAvailable(provider) : false;
     } catch {
-      availability[prov.name] = prov.name === 'claude'; // claude always available
+      installed = key === 'claude-code';
     }
+    const suffix = !installed ? ` ${dim(t('installer.llm_provider_not_installed'))}` : '';
+    const providerName = PROVIDER_DISPLAY_NAMES[provider] || config.name;
+    options.push({
+      value: provider,
+      label: `${providerName}${config.recommended ? ' (Recommended)' : ''}${suffix}`,
+      hint: config.description,
+    });
   }
 
-  const options = providers.map(prov => {
-    const installed = availability[prov.name];
-    const suffix = installed ? '' : ` ${dim(t('installer.llm_provider_not_installed'))}`;
-    return {
-      value: prov.name,
-      label: `${prov.label}${suffix}`,
-    };
+  const selected = await p.multiselect({
+    message: t('installer.provider_selection_title'),
+    options,
+    required: true,
   });
 
-  const provider = await p.select({
-    message: t('installer.llm_provider_title'),
+  if (p.isCancel(selected)) {
+    p.cancel('Installation cancelled.');
+    process.exit(0);
+  }
+
+  return selected;
+}
+
+/**
+ * Step 3b: Editor Selection (multi-select, optional)
+ *
+ * Asks the user which editor IDEs should receive rules files.
+ * Returns an array of IDE keys (e.g. ['vscode', 'cursor']).
+ */
+export async function stepEditorSelection() {
+  const editorIDEs = Object.entries(IDE_CONFIGS).filter(([, c]) => c.group === 'editor');
+
+  if (editorIDEs.length === 0) return [];
+
+  const options = editorIDEs.map(([key, config]) => ({
+    value: key,
+    label: config.name,
+    hint: config.description,
+  }));
+
+  const selected = await p.multiselect({
+    message: t('installer.editor_selection_title'),
     options,
-    initialValue: 'claude',
+    required: false,
   });
 
-  if (p.isCancel(provider)) {
+  if (p.isCancel(selected)) {
     p.cancel('Installation cancelled.');
     process.exit(0);
   }
 
-  return provider;
+  return selected;
+}
+
+/**
+ * Step 3: IDE / CLI Selection (multi-select) — LEGACY
+ *
+ * Maintained for backward compatibility. Combines providers and editors in a single prompt.
+ * Users select which IDEs/CLIs they'll use; CLI providers are derived from selections.
+ */
+export async function stepIDESelection() {
+  // Check availability of CLI-based IDEs
+  const cliIDEs = Object.entries(IDE_CONFIGS).filter(([, c]) => c.group === 'cli').map(([k]) => k);
+  const availability = {};
+  for (const ide of cliIDEs) {
+    const provider = IDE_TO_PROVIDER[ide];
+    try {
+      availability[ide] = provider ? await isProviderAvailable(provider) : false;
+    } catch {
+      availability[ide] = ide === 'claude-code';
+    }
+  }
+
+  // Build options with visual group separators
+  const options = [];
+
+  // CLI providers first (spawn terminals, enable multi-provider continuity)
+  options.push({ value: '_cli_header', label: dim('── CLI Providers (spawn agent terminals) ──'), hint: '', disabled: true });
+  for (const [key, config] of Object.entries(IDE_CONFIGS)) {
+    if (config.group !== 'cli') continue;
+    const installed = availability[key];
+    const suffix = !installed ? ` ${dim(t('installer.llm_provider_not_installed'))}` : '';
+    options.push({
+      value: key,
+      label: `${config.name}${config.recommended ? ' (Recommended)' : ''}${suffix}`,
+      hint: config.description,
+    });
+  }
+
+  // Editor IDEs (rules files only, no terminal spawning)
+  options.push({ value: '_editor_header', label: dim('── Editor IDEs (rules integration) ──'), hint: '', disabled: true });
+  for (const [key, config] of Object.entries(IDE_CONFIGS)) {
+    if (config.group !== 'editor') continue;
+    options.push({
+      value: key,
+      label: config.name,
+      hint: config.description,
+    });
+  }
+
+  const selectedIDEs = await p.multiselect({
+    message: t('installer.ide_selection_title'),
+    options,
+    required: true,
+  });
+
+  if (p.isCancel(selectedIDEs)) {
+    p.cancel('Installation cancelled.');
+    process.exit(0);
+  }
+
+  // Filter out separator headers
+  return selectedIDEs.filter(id => !id.startsWith('_'));
+}
+
+/**
+ * Step 3b: Primary CLI Provider Selection
+ *
+ * Only shown when the user selected multiple CLI-based IDEs.
+ * Determines which provider's adapted files go in chati.dev/ (main).
+ */
+export async function stepPrimaryProvider(cliProviders) {
+  if (cliProviders.length <= 1) return cliProviders[0] || 'claude';
+
+  const primary = await p.select({
+    message: t('installer.primary_provider_title'),
+    options: cliProviders.map(prov => ({
+      value: prov,
+      label: PROVIDER_DISPLAY_NAMES[prov] || prov,
+    })),
+  });
+
+  if (p.isCancel(primary)) {
+    p.cancel('Installation cancelled.');
+    process.exit(0);
+  }
+
+  return primary;
 }
 
 /**
  * Step 4: Confirmation
  */
 export async function stepConfirmation(config) {
-  const { projectName, projectType, language, llmProvider, selectedMCPs, selectedIDEs } = config;
+  const { projectName, projectType, language, llmProvider, selectedMCPs, selectedIDEs, allProviders } = config;
 
   const langName = SUPPORTED_LANGUAGES.find(l => l.value === language)?.label || language;
-  const providerNames = { claude: 'Claude (Anthropic)', gemini: 'Gemini (Google)', codex: 'Codex (OpenAI)' };
-  const providerDisplay = providerNames[llmProvider] || llmProvider;
-  const ideNames = (selectedIDEs || ['claude-code'])
-    .map(id => IDE_CONFIGS[id]?.name || id)
-    .join(', ') + ' (auto-configured)';
+
+  // Show all providers with primary indicator
+  const providers = allProviders || [llmProvider || 'claude'];
+  const providersDisplay = providers.map(prov => {
+    const name = PROVIDER_DISPLAY_NAMES[prov] || prov;
+    return prov === llmProvider ? `${name} (Primary)` : name;
+  }).join(', ');
+
+  // Separate editors from CLI IDEs for display
+  const editorIDEs = (selectedIDEs || []).filter(id => IDE_CONFIGS[id]?.group === 'editor');
+  const editorNames = editorIDEs.length > 0
+    ? editorIDEs.map(id => IDE_CONFIGS[id]?.name || id).join(', ')
+    : 'None';
   const mcpNames = selectedMCPs.length > 0
     ? `${selectedMCPs.join(', ')} (auto-installed)`
     : 'None';
 
-  console.log();
-  console.log(brand(t('installer.confirmation_title') + ':'));
-  showSummary({
+  const summaryData = {
     [t('installer.project_label')]: `${projectName} (${projectType === 'greenfield' ? 'Greenfield' : 'Brownfield'})`,
     [t('installer.language_label')]: langName,
-    [t('installer.llm_provider_label')]: providerDisplay,
-    [t('installer.ides_label')]: ideNames,
-    [t('installer.mcps_label')]: mcpNames,
-  });
+    [t('installer.providers_label')]: providersDisplay,
+  };
+
+  // Only show editor IDEs line if any were selected
+  if (editorIDEs.length > 0) {
+    summaryData[t('installer.ides_label')] = editorNames;
+  }
+
+  summaryData[t('installer.mcps_label')] = mcpNames;
+
+  console.log();
+  console.log(brand(t('installer.confirmation_title') + ':'));
+  showSummary(summaryData);
 
   console.log();
   console.log(`  ${t('installer.will_install')}:`);
@@ -154,3 +293,25 @@ export async function stepConfirmation(config) {
 
   return true;
 }
+
+/**
+ * Step 5: Telemetry Consent (opt-in)
+ *
+ * Asks the user if they want to share anonymous usage metrics.
+ * Returns true (opt-in) or false (opt-out).
+ */
+export async function stepTelemetryConsent() {
+  p.note(
+    `${dim(t('installer.telemetry_description'))}\n\n${dim(t('installer.telemetry_privacy'))}`,
+    dim('Telemetry')
+  );
+
+  const consent = await p.confirm({
+    message: t('installer.telemetry_consent'),
+    initialValue: false,
+  });
+
+  if (p.isCancel(consent)) return false;
+
+  return consent;
+}